feat(client)!: own the terminal layer on official libghostty-vt

.gitattributes

@@ -1 +1,2 @@
 * text=auto eol=lf
+*.wasm binary

.gitignore

@@ -8,6 +8,7 @@ pnpm-lock.yaml
 
 # Build outputs
 dist/
+coverage/
 
 # npm publish artifacts
 *.tgz

AGENTS.md

@@ -11,8 +11,10 @@ Follow [docs/development.md](docs/development.md) — Spec & ADR Driven Developm
 ```
 webtty/
 ├── docs/
-│   ├── specs/                   # living architecture specs
+│   ├── specs/                   # living specs; specs/architecture.md maps the code
 │   └── adrs/                    # architecture decision records
+├── src/                         # cli/, server/, pty/, config/, client/ (tree in specs/architecture.md)
+├── scripts/                     # build, architecture and coverage checks, ghostty-vt updater
 └── README.md
 ```
 

README.md

@@ -7,7 +7,7 @@
 [![npm version](https://img.shields.io/npm/v/webtty)](https://www.npmjs.com/package/webtty)
 [![CI](https://github.com/jesse23/webtty/actions/workflows/ci.yml/badge.svg)](https://github.com/jesse23/webtty/actions/workflows/ci.yml)
 
-Terminal UI in the browser. Run CLI/TUI applications in a browser tab, across platforms. Powered by [ghostty-web](https://github.com/coder/ghostty-web).
+Terminal UI in the browser. Run CLI/TUI applications in a browser tab, across platforms. Terminal emulation by [Ghostty](https://ghostty.org)'s official [libghostty-vt](https://github.com/ghostty-org/ghostty), with a renderer and input layer derived from [ghostty-web](https://github.com/coder/ghostty-web).
 
 - [Why webtty?](docs/awesome-web.md#terminal)
 

biome.json

@@ -7,7 +7,13 @@
   },
   "files": {
     "ignoreUnknown": false,
-    "includes": ["**", "!**/node_modules", "!**/dist"]
+    "includes": [
+      "**",
+      "!**/node_modules",
+      "!**/dist",
+      "!src/client/vendor/ghostty-web",
+      "!src/client/vendor/ghostty-vt"
+    ]
   },
   "formatter": {
     "enabled": true,

bunfig.toml

@@ -0,0 +1,4 @@
+# Bun's coverage threshold is one global setting, so this is the common floor of the
+# per-layer targets; scripts/check-coverage.ts enforces each layer (architecture SPEC, ADR 064).
+[test]
+coverageThreshold = { line = 0.85, function = 0.80 }

docs/adrs/011.cli.config-and-help.md

@@ -134,6 +134,8 @@ Several small UX issues surfaced during review:
 - `copyOnSelect: boolean` (default `true`) — auto-copy to clipboard on mouseup, like kitty and Windows Terminal.
 - `rightClickBehavior: "default" | "copyPaste"` (default `"default"`) — `"copyPaste"` copies + clears selection on right-click (Windows Terminal style); `"default"` leaves the native context menu untouched. Invalid values silently fall back to `"default"`.
 
+**Update (ADR 051):** `rightClickBehavior` is `"contextMenu"` (default; `"default"` is still accepted), `"copyPaste"`, `"paste"` or `"none"`, and invalid values fall back to `"contextMenu"`. While the app tracks the mouse, a drag or right-click goes only to the app: webtty selects nothing, copies nothing and shows no menu, unless Shift is held. See [ADR 051](051.client.mouse-tracking-selection-and-right-click.md).
+
 ## Related Decisions
 
 - [ADR 002 — CLI start/stop](002.cli.start-stop.md): established `startServer` and `isServerRunning` used by the no-arg path

docs/adrs/013.client.cursor-style.md

@@ -34,6 +34,10 @@ Intercept DECSCUSR sequences in `src/client/cursor.ts` before passing data to `t
 
 The intercept lives in `src/client/cursor.ts`, isolated from the WebSocket and terminal wiring in `index.ts`. It is removed when ghostty-web implements DECSCUSR natively.
 
+**Update (ADR 041):** DECSCUSR is now applied inside the vendored terminal (`src/client/vendor/ghostty-web/terminal.ts`): `write()` scans the output (`scanDecscusr`, which also carries a sequence split across writes) and keeps the app's shape apart from `options.cursorStyle` / `options.cursorBlink`, which stay the configured default. Ps 0 now clears the app's shape, so the configured cursor shows again (it was blinking block). `cursor.ts` and its call in `index.ts` are deleted. The Coder wasm does not export the cursor style, so the output is still scanned; reading it from the render state is ADR 041 step 5. ([ADR 047](047.client.official-engine-only.md) removed the Coder wasm but kept the scan: the official render state does expose the cursor style, and reading it from there is a follow-up with its own update to this ADR, since Ghostty's blink also follows mode 12.)
+
+**Update (ADR 049):** the scan is gone. The configured style and blink are Ghostty's defaults (`DEFAULT_CURSOR_STYLE` / `DEFAULT_CURSOR_BLINK`), Ghostty applies DECSCUSR, and the renderer draws the shape and blink that the render state reports. Ps 0 and RIS still restore the configured default. Following Ghostty, the shape is kept per screen and DECSTR restores the default. Mode 12 is ignored, as in Ghostty with `cursor-style-blink` set, so only DECSCUSR changes the blink. See [ADR 049](049.client.official-mouse-cursor-paste.md).
+
 ## Considered Options
 
 **Option A: Fix ghostty-web upstream (long-term)**

docs/adrs/015.client.cursor-ghost-repaint.md

@@ -71,6 +71,8 @@ The force repaint is guarded by a `changed` flag and only fires when style or
 blink actually differs from the current value — i.e., on vim mode switches,
 which are infrequent. There is no per-message overhead.
 
+**Update (ADR 041):** the repaint now lives in the vendored renderer (`src/client/vendor/ghostty-web/renderer.ts`): `setCursorStyle()` / `setCursorBlink()` flag a shape change, and the next frame redraws the cursor row as it does when the cursor moves, instead of a synchronous full repaint from `cursor.ts`. It also covers shape changes made through `term.options`.
+
 ---
 
 ## Considered Options

docs/adrs/017.client.mouse-scroll.md

@@ -89,6 +89,10 @@ term.attachCustomWheelEventHandler((e: WheelEvent): boolean => {
 });
 ```
 
+**Update (ADR 041):** the intercept now lives in the vendored terminal (`src/client/vendor/ghostty-web/terminal.ts`): `Terminal.handleWheel` checks mouse tracking on either screen before its arrow-key and viewport paths and fires the SGR reports through `onData` (`wheelTicks`, `wheelSgr`); `mouseScrollSpeed` is a `Terminal` option. The custom wheel handler in `index.ts` now only does pixel-smooth scrollback (ADR 040) when the app does not track the mouse. The cell is measured from the canvas rather than the event target.
+
+**Update (ADR 049):** wheel ticks are encoded by Ghostty's mouse encoder as presses of buttons 4/5 at the pointer's cell, in the format the app chose (SGR 64/65 under 1006, X10 bytes, UTF-8, urxvt or SGR-pixels), with Shift, Alt and Ctrl. `wheelSgr` is removed. See [ADR 049](049.client.official-mouse-cursor-paste.md).
+
 When the custom handler returns `true`, `Terminal.handleWheel` returns early
 and skips the arrow-key loop. When it returns `false` (mouse tracking off),
 the default behaviour is preserved — arrow keys are still sent for apps that

docs/adrs/032.client.kitty-graphics-overlay.md

@@ -52,7 +52,10 @@ Implement the protocol in the webtty client, in front of ghostty-web:
    (`ESC _ G i=<id>;OK ESC \`) are sent back over the WebSocket as if typed.
    Programs that size their output in pixels ask with `CSI 14 t` / `16 t` /
    `18 t`; the client answers these itself from the renderer metrics, because
-   the WASM cannot know pixel size.
+   the WASM cannot know pixel size. (Changed by [ADR 042](042.client.official-vt-engine.md)
+   and [ADR 047](047.client.official-engine-only.md): the official wasm takes
+   the cell size through `OPT_SIZE` and answers them, and the client's replies
+   are deleted.)
 7. **Pixel scale is `devicePixelRatio`.** Sizes reported to programs are
    device pixels, as kitty and Ghostty report them, and images are drawn at
    `size / scale` CSS pixels. Programs rely on this: terminal-browser divides

docs/adrs/033.client.padding-fit.md

@@ -37,6 +37,8 @@ Two changes, both aimed at the visible strip:
    terminal colour, so the client removes it from the theme object before handing the
    theme to ghostty-web.
 
+**Update (ADR 041):** the reserve is now removed in the vendored `FitAddon` (`src/client/vendor/ghostty-web/addons/fit.ts`, `fitDimensions`), and `computeGrid` is gone. The client sets `config.padding` as the container's CSS padding and takes the grid from `FitAddon.proposeDimensions()`; the leftover is still placed by `computeInsets` in `src/client/fit.ts`.
+
 ## Considered Options
 
 ### Option A: Local fit without the reserve, plus `theme.padding` (chosen)

docs/adrs/037.client.multiline-text-paste.md

@@ -22,6 +22,8 @@ Send nonempty text to the PTY regardless of mode 2004: wrap multiline text in br
 - A receiving app without bracketed paste may treat newlines as Enter, potentially submitting commands or accepting an fzf selection. There is no universal, application-independent way to ensure atomic multiline editing in such an app. Users should not paste untrusted multiline commands into an unbracketed shell or prompt. A nested app must enable/propagate mode 2004 for safe multiline editing.
 - Image-only clipboard paste still forwards Ctrl+V, preserving the existing native clipboard path from ADR 014.
 
+**Update (ADR 049):** pastes are encoded by `ghostty_terminal_paste`. With mode 2004 on, every paste is bracketed, single-line text too. Unsafe control bytes become spaces, and without 2004 newlines are sent as `\r`. Nonempty text is still always sent and never refused, and empty text still sends Ctrl+V. See [ADR 049](049.client.official-mouse-cursor-paste.md).
+
 ## Related Decisions
 
 - [ADR 014 — Non-text paste](014.client.image-paste.md)

docs/adrs/038.client.ime-composition-at-cursor.md

@@ -27,6 +27,8 @@ The client takes over how composition is presented. The data path that ghostty-w
 2. **Anchor the textarea at the cursor.** On every animation frame, move the textarea to the pixel position of the terminal cursor cell, writing only the styles that changed. ghostty-web's `onRender` never fires and `onCursorMove` only reports row changes, so neither can drive this. The position is `term.buffer.active.cursorX` / `cursorY`, shifted down by `viewportY` and clamped to the grid, multiplied by the cell size from `renderer.getMetrics()`, and offset by the canvas position inside the container. The textarea stays anchored even before a composition starts, because macOS places the dictation microphone when dictation begins. The textarea gets the cell's line height. macOS then places the dictation microphone and the IME candidate window at the cursor.
 3. **Show a themed preview at the cursor.** Add a small overlay element (`src/client/compose.ts`) with absolute position and `pointer-events: none`, placed over the cursor cell. It is updated from `compositionupdate` (`event.data`) and hidden on `compositionend` or `blur`. It uses the terminal's `fontFamily` and `fontSize`, `theme.foreground` on `theme.background`, and an underline, which is the usual style for uncommitted text. Long text is not wrapped and runs to the right edge. The textarea stays invisible, so the overlay is the only visible copy of the composition.
 
+**Update (ADR 041):** steps 1 and 2 now live in the vendored terminal (`src/client/vendor/ghostty-web/terminal.ts`): `open()` adds the `focusin` and window `focus` redirects, and the render loop anchors the textarea at the cursor cell each frame (`cursorCellOffset`, unit-tested in `src/client/vendor/terminal.test.ts`). `compose.ts` keeps only the overlay, placed from `Terminal.getCursorCellOffset()` on each frame while composing.
+
 ## Considered Options
 
 - **Remove `contenteditable` from the container.** This would stop the stray text node. However, ghostty-web adds the attribute deliberately and its `beforeinput` guard depends on it. Removing it would also leave a focused container that accepts no IME input at all. Sending focus to the textarea fixes the same problem without patching ghostty-web's assumptions.

docs/adrs/039.client.device-pixel-ratio-change.md

@@ -25,12 +25,14 @@ Rounding up keeps `cols × cellWidth × dpr` an integer (cell sizes are whole CS
 - **Patch ghostty-web to compare against `Math.round(...)`** — stops the per-frame resize at the exact ratio, but needs a dependency patch in the build and leaves the seams.
 - **Round up the ratio (chosen)** — no patch, fixes both; costs a larger backing store at fractional ratios.
 
+**Update (ADR 041):** the logic now lives in the vendored renderer (`src/client/vendor/ghostty-web/renderer.ts`): it rounds the ratio up (`wholeDevicePixelRatio`), rounds backing-store sizes the same way in `resize()` and `render()`, and follows changes itself (`watchDevicePixelRatio`); its next frame resizes and repaints the canvas. `index.ts` only schedules a fit on a change. The private-field cast is gone.
+
 ## Consequences
 
 - Moving between displays of different scale keeps text crisp without a reload.
 - At a fractional ratio the canvas no longer resizes every frame (measured at 1.36: 60/s on `main`, 0 with this change).
 - At a fractional ratio the backing store is larger than strictly needed (e.g. 2× instead of 1.36×), and text is drawn at the higher ratio and scaled down by the browser rather than drawn at native resolution.
-- Depends on a private field of ghostty-web's renderer; an upgrade that renames it would silently drop the fix (the cast compiles either way). Revisit once coder/ghostty-web#198 is fixed upstream.
+- Depends on a private field of ghostty-web's renderer; an upgrade that renames it would silently drop the fix (the cast compiles either way). Revisit once coder/ghostty-web#198 is fixed upstream. (Resolved by ADR 041: the renderer owns the logic and the cast is gone.)
 
 ## Related Decisions
 

docs/adrs/040.client.pixel-smooth-scroll.md

@@ -21,6 +21,12 @@ Keep the scroll position as fractional lines in the client (`src/client/smooth-s
 
 The alternate screen and mouse-tracking apps scroll their own view in whole lines, so no pixel offset is possible there. For mouse-tracking apps (herdr, Claude Code's fullscreen TUI, vim `mouse=a`), count pixel wheel deltas by distance instead: one SGR scroll tick per cell height scrolled, 1:1 with the OS like native macOS scrolling. `mouseScrollSpeed` (ADR 017) does not apply to pixel deltas, as Ghostty skips its scroll multiplier for precision scrolls; at 1.5 it made apps scroll visibly faster than native. Previously every wheel event was one tick, so a trackpad's many small events and momentum scrolled far ahead of the fingers. Line and page deltas still count one tick per event.
 
+**Superseded in part by [ADR 043](043.client.scroll-copy-and-overscan.md):** the strip canvas and the `renderLine` swap are gone. The renderer draws rows above and below the viewport on a canvas of its own and shows the offset itself (`setScrollOffset`), moving that canvas by `translateY` and clipping it to the viewport. The bottom edge strip now extends the last row in view, and Kitty images move with the offset.
+
+**Update (ADR 041):** the mouse-tracking tick counting now lives in the vendored terminal (`src/client/vendor/ghostty-web/terminal.ts`, `wheelTicks`), with ADR 017's SGR reports; `index.ts` keeps only the pixel-smooth scrollback handler.
+
+**Update (ADR 045):** a mouse wheel notch in scrollback now glides to its target instead of jumping there. The tick counting for apps is in `src/client/vendor/ghostty-web/wheel.ts`.
+
 ## Consequences
 
 - Trackpad scrolling through scrollback follows the fingers pixel by pixel, with macOS momentum, and no easing lag.