@ultimat3/render 23.0.0 → 25.0.0

package/src/render-stream.ts

@@ -11,9 +11,8 @@
  * contains no interactive island costs literally zero JS.
  */
 
-import { finiteCount, logger, renderThrowable } from '@ultimat3/core';
+import { BUILD_ID_HEADER, escapeHtml, finiteCount, logger, renderThrowable } from '@ultimat3/core';
 import { finiteStatus } from './finite-status';
-import { escapeAttribute } from './html';
 import type { RenderResult } from './route';
 import { REVEAL_BODY, REVEAL_CALL } from './stream-scripts';
 
@@ -54,7 +53,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 +63,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 +116,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".
@@ -224,7 +224,7 @@ export function streamResult(plan: StreamPlan, options: StreamOptions, status =
       // Proxies that buffer defeat the entire mode.
       'x-accel-buffering': 'no',
       'transfer-encoding': 'chunked',
-      'x-ultimate-build': options.buildId,
+      [BUILD_ID_HEADER]: options.buildId,
     },
     body: renderStreamHtml(plan, options),
   };

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;
 }
 
 /**
@@ -273,8 +265,10 @@ export interface RenderResult {
 /**
  * Route descriptors carry tags in `@ultimat3/cache`'s wire form (`post`, `post:123`), the
  * same strings every cache tier speaks. Render never invents a key convention of its own.
+ * Declaration order is kept — unlike `@ultimat3/cache`'s `tagKeys`, the sorted identity form —
+ * so the name says which list this is, and it stays out of the public barrel.
  */
-export function tagKeys(tags: readonly CacheTag[] | undefined): readonly string[] {
+export function routeTagKeys(tags: readonly CacheTag[] | undefined): readonly string[] {
   return tags === undefined ? [] : serializeTags(tags);
 }
 
@@ -299,7 +293,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 +306,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/server.ts

@@ -47,9 +47,10 @@ export type {
   IsrServeResult,
 } from './render-isr';
 export {
-  createIsrController,
+  DEFAULT_ISR_REGENERATE_DEADLINE_MS,
   ISR_LOCALE_PARAM,
   invalidateAndRevalidate,
+  isrController,
   isrKey,
 } from './render-isr';
 export type { IsrEntry, IsrState, IsrStore, MemoryIsrStoreOptions } from './render-isr-store';

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/stylesheet-path.ts

@@ -0,0 +1,34 @@
+// One responsibility: the ONE spelling of a filesystem path the stylesheet registry compares — `/`
+// separators, `..` folded, a Windows drive letter upper-cased — so "is this sheet below that
+// directory" means the same on Windows, where Bun hands every path over as `D:\app\…`, as on POSIX.
+
+// why: Bun ships no path API, and a relative root must be resolved against the working directory.
+import { posix, resolve } from 'node:path';
+
+/** POSIX-absolute (`/srv/app`), drive-absolute (`D:\app`, `d:/app`) or UNC (`\\host\share`). */
+const ABSOLUTE = /^(?:[A-Za-z]:)?[\\/]/;
+
+/**
+ * Comparable, never displayed: the registry keeps every sheet under the path it was handed and only
+ * COMPARES through this. An absolute path is not re-resolved, because `resolve('/app')` on Windows
+ * is `D:\app` — a drive the sheets a caller handed as `/app/…` never carry.
+ */
+export function comparablePath(path: string): string {
+  const absolute = ABSOLUTE.test(path) ? path : resolve(path);
+  const slashed = posix.normalize(absolute.replaceAll('\\', '/'));
+  const drive = slashed.replace(/^([a-z]):/, (_, letter: string) => `${letter.toUpperCase()}:`);
+  // A trailing separator is dropped so `${dir}/` is one prefix — except the filesystem root itself.
+  const trimmed = drive.replace(/\/+$/, '');
+  return trimmed === '' || trimmed.endsWith(':') ? `${trimmed}/` : trimmed;
+}
+
+/** `path` sits below `dir` — both already `comparablePath`. A sibling sharing a prefix does not. */
+export function isPathBelow(path: string, dir: string): boolean {
+  return path.startsWith(dir.endsWith('/') ? dir : `${dir}/`);
+}
+
+/** `path` relative to `dir` when it sits below it, else `path` — both already `comparablePath`. */
+export function pathBelow(path: string, dir: string): string {
+  if (!isPathBelow(path, dir)) return path;
+  return path.slice(dir.endsWith('/') ? dir.length : dir.length + 1);
+}

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