@ultimat3/render 24.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` 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 | 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.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": "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.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/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',
   );
 }

package/src/island-hold.ts

@@ -0,0 +1,56 @@
+// A HELD island (#506): server markup that must not paint before the island mounts, because what
+// it shows can be older than what the page will show — an offline reload's cached count, under a
+// queued write the mount rebuilds. Hidden from its first byte, booted at once, revealed when the
+// mount settles or at the cap. Who is held is the renderer's caller's call (`hold` on the collector).
+
+/** On a held island's wrapper until the runtime reveals it; what the runtime finds it by. */
+export const ISLAND_HOLD_ATTRIBUTE = 'data-x-hold';
+
+/**
+ * The longest a held island stays hidden, whatever its chunk does — a download on a slow network,
+ * a mount that never settles. Above `@ultimat3/realtime`'s `FIRST_PAINT_HOLD_MS` (1 s), the cap on
+ * the disk restore a realtime island waits for, so a slow disk meets that cap and still mounts
+ * before this one shows the server's markup. Interpolated into the runtime: one number, one copy.
+ */
+export const ISLAND_HOLD_MS = 3_000;
+
+/**
+ * The keyframes that reveal a held island with no script at all — JS off, the runtime blocked, a
+ * strategy part that threw before the hold could run. Defined in `@ultimat3/ui`'s `global.scss`
+ * (this package may not import `ui`; `island-hold-replay.test.ts` holds the two spellings equal).
+ */
+export const ISLAND_HOLD_REVEAL = 'ultimate-hold-reveal';
+
+/**
+ * The wrapper's attributes. An inline `style` and not a stylesheet rule: it applies from the byte
+ * the parser reads (no sheet can have loaded yet), and `@ultimat3/http`'s policy admits a style
+ * ATTRIBUTE (`style-src-attr`) where an inline `<style>` would need a hash. `visibility`, never
+ * `display`: the island keeps its box, so the reveal shifts no layout. The animation is the reveal
+ * that needs no script: a zero-length step to `visible` after the cap, held by `forwards` (reduced
+ * motion shortens durations, never delays). The runtime takes both properties off when it reveals.
+ */
+export const ISLAND_HOLD_ATTRIBUTES =
+  `${ISLAND_HOLD_ATTRIBUTE} ` +
+  `style="visibility:hidden;animation:${ISLAND_HOLD_REVEAL} 0s ${ISLAND_HOLD_MS}ms forwards"`;
+
+// Booted at once, whatever the route's strategy: a hidden island receives no press and sits in no
+// idle slot worth waiting for, so `interaction` would hold it until the cap and show the stale
+// markup anyway. `boot` is the prelude's, so the strategy below chains on the SAME `el.__x` and
+// mounts nothing twice. `el.__h`, not `each`'s `el.__v`: `each` would mark the root visited and
+// the strategy's own pass would then skip it. Emitted FIRST after the prelude (`hydrate.ts`), so
+// a strategy part that throws — an old WebView with no IntersectionObserver — cannot strand it.
+// The strategy's capture listeners let go on the first event after the mount (`catchUp`'s `on`),
+// since the hold, not a caught event, is what booted the island.
+//
+// Revealed TOGETHER, once every held island of this pass has settled (or at the cap): one record
+// shown in two islands is rebuilt by whichever island holds its writer — a queued write's overlay
+// is restored inside THAT island's mount — so a reader revealed at its own mount painted the
+// record without it (#506, measured in `offline-like.e2e.test.ts`). A failed mount counts as
+// settled (`hush`): its server markup is shown rather than hidden forever.
+export const RUNTIME_HOLD = `
+var hs=[];Array.prototype.forEach.call(document.querySelectorAll('[${ISLAND_HOLD_ATTRIBUTE}]'),function(el){
+if(!el.__h){el.__h=1;hs.push(el)}});
+if(hs.length){var t,r=function(){clearTimeout(t);hs.forEach(function(el){el.removeAttribute('${ISLAND_HOLD_ATTRIBUTE}');
+el.style.removeProperty('visibility');el.style.removeProperty('animation')})};
+t=setTimeout(r,${ISLAND_HOLD_MS});Promise.all(hs.map(function(el){return boot(el).then(null,hush)})).then(r)}
+`.trim();

package/src/island-props.ts

@@ -173,7 +173,7 @@ export function checkIslandProps(
         'and every one of them ships inside the HTML on every request — ' +
         heaviest.map(([key, size]) => `props.${key} is ${size} B of the ${bytes}`).join(', '),
       `in ${file}, pass ${heaviest.map(([key]) => `\`${key}: []\``).join(' and ')} beside ` +
-        `\`${first}Endpoint: derivePath('<queryName>')\` (@ultimat3/query) and fetch the rows inside ` +
+        `\`${first}Endpoint: queryPath('<queryName>')\` (@ultimat3/core) and fetch the rows inside ` +
         'the island after mount — a list that is the same on every request is a dataset, not a ' +
         'prop; an id, a count and a URL are',
     );

package/src/island.ts

@@ -6,6 +6,7 @@
  * graph (axiom 6). WHEN it wakes is the route's `hydrate`, never a second declaration here.
  */
 
+import { renderFixShellArg } from '@ultimat3/core';
 import { IslandInvalidError } from './errors';
 import type { JsonValue } from './island-props';
 import type { JsxProps } from './jsx';
@@ -195,7 +196,10 @@ function normalizeIsland(declaration: IslandDeclaration): IslandSpec {
     throw new IslandInvalidError(
       `island src ${JSON.stringify(src)} is not an island file: a module ships to the browser ` +
         `only if its name says so, and ${ISLAND_EXTENSION} is the one spelling that says it`,
-      `git mv -- ${src} ${stem}${ISLAND_EXTENSION}, then pass src: '${stem}${ISLAND_EXTENSION}'`,
+      // Screened (security audit of plan 101 sweep 1c, M1): `UNSAFE_SPECIFIER` lets `$(…)`, `;`,
+      // `|` and `&` through. A leading `./` is dropped first — the same path to a shell, and
+      // `renderFixShellArg` refuses a leading `.` — so the common specifier stays pasteable.
+      `git mv -- ${renderFixShellArg(src.replace(/^\.\//, ''), "'<module>'")} ${renderFixShellArg(`${stem.replace(/^\.\//, '')}${ISLAND_EXTENSION}`, `'<name>${ISLAND_EXTENSION}'`)}, then pass src: '${stem}${ISLAND_EXTENSION}'`,
     );
   }
 

package/src/module-loader.ts

@@ -4,12 +4,10 @@
  * `bun test` all load a component the same way and there is no separate "bundled" behaviour.
  */
 
-// why: Bun ships no path API, and a relative app root has to be resolved against the working
-// directory before it can be compared with the absolute paths the Bun plugin hands this loader.
-import { resolve } from 'node:path';
 import { renderThrowable } from '@ultimat3/core';
 import { compileStylesheet, isGlobalStylesheet, stripCharset } from './css-modules';
 import { PrerenderFailedError } from './errors';
+import { comparablePath, isPathBelow, pathBelow } from './stylesheet-path';
 import type { Surface } from './surfaces';
 import { surfaceUnder } from './surfaces';
 
@@ -42,7 +40,8 @@ const RENDER_PACKAGE = '@ultimat3/render';
  * `Bun.plugin` ignores `onResolve` outright — the callback never fires, from module scope or from
  * a `--preload`, and a virtual namespace never resolves — and ignores `resolveDir` on an `onLoad`
  * result. Neither seam can carry the resolution, so the specifier must. Revisit if Bun wires
- * either: an `onResolve` hook would leave every compiled module byte-identical.
+ * either: an `onResolve` hook would leave every compiled module byte-identical. Upstream:
+ * https://github.com/oven-sh/bun/issues/40579.
  *
  * The fallback is the status quo, for the one frame that cannot answer: inside a
  * `bun build --compile` binary `import.meta.url` is `file:///$bunfs/root/<name>` and
@@ -120,9 +119,12 @@ export function registeredStylesheets(): readonly Stylesheet[] {
 /**
  * The directory a sheet's surface is read below. Absent, the process's working directory — which
  * is the app root in the container (`WORKDIR /app`) and under every `x` command run from one.
+ * Held as a `comparablePath`, like every claim: on Windows each arrives as `D:\app\…`.
  */
 let stylesheetRoot: string | undefined;
 
+const rootOfSheets = (): string => stylesheetRoot ?? comparablePath(process.cwd());
+
 /**
  * Directories a package claimed for ONE surface, longest first. A package's sheet has no surface
  * of its own and rides both graphs — right for a design system, and the reason an app's static
@@ -130,11 +132,13 @@ let stylesheetRoot: string | undefined;
  */
 const claims: { readonly dir: string; readonly surface: Surface }[] = [];
 
-const claimedSurface = (path: string): Surface | undefined =>
-  claims.find((claim) => path.startsWith(`${claim.dir}/`))?.surface;
+const claimedSurface = (path: string): Surface | undefined => {
+  const comparable = comparablePath(path);
+  return claims.find((claim) => isPathBelow(comparable, claim.dir))?.surface;
+};
 
 const surfaceOfSheet = (path: string): Surface | null =>
-  claimedSurface(path) ?? surfaceUnder(stylesheetRoot ?? process.cwd(), path);
+  claimedSurface(path) ?? surfaceUnder(rootOfSheets(), comparablePath(path));
 
 /** Every registered sheet, classified again; the revision moves only when an answer does. */
 const reclassify = (): void => {
@@ -157,7 +161,7 @@ const reclassify = (): void => {
  * it standing, because the module that made it is cached and will not make it again.
  */
 export function claimStylesheets(dir: string, surface: Surface): void {
-  const claimed = resolve(dir);
+  const claimed = comparablePath(dir);
   if (claims.some((claim) => claim.dir === claimed && claim.surface === surface)) return;
   claims.push({ dir: claimed, surface });
   claims.sort((a, b) => b.dir.length - a.dir.length);
@@ -174,7 +178,7 @@ export function claimStylesheets(dir: string, surface: Surface): void {
  */
 export function setStylesheetRoot(root: string | undefined): void {
   // Resolved: `loadApp('.')` is a legal call, and `.` is a prefix of no absolute path.
-  stylesheetRoot = root === undefined ? undefined : resolve(root);
+  stylesheetRoot = root === undefined ? undefined : comparablePath(root);
   reclassify();
 }
 
@@ -221,11 +225,12 @@ const OWNER_RANK = (sheet: Stylesheet): number =>
   // A claimed sheet is a package's whichever surface carries it: library first.
   sheet.surface === null || sheet.claimed ? 0 : sheet.surface === 'shared' ? 1 : 2;
 
-/** Relative to the app root, so a container at `/app` and a laptop order one app alike. */
-const orderPath = (sheet: Stylesheet): string => {
-  const root = stylesheetRoot ?? process.cwd();
-  return sheet.file.startsWith(`${root}/`) ? sheet.file.slice(root.length + 1) : sheet.file;
-};
+/**
+ * Relative to the app root and `/`-separated, so a container at `/app`, a laptop and a Windows
+ * checkout at `D:\app` order one app alike — and so mint one stylesheet hash.
+ */
+const orderPath = (sheet: Stylesheet): string =>
+  pathBelow(comparablePath(sheet.file), rootOfSheets());
 
 /** See `stylesFor`: global layer, then owner, then path. Exported for the tests that pin it. */
 export function stylesheetOrder(a: Stylesheet, b: Stylesheet): number {

package/src/navigation-fetch.ts

@@ -5,14 +5,15 @@
  * page's text, or a non-page's bytes to hand over (a prefetch's are dropped unread).
  */
 
-import { CLIENT_BUILD_META, CLIENT_SCOPE_META } from '@ultimat3/core/page';
 import {
-  NAVIGATION_HEADER,
-  NAVIGATION_LOCATION_HEADER,
-  NAVIGATION_META,
-  NAVIGATION_SCOPE_HEADER,
-  NAVIGATION_SURFACE_HEADER,
-} from './navigation-rules';
+  CLIENT_BUILD_META,
+  CLIENT_NAVIGATION_HEADER,
+  CLIENT_NAVIGATION_LOCATION_HEADER,
+  CLIENT_NAVIGATION_SCOPE_HEADER,
+  CLIENT_NAVIGATION_SURFACE_HEADER,
+  CLIENT_SCOPE_META,
+} from '@ultimat3/core/page';
+import { NAVIGATION_META } from './navigation-rules';
 
 /** One fetched answer, read once — a prefetch and the click after it share it. */
 export interface Answer {
@@ -41,11 +42,11 @@ export function fetchDocument(
 ): Promise<Answer> {
   const headers: Record<string, string> = {
     accept: 'text/html,application/xhtml+xml',
-    [NAVIGATION_HEADER]: purpose,
-    [NAVIGATION_SURFACE_HEADER]: metaOf(doc, NAVIGATION_META) ?? '',
+    [CLIENT_NAVIGATION_HEADER]: purpose,
+    [CLIENT_NAVIGATION_SURFACE_HEADER]: metaOf(doc, NAVIGATION_META) ?? '',
   };
   const scope = metaOf(doc, CLIENT_SCOPE_META);
-  if (scope !== null) headers[NAVIGATION_SCOPE_HEADER] = scope;
+  if (scope !== null) headers[CLIENT_NAVIGATION_SCOPE_HEADER] = scope;
   // GET only: a skewed GET is refused before any route runs; a POST is never refused mid-submit.
   const build = metaOf(doc, CLIENT_BUILD_META);
   if ((init.method ?? 'GET') === 'GET' && build !== null) headers[CLIENT_BUILD_META] = build;
@@ -61,7 +62,7 @@ export function fetchDocument(
         if (purpose === 'prefetch') await response.body?.cancel();
         else body = await response.blob();
       }
-      const location = response.headers.get(NAVIGATION_LOCATION_HEADER);
+      const location = response.headers.get(CLIENT_NAVIGATION_LOCATION_HEADER);
       return {
         status: response.status,
         opaqueRedirect,

package/src/navigation-rules.ts

@@ -1,33 +1,19 @@
 /**
  * Which clicks and submits the client router takes, and which it leaves to the browser — as pure
  * functions over plain facts, so every rule is testable without a DOM and the router
- * (`navigation.ts`) only gathers the facts. Also the one declaration of every attribute, header and
- * event name the router shares with the documents the server renders and the apps that listen.
+ * (`navigation.ts`) only gathers the facts. Also the one declaration of every attribute and event
+ * name the router shares with the documents the server renders and the apps that listen; the
+ * router's headers are core's (`CLIENT_NAVIGATION_*_HEADER`), imported where they are sent.
  */
 
-import {
-  CLIENT_NAVIGATION_HEADER,
-  CLIENT_NAVIGATION_LOCATION_HEADER,
-  CLIENT_NAVIGATION_SCOPE_HEADER,
-  CLIENT_NAVIGATION_SURFACE_HEADER,
-} from '@ultimat3/core/page';
-
 /**
  * `<meta name="ultimate-navigation" content="<app>:<surface>">` — present only on an opted-in
  * surface. The app's name is part of it, so two apps on one origin (web and admin) are two routers.
  */
 export const NAVIGATION_META = 'ultimate-navigation';
-/**
- * Sent on every router fetch: `soft` when a visitor asked for the page, `prefetch` when the router
- * guessed they would. The server answers a route that did not opt in before running it.
- */
-export const NAVIGATION_HEADER = CLIENT_NAVIGATION_HEADER;
-/** The `<app>:<surface>` of the document the router runs in, on every router fetch. */
-export const NAVIGATION_SURFACE_HEADER = CLIENT_NAVIGATION_SURFACE_HEADER;
-/** The document's principal (`ultimate-scope`), when it carries one. */
-export const NAVIGATION_SCOPE_HEADER = CLIENT_NAVIGATION_SCOPE_HEADER;
-/** On a `204`: load this URL with a real navigation — the server's hand-over. */
-export const NAVIGATION_LOCATION_HEADER = CLIENT_NAVIGATION_LOCATION_HEADER;
+// The four router HEADERS are core's (`CLIENT_NAVIGATION_HEADER`, `…_SURFACE_HEADER`,
+// `…_SCOPE_HEADER`, `…_LOCATION_HEADER`), imported by the fetcher and by `@ultimat3/http`'s gate —
+// 25.0.0 deleted the `NAVIGATION_*_HEADER` aliases this file published for them (`X_HELPER_COPY`).
 /** On a link or form: always a full document load. */
 export const NAVIGATION_RELOAD_ATTRIBUTE = 'data-x-reload';
 /** On a link: followed softly, never fetched before it is clicked. */
@@ -275,7 +261,15 @@ export function responseVerdict(facts: ResponseFacts): ResponseVerdict {
     facts.build !== null && facts.nextBuild !== null && facts.build !== facts.nextBuild;
   // A GET refused for skew (409 before any route ran) or rendered by another build: load it.
   if (get && skewed) return load(facts.requested, 'another build');
-  if (!/^\s*text\/html\b/i.test(facts.contentType)) return { kind: 'hand-over' };
+  const html = /^\s*text\/html\b/i.test(facts.contentType);
+  // An error that is not a page (an offline service worker's empty 503, a JSON 404) is nothing to
+  // show — handed over, it became a `blob:` URL in the address bar. A GET is the browser's to
+  // load (a worker answers a real navigation with its offline page); a POST is never re-sent.
+  if (facts.status >= 400 && !html) {
+    const reason = 'an error answer that is not a page';
+    return get ? load(facts.requested, reason) : { kind: 'failed', reason };
+  }
+  if (!html) return { kind: 'hand-over' };
   // A POST answered in place IS the page the browser would have shown, whatever rendered it —
   // and when that is another principal's or build's, the caller stops trusting this tab
   // (`answerMovesTab`): every later navigation is a real load.

package/src/navigation.ts

@@ -46,6 +46,7 @@ import {
   NAVIGATED_EVENT,
   NAVIGATING_ATTRIBUTE,
   NAVIGATION_ERROR_EVENT,
+  NAVIGATION_MAX_HOPS,
   NAVIGATION_META,
   NAVIGATION_NO_PREFETCH_ATTRIBUTE,
   NAVIGATION_PREFETCH_DELAY_MS,
@@ -103,7 +104,7 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
   let rendered = withoutFragment(win.location.href);
   /** The URL a navigation in flight is fetching: a prefetch never asks for it a second time. */
   let navigatingTo: string | undefined;
-  /** The view transition still animating, which a press skips to the new page. */
+  /** The view transition still animating — skipped only for a click it swallowed (`onClick`). */
   let animating: RunningTransition | undefined;
   /** Between a press and its click: the focus the press gives a link is not a hover. */
   let pressed = false;
@@ -172,6 +173,12 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
   };
 
   const navigate = async (url: string, options: NavigateOptions = {}): Promise<void> => {
+    // The redirect chain's only exit is `hops >= NAVIGATION_MAX_HOPS`, which `NaN` never meets.
+    // `hops` is this router's own recursion counter (nothing outside it can reach `navigate`), so a
+    // non-count is a broken caller, not input: it fails CLOSED as an exhausted chain — one request,
+    // then the browser loads the page — instead of shipping the error renderer (~2 KB) to every page.
+    const asked = options.hops ?? 0;
+    const hops = Number.isSafeInteger(asked) && asked >= 0 ? asked : NAVIGATION_MAX_HOPS;
     const method = options.method ?? 'GET';
     // After an answer for another principal or build was shown in place, this tab is no longer
     // trusted to swap: every navigation is a real load (`answerMovesTab`).
@@ -212,7 +219,7 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
         opaqueRedirect: answer.opaqueRedirect,
         location: answer.location,
         contentType: answer.contentType,
-        hops: options.hops ?? 0,
+        hops,
         surface: metaOf(doc, NAVIGATION_META),
         nextSurface: next === null ? null : metaOf(next, NAVIGATION_META),
         build: metaOf(doc, CLIENT_BUILD_META),
@@ -236,7 +243,7 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
         case 'follow':
           await navigate(verdict.url, {
             history: options.history === 'none' ? 'replace' : 'push',
-            hops: (options.hops ?? 0) + 1,
+            hops: hops + 1,
           });
           return;
         case 'hand-over':
@@ -315,9 +322,9 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
     pressed = true;
     pressedOverTransition = animating !== undefined;
     // A press is not a hover: the click it becomes navigates, and a guess on its heels is a
-    // second request for the same page. And a press during the animation skips to the new page.
+    // second request for the same page. A press alone never skips the running transition — that
+    // snapped every named element to its end mid-glide (#621); only the click below may.
     win.clearTimeout(intent);
-    animating?.skipTransition?.();
   };
   const onRelease = (): void => {
     pressed = false;
@@ -325,13 +332,15 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
 
   const onClick = (event: MouseEvent): void => {
     win.clearTimeout(intent);
-    // While a view transition paints, the browser hit-tests every press to `<html>`: the press
-    // skipped the animation (`onPress`), the release landed on the real element, and the click —
-    // aimed at their common ancestor — reached nothing. The visitor's first click after a swap was
-    // lost. It is given to the element under the pointer NOW, whatever it is: a link, a submit
-    // button, an island's own control.
+    // While a view transition paints, the browser hit-tests every press to `<html>` — Chrome does
+    // so whatever `pointer-events` the `::view-transition` overlay has — so the click reached
+    // nothing: the visitor's first click after a swap was lost. It is given to the element under
+    // the pointer, whatever it is: a link, a submit button, an island's own control. Only a
+    // skipped transition hit-tests the page, so the skip happens HERE, at the click, never at
+    // the press; when the animation already ended between the two, there is nothing to skip.
     if (pressedOverTransition && event.target === doc.documentElement) {
       pressedOverTransition = false;
+      animating?.skipTransition?.();
       const hit = doc.elementFromPoint(event.clientX, event.clientY);
       if (hit !== null && hit !== doc.documentElement && hit instanceof HTMLElement) hit.click();
       return;

package/src/registry.ts

@@ -1,6 +1,6 @@
 /**
  * The route table — the single source of route truth. File path → URL conventions for
- * `site/`, `app/` and `api/`, plus `describeRoutes()`, the serializable projection that
+ * `site/`, `app/` and `api/`, plus `describePages()`, the serializable projection that
  * `x.manifest.json`, the `/_x` routes panel, the sitemap and `sw.js` are all generated
  * from. Nothing downstream may keep its own list of routes.
  */
@@ -27,7 +27,7 @@ import {
   setMountedRoutes,
 } from './mounted-routes';
 import type { RouteConfig, RouteData } from './route';
-import { isRouteConfig, tagKeys } from './route';
+import { isRouteConfig, routeTagKeys } from './route';
 import type { RouteComponent } from './route-component';
 import type { CompiledPattern } from './route-pattern';
 import { compilePattern } from './route-pattern';
@@ -206,7 +206,7 @@ function toUrlSegment(segment: string): string {
 }
 
 const routes = new Map<string, RouteEntry>();
-/** The table `describeRoutes()` last built, dropped whenever a route registers or the registry clears. */
+/** The table `describePages()` last built, dropped whenever a route registers or the registry clears. */
 let described: readonly RouteDescriptor[] | undefined;
 
 export interface RegisterRouteInput<TData = RouteData> {
@@ -250,7 +250,7 @@ export function registerRoute<TData = RouteData>(
   input: RegisterRouteInput<TData>,
 ): RouteEntry<TData> {
   // The type already refuses a declaration; this catches the JS caller and the cast. Without it a
-  // raw declaration registers, and `describeRoutes()` is where it surfaces — as a bare TypeError
+  // raw declaration registers, and `describePages()` is where it surfaces — as a bare TypeError
   // on `config.budget.js`, one build step away from the file that caused it.
   if (!isRouteConfig(input.config)) {
     throw new RouteUnnormalizedError(
@@ -367,7 +367,7 @@ export function routeCount(): number {
 }
 
 export function routeEntries(): readonly RouteEntry[] {
-  // Code units, never `localeCompare` — `describeRoutes()` below promises an order "identical for
+  // Code units, never `localeCompare` — `describePages()` below promises an order "identical for
   // identical input", and `localeCompare` with no locale argument reads the runtime's ICU default.
   return [...routes.values()].sort((a, b) => byCodeUnit(a.path, b.path));
 }
@@ -380,7 +380,7 @@ export function routeFor(path: string): RouteEntry | undefined {
  * The manifest projection: JSON-safe, sorted by path, identical for identical input.
  * Determinism matters because `sw.js` and the sitemap are diffed across deploys.
  */
-export function describeRoutes(): readonly RouteDescriptor[] {
+export function describePages(): readonly RouteDescriptor[] {
   // Built once per registry change and handed out as the SAME frozen array: an ISR regeneration
   // looked its route up through this on every request, re-sorting the whole table each time, and
   // a stable identity is what lets `render-isr.ts` compile its matchers once per table.
@@ -422,7 +422,7 @@ const descriptorOf = (
   mode: config.render,
   offline: config.offline,
   hydrate: config.hydrate,
-  revalidateTags: tagKeys(config.revalidate?.tags),
+  revalidateTags: routeTagKeys(config.revalidate?.tags),
   revalidateTtl: config.revalidate?.ttl ?? null,
   prerenderable: config.prerender !== undefined,
   dynamic: params > 0,

package/src/render-html.ts

@@ -4,14 +4,14 @@
  * component — `static` at build time, `ssr`/`stream` per request, all through `renderToHtml`.
  */
 
-import { renderThrowable } from '@ultimat3/core';
+import { escapeHtml, renderFixShellArg, renderThrowable } from '@ultimat3/core';
 import {
   IslandInvalidError,
   IslandNotHydratedError,
   IslandPropsInvalidError,
   PrerenderFailedError,
 } from './errors';
-import { escapeHtml, renderAttributes, VOID_ELEMENTS } from './html';
+import { renderAttributes, VOID_ELEMENTS } from './html';
 import { emitIslandAttributes, emitIslandProps } from './hydrate';
 import type { IslandNode } from './island';
 import { isIslandNode } from './island';
@@ -164,7 +164,9 @@ export async function renderComponent(
       // null-prototype object (`String()` raises) or an Error whose `message` getter does — and
       // this frame is the last thing between that and a build failure with no code at all.
       `rendering the component in ${file} threw: ${renderThrowable(error)}`,
-      `run \`bun test ${file.replace(/\.tsx?$/, '.test.ts')}\` to reproduce, then fix ${file}`,
+      // The route file is author text and `$(…)` is a legal name: screened where it enters the
+      // reproduce command (security audit of plan 101 sweep 1c).
+      `run \`bun test ${renderFixShellArg(file.replace(/\.tsx?$/, '.test.ts'), "'<the route's test file>'")}\` to reproduce, then fix ${file}`,
     );
   }
 }

package/src/render-isr.ts

@@ -17,11 +17,11 @@ import {
   unregisterDependent,
 } from '@ultimat3/cache';
 import type { Scheduler } from '@ultimat3/core';
-import { createSingleFlight, finiteCount, logger, renderThrowable } from '@ultimat3/core';
+import { finiteCount, logger, renderThrowable, singleFlight } from '@ultimat3/core';
 import { parseTtlMs } from './duration';
 import { finiteStatus, isRenderStatus } from './finite-status';
 import type { RouteDescriptor } from './registry';
-import { describeRoutes } from './registry';
+import { describePages } from './registry';
 import type { IsrEntry, IsrState, IsrStore } from './render-isr-store';
 import { memoryIsrStore } from './render-isr-store';
 import { contentHash, staticHeaders } from './render-static';
@@ -153,16 +153,16 @@ let installedRevalidator: Revalidator | undefined;
 /** What `registerRevalidator` is handed on detach: the framework's "nothing to revalidate". */
 const NO_REVALIDATION: Revalidator = () => undefined;
 
-export function createIsrController(options: IsrControllerOptions = {}): IsrController {
+export function isrController(options: IsrControllerOptions = {}): IsrController {
   const store = options.store ?? memoryIsrStore();
   const now = options.now ?? (() => Date.now());
-  const routes = options.routes ?? describeRoutes;
+  const routes = options.routes ?? describePages;
   const isrDependents =
     options.isrDependents ?? ((tags: readonly CacheTag[]) => dependentsOfKind(tags, 'isr-route'));
   const buildId = options.buildId ?? 'dev';
-  const flight = createSingleFlight({
+  const flight = singleFlight({
     deadlineMs: finiteCount(
-      'createIsrController',
+      'isrController',
       'regenerateDeadlineMs',
       options.regenerateDeadlineMs ?? DEFAULT_ISR_REGENERATE_DEADLINE_MS,
       1,
@@ -380,7 +380,7 @@ interface RouteMatcher {
   test(storedPath: string): boolean;
 }
 
-/** One compiled set per route TABLE — `describeRoutes()` hands out one array per registry change. */
+/** One compiled set per route TABLE — `describePages()` hands out one array per registry change. */
 const compiledTables = new WeakMap<readonly RouteDescriptor[], readonly RouteMatcher[]>();
 
 /**

package/src/render-ssr.ts

@@ -5,6 +5,7 @@
  */
 
 import type { Ctx } from '@ultimat3/core';
+import { BUILD_ID_HEADER } from '@ultimat3/core';
 import { cacheControl } from '@ultimat3/http';
 import { finiteStatus } from './finite-status';
 import type { RouteEntry } from './registry';
@@ -81,6 +82,6 @@ export function ssrHeaders(
           ? PRIVATE_NO_STORE
           : 'public, max-age=0, s-maxage=30, stale-while-revalidate=300',
     vary: [...vary].sort().join(', '),
-    'x-ultimate-build': options.buildId,
+    [BUILD_ID_HEADER]: options.buildId,
   };
 }

package/src/render-static.ts

@@ -4,7 +4,7 @@
  * the precache revision in `sw.js`, and the asset filename suffix.
  */
 
-import { renderCauseValue, renderThrowable, useContext } from '@ultimat3/core';
+import { BUILD_ID_HEADER, renderCauseValue, renderThrowable, useContext } from '@ultimat3/core';
 import { PrerenderFailedError, RouteModeInvalidError } from './errors';
 import type { RouteEntry } from './registry';
 import type { RenderResult, RouteParams } from './route';
@@ -161,7 +161,7 @@ export function staticHeaders(hash: string, buildId: string): Readonly<Record<st
     // Revalidate cheaply: the HTML URL is stable, its content hash is not.
     'cache-control': 'public, max-age=0, must-revalidate',
     etag: `"${hash}"`,
-    'x-ultimate-build': buildId,
+    [BUILD_ID_HEADER]: buildId,
   };
 }
 

package/src/render-stream.ts

@@ -11,9 +11,8 @@
  * contains no interactive island costs literally zero JS.
  */
 
-import { finiteCount, logger, renderThrowable } from '@ultimat3/core';
+import { BUILD_ID_HEADER, escapeHtml, finiteCount, logger, renderThrowable } from '@ultimat3/core';
 import { finiteStatus } from './finite-status';
-import { escapeHtml } from './html';
 import type { RenderResult } from './route';
 import { REVEAL_BODY, REVEAL_CALL } from './stream-scripts';
 
@@ -225,7 +224,7 @@ export function streamResult(plan: StreamPlan, options: StreamOptions, status =
       // Proxies that buffer defeat the entire mode.
       'x-accel-buffering': 'no',
       'transfer-encoding': 'chunked',
-      'x-ultimate-build': options.buildId,
+      [BUILD_ID_HEADER]: options.buildId,
     },
     body: renderStreamHtml(plan, options),
   };

package/src/route.ts

@@ -265,8 +265,10 @@ export interface RenderResult {
 /**
  * Route descriptors carry tags in `@ultimat3/cache`'s wire form (`post`, `post:123`), the
  * same strings every cache tier speaks. Render never invents a key convention of its own.
+ * Declaration order is kept — unlike `@ultimat3/cache`'s `tagKeys`, the sorted identity form —
+ * so the name says which list this is, and it stays out of the public barrel.
  */
-export function tagKeys(tags: readonly CacheTag[] | undefined): readonly string[] {
+export function routeTagKeys(tags: readonly CacheTag[] | undefined): readonly string[] {
   return tags === undefined ? [] : serializeTags(tags);
 }
 

package/src/server.ts

@@ -47,10 +47,10 @@ export type {
   IsrServeResult,
 } from './render-isr';
 export {
-  createIsrController,
   DEFAULT_ISR_REGENERATE_DEADLINE_MS,
   ISR_LOCALE_PARAM,
   invalidateAndRevalidate,
+  isrController,
   isrKey,
 } from './render-isr';
 export type { IsrEntry, IsrState, IsrStore, MemoryIsrStoreOptions } from './render-isr-store';

package/src/stylesheet-path.ts

@@ -0,0 +1,34 @@
+// One responsibility: the ONE spelling of a filesystem path the stylesheet registry compares — `/`
+// separators, `..` folded, a Windows drive letter upper-cased — so "is this sheet below that
+// directory" means the same on Windows, where Bun hands every path over as `D:\app\…`, as on POSIX.
+
+// why: Bun ships no path API, and a relative root must be resolved against the working directory.
+import { posix, resolve } from 'node:path';
+
+/** POSIX-absolute (`/srv/app`), drive-absolute (`D:\app`, `d:/app`) or UNC (`\\host\share`). */
+const ABSOLUTE = /^(?:[A-Za-z]:)?[\\/]/;
+
+/**
+ * Comparable, never displayed: the registry keeps every sheet under the path it was handed and only
+ * COMPARES through this. An absolute path is not re-resolved, because `resolve('/app')` on Windows
+ * is `D:\app` — a drive the sheets a caller handed as `/app/…` never carry.
+ */
+export function comparablePath(path: string): string {
+  const absolute = ABSOLUTE.test(path) ? path : resolve(path);
+  const slashed = posix.normalize(absolute.replaceAll('\\', '/'));
+  const drive = slashed.replace(/^([a-z]):/, (_, letter: string) => `${letter.toUpperCase()}:`);
+  // A trailing separator is dropped so `${dir}/` is one prefix — except the filesystem root itself.
+  const trimmed = drive.replace(/\/+$/, '');
+  return trimmed === '' || trimmed.endsWith(':') ? `${trimmed}/` : trimmed;
+}
+
+/** `path` sits below `dir` — both already `comparablePath`. A sibling sharing a prefix does not. */
+export function isPathBelow(path: string, dir: string): boolean {
+  return path.startsWith(dir.endsWith('/') ? dir : `${dir}/`);
+}
+
+/** `path` relative to `dir` when it sits below it, else `path` — both already `comparablePath`. */
+export function pathBelow(path: string, dir: string): string {
+  if (!isPathBelow(path, dir)) return path;
+  return path.slice(dir.endsWith('/') ? dir.length : dir.length + 1);
+}