@ultimat3/render 24.0.0 → 25.1.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` 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. |
+| 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)`. |
@@ -73,8 +74,8 @@ axiom 6). Never `cli` (upward).
 | `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`, 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 `:`. |
+| 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). |
@@ -97,7 +98,7 @@ 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`, 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`). |
+| 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. |
@@ -112,7 +113,7 @@ axiom 6). Never `cli` (upward).
 | 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 (when sent AND when it settles), `onClientWrite`, `onRescope` and a `BroadcastChannel` message from another tab. |
+| Router: nothing is sent twice | every router fetch is `cache: 'no-cache'` — the browser's HTTP cache never answers, the router's own is the only reuse layer (#693; `navigation-fetch.test.ts`, `client-navigation-cache.e2e.test.ts`). 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

@@ -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 |
@@ -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,6 +509,7 @@ 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; 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 |
@@ -517,7 +526,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
   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. One regeneration holds its page for at most
-  `DEFAULT_ISR_REGENERATE_DEADLINE_MS` (30 s; `createIsrController({ regenerateDeadlineMs })`),
+  `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.
@@ -545,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": "24.0.0",
+  "version": "25.1.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": "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"
+    "@ultimat3/cache": "25.1.0",
+    "@ultimat3/core": "25.1.0",
+    "@ultimat3/http": "25.1.0",
+    "@ultimat3/i18n": "25.1.0",
+    "@ultimat3/seo": "25.1.0",
+    "sass": "1.105.1"
   }
 }

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

@@ -359,7 +359,8 @@ export function compileStylesheet(file: string, source: string): CompiledStylesh
   // 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. 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}`));
+  // 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/errors.ts

@@ -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;

package/src/head.ts

@@ -7,11 +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 { escapeHtml, escapeJsonContent, escapeRawTextContent, 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';
 
@@ -172,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.

package/src/html.ts

@@ -1,8 +1,8 @@
 /**
  * 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.
+ * `@ultimat3/core`'s `escapeHtml`, imported from core by every render-* file: a second escaper is
+ * how one of them ends up missing a character, and a missing character in an attribute is an
+ * injection (`X_HELPER_COPY` refuses both a copy and a re-export).
  */
 
 import { escapeHtml, safeUrl, URL_ATTRIBUTES } from '@ultimat3/core';
@@ -26,12 +26,6 @@ export const VOID_ELEMENTS: ReadonlySet<string> = new Set([
   'wbr',
 ]);
 
-/**
- * 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 { escapeHtml };
-
 /**
  * `<script>` and `<style>` hold RAW TEXT: a character reference is not decoded inside them, so
  * `escapeHtml` there would ship `&lt;` to a JS or CSS parser and corrupt the code without closing

package/src/hydrate.ts

@@ -6,8 +6,9 @@
  */
 
 import type { HydrateStrategy } from '@ultimat3/core';
-import { HYDRATE_STRATEGIES } from '@ultimat3/core';
-import { escapeHtml, escapeJsonContent } from './html';
+import { escapeHtml, HYDRATE_STRATEGIES } from '@ultimat3/core';
+import { escapeJsonContent } from './html';
+import { ISLAND_HOLD_ATTRIBUTES, RUNTIME_HOLD } from './island-hold';
 
 export interface IslandDirective {
   /** Unique per INSTANCE: two of the same island on a page need two prop bags to find. */
@@ -26,6 +27,11 @@ export interface IslandDirective {
   readonly events?: readonly string[];
   /** `rootMargin` for `visible`. */
   readonly rootMargin?: string;
+  /**
+   * The server markup must not paint before the island mounts (`island-hold.ts`, #506): hidden
+   * from its first byte, booted at once, revealed by the mount or the cap. Never on `never`.
+   */
+  readonly hold?: boolean;
 }
 
 export const DEFAULT_REPLAY_EVENTS = ['click', 'input', 'change', 'submit', 'keydown'] as const;
@@ -74,6 +80,8 @@ export function emitIslandAttributes(directive: IslandDirective): string {
     if (directive.events !== undefined && directive.events.length > 0) {
       attrs.push(attr('data-x-events', directive.events.join(' ')));
     }
+    // A constant, so it needs no escaper — and nothing a caller supplies reaches it.
+    if (directive.hold === true) attrs.push(ISLAND_HOLD_ATTRIBUTES);
   }
   return attrs.join(' ');
 }
@@ -205,6 +213,9 @@ io.observe(el)})
 // `go` chains on the same `el.__x`, and the first flush empties `q` and sets `done`, so however many
 // ran, each caught event is replayed exactly once and an untouched island still lets go of its
 // listeners at mount — a listener left behind would replay every later click a second time.
+// An island something ELSE booted (a held island: `island-hold.ts` boots it at once) had no flush
+// to let go in, so `on` checks the mount marker — set in the same `.then` that settles `el.__x` —
+// and detaches instead of queueing: the press reaches its target natively, once.
 const RUNTIME_CATCH_UP = `
 function path(el,t){var p=[t&&t.tagName];
 for(;t&&t!==el&&t.parentNode;t=t.parentNode)p.unshift(Array.prototype.indexOf.call(t.parentNode.children,t));
@@ -219,7 +230,8 @@ var q=[],done=false;
 var off=function(){done=true;evs.forEach(function(n){el.removeEventListener(n,on,true)});q=[]};
 var go=function(){boot(el).then(function(){var r=q;off();
 r.forEach(function(e){var ev=e[0],c=new ev.constructor(ev.type,ev);aim(el,ev,e[1]).dispatchEvent(c)})},off)};
-var on=function(ev){if(done)return;q.push([ev,path(el,ev.target)]);go()};
+var on=function(ev){if(done)return;if(el.getAttribute('${ISLAND_MOUNTED_ATTRIBUTE}')!==null){off();return}
+q.push([ev,path(el,ev.target)]);go()};
 evs.forEach(function(n){el.addEventListener(n,on,true)});return go}
 `.trim();
 
@@ -249,9 +261,14 @@ const RUNTIME_ORDER: readonly Exclude<HydrateStrategy, 'never'>[] = HYDRATE_STRA
  * moment the runtime changes, and the failure it produces is an island that never boots on a page
  * that otherwise looks correct.
  */
-const runtimeBody = (needed: ReadonlySet<Exclude<HydrateStrategy, 'never'>>): string =>
+const runtimeBody = (
+  needed: ReadonlySet<Exclude<HydrateStrategy, 'never'>>,
+  held: boolean,
+): string =>
   [
     RUNTIME_PRELUDE,
+    // Right after the prelude: no strategy part below that throws can strand a held island.
+    ...(held ? [RUNTIME_HOLD] : []),
     // Emitted once for whichever of the two catch-up strategies the page uses; a `visible`-only
     // page never pays for it.
     ...(needed.has('idle') || needed.has('interaction') ? [RUNTIME_CATCH_UP] : []),
@@ -260,18 +277,22 @@ const runtimeBody = (needed: ReadonlySet<Exclude<HydrateStrategy, 'never'>>): st
     ),
   ].join('\n');
 
+/** Whether any island the runtime boots is held — a `never` island boots nothing to reveal it. */
+const holds = (directives: readonly IslandDirective[]): boolean =>
+  directives.some((directive) => directive.hold === true && directive.strategy !== 'never');
+
 /**
- * Every body `hydrateRuntime` can emit: one per non-empty subset of the three strategies, seven in
- * all, deterministic. A policy that admits inline script by HASH has to enumerate them before the
+ * Every body `hydrateRuntime` can emit: one per non-empty subset of the three strategies, with and
+ * without a held island — fourteen in all, deterministic. A policy that admits inline script by HASH has to enumerate them before the
  * socket opens — the alternative is a per-response nonce, which a `render: 'static'` page (a file
  * on disk) can never receive. Enumerated rather than derived from the route table because the
  * runtime is a function of the SET a document needs, and a table read at boot cannot answer for
  * a document assembled later.
  */
-export const HYDRATE_RUNTIME_BODIES: readonly string[] = Array.from(
-  { length: 2 ** RUNTIME_ORDER.length - 1 },
-  (_unused, index) =>
-    runtimeBody(new Set(RUNTIME_ORDER.filter((_s, bit) => (((index + 1) >> bit) & 1) === 1))),
+export const HYDRATE_RUNTIME_BODIES: readonly string[] = [false, true].flatMap((held) =>
+  Array.from({ length: 2 ** RUNTIME_ORDER.length - 1 }, (_unused, index) =>
+    runtimeBody(new Set(RUNTIME_ORDER.filter((_s, bit) => (((index + 1) >> bit) & 1) === 1)), held),
+  ),
 );
 
 /**
@@ -281,7 +302,7 @@ export const HYDRATE_RUNTIME_BODIES: readonly string[] = Array.from(
 export function hydrateRuntime(directives: readonly IslandDirective[]): string {
   const needed = requiredStrategies(directives);
   if (needed.size === 0) return '';
-  return `<script type="module">${runtimeBody(needed)}</script>`;
+  return `<script type="module">${runtimeBody(needed, holds(directives))}</script>`;
 }
 
 /** Rough emitted size of the hydration runtime for a page, for the budget check. */

package/src/index.ts

@@ -5,26 +5,21 @@
  */
 
 /**
- * The route vocabulary is declared once, at tier 0 (`@ultimat3/core`), and re-exported here
- * because `defineRoute`, `MODE_SPECS`, `surfaceAllows` and `RouteDescriptor` all take these types
- * in their signatures: a consumer calling this package's API should not need a second import to
- * name its arguments. A re-export is not a declaration — `scripts/render-modes.test.ts` refuses a
- * second declaration, which is what makes re-exporting safe where copying was not.
+ * The route vocabulary is declared once, at tier 0 (`@ultimat3/core`). Its TYPES are re-exported
+ * here because `defineRoute`, `MODE_SPECS`, `surfaceAllows` and `RouteDescriptor` take them in
+ * their signatures; its VALUES (`RENDER_MODES`, `HYDRATE_STRATEGIES`, `OFFLINE_STRATEGIES`) and
+ * `formatBytes` are imported from core by every caller — a value re-export is a second import path
+ * (`X_HELPER_COPY`, `bun run flight-copies`). Nor are core's page-meta names (`CLIENT_*_META`)
+ * re-published beside the tag writers below.
  */
 export type { HydrateStrategy, OfflineStrategy, RenderMode } from '@ultimat3/core';
-// `formatBytes` moved to `@ultimat3/core` (one formatter, with the `mb` branch this package's copy
-// never had); still named here because `@ultimat3/cli`'s budget reporter reads it beside the route
-// table it prints against.
-export { formatBytes, HYDRATE_STRATEGIES, OFFLINE_STRATEGIES, RENDER_MODES } from '@ultimat3/core';
 /** `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';
+export { clientPathStyleTags } from './client-path-style-tag';
 /** The `<meta name="ultimate-scope">` core's `pageClient()` reads, on private documents only. */
 export {
-  CLIENT_PERSIST_META,
-  CLIENT_SCOPE_META,
   clientPersistTags,
   clientScopeTag,
   documentCarriesScope,
@@ -32,9 +27,6 @@ export {
 /** Where the page's one socket dials, and the worker that hosts it (plan 101, slice 11). */
 export type { ClientSyncHead } from './client-sync-tags';
 export {
-  CLIENT_BUILD_META,
-  CLIENT_SYNC_META,
-  CLIENT_SYNC_WORKER_META,
   clientBootTags,
   clientSyncTags,
 } from './client-sync-tags';
@@ -75,7 +67,6 @@ export {
   headFromMeta,
   mergeHead,
   renderHead,
-  THEME_STORAGE_KEY,
   themeScript,
   themeScriptBody,
 } from './head';
@@ -99,7 +90,8 @@ export {
   islandModuleId,
 } from './island';
 export type { IslandCollector, IslandCollectorInput } from './island-collector';
-export { createIslandCollector, islandModuleIds } from './island-collector';
+export { islandCollector, islandModuleIds } from './island-collector';
+export { ISLAND_HOLD_ATTRIBUTE, ISLAND_HOLD_MS, ISLAND_HOLD_REVEAL } from './island-hold';
 export type { IslandProps, JsonValue } from './island-props';
 export { ISLAND_PROPS_MAX_BYTES } from './island-props';
 export { parseByteBudget } from './islands';
@@ -137,8 +129,6 @@ export {
   NAVIGATING_ATTRIBUTE,
   NAVIGATION_CACHE_TTL_MS,
   NAVIGATION_ERROR_EVENT,
-  NAVIGATION_HEADER,
-  NAVIGATION_LOCATION_HEADER,
   NAVIGATION_MAX_HOPS,
   NAVIGATION_META,
   NAVIGATION_NO_PREFETCH_ATTRIBUTE,
@@ -147,8 +137,6 @@ export {
   NAVIGATION_PREFETCH_DELAY_MS,
   NAVIGATION_PROGRESS_DELAY_MS,
   NAVIGATION_RELOAD_ATTRIBUTE,
-  NAVIGATION_SCOPE_HEADER,
-  NAVIGATION_SURFACE_HEADER,
   responseVerdict,
   reusable,
 } from './navigation-rules';
@@ -164,7 +152,7 @@ export type {
 } from './registry';
 export {
   clearRoutes,
-  describeRoutes,
+  describePages,
   ROUTE_FILENAME,
   registerMountedRoutes,
   registerRoute,
@@ -198,7 +186,6 @@ export {
   defineRoute,
   isRouteConfig,
   ROUTE_NAVIGATION_MODES,
-  tagKeys,
 } from './route';
 export type { RouteComponent } from './route-component';
 export { pageComponentOf } from './route-component';

package/src/island-collector.ts

@@ -29,6 +29,12 @@ export interface IslandCollectorInput {
   readonly hydrate: HydrateStrategy;
   /** Specifier → built chunk URL. Identity in dev and in tests; the build supplies the real one. */
   readonly resolve?: (src: string) => string;
+  /**
+   * Which islands (by `src`, as the page wrote it) must not paint their server markup before they
+   * mount (`island-hold.ts`). The caller's to answer — the renderer cannot see what an island's
+   * graph imports. Absent, nothing is held.
+   */
+  readonly hold?: (src: string) => boolean;
 }
 
 /**
@@ -43,7 +49,7 @@ export interface IslandCollector {
   record(spec: IslandSpec, props: JsxProps): IslandDirective;
 }
 
-export function createIslandCollector(input: IslandCollectorInput): IslandCollector {
+export function islandCollector(input: IslandCollectorInput): IslandCollector {
   const directives: IslandDirective[] = [];
   const entries = new Map<string, string>();
   const resolve = input.resolve ?? ((src: string) => src);
@@ -72,7 +78,8 @@ export function createIslandCollector(input: IslandCollectorInput): IslandCollec
 
       const bag = checkIslandProps(props, spec.propKeys, input.file, spec.moduleId);
       const instance = directives.filter((d) => d.moduleId === spec.moduleId).length + 1;
-      const directive = buildDirective(spec, strategy, entry, `${spec.moduleId}-${instance}`, bag);
+      const built = buildDirective(spec, strategy, entry, `${spec.moduleId}-${instance}`, bag);
+      const directive = input.hold?.(spec.src) === true ? { ...built, hold: true } : built;
       directives.push(directive);
       return directive;
     },
@@ -134,7 +141,7 @@ function assertEntry(entry: string, spec: IslandSpec, file: string): void {
   throw new IslandInvalidError(
     `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',
+    'fix the resolve() passed to islandCollector — it must return a plain URL path',
   );
 }
 
@@ -143,7 +150,7 @@ export function islandWithoutCollector(spec: IslandSpec): IslandNotHydratedError
   return new IslandNotHydratedError(
     `the ${spec.moduleId} island was rendered outside a render that collects islands, so no ` +
       'hydration runtime is emitted and its chunk is never requested',
-    'render the page through renderToHtml(tree, { islands: createIslandCollector({ file, ' +
+    'render the page through renderToHtml(tree, { islands: islandCollector({ file, ' +
       'hydrate }) }) so the island is counted, booted and budgeted',
   );
 }