# Folding Stage 2 — grid (daemon-rendered) collapse — framing (Arc 6)

**Revision 2 — 2026-07-23. Status: DRAFT for review (rev 1's five findings
addressed).** Parent architecture (`docs/folding-framing.md`, rev 5) is APPROVED
and Stage 1 (the headless fold engine) is MERGED as **#142** (canonical `main` @
`c49a8c7`). This doc reframes **Stage 2** in detail off that base, per the
parent's §8/§14. Numbering continues the parent's `Q#FD…` scheme from `Q#FD12`.

## 0. Revision history

### Round 1 (rev 1 → rev 2)

- **F1 (major) — nested folds resolved to the wrong head.** Rev 1's `head_of`
  returned the *innermost* enclosing fold's head and assumed it visible; under
  nesting an outer fold hides the inner head, so carets/diagnostics/relative
  numbers would have clamped onto another *hidden* line. Rev 2 defines
  **`visible_head_of(line)` = the head of the *outermost* enclosing fold** (the
  only head guaranteed visible), used by every clamp. A hidden `view_top` clamps
  **backward** to that head (not forward past the fold, which contradicted
  acceptance 6). Relative/Hybrid numbering anchors on the **clamped visible
  cursor**. New nested-fold / shared-cursor acceptance (§11).
- **F2 (major) — the mapping-consumer census was incomplete.** Rev 1 claimed all
  painters route through `Viewport`. They do not: local selection
  (`src/editor.rs:3241`) and the mode-line scroll indicator (`src/editor.rs:3803`)
  paint from `paint_frame` with raw `view_top` arithmetic; peer cursor/selection
  (`src/overlay_paint.rs:159`) runs *after* `paint_frame` and subtracts `view_top`
  independently; the style overlay (`src/overlay.rs:385`), search wash
  (`src/search.rs:492`), diagnostics (`src/diag.rs:563`), and the completion
  anchor each derive `start_line + row_offset`. Rev 2 carries the **complete
  consumer census** (§3.1), adds **TUI peer-presence fold behavior** (clamp a
  hidden peer cursor to the visible head; drop/project hidden selection cells) as
  explicit scope, and expands acceptance to pin local selection, peer presence, an
  ordinary style/search overlay across a fold, completion anchoring, and the
  scroll indicator.
- **F3 (major) — the fold glyph's sign cell does not exist by default.** Line
  numbers default to `Off` ⇒ `gutter_width()==0` (`src/window.rs:216`); diagnostics
  then fall back to a col-0 *background* on the first content cell
  (`src/diag.rs:635`), so rev 1's "zero-width-change" gutter glyph had nowhere to
  render. Rev 2 makes the fold glyph **conditional on a gutter existing**
  (Q#FD20): gutter off ⇒ **ellipsis only**; gutter on ⇒ reuse the sign cell with
  diagnostic priority. Acceptance covers both. The parent's unconditional
  gutter-marker promise, if required, needs a **dedicated sign column** and an
  acknowledged layout change (named alternative, §5/§9).
- **F4 (major) — a per-frame map instance cannot serve command-time motion, and
  `Viewport` is `Copy`.** `move_up/down`, paging, wheel scroll, and clicks execute
  **outside** the render frame, so they cannot reuse a map installed on that
  frame's `Viewport`; and `Viewport` is compile-time-pinned `Copy`
  (`src/view.rs:130`). Rev 2 reframes the map as **one shared derivation/query
  primitive** with **separate short-lived instances** for rendering vs
  command/event handling (Q#FD12); the render instance is threaded as
  `Option<&'a VisibleLineMap>` on a **lifetime-bearing `Viewport<'a>>`** (a shared
  ref is `Copy`, so `Viewport` stays `Copy`); the primitive's home is usable from
  `EditorCore`, not render-only.
- **F5 (moderate) — tighter unfold seam + settled undo decision.** Rev 2 keys the
  Lua-path widening on the existing **`InteractiveCommandOrigin`**
  (`src/editor.rs:53`), not command-history inference; hooks the **common
  `run_buffer_edit`** (`src/lua_bindings/mod.rs:1305`) so interactive
  `bypass_intercept` mutations do not escape; **requires the target to be the
  invoking frontend's active-window buffer** (an explicit inactive-buffer Lua
  mutation stays programmatic); keeps the Rust hook at `apply_active_edit` and the
  `notify_buffer_edit` exclusion; and **explicitly defers undo/redo unfold**
  (Q#FD19).

### Rulings absorbed

- **Q#FD17 = INCLUDE.** Vertical motion steps through *visible* lines; if motion
  begins from a hidden logical cursor (shared fold or goto-line), it **first
  normalizes to the visible head**, then steps to the preceding/following visible
  line (§7).
- **#142 housekeeping** (retire the active-work.md folding lane + refresh handoff
  §1) is a **separate docs PR**, kept out of `folding-tui`.

## 1. What Stage 2 ships

The grid TUI is **daemon-rendered**: the daemon walks a buffer's source lines and
paints a character grid it ships to the terminal client. Stage 1 built the
instance-side fold store and produces `FoldState` for GPU sessions, but **no
frontend renders a collapse yet** — the daemon grid path never consults the fold
store.

Stage 2 makes the **daemon grid renderer fold-aware**:

1. **Collapse** — omit each fold's hidden source lines; head line shows a trailing
   ellipsis; rows below shift up.
2. **Gutter fold marker** — a fold glyph on the head-line row **when a gutter
   exists** (Q#FD20); ellipsis-only otherwise.
3. **Fold-aware line numbers** — the `LineNumbers` family skips hidden lines;
   relative/hybrid distance is measured across the collapse, anchored on the
   clamped visible cursor.
4. **Fold-aware diagnostic signs** — a sign on a hidden line clamps to the fold's
   **visible head** row (most-severe merge).
5. **Fold-aware caret, local selection, and peer presence** — no caret, no
   selection cell, and no peer cursor renders on a hidden line; each clamps to the
   visible head or is projected/dropped.
6. **Fold-aware viewport/scroll/motion** — `view_top`, paging, wheel scroll,
   clicks, auto-scroll, vertical line-motion, and the mode-line scroll indicator
   all reckon in **visible** lines.
7. **Interactive-Lua-command unfold widening** — yank, query-replace, and
   comment-toggle unfold a fold at their edit point before the edit is visible.

**No wire schema changes and no protocol bump.** `FoldState` production (Stage 1)
is untouched; the TUI collapse is entirely daemon-side (the vterm-Stage-2 shape);
the GPU render path is Stage 3.

## 2. Ground truth (scouted + review-verified 2026-07-23, `main` @ `c49a8c7`)

### 2.1 The grid render path is layered — collapse belongs deep in it

`RenderState::render_frame` (`src/instance_render.rs:98`) is a **diff shell** (it
double-buffers cells, emits `CellDelta`); it does not walk source lines. The
source-line→grid-row loop is two calls down:

```
RenderState::render_frame  (src/instance_render.rs:98)   — diff shell
  → paint_frame            (src/editor.rs:2796)          — per-window composition; HAS state.fold_registry
      → window.text_view.render(buf, viewport, grid)     (src/editor.rs:2948)
          → TextView::render (src/text_view.rs:207)      — the line→row loop
```

`TextView::render` (`src/text_view.rs:213`) maps `line = start_line + row_offset`
— **strictly identity**, no skip, no wrap (long lines truncate). `Window.view_top`
(`src/window.rs:179`) is a **source-line index**. `DisplayCoord`'s doc
(`src/view.rs:108`) anticipates a non-identity map "once virtual lines, wrapping,
and inline expansions appear," but nothing implements one today — **folding is the
first**.

### 2.2 The complete set of identity-assuming consumers (F2)

Every site below assumes `display_row = source_line − view_top` (or the inverse)
and must consult the shared visible-line map. Rendering-frame sites, after-frame
sites, and command-time sites are distinguished because they need **different
instances** of the map (§3, F4):

| # | Site | file:line | phase |
|---|---|---|---|
| 1 | text render loop | `src/text_view.rs:214` | render (Viewport) |
| 2 | line-number gutter | `src/editor.rs:3215` | render (paint_frame) |
| 3 | style/syntax overlay | `src/overlay.rs:385` | render (Viewport) |
| 4 | diagnostics overlay | `src/diag.rs:563` + `paint_line_markers` `:635` | render (Viewport) |
| 5 | search wash overlay | `src/search.rs:492` | render (Viewport) |
| 6 | completion popup anchor | completion overlay (byte→row) | render (Viewport) |
| 7 | caret grid row | `src/editor.rs:3044` | render (paint_frame) |
| 8 | local selection | `paint_local_selection`, `src/editor.rs:3241` | render (paint_frame) |
| 9 | mode-line scroll indicator | `format_scroll_indicator`, `src/editor.rs:3803` | render (paint_frame) |
| 10 | peer cursor + selection | `src/overlay_paint.rs:159` | **after** paint_frame |
| 11 | click inverse | `activate_and_position`, `src/editor.rs:2233` | command/event |
| 12 | auto-scroll clamp | `src/editor.rs:2866` | command/event |
| 13 | paging / wheel / vertical motion | `src/editor_core.rs:1745/1779`, `src/editor.rs:2264`, `move_up/down` | command/event |

Overlays (1,3,4,5,6) already thread through `Viewport`; sites 2,7,8,9 run in
`paint_frame` directly; site 10 runs after `paint_frame` and re-derives
`gutter_w`/`view_top` itself (`src/overlay_paint.rs:143-160`); sites 11–13 run
during input dispatch, entirely outside any render frame.

### 2.3 The renderer can reach the fold store

`fold_registry: SharedFoldRegistry` is a field on `EditorCore`
(`src/editor_core.rs:223`) and `EditorState` (`src/editor.rs:110`). Both the
render path (`paint_frame`) and command-time code (`EditorCore` methods) reach it.
The read surface (`src/fold.rs`): `FoldRegistry::folds(buf) -> Vec<ByteRange>`
(`:327`, whole-buffer, sorted); `FoldStore::containing(p)` (`:171`, byte-space,
`(start, end]`). **No line-space query exists** — Stage 2 adds it (§3). A fold's
`start` = end-of-head-line content byte, `end` = end-of-last-hidden-line content
byte, so `head_line = line_at_offset(start)`, hidden = `head_line+1 ..=
line_at_offset(end)`. Use the fold's `(start,end]` convention, never the
`ByteRange` struct doc's `[start,end)`.

### 2.4 The gutter

- `LineNumberMode` (`pmacs-protocol/src/message.rs:1173`; default **`Off`**) is
  per-window (`Window.line_numbers`, `src/window.rs:188`). Number rule
  `number_for(line, cursor_line)` (`:1197`) uses **raw-line `abs_diff`** for
  relative distance.
- `paint_line_number_gutter` (`src/editor.rs:3177`): `buffer_line = view_top + r`
  (`:3215`) → `number_for(...)`; `cursor_line = line_at_offset(window.cursor)`
  (`:3189`).
- **Gutter width is 0 when line numbers are Off** (`Window::gutter_width`,
  `src/window.rs:216`). When on, width = `decimal_digits(line_count)+2`, fixed to
  the absolute count (no jitter; folding does not change `line_count`).
- Diagnostic signs: `DiagnosticView::render` (`src/diag.rs:496`) →
  `paint_line_markers` (`:635`): `gutter_w>0` draws the sign glyph in the gutter's
  leading cell; **`gutter_w==0` falls back to a col-0 background** on the first
  content cell (the "fake gutter"). So a dedicated sign cell only exists with a
  gutter on (F3).

### 2.5 The interactive-edit unfold seam (F5, correcting rev 1)

Stage 1's `unfold_before_point_edit` (`src/editor_core.rs:1847`, reads
`active_window().cursor`) is called at the top of the six `EditorCore` primitives;
the shared `apply_active_edit` (`:1266`) they call does not itself unfold.

- **Yank / query-replace** are **`apply_active_edit` callers** (local; never the
  remote path): yank → `clipboard_paste`→`insert_bytes_over_region`→`apply_active_edit`
  (`:2544/2570`); query-replace → `query_replace_apply_current`→`apply_active_edit`
  (`:1129/1137`). They skip the six primitives, so they do not unfold today.
- **Comment-toggle / yank-pop** take the Lua mutator path. The common entry is
  **`run_buffer_edit`** (`src/lua_bindings/mod.rs:1305`), which dispatches to
  `run_managed_edit` (`:1347`) *or* `run_bypass_edit` (`:1318`) on the
  `bypass_intercept` flag; both call `apply_edit_skip_intercepts` then
  `notify_buffer_edit_to_windows`. Hooking only `run_managed_edit` would let an
  interactive `bypass_intercept` edit escape — hook `run_buffer_edit`.
- **`InteractiveCommandOrigin`** (`src/editor.rs:53`) is an ephemeral, Lua-app-data
  authenticated origin: `.current() -> Option<FrontendId>` is the frontend while an
  interactive command runs; `.enter(fid)` returns a guard that restores on drop and
  **clears even when a Lua command errors**. This is the scoped authority for the
  Lua-path widening — no command-history inference needed.
- **Undo/redo** reach the buffer through `notify_buffer_edit_to_windows` directly
  (`add_history_methods`, `src/lua_bindings/mod.rs`), not `apply_active_edit` nor
  `run_buffer_edit`.

### 2.6 Scroll/viewport commands count raw lines; no recenter

`move_page_down/up` (`src/editor_core.rs:1745/1779`), `scroll_window`
(`src/editor.rs:2264`), `move_to_line` (`:708`), and the mode-line indicator all
work in **raw source-line** space. There is no `beginning/end-of-buffer` command
and **no recenter** (deferred, blocked on viewport facts; handoff §6). Stage 2
inherits the recenter deferral.

## 3. The shared visible-line map primitive (Q#FD12)

Stage 2's spine is **one derivation/query primitive** — a `VisibleLineMap` type
plus a builder — computed from `state.fold_registry.folds(buffer_id)` and the
buffer's line offsets. It is **not one instance pinned to a frame**: it is built as
**short-lived instances** wherever a source↔display mapping is needed (F4), and its
home is a module usable from **both** the render path and `EditorCore` (not
render-only). Candidate home: `src/fold_view.rs`, or a `FoldStore`
convenience that returns hidden-line intervals given the line-offset table (the
byte→line conversion then lives beside the `(start,end]` convention it must match).
The byte-range store in `src/fold.rs` stays the single source of truth; the map is
derived, never stored.

### 3.1 Queries

Folds may nest; the derivation unions their hidden intervals into a sorted,
non-overlapping hidden-line set `H` (a line is hidden regardless of which fold owns
it). The map answers, in **line space**:

- `is_hidden(line) -> bool` — `line ∈ H`.
- **`visible_head_of(line) -> line`** — for a hidden `line`, the head of the
  **outermost** enclosing fold (resolve to the enclosing fold's head; if that head
  is itself hidden, recurse; heads strictly decrease, so it terminates on the one
  visible head). For a visible `line`, itself. **Every clamp uses this** — caret,
  diagnostics, peer cursor, relative-number cursor anchor, and the `view_top`
  backward clamp. (Rev 1's innermost `head_of` is removed — F1.)
- `next_visible(line)` / `prev_visible(line)` — the next/previous visible line,
  skipping whole folds (for the render walk and vertical motion).
- `visible_between(a, b) -> isize` — signed count of visible lines from `a` to `b`
  (relative/hybrid distance; paging).
- **`clamp_view_top(line) -> line`** — if `line ∈ H`, `visible_head_of(line)`
  (**backward**, so a fold at the top shows its head — acceptance 6); else `line`.
  This replaces rev 1's forward `first_visible_at_or_after`, which skipped past the
  fold and hid the head.

Build cost is O(folds) (folds are O(top-level blocks), parent B2), reusing the
render path's existing line-offset table — **Bet B4**.

### 3.2 Instances per phase (F4)

- **Render frame.** `paint_frame` (`src/editor.rs:2796`) builds one instance and
  (a) threads it to the overlay painters (1,3,4,5,6) as `Option<&'a
  VisibleLineMap>` on a **lifetime-bearing `Viewport<'a>>`** — a shared ref is
  `Copy`, so `Viewport` stays `Copy` (F4); (b) passes the **same** instance
  directly to the in-`paint_frame` sites (2,7,8,9). The `View::render` signature
  becomes `Viewport<'_>`; every construction site gains the field (non-fold callers
  pass `None`). This is a settled compile-time change across the `View` impls and
  `Viewport` constructions.
- **After the frame.** The peer-presence pass (`src/overlay_paint.rs`, site 10)
  runs after `paint_frame` and takes its own arguments; it receives (or builds) a
  fresh instance for the same buffer and clamps peer cursors / projects peer
  selection through it.
- **Command / event.** Click inverse, auto-scroll, paging, wheel, and vertical
  motion (sites 11–13, in `EditorCore` / `EditorState`) each build a short-lived
  instance from `state.fold_registry` + the buffer at call time. "The map is
  already built" (rev 1) was false for these — they run outside any frame.

`view_top` **stays a source-line index** (Q#FD12, **Bet B5**), only ever set via
`clamp_view_top` so it never rests on a hidden line — preserving the saveplace
(`saveplace.lua:60`) and `_view_top`/`set_view_top` contracts. Visible-line
*ordinals* are derived where needed, never stored.

## 4. Collapse rendering (Q#FD13)

`TextView::render` (`src/text_view.rs:207`) advances over **visible** lines via
`next_visible`: row `r` shows the `r`-th visible source line at/after
(already-visible) `view_top`; hidden lines are skipped; trailing rows clear as
today. A visible head line renders its real content then a trailing ellipsis
marker (` …`) in the **content area** (clipped like any long line) — the
authoritative, layout-neutral fold indicator. Overlays (1,3,4,5,6) read the same
map through `Viewport`, so a span/wash/sign/anchor on a hidden line is simply not
painted (its row does not exist) and one on a visible line lands on the right row.
Folding is **not** an overlay — overlays cannot delete rows.

## 5. Gutter: line numbers + fold glyph (Q#FD14, Q#FD20)

**Line numbers (Q#FD14).** `paint_line_number_gutter` (`src/editor.rs:3177`) walks
visible lines (row `r` → the `r`-th visible line). **Absolute** shows that line's
raw `line+1` (hidden numbers just do not appear — the column jumps from the head's
number to the first post-fold number). **Relative/Hybrid** measure distance in
**visible** lines: `visible_between(anchor, row_line)`, where the cursor **anchor**
is `visible_head_of(cursor_line)` (F1 — the cursor may be on a hidden shared-fold
line). Absolute still needs the raw line, so the walk carries both the raw source
line and the visible ordinal. Gutter width is unchanged (§2.4).

**Fold glyph (Q#FD20, F3).** Conditioned on a gutter existing:
- **Line numbers off (`gutter_w==0`, default):** no sign cell exists, so the fold
  marker is the **content-area ellipsis only**; the diagnostic col-0 background
  fallback is unchanged.
- **Line numbers on (`gutter_w>0`):** on a head-line row, draw a fold glyph in the
  gutter's col-0 sign cell **unless a diagnostic clamps there** (Q#FD15) —
  diagnostic wins (an error inside the fold is higher-signal).

This keeps the gutter width rule intact and adds no column. Making the gutter
marker **unconditional** would require a **dedicated fold sign column** and an
acknowledged layout change; deferred (§9). The parent §7's promise is thus honored
*when a gutter is present*, with the ellipsis as the universal indicator.

## 6. Diagnostic signs on hidden lines (Q#FD15)

`DiagnosticView::render` (`src/diag.rs:496`): before recording a marker for source
`line` (`:563/:570`), if `is_hidden(line)` **remap to `visible_head_of(line)`**
(clamp to the outermost visible head, F1), not drop. The existing
most-severe-per-row merge (`:570`) then makes the head row show the most severe
sign among the head and every hidden line under its fold. Clamp (not drop)
preserves the "there is a problem inside this collapsed region" signal.
`DiagnosticView` reaches the map through `Viewport` (§3.2), needing no separate
handle.

## 7. Caret, selection, peer presence, viewport, and motion (Q#FD16, Q#FD17, Q#FD18)

**Caret clamp (Q#FD16).** Caret grid-row (`src/editor.rs:3033-3044`): if the
logical cursor's line `is_hidden`, render at `visible_head_of(line)`'s row —
satisfying the parent's per-cursor render-time invariant (Q#FD3), including the
shared-store case.

**Local selection (Q#FD16, F2).** `paint_local_selection` (`src/editor.rs:3241`):
selection cells on hidden lines are dropped; the visible portion projects through
the map (a selection spanning a fold paints on the visible head row and the visible
tail rows, contiguous on screen).

**Peer presence (Q#FD16, F2).** `src/overlay_paint.rs:159`: a peer cursor on a
hidden line clamps to `visible_head_of`; peer selection cells on hidden lines are
dropped/projected exactly like local selection. Folds are per-buffer/shared, so the
peer's map is the same buffer's map.

**Click inverse (Q#FD16).** `activate_and_position` (`src/editor.rs:2233`): grid
row `k` maps to the `k`-th visible line, so a click never lands on a hidden line.

**Viewport / scroll (Q#FD18).** `view_top` is set only via `clamp_view_top`
(backward to the head for a hidden candidate, F1). Paging
(`move_page_down/up`), wheel (`scroll_window`), and the auto-scroll-to-cursor clamp
(`src/editor.rs:2866`) advance and bound by **visible** lines
(`next_visible`/`prev_visible`, `visible_between`). `move_to_line`/goto-line targets
a raw line; if hidden, `view_top` clamps so the target's **head** is visible (no
auto-unfold — that is the deferred search-reveal, §9). The **mode-line scroll
indicator** (`format_scroll_indicator`, `src/editor.rs:3803`) computes All/Top/Bot/%
in **visible-line** space (visible total, `view_top`'s visible ordinal, cursor's
visible ordinal). Recenter stays deferred (§2.6).

**Vertical line-motion (Q#FD17 — RULED: include).** `next-line`/`prev-line` (and
arrows) step to the adjacent **visible** line (`next_visible`/`prev_visible`), so a
collapsed region is one motion step and the cursor never rests hidden. **If motion
begins from a hidden logical cursor** (after a shared fold or a goto-line into a
fold), it **first normalizes to `visible_head_of(cursor)`**, then steps to the
preceding/following visible line. The render-time caret clamp (Q#FD16) remains the
backstop for the pre-motion shared-fold frame. These reuse the command-time map
instance (§3.2).

## 8. Interactive-Lua-command unfold widening (Q#FD19)

Widen the pre-edit unfold beyond the six `dispatch_key` primitives to the
interactive Lua commands, **local-interactive only** (never the remote/optimistic
CRDT path — parent Stage 3).

- **`apply_active_edit` funnel (yank, query-replace, and the six).** Move the
  pre-edit unfold to the **top of `apply_active_edit`** (`src/editor_core.rs:1266`),
  keyed on the active frontend's point. This subsumes the six primitives'
  individual calls (retired — one funnel) and covers yank + query-replace for free.
  `apply_active_edit` is never the remote-apply path, so this funnel is inherently
  local.
- **Interactive Lua-mutator funnel (comment-toggle, yank-pop).** Hook the **common
  `run_buffer_edit`** (`src/lua_bindings/mod.rs:1305`) — above both
  `run_managed_edit` and `run_bypass_edit`, so an interactive `bypass_intercept`
  edit does not escape (F5). Unfold **only when all** hold: (i)
  `InteractiveCommandOrigin.current()` is `Some(f)` (`src/editor.rs:53`); (ii) the
  edited buffer **is `f`'s active-window buffer** (an explicit inactive-buffer Lua
  mutation stays programmatic — no unfold); (iii) `edit.range.start` is inside a
  fold. Condition (i)+(ii) is what distinguishes an interactive command's edit at
  the point from a plugin's/data-API's programmatic edit (matching Stage 1's
  data-API exemption).
- **Excluded (Stage 3):** the remote/optimistic-CRDT apply path
  (`notify_buffer_edit`, `src/editor_core.rs:1364`). A remote peer's edit inside my
  fold must not unfold it; a GPU user's own optimistic edit is the parent's Stage 3
  obligation.
- **Undo/redo — DEFERRED (F5 ruling).** `undo`/`redo` reach
  `notify_buffer_edit_to_windows` directly; their unfold behavior is **explicitly
  deferred** (§9), not decided at implementation time.

Each widened behavior is **bite-verified** (a test failing without the widening).

## 9. Deferred (named)

- **Stage 3 (GPU):** GPU collapse, caret/hit-test fold-awareness at TUI parity, the
  `BufferSnapshot` fold-mirror clear (parent R2-4), and CRDT-origin / GPU-optimistic
  interactive unfold (parent R2-3).
- **Undo/redo unfold** (F5 ruling) — deferred.
- **Recenter** and any frontend scroll control — blocked on viewport facts; Arc 8
  adjacent (§2.6).
- **Search-reveal** — a match inside a fold auto-unfolds; parent §11 "Stage 2+";
  goto-line likewise does not auto-unfold (§7).
- **A dedicated gutter fold column** (unconditional marker) — its width recompute /
  layout change is deferred; Q#FD20 uses the conditional sign cell.
- **Fold-aware horizontal/word motion** and screen-line editing beyond vertical
  line-motion.
- **Persisted folds, `hide-level N`, auto-fold-on-open**; fold-store revalidation on
  revert/reload (parent §11; v1 still drops it).

## 10. Bets

- **B4** The per-instance visible-line map (from `folds()` + line offsets) is cheap:
  O(folds) build, reusing the render path's line table. Multiple short-lived
  instances per interaction are still O(folds) each. FALSIFIABLE on a pathological
  many-fold buffer (mitigation: derivation is O(folds), not O(lines)).
- **B5** `view_top` stays a source-line index (clamped via `clamp_view_top`) —
  less churn than a visible-ordinal coordinate space, and preserves saveplace /
  `set_view_top`.
- **B6** No wire/protocol change: `FoldState` (Stage 1) untouched; the TUI collapse
  is daemon-side; a semantic GPU session still gets `FoldState` and renders nothing
  new until Stage 3.
- **B7** Threading `Option<&'a VisibleLineMap>` on a lifetime-bearing `Viewport<'a>>`
  keeps `Viewport: Copy`. FALSIFIABLE if a `View` impl or construction site cannot
  satisfy the lifetime; fallback is to settle `Viewport` as non-`Copy` explicitly.

## 11. Acceptance — Stage 2

Tests assert on the **rendered cell grid** through a real-daemon / real-TUI grid
harness (the vterm-Stage-2 real-PTY smoke and the UX-gutter daemon-acceptance are
the precedents), sized for macOS startup + long temp-path width (handoff §5).

1. **Collapse.** Fold a region; the frame omits the hidden lines, the head shows
   text + ellipsis, rows below shift up, content row count = visible-line count.
2. **Head marker, both gutter states (F3).** With line numbers **off**: the head
   shows the ellipsis and **no gutter glyph** (width unchanged, 0). With a
   line-number mode **on**: the head shows the ellipsis **and** the gutter fold
   glyph (unless a diagnostic clamps there — then the diagnostic sign).
3. **Line numbers.** Absolute skips hidden numbers (head's number, then first
   post-fold number, no gap-fill). Relative/Hybrid distance is measured in
   **visible** lines across a fold, anchored on the visible cursor head.
4. **Diagnostic clamp (F1).** A diagnostic on a hidden line surfaces on the
   **outermost visible head** row; most-severe wins across the head and all its
   hidden lines (including a diagnostic on a *nested* inner-fold line clamping to
   the outer head).
5. **Nested-fold / shared cursor (F1).** With a fold nested inside another and the
   logical cursor on a deeply-hidden line (folded via the shared store from a
   second frontend), the caret renders on the **outermost** visible head; relative
   numbers anchor there; a `view_top` set into the nest clamps **backward** to that
   head.
6. **Caret, local selection, peer presence (F2).** Caret on a hidden line → head
   row. A local selection spanning a fold paints on the visible head + visible tail
   rows, nothing on hidden rows. A peer cursor on a hidden line clamps to the head;
   peer selection cells on hidden lines drop/project. A click never selects a hidden
   line.
7. **Ordinary overlays across a fold (F2).** A style/syntax span and a search wash
   on lines straddling a fold paint only on the visible rows, correctly aligned;
   the completion popup anchored below a fold lands on the right visible row.
8. **Viewport / paging / indicator (F2).** Page-down advances by a screenful of
   **visible** lines across a fold; `view_top` never rests hidden; a fold at the top
   clamps to its head; goto-line to a hidden line leaves its head visible; the
   mode-line indicator reports Top/Bot/% in visible-line space.
9. **Vertical motion (Q#FD17).** `next-line`/`prev-line` step across a collapsed
   region as one motion; starting from a hidden logical cursor, motion first
   normalizes to the visible head; the cursor never rests hidden.
10. **Interactive unfold widening (Q#FD19).** A **yank**, a **query-replace**
    replacement, and a **comment-toggle** whose edit point is inside a fold each
    unfold it before the edit is visible; a **bypass-intercept** interactive edit at
    the point also unfolds (proving the `run_buffer_edit` seam). A **programmatic**
    `buf:insert` — and an interactive command mutating an **inactive** buffer — do
    **not** unfold. **Undo/redo do not unfold** (deferred). Each assertion is
    **bite-verified**; the test documents CRDT-origin unfold as the Stage 3
    obligation.
11. **No wire/protocol change.** A semantic session still receives `FoldState`
    exactly as in Stage 1; the protocol version is unchanged; the GPU render path is
    untouched (the Stage-1 `FoldState` producer transitions test passes verbatim).
12. **Shared store, independent viewports.** Two TUI windows on one buffer both
    render the same fold collapsed, each with its own correct `view_top`, gutter, and
    caret.

## 12. Gates (Stage 2)

`cargo fmt --check`; `cargo clippy --workspace --all-targets -- -D warnings` (own
step); `cargo test --lib`; `cargo test --lib --features crdt`;
`tests/folding_acceptance.rs` (Stage-1 suite, stays green) + new
`tests/folding_stage2_acceptance.rs` (default + CRDT); `cargo test --test
m4_acceptance -- --skip basedpyright`; `PMACS_REQUIRE_GPU=1 cargo test -p pmacs-gpu`
(stays green — Stage 2 does not touch the GPU); the workspace sweep as one
invocation; `git diff --check`. New behavioral acceptance is bite-verified with
`scripts/bite`; timing-flaky tests are rerun isolated before treating a sweep
failure as a regression (handoff §3).

## 13. Numbered decisions (continuing the parent's Q#FD scheme)

- **Q#FD12** One shared visible-line map **primitive** (derivation + queries from
  `folds()` + line offsets), instantiated as short-lived instances per phase
  (render via `Option<&'a VisibleLineMap>` on `Viewport<'a>>` preserving `Copy`;
  after-frame direct; command-time fresh), home usable from `EditorCore`. `view_top`
  stays a source-line index, set only via `clamp_view_top`. Every consumer in the
  §2.2 census routes through it. (§3)
- **Q#FD13** Collapse in `TextView::render` (row `r` → `r`-th visible line); head
  renders content + trailing ellipsis; folding is not an overlay. (§4)
- **Q#FD14** Line numbers walk visible lines; Absolute uses raw `line+1`,
  Relative/Hybrid measure **visible**-line distance anchored on `visible_head_of`
  of the cursor; gutter width unchanged. (§5)
- **Q#FD15** A diagnostic on a hidden line clamps to `visible_head_of` (outermost
  visible head), most-severe merge; not dropped. (§6)
- **Q#FD16** Render-time clamp to `visible_head_of` for caret, local selection, and
  peer cursor on hidden lines; hidden selection cells drop/project; click inverse
  maps grid rows to visible lines. (§7)
- **Q#FD17** *(ruled: include)* Vertical line-motion steps by visible lines; motion
  from a hidden cursor first normalizes to the visible head. (§7)
- **Q#FD18** Viewport/paging/auto-scroll/indicator reckon in visible lines;
  `view_top` set via `clamp_view_top` (backward to the head); goto-line leaves a
  hidden target's head visible; recenter deferred. (§7)
- **Q#FD19** Interactive-unfold widening hooks **local** funnels only:
  `apply_active_edit` (top; subsumes the six; covers yank + query-replace) and the
  common `run_buffer_edit` gated on `InteractiveCommandOrigin.current()` **and**
  the edit targeting the invoking frontend's active-window buffer **and**
  `edit.range.start` inside a fold; the remote/optimistic-CRDT `notify_buffer_edit`
  path is excluded (Stage 3); **undo/redo unfold is deferred**. (§8)
- **Q#FD20** Fold gutter glyph is **conditional on a gutter existing**: off ⇒
  ellipsis only; on ⇒ col-0 sign cell on the head row with diagnostic priority. A
  dedicated fold column (unconditional marker + layout change) is deferred. (§5)

## 14. Branch and PR plan

Branch **`folding-tui`**, worktree `../pmacs-folding-tui`, off canonical `main` @
`c49a8c7` (folding Stage 1 / #142 merged). This framing is the opening commits (rev
1 → rev 2); Stage 2 implements on this same branch and opens as the second folding
PR. One feature, one branch, one PR — Stage 3 (GPU) is a separate branch/PR off the
resulting main.

Housekeeping from #142 (retire the `docs/active-work.md` folding lane + refresh
`docs/agent-handoff.md` §1) is a **separate docs PR**, kept out of `folding-tui`
(ruled).