Merge pull request #38 from levineuwirth/worktree-gpu-design-framing
docs: pmacs-gpu design note (framing pass closed)
This commit is contained in:
GitHub
commit
f7cea2ec3a
|
|
@ -0,0 +1,366 @@
|
||||||
|
# pmacs-gpu — design note
|
||||||
|
|
||||||
|
**Status: framing pass closed; pre-implementation.** Sessions queued:
|
||||||
|
session 1 = `pmacs-protocol` crate extraction; session 2 = `pmacs-gpu`
|
||||||
|
workspace setup + hello-world rendering; session 3+ = Phase A proper.
|
||||||
|
|
||||||
|
This is the post-v1.0 design artifact for the GPU/GUI frontend. It
|
||||||
|
inherits the contract boundary established by
|
||||||
|
[`semantic-frontend-protocol.md`](semantic-frontend-protocol.md) and
|
||||||
|
applies the M10-matured framing discipline (verification-milestone
|
||||||
|
premise-check, predictive-density, categorical scoring, per-phase audit
|
||||||
|
docs) to a multi-month effort.
|
||||||
|
|
||||||
|
## Why this exists
|
||||||
|
|
||||||
|
The M11 producer arc shipped without a real consumer. Everything we've
|
||||||
|
built — `StyleSpans` (policy A, tree-sitter + LSP), `Decorations`
|
||||||
|
(diagnostics + selection), `InlineAdornments` (inlay hints),
|
||||||
|
`FileStyleSummary` (minimap), `CursorByte` — is a *hypothesis about
|
||||||
|
wire shape* until something renders against it. `pmacs-gpu` is that
|
||||||
|
consumer. Phase A's adversarial verification of the producer arc is its
|
||||||
|
load-bearing job; the "read-only viewer that renders text" is a side
|
||||||
|
effect of validating the wire.
|
||||||
|
|
||||||
|
This framing is the most consequential commitment in the note. Phase A
|
||||||
|
is **not** "build a viewer that works" — it is "exercise every field of
|
||||||
|
every producer-arc message in conditions that would surface shape
|
||||||
|
issues, and ship a viewer as the artifact of having done so."
|
||||||
|
|
||||||
|
## Contract inheritance
|
||||||
|
|
||||||
|
From `semantic-frontend-protocol.md`'s "Contract boundary" section,
|
||||||
|
verbatim: *the instance never learns a pixel.* Not viewport pixel size,
|
||||||
|
not DPI, not font metrics, not glyph advances. The only spatial fact
|
||||||
|
the instance learns is which buffer byte range is on screen
|
||||||
|
(`FrontendEvent::Viewport`).
|
||||||
|
|
||||||
|
Corollary, also from the doc: *there is no hit-test round trip.* The
|
||||||
|
frontend resolves pixel→offset locally and only ever emits buffer
|
||||||
|
offsets and edits. `pmacs-gpu` ships sophisticated client logic
|
||||||
|
specifically to honor this; if a render path would require the
|
||||||
|
instance to learn pixels, the verification-milestone premise-check
|
||||||
|
classifies that as a load-bearing finding (see [Finding feedback
|
||||||
|
loop](#finding-feedback-loop) below).
|
||||||
|
|
||||||
|
## Toolkit
|
||||||
|
|
||||||
|
**`wgpu` + custom + `cosmic-text` + `glyphon`. Unambiguous.**
|
||||||
|
|
||||||
|
### Against `gpui`
|
||||||
|
|
||||||
|
The `gpui` option is more attractive than it should be and worth
|
||||||
|
recording an unambiguous against-paragraph so this decision isn't
|
||||||
|
relitigated:
|
||||||
|
|
||||||
|
`gpui` is built around Zed's editor model — a specific text-buffer
|
||||||
|
abstraction, a specific event-loop shape, a specific approach to
|
||||||
|
composing editor UI. Pmacs's model differs in load-bearing ways:
|
||||||
|
CRDT-backed buffers, attach-protocol-driven rendering, Lua-extensible
|
||||||
|
behavior, daemon-frontend split. Each difference means either reshaping
|
||||||
|
pmacs to fit `gpui` (foreign architecture imposed on mature pmacs
|
||||||
|
design) or reshaping `gpui` to fit pmacs (rewriting parts of a
|
||||||
|
framework we don't control). Vendoring forks an upstream we'd have to
|
||||||
|
track; depending pins us to Zed's release cadence and refactors. Six
|
||||||
|
months of head-start cost the next five years of upgrade friction.
|
||||||
|
|
||||||
|
The `wgpu` + custom path has the property that every line of code in
|
||||||
|
the frontend is ours. The "biggest work item: text rendering" is real
|
||||||
|
but bounded — `cosmic-text + glyphon` resolve most of it. The
|
||||||
|
foreign-API surface to misread (the M10.10 library-API-verification
|
||||||
|
lesson) is far smaller than `gpui`'s.
|
||||||
|
|
||||||
|
### Why not the alternatives
|
||||||
|
|
||||||
|
- `iced` / `egui` — general-purpose Rust GUI; neither editor-shaped.
|
||||||
|
Immediate-mode (egui) fights long-running editor model.
|
||||||
|
- Tauri / web stack — loses the "pmacs is a real native binary"
|
||||||
|
character; adds JS runtime story.
|
||||||
|
- GTK or other native widget toolkits — not GPU-first, loses the
|
||||||
|
framing.
|
||||||
|
|
||||||
|
## Scope phases
|
||||||
|
|
||||||
|
Sequential, not alternative. Recording the total honestly at
|
||||||
|
decision-time so future-us doesn't relitigate the timeline:
|
||||||
|
|
||||||
|
| Phase | Deliverable | Duration |
|
||||||
|
|---|---|---|
|
||||||
|
| **A** | Adversarial verification of the producer arc, artifact = read-only viewer | 2–3 weeks |
|
||||||
|
| **B** | Editing parity with TUI | 2–3 months after A |
|
||||||
|
| **C** | Beyond-TUI features (smooth scroll, real inline inlay hints, minimap consumption) | 3–4 months after B |
|
||||||
|
|
||||||
|
Total path: ~6 months to TUI parity, ~9–10 months to beyond-TUI. v0.1
|
||||||
|
of `pmacs-gpu` is the end of Phase A.
|
||||||
|
|
||||||
|
## Phase A: adversarial verification
|
||||||
|
|
||||||
|
### Scope framing
|
||||||
|
|
||||||
|
Phase A's success criterion is *not* "renders correctly." It is
|
||||||
|
"exercises every field of every producer-arc message in conditions
|
||||||
|
that would surface shape issues." The choice of what to render is
|
||||||
|
driven by what the producer arc needs validated, not by what looks
|
||||||
|
good in a demo.
|
||||||
|
|
||||||
|
### Test corpus
|
||||||
|
|
||||||
|
Six static probes + one temporal probe. Each is a planned exercise of
|
||||||
|
a specific wire surface, not an open-file-and-see-what-happens session.
|
||||||
|
|
||||||
|
| # | Probe | Wire surface exercised |
|
||||||
|
|---|---|---|
|
||||||
|
| 1 | Non-ASCII source (mixed CJK / emoji / combining marks) | UTF-16 col/byte conversion edge cases in `StyleSpans` LSP path; `char_to_byte` correctness across encodings |
|
||||||
|
| 2 | Mixed tree-sitter + LSP file (Rust with rust-analyzer) | The M_B3 composition path — `merge_styles` behavior when both authorities cover the same byte |
|
||||||
|
| 3 | Viewport-boundary tokens (token straddles the visible region's edge) | `StyleSpans`/`Decorations` dirty-segment edges; M11.4 clip behavior |
|
||||||
|
| 4 | 100k-line file | `FileStyleSummary` at scale; per-line dominant-style accuracy; minimap-style consumption |
|
||||||
|
| 5 | Active diagnostics + multi-frontend `PresenceUpdate` overlap | `Decorations` ↔ `PresenceUpdate` composition; peer-cursor SO_PEERCRED color stability |
|
||||||
|
| 6 | `\r\n` line endings | `line_offsets` convention; trailing-newline assumptions across producers |
|
||||||
|
| 7 | **Sustained typing** (1000 keystrokes in 30s synthetic) | Temporal probe — `CursorByte` emission cadence; `InlineAdornments` suppression timing; dirty-segment propagation under fast edits |
|
||||||
|
|
||||||
|
The temporal probe is structurally different from the six static
|
||||||
|
probes. State-shape probes test "does the wire carry the right thing";
|
||||||
|
the temporal probe tests "do the wire shapes hold under sustained
|
||||||
|
interaction." Predict 1–2 additional findings from the temporal surface
|
||||||
|
beyond the categorical bets below.
|
||||||
|
|
||||||
|
### Predicted findings — categorical bets
|
||||||
|
|
||||||
|
Five named bets, each probing a categorically different failure surface:
|
||||||
|
|
||||||
|
| # | Bet | Category |
|
||||||
|
|---|---|---|
|
||||||
|
| 1 | `StyleSpans`/`Decorations` dirty-segment edges at viewport boundaries | Headless-test-blind-spot probe |
|
||||||
|
| 2 | `InlineAdornments` M11.2-level suppression visible-flicker on edit-then-revert | Temporal-interaction probe |
|
||||||
|
| 3 | `FileStyleSummary` trailing-empty-line behavior may need wire decision | Convention-vs-contract probe |
|
||||||
|
| 4 | `CursorByte` per-tick cadence may surface as wrong frequency for a 60fps consumer | Producer-frequency-vs-consumer-need probe |
|
||||||
|
| 5 | `PresenceUpdate` peer-cursor color stability may need `M10.9` SO_PEERCRED discipline ported into the renderer, not re-derived | State-derivation-location probe |
|
||||||
|
|
||||||
|
### Scoring methodology (committed before data lands)
|
||||||
|
|
||||||
|
The predicted-vs-actual score at Phase A's close is a **category
|
||||||
|
matrix, not a count**. This is the M10.10 dual-methodology-scorecard
|
||||||
|
discipline applied here: different measurements capture different
|
||||||
|
signals; report them separately rather than collapse to one number.
|
||||||
|
|
||||||
|
At Phase A close, report:
|
||||||
|
|
||||||
|
- **Predicted categories that surfaced** (true positives): which of
|
||||||
|
the five bets above produced findings.
|
||||||
|
- **Predicted categories that didn't surface** (false positives):
|
||||||
|
bets that turned out not to be load-bearing.
|
||||||
|
- **Unpredicted categories that surfaced** (false negatives): genuine
|
||||||
|
gaps the model missed entirely.
|
||||||
|
- **Count distribution within each category**: how many findings of
|
||||||
|
each category appeared.
|
||||||
|
|
||||||
|
The model is right about *structure* if predicted categories surface
|
||||||
|
even at low count; it is right about *distribution* only if the count
|
||||||
|
within each category roughly matches the prediction. A score of "4/5
|
||||||
|
predicted categories surfaced; 2 unpredicted categories surfaced; one
|
||||||
|
predicted category produced 3 findings" is a structurally right but
|
||||||
|
distributively wrong prediction.
|
||||||
|
|
||||||
|
This methodology is recorded **before** data lands to prevent the
|
||||||
|
M10.10 Day-5 reconciliation trap where scoring criteria get decided
|
||||||
|
after results are known.
|
||||||
|
|
||||||
|
### Finding feedback loop
|
||||||
|
|
||||||
|
Classification rule (iii) — pre-authorized at framing time, not
|
||||||
|
discovered mid-implementation:
|
||||||
|
|
||||||
|
- **Small finding** (≈ half-day patch, no structural change, no
|
||||||
|
contract violation): absorb into Phase A. Patch the producer arc,
|
||||||
|
re-verify, continue.
|
||||||
|
- **Structural finding** (changes a contract, ripples across producers
|
||||||
|
or consumers, invalidates a v1.0 assumption, or breaks the
|
||||||
|
pixel-pure-instance invariant): apply the
|
||||||
|
verification-milestone-premise-check. Defer to a numbered v0.x.
|
||||||
|
Phase A ships with the limitation documented; the structural work
|
||||||
|
becomes its own scoped milestone.
|
||||||
|
|
||||||
|
Classification happens *at surface-time*, not at Phase A's close.
|
||||||
|
Phase A's framing pre-authorizes both branches; neither blocks the
|
||||||
|
other. The audit doc for Phase A records each finding with its
|
||||||
|
classification and the resolution path taken.
|
||||||
|
|
||||||
|
## Distribution
|
||||||
|
|
||||||
|
**Workspace member: separate `pmacs-gpu` binary.** Single binary with a
|
||||||
|
flag would force `wgpu` runtime deps (vulkan/metal/dx12) and font
|
||||||
|
handling into every TUI install. Separate repo would sever the audit
|
||||||
|
trail and require cross-repo coordination for protocol changes.
|
||||||
|
Workspace + separate binary is the right shape: shared protocol crate,
|
||||||
|
independent dep graphs, single audit history.
|
||||||
|
|
||||||
|
### Protocol-crate extraction (prerequisite)
|
||||||
|
|
||||||
|
`src/protocol.rs` is currently inlined in the main `pmacs` crate. The
|
||||||
|
extraction is **a discrete prerequisite PR**, not folded into "workspace
|
||||||
|
setup":
|
||||||
|
|
||||||
|
1. Extract `pmacs-protocol` as a workspace crate.
|
||||||
|
2. Move wire types (`InstanceMessage`, `FrontendEvent`, capability
|
||||||
|
structs, `NegotiatedCapabilities`, `BufferId`, `FrontendId`, the
|
||||||
|
`SemanticFrame` family, `SelectionSnapshot`, `ResourceBody`, etc.).
|
||||||
|
3. Leave internal types (serialization wrappers, dispatch utilities,
|
||||||
|
format-version constants if internal-only) in the main crate.
|
||||||
|
4. Use `[workspace.dependencies]` for cross-crate version pinning, not
|
||||||
|
path-dependency duplication.
|
||||||
|
|
||||||
|
**Budget: 4 hours, not 1–2.** Mechanical if `protocol.rs` is clean;
|
||||||
|
longer if internal types need disentangling. The wire-vs-internal pass
|
||||||
|
takes care — mismatched extraction (moving too much or too little)
|
||||||
|
propagates into `pmacs-gpu`'s dependency graph in ways that are
|
||||||
|
expensive to undo.
|
||||||
|
|
||||||
|
Naming: `pmacs-protocol` is the chosen name for consistency with
|
||||||
|
`protocol.rs`. Alternatives considered (`pmacs-wire`, `pmacs-ipc`) are
|
||||||
|
more specific but break the naming continuity.
|
||||||
|
|
||||||
|
## Forced decisions
|
||||||
|
|
||||||
|
These are decisions the producer arc deferred because no frontend
|
||||||
|
existed. The framing pass commits each before Phase A starts so the
|
||||||
|
work isn't blocked on rediscovery.
|
||||||
|
|
||||||
|
### Q#1 — visual motion API: stance (β)
|
||||||
|
|
||||||
|
The frontend implements visual motion. The instance stays pixel-pure.
|
||||||
|
|
||||||
|
Concretely: on arrow-down in a soft-wrapped buffer, the frontend
|
||||||
|
computes the visual-next byte position locally and sends
|
||||||
|
`FrontendEvent::SetCursor` with the target byte. The instance never
|
||||||
|
reasons about wrap.
|
||||||
|
|
||||||
|
If Phase A surfaces (β) as unworkable, that's a load-bearing finding
|
||||||
|
the verification-milestone-premise-check classifies as structural —
|
||||||
|
defer, scope its own work, don't try to patch in Phase A.
|
||||||
|
|
||||||
|
#### Implementation: (β-impl) for Phase A, with documented upgrade path
|
||||||
|
|
||||||
|
Phase A starts with **(β-impl)**: the frontend recomputes wrap state
|
||||||
|
from `BufferMirror` on each visual-motion event. O(viewport) per motion
|
||||||
|
event; no maintained index. Cheaper to implement; fine if motion is
|
||||||
|
keyboard-driven (one event per keypress).
|
||||||
|
|
||||||
|
**Upgrade to (α-impl)** — a maintained wrapped-line tree indexed by
|
||||||
|
byte position, incrementally invalidated on edits — becomes necessary
|
||||||
|
if smooth scroll or kinetic scroll lands in v0.1. The framing
|
||||||
|
pre-authorizes the upgrade if Phase A's scope grows there.
|
||||||
|
|
||||||
|
### Cursor scope at v0.1
|
||||||
|
|
||||||
|
In scope:
|
||||||
|
|
||||||
|
- **Blink** (configurable rate; standard).
|
||||||
|
- **Multi-cursor rendering** — pmacs's data model supports multiple
|
||||||
|
cursors; rendering is an additive concern. Renders correctly when
|
||||||
|
present, even if not heavily exercised in Phase A.
|
||||||
|
- **Peer cursors** via `PresenceUpdate` with stable per-frontend colors
|
||||||
|
honoring `M10.9`'s SO_PEERCRED-stable color discipline. Data already
|
||||||
|
exists; rendering is what validates it.
|
||||||
|
|
||||||
|
Out of scope:
|
||||||
|
|
||||||
|
- **Multi-cursor commands** — TUI doesn't have ways to create multiple
|
||||||
|
cursors; the command layer is a separate concern. Multi-cursor
|
||||||
|
rendering ships ahead of the commands that exercise it.
|
||||||
|
|
||||||
|
### Font at v0.1
|
||||||
|
|
||||||
|
Stance (γ): **bundle JetBrains Mono as default; expose Lua hook for
|
||||||
|
override.**
|
||||||
|
|
||||||
|
- Bundled font: JetBrains Mono (Apache 2.0; broad glyph coverage;
|
||||||
|
designed for code; ~1.5MB; dwarfed by `wgpu`'s footprint).
|
||||||
|
- Lua override: `pmacs.gpu.set_font(path)` or similar (precise binding
|
||||||
|
shape decided session 2).
|
||||||
|
- Missing-glyph fallback: tofu (replacement character `U+FFFD`).
|
||||||
|
Explicit non-goal to ship a sophisticated fallback chain in v0.1.
|
||||||
|
If real users hit this, it's v0.2+ scope.
|
||||||
|
|
||||||
|
The bundled-default-plus-override shape means v0.1 works without
|
||||||
|
configuration; future customization needs no wire-protocol changes.
|
||||||
|
|
||||||
|
## Rhythm
|
||||||
|
|
||||||
|
The worktree-per-step pattern that drove v1.0 ships individual PRs at
|
||||||
|
hour-level granularity. The GPU work has portions that don't decompose
|
||||||
|
that cleanly: text rendering integration, layout, input event handling
|
||||||
|
are days of work each, not hours.
|
||||||
|
|
||||||
|
**The cadence relaxes; the discipline does not bend.**
|
||||||
|
|
||||||
|
- Worktree-per-step continues for discrete features (project setup,
|
||||||
|
protocol extraction, isolable subsystems).
|
||||||
|
- Larger features ship at daily-PR cadence: each session is a
|
||||||
|
day's worth of work, ending in a commit; multi-day features
|
||||||
|
accumulate across sessions, with a final feature-completion commit.
|
||||||
|
|
||||||
|
### Discipline anchor: session, not PR
|
||||||
|
|
||||||
|
In v1.0's hour-level rhythm, each PR was an audit-doc-finding-recording
|
||||||
|
event. With daily cadence, PRs are too coarse for the discipline; the
|
||||||
|
session is the unit.
|
||||||
|
|
||||||
|
Concretely:
|
||||||
|
|
||||||
|
- A session starts with audit-doc state and ends with audit-doc state.
|
||||||
|
- Findings surface within sessions; pause-and-report happens at
|
||||||
|
session boundaries or mid-session as the finding warrants.
|
||||||
|
- The session-end commit (or audit-doc update for sessions where no
|
||||||
|
code-merge ships) is the rhythm anchor.
|
||||||
|
|
||||||
|
The pause-before-implementation, finding-recording-at-surface-time, and
|
||||||
|
audit-doc-as-canonical-source disciplines are unchanged.
|
||||||
|
|
||||||
|
## Audit artifacts
|
||||||
|
|
||||||
|
This doc (`pmacs-gpu-design.md`) is the **design artifact**. It lives
|
||||||
|
in the same documentation tier as
|
||||||
|
`docs/semantic-frontend-protocol.md` — forward-looking design framing,
|
||||||
|
read by future contributors and sessions.
|
||||||
|
|
||||||
|
**Per-phase audit material lives in separate per-phase audit docs**,
|
||||||
|
following the M10.x pattern:
|
||||||
|
|
||||||
|
- `docs/pmacs-gpu-phase-a-audit.md` — Phase A findings, classification
|
||||||
|
decisions, predicted-vs-actual scoring at Phase A close.
|
||||||
|
- `docs/pmacs-gpu-phase-b-audit.md` — Phase B equivalent. (Future.)
|
||||||
|
- etc.
|
||||||
|
|
||||||
|
This doc updates with cross-references to per-phase audit docs as they
|
||||||
|
land. Design artifact stays readable; audit material gets the
|
||||||
|
per-phase shape M10 validated.
|
||||||
|
|
||||||
|
## Deliberately not committed (framing-pass scope)
|
||||||
|
|
||||||
|
The framing pass closes with the following deliberately deferred to
|
||||||
|
session 1 or later:
|
||||||
|
|
||||||
|
- **`winit`** (the window/event-loop crate). The Rust ecosystem
|
||||||
|
alternative is sparse; `winit` is the likely default. Session 1
|
||||||
|
confirms; if the ecosystem has shifted, the decision happens then.
|
||||||
|
- **`pmacs-gpu` internal layering** (UI module structure, threading
|
||||||
|
model, frame-budget discipline). Decided session 2 when the
|
||||||
|
workspace is set up, not pre-decided here.
|
||||||
|
- **Acceptance-test shape**. Golden-frame / screenshot-comparison via
|
||||||
|
headless `wgpu` rendering is the likely substrate; pixel-exact vs
|
||||||
|
perceptual comparison is a separate decision. If acceptance-test
|
||||||
|
shape surfaces complications during session 1 or 2, classify as
|
||||||
|
structural finding (iii).
|
||||||
|
|
||||||
|
## Session plan
|
||||||
|
|
||||||
|
| Session | Work | Gate at close |
|
||||||
|
|---|---|---|
|
||||||
|
| 1 | `pmacs-protocol` crate extraction. Move wire types out; `[workspace.dependencies]` pattern; main crate keeps internal protocol utilities. | Full gate set; main pmacs binary still passes all v1.0 tests. |
|
||||||
|
| 2 | `pmacs-gpu` workspace member; `wgpu`/`winit`/`cosmic-text`/`glyphon` deps; hello-world: open a window, render "hello, pmacs" with the bundled font. | Hello-world runs; no protocol consumption yet. |
|
||||||
|
| 3 | Attach loop — `pmacs-gpu` connects to a running pmacs daemon as a `semantic_render` session; receives `BufferSnapshot`; rebuilds rope locally. | Daemon ↔ frontend handshake; rope reconstruction matches. |
|
||||||
|
| 4+ | Phase A proper — render the rope; consume `StyleSpans`, `Decorations`, `InlineAdornments`, `FileStyleSummary`, `CursorByte`; work through the test corpus. | Phase A close = predicted-vs-actual scoring against the bets above. |
|
||||||
|
|
||||||
|
The session-numbered plan is forward-looking; reality will reshape it
|
||||||
|
as Phase A surfaces findings. The framing pass commits the *structure*;
|
||||||
|
the *sequence* is allowed to bend.
|
||||||
Loading…
Reference in New Issue