wraithterm 0.0.0-stage → 0.2.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,179 @@
+# Architecture
+
+Wraith separates terminal semantics, rendering, and browser integration. The
+`Wraith.mount()` terminal model never crosses JavaScript as a JSON screen or an array of cell
+objects. Each `Wraith.mount()` instance owns a worker, a Wasm module, and a GPU device.
+
+```mermaid
+flowchart LR
+    App[Application / PTY transport] --> SDK[TypeScript SDK]
+    SDK -->|owned byte buffers / commands| Worker[Dedicated worker]
+    Worker -->|one Wasm instance| Ghostty[libghostty-vt]
+    Ghostty -->|C ABI / changed rows| Core[Retained Rust snapshot]
+    Core --> Text[HarfRust / swash / glyph atlas]
+    Text --> GPU[Rust wgpu / WGSL]
+    GPU --> Canvas[OffscreenCanvas / WebGPU]
+    Ghostty -->|responses / input encoding| Worker
+    Worker --> SDK
+```
+
+## Ownership
+
+`Core` owns a Ghostty bridge handle and a stable Rust `State` allocation. The State's address
+remains stable when Core moves. Its internal raw owner prevents an owning Box
+field from being retagged while foreign code retains a userdata pointer. Public
+snapshot access is read-only. Ghostty callbacks may borrow it only synchronously,
+inside a write or render-state update. No callback reenters the terminal. The bridge
+is freed before the State, and uses Rust allocation callbacks for every Ghostty
+allocation. There are no competing Zig and Rust heaps.
+
+`native/bridge.c` is the sole translation layer for upstream C structs, sized
+struct initialization, and enum constants. Rust exposes its own small `Frame`
+layout. A pinned Ghostty revision and C compilation isolate upstream API churn.
+
+`Renderer` owns the device, surface, pipeline, atlas texture, cell storage buffer,
+uniform buffer, and CPU staging cells. `Atlas` owns font bytes, shaping metadata,
+the swash scaler context, and a bounded cache keyed by grapheme and style.
+
+The SDK copies caller-owned input once before transferring it to the worker.
+String input is encoded once. Wasm bindings copy input into Wasm memory. Inside
+Wasm, changed cells are copied into retained Rust storage; they do not make an
+expensive trip through JavaScript. WebGPU performs its required upload copies.
+This is deliberately not described as an entirely zero-copy pipeline.
+
+## A frame
+
+1. libghostty-vt parses a streaming byte sequence and updates terminal state.
+2. The worker coalesces presentation through requestAnimationFrame. Idle state
+   produces no redraw, except cursor or text blinking.
+3. Ghostty updates its incremental render snapshot. The adapter visits dirty rows
+   and copies their grapheme, colors, and flags into reusable Rust cell storage.
+4. Atlas hits reuse an existing tile. A miss chooses a fallback font, shapes the
+   grapheme with HarfRust, rasterizes with swash, and schedules one texture upload.
+5. Each changed cell becomes a 20-byte GPU record: colors, flags and one glyph
+   word (atlas slot, ink width, color bit). Rows that only moved are copied
+   by libghostty row id and raw cells instead of re-read. Adjacent changed rows merge into
+   one `write_buffer` call. The GPU cell buffer stays resident between frames.
+6. A single render pass issues two instanced draw calls: backgrounds first, then
+   glyphs and decorations. This prevents a wide glyph from being covered by the
+   next cell's background. Glyph sampling uses explicit LOD 0, so per-cell branches
+   do not violate WGSL derivative-uniformity rules.
+7. The command buffer is submitted and the surface texture is presented. Dirty
+   flags clear only after successful submission.
+
+Moving a cursor may dirty its previous and new rows, following Ghostty's damage
+model. Scrolling currently repacks the changed viewport rows. GPU row remapping
+is a priority for reducing that work in dense and real scrolling workloads.
+
+## Input and output
+
+Keyboard and mouse events are encoded by Ghostty, using its current modes. This
+keeps legacy application cursor keys, modifiers, and Kitty keyboard behavior in
+the terminal core. Browser code owns focus, composition events, pointer selection,
+clipboard gestures, and safe activation of HTTP(S)/mailto OSC 8 links.
+
+Terminal-generated replies share the same byte event path as user input.
+Title and bell effects have separate typed events. Selection anchors belong to
+Ghostty, so copying can use its formatter rather than reconstructing logical
+lines from pixels.
+
+The worker serializes commands. In particular, an asynchronous GPU fence holds a
+Rust borrow until completion. Previously queued animation callbacks are canceled
+or guarded while that borrow is active. This prevents a render callback from
+recursively mutating a borrowed Wasm object.
+
+## Bounds and failures
+
+The grid is limited to 512 per dimension and 65,536 cells, and pixel dimensions
+must fit the GPU's texture limits. The atlas is 2048×2048 RGBA. If a new glyph set
+would exceed capacity, it resets and rebuilds all visible rows in the same frame.
+If the visible set itself exceeds capacity, rendering reports an explicit error
+rather than reusing live tiles. Font bytes remain independent of atlas entries.
+
+Synchronized output preserves the last completed snapshot. A 150 ms worker timer
+releases an abandoned hold when it can safely access the engine. GPU-fenced
+benchmark batches and explicit flushes do not block the application UI thread.
+
+Pipeline creation checks a WebGPU validation scope before mount resolves. Runtime
+GPU errors retain the first diagnostic and reach `onError`; outstanding work is
+rejected and the worker is terminated. Device-loss recovery currently means
+remounting a terminal. Teardown disposes listeners, ResizeObserver, timers, DOM,
+the Wasm owner, and GPU resources; a stalled worker is terminated after a bounded
+wait.
+
+## Where to extend
+
+| Area                                         | File / module                            |
+| -------------------------------------------- | ---------------------------------------- |
+| Upstream ABI and effects                     | `native/bridge.c`                        |
+| Headless state ownership and snapshots       | `crates/wraith-engine/src/core.rs`       |
+| Shaping, fallback, rasterization, cache      | `crates/wraith-engine/src/text.rs`       |
+| Uploads, device, surface, render pass        | `crates/wraith-engine/src/gpu.rs`        |
+| Cell geometry and visual styles              | `crates/wraith-engine/src/terminal.wgsl` |
+| Wasm public engine bindings                  | `crates/wraith-engine/src/web.rs`        |
+| Scheduling, protocol, benchmarks             | `packages/wraith/src/worker.ts`          |
+| Browser API, input, transport, accessibility | `packages/wraith/src/index.ts`           |
+
+Performance work should be driven by a recorded workload and percentile evidence.
+Broad compatibility additions should add a failing protocol fixture and, where
+visual behavior is involved, a browser pixel assertion.
+
+## xterm-compatible profile
+
+`Terminal` inherits the official, pinned xterm 6.0 core. Its renderer adapter is
+isolated in `xterm-internals.ts`; no private parser or input code is patched.
+`xterm-api.d.ts` and the CSS are generated from that pinned package, with the MIT
+notice preserved. An internal npm dependency alias prevents recursion when users
+install Wraith as `@xterm/xterm`.
+
+The synchronous constructor and `open()` keep the original DOM/input tree and
+services. The adapter transfers ownership of the original DOM renderer through
+xterm's `MutableDisposable.clearAndLeak()` and installs a composite renderer.
+The adapter then owns its fallback, canvas, subscriptions, timer and compositor.
+Replacement by another renderer or terminal disposal releases all of them. An
+instance disposed during GPU initialization immediately frees a late result.
+
+Warm scalar glyphs use numeric cache keys referencing the same text/style tiles.
+Combining clusters retain the string path. Ordinary adjacent attribute runs
+reuse one decoded style; extended attributes bypass that optimization. These
+paths read the guarded three-word BufferLine storage through the private adapter.
+Ordinary scalar cells bypass public cell loading; combined text, extended
+attributes, invalid scalars and unfamiliar row layouts retain getter behavior.
+
+The compositor owns a reusable Wasm arena containing cell words, four dimensions
+and eight frame words. JavaScript packs directly into views of that allocation,
+then submits a cell count and destination offset. This removes the three binding
+allocations and JS-to-Wasm array copies from the compatible redraw path. GPU
+upload copies remain. Bounds and device storage limits are checked before use.
+
+Views refresh when configuration changes or Wasm memory grows. A cold glyph
+upload can detach them during packing; the adapter refreshes the views and
+repeats the affected row before submission. Arena slots use `UnsafeCell` to make
+their JS write ownership explicit. Writes and synchronous Rust slice consumption
+must not overlap, and rendering remains paused during benchmark fences.
+
+Buffers, float views and uniforms are reused. Every packed cell overwrites its
+complete record, including explicit zero UVs for blank and continuation cells.
+A failed surface acquisition retains pending presentation and damage until an
+actual submission. The native worker retries at its next animation opportunity;
+the compatible renderer requests another redraw.
+
+xterm's render service coalesces changed row ranges. The adapter reads those rows
+from the authoritative buffer, reuses compositor-owned staging storage, and uses a
+borrowed-text glyph cache with four bold/italic variants. Browser Canvas2D handles
+CSS font rasterization on misses. Atlas exhaustion resets and repacks the full
+viewport before submission, avoiding stale references. If a visible glyph set
+still exceeds capacity, the DOM renderer takes over.
+
+The Rust `Compositor` has no terminal parser or font allocation. It validates
+geometry and upload ranges and shares the resident cell buffer, texture, shaders,
+render pass and submission code with the native Ghostty renderer. xterm's
+callbacks, events and buffer reads keep their original timing; write callbacks
+indicate parsed state, rather than GPU completion.
+
+Transparency, minimum contrast, character joiners, buffer decorations and link
+hover currently delegate rendering to the retained DOM renderer. This is a
+behavior-preserving fallback; the GPU profile resumes when those conditions end.
+Selection, modes and input remain xterm-owned throughout. Browser rendering and
+parser costs differ from the libghostty worker profile, so its benchmark numbers
+cannot be assigned to the compatibility profile.

package/docs/COMPATIBILITY.md

@@ -0,0 +1,66 @@
+# Compatibility
+
+The complete xterm.js 6.0 public API is available through `Terminal`. It uses the
+pinned upstream semantic core with Wraith's WebGPU compositor and automatic DOM
+fallback. Original Fit, Search, Serialize, Attach and Unicode11 addons, unchanged
+npm imports, and strict consumer types are verified. See [XTERM_API.md](XTERM_API.md)
+for the complete surface and exact rendering limitations.
+
+The protocol matrix below describes the separate **libghostty `Wraith.mount()`
+profile**. Its remaining work does not imply missing xterm methods in `Terminal`.
+
+Wraith uses upstream libghostty-vt at the commit in `upstream.json`, rather than
+an independently invented escape-sequence parser. That gives it a substantial
+terminal model, but complete browser-terminal conformance also depends on the
+renderer, input path, effects, fonts, and browser integration.
+
+## Implemented and verified
+
+| Area                                                                            | Verification                                                                 |
+| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Streaming UTF-8, split CSI/OSC sequences                                        | Every split boundary of a Unicode/SGR fixture; one-byte Wasm writes.         |
+| Cursor positioning, save/restore, delayed wrap                                  | Native protocol fixtures.                                                    |
+| Insert/delete/erase, BCE, scrolling margins, origin mode                        | Native fixtures with expected visible contents.                              |
+| Alternate screen and main-screen restoration                                    | Native and packaged Wasm fixtures.                                           |
+| Bounded scrollback, viewport scrolling, resize reflow                           | Native contents checks.                                                      |
+| ANSI indexed and 24-bit color, colon syntax                                     | Exact cell color assertions.                                                 |
+| Bold, synthetic italic, faint, inverse, hidden, blink                           | Core styles and implemented renderer flags; visual sample in Chrome.         |
+| Single/double/curly/dotted/dashed underlines, underline color, strike, overline | Core style flags and WGSL implementations; underline/strike pixels in demo.  |
+| DEC line drawing                                                                | Expected Unicode box drawing and Chrome sample.                              |
+| Wide and combining characters                                                   | Cell widths, tail cells, combined clusters, clipboard text fixtures.         |
+| OSC title and bell                                                              | Native and browser effect paths.                                             |
+| Device attributes, version, cursor, size, color-scheme reports                  | Registered effects and native fixtures.                                      |
+| Synchronized output                                                             | Snapshot hold, release, and deadline recovery.                               |
+| OSC 8 hyperlinks                                                                | Core URI lookup; browser modifier-click handler restricts URL schemes.       |
+| Selection                                                                       | Real pointer selection in Chrome; Ghostty formatter unwraps soft-wraps.      |
+| Legacy / application arrows and Kitty keyboard disambiguation                   | Packaged Wasm byte-for-byte encoding tests.                                  |
+| SGR mouse encoding, focus reports, bracketed paste                              | Native encoder path; browser paste test and sanitized frame contents.        |
+| IME commits and preedit placement                                               | Browser composition test; cursor coordinates anchor the input element.       |
+| Accessible viewport mirror                                                      | Optional role=log mirror, exercised in browser lifecycle test.               |
+| Input ownership and backpressure                                                | Original buffer survives transfer; oversize write rejects.                   |
+| Multiple instances and disposal                                                 | Browser independent instance test and repeated Wasm allocation plateau test. |
+| WebGPU rendering                                                                | Chrome pipeline validation and actual screenshot pixel assertions.           |
+
+The installed default font does not cover every Unicode character. Fonts affect
+visual coverage independently of the terminal model's Unicode support.
+
+## Remaining release work
+
+| Area                                                            | Current status                                                                      |
+| --------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Kitty graphics / Sixel                                          | Kitty graphics compiled out; Sixel renderer absent.                                 |
+| OSC 52 / Kitty clipboard protocol                               | No terminal-initiated browser clipboard read/write bridge. User paste/copy works.   |
+| Cross-cell ligatures and contextual script runs                 | Shaping is per Ghostty grapheme cell. Full row-run shaping remains.                 |
+| Bidi behavior                                                   | No separate browser bidi layout pipeline.                                           |
+| Native font discovery                                           | Explicit bundled / supplied font data; no browser system-font rasterizer.           |
+| Dynamic DPR or font-size changes                                | DPR captured at mount. Remount with new settings.                                   |
+| Full screen-reader certification                                | Optional text mirror is implemented; assistive-technology auditing remains.         |
+| Search, word/line selection gestures, configurable key bindings | Not exposed in the SDK yet.                                                         |
+| WebGL/Canvas fallback                                           | WebGPU-only; unsupported environments receive an actionable initialization error.   |
+| Firefox / Safari certification                                  | Capability checks exist; the current recorded browser suite is Chrome on macOS.     |
+| xterm.js addon compatibility                                    | Available through the separate `Terminal` profile; see XTERM_API.md.                |
+| Complete terminal-spec certification                            | Requires expanded upstream fixtures, vttest, and real PTY/TUI integration coverage. |
+
+The first release should keep this matrix current rather than advertise an
+unqualified “full support” badge. Image protocols, script-run shaping, and
+cross-browser/TUI certification are the next compatibility milestones.

package/docs/PERFORMANCE.md

@@ -0,0 +1,122 @@
+# Performance
+
+**Current results:** the [efficiency pass](benchmarks/efficiency/REPORT.md)
+measures both profiles against `a136240` with interleaved runs. Dense
+240×80 updates are 23–60% faster, and log streaming is about 95% faster.
+Redraw CPU drops to 0.3 ms (compat) and 0.5 ms (native). Every scene is
+pixel-identical to the earlier build. Sections below are earlier
+measurements, retained with their original builds.
+
+These measurements cover the **libghostty `Wraith.mount()` worker profile**.
+The xterm-compatible `Terminal` profile uses a different semantic core and
+browser rasterizer; these throughput figures do not measure that profile.
+
+The recorded Chrome suite verifies actual terminal pixels before measuring throughput.
+It ran with default Chrome WebGPU settings on macOS, devicePixelRatio 1, a 13 CSS
+pixel font, and line height 1.45. Chrome identified the backend as BrowserWebGpu;
+it did not expose a hardware model, so no specific GPU model is claimed.
+
+## Head-to-head comparison
+
+The newer [dense-scene comparison](benchmarks/comparison/REPORT.md) measures the
+compatible Terminal against xterm 6.0 DOM and WebGL, alongside the libghostty
+engine. It records 60 runs at 240×80 with 4,800 style changes per frame, plus
+post-warmup pixel/text validation. On the dense DPR 1 scene, compatible Wraith
+completes about 290 GPU-fenced updates/s versus 182 for xterm WebGL. This workload
+has substantially more input and styling than the earlier benchmark below.
+
+The earlier results below retain their original binary SHA and date; the
+comparison uses an instrumented build with a compositor fence export. Neither
+set is a claim about physical display refresh.
+
+[CPU and GPU utilization](benchmarks/comparison/UTILIZATION.md) is sampled
+separately during repeated continuous runs. CPU covers the benchmark's dedicated
+Chrome instance. GPU counters cover the entire device and include paired idle
+baselines; they cannot be attributed to one library on this shared machine.
+
+The [newer optimization pass](benchmarks/optimization/REPORT.md) compares a saved
+pre-change build with the final optimized build in alternating order. Its source
+and binary hashes, submitted-frame checks and differential results are recorded
+separately. Earlier speed and usage figures below remain historical measurements.
+
+The subsequent [bulk packing and persistent staging pass](benchmarks/packing/REPORT.md)
+records 48 alternating runs and independent staging experiments. The compatible
+pipeline improves by about 7–11% across the tested conditions; staging's separate
+throughput effect remains noisy. It also verifies actual submitted cells after
+forced Wasm memory growth. All new records carry their source/binary identities.
+
+## Recorded results
+
+| Grid   | Workload          | Frames | GPU-fenced frames/s | CPU p50 ms | CPU p95 ms | CPU p99 ms |
+| ------ | ----------------- | -----: | ------------------: | ---------: | ---------: | ---------: |
+| 80×24  | sparse            |    512 |              11,532 |       0.00 |       0.10 |       0.20 |
+| 80×24  | dense             |    512 |               8,166 |       0.10 |       0.20 |       0.20 |
+| 80×24  | scroll            |    512 |               8,298 |       0.10 |       0.20 |       0.20 |
+| 160×50 | sparse            |    512 |               7,829 |       0.00 |       0.10 |       0.20 |
+| 160×50 | dense             |    512 |               2,238 |       0.40 |       0.50 |       0.60 |
+| 160×50 | scroll            |    512 |               2,353 |       0.40 |       0.50 |       0.60 |
+| 160×50 | dense (sustained) |  8,192 |               2,280 |       0.40 |       0.50 |       0.60 |
+
+The sustained dense run completed **8,192 frames in 3.59 seconds**, averaging
+**2,280 GPU-completed frames/s**. Its CPU p95 was **0.50 ms**.
+
+[Latest native browser verification](benchmarks/chrome.json) includes the exact Wasm SHA-256,
+Ghostty revision, user agent, all timings, and the pixel assertion summary.
+[An earlier unoptimized run](benchmarks/baseline-chrome.json) is retained for
+context. Runs are observations on this machine, not a controlled A/B comparison.
+
+## What the benchmark measures
+
+Inputs are generated before the timed region. Sixty-four warmup frames populate
+the glyph atlas and exercise the parser. Each measured iteration writes a fresh
+payload, captures the terminal snapshot, updates dirty rows, encodes a render
+pass, and submits it. Every 32 submissions, a four-byte GPU buffer copy is mapped
+and awaited; a final fence waits for the last batch. The elapsed time therefore
+includes GPU completion waits rather than counting an unchecked submission loop.
+
+The dense payload changes every cell, its character cycle, and row colors. Sparse
+updates one row; scroll appends a line and shifts the viewport. The same 64-frame
+payload cycle makes the input deterministic. Large-grid rendering covers a full
+1280×950 pixel canvas even when the page's host clips the visible viewport.
+
+CPU percentiles include parsing, snapshot traversal, atlas lookup, uploads,
+encoding, and submission. They exclude the main-thread SDK and worker message
+transport, and do not isolate GPU execution time. Cold rasterization and pipeline
+initialization are excluded by warmup. Browser timer resolution is about 0.1 ms
+in this test; zero samples mean below timer resolution.
+
+**These are completed render frames in fenced batches, not distinct monitor
+presentations.** Browsers present through refresh-paced requestAnimationFrame.
+A 120 Hz screen has an 8.33 ms presentation budget; 1000 Hz would have a 1 ms
+budget. The measured warm pipeline has headroom for the target, but 120 Hz physical
+presentation still requires an appropriate browser, display, workload, and input
+feed. This suite does not certify a particular monitor refresh rate.
+
+## Distribution size
+
+The optimized Wasm module is **2.27 MiB raw / 797 KiB gzip**.
+wasm-opt version 133 with -O3 --strip-dwarf reduced it from
+2,931,003 to 2,380,758 bytes. Font data is a separate
+270 KB asset for the libghostty profile. The xterm profile rasterizes CSS fonts
+without a font download. Its pinned xterm core is the one npm runtime dependency.
+
+## Repeat
+
+Run the demo server, then:
+
+```sh
+npm run test:browser
+```
+
+The suite records six 512-frame runs, an 8192-frame sustained dense run, and PNG
+proof under docs/benchmarks. Set WRAITH_REPORT_DIR to retain another run separately.
+Use the playground to select a workload and export its raw JSON result. Test
+physical refresh behavior separately on the intended 120/144/240 Hz displays.
+
+## Next performance work
+
+Measure cold Unicode glyph storms, atlas rebuilding, multiple simultaneous
+terminals, large PTY output bursts, and background-to-foreground transitions.
+Optional GPU timestamp queries can separate GPU pass time from CPU time and
+queue/fence overhead. A row-identity mapping could reduce scroll uploads. These
+should each be backed by a recorded before/after workload.

package/docs/TOP_TIER.md

@@ -0,0 +1,124 @@
+# Wraith: engineering plan for a top-tier terminal
+
+Wraith should win on responsive input, reliable 120 Hz presentation, correct terminal behavior, low resource use, and effortless integration. A 1000-update/s stress result remains a useful stretch target. It is one workload-specific throughput measurement, not the complete product standard.
+
+This plan separates implemented changes from proposed work. Its priorities come from the current source, the dense-scene CPU profile, compatibility checks, and before/after measurements. Performance targets below are proposed acceptance criteria, not claims that Wraith already meets them on every device.
+
+## Architecture decisions
+
+Keep two explicit profiles. The compatible `Terminal` preserves xterm's semantic core, callbacks, parser hooks, live buffers and addons. The native `Wraith.mount()` profile keeps libghostty, shaping and GPU rendering together in a worker. Do not parse output twice, replay terminal state through ANSI, or silently assign the native engine's speed to the compatible API. Replacing xterm's semantic core with Ghostty requires a separate conformance project; moving synchronous API state into a worker is not a free optimization.
+
+The renderer should consume stable row identities, revisions, glyph IDs and packed attributes. Presentation scheduling should consume damage and deadlines. Neither layer should own terminal semantics. Preserve ordered input and resize effects; coalesce redundant presentation work rather than dropping terminal bytes or callbacks.
+
+## Work implemented in this pass
+
+- Native atlas preflight borrows glyph strings, checks hits before creating missing-key entries, and excludes spaces that require no tile. A full warm viewport no longer clones thousands of glyph strings merely to check capacity.
+- Compatibility packing reuses cell and uniform buffers and a float view. It overwrites blank/continuation glyph coordinates explicitly instead of clearing the complete staging array before writing every populated record.
+- Adjacent cells reuse decoded ordinary attributes. This cache holds one style, resets per pack, and bypasses extended attributes. RGB churn cannot grow it, and selected colors remain resolved per cell.
+- Unicode scalar glyphs have a numeric cache referencing the existing tile variants. Warm scalar cells avoid reconstructing Unicode strings. Combining clusters use the original string path, and both caches reset together.
+- A temporarily unavailable surface retains pending presentation. Native damage is acknowledged only after submission; the worker retries without waiting for another write. The compatible renderer also requests a retry. An added browser regression simulates a skipped presentation.
+- Benchmark pipelines check actual WebGPU submission counters rather than assuming every attempted update submitted a frame. Packed-output differential fixtures compare every word at DPR 1 and 2.
+- The subsequent row-packing pass reads guarded three-word xterm rows directly for ordinary scalar cells and retains getter fallbacks. The compositor owns persistent Wasm cell and uniform staging, removing binding allocations and copies from normal compatible redraws. Cold glyph uploads that grow memory refresh views and repack the affected row. Bounds, reserved uniform reset, and actual submitted cells after forced growth are tested.
+
+- The efficiency pass packs 20-byte cells with one glyph word and sizes glyph quads to ink. It replaces string hashing with a scalar glyph table and cuts per-cell libghostty queries. Both profiles reuse unchanged and moved rows and upload only changed rows, and write bursts reach the worker as one transfer. See [the efficiency report](benchmarks/efficiency/REPORT.md).
+
+Results and limitations belong in [the efficiency report](benchmarks/efficiency/REPORT.md) and, for earlier passes, [the optimization report](benchmarks/optimization/REPORT.md). Archived earlier benchmarks remain attached to their original binaries.
+
+## Prioritized implementation backlog
+
+| Priority | Investment                                                          | Why it matters                                                                    | Proof required                                                                                             |
+| -------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| P0       | GPU support for search decorations, link hover and minimum contrast | Ordinary features currently trigger much slower DOM rendering                     | Original-addon and pixel tests; GPU mode remains active during decorated search and hover                  |
+| P0       | GPU row remapping for scrolls                                       | Moved rows are now reused on the CPU but still uploaded at their new position     | Append-only PTY traces; one-row scroll uploads proportional to the new row, with correct selection/history |
+| P0       | Input scheduling and latency instrumentation                        | A fast average can coexist with delayed keystrokes or large pauses                | Local input-to-visible-echo distribution, main-thread long tasks and frame-miss counts                     |
+| P0       | Separate model lifetime from GPU lifetime                           | Device loss currently makes the native profile terminate its worker               | Simulated loss/recovery preserves text, history, modes, selections and ordered pending writes              |
+| P1       | Bounded multi-page glyph atlas with generations                     | A single 2048-square atlas can reset or overflow on large Unicode/Retina scenes   | Atlas exhaustion, font changes, mixed scripts and stale-reference tests                                    |
+| P1       | Shared device/pipeline/atlas resources where ownership allows       | Each terminal currently owns another GPU device and RGBA atlas                    | 1/4/8/16-terminal resource and responsiveness measurements                                                 |
+| P1       | Smaller compositor-only Wasm artifact                               | The compatible renderer downloads code for native parsing/shaping it does not use | Cold-load and first-correct-frame comparisons; unchanged APIs and consumers                                |
+| P1       | Complete rendering and input conformance corpus                     | Public API shape alone does not establish visual or protocol parity               | Differential state, pixels, keyboard/IME and real application traces                                       |
+| P2       | Persistent render target with damage rendering                      | Sparse changes still redraw the entire canvas                                     | GPU pass timings; scroll, cursor, transparency and resize correctness                                      |
+| P2       | SIMD, upload staging rings, compact glyph draw lists                | These may improve specific bottlenecks after larger waste is removed              | Per-platform measurements showing a meaningful benefit without regressions                                 |
+
+## CPU, copies and the terminal core
+
+1. Profile parsing, snapshot extraction, attribute decoding, glyph lookup, packing, Wasm copies, GPU submission and browser paint independently. Use a profiling build for Ghostty/Wasm function attribution. RGB churn is a separate parser workload: the native parser is not universally faster than xterm's JavaScript parser in the recorded tests.
+2. Build a guarded numeric glyph path and eventually a glyph-ID ABI. The current scalar cache is a first step. An immutable glyph descriptor can hold UV coordinates, bearings, dimensions and color mode once instead of repeating coordinates in every cell. Keep explicit underline colors and wide/continuation semantics when evaluating a 20-byte or smaller cell layout.
+3. Persistent Wasm staging is implemented. Continue measuring its independent effect, since copy removal alone does not establish a throughput gain in a parser-heavy workload. Refresh views after growth, validate ranges, and keep ownership explicit. WebGPU still performs its required data snapshot/upload.
+4. Reduce retained native text allocation using scalar/cluster IDs or inline small text, while preserving the public cell/text/selection behavior. Use row arenas or reusable storage before introducing unsafe borrowed pointers into Ghostty memory.
+5. Expose a stream sink that waits for write credit instead of making callers invent retry loops. Write bursts are already batched into one worker transfer.
+6. Investigate why toggling reverse video (CSI ?5h) after content is drawn leaves existing native cells in their old colors; a136240 already behaves this way.
+7. Budget large input processing so it cannot starve rendering or keyboard responses. Preserve UTF-8/escape state across slices and respect synchronized output. Avoid changing xterm's callback or custom-parser semantics for the compatible profile.
+8. Replace per-frame sample shifts with rings, make expensive diagnostics opt-in, and remove avoidable geometry/font-string work and row wrappers after profiling confirms their cost.
+
+Shared memory can be an optional high-throughput lane. It must retain the transferable-buffer path for ordinary embedding; browser shared memory requires a secure, cross-origin-isolated document. [SharedArrayBuffer requirements](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer)
+
+## GPU rendering and glyph residency
+
+1. Keep unchanged rows resident. Map screen rows to retained physical GPU rows, update the mapping and only pack new/revised rows. Track parser mutations, viewport changes, selection and atlas generations explicitly. Use conservative full invalidation when a revision is unknown.
+2. Merge uploads by dirty ranges and benchmark a threshold for partial-cell spans. Comparing packed cells can avoid unnecessary uploads, but it is additional CPU work; use it where the expected unchanged data justifies the comparison.
+3. Experiment with a persistent backing texture for sparse damage. Swapchain contents cannot be assumed to preserve the previous image. Update damaged regions in the retained texture, then present through a copy or blit. Include the extra pass and texture bandwidth in the result.
+4. Crop glyphs to ink bounds with descriptor bearings to reduce transparent overdraw. Compact the nonempty-glyph draw list for sparse logs. Dense workloads may not benefit from that compaction.
+5. Evaluate an alpha-only atlas for monochrome glyphs with a separate RGBA atlas for emoji/images. The current RGBA texture consumes 16 MiB per terminal before cells, fonts and history; 16 independent atlases alone consume 256 MiB.
+6. Add bounded pages, live-tile pinning, eviction generations and explicit budgets. An eviction must invalidate affected rows before a slot is reused. Never trade stale glyph references for a higher rate.
+7. Prewarm common glyph/style sets without delaying the usable API. Budget cold shaping/raster work and measure time to a correct image separately from warm-frame speed. Handle CSS webfonts finishing loading, font fallback changes and DPR changes as atlas epochs.
+8. Reuse a device and pipelines on the same rendering owner. For the native worker profile, a shared rendering worker is a possible design; GPU devices cannot simply be assumed transferable between dedicated workers. Measure fairness and fault isolation before adopting pooling.
+9. Keep the frame queue bounded so throughput does not turn into latency. Do not introduce a synchronous GPU fence on every normal frame. A queue-completion fence establishes completed submitted work, not physical screen presentation. [GPUQueue completion semantics](https://gpuweb.github.io/types/interfaces/GPUQueue.html)
+
+GPU timestamps are the right optional probe for render-pass duration. Their availability is feature-dependent; asynchronously resolve/read a bounded query ring and keep unsupported devices functional. This measures GPU command duration, not per-process device utilization. [WebGPU timestamp-query sample](https://webgpu.github.io/webgpu-samples/?sample=timestampQuery)
+
+## Feature completeness and everyday quality
+
+| Area           | Work to cover                                                                                                                                                                                        |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Decorations    | Search matches, active-match colors, overview rulers, foreground/background layers, link underlines and custom decorations without a whole-terminal renderer switch                                  |
+| Visual options | Contrast adjustment, transparency, correct selection tint, cursor modes, faint/inverse/hidden/underline/strike/overline behavior, fractional DPR and letter spacing                                  |
+| Text           | Wide cells, combining marks, supplementary scalars, emoji/ZWJ/variation sequences, fallback fonts, ligatures/character joiners, font bearings and line-height seams                                  |
+| VT behavior    | Chunked UTF-8 and controls, margins/origin, wrap/reflow, erase/insert/delete, alternate screens, synchronized output, queries/replies and scrollback anchors                                         |
+| Input          | Keyboard modes, modifiers, AltGraph/dead keys, IME/composition, mobile keyboards, paste, focus reporting, mouse modes and browser shortcut handling                                                  |
+| Interaction    | Smooth trackpad scrolling, reliable selection across history/reflow, word/line selection, link hit testing, copy formatting, sticky-bottom behavior and resize transitions                           |
+| Accessibility  | Screen readers, keyboard-only navigation, focus, reduced-motion behavior, announcements that do not flood the user, and correct textarea/candidate-window positioning                                |
+| Images         | Explicitly scoped Kitty/iTerm/Sixel support, decoded resource budgets and asynchronous decode/upload; current Ghostty build disables Kitty graphics                                                  |
+| Large history  | Bounded memory, fast search/indexing, stable line identifiers and efficient serialization; preserve synchronous original-addon contracts, and offer separate async native features where appropriate |
+
+Use the pinned core and protocol references as behavioral authorities. Ghostty's VT support does not automatically mean its desktop frontend features or every graphics protocol are exposed through this bridge. [Ghostty architecture](https://ghostty.org/docs/about), [VT protocol reference](https://ghostty.org/docs/vt)
+
+## Reliability, safety and maintainability
+
+- Preserve the terminal model through recoverable GPU failure, sleep/resume and renderer replacement. Rebuild texture/buffer state from authoritative cells, use DOM where that profile permits it, and bound retries.
+- Bound history, atlas pages, queues, image decoding and control-string work. Test extreme combining clusters, malformed byte streams and invalid compositor ranges. Logical text correctness and rendering resource limits need separate policies.
+- Keep remote clipboard writes, external navigation and downloaded resources within explicit host/browser permissions. OSC replies, title changes and link providers must not become an implicit HTML execution path.
+- Stress dispose-during-init, worker termination, queue rejection, observer cleanup, repeated mount/unmount and rapid resizing. Verify resources return close to baseline after teardown.
+- Keep the pinned private xterm boundary small and documented. The optional attribute/content words are optimizations; getter-based paths remain available. Run conformance and installed-package checks before any upstream upgrade.
+- Generate/check ABI layout constants, maintain WGSL/Rust layout assertions, preserve dependency notices, and add native fuzz/sanitizer checks for the C boundary. The existing stable-state owner and synchronous callback discipline must survive performance refactors.
+- Instrument cache occupancy, evictions, upload bytes, queue age, cold glyphs, renderer state, long tasks and high-percentile latency. Expose diagnostics for developers without making telemetry or profiling a mandatory hot-path cost.
+
+## Integration and release quality
+
+Keep the common setup to a constructor, `open`, `write`, and the stylesheet. Continue testing installation as `wraithterm` and as an alias for `@xterm/xterm`, with original addons. Consumers should receive prebuilt assets and never need Rust or Zig toolchains.
+
+Add production fixtures for Vite, Webpack/Rspack, Rollup/esbuild and Next.js/SSR; React Strict Mode, hidden tabs, split panes, CSP, CDN/asset-base loading and versioned caching. Separate the compatible compositor download from the native engine if it materially improves startup. Test ESM and the documented Node require behavior rather than implying universal CommonJS support.
+
+Provide small framework wrappers, a resize helper, binary WebSocket/stream examples, an optional backend PTY example, precise API references and a capability matrix. Framework wrappers should dispose correctly and not require state updates on every frame. Runtime errors should explain an actionable capability/asset problem, while fallback normally keeps the terminal usable.
+
+Ship an experimental npm release first. A stable release requires the correctness, presentation and resource gates below, not only a successful publish dry run.
+
+## Acceptance gates and measurement discipline
+
+| Gate                  | Proposed target / verification                                                                                                                                        |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 120 Hz                | Real 120 Hz presentation tests on named reference hardware; 99% of presentation opportunities met in sustained representative traces; report missed frames and stalls |
+| CPU headroom          | Dense 240×80 reference scene: parser + pack + submission p95 under 4 ms and p99 under 6 ms; cold/rare glyph bursts reported separately                                |
+| Input latency         | Controlled local echo p95 under 16 ms, including scheduling and presentation; distinguish remote transport latency                                                    |
+| Idle                  | No unnecessary redraw; target under 0.5% of one CPU core for a stationary terminal, measured with the same diagnostic settings                                        |
+| Resource scaling      | 1/4/8/16 terminals, bounded atlas/history/queues, fair scheduling and teardown returning resources near baseline                                                      |
+| Compatibility         | Public API, original addons, protocol fixtures, visual options, keyboard/IME and accessibility on all declared support tiers                                          |
+| Recovery              | No lost terminal state after transient surface failure or recoverable device loss; no hanging writes/disposal                                                         |
+| 1000-update/s stretch | Publish grid, styling, input volume, font/DPR, actual submitted/completed frames and latency; require a repeatable named workload                                     |
+
+For this dense scene, 1000 updates/s means about 19.2 million cells, 4.8 million SGR changes and roughly 205 MiB of input per second. The current 20-byte layout would upload about 384 MB of cells per second before other copies. Parsing alone is around a millisecond in prior measurements, so GPU micro-optimization cannot by itself deliver that target.
+
+Build replay corpora from append-only logs, compiler output, tmux/Neovim/btop, color churn, atlas exhaustion, cold Unicode, resizing and multiple terminals. Pin inputs and versions. Alternate before/after order, warm consistently, retain outliers, verify text/geometry/pixels, and report distributions and source/binary hashes. Run CPU/GPU profiling separately from the primary speed benchmark. Use isolated hardware for resource attribution and repeated sustained runs for confidence.
+
+requestAnimationFrame is normally synchronized to the display's refresh cadence; the current headless browser is not a 120 Hz physical-display test. [requestAnimationFrame behavior](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame)
+
+Implementation order: finish allocation reductions and transient-presentation recovery; retain rows through scrolling; support common decorations/contrast on GPU; add latency/recovery/cross-browser gates; then evaluate the compact ABI, smaller compositor artifact and resource pooling. Keep changes only when correctness and the relevant workload both improve.