@ultimat3/cli 19.1.3 → 19.3.1

package/src/mcp-host.ts

@@ -3,6 +3,9 @@
 // the gate. The description half is the framework's own `frameworkIntrospection`, so nothing here
 // is a second catalog of routes, entities, actions, queries or jobs.
 
+// why: Bun exposes no path API. Every use here builds a path this host then hands to `Bun.file`
+// or prints inside a `fix:` an operator runs — the dev log, a per-role log, the committed
+// manifest — and string concatenation would answer a different path on a Windows checkout.
 import { join } from 'node:path';
 import { agentActor, isUltimateError, renderThrowable, UltimateError } from '@ultimat3/core';
 import type { DbClient } from '@ultimat3/db';
@@ -42,6 +45,7 @@ import { databaseTarget } from './mcp-db-target';
 import { explainErrorCode } from './mcp-errors';
 import { parseBunTest } from './mcp-test-output';
 import { readMigrations } from './migrations';
+import { retryMemo } from './retry-memo';
 
 export interface DevHostInput {
   readonly root: string;
@@ -88,7 +92,11 @@ export interface LazyServices {
  */
 export function lazyServices(input: DevHostInput): LazyServices {
   const services = resolveServices(input.root, input.env);
-  let started: Promise<RunningServices> | undefined;
+  // `retryMemo`, not `??=`: a boot that REJECTED is not an answer to keep. A Postgres that refused
+  // one connection wedged every later tool call in the session with that first error, and the only
+  // way out was restarting the host — `startServices` unwinds everything it started before it
+  // rejects, so there is nothing left over for a second attempt to collide with.
+  const boot = retryMemo(() => startServices(services, input.env));
   let closed = false;
   return {
     services,
@@ -101,14 +109,14 @@ export function lazyServices(input: DevHostInput): LazyServices {
           fix: 'x mcp serve --transport stdio   # keep the host open for the whole session',
         });
       }
-      started ??= startServices(services, input.env);
-      return started;
+      return boot.get();
     },
     async close(): Promise<void> {
       if (closed) return;
       closed = true;
-      // A boot that rejected has nothing to stop, and close() must not throw on the way out.
-      await (await started?.catch(() => undefined))?.stop();
+      // `started()` and never `get()`: closing must not BOOT a database in order to stop one. A
+      // boot that rejected has nothing to stop, and close() must not throw on the way out.
+      await (await boot.started()?.catch(() => undefined))?.stop();
     },
   };
 }
@@ -172,8 +180,13 @@ export async function readOnlyRows(
 function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities {
   const { root, runner } = input;
   // Layer 1 is seven idempotent DDL statements, and `db.query` is a tool an agent calls in a
-  // loop — resolve the role once per process and reuse the answer, `null` included.
-  let readOnlyRole: Promise<string | null> | undefined;
+  // loop — resolve the role once per process and reuse the answer, `null` included. A FAILED
+  // resolution is not an answer: `??=` kept the rejection, so a statement timeout on the DDL
+  // meant every later `db.query` in the session refused with it instead of trying again.
+  //
+  // It asks `lazy.running()` for the client rather than closing over one: this runs before any
+  // boot has happened, and the boot is memoised, so it is the same connection `runQuery` uses.
+  const readOnlyRole = retryMemo(async () => ensureReadOnlyRole((await lazy.running()).db));
 
   return {
     database: databaseTarget(lazy.services, input.env),
@@ -182,8 +195,7 @@ function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities
       const { db } = await lazy.running();
       // A managed Postgres may refuse CREATE ROLE; `ensureReadOnlyRole` answers null and the
       // layer is reported absent in `guards` rather than quietly assumed present.
-      readOnlyRole ??= ensureReadOnlyRole(db);
-      return readOnlyRows(db, sql, limits, await readOnlyRole);
+      return readOnlyRows(db, sql, limits, await readOnlyRole.get());
     },
 
     async runMigrations(branch: string, dryRun: boolean) {

package/src/parse.ts

@@ -88,6 +88,15 @@ export interface CommandSpec {
    * that declared it and forgot the call ran outside an app with no refusal.
    */
   readonly requiresApp?: boolean;
+  /**
+   * The command hands everything after a bare `--` to another tool, so `ParsedArgs.passthrough`
+   * has a READER. Declared, because it did not until 2026-09 and nothing read it anywhere:
+   * `x test unit -- --coverage --bail` parsed both flags, carried them the whole way and dropped
+   * them, and every other command did the same in the same silence. A command that declares this
+   * forwards them; one that does not refuses the `--` (`X_CLI_BAD_FLAG`), which is the only way an
+   * argument that changes nothing becomes visible to the caller who typed it.
+   */
+  readonly passthrough?: true;
 }
 
 export interface ParsedArgs {
@@ -170,6 +179,14 @@ export function parseArgs(argv: readonly string[], specs: readonly CommandSpec[]
   }
 
   const spec = resolveCommand(first, specs);
+  if (passthrough.length > 0 && spec.passthrough !== true) {
+    throw new BadFlagError({
+      flag: '',
+      command: spec.name,
+      reason: `hands nothing to another tool, so ${passthrough.join(' ')} would be dropped in silence`,
+      fix: `x ${spec.name} --help`,
+    });
+  }
   const flags = defaults(spec);
   const positionals: string[] = [];
   // What argv actually SET, as against what `defaults()` seeded: a default is nobody's request,

package/src/path-segments.ts

@@ -0,0 +1,14 @@
+// One answer to "does this path pass through a directory called X". Six modules asked it with
+// `path.includes('node_modules')`, which is a SUBSTRING match: an app checked out under
+// `~/dev/node_modules-experiments/myapp` answered true for every file it holds, so `loadApp`
+// imported none of them and the app registered nothing at all.
+
+/** Split on either separator: a rule that reads `a/b` and not `a\b` does not exist on Windows. */
+export function pathSegments(path: string): readonly string[] {
+  return path.replaceAll('\\', '/').split('/');
+}
+
+/** Whether any whole segment of `path` is `segment` — never a substring of one. */
+export function hasPathSegment(path: string, segment: string): boolean {
+  return pathSegments(path).includes(segment);
+}

package/src/prerender.ts

@@ -4,7 +4,7 @@
 // only which routes qualify and where the bytes land.
 
 import { join } from 'node:path';
-import { createContext, renderThrowable, runWithContext } from '@ultimat3/core';
+import { createContext, isUltimateError, renderThrowable, runWithContext } from '@ultimat3/core';
 import type { RouteEntry } from '@ultimat3/render';
 import { describeRoutes, routeEntries } from '@ultimat3/render';
 import { renderStatic } from '@ultimat3/render/server';
@@ -21,7 +21,14 @@ import { measurementActor } from './measurement-actor';
 import { loadPwaArtifacts, WEB_MANIFEST_PATH, writePwaIcons } from './pwa-artifacts';
 import type { SkippedRoute, UnmeasuredRoute } from './static-report';
 import { skippedRoute, skipReasonFor, writeStaticReport } from './static-report';
-import { SERVICE_WORKER_PATH, SW_REGISTER_PATH, serviceWorkerArtifacts } from './sw-artifacts';
+import { styleBundle, writeStyles } from './style-bundle';
+import type { RenderedDocument } from './sw-artifacts';
+import {
+  SERVICE_WORKER_PATH,
+  SW_REGISTER_PATH,
+  serviceWorkerArtifacts,
+  serviceWorkerHead,
+} from './sw-artifacts';
 
 // Re-exported, never re-declared: `static-report.ts` owns the shape because the report on disk
 // carries it, and this file already imports that module.
@@ -78,6 +85,8 @@ export interface PrerenderReport {
   readonly report: string;
   /** Client entries emitted, one chunk each. Reported so "which JS shipped?" needs no unzip. */
   readonly islands: readonly string[];
+  /** Surface stylesheets emitted, one file each — the CSS half of the same question. */
+  readonly styles: readonly string[];
   /**
    * What the service worker could not express, and what its precache manifest weighs too much of.
    *
@@ -138,12 +147,23 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   const skipped: SkippedRoute[] = [];
   const routes: RouteStats[] = [];
   const unmeasured: UnmeasuredRoute[] = [];
+  // What the loop below rendered, by the path it rendered — the service worker's precache
+  // revisions. A `Map` and not a record, so a route path spelling a prototype member cannot answer
+  // with one; insertion order is never read, because `pwaRoutes` walks the route table and
+  // `buildPrecacheManifest` sorts its own entries by code unit.
+  const documents = new Map<string, RenderedDocument>();
 
   // Before the first document: a page's `data-x-entry` is a built chunk's URL, so the chunks have
   // to exist to be named. Written into `out` too — a static export is served with no process
   // behind it, so the artifact carries every byte the browser will ask for.
   const islands = await buildIslands(options.root);
   await writeIslands(islands, options.out);
+  // And the stylesheet every document below LINKS. Derived after the island build on purpose:
+  // `islandStylesPlugin` registers an island's own `.module.scss` during `Bun.build`, so a bundle
+  // minted before it would hash CSS the documents do not carry — and the export would publish
+  // pages whose `<link>` names a file the artifact does not have.
+  const styles = styleBundle();
+  await writeStyles(styles, options.out);
   // Same rule, one asset further: a browser asks for `/favicon.ico` on the first page it loads,
   // and a static export has no route to answer it — so the bytes the served surfaces would have
   // returned go into the artifact instead of leaving a 404 in every visitor's console.
@@ -165,18 +185,15 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // wiring exists to close. `undefined` when the app is not installable, and then no document
   // names it either.
   const pwa = await loadPwaArtifacts(options.root);
-  // The worker and its registration script, written as FILES. A static host runs no route table,
-  // so a `<script src="/x-sw-register.js">` in every document is a 404 unless the bytes are in the
-  // artifact — the same promise `favicon.ico` and the icons above keep, for the asset that decides
-  // whether the export works offline at all.
-  const serviceWorker =
-    pwa === undefined
-      ? undefined
-      : serviceWorkerArtifacts({ pwa, buildId, routes: describeRoutes(), islands });
-  if (serviceWorker !== undefined) {
-    await Bun.write(join(options.out, SERVICE_WORKER_PATH.slice(1)), serviceWorker.source);
-    await Bun.write(join(options.out, SW_REGISTER_PATH.slice(1)), serviceWorker.register);
-  }
+  // The registration TAG now, the worker itself after the render loop — the two halves are wanted
+  // at different moments and used to be taken at the same one. Every document below has to name
+  // `/x-sw-register.js`, and the worker's precache manifest is built from the content hash of
+  // those same documents, which do not exist yet: emitted here, every route's revision was the
+  // BUILD ID and every route's byte count was 0, so a deploy of a byte-identical site re-fetched
+  // everything and the precache budget could not count one byte of HTML (`precache.ts`' own
+  // header). `serviceWorkerHead` is the one predicate behind both, so a page can never name a
+  // script the export does not carry.
+  const swHead = pwa === undefined ? undefined : serviceWorkerHead(pwa);
   if (pwa !== undefined) {
     await Bun.write(join(options.out, WEB_MANIFEST_PATH.slice(1)), pwa.body);
     // And the icons that manifest NAMES. A static host runs no `assetRoutes()`, so every
@@ -209,7 +226,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     runWithContext(as, () =>
       routeDocument(entry, data, {
         resolveIsland: (file: string) => islands.resolverFor(file),
-        ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
+        ...(pwa === undefined ? {} : { pwaHead: pwa.head + (swHead ?? '') }),
       }),
     );
   const document = (entry: RouteEntry, data: { url: string; params: Record<string, string> }) =>
@@ -240,7 +257,17 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
       } catch (error) {
         // `renderThrowable`, never `String(error)`: this is a caught unknown, and a hostile
         // `toString` here would take the whole build down instead of one route's measurement.
-        unmeasured.push({ path: entry.path, reason: renderThrowable(error) });
+        // A framework error rides along with its code, cause and fix: `checkBudgets` reports
+        // `X_ISLAND_PROPS_INVALID` under its own name, because that sentence — the island, the
+        // prop, its bytes — is the finding, and `X_BUDGET_UNMEASURED` pointing at this list was
+        // a second command between the author and it.
+        unmeasured.push({
+          path: entry.path,
+          reason: renderThrowable(error),
+          ...(isUltimateError(error)
+            ? { code: error.code, cause: error.cause, fix: error.fix }
+            : {}),
+        });
       }
       continue;
     }
@@ -274,6 +301,11 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
         hash: artifact.hash,
         bytes,
       });
+      // `artifact.hash` is `contentHash(html)` — the same identity that becomes this page's ETag,
+      // so the precache revision and the HTTP validator can never disagree about one document.
+      // Keyed by the FILLED path, which for a non-dynamic route is the declared one; a dynamic
+      // route is not precached as a single URL anyway (`buildPrecacheManifest` skips it).
+      documents.set(artifact.path, { revision: artifact.hash, bytes });
       // Measured from the document that was just written, so the `budgets` step compares a
       // declared budget against bytes that exist on disk rather than against a graph's estimate.
       const measured = await measureDocumentJs(artifact.html, options.out);
@@ -287,6 +319,25 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     }
     if (heaviest !== undefined) routes.push(heaviest);
   }
+  // The worker, LAST: every document it precaches has now been rendered, hashed and weighed. A
+  // static host runs no route table, so both files go into the artifact — a
+  // `<script src="/x-sw-register.js">` in every document is a 404 otherwise, which is the same
+  // promise `favicon.ico` and the icons above keep.
+  const serviceWorker =
+    pwa === undefined
+      ? undefined
+      : serviceWorkerArtifacts({
+          pwa,
+          buildId,
+          routes: describeRoutes(),
+          islands,
+          styles,
+          documents,
+        });
+  if (serviceWorker !== undefined) {
+    await Bun.write(join(options.out, SERVICE_WORKER_PATH.slice(1)), serviceWorker.source);
+    await Bun.write(join(options.out, SW_REGISTER_PATH.slice(1)), serviceWorker.register);
+  }
   const stats = await writeBuildStats(options.root, { routes });
   // Written LAST and by the same call that writes the stats, so an app whose `prerender.ts` does
   // not reach `prerenderSite` produces neither — and `x verify`'s `budgets` step already reds that
@@ -313,6 +364,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     stats,
     report,
     islands: islands.chunks.map((chunk) => chunk.file),
+    styles: styles.chunks.map((chunk) => chunk.url),
     serviceWorkerWarnings: serviceWorker?.warnings ?? [],
   };
 }

package/src/retry-memo.ts

@@ -0,0 +1,37 @@
+// One in-flight attempt, shared — and a FAILED one not kept. `started ??= boot()` caches the
+// rejection with the value, so a Postgres that refused a connection once answered every later
+// call in the session with that same error and no retry was possible short of restarting the host.
+
+/**
+ * A lazily made attempt that may be made again.
+ *
+ * `started()` is the half `??=` has no spelling for: it answers the attempt already in flight or
+ * already made, and `undefined` when nobody has asked yet — so a `close()` can stop what was
+ * booted without BOOTING one in order to stop it.
+ */
+export interface RetryMemo<T> {
+  get(): Promise<T>;
+  started(): Promise<T> | undefined;
+}
+
+/**
+ * `start` runs at most once per SUCCESS. `@ultimat3/db`'s `createPgliteClient` states the rule this
+ * generalises — "a failed boot must not be cached" — and the clearing handler is attached at
+ * creation for the reason that matters: it therefore runs ahead of every caller's own `await`
+ * continuation, so by the time anyone sees the rejection the slot is already empty and the next
+ * call really does start a new attempt. Cleared inside the caller's `catch` instead, there is a
+ * window in which a second call is handed the dead promise.
+ */
+export function retryMemo<T>(start: () => Promise<T>): RetryMemo<T> {
+  let attempt: Promise<T> | undefined;
+  return {
+    get(): Promise<T> {
+      attempt ??= start().catch((error: unknown) => {
+        attempt = undefined;
+        throw error;
+      });
+      return attempt;
+    },
+    started: (): Promise<T> | undefined => attempt,
+  };
+}

package/src/serve.ts

@@ -49,6 +49,8 @@ import { readMigrations } from './migrations';
 import { startOtlpExport } from './otlp-export';
 import { loadPwaArtifacts } from './pwa-artifacts';
 import type { RuntimeOverrides } from './runtime-overrides';
+import { styleBundle } from './style-bundle';
+import { styleRoutes } from './style-routes';
 import { serviceWorkerArtifacts } from './sw-artifacts';
 import { serviceWorkerRoutes } from './sw-routes';
 
@@ -193,7 +195,11 @@ export type StartedApp = ServedApp | MigratedApp;
  * is what fails on it.
  */
 export async function runMigrations(options: ServeOptions): Promise<MigratedApp> {
-  const queue = await startQueue(resolveServices(options.root, options.env), options.runtime);
+  const queue = await startQueue(
+    resolveServices(options.root, options.env),
+    options.runtime,
+    options.env,
+  );
   try {
     const migrations = await readMigrations(options.root);
     const report = await migrate({
@@ -329,7 +335,13 @@ async function bootRoles(boot: {
   const serviceWorker =
     pwa === undefined
       ? undefined
-      : serviceWorkerArtifacts({ pwa, buildId, routes: describeRoutes(), islands });
+      : serviceWorkerArtifacts({
+          pwa,
+          buildId,
+          routes: describeRoutes(),
+          islands,
+          styles: styleBundle(),
+        });
   // The app's own MCP endpoint, through the same call `x dev` makes — see `app-mcp.ts`.
   const mcpMount = await mountAppMcp(options.root);
   const routes: readonly Route[] = [
@@ -344,6 +356,9 @@ async function bootRoles(boot: {
     }),
     ...storageRoutes({ storage: runtime.storage }),
     ...islandRoutes(() => islands),
+    // The surface stylesheets the documents link. Built from the registry the `loadApp` above
+    // filled, so this process serves exactly the CSS it renders against.
+    ...styleRoutes(() => styleBundle()),
     ...appRoutes({
       buildId,
       resolveIsland: (file) => islands.resolverFor(file),

package/src/shot-browser.ts

@@ -8,6 +8,7 @@ import {
   cdpUrlFrom,
   cdpUrlProblem,
   executablePathFrom,
+  ShotChromeMissingError,
 } from './browser-launcher';
 import { BadFlagError } from './errors';
 
@@ -21,7 +22,10 @@ const CDP_FIX = 'x shot / --cdp-url wss://cdp.example.com/session/abc';
 export interface ShotBrowserChoice {
   /** Attach here. When set, nothing about a local executable was read. */
   readonly cdpUrl?: string | undefined;
-  /** Launch this. Already proved to exist on disk. */
+  /**
+   * Launch this. Already proved to exist on disk, and never absent alongside an absent `cdpUrl`:
+   * a run that reached this type has a browser, because the alternative is refused above.
+   */
   readonly executablePath?: string | undefined;
 }
 
@@ -31,6 +35,12 @@ export interface ShotBrowserInput {
   /** `--browser` as typed, before `PUPPETEER_EXECUTABLE_PATH` / `CHROME_PATH`. */
   readonly browserFlag?: string | undefined;
   readonly env: Readonly<Record<string, string | undefined>>;
+  /**
+   * Test seam: how a path is proved to be on disk. Injected rather than stubbed globally, so the
+   * probe below is asserted identically on a machine that has Chrome and on one that does not —
+   * an assertion whose verdict depends on the box it runs on is not an assertion.
+   */
+  readonly exists?: (path: string) => boolean;
 }
 
 /**
@@ -47,8 +57,14 @@ export interface ShotBrowserInput {
  *    the flag IS read.
  * 3. **On an attach, no executable is read at all.** Checking the filesystem for a binary this run
  *    will never execute is how a correct remote capture gets refused on a box with no Chrome.
+ * 4. **A local run with no browser anywhere is refused HERE.** `puppeteer-core` has no bundled
+ *    browser and no default, so "nothing named" is not "the library finds its own" — it is a throw
+ *    from inside somebody else's library, after `runShot` has already booted an embedded Postgres,
+ *    saying ``An `executablePath` or `channel` must be specified``. The same fact is knowable from
+ *    the environment and four filesystem probes before anything starts.
  */
 export function shotBrowserChoice(input: ShotBrowserInput): ShotBrowserChoice {
+  const exists = input.exists ?? browserBinaryExists;
   if (input.cdpFlag !== undefined && input.browserFlag !== undefined) {
     throw new BadFlagError({
       flag: 'cdp-url',
@@ -71,8 +87,11 @@ export function shotBrowserChoice(input: ShotBrowserInput): ShotBrowserChoice {
     }
     return { cdpUrl };
   }
-  const executablePath = executablePathFrom(input.browserFlag, input.env);
-  if (executablePath !== undefined && !browserBinaryExists(executablePath)) {
+  const executablePath = executablePathFrom(input.browserFlag, input.env, exists);
+  // Nothing named and nothing probed: not a bad flag, because no flag was typed — a machine with no
+  // browser on it, which is a configuration to repair rather than a value to correct.
+  if (executablePath === undefined) throw new ShotChromeMissingError();
+  if (!exists(executablePath)) {
     throw new BadFlagError({
       flag: 'browser',
       command: 'shot',
@@ -80,5 +99,5 @@ export function shotBrowserChoice(input: ShotBrowserInput): ShotBrowserChoice {
       fix: 'x shot / --browser /usr/bin/chromium',
     });
   }
-  return executablePath === undefined ? {} : { executablePath };
+  return { executablePath };
 }

package/src/source-files.ts

@@ -2,6 +2,8 @@
 // and an app. One list for every step that walks source, because two steps scanning different sets
 // means a finding one of them can never see.
 
+import { hasPathSegment } from './path-segments';
+
 export const SOURCE_GLOBS = [
   'packages/*/src/**/*.{ts,tsx}',
   // Three packages carry an `e2e` directory beside `src`. It is shipped source by every rule that
@@ -21,7 +23,7 @@ export const SOURCE_GLOBS = [
  * root. `dist/` is build output: the sources that produced it are already in the set.
  */
 export const isVendored = (path: string): boolean =>
-  path.includes('node_modules') || path.includes('/dist/') || path.startsWith('dist/');
+  hasPathSegment(path, 'node_modules') || hasPathSegment(path, 'dist');
 
 /** Emitted declarations, not authored source — a rule about authored code cannot apply to them. */
 export const isGenerated = (path: string): boolean => path.endsWith('.d.ts');

package/src/static-report.ts

@@ -60,6 +60,17 @@ export type UnmeasuredRoute = {
   /** The DECLARED path, as `X_BUDGET_UNMEASURED`'s `at:` spells it, so the two rows join. */
   readonly path: string;
   readonly reason: string;
+  /**
+   * The throwable's own `code`, `cause` and `fix` when the render failed with an `UltimateError`
+   * — absent for a bare `TypeError`. Carried so the `budgets` step can report a failure that IS
+   * an instruction under its own code rather than under `X_BUDGET_UNMEASURED`: an island handed
+   * props over `ISLAND_PROPS_MAX_BYTES` throws `X_ISLAND_PROPS_INVALID` naming the prop and its
+   * bytes, and "run x build, its unmeasured list says why" sent the reader to a second command to
+   * read the sentence this build had already composed.
+   */
+  readonly code?: string;
+  readonly cause?: string;
+  readonly fix?: string;
 };
 
 /** One HTML file in the artifact, and the declared route that produced it. */
@@ -171,8 +182,17 @@ const isSkipped = (value: unknown): value is SkippedRoute =>
   typeof value['why'] === 'string' &&
   inDomain(SKIP_REASONS, value['reason']);
 
+const optionalString = (value: unknown): boolean =>
+  value === undefined || typeof value === 'string';
+
+/** The three coded fields are optional TOGETHER on the way in; a present one must be a string. */
 const isUnmeasured = (value: unknown): value is UnmeasuredRoute =>
-  isRecord(value) && typeof value['path'] === 'string' && typeof value['reason'] === 'string';
+  isRecord(value) &&
+  typeof value['path'] === 'string' &&
+  typeof value['reason'] === 'string' &&
+  optionalString(value['code']) &&
+  optionalString(value['cause']) &&
+  optionalString(value['fix']);
 
 const isEmitted = (value: unknown): value is EmittedPage =>
   isRecord(value) &&

package/src/style-bundle.ts

@@ -0,0 +1,124 @@
+// The surface stylesheet table: the CSS a document on `site/` or `app/` carries, content-hashed
+// and addressed as a FILE rather than inlined into every response. The island table's shape one
+// asset over (`island-bundle.ts`), because the two answer the same question — "what does this
+// document make the browser fetch, and can it keep it?" — and one mechanism is the whole point.
+//
+// Why it stopped being an inline `<style>`: measured against ai-maxxing on 2026-09-06, every
+// `app/` document carried one 156,738-byte block — 1,336 rules from 406 module sources, byte
+// identical across `/`, `/fleet`, `/fleet/[host]` and the session page — inside a response the
+// pipeline sends `Cache-Control: private, no-store`. 92% of the dashboard document and 89% of the
+// session document, re-sent and re-parsed on every navigation, cacheable by nothing.
+
+// Bun ships no path API; `join` is the filesystem side of writing a chunk into a static export.
+// why: Bun exposes no path API — nothing native joins a directory to a URL-shaped path.
+import { join } from 'node:path';
+import type { Surface } from '@ultimat3/render';
+import { SURFACES } from '@ultimat3/render';
+import { contentHash, stylesFor, stylesheetsRevision } from '@ultimat3/render/server';
+
+/**
+ * The surfaces a stylesheet is minted for. `api/` is dropped for `documentSurfaces`' reason — it
+ * emits no document, so a file no `<link>` can ever name would be bytes in the export and an entry
+ * in the precache manifest with no reader. `shared/` stays: `x shot --island` renders an island
+ * that lives there, and `surfaceOf` answers `shared` for it.
+ */
+const STYLED_SURFACES: readonly Surface[] = SURFACES.filter((surface) => surface !== 'api');
+
+/**
+ * Where a surface stylesheet is served from, in `x dev`, in the container and in a static export.
+ * Sits beside `ISLAND_BASE_PATH`, `ICON_BASE_PATH` and `MEDIA_BASE_PATH`, and outside the dev-only
+ * `/_x` namespace for their reason: the URL is baked into documents a static export publishes, so
+ * a dev-only path would be a page that renders in `x dev` and 404s on a CDN.
+ */
+export const STYLE_BASE_PATH = '/styles';
+
+export interface StyleChunk {
+  /**
+   * Every surface whose documents link it, sorted. Usually one — `site/` and `app/` carry
+   * different modules — but an app whose only CSS is its global layer produces one byte string for
+   * all three, and shipping it three times would put three copies in the static export and three
+   * entries in the precache manifest, which has a budget.
+   */
+  readonly surfaces: readonly Surface[];
+  /** Immutable, content-addressed URL. What `<link rel="stylesheet">` carries. */
+  readonly url: string;
+  readonly css: string;
+  readonly bytes: number;
+}
+
+export interface StyleBundle {
+  readonly chunks: readonly StyleChunk[];
+  /** The `href` a document on this surface links, or `undefined` when the surface has no CSS. */
+  hrefFor(surface: Surface | null): string | undefined;
+  /** The chunk a URL names — for serving it, and for writing it into a static export. */
+  chunkAt(url: string): StyleChunk | undefined;
+}
+
+/**
+ * `stylesFor(null)` and `stylesFor('shared')` select the same sheets by construction — a `null`
+ * surface matches only the package sheets, which `'shared'` already carries — so the one chunk
+ * answers both. `island-harness.ts` is the caller that can hold a `null`.
+ */
+const surfaceKey = (surface: Surface | null): Surface => surface ?? 'shared';
+
+/**
+ * Derived, never cached across a change: `stylesheetsRevision()` moves when a sheet's rules move,
+ * and island CSS registers on every `buildIslands` — which `x dev` re-runs on every watcher tick.
+ * Memoised on that revision rather than recomputed per request, because the derivation is a filter
+ * over every registered sheet plus a hash of the ~150 kB it joins.
+ */
+let memo: { readonly revision: number; readonly bundle: StyleBundle } | undefined;
+
+export function styleBundle(): StyleBundle {
+  const revision = stylesheetsRevision();
+  if (memo !== undefined && memo.revision === revision) return memo.bundle;
+  const bundle = styleBundleOf(
+    STYLED_SURFACES.map((surface) => ({ surface, css: stylesFor(surface) })).filter(
+      (sheet) => sheet.css.length > 0,
+    ),
+  );
+  memo = { revision, bundle };
+  return bundle;
+}
+
+/**
+ * Test seam, and the shape `islandBundle` has: a table built from what the caller supplies.
+ *
+ * The URL is the content hash and nothing else — no surface in the name — because a surface is not
+ * a property of the BYTES. Two surfaces with identical CSS are one file, one precache entry and
+ * one download, which is what the name would otherwise prevent. The same `contentHash` that stamps
+ * an ETag, a precache revision and an island chunk: one identity for a byte string, not a fourth.
+ */
+export function styleBundleOf(
+  sheets: readonly { readonly surface: Surface; readonly css: string }[],
+): StyleBundle {
+  const byCss = new Map<string, Surface[]>();
+  for (const sheet of sheets) {
+    const held = byCss.get(sheet.css);
+    if (held === undefined) byCss.set(sheet.css, [sheet.surface]);
+    else held.push(sheet.surface);
+  }
+  const chunks: readonly StyleChunk[] = [...byCss].map(([css, surfaces]) => ({
+    surfaces: [...surfaces].sort(),
+    url: `${STYLE_BASE_PATH}/${contentHash(css)}.css`,
+    css,
+    bytes: new TextEncoder().encode(css).byteLength,
+  }));
+  const bySurface = new Map(
+    chunks.flatMap((chunk) => chunk.surfaces.map((surface) => [surface, chunk] as const)),
+  );
+  const byUrl = new Map(chunks.map((chunk) => [chunk.url, chunk]));
+  return {
+    chunks,
+    hrefFor: (surface: Surface | null): string | undefined =>
+      bySurface.get(surfaceKey(surface))?.url,
+    chunkAt: (url: string): StyleChunk | undefined => byUrl.get(url),
+  };
+}
+
+/** Write every surface stylesheet under a static export, at the URL the documents already carry. */
+export async function writeStyles(bundle: StyleBundle, out: string): Promise<void> {
+  for (const chunk of bundle.chunks) {
+    await Bun.write(join(out, chunk.url.slice(1)), chunk.css);
+  }
+}

package/src/style-csp.ts

@@ -1,19 +1,21 @@
-// Every inline `<style>` body a served process can put in a document, as the `style-src` sources
-// that admit it. Read from the stylesheet registry at boot rather than checked in as a constant:
-// importing the app's modules IS what fills that registry, so a committed hash would describe a
-// stylesheet the document no longer carries — and the CSP would block the framework's own CSS.
+// Every inline `<style>` body a served process can still put in a document, as the `style-src`
+// sources that admit it. The caller names them, because the caller is what knows which documents
+// it mounted.
+//
+// The app's OWN CSS is no longer among them, `As of 2026-09-06`: a surface stylesheet is served as
+// a content-hashed file (`style-bundle.ts`) and a same-origin `<link>` is admitted by the `'self'`
+// already in `@ultimat3/http`'s `style-src`. This function used to hash `stylesFor(surface)` for
+// all four surfaces — 157 kB of CSS hashed at boot to admit a block that is not emitted any more,
+// which is a rule describing a document nobody serves. So a production boot (`serve.ts`, which
+// passes no extras) now extends `style-src` with nothing at all.
 
 import { cspHashSource } from '@ultimat3/http';
-import { SURFACES } from '@ultimat3/render';
-import { stylesFor } from '@ultimat3/render/server';
 
 /**
- * Call AFTER `loadApp`. One hash per distinct body: `stylesFor` is what `dev-render.ts` puts in
- * the tag, per surface, so hashing the same call is the only way the two cannot drift. `extra`
- * carries the documents this package does not render — `/_x`'s shell — because the caller is what
- * knows which of them it mounted.
+ * Call with the inline bodies THIS process emits. `x dev` passes the `/_x` shell's stylesheet and
+ * the screenshot harness's frame style — documents this package renders itself, which no app
+ * surface can see.
  */
-export function inlineStyleSources(extra: readonly string[] = []): readonly string[] {
-  const bodies = [...SURFACES.map((surface) => stylesFor(surface)), ...extra];
+export function inlineStyleSources(bodies: readonly string[] = []): readonly string[] {
   return [...new Set(bodies.filter((body) => body.length > 0).map(cspHashSource))].sort();
 }