pmacs/docs/gpu-horizontal-scroll-framing.md

GPU horizontal scroll — QoL Stage 5

Status: revision 4 — APPROVED 2026-08-07. All five questions resolved. Implementation may begin within this scope.

• Q#G1 — the GPU-local offset is stored in pixels; parity conversion is exact via the supported monospace advance.
• Q#G2 — automatic cursor-follow only; reset on both the wrap transition and BufferSnapshot, with the specified pre-motion witnesses.
• Q#G3 — monospace-only, by the font contract that already exists.
• Q#G4 — the minimap does not move.
• Q#G5 — the complete verification set is accepted, including the snapshot-reset and minimap-stability witnesses.

Scope boundary, restated because it is what makes this lane small: local GPU viewport state only. No wire message, no protocol bump, no command surface, no minimap movement.

Revision 3 fixes four things review found in revision 2: Q#G1 still carried two claims Q#G3 had already falsified; Q#G2 was missing the buffer-snapshot reset; Q#G5's "nothing paints into the gutter" is impossible as written, because the gutter legitimately holds line numbers and diagnostic signs; and an off-left completion anchor hides the popup rather than closing it, which is a protocol distinction this lane must not blur.

Revision 2 had answered two functional findings: §1.1's "three consumers" was incomplete because the manual quad/squiggle renderers have no code-area scissor at all, and Q#G2's "inert under wrap" was too weak — the offset must be reset to zero, as the TUI already does.

This closes the QoL arc. Stage 1 (#219) made the TUI survive terminal zoom; Stage 2 (#220) gave the GUI native zoom; Stage 3 (#221) added ui.line-wrap; Stage 4 (#222) made truncate navigable in the TUI only. Stage 5 is the GPU half, and it is the lane Q#HS1's time box exists to guarantee: it is the immediately-next QoL work, and wrap stays the default until it lands.

---

1. Stage 4's framing was wrong about the hard part

§1.3 of docs/horizontal-scroll-framing.md said the GPU "needs a mechanism that does not exist" and called it the fact most likely to invert the cost estimate. It was half right and the half it got wrong is the expensive half.

What it got right: Scroll::horizontal is discarded throughout, because glyphon 0.11 never applies it when placing glyphs (pmacs-gpu/src/main.rs:1611, :6316, :8020, asserted at :16266, :16337, :16737). Scrolling via cosmic-text's own scroll is not available.

What it got wrong: that is not the only mechanism. The document TextArea already carries an explicit origin and a clip rectangle (pmacs-gpu/src/main.rs:8712):

TextArea {
    buffer: &self.buffer,
    left: text_left,                       // paint origin
    top: TEXT_TOP,
    bounds: TextBounds { left: gutter_clip_left, right: text_bounds_right, .. },
    ..
}

Horizontal scroll is left: text_left - offset_px with bounds.left unchanged. glyphon clips to bounds, so glyphs pushed left of the gutter simply are not painted — which is the same "paint from column 0, clip at the edge" shape the grid renderer uses, expressed in pixels.

This is a mechanism the file already relies on, not a new one: gutter_clip_left exists precisely so the gutter does not get painted over.

Why the correction matters beyond the estimate. Stage 4's framing used §1.3 to justify splitting the GPU out, and I endorsed the split on that basis. The split is still right — the consumers below are real work, and shipping them inside Stage 4 would have made one reviewable change into two unreviewable ones — but it was justified partly by a claim that overstated the difficulty. Recorded here rather than quietly dropped.

1.1 The real work is a shared transform AND a shared clip

Revision 1 said "three consumers" and that was wrong in a way that would have shipped a defect. Shifting the TextArea clips glyphon's text, because glyphon honors TextBounds. The manual quad and squiggle renderers have no code-area scissor at all — nothing stops them painting into the gutter, and today nothing needs to, because no code-relative x can be negative. Scrolling makes that false.

So Stage 5 needs two shared things, not one offset:

1. One screen↔code transform. code_x → screen_x is text_left() - offset_px + code_x, and hit testing is its exact inverse. Applied once, in one place, or the consumers disagree.
2. One code clip rectangle. [gutter_clip_left, text_bounds_right) — the same bounds the TextArea gets, expressed for the paths glyphon does not clip. Every code-relative painter must intersect with it, and that is a new obligation, not a threading exercise.

The paths that need both:

path	site	what breaks without the clip
caret rect in clip	:9698	asserts the caret cannot precede text_left — its comment says so explicitly. False after scrolling; the caret paints over the gutter
caret-painted predicate	:9734	same missing left-edge test. So revision 1's claim that the scroll indicator "inherits the fix" is FALSE — code_byte_painted reuses this and would call an off-left byte painted
glyph extent rects	:9766	washes, squiggles and selection extents must be cropped at the gutter edge, not merely offset
inline math origins	:9434	math boxes derive from the code origin and would render into the gutter
completion anchor	:7606	an off-left anchor must hide the popup — it already returns None when scrolled out, and closure is the daemon's CompletionPopup { anchor: None }, not this lane's

The two caret sites are the sharpest: :9698 does not merely lack a check, it documents the absence as safe ("right of the gutter isn't needed: the caret x can't precede text_left"). A comment asserting an invariant this lane deletes is worse than silence, so it must be rewritten rather than merely joined by a new test.

1.2 No wire, and that is not an accident

The GPU owns its viewport locally — scroll_top and code_scroll_residual are local state, never sent. A horizontal offset is the same kind of state, so Stage 5 adds no protocol message and no version bump, exactly as Stage 4 added none.

This is worth stating because the parallel with ui.line-wrap is misleading: the mode is buffer state and needed LineWrapFacts at v22, but the offset is viewport state and needs nothing.

1.2a The one approved exception to "local GPU viewport state"

Approved by the user 2026-08-08, after implementation raised it. The scope line for this stage is local GPU viewport state — no wire message, protocol bump, command surface, or minimap movement. One change lands outside it, and only one:

pmacs_protocol::scroll::follow_left. The follow rule — scroll the minimum distance that puts the cursor back inside — now lives in the protocol crate beside classify, and both frontends call it: src/editor.rs::horizontal_follow delegates, and the GPU converts px ↔ columns around it (exact, per Q#G1/Q#G3).

Why it is not scope creep. Q#G5 requires a TUI-parity witness that is "checkable rather than asserted". Two tests in two crates asserting the same literal is not that — it is the structural duplication pmacs-protocol::scroll's own module docs condemn, and that module exists because this arc already shipped exactly that defect: the scroll indicator, fixed in one copy and left wrong in the other. Without a shared rule there is no way to make the witness real.

What it does not do, which is what keeps it narrow and is the basis of the approval: it moves no viewport state (the TUI still owns view_left, the GPU still owns code_scroll_left), adds no wire message, and needs no protocol-version bump. follow_left is a pure function over values each side already holds — the identical argument classify's module docs already make for living there.

---

2. Open questions

Q#G1 — is the stored offset a column or a pixel count?

The TUI stores a display column (view_left). The GPU paints in pixels.

Revision 2 left two claims here that its own Q#G3 answer had already falsified: that the GPU's font "need not be monospace", and that Q#G3 makes "column" ill-defined. Neither is true — the code font is monospace by contract, so a column has one well-defined width, measured by the existing ADVANCE_PROBE helper.

My vote is unchanged — store pixels — but the reasons narrow to the ones that survive: the GPU's other viewport state is already pixel-flavoured (code_scroll_residual is a float), and a pixel offset composes with the clip rectangle without rounding at every frame.

Conversion is therefore exact, not approximate. columns × the supported monospace advance is the definition, and it is what makes the unconditional TUI-parity witness in Q#G5 checkable at all. A proportional font would have made this a lossy conversion; the font contract means it never is.

Q#G2 — how is the offset moved?

Stage 4 chose automatic only: the cursor-visibility pass gains a horizontal component. The GPU's analogous pass is ensure_caret_painted — named rather than cited by line, since revision 2 also invented a follow_cursor that does not exist.

My vote: mirror it exactly, so the two frontends agree on when the view moves. A GUI is also the place a horizontal wheel/trackpad gesture exists — but that is an explicit-scroll surface, which Stage 4 deliberately deferred, and adding it here would make the frontends disagree again in the lane that exists to stop that.

And the wrap transition must RESET the offset to zero, not merely ignore it. Revision 1 said "inert under wrap", which is too weak: inertness hides a stale value that reappears the moment the buffer toggles back to truncate, before any cursor motion. The TUI does not rely on inertness — horizontal_follow (src/editor.rs) assigns view_left = 0 on the wrap branch and returns.

The GPU must specify the identical lifecycle, and apply_line_wrap is where it belongs, beside the reflow it already performs.

And a second reset the TUI has no analogue for: the buffer snapshot. The GPU zeroes scroll_top and code_scroll_residual whenever a snapshot installs a new buffer — the offset is viewport state tied to the document being shown, and it must reset there for the same reason they do. Without it a buffer switch inherits the previous document's leftward viewport, showing the new buffer scrolled sideways until a cursor motion repairs it.

That is a worse symptom than the wrap case, because nothing about the new buffer explains it. Both resets are lifecycle requirements with their own witnesses (Q#G5), not properties that fall out of the transform.

Q#G3 — proportional fonts ANSWERED: they do not occur

Revision 1 asked the wrong question, from a false premise. It said "the GPU can resolve a non-monospace family" and proposed accepting a new TUI/GPU divergence to accommodate it.

The GPU does not resolve proportional code fonts. family_is_monospace_everywhere (pmacs-gpu/src/main.rs:8199) gates the family across all four weight/style combinations, apply_font_facts (:8235) falls back when it fails, and unresolvable_and_proportional_families_fall_back requires that fallback. A proportional family cannot become the code font.

So the answer is monospace-only, by the font contract that already exists — not a new constraint this lane imposes, and not a divergence to negotiate. Revision 1 would have introduced a font-dependent behavior difference to solve a problem the codebase had already solved, in the lane whose entire purpose is removing unchosen divergence.

The consequence for Q#G5: the monospace TUI-parity witness is unconditional for every font the GPU supports, rather than gated on a font check. That is a stronger test, and it exists only because the premise was corrected.

Pixel storage (Q#G1) is unaffected and still preferred — but its column↔pixel conversion is now defined against the supported monospace advance, which is a well-defined quantity rather than an approximation.

Q#G4 — does the minimap move?

The minimap draws line-shape bands. Horizontal scroll does not change which lines exist.

My vote: no. The minimap is a whole-document overview; scrolling the text sideways should not scroll it.

Q#G5 — what does the verification look like?

The GPU suite is headless-render based (headless_or_skip), and PMACS_REQUIRE_GPU=1 makes a missing adapter a failure rather than a skip.

Sketch, pending Q#G1/G2/G4:

• The gutter is unchanged by scrolling. Revision 2 proposed asserting that nothing paints left of gutter_clip_left, which is impossible: with line numbers on, the gutter deliberately holds digit glyphs and diagnostic-sign quads. The assertion would fail on a correct implementation.

  The checkable form of the same intent: the gutter rectangle is byte-identical before and after a horizontal scroll, and separately, only code-relative output geometry is inspected for the left-edge rule. That still catches the failure a per-painter test would miss — a code painter bleeding into the gutter changes those pixels — while remaining true of a working build.

• A left-clipped caret predicate. code_caret_rect_in_clip and caret_painted_in_code_clip must both report not painted for a caret scrolled off-left. This is what makes the scroll indicator correct; revision 1 wrongly assumed it came for free.

• Math and rule clipping: an inline math box and a decoration rule whose origins are left of the edge are cropped or culled, not drawn.

• An off-left completion anchor HIDES the popup; it does not close it — and the boundary is a point, tested at the edge.

  Added after review found the first implementation wrong here. It reused survives_code_clip_left and passed line_height as the horizontal extent: a vertical dimension standing in for a horizontal one. An anchor up to a line-height left of the gutter therefore survived, and completion_dropdown_rect bounds ax against the right margin only — so the popup painted over the line numbers. An anchor is a position between glyphs with no width of its own, so the predicate is screen_x < code_clip_left().

  The far-off-left witness cannot catch this, which is why it stayed green: 200px off-left fails a width-based predicate too. The witness must straddle the edge — the same anchor a fraction of a pixel either side — and assert the popup's own left edge stays out of the gutter on the visible side.

  The distinction is a protocol one and revision 2 got it wrong. completion_anchor_px returns None, so nothing draws — but the daemon-owned completion state and its key handling are retained. Actual closure is CompletionPopup { anchor: None }, which is the daemon's to send. So the witness is: no completion paint while the anchor is off-left, and the popup reappears when it scrolls back into view — session semantics unchanged. A lane about viewport geometry must not quietly redefine when a completion ends.

• The three consumers agree with the shifted origin — caret, decoration rect, and hit test at one non-zero offset, since a partial fix shows up as disagreement between them.

• Round-trip hit testing: pixel → byte → pixel at a non-zero offset.

• The wrap transition resets to zero (Q#G2): scroll right under truncate, toggle to wrap, toggle back, and assert the offset is 0 before any cursor motion. An inertness-only implementation passes a "wrap looks right" test and fails this one.

• The buffer snapshot resets to zero (Q#G2, second lifecycle rule). Revision 3 added the requirement and left it untested, which is how a lifecycle rule quietly becomes a comment. Scroll to a non-zero offset in buffer A, install a buffer B snapshot, and assert the offset is 0 and B renders at its code origin — before any CursorByte arrives. The pre-cursor scoping is the whole test: a later cursor motion repairs the offset anyway, so a witness that waits for one cannot distinguish "reset on snapshot" from "repaired on first motion", which is precisely the bug.

• The minimap does not move (Q#G4). The implementation already supports the vote — the minimap derives from the summary, the surface dimensions and scroll_top, with no horizontal input — so this pins an existing property rather than asking for new work, and that is the reason to write it: an offset threaded one seam too far would break it silently. Assert equal minimap vertices (or pixels) before and after a non-zero horizontal offset, with vertical state unchanged.

• A TUI-parity witness, now unconditional (Q#G3): the same buffer and the same column offset yield the same first visible character in both frontends. This is what makes "the frontends agree" checkable rather than asserted.

---

3. Coherence impact (§20)

• §16 Semantic Frontend Architecture — the direct target. This lane closes the divergence Stage 4 opened deliberately. The release notes should say the gap is closed, since Stage 4's said it existed.

• Journey step 4 is NOT completed by this lane, and revision 1 claimed it was. Step 4 ("Understand interface") is scored on welcome / help / tutorial discoverability, and COHERENCE.md:395 holds it Partial for reasons this lane does not touch: C-h deletes a word (deliberately, §18) and there is no tutorial. Long-line reachability is interface comprehension, which the step benefits from without being scored on.

  So the honest claim is preserving and improving interface comprehension, with no scorecard movement — and a scorecard edit here would need new journey evidence, which this lane does not produce. Recorded because writing an unearned ✔ into a scorecard is how a coherence document stops being ground truth.

• After this merges, Q#HS6 becomes live: whether wrap remains the default is revisitable on use evidence once parity exists. Not part of this stage.

• Rule 4 applies at this merge: the arc is done, so the long-lines lane in docs/active-work.md is removed — after its durable facts reach docs/agent-handoff.md, which is the precondition, not a formality.