@ultimat3/render 9.0.0 → 11.0.0

package/CLAUDE.md

@@ -48,7 +48,7 @@ for the mirror-image reason, keeping `render → pwa` refused. Never `cli` (upwa
 | Island node shape | a **branded array** (`IslandNode extends Array<never>`), and every walker tests `isIslandNode` BEFORE `Array.isArray`. An app types JSX with `jsxImportSource: solid-js`, whose `JSX.Element` is a type ALIAS — unaugmentable — and whose only object-shaped member is `ArrayElement`; a plain object was TS2786 at every `<Island />`, so the feature only worked through `h(Island, …)`, which is what render's own tests used. The array stays empty; the shell is `props.children`. Never satisfy this by importing solid's union. |
 | Island declaration order | `island()` above `defineRoute`, drained by it (`drainDeclaredIslands`). Package-internal — reachable from `./island`, never re-exported by `src/index.ts`: an app calling the drain between its `island()` and its `defineRoute` would silently un-declare the islands the route derives everything from, and a public export is semver-locked the moment it ships. Ambient, and NOT the thing the collector refuses to be: that one is per RENDER, where two requests would bill each other; this one is per MODULE, evaluated once, before any request — and `src` is resolved relative to the route file, so an `island()` call is route-module-local by construction. |
 | Derived budget | `registry.ts`, not `defineRoute`: a ceiling is only meaningful against a surface baseline, and the surface is a fact of the file path the route table already reads. `site/` → `20kb`, `app/` → `34kb` (`DEFAULT_ISLAND_JS_BYTES` above `jsBaselineBytes`). **Calibrated on a Solid island** `As of 2026-08`: it was `4kb`, sized from `contact-sales.island.tsx`, which imports no `solid-js` at all — and `render(() => <p>hello</p>, el)` measures 12,588 B, so the default sat a factor of three below the floor of every island that uses the JSX runtime, on every surface. A declared `budget.js` wins; a `'never'` route gets none, so the contradiction stays visible. |
-| `RouteEntry.islands` | filled from `config.islands` at registration, and from nothing else — `RegisterRouteInput` has no `islands` key. It was `input.islands ?? []`, undocumented and passed by nothing, so `routeJsBytes`'s "what registration declared" half read `[]` on every route in the framework's history; keeping it as a fallback would be a second answer to one question that can only ever weaken it, since a caller passing `[]` un-weighs a declared island. |
+| `RouteEntry.islands` | filled from `config.islands` at registration, and from nothing else — `RegisterRouteInput` has no `islands` key. It was `input.islands ?? []`, undocumented and passed by nothing, so the now-deleted `routeJsBytes`'s "what registration declared" half read `[]` on every route in the framework's history; keeping it as a fallback would be a second answer to one question that can only ever weaken it, since a caller passing `[]` un-declares an island. The field survives its one former reader: it is the only record a build has of an island a page declared but did not render on a given pass. |
 | Island props | declared, JSON-safe, under `ISLAND_PROPS_MAX_BYTES` — `island-props.ts` is the one gate. A structural walk, never a `JSON.stringify` round trip: stringify drops a function and an `undefined` silently, which is the footgun rather than the check. |
 | A prop lands via `Object.defineProperty` | never `out[key] = v`. For exactly one name — `__proto__`, which `JSON.parse` mints as a real OWN key off any request body — the assignment runs `Object.prototype`'s setter: the prop was DROPPED from the browser payload (the footgun the walk exists to prevent), the record handed back as `IslandProps` carried a prototype built from request data, so a later `bag.row.isAdmin` on the SERVER read attacker-chosen values, and `ISLAND_PROPS_MAX_BYTES` under-counted because `JSON.stringify` could not see it. Same shape `@ultimat3/mcp`'s `validate-args.ts` uses for the same class. |
 | An attribute alias is a `Map` | never a record — an object lookup walks the prototype chain, so `<div {...row} />` with a column named `toString` resolved the alias to a FUNCTION and `attribute.toLowerCase()` threw a bare `TypeError`: no code, no fix, the whole page 500s off a `load()` result. Same reason `MODE_SPECS[config.render]` in `modes.ts` is guarded by `Object.hasOwn`, where `render: 'constructor'` returned a frozen descriptor for a mode nothing implements. |
@@ -56,10 +56,12 @@ for the mirror-image reason, keeping `render → pwa` refused. Never `cli` (upwa
 | Which attributes take a URL | `URL_BEARING_ATTRIBUTES` in `html.ts` — core's four (`href`, `src`, `action`, `formaction`) plus `data`, `poster`, `ping` and `xlink:href`, each of which a browser FOLLOWS. `srcdoc` is refused outright: its value is entity-decoded and THEN parsed as HTML, so `escapeAttribute`'s `&lt;script&gt;` becomes a live `<script>` on this origin — escaping cannot make markup inert, so the attribute is never emitted, the same way `innerHTML` stays the one explicit escape hatch. |
 | Island collection | per render, passed as `renderToHtml(tree, { islands })`. Never module-global and never on an ambient context — two concurrent requests would bill one page for the other's JS, and `assertNoPerRequestState` refuses a live context under `static` anyway. |
 | A byte count in a message | `formatBytes` from `@ultimat3/core`, never a local one. This package's copy stopped at `kb`, so a 5 MB route read `5120kb` in `X_BUDGET_EXCEEDED` while `@ultimat3/pwa`'s own copy said `5mb` for the same bytes — two halves of one build disagreeing about the size of one artifact. Still on this barrel, because `@ultimat3/cli`'s budget reporter reads it beside the route table. |
-| Island bytes | `routeJsBytes` unions `entry.islands` with the rendered directives' `moduleId`s. Reading either alone is a budget that counts the runtime and not the chunk. |
+| Island bytes | **not this package's**, `As of 2026-08-23`. `routeJsBytes`, `graphFor`, `checkBudget`, `checkBudgets`, `assertBudget` and the `Island` / `BundleGraph` / `RouteBytes` / `BudgetReport` types were exported from the barrel and called by NOTHING outside this package's own tests — the near-miss is `@ultimat3/cli`'s own `checkBudgets` in `packages/cli/src/budgets.ts`, which measures the EMITTED document and is the gate that runs. Deleted rather than wired, because two answers to "what does this route weigh" — one of them never asked — is axiom 1, and a build error nothing calls is not a build error. What survives here is the budget GRAMMAR (`parseByteBudget`, which the CLI does import) and `defaultIslandBudget`, which `registerRoute` reaches. **Breaking**: the six functions and five types are gone from the public API. |
+| The hydration runtime's CSP | `HYDRATE_RUNTIME_BODIES` — every body `hydrateRuntime` can emit, one per non-empty subset of the three strategies, seven in all. It is emitted INLINE in every document carrying an island, and `@ultimat3/http`'s `script-src` is `'self' 'wasm-unsafe-eval'`, so under the enforced policy a container serves (`dev: false`) **no island ever booted** — invisible in `x dev`, where the policy is report-only. `@ultimat3/cli`'s `script-csp.ts` hashes this list at boot, the mirror of `style-csp.ts`. Hashes and not a nonce, for `cspHashSource`'s own reason: a `render: 'static'` page is a file on disk. Never restate the concatenation — `runtimeBody` is the one place the served text and the hashed text are the same string. **Still uncovered**: `render-stream.ts`'s per-hole `<script>$X("id")</script>`, whose body is per-response and cannot be hashed. Unreachable today (`dev-render.ts` passes `holes: []`), and the first real hole needs a nonce, not a hash. |
 | Island markup | the props `<script>` is emitted INSIDE the wrapper by `render-html.ts`, so a document assembler has exactly one thing left to remember: `hydrateRuntime(directives)`. |
 | Island boot | `el.__x` holds the boot PROMISE, never a boolean. As a flag, a second interaction while the chunk was still loading got a resolved promise back and the replay queue flushed into an island that had not mounted — the events went nowhere and the listeners were already removed. |
-| Island mount markers | `data-x-mounted=""` when `mount()` RESOLVED, `data-x-failed="<message>"` when it rejected — set by the runtime, never by `emitIslandAttributes`, because the server does not know the answer. `el.__x` alone cannot carry this: it is assigned when `import()` is CALLED, so a chunk still downloading and one whose `mount()` threw were the same observable, and telling those apart is what `x shot` gates on. Two attributes rather than two values of one, so `[data-x-mounted]` never counts a failure as a success. The rejection handler RETHROWS — swallowing it resolves `el.__x` and the interaction runtime flushes its replay queue into an island that never mounted, which is the row above reintroduced one layer out. Costs 129 B of shared prelude: `idle` 744, `visible` 816, `interaction` 1,010 (`As of 2026-08-21`, the numbers `DEFAULT_ISLAND_JS_BYTES` is derived from). |
+| Island mount markers | `data-x-mounted=""` when `mount()` RESOLVED, `data-x-failed="<message>"` when it rejected — set by the runtime, never by `emitIslandAttributes`, because the server does not know the answer. `el.__x` alone cannot carry this: it is assigned when `import()` is CALLED, so a chunk still downloading and one whose `mount()` threw were the same observable, and telling those apart is what `x shot` gates on. Two attributes rather than two values of one, so `[data-x-mounted]` never counts a failure as a success. The rejection handler RETHROWS — swallowing it resolves `el.__x` and the interaction runtime flushes its replay queue into an island that never mounted, which is the row above reintroduced one layer out. Costs 129 B of shared prelude: `idle` 774, `visible` 846, `interaction` 1,067 (`As of 2026-08-23`, the numbers `DEFAULT_ISLAND_JS_BYTES` is derived from). |
+| A runtime that calls `boot` | TERMINATES the chain, because `boot` rethrows. `idle` and `visible` end in `.catch(hush)`; `interaction` passes `off` as the rejection arm of its `then`. A bare `boot(el)` produced a fresh rejected promise per call — one unhandled rejection per user event on an island whose `mount()` threw — and, on `interaction`, left `done` false, the listeners attached and the queue growing by one retained `Event` (each with a live `target`) per click, for an island that will never mount. Nothing is lost by swallowing here: the DOM already carries the failure as `data-x-failed`, which is the row above and the documented observable. `hydrate-runtime.test.ts` runs all three against a real module; Bun's runner fails a test on an unhandled rejection, so the omission reds the suite by itself. |
 | `idle`'s deadline | `IDLE_HYDRATE_TIMEOUT_MS`, interpolated INTO the runtime string. Exported because a second reader has to agree — `x shot` waits before it photographs, and a settle shorter than this deadline reports an unhydrated page for one that hydrates perfectly. A constant the emitted string restates instead of reading is worse than no constant. |
 | Route truth | `registry.ts`. Never keep a second route list anywhere, and never a second *matcher*: this package's `matchRoute` was deleted in 2026-08 with zero consumers, because `@ultimat3/http`'s trie (`stages.ts`) is the one that serves requests and two matchers with different precedence rules is two answers to "which route is this?". `routeFor` is an exact-path `Map` lookup, not a pattern matcher. |
 | Route filename | `page.tsx` under `site/`/`app/`, `route.ts` under `api/` — `ROUTE_FILENAME`, one per surface. The URL is the directory path. Anything else is `X_ROUTE_FILE_INVALID`; never widen the table to accept a second spelling. |
@@ -71,6 +73,9 @@ for the mirror-image reason, keeping `render → pwa` refused. Never `cli` (upwa
 | "Is this a TTL?" has one reader | `parseTtlMs` in `duration.ts`, below both `modes.ts` and `render-isr.ts` (importing the latter from the former is a cycle through `registry.ts`). `hasRevalidateTrigger` accepted any non-empty string, so `revalidate: { ttl: '5 minutes' }` passed registration and parsed to `null` at serve time: generated ONCE, served for the life of the process, while the CDN was told `s-maxage=60` — the exact costume the `isr`-needs-a-trigger check refuses. |
 | A build-time frame reads a throw with `renderThrowable` | `render-html.ts`, `render-static.ts`, `css-modules.ts`, `module-loader.ts`, `route-data.ts` — never `error instanceof Error ? error.message : String(error)`. A component that throws `Object.create(null)` escaped as a bare `TypeError` and one whose `message` getter throws as a bare `Error`, where `X_PRERENDER_FAILED` naming the file belongs. `bun run error-render` does NOT see this shape: it follows a direct interpolation, not a value laundered through a file-local `describe()` helper. |
 | `X_ROUTE_LOAD_FAILED` computes its pathname BEFORE the try | `new URL(ctx.url)` inside the catch made a relative `ctx.url` — what a prerender pass, `x build` and every test harness hand in — throw a bare `TypeError` on the one path whose job is a coded error. `pathnameOf` never throws. |
+| The ISR key | `isrKey(url, locale)` — pathname, the negotiated LOCALE in the reserved `__x_locale` parameter, then the query, params sorted. The locale is a REQUIRED argument, so every call site has to answer: a document is rendered with `<html lang>` and every `t()` in the request's own locale, so one entry per path served visitor 2 the document negotiated for visitor 1 — for the whole TTL, and `s-maxage` told the CDN to do the same. `examples/dummy` ships en + es and three `isr` routes, so it was all three. A parameter and not a prefix because `routePathOf` splits a key at its `?`: a `es:/blog` key matches no route, so `descriptorFor` answers `undefined` and a declared `ttl` silently becomes tag-only. The time zone is deliberately NOT a dimension — unbounded where a locale set is declared — so a date on an `isr` page belongs in a zone the page itself names. `toResult` emits `vary: accept-language` for the CDN half; the rest of the shared key is added by `@ultimat3/http`'s `cache-headers` stage, which sees the actor this function cannot. |
+| A bust that lands MID-render | fenced with `@ultimat3/cache`'s `sampleFence({ key, tags })`, taken before `render()` and asked before `store.set` — the same mechanism `CacheStack`'s read-through fill uses, never a second one grown here. `regenerate` rendered and then wrote `{ stale: false }` unconditionally, so a `markStale` arriving in between was ERASED by HTML built from pre-write rows; for a tag-only route `isFresh` is then true forever and the process serves it for the rest of its life. `registerPath` runs BEFORE the render for the other half: `revalidateByTags` reads the graph, so a bust could not see a cold path whose first render was still in flight. |
+| Marking a page stale | `IsrStore.markStale(path)`, in place — never `set({ ...entry, stale: true })`. `set` means "this page was just generated" and the default store orders eviction by exactly that, so the read-modify-write made the STALEST page the newest: a tag bust protected the pages that most needed regenerating and evicted the freshest one instead. **Breaking**: `markStale` is a required member of `IsrStore`. |
 | ISR store bound | `memoryIsrStore()` caps at `DEFAULT_ISR_MAX_ENTRIES` (1,000), least recently generated first — a route table supports `:params` and `*`, so `/blog/:slug` retains one full HTML string per slug ever requested, 404-shaped ones included. |
 | Route path from file | ONE reader of the surface segment: `locateSurface()` answers which surface AND where it starts. `registry.ts` sliced at `indexOf('app/')` instead, which matched inside `myapp/`, so every route under `apps/myapp/app/` served at `/app/…`. Never re-derive the offset from the surface NAME. |
 | An undecodable path segment | not a match, never a throw — `decodeSegment` in `registry.ts` is the one reader. `decodeURIComponent('%zz')` is a bare `URIError`, so a typo in a path segment was a 500 where `@ultimat3/http`'s router already answers "this branch does not match". A literal route matching the same text still wins. `router-client.ts` was the second reader and went with `createRouter`. |
@@ -80,6 +85,7 @@ for the mirror-image reason, keeping `render → pwa` refused. Never `cli` (upwa
 | Policy | render checks *presence* only. Evaluation belongs to `@ultimat3/policy`. |
 | A gated route is never a cached one | `modes.ts` refuses `policy` on BOTH `static` and `isr` (`X_ROUTE_MODE_INVALID`, `modes.test.ts`). `isr` was not refused until 2026-08 and `dev-render.ts` keys the cache on `url.pathname` alone — no actor, no query string — so a gated ISR route rendered the first actor's document and served it to every later actor who passed the same policy. Keying on more is a trap, not a fix: the key would have to enumerate everything a `policy` and a `load` can read. `ssr` is the one gated mode there is. |
 | Responses | return `RenderResult`. `@ultimat3/http` builds the `Response`. |
+| Who owns `cache-control` | a render mode states the MODE's intent; `@ultimat3/http`'s `cache-headers` stage makes the final answer and may overrule it. `ssrHeaders` writes `s-maxage=30` for any route without a `policy` — and `meta.auth` is `'public' \| 'required'`, so the page that greets a signed-in visitor by name is a `'public'` route whose own header offered it to a CDN. This package cannot see the actor and must never try: the fix is not a second actor check here. |
 | Solid | no `solid-js` import anywhere in this package — `type-pins.tsx` satisfies its `JSX.Element` structurally, through `jsxImportSource`, and never names it. The JSX factory in `jsx.ts` builds inert nodes — it is not a Solid renderer and must never become one. The client half runs in an island chunk, which `@ultimat3/cli`'s `solid-loader.ts` compiles with `babel-preset-solid`: Solid's reactivity is a COMPILE-time contract, so nothing this package could inject would substitute for it. `router-client.ts` was the one file built on that premise ("inject primitives") and it never had a caller. |
 | Root element | `ROOT_ELEMENT_ID` (`render-html.ts`), the id every document's body wraps its component in. It was `SPA_ROOT_ID` in `render-spa.ts`, naming a mode that never used it and that no longer exists. |
 | The loaders | `module-loader.ts` installs them at **`server.ts`** module scope, once — `index.ts` until the barrel split, and it cannot be there again: the client barrel would carry `sass` and `node:url`. A plugin only affects modules loaded after it, so a second install point is a page that renders in one entry point and not another. Anything that loads an app's `.tsx` reaches `@ultimat3/render/server` first, which is why `packages/cli/src/app-load.ts` imports it for the side effect and nothing else. |

package/README.md

@@ -280,18 +280,22 @@ are never serialized.
 const collector = createIslandCollector({ file, hydrate: config.hydrate, resolve });
 const html = await renderToHtml(page, { islands: collector });
 document.body += hydrateRuntime(collector.directives);   // the one thing left to remember
-assertBudget(entry, measuredIslands, collector.directives);
 ```
 
-`routeJsBytes` reads **both** sources — what registration declared in `entry.islands` and what the
-render actually pulled in. Reading only the first is how a page could be charged for the hydration
-runtime and not for the chunk it boots: a budget that counts the wrapper and not the code.
+Declaring an island is what puts a `budget.js` on the route — `defaultIslandBudget(surface)`,
+applied by `registerRoute`, so a page that declares one is charged without saying so. **Weighing it
+is `x verify`'s `budgets` step**, which measures the emitted document against the manifest's
+per-route budget and fails with `X_BUDGET_EXCEEDED`.
+
+**Removed `As of 2026-08-23`** (breaking): `routeJsBytes`, `graphFor`, `checkBudget`, `checkBudgets`, `assertBudget` and
+the `Island` / `BundleGraph` / `RouteBytes` / `BudgetReport` types. They were a second, graph-based
+answer to the same question that nothing in the framework ever asked — the gate has always been the
+CLI's. `parseByteBudget` (the `'40kb'` grammar) and `defaultIslandBudget` stay.
 
 `entry.islands` is filled from `config.islands` at registration and from nothing else, so a declared
-island is weighed even on a route no render has touched. It was `input.islands ?? []` and nothing
-ever passed `islands`, which left that half of the union reading nothing at all; `RegisterRouteInput`
-no longer carries the key, because the only thing a caller could do with it was un-weigh a
-declaration.
+island is on the record even on a route no render has touched. It was `input.islands ?? []` and
+nothing ever passed `islands`; `RegisterRouteInput` no longer carries the key, because the only
+thing a caller could do with it was un-declare an island.
 
 An island on a route that resolves to `hydrate: 'never'`, or rendered with no collector, is
 `X_ISLAND_NOT_HYDRATED` — inert markup either way. With `hydrate` derived it means one of exactly
@@ -359,9 +363,9 @@ side effect. Anything that loads an app's source — `x dev`, `x build`, `server
 | `renderSsr`†, `streamResult`† | the per-request modes |
 | `renderToHtml`†, `renderComponent`†, `stylesFor`† | the server JSX writer and the surface's css |
 | `installRenderLoader`†, `compileStylesheet`† | the `.tsx`/`.scss` loaders, installed on import |
-| `emitIslandAttributes`, `hydrateRuntime` | the four hydration strategies |
+| `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 |
-| `graphFor`, `checkBudget`, `assertBudget` | two bundle graphs, per-route budgets |
+| `parseByteBudget`, `defaultIslandBudget` | the `'40kb'` budget grammar, and the ceiling a declared island earns |
 | `mergeHead`, `renderHead`, `themeScript` | `<head>` merge + the one inlined script |
 
 ## Notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/render",
-  "version": "9.0.0",
+  "version": "11.0.0",
   "description": "The route primitive and the five render modes: static, isr, ssr, stream, spa.",
   "license": "MIT",
   "type": "module",
@@ -36,10 +36,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "9.0.0",
-    "@ultimat3/core": "9.0.0",
-    "@ultimat3/i18n": "9.0.0",
-    "@ultimat3/seo": "9.0.0",
+    "@ultimat3/cache": "11.0.0",
+    "@ultimat3/core": "11.0.0",
+    "@ultimat3/i18n": "11.0.0",
+    "@ultimat3/seo": "11.0.0",
     "sass": "1.102.0"
   }
 }

package/src/errors.ts

@@ -54,7 +54,12 @@ registerErrorCodes(
   Object.fromEntries(Object.entries(RENDER_ERROR_TITLES).map(([code, title]) => [code, { title }])),
 );
 
-const docsFor = (code: RenderErrorCode): string => `https://ultimate.dev/errors/${code}`;
+// No `docs:` on the subclasses below. `UltimateError` fills it from `describeErrorCode(code).docs`,
+// which is `@ultimat3/core`'s `ERROR_DOCS_URL` — one page for every code, never one per code, because
+// `wiki/` is the framework's only public documentation surface and a code lives there in a TABLE ROW,
+// which has no anchor. The `https://ultimate.dev/errors/<code>` links this file built until 9.x
+// answered 404, host included, on every error it has ever thrown; restating the replacement here
+// would be the same constant in eight places waiting to drift again.
 
 /** A render mode's invariant was violated at registration (see `modes.ts`). */
 export class RouteModeInvalidError extends UltimateError {
@@ -64,7 +69,6 @@ export class RouteModeInvalidError extends UltimateError {
       code: RouteModeInvalidError.code,
       cause,
       fix,
-      docs: docsFor(RouteModeInvalidError.code),
     });
   }
 }
@@ -77,7 +81,6 @@ export class RouteOfflineMissingError extends UltimateError {
       code: RouteOfflineMissingError.code,
       cause,
       fix,
-      docs: docsFor(RouteOfflineMissingError.code),
     });
   }
 }
@@ -90,7 +93,6 @@ export class RouteMetaMissingError extends UltimateError {
       code: RouteMetaMissingError.code,
       cause,
       fix,
-      docs: docsFor(RouteMetaMissingError.code),
     });
   }
 }
@@ -107,7 +109,6 @@ export class RouteUnnormalizedError extends UltimateError {
       code: RouteUnnormalizedError.code,
       cause,
       fix,
-      docs: docsFor(RouteUnnormalizedError.code),
     });
   }
 }
@@ -120,7 +121,6 @@ export class RouteDuplicateError extends UltimateError {
       code: RouteDuplicateError.code,
       cause,
       fix,
-      docs: docsFor(RouteDuplicateError.code),
     });
   }
 }
@@ -138,7 +138,6 @@ export class RouteFileInvalidError extends UltimateError {
       code: RouteFileInvalidError.code,
       cause,
       fix,
-      docs: docsFor(RouteFileInvalidError.code),
     });
   }
 }
@@ -151,7 +150,6 @@ export class SurfaceBoundaryError extends UltimateError {
       code: SurfaceBoundaryError.code,
       cause,
       fix,
-      docs: docsFor(SurfaceBoundaryError.code),
     });
   }
 }
@@ -164,7 +162,6 @@ export class BudgetExceededError extends UltimateError {
       code: BudgetExceededError.code,
       cause,
       fix,
-      docs: docsFor(BudgetExceededError.code),
     });
   }
 }
@@ -177,7 +174,6 @@ export class PrerenderFailedError extends UltimateError {
       code: PrerenderFailedError.code,
       cause,
       fix,
-      docs: docsFor(PrerenderFailedError.code),
     });
   }
 }
@@ -190,7 +186,6 @@ export class RouteLoadInvalidError extends UltimateError {
       code: RouteLoadInvalidError.code,
       cause,
       fix,
-      docs: docsFor(RouteLoadInvalidError.code),
     });
   }
 }
@@ -207,7 +202,6 @@ export class IslandInvalidError extends UltimateError {
       code: IslandInvalidError.code,
       cause,
       fix,
-      docs: docsFor(IslandInvalidError.code),
     });
   }
 }
@@ -224,7 +218,6 @@ export class IslandPropsInvalidError extends UltimateError {
       code: IslandPropsInvalidError.code,
       cause,
       fix,
-      docs: docsFor(IslandPropsInvalidError.code),
     });
   }
 }
@@ -242,7 +235,6 @@ export class IslandNotHydratedError extends UltimateError {
       code: IslandNotHydratedError.code,
       cause,
       fix,
-      docs: docsFor(IslandNotHydratedError.code),
     });
   }
 }
@@ -259,7 +251,6 @@ export class RouteLoadFailedError extends UltimateError {
       code: RouteLoadFailedError.code,
       cause,
       fix,
-      docs: docsFor(RouteLoadFailedError.code),
     });
   }
 }

package/src/hydrate.ts

@@ -6,6 +6,7 @@
  */
 
 import type { HydrateStrategy } from '@ultimat3/core';
+import { HYDRATE_STRATEGIES } from '@ultimat3/core';
 import { escapeAttribute, escapeJsonContent } from './html';
 
 export interface IslandDirective {
@@ -85,7 +86,10 @@ export function emitIslandAttributes(directive: IslandDirective): string {
 export function emitIslandProps(directive: IslandDirective): string {
   if (directive.props === undefined || directive.strategy === 'never') return '';
   return (
-    `<script type="application/json" data-x-props="${directive.islandId}">` +
+    // The id goes through the SAME escaper every other attribute in this file does. Safe today —
+    // `islandModuleId` reduces to `[a-z0-9-]` — which is exactly why it costs nothing to route it
+    // now, rather than after an id starts being derived from something an author did not type.
+    `<script type="application/json" data-x-props="${escapeAttribute(directive.islandId)}">` +
     `${escapeJsonContent(JSON.stringify(directive.props))}</script>`
   );
 }
@@ -122,31 +126,44 @@ return el.__x=import(e).then(function(m){return m.mount(el,props)}).then(
 function(r){el.setAttribute('${ISLAND_MOUNTED_ATTRIBUTE}','');return r},
 function(x){el.setAttribute('${ISLAND_FAILED_ATTRIBUTE}',x&&x.message||'1');throw x})}
 function each(s,f){Array.prototype.forEach.call(document.querySelectorAll(s),f)}
+function hush(){}
 `.trim();
+// `hush` above: `boot` rethrows, so every runtime below has to terminate the chain it starts or
+// the page reports an unhandled rejection for a failure it already recorded on the element.
 
 const RUNTIME_IDLE = `
 each('[data-x-hydrate="idle"]',function(el){
-var go=function(){boot(el)};
+var go=function(){boot(el).catch(hush)};
 if('requestIdleCallback'in window)requestIdleCallback(go,{timeout:${IDLE_HYDRATE_TIMEOUT_MS}});else setTimeout(go,1)})
 `.trim();
 
 const RUNTIME_VISIBLE = `
 each('[data-x-hydrate="visible"]',function(el){
 var io=new IntersectionObserver(function(es){es.forEach(function(en){
-if(en.isIntersecting){io.disconnect();boot(el)}})},{rootMargin:el.getAttribute('data-x-margin')||'200px'});
+if(en.isIntersecting){io.disconnect();boot(el).catch(hush)}})},{rootMargin:el.getAttribute('data-x-margin')||'200px'});
 io.observe(el)})
 `.trim();
 
 // Event replay: the listener is registered before the chunk exists, records the event that
 // woke the island, and re-dispatches it once mounted. Without this, the first click on a
 // cold island is silently lost — the failure users read as "the button does nothing".
+//
+// `off` is BOTH arms of the `then`, and the rejection arm is the reason it is a named function.
+// `boot` rethrows on purpose (see the prelude), so `el.__x` holds a rejected promise from the
+// first failed mount onward — and a `.then` with no rejection handler makes a fresh rejected
+// promise out of it on EVERY event, i.e. one unhandled rejection per user click, forever. The
+// queue was the second half: nothing ever set `done`, so the listeners stayed attached and `q`
+// grew by one retained `Event` — each holding a live `target` — per click, for an island that
+// will never mount. Swallowing here loses no signal: the DOM already carries the failure as
+// `data-x-failed`, which is the documented observable.
 const RUNTIME_INTERACTION = `
 each('[data-x-hydrate="interaction"]',function(el){
 var evs=(el.getAttribute('data-x-events')||'click').split(' ');
 var q=[],done=false;
+var off=function(){done=true;evs.forEach(function(n){el.removeEventListener(n,on,true)});q=[]};
 var on=function(ev){if(done)return;q.push(ev);
-boot(el).then(function(){done=true;evs.forEach(function(n){el.removeEventListener(n,on,true)});
-q.forEach(function(ev){var c=new ev.constructor(ev.type,ev);ev.target.dispatchEvent(c)});q=[]})};
+boot(el).then(function(){var r=q;off();
+r.forEach(function(ev){var c=new ev.constructor(ev.type,ev);ev.target.dispatchEvent(c)})},off)};
 evs.forEach(function(n){el.addEventListener(n,on,true)})})
 `.trim();
 
@@ -156,6 +173,44 @@ const RUNTIME_PARTS: Readonly<Record<Exclude<HydrateStrategy, 'never'>, string>>
   interaction: RUNTIME_INTERACTION,
 };
 
+/**
+ * Emission order, and the order the subsets below are enumerated in. Derived from core's one
+ * declaration of the vocabulary, never restated: a second literal of this set is what
+ * `bun run render-modes` refuses, and it refuses it on the MEMBERS, not on the name.
+ */
+const RUNTIME_ORDER: readonly Exclude<HydrateStrategy, 'never'>[] = HYDRATE_STRATEGIES.filter(
+  (strategy): strategy is Exclude<HydrateStrategy, 'never'> => strategy !== 'never',
+);
+
+/**
+ * The TEXT of the runtime script for exactly these strategies — the body a CSP `script-src` hash
+ * is taken over. Split out of `hydrateRuntime` so the served document and the policy that admits
+ * it read one function: a second copy of this concatenation is a hash that stops matching the
+ * 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 =>
+  [
+    RUNTIME_PRELUDE,
+    ...RUNTIME_ORDER.filter((strategy) => needed.has(strategy)).map(
+      (strategy) => RUNTIME_PARTS[strategy],
+    ),
+  ].join('\n');
+
+/**
+ * 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
+ * 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))),
+);
+
 /**
  * Emit only the runtime the page's islands actually use. A page of `never` islands gets
  * the empty string — an unused strategy must not cost a byte.
@@ -163,10 +218,7 @@ const RUNTIME_PARTS: Readonly<Record<Exclude<HydrateStrategy, 'never'>, string>>
 export function hydrateRuntime(directives: readonly IslandDirective[]): string {
   const needed = requiredStrategies(directives);
   if (needed.size === 0) return '';
-  const parts = (['idle', 'visible', 'interaction'] as const)
-    .filter((strategy) => needed.has(strategy))
-    .map((strategy) => RUNTIME_PARTS[strategy]);
-  return `<script type="module">${RUNTIME_PRELUDE}\n${parts.join('\n')}</script>`;
+  return `<script type="module">${runtimeBody(needed)}</script>`;
 }
 
 /** Rough emitted size of the hydration runtime for a page, for the budget check. */

package/src/index.ts

@@ -57,6 +57,7 @@ export {
   DEFAULT_REPLAY_EVENTS,
   emitIslandAttributes,
   emitIslandProps,
+  HYDRATE_RUNTIME_BODIES,
   hydrateRuntime,
   hydrateRuntimeBytes,
   IDLE_HYDRATE_TIMEOUT_MS,
@@ -77,15 +78,7 @@ export type { IslandCollector, IslandCollectorInput } from './island-collector';
 export { createIslandCollector, islandModuleIds } from './island-collector';
 export type { IslandProps, JsonValue } from './island-props';
 export { checkIslandProps, ISLAND_PROPS_MAX_BYTES } from './island-props';
-export type { BudgetReport, BundleGraph, GraphName, Island, RouteBytes } from './islands';
-export {
-  assertBudget,
-  checkBudget,
-  checkBudgets,
-  graphFor,
-  parseByteBudget,
-  routeJsBytes,
-} from './islands';
+export { parseByteBudget } from './islands';
 export type { JsxComponent, JsxNode, JsxProps } from './jsx';
 export { Fragment, h, isJsxNode, JSX_NODE } from './jsx';
 export type { ModeCheckContext, ModeSpec, RouteShape } from './modes';

package/src/islands.ts

@@ -1,50 +1,19 @@
 /**
- * Island boundaries and the two separate bundle graphs. `site/` and `app/` never share a
- * graph: that is the mechanical half of axiom 6 (the surface boundary in `surfaces.ts` is
- * the other half). `site/` starts at a 0kb baseline and every byte after that is an
- * opt-in, budgeted island.
+ * How a byte budget is WRITTEN — `'40kb'` — and nothing else.
+ *
+ * It was the whole graph-based budget API: `Island`, `BundleGraph`, `graphFor`, `routeJsBytes`,
+ * `checkBudget`, `checkBudgets`, `assertBudget`. Every one of them was exported from the barrel and
+ * called by nothing outside this package's own tests. The real gate is `@ultimat3/cli`'s
+ * `checkBudgets` (`packages/cli/src/budgets.ts`), which measures the EMITTED document against the
+ * manifest's per-route `budget` and has its own `parseByteBudget` caller — the near-miss that made
+ * the dead half look reached. Deleted 2026-08-23 rather than wired: two answers to "what does this
+ * route weigh", one of which never ran, is the ambiguity axiom 1 refuses, and a build error nothing
+ * calls is not a build error.
+ *
+ * `defaultIslandBudget` in `modes.ts` is the surviving half of the island-budget story: it is
+ * reached, through `registerRoute`, and it is what puts a number on a route that declares none.
  */
 
-import type { HydrateStrategy } from '@ultimat3/core';
-// One formatter, in `@ultimat3/core`: the copy that lived here had no `mb` branch, so a 5 MB route
-// read `5120kb` in `X_BUDGET_EXCEEDED` while `@ultimat3/pwa` said `5mb` for the same bytes.
-import { formatBytes } from '@ultimat3/core';
-import { BudgetExceededError } from './errors';
-import type { IslandDirective } from './hydrate';
-import { hydrateRuntimeBytes } from './hydrate';
-import type { RouteEntry } from './registry';
-import type { Surface } from './surfaces';
-import { SURFACE_SPECS } from './surfaces';
-
-/** A bundle graph is per surface. There are exactly two that ship JS: `site` and `app`. */
-export type GraphName = 'site' | 'app';
-
-export interface Island {
-  readonly id: string;
-  readonly file: string;
-  readonly graph: GraphName;
-  readonly strategy: HydrateStrategy;
-  /** Measured from the real bundle, gzip-before-brotli agnostic: raw bytes. */
-  readonly bytes: number;
-  /** The import chain that pulled the heaviest dependency in, for error messages. */
-  readonly heaviestChain?: readonly string[];
-}
-
-export interface BundleGraph {
-  readonly name: GraphName;
-  readonly baselineBytes: number;
-  readonly islands: readonly Island[];
-}
-
-export function graphFor(surface: Surface, islands: readonly Island[]): BundleGraph {
-  const name: GraphName = surface === 'site' ? 'site' : 'app';
-  return {
-    name,
-    baselineBytes: SURFACE_SPECS[name].jsBaselineBytes,
-    islands: islands.filter((island) => island.graph === name && island.strategy !== 'never'),
-  };
-}
-
 const UNITS: Readonly<Record<string, number>> = { b: 1, kb: 1024, mb: 1024 * 1024 };
 
 /** `'40kb'` → 40960. Throws nothing: an unparseable budget is `null` and skipped. */
@@ -57,120 +26,3 @@ export function parseByteBudget(budget: string | undefined): number | null {
   const factor = UNITS[unit];
   return factor === undefined ? null : Math.round(Number(amount) * factor);
 }
-
-export interface RouteBytes {
-  readonly total: number;
-  readonly baseline: number;
-  readonly islandBytes: number;
-  readonly runtimeBytes: number;
-  readonly heaviest: Island | null;
-}
-
-export function routeJsBytes(
-  entry: RouteEntry,
-  islands: readonly Island[],
-  directives: readonly IslandDirective[] = [],
-): RouteBytes {
-  const graph = graphFor(entry.surface, islands);
-  // Two sources, unioned: `entry.islands` is what registration declared, and the directives are
-  // what the page actually rendered. Reading only the first is how the runtime bytes of an island
-  // could be charged while its chunk was not — a budget that counts the wrapper and not the code.
-  const onRoute = graph.islands.filter(
-    (island) =>
-      entry.islands.includes(island.id) ||
-      directives.some((directive) => (directive.moduleId ?? directive.islandId) === island.id),
-  );
-  const islandBytes = onRoute.reduce((sum, island) => sum + island.bytes, 0);
-  const runtimeBytes = directives.length > 0 ? hydrateRuntimeBytes(directives) : 0;
-  const baseline = islandBytes === 0 && runtimeBytes === 0 ? 0 : graph.baselineBytes;
-  const heaviest = onRoute.reduce<Island | null>(
-    (max, island) => (max === null || island.bytes > max.bytes ? island : max),
-    null,
-  );
-  return {
-    total: baseline + islandBytes + runtimeBytes,
-    baseline,
-    islandBytes,
-    runtimeBytes,
-    heaviest,
-  };
-}
-
-export interface BudgetReport {
-  readonly path: string;
-  readonly measured: number;
-  readonly limit: number | null;
-  readonly ok: boolean;
-  readonly cause: string | null;
-}
-
-/**
- * The build gate. Failure names the *cause* — the island and the transitive import that
- * added the bytes — because "bundle too big" without a chain is not an instruction.
- */
-export function checkBudget(
-  entry: RouteEntry,
-  islands: readonly Island[],
-  directives: readonly IslandDirective[] = [],
-): BudgetReport {
-  const bytes = routeJsBytes(entry, islands, directives);
-  const limit = parseByteBudget(entry.config.budget.js);
-
-  // site/ has a 0kb default: shipping JS there without declaring a budget is the failure.
-  if (limit === null && entry.surface === 'site' && bytes.total > 0) {
-    return {
-      path: entry.path,
-      measured: bytes.total,
-      limit: 0,
-      ok: false,
-      cause:
-        `${entry.path} is in site/ (0kb JS baseline) and ships ${formatBytes(bytes.total)} ` +
-        `with no budget.js${chainOf(bytes.heaviest)}`,
-    };
-  }
-
-  if (limit === null) {
-    return { path: entry.path, measured: bytes.total, limit: null, ok: true, cause: null };
-  }
-
-  const ok = bytes.total <= limit;
-  return {
-    path: entry.path,
-    measured: bytes.total,
-    limit,
-    ok,
-    cause: ok
-      ? null
-      : `${entry.path}  js ${formatBytes(bytes.total)} > ${formatBytes(limit)}${chainOf(bytes.heaviest)}`,
-  };
-}
-
-function chainOf(island: Island | null): string {
-  if (island === null) return '';
-  const chain = island.heaviestChain;
-  if (chain === undefined || chain.length === 0) return ` (heaviest island: ${island.file})`;
-  return ` (${chain.join(' → ')})`;
-}
-
-export function assertBudget(
-  entry: RouteEntry,
-  islands: readonly Island[],
-  directives: readonly IslandDirective[] = [],
-): void {
-  const report = checkBudget(entry, islands, directives);
-  if (report.ok || report.cause === null) return;
-  throw new BudgetExceededError(
-    report.cause,
-    `raise budget.js in ${entry.file} deliberately, or remove the import that added the bytes`,
-  );
-}
-
-/** `x verify` prints every route, not just the first failure. */
-export function checkBudgets(
-  entries: readonly RouteEntry[],
-  islands: readonly Island[],
-): readonly BudgetReport[] {
-  return entries
-    .map((entry) => checkBudget(entry, islands))
-    .sort((a, b) => a.path.localeCompare(b.path));
-}

package/src/modes.ts

@@ -225,18 +225,21 @@ export function defaultHydrate(surface: Surface): HydrateStrategy {
  * (`settings.island.tsx`) is 17,797 B. No `budget.js` under 4096 was reachable by any of them, on
  * any surface, because the allowance is measured above the baseline and not against it.
  *
- * The number: 17,797 (the heaviest island this repo actually ships) + 1,010 (`hydrateRuntimeBytes`
+ * The number: 17,797 (the heaviest island this repo actually ships) + 1,067 (`hydrateRuntimeBytes`
  * for one directive at `DEFAULT_ISLAND_HYDRATE`, which is `'interaction'` — `route.ts:33`, applied
- * at `:253` to any island route declaring no `hydrate`) = **18,807**. That is the worst case an
+ * at `:253` to any island route declaring no `hydrate`) = **18,864**. That is the worst case an
  * app reaches without writing a number down. 20,480 is NOT that rounded up — the next whole
- * kilobyte above it is 19,456 — it is one whole kB further, leaving 1,673 B of headroom and still
- * under 2x 18,807, so a route bundling the same island twice is refused. `island-budget.test.ts`
- * asserts all three. `idle` costs 744 and `visible` 816, so an island route that declares its
+ * kilobyte above it is 19,456 — it is one whole kB further, leaving 1,616 B of headroom and still
+ * under 2x 18,864, so a route bundling the same island twice is refused. `island-budget.test.ts`
+ * asserts all three. `idle` costs 774 and `visible` 846, so an island route that declares its
  * strategy pays less; the default is what the budget has to clear.
  *
  * All three grew by 129 B on 2026-08-21 (from 881 / 615 / 687), when the prelude learned to mark a
- * mount's OUTCOME so `x shot` can tell an island that RAN from one that only started loading. The
- * headroom absorbed it and the conclusion is unchanged — which is the point of stating the
+ * mount's OUTCOME so `x shot` can tell an island that RAN from one that only started loading, and
+ * again on 2026-08-23 — +18 B in the shared prelude (`hush`) for all three, +39 B more on
+ * `interaction` — when each runtime learned to TERMINATE the promise chain `boot` starts rather
+ * than emit one unhandled rejection per user event. The headroom absorbed both and the conclusion
+ * is unchanged, which is the point of stating the
  * arithmetic here rather than the answer alone. It is not
  * derived from Solid's own size on purpose — this package may not import or name `solid-js`
  * (`CLAUDE.md`), so a constant tracking the runtime's version would be a dependency in a comment.

package/src/registry.ts

@@ -269,9 +269,11 @@ export function registerRoute<TData = RouteData>(
     config,
     suspenseBoundaries,
     // The declaration is the ONLY source. It was `input.islands ?? []`, which nothing ever passed,
-    // so `routeJsBytes`'s "what registration declared" half read `[]` on every route in the
-    // framework's history — and keeping the input as a fallback would be a second answer to one
-    // question that can only ever weaken it: a caller passing `[]` un-weighs a declared island.
+    // so the now-deleted `routeJsBytes`'s "what registration declared" half read `[]` on every
+    // route in the framework's history — and keeping the input as a fallback would be a second
+    // answer to one question that can only ever weaken it: a caller passing `[]` un-declares an
+    // island. The field outlives that reader: it is the only record a build has of an island a
+    // page declared but did not render on a given pass.
     islands: config.islands.map((spec) => spec.moduleId),
     pattern: compilePattern(path),
     // Spread, never assigned: `exactOptionalPropertyTypes` makes an explicit `undefined` a

package/src/render-html.ts

@@ -30,6 +30,20 @@ export const ROOT_ELEMENT_ID = 'x-root';
 /** Depth is bounded so a component that renders itself fails with a cause instead of a stack trace. */
 const MAX_DEPTH = 500;
 
+/**
+ * Asserted at the top of `unwrap`, not only in `renderNode`. The element path was the only one
+ * bounded, and it is not the only one that recurses: `unwrap` walks arrays and calls thunks, both
+ * of which a component's `children` routinely are, so a self-referencing array or a self-returning
+ * accessor escaped `renderToHtml` as a bare `RangeError` — no code, no `fix:`, nothing to catch by.
+ */
+function assertDepth(depth: number): void {
+  if (depth <= MAX_DEPTH) return;
+  throw new PrerenderFailedError(
+    `component tree exceeded ${MAX_DEPTH} levels, so it renders itself`,
+    'remove the self-reference from the component that renders its own tag',
+  );
+}
+
 /**
  * What the walk carries besides depth. One object per render, never module-global: two concurrent
  * requests render different params, and a shared collector would bill one page for the other's JS.
@@ -41,8 +55,12 @@ export interface RenderHtmlOptions {
 /**
  * A thunk is called, not stringified. Solid's reactive reads are accessors (`count()`), and a
  * `children` prop is routinely a function — evaluating it once is exactly the server's job.
+ *
+ * Which is also why the depth bound belongs HERE and not only on the element path: the array and
+ * thunk branches below recurse, and both are ordinary shapes for a component's children.
  */
 async function unwrap(value: unknown, depth: number, walk: RenderHtmlOptions): Promise<string> {
+  assertDepth(depth);
   if (value === null || value === undefined || value === false || value === true) return '';
   if (typeof value === 'string') return escapeText(value);
   if (typeof value === 'number' || typeof value === 'bigint') return escapeText(String(value));
@@ -106,12 +124,7 @@ async function renderNode(
   depth: number,
   walk: RenderHtmlOptions,
 ): Promise<string> {
-  if (depth > MAX_DEPTH) {
-    throw new PrerenderFailedError(
-      `component tree exceeded ${MAX_DEPTH} levels, so it renders itself`,
-      'remove the self-reference from the component that renders its own tag',
-    );
-  }
+  assertDepth(depth);
   if (typeof type === 'string') return renderElement(type, props, depth, walk);
   return unwrap(type(props), depth + 1, walk);
 }

package/src/render-isr.ts

@@ -9,8 +9,10 @@ import type { CacheTag, Revalidator } from '@ultimat3/cache';
 import {
   dependentsOfKind,
   invalidateTags,
+  markInvalidated,
   registerDependent,
   registerRevalidator,
+  sampleFence,
   unregisterDependent,
 } from '@ultimat3/cache';
 import { logger, renderThrowable } from '@ultimat3/core';
@@ -40,6 +42,13 @@ export interface IsrEntry {
 export interface IsrStore {
   get(path: string): IsrEntry | undefined;
   set(entry: IsrEntry): void;
+  /**
+   * Mark a held page stale IN PLACE — `false` when the store does not hold it. Its own method and
+   * not `set({ ...entry, stale: true })`, because `set` means "this page was just generated" and a
+   * store is entitled to order its eviction by that: the read-modify-write made the STALEST page
+   * the newest, so a tag bust protected exactly the pages that most needed regenerating.
+   */
+  markStale(path: string): boolean;
   delete(path: string): void;
   paths(): readonly string[];
 }
@@ -73,6 +82,14 @@ export function memoryIsrStore(options: MemoryIsrStoreOptions = {}): IsrStore {
         map.delete(oldest.value);
       }
     },
+    // In place: `map.set` on a key the Map already holds keeps its position, and that position is
+    // the eviction order. Never `delete` + `set` here — that is the bug this method exists to fix.
+    markStale: (path) => {
+      const entry = map.get(path);
+      if (entry === undefined) return false;
+      map.set(path, { ...entry, stale: true });
+      return true;
+    },
     delete: (path) => {
       map.delete(path);
     },
@@ -81,20 +98,36 @@ export function memoryIsrStore(options: MemoryIsrStoreOptions = {}): IsrStore {
 }
 
 /**
- * The ISR store key for one request URL: pathname plus the query, **params sorted**.
+ * The reserved query parameter the negotiated locale rides in. A parameter and not a prefix
+ * because `routePathOf` splits a key at its `?`: a `es:/blog` key would match no route, so
+ * `descriptorFor` would answer `undefined` and a declared `revalidate: { ttl }` would silently
+ * become tag-only. Reserved spelling, so an app's own `?locale=` stays its own dimension.
+ */
+export const ISR_LOCALE_PARAM = '__x_locale';
+
+/**
+ * The ISR store key for one request URL: pathname, the negotiated LOCALE, and the query, **params
+ * sorted**.
  *
  * Exported because deriving it is the caller's job and there may only be ONE derivation — a
  * server that keyed on `url.pathname` while the store believed it held a whole URL is the shape
  * of #171. Sorting makes `?a=1&b=2` and `?b=2&a=1` one entry rather than two renders of one page.
  *
+ * The locale is REQUIRED, and required as an argument rather than read from the ambient context so
+ * that every call site has to answer: a document is rendered with `<html lang>` and every `t()` in
+ * the request's own locale, so one entry per path served visitor 2 the document negotiated for
+ * visitor 1 — for the whole TTL, and with `s-maxage` telling the CDN to do the same. The time zone
+ * is deliberately NOT a dimension: it is unbounded where a locale set is declared, and an `isr`
+ * page is a shared artifact, so a date on one belongs in an explicit zone the page itself names.
+ *
  * A query-carrying URL therefore gets its own entry, which is correct and is not free: a crawler
  * appending `?utm_source=…` mints one entry per value. That is bounded, not unbounded —
  * `DEFAULT_ISR_MAX_ENTRIES` evicts least-recently-generated first — and a bounded cache that
  * thrashes is the right failure next to an unbounded one that answers the wrong document.
  */
-export function isrKey(url: URL): string {
-  if (url.search === '') return url.pathname;
+export function isrKey(url: URL, locale: string): string {
   const params = new URLSearchParams(url.search);
+  params.set(ISR_LOCALE_PARAM, locale);
   params.sort();
   return `${url.pathname}?${params.toString()}`;
 }
@@ -213,6 +246,19 @@ export function createIsrController(options: IsrControllerOptions = {}): IsrCont
 
     const descriptor = descriptorFor(path);
     const work = (async (): Promise<IsrEntry> => {
+      // BEFORE the render, not after: `revalidateByTags` reads the graph, so a bust arriving while
+      // a cold path's first render was in flight could not see the page it was invalidating —
+      // which is the window in which the bust that matters most arrives.
+      registerPath(path, descriptor);
+      // Sampled before the render for the reason `@ultimat3/cache`'s read-through fill samples
+      // before its `load()` (`tiers.ts`): the HTML below is built from rows read in the past, and
+      // a `markStale` landing in between was then ERASED by `store.set({ stale: false })`. For a
+      // tag-only route `isFresh` is true forever, so the process went on serving pre-write HTML
+      // for the rest of its life. One mechanism, not a second one grown here.
+      const fence = sampleFence({
+        key: path,
+        tags: (descriptor?.revalidateTags ?? []).map(parseWireTag),
+      });
       const html = await render(path);
       const entry: IsrEntry = {
         path,
@@ -222,8 +268,10 @@ export function createIsrController(options: IsrControllerOptions = {}): IsrCont
         ttlMs: parseTtlMs(descriptor?.revalidateTtl),
         stale: false,
       };
-      store.set(entry);
-      registerPath(path, descriptor);
+      // Refused, never published stale-flagged: the next request re-renders from rows that now
+      // include the write, where a stored-but-stale entry would serve this pre-write body once
+      // more before doing the same thing.
+      if (fence.isValid()) store.set(entry);
       forgetEvictedPaths();
       return entry;
     })();
@@ -234,10 +282,11 @@ export function createIsrController(options: IsrControllerOptions = {}): IsrCont
   }
 
   function markStale(path: string): boolean {
-    const entry = store.get(path);
-    if (entry === undefined) return false;
-    store.set({ ...entry, stale: true });
-    return true;
+    // The mark is recorded whether or not the store holds the page: a regeneration already in
+    // flight for a path this store has never held is exactly the case the fence above exists for,
+    // and `invalidateTags`' own fanout only marks the TAGS.
+    markInvalidated({ key: path });
+    return store.markStale(path);
   }
 
   return {
@@ -362,6 +411,11 @@ function toResult(entry: IsrEntry, buildId: string, servedStale = false): Render
   const headers: Record<string, string> = {
     ...staticHeaders(entry.hash, buildId),
     'cache-control': cacheControl(entry.ttlMs),
+    // The store keys on the locale; a shared cache in front of it has to as well, or the CDN
+    // repeats the bug this entry was split to fix. `ssrHeaders`' own line, for the same reason.
+    // The rest of the shared key — the cookie, the zone — is added by `@ultimat3/http`'s
+    // `cache-headers` stage, which sees the actor this function cannot.
+    vary: 'accept-language',
   };
   if (servedStale) headers['x-ultimate-isr'] = 'stale';
   return { status: 200, headers, body: entry.html };

package/src/server.ts

@@ -43,6 +43,7 @@ export type {
 export {
   createIsrController,
   DEFAULT_ISR_MAX_ENTRIES,
+  ISR_LOCALE_PARAM,
   invalidateAndRevalidate,
   isrKey,
   memoryIsrStore,