@abide/abide 0.41.0 → 0.41.1

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

@@ -0,0 +1,30 @@
+import { RANGE_CLOSE, RANGE_OPEN } from '../runtime/RANGE_MARKER.ts'
+import { scope } from '../runtime/scope.ts'
+import { enterNamespace } from './enterNamespace.ts'
+
+/*
+Builds a `[ … ]`-bounded content range into a DETACHED fragment under a fresh reactive
+scope, then returns the markers, the fragment, and the scope disposer — leaving
+INSERTION to the caller. The create-path range builder for the keyed list runtimes
+(`each` / `eachAsync`): `each` holds the fragment in `pending` for deferred placement
+(its reconcile reorders rows), `eachAsync` inserts it immediately at the stream anchor
+(arrival order). Both need the same bracketed-fragment build, so it lives here once.
+
+Unlike `openMarker`, this never touches a live parent or the hydrate claim cursor — the
+markers are created fresh and parked in a fragment — so it is a pure CREATE primitive;
+the hydrate paths claim their server markers directly. `namespaceParent` sets the
+ambient foreign namespace for the build (a row's svg/math children read it off the
+fragment's eventual parent), matching `fillBefore`/`enterNamespace`.
+*/
+export function buildDetachedRange(
+    namespaceParent: Node,
+    build: (into: Node) => void,
+): { start: Comment; end: Comment; fragment: DocumentFragment; dispose: () => void } {
+    const start = document.createComment(RANGE_OPEN)
+    const end = document.createComment(RANGE_CLOSE)
+    const fragment = document.createDocumentFragment()
+    fragment.appendChild(start)
+    const dispose = enterNamespace(namespaceParent, () => scope(() => build(fragment)))
+    fragment.appendChild(end)
+    return { start, end, fragment, dispose }
+}

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

@@ -0,0 +1,34 @@
+import { commentData } from './commentData.ts'
+import { markerDepthDelta } from './markerDepthDelta.ts'
+
+/*
+A sibling list's DEPTH-0 nodes — those belonging to THIS skeleton's own structure, excluding
+any node inside a block/component's `[`…`]` / `abide:` range (depth > 0), whose anchors belong
+to that range's OWN skeleton. The realized-DOM analogue of the compiler's fresh-context
+boundary: the shared anchor walk (`walkAnchorOrder`) classifies one node at a time and so can't
+skip a sibling RUN, so the marker-depth skip lives here, feeding the walk only own-skeleton
+nodes. In create mode the clone is shallow (no markers built yet), so depth stays 0 and every
+node is returned — a plain document scan.
+*/
+export function depthZeroNodes(nodes: ArrayLike<Node>): Node[] {
+    const own: Node[] = []
+    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 (depth === 0) {
+                own.push(node)
+            }
+            continue
+        }
+        const delta = markerDepthDelta(data)
+        if (delta !== 0) {
+            depth += delta
+        } else if (depth === 0) {
+            /* A non-marker comment (this skeleton's own `a` anchor) at depth 0. */
+            own.push(node)
+        }
+    }
+    return own
+}

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

@@ -0,0 +1,29 @@
+import type { AnchorRole, AnchorWalkAdapter } from '../compile/walkAnchorOrder.ts'
+import { ANCHOR } from '../runtime/RANGE_MARKER.ts'
+import { commentData } from './commentData.ts'
+import { depthZeroNodes } from './depthZeroNodes.ts'
+import { isElement } from './isElement.ts'
+
+/*
+The realized-DOM side of the shared anchor-ordering rule (`walkAnchorOrder`). Classifies each
+recovered node by the SAME positions the template-AST side numbered (`templateAnchorAdapter`),
+so `scanAnchors`'s collection lines up with the compiler's `anIndex`.
+
+An `a` comment is this skeleton's own anchor (one position); an element is an own-skeleton
+container to descend; anything else contributes nothing. `childrenOf` returns only depth-0
+nodes — a nested block/component's marker-bracketed content is skipped exactly as the compiler
+stops at a fresh-context boundary.
+*/
+export const domAnchorAdapter: AnchorWalkAdapter<Node> = {
+    classify: (node: Node): AnchorRole => {
+        const data = commentData(node)
+        if (data === ANCHOR) {
+            return { kind: 'anchor', positions: [node] }
+        }
+        if (data === undefined && isElement(node)) {
+            return { kind: 'recurse' }
+        }
+        return { kind: 'skip' }
+    },
+    childrenOf: (node: Node): readonly Node[] => depthZeroNodes(node.childNodes),
+}

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

@@ -0,0 +1,20 @@
+import type { ElementRole, ElementWalkAdapter } from '../compile/walkElementOrder.ts'
+import { HOLE_ATTRIBUTE } from '../runtime/HOLE_ATTRIBUTE.ts'
+import { isElement } from './isElement.ts'
+
+/*
+The parsed-DOM side of the shared element-hole numbering rule (`walkElementOrder`). Classifies
+each node of the parsed skeleton by the SAME holes the template-AST side numbered
+(`templateElementAdapter`), so the runtime's collected element paths line up with the compiler's
+`elIndex`. Runs over the SHALLOW parsed skeleton (blocks/components/slots are already `<!--a-->`
+anchors, not elements), so a `HOLE_ATTRIBUTE` element is a hole and every element is descended;
+everything else skips. The collected paths resolve against the expanded server DOM separately
+(`resolveElementHole`, which skips nested ranges there).
+*/
+export const domElementAdapter: ElementWalkAdapter<Node> = {
+    classify: (node: Node): ElementRole =>
+        isElement(node)
+            ? { kind: 'element', isHole: node.hasAttribute(HOLE_ATTRIBUTE) }
+            : { kind: 'skip' },
+    childrenOf: (node: Node): readonly Node[] => Array.from(node.childNodes),
+}

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

@@ -6,7 +6,7 @@ import { scope } from '../runtime/scope.ts'
 import { scopeGroup } from '../runtime/scopeGroup.ts'
 import type { State } from '../runtime/types/State.ts'
 import { state } from '../state.ts'
-import { enterNamespace } from './enterNamespace.ts'
+import { buildDetachedRange } from './buildDetachedRange.ts'
 import { moveRange } from './moveRange.ts'
 import { removeRange } from './removeRange.ts'
 import type { EachRow } from './types/EachRow.ts'
@@ -70,17 +70,13 @@ export function each<T>(
             hydration.next.set(parent, end.nextSibling)
             return { start, end, dispose, cell, indexCell }
         }
-        const start = document.createComment('[')
-        const end = document.createComment(']')
-        const pending = document.createDocumentFragment()
-        pending.appendChild(start)
-        /* 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 = group.track(
-            enterNamespace(parent, () => scope(() => render(pending, cell as State<T>, indexCell))),
+        /* Shared detached-range create primitive: a `[ … ]` fragment built under `parent`'s
+           foreign namespace (so svg/math row children are namespaced, not built as HTML),
+           held in `pending` until placement inserts it. */
+        const { start, end, fragment, dispose } = buildDetachedRange(parent, (host) =>
+            render(host, cell as State<T>, indexCell),
         )
-        pending.appendChild(end)
-        return { start, end, dispose, cell, indexCell, pending }
+        return { start, end, dispose: group.track(dispose), cell, indexCell, pending: fragment }
     }
 
     /* Place a row so its range ends just before `cursor`: insert a fresh row's

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

@@ -2,11 +2,10 @@ import { effect } from '../effect.ts'
 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 { scopeGroup } from '../runtime/scopeGroup.ts'
 import type { State } from '../runtime/types/State.ts'
 import { state } from '../state.ts'
-import { enterNamespace } from './enterNamespace.ts'
+import { buildDetachedRange } from './buildDetachedRange.ts'
 import { removeRange } from './removeRange.ts'
 import type { EachRow } from './types/EachRow.ts'
 
@@ -49,24 +48,20 @@ export function eachAsync<T>(
         parent.insertBefore(anchor, before) // `before` places rows before a static suffix
     }
 
-    /* Build a content range and insert it just before the anchor (arrival order). A bare
-       range (no item cell) — the data-row site adds the cell, the error branch needs none. */
+    /* Build a content range (the shared detached-range create primitive) and insert it
+       just before the anchor (arrival order). A bare range (no item cell) — the data-row
+       site adds the cell, the error branch needs none. */
     const insertRange = (
         build: (into: Node) => void,
     ): { start: Node; end: Node; dispose: () => void } => {
-        const start = document.createComment('[')
-        const end = document.createComment(']')
-        const fragment = document.createDocumentFragment()
-        fragment.appendChild(start)
-        const dispose = group.track(
-            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,
-           emptied into the document once the enclosing block placed it. */
-        ;(anchor.parentNode ?? parent).insertBefore(fragment, anchor)
-        return { start, end, dispose }
+        /* Namespace the build off the anchor's LIVE parent, and insert there too: when this
+           `each` is a bare child of a control-flow branch, the captured `parent` is the
+           branch's build fragment, emptied into the document once the enclosing block
+           placed it. */
+        const host = anchor.parentNode ?? parent
+        const { start, end, fragment, dispose } = buildDetachedRange(host, build)
+        host.insertBefore(fragment, anchor)
+        return { start, end, dispose: group.track(dispose) }
     }
 
     /* The mounted `<template catch>` range, disposed when a fresh run re-streams. */

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

@@ -0,0 +1,6 @@
+/* An element carries `hasAttribute`; comment/text nodes do not. Detected by method (not
+   `nodeType`) so every skeleton walk runs under the test mini-dom too. Shared by the
+   element-hole path resolver (`skeleton`) and both realized-DOM walk adapters. */
+export function isElement(node: Node): node is Element {
+    return typeof (node as Element).hasAttribute === 'function'
+}

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

@@ -0,0 +1,19 @@
+import { RANGE_CLOSE, RANGE_OPEN } from '../runtime/RANGE_MARKER.ts'
+
+/* The block-range nesting rule, the single source both marker-depth scans share
+   (`depthZeroNodes`'s anchor filter and `skeleton`'s `elementChildAt` element walk):
+   `+1` opening a range, `-1` closing one, `0` for any other comment. A control-flow
+   block's rendered content sits between an OPEN and CLOSE comment — `[`…`]` for each
+   rows / if / switch / slot ranges, named `abide:…`…`/abide:…` for await / try /
+   snippet / html; the skeleton's own anchor (`a`) sits OUTSIDE any range, so it scores
+   `0`. Keeping the rule here means a new marker family updates one place, so the two
+   scans can never disagree on what nests. */
+export function markerDepthDelta(data: string): number {
+    if (data === RANGE_CLOSE || data.startsWith('/abide:')) {
+        return -1
+    }
+    if (data === RANGE_OPEN || data.startsWith('abide:')) {
+        return 1
+    }
+    return 0
+}

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

@@ -1,3 +1,4 @@
+import { RANGE_CLOSE, RANGE_OPEN } from '../runtime/RANGE_MARKER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
 import type { UiProps } from '../runtime/types/UiProps.ts'
@@ -31,15 +32,15 @@ export function mountRange(
     label: string | undefined = undefined,
 ): { start: Comment; end: Comment; dispose: () => void } {
     const hydration = RENDER.hydration
-    const start = openMarker(parent, '[', before)
+    const start = openMarker(parent, RANGE_OPEN, before)
     if (hydration === undefined) {
-        const end = openMarker(parent, ']', before)
+        const end = openMarker(parent, RANGE_CLOSE, before)
         return fillRange(start, end, build, props, label)
     }
     /* Hydrate: adopt the server range in place. Establish the child's lexical scope
        and render pass (same as `fillRange`), build claiming the existing nodes, then
        claim the end marker the build's content stops before. */
     const scoped = withScope(label, () => scope(() => build(parent, props)))
-    const end = openMarker(parent, ']')
+    const end = openMarker(parent, RANGE_CLOSE)
     return { start, end, dispose: disposeRange(scoped, start, end) }
 }

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

@@ -1,3 +1,4 @@
+import { RANGE_CLOSE, RANGE_OPEN } from '../runtime/RANGE_MARKER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
 import { scopeGroup } from '../runtime/scopeGroup.ts'
@@ -26,12 +27,12 @@ export function mountSlot(
        dispose on owner teardown (a navigation) — the slot never toggles, so the
        group only ever tracks this one child. */
     const group = scopeGroup()
-    openMarker(parent, '[', before)
+    openMarker(parent, RANGE_OPEN, before)
     if (hydration !== undefined) {
         group.track(scope(() => render(parent))) // content claims the SSR range in place
-        openMarker(parent, ']')
+        openMarker(parent, RANGE_CLOSE)
     } else {
-        const end = openMarker(parent, ']', before)
+        const end = openMarker(parent, RANGE_CLOSE, before)
         group.track(fillBefore(end, render))
     }
 }

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

@@ -1,3 +1,4 @@
+import { batch } from '../runtime/batch.ts'
 import { CURRENT_SCOPE } from '../runtime/CURRENT_SCOPE.ts'
 import { inScope } from '../runtime/inScope.ts'
 import { OWNER } from '../runtime/OWNER.ts'
@@ -20,7 +21,11 @@ export function on(element: Element, type: string, handler: EventListener): void
         return
     }
     const captured = CURRENT_SCOPE.current
-    const wrapped: EventListener = (event) => inScope(captured, () => handler(event))
+    /* Coalesce the handler's writes: a handler setting several signals re-runs each
+       dependent effect once on batch exit, not once per write (the unbatched default
+       flushed eagerly per `trigger`). Stays synchronous — flush runs at handler-end
+       before it returns, so the causal stack (dispatch → handler → effects) is intact. */
+    const wrapped: EventListener = (event) => inScope(captured, () => batch(() => handler(event)))
     element.addEventListener(type, wrapped)
     if (OWNER.current !== undefined) {
         OWNER.current.push(() => element.removeEventListener(type, wrapped))

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

@@ -0,0 +1,24 @@
+import { clearBetween } from './clearBetween.ts'
+import { fillBefore } from './fillBefore.ts'
+
+/*
+The one "replace a marker-bounded region's contents" operation. A control-flow block
+that swaps a branch as a unit (if/else, switch, snippet) clears the live range
+(disposing its scope and removing its nodes via `clearBetween`), then — if the new
+branch has content — builds it fresh into the range before the close marker
+(`fillBefore`). Returns the new content's disposer, or `undefined` for an empty
+branch.
+
+This is the single seam those blocks shared by copy-paste: same `clearBetween` +
+conditional `fillBefore` shape, hand-rolled three times. Routing them through one
+helper makes the region-update strategy a named, testable primitive.
+*/
+export function replaceRange(
+    start: Node,
+    end: Node,
+    dispose: (() => void) | undefined,
+    content: ((into: Node) => void) | undefined,
+): (() => void) | undefined {
+    clearBetween(start, end, dispose)
+    return content !== undefined ? fillBefore(end, content) : undefined
+}

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

@@ -1,8 +1,15 @@
+import { walkAnchorOrder } from '../compile/walkAnchorOrder.ts'
+import { walkElementOrder } from '../compile/walkElementOrder.ts'
 import { claimChild } from '../runtime/claimChild.ts'
 import { HOLE_ATTRIBUTE } from '../runtime/HOLE_ATTRIBUTE.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { commentData } from './commentData.ts'
+import { depthZeroNodes } from './depthZeroNodes.ts'
+import { domAnchorAdapter } from './domAnchorAdapter.ts'
+import { domElementAdapter } from './domElementAdapter.ts'
 import { foreignWrapperTag } from './foreignWrapperTag.ts'
+import { isElement } from './isElement.ts'
+import { markerDepthDelta } from './markerDepthDelta.ts'
 import type { SkeletonHoles } from './types/SkeletonHoles.ts'
 
 type CompiledSkeleton = {
@@ -21,23 +28,6 @@ type CompiledSkeleton = {
    `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'
-}
-
-/* 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
@@ -57,69 +47,28 @@ function elementChildAt(children: ArrayLike<Node>, index: number): Element | und
                 }
                 seen += 1
             }
-        } else if (isCloseMarker(data)) {
-            depth -= 1
-        } else if (isOpenMarker(data)) {
-            depth += 1
+            continue
         }
+        depth += markerDepthDelta(data)
     }
     return undefined
 }
 
-/* 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)
+/* Walks an element-only path from the top-level node list to the target element. A step
+   that resolves to nothing means the claimed server run is missing an element the skeleton
+   expects here — a hydration desync; throw AT it (naming the path) rather than returning
+   the undefined that derefs in the downstream `mountChild`/`attr`, far from the cause. */
+function resolveElementHole(topLevel: ArrayLike<Node>, path: number[]): Element {
+    let node = elementChildAt(topLevel, path[0] as number)
+    for (let depth = 1; depth < path.length && node !== undefined; depth += 1) {
+        node = elementChildAt(node.childNodes, path[depth] as number)
     }
-}
-
-/* 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 AND child-component content is bounded by range
-   markers (a component mounts as a `[`…`]` range at its anchor, like a block — see
-   `mountRange`), 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 ranges 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) {
-            /* Recurse into this skeleton's own elements at depth 0. A child component's
-               content sits inside its `[`…`]` range (depth > 0), so it is skipped like any
-               block range — its anchors belong to the child's own skeleton. */
-            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)
-        }
+    if (node === undefined) {
+        throw new Error(
+            `[abide] hydration desync: skeleton element hole [${path.join(',')}] resolved to no node — the server DOM is missing an element the client build expects here.`,
+        )
     }
+    return node
 }
 
 /* When `parent` is foreign (or a control-flow fragment inside foreign content), the
@@ -140,31 +89,20 @@ function compile(html: string, wrapper: string | undefined): CompiledSkeleton {
         template.innerHTML = wrapper === undefined ? html : `<${wrapper}>${html}</${wrapper}>`
         const source =
             wrapper === undefined ? template.content : (template.content.firstChild as Node)
+        /* Element holes via the ONE shared rule (`walkElementOrder`) — the same element-only
+           pre-order the compiler numbers `elIndex` with. Record each `HOLE_ATTRIBUTE`
+           element's path and strip the marker so a clone never carries it into the live DOM. */
         const elementPaths: number[][] = []
-        indexElementHoles(source, [], elementPaths)
+        walkElementOrder(Array.from(source.childNodes), domElementAdapter, (node, path) => {
+            elementPaths.push(path)
+            ;(node as Element).removeAttribute(HOLE_ATTRIBUTE)
+        })
         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. A step
-   that resolves to nothing means the claimed server run is missing an element the skeleton
-   expects here — a hydration desync; throw AT it (naming the path) rather than returning
-   the undefined that derefs in the downstream `mountChild`/`attr`, far from the cause. */
-function resolveElementHole(topLevel: ArrayLike<Node>, path: number[]): Element {
-    let node = elementChildAt(topLevel, path[0] as number)
-    for (let depth = 1; depth < path.length && node !== undefined; depth += 1) {
-        node = elementChildAt(node.childNodes, path[depth] as number)
-    }
-    if (node === undefined) {
-        throw new Error(
-            `[abide] hydration desync: skeleton element hole [${path.join(',')}] resolved to no node — the server DOM is missing an element the client build expects here.`,
-        )
-    }
-    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,
@@ -197,8 +135,13 @@ export function skeleton(parent: Node, html: string): SkeletonHoles {
             parent.appendChild(clone)
         }
     }
+    /* Anchor holes via the ONE shared ordering rule (`walkAnchorOrder`) — the same traversal
+       the compiler numbers `anIndex` with. The top-level list is depth-0-filtered up front (a
+       nested range can sit among the top-level run); the adapter filters each deeper level. */
     const an: Node[] = []
-    scanAnchors(topLevel, an)
+    walkAnchorOrder(depthZeroNodes(topLevel), domAnchorAdapter, (anchor) => {
+        an.push(anchor as Node)
+    })
     return {
         el: elementPaths.map((path) => resolveElementHole(topLevel, path)),
         an,

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

@@ -1,10 +1,11 @@
 import { effect } from '../effect.ts'
+import { RANGE_CLOSE, RANGE_OPEN } from '../runtime/RANGE_MARKER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
 import { scopeGroup } from '../runtime/scopeGroup.ts'
-import { clearBetween } from './clearBetween.ts'
 import { fillBefore } from './fillBefore.ts'
 import { openMarker } from './openMarker.ts'
+import { replaceRange } from './replaceRange.ts'
 import type { SwitchCase } from './types/SwitchCase.ts'
 
 /*
@@ -28,7 +29,7 @@ export function switchBlock(
 ): void {
     const hydration = RENDER.hydration
     /* The live case's scope, registered with the owner so it disposes on owner
-       teardown — not only when the subject switches cases via clearBetween. */
+       teardown — not only when the subject switches cases via replaceRange. */
     const group = scopeGroup()
     let dispose: (() => void) | undefined
     let activeIndex: number
@@ -49,16 +50,16 @@ export function switchBlock(
 
     /* `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)
+    const start = openMarker(parent, RANGE_OPEN, before)
     if (hydration !== undefined) {
         activeIndex = select(subject())
         const chosen = caseAt(activeIndex)
         if (chosen !== undefined) {
             dispose = group.track(scope(() => chosen.render(parent))) // claim the SSR nodes in place
         }
-        end = openMarker(parent, ']')
+        end = openMarker(parent, RANGE_CLOSE)
     } else {
-        end = openMarker(parent, ']', before)
+        end = openMarker(parent, RANGE_CLOSE, before)
         activeIndex = select(subject())
         const chosen = caseAt(activeIndex)
         if (chosen !== undefined) {
@@ -71,12 +72,14 @@ export function switchBlock(
         if (index === activeIndex) {
             return
         }
-        clearBetween(start, end, dispose)
-        dispose = undefined
         activeIndex = index
         const chosen = caseAt(index)
-        if (chosen !== undefined) {
-            dispose = group.track(fillBefore(end, (p) => chosen.render(p)))
-        }
+        /* Null `dispose` before `replaceRange` builds the new case: a reentrant switch
+           during that build (an effect in the new content writing the subject) would
+           otherwise re-enter with the already-disposed disposer and clear it twice. */
+        const prior = dispose
+        dispose = undefined
+        const next = replaceRange(start, end, prior, chosen && ((p) => chosen.render(p)))
+        dispose = next !== undefined ? group.track(next) : undefined
     })
 }

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

@@ -1,10 +1,11 @@
 import { effect } from '../effect.ts'
+import { RANGE_CLOSE, RANGE_OPEN } from '../runtime/RANGE_MARKER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
 import { scopeGroup } from '../runtime/scopeGroup.ts'
-import { clearBetween } from './clearBetween.ts'
 import { fillBefore } from './fillBefore.ts'
 import { openMarker } from './openMarker.ts'
+import { replaceRange } from './replaceRange.ts'
 
 /*
 Conditional binding — the runtime for `<template if>` (with optional `else`). The
@@ -34,7 +35,7 @@ export function when(
        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. */
+       teardown — not only on a branch flip via replaceRange. */
     const group = scopeGroup()
     let dispose: (() => void) | undefined
     let activeBranch: 'then' | 'else'
@@ -43,16 +44,16 @@ export function when(
     /* `before` (a static node located by the skeleton) places the range among siblings on
        create, so the block sits before a static suffix rather than at the parent's end.
        Hydrate ignores it — the claim cursor (positioned past the prefix) drives placement. */
-    const start = openMarker(parent, '[', before)
+    const start = openMarker(parent, RANGE_OPEN, before)
     if (hydration !== undefined) {
         activeBranch = condition() ? 'then' : 'else'
         const chosen = chosenFor(activeBranch)
         if (chosen !== undefined) {
             dispose = group.track(scope(() => chosen(parent))) // content claims the SSR nodes in place
         }
-        end = openMarker(parent, ']')
+        end = openMarker(parent, RANGE_CLOSE)
     } else {
-        end = openMarker(parent, ']', before)
+        end = openMarker(parent, RANGE_CLOSE, before)
         activeBranch = condition() ? 'then' : 'else'
         const chosen = chosenFor(activeBranch)
         if (chosen !== undefined) {
@@ -65,12 +66,14 @@ export function when(
         if (branch === activeBranch) {
             return
         }
-        clearBetween(start, end, dispose)
-        dispose = undefined
         activeBranch = branch
         const chosen = chosenFor(branch)
-        if (chosen !== undefined) {
-            dispose = group.track(fillBefore(end, chosen))
-        }
+        /* Null `dispose` before `replaceRange` builds the new branch: a reentrant flip
+           during that build (an effect in the new content writing the condition) would
+           otherwise re-enter with the already-disposed disposer and clear it twice. */
+        const prior = dispose
+        dispose = undefined
+        const next = replaceRange(start, end, prior, chosen)
+        dispose = next !== undefined ? group.track(next) : undefined
     })
 }

package/src/lib/ui/runtime/RANGE_MARKER.ts

@@ -0,0 +1,16 @@
+/* The comment-marker "wire alphabet" — the single source of truth for the sentinel
+   strings the SSR emit (`generateSSR`) writes into HTML comments and the hydrate scan
+   (`skeleton`) + every range-mount runtime (`when`/`switch`/`each`/`mountRange`/
+   `mountSlot`/`appendSnippet`) creates as `document.createComment` nodes. Both sides
+   reference THESE constants, so a marker the server writes and the marker the client
+   looks for can never drift on a literal.
+
+   A control-flow block's rendered content sits between an OPEN (`[`) and CLOSE (`]`)
+   comment; a snippet interpolation between `abide:snippet` / `/abide:snippet` (matching
+   `skeleton`'s `abide:` / `/abide:` named-boundary convention, like `OUTLET_MARKER`).
+   The skeleton's own positioning anchor (`a`) sits OUTSIDE any such range. */
+export const RANGE_OPEN = '['
+export const RANGE_CLOSE = ']'
+export const ANCHOR = 'a'
+export const SNIPPET_OPEN = 'abide:snippet'
+export const SNIPPET_CLOSE = '/abide:snippet'