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.

<!-- next sub-arcs appended here -->