@ultimat3/cli 29.3.2 → 30.0.0

package/wiki/Client-Navigation.md

@@ -0,0 +1,513 @@
+# Client navigation
+
+Moving between pages of an opted-in surface without a full document load: the router fetches the
+next page **the server renders anyway** and swaps it into the same tab. The tab keeps its islands
+that did not change, its socket, its page store and its scroll history, so an app of server pages
+feels like an installed one.
+
+**Not a render mode.** Every page is still rendered by its own route, in its own mode (`ssr`,
+`stream`, `static`, `isr`), behind its own policy and cache headers. The router only decides what
+the browser does with the answer. Without the script (scripting off, or a link marked
+`data-x-reload`), the same markup is an ordinary multi-page app. Why this and not a client-rendered
+mode: [docs/history/render.md](https://github.com/developerz-ai/ultimate/blob/main/docs/history/render.md).
+
+**One rule over everything below: nothing the router sends is sent twice, and nothing it guesses
+runs a route that did not ask for it.** The server enforces both, before any app code runs.
+
+## Opt in: per surface, then per page
+
+```ts
+// app.config.ts
+export const config = defineConfig({
+  name: 'acme',
+  navigation: { client: ['app'] },
+});
+```
+
+| `navigation.client` | Effect |
+|---|---|
+| `[]` (default) | every navigation is a full load; no surface ships a router byte |
+| `['app']` | `app/` pages navigate softly; `site/` stays 0kb of JS |
+| `['site', 'app']` | both. Crossing from one surface to the other is still a full load |
+
+`api` and `shared` render no documents and are refused (`X_CONFIG_INVALID`).
+
+A page may then say how the router treats it, with the route's twelfth key:
+
+```ts
+export const config = defineRoute({ render: 'ssr', …, navigation: 'prefetch' });
+```
+
+| `navigation` | The router | The server, before `load` |
+|---|---|---|
+| absent | swaps the page in on a click; never fetches it early | a prefetch gets an empty `204` |
+| `'prefetch'` | also fetches it on hover/focus | a prefetch is answered like a visit |
+| `'document'` | always a real document load; the page itself carries **no router** (`As of 22.8.1`): no script, no navigation metas, none of the router's bytes charged to its budget — a `0b` page stays `0b`, and its own links and forms are plain browser navigations | a soft visit gets `204` + `x-ultimate-location`; the browser's own load runs it once |
+| `'modal'` | shown **over** the page the visitor is on, addressed by the hash (`/runs#/runs/new`) — [Modals](#modals-a-page-over-a-page). A full load of its own URL is still the whole page | as absent: a prefetch gets an empty `204` |
+| `{ modal: true, prefetch: 'intent' }` | a `'modal'` that is also fetched on hover/focus/touchstart, as `'prefetch'` is (`As of 29.1.0`) | a prefetch is answered like a visit |
+
+**Use `'document'` for every GET that records something** — a recipient opening a link, a download
+logged as evidence, a one-time token. **Use `'prefetch'` — or, for a modal, `{ modal: true,
+prefetch: 'intent' }` — only for a GET that does nothing but render.** A plain `'modal'` stays
+unprefetched: a modal is often a form, and its GET may prepare one (a draft, a token, a reserved
+slot). One spelling per meaning: the object takes exactly those two keys and values, anything else
+is `X_ROUTE_NAVIGATION_INVALID`, and `{ modal: true }` alone is refused — that is `'modal'`.
+Declaring any of them on a surface without client navigation refuses the boot
+(`X_ROUTE_NAVIGATION_INVALID`).
+
+An opted-in document (every page of the surface except a `'document'` one) carries:
+
+| Tag | Why |
+|---|---|
+| `<meta name="ultimate-navigation" content="<app>:<surface>">` | which router may swap it in. The app's `name` is part of it, so two apps on one origin (web and admin) never swap each other's pages |
+| `<meta name="x-ultimate-build" content="…">` | the skew check |
+| `<script src="/_x/assets/navigation/<hash>.js" defer>` | the router: one classic script, content-addressed, `immutable`, `'self'` under the default CSP. `x dev`, the container and `x build --target static` all serve or write it |
+| `<meta name="ultimate-modals" content='{"routes":[…],"close":"…","loading":"…"}'>` | only on a surface with a `'modal'` route: the modal patterns, most specific first, with `!<pattern>` for a page that outranks one (`/runs/new/peek` over `/runs/:id/peek`), and the frame's two words in the document's locale (`ui.close`, `ui.loading` — override them in the app's catalog). What lets a click open the dialog before the answer ([Modals](#opening-on-the-click)) |
+
+**Budget:** the router is 27,845 B minified (10,094 B gzip) `As of 29.1.0` — 24,448 B (9,028 B
+gzip) before the modal that opens on the click and its popover opening (+3,397 B), and 19,966 B
+before route-presented modals and navigating from code (+4,092 B, 26.1.0). It is **charged** to
+every route on the surface, like realtime's page boot, because it is interactivity the app opted
+into. Raise a route's `budget.js` by the measured amount (`bun run budget-raises`).
+
+## What the server enforces
+
+Every router request carries `x-ultimate-navigation: soft | prefetch`, the document's
+`x-ultimate-surface: <app>:<surface>`, its principal (`x-ultimate-navigation-scope`, when the
+document has one) and, on a GET, its `x-ultimate-build`. `@ultimat3/http` answers **before auth,
+before any hook, before the handler**:
+
+| Request | Route | Answer |
+|---|---|---|
+| prefetch | anything but a page declaring `'prefetch'` (actions, queries, assets, storage, app routes, pages) | `204`, nothing ran |
+| soft GET | anything but a page of THIS router's `<app>:<surface>` (a download, an evidence GET, a `'document'` page, another surface or app) | `204` + `x-ultimate-location: <same url>`; the router loads it for real, and it runs once |
+| soft GET | a page rendered for another principal than the router's document | `204` + `x-ultimate-location`, before `load` |
+| GET | a tab on another build | `409` from the existing build check; the router loads the page for real |
+| any router request answered with a 3xx (a form's 303, a sign-in wall, a `load`'s `setRedirect`, an OAuth or payment hop) | any | `204` + `x-ultimate-location: <target>`, cookies kept. The handler ran once; the router follows a same-origin target as its own next request, and hands another origin to the browser. A target that is not `http:`/`https:` (or will not parse) is never handed over: the header names the requested URL instead, as a path |
+| POST | any | never gated: it is the form's submission |
+
+A soft GET across a principal change runs auth and rate-limit **twice** — once before the `204` of
+the principal row above, once for the real load. Expected and harmless (auth and rate-limit only;
+the handler and `load` run once), but a tight per-actor rate limit should budget one extra request
+per sign-in or sign-out navigation.
+
+The router never lets `fetch` follow a redirect (`redirect: 'manual'`), so a CORS-refused hop to
+another origin, or a target on another surface, is never fetched and then asked for again.
+
+## What the router takes, and what it leaves to the browser
+
+Clicks and submits are read on `window` in the bubble phase, **after** every handler on the page:
+a handler that calls `preventDefault()` keeps the event.
+
+| Taken (soft) | Left to the browser (native) |
+|---|---|
+| left click on a same-origin `<a href>` / `<area href>` | a modifier key or another button; `target` other than `_self`; `download`; `rel="external"`; `data-x-reload`; another origin or scheme |
+| a link to another page, or another query on this page | a fragment on the page already shown, `href="#"` included: the browser scrolls, nothing is fetched. An `href` or form `action` no URL parses (`http://`): the browser decides |
+| `<form method="get">`: navigates to its query, like the browser | `method="dialog"`; a `target`; another origin; `data-x-reload` on the form or its submitter |
+| `<form method="post">`, url-encoded or multipart | a POST with a chosen file (the browser's own upload progress); `enctype="text/plain"` |
+
+The submitter's `formaction`, `formmethod`, `formenctype`, `formtarget` and its own name/value are
+honoured. A GET query and a url-encoded body carry every line break as CRLF, as a native submit does
+(`As of 2026-10-02`): a `<textarea>` sends the same bytes with the router as without it.
+
+### What happens to the answer
+
+| Answer | Result |
+|---|---|
+| a page of this surface, build and principal | swapped in |
+| a 4xx/5xx page to a GET, whatever rendered it (the framework's own error page carries no surface meta) | swapped in: a `load` that wrote and then threw is never run a second time. The next click is a real load |
+| `204` + `x-ultimate-location`, same origin | followed as the router's next request (at most 5 hops), or loaded when it names the URL just asked for |
+| `204` + `x-ultimate-location`, another origin | the browser goes there |
+| an empty `204` | nothing: the browser stays, as it does for a `204` navigation |
+| a 2xx that is not a page (a PDF, a zip, JSON) | handed to the browser **from the bytes already received**: saved under its `Content-Disposition` name when `attachment`, shown otherwise. Never asked for again |
+| a 4xx/5xx that is not a page (an offline service worker's empty `503`, a JSON `404`) | a GET: a full load of the URL asked for — the one answer the router asks for again, since there is nothing to show (`As of 2026-10-05`). A POST: `ultimate:navigation-error`, never re-sent |
+| a POST answered in place with a page | swapped in: it cannot be repeated. When it was rendered for ANOTHER principal or build (a sign-in that renders instead of redirecting), every tab's cache is emptied and this tab stops swapping: every later link and form is a real document load |
+| a page from another surface, build or principal where no framework server answered (a static host) | a full load |
+
+### When something fails
+
+| Failure | Result |
+|---|---|
+| a GET fails on the network | the browser loads it (its own offline page) |
+| a POST fails on the network, or its answer cannot be read | **never re-sent.** `ultimate:navigation-error` on `document` (cancelable, `detail: { url, method, reason }`); its default is a GET load of the page the visitor is on, which shows what the server actually has |
+| the swap throws part-way, or the answer's body cannot be read | a real load of the page (GET), or `ultimate:navigation-error` (POST) — never a half-replaced page |
+
+**A failed swap or body read loads a GET for real, so its route runs a second time.** That is why a
+page whose GET records anything must be `navigation: 'document'`: the server then never runs it for
+a soft request at all.
+
+**A failed POST's default is a GET reload of the current page.** On a page where reloading has an
+effect of its own (it is itself a `'document'` page, or its GET records something), put
+`data-x-reload` on its forms — the browser then submits them natively — or cancel
+`ultimate:navigation-error` and show the failure in place.
+
+A navigation started while another is in flight aborts the older one; the slower answer is never
+swapped in over the newer page.
+
+## The swap
+
+In one order, so no frame is unstyled and no island runs twice:
+
+1. **Stylesheets** the next page links and this one has not loaded are loaded first.
+2. **Islands** of the old body are disposed: each one's `mount` return value, when it is a
+   function, is called (Solid's `render` returns one).
+3. **Body** replaced. Elements marked `data-x-persist="<id>"` in **both** documents are carried
+   across live (same node, same state, islands inside still mounted). What the element SAYS about
+   the page follows the incoming one: its own attributes (the ones a server document set — never one
+   a script added), and every descendant's `aria-current` with the `class` beside it, matched by `id`
+   or by position. A sidebar's active item moves.
+4. **Head** brought level by markup: server-rendered tags only this page had go (JSON-LD
+   included), tags only the next has arrive, identical ones stay. Tags a **script** added at run
+   time (a CSS-in-JS `<style>`, analytics) are the tab's and are never removed. The previous page's
+   own stylesheets it no longer links are retired after the swap. `<html lang>` and `dir` follow.
+5. **Scripts**: the next page's head `<script src>` and its body scripts run, in order. The inline
+   hydration runtime runs again and boots the new islands; it visits each island root once per tab,
+   so a carried island is not booted twice. A `src` this tab already ran is not run again. An
+   inline head script runs when its TEXT is new to this head (once per page that carries it, as a
+   full load would), never when the current head already has it (the theme boot, on every page);
+   one only the previous page had is removed. Every inline script, head or body, still needs its
+   CSP hash — the router re-inserts the same text, and the policy judges it as on a full load.
+
+Inside `document.startViewTransition` when the browser has it and `prefers-reduced-motion` is not
+`reduce`. Style the transition with the standard `::view-transition-*` pseudo-elements. While it
+animates the browser hit-tests every press to `<html>` (Chrome does whatever `pointer-events` the
+overlay has), so a click that lands there skips the animation and is given to the element under the
+pointer: the visitor's first click after a swap is never lost. A bare press — a touch that scrolls,
+a long press — never skips it, so named elements finish their glide (`As of 2026-10-05`).
+
+## History, scroll, focus
+
+| Concern | Behaviour |
+|---|---|
+| history | `pushState` per navigation, each entry naming the document it shows; `replaceState` for the same URL. Back/forward to an entry whose document is not the one on screen swaps it in; an entry an app pushed shows the document of its path |
+| scroll | top on a new page; the fragment's element for `#id`; back AND forward restore the saved position (saved as the visitor scrolls), and so do a reload and a Back that is a full document load (`As of 2026-10-02`). Always `instant`, whatever `scroll-behavior` says |
+| focus | moved to the new page's `<main>` (else its first `<h1>`), `tabindex="-1"` added if needed. A `refresh()` keeps it where it was ([below](#refresh-is-the-same-page)) |
+| announcement | the new `document.title`, in a polite `aria-live` region the router owns. A `refresh()` announces nothing |
+| progress | `data-x-navigating` on `<html>` once a navigation runs past 150 ms. No bundled UI: style it, e.g. `html[data-x-navigating] main { opacity: 0.6 }` inside `prefers-reduced-motion: no-preference` |
+
+## Prefetch
+
+On intent: `pointerover` that rests 65 ms, `focusin`, `touchstart`. The server answers only pages
+that declared `navigation: 'prefetch'`; everything else is an empty `204`, remembered so a second
+hover does not ask again. Answers wait in a per-tab **memory** cache (never storage), 30 s, at most 20
+documents, keyed with the query sorted and without the fragment. It is the ONLY reuse layer: every
+router fetch goes out `cache: 'no-cache'`, so the browser's HTTP cache never answers a soft
+navigation — an anonymous page's `stale-while-revalidate` would otherwise show the document from
+before a write, a sign-out or a deploy (`navigation-fetch.ts`; issue #693).
+
+| A prefetched answer is never used when | |
+|---|---|
+| it is not a 2xx page, or it was a hand-over (a redirect, a login wall) | the click asks again |
+| the server said `no-store` and the click came more than 5 s later | the click asks again |
+
+| The cache is emptied by | |
+|---|---|
+| any POST the router sends — when it is sent, and again when it settles, landed or failed: a prefetch sent while it was in flight may have rendered the old state | |
+| any write through the framework's client (`rpc`, a mutation, an upload — `@ultimat3/core`'s `onClientWrite`) | |
+| a principal change: `onRescope`, a load for another principal, a POST answered for one, and every hand-over of the very URL asked for (the server's principal check answers that way, and the router cannot tell it from a `'document'` page — so it forgets either way) | |
+| a `BroadcastChannel('ultimate:navigation')` message from another tab — each of the above posts one | |
+| the page's return from the back/forward cache: the channel is closed on `pagehide` (an open one keeps a page out of that cache), so every message sent meanwhile was missed | |
+
+Never prefetched at all: a link with `data-x-no-prefetch`, anything the click rules leave to the
+browser, anything on `Save-Data` or a `2g`/`slow-2g` connection, and the page a navigation is
+already fetching. A press or click cancels a pending hover's prefetch, and the focus a press gives a
+link is not an intent — so a fast click sends exactly one request (`As of 22.8.1`).
+
+## Without the router: the browser's own prefetch
+
+`As of 2026-09`. A document that carries **no** router — every page of a surface outside
+`navigation.client`, and every `navigation: 'document'` page — carries one
+`<script type="speculationrules">` instead: the browser fetches a link's document before the click,
+and the full-page load that follows paints from memory. No JavaScript ships for it; a `0kb` page
+stays `0kb` (`budgets.ts` reads the block as data). **Prefetch only, never prerender** — a prerender
+runs the next page's scripts for a page nobody opened.
+
+```ts
+navigation: { speculation: { prefetch: 'moderate', exclude: ['/blog/borrador-*'] } },
+```
+
+| `speculation.prefetch` | The browser fetches |
+|---|---|
+| `'moderate'` (default) | on pointer rest (~200 ms) or pointer down |
+| `'conservative'` | on pointer down only |
+| `false` | nothing: no tag, no CSP source |
+
+The rules are an **allow-list** from the route table — a prefetch is a real GET with the visitor's
+cookies, so only a page the table says is a pure read is a candidate:
+
+| A page is a candidate when | Why |
+|---|---|
+| its surface has no router, and it is `static` or `isr` with no policy | it was rendered at build time, for nobody |
+| its surface has the router, and it declared `navigation: 'prefetch'` | the app's own statement that its GET is a pure read |
+
+Never a candidate: a `navigation: 'document'` page, an `ssr` page of a surface without the router
+(it has no way to say its GET records nothing), an `offline: 'network-only'` page, an `api/` route,
+and anything that is not a page — `/_storage/*`, `/mcp*`, an app's plain routes. Each candidate is
+one URL pattern covering every routed locale (`{/en}?/precios`, `{/en}?/blog/:slug`);
+`speculation.exclude` subtracts more, as URL patterns starting with `/`.
+
+The body is the same string on every document of the app, sorted, and `script-src` admits it by
+sha256 hashed from that string (`page-speculation.ts`), so the enforced policy needs no
+`'unsafe-inline'`. Browsers without Speculation Rules ignore the block.
+
+## Opting a link or form out
+
+| Want | Write |
+|---|---|
+| a full load for this link or form | `data-x-reload` |
+| soft on click, never fetched early | `data-x-no-prefetch` |
+| a full load for every link to a page, from anywhere | `navigation: 'document'` on its route |
+| an element that survives navigations | `data-x-persist="<stable id>"` on it, in both pages |
+
+## Modals: a page over a page
+
+`As of 26.1.0`. A create form, an edit step, a confirmation: a page whose route says it is
+presented over another.
+
+```ts
+// app/runs/new/page.tsx
+import { defineRoute } from '@ultimat3/render';
+
+export const config = defineRoute({
+  render: 'ssr',
+  offline: 'network-only',
+  meta: ({ t }) => ({ title: t('runs.new') }),
+  navigation: 'modal',
+});
+```
+
+```tsx
+// app/runs/page.tsx — an ordinary link: without the router it is the whole page
+<a href="/runs/new">New run</a>
+```
+
+**Two routers, one URL.** The PATH is the page on screen, swapped as everywhere else on this page.
+The HASH is the one modal over it, and the hash's path is itself a route of the same surface:
+`/runs#/runs/new`, `/projects/7#/projects/7/members/invite` — any depth, with a query
+(`#/runs/new?bank=ve`). Every other fragment (`#below`) is still a fragment. Link the page's own
+path; the router writes the hash.
+
+| Visit | Result |
+|---|---|
+| a click on a link to a `'modal'` page | the dialog opens **on the click**, busy ([below](#opening-on-the-click)); its document fetched (one soft GET), its `<main>` shown in that `<dialog>` over this page; the URL becomes `<this page>#<its path>`, pushed once the content is in |
+| a reload, a pasted or bookmarked `/runs#/runs/new`, Forward onto it | `/runs` renders; the router opens `/runs/new` over it |
+| a hash typed over the page | the same |
+| a hash naming anything else — a page that is not `'modal'`, a 404, a redirect, another principal's page, `#//host` | **just the page**: the hash is dropped in place. Never followed, loaded, or shown as an error |
+| a full load of `/runs/new` itself, scripting off, `data-x-reload` | the whole page, as before — the server renders one document for both |
+| a link to the page on screen that is itself a `'modal'` route | that page, swapped in as usual |
+
+**Why the route, and not the link (axiom 1).** Presentation is a property of the page: a create
+form is a modal wherever it is reached from, and the one place that can say so for EVERY way of
+reaching it — a link, a redirect after a POST, a pasted hash — is its route. A link attribute
+would be a second declaration two links to one page could disagree on, and a redirect has no link
+to carry it. The server names the page a modal in its own document
+(`<meta name="ultimate-presentation" content="modal">`); the router never decides it.
+
+**Why the whole document, and not a fragment.** The router asks for the page exactly as a full
+load does — same policy, same `load`, same cache headers, no request header that varies the
+answer — and shows its `<main>`. A second shape of one URL would need `Vary`, could not be a
+`static` or `isr` file, and would put two answers under one key in every cache on the way.
+
+### Opening on the click
+
+`As of 29.1.0`. The document of every page on a surface with a `'modal'` route names those routes
+(`ultimate-modals`). A click on a link to one — or `openModal(path)`, or a hash that addresses one —
+opens the dialog **in the click's own task**, before the request is sent:
+
+| Phase | The dialog |
+|---|---|
+| on the click | open, in the top layer, focused: its body `[data-x-modal-body]` is `aria-busy="true"` and holds a skeleton (`[data-x-modal-skeleton]`, `aria-hidden`); the dialog is named "Loading…" (`ui.loading`); the close button is there. Nothing is pushed on history yet |
+| the answer is the modal | its `<main>` replaces the skeleton in the same dialog, `aria-busy` goes, the dialog is named by its heading, focus moves to `[autofocus]` (else the first focusable element) unless the visitor already moved it, and the hash entry is pushed — exactly as before |
+| closed while it loads (Escape, the close button, a press outside, Back) | the request is **aborted**; the dialog goes; no entry was pushed, so nothing is left to pop |
+| the answer is not a modal (a page, a redirect, a load, a failure, a stale hash) | the frame goes, and the answer is handled exactly as it was before this release: a page swaps in, a network failure loads the URL, a stale hash is dropped in place |
+| a link to another modal from inside one | the dialog keeps its content, busy, until the next one replaces it |
+
+The router never decides the presentation from the meta: it only opens early. The ANSWER's
+`ultimate-presentation` still decides, so a document that names no modal routes (or an older
+router) behaves as before: nothing on screen until the answer.
+
+**Prefetch on intent.** With `navigation: { modal: true, prefetch: 'intent' }` a hover, focus or
+touchstart fetches the modal's document, and the click fills the frame from that answer — often in
+the same frame it opened in. An island that opens a modal from code (`openModal`) gets no hover of
+its own; put the modal's link in the row, or let the row's own link carry the intent.
+
+**Why not `showModal()`.** A modal `<dialog>` makes the rest of the document inert, and Chrome
+computes inertness in style: opening one restyles **every element on the page**. The router opens
+its dialog with `show()` + `showPopover()` — the top layer and `::backdrop`, no inert document — and
+does what `showModal()` did by hand: `aria-modal="true"`, focus moved in, Tab kept inside, Escape
+(where `closedby` is not supported) and a press on the backdrop closing it. Measured on a 7,011-element
+page in headless Chrome 150, 4x CPU throttling, median of 7 cold loads:
+
+| Opening | open + forced style/layout | to next frame | RecalcStyle |
+|---|---|---|---|
+| `showModal()` + `html:has(dialog:modal)` (before) | 131.3 ms | 163.9 ms | 124.1 ms |
+| `showModal()`, no `:has()` lock | 122.3 ms | 157.8 ms | 116.4 ms |
+| `inert` on one wrapper + popover | 117.3 ms | 153.3 ms | 111.1 ms |
+| `show()` + `showPopover()` + `html:has(> body > dialog[data-x-modal][open])` (now) | 9.7 ms | 32.8 ms | 2.6 ms |
+
+The cost was the inert document, not the `:has()` lock and not the attribute toggles: `inert` on a
+single wrapper is as expensive as `showModal()`. A browser without popovers still gets `showModal()`.
+The page beneath is out of reach behind the backdrop and for assistive technology (`aria-modal`),
+but it is not `inert`: `:modal` no longer matches the router's dialog — select it by
+`dialog[data-x-modal]` (and `[open]`).
+
+### Inside the modal
+
+| Concern | Behaviour |
+|---|---|
+| markup | one `<dialog data-x-modal aria-modal="true">` in the top layer (`show()` + `showPopover()`, [above](#opening-on-the-click)), `::backdrop`, focus moved in and kept in. Its content in `[data-x-modal-body]`, then the frame's close button. Named by its first `h1`/`h2` (`aria-labelledby`), else by the page's title. The tab's title is the modal's while it is open |
+| the page beneath | untouched: its islands stay mounted, its socket and page store live, its scroll where it was |
+| links and forms | resolved against the MODAL's URL, as on its own page: `href="?step=2"` is `/runs/new?step=2`, a form with no `action` posts to `/runs/new` |
+| islands in the modal | booted by the page's hydration runtime; disposed when the modal closes or its content is replaced |
+| styles | the modal page's stylesheets load first. `@ultimat3/ui`'s `global.scss` styles `dialog[data-x-modal]` as its `Dialog` (`surface-raised` over `scrim`), its close button and its skeleton, under `:where()` so an app restyles them at zero specificity; its reset locks the page's scroll behind the router's dialog (`html:has(> body > dialog[data-x-modal][open])`) and behind any `:modal` `<dialog>` |
+| one at a time | a link to another `'modal'` page from inside replaces the content of the same dialog and pushes, so Back steps out one level (`#/runs/new` → `#/runs/new/advanced` → Back → `#/runs/new`) |
+
+### Closing
+
+| Gesture | Result |
+|---|---|
+| Escape, a press outside it (the dialog carries `closedby="any"`; a browser without it gets the same from the router, for a press that begins and ends on the backdrop), a `<form method="dialog">`, any way the browser closes the dialog | **Back**, when the entry is the one the router pushed; otherwise (a cold-loaded address — Back would leave the app) the hash is dropped in place |
+| the browser's Back | the entry beneath has no modal: closed |
+| a link to the page beneath (the page's own **Cancel**, which is also its no-JS way back) | as Escape — nothing is fetched |
+| a link anywhere else | that page swaps in, in place of the modal's entry |
+
+Focus returns to the link or button that opened it; the title returns to the page's.
+
+The router renders **one close button** (`As of 29.1.0`): `<button type="button"
+data-x-modal-close aria-label="…">` after the content — never a `<form>`, so a page's own
+`dialog form` selector still finds its form — named by the framework catalog's
+`ui.close` in the document's locale, drawn as a cross by `@ultimat3/ui`. It closes as Escape
+does. It needs the `ultimate-modals` meta for its name, so a document without one gets none. Still
+give the modal page a Cancel link to the page it is opened over: on its own full page that link is
+its way back.
+
+### Forms inside
+
+A form inside the modal submits through the router like any other: the POST is sent once, never
+again.
+
+| The server answers | Result |
+|---|---|
+| the modal page again (a `422` re-render with its errors) | shown in the same dialog; the address stays (`replace`) |
+| a redirect to the page beneath (`303 /runs`) | the modal closes and the page is fetched and swapped in — its content refreshed — through Back, so the spent form's entry is not left to reopen |
+| a redirect anywhere else | the target swaps in, in place of the modal's entry |
+| a redirect to another `'modal'` page (create, then confirm) | shown in the same dialog, in place of the form's entry |
+| nothing (the network failed) | `ultimate:navigation-error`, never re-sent; its default reloads the tab — the page and its modal both asked for again, since a hash alone is only scrolled to |
+| anything else (a download, another principal) | as on any page — [What happens to the answer](#what-happens-to-the-answer) |
+
+A `'modal'` page's form on its own full page is an ordinary page form: a re-render there is a
+page, never a modal.
+
+## Navigating from code
+
+`As of 2026-10`. From an island or an app script, never by clicking a hidden link — imported from
+`@ultimat3/render/client`, the package's browser entry:
+
+```ts
+import { closeModal, navigate, openModal, refresh, scheduleRefresh } from '@ultimat3/render/client';
+
+await navigate('/runs/7'); // as a click on a link to it
+await navigate('/runs?status=failed', { replace: true }); // the current entry replaced
+await refresh(); // the page on screen, rendered again, where it is scrolled
+await openModal('/runs/new'); // the `navigation: 'modal'` route over this page: /runs#/runs/new
+closeModal(); // as Escape
+```
+
+The same entry exports `disposeIslands(root)`: what the router calls on the body it swaps out, for an
+island that drops markup holding other islands (`As of 2026-10`, [Client data](Client-Data)).
+
+| Call | With the router | Without it (a `site/` page, a `'document'` page, the router's script blocked) |
+|---|---|---|
+| `navigate(url, { replace? })` | the router's own navigation: the server's gate and the answer decide swap, modal or full load. Another origin: a document load | `location.assign` / `location.replace` |
+| `refresh()` | the page fetched again (never from the prefetch cache) and swapped in with no history entry, at the visitor's scroll — for the same visitor: [below](#refresh-is-the-same-page). Under an open modal: nothing | `location.reload()` |
+| `scheduleRefresh()` | a `refresh()` once the visitor is idle, coalesced: [below](#scheduling-a-refresh) | nothing — a reload under a reader is the failure it prevents |
+| `openModal(path)` | `#<path>` over the page, pushed, so Back closes it. A path that is not a modal of this tab opens nothing, as a stale hash | `location.assign(path)`: the modal route's whole page |
+| `closeModal()` | as Escape: Back through the router's own entry, else the hash dropped in place | nothing — no modal is open |
+
+`openModal` takes the route's own path, as its link would (`'/runs/new'`, `'/runs/new?bank=ve'`); a
+full URL, `//host` or a relative path is a rejected promise, `X_NAVIGATION_MODAL_PATH_INVALID` —
+never a synchronous throw, so `.catch` sees it. On the server
+every call does nothing. The functions import the router's TYPE only: an island that navigates
+ships none of the router's bytes.
+
+Import them from `/client`, never from `@ultimat3/render`: the barrel keeps render's whole error
+table in any chunk that reaches it. An island whose body is `refresh()` is 216 B minified from
+`/client` and was 9,323 B from the barrel (`packages/render/src/client-bundle.test.ts`, `As of
+2026-10-08`). The barrel still exports them, for compatibility. The rejection is
+`NavigationModalPathInvalidError`, one class from either entry, so `instanceof` holds whichever an
+app imports; read `.code` when the two halves of an app may disagree on where they import from.
+
+### `refresh()` is the same page
+
+`As of 30.0.0`. Same page, same visitor, so none of a new page's arrival applies:
+
+| | A navigation | `refresh()` |
+|---|---|---|
+| view transition | yes, unless reduced motion | none |
+| focus | `<main>` | the control the visitor was in: by `id`, else `name` in the same form, else its row (`[data-row]`) + tag + place in the row. Restored after the page's scripts ran, so an island's control is there. Gone from the new page: `<main>`. Nothing focused: untouched |
+| announcer | the new title | not written |
+| a navigation already in flight | aborted by the newer one | kept: the refresh resolves and does nothing, since that navigation fetches fresh anyway |
+| an open modal | — | nothing is fetched; the modal and the page beneath stay |
+
+Proof: `packages/render/src/navigation-refresh.test.ts`, and in Chrome
+`packages/cli/e2e/client-navigation-refresh.e2e.test.ts`.
+
+### Scheduling a refresh
+
+`scheduleRefresh()` is "a channel said the page changed", not "re-read now". One runs, one is owed;
+any number of calls while one runs owe exactly one more. It is held — owed, paid later — while:
+
+| Held while | Paid |
+|---|---|
+| the tab is hidden | on show |
+| a `dialog[open]` or an open popover is on the page | once it closes (asked again every second) |
+| focus is in an `input`, `textarea` or `[contenteditable]`, or text is selected | once it leaves |
+| a navigation runs (`data-x-navigating`) | after it |
+| within `QUIET_MS` (1 s) of a scroll, wheel, key or press | 1 s after the last one |
+| a press is down | on release, or 10 s after it (a lost `pointerup`) |
+
+After a lost session (`sessionIsLost()`, [Client data](Client-Data)) it does nothing, ever. Without
+the router it does nothing — the difference from `refresh()`. Its state is on `window` under
+`Symbol.for('ultimate.refresh-idle')`, so every island chunk shares one. The channel-to-refresh
+idiom is in [Realtime](Realtime#a-channel-event-re-reads-the-page).
+
+## Events
+
+Dispatched on `document`:
+
+| Event | When | `detail` |
+|---|---|---|
+| `ultimate:navigate` | before the fetch. **Cancelable**: `preventDefault()` keeps the tab where it is | `{ url, method }` |
+| `ultimate:navigated` | after the swap, the scroll and the new scripts — and after a modal opens, its `url` the modal's | `{ url }` |
+| `ultimate:navigation-error` | a POST that failed or could not be shown, a swap that failed on a POST. **Cancelable**: the default is a GET of the current page | `{ url, method, reason }` |
+
+The three event names are on `@ultimat3/render/client` too — what an island listens with. The event
+names and attributes are exported from `@ultimat3/render` (`NAVIGATE_EVENT`,
+`NAVIGATED_EVENT`, `NAVIGATION_ERROR_EVENT`, `NAVIGATION_RELOAD_ATTRIBUTE`,
+`NAVIGATION_NO_PREFETCH_ATTRIBUTE`, `NAVIGATION_PERSIST_ATTRIBUTE`, `NAVIGATING_ATTRIBUTE`,
+`NAVIGATION_PRESENTATION_META`, `NAVIGATION_MODAL_ATTRIBUTE`, `NAVIGATION_MODALS_META`,
+`NAVIGATION_MODAL_BODY_ATTRIBUTE`, `NAVIGATION_MODAL_CLOSE_ATTRIBUTE`,
+`NAVIGATION_MODAL_SKELETON_ATTRIBUTE`), with the pure rules the router runs
+(`linkVerdict`, `formVerdict`, `responseVerdict`, `reusable`, `mayPrefetch`, `modalAddress`,
+`presentation`, `modalHistory`, `leaveModal`, `declaresModal`, `parseModalRoutes`), the server's
+`modalRouteList`, and the declaration's readers (`isRouteNavigation`, `navigationModeOf`,
+`navigationPrefetches`). The headers are `@ultimat3/core`'s, imported from there only
+(`CLIENT_NAVIGATION_HEADER`, `CLIENT_NAVIGATION_LOCATION_HEADER`, `CLIENT_NAVIGATION_SCOPE_HEADER`,
+`CLIENT_NAVIGATION_SURFACE_HEADER`) — render's `NAVIGATION_*_HEADER` aliases were deleted in 25.0.0. The server half is
+`@ultimat3/http`'s `navigationGate`, `redirectForRouter` and `relocate`.
+
+## Tested where
+
+| What | Where |
+|---|---|
+| every client rule, as pure functions | `packages/render/src/navigation-rules.test.ts`, `navigation-cache.test.ts`, `navigation-dom.test.ts`, `route-navigation.test.ts`, `navigation-modal-rules.test.ts` |
+| a `'modal'` page: never prefetched, one document for a soft and a full load, the meta it carries; `{ modal: true, prefetch: 'intent' }` prefetched; the `ultimate-modals` meta, its shadows and its words | `packages/cli/src/page-navigation.test.ts`, `packages/render/src/navigation-tags.test.ts` |
+| the frame: open on the click, filled by the answer, aborted on close, taken down by a non-modal answer, opened without `showModal()` | `packages/render/src/navigation-modal-frame.test.ts` |
+| modals in a real Chrome: open over a live page, the frame in the click's own task, Escape while it loads, a prefetched modal, Escape/Back/Cancel, reload and pasted hash, stale hash, nesting, a refused and a redirected submit, a confirmation, `openModal`/`closeModal`/`refresh` from code, scripting off | `packages/cli/e2e/client-navigation-modal.e2e.test.ts` |
+| navigating from code: through the router, the browser's fallbacks, the server, `openModal`'s refusal | `packages/render/src/navigation-api.test.ts` |
+| the server gate and the redirect hand-over, counting handler runs | `packages/http/src/navigation.test.ts` |
+| speculation rules: which pages are candidates, the tag on a router-less document only, the CSP hash of the served bytes | `packages/cli/src/page-speculation.test.ts`, `packages/render/src/speculation-rules.test.ts` |
+| real pages: prefetch and `'document'` run no `load`, another principal or app is refused, a misplaced key refuses the boot | `packages/cli/src/page-navigation.test.ts` |
+| writes announced after they settle | `packages/core/src/client-writes.test.ts` |
+| in a real Chrome, through the real pipeline under an enforced CSP: every rule above, counted in route executions | `packages/cli/e2e/client-navigation-*.e2e.test.ts` |
+| the reference app, opted in: real pages, sign-out, a like after a round trip, the editor as a modal over the feed, scripting off | `examples/dummy/apps/web/e2e/client-navigation.e2e.test.ts` |

package/wiki/Compared.md

@@ -0,0 +1,93 @@
+# Compared
+
+Each stack this framework gets compared to, **"pick it instead when" first**. A row in this
+framework's favour cites a command, a file or a page you can check; a claim about another stack
+links that stack's own documentation. `As of 2026-11`. No head-to-head chart: a vendor's numbers
+against its rivals convince nobody, so this page publishes its own figures and the harness, and you
+point the harness at yours.
+
+## What you give up here, whichever stack you come from
+
+| You give up | Where it is stated |
+|---|---|
+| any runtime but Bun | `non_goals` in `.dz/maintainer/maintainer.yml`; [FAQ](FAQ) |
+| any database but Postgres | the same list; [Home](Home) |
+| any renderer but SolidJS | the same list; [Routes and render modes](Routes-And-Render-Modes) |
+| a long track record: released in 2026, no outside production adopter claimed | [FAQ](FAQ) |
+| a slow major cadence: from v30, one major per 90 days | [Stability](Stability) |
+| a third-party security audit: there has been none | [`SECURITY.md`](https://github.com/developerz-ai/ultimate/blob/main/SECURITY.md) |
+| a plugin API: an app wraps a primitive instead | [Home](Home) |
+| a serverless or edge target: containers only | [Deployment](Deployment) |
+| everything on the open list | [Known gaps](Known-Gaps) |
+
+## Measured, and how to reproduce it
+
+One local run on an 8-core laptop, `As of 2026-11-06`, not yet a CI figure; the method, the box and
+the caveats are [`scripts/bench/results/README.md`](https://github.com/developerz-ai/ultimate/blob/main/scripts/bench/results/README.md),
+and every number below is held to the committed JSON by `bun run scripts/bench-claims.ts`
+(`X_BENCH_CLAIM_STALE`).
+
+| Figure | Measured |
+|---|---|
+| scaffold, published `create-ultimate` (29.4.0) | 4.7 s |
+| `bun run setup`, cold Bun cache | 43.3 s |
+| `node_modules` after setup | 165 MB |
+| first `bun run verify` | **red on 29.4.0**: `budgets` was `X_BUDGET_UNMEASURED` until something built; the step builds first on `main` |
+| `/` under `x dev`, one client, concurrency 16 | median 267 req/s, p99 181.85 ms |
+| a typed read, `/_x/query/post-list` | median 183 req/s, p99 258.26 ms |
+| cold start to the first 2xx (`x dev`) | 4.8 s |
+
+`x dev` is the development server — every role and an embedded Postgres in one process — so these
+are a laptop's first-hour numbers, not a production capacity claim.
+
+Reproduce on any machine with Bun and a clone of this repository:
+
+```sh
+bun run scripts/bench/first-hour.ts --runs 5 --json
+bun run scripts/bench/http-hello.ts --url http://localhost:3000/ --seconds 30 --runs 5 --start 'bunx x dev' --cwd <the work directory first-hour printed>/firsthour
+```
+
+`http-hello.ts --url` loads any URL, so point it at your own app on any stack and compare like with
+like. It refuses a run under 10 s (`X_BENCH_RUN_TOO_SHORT`), and a non-2xx answer or a server that
+dies mid-run is `X_BENCH_RUN_FAILED`, never a figure. `.github/workflows/bench.yml` re-measures weekly
+and on every release, on a free `ubuntu-latest` runner, and opens a pull request with the JSON.
+
+## Rails
+
+| | |
+|---|---|
+| **Pick Rails instead when** | your team writes Ruby; you need MySQL or SQLite as well as Postgres ([Active Record](https://guides.rubyonrails.org/active_record_basics.html)); you want two decades of gems, hosts and hiring; you want server-rendered HTML with Hotwire and no client build |
+| **Pick this when** | the primary author is an agent: one declaration projects HTTP, OpenAPI, a typed client and an MCP tool ([Actions](Actions)), and `x verify` is one green-or-red answer over 21 steps (`VERIFY_STEP_NAMES`, `packages/cli/src/verify-step.ts`); you want types end to end with no codegen step ([Client data](Client-Data)) |
+| **What you give up** | the table above, and Rails' ecosystem. The concept map: [Migrating from Rails](Migrating-From-Rails) |
+
+## Next.js
+
+| | |
+|---|---|
+| **Pick Next.js instead when** | your team and component library are React; you deploy to a serverless or edge platform ([Next.js deploying](https://nextjs.org/docs/app/getting-started/deploying)); you want the largest ecosystem of the five |
+| **Pick this when** | you want jobs, realtime, authz, mail, storage and an admin in the box rather than chosen per project ([Jobs and workflows](Jobs-And-Workflows), [Realtime](Realtime), [Policies and authz](Policies-And-Authz), [Admin dashboard](Admin-Dashboard)); you want a page's JavaScript budget to fail the build (`budget: { js: '0kb' }`, [Routes and render modes](Routes-And-Render-Modes)) |
+| **What you give up** | React, and the platform features this framework will not use. The concept map for a Node app: [Migrating from Node and Drizzle](Migrating-From-Node-Drizzle) |
+
+## Meteor
+
+| | |
+|---|---|
+| **Pick Meteor instead when** | your data is in MongoDB, Meteor's primary database ([Meteor docs](https://docs.meteor.com/)); you already run a Meteor app |
+| **Pick this when** | you want realtime that reuses the one authz system per delivered row: a live query is a `query` with its `policy` ([Queries and live queries](Queries-And-Live-Queries)); you want Postgres and SQL you can read (`postgresDriver()`, `packages/entity/src/pg-driver.ts`) |
+| **What you give up** | MongoDB, and Meteor's package ecosystem |
+
+## Phoenix
+
+| | |
+|---|---|
+| **Pick Phoenix instead when** | you want the BEAM: lightweight processes, supervision and clustering ([Phoenix docs](https://hexdocs.pm/phoenix/overview.html)); you want LiveView's server-held state over a socket |
+| **Pick this when** | you want TypeScript on both sides with one schema per declaration ([Actions](Actions)); you want durable step workflows as a primitive rather than a library choice ([Jobs and workflows](Jobs-And-Workflows)) |
+| **What you give up** | the BEAM's concurrency model and a long-proven runtime. Realtime capacity here is measured on one node: `scripts/bench/results/README.md` |
+
+## Inngest and Zero
+
+| | |
+|---|---|
+| **Pick them instead when** | you keep the framework you have and add durable functions ([Inngest docs](https://www.inngest.com/docs)) or a sync engine ([Zero docs](https://zero.rocicorp.dev/docs/introduction)) to it |
+| **Pick this when** | you want their shapes — a `job` with steps, a `mutator` — inside one runtime under one authz system, with nothing to operate beside Postgres ([The eight primitives](The-Eight-Primitives)) |
+| **What you give up** | keeping your current framework |