@abide/abide 0.40.2 → 0.41.1

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

@@ -1,6 +1,11 @@
 import { assertExhaustive } from '../../shared/assertExhaustive.ts'
 import { OUTLET_CLOSE, OUTLET_OPEN } from '../runtime/OUTLET_MARKER.ts'
 import { OUTLET_TAG } from '../runtime/OUTLET_TAG.ts'
+import {
+    ANCHOR,
+    RANGE_CLOSE as RANGE_CLOSE_DATA,
+    RANGE_OPEN as RANGE_OPEN_DATA,
+} from '../runtime/RANGE_MARKER.ts'
 import { asOutlet } from './asOutlet.ts'
 import { composeProps } from './composeProps.ts'
 import { groupBindParts } from './groupBindParts.ts'
@@ -16,12 +21,16 @@ import { stripEffects } from './stripEffects.ts'
 import type { TemplateNode } from './types/TemplateNode.ts'
 import { VOID_TAGS } from './VOID_TAGS.ts'
 
-/* The range boundary comments a control-flow block emits around its content. They
-   serialize exactly as the client's `document.createComment('[' | ']')` markers, so
-   the client claims the same `[ … ]` boundary it builds — the comment-marked range
-   that lets a branch hold any content. */
-const RANGE_OPEN = '<!--[-->'
-const RANGE_CLOSE = '<!--]-->'
+/* The range boundary comments a control-flow block emits around its content. Sourced
+   from the SAME wire-alphabet constants the client's `document.createComment` markers
+   use (`RANGE_MARKER`), wrapped in comment syntax — so a server-emitted boundary and the
+   client `[ … ]` boundary it claims can never drift on a literal. */
+const RANGE_OPEN = `<!--${RANGE_OPEN_DATA}-->`
+const RANGE_CLOSE = `<!--${RANGE_CLOSE_DATA}-->`
+
+/* The skeleton positioning anchor a control-flow block / slot / outlet emits, sourced
+   from the same `ANCHOR` constant the client's anchor scan matches. */
+const ANCHOR_COMMENT = `<!--${ANCHOR}-->`
 
 /*
 Server code generator: turns the parsed template into statements that push HTML
@@ -172,7 +181,7 @@ export function generateSSR(
        Outside a skeleton (top-level / inside a branch) blocks mount on the host directly,
        so no anchor. */
     const anchorMark = (node: TemplateNode, target: string): string =>
-        inSkeleton.get(node) ? push(target, '<!--a-->') : ''
+        inSkeleton.get(node) ? push(target, ANCHOR_COMMENT) : ''
 
     function generate(node: TemplateNode, target: string): string {
         /* Every kind that mounts as a marker range is positioned by an `<!--a-->` anchor when
@@ -197,7 +206,7 @@ export function generateSSR(
                         ? `$text(await (${lowered}))`
                         : `$text(${lowered})`
                     return markText.get(node)
-                        ? `${target}.push('<!--a-->' + ${value});\n`
+                        ? `${target}.push('${ANCHOR_COMMENT}' + ${value});\n`
                         : `${target}.push(${value});\n`
                 })
                 .join('')
@@ -269,7 +278,15 @@ export function generateSSR(
             if (node.async) {
                 return anchor
             }
-            return `${anchor}for (const ${node.as} of (${lowerExpression(node.items)})) {\n${openRange(target)}${branchContent(node.children, target)}${closeRange(target)}}\n`
+            const rowBody = `${openRange(target)}${branchContent(node.children, target)}${closeRange(target)}`
+            /* `index="i"` binds the row position. SSR reads it as a plain number from
+               `entries()` over a materialized array; the client reads the same number from a
+               cell, so first paint is congruent. No index → a plain `for…of` over the items. */
+            const header =
+                node.index === undefined
+                    ? `for (const ${node.as} of (${lowerExpression(node.items)}))`
+                    : `for (const [${node.index}, ${node.as}] of [...(${lowerExpression(node.items)})].entries())`
+            return `${anchor}${header} {\n${rowBody}}\n`
         }
         if (node.kind === 'await') {
             return `${anchor}${generateAwait(node, target)}`

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

@@ -22,20 +22,21 @@ export function lowerContext(
     derivedNames: ReadonlySet<string>,
     computedNames: ReadonlySet<string> = new Set(),
 ) {
-    /* Branch-scoped signal bindings (from nested `<script>`s) — they deref to
-       `.value` like a `computed`. Pushed while a branch's script + markup compile,
-       popped after, so they shadow only within that subtree. */
+    /* Branch-scoped signal bindings (from nested `<script>`s, and the block value params
+       pushed by `withLocalDerived`) — they deref to `.value` like a `computed`, and as a
+       nearer lexical scope they SHADOW a same-named component signal. Pushed while a
+       branch's script + markup compile, popped after, so they shadow only within that
+       subtree. */
     const localDerived = new Set<string>()
-    const derefScope = (): ReadonlySet<string> =>
-        localDerived.size === 0 ? derivedNames : new Set([...derivedNames, ...localDerived])
 
     /* Parse `code` once and chain the reference rename and doc-access lowering over the
-       one tree — the two string passes would each parse + reprint. `derefScope()` is read
-       per call so a nested-`<script>` binding pushed mid-compile is honoured. */
+       one tree — the two string passes would each parse + reprint. `localDerived` is
+       snapshotted per call (as the transformer's block-local shadow set) so a binding
+       pushed mid-compile is honoured AND shadows a same-named component signal. */
     function lowerOnce(code: string): string {
         const source = ts.createSourceFile('expr.ts', code, ts.ScriptTarget.Latest, true)
         const result = ts.transform(source, [
-            signalRefsTransformer(stateNames, derefScope(), computedNames),
+            signalRefsTransformer(stateNames, derivedNames, computedNames, new Set(localDerived)),
             docAccessTransformer('model'),
         ])
         const output = TS_PRINTER.printFile(result.transformed[0] as ts.SourceFile).trim()
@@ -113,5 +114,24 @@ export function lowerContext(
         return result
     }
 
-    return { expression, statement, withNestedScripts, bindRead, bindWrite }
+    /* Pushes explicit names into the deref scope for `body` then pops them — the
+       programmatic counterpart to `withNestedScripts`, used to bind a block's value param
+       (an `await` `then` value, a keyed `each` item) as a reactive `.value` cell so the
+       branch reads it reactively and re-runs in place when the block sets the cell. */
+    function withLocalDerived<T>(names: string[], body: () => T): T {
+        const added: string[] = []
+        for (const name of names) {
+            if (!localDerived.has(name)) {
+                localDerived.add(name)
+                added.push(name)
+            }
+        }
+        const result = body()
+        for (const name of added) {
+            localDerived.delete(name)
+        }
+        return result
+    }
+
+    return { expression, statement, withNestedScripts, withLocalDerived, bindRead, bindWrite }
 }

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

@@ -560,11 +560,13 @@ function toControlFlow(attrs: TemplateAttr[], children: TemplateNode[]): Templat
     }
     const as = find('as')
     const key = find('key')
+    const index = find('index')
     return {
         kind: 'each',
         items: itemsCode,
         as: (as === undefined ? undefined : attrText(as)) ?? '_item',
         key: key === undefined ? undefined : attrText(key),
+        index: index === undefined ? undefined : attrText(index),
         async: find('await') !== undefined, // `<template each await>` over an AsyncIterable
         children,
         loc: attrLoc(items),

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

@@ -43,10 +43,19 @@ export function signalRefsTransformer(
     stateNames: ReadonlySet<string>,
     derivedNames: ReadonlySet<string>,
     computedNames: ReadonlySet<string> = new Set(),
+    /* Block-local signal bindings (an `await` `then` / keyed `each` value param, a nested
+       `<script>` declaration) — a nearer lexical scope than the component signals, so a
+       name here shadows a same-named `state`/`computed`/`derived` and derefs as a cell. */
+    blockLocal: ReadonlySet<string> = new Set(),
 ): ts.TransformerFactory<ts.SourceFile> {
     /* The signal names that a nested binding can shadow — only these matter for
        scope tracking, so we ignore every other local binding. */
-    const signalNames = new Set<string>([...stateNames, ...derivedNames, ...computedNames])
+    const signalNames = new Set<string>([
+        ...stateNames,
+        ...derivedNames,
+        ...computedNames,
+        ...blockLocal,
+    ])
     return (context) => (root) => {
         /* The identifier nodes that are names, not value reads — collected by walking
            each parent and recording its name children (`parent.name`, a label, a
@@ -88,6 +97,7 @@ export function signalRefsTransformer(
                         stateNames,
                         derivedNames,
                         computedNames,
+                        blockLocal,
                     )
                     if (replacement !== undefined) {
                         return ts.factory.createPropertyAssignment(node.name.text, replacement)
@@ -99,6 +109,7 @@ export function signalRefsTransformer(
                         stateNames,
                         derivedNames,
                         computedNames,
+                        blockLocal,
                     )
                     if (replacement !== undefined) {
                         return replacement
@@ -305,13 +316,19 @@ function functionParameters(node: ts.Node): ts.NodeArray<ts.ParameterDeclaration
 
 /* `model.<name>` for a state binding, `<name>()` for a computed doc-slot (the
    string-free reader `scope().derive` returns), `<name>.value` for a runtime cell
-   (linked / lens / transform-state), else undefined. */
+   (linked / lens / transform-state), else undefined. A `blockLocal` binding shadows
+   any same-named component signal — it is a nearer lexical scope — so it derefs as a
+   cell (`<name>.value`) regardless of a colliding `state`/`computed`/`derived`. */
 function referenceFor(
     name: string,
     stateNames: ReadonlySet<string>,
     derivedNames: ReadonlySet<string>,
     computedNames: ReadonlySet<string>,
+    blockLocal: ReadonlySet<string> = new Set(),
 ): ts.Expression | undefined {
+    if (blockLocal.has(name)) {
+        return ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier(name), 'value')
+    }
     if (stateNames.has(name)) {
         return ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier('model'), name)
     }

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/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/TemplateNode.ts

@@ -34,6 +34,8 @@ export type TemplateNode =
           items: string
           as: string
           key: string | undefined
+          /* `index="i"` → the row's reactive position, bound to this name; absent → unbound. */
+          index: string | undefined
           /* `await` on the tag → `items` is an AsyncIterable, drained on the client. */
           async: boolean
           children: TemplateNode[]

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)
+    }
+}