ompchamber 3.1.1 → 3.3.0

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/chat/omp/session-list.tsx

@@ -32,6 +32,16 @@ export interface SidebarDataHandle {
   initializing: boolean;
   /** Fire a refresh (dedup: while a load is in flight this is a no-op). */
   refresh: () => void;
+  /**
+   * User-initiated refresh: the same load as `refresh`, but it also raises
+   * `refreshing` until THAT load settles, so a toolbar button can spin while
+   * it runs. The background paths (idle poll, stream events, status ack) go
+   * through `refresh` and deliberately never raise the flag — a spinner that
+   * turns on by itself every 30s reads as a broken list.
+   */
+  refreshNow: () => void;
+  /** True while a `refreshNow` load is in flight. */
+  refreshing: boolean;
   /**
    * Mark a session's one-shot terminal badge as seen NOW: strips the check
    * optimistically for this mount and POSTs the server ack. No-op unless the
@@ -74,6 +84,22 @@ export function SidebarDataProvider({ children, initialFolders = [] }: { childre
     };
   }, [fetcher]);
 
+  // User-initiated refresh. Unlike `refresh` it does NOT skip an in-flight
+  // load — a click is an explicit "read it again now", and the fetcher aborts
+  // the superseded request rather than letting two answer. The spinner follows
+  // THIS load only: a token marks the newest click, so a background poll
+  // settling in between cannot stop a spin that is still running, and a
+  // superseded click cannot stop the newer one's.
+  const [refreshing, setRefreshing] = useState(false);
+  const refreshTokenRef = useRef(0);
+  const refreshNow = useCallback(() => {
+    const token = ++refreshTokenRef.current;
+    setRefreshing(true);
+    void fetcher.load('/api/sessions/list').finally(() => {
+      if (refreshTokenRef.current === token) setRefreshing(false);
+    });
+  }, [fetcher]);
+
   // Idle keep-alive: the throttled stream-event hook and useStreamPoll only
   // fire while THIS client streams, so changes made elsewhere (another tab,
   // a background omp process finishing, an archive from a second browser)
@@ -142,10 +168,12 @@ export function SidebarDataProvider({ children, initialFolders = [] }: { childre
       isMock: data?.isMock ?? false,
       initializing: !hasLoaded,
       refresh,
+      refreshNow,
+      refreshing,
       markSeen,
       hasSeen: (id) => seen.has(String(id)),
     };
-  }, [fetcher.data, initialFolders, hasLoaded, refresh, markSeen]);
+  }, [fetcher.data, initialFolders, hasLoaded, refresh, refreshNow, refreshing, markSeen]);
 
   return <SidebarDataContext.Provider value={value}>{children}</SidebarDataContext.Provider>;
 }
@@ -163,6 +191,8 @@ export function useSidebarData(): SidebarDataHandle {
     isMock: false,
     initializing: true,
     refresh: () => {},
+    refreshNow: () => {},
+    refreshing: false,
     markSeen: () => {},
     hasSeen: () => false,
   };

package/src/client/hooks/chat/omp/session-sidebar-controller.ts

@@ -51,6 +51,10 @@ export interface SessionSidebarController {
   folders: WorkspaceFolderData[];
   initializing: boolean;
   refresh: () => void;
+  /** User-initiated refresh — raises `refreshing` until that load settles. */
+  refreshNow: () => void;
+  /** True while a `refreshNow` load is in flight (drives the toolbar spinner). */
+  refreshing: boolean;
   activeSessionId: number | string | null;
   sessionParam: string | null;
   searchQuery: string;
@@ -71,7 +75,7 @@ export function useSessionSidebarController(
   options: SessionSidebarControllerOptions = {},
 ): SessionSidebarController {
   const { includePendingSessions = false, onSelectSession, onAfterSelect } = options;
-  const { folders, initializing, refresh, markSeen, hasSeen } = useSidebarData();
+  const { folders, initializing, refresh, refreshNow, refreshing, markSeen, hasSeen } = useSidebarData();
   const [searchParams, setSearchParams] = useSearchParams();
   const sessionParam = searchParams.get('sessionId');
   const activeSessionId = sessionParam
@@ -232,6 +236,8 @@ export function useSessionSidebarController(
     folders,
     initializing,
     refresh: revalidate,
+    refreshNow,
+    refreshing,
     activeSessionId,
     sessionParam,
     searchQuery,

package/src/client/hooks/chat/subagent/index.ts

@@ -2,7 +2,7 @@
 import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
 import type { ChatMessageData, SubagentInfo } from '@/shared/types';
 import { isRecord } from '@/shared/lib/util/guards';
-import { parseSubagentLifecycle, parseSubagentProgress } from '@/shared/lib/omp/subagent/parse';
+import { parseSubagentLifecycle, readSubagentProgressFrame } from '@/shared/lib/omp/subagent/parse';
 import { convertMessages, mergeMessages, requestHistoryPage, requestSubagentPage } from '@/shared/lib/omp/subagent/transcript-client';
 
 /**
@@ -86,6 +86,9 @@ export function useSubagentTranscript(
   const nextByteRef = useRef(0);
   const sessionFileRef = useRef<string | undefined>(undefined);
   const readyRef = useRef(false);
+  /** False once the live RPC has refused this subagent (its process is gone).
+   *  Later tail fetches then read the on-disk transcript directly. */
+  const rpcAvailableRef = useRef(true);
   const flushingRef = useRef(false);
   const queuedRef = useRef(false);
   const flushTimerRef = useRef<number | null>(null);
@@ -103,8 +106,25 @@ export function useSubagentTranscript(
     flushingRef.current = true;
     const generation = generationRef.current;
     try {
-      const page = await requestSubagentPage(sid, active.id, sessionFileRef.current, nextByteRef.current);
-      if (generation !== generationRef.current || !page) return;
+      const fromByte = nextByteRef.current;
+      // Once the RPC has answered "not managed", stop probing it: the child is
+      // gone for the rest of this view's life, and every later tail would pay a
+      // refused round-trip before falling back anyway. The disk path below is
+      // the same transcript file the RPC was reading.
+      let page = rpcAvailableRef.current
+        ? await requestSubagentPage(sid, active.id, sessionFileRef.current, fromByte)
+        : null;
+      if (generation !== generationRef.current) return;
+      if (!page) {
+        // The session's omp process is gone (the child finished, the idle
+        // reclaim took it, or the chamber restarted) — the RPC is refused for
+        // an unmanaged session rather than respawning one for a read. Continue
+        // on disk; without this the view froze on whatever the last live page
+        // held, which is exactly the final turns of a just-finished subagent.
+        rpcAvailableRef.current = false;
+        page = await requestHistoryPage(sid, active.id, fromByte);
+        if (generation !== generationRef.current || !page) return;
+      }
       sessionFileRef.current = page.sessionFile || sessionFileRef.current;
       const converted = convertMessages(page.messages, true);
       if (page.reset) {
@@ -163,6 +183,7 @@ export function useSubagentTranscript(
     nextByteRef.current = 0;
     sessionFileRef.current = initial?.sessionFile;
     readyRef.current = false;
+    rpcAvailableRef.current = true;
 
     const scheduleTail = () => {
       if (flushTimerRef.current !== null) return;
@@ -188,8 +209,10 @@ export function useSubagentTranscript(
         if (!isCurrent()) return;
         if (!result && !viaHistory && fromByte === 0) {
           // The parent RPC dropped this subagent (already finished) — the
-          // on-disk transcript is authoritative from here on.
+          // on-disk transcript is authoritative from here on, and the tail
+          // fetch must not keep probing a refused RPC.
           viaHistory = true;
+          rpcAvailableRef.current = false;
           result = await requestHistoryPage(sessionId, subagentId, 0);
           if (!isCurrent()) return;
         }
@@ -236,15 +259,18 @@ export function useSubagentTranscript(
       if (!detail) return;
       const payload = isRecord(detail.payload) ? detail.payload : null;
       if (!payload) return;
-      const payloadId = typeof payload.id === 'string' ? payload.id : null;
-      if (payloadId && payloadId !== subagentId) return;
-      if (!payloadId) {
-        const payloadIndex = typeof payload.index === 'number' ? payload.index : null;
+      // `subagent_progress` nests the child's AgentProgress under `progress`
+      // (SubagentProgressPayload), and only the NESTED snapshot carries the id
+      // plus the resolved model/thinking level — reading the wrapper alone
+      // dropped every field it reports.
+      const progress = readSubagentProgressFrame(payload);
+      if (!progress) return;
+      if (progress.id !== undefined) {
+        if (progress.id !== subagentId) return;
+      } else {
         // Index is only unique within a spawning batch — require the exact match.
-        if (payloadIndex === null || payloadIndex !== (subagentRef.current?.index ?? -1)) return;
+        if (progress.index === undefined || progress.index !== (subagentRef.current?.index ?? -1)) return;
       }
-      const progress = parseSubagentProgress(payload);
-      if (!progress) return;
       setStatus(prev => {
         if (!prev || prev.id !== subagentId) return prev;
         const next: SubagentInfo = { ...prev, progress: { ...prev.progress, ...progress } };

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/editor/use-file-editor.ts

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
-import { getLanguageFromPath } from '@/shared/lib/code/syntax-highlight';
+import { getLanguageFromPath } from '@/shared/lib/code/language';
 import { getImageMimeType } from '@/shared/lib/fs/file-kind';
 import { buildFsRawUrl } from '@/shared/lib/fs/paths';
 import { detectLineEnding, toDiskText, toLf, type LineEnding } from '@/shared/lib/code/line-endings';

package/src/client/hooks/settings/master-detail.ts

@@ -0,0 +1,33 @@
+import { useCallback, useState } from 'preact/hooks';
+
+/** Which of a two-pane settings category's screens a phone is showing. */
+export type SettingsPane = 'list' | 'detail';
+
+export interface SettingsMasterDetailHandle {
+  pane: SettingsPane;
+  /** Called by the category's own row handler, never derived from selection. */
+  openDetail: () => void;
+  back: () => void;
+}
+
+/**
+ * Pane state for the settings categories that are two panes on a desktop.
+ *
+ * A phone has no room for a 224px list beside a detail pane: measured on a
+ * 412x915 Android viewport, the detail was left 186px wide, and the categories
+ * whose container stacked gave it 48px of height. Below `md` the two panes are
+ * therefore two screens, and this is which one is up.
+ *
+ * The pane is opened by an EXPLICIT row choice, never by a selection that
+ * merely exists: `useCrudList` selects its first row on load and the provider
+ * list falls back to `connectedProviders[0]`, so deriving the pane from
+ * `selectedId` would drop the user into a detail pane they never asked for and
+ * hide the list they came to browse. Desktop ignores this state entirely —
+ * `md:` shows both panes.
+ */
+export function useSettingsMasterDetail(): SettingsMasterDetailHandle {
+  const [pane, setPane] = useState<SettingsPane>('list');
+  const openDetail = useCallback(() => setPane('detail'), []);
+  const back = useCallback(() => setPane('list'), []);
+  return { pane, openDetail, back };
+}

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;
+}