@abide/abide 0.32.1 → 0.33.0

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

@@ -3,6 +3,7 @@ import { claimChild } from '../runtime/claimChild.ts'
 import { OWNER } from '../runtime/OWNER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
+import { enterNamespace } from './enterNamespace.ts'
 import { moveRange } from './moveRange.ts'
 import { removeRange } from './removeRange.ts'
 import type { EachRow } from './types/EachRow.ts'
@@ -31,6 +32,7 @@ export function each<T>(
     items: () => Iterable<T>,
     keyOf: (item: T) => string,
     render: (parent: Node, item: T) => void,
+    before: Node | null = null,
 ): void {
     const rows = new Map<string, EachRow>()
 
@@ -53,7 +55,9 @@ export function each<T>(
         const end = document.createComment(']')
         const pending = document.createDocumentFragment()
         pending.appendChild(start)
-        const dispose = scope(() => render(pending, item))
+        /* Build under `parent`'s foreign namespace so foreign row elements (svg/math)
+           built into the detached fragment are namespaced, not built as HTML. */
+        const dispose = enterNamespace(parent, () => scope(() => render(pending, item)))
         pending.appendChild(end)
         return { start, end, dispose, pending }
     }
@@ -88,7 +92,9 @@ export function each<T>(
         adopting = true
     } else {
         anchor = document.createTextNode('')
-        parent.appendChild(anchor)
+        /* `before` (a static node located by the skeleton) places the row anchor among
+           siblings on create, so rows land before a static suffix; null appends (tail). */
+        parent.insertBefore(anchor, before)
     }
 
     effect(() => {
@@ -99,31 +105,44 @@ export function each<T>(
             adopting = false // rows already adopted in document order; nothing to move
             return
         }
-        const list = Array.isArray(source) ? source : [...source]
-        const keys = list.map(keyOf)
-        const present = new Set(keys)
-        /* Prune departed rows first so their ranges don't sit between survivors and
-           throw off the in-place sibling checks below. */
-        for (const [key, row] of rows) {
-            if (!present.has(key)) {
-                row.dispose()
-                removeRange(row.start, row.end)
-                rows.delete(key)
+        /* All SSR rows were adopted in the pre-effect loop, so every reconcile build is
+           create mode. Clear the global claim cursor for the duration: a synchronous
+           write that reconciles *mid-hydrate* (RENDER.hydration still active — e.g. a
+           page setting shared state during the hydrate pass) would otherwise make
+           buildRow and its inner row render claim SSR nodes that don't exist for a
+           freshly keyed row. The same `next` Map is restored, so the outer hydration
+           cursor is untouched (mirrors awaitBlock/tryBlock). */
+        const previousHydration = RENDER.hydration
+        RENDER.hydration = undefined
+        try {
+            const list = Array.isArray(source) ? source : [...source]
+            const keys = list.map(keyOf)
+            const present = new Set(keys)
+            /* Prune departed rows first so their ranges don't sit between survivors and
+               throw off the in-place sibling checks below. */
+            for (const [key, row] of rows) {
+                if (!present.has(key)) {
+                    row.dispose()
+                    removeRange(row.start, row.end)
+                    rows.delete(key)
+                }
             }
-        }
-        /* Walk backwards from the anchor: `cursor` is the node the current row must
-           precede. A row already ending there keeps its place; only out-of-order (or
-           freshly built) rows move. */
-        let cursor: Node = anchor
-        for (let index = list.length - 1; index >= 0; index -= 1) {
-            const key = keys[index] as string
-            let row = rows.get(key)
-            if (row === undefined) {
-                row = buildRow(list[index] as T)
-                rows.set(key, row)
+            /* Walk backwards from the anchor: `cursor` is the node the current row must
+               precede. A row already ending there keeps its place; only out-of-order (or
+               freshly built) rows move. */
+            let cursor: Node = anchor
+            for (let index = list.length - 1; index >= 0; index -= 1) {
+                const key = keys[index] as string
+                let row = rows.get(key)
+                if (row === undefined) {
+                    row = buildRow(list[index] as T)
+                    rows.set(key, row)
+                }
+                placeBefore(row, cursor)
+                cursor = row.start
             }
-            placeBefore(row, cursor)
-            cursor = row.start
+        } finally {
+            RENDER.hydration = previousHydration
         }
     })
 

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

@@ -3,6 +3,7 @@ import { claimChild } from '../runtime/claimChild.ts'
 import { OWNER } from '../runtime/OWNER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
+import { enterNamespace } from './enterNamespace.ts'
 import { removeRange } from './removeRange.ts'
 import type { EachRow } from './types/EachRow.ts'
 
@@ -28,6 +29,7 @@ export function eachAsync<T>(
     render: (parent: Node, item: T) => void,
     /* Absent → an iterator rejection surfaces instead of rendering a catch branch. */
     renderCatch: ((parent: Node, error: unknown) => void) | undefined,
+    before: Node | null = null,
 ): void {
     const rows = new Map<string, EachRow>()
     const hydration = RENDER.hydration
@@ -35,7 +37,7 @@ export function eachAsync<T>(
     if (hydration !== undefined) {
         parent.insertBefore(anchor, claimChild(hydration, parent)) // no server rows to claim
     } else {
-        parent.appendChild(anchor)
+        parent.insertBefore(anchor, before) // `before` places rows before a static suffix
     }
 
     /* Build a content range and insert it just before the anchor (arrival order). */
@@ -44,7 +46,9 @@ export function eachAsync<T>(
         const end = document.createComment(']')
         const fragment = document.createDocumentFragment()
         fragment.appendChild(start)
-        const dispose = scope(() => build(fragment))
+        const dispose = enterNamespace(anchor.parentNode ?? parent, () =>
+            scope(() => build(fragment)),
+        )
         fragment.appendChild(end)
         /* Insert via the anchor's LIVE parent: when this `each` is a bare child of a
            control-flow branch, the captured `parent` is the branch's build fragment,

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

@@ -0,0 +1,13 @@
+import { RENDER } from '../runtime/RENDER.ts'
+import { inheritedNamespace } from './inheritedNamespace.ts'
+
+/*
+The foreign namespace a child built under `parent` belongs to. A real element dictates
+it from its own namespace (`inheritedNamespace`); a detached `DocumentFragment` — a
+control-flow block's build buffer — carries none, so it inherits the ambient context
+the enclosing block set via `enterNamespace`. `foreignWrapperTag` reads this so a
+`skeleton` parsed into a block's fragment wraps its markup in the right namespace.
+*/
+export function effectiveChildNamespace(parent: Node): string | undefined {
+    return (parent as Element).namespaceURI == null ? RENDER.namespace : inheritedNamespace(parent)
+}

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

@@ -0,0 +1,20 @@
+import { RENDER } from '../runtime/RENDER.ts'
+import { effectiveChildNamespace } from './effectiveChildNamespace.ts'
+
+/*
+Runs a control-flow block's fragment build with the ambient foreign namespace set from
+its insertion `parent`, then restores it. Foreign elements (svg/math children) the
+block builds into its detached fragment read this context (the fragment carries no
+namespace of its own). A foreign `parent` establishes the context; a fragment parent
+keeps the current one, so a block nested inside foreign content stays foreign; a real
+HTML parent (e.g. `<foreignObject>`'s content) resets it.
+*/
+export function enterNamespace<T>(parent: Node, build: () => T): T {
+    const previous = RENDER.namespace
+    RENDER.namespace = effectiveChildNamespace(parent)
+    try {
+        return build()
+    } finally {
+        RENDER.namespace = previous
+    }
+}

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

@@ -1,4 +1,6 @@
+import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
+import { enterNamespace } from './enterNamespace.ts'
 
 /*
 Builds `content` into a fragment under a fresh reactive scope, then inserts it just
@@ -7,10 +9,25 @@ the content append freely (elements, components, nested blocks all use the norma
 append path) before it lands as a unit. Inserting via the marker's LIVE parent
 (`end.parentNode`) keeps placement correct even after an enclosing block has moved
 the markers from a build-time fragment into the document.
+
+`fillBefore` is exclusively the *create* path — control-flow blocks adopt SSR nodes
+in place (a direct `scope(render)`) and route only fresh builds here. So neutralize
+the global claim cursor for the build: a rebuild that runs while the hydrate pass is
+still active (e.g. a synchronous write that flips a `when`/`switch` mid-hydrate)
+would otherwise make the build helpers claim SSR nodes that don't exist for fresh
+content. The same cursor is restored after (mirrors awaitBlock/tryBlock/each).
 */
 export function fillBefore(end: Node, content: (into: Node) => void): () => void {
     const fragment = document.createDocumentFragment()
-    const dispose = scope(() => content(fragment))
-    ;(end.parentNode ?? end).insertBefore(fragment, end)
-    return dispose
+    const previousHydration = RENDER.hydration
+    RENDER.hydration = undefined
+    try {
+        /* Build under the insertion parent's foreign namespace (if any), so foreign
+           elements built into the fragment are namespaced off `end`'s live parent. */
+        const dispose = enterNamespace(end.parentNode ?? end, () => scope(() => content(fragment)))
+        ;(end.parentNode ?? end).insertBefore(fragment, end)
+        return dispose
+    } finally {
+        RENDER.hydration = previousHydration
+    }
 }

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

@@ -0,0 +1,22 @@
+import { effectiveChildNamespace } from './effectiveChildNamespace.ts'
+import { MATHML_NAMESPACE } from './MATHML_NAMESPACE.ts'
+import { SVG_NAMESPACE } from './SVG_NAMESPACE.ts'
+
+/*
+The wrapper tag a static run must be parsed inside so its children land in `parent`'s
+foreign namespace — `svg`/`math`, or undefined for HTML. A bare `<path>` fragment
+parses into the HTML namespace; wrapping it in `<svg>` lets the parser namespace it.
+`cloneStatic` uses this for a static run coalesced under a foreign parent that was
+built imperatively, or under a control-flow block's fragment inside foreign content
+(where `parent`'s effective namespace comes from the ambient context).
+*/
+export function foreignWrapperTag(parent: Node): string | undefined {
+    const namespace = effectiveChildNamespace(parent)
+    if (namespace === SVG_NAMESPACE) {
+        return 'svg'
+    }
+    if (namespace === MATHML_NAMESPACE) {
+        return 'math'
+    }
+    return undefined
+}

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

@@ -5,7 +5,7 @@ import { scope } from '../runtime/scope.ts'
 
 /*
 Adopts existing server-rendered DOM instead of rebuilding it. Runs `build(host)`
-with a claim cursor active, so the dom helpers (openChild/appendText/appendStatic)
+with a claim cursor active, so the dom helpers (skeleton/appendText/appendStatic)
 take the existing nodes rather than creating new ones — attaching event listeners
 and reactive effects to the server's markup in place (no re-render, preserved
 focus/scroll). Returns a disposer.

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

@@ -0,0 +1,19 @@
+import { MATHML_NAMESPACE } from './MATHML_NAMESPACE.ts'
+import { SVG_NAMESPACE } from './SVG_NAMESPACE.ts'
+
+/*
+The foreign namespace that element children of `node` inherit — `SVG_NAMESPACE` under
+an svg, `MATHML_NAMESPACE` under math — or undefined for ordinary HTML. `<foreignObject>`
+is SVG's re-entry point back into HTML, so its children are HTML despite its own SVG
+namespace.
+*/
+export function inheritedNamespace(node: Node): string | undefined {
+    const namespace = (node as Element).namespaceURI
+    if (namespace === SVG_NAMESPACE && (node as Element).localName !== 'foreignObject') {
+        return SVG_NAMESPACE
+    }
+    if (namespace === MATHML_NAMESPACE) {
+        return MATHML_NAMESPACE
+    }
+    return undefined
+}

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

@@ -0,0 +1,32 @@
+import { RENDER } from '../runtime/RENDER.ts'
+import { scope } from '../runtime/scope.ts'
+import { fillBefore } from './fillBefore.ts'
+import { openMarker } from './openMarker.ts'
+
+/*
+Mounts a component's `<slot>` content as a marker-bounded range, so a slot positions among
+static siblings exactly like a control-flow block — by `before` (create) or the claim
+cursor (hydrate). `render` appends the parent-supplied `$children`, or the slot's own
+fallback when none was passed; it runs once (a slot never toggles), so there is no effect or
+re-render — the markers exist only to delimit the range for create insertion and hydrate
+claiming.
+
+Create fills the range before the end marker; hydrate adopts the server range in place
+(claiming from the parked cursor). Mirrors `when` without the conditional swap.
+*/
+// @readme plumbing
+export function mountSlot(
+    parent: Node,
+    render: (host: Node) => void,
+    before: Node | null = null,
+): void {
+    const hydration = RENDER.hydration
+    openMarker(parent, '[', before)
+    if (hydration !== undefined) {
+        scope(() => render(parent)) // content claims the SSR range in place
+        openMarker(parent, ']')
+    } else {
+        const end = openMarker(parent, ']', before)
+        fillBefore(end, render)
+    }
+}

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

@@ -9,7 +9,7 @@ HTML and the block can claim them positionally on hydrate — the boundary that
 a branch hold ANY content (components, text, nested blocks, snippets) as a range,
 rather than a list of single nodes.
 */
-export function openMarker(parent: Node, data: string): Comment {
+export function openMarker(parent: Node, data: string, before: Node | null = null): Comment {
     const hydration = RENDER.hydration
     if (hydration !== undefined) {
         const node = claimChild(hydration, parent) as unknown as Comment
@@ -17,6 +17,8 @@ export function openMarker(parent: Node, data: string): Comment {
         return node
     }
     const node = document.createComment(data)
-    parent.appendChild(node)
+    /* `before` (a node already in `parent`) places the block among static siblings —
+       its content lands at that position; without it the marker appends (block at tail). */
+    parent.insertBefore(node, before)
     return node
 }

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

@@ -0,0 +1,202 @@
+import { claimChild } from '../runtime/claimChild.ts'
+import { HOLE_ATTRIBUTE } from '../runtime/HOLE_ATTRIBUTE.ts'
+import { RENDER } from '../runtime/RENDER.ts'
+import { foreignWrapperTag } from './foreignWrapperTag.ts'
+import type { SkeletonHoles } from './types/SkeletonHoles.ts'
+
+type CompiledSkeleton = {
+    /* The node whose children are the skeleton's top-level run — the template content,
+       or a foreign wrapper element (`<svg>`/`<math>`) the run was parsed inside. */
+    source: Node
+    /* Element holes, in pre-order — each an element-only-index path from a top-level
+       node. Element-only indexing keeps a path stable: a reactive text value is a text
+       node, so its width never shifts an element hole between the empty client skeleton
+       and the value-filled server DOM. */
+    elementPaths: number[][]
+    topLevelCount: number
+}
+
+/* Parsed-once skeleton per unique string, keyed by the owning document (see
+   `templateFor` for the per-document rationale). */
+const CACHES = new WeakMap<object, Map<string, CompiledSkeleton>>()
+
+/* An element carries `hasAttribute`; text/comment nodes do not. Used instead of
+   `nodeType` so the walk runs under the test mini-dom too. */
+function isElement(node: Node): node is Element {
+    return typeof (node as Element).hasAttribute === 'function'
+}
+
+/* A comment node's data, or undefined for elements/text. A comment is a node that is
+   neither an element (`hasAttribute`) nor a text node (`splitText`); the mini-dom
+   exposes no `nodeType`, so detect by method. */
+function commentData(node: Node): string | undefined {
+    if (isElement(node) || typeof (node as Text).splitText === 'function') {
+        return undefined
+    }
+    return (node as Comment).data
+}
+
+/* Block-range boundary markers. A control-flow block's rendered content sits between an
+   OPEN and CLOSE comment: `[`…`]` for each rows / if / switch / slot ranges, and named
+   `abide:…`…`/abide:…` boundaries for await / try / snippet / html. The skeleton's own
+   anchor (`a`) sits OUTSIDE any such range. */
+function isOpenMarker(data: string): boolean {
+    return data === '[' || data.startsWith('abide:')
+}
+function isCloseMarker(data: string): boolean {
+    return data === ']' || data.startsWith('/abide:')
+}
+
+/* The `index`-th depth-0 ELEMENT among `children` — skipping text/comment nodes AND any
+   element nested inside a block's rendered range (between `[`…`]` / `abide:…` boundaries),
+   which belongs to that block's own skeleton. The compiler indexes element holes over the
+   SHALLOW template (block positions are `<!--a-->` anchors, no content), so on hydrate the
+   expanded tree must skip that inline content or a hole positioned after a block shifts. In
+   create mode the clone is shallow (no markers), so depth stays 0 — a plain element count. */
+function elementChildAt(children: ArrayLike<Node>, index: number): Element {
+    let seen = 0
+    let depth = 0
+    for (let cursor = 0; cursor < children.length; cursor += 1) {
+        const child = children[cursor] as Node
+        const data = commentData(child)
+        if (data === undefined) {
+            if (isElement(child) && depth === 0) {
+                if (seen === index) {
+                    return child
+                }
+                seen += 1
+            }
+        } else if (isCloseMarker(data)) {
+            depth -= 1
+        } else if (isOpenMarker(data)) {
+            depth += 1
+        }
+    }
+    return undefined as unknown as Element
+}
+
+/* Records each element hole's element-only path in PRE-ORDER (the `HOLE_ATTRIBUTE`
+   marks which) and strips the marker — the compiler assigns element-hole indices in the
+   same pre-order, so the arrays line up without numbering the markers. */
+function indexElementHoles(container: Node, prefix: number[], paths: number[][]): void {
+    const children = container.childNodes
+    let elementIndex = 0
+    for (let cursor = 0; cursor < children.length; cursor += 1) {
+        const child = children[cursor] as Node
+        if (!isElement(child)) {
+            continue
+        }
+        const path = [...prefix, elementIndex]
+        elementIndex += 1
+        if (child.hasAttribute(HOLE_ATTRIBUTE)) {
+            paths.push(path)
+            child.removeAttribute(HOLE_ATTRIBUTE)
+        }
+        indexElementHoles(child, path, paths)
+    }
+}
+
+/* Collects THIS skeleton's own anchor holes (`a` comments) in document order, present in
+   both the cloned skeleton and the server DOM (text-width-independent). The compiler emits
+   anchors in the same order, so the arrays line up.
+
+   In hydrate mode the claimed tree is FULLY EXPANDED — a nested block's rendered content
+   (each rows, branches, await/try boundaries) sits inline — so a naive descent would also
+   collect the inner block's anchors, which belong to that block's OWN skeleton, shifting
+   every index past the first block. Block content is bounded by range markers, so track
+   depth per sibling list and take an anchor (and recurse into an element) only at depth 0,
+   where the skeleton's own structure lives. In create mode the clone is shallow (the blocks
+   have not built yet — no markers), so depth stays 0 and this is a plain document scan. */
+function scanAnchors(nodes: ArrayLike<Node>, anchors: Node[]): void {
+    let depth = 0
+    for (let index = 0; index < nodes.length; index += 1) {
+        const node = nodes[index] as Node
+        const data = commentData(node)
+        if (data === undefined) {
+            if (isElement(node) && depth === 0) {
+                scanAnchors(node.childNodes, anchors)
+            }
+        } else if (isCloseMarker(data)) {
+            depth -= 1
+        } else if (isOpenMarker(data)) {
+            depth += 1
+        } else if (data === 'a' && depth === 0) {
+            anchors.push(node)
+        }
+    }
+}
+
+/* When `parent` is foreign (or a control-flow fragment inside foreign content), the
+   skeleton's own markup carries no foreign ancestor, so a bare `<circle>` would parse
+   into the HTML namespace. Parse it inside the matching wrapper so the parser
+   namespaces the run; key the cache by wrapper too, since one string can be realized
+   in either context. */
+function compile(html: string, wrapper: string | undefined): CompiledSkeleton {
+    let cache = CACHES.get(document)
+    if (cache === undefined) {
+        cache = new Map()
+        CACHES.set(document, cache)
+    }
+    const key = wrapper === undefined ? html : `${wrapper} ${html}`
+    let compiled = cache.get(key)
+    if (compiled === undefined) {
+        const template = document.createElement('template')
+        template.innerHTML = wrapper === undefined ? html : `<${wrapper}>${html}</${wrapper}>`
+        const source =
+            wrapper === undefined ? template.content : (template.content.firstChild as Node)
+        const elementPaths: number[][] = []
+        indexElementHoles(source, [], elementPaths)
+        compiled = { source, elementPaths, topLevelCount: source.childNodes.length }
+        cache.set(key, compiled)
+    }
+    return compiled
+}
+
+/* Walks an element-only path from the top-level node list to the target element. */
+function resolveElementHole(topLevel: ArrayLike<Node>, path: number[]): Element {
+    let node = elementChildAt(topLevel, path[0] as number)
+    for (let depth = 1; depth < path.length; depth += 1) {
+        node = elementChildAt(node.childNodes, path[depth] as number)
+    }
+    return node
+}
+
+/*
+Realizes a compiled skeleton under `parent` and returns its holes: `el` the element
+holes (attribute/listener/bind), in pre-order; `an` the anchor holes (reactive text,
+control flow, components), in document order. The browser's parser is the sole
+tree-builder here, so foreign content (SVG/MathML) lands in the correct namespace and
+`cloneNode` preserves it — a hand-rolled `createElement` tree-builder could not.
+
+Element holes resolve by element-only path (stable against text-value width, computed
+client-side — no server marker). Anchor holes resolve by scanning for their `a` comment
+markers (present in both clone and server DOM). Create mode clones the parsed top-level
+nodes; hydrate mode claims the matching server run.
+*/
+// @readme plumbing
+export function skeleton(parent: Node, html: string): SkeletonHoles {
+    const { source, elementPaths, topLevelCount } = compile(html, foreignWrapperTag(parent))
+    const hydration = RENDER.hydration
+    const topLevel: Node[] = []
+    if (hydration !== undefined) {
+        let node = claimChild(hydration, parent)
+        for (let count = 0; count < topLevelCount && node !== null; count += 1) {
+            topLevel.push(node)
+            node = node.nextSibling
+        }
+        hydration.next.set(parent, node)
+    } else {
+        const children = source.childNodes
+        for (let index = 0; index < children.length; index += 1) {
+            const clone = (children[index] as Node).cloneNode(true)
+            topLevel.push(clone)
+            parent.appendChild(clone)
+        }
+    }
+    const an: Node[] = []
+    scanAnchors(topLevel, an)
+    return {
+        el: elementPaths.map((path) => resolveElementHole(topLevel, path)),
+        an,
+    }
+}

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

@@ -19,7 +19,12 @@ matching case in place, claim the end marker. The effect's first run picks the s
 case and is a no-op; later changes swap the range.
 */
 // @readme plumbing
-export function switchBlock(parent: Node, subject: () => unknown, cases: SwitchCase[]): void {
+export function switchBlock(
+    parent: Node,
+    subject: () => unknown,
+    cases: SwitchCase[],
+    before: Node | null = null,
+): void {
     const hydration = RENDER.hydration
     let dispose: (() => void) | undefined
     let activeIndex: number
@@ -34,7 +39,9 @@ export function switchBlock(parent: Node, subject: () => unknown, cases: SwitchC
     const caseAt = (index: number): SwitchCase | undefined =>
         index === -1 ? undefined : cases[index]
 
-    const start = openMarker(parent, '[')
+    /* `before` places the range among static siblings on create (block before a suffix);
+       hydrate ignores it and uses the parked claim cursor. */
+    const start = openMarker(parent, '[', before)
     if (hydration !== undefined) {
         activeIndex = select(subject())
         const chosen = caseAt(activeIndex)
@@ -43,7 +50,7 @@ export function switchBlock(parent: Node, subject: () => unknown, cases: SwitchC
         }
         end = openMarker(parent, ']')
     } else {
-        end = openMarker(parent, ']')
+        end = openMarker(parent, ']', before)
         activeIndex = select(subject())
         const chosen = caseAt(activeIndex)
         if (chosen !== undefined) {

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

@@ -0,0 +1,28 @@
+/*
+Parsed-once `<template>` per unique static-skeleton string, reused across every
+mount. A `<template>` (not a detached `<div>`) so table/select content parses by
+the real content model, exactly as the browser parsed the server markup. Backs
+`cloneStatic`'s skeleton-string→template cache.
+
+The cache is keyed by the owning `document`: a template belongs to the document
+that created it, and its clones must land in that same document. In production there
+is one document, so this is one inner map; under the test harness, which installs a
+fresh `document` per file, it keeps each file's templates (and their node class)
+from leaking into the next.
+*/
+const CACHES = new WeakMap<object, Map<string, HTMLTemplateElement>>()
+
+export function templateFor(html: string): HTMLTemplateElement {
+    let cache = CACHES.get(document)
+    if (cache === undefined) {
+        cache = new Map()
+        CACHES.set(document, cache)
+    }
+    let template = cache.get(html)
+    if (template === undefined) {
+        template = document.createElement('template')
+        template.innerHTML = html
+        cache.set(html, template)
+    }
+    return template
+}

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

@@ -2,6 +2,7 @@ import { claimChild } from '../runtime/claimChild.ts'
 import { OWNER } from '../runtime/OWNER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { discardBoundary } from './discardBoundary.ts'
+import { enterNamespace } from './enterNamespace.ts'
 
 /*
 Synchronous error boundary — the runtime for `<template try>`. Builds the guarded
@@ -25,6 +26,7 @@ export function tryBlock(
     id: number,
     renderTry: (parent: Node) => void,
     renderCatch?: (parent: Node, error: unknown) => void,
+    before: Node | null = null,
 ): void {
     /* Run a void build under a fresh ownership scope; on throw, tear down the partial
        effects/listeners it registered and rethrow so the caller can fall back. */
@@ -63,7 +65,7 @@ export function tryBlock(
             RENDER.hydration = undefined
             try {
                 const fragment = document.createDocumentFragment()
-                guard(() => renderCatch(fragment, error))
+                enterNamespace(parent, () => guard(() => renderCatch(fragment, error)))
                 parent.insertBefore(fragment, after)
             } finally {
                 RENDER.hydration = previous
@@ -76,14 +78,14 @@ export function tryBlock(
        (they never entered the document) before the catch builds. */
     try {
         const fragment = document.createDocumentFragment()
-        guard(() => renderTry(fragment))
-        parent.appendChild(fragment)
+        enterNamespace(parent, () => guard(() => renderTry(fragment)))
+        parent.insertBefore(fragment, before)
     } catch (error) {
         if (renderCatch === undefined) {
             throw error
         }
         const fragment = document.createDocumentFragment()
-        guard(() => renderCatch(fragment, error))
-        parent.appendChild(fragment)
+        enterNamespace(parent, () => guard(() => renderCatch(fragment, error)))
+        parent.insertBefore(fragment, before)
     }
 }

package/src/lib/ui/dom/types/SkeletonHoles.ts

@@ -0,0 +1,8 @@
+/* The holes a realized `skeleton` exposes for the build's attach code to wire up:
+   `el` the element holes (attribute/listener/bind nodes) in pre-order, `an` the anchor
+   holes (reactive text, control flow, components) in document order. Two arrays so the
+   compiler and SSR only agree on traversal order, never on synchronized indices. */
+export type SkeletonHoles = {
+    el: Element[]
+    an: Node[]
+}