@abide/abide 0.41.0 → 0.42.0

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

@@ -1,87 +1,72 @@
 import { OUTLET_TAG } from '../runtime/OUTLET_TAG.ts'
-import { isAnchorPositioned } from './isAnchorPositioned.ts'
 import { isControlFlow } from './isControlFlow.ts'
 import { isTextLeaf } from './isTextLeaf.ts'
 import { skeletonable } from './skeletonable.ts'
+import { templateAnchorAdapter } from './templateAnchorAdapter.ts'
+import { templateElementAdapter } from './templateElementAdapter.ts'
 import type { SkeletonContext } from './types/SkeletonContext.ts'
 import type { TemplateNode } from './types/TemplateNode.ts'
+import { walkAnchorOrder } from './walkAnchorOrder.ts'
+import { walkElementOrder } from './walkElementOrder.ts'
 
 /*
 The single source of truth for where skeleton markers go AND what their hole indices are.
-One top-down walk records, per node, whether it sits inside a parser-backed skeleton clone
-(`inSkeleton`) and whether its reactive text is interleaved (`markText`) — the two facts
-that decide `<!--a-->` anchor placement — and assigns each hole its `el`/`an` index.
-`generateBuild` reads these indices instead of threading its own counter through a second
-document-order walk, so the numbering cannot drift from the decisions: one walk owns both.
+One top-down `visit` walk records, per node, whether it sits inside a parser-backed skeleton
+clone (`inSkeleton`), whether its reactive text is interleaved (`markText`), and which
+`skeletonable` elements OPEN a skeleton (`skeletonRoots`). Both hole axes are then numbered by
+the two shared ordering rules — `walkElementOrder` (`el`) and `walkAnchorOrder` (`an`) — run
+once per root, so `generateBuild` reads `sk.el`/`sk.an` rather than re-deriving the numbering,
+and the runtime recovers the same positions through the SAME two walks. One rule per axis, both
+sides; the numbering cannot drift from the decisions.
 
 The index assignment is scoped per skeleton root (a `skeletonable` element not already in a
-skeleton — the unit `generateSkeleton` instantiates with `{ el: 0, an: 0 }`). `el` numbers
-element holes in pre-order; `an` numbers anchor holes (interleaved reactive text PARTS,
-control-flow blocks, child components, `<slot>` outlets) in
-document order — the orders the runtime's `indexElementHoles`/`scanAnchors` re-derive from
-the realized DOM, so the compile-time numbers and the runtime positions line up.
+skeleton — the unit `generateSkeleton` instantiates with a fresh `{ el: 0, an: 0 }`). `el`
+numbers element holes in pre-order (the root element itself can be one); `an` numbers anchor
+holes (interleaved reactive text PARTS, control-flow blocks, child components, `<slot>` outlets)
+in document order.
 
-A fresh-context boundary resets to NOT-in-skeleton (and to no active counter), because the
-content there is built by its own runtime (a control-flow block's branch, a component's slot
-content, a `<slot>`'s fallback, a snippet's body) — never cloned by the enclosing skeleton.
+A fresh-context boundary resets to NOT-in-skeleton, because the content there is built by its
+own runtime (a control-flow block's branch, a component's slot content, a `<slot>`'s fallback,
+a snippet's body) — never cloned by the enclosing skeleton.
 */
 export function skeletonContext(nodes: TemplateNode[]): SkeletonContext {
     const inSkeleton = new WeakMap<TemplateNode, boolean>()
     const markText = new WeakMap<TemplateNode, boolean>()
-    /* Element holes keyed by node; anchor holes keyed by node (control-flow/component/slot)
-       OR by the reactive text PART object (a text node carries one anchor per reactive part). */
+    /* Element holes keyed by node; anchor holes keyed by node (control-flow/component/slot) OR
+       by the reactive text PART object (a text node carries one anchor per reactive part). Both
+       numbered AFTER this context pass by the shared walks, once per skeleton root. */
     const elIndex = new WeakMap<TemplateNode, number>()
     const anIndex = new WeakMap<object, number>()
+    /* The skeletonable elements that OPEN a skeleton — each owns a fresh `el`/`an` numbering, so
+       the shared walks run once per root. Collected in pre-order here, numbered below. */
+    const skeletonRoots: TemplateNode[] = []
 
-    type Counter = { el: number; an: number }
-
-    /* Walk `node` carrying the context AND the active skeleton counter that apply AT it
-       (`counter === undefined` outside any skeleton — no holes are numbered there). */
-    function visit(
-        node: TemplateNode,
-        nodeInSkeleton: boolean,
-        nodeMarkText: boolean,
-        counter: Counter | undefined,
-    ): void {
+    /* Record the boundary context (`inSkeleton`/`markText`) at `node` and collect skeleton
+       roots. Hole NUMBERING is no longer threaded here — the two shared walks own it. */
+    function visit(node: TemplateNode, nodeInSkeleton: boolean, nodeMarkText: boolean): void {
         inSkeleton.set(node, nodeInSkeleton)
         markText.set(node, nodeMarkText)
 
         /* Control-flow blocks, components, and snippets are fresh build contexts. The node
-           ITSELF is a hole in the enclosing skeleton (an `<!--a-->` anchor for a block OR a
-           component — both mount as a marker-bounded range at that anchor); its children
-           re-enter the skeleton only via their own roots. */
+           ITSELF is an anchor in the enclosing skeleton (a block OR a component mounts as a
+           marker-bounded range at that anchor); its children re-enter the skeleton only via
+           their own roots. */
         if (isControlFlow(node) || node.kind === 'component' || node.kind === 'snippet') {
-            /* A block or a component takes an anchor only inside an enclosing skeleton (a
-               standalone one routes through `generateIf`/`mountChild`, not the skeleton path);
-               a snippet declares a builder and is never anchor-positioned (`isAnchorPositioned`). */
-            if (counter !== undefined && isAnchorPositioned(node)) {
-                anIndex.set(node, counter.an++)
-            }
             for (const child of childrenOf(node)) {
-                visit(child, false, false, undefined)
+                visit(child, false, false)
             }
             return
         }
         /* A `branch`/`case` is a transparent grouping inside its control-flow block — pass the
-           already-reset context (and absent counter) through so a skeletonable element inside
-           it opens its own skeleton. */
+           already-reset context through so a skeletonable element inside it opens its own
+           skeleton. */
         if (node.kind === 'branch' || node.kind === 'case') {
             for (const child of node.children) {
-                visit(child, nodeInSkeleton, nodeMarkText, counter)
+                visit(child, nodeInSkeleton, nodeMarkText)
             }
             return
         }
         if (node.kind === 'text') {
-            /* Interleaved reactive text (markText true): each reactive part takes an `<!--a-->`
-               anchor, numbered in document order. A text-leaf's text (markText false) binds
-               marker-free via the element, so its parts take no anchor. */
-            if (counter !== undefined && nodeMarkText) {
-                for (const part of node.parts) {
-                    if (part.kind !== 'static') {
-                        anIndex.set(part, counter.an++)
-                    }
-                }
-            }
             return
         }
         if (node.kind !== 'element') {
@@ -89,51 +74,54 @@ export function skeletonContext(nodes: TemplateNode[]): SkeletonContext {
         }
         if (node.tag === 'slot' || node.tag === OUTLET_TAG) {
             /* A component `<slot>` content fill OR a layout's `OUTLET_TAG` router fill point
-               (`asOutlet`) is an anchor hole in the enclosing skeleton — both mount a marker
-               range at the anchor (`mountSlot` / `outlet`). A `<slot>`'s children are its
-               fallback (a fresh context); an outlet has none. */
-            if (counter !== undefined) {
-                anIndex.set(node, counter.an++)
-            }
+               (`asOutlet`): its children are a fresh context (the `<slot>` fallback / an outlet
+               has none). The slot's own anchor is numbered by the shared walk. */
             for (const child of node.children) {
-                visit(child, false, false, undefined)
+                visit(child, false, false)
             }
             return
         }
-        /* A skeletonable element not already in a skeleton OPENS one (a fresh counter — the
-           `generateSkeleton` unit). An element already in a skeleton uses the enclosing
-           counter. A static element outside any skeleton numbers nothing. */
+        /* A skeletonable element not already in a skeleton OPENS one (the `generateSkeleton`
+           unit). An element already in a skeleton stays in it. A static element outside any
+           skeleton numbers nothing. */
         const opensSkeleton = !nodeInSkeleton && skeletonable(node)
         const childInSkeleton = nodeInSkeleton || skeletonable(node)
-        const effectiveCounter = nodeInSkeleton
-            ? counter
-            : opensSkeleton
-              ? { el: 0, an: 0 }
-              : undefined
         const childMarkText = childInSkeleton && !isTextLeaf(node)
 
-        if (effectiveCounter !== undefined) {
-            /* The element is a located hole when it carries a reactive attr/listener/bind, or
-               binds text-leaf reactive text on itself. Take its `el` index BEFORE recursing,
-               so holes number in pre-order — the order the runtime's path walk produces them. */
-            const hasReactiveAttr = node.attrs.some((attr) => attr.kind !== 'static')
-            const reactiveTextChild = node.children.find(
-                (child) =>
-                    child.kind === 'text' && child.parts.some((part) => part.kind !== 'static'),
-            )
-            const textLeafBind = reactiveTextChild !== undefined && isTextLeaf(node)
-            if (hasReactiveAttr || textLeafBind) {
-                elIndex.set(node, effectiveCounter.el++)
-            }
+        if (opensSkeleton) {
+            skeletonRoots.push(node)
         }
         for (const child of node.children) {
-            visit(child, childInSkeleton, childMarkText, effectiveCounter)
+            visit(child, childInSkeleton, childMarkText)
         }
     }
 
     for (const node of nodes) {
-        visit(node, false, false, undefined)
+        visit(node, false, false)
     }
+
+    /* Number element holes via the ONE shared rule (`walkElementOrder`), once per skeleton root
+       so each root's holes start at 0 — the element-only pre-order the runtime's clone walk
+       re-derives. The walk starts AT the root: the root element itself is a located hole when it
+       binds. */
+    for (const root of skeletonRoots) {
+        let next = 0
+        walkElementOrder([root], templateElementAdapter, (node) => {
+            elIndex.set(node, next++)
+        })
+    }
+
+    /* Number anchor holes via the ONE shared rule (`walkAnchorOrder`), once per skeleton root.
+       The root's own children are walked — the root element is a located hole, never an
+       anchor. */
+    const anchorAdapter = templateAnchorAdapter(inSkeleton, markText)
+    for (const root of skeletonRoots) {
+        let next = 0
+        walkAnchorOrder(childrenOf(root), anchorAdapter, (position) => {
+            anIndex.set(position, next++)
+        })
+    }
+
     return { inSkeleton, markText, elIndex, anIndex }
 }
 

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

@@ -0,0 +1,101 @@
+import type { SemanticToken } from './types/SemanticToken.ts'
+
+/*
+Lexical highlighting for `{#…}`/`{:…}`/`{/…}` control-flow framing — the part the
+HTML grammar sees only as text and the shadow program lowers away. A pure scan of
+raw source (independent of a successful parse, so it survives mid-edit), it emits
+an `operator` token for the `{`+sigil opener and a `keyword` token for the block
+word, plus the `of`/`by` connectors inside a `{#for …}` head. Expression interiors
+(and the `{@const}`/`{@html}` tags and bare `{expr}` interpolations) are NOT touched
+here — those are the shadow's job. A keyword allowlist after the sigil prevents
+matching arbitrary `{:foo}` text. Longest phrases first so `for await` beats `for`
+and `else if` beats `else`.
+*/
+const BLOCK_KEYWORDS = [
+    'for await',
+    'else if',
+    'if',
+    'for',
+    'await',
+    'switch',
+    'case',
+    'default',
+    'try',
+    'catch',
+    'finally',
+    'then',
+    'else',
+]
+
+const BLOCK_HEAD = new RegExp(`\\{([#:/])\\s*(${BLOCK_KEYWORDS.join('|')})\\b`, 'g')
+
+export function structuralBlockTokens(source: string): SemanticToken[] {
+    const tokens: SemanticToken[] = []
+    for (const match of source.matchAll(BLOCK_HEAD)) {
+        const braceStart = match.index
+        const sigil = match[1]
+        const keyword = match[2]
+        if (keyword === undefined) {
+            continue
+        }
+        const keywordStart = braceStart + match[0].length - keyword.length
+        tokens.push({ start: braceStart, length: 2, type: 'operator', modifiers: [] })
+        tokens.push({ start: keywordStart, length: keyword.length, type: 'keyword', modifiers: [] })
+        /* A `{#for …}` head carries abide-only connectors `of`/`by` that the shadow
+           lowers away (`of`) or never emits (`by`), so color them here. */
+        if (sigil === '#' && (keyword === 'for' || keyword === 'for await')) {
+            tokens.push(...forHeadConnectors(source, keywordStart + keyword.length))
+        }
+    }
+    return tokens
+}
+
+/*
+Scans a `{#for …}` head from `from` to its closing `}`, emitting `keyword` tokens
+for the `of`/`by` connectors at brace depth 0 — skipping any `of`/`by` nested in a
+destructure, call, or string so an identifier or object key is never miscolored.
+*/
+function forHeadConnectors(source: string, from: number): SemanticToken[] {
+    const tokens: SemanticToken[] = []
+    let depth = 0
+    let cursor = from
+    while (cursor < source.length) {
+        const char = source.charAt(cursor)
+        if (char === '"' || char === "'" || char === '`') {
+            cursor += 1
+            while (cursor < source.length && source.charAt(cursor) !== char) {
+                if (source.charAt(cursor) === '\\') {
+                    cursor += 1
+                }
+                cursor += 1
+            }
+        } else if (char === '{' || char === '(' || char === '[') {
+            depth += 1
+        } else if (char === ')' || char === ']') {
+            depth -= 1
+        } else if (char === '}') {
+            if (depth === 0) {
+                break
+            }
+            depth -= 1
+        } else if (depth === 0 && (char === 'o' || char === 'b')) {
+            const word = source.startsWith('of', cursor)
+                ? 'of'
+                : source.startsWith('by', cursor)
+                  ? 'by'
+                  : undefined
+            const isWordBoundary = (offset: number): boolean => /\s/.test(source.charAt(offset))
+            if (
+                word !== undefined &&
+                isWordBoundary(cursor - 1) &&
+                isWordBoundary(cursor + word.length)
+            ) {
+                tokens.push({ start: cursor, length: word.length, type: 'keyword', modifiers: [] })
+                cursor += word.length
+                continue
+            }
+        }
+        cursor += 1
+    }
+    return tokens
+}

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

@@ -0,0 +1,61 @@
+import { isAnchorPositioned } from './isAnchorPositioned.ts'
+import type { TemplateNode } from './types/TemplateNode.ts'
+import type { AnchorRole, AnchorWalkAdapter } from './walkAnchorOrder.ts'
+
+/*
+The template-AST side of the shared anchor-ordering rule (`walkAnchorOrder`). Classifies each
+parsed node by the SAME positions the realized-DOM side recovers, so the compiler's `anIndex`
+numbering and the runtime's `scanAnchors` collection cannot disagree.
+
+Anchor positions, in document order: a control-flow/component node and a `<slot>`/outlet
+element each contribute themselves (one anchor, fresh-context body — not descended); a text
+node whose reactive parts are interleaved contributes one anchor per non-static part. A
+skeleton-structure element is a container we descend; everything else (static text, a
+text-leaf's marker-free text, script/style, a node outside any skeleton) contributes nothing.
+
+`inSkeleton`/`markText` come from the context pass (the element-hole + boundary axes), read here
+so the adapter stays a pure classifier — the anchor counter never re-derives the context.
+*/
+export function templateAnchorAdapter(
+    inSkeleton: WeakMap<TemplateNode, boolean>,
+    markText: WeakMap<TemplateNode, boolean>,
+): AnchorWalkAdapter<TemplateNode> {
+    return {
+        classify: (node: TemplateNode): AnchorRole => {
+            /* A node outside an active skeleton numbers nothing — its block/text mounts on the
+               host directly (top-level / inside a branch), no anchor. */
+            if (inSkeleton.get(node) !== true) {
+                /* It may still be a non-skeleton CONTAINER whose descendants open their own
+                   skeletons (a static wrapper element), so recurse into elements, skip leaves. */
+                return node.kind === 'element' ? { kind: 'recurse' } : { kind: 'skip' }
+            }
+            /* An anchor-positioned node IS one anchor and its body is a fresh context. */
+            if (isAnchorPositioned(node)) {
+                return { kind: 'anchor', positions: [node] }
+            }
+            /* A component/snippet inside a skeleton that isn't anchor-positioned (a snippet
+               declares a builder) — fresh context, no anchor, no descent. */
+            if (node.kind === 'component' || node.kind === 'snippet') {
+                return { kind: 'skip' }
+            }
+            /* Interleaved reactive text: one anchor per non-static part, document order. */
+            if (node.kind === 'text') {
+                return markText.get(node) === true
+                    ? {
+                          kind: 'anchor',
+                          positions: node.parts.filter((part) => part.kind !== 'static'),
+                      }
+                    : { kind: 'skip' }
+            }
+            /* A skeleton-structure element — descend into its children. */
+            if (node.kind === 'element') {
+                return { kind: 'recurse' }
+            }
+            return { kind: 'skip' }
+        },
+        /* A branch/case is a transparent grouping inside its block — the context pass already
+           records its children's reset state, so the walk descends straight through it. */
+        childrenOf: (node: TemplateNode): readonly TemplateNode[] =>
+            'children' in node ? node.children : [],
+    }
+}

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

@@ -0,0 +1,44 @@
+import { OUTLET_TAG } from '../runtime/OUTLET_TAG.ts'
+import { isControlFlow } from './isControlFlow.ts'
+import { isTextLeaf } from './isTextLeaf.ts'
+import type { TemplateNode } from './types/TemplateNode.ts'
+import type { ElementRole, ElementWalkAdapter } from './walkElementOrder.ts'
+
+/*
+The template-AST side of the shared element-hole numbering rule (`walkElementOrder`). Classifies
+each parsed node by the SAME holes the parsed-DOM side recovers (`domElementAdapter`), so the
+compiler's `elIndex` numbering and the runtime's `HOLE_ATTRIBUTE` path collection cannot
+disagree.
+
+A skeleton element is a numbered element (descended into); it is a HOLE when it carries a
+reactive attribute/listener/bind, or binds reactive text marker-free as a text leaf — exactly
+the elements `generateSkeleton` stamps with `HOLE_ATTRIBUTE`. A control-flow block, component,
+snippet, `<slot>`, or outlet is a fresh build context (its content numbers in its own skeleton),
+and a text/script/style/branch/case carries no element index — all skip.
+*/
+export const templateElementAdapter: ElementWalkAdapter<TemplateNode> = {
+    classify: (node: TemplateNode): ElementRole => {
+        /* Fresh build contexts — their content is numbered by their own skeleton, not here. */
+        if (isControlFlow(node) || node.kind === 'component' || node.kind === 'snippet') {
+            return { kind: 'skip' }
+        }
+        if (node.kind !== 'element') {
+            return { kind: 'skip' } // text / script / style / standalone branch|case
+        }
+        /* A `<slot>` fill point or a layout outlet — fresh context (slot fallback / outlet has
+           none), anchor-positioned, never an element hole. */
+        if (node.tag === 'slot' || node.tag === OUTLET_TAG) {
+            return { kind: 'skip' }
+        }
+        const hasReactiveAttr = node.attrs.some((attr) => attr.kind !== 'static')
+        const hasReactiveTextChild = node.children.some(
+            (child) => child.kind === 'text' && child.parts.some((part) => part.kind !== 'static'),
+        )
+        return {
+            kind: 'element',
+            isHole: hasReactiveAttr || (hasReactiveTextChild && isTextLeaf(node)),
+        }
+    },
+    childrenOf: (node: TemplateNode): readonly TemplateNode[] =>
+        'children' in node ? node.children : [],
+}

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

@@ -0,0 +1,11 @@
+/*
+A semantic-highlighting token in original `.abide` source coordinates. `type` and
+`modifiers` are legend names (see ABIDE_SEMANTIC_TOKENS_LEGEND), resolved to wire
+indices only at encode time.
+*/
+export type SemanticToken = {
+    start: number
+    length: number
+    type: string
+    modifiers: string[]
+}

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

@@ -40,6 +40,11 @@ export type TemplateNode =
           async: boolean
           children: TemplateNode[]
           loc?: number
+          /* Source offsets of the binding name, `by` key, and index — so the shadow
+             maps hover/highlighting onto them (absent for synthesised/missing parts). */
+          asLoc?: number
+          keyLoc?: number
+          indexLoc?: number
       }
     | { kind: 'if'; condition: string; children: TemplateNode[]; loc?: number }
     | {
@@ -52,6 +57,8 @@ export type TemplateNode =
           as: string | undefined
           children: TemplateNode[]
           loc?: number
+          /* Source offset of an inline blocking `then` binding (`{#await p then v}`). */
+          asLoc?: number
       }
     | { kind: 'try'; children: TemplateNode[] }
     | {
@@ -59,6 +66,8 @@ export type TemplateNode =
           branch: 'then' | 'catch' | 'finally'
           as: string | undefined
           children: TemplateNode[]
+          /* Source offset of the `then`/`catch` binding, so the shadow maps it. */
+          asLoc?: number
       }
     | {
           kind: 'component'

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

@@ -0,0 +1,57 @@
+/*
+The ONE document-order anchor-numbering rule, shared by every side that recovers a skeleton's
+`<!--a-->` anchor positions. The same "why" — assign every block anchor, slot, and
+interleaved-reactive-text part a position in document order, recover it on the other side — was
+computed twice with no shared definition: `skeletonContext` re-derived it over the template AST
+(assigning `anIndex`), `scanAnchors` re-derived it over the realized DOM (collecting the live
+`a` comments). Each hand-mirrored the same traversal, so a change to one drifted silently from
+the other — the index-desync class the runtime anchor guards exist to catch.
+
+This module owns the traversal SHAPE as a sibling-list scan. A per-substrate
+`AnchorWalkAdapter` classifies each node it meets into one of three roles, and that
+classification — plus the document-order scan over it — IS the shared rule. The two substrates
+differ only in how a fresh-context region is delimited (a control-flow/component/slot SUBTREE on
+the AST side; a `[`…`]` / `abide:` marker-bracketed sibling RUN on the realized-DOM side), so
+the adapter, not this walk, skips the region; the walk guarantees both sides emit the same
+positions in the same order.
+*/
+
+/* What a node contributes as the scan reaches it, in document order. */
+export type AnchorRole =
+    /* Emit this node's anchor positions (zero or more — a reactive text node carries one per
+       non-static part), then do NOT descend. A block/component/slot is itself one anchor whose
+       body is a fresh context; an interleaved reactive text node is several. */
+    | { kind: 'anchor'; positions: readonly object[] }
+    /* An own-skeleton container — descend into its children, contributing no anchor itself (a
+       static/host element). */
+    | { kind: 'recurse' }
+    /* Contribute nothing and do not descend — a static text leaf, a script/style, or a
+       boundary the adapter handles out-of-band (range markers on the DOM side). */
+    | { kind: 'skip' }
+
+/* The single substrate fact the shared walk needs: classify a node. The adapter owns substrate
+   detail (what an anchor is, what a fresh-context boundary is, how to reach children); the walk
+   owns only document order. */
+export type AnchorWalkAdapter<TNode> = {
+    classify: (node: TNode) => AnchorRole
+    childrenOf: (node: TNode) => readonly TNode[]
+}
+
+/* Scan `nodes` in document order, calling `emit` once per anchor position in the order both
+   sides must agree on. Pure: the adapter decides roles, this owns only the order. */
+export function walkAnchorOrder<TNode>(
+    nodes: readonly TNode[],
+    adapter: AnchorWalkAdapter<TNode>,
+    emit: (position: object) => void,
+): void {
+    for (const node of nodes) {
+        const role = adapter.classify(node)
+        if (role.kind === 'anchor') {
+            for (const position of role.positions) {
+                emit(position)
+            }
+        } else if (role.kind === 'recurse') {
+            walkAnchorOrder(adapter.childrenOf(node), adapter, emit)
+        }
+    }
+}

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

@@ -0,0 +1,60 @@
+/*
+The ONE pre-order element-hole numbering rule, shared by every side that positions a skeleton's
+located elements. The same "why" — number the bound elements in pre-order, recover them on the
+other side — was computed twice with no shared definition: `skeletonContext` threaded an `el`
+counter over the template AST (assigning `elIndex`), `indexElementHoles` re-walked the parsed
+skeleton DOM (recording each `HOLE_ATTRIBUTE` element's path). Each hand-mirrored the same
+element-only pre-order, so a change to one drifted silently from the other — the index-desync
+class `resolveElementHole` exists to catch.
+
+This module owns the traversal SHAPE: an element-only pre-order over a sibling list, threading
+an element-only path. A per-substrate `ElementWalkAdapter` classifies each node — a numbered
+element (a hole emits, all elements descend) or a skip (non-element / fresh-context boundary) —
+and that classification, plus the path-threading scan over it, IS the shared rule. The two
+substrates differ only in what marks a hole (a reactive attr/text-leaf on the AST side, the
+`HOLE_ATTRIBUTE` on the parsed-DOM side) and where a fresh context begins (a control-flow/
+component/slot SUBTREE on the AST side; the parsed skeleton already prunes those to `<!--a-->`
+anchors, so the DOM side only meets its own elements), which the adapter owns — the walk
+guarantees both number the same elements in the same element-only order.
+*/
+
+/* What a node contributes as the pre-order scan reaches it. */
+export type ElementRole =
+    /* An element in this skeleton: it consumes an element-only index (so a later sibling's
+       path stays stable), emits its hole position when `isHole`, and is descended into. */
+    | { kind: 'element'; isHole: boolean }
+    /* A non-element (text/comment) or a fresh-context boundary (control-flow/component/slot):
+       contributes no index, no hole, and is not descended. */
+    | { kind: 'skip' }
+
+/* The substrate facts the shared walk needs: classify a node, reach its children. The adapter
+   owns substrate detail (what an element hole is, how to reach children); the walk owns only
+   the element-only pre-order and the path it threads. */
+export type ElementWalkAdapter<TNode> = {
+    classify: (node: TNode) => ElementRole
+    childrenOf: (node: TNode) => readonly TNode[]
+}
+
+/* Scan `nodes` in element-only pre-order, calling `emit` once per hole with its element-only
+   path — the order and path both sides must agree on. Pure: the adapter decides roles, this
+   owns only the order and the path prefix. */
+export function walkElementOrder<TNode>(
+    nodes: readonly TNode[],
+    adapter: ElementWalkAdapter<TNode>,
+    emit: (node: TNode, path: number[]) => void,
+    prefix: number[] = [],
+): void {
+    let elementIndex = 0
+    for (const node of nodes) {
+        const role = adapter.classify(node)
+        if (role.kind === 'skip') {
+            continue
+        }
+        const path = [...prefix, elementIndex]
+        elementIndex += 1
+        if (role.isHole) {
+            emit(node, path)
+        }
+        walkElementOrder(adapter.childrenOf(node), adapter, emit, path)
+    }
+}

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

@@ -1,11 +1,12 @@
 import { snippetPayload } from '../../shared/snippet.ts'
 import { effect } from '../effect.ts'
+import { SNIPPET_CLOSE, SNIPPET_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'
 
 /*
 A `{snippet(args)}` interpolation: mount the branded builder's nodes in a range
@@ -30,7 +31,7 @@ the args; a later argument change rebuilds fresh (the SSR markers stay as the ra
 export function appendSnippet(parent: Node, read: () => unknown): void {
     const hydration = RENDER.hydration
     /* Mount scopes register with the owner so they dispose on owner teardown, not
-       only on an argument-driven rebuild via clearBetween. */
+       only on an argument-driven rebuild via replaceRange. */
     const group = scopeGroup()
     let dispose: (() => void) | undefined
 
@@ -44,15 +45,15 @@ export function appendSnippet(parent: Node, read: () => unknown): void {
     let open: Comment
     let close: Comment
     if (hydration !== undefined) {
-        open = openMarker(parent, 'abide:snippet')
+        open = openMarker(parent, SNIPPET_OPEN)
         const builder = builderOf()
         if (builder !== undefined) {
             dispose = group.track(scope(() => builder(parent))) // content claims the SSR nodes in place
         }
-        close = openMarker(parent, '/abide:snippet')
+        close = openMarker(parent, SNIPPET_CLOSE)
     } else {
-        open = openMarker(parent, 'abide:snippet')
-        close = openMarker(parent, '/abide:snippet')
+        open = openMarker(parent, SNIPPET_OPEN)
+        close = openMarker(parent, SNIPPET_CLOSE)
         const builder = builderOf()
         if (builder !== undefined) {
             dispose = group.track(fillBefore(close, builder))
@@ -68,7 +69,7 @@ export function appendSnippet(parent: Node, read: () => unknown): void {
             first = false
             return
         }
-        clearBetween(open, close, dispose)
-        dispose = builder !== undefined ? group.track(fillBefore(close, builder)) : undefined
+        const next = replaceRange(open, close, dispose, builder)
+        dispose = next !== undefined ? group.track(next) : undefined
     })
 }

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 { isComment } from './isComment.ts'
 import { parseRawNodes } from './parseRawNodes.ts'
 
 const CLOSE = '/abide:html'
@@ -106,8 +107,3 @@ function appendRawHtml(parent: Node, read: () => unknown): void {
         set(markup())
     })
 }
-
-/* A comment node carrying exactly `data`. */
-function isComment(node: Node, data: string): boolean {
-    return (node as { data?: string }).data === data && node.childNodes.length === 0
-}