Gjallar/docs/architecture.md

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

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

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.