@abide/abide 0.39.0 → 0.40.1

package/src/lib/ui/compile/renameSignalRefs.ts

@@ -1,4 +1,5 @@
 import ts from 'typescript'
+import { TS_PRINTER } from './TS_PRINTER.ts'
 
 /*
 Rewrites references to a component's signal bindings into the document form the
@@ -24,92 +25,177 @@ export function renameSignalRefs(
     computedNames: ReadonlySet<string> = new Set(),
 ): string {
     const source = ts.createSourceFile('component.ts', code, ts.ScriptTarget.Latest, true)
+    const result = ts.transform(source, [
+        signalRefsTransformer(stateNames, derivedNames, computedNames),
+    ])
+    const output = TS_PRINTER.printFile(result.transformed[0] as ts.SourceFile)
+    result.dispose()
+    return output
+}
 
+/*
+The signal-rewrite as a `ts.TransformerFactory`, so the script pipeline can chain it
+with `docAccessTransformer` over a SINGLE parsed tree (see `lowerScript`) instead of
+print-then-reparse between passes. `renameSignalRefs` is the standalone string wrapper
+kept for per-expression callers (`lowerContext`).
+*/
+export function signalRefsTransformer(
+    stateNames: ReadonlySet<string>,
+    derivedNames: ReadonlySet<string>,
+    computedNames: ReadonlySet<string> = new Set(),
+): ts.TransformerFactory<ts.SourceFile> {
     /* The signal names that a nested binding can shadow — only these matter for
        scope tracking, so we ignore every other local binding. */
     const signalNames = new Set<string>([...stateNames, ...derivedNames, ...computedNames])
-
-    /* Identifier nodes that are names, not value reads — never rewritten. */
-    const skip = new Set<ts.Node>()
-    const collect = (node: ts.Node): void => {
-        if (ts.isPropertyAccessExpression(node)) {
-            skip.add(node.name)
-        }
-        /* A declaration name is a binding, not a value read. A plain identifier is
-           skipped directly; a destructuring pattern's leaf names are collected so a
-           bound name shadowing a signal (`const { count } = …`) is never rewritten. */
-        if (ts.isVariableDeclaration(node)) {
-            if (ts.isIdentifier(node.name)) {
-                skip.add(node.name)
-            } else {
-                collectBindingIdentifiers(node.name, skip)
+    return (context) => (root) => {
+        /* The identifier nodes that are names, not value reads — collected by walking
+           each parent and recording its name children (`parent.name`, a label, a
+           specifier). Read structurally, NOT via `child.parent`, so it holds on
+           synthesized nodes too — `desugar`'s rewritten declarations carry no parent
+           pointers, and chaining this transformer after `desugarTransformer` over one
+           tree must still classify their refs correctly. */
+        const nameSlots = collectNameSlots(root)
+        /* Each visitor carries the set of signal names shadowed by the scopes it sits
+           inside; entering a scope that re-binds a signal name produces a fresh visitor
+           with that name added, so shadowing is per-branch (a sibling scope is unaffected). */
+        const makeVisitor = (shadowed: ReadonlySet<string>): ts.Visitor => {
+            const visit = (node: ts.Node): ts.Node => {
+                /* Type space never holds a value read. A type alias, an interface, or any
+                   type annotation can name a signal — a prop-type member `option?: …`, a
+                   `typeof x` — without it being a runtime reference. Leave the whole type
+                   subtree untouched so it isn't rewritten into a call/access (`option()`)
+                   and emitted as broken code (types erase at build anyway). */
+                if (
+                    ts.isTypeAliasDeclaration(node) ||
+                    ts.isInterfaceDeclaration(node) ||
+                    ts.isTypeNode(node)
+                ) {
+                    return node
+                }
+                /* Import/export specifiers are binding/module names, never value reads.
+                   An aliased import whose original name collides with a signal
+                   (`import { pending as p }` next to a `pending` prop) would otherwise
+                   have its `pending` specifier rewritten to the reader form, corrupting
+                   the declaration. Leave the whole subtree untouched. */
+                if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) {
+                    return node
+                }
+                /* Shorthand `{ count }` → `{ count: model.count }` / `{ total: total.value }`,
+                   unless a nearer scope shadows the name. */
+                if (ts.isShorthandPropertyAssignment(node) && !shadowed.has(node.name.text)) {
+                    const replacement = referenceFor(
+                        node.name.text,
+                        stateNames,
+                        derivedNames,
+                        computedNames,
+                    )
+                    if (replacement !== undefined) {
+                        return ts.factory.createPropertyAssignment(node.name.text, replacement)
+                    }
+                }
+                if (ts.isIdentifier(node) && !nameSlots.has(node) && !shadowed.has(node.text)) {
+                    const replacement = referenceFor(
+                        node.text,
+                        stateNames,
+                        derivedNames,
+                        computedNames,
+                    )
+                    if (replacement !== undefined) {
+                        return replacement
+                    }
+                }
+                /* Recurse with the scope this node introduces folded in (same visitor when
+                   it adds no shadowing name, so unscoped subtrees allocate nothing extra). */
+                const inner = extendShadowed(node, shadowed, signalNames)
+                return ts.visitEachChild(
+                    node,
+                    inner === shadowed ? visit : makeVisitor(inner),
+                    context,
+                )
             }
+            return visit
         }
-        if (ts.isParameter(node) && ts.isIdentifier(node.name)) {
-            skip.add(node.name)
+        return ts.visitNode(root, makeVisitor(new Set())) as ts.SourceFile
+    }
+}
+
+/*
+Collects every identifier NODE that occupies a name/label/specifier slot — a position
+that DECLARES, NAMES, or LABELS rather than READS. Walks each PARENT and records its
+name children (`parent.name`, a label, a specifier), so it reads structure top-down
+and never touches `child.parent` — it therefore holds on synthesized nodes (e.g.
+`desugar`'s rewritten declarations), which carry no parent pointers. The visitor then
+rewrites any identifier NOT in this set (rewrite is the default — value reads appear
+under almost any expression parent and can't be allow-listed), so this set is the
+exhaustive list of non-read slots. It is positional, so `pending` in
+`import { pending as p }` and `pending` in `pending(query)` are told apart by where
+they sit. A non-read slot missing here would be misread as a value read and rewritten
+into broken syntax, so completeness is NOT self-evident — it is guarded empirically by
+the syntax fuzz corpus (`uiCompileSyntaxFuzz.test.ts`), which transpiles each pass's
+output and fails on any corruption.
+*/
+function collectNameSlots(root: ts.Node): Set<ts.Node> {
+    const slots = new Set<ts.Node>()
+    const add = (name: ts.Node | undefined): void => {
+        if (name !== undefined && ts.isIdentifier(name)) {
+            slots.add(name)
         }
-        if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name)) {
-            skip.add(node.name)
+    }
+    const visit = (node: ts.Node): void => {
+        /* `obj.NAME` — the member name; the object side (`.expression`) is the read. */
+        if (ts.isPropertyAccessExpression(node)) {
+            add(node.name)
         }
+        /* `NAME: value`, and method/property/accessor/enum-member names in classes,
+           object literals, and type members. */
         if (
-            (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node)) &&
-            node.name !== undefined
+            ts.isPropertyAssignment(node) ||
+            ts.isMethodDeclaration(node) ||
+            ts.isPropertyDeclaration(node) ||
+            ts.isGetAccessorDeclaration(node) ||
+            ts.isSetAccessorDeclaration(node) ||
+            ts.isMethodSignature(node) ||
+            ts.isPropertySignature(node) ||
+            ts.isEnumMember(node)
+        ) {
+            add(node.name)
+        }
+        /* Declaration names: const/let/var, parameters, named functions and classes. */
+        if (
+            ts.isVariableDeclaration(node) ||
+            ts.isParameter(node) ||
+            ts.isFunctionDeclaration(node) ||
+            ts.isFunctionExpression(node) ||
+            ts.isClassDeclaration(node) ||
+            ts.isClassExpression(node)
         ) {
-            skip.add(node.name)
+            add(node.name)
+        }
+        /* A destructure element binds (`{ a }` / `[a]`) or renames (`{ a: b }`): both
+           the bound name and the source key are names, not reads. */
+        if (ts.isBindingElement(node)) {
+            add(node.name)
+            add(node.propertyName)
+        }
+        /* Labels: `NAME:` and `break NAME` / `continue NAME`. */
+        if (ts.isLabeledStatement(node)) {
+            add(node.label)
+        }
+        if (ts.isBreakStatement(node) || ts.isContinueStatement(node)) {
+            add(node.label)
         }
-        ts.forEachChild(node, collect)
+        /* Import/export specifier and clause names. */
+        if (ts.isImportSpecifier(node) || ts.isExportSpecifier(node)) {
+            add(node.name)
+            add(node.propertyName)
+        }
+        if (ts.isImportClause(node) || ts.isNamespaceImport(node) || ts.isNamespaceExport(node)) {
+            add(node.name)
+        }
+        ts.forEachChild(node, visit)
     }
-    collect(source)
-
-    const result = ts.transform(source, [
-        (context) => (root) => {
-            /* Each visitor carries the set of signal names shadowed by the scopes it sits
-               inside; entering a scope that re-binds a signal name produces a fresh visitor
-               with that name added, so shadowing is per-branch (a sibling scope is unaffected). */
-            const makeVisitor = (shadowed: ReadonlySet<string>): ts.Visitor => {
-                const visit = (node: ts.Node): ts.Node => {
-                    /* Shorthand `{ count }` → `{ count: model.count }` / `{ total: total.value }`,
-                       unless a nearer scope shadows the name. */
-                    if (ts.isShorthandPropertyAssignment(node) && !shadowed.has(node.name.text)) {
-                        const replacement = referenceFor(
-                            node.name.text,
-                            stateNames,
-                            derivedNames,
-                            computedNames,
-                        )
-                        if (replacement !== undefined) {
-                            return ts.factory.createPropertyAssignment(node.name.text, replacement)
-                        }
-                    }
-                    if (ts.isIdentifier(node) && !skip.has(node) && !shadowed.has(node.text)) {
-                        const replacement = referenceFor(
-                            node.text,
-                            stateNames,
-                            derivedNames,
-                            computedNames,
-                        )
-                        if (replacement !== undefined) {
-                            return replacement
-                        }
-                    }
-                    /* Recurse with the scope this node introduces folded in (same visitor when
-                       it adds no shadowing name, so unscoped subtrees allocate nothing extra). */
-                    const inner = extendShadowed(node, shadowed, signalNames)
-                    return ts.visitEachChild(
-                        node,
-                        inner === shadowed ? visit : makeVisitor(inner),
-                        context,
-                    )
-                }
-                return visit
-            }
-            return ts.visitNode(root, makeVisitor(new Set())) as ts.SourceFile
-        },
-    ])
-    const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed })
-    const output = printer.printFile(result.transformed[0] as ts.SourceFile)
-    result.dispose()
-    return output
+    visit(root)
+    return slots
 }
 
 /* The shadowed-name set for `node`'s children: the parent set plus any signal name
@@ -187,22 +273,6 @@ function collectStatementBindings(statement: ts.Statement, into: Set<string>): v
     }
 }
 
-/* The identifier NODES a binding name binds — a plain identifier or the leaves of a
-   destructuring pattern (object/array, including nested patterns and rest elements).
-   For `{ a: b }` only the bound name `b` is a binding; `a` is the source property.
-   Feeds the skip set so a destructured name shadowing a signal is never rewritten. */
-function collectBindingIdentifiers(name: ts.BindingName, into: Set<ts.Node>): void {
-    if (ts.isIdentifier(name)) {
-        into.add(name)
-        return
-    }
-    for (const element of name.elements) {
-        if (ts.isBindingElement(element)) {
-            collectBindingIdentifiers(element.name, into)
-        }
-    }
-}
-
 /* Every identifier bound by a binding name — a plain identifier or the leaves of a
    destructuring pattern (object/array, including rest elements). */
 function collectBindingNames(name: ts.BindingName, into: Set<string>): void {

package/src/lib/ui/compile/resolveBranches.ts

@@ -0,0 +1,21 @@
+import type { TemplateNode } from './types/TemplateNode.ts'
+
+type Branch = Extract<TemplateNode, { kind: 'branch' }>
+type BranchName = Branch['branch']
+
+/* Extracts the `then`/`catch`/`finally` branch children of a control-flow block
+   (await/try), one slot per requested name in the order asked, so callers
+   destructure them directly. A requested branch that is absent yields `undefined`
+   — the caller reads `?.children`/`?.as` for its content and bound var. This is
+   the one branch-lookup site both back-ends share, replacing the per-generator
+   `findBranch`/`branchNamed`/`branchChildren`/`branchVar` copies. */
+export function resolveBranches(
+    node: Extract<TemplateNode, { children: TemplateNode[] }>,
+    ...which: BranchName[]
+): (Branch | undefined)[] {
+    return which.map((name) =>
+        node.children.find(
+            (child): child is Branch => child.kind === 'branch' && child.branch === name,
+        ),
+    )
+}

package/src/lib/ui/compile/stripEffects.ts

@@ -1,4 +1,5 @@
 import ts from 'typescript'
+import { TS_PRINTER } from './TS_PRINTER.ts'
 
 /*
 Removes `effect(...)` calls from a script for the SSR back-end. Effects are client
@@ -10,23 +11,27 @@ binding keeps a defined (unused) name. Client compilation keeps effects untouche
 */
 export function stripEffects(code: string): string {
     const source = ts.createSourceFile('script.ts', code, ts.ScriptTarget.Latest, true)
-    const result = ts.transform(source, [
-        (context) => (root) => {
-            const visit = (node: ts.Node): ts.Node => {
-                if (
-                    ts.isCallExpression(node) &&
-                    ts.isIdentifier(node.expression) &&
-                    node.expression.text === 'effect'
-                ) {
-                    return ts.factory.createIdentifier('undefined')
-                }
-                return ts.visitEachChild(node, visit, context)
-            }
-            return ts.visitNode(root, visit) as ts.SourceFile
-        },
-    ])
-    const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed })
-    const output = printer.printFile(result.transformed[0] as ts.SourceFile)
+    const result = ts.transform(source, [stripEffectsTransformer()])
+    const output = TS_PRINTER.printFile(result.transformed[0] as ts.SourceFile)
     result.dispose()
     return output
 }
+
+/* The effect-stripping as a `ts.TransformerFactory`, so the SSR script path can run it
+   over the tree `lowerScript` already built (one extra print, no reparse). `stripEffects`
+   is the standalone string wrapper kept for the per-nested-`<script>` SSR callers. */
+export function stripEffectsTransformer(): ts.TransformerFactory<ts.SourceFile> {
+    return (context) => (root) => {
+        const visit = (node: ts.Node): ts.Node => {
+            if (
+                ts.isCallExpression(node) &&
+                ts.isIdentifier(node.expression) &&
+                node.expression.text === 'effect'
+            ) {
+                return ts.factory.createIdentifier('undefined')
+            }
+            return ts.visitEachChild(node, visit, context)
+        }
+        return ts.visitNode(root, visit) as ts.SourceFile
+    }
+}

package/src/lib/ui/compile/types/AnalyzedComponent.ts

@@ -7,7 +7,12 @@ The shared front-end result for a component, consumed by both the client
 (so template expressions rewrite consistently), and the parsed template tree.
 */
 export type AnalyzedComponent = {
+    /* The lowered client script — keeps `effect(...)` calls (client lifecycle). */
     script: string
+    /* The same lowered script with `effect(...)` calls stripped, for the SSR render
+       (effects emit no HTML and must not run on the server). Produced from the one
+       parse `script` came from, not a downstream re-parse. */
+    ssrScript: string
     /* Top-level import statements hoisted out of the script (e.g. child
        components), placed at module scope by the module wrapper. */
     imports: string

package/src/lib/ui/compile/types/TemplateNode.ts

@@ -4,7 +4,7 @@ import type { TextPart } from './TextPart.ts'
 /*
 A parsed template node. `text` carries interpolation parts; `element` carries
 attributes and children; `each` is the `<template each as key>` control flow over
-a list. (if/await/switch are future siblings.)
+a list; `if`/`await`/`switch`/`try` are its control-flow siblings.
 
 `loc` (where present) is the absolute offset of the node's primary expression in
 the original `.abide` source — additive, set only when the parser tracks
@@ -67,7 +67,17 @@ export type TemplateNode =
           children: TemplateNode[]
       }
     | { kind: 'switch'; subject: string; children: TemplateNode[]; loc?: number }
-    | { kind: 'case'; match: string | undefined; children: TemplateNode[]; loc?: number }
+    /* A branch of a `<template switch>` (`match` set) or `<template if>` chain. Inside an
+       `if`, `<template elseif={c}>` sets `condition` (match-less, truthy-tested), and
+       `<template else>` leaves both unset (the default). `loc` points at whichever
+       expression the node carries (`match` or `condition`). */
+    | {
+          kind: 'case'
+          match: string | undefined
+          condition?: string
+          children: TemplateNode[]
+          loc?: number
+      }
     /* A `<template name="row" args={item}>` snippet: a named, scope-capturing
        builder declared once and called like a function (`{row(item)}`). `params`
        is the raw `args` source spliced into the builder's parameter list. */

package/src/lib/ui/createScope.ts

@@ -37,6 +37,9 @@ export function createScope(
     const data = (): Doc => (document ??= createDoc({}))
     const id = parent === undefined ? `scope-${nextId++}` : `${parent.id}.${nextId++}`
     const children: Scope[] = []
+    /* Context values shared down the tree, held apart from the reactive doc (which
+       a child does not inherit): keyed by name, read by the closest ancestor walk. */
+    const shared = new Map<string, unknown>()
     let past: History | undefined
     let persistence: PersistHandle | undefined
     let unsync: (() => void) | undefined
@@ -64,6 +67,16 @@ export function createScope(
             return created
         },
         root: () => (parent === undefined ? self : parent.root()),
+        /* Reference store — no tracking, so a lookup never subscribes; reactivity comes
+           from what is shared (a cell/scope), not from the share. */
+        share: (key, value) => {
+            shared.set(key, value)
+        },
+        /* Closest-ancestor resolve: own map first (self can read what it shared), then
+           defer up via each scope's own `shared`. `has` distinguishes a shared
+           `undefined` from "not provided"; undefined at the root means no provider. */
+        shared: <T>(key: string): T | undefined =>
+            shared.has(key) ? (shared.get(key) as T) : parent?.shared<T>(key),
         record: (options) => {
             past ??= history(data(), options)
         },
@@ -82,6 +95,7 @@ export function createScope(
                 created.dispose()
             }
             children.length = 0
+            shared.clear()
             past?.dispose()
             past = undefined
             persistence?.dispose()

package/src/lib/ui/dom/appendText.ts

@@ -4,6 +4,7 @@ import { effect } from '../effect.ts'
 import { claimChild } from '../runtime/claimChild.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { appendSnippet } from './appendSnippet.ts'
+import { parseRawNodes } from './parseRawNodes.ts'
 
 const CLOSE = '/abide:html'
 
@@ -73,9 +74,7 @@ function appendRawHtml(parent: Node, read: () => unknown): void {
         for (const node of nodes) {
             parent.removeChild(node)
         }
-        const holder = document.createElement('div')
-        holder.innerHTML = value
-        nodes = [...holder.childNodes]
+        nodes = parseRawNodes(parent, value)
         for (const node of nodes) {
             parent.insertBefore(node, anchor)
         }

package/src/lib/ui/dom/appendTextAt.ts

@@ -4,6 +4,7 @@ import { effect } from '../effect.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { appendSnippet } from './appendSnippet.ts'
 import { appendText } from './appendText.ts'
+import { parseRawNodes } from './parseRawNodes.ts'
 
 /*
 A reactive `{expr}` interpolation mounted at a skeleton anchor comment (`<!--a-->`), used
@@ -51,9 +52,7 @@ export function appendTextAt(anchor: Node, read: () => unknown): void {
             for (const node of nodes) {
                 parent.removeChild(node)
             }
-            const holder = document.createElement('div')
-            holder.innerHTML = rawHtmlString(read()) ?? ''
-            nodes = [...holder.childNodes]
+            nodes = parseRawNodes(parent, rawHtmlString(read()) ?? '')
             /* Insert the fresh markup just after the anchor (its live re-insertion point). */
             const after = anchor.nextSibling
             for (const node of nodes) {

package/src/lib/ui/dom/applyResolved.ts

@@ -41,16 +41,13 @@ export function applyResolved(root: Element, frame: string): void {
     if (id === null) {
         return
     }
-    /* The resolved value rides in a leading <script type=application/json>; parse and
-       remove it so only the resolved markup moves into the boundary. Recording it lets a
-       later hydrate adopt this branch (no re-fetch). */
+    /* The resolved value rides in a leading <script type=application/json> as ref-json
+       text; store it raw and remove the node so only the resolved markup moves into the
+       boundary. Decoding is deferred to the read in `awaitBlock` (which has the codec);
+       recording it lets a later hydrate adopt this branch (no re-fetch). */
     const payload = resolved.firstChild as Element | null
     if (payload !== null && payload.nodeName === 'SCRIPT') {
-        try {
-            RESUME[Number(id)] = JSON.parse(payload.textContent ?? 'null')
-        } catch {
-            /* malformed payload — leave unregistered, hydration re-runs the promise */
-        }
+        RESUME[Number(id)] = payload.textContent ?? ''
         payload.remove()
     }
     const open = `abide:await:${id}`

package/src/lib/ui/dom/awaitBlock.ts

@@ -1,6 +1,8 @@
+import { decodeRefJson } from '../../shared/decodeRefJson.ts'
 import { effect } from '../effect.ts'
 import { claimChild } from '../runtime/claimChild.ts'
 import { RENDER } from '../runtime/RENDER.ts'
+import type { ResumeEntry } from '../runtime/RESUME.ts'
 import { RESUME } from '../runtime/RESUME.ts'
 import { scope } from '../runtime/scope.ts'
 import { scopeGroup } from '../runtime/scopeGroup.ts'
@@ -161,7 +163,18 @@ export function awaitBlock(
     const firstHydrate = (result: unknown): void => {
         const cursor = hydration as NonNullable<typeof hydration>
         const open = claimChild(cursor, parent)
-        const entry = RESUME[id]
+        /* RESUME holds the ref-json-encoded entry STRING; decode here, where the codec
+           lives. A decode failure (malformed/absent payload) reads as "no resume" — fall
+           through to the live promise rather than crash hydration. */
+        const raw = RESUME[id]
+        let entry: ResumeEntry | undefined
+        if (raw !== undefined) {
+            try {
+                entry = decodeRefJson(raw) as ResumeEntry
+            } catch {
+                entry = undefined
+            }
+        }
         if (entry !== undefined) {
             let build: (host: Node) => void
             if (entry.ok) {
@@ -210,7 +223,14 @@ export function awaitBlock(
            subscribes to its reactive source (a cache key). A cache-remote read is warm
            on resume — it serves the snapshot without a network round-trip, so adoption
            stays no-flash AND a later cache.invalidate re-runs the block. Without this
-           read a resume-adopted block has no deps and invalidate is a no-op. */
+           read a resume-adopted block has no deps and invalidate is a no-op.
+
+           ONLY the promise read is tracked. The warm-sync resolve, the hydration adopt,
+           and the pending render all BUILD the branch through `scope`, which builds
+           untracked — so the branch's own reactive reads don't subscribe THIS effect
+           (otherwise the whole block re-runs and re-suspends on any branch-state change,
+           e.g. a sibling route param updating in place). The branch's own child effects
+           still track normally; the block re-runs only when the promise source does. */
         const result = promiseThunk()
         if (first) {
             first = false

package/src/lib/ui/dom/each.ts

@@ -45,6 +45,10 @@ export function each<T>(
        claim): claim the start marker, build content in place, claim the end marker.
        Create mode: markers + content in a fragment, held in `pending` until placement
        inserts it. */
+    /* Reconcile runs inside the effect below; the row build doesn't subscribe it
+       (`scope` builds untracked), so a raw reactive read in the row content — e.g. a
+       nested `<script>` body — can't re-reconcile the whole list. Only `items()` drives
+       the each; each row's own interpolations track through their own effects. */
     const buildRow = (item: T): EachRow => {
         const hydration = RENDER.hydration
         if (hydration !== undefined) {

package/src/lib/ui/dom/on.ts

@@ -12,6 +12,13 @@ resolves the component, not whatever is current when the event fires.
 */
 // @documentation plumbing
 export function on(element: Element, type: string, handler: EventListener): void {
+    /* A caller that omits an optional `on*` prop forwards it as undefined, yet the
+       compiler still emits this on() call — so skip attaching a non-function rather
+       than invoke undefined when the event fires (e.g. input/keydown on a search box,
+       which would throw "handler is not a function" on every keystroke). */
+    if (typeof handler !== 'function') {
+        return
+    }
     const captured = CURRENT_SCOPE.current
     const wrapped: EventListener = (event) => inScope(captured, () => handler(event))
     element.addEventListener(type, wrapped)

package/src/lib/ui/dom/parseRawNodes.ts

@@ -0,0 +1,17 @@
+import { foreignWrapperTag } from './foreignWrapperTag.ts'
+
+/*
+Parses a trusted raw-markup string into detached nodes in the SAME foreign namespace
+as `parent`. The HTML fragment parser namespaces by its context element, so markup
+bound inside an <svg>/<math> must parse inside a matching wrapper — otherwise a bare
+`<path>` lands in the HTML namespace and never renders. Mirrors `cloneStatic`'s
+foreign handling, but parses per-call into a throwaway `<template>` rather than the
+skeleton cache: raw values are dynamic, so caching every distinct string would leak.
+*/
+export function parseRawNodes(parent: Node, markup: string): Node[] {
+    const wrapper = foreignWrapperTag(parent)
+    const template = document.createElement('template')
+    template.innerHTML = wrapper === undefined ? markup : `<${wrapper}>${markup}</${wrapper}>`
+    const source = wrapper === undefined ? template.content : (template.content.firstChild as Node)
+    return [...source.childNodes]
+}

package/src/lib/ui/dom/switchBlock.ts

@@ -42,6 +42,10 @@ export function switchBlock(
     }
     const caseAt = (index: number): SwitchCase | undefined =>
         index === -1 ? undefined : cases[index]
+    /* The chosen case builds through `scope` (directly on hydrate, via `fillBefore` on a
+       swap), which builds untracked — so a raw reactive read in the case content doesn't
+       subscribe the swap effect below; only `subject()` (and each case's `match()`) drives
+       the swap. The case's own interpolations still track, each through its own effect. */
 
     /* `before` places the range among static siblings on create (block before a suffix);
        hydrate ignores it and uses the parked claim cursor. */

package/src/lib/ui/dom/when.ts

@@ -28,6 +28,10 @@ export function when(
     before: Node | null = null,
 ): void {
     const hydration = RENDER.hydration
+    /* The chosen branch builds through `scope` (directly on hydrate, via `fillBefore`
+       on a swap), which builds untracked — so a raw reactive read in the branch content
+       doesn't subscribe the swap effect below; only `condition()` drives the toggle. The
+       branch's own interpolations still track, each through its own effect. */
     const chosenFor = (branch: 'then' | 'else') => (branch === 'then' ? render : renderElse)
     /* The live branch's scope, registered with the owner so it disposes on owner
        teardown — not only on a branch flip via clearBetween. */

package/src/lib/ui/installInspectorBridge.ts

@@ -49,7 +49,9 @@ function routerState() {
     return {
         path: runtimePath.value,
         route: page.route,
-        params: page.params,
+        /* `page.params` is a reactive Proxy — structuredClone (postMessage) can't carry
+           a Proxy and throws, dropping every router frame. Spread to a plain object. */
+        params: { ...page.params },
         navigating: page.navigating,
         url: page.url.href,
         entry: historyEntries.current,