@ultimat3/render 22.7.0 → 22.8.0

package/CLAUDE.md

@@ -25,7 +25,7 @@ axiom 6). Never `cli` (upward).
 |---|---|
 | `offline`, `meta` | required by `RouteDefinition`. Never make them optional. |
 | `hydrate` | optional, **derived from `island()`** — `'interaction'` when the module declared one, `'never'` when not. Declaring it still wins and is the only way to reach `idle` / `visible`. Never give an island its own strategy: `RouteDescriptor.hydrate` is read by `sw.js`, the web manifest and `x routes`. |
-| `defineRoute` shape | exactly the contract's 11 keys (`cache`, `ssr` only, is the tenth; `post`, an action's export name bound to `POST` at the page URL, the eleventh — never on `static`, `X_ROUTE_POST_INVALID`; the CLI mounts it and refuses an unregistered name at boot). New route *metadata* goes inside `meta`. |
+| `defineRoute` shape | exactly the contract's 12 keys (`cache`, `ssr` only, is the tenth; `post`, an action's export name bound to `POST` at the page URL, the eleventh — never on `static`, `X_ROUTE_POST_INVALID`; the CLI mounts it and refuses an unregistered name at boot; `navigation`, `'prefetch' \| 'document'`, the twelfth — read by the server's navigation gate, refused off a `navigation.client` surface at boot, `X_ROUTE_NAVIGATION_INVALID`). New route *metadata* goes inside `meta`. |
 | `load` | optional, and the ONE server-side data seam. Resolved once per render by `routeDataFor()` and handed to **both** `meta` and the page component. Absent `load`, the context IS the data (`{ params, url }`). |
 | `load` is required when the context cannot supply the data | `LoadRequirement<TData>` in `defineRoute`'s parameter. `RouteContext` is a type ALIAS on purpose — only an alias carries the implicit index signature that makes it a `RouteData`. |
 | A loader's own error | rethrown only when `isUltimateError` says so (core's brand), never a `code` property and never `instanceof UltimateError` — a tier-0 error is branded, not a subclass. Everything else is `X_ROUTE_LOAD_FAILED`. |
@@ -54,7 +54,7 @@ axiom 6). Never `cli` (upward).
 | The hydration runtime's CSP | `HYDRATE_RUNTIME_BODIES` — every body `hydrateRuntime` can emit (seven subsets). It is inline in every document with an island and `@ultimat3/http`'s `script-src` is `'self' 'wasm-unsafe-eval'`, so `@ultimat3/cli`'s `script-csp.ts` hashes this list at boot. `runtimeBody` is the one place the served and hashed text are one string. **Uncovered**: `render-stream.ts`'s per-hole `<script>$X("id")</script>` (unreachable today; the first real hole needs a nonce). |
 | Island markup | the props `<script>` is emitted INSIDE the wrapper by `render-html.ts`; an assembler only adds `hydrateRuntime(directives)`. |
 | Island boot | `el.__x` holds the boot PROMISE, never a boolean. |
-| Island mount markers | `data-x-mounted=""` when `mount()` resolved, `data-x-failed="<message>"` when it rejected — set by the runtime, never by `emitIslandAttributes`. The rejection handler RETHROWS. Prelude sizes `As of 2026-09-22`: `idle` 1,744, `visible` 846, `interaction` 1,629 B (what `DEFAULT_ISLAND_JS_BYTES` derives from). |
+| Island mount markers | `data-x-mounted=""` when `mount()` resolved, `data-x-failed="<message>"` when it rejected — set by the runtime, never by `emitIslandAttributes`. The rejection handler RETHROWS. Prelude sizes `As of 2026-09-28`: `idle` 1,784, `visible` 886, `interaction` 1,669 B (what `DEFAULT_ISLAND_JS_BYTES` derives from). |
 | A runtime that calls `boot` | TERMINATES the chain: `idle`/`visible` end in `.catch(hush)`, `interaction` passes `off` as the rejection arm. `hydrate-runtime.test.ts` reds on an unhandled rejection. |
 | `idle` replays too | `idle` and `interaction` share ONE `catchUp(el)` in `hydrate.ts` (capture listeners for `data-x-events`, default `click`; a queue; `aim`; one flush). A caught event wakes an `idle` island early; each event replays once. `hydrate-replay.test.ts`. |
 | Where `interaction` replays | `aim(el, ev)`, never `ev.target` — `mount` usually clears the root, detaching the pressed node. Kept → original target; replaced → `path(el, target)`'s structural walk (same tag, same place), then `document.elementFromPoint(ev.clientX, ev.clientY)` (unless `ev.detail === 0`), then the island root. A hit outside the island falls back to the root. `hydrate-replay.test.ts`. |
@@ -100,6 +100,10 @@ axiom 6). Never `cli` (upward).
 | Colours | tokens and `data-theme` only. No hex in `head.ts` or any emitted script. |
 | An island's `mount` | may return `() => void`, its disposer; the runtime never calls it, `@ultimat3/testing`'s `mountIsland` does. |
 | `<head>` binding | `head.ts` stays injection-only; `head-seo.ts` is the ONE binding of `HeadRenderers` to `@ultimat3/seo`. |
+| Client navigation | `navigation*.ts` — soft navigation over server-rendered documents, NOT a mode: the router renders nothing, it swaps the document the route already rendered. Rules are pure (`navigation-rules.ts`: `linkVerdict`, `formVerdict`, `responseVerdict`, `mayPrefetch`) and unit-tested; the DOM half (`navigation-swap.ts`, `navigation.ts`) is proven in Chrome by `packages/cli/e2e/client-navigation-*.e2e.test.ts`. `./navigation` (`navigation-entry.ts`) is the script the CLI builds; importing it starts it, and a document without `ultimate-navigation` is never intercepted. |
+| Router ↔ islands | ONE bootstrap: the swap re-runs the inline hydration runtime, whose `each` visits a root once per tab (`el.__v`). Never add a second mount path for the router. Dispose = call what `el.__x` resolved to. |
+| Router head diff | only elements a SERVER document put in `<head>` (`documentHead`'s set) may be removed; a script-added one is the tab's. Scripts and stylesheets are never diffed. |
+| Router: nothing is sent twice | the router follows no redirect (`redirect: 'manual'`; the server hands it over as `204` + `x-ultimate-location`), never re-submits a POST (a failure is `ultimate:navigation-error`), and hands a non-page answer to the browser from the bytes it already has. Its cache never answers with a non-2xx, a hand-over, or a `no-store` page older than 5 s, and is emptied by any POST, `onClientWrite`, `onRescope` and a `BroadcastChannel` message from another tab. |
 
 Cross-package: `@ultimat3/pwa` consumes route descriptors as **data**, never by import.
 Keep `RouteDescriptor` additive — removing a field breaks `sw.js` generation.

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@ultimat3/render",
-  "version": "22.7.0",
+  "version": "22.8.0",
   "description": "The route primitive and the five render modes: static, isr, ssr, stream, spa.",
   "license": "MIT",
   "type": "module",
   "sideEffects": [
     "./src/errors.ts",
-    "./src/server.ts"
+    "./src/server.ts",
+    "./src/navigation-entry.ts"
   ],
   "repository": {
     "type": "git",
@@ -19,7 +20,8 @@
   },
   "exports": {
     ".": "./src/index.ts",
-    "./server": "./src/server.ts"
+    "./server": "./src/server.ts",
+    "./navigation": "./src/navigation-entry.ts"
   },
   "files": [
     "src",
@@ -36,11 +38,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "22.7.0",
-    "@ultimat3/core": "22.7.0",
-    "@ultimat3/http": "22.7.0",
-    "@ultimat3/i18n": "22.7.0",
-    "@ultimat3/seo": "22.7.0",
+    "@ultimat3/cache": "22.8.0",
+    "@ultimat3/core": "22.8.0",
+    "@ultimat3/http": "22.8.0",
+    "@ultimat3/i18n": "22.8.0",
+    "@ultimat3/seo": "22.8.0",
     "sass": "1.104.0"
   }
 }

package/src/errors.ts

@@ -27,6 +27,7 @@ export const RENDER_ERROR_CODES = [
   'X_STYLES_GLOBAL_MISSING',
   'X_ASSET_MISSING',
   'X_ROUTE_POST_INVALID',
+  'X_ROUTE_NAVIGATION_INVALID',
 ] as const;
 
 export type RenderErrorCode = (typeof RENDER_ERROR_CODES)[number];
@@ -51,6 +52,8 @@ export const RENDER_ERROR_TITLES: Readonly<Record<RenderErrorCode, string>> = {
     'a surface renders documents whose CSS defines no :root custom properties',
   X_ASSET_MISSING: 'a page names a site asset the app does not have',
   X_ROUTE_POST_INVALID: "a page route's post binding cannot be mounted",
+  X_ROUTE_NAVIGATION_INVALID:
+    "a route's navigation is not 'prefetch' or 'document', or its surface has no client navigation",
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -200,6 +203,21 @@ export class RoutePostInvalidError extends UltimateError {
   }
 }
 
+/**
+ * `defineRoute({ navigation })` that says nothing a process can honour: a value other than
+ * `'prefetch'` or `'document'`, or — at boot — a page whose surface has no client navigation.
+ */
+export class RouteNavigationInvalidError extends UltimateError {
+  static readonly code = 'X_ROUTE_NAVIGATION_INVALID' as const;
+  constructor(cause: string) {
+    super({
+      code: RouteNavigationInvalidError.code,
+      cause,
+      fix: "defineRoute({ ..., navigation: 'prefetch' | 'document' }) on a page whose surface is listed in app.config.ts navigation.client, or remove the key",
+    });
+  }
+}
+
 export class RouteLoadInvalidError extends UltimateError {
   static readonly code = 'X_ROUTE_LOAD_INVALID' as const;
   constructor(cause: string, fix: string) {

package/src/hydrate.ts

@@ -129,9 +129,13 @@ var props=p?JSON.parse(p.textContent||'{}'):{};
 return el.__x=import(e).then(function(m){return m.mount(el,props)}).then(
 function(r){el.setAttribute('${ISLAND_MOUNTED_ATTRIBUTE}','');return r},
 function(x){el.setAttribute('${ISLAND_FAILED_ATTRIBUTE}',x&&x.message||'1');throw x})}
-function each(s,f){Array.prototype.forEach.call(document.querySelectorAll(s),f)}
+function each(s,f){Array.prototype.forEach.call(document.querySelectorAll(s),function(el){if(!el.__v){el.__v=1;f(el)}})}
 function hush(){}
 `.trim();
+// `each` visits an island root ONCE per tab (`el.__v`): the client router (`navigation-swap.ts`)
+// re-runs this same runtime over every body it swaps in, and an island it carried across
+// (`data-x-persist`) must not get a second `catchUp` — its listeners would replay every later click
+// twice. One bootstrap path, safe to run again, instead of a second mount API for the router.
 // `hush` above: `boot` rethrows, so every runtime below has to terminate the chain it starts or
 // the page reports an unhandled rejection for a failure it already recorded on the element.
 

package/src/index.ts

@@ -53,6 +53,7 @@ export {
   RouteLoadInvalidError,
   RouteMetaMissingError,
   RouteModeInvalidError,
+  RouteNavigationInvalidError,
   RouteOfflineMissingError,
   RoutePostInvalidError,
   RouteStatusInvalidError,
@@ -111,6 +112,46 @@ export {
   defaultIslandBudget,
   MODE_SPECS,
 } from './modes';
+/** Client-side navigation over server-rendered documents — `navigation: { client }` surfaces. */
+export type { CachedDocument, NavigationCache, NavigationCacheOptions } from './navigation-cache';
+export { cacheKey, NAVIGATION_CACHE_MAX_ENTRIES, navigationCache } from './navigation-cache';
+export type {
+  CachedFacts,
+  FormFacts,
+  FormVerdict,
+  LinkFacts,
+  LinkVerdict,
+  NativeReason,
+  PrefetchFacts,
+  ResponseFacts,
+  ResponseVerdict,
+} from './navigation-rules';
+export {
+  formVerdict,
+  linkVerdict,
+  mayPrefetch,
+  NAVIGATE_EVENT,
+  NAVIGATED_EVENT,
+  NAVIGATING_ATTRIBUTE,
+  NAVIGATION_CACHE_TTL_MS,
+  NAVIGATION_ERROR_EVENT,
+  NAVIGATION_HEADER,
+  NAVIGATION_LOCATION_HEADER,
+  NAVIGATION_MAX_HOPS,
+  NAVIGATION_META,
+  NAVIGATION_NO_PREFETCH_ATTRIBUTE,
+  NAVIGATION_NO_STORE_REUSE_MS,
+  NAVIGATION_PERSIST_ATTRIBUTE,
+  NAVIGATION_PREFETCH_DELAY_MS,
+  NAVIGATION_PROGRESS_DELAY_MS,
+  NAVIGATION_RELOAD_ATTRIBUTE,
+  NAVIGATION_SCOPE_HEADER,
+  NAVIGATION_SURFACE_HEADER,
+  responseVerdict,
+  reusable,
+} from './navigation-rules';
+export type { ClientNavigationHead } from './navigation-tags';
+export { clientNavigationTags } from './navigation-tags';
 export type {
   CompiledPattern,
   RegisterRouteInput,
@@ -145,9 +186,16 @@ export type {
   RouteMetaAsyncFn,
   RouteMetaContext,
   RouteMetaFn,
+  RouteNavigationMode,
   RouteParams,
 } from './route';
-export { DEFAULT_ISLAND_HYDRATE, defineRoute, isRouteConfig, tagKeys } from './route';
+export {
+  DEFAULT_ISLAND_HYDRATE,
+  defineRoute,
+  isRouteConfig,
+  ROUTE_NAVIGATION_MODES,
+  tagKeys,
+} from './route';
 export type { RouteComponent } from './route-component';
 export { pageComponentOf } from './route-component';
 export { metaContextFor, routeDataFor } from './route-data';

package/src/modes.ts

@@ -246,12 +246,12 @@ export function defaultHydrate(surface: Surface): HydrateStrategy {
  * (`settings.island.tsx`) is 17,797 B. No `budget.js` under 4096 was reachable by any of them, on
  * any surface, because the allowance is measured above the baseline and not against it.
  *
- * The number: 17,797 (the heaviest island this repo actually ships) + 1,744 (`hydrateRuntimeBytes`
+ * The number: 17,797 (the heaviest island this repo actually ships) + 1,784 (`hydrateRuntimeBytes`
  * for one `idle` directive — `defaultHydrate('app')`, and since 2026-09-22 the costlier of the two
- * runtimes an island gets unasked; `DEFAULT_ISLAND_HYDRATE`'s `'interaction'` is 1,629) =
- * **19,541**. That is the worst case an app reaches without writing a number down. 20,480 is the
- * next whole kilobyte above it, leaving 939 B of headroom and still under 2x 19,541, so a route
- * bundling the same island twice is refused. `island-budget.test.ts` asserts all three. `visible` costs 846, so an island route
+ * runtimes an island gets unasked; `DEFAULT_ISLAND_HYDRATE`'s `'interaction'` is 1,669) =
+ * **19,581**. That is the worst case an app reaches without writing a number down. 20,480 is the
+ * next whole kilobyte above it, leaving 899 B of headroom and still under 2x 19,581, so a route
+ * bundling the same island twice is refused. `island-budget.test.ts` asserts all three. `visible` costs 886, so an island route
  * that declares it pays less; the default is what the budget has to clear.
  *
  * All three grew by 129 B on 2026-08-21 (from 881 / 615 / 687), when the prelude learned to mark a

package/src/navigation-cache.ts

@@ -0,0 +1,93 @@
+/**
+ * The client router's per-tab memory of documents it fetched: a prefetch on intent, answered by
+ * the click that follows. Memory only, never storage — a gated page rendered for this principal
+ * must not outlive the tab — for `NAVIGATION_CACHE_TTL_MS`, and emptied by any POST, because a
+ * write is the one thing this tab knows makes every page it holds suspect.
+ */
+
+import { NAVIGATION_CACHE_TTL_MS } from './navigation-rules';
+
+/** One fetched document: the promise, so a click during the prefetch waits for the same fetch. */
+export interface CachedDocument<T> {
+  readonly at: number;
+  readonly value: Promise<T>;
+}
+
+export interface NavigationCache<T> {
+  /** A fresh entry for `url`, or `undefined` — an expired one is dropped on the way. */
+  get(url: string): Promise<T> | undefined;
+  /** A fresh entry's answer and how old it is, or `undefined`. */
+  peek(url: string): { readonly value: Promise<T>; readonly ageMs: number } | undefined;
+  set(url: string, value: Promise<T>): void;
+  delete(url: string): void;
+  clear(): void;
+  readonly size: number;
+}
+
+export interface NavigationCacheOptions {
+  /** The clock, for a test. The TTL and the cap are constants: nothing has a reason to vary them. */
+  readonly now?: () => number;
+}
+
+/** Bounded: a visitor hovering a 200-row table must not hold 200 documents. */
+export const NAVIGATION_CACHE_MAX_ENTRIES = 20;
+
+/**
+ * The fragment never reaches the server, so `/a#x` and `/a#y` are one document; and `?b=2&a=1` is
+ * `?a=1&b=2` — one query, however a link happened to spell it.
+ */
+export const cacheKey = (url: string): string => {
+  const parsed = new URL(url, 'http://x.invalid');
+  parsed.hash = '';
+  parsed.searchParams.sort();
+  return url.startsWith('/') ? `${parsed.pathname}${parsed.search}` : parsed.href;
+};
+
+export function navigationCache<T>(options: NavigationCacheOptions = {}): NavigationCache<T> {
+  const ttl = NAVIGATION_CACHE_TTL_MS;
+  const now = options.now ?? Date.now;
+  const max = NAVIGATION_CACHE_MAX_ENTRIES;
+  const entries = new Map<string, CachedDocument<T>>();
+  return {
+    get(url) {
+      const key = cacheKey(url);
+      const entry = entries.get(key);
+      if (entry === undefined) return undefined;
+      if (now() - entry.at >= ttl) {
+        entries.delete(key);
+        return undefined;
+      }
+      return entry.value;
+    },
+    peek(url) {
+      const value = this.get(url);
+      const entry = entries.get(cacheKey(url));
+      return value === undefined || entry === undefined
+        ? undefined
+        : { value, ageMs: now() - entry.at };
+    },
+    set(url, value) {
+      const key = cacheKey(url);
+      entries.delete(key);
+      entries.set(key, { at: now(), value });
+      // Oldest first: a Map iterates in insertion order and `set` re-inserts.
+      for (const oldest of entries.keys()) {
+        if (entries.size <= max) break;
+        entries.delete(oldest);
+      }
+      // A failed fetch is not a document: the next click must ask again, not replay the failure.
+      value.catch(() => {
+        if (entries.get(key)?.value === value) entries.delete(key);
+      });
+    },
+    delete(url) {
+      entries.delete(cacheKey(url));
+    },
+    clear() {
+      entries.clear();
+    },
+    get size() {
+      return entries.size;
+    },
+  };
+}