This repository has been archived on 2026-10-29. You can view files and clone it, but you cannot make any changes to its state, such as pushing and creating new issues, pull requests or comments.
Gjallar/docs/architecture.md
2026-06-15 01:10:20 +01:00

107 lines
4.2 KiB
Markdown

# Gjallar Architecture
## Objective
Gjallar owns framebuffer-native, multi-scale TUI composition: turning many
surface inputs into one dense, inspectable operator display where different
regions may use different text resolutions.
## Authority Map
- Owner: Gjallar owns display composition, pane partitioning, per-pane virtual
text grids, font-scale selection, framebuffer lowering, and future sparse
refresh output. Gjallar also owns local cursor state, title-bar hit testing,
and minimized/restored panel state.
- Inputs: provider catalogs, provider-owned surface trees, display dimensions,
font assets, runtime flags, mouse input, Odin's canonical slash-delimited
marquee tape, and eventually direct CultMesh subscriptions.
- Outputs: `gjallar.overview` composition state, visible framebuffer frames,
cursor presentation, top-tab minimized panel presentation, and renderer
telemetry.
- Derived state: pane weights, pixel rectangles, chosen font sizes, one-row
gutter blocks, an ECS-style structure-of-arrays gutter ribbon, ordered
marquee queue objects, ribbon occupancy, dirty rectangles, glyph runs,
title-bar hit regions, top-tab restore affordances, local
minimized-panel keys, and compact agent-readable projections.
- Forbidden writers: discovery systems do not decide Gjallar layout; providers
do not tune themselves for Nightwing; framebuffer backends do not invent
provider truth; Gjallar does not derive marquee content from provider status
summaries; Odin and providers do not own Nightwing-local minimized state.
- Shared paths: full-frame rendering, sparse refresh, future browser previews,
and agent text capture should lower the same overview model.
- Deletion line: any code that both discovers provider truth and decides final
screen composition belongs on one side or the other. Gjallar shows; discovery
systems see.
## Current Pipeline
```text
Odin provider catalog
-> display provider selection
-> provider surface fetch
-> canonical marquee tape passthrough
-> synthetic gjallar.overview surface
-> EveNode panel extraction
-> weighted AABB packing
-> local minimized-state application
-> minimized top-tab strip reservation
-> title-bar hit-region emission
-> one-row gutter cell plan as an addressable SoA ribbon
-> slash-delimited marquee queue object lowering into ribbon occupancy
-> per-panel text pressure estimate
-> PSF font selection
-> frame draw commands
-> BGRA framebuffer present
```
## Target Pipeline
```text
SurfaceSource[]
-> GjallarOverview
-> PaneTree
-> PaneGrid[]
-> RenderPlan
-> backend
```
Backends:
- `FramebufferBackend`: full BGRA frame writes, current implementation.
- `SparseCellBackend`: dirty cell/glyph/rect pipe for high-frequency remote or
terminal targets.
- `AgentTextBackend`: token-efficient navigation and panel capture for agents.
## First Product Claim
Gjallar is not a terminal multiplexer and not a dashboard theme. It is a
multi-resolution text compositor. The important gap is that each pane can become
its own virtual terminal scale while still belonging to one coherent display.
## Raster Font Authority
Gjallar owns TUI pixel typography for its framebuffer body. Eve GUI lowerers use
outline display/body families such as Montserrat, Zen Kaku Gothic New, M PLUS 1,
and Ubuntu Sans; those are not substitutes for Gjallar's raster cell fonts.
For any scale Gjallar claims as Japanese-capable, the font must provide Latin,
hiragana, and katakana in the same fixed cell grid. The target ladder is:
- display: 16x16;
- body: 14x14;
- small: 12x12.
`PsfFont` reads Unicode-mapped PSF fonts and `FontAtlas` selects from the
packaged Shinonome bitmap family. Default startup now treats that family as a
hard contract: if any required raster is missing, mis-sized, or missing kana,
Gjallar fails loudly instead of falling back to random system console fonts.
The repo-native verification path is:
- `tools/verify_bitmap_family.ps1`
That verifier builds Gjallar, runs specimen mode against a temp framebuffer, and
proves the shipped 12/14/16 family loads with zero missing glyphs for a mixed
Latin/hiragana/katakana specimen string including `メタめ`. The verifier uses
`--specimen-text-file` so UTF-8 specimen content does not depend on shell
argument encoding quirks.