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).

Above WINDOW_CAP_LINES a chunked build is additionally windowed around the viewport rather than covering the file, and that window is sized in buffer lines the viewport reaches, not in rows:

span   = fold_aware_visible_end(scroll, viewport_height) − scroll   // ≥ viewport_height
window = [scroll − span, scroll + span + span)                      // chunk-aligned, clamped

The two quantities coincide for every buffer with nothing collapsed, which is why the distinction is easy to lose — and losing it is a visible bug, not a perf one. A closed fold makes one row stand for a whole subtree, so a viewport of 60 rows over a collapsed org file reaches ~2500 lines in. Sizing the window in rows covered the first 128 lines, left every row below the first fold with no chunk, and the renderers took their plain-text fallback: the top few headings coloured and the rest of the screen did not.

Two consequences worth stating rather than discovering:

• The coverage gate and the window must derive the bound identically. The worker cache-hits on matrix.covers(scroll, visible_end). A gate asking for more than the build produces never hits, so the worker rebuilds on every tick forever. Both call folds::fold_aware_visible_end, and so does the syntax layer's parse window (Editor::fold_aware_highlight_end_line) — one walk, three consumers, no drift.
• Overscan scales with the span, not the row count. One row of scroll can advance scroll past a whole fold body, so a row-sized overscan would be crossed immediately and rebuild every scroll tick.

The cost this initially admitted: the highlight query ran over the lines the folds hide. Rows are not built for them (folded interiors are skipped), so row count and memory stayed O(viewport) — only the query scaled. Measured at 52 ms on a collapsed 5000-line file against 1.6 ms fold-free.

FW.2 removed that, by querying per visible run rather than per window:

runs   = maximal ranges of [win_lo, win_hi) not hidden inside a closed fold
spans  = concat(highlight_lines(run) for run in runs)   // stitched dense, indexed from win_lo

highlight_lines costs what its range costs whether or not those lines are ever drawn, so the window query was paying for spans nothing would read. Three properties make this the right shape rather than a micro-optimisation:

• The run count is bounded by the viewport, not the span. Every boundary between two runs is a closed fold, and every closed fold in the window spends one of the viewport's rows on its head — so there are at most viewport_height + 1 runs however many lines the folds hide. Without that bound this would be trading one large cost for an unbounded number of small ones.
• The fold-free path is untouched. Nothing collapsed ⇒ exactly one run covering the window ⇒ short-circuit to the single pre-FW.2 call. No stitching, no dense allocation, and the bench measures it (1.54 ms, unchanged) rather than the comment asserting it.
• The result stays a dense vector indexed from win_lo, so spans_base lookups, ChunkInputs and build_display_rows did not move. A hidden line keeps an empty span list — what it would have got anyway, and what nothing reads.

52.3 ms → 2.33 ms at a ~2400-line collapsed span; see benchmarks.md for the table. A collapsed file now paints with correct colour for ~0.4 ms more worker time than the broken version spent painting it wrong.

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.

The syntax axis is stamped from render_version, and this is load-bearing

One edit publishes twice from the syntax worker (SyntaxHandle, slice C.2):

1. an intermediate — every node's byte range shifted to track the edit, source and text_version updated, tree shape still pre-parse. Published immediately so unchanged content keeps painting at correct positions;
2. the completed reparse a moment later.

Both carry the same text_version. So an invalidation axis stamped from snapshot().text_version() cannot tell "shifted, not yet coloured" from "parsed, colours ready". It moved on the intermediate — rebuilding uncoloured, which is correct and deliberate on the edit path (sync_rebuild_pane_on_edit builds with allow_highlight: false so the glyph lands in the keystroke's own frame) — and then stood still for the parse that actually had the colour. The buffer held default colours until something dropped the matrix outright (<C-l>), which is how it was reported, twice.

The axis is therefore stamped from SyntaxSnapshot::render_version — text_version + parsed_text_version — which changes on both publishes. Neither half alone works: text_version misses the completed parse (the bug above), and parsed_text_version misses the intermediate, whose whole purpose is the byte-aligned repaint.

parsed_text_version and its predicate tree_reflects() already existed for exactly this distinction, and their doc already recorded two earlier callers that asked text_version / reparsed_from_version instead (= silently reindenting nothing; predictive indent falling to the lexical bridge). The cells axis was the third. When the question is "has the tree changed", never ask text_version.

The renderer-side half: don't paint a matrix built under different inputs

The table above is what makes the worker rebuild. A renderer must also refuse to paint a matrix whose stamp disagrees with the live inputs, because the rebuild is async and a request already in flight when the config changed lands after it, storing pre-change cells into the pane's (stable-identity) matrix cell.

Two axes are guarded at paint time, in both peers — TUI display_stale in render.rs, GPUI's .filter(...) on cell_matrix / display_matrix in window.rs:

• text — the matrix lags the snapshot. Fall back to plain snapshot text: current content uncoloured beats pre-edit content coloured.
• whitespace — the matrix was emitted under a different display.whitespace.* config. Markers live in Cell.ch, and the TUI's compose-loop decoration pre-pass deliberately skips cell-derived bodies (re-decorating desyncs source bytes once tabs expand), so painting such a matrix means :set list shows nothing and :set nolist keeps showing glyphs. Falling back lets the TUI's pre-pass decorate the raw text on the very same frame; GPUI drops to shape_row until the worker republishes.

Compare against CellsRenderState::whitespace_version_for_pane(pane_id) (the stamp a matrix built now would carry), never against a locally recomputed hash — one producer, one comparison. The remaining axes (syntax, inlay, folds, theme) deliberately do not gate paint: they change often and their staleness is a colour/layout lag the overlay and next publish absorb, so gating on them would reintroduce whole-viewport flicker.

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.