@ultimat3/render 23.0.0 → 25.0.0

package/src/registry.ts

@@ -1,16 +1,19 @@
 /**
  * The route table — the single source of route truth. File path → URL conventions for
- * `site/`, `app/` and `api/`, plus `describeRoutes()`, the serializable projection that
+ * `site/`, `app/` and `api/`, plus `describePages()`, the serializable projection that
  * `x.manifest.json`, the `/_x` routes panel, the sitemap and `sw.js` are all generated
  * from. Nothing downstream may keep its own list of routes.
  */
 
+import type { CacheTag } from '@ultimat3/cache';
+import { serializeTag, surrogateKeys } from '@ultimat3/cache';
 import type { HydrateStrategy, OfflineStrategy, RenderMode } from '@ultimat3/core';
-import { finiteCount } from '@ultimat3/core';
+import { finiteCount, isUltimateError, renderFixLiteral } from '@ultimat3/core';
 import { byCodeUnit } from './code-unit-order';
 import {
   RouteDuplicateError,
   RouteFileInvalidError,
+  RouteModeInvalidError,
   RouteUnnormalizedError,
   SurfaceBoundaryError,
 } from './errors';
@@ -24,8 +27,10 @@ import {
   setMountedRoutes,
 } from './mounted-routes';
 import type { RouteConfig, RouteData } from './route';
-import { isRouteConfig, tagKeys } from './route';
+import { isRouteConfig, routeTagKeys } from './route';
 import type { RouteComponent } from './route-component';
+import type { CompiledPattern } from './route-pattern';
+import { compilePattern } from './route-pattern';
 import type { Surface } from './surfaces';
 import { locateSurface } from './surfaces';
 
@@ -90,7 +95,6 @@ export interface RouteDescriptor {
    */
   readonly islandSources: readonly string[];
   readonly budgetJs: string | null;
-  readonly budgetLcp: number | null;
   /**
    * Present on a route NO surface file declares: who mounted it and every permission that gates
    * it. Absent on a file route — so a reader never has to ask whether `file` is a path.
@@ -100,14 +104,6 @@ export interface RouteDescriptor {
 
 export type { MountedRouteInput, RouteMount, RouteMountInput } from './mounted-routes';
 
-export interface CompiledPattern {
-  readonly source: string;
-  readonly regex: RegExp;
-  readonly keys: readonly string[];
-  /** Higher wins when two patterns match the same pathname. */
-  readonly specificity: number;
-}
-
 /**
  * `apps/web/site/blog/[slug]/page.tsx` → `{ surface: 'site', path: '/blog/:slug' }`.
  *
@@ -209,36 +205,8 @@ function toUrlSegment(segment: string): string {
   return segment;
 }
 
-export function compilePattern(path: string): CompiledPattern {
-  const keys: string[] = [];
-  let specificity = 0;
-  const segments = path.split('/').filter((s) => s.length > 0);
-
-  const parts = segments.map((segment) => {
-    if (segment.startsWith('*')) {
-      keys.push(segment.slice(1));
-      specificity += 1;
-      return '(.*)';
-    }
-    if (segment.startsWith(':')) {
-      keys.push(segment.slice(1));
-      specificity += 10;
-      return '([^/]+)';
-    }
-    specificity += 100;
-    return segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  });
-
-  return {
-    source: path,
-    regex: new RegExp(`^/${parts.join('/')}/?$`),
-    keys,
-    specificity,
-  };
-}
-
 const routes = new Map<string, RouteEntry>();
-/** The table `describeRoutes()` last built, dropped whenever a route registers or the registry clears. */
+/** The table `describePages()` last built, dropped whenever a route registers or the registry clears. */
 let described: readonly RouteDescriptor[] | undefined;
 
 export interface RegisterRouteInput<TData = RouteData> {
@@ -256,12 +224,33 @@ export interface RegisterRouteInput<TData = RouteData> {
   readonly component?: RouteComponent;
 }
 
+/**
+ * A `revalidate.tags` entry goes out as a purge key on every response of the route
+ * (`render-isr.ts`), so one a CDN would split is refused HERE, naming the file. Asked of
+ * `@ultimat3/cache`'s own screen rather than restated: found at serve time it is a 500 on a
+ * public page, found at purge time it is a document nothing can clear.
+ */
+function assertPurgeableTags(file: string, tags: readonly CacheTag[] | undefined): void {
+  for (const owned of tags ?? []) {
+    try {
+      surrogateKeys([owned], file);
+    } catch (error) {
+      if (!isUltimateError(error) || error.code !== 'X_CACHE_PURGE_FAILED') throw error;
+      const wire = renderFixLiteral(serializeTag(owned), '<the tag>');
+      throw new RouteModeInvalidError(
+        `${file} declares revalidate tag ${wire}, which cannot be a CDN purge key — a key is split on whitespace and commas and capped at 1024 bytes, so every response of the route would carry one no purge can name`,
+        `edit revalidate.tags in ${file}: replace ${wire} with a tag whose entity and id carry no whitespace or comma`,
+      );
+    }
+  }
+}
+
 /** Register a route and enforce every invariant that needs the surrounding module. */
 export function registerRoute<TData = RouteData>(
   input: RegisterRouteInput<TData>,
 ): RouteEntry<TData> {
   // The type already refuses a declaration; this catches the JS caller and the cast. Without it a
-  // raw declaration registers, and `describeRoutes()` is where it surfaces — as a bare TypeError
+  // raw declaration registers, and `describePages()` is where it surfaces — as a bare TypeError
   // on `config.budget.js`, one build step away from the file that caused it.
   if (!isRouteConfig(input.config)) {
     throw new RouteUnnormalizedError(
@@ -292,6 +281,8 @@ export function registerRoute<TData = RouteData>(
     suspenseBoundaries,
   });
 
+  assertPurgeableTags(input.file, config.revalidate?.tags);
+
   const existing = routes.get(path);
   if (existing !== undefined && existing.file !== input.file) {
     throw new RouteDuplicateError(
@@ -359,6 +350,7 @@ export function registerMountedRoutes(
   for (const route of declared) {
     const file = routes.get(route.path)?.file;
     if (file !== undefined) throw mountCollision(route.path, file, mount);
+    assertPurgeableTags(mount.file, route.config.revalidate?.tags);
   }
   setMountedRoutes(mount, declared);
   described = undefined;
@@ -375,7 +367,7 @@ export function routeCount(): number {
 }
 
 export function routeEntries(): readonly RouteEntry[] {
-  // Code units, never `localeCompare` — `describeRoutes()` below promises an order "identical for
+  // Code units, never `localeCompare` — `describePages()` below promises an order "identical for
   // identical input", and `localeCompare` with no locale argument reads the runtime's ICU default.
   return [...routes.values()].sort((a, b) => byCodeUnit(a.path, b.path));
 }
@@ -388,7 +380,7 @@ export function routeFor(path: string): RouteEntry | undefined {
  * The manifest projection: JSON-safe, sorted by path, identical for identical input.
  * Determinism matters because `sw.js` and the sitemap are diffed across deploys.
  */
-export function describeRoutes(): readonly RouteDescriptor[] {
+export function describePages(): readonly RouteDescriptor[] {
   // Built once per registry change and handed out as the SAME frozen array: an ISR regeneration
   // looked its route up through this on every request, re-sorting the whole table each time, and
   // a stable identity is what lets `render-isr.ts` compile its matchers once per table.
@@ -430,7 +422,7 @@ const descriptorOf = (
   mode: config.render,
   offline: config.offline,
   hydrate: config.hydrate,
-  revalidateTags: tagKeys(config.revalidate?.tags),
+  revalidateTags: routeTagKeys(config.revalidate?.tags),
   revalidateTtl: config.revalidate?.ttl ?? null,
   prerenderable: config.prerender !== undefined,
   dynamic: params > 0,
@@ -439,7 +431,6 @@ const descriptorOf = (
   islands: config.islands.map((spec) => spec.moduleId),
   islandSources: config.islands.map((spec) => spec.src),
   budgetJs: config.budget.js ?? null,
-  budgetLcp: config.budget.lcp ?? null,
 });
 
 /** See `RouteDescriptor.personal`. */

package/src/render-html.ts

@@ -4,14 +4,14 @@
  * component — `static` at build time, `ssr`/`stream` per request, all through `renderToHtml`.
  */
 
-import { renderThrowable } from '@ultimat3/core';
+import { escapeHtml, renderFixShellArg, renderThrowable } from '@ultimat3/core';
 import {
   IslandInvalidError,
   IslandNotHydratedError,
   IslandPropsInvalidError,
   PrerenderFailedError,
 } from './errors';
-import { escapeText, renderAttributes, VOID_ELEMENTS } from './html';
+import { renderAttributes, VOID_ELEMENTS } from './html';
 import { emitIslandAttributes, emitIslandProps } from './hydrate';
 import type { IslandNode } from './island';
 import { isIslandNode } from './island';
@@ -62,8 +62,8 @@ export interface RenderHtmlOptions {
 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));
+  if (typeof value === 'string') return escapeHtml(value);
+  if (typeof value === 'number' || typeof value === 'bigint') return escapeHtml(String(value));
   if (value instanceof Promise) return unwrap(await value, depth, walk);
   // Before the array branch, never after: an island node IS an array — the only object shape the
   // configured `JSX.Element` admits — so the generic branch would render its empty contents and
@@ -75,7 +75,7 @@ async function unwrap(value: unknown, depth: number, walk: RenderHtmlOptions): P
   }
   if (isJsxNode(value)) return renderNode(value.type, value.props, depth, walk);
   if (typeof value === 'function') return unwrap((value as () => unknown)(), depth + 1, walk);
-  return escapeText(String(value));
+  return escapeHtml(String(value));
 }
 
 /**
@@ -164,7 +164,9 @@ export async function renderComponent(
       // null-prototype object (`String()` raises) or an Error whose `message` getter does — and
       // this frame is the last thing between that and a build failure with no code at all.
       `rendering the component in ${file} threw: ${renderThrowable(error)}`,
-      `run \`bun test ${file.replace(/\.tsx?$/, '.test.ts')}\` to reproduce, then fix ${file}`,
+      // The route file is author text and `$(…)` is a legal name: screened where it enters the
+      // reproduce command (security audit of plan 101 sweep 1c).
+      `run \`bun test ${renderFixShellArg(file.replace(/\.tsx?$/, '.test.ts'), "'<the route's test file>'")}\` to reproduce, then fix ${file}`,
     );
   }
 }

package/src/render-isr.ts

@@ -13,17 +13,20 @@ import {
   registerDependent,
   registerRevalidator,
   sampleFence,
+  surrogateKeys,
   unregisterDependent,
 } from '@ultimat3/cache';
-import { logger, renderThrowable } from '@ultimat3/core';
+import type { Scheduler } from '@ultimat3/core';
+import { finiteCount, logger, renderThrowable, singleFlight } from '@ultimat3/core';
 import { parseTtlMs } from './duration';
 import { finiteStatus, isRenderStatus } from './finite-status';
 import type { RouteDescriptor } from './registry';
-import { describeRoutes } from './registry';
+import { describePages } from './registry';
 import type { IsrEntry, IsrState, IsrStore } from './render-isr-store';
 import { memoryIsrStore } from './render-isr-store';
 import { contentHash, staticHeaders } from './render-static';
 import type { RenderResult } from './route';
+import { compilePattern } from './route-pattern';
 
 /**
  * The reserved query parameter the negotiated locale rides in. A parameter and not a prefix
@@ -105,8 +108,25 @@ export interface IsrControllerOptions {
   readonly routes?: () => readonly RouteDescriptor[];
   /** ISR-route dependents for a tag set; defaults to `@ultimat3/cache`'s graph. */
   readonly isrDependents?: (tags: readonly CacheTag[]) => readonly string[];
+  /**
+   * How long one regeneration may hold its path, in whole ms (≥ 1). Defaults to
+   * `DEFAULT_ISR_REGENERATE_DEADLINE_MS`. There is no "forever": that is the bug it bounds.
+   */
+  readonly regenerateDeadlineMs?: number | undefined;
+  /** Injected so the deadline is provable without waiting one out. */
+  readonly schedule?: Scheduler | undefined;
 }
 
+/**
+ * The ceiling on one regeneration's hold on its path — `@ultimat3/http`'s default
+ * `requestTimeoutMs`, so the request that started a render has been cut off by then. Without it,
+ * one `render()` that never settled pinned its path for the life of the process: a missed page
+ * hung every later request, a stale one was served stale forever, and only a restart cleared it.
+ * Eviction frees the PATH; the hung render is not cancellable from here, and its late result is
+ * dropped if a newer regeneration has started since (`latest`).
+ */
+export const DEFAULT_ISR_REGENERATE_DEADLINE_MS = 30_000;
+
 export interface IsrController {
   serve(path: string, render: IsrRenderFn): Promise<IsrServeResult>;
   /** Single-flight: concurrent callers for the same path share one render. */
@@ -133,14 +153,29 @@ let installedRevalidator: Revalidator | undefined;
 /** What `registerRevalidator` is handed on detach: the framework's "nothing to revalidate". */
 const NO_REVALIDATION: Revalidator = () => undefined;
 
-export function createIsrController(options: IsrControllerOptions = {}): IsrController {
+export function isrController(options: IsrControllerOptions = {}): IsrController {
   const store = options.store ?? memoryIsrStore();
   const now = options.now ?? (() => Date.now());
-  const routes = options.routes ?? describeRoutes;
+  const routes = options.routes ?? describePages;
   const isrDependents =
     options.isrDependents ?? ((tags: readonly CacheTag[]) => dependentsOfKind(tags, 'isr-route'));
   const buildId = options.buildId ?? 'dev';
-  const pending = new Map<string, Promise<IsrEntry>>();
+  const flight = singleFlight({
+    deadlineMs: finiteCount(
+      'isrController',
+      'regenerateDeadlineMs',
+      options.regenerateDeadlineMs ?? DEFAULT_ISR_REGENERATE_DEADLINE_MS,
+      1,
+    ),
+    schedule: options.schedule,
+  });
+  /**
+   * The newest regeneration STARTED per path, by identity. Once a deadline can evict a flight, two
+   * renders of one path can overlap, and the older one settling last would publish its HTML over
+   * the newer page with a fresh `generatedAt`. Cleared by the run that still owns it; a run that
+   * never settles leaves one entry, replaced by the next regeneration of that path.
+   */
+  const latest = new Map<string, object>();
   const registered = new Set<string>();
 
   function descriptorFor(key: string): RouteDescriptor | undefined {
@@ -149,6 +184,10 @@ export function createIsrController(options: IsrControllerOptions = {}): IsrCont
     return table.find((r) => r.path === path) ?? matchersOf(table).find((m) => m.test(path))?.route;
   }
 
+  /** The route's `revalidate.tags` for a store key — what its document is purged by at the edge. */
+  const tagsOf = (key: string): readonly CacheTag[] =>
+    (descriptorFor(key)?.revalidateTags ?? []).map(parseWireTag);
+
   /**
    * A rendered page joins the invalidation graph under its route's tags, so `/blog/a` and
    * `/blog/b` are separately addressable and a `tag.post` bust does not touch `/team`.
@@ -184,48 +223,53 @@ export function createIsrController(options: IsrControllerOptions = {}): IsrCont
     return now() - entry.generatedAt < ttlMs;
   }
 
+  /** One regeneration of `path`; `led` is told when THIS call started it rather than joined one. */
+  function regenerateOnce(path: string, render: IsrRenderFn, led?: () => void): Promise<IsrEntry> {
+    return flight.run(path, async (): Promise<IsrEntry> => {
+      led?.();
+      const run = {};
+      latest.set(path, run);
+      const descriptor = descriptorFor(path);
+      try {
+        // 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, status } = renderedOf(await render(path));
+        const entry: IsrEntry = {
+          path,
+          html,
+          hash: contentHash(html),
+          generatedAt: now(),
+          ttlMs: parseTtlMs(descriptor?.revalidateTtl),
+          stale: false,
+          // Screened at generation, the one place a status enters the store: a `NaN` written here
+          // would be served for the whole TTL as a `RangeError` on every hit.
+          status: finiteStatus('IsrRenderFn', status),
+        };
+        // 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. Refused too once a newer run started (`latest`).
+        if (fence.isValid() && latest.get(path) === run) store.set(entry);
+        forgetEvictedPaths();
+        return entry;
+      } finally {
+        if (latest.get(path) === run) latest.delete(path);
+      }
+    });
+  }
+
   function regenerate(path: string, render: IsrRenderFn): Promise<IsrEntry> {
-    const existing = pending.get(path);
-    if (existing !== undefined) return existing;
-
-    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, status } = renderedOf(await render(path));
-      const entry: IsrEntry = {
-        path,
-        html,
-        hash: contentHash(html),
-        generatedAt: now(),
-        ttlMs: parseTtlMs(descriptor?.revalidateTtl),
-        stale: false,
-        // Screened at generation, the one place a status enters the store: a `NaN` written here
-        // would be served for the whole TTL as a `RangeError` on every hit.
-        status: finiteStatus('IsrRenderFn', status),
-      };
-      // 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;
-    })();
-
-    pending.set(path, work);
-    void work.catch(() => undefined).finally(() => pending.delete(path));
-    return work;
+    return regenerateOnce(path, render);
   }
 
   function markStale(path: string): boolean {
@@ -238,7 +282,7 @@ export function createIsrController(options: IsrControllerOptions = {}): IsrCont
 
   return {
     store: () => store,
-    inflight: () => pending.size,
+    inflight: () => flight.size,
     regenerate,
     markStale,
 
@@ -247,21 +291,24 @@ export function createIsrController(options: IsrControllerOptions = {}): IsrCont
 
       if (cached === undefined) {
         const entry = await regenerate(path, render);
-        return { state: 'miss', entry, result: toResult(entry, buildId), regenerating: false };
+        const result = toResult(entry, buildId, tagsOf(path));
+        return { state: 'miss', entry, result, regenerating: false };
       }
 
       if (isFresh(cached)) {
         return {
           state: 'hit',
           entry: cached,
-          result: toResult(cached, buildId),
+          result: toResult(cached, buildId, tagsOf(path)),
           regenerating: false,
         };
       }
 
       // stale-while-revalidate: answer from the stale copy now, refresh behind the request.
-      const already = pending.has(path);
-      void regenerate(path, render).catch((error: unknown) => {
+      let started = false;
+      void regenerateOnce(path, render, () => {
+        started = true;
+      }).catch((error: unknown) => {
         // `renderThrowable`, never `.message`/`String()`: this `.catch` is the last frame under a
         // route's own render function, and `String()` raises on a null-prototype object — the
         // handler that exists to REPORT the failure became a second, unhandled rejection.
@@ -270,8 +317,8 @@ export function createIsrController(options: IsrControllerOptions = {}): IsrCont
       return {
         state: 'stale',
         entry: cached,
-        result: toResult(cached, buildId, true),
-        regenerating: !already,
+        result: toResult(cached, buildId, tagsOf(path), true),
+        regenerating: started,
       };
     },
 
@@ -333,30 +380,31 @@ interface RouteMatcher {
   test(storedPath: string): boolean;
 }
 
-/** One compiled set per route TABLE — `describeRoutes()` hands out one array per registry change. */
+/** One compiled set per route TABLE — `describePages()` hands out one array per registry change. */
 const compiledTables = new WeakMap<readonly RouteDescriptor[], readonly RouteMatcher[]>();
 
-/** A stored path belongs to a route when the route's pattern matches it. */
+/**
+ * A stored path belongs to a route when the route's pattern matches it — `route-pattern.ts`'s one
+ * pattern compiler, never a second. Ordered MOST SPECIFIC FIRST, as `@ultimat3/http`'s trie
+ * resolves a request: segment by segment, a static beats a `:param` beats a `*catch-all`. In table
+ * order `/docs/*path` sorts before `/docs/:id`, so the first match gave `/docs/7` the catch-all's
+ * TTL and tags — a page rendered by one route and expired by another's clock.
+ */
 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) };
-  });
+  // Static routes too: `/precios-españa` is the route's path and `/precios-espa%C3%B1a` the key's,
+  // so only the pattern (raw or encoded, per character) finds it.
+  const compiled = table
+    .map((route): RouteMatcher & { readonly specificity: number } => {
+      const { regex, specificity } = compilePattern(route.path);
+      return { route, specificity, test: (stored) => regex.test(stored) };
+    })
+    .sort((a, b) => b.specificity - a.specificity);
   compiledTables.set(table, compiled);
   return compiled;
 }
 
-function segmentPattern(segment: string): string {
-  if (segment.startsWith(':')) return '([^/]+)';
-  if (segment.startsWith('*')) return '(.*)';
-  return segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
 /** Tag-only routes have no clock of their own; a tag bust reaches the CDN through the fanout. */
 const TAG_ONLY_S_MAX_AGE_SECONDS = 60;
 
@@ -402,7 +450,12 @@ function entryStatus(entry: IsrEntry): number {
   return 200;
 }
 
-function toResult(entry: IsrEntry, buildId: string, servedStale = false): RenderResult {
+function toResult(
+  entry: IsrEntry,
+  buildId: string,
+  tags: readonly CacheTag[],
+  servedStale = false,
+): RenderResult {
   const headers: Record<string, string> = {
     ...staticHeaders(entry.hash, buildId),
     'cache-control': cacheControl(entryTtlMs(entry)),
@@ -412,6 +465,15 @@ function toResult(entry: IsrEntry, buildId: string, servedStale = false): Render
     // `cache-headers` stage, which sees the actor this function cannot.
     vary: 'accept-language',
   };
+  // The keys an edge purges this document by — `@ultimat3/cache`'s list, never a second one, so
+  // what a bust sends and what the page carries cannot drift. Absent, an `invalidates` cleared
+  // every tier but the CDN, which held the document for its whole `s-maxage`. The tags were
+  // screened when the route registered (`registry.ts`), so this cannot refuse on the request path.
+  const keys = surrogateKeys(tags, 'isr');
+  if (keys.length > 0) {
+    headers['surrogate-key'] = keys.join(' ');
+    headers['cache-tag'] = keys.join(',');
+  }
   if (servedStale) headers['x-ultimate-isr'] = 'stale';
   return { status: entryStatus(entry), headers, body: entry.html };
 }

package/src/render-ssr.ts

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

package/src/render-static.ts

@@ -4,7 +4,7 @@
  * the precache revision in `sw.js`, and the asset filename suffix.
  */
 
-import { renderThrowable, useContext } from '@ultimat3/core';
+import { BUILD_ID_HEADER, renderCauseValue, renderThrowable, useContext } from '@ultimat3/core';
 import { PrerenderFailedError, RouteModeInvalidError } from './errors';
 import type { RouteEntry } from './registry';
 import type { RenderResult, RouteParams } from './route';
@@ -31,9 +31,11 @@ export type StaticRenderFn = (input: {
  * 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.
+ * bust: every ETag and every scoped CSS class name changed once, in 22.0.0. Bytes hash to what
+ * their UTF-8 string does, so an icon's or an `asset()` file's ETag is this function too — the one
+ * xxHash32 call in the framework (`bun run flight-copies` refuses a second).
  */
-export function contentHash(input: string): string {
+export function contentHash(input: string | Uint8Array): string {
   return Bun.hash.xxHash32(input).toString(16).padStart(8, '0');
 }
 
@@ -86,12 +88,12 @@ export async function enumeratePrerender(entry: RouteEntry): Promise<readonly Ro
   }
 
   const keys = entry.pattern.keys;
-  return produced.map((item) => {
-    if (typeof item !== 'string') return item;
+  return produced.map((item: unknown) => {
+    if (typeof item !== 'string') return paramsOf(entry, item);
     const only = keys[0];
     if (keys.length !== 1 || only === undefined) {
       throw new PrerenderFailedError(
-        `prerender() for ${entry.path} returned the bare string ${JSON.stringify(item)} ` +
+        `prerender() for ${entry.path} returned the bare string ${renderCauseValue(item)} ` +
           `but the route has ${keys.length} dynamic params (${keys.join(', ')})`,
         `return objects from prerender in ${entry.file}, e.g. { ${keys.join(': …, ')}: … }`,
       );
@@ -100,6 +102,18 @@ export async function enumeratePrerender(entry: RouteEntry): Promise<readonly Ro
   });
 }
 
+/**
+ * One `prerender()` item that is not a bare string: a params object, or a coded refusal. A `null`
+ * reached `Object.hasOwn` in `static-path.ts` and left the build as a bare `TypeError`.
+ */
+function paramsOf(entry: RouteEntry, item: unknown): RouteParams {
+  if (typeof item === 'object' && item !== null && !Array.isArray(item)) return item as RouteParams;
+  throw new PrerenderFailedError(
+    `prerender() for ${entry.path} returned ${renderCauseValue(item)} as one of its items, which is neither a params object nor a string`,
+    `return an array of params objects (or strings, for a one-param route) from prerender in ${entry.file}`,
+  );
+}
+
 export interface StaticBuildOptions {
   readonly buildId: string;
   /** Extension-less output files get `/index.html` appended. */
@@ -147,7 +161,7 @@ export function staticHeaders(hash: string, buildId: string): Readonly<Record<st
     // Revalidate cheaply: the HTML URL is stable, its content hash is not.
     'cache-control': 'public, max-age=0, must-revalidate',
     etag: `"${hash}"`,
-    'x-ultimate-build': buildId,
+    [BUILD_ID_HEADER]: buildId,
   };
 }