From 5f7270d26a8e06770564dcaf2dbb5f822f9c35e6 Mon Sep 17 00:00:00 2001 From: Levi Neuwirth Date: Thu, 23 Jul 2026 16:19:59 -0400 Subject: [PATCH 1/2] docs: record folding Stage 1 (#142) landing; open Stage 2 lane MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Post-merge housekeeping owed from #142, kept as its own docs PR (no runtime code). - agent-handoff.md §1: bump main to c49a8c7, add the folding Stage 1 substrate bullet (store/View, structural source, C-c @ surface, command-path unfold, FoldState production; no protocol bump), refresh the "Last updated" line and the roadmap Arc 6 entry, and note Stage 2 is in framing on folding-tui (the visible-line-map reframe). - active-work.md: retire the Stage 1 folding lane (PR #142 was OPEN), add a "Closed since the last snapshot" entry for #142, open the Stage 2 (grid/daemon collapse) framing lane on folding-tui, and refresh the canonical base snapshot to c49a8c7. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01Q5BkezMppbpCgGAYk2ftxV --- docs/active-work.md | 73 +++++++++++++++++++++++++------------------ docs/agent-handoff.md | 69 +++++++++++++++++++++++++++++++++------- 2 files changed, 100 insertions(+), 42 deletions(-) diff --git a/docs/active-work.md b/docs/active-work.md index 2f1e82a..0cd719c 100644 --- a/docs/active-work.md +++ b/docs/active-work.md @@ -14,8 +14,8 @@ 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` @ `c49a8c7` (folding Stage 1 #142 atop one-command GPU + invocation #141 and documentation refresh #140; 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 +49,41 @@ git worktree list git status --short --branch ``` -The first command must expose `63fbc66` or a newer intentional main. +The first command must expose `c49a8c7` or a newer intentional main. If it does not, stop and repair the remote/fetch configuration. -## Folding framing lane (Arc 6) +## Folding Stage 2 framing lane (Arc 6) -- 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: canonical `main` @ `c49a8c7` (folding Stage 1 / #142 merged). +- Framing head: `docs/folding-stage2-framing.md` (rev 1 → rev 2; rev 2 + absorbs review round 1's five findings + two rulings). Numbering continues + the parent `Q#FD` scheme from `Q#FD12`. +- State: **framing only, rev 2, under review; no implementation, no PR.** + Load-bearing reframe (Q#FD12): the TUI has no non-identity + source-line↔display-row map today (`view_top + row` is baked into ~13 + sites), so Stage 2's spine is one shared visible-line-map primitive that + every consumer routes through. Correction to the parent premise (Q#FD19): + yank + query-replace are `apply_active_edit` callers (local), not + Lua-mutator callers; only comment-toggle/yank-pop take the Lua path + (shared with the remote/optimistic-CRDT apply deferred to Stage 3). No + wire schema or protocol change — `FoldState` production (Stage 1) is + untouched; the GPU render path is Stage 3. +- Next: land the remaining review rounds → implement Stage 2 on this branch + → PR. 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 +122,19 @@ git worktree add --track \ ## Closed since the last snapshot +- **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 continues 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). diff --git a/docs/agent-handoff.md b/docs/agent-handoff.md index bc8163c..71907cd 100644 --- a/docs/agent-handoff.md +++ b/docs/agent-handoff.md @@ -1,11 +1,11 @@ # 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 folding Stage 1 (#142, the headless fold +engine) landed, following 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 +19,52 @@ 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` @ `c49a8c7` (folding Stage 1 #142 atop one-command GPU invocation + #141 and documentation refresh #140), 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>, 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 in framing** on `folding-tui` + (`docs/folding-stage2-framing.md`, rev 2). Its load-bearing reframe: the + TUI has **no non-identity source-line↔display-row map** today (`view_top + + row` is baked into ~13 sites), so Stage 2's spine is one shared + visible-line-map primitive 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. + 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 +464,12 @@ 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 in framing on + `folding-tui`; Stage 3 (GPU) follows. + - 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) From f16d72fded019fd8734d22af2e447302146da61c Mon Sep 17 00:00:00 2001 From: Levi Neuwirth Date: Thu, 23 Jul 2026 21:58:02 -0400 Subject: [PATCH 2/2] docs: refresh the ledger to current main and Stage 2's real state MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR #149 review round 5 flagged this PR as stale: it still claimed `main` @ `c49a8c7`, Stage 2 framing "rev 2, under review; no implementation, no PR", while `main` is `47581f4` and Stage 2 is implemented and open. - Base snapshot and the recovery check bump `c49a8c7` -> `47581f4`. - The folding Stage 2 lane becomes IMPLEMENTED / PR #149 OPEN: framing rev 4 approved, the `VisibleLineMap` spine, the base-moved merge (and why it was merged rather than rebased), and the five review rounds' design-changing findings — each of which is a trap Stage 3 inherits. - `main`'s ledger had gone unrefreshed through four merges, not one, so "Closed since the last snapshot" now also records web grammars HTML + CSS (#146) and LaTeX Stage 1 (#144) with its inline-math framing (#145), including their durable lessons. - agent-handoff §1: `main` @ `47581f4`, the "Last updated" line, the Stage 2 substrate bullet, and the roadmap entry. Rebased onto `47581f4` so it stays one documentation-only commit directly off canonical main. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01Q5BkezMppbpCgGAYk2ftxV --- docs/active-work.md | 77 ++++++++++++++++++++++++++++++------------- docs/agent-handoff.md | 55 +++++++++++++++++++++---------- 2 files changed, 93 insertions(+), 39 deletions(-) diff --git a/docs/active-work.md b/docs/active-work.md index 0cd719c..ac661be 100644 --- a/docs/active-work.md +++ b/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` @ `c49a8c7` (folding Stage 1 #142 atop one-command GPU - invocation #141 and 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,33 +50,46 @@ git worktree list git status --short --branch ``` -The first command must expose `c49a8c7` 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 Stage 2 framing lane (Arc 6) +## Folding Stage 2 lane (Arc 6) — IMPLEMENTED, PR #149 OPEN 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: canonical `main` @ `c49a8c7` (folding Stage 1 / #142 merged). -- Framing head: `docs/folding-stage2-framing.md` (rev 1 → rev 2; rev 2 - absorbs review round 1's five findings + two rulings). Numbering continues - the parent `Q#FD` scheme from `Q#FD12`. -- State: **framing only, rev 2, under review; no implementation, no PR.** - Load-bearing reframe (Q#FD12): the TUI has no non-identity - source-line↔display-row map today (`view_top + row` is baked into ~13 - sites), so Stage 2's spine is one shared visible-line-map primitive that - every consumer routes through. Correction to the parent premise (Q#FD19): - yank + query-replace are `apply_active_edit` callers (local), not - Lua-mutator callers; only comment-toggle/yank-pop take the Lua path - (shared with the remote/optimistic-CRDT apply deferred to Stage 3). No - wire schema or protocol change — `FoldState` production (Stage 1) is +- 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. -- Next: land the remaining review rounds → implement Stage 2 on this branch - → PR. Stage 3 (GPU) is a separate branch/PR off the resulting main, - re-framed in detail after Stage 2 lands. +- 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: @@ -122,6 +136,24 @@ 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 `