@ultimat3/render 20.2.1 → 22.0.0

package/src/hydrate.ts

@@ -135,9 +135,14 @@ function hush(){}
 // `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.
 
+// `idle` hydrates on the browser's schedule, not the visitor's, so its server-rendered controls
+// are pressable for the idle wait plus the chunk's download — up to IDLE_HYDRATE_TIMEOUT_MS and
+// more. A press in that window reached a node with no handler and was lost, which is every app's
+// first click. It catches up exactly as `interaction` does, through the one `catchUp` below; the
+// only difference left between the two is that `idle` also boots when the browser goes idle.
 const RUNTIME_IDLE = `
 each('[data-x-hydrate="idle"]',function(el){
-var go=function(){boot(el).catch(hush)};
+var go=catchUp(el);
 if('requestIdleCallback'in window)requestIdleCallback(go,{timeout:${IDLE_HYDRATE_TIMEOUT_MS}});else setTimeout(go,1)})
 `.trim();
 
@@ -171,7 +176,16 @@ io.observe(el)})
 // root is never visited. The root is the last resort, not the repair: it is where an event with no
 // coordinates goes (a `keydown` has no `clientX`), and where a hit landing outside this island goes
 // — synthesizing a click on an element the visitor never pressed is worse than losing the replay.
-// `typeof` and not `ev.clientX||ev.clientY`, because (0, 0) is a coordinate.
+// `typeof` and not `ev.clientX||ev.clientY`, because (0, 0) is a coordinate — but not when
+// `ev.detail` is 0: a keyboard-activated or scripted `click()` fires at (0, 0) and names no point,
+// so hit-testing the page's corner found nothing of the island and the press went to the root.
+//
+// Between the hit test and the root sits the STRUCTURAL answer: `path` records, when the event is
+// caught, the child-element indices from the root to the target plus the target's tag, and `aim`
+// walks the same indices in the mounted tree. Same tag at the same place is the island's own render
+// of the control that was pressed — which is what a keyboard press, a `keydown`, and a hit landing
+// on a sticky header all lack otherwise. A different tag there is a different control and falls
+// through to the root, for the stranger rule above.
 //
 // `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
@@ -181,18 +195,32 @@ io.observe(el)})
 // 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 = `
-function aim(el,ev){var t=ev.target;if(t&&el.contains(t))return t;
-var x=ev.clientX,h=typeof x==='number'?document.elementFromPoint(x,ev.clientY):null;
-return h&&el.contains(h)?h:el}
-each('[data-x-hydrate="interaction"]',function(el){
-var evs=(el.getAttribute('data-x-events')||'click').split(' ');
+//
+// `catchUp(el)` attaches the capture listeners and answers `go`, the one boot-then-flush both
+// strategies call: a caught event calls it, and `idle` calls it again from its idle callback. Every
+// `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.
+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));
+return t===el?p:null}
+function aim(el,ev,p){var t=ev.target;if(t&&el.contains(t))return t;
+var x=ev.clientX,h=typeof x==='number'&&ev.detail!==0?document.elementFromPoint(x,ev.clientY):null;
+if(h&&el.contains(h))return h;
+for(var n=el,i=0;p&&n&&i<p.length-1;i++)n=n.children[p[i]];
+return p&&n&&n.tagName===p[p.length-1]?n:el}
+function catchUp(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(){var r=q;off();
-r.forEach(function(ev){var c=new ev.constructor(ev.type,ev);aim(el,ev).dispatchEvent(c)})},off)};
-evs.forEach(function(n){el.addEventListener(n,on,true)})})
+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()};
+evs.forEach(function(n){el.addEventListener(n,on,true)});return go}
+`.trim();
+
+const RUNTIME_INTERACTION = `
+each('[data-x-hydrate="interaction"]',catchUp)
 `.trim();
 
 const RUNTIME_PARTS: Readonly<Record<Exclude<HydrateStrategy, 'never'>, string>> = {
@@ -220,6 +248,9 @@ const RUNTIME_ORDER: readonly Exclude<HydrateStrategy, 'never'>[] = HYDRATE_STRA
 const runtimeBody = (needed: ReadonlySet<Exclude<HydrateStrategy, 'never'>>): string =>
   [
     RUNTIME_PRELUDE,
+    // 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] : []),
     ...RUNTIME_ORDER.filter((strategy) => needed.has(strategy)).map(
       (strategy) => RUNTIME_PARTS[strategy],
     ),

package/src/index.ts

@@ -16,6 +16,23 @@ export type { HydrateStrategy, OfflineStrategy, RenderMode } from '@ultimat3/cor
 // 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';
+/** The `<meta name="ultimate-scope">` core's `pageClient()` reads, on private documents only. */
+export {
+  CLIENT_PERSIST_META,
+  CLIENT_SCOPE_META,
+  clientPersistTags,
+  clientScopeTag,
+  documentCarriesScope,
+} from './client-scope-tag';
+/** 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';
 export { parseTtlMs } from './duration';
 export type { RenderErrorCode } from './errors';
 export {
@@ -50,15 +67,13 @@ export {
   headFromMeta,
   mergeHead,
   renderHead,
-  THEME_SCRIPT_MAX_BYTES,
   THEME_STORAGE_KEY,
   themeScript,
   themeScriptBody,
 } from './head';
-export { headTagKey, seoRenderers, toHeadTag } from './head-seo';
+export { seoRenderers } from './head-seo';
 export type { IslandDirective } from './hydrate';
 export {
-  DEFAULT_REPLAY_EVENTS,
   emitIslandAttributes,
   emitIslandProps,
   HYDRATE_RUNTIME_BODIES,
@@ -67,13 +82,10 @@ export {
   IDLE_HYDRATE_TIMEOUT_MS,
   ISLAND_FAILED_ATTRIBUTE,
   ISLAND_MOUNTED_ATTRIBUTE,
-  requiredStrategies,
 } from './hydrate';
 export type { IslandComponent, IslandDeclaration, IslandNode, IslandSpec } from './island';
 export {
   ISLAND_EXTENSION,
-  ISLAND_NODE,
-  isEmittableSpecifier,
   isIslandNode,
   island,
   islandModuleId,
@@ -81,7 +93,7 @@ export {
 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 { ISLAND_PROPS_MAX_BYTES } from './island-props';
 export { parseByteBudget } from './islands';
 export type { JsxComponent, JsxNode, JsxProps } from './jsx';
 export { Fragment, h, isJsxNode, JSX_NODE } from './jsx';
@@ -106,7 +118,6 @@ export {
   describeRoutes,
   ROUTE_FILENAME,
   registerRoute,
-  routeCount,
   routeEntries,
   routeFor,
   routePathFromFile,
@@ -133,7 +144,8 @@ export { DEFAULT_ISLAND_HYDRATE, defineRoute, isRouteConfig, tagKeys } from './r
 export type { RouteComponent } from './route-component';
 export { pageComponentOf } from './route-component';
 export { metaContextFor, routeDataFor } from './route-data';
-export { DEFAULT_ROUTE_STATUS, isErrorStatus, routeStatusOf, withStatus } from './route-status';
+export { routeStatusOf, withStatus } from './route-status';
+export { STREAM_REVEAL_BODIES } from './stream-scripts';
 export type {
   BoundaryRule,
   BoundaryViolation,

package/src/modes.ts

@@ -225,14 +225,13 @@ 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,251 (`hydrateRuntimeBytes`
- * for one directive at `DEFAULT_ISLAND_HYDRATE`, which is `'interaction'` — `route.ts:33`, applied
- * at `:253` to any island route declaring no `hydrate`) = **19,048**. 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,432 B of headroom and still
- * under 2x 19,048, 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.
+ * The number: 17,797 (the heaviest island this repo actually ships) + 1,744 (`hydrateRuntimeBytes`
+ * for one `idle` directive — `defaultHydrate('app')`, and since 2026-09-22 the costlier of the two
+ * runtimes an island gets unasked; `DEFAULT_ISLAND_HYDRATE`'s `'interaction'` is 1,629) =
+ * **19,541**. That is the worst case an app reaches without writing a number down. 20,480 is the
+ * next whole kilobyte above it, leaving 939 B of headroom and still under 2x 19,541, so a route
+ * bundling the same island twice is refused. `island-budget.test.ts` asserts all three. `visible` costs 846, so an island route
+ * that declares it 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, and
@@ -240,8 +239,10 @@ export function defaultHydrate(surface: Surface): HydrateStrategy {
  * `interaction` — when each runtime learned to TERMINATE the promise chain `boot` starts rather
  * than emit one unhandled rejection per user event. `interaction` alone grew a third time on
  * 2026-08-25 (+184 B, `aim`), when the replay learned that the node it was dispatching at had been
- * detached by the mount it was waiting for. The headroom absorbed all three and the conclusion is
- * unchanged, which is the point of stating the
+ * detached by the mount it was waiting for. On 2026-09-22 `idle` learned the same replay through a
+ * shared `catchUp`, and both learned to aim a keyboard press by the pressed node's path (774 -> 1,744;
+ * `interaction` 1,251 -> 1,629), and `idle` became the worst case. The
+ * headroom absorbed all four 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/module-loader.ts

@@ -152,6 +152,9 @@ export function transformTsx(source: string): string {
  */
 export function loadStylesheet(path: string, source: string): string {
   const compiled = compileStylesheet(path, source);
+  // An EMPTY compile unregisters: under `x dev` an edit that deleted every rule left the old entry
+  // in place, serving rules the file no longer had until the process restarted.
+  if (compiled.css.length === 0 && stylesheets.delete(path)) revision += 1;
   if (compiled.css.length > 0) {
     if (stylesheets.get(path)?.css !== compiled.css) revision += 1;
     stylesheets.set(path, {

package/src/registry.ts

@@ -211,6 +211,8 @@ export function compilePattern(path: string): CompiledPattern {
 }
 
 const routes = new Map<string, RouteEntry>();
+/** The table `describeRoutes()` last built, dropped whenever a route registers or the registry clears. */
+let described: readonly RouteDescriptor[] | undefined;
 
 export interface RegisterRouteInput<TData = RouteData> {
   readonly file: string;
@@ -290,6 +292,7 @@ export function registerRoute<TData = RouteData>(
     ...(input.component === undefined ? {} : { component: input.component }),
   };
   routes.set(path, entry as RouteEntry);
+  described = undefined;
   return entry;
 }
 
@@ -316,6 +319,7 @@ function withIslandBudget<TData>(config: RouteConfig<TData>, surface: Surface):
 
 export function clearRoutes(): void {
   routes.clear();
+  described = undefined;
 }
 
 export function routeCount(): number {
@@ -337,6 +341,14 @@ export function routeFor(path: string): RouteEntry | undefined {
  * Determinism matters because `sw.js` and the sitemap are diffed across deploys.
  */
 export function describeRoutes(): 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.
+  described ??= Object.freeze(buildDescriptors());
+  return described;
+}
+
+function buildDescriptors(): RouteDescriptor[] {
   return routeEntries().map((entry) => ({
     path: entry.path,
     file: entry.file,

package/src/render-isr-store.ts

@@ -0,0 +1,93 @@
+/**
+ * The ISR store: what an entry is, the driver seam an app may back with its own storage, and the
+ * bounded in-memory default. Split from `render-isr.ts`, which is the controller that reads it.
+ */
+
+import { finiteCount } from '@ultimat3/core';
+
+export type IsrState = 'miss' | 'hit' | 'stale';
+
+export interface IsrEntry {
+  /**
+   * The store key: the request's pathname AND its query, params sorted. Not the route's pattern
+   * and not the bare pathname — `/blog?page=2` and `/blog?page=3` render different documents, and
+   * keying both as `/blog` served the second visitor the first one's HTML (#171).
+   */
+  readonly path: string;
+  readonly html: string;
+  readonly hash: string;
+  readonly generatedAt: number;
+  readonly ttlMs: number | null;
+  /** Set by a tag invalidation; independent of the TTL clock. */
+  readonly stale: boolean;
+  /**
+   * What the page answers, 200–599. Optional because an entry can come back from an app's own
+   * store, written before this field existed or JSON-round-tripped without it; absent reads as
+   * 200, the only status an entry ever had until `withStatus`.
+   */
+  readonly status?: number;
+}
+
+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[];
+}
+
+/**
+ * How many rendered pages the default store holds. A route table supports `:params` and `*`, so
+ `/blog/:slug` has as many ISR paths as the blog has slugs — 404-shaped ones that still render
+ * included. Unbounded, a crawler over 100k slugs is 100k HTML strings resident for the life of
+ * the process.
+ */
+export const DEFAULT_ISR_MAX_ENTRIES = 1_000;
+
+export interface MemoryIsrStoreOptions {
+  /** Pages retained. The least recently generated goes first. */
+  readonly maxEntries?: number;
+}
+
+export function memoryIsrStore(options: MemoryIsrStoreOptions = {}): IsrStore {
+  // `map.size > NaN` is false for every size, so a cap that arrived non-finite is not a bigger
+  // cap — it is no cap, and this store is the one thing bounding a crawler over 100k slugs.
+  const maxEntries = finiteCount(
+    'memoryIsrStore',
+    'maxEntries',
+    options.maxEntries ?? DEFAULT_ISR_MAX_ENTRIES,
+  );
+  const map = new Map<string, IsrEntry>();
+  return {
+    get: (path) => map.get(path),
+    set: (entry) => {
+      // Re-inserted rather than overwritten, so the Map's iteration order IS generation order and
+      // the first key is the least recently generated page.
+      map.delete(entry.path);
+      map.set(entry.path, entry);
+      while (map.size > maxEntries) {
+        const oldest = map.keys().next();
+        if (oldest.done === true) break;
+        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);
+    },
+    paths: () => [...map.keys()].sort(),
+  };
+}

package/src/render-isr.ts

@@ -15,101 +15,16 @@ import {
   sampleFence,
   unregisterDependent,
 } from '@ultimat3/cache';
-import { finiteCount, logger, renderThrowable } from '@ultimat3/core';
+import { logger, renderThrowable } from '@ultimat3/core';
 import { parseTtlMs } from './duration';
 import { finiteStatus, isRenderStatus } from './finite-status';
 import type { RouteDescriptor } from './registry';
 import { describeRoutes } from './registry';
+import type { IsrEntry, IsrState, IsrStore } from './render-isr-store';
+import { memoryIsrStore } from './render-isr-store';
 import { contentHash, staticHeaders } from './render-static';
 import type { RenderResult } from './route';
 
-export type IsrState = 'miss' | 'hit' | 'stale';
-
-export interface IsrEntry {
-  /**
-   * The store key: the request's pathname AND its query, params sorted. Not the route's pattern
-   * and not the bare pathname — `/blog?page=2` and `/blog?page=3` render different documents, and
-   * keying both as `/blog` served the second visitor the first one's HTML (#171).
-   */
-  readonly path: string;
-  readonly html: string;
-  readonly hash: string;
-  readonly generatedAt: number;
-  readonly ttlMs: number | null;
-  /** Set by a tag invalidation; independent of the TTL clock. */
-  readonly stale: boolean;
-  /**
-   * What the page answers, 200–599. Optional because an entry can come back from an app's own
-   * store, written before this field existed or JSON-round-tripped without it; absent reads as
-   * 200, the only status an entry ever had until `withStatus`.
-   */
-  readonly status?: number;
-}
-
-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[];
-}
-
-/**
- * How many rendered pages the default store holds. A route table supports `:params` and `*`, so
- `/blog/:slug` has as many ISR paths as the blog has slugs — 404-shaped ones that still render
- * included. Unbounded, a crawler over 100k slugs is 100k HTML strings resident for the life of
- * the process.
- */
-export const DEFAULT_ISR_MAX_ENTRIES = 1_000;
-
-export interface MemoryIsrStoreOptions {
-  /** Pages retained. The least recently generated goes first. */
-  readonly maxEntries?: number;
-}
-
-export function memoryIsrStore(options: MemoryIsrStoreOptions = {}): IsrStore {
-  // `map.size > NaN` is false for every size, so a cap that arrived non-finite is not a bigger
-  // cap — it is no cap, and this store is the one thing bounding a crawler over 100k slugs.
-  const maxEntries = finiteCount(
-    'memoryIsrStore',
-    'maxEntries',
-    options.maxEntries ?? DEFAULT_ISR_MAX_ENTRIES,
-  );
-  const map = new Map<string, IsrEntry>();
-  return {
-    get: (path) => map.get(path),
-    set: (entry) => {
-      // Re-inserted rather than overwritten, so the Map's iteration order IS generation order and
-      // the first key is the least recently generated page.
-      map.delete(entry.path);
-      map.set(entry.path, entry);
-      while (map.size > maxEntries) {
-        const oldest = map.keys().next();
-        if (oldest.done === true) break;
-        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);
-    },
-    paths: () => [...map.keys()].sort(),
-  };
-}
-
 /**
  * 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
@@ -231,7 +146,7 @@ export function createIsrController(options: IsrControllerOptions = {}): IsrCont
   function descriptorFor(key: string): RouteDescriptor | undefined {
     const path = routePathOf(key);
     const table = routes();
-    return table.find((r) => r.path === path) ?? table.find((r) => matchesRoute(path, r.path));
+    return table.find((r) => r.path === path) ?? matchersOf(table).find((m) => m.test(path))?.route;
   }
 
   /**
@@ -413,11 +328,27 @@ function parseWireTag(wire: string): CacheTag {
   return { entity: wire.slice(0, split), id: wire.slice(split + 1) };
 }
 
+interface RouteMatcher {
+  readonly route: RouteDescriptor;
+  test(storedPath: string): boolean;
+}
+
+/** One compiled set per route TABLE — `describeRoutes()` hands out one array per registry change. */
+const compiledTables = new WeakMap<readonly RouteDescriptor[], readonly RouteMatcher[]>();
+
 /** A stored path belongs to a route when the route's pattern matches it. */
-function matchesRoute(storedPath: string, routePath: string): boolean {
-  if (!routePath.includes(':') && !routePath.includes('*')) return storedPath === routePath;
-  const parts = routePath.split('/').map(segmentPattern);
-  return new RegExp(`^${parts.join('/')}/?$`).test(storedPath);
+function matchersOf(table: readonly RouteDescriptor[]): readonly RouteMatcher[] {
+  const cached = compiledTables.get(table);
+  if (cached !== undefined) return cached;
+  const compiled = table.map((route): RouteMatcher => {
+    if (!route.path.includes(':') && !route.path.includes('*')) {
+      return { route, test: (storedPath) => storedPath === route.path };
+    }
+    const pattern = new RegExp(`^${route.path.split('/').map(segmentPattern).join('/')}/?$`);
+    return { route, test: (storedPath) => pattern.test(storedPath) };
+  });
+  compiledTables.set(table, compiled);
+  return compiled;
 }
 
 function segmentPattern(segment: string): string {

package/src/render-static.ts

@@ -8,12 +8,13 @@ import { renderThrowable, useContext } from '@ultimat3/core';
 import { PrerenderFailedError, RouteModeInvalidError } from './errors';
 import type { RouteEntry } from './registry';
 import type { RenderResult, RouteParams } from './route';
+import { filePathOf, filledSegments, urlPathOf } from './static-path';
 
 export interface StaticArtifact {
   readonly path: string;
   readonly params: RouteParams;
   readonly html: string;
-  /** FNV-1a of the HTML. Stable across machines and across Bun versions. */
+  /** `contentHash` (xxHash32) of the HTML. Stable across machines and across Bun versions. */
   readonly hash: string;
   /** Where the file lands on disk, relative to the build output root. */
   readonly outputPath: string;
@@ -25,14 +26,15 @@ export type StaticRenderFn = (input: {
   readonly params: RouteParams;
 }) => string | Promise<string>;
 
-/** Deterministic, dependency-free 32-bit FNV-1a, hex. */
+/**
+ * xxHash32 (seed 0) of the UTF-8 bytes, 8 hex characters. Native: FNV-1a in JS measured 134 µs on a
+ * 96 kB document against 21 µs here, and every static page, ISR regeneration and CSS module hashes
+ * through it. xxHash32 is a SPECIFIED algorithm — the test pins its reference vectors — so the value
+ * is stable across machines and Bun versions, as the FNV one was. Switching was a one-time cache
+ * bust: every ETag and every scoped CSS class name changed once, in 22.0.0.
+ */
 export function contentHash(input: string): string {
-  let hash = 0x811c9dc5;
-  for (let i = 0; i < input.length; i += 1) {
-    hash ^= input.charCodeAt(i);
-    hash = Math.imul(hash, 0x01000193) >>> 0;
-  }
-  return hash.toString(16).padStart(8, '0');
+  return Bun.hash.xxHash32(input).toString(16).padStart(8, '0');
 }
 
 /**
@@ -115,7 +117,8 @@ export async function renderStatic(
 
   const artifacts: StaticArtifact[] = [];
   for (const params of paramSets) {
-    const path = fillPath(entry.pattern.source, params);
+    const segments = filledSegments(entry.pattern.source, params);
+    const path = urlPathOf(segments);
     let html: string;
     try {
       html = await render({ path, params });
@@ -131,7 +134,7 @@ export async function renderStatic(
       params,
       html,
       hash,
-      outputPath: `${path === '/' ? '' : path}/${indexFile}`.replace(/^\/+/, ''),
+      outputPath: filePathOf(segments, indexFile),
       headers: staticHeaders(hash, options.buildId),
     });
   }
@@ -152,17 +155,11 @@ export function staticResult(artifact: StaticArtifact): RenderResult {
   return { status: 200, headers: artifact.headers, body: artifact.html };
 }
 
-/** `/blog/:slug` + `{ slug: 'hello' }` → `/blog/hello`. */
+/**
+ * `/blog/:slug` + `{ slug: 'hello' }` → `/blog/hello`, each segment percent-encoded. A missing
+ * param, a dot segment, a separator inside a `:param`, NUL, `?` and `#` are `X_PRERENDER_FAILED`
+ * (`static-path.ts`) — they wrote a `:slug` directory, or a file outside the build output.
+ */
 export function fillPath(pattern: string, params: RouteParams): string {
-  return (
-    pattern
-      .split('/')
-      .map((segment) => {
-        if (segment.startsWith(':')) return params[segment.slice(1)] ?? segment;
-        if (segment.startsWith('*')) return params[segment.slice(1)] ?? '';
-        return segment;
-      })
-      .join('/')
-      .replace(/\/+$/, '') || '/'
-  );
+  return urlPathOf(filledSegments(pattern, params));
 }

package/src/render-stream.ts

@@ -13,8 +13,9 @@
 
 import { finiteCount, logger, renderThrowable } from '@ultimat3/core';
 import { finiteStatus } from './finite-status';
-import { escapeAttribute, escapeRawTextContent } from './html';
+import { escapeAttribute } from './html';
 import type { RenderResult } from './route';
+import { REVEAL_BODY, REVEAL_CALL } from './stream-scripts';
 
 export interface StreamHole {
   /** Stable within a response; becomes the DOM id, so keep it short. */
@@ -60,20 +61,14 @@ export function holeMarker(id: string, fallback: string): string {
  * The entire client half of out-of-order streaming. Inline, uncompressed, ~200 bytes; it
  * moves a late `<template>`'s content into the placeholder that is already on screen.
  */
-export const REVEAL_SCRIPT =
-  "<script>window.$X=function(i){var t=document.querySelector('template[data-x-hole=\"'+i+'\"]')," +
-  's=document.getElementById(i);if(t&&s){s.replaceWith(t.content);t.remove()}}</script>';
+export const REVEAL_SCRIPT = `<script>${REVEAL_BODY}</script>`;
 
 export function revealChunk(id: string, html: string): string {
-  const key = holeId(id);
-  // Two contexts, two encoders — the attribute takes `escapeAttribute`, and the script argument is
-  // built by `JSON.stringify` so the id is a JS string LITERAL rather than text pasted between two
-  // quotes: `a");alert(1);//` closed the call and ran on the page's own origin. `</script` inside
-  // it would still end the element, so the raw-text rule applies over the top, as `html.ts` says.
-  const argument = escapeRawTextContent(JSON.stringify(key));
+  // The id reaches markup ONLY through `escapeAttribute` — never a script — so a quote in it
+  // cannot close anything, and no per-hole body exists for a CSP to fail to list.
   return (
-    `<template data-x-hole="${escapeAttribute(key)}">${html}</template>` +
-    `<script>$X(${argument})</script>`
+    `<template data-x-hole="${escapeAttribute(holeId(id))}">${html}</template>` +
+    `<script>${REVEAL_CALL}</script>`
   );
 }
 
@@ -186,7 +181,7 @@ export function renderStreamHtml(
           timeoutMs === null
             ? undefined
             : setTimeout(() => {
-                logger.warn(`stream hole ${hole.id} missed its ${timeoutMs}ms deadline`);
+                logger.warn('render.stream.hole_deadline', { hole: hole.id, timeoutMs });
                 reveal(errorFallback(hole.id));
               }, timeoutMs);
         // A response nobody is reading must not hold the process open until its deadline.
@@ -200,7 +195,12 @@ export function renderStreamHtml(
             // `renderThrowable`, never `.message`/`String()`: the value is whatever the hole threw,
             // and a read that raises here skips the `reveal` below — the hole never fills and the
             // response is held to its deadline for a failure that was already handled.
-            logger.warn(`stream hole ${hole.id} rejected: ${renderThrowable(error)}`);
+            // A FIELD, never the message: `logger` redacts fields and never `msg`, so a hole's
+            // failure text interpolated into the message reached the log past every redactor.
+            logger.warn('render.stream.hole_rejected', {
+              hole: hole.id,
+              error: renderThrowable(error),
+            });
             reveal(errorFallback(hole.id));
           },
         );