@ultimat3/render 10.0.0 → 11.0.0

package/CLAUDE.md

@@ -57,6 +57,7 @@ for the mirror-image reason, keeping `render → pwa` refused. Never `cli` (upwa
 | 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 | **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` 774, `visible` 846, `interaction` 1,067 (`As of 2026-08-23`, the numbers `DEFAULT_ISLAND_JS_BYTES` is derived from). |
@@ -72,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`. |
@@ -81,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

@@ -363,7 +363,7 @@ 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 |
 | `parseByteBudget`, `defaultIslandBudget` | the `'40kb'` budget grammar, and the ceiling a declared island earns |
 | `mergeHead`, `renderHead`, `themeScript` | `<head>` merge + the one inlined script |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/render",
-  "version": "10.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": "10.0.0",
-    "@ultimat3/core": "10.0.0",
-    "@ultimat3/i18n": "10.0.0",
-    "@ultimat3/seo": "10.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/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>`
   );
 }
@@ -169,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.
@@ -176,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,

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,