zidane-ui 9.0.4 → 9.1.3

package/src/terminal/HostTerminalSurface.tsx

@@ -1,911 +0,0 @@
-/**
- * One view of one terminal of a `TerminalHost`: a ghostty-web `Terminal`
- * (`@tahul/ghostty-web`) on a canvas, attached to the host with its own
- * client id. The library loads lazily through `loadGhostty` (the package
- * inlines its 400 KB wasm, which stays out of the main chunk until a
- * terminal is shown). `TerminalSurface` is the same canvas over any process
- * (a `TerminalAdapter`); this one runs the host's attach, replay and size
- * protocol.
- *
- * Output never touches React state: the store hands signals to the sink
- * below, which writes into the terminal, keeps its cursor (`planChunk`)
- * and acknowledges what was written (throttled). The same terminal may be
- * shown in the drawer and the panel tab at once; each view attaches on
- * its own and the last focused one owns the PTY size.
- *
- * Keys: the host carries `data-zg-keyscope="editor"`, so bare ctrl+letter
- * chords belong to the shell. Cmd chords and app bindings skip the
- * terminal (marked composing so ghostty ignores them without calling
- * preventDefault) and reach the app / the menu; Cmd+C copies a selection,
- * Cmd+V is the native paste, which the library brackets when asked.
- *
- * Links: the library finds OSC 8 hyperlinks and URLs and hands every click
- * to `linkHandler` (`linkTarget` decides where it goes); our provider adds
- * file paths and scheme-less local servers. Where they open is the app's
- * (`TerminalAppActions.openUrl` / `openFile`).
- *
- * Mouse: while the program tracks the mouse (vim, htop, less --mouse) the
- * library reports clicks, drags and the wheel to it and doesn't select;
- * Shift gives them back to the terminal (select, scroll, our menu).
- */
-import type { IBufferRange, ILink, ILinkHandler, Terminal } from '@tahul/ghostty-web';
-import {
-  OutputHistory,
-  parseBindingSpecs,
-  TERMINAL_HISTORY_MAX_CHARS,
-  TERMINAL_VIEW_MAX_LINES,
-  TERMINAL_VIEW_SCROLLBACK,
-} from 'zidane/chat/pure';
-import { useEffect, useMemo, useRef, useState, type KeyboardEvent as ReactKeyboardEvent } from 'react';
-
-import { useAppearanceState, usePalette } from '../appearance/AppearanceProvider';
-import { RowActionsMenu, type RowActionItem } from '../components/RowActionsMenu';
-import { getMergedKeybindings, type KeyAction, type KeybindingsHost } from '../keybindings/headless';
-import { bindingAllowedIn } from '../keybindings/headless/key-scope';
-import { useKeybindingsHost } from '../keybindings/KeybindingsProvider';
-import { matchesBinding } from '../keybindings/match';
-import { loadGhostty, openTerminal } from './ghostty';
-import { terminalFont } from './grid-size';
-import { detectLinks, linkTarget, resolveTerminalPath, serverOnlyLink } from './headless/links';
-import { ACK_EVERY_MS, planChunk, planReset, shouldAck } from './headless/output-cursor';
-import { feedSlices, yieldToEventLoop } from './headless/replay';
-import type { TerminalScope } from './headless/scope';
-import { macTerminalKey } from './keys';
-import { terminalTheme } from './theme';
-import { useSymbolsFontUrl, useTerminalActions, useTerminalStore } from './TerminalProvider';
-import { useTerminalLabels } from './useTerminalLabels';
-
-const SCROLLBACK = TERMINAL_VIEW_SCROLLBACK;
-const FIT_DEBOUNCE_MS = 40;
-const CLAIM_EVERY_MS = 2_000;
-/** A history replay parses this long per task before giving the event loop a turn. */
-const REPLAY_BUDGET_MS = 8;
-/** Replay writes are this big: small enough to check the budget often, big enough to keep per-write overhead low. */
-const REPLAY_SLICE_CHARS = 16 * 1024;
-/** Live output bigger than this (heavy output, one batch from the host) is fed in time-boxed slices too. */
-const LIVE_SLICE_MIN = 64 * 1024;
-const CLEAR = '\x1bc\x1b[3J';
-
-/** ghostty-web keeps a render loop for as long as a terminal is open; these TS-private methods pause it. */
-interface RenderLoop {
-  cancelRenderLoop?: () => void;
-  startRenderLoop?: () => void;
-}
-
-/** Props for {@link HostTerminalSurface}. */
-export interface HostTerminalSurfaceProps {
-  /** Whose terminal (handed to the app's link and chat actions). */
-  scope: TerminalScope;
-  /** The terminal this view attaches to. */
-  terminalId: string;
-  /** The terminal's label, for "Add to chat" excerpts. */
-  label: string;
-  /** Where relative paths printed by the shell resolve; empty = don't link files. */
-  cwd: string;
-  /** Take keyboard focus on mount (the user opened or picked this terminal). */
-  autoFocus?: boolean;
-  /** A new value takes focus again while `autoFocus` stays on (the terminal shown on request a second time). */
-  focusSeq?: number;
-  /** The PTY's columns (from the host): the grid always has its size, whatever this view's container fits. */
-  ptyCols: number;
-  /** The PTY's rows. */
-  ptyRows: number;
-  /** `TerminalInfo.sizeSeq` of that size: a view keeps the newest, whichever route it came by. */
-  ptySeq: number;
-  /** The machine the terminal runs on when it is not this one: its loopback links are not this computer's. */
-  serverName?: string | null;
-  /** Extra classes on the root. */
-  className?: string;
-}
-
-/** Handlers the effect reads through a ref, so link clicks see fresh context without re-creating the terminal. */
-interface LinkContext {
-  openUrl: (url: string, external: boolean) => void;
-  openFile: (path: string, event: MouseEvent, at?: { line: number; column?: number }) => void;
-  cwd: string;
-  /** Why a web link is not opened from here (`serverOnlyLink`), else `null`. */
-  unreachable: (url: string) => string | null;
-  /** Show (or clear) a hovered link's tooltip. */
-  tip: (text: string | null) => void;
-}
-
-/**
- * One view of one of the host's terminals, attached for as long as it is mounted.
- *
- * @param props - The terminal, its scope and label, where its paths resolve, focus and the PTY's size.
- */
-export function HostTerminalSurface({
-  scope,
-  terminalId,
-  label,
-  cwd,
-  autoFocus = false,
-  focusSeq = 0,
-  ptyCols,
-  ptyRows,
-  ptySeq,
-  serverName = null,
-  className,
-}: HostTerminalSurfaceProps) {
-  const hostRef = useRef<HTMLDivElement>(null);
-  const store = useTerminalStore();
-  const actions = useTerminalActions();
-  const symbolsFontUrl = useSymbolsFontUrl();
-  const keybindings = useKeybindingsHost();
-  const labels = useTerminalLabels();
-  const termRef = useRef<Terminal | null>(null);
-  // Focus claims the PTY size for this view (set by the effect, which owns the client id).
-  const claimRef = useRef<() => void>(() => undefined);
-  /*
-   * The grid's size is the PTY's. It arrives two ways (the attach reply, the
-   * terminals list), which can cross: the one with the higher `sizeSeq` wins,
-   * or a stale size sticks (a full-screen app then draws past the grid).
-   */
-  const gridSeq = useRef(-1);
-  /** Told when the grid changed size (the view waits for its claimed size before showing). */
-  const gridChanged = useRef<(() => void) | null>(null);
-  /** Resizes a grid that has content by redrawing it (set by the effect; see `redrawAt`). */
-  const redraw = useRef<((cols: number, rows: number) => void) | null>(null);
-  const applyGrid = (term: Terminal | null, cols: number, rows: number, seq: number) => {
-    if (!term || seq < gridSeq.current || cols < 2 || rows < 2) return;
-    gridSeq.current = seq;
-    if (term.cols === cols && term.rows === rows) return;
-    if (redraw.current) redraw.current(cols, rows);
-    else term.resize(cols, rows);
-    gridChanged.current?.();
-  };
-  // The PTY's size when the terminal is created: it starts at that size, never at a default.
-  const ptySize = useRef({ cols: ptyCols, rows: ptyRows });
-  ptySize.current = { cols: ptyCols, rows: ptyRows };
-  const applyGridRef = useRef(applyGrid);
-  applyGridRef.current = applyGrid;
-  const [failed, setFailed] = useState<string | null>(null);
-  const [menu, setMenu] = useState<{ x: number; y: number; selection: string } | null>(null);
-
-  const palette = usePalette();
-  const theme = useMemo(() => terminalTheme(palette), [palette]);
-  const themeKey = useMemo(() => JSON.stringify(theme), [theme]);
-  const { fonts, fontSizes } = useAppearanceState();
-  const { family: fontFamily, size: fontSize } = terminalFont(fonts.mono, fontSizes.code);
-
-  const links = useRef<LinkContext | null>(null);
-  links.current = {
-    // Without the app's file opener, paths don't link.
-    cwd: actions.openFile ? cwd : '',
-    unreachable: (url) => serverOnlyLink(url, serverName, labels.terminalLinkOnServer),
-    tip: (text) => {
-      const mount = hostRef.current;
-      if (!mount) return;
-      if (text) mount.title = text;
-      else mount.removeAttribute('title');
-    },
-    openUrl: (url, external) => {
-      if (actions.openUrl) actions.openUrl(scope, url, external, cwd);
-      else window.open(url, '_blank');
-    },
-    openFile: (path, event, at) => {
-      const abs = resolveTerminalPath(path, cwd);
-      if (abs) actions.openFile?.(scope, abs, event, at);
-    },
-  };
-  const labelRef = useRef(label);
-  labelRef.current = label;
-  // Read when the terminal is created: `autoFocus` can turn on while ghostty loads (Show terminal).
-  const autoFocusRef = useRef(autoFocus);
-  autoFocusRef.current = autoFocus;
-
-  // Font changes apply live; theme changes re-create the terminal (ghostty-web
-  // does not repaint a new theme after open) and re-attach from history.
-  useEffect(() => {
-    const term = termRef.current;
-    if (!term) return;
-    if (term.options.fontFamily !== fontFamily) term.options.fontFamily = fontFamily;
-    if (term.options.fontSize !== fontSize) term.options.fontSize = fontSize;
-  }, [fontFamily, fontSize]);
-
-  // The grid follows the PTY (another view may own its size): output always matches the grid it is drawn in.
-  useEffect(() => {
-    applyGrid(termRef.current, ptyCols, ptyRows, ptySeq);
-  }, [ptyCols, ptyRows, ptySeq]);
-
-  // Kept mounted across tab switches: picking this tab again focuses it (creation handles the first time).
-  useEffect(() => {
-    if (autoFocus) termRef.current?.focus();
-  }, [autoFocus, focusSeq]);
-
-  useEffect(() => {
-    const host = hostRef.current;
-    if (!host) return undefined;
-    let disposed = false;
-    const clientId = crypto.randomUUID();
-    const api = store.host;
-    let term: Terminal | null = null;
-    let fitTimer = 0;
-    let ackTimer = 0;
-    let observer: ResizeObserver | null = null;
-    let unregister: (() => void) | null = null;
-    let onVisibility: (() => void) | null = null;
-    let onFocusChange: ((event: FocusEvent) => void) | null = null;
-    // What fits this view's container (null while hidden); set once the terminal exists.
-    let propose: () => { cols: number; rows: number } | null = () => null;
-
-    // Stream position (what has been handed to the terminal) and what was written + acked.
-    let pos = 0;
-    let written = 0;
-    const ack = { acked: 0, at: 0 };
-    let attached = false;
-    let attachSeq = 0;
-    let queued: { kind: 'output' | 'reset'; offset: number; data: string }[] = [];
-    let lastClaim = 0;
-
-    const sendAck = () => {
-      ackTimer = 0;
-      if (disposed || written <= ack.acked) return;
-      ack.acked = written;
-      ack.at = Date.now();
-      void api.ack(terminalId, clientId, written).catch(() => undefined);
-    };
-    const maybeAck = () => {
-      if (shouldAck(ack, written, Date.now())) sendAck();
-      else if (!ackTimer && written > ack.acked) ackTimer = window.setTimeout(sendAck, ACK_EVERY_MS);
-    };
-    /*
-     * ghostty-web parses synchronously inside `write` (its callback only
-     * waits for the next frame, which a hidden window may never paint), so
-     * what was written is known on return. Two quirks: an empty write throws
-     * (a zero-length wasm alloc), and `reset()` swaps the wasm terminal under
-     * the selection and link layers, so a reset goes through the parser as
-     * RIS instead.
-     */
-    let fresh = true;
-    /*
-     * The emulator answers queries in the output (cursor position, device
-     * attributes) synchronously, from inside `term.write`, through `onData`.
-     * Those replies are not typing: dropped for replayed history (the program
-     * that asked is long gone, and the shell would read them as input:
-     * `;1R;1R…`), tagged as replies for live output (the host keeps only the
-     * size owner's, so two views never answer twice).
-     */
-    let writing: 'history' | 'live' | null = null;
-    /*
-     * What this view drew, capped like the host's history and by the lines
-     * a replay can use (its scrollback and screen; all of a program still on
-     * the alternate screen). The library's
-     * resize reflows a grid with content badly (lines overlap instead of
-     * rewrapping, and stay that way), so a view never resizes one: it clears,
-     * resizes the empty grid and draws this again (see `rebuild`). Plain
-     * output wraps as in any terminal; full-screen programs repaint on the
-     * resize anyway.
-     */
-    const drawn = new OutputHistory(TERMINAL_HISTORY_MAX_CHARS, { maxLines: TERMINAL_VIEW_MAX_LINES });
-    const feed = (data: string, kind: 'history' | 'live') => {
-      if (!term || !data) return;
-      writing = kind;
-      try {
-        term.write(data);
-      } finally {
-        writing = null;
-      }
-    };
-
-    /*
-     * Rendering pauses while nothing can be seen (a background tab, a closed
-     * panel, a hidden window, a replay in progress): the library's loop would
-     * otherwise run every frame for every mounted terminal. `resize` restarts
-     * the loop by itself, hence `resizeGrid`.
-     */
-    let viewHidden = false;
-    let loopPaused = false;
-    // The cursor blinks only in the terminal being typed into: a blinking one redraws its row every frame.
-    let focused = false;
-    const updateRendering = () => {
-      if (!term) return;
-      const pause = viewHidden || replayHidden;
-      if (pause === loopPaused) return;
-      loopPaused = pause;
-      const loop = term as unknown as RenderLoop;
-      const canPause = typeof loop.cancelRenderLoop === 'function' && typeof loop.startRenderLoop === 'function';
-      term.options.cursorBlink = focused && !pause;
-      if (!canPause) return;
-      if (pause) {
-        loop.cancelRenderLoop!();
-        return;
-      }
-      // Output written while paused left the canvas behind: repaint it all, then let the loop take over.
-      if (term.renderer && term.wasmTerm) term.renderer.render(term.wasmTerm, true, term.viewportY, term, 0);
-      loop.startRenderLoop!();
-    };
-    const resizeGrid = (cols: number, rows: number) => {
-      if (!term) return;
-      term.resize(cols, rows);
-      if (loopPaused) (term as unknown as RenderLoop).cancelRenderLoop?.();
-    };
-
-    /*
-     * Rebuilding the grid (an attach, a resize) replays what the terminal
-     * can keep (see `OutputHistory.replay`) in time-boxed slices, so a big
-     * history never blocks the renderer. A replay that outlasts its first
-     * slice hides the view until it is done: a half-drawn grid is never on
-     * screen. Output arriving meanwhile goes to `drawn` and is fed after the
-     * replay, in order, as live output (acked as it is fed); a newer rebuild
-     * supersedes a running one. Started from a microtask so rebuilds asked
-     * for in the same task (attach resizes, then replaces) replay once.
-     * A big batch of live output goes through the same loop (`catchUp`),
-     * without a history to replay first and without hiding the view.
-     */
-    let replayGen = 0;
-    let replaying = false;
-    let replayHidden = false;
-    // Stream offset of the output fed to the terminal.
-    let fed = 0;
-    const rebuild = (upTo: number) => {
-      const gen = ++replayGen;
-      replaying = true;
-      queueMicrotask(() => void runReplay(gen, upTo));
-    };
-    const catchUp = () => {
-      const gen = ++replayGen;
-      replaying = true;
-      void runReplay(gen, null);
-    };
-    /** `upTo`: replay the history up to there first; `null`: only feed the live output from `fed` on. */
-    const runReplay = async (gen: number, upTo: number | null) => {
-      const current = () => gen === replayGen && !disposed && term !== null;
-      if (!current()) return;
-      let kind: 'history' | 'live' = upTo === null ? 'live' : 'history';
-      let buf = upTo === null ? drawn.text(fed) : drawn.replay(SCROLLBACK + term!.rows, upTo);
-      let i = 0;
-      let deadline = performance.now() + REPLAY_BUDGET_MS;
-      for (;;) {
-        const from = i;
-        i = feedSlices(buf, i, REPLAY_SLICE_CHARS, deadline, (slice) => feed(slice, kind));
-        if (kind === 'live' && i > from) {
-          fed += i - from;
-          if (fed > written) written = fed;
-          maybeAck();
-        }
-        if (i >= buf.length) {
-          if (kind === 'history' && upTo !== null) {
-            kind = 'live';
-            fed = upTo;
-            if (upTo > written) written = upTo;
-            maybeAck();
-          }
-          if (fed < drawn.start) {
-            // More output arrived during the replay than the history keeps: start over from what it has.
-            feed(CLEAR, 'history');
-            rebuild(drawn.end);
-            return;
-          }
-          buf = drawn.text(fed);
-          i = 0;
-          if (!buf) break;
-          if (performance.now() < deadline) continue;
-        }
-        if (!replayHidden && upTo !== null) {
-          replayHidden = true;
-          if (mountEl) mountEl.style.opacity = '0';
-          updateRendering();
-        }
-        await yieldToEventLoop();
-        if (!current()) return;
-        deadline = performance.now() + REPLAY_BUDGET_MS;
-      }
-      replaying = false;
-      if (replayHidden) {
-        replayHidden = false;
-        updateRendering();
-        showSoon();
-      }
-    };
-
-    const redrawAt = (cols: number, rows: number) => {
-      if (!term) return;
-      if (fresh || drawn.size === 0) {
-        resizeGrid(cols, rows);
-        return;
-      }
-      feed(CLEAR, 'history');
-      resizeGrid(cols, rows);
-      rebuild(drawn.end);
-    };
-    redraw.current = redrawAt;
-
-    const replace = (offset: number, data: string) => {
-      if (!term) return;
-      if (!fresh) feed(CLEAR, 'history');
-      fresh = false;
-      pos = offset;
-      written = Math.min(written, offset);
-      drawn.reset(offset, data);
-      rebuild(offset);
-    };
-
-    const apply = (offset: number, data: string) => {
-      if (!term) return;
-      const plan = planChunk(pos, offset, data);
-      if (plan.kind === 'drop') return;
-      if (plan.kind === 'gap') {
-        void attach();
-        return;
-      }
-      pos = plan.next;
-      drawn.push(plan.data);
-      // A replay in progress feeds it once it has caught up.
-      if (replaying) return;
-      if (plan.data.length > LIVE_SLICE_MIN) {
-        catchUp();
-        return;
-      }
-      feed(plan.data, 'live');
-      fed = pos;
-      if (pos > written) written = pos;
-      maybeAck();
-    };
-
-    // A reset that overlaps what this view has appends the rest (no clear, scrollback kept); see `planReset`.
-    const reset = (offset: number, data: string) => {
-      const plan = planReset(fresh, pos, offset, data);
-      if (plan.kind === 'append') apply(plan.offset, plan.data);
-      else replace(offset, data);
-    };
-
-    /*
-     * Sizing, tmux-style: this view never resizes its own grid. It asks for
-     * what fits its container, and the grid follows the PTY's size (the
-     * `ptyCols` / `ptyRows` props) in lockstep with the program's redraw, so
-     * output is always laid out for the grid it is drawn in. `claim`: this
-     * view is the one being looked at (shown, focused, typed into) and takes
-     * the size; otherwise the request only applies when nobody owns it.
-     */
-    const resize = (claim: boolean) => {
-      if (!term || !attached) return;
-      const size = propose();
-      if (!size) return;
-      if (claim) lastClaim = Date.now();
-      void api.resize(terminalId, clientId, size.cols, size.rows, claim).catch(() => undefined);
-    };
-
-    async function attach(): Promise<void> {
-      const seq = ++attachSeq;
-      attached = false;
-      queued = [];
-      try {
-        const result = await api.attach(terminalId, clientId);
-        // Unmounted mid-attach: the cleanup's detach may have landed first, so detach again.
-        if (disposed) void api.detach(terminalId, clientId).catch(() => undefined);
-        if (disposed || seq !== attachSeq) return;
-        // History was produced at the PTY's size: the grid takes that size (never reflowed here).
-        applyGridRef.current(term, result.terminal.cols, result.terminal.rows, result.terminal.sizeSeq);
-        replace(result.offset, result.data);
-        ack.acked = result.offset;
-        attached = true;
-        setFailed(null);
-        const pending = queued;
-        queued = [];
-        for (const q of pending) (q.kind === 'reset' ? reset : apply)(q.offset, q.data);
-        // Being shown means being looked at: take the size (no-op while hidden), then show it at that size.
-        settle(true);
-      } catch (err) {
-        if (!disposed && seq === attachSeq) setFailed(err instanceof Error ? err.message : String(err));
-        reveal();
-      }
-    }
-
-    /*
-     * Nothing half-drawn is ever on screen: the mount stays transparent (opacity,
-     * which no child can override) until
-     * the terminal has its history and the size this view asked for (a new
-     * size only arrives after the host resized the PTY, so for a moment the
-     * grid still has the old one). Capped, so a lost reply never keeps it
-     * blank. Shown two frames later: ghostty paints on the next frame.
-     */
-    let mountEl: HTMLElement | null = null;
-    let revealTimer = 0;
-    // Hidden until sized (`hide` / `reveal`); a long replay holds it hidden on its own (`replayHidden`).
-    let settling = false;
-    const hide = () => {
-      settling = true;
-      if (mountEl) mountEl.style.opacity = '0';
-    };
-    const showSoon = () =>
-      requestAnimationFrame(() =>
-        requestAnimationFrame(() => {
-          if (!disposed && mountEl && !settling && !replayHidden) mountEl.style.opacity = '';
-        }),
-      );
-    const reveal = () => {
-      window.clearTimeout(revealTimer);
-      gridChanged.current = null;
-      settling = false;
-      showSoon();
-    };
-    const settle = (claim: boolean) => {
-      const target = propose();
-      resize(claim);
-      // Not laid out yet (a panel sliding in, a background tab): shown once it is, from the observer.
-      if (!target) {
-        hide();
-        return;
-      }
-      if (!term || (target.cols === term.cols && target.rows === term.rows)) {
-        reveal();
-        return;
-      }
-      hide();
-      gridChanged.current = () => {
-        if (term && term.cols === target.cols && term.rows === target.rows) reveal();
-      };
-      window.clearTimeout(revealTimer);
-      revealTimer = window.setTimeout(reveal, 400);
-    };
-
-    claimRef.current = () => resize(true);
-    unregister = store.addView(terminalId, {
-      output: (offset, data) => (attached ? apply(offset, data) : queued.push({ kind: 'output', offset, data })),
-      reset: (offset, data) => (attached ? reset(offset, data) : queued.push({ kind: 'reset', offset, data })),
-      reattach: () => void attach(),
-    });
-
-    // The fonts first: cells are measured once, from the font the canvas has when it opens.
-    void Promise.all([
-      loadGhostty(symbolsFontUrl),
-      document.fonts.load(`${fontSize}px ${fontFamily}`).catch(() => []),
-    ]).then(
-      ([{ Terminal: GhosttyTerminal, FitAddon }]) => {
-        if (disposed) return;
-        const mount = host.querySelector<HTMLElement>('[data-terminal-mount]');
-        if (!mount) return;
-        mountEl = mount;
-        hide();
-        term = new GhosttyTerminal({
-          ...(ptySize.current.cols >= 2 && ptySize.current.rows >= 2 ? ptySize.current : {}),
-          fontFamily,
-          fontSize,
-          theme,
-          scrollback: SCROLLBACK,
-          cursorBlink: false,
-          cursorStyle: 'block',
-          linkHandler: libraryLinkHandler(links),
-        });
-        termRef.current = term;
-        openTerminal(term, mount);
-        // The wasm grid starts on unzeroed memory (cells of a terminal freed earlier):
-        // rows no output reaches show them until a clear. Nothing answers RIS, so no replies.
-        term.write(CLEAR);
-        onFocusChange = (event) => {
-          const inside = event.type === 'focusin' || mount.contains(event.relatedTarget as Node | null);
-          if (inside === focused) return;
-          focused = inside;
-          if (term) term.options.cursorBlink = focused && !loopPaused;
-        };
-        mount.addEventListener('focusin', onFocusChange);
-        mount.addEventListener('focusout', onFocusChange);
-        const fit = new FitAddon();
-        term.loadAddon(fit);
-        // Hidden (panel closed, drawer animating shut, a background tab): nothing to propose.
-        propose = () => {
-          if (disposed || mount.clientWidth === 0 || mount.clientHeight === 0) return null;
-          const size = fit.proposeDimensions();
-          return size && size.cols >= 2 && size.rows >= 2 ? { cols: size.cols, rows: size.rows } : null;
-        };
-        term.onData((data) => {
-          if (writing === 'history') return;
-          if (writing === 'live') {
-            void api.write(terminalId, data, { clientId, response: true }).catch(() => undefined);
-            return;
-          }
-          if (Date.now() - lastClaim > CLAIM_EVERY_MS) resize(true);
-          void api.write(terminalId, data, { clientId }).catch(() => undefined);
-        });
-        term.registerLinkProvider({
-          provideLinks: (y, callback) => callback(linksOnRow(term, y, links)),
-        });
-        // Container changes propose a new size; coming back into view (a tab or panel shown again) claims it.
-        let wasHidden = mount.clientWidth === 0 || mount.clientHeight === 0;
-        onVisibility = () => {
-          viewHidden = wasHidden || document.hidden;
-          updateRendering();
-        };
-        onVisibility();
-        document.addEventListener('visibilitychange', onVisibility);
-        let claimNext = false;
-        observer = new ResizeObserver(() => {
-          const hidden = mount.clientWidth === 0 || mount.clientHeight === 0;
-          const shown = wasHidden && !hidden;
-          wasHidden = hidden;
-          onVisibility?.();
-          claimNext ||= shown;
-          window.clearTimeout(fitTimer);
-          // Shown again at another size: hidden until the new size is in, like on open.
-          fitTimer = window.setTimeout(
-            () => {
-              const claim = claimNext;
-              claimNext = false;
-              if (claim && attached) settle(true);
-              else resize(claim);
-            },
-            shown ? 0 : FIT_DEBOUNCE_MS,
-          );
-        });
-        observer.observe(mount);
-        // Test hooks (ghostty paints to a canvas): buffer text, where some text is on screen, selection.
-        Object.defineProperty(host, 'zgBufferText', {
-          configurable: true,
-          value: () => bufferText(term),
-        });
-        Object.defineProperty(host, 'zgCellCenter', {
-          configurable: true,
-          value: (needle: string) => cellCenter(term, mount, needle),
-        });
-        Object.defineProperty(host, 'zgHasSelection', {
-          configurable: true,
-          value: () => term?.hasSelection() ?? false,
-        });
-        Object.defineProperty(host, 'zgGrid', {
-          configurable: true,
-          value: () => (term ? { cols: term.cols, rows: term.rows } : null),
-        });
-        void attach();
-        if (autoFocusRef.current) term.focus();
-      },
-      (err: unknown) => {
-        if (!disposed) setFailed(labels.terminalCouldNotLoad(err instanceof Error ? err.message : String(err)));
-      },
-    );
-
-    return () => {
-      disposed = true;
-      claimRef.current = () => undefined;
-      redraw.current = null;
-      gridChanged.current = null;
-      window.clearTimeout(revealTimer);
-      window.clearTimeout(fitTimer);
-      window.clearTimeout(ackTimer);
-      observer?.disconnect();
-      if (onVisibility) document.removeEventListener('visibilitychange', onVisibility);
-      if (onFocusChange) {
-        mountEl?.removeEventListener('focusin', onFocusChange);
-        mountEl?.removeEventListener('focusout', onFocusChange);
-      }
-      unregister?.();
-      void api.detach(terminalId, clientId).catch(() => undefined);
-      termRef.current = null;
-      term?.dispose();
-    };
-    // Fonts are applied live above; everything else re-creates the view.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [terminalId, themeKey]);
-
-  const onKeyDownCapture = (e: ReactKeyboardEvent<HTMLDivElement>) => {
-    const term = termRef.current;
-    // The context menu is portaled but its events bubble through React here.
-    if (!term || !hostRef.current?.contains(e.target as Node)) return;
-    const native = e.nativeEvent;
-    // macOS editing keys (⌘⌫, ⌥←, …) as Terminal.app sends them; stopped here, before ghostty and app bindings.
-    const edit = macTerminalKey(native);
-    if (edit) {
-      e.preventDefault();
-      e.stopPropagation();
-      term.input(edit, true);
-      return;
-    }
-    const skip = () => Object.defineProperty(native, 'isComposing', { value: true });
-    if (native.metaKey && !native.ctrlKey && !native.altKey) {
-      const key = native.key.toLowerCase();
-      // Cmd+C copies a selection; Cmd+V is left to the native paste event, which the library brackets.
-      if (key === 'c' && term.copySelection()) e.preventDefault();
-      skip();
-      return;
-    }
-    if ((native.ctrlKey || native.altKey) && isAppChord(native, keybindings)) skip();
-  };
-
-  // Keys the terminal took stop here, so window-level bindings (shift+tab, …) never see them.
-  const onKeyDown = (e: ReactKeyboardEvent<HTMLDivElement>) => {
-    if (hostRef.current?.contains(e.target as Node) && !e.nativeEvent.isComposing) e.stopPropagation();
-  };
-
-  const onContextMenu = (e: React.MouseEvent) => {
-    const term = termRef.current;
-    if (!term || !hostRef.current?.contains(e.target as Node)) return;
-    e.preventDefault();
-    // The program tracks the mouse: its right-click was reported to it. Shift+right-click is ours.
-    if (term.hasMouseTracking() && !e.shiftKey) return;
-    setMenu({ x: e.clientX, y: e.clientY, selection: term.hasSelection() ? term.getSelection() : '' });
-  };
-
-  // Read when the menu renders: no chat for this scope (a panels window, a project page), nowhere to add to.
-  const chat = actions.addToChat !== undefined && menu !== null && (actions.canAddToChat?.(scope) ?? true);
-  const addToChat = () => {
-    if (!chat) return;
-    const term = termRef.current;
-    if (!term || !menu?.selection) return;
-    const range = selectionLines(term);
-    actions.addToChat?.(scope, {
-      label: labelRef.current,
-      startLine: range?.start ?? 1,
-      endLine: range?.end ?? 1,
-      text: menu.selection,
-    });
-  };
-
-  const items: RowActionItem[] = [
-    ...(actions.addToChat
-      ? [
-          {
-            id: 'chat',
-            label: chat ? labels.terminalAddToChat : labels.terminalAddToChatNowhere,
-            shortcut: 'a',
-            disabled: !menu?.selection || !chat,
-            onSelect: addToChat,
-          },
-        ]
-      : []),
-    {
-      id: 'copy',
-      label: labels.terminalCopy,
-      shortcut: 'c',
-      disabled: !menu?.selection,
-      onSelect: () => void navigator.clipboard.writeText(menu?.selection ?? ''),
-    },
-    {
-      id: 'paste',
-      label: labels.terminalPaste,
-      shortcut: 'v',
-      onSelect: () => {
-        const term = termRef.current;
-        if (term) void paste(term).then(() => term.focus());
-      },
-    },
-    { id: 'clear', label: labels.terminalClear, shortcut: 'k', onSelect: () => termRef.current?.clear() },
-  ];
-
-  return (
-    // The canvas's own input handles the keys; this root only filters them on the way.
-    // eslint-disable-next-line jsx-a11y/no-static-element-interactions
-    <div
-      ref={hostRef}
-      className={`relative flex-1 min-h-0 min-w-0 flex overflow-hidden${className ? ` ${className}` : ''}`}
-      data-testid="terminal-surface"
-      data-terminal-id={terminalId}
-      data-zg-keyscope="editor"
-      onKeyDownCapture={onKeyDownCapture}
-      onKeyDown={onKeyDown}
-      onFocusCapture={() => claimRef.current()}
-      onContextMenu={onContextMenu}
-    >
-      {/* ghostty-web makes the mount contenteditable: hide the browser's caret, the canvas draws the real one. */}
-      <div data-terminal-mount className="absolute inset-0 pl-2 pt-1" style={{ caretColor: 'transparent' }} />
-      {failed && (
-        <div className="absolute inset-x-0 top-0 m-2 px-2.5 py-1.5 rounded-md bg-zg-danger/10 text-zg-label text-[var(--zg-danger)]">
-          {failed}
-        </div>
-      )}
-      <RowActionsMenu
-        open={menu !== null}
-        position={menu ? { x: menu.x, y: menu.y } : null}
-        onClose={() => setMenu(null)}
-        items={items}
-      />
-    </div>
-  );
-}
-
-/** The menu's Paste (no native paste event there): bracketed when the program enabled it. */
-async function paste(term: Terminal): Promise<void> {
-  const text = await navigator.clipboard.readText().catch(() => '');
-  if (text) term.paste(text);
-}
-
-/** App bindings that are app intents even inside a terminal (same rule as the editor). */
-function isAppChord(event: KeyboardEvent, host: KeybindingsHost | null): boolean {
-  const merged = getMergedKeybindings(host);
-  for (const action of Object.keys(merged) as KeyAction[]) {
-    for (const spec of parseBindingSpecs(merged[action])) {
-      if (matchesBinding(event, spec) && bindingAllowedIn('editor', spec, action)) return true;
-    }
-  }
-  return false;
-}
-
-/** Buffer lines of the selection (1-based), from the viewport rows ghostty reports. */
-function selectionLines(term: Terminal): { start: number; end: number } | null {
-  const range: IBufferRange | undefined = term.getSelectionPosition();
-  if (!range) return null;
-  const top = term.getScrollbackLength() - Math.floor(term.getViewportY());
-  return { start: top + range.start.y + 1, end: top + range.end.y + 1 };
-}
-
-/** Plain text of the whole buffer (tests read it through the host's `zgBufferText`). */
-function bufferText(term: Terminal | null): string {
-  if (!term) return '';
-  const buf = term.buffer.active;
-  const out: string[] = [];
-  for (let y = 0; y < buf.length; y++) out.push(buf.getLine(y)?.translateToString(true) ?? '');
-  return out.join('\n').replace(/\n+$/, '');
-}
-
-/**
- * Clicks on links the library found (OSC 8 hyperlinks, URLs with a scheme).
- * A plain click opens web pages in the Browser tab, Cmd/Ctrl in the system
- * browser; file hyperlinks open in Files (only when the terminal's paths are
- * this machine's); mailto only on Cmd/Ctrl-click.
- */
-function libraryLinkHandler(ctx: { current: LinkContext | null }): ILinkHandler {
-  return {
-    activate: (event, uri) => {
-      const c = ctx.current;
-      const target = linkTarget(uri);
-      if (!c || !target) return;
-      const modified = event.metaKey || event.ctrlKey;
-      // A server's loopback address: nothing on this computer to open.
-      if (target.kind === 'web' && c.unreachable(target.url)) return;
-      if (target.kind === 'web') c.openUrl(target.url, modified);
-      else if (target.kind === 'file') {
-        if (c.cwd)
-          c.openFile(
-            target.path,
-            event,
-            target.line !== undefined ? { line: target.line, column: target.column } : undefined,
-          );
-      } else if (modified) window.open(target.url, '_blank', 'noopener,noreferrer');
-    },
-    hover: (_event, uri) => {
-      const target = linkTarget(uri);
-      ctx.current?.tip(target?.kind === 'web' ? ctx.current.unreachable(target.url) : null);
-    },
-    leave: () => ctx.current?.tip(null),
-  };
-}
-
-/** Viewport point of the last on-screen occurrence of `needle` (ASCII), for tests. */
-function cellCenter(term: Terminal | null, mount: HTMLElement, needle: string): { x: number; y: number } | null {
-  const canvas = mount.querySelector('canvas');
-  if (!term || !canvas) return null;
-  const rect = canvas.getBoundingClientRect();
-  const width = rect.width / term.cols;
-  const height = rect.height / term.rows;
-  const top = term.getScrollbackLength() - Math.floor(term.getViewportY());
-  for (let row = term.rows - 1; row >= 0; row--) {
-    const col =
-      term.buffer.active
-        .getLine(top + row)
-        ?.translateToString(true)
-        .indexOf(needle) ?? -1;
-    if (col >= 0) return { x: rect.left + (col + 0.5) * width, y: rect.top + (row + 0.5) * height };
-  }
-  return null;
-}
-
-/** Our links: file paths and scheme-less local servers (see `detectLinks`). */
-function linksOnRow(term: Terminal | null, y: number, ctx: { current: LinkContext | null }): ILink[] | undefined {
-  const line = term?.buffer.active.getLine(y);
-  if (!line) return undefined;
-  let text = '';
-  const cols: number[] = [];
-  for (let x = 0; x < line.length; x++) {
-    const cell = line.getCell(x);
-    if (!cell) break;
-    if (cell.getWidth() === 0) continue;
-    const chars = cell.getChars() || ' ';
-    for (let i = 0; i < chars.length; i++) cols.push(x);
-    text += chars;
-  }
-  const found = detectLinks(text).filter((l) => l.kind === 'url' || ctx.current?.cwd);
-  if (found.length === 0) return undefined;
-  return found.map((l) => ({
-    text: l.text,
-    range: { start: { x: cols[l.start] ?? 0, y }, end: { x: cols[l.end - 1] ?? 0, y } },
-    hover: (isHovered: boolean) =>
-      ctx.current?.tip(isHovered && l.kind === 'url' ? ctx.current.unreachable(l.url) : null),
-    activate: (event: MouseEvent) => {
-      const c = ctx.current;
-      if (!c) return;
-      // A server's loopback address: nothing on this computer to open.
-      if (l.kind === 'url' && c.unreachable(l.url)) return;
-      if (l.kind === 'url') c.openUrl(l.url, event.metaKey || event.ctrlKey);
-      else c.openFile(l.path, event, l.line !== undefined ? { line: l.line, column: l.column } : undefined);
-    },
-  }));
-}