@ultimat3/render 26.0.0 → 26.1.1

package/CLAUDE.md

@@ -10,7 +10,12 @@ loaders that make an app's `.tsx` and `.scss` runnable**.
 `node:url`, which a browser build cannot link; no `sideEffects` value repairs that). Never re-export
 a name from both barrels: `index.test.ts` asserts the empty name intersection and that `index.ts`'s
 runtime import graph reaches none of those seven modules; `scripts/browser-barrel.test.ts` holds
-the end property.
+the end property. **`"./client"` (`client.ts`) is THE browser entry** for what an island calls
+(`navigate`, `refresh`, `openModal`, `closeModal`, the modal refusal, the three event names): its
+graph never reaches `errors.ts` (the barrel's `sideEffects` keeps that table in every chunk), held
+by `client-bundle.test.ts`. A name there stays on `.` too (additive); a refusal it can construct
+lives in its own module over `@ultimat3/core/page`'s `UltimateError` (`navigation-errors.ts`) and
+`errors.ts` re-exports it — one class, never two.
 
 `island()` is a **factory over the route's own `hydrate`**, not a ninth primitive and not a second
 render mode. It adds no key to `defineRoute`.
@@ -109,7 +114,7 @@ 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. |
+| 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. Route-presented modals (`navigation: 'modal'`): the hash grammar and verdicts are pure (`navigation-modal-rules.ts`), the `<dialog>` is `navigation-modal.ts`, styled by `@ultimat3/ui`'s `global.scss` under `NAVIGATION_MODAL_ATTRIBUTE` (pinned by `navigation-modal-style.test.ts` — render never imports ui), proven by `client-navigation-modal.e2e.test.ts`. |
 | Router ↔ the page's lifecycle | `navigation-scroll.ts` owns `scrollRestoration = 'manual'` and RESTORES the entry's saved offset at start, before its first save (a reload, or Back after a full load); `navigation-tabs.ts` owns the `BroadcastChannel`, closed on `pagehide` (it blocks the back/forward cache), reopened and the cache emptied on a persisted `pageshow`. A sheet `loadStylesheets` appends is `owned` at once, so an aborted navigation's sheets are retired by the next swap. A view transition is tracked by identity: an older one finishing never clears the running one. |
 | 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. |

package/README.md

@@ -126,6 +126,27 @@ posted fields (query wins). An RFC 8058 one-click `POST /correos/baja?t=…` wit
 `GET` stays the confirm page. `@ultimat3/cli` mounts it in both boots; a name no action is
 registered under is `X_ROUTE_POST_INVALID` at boot, as is `post` on a `static` page.
 
+## `navigation` — how the client router treats a page
+
+On a surface listed in `app.config.ts`'s `navigation.client` only (elsewhere it refuses the boot,
+`X_ROUTE_NAVIGATION_INVALID`). Absent: swapped in on a click, never prefetched. Full rules:
+[Client Navigation](../../wiki/Client-Navigation.md).
+
+| `navigation` | The page |
+|---|---|
+| `'prefetch'` | may also be fetched on hover/focus — a GET that does nothing but render |
+| `'document'` | always a real document load; carries no router |
+| `'modal'` | `As of 26.1.0`. Shown OVER the page a visitor is on, in a native `<dialog>`, addressed by the hash (`/runs#/runs/new`); reload, Back/Forward and a pasted URL reopen it, a stale hash is just the page. A full load of its own URL is still the whole page — the server renders one document for both and names it a modal (`NAVIGATION_PRESENTATION_META`) |
+
+Declared on the route, never on a link: the route is the one place that covers every way of
+reaching a page — a link, a redirect after a POST, a pasted hash.
+
+From code — an island, an app script — `navigate(url, { replace? })`, `refresh()`,
+`openModal(path)` and `closeModal()` go through the router when the page has one and fall back to
+`location.assign`/`replace`/`reload` when it does not; they import the router's type only. An
+island imports them from **`@ultimat3/render/client`**, never the barrel — see
+[Two entry points](#two-entry-points). [Navigating from code](../../wiki/Client-Navigation.md#navigating-from-code).
+
 ## Mode invariants, checked at registration
 
 | Mode | Invariant | Error if violated |
@@ -463,6 +484,19 @@ does.
 side effect. Anything that loads an app's source — `x dev`, `x build`, `server.ts`, a test that
 `await import()`s a `page.tsx` — reaches it before the module it loads.
 
+`@ultimat3/render/client` is the **browser** entry — what an island or a page script calls:
+`navigate`, `refresh`, `openModal`, `closeModal`, `NavigateToOptions`,
+`NavigationModalPathInvalidError`, `NAVIGATE_EVENT`, `NAVIGATED_EVENT`, `NAVIGATION_ERROR_EVENT`.
+The barrel bundles for the browser but its `sideEffects` keeps `errors.ts` — render's code table,
+and core's and schema's titles tables behind it — in every chunk that reaches it; this entry's
+graph is the navigation helpers plus `@ultimat3/core/page` (`client-bundle.test.ts`). `As of
+2026-10-08`, an island whose body is `refresh()`: 9,323 B minified from the barrel, 216 B from
+`/client`. The barrel keeps the same names, for compatibility.
+
+```ts
+import { navigate, refresh } from '@ultimat3/render/client';
+```
+
 ## Error classes
 
 Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
@@ -475,6 +509,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `IslandInvalidError` | `X_ISLAND_INVALID` | `src/errors.ts` |
 | `IslandNotHydratedError` | `X_ISLAND_NOT_HYDRATED` | `src/errors.ts` |
 | `IslandPropsInvalidError` | `X_ISLAND_PROPS_INVALID` | `src/errors.ts` |
+| `NavigationModalPathInvalidError` | `X_NAVIGATION_MODAL_PATH_INVALID` | `src/navigation-errors.ts` (re-exported by `src/errors.ts`; also on `/client`) |
 | `PrerenderFailedError` | `X_PRERENDER_FAILED` | `src/errors.ts` |
 | `RouteDuplicateError` | `X_ROUTE_DUPLICATE` | `src/errors.ts` |
 | `RouteFileInvalidError` | `X_ROUTE_FILE_INVALID` | `src/errors.ts` |
@@ -488,7 +523,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 
 ## Public API
 
-`†` marks a name on `@ultimat3/render/server`.
+`†` marks a name on `@ultimat3/render/server`; `‡` a name also on `@ultimat3/render/client`.
 
 | Export | Owns |
 |---|---|
@@ -512,6 +547,9 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `ISLAND_HOLD_ATTRIBUTE`, `ISLAND_HOLD_MS`, `ISLAND_HOLD_REVEAL` | a held island's marker, and the cap after which it shows its server markup regardless |
 | `parseByteBudget`, `defaultIslandBudget` | the `'40kb'` budget grammar, and the ceiling a declared island earns |
 | `mergeHead`, `renderHead`, `themeScript` | `<head>` merge + the one inlined script; it stamps `data-theme` and, beside it, the fallback itself as `data-theme-default` for `@ultimat3/ui`'s `clearTheme`/`watchOsTheme` |
+| `clientNavigationTags`, `linkVerdict`, `formVerdict`, `responseVerdict`, `reusable`, `mayPrefetch`, `NAVIGATION_*` (`NAVIGATION_ERROR_EVENT`‡), `NAVIGATE_EVENT`‡, `NAVIGATED_EVENT`‡ | the client router's document tags and its pure rules; the router itself is `@ultimat3/render/navigation`, built and served by the CLI |
+| `navigate`‡, `refresh`‡, `openModal`‡, `closeModal`‡, `NavigateToOptions`‡, `NavigationModalPathInvalidError`‡ | navigating from code: the router when the page has one, the browser's own load when not. Import from `/client` in an island |
+| `modalAddress`, `modalLocation`, `addressOf`, `presentation`, `modalHistory`, `leaveModal`, `NAVIGATION_PRESENTATION_META`, `NAVIGATION_MODAL_ATTRIBUTE` | route-presented modals (`navigation: 'modal'`): the hash grammar, when an answer is a modal, and what leaving one does to history |
 | `clientPathStyleTags`, `CLIENT_PATH_STYLE_META` | `<meta name="ultimate-path-style">` — the action path style the server serves, for the browser's typed client. No tag for `'resource'`, the default |
 
 ## Notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/render",
-  "version": "26.0.0",
+  "version": "26.1.1",
   "description": "The route primitive and the five render modes: static, isr, ssr, stream, spa.",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,7 @@
   },
   "exports": {
     ".": "./src/index.ts",
+    "./client": "./src/client.ts",
     "./server": "./src/server.ts",
     "./navigation": "./src/navigation-entry.ts"
   },
@@ -39,11 +40,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "26.0.0",
-    "@ultimat3/core": "26.0.0",
-    "@ultimat3/http": "26.0.0",
-    "@ultimat3/i18n": "26.0.0",
-    "@ultimat3/seo": "26.0.0",
+    "@ultimat3/cache": "26.1.1",
+    "@ultimat3/core": "26.1.1",
+    "@ultimat3/http": "26.1.1",
+    "@ultimat3/i18n": "26.1.1",
+    "@ultimat3/seo": "26.1.1",
     "sass": "1.105.1"
   }
 }

package/src/client-sync-tags.ts

@@ -11,7 +11,7 @@ export interface ClientSyncHead {
   readonly syncUrl: string;
   readonly buildId: string;
   readonly workerUrl?: string | undefined;
-  /** `/_x/page-boot/<hash>.js` — realtime's page boot, when the app has realtime. */
+  /** `/_x/assets/page-boot/<hash>.js` — realtime's page boot, when the app has realtime. */
   readonly bootUrl?: string | undefined;
 }
 

package/src/client.ts

@@ -0,0 +1,14 @@
+// `@ultimat3/render/client` — THE browser entry of this package: what an island or a page script
+// may call, and nothing that drags the rest along. The `.` barrel bare-retains `errors.ts` (render's
+// whole code table, registered at import, plus core's titles tables); this entry's graph is
+// `navigation-api.ts`, `navigation-errors.ts`, the pure rules and `@ultimat3/core/page`, held there
+// by `client-bundle.test.ts`.
+//
+//   import { navigate, openModal, refresh } from '@ultimat3/render/client';
+//
+// The same names stay exported from `.` for compatibility; an island imports them from here.
+
+export type { NavigateToOptions } from './navigation-api';
+export { closeModal, navigate, openModal, refresh } from './navigation-api';
+export { NavigationModalPathInvalidError } from './navigation-errors';
+export { NAVIGATE_EVENT, NAVIGATED_EVENT, NAVIGATION_ERROR_EVENT } from './navigation-rules';

package/src/errors.ts

@@ -28,6 +28,7 @@ export const RENDER_ERROR_CODES = [
   'X_ASSET_MISSING',
   'X_ROUTE_POST_INVALID',
   'X_ROUTE_NAVIGATION_INVALID',
+  'X_NAVIGATION_MODAL_PATH_INVALID',
 ] as const;
 
 export type RenderErrorCode = (typeof RENDER_ERROR_CODES)[number];
@@ -53,7 +54,9 @@ export const RENDER_ERROR_TITLES: Readonly<Record<RenderErrorCode, string>> = {
   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",
+    "a route's navigation is not 'prefetch', 'document' or 'modal', or its surface has no client navigation",
+  X_NAVIGATION_MODAL_PATH_INVALID:
+    'openModal was given something that is not a path of this origin',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -205,7 +208,8 @@ 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.
+ * `'prefetch'`, `'document'` or `'modal'`, 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;
@@ -213,11 +217,16 @@ export class RouteNavigationInvalidError extends UltimateError {
     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",
+      fix: "defineRoute({ ..., navigation: 'prefetch' | 'document' | 'modal' }) on a page whose surface is listed in app.config.ts navigation.client, or remove the key",
     });
   }
 }
 
+// `openModal(path)` with a path no hash can address on this origin. Re-exported, never re-declared:
+// the class lives in `navigation-errors.ts` so `@ultimat3/render/client` constructs it without this
+// module's table. One class, so `instanceof` holds from either entry.
+export { NavigationModalPathInvalidError } from './navigation-errors';
+
 export class RouteLoadInvalidError extends UltimateError {
   static readonly code = 'X_ROUTE_LOAD_INVALID' as const;
   constructor(cause: string, fix: string) {

package/src/index.ts

@@ -38,6 +38,7 @@ export {
   IslandInvalidError,
   IslandNotHydratedError,
   IslandPropsInvalidError,
+  NavigationModalPathInvalidError,
   PrerenderFailedError,
   RENDER_ERROR_CODES,
   RENDER_ERROR_TITLES,
@@ -106,9 +107,27 @@ export {
   defaultIslandBudget,
   MODE_SPECS,
 } from './modes';
+/**
+ * Navigating from code — through the router when the page has one, the browser's load when not.
+ * Kept here for compatibility; an island imports them from `@ultimat3/render/client` (`client.ts`),
+ * whose graph does not retain this barrel's `errors.ts` and the code tables behind it.
+ */
+export type { NavigateToOptions } from './navigation-api';
+export { closeModal, navigate, openModal, refresh } from './navigation-api';
 /** 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 { Presentation, PresentationFacts } from './navigation-modal-rules';
+export {
+  addressOf,
+  leaveModal,
+  modalAddress,
+  modalHistory,
+  modalLocation,
+  NAVIGATION_MODAL_ATTRIBUTE,
+  NAVIGATION_PRESENTATION_META,
+  presentation,
+} from './navigation-modal-rules';
 export type {
   CachedFacts,
   FormFacts,

package/src/navigation-api.ts

@@ -0,0 +1,84 @@
+/**
+ * Navigating from code: the client router's public face for an island or an app script —
+ * `navigate`, `refresh`, `openModal`, `closeModal`. Each goes through the router when the page
+ * carries one (`window.__xNavigation`, started by `@ultimat3/render/navigation`), and falls back to
+ * what the browser does without it — so the same call is right on a `site/` page, a
+ * `navigation: 'document'` page, or with the router's script blocked. Imports the router's TYPE
+ * only: an island that navigates never ships the router.
+ */
+
+import type { NavigationRouter } from './navigation';
+import { NavigationModalPathInvalidError } from './navigation-errors';
+import { modalAddress } from './navigation-modal-rules';
+
+export interface NavigateToOptions {
+  /** Replace the current history entry instead of pushing one (`location.replace` without the router). */
+  readonly replace?: boolean;
+}
+
+interface NavigationWindow {
+  readonly location: Location;
+  readonly __xNavigation?: NavigationRouter;
+}
+
+/** The page's window, or `undefined` on the server — where there is nothing to navigate. */
+const page = (): NavigationWindow | undefined =>
+  (globalThis as { window?: NavigationWindow }).window;
+
+/**
+ * Go to `url` (resolved against the page) as a click on a link to it would: through the router on
+ * this origin — its own rules and the server's gate decide swap, modal or full load — and as a
+ * document load anywhere else, or when the page has no router.
+ */
+export function navigate(url: string, options: NavigateToOptions = {}): Promise<void> {
+  const win = page();
+  if (win === undefined) return Promise.resolve();
+  const to = new URL(url, win.location.href);
+  const router = win.__xNavigation;
+  if (router === undefined || to.origin !== new URL(win.location.href).origin) {
+    if (options.replace === true) win.location.replace(to.href);
+    else win.location.assign(to.href);
+    return Promise.resolve();
+  }
+  return router.navigate(to.href, options.replace === true ? { history: 'replace' } : {});
+}
+
+/**
+ * The page on screen, rendered again by the server and swapped in where the visitor is scrolled —
+ * after a write the page's own islands do not reflect. Without the router: a reload.
+ */
+export function refresh(): Promise<void> {
+  const win = page();
+  if (win === undefined) return Promise.resolve();
+  if (win.__xNavigation === undefined) {
+    win.location.reload();
+    return Promise.resolve();
+  }
+  return win.__xNavigation.refresh();
+}
+
+/**
+ * Open the `navigation: 'modal'` route at `path` over the page on screen (`#<path>`), pushed so
+ * Back closes it. A path that is not a modal of this tab opens nothing, as a stale hash does.
+ * Without the router: the modal route's own whole page. A path no hash can address (another
+ * origin, `//host`, a relative one) is refused, `X_NAVIGATION_MODAL_PATH_INVALID`.
+ */
+export function openModal(path: string): Promise<void> {
+  const win = page();
+  const base = win?.location.href ?? 'http://localhost/';
+  if (!path.startsWith('/') || modalAddress(`#${path}`, base) === null) {
+    // Rejected, never thrown: one failure channel for an async call — `.catch` sees it.
+    return Promise.reject(new NavigationModalPathInvalidError(path));
+  }
+  if (win === undefined) return Promise.resolve();
+  if (win.__xNavigation === undefined) {
+    win.location.assign(new URL(path, base).href);
+    return Promise.resolve();
+  }
+  return win.__xNavigation.openModal(path);
+}
+
+/** Close the open modal as Escape does. Nothing is open without the router: nothing to do. */
+export function closeModal(): void {
+  page()?.__xNavigation?.closeModal();
+}

package/src/navigation-dom.ts

@@ -4,8 +4,13 @@
  * browser. Split from `navigation.ts` so that file is the controller and nothing else.
  */
 
-import type { LinkFacts } from './navigation-rules';
-import { NAVIGATION_RELOAD_ATTRIBUTE } from './navigation-rules';
+import type { FormFacts, LinkFacts } from './navigation-rules';
+import {
+  linkVerdict,
+  mayPrefetch,
+  NAVIGATION_NO_PREFETCH_ATTRIBUTE,
+  NAVIGATION_RELOAD_ATTRIBUTE,
+} from './navigation-rules';
 
 /** A link as the rules read it; `event` absent for a hover, which is no click at all. */
 export function linkFacts(
@@ -35,6 +40,24 @@ export function anchorOf(target: EventTarget | null): HTMLAnchorElement | HTMLAr
     : null;
 }
 
+/** The URL a hover or focus on `target` may prefetch, or `undefined` (`linkVerdict`, `mayPrefetch`). */
+export function intentUrl(win: Window, target: EventTarget | null): string | undefined {
+  const anchor = anchorOf(target);
+  if (anchor === null) return undefined;
+  const verdict = linkVerdict(linkFacts(win, anchor));
+  if (verdict.kind !== 'soft') return undefined;
+  const connection = (
+    win.navigator as { connection?: { saveData?: boolean; effectiveType?: string } }
+  ).connection;
+  const may = mayPrefetch({
+    url: verdict.url,
+    noPrefetch: anchor.hasAttribute(NAVIGATION_NO_PREFETCH_ATTRIBUTE),
+    saveData: connection?.saveData,
+    effectiveType: connection?.effectiveType,
+  });
+  return may ? verdict.url : undefined;
+}
+
 /** A field as a GET query carries it: a file by its name, as the browser does. */
 export const fieldText = (value: unknown): string =>
   value instanceof File ? value.name : String(value);
@@ -70,6 +93,35 @@ export function formFields(form: HTMLFormElement, submitter: HTMLElement | null)
   }
 }
 
+/** A submit as the rules read it — the submitter's `form*` attributes over the form's — and its fields. */
+export function submitFacts(
+  win: Window,
+  form: HTMLFormElement,
+  submitter: HTMLElement | null,
+  defaultPrevented: boolean,
+): { readonly facts: FormFacts; readonly fields: FormData } {
+  const fields = formFields(form, submitter);
+  const say = (attr: string, fallback: string): string =>
+    submitter?.getAttribute(`form${attr}`) ?? form.getAttribute(attr) ?? fallback;
+  const facts: FormFacts = {
+    action: formAction(say('action', ''), win.location.href, win.document.baseURI),
+    current: win.location.href,
+    method: say('method', 'get').toLowerCase(),
+    enctype: say('enctype', 'application/x-www-form-urlencoded').toLowerCase(),
+    target: say('target', ''),
+    defaultPrevented,
+    reload:
+      form.hasAttribute(NAVIGATION_RELOAD_ATTRIBUTE) ||
+      submitter?.hasAttribute(NAVIGATION_RELOAD_ATTRIBUTE) === true,
+    // `unknown`: a browser yields a `File` for a file input, whatever a server-side type says.
+    hasFile: [...fields.values()].some(
+      (value: unknown) => value instanceof File && value.name !== '',
+    ),
+    fields: formPairs(fields),
+  };
+  return { facts, fields };
+}
+
 const hush = (): void => undefined;
 
 /**

package/src/navigation-errors.ts

@@ -0,0 +1,21 @@
+/**
+ * The one refusal a BROWSER can reach in this package — `openModal`'s — apart from `errors.ts` for
+ * bytes: that module registers render's whole code table at import, and an island that calls
+ * `openModal` must not carry it. `errors.ts` re-exports this class, so it is ONE class wherever it is
+ * imported from and `instanceof` agrees across both entries. Without the table loaded, core titles
+ * the code from its name; the code, cause and fix are the same either way. Runs nothing at import.
+ */
+
+import { UltimateError } from '@ultimat3/core/page';
+
+/** `openModal` was handed something no `#<path>` hash can address. Rejected, never thrown. */
+export class NavigationModalPathInvalidError extends UltimateError {
+  static readonly code = 'X_NAVIGATION_MODAL_PATH_INVALID' as const;
+  constructor(path: string) {
+    super({
+      code: NavigationModalPathInvalidError.code,
+      cause: `openModal(${JSON.stringify(path)}): a modal is addressed by '#<path>', and this is not an absolute path on this origin`,
+      fix: "openModal('/runs/new') — the modal route's own path, as its link carries it; never a full URL or a relative one",
+    });
+  }
+}

package/src/navigation-fetch.ts

@@ -14,7 +14,8 @@ import {
   CLIENT_NAVIGATION_SURFACE_HEADER,
   CLIENT_SCOPE_META,
 } from '@ultimat3/core/page';
-import { NAVIGATION_META } from './navigation-rules';
+import type { NavigationCache } from './navigation-cache';
+import { NAVIGATION_META, type ResponseFacts, reusable } from './navigation-rules';
 
 /** One fetched answer, read once — a prefetch and the click after it share it. */
 export interface Answer {
@@ -85,3 +86,53 @@ export function fetchDocument(
       };
     });
 }
+
+/**
+ * A GET's answer: the prefetch held for `url` when it may stand in for the click (`reusable`), else
+ * `fetchAgain()`. Taken out of the cache either way — a held answer answers one click.
+ */
+export function heldOrFetched(
+  cache: NavigationCache<Answer>,
+  url: string,
+  fetchAgain: () => Promise<Answer>,
+): Promise<Answer> {
+  const held = cache.peek(url);
+  cache.delete(url);
+  if (held === undefined) return fetchAgain();
+  return held.value.then(
+    (answer) =>
+      reusable({
+        status: answer.status,
+        html: answer.html !== null,
+        location: answer.location,
+        noStore: answer.noStore,
+        ageMs: held.ageMs,
+      })
+        ? answer
+        : fetchAgain(),
+    fetchAgain,
+  );
+}
+
+/** What `responseVerdict` reads, off the answer, this document and the next one. */
+export function responseFactsOf(
+  doc: Document,
+  next: Document | null,
+  answer: Answer,
+  asked: Pick<ResponseFacts, 'method' | 'requested' | 'hops'>,
+): ResponseFacts {
+  const nextMeta = (name: string): string | null => (next === null ? null : metaOf(next, name));
+  return {
+    ...asked,
+    status: answer.status,
+    opaqueRedirect: answer.opaqueRedirect,
+    location: answer.location,
+    contentType: answer.contentType,
+    surface: metaOf(doc, NAVIGATION_META),
+    nextSurface: nextMeta(NAVIGATION_META),
+    build: metaOf(doc, CLIENT_BUILD_META),
+    nextBuild: answer.build ?? nextMeta(CLIENT_BUILD_META),
+    scope: metaOf(doc, CLIENT_SCOPE_META),
+    nextScope: nextMeta(CLIENT_SCOPE_META),
+  };
+}

package/src/navigation-history.ts

@@ -12,6 +12,8 @@ export interface EntryState {
   readonly scroll: readonly [number, number];
   /** The document this entry shows — what back/forward compares with the one on screen. */
   readonly doc: string;
+  /** The modal open over `doc` (`navigation-modal-rules.ts`), on an entry this router pushed. */
+  readonly modal?: string;
 }
 
 /** Back/forward, as the router passes it: `none` restores; the others start at the top. */
@@ -38,7 +40,12 @@ export function saveEntryScroll(win: Window, rendered: string): void {
   const state = (win.history.state ?? {}) as Record<string, unknown>;
   const held = entryOf(state)?.doc;
   if (held !== undefined && held !== rendered) return;
-  const entry: EntryState = { scroll: [win.scrollX, win.scrollY], doc: held ?? rendered };
+  // Spread: the entry's modal mark is what lets Escape go Back (`navigation-modal.ts`).
+  const entry: EntryState = {
+    ...entryOf(state),
+    scroll: [win.scrollX, win.scrollY],
+    doc: held ?? rendered,
+  };
   win.history.replaceState({ ...state, [STATE_KEY]: entry }, '');
 }
 

package/src/navigation-modal-rules.ts

@@ -0,0 +1,110 @@
+/**
+ * Route-presented modals, as pure rules: the hash grammar (`/runs#/runs/new` — the PATH is the page
+ * on screen, the HASH is the one modal over it), whether an answer is shown as a modal, as the page,
+ * or dropped back to "just the page", and what leaving a modal does to history. The controller
+ * (`navigation-modal.ts`) only gathers the facts; every rule is testable without a DOM.
+ */
+
+import type { ResponseVerdict } from './navigation-rules';
+
+/**
+ * `<meta name="ultimate-presentation" content="modal">` — on the document of a route that declared
+ * `navigation: 'modal'`. The SERVER's word that this page is presented over another: the router
+ * never decides it from a link, so a redirect target and a hand-typed hash are answered alike.
+ */
+export const NAVIGATION_PRESENTATION_META = 'ultimate-presentation';
+/** On the `<dialog>` the router opens. `@ultimat3/ui`'s `global.scss` styles it, by this name. */
+export const NAVIGATION_MODAL_ATTRIBUTE = 'data-x-modal';
+
+/**
+ * The modal a hash addresses — `#/runs/new?x=1` → `/runs/new?x=1` — or `null` for every other
+ * fragment (`#below`, `#`, `#//host`, one that leaves the origin). NEVER throws: a stale or
+ * hand-edited hash degrades to "just the page", it is never an error.
+ */
+export function modalAddress(hash: string, base: string): string | null {
+  // `#//host` would resolve to another origin; a backslash is a slash to the URL parser.
+  if (!hash.startsWith('#/') || hash.startsWith('#//') || hash.includes('\\')) return null;
+  const said = hash.slice(1);
+  if (!URL.canParse(base) || !URL.canParse(said, base)) return null;
+  const url = new URL(said, base);
+  if (url.origin !== new URL(base).origin) return null;
+  return `${url.pathname}${url.search}`;
+}
+
+/** The URL the address bar shows for `address` over the page `page`: `/runs#/runs/new`. */
+export const modalLocation = (page: string, address: string): string =>
+  `${page.split('#')[0] ?? page}#${address}`;
+
+/** `/runs/new?x=1` of an absolute URL — the hash a modal at that URL is addressed by. */
+export const addressOf = (url: string): string => {
+  const parsed = new URL(url);
+  return `${parsed.pathname}${parsed.search}`;
+};
+
+/**
+ * - `modal`: shown in the dialog over the page on screen.
+ * - `page`: the router's ordinary handling (a swap, a follow, a load…).
+ * - `degrade`: the hash named something that is not a modal for this tab — the hash is dropped in
+ *   place and the page stays, with nothing loaded, followed or shown as an error.
+ */
+export type Presentation = 'modal' | 'page' | 'degrade';
+
+/** What decides a presentation, read off the answer, the tab and how the request came about. */
+export interface PresentationFacts {
+  /** The address came from the URL's hash (a load, Back/Forward, a typed hash), not a click. */
+  readonly fromHash: boolean;
+  readonly method: 'GET' | 'POST';
+  readonly verdict: ResponseVerdict['kind'];
+  readonly status: number;
+  /** The answer carries `NAVIGATION_PRESENTATION_META` = `modal`. */
+  readonly modalPage: boolean;
+  /** A modal is open now. */
+  readonly modalOpen: boolean;
+  /** The answered URL, and the page on screen — both without a fragment. */
+  readonly landed: string;
+  readonly rendered: string;
+  /** The answer belongs to another principal or build (`answerMovesTab`). */
+  readonly movesTab: boolean;
+}
+
+export function presentation(facts: PresentationFacts): Presentation {
+  const modal = facts.verdict === 'swap' && facts.modalPage && !facts.movesTab;
+  // From the hash, only a 2xx modal of this tab opens; anything else (a 404, a redirect, a page that
+  // is not a modal, another principal) is a stale address — never followed, never loaded.
+  if (facts.fromHash) {
+    return modal && facts.status >= 200 && facts.status < 300 ? 'modal' : 'degrade';
+  }
+  if (!modal) return 'page';
+  // A POST re-renders a modal only from inside one: the full page's own form stays a page.
+  if (facts.method === 'POST') return facts.modalOpen ? 'modal' : 'page';
+  // A link to the page on screen is that page, whatever it declared.
+  return facts.landed === facts.rendered ? 'page' : 'modal';
+}
+
+/**
+ * The history move for a modal shown: a POST answered in place re-renders it where it is (the
+ * entry is the modal's already); Back/Forward and a hash move nothing; a click pushes, so Back
+ * steps out of it (nesting deeper is a deeper path in the same dialog, with its own Back stop).
+ */
+export function modalHistory(
+  method: 'GET' | 'POST',
+  history: 'push' | 'replace' | 'none' | undefined,
+): 'push' | 'replace' | 'none' {
+  if (history === 'none') return 'none';
+  return method === 'POST' ? 'replace' : (history ?? 'push');
+}
+
+/**
+ * Leaving an open modal for a PAGE: the modal's entry is never left behind to reopen a spent form
+ * on Back. Onto the page beneath, through an entry this router pushed: Back to it (two entries for
+ * one URL read as a Back that did nothing). Anywhere else: the modal's entry is replaced.
+ */
+export function leaveModal(facts: {
+  readonly history: 'push' | 'replace' | 'none' | undefined;
+  readonly landed: string;
+  readonly rendered: string;
+  readonly owned: boolean;
+}): 'back' | 'replace' | 'none' {
+  if (facts.history === 'none') return 'none';
+  return facts.landed === facts.rendered && facts.owned ? 'back' : 'replace';
+}