@ultimat3/render 22.15.0 → 23.0.0

package/CLAUDE.md

@@ -61,6 +61,7 @@ axiom 6). Never `cli` (upward).
 | `idle`'s deadline | `IDLE_HYDRATE_TIMEOUT_MS`, interpolated INTO the runtime string and exported for `x shot`'s settle. |
 | Route truth | `registry.ts`. Never a second route list and never a second matcher — `@ultimat3/http`'s trie (`stages.ts`) serves requests. `routeFor` is an exact-path `Map` lookup. |
 | Route filename | `page.tsx` under `site/`/`app/`, `route.ts` under `api/` — `ROUTE_FILENAME`. Anything else is `X_ROUTE_FILE_INVALID`. |
+| Mounted routes | `registerMountedRoutes(mount, routes)` (`mounted-routes.ts`) — routes a PACKAGE mounts with no surface file (the admin's screens). In `describeRoutes()` with `mount: { by, permissions }`, never in `routeEntries()`: described, not rendered here. Re-declaring a `key` replaces its set; a path a file route also claims is `X_ROUTE_DUPLICATE` in both orders. `RouteDescriptor.mount` is absent on a file route. |
 | Registry input | descriptors only. `registerRoute` refuses a raw declaration with `X_ROUTE_UNNORMALIZED`; it fills in only the island budget. |
 | Descriptors | `describeRoutes()` stays JSON-safe, sorted by path, deterministic. |
 | Every string order | `byCodeUnit` (`code-unit-order.ts`), never `localeCompare` (ICU default locale and collation version vary by machine). |
@@ -88,14 +89,16 @@ axiom 6). Never `cli` (upward).
 | Solid | no `solid-js` import anywhere in this package; `type-pins.tsx` satisfies `JSX.Element` structurally. `jsx.ts` builds inert nodes. Islands are compiled by `@ultimat3/cli`'s `solid-loader.ts` with `babel-preset-solid`. |
 | Root element | `ROOT_ELEMENT_ID` (`render-html.ts`). |
 | The loaders | `module-loader.ts` installs them at **`server.ts`** module scope, once. `packages/cli/src/app-load.ts` imports `@ultimat3/render/server` for that side effect. |
+| Path style tag | `client-path-style-tag.ts` — `<meta name="ultimate-path-style">`, read by core's `actionPath`. Principal-free, on every document; written ONLY for a non-default style, so a `'resource'` app's bytes do not move. `@ultimat3/cli`'s `headFor` hands it `@ultimat3/action`'s `actionPathStyle()` per render — this package has no edge to `action`. |
 | Client sync tags | `client-sync-tags.ts` — `ultimate-sync`, `ultimate-build`, `ultimate-sync-worker`. Principal-free, on every document. |
 | Client scope tag | `client-scope-tag.ts` — `<meta name="ultimate-scope">`, read by core's `pageClient()`. `documentCarriesScope(headers)` is the one rule: only a `private` document carries it; absent means "not rendered for anyone". The literal is duplicated in core until core exports a constant. |
 | `<head>` baseline | `documentBaseline()` in `head.ts` — charset, viewport, `color-scheme` — merged FIRST so a route can override any of them. |
 | Escaping | `html.ts` only — including `render-stream.ts`'s `holeMarker` and `revealChunk` (`JSON.stringify`), and `head.ts`'s `themeScript`. `escapeAttribute` is `@ultimat3/seo`'s, re-exported by `html.ts`. |
 | Script and style CONTENT | never raw: `escapeText`, `escapeRawTextContent` (`</` → `<\/`, `<!--` → `<\!--`), or `escapeJsonContent` for a `type` ending in `json`. Never HTML-escape a script body. |
 | Which export is the page | `route-component.ts`: `Page` → a single `…Page` → a single capitalised function. |
-| Stylesheets | compiled by `css-modules.ts`, grouped per surface, served by the CLI as one content-hashed file per surface (`@ultimat3/cli`'s `style-bundle.ts`) from `stylesFor`. `sass` is this package's only third-party dependency. Each compile goes through `sass-cache.ts`: `.x/cache/sass/` under cwd, a hit only while every file the compile read hashes the same; `setSassCacheDir(null)` turns it off. |
+| Stylesheets | compiled by `css-modules.ts`, grouped per surface, served by the CLI as one content-hashed file per surface (`@ultimat3/cli`'s `style-bundle.ts`) from `stylesFor`. `sass` is this package's only third-party dependency. Each compile goes through `sass-cache.ts`: `.x/cache/sass/` under cwd, a hit only while every file the compile read hashes the same; `setSassCacheDir(null)` turns it off, `setSassCacheDir(dir)` moves it (the image's prebuilt store), `sassCompilations()` counts the misses a boot reports. |
 | CSS order | `stylesFor` sorts **globals before modules** (`isGlobalStylesheet`). `shared/` is carried by both graphs. |
+| A package's sheets | carried by BOTH surfaces unless the package claims its directory: `claimStylesheets(import.meta.dir, 'app')` makes every sheet below it that surface's alone, still ordered with the library. `@ultimat3/admin` claims `app` — a `site/` document carried its dashboard CSS (axiom 6). A claim re-classifies sheets already registered and survives `clearStylesheets()`. |
 | The global layer | the app's `shared/global.scss` `@use`s `@ultimat3/ui/global.scss`, side-effect-imported by `shared/global.ts` (this package may not import `ui`). `x verify` fails with `X_STYLES_GLOBAL_MISSING` when a surface's document defines none. |
 | Colours | tokens and `data-theme` only. No hex in `head.ts` or any emitted script. |
 | An island's `mount` | may return `() => void`, its disposer; the runtime never calls it, `@ultimat3/testing`'s `mountIsland` does. |

package/README.md

@@ -490,16 +490,20 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `asset`, `setAssetResolver`, `assetPathProblem`, `AssetPath` | `asset('assets/x.avif')` → the content-hashed URL of a public site file; the table is the CLI's ([Static Assets](../../wiki/Static-Assets.md)) |
 | `MODE_SPECS`, `assertModeShape`, `assertModeInvariants` | the mode invariant table |
 | `registerRoute`, `describeRoutes`, `routeFor`, `routePathFromFile` | the route table |
+| `registerMountedRoutes`, `RouteMount`, `RouteMountInput`, `MountedRouteInput` | routes a package mounts with no surface file: listed by `describeRoutes()` with `mount: { by, permissions }`, absent from `routeEntries()` |
 | `checkSurfaceBoundary`, `assertSurfaceBoundary`, `surfaceOf` | the hard boundary |
 | `renderStatic`†, `enumeratePrerender`† | build-time render, content hashing |
 | `createIsrController`†, `invalidateAndRevalidate`† | SWR + single-flight + tag triggers |
 | `renderSsr`†, `streamResult`† | the per-request modes |
 | `renderToHtml`†, `renderComponent`†, `stylesFor`† | the server JSX writer and the surface's css |
+| `claimStylesheets`† | a package claims its own directory's stylesheets for ONE surface, so the other surface's documents never carry them |
 | `installRenderLoader`†, `compileStylesheet`† | the `.tsx`/`.scss` loaders, installed on import |
+| `setSassCacheDir`†, `sassCompilations`† | where the Sass compile cache lives (`.x/cache/sass` under cwd; a container's is the image's prebuilt store) and how many compiles this process ran instead of reading one |
 | `emitIslandAttributes`, `hydrateRuntime`, `HYDRATE_RUNTIME_BODIES` | the four hydration strategies, and every body the runtime script can hold — a host hashes that list into `script-src`, because the runtime is emitted inline and no `render: 'static'` file can receive a nonce |
 | `ISLAND_MOUNTED_ATTRIBUTE`, `ISLAND_FAILED_ATTRIBUTE`, `IDLE_HYDRATE_TIMEOUT_MS` | what hydration looks like from outside the page |
 | `parseByteBudget`, `defaultIslandBudget` | the `'40kb'` budget grammar, and the ceiling a declared island earns |
 | `mergeHead`, `renderHead`, `themeScript` | `<head>` merge + the one inlined script |
+| `clientPathStyleTags`, `CLIENT_PATH_STYLE_META` | `<meta name="ultimate-path-style">` — the action path style the server serves, for the browser's typed client. No tag for `'resource'`, the default |
 
 ## Notes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/render",
-  "version": "22.15.0",
+  "version": "23.0.0",
   "description": "The route primitive and the five render modes: static, isr, ssr, stream, spa.",
   "license": "MIT",
   "type": "module",
@@ -26,6 +26,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -38,11 +39,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "22.15.0",
-    "@ultimat3/core": "22.15.0",
-    "@ultimat3/http": "22.15.0",
-    "@ultimat3/i18n": "22.15.0",
-    "@ultimat3/seo": "22.15.0",
+    "@ultimat3/cache": "23.0.0",
+    "@ultimat3/core": "23.0.0",
+    "@ultimat3/http": "23.0.0",
+    "@ultimat3/i18n": "23.0.0",
+    "@ultimat3/seo": "23.0.0",
     "sass": "1.104.0"
   }
 }

package/src/client-path-style-tag.ts

@@ -0,0 +1,25 @@
+/**
+ * How this server turns an action's name into its URL, as a `<head>` tag:
+ * `<meta name="ultimate-path-style" content="readable">`, read by `@ultimat3/core`'s `actionPath`
+ * for every browser caller that names no style. Principal-free, so every document may carry it —
+ * and only a non-default style is written: an app that declared none renders the same bytes.
+ */
+
+import type { ActionPathStyle } from '@ultimat3/core';
+import { CLIENT_PATH_STYLE_META } from '@ultimat3/core';
+import type { HeadTag } from './head';
+
+/** The `name` core's reader matches — core's constant, so the writer and the reader are one literal. */
+export { CLIENT_PATH_STYLE_META };
+
+/** `style` is `@ultimat3/action`'s `actionPathStyle()`: what `defineApi` declared, read per render. */
+export function clientPathStyleTags(style: ActionPathStyle): readonly HeadTag[] {
+  if (style === 'resource') return [];
+  return [
+    {
+      kind: 'meta',
+      key: `meta:${CLIENT_PATH_STYLE_META}`,
+      attrs: { name: CLIENT_PATH_STYLE_META, content: style },
+    },
+  ];
+}

package/src/index.ts

@@ -19,6 +19,8 @@ export { formatBytes, HYDRATE_STRATEGIES, OFFLINE_STRATEGIES, RENDER_MODES } fro
 /** `asset('assets/x.avif')` → the content-hashed URL the site asset surface serves it at. */
 export type { AssetExtension, AssetPath, AssetResolver } from './asset';
 export { ASSET_DIR, ASSET_EXTENSIONS, asset, assetPathProblem, setAssetResolver } from './asset';
+/** The `<meta name="ultimate-path-style">` core's `actionPath` reads — a non-default style only. */
+export { CLIENT_PATH_STYLE_META, clientPathStyleTags } from './client-path-style-tag';
 /** The `<meta name="ultimate-scope">` core's `pageClient()` reads, on private documents only. */
 export {
   CLIENT_PERSIST_META,
@@ -154,15 +156,19 @@ export type { ClientNavigationHead } from './navigation-tags';
 export { clientNavigationTags } from './navigation-tags';
 export type {
   CompiledPattern,
+  MountedRouteInput,
   RegisterRouteInput,
   RouteDescriptor,
   RouteEntry,
+  RouteMount,
+  RouteMountInput,
 } from './registry';
 export {
   clearRoutes,
   compilePattern,
   describeRoutes,
   ROUTE_FILENAME,
+  registerMountedRoutes,
   registerRoute,
   routeEntries,
   routeFor,

package/src/jsx.ts

@@ -28,16 +28,37 @@ export function isJsxNode(value: unknown): value is JsxNode {
  * component reading `props.children` behaves the same whether its children came from the classic
  * factory's rest arguments or from an explicit `children` prop.
  */
+export function h(type: string, props: JsxProps | null, ...children: readonly unknown[]): JsxNode;
+/**
+ * A component, with the props IT declares. `JsxComponent` takes any record, so a component typed
+ * for its own props — an `island()`, a page's `Shell` — is not one under `strictFunctionTypes`,
+ * and a hand-written `h(Toggle, { label })` was refused where the `.tsx` loader's own call is not.
+ * The props are checked against the component here; `children` rides as the rest arguments.
+ */
+export function h<Props extends object>(
+  type: (props: Props) => unknown,
+  props: Omit<Props, 'children'> | null,
+  ...children: readonly unknown[]
+): JsxNode;
 export function h(
   type: string | JsxComponent,
   props: JsxProps | null,
   ...children: readonly unknown[]
+): JsxNode;
+export function h(
+  // `never` is the one parameter type every component's props satisfy.
+  type: string | ((props: never) => unknown),
+  props: object | null,
+  ...children: readonly unknown[]
 ): JsxNode {
-  const base = props ?? {};
-  if (children.length === 0) return { [JSX_NODE]: true, type, props: base };
+  // The overloads above are where a call is checked; a node carries the pair erased, which is all
+  // `render-html.ts` ever reads — it hands `props` back to the `type` it arrived with.
+  const erased = type as string | JsxComponent;
+  const base = (props ?? {}) as JsxProps;
+  if (children.length === 0) return { [JSX_NODE]: true, type: erased, props: base };
   return {
     [JSX_NODE]: true,
-    type,
+    type: erased,
     props: { ...base, children: children.length === 1 ? children[0] : children },
   };
 }

package/src/module-loader.ts

@@ -76,6 +76,11 @@ export interface Stylesheet {
   readonly file: string;
   /** The surface that owns it, or `null` for a package stylesheet shared by both graphs. */
   readonly surface: Surface | null;
+  /**
+   * A PACKAGE's sheet whose surface came from `claimStylesheets`, not from where the file sits.
+   * It is carried by that one surface and still ordered with the library — see `stylesheetOrder`.
+   */
+  readonly claimed: boolean;
   /** A plain (non-module) stylesheet: the tokens and the reset, which the cascade needs first. */
   readonly global: boolean;
   /**
@@ -118,8 +123,46 @@ export function registeredStylesheets(): readonly Stylesheet[] {
  */
 let stylesheetRoot: string | undefined;
 
+/**
+ * Directories a package claimed for ONE surface, longest first. A package's sheet has no surface
+ * of its own and rides both graphs — right for a design system, and the reason an app's static
+ * `site/` documents carried the admin's stylesheet for screens only `app/` serves (axiom 6).
+ */
+const claims: { readonly dir: string; readonly surface: Surface }[] = [];
+
+const claimedSurface = (path: string): Surface | undefined =>
+  claims.find((claim) => path.startsWith(`${claim.dir}/`))?.surface;
+
 const surfaceOfSheet = (path: string): Surface | null =>
-  surfaceUnder(stylesheetRoot ?? process.cwd(), path);
+  claimedSurface(path) ?? surfaceUnder(stylesheetRoot ?? process.cwd(), path);
+
+/** Every registered sheet, classified again; the revision moves only when an answer does. */
+const reclassify = (): void => {
+  for (const [path, sheet] of stylesheets) {
+    const surface = surfaceOfSheet(path);
+    const claimed = claimedSurface(path) !== undefined;
+    if (surface === sheet.surface && claimed === sheet.claimed) continue;
+    stylesheets.set(path, { ...sheet, surface, claimed });
+    revision += 1;
+  }
+};
+
+/**
+ * A package says its own stylesheets belong to one surface: every sheet below `dir` is carried by
+ * documents of `surface` and by no other. Called by the package that OWNS the directory, with its
+ * own `import.meta.dir` — a sheet loads when its module is linked, which is before the claiming
+ * module's body runs, so a claim re-classifies what is already registered.
+ *
+ * A claim is a fact about a package's source, made once per process: `clearStylesheets()` leaves
+ * it standing, because the module that made it is cached and will not make it again.
+ */
+export function claimStylesheets(dir: string, surface: Surface): void {
+  const claimed = resolve(dir);
+  if (claims.some((claim) => claim.dir === claimed && claim.surface === surface)) return;
+  claims.push({ dir: claimed, surface });
+  claims.sort((a, b) => b.dir.length - a.dir.length);
+  reclassify();
+}
 
 /**
  * Names the app root the registry classifies against; `loadApp` calls it before importing a module.
@@ -132,12 +175,7 @@ const surfaceOfSheet = (path: string): Surface | null =>
 export function setStylesheetRoot(root: string | undefined): void {
   // Resolved: `loadApp('.')` is a legal call, and `.` is a prefix of no absolute path.
   stylesheetRoot = root === undefined ? undefined : resolve(root);
-  for (const [path, sheet] of stylesheets) {
-    const surface = surfaceOfSheet(path);
-    if (surface === sheet.surface) continue;
-    stylesheets.set(path, { ...sheet, surface });
-    revision += 1;
-  }
+  reclassify();
 }
 
 /** Test seam: the registry is process-global because the module cache it mirrors is too. */
@@ -180,7 +218,8 @@ export function stylesFor(surface: Surface | null): string {
 }
 
 const OWNER_RANK = (sheet: Stylesheet): number =>
-  sheet.surface === null ? 0 : sheet.surface === 'shared' ? 1 : 2;
+  // A claimed sheet is a package's whichever surface carries it: library first.
+  sheet.surface === null || sheet.claimed ? 0 : sheet.surface === 'shared' ? 1 : 2;
 
 /** Relative to the app root, so a container at `/app` and a laptop order one app alike. */
 const orderPath = (sheet: Stylesheet): string => {
@@ -233,6 +272,7 @@ export function loadStylesheet(
     stylesheets.set(path, {
       file: path,
       surface: surfaceOfSheet(path),
+      claimed: claimedSurface(path) !== undefined,
       global: isGlobalStylesheet(path),
       island,
       css: compiled.css,

package/src/mounted-routes.ts

@@ -0,0 +1,74 @@
+/**
+ * The routes a package MOUNTS — screens no surface file declares, like the admin's — held beside
+ * the file routes so `registry.ts` can describe both in the one route list. Storage and the
+ * collision rule only: nothing here renders, matches or serves.
+ */
+
+import { RouteDuplicateError } from './errors';
+import type { RouteConfig } from './route';
+import type { Surface } from './surfaces';
+
+/** Who put a mounted route in the table, and what it requires. */
+export interface RouteMount {
+  /** The call that declared it: `defineAdmin`. */
+  readonly by: string;
+  /** Every permission the route's own screen decides on, coarse gate first. */
+  readonly permissions: readonly string[];
+}
+
+/** The mount a set of routes belongs to. `key` is what a re-declaration replaces. */
+export interface RouteMountInput {
+  readonly key: string;
+  readonly by: string;
+  /** What `RouteDescriptor.file` reads for these routes: the package, since no app file is. */
+  readonly file: string;
+  readonly surface: Exclude<Surface, 'shared'>;
+}
+
+export interface MountedRouteInput {
+  readonly path: string;
+  readonly config: RouteConfig;
+  readonly permissions: readonly string[];
+}
+
+export interface MountedRoute extends MountedRouteInput {
+  readonly mount: RouteMountInput;
+}
+
+const mounted = new Map<string, readonly MountedRoute[]>();
+
+/** Every mounted route, in mount-declaration order. */
+export function mountedRoutes(): readonly MountedRoute[] {
+  return [...mounted.values()].flat();
+}
+
+/** The mounted route claiming `path`, if one does. */
+export function mountedAt(path: string): MountedRoute | undefined {
+  return mountedRoutes().find((route) => route.path === path);
+}
+
+/** Replaces the set under `mount.key`: a re-declaration is the same mount, saved again. */
+export function setMountedRoutes(
+  mount: RouteMountInput,
+  declared: readonly MountedRouteInput[],
+): void {
+  mounted.set(
+    mount.key,
+    declared.map((route) => ({ ...route, mount })),
+  );
+}
+
+export function clearMountedRoutes(): void {
+  mounted.clear();
+}
+
+/** One URL, one claimant — a file and a mount on the same path is two servers for it. */
+export const mountCollision = (
+  path: string,
+  file: string,
+  mount: RouteMountInput,
+): RouteDuplicateError =>
+  new RouteDuplicateError(
+    `${path} is claimed by both ${file} and ${mount.by}() — a route ${mount.file} mounts`,
+    `delete ${file}: ${mount.by}() already serves ${path}, and the route table is keyed by URL`,
+  );

package/src/registry.ts

@@ -15,6 +15,14 @@ import {
   SurfaceBoundaryError,
 } from './errors';
 import { assertModeInvariants, defaultIslandBudget } from './modes';
+import type { MountedRouteInput, RouteMount, RouteMountInput } from './mounted-routes';
+import {
+  clearMountedRoutes,
+  mountCollision,
+  mountedAt,
+  mountedRoutes,
+  setMountedRoutes,
+} from './mounted-routes';
 import type { RouteConfig, RouteData } from './route';
 import { isRouteConfig, tagKeys } from './route';
 import type { RouteComponent } from './route-component';
@@ -83,8 +91,15 @@ export interface RouteDescriptor {
   readonly islandSources: readonly string[];
   readonly budgetJs: string | null;
   readonly budgetLcp: number | null;
+  /**
+   * Present on a route NO surface file declares: who mounted it and every permission that gates
+   * it. Absent on a file route — so a reader never has to ask whether `file` is a path.
+   */
+  readonly mount?: RouteMount;
 }
 
+export type { MountedRouteInput, RouteMount, RouteMountInput } from './mounted-routes';
+
 export interface CompiledPattern {
   readonly source: string;
   readonly regex: RegExp;
@@ -284,6 +299,8 @@ export function registerRoute<TData = RouteData>(
       `rename or delete one of them — the route table is keyed by URL`,
     );
   }
+  const claimed = mountedAt(path);
+  if (claimed !== undefined) throw mountCollision(path, input.file, claimed.mount);
 
   const entry: RouteEntry<TData> = {
     file: input.file,
@@ -329,8 +346,27 @@ function withIslandBudget<TData>(config: RouteConfig<TData>, surface: Surface):
   return Object.freeze(derived);
 }
 
+/**
+ * Declare the routes a package MOUNTS — screens no surface file exists for, like the admin's — so
+ * the one route list carries them. Described, never rendered here: the mounting host serves them,
+ * and `routeEntries()` stays the pages a file declares. Re-declaring a `key` replaces its set,
+ * because `x dev` re-evaluates the module that declared it on every save.
+ */
+export function registerMountedRoutes(
+  mount: RouteMountInput,
+  declared: readonly MountedRouteInput[],
+): void {
+  for (const route of declared) {
+    const file = routes.get(route.path)?.file;
+    if (file !== undefined) throw mountCollision(route.path, file, mount);
+  }
+  setMountedRoutes(mount, declared);
+  described = undefined;
+}
+
 export function clearRoutes(): void {
   routes.clear();
+  clearMountedRoutes();
   described = undefined;
 }
 
@@ -361,26 +397,51 @@ export function describeRoutes(): readonly RouteDescriptor[] {
 }
 
 function buildDescriptors(): RouteDescriptor[] {
-  return routeEntries().map((entry) => ({
-    path: entry.path,
-    file: entry.file,
-    surface: entry.surface,
-    mode: entry.config.render,
-    offline: entry.config.offline,
-    hydrate: entry.config.hydrate,
-    revalidateTags: tagKeys(entry.config.revalidate?.tags),
-    revalidateTtl: entry.config.revalidate?.ttl ?? null,
-    prerenderable: entry.config.prerender !== undefined,
-    dynamic: entry.pattern.keys.length > 0,
-    hasPolicy: entry.config.policy !== undefined,
-    personal: isPersonal(entry.config),
-    islands: entry.islands,
-    islandSources: entry.config.islands.map((spec) => spec.src),
-    budgetJs: entry.config.budget.js ?? null,
-    budgetLcp: entry.config.budget.lcp ?? null,
-  }));
+  const files = routeEntries().map((entry) =>
+    descriptorOf(entry.path, entry.file, entry.surface, entry.config, entry.pattern.keys.length),
+  );
+  const mounts = mountedRoutes().map(
+    (route): RouteDescriptor => ({
+      ...descriptorOf(
+        route.path,
+        route.mount.file,
+        route.mount.surface,
+        route.config,
+        compilePattern(route.path).keys.length,
+      ),
+      mount: { by: route.mount.by, permissions: [...route.permissions] },
+    }),
+  );
+  return mounts.length === 0
+    ? files
+    : [...files, ...mounts].sort((a, b) => byCodeUnit(a.path, b.path));
 }
 
+const descriptorOf = (
+  path: string,
+  file: string,
+  surface: Surface,
+  config: RouteConfig,
+  params: number,
+): RouteDescriptor => ({
+  path,
+  file,
+  surface,
+  mode: config.render,
+  offline: config.offline,
+  hydrate: config.hydrate,
+  revalidateTags: tagKeys(config.revalidate?.tags),
+  revalidateTtl: config.revalidate?.ttl ?? null,
+  prerenderable: config.prerender !== undefined,
+  dynamic: params > 0,
+  hasPolicy: config.policy !== undefined,
+  personal: isPersonal(config),
+  islands: config.islands.map((spec) => spec.moduleId),
+  islandSources: config.islands.map((spec) => spec.src),
+  budgetJs: config.budget.js ?? null,
+  budgetLcp: config.budget.lcp ?? null,
+});
+
 /** See `RouteDescriptor.personal`. */
 function isPersonal(config: RouteConfig): boolean {
   if (config.policy !== undefined || config.render === 'stream') return true;

package/src/sass-cache.ts

@@ -9,7 +9,12 @@ import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'no
 // why: Bun ships no path-join primitive.
 import { join } from 'node:path';
 
-/** Relative to the process's cwd — the app root for every `x` command. `.x/` is gitignored. */
+/**
+ * Relative to the process's cwd — the app root for every `x` command. `.x/` is gitignored, and in
+ * a container it is the STATE directory a topology mounts a tmpfs over, so an image's own entries
+ * live elsewhere: the image build points this cache at its prebuilt store through
+ * `setSassCacheDir`, and the container's boot points it back at the same place.
+ */
 export const SASS_CACHE_DIR = join('.x', 'cache', 'sass');
 
 /** Bumped when the entry shape changes, so an old entry is a miss and never a misread. */
@@ -153,11 +158,25 @@ export function cachedSassCompile(
   assetsValid: AssetCheck = () => false,
 ): SassOutput {
   const dir = cacheDir();
-  if (dir === null) return compile();
+  if (dir === null) return counted(compile);
   const file = join(dir, `${sha256(key)}.json`);
   const hit = readHit(file, assetsValid);
   if (hit !== undefined) return hit;
-  const output = compile();
+  const output = counted(compile);
   store(dir, file, output);
   return output;
 }
+
+let compilations = 0;
+
+const counted = (compile: () => SassOutput): SassOutput => {
+  compilations += 1;
+  return compile();
+};
+
+/**
+ * How many times this process ran Sass rather than reading a stored result. A container booted
+ * from a prebuilt image answers 0; anything else is a boot that compiled what the image build
+ * should have, and the number is what its log line reports.
+ */
+export const sassCompilations = (): number => compilations;

package/src/server.ts

@@ -26,6 +26,7 @@ export {
 // ---- the two Bun loaders: `.tsx` → the server JSX factory, `.scss` → css + a class map ----------
 export type { Stylesheet } from './module-loader';
 export {
+  claimStylesheets,
   clearStylesheets,
   installRenderLoader,
   loadStylesheet,
@@ -76,3 +77,5 @@ export {
   revealChunk,
   streamResult,
 } from './render-stream';
+// ---- the Sass compile cache: where it lives, and how often this process ran Sass instead --------
+export { sassCompilations, setSassCacheDir } from './sass-cache';

package/src/navigation-controller-fixture.ts

@@ -1,91 +0,0 @@
-/**
- * The controller's test harness beside the fake DOM: a page with the links every test follows, a
- * tab whose `fetch` the test answers (every call recorded), an event dispatched the way a browser
- * does, and the router the test started — stopped after each by `stopRouter()`.
- */
-import { startNavigation } from './navigation';
-import {
-  FakeDocument,
-  type FakeElement,
-  type FakeWindow,
-  fakeWindow,
-  h,
-  htmlAnswer,
-  routerHead,
-} from './navigation-dom-fixture';
-
-export type Handler = (init: RequestInit | undefined) => Response | Promise<Response>;
-
-export const page = (
-  title: string,
-  meta: { scope?: string; build?: string } = {},
-  body: FakeElement[] = [],
-) =>
-  new FakeDocument(routerHead(title, [], meta), [
-    h('main', {}, [
-      h('h1', {}, title),
-      h('a', { id: 'to-b', href: '/b' }, 'b'),
-      h('a', { id: 'to-c', href: '/c' }, 'c'),
-      h('a', { id: 'to-slow', href: '/slow' }, 'slow'),
-      h('a', { id: 'plain', href: '/b', 'data-x-no-prefetch': '' }, 'plain'),
-      ...body,
-    ]),
-    h('script', {}, `hydrate(${title})`),
-  ]);
-
-/** The router the current test started; `stopRouter()` in an `afterEach` lets it go. */
-let router: ReturnType<typeof startNavigation>;
-export const currentRouter = (): ReturnType<typeof startNavigation> => router;
-export function stopRouter(): void {
-  router?.stop();
-  router = undefined;
-}
-
-/** A tab on `/a` whose `fetch` answers from `routes`; `calls` records `METHOD path purpose`. */
-export function tab(routes: Record<string, Handler>, doc = page('A')) {
-  const calls: string[] = [];
-  const fetch = (url: string, init?: RequestInit): Promise<Response> => {
-    const u = new URL(url);
-    const headers = (init?.headers ?? {}) as Record<string, string>;
-    calls.push(
-      `${init?.method ?? 'GET'} ${u.pathname}${u.search} ${headers['x-ultimate-navigation']}`,
-    );
-    const handler = routes[u.pathname];
-    if (handler === undefined) return Promise.reject(new TypeError('network'));
-    return Promise.resolve(handler(init));
-  };
-  const win = fakeWindow(doc, 'https://app.test/a', fetch);
-  router = startNavigation(win as unknown as Window);
-  return { win, doc, calls };
-}
-
-/** An event the way a browser dispatches it: cancelable, with its target and fields. */
-export function fire(
-  on: EventTarget,
-  type: string,
-  target: unknown,
-  fields: Record<string, unknown> = {},
-): Event {
-  const event = new Event(type, { cancelable: true, bubbles: true });
-  Object.defineProperty(event, 'target', { value: target });
-  for (const [key, value] of Object.entries({
-    button: 0,
-    metaKey: false,
-    ctrlKey: false,
-    shiftKey: false,
-    altKey: false,
-    ...fields,
-  })) {
-    Object.defineProperty(event, key, { value });
-  }
-  on.dispatchEvent(event);
-  return event;
-}
-
-export const click = (win: FakeWindow, id: string, fields?: Record<string, unknown>) =>
-  fire(win, 'click', win.document.getElementById(id), fields);
-
-export const answers = {
-  b: () => htmlAnswer('page:B', page('B')),
-  c: () => htmlAnswer('page:C', page('C')),
-};

package/src/navigation-dom-fixture.ts

@@ -1,424 +0,0 @@
-/**
- * Just enough DOM for the client router's unit tests, written for them the way `hydrate-replay`'s
- * fakes are: elements with attributes and children, the selectors the router uses (tag, `[a]`,
- * `[a="v"]`, `[a~="v"]`, `:not([src])`, comma lists), documents that adopt and swap bodies, a
- * window with history, location and timers, and a `DOMParser` that answers a fetched string with a
- * document the test built. What a browser DOES with a document is proven in Chrome
- * (`packages/cli/e2e/client-navigation-*.e2e.test.ts`); this is the branch coverage beside it.
- */
-
-type Attrs = Readonly<Record<string, string>>;
-
-/** One compound selector: a tag and attribute conditions, optionally excluding a `src`. */
-interface Simple {
-  readonly tag: string;
-  readonly conditions: readonly { name: string; op: string | undefined; value: string }[];
-  readonly notSrc: boolean;
-}
-
-const parse = (selector: string): readonly Simple[] =>
-  selector.split(',').map((part) => {
-    const text = part.trim();
-    const notSrc = text.includes(':not([src])');
-    const clean = text.replace(':not([src])', '');
-    const tag = /^[a-z0-9]*/i.exec(clean)?.[0] ?? '';
-    const conditions = [...clean.matchAll(/\[([\w:-]+)(?:(~?=)"?([^"\]]*)"?)?\]/g)].map((m) => ({
-      name: m[1] ?? '',
-      op: m[2],
-      value: m[3] ?? '',
-    }));
-    return { tag: tag.toUpperCase(), conditions, notSrc };
-  });
-
-const matches = (el: FakeElement, selector: string): boolean =>
-  parse(selector).some(
-    (simple) =>
-      (simple.tag === '' || simple.tag === el.tagName) &&
-      !(simple.notSrc && el.hasAttribute('src')) &&
-      simple.conditions.every(({ name, op, value }) => {
-        const said = el.getAttribute(name);
-        if (said === null) return false;
-        if (op === undefined) return true;
-        if (op === '~=') return said.split(/\s+/).includes(value);
-        return said === value;
-      }),
-  );
-
-export class FakeElement {
-  readonly tagName: string;
-  readonly attrs = new Map<string, string>();
-  children: FakeElement[] = [];
-  parentElement: FakeElement | null = null;
-  ownerDocument: FakeDocument;
-  text = '';
-  style: Record<string, string> = {};
-  nonce = '';
-  async = true;
-  onload: (() => void) | null = null;
-  onerror: (() => void) | null = null;
-  __x?: Promise<unknown>;
-  clicks = 0;
-
-  constructor(
-    doc: FakeDocument,
-    tag: string,
-    attrs: Attrs = {},
-    content: readonly FakeElement[] | string = [],
-  ) {
-    this.ownerDocument = doc;
-    this.tagName = tag.toUpperCase();
-    for (const [name, value] of Object.entries(attrs)) this.attrs.set(name, value);
-    if (typeof content === 'string') this.text = content;
-    else for (const child of content) this.append(child);
-  }
-
-  get id(): string {
-    return this.getAttribute('id') ?? '';
-  }
-  getAttribute(name: string): string | null {
-    return this.attrs.get(name) ?? null;
-  }
-  setAttribute(name: string, value: string): void {
-    this.attrs.set(name, String(value));
-  }
-  removeAttribute(name: string): void {
-    this.attrs.delete(name);
-  }
-  hasAttribute(name: string): boolean {
-    return this.attrs.has(name);
-  }
-  getAttributeNames(): string[] {
-    return [...this.attrs.keys()];
-  }
-  get attributes(): { name: string; value: string }[] {
-    return [...this.attrs].map(([name, value]) => ({ name, value }));
-  }
-  get textContent(): string {
-    return this.text + this.children.map((child) => child.textContent).join('');
-  }
-  set textContent(value: string) {
-    this.text = value;
-    this.children = [];
-  }
-  get className(): string {
-    return this.getAttribute('class') ?? '';
-  }
-  get outerHTML(): string {
-    const attrs = [...this.attrs].map(([n, v]) => ` ${n}="${v}"`).join('');
-    const tag = this.tagName.toLowerCase();
-    return `<${tag}${attrs}>${this.text}${this.children.map((c) => c.outerHTML).join('')}</${tag}>`;
-  }
-  // The properties the router reads and writes on links, scripts and anchors.
-  get href(): string {
-    return new URL(this.getAttribute('href') ?? '', this.ownerDocument.baseURI).href;
-  }
-  set href(value: string) {
-    this.setAttribute('href', value);
-  }
-  set rel(value: string) {
-    this.setAttribute('rel', value);
-  }
-  get target(): string {
-    return this.getAttribute('target') ?? '';
-  }
-  set download(value: string) {
-    this.setAttribute('download', value);
-  }
-  get type(): string {
-    return this.getAttribute('type') ?? '';
-  }
-
-  get connected(): boolean {
-    let at: FakeElement | null = this;
-    while (at.parentElement !== null) at = at.parentElement;
-    return at === this.ownerDocument.documentElement;
-  }
-
-  /** A `src` script or a stylesheet link inserted into the live document "loads". */
-  private loaded(): void {
-    if (!this.connected) return;
-    if (this.tagName === 'SCRIPT')
-      this.ownerDocument.ran.push(this.getAttribute('src') ?? this.text);
-    if (this.tagName === 'SCRIPT' || this.tagName === 'LINK') {
-      const failed = (this.getAttribute('src') ?? this.getAttribute('href') ?? '').includes('fail');
-      queueMicrotask(() => (failed ? this.onerror?.() : this.onload?.()));
-    }
-  }
-
-  append(...nodes: FakeElement[]): void {
-    for (const node of nodes) {
-      node.remove();
-      node.parentElement = this;
-      node.adopt(this.ownerDocument);
-      this.children.push(node);
-      node.loaded();
-    }
-  }
-  remove(): void {
-    const parent = this.parentElement;
-    if (parent === null) return;
-    parent.children = parent.children.filter((child) => child !== this);
-    this.parentElement = null;
-  }
-  replaceWith(node: FakeElement): void {
-    const parent = this.parentElement;
-    if (parent === null) return;
-    node.remove();
-    const index = parent.children.indexOf(this);
-    parent.children.splice(index, 1, node);
-    node.parentElement = parent;
-    this.parentElement = null;
-    node.adopt(parent.ownerDocument);
-    node.loaded();
-  }
-  replaceChild(next: FakeElement, old: FakeElement): void {
-    old.replaceWith(next);
-  }
-  adopt(doc: FakeDocument): void {
-    this.ownerDocument = doc;
-    for (const child of this.children) child.adopt(doc);
-  }
-  contains(node: FakeElement): boolean {
-    for (let at: FakeElement | null = node; at !== null; at = at.parentElement) {
-      if (at === this) return true;
-    }
-    return false;
-  }
-  private descendants(): FakeElement[] {
-    return this.children.flatMap((child) => [child, ...child.descendants()]);
-  }
-  querySelectorAll(selector: string): FakeElement[] {
-    return this.descendants().filter((el) => matches(el, selector));
-  }
-  querySelector(selector: string): FakeElement | null {
-    return this.querySelectorAll(selector)[0] ?? null;
-  }
-  closest(selector: string): FakeElement | null {
-    for (let at: FakeElement | null = this; at !== null; at = at.parentElement) {
-      if (matches(at, selector)) return at;
-    }
-    return null;
-  }
-  focus(): void {
-    this.ownerDocument.activeElement = this;
-  }
-  click(): void {
-    this.clicks += 1;
-  }
-}
-
-/** A form the router's `instanceof HTMLFormElement` accepts once installed as that global. */
-export class FakeForm extends FakeElement {
-  fields: [string, string | File][] = [];
-}
-
-export class FakeDocument extends EventTarget {
-  readonly documentElement: FakeElement;
-  baseURI = 'https://app.test/';
-  activeElement: FakeElement | null = null;
-  /** Every script that "ran": its `src`, or its text for an inline one. */
-  readonly ran: string[] = [];
-  startViewTransition?: (update: () => void) => {
-    updateCallbackDone: Promise<void>;
-    ready: Promise<void>;
-    finished: Promise<void>;
-  };
-
-  constructor(head: readonly FakeElement[] = [], body: readonly FakeElement[] = [], lang = 'en') {
-    super();
-    this.documentElement = new FakeElement(this, 'html', { lang });
-    this.documentElement.append(new FakeElement(this, 'head'), new FakeElement(this, 'body'));
-    this.head.append(...head.map((el) => this.take(el)));
-    this.body.append(...body.map((el) => this.take(el)));
-  }
-  private take(el: FakeElement): FakeElement {
-    el.adopt(this);
-    return el;
-  }
-  get head(): FakeElement {
-    return this.documentElement.children.find((c) => c.tagName === 'HEAD') as FakeElement;
-  }
-  get body(): FakeElement {
-    return this.documentElement.children.find((c) => c.tagName === 'BODY') as FakeElement;
-  }
-  get title(): string {
-    return this.head.querySelector('title')?.textContent ?? '';
-  }
-  set title(value: string) {
-    const el = this.head.querySelector('title');
-    if (el === null) this.head.append(new FakeElement(this, 'title', {}, value));
-    else el.textContent = value;
-  }
-  createElement(tag: string): FakeElement {
-    return new FakeElement(this, tag);
-  }
-  adoptNode(node: FakeElement): FakeElement {
-    node.remove();
-    node.adopt(this);
-    return node;
-  }
-  /** What a test says is under the pointer, for a click the browser aimed at `<html>`. */
-  underPointer: FakeElement | null = null;
-  elementFromPoint(): FakeElement | null {
-    return this.underPointer;
-  }
-  getElementById(id: string): FakeElement | null {
-    return this.documentElement.querySelectorAll('[id]').find((el) => el.id === id) ?? null;
-  }
-  querySelector(selector: string): FakeElement | null {
-    return this.documentElement.querySelector(selector);
-  }
-  querySelectorAll(selector: string): FakeElement[] {
-    return this.documentElement.querySelectorAll(selector);
-  }
-}
-
-/** `h('a', { href: '/b' }, 'b')` — builds an element owned by a scratch document until adopted. */
-const scratch = new FakeDocument();
-export const h = (
-  tag: string,
-  attrs: Attrs = {},
-  content: readonly FakeElement[] | string = [],
-): FakeElement =>
-  tag === 'form'
-    ? new FakeForm(scratch, tag, attrs, content)
-    : new FakeElement(scratch, tag, attrs, content);
-
-/** The head an opted-in document carries, plus whatever the page adds. */
-export const routerHead = (
-  title: string,
-  extra: readonly FakeElement[] = [],
-  meta: { surface?: string; build?: string; scope?: string } = {},
-): FakeElement[] => [
-  h('title', {}, title),
-  h('meta', { name: 'ultimate-navigation', content: meta.surface ?? 'web:app' }),
-  h('meta', { name: 'x-ultimate-build', content: meta.build ?? 'b1' }),
-  ...(meta.scope === undefined ? [] : [h('meta', { name: 'ultimate-scope', content: meta.scope })]),
-  ...extra,
-];
-
-interface HistoryEntry {
-  state: unknown;
-  url: string;
-}
-
-/** A window: location, history (with a back/forward that fires `popstate`), timers, `fetch`. */
-export class FakeWindow extends EventTarget {
-  document: FakeDocument;
-  readonly assigned: string[] = [];
-  readonly entries: HistoryEntry[];
-  index = 0;
-  scrollX = 0;
-  scrollY = 0;
-  reducedMotion = false;
-  navigator: { connection?: { saveData?: boolean; effectiveType?: string } } = {};
-  readonly DOMParser = true;
-  readonly BroadcastChannel = true;
-  fetch: (url: string, init?: RequestInit) => Promise<Response>;
-  __xNavigation?: unknown;
-
-  constructor(doc: FakeDocument, url: string, fetch: FakeWindow['fetch']) {
-    super();
-    this.document = doc;
-    this.entries = [{ state: null, url }];
-    this.fetch = fetch;
-  }
-
-  readonly location = {
-    get href(): string {
-      return self.entries[self.index]?.url ?? '';
-    },
-    assign: (url: string): void => {
-      this.assigned.push(url);
-    },
-  };
-
-  readonly history = {
-    scrollRestoration: 'auto',
-    get state(): unknown {
-      return self.entries[self.index]?.state ?? null;
-    },
-    pushState: (state: unknown, _title: string, url?: string): void => {
-      this.entries.splice(this.index + 1);
-      this.entries.push({ state, url: url ?? this.location.href });
-      this.index += 1;
-    },
-    replaceState: (state: unknown, _title: string, url?: string): void => {
-      this.entries[this.index] = { state, url: url ?? this.location.href };
-    },
-  };
-
-  /** Back or forward, as a browser does it: the entry moves, then `popstate` fires. */
-  go(delta: number): void {
-    this.index += delta;
-    this.dispatchEvent(Object.assign(new Event('popstate'), { state: this.history.state }));
-  }
-
-  scrollTo(options: { left: number; top: number }): void {
-    this.scrollX = options.left;
-    this.scrollY = options.top;
-  }
-  matchMedia(): { matches: boolean } {
-    return { matches: this.reducedMotion };
-  }
-  setTimeout(fn: () => void, ms?: number): number {
-    return globalThis.setTimeout(fn, ms) as unknown as number;
-  }
-  clearTimeout(id: number | undefined): void {
-    globalThis.clearTimeout(id);
-  }
-}
-
-// `location` and `history` are object literals whose getters need the window; `self` is set per
-// instance by `fakeWindow`, one window per test.
-let self: FakeWindow;
-
-/** The window a test drives; installs the three globals the router reaches for by name. */
-export function fakeWindow(doc: FakeDocument, url: string, fetch: FakeWindow['fetch']): FakeWindow {
-  self = new FakeWindow(doc, url, fetch);
-  const globals = globalThis as unknown as Record<string, unknown>;
-  globals['DOMParser'] = FakeParser;
-  globals['HTMLFormElement'] = FakeForm;
-  globals['FormData'] = FakeFormData;
-  globals['HTMLElement'] = FakeElement;
-  return self;
-}
-
-/** Documents a `DOMParser` answers, keyed by the HTML string a fake `fetch` returned. */
-export const parsed = new Map<string, FakeDocument>();
-
-class FakeParser {
-  parseFromString(html: string): FakeDocument {
-    const doc = parsed.get(html);
-    if (doc === undefined) throw new TypeError(`no fake document registered for ${html}`);
-    return doc;
-  }
-}
-
-const RealFormData = globalThis.FormData;
-class FakeFormData extends RealFormData {
-  constructor(form?: FakeForm, submitter?: FakeElement | null) {
-    super();
-    for (const [name, value] of form?.fields ?? []) this.append(name, value);
-    const name = submitter?.getAttribute('name');
-    if (name !== undefined && name !== null)
-      this.append(name, submitter?.getAttribute('value') ?? '');
-  }
-}
-
-/** A registered page: `answer('/b', doc)` is what the fake fetch returns for `/b`. */
-export function htmlAnswer(key: string, doc: FakeDocument, init: ResponseInit = {}): Response {
-  parsed.set(key, doc);
-  return new Response(key, {
-    ...init,
-    headers: {
-      'content-type': 'text/html; charset=utf-8',
-      ...(init.headers as Record<string, string>),
-    },
-  });
-}
-
-/** Lets queued microtasks and a few macrotasks run — a swap awaits loads, transitions, scripts. */
-export const settle = async (ms = 5): Promise<void> => {
-  for (let i = 0; i < 5; i += 1) await new Promise((resolve) => setTimeout(resolve, ms));
-};