@ultimat3/render 22.15.0 → 24.0.0

package/src/render-isr.ts

@@ -13,9 +13,11 @@ import {
   registerDependent,
   registerRevalidator,
   sampleFence,
+  surrogateKeys,
   unregisterDependent,
 } from '@ultimat3/cache';
-import { logger, renderThrowable } from '@ultimat3/core';
+import type { Scheduler } from '@ultimat3/core';
+import { createSingleFlight, finiteCount, logger, renderThrowable } from '@ultimat3/core';
 import { parseTtlMs } from './duration';
 import { finiteStatus, isRenderStatus } from './finite-status';
 import type { RouteDescriptor } from './registry';
@@ -24,6 +26,7 @@ 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. */
@@ -140,7 +160,22 @@ export function createIsrController(options: IsrControllerOptions = {}): IsrCont
   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 = createSingleFlight({
+    deadlineMs: finiteCount(
+      'createIsrController',
+      '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,
       };
     },
 
@@ -336,27 +383,28 @@ interface RouteMatcher {
 /** 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. */
+/**
+ * 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-static.ts

@@ -4,7 +4,7 @@
  * the precache revision in `sw.js`, and the asset filename suffix.
  */
 
-import { renderThrowable, useContext } from '@ultimat3/core';
+import { 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. */

package/src/render-stream.ts

@@ -13,7 +13,7 @@
 
 import { finiteCount, logger, renderThrowable } from '@ultimat3/core';
 import { finiteStatus } from './finite-status';
-import { escapeAttribute } from './html';
+import { escapeHtml } from './html';
 import type { RenderResult } from './route';
 import { REVEAL_BODY, REVEAL_CALL } from './stream-scripts';
 
@@ -54,7 +54,7 @@ export function holeId(id: string): string {
  * from a param. `fallback` is already-rendered HTML and stays verbatim.
  */
 export function holeMarker(id: string, fallback: string): string {
-  return `<x-hole id="${escapeAttribute(holeId(id))}">${fallback}</x-hole>`;
+  return `<x-hole id="${escapeHtml(holeId(id))}">${fallback}</x-hole>`;
 }
 
 /**
@@ -64,10 +64,10 @@ export function holeMarker(id: string, fallback: string): string {
 export const REVEAL_SCRIPT = `<script>${REVEAL_BODY}</script>`;
 
 export function revealChunk(id: string, html: string): string {
-  // The id reaches markup ONLY through `escapeAttribute` — never a script — so a quote in it
+  // The id reaches markup ONLY through `escapeHtml` — 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(holeId(id))}">${html}</template>` +
+    `<template data-x-hole="${escapeHtml(holeId(id))}">${html}</template>` +
     `<script>${REVEAL_CALL}</script>`
   );
 }
@@ -117,7 +117,8 @@ export function renderStreamHtml(
   const encoder = new TextEncoder();
   const tail = plan.tail ?? '</body></html>';
   const errorFallback =
-    options.errorFallback ?? ((id) => `<div data-x-hole-error="${id}" hidden></div>`);
+    // Escaped as `holeMarker` escapes the same id: it lands inside an attribute either way.
+    options.errorFallback ?? ((id) => `<div data-x-hole-error="${escapeHtml(id)}" hidden></div>`);
   // A deadline is the bound a non-finite value does not disable but MOVES: `setTimeout(fn, NaN)`
   // is `setTimeout(fn, 0)`, so every hole would miss a deadline nobody set and the document would
   // be all fallbacks. `null` is the declared opt-out; there is no spelling that means "immediately".

package/src/route-pattern.ts

@@ -0,0 +1,67 @@
+/**
+ * A route pattern (`/docs/:id`, `/docs/*path`) as the regex a pathname is tested with, and the
+ * order two matching patterns are ranked in. Split from `registry.ts`, which registers routes; this
+ * file only reads a pattern string.
+ */
+
+import { routeRank } from '@ultimat3/core';
+
+export interface CompiledPattern {
+  readonly source: string;
+  readonly regex: RegExp;
+  readonly keys: readonly string[];
+  /**
+   * Higher wins when two patterns match the same pathname — `@ultimat3/core`'s `routeRank`, the
+   * ONE ordering rule: ISR, the sitemap, the admin and `@ultimat3/pwa`'s worker all sort on it.
+   */
+  readonly specificity: number;
+}
+
+/** A regex metacharacter, matched as itself. */
+const escapeRegex = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * A literal segment as a pathname may spell it: each character raw OR percent-encoded, either hex
+ * case. A route file is named in Unicode (`precios-españa`) and `URL.pathname` encodes it
+ * (`precios-espa%C3%B1a`), so a literal-only pattern never matched the key it was asked about.
+ */
+function literalPattern(segment: string): string {
+  let out = '';
+  for (const char of segment) {
+    const encoded = [...new TextEncoder().encode(char)]
+      .map((byte) => {
+        const hex = byte.toString(16).toUpperCase().padStart(2, '0');
+        const digit = (d: string): string => (/[A-F]/.test(d) ? `[${d}${d.toLowerCase()}]` : d);
+        return `%${digit(hex[0] ?? '0')}${digit(hex[1] ?? '0')}`;
+      })
+      .join('');
+    out += `(?:${escapeRegex(char)}|${encoded})`;
+  }
+  return out;
+}
+
+export function compilePattern(path: string): CompiledPattern {
+  const keys: string[] = [];
+  const segments = path.split('/').filter((s) => s.length > 0);
+
+  // Each part carries its own leading `/`, so a catch-all can own its separator: an empty rest is
+  // the bare prefix (`/docs`), which is the path `static-path.ts` writes for it.
+  const parts = segments.map((segment) => {
+    if (segment.startsWith('*')) {
+      keys.push(segment.slice(1));
+      return '(?:/(.*))?';
+    }
+    if (segment.startsWith(':')) {
+      keys.push(segment.slice(1));
+      return '/([^/]+)';
+    }
+    return `/${literalPattern(segment)}`;
+  });
+
+  return {
+    source: path,
+    regex: new RegExp(`^${parts.join('')}/?$`),
+    keys,
+    specificity: routeRank(path),
+  };
+}

package/src/route.ts

@@ -51,17 +51,15 @@ export interface RevalidateConfig {
 }
 
 /**
- * What a route promises to stay under. **Two keys, and every one of them is PROJECTED** — a key
- * here that `RouteDescriptor` does not carry is a number an author writes and nothing can ever
- * compare against, which `type-pins.tsx` now makes a build error.
+ * What a route promises to stay under. **One key, and it is MEASURED** — a key here that nothing
+ * weighs is a number an author writes and nothing can ever compare against. `type-pins.tsx` makes
+ * an unprojected key a build error, and `assertModeInvariants` refuses one that arrives anyway.
  *
- * `css`, `cls` and `tbt` were three such keys and are gone in 12.0.0. `registerRoute` flattens a
- * budget to `budgetJs` + `budgetLcp`, and every reader downstream — `x verify`'s `budgets` step,
- * `x.manifest.json`, `x routes`, the dev dashboard — reads only those two, so `budget: { cls: 0.1 }`
- * was accepted, normalised, stored and ignored while the gate that exists to enforce budgets
- * reported green. Deleted rather than wired for `PwaConfig.installPrompt`'s reason: the measuring
- * half does not exist either, and a knob that fails silently in the permissive direction is the
- * framework's most repeated defect.
+ * `css`, `cls` and `tbt` went in 12.0.0 and `lcp` after them: each was accepted, stored and
+ * ignored while the gate that exists to enforce budgets reported green, because nothing in the
+ * framework observes a paint — the build emits static HTML. Deleted rather than wired for
+ * `PwaConfig.installPrompt`'s reason: the measuring half does not exist, and a knob that fails
+ * silently in the permissive direction is the framework's most repeated defect.
  */
 export interface RouteBudget {
   /**
@@ -72,12 +70,6 @@ export interface RouteBudget {
    * `As of 2026-09-05`; `packages/cli/src/budgets.ts`'s `measureDocumentJs` is the one reader.
    */
   readonly js?: string;
-  /**
-   * Milliseconds. PUBLISHED, not enforced: it reaches `x.manifest.json` and `x routes`, and no
-   * step of the gate compares it — nothing in the framework produces an `lcp` measurement, which
-   * `packages/cli/src/templates/route.ts` states at the one place an author would write one.
-   */
-  readonly lcp?: number;
 }
 
 /**
@@ -299,7 +291,7 @@ export function defineRoute<TData = RouteData>(
   }
   if (!OFFLINE_STRATEGIES.includes(def.offline)) {
     throw new RouteOfflineMissingError(
-      `offline: ${JSON.stringify(def.offline)} is not a known strategy`,
+      `offline: ${renderCauseValue(def.offline)} is not a known strategy`,
       `use one of ${OFFLINE_STRATEGIES.join(' | ')}`,
     );
   }
@@ -312,7 +304,7 @@ export function defineRoute<TData = RouteData>(
 
   if (def.load !== undefined && typeof def.load !== 'function') {
     throw new RouteLoadInvalidError(
-      `load: ${JSON.stringify(def.load)} is not a function`,
+      `load: ${renderCauseValue(def.load)} is not a function`,
       'make load a function of ({ params, url }) returning the page data, or remove it',
     );
   }

package/src/sass-cache.ts

@@ -9,7 +9,12 @@ import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'no
 // why: Bun ships no path-join primitive.
 import { join } from 'node:path';
 
-/** Relative to the process's cwd — the app root for every `x` command. `.x/` is gitignored. */
+/**
+ * Relative to the process's cwd — the app root for every `x` command. `.x/` is gitignored, and in
+ * a container it is the STATE directory a topology mounts a tmpfs over, so an image's own entries
+ * live elsewhere: the image build points this cache at its prebuilt store through
+ * `setSassCacheDir`, and the container's boot points it back at the same place.
+ */
 export const SASS_CACHE_DIR = join('.x', 'cache', 'sass');
 
 /** Bumped when the entry shape changes, so an old entry is a miss and never a misread. */
@@ -153,11 +158,25 @@ export function cachedSassCompile(
   assetsValid: AssetCheck = () => false,
 ): SassOutput {
   const dir = cacheDir();
-  if (dir === null) return compile();
+  if (dir === null) return counted(compile);
   const file = join(dir, `${sha256(key)}.json`);
   const hit = readHit(file, assetsValid);
   if (hit !== undefined) return hit;
-  const output = compile();
+  const output = counted(compile);
   store(dir, file, output);
   return output;
 }
+
+let compilations = 0;
+
+const counted = (compile: () => SassOutput): SassOutput => {
+  compilations += 1;
+  return compile();
+};
+
+/**
+ * How many times this process ran Sass rather than reading a stored result. A container booted
+ * from a prebuilt image answers 0; anything else is a boot that compiled what the image build
+ * should have, and the number is what its log line reports.
+ */
+export const sassCompilations = (): number => compilations;

package/src/server.ts

@@ -26,6 +26,7 @@ export {
 // ---- the two Bun loaders: `.tsx` → the server JSX factory, `.scss` → css + a class map ----------
 export type { Stylesheet } from './module-loader';
 export {
+  claimStylesheets,
   clearStylesheets,
   installRenderLoader,
   loadStylesheet,
@@ -47,6 +48,7 @@ export type {
 } from './render-isr';
 export {
   createIsrController,
+  DEFAULT_ISR_REGENERATE_DEADLINE_MS,
   ISR_LOCALE_PARAM,
   invalidateAndRevalidate,
   isrKey,
@@ -76,3 +78,5 @@ export {
   revealChunk,
   streamResult,
 } from './render-stream';
+// ---- the Sass compile cache: where it lives, and how often this process ran Sass instead --------
+export { sassCompilations, setSassCacheDir } from './sass-cache';

package/src/static-path.ts

@@ -35,6 +35,19 @@ const checked = (pattern: string, param: string, segment: string): string => {
   return segment;
 };
 
+/**
+ * A param as text, `undefined` when absent. Typed `string` but filled from app data at runtime:
+ * `{ id: 7 }` reached `.split()` and `for…of` as a number and left the build as a bare `TypeError`.
+ */
+const paramText = (pattern: string, name: string, params: RouteParams): string | undefined => {
+  if (typeof params !== 'object' || params === null) {
+    return refuse(pattern, name, params, 'is missing — the params are not an object');
+  }
+  const value: unknown = Object.hasOwn(params, name) ? params[name] : undefined;
+  if (value === undefined || typeof value === 'string') return value;
+  return refuse(pattern, name, value, 'is not text — a path segment is a string');
+};
+
 /**
  * The raw (decoded) segments, validated. `:name` must be present and one segment; `*name` may span
  * several (`a/b`) and may be absent, but none of its parts may be a dot segment or unsafe.
@@ -45,7 +58,7 @@ export function filledSegments(pattern: string, params: RouteParams): readonly s
     if (segment === '') continue;
     if (segment.startsWith(':')) {
       const name = segment.slice(1);
-      const value = Object.hasOwn(params, name) ? params[name] : undefined;
+      const value = paramText(pattern, name, params);
       if (value === undefined || value === '') {
         return refuse(
           pattern,
@@ -59,7 +72,7 @@ export function filledSegments(pattern: string, params: RouteParams): readonly s
     }
     if (segment.startsWith('*')) {
       const name = segment.slice(1);
-      const value = Object.hasOwn(params, name) ? (params[name] ?? '') : '';
+      const value = paramText(pattern, name, params) ?? '';
       for (const part of value.split('/')) if (part !== '') out.push(checked(pattern, name, part));
       continue;
     }

package/src/type-pins.tsx

@@ -110,9 +110,10 @@ export function _IslandIsAJsxComponent(): unknown {
 /**
  * Every key a route may declare a BUDGET for is a key the descriptor projects.
  *
- * Both sides are derived, so neither can move alone: `budgetJs`/`budgetLcp` on `RouteDescriptor`
- * give `'js' | 'lcp'`, and anything `RouteBudget` declares beyond that fails this line by name.
- * `budget.css`, `budget.cls` and `budget.tbt` were declared on the contract for four majors, were
+ * Both sides are derived, so neither can move alone: `budgetJs` on `RouteDescriptor` gives `'js'`,
+ * and anything `RouteBudget` declares beyond that fails this line by name. `budget.lcp` left the
+ * contract with its descriptor field, measured by nothing. `budget.css`, `budget.cls` and
+ * `budget.tbt` were declared on the contract for four majors, were
  * flattened away by `registerRoute`, and reached no reader anywhere — so an author writing
  * `budget: { cls: 0.1 }` was ignored in silence while `x verify`'s `budgets` step, the one thing
  * that exists to enforce a budget, reported green. `scripts/declaration-readers.ts` is the rule