pmacs/docs/pmacs-gpu-quad-backgrounds-framing.md

pmacs-gpu — quad-background framing

Status: CLOSED 2026-05-29. Sessions 9.1 (Selection), 9.2 (CurrentLine), 9.3 (peer-presence sourcing) all merged; finding A8 retired. Scoring + the QB1–QB3 follow-on findings are in pmacs-gpu-quad-backgrounds-audit.md. Search backgrounds (Q#4) remain deferred to a later arc. The sections below are the original framing pass, preserved.

This is the per-milestone framing artifact for the quad-pipeline work that closes Phase A's one deferred structural finding. It inherits the framing discipline of pmacs-gpu-design.md and records load-bearing commitments before any session-9 code lands. Audit material at Phase-A-finalization close goes to docs/pmacs-gpu-quad-backgrounds-audit.md (future).

Why this exists

Phase A's audit (pmacs-gpu-phase-a-audit.md) scored A8 as a single structural finding deferred from Phase A by design: foreground-only glyph attributes (cosmic-text 0.18's Attrs) cannot render the background visual that Selection, SearchMatch, SearchMatchActive, and CurrentLine need. The wire and consumer-cache infrastructure for these decoration kinds already exists; the render pass does not.

The framing claim, load-bearing for the rest of this doc: the expensive part of this milestone is gone before it starts. Session 7 shipped a wgpu quad pipeline for the minimap; this milestone reuses that pipeline for a second purpose. There is no new shader to author, no new vertex-buffer abstraction to design, no new blend-mode story. The work decomposes into vertex generation + render-order discipline + one missing producer call (CurrentLine). That smallness is what qualifies this as Phase A finalization rather than a Phase B prerequisite.

Contract inheritance

From pmacs-gpu-design.md: the instance never learns a pixel. This milestone strengthens that invariant rather than testing it. The producer emits Decoration { range: ByteRange, kind: DecorationKind }; the consumer translates byte ranges into pixel rectangles entirely from local glyph layout. The pixel-pure-instance invariant is not at risk in any session-9 work; if it appears to be, classify as a structural finding and pause.

Scope inheritance from Phase A

What already flows on the wire and in pmacs-gpu state:

Field	Status at Phase A close
DecorationKind::Selection producer emission	Shipped (src/semantic_render.rs:383, from win.region()).
DecorationKind::DiagnosticError/Warning/Info/Hint producer emission	Shipped; renders as foreground override (not in scope here).
current_decorations: Vec<Decoration> consumer state	Shipped; populated by the M11.4 dirty-merge path.
wgpu quad pipeline	Shipped; minimap rendering uses it.
Glyph layout access (Buffer::layout_runs())	Available; cosmic-text 0.18 stable API.
decoration_kind_to_color foreground helper	Shipped; returns None for background kinds (correct per its contract).

What is NOT closed by Phase A:

Gap	Resolution path
DecorationKind::Selection rendering	Session 9.1. Data flows; render pass is missing.
DecorationKind::CurrentLine producer emission	Session 9.2. Derivable from vp.cursor; trivial producer change.
DecorationKind::CurrentLine rendering	Session 9.2. Same render path as 9.1.
DecorationKind::SearchMatch{,Active} producer emission	Deferred. Requires a search feature in pmacs core (Lua command + core state + producer wiring). Belongs to a later arc; not this milestone.
DecorationKind::SearchMatch{,Active} rendering	Deferred with the producer.

Toolkit (recurrence)

Component	Status
wgpu quad pipeline	Reuse Session 7's QuadRenderer (pmacs-gpu/src/main.rs:375-428). Same shader, same vertex layout, same alpha-blending state.
cosmic-text glyph layout	Buffer::layout_runs() yields per-visual-line layout; each LayoutRun exposes glyphs: &[LayoutGlyph] with start_byte, end_byte, x, w.
pmacs-protocol	No wire changes. DecorationKind already enumerates all four background kinds. Decoration already carries range: ByteRange.

No new dependencies. No new wire-format decisions.

Predicted findings — categorical bets

Three named bets, each probing a categorically different failure surface. Committed before session-9 code lands so the post-milestone scoring is honest:

#	Bet	Category
1	Multi-line vertex generation produces wrong number of quads on selections that cross visual-line boundaries (soft-wrapped lines, lines wider than viewport).	Geometric-decomposition probe
2	Overlap composition between Selection and a future CurrentLine (or between Selection and a diagnostic-foreground decoration) needs an explicit precedence rule the producer arc didn't commit to.	Convention-vs-contract probe
3	CurrentLine emitted from the active window's cursor re-emits a full Decorations family every cursor-byte tick; the consumer churns its quad buffer on horizontal cursor motion that doesn't change the rendered line.	Producer-cadence-vs-consumer-cost probe

Unpredicted categories may surface. The audit doc records them at classification-time per rule (iii).

Scoring methodology (committed before data lands)

Same shape as Phase A: category matrix, not a count. At session-9 arc close, report:

• Predicted categories that surfaced (true positives).
• Predicted categories that didn't surface (false positives).
• Unpredicted categories that surfaced (false negatives).
• Count distribution within each category.

Recorded before the work to prevent the M10.10 Day-5 reconciliation trap.

Forced decisions

These are decisions session 9.x will need to make. The framing pass commits each so sessions don't rediscover them mid-implementation. Each follows pmacs-gpu-design.md's Q-numbering convention.

Q#1 — CurrentLine source location: stance (α)

Stance (α): the producer emits DecorationKind::CurrentLine derived from the active window's cursor. Concretely, scoped_decorations reads core.active_window_for(self.frontend_id).cursor — the same per-frontend access path it already uses for Selection at src/semantic_render.rs:378 — and converts that byte position into a line range via line_starts (the line-offset table already built in the diagnostic branch of the same function). The consumer treats CurrentLine like any other decoration; no consumer-side cursor → line-range derivation.

Reasoning: centralizing the line-derivation in the producer means the TUI's future CurrentLine highlight (if it ships) reuses the same derivation. The TUI today does not paint a current-line background; when it does, deriving it consumer-side in two places would be a duplication M10's discipline rejects. Producer-side derivation also gives the producer a place to throttle (Q#3 below).

Stance (α) commits the producer to emit CurrentLine even when no consumer renders it. The wire cost is one extra Decoration per Decorations frame, ~16 bytes. Negligible.

Q#2 — render order: stance (α)

Stance (α): single render pass, two pass.draw() calls. Quad backgrounds first, text second. The minimap continues to render last (at the right margin, after text, in the same pass).

Reasoning: a single render pass per frame is the standard wgpu shape and matches the existing structure. Adding a second pre-text pass introduces a second begin_render_pass per frame with no correctness benefit — the same pipeline can be issued twice in one pass with different vertex-buffer ranges or different set_vertex_buffer calls. The minimap's existing draw-after-text behavior is preserved.

If session 9.1 surfaces a transparency-correctness issue (decoration backgrounds blending against the clear color instead of against text), that's a structural finding — classify and consider stance (β) (separate pre-text pass with LoadOp::Load for the text pass).

Q#3 — CurrentLine producer cadence: stance (β)

Stance (β): the producer emits CurrentLine once per visible-line change, not once per cursor tick. Horizontal cursor motion within the same source line is a no-op; only motion that crosses a \n triggers a fresh Decorations family.

Implementation: the producer's per-frontend SemanticRenderState tracks last_cursor_line: Option<u64>; on each render_frame it reads the active window's cursor, computes the line via the line_starts table, and compares against the cached value. Same line → suppress the CurrentLine portion of the Decorations emission (but Selection/diagnostic portions still emit normally). Different line → emit a full Decorations frame.

Reasoning: cursor moves 60–120 Hz under arrow-key autorepeat; rebuilding the consumer's quad-vertex buffer that often is wasted work the bet #3 predicts. Throttling at the producer is cheaper than at every consumer. Same-line motion still updates CursorByte; only the CurrentLine decoration is suppressed.

If session 9.2 surfaces a freshness gap (e.g. Decorations family arrives with stale Selection after a CurrentLine emission), that's a structural finding — likely indicates the per-line throttle needs to emit a no-op Decorations { full: true, segments: [] } to clear other decoration kinds.

Q#4 — search backgrounds: deferred

Search (Find / FindReplace) is a load-bearing pmacs feature with no current implementation in pmacs core. The producer cannot emit SearchMatch until search state exists; the consumer cannot test SearchMatch rendering without the producer emitting it.

Defer to the editing-parity arc (pmacs-gpu-design.md's Phase B). Phase A finalization closes with SearchMatch{,Active} rendering documented-but-not-implemented; the rule-(iii) classification is "small finding deferred awaiting upstream feature."

Q#5 — read-only mirror cursor source: stance (peer-presence)

Surfaced during 9.2 manual validation (structural finding QB1). Sessions 9.1 and 9.2 emit Selection / CurrentLine from the viewing frontend's own window (scoped_decorations reads active_window_for(self.frontend_id)). pmacs-gpu is a read-only viewer with no input path: it never sends Key/cursor events, so its own window's cursor stays pinned at 0 and its selection stays None. The two per-window decoration kinds are therefore inert in pmacs-gpu — CurrentLine paints a static line-0 wash and Selection never appears. Every other rendered family (StyleSpans, diagnostics, inlay hints, minimap) is keyed to the buffer (shared), which is why only these two are affected.

Stance: peer presence is the authoritative cursor/selection source for a read-only mirror. What the user watches in pmacs-gpu is the editing frontend's (their TUI's) cursor and selection. That is PresenceUpdate — already on the wire (InstanceMessage::PresenceUpdate { frontend_id, buffer_id, cursor, selection }), already broadcast by the daemon to every multi_frontend recipient, and pmacs-gpu already negotiates multi_frontend: true. It simply drops the message at its _ => None catch-all today.

The fix is consumer-only — no producer or protocol change:

• pmacs-gpu consumes PresenceUpdate, storing per-peer (buffer_id, cursor, selection).
• The quad-background path renders Selection / CurrentLine washes from peer presence (the editing peer's cursor line + selection) rather than from the inert own-window current_decorations of those two kinds. Diagnostic (foreground) decorations are buffer-keyed and unaffected.
• The producer keeps emitting own-window Selection / CurrentLine (9.1/9.2) unchanged — correct and forward-looking for when pmacs-gpu gains its own input in Phase B; simply unconsumed-for-backgrounds by the mirror today.

Deliberately deferred within this stance:

• Per-peer stable colors (the audit's PresenceUpdate color-stability item). The single-peer mirror reuses the Selection / CurrentLine colors so the visual reads as "my editing, mirrored." Multiple distinct peers each getting a stable color is a later refinement.
• Peer caret glyph + label ("user N editing here"). This session renders the line/selection backgrounds only; the caret bar and name label are future presence work.
• Own-cursor vs peer-cursor merge. Once pmacs-gpu has input, its own CurrentLine (now meaningful) and peer presences coexist with distinct colors. Out of scope until input lands.

This is session 9.3.

Finding feedback loop

Rule (iii) from pmacs-gpu-design.md carries forward unchanged:

• Small finding (≤ half-day patch, no structural change, no contract violation): absorb into the current session. Patch, verify, continue.
• Structural finding (changes a contract, ripples across producers or consumers, invalidates a v1.0 assumption, or breaks the pixel-pure-instance invariant): pause; classify; defer to its own scoped milestone or session.

Classification happens at surface-time. The session 9.x audit doc records classification and resolution.

Rhythm

The session-anchored cadence from pmacs-gpu-design.md applies. Two sessions are framed for this arc:

• Session 9.1 — Selection quad backgrounds. Vertex generation from current_decorations filtered to background kinds; render-order change per Q#2; decoration_kind_to_bg_color helper; visual probe (TUI selection → pmacs-gpu rectangle). Exercises bet #1 directly; exercises bet #2 only insofar as Selection may overlap diagnostic foregrounds.
• Session 9.2 — CurrentLine producer + consumer. Producer emission per Q#1 + Q#3; consumer renders via session-9.1's path. Exercises bets #2 (now Selection ↔ CurrentLine overlap) and #3 (cadence).

Each session ends in a session-end commit. Worktree-per-step applies unless a session is short enough to land on main directly.

Deliberately not committed (framing-pass scope)

The framing pass closes with the following deferred to session 9.x or later:

• Exact quad colors per kind. Stance β-ish defaults will be picked in session 9.1 (probably Indexed(4) translucent for Selection, Indexed(0) slightly-lighter for CurrentLine). Real users will prefer theme-driven; expose via pmacs.theme in a follow-up if needed. Not framing-time work.
• Alpha vs reverse-foreground for selection. Some editors render selection by inverting the underlying text color; others by drawing a semi-transparent rectangle. Stance: rectangle (matches existing quad pipeline; reverse-foreground would require text-renderer cooperation we don't want yet). Decided session 9.1 if it surfaces.
• SelectionSnapshot vs Decorations::Selection reconciliation. pmacs-protocol has both a SelectionSnapshot family and a DecorationKind::Selection. Phase A used the decoration path. If a finding emerges that the snapshot path should drive backgrounds instead, classify per rule (iii). Out of framing scope.
• Acceptance-test shape for quad rendering. Headless wgpu golden- frame comparison was Phase A's deferred decision; quad backgrounds inherit the same defer. Session 9.x may surface complications; classify at surface-time.

Phase A finalization criterion

Phase A finalizes when:

1. Session 9.1 ships and Selection renders correctly in pmacs-gpu against the Phase A test corpus.
2. Session 9.2 ships and CurrentLine renders correctly with the Q#3 cadence holding.
3. The session-9 audit doc records the predicted-vs-actual scoring, matching pmacs-gpu-phase-a-audit.md's shape.
4. docs/pmacs-gpu-design.md's "Phase A" reference updates to point at the finalization audit doc.

The structural finding A8 from Phase A is then closed. SearchMatch{,Active} remains documented-but-not-implemented, queued for Phase B's editing-parity arc.