@brust/runtime-dom 2.0.0-alpha.25 → 2.0.0-alpha.27

package/package.json

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

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/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,282 @@
+// SPA navigation (design): 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>; clearCache(): 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 noHash = (u: string) => u.split('#')[0]!
+const sameDoc = (a: string, b: string) => noHash(a) === noHash(b)
+/** A fetched document as the cache holds it (§10.1). `no`: never kept (`no-store`, a status of 400 or more). */
+interface Got { status: number; url: string; type: string; text: string; no: boolean }
+type VT = { skipTransition(): void; updateCallbackDone: Promise<void> }
+const reduced = () => matchMedia('(prefers-reduced-motion: reduce)').matches
+const BAR = 'data-brust-bar'
+
+/** 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)
+  }
+
+  // ---- the page cache (§10.1): an LRU of 32 documents by URL without its hash, filled by prefetches and navigations,
+  // fresh for 5 minutes (`data-brust-cache` seconds), any age for back/forward; a fetch in flight (at: Infinity) is shared
+  const cache = new Map<string, [Promise<Got>, number]>()
+  const ttl = () => { const s = html.getAttribute('data-brust-cache'); return s == null || isNaN(+s) ? 3e5 : +s * 1e3 }
+  const get = (u: string, any?: boolean, init?: RequestInit): Promise<Got> => {
+    const k = noHash(u)
+    let e = cache.get(k)
+    cache.delete(k)
+    if (!e || !(any || Date.now() - e[1] < ttl())) {
+      const p = fetch(k, init).then(async (r) => ({ status: r.status, url: r.url, type: r.headers.get('content-type') ?? '', text: await r.text(), no: r.status >= 400 || /no-store/i.test(r.headers.get('cache-control') ?? '') }))
+      const f = (e = [p, Infinity])
+      const drop = () => cache.get(k) === f && cache.delete(k)
+      p.then((g) => (g.no || !ttl() ? drop() : (f[1] = Date.now())), drop)
+    }
+    cache.set(k, e)
+    if (cache.size > 32) cache.delete(cache.keys().next().value!)
+    return e[0]
+  }
+
+  // ---- the progress bar (§10.2): only for a navigation still loading 150 ms after `load`; outside <body>, so no swap
+  // removes it, and its <style> is runtime-added, so the head reconcile keeps it ----
+  let bar: Element | undefined
+  let css: HTMLStyleElement | undefined
+  let wait: ReturnType<typeof setTimeout> | undefined
+  const progress = (on?: boolean) => {
+    clearTimeout(wait)
+    if (on) {
+      if (!bar && html.getAttribute('data-brust-progress') !== 'off') wait = setTimeout(() => {
+        if (!css) {
+          ;(css = document.createElement('style')).textContent =
+            `div[${BAR}]{position:fixed;z-index:2147483647;top:0;left:0;width:100%;height:3px;pointer-events:none;background:var(--brust-progress-color,#2f7cf6);transform-origin:0;transform:scaleX(0);animation:brust-bar 8s cubic-bezier(.1,.7,.3,1) forwards}` +
+            `div[${BAR}=done]{animation:none;transform:none;opacity:0;transition:transform .2s,opacity .3s .2s}@keyframes brust-bar{to{transform:scaleX(.9)}}` +
+            `@media (prefers-reduced-motion:reduce){div[${BAR}]{animation:none;transform:scaleX(.9)}}`
+          css.setAttribute(BAR, '')
+        }
+        if (!css.isConnected) document.head.append(css)
+        html.append((bar = document.createElement('div')))
+        bar.setAttribute(BAR, '')
+      }, 150)
+    } else if (bar) {
+      const b = bar
+      bar = undefined
+      b.setAttribute(BAR, 'done')
+      setTimeout(() => b.remove(), reduced() ? 0 : 500)
+    }
+  }
+
+  // the head elements that came from the server (there at boot, or inserted from a fetched document): the only ones the
+  // head reconcile may remove (§3 step 5)
+  const served = new WeakSet<Element>(document.head.children)
+
+  /** 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
+    get(l[1], false, { priority: 'low' } as RequestInit).catch(() => {})
+  }
+
+  // ---- one navigation (§3); a newer one supersedes it (and skips its transition) and it fires nothing more ----
+  let active = 0
+  let vt: VT | undefined
+  const go = async (req: string, trigger: Trigger, id: number, replace: boolean, pop?: string): Promise<void> => {
+    vt?.skipTransition()
+    const me = ++active
+    const live = () => me === active
+    const from = shown
+    let url = req
+    let status = 0
+    let pushed = false
+    const added: Element[] = []
+    html.setAttribute(LOADING, '')
+    progress(true)
+    fire('load', { id, url, from, trigger })
+    try {
+      // not aborted when superseded: the response still fills the cache
+      const res = await get(req, trigger === 'popstate')
+      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.type) ? new DOMParser().parseFromString(res.text, 'text/html') : null
+      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
+      let fresh: Element[] = []
+      let body: HTMLScriptElement[] = []
+      let whole = false
+      const swap = () => {
+        if (!live()) return
+        for (const [e, m] of plan.sheets) m == null ? e.removeAttribute('media') : e.setAttribute('media', m)
+        pos.set(cur, [scrollX, scrollY])
+        for (const e of added) served.add(e)
+        fresh = applyHead(plan, (e) => served.has(e))
+        for (const e of fresh) served.add(e)
+        ;[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!))
+      }
+      // §10.3: the swap inside a view transition (a root cross-fade). Everything slow is done by now. The first 8 images of
+      // the new page that are not lazy and not on screen already are preloaded (the same candidate: srcset, sizes,
+      // crossorigin and referrerpolicy copied) and get 100 ms in all to decode, so none pops in after the fade. `swap`
+      // runs once: a throw from it rejects updateCallbackDone and takes the error path; a throw from startViewTransition
+      // itself is a direct swap.
+      const start = (document as { startViewTransition?: (u: () => void) => VT }).startViewTransition
+      let t: VT | undefined
+      if (start && html.getAttribute('data-brust-transition') !== 'off' && !reduced()) {
+        const abs = (u: string | null) => (u ? new URL(u, url).href : '')
+        const onScreen = new Set([...document.querySelectorAll('img')].flatMap((i) => [i.src, i.currentSrc]).filter(Boolean))
+        await Promise.race([
+          new Promise((r) => setTimeout(r, 100)),
+          Promise.all([...doc.querySelectorAll('img')]
+            .filter((i) => i.getAttribute('loading') !== 'lazy' && (i.hasAttribute('src') || i.hasAttribute('srcset')) && !onScreen.has(abs(i.getAttribute('src'))))
+            .slice(0, 8)
+            .map((i) => {
+              const m = new Image()
+              for (const a of ['crossorigin', 'referrerpolicy', 'sizes']) if (i.hasAttribute(a)) m.setAttribute(a, i.getAttribute(a)!)
+              const set = i.getAttribute('srcset')
+              if (set) m.srcset = set.replace(/(^|,)(\s*)([^\s,]+)/g, (_, c, w, u) => c + w + abs(u))
+              if (i.hasAttribute('src')) m.src = abs(i.getAttribute('src'))
+              return m.decode().catch(() => {})
+            })),
+        ])
+        if (!live()) return
+        try { vt = t = start.call(document, swap) } catch {}
+      }
+      t ? await t.updateCallbackDone : swap()
+      if (!live()) return
+      // the head scripts new to it run; after a whole-body swap (<html> and <body> attributes replaced) every one the
+      // server sent runs again, as on a full load (a theme script setting <html class>), but a data-brust-once one only
+      // if it is new, and one a component added at runtime never (a loader such as Stripe.js must not run twice). A
+      // re-created script is the server's too, so the next reconcile still removes it.
+      const head = whole ? [...document.head.children].filter((e) => served.has(e) && (!e.hasAttribute('data-brust-once') || fresh.includes(e))) : fresh
+      await runScripts([...classicScripts(head), ...body], (s) => served.add(s))
+      if (!live()) return
+      html.removeAttribute(LOADING)
+      progress()
+      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)
+      progress()
+      cache.delete(noHash(req))
+      // 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, clearCache: () => cache.clear() }
+
+  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
+    // the click navigates now: a hover intent still pending would refetch a page the cache does not keep
+    clearTimeout(hover)
+    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,153 @@
+// 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 `plan.want`, moving no fixed element. An old element not wanted is removed only if
+ * `served` says it came from the server: one a live component added at runtime stays. Returns the elements new to it.
+ */
+export function applyHead({ want, fixed }: HeadPlan, served: (el: Element) => boolean = () => true): Element[] {
+  const head = document.head
+  const keep = new Set(want)
+  for (const el of [...head.children]) if (!keep.has(el) && served(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.
+ *  `ran` gets each replacement, which stands for the old node from then on. */
+export async function runScripts(list: HTMLScriptElement[], ran?: (s: HTMLScriptElement) => void): 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)
+    ran?.(s)
+    await done
+  }
+}

package/src/store/define-store.ts

@@ -1,7 +1,7 @@
 // defineStore (M3-F D1): the 0.1.x `brustjs/store` handle on the shared reactive core and the
 // globalThis registry. Resolution (browser registry / server resolver) lives in ./registry.
 import { type Computed, type Signal, isSignal } from '../core-api'
-import { type StoreInstanceRecord, computeSnapshot, resolveRecord } from './registry'
+import { type StoreInstanceRecord, computeSnapshot, resolveRecord, ssrSnapshotOf } from './registry'
 
 // Unwrap a Signal/Computed to its value type; `never` if it is neither. Uses `infer` (not
 // `extends Signal<unknown>`): `Signal<T>.set(next: T)` is contravariant in T, so
@@ -83,7 +83,10 @@ export function defineStore<S extends object>(name: string, factory: () => S): S
     return computeSnapshot(rec) as Snapshot<S>
   }
   // The snapshot the SSR HTML was rendered from (browser); React islands hydrate against it. Absent on the server.
-  ;(handle as unknown as Record<symbol, unknown>)[Symbol.for('brust.ssrSnapshot')] = () => resolve().ssr ?? handle.snapshot()
+  ;(handle as unknown as Record<symbol, unknown>)[Symbol.for('brust.ssrSnapshot')] = () => {
+    const rec = resolve()
+    return ssrSnapshotOf(name, rec) ?? handle.snapshot()
+  }
   handle.serialize = () => {
     const out: Record<string, unknown> = {}
     for (const [k, s] of Object.entries(resolve().instance)) {

package/src/store/registry.ts

@@ -14,6 +14,8 @@ export interface StoreInstanceRecord {
   snap: { value: Record<string, unknown>; version: number } | null
   /** Browser only: the snapshot the SSR HTML was rendered from (script seed applied, nothing written since). Islands hydrate against it (G13). */
   ssr?: Record<string, unknown>
+  /** Browser only: the seed tag `ssr` was read from (`null` when the page carried none). */
+  ssrSeed?: Element | null
   handle?: { serialize(): Record<string, unknown> }
 }
 
@@ -76,12 +78,30 @@ export function resolveRecord(
     const made = (rec = reg[name] = create(false))
     const el = seedScript(name)
     if (el) seed(rec, parseStoreScript(el))
+    rec.ssrSeed = el
     // Identity-stable: the same object stays `rec.snap` until the first write.
     rec.ssr = untracked(() => computeSnapshot(made)) // a first access inside an effect must not subscribe it
   }
   return rec
 }
 
+const tagSnapshots = new WeakMap<Element, Record<string, unknown>>()
+
+/**
+ * The snapshot an island hydrating NOW must render from: the seed tag of the document it came from. A live store keeps
+ * `rec.ssr` from the first page (§5.5 of the SPA design), so an island on a page navigated to would otherwise hydrate
+ * against the first page's values. Keys the tag does not carry (computeds) keep the first snapshot's value.
+ */
+export function ssrSnapshotOf(name: string, rec: StoreInstanceRecord): Record<string, unknown> | undefined {
+  const base = rec.ssr
+  if (!base || typeof document === 'undefined') return base
+  const el = seedScript(name)
+  if (!el || el === rec.ssrSeed) return base
+  let snap = tagSnapshots.get(el)
+  if (!snap) tagSnapshots.set(el, (snap = { ...base, ...parseStoreScript(el) }))
+  return snap
+}
+
 /** Apply a navigation-payload snapshot to live client stores. Reserved for the SPA wave (D9): no callers yet. */
 export function applyStoreSnapshot(snap: Record<string, Record<string, unknown>>): void {
   const reg = (globalThis as { [STORES]?: Registry })[STORES]