@ultimat3/cli 22.7.0 → 22.8.0

package/CLAUDE.md

@@ -83,6 +83,7 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 | `runtime-overrides.ts` | the one field a host hands the framework a driver through — and `routes`, the plain routes for a wire format no primitive speaks (OAuth token endpoint) |
 | `app-openapi.ts` | `openapi.json` (complete when `defineApi({ openapi })` is declared) and each bearer mount's own document; staleness for all of them |
 | `script-csp.ts` / `style-csp.ts` / `style-bundle.ts` / `page-sync.ts` / `worker-bundle.ts` | CSP hashes, the CSS file, the page's sync target and worker |
+| `page-navigation.ts` | the client router for `navigation.client` surfaces — built, routed and named ONCE for `x dev`, the container and the static export; none opted in builds nothing |
 | `island-bundle.ts` / `island-store.ts` / `island-realtime.ts` / `solid-loader.ts` | islands: one `Bun.build` each, source-addressed; `x build --target docker` writes a verified store the container loads |
 | `dev-*.ts` | `x dev` only: dashboard sources, traces, the N+1 ledger, the watcher, the reload, the lock, the port |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "22.7.0",
+  "version": "22.8.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -38,33 +38,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "22.7.0",
-    "@ultimat3/admin": "22.7.0",
-    "@ultimat3/ai": "22.7.0",
-    "@ultimat3/auth": "22.7.0",
-    "@ultimat3/cache": "22.7.0",
-    "@ultimat3/core": "22.7.0",
-    "@ultimat3/db": "22.7.0",
-    "@ultimat3/entity": "22.7.0",
-    "@ultimat3/flags": "22.7.0",
-    "@ultimat3/http": "22.7.0",
-    "@ultimat3/i18n": "22.7.0",
-    "@ultimat3/jobs": "22.7.0",
-    "@ultimat3/mail": "22.7.0",
-    "@ultimat3/manifest": "22.7.0",
-    "@ultimat3/mcp": "22.7.0",
-    "@ultimat3/money": "22.7.0",
-    "@ultimat3/notify": "22.7.0",
-    "@ultimat3/policy": "22.7.0",
-    "@ultimat3/pwa": "22.7.0",
-    "@ultimat3/query": "22.7.0",
-    "@ultimat3/realtime": "22.7.0",
-    "@ultimat3/render": "22.7.0",
-    "@ultimat3/schema": "22.7.0",
-    "@ultimat3/seo": "22.7.0",
-    "@ultimat3/storage": "22.7.0",
-    "@ultimat3/testing": "22.7.0",
-    "@ultimat3/time": "22.7.0",
+    "@ultimat3/action": "22.8.0",
+    "@ultimat3/admin": "22.8.0",
+    "@ultimat3/ai": "22.8.0",
+    "@ultimat3/auth": "22.8.0",
+    "@ultimat3/cache": "22.8.0",
+    "@ultimat3/core": "22.8.0",
+    "@ultimat3/db": "22.8.0",
+    "@ultimat3/entity": "22.8.0",
+    "@ultimat3/flags": "22.8.0",
+    "@ultimat3/http": "22.8.0",
+    "@ultimat3/i18n": "22.8.0",
+    "@ultimat3/jobs": "22.8.0",
+    "@ultimat3/mail": "22.8.0",
+    "@ultimat3/manifest": "22.8.0",
+    "@ultimat3/mcp": "22.8.0",
+    "@ultimat3/money": "22.8.0",
+    "@ultimat3/notify": "22.8.0",
+    "@ultimat3/policy": "22.8.0",
+    "@ultimat3/pwa": "22.8.0",
+    "@ultimat3/query": "22.8.0",
+    "@ultimat3/realtime": "22.8.0",
+    "@ultimat3/render": "22.8.0",
+    "@ultimat3/schema": "22.8.0",
+    "@ultimat3/seo": "22.8.0",
+    "@ultimat3/storage": "22.8.0",
+    "@ultimat3/testing": "22.8.0",
+    "@ultimat3/time": "22.8.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/build-errors.ts

@@ -35,8 +35,8 @@ export class IslandBuildFailedError extends UltimateError {
   }
 }
 
-/** Which framework script a page ships: the one sync worker, or the one page boot. */
-export type FrameworkScriptKind = 'sync worker' | 'page boot';
+/** Which framework script a page ships: the sync worker, the page boot, or the client router. */
+export type FrameworkScriptKind = 'sync worker' | 'page boot' | 'client router';
 
 /**
  * One of the page's framework scripts would not bundle. Same code as an island: "a browser entry

package/src/dev-route-table.ts

@@ -16,6 +16,7 @@ import type { IslandBundle } from './island-bundle';
 import { islandHarnessRoutes } from './island-harness-route';
 import { islandRoutes } from './island-routes';
 import { loadIslandStates } from './island-states-load';
+import { loadNavigation, pageNavigation } from './page-navigation';
 import { pageSync } from './page-sync';
 import { loadPwaArtifacts } from './pwa-artifacts';
 import { assetRoutes } from './runtime-assets';
@@ -71,6 +72,12 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
   const origin = publicOrigin(input.env, site);
   // The same call `serve.ts` makes, so the two boots cannot serve different sync targets.
   const sync = await pageSync(input.root, input.env, input.buildId, input.realtime);
+  // The client router, when a surface opted in (`navigation.client`) — the same call in both boots.
+  const navigation = await pageNavigation(
+    input.root,
+    await loadNavigation(input.root),
+    input.buildId,
+  );
   const errorStyles = await errorPageStyleSources(input.root);
   // Built once at boot and NOT rebuilt with the islands on a watcher tick: a service worker that
   // changes under a page it controls is the update path, and one per keystroke exercises it per save.
@@ -83,7 +90,10 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
           routes: describeRoutes(),
           islands: input.islands(),
           styles: styleBundle(),
-          scripts: sync.scripts,
+          scripts: [
+            ...sync.scripts,
+            ...(navigation.script === undefined ? [] : [navigation.script]),
+          ],
         });
 
   // The app's own MCP endpoint, discovered from `apps/<app>/mcp.ts` and mounted through the SAME
@@ -129,6 +139,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
     }),
     ...(serviceWorker === undefined ? [] : serviceWorkerRoutes(serviceWorker)),
     ...sync.routes,
+    ...navigation.routes,
     ...pagePostRoutes(),
     ...appRoutes({
       buildId: input.buildId,
@@ -136,6 +147,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
       resolveIsland: (file) => input.islands().resolverFor(file),
       ...(sync.head === undefined ? {} : { sync: sync.head }),
       persisted: sync.persisted,
+      ...(navigation.head === undefined ? {} : { navigation: navigation.head }),
       themeHead: theme.head,
       ...(origin === undefined ? {} : { origin }),
       ...(pwa === undefined

package/src/page-navigation.ts

@@ -0,0 +1,206 @@
+// The client router a document may carry, composed ONCE for `x dev`, the container and the static
+// export: which surfaces opted in (`navigation: { client: [...] }` in `app.config.ts`), the router
+// script built from the app's own `@ultimat3/render`, its route, the head a document of an opted-in
+// surface carries, and the SERVER's half per page — which router may swap it in, whether it may be
+// prefetched (`@ultimat3/http`'s navigation gate reads that off the route meta), and the principal
+// check a soft visit gets before `load`. No surface opted in: nothing is built, served or named — a
+// `site/` page that did not ask stays 0kb (axiom 6).
+
+// why: Bun exposes no path-join primitive, and the config path is app-root-relative — the same
+// necessity `theme-boot.ts` records.
+import { join } from 'node:path';
+import { clientScopeOf } from '@ultimat3/auth';
+import type { Ctx, NavigationSurface } from '@ultimat3/core';
+import { CLIENT_NAVIGATION_SCOPE_HEADER, NAVIGATION_SURFACES } from '@ultimat3/core';
+import type { Route, RouteNavigation, UltimateRequest } from '@ultimat3/http';
+import { navigationPurpose, relocate } from '@ultimat3/http';
+import type { ClientNavigationHead, HeadTag, RouteEntry } from '@ultimat3/render';
+import {
+  clientNavigationTags,
+  documentCarriesScope,
+  RouteNavigationInvalidError,
+  routeEntries,
+} from '@ultimat3/render';
+import { ssrHeaders } from '@ultimat3/render/server';
+import { APP_CONFIG_EXPORT } from './app-auth';
+import { APP_CONFIG_FILE } from './app-root';
+import { FrameworkScriptBuildFailedError } from './errors';
+import {
+  buildNavigationScript,
+  type FrameworkScript,
+  NAVIGATION_SPECIFIER,
+  navigationRoutes,
+} from './worker-bundle';
+
+/** What a document renderer needs to decide, per route, whether to name the router. */
+export interface NavigationDocumentHead {
+  readonly surfaces: ReadonlySet<string>;
+  readonly scriptUrl: string;
+  /** The skew check's reference: a soft navigation onto another build is a full load. */
+  readonly buildId: string;
+  /** `app.config.ts`'s `name`: two apps on one origin (web and admin) are two routers. */
+  readonly app: string;
+}
+
+export interface PageNavigation {
+  readonly routes: readonly Route[];
+  /** The router script, for the static export to write and the service worker to precache. */
+  readonly script: FrameworkScript | undefined;
+  /** `undefined` when no surface opted in. */
+  readonly head: NavigationDocumentHead | undefined;
+}
+
+/** `app.config.ts`'s answer: the app's name and the surfaces that opted in. */
+export interface NavigationDeclaration {
+  readonly app: string;
+  readonly surfaces: readonly NavigationSurface[];
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+const isSurface = (value: unknown): value is NavigationSurface =>
+  NAVIGATION_SURFACES.some((surface) => surface === value);
+
+/**
+ * `navigation.client` and `name`, as `defineConfig` validated them — no surfaces when the app says
+ * nothing or has no config file. Structural, never `instanceof`, for `loadThemeMode`'s reason.
+ */
+export async function loadNavigation(root: string): Promise<NavigationDeclaration> {
+  const configPath = join(root, APP_CONFIG_FILE);
+  if (!(await Bun.file(configPath).exists())) return { app: 'app', surfaces: [] };
+  const module = (await import(configPath)) as Record<string, unknown>;
+  const config = module[APP_CONFIG_EXPORT];
+  if (!isRecord(config)) return { app: 'app', surfaces: [] };
+  const app = typeof config['name'] === 'string' ? config['name'] : 'app';
+  const navigation = config['navigation'];
+  const client = isRecord(navigation) ? navigation['client'] : undefined;
+  return { app, surfaces: Array.isArray(client) ? client.filter(isSurface) : [] };
+}
+
+/**
+ * A page declaring `navigation` on a surface with no client navigation says something no process
+ * can honour — refused at boot, before a single request, for every route in the table.
+ */
+export function assertRouteNavigation(
+  surfaces: readonly NavigationSurface[],
+  entries: readonly RouteEntry[] = routeEntries(),
+): void {
+  for (const entry of entries) {
+    const mode = entry.config.navigation;
+    if (mode === undefined || surfaces.some((surface) => surface === entry.surface)) continue;
+    throw new RouteNavigationInvalidError(
+      `${entry.file} declares navigation: '${mode}', and its surface (${entry.surface}) is not in app.config.ts navigation.client`,
+    );
+  }
+}
+
+/**
+ * Built at boot, never on the watcher tick — the router is framework code, and a tab that loaded
+ * it keeps it across every soft navigation, so a URL that changed per save would be one no tab
+ * asks for again.
+ */
+export async function pageNavigation(
+  root: string,
+  declared: NavigationDeclaration,
+  buildId: string,
+): Promise<PageNavigation> {
+  assertRouteNavigation(declared.surfaces);
+  if (declared.surfaces.length === 0) return { routes: [], script: undefined, head: undefined };
+  const script = await buildNavigationScript(root);
+  // Opted in and nothing to build is a refusal, never a silent full-page app: the app asked for a
+  // behaviour and would otherwise ship without it and without a word.
+  if (script === undefined) {
+    throw new FrameworkScriptBuildFailedError({
+      what: 'client router',
+      entry: NAVIGATION_SPECIFIER,
+      logs: `${NAVIGATION_SPECIFIER} does not resolve from ${root} — install @ultimat3/render at the version of @ultimat3/cli`,
+    });
+  }
+  return {
+    routes: navigationRoutes(() => script),
+    script,
+    head: {
+      surfaces: new Set(declared.surfaces),
+      scriptUrl: script.url,
+      buildId,
+      app: declared.app,
+    },
+  };
+}
+
+/** `<app>:<surface>` — what the document says and what the route meta requires. */
+export const surfaceKey = (head: NavigationDocumentHead, surface: string): string =>
+  `${head.app}:${surface}`;
+
+/** The head for one document, or `undefined` when its surface did not opt in. */
+export function navigationHeadFor(
+  head: NavigationDocumentHead | undefined,
+  surface: string,
+): ClientNavigationHead | undefined {
+  if (head === undefined || !head.surfaces.has(surface)) return undefined;
+  return { surface: surfaceKey(head, surface), buildId: head.buildId, scriptUrl: head.scriptUrl };
+}
+
+/** The router's meta, build and script — only on a surface that opted in. */
+export function navigationTagsOf(
+  head: NavigationDocumentHead | undefined,
+  surface: string,
+): readonly HeadTag[] {
+  const tags = navigationHeadFor(head, surface);
+  return tags === undefined ? [] : clientNavigationTags(tags);
+}
+
+/** `{ navigation }` for `metaOf`'s spread, or nothing. */
+export function navigationMetaOf(
+  entry: RouteEntry,
+  head: NavigationDocumentHead | undefined,
+): { readonly navigation?: RouteNavigation } {
+  const navigation = routeNavigationOf(entry, head);
+  return navigation === undefined ? {} : { navigation };
+}
+
+/**
+ * The route meta `@ultimat3/http`'s gate reads: present only for a page the router may swap in.
+ * `navigation: 'document'` and every page of a surface that did not opt in get none — so a
+ * router request to them runs nothing and is handed to the browser.
+ */
+export function routeNavigationOf(
+  entry: RouteEntry,
+  head: NavigationDocumentHead | undefined,
+): RouteNavigation | undefined {
+  if (head === undefined || !head.surfaces.has(entry.surface)) return undefined;
+  if (entry.config.navigation === 'document') return undefined;
+  return {
+    surface: surfaceKey(head, entry.surface),
+    prefetch: entry.config.navigation === 'prefetch',
+  };
+}
+
+/**
+ * The principal this page's document will be rendered for — `null` for a shareable document, which
+ * carries no scope — by the rule `resultFor` renders by: every `stream` and every gated `ssr`.
+ */
+function scopeOf(entry: RouteEntry, ctx: Ctx, buildId: string): string | null {
+  const render = entry.config.render;
+  const scoped =
+    render === 'stream' ||
+    (render === 'ssr' && documentCarriesScope(ssrHeaders(entry, { buildId })));
+  return scoped ? clientScopeOf(ctx.actor) : null;
+}
+
+/**
+ * A soft visit to a page rendered for a principal other than the one the router's document was:
+ * the page boot restores and fences ONE principal per load, so it must be a real load — answered
+ * here, before `load` runs, so the page runs once (for that load) and never for a swap discarded.
+ */
+export function principalRelocation(
+  entry: RouteEntry,
+  request: UltimateRequest,
+  ctx: Ctx,
+  buildId: string,
+): Response | undefined {
+  if (navigationPurpose(request.raw) === null) return undefined;
+  const said = request.header(CLIENT_NAVIGATION_SCOPE_HEADER);
+  return said === scopeOf(entry, ctx, buildId) ? undefined : relocate(request.url.href);
+}

package/src/prerender.ts

@@ -27,6 +27,7 @@ import { buildIslands, writeIslands } from './island-bundle';
 import { measureDatabase } from './measure-database';
 import { measurePaths } from './measure-paths';
 import { measureScope, withAppUrl } from './measure-scope';
+import { loadNavigation, pageNavigation } from './page-navigation';
 import { localizedArtifacts } from './prerender-locales';
 import { clearPrerenderOut } from './prerender-out';
 import { loadPwaArtifacts, writePwaIcons } from './pwa-artifacts';
@@ -228,6 +229,17 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // names it either.
   const pwa = await loadPwaArtifacts(options.root);
   const theme = themeBoot(await loadThemeMode(options.root));
+  // The client router, for the surfaces that opted in: written BEFORE any document names it, for
+  // the register's reason below — `measureDocumentJs` weighs it off disk, and it is charged to
+  // the route (the interactivity the app asked for), so it must be there to be weighed.
+  const navigation = await pageNavigation(
+    options.root,
+    await loadNavigation(options.root),
+    buildId,
+  );
+  if (navigation.script !== undefined) {
+    await Bun.write(join(options.out, navigation.script.url.slice(1)), navigation.script.code);
+  }
   // 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
@@ -289,6 +301,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
       resolveIsland: (file: string) => islands.resolverFor(file),
       themeHead: theme.head,
       origin,
+      ...(navigation.head === undefined ? {} : { navigation: navigation.head }),
       ...(pwa === undefined
         ? {}
         : { pwaHead: (locale: string) => pwa.headFor(locale) + (swHead ?? '') }),
@@ -434,6 +447,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
           islands,
           styles,
           documents,
+          ...(navigation.script === undefined ? {} : { scripts: [navigation.script] }),
         });
   // `sw.js` only: `serviceWorker.register` IS `serviceWorkerRegistration()`, already on disk above
   // and identical by construction. A second writer of one path is how the two could ever disagree.

package/src/runtime-render.ts

@@ -66,6 +66,12 @@ import {
   streamResult,
 } from '@ultimat3/render/server';
 import { realtimeIslandFiles } from './island-realtime';
+import {
+  type NavigationDocumentHead,
+  navigationMetaOf,
+  navigationTagsOf,
+  principalRelocation,
+} from './page-navigation';
 import { styleBundle } from './style-bundle';
 
 /**
@@ -113,6 +119,11 @@ export interface DocumentOptions {
    * resolves against whatever host it happened to fetch from, a CDN's or a preview's.
    */
   readonly origin?: string;
+  /**
+   * The client router — `pageNavigation(…).head`. A document of a surface listed in
+   * `navigation.client` names it; every other document carries none of it.
+   */
+  readonly navigation?: NavigationDocumentHead;
 }
 
 export interface DevRenderOptions extends DocumentOptions {
@@ -166,6 +177,7 @@ const headFor = async (
         }),
         [
           ...(options.sync === undefined ? [] : clientSyncTags(options.sync)),
+          ...navigationTagsOf(options.navigation, entry.surface),
           // The page boot rides the scope tag: its whole job — restoring a principal's persisted
           // records and replaying its queued writes — is per principal, and a shareable document
           // (no scope tag) has neither. Cheaper than walking the page's islands, and exact.
@@ -420,11 +432,8 @@ const responseOf = (result: RenderResult): Response =>
     ? html(result.body, { status: result.status, headers: result.headers })
     : stream(result.body, { status: result.status, headers: result.headers });
 
-/**
- * `auth` follows the route's own guard, so a gated page is gated in dev by the same pipeline
- * stage that gates it in production. A route that declares no policy is public by declaration.
- */
-const metaOf = (entry: RouteEntry): HttpRouteMeta => ({
+/** `auth` follows the route's own guard: a gated page is gated in dev by the production stage. */
+const metaOf = (entry: RouteEntry, head?: NavigationDocumentHead): HttpRouteMeta => ({
   name: entry.file,
   auth: entry.config.policy === undefined ? 'public' : 'required',
   render: entry.config.render,
@@ -439,6 +448,8 @@ const metaOf = (entry: RouteEntry): HttpRouteMeta => ({
   ...(entry.config.cache === undefined
     ? {}
     : { cache: entry.config.cache === 'no-store' ? NO_STORE : entry.config.cache }),
+  // Which router may swap this page in, read by `@ultimat3/http`'s gate before anything runs.
+  ...navigationMetaOf(entry, head),
 });
 
 /**
@@ -462,11 +473,14 @@ export function appRoutes(options: DevRenderOptions): readonly Route[] {
     method: 'GET' as const,
     path: registered.path,
     get meta(): HttpRouteMeta {
-      return metaOf(routeFor(registered.path) ?? registered);
+      return metaOf(routeFor(registered.path) ?? registered, options.navigation);
     },
     // `ctx.params` is the router's own match — the CLI never re-parses a path it did not match.
     handler: async (request, ctx): Promise<Response> => {
       const entry = routeFor(registered.path) ?? registered;
+      // A soft visit onto another principal's document is a real load — answered before `load`.
+      const moved = principalRelocation(entry, request, asCtx(ctx), options.buildId);
+      if (moved !== undefined) return moved;
       const data: DevRouteData = { url: request.url.href, params: ctx.params };
       // ONCE per request, before the mode is chosen: every branch of `resultFor` reads this same
       // object, so a route's `load` runs exactly once however its mode splits head from body.

package/src/serve-boot.ts

@@ -18,6 +18,7 @@ import { islandRoutes } from './island-routes';
 import { loadOrBuildIslands } from './island-store';
 import type { MetricsEndpoint } from './metrics-endpoint';
 import { startOtlpExport } from './otlp-export';
+import { loadNavigation, pageNavigation } from './page-navigation';
 import { pageSync } from './page-sync';
 import { loadPwaArtifacts } from './pwa-artifacts';
 import { startRoles } from './role-start';
@@ -149,6 +150,12 @@ async function webSurface(
   // 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, runtime.realtime);
+  // The client router, when a surface opted in (`navigation.client`) — the same call in both boots.
+  const navigation = await pageNavigation(
+    options.root,
+    await loadNavigation(options.root),
+    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.
@@ -161,7 +168,10 @@ async function webSurface(
           routes: describeRoutes(),
           islands,
           styles: styleBundle(),
-          scripts: sync.scripts,
+          scripts: [
+            ...sync.scripts,
+            ...(navigation.script === undefined ? [] : [navigation.script]),
+          ],
         });
   // The app's own MCP endpoint, through the same call `x dev` makes — see `app-mcp.ts`.
   const mcpMount = await mountAppMcp(options.root);
@@ -191,6 +201,7 @@ async function webSurface(
     ...seoRoutes({ env: options.env, site }),
     // The page's one socket: its worker script, served beside the islands for their reason.
     ...sync.routes,
+    ...navigation.routes,
     // A page's `POST`, bound to an action (`defineRoute({ post })`) — beside the page's `GET`.
     ...pagePostRoutes(),
     ...appRoutes({
@@ -198,6 +209,7 @@ async function webSurface(
       resolveIsland: (file) => islands.resolverFor(file),
       ...(sync.head === undefined ? {} : { sync: sync.head }),
       persisted: sync.persisted,
+      ...(navigation.head === undefined ? {} : { navigation: navigation.head }),
       themeHead: theme.head,
       ...(origin === undefined ? {} : { origin }),
       ...(pwa === undefined

package/src/sw-artifacts.ts

@@ -67,7 +67,8 @@ export interface ServiceWorkerInput {
    */
   readonly documents?: ReadonlyMap<string, RenderedDocument>;
   /**
-   * The page's framework scripts — realtime's page boot and sync worker (`pageSync(…).scripts`).
+   * The page's framework scripts — realtime's page boot and sync worker (`pageSync(…).scripts`), and
+   * the client router when a surface opted in (`pageNavigation(…).script`).
    * 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.
    */

package/src/worker-bundle.ts

@@ -23,6 +23,12 @@ export const PAGE_BOOT_BASE_PATH = '/_x/page-boot';
 /** Realtime's page boot, from the APP's install. */
 export const PAGE_BOOT_SPECIFIER = '@ultimat3/realtime/boot';
 
+/** Under the dev namespace too; one per document whose surface opted into client navigation. */
+export const NAVIGATION_BASE_PATH = '/_x/navigation';
+
+/** Render's client router, from the APP's install — the copy its documents were rendered by. */
+export const NAVIGATION_SPECIFIER = '@ultimat3/render/navigation';
+
 /** One framework script: the sync worker or the page boot. */
 export interface FrameworkScript {
   /** `<base>/<hash>.js` — what the document names. */
@@ -74,6 +80,23 @@ export function buildPageBoot(
   );
 }
 
+/**
+ * The client router (`navigation: { client }` in `app.config.ts`), or `undefined` when the app's
+ * render predates it. Built only when a surface opted in — see `pageNavigation`.
+ */
+export function buildNavigationScript(
+  root: string,
+  options: BuildSyncWorkerOptions = {},
+): Promise<FrameworkScript | undefined> {
+  return buildFrameworkScript(
+    root,
+    'client router',
+    NAVIGATION_SPECIFIER,
+    NAVIGATION_BASE_PATH,
+    options.entry,
+  );
+}
+
 async function buildFrameworkScript(
   root: string,
   what: FrameworkScriptKind,
@@ -158,6 +181,10 @@ export function pageBootRoutes(source: SyncWorkerSource): readonly Route[] {
   return [scriptRoute(PAGE_BOOT_BASE_PATH, 'assets.page-boot', 'page boot', source)];
 }
 
+export function navigationRoutes(source: SyncWorkerSource): readonly Route[] {
+  return [scriptRoute(NAVIGATION_BASE_PATH, 'assets.navigation', 'client router', source)];
+}
+
 function scriptRoute(
   basePath: string,
   name: string,