Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

120 KB
Raw Blame
import { AGENT_REGISTRY, type HostSnapshot, TERMINAL_CLI_IDS } from '@inkeep/open-knowledge-core';
import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
import { afterEach, beforeEach, describe, expect, onTestFinished, test, vi } from 'vitest';
import { TooltipProvider } from '@/components/ui/tooltip';
import type { ApplyAgentConnectionsResult } from '@/lib/agent-connections';
import type {
  ClaudeReadiness,
  OkDesktopBridge,
  OkPtyAdoptResult,
  OkPtyCreateResult,
  OkPtyData,
  OkPtyExit,
  OkPtyNotice,
} from '@/lib/desktop-bridge-types';
import {
  __resetPaneVisibilityStoreForTests,
  type PaneVisibilityRequest,
  paneVisibilityStore,
} from '@/lib/pane-visibility-store';
import { terminalAgentSnapshot } from './terminal-agent-connections.test-helper';
import {
  applyModelledScroll,
  createScrollModelState,
  instrumentSmoothScrollOption,
} from './terminal-scroll-model.test-helper';

class MockFitAddon {
  fit = vi.fn(() => {});
  constructor() {
    lastFit = this;
  }
}
class MockWebglAddon {}
let lastWebLinksHandler: ((event: MouseEvent, uri: string) => void) | null = null;
class MockWebLinksAddon {
  constructor(handler?: (event: MouseEvent, uri: string) => void) {
    lastWebLinksHandler = handler ?? null;
  }
}
class MockUnicode11Addon {}

class MockTerminal {
  cols = 80;
  rows = 24;
  unicode = { activeVersion: '6' };
  modes = { mouseTrackingMode: 'none' as string };
  mouseEncoding = 'SGR' as string;
  renderFlush = vi.fn(() => {});
  refresh = vi.fn((_start: number, _end: number) => {});
  selection = '';
  hasSelection = vi.fn(() => this.selection.length > 0);
  getSelection = vi.fn(() => this.selection);
  clearSelection = vi.fn(() => {
    this.selection = '';
  });
  get _core() {
    return {
      coreMouseService: { activeEncoding: this.mouseEncoding },
      _renderService: {
        dimensions: { css: { cell: { width: 10, height: 17 } } },
        _renderDebouncer: { _innerRefresh: this.renderFlush },
      },
    };
  }
  element: HTMLElement | undefined = undefined;
  lineText = '';
  lineRows: string[] | null = null;
  scrollState = createScrollModelState(0);
  baseY = 0;
  get viewportY() {
    return this.scrollState.viewportY;
  }
  set viewportY(line: number) {
    this.scrollState.viewportY = line;
  }
  get scrollbarLine() {
    return this.scrollState.scrollbarLine;
  }
  set scrollbarLine(line: number) {
    this.scrollState.scrollbarLine = line;
  }
  get pendingScrollTarget() {
    return this.scrollState.pendingTarget;
  }
  scrollToBottom = vi.fn(() => {
    applyModelledScroll(this.scrollState, this.baseY, this.options.smoothScrollDuration as number);
  });
  scrollToLine = vi.fn((line: number) => {
    applyModelledScroll(this.scrollState, line, this.options.smoothScrollDuration as number);
  });
  get buffer() {
    return {
      active: {
        viewportY: this.viewportY,
        baseY: this.baseY,
        getLine: (index: number) => {
          if (this.lineRows) {
            const t = this.lineRows[index];
            if (t === undefined) return undefined;
            return { translateToString: (_trim?: boolean) => t, isWrapped: index > 0 };
          }
          return { translateToString: (_trim?: boolean) => this.lineText, isWrapped: false };
        },
      },
    };
  }
  linkProvider: {
    provideLinks(line: number, cb: (links: unknown[] | undefined) => void): void;
  } | null = null;
  linkProviderDispose = vi.fn(() => {});
  registerLinkProvider = vi.fn(
    (provider: {
      provideLinks(line: number, cb: (links: unknown[] | undefined) => void): void;
    }) => {
      this.linkProvider = provider;
      return { dispose: this.linkProviderDispose };
    },
  );
  onDataCb: ((d: string) => void) | null = null;
  keyHandler: ((e: KeyboardEvent) => boolean) | null = null;
  wheelHandler: ((e: WheelEvent) => boolean) | null = null;
  options: Record<string, unknown>;
  open = vi.fn((container: HTMLElement) => {
    const screen = document.createElement('div');
    screen.className = 'xterm-screen';
    screen.appendChild(document.createElement('canvas'));
    container.appendChild(screen);
  });
  focus = vi.fn(() => {});
  dispose = vi.fn(() => {});
  paste = vi.fn((_data: string) => {});
  pendingWrites: Array<{ data: string; callback?: () => void }> = [];
  write = vi.fn((data: string, callback?: () => void) => {
    if (deferTerminalWrites) {
      this.pendingWrites.push({ data, callback });
      return;
    }
    callback?.();
  });
  flushPendingWrites(): void {
    for (const pending of this.pendingWrites.splice(0)) {
      if (terminalGeneratedInput !== null) this.onDataCb?.(terminalGeneratedInput);
      pending.callback?.();
    }
  }
  loadAddon = vi.fn((addon: unknown) => {
    if (webglThrows && addon instanceof MockWebglAddon) throw new Error('no webgl2 context');
  });
  onData = vi.fn((cb: (d: string) => void) => {
    this.onDataCb = cb;
    return { dispose() {} };
  });
  onTitleChangeCb: ((title: string) => void) | null = null;
  onTitleChange = vi.fn((cb: (title: string) => void) => {
    this.onTitleChangeCb = cb;
    return { dispose() {} };
  });
  attachCustomKeyEventHandler = vi.fn((h: (e: KeyboardEvent) => boolean) => {
    this.keyHandler = h;
  });
  attachCustomWheelEventHandler = vi.fn((h: (e: WheelEvent) => boolean) => {
    this.wheelHandler = h;
  });
  smoothScrollWrites: () => number;
  constructor(options: Record<string, unknown>) {
    this.smoothScrollWrites = instrumentSmoothScrollOption(
      options as { smoothScrollDuration?: number },
    );
    this.options = options;
    lastTerm = this;
  }
}

let lastTerm: MockTerminal | null = null;
let lastFit: MockFitAddon | null = null;
let webglThrows = false;
let deferTerminalWrites = false;
let terminalGeneratedInput: string | null = null;
let mockResolvedTheme: string | undefined = 'dark';

type MockResizeEntry = { contentRect: { width: number; height: number } };
type MockResizeCallback = (entries?: readonly MockResizeEntry[]) => void;
const sizedEntries = (width: number, height: number): readonly MockResizeEntry[] => [
  { contentRect: { width, height } },
];

const stubContainerLayout = (
  rect: { width: number; height: number },
  style: { width: string; height: string },
) => {
  const measure = Element.prototype.getBoundingClientRect;
  const computed = window.getComputedStyle;
  Element.prototype.getBoundingClientRect = function (this: Element) {
    return (this.matches('[data-terminal-status]') ? rect : measure.call(this)) as DOMRect;
  };
  window.getComputedStyle = ((element: Element, pseudo?: string | null) => {
    const base = computed.call(window, element, pseudo ?? undefined);
    if (!element.matches('[data-terminal-status]')) return base;
    return new Proxy(base, {
      get(target, prop, receiver) {
        if (prop === 'width') return style.width;
        if (prop === 'height') return style.height;
        return Reflect.get(target, prop, receiver);
      },
    });
  }) as typeof window.getComputedStyle;
  onTestFinished(() => {
    Element.prototype.getBoundingClientRect = measure;
    window.getComputedStyle = computed;
  });
};

let roCallback: MockResizeCallback | null = null;
let allROs: MockResizeObserver[] = [];
class MockResizeObserver {
  cb: MockResizeCallback;
  observed: Array<{ el: Element; opts?: ResizeObserverOptions }> = [];
  observe = vi.fn((el: Element, opts?: ResizeObserverOptions) => {
    this.observed.push({ el, opts });
  });
  unobserve = vi.fn(() => {});
  disconnect = vi.fn(() => {});
  constructor(cb: MockResizeCallback) {
    this.cb = cb;
    roCallback = cb;
    allROs.push(this);
  }
}

vi.doMock('@xterm/xterm', () => ({ Terminal: MockTerminal }));
vi.doMock('@xterm/addon-fit', () => ({ FitAddon: MockFitAddon }));
vi.doMock('@xterm/addon-webgl', () => ({ WebglAddon: MockWebglAddon }));
vi.doMock('@xterm/addon-web-links', () => ({ WebLinksAddon: MockWebLinksAddon }));
vi.doMock('@xterm/addon-unicode11', () => ({ Unicode11Addon: MockUnicode11Addon }));
vi.doMock('@xterm/xterm/css/xterm.css', () => ({}));
vi.doMock('next-themes', () => ({
  useTheme: () => ({ resolvedTheme: mockResolvedTheme }),
}));

const WIRED: ClaudeReadiness = { claude: 'present' };

function makeBridge(
  createResult: OkPtyCreateResult,
  preflight: ClaudeReadiness = WIRED,
  adopt: (id: string, opts?: { start?: boolean }) => Promise<OkPtyAdoptResult> = async () => ({
    ok: true,
    replay: '',
  }),
  platform: OkDesktopBridge['platform'] = 'darwin',
) {
  const dataSubs: Array<(m: OkPtyData) => void> = [];
  const exitSubs: Array<(m: OkPtyExit) => void> = [];
  const noticeSubs: Array<(m: OkPtyNotice) => void> = [];
  const unsubData = vi.fn(() => {});
  const unsubExit = vi.fn(() => {});
  const unsubNotice = vi.fn(() => {});
  const openExternal = vi.fn(async (_url: string) => {});
  const openAsset = vi.fn(
    async (_relPath: string): Promise<{ ok: true } | { ok: false; reason: string }> => ({
      ok: true,
    }),
  );
  const revealAsset = vi.fn(async (_relPath: string) => ({ ok: true }) as { ok: true });
  const revealExternal = vi.fn(
    async (_absPath: string) =>
      ({ ok: true, outcome: 'revealed' }) as { ok: true; outcome: 'revealed' },
  );
  const checkTargetExists = vi.fn(
    async (_req: { projectPath: string; kind: 'doc' | 'folder'; path: string }) =>
      'exists' as const,
  );
  const adoptMock = vi.fn(adopt);
  const terminal = {
    create: vi.fn(async () => createResult),
    adopt: adoptMock,
    start: vi.fn((id: string) => adoptMock(id, { start: true })),
    input: vi.fn((_id: string, _d: string) => {}),
    resize: vi.fn((_id: string, _c: number, _r: number) => {}),
    kill: vi.fn(async (_id: string) => {}),
    drain: vi.fn((_id: string, _bytes: number) => {}),
    onData: vi.fn((cb: (m: OkPtyData) => void) => {
      dataSubs.push(cb);
      return unsubData;
    }),
    onExit: vi.fn((cb: (m: OkPtyExit) => void) => {
      exitSubs.push(cb);
      return unsubExit;
    }),
    onNotice: vi.fn((cb: (m: OkPtyNotice) => void) => {
      noticeSubs.push(cb);
      return unsubNotice;
    }),
    claudePreflight: vi.fn(async () => preflight),
    cliPreflight: vi.fn(async () => ({ onPath: 'present' as const })),
  };
  return {
    bridge: {
      terminal,
      shell: { openExternal, openAsset, revealAsset, revealExternal },
      project: { checkTargetExists },
      config: { e2eSmoke: false, projectPath: '/Users/me/project' },
      platform,
      getPathForFile: (file: File) => `/dropped/${file.name}`,
    } as unknown as OkDesktopBridge,
    terminal,
    openExternal,
    openAsset,
    revealAsset,
    revealExternal,
    checkTargetExists,
    unsubData,
    unsubExit,
    unsubNotice,
    pushData: (m: OkPtyData) => {
      for (const f of dataSubs) f(m);
    },
    pushExit: (m: OkPtyExit) => {
      for (const f of exitSubs) f(m);
    },
    pushNotice: (m: OkPtyNotice) => {
      for (const f of noticeSubs) f(m);
    },
  };
}

let connectionSnapshot: HostSnapshot | null = null;
const applyConnections = vi.fn(
  async (): Promise<ApplyAgentConnectionsResult> => ({
    ok: true,
    report: { actions: [], conflicts: [], withheld: [] },
    snapshot: connectionSnapshot,
  }),
);
vi.doMock('@/lib/agent-connections', async (importOriginal) => ({
  ...(await importOriginal<typeof import('@/lib/agent-connections')>()),
  applyAgentConnectionIntents: applyConnections,
}));

const { TerminalPanel } = await import('./TerminalPanel');
const { XTERM_DARK_THEME, XTERM_LIGHT_THEME } = await import('./terminal-theme');

describe('TerminalPanel', () => {
  beforeEach(() => {
    connectionSnapshot = terminalAgentSnapshot(TERMINAL_CLI_IDS);
    applyConnections.mockClear();
    lastTerm = null;
    lastFit = null;
    roCallback = null;
    allROs = [];
    webglThrows = false;
    deferTerminalWrites = false;
    terminalGeneratedInput = null;
    mockResolvedTheme = 'dark';
    (globalThis as { ResizeObserver: unknown }).ResizeObserver = MockResizeObserver;
    Object.defineProperty(globalThis.navigator, 'clipboard', {
      configurable: true,
      value: {
        readText: vi.fn(async () => 'clipboard paste'),
        writeText: vi.fn(async () => {}),
      },
    });
  });
  afterEach(() => {
    cleanup();
    __resetPaneVisibilityStoreForTests();
  });

  test('mounts an accessible region, configures xterm for a11y, and creates a PTY sized to the fitted terminal', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);

    const region = screen.getByRole('region', { name: 'Terminal' });
    expect(region).toBeTruthy();

    expect(lastTerm?.options.screenReaderMode).toBe(true);
    expect(lastTerm?.options.minimumContrastRatio).toBe(4.5);
    expect(lastTerm?.unicode.activeVersion).toBe('11');
    expect(lastTerm?.options.scrollback).toBe(10000);
    expect(lastTerm?.options.smoothScrollDuration).toBe(125);

    await waitFor(() => expect(terminal.create).toHaveBeenCalledTimes(1));
    expect(terminal.create).toHaveBeenCalledWith({ cols: 80, rows: 24 });
  });

  test('screen-reader mode follows the assistive-tech signal: off when inactive, live-toggled on attach', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
    const a11ySubs: Array<(active: boolean) => void> = [];
    const a11yUnsub = vi.fn(() => {});
    const withA11y = {
      ...(bridge as unknown as Record<string, unknown>),
      accessibility: {
        isScreenReaderActive: () => false,
        onScreenReaderChanged: (cb: (active: boolean) => void) => {
          a11ySubs.push(cb);
          return a11yUnsub;
        },
      },
    } as unknown as OkDesktopBridge;
    const { unmount } = render(<TerminalPanel bridge={withA11y} />);
    await waitFor(() => expect(terminal.create).toHaveBeenCalledTimes(1));

    expect(lastTerm?.options.screenReaderMode).toBe(false);

    act(() => {
      for (const f of a11ySubs) f(true);
    });
    expect(lastTerm?.options.screenReaderMode).toBe(true);
    act(() => {
      for (const f of a11ySubs) f(false);
    });
    expect(lastTerm?.options.screenReaderMode).toBe(false);

    act(() => unmount());
    expect(a11yUnsub).toHaveBeenCalledTimes(1);
  });

  test('the smoke suite pins screen-reader mode on even with no assistive tech (assertions read the a11y tree)', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
    const smokeBridge = {
      ...(bridge as unknown as Record<string, unknown>),
      config: { e2eSmoke: true },
      accessibility: {
        isScreenReaderActive: () => false,
        onScreenReaderChanged: () => () => {},
      },
    } as unknown as OkDesktopBridge;
    render(<TerminalPanel bridge={smokeBridge} />);
    await waitFor(() => expect(terminal.create).toHaveBeenCalledTimes(1));
    expect(lastTerm?.options.screenReaderMode).toBe(true);
  });

  test('captures the one-shot prompt before the start handshake resolves without typing', async () => {
    const h = makeBridge({ ok: true, ptyId: 'pty-1' });
    h.terminal.adopt.mockImplementationOnce(async () => {
      h.pushData({ ptyId: 'pty-1', data: 'prompt$ ' });
      return { ok: true, replay: '' };
    });
    render(<TerminalPanel bridge={h.bridge} />);
    await waitFor(() => expect(h.terminal.start).toHaveBeenCalledWith('pty-1'));
    await waitFor(() => expect(screen.queryByTestId('terminal-starting-notice')).toBeNull());
    expect(lastTerm?.write).toHaveBeenCalledExactlyOnceWith('prompt$ ', expect.any(Function));
    expect(h.terminal.input).not.toHaveBeenCalled();
  });

  test('keeps an exit received before the start reply in the exited state', async () => {
    const h = makeBridge({ ok: true, ptyId: 'pty-1' });
    h.terminal.adopt.mockImplementationOnce(async () => {
      h.pushData({ ptyId: 'pty-1', data: 'goodbye\r\n' });
      h.pushExit({ ptyId: 'pty-1', exitCode: 7, signal: null });
      return { ok: true, replay: '' };
    });
    render(<TerminalPanel bridge={h.bridge} />);
    await waitFor(() =>
      expect(screen.getByRole('button', { name: 'Restart terminal' })).toBeTruthy(),
    );
    expect(document.querySelector('[data-terminal-status="exited"]')).toBeTruthy();
    expect(screen.queryByTestId('terminal-starting-notice')).toBeNull();
    expect(lastTerm?.write).toHaveBeenCalledExactlyOnceWith('goodbye\r\n', expect.any(Function));
    act(() => lastTerm?.onDataCb?.('ignored input'));
    expect(h.terminal.input).not.toHaveBeenCalled();
  });

  test('shows a restartable error if the reserved session disappears before attachment', async () => {
    const h = makeBridge({ ok: true, ptyId: 'pty-1' });
    h.terminal.adopt.mockResolvedValueOnce({ ok: false, reason: 'unknown-session' });
    render(<TerminalPanel bridge={h.bridge} />);
    await waitFor(() => expect(screen.getByRole('button', { name: 'Try again' })).toBeTruthy());
    expect(screen.getByText(/couldn't start/i)).toBeTruthy();
    expect(screen.getByText(/no longer available/i)).toBeTruthy();
    expect(screen.queryByText('unknown-session')).toBeNull();
    expect(screen.queryByTestId('terminal-starting-notice')).toBeNull();
    expect(h.terminal.input).not.toHaveBeenCalled();
  });

  test('rehydrating a survivor adopts it for replay and never asks for a fresh start', async () => {
    const h = makeBridge({ ok: true, ptyId: 'unused' });
    h.terminal.adopt.mockResolvedValueOnce({ ok: true, replay: 'restored$ ' });
    render(<TerminalPanel bridge={h.bridge} adoptPtyId="surv-1" />);
    await waitFor(() => expect(h.terminal.adopt).toHaveBeenCalledWith('surv-1'));
    await waitFor(() => expect(screen.queryByTestId('terminal-starting-notice')).toBeNull());
    expect(h.terminal.adopt).toHaveBeenCalledExactlyOnceWith('surv-1');
    expect(lastTerm?.write).toHaveBeenCalledExactlyOnceWith('restored$ ', expect.any(Function));
    expect(h.terminal.create).not.toHaveBeenCalled();
  });

  test('keeps the panel non-interactive until the shell start is acknowledged', async () => {
    const h = makeBridge({ ok: true, ptyId: 'pty-1' });
    let releaseStart = (): void => {};
    h.terminal.adopt.mockImplementationOnce(
      async () =>
        await new Promise<OkPtyAdoptResult>((resolve) => {
          releaseStart = () => resolve({ ok: true, replay: '' });
        }),
    );
    render(<TerminalPanel bridge={h.bridge} />);
    await waitFor(() => expect(h.terminal.start).toHaveBeenCalledWith('pty-1'));
    act(() => lastTerm?.onDataCb?.('typed too early'));
    expect(h.terminal.input).not.toHaveBeenCalled();
    expect(document.querySelector('[data-terminal-status="starting"]')).toBeTruthy();
    expect(document.querySelector('[data-terminal-status="starting"]')?.ariaBusy).toBe('true');
    await act(async () => {
      releaseStart();
      await Promise.resolve();
    });
    await waitFor(() =>
      expect(document.querySelector('[data-terminal-status="running"]')).toBeTruthy(),
    );
    expect(screen.getByTestId('terminal-starting-notice')).toBeTruthy();
    expect(document.querySelector('[data-terminal-status="running"]')?.ariaBusy).toBe('true');
    act(() => lastTerm?.onDataCb?.('now live'));
    expect(h.terminal.input).toHaveBeenCalledWith('pty-1', 'now live');
    act(() => h.pushData({ ptyId: 'pty-1', data: '$ ' }));
    expect(screen.queryByTestId('terminal-starting-notice')).toBeNull();
    expect(document.querySelector('[data-terminal-status="running"]')?.ariaBusy).toBe('false');
  });

  test('surfaces a withdrawn terminal consent at start time as a refusal, not a crash', async () => {
    const h = makeBridge({ ok: true, ptyId: 'pty-1' });
    h.terminal.adopt.mockResolvedValueOnce({ ok: false, reason: 'not-consented' });
    render(<TerminalPanel bridge={h.bridge} />);
    await waitFor(() =>
      expect(screen.getByText(/Terminal access isn't enabled for this project\./)).toBeTruthy(),
    );
    expect(screen.queryByRole('button', { name: 'Restart terminal' })).toBeNull();
  });

  test('reload rehydration: adopts a surviving session instead of spawning a fresh one', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-fresh' });
    render(<TerminalPanel bridge={bridge} adoptPtyId="pty-survivor" />);

    await waitFor(() => expect(terminal.adopt).toHaveBeenCalledWith('pty-survivor'));
    expect(terminal.create).not.toHaveBeenCalled();
    expect(terminal.resize).not.toHaveBeenCalled();
    act(() => lastTerm?.onDataCb?.('user input'));
    expect(terminal.input).toHaveBeenCalledWith('pty-survivor', 'user input');
  });

  test('reload rehydration: writes the adopted session replay into xterm so the screen repaints', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-fresh' }, WIRED, async () => ({
      ok: true,
      replay: 'REPLAYED-SCREEN-BYTES',
    }));
    render(<TerminalPanel bridge={bridge} adoptPtyId="pty-survivor" />);

    await waitFor(() => expect(terminal.adopt).toHaveBeenCalledWith('pty-survivor'));
    expect(lastTerm?.write).toHaveBeenCalledWith('REPLAYED-SCREEN-BYTES', expect.any(Function));
    expect(terminal.create).not.toHaveBeenCalled();
    await waitFor(() => expect(screen.queryByTestId('terminal-starting-notice')).toBeNull());
  });

  test('reload rehydration: does not send replay-generated terminal replies into the live shell', async () => {
    deferTerminalWrites = true;
    terminalGeneratedInput = '\x1b[?1;2c';
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-fresh' }, WIRED, async () => ({
      ok: true,
      replay: '\x1b[c',
    }));
    render(<TerminalPanel bridge={bridge} adoptPtyId="pty-survivor" />);

    await waitFor(() => expect(terminal.onData).toHaveBeenCalledTimes(1));
    expect(document.querySelector('[data-terminal-status="starting"]')).toBeTruthy();
    expect(lastTerm?.focus).not.toHaveBeenCalled();
    act(() => lastTerm?.onDataCb?.('early user input'));
    expect(terminal.input).not.toHaveBeenCalledWith('pty-survivor', 'early user input');
    expect(terminal.resize).not.toHaveBeenCalled();
    act(() => lastTerm?.flushPendingWrites());

    expect(terminal.input).not.toHaveBeenCalledWith('pty-survivor', '\x1b[?1;2c');
    expect(document.querySelector('[data-terminal-status="running"]')).toBeTruthy();
    expect(lastTerm?.focus).toHaveBeenCalledTimes(1);

    act(() => lastTerm?.onDataCb?.('user input'));
    expect(terminal.input).toHaveBeenCalledWith('pty-survivor', 'user input');
  });

  test('reload rehydration: gates direct input surfaces until replay completes', async () => {
    deferTerminalWrites = true;
    const { bridge, terminal, pushNotice } = makeBridge(
      { ok: true, ptyId: 'pty-fresh' },
      WIRED,
      async () => ({ ok: true, replay: 'REPLAYED-SCREEN-BYTES' }),
      'win32',
    );
    render(<TerminalPanel bridge={bridge} adoptPtyId="pty-survivor" />);

    await waitFor(() => expect(lastTerm?.onDataCb).toBeTruthy());
    const term = lastTerm;
    if (term?.keyHandler == null || term.wheelHandler == null) {
      throw new Error('terminal input handlers not attached');
    }
    act(() =>
      pushNotice({
        ptyId: 'pty-survivor',
        notice: 'shell-resolved',
        shellFamily: 'powershell',
      }),
    );

    const shiftEnter = {
      type: 'keydown',
      key: 'Enter',
      shiftKey: true,
      preventDefault: vi.fn(() => {}),
    } as unknown as KeyboardEvent;
    expect(term.keyHandler(shiftEnter)).toBe(false);

    term.modes.mouseTrackingMode = 'any';
    term.mouseEncoding = 'SGR';
    expect(term.wheelHandler({ deltaY: 120, deltaMode: 0 } as unknown as WheelEvent)).toBe(true);

    const container = document.querySelector('[data-terminal-status]');
    if (container === null) throw new Error('terminal container not found');
    const file = new File(['x'], 'shot.png', { type: 'image/png' });
    fireEvent.drop(container, { dataTransfer: { types: ['Files'], files: [file] } });

    const ctrlV = {
      type: 'keydown',
      key: 'v',
      ctrlKey: true,
      shiftKey: false,
      altKey: false,
      metaKey: false,
      preventDefault: vi.fn(() => {}),
    } as unknown as KeyboardEvent;
    expect(term.keyHandler(ctrlV)).toBe(false);
    await act(async () => {});

    expect(terminal.input).not.toHaveBeenCalled();
    expect(navigator.clipboard.readText).not.toHaveBeenCalled();
    expect(term.paste).not.toHaveBeenCalled();

    act(() => term.flushPendingWrites());
    terminal.input.mockClear();

    expect(term.keyHandler(shiftEnter)).toBe(false);
    expect(terminal.input).toHaveBeenLastCalledWith('pty-survivor', '\n');

    terminal.input.mockClear();
    expect(term.wheelHandler({ deltaY: 120, deltaMode: 0 } as unknown as WheelEvent)).toBe(false);
    expect(terminal.input).toHaveBeenCalledTimes(1);

    terminal.input.mockClear();
    fireEvent.drop(container, { dataTransfer: { types: ['Files'], files: [file] } });
    expect(terminal.input).toHaveBeenCalledWith('pty-survivor', "'/dropped/shot.png' ");

    expect(term.keyHandler(ctrlV)).toBe(false);
    await act(async () => {});
    expect(navigator.clipboard.readText).toHaveBeenCalledTimes(1);
    expect(term.paste).toHaveBeenCalledWith('clipboard paste');
  });

  test('reload rehydration: a shell that exits during replay stays exited', async () => {
    deferTerminalWrites = true;
    const { bridge, terminal, pushExit } = makeBridge(
      { ok: true, ptyId: 'pty-fresh' },
      WIRED,
      async () => ({ ok: true, replay: 'REPLAYED-SCREEN-BYTES' }),
    );
    render(<TerminalPanel bridge={bridge} adoptPtyId="pty-survivor" />);

    await waitFor(() => expect(terminal.onExit).toHaveBeenCalledTimes(1));
    act(() => pushExit({ ptyId: 'pty-survivor', exitCode: 1, signal: null }));
    act(() => lastTerm?.flushPendingWrites());

    expect(document.querySelector('[data-terminal-status="exited"]')).toBeTruthy();
    expect(screen.getByRole('button', { name: 'Restart terminal' })).toBeTruthy();
    expect(lastTerm?.focus).not.toHaveBeenCalled();
  });

  test('reload rehydration: restores a standing unsupported-shell capability notice', async () => {
    const { bridge, terminal } = makeBridge(
      { ok: true, ptyId: 'pty-fresh' },
      WIRED,
      async () => ({
        ok: true,
        replay: '',
        shellNoticeReason: 'unsupported-family',
      }),
      'win32',
    );
    render(<TerminalPanel bridge={bridge} adoptPtyId="pty-survivor" />);

    await waitFor(() => expect(terminal.adopt).toHaveBeenCalledWith('pty-survivor'));
    expect(screen.getByTestId('terminal-shell-notice-banner').textContent).toMatch(
      /\.ok\/local\/config\.yml.*PowerShell.*cmd\.exe.*Git Bash.*plain terminal only.*agent and command launches do not run/i,
    );
  });

  test('reload rehydration: a refused adopt (session died in the gap) falls through to a fresh create', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-fresh' }, WIRED, async () => ({
      ok: false,
      reason: 'unknown-session',
    }));
    render(<TerminalPanel bridge={bridge} adoptPtyId="pty-gone" />);

    await waitFor(() => expect(terminal.create).toHaveBeenCalledTimes(1));
    expect(terminal.adopt).toHaveBeenCalledWith('pty-gone');
    expect(terminal.resize).not.toHaveBeenCalled();
  });

  test('reload rehydration: an adopt that throws is caught and falls through to a fresh create', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-fresh' }, WIRED, async () => {
      throw new Error('ipc boom');
    });
    render(<TerminalPanel bridge={bridge} adoptPtyId="pty-survivor" />);

    await waitFor(() => expect(terminal.create).toHaveBeenCalledTimes(1));
    expect(terminal.adopt).toHaveBeenCalledWith('pty-survivor');
    expect(terminal.resize).not.toHaveBeenCalled();
  });

  test('reload rehydration: an unmount mid-adopt leaves the surviving session alive (does not kill it)', async () => {
    let releaseAdopt: (() => void) | null = null;
    const { bridge, terminal } = makeBridge(
      { ok: true, ptyId: 'pty-fresh' },
      WIRED,
      () =>
        new Promise<{ ok: true }>((resolve) => {
          releaseAdopt = () => resolve({ ok: true });
        }),
    );
    const { unmount } = render(<TerminalPanel bridge={bridge} adoptPtyId="pty-survivor" />);

    await waitFor(() => expect(terminal.adopt).toHaveBeenCalledWith('pty-survivor'));
    unmount();
    releaseAdopt?.();
    await act(async () => {});

    expect(terminal.kill).not.toHaveBeenCalled();
  });

  test('forwards xterm OSC 0/2 title changes to onTitleChange', async () => {
    const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' });
    const onTitleChange = vi.fn((_title: string) => {});
    render(<TerminalPanel bridge={bridge} onTitleChange={onTitleChange} />);

    await waitFor(() => expect(lastTerm?.onTitleChangeCb).toBeTruthy());

    act(() => lastTerm?.onTitleChangeCb?.('claude — repo'));
    expect(onTitleChange).toHaveBeenCalledWith('claude — repo');

    act(() => lastTerm?.onTitleChangeCb?.('claude — done'));
    expect(onTitleChange).toHaveBeenLastCalledWith('claude — done');
  });

  test('disposes the title listener on unmount', async () => {
    const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' });
    const onTitleChange = vi.fn((_title: string) => {});
    const { unmount } = render(<TerminalPanel bridge={bridge} onTitleChange={onTitleChange} />);
    await waitFor(() => expect(lastTerm?.onTitleChangeCb).toBeTruthy());

    unmount();
    onTitleChange.mockClear();
    act(() => lastTerm?.onTitleChangeCb?.('late'));
    expect(onTitleChange).not.toHaveBeenCalled();
  });

  test('writes shell output to the terminal and drains the consumed code-unit count for backpressure', async () => {
    const { bridge, terminal, pushData } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(terminal.onData).toHaveBeenCalledTimes(1));

    const payload = 'hi🎉';
    expect(payload.length).toBe(4);
    act(() => pushData({ ptyId: 'pty-1', data: payload }));

    expect(lastTerm?.write).toHaveBeenCalledTimes(1);
    expect(lastTerm?.write.mock.calls[0]?.[0]).toBe(payload);
    expect(terminal.drain).toHaveBeenCalledWith('pty-1', payload.length);
  });

  test('says the terminal is starting until the first shell byte, then gets out of the way (PRD-8313)', async () => {
    const { bridge, terminal, pushData } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);

    await waitFor(() => expect(terminal.onData).toHaveBeenCalledTimes(1));
    expect(screen.getByTestId('terminal-starting-notice')).toBeTruthy();

    act(() => pushData({ ptyId: 'pty-1', data: '$ ' }));

    expect(screen.queryByTestId('terminal-starting-notice')).toBeNull();
  });

  test('the starting notice never covers or click-blocks the readiness banner (PRD-8313)', async () => {
    connectionSnapshot = terminalAgentSnapshot();
    const { bridge, pushData } = makeBridge({ ok: true, ptyId: 'pty-1' }, { claude: 'present' });
    render(<TerminalPanel bridge={bridge} launch={{ prompt: null, cli: 'claude', nonce: 1 }} />);

    const banner = await screen.findByTestId('terminal-readiness-banner');
    const notice = screen.getByTestId('terminal-starting-notice');

    const containingBlock = notice.parentElement;
    expect(containingBlock).not.toBeNull();
    expect(containingBlock?.contains(banner)).toBe(false);
    expect(containingBlock?.className.split(/\s+/)).toContain('relative');
    expect(notice.className).toContain('pointer-events-none');
    expect(screen.getByRole('button', { name: 'Connect tools' })).toBeTruthy();

    act(() => pushData({ ptyId: 'pty-1', data: '$ ' }));
    expect(screen.queryByTestId('terminal-starting-notice')).toBeNull();
  });

  test('the starting notice keeps its Reload clickable under the click-through overlay', async () => {
    vi.useFakeTimers();
    try {
      const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' });
      render(<TerminalPanel bridge={bridge} />);
      const notice = await vi.waitFor(() => screen.getByTestId('terminal-starting-notice'));
      expect(notice.className).toContain('pointer-events-none');
      await act(async () => {
        await vi.advanceTimersByTimeAsync(8_000);
      });
      const reload = screen.getByRole('button', { name: 'Reload' });
      expect(notice.contains(reload)).toBe(true);
      expect(reload.className).toContain('pointer-events-auto');
    } finally {
      vi.useRealTimers();
    }
  });

  test('forwards user keystrokes to the PTY via input', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.onDataCb).toBeTruthy());

    act(() => lastTerm?.onDataCb?.('ls\r'));
    expect(terminal.input).toHaveBeenCalledWith('pty-1', 'ls\r');
  });

  test('dropping files inserts their shell-escaped paths at the prompt (PRD-7238)', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.onDataCb).toBeTruthy());

    const container = document.querySelector('[data-terminal-status]');
    if (container === null) throw new Error('terminal container not found');

    const fileA = new File(['x'], 'shot.png', { type: 'image/png' });
    const fileB = new File(['y'], "a b's.png", { type: 'image/png' });
    const dataTransfer = { types: ['Files'], files: [fileA, fileB] };
    fireEvent.dragOver(container, { dataTransfer });
    fireEvent.drop(container, { dataTransfer });

    expect(terminal.input).toHaveBeenCalledWith(
      'pty-1',
      "'/dropped/shot.png' '/dropped/a b'\\''s.png' ",
    );
  });

  test('a PowerShell terminal doubles quotes in dropped Windows paths', async () => {
    const { bridge, terminal, pushNotice } = makeBridge(
      { ok: true, ptyId: 'pty-1' },
      WIRED,
      undefined,
      'win32',
    );
    (bridge as unknown as { getPathForFile: (file: File) => string }).getPathForFile = (file) =>
      `C:\\Users\\O'Brien\\${file.name}`;
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.onDataCb).toBeTruthy());
    act(() =>
      pushNotice({
        ptyId: 'pty-1',
        notice: 'shell-resolved',
        shellFamily: 'powershell',
      }),
    );

    const container = document.querySelector('[data-terminal-status]');
    if (container === null) throw new Error('terminal container not found');
    const file = new File(['x'], 'shot.png', { type: 'image/png' });
    const dataTransfer = { types: ['Files'], files: [file] };
    fireEvent.drop(container, { dataTransfer });

    expect(terminal.input).toHaveBeenCalledWith('pty-1', "'C:\\Users\\O''Brien\\shot.png' ");
  });

  test('a PowerShell terminal doubles every curly single quote in dropped Windows paths', async () => {
    const { bridge, terminal, pushNotice } = makeBridge(
      { ok: true, ptyId: 'pty-1' },
      WIRED,
      undefined,
      'win32',
    );
    (bridge as unknown as { getPathForFile: (file: File) => string }).getPathForFile = (file) =>
      `C:\\Users\\me\\${file.name}`;
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.onDataCb).toBeTruthy());
    act(() =>
      pushNotice({
        ptyId: 'pty-1',
        notice: 'shell-resolved',
        shellFamily: 'powershell',
      }),
    );

    const container = document.querySelector('[data-terminal-status]');
    if (container === null) throw new Error('terminal container not found');
    const files = [
      new File(['a'], '\u2018draft.md', { type: 'text/markdown' }),
      new File(['b'], 'Nick\u2019s notes.md', { type: 'text/markdown' }),
      new File(['c'], 'a\u201Ab.md', { type: 'text/markdown' }),
      new File(['d'], 'a\u201Bb.md', { type: 'text/markdown' }),
    ];
    fireEvent.drop(container, { dataTransfer: { types: ['Files'], files } });

    expect(terminal.input).toHaveBeenCalledWith(
      'pty-1',
      "'C:\\Users\\me\\\u2018\u2018draft.md' 'C:\\Users\\me\\Nick\u2019\u2019s notes.md' 'C:\\Users\\me\\a\u201A\u201Ab.md' 'C:\\Users\\me\\a\u201B\u201Bb.md' ",
    );
    expect(screen.queryByTestId('terminal-path-drop-notice-banner')).toBeNull();
  });

  test('a Git Bash terminal POSIX-quotes dropped Windows paths', async () => {
    const { bridge, terminal, pushNotice } = makeBridge(
      { ok: true, ptyId: 'pty-1' },
      WIRED,
      undefined,
      'win32',
    );
    (bridge as unknown as { getPathForFile: (file: File) => string }).getPathForFile = (file) =>
      `C:\\Users\\O'Brien\\${file.name}`;
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.onDataCb).toBeTruthy());
    act(() => pushNotice({ ptyId: 'pty-1', notice: 'shell-resolved', shellFamily: 'bash' }));

    const container = document.querySelector('[data-terminal-status]');
    if (container === null) throw new Error('terminal container not found');
    const file = new File(['x'], 'shot.png', { type: 'image/png' });
    fireEvent.drop(container, { dataTransfer: { types: ['Files'], files: [file] } });

    expect(terminal.input).toHaveBeenCalledWith('pty-1', "'C:\\Users\\O'\\''Brien\\shot.png' ");
  });

  test('a shell family learned before the start reply survives the start reply', async () => {
    const { bridge, terminal, pushNotice } = makeBridge(
      { ok: true, ptyId: 'pty-1' },
      WIRED,
      undefined,
      'win32',
    );
    let releaseStart = (): void => {};
    terminal.adopt.mockImplementationOnce(
      async () =>
        await new Promise<OkPtyAdoptResult>((resolve) => {
          releaseStart = () => resolve({ ok: true, replay: '' });
        }),
    );
    (bridge as unknown as { getPathForFile: (file: File) => string }).getPathForFile = () =>
      'C:\\Users\\A B\\safe.png';
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(terminal.start).toHaveBeenCalledWith('pty-1'));
    act(() => pushNotice({ ptyId: 'pty-1', notice: 'shell-resolved', shellFamily: 'cmd' }));
    await act(async () => {
      releaseStart();
      await Promise.resolve();
    });
    await waitFor(() =>
      expect(document.querySelector('[data-terminal-status="running"]')).toBeTruthy(),
    );

    const container = document.querySelector('[data-terminal-status]');
    if (container === null) throw new Error('terminal container not found');
    const file = new File(['x'], 'safe.png', { type: 'image/png' });
    fireEvent.drop(container, { dataTransfer: { types: ['Files'], files: [file] } });

    expect(terminal.input).toHaveBeenCalledWith('pty-1', '"C:\\Users\\A B\\safe.png" ');
    expect(screen.queryByTestId('terminal-path-drop-notice-banner')).toBeNull();
  });

  test('a cmd terminal quotes safe paths and refuses variable-expanding paths', async () => {
    const { bridge, terminal, pushNotice } = makeBridge(
      { ok: true, ptyId: 'pty-1' },
      WIRED,
      undefined,
      'win32',
    );
    (bridge as unknown as { getPathForFile: (file: File) => string }).getPathForFile = (file) =>
      file.name === 'unsafe.png' ? 'C:\\Users\\%USERNAME%\\unsafe.png' : 'C:\\Users\\A B\\safe.png';
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.onDataCb).toBeTruthy());
    act(() => pushNotice({ ptyId: 'pty-1', notice: 'shell-resolved', shellFamily: 'cmd' }));

    const container = document.querySelector('[data-terminal-status]');
    if (container === null) throw new Error('terminal container not found');
    const safe = new File(['x'], 'safe.png', { type: 'image/png' });
    const unsafe = new File(['y'], 'unsafe.png', { type: 'image/png' });
    const dataTransfer = { types: ['Files'], files: [safe, unsafe] };
    fireEvent.drop(container, { dataTransfer });

    expect(terminal.input).toHaveBeenCalledWith('pty-1', '"C:\\Users\\A B\\safe.png" ');
    expect(screen.getByTestId('terminal-path-drop-notice-banner').textContent).toMatch(
      /could not be inserted safely/i,
    );
  });

  test('a drop where every file resolves to no disk path writes nothing (clipboard blobs)', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
    (bridge as unknown as { getPathForFile: (f: File) => string }).getPathForFile = () => '';
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.onDataCb).toBeTruthy());

    const container = document.querySelector('[data-terminal-status]');
    if (container === null) throw new Error('terminal container not found');

    const blob = new File(['x'], 'pasted.png', { type: 'image/png' });
    const dataTransfer = { types: ['Files'], files: [blob] };
    fireEvent.dragOver(container, { dataTransfer });
    fireEvent.drop(container, { dataTransfer });

    expect(terminal.input).not.toHaveBeenCalled();
    expect(screen.getByTestId('terminal-path-drop-notice-banner')).toBeTruthy();
  });

  test('a mixed drop writes only the files that resolve to a disk path', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
    (bridge as unknown as { getPathForFile: (f: File) => string | null }).getPathForFile = (
      file,
    ) => (file.name === 'ghost.png' ? null : `/dropped/${file.name}`);
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.onDataCb).toBeTruthy());

    const container = document.querySelector('[data-terminal-status]');
    if (container === null) throw new Error('terminal container not found');

    const real = new File(['x'], 'shot.png', { type: 'image/png' });
    const ghost = new File(['y'], 'ghost.png', { type: 'image/png' });
    const dataTransfer = { types: ['Files'], files: [real, ghost] };
    fireEvent.dragOver(container, { dataTransfer });
    fireEvent.drop(container, { dataTransfer });

    expect(terminal.input).toHaveBeenCalledTimes(1);
    expect(terminal.input).toHaveBeenCalledWith('pty-1', "'/dropped/shot.png' ");
  });

  test('a dropped path containing a control char is filtered (no PTY command injection)', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.onDataCb).toBeTruthy());

    const container = document.querySelector('[data-terminal-status]');
    if (container === null) throw new Error('terminal container not found');

    const clean = new File(['x'], 'shot.png', { type: 'image/png' });
    const tainted = new File(['y'], 'a\nrm -rf ~.png', { type: 'image/png' });
    const dataTransfer = { types: ['Files'], files: [clean, tainted] };
    fireEvent.dragOver(container, { dataTransfer });
    fireEvent.drop(container, { dataTransfer });

    expect(terminal.input).toHaveBeenCalledTimes(1);
    expect(terminal.input).toHaveBeenCalledWith('pty-1', "'/dropped/shot.png' ");
  });

  describe('dropped file names with control characters', () => {
    const DROPPED_NAME_CONTROL_CHARACTERS: ReadonlyArray<
      readonly [label: string, character: string]
    > = [
      ['U+0000 (C0)', '\u0000'],
      ['U+0001 (C0)', '\u0001'],
      ['U+000A (C0)', '\u000a'],
      ['U+001B (C0)', '\u001b'],
      ['U+001F (C0)', '\u001f'],
      ['U+007F (DEL)', '\u007f'],
      ['U+0080 (C1)', '\u0080'],
      ['U+0085 (C1)', '\u0085'],
      ['U+009B (C1)', '\u009b'],
      ['U+009F (C1)', '\u009f'],
    ];
    const DROPPED_NAME_TYPED_CHARACTERS: ReadonlyArray<
      readonly [label: string, character: string]
    > = [
      ['U+0020', '\u0020'],
      ['U+007E', '\u007e'],
      ['U+00A0', '\u00a0'],
      ['U+200B', '\u200b'],
      ['U+200E', '\u200e'],
      ['U+2028', '\u2028'],
      ['U+202E', '\u202e'],
      ['U+202F', '\u202f'],
      ['U+2066', '\u2066'],
      ['U+FEFF', '\ufeff'],
    ];
    const DROP_TERMINALS: ReadonlyArray<{
      readonly label: string;
      readonly platform: OkDesktopBridge['platform'];
      readonly shellFamily: 'powershell' | 'cmd' | 'bash' | null;
      readonly root: string;
      readonly quote: string;
      readonly otherRefusedCharacters: string;
    }> = [
      {
        label: 'macOS',
        platform: 'darwin',
        shellFamily: null,
        root: '/dropped/',
        quote: "'",
        otherRefusedCharacters: '',
      },
      {
        label: 'Linux',
        platform: 'linux',
        shellFamily: null,
        root: '/dropped/',
        quote: "'",
        otherRefusedCharacters: '',
      },
      {
        label: 'Windows PowerShell',
        platform: 'win32',
        shellFamily: 'powershell',
        root: 'C:\\Users\\me\\',
        quote: "'",
        otherRefusedCharacters: '',
      },
      {
        label: 'Windows cmd',
        platform: 'win32',
        shellFamily: 'cmd',
        root: 'C:\\Users\\me\\',
        quote: '"',
        otherRefusedCharacters: '!"%',
      },
      {
        label: 'Windows Git Bash',
        platform: 'win32',
        shellFamily: 'bash',
        root: 'C:\\Users\\me\\',
        quote: "'",
        otherRefusedCharacters: '',
      },
    ];
    type DropTerminal = (typeof DROP_TERMINALS)[number];
    const LATIN_1_CODE_POINTS = Array.from({ length: 0x100 }, (_, codePoint) => codePoint);
    const isControlCodePoint = (codePoint: number): boolean =>
      codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f);
    const formatCodePoint = (codePoint: number): string =>
      `U+${codePoint.toString(16).toUpperCase().padStart(4, '0')}`;

    async function renderDropTarget(
      target: DropTerminal,
    ): Promise<(names: readonly string[]) => string[]> {
      const { bridge, terminal, pushNotice } = makeBridge(
        { ok: true, ptyId: 'pty-1' },
        WIRED,
        undefined,
        target.platform,
      );
      (bridge as unknown as { getPathForFile: (file: File) => string }).getPathForFile = (file) =>
        `${target.root}${file.name}`;
      render(<TerminalPanel bridge={bridge} />);
      await waitFor(() =>
        expect(document.querySelector('[data-terminal-status="running"]')).not.toBeNull(),
      );
      const { shellFamily } = target;
      if (shellFamily !== null) {
        act(() => pushNotice({ ptyId: 'pty-1', notice: 'shell-resolved', shellFamily }));
      }
      const container = document.querySelector('[data-terminal-status]');
      if (container === null) throw new Error('terminal container not found');
      return (names) => {
        const writesBefore = terminal.input.mock.calls.length;
        const files = names.map((name) => new File(['x'], name, { type: 'text/markdown' }));
        fireEvent.drop(container, { dataTransfer: { types: ['Files'], files } });
        return terminal.input.mock.calls.slice(writesBefore).map(([, data]) => data);
      };
    }

    function typedPath(target: DropTerminal, name: string): string {
      return `${target.quote}${target.root}${name}${target.quote}`;
    }

    describe.each(DROP_TERMINALS)('on a $label terminal', (target) => {
      const exceptions = Array.from(target.otherRefusedCharacters, (character) =>
        formatCodePoint(character.charCodeAt(0)),
      );

      test.each(DROPPED_NAME_CONTROL_CHARACTERS)(
        'leaves out a file whose name contains %s and types the rest of the drop',
        async (_label, character) => {
          const drop = await renderDropTarget(target);
          expect(drop(['before.md', `a${character}b.md`, 'after.md'])).toEqual([
            `${typedPath(target, 'before.md')} ${typedPath(target, 'after.md')} `,
          ]);
          expect(screen.getByTestId('terminal-path-drop-notice-banner')).toBeTruthy();
        },
      );

      test.each(DROPPED_NAME_TYPED_CHARACTERS)(
        'types a file whose name contains %s as-is',
        async (_label, character) => {
          const name = `a${character}b.md`;
          const drop = await renderDropTarget(target);
          expect(drop(['before.md', name, 'after.md'])).toEqual([
            `${typedPath(target, 'before.md')} ${typedPath(target, name)} ${typedPath(target, 'after.md')} `,
          ]);
          expect(screen.queryByTestId('terminal-path-drop-notice-banner')).toBeNull();
        },
      );

      test('types nothing when every dropped file name contains DEL or a C1 control', async () => {
        const drop = await renderDropTarget(target);
        expect(drop(['a\u007fb.md', 'c\u009bd.md'])).toEqual([]);
        expect(screen.getByTestId('terminal-path-drop-notice-banner')).toBeTruthy();
      });

      test('leaves out every file whose name contains a control character from U+0000 to U+00FF', async () => {
        const drop = await renderDropTarget(target);
        const controls = LATIN_1_CODE_POINTS.filter(isControlCodePoint);
        const leftOut = controls.filter(
          (codePoint) => drop([`a${String.fromCharCode(codePoint)}b.md`]).length === 0,
        );
        expect(leftOut.map(formatCodePoint)).toEqual(controls.map(formatCodePoint));
        expect(drop(['after.md'])).toEqual([`${typedPath(target, 'after.md')} `]);
      });

      test(`types a file whose name contains any other character from U+0000 to U+00FF${exceptions.length === 0 ? '' : ` except ${exceptions.join(', ')}`}`, async () => {
        const drop = await renderDropTarget(target);
        const others = LATIN_1_CODE_POINTS.filter(
          (codePoint) =>
            !isControlCodePoint(codePoint) &&
            !target.otherRefusedCharacters.includes(String.fromCharCode(codePoint)),
        );
        const typed = others.filter(
          (codePoint) => drop([`a${String.fromCharCode(codePoint)}b.md`]).length === 1,
        );
        expect(typed.map(formatCodePoint)).toEqual(others.map(formatCodePoint));
      });
    });
  });

  test('a drag that carries no external files is ignored (no PTY write)', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.onDataCb).toBeTruthy());

    const container = document.querySelector('[data-terminal-status]');
    if (container === null) throw new Error('terminal container not found');

    const dataTransfer = { types: ['text/plain'], files: [] };
    fireEvent.drop(container, { dataTransfer });
    expect(terminal.input).not.toHaveBeenCalled();
  });

  test('re-fits and resizes the PTY when the container resizes', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(roCallback).toBeTruthy());

    const fitsBefore = lastFit?.fit.mock.calls.length ?? 0;
    act(() => roCallback?.(sizedEntries(742, 380)));

    expect(lastFit?.fit.mock.calls.length ?? 0).toBeGreaterThan(fitsBefore);
    expect(terminal.resize).toHaveBeenCalledWith('pty-1', 80, 24);
  });

  test('a resize burst fits per event (no flicker) but coalesces PTY resizes: one leading, one trailing', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(roCallback).toBeTruthy());

    const fitsBefore = lastFit?.fit.mock.calls.length ?? 0;
    const resizesBefore = terminal.resize.mock.calls.length;
    act(() => {
      roCallback?.(sizedEntries(742, 380));
      roCallback?.(sizedEntries(742, 380));
      roCallback?.(sizedEntries(742, 380));
    });
    expect((lastFit?.fit.mock.calls.length ?? 0) - fitsBefore).toBe(3);
    expect(terminal.resize.mock.calls.length - resizesBefore).toBe(1);

    await waitFor(() => expect(terminal.resize.mock.calls.length - resizesBefore).toBe(2), {
      timeout: 1000,
    });
  });

  test('a resize notification from an unrendered container never collapses the grid or the PTY', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(roCallback).toBeTruthy());

    expect(lastFit).not.toBeNull();
    lastFit?.fit.mockImplementation(() => {
      if (lastTerm) {
        lastTerm.cols = 11;
        lastTerm.rows = 5;
      }
    });
    const fitsBefore = lastFit?.fit.mock.calls.length ?? 0;
    const resizesBefore = terminal.resize.mock.calls.length;

    act(() => roCallback?.(sizedEntries(0, 0)));

    expect(lastFit?.fit.mock.calls.length ?? 0).toBe(fitsBefore);
    expect(lastTerm?.cols).toBe(80);
    expect(lastTerm?.rows).toBe(24);
    expect(terminal.resize.mock.calls.length).toBe(resizesBefore);
    expect(terminal.resize).not.toHaveBeenCalledWith('pty-1', 11, 5);
  });

  test('the mount-time fit is skipped while the container is not rendered', async () => {
    const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(roCallback).toBeTruthy());

    expect(lastFit).not.toBeNull();
    expect(lastFit?.fit.mock.calls.length).toBe(0);
  });

  test('the mount-time fit is skipped when only padding gives the container width', async () => {
    stubContainerLayout({ width: 12, height: 380 }, { width: '0px', height: '380px' });

    const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(roCallback).toBeTruthy());

    expect(lastFit).not.toBeNull();
    expect(lastFit?.fit.mock.calls.length).toBe(0);
  });

  test('the mount-time fit runs once the container is rendered', async () => {
    stubContainerLayout({ width: 742, height: 380 }, { width: '730px', height: '380px' });

    const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);

    await waitFor(() => expect(lastFit?.fit.mock.calls.length ?? 0).toBeGreaterThan(0));
  });

  test('an adopted session forwards only the measured grid, never an unmeasured one', async () => {
    stubContainerLayout({ width: 742, height: 380 }, { width: '730px', height: '380px' });

    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-fresh' });
    render(<TerminalPanel bridge={bridge} adoptPtyId="pty-survivor" />);

    await waitFor(() => expect(terminal.adopt).toHaveBeenCalledWith('pty-survivor'));
    expect(lastFit).not.toBeNull();
    expect(lastFit?.fit.mock.calls.length).toBeGreaterThan(0);
    expect(terminal.resize).not.toHaveBeenCalled();

    await waitFor(() => expect(roCallback).toBeTruthy());
    lastFit?.fit.mockImplementation(() => {
      if (lastTerm) {
        lastTerm.cols = 200;
        lastTerm.rows = 50;
      }
    });
    act(() => roCallback?.(sizedEntries(742, 380)));

    expect(terminal.resize).toHaveBeenCalledWith('pty-survivor', 200, 50);
  });

  test('an adopted session mounted hidden sends the live PTY no grid until the container is rendered', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-fresh' });
    render(<TerminalPanel bridge={bridge} adoptPtyId="pty-survivor" />);

    await waitFor(() => expect(terminal.adopt).toHaveBeenCalledWith('pty-survivor'));
    expect(lastFit).not.toBeNull();
    expect(lastFit?.fit.mock.calls.length).toBe(0);
    expect(terminal.resize).not.toHaveBeenCalled();

    await waitFor(() => expect(roCallback).toBeTruthy());
    lastFit?.fit.mockImplementation(() => {
      if (lastTerm) {
        lastTerm.cols = 200;
        lastTerm.rows = 50;
      }
    });
    act(() => roCallback?.(sizedEntries(742, 380)));

    expect(lastFit?.fit.mock.calls.length ?? 0).toBe(1);
    expect(terminal.resize).toHaveBeenCalledWith('pty-survivor', 200, 50);
  });

  test('a grid-changing fit repaints synchronously in the same frame (no blank-frame flash)', async () => {
    const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(roCallback).toBeTruthy());

    act(() => roCallback?.(sizedEntries(742, 380)));
    expect(lastTerm?.renderFlush).not.toHaveBeenCalled();

    lastFit?.fit.mockImplementation(() => {
      if (lastTerm) lastTerm.cols = 100;
    });
    act(() => roCallback?.(sizedEntries(742, 380)));
    expect(lastTerm?.refresh).toHaveBeenCalled();
    expect(lastTerm?.renderFlush).toHaveBeenCalledTimes(1);
  });

  test('a grid-changing fit keeps a scrolled-back viewport on the line it was reading', async () => {
    const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(roCallback).toBeTruthy());

    if (lastTerm) {
      lastTerm.viewportY = 120;
      lastTerm.baseY = 120;
      lastTerm.scrollbarLine = 7;
    }
    lastFit?.fit.mockImplementation(() => {
      if (lastTerm) lastTerm.cols += 1;
    });
    act(() => roCallback?.(sizedEntries(742, 380)));
    expect(lastTerm?.viewportY).toBe(120);
    expect(lastTerm?.scrollbarLine).toBe(7);
    expect(lastTerm?.pendingScrollTarget).toBeNull();
    expect(lastTerm?.smoothScrollWrites()).toBe(0);

    if (lastTerm) {
      lastTerm.viewportY = 34;
      lastTerm.scrollbarLine = 0;
      lastTerm.renderFlush.mockClear();
      lastTerm.scrollToBottom.mockClear();
    }
    act(() => roCallback?.(sizedEntries(742, 380)));
    expect(lastTerm?.renderFlush.mock.invocationCallOrder[0]).toBeLessThan(
      lastTerm?.scrollToBottom.mock.invocationCallOrder[0] ?? 0,
    );
    expect(lastTerm?.viewportY).toBe(34);
    expect(lastTerm?.scrollbarLine).toBe(34);
    expect(lastTerm?.pendingScrollTarget).toBeNull();
    expect(lastTerm?.smoothScrollWrites()).toBe(2);
    expect(lastTerm?.options.smoothScrollDuration).toBe(125);

    if (lastTerm) {
      lastTerm.viewportY = 12;
      lastTerm.scrollbarLine = 3;
    }
    lastFit?.fit.mockImplementation(() => {});
    act(() => roCallback?.(sizedEntries(742, 380)));
    expect(lastTerm?.viewportY).toBe(12);
    expect(lastTerm?.scrollbarLine).toBe(3);
    expect(lastTerm?.pendingScrollTarget).toBeNull();
  });

  test("the WebGL canvas's device-pixel re-clear also repaints in the same frame", async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(terminal.create).toHaveBeenCalledTimes(1));

    const canvas = document.querySelector('.xterm-screen canvas');
    expect(canvas).toBeTruthy();
    const canvasRO = allROs.find((ro) => ro.observed.some((o) => o.el === canvas));
    expect(canvasRO).toBeTruthy();
    expect(canvasRO?.observed[0]?.opts).toEqual({ box: 'device-pixel-content-box' });

    const flushesBefore = lastTerm?.renderFlush.mock.calls.length ?? 0;
    act(() => canvasRO?.cb());
    expect((lastTerm?.renderFlush.mock.calls.length ?? 0) - flushesBefore).toBe(1);
  });

  test('cancels the browser default for Shift+Tab only; every other key (incl. Escape) reaches the PTY', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.onDataCb).toBeTruthy());

    expect(lastTerm?.attachCustomKeyEventHandler).toHaveBeenCalledTimes(1);
    const handler = lastTerm?.keyHandler;
    expect(handler).toBeTruthy();

    const shiftTabPreventDefault = vi.fn(() => {});
    const shiftTab = {
      type: 'keydown',
      key: 'Tab',
      shiftKey: true,
      preventDefault: shiftTabPreventDefault,
    } as unknown as KeyboardEvent;
    expect(handler?.(shiftTab)).toBe(true);
    expect(shiftTabPreventDefault).toHaveBeenCalledTimes(1);

    const plainTabPreventDefault = vi.fn(() => {});
    const plainTab = {
      type: 'keydown',
      key: 'Tab',
      shiftKey: false,
      preventDefault: plainTabPreventDefault,
    } as unknown as KeyboardEvent;
    expect(handler?.(plainTab)).toBe(true);
    expect(plainTabPreventDefault).not.toHaveBeenCalled();

    const escapePreventDefault = vi.fn(() => {});
    const escapeKey = {
      type: 'keydown',
      key: 'Escape',
      shiftKey: false,
      preventDefault: escapePreventDefault,
    } as unknown as KeyboardEvent;
    expect(handler?.(escapeKey)).toBe(true);
    expect(escapePreventDefault).not.toHaveBeenCalled();

    act(() => lastTerm?.onDataCb?.('\x1b'));
    expect(terminal.input).toHaveBeenCalledWith('pty-1', '\x1b');
  });

  test('Shift+Enter sends a newline (LF) to the PTY instead of submitting (CR)', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.onDataCb).toBeTruthy());
    const handler = lastTerm?.keyHandler;
    expect(handler).toBeTruthy();

    const shiftEnterPreventDefault = vi.fn(() => {});
    const shiftEnter = {
      type: 'keydown',
      key: 'Enter',
      shiftKey: true,
      preventDefault: shiftEnterPreventDefault,
    } as unknown as KeyboardEvent;
    expect(handler?.(shiftEnter)).toBe(false);
    expect(shiftEnterPreventDefault).toHaveBeenCalledTimes(1);
    expect(terminal.input).toHaveBeenCalledWith('pty-1', '\n');

    const plainEnterPreventDefault = vi.fn(() => {});
    const plainEnter = {
      type: 'keydown',
      key: 'Enter',
      shiftKey: false,
      preventDefault: plainEnterPreventDefault,
    } as unknown as KeyboardEvent;
    expect(handler?.(plainEnter)).toBe(true);
    expect(plainEnterPreventDefault).not.toHaveBeenCalled();
  });

  test('Linux Ctrl+C and Ctrl+V bypass menu accelerators and still reach the PTY', async () => {
    const { bridge, terminal } = makeBridge(
      { ok: true, ptyId: 'pty-1' },
      WIRED,
      undefined,
      'linux',
    );
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.onDataCb).toBeTruthy());
    const handler = lastTerm?.keyHandler;
    expect(handler).toBeTruthy();

    for (const [key, bytes] of [
      ['c', '\x03'],
      ['v', '\x16'],
    ] as const) {
      const preventDefault = vi.fn(() => {});
      expect(
        handler?.({
          type: 'keydown',
          key,
          ctrlKey: true,
          shiftKey: false,
          altKey: false,
          metaKey: false,
          preventDefault,
        } as unknown as KeyboardEvent),
      ).toBe(true);
      expect(preventDefault).toHaveBeenCalledTimes(1);
      act(() => lastTerm?.onDataCb?.(bytes));
      expect(terminal.input).toHaveBeenLastCalledWith('pty-1', bytes);
    }
  });

  test('Linux Ctrl+Shift+C copies the xterm selection and Ctrl+Shift+V pastes clipboard text', async () => {
    const { bridge, terminal } = makeBridge(
      { ok: true, ptyId: 'pty-1' },
      WIRED,
      undefined,
      'linux',
    );
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.onDataCb).toBeTruthy());
    const handler = lastTerm?.keyHandler;
    expect(handler).toBeTruthy();
    if (lastTerm) lastTerm.selection = 'selected output';

    const copyPreventDefault = vi.fn(() => {});
    expect(
      handler?.({
        type: 'keydown',
        key: 'C',
        ctrlKey: true,
        shiftKey: true,
        altKey: false,
        metaKey: false,
        preventDefault: copyPreventDefault,
      } as unknown as KeyboardEvent),
    ).toBe(false);
    expect(copyPreventDefault).toHaveBeenCalledTimes(1);
    await waitFor(() =>
      expect(navigator.clipboard.writeText).toHaveBeenCalledWith('selected output'),
    );

    const pastePreventDefault = vi.fn(() => {});
    expect(
      handler?.({
        type: 'keydown',
        key: 'V',
        ctrlKey: true,
        shiftKey: true,
        altKey: false,
        metaKey: false,
        preventDefault: pastePreventDefault,
      } as unknown as KeyboardEvent),
    ).toBe(false);
    expect(pastePreventDefault).toHaveBeenCalledTimes(1);
    await waitFor(() => expect(lastTerm?.paste).toHaveBeenCalledWith('clipboard paste'));
    expect(terminal.input).not.toHaveBeenCalledWith('pty-1', 'clipboard paste');
  });

  test('Linux Ctrl+Shift+C consumes the clipboard chord when xterm has no selection', async () => {
    const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' }, WIRED, undefined, 'linux');
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.keyHandler).toBeTruthy());

    const preventDefault = vi.fn(() => {});
    expect(
      lastTerm?.keyHandler?.({
        type: 'keydown',
        key: 'C',
        ctrlKey: true,
        shiftKey: true,
        altKey: false,
        metaKey: false,
        preventDefault,
      } as unknown as KeyboardEvent),
    ).toBe(false);
    expect(preventDefault).toHaveBeenCalledTimes(1);
    expect(navigator.clipboard.writeText).not.toHaveBeenCalled();
  });

  test('Windows Ctrl+C copies with a selection and interrupts without one', async () => {
    const { bridge, terminal } = makeBridge(
      { ok: true, ptyId: 'pty-1' },
      WIRED,
      undefined,
      'win32',
    );
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.keyHandler).toBeTruthy());
    const handler = lastTerm?.keyHandler;

    if (lastTerm) lastTerm.selection = 'selected output';
    const copyPreventDefault = vi.fn(() => {});
    expect(
      handler?.({
        type: 'keydown',
        key: 'c',
        ctrlKey: true,
        shiftKey: false,
        altKey: false,
        metaKey: false,
        preventDefault: copyPreventDefault,
      } as unknown as KeyboardEvent),
    ).toBe(false);
    expect(copyPreventDefault).toHaveBeenCalledTimes(1);
    await waitFor(() =>
      expect(navigator.clipboard.writeText).toHaveBeenCalledWith('selected output'),
    );

    vi.mocked(navigator.clipboard.writeText).mockClear();
    expect(lastTerm?.clearSelection).toHaveBeenCalledTimes(1);
    const interruptPreventDefault = vi.fn(() => {});
    expect(
      handler?.({
        type: 'keydown',
        key: 'c',
        ctrlKey: true,
        shiftKey: false,
        altKey: false,
        metaKey: false,
        preventDefault: interruptPreventDefault,
      } as unknown as KeyboardEvent),
    ).toBe(true);
    expect(interruptPreventDefault).toHaveBeenCalledTimes(1);
    expect(navigator.clipboard.writeText).not.toHaveBeenCalled();
    act(() => lastTerm?.onDataCb?.('\x03'));
    expect(terminal.input).toHaveBeenLastCalledWith('pty-1', '\x03');
  });

  test('Windows Ctrl+Shift+C copies and both Ctrl+V chords paste', async () => {
    const { bridge, terminal } = makeBridge(
      { ok: true, ptyId: 'pty-1' },
      WIRED,
      undefined,
      'win32',
    );
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.keyHandler).toBeTruthy());
    const handler = lastTerm?.keyHandler;
    if (lastTerm) lastTerm.selection = 'shift-selected';

    expect(
      handler?.({
        type: 'keydown',
        key: 'C',
        ctrlKey: true,
        shiftKey: true,
        altKey: false,
        metaKey: false,
        preventDefault: vi.fn(() => {}),
      } as unknown as KeyboardEvent),
    ).toBe(false);
    await waitFor(() =>
      expect(navigator.clipboard.writeText).toHaveBeenCalledWith('shift-selected'),
    );

    for (const shiftKey of [false, true]) {
      const preventDefault = vi.fn(() => {});
      expect(
        handler?.({
          type: 'keydown',
          key: 'V',
          ctrlKey: true,
          shiftKey,
          altKey: false,
          metaKey: false,
          preventDefault,
        } as unknown as KeyboardEvent),
      ).toBe(false);
      expect(preventDefault).toHaveBeenCalledTimes(1);
    }
    await waitFor(() => expect(lastTerm?.paste).toHaveBeenCalledTimes(2));
    expect(lastTerm?.paste).toHaveBeenNthCalledWith(1, 'clipboard paste');
    expect(lastTerm?.paste).toHaveBeenNthCalledWith(2, 'clipboard paste');
    expect(terminal.input).not.toHaveBeenCalledWith('pty-1', 'clipboard paste');
  });

  test('Linux paste ignores clipboard text that resolves after the terminal unmounts', async () => {
    let resolveClipboard: ((text: string) => void) | null = null;
    Object.defineProperty(globalThis.navigator, 'clipboard', {
      configurable: true,
      value: {
        readText: vi.fn(() => {
          const { promise, resolve } = Promise.withResolvers<string>();
          resolveClipboard = resolve;
          return promise;
        }),
        writeText: vi.fn(async () => {}),
      },
    });
    const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' }, WIRED, undefined, 'linux');
    const { unmount } = render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.keyHandler).toBeTruthy());

    expect(
      lastTerm?.keyHandler?.({
        type: 'keydown',
        key: 'V',
        ctrlKey: true,
        shiftKey: true,
        altKey: false,
        metaKey: false,
        preventDefault: vi.fn(() => {}),
      } as unknown as KeyboardEvent),
    ).toBe(false);
    const term = lastTerm;
    unmount();
    await act(async () => resolveClipboard?.('late clipboard text'));

    expect(term?.paste).not.toHaveBeenCalled();
  });

  test('macOS leaves Ctrl+Shift+C and Ctrl+Shift+V on xterm’s existing path', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.onDataCb).toBeTruthy());
    const handler = lastTerm?.keyHandler;

    for (const key of ['C', 'V']) {
      const preventDefault = vi.fn(() => {});
      expect(
        handler?.({
          type: 'keydown',
          key,
          ctrlKey: true,
          shiftKey: true,
          altKey: false,
          metaKey: false,
          preventDefault,
        } as unknown as KeyboardEvent),
      ).toBe(true);
      expect(preventDefault).not.toHaveBeenCalled();
    }
    expect(navigator.clipboard.writeText).not.toHaveBeenCalled();
    expect(navigator.clipboard.readText).not.toHaveBeenCalled();
    expect(lastTerm?.paste).not.toHaveBeenCalled();
    expect(terminal.input).not.toHaveBeenCalledWith('pty-1', 'clipboard paste');
  });

  test('wheel handler defers to xterm in normal scrollback, drives the PTY in mouse mode', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.wheelHandler).toBeTruthy());
    const term = lastTerm;
    if (term?.wheelHandler == null) throw new Error('wheel handler not attached');
    const wheel = term.wheelHandler;

    term.modes.mouseTrackingMode = 'none';
    expect(wheel({ deltaY: 120, deltaMode: 0 } as unknown as WheelEvent)).toBe(true);
    expect(terminal.input).not.toHaveBeenCalled();

    term.modes.mouseTrackingMode = 'any';
    term.mouseEncoding = 'DEFAULT';
    expect(wheel({ deltaY: 120, deltaMode: 0 } as unknown as WheelEvent)).toBe(true);
    expect(terminal.input).not.toHaveBeenCalled();

    term.mouseEncoding = 'SGR';
    expect(wheel({ deltaY: 120, deltaMode: 0 } as unknown as WheelEvent)).toBe(false);
    expect(terminal.input).toHaveBeenCalledTimes(1);
    const [ptyId, payload] = terminal.input.mock.calls[0] as [string, string];
    expect(ptyId).toBe('pty-1');
    const downTick = '\x1b[<65;40;12M';
    expect(payload.length).toBeGreaterThan(0);
    expect(payload.length % downTick.length).toBe(0);
    expect(payload.replaceAll(downTick, '')).toBe('');

    terminal.input.mockClear();
    term.mouseEncoding = 'SGR_PIXELS';
    expect(wheel({ deltaY: 120, deltaMode: 0 } as unknown as WheelEvent)).toBe(false);
    expect(terminal.input).toHaveBeenCalledTimes(1);
    const [, pxPayload] = terminal.input.mock.calls[0] as [string, string];
    const pxTick = '\x1b[<65;400;204M';
    expect(pxPayload.length).toBeGreaterThan(0);
    expect(pxPayload.length % pxTick.length).toBe(0);
    expect(pxPayload.replaceAll(pxTick, '')).toBe('');
  });

  test('wheel reports carry the pointer cell so hit-testing TUIs scroll the hovered component', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.wheelHandler).toBeTruthy());
    const term = lastTerm;
    if (term?.wheelHandler == null) throw new Error('wheel handler not attached');
    term.modes.mouseTrackingMode = 'any';
    term.mouseEncoding = 'SGR';

    const screenEl = document.createElement('div');
    screenEl.className = 'xterm-screen';
    screenEl.getBoundingClientRect = () => ({ left: 100, top: 50 }) as DOMRect;
    const host = document.createElement('div');
    host.appendChild(screenEl);
    term.element = host;

    expect(
      term.wheelHandler({
        deltaY: 120,
        deltaMode: 0,
        clientX: 605,
        clientY: 160,
      } as unknown as WheelEvent),
    ).toBe(false);
    expect(terminal.input).toHaveBeenCalledTimes(1);
    const [, payload] = terminal.input.mock.calls[0] as [string, string];
    const tick = '\x1b[<65;51;7M';
    expect(payload.length).toBeGreaterThan(0);
    expect(payload.length % tick.length).toBe(0);
    expect(payload.replaceAll(tick, '')).toBe('');
  });

  test('pointer mapping falls back to the terminal element rect when .xterm-screen is absent', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.wheelHandler).toBeTruthy());
    const term = lastTerm;
    if (term?.wheelHandler == null) throw new Error('wheel handler not attached');
    term.modes.mouseTrackingMode = 'any';
    term.mouseEncoding = 'SGR';

    const host = document.createElement('div');
    host.getBoundingClientRect = () => ({ left: 200, top: 100 }) as DOMRect;
    term.element = host;

    expect(
      term.wheelHandler({
        deltaY: 120,
        deltaMode: 0,
        clientX: 705,
        clientY: 210,
      } as unknown as WheelEvent),
    ).toBe(false);
    expect(terminal.input).toHaveBeenCalledTimes(1);
    const [, payload] = terminal.input.mock.calls[0] as [string, string];
    const tick = '\x1b[<65;51;7M';
    expect(payload.length).toBeGreaterThan(0);
    expect(payload.length % tick.length).toBe(0);
    expect(payload.replaceAll(tick, '')).toBe('');
  });

  test('mode transition resets the wheel accumulator (no stale carry across apps)', async () => {
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm?.wheelHandler).toBeTruthy());
    const term = lastTerm;
    if (term?.wheelHandler == null) throw new Error('wheel handler not attached');
    const wheel = term.wheelHandler;
    term.mouseEncoding = 'SGR';

    term.modes.mouseTrackingMode = 'any';
    expect(wheel({ deltaY: 30, deltaMode: 0 } as unknown as WheelEvent)).toBe(false);
    expect(terminal.input).toHaveBeenCalledTimes(1);

    term.modes.mouseTrackingMode = 'none';
    expect(wheel({ deltaY: 5, deltaMode: 0 } as unknown as WheelEvent)).toBe(true);

    term.modes.mouseTrackingMode = 'any';
    terminal.input.mockClear();
    expect(wheel({ deltaY: 10, deltaMode: 0 } as unknown as WheelEvent)).toBe(false);
    expect(terminal.input).not.toHaveBeenCalled();
  });

  test('disposes the terminal, kills the PTY, and unsubscribes on unmount', async () => {
    const { bridge, terminal, unsubData, unsubExit } = makeBridge({ ok: true, ptyId: 'pty-1' });
    const { unmount } = render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(roCallback).toBeTruthy());

    const term = lastTerm;
    const ros = allROs.slice();
    expect(ros.length).toBe(2);
    act(() => unmount());

    expect(term?.dispose).toHaveBeenCalledTimes(1);
    expect(terminal.kill).toHaveBeenCalledWith('pty-1');
    expect(unsubData).toHaveBeenCalledTimes(1);
    expect(unsubExit).toHaveBeenCalledTimes(1);
    for (const ro of ros) expect(ro.disconnect).toHaveBeenCalledTimes(1);
  });

  test('leaves a PTY for reload adoption only while a non-bfcache pagehide remains active', async () => {
    const removeWindowListener = vi.spyOn(window, 'removeEventListener');
    const removeDocumentListener = vi.spyOn(document, 'removeEventListener');
    const originalVisibilityState = Object.getOwnPropertyDescriptor(document, 'visibilityState');
    onTestFinished(() => {
      removeWindowListener.mockRestore();
      removeDocumentListener.mockRestore();
      if (originalVisibilityState === undefined) {
        Reflect.deleteProperty(document, 'visibilityState');
      } else {
        Object.defineProperty(document, 'visibilityState', originalVisibilityState);
      }
    });
    const first = makeBridge({ ok: true, ptyId: 'pty-reload' });
    const firstView = render(<TerminalPanel bridge={first.bridge} />);
    await waitFor(() => expect(first.terminal.create).toHaveBeenCalledTimes(1));

    act(() => {
      window.dispatchEvent(new PageTransitionEvent('pagehide', { persisted: false }));
      firstView.unmount();
    });
    expect(first.terminal.kill).not.toHaveBeenCalled();
    expect(removeWindowListener).toHaveBeenCalledWith('pagehide', expect.any(Function));
    expect(removeDocumentListener).toHaveBeenCalledWith('visibilitychange', expect.any(Function));

    const second = makeBridge({ ok: true, ptyId: 'pty-bfcache' });
    const secondView = render(<TerminalPanel bridge={second.bridge} />);
    await waitFor(() => expect(second.terminal.create).toHaveBeenCalledTimes(1));

    act(() => {
      window.dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
      secondView.unmount();
    });
    expect(second.terminal.kill).toHaveBeenCalledWith('pty-bfcache');

    const hidden = makeBridge({ ok: true, ptyId: 'pty-still-unloading' });
    const hiddenView = render(<TerminalPanel bridge={hidden.bridge} />);
    await waitFor(() => expect(hidden.terminal.create).toHaveBeenCalledTimes(1));

    act(() => {
      window.dispatchEvent(new PageTransitionEvent('pagehide', { persisted: false }));
      Object.defineProperty(document, 'visibilityState', { configurable: true, value: 'hidden' });
      document.dispatchEvent(new Event('visibilitychange'));
      hiddenView.unmount();
    });
    expect(hidden.terminal.kill).not.toHaveBeenCalled();

    const visible = makeBridge({ ok: true, ptyId: 'pty-restored' });
    const visibleView = render(<TerminalPanel bridge={visible.bridge} />);
    await waitFor(() => expect(visible.terminal.create).toHaveBeenCalledTimes(1));

    act(() => {
      window.dispatchEvent(new PageTransitionEvent('pagehide', { persisted: false }));
      Object.defineProperty(document, 'visibilityState', { configurable: true, value: 'visible' });
      document.dispatchEvent(new Event('visibilitychange'));
      visibleView.unmount();
    });
    expect(visible.terminal.kill).toHaveBeenCalledWith('pty-restored');
  });

  test('degrades to the DOM renderer when WebGL is unavailable instead of failing the mount', async () => {
    webglThrows = true;
    const { bridge, terminal, pushData } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);

    await waitFor(() => expect(terminal.onData).toHaveBeenCalledTimes(1));
    act(() => pushData({ ptyId: 'pty-1', data: 'ok' }));
    expect(lastTerm?.write).toHaveBeenCalledTimes(1);
  });

  test('ignores data addressed to a different PTY', async () => {
    const { bridge, terminal, pushData } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(terminal.onData).toHaveBeenCalledTimes(1));

    act(() => pushData({ ptyId: 'someone-else', data: 'leak' }));
    expect(lastTerm?.write).not.toHaveBeenCalled();
    expect(terminal.drain).not.toHaveBeenCalled();

    act(() => pushData({ ptyId: 'pty-1', data: 'mine' }));
    expect(lastTerm?.write).toHaveBeenCalledTimes(1);
    expect(lastTerm?.write.mock.calls[0]?.[0]).toBe('mine');
  });

  test('shows a translated pane notice when an invalid shell override is skipped', async () => {
    const { bridge, terminal, pushNotice } = makeBridge(
      { ok: true, ptyId: 'pty-1' },
      WIRED,
      undefined,
      'win32',
    );
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(terminal.onNotice).toHaveBeenCalledTimes(1));

    act(() =>
      pushNotice({ ptyId: 'pty-1', notice: 'invalid-shell-override', reason: 'not-found' }),
    );

    const banner = screen.getByTestId('terminal-shell-notice-banner');
    expect(banner.textContent).toMatch(/terminal\.shell executable.*was not found/i);
    fireEvent.click(screen.getByRole('button', { name: 'Dismiss' }));
    expect(screen.queryByTestId('terminal-shell-notice-banner')).toBeNull();
  });

  test('explains the capability boundary for an unsupported Windows shell override', async () => {
    const { bridge, terminal, pushNotice } = makeBridge(
      { ok: true, ptyId: 'pty-1' },
      WIRED,
      undefined,
      'win32',
    );
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(terminal.onNotice).toHaveBeenCalledTimes(1));

    act(() =>
      pushNotice({
        ptyId: 'pty-1',
        notice: 'invalid-shell-override',
        reason: 'unsupported-family',
      }),
    );

    expect(screen.getByTestId('terminal-shell-notice-banner').textContent).toMatch(
      /\.ok\/local\/config\.yml.*PowerShell.*cmd\.exe.*Git Bash.*plain terminal only.*agent and command launches do not run/i,
    );
  });

  test('does not lose a shell notice delivered before create resolves', async () => {
    const h = makeBridge({ ok: true, ptyId: 'pty-1' }, WIRED, undefined, 'win32');
    h.terminal.create.mockImplementationOnce(async () => {
      h.pushNotice({
        ptyId: 'pty-1',
        notice: 'invalid-shell-override',
        reason: 'not-found',
      });
      return { ok: true as const, ptyId: 'pty-1' };
    });

    render(<TerminalPanel bridge={h.bridge} />);

    expect((await screen.findByTestId('terminal-shell-notice-banner')).textContent).toMatch(
      /terminal\.shell executable.*was not found/i,
    );
  });

  test.each([
    ['containment-refused', /not safely contained.*not a link.*approve OpenKnowledge/i],
    ['write-failed', /\.ok\/local\/terminal.*folder is writable.*approve OpenKnowledge/i],
  ] as const)('shows the support-file degradation notice for %s', async (reason, copy) => {
    const { bridge, terminal, pushNotice } = makeBridge(
      { ok: true, ptyId: 'pty-1' },
      WIRED,
      undefined,
      'win32',
    );
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(terminal.onNotice).toHaveBeenCalledTimes(1));

    act(() => pushNotice({ ptyId: 'pty-1', notice: 'support-file-degraded', reason }));

    const banner = screen.getByTestId('terminal-support-file-notice-banner');
    expect(banner.textContent).toMatch(copy);
  });

  test('shows one operational notice at a time and reveals the next after dismissal', async () => {
    const { bridge, terminal, pushNotice } = makeBridge(
      { ok: true, ptyId: 'pty-1' },
      WIRED,
      undefined,
      'win32',
    );
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(terminal.onNotice).toHaveBeenCalledTimes(1));

    act(() => {
      pushNotice({ ptyId: 'pty-1', notice: 'invalid-shell-override', reason: 'not-found' });
      pushNotice({ ptyId: 'pty-1', notice: 'support-file-degraded', reason: 'write-failed' });
    });

    expect(screen.getByTestId('terminal-support-file-notice-banner')).toBeTruthy();
    expect(screen.queryByTestId('terminal-shell-notice-banner')).toBeNull();
    fireEvent.click(screen.getByRole('button', { name: 'Dismiss' }));
    expect(screen.getByTestId('terminal-shell-notice-banner')).toBeTruthy();
  });

  test('a new launch clears shell and dropped-path notices from the previous session', async () => {
    const { bridge, terminal, pushNotice } = makeBridge(
      { ok: true, ptyId: 'pty-1' },
      WIRED,
      undefined,
      'win32',
    );
    (bridge as unknown as { getPathForFile: (file: File) => string }).getPathForFile = () =>
      'C:\\Users\\%USERNAME%\\unsafe.png';
    const { rerender } = render(
      <TerminalPanel bridge={bridge} launch={{ prompt: null, cli: 'claude', nonce: 1 }} />,
    );
    await waitFor(() => expect(terminal.onNotice).toHaveBeenCalledTimes(1));

    act(() => {
      pushNotice({ ptyId: 'pty-1', notice: 'shell-resolved', shellFamily: 'cmd' });
      pushNotice({ ptyId: 'pty-1', notice: 'invalid-shell-override', reason: 'not-found' });
    });
    const container = document.querySelector('[data-terminal-status]');
    if (container === null) throw new Error('terminal container not found');
    fireEvent.drop(container, {
      dataTransfer: {
        types: ['Files'],
        files: [new File(['x'], 'unsafe.png', { type: 'image/png' })],
      },
    });

    rerender(<TerminalPanel bridge={bridge} launch={{ prompt: null, cli: 'claude', nonce: 2 }} />);
    await waitFor(() => expect(terminal.create).toHaveBeenCalledTimes(2));
    expect(screen.queryByTestId('terminal-shell-notice-banner')).toBeNull();
    expect(screen.queryByTestId('terminal-path-drop-notice-banner')).toBeNull();
  });

  test('shows operational notices before the routine manual-submit notice', async () => {
    const { bridge, terminal, pushNotice } = makeBridge(
      { ok: true, ptyId: 'pty-1' },
      WIRED,
      undefined,
      'win32',
    );
    (bridge as unknown as { getPathForFile: (file: File) => string }).getPathForFile = () =>
      'C:\\Users\\%USERNAME%\\unsafe.png';
    render(
      <TerminalPanel
        bridge={bridge}
        launch={{ prompt: 'review this safely', cli: 'claude', nonce: 1 }}
      />,
    );
    await waitFor(() =>
      expect(document.querySelector('[data-terminal-status="running"]')).not.toBeNull(),
    );

    act(() => {
      pushNotice({ ptyId: 'pty-1', notice: 'shell-resolved', shellFamily: 'cmd' });
      pushNotice({ ptyId: 'pty-1', notice: 'invalid-shell-override', reason: 'not-found' });
      pushNotice({ ptyId: 'pty-1', notice: 'support-file-degraded', reason: 'write-failed' });
    });
    const container = document.querySelector('[data-terminal-status]');
    if (container === null) throw new Error('terminal container not found');
    fireEvent.drop(container, {
      dataTransfer: {
        types: ['Files'],
        files: [new File(['x'], 'unsafe.png', { type: 'image/png' })],
      },
    });

    await waitFor(() => expect(terminal.input).toHaveBeenCalled(), { timeout: 6_000 });
    expect(screen.getByTestId('terminal-path-drop-notice-banner')).toBeTruthy();
    expect(screen.queryByTestId('terminal-manual-submit-notice-banner')).toBeNull();
    fireEvent.click(screen.getByRole('button', { name: 'Dismiss' }));
    expect(screen.getByTestId('terminal-support-file-notice-banner')).toBeTruthy();
    fireEvent.click(screen.getByRole('button', { name: 'Dismiss' }));
    expect(screen.getByTestId('terminal-shell-notice-banner')).toBeTruthy();
    fireEvent.click(screen.getByRole('button', { name: 'Dismiss' }));
    expect(screen.getByTestId('terminal-manual-submit-notice-banner')).toBeTruthy();
  }, 10_000);

  test('reports the no-project state and wires no data stream when the window has no project', async () => {
    const { bridge, terminal } = makeBridge({ ok: false, reason: 'no-project' });
    render(<TerminalPanel bridge={bridge} />);

    await waitFor(() =>
      expect(document.querySelector('[data-terminal-status="no-project"]')).not.toBeNull(),
    );
    expect(terminal.onData).not.toHaveBeenCalled();
    expect(terminal.drain).not.toHaveBeenCalled();
    expect(screen.getByRole('region', { name: 'Terminal' })).toBeTruthy();
    const alert = await screen.findByRole('alert');
    expect(alert.textContent).toMatch(/no project folder/i);
    expect(lastTerm?.focus).not.toHaveBeenCalled();
  });

  test('renders a refusal notice (not a blank canvas) when main refuses with not-consented', async () => {
    const onClose = vi.fn(() => {});
    const { bridge, terminal } = makeBridge({ ok: false, reason: 'not-consented' });
    render(<TerminalPanel bridge={bridge} onClose={onClose} />);

    await waitFor(() =>
      expect(document.querySelector('[data-terminal-status="not-consented"]')).not.toBeNull(),
    );
    const alert = await screen.findByRole('alert');
    expect(alert.textContent).toMatch(/isn't enabled for this project/i);
    expect(lastTerm?.focus).not.toHaveBeenCalled();
    expect(terminal.onData).not.toHaveBeenCalled();
    const closeButton = screen.getByRole('button', { name: 'Close terminal' });
    fireEvent.click(closeButton);
    expect(onClose).toHaveBeenCalledTimes(1);
  });

  test('omits the "Close terminal" button when no onClose is provided', async () => {
    const { bridge } = makeBridge({ ok: false, reason: 'not-consented' });
    render(<TerminalPanel bridge={bridge} />);

    await waitFor(() =>
      expect(document.querySelector('[data-terminal-status="not-consented"]')).not.toBeNull(),
    );
    await screen.findByRole('alert');
    expect(screen.queryByRole('button', { name: 'Close terminal' })).toBeNull();
  });

  test('reaps a PTY that finishes spawning after the panel has already unmounted', async () => {
    const { promise: createPromise, resolve: resolveCreate } =
      Promise.withResolvers<OkPtyCreateResult>();
    const kill = vi.fn(async (_id: string) => {});
    const terminal = {
      create: vi.fn(() => createPromise),
      adopt: vi.fn(async () => ({ ok: true, replay: '' }) as const),
      start: vi.fn(async () => ({ ok: true, replay: '' }) as const),
      input: vi.fn(() => {}),
      resize: vi.fn(() => {}),
      kill,
      drain: vi.fn(() => {}),
      onData: vi.fn(() => vi.fn(() => {})),
      onExit: vi.fn(() => vi.fn(() => {})),
      onNotice: vi.fn(() => vi.fn(() => {})),
    };
    const bridge = { terminal, config: { e2eSmoke: false } } as unknown as OkDesktopBridge;

    const { unmount } = render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(terminal.create).toHaveBeenCalledTimes(1));

    act(() => unmount());
    await act(async () => {
      resolveCreate({ ok: true, ptyId: 'pty-late' });
      await createPromise;
    });

    expect(kill).toHaveBeenCalledWith('pty-late');
    expect(terminal.onData).not.toHaveBeenCalled();
  });

  test('reaps a PTY that is mid-start when the panel unmounts', async () => {
    const { promise: adoptPromise, resolve: resolveAdopt } =
      Promise.withResolvers<OkPtyAdoptResult>();
    const { bridge, terminal } = makeBridge(
      { ok: true, ptyId: 'pty-1' },
      WIRED,
      () => adoptPromise,
    );

    const { unmount } = render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(terminal.start).toHaveBeenCalledWith('pty-1'));
    expect(terminal.kill).not.toHaveBeenCalled();

    act(() => unmount());
    await act(async () => {
      resolveAdopt({ ok: true, replay: '' });
      await adoptPromise;
    });

    expect(terminal.kill).toHaveBeenCalledWith('pty-1');
  });

  test('a claude launch probes readiness and shows a help affordance when claude is not on PATH', async () => {
    const { bridge, terminal, openExternal } = makeBridge(
      { ok: true, ptyId: 'pty-1' },
      { claude: 'not-found' },
    );
    render(<TerminalPanel bridge={bridge} launch={{ prompt: null, cli: 'claude', nonce: 1 }} />);

    await waitFor(() => expect(terminal.claudePreflight).toHaveBeenCalledTimes(1));
    expect(await screen.findByText(/isn't installed or on your PATH/)).toBeTruthy();

    fireEvent.click(screen.getByRole('button', { name: 'Get Claude Code' }));
    expect(openExternal).toHaveBeenCalledTimes(1);
    expect(openExternal.mock.calls[0]?.[0]).toContain('claude-code');
  });

  test.each(TERMINAL_CLI_IDS)(
    'a %s launch checks connection readiness and opens its setup dialog',
    async (cli) => {
      connectionSnapshot = terminalAgentSnapshot();
      const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' });
      render(
        <TooltipProvider>
          <TerminalPanel bridge={bridge} launch={{ prompt: null, cli, nonce: 1 }} />
        </TooltipProvider>,
      );

      expect(await screen.findByText(/aren't connected to it yet/)).toBeTruthy();
      fireEvent.click(screen.getByRole('button', { name: 'Connect tools' }));
      expect(screen.getByRole('dialog').textContent).toContain(
        'Choose what OpenKnowledge sets up for',
      );
      fireEvent.click(screen.getByRole('button', { name: 'Cancel' }));
      expect(screen.getByRole('button', { name: 'Connect tools' })).toBeTruthy();
    },
  );

  test.each(TERMINAL_CLI_IDS)(
    'restarts a running %s session after setup without disturbing a sibling',
    async (cli) => {
      connectionSnapshot = terminalAgentSnapshot();
      const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
      let created = 0;
      terminal.create.mockImplementation(async () => ({ ok: true, ptyId: `pty-${++created}` }));
      render(
        <TooltipProvider>
          <TerminalPanel bridge={bridge} launch={{ prompt: null, cli, nonce: 1 }} />
        </TooltipProvider>,
      );
      await screen.findByRole('button', { name: 'Connect tools' });
      const originalTerm = lastTerm;
      render(<TerminalPanel bridge={bridge} />);
      await waitFor(() => expect(terminal.create).toHaveBeenCalledTimes(2));
      const siblingTerm = lastTerm;

      const mcp = AGENT_REGISTRY[cli].satisfiers.find((satisfier) => satisfier.piece === 'mcp');
      if (mcp === undefined) throw new Error(`Missing MCP satisfier for ${cli}`);
      connectionSnapshot = terminalAgentSnapshot([cli]);
      applyConnections.mockResolvedValueOnce({
        ok: true,
        snapshot: connectionSnapshot,
        report: {
          actions: [
            {
              satisfierId: mcp.id,
              agentId: cli,
              piece: 'mcp',
              scope: mcp.scope,
              kind: mcp.kind,
              desired: 'present',
              action: 'written',
            },
          ],
          conflicts: [],
          withheld: [],
        },
      });
      fireEvent.click(screen.getByRole('button', { name: 'Connect tools' }));
      fireEvent.click(screen.getByRole('button', { name: 'Save changes' }));
      await waitFor(() => expect(screen.queryByRole('dialog')).toBeNull());
      expect(terminal.kill).not.toHaveBeenCalled();

      fireEvent.click(screen.getByRole('button', { name: 'Restart terminal' }));
      await waitFor(() => expect(terminal.create).toHaveBeenCalledTimes(3));
      expect(terminal.kill).toHaveBeenCalledExactlyOnceWith('pty-1');
      expect(terminal.kill.mock.invocationCallOrder[0]).toBeLessThan(
        terminal.create.mock.invocationCallOrder[2],
      );
      expect(originalTerm?.dispose).toHaveBeenCalledTimes(1);
      expect(siblingTerm?.dispose).not.toHaveBeenCalled();
      expect(terminal.create).toHaveBeenLastCalledWith(
        expect.objectContaining({
          launchCli: cli,
          launchCommand: expect.objectContaining({ executable: expect.any(String) }),
        }),
      );
      expect(
        cli === 'claude' ? terminal.claudePreflight : terminal.cliPreflight,
      ).toHaveBeenCalledTimes(2);
      await waitFor(() => expect(applyConnections).toHaveBeenCalledTimes(3));
      expect(screen.queryByTestId('terminal-readiness-banner')).toBeNull();
      expect(screen.queryByTestId('terminal-cli-missing-banner')).toBeNull();
      expect(screen.queryByTestId('terminal-restart-banner')).toBeNull();
    },
  );

  test('a claude launch shows no readiness banner when claude is present and OK tools are wired', async () => {
    connectionSnapshot = terminalAgentSnapshot(['claude']);
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' }, WIRED);
    render(<TerminalPanel bridge={bridge} launch={{ prompt: null, cli: 'claude', nonce: 1 }} />);

    await waitFor(() => expect(terminal.claudePreflight).toHaveBeenCalledTimes(1));
    await act(async () => {
      await Promise.resolve();
    });
    expect(screen.queryByTestId('terminal-readiness-banner')).toBeNull();
    expect(screen.queryByTestId('terminal-cli-missing-banner')).toBeNull();
  });

  test('the missing-CLI banner is dismissible', async () => {
    const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' }, { claude: 'not-found' });
    render(<TerminalPanel bridge={bridge} launch={{ prompt: null, cli: 'claude', nonce: 1 }} />);

    await screen.findByText(/isn't installed or on your PATH/);
    fireEvent.click(screen.getByRole('button', { name: 'Dismiss' }));
    await waitFor(() => expect(screen.queryByText(/isn't installed or on your PATH/)).toBeNull());
  });

  test('surfaces a restartable error state when create() rejects (startup failure, no silent dead-end)', async () => {
    let createCalls = 0;
    const { promise: createGate, resolve: resolveCreate } = Promise.withResolvers<void>();
    const terminal = {
      create: vi.fn(async () => {
        createCalls += 1;
        if (createCalls === 1) throw new Error('fork EMFILE');
        await createGate;
        return { ok: true, ptyId: 'pty-restarted' } as const;
      }),
      adopt: vi.fn(async () => ({ ok: true, replay: '' }) as const),
      start: vi.fn(async () => ({ ok: true, replay: '' }) as const),
      input: vi.fn(() => {}),
      resize: vi.fn(() => {}),
      kill: vi.fn(async () => {}),
      drain: vi.fn(() => {}),
      onData: vi.fn(() => vi.fn(() => {})),
      onExit: vi.fn(() => vi.fn(() => {})),
      onNotice: vi.fn(() => vi.fn(() => {})),
      claudePreflight: vi.fn(async () => WIRED),
      cliPreflight: vi.fn(async () => ({ onPath: 'present' as const })),
    };
    const bridge = {
      terminal,
      shell: { openExternal: vi.fn(async () => {}) },
      config: { e2eSmoke: false },
    } as unknown as OkDesktopBridge;

    render(<TerminalPanel bridge={bridge} />);

    expect(await screen.findByRole('alert')).toBeTruthy();
    expect(screen.getByText(/couldn't start/i)).toBeTruthy();
    expect(screen.queryByText(/stopped unexpectedly/i)).toBeNull();
    const restart = screen.getByRole('button', { name: 'Try again' });

    fireEvent.click(restart);
    await waitFor(() => expect(terminal.create).toHaveBeenCalledTimes(2));
    await act(async () => {
      resolveCreate();
      await Promise.resolve();
    });
    await waitFor(() => expect(screen.queryByRole('alert')).toBeNull());
  });

  test('renders a visible exit state with a restart affordance when the shell exits', async () => {
    const { bridge, terminal, pushExit } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(terminal.onExit).toHaveBeenCalledTimes(1));

    act(() => pushExit({ ptyId: 'pty-1', exitCode: 1, signal: null }));

    expect(screen.getByRole('alert')).toBeTruthy();
    expect(screen.getByText(/exit code 1/)).toBeTruthy();
    expect(screen.getByRole('button', { name: 'Restart terminal' })).toBeTruthy();
  });

  test('a throw anywhere in the mount sequence lands a restartable state, not a stuck spinner', async () => {
    const h = makeBridge({ ok: true, ptyId: 'pty-1' });
    h.terminal.onExit = vi.fn(() => {
      throw new Error('bridge channel closed');
    });
    render(<TerminalPanel bridge={h.bridge} />);

    await waitFor(() => expect(screen.getByRole('button', { name: 'Try again' })).toBeTruthy());
    expect(screen.getByText(/couldn't start/i)).toBeTruthy();
    expect(screen.getByText('bridge channel closed')).toBeTruthy();
    expect(screen.queryByTestId('terminal-starting-notice')).toBeNull();
  });

  test('a throw anywhere in the adopt mount sequence lands a restartable state, not a stuck spinner', async () => {
    const h = makeBridge({ ok: true, ptyId: 'unused' }, WIRED, async () => ({
      ok: true,
      replay: '',
    }));
    h.terminal.onExit = vi.fn(() => {
      throw new Error('bridge channel closed');
    });
    render(<TerminalPanel bridge={h.bridge} adoptPtyId="surv-1" />);

    await waitFor(() => expect(screen.getByRole('button', { name: 'Try again' })).toBeTruthy());
    expect(screen.getByText(/couldn't start/i)).toBeTruthy();
    expect(screen.getByText('bridge channel closed')).toBeTruthy();
    expect(screen.queryByTestId('terminal-starting-notice')).toBeNull();
  });

  test('a throw after the shell is live keeps the session running instead of reporting never-started', async () => {
    const h = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={h.bridge} />);
    lastTerm?.focus.mockImplementationOnce(() => {
      throw new Error('focus after start blew up');
    });

    await waitFor(() =>
      expect(document.querySelector('[data-terminal-status="running"]')).toBeTruthy(),
    );
    expect(screen.queryByText(/couldn't start/i)).toBeNull();
    expect(screen.queryByRole('button', { name: 'Try again' })).toBeNull();
  });

  test('a throw after the adopted shell is live keeps the session running instead of reporting never-started', async () => {
    let releaseAdopt: ((r: OkPtyAdoptResult) => void) | undefined;
    const h = makeBridge({ ok: true, ptyId: 'unused' }, WIRED, () => {
      const { promise, resolve } = Promise.withResolvers<OkPtyAdoptResult>();
      releaseAdopt = resolve;
      return promise;
    });
    render(<TerminalPanel bridge={h.bridge} adoptPtyId="surv-1" />);
    await waitFor(() => expect(h.terminal.adopt).toHaveBeenCalledWith('surv-1'));
    lastTerm?.write.mockImplementationOnce(() => {
      throw new Error('write after adopt blew up');
    });
    await act(async () => {
      releaseAdopt?.({ ok: true, replay: 'restored$ ' });
      await Promise.resolve();
    });

    await waitFor(() =>
      expect(document.querySelector('[data-terminal-status="running"]')).toBeTruthy(),
    );
    expect(screen.queryByText(/couldn't start/i)).toBeNull();
    expect(screen.queryByRole('button', { name: 'Try again' })).toBeNull();
  });

  test('a shell that failed to spawn reads as never-started, not as a crash', async () => {
    const { bridge, terminal, pushExit } = makeBridge({ ok: true, ptyId: 'pty-1' });
    const onExit = vi.fn();
    render(<TerminalPanel bridge={bridge} onExit={onExit} />);
    await waitFor(() => expect(terminal.onExit).toHaveBeenCalledTimes(1));

    act(() =>
      pushExit({
        ptyId: 'pty-1',
        error: 'posix_spawnp failed',
        neverStarted: true,
      }),
    );

    expect(screen.getByText(/couldn't start/i)).toBeTruthy();
    expect(screen.getByText('posix_spawnp failed')).toBeTruthy();
    expect(screen.queryByText(/stopped unexpectedly/i)).toBeNull();
    expect(screen.queryByText(/exit code/i)).toBeNull();
    expect(screen.getByRole('button', { name: 'Try again' })).toBeTruthy();
    expect(onExit).not.toHaveBeenCalled();
  });

  test('a host that dies before the shell spawns reads as localized copy, not a wire marker', async () => {
    const { bridge, terminal, pushExit } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(terminal.onExit).toHaveBeenCalledTimes(1));

    act(() => pushExit({ ptyId: 'pty-1', neverStarted: true, hostExited: true }));

    expect(screen.getByText(/couldn't start/i)).toBeTruthy();
    expect(
      screen.getByText(/background service stopped before the shell could start/i),
    ).toBeTruthy();
    expect(screen.queryByText(/terminal host exited/)).toBeNull();
    expect(screen.getByRole('button', { name: 'Try again' })).toBeTruthy();
  });

  test('a launch that could not be composed reads as localized copy, not a machine reason', async () => {
    const { bridge, terminal, pushExit } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(terminal.onExit).toHaveBeenCalledTimes(1));

    act(() => pushExit({ ptyId: 'pty-1', neverStarted: true, launchFailure: 'unsafe-argument' }));

    expect(screen.getByText(/couldn't start/i)).toBeTruthy();
    expect(screen.getByText(/can't run this command in the configured shell/i)).toBeTruthy();
    expect(screen.queryByText('unsafe-argument')).toBeNull();
    expect(screen.getByRole('button', { name: 'Try again' })).toBeTruthy();
  });

  test('a reaped start with no failure detail reads as bare start copy and nothing else', async () => {
    const { bridge, terminal, pushExit } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(terminal.onExit).toHaveBeenCalledTimes(1));

    act(() => pushExit({ ptyId: 'pty-1', neverStarted: true }));

    expect(screen.getByText(/couldn't start/i)).toBeTruthy();
    expect(screen.getByRole('alert').querySelectorAll('p')).toHaveLength(1);
    expect(screen.getByRole('button', { name: 'Try again' })).toBeTruthy();
    expect(screen.queryByRole('button', { name: 'Restart terminal' })).toBeNull();
    expect(screen.queryByText(/exit code/i)).toBeNull();
  });

  test('Restart spawns a fresh PTY in the same window and clears the exit state', async () => {
    const { bridge, terminal, pushExit } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(terminal.create).toHaveBeenCalledTimes(1));

    act(() => pushExit({ ptyId: 'pty-1', exitCode: 0, signal: null }));
    fireEvent.click(screen.getByRole('button', { name: 'Restart terminal' }));

    await waitFor(() => expect(terminal.create).toHaveBeenCalledTimes(2));
    await waitFor(() => expect(screen.queryByRole('alert')).toBeNull());
  });

  test('hides the missing-CLI banner once the shell has exited', async () => {
    const { bridge, pushExit } = makeBridge({ ok: true, ptyId: 'pty-1' }, { claude: 'not-found' });
    render(<TerminalPanel bridge={bridge} launch={{ prompt: null, cli: 'claude', nonce: 1 }} />);

    await screen.findByText(/isn't installed or on your PATH/);

    act(() => pushExit({ ptyId: 'pty-1', exitCode: 0, signal: null }));
    await waitFor(() => expect(screen.queryByText(/isn't installed or on your PATH/)).toBeNull());
    expect(screen.getByRole('alert')).toBeTruthy();
  });

  test('a plain tab (no launch intent) shows no claude-readiness banner even when claude is not on PATH', async () => {
    const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' }, { claude: 'not-found' });
    render(<TerminalPanel bridge={bridge} />);

    await waitFor(() =>
      expect(document.querySelector('[data-terminal-status="running"]')).toBeTruthy(),
    );
    await act(async () => {
      await Promise.resolve();
      await Promise.resolve();
    });
    expect(screen.queryByTestId('terminal-readiness-banner')).toBeNull();
    expect(screen.queryByTestId('terminal-cli-missing-banner')).toBeNull();
    expect(screen.queryByText(/isn't installed or on your PATH/)).toBeNull();
  });

  test('a plain tab (no launch intent) shows no MCP-rewire nudge either', async () => {
    const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' }, { claude: 'present' });
    render(<TerminalPanel bridge={bridge} />);

    await waitFor(() =>
      expect(document.querySelector('[data-terminal-status="running"]')).toBeTruthy(),
    );
    await act(async () => {
      await Promise.resolve();
      await Promise.resolve();
    });
    expect(screen.queryByTestId('terminal-readiness-banner')).toBeNull();
    expect(screen.queryByTestId('terminal-cli-missing-banner')).toBeNull();
    expect(screen.queryByText(/aren't connected to it yet/)).toBeNull();
  });

  test('a "run this command" tab shows no claude-readiness banner (no CLI is involved)', async () => {
    const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' }, { claude: 'not-found' });
    render(<TerminalPanel bridge={bridge} commandId="install-slidev" />);

    await waitFor(() =>
      expect(document.querySelector('[data-terminal-status="running"]')).toBeTruthy(),
    );
    await act(async () => {
      await Promise.resolve();
      await Promise.resolve();
    });
    expect(screen.queryByTestId('terminal-readiness-banner')).toBeNull();
    expect(screen.queryByTestId('terminal-cli-missing-banner')).toBeNull();
    expect(screen.queryByText(/isn't installed or on your PATH/)).toBeNull();
  });

  test('an adopted tab (reload survivor) shows no claude-readiness banner', async () => {
    const { bridge } = makeBridge({ ok: true, ptyId: 'pty-ignored' }, { claude: 'not-found' });
    render(<TerminalPanel bridge={bridge} adoptPtyId="surv-1" />);

    await waitFor(() =>
      expect(document.querySelector('[data-terminal-status="running"]')).toBeTruthy(),
    );
    await act(async () => {
      await Promise.resolve();
      await Promise.resolve();
    });
    expect(screen.queryByTestId('terminal-readiness-banner')).toBeNull();
    expect(screen.queryByTestId('terminal-cli-missing-banner')).toBeNull();
    expect(screen.queryByText(/isn't installed or on your PATH/)).toBeNull();
  });

  test('an adopted tab that still carries a stale claude launch intent shows no readiness banner', async () => {
    const { bridge } = makeBridge({ ok: true, ptyId: 'pty-ignored' }, { claude: 'not-found' });
    render(
      <TerminalPanel
        bridge={bridge}
        adoptPtyId="surv-1"
        launch={{ prompt: null, cli: 'claude', nonce: 1 }}
      />,
    );

    await waitFor(() =>
      expect(document.querySelector('[data-terminal-status="running"]')).toBeTruthy(),
    );
    await act(async () => {
      await Promise.resolve();
      await Promise.resolve();
    });
    expect(screen.queryByTestId('terminal-readiness-banner')).toBeNull();
    expect(screen.queryByTestId('terminal-cli-missing-banner')).toBeNull();
    expect(screen.queryByText(/isn't installed or on your PATH/)).toBeNull();
  });

  test('constructs xterm with the palette for the resolved app theme', async () => {
    mockResolvedTheme = 'light';
    const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' });
    render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(lastTerm).not.toBeNull());
    expect(lastTerm?.options.theme).toEqual(XTERM_LIGHT_THEME);

    cleanup();
    lastTerm = null;
    mockResolvedTheme = 'dark';
    const second = makeBridge({ ok: true, ptyId: 'pty-2' });
    render(<TerminalPanel bridge={second.bridge} />);
    await waitFor(() => expect(lastTerm).not.toBeNull());
    expect(lastTerm?.options.theme).toEqual(XTERM_DARK_THEME);
  });

  test('re-skins the live terminal on a theme switch without respawning the PTY', async () => {
    mockResolvedTheme = 'dark';
    const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' });
    const { rerender } = render(<TerminalPanel bridge={bridge} />);
    await waitFor(() => expect(terminal.create).toHaveBeenCalledTimes(1));

    const term = lastTerm;
    expect(term?.options.theme).toEqual(XTERM_DARK_THEME);

    mockResolvedTheme = 'light';
    rerender(<TerminalPanel bridge={bridge} />);

    await waitFor(() => expect(lastTerm?.options.theme).toEqual(XTERM_LIGHT_THEME));
    expect(lastTerm).toBe(term);
    expect(term?.dispose).not.toHaveBeenCalled();
    expect(terminal.create).toHaveBeenCalledTimes(1);
    expect(terminal.kill).not.toHaveBeenCalled();
  });

  test('restarting one session spawns a fresh PTY for it without disturbing a sibling', async () => {
    const exitSubs: Array<(m: OkPtyExit) => void> = [];
    let created = 0;
    const create = vi.fn(async () => {
      created += 1;
      return { ok: true as const, ptyId: `pty-${created}` };
    });
    const kill = vi.fn(async (_id: string) => {});
    const terminal = {
      create,
      adopt: vi.fn(async () => ({ ok: true, replay: '' }) as const),
      start: vi.fn(async () => ({ ok: true, replay: '' }) as const),
      input: vi.fn(() => {}),
      resize: vi.fn(() => {}),
      kill,
      drain: vi.fn(() => {}),
      onData: vi.fn(() => vi.fn(() => {})),
      onExit: vi.fn((cb: (m: OkPtyExit) => void) => {
        exitSubs.push(cb);
        return vi.fn(() => {});
      }),
      onNotice: vi.fn(() => vi.fn(() => {})),
      claudePreflight: vi.fn(async () => WIRED),
    };
    const bridge = {
      terminal,
      shell: { openExternal: vi.fn(async () => {}) },
      config: { e2eSmoke: false },
    } as unknown as OkDesktopBridge;
    const pushExit = (m: OkPtyExit) => {
      for (const f of exitSubs) f(m);
    };

    render(
      <>
        <TerminalPanel bridge={bridge} />
        <TerminalPanel bridge={bridge} />
      </>,
    );
    await waitFor(() => expect(create).toHaveBeenCalledTimes(2));

    act(() => pushExit({ ptyId: 'pty-1', exitCode: 1, signal: null }));
    expect(screen.getAllByRole('alert')).toHaveLength(1);

    fireEvent.click(screen.getByRole('button', { name: 'Restart terminal' }));
    await waitFor(() => expect(create).toHaveBeenCalledTimes(3));

    expect(kill).not.toHaveBeenCalledWith('pty-2');
    await waitFor(() => expect(screen.queryByRole('alert')).toBeNull());
  });

  describe('clickable links', () => {
    function provide(
      term: MockTerminal,
      bufferLine = 1,
    ): Promise<Array<{ activate: (e: MouseEvent, t: string) => void; text: string }>> {
      return new Promise((resolve) => {
        term.linkProvider?.provideLinks(bufferLine, (links) =>
          resolve(
            (links ?? []) as Array<{ activate: (e: MouseEvent, t: string) => void; text: string }>,
          ),
        );
      });
    }

    test('routes URL clicks (WebLinksAddon + OSC 8) through the bridge', async () => {
      const { bridge, openExternal } = makeBridge({ ok: true, ptyId: 'pty-1' });
      render(<TerminalPanel bridge={bridge} />);
      await waitFor(() => expect(lastTerm).not.toBeNull());

      expect(lastWebLinksHandler).not.toBeNull();
      lastWebLinksHandler?.({} as MouseEvent, 'https://example.com');
      expect(openExternal).toHaveBeenCalledWith('https://example.com');

      const linkHandler = lastTerm?.options.linkHandler as
        | { activate: (e: MouseEvent, uri: string) => void }
        | undefined;
      linkHandler?.activate({} as MouseEvent, 'https://osc8.example');
      expect(openExternal).toHaveBeenCalledWith('https://osc8.example');
    });

    test('registers a file-path link provider once the panel mounts', async () => {
      const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' });
      render(<TerminalPanel bridge={bridge} />);
      await waitFor(() => expect(lastTerm?.linkProvider).toBeTruthy());
    });

    test('clicking a markdown path navigates the editor to the doc', async () => {
      const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' });
      render(<TerminalPanel bridge={bridge} />);
      await waitFor(() => expect(lastTerm?.linkProvider).toBeTruthy());
      const term = lastTerm as MockTerminal;
      term.lineText = 'edited notes/a.md';

      const [link] = await provide(term);
      expect(link?.text).toBe('notes/a.md');
      window.location.hash = '';
      link?.activate({} as MouseEvent, link.text);
      expect(window.location.hash).toBe('#/notes/a');
    });

    test('stitches a path wrapped across buffer rows and navigates it', async () => {
      const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' });
      render(<TerminalPanel bridge={bridge} />);
      await waitFor(() => expect(lastTerm?.linkProvider).toBeTruthy());
      const term = lastTerm as MockTerminal;
      term.cols = 19;
      term.lineRows = ['see docs/guide/very', '-long.md'];

      const [link] = await provide(term);
      expect(link?.text).toBe('docs/guide/very-long.md');
      window.location.hash = '';
      link?.activate({} as MouseEvent, link.text);
      expect(window.location.hash).toBe('#/docs/guide/very-long');
    });

    test('reconstructs a wrapped path when its continuation row is hovered (backward walk)', async () => {
      const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' });
      render(<TerminalPanel bridge={bridge} />);
      await waitFor(() => expect(lastTerm?.linkProvider).toBeTruthy());
      const term = lastTerm as MockTerminal;
      term.cols = 19;
      term.lineRows = ['see docs/guide/very', '-long.md'];
      const [link] = await provide(term, 2);
      expect(link?.text).toBe('docs/guide/very-long.md');
      window.location.hash = '';
      link?.activate({} as MouseEvent, link.text);
      expect(window.location.hash).toBe('#/docs/guide/very-long');
    });

    test('clicking a trailing-slash folder navigates the editor to that folder', async () => {
      const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' });
      render(<TerminalPanel bridge={bridge} />);
      await waitFor(() => expect(lastTerm?.linkProvider).toBeTruthy());
      const term = lastTerm as MockTerminal;
      term.lineText = 'cd packages/app/';

      const [link] = await provide(term);
      expect(link?.text).toBe('packages/app');
      window.location.hash = '';
      link?.activate({} as MouseEvent, link.text);
      expect(window.location.hash).toBe('#/packages/app/');
    });

    test.each([
      { kind: 'markdown path', line: 'edited notes/a.md', text: 'notes/a.md', hash: '#/notes/a' },
      {
        kind: 'trailing-slash folder',
        line: 'cd packages/app/',
        text: 'packages/app',
        hash: '#/packages/app/',
      },
    ])(
      'clicking a $kind shows a hidden editor before navigating to it',
      async ({ line, text, hash }) => {
        const reveals: Array<PaneVisibilityRequest & { hashWhenAsked: string }> = [];
        paneVisibilityStore.subscribeRequests((request) => {
          reveals.push({ ...request, hashWhenAsked: window.location.hash });
        });
        paneVisibilityStore.publish({
          editor: { open: false, onScreen: false },
          agents: null,
          terminal: null,
        });
        const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' });
        render(<TerminalPanel bridge={bridge} />);
        await waitFor(() => expect(lastTerm?.linkProvider).toBeTruthy());
        const term = lastTerm as MockTerminal;
        term.lineText = line;

        const [link] = await provide(term);
        expect(link?.text).toBe(text);
        window.location.hash = '';
        link?.activate({} as MouseEvent, link.text);

        expect(reveals).toEqual([{ pane: 'editor', open: true, hashWhenAsked: '' }]);
        expect(window.location.hash).toBe(hash);
      },
    );

    test('a non-blocked openAsset failure surfaces silently — no reveal fallback', async () => {
      const { bridge, openAsset, revealAsset } = makeBridge({ ok: true, ptyId: 'pty-1' });
      render(<TerminalPanel bridge={bridge} />);
      await waitFor(() => expect(lastTerm?.linkProvider).toBeTruthy());
      const term = lastTerm as MockTerminal;
      term.lineText = 'wrote data/x.csv';

      const [link] = await provide(term);
      openAsset.mockResolvedValueOnce({ ok: false, reason: 'not-found' });
      link?.activate({} as MouseEvent, link.text);
      await waitFor(() => expect(openAsset).toHaveBeenCalledWith('data/x.csv'));
      expect(revealAsset).not.toHaveBeenCalled();
    });

    test('disposes the file-link provider on unmount', async () => {
      const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' });
      const { unmount } = render(<TerminalPanel bridge={bridge} />);
      await waitFor(() => expect(lastTerm?.linkProvider).toBeTruthy());
      const term = lastTerm as MockTerminal;
      unmount();
      expect(term.linkProviderDispose).toHaveBeenCalledTimes(1);
    });

    test('clicking a non-doc path OS-delegates via openAsset, revealing on block', async () => {
      const { bridge, openAsset, revealAsset } = makeBridge({ ok: true, ptyId: 'pty-1' });
      render(<TerminalPanel bridge={bridge} />);
      await waitFor(() => expect(lastTerm?.linkProvider).toBeTruthy());
      const term = lastTerm as MockTerminal;
      term.lineText = 'wrote data/x.csv';

      const [link] = await provide(term);
      expect(link?.text).toBe('data/x.csv');
      link?.activate({} as MouseEvent, link.text);
      await waitFor(() => expect(openAsset).toHaveBeenCalledWith('data/x.csv'));

      openAsset.mockResolvedValueOnce({ ok: false, reason: 'extension-blocked' });
      link?.activate({} as MouseEvent, link.text);
      await waitFor(() => expect(revealAsset).toHaveBeenCalledWith('data/x.csv'));

      openAsset.mockResolvedValueOnce({ ok: false, reason: 'not-a-file' });
      link?.activate({} as MouseEvent, link.text);
      await waitFor(() => expect(revealAsset).toHaveBeenCalledTimes(2));
    });

    test('clicking an out-of-project absolute path routes the reveal-external dialog', async () => {
      const { bridge, revealExternal } = makeBridge({ ok: true, ptyId: 'pty-1' });
      render(<TerminalPanel bridge={bridge} />);
      await waitFor(() => expect(lastTerm?.linkProvider).toBeTruthy());
      const term = lastTerm as MockTerminal;
      term.lineText = 'built /tmp/out/report.pdf';
      const [link] = await provide(term);
      expect(link?.text).toBe('/tmp/out/report.pdf');
      link?.activate({} as MouseEvent, link.text);
      await waitFor(() => expect(revealExternal).toHaveBeenCalledWith('/tmp/out/report.pdf'));
    });

    test('defers URL clicks to a mouse-tracking TUI (no double-open with claude)', async () => {
      const { bridge, openExternal } = makeBridge({ ok: true, ptyId: 'pty-1' });
      render(<TerminalPanel bridge={bridge} />);
      await waitFor(() => expect(lastTerm).not.toBeNull());
      (lastTerm as MockTerminal).modes.mouseTrackingMode = 'any';
      lastWebLinksHandler?.({} as MouseEvent, 'https://example.com');
      const osc8 = lastTerm?.options.linkHandler as {
        activate: (e: MouseEvent, u: string) => void;
      };
      osc8.activate({} as MouseEvent, 'https://example.com');
      expect(openExternal).not.toHaveBeenCalled();
    });

    test('still opens FILE clicks inside a mouse-tracking TUI (only URLs defer)', async () => {
      const { bridge, openAsset } = makeBridge({ ok: true, ptyId: 'pty-1' });
      render(<TerminalPanel bridge={bridge} />);
      await waitFor(() => expect(lastTerm?.linkProvider).toBeTruthy());
      const term = lastTerm as MockTerminal;
      term.lineText = 'wrote data/x.csv';
      const [link] = await provide(term);
      term.modes.mouseTrackingMode = 'any';
      link?.activate({} as MouseEvent, link.text);
      await waitFor(() => expect(openAsset).toHaveBeenCalledWith('data/x.csv'));
    });
  });
});