pmacs/docs/ux-arc-framing.md

UX arc — framing (the gutter, and what it unlocks)

A UX overhaul arc for pmacs. The diagnostic-surface work (colors, status counts, wavy squiggles, minimap marks) already shipped (PRs #64–69), so the next frontier isn't polishing diagnostics — it's the one layout primitive both frontends still lack: a gutter column. Line numbers, diagnostic gutter signs (the last deferred Task #23 item), and later fold/git-diff markers all live in the gutter. This doc frames the umbrella UX arc and designs its keystone, the gutter, grounded in a coordinate- system recon of both frontends.

Why the gutter is the keystone

Two independently-requested features share one missing foundation:

• Line numbers — requested; every editor has them; pmacs has none.
• Diagnostic gutter signs — explicitly parked in the diagnostics arc: "no gutter column exists; adding one is a layout-level project, deliberately not done." Today the TUI fakes it with a col-0 background marker (diag.rs) and the GPU proxies it with minimap marks.

Both need a reserved left column and the coordinate-math to go with it. Build the column once (per frontend) and both features — plus future fold markers, git-diff bars, breakpoint dots — become content that rides it.

The load-bearing bet: no protocol change

The daemon is pixel-pure — it never learns screen geometry; the frontend owns viewport and visual layout (the semantic-frontend contract). The gutter is therefore entirely frontend-local, and the recon confirms each frontend already holds the data it needs:

• Line numbers — the frontend owns the text, so it has line indices.
• Diagnostic severity per line — already frontend-side (TUI: DiagnosticView over the diag store; GPU: current_decorations, the same source the squiggles use). Map each diagnostic's range.start to a line, take the max severity per line — no new wire data.

So zero protocol change, zero daemon change. The blast radius is two frontend renderers. (This also means it's implemented twice — the TUI grid and the GPU are separate codebases with no shared render code — so the design fixes a shared convention, §Q#UX7, even though the code is duplicated.)

The reserved-width model

A gutter is a fixed-width strip carved from the left, mirroring how the GPU already carves the right for the minimap. Text shrinks by the gutter width; the gutter stays fixed while text scrolls (neither frontend has horizontal scroll, so "fixed while scrolling" is free — only the numbers printed change with the vertical scroll position).

TUI (recon: clean seam). The renderer paints everything relative to a per-window Viewport { cell_origin, cell_size }. The whole gutter is fundamentally one shift at the viewport-construction site (editor.rs:1610): cell_origin.col += gutter_w, cell_size.cols -= gutter_w, then paint the gutter into the reclaimed [rect.origin.col, +gutter_w) strip. Every painter that consumes viewport.cell_origin (base text, syntax, diagnostic underline, search) becomes gutter-agnostic for free. The handful that read rect.origin.col directly each need a manual +gutter_w:

• cursor placement (editor.rs:1683), local selection (:1794), remote-presence cursor/selection (overlay_paint.rs:160,253);
• mouse hit-test (dispatch_mouse, editor.rs:866) subtracts gutter_w from local_col, and clicks with local_col < gutter_w are gutter clicks (§Q#UX6);
• the diagnostic col-0 sign (diag.rs:499–586) relocates into the strip — gutter_glyph() (diag.rs:75) is already defined and unused, waiting for exactly this.

pos_to_display/display_to_pos (the byte↔display-column core) operate in line-local space and need no change — the gutter is applied by callers crossing into grid space, not in the mapping itself.

GPU (recon: one knob). All horizontal geometry hangs off TEXT_LEFT = 16.0. A gutter of width G is:

• pixel→byte — one site: hit_test_source_byte (main.rs:2758), x - TEXT_LEFT → x - TEXT_LEFT - G;
• byte→pixel — four sites, each TEXT_LEFT → TEXT_LEFT + G: glyph render origin (TextArea.left, :3894), text clip bounds.left (:3898, 0 → G), caret (:4350/4355), washes+squiggles (:4413);
• placement loop — walk layout_runs() (run.line_top, run.line_i) and draw gutter glyphs/quads at x ∈ [0, G), exactly the minimap's mirror on the left. Reserve the band for clicks like in_minimap_band.

Neither frontend has horizontal scroll or soft-wrap today, so there is no scroll-offset interaction to reconcile — the single biggest simplifier.

Forced decisions

Q#UX1 — frontend-local, no protocol change. ✗ DISPROVEN (see below). Framed as: the data is local in both frontends, so no wire change. That was half-right — rendering is local, but the control (M-x window.toggle-line-numbers) lives daemon-side, so the mode must reach the GUI over the wire. Corrected to: the toggle is daemon-owned per-window state, shipped to the frontend via a new additive InstanceMessage:: LineNumbers variant (protocol v13, daemon-gated < 13). The GUI still renders locally; it just receives the on/off flag. See the as-built control-plane note.

Q#UX2 — reserve on the left, mirror the minimap. Text area shrinks; the gutter is a fixed strip. TUI: shift the viewport at one site. GPU: add G to the four byte→pixel sites, subtract at the one pixel→byte site, set a text_bounds_left.

Q#UX3 — dynamic width, digit-count driven. gutter_w = digits(line_ count) + padding (padding = 1 leading + 1 trailing cell/space typical). Recomputed as the line count crosses a power of ten. Rejected: fixed width (wastes space on small files, truncates on huge ones). Line count is already in hand at the width-computation site in both frontends.

Q#UX4 — modes: off | absolute | relative | hybrid. absolute = line index + 1. relative = distance from the cursor line (Vim-style, for fast N j/N k). hybrid = current line absolute, others relative (the popular default). Ships incrementally: absolute first (proves the column + width + coordinate math with zero cursor-coupling), relative/ hybrid as a follow-up (they add a cursor-line dependency + repaint-on- cursor-move, which is why they come second).

Q#UX5 — the setting hook + where state lives. Model on the existing frame_target_ms tunable (async_runtime.rs:630 + Lua _frame_target_ms /_set_frame_target_ms). Line-number mode is naturally per-window (relative numbers frequently are), so the field lives on struct Window (TUI) and is read at paint time; a pmacs.window/pmacs.frontend binding sets it, wrapped by a friendly builtin/ Lua chunk. The GPU reads an equivalent local setting (it has no window tree, so a single frontend-wide mode is fine there for v1). Consistency of value across frontends is a convention, not shared code.

Q#UX6 — gutter click behavior. MVP: a click in the gutter band selects the whole line (common editor affordance) — or, if that's too much for the first cut, is consumed as a no-op (never mis-mapped to a text byte). The recon shows both frontends can classify a gutter-band click cheaply (local_col < gutter_w / in_minimap_band-style). Pick line-select if it's a few lines; else no-op and defer.

Q#UX7 — shared convention across the two renderers. The code is duplicated, so the design pins the contract both must honor: same width formula (digits + padding), same number formatting (right-aligned, 1-based), same mode set, same diagnostic-sign glyphs/severity precedence, gutter never overlaps the mode line / status band / minibuffer. A short "gutter contract" section in each frontend's code comments points back here so they don't drift.

Sub-arc sequence (each its own PR, each green under both flavors)

1. Gutter + absolute line numbers. Introduce the reserved column and the coordinate shift in both frontends; render absolute numbers. The riskiest, most valuable step — it lands the foundation and the coordinate math. Validation is a human eyeball per frontend (cursor lands on the right glyph after a click; caret draws in the right place; selection/overlays don't bleed into the gutter).
2. Diagnostic gutter signs. Relocate the TUI col-0 marker into the gutter (gutter_glyph()) and add GPU gutter glyphs; max-severity per line from data already present. Closes the last Task #23 item.
3. Relative / hybrid line-number modes. Add the cursor-line dependency
   • repaint-on-cursor-move; a mode toggle on the same machinery.
4. The rest of the UX backlog (below), sequenced later.

The umbrella UX backlog (beyond the gutter)

Named now so the arc has a horizon; not committed, sequenced after the gutter sub-arcs:

• Minibuffer polish — i/total hint, Telescope-style preview pane, candidate annotations (kind/docstring), multibyte-exact band caret.
• Editing affordances — current-line highlight refinements, whitespace rendering, indent guides.
• Folding — needs a fold engine and gutter fold markers (rides the gutter built here); big, greenfield.
• Git-diff gutter markers — needs a diff source; rides the gutter.
• Context-menu polish — submenus, kill-ring/clipboard history, first-letter mnemonic jump.

Categorical bets (score at the arc's close)

• No protocol change holds. → SCORED FALSE. Rendering is local, but the toggle command lives daemon-side, so the mode has to cross the wire. It cost one additive variant + a version bump (v13) — cheap and routine here, but the bet was wrong: "renders locally" does not imply "no protocol change" when control is daemon-owned. Lesson for the rest of the arc: a frontend-rendered feature still needs a wire channel whenever its control is a daemon command.
• The coordinate shift is localized, not pervasive. Recon says TUI = 1 viewport shift + ~5 manual sites; GPU = 1 pixel→byte + 4 byte→pixel sites. If a gutter bug shows up somewhere not on those lists, the bet was wrong and the mapping was less centralized than the recon found.
• pos_to_display / cosmic-hit stay gutter-agnostic. The mapping core is untouched; only the grid-crossing callers change. If a mapping-core edit becomes necessary, the seam was leakier than modeled.
• Duplication is cheaper than abstraction here. Two ~50-line gutter implementations beat inventing a shared cross-frontend layout layer for two consumers. Revisit only if a third frontend appears.

Validation implications

Per sub-arc: fmt + clippy --all-targets + full tests under both Lua flavors, as always. But the load-bearing validation is a human eyeball in each frontend — the coordinate shift is precisely the class of change where a unit test passes and the caret still lands one column off. Minimum manual checklist for sub-arc 1: click-to-place lands correctly with the gutter present; caret draws in the right cell/pixel; selection drag stays out of the gutter; resize/scroll keep the gutter fixed; a >999-line file grows the width without misaligning anything. GPU and TUI checked separately.

As-built

Sub-arc 1 — gutter + absolute line numbers (TUI + GPU).

• TUI (window.rs/editor.rs/overlay_paint.rs): LineNumberMode {Off, Absolute} per-window field + Window::gutter_width(). One viewport shift (editor.rs) makes text/syntax/diag/search painters gutter-agnostic; ~5 direct-coordinate sites (cursor, selection, mouse hit-test → line-start, remote presence) each add gutter_w. paint_line_number_gutter writes right-aligned dim digits alloc-free.
• GPU (pmacs-gpu/main.rs): everything hangs off TEXT_LEFT; a text_left() (= TEXT_LEFT + gutter_width_px()) is applied at the 4 byte→pixel sites (main text, caret, washes/squiggles) and subtracted at the 1 pixel→byte hit-test. A dedicated gutter_text_renderer/buffer draws right-aligned dim numbers reshaped per scroll, mirroring the minimap's reserved column.
• Control plane (the Q#UX1 correction). M-x window.toggle-line-numbers sets the active window's mode (daemon-side). The TUI reads its window directly; the GUI receives the mode via the new InstanceMessage::LineNumbers { buffer_id, enabled } (protocol v13, additive, daemon-gated < 13). Producer: SemanticRenderState::line_numbers_msg (cached-compare suppression, seeded to the frontend's off default so a plain window adds no traffic). Consumer: the GUI drives its local line_numbers from it. The earlier --line-numbers GPU flag was retired. Now one M-x toggle works in both frontends, each affecting its own window — a single source of truth.

Validated: fmt + clippy --all-targets clean under both Lua flavors; 1440 lib tests (incl. the gutter render + line_numbers_msg emit/suppress tests), 12 protocol, 53 pmacs-gpu (incl. the headless gutter render test on the adapter). Both frontends eyeballed for coordinate correctness.

Deferred to later sub-arcs: relative/hybrid modes; diagnostic gutter signs (sub-arc 2); the exact gutter padding is a tunable to eyeball.

Sub-arc 2 — diagnostic gutter signs (TUI + GPU).

Per-line severity signs riding the sub-arc-1 gutter — closing the last deferred Task #23 item. No protocol/daemon change: the per-line severity is already frontend-side (the TUI's diag store, the GPU's current_decorations).

• Coupling decision. Signs ride the line-number gutter — they show when line numbers are on, and vanish when off (the legacy col-0 background marker returns in the TUI's no-gutter mode). A signs-without-numbers mode is deferred; when it lands, the gutter's presence test widens from "line numbers on" to "line numbers OR signs on."
• TUI (diag.rs/editor.rs/view.rs): Viewport gains gutter_w so overlays can address the gutter's leading column at cell_origin.col - gutter_w. The gutter number pass moved before the overlay loop so DiagnosticView can draw its sign into the gutter's blanked leading column without the number pass erasing it. The sign is the severity glyph (E/W/I/H) colored by underline_color(); most-severe wins (the existing line_markers map). Extracted paint_line_markers.
• GPU (pmacs-gpu/main.rs): collect_gutter_sign_rects walks layout_runs(), finds the most-severe diagnostic decoration overlapping each line (diagnostic_severity_rank, min wins) and pushes a thin severity-colored bar at the gutter's left edge, riding the existing background quad batch. Rendered as a bar, not a glyph — the GPU gutter number layer is single-color, so a per-line-colored bar was the clean path; same convention as the TUI, per-frontend rendering (Q#UX7).

Validated: fmt + clippy --all-targets clean both flavors; lib tests (incl. the TUI gutter-sign placement test) + 54 pmacs-gpu (incl. a headless sign render test on the adapter). Both frontends eyeballed.

Cross-cutting bug fixed en route (PR #87, off the arc): a bare --daemon + a GPU is a two-frontend session; EditorCore::close_active / close_others operated on the global windows set and so closed other frontends' windows, dangling their view.active and crashing the daemon in active_window(). Scoped both to the active frontend's layout. (Surfaced while eyeballing this sub-arc against the two-frontend setup.)

Known follow-up (not this arc): the GPU minibuffer completion-navigation highlight sticks / doesn't wrap on arrow-up; reproduces on the "normal" nav path but not the alternate one. Its own thread.

Sub-arc 3 — relative + hybrid line-number modes (TUI + GPU, protocol v14).

The last two of the framed modes (Q#UX4): Relative (each line shows its distance from the cursor line; cursor = 0) and Hybrid (cursor line shows its absolute number, others relative — Vim number+relativenumber).

• One enum, one number rule. LineNumberMode {Off, Absolute, Relative, Hybrid} + number_for(line, cursor_line) live in pmacs-protocol so the wire, daemon, TUI, and GPU all compute the same value (Q#UX7); pmacs re-exports it as crate::window::LineNumberMode.
• Protocol v14 (the scored-false Q#UX1 debt, part two). Sub-arc 1 shipped LineNumbers { enabled: bool } (off/absolute) as a deliberate placeholder; relative/hybrid need the mode, so the variant now carries mode: LineNumberMode. Encoding change → 13 → 14, daemon-gated < 14 (a v13 peer gets no LineNumbers), same shape as the v10 SearchPrompt bump.
• Cursor-line dependency + repaint-on-move. Relative numbers change as the cursor moves, not just on scroll. TUI: the full-frame render already repaints on cursor motion, and paint_line_number_gutter reads the cursor's buffer line (text_view.line_at_offset(cursor)) — free. GPU: refresh_gutter_buffer rebuilds every render (which cursor moves already trigger) using cursor_line() off current_line_starts — also free.
• Stable width. gutter_width is sized by digits(line_count) for every on-mode, so the text never jitters as the cursor moves.
• Selection UX (chosen over a 4-way cycle): window.toggle-line-numbers stays a binary off/absolute toggle; window.set-line-numbers opens the minibuffer with an arrow-navigable completion dropdown (off|absolute|relative|hybrid) — dogfooding the #89 arrow-nav fix.

Validated: fmt + clippy --all-targets clean both flavors + gpu; 1446 lib (incl. number_for across all modes), 12 protocol, 55 pmacs-gpu (incl. a headless render proving relative ≠ absolute). Both frontends eyeballed, including live cursor-move renumbering.

Arc close

All four sub-arcs shipped: 1) gutter + absolute (v13), 2) diagnostic signs, 3) relative/hybrid (v14). Q#UX1 ("no protocol change") scored false — the gutter cost two protocol bumps (v13 daemon-owned toggle, v14 mode) — because the control is daemon-owned even though rendering is frontend-local. Deferred, riding the gutter when someone wants them: signs-without-numbers mode; whitespace/indent guides; folding placeholders; git change markers.