@ultimat3/render 22.15.0 → 24.0.0

package/CLAUDE.md

@@ -33,7 +33,7 @@ axiom 6). Never `cli` (upward).
 | Type claims | `type-pins.tsx`, never a `.test.ts` — `tsconfig.json` excludes tests. `.tsx` so the island-as-JSX claim is checked against the JSX an author writes. |
 | Descriptor `meta` / `load` | always `(x) => Promise<…>`. Authors may declare either sync; consumers never branch. |
 | Descriptor `budget` | always an object, `{}` when undeclared. `budget.js === undefined` is the site/ hydration failure. |
-| `RouteBudget` keys | **`js` and `lcp` only, and every key is PROJECTED** (`budgetJs`, `budgetLcp`). `type-pins.tsx` derives the allowed set from `RouteDescriptor`'s `budget*` keys, so an unprojected key is a build error; `scripts/declaration-readers.ts` finds the class across every declaration. |
+| `RouteBudget` keys | **`js` only, PROJECTED as `budgetJs`** — `lcp` went with `budgetLcp`, measured by nothing. `assertModeInvariants` refuses any other key that arrives by a cast (`X_ROUTE_MODE_INVALID`); `type-pins.tsx` derives the allowed set from `RouteDescriptor`'s `budget*` keys, so an unprojected key is a build error; `scripts/declaration-readers.ts` finds the class across every declaration. |
 | No `describe()` on a route | `describeRoutes()` is the one route list. |
 | Mode invariants | `modes.ts` only; never inline a mode check in a render-\* file. **Four modes, and every one renders the route's component.** A fifth mode has to name the function that renders it. |
 | Island declaration | `island({ src })` — a **specifier**, never an import, so a `static` page's graph cannot grow the island's dependencies. Never add an overload that takes a component. |
@@ -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). |
@@ -70,8 +71,12 @@ axiom 6). Never `cli` (upward).
 | "Is this a TTL?" has one reader | `parseTtlMs` in `duration.ts`, below `modes.ts` and `render-isr.ts`. |
 | A build-time frame reads a throw with `renderThrowable` | `render-html.ts`, `render-static.ts`, `css-modules.ts`, `module-loader.ts`, `route-data.ts`. `bun run error-render` cannot see a value laundered through a local helper. |
 | `X_ROUTE_LOAD_FAILED` computes its pathname BEFORE the try | `pathnameOf` never throws on a relative `ctx.url`. |
-| The ISR key | `isrKey(url, locale)` — pathname, the negotiated locale in the reserved `__x_locale` parameter, then the sorted query. The locale is REQUIRED. The time zone is deliberately not a dimension. `toResult` emits `vary: accept-language`; the rest of the shared key is `@ultimat3/http`'s `cache-headers` stage. |
+| The ISR key | `isrKey(url, locale)` — pathname, the negotiated locale in the reserved `__x_locale` parameter, then the sorted query. The locale is REQUIRED. The time zone is deliberately not a dimension. `toResult` emits `vary: accept-language`, and `surrogate-key`/`cache-tag` from `@ultimat3/cache`'s `surrogateKeys()` over the route's `revalidateTags` — kept only while the response stays shared: http's `applyCacheHeaders` strips both on a rewrite to `private`/`no-store`. `registry.ts`'s `assertPurgeableTags` screens the tags at registration (`X_ROUTE_MODE_INVALID`); the rest of the shared key is `@ultimat3/http`'s `cache-headers` stage. The one shipped emitter of purge keys; file and mounted routes are both screened, so `toResult` never refuses on the request path |
 | A bust that lands MID-render | fenced with `@ultimat3/cache`'s `sampleFence({ key, tags })`, taken before `render()` and asked before `store.set`. `registerPath` runs BEFORE the render. |
+| ISR regeneration | `@ultimat3/core`'s `createSingleFlight`, `deadlineMs` = `regenerateDeadlineMs` (`DEFAULT_ISR_REGENERATE_DEADLINE_MS`, 30 s; `finiteCount` ≥ 1, no opt-out), `schedule` injectable. Past it the PATH is free; the hung render runs on, and `latest` (by identity) drops its result once a newer run started. `render-isr-flight.test.ts`, on a hand-fired scheduler. |
+| Which route a stored ISR path is | exact path first, else the MOST SPECIFIC pattern: `route-pattern.ts`'s `compilePattern` (never a second compiler), sorted on `CompiledPattern.specificity`. Never table order: `describeRoutes()` sorts `*` before `:`. |
+| `CompiledPattern.specificity` | the ONE ordering rule, read by ISR, `@ultimat3/cli`'s sitemap extras and `@ultimat3/admin`'s `adminRouteMatch`: `@ultimat3/core`'s `routeRank(path)` — the request trie's order as one integer, shared with `@ultimat3/pwa`'s worker rule order. Never a local rank. |
+| `compilePattern`'s regex | a `*catch-all` owns its separator, `(?:/(.*))?`, so the bare prefix `static-path.ts` writes for an empty rest (`/docs`) matches; a literal character matches raw OR percent-encoded, either hex case — a store key is `URL.pathname`, and `precios-españa` arrives as `precios-espa%C3%B1a`. `route-pattern.test.ts`. |
 | Marking a page stale | `IsrStore.markStale(path)`, in place — never `set({ ...entry, stale: true })` (`set` means "just generated" and orders eviction). |
 | ISR store bound | `memoryIsrStore()` caps at `DEFAULT_ISR_MAX_ENTRIES` (1,000), least recently generated first. |
 | A `RenderResult.status` | `finiteStatus(subject, status)` (`finite-status.ts`), 200–599 whole, at every site that takes one from a caller; `isRenderStatus` is the TOTAL read of a stored `IsrEntry.status`. The name carries `finite` so `bun run finite-bounds` recognises it. |
@@ -88,22 +93,26 @@ 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. |
+| Escaping | `html.ts` only — including `render-stream.ts`'s `holeMarker`, its default `errorFallback` and `revealChunk` (`JSON.stringify`), and `head.ts`'s `themeScript`. `escapeHtml` — text and attributes alike, five characters — is `@ultimat3/core`'s, re-exported by `html.ts`; `bun run flight-copies` refuses a second table (`X_HELPER_COPY`). |
+| Script and style CONTENT | never raw: `escapeHtml`, `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. |
+| CSS-module scoping | `scopeClasses` rewrites class selectors in qualified-rule PRELUDES only (`inPreludes`) — never a declaration (`local(Inter.Regular)`), a comment or an at-rule prelude; a class is a whole CSS identifier, escapes included, and the map key is its unescaped name. The suffix hashes the basename + the COMPILED CSS, so two modules with one source and different partials never share a class name. |
+| 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. |
 | `<head>` binding | `head.ts` stays injection-only; `head-seo.ts` is the ONE binding of `HeadRenderers` to `@ultimat3/seo`. |
 | Client navigation | `navigation*.ts` — soft navigation over server-rendered documents, NOT a mode: the router renders nothing, it swaps the document the route already rendered. Rules are pure (`navigation-rules.ts`: `linkVerdict`, `formVerdict`, `responseVerdict`, `mayPrefetch`) and unit-tested; the DOM half (`navigation-swap.ts`, `navigation.ts`) is proven in Chrome by `packages/cli/e2e/client-navigation-*.e2e.test.ts`. `./navigation` (`navigation-entry.ts`) is the script the CLI builds; importing it starts it, and a document without `ultimate-navigation` is never intercepted. |
+| Router ↔ the page's lifecycle | `navigation-scroll.ts` owns `scrollRestoration = 'manual'` and RESTORES the entry's saved offset at start, before its first save (a reload, or Back after a full load); `navigation-tabs.ts` owns the `BroadcastChannel`, closed on `pagehide` (it blocks the back/forward cache), reopened and the cache emptied on a persisted `pageshow`. A sheet `loadStylesheets` appends is `owned` at once, so an aborted navigation's sheets are retired by the next swap. A view transition is tracked by identity: an older one finishing never clears the running one. |
 | Router ↔ islands | ONE bootstrap: the swap re-runs the inline hydration runtime, whose `each` visits a root once per tab (`el.__v`). Never add a second mount path for the router. Dispose = call what `el.__x` resolved to. |
 | Router head diff | only elements a SERVER document put in `<head>` (`documentHead`'s set) may be removed; a script-added one is the tab's. Scripts and stylesheets are never diffed. |
-| Router: nothing is sent twice | the router follows no redirect (`redirect: 'manual'`; the server hands it over as `204` + `x-ultimate-location`), never re-submits a POST (a failure is `ultimate:navigation-error`), and hands a non-page answer to the browser from the bytes it already has. Its cache never answers with a non-2xx, a hand-over, or a `no-store` page older than 5 s, and is emptied by any POST, `onClientWrite`, `onRescope` and a `BroadcastChannel` message from another tab. |
+| Router: nothing is sent twice | the router follows no redirect (`redirect: 'manual'`; the server hands it over as `204` + `x-ultimate-location`), never re-submits a POST (a failure is `ultimate:navigation-error`), and hands a non-page answer to the browser from the bytes it already has. Its cache never answers with a non-2xx, a hand-over, or a `no-store` page older than 5 s, and is emptied by any POST (when sent AND when it settles), `onClientWrite`, `onRescope` and a `BroadcastChannel` message from another tab. |
 
 Cross-package: `@ultimat3/pwa` consumes route descriptors as **data**, never by import.
 Keep `RouteDescriptor` additive — removing a field breaks `sw.js` generation.

package/README.md

@@ -16,7 +16,7 @@ export const config = defineRoute({
   prerender:  () => db.posts.slugs(),
   offline:    'precache',             // precache | runtime | network-only
   hydrate:    'visible',              // idle | visible | interaction | never
-  budget:     { js: '40kb', lcp: 2000 },
+  budget:     { js: '40kb' },
   load:       ({ params }) => db.posts.bySlug(params.slug),   // once per render
   meta:       ({ data, url }) => ({ title: data.title, description: data.excerpt,
                                     og: { image: data.cover }, canonical: url,
@@ -131,7 +131,7 @@ registered under is `X_ROUTE_POST_INVALID` at boot, as is `post` on a `static` p
 | Mode | Invariant | Error if violated |
 |---|---|---|
 | `static` | no per-request state — no `policy`, no `revalidate` | `X_ROUTE_MODE_INVALID` |
-| `isr` | needs a trigger: `revalidate.tags` or `revalidate.ttl`; **no `policy`** — one cached document per URL cannot answer two actors | `X_ROUTE_MODE_INVALID` |
+| `isr` | needs a trigger: `revalidate.tags` or `revalidate.ttl`; **no `policy`** — one cached document per URL cannot answer two actors; every `revalidate.tags` entry must be a purgeable CDN key (no whitespace, no comma) | `X_ROUTE_MODE_INVALID` |
 | `ssr` | cannot be prerendered | `X_ROUTE_MODE_INVALID` |
 | any but `ssr` | declares no `cache` — `static`/`isr` headers are the mode, a `stream` is always `private, no-store` | `X_ROUTE_MODE_INVALID` |
 | gated (`policy`) | its `cache` is never `public`/`immutable` — one actor's document in a shared cache | `X_ROUTE_MODE_INVALID` |
@@ -152,7 +152,7 @@ sorted, JSON-safe descriptor list. Every downstream generator reads that one tab
 | `site/pricing/page.tsx` | `/pricing` |
 | `site/(marketing)/about/page.tsx` | `/about` |
 | `site/blog/[slug]/page.tsx` | `/blog/:slug` |
-| `site/docs/[...path]/page.tsx` | `/docs/*path` |
+| `site/docs/[...path]/page.tsx` | `/docs/*path` — `compilePattern` matches the bare `/docs` too, the path the static build writes for an empty rest |
 | `app/dashboard/page.tsx` | `/dashboard` |
 | `api/posts/route.ts` | `/api/posts` |
 
@@ -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 |
+| `mergeHead`, `renderHead`, `themeScript` | `<head>` merge + the one inlined script; it stamps `data-theme` and, beside it, the fallback itself as `data-theme-default` for `@ultimat3/ui`'s `clearTheme`/`watchOsTheme` |
+| `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
 
@@ -512,7 +516,21 @@ a job boundary the class is gone and the `code` is what survives — match on th
   framework's `Revalidator`, and the function it returns releases **both** halves — the
   dependents and the revalidator slot, the latter only while it is still this controller's.
   The default store (`memoryIsrStore`) is capped at `DEFAULT_ISR_MAX_ENTRIES` (1,000) pages,
-  least recently generated evicted first.
+  least recently generated evicted first. One regeneration holds its page for at most
+  `DEFAULT_ISR_REGENERATE_DEADLINE_MS` (30 s; `createIsrController({ regenerateDeadlineMs })`),
+  so a render that never settles no longer pins the page for the life of the process. A stored
+  path takes its TTL and tags from the most specific matching route (static > `:param` >
+  `*catch-all`, per segment), never the first in table order.
+- **A tag-revalidated ISR document carries its purge keys while it is shared-cacheable**,
+  `As of 2026-10-02` — `@ultimat3/http`'s `cache-headers` stage rewrites the response to `private`
+  for a signed-in visitor and strips both headers: `Surrogate-Key`
+  (space-joined) and `Cache-Tag` (comma-joined) from `@ultimat3/cache`'s `surrogateKeys()` over
+  the route's `revalidate.tags` — `revalidate: { tags: [tag.post] }` answers `post e:post` — on a
+  miss, a hit and a served-stale response alike. That is what lets the same `invalidates` purge
+  the document at the CDN; before it, the edge held every ISR page for its whole `s-maxage`. A
+  TTL-only route carries neither header. A tag a CDN would split (whitespace, a comma) is refused
+  when the route registers — `X_ROUTE_MODE_INVALID`, naming the file — for file routes and
+  mounted routes both.
 - **`stream`** flushes the shell first, then reveals holes in completion order with a
   ~200-byte inline script. A client that disconnects mid-stream cancels it: `StreamHole.resolve`
   is handed an `AbortSignal` so the work stops, and nothing more is enqueued. Solid's compiled templates and signals mean the shell costs zero

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/render",
-  "version": "22.15.0",
+  "version": "24.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": "24.0.0",
+    "@ultimat3/core": "24.0.0",
+    "@ultimat3/http": "24.0.0",
+    "@ultimat3/i18n": "24.0.0",
+    "@ultimat3/seo": "24.0.0",
     "sass": "1.104.0"
   }
 }

package/src/asset.ts

@@ -6,6 +6,7 @@
  * `island({ src })` does. The table is the CLI's (`site-assets.ts`); this file holds only the seam.
  */
 
+import { renderCauseValue } from '@ultimat3/core';
 import { AssetMissingError } from './errors';
 
 /**
@@ -48,6 +49,8 @@ const EXTENSIONS: ReadonlySet<string> = new Set(ASSET_EXTENSIONS);
  * refused here, before any disk is asked.
  */
 export function assetPathProblem(path: string): string | undefined {
+  // Typed, but a JS caller or a Sass `asset()` can still hand over anything: a refusal, not a crash.
+  if (typeof path !== 'string') return `${renderCauseValue(path)} is not a path`;
   if (path.includes('\\')) return `"${path}" contains a backslash`;
   const segments = path.split('/');
   if (segments[0] !== ASSET_DIR || segments.length < 2) {
@@ -94,14 +97,14 @@ export function asset(path: AssetPath): string {
   const problem = assetPathProblem(path);
   if (problem !== undefined) {
     throw new AssetMissingError(
-      `asset(${JSON.stringify(path)}): ${problem}`,
+      `asset(${renderCauseValue(path)}): ${problem}`,
       `name a file under apps/web/site/${ASSET_DIR}/ with one of: ${ASSET_EXTENSIONS.join(', ')}`,
     );
   }
   const resolver = holder[RESOLVER_SLOT];
   if (resolver === undefined) {
     throw new AssetMissingError(
-      `asset(${JSON.stringify(path)}) ran with no site asset table installed — in a browser (an island), or in a test that never loaded the app`,
+      `asset(${renderCauseValue(path)}) ran with no site asset table installed — in a browser (an island), or in a test that never loaded the app`,
       'call asset() in the page and pass the URL to the island as a prop; a unit test installs a table with setAssetResolver((path) => "/" + path)',
     );
   }

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/css-modules.ts

@@ -78,10 +78,21 @@ const partialCandidates = (target: string): readonly string[] => {
   ];
 };
 
-/** Strings and `url()` payloads may contain a `.` that is not a class selector. */
-const PROTECTED = /"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|url\([^)]*\)/g;
-/** A class selector: a dot followed by an identifier start. `0.5rem` cannot match — `5` is not one. */
-const CLASS_SELECTOR = /\.(-?[A-Za-z_][\w-]*)/g;
+/** Strings, `url()` payloads and comments may contain a `.` that is not a class selector. */
+const PROTECTED = /"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|url\([^)]*\)|\/\*[\s\S]*?\*\//g;
+/** One CSS escape: up to six hex digits and the whitespace that ends them, or any other char. */
+const ESCAPE = String.raw`\\[0-9a-fA-F]{1,6}[ \t\n]?|\\[^\n\r\f0-9a-fA-F]`;
+const NAME_START = String.raw`(?:[A-Za-z_\u0080-\uffff]|${ESCAPE})`;
+const NAME_CHAR = String.raw`(?:[\w\-\u0080-\uffff]|${ESCAPE})`;
+/**
+ * A class selector: a dot, then a whole CSS identifier — escapes included, so `.w-1\.5` is ONE
+ * class, where `[\w-]*` split it into a scoped `w-1` and a stray `.5`. `0.5rem` cannot match: `5`
+ * starts no identifier.
+ */
+const CLASS_SELECTOR = new RegExp(
+  String.raw`\.(-?${NAME_START}${NAME_CHAR}*|--${NAME_CHAR}*)`,
+  'g',
+);
 /**
  * The mask delimiter. NUL is the one byte CSS cannot contain, so the restore pass cannot mistake
  * a real declaration for a placeholder — a bare numeric marker would collide with `flex:1 1 0`.
@@ -140,6 +151,11 @@ export function scopeClasses(
   suffix: string,
 ): { readonly css: string; readonly classes: Record<string, string> } {
   const classes: Record<string, string> = {};
+  const scopeSelector = (selector: string): string =>
+    selector.replace(CLASS_SELECTOR, (_match, name: string) => {
+      classes[unescapeName(name)] = `${unescapeName(name)}_${suffix}`;
+      return `.${name}_${suffix}`;
+    });
   const literals: string[] = [];
   const mask = (match: string): string => {
     literals.push(match);
@@ -148,11 +164,7 @@ export function scopeClasses(
   // Strings and `url()` first, so a `:global(` inside a `content:` string is never unwrapped;
   // then each `:global()` payload joins the same mask and comes back unscoped.
   const masked = unwrapGlobal(css.replace(PROTECTED, mask), mask);
-  const scoped = masked.replace(CLASS_SELECTOR, (_match, name: string) => {
-    const local = `${name}_${suffix}`;
-    classes[name] = local;
-    return `.${local}`;
-  });
+  const scoped = inPreludes(masked, scopeSelector);
   // Recursive: a `:global()` payload is masked AFTER the strings inside it were, so its literal
   // holds their placeholders — one pass restored `html[data-theme='light']` as
   // `html[data-theme=\0 0 \0]`, a selector that matched nothing. A literal only ever holds
@@ -167,6 +179,39 @@ export function scopeClasses(
   return { css: restore(scoped), classes };
 }
 
+/**
+ * `rewrite` applied to every qualified rule's prelude — the text before a `{` that is not an
+ * at-rule's — and nothing else. A declaration ends at `;` or `}` and never reaches it: a font's
+ * `local(Inter.Regular)` is not a class. The strings, comments and `url()`s are masked by then, so
+ * no brace in this text is quoted.
+ */
+function inPreludes(css: string, rewrite: (selector: string) => string): string {
+  let out = '';
+  let start = 0;
+  for (let at = 0; at < css.length; at += 1) {
+    const char = css[at];
+    if (char !== '{' && char !== '}' && char !== ';') continue;
+    const segment = css.slice(start, at);
+    out += char === '{' && !segment.trimStart().startsWith('@') ? rewrite(segment) : segment;
+    out += char;
+    start = at + 1;
+  }
+  return out + css.slice(start);
+}
+
+/** A class name as `class=""` spells it: every CSS escape resolved, a bad code point as U+FFFD. */
+function unescapeName(name: string): string {
+  return name.replace(
+    /\\([0-9a-fA-F]{1,6})[ \t\n]?|\\(.)/g,
+    (_match, hex?: string, char?: string) => {
+      if (hex === undefined) return char ?? '';
+      const point = Number.parseInt(hex, 16);
+      const valid = point > 0 && point <= 0x10ffff && (point < 0xd800 || point > 0xdfff);
+      return String.fromCodePoint(valid ? point : 0xfffd);
+    },
+  );
+}
+
 /** The fix line for a stylesheet that names tokens `@ultimat3/ui/tokens` does not export. */
 const TOKEN_FIX =
   "@ultimat3/ui/tokens exports functions and mixins — space(4), radius(md), role('surface-raised'), " +
@@ -312,7 +357,9 @@ export function compileStylesheet(file: string, source: string): CompiledStylesh
   }
   if (!isCssModule(file)) return { css, classes: {}, dependencies };
   // Content-addressed, not path-addressed: a checkout at a different absolute path must produce
-  // byte-identical CSS, which a hash over the absolute filename would not.
-  const scoped = scopeClasses(css, contentHash(`${file.split('/').pop() ?? file} ${source}`));
+  // byte-identical CSS, which a hash over the absolute filename would not. The COMPILED CSS, not
+  // the source: two `page.module.scss` with one source and different `@use`d partials hashed
+  // alike, emitted one class name with two bodies, and the later sheet won on both pages.
+  const scoped = scopeClasses(css, contentHash(`${file.split('/').pop() ?? file} ${css}`));
   return { css: scoped.css, classes: scoped.classes, dependencies };
 }

package/src/duration.ts

@@ -18,11 +18,19 @@ const DURATION_UNITS: ReadonlyMap<string, number> = new Map([
 /** `'5m'` → 300000. Numbers pass through as milliseconds. */
 export function parseTtlMs(ttl: string | number | null | undefined): number | null {
   if (ttl === null || ttl === undefined) return null;
-  if (typeof ttl === 'number') return Number.isFinite(ttl) && ttl > 0 ? ttl : null;
+  if (typeof ttl === 'number') return positiveMs(ttl);
+  // Typed away, reachable from JS: `modes.ts` asks this of an unvalidated `revalidate.ttl`.
+  if (typeof ttl !== 'string') return null;
   const match = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/.exec(ttl.trim());
   const amount = match?.[1];
   const unit = match?.[2];
   if (amount === undefined || unit === undefined) return null;
   const factor = DURATION_UNITS.get(unit);
-  return factor === undefined ? null : Number(amount) * factor;
+  return factor === undefined ? null : positiveMs(Number(amount) * factor);
 }
+
+/**
+ * Both arms end here, so `'0s'` and `0` cannot disagree: a zero-length TTL registered, and
+ * `entryTtlMs` then read the stored `0` as tag-only — a page declared to expire never did.
+ */
+const positiveMs = (ms: number): number | null => (Number.isFinite(ms) && ms > 0 ? ms : null);

package/src/errors.ts

@@ -43,7 +43,7 @@ export const RENDER_ERROR_TITLES: Readonly<Record<RenderErrorCode, string>> = {
   X_ROUTE_LOAD_FAILED: "a route's load threw while resolving its data",
   X_ROUTE_STATUS_INVALID: 'a route answered a status a rendered page cannot carry',
   X_SURFACE_BOUNDARY: 'a surface imported across the hard boundary',
-  X_BUDGET_EXCEEDED: 'a route blew its JS or LCP budget',
+  X_BUDGET_EXCEEDED: 'a route blew its JS budget',
   X_PRERENDER_FAILED: 'a prerendered path threw during build',
   X_ISLAND_INVALID: 'an island declaration cannot become a client entry',
   X_ISLAND_PROPS_INVALID: 'an island was passed props it cannot carry to the browser',
@@ -163,7 +163,7 @@ export class SurfaceBoundaryError extends UltimateError {
   }
 }
 
-/** A route's measured JS/LCP exceeded its declared `budget`. */
+/** A route's measured JS exceeded its declared `budget`. */
 export class BudgetExceededError extends UltimateError {
   static readonly code = 'X_BUDGET_EXCEEDED' as const;
   constructor(cause: string, fix: string) {

package/src/head.ts

@@ -11,13 +11,7 @@ import { finiteCount } from '@ultimat3/core';
 import type { RouteMeta } from '@ultimat3/seo';
 import { BudgetExceededError } from './errors';
 // `html.ts` is this package's one escaper — a second one is how a character ends up missing.
-import {
-  escapeAttribute,
-  escapeJsonContent,
-  escapeRawTextContent,
-  escapeText,
-  isAttributeName,
-} from './html';
+import { escapeHtml, escapeJsonContent, escapeRawTextContent, isAttributeName } from './html';
 
 export type HeadTagKind = 'title' | 'base' | 'meta' | 'link' | 'script' | 'style';
 
@@ -125,7 +119,7 @@ function renderTag(tag: HeadTag): string {
   const attrs = Object.entries(tag.attrs ?? {})
     .filter(([name]) => isAttributeName(name))
     .map(([name, value]) =>
-      value === true ? ` ${name}` : ` ${name}="${escapeAttribute(String(value))}"`,
+      value === true ? ` ${name}` : ` ${name}="${escapeHtml(String(value))}"`,
     )
     .join('');
   if (VOID_KINDS.has(tag.kind)) return `<${tag.kind}${attrs}>`;
@@ -141,7 +135,7 @@ function renderTag(tag: HeadTag): string {
  * reaching `meta.ld` — a title, a product name, a bio — able to close the element.
  */
 function contentOf(tag: HeadTag, raw: string): string {
-  if (tag.kind !== 'script' && tag.kind !== 'style') return escapeText(raw);
+  if (tag.kind !== 'script' && tag.kind !== 'style') return escapeHtml(raw);
   return carriesJson(tag) ? escapeJsonContent(raw) : escapeRawTextContent(raw);
 }
 
@@ -204,10 +198,15 @@ export function themeScriptBody(options: ThemeScriptOptions = {}): string {
   // string in a `<script>` body, where one `"` ends the string and the rest is code the page runs.
   // Author-supplied today — the same status every `emitIslandAttributes` value had before it was
   // routed through `html.ts`. The element's own raw-text rule is applied by `renderTag` below.
+  // The fallback itself goes on the document too, OUTSIDE the `try`: a storage read that throws
+  // still leaves the app's own opinion where `@ultimat3/ui`'s `clearTheme` / `watchOsTheme` read
+  // it, so a fixed `theme.defaultMode` is never overridden by an OS flip or a "system" pick.
   return (
+    `var d=document.documentElement;` +
+    `d.setAttribute(${JSON.stringify(`${attribute}-default`)},${JSON.stringify(fallback)});` +
     `try{var s=localStorage.getItem(${JSON.stringify(storageKey)}),` +
     `t=s==="light"||s==="dark"?s:${otherwise};` +
-    `document.documentElement.setAttribute(${JSON.stringify(attribute)},t)}catch(e){}`
+    `d.setAttribute(${JSON.stringify(attribute)},t)}catch(e){}`
   );
 }
 

package/src/html.ts

@@ -1,11 +1,11 @@
 /**
- * HTML text and attribute serialization for the server renderer. Escaping lives here and only
- * here: a second escaper is how one of them ends up missing a character, and a missing character
- * in an attribute is an injection.
+ * HTML text and attribute serialization for the server renderer. The character table is
+ * `@ultimat3/core`'s `escapeHtml`, reached from here and nowhere else in this package: a second
+ * escaper is how one of them ends up missing a character, and a missing character in an attribute
+ * is an injection.
  */
 
-import { safeUrl, URL_ATTRIBUTES } from '@ultimat3/core';
-import { escapeAttribute } from '@ultimat3/seo';
+import { escapeHtml, safeUrl, URL_ATTRIBUTES } from '@ultimat3/core';
 import type { JsxProps } from './jsx';
 
 /** Elements that never carry children, so the writer must not emit a closing tag. */
@@ -26,21 +26,15 @@ export const VOID_ELEMENTS: ReadonlySet<string> = new Set([
   'wbr',
 ]);
 
-export function escapeText(value: string): string {
-  return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
-}
-
 /**
- * Re-exported, never re-implemented: `@ultimat3/seo` (tier 1) owns the one attribute escaper, and
- * the copy that lived here was a second place for a character to go missing. It stays reachable
- * from `./html` so this module remains the single import site every render-* file already uses —
- * one implementation, one place to look.
+ * Re-exported, never re-implemented: one set of five characters for text AND attributes, so a
+ * value is inert wherever it lands. Every render-* file escapes through this import.
  */
-export { escapeAttribute };
+export { escapeHtml };
 
 /**
  * `<script>` and `<style>` hold RAW TEXT: a character reference is not decoded inside them, so
- * `escapeText` there would ship `&lt;` to a JS or CSS parser and corrupt the code without closing
+ * `escapeHtml` there would ship `&lt;` to a JS or CSS parser and corrupt the code without closing
  * the hole. What actually ends the element is `</` followed by its tag name, and — inside a script
  * only — `<!--` switches the tokenizer into the escaped state where the element's own `</script>`
  * no longer closes it and the rest of the document becomes script text.
@@ -113,7 +107,7 @@ const URL_BEARING_ATTRIBUTES: ReadonlySet<string> = new Set([
 
 /**
  * Attributes that carry MARKUP, not text or a URL, and are therefore never emitted. `srcdoc` is
- * entity-DECODED and then parsed as HTML, so `escapeAttribute`'s `&lt;script&gt;` becomes a live
+ * entity-DECODED and then parsed as HTML, so an escaped `&lt;script&gt;` becomes a live
  * `<script>` inside the iframe — on this origin, with this session's cookie. Escaping cannot make
  * it inert, so the attribute is refused instead, the same way `innerHTML` above stays the one
  * explicit escape hatch rather than a prop anyone can spread in from a row.
@@ -167,7 +161,7 @@ export function attributePair(name: string, value: unknown): string | null {
   if (value === true) return attribute;
   if (attribute === 'style') {
     const style = styleValue(value);
-    return style === null ? null : `style="${escapeAttribute(style)}"`;
+    return style === null ? null : `style="${escapeHtml(style)}"`;
   }
   const text = String(value);
   // Escaping makes a value inert inside the quotes; it cannot make a SCHEME inert, because
@@ -178,9 +172,9 @@ export function attributePair(name: string, value: unknown): string | null {
   if (URL_BEARING_ATTRIBUTES.has(attribute.toLowerCase())) {
     const url = safeUrl(text, attribute.toLowerCase());
     if (url === null) return null;
-    return `${attribute}="${escapeAttribute(url)}"`;
+    return `${attribute}="${escapeHtml(url)}"`;
   }
-  return `${attribute}="${escapeAttribute(text)}"`;
+  return `${attribute}="${escapeHtml(text)}"`;
 }
 
 export function renderAttributes(props: JsxProps): string {

package/src/hydrate.ts

@@ -7,7 +7,7 @@
 
 import type { HydrateStrategy } from '@ultimat3/core';
 import { HYDRATE_STRATEGIES } from '@ultimat3/core';
-import { escapeAttribute, escapeJsonContent } from './html';
+import { escapeHtml, escapeJsonContent } from './html';
 
 export interface IslandDirective {
   /** Unique per INSTANCE: two of the same island on a page need two prop bags to find. */
@@ -61,7 +61,7 @@ export function emitIslandAttributes(directive: IslandDirective): string {
   // and the rest of the string is markup. Author-controlled today — which is why it costs nothing
   // to route through the ONE escaper now, rather than after a build id or a prop-derived margin
   // starts carrying something the author did not type.
-  const attr = (name: string, value: string): string => `${name}="${escapeAttribute(value)}"`;
+  const attr = (name: string, value: string): string => `${name}="${escapeHtml(value)}"`;
   const attrs = [
     attr('data-x-island', directive.islandId),
     attr('data-x-hydrate', directive.strategy),
@@ -89,7 +89,7 @@ export function emitIslandProps(directive: IslandDirective): string {
     // The id goes through the SAME escaper every other attribute in this file does. Safe today —
     // `islandModuleId` reduces to `[a-z0-9-]` — which is exactly why it costs nothing to route it
     // now, rather than after an id starts being derived from something an author did not type.
-    `<script type="application/json" data-x-props="${escapeAttribute(directive.islandId)}">` +
+    `<script type="application/json" data-x-props="${escapeHtml(directive.islandId)}">` +
     `${escapeJsonContent(JSON.stringify(directive.props))}</script>`
   );
 }

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,
@@ -153,16 +155,18 @@ export {
 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,
@@ -199,6 +203,8 @@ export {
 export type { RouteComponent } from './route-component';
 export { pageComponentOf } from './route-component';
 export { metaContextFor, routeDataFor } from './route-data';
+export type { CompiledPattern } from './route-pattern';
+export { compilePattern } from './route-pattern';
 export { routeStatusOf, withStatus } from './route-status';
 export type { SpeculationRules } from './speculation-rules';
 export {

package/src/island-collector.ts

@@ -5,6 +5,7 @@
  */
 
 import type { HydrateStrategy } from '@ultimat3/core';
+import { renderCauseValue } from '@ultimat3/core';
 import { IslandInvalidError, IslandNotHydratedError } from './errors';
 import type { IslandDirective } from './hydrate';
 import { DEFAULT_REPLAY_EVENTS } from './hydrate';
@@ -131,7 +132,7 @@ function assertHydrates(strategy: HydrateStrategy, spec: IslandSpec, file: strin
 function assertEntry(entry: string, spec: IslandSpec, file: string): void {
   if (isEmittableSpecifier(entry)) return;
   throw new IslandInvalidError(
-    `the resolver returned ${JSON.stringify(entry)} for the ${spec.moduleId} island in ${file}, ` +
+    `the resolver returned ${renderCauseValue(entry)} for the ${spec.moduleId} island in ${file}, ` +
       'which cannot be emitted as a module URL',
     'fix the resolve() passed to createIslandCollector — it must return a plain URL path',
   );

package/src/island.ts

@@ -25,7 +25,7 @@ const UNSAFE_SPECIFIER = /["'`<>\s\\]/;
 
 /** The same test the resolver's output has to pass: one rule, applied at both ends of the seam. */
 export function isEmittableSpecifier(value: string): boolean {
-  return value.length > 0 && !UNSAFE_SPECIFIER.test(value);
+  return typeof value === 'string' && value.length > 0 && !UNSAFE_SPECIFIER.test(value);
 }
 
 export interface IslandDeclaration<TKeys extends readonly string[] = readonly string[]> {