@ultimat3/cli 20.2.0 → 21.0.0

package/src/island-realtime.ts

@@ -0,0 +1,91 @@
+// Realtime installed for the author, on exactly the islands that use it: an island whose own import
+// graph reaches `@ultimat3/realtime` is built from a virtual entry that first calls
+// `installRealtime({ signal: createSignal })` with THIS bundle's solid-js, then re-exports the
+// island whole. Every other island is built from its own file and pays nothing (plan 101 slice 14).
+
+// why: Bun ships no path API; the entry is joined to the root and resolved from its directory.
+import { dirname, join } from 'node:path';
+import type { BunPlugin } from 'bun';
+import { firstInGraph } from './live-routes';
+
+/** What `Bun.build` is handed for a realtime island; resolved by `islandRealtimePlugin`. */
+export const REALTIME_ISLAND_ENTRY = 'ultimate:island-entry';
+
+const REALTIME = '@ultimat3/realtime';
+const NAMESPACE = 'ultimate-island';
+const INSTALL = 'ultimate:island-realtime';
+const MODULE = 'ultimate:island-module';
+
+/**
+ * Whether the island's own graph value-imports realtime. Relative specifiers only, which is the
+ * one blind spot: a PACKAGE importing realtime for the island is not seen, and a hook it calls
+ * then throws `X_REALTIME_UNINSTALLED` by name — loud, never silent.
+ */
+export async function reachesRealtime(root: string, file: string): Promise<boolean> {
+  const found = await firstInGraph(root, file, (source, path) => {
+    // The transpiler, not a regex: it erases `import type` and reads a re-export as an import.
+    const scanned = new Bun.Transpiler({ loader: path.endsWith('x') ? 'tsx' : 'ts' }).scanImports(
+      source,
+    );
+    return scanned.some((entry) => entry.path === REALTIME) ? true : undefined;
+  });
+  // Recorded with the answer, so the document renderer can ask it of a page's islands without a
+  // second graph walk per request. Every build re-asks, so an edit that drops realtime drops it.
+  if (found === true) realtimeIslands.add(file);
+  else realtimeIslands.delete(file);
+  return found === true;
+}
+
+/** App-root-relative island files whose graph reaches realtime, as the last build answered. */
+const realtimeIslands = new Set<string>();
+
+/**
+ * The islands (app-root-relative POSIX paths) the last build found reaching realtime. A page needs
+ * realtime's page boot only if one of ITS islands does — `settings` paid 34.9 kB of boot script
+ * for an island that never touched a record.
+ */
+export function realtimeIslandFiles(): ReadonlySet<string> {
+  return realtimeIslands;
+}
+
+/**
+ * `export *` and never a named list: the hydration runtime reads `mount` off the module, and the
+ * wrapper must not decide which of an island's names survive. The install is imported FIRST, so it
+ * has run before the island's module body — and every hook the island calls — does.
+ */
+const ENTRY_SOURCE = `import '${INSTALL}';\nexport * from '${MODULE}';\n`;
+
+/**
+ * The install resolves `@ultimat3/realtime` from the ISLAND's own directory — the resolution the
+ * island itself gets — so the bundle holds one copy and the signal lands where the hooks read it.
+ * `solid-js` goes through `island-solid-dedupe.ts` like every other import in the graph.
+ */
+const INSTALL_SOURCE = (realtime: string): string =>
+  `import { installRealtime } from ${JSON.stringify(realtime)};\n` +
+  `import { createSignal } from 'solid-js';\n` +
+  `installRealtime({ signal: createSignal });\n`;
+
+export function islandRealtimePlugin(root: string, file: string): BunPlugin {
+  const island = join(root, file);
+  return {
+    name: 'ultimate-island-realtime',
+    setup(build) {
+      build.onResolve({ filter: /^ultimate:island-entry$/ }, () => ({
+        path: 'entry',
+        namespace: NAMESPACE,
+      }));
+      build.onResolve({ filter: /^ultimate:island-realtime$/ }, () => ({
+        path: 'install',
+        namespace: NAMESPACE,
+      }));
+      build.onResolve({ filter: /^ultimate:island-module$/ }, () => ({ path: island }));
+      build.onLoad({ filter: /.*/, namespace: NAMESPACE }, (args) => ({
+        contents:
+          args.path === 'entry'
+            ? ENTRY_SOURCE
+            : INSTALL_SOURCE(Bun.resolveSync(REALTIME, dirname(island))),
+        loader: 'js',
+      }));
+    },
+  };
+}

package/src/island-solid-dedupe.ts

@@ -0,0 +1,108 @@
+// One Solid runtime per island chunk: the app's. Every `solid-js` specifier in the island's graph
+// — the entry's own `render` from `solid-js/web`, and the `solid-js/web` helpers the JSX
+// transform writes into every `@ultimat3/ui` component — resolves to the copy the APP installed.
+//
+// Without this, `Bun.build` resolves each import from the importing file's REAL path. A package
+// reached through a symlink (`file:` overrides, `bun link`, a workspace with its own install)
+// resolves `solid-js` from its own `node_modules`, and the chunk ships two runtimes: measured on
+// the scaffold's theme-toggle island under CI's own `file:` links, 62,463 B against 50,042 B with
+// one (issue #490). Two copies are also two reactive graphs — a context created by one is never
+// found by the other's `useContext` — so the dedupe is a correctness rule that happens to be the
+// biggest single cut in the chunk, not a size trick.
+
+// why: Bun ships no path API; `dirname` recovers the package directory from the manifest path
+// `Bun.resolveSync` answers, and `join` puts an export target under it.
+import { dirname, join } from 'node:path';
+import type { BunPlugin } from 'bun';
+
+const SOLID_PACKAGE = 'solid-js';
+
+/** `solid-js` and every subpath of it — `solid-js/web`, `solid-js/store`, `solid-js/h`. */
+export const SOLID_SPECIFIER = /^solid-js(?:\/.*)?$/;
+
+/**
+ * The conditions an island is built under, in the order they are tried: `browser` because the
+ * chunk runs there, `import` because it is ESM, `default` as the map's own fallback. NOT
+ * `development` — `island-bundle.ts` defines `process.env.NODE_ENV` as `"production"` for the
+ * same reason, and solid nests `development` INSIDE `browser`, so walking without it is what
+ * selects `dist/solid.js` over `dist/dev.js`.
+ */
+const BROWSER_CONDITIONS: readonly string[] = ['browser', 'import', 'default'];
+
+/** `solid-js` → `.`, `solid-js/web` → `./web`: the key the package's `exports` map uses. */
+export function solidSubpath(specifier: string): string {
+  return specifier === SOLID_PACKAGE ? '.' : `.${specifier.slice(SOLID_PACKAGE.length)}`;
+}
+
+/**
+ * The target one `exports` entry names under the conditions above — depth-first, in the map's
+ * own key order, which is how Node and Bun read a conditions object. A string is a target; a
+ * nested object is walked; a condition the island does not build under (`node`, `worker`,
+ * `require`, `types`, `development`) is skipped. `undefined` when nothing matched, and the
+ * caller then leaves the specifier to Bun's own resolver rather than guessing.
+ */
+export function conditionTarget(entry: unknown): string | undefined {
+  if (typeof entry === 'string') return entry;
+  if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) return undefined;
+  for (const [condition, nested] of Object.entries(entry)) {
+    if (!BROWSER_CONDITIONS.includes(condition)) continue;
+    const target = conditionTarget(nested);
+    if (target !== undefined) return target;
+  }
+  return undefined;
+}
+
+export interface AppSolid {
+  /** The installed package's directory — where every export target is joined onto. */
+  readonly dir: string;
+  /** Its `exports` map, verbatim. */
+  readonly exports: unknown;
+}
+
+/**
+ * The `solid-js` the app installed, found the way the app's own entry would find it: from the app
+ * root upward. `null` when there is none — an app with no islands never gets here, and an island
+ * importing solid where none is installed fails the build in Bun's own words either way.
+ */
+export async function resolveAppSolid(root: string): Promise<AppSolid | null> {
+  let manifest: string;
+  try {
+    manifest = Bun.resolveSync(`${SOLID_PACKAGE}/package.json`, root);
+  } catch {
+    return null;
+  }
+  const parsed = (await Bun.file(manifest).json()) as { readonly exports?: unknown };
+  return { dir: dirname(manifest), exports: parsed.exports };
+}
+
+/** Where `specifier` lands in the app's own copy, or `undefined` to leave it to Bun. */
+export function appSolidPath(solid: AppSolid, specifier: string): string | undefined {
+  const exports = solid.exports;
+  if (exports === null || typeof exports !== 'object') return undefined;
+  const entry = Object.hasOwn(exports, solidSubpath(specifier))
+    ? (exports as Record<string, unknown>)[solidSubpath(specifier)]
+    : undefined;
+  const target = conditionTarget(entry);
+  return target === undefined ? undefined : join(solid.dir, target);
+}
+
+/**
+ * The plugin `island-bundle.ts` installs FIRST, so it sees every `solid-js` specifier before the
+ * JSX and style plugins do. Resolved once per build and cached: the map is read from disk at
+ * most one time however many modules import solid.
+ */
+export function solidDedupePlugin(root: string): BunPlugin {
+  let app: Promise<AppSolid | null> | null = null;
+  return {
+    name: 'ultimate-solid-dedupe',
+    setup(build): void {
+      build.onResolve({ filter: SOLID_SPECIFIER }, async (args) => {
+        app ??= resolveAppSolid(root);
+        const solid = await app;
+        if (solid === null) return undefined;
+        const path = appSolidPath(solid, args.path);
+        return path === undefined ? undefined : { path };
+      });
+    },
+  };
+}

package/src/island-verdict.ts

@@ -57,7 +57,7 @@ export interface IslandReadiness {
   /**
    * `"WS <url>"` / `"SSE <url>"` for every socket a component constructed — recorded, never
    * gating. The harness's stand-in is inert (constructs, never opens, `close()` is a no-op), so
-   * a component dialing `@ultimat3/realtime`'s `LiveClient.connect()` does not fail the state it
+   * a component whose page socket dials `/_x/sync` (`@ultimat3/realtime`) does not fail the state it
    * is mounted in; this is the fact a picture cannot carry about that.
    */
   readonly sockets: readonly string[];

package/src/live-routes.ts

@@ -12,29 +12,35 @@ import { join, posix } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { RouteEntry } from '@ultimat3/render';
 import { ISLAND_EXTENSION, routeEntries } from '@ultimat3/render';
+import { discoverIslands } from './island-bundle';
 import type { Finding } from './output';
 
 /**
- * The exports that only work with a registered `LiveClient`. Each one either subscribes, mutates
- * or reads the connection, so a module naming one is a module that needs a browser to have booted
- * it — `hasLiveClient` and `LiveClient` itself are deliberately absent: the first IS the guard, and
- * the second is what an island's `mount()` constructs.
+ * The exports that only work in a booted browser page: each one reads the page's store, its socket
+ * or its connection, so a module naming one needs an island to have run it. `hasPageSocket` is
+ * deliberately absent — it IS the guard — and so is `installRealtime`, which the island bundle
+ * writes for the author (plan 101, slice 14).
  */
 export const LIVE_HOOKS = [
-  'useLive',
-  'liveHookFor',
+  'useQuery',
   'useConnection',
   'useMutation',
   'useMutationQueue',
+  'useRecord',
+  'useChannel',
 ] as const;
 
 /**
- * The one escape hatch, and it is a call an author writes on purpose: a module that ASKS whether
- * there is a client has already written what happens when there is none. `app/update-banner.tsx`
- * in the reference app is the shape — imported by the layout, so by every page, and correct on all
- * of them.
+ * NOT an escape hatch, `As of 2026-09-22`: `hasPageSocket()` answers false on the server, every
+ * time, so a module that guards on it and never runs in a browser renders nothing forever. It was
+ * exempted here — "a module that asks has handled the absence" — and that is exactly how
+ * `examples/dummy`'s update banner, in a layout no island imports, never showed "A new version is
+ * ready.". It is a browser-only read like any hook, so it is reported like one.
  */
-const GUARD = 'hasLiveClient';
+const GUARD = 'hasPageSocket';
+
+/** Everything that only means something in a booted browser page: the hooks, and the guard. */
+const BROWSER_ONLY: readonly string[] = [GUARD, ...LIVE_HOOKS];
 
 /** Value imports only: `import type` is erased, so it boots nothing and needs nothing. */
 const REALTIME_IMPORT = /import\s+([^;]*?)from\s*['"]@ultimat3\/realtime(?:\/[\w-]+)?['"]/g;
@@ -45,18 +51,14 @@ const bindingsOf = (clause: string): readonly string[] =>
     .map((entry) => entry.split(/\bas\b/)[0]?.trim() ?? '')
     .filter((name) => name.length > 0 && !name.startsWith('type '));
 
-/**
- * Which live hooks one module imports, or `[]` — including for a module that guards, which is a
- * per-FILE verdict on purpose: the guard is written next to the read it protects.
- */
+/** Which browser-only reads one module imports — the hooks and `hasPageSocket` — or `[]`. */
 export function liveHooksIn(source: string): readonly string[] {
   const hooks: string[] = [];
   for (const match of source.matchAll(REALTIME_IMPORT)) {
     const clause = match[1] ?? '';
     if (clause.trimStart().startsWith('type ')) continue;
     const names = bindingsOf(clause);
-    if (names.includes(GUARD)) return [];
-    for (const hook of LIVE_HOOKS) if (names.includes(hook)) hooks.push(hook);
+    for (const hook of BROWSER_ONLY) if (names.includes(hook)) hooks.push(hook);
   }
   return hooks;
 }
@@ -88,14 +90,18 @@ export interface LiveReach {
 }
 
 /**
- * Walk the route module's own import graph and answer the first live hook in it.
+ * Walk a module's own import graph and answer the first thing `probe` finds in it.
  *
  * Relative specifiers only. A bare one resolves through `node_modules` or a workspace name, and
  * following either would mean guessing which package a name came from — the limit `fix-imports.ts`
  * records for the same walk. So this UNDER-reports rather than over-reports: a finding here is
  * always a real one, which is what lets the rule ship with no pin table.
  */
-export async function liveReachOf(root: string, file: string): Promise<LiveReach | undefined> {
+export async function firstInGraph<T>(
+  root: string,
+  file: string,
+  probe: (source: string, path: string) => T | undefined,
+): Promise<T | undefined> {
   const seen = new Set<string>();
   const queue = [file];
   while (queue.length > 0) {
@@ -104,8 +110,8 @@ export async function liveReachOf(root: string, file: string): Promise<LiveReach
     seen.add(next);
     const module = await readModule(root, next);
     if (module === undefined) continue;
-    const hook = liveHooksIn(module.source)[0];
-    if (hook !== undefined) return { at: module.path, hook };
+    const found = probe(module.source, module.path);
+    if (found !== undefined) return found;
     const loader = module.path.endsWith('x') ? 'tsx' : 'ts';
     // Bun's transpiler is the parser, exactly as in `scripts/boundaries.ts`: it erases type-only
     // imports and finds the dynamic ones, which no regex over this source could do.
@@ -117,6 +123,36 @@ export async function liveReachOf(root: string, file: string): Promise<LiveReach
   return undefined;
 }
 
+/** Every module in a file's relative import graph, app-root-relative — one walk, no probe. */
+export async function graphModules(root: string, file: string): Promise<ReadonlySet<string>> {
+  const seen = new Set<string>();
+  await firstInGraph(root, file, (_source, path) => {
+    seen.add(path);
+    return undefined;
+  });
+  return seen;
+}
+
+/** Every module a browser can run: the union of every island's graph in the app. */
+async function islandModules(root: string): Promise<ReadonlySet<string>> {
+  const modules = new Set<string>();
+  for (const island of await discoverIslands(root)) {
+    for (const path of await graphModules(root, island)) modules.add(path);
+  }
+  return modules;
+}
+
+/** Each module in the route's graph that reads a browser-only name, with the first name it reads. */
+async function browserOnlyReads(root: string, file: string): Promise<readonly LiveReach[]> {
+  const reads: LiveReach[] = [];
+  await firstInGraph(root, file, (source, path) => {
+    const hook = liveHooksIn(source)[0];
+    if (hook !== undefined) reads.push({ at: path, hook });
+    return undefined;
+  });
+  return reads;
+}
+
 export interface LiveRouteGap extends LiveReach {
   readonly route: string;
   readonly file: string;
@@ -132,28 +168,34 @@ const generatorFor = (file: string): string => {
 };
 
 /**
- * Every route that reads live rows with nothing to receive them. Two shapes, one condition — no
- * island at all, and an island the route declares `hydrate: 'never'` for. `X_ISLAND_NOT_HYDRATED`
- * covers the second only at render time, and only for a render that reaches the island, so a route
- * can hold the contradiction and never be asked.
+ * Every browser-only read a route's SERVER graph holds that no browser will ever run. A page's
+ * imports are server-rendered — an island is reached by a `src` string, never an import — so a
+ * module there runs in a browser only if some island's own graph imports it too. Anything else
+ * renders its server state (nothing, or `loading`) forever, at 200. `hydrate: 'never'` boots no
+ * island at all, so every read on such a route is reported. One finding per MODULE: a layout every
+ * page imports is one mistake, not one per route.
  */
 export async function liveRouteGaps(
   root: string,
   entries: readonly RouteEntry[],
 ): Promise<readonly LiveRouteGap[]> {
+  const inBrowser = await islandModules(root);
+  const reported = new Set<string>();
   const gaps: LiveRouteGap[] = [];
   for (const entry of entries) {
     if (entry.surface === 'api') continue;
-    if (entry.islands.length > 0 && entry.config.hydrate !== 'never') continue;
-    const reach = await liveReachOf(root, entry.file);
-    if (reach === undefined) continue;
-    gaps.push({
-      ...reach,
-      route: entry.path,
-      file: entry.file,
-      hydrate: entry.config.hydrate,
-      islands: entry.islands,
-    });
+    const never = entry.config.hydrate === 'never';
+    for (const read of await browserOnlyReads(root, entry.file)) {
+      if (reported.has(read.at) || (!never && inBrowser.has(read.at))) continue;
+      reported.add(read.at);
+      gaps.push({
+        ...read,
+        route: entry.path,
+        file: entry.file,
+        hydrate: entry.config.hydrate,
+        islands: entry.islands,
+      });
+    }
   }
   return gaps;
 }
@@ -161,14 +203,12 @@ export async function liveRouteGaps(
 export const liveRouteFindingFor = (gap: LiveRouteGap): Finding => ({
   code: 'X_LIVE_ROUTE_NO_ISLAND',
   cause:
-    `${gap.route} reads ${gap.hook}() (${gap.at}) and ` +
-    (gap.islands.length === 0
-      ? 'declares no island'
-      : `declares hydrate: 'never' beside ${gap.islands.join(', ')}`) +
-    ', so no module of this route ever runs in a browser: its rows have nowhere to arrive and the page renders its loading branch forever, at 200',
+    `${gap.route} reads ${gap.hook}() in ${gap.at}, which ` +
+    (gap.hydrate === 'never' ? `sits on a route declaring hydrate: 'never'` : 'no island imports') +
+    ' — so it only ever runs on the server, where it answers its server state (nothing, or loading) forever, at 200',
   fix:
-    `${generatorFor(gap.file)}, declare it with island({ src: './${posix.basename(posix.dirname(gap.file))}${ISLAND_EXTENSION}' }) above defineRoute in ${gap.file}, ` +
-    `and move the ${gap.hook}() read into its mount() — which is where setLiveClient() can be called`,
+    `move it into an island: ${generatorFor(gap.file)}, import ${gap.at} from that island's mount(), and declare it with island({ src: './${posix.basename(posix.dirname(gap.file))}${ISLAND_EXTENSION}' }) in ${gap.file}` +
+    (gap.hydrate === 'never' ? `, with a hydrate other than 'never'` : ''),
   docs: ERROR_DOCS_URL,
   at: gap.at,
 });

package/src/mcp-errors.ts

@@ -102,6 +102,7 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_E2E_LOCATOR_AMBIGUOUS:
     'x test e2e --json   # the fix line carries the same call with .first() on it',
   X_E2E_SERVICE_WORKER_ABSENT: 'x build --target static --json',
+  X_E2E_APP_FAILED: 'x dev --json',
   // The four raw-CDP codes. `x doctor` for the missing browser, because that is the command whose
   // whole job is reporting what this machine does not have; the other three are raised inside a
   // running suite, so the runnable half is the command that re-runs it.
@@ -122,6 +123,8 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x errors list --json   # register the code in its package src/errors.ts, or move its row under "Reserved codes"',
   X_ERROR_CODE_UNRESOLVED:
     'x verify --json   # the finding names the file, the line and the name it could not resolve',
+  X_ERROR_CODE_UNTHROWN:
+    'x errors explain X_ERROR_CODE_UNTHROWN --json   # then mark the row "registered, thrown by nothing since <version>"',
   X_CLI_UNEXPECTED: 'x doctor --json',
   X_TYPECHECK_FAILED: 'bunx tsc -b --pretty false',
   X_LINT_FAILED: 'bunx biome check --write .',

package/src/page-sync.ts

@@ -0,0 +1,54 @@
+// What a page needs to reach the sync node, composed ONCE for `x dev` and the container alike: the
+// worker bundle and the page boot with their routes, the head a document carries (`ultimate-sync`,
+// `ultimate-build`, `ultimate-sync-worker`, the boot script), and the persisted record types a
+// private document names. One call from both boots, so the two cannot serve different targets.
+
+import { persistedRecordTypes } from '@ultimat3/entity';
+import type { Route } from '@ultimat3/http';
+import type { ClientSyncHead } from '@ultimat3/render';
+import { syncUrlFrom } from './sync-url';
+import {
+  buildPageBoot,
+  buildSyncWorker,
+  type FrameworkScript,
+  pageBootRoutes,
+  syncWorkerRoutes,
+} from './worker-bundle';
+
+export interface PageSync {
+  readonly routes: readonly Route[];
+  /** The scripts those routes serve, for the service worker to precache beside the islands. */
+  readonly scripts: readonly FrameworkScript[];
+  readonly head: ClientSyncHead;
+  /**
+   * The record types the app persists, read per render off the entity registry — the app's modules
+   * register their entities during boot, so a value captured here could predate them.
+   */
+  readonly persisted: () => readonly string[];
+}
+
+/**
+ * Built at boot and never on the watcher tick: the worker is framework code, not the app's, and a
+ * worker that changes under tabs already running it is exactly what a source-addressed URL exists
+ * to keep from happening mid-session.
+ */
+export async function pageSync(
+  root: string,
+  env: Readonly<Record<string, string | undefined>>,
+  buildId: string,
+): Promise<PageSync> {
+  const syncUrl = syncUrlFrom(env);
+  const worker = await buildSyncWorker(root);
+  const boot = await buildPageBoot(root);
+  return {
+    routes: [...syncWorkerRoutes(() => worker), ...pageBootRoutes(() => boot)],
+    scripts: [worker, boot].filter((script): script is FrameworkScript => script !== undefined),
+    head: {
+      syncUrl,
+      buildId,
+      ...(worker === undefined ? {} : { workerUrl: worker.url }),
+      ...(boot === undefined ? {} : { bootUrl: boot.url }),
+    },
+    persisted: persistedRecordTypes,
+  };
+}

package/src/realtime-browser-probe-fixture.ts

@@ -4,6 +4,6 @@
 // Bundled AND imported by `realtime-browser-barrel.test.ts` — the import is what gives it an lcov
 // record, since `Bun.build()` reads this file without evaluating it.
 
-import { useLive } from '@ultimat3/realtime';
+import { useQuery } from '@ultimat3/realtime';
 
-export const probeUseLive = useLive;
+export const probeUseQuery = useQuery;

package/src/serve.ts

@@ -48,6 +48,7 @@ import { islandRoutes } from './island-routes';
 import { DEFAULT_METRICS_PORT } from './metrics-endpoint';
 import { readMigrations } from './migrations';
 import { startOtlpExport } from './otlp-export';
+import { pageSync } from './page-sync';
 import { loadPwaArtifacts } from './pwa-artifacts';
 import type { RuntimeOverrides } from './runtime-overrides';
 import { styleBundle } from './style-bundle';
@@ -363,6 +364,9 @@ async function bootRoles(boot: {
   // prevent, and it is the one an operator cannot see without installing the app.
   const pwa = await loadPwaArtifacts(options.root);
   const theme = themeBoot(await loadThemeMode(options.root));
+  // The page's sync target and its scripts — the same call `x dev` makes, so the two cannot differ.
+  // Before the service worker, which precaches those scripts.
+  const sync = await pageSync(options.root, options.env, buildId);
   // The worker, from the SAME route table this process is about to serve — `describeRoutes()` is
   // the one projection `x.manifest.json`, `/_x`, the sitemap and `sw.js` are all built from, so a
   // route added here cannot be missing from the precache manifest.
@@ -375,6 +379,7 @@ async function bootRoles(boot: {
           routes: describeRoutes(),
           islands,
           styles: styleBundle(),
+          scripts: sync.scripts,
         });
   // The app's own MCP endpoint, through the same call `x dev` makes — see `app-mcp.ts`.
   const mcpMount = await mountAppMcp(options.root);
@@ -393,9 +398,13 @@ async function bootRoles(boot: {
     // 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()),
+    // The page's one socket: its worker script, served beside the islands for their reason.
+    ...sync.routes,
     ...appRoutes({
       buildId,
       resolveIsland: (file) => islands.resolverFor(file),
+      sync: sync.head,
+      persisted: sync.persisted,
       themeHead: theme.head,
       ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
       // Only when a store was supplied. `createIsrController` defaults to a per-process memory

package/src/shot-theme.ts

@@ -0,0 +1,52 @@
+// The script a capture runs ahead of the document when a theme was ASKED for. Since 20.2.0 the
+// boot inlines a theme script (`@ultimat3/render`'s `themeScriptBody`) whose fallback is the app's
+// `theme.defaultMode`, and only a stored choice under `THEME_STORAGE_KEY` beats it — so emulating
+// `prefers-color-scheme` alone photographs a `defaultMode: 'dark'` app dark whatever was requested
+// (issue #489). A requested theme is therefore stored as the visitor's CHOICE, on the page's origin,
+// before the boot reads it: the picture is then what a visitor who chose that theme sees.
+
+import { THEME_STORAGE_KEY } from '@ultimat3/render';
+import type { ColorScheme } from '@ultimat3/scraping';
+import { BadFlagError } from './errors';
+
+/** What `x shot --theme` accepts: the two the boot honours from storage, and nothing else. */
+const SHOT_THEMES = ['light', 'dark'] as const;
+export type ShotTheme = (typeof SHOT_THEMES)[number];
+
+const isShotTheme = (value: string): value is ShotTheme =>
+  (SHOT_THEMES as readonly string[]).includes(value);
+
+/**
+ * `--theme light|dark` on a ROUTE shot, or nothing — the box's own preference and the app's own
+ * default, which is what `x shot` has always photographed. Refused by name for any other value:
+ * `no-preference` is the scraping vocabulary's clear, not a theme a reader can ask for.
+ */
+export function readThemeFlag(value: string | undefined): ShotTheme | undefined {
+  if (value === undefined) return undefined;
+  if (isShotTheme(value)) return value;
+  throw new BadFlagError({
+    flag: 'theme',
+    command: 'shot',
+    reason: `"${value}" is not a theme; it is light or dark`,
+    fix: 'x shot / --theme light --json',
+  });
+}
+
+/**
+ * The seeding expression, DETERMINISTIC per scheme: the offline drivers key recordings on the exact
+ * string, and a test asserts on it by value. `'no-preference'` answers `undefined` — the boot
+ * honours only `"light"` and `"dark"` from storage, so there is no choice to store, and storing
+ * anything else would be a value the tokens have no block for.
+ *
+ * `JSON.stringify` on both halves, never a value pasted between quotes: the key and the scheme land
+ * inside a JS string, where one `"` ends it. The `try` is for the origin the page starts on:
+ * `about:blank` is opaque and its `localStorage` throws, and a throw from a new-document script
+ * would surface as a page error on a capture that has not navigated yet.
+ */
+export function themeChoiceExpression(scheme: ColorScheme): string | undefined {
+  if (scheme === 'no-preference') return undefined;
+  return (
+    `try{localStorage.setItem(${JSON.stringify(THEME_STORAGE_KEY)},${JSON.stringify(scheme)})}` +
+    'catch(e){}'
+  );
+}

package/src/sw-artifacts.ts

@@ -57,6 +57,12 @@ export interface ServiceWorkerInput {
    * this map does not name.
    */
   readonly documents?: ReadonlyMap<string, RenderedDocument>;
+  /**
+   * The page's framework scripts — realtime's page boot and sync worker (`pageSync(…).scripts`).
+   * Precached beside the island chunks for their reason: source-addressed and `immutable`, and an
+   * offline reload that cannot load the boot restores no record and shows the old count.
+   */
+  readonly scripts?: readonly { readonly url: string; readonly bytes: number }[];
 }
 
 /**
@@ -117,8 +123,12 @@ const pwaRoutes = (
  * Sorted by url, because `buildPrecacheManifest` sorts its own entries but the ASSET list is what
  * decides which of two equal urls wins, and `sw.js` must be byte-identical for identical input.
  */
-const staticAssets = (islands: IslandBundle, styles: StyleBundle): readonly PrecacheAsset[] =>
-  [...islands.chunks, ...styles.chunks]
+const staticAssets = (
+  islands: IslandBundle,
+  styles: StyleBundle,
+  scripts: readonly { readonly url: string; readonly bytes: number }[],
+): readonly PrecacheAsset[] =>
+  [...islands.chunks, ...styles.chunks, ...scripts]
     .map((chunk) => ({ url: chunk.url, revision: chunk.url, bytes: chunk.bytes }))
     .sort((a, b) => (a.url < b.url ? -1 : a.url > b.url ? 1 : 0));
 
@@ -200,7 +210,7 @@ export function serviceWorkerArtifacts(
         neverCache: pwa.offline.neverCache,
       },
       capabilities: { backgroundSync: pwa.backgroundSync, push: pwa.push },
-      assets: staticAssets(input.islands, input.styles),
+      assets: staticAssets(input.islands, input.styles, input.scripts ?? []),
     },
     input.buildId,
   );