ompchamber 3.2.0 → 3.3.0

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

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

@@ -0,0 +1,103 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+import { describeShellBuildFailure } from '@/server/lib/bundler/build-errors.server';
+
+let root: string;
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), 'omp-build-errors-'));
+  Bun.write(join(root, 'index.html'), '<!doctype html><html><body><script type="module" src="./entry.ts"></script></body></html>');
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+describe('describeShellBuildFailure', () => {
+  test('names the file, position and message of a syntax error', async () => {
+    await Bun.write(join(root, 'entry.ts'), 'const a = 1;\nexport const broken = ;\n');
+
+    const detail = await describeShellBuildFailure(root);
+
+    expect(detail).toContain('entry.ts:2:23');
+    expect(detail).toContain('Unexpected ;');
+    // The offending source line travels with the message: a file and column
+    // alone still leave the reader hunting for the edit.
+    expect(detail).toContain('export const broken = ;');
+  });
+
+  test('reports an unresolved import that the bundle would use', async () => {
+    await Bun.write(join(root, 'entry.ts'), 'import { a } from "./nowhere";\nconsole.log(a);\n');
+
+    expect(await describeShellBuildFailure(root)).toContain('Could not resolve: "./nowhere"');
+  });
+
+  test('reports a missing named export, which the route serves as a reload stub', async () => {
+    // The route answers 200 for this, so a status-only check calls it healthy —
+    // but Bun replaces the bundle with a 104-byte stub that only calls
+    // `location.reload()`, so the page cannot run. It is a real failure of the
+    // bundle and is reported as one.
+    await Bun.write(join(root, 'dep.ts'), 'export const a = 1;\n');
+    await Bun.write(join(root, 'entry.ts'), 'import { zzz } from "./dep";\nconsole.log(zzz);\n');
+
+    expect(await describeShellBuildFailure(root)).toContain('No matching export');
+  });
+
+  test('stays silent for an unresolved import the bundle would drop anyway', async () => {
+    // Tree-shaken away, so the route serves the page fine (verified: 200). A
+    // probe that reported it would send the reader after a build error that is
+    // not why the page is broken.
+    await Bun.write(join(root, 'entry.ts'), 'import x from "./nowhere";\n');
+
+    expect(await describeShellBuildFailure(root)).toBeNull();
+  });
+
+  test('returns null for a bundle that builds, so the reason stays the status alone', async () => {
+    await Bun.write(join(root, 'entry.ts'), 'console.log("ok");\n');
+
+    expect(await describeShellBuildFailure(root)).toBeNull();
+  });
+
+  test('returns null when there is no shell entrypoint to build', async () => {
+    rmSync(join(root, 'index.html'));
+
+    expect(await describeShellBuildFailure(root)).toBeNull();
+  });
+
+  test('loads the plugins named in bunfig.toml, as the route does', async () => {
+    // A plugin that fails a file the route would bundle: if the probe ignored
+    // bunfig it would report a clean build and hide the real failure.
+    await Bun.write(
+      join(root, 'probe-plugin.ts'),
+      `import type { BunPlugin } from 'bun';
+const plugin: BunPlugin = {
+  name: 'probe',
+  setup(build) {
+    build.onLoad({ filter: /\\.probe\\.ts$/ }, () => ({ contents: 'export const = ;', loader: 'ts' }));
+  },
+};
+export default plugin;
+`,
+    );
+    await Bun.write(join(root, 'bunfig.toml'), '[serve.static]\nplugins = ["./probe-plugin.ts"]\n');
+    await Bun.write(join(root, 'entry.ts'), 'import "./thing.probe";\n');
+    await Bun.write(join(root, 'thing.probe.ts'), 'export const ok = 1;\n');
+
+    expect(await describeShellBuildFailure(root)).not.toBeNull();
+  });
+
+  test('survives a bunfig it cannot parse', async () => {
+    await Bun.write(join(root, 'bunfig.toml'), '[serve.static\nplugins = broken\n');
+    await Bun.write(join(root, 'entry.ts'), 'console.log("ok");\n');
+
+    expect(await describeShellBuildFailure(root)).toBeNull();
+  });
+});

package/src/server/lib/bundler/dependencies.test.ts

@@ -0,0 +1,134 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Every bare import in `src/` must resolve from a published install.
+ *
+ * The bundler plugin (`css.ts`) is **runtime server code**, not build tooling:
+ * `bunfig.toml` names it in `[serve.static].plugins`, so `Bun.serve` loads it
+ * whenever an HTML route is bundled — which is every `ompchamber serve` in
+ * development and every `bun run start`. It therefore has to be loadable from
+ * an install that carries only `dependencies`.
+ *
+ * It was not. `@tailwindcss/postcss` was declared a devDependency and `postcss`
+ * was declared nowhere at all, which no local run could reveal — a source
+ * checkout and the developer's own `bun install` both have the whole tree — but
+ * the published package does not. Measured against a production-only install of
+ * the published tarball: the server came up and answered `503` on every page,
+ * with `error: Failed to load plugins for Bun.serve: Cannot find package
+ * 'postcss'` in its log and nothing in the shell to say why. The same install
+ * from `bun add -g` failed one dependency later on `@tailwindcss/postcss`.
+ *
+ * The invariant is therefore: a module reachable from a runtime entry point may
+ * only import a bare specifier that `dependencies` declares (or a Node/Bun
+ * builtin). `devDependencies` is the wrong home for anything the running server
+ * loads, however build-shaped it looks.
+ *
+ * Scope is deliberately `src/**` rather than "what the bundler reaches": the
+ * published tarball ships all of `src` and the CLI executes from it too, so a
+ * static import anywhere in the tree is a real requirement. Type-only imports
+ * are excluded because `scanImports` erases them — they cost nothing at runtime.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { builtinModules } from 'node:module';
+import { join } from 'node:path';
+
+import { packageRoot } from '@/server/lib/assets/fonts.server';
+
+/** Files whose imports are not part of any runtime path. */
+const EXCLUDED = /\.test\.|\.test-util\.|test-util\./;
+
+/** `@scope/name` keeps two segments; a bare package keeps one. */
+function packageName(specifier: string): string {
+  const segments = specifier.split('/');
+  return specifier.startsWith('@') ? segments.slice(0, 2).join('/') : segments[0];
+}
+
+const BUILTINS = new Set(builtinModules);
+
+/**
+ * Resolved from the running module, not the cwd — the same helper the bundler
+ * plugin uses, so this test answers the same question whether it is run from the
+ * repo root, from `dist/client`, or through `bun test <path>` elsewhere.
+ */
+const ROOT = packageRoot();
+
+const pkg = (await Bun.file(join(ROOT, 'package.json')).json()) as {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+};
+
+const RUNTIME = new Set(Object.keys(pkg.dependencies ?? {}));
+const DEV = new Set(Object.keys(pkg.devDependencies ?? {}));
+
+/**
+ * Bun's transpiler is the parser here, so the answer matches what the bundler
+ * itself sees: `@/` aliases, relative paths and `node:`/`bun:` prefixes are
+ * filtered below, and a type-only import never appears at all.
+ */
+const transpiler = new Bun.Transpiler({
+  loader: 'tsx',
+  tsconfig: readFileSync(join(ROOT, 'tsconfig.json'), 'utf8'),
+});
+
+const sources = [...new Bun.Glob('src/**/*.{ts,tsx,js}').scanSync({ cwd: ROOT })]
+  .filter((file) => !EXCLUDED.test(file));
+
+/** Every bare specifier each file imports, keyed by the file that imports it. */
+async function bareImports(file: string): Promise<string[]> {
+  let imports: Bun.Import[];
+  try {
+    imports = transpiler.scanImports(readFileSync(join(ROOT, file), 'utf8'));
+  } catch {
+    // A shebang line (`src/cli/ompchamber.js`) is not parseable as a module;
+    // its imports are covered by the files it imports.
+    return [];
+  }
+  return imports
+    // `require-call` entries are the JSX runtime Bun injects into the scan, not
+    // a specifier the source names; the runtime itself is `preact`, which is
+    // declared.
+    .filter((entry) => entry.kind !== 'require-call')
+    .map((entry) => entry.path)
+    .filter((path) => !path.startsWith('.') && !path.startsWith('@/'))
+    .filter((path) => !path.startsWith('bun:') && !path.startsWith('node:'))
+    .filter((path) => !BUILTINS.has(packageName(path)));
+}
+
+describe('runtime imports are declared as dependencies', () => {
+  test('no shipped module imports a bare specifier the package does not declare', async () => {
+    const violations: string[] = [];
+
+    for (const file of sources) {
+      for (const specifier of await bareImports(file)) {
+        const name = packageName(specifier);
+        if (RUNTIME.has(name)) continue;
+        violations.push(`${file} imports '${specifier}' — ${DEV.has(name) ? 'declared in devDependencies' : 'not declared in package.json'}`);
+      }
+    }
+
+    // Printed rather than merely counted: the fix is per-specifier, and the
+    // message has to say which list to move it to.
+    expect(violations).toEqual([]);
+  });
+
+  test('the bundler plugin is a runtime dependency of the server', () => {
+    // The specific regression, pinned by name. `bunfig.toml` is what makes the
+    // plugin runtime code, so the two are read together: if the plugin ever
+    // stops being a `serve.static` entry, this assertion is what says the
+    // dependency placement no longer has to hold.
+    const bunfig = Bun.TOML.parse(readFileSync(join(ROOT, 'bunfig.toml'), 'utf8')) as {
+      serve?: { static?: { plugins?: string[] } };
+    };
+    expect(bunfig.serve?.static?.plugins).toContain('./src/server/lib/bundler/css.ts');
+
+    for (const name of ['@tailwindcss/postcss', 'postcss']) {
+      expect(RUNTIME.has(name)).toBe(true);
+      expect(DEV.has(name)).toBe(false);
+    }
+  });
+});

package/src/server/lib/lifecycle/listener.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The HTTP listener this process is serving on.
+ *
+ * Two consumers need it and neither can import it: the shell renderer, which
+ * asks the listener for its own `/_shell` route (Bun renders an HTML route only
+ * while serving), and the dev asset proxy, which asks it for the assets Bun's
+ * own routing table owns. The reference is injected rather than imported because
+ * `index.ts` owns the listener and imports both of them — a direct import would
+ * be a cycle.
+ */
+
+type Listener = { url: URL } | null;
+
+let listener: Listener = null;
+
+/** Called by the server entry once its listener is up. */
+export function setListener(server: { url: URL }): void {
+  listener = server;
+}
+
+/** The listener's base URL, or null before it is up. */
+export function listenerUrl(): URL | null {
+  return listener?.url ?? null;
+}

package/src/server/plugins/shell.server.ts

@@ -19,22 +19,58 @@
  * own routing table rather than Elysia's (verified against Bun 1.4.2). Fetching
  * our own listener is the supported way to obtain the markup.
  *
- * The server reference is injected rather than imported to avoid a cycle:
- * `index.ts` owns the listener and imports `ssrRoutes`, which reaches here.
+ * The listener reference is shared with the dev asset proxy, which needs the
+ * same URL to reach the routes Bun's own table owns — see `lifecycle/listener`.
  */
 
+import { describeShellBuildFailure } from '@/server/lib/bundler/build-errors.server';
 import { SHELL_ROUTE } from '@/server/lib/lifecycle/shell-route';
+import { listenerUrl } from '@/server/lib/lifecycle/listener';
 
-type ShellSource = { url: URL } | null;
-
-let source: ShellSource = null;
+export type ShellRender = { ok: true; html: string } | { ok: false; reason: string };
 
-/** Called by the server entry once its listener is up. */
-export function setShellSource(server: { url: URL }): void {
-  source = server;
+/**
+ * Why the route refused, in the terms of the edit that broke it.
+ *
+ * A status alone is the least useful half of the answer: the route answers 500
+ * because Bun could not bundle the page, and the file, line and message are in
+ * the response — but only inside Bun's "Build Failed" page, which carries them
+ * as a binary payload the page decodes at runtime. So the entrypoint is rebuilt
+ * to obtain them in readable form. See `bundler/build-errors.server` for why
+ * that probe agrees with the route.
+ *
+ * Runs only on a failure, on a page that is already broken.
+ */
+async function shellFailureReason(status: number, markupInvalid = false): Promise<string> {
+  const detail = await describeShellBuildFailure();
+  if (detail) {
+    const reason = markupInvalid ? 'The shell route answered with markup that is not the shell.' : `Shell route answered ${status}.`;
+    return `${reason}\n\nThe client bundle does not build:\n\n${detail}`;
+  }
+  // Markup that is not the shell while the bundle builds cleanly means the
+  // route is serving a CACHED failure: Bun caches the HTML route's output once
+  // in production and never rebuilds it, so the empty body a failed first
+  // request left behind outlives the fix. There is nothing to point at in the
+  // source, and no amount of reloading helps — only a restart does.
+  return 'The shell route answered with markup that is not the shell, and the client bundle builds cleanly.\n\n'
+    + 'In production Bun caches the HTML route\'s output, so a build failure on the first request is cached as an empty page. Restart the server to rebuild it.';
 }
 
-export type ShellRender = { ok: true; html: string } | { ok: false; reason: string };
+/**
+ * The bootstrap marker the SSR route substitutes, and therefore the one string
+ * that proves the markup came from `index.html`.
+ *
+ * A status check alone is not enough, and the gap is not theoretical: with
+ * `development: false` Bun caches the route's output, and a build that failed on
+ * the FIRST request leaves it caching an EMPTY body answered `200`. Every later
+ * request then looks successful, and the substitution below finds nothing to
+ * replace — so the browser gets a blank page with a 200 and no way to tell why.
+ * Measured on Bun 1.4.2: request 1 `500` + empty, requests 2..n `200` + empty,
+ * and it stayed empty after the source was fixed, because the cached output is
+ * never rebuilt in production. The marker turns that into the same actionable
+ * page the development path already produces.
+ */
+export const SHELL_MARKER = '<!--app-bootstrap-->';
 
 /**
  * The current shell markup, or a reason it could not be produced.
@@ -44,11 +80,14 @@ export type ShellRender = { ok: true; html: string } | { ok: false; reason: stri
  * thing that could serve markup pointing at a previous build's asset hashes.
  */
 export async function renderShell(): Promise<ShellRender> {
-  if (!source) return { ok: false, reason: 'The HTTP listener is not up yet.' };
+  const base = listenerUrl();
+  if (!base) return { ok: false, reason: 'The HTTP listener is not up yet.' };
   try {
-    const response = await fetch(new URL(SHELL_ROUTE, source.url));
-    if (!response.ok) return { ok: false, reason: `Shell route answered ${response.status}.` };
-    return { ok: true, html: await response.text() };
+    const response = await fetch(new URL(SHELL_ROUTE, base));
+    if (!response.ok) return { ok: false, reason: await shellFailureReason(response.status) };
+    const html = await response.text();
+    if (!html.includes(SHELL_MARKER)) return { ok: false, reason: await shellFailureReason(response.status, true) };
+    return { ok: true, html };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     return { ok: false, reason: message };