@ultimat3/render 23.0.0 → 25.0.0

package/CLAUDE.md

@@ -29,12 +29,12 @@ axiom 6). Never `cli` (upward).
 | `load` | optional, and the ONE server-side data seam. Resolved once per render by `routeDataFor()` and handed to **both** `meta` and the page component. Absent `load`, the context IS the data (`{ params, url }`). |
 | `load` is required when the context cannot supply the data | `LoadRequirement<TData>` in `defineRoute`'s parameter. `RouteContext` is a type ALIAS on purpose — only an alias carries the implicit index signature that makes it a `RouteData`. |
 | A loader's own error | rethrown only when `isUltimateError` says so (core's brand), never a `code` property and never `instanceof UltimateError` — a tier-0 error is branded, not a subclass. Everything else is `X_ROUTE_LOAD_FAILED`. |
-| A loader's own STATUS | `withStatus(status, data)` (`route-status.ts`) — the ONE way a page answers 404/410/503 while rendering its own component in the app's shell. The status rides on the data by IDENTITY in a `WeakMap`; `routeStatusOf(data)` is the total reader (200 by default). A 3xx is `X_ROUTE_STATUS_INVALID`. A 4xx/5xx is `robots.index = false` by construction in `defineRoute`'s `meta` wrapper. The `Response` status is minted by `@ultimat3/cli`'s `dev-render.ts`. |
+| A loader's own STATUS | `withStatus(status, data)` (`route-status.ts`) — the ONE way a page answers 404/410/503 while rendering its own component in the app's shell. The status rides on the data by IDENTITY in a `WeakMap`; `routeStatusOf(data)` is the total reader (200 by default). A 3xx is `X_ROUTE_STATUS_INVALID`. A 4xx/5xx is `robots.index = false` by construction in `defineRoute`'s `meta` wrapper. The `Response` status is minted by `@ultimat3/cli`'s `runtime-render.ts`. |
 | 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. |
-| No `describe()` on a route | `describeRoutes()` is the one route list. |
+| `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 | `describePages()` 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. |
 | Island filename | `*.island.tsx`, `ISLAND_EXTENSION` — one spelling. Never widen it. |
@@ -51,19 +51,20 @@ axiom 6). Never `cli` (upward).
 | Island collection | per render, `renderToHtml(tree, { islands })`. Never module-global and never on an ambient context. |
 | A byte count in a message | `formatBytes` from `@ultimat3/core`, never a local one. |
 | Island bytes | **not this package's**: `@ultimat3/cli`'s `packages/cli/src/budgets.ts` measures the EMITTED document and is the gate. What stays here is the budget grammar (`parseByteBudget`) and `defaultIslandBudget`. |
-| The hydration runtime's CSP | `HYDRATE_RUNTIME_BODIES` — every body `hydrateRuntime` can emit (seven subsets). It is inline in every document with an island and `@ultimat3/http`'s `script-src` is `'self' 'wasm-unsafe-eval'`, so `@ultimat3/cli`'s `script-csp.ts` hashes this list at boot. `runtimeBody` is the one place the served and hashed text are one string. **Uncovered**: `render-stream.ts`'s per-hole `<script>$X("id")</script>` (unreachable today; the first real hole needs a nonce). |
+| The hydration runtime's CSP | `HYDRATE_RUNTIME_BODIES` — every body `hydrateRuntime` can emit (seven subsets, each with and without the hold part — fourteen). It is inline in every document with an island and `@ultimat3/http`'s `script-src` is `'self' 'wasm-unsafe-eval'`, so `@ultimat3/cli`'s `script-csp.ts` hashes this list at boot. `runtimeBody` is the one place the served and hashed text are one string. **Uncovered**: `render-stream.ts`'s per-hole `<script>$X("id")</script>` (unreachable today; the first real hole needs a nonce). |
 | Island markup | the props `<script>` is emitted INSIDE the wrapper by `render-html.ts`; an assembler only adds `hydrateRuntime(directives)`. |
 | Island boot | `el.__x` holds the boot PROMISE, never a boolean. |
-| Island mount markers | `data-x-mounted=""` when `mount()` resolved, `data-x-failed="<message>"` when it rejected — set by the runtime, never by `emitIslandAttributes`. The rejection handler RETHROWS. Prelude sizes `As of 2026-09-28`: `idle` 1,784, `visible` 886, `interaction` 1,669 B (what `DEFAULT_ISLAND_JS_BYTES` derives from). |
+| Island mount markers | `data-x-mounted=""` when `mount()` resolved, `data-x-failed="<message>"` when it rejected — set by the runtime, never by `emitIslandAttributes`. The rejection handler RETHROWS. Prelude sizes `As of 2026-10-05`: `idle` 1,843, `visible` 886, `interaction` 1,728 B (what `DEFAULT_ISLAND_JS_BYTES` derives from). |
 | A runtime that calls `boot` | TERMINATES the chain: `idle`/`visible` end in `.catch(hush)`, `interaction` passes `off` as the rejection arm. `hydrate-runtime.test.ts` reds on an unhandled rejection. |
 | `idle` replays too | `idle` and `interaction` share ONE `catchUp(el)` in `hydrate.ts` (capture listeners for `data-x-events`, default `click`; a queue; `aim`; one flush). A caught event wakes an `idle` island early; each event replays once. `hydrate-replay.test.ts`. |
 | Where `interaction` replays | `aim(el, ev)`, never `ev.target` — `mount` usually clears the root, detaching the pressed node. Kept → original target; replaced → `path(el, target)`'s structural walk (same tag, same place), then `document.elementFromPoint(ev.clientX, ev.clientY)` (unless `ev.detail === 0`), then the island root. A hit outside the island falls back to the root. `hydrate-replay.test.ts`. |
+| A held island | `hold` on the collector (the host decides — the CLI holds realtime islands on a page-boot document); `island-hold.ts` owns the attribute, the inline `visibility:hidden`, the cap `ISLAND_HOLD_MS` and the runtime part. Emitted right after the prelude; booted at once, revealed TOGETHER on both mount arms, at the cap, or by CSS (`ISLAND_HOLD_REVEAL`, keyframes in `@ultimat3/ui`'s `global.scss`) — never hidden for good. `catchUp`'s `on` lets go after a mount it did not flush. `island-hold.test.ts`, `island-hold-replay.test.ts`. |
 | `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. |
+| Mounted routes | `registerMountedRoutes(mount, routes)` (`mounted-routes.ts`) — routes a PACKAGE mounts with no surface file (the admin's screens). In `describePages()` 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. |
+| Descriptors | `describePages()` 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). |
 | Boundary | `surfaces.ts` throws; it never warns. Type-only edges are not violations. |
 | Stream cancellation | the source has a `cancel()` and `write` is guarded on it; a disconnect aborts `StreamHole.resolve(signal)`. |
@@ -71,8 +72,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 `singleFlight`, `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: `describePages()` 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. |
@@ -93,9 +98,10 @@ axiom 6). Never `cli` (upward).
 | 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, imported by `html.ts` (never re-exported); `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. |
+| 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()`. |
@@ -104,9 +110,10 @@ axiom 6). Never `cli` (upward).
 | 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 2xx non-page answer to the browser from the bytes it already has. A 4xx/5xx non-page answer (an offline worker's empty 503) is never handed over (it became a `blob:` URL): a POST fails, a GET is loaded by the browser — the ONE deliberate re-send, as there is nothing to show (`responseVerdict`). 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` |
@@ -143,7 +143,7 @@ is a build error.
 
 ## The route table is the single source of route truth
 
-`registry.ts` maps file paths to URLs and `describeRoutes()` projects the table into a
+`registry.ts` maps file paths to URLs and `describePages()` projects the table into a
 sorted, JSON-safe descriptor list. Every downstream generator reads that one table.
 
 | File | URL |
@@ -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` |
 
@@ -333,7 +333,7 @@ first frame — an id, a count, and the URL of the read that answers the rest:
 
 ```ts
 // page.tsx — the props are the id and the endpoint, never the rows
-import { derivePath } from '@ultimat3/query';
+import { queryPath } from '@ultimat3/core';
 import { island } from '@ultimat3/render';
 
 const Dispatch = island({
@@ -342,7 +342,7 @@ const Dispatch = island({
 });
 
 export const DispatchFor = (host: { readonly id: string }) =>
-  Dispatch({ hostId: host.id, models: [], modelsEndpoint: `${derivePath('modelList')}?limit=100` });
+  Dispatch({ hostId: host.id, models: [], modelsEndpoint: `${queryPath('modelList')}?limit=100` });
 ```
 
 ```tsx
@@ -370,7 +370,7 @@ export function mount(el: HTMLElement, props: DispatchProps): void {
 ```
 
 `models: []` keeps the island's first frame honest (an empty picker, not a missing one) and
-`derivePath` is the same derivation the typed `client()` uses, so the URL cannot drift from the
+`queryPath` is the same derivation the typed `client()` uses, so the URL cannot drift from the
 route. The `fix:` line of an over-cap `X_ISLAND_PROPS_INVALID` names exactly this edit, with the
 heaviest prop's own name in it.
 
@@ -385,7 +385,7 @@ by the request that carries it.
 ### It counts against the route's budget
 
 ```ts
-const collector = createIslandCollector({ file, hydrate: config.hydrate, resolve });
+const collector = islandCollector({ file, hydrate: config.hydrate, resolve });
 const html = await renderToHtml(page, { islands: collector });
 document.body += hydrateRuntime(collector.directives);   // the one thing left to remember
 ```
@@ -433,6 +433,14 @@ never flushed into an island that did not mount. `ISLAND_MOUNTED_ATTRIBUTE` and
 from, exported for the same reason: anything waiting for hydration has to wait at least this long,
 and a second copy of the number is a settle that shoots early and calls a healthy page broken.
 
+**A held island** (`data-x-hold`, `As of 2026-10`) is one whose server markup must not paint before
+it mounts — an offline reload's cached count under a queued write (#506). The collector's
+`hold: (src) => boolean` names them (the host's call: `@ultimat3/cli` holds realtime islands on a
+document that carries the page boot); the wrapper is `visibility:hidden` from its first byte, the
+runtime boots it at once whatever the strategy, and reveals it when `mount()` settles either way or
+at `ISLAND_HOLD_MS` (3000), whichever comes first — and at the same cap by CSS alone (`ISLAND_HOLD_REVEAL`, keyframes in `@ultimat3/ui`'s `global.scss`), so a page with no script still shows the markup. Only a page holding an island pays for that part
+of the runtime, and `HYDRATE_RUNTIME_BODIES` carries both variants.
+
 ## Two entry points
 
 **Split 2026-08-22, and every claim in this section holds `As of 2026-08`.**
@@ -486,14 +494,14 @@ a job boundary the class is gone and the `code` is what survives — match on th
 |---|---|
 | `defineRoute` | the `route` primitive |
 | `withStatus`, `routeStatusOf` | the status a loader answers, carried on its data; 200 when nothing asked |
-| `island`, `createIslandCollector` | one interactive component on a static page |
+| `island`, `islandCollector` | one interactive component on a static page |
 | `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()` |
+| `registerRoute`, `describePages`, `routeFor`, `routePathFromFile` | the route table |
+| `registerMountedRoutes`, `RouteMount`, `RouteMountInput`, `MountedRouteInput` | routes a package mounts with no surface file: listed by `describePages()` 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 |
+| `isrController`†, `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 |
@@ -501,8 +509,9 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `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 |
+| `ISLAND_HOLD_ATTRIBUTE`, `ISLAND_HOLD_MS`, `ISLAND_HOLD_REVEAL` | a held island's marker, and the cap after which it shows its server markup regardless |
 | `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
@@ -516,7 +525,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; `isrController({ 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
@@ -531,7 +554,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 - **`hydrate: 'never'`** emits no attributes beyond the marker and no runtime — the `site/`
   0kb default is mechanical, not aspirational. A page that renders an island anyway is
   `X_ISLAND_NOT_HYDRATED`, not a silently dead button.
-- **A gated page is `ssr`**, never a client-rendered shell. `spa` and `createRouter` were
+- **A gated page is `ssr`**, never a client-rendered shell. `spa` and `httpRouter` were
   deleted `As of 2026-08-20`: `renderSpa` never read the route's component and no build ever produced the
   `chunks` it preloaded, so every `spa` route served an empty `<div id="x-root">`, and the router
   that shell would have needed had no caller in the framework or in either tracked app. A page

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/render",
-  "version": "23.0.0",
+  "version": "25.0.0",
   "description": "The route primitive and the five render modes: static, isr, ssr, stream, spa.",
   "license": "MIT",
   "type": "module",
@@ -32,18 +32,18 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@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"
+    "@ultimat3/cache": "25.0.0",
+    "@ultimat3/core": "25.0.0",
+    "@ultimat3/http": "25.0.0",
+    "@ultimat3/i18n": "25.0.0",
+    "@ultimat3/seo": "25.0.0",
+    "sass": "1.105.1"
   }
 }

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

@@ -9,9 +9,6 @@ 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 [];

package/src/client-scope-tag.ts

@@ -9,9 +9,6 @@
 import { CLIENT_PERSIST_META, CLIENT_SCOPE_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_PERSIST_META, CLIENT_SCOPE_META };
-
 /** `scope` is opaque (`@ultimat3/auth`'s `clientScopeOf`), and `''` is the anonymous page. */
 export function clientScopeTag(scope: string): HeadTag {
   return {

package/src/client-sync-tags.ts

@@ -7,9 +7,6 @@
 import { CLIENT_BUILD_META, CLIENT_SYNC_META, CLIENT_SYNC_WORKER_META } from '@ultimat3/core';
 import type { HeadTag } from './head';
 
-/** Core's names (`page-meta.ts`), so the writer here and every reader share one literal each. */
-export { CLIENT_BUILD_META, CLIENT_SYNC_META, CLIENT_SYNC_WORKER_META };
-
 export interface ClientSyncHead {
   readonly syncUrl: string;
   readonly buildId: string;

package/src/code-unit-order.ts

@@ -10,7 +10,7 @@
  * the runtime's ICU **default locale** and **collation version**: `'/A'` sorts after `'/a'` on one
  * machine and before it on the next, and `'/zoo'` before `'/ärzte'` under `sv-SE` but after it
  * under `en-US`, for the same input. Everything this package orders is either diffed across
- * deploys (`describeRoutes()` feeds `x.manifest.json`, the sitemap and `sw.js`'s rule table) or is
+ * deploys (`describePages()` feeds `x.manifest.json`, the sitemap and `sw.js`'s rule table) or is
  * a choice a build makes (`pageComponentOf`'s fallback), so a machine-dependent order is a no-op
  * deploy that reads as a change — or a different page rendered per host. Same rule
  * `@ultimat3/pwa`'s `precache.ts` and `service-worker.ts` state for the artifact they emit.

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,10 @@ 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. Split on
+  // both separators: on Windows Bun hands the path over as `D:\…`, and `/` alone kept all of it.
+  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',
@@ -109,7 +109,7 @@ export class RouteMetaMissingError extends UltimateError {
 /**
  * The route table holds descriptors, never declarations. `defineRoute` is the one normalizer, so
  * a raw declaration reaching the registry means `budget` and `meta` are whatever the author wrote
- * — and every reader downstream (`describeRoutes`, `sw.js`, the sitemap) assumes they are not.
+ * — and every reader downstream (`describePages`, `sw.js`, the sitemap) assumes they are not.
  */
 export class RouteUnnormalizedError extends UltimateError {
   static readonly code = 'X_ROUTE_UNNORMALIZED' as const;
@@ -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

@@ -7,17 +7,12 @@
  * catalog and so the tag vocabulary keeps exactly one owner (`@ultimat3/seo`).
  */
 
-import { finiteCount } from '@ultimat3/core';
+import { escapeHtml, finiteCount, THEME_STORAGE_KEY } 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';
+// The raw-text escapers are `html.ts`'s and the text/attribute table is core's `escapeHtml` — a
+// second one is how a character ends up missing.
+import { escapeJsonContent, escapeRawTextContent, isAttributeName } from './html';
 
 export type HeadTagKind = 'title' | 'base' | 'meta' | 'link' | 'script' | 'style';
 
@@ -125,7 +120,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 +136,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);
 }
 
@@ -178,14 +173,6 @@ export interface ThemeScriptOptions {
 
 export const THEME_SCRIPT_MAX_BYTES = 512;
 
-/**
- * The storage key `@ultimat3/ui`'s `ThemeToggle` reads (`THEME_STORAGE_KEY` there). One literal on
- * each side, pinned equal by a test in `@ultimat3/cli`: render sits below ui in the tier table and
- * cannot import it, and the two keys disagreeing was exactly the bug — the boot stamped one key,
- * the toggle wrote another, and a visitor's choice never survived a reload.
- */
-export const THEME_STORAGE_KEY = 'ultimate.theme';
-
 /**
  * The script's text alone, so the CSP hash and the tag come from one string: a policy hashed from
  * a restatement admits a script that is not the one the document carries.
@@ -204,10 +191,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){}`
   );
 }