@invisibleloop/pulse 0.1.39 → 0.2.0

package/src/runtime/index.js

@@ -24,6 +24,9 @@ const showToast = (opts) => import('./toast.js').then(m => m.showToast(opts))
  * @param {Object} [serverState] - Serialised server state from SSR
  */
 export function mount(spec, el, serverState = {}, options = {}) {
+  if (!spec || spec.state === undefined || !spec.view) {
+    throw new Error('[Pulse] mount: spec must have state and view')
+  }
   // Spec is validated server-side at startup — no need to re-validate in the browser
   // Initialise the client store from SSR data (no-op after the first page mount).
   // window.__PULSE_STORE__ is serialised by the server when a store is registered.
@@ -119,9 +122,10 @@ export function mount(spec, el, serverState = {}, options = {}) {
       const raw = spec.mutations[type](state, payload)
       if (raw?._toast) showToast(raw._toast)
       const { _toast, ...partial } = raw ?? {}
+      const prev = state
       state = applyConstraints({ ...state, ...partial }, spec.constraints)
       persist()
-      render()
+      if (shallowChanged(prev, state)) render()
       return
     }
 
@@ -144,8 +148,9 @@ export function mount(spec, el, serverState = {}, options = {}) {
       const raw = action.onStart(currentState, payload)
       if (raw?._toast) showToast(raw._toast)
       const { _toast, ...partial } = raw ?? {}
+      const prev = state
       state = applyConstraints({ ...state, ...partial }, spec.constraints)
-      render()
+      if (shallowChanged(prev, state)) render()
     }
 
     // Validate before running if requested
@@ -156,8 +161,9 @@ export function mount(spec, el, serverState = {}, options = {}) {
         const raw = action.onError?.(state, { validation: errors }) ?? {}
         if (raw._toast) showToast(raw._toast)
         const { _toast, ...partial } = raw
+        const prev = state
         state = applyConstraints({ ...state, ...partial }, spec.constraints)
-        render()
+        if (shallowChanged(prev, state)) render()
         return
       }
     }
@@ -171,17 +177,20 @@ export function mount(spec, el, serverState = {}, options = {}) {
       if (raw._storeUpdate) updateStore(raw._storeUpdate)
       if (raw._toast)       showToast(raw._toast)
       const { _storeUpdate: _su, _toast: _t, ...partial } = raw
+      const prev = state
       state = applyConstraints({ ...state, ...partial }, spec.constraints)
+      if (shallowChanged(prev, state)) render()
     } catch (error) {
       console.error(`[Pulse] Action "${name}" failed:`, error)
       const raw = action.onError(state, error) ?? {}
       if (raw._toast) showToast(raw._toast)
       const { _toast, ...partial } = raw
+      const prev = state
       state = applyConstraints({ ...state, ...partial }, spec.constraints)
+      if (shallowChanged(prev, state)) render()
     }
 
     persist()
-    render()
   }
 
   // ---------------------------------------------------------------------------
@@ -359,9 +368,19 @@ function morph(el, newHtml) {
 }
 
 function morphNodes(cur, nxt) {
-  const curNodes = Array.from(cur.childNodes)
   const nxtNodes = Array.from(nxt.childNodes)
 
+  // Key-based reconciliation — activated when every element child carries data-key.
+  // Handles insert, remove, and reorder in O(n) without touching unaffected nodes.
+  const nxtEls = nxtNodes.filter(n => n.nodeType === 1)
+  if (nxtEls.length > 0 && nxtEls.every(n => n.getAttribute('data-key') !== null)) {
+    morphKeyed(cur, nxtEls)
+    return
+  }
+
+  // Position-based fallback for unkeyed content
+  const curNodes = Array.from(cur.childNodes)
+
   nxtNodes.forEach((nxtNode, i) => {
     const curNode = curNodes[i]
 
@@ -390,6 +409,50 @@ function morphNodes(cur, nxt) {
   while (cur.childNodes.length > nxtNodes.length) cur.removeChild(cur.lastChild)
 }
 
+/**
+ * Key-based reconciliation for a container whose element children all carry data-key.
+ * Builds a map of existing keyed nodes, then places new nodes in reverse order using
+ * insertBefore — O(n) moves, O(n) removals, zero unnecessary DOM patches.
+ *
+ * @param {Element} cur   - existing parent element
+ * @param {Element[]} nxtEls - ordered array of new element children (all have data-key)
+ */
+function morphKeyed(cur, nxtEls) {
+  // Index existing keyed children
+  const keyMap = new Map()
+  for (const node of cur.childNodes) {
+    if (node.nodeType === 1) {
+      const k = node.getAttribute('data-key')
+      if (k !== null) keyMap.set(k, node)
+    }
+  }
+
+  // Place elements in reverse order — insertBefore(node, ref) where ref tracks the
+  // right-hand boundary. When a node is already in the correct position, skip the move.
+  let ref = null
+  for (let i = nxtEls.length - 1; i >= 0; i--) {
+    const nxtEl = nxtEls[i]
+    const key   = nxtEl.getAttribute('data-key')
+    let   node  = keyMap.get(key)
+
+    if (node) {
+      keyMap.delete(key)
+      morphAttrs(node, nxtEl)
+      morphNodes(node, nxtEl)
+    } else {
+      node = nxtEl.cloneNode(true)
+    }
+
+    if (node.nextSibling !== ref || node.parentNode !== cur) {
+      cur.insertBefore(node, ref)
+    }
+    ref = node
+  }
+
+  // Remove elements no longer in the list
+  for (const node of keyMap.values()) cur.removeChild(node)
+}
+
 function morphAttrs(cur, nxt) {
   for (const { name, value } of Array.from(nxt.attributes)) {
     if (cur.getAttribute(name) !== value) cur.setAttribute(name, value)
@@ -451,7 +514,8 @@ function dispatchTimed(target, name, e, dispatch) {
 function applyConstraints(state, constraints) {
   if (!constraints) return state
 
-  const next = deepClone(state)
+  const hasNested = Object.keys(constraints).some(p => p.includes('.'))
+  const next = hasNested ? structuredClone(state) : state
 
   for (const [path, rules] of Object.entries(constraints)) {
     const { obj, key } = resolvePath(next, path)
@@ -570,7 +634,25 @@ function resolvePath(obj, path) {
  * @returns {Object}
  */
 function deepClone(obj) {
-  return JSON.parse(JSON.stringify(obj))
+  return structuredClone(obj)
+}
+
+/**
+ * Returns true when two flat state objects differ by reference at any key.
+ * Used to skip render() when a mutation produces no actual change —
+ * e.g. a constraint-clamped increment when already at max.
+ * Only compares top-level keys — nested objects are compared by reference,
+ * which is correct since mutations return new partial objects via spread.
+ *
+ * @param {Object} a
+ * @param {Object} b
+ * @returns {boolean}
+ */
+function shallowChanged(a, b) {
+  if (a === b) return false
+  const ka = Object.keys(a)
+  if (ka.length !== Object.keys(b).length) return true
+  return ka.some(k => a[k] !== b[k])
 }
 
 function viewErrorFallback(err) {

package/src/runtime/morph.test.js

@@ -0,0 +1,317 @@
+/**
+ * Pulse — morph / key-based reconciliation tests
+ * run: node src/runtime/morph.test.js
+ *
+ * Sets up a minimal DOM shim so morphNodes runs its real code path
+ * (not the innerHTML fallback). Tests verify node identity is preserved
+ * across updates — the key property of key-based reconciliation.
+ */
+
+// ---------------------------------------------------------------------------
+// Minimal DOM shim
+// ---------------------------------------------------------------------------
+
+class FakeText {
+  constructor(value) {
+    this.nodeType  = 3
+    this.nodeName  = '#text'
+    this.nodeValue = value
+    this.parentNode = null
+    this.nextSibling = null
+  }
+  cloneNode() { return new FakeText(this.nodeValue) }
+}
+
+class FakeElement {
+  constructor(tag) {
+    this.nodeType  = 1
+    this.nodeName  = tag.toUpperCase()
+    this._attrs    = {}
+    this._children = []
+    this.parentNode  = null
+    this.nextSibling = null
+  }
+
+  // ---- child access ----
+  get childNodes() { return this._children }
+  get lastChild()  { return this._children[this._children.length - 1] ?? null }
+
+  // ---- attributes ----
+  get attributes()        { return Object.entries(this._attrs).map(([name, value]) => ({ name, value })) }
+  getAttribute(n)         { return this._attrs[n] ?? null }
+  setAttribute(n, v)      { this._attrs[n] = v }
+  removeAttribute(n)      { delete this._attrs[n] }
+  hasAttribute(n)         { return n in this._attrs }
+
+  // ---- mutation ----
+  appendChild(node) {
+    if (node.parentNode) node.parentNode._detach(node)
+    const prev = this._children[this._children.length - 1]
+    if (prev) prev.nextSibling = node
+    node.nextSibling = null
+    node.parentNode  = this
+    this._children.push(node)
+    return node
+  }
+
+  removeChild(node) {
+    const i = this._children.indexOf(node)
+    if (i === -1) throw new Error('removeChild: node not a child')
+    this._children.splice(i, 1)
+    if (i > 0) this._children[i - 1].nextSibling = this._children[i] ?? null
+    node.parentNode  = null
+    node.nextSibling = null
+    return node
+  }
+
+  replaceChild(newNode, oldNode) {
+    const i = this._children.indexOf(oldNode)
+    if (i === -1) throw new Error('replaceChild: oldNode not a child')
+    if (newNode.parentNode) newNode.parentNode._detach(newNode)
+    this._children[i]  = newNode
+    newNode.parentNode = this
+    newNode.nextSibling = this._children[i + 1] ?? null
+    if (i > 0) this._children[i - 1].nextSibling = newNode
+    oldNode.parentNode  = null
+    oldNode.nextSibling = null
+    return oldNode
+  }
+
+  insertBefore(node, ref) {
+    if (node.parentNode) node.parentNode._detach(node)
+    if (ref === null) return this.appendChild(node)
+    const i = this._children.indexOf(ref)
+    if (i === -1) throw new Error('insertBefore: ref not a child')
+    this._children.splice(i, 0, node)
+    node.parentNode  = this
+    node.nextSibling = ref
+    if (i > 0) this._children[i - 1].nextSibling = node
+    return node
+  }
+
+  // Internal: remove without clearing siblings (used by move operations)
+  _detach(node) {
+    const i = this._children.indexOf(node)
+    if (i === -1) return
+    this._children.splice(i, 1)
+    if (i > 0) this._children[i - 1].nextSibling = this._children[i] ?? null
+    node.parentNode = null
+  }
+
+  cloneNode(deep = false) {
+    const clone = new FakeElement(this.nodeName.toLowerCase())
+    clone._attrs = { ...this._attrs }
+    if (deep) {
+      for (const child of this._children) {
+        clone.appendChild(child.cloneNode(true))
+      }
+    }
+    return clone
+  }
+
+  // ---- innerHTML (for test setup only) ----
+  set innerHTML(html) {
+    this._children = []
+    for (const node of parseHtml(html)) this.appendChild(node)
+  }
+
+  get innerHTML() {
+    return this._children.map(n => {
+      if (n.nodeType === 3) return n.nodeValue
+      const attrs = Object.entries(n._attrs).map(([k, v]) => ` ${k}="${v}"`).join('')
+      return `<${n.nodeName.toLowerCase()}${attrs}>${n.innerHTML}</${n.nodeName.toLowerCase()}>`
+    }).join('')
+  }
+
+  addEventListener() {}
+  querySelectorAll() { return [] }
+}
+
+// Minimal HTML parser — handles flat list of elements with attributes + text content
+// Sufficient for testing morph with <li data-key="x">text</li> structures
+function parseHtml(html) {
+  const nodes  = []
+  const re     = /<(\w+)((?:\s+[\w-]+=(?:"[^"]*"|'[^']*'|[^\s>]*))*)\s*>([\s\S]*?)<\/\1>|([^<]+)/g
+  let m
+  while ((m = re.exec(html)) !== null) {
+    if (m[4] !== undefined) {
+      const text = m[4]
+      if (text.trim()) nodes.push(new FakeText(text))
+    } else {
+      const el = new FakeElement(m[1])
+      const attrRe = /([\w-]+)=(?:"([^"]*)"|'([^']*)'|(\S+))/g
+      let am
+      while ((am = attrRe.exec(m[2])) !== null) {
+        el.setAttribute(am[1], am[2] ?? am[3] ?? am[4])
+      }
+      for (const child of parseHtml(m[3])) el.appendChild(child)
+      nodes.push(el)
+    }
+  }
+  return nodes
+}
+
+// Inject document shim so morph() uses real DOM path
+global.document = {
+  createElement: (tag) => new FakeElement(tag),
+}
+
+// ---------------------------------------------------------------------------
+// Import runtime (after shim is in place)
+// ---------------------------------------------------------------------------
+
+import { mount } from './index.js'
+
+// ---------------------------------------------------------------------------
+// Test runner
+// ---------------------------------------------------------------------------
+
+let passed = 0
+let failed = 0
+
+function test(label, fn) {
+  try {
+    fn()
+    console.log(`  ✓ ${label}`)
+    passed++
+  } catch (e) {
+    console.log(`  ✗ ${label}`)
+    console.log(`    ${e.message}`)
+    console.log(e.stack.split('\n')[1])
+    failed++
+  }
+}
+
+function assert(cond, msg) {
+  if (!cond) throw new Error(msg || 'Assertion failed')
+}
+
+// ---------------------------------------------------------------------------
+// Helper — mount a spec and return the root element + instance
+// ---------------------------------------------------------------------------
+
+function makeListSpec(items) {
+  return {
+    route:   '/list',
+    state:   { items },
+    view:    (s) => `<ul>${s.items.map(it => `<li data-key="${it.id}">${it.label}</li>`).join('')}</ul>`,
+    mutations: {
+      setItems: (_, items) => ({ items }),
+    },
+  }
+}
+
+console.log('\nKey-based morphing\n')
+
+// ---------------------------------------------------------------------------
+
+test('initial render produces correct keyed list', () => {
+  const el = new FakeElement('div')
+  const items = [{ id: 'a', label: 'Alpha' }, { id: 'b', label: 'Beta' }]
+  mount(makeListSpec(items), el)
+
+  const ul = el.childNodes[0]
+  assert(ul.nodeName === 'UL', 'expected UL')
+  assert(ul.childNodes.length === 2, `expected 2 children, got ${ul.childNodes.length}`)
+  assert(ul.childNodes[0].getAttribute('data-key') === 'a', 'first key should be a')
+  assert(ul.childNodes[1].getAttribute('data-key') === 'b', 'second key should be b')
+})
+
+test('removing an item removes only that node', () => {
+  const el = new FakeElement('div')
+  const items = [{ id: 'a', label: 'A' }, { id: 'b', label: 'B' }, { id: 'c', label: 'C' }]
+  const instance = mount(makeListSpec(items), el)
+
+  const ul    = el.childNodes[0]
+  const nodeA = ul.childNodes[0]
+  const nodeC = ul.childNodes[2]
+
+  instance.dispatch('setItems', [{ id: 'a', label: 'A' }, { id: 'c', label: 'C' }])
+
+  assert(ul.childNodes.length === 2, `expected 2 children after remove, got ${ul.childNodes.length}`)
+  assert(ul.childNodes[0] === nodeA, 'node A should be the same object (not recreated)')
+  assert(ul.childNodes[1] === nodeC, 'node C should be the same object (not recreated)')
+})
+
+test('reordering moves nodes without recreating them', () => {
+  const el = new FakeElement('div')
+  const items = [{ id: 'a', label: 'A' }, { id: 'b', label: 'B' }, { id: 'c', label: 'C' }]
+  const instance = mount(makeListSpec(items), el)
+
+  const ul    = el.childNodes[0]
+  const nodeA = ul.childNodes[0]
+  const nodeB = ul.childNodes[1]
+  const nodeC = ul.childNodes[2]
+
+  instance.dispatch('setItems', [{ id: 'c', label: 'C' }, { id: 'a', label: 'A' }, { id: 'b', label: 'B' }])
+
+  assert(ul.childNodes.length === 3, 'length unchanged after reorder')
+  assert(ul.childNodes[0] === nodeC, 'C should now be first (same node)')
+  assert(ul.childNodes[1] === nodeA, 'A should now be second (same node)')
+  assert(ul.childNodes[2] === nodeB, 'B should now be third (same node)')
+})
+
+test('inserting an item at the start preserves existing nodes', () => {
+  const el = new FakeElement('div')
+  const items = [{ id: 'a', label: 'A' }, { id: 'b', label: 'B' }]
+  const instance = mount(makeListSpec(items), el)
+
+  const ul    = el.childNodes[0]
+  const nodeA = ul.childNodes[0]
+  const nodeB = ul.childNodes[1]
+
+  instance.dispatch('setItems', [{ id: 'x', label: 'X' }, { id: 'a', label: 'A' }, { id: 'b', label: 'B' }])
+
+  assert(ul.childNodes.length === 3, `expected 3 children, got ${ul.childNodes.length}`)
+  assert(ul.childNodes[0].getAttribute('data-key') === 'x', 'new node X at index 0')
+  assert(ul.childNodes[1] === nodeA, 'A same node at index 1')
+  assert(ul.childNodes[2] === nodeB, 'B same node at index 2')
+})
+
+test('text content is updated when label changes on an existing node', () => {
+  const el = new FakeElement('div')
+  const items = [{ id: 'a', label: 'Alpha' }, { id: 'b', label: 'Beta' }]
+  const instance = mount(makeListSpec(items), el)
+
+  const ul    = el.childNodes[0]
+  const nodeA = ul.childNodes[0]
+
+  instance.dispatch('setItems', [{ id: 'a', label: 'UPDATED' }, { id: 'b', label: 'Beta' }])
+
+  assert(ul.childNodes[0] === nodeA, 'node A is same object (reused)')
+  assert(nodeA.innerHTML === 'UPDATED', `expected text UPDATED, got: ${nodeA.innerHTML}`)
+})
+
+test('clearing to empty list removes all nodes', () => {
+  const el = new FakeElement('div')
+  const instance = mount(makeListSpec([{ id: 'a', label: 'A' }, { id: 'b', label: 'B' }]), el)
+
+  const ul = el.childNodes[0]
+  instance.dispatch('setItems', [])
+
+  assert(ul.childNodes.length === 0, `expected empty list, got ${ul.childNodes.length} nodes`)
+})
+
+test('unkeyed content falls back to position-based morphing', () => {
+  const el = new FakeElement('div')
+  const spec = {
+    route: '/unkeyed',
+    state: { label: 'hello' },
+    view:  (s) => `<p>${s.label}</p>`,
+    mutations: { setLabel: (_, v) => ({ label: v }) },
+  }
+  const instance = mount(spec, el)
+  instance.dispatch('setLabel', 'world')
+
+  assert(el.childNodes[0].innerHTML === 'world', `expected 'world', got: ${el.childNodes[0].innerHTML}`)
+})
+
+// ---------------------------------------------------------------------------
+
+console.log()
+if (failed > 0) {
+  console.log(`${passed} passed, ${failed} failed`)
+  process.exit(1)
+} else {
+  console.log(`${passed} passed, 0 failed`)
+}

package/src/runtime/navigate.js

@@ -29,68 +29,102 @@ export function initNavigation(root, mountFn) {
 
       if (!res.ok) { location.href = path; return }
 
-      const { html, title, styles, scripts, hydrate, serverState, storeState } = await res.json()
+      const ct = res.headers.get('content-type') || ''
+
+      if (ct.includes('application/x-ndjson')) {
+        // Streaming nav response — apply chunks progressively as they arrive
+        const reader  = res.body.getReader()
+        const decoder = new TextDecoder()
+        let buf              = ''
+        let hydratePath      = null
+        let finalServerState = {}
+        const deferredSlots  = new Map()
+
+        const processLine = async (line) => {
+          if (!line.trim()) return
+          const msg = JSON.parse(line)
+
+          if (msg.type === 'meta') {
+            hydratePath    = msg.hydrate
+            document.title = msg.title || document.title
+            applyStyles(msg.styles)
+            await applyScripts(msg.scripts)
+
+          } else if (msg.type === 'html') {
+            root.innerHTML = msg.html
+            // Index <pulse-deferred> placeholders so deferred chunks land in the right spot
+            for (const id of (msg.deferred || [])) {
+              const el = root.querySelector(`[id="pd-${id}"]`)
+              if (el) deferredSlots.set(id, el)
+            }
+            if (push) history.pushState({ pulse: true, path }, '', path)
+            scrollAndFocus(root)
+
+          } else if (msg.type === 'deferred') {
+            const slot = deferredSlots.get(msg.id)
+            if (slot) {
+              const tmp = document.createElement('div')
+              tmp.innerHTML = msg.html
+              slot.replaceWith(...tmp.childNodes)
+              deferredSlots.delete(msg.id)
+            }
+
+          } else if (msg.type === 'done') {
+            if (msg.storeState && window.__updatePulseStore__) {
+              window.__updatePulseStore__(msg.storeState)
+            }
+            finalServerState = msg.serverState || {}
+          }
+        }
 
-      // Update the client store singleton with fresh server-resolved store data.
-      if (storeState && typeof window !== 'undefined' && window.__updatePulseStore__) {
-        window.__updatePulseStore__(storeState)
-      }
+        while (true) {
+          const { done, value } = await reader.read()
+          if (done) break
+          buf += decoder.decode(value, { stream: true })
+          const lines = buf.split('\n')
+          buf = lines.pop()  // last element may be an incomplete line
+          for (const line of lines) await processLine(line)
+        }
+        if (buf) await processLine(buf)
 
-      root.innerHTML = html
-      document.title = title || document.title
-
-      if (Array.isArray(styles)) {
-        const existing = new Set(
-          [...document.querySelectorAll('link[rel="stylesheet"]')].map(l => l.getAttribute('href'))
-        )
-        for (const href of styles) {
-          if (!existing.has(href)) {
-            const link = document.createElement('link')
-            link.rel = 'stylesheet'
-            link.href = href
-            document.head.appendChild(link)
-          }
+        runScripts(root)
+        document.dispatchEvent(new CustomEvent('pulse:navigate'))
+
+        if (hydratePath && mountFn) {
+          currentMount?.destroy()
+          root.dataset.pulseMounted = '1'
+          window.__PULSE_SERVER__ = finalServerState
+          const { default: spec } = await import(/* @vite-ignore */ hydratePath)
+          if (spec) currentMount = mountFn(spec, root, finalServerState)
         }
-      }
 
-      if (Array.isArray(scripts)) {
-        const existingSrcs = new Set(
-          [...document.querySelectorAll('script[src]')].map(s => s.getAttribute('src'))
-        )
-        await Promise.all(scripts
-          .filter(src => !existingSrcs.has(src))
-          .map(src => new Promise((resolve) => {
-            const script = document.createElement('script')
-            script.src = src
-            script.onload = resolve
-            script.onerror = resolve
-            document.head.appendChild(script)
-          }))
-        )
-      }
+      } else {
+        // Legacy JSON response (server running with stream: false)
+        const { html, title, styles, scripts, hydrate, serverState, storeState } = await res.json()
 
-      runScripts(root)
+        if (storeState && window.__updatePulseStore__) {
+          window.__updatePulseStore__(storeState)
+        }
 
-      if (push) history.pushState({ pulse: true, path }, '', path)
+        root.innerHTML = html
+        document.title = title || document.title
+        applyStyles(styles)
+        await applyScripts(scripts)
+        runScripts(root)
 
-      if (hydrate && mountFn) {
-        // Destroy the previous mount to clean up its store subscription
-        currentMount?.destroy()
-        root.dataset.pulseMounted = '1'
-        window.__PULSE_SERVER__ = serverState || {}
-        const { default: spec } = await import(/* @vite-ignore */ hydrate)
-        if (spec) currentMount = mountFn(spec, root, serverState || {})
-      }
+        if (push) history.pushState({ pulse: true, path }, '', path)
 
-      document.dispatchEvent(new CustomEvent('pulse:navigate'))
-      window.scrollTo({ top: 0, behavior: 'instant' })
+        if (hydrate && mountFn) {
+          currentMount?.destroy()
+          root.dataset.pulseMounted = '1'
+          window.__PULSE_SERVER__ = serverState || {}
+          const { default: spec } = await import(/* @vite-ignore */ hydrate)
+          if (spec) currentMount = mountFn(spec, root, serverState || {})
+        }
 
-      const focusTarget = root.querySelector('#main-content, main, h1') || root
-      if (!focusTarget.hasAttribute('tabindex')) {
-        focusTarget.setAttribute('tabindex', '-1')
-        focusTarget.addEventListener('blur', () => focusTarget.removeAttribute('tabindex'), { once: true })
+        document.dispatchEvent(new CustomEvent('pulse:navigate'))
+        scrollAndFocus(root)
       }
-      focusTarget.focus({ preventScroll: true })
 
     } catch {
       location.href = path
@@ -144,3 +178,49 @@ function runScripts(el) {
     s.remove()
   })
 }
+
+/** Inject any stylesheets not already present in <head>. */
+function applyStyles(styles) {
+  if (!Array.isArray(styles)) return
+  const existing = new Set(
+    [...document.querySelectorAll('link[rel="stylesheet"]')].map(l => l.getAttribute('href'))
+  )
+  for (const href of styles) {
+    if (!existing.has(href)) {
+      const link = document.createElement('link')
+      link.rel  = 'stylesheet'
+      link.href = href
+      document.head.appendChild(link)
+    }
+  }
+}
+
+/** Inject any external scripts not already present in <head>. Returns a Promise. */
+function applyScripts(scripts) {
+  if (!Array.isArray(scripts)) return Promise.resolve()
+  const existingSrcs = new Set(
+    [...document.querySelectorAll('script[src]')].map(s => s.getAttribute('src'))
+  )
+  return Promise.all(
+    scripts
+      .filter(src => !existingSrcs.has(src))
+      .map(src => new Promise((resolve) => {
+        const script   = document.createElement('script')
+        script.src     = src
+        script.onload  = resolve
+        script.onerror = resolve
+        document.head.appendChild(script)
+      }))
+  )
+}
+
+/** Scroll to top and move focus to the main landmark. */
+function scrollAndFocus(root) {
+  window.scrollTo({ top: 0, behavior: 'instant' })
+  const focusTarget = root.querySelector('#main-content, main, h1') || root
+  if (!focusTarget.hasAttribute('tabindex')) {
+    focusTarget.setAttribute('tabindex', '-1')
+    focusTarget.addEventListener('blur', () => focusTarget.removeAttribute('tabindex'), { once: true })
+  }
+  focusTarget.focus({ preventScroll: true })
+}