feat(terminal-engine): full xterm.js → alacritty cutover (Phase 1+2+3)

[alxjrvs]

Summary

Complete migration of gnar-term's terminal state engine from xterm.js to alacritty_terminal. Phase 1 (engine + IPC + renderer behind a feature flag), Phase 2 (parity bridges for search, selection/clipboard, links, input, theme/font), and Phase 3 (xterm.js removal + default flip) all shipped in this single branch.

After this PR merges, @xterm/* is gone from src/ and from package-lock.json. AlacrittyTerminalSurface.svelte is the sole terminal renderer. The terminalEngine flag is removed (no escape hatch — the alacritty path is the only path).

What landed (21 cycles, 3 orchestrator hot-fixes)

Phase 1 — engine + IPC + canvas-2d renderer (cycles 1–7):

• terminal_engine Rust module: TerminalEngine trait, AlacrittyEngine wrapping Term<MyListener> + vte::Processor
• GridSnapshot/GridDiff IPC types with serde round-trip + TS mirror; Tauri Channel<TerminalChannelMessage> dispatch
• AlacrittyTerminalSurface.svelte with canvas-2d renderer (16-color palette, SGR attrs, block cursor)
• Initial terminalEngine feature flag in gnar-term.json (default "xterm" during Phase 1)

Phase 1 remediation (cycle-8 + 2 hot-fixes):

• Wired the previously-deferred PTY → bridge data pipe so the engine actually receives bytes
• detach_alacritty_engine Tauri command + kill_pty safety-net cleanup
• textBaseline survives canvas resize (HTML spec §4.12.5.1 fix); poisoned-mutex logging in pty reader thread

Smoke-note hand-offs (cycles 9–11):

• 256-color cube + grayscale ramp + ATTR_ITALIC rendering
• MyListener event surfacing (Bell/Title/PtyWrite/etc. drained and logged)
• PtyBridge::viewport_dims cached as fields (no more per-feed full-grid snapshot)

Alacritty alignment audit + resolution (cycle-12):

• PTY write-back routing: Event::PtyWrite and Event::ColorRequest now invoke the formatter against term.colors() and write the response — programs no longer hang on OSC color queries
• Full xterm key encoding: F1–F12, Home/End/PageUp/PageDown/Insert/Delete, Ctrl-letter combos, Alt-prefix, modifier-encoded variants
• CursorPos.shape (Block/Beam/Underline/HollowBlock/Hidden) via RenderableCursor::new — neovim insert-mode beam cursor renders correctly
• Expanded attrs bitfield (DIM, HIDDEN, STRIKEOUT, WIDE_CHAR) + zerowidth combining marks preserved in Cell.ch

Final deferrals closed (cycles 13–15):

• OSC 52 clipboard read/write routed through tauri-plugin-clipboard-manager via a ClipboardAccess trait (testable independent of Tauri)
• ColorIndex::Named wire-format variant preserves Foreground/Background/Cursor/Dim*/BrightForeground semantics — themes overriding via OSC 10/11/12 actually reach the renderer
• Snapshot generation switched to Grid::display_iter so display_offset is honored (scrollback no longer shows the wrong rows)

Phase 2 parity (cycles 16–20):

• search-bridge.ts wires alacritty_terminal::regex_search_left/right to the search-result API (cycle-16)
• mouse-handler.ts for selection + middle-click paste + OSC 52 read response (cycle-17)
• link-overlay.ts + OSC 7 cwd tap per-pane (cycle-18)
• paste-handler.ts bracketed paste mode + full key-corpus + scroll anchor (cycle-19)
• theme-bridge.ts runtime theme + font hot-reload (cycle-20)

Phase 3 cutover (cycle-21):

• @xterm/xterm, @xterm/addon-fit, @xterm/addon-search, @xterm/addon-webgl removed from package.json
• src/types/xterm.d.ts and src/lib/components/TerminalSurface.svelte deleted
• terminal-service.ts xterm code paths removed (flushPtyBuffer HWM backpressure, clearTextureAtlas hooks, xterm-style linkHandler, xterm theme mapping) — ~660 lines deleted
• FindBar.svelte rewired to alacritty's search bridge
• PaneView.svelte renders AlacrittyTerminalSurface unconditionally; terminalEngine field + getter deleted
• cutover.test.ts integration test asserts no xterm imports remain and the cutover surface is wired
• e2e-smoke-notes.md expanded with cutover QA plan
• package-lock.json scrubbed of the four @xterm/* transitive entries

Stats

• 28 cycles' worth of commits (21 planned + 1 Phase-1 remediation + 3 orchestrator hot-fixes + 3 smoke-note hand-offs already counted in the 21)
• ~3,900 insertions / ~660 deletions in src/ net of xterm removal
• 83 Rust tests passing (cargo) + 2,412 frontend tests passing (vitest, 7 skipped)
• cargo clippy -- -D warnings clean
• All pre-commit hooks pass (rust-fmt, prettier, eslint, typecheck, svelte-check, rust-clippy, rust-check) and the pre-push npm test hook passes

Verification sweep

$ rg -n "@xterm/|searchAddon|FitAddon|WebglAddon|xterm\.d\.ts" src/
(zero hits)

$ npm ls @xterm/addon-fit @xterm/addon-search @xterm/addon-webgl @xterm/xterm
gnar-term@0.5.0
└── (empty)

Test plan

• Pull this branch locally
• npm install — verify package-lock has no @xterm/* entries
• npm test — verify 2412 vitest tests pass (7 skipped expected)
• cargo test --manifest-path src-tauri/Cargo.toml --package gnar-term --lib terminal_engine — 83 tests pass
• cargo clippy --manifest-path src-tauri/Cargo.toml --lib --tests -- -D warnings — clean
• npm run build — full Tauri build succeeds
• macOS smoke — launch the built app:
  • Open a new pane; type a command, see output rendered through the canvas
  • ls --color=auto renders 16-color ANSI + extended palette correctly
  • git log --color=always | head -50 paginates and colors correctly
  • Resize the pane (drag divider): grid reflows, glyph alignment stays correct, cursor lands in the right cell
  • Open nvim (or any program that queries OSC 10/11 colors): app does NOT hang
  • Highlight text → middle-click pastes via OSC 52
  • Open a URL printed in the terminal by clicking it (link overlay)
  • cd somewhere → check the pane title reflects the OSC 7 cwd
  • Ctrl+F opens FindBar → search returns highlighted matches → next/prev cycles through them
  • Change theme in settings → terminal recolors live without a relaunch
  • PageUp scrolls back; PageDown scrolls forward; cursor tracks correctly through wraps
• Linux smoke (WebKitGTK) — same checklist as macOS where applicable
• MCP read_output — invoke against an alacritty pane: returns recent terminal text (whatever the bridge plumbing routed it to per cycle-21 prose)

Files of interest

• src-tauri/src/terminal_engine/ — the entire engine module
• src-tauri/src/terminal_engine/pty_bridge.rs — bridge between the PTY reader thread and the engine, plus the clipboard/PTY-write event routing
• src/lib/components/AlacrittyTerminalSurface.svelte — single terminal renderer
• src/lib/components/alacritty/ — five Phase-2 parity bridges
• src/lib/components/cutover.test.ts — proves no xterm imports remain
• docs/implement/2026-05-16-alacritty-terminal-engine/ — full audit trail (intent.md, plan.md, review.md, ship.md, journal.jsonl, per-cycle prose, e2e-smoke-notes.md) — kept locally per project policy (docs/implement/ is gitignored)

🤖 Generated with Claude Code

[alxjrvs]

Phase 2 hand-off wave landed (wave 7) — three additional cycles addressing the deferred items from e2e-smoke-notes.md:

• cycle-9 (5a1c47d): 256-color palette cube + ATTR_ITALIC SGR rendering — alacritty-renderer.ts now resolves the full xterm 256-color space (6×6×6 cube + 24-step grayscale) and renders italic glyphs (incl. combined bold+italic). +12 vitest tests.
• cycle-10 (759308c): MyListener event surfacing — events from alacritty_terminal::Term are now drained per byte-feed and logged. Adapted from PtyWrite-only to the actual emit shape (alacritty uses Event::ColorRequest for OSC color queries). Full PTY write-back routing remains a follow-up (TODO(pty-write-routing) in pty_bridge.rs).
• cycle-11 (5bc772e): cache viewport dims as PtyBridge fields — removes the per-feed full-grid snapshot just to read 2 u16s. +1 regression test.

Updated stats: 26 cargo + 2209 vitest tests passing; clippy -D warnings clean; all pre-commit/pre-push hooks green.

The test plan above is unchanged — the additions are behind the same feature flag (terminalEngine: "alacritty"), and the xterm.js default path remains byte-identical.

[alxjrvs]

TODO-resolution + alacritty-alignment wave landed (wave 8 — cycle-12):

• PtyWrite routing wired. PtyBridge now owns a pty_writer (independent take_writer() clone at attach_alacritty_engine time). On Event::PtyWrite, response bytes are written + flushed to the PTY. On Event::ColorRequest(index, formatter), the engine's color slot is looked up and the formatter is evaluated to produce the OSC response. Programs that issue OSC 4/10/11/12 color queries (nvim --termguicolors detection, bat, ls --color=auto) no longer hang.
• Full key encoding. alacritty-key-encoder.ts now covers F1-F12 (DEC PF1-PF4 + xterm ~-terminated), Home/End/PageUp/PageDown/Insert/Delete, Ctrl-letter combos (Ctrl+A → \x01, etc.), Alt-prefix for printables, and modifier-encoded variants (\x1b[1;5A for Ctrl+Up etc.).
• Cursor shape preserved. CursorPos carries a shape: { kind: "block" | "beam" | "underline" | "hollow_block" | "hidden" } field sourced from RenderableCursor::new(&term). Renderer branches on shape — neovim's insert-mode beam cursor now renders correctly.
• Attribute coverage expanded. Added ATTR_DIM, ATTR_HIDDEN, ATTR_STRIKEOUT, ATTR_WIDE_CHAR to the bitfield and the renderer. DIM darkens fg, HIDDEN renders fg=bg, STRIKEOUT draws a midline rect, WIDE_CHAR spaces correctly across two cells.
• Combining marks no longer dropped. map_row now appends acell.zerowidth() characters to Cell.ch, so accented letters and emoji ZWJ sequences round-trip intact.

Stats: 34 cargo + 2248 vitest tests passing (up from 26 + 2209), all 7 pre-commit hooks green, clippy -D warnings clean.

Intentionally deferred (out-of-scope per intent.md): OSC 52 clipboard plumbing (TODO(clipboard-osc52)), Color::Named wire-format change (would require coordinated TS/Rust schema bump), display_iter for scrollback (Phase 2 has its own scrollback design).

The alignment audit from earlier (F-1 through F-9) is documented in cycles/cycle-12.md alongside the rationale for which findings landed here vs. which remain for the migration's full Phase 2 run.