Merge pull request #147 from levineuwirth/docs-folding-stage1-landed

docs: record folding Stage 1 (#142) landing; open Stage 2 lane

docs/active-work.md

@@ -14,8 +14,9 @@ backlog.
   machine-local: `origin` may name this canonical URL, a release mirror,
   or something else, and therefore has no authority by name alone.
 - Canonical base at this snapshot:
-  `githubsucks/main` @ `63fbc66` (one-command GPU invocation #141 atop
-  documentation refresh #140; protocol v19).
+  `githubsucks/main` @ `47581f4` (web grammars HTML+CSS #146 atop the LaTeX
+  Stage 1 #144 / inline-math framing #145 pair and folding Stage 1 #142;
+  protocol v19).
 - On the transfer source, `origin/main` named a release mirror at
   `d3fa632` and lagged badly. On the current destination, `origin` names
   the canonical URL. This difference is why all recovery begins by
@@ -49,43 +50,54 @@ git worktree list
 git status --short --branch
 ```
 
-The first command must expose `63fbc66` or a newer intentional main.
+The first command must expose `47581f4` or a newer intentional main.
 If it does not, stop and repair the remote/fetch configuration.
 
-## Folding framing lane (Arc 6)
+## Folding Stage 2 lane (Arc 6) — IMPLEMENTED, PR #149 OPEN
 
-- Portable branch: `githubsucks/folding`; worktree `../pmacs-folding`.
-- Base: **rebased onto canonical `main` @ `96d0bae`** at implementation
-  start (was `cac4961`; the earlier base fell behind the docs + tab-width
-  housekeeping).
-- Framing head: revision 5 of `docs/folding-framing.md` (rev 1 → … → rev 4
-  absorbed three review rounds; rev 5 records approval + the Q#FD4 binding
-  decision).
-- State: **Stage 1 (fold engine, headless) implemented; PR #142 OPEN**,
-  two review rounds landed on the branch. Bindings decided (Q#FD4 → Emacs
-  hideshow `C-c @` set); Bet B1 accepted as framed.
-  Load-bearing decision (Q#FD1): the bundled grammars ship no fold query and
-  no `folds.scm`, so the roadmap's "tree-sitter fold ranges" is not free; v1
-  is structural node folding (block-like node ≥2 source lines, derived head
-  line, closer-aware tail), with indentation fallback and curated queries
-  deferred. `FoldState` already exists in the protocol; Stage 1 starts
-  *producing* it (authoritative-empty), no protocol bump; gutter markers are
-  frontend-derived like the diagnostic sign bars, so no new wire type. Staged
-  like vterm: Stage 1 engine (headless), Stage 2 TUI, Stage 3 GPU.
-- PR: **#142** (`Arc 6 folding — Stage 1: instance fold engine`), open
-  against `main`. Round 1 (tail-boundary delete bug + buffer-kill cleanup +
-  close-all point-move) and round 2 (pin the kill-path + close-all through
-  the real command surface) are landed as fix commits on the branch.
-- Next: land Stage 1; Stages 2/3 are separate branches/PRs, each re-framed
-  in detail after the prior stage lands.
+Stage 1 (the headless fold engine) is MERGED as **#142** (see "Closed since
+the last snapshot"); this lane carries the Stage 2 (grid/daemon collapse)
+work off the resulting main.
+
+- Portable branch: `githubsucks/folding-tui`; worktree `../pmacs-folding-tui`.
+- Base: originally canonical `main` @ `c49a8c7`; `main` moved to `47581f4`
+  (#146) during the arc, so the branch carries a **merge** of it. The merge
+  is textually clean but was NOT semantically clean — #146 added three new
+  `Viewport` literals to `src/highlight.rs`'s unit tests and Stage 2 gives
+  `Viewport` a `folds` field — so the carry-over is resolved in the merge
+  commit. Merged rather than rebased so the four framing revisions the
+  review rounds cite by SHA stay reachable.
+- Framing head: `docs/folding-stage2-framing.md` **rev 4, APPROVED**
+  (`4222ffa`; rev 1 → 4 absorb review rounds 1–3). Numbering continues the
+  parent `Q#FD` scheme from `Q#FD12`.
+- State: **implemented; PR #149 OPEN, five review rounds so far, awaiting
+  the merge word.** The spine (Q#FD12) is `src/fold_view.rs`'s
+  `VisibleLineMap`, derived per rendered window and per command/event
+  operation and never stored; fold projection is per-frontend
+  (`FrontendView.fold_projection`, Q#FD21). 48 acceptance tests in
+  `tests/folding_stage2_acceptance.rs`, each asserting on the real
+  `paint_frame` cell grid; every behavioral claim bite-verified. No wire
+  schema or protocol change — `FoldState` production (Stage 1) is
+  untouched; the GPU render path is Stage 3.
+- Review findings that changed the design, worth carrying forward: fold
+  projection must be per-frontend or a simultaneous unfolded GPU session's
+  cursor skips lines it displays (round 2); maps are per-window, and a
+  command's map follows the operation's TARGET window, not the active one
+  (rounds 2–3); crossing folds need merged hidden components, not
+  "outermost containing fold" (round 3); hidden-cursor motion must project
+  the whole POSITION and `set_view_top` must clamp in the setter (round 4);
+  the Lua widening must key on the **post-intercept** edit site, since a
+  managed intercept may relocate the op (round 5).
+- Next: remaining review rounds → merge word. Stage 3 (GPU) is a separate
+  branch/PR off the resulting main, re-framed in detail after Stage 2 lands.
 
 Recovery worktree:
 
 ```sh
 git worktree add --track \
-  -b folding \
-  ../pmacs-folding \
-  githubsucks/folding
+  -b folding-tui \
+  ../pmacs-folding-tui \
+  githubsucks/folding-tui
 ```
 
 ## Parked lane: kill-ring browser + persistence
@@ -124,6 +136,38 @@ git worktree add --track \
 
 ## Closed since the last snapshot
 
+- **Web grammars HTML + CSS — MERGED as #146** (`main` @ `47581f4`,
+  2026-07-23). `.html/.htm/.xhtml` and `.css` highlight off the official
+  `tree-sitter-html` 0.23 / `tree-sitter-css` 0.25 crate query constants (no
+  in-repo overlay), and HTML's `INJECTIONS_QUERY` lights up `<script>` → js
+  and `<style>` → css. Durable lesson recorded in
+  `docs/web-grammars-html-css-framing.md`: the `highlight.rs` capture table
+  is **global**, so adding a capture name retro-paints every other language —
+  check the reverse direction and pin it.
+
+- **LaTeX Stage 1 — MERGED as #144**, with its parent inline-math framing
+  committed as **#145** (`main` @ `f09b0a1`, 2026-07-23).
+  `.tex/.latex/.sty/.cls` highlight via `codebook-tree-sitter-latex` 0.6 plus
+  the first in-repo query overlay (`builtin/queries/latex/highlights.scm`,
+  `include_str!`) — the reusable pattern for grammars whose crate ships no
+  usable queries. The crates.io `tree-sitter-latex` is provably broken (no
+  `scanner.c`). The math parser and Tiers 3–4 are deferred to the inline-math
+  arc.
+
+- **Folding Stage 1 (headless fold engine) — MERGED as #142** (`main` @
+  `c49a8c7`, 2026-07-23, after three review rounds; round 3 clean). The
+  instance-side fold store + translating/dropping `View`, the structural
+  source (derived head line, closer-aware tail), the Lua data API +
+  interactive `C-c @` commands, the command-path pre-edit unfold, and
+  authoritative-empty `FoldState` production landed with no protocol bump.
+  The `folding` branch and worktree (`../pmacs-folding`) are retained but
+  carry nothing unmerged; the `folding-framing.md` framing is preserved.
+  CI red at merge was an unrelated environmental perf flake
+  (`outline_5_level_100_entry_renders_within_100ms`, macOS/luajit only),
+  green on rerun. Stage 2 is implemented and open as **PR #149** on
+  `folding-tui` (see the lane above); durable substrate seams live in
+  `docs/agent-handoff.md` §1.
+
 - **Vterm Stage 3 (protocol v19 + GPU terminal) — MERGED as #135** (`main`
   @ `cac4961`, 2026-07-22, after two review rounds). Arc 5's terminal stage
   is complete (compile mode #113, Stage 1 #126, Stage 2 #130, Stage 3 #135).

docs/agent-handoff.md

@@ -1,11 +1,12 @@
 # Agent handoff — cross-machine continuity
 
-**Last updated: 2026-07-23, after one-command GPU invocation (#141) landed,
-following the documentation refresh (#140), Vterm Stage 3 (#135, protocol v19
-and native GPU terminal), tab-width rendering parity (#137), locals-query
-processing (#134), modeline detection (#132), mode system wiring (#129),
-config registry (#127), Vterm Stages 1–2 (#126/#130), and completed Themes
-Arc 4 (#120/#124/#125).**
+**Last updated: 2026-07-23, after web grammars HTML+CSS (#146) landed,
+following the LaTeX Stage 1 / inline-math framing pair (#144/#145), folding
+Stage 1 (#142, the headless fold engine), one-command GPU invocation (#141), the
+documentation refresh (#140), Vterm Stage 3 (#135, protocol v19 and native GPU terminal),
+tab-width rendering parity (#137), locals-query processing (#134), modeline
+detection (#132), mode system wiring (#129), config registry (#127), Vterm
+Stages 1–2 (#126/#130), and completed Themes Arc 4 (#120/#124/#125).**
 This file is the
 bridge between development machines. If you are an agent reading
 this on a fresh clone: this document plus the `docs/*-framing.md`
@@ -19,9 +20,70 @@ commands, read `docs/active-work.md` immediately after this file.
 
 ## 1. Where the project stands (2026-07-23)
 
-- `main` @ `63fbc66` (one-command GPU invocation #141 atop documentation
-  refresh #140), protocol **v19** (`SUPPORTED=[6..=19]`; v16 = `ThemeFacts`,
-  v17 = `FontFacts`, v18 = `StatuslineSegments`, v19 = terminal frames/events).
+- `main` @ `47581f4` (web grammars HTML+CSS #146 atop LaTeX Stage 1 #144 /
+  inline-math framing #145 and folding Stage 1 #142), protocol **v19**
+  (`SUPPORTED=[6..=19]`; v16 = `ThemeFacts`, v17 = `FontFacts`, v18 =
+  `StatuslineSegments`, v19 = terminal frames/events).
+- **Folding Stage 1 (headless fold engine) LANDED — #142**
+  (`docs/folding-framing.md` rev 5; merge `c49a8c7`; three review rounds,
+  round 3 clean). Arc 6's engine — instance-side and headless; **no frontend
+  renders a collapse yet** (that is Stage 2). No protocol bump.
+  - `src/fold.rs`: a per-buffer `FoldStore` of byte ranges attached as a
+    translating/dropping `View` (the `BufferStyleSpanTranslator` pattern — it
+    translates strictly-inside edits and DROPS boundary-crossers,
+    provenance-blind); `FoldRegistry`/`SharedFoldRegistry` =
+    `Rc<RefCell<HashMap<BufferId, {Arc<Mutex<FoldStore>>, ViewId}>>>` (the
+    SyntaxRegistry per-buffer model), held on both `EditorCore`
+    (`src/editor_core.rs:223`) and `EditorState` (`src/editor.rs:110`).
+    Containment is **start-exclusive, end-inclusive `(start, end]`**; the
+    stored range is `[end of head line, end of last hidden line]` (NOT the
+    `ByteRange` struct doc's `[start,end)`).
+  - Structural source: nearest enclosing block-like node ≥2 source lines →
+    resolve introducer↔body → **derived head line** (the line immediately
+    above the first hidden line, so wrapped signatures / `where` clauses stay
+    visible) → **closer-aware tail** (a closing-delimiter line stays visible,
+    e.g. `} else {`). Stale/absent parse tree refuses.
+  - The six `EditorCore` edit primitives call `unfold_before_point_edit`
+    first (command-path pre-edit unfold, keyed on the active frontend's
+    point). Interactive Lua-command unfold (yank/query-replace/comment) is a
+    Stage 2 obligation; CRDT-origin unfold is Stage 3.
+  - `src/lua_bindings/fold.rs` (`install_fold`): `pmacs.fold.*` data API
+    (explicit buffer, no ambient resolution, matching #127) + interactive
+    commands on the **Emacs hideshow `C-c @` prefix set**;
+    `builtin/runtime/fold.lua`.
+  - `src/semantic_render.rs`: `fold_state_msg` PRODUCES `FoldState`
+    (semantic/GPU sessions) — authoritative-empty, diff-suppressed, per-session
+    baseline reset on `BufferSnapshot` (the #120 stale-mirror trap class; the
+    GPU fold-mirror clear-on-snapshot is a named Stage 3 obligation).
+  - Durable lesson (round 2): after wiring a cleanup into a production hook,
+    PIN IT THROUGH THE REAL PATH — a direct-call unit test misses the wiring
+    (falsify by revert).
+  - **Stage 2 (grid/daemon collapse) is IMPLEMENTED — PR #149 OPEN** on
+    `folding-tui` (`docs/folding-stage2-framing.md` rev 4, approved). Its
+    load-bearing reframe: the TUI had **no non-identity
+    source-line↔display-row map** (`view_top + row` was baked into ~13 sites),
+    so Stage 2's spine is `src/fold_view.rs`'s `VisibleLineMap` — derived from
+    the fold store plus a window's line offsets, never stored — that the render
+    loop, gutter, diagnostics, caret, selection, peer presence,
+    viewport/scroll/motion, and the mode-line indicator all route through, plus
+    the interactive-Lua unfold widening. Threaded as `Option<&'a
+    VisibleLineMap>` on a lifetime-bearing `Viewport<'a>` that stays `Copy`.
+    Design points the review rounds forced, each a trap for Stage 3:
+    - the map's unit is a **merged hidden component** (overlapping *or
+      adjacent* intervals unioned, keeping the earliest visible head), not a
+      fold — folds may cross, and an inner/later fold's own head can be hidden;
+    - instances are **per rendered window** and **per command/event
+      operation**, never per frame; a command's map follows the operation's
+      TARGET window (a wheel event names a pane without activating it);
+    - fold projection is **per-frontend** (`FrontendView.fold_projection`, set
+      at attach from the negotiated `semantic_render` bit) — shared
+      `EditorCore` motion would otherwise make a simultaneous unfolded GPU
+      session's cursor skip lines it still displays;
+    - a hidden cursor normalizes by **position**, not row, and `set_view_top`
+      clamps in the setter rather than being repaired at render time;
+    - the interactive-Lua unfold keys on the **post-intercept** edit site — a
+      managed buffer intercept may legally relocate the op.
+    No protocol bump. Stage 3 (GPU) follows.
 - **One-command GPU invocation LANDED — #141**
   (`docs/gpu-invocation-framing.md` rev 6; merge `63fbc66`; two implementation
   reviews). The additive public path is `pmacs --gpu [--socket NAME|PATH]`;
@@ -421,8 +483,14 @@ commands, read `docs/active-work.md` immediately after this file.
     lexical resolution, settled per-layer facts, shared TUI/GPU
     local-predicate filtering, and a registry-wide locals-query invariant
     shipped without a protocol change.
-  - Remaining ranked arcs: 6 folding, 7 DAP, 8 GPU splits, plus the
-    `.ipynb` arc (its JSON-grammar prerequisite shipped in #123).
+  - **Arc 6 (folding) Stage 1 LANDED — #142** — the headless fold engine
+    (store, structural source, Lua `C-c @` surface, command-path unfold,
+    `FoldState` production). Stage 2 (grid/daemon collapse) is implemented and
+    open as **PR #149** on `folding-tui`; Stage 3 (GPU) follows.
+  - **Web grammars HTML+CSS LANDED — #146**, and **LaTeX Stage 1 — #144**
+    with its inline-math parent framing **#145**.
+  - Remaining ranked arcs: 6 folding Stages 2–3, 7 DAP, 8 GPU splits, plus
+    the `.ipynb` arc (its JSON-grammar prerequisite shipped in #123).
 
 ## 2. How we work (the part that must not drift)