ompchamber 3.2.0 → 3.3.1

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

@@ -0,0 +1,78 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * True when an element's content is visually cut off by CSS truncation.
+ *
+ * `text-overflow: ellipsis` hides content at a WIDTH, not at a character count,
+ * and the two are unrelated: the same 76-character line fits a 970px desktop
+ * timeline and is cut on a 340px phone card. A caller that decides "is there
+ * more to show?" from `text.length` therefore renders an ellipsis the user can
+ * see and no way to reveal it — the exact failure this hook exists to prevent.
+ *
+ * `scrollWidth > clientWidth` is the measurement the browser itself uses to
+ * decide whether to draw the ellipsis, so it cannot disagree with what is on
+ * screen. Three details are load-bearing:
+ *
+ * - A zero-width element reports 0 for BOTH values, which reads as "fits". That
+ *   is not a measurement, it is the absence of one (a `display: none` ancestor,
+ *   a detached node), so it is skipped and the previous answer stands.
+ * - The measurement is retained when the ref detaches. Callers unmount the
+ *   truncated row as soon as it expands, and forgetting the answer there would
+ *   retract the very control the user just used.
+ * - A webfont that lands after first paint changes the text's width without
+ *   resizing the box, so `ResizeObserver` alone never fires. `document.fonts`
+ *   is the one signal for it.
+ */
+
+import { useLayoutEffect, useRef, useState } from 'preact/hooks';
+import type { RefObject } from 'preact';
+
+/**
+ * @param ref Element carrying the truncating class.
+ * @param content Deps that change the rendered text; the element's own resize
+ *   is observed, but new text in an unchanged box is not.
+ */
+export function useIsTruncated(
+  ref: RefObject<HTMLElement | null>,
+  content: unknown,
+): boolean {
+  const [truncated, setTruncated] = useState(false);
+  const measuredRef = useRef(false);
+
+  useLayoutEffect(() => {
+    const element = ref.current;
+    if (!element) return;
+
+    let cancelled = false;
+    const measure = () => {
+      if (cancelled) return;
+      // No layout to measure — keep the last real answer rather than report "fits".
+      if (element.clientWidth === 0) return;
+      const next = element.scrollWidth > element.clientWidth;
+      if (next === measuredRef.current) return;
+      measuredRef.current = next;
+      setTruncated(next);
+    };
+
+    measure();
+
+    // Fonts swap after first paint and move the text inside a box that never
+    // resizes, so no observer fires; `fonts.ready` is the only signal. Absent
+    // in a DOM without font loading (a test environment), hence the guard.
+    document?.fonts?.ready?.then(measure).catch(() => {});
+
+    if (typeof ResizeObserver === 'undefined') return;
+    const observer = new ResizeObserver(measure);
+    observer.observe(element);
+
+    return () => {
+      cancelled = true;
+      observer.disconnect();
+    };
+  }, [ref, content]);
+
+  return truncated;
+}

package/src/client/hooks/ui/touch-device.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Whether this device is typed into with a soft keyboard — the only condition
+ * under which a terminal needs on-screen keys.
+ *
+ * `(pointer: coarse)` is the signal: a phone or tablet reports it, and a
+ * touchscreen laptop does not, because its primary pointer is the trackpad.
+ * The fallback covers the devices that report a fine pointer anyway (some
+ * Android desktop modes): touch points plus `(hover: none)`, which is the pair
+ * that means "there is no pointer at all" rather than "there is a screen that
+ * can be touched".
+ *
+ * The queries are subscribed, not read once: a hybrid device that docks a
+ * keyboard or leaves tablet mode changes the answer, and a bar of keys that
+ * cannot react to that is stuck on a desktop or missing on a phone.
+ */
+
+import { useEffect, useState } from 'preact/hooks';
+
+const COARSE_POINTER_QUERY = '(pointer: coarse)';
+const NO_HOVER_QUERY = '(hover: none)';
+
+function detectSoftKeyboardDevice(): boolean {
+  if (typeof window === 'undefined') return false;
+  if (window.matchMedia(COARSE_POINTER_QUERY).matches) return true;
+  return navigator.maxTouchPoints > 0 && window.matchMedia(NO_HOVER_QUERY).matches;
+}
+
+export function useTouchDevice(): boolean {
+  const [isTouch, setIsTouch] = useState(detectSoftKeyboardDevice);
+
+  useEffect(() => {
+    const queries = [COARSE_POINTER_QUERY, NO_HOVER_QUERY].map((q) => window.matchMedia(q));
+    const update = () => setIsTouch(detectSoftKeyboardDevice());
+    for (const query of queries) query.addEventListener('change', update);
+    return () => {
+      for (const query of queries) query.removeEventListener('change', update);
+    };
+  }, []);
+
+  return isTouch;
+}

package/src/client/main.tsx

@@ -7,6 +7,7 @@ import { initDocumentTheme } from '@/client/hooks/ui/theme';
 import '@/client/tailwind.css';
 import '@/shared/lib/markdown/katex-fonts.css';
 import '@/shared/lib/markdown/fira-code-fonts.css';
+import '@/shared/lib/fonts/nerd-symbols.css';
 
 const root = document.getElementById('app');
 const bootstrap = window.__OMP_BOOTSTRAP__;

package/src/server/index.ts

@@ -3,7 +3,7 @@ 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 { setListener } from '@/server/lib/lifecycle/listener';
 import { getDatabasePath } from '@/server/db.server';
 import { fetchOmpRegistrySnapshot } from '@/server/lib/models/provider-registry.server';
 import { ompStartupError, ompStartupLogLines } from '@/server/lib/omp/core/startup';
@@ -67,8 +67,9 @@ try {
       // 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);
+      // `renderShell()` possible — and the dev asset proxy reaches Bun's own
+      // asset routes through it for the same reason.
+      setListener(app.server);
     },
   });
 } catch (error) {

package/src/server/lib/assets/conditional.server.test.ts

@@ -0,0 +1,74 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { notModified } from '@/server/lib/assets/conditional.server';
+
+const ETAG = '"abc123"';
+const MTIME_MS = Date.parse('2026-01-02T03:04:05.000Z');
+
+/** A GET carrying the given conditional headers. */
+const request = (headers: Record<string, string> = {}) => new Request('http://localhost/asset.js', { headers });
+
+describe('notModified', () => {
+  test('a plain request is never a match', () => {
+    expect(notModified(request(), ETAG, MTIME_MS)).toBe(false);
+  });
+
+  test('a matching validator answers 304', () => {
+    expect(notModified(request({ 'if-none-match': ETAG }), ETAG, MTIME_MS)).toBe(true);
+  });
+
+  test('a stale validator does not', () => {
+    expect(notModified(request({ 'if-none-match': '"other"' }), ETAG, MTIME_MS)).toBe(false);
+  });
+
+  test('a weak or list-form validator still matches', () => {
+    expect(notModified(request({ 'if-none-match': `W/${ETAG}` }), ETAG, MTIME_MS)).toBe(true);
+    expect(notModified(request({ 'if-none-match': `"other", ${ETAG}` }), ETAG, MTIME_MS)).toBe(true);
+    expect(notModified(request({ 'if-none-match': '"other", W/' + ETAG }), ETAG, MTIME_MS)).toBe(true);
+  });
+
+  test('a date at or after the mtime matches, an older one does not', () => {
+    expect(notModified(request({ 'if-modified-since': new Date(MTIME_MS).toUTCString() }), ETAG, MTIME_MS)).toBe(true);
+    expect(notModified(request({ 'if-modified-since': new Date(MTIME_MS + 60_000).toUTCString() }), ETAG, MTIME_MS)).toBe(true);
+    expect(notModified(request({ 'if-modified-since': new Date(MTIME_MS - 1000).toUTCString() }), ETAG, MTIME_MS)).toBe(false);
+  });
+
+  // HTTP dates carry one-second resolution. A file whose mtime has a fractional
+  // part must still match the `Last-Modified` this server sent for it, or no
+  // request could ever revalidate.
+  test('a fractional mtime is floored before comparing', () => {
+    const fractional = MTIME_MS + 742;
+    expect(notModified(request({ 'if-modified-since': new Date(MTIME_MS).toUTCString() }), ETAG, fractional)).toBe(true);
+  });
+
+  // RFC 9110 §13.1.3: `If-Modified-Since` MUST be ignored when `If-None-Match`
+  // is present. A stale validator beside a fresh date is a stale copy.
+  test('If-None-Match wins over If-Modified-Since', () => {
+    const fresh = new Date(MTIME_MS + 60_000).toUTCString();
+    expect(notModified(request({ 'if-none-match': '"stale"', 'if-modified-since': fresh }), ETAG, MTIME_MS)).toBe(false);
+  });
+
+  test('an unparseable date is not a match', () => {
+    expect(notModified(request({ 'if-modified-since': 'not-a-date' }), ETAG, MTIME_MS)).toBe(false);
+  });
+
+  // A server that offers only `Last-Modified` revalidates on the date alone —
+  // the standard fallback. Neither caller here takes this shape (the file route
+  // always mints a validator, the dev proxy never has a date), but the rule is
+  // the general one and the branch is reachable if either changes.
+  test('without a validator, the date decides', () => {
+    expect(notModified(request({ 'if-modified-since': new Date(MTIME_MS).toUTCString() }), null, MTIME_MS)).toBe(true);
+    expect(notModified(request({ 'if-modified-since': new Date(MTIME_MS - 1000).toUTCString() }), null, MTIME_MS)).toBe(false);
+  });
+
+  test('with a validator but no mtime, only the validator can match', () => {
+    expect(notModified(request({ 'if-none-match': ETAG }), ETAG, null)).toBe(true);
+    expect(notModified(request({ 'if-none-match': '"other"' }), ETAG, null)).toBe(false);
+    expect(notModified(request({ 'if-modified-since': new Date(MTIME_MS).toUTCString() }), ETAG, null)).toBe(false);
+  });
+});

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

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Conditional requests for the assets this server serves itself.
+ *
+ * Two routes hand out bytes and both need the same answer to "is the client's
+ * copy still good?" — `plugins/static.ts`, from a file on disk, and
+ * `lib/assets/dev-assets.server.ts`, from bytes it just read back through Bun's
+ * dev asset routes. They must agree: a rule applied to one and not the other
+ * would make one asset kind revalidate differently from another for no reason a
+ * caller could see, so the decision lives here rather than in either caller.
+ *
+ * The precedence is the load-bearing part. RFC 9110 §13.1.3: a recipient MUST
+ * ignore `If-Modified-Since` when the request carries `If-None-Match`. So the
+ * presence of `If-None-Match` settles the response on its own — a non-match
+ * means "the client's copy is stale" (200), never a reason to consult the date.
+ *
+ * Every path here errs toward `false`. A `false` costs one full response; a
+ * wrong `true` hands the client a stale asset with no way to notice.
+ */
+
+/**
+ * Whether the client's stored copy is still current, so the caller can answer
+ * `304` and skip the body.
+ *
+ * `lastModifiedMs` is the file's own mtime; pass null when there is no file
+ * behind the bytes (the dev proxy hashes what it fetched instead).
+ */
+export function notModified(request: Request, etag: string | null, lastModifiedMs: number | null): boolean {
+  const ifNoneMatch = request.headers.get('if-none-match');
+  if (ifNoneMatch !== null) {
+    if (!etag) return false;
+    // A validator survives a `W/` prefix and arrives as a candidate list.
+    const wanted = etag.trim().replace(/^W\//, '');
+    return ifNoneMatch.split(',').some((candidate) => candidate.trim().replace(/^W\//, '') === wanted);
+  }
+
+  const ifModifiedSince = request.headers.get('if-modified-since');
+  if (ifModifiedSince && lastModifiedMs !== null) {
+    const since = Date.parse(ifModifiedSince);
+    if (!Number.isNaN(since)) {
+      // HTTP dates carry one-second resolution, so the mtime is floored to match
+      // before comparing. Without the floor a file whose mtime has a fractional
+      // part is always "newer" than the `Last-Modified` this server just sent
+      // for it, and no request could ever revalidate.
+      return Math.floor(lastModifiedMs / 1000) * 1000 <= since;
+    }
+  }
+
+  return false;
+}

package/src/server/lib/assets/dev-assets.server.test.ts

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { devAssetUpstreamPath, rewriteDevAssetUrls } from '@/server/lib/assets/dev-assets.server';
+
+describe('rewriteDevAssetUrls', () => {
+  test('moves the bundle and the assets to the proxied prefix', () => {
+    const html = '<script src="/_bun/client/index-abc.js"></script><link href="/_bun/asset/x.css">';
+    expect(rewriteDevAssetUrls(html)).toBe(
+      '<script src="/_dev-assets/client/index-abc.js"></script><link href="/_dev-assets/asset/x.css">',
+    );
+  });
+
+  // The HMR client dials `/_bun/hmr` from the bundle and the beacon posts to
+  // `/_bun/unref`; both are Bun's own routes and must stay where Bun serves them.
+  test('leaves the HMR socket and the unref beacon on Bun', () => {
+    const html = '<script>new WebSocket("/_bun/hmr");navigator.sendBeacon("/_bun/unref")</script>';
+    expect(rewriteDevAssetUrls(html)).toBe(html);
+  });
+});
+
+describe('devAssetUpstreamPath', () => {
+  test('maps a proxied asset back to the path Bun serves', () => {
+    expect(devAssetUpstreamPath('/_dev-assets/client/index-abc.js')).toBe('/_bun/client/index-abc.js');
+    expect(devAssetUpstreamPath('/_dev-assets/asset/x.css')).toBe('/_bun/asset/x.css');
+  });
+
+  test('claims nothing outside its prefix', () => {
+    expect(devAssetUpstreamPath('/_bun/client/index-abc.js')).toBeNull();
+    expect(devAssetUpstreamPath('/fonts.css')).toBeNull();
+    expect(devAssetUpstreamPath('/')).toBeNull();
+  });
+
+  // A prefix match alone is not enough: `/_bun/hmr` is a WebSocket upgrade and
+  // must never be proxied through a normal request handler.
+  test('refuses a Bun path that is not a page-load asset', () => {
+    expect(devAssetUpstreamPath('/_dev-assets/hmr')).toBeNull();
+    expect(devAssetUpstreamPath('/_dev-assets/unref')).toBeNull();
+  });
+});

package/src/server/lib/assets/dev-assets.server.ts

@@ -0,0 +1,121 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Dev asset proxy — the one place Bun's own asset routes fall short.
+ *
+ * In development Bun bundles `index.html` itself and answers the assets it emits
+ * from its own routing table (`/_bun/client/*`, `/_bun/asset/*`), before a
+ * request can reach Elysia. Those responses carry an `ETag` but ignore
+ * `If-None-Match`, carry no `Cache-Control`, and are never compressed — so every
+ * page load re-downloads the whole unminified bundle. Measured on Bun 1.4.2, a
+ * 19.7 MB dev bundle answered `200` with all 19,755,962 bytes to a request that
+ * sent its own ETag back, and again with `Accept-Encoding: gzip, br, zstd` (no
+ * `content-encoding`). The same server with `development: false` answers `304`
+ * and `Cache-Control: public, max-age=31536000, immutable`, which is exactly why
+ * production is cheap and development was not.
+ *
+ * Bun's table wins for the paths it declares, so a route on `/_bun/*` cannot
+ * shadow them (verified: a `routes` entry for `/_bun/client/*` is never
+ * reached). The shell is therefore rewritten to a prefix this server owns, and
+ * this module serves the bytes back from the listener — adding the two headers
+ * Bun omits.
+ *
+ * Why `no-cache` rather than `immutable`: the JS bundle's name is a build
+ * generation id that changes on every rebuild, but the CSS asset names are NOT
+ * content-addressed — appending a rule to `tailwind.css` changed the bytes
+ * served at the same `/_bun/asset/<hash>.css` URL (verified). `immutable` there
+ * would pin stale styles for a year. `no-cache` plus a content `ETag` is correct
+ * for both: the browser stores the body and revalidates, so an unchanged asset
+ * costs one 304 instead of a re-download.
+ *
+ * Development only. Production assets are content-hashed and already answered
+ * with a working `304` and `immutable` — by Bun's own table in runtime mode and
+ * by `plugins/static.ts` from a build — so neither needs this.
+ */
+
+import { notModified } from '@/server/lib/assets/conditional.server';
+import { maybeCompress } from '@/server/plugins/compress';
+
+/** Whether the proxy is active at all. See the module comment. */
+export const DEV_ASSETS_ENABLED = Bun.env.NODE_ENV !== 'production';
+
+/** Bun's own dev asset prefix — its routing table owns every path under it. */
+const BUN_ASSET_PREFIX = '/_bun/';
+
+/**
+ * The asset kinds worth proxying.
+ *
+ * `/_bun/hmr` (the WebSocket) and `/_bun/unref` (a visibility beacon) stay on
+ * Bun's table: neither is a page-load byte, and proxying them would put a socket
+ * upgrade and a POST through here for nothing.
+ */
+const ASSET_KINDS = ['/_bun/client/', '/_bun/asset/'] as const;
+
+/** The prefix this server answers instead. Underscored, so it cannot collide. */
+export const DEV_ASSET_PREFIX = '/_dev-assets/';
+
+/** Cache policy: store the body, revalidate every time. See the module comment. */
+const DEV_ASSET_CACHE = 'no-cache';
+
+/** `/_bun/client/x.js` -> `/_dev-assets/client/x.js`, in the shell markup. */
+export function rewriteDevAssetUrls(html: string): string {
+  let out = html;
+  for (const kind of ASSET_KINDS) {
+    out = out.replaceAll(kind, DEV_ASSET_PREFIX + kind.slice(BUN_ASSET_PREFIX.length));
+  }
+  return out;
+}
+
+/** `/_dev-assets/client/x.js` -> `/_bun/client/x.js`, or null when not ours. */
+export function devAssetUpstreamPath(pathname: string): string | null {
+  if (!pathname.startsWith(DEV_ASSET_PREFIX)) return null;
+  const upstream = BUN_ASSET_PREFIX + pathname.slice(DEV_ASSET_PREFIX.length);
+  return ASSET_KINDS.some((kind) => upstream.startsWith(kind)) ? upstream : null;
+}
+
+/**
+ * The response for a dev asset request, or null when the path is not one.
+ *
+ * `base` is the listener's own URL: the bytes are fetched back from it because
+ * Bun's bundle is in memory and its routing table — not Elysia's — owns the
+ * `/_bun/*` paths.
+ */
+export async function serveDevAsset(request: Request, pathname: string, base: URL): Promise<Response | null> {
+  const upstream = devAssetUpstreamPath(pathname);
+  if (!upstream) return null;
+
+  const response = await fetch(new URL(upstream, base));
+  const type = response.headers.get('content-type') ?? '';
+  // An asset name that no longer exists falls through Bun's table to the SSR
+  // catch-all and comes back as the shell markup. Serving that as JavaScript
+  // would fail far from its cause, so it is reported here instead.
+  if (!response.ok || type.startsWith('text/html')) {
+    return new Response(`No dev asset at ${upstream}\n`, {
+      status: 404,
+      headers: { 'content-type': 'text/plain; charset=utf-8' },
+    });
+  }
+
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  const etag = `"${Bun.hash(bytes).toString(16)}"`;
+  // The same decision the file route makes, so a dev asset and a built one
+  // revalidate identically. `lastModifiedMs` is null: there is no file behind
+  // these bytes, only the hash above, so the date branch does not apply.
+  if (notModified(request, etag, null)) {
+    return new Response(null, { status: 304, headers: { etag, 'cache-control': DEV_ASSET_CACHE } });
+  }
+
+  return maybeCompress(
+    new Response(bytes, {
+      headers: {
+        'content-type': type || 'application/octet-stream',
+        'cache-control': DEV_ASSET_CACHE,
+        etag,
+      },
+    }),
+    request.headers.get('accept-encoding'),
+  );
+}

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

@@ -4,13 +4,14 @@
  */
 
 /**
- * Font files served straight from the installed packages.
+ * Font files served straight from the installed packages — plus the one the
+ * chamber vendors itself (`src/shared/lib/fonts`, the Nerd Font symbols face).
  *
  * 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.
+ * `<FONT_ROUTE_PREFIX><basename>`. Nothing is copied at build time: a font is
+ * addressed by its own basename, and this module resolves that basename back to
+ * the directory 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
@@ -35,6 +36,10 @@ export const FONT_ROUTE_PREFIX = '/fonts/';
 const FONT_SOURCES = [
   'node_modules/katex/dist/fonts',
   'node_modules/@fontsource/fira-code/files',
+  // The one font the chamber vendors itself rather than borrowing from a
+  // package: the Nerd Font symbols face the terminal falls back to. See
+  // `src/shared/lib/fonts/nerd-symbols.css`.
+  'src/shared/lib/fonts',
 ] as const;
 
 /**

package/src/server/lib/bundler/build-errors.server.ts

@@ -0,0 +1,136 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Why the shell's bundle failed, in the terms the person who broke it needs.
+ *
+ * Bun renders an HTML route by bundling it. When the bundle fails, the route
+ * answers with Bun's own "Build Failed" page, which holds the file, line,
+ * message and offending source line — but only inside a JavaScript payload the
+ * page decodes at runtime (`Uint8Array.from(atob(…))`, a private binary format
+ * with no server-side reader). Scraping that would be a bet on Bun's internals.
+ *
+ * `Bun.build` is the supported way to the same facts: a probe over the same
+ * entrypoint with the same plugins returns `logs` carrying `message` and
+ * `position {file,line,column,lineText}`. What it reports is what `Bun.build`
+ * rejects, and that set covers every shape the route 500s on — measured against
+ * the route on Bun 1.4.2, an unresolved import that survives tree shaking and a
+ * syntax error both fail the route and are both reported here. It is not a
+ * subset of the route's failures, and deliberately so: a missing named export is
+ * answered `200` by the route while Bun serves a 104-byte stub that only calls
+ * `location.reload()` in place of the bundle, so the page cannot run. That is a
+ * real failure of the bundle and is reported as one.
+ *
+ * `target: 'browser'` because that is the bundle the page is served; `bun`
+ * agreed with it on every case measured.
+ *
+ * Runs only after the shell has already failed, so its cost lands on a page that
+ * is broken anyway and never on a healthy request.
+ */
+
+import { join, relative } from 'path';
+import type { BuildOutput, BunPlugin } from 'bun';
+
+import { packageRoot } from '@/server/lib/assets/fonts.server';
+
+/** The shell bundle's entrypoint, relative to the package root. */
+const SHELL_ENTRYPOINT = 'index.html';
+
+/** Bun's own config file, and the section naming the bundle's plugins. */
+const BUNFIG = 'bunfig.toml';
+
+type BundleLog = BuildOutput['logs'][number];
+
+/**
+ * The plugin list Bun uses for this bundle, read from the file Bun reads.
+ *
+ * The probe has to bundle what the route bundles: a plugin missing here would
+ * make it describe a build nobody is served — or succeed where the route fails,
+ * which reports nothing at all.
+ */
+async function bundlePlugins(root: string): Promise<BunPlugin[]> {
+  const path = join(root, BUNFIG);
+  if (!(await Bun.file(path).exists())) return [];
+
+  let configured: unknown;
+  try {
+    const config = Bun.TOML.parse(await Bun.file(path).text()) as {
+      serve?: { static?: { plugins?: unknown } };
+    };
+    configured = config.serve?.static?.plugins;
+  } catch {
+    // A config Bun cannot parse is the build's own error to report.
+    return [];
+  }
+  if (!Array.isArray(configured)) return [];
+
+  const plugins: BunPlugin[] = [];
+  for (const entry of configured) {
+    if (typeof entry !== 'string') continue;
+    // A relative path is resolved from the package root; a bare specifier is
+    // left to the resolver, exactly as Bun reads it. Dynamic because the
+    // specifier is whatever the config names, not a module known here.
+    const specifier = entry.startsWith('.') ? join(root, entry) : entry;
+    try {
+      const module = (await import(specifier)) as { default?: BunPlugin };
+      if (module.default) plugins.push(module.default);
+    } catch {
+      // Same: an unimportable plugin surfaces through the build, not here.
+    }
+  }
+  return plugins;
+}
+
+/**
+ * A path as the reader knows it: relative to the package root, falling back to
+ * the absolute path when the file is not under it. The fallback matters on
+ * macOS, where `tmpdir()` is `/var/…` while the same file resolves to
+ * `/private/var/…` — a lexically-relative path there is `../../../private/var/…`,
+ * which is longer than what it replaces.
+ */
+function displayPath(file: string, root: string): string {
+  const relativePath = relative(root, file);
+  return relativePath && !relativePath.startsWith('..') ? relativePath : file;
+}
+
+/** One error as `file:line:column  message` plus the offending source line. */
+function formatLog(log: BundleLog, root: string): string {
+  const position = log.position;
+  if (!position?.file) return log.message;
+  const where = `${displayPath(position.file, root)}:${position.line}:${position.column}`;
+  const source = position.lineText.trim();
+  // The source line travels with the position: a file and column alone still
+  // leave the reader hunting for the edit.
+  return source ? `${where}  ${log.message}\n    ${source}` : `${where}  ${log.message}`;
+}
+
+/**
+ * The bundle errors behind a shell that would not render, or null when this
+ * build is not the reason (a clean bundle means the failure lies elsewhere).
+ */
+export async function describeShellBuildFailure(root = packageRoot()): Promise<string | null> {
+  const entrypoint = join(root, SHELL_ENTRYPOINT);
+  if (!(await Bun.file(entrypoint).exists())) return null;
+
+  let result: BuildOutput;
+  try {
+    result = await Bun.build({
+      entrypoints: [entrypoint],
+      target: 'browser',
+      plugins: await bundlePlugins(root),
+      // `throw: false` is what makes the failures readable: it returns them as
+      // `logs` instead of rejecting with an AggregateError, and keeps the probe
+      // from printing a second copy of an error Bun has already printed.
+      throw: false,
+    });
+  } catch (error) {
+    return `Rebuilding the client bundle failed: ${error instanceof Error ? error.message : String(error)}`;
+  }
+  if (result.success) return null;
+
+  const errors = result.logs.filter((log) => log.level === 'error');
+  if (errors.length === 0) return null;
+  return errors.map((log) => formatLog(log, root)).join('\n');
+}