@brust/runtime-dom 2.0.0-alpha.3 → 2.0.0-alpha.30

package/src/nav/nav.ts

@@ -0,0 +1,286 @@
+// 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, incomingImages, 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. The <style> goes first in the head
+  // and its rules are one attribute selector each, so an app rule on div[data-brust-bar] wins ----
+  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:var(--brust-progress-height,2px);pointer-events:none;background:var(--brust-progress-color,#2f7cf6);transform-origin:0;transform:scaleX(0);animation:brust-bar 8s cubic-bezier(.1,.8,.2,1) forwards}` +
+            `div[${BAR}=done]{animation:none;transform:none;opacity:0;transition:transform .2s,opacity .3s .2s}@keyframes brust-bar{to{transform:scaleX(.8)}}` +
+            `@media (prefers-reduced-motion:reduce){div[${BAR}]{animation:none;transform:scaleX(.8)}div[${BAR}=done]{transition:none}}`
+          css.setAttribute(BAR, '')
+        }
+        if (!css.isConnected) document.head.prepend(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, at the end of the body, after
+      // the old ones (a store seeds from the first tag of its name; a live store never re-reads one): an old-page island
+      // that hydrates while the modules load still finds its own page's tag, and a store new to this page, first read
+      // by one of its modules, finds the new one. The swap removes them with the old body tail. 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.body.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 the
+      // swap puts in (the changed level's, so a kept layout's never take a slot) 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(incomingImages(doc)
+            .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,160 @@
+// 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
+}
+
+/** The images `swapBody(doc)` will put in, before it runs: the changed level's, or the whole body's. */
+export function incomingImages(doc: Document): HTMLImageElement[] {
+  const b = readChain(doc)
+  const i = swapLevel(readChain(document), b)
+  return all(i && tail(document.body) && tail(doc.body) ? between(b![i]!) : [...doc.body.childNodes], 'img') as HTMLImageElement[]
+}
+
+/**
+ * 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/props-bind.ts

@@ -9,6 +9,16 @@ function scopeOf(el: Element): Record<string, unknown> {
   return {}
 }
 
+/** F277: the props a linked host starts with: its parent's current `x-props-bind` value when the parent is mounted (a
+ * host an `x-if` or a row creates after first paint gets what the parent passes NOW, as React mounts with the current
+ * props: a `useState(prop)` starts from it), else its printed `x-props`. */
+export function initialProps(host: HTMLElement, parent: Instance | null, printed: Record<string, unknown>): Record<string, unknown> {
+  const raw = host.getAttribute('x-props-bind'); if (!raw || !parent) return printed
+  const p = parseValue(raw); if (!p) return printed
+  const r = resolve(parent.members, p, scopeOf(host))
+  return r.ok && r.value && typeof r.value === 'object' ? (r.value as Record<string, unknown>) : printed
+}
+
 export function bindPropsFromParent(inst: Instance): void {
   const raw = inst.host.getAttribute('x-props-bind'); if (!raw) return
   const p = parseValue(raw)

package/src/registry.ts

@@ -3,9 +3,13 @@ import type { Dispose, Signal } from './signal'
 export interface BehaviorCtx {
   el: HTMLElement
   props: Signal<Record<string, unknown>>
-  effect: (fn: () => void | (() => void)) => Dispose
+  effect: (fn: () => void | (() => void), layout?: boolean) => Dispose
   onCleanup: (fn: () => void) => void
-  ref: <E extends Element = HTMLElement>(name: string) => { current: E | null }
+  ref: <E extends Element = HTMLElement>(name: string, init?: unknown) => { current: E | null }
+  /** True when this instance mounted after the page booted (an x-if clone, an x-for row, a navigation): nothing of it was server-rendered. */
+  late: boolean
+  /** The collection items under the nearest collection root of this instance, in document order (R34.141). */
+  items: () => Array<{ ref: { current: Element }; element: Element } & Record<string, unknown>>
 }
 export type BehaviorInstance = Record<string, unknown>
 export type BehaviorFactory = (ctx: BehaviorCtx) => BehaviorInstance | void

package/src/signal.ts

@@ -1,7 +1,7 @@
 // A small push-pull reactive core. Signals push "dirty" to subscribers; computeds pull lazily.
 type Subscriber = { mark(): void; deps: Set<Node> }
 type Node = { subs: Set<Subscriber> }
-type Runnable = { disposed: boolean; run(): void }
+type Runnable = { disposed: boolean; run(): void; tier?: number; id?: number }
 interface ReactiveCtx { currentSub: Subscriber | null; batchDepth: number; pending: Set<Runnable> }
 
 const CTX = Symbol.for('brust.reactive.ctx')          // M3-F C7
@@ -23,8 +23,13 @@ function flush() {
   if (ctx.batchDepth > 0) return
   const pending = ctx.pending
   while (pending.size) {
-    const batch = Array.from(pending); pending.clear()
-    for (const e of batch) if (!e.disposed) e.run()
+    // F288 (ruling 94404307 amended): a re-run follows React's commit order: every binding of the change (tier 0, in
+    // notify order), then compiled layout effects (1), then compiled passive effects (2), each in declaration order.
+    const all = Array.from(pending)
+    const t = Math.min(...all.map((e) => e.tier || 0))
+    // a stable sort: bindings (t = 0) keep their notify order
+    const run = all.filter((e) => (e.tier || 0) === t).sort((a, b) => t && a.id! - b.id!)
+    for (const e of run) pending.delete(e), e.disposed || e.run()
   }
 }
 
@@ -67,9 +72,11 @@ export function computed<T>(fn: () => T): Computed<T> {
 // Cleanups run untracked: a read inside one must not subscribe whichever effect is running around it.
 function runCleanup(c: () => void) { const prev = ctx.currentSub; ctx.currentSub = null; try { c() } finally { ctx.currentSub = prev } }
 
+let ids = 0
 class EffectImpl implements Subscriber {
   deps = new Set<Node>(); disposed = false; cleanup: void | (() => void) = undefined
-  constructor(private fn: () => void | (() => void)) {}
+  readonly id = ++ids
+  constructor(private fn: () => void | (() => void), readonly tier = 0) {}
   mark() { ctx.pending.add(this) }
   run() {
     if (this.disposed) return
@@ -86,9 +93,10 @@ class EffectImpl implements Subscriber {
   }
 }
 
-export function effect(fn: () => void | (() => void)): Dispose {
-  const e = new EffectImpl(fn)
-  e.run()
+/** `tier`: 0 a binding, 1 a compiled layout effect, 2 a compiled passive effect (the order of re-runs). */
+export function effect(fn: () => void | (() => void), tier = 0): Dispose {
+  const e = new EffectImpl(fn, tier)
+  try { e.run() } catch (x) { e.dispose(); throw x }   // F98: a first run that throws must not stay subscribed
   return () => e.dispose()
 }
 

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, isComputed, isSignal } from '../signal'
-import { type StoreInstanceRecord, resolveRecord } from './registry'
+import { type Computed, type Signal, isSignal } from '../core-api'
+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
@@ -80,14 +80,12 @@ export function defineStore<S extends object>(name: string, factory: () => S): S
   }
   handle.snapshot = () => {
     const rec = resolve()
-    if (rec.snap && rec.snap.version === rec.version.n) return rec.snap.value as Snapshot<S>
-    const out: Record<string, unknown> = {}
-    for (const key of Object.keys(rec.instance)) {
-      const v = (rec.instance as Record<string, unknown>)[key]
-      if (isSignal(v) || isComputed(v)) out[key] = v()
-    }
-    rec.snap = { value: out, version: rec.version.n }
-    return out as Snapshot<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')] = () => {
+    const rec = resolve()
+    return ssrSnapshotOf(name, rec) ?? handle.snapshot()
   }
   handle.serialize = () => {
     const out: Record<string, unknown> = {}

package/src/store/react.ts

@@ -10,7 +10,9 @@ export function useStore<S extends object>(store: StoreHandle<S> & S): Snapshot<
   // factory-default markup; the client resolves the real registry instance and hydrates.
   const serverSnapshot = (): Snapshot<S> => {
     try {
-      return store.snapshot()
+      // Hydration must see the markup the server rendered, not a value a native mount effect wrote since (#418).
+      const ssr = (store as unknown as Record<symbol, (() => Snapshot<S>) | undefined>)[Symbol.for('brust.ssrSnapshot')]
+      return ssr ? ssr() : store.snapshot()
     } catch {
       return {} as Snapshot<S>
     }

package/src/store/registry.ts

@@ -1,5 +1,6 @@
 // Browser store registry + the server-resolver hook (M3-F D3/D6/C7).
 // The registry lives on globalThis (C7) so two copies of this module share one instance per name.
+import { isComputed, isSignal, untracked } from '../core-api'
 import { parseStoreScript } from './serialize'
 
 // The resolved per-scope store record, shared by the browser registry and the server per-request
@@ -11,9 +12,25 @@ export interface StoreInstanceRecord {
   subs: Set<() => void>
   version: { n: number }
   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> }
 }
 
+/** Plain-value view of a record (signals and computeds read, actions dropped), memoized in `rec.snap` per version. */
+export function computeSnapshot(rec: StoreInstanceRecord): Record<string, unknown> {
+  if (rec.snap && rec.snap.version === rec.version.n) return rec.snap.value
+  const out: Record<string, unknown> = {}
+  for (const key of Object.keys(rec.instance)) {
+    const v = (rec.instance as Record<string, unknown>)[key]
+    if (isSignal(v) || isComputed(v)) out[key] = v()
+  }
+  rec.snap = { value: out, version: rec.version.n }
+  return out
+}
+
 export type ServerResolver = (name: string, create: () => StoreInstanceRecord) => StoreInstanceRecord
 
 const STORES = Symbol.for('brust.stores') // C7
@@ -58,13 +75,33 @@ export function resolveRecord(
   const reg = browserRegistry()
   let rec = reg[name]
   if (!rec) {
-    rec = reg[name] = create(false)
+    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]
@@ -77,6 +114,7 @@ export function applyStoreSnapshot(snap: Record<string, Record<string, unknown>>
       const v = inst[key]
       if (v && typeof v.set === 'function') v.set(state[key])
     }
+    entry.ssr = untracked(() => computeSnapshot(entry)) // R11.1: the payload is the new server truth for islands hydrating later
   }
 }