@ultimat3/render 24.0.0 → 25.1.0

package/src/island-hold.ts

@@ -0,0 +1,56 @@
+// A HELD island (#506): server markup that must not paint before the island mounts, because what
+// it shows can be older than what the page will show — an offline reload's cached count, under a
+// queued write the mount rebuilds. Hidden from its first byte, booted at once, revealed when the
+// mount settles or at the cap. Who is held is the renderer's caller's call (`hold` on the collector).
+
+/** On a held island's wrapper until the runtime reveals it; what the runtime finds it by. */
+export const ISLAND_HOLD_ATTRIBUTE = 'data-x-hold';
+
+/**
+ * The longest a held island stays hidden, whatever its chunk does — a download on a slow network,
+ * a mount that never settles. Above `@ultimat3/realtime`'s `FIRST_PAINT_HOLD_MS` (1 s), the cap on
+ * the disk restore a realtime island waits for, so a slow disk meets that cap and still mounts
+ * before this one shows the server's markup. Interpolated into the runtime: one number, one copy.
+ */
+export const ISLAND_HOLD_MS = 3_000;
+
+/**
+ * The keyframes that reveal a held island with no script at all — JS off, the runtime blocked, a
+ * strategy part that threw before the hold could run. Defined in `@ultimat3/ui`'s `global.scss`
+ * (this package may not import `ui`; `island-hold-replay.test.ts` holds the two spellings equal).
+ */
+export const ISLAND_HOLD_REVEAL = 'ultimate-hold-reveal';
+
+/**
+ * The wrapper's attributes. An inline `style` and not a stylesheet rule: it applies from the byte
+ * the parser reads (no sheet can have loaded yet), and `@ultimat3/http`'s policy admits a style
+ * ATTRIBUTE (`style-src-attr`) where an inline `<style>` would need a hash. `visibility`, never
+ * `display`: the island keeps its box, so the reveal shifts no layout. The animation is the reveal
+ * that needs no script: a zero-length step to `visible` after the cap, held by `forwards` (reduced
+ * motion shortens durations, never delays). The runtime takes both properties off when it reveals.
+ */
+export const ISLAND_HOLD_ATTRIBUTES =
+  `${ISLAND_HOLD_ATTRIBUTE} ` +
+  `style="visibility:hidden;animation:${ISLAND_HOLD_REVEAL} 0s ${ISLAND_HOLD_MS}ms forwards"`;
+
+// Booted at once, whatever the route's strategy: a hidden island receives no press and sits in no
+// idle slot worth waiting for, so `interaction` would hold it until the cap and show the stale
+// markup anyway. `boot` is the prelude's, so the strategy below chains on the SAME `el.__x` and
+// mounts nothing twice. `el.__h`, not `each`'s `el.__v`: `each` would mark the root visited and
+// the strategy's own pass would then skip it. Emitted FIRST after the prelude (`hydrate.ts`), so
+// a strategy part that throws — an old WebView with no IntersectionObserver — cannot strand it.
+// The strategy's capture listeners let go on the first event after the mount (`catchUp`'s `on`),
+// since the hold, not a caught event, is what booted the island.
+//
+// Revealed TOGETHER, once every held island of this pass has settled (or at the cap): one record
+// shown in two islands is rebuilt by whichever island holds its writer — a queued write's overlay
+// is restored inside THAT island's mount — so a reader revealed at its own mount painted the
+// record without it (#506, measured in `offline-like.e2e.test.ts`). A failed mount counts as
+// settled (`hush`): its server markup is shown rather than hidden forever.
+export const RUNTIME_HOLD = `
+var hs=[];Array.prototype.forEach.call(document.querySelectorAll('[${ISLAND_HOLD_ATTRIBUTE}]'),function(el){
+if(!el.__h){el.__h=1;hs.push(el)}});
+if(hs.length){var t,r=function(){clearTimeout(t);hs.forEach(function(el){el.removeAttribute('${ISLAND_HOLD_ATTRIBUTE}');
+el.style.removeProperty('visibility');el.style.removeProperty('animation')})};
+t=setTimeout(r,${ISLAND_HOLD_MS});Promise.all(hs.map(function(el){return boot(el).then(null,hush)})).then(r)}
+`.trim();

package/src/island-props.ts

@@ -173,7 +173,7 @@ export function checkIslandProps(
         'and every one of them ships inside the HTML on every request — ' +
         heaviest.map(([key, size]) => `props.${key} is ${size} B of the ${bytes}`).join(', '),
       `in ${file}, pass ${heaviest.map(([key]) => `\`${key}: []\``).join(' and ')} beside ` +
-        `\`${first}Endpoint: derivePath('<queryName>')\` (@ultimat3/query) and fetch the rows inside ` +
+        `\`${first}Endpoint: queryPath('<queryName>')\` (@ultimat3/core) and fetch the rows inside ` +
         'the island after mount — a list that is the same on every request is a dataset, not a ' +
         'prop; an id, a count and a URL are',
     );

package/src/island.ts

@@ -6,6 +6,7 @@
  * graph (axiom 6). WHEN it wakes is the route's `hydrate`, never a second declaration here.
  */
 
+import { renderFixShellArg } from '@ultimat3/core';
 import { IslandInvalidError } from './errors';
 import type { JsonValue } from './island-props';
 import type { JsxProps } from './jsx';
@@ -195,7 +196,10 @@ function normalizeIsland(declaration: IslandDeclaration): IslandSpec {
     throw new IslandInvalidError(
       `island src ${JSON.stringify(src)} is not an island file: a module ships to the browser ` +
         `only if its name says so, and ${ISLAND_EXTENSION} is the one spelling that says it`,
-      `git mv -- ${src} ${stem}${ISLAND_EXTENSION}, then pass src: '${stem}${ISLAND_EXTENSION}'`,
+      // Screened (security audit of plan 101 sweep 1c, M1): `UNSAFE_SPECIFIER` lets `$(…)`, `;`,
+      // `|` and `&` through. A leading `./` is dropped first — the same path to a shell, and
+      // `renderFixShellArg` refuses a leading `.` — so the common specifier stays pasteable.
+      `git mv -- ${renderFixShellArg(src.replace(/^\.\//, ''), "'<module>'")} ${renderFixShellArg(`${stem.replace(/^\.\//, '')}${ISLAND_EXTENSION}`, `'<name>${ISLAND_EXTENSION}'`)}, then pass src: '${stem}${ISLAND_EXTENSION}'`,
     );
   }
 

package/src/module-loader.ts

@@ -4,12 +4,10 @@
  * `bun test` all load a component the same way and there is no separate "bundled" behaviour.
  */
 
-// why: Bun ships no path API, and a relative app root has to be resolved against the working
-// directory before it can be compared with the absolute paths the Bun plugin hands this loader.
-import { resolve } from 'node:path';
 import { renderThrowable } from '@ultimat3/core';
 import { compileStylesheet, isGlobalStylesheet, stripCharset } from './css-modules';
 import { PrerenderFailedError } from './errors';
+import { comparablePath, isPathBelow, pathBelow } from './stylesheet-path';
 import type { Surface } from './surfaces';
 import { surfaceUnder } from './surfaces';
 
@@ -42,7 +40,8 @@ const RENDER_PACKAGE = '@ultimat3/render';
  * `Bun.plugin` ignores `onResolve` outright — the callback never fires, from module scope or from
  * a `--preload`, and a virtual namespace never resolves — and ignores `resolveDir` on an `onLoad`
  * result. Neither seam can carry the resolution, so the specifier must. Revisit if Bun wires
- * either: an `onResolve` hook would leave every compiled module byte-identical.
+ * either: an `onResolve` hook would leave every compiled module byte-identical. Upstream:
+ * https://github.com/oven-sh/bun/issues/40579.
  *
  * The fallback is the status quo, for the one frame that cannot answer: inside a
  * `bun build --compile` binary `import.meta.url` is `file:///$bunfs/root/<name>` and
@@ -120,9 +119,12 @@ export function registeredStylesheets(): readonly Stylesheet[] {
 /**
  * The directory a sheet's surface is read below. Absent, the process's working directory — which
  * is the app root in the container (`WORKDIR /app`) and under every `x` command run from one.
+ * Held as a `comparablePath`, like every claim: on Windows each arrives as `D:\app\…`.
  */
 let stylesheetRoot: string | undefined;
 
+const rootOfSheets = (): string => stylesheetRoot ?? comparablePath(process.cwd());
+
 /**
  * Directories a package claimed for ONE surface, longest first. A package's sheet has no surface
  * of its own and rides both graphs — right for a design system, and the reason an app's static
@@ -130,11 +132,13 @@ let stylesheetRoot: string | undefined;
  */
 const claims: { readonly dir: string; readonly surface: Surface }[] = [];
 
-const claimedSurface = (path: string): Surface | undefined =>
-  claims.find((claim) => path.startsWith(`${claim.dir}/`))?.surface;
+const claimedSurface = (path: string): Surface | undefined => {
+  const comparable = comparablePath(path);
+  return claims.find((claim) => isPathBelow(comparable, claim.dir))?.surface;
+};
 
 const surfaceOfSheet = (path: string): Surface | null =>
-  claimedSurface(path) ?? surfaceUnder(stylesheetRoot ?? process.cwd(), path);
+  claimedSurface(path) ?? surfaceUnder(rootOfSheets(), comparablePath(path));
 
 /** Every registered sheet, classified again; the revision moves only when an answer does. */
 const reclassify = (): void => {
@@ -157,7 +161,7 @@ const reclassify = (): void => {
  * it standing, because the module that made it is cached and will not make it again.
  */
 export function claimStylesheets(dir: string, surface: Surface): void {
-  const claimed = resolve(dir);
+  const claimed = comparablePath(dir);
   if (claims.some((claim) => claim.dir === claimed && claim.surface === surface)) return;
   claims.push({ dir: claimed, surface });
   claims.sort((a, b) => b.dir.length - a.dir.length);
@@ -174,7 +178,7 @@ export function claimStylesheets(dir: string, surface: Surface): void {
  */
 export function setStylesheetRoot(root: string | undefined): void {
   // Resolved: `loadApp('.')` is a legal call, and `.` is a prefix of no absolute path.
-  stylesheetRoot = root === undefined ? undefined : resolve(root);
+  stylesheetRoot = root === undefined ? undefined : comparablePath(root);
   reclassify();
 }
 
@@ -221,11 +225,12 @@ const OWNER_RANK = (sheet: Stylesheet): number =>
   // A claimed sheet is a package's whichever surface carries it: library first.
   sheet.surface === null || sheet.claimed ? 0 : sheet.surface === 'shared' ? 1 : 2;
 
-/** Relative to the app root, so a container at `/app` and a laptop order one app alike. */
-const orderPath = (sheet: Stylesheet): string => {
-  const root = stylesheetRoot ?? process.cwd();
-  return sheet.file.startsWith(`${root}/`) ? sheet.file.slice(root.length + 1) : sheet.file;
-};
+/**
+ * Relative to the app root and `/`-separated, so a container at `/app`, a laptop and a Windows
+ * checkout at `D:\app` order one app alike — and so mint one stylesheet hash.
+ */
+const orderPath = (sheet: Stylesheet): string =>
+  pathBelow(comparablePath(sheet.file), rootOfSheets());
 
 /** See `stylesFor`: global layer, then owner, then path. Exported for the tests that pin it. */
 export function stylesheetOrder(a: Stylesheet, b: Stylesheet): number {

package/src/navigation-fetch.ts

@@ -1,18 +1,20 @@
 /**
  * The client router's one request: the headers the server's navigation gate reads (purpose, the
  * document's `<app>:<surface>`, its principal, its build on a GET), `redirect: 'manual'` so no
- * redirect is followed behind the router's back, and the answer read ONCE into an `Answer` — the
- * page's text, or a non-page's bytes to hand over (a prefetch's are dropped unread).
+ * redirect is followed behind the router's back, `cache: 'no-cache'` so the browser's HTTP cache
+ * never answers, and the answer read ONCE into an `Answer` — the page's text, or a non-page's
+ * bytes to hand over (a prefetch's are dropped unread).
  */
 
-import { CLIENT_BUILD_META, CLIENT_SCOPE_META } from '@ultimat3/core/page';
 import {
-  NAVIGATION_HEADER,
-  NAVIGATION_LOCATION_HEADER,
-  NAVIGATION_META,
-  NAVIGATION_SCOPE_HEADER,
-  NAVIGATION_SURFACE_HEADER,
-} from './navigation-rules';
+  CLIENT_BUILD_META,
+  CLIENT_NAVIGATION_HEADER,
+  CLIENT_NAVIGATION_LOCATION_HEADER,
+  CLIENT_NAVIGATION_SCOPE_HEADER,
+  CLIENT_NAVIGATION_SURFACE_HEADER,
+  CLIENT_SCOPE_META,
+} from '@ultimat3/core/page';
+import { NAVIGATION_META } from './navigation-rules';
 
 /** One fetched answer, read once — a prefetch and the click after it share it. */
 export interface Answer {
@@ -41,16 +43,24 @@ export function fetchDocument(
 ): Promise<Answer> {
   const headers: Record<string, string> = {
     accept: 'text/html,application/xhtml+xml',
-    [NAVIGATION_HEADER]: purpose,
-    [NAVIGATION_SURFACE_HEADER]: metaOf(doc, NAVIGATION_META) ?? '',
+    [CLIENT_NAVIGATION_HEADER]: purpose,
+    [CLIENT_NAVIGATION_SURFACE_HEADER]: metaOf(doc, NAVIGATION_META) ?? '',
   };
   const scope = metaOf(doc, CLIENT_SCOPE_META);
-  if (scope !== null) headers[NAVIGATION_SCOPE_HEADER] = scope;
+  if (scope !== null) headers[CLIENT_NAVIGATION_SCOPE_HEADER] = scope;
   // GET only: a skewed GET is refused before any route runs; a POST is never refused mid-submit.
   const build = metaOf(doc, CLIENT_BUILD_META);
   if ((init.method ?? 'GET') === 'GET' && build !== null) headers[CLIENT_BUILD_META] = build;
+  // `no-cache`: the browser's HTTP cache never answers — a `stale-while-revalidate` page would be
+  // swapped in stale after a write, a sign-out or a deploy (#693); the router's cache is the only one.
   return win
-    .fetch(url, { ...init, credentials: 'same-origin', redirect: 'manual', headers })
+    .fetch(url, {
+      ...init,
+      cache: 'no-cache',
+      credentials: 'same-origin',
+      redirect: 'manual',
+      headers,
+    })
     .then(async (response) => {
       const contentType = response.headers.get('content-type') ?? '';
       const opaqueRedirect = response.type === 'opaqueredirect';
@@ -61,7 +71,7 @@ export function fetchDocument(
         if (purpose === 'prefetch') await response.body?.cancel();
         else body = await response.blob();
       }
-      const location = response.headers.get(NAVIGATION_LOCATION_HEADER);
+      const location = response.headers.get(CLIENT_NAVIGATION_LOCATION_HEADER);
       return {
         status: response.status,
         opaqueRedirect,

package/src/navigation-rules.ts

@@ -1,33 +1,19 @@
 /**
  * Which clicks and submits the client router takes, and which it leaves to the browser — as pure
  * functions over plain facts, so every rule is testable without a DOM and the router
- * (`navigation.ts`) only gathers the facts. Also the one declaration of every attribute, header and
- * event name the router shares with the documents the server renders and the apps that listen.
+ * (`navigation.ts`) only gathers the facts. Also the one declaration of every attribute and event
+ * name the router shares with the documents the server renders and the apps that listen; the
+ * router's headers are core's (`CLIENT_NAVIGATION_*_HEADER`), imported where they are sent.
  */
 
-import {
-  CLIENT_NAVIGATION_HEADER,
-  CLIENT_NAVIGATION_LOCATION_HEADER,
-  CLIENT_NAVIGATION_SCOPE_HEADER,
-  CLIENT_NAVIGATION_SURFACE_HEADER,
-} from '@ultimat3/core/page';
-
 /**
  * `<meta name="ultimate-navigation" content="<app>:<surface>">` — present only on an opted-in
  * surface. The app's name is part of it, so two apps on one origin (web and admin) are two routers.
  */
 export const NAVIGATION_META = 'ultimate-navigation';
-/**
- * Sent on every router fetch: `soft` when a visitor asked for the page, `prefetch` when the router
- * guessed they would. The server answers a route that did not opt in before running it.
- */
-export const NAVIGATION_HEADER = CLIENT_NAVIGATION_HEADER;
-/** The `<app>:<surface>` of the document the router runs in, on every router fetch. */
-export const NAVIGATION_SURFACE_HEADER = CLIENT_NAVIGATION_SURFACE_HEADER;
-/** The document's principal (`ultimate-scope`), when it carries one. */
-export const NAVIGATION_SCOPE_HEADER = CLIENT_NAVIGATION_SCOPE_HEADER;
-/** On a `204`: load this URL with a real navigation — the server's hand-over. */
-export const NAVIGATION_LOCATION_HEADER = CLIENT_NAVIGATION_LOCATION_HEADER;
+// The four router HEADERS are core's (`CLIENT_NAVIGATION_HEADER`, `…_SURFACE_HEADER`,
+// `…_SCOPE_HEADER`, `…_LOCATION_HEADER`), imported by the fetcher and by `@ultimat3/http`'s gate —
+// 25.0.0 deleted the `NAVIGATION_*_HEADER` aliases this file published for them (`X_HELPER_COPY`).
 /** On a link or form: always a full document load. */
 export const NAVIGATION_RELOAD_ATTRIBUTE = 'data-x-reload';
 /** On a link: followed softly, never fetched before it is clicked. */
@@ -275,7 +261,15 @@ export function responseVerdict(facts: ResponseFacts): ResponseVerdict {
     facts.build !== null && facts.nextBuild !== null && facts.build !== facts.nextBuild;
   // A GET refused for skew (409 before any route ran) or rendered by another build: load it.
   if (get && skewed) return load(facts.requested, 'another build');
-  if (!/^\s*text\/html\b/i.test(facts.contentType)) return { kind: 'hand-over' };
+  const html = /^\s*text\/html\b/i.test(facts.contentType);
+  // An error that is not a page (an offline service worker's empty 503, a JSON 404) is nothing to
+  // show — handed over, it became a `blob:` URL in the address bar. A GET is the browser's to
+  // load (a worker answers a real navigation with its offline page); a POST is never re-sent.
+  if (facts.status >= 400 && !html) {
+    const reason = 'an error answer that is not a page';
+    return get ? load(facts.requested, reason) : { kind: 'failed', reason };
+  }
+  if (!html) return { kind: 'hand-over' };
   // A POST answered in place IS the page the browser would have shown, whatever rendered it —
   // and when that is another principal's or build's, the caller stops trusting this tab
   // (`answerMovesTab`): every later navigation is a real load.

package/src/navigation.ts

@@ -46,6 +46,7 @@ import {
   NAVIGATED_EVENT,
   NAVIGATING_ATTRIBUTE,
   NAVIGATION_ERROR_EVENT,
+  NAVIGATION_MAX_HOPS,
   NAVIGATION_META,
   NAVIGATION_NO_PREFETCH_ATTRIBUTE,
   NAVIGATION_PREFETCH_DELAY_MS,
@@ -103,7 +104,7 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
   let rendered = withoutFragment(win.location.href);
   /** The URL a navigation in flight is fetching: a prefetch never asks for it a second time. */
   let navigatingTo: string | undefined;
-  /** The view transition still animating, which a press skips to the new page. */
+  /** The view transition still animating — skipped only for a click it swallowed (`onClick`). */
   let animating: RunningTransition | undefined;
   /** Between a press and its click: the focus the press gives a link is not a hover. */
   let pressed = false;
@@ -172,6 +173,12 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
   };
 
   const navigate = async (url: string, options: NavigateOptions = {}): Promise<void> => {
+    // The redirect chain's only exit is `hops >= NAVIGATION_MAX_HOPS`, which `NaN` never meets.
+    // `hops` is this router's own recursion counter (nothing outside it can reach `navigate`), so a
+    // non-count is a broken caller, not input: it fails CLOSED as an exhausted chain — one request,
+    // then the browser loads the page — instead of shipping the error renderer (~2 KB) to every page.
+    const asked = options.hops ?? 0;
+    const hops = Number.isSafeInteger(asked) && asked >= 0 ? asked : NAVIGATION_MAX_HOPS;
     const method = options.method ?? 'GET';
     // After an answer for another principal or build was shown in place, this tab is no longer
     // trusted to swap: every navigation is a real load (`answerMovesTab`).
@@ -212,7 +219,7 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
         opaqueRedirect: answer.opaqueRedirect,
         location: answer.location,
         contentType: answer.contentType,
-        hops: options.hops ?? 0,
+        hops,
         surface: metaOf(doc, NAVIGATION_META),
         nextSurface: next === null ? null : metaOf(next, NAVIGATION_META),
         build: metaOf(doc, CLIENT_BUILD_META),
@@ -236,7 +243,7 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
         case 'follow':
           await navigate(verdict.url, {
             history: options.history === 'none' ? 'replace' : 'push',
-            hops: (options.hops ?? 0) + 1,
+            hops: hops + 1,
           });
           return;
         case 'hand-over':
@@ -315,9 +322,9 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
     pressed = true;
     pressedOverTransition = animating !== undefined;
     // A press is not a hover: the click it becomes navigates, and a guess on its heels is a
-    // second request for the same page. And a press during the animation skips to the new page.
+    // second request for the same page. A press alone never skips the running transition — that
+    // snapped every named element to its end mid-glide (#621); only the click below may.
     win.clearTimeout(intent);
-    animating?.skipTransition?.();
   };
   const onRelease = (): void => {
     pressed = false;
@@ -325,13 +332,15 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
 
   const onClick = (event: MouseEvent): void => {
     win.clearTimeout(intent);
-    // While a view transition paints, the browser hit-tests every press to `<html>`: the press
-    // skipped the animation (`onPress`), the release landed on the real element, and the click —
-    // aimed at their common ancestor — reached nothing. The visitor's first click after a swap was
-    // lost. It is given to the element under the pointer NOW, whatever it is: a link, a submit
-    // button, an island's own control.
+    // While a view transition paints, the browser hit-tests every press to `<html>` — Chrome does
+    // so whatever `pointer-events` the `::view-transition` overlay has — so the click reached
+    // nothing: the visitor's first click after a swap was lost. It is given to the element under
+    // the pointer, whatever it is: a link, a submit button, an island's own control. Only a
+    // skipped transition hit-tests the page, so the skip happens HERE, at the click, never at
+    // the press; when the animation already ended between the two, there is nothing to skip.
     if (pressedOverTransition && event.target === doc.documentElement) {
       pressedOverTransition = false;
+      animating?.skipTransition?.();
       const hit = doc.elementFromPoint(event.clientX, event.clientY);
       if (hit !== null && hit !== doc.documentElement && hit instanceof HTMLElement) hit.click();
       return;

package/src/registry.ts

@@ -1,6 +1,6 @@
 /**
  * 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.
  */
@@ -27,7 +27,7 @@ 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';
@@ -206,7 +206,7 @@ function toUrlSegment(segment: string): string {
 }
 
 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> {
@@ -250,7 +250,7 @@ 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(
@@ -367,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));
 }
@@ -380,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.
@@ -422,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,

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 { escapeHtml, 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';
@@ -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

@@ -17,11 +17,11 @@ import {
   unregisterDependent,
 } from '@ultimat3/cache';
 import type { Scheduler } from '@ultimat3/core';
-import { createSingleFlight, finiteCount, logger, renderThrowable } 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';
@@ -153,16 +153,16 @@ 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 flight = createSingleFlight({
+  const flight = singleFlight({
     deadlineMs: finiteCount(
-      'createIsrController',
+      'isrController',
       'regenerateDeadlineMs',
       options.regenerateDeadlineMs ?? DEFAULT_ISR_REGENERATE_DEADLINE_MS,
       1,
@@ -380,7 +380,7 @@ 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[]>();
 
 /**

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 { renderCauseValue, 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';
@@ -161,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,
   };
 }
 

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 { escapeHtml } from './html';
 import type { RenderResult } from './route';
 import { REVEAL_BODY, REVEAL_CALL } from './stream-scripts';
 
@@ -225,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.ts

@@ -265,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);
 }
 

package/src/server.ts

@@ -47,10 +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/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);
+}