ompchamber 2.0.2 → 3.1.0

package/src/client/hooks/workspace/file-tree-actions.ts

@@ -0,0 +1,250 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Everything a file-tree row does that is not rendering: the context menu's
+ * action dispatch, the create/rename/delete dialogs and their server calls.
+ *
+ * Extracted from the row component because it is a stateful cluster with one
+ * shared dependency (`/api/fs/action` and the fetcher that submits to it), and
+ * because the row is at the repository's line ceiling. The component keeps the
+ * markup and the handlers that need its own DOM node; this keeps the behavior.
+ */
+
+import { useEffect, useRef, useState } from 'preact/hooks';
+import type { FormEvent, RefObject } from 'preact/compat';
+import { useFetcher } from '@/client/lib/router/fetcher';
+import { toAbsolutePath } from '@/shared/lib/fs/paths';
+import { copyToClipboard } from '@/client/hooks/ui/clipboard';
+
+/** The shape `/api/fs/action` answers with, as far as a row reads it. */
+interface FsActionResponse {
+  success?: boolean;
+  /** Present on the git-history payload, which the history modal reads. */
+  type?: string;
+  /** Relative path of a freshly created file. */
+  path?: string;
+  error?: string;
+}
+
+export interface FileActionTarget {
+  path: string;
+  name: string;
+  /** Absolute base dir of the listing, anchoring Copy Path. */
+  basePath?: string;
+  rootPath?: string;
+  repo?: string;
+}
+
+export interface FileActionDeps {
+  file: FileActionTarget;
+  /** Which diff to open, when the row is a changed file. */
+  diff?: { staged?: boolean; status?: string };
+  onOpenFile?: (file: { path: string; name: string; root?: string; repo?: string }) => void;
+  onActionComplete: () => void;
+}
+
+export interface FileActions {
+  contextMenu: { x: number; y: number } | null;
+  contextMenuRef: RefObject<HTMLDivElement>;
+  openContextMenu: (x: number, y: number) => void;
+  closeContextMenu: () => void;
+  showRenameModal: boolean;
+  showDeleteModal: boolean;
+  showHistoryModal: boolean;
+  showCreateModal: boolean;
+  /** The server's refusal for the create request, rendered inside its dialog. */
+  createError: string | null;
+  createName: string;
+  setCreateName: (value: string) => void;
+  renameValue: string;
+  setRenameValue: (value: string) => void;
+  /** True while a request is in flight; every dialog's buttons read it. */
+  busy: boolean;
+  /** The fetcher's own state/data, for the history modal. */
+  fetcherState: string;
+  fetcherData: FsActionResponse | undefined;
+  handleAction: (actionType: string) => void;
+  submitCreate: (e: FormEvent) => void;
+  submitRename: (e: FormEvent) => void;
+  submitDelete: () => void;
+  closeCreate: () => void;
+  closeDelete: () => void;
+  closeRename: () => void;
+  closeHistory: () => void;
+}
+
+export function useFileActions({ file, diff, onOpenFile, onActionComplete }: FileActionDeps): FileActions {
+  const actionFetcher = useFetcher<FsActionResponse>();
+  const [contextMenu, setContextMenu] = useState<{ x: number; y: number } | null>(null);
+  const contextMenuRef = useRef<HTMLDivElement>(null);
+  const [showRenameModal, setShowRenameModal] = useState(false);
+  const [showDeleteModal, setShowDeleteModal] = useState(false);
+  const [showHistoryModal, setShowHistoryModal] = useState(false);
+  const [showCreateModal, setShowCreateModal] = useState(false);
+  const [createName, setCreateName] = useState('');
+  const [createError, setCreateError] = useState<string | null>(null);
+  const [renameValue, setRenameValue] = useState(file.path);
+  /** Which dialog the in-flight request belongs to, so its result is routed. */
+  const pendingActionRef = useRef<'create' | null>(null);
+
+  const repo = file.repo;
+  const rootPath = file.rootPath;
+
+  /**
+   * The payload already acted on.
+   *
+   * The fetcher keeps `data` until the next request, and the callbacks below
+   * (`onActionComplete` → the panel's refresh → a re-render with a fresh
+   * callback identity) would otherwise re-run this effect for the SAME
+   * response forever: an unguarded effect here is an infinite refresh loop that
+   * pins the tab the moment a file is created.
+   */
+  const handledRef = useRef<FsActionResponse | null>(null);
+
+  useEffect(() => {
+    if (actionFetcher.state !== 'idle' || !actionFetcher.data) return;
+    const data = actionFetcher.data;
+    if (handledRef.current === data) return;
+    handledRef.current = data;
+    // The fetcher parses the body whatever the status, so a refusal arrives as
+    // `data.error` rather than as a throw — which is what lets the create
+    // dialog stay open and put the reason beside the field.
+    if (pendingActionRef.current === 'create') {
+      pendingActionRef.current = null;
+      if (data.success && data.path) {
+        // The user asked for a file to work on, so it opens: closing the dialog
+        // and refreshing the tree alone would leave them hunting for the empty
+        // row they just created.
+        setShowCreateModal(false);
+        setCreateName('');
+        setCreateError(null);
+        onActionComplete();
+        onOpenFile?.({
+          path: data.path,
+          name: data.path.split('/').pop() || data.path,
+          root: rootPath,
+          repo: repo || '.',
+        });
+      } else {
+        setCreateError(data.error || 'Could not create the file');
+      }
+      return;
+    }
+    if (data.success && !data.type) {
+      setShowRenameModal(false);
+      setShowDeleteModal(false);
+      onActionComplete();
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [actionFetcher.state, actionFetcher.data]);
+
+  const submitAction = (formData: FormData) => {
+    if (repo && repo !== '.') formData.append('repo', repo);
+    if (rootPath) formData.append('root', rootPath);
+    void actionFetcher.submit(formData, { method: 'post', action: '/api/fs/action' });
+  };
+
+  const openFile = () => {
+    onOpenFile?.({ path: file.path, name: file.name, root: rootPath, repo: repo || '.' });
+  };
+
+  const handleAction = (actionType: string) => {
+    setContextMenu(null);
+    if (actionType === 'view') {
+      openFile();
+    } else if (actionType === 'diff') {
+      window.dispatchEvent(new CustomEvent('omp:open-diff', {
+        detail: {
+          file: file.path,
+          staged: diff?.staged,
+          status: diff?.status || 'M',
+          repo: repo || '.',
+          root: rootPath,
+        },
+      }));
+    } else if (actionType === 'explorer') {
+      const fd = new FormData();
+      fd.append('actionType', 'open_explorer');
+      fd.append('path', file.path);
+      submitAction(fd);
+    } else if (actionType === 'copy_path') {
+      void copyToClipboard(toAbsolutePath(file.basePath, file.path));
+    } else if (actionType === 'copy_relative') {
+      void copyToClipboard(file.path);
+    } else if (actionType === 'history') {
+      setShowHistoryModal(true);
+      const fd = new FormData();
+      fd.append('actionType', 'git_history');
+      fd.append('path', file.path);
+      submitAction(fd);
+    } else if (actionType === 'rename') {
+      setRenameValue(file.path);
+      setShowRenameModal(true);
+    } else if (actionType === 'new_file') {
+      setCreateName('');
+      setCreateError(null);
+      setShowCreateModal(true);
+    } else if (actionType === 'delete') {
+      setShowDeleteModal(true);
+    }
+  };
+
+  const submitCreate = (e: FormEvent) => {
+    e.preventDefault();
+    const name = createName.trim();
+    if (!name) return;
+    setCreateError(null);
+    pendingActionRef.current = 'create';
+    const fd = new FormData();
+    fd.append('actionType', 'create');
+    fd.append('path', file.path);
+    fd.append('name', name);
+    submitAction(fd);
+  };
+
+  const submitRename = (e: FormEvent) => {
+    e.preventDefault();
+    const fd = new FormData();
+    fd.append('actionType', 'rename');
+    fd.append('path', file.path);
+    fd.append('newPath', renameValue);
+    submitAction(fd);
+  };
+
+  const submitDelete = () => {
+    const fd = new FormData();
+    fd.append('actionType', 'delete');
+    fd.append('path', file.path);
+    submitAction(fd);
+  };
+
+  return {
+    contextMenu,
+    contextMenuRef,
+    openContextMenu: (x, y) => setContextMenu({ x, y }),
+    closeContextMenu: () => setContextMenu(null),
+    showRenameModal,
+    showDeleteModal,
+    showHistoryModal,
+    showCreateModal,
+    createError,
+    createName,
+    setCreateName,
+    renameValue,
+    setRenameValue,
+    busy: actionFetcher.state !== 'idle',
+    fetcherState: actionFetcher.state,
+    fetcherData: actionFetcher.data,
+    handleAction,
+    submitCreate,
+    submitRename,
+    submitDelete,
+    closeCreate: () => setShowCreateModal(false),
+    closeDelete: () => setShowDeleteModal(false),
+    closeRename: () => setShowRenameModal(false),
+    closeHistory: () => setShowHistoryModal(false),
+  };
+}

package/src/client/hooks/workspace/session-todos.ts

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Reads a session's live todo list for the right-panel view.
+ *
+ * The list belongs to omp and its only durable home is the session transcript,
+ * so this hook is a reader: it fetches `GET /api/omp/session-todos` and re-reads
+ * on two triggers —
+ *
+ *   - a poll (`usePanelRefresh`, paused while hidden), which covers a list the
+ *     agent changed while this client was not the one driving it;
+ *   - `omp:session-updated`, which the chat dispatches at every turn boundary
+ *     and therefore right after each `todo` tool call, so the panel follows a
+ *     running agent without waiting out the poll.
+ *
+ * The event path is throttled: one run emits the signal several times around a
+ * single tool call, and the read is a disk parse. A read already in flight is
+ * not cancelled by a newer trigger — the server answers an unchanged session
+ * from a stat, so the extra request is cheap, and dropping the newer one would
+ * leave the panel showing the list from before the call that just finished.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
+import { useChamberEvent } from '@/client/hooks/ui/window-event';
+import { usePanelRefresh } from '@/client/hooks/workspace/panel-refresh';
+import { TODO_REFRESH_EVENT_THROTTLE_MS } from '@/shared/lib/workspace/refresh-cadence';
+import type { SessionTodosPayload } from '@/shared/types/todo';
+
+export interface SessionTodosState {
+  data: SessionTodosPayload | null;
+  isLoading: boolean;
+  /** Set when the last read failed; the previous payload is kept meanwhile. */
+  error: string | null;
+  reload: () => void;
+}
+
+export function useSessionTodos(sessionId: string | null, enabled: boolean): SessionTodosState {
+  const [data, setData] = useState<SessionTodosPayload | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // Latest session id for the fetcher, so switching sessions does not have to
+  // rebuild the callback (and with it the poll interval) on every render.
+  const sessionIdRef = useRef(sessionId);
+  sessionIdRef.current = sessionId;
+  // Guards against a response for a session the user has already left being
+  // written into the panel that now shows a different one.
+  const requestRef = useRef(0);
+
+  const load = useCallback(() => {
+    const id = sessionIdRef.current;
+    if (!id) {
+      setData(null);
+      return;
+    }
+    const request = ++requestRef.current;
+    setIsLoading(true);
+    fetch(`/api/omp/session-todos?sessionId=${encodeURIComponent(id)}`)
+      .then((response) => {
+        if (!response.ok) throw new Error(`Todo request failed (${response.status})`);
+        return response.json() as Promise<SessionTodosPayload>;
+      })
+      .then((payload) => {
+        if (requestRef.current !== request) return;
+        setData(payload);
+        setError(null);
+      })
+      .catch((err: unknown) => {
+        if (requestRef.current !== request) return;
+        setError(err instanceof Error ? err.message : 'Failed to load todos');
+      })
+      .finally(() => {
+        if (requestRef.current === request) setIsLoading(false);
+      });
+  }, []);
+
+  // A session switch must not render the previous session's list under the new
+  // title: drop the payload and re-read immediately.
+  useEffect(() => {
+    setData(null);
+    setError(null);
+    if (sessionId) load();
+  }, [sessionId, load]);
+
+  usePanelRefresh(load, enabled);
+
+  const throttleRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  useChamberEvent('omp:session-updated', () => {
+    if (!enabled || throttleRef.current !== undefined) return;
+    throttleRef.current = setTimeout(() => {
+      throttleRef.current = undefined;
+      load();
+    }, TODO_REFRESH_EVENT_THROTTLE_MS);
+  });
+
+  useEffect(() => () => clearTimeout(throttleRef.current), []);
+
+  return { data, isLoading, error, reload: load };
+}

package/src/client/stubs/elkjs.ts

@@ -4,7 +4,12 @@
  */
 
 /**
- * Browser replacement for `elkjs`, aliased in `rsbuild.config.ts`.
+ * Browser replacement for `elkjs`, aliased through `tsconfig.json` `paths`.
+ *
+ * The alias moved there when the client build moved to Bun: Bun's bundler does
+ * not read an `alias` option (it is absent from `Bun.build`'s config and from
+ * `bun-types`; passing one is silently ignored — verified), while `paths` it
+ * honours for both internal aliases and package specifiers.
  *
  * Mermaid 12 changed the global `layout` default from `dagre` to `elk`, so every
  * flowchart pulled in `elkjs/lib/elk.bundled.js` whether the diagram asked for

package/src/client/tailwind.css

@@ -246,6 +246,36 @@
  * The selector keys off the variant attribute, not a list of theme ids. */
 .shiki span { color: var(--shiki-light); }
 html[data-theme-variant="dark"] .shiki span { color: var(--shiki-dark); }
+
+/* Find matches, painted inside the token spans the highlighter emits. An
+ * inline <mark> colours a background without moving a glyph, which is what
+ * keeps the transparent <textarea> above aligned with this layer — a block or
+ * a padding would shift the text under the caret. `color: inherit` is required:
+ * a <mark> would otherwise take the UA's own black-on-yellow, ignoring the
+ * dual-theme token colour it sits inside.
+ *
+ * No `border-radius`, and the current match is marked with TOP/BOTTOM borders
+ * rather than an outline: a match spanning several tokens (`const alpha` is
+ * three) is emitted as one <mark> per token, so any per-fragment decoration
+ * that draws vertical edges — radius, outline, left/right border — paints a
+ * seam in the middle of the match. Horizontal edges join seamlessly. */
+.shiki .find-match {
+  color: inherit;
+  background: color-mix(in srgb, var(--theme-warning) 32%, transparent);
+}
+/* An extra ⌘D selection: same geometry as a find match, different ink. The
+ * caret can only live in the primary range, so the two must not look alike —
+ * the user has to see where their keystrokes will land. */
+.shiki .find-match[data-occurrence] {
+  background: color-mix(in srgb, var(--theme-info) 30%, transparent);
+  border-top: 1px solid color-mix(in srgb, var(--theme-info) 55%, transparent);
+  border-bottom: 1px solid color-mix(in srgb, var(--theme-info) 55%, transparent);
+}
+.shiki .find-match[data-find-current] {
+  background: color-mix(in srgb, var(--theme-warning) 55%, transparent);
+  border-top: 1px solid color-mix(in srgb, var(--theme-warning) 75%, transparent);
+  border-bottom: 1px solid color-mix(in srgb, var(--theme-warning) 75%, transparent);
+}
 .prose-content .katex-display { overflow-x: auto; overflow-y: hidden; }
 
 /* Math placeholder: `marked.ts` emits a `.math-pending` span and KaTeX is

package/src/server/index.ts

@@ -1,13 +1,16 @@
 import { Elysia } from 'elysia';
 import pkg from '@/../package.json';
+import shell from '@/../index.html';
 import { apiRoutes } from '@/server/routes';
 import { ssrRoutes } from '@/server/plugins/ssr';
+import { setShellSource } from '@/server/plugins/shell.server';
 import { getDatabasePath } from '@/server/db.server';
 import { fetchOmpRegistrySnapshot } from '@/server/lib/models/provider-registry.server';
 import { ompStartupError, ompStartupLogLines } from '@/server/lib/omp/core/startup';
 import { readInstanceRecord, removeInstanceRecord, writeInstanceRecord } from '@/server/lib/lifecycle/instance';
 import { resolveLaunchMode } from '@/server/lib/lifecycle/launch-mode';
 import { acquirePortLock, claimPort, PortInUseError } from '@/server/lib/lifecycle/port-guard';
+import { SHELL_ROUTE } from '@/server/lib/lifecycle/shell-route';
 import { isMockMode } from '@/server/mock.server';
 
 // Refuse to run without a resolvable omp binary — before the listener opens and
@@ -39,7 +42,15 @@ if (!lock) {
   process.exit(1);
 }
 
-const app = new Elysia().use(apiRoutes).use(ssrRoutes);
+// `serve.routes` is where the HTML shell lives. Elysia merges its own static
+// routes into that same table (its Bun adapter passes `serve` straight to
+// `Bun.serve`), and Bun's table wins for the paths it declares — so `/_shell`
+// renders the bundle while every other path falls through to `fetch`. The
+// WebSocket routes keep working: Elysia composes its `websocket` handler
+// alongside this object.
+const app = new Elysia({ serve: { routes: { [SHELL_ROUTE]: shell } } })
+  .use(apiRoutes)
+  .use(ssrRoutes);
 
 try {
   await claimPort({
@@ -50,7 +61,14 @@ try {
       // `reusePort: true`, which lets a second server bind a port already in
       // use and then sit invisible while the first-bound socket takes every
       // connection.
-      await app.listen({ port, hostname: host, reusePort: false });
+      app.listen({ port, hostname: host, reusePort: false });
+      if (!app.server) throw new Error('Bun.serve returned no listener');
+      // The shell is rendered by asking this same listener for it: Bun renders
+      // an HTML route only while serving, and there is no in-process API for an
+      // `HTMLBundle` (`new Response(bundle)` is "[object HTMLBundle]",
+      // `app.handle` answers 404). Handing the listener over is what makes
+      // `renderShell()` possible.
+      setShellSource(app.server);
     },
   });
 } catch (error) {

package/src/server/lib/assets/font-css.server.ts

@@ -0,0 +1,86 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The font stylesheet, assembled at request time.
+ *
+ * `@font-face` blocks cannot live in the bundle: Bun's CSS loader resolves every
+ * local `url()`, and a font is always a local file — so a bundled face is either
+ * a base64 blob or an absolute filesystem path. `lib/bundler/css.ts` lifts each
+ * block out of its stylesheet and rewrites the urls to `<FONT_ROUTE_PREFIX><basename>`;
+ * this module serves the result.
+ *
+ * Two jobs, one route each:
+ *
+ * - `FONT_STYLESHEET_ROUTE` (`/fonts.css`) concatenates the extracted faces.
+ *   Read per request rather than cached: it is a handful of kilobytes, and a
+ *   cache is what would keep a stale face alive across an edit to a stylesheet.
+ *   A missing directory is an empty stylesheet, not a 404 — the shell links this
+ *   unconditionally.
+ *
+ * - `FONT_ROUTE_PREFIX` (`/fonts/<basename>`) serves the file itself from the
+ *   installed packages. The basename is the whole key, so the lookup is an index
+ *   rather than a path built from the request; see `fonts.server.ts`.
+ */
+
+import { join } from 'path';
+import { Glob } from 'bun';
+
+import { packageRoot, resolveFontFile } from '@/server/lib/assets/fonts.server';
+
+/** Directory holding one extracted face file per source stylesheet. */
+export const FONT_FACE_DIR = join('.ompchamber-build', 'font-faces');
+
+/** The route the assembled stylesheet is served on. */
+export const FONT_STYLESHEET_ROUTE = '/fonts.css';
+
+const FONT_MIME: Record<string, string> = {
+  '.woff2': 'font/woff2',
+  '.woff': 'font/woff',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+};
+
+const STYLESHEET_HEADERS = {
+  'content-type': 'text/css; charset=utf-8',
+  'cache-control': 'no-store',
+} as const;
+
+/** Every extracted face file, concatenated in a stable order. */
+export async function fontStylesheet(): Promise<string> {
+  const dir = join(packageRoot(), FONT_FACE_DIR);
+  const glob = new Glob('*.css');
+  const files: string[] = [];
+  try {
+    for await (const file of glob.scan({ cwd: dir, onlyFiles: true })) files.push(file);
+  } catch {
+    return '';
+  }
+  // Sorted so the stylesheet is byte-stable between builds: the browser caches
+  // on the ETag, and an unstable order would invalidate it for no change.
+  files.sort();
+  const parts = await Promise.all(files.map((file) => Bun.file(join(dir, file)).text()));
+  return parts.join('\n');
+}
+
+/** The `/fonts.css` response. */
+export async function serveFontStylesheet(): Promise<Response> {
+  return new Response(await fontStylesheet(), { headers: STYLESHEET_HEADERS });
+}
+
+/** The `/fonts/<basename>` response, or null when no package ships that file. */
+export async function serveFontFile(name: string): Promise<Response | null> {
+  const file = await resolveFontFile(name);
+  if (!file) return null;
+  const ext = name.slice(name.lastIndexOf('.')).toLowerCase();
+  return new Response(Bun.file(file), {
+    headers: {
+      'content-type': FONT_MIME[ext] ?? 'application/octet-stream',
+      // A font's bytes never change under a fixed basename inside a pinned
+      // dependency, so this is the one asset that can be cached hard.
+      'cache-control': 'public, max-age=31536000, immutable',
+    },
+  });
+}

package/src/server/lib/assets/fonts.server.ts

@@ -0,0 +1,117 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Font files served straight from the installed packages.
+ *
+ * The client stylesheet reaches its `@font-face` sources through the bundler's
+ * CSS loader (`lib/bundler/css.ts`), which rewrites every one of them to
+ * `<FONT_ROUTE_PREFIX><basename>`. Nothing copies them into the repository: a
+ * font is addressed by its own basename, and this module resolves that basename
+ * back to the package that ships it.
+ *
+ * A directory index rather than a path built from the request, because the
+ * request must never choose a directory. The index is built once, lazily, by
+ * walking the vendor font directories, and a basename that is not in it is a
+ * 404 rather than a lookup somewhere else.
+ *
+ * The search roots are not just `process.cwd()`. An installed package runs the
+ * AOT bundle from `dist/client`, and a `serve --prod` started from another
+ * directory has neither `node_modules` nor the source tree under it — so the
+ * roots are every directory from the running module up to the filesystem root,
+ * plus the cwd. Whichever one holds `node_modules` is the package root.
+ */
+
+import { existsSync } from 'fs';
+import { basename, dirname, join, parse, resolve } from 'path';
+import { Glob } from 'bun';
+
+/** Path prefix every rewritten font url carries. */
+export const FONT_ROUTE_PREFIX = '/fonts/';
+
+/** Where the fonts live, relative to a package root. */
+const FONT_SOURCES = [
+  'node_modules/katex/dist/fonts',
+  'node_modules/@fontsource/fira-code/files',
+] as const;
+
+/**
+ * Directories a package root may be found under, nearest first.
+ *
+ * `import.meta.dir` is the running file's directory — the repo root for the
+ * TypeScript entry, `dist/client` for the AOT bundle — and walking up from it
+ * finds `node_modules` in both. The cwd is included because a source checkout
+ * run from elsewhere still resolves its dependencies through it.
+ */
+function searchRoots(): string[] {
+  const roots: string[] = [];
+  const seen = new Set<string>();
+  const add = (dir: string) => {
+    if (dir && !seen.has(dir)) {
+      seen.add(dir);
+      roots.push(dir);
+    }
+  };
+
+  let dir = import.meta.dir;
+  const { root } = parse(dir);
+  for (;;) {
+    add(dir);
+    if (dir === root) break;
+    dir = dirname(dir);
+  }
+  add(resolve(process.cwd()));
+  return roots;
+}
+
+/** Basename -> absolute path. Built once; the packages do not change at runtime. */
+let index: Record<string, string> | null = null;
+
+/**
+ * The package root — the first search root that holds `node_modules`.
+ *
+ * Both ends of the build need the same answer: the plugin writes the extracted
+ * face files here and the server reads them back, and an AOT bundle runs from
+ * `dist/client` while a source checkout runs from the repo. Falling back to the
+ * cwd keeps a checkout with no `node_modules` (a publish dry-run) working.
+ */
+export function packageRoot(): string {
+  for (const root of searchRoots()) {
+    // `existsSync` rather than `Bun.file().exists()`: the latter is async and
+    // file-only, and `node_modules` is a directory.
+    if (existsSync(join(root, 'node_modules'))) return root;
+  }
+  return process.cwd();
+}
+
+async function buildIndex(): Promise<Record<string, string>> {
+  const found: Record<string, string> = {};
+  const glob = new Glob('*.{woff2,woff,ttf,otf}');
+  for (const root of searchRoots()) {
+    for (const dir of FONT_SOURCES) {
+      const from = join(root, dir);
+      try {
+        for await (const file of glob.scan({ cwd: from, onlyFiles: true })) {
+          const name = basename(file);
+          // Nearest root wins: a checkout's own node_modules is what its build
+          // was made against, so it must not lose to a parent's copy.
+          found[name] ??= join(from, file);
+        }
+      } catch {
+        // A root without these packages contributes nothing; the CSS that
+        // referenced a missing font will 404, which is the honest outcome.
+      }
+    }
+  }
+  return found;
+}
+
+/** The font file for a basename, or null when nothing ships it. */
+export async function resolveFontFile(name: string): Promise<string | null> {
+  // A basename only: a request for `../` or a nested path is not a font.
+  if (!name || name !== basename(name)) return null;
+  index ??= await buildIndex();
+  return index[name] ?? null;
+}