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.

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.

// app.config.ts
export const config = defineConfig({
  name: 'notificado',
  navigation: { client: ['app'] },
});

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:

export const config = defineRoute({ render: 'ssr', …, navigation: 'prefetch' });

Use 'document' for every GET that records something — a recipient opening a link, a download logged as evidence, a one-time token. Use 'prefetch' only for a GET that does nothing but render. Declaring any of the three 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:

Budget: the router is 24,058 B minified (8,836 B gzip) As of 26.1.0 — 19,966 B before route-presented modals and navigating from code (+4,092 B). 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).

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:

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.

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.

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.

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.

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).

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).

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).

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.

navigation: { speculation: { prefetch: 'moderate', exclude: ['/blog/borrador-*'] } },

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:

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.

As of 26.1.0. A create form, an edit step, a confirmation: a page whose route says it is presented over another.

// 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',
});

// 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.

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.

Focus returns to the link or button that opened it; the title returns to the page's.

The router renders no close button: it has no catalog to name one in, and a page that is also a full page already has its way back. Give the modal page a Cancel link to the page it is opened over (or a <form method="dialog"> button).

A form inside the modal submits through the router like any other: the POST is sent once, never again.

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.

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:

import { closeModal, navigate, openModal, refresh } 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).

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.

Dispatched on document:

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), with the pure rules the router runs (linkVerdict, formVerdict, responseVerdict, reusable, mayPrefetch, modalAddress, presentation, modalHistory, leaveModal). 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.