@ultimat3/render 29.0.0 → 29.1.0

package/CLAUDE.md

@@ -30,7 +30,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 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`. |
+| `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`, the twelfth — `route-navigation.ts`, read only through `navigationModeOf`/`navigationPrefetches`; 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`. |
@@ -115,10 +115,11 @@ axiom 6). Never `cli` (upward).
 | 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. 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`. |
+| Modal on the click | `navigation-modal-frame.ts`: `modal.loading(url)` in `navigate`'s synchronous prefix opens the frame off `NAVIGATION_MODALS_META`; the answer's meta still decides. Closing aborts (`abandon`); the router `release()`s before its own dismissals; `settle()` in `finally`. Never `showModal()` where popovers exist, never a toggle on `<html>`/`<body>` ([why](../../docs/history/render.md#the-modal-that-opens-on-the-click)) |
 | 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. |
-| Router: nothing is sent twice | every router fetch is `cache: 'no-cache'` — the browser's HTTP cache never answers, the router's own is the only reuse layer (#693; `navigation-fetch.test.ts`, `client-navigation-cache.e2e.test.ts`). 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 2xx non-page answer to the browser from the bytes it already has. A 4xx/5xx non-page answer (an offline worker's empty 503) is never handed over (it became a `blob:` URL): a POST fails, a GET is loaded by the browser — the ONE deliberate re-send, as there is nothing to show (`responseVerdict`). 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 (when sent AND when it settles), `onClientWrite`, `onRescope` and a `BroadcastChannel` message from another tab. |
+| Router: nothing is sent twice | every fetch `cache: 'no-cache'` (#693), `redirect: 'manual'`, a POST never re-sent; the cache answers only a reusable 2xx and is emptied by every write signal ([full rule](../../docs/history/render.md#router-nothing-is-sent-twice)) |
 
 Cross-package: `@ultimat3/pwa` consumes route descriptors as **data**, never by import.
 Keep `RouteDescriptor` additive — removing a field breaks `sw.js` generation.

package/README.md

@@ -144,7 +144,20 @@ On a surface listed in `app.config.ts`'s `navigation.client` only (elsewhere it
 |---|---|
 | `'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`) |
+| `'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`). Never prefetched |
+| `{ modal: true, prefetch: 'intent' }` | `As of 29.1.0`. A `'modal'` whose GET only reads (a peek, a detail view): also fetched on hover/focus/touchstart, as `'prefetch'` is. Exactly these two keys and values (`isRouteNavigation`); read it with `navigationModeOf` / `navigationPrefetches`, never by comparing against a string |
+
+**A modal opens on the click** (`As of 29.1.0`). Every document of a surface with a modal route
+names those routes (`<meta name="ultimate-modals">`, `modalRouteList` — most specific first, with
+the pages that outrank one as `!<pattern>`) and the frame's words in its locale (`ui.close`,
+`ui.loading`). A click on a link to one, `openModal(path)` or a hash addressing one opens the
+dialog in the same task: `[data-x-modal-body][aria-busy="true"]` with a skeleton, and a close button
+(`[data-x-modal-close]`, a `type="button"`, never a `<form>`). The answer fills it; closing it first aborts
+the request and pushes nothing; an answer that is no modal takes it down and is handled as before.
+The dialog is opened with `show()` + `showPopover()`, never `showModal()`, whose inert document
+restyles every element beneath (124 ms of RecalcStyle on a 7,011-element page at 4x CPU, against
+2.6 ms) — `aria-modal`, focus containment and Escape are the router's. Numbers and rules:
+[Client Navigation](../../wiki/Client-Navigation.md#opening-on-the-click).
 
 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.
@@ -581,6 +594,8 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `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 |
 | `disposeIslands` (on `/client` only) | dispose the islands mounted under an element: what the router does on a swap, for an island that drops markup holding other islands |
 | `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 |
+| `declaresModal`, `parseModalRoutes`, `modalRouteList`, `ModalRoutes`, `NAVIGATION_MODALS_META`, `NAVIGATION_MODAL_BODY_ATTRIBUTE`, `NAVIGATION_MODAL_CLOSE_ATTRIBUTE`, `NAVIGATION_MODAL_SKELETON_ATTRIBUTE` | the modal that opens on the click: the meta naming a surface's modal routes (composed by the server, read by the router) and the frame's attributes, styled by `@ultimat3/ui` |
+| `isRouteNavigation`, `navigationModeOf`, `navigationPrefetches`, `RouteNavigationDeclaration`, `RouteModalPrefetch` | `navigation:` read back: the four spellings, which mode, prefetched or not |
 | `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": "29.0.0",
+  "version": "29.1.0",
   "description": "The route primitive and the five render modes: static, isr, ssr, stream, spa.",
   "license": "MIT",
   "type": "module",
@@ -40,11 +40,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "29.0.0",
-    "@ultimat3/core": "29.0.0",
-    "@ultimat3/http": "29.0.0",
-    "@ultimat3/i18n": "29.0.0",
-    "@ultimat3/seo": "29.0.0",
+    "@ultimat3/cache": "29.1.0",
+    "@ultimat3/core": "29.1.0",
+    "@ultimat3/http": "29.1.0",
+    "@ultimat3/i18n": "29.1.0",
+    "@ultimat3/seo": "29.1.0",
     "sass": "1.105.1"
   }
 }

package/src/errors.ts

@@ -54,7 +54,7 @@ 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', 'document' or 'modal', or its surface has no client navigation",
+    "a route's navigation is not 'prefetch', 'document', 'modal' or { modal: true, prefetch: 'intent' }, or its surface has no client navigation",
   X_NAVIGATION_MODAL_PATH_INVALID:
     'openModal was given something that is not a path of this origin',
 };
@@ -208,8 +208,8 @@ export class RoutePostInvalidError extends UltimateError {
 
 /**
  * `defineRoute({ navigation })` that says nothing a process can honour: a value other than
- * `'prefetch'`, `'document'` or `'modal'`, or — at boot — a page whose surface has no client
- * navigation.
+ * `'prefetch'`, `'document'`, `'modal'` or `{ modal: true, prefetch: 'intent' }`, 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;
@@ -217,7 +217,7 @@ export class RouteNavigationInvalidError extends UltimateError {
     super({
       code: RouteNavigationInvalidError.code,
       cause,
-      fix: "defineRoute({ ..., navigation: 'prefetch' | 'document' | 'modal' }) on a page whose surface is listed in app.config.ts navigation.client, or remove the key",
+      fix: "defineRoute({ ..., navigation: 'prefetch' | 'document' | 'modal' | { modal: true, prefetch: 'intent' } }) on a page whose surface is listed in app.config.ts navigation.client, or remove the key",
     });
   }
 }

package/src/index.ts

@@ -117,15 +117,21 @@ 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 type { ModalRoutes, Presentation, PresentationFacts } from './navigation-modal-rules';
 export {
   addressOf,
+  declaresModal,
   leaveModal,
   modalAddress,
   modalHistory,
   modalLocation,
   NAVIGATION_MODAL_ATTRIBUTE,
+  NAVIGATION_MODAL_BODY_ATTRIBUTE,
+  NAVIGATION_MODAL_CLOSE_ATTRIBUTE,
+  NAVIGATION_MODAL_SKELETON_ATTRIBUTE,
+  NAVIGATION_MODALS_META,
   NAVIGATION_PRESENTATION_META,
+  parseModalRoutes,
   presentation,
 } from './navigation-modal-rules';
 export type {
@@ -160,7 +166,7 @@ export {
   reusable,
 } from './navigation-rules';
 export type { ClientNavigationHead } from './navigation-tags';
-export { clientNavigationTags } from './navigation-tags';
+export { clientNavigationTags, modalRouteList } from './navigation-tags';
 export type {
   MountedRouteInput,
   RegisterRouteInput,
@@ -200,18 +206,23 @@ export type {
   RouteMetaAsyncFn,
   RouteMetaContext,
   RouteMetaFn,
-  RouteNavigationMode,
   RouteParams,
 } from './route';
-export {
-  DEFAULT_ISLAND_HYDRATE,
-  defineRoute,
-  isRouteConfig,
-  ROUTE_NAVIGATION_MODES,
-} from './route';
+export { DEFAULT_ISLAND_HYDRATE, defineRoute, isRouteConfig } from './route';
 export type { RouteComponent } from './route-component';
 export { pageComponentOf } from './route-component';
 export { metaContextFor, routeDataFor } from './route-data';
+export type {
+  RouteModalPrefetch,
+  RouteNavigationDeclaration,
+  RouteNavigationMode,
+} from './route-navigation';
+export {
+  isRouteNavigation,
+  navigationModeOf,
+  navigationPrefetches,
+  ROUTE_NAVIGATION_MODES,
+} from './route-navigation';
 export type { CompiledPattern } from './route-pattern';
 export { compilePattern } from './route-pattern';
 export { noStore, routeNoStoreOf, routeStatusOf, withStatus } from './route-status';

package/src/navigation-modal-frame.ts

@@ -0,0 +1,159 @@
+/**
+ * The route-presented modal's `<dialog>` as DOM: its frame (a body region, a close button), how it
+ * is opened into the top layer and kept modal, and where focus goes. `navigation-modal.ts` decides
+ * when; this file only builds, opens, fills and hides.
+ *
+ * Opened with `show()` + `showPopover()`, NOT `showModal()`: a modal dialog makes the rest of the
+ * document inert, and Chrome computes inertness in style — every element of the page beneath has
+ * its style recalculated (7,011 elements, 4x CPU: 124 ms of RecalcStyle for `showModal()`, 2.6 ms
+ * this way; `inert` on one wrapper costs the same 111 ms). The popover is the top layer and the
+ * `::backdrop`; `aria-modal` tells assistive technology the page beneath is out of reach; the
+ * backdrop takes every press, and Tab wraps inside. A browser without popovers gets `showModal()`.
+ */
+
+import {
+  type ModalRoutes,
+  NAVIGATION_MODAL_ATTRIBUTE,
+  NAVIGATION_MODAL_BODY_ATTRIBUTE,
+  NAVIGATION_MODAL_CLOSE_ATTRIBUTE,
+  NAVIGATION_MODAL_SKELETON_ATTRIBUTE,
+} from './navigation-modal-rules';
+
+export type ModalLabels = Pick<ModalRoutes, 'close' | 'loading'>;
+
+/** What may take focus inside the dialog — filtered for `disabled` and `tabindex="-1"` below. */
+const FOCUSABLE =
+  'a[href], area[href], button, input, select, textarea, [tabindex], [contenteditable]';
+
+const supportsPopover = (el: HTMLElement): boolean =>
+  typeof (el as { showPopover?: unknown }).showPopover === 'function';
+
+/** The region the modal page's `<main>` goes in. */
+export const bodyOf = (dialog: HTMLDialogElement): Element =>
+  dialog.querySelector(`[${NAVIGATION_MODAL_BODY_ATTRIBUTE}]`) ?? dialog;
+
+/**
+ * A dialog with its body region and, when the document named the words for it, its close button:
+ * a plain `type="button"` that closes as Escape does (`onClose`) — never a `<form>`, which a page's
+ * own `dialog form` would find first. AFTER the body, so the first focusable thing is the page's.
+ */
+export function createModal(
+  doc: Document,
+  labels: ModalLabels | undefined,
+  onClose: () => void,
+): HTMLDialogElement {
+  const dialog = doc.createElement('dialog');
+  dialog.setAttribute(NAVIGATION_MODAL_ATTRIBUTE, '');
+  // Light dismiss: Escape AND a press outside close it, as every modal does (`Dialog` included).
+  dialog.setAttribute('closedby', 'any');
+  dialog.setAttribute('aria-modal', 'true');
+  // Focusable itself, so focus is inside from the first frame — before there is content to take it.
+  dialog.setAttribute('tabindex', '-1');
+  const body = doc.createElement('div');
+  body.setAttribute(NAVIGATION_MODAL_BODY_ATTRIBUTE, '');
+  dialog.append(body);
+  if (labels !== undefined) {
+    const close = doc.createElement('button');
+    close.setAttribute('type', 'button');
+    close.setAttribute(NAVIGATION_MODAL_CLOSE_ATTRIBUTE, '');
+    close.setAttribute('aria-label', labels.close);
+    close.addEventListener('click', onClose);
+    dialog.append(close);
+  }
+  return dialog;
+}
+
+/** The body as "on its way": busy, a skeleton in place of content that is not there yet. */
+export function markBusy(dialog: HTMLDialogElement, empty: boolean): void {
+  const body = bodyOf(dialog);
+  body.setAttribute('aria-busy', 'true');
+  if (!empty) return;
+  const skeleton = dialog.ownerDocument.createElement('div');
+  skeleton.setAttribute(NAVIGATION_MODAL_SKELETON_ATTRIBUTE, '');
+  skeleton.setAttribute('aria-hidden', 'true');
+  body.replaceChildren(skeleton);
+}
+
+export const markIdle = (dialog: HTMLDialogElement): void =>
+  bodyOf(dialog).removeAttribute('aria-busy');
+
+/** Into the top layer, without the inert document (see the header); `showModal()` without popovers. */
+export function raiseModal(dialog: HTMLDialogElement): void {
+  if (!supportsPopover(dialog)) {
+    dialog.showModal();
+    return;
+  }
+  dialog.setAttribute('popover', 'manual');
+  dialog.show();
+  dialog.showPopover();
+}
+
+/** Out of the top layer: the popover first, so no frame shows a backdrop over nothing. */
+export function lowerModal(dialog: HTMLDialogElement): void {
+  if (dialog.hasAttribute('popover') && supportsPopover(dialog)) {
+    try {
+      dialog.hidePopover();
+    } catch {
+      // Already hidden (removed, or hidden by the browser): nothing is showing.
+    }
+  }
+  if (dialog.open) dialog.close();
+}
+
+const focusable = (dialog: HTMLDialogElement): HTMLElement[] =>
+  [...dialog.querySelectorAll(FOCUSABLE)].filter(
+    (el) =>
+      !el.hasAttribute('disabled') &&
+      el.getAttribute('tabindex') !== '-1' &&
+      el.getAttribute('type') !== 'hidden',
+  ) as HTMLElement[];
+
+/** As `showModal()` focuses: `[autofocus]`, else the first focusable thing, else the dialog. */
+export function focusInto(dialog: HTMLDialogElement): void {
+  const target =
+    (dialog.querySelector('[autofocus]') as HTMLElement | null) ?? focusable(dialog)[0] ?? dialog;
+  target.focus?.({ preventScroll: true });
+}
+
+/**
+ * What `showModal()` gave for free and a popover does not: Tab stays inside, and — where the
+ * browser has no `closedby` — Escape closes. Returns the remover. Escape on something that is
+ * itself a dialog or popover inside (a `Dialog`, a menu) is that one's.
+ */
+export function keepModal(
+  doc: Document,
+  dialog: HTMLDialogElement,
+  onEscape: () => void,
+): () => void {
+  if (!dialog.hasAttribute('popover')) return () => undefined;
+  const escapes = !('closedBy' in dialog);
+  const onKey = (event: KeyboardEvent): void => {
+    if (event.defaultPrevented) return;
+    const at = event.target as Element | null;
+    const inner = at?.closest?.('dialog[open], [popover]') ?? null;
+    if (event.key === 'Escape' && escapes && (inner === null || inner === dialog)) {
+      event.preventDefault();
+      onEscape();
+      return;
+    }
+    if (event.key !== 'Tab' || (inner !== null && inner !== dialog)) return;
+    const all = focusable(dialog);
+    const first = all[0];
+    const last = all[all.length - 1];
+    if (first === undefined || last === undefined) {
+      event.preventDefault();
+      dialog.focus();
+      return;
+    }
+    const active = doc.activeElement;
+    const inside = active !== null && dialog.contains(active);
+    if (
+      event.shiftKey ? !inside || active === first || active === dialog : !inside || active === last
+    ) {
+      event.preventDefault();
+      (event.shiftKey ? last : first).focus();
+    }
+  };
+  doc.addEventListener('keydown', onKey as EventListener);
+  return () => doc.removeEventListener('keydown', onKey as EventListener);
+}

package/src/navigation-modal-rules.ts

@@ -16,6 +16,81 @@ 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';
 
+/**
+ * `<meta name="ultimate-modals" content='{"routes":[…],"close":"…","loading":"…"}'>` — on every
+ * opted-in document of a surface with a `navigation: 'modal'` route: the patterns of the routes
+ * that present as a modal, so a click opens the dialog BEFORE their document arrives, and the
+ * frame's two words in the document's own locale. Still not the router's decision: the answer's
+ * `NAVIGATION_PRESENTATION_META` is, and an answer that is no modal takes the frame down.
+ */
+export const NAVIGATION_MODALS_META = 'ultimate-modals';
+/** The dialog's content region; `aria-busy="true"` on it while the modal's document is on its way. */
+export const NAVIGATION_MODAL_BODY_ATTRIBUTE = 'data-x-modal-body';
+/** The placeholder inside a busy body: no words, so nothing to translate; hidden from AT. */
+export const NAVIGATION_MODAL_SKELETON_ATTRIBUTE = 'data-x-modal-skeleton';
+/** The frame's close button — a `<form method="dialog">` button, so it closes without the router. */
+export const NAVIGATION_MODAL_CLOSE_ATTRIBUTE = 'data-x-modal-close';
+
+/** What the modals meta says. `routes`: most specific first; a `!` prefix is a page that is not. */
+export interface ModalRoutes {
+  readonly routes: readonly string[];
+  /** The close button's accessible name. */
+  readonly close: string;
+  /** The busy dialog's accessible name until the modal's own heading names it. */
+  readonly loading: string;
+}
+
+/** The meta's content read back, or `undefined` for anything malformed — never a throw. */
+export function parseModalRoutes(content: string | null): ModalRoutes | undefined {
+  if (content === null) return undefined;
+  let said: unknown;
+  try {
+    said = JSON.parse(content);
+  } catch {
+    return undefined;
+  }
+  if (typeof said !== 'object' || said === null) return undefined;
+  const { routes, close, loading } = said as Record<string, unknown>;
+  if (!Array.isArray(routes) || !routes.every((r) => typeof r === 'string')) return undefined;
+  if (typeof close !== 'string' || typeof loading !== 'string') return undefined;
+  return { routes, close, loading };
+}
+
+/** One pattern (`/runs/:id/peek`, `/docs/*rest`) against a pathname's decoded segments. */
+function patternMatches(pattern: string, segments: readonly string[]): boolean {
+  const parts = pattern.split('/').filter((part) => part.length > 0);
+  for (const [i, part] of parts.entries()) {
+    if (part.startsWith('*')) return true;
+    const segment = segments[i];
+    if (segment === undefined) return false;
+    if (!part.startsWith(':') && part !== segment) return false;
+  }
+  return parts.length === segments.length;
+}
+
+/**
+ * Whether `url`'s path is a route the meta names a modal: the FIRST pattern that matches decides,
+ * as the list is most specific first — a more specific page (`!/runs/new`) beats `/runs/:id`.
+ * A path that does not decode is no modal: the router then waits for the answer, as before.
+ */
+export function declaresModal(url: string, routes: readonly string[]): boolean {
+  if (!URL.canParse(url)) return false;
+  let segments: string[];
+  try {
+    segments = new URL(url).pathname
+      .split('/')
+      .filter((segment) => segment.length > 0)
+      .map(decodeURIComponent);
+  } catch {
+    return false;
+  }
+  for (const route of routes) {
+    const not = route.startsWith('!');
+    if (patternMatches(not ? route.slice(1) : route, segments)) return !not;
+  }
+  return false;
+}
+
 /**
  * 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

package/src/navigation-modal.ts

@@ -1,21 +1,36 @@
 /**
  * The route-presented modal: ONE native `<dialog>` over the page on screen, holding the `<main>` of
  * a page whose route declared `navigation: 'modal'`. The page beneath is never touched — its
- * islands, socket and state stay live, `showModal()` makes it inert — and the modal is addressed by
- * the URL's hash (`/runs#/runs/new`), so a reload, Back/Forward and a pasted link reopen it.
- * `navigation.ts` decides WHEN (`navigation-modal-rules.ts`); this file only shows and hides.
+ * islands, socket and state stay live, out of reach behind the top layer — and the modal is
+ * addressed by the URL's hash (`/runs#/runs/new`), so a reload, Back/Forward and a pasted link
+ * reopen it. A route the document names a modal (`NAVIGATION_MODALS_META`) opens on the click, as a
+ * busy frame the answer fills. `navigation.ts` decides WHEN (`navigation-modal-rules.ts`); this
+ * file only shows and hides, and `navigation-modal-frame.ts` is the dialog's DOM.
  */
 
 import { disposeIslands } from './island-dispose';
 import { metaOf } from './navigation-fetch';
 import { entryOf, STATE_KEY, withoutFragment } from './navigation-history';
 import {
+  bodyOf,
+  createModal,
+  focusInto,
+  keepModal,
+  lowerModal,
+  type ModalLabels,
+  markBusy,
+  markIdle,
+  raiseModal,
+} from './navigation-modal-frame';
+import {
+  declaresModal,
   leaveModal,
   modalLocation,
-  NAVIGATION_MODAL_ATTRIBUTE,
+  NAVIGATION_MODALS_META,
   NAVIGATION_PRESENTATION_META,
   type Presentation,
   type PresentationFacts,
+  parseModalRoutes,
   presentation,
 } from './navigation-modal-rules';
 import { runScripts } from './navigation-swap';
@@ -43,6 +58,16 @@ export interface ModalController {
     landed: string,
     history: 'push' | 'replace' | 'none',
   ): Promise<void>;
+  /**
+   * A GET of `url` is starting: when the document names it a modal, the dialog opens NOW — a busy
+   * frame, or the open modal marked busy — and `true` is answered. Nothing is pushed until
+   * `present`; closing it before then aborts the request (the controller's `abandon`).
+   */
+  loading(url: string): boolean;
+  /** A newer navigation took over: the frame is no longer this request's to abort. */
+  release(): void;
+  /** The request ended without `present`: a frame with no content goes, an open modal is idle. */
+  settle(): void;
   /** Escape, a native close, a link to the page beneath: Back when this router pushed the entry. */
   close(): void;
   /** The hash names no modal for this tab: dropped in place, the page stays. */
@@ -71,23 +96,33 @@ function rebase(root: Element, landed: string): void {
 
 /** Named by its first heading, as `@ultimat3/ui`'s `Dialog` is by its title. */
 function label(dialog: HTMLDialogElement, title: string): void {
-  const heading = dialog.querySelector('h1, h2');
+  const heading = bodyOf(dialog).querySelector('h1, h2');
   if (heading === null) {
+    dialog.removeAttribute('aria-labelledby');
     dialog.setAttribute('aria-label', title);
     return;
   }
   if (heading.id === '') heading.id = 'x-modal-title';
+  dialog.removeAttribute('aria-label');
   dialog.setAttribute('aria-labelledby', heading.id);
 }
 
+/**
+ * `abandon` aborts the request a frame is waiting on — called when the visitor closes it (Escape,
+ * the close button, Back) before its answer arrived, never when the router itself moves on.
+ */
 export function modalController(
   win: Window,
   rendered: () => string,
   ran: Set<string>,
   head: WeakSet<Element>,
+  abandon: () => void = () => undefined,
 ): ModalController {
   const doc = win.document;
   let dialog: HTMLDialogElement | undefined;
+  /** A request is on its way to fill the dialog: closing it now aborts that request. */
+  let pending = false;
+  let unkeep: () => void = () => undefined;
   /** The open modal's path (`/runs/new`), as the URL bar shows it. */
   let openAt: string | undefined;
   let opener: Element | null = null;
@@ -102,13 +137,18 @@ export function modalController(
   };
 
   const dismiss = (): void => {
+    if (pending) {
+      pending = false;
+      abandon();
+    }
     const open = dialog;
     if (open === undefined) return;
     dialog = undefined;
     openAt = undefined;
     leaving = false;
+    unkeep();
     disposeIslands(open);
-    if (open.open) open.close();
+    lowerModal(open);
     open.remove();
     doc.title = title;
     // Back where the visitor was: the link or button that opened it, when it is still there.
@@ -127,6 +167,15 @@ export function modalController(
   };
 
   const close = (): void => {
+    // A frame with no content yet: nothing was pushed, so closing is the request abandoned.
+    if (openAt === undefined && pending) {
+      dismiss();
+      return;
+    }
+    if (pending) {
+      pending = false;
+      abandon();
+    }
     if (openAt === undefined || leaving) return;
     if (owned()) {
       leaving = true;
@@ -145,7 +194,10 @@ export function modalController(
   // A `<form method="dialog">`, or an Escape the browser would not let be cancelled: the dialog
   // closed itself, and the URL must follow. One it closed for `dismiss` is no longer `dialog`.
   const onClose = (event: Event): void => {
-    if (event.target === dialog && dialog !== undefined && !dialog.open) close();
+    if (event.target !== dialog || dialog === undefined || dialog.open) return;
+    // Closed by the browser, still a popover: out of the top layer now, not when history settles.
+    lowerModal(dialog);
+    close();
   };
   // A press on the backdrop. `closedby="any"` has the browser close the dialog itself (and fire
   // `close`, read above); a browser without it reports the press as a click whose target is the
@@ -171,6 +223,45 @@ export function modalController(
     if (began && outside(event)) close();
   };
 
+  /** A new dialog, its listeners, opened into the top layer: the page's title and focus kept. */
+  const raise = (labels: ModalLabels | undefined): HTMLDialogElement => {
+    opener = doc.activeElement;
+    title = doc.title;
+    const open = createModal(doc, labels, () => close());
+    open.addEventListener('cancel', onCancel);
+    open.addEventListener('close', onClose);
+    open.addEventListener('pointerdown', onPointerDown);
+    open.addEventListener('click', onClick);
+    doc.body.append(open);
+    raiseModal(open);
+    unkeep = keepModal(doc, open, close);
+    return open;
+  };
+
+  const loading = (url: string): boolean => {
+    const named = parseModalRoutes(metaOf(doc, NAVIGATION_MODALS_META));
+    if (named === undefined || !declaresModal(url, named.routes)) return false;
+    pending = true;
+    if (dialog !== undefined) {
+      // One modal at a time: the open one stays on screen, busy, until the next one replaces it.
+      markBusy(dialog, false);
+      return true;
+    }
+    dialog = raise(named);
+    markBusy(dialog, true);
+    dialog.setAttribute('aria-label', named.loading);
+    // Inside from the first frame: Escape, Tab and a screen reader are already the dialog's.
+    dialog.focus({ preventScroll: true });
+    return true;
+  };
+
+  const settle = (): void => {
+    pending = false;
+    if (dialog === undefined) return;
+    if (openAt === undefined) dismiss();
+    else markIdle(dialog);
+  };
+
   const present = async (
     next: Document,
     at: string,
@@ -183,34 +274,26 @@ export function modalController(
     rebase(source, landed);
     const content = [...source.childNodes, ...outside].map((node) => doc.adoptNode(node));
     const headScripts = [...next.head.querySelectorAll('script[src]')] as HTMLScriptElement[];
-    let open = dialog;
-    if (open === undefined) {
-      opener = doc.activeElement;
-      title = doc.title;
-      open = doc.createElement('dialog');
-      open.setAttribute(NAVIGATION_MODAL_ATTRIBUTE, '');
-      // Light dismiss: Escape AND a press outside close it, as every modal does (`Dialog` included).
-      open.setAttribute('closedby', 'any');
-      open.addEventListener('cancel', onCancel);
-      open.addEventListener('close', onClose);
-      open.addEventListener('pointerdown', onPointerDown);
-      open.addEventListener('click', onClick);
-      doc.body.append(open);
-    } else {
-      // One modal at a time: the next address replaces this one's content, in the same dialog.
-      // Closed as `dismiss` closes it — no longer `dialog` — so its own `close` event, queued or
-      // (in any engine that fires it at once) synchronous, is never read as the visitor closing.
-      disposeIslands(open);
-      dialog = undefined;
-      if (open.open) open.close();
-    }
+    // The frame the click opened, the modal already open, or — for a document that names no
+    // modal routes — a dialog opened now. Never closed and reopened: its `close` event would read
+    // as the visitor closing, and reopening is the work this frame exists to do once.
+    const fresh = dialog === undefined;
+    const open = dialog ?? raise(parseModalRoutes(metaOf(doc, NAVIGATION_MODALS_META)));
+    disposeIslands(open);
     dialog = open;
     openAt = at;
     leaving = false;
-    open.replaceChildren(...content);
+    pending = false;
+    const body = bodyOf(open);
+    // Focus moves in as `showModal()` moved it — unless the visitor already moved it to the close
+    // button while the frame waited.
+    const active = doc.activeElement;
+    const moveFocus = fresh || active === null || active === open || body.contains(active);
+    body.replaceChildren(...content);
+    markIdle(open);
     label(open, next.title);
     doc.title = next.title;
-    open.showModal();
+    if (moveFocus || doc.activeElement?.isConnected !== true) focusInto(open);
     if (history !== 'none') {
       const state = {
         [STATE_KEY]: { scroll: [win.scrollX, win.scrollY], doc: rendered(), modal: at },
@@ -251,6 +334,11 @@ export function modalController(
             owned: owned(),
           }),
     present,
+    loading,
+    release() {
+      pending = false;
+    },
+    settle,
     close,
     clear() {
       clearEntry();

package/src/navigation-tags.ts

@@ -1,13 +1,17 @@
 /**
- * What an opted-in document carries for the client router: which surface rendered it, which build
- * (the skew check — the same meta realtime's sync tags write, deduped by key), the router's
- * script, and — for a `navigation: 'modal'` route — that it is presented over another page. A
- * surface that did not opt in gets none of them, so it pays no byte.
+ * What an opted-in document carries for the client router: its surface, its build (the skew check,
+ * deduped with realtime's sync tags by key), the router's script, a modal route's presentation, and
+ * the surface's modal routes so a click opens the dialog before the answer. Nothing elsewhere.
  */
 
-import { CLIENT_BUILD_META } from '@ultimat3/core';
+import { CLIENT_BUILD_META, routeRank } from '@ultimat3/core';
+import { byCodeUnit } from './code-unit-order';
 import type { HeadTag } from './head';
-import { NAVIGATION_PRESENTATION_META } from './navigation-modal-rules';
+import {
+  type ModalRoutes,
+  NAVIGATION_MODALS_META,
+  NAVIGATION_PRESENTATION_META,
+} from './navigation-modal-rules';
 import { NAVIGATION_META } from './navigation-rules';
 
 export interface ClientNavigationHead {
@@ -18,6 +22,41 @@ export interface ClientNavigationHead {
   readonly scriptUrl: string;
   /** The route declared `navigation: 'modal'`: the router shows it over the page beneath. */
   readonly modal?: boolean;
+  /** The surface's modal routes (`modalRouteList`) and the frame's words, in the page's locale. */
+  readonly modals?: ModalRoutes;
+}
+
+/** Whether some pathname matches both patterns — segment by segment, a catch-all takes the rest. */
+function overlap(a: string, b: string): boolean {
+  const left = a.split('/').filter((s) => s.length > 0);
+  const right = b.split('/').filter((s) => s.length > 0);
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const l = left[i];
+    const r = right[i];
+    if (l?.startsWith('*') === true || r?.startsWith('*') === true) return true;
+    if (l === undefined || r === undefined) return false;
+    if (!l.startsWith(':') && !r.startsWith(':') && l !== r) return false;
+  }
+  return true;
+}
+
+/**
+ * The modals meta's `routes`: every modal pattern, plus — as `!<pattern>` — every page that is NOT
+ * a modal yet matches a path a modal pattern matches and outranks it (`routeRank`, the request
+ * router's own order: `/runs/new/peek` before `/runs/:id/peek`). Most specific first, so the
+ * router's first match is the route the server will run. Deterministic: ties by code unit.
+ */
+export function modalRouteList(
+  pages: readonly { readonly path: string; readonly modal: boolean }[],
+): string[] {
+  const modals = pages.filter((page) => page.modal).map((page) => page.path);
+  const shadows = pages
+    .filter((page) => !page.modal)
+    .map((page) => page.path)
+    .filter((path) => modals.some((m) => routeRank(path) > routeRank(m) && overlap(path, m)));
+  return [...modals, ...shadows]
+    .sort((a, b) => routeRank(b) - routeRank(a) || byCodeUnit(a, b))
+    .map((path) => (modals.includes(path) ? path : `!${path}`));
 }
 
 export function clientNavigationTags(head: ClientNavigationHead): readonly HeadTag[] {
@@ -41,6 +80,15 @@ export function clientNavigationTags(head: ClientNavigationHead): readonly HeadT
           },
         ]
       : []),
+    ...(head.modals !== undefined && head.modals.routes.length > 0
+      ? [
+          {
+            kind: 'meta' as const,
+            key: `meta:${NAVIGATION_MODALS_META}`,
+            attrs: { name: NAVIGATION_MODALS_META, content: JSON.stringify(head.modals) },
+          },
+        ]
+      : []),
     // Deferred, in `<head>`: it runs once, after parsing, and survives every swap of the body.
     {
       kind: 'script',

package/src/navigation.ts

@@ -125,7 +125,14 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
   const tabs = tabSync(win, () => cache.clear());
   const forget = tabs.forget;
   const scroll = scrollKeeper(win, () => rendered);
-  const modal = modalController(win, () => rendered, ran, owned);
+  // Closing a frame before its answer arrived abandons the request it waits on.
+  const modal = modalController(
+    win,
+    () => rendered,
+    ran,
+    owned,
+    () => inflight?.abort(),
+  );
 
   const request = (url: string, purpose: 'soft' | 'prefetch', init?: RequestInit) =>
     fetchDocument(win, doc, url, purpose, init);
@@ -187,8 +194,11 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
     inflight?.abort();
     const mine = new AbortController();
     inflight = mine;
+    modal.release();
     win.clearTimeout(intent);
     navigatingTo = withoutFragment(url);
+    // A route the document names a modal opens NOW, in the click's own task; the answer fills it.
+    if (method === 'GET' && navigatingTo !== rendered) modal.loading(url);
     if (options.history !== 'none') scroll.save();
     const progress = win.setTimeout(
       () => doc.documentElement.setAttribute(NAVIGATING_ATTRIBUTE, ''),
@@ -219,6 +229,7 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
         movesTab: answerMovesTab(facts),
       });
       if (shown === 'degrade') {
+        modal.release();
         modal.clear();
         return;
       }
@@ -266,6 +277,7 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
           backing = true;
           win.history.back();
         }
+        modal.release();
         modal.dismiss();
         let swapped: ReturnType<typeof swapDocument> | undefined;
         await transition(
@@ -317,6 +329,8 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
       if (inflight === mine) {
         inflight = undefined;
         navigatingTo = undefined;
+        // Whatever the answer was, a frame nothing filled goes; an open modal is no longer busy.
+        modal.settle();
         doc.documentElement.removeAttribute(NAVIGATING_ATTRIBUTE);
       }
     }

package/src/route-navigation.ts

@@ -0,0 +1,64 @@
+/**
+ * `defineRoute({ navigation })` read back: the ONE spelling per meaning — `'prefetch'`,
+ * `'document'`, `'modal'`, or `{ modal: true, prefetch: 'intent' }` for a modal that may also be
+ * fetched on intent — and the two questions every reader asks of it (which mode, prefetched or
+ * not), so no reader compares against a string the object form would slip past.
+ */
+
+/**
+ * How the client router treats this page (`navigation: { client }` surfaces only). Absent: swapped
+ * in on a click, never fetched before one. `'prefetch'`: may also be fetched on intent — only for a
+ * page whose GET does nothing but render. `'document'`: always a real document load, the route run
+ * once by the browser — for a GET that records something (an open, a download, a token consumed).
+ * `'modal'`: presented OVER the page a visitor came from, addressed by the hash
+ * (`/runs#/runs/new`) — a create form, a confirmation; a full load of its own URL is still the
+ * whole page. Never fetched before a click: a modal is often a form, and its GET may prepare one.
+ * The server enforces all three before `load` (`@ultimat3/http`'s navigation gate) and names a
+ * modal in its document (`NAVIGATION_PRESENTATION_META`).
+ */
+export type RouteNavigationMode = 'prefetch' | 'document' | 'modal';
+
+export const ROUTE_NAVIGATION_MODES: readonly RouteNavigationMode[] = [
+  'prefetch',
+  'document',
+  'modal',
+];
+
+/**
+ * A `'modal'` whose GET only reads (a peek, a detail view), so it may be fetched on hover, focus
+ * or touchstart, as `'prefetch'` pages are — the click then fills the frame from the answer
+ * already held. `'intent'` is the one value: the router's own hover/focus/touchstart prefetch.
+ */
+export interface RouteModalPrefetch {
+  readonly modal: true;
+  readonly prefetch: 'intent';
+}
+
+/** What `navigation:` takes. */
+export type RouteNavigationDeclaration = RouteNavigationMode | RouteModalPrefetch;
+
+const MODAL_PREFETCH_KEYS = ['modal', 'prefetch'] as const;
+
+/** Exactly one of the four spellings — an object with anything more, or less, is not one. */
+export function isRouteNavigation(value: unknown): value is RouteNavigationDeclaration {
+  if (typeof value === 'string') return ROUTE_NAVIGATION_MODES.some((mode) => mode === value);
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const keys = Object.keys(value);
+  const said = value as Record<string, unknown>;
+  return (
+    keys.length === MODAL_PREFETCH_KEYS.length &&
+    MODAL_PREFETCH_KEYS.every((key) => keys.includes(key)) &&
+    said['modal'] === true &&
+    said['prefetch'] === 'intent'
+  );
+}
+
+/** The mode a declaration says; the object form is a `'modal'`. */
+export const navigationModeOf = (
+  declared: RouteNavigationDeclaration | undefined,
+): RouteNavigationMode | undefined =>
+  declared === undefined || typeof declared === 'string' ? declared : 'modal';
+
+/** Whether the server answers a prefetch of this page as a visit (`RouteNavigation.prefetch`). */
+export const navigationPrefetches = (declared: RouteNavigationDeclaration | undefined): boolean =>
+  declared === 'prefetch' || (typeof declared === 'object' && declared.prefetch === 'intent');

package/src/route.ts

@@ -29,6 +29,11 @@ import {
 import type { IslandSpec } from './island';
 import { drainDeclaredIslands } from './island';
 import { assertModeShape } from './modes';
+import {
+  isRouteNavigation,
+  ROUTE_NAVIGATION_MODES,
+  type RouteNavigationDeclaration,
+} from './route-navigation';
 import { isErrorStatus, routeStatusOf } from './route-status';
 
 /**
@@ -234,25 +239,6 @@ export type LoadRequirement<TData> = RouteContext extends TData
  */
 export type RouteCache = 'no-store' | Omit<CacheHint, 'tags'>;
 
-/**
- * How the client router treats this page (`navigation: { client }` surfaces only). Absent: swapped
- * in on a click, never fetched before one. `'prefetch'`: may also be fetched on intent — only for a
- * page whose GET does nothing but render. `'document'`: always a real document load, the route run
- * once by the browser — for a GET that records something (an open, a download, a token consumed).
- * `'modal'`: presented OVER the page a visitor came from, addressed by the hash
- * (`/runs#/runs/new`) — a create form, a confirmation; a full load of its own URL is still the
- * whole page. Never fetched before a click. The server enforces all three before `load`
- * (`@ultimat3/http`'s navigation gate) and names a modal in its document
- * (`NAVIGATION_PRESENTATION_META`).
- */
-export type RouteNavigationMode = 'prefetch' | 'document' | 'modal';
-
-export const ROUTE_NAVIGATION_MODES: readonly RouteNavigationMode[] = [
-  'prefetch',
-  'document',
-  'modal',
-];
-
 /** The input shape of `defineRoute` — exactly the contract's twelve keys, nothing else. */
 export interface RouteDefinition<TData = RouteData> {
   readonly render: RenderMode;
@@ -284,8 +270,11 @@ export interface RouteDefinition<TData = RouteData> {
    * Never on `static`: a file on disk has no process to answer a `POST`.
    */
   readonly post?: string;
-  /** See `RouteNavigationMode`. Refused on a surface without client navigation, at boot. */
-  readonly navigation?: RouteNavigationMode;
+  /**
+   * See `RouteNavigationMode` and `RouteModalPrefetch` (`route-navigation.ts`). Refused on a
+   * surface without client navigation, at boot.
+   */
+  readonly navigation?: RouteNavigationDeclaration;
 }
 
 /**
@@ -368,9 +357,9 @@ export function defineRoute<TData = RouteData>(
   }
 
   if (def.post !== undefined) assertPostBinding(def.post, def.render);
-  if (def.navigation !== undefined && !ROUTE_NAVIGATION_MODES.includes(def.navigation)) {
+  if (def.navigation !== undefined && !isRouteNavigation(def.navigation)) {
     throw new RouteNavigationInvalidError(
-      `navigation: ${renderCauseValue(def.navigation)} is not one of ${ROUTE_NAVIGATION_MODES.join(', ')}`,
+      `navigation: ${renderCauseValue(def.navigation)} is not one of ${ROUTE_NAVIGATION_MODES.join(', ')} or { modal: true, prefetch: 'intent' }`,
     );
   }