@ultimat3/render 22.7.1 → 22.8.0

package/src/navigation-rules.ts

@@ -0,0 +1,306 @@
+/**
+ * Which clicks and submits the client router takes, and which it leaves to the browser — as pure
+ * functions over plain facts, so every rule is testable without a DOM and the router
+ * (`navigation.ts`) only gathers the facts. Also the one declaration of every attribute, header and
+ * event name the router shares with the documents the server renders and the apps that listen.
+ */
+
+import {
+  CLIENT_NAVIGATION_HEADER,
+  CLIENT_NAVIGATION_LOCATION_HEADER,
+  CLIENT_NAVIGATION_SCOPE_HEADER,
+  CLIENT_NAVIGATION_SURFACE_HEADER,
+} from '@ultimat3/core/page';
+
+/**
+ * `<meta name="ultimate-navigation" content="<app>:<surface>">` — present only on an opted-in
+ * surface. The app's name is part of it, so two apps on one origin (web and admin) are two routers.
+ */
+export const NAVIGATION_META = 'ultimate-navigation';
+/**
+ * Sent on every router fetch: `soft` when a visitor asked for the page, `prefetch` when the router
+ * guessed they would. The server answers a route that did not opt in before running it.
+ */
+export const NAVIGATION_HEADER = CLIENT_NAVIGATION_HEADER;
+/** The `<app>:<surface>` of the document the router runs in, on every router fetch. */
+export const NAVIGATION_SURFACE_HEADER = CLIENT_NAVIGATION_SURFACE_HEADER;
+/** The document's principal (`ultimate-scope`), when it carries one. */
+export const NAVIGATION_SCOPE_HEADER = CLIENT_NAVIGATION_SCOPE_HEADER;
+/** On a `204`: load this URL with a real navigation — the server's hand-over. */
+export const NAVIGATION_LOCATION_HEADER = CLIENT_NAVIGATION_LOCATION_HEADER;
+/** On a link or form: always a full document load. */
+export const NAVIGATION_RELOAD_ATTRIBUTE = 'data-x-reload';
+/** On a link: followed softly, never fetched before it is clicked. */
+export const NAVIGATION_NO_PREFETCH_ATTRIBUTE = 'data-x-no-prefetch';
+/** `data-x-persist="<id>"` on an element in both documents: the live element is kept across. */
+export const NAVIGATION_PERSIST_ATTRIBUTE = 'data-x-persist';
+/** Set on `<html>` while a navigation has run past `NAVIGATION_PROGRESS_DELAY_MS`. */
+export const NAVIGATING_ATTRIBUTE = 'data-x-navigating';
+/** Dispatched on `document`, cancelable, before the fetch: `detail: { url, method }`. */
+export const NAVIGATE_EVENT = 'ultimate:navigate';
+/** Dispatched on `document` after the new document is in place: `detail: { url }`. */
+export const NAVIGATED_EVENT = 'ultimate:navigated';
+/**
+ * Dispatched on `document`, cancelable, when a navigation could not complete: `detail: { url,
+ * method, reason }`. Default action: a GET load of the page the visitor is on — a POST is never
+ * sent twice, and after a failed one only the server knows whether it landed.
+ */
+export const NAVIGATION_ERROR_EVENT = 'ultimate:navigation-error';
+
+/** How long a prefetched or visited document answers a navigation to the same URL. */
+export const NAVIGATION_CACHE_TTL_MS = 30_000;
+/** Pointer rest before a prefetch — long enough that sweeping across a menu fetches nothing. */
+export const NAVIGATION_PREFETCH_DELAY_MS = 65;
+/** Below this, a navigation shows no progress at all: a flash of a bar reads as jank. */
+export const NAVIGATION_PROGRESS_DELAY_MS = 150;
+/** How long a prefetched answer marked `no-store` may still answer the click it anticipated. */
+export const NAVIGATION_NO_STORE_REUSE_MS = 5_000;
+/** Redirects the router follows itself before it hands the rest to the browser. */
+export const NAVIGATION_MAX_HOPS = 5;
+
+/** Why the browser keeps a navigation. Named, so a test states the rule it pins. */
+export type NativeReason =
+  | 'prevented'
+  | 'modified'
+  | 'target'
+  | 'download'
+  | 'external'
+  | 'opt-out'
+  | 'cross-origin'
+  | 'hash'
+  | 'method'
+  | 'encoding'
+  | 'file';
+
+export type LinkVerdict =
+  | { readonly kind: 'soft'; readonly url: string }
+  | { readonly kind: 'native'; readonly reason: NativeReason };
+
+/** What a click on an `<a href>` tells the router. `href` is the RESOLVED `a.href`. */
+export interface LinkFacts {
+  readonly href: string;
+  /** `location.href` of the page the link sits on. */
+  readonly current: string;
+  readonly button: number;
+  readonly modified: boolean;
+  readonly defaultPrevented: boolean;
+  /** `a.target`, `''` when unset. `_self` is the one value that stays in this tab. */
+  readonly target: string;
+  readonly download: boolean;
+  /** `a.rel`, space-separated. */
+  readonly rel: string;
+  readonly reload: boolean;
+}
+
+const native = (reason: NativeReason): { readonly kind: 'native'; reason: NativeReason } => ({
+  kind: 'native',
+  reason,
+});
+
+/** Same document, fragment only: the browser scrolls, no fetch. */
+const hashOnly = (to: URL, from: URL): boolean =>
+  to.hash !== '' && to.pathname === from.pathname && to.search === from.search;
+
+/**
+ * The link rules, in the order a reader checks them. The SURFACE is not decided here: the URL
+ * alone cannot say which surface answers it, so the router fetches and compares the answer's
+ * `ultimate-navigation` meta with this document's (`responseVerdict`).
+ */
+export function linkVerdict(facts: LinkFacts): LinkVerdict {
+  if (facts.defaultPrevented) return native('prevented');
+  if (facts.button !== 0 || facts.modified) return native('modified');
+  if (facts.target !== '' && facts.target !== '_self') return native('target');
+  if (facts.download) return native('download');
+  if (facts.rel.split(/\s+/).includes('external')) return native('external');
+  if (facts.reload) return native('opt-out');
+  const to = new URL(facts.href);
+  const from = new URL(facts.current);
+  if (to.origin !== from.origin || (to.protocol !== 'http:' && to.protocol !== 'https:')) {
+    return native('cross-origin');
+  }
+  if (hashOnly(to, from)) return native('hash');
+  return { kind: 'soft', url: to.href };
+}
+
+/** What a hover or focus on a link tells the router, before anyone has clicked. */
+export interface PrefetchFacts {
+  /** The URL `linkVerdict` would follow softly. */
+  readonly url: string;
+  readonly noPrefetch: boolean;
+  /** `navigator.connection` — absent in a browser that does not say. */
+  readonly saveData?: boolean | undefined;
+  readonly effectiveType?: string | undefined;
+}
+
+/** The connections a guess costs too much on: every byte of a wrong one is the visitor's. */
+const SLOW_CONNECTIONS: ReadonlySet<string> = new Set(['slow-2g', '2g']);
+
+/**
+ * Whether the router may ASK for `url` before it is clicked. Only asking: the server answers a
+ * prefetch of any route that did not declare `navigation: 'prefetch'` with an empty `204` before
+ * it runs anything (`@ultimat3/http`'s navigation gate), so a GET that records something — a
+ * download, a click, a token opened — is never executed by a hover, whatever its path is called.
+ */
+export function mayPrefetch(facts: PrefetchFacts): boolean {
+  if (facts.noPrefetch || facts.saveData === true) return false;
+  return facts.effectiveType === undefined || !SLOW_CONNECTIONS.has(facts.effectiveType);
+}
+
+export type FormVerdict =
+  | { readonly kind: 'get'; readonly url: string }
+  | { readonly kind: 'post'; readonly url: string; readonly encoding: 'urlencoded' | 'multipart' }
+  | { readonly kind: 'native'; readonly reason: NativeReason };
+
+/** What a `submit` tells the router — the submitter's `formmethod`/`formaction` already applied. */
+export interface FormFacts {
+  /** Resolved action URL. */
+  readonly action: string;
+  readonly current: string;
+  /** Lower case: `get`, `post` or `dialog`. */
+  readonly method: string;
+  readonly enctype: string;
+  readonly target: string;
+  readonly defaultPrevented: boolean;
+  readonly reload: boolean;
+  /** A file input with a file chosen: an upload is the browser's, with its own progress. */
+  readonly hasFile: boolean;
+  /** The fields, for a GET — the query the browser would have built. */
+  readonly fields: readonly (readonly [string, string])[];
+}
+
+export function formVerdict(facts: FormFacts): FormVerdict {
+  if (facts.defaultPrevented) return native('prevented');
+  if (facts.target !== '' && facts.target !== '_self') return native('target');
+  if (facts.reload) return native('opt-out');
+  if (facts.method !== 'get' && facts.method !== 'post') return native('method');
+  // `text/plain` is the browser's own encoding, with no `fetch` body that reproduces it byte for byte.
+  if (facts.method === 'post' && facts.enctype === 'text/plain') return native('encoding');
+  const to = new URL(facts.action);
+  if (to.origin !== new URL(facts.current).origin) return native('cross-origin');
+  if (facts.method === 'get') {
+    // The browser REPLACES the action's query with the fields, and so does this.
+    to.search = new URLSearchParams(facts.fields.map(([k, v]) => [k, v])).toString();
+    return { kind: 'get', url: to.href };
+  }
+  if (facts.hasFile) return native('file');
+  return {
+    kind: 'post',
+    url: to.href,
+    encoding: facts.enctype === 'multipart/form-data' ? 'multipart' : 'urlencoded',
+  };
+}
+
+export type ResponseVerdict =
+  /** Put the answer in place of this document. */
+  | { readonly kind: 'swap' }
+  /** A redirect the server handed over, on this origin: the router's own next request. */
+  | { readonly kind: 'follow'; readonly url: string }
+  /** A real navigation to `url`: the browser asks for it, once. */
+  | { readonly kind: 'load'; readonly url: string; readonly reason: string }
+  /** Not a page: the bytes already received go to the browser — saved or shown, never re-fetched. */
+  | { readonly kind: 'hand-over' }
+  /** A `204` with nowhere to go: the browser stays where it is, and so does the router. */
+  | { readonly kind: 'stay' }
+  /** A POST whose outcome cannot be shown: `NAVIGATION_ERROR_EVENT`, then a GET of this page. */
+  | { readonly kind: 'failed'; readonly reason: string };
+
+/** What the router knows once an answer arrives, read off the response and both documents. */
+export interface ResponseFacts {
+  readonly method: 'GET' | 'POST';
+  /** The URL this request asked for. */
+  readonly requested: string;
+  readonly status: number;
+  /** `redirect: 'manual'` met a redirect the server did not hand over (not a framework server). */
+  readonly opaqueRedirect: boolean;
+  /** `x-ultimate-location` on a `204`, resolved. */
+  readonly location: string | null;
+  readonly contentType: string;
+  /** Redirects the router already followed for this navigation. */
+  readonly hops: number;
+  /** This document's `<app>:<surface>`, and the answer's (`null` when it carries none). */
+  readonly surface: string | null;
+  readonly nextSurface: string | null;
+  /** `x-ultimate-build`: this document's, and the answer's header or meta. */
+  readonly build: string | null;
+  readonly nextBuild: string | null;
+  /** `ultimate-scope`: whose document this is. Absent means "rendered for nobody". */
+  readonly scope: string | null;
+  readonly nextScope: string | null;
+}
+
+const origin = (url: string): string => new URL(url).origin;
+const withoutFragment = (url: string): string => url.split('#')[0] ?? url;
+
+/**
+ * What to do with an answer. Every branch keeps one rule: nothing the router sent is sent again.
+ * A GET is loaded again only where no framework server answered it (an opaque redirect or skew on
+ * a static host); a POST never — after one, only the server knows what landed.
+ */
+export function responseVerdict(facts: ResponseFacts): ResponseVerdict {
+  const get = facts.method === 'GET';
+  const load = (url: string, reason: string): ResponseVerdict => ({ kind: 'load', url, reason });
+  if (facts.opaqueRedirect) {
+    return get
+      ? load(facts.requested, 'a redirect no framework server handed over')
+      : { kind: 'failed', reason: 'a redirect no framework server handed over' };
+  }
+  if (facts.status === 204) {
+    if (facts.location === null) return { kind: 'stay' };
+    if (origin(facts.location) !== origin(facts.requested))
+      return load(facts.location, 'another origin');
+    // The server asked for THIS url as a document: the route did not run, the browser runs it.
+    if (get && withoutFragment(facts.location) === withoutFragment(facts.requested)) {
+      return load(facts.location, 'the server asked for a document load');
+    }
+    if (facts.hops >= NAVIGATION_MAX_HOPS) return load(facts.location, 'too many redirects');
+    return { kind: 'follow', url: facts.location };
+  }
+  const skewed =
+    facts.build !== null && facts.nextBuild !== null && facts.build !== facts.nextBuild;
+  // A GET refused for skew (409 before any route ran) or rendered by another build: load it.
+  if (get && skewed) return load(facts.requested, 'another build');
+  if (!/^\s*text\/html\b/i.test(facts.contentType)) return { kind: 'hand-over' };
+  // A POST answered in place IS the page the browser would have shown, whatever rendered it —
+  // and when that is another principal's or build's, the caller stops trusting this tab
+  // (`answerMovesTab`): every later navigation is a real load.
+  if (!get) return { kind: 'swap' };
+  // An error page is the answer, whatever shell rendered it (the framework's own carries no
+  // surface meta): a load that wrote and then threw must not run a second time.
+  if (facts.status >= 400) return { kind: 'swap' };
+  if (facts.nextSurface === null || facts.nextSurface !== facts.surface) {
+    return load(facts.requested, 'another surface');
+  }
+  if (facts.scope !== facts.nextScope) return load(facts.requested, 'another principal');
+  return { kind: 'swap' };
+}
+
+/** A cached answer, as far as reuse is concerned. */
+export interface CachedFacts {
+  readonly status: number;
+  readonly html: boolean;
+  readonly location: string | null;
+  readonly noStore: boolean;
+  readonly ageMs: number;
+}
+
+/**
+ * Whether a prefetched answer may stand in for the click: a 2xx page, nothing handed over, and —
+ * when the server said `no-store` — only within `NAVIGATION_NO_STORE_REUSE_MS` of being fetched.
+ * A failure, a redirect, an empty `204` is never an answer to reuse.
+ */
+export function reusable(facts: CachedFacts): boolean {
+  if (facts.status < 200 || facts.status > 299 || facts.status === 204) return false;
+  if (!facts.html || facts.location !== null) return false;
+  return !facts.noStore || facts.ageMs < NAVIGATION_NO_STORE_REUSE_MS;
+}
+
+/**
+ * An answer swapped in although it belongs to another principal or build (a POST answered in place,
+ * which cannot be asked for again). The tab's fence, its cache and its islands were set up for the
+ * old one, so after it every navigation is a real document load, and every tab's cache is emptied.
+ */
+export function answerMovesTab(facts: ResponseFacts): boolean {
+  const skewed =
+    facts.build !== null && facts.nextBuild !== null && facts.build !== facts.nextBuild;
+  return skewed || facts.scope !== facts.nextScope;
+}

package/src/navigation-swap.ts

@@ -0,0 +1,297 @@
+/**
+ * Puts a fetched document in place of the current one, in one order: its stylesheets loaded (no
+ * unstyled frame), this page's islands disposed, the body replaced with persisted elements carried
+ * across, the head brought level, and the document's own scripts run — which re-runs the ONE
+ * island bootstrap (`hydrate.ts`'s runtime) over the new body. There is no second mount path.
+ */
+
+import { NAVIGATION_PERSIST_ATTRIBUTE } from './navigation-rules';
+
+/** What `hydrate.ts`'s runtime leaves on an island root: the boot promise and the visited mark. */
+interface IslandElement extends Element {
+  __x?: Promise<unknown>;
+}
+
+const ISLAND_SELECTOR = '[data-x-island]';
+const STYLESHEET = 'link[rel~="stylesheet"]';
+
+const isStylesheet = (el: Element): boolean =>
+  el.tagName === 'LINK' && /\bstylesheet\b/i.test(el.getAttribute('rel') ?? '');
+
+/** A script type the parser executes — JSON (island props, JSON-LD) is data. */
+const executes = (script: Element): boolean =>
+  script.tagName === 'SCRIPT' && !/json$/i.test(script.getAttribute('type') ?? '');
+
+/**
+ * Diffed by markup: everything but a script that executes (it ran, or runs through `runScripts`)
+ * and a stylesheet (loaded before the swap, retired after it). JSON-LD is data, so it is replaced.
+ */
+const isDiffed = (el: Element): boolean => !executes(el) && !isStylesheet(el);
+
+/**
+ * The head, brought level by MARKUP: a tag identical in both stays (no reflow, no refetch), one
+ * only this document has goes, one only the next has arrives. Covers every route-owned tag —
+ * title, description, robots, canonical, alternates, Open Graph, JSON-LD — without a list of
+ * names that the next SEO tag would be missing from.
+ */
+export function headPlan(
+  current: readonly Element[],
+  next: readonly Element[],
+): { readonly remove: readonly Element[]; readonly add: readonly Element[] } {
+  const have = new Set(current.filter(isDiffed).map((el) => el.outerHTML));
+  const want = new Set(next.filter(isDiffed).map((el) => el.outerHTML));
+  return {
+    remove: current.filter((el) => isDiffed(el) && !want.has(el.outerHTML)),
+    add: next.filter((el) => isDiffed(el) && !have.has(el.outerHTML)),
+  };
+}
+
+/** The next document's stylesheets this one has not loaded, as hrefs. */
+export function missingStylesheets(doc: Document, next: Document): readonly string[] {
+  const loaded = new Set(
+    [...doc.querySelectorAll<HTMLLinkElement>(STYLESHEET)].map((link) => link.href),
+  );
+  return [...next.querySelectorAll<HTMLLinkElement>(STYLESHEET)]
+    .map((link) => new URL(link.getAttribute('href') ?? '', doc.baseURI).href)
+    .filter((href) => !loaded.has(href));
+}
+
+/** Resolves once every sheet loaded OR failed — a missing sheet must not hang the navigation. */
+export function loadStylesheets(doc: Document, hrefs: readonly string[]): Promise<void> {
+  return Promise.all(
+    hrefs.map(
+      (href) =>
+        new Promise<void>((done) => {
+          const link = doc.createElement('link');
+          link.rel = 'stylesheet';
+          link.href = href;
+          link.onload = () => done();
+          link.onerror = () => done();
+          doc.head.append(link);
+        }),
+    ),
+  ).then(() => undefined);
+}
+
+/**
+ * Calls each island's disposer — what its `mount` returned, held by `el.__x` — unless the island
+ * is carried across. A rejected boot has nothing to dispose, and the rejection is already on the
+ * element as `data-x-failed`.
+ */
+export function disposeIslands(root: Element, kept: (el: Element) => boolean): number {
+  let disposed = 0;
+  for (const el of root.querySelectorAll<IslandElement>(ISLAND_SELECTOR)) {
+    if (kept(el) || el.__x === undefined) continue;
+    disposed += 1;
+    el.__x.then(
+      (dispose) => {
+        if (typeof dispose === 'function') dispose();
+      },
+      () => undefined,
+    );
+  }
+  return disposed;
+}
+
+/** `[data-x-persist="id"]` present in BOTH documents: the live element moves into the next body. */
+export function persistedPairs(
+  current: ParentNode,
+  next: ParentNode,
+): readonly (readonly [Element, Element])[] {
+  const pairs: (readonly [Element, Element])[] = [];
+  for (const incoming of next.querySelectorAll(`[${NAVIGATION_PERSIST_ATTRIBUTE}]`)) {
+    const id = incoming.getAttribute(NAVIGATION_PERSIST_ATTRIBUTE) ?? '';
+    const live = [...current.querySelectorAll(`[${NAVIGATION_PERSIST_ATTRIBUTE}]`)].find(
+      (el) => el.getAttribute(NAVIGATION_PERSIST_ATTRIBUTE) === id,
+    );
+    if (id !== '' && live !== undefined) pairs.push([live, incoming]);
+  }
+  return pairs;
+}
+
+/**
+ * Re-creates executable scripts so they run: a script parsed by `DOMParser` is inert wherever it
+ * is inserted. A `src` this tab already ran is left alone (the page boot runs once per tab, as it
+ * does once per load); an inline one runs again — the hydration runtime, which skips every island
+ * it already visited. In document order, each `src` awaited, so a deferred boot still runs before
+ * the island modules that follow it. `place` puts the fresh copy where it belongs: in place of the
+ * inert one in a body, appended to the head. A `src` is recorded only once it is IN the document.
+ */
+export async function runScripts(
+  scripts: readonly HTMLScriptElement[],
+  ran: Set<string>,
+  place: (fresh: HTMLScriptElement, inert: HTMLScriptElement) => void,
+): Promise<void> {
+  for (const inert of scripts) {
+    if (!executes(inert)) continue;
+    const doc = inert.ownerDocument;
+    const src = inert.getAttribute('src');
+    const url = src === null ? null : new URL(src, doc.baseURI).href;
+    if (url !== null && ran.has(url)) continue;
+    const fresh = doc.createElement('script');
+    for (const attr of inert.attributes) fresh.setAttribute(attr.name, attr.value);
+    // `nonce` is hidden from the attribute once parsed; the property still carries it.
+    if (inert.nonce) fresh.nonce = inert.nonce;
+    fresh.textContent = inert.textContent;
+    if (url === null) {
+      place(fresh, inert);
+      continue;
+    }
+    fresh.async = false;
+    await new Promise<void>((done) => {
+      fresh.onload = () => done();
+      fresh.onerror = () => done();
+      place(fresh, inert);
+      ran.add(url);
+    });
+  }
+}
+
+/**
+ * The attributes a server document put on each persisted root: taken when the router starts (before
+ * any island or app script has run) and after every sync — the only ones a later page may remove.
+ */
+const serverAttributes = new WeakMap<Element, ReadonlySet<string>>();
+
+/** Snapshot the document's persisted roots; call once, when the router starts. */
+export function notePersisted(doc: Document): void {
+  for (const el of doc.querySelectorAll(`[${NAVIGATION_PERSIST_ATTRIBUTE}]`)) {
+    serverAttributes.set(el, new Set(el.getAttributeNames()));
+  }
+}
+
+/** Attributes the hydration runtime sets on an island root: the live element's, never a page's. */
+const RUNTIME_ATTRIBUTES: ReadonlySet<string> = new Set(['data-x-mounted', 'data-x-failed']);
+
+/** Where `el` (under `from`) sits under `to`: by id, else by the same child path and tag. */
+function counterpart(el: Element, from: Element, to: Element): Element | null {
+  if (el.id !== '') {
+    const byId = [...to.querySelectorAll('[id]')].find((other) => other.id === el.id);
+    if (byId !== undefined) return byId;
+  }
+  const path: number[] = [];
+  for (let at: Element = el; at !== from; ) {
+    const parent: Element | null = at.parentElement;
+    if (parent === null) return null;
+    path.unshift([...parent.children].indexOf(at));
+    at = parent;
+  }
+  let walked: Element | undefined = to;
+  for (const index of path) walked = walked?.children[index];
+  return walked !== undefined && walked.tagName === el.tagName ? walked : null;
+}
+
+/**
+ * A persisted element keeps its node, its state and its islands — and takes the incoming page's
+ * word for what it SAYS about the page: the root's attributes, and every descendant's
+ * `aria-current` with the `class` that styles it (the sidebar's active item moves).
+ */
+export function syncPersisted(kept: Element, incoming: Element): void {
+  // Only what a server document said may be unsaid: an attribute a script set at run time (a
+  // collapsed state, an island's marker) is the tab's, and survives like the node it sits on.
+  const said = serverAttributes.get(kept) ?? new Set(kept.getAttributeNames());
+  for (const name of said) {
+    if (!incoming.hasAttribute(name) && !RUNTIME_ATTRIBUTES.has(name)) kept.removeAttribute(name);
+  }
+  for (const attr of incoming.attributes) kept.setAttribute(attr.name, attr.value);
+  serverAttributes.set(kept, new Set(incoming.getAttributeNames()));
+  const pairs = new Map<Element, Element | null>();
+  for (const el of kept.querySelectorAll('[aria-current]')) {
+    pairs.set(el, counterpart(el, kept, incoming));
+  }
+  for (const el of incoming.querySelectorAll('[aria-current]')) {
+    const live = counterpart(el, incoming, kept);
+    if (live !== null) pairs.set(live, el);
+  }
+  for (const [live, next] of pairs) {
+    const current = next?.getAttribute('aria-current') ?? null;
+    if (current === null) live.removeAttribute('aria-current');
+    else live.setAttribute('aria-current', current);
+    const cls = next?.getAttribute('class') ?? null;
+    if (next !== null && next !== undefined) {
+      if (cls === null) live.removeAttribute('class');
+      else live.setAttribute('class', cls);
+    }
+  }
+}
+
+/**
+ * The head elements a server DOCUMENT put there — the only ones a swap may take away. Anything a
+ * script added at run time (a CSS-in-JS `<style>`, an analytics tag, a persisted island's own
+ * sheet) is the tab's, not the page's, and outlives every navigation as it would have outlived the
+ * page's own scripts.
+ */
+export function documentHead(doc: Document): WeakSet<Element> {
+  return new WeakSet(doc.head.children);
+}
+
+/**
+ * The swap itself, after the caller decided the answer IS a page for this tab. Synchronous from
+ * the dispose to the head, so a view transition's "after" snapshot is one consistent document.
+ * `owned` is `documentHead`'s set, kept by the caller across swaps and grown by each one.
+ */
+export function swapDocument(doc: Document, next: Document, owned: WeakSet<Element>): Swapped {
+  // Read before the head moves: `next.title` reads the `<title>` element, which the plan adopts.
+  const title = next.title;
+  const nextSheets = new Set(
+    [...next.head.querySelectorAll('link')]
+      .filter(isStylesheet)
+      .map((link) => new URL(link.getAttribute('href') ?? '', doc.baseURI).href),
+  );
+  // Inline head scripts by TEXT: one this page already ran (the theme boot, on every document)
+  // is not run again; one only the next page has runs once; one only this page had is dropped.
+  const inline = (head: HTMLHeadElement): HTMLScriptElement[] =>
+    [...head.querySelectorAll('script')].filter((s) => executes(s) && !s.hasAttribute('src'));
+  const ranInline = new Set(inline(doc.head).map((s) => s.textContent));
+  const nextInline = new Set(inline(next.head).map((s) => s.textContent));
+  const headScripts = [...next.head.querySelectorAll('script')].filter(
+    (script) =>
+      executes(script) && (script.hasAttribute('src') || !ranInline.has(script.textContent)),
+  );
+  for (const stale of inline(doc.head)) {
+    if (owned.has(stale) && !nextInline.has(stale.textContent)) stale.remove();
+  }
+  const pairs = persistedPairs(doc.body, next.body);
+  const live = pairs.map(([el]) => el);
+  disposeIslands(doc.body, (island) => live.some((kept) => kept.contains(island)));
+  for (const [kept, incoming] of pairs) {
+    syncPersisted(kept, incoming);
+    incoming.replaceWith(kept);
+  }
+  const body = doc.adoptNode(next.body);
+  doc.documentElement.replaceChild(body, doc.body);
+  const plan = headPlan(
+    [...doc.head.children].filter((el) => owned.has(el)),
+    [...next.head.children],
+  );
+  for (const el of plan.remove) el.remove();
+  for (const el of plan.add) {
+    doc.head.append(doc.adoptNode(el));
+    owned.add(el);
+  }
+  // Retired only now, after the next page's sheets loaded: the previous page's own, never a
+  // sheet a script added (not `owned`), never one both pages link.
+  for (const sheet of [...doc.head.querySelectorAll('link')].filter(isStylesheet)) {
+    const href = new URL(sheet.getAttribute('href') ?? '', doc.baseURI).href;
+    if (owned.has(sheet) && !nextSheets.has(href)) sheet.remove();
+  }
+  for (const sheet of [...doc.head.querySelectorAll('link')].filter(isStylesheet)) {
+    if (nextSheets.has(new URL(sheet.getAttribute('href') ?? '', doc.baseURI).href))
+      owned.add(sheet);
+  }
+  // `lang` and `dir` are the document's; `data-theme` and the rest belong to this tab's scripts.
+  for (const name of ['lang', 'dir']) {
+    const value = next.documentElement.getAttribute(name);
+    if (value === null) doc.documentElement.removeAttribute(name);
+    else doc.documentElement.setAttribute(name, value);
+  }
+  doc.title = title;
+  return { body, headScripts };
+}
+
+/** What the caller still owes the new document once the view transition has painted it. */
+export interface Swapped {
+  readonly body: HTMLElement;
+  /** The next page's `<script src>` in its head, still inert — `runScripts` them into the head. */
+  readonly headScripts: readonly HTMLScriptElement[];
+}

package/src/navigation-tags.ts

@@ -0,0 +1,38 @@
+/**
+ * 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), and the router's
+ * script. A surface that did not opt in gets none of the three, so it pays no byte.
+ */
+
+import { CLIENT_BUILD_META } from '@ultimat3/core';
+import type { HeadTag } from './head';
+import { NAVIGATION_META } from './navigation-rules';
+
+export interface ClientNavigationHead {
+  /** The surface this document belongs to — a link that lands on another is a full load. */
+  readonly surface: string;
+  readonly buildId: string;
+  /** `/_x/navigation/<hash>.js`, content-addressed and served `immutable`. */
+  readonly scriptUrl: string;
+}
+
+export function clientNavigationTags(head: ClientNavigationHead): readonly HeadTag[] {
+  return [
+    {
+      kind: 'meta',
+      key: `meta:${NAVIGATION_META}`,
+      attrs: { name: NAVIGATION_META, content: head.surface },
+    },
+    {
+      kind: 'meta',
+      key: `meta:${CLIENT_BUILD_META}`,
+      attrs: { name: CLIENT_BUILD_META, content: head.buildId },
+    },
+    // Deferred, in `<head>`: it runs once, after parsing, and survives every swap of the body.
+    {
+      kind: 'script',
+      key: 'script:ultimate-navigation',
+      attrs: { src: head.scriptUrl, defer: true },
+    },
+  ];
+}