ompchamber 3.2.0 → 3.3.0

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

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

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

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

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