@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/server/lib/workspace/register-folder.server.ts

@@ -0,0 +1,78 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Insert one workspace folder row, with the side effects every creation path
+ * owes.
+ *
+ * Two routes create a workspace — `POST /api/folders` (the user named a
+ * directory) and `POST /api/folders/clone` (a repository was cloned into one)
+ * — and the parts that matter are the ones a second copy gets wrong:
+ *
+ * - **The name is unique case-insensitively.** The sidebar lists folders by
+ *   name, so a second folder called `kabmo` beside the first is indistinguishable.
+ * - **A tombstone for the same project path is cleared.** `deleted_workspaces`
+ *   remembers a removed folder so the omp discovery sync does not resurrect
+ *   it; re-adding that path by hand is the user overriding the tombstone, and
+ *   leaving it would make the folder vanish on the next boot. Cleared by
+ *   CANONICAL key, because a tombstone may hold the unresolved spelling of the
+ *   same directory (`/var/...` vs `/private/var/...` on macOS).
+ * - **The skill-discovery watcher set grows with the folder.** A new workspace
+ *   brings its own `.omp/skills` into scope; without the sync a skill created
+ *   there stays invisible to a live session until the server restarts.
+ * - **The sidebar is told.** A folder is structure, so the signal is what
+ *   republishes the list to every open tab.
+ */
+
+import type { DbClient } from '@/server/lib/db/client';
+import { projectPathKey } from '@/server/lib/omp/core/paths';
+import { syncDiscoveryRootsWatch } from '@/server/lib/omp/config/roots-watch.server';
+import { emitRealtimeSignal } from '@/server/lib/realtime/signals.server';
+
+export type RegisterFolderResult =
+  | { ok: true; id: number; name: string }
+  | { ok: false; code: 'duplicate_name'; error: string };
+
+/**
+ * The name a folder is listed under when the caller did not supply one: the
+ * directory's basename, lowercased, so a path-only request still yields a name
+ * the user recognizes.
+ */
+export function defaultFolderName(projectPath: string): string {
+  const withoutTrailing = projectPath.replace(/[\\/]+$/, '');
+  return (withoutTrailing.split(/[\\/]/).pop() ?? '').toLowerCase();
+}
+
+export async function registerWorkspaceFolder(
+  db: DbClient,
+  input: { name: string; projectPath: string | null },
+): Promise<RegisterFolderResult> {
+  const existing = await db.get('SELECT id FROM workspace_folders WHERE lower(name) = lower(?)', [input.name]);
+  if (existing) {
+    return { ok: false, code: 'duplicate_name', error: 'A workspace with this name already exists' };
+  }
+
+  if (input.projectPath) {
+    const target = projectPathKey(input.projectPath);
+    const tombstones = await db.all<{ project_path: string | null }>(
+      'SELECT project_path FROM deleted_workspaces',
+    );
+    for (const row of tombstones) {
+      if (typeof row.project_path !== 'string') continue;
+      if (projectPathKey(row.project_path) !== target) continue;
+      await db.run('DELETE FROM deleted_workspaces WHERE project_path = ?', [row.project_path]);
+    }
+  }
+
+  const result = await db.run(
+    'INSERT INTO workspace_folders (name, is_expanded, project_path) VALUES (?, 1, ?)',
+    [input.name, input.projectPath],
+  );
+
+  void syncDiscoveryRootsWatch();
+  emitRealtimeSignal('sidebar-structure');
+
+  return { ok: true, id: result.lastID, name: input.name };
+}

package/src/server/mock.server.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Utility to determine whether the application is running in MOCK mode.
+ *
+ * - When MOCK=true (or MOCK=1): all data uses mock / simulated presets (demo chat traces, mock token analytics, mock settings presets).
+ * - When MOCK=false (or MOCK=0): all data uses real data (real SQLite persistence, real token calculations, real workspace state).
+ * - Unset (or any unrecognized value) defaults to REAL data — Kabmo is a
+ *   diagnostic console for a live omp install, so demo presets must be opted
+ *   into explicitly rather than inherited by omission.
+ */
+export function isMockMode(): boolean {
+  const envVal = (Bun.env.MOCK || '').trim().toLowerCase();
+
+  return envVal === 'true' || envVal === '1' || envVal === 'on' || envVal === 'yes';
+}
+
+export function getMockModeInfo(): { isMock: boolean; rawEnv: string } {
+  const isMock = isMockMode();
+  return {
+    isMock,
+    rawEnv: Bun.env.MOCK || (isMock ? 'true' : 'false (default)'),
+  };
+}

package/src/server/plugins/compress.ts

@@ -0,0 +1,79 @@
+// node:zlib stays for brotli only — Bun has no brotli API (Bun.brotliCompressSync is undefined).
+import { brotliCompressSync, constants } from 'node:zlib';
+
+/**
+ * Compresses a response body, except `text/event-stream`.
+ *
+ * SSE must never be compressed: zlib holds small frames until its buffer
+ * fills, so a compressed event stream delivers nothing until it ends. This
+ * mirrors the Express `compression({ filter })` it replaces.
+ *
+ * The incoming body is buffered and a fresh `Response` is returned, because a
+ * `Response` body can only be read once — reading it here would otherwise
+ * leave Elysia nothing to send.
+ *
+ * Encodings are offered best-first: zstd, brotli, gzip. On a 905 KiB JSON body
+ * the three measured 0.48 ms / 8 KiB, 1.05 ms / 7 KiB and 2.22 ms / 19 KiB —
+ * zstd is both the fastest and, within 14% of brotli's ratio, effectively as
+ * small, and it stays ahead at every payload size measured (0.004 ms against
+ * 0.007 ms for gzip at 2 KiB). Brotli remains for a client that accepts `br`
+ * but not `zstd`, and gzip is the floor every client has.
+ */
+const MIN_BYTES = 1024;
+
+const COMPRESSIBLE = /^(text\/|application\/(json|javascript|xml|wasm|svg))/;
+
+/** Compression encodings this server can produce, best first. */
+const ENCODINGS = ['zstd', 'br', 'gzip'] as const;
+
+type Encoding = (typeof ENCODINGS)[number];
+
+/**
+ * The best encoding the client accepts, or null.
+ *
+ * Plain substring matching, matching the previous `includes('br')` behavior: a
+ * browser's `Accept-Encoding` is an explicit set of alternatives, not a
+ * preference ordering this server has to weigh.
+ */
+function negotiateEncoding(acceptEncoding: string): Encoding | null {
+  for (const encoding of ENCODINGS) {
+    if (acceptEncoding.includes(encoding)) return encoding;
+  }
+  return null;
+}
+
+function compress(body: Uint8Array<ArrayBuffer>, encoding: Encoding): Uint8Array {
+  if (encoding === 'zstd') return Bun.zstdCompressSync(body, { level: 3 });
+  if (encoding === 'br') {
+    return brotliCompressSync(body, { params: { [constants.BROTLI_PARAM_QUALITY]: 4 } });
+  }
+  return Bun.gzipSync(body, { level: 6 });
+}
+
+export async function maybeCompress(response: Response, acceptEncoding: string | null): Promise<Response> {
+  if (!acceptEncoding) return response;
+  const contentType = response.headers.get('content-type') ?? '';
+  if (contentType.includes('text/event-stream')) return response;
+  if (!COMPRESSIBLE.test(contentType)) return response;
+  if (response.status === 204 || response.status === 304) return response;
+
+  const encoding = negotiateEncoding(acceptEncoding);
+  if (!encoding) return response;
+
+  const buffer = new Uint8Array(await response.arrayBuffer()) as Uint8Array<ArrayBuffer>;
+  if (buffer.byteLength < MIN_BYTES) {
+    // Body already consumed — hand back a rebuilt Response over the same bytes.
+    return rebuild(response, buffer);
+  }
+
+  const compressed = compress(buffer, encoding);
+  const headers = new Headers(response.headers);
+  headers.set('content-encoding', encoding);
+  headers.set('content-length', String(compressed.byteLength));
+  headers.append('vary', 'accept-encoding');
+  return new Response(compressed, { status: response.status, headers });
+}
+
+function rebuild(response: Response, buffer: Uint8Array): Response {
+  return new Response(buffer, { status: response.status, headers: response.headers });
+}

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

@@ -0,0 +1,98 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { composeShellFailureReason, shellBundleRefusal } from '@/server/plugins/shell.server';
+import { SPAWN_CLIFF, hasDescriptorHeadroom } from '@/server/lib/lifecycle/fd-pressure';
+
+const FULL_TABLE = { open: 10_240, highest: 10_239, limit: SPAWN_CLIFF, nearCliff: true };
+const ROOMY_TABLE = { open: 400, highest: 402, limit: SPAWN_CLIFF, nearCliff: false };
+
+/**
+ * The message Bun actually produced on the real condition, kept verbatim: it
+ * names a missing dependency and is what sent the reader to `bun install`.
+ */
+const MISLEADING_DETAIL = 'runtime.ts:32:25  Could not resolve: "@kabmo-labs/kabmo-sdk/app". Maybe you need to "bun install"?';
+
+describe('composeShellFailureReason', () => {
+  test('leads with descriptor exhaustion, not the dependency it blames', () => {
+    const reason = composeShellFailureReason({
+      status: 500,
+      detail: MISLEADING_DETAIL,
+      pressure: FULL_TABLE,
+    });
+
+    // The real cause is the first thing said, and the wrong fix is never
+    // repeated as an instruction.
+    expect(reason.indexOf('out of file descriptors')).toBeLessThan(reason.indexOf('Could not resolve'));
+    expect(reason).toContain('restart the instance');
+    // The build detail survives as evidence, labelled as the consequence.
+    expect(reason).toContain('consequence of the same exhaustion');
+    expect(reason).toContain('@kabmo-labs/kabmo-sdk/app');
+  });
+
+  test('blames the bundle only when the table has room', () => {
+    const reason = composeShellFailureReason({
+      status: 500,
+      detail: MISLEADING_DETAIL,
+      pressure: ROOMY_TABLE,
+    });
+
+    expect(reason).toContain('The client bundle does not build:');
+    expect(reason).not.toContain('out of file descriptors');
+  });
+
+  test('still explains a cached failure when nothing is exhausted and the build is clean', () => {
+    const reason = composeShellFailureReason({ status: 200, markupInvalid: true, detail: null, pressure: null });
+
+    expect(reason).toContain('cached');
+    expect(reason).toContain('Restart the server');
+  });
+
+  test('names exhaustion even when the probe could not report a build error', () => {
+    // The real condition: at the cliff Bun.build fails before it can log a
+    // position, so `describeShellBuildFailure` returns null and the status
+    // alone would have been the whole answer.
+    const reason = composeShellFailureReason({ status: 500, detail: null, pressure: FULL_TABLE });
+
+    expect(reason).toContain('out of file descriptors');
+    expect(reason).toContain('Shell route answered 500.');
+  });
+});
+
+describe('hasDescriptorHeadroom', () => {
+  test('permits work when the probe cannot answer, rather than guessing', () => {
+    expect(hasDescriptorHeadroom(null, 100_000)).toBe(true);
+  });
+
+  test('reserves room for a burst of spawns beyond the work itself', () => {
+    // Exactly the work plus the reserve fits; one descriptor less does not.
+    expect(hasDescriptorHeadroom({ open: 1000, highest: 1000, limit: 2024, nearCliff: false }, 0)).toBe(true);
+    expect(hasDescriptorHeadroom({ open: 1001, highest: 1001, limit: 2024, nearCliff: false }, 0)).toBe(false);
+  });
+});
+
+describe('shellBundleRefusal', () => {
+  test('refuses a dev bundle once the table cannot hold one', () => {
+    // 61440-entry table with 60000 open: a 3600-descriptor bundle plus the
+    // spawn reserve no longer fits, so the build must not be attempted.
+    const tight = { open: 60_000, highest: 60_000, limit: 61_440, nearCliff: true };
+    const refusal = shellBundleRefusal(tight);
+
+    if (Bun.env.NODE_ENV === 'production') {
+      // Production builds ahead of time and holds no graph, so the count is not
+      // what decides whether it can serve.
+      expect(refusal).toBeNull();
+      return;
+    }
+    expect(refusal).toContain('out of file descriptors');
+    expect(refusal).toContain('NOT rebuilt');
+  });
+
+  test('allows the bundle on a healthy table', () => {
+    expect(shellBundleRefusal({ open: 3354, highest: 3354, limit: 61_440, nearCliff: false })).toBeNull();
+  });
+});

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

@@ -0,0 +1,168 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The HTML shell, rendered by Bun's own HTML pipeline.
+ *
+ * The shell used to be a file the bundler wrote and the server read back
+ * (`dist/client/index.html`). It is now a route Bun bundles and renders: the
+ * `index.html` import carries a manifest of hashed assets, and fetching the
+ * shell route returns that markup with the correct script and stylesheet tags
+ * for the current build — which is also what keeps the dev HMR client injected.
+ *
+ * The round-trip through the local listener is deliberate. Bun renders an HTML
+ * route only when serving it, and there is no API to render an `HTMLBundle` in
+ * process: `new Response(bundle)` yields the string "[object HTMLBundle]" and
+ * `app.handle('/_shell')` answers 404, because the route lives in `Bun.serve`'s
+ * 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 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 { countOpenFileDescriptors, describeFdPressure, hasDescriptorHeadroom, type FdPressure } from '@/server/lib/lifecycle/fd-pressure';
+import { DEV_ASSETS_ENABLED } from '@/server/lib/assets/dev-assets.server';
+import { SHELL_ROUTE } from '@/server/lib/lifecycle/shell-route';
+import { listenerFetchOptions, listenerUrl } from '@/server/lib/lifecycle/listener';
+
+export type ShellRender = { ok: true; html: string } | { ok: false; reason: string };
+
+/**
+ * Descriptors one dev bundle of this app needs, measured on the real server:
+ * 13 open on a freshly started process, 3354 after the first page load — a
+ * single build of the client graph, which `development: true` then holds for
+ * the life of the process (bun#40706). Production needs 6 (12 -> 18), because
+ * it builds once ahead of time and holds nothing.
+ *
+ * Deliberately generous rather than exact: the number decides when to REFUSE
+ * work, and refusing a healthy build would be a worse bug than the cascade this
+ * guards against. It is a dev-mode figure only — see `renderShell`.
+ */
+const DEV_BUNDLE_DESCRIPTOR_COST = 3_600;
+
+/**
+ * Whether a bundle may be attempted right now, and the reason when it may not.
+ *
+ * Without this the failure cascades, which is exactly what was observed: the
+ * build dies partway, so the browser is handed a bundle that cannot run, the
+ * dev client reloads, and each attempt drives the table further down until
+ * every spawn in the process fails. One refusal that names the real state is
+ * worth more than a build that half-succeeds into a broken page.
+ *
+ * Production is exempt by construction: it bundles ahead of time and holds no
+ * graph, so a descriptor count is not the thing that decides whether it can
+ * serve — and `Bun.serve` caches the HTML route's output there anyway.
+ */
+export function shellBundleRefusal(pressure: FdPressure | null): string | null {
+  if (!DEV_ASSETS_ENABLED) return null;
+  if (hasDescriptorHeadroom(pressure, DEV_BUNDLE_DESCRIPTOR_COST)) return null;
+  const detail = describeFdPressure(pressure) ?? 'The descriptor table is nearly full.';
+  return `${detail} The page was NOT rebuilt, because a client bundle needs about `
+    + `${DEV_BUNDLE_DESCRIPTOR_COST} descriptors and attempting it at this point fails partway — `
+    + `which is what leaves the browser reloading a bundle that cannot run.`;
+}
+
+/**
+ * Why the shell would not render, from the two facts that can explain it.
+ *
+ * Descriptor exhaustion comes first, and it has to: a truncated table makes the
+ * bundle fail with messages that name the wrong cause entirely. Measured on the
+ * real condition (a dev server past Darwin's 10,240-descriptor cliff) — Bun
+ * reports the file reads it could not do as
+ * `Could not resolve: "@kabmo-labs/kabmo-sdk/app". Maybe you need to "bun install"?`,
+ * which sends the reader to reinstall a dependency that is present and correct
+ * while the actual fix is a restart. The build detail is still printed under it,
+ * because it is the evidence, but it is labelled as the consequence it is.
+ *
+ * Pure so the composition can be pinned without reproducing a full table.
+ */
+export function composeShellFailureReason(input: {
+  status: number;
+  markupInvalid?: boolean;
+  detail: string | null;
+  pressure: FdPressure | null;
+}): string {
+  const pressure = describeFdPressure(input.pressure);
+  if (pressure) {
+    const head = input.markupInvalid
+      ? 'The shell route answered with markup that is not the shell.'
+      : `Shell route answered ${input.status}.`;
+    const detail = input.detail
+      ? `\n\nThe client bundle could not be built, which is a consequence of the same exhaustion:\n\n${input.detail}`
+      : '';
+    return `${head}\n\n${pressure}${detail}`;
+  }
+  if (input.detail) {
+    const reason = input.markupInvalid ? 'The shell route answered with markup that is not the shell.' : `Shell route answered ${input.status}.`;
+    return `${reason}\n\nThe client bundle does not build:\n\n${input.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.';
+}
+
+/**
+ * The reason for the current failure: the descriptor table is read FIRST,
+ * because when it is exhausted every other symptom is downstream of it.
+ *
+ * Runs only on a failure, on a page that is already broken.
+ */
+async function shellFailureReason(status: number, markupInvalid = false): Promise<string> {
+  const pressure = countOpenFileDescriptors();
+  const detail = await describeShellBuildFailure();
+  return composeShellFailureReason({ status, markupInvalid, detail, pressure });
+}
+
+/**
+ * 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.
+ *
+ * Never cached: Bun re-renders the route per request in development, and in
+ * production the manifest is already in memory — a cache here would be the one
+ * thing that could serve markup pointing at a previous build's asset hashes.
+ */
+export async function renderShell(): Promise<ShellRender> {
+  const base = listenerUrl();
+  if (!base) return { ok: false, reason: 'The HTTP listener is not up yet.' };
+  // Checked BEFORE the fetch, because the fetch is what makes Bun bundle the
+  // page: past this point the damage is already done, and the browser has been
+  // handed a bundle it will reload forever. See `shellBundleRefusal`.
+  const refusal = shellBundleRefusal(countOpenFileDescriptors());
+  if (refusal) return { ok: false, reason: refusal };
+  try {
+    // `listenerFetchOptions()` carries the TLS bypass under `--tls`: this is the
+    // process asking its own listener, and its self-signed certificate would
+    // otherwise fail the handshake and render "Shell not available" on every page.
+    const response = await fetch(new URL(SHELL_ROUTE, base), listenerFetchOptions());
+    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 };
+  }
+}

package/src/server/plugins/ssr.ts

@@ -0,0 +1,199 @@
+import { Elysia } from 'elysia';
+import { getDb } from '@/server/db.server';
+import { isAuthEnabled, isAuthenticatedRequest } from '@/server/lib/auth/guard';
+import { tryServeStatic } from '@/server/plugins/static';
+import { renderShell, SHELL_MARKER } from '@/server/plugins/shell.server';
+import {
+  DEV_ASSETS_ENABLED,
+  devAssetUpstreamPath,
+  rewriteDevAssetUrls,
+  serveDevAsset,
+} from '@/server/lib/assets/dev-assets.server';
+import { listenerFetchOptions, listenerUrl } from '@/server/lib/lifecycle/listener';
+import { FONT_STYLESHEET_ROUTE } from '@/server/lib/assets/font-css.server';
+import { readSettingsBlob } from '@/shared/lib/settings/keys';
+import { resolveTheme } from '@/shared/lib/theme/catalog';
+import { windowChromeColor } from '@/shared/lib/theme/chrome';
+import { THEME_STYLE_ELEMENT_ID, themeStyleSheet } from '@/shared/lib/theme/css';
+
+/** HTML-escape a string for interpolation into the failure page's `<pre>`. */
+function escapeHtmlText(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/**
+ * Actionable message instead of a bare 500 when the shell cannot be rendered.
+ *
+ * The shell is a Bun HTML route now, not a file on disk, so "not found" is no
+ * longer the failure mode — a bundle error is, and Bun renders its own error
+ * page for that, with the file and line locked inside a payload only the
+ * browser can decode. `plugins/shell.server.ts` rebuilds the entrypoint to get
+ * those facts in readable form and passes them here as the reason, so this page
+ * names the edit that broke the bundle rather than the status it produced.
+ */
+function shellUnavailableResponse(reason: string): Response {
+  // Escaped, not interpolated raw: the reason carries the failed build's own
+  // source lines, which are arbitrary code — a `<` in one would otherwise
+  // truncate the page at the first tag.
+  return new Response(
+    `<!doctype html><meta charset="utf-8"><title>Kabmo</title>
+<body style="font:14px/1.6 ui-monospace,monospace;padding:2rem">
+<h1 style="font-size:1.1rem">Shell not available</h1>
+<p>The server could not render its HTML shell.</p>
+<pre style="background:#f4f1ea;padding:1rem;border-radius:6px">${escapeHtmlText(reason)}</pre>
+</body>`,
+    { status: 503, headers: HTML_HEADERS },
+  );
+}
+
+async function readSettings(): Promise<Record<string, unknown>> {
+  try {
+    const db = await getDb();
+    const rows = await db.all<{ key: string; value: string }>('SELECT * FROM app_settings');
+    const settings: Record<string, unknown> = {};
+    for (const row of rows) {
+      try {
+        settings[row.key] = JSON.parse(row.value);
+      } catch {
+        settings[row.key] = row.value;
+      }
+    }
+    return settings;
+  } catch {
+    return {};
+  }
+}
+
+const MOBILE_UA = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini|Mobile|mobile|CriOS/i;
+
+/**
+ * The HTML shell is generated per request, so its cacheability is declared
+ * rather than left to the browser's heuristics.
+ *
+ * It is not a static file: the theme and the bootstrap settings are injected on
+ * every request, and its only link to the bundle is a content hash inside the
+ * markup. A copy that outlives its build does not merely go stale — it points at
+ * an asset hash the build no longer emits, leaving the page running previous
+ * code with nothing in the response to signal it.
+ *
+ * Chrome does not currently cache it: the response carries no `Cache-Control`,
+ * `Last-Modified` or `ETag`, so there is no freshness to heuristically derive
+ * and every navigation re-fetches (measured: a second load of the shell reported
+ * the full 41 KB `transferSize`). That is the behaviour this header makes
+ * explicit — the day a validator is added for the template, heuristic caching
+ * would start and nothing else here would prevent it.
+ *
+ * `no-store` rather than `no-cache`: with no validator there is nothing to
+ * revalidate against, so a stored copy is never usable.
+ */
+const SHELL_CACHE = 'no-store';
+
+const HTML_HEADERS = {
+  'content-type': 'text/html; charset=utf-8',
+  'cache-control': SHELL_CACHE,
+  // The shell is served to anyone — it has to be, since it renders the login
+  // screen — so a crawler that finds a password-protected instance would index
+  // its title and structure. `/robots.txt` states the intent; this header is
+  // what actually enforces it, because robots.txt is advisory and only read by
+  // crawlers that choose to.
+  'x-robots-tag': 'noindex, nofollow',
+} as const;
+
+/** `/robots.txt` — the explicit half of the no-index rule above. */
+const ROBOTS_TXT = 'User-agent: *\nDisallow: /\n';
+
+export const ssrRoutes = new Elysia({ name: 'ssr' }).get('*', async ({ request }) => {
+  const pathname = new URL(request.url).pathname;
+
+  if (pathname === '/robots.txt') {
+    return new Response(ROBOTS_TXT, {
+      headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'public, max-age=3600' },
+    });
+  }
+
+  if (pathname.startsWith('/api/')) {
+    return new Response(JSON.stringify({ error: 'Not found' }), {
+      status: 404,
+      headers: { 'content-type': 'application/json; charset=utf-8' },
+    });
+  }
+
+  // The dev asset proxy, before the static lookup: its prefix is this server's
+  // own, and Bun's table never sees it. See `lib/assets/dev-assets.server`.
+  if (DEV_ASSETS_ENABLED && devAssetUpstreamPath(pathname)) {
+    const base = listenerUrl();
+    if (base) {
+      // The fetch options ride along for the same reason `renderShell` needs
+      // them: under `--tls` this is an HTTPS request to the server's own
+      // self-signed listener.
+      const proxied = await serveDevAsset(request, pathname, base, listenerFetchOptions());
+      if (proxied) return proxied;
+    }
+  }
+
+  const asset = await tryServeStatic(pathname, request);
+  if (asset) return asset;
+
+  // An unauthenticated visitor still gets the shell — it IS the login screen —
+  // but not the settings map. `appSettings` carries the provider registry, the
+  // theme and every stored preference, and publishing it to whoever can reach
+  // the port would hand out exactly what the password protects. The client
+  // answers "is auth required" from `/api/auth/state` and renders the login
+  // screen without it.
+  const authenticated = isAuthenticatedRequest(request);
+  const settings = authenticated ? await readSettings() : {};
+  // Both blobs, legacy beneath: an install that predates the rename still has
+  // its theme in the old row, and the SSR shell is what paints the first frame.
+  const settingsBlob = readSettingsBlob(settings) as { theme?: string };
+  // Resolved through the catalog: an id this build no longer ships (a
+  // downgrade, the retired `noir` alias) renders the default palette instead of
+  // an unstyled page.
+  const theme = resolveTheme(settingsBlob.theme);
+  const initialIsMobile = MOBILE_UA.test(request.headers.get('user-agent') ?? '');
+
+  const rendered = await renderShell();
+  if (!rendered.ok) return shellUnavailableResponse(rendered.reason);
+
+  // `production` is the same predicate the dev-asset proxy runs on
+  // (`NODE_ENV !== 'production'`), so the client's dev-only chrome and the
+  // server's dev-only asset route can never disagree about which build this is.
+  // `authEnabled` travels beside `authenticated` because they answer different
+  // questions: "this browser has a session" versus "there is a session to have".
+  // A Kabmo running open answers `authenticated: true` for every visitor, so
+  // the navbar cannot use it to decide whether a sign-out control applies.
+  const bootstrap = JSON.stringify({ initialIsMobile, authenticated, authEnabled: isAuthEnabled(), production: !DEV_ASSETS_ENABLED, appSettings: settings }).replace(/</g, '\\u003c');
+  // The template's own `<meta name="theme-color">` is REWRITTEN, not joined by
+  // a second tag: with both present Chrome reads the first one, so an appended
+  // tag would leave a dark theme painting light browser chrome.
+  const themeStyle = `<style id="${THEME_STYLE_ELEMENT_ID}">${themeStyleSheet()}</style>`;
+  // The chrome color has to match the surface at the TOP of the window, which
+  // is per-layout (`shared/lib/theme/chrome.ts`); this request already knows the
+  // two facts behind it. The login screen is the shell too, and paints canvas.
+  const chrome = windowChromeColor(theme, { isMobile: initialIsMobile, authRequired: !authenticated });
+  // The font faces are a stylesheet the bundler cannot carry: Bun resolves every
+  // local `url()` in CSS, so a bundled face is either base64 or an absolute
+  // filesystem path. `lib/bundler/css.ts` strips the blocks out of the bundle
+  // and `lib/assets/font-css.server.ts` re-declares them on the route below,
+  // which is why the link is injected here — a `<link href="/fonts.css">` in
+  // index.html would be resolved by the HTML loader and fail the same way.
+  const fontLink = `<link rel="stylesheet" href="${FONT_STYLESHEET_ROUTE}">`;
+
+  // Bun's dev asset URLs move to this server's prefix so the proxy above can add
+  // the caching headers Bun omits. Rewritten BEFORE the bootstrap is injected,
+  // so a `/_bun/` string inside the settings payload is left alone.
+  const shellHtml = DEV_ASSETS_ENABLED ? rewriteDevAssetUrls(rendered.html) : rendered.html;
+
+  return new Response(
+    shellHtml
+      .replace('data-theme="paper"', `data-theme="${theme.id}"`)
+      .replace('data-theme-variant="light"', `data-theme-variant="${theme.variant}"`)
+      .replace('<meta name="theme-color" content="#faf8f3" />', `<meta name="theme-color" content="${chrome}" />`)
+      .replace('<!--app-head-->', themeStyle + fontLink)
+      .replace(SHELL_MARKER, `<script>window.__OMP_BOOTSTRAP__=${bootstrap}</script>`),
+    { headers: HTML_HEADERS },
+  );
+});