@brust/runtime-dom 2.0.0-alpha.24 → 2.0.0-alpha.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brust/runtime-dom",
-  "version": "2.0.0-alpha.24",
+  "version": "2.0.0-alpha.26",
   "type": "module",
   "exports": {
     ".": {

package/src/directives/bind.ts

@@ -1,3 +1,4 @@
+import { reactEvent } from './on'
 import { BINDERS, parsed, read, warnOnce } from '../core-api'
 import { BOOLEAN, OVERLOADED, STRINGIFY } from '../attr-kinds'
 import type { Instance } from '../instance'
@@ -11,6 +12,8 @@ function writeAttr(inst: Instance, attr: string, el: Element, name: string, v: u
   // setAttribute: `className` is a getter-only SVGAnimatedString on SVG elements (F96a).
   // F311: undefined/null removes `class` (React does; `className=""` keeps an empty one), and an empty `style` is no attribute (the first paint omits it)
   if (name === 'class') { if (v == null) el.removeAttribute('class'); else el.setAttribute('class', `${v}`); return }
+  // F434: a multiple select is bound to an array, one pick per option (`null`/`undefined` leave the picks alone, as React does)
+  if (name === 'value' && el instanceof HTMLSelectElement && el.multiple) { if (v != null) { const vs = ([] as unknown[]).concat(v).map(String); for (const o of el.options) o.selected = vs.includes(o.value) } return }
   if (name === 'value' && 'value' in el) { (el as HTMLInputElement).value = v == null ? '' : String(v); return }
   // React passes every attribute of a custom element (a tag with `-`) through as given: `true` is ``, `false` omits it.
   const custom = el.localName.includes('-')
@@ -54,6 +57,20 @@ BINDERS.push({
   match: (a) => a.startsWith('x-prop-'),
   bind: ({ inst, el, attr, raw }) => {
     const name = attr.slice('x-prop-'.length)
+    // F369c: `x-prop-on-<event>="<prop key>"` calls the instance's prop (a function a caller handed through the child's rest)
+    // with the event, reading it at call time so a prop that changes is the one that runs. The event is `[a-z0-9]+`.
+    if (name.startsWith('on-')) {
+      const event = name.slice(3)
+      if (!raw || !/^[a-z0-9]+$/.test(event)) { warnOnce(`pb:${inst.name}:${name}`, `${attr} in ${inst.name} refused`); return }
+      const handler = (e: Event) => {
+        reactEvent(e)
+        const ps = inst.props(); const fn = Object.hasOwn(ps, raw) ? ps[raw] : undefined
+        if (typeof fn === 'function') (fn as (e: Event) => void)(e)
+      }
+      el.addEventListener(event, handler)
+      inst.onCleanup(() => el.removeEventListener(event, handler))
+      return
+    }
     if (!name || !raw || name.startsWith('on') || name.startsWith('x-') || PROP_REFUSED.has(name)) {
       warnOnce(`pb:${inst.name}:${name}`, `${attr} in ${inst.name} refused`); return
     }

package/src/directives/common.ts

@@ -23,6 +23,7 @@ export function member(inst: Instance, p: ParsedValue, attr: string): unknown {
 }
 export function mismatch(inst: Instance, attr: string, _el: Element, server: unknown, client: unknown): void {
   if (inst.booted) return   // element created after mount (new x-for row / x-if clone): nothing was server-rendered
+  if (inst.late) return   // F301: mounted after the page booted (a navigation's markup, a React client mount): no first paint to compare
   if (inst.reseeded) return   // F277: a host created later, started from its parent's current props, not the printed ones
   warnOnce(`x:${inst.name}:${attr}`, `first-paint mismatch ${attr} in ${inst.name}: ${JSON.stringify(server)} vs ${JSON.stringify(client)}`)
 }

package/src/directives/model.ts

@@ -17,9 +17,10 @@ BINDERS.push({
       const h = () => { if (input.checked) s.set(input.value) }; el.addEventListener('change', h); inst.onCleanup(() => el.removeEventListener('change', h))
       inst.effect(() => { input.checked = s() === input.value })
     } else if (el instanceof HTMLSelectElement) {
-      if (el.multiple) { warnOnce(`mm:${inst.name}`, `select[multiple] unsupported`); return }
-      const h = () => s.set(el.value); el.addEventListener('change', h); inst.onCleanup(() => el.removeEventListener('change', h))
-      const apply = () => { const v = s(); if (el.value !== String(v)) el.value = String(v ?? '') }
+      // F434: a multiple select is an array of the picked values
+      const many = el.multiple
+      const h = () => s.set(many ? Array.from(el.options).filter((o) => o.selected).map((o) => o.value) : el.value); el.addEventListener('change', h); inst.onCleanup(() => el.removeEventListener('change', h))
+      const apply = () => { const v = s(); if (many) { if (v != null) { const vs = ([] as unknown[]).concat(v).map(String); for (const o of el.options) o.selected = vs.includes(o.value) } } else if (el.value !== String(v)) el.value = String(v ?? '') }
       inst.effect(apply)
       const mo = new MutationObserver(() => apply()); mo.observe(el, { childList: true }); inst.onCleanup(() => mo.disconnect())
     } else {

package/src/directives/on.ts

@@ -10,13 +10,17 @@ const SYNTHETIC: PropertyDescriptorMap = {
   isPersistent: { value: () => true },
   nativeEvent: { get(this: Event) { return this } },
 }
+/** Gives a DOM event the React members (once). Shared with `x-prop-on-*`. */
+export function reactEvent(e: Event): void {
+  if (!('isPropagationStopped' in e)) Object.defineProperties(e, SYNTHETIC)
+}
 BINDERS.push({
   match: (a) => a.startsWith('x-on-'),
   bind: ({ inst, el, attr, raw, scope }) => {
     const event = attr.slice('x-on-'.length)
     const p = parsed(inst, attr, raw); if (!p) return
     const handler = (e: Event) => {
-      if (!('isPropagationStopped' in e)) Object.defineProperties(e, SYNTHETIC)
+      reactEvent(e)
       const fn = member(inst, p, attr)
       if (typeof fn !== 'function') return
       const args = p.bindings.map((b) => scope[b])

package/src/island.ts

@@ -3,7 +3,9 @@
 // hydrates each host once, when idle (spec S12). Load order between runtime and chunks is free.
 import { warnOnce, insideRaw } from './core-api'
 
-export type IslandHydrate = (host: HTMLElement, props: Record<string, unknown>) => void
+/** Hydrates `host`. It may return a dispose function (the React shim returns `() => root.unmount()`): the runtime
+ *  calls it once, when the host leaves the document, so effects clean up like a React route change. */
+export type IslandHydrate = (host: HTMLElement, props: Record<string, unknown>) => void | (() => void)
 type QueueEntry = [string, IslandHydrate]
 declare global { var __brustIslands: QueueEntry[] | undefined; var __brustIslandReady: (() => void) | undefined }
 
@@ -45,6 +47,8 @@ let idle: Idle = defaultIdle
 export function _setIdle(fn: Idle | null): void { idle = fn ?? defaultIdle }
 
 const pending = new Set<HTMLElement>()
+/** Dispose functions of hydrated hosts, until the host leaves the document. */
+const live = new Map<HTMLElement, () => void>()
 
 function readIslandProps(host: HTMLElement, id: string): Record<string, unknown> {
   const raw = host.getAttribute('x-props')
@@ -56,7 +60,11 @@ function readIslandProps(host: HTMLElement, id: string): Record<string, unknown>
 function hydrateHost(host: HTMLElement, id: string, hydrate: IslandHydrate): void {
   pending.delete(host)
   if (!host.isConnected || host.hasAttribute('data-hydrated')) return
-  try { hydrate(host, readIslandProps(host, id)); host.setAttribute('data-hydrated', '1') }
+  try {
+    const dispose = hydrate(host, readIslandProps(host, id))
+    if (typeof dispose === 'function') live.set(host, dispose)
+    host.setAttribute('data-hydrated', '1')
+  }
   catch (e) { console.error(`[brust] hydrate threw: ${id}`, e) }
 }
 
@@ -74,16 +82,24 @@ export function scheduleIslands(root: ParentNode): void {
   root.querySelectorAll<HTMLElement>('brust-island[data-id]').forEach(scheduleHost)
 }
 
-/** Forget pending hosts under a subtree that left the document. */
+/** A subtree left the document: forget its pending hosts and unmount the roots of its hydrated ones. */
 export function cancelIslands(root: Node): void {
   if (!(root instanceof Element)) return
-  if (root instanceof HTMLElement && pending.has(root)) pending.delete(root)
-  root.querySelectorAll<HTMLElement>('brust-island[data-id]').forEach((h) => pending.delete(h))
+  const hosts = root.querySelectorAll<HTMLElement>('brust-island[data-id]')
+  const forget = (h: HTMLElement) => {
+    pending.delete(h)
+    const dispose = live.get(h)
+    if (!dispose) return
+    live.delete(h)
+    try { dispose() } catch (e) { console.error('[brust] island unmount threw', e) }
+  }
+  if (root instanceof HTMLElement) forget(root)
+  hosts.forEach(forget)
 }
 
 /** Test helper: forget registrations, waiters, pending hosts and the global queue. */
 export function _resetIslands(): void {
-  slots.clear(); pending.clear(); idle = defaultIdle
+  slots.clear(); pending.clear(); live.clear(); idle = defaultIdle
   globalThis.__brustIslands = []
   globalThis.__brustIslandReady = undefined
 }

package/src/mount.ts

@@ -93,6 +93,6 @@ function startObserver(root: ParentNode): void {
   observer.observe(root, { childList: true, subtree: true })
 }
 export function unmount(root: ParentNode = document.body): void {
-  if (root === observedRoot) { observer?.disconnect(); observer = null; observedRoot = null }
+  if (root === observedRoot) { observer?.disconnect(); observer = null; observedRoot = null; pageBooted = false }   // torn down: the next mount() is a fresh boot
   disposeTree(root as Node)
 }

package/src/nav/chain.ts

@@ -0,0 +1,57 @@
+// The layout chain of a brust document (design §5.9): the root level from the nav tag's `data-brust-root`, then the
+// `<!--brust-l:<id>:<hash>-->…<!--/brust-l:<id>-->` pairs the server wraps around every inner level, outermost first.
+
+/** One level: `key` is `<id>:<shellHash>`; an inner level has its two comments. */
+export interface Level { key: string; open?: Comment; close?: Comment }
+
+/** null when the document has no usable chain (no root, unbalanced, crossing or sibling pairs): swap the whole body. */
+export function readChain(doc: Document): Level[] | null {
+  const root = doc.querySelector('script[data-brust-nav]')?.getAttribute('data-brust-root')
+  if (!root || !doc.body) return null
+  const out: Level[] = [{ key: root }]
+  const open: Level[] = []
+  const w = doc.createTreeWalker(doc.body, 128 /* NodeFilter.SHOW_COMMENT */)
+  for (let n: Node | null; (n = w.nextNode()); ) {
+    const v = (n as Comment).data
+    if (v.startsWith('brust-l:')) {
+      // a level opens inside the deepest open one, never beside a closed one: the chain is a line
+      if (open.length !== out.length - 1) return null
+      const l: Level = { key: v.slice(8), open: n as Comment }
+      out.push(l)
+      open.push(l)
+    } else if (v.startsWith('/brust-l:')) {
+      const l = open.pop()
+      if (!l || l.key.slice(0, l.key.lastIndexOf(':')) !== v.slice(9)) return null
+      l.close = n as Comment
+    }
+  }
+  return open.length ? null : out
+}
+
+/**
+ * A pair can be a range only when the parser kept its two comments siblings (a block in a `<p>` splits them), and not
+ * in a table section: there the comments stay put while the parser moves the content out in front of the table
+ * (foster parenting), so the range would hold nothing of the level.
+ */
+const usable = (l: Level) => l.open!.parentNode === l.close!.parentNode && !/^T(ABLE|BODY|HEAD|FOOT|R)$/.test(l.open!.parentNode!.nodeName)
+
+/**
+ * The level to replace: the first one whose id or hash differs, else the page (never kept), moved up while its pair is
+ * not a sibling pair in either document. 0 = the whole body.
+ */
+export function swapLevel(a: Level[] | null, b: Level[] | null): number {
+  if (!a || !b || a[0]!.key !== b[0]!.key) return 0
+  const leaf = Math.min(a.length, b.length) - 1
+  let i = 1
+  while (i < leaf && a[i]!.key === b[i]!.key) i++
+  if (i > leaf) return 0
+  while (i && !(usable(a[i]!) && usable(b[i]!))) i--
+  return i
+}
+
+/** The nodes of a level's range, both comments included. */
+export function between(l: Level): ChildNode[] {
+  const out: ChildNode[] = []
+  for (let n: ChildNode | null = l.open!; n; n = n === l.close ? null : n.nextSibling) out.push(n)
+  return out
+}

package/src/nav/index.ts

@@ -0,0 +1,5 @@
+// The `nav` asset (design §5.8): SPA navigation on every full brust document, also on a page that loads no runtime.
+// Standalone: nothing under nav/ imports the runtime core. `navigate()` reaches it through `Symbol.for('brust.nav')`.
+import { boot } from './nav'
+
+boot()

package/src/nav/nav.ts

@@ -0,0 +1,191 @@
+// SPA navigation (design docs/design/2026-10-25-spa-navigation-design.md): a qualifying link click, `navigate()` or
+// back/forward fetches the real HTML document and swaps it in place, so the page shows exactly what a full load of
+// that URL shows (§2). Anything that cannot be swapped is a full load. Events: `brust:nav:click|load|success|error`.
+import { applyHead, classicScripts, planHead, runScripts, swapBody } from './swap'
+
+type Trigger = 'link' | 'navigate' | 'popstate'
+export interface NavBridge { navigate(url: string, opts?: { replace?: boolean }): Promise<void> }
+/** How a module script of the new page is loaded; tests swap it. */
+export type Load = (url: string) => Promise<unknown>
+
+const KEY = Symbol.for('brust.nav')
+const LOADING = 'data-brust-loading'
+const NAV = 'script[data-brust-nav]'
+const sameDoc = (a: string, b: string) => a.split('#')[0] === b.split('#')[0]
+
+/** Boot once per tab. Returns a stop function (tests). */
+export function boot(load: Load = (u) => import(/* @vite-ignore */ u)): () => void {
+  const g = globalThis as { [KEY]?: NavBridge }
+  const build = document.querySelector(NAV)?.getAttribute('data-brust-build')
+  if (g[KEY] || build == null) return () => {}
+  const off = new AbortController()
+  const on = (t: EventTarget, type: string, h: (e: any) => void, capture?: boolean) =>
+    t.addEventListener(type, h, { capture, passive: type === 'touchstart', signal: off.signal })
+  const html = document.documentElement
+  const fire = (name: string, detail: object, cancelable?: boolean) =>
+    document.dispatchEvent(new CustomEvent('brust:nav:' + name, { detail, bubbles: true, cancelable }))
+
+  // ---- history entries: an id per entry in history.state.brust, scroll positions in memory (§5.7) ----
+  const stamp = Date.now().toString(36)
+  let n = 0
+  let seq = 0
+  const pos = new Map<string, [number, number]>()
+  const tag = (replaceUrl?: string) => {
+    const id = stamp + n++
+    history.replaceState({ ...history.state, brust: id }, '', replaceUrl)
+    return id
+  }
+  let cur: string = history.state?.brust ?? tag()
+  let shown = location.href
+  history.scrollRestoration = 'manual'
+  const land = (url: string, at?: [number, number]) => {
+    if (at) return scrollTo(at[0], at[1])
+    let t: Element | null = null
+    try { const h = decodeURIComponent(new URL(url).hash.slice(1)); t = h ? document.getElementById(h) : null } catch {}
+    t ? t.scrollIntoView() : scrollTo(0, 0)
+  }
+
+  // ---- prefetch on intent (§5.2): one response per URL, held 15 s, used once ----
+  const held = new Map<string, [Promise<Response>, number]>()
+  const take = (u: string) => {
+    const e = held.get(u)
+    held.delete(u)
+    return e && e[1] > Date.now() ? e[0] : undefined
+  }
+
+  /** The URL a link navigates to, or null when the click (or a prefetch) is left to the browser (§5.1). */
+  const target = (t: EventTarget | null): [Element, string] | null => {
+    const a = (t as Element | null)?.closest?.('a')
+    const href = a?.getAttribute('href')
+    if (href == null || a!.hasAttribute('download') || (a!.getAttribute('target') || '_self').toLowerCase() !== '_self' || a!.closest('[data-brust-reload]')) return null
+    let u: URL
+    try { u = new URL(href, document.baseURI) } catch { return null }
+    if (u.origin !== location.origin || !/^https?:$/.test(u.protocol) || (u.href.includes('#') && sameDoc(u.href, location.href))) return null
+    return [a!, u.href]
+  }
+
+  const prefetch = (t: EventTarget | null) => {
+    const l = target(t)
+    const c = (navigator as { connection?: { saveData?: boolean; effectiveType?: string } }).connection
+    if (!l || l[0].closest('[data-brust-prefetch="false"]') || c?.saveData || /2g/.test(c?.effectiveType ?? '')) return
+    const u = l[1]
+    if ((held.get(u)?.[1] ?? 0) > Date.now()) return
+    const p = fetch(u, { priority: 'low' } as RequestInit)
+    p.catch(() => {})
+    held.set(u, [p, Date.now() + 15e3])
+  }
+
+  // ---- one navigation (§3); a newer one aborts it and it fires nothing more ----
+  let active: AbortController | null = null
+  const go = async (req: string, trigger: Trigger, id: number, replace: boolean, pop?: string): Promise<void> => {
+    active?.abort()
+    const c = (active = new AbortController())
+    const live = () => c === active
+    const from = shown
+    let url = req
+    let status = 0
+    let pushed = false
+    const added: Element[] = []
+    html.setAttribute(LOADING, '')
+    fire('load', { id, url, from, trigger })
+    try {
+      const res = await (take(req) ?? fetch(req, { signal: c.signal }))
+      if (!live()) return
+      status = res.status
+      // the final URL (after redirects); a fetch drops the fragment, which a redirect without one keeps
+      const fin = new URL(res.url || req)
+      // a redirect that left this origin (an open redirect to a CORS-readable page) is never parsed: a full load
+      if (fin.origin !== location.origin) throw new Error('cross-origin')
+      fin.hash ||= new URL(req).hash
+      url = fin.href
+      const doc = /html/.test(res.headers.get('content-type') ?? '') ? new DOMParser().parseFromString(await res.text(), 'text/html') : null
+      if (!live()) return
+      if (doc?.querySelector(NAV)?.getAttribute('data-brust-build') !== build) throw new Error(`not a brust page of this build`)
+
+      // §3 step 4: everything the new page needs before it is shown. The store tags first, ahead of the old ones (a
+      // store seeds from the first tag of its name; a live store never re-reads one), then the module scripts in
+      // document order (one at a time: the order they register in is the order the server wrote), then the stylesheets
+      // the head plan inserted, with `media="not all"`: loaded and parsed, applied to nothing until the swap.
+      const stores = Array.from(doc.querySelectorAll('script[data-brust-store]'), (s) => document.importNode(s, true))
+      document.head.append(...stores)
+      added.push(...stores)
+      for (const s of doc.querySelectorAll('script[type=module][src]')) {
+        if (!s.matches(NAV)) await load(new URL(s.getAttribute('src')!, url).href)
+        if (!live()) return
+      }
+      const plan = planHead([...doc.head.children])
+      added.push(...plan.sheets.map(([e]) => e))
+      // a load event is a later task: the handlers set now still catch a cached sheet
+      await Promise.all(plan.sheets.map(([e]) => new Promise((r) => { (e as HTMLLinkElement).onload = (e as HTMLLinkElement).onerror = r })))
+      if (!live()) return
+
+      // §3 step 5: swap (one task, nothing painted in between), then history and scroll
+      for (const [e, m] of plan.sheets) m == null ? e.removeAttribute('media') : e.setAttribute('media', m)
+      pos.set(cur, [scrollX, scrollY])
+      const fresh = applyHead(plan)
+      const [body, whole] = swapBody(doc, LOADING)
+      added.length = 0
+      if (trigger === 'popstate') cur = pop || tag()
+      else if (replace) history.replaceState({ ...history.state, brust: cur }, '', url)
+      else history.pushState({ brust: (cur = stamp + n++) }, '', url)
+      pushed = true
+      shown = location.href
+      land(url, pos.get(pop!))
+      // the head scripts new to it run; after a whole-body swap (<html> and <body> attributes replaced) every one runs
+      // again, as on a full load (a theme script setting <html class>), but a data-brust-once one only if it is new
+      const head = whole ? [...document.head.children].filter((e) => !e.hasAttribute('data-brust-once') || fresh.includes(e)) : fresh
+      await runScripts([...classicScripts(head), ...body])
+      if (!live()) return
+      html.removeAttribute(LOADING)
+      if (status < 400) fire('success', { id, url, from, trigger, status })
+      else fire('error', { id, url, from, trigger, status, error: undefined, swapped: true })
+    } catch (error) {
+      if (!live()) return
+      html.removeAttribute(LOADING)
+      // nothing could be swapped: the default action is a full load of the URL (cancelable)
+      if (fire('error', { id, url, from, trigger, status, error, swapped: false }, true)) location[pushed || trigger === 'popstate' ? 'replace' : 'assign'](url)
+    } finally {
+      for (const e of added) e.remove()
+    }
+  }
+
+  const navigate = (u: string, o?: { replace?: boolean }): Promise<void> => {
+    const url = new URL(u, location.href).href
+    if (url.startsWith(location.origin + '/') && !document.body.closest('[data-brust-reload]') && !(url.includes('#') && sameDoc(url, location.href)))
+      return go(url, 'navigate', ++seq, !!o?.replace || sameDoc(url, location.href))
+    location[o?.replace ? 'replace' : 'assign'](url)
+    return Promise.resolve()
+  }
+  g[KEY] = { navigate }
+
+  on(document, 'click', (e: MouseEvent) => {
+    if (e.defaultPrevented || e.button || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return
+    const l = target(e.target)
+    if (!l) return
+    const id = ++seq
+    if (!fire('click', { id, url: l[1], from: shown, link: l[0] }, true)) return
+    e.preventDefault()
+    void go(l[1], 'link', id, sameDoc(l[1], location.href))
+  })
+  let hover: ReturnType<typeof setTimeout> | undefined
+  const isA = (t: EventTarget | null) => (t as Element | null)?.localName === 'a'
+  on(document, 'pointerenter', (e) => { if (isA(e.target)) hover = setTimeout(() => prefetch(e.target), 65) }, true)
+  on(document, 'pointerleave', (e) => { if (isA(e.target)) clearTimeout(hover) }, true)
+  on(document, 'focusin', (e) => prefetch(e.target))
+  on(document, 'touchstart', (e) => prefetch(e.target), true)
+  on(window, 'popstate', (e: PopStateEvent) => {
+    const to: string | undefined = e.state?.brust
+    if (sameDoc(location.href, shown)) {
+      // a fragment entry of the page on screen: the browser owns it; keep the scroll of the entry left
+      pos.set(cur, [scrollX, scrollY])
+      cur = to || tag()
+      shown = location.href
+      return land(shown, pos.get(cur))
+    }
+    void go(location.href, 'popstate', ++seq, false, to)
+  })
+  return () => {
+    off.abort()
+    delete g[KEY]
+  }
+}

package/src/nav/swap.ts

@@ -0,0 +1,148 @@
+// The DOM half of a navigation (design §3 step 5): the head made equal to the new head, then the body swapped whole or
+// from one layout level down (§5.9), persisted elements moved over, and the new classic scripts run.
+import { between, readChain, swapLevel } from './chain'
+
+/** `sheets`: the inserted stylesheets with their own `media` (null: none); they carry `media="not all"` until the swap. */
+const SHEET = 'link[rel~=stylesheet]'
+
+export interface HeadPlan { want: Element[]; fixed: Set<Element>; sheets: [Element, string | null][] }
+
+/**
+ * §3 step 5, planned before the swap: each new head element is matched to an unused old one with the same outerHTML
+ * (kept, never re-created) or is new. The kept elements already in the right order (the longest such run) never move.
+ * A new stylesheet, or a kept one out of that run, is inserted now at its final place (a clone for a kept one): a moved
+ * `<link>` drops its sheet until a later task, a visible flash, so no loaded stylesheet ever moves. They go in with
+ * `media="not all"` (loaded and parsed, applied to nothing) and come back in `sheets` for the caller to await.
+ */
+export function planHead(next: Element[]): HeadPlan {
+  const head = document.head
+  const old = [...head.children]
+  const pool = new Map<string, Element[]>()
+  for (const el of old) { const k = el.outerHTML; pool.has(k) ? pool.get(k)!.push(el) : pool.set(k, [el]) }
+  const want = next.map((n) => pool.get(n.outerHTML)?.shift() ?? n)
+  // the heaviest run of old elements already in order, a stylesheet outweighing everything else (a head is small:
+  // quadratic is fine)
+  const at = want.map((el) => old.indexOf(el))
+  const w: number[] = []
+  const prev: number[] = []
+  let best = -1
+  at.forEach((v, i) => {
+    if (v < 0) return
+    const own = want[i]!.matches(SHEET) ? 1e3 : 1
+    w[i] = own
+    prev[i] = -1
+    for (let j = 0; j < i; j++) if (at[j]! >= 0 && at[j]! < v && w[j]! + own > w[i]!) { w[i] = w[j]! + own; prev[i] = j }
+    if (best < 0 || w[i]! > w[best]!) best = i
+  })
+  const fixed = new Set<Element>()
+  for (let i = best; i >= 0; i = prev[i]!) fixed.add(want[i]!)
+  const sheets: HeadPlan['sheets'] = []
+  want.forEach((el, i) => {
+    if (fixed.has(el) || !el.matches(SHEET)) return
+    const s = el.ownerDocument === document ? (el.cloneNode() as Element) : document.adoptNode(el)
+    sheets.push([s, s.getAttribute('media')])
+    s.setAttribute('media', 'not all')
+    head.insertBefore(s, want.slice(i + 1).find((e) => fixed.has(e)) ?? null)
+    fixed.add((want[i] = s))
+  })
+  return { want, fixed, sheets }
+}
+
+/** Make the head's element children exactly `plan.want`, moving no fixed element. Returns the elements new to it. */
+export function applyHead({ want, fixed }: HeadPlan): Element[] {
+  const head = document.head
+  const keep = new Set(want)
+  for (const el of [...head.children]) if (!keep.has(el)) el.remove()
+  const fresh: Element[] = []
+  let prev: Element | null = null
+  for (let el of want) {
+    if (el.ownerDocument !== document) fresh.push((el = document.adoptNode(el)))
+    // the fixed elements are already in order: every other one goes right after the one before it
+    if (!fixed.has(el) && (prev ? prev.nextElementSibling : head.firstElementChild) !== el) prev ? prev.after(el) : head.prepend(el)
+    prev = el
+  }
+  return fresh
+}
+
+function copyAttrs(to: Element, from: Element, keep?: string): void {
+  for (const a of [...to.attributes]) if (a.name !== keep && !from.hasAttribute(a.name)) to.removeAttribute(a.name)
+  for (const a of from.attributes) to.setAttribute(a.name, a.value)
+}
+
+const all = (nodes: Node[], sel: string) =>
+  nodes.flatMap((n) => (n instanceof Element ? [...(n.matches(sel) ? [n] : []), ...n.querySelectorAll(sel)] : []))
+
+const P = '[data-brust-persist]'
+const key = (el: Element) => el.getAttribute('data-brust-persist')!
+
+/**
+ * A live `data-brust-persist` element replaces the inserted element with the same key, in the same task as the swap:
+ * it never leaves this document (no adoption into the parsed one), so it is moved, never disposed.
+ */
+function persist(old: Node[]): (next: Node[]) => void {
+  const live = new Map(all(old, P).map((el) => [key(el), el]))
+  return (next) => { for (const el of all(next, P)) { const k = live.get(key(el)); if (k) el.replaceWith(k) } }
+}
+
+/** The body-end assets: the nav tag and every node after it (store tags, module scripts). */
+function tail(body: HTMLElement): ChildNode[] | null {
+  const tag = body.querySelector(':scope > script[data-brust-nav]')
+  const out: ChildNode[] = []
+  for (let n: ChildNode | null = tag; n; n = n.nextSibling) out.push(n)
+  return tag && out
+}
+
+/**
+ * Swap the body to `doc`'s (§5.9): from the first level that changed, or the whole body (with the attributes of
+ * `<html>` and `<body>`) when the root changed or a chain cannot be trusted. Returns the classic scripts of the new
+ * nodes, taken before the persisted elements go in (a live one's scripts already ran: they never run again), and true
+ * for a whole-body swap.
+ */
+export function swapBody(doc: Document, loading: string): [HTMLScriptElement[], boolean] {
+  const body = document.body
+  const a = readChain(document)
+  const b = readChain(doc)
+  const i = swapLevel(a, b)
+  const ta = tail(body)
+  const tb = tail(doc.body)
+  if (i && ta && tb) {
+    const old = between(a![i]!)
+    const next = between(b![i]!)
+    const run = classicScripts([...next, ...tb])
+    const keep = persist(old)
+    // focus resets as on a full load, also when the focused element sits in a kept level
+    ;(document.activeElement as HTMLElement | null)?.blur?.()
+    for (const n of old.slice(1)) n.remove()
+    old[0]!.replaceWith(...next)
+    keep(next)
+    for (const n of ta) n.remove()
+    body.append(...tb)
+    return [run, false]
+  }
+  copyAttrs(document.documentElement, doc.documentElement, loading)
+  copyAttrs(body, doc.body)
+  const next = [...doc.body.childNodes]
+  const run = classicScripts(next)
+  const keep = persist([...body.childNodes])
+  body.replaceChildren(...next)
+  keep(next)
+  return [run, true]
+}
+
+const isClassic = (s: Element) => !(s as HTMLScriptElement).type || /java|ecma/i.test((s as HTMLScriptElement).type)
+
+/** The classic scripts among `nodes` (and under them), in document order. */
+export const classicScripts = (nodes: Node[]) => all(nodes, 'script').filter(isClassic) as HTMLScriptElement[]
+
+/** Run each script as a full load would: re-created (a parsed one never runs), one after the other, a `src` awaited. */
+export async function runScripts(list: HTMLScriptElement[]): Promise<void> {
+  for (const old of list) {
+    if (!old.isConnected) continue
+    const s = document.createElement('script')
+    for (const a of old.attributes) s.setAttribute(a.name, a.value)
+    s.text = old.text
+    const done = s.src && new Promise((r) => { s.onload = s.onerror = r })
+    old.replaceWith(s)
+    await done
+  }
+}