ompchamber 3.1.1 → 3.3.0

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

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/hooks/workspace/expanded-sessions.ts

@@ -0,0 +1,62 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Expanded-session rows, shared by the desktop and mobile session sidebars.
+ *
+ * A session row's roster (its `SubagentList`) is shown while that row's id is
+ * in the expanded set, so both sidebars must read and write ONE set — persisted
+ * in `app_settings.omp_sidebar_expanded_sessions` — or a row expanded on the
+ * phone would come back collapsed on the desktop.
+ *
+ * The `?subagent=` deep link auto-expands its session row: a reload on a
+ * subagent transcript must leave the roster entry that opened it visible.
+ */
+
+import { useCallback, useEffect, useState } from 'preact/hooks';
+import { useSearchParams } from '@/client/lib/router/search-params';
+import { loadExpandedSessionIds, saveExpandedSessionIds } from '@/shared/lib/workspace/sidebar-expanded';
+
+export interface ExpandedSessionsHandle {
+  expandedSessionIds: Set<string>;
+  /** Collapse an expanded row, or expand a collapsed one. Persists the result. */
+  toggleSession: (sessionId: string) => void;
+}
+
+export function useExpandedSessions(): ExpandedSessionsHandle {
+  const [searchParams] = useSearchParams();
+  const urlSubagentId = searchParams.get('subagent');
+  const urlSessionId = searchParams.get('sessionId');
+  const [expandedSessionIds, setExpandedSessionIds] = useState<Set<string>>(() => new Set());
+
+  useEffect(() => {
+    const saved = loadExpandedSessionIds();
+    if (saved && saved.size > 0) {
+      setExpandedSessionIds(saved);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!urlSubagentId || !urlSessionId) return;
+    setExpandedSessionIds(prev => {
+      if (prev.has(urlSessionId)) return prev;
+      const next = new Set(prev);
+      next.add(urlSessionId);
+      return next;
+    });
+  }, [urlSubagentId, urlSessionId]);
+
+  const toggleSession = useCallback((sessionId: string) => {
+    setExpandedSessionIds((prev) => {
+      const next = new Set(prev);
+      if (next.has(sessionId)) next.delete(sessionId);
+      else next.add(sessionId);
+      saveExpandedSessionIds(next);
+      return next;
+    });
+  }, []);
+
+  return { expandedSessionIds, toggleSession };
+}

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'),
+  );
+}