ompchamber 3.2.0 → 3.3.1

package/src/client/components/workspace/terminal-panel/index.tsx

@@ -1,10 +1,22 @@
-import { useCallback, useRef } from 'preact/hooks';
+import { useCallback, useRef, useState } from 'preact/hooks';
 import { useTerminal } from '@/client/hooks/workspace/terminal';
 import { useRepoList, useRepoScope } from '@/client/hooks/workspace/repo-scope';
 import { useTheme } from '@/client/hooks/ui/theme';
+import { useTouchDevice } from '@/client/hooks/ui/touch-device';
+import { useKeyboardInset } from '@/client/hooks/ui/keyboard-inset';
+import { copyToClipboard, readClipboardText } from '@/client/hooks/ui/clipboard';
 import { TerminalHeader } from '@/client/components/workspace/terminal-panel/Header';
 import { TerminalQuickActions } from '@/client/components/workspace/terminal-panel/QuickActions';
+import { TerminalKeyBar } from '@/client/components/workspace/terminal-panel/KeyBar';
 import { RealtimeXtermView, type RealtimeXtermHandle } from '@/client/components/workspace/terminal-panel/RealtimeXtermView';
+import {
+  NO_MODIFIERS,
+  applyModifiers,
+  resolveKeySequence,
+  type TerminalKeyId,
+  type TerminalModifier,
+  type TerminalModifiers,
+} from '@/shared/lib/workspace/terminal/keys';
 
 interface TerminalPanelProps {
   className?: string;
@@ -18,9 +30,22 @@ const encoder = new TextEncoder();
 export function TerminalPanel({ className = '', enabled = true, rootPath, showHeader = true }: TerminalPanelProps) {
   const xtermRef = useRef<RealtimeXtermHandle>(null);
   const { isDark } = useTheme();
+  // Only a device without a physical keyboard gets the key bar: on a desktop
+  // every one of those keys is already under the user's fingers, and a strip of
+  // them would cost the canvas height for nothing.
+  const isTouchDevice = useTouchDevice();
+  // The inset is measured from the panel's OWN bottom edge, so it can never
+  // double-count a keyboard the container already shrank for.
+  const rootRef = useRef<HTMLDivElement>(null);
+  const keyboardInset = useKeyboardInset(rootRef);
+  const [modifiers, setModifiers] = useState<TerminalModifiers>(NO_MODIFIERS);
   const { activeRepo, setActiveRepo } = useRepoScope(rootPath, 'terminal.activeRepo');
   const { repos, scanning: reposScanning, rescan: rescanRepos } = useRepoList(rootPath, enabled);
   const gridRef = useRef<{ cols: number; rows: number } | null>(null);
+  // The latch is read inside `handleInput`, which xterm calls outside React's
+  // render — a ref is what makes it the value at the keystroke, not at mount.
+  const modifiersRef = useRef(modifiers);
+  modifiersRef.current = modifiers;
 
   const handleOutput = useCallback((bytes: Uint8Array) => {
     xtermRef.current?.write(bytes);
@@ -70,10 +95,59 @@ export function TerminalPanel({ className = '', enabled = true, rootPath, showHe
 
   // Keystrokes arrive as text; `onBinary` payloads are latin-1 bytes and must
   // not be UTF-8 encoded on the way out.
+  //
+  // A latched modifier is folded in here, on the way out, because that is the
+  // only place a soft keyboard's letters pass through — Ctrl+C on a phone is a
+  // tap on `Ctrl` and then the `c` the OS keyboard produces.
   const handleInput = useCallback((data: string) => {
-    input(encoder.encode(data));
+    const latched = modifiersRef.current;
+    const armed = latched.ctrl || latched.alt;
+    const encoded = applyModifiers(data, latched);
+    // Only a single typed character consumes the latch. A paste, a mouse report
+    // or a focus event arrives on this same event and must leave the armed
+    // modifier alone, or the tap that armed it is silently spent on a no-op.
+    if (armed && data.length === 1) setModifiers(NO_MODIFIERS);
+    input(encoder.encode(encoded));
   }, [input]);
 
+  const handleToggleModifier = useCallback((modifier: TerminalModifier) => {
+    setModifiers((previous) => ({ ...previous, [modifier]: !previous[modifier] }));
+    xtermRef.current?.focus();
+  }, []);
+
+  const handleKey = useCallback((id: TerminalKeyId) => {
+    const sequence = resolveKeySequence(id, {
+      applicationCursorKeys: xtermRef.current?.applicationCursorKeys() ?? false,
+      modifiers: modifiersRef.current,
+    });
+    if (!sequence) return;
+    input(encoder.encode(sequence));
+    setModifiers(NO_MODIFIERS);
+    // Keep the OS keyboard where it was; a key bar tap must not dismiss it.
+    xtermRef.current?.focus();
+  }, [input]);
+
+  /**
+   * Cmd+C / Cmd+V, the two chords a terminal actually has — a phone can neither
+   * select on the canvas nor reach its own clipboard from there. Copy reports
+   * whether it had anything to copy so the bar can say "nothing selected"
+   * instead of flashing success over an untouched clipboard.
+   */
+  const handleCopy = useCallback(async () => {
+    const selection = xtermRef.current?.getSelection() ?? '';
+    if (!selection) return false;
+    return copyToClipboard(selection);
+  }, []);
+
+  const handlePaste = useCallback(async () => {
+    const text = await readClipboardText();
+    if (text === null || text.length === 0) return false;
+    // Through xterm's own paste, so a bracketed-paste shell gets its markers.
+    xtermRef.current?.paste(text);
+    xtermRef.current?.focus();
+    return true;
+  }, []);
+
   const handleBinaryInput = useCallback((data: string) => {
     const bytes = new Uint8Array(data.length);
     for (let i = 0; i < data.length; i += 1) bytes[i] = data.charCodeAt(i) & 0xff;
@@ -98,7 +172,17 @@ export function TerminalPanel({ className = '', enabled = true, rootPath, showHe
   }
 
   return (
-    <div className={`flex flex-col h-full w-full bg-paper text-ink overflow-hidden ${className}`}>
+    <div
+      ref={rootRef}
+      className={`flex flex-col h-full w-full bg-paper text-ink overflow-hidden ${className}`}
+      // The soft keyboard covers the bottom of the visual viewport without
+      // shrinking the layout one, so the key bar would sit behind the keys the
+      // user is typing on. Lifting by the panel's actual overlap with the
+      // visible area keeps the bar — and the shell's own grid, which the fit
+      // observer re-measures — above the keyboard, and lifts nothing at all
+      // when the container already ends above it.
+      style={keyboardInset > 0 ? { paddingBottom: keyboardInset } : undefined}
+    >
       {showHeader && (
         <TerminalHeader
           status={status}
@@ -135,6 +219,17 @@ export function TerminalPanel({ className = '', enabled = true, rootPath, showHe
           onGridChange={handleGridChange}
         />
       </div>
+
+      {isTouchDevice && (
+        <TerminalKeyBar
+          modifiers={modifiers}
+          onToggleModifier={handleToggleModifier}
+          onKey={handleKey}
+          onCopy={handleCopy}
+          onPaste={handlePaste}
+          disabled={status !== 'running'}
+        />
+      )}
     </div>
   );
 }

package/src/client/components/workspace/terminal-panel/mount.ts

@@ -34,6 +34,7 @@ import type { FitAddon } from '@xterm/addon-fit';
 import type { WebglAddon } from '@xterm/addon-webgl';
 import {
   getXtermTheme,
+  NERD_SYMBOLS_FAMILY,
   XTERM_FONT_FAMILY,
   safePatchFitAddon,
   safePatchRenderService,
@@ -127,6 +128,11 @@ export async function mountXterm(
   const fitAddon = new FitAddonClass() as FitAddon;
   term.loadAddon(fitAddon);
 
+  // The bundled Nerd Font symbols face may still be in flight (a phone has no
+  // Nerd Font of its own). See the helper for why the atlas has to be dropped
+  // once it lands.
+  const stopNerdFaceWatch = refreshAtlasWhenNerdFaceLoads(term);
+
   term.attachCustomKeyEventHandler((event: globalThis.KeyboardEvent) => handleKeyNavigation(term, event));
 
   const disposables = [
@@ -228,6 +234,7 @@ export async function mountXterm(
     dispose() {
       if (frame !== null) cancelAnimationFrame(frame);
       clearTimeout(fitTimer ?? undefined);
+      stopNerdFaceWatch();
       touch();
       for (const disposable of disposables) disposable.dispose();
       resizeObserver.disconnect();
@@ -241,6 +248,46 @@ export async function mountXterm(
   };
 }
 
+/**
+ * Re-rasterize the terminal once the bundled symbols face has loaded.
+ *
+ * xterm has no `document.fonts` listener: it rasterizes a glyph the first time
+ * it draws it and keeps the result in a texture atlas, so a PUA glyph written
+ * before the face arrived stays whatever the fallback painted — a tofu box —
+ * for the life of the buffer. The browser does re-lay-out DOM text when a face
+ * lands late (verified on the DOM renderer), but xterm's canvas does not get
+ * that for free.
+ *
+ * `loadingdone` naming our own family is exactly the signal that this machine
+ * had no Nerd Font of its own: the face is declared last in the stack and its
+ * `unicode-range` covers only PUA, so a device with an installed Nerd Font
+ * never fetches it (verified: zero requests with a local family present). That
+ * makes this a no-op on the developer's laptop and the fix on a phone.
+ *
+ * `clearTextureAtlas()` drops the atlas and forces a full refresh, which is
+ * what re-rasterizes the glyphs. It is a public API on `Terminal`, and the
+ * atlas is small enough that a full refresh is cheap — this runs at most once
+ * per page load.
+ *
+ * Returns a disposer.
+ */
+function refreshAtlasWhenNerdFaceLoads(term: Terminal): () => void {
+  if (typeof document === 'undefined' || !document.fonts) return () => {};
+
+  const onLoadingDone = (event: FontFaceSetLoadEvent) => {
+    const loaded = [...event.fontfaces].some((face) => face.family.replace(/['"]/g, '') === NERD_SYMBOLS_FAMILY);
+    if (!loaded) return;
+    try {
+      term.clearTextureAtlas();
+    } catch {
+      // A disposed terminal has no render service; nothing to refresh.
+    }
+  };
+
+  document.fonts.addEventListener('loadingdone', onLoadingDone);
+  return () => document.fonts.removeEventListener('loadingdone', onLoadingDone);
+}
+
 /** Shift+PageUp/Home/End scroll the viewport instead of reaching the shell. */
 function handleKeyNavigation(term: Terminal, event: globalThis.KeyboardEvent): boolean {
   if (event.type !== 'keydown' || !event.shiftKey) return true;

package/src/client/data/theme/terminal.ts

@@ -60,14 +60,21 @@ export function getXtermTheme(themeId: string) {
  * Material Design icons) that **no** coding webfont contains — `@fontsource/
  * fira-code`'s latin subset maps 226 codepoints and not one of them is above
  * U+FFFF — so without a face that supplies them the browser paints a hollow
- * tofu box for every prompt segment. The names below cover the Nerd Font
- * families a user is most likely to have installed (plus the *fontconfig*
- * symbol faces on Linux); a face that is absent is simply skipped by the
- * normal fallback chain, so listing many costs nothing.
+ * tofu box for every prompt segment.
  *
- * This is the same shape OpenChamber ships (`TERMINAL_GLYPH_FALLBACKS` in its
- * `ghostty/surface.ts`), which additionally bundles `SymbolsNerdFontMono` as a
- * webfont so the coverage never depends on the machine.
+ * The entries before the last one name the Nerd Font families a user is most
+ * likely to have installed (plus the *fontconfig* symbol faces on Linux); a
+ * face that is absent is simply skipped by the normal fallback chain, so
+ * listing many costs nothing.
+ *
+ * `'OMPChamber Nerd Symbols'` is the one the chamber bundles itself
+ * (`src/shared/lib/fonts/nerd-symbols.css`), and it is deliberately LAST: a
+ * machine that already has a Nerd Font renders from it and never fetches these
+ * bytes, while a phone — which has none — falls through to it instead of
+ * painting tofu. Verified: with the bundled face last and a local Nerd Font
+ * ahead of it, laying out a PUA glyph issued zero font requests; with no local
+ * family present, the face is fetched and all of the prompt's codepoints
+ * render.
  *
  * Only glyphs the text face lacks reach these entries, so Latin metrics are
  * untouched — verified: `A`/`m`/`W` keep identical advance and ink.
@@ -78,7 +85,17 @@ export const XTERM_GLYPH_FALLBACKS =
   "'MesloLGM Nerd Font', 'CaskaydiaCove Nerd Font', 'SauceCodePro Nerd Font', " +
   "'Symbols Nerd Font Mono', 'Symbols Nerd Font', 'PowerlineSymbols'";
 
-export const XTERM_FONT_FAMILY = `'Fira Code', ${XTERM_GLYPH_FALLBACKS}, Menlo, Monaco, 'Courier New', monospace`;
+/**
+ * The bundled symbols face, kept separate so `mount.ts` can await it by name.
+ *
+ * It must stay last in the stack (see above) and its family name must match the
+ * `@font-face` in `nerd-symbols.css` — the two are one contract, which is why
+ * the name is a constant rather than a literal in each file.
+ */
+export const NERD_SYMBOLS_FAMILY = 'OMPChamber Nerd Symbols';
+
+export const XTERM_FONT_FAMILY =
+  `'Fira Code', ${XTERM_GLYPH_FALLBACKS}, '${NERD_SYMBOLS_FAMILY}', Menlo, Monaco, 'Courier New', monospace`;
 
 /** xterm's private render service, read only to size-check before fitting. */
 export interface XtermCore {

package/src/client/hooks/editor/font.ts

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The editor font setting, and how a live change reaches an open editor.
+ *
+ * The setting is visual, so it has to apply to the editor the user is looking
+ * at — not on the next reload. That rules out reading it once from the
+ * bootstrap payload the way `keybindingSend` is read: `appSettings` is a prop
+ * captured at boot, so a settings change would not reach an already-mounted
+ * editor. The theme solved the same problem with a window event, and this
+ * follows it: the picker writes the setting AND announces it, and the editor
+ * subscribes.
+ *
+ * The stored value is the family name. `editorFontStack` puts it in front of
+ * the shared stack, so a face the device lacks falls through to the bundled
+ * Fira Code instead of replacing it — which is why the picker can offer faces
+ * the app does not ship.
+ */
+
+import { useEffect, useState } from 'preact/hooks';
+import { readChamberSetting } from '@/shared/lib/settings/client';
+import {
+  EDITOR_DEFAULT_FONT_FAMILY,
+  editorFontStack,
+} from '@/shared/lib/code/editor/typography';
+
+/** Broadcast on every editor-font write. Detail is the new family name. */
+export const EDITOR_FONT_CHANGED_EVENT = 'omp:editor-font-changed';
+
+/** The family currently stored, falling back to the shipped default. */
+export function currentEditorFont(): string {
+  if (typeof window === 'undefined') return EDITOR_DEFAULT_FONT_FAMILY;
+  return readChamberSetting<string>('editorFont') ?? EDITOR_DEFAULT_FONT_FAMILY;
+}
+
+/** The stored family and the stack it resolves to, kept in step with writes. */
+export function useEditorFontStack(): string {
+  const [family, setFamily] = useState<string>(currentEditorFont);
+
+  useEffect(() => {
+    const onChange = (event: Event) => {
+      const detail = (event as CustomEvent<string>).detail;
+      setFamily(detail || currentEditorFont());
+    };
+    window.addEventListener(EDITOR_FONT_CHANGED_EVENT, onChange);
+    return () => window.removeEventListener(EDITOR_FONT_CHANGED_EVENT, onChange);
+  }, []);
+
+  return editorFontStack(family);
+}

package/src/client/hooks/ui/clipboard.ts

@@ -31,3 +31,20 @@ export async function copyToClipboard(text: string): Promise<boolean> {
     return false;
   }
 }
+
+/**
+ * Read text from the clipboard, or null when the browser refused.
+ *
+ * There is no fallback, and there cannot be one: `execCommand('paste')` is
+ * blocked by every browser and `navigator.clipboard.readText` needs a secure
+ * context plus a permission the user grants once — so a denial is reported
+ * rather than papered over with an empty paste.
+ */
+export async function readClipboardText(): Promise<string | null> {
+  try {
+    if (!navigator.clipboard || !window.isSecureContext) return null;
+    return await navigator.clipboard.readText();
+  } catch {
+    return null;
+  }
+}

package/src/client/hooks/ui/keyboard-inset.test.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The keyboard-inset arithmetic.
+ *
+ * The failure this file exists for is an OVER-lift: computing the keyboard's
+ * height from `innerHeight - visualHeight` and applying it to a panel that does
+ * not reach the screen's bottom edge (a drawer with safe-area padding, a
+ * container a browser already shrank) lifts by the keyboard's height PLUS the
+ * gap the panel never had. Deriving the lift from the panel's own overlap makes
+ * every one of those cases zero.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { resolveKeyboardInset } from '@/client/hooks/ui/keyboard-inset';
+
+describe('resolveKeyboardInset', () => {
+  test('a panel that clears the visible bottom is not lifted', () => {
+    // Keyboard open, panel already above it: nothing to do.
+    expect(resolveKeyboardInset(500, 508)).toBe(0);
+    expect(resolveKeyboardInset(508, 508)).toBe(0);
+  });
+
+  test('a collapsed URL bar is not a keyboard', () => {
+    expect(resolveKeyboardInset(844, 780)).toBe(0);
+    expect(resolveKeyboardInset(844, 765)).toBe(0);
+  });
+
+  test('the lift is the overlap, not the keyboard height', () => {
+    // Panel bottom at 844, visible bottom at 508 -> 336px covered.
+    expect(resolveKeyboardInset(844, 508)).toBe(336);
+    // The same keyboard over a panel that ends 20px higher lifts 20px less,
+    // which is exactly the over-lift the height-difference form produced.
+    expect(resolveKeyboardInset(824, 508)).toBe(316);
+    expect(resolveKeyboardInset(508, 508)).toBe(0);
+  });
+
+  test('a nonsense visible bottom lifts nothing', () => {
+    expect(resolveKeyboardInset(844, 0)).toBe(0);
+    expect(resolveKeyboardInset(844, -100)).toBe(0);
+  });
+});

package/src/client/hooks/ui/keyboard-inset.ts

@@ -0,0 +1,113 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * How far a bottom-anchored panel must lift so a soft keyboard does not cover
+ * it.
+ *
+ * The measurement is taken from the PANEL'S OWN geometry, not from
+ * `window.innerHeight`: the overlap between the panel's bottom edge and the
+ * visible bottom edge is what actually matters, and it is self-correcting.
+ *
+ * The difference matters because `innerHeight` is not a stable reference. A
+ * browser that shrinks it when the keyboard opens, a `dvh` container that
+ * tracks it, or a panel that already ends above the keyboard all change what
+ * "the keyboard height" means — and computing `innerHeight - visualHeight`
+ * against a height that already moved lifts the panel by the keyboard's height
+ * a second time, which is the too-far margin. Deriving the lift from the
+ * overlap yields zero in every one of those cases and the exact height only
+ * when the panel genuinely runs under the keyboard.
+ *
+ * Deliberately local to the panel that uses it. Putting
+ * `interactive-widget=resizes-content` in the viewport meta would solve this
+ * globally, but it changes how every surface in the app sizes itself when the
+ * keyboard opens — a whole-app layout decision, not a terminal one.
+ */
+
+import { useEffect, useState } from 'preact/hooks';
+
+/** Ignore small overlaps: a collapsing URL bar is not a keyboard. */
+const MIN_KEYBOARD_INSET_PX = 80;
+
+/** The element shape the hook needs; keeps the signature free of a Preact import. */
+export interface PanelRef {
+  readonly current: HTMLElement | null;
+}
+
+/**
+ * The lift for one measurement pair, in CSS px.
+ *
+ * `panelBottom` is the panel's bottom edge and `visibleBottom` the visible
+ * area's bottom edge, both in the same coordinate space. Pure so the cases
+ * below can be pinned without a DOM.
+ */
+export function resolveKeyboardInset(panelBottom: number, visibleBottom: number): number {
+  // A non-positive visible bottom is a browser reporting nonsense; lifting by
+  // it would squeeze the panel to nothing, so the failure mode is "no keyboard".
+  if (visibleBottom <= 0) return 0;
+  const overlap = panelBottom - visibleBottom;
+  if (overlap < MIN_KEYBOARD_INSET_PX) return 0;
+  return Math.round(overlap);
+}
+
+export function useKeyboardInset(ref: PanelRef): number {
+  const [inset, setInset] = useState(0);
+
+  useEffect(() => {
+    const element = ref.current;
+    if (!element) return;
+
+    let frame: number | null = null;
+    const measure = () => {
+      frame = null;
+      const viewport = window.visualViewport;
+      if (!viewport) {
+        setInset((previous) => (previous === 0 ? previous : 0));
+        return;
+      }
+      // `offsetTop` + `height` is the visible area's bottom edge within the
+      // layout viewport, which is the space `getBoundingClientRect` reports in.
+      const next = resolveKeyboardInset(
+        element.getBoundingClientRect().bottom,
+        viewport.offsetTop + viewport.height,
+      );
+      setInset((previous) => (previous === next ? previous : next));
+    };
+
+    // Deferred by a frame: `visualViewport.resize` fires BEFORE the container
+    // reflows for the keyboard, so measuring in the handler reads the old, full
+    // height and lifts by the keyboard twice over. One frame later the layout
+    // has settled and the panel's own bottom edge is the truth.
+    const schedule = () => {
+      if (frame !== null) return;
+      frame = requestAnimationFrame(measure);
+    };
+
+    // The container can also shrink with no viewport event at all (a `dvh`
+    // wrapper tracking the keyboard, a drawer resized by the layout). Watching
+    // the panel's BORDER box catches that without a feedback loop: our own
+    // padding changes the content box only.
+    const observer = new ResizeObserver(schedule);
+    observer.observe(element, { box: 'border-box' });
+
+    const viewport = window.visualViewport;
+    viewport?.addEventListener('resize', schedule);
+    viewport?.addEventListener('scroll', schedule);
+    window.addEventListener('resize', schedule);
+    window.addEventListener('orientationchange', schedule);
+    schedule();
+
+    return () => {
+      if (frame !== null) cancelAnimationFrame(frame);
+      observer.disconnect();
+      viewport?.removeEventListener('resize', schedule);
+      viewport?.removeEventListener('scroll', schedule);
+      window.removeEventListener('resize', schedule);
+      window.removeEventListener('orientationchange', schedule);
+    };
+  }, [ref]);
+
+  return inset;
+}

package/src/client/hooks/ui/text-overflow.test.ts

@@ -0,0 +1,152 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Truncation measurement contract. The bug this hook replaces was a character
+ * count standing in for a width: 76 characters fit a desktop timeline and were
+ * clipped on a 340px phone card, so the notice rendered an ellipsis and shipped
+ * a disabled button — the chevron was dropped with it, and the tap did nothing.
+ *
+ * happy-dom does no layout, so `scrollWidth`/`clientWidth` are faked on the
+ * element exactly as the scroll tests fake container geometry.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import type { h as PreactH, render as PreactRender } from 'preact';
+import type { act as PreactAct } from 'preact/test-utils';
+import type { RefObject } from 'preact';
+import type { useIsTruncated as UseIsTruncated } from '@/client/hooks/ui/text-overflow';
+
+let useIsTruncated: typeof UseIsTruncated;
+let h: typeof PreactH;
+let render: typeof PreactRender;
+let act: typeof PreactAct;
+
+let win: Window;
+
+/** Box the hook measures. `clientWidth` is faked, so no layout is needed. */
+class StubResizeObserver {
+  static latest: StubResizeObserver | null = null;
+  constructor(private readonly callback: () => void) {
+    StubResizeObserver.latest = this;
+  }
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+  fire() { this.callback(); }
+}
+
+function installBox(el: HTMLElement, scrollWidth: number, clientWidth: number) {
+  Object.defineProperty(el, 'scrollWidth', { get: () => scrollWidth, configurable: true });
+  Object.defineProperty(el, 'clientWidth', { get: () => clientWidth, configurable: true });
+}
+
+interface ProbeProps {
+  content: string;
+  seen: { current: boolean | null };
+  /** Not named `ref`: Preact strips that key from props. */
+  targetRef: RefObject<HTMLSpanElement | null>;
+  /** When false the truncated row is not rendered — the expanded state. */
+  show?: boolean;
+}
+
+function Probe(props: ProbeProps) {
+  props.seen.current = useIsTruncated(props.targetRef, props.content);
+  if (props.show === false) return h('span', null, 'expanded body');
+  return h('span', { ref: props.targetRef, className: 'truncate' }, props.content);
+}
+
+async function mount(content: string): Promise<{
+  seen: { current: boolean | null };
+  ref: RefObject<HTMLSpanElement | null>;
+  node: HTMLDivElement;
+  el: HTMLSpanElement;
+}> {
+  const seen: { current: boolean | null } = { current: null };
+  const ref: RefObject<HTMLSpanElement | null> = { current: null };
+  const node = document.createElement('div');
+  document.body.appendChild(node);
+  await act(async () => { render(h(Probe, { content, seen, targetRef: ref }), node); });
+  return { seen, ref, node, el: ref.current! };
+}
+
+beforeAll(async () => {
+  win = new Window({ url: 'http://localhost' });
+  for (const key of ['window', 'document', 'navigator', 'Node', 'Element', 'HTMLElement', 'Event', 'ResizeObserver'] as const) {
+    (globalThis as Record<string, unknown>)[key] = (win as unknown as Record<string, unknown>)[key];
+  }
+  (globalThis as Record<string, unknown>).ResizeObserver = StubResizeObserver;
+  // Static imports cannot work here: Preact binds its environment at module
+  // evaluation time, so the modules below must load after those DOM globals.
+  ({ useIsTruncated } = await import('@/client/hooks/ui/text-overflow'));
+  ({ h, render } = await import('preact'));
+  ({ act } = await import('preact/test-utils'));
+});
+
+afterAll(() => {
+  for (const key of ['window', 'document', 'navigator', 'Node', 'Element', 'HTMLElement', 'Event', 'ResizeObserver']) {
+    delete (globalThis as Record<string, unknown>)[key];
+  }
+});
+
+describe('useIsTruncated', () => {
+  test('reports a clipped line even when it is short', async () => {
+    // The regression: 76 characters, clipped on a phone card. A character
+    // threshold called this "fits" and the expander was never offered.
+    const probe = await mount('Multi-step reasoning: think carefully through the problem before responding.');
+    installBox(probe.el, 480, 254);
+    await act(async () => { StubResizeObserver.latest!.fire(); });
+
+    expect(probe.seen.current).toBe(true);
+    render(null, probe.node);
+    probe.node.remove();
+  });
+
+  test('reports a fitting line as not truncated', async () => {
+    const probe = await mount('Late LSP diagnostics arrived after the edit returned:');
+    installBox(probe.el, 335, 335);
+    await act(async () => { StubResizeObserver.latest!.fire(); });
+
+    expect(probe.seen.current).toBe(false);
+    render(null, probe.node);
+    probe.node.remove();
+  });
+
+  test('keeps the last answer when the element has no layout to measure', async () => {
+    // An unmeasured element reports 0 for both values, which is not "fits" —
+    // treating it as one would retract the expander mid-interaction.
+    const probe = await mount('clipped');
+    installBox(probe.el, 500, 200);
+    await act(async () => { StubResizeObserver.latest!.fire(); });
+    expect(probe.seen.current).toBe(true);
+
+    installBox(probe.el, 0, 0);
+    await act(async () => { StubResizeObserver.latest!.fire(); });
+    expect(probe.seen.current).toBe(true);
+
+    render(null, probe.node);
+    probe.node.remove();
+  });
+
+  test('keeps its answer when the truncated row is replaced by the expanded body', async () => {
+    // Expanding swaps the truncated row out for the body, so the ref detaches
+    // while the answer is still the reason the expander is on screen. A reset
+    // there would collapse the card the user just opened.
+    const probe = await mount('clipped');
+    installBox(probe.el, 500, 200);
+    await act(async () => { StubResizeObserver.latest!.fire(); });
+    expect(probe.seen.current).toBe(true);
+
+    // Detached AND with new content, so the effect re-runs against a null ref.
+    await act(async () => {
+      render(h(Probe, { content: 'clipped and expanded', seen: probe.seen, targetRef: probe.ref, show: false }), probe.node);
+    });
+    expect(probe.seen.current).toBe(true);
+
+    render(null, probe.node);
+    probe.node.remove();
+  });
+});