Cell-grid renderer architecture

Anchor: design.md §5.6 (rendering layered architecture) and paramount goal #1 (sub-frame keystroke→glyph at 120 Hz, within the one-frame ceiling ≤ 8.3 ms).

This document specifies the renderer substrate that replaces the per-frame WindowTextSystem::shape_line path for code/terminal/file-tree/synthetic buffers. The Shaped path (markdown previews, help with rich text, future prose mode) is preserved as a sibling and is out of scope for this work.

The design satisfies four constraints simultaneously:

1. Cursor motion and overlay updates paint at memcpy + atlas-lookup speed regardless of buffer size, scroll velocity, or background async work.
2. Edits, syntax recomputes, LSP arrivals, fold changes never block the UI/edit thread. All matrix-affecting work runs on a background tokio worker.
3. TUI and GPU surfaces consume the same substrate. The cell matrix is the contract; only the output target differs.
4. Decoration freshness is bounded to "next paint" for overlay-class state and to "next paint after worker publishes" for cell-baked state. No state is ever rendered before it is consistent with the cursor's published row.

Why the current shape-line path can't meet goal #1

WindowTextSystem::shape_line runs HarfBuzz-class shaping (font matching → glyph mapping → kerning → positioning) per call. Held-j probe (commit 734486d, 2026-05-25) measured:

The per-call cost is real layout work, not redundant calls. A renderer-side content cache (Layer A, retired) reduced call count to 2 per paint but each remaining call cost the same 10 ms, conserving total wall time. The cost is structural to shape_line; the only path to ≤ 1 ms paint is to bypass shape_line entirely for code-class content.

Cell-grid + glyph atlas is the path. Every high-performance terminal (alacritty, wezterm, kitty) and most GPU editors (VSCode, Sublime via DirectWrite cache, browsers) use the same decomposition. For monospace, single-font, ASCII-heavy source code, full text shaping is wasted work; an atlas + per-cell quad emission hits sub-microsecond per cell.

Architecture

Three concerns, decomposed cleanly

The renderer never builds cells, never shapes lines, never walks ropes. It loads three Arcs, iterates the visible slice, and emits quads.

Data model

The substrate types live in a new lattice-cells crate. Pure data; no I/O, no rendering, no rope dependencies. Both renderer crates and lattice-host depend on it.

/// 16 bytes. Cache-line friendly; ~4 cells per cache line.
#[repr(C)]
pub struct Cell {
    pub codepoint: u32,   // unicode scalar; 0 = blank
    pub fg: u32,          // 0xRRGGBB; theme-resolved
    pub bg: u32,          // 0xRRGGBB or 0 = transparent
    pub flags: u16,       // bit 0: inlay; bit 1: ws marker; rest reserved
    _padding: u16,
}

pub struct CellRow {
    pub cells: Arc<[Cell]>,             // body cells, inlay-spliced
    pub source_line: u32,               // logical line (pre-fold) in the buffer
    pub inlay_offsets: Arc<[(u32, u32)]>, // (orig_byte, char_width) for byte↔col remap
}

pub struct CellChunk {
    pub start_source_line: u32,         // logical line where this chunk starts
    pub rows: Arc<[CellRow]>,           // ordered by source_line; folded rows elided
    pub version: MatrixVersion,         // captured at build time
}

pub struct CellMatrix {
    pub chunks: Arc<[Arc<CellChunk>]>,  // ordered by start_source_line
    pub chunk_size: u32,                // logical lines per chunk; 0 = whole-doc mode
    pub source_line_count: u32,         // total logical lines (pre-fold)
    pub visible_line_count: u32,        // total matrix rows (post-fold)
    pub version: MatrixVersion,         // max version across chunks
}

#[derive(Clone, Copy, Default, PartialEq, Eq, Hash)]
pub struct MatrixVersion {
    pub text: u32,
    pub syntax: u32,
    pub inlay_hints: u32,
    pub folds: u32,
    pub theme: u32,
}

Diagnostics, doc-highlights, search-matches, hlsearch, cursor, selection, visual range — none affect cell content. They are overlay state, not in MatrixVersion.

Overlay state

Per RenderState, alongside the existing per-subsystem render states:

pub struct OverlayState {
    pub gutter: Arc<[GutterRow]>,           // per visible row: line_num, fold_marker, severity
    pub cursor: CursorState,                // line, column, shape (block/bar/underline)
    pub selection: Option<RangeOverlay>,    // selection / visual range
    pub current_match: Option<RangeOverlay>,
    pub all_matches: Arc<[RangeOverlay]>,   // hlsearch
    pub doc_highlights: Arc<[RangeOverlay]>,
    pub diagnostics: Arc<[DiagnosticRange]>, // underline ranges
    pub substitute_preview: Arc<[RangeOverlay]>,
}

Each field is published via the existing RenderState machinery (ArcSwap snapshot). The paint loop loads the whole OverlayState once per frame.

Decoration assignment

The principle: any decoration that doesn't change glyph layout is an overlay. Async-arriving decorations that pass that test appear on the next paint with zero matrix work.

Cell-builder worker

A tokio task in lattice-host, sibling to highlights_worker. Subscribes to MatrixVersion field changes via the existing RenderState cascade. On a version bump:

1. Compute the smallest rebuild set: chunks whose covered start_source_line .. start_source_line + chunk_size intersects the changed range.
2. For edits, downstream chunks (lines past the edit) have their start_source_line shifted by Δ; their rows are unchanged. No rebuild for those chunks.
3. Build affected chunks: read rope, walk syntax spans, weave inlay hints, apply fold map, emit CellRow array.
4. Coalesce: if more version bumps arrive during the build, drop intermediate results and rebuild against the latest state.
5. Atomically swap the published Arc<CellMatrix>.

Cost target: a chunk rebuild (≈ 128 lines × 10 µs/row) ≈ 1.3 ms. Worker stays ≤ 10% busy at sustained 30 Hz typing.

Chunking policy

Self-tuning to viewport:

• Whole-doc mode when source_line_count ≤ 4 × viewport_height. Single chunk == whole doc. No chunking overhead.
• Chunked mode otherwise. chunk_size = 2 × viewport_height, rounded to a power of two for cache-friendly layout.
• A typical 70-line viewport produces 128-line chunks. A 100 K-line buffer = ~780 chunks at ~2 KB metadata each = ~1.5 MB chunk-table overhead.
• LRU cap at 8 × viewport_height / chunk_size chunks resident if memory pressure shows up (deferred; mostly N/A at expected scale).

Paint loop (UI thread)

1. Load matrix     = rs.cells.matrix.load_full()       // ArcSwap, wait-free
2. Load overlays   = rs.cells.overlays.load_full()     // ArcSwap, wait-free
3. slice = matrix.slice(scroll, viewport_height)       // O(log chunks) binary search
4. for row in slice {
       for cell in row.cells:
           glyph = atlas.lookup_or_raster(cell.codepoint, font_id, size)
           emit_quad(x, y, glyph.uv, cell.fg, cell.bg)
           x += glyph.advance
   }
5. for row in slice { emit gutter quads via atlas }
6. emit cursor quad, selection quads, hlsearch quads, doc_highlight quads, diagnostic underline quads
7. GPU submit

No conditional branches on buffer state, no version checks, no shape calls. Every paint is the same shape. Bounded by viewport × max-cells-per-row × constant.

Invalidation, by source

The cell-builder worker computes "smallest rebuild set" by intersecting the changed range against chunk ranges. For pure typing (single-line edits), this is one chunk worth of rebuild per keystroke.

Trade-offs

Accepted:

• One-frame cursor-cell lag after a typed character. The cursor renders at its new column immediately (overlay); the cell under the cursor reflects pre-edit content for at most one frame, then updates. Invisible during normal typing; only observable in constructed stress tests.
• No shape_line for code-class content. Loses ligatures (most code fonts ship with them off by default; we mirror that), complex-script support in source code (rare; available via Shaped buffer mode), and subpixel positioning (we choose pixel-aligned for monospace).
• Glyph atlas as renderer-side infrastructure. Texture upload, eviction, and per-font-size buckets. Manageable scope; alacritty/wezterm have proven the model.
• Selection / hlsearch / visual range as overlay quads, not cell-bg mutations. Keeps the cell matrix cursor-invariant. Costs one extra quad emission per cell in the selection range; trivial.

Rejected:

• Lazy decoration rendering (paint cells now, decorations later). Coherence problem: user could act on stale visual state. Replaced by overlay composition, which has the same async benefit without the coherence cost.
• Synchronous chunk rebuild on edit. Would block the edit handler by 1–10 ms per keystroke. Replaced by fully async path; accept the one-frame cell lag.
• Sub-chunk row Arc structure (Arc<[Arc<CellRow>]>) for row-granular sync patching. Adds metadata overhead without a load-bearing reason given the async path is fast enough.
• "Render when cursor idle" debouncing. Cursor-coupled overlays must paint every frame anyway; the half-and-half rule would create two render paths.
• Drop GPUI for direct wgpu. Re-implements windowing/input/focus/animations; net cost ≫ net gain.

Promise

Cursor motion in any buffer is bounded by O(viewport_size) atlas lookups plus a constant overlay pass. Edit-induced downstream effects (re-syntax of distant lines, re-numbering line 9999) catch up within a few frames asynchronously; they never block input. Decoration updates (LSP highlights, diagnostics, doc highlights, search matches) appear on the next paint at zero matrix cost.

Sub-millisecond paint, regardless of viewport size or scroll velocity. Held-key bursts at any OS-produced input rate. TUI and GUI behave identically from the buffer's perspective.

Slicing

Estimated calendar: 6–9 weeks across all slices.

S2.3 is the natural sync point: after it lands, the matrix is feature-complete content-wise and S3 (TUI cutover) can proceed in parallel with S2.4–S2.5 (perf optimisations).

Open questions

1. chunk_size exact value. 2 × viewport_height is the design; bench (S5) picks the rounded power-of-two anchor.
2. Whole-doc-mode threshold. 4 × viewport_height is a guess; bench validates.
3. Atlas page size and count. Probably 2048 × 2048 pages × 4–8 resident, but depends on per-platform texture limits. S4 work.
4. Atlas eviction policy. LRU per-glyph or per-(font, size) bucket. S4 work.
5. Selection bg as one-quad-per-selected-cell vs one-quad-per-contiguous-run. Run optimisation deferred until profile shows it matters.
6. Word wrap interaction. Each logical line could produce multiple matrix rows; the source_line field generalises to (source_line, wrap_segment). Add when word wrap lands in the editor, not before.
7. Inlay hint rebuild granularity. Today: any inlay change rebuilds the affected chunk. Could be tightened to per-row if profiling shows the chunk rebuild is the bottleneck on heavy LSP workloads.

Conventions for updating this doc

• Update the slice table as each lands; move completed slices' "What lands" detail into prose.
• When the bench (S5) lands, fold numbers from benchmarks.md into the "Promise" section.
• Append rejected alternatives to "Trade-offs" as they come up; future readers benefit from the audit trail.
• Cross-reference paramount goals explicitly when motivating changes.