@abide/abide 0.40.2 → 0.41.1

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

@@ -1,5 +1,4 @@
-import { RESUME } from '../runtime/RESUME.ts'
-import { seedStreamedResolution } from '../seedStreamedResolution.ts'
+import { seedResolved } from '../seedResolved.ts'
 
 /*
 Bundle-side consumer of an SSR stream chunk, the counterpart of the doc stream's inline
@@ -31,7 +30,7 @@ export function applyResolved(root: Element, frame: string): void {
        bundle-consumed stream can't adopt a resolved branch while dropping its cache key. */
     if (resolved.nodeName === 'ABIDE-CACHE') {
         try {
-            seedStreamedResolution(JSON.parse(resolved.textContent ?? 'null'))
+            seedResolved({ kind: 'cache', resolution: JSON.parse(resolved.textContent ?? 'null') })
         } catch {
             /* malformed payload — leave unseeded; the read falls back to a live fetch */
         }
@@ -47,7 +46,7 @@ export function applyResolved(root: Element, frame: string): void {
        recording it lets a later hydrate adopt this branch (no re-fetch). */
     const payload = resolved.firstChild as Element | null
     if (payload !== null && payload.nodeName === 'SCRIPT') {
-        RESUME[Number(id)] = payload.textContent ?? ''
+        seedResolved({ kind: 'resume', id: Number(id), resume: payload.textContent ?? '' })
         payload.remove()
     }
     const open = `abide:await:${id}`

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

@@ -1,19 +1,25 @@
 import { decodeRefJson } from '../../shared/decodeRefJson.ts'
 import { effect } from '../effect.ts'
 import { claimChild } from '../runtime/claimChild.ts'
+import { RANGE_CLOSE, RANGE_OPEN } from '../runtime/RANGE_MARKER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import type { ResumeEntry } from '../runtime/RESUME.ts'
 import { RESUME } from '../runtime/RESUME.ts'
 import { scope } from '../runtime/scope.ts'
 import { scopeGroup } from '../runtime/scopeGroup.ts'
+import type { State } from '../runtime/types/State.ts'
+import { state } from '../state.ts'
+import { buildDetachedRange } from './buildDetachedRange.ts'
 import { discardBoundary } from './discardBoundary.ts'
-import { enterNamespace } from './enterNamespace.ts'
+import { removeRange } from './removeRange.ts'
 
 /*
 Async binding — the runtime for `<template await>`. Renders the pending branch,
 then swaps to the resolved branch (with the value) or the error branch on settle.
-Each branch is a RANGE of element roots, tracked as a node array so a multi-root
-branch inserts/removes as a unit.
+Each branch's content lives in a RANGE bounded by two comment markers (`[`…`]`), the
+same model `when`/`switch`/`each` use — so a multi-root branch inserts as a unit
+(`buildDetachedRange`) and detaches as a unit (`removeRange`), rather than tracking and
+removing a node array by hand.
 
 The read runs inside a abide-ui `effect`, so it's reactive: `abide/shared/cache`'s
 store subscribes the key it reads to this effect (createSubscriber is abide-ui-
@@ -47,88 +53,127 @@ export function awaitBlock(
     /* The live branch's scope, registered with the owner so it disposes on owner
        teardown — not only when a settle/re-run swaps branches via detach. */
     const group = scopeGroup()
-    let active: { nodes: Node[]; dispose: () => void } | undefined
+    let active: { start: Comment; end: Comment; dispose: () => void } | undefined
     let anchor: Node | undefined
     let first = true
     /* Bumped each run so a prior run's in-flight promise can't clobber a newer one. */
     let generation = 0
+    /* The resolved value, held as a reactive cell so the then-branch reads it through its
+       own effects. A re-run that resolves to a NEW value SETS this cell instead of rebuilding
+       the branch — the branch (and any keyed `each` inside it) survives and updates in place,
+       so a live cache patch no longer flashes the whole subtree. The branch is rebuilt only
+       across a kind change (pending/catch ↔ then), where it has to be. */
+    let valueCell: State<unknown> | undefined
+    /* Which branch is currently mounted, so a settle knows whether it can update the cell in
+       place (then→then) or must build a fresh branch. */
+    let activeKind: 'pending' | 'then' | 'catch' | undefined
 
     const detach = (): void => {
         if (active !== undefined) {
             active.dispose()
-            /* Remove via each node's LIVE parent, not the captured `parent` — when this
-               await is a bare child of a control-flow branch, `parent` is the branch's
-               build fragment, emptied into the document once the enclosing block placed
-               it (`place` already inserts via `anchor.parentNode` for the same reason). */
-            for (const node of active.nodes) {
-                node.parentNode?.removeChild(node)
-            }
+            /* `removeRange` evicts the markers AND everything between them via the end
+               marker's LIVE parent — not the captured `parent`, which (when this await is a
+               bare child of a control-flow branch) is the branch's build fragment, emptied
+               into the document once the enclosing block placed it. */
+            removeRange(active.start, active.end)
             active = undefined
         }
     }
 
-    /* Replace the current content with a freshly-built branch, before the anchor. The
-       branch builds into a fragment (so any content — components, text, nested blocks
-       — appends freely), whose top-level nodes are tracked for the next swap. */
+    /* Replace the current content with a freshly-built branch, before the anchor. The branch
+       builds into a detached `[`…`]`-bracketed fragment (so any content — components, text,
+       nested blocks — appends freely), the same create primitive the keyed-list runtimes use,
+       which lands as a marker-bounded range the next swap detaches with `removeRange`. */
     const place = (build: (parent: Node) => void): void => {
         detach()
-        const fragment = document.createDocumentFragment()
-        const dispose = group.track(
-            enterNamespace(anchor?.parentNode ?? parent, () => scope(() => build(fragment))),
-        )
-        const nodes = [...fragment.childNodes]
-        ;(anchor?.parentNode ?? parent).insertBefore(fragment, anchor ?? null)
-        active = { nodes, dispose }
+        const namespaceParent = anchor?.parentNode ?? parent
+        const { start, end, fragment, dispose } = buildDetachedRange(namespaceParent, build)
+        const tracked = group.track(dispose)
+        namespaceParent.insertBefore(fragment, anchor ?? null)
+        active = { start, end, dispose: tracked }
+    }
+
+    /* Settle to a resolved value. then→then updates the cell in place — the branch and its
+       inner each survive (no flash); any other prior kind builds a fresh then-branch around
+       a new cell. renderThen receives the CELL (not the raw value), so the branch reads it
+       reactively and re-runs its own effects when a later settle sets it. */
+    const settleThen = (value: unknown): void => {
+        if (activeKind === 'then' && valueCell !== undefined) {
+            valueCell.value = value
+            return
+        }
+        const cell = state(value)
+        valueCell = cell
+        place((host) => renderThen(host, cell))
+        activeKind = 'then'
+    }
+
+    /* Settle to a rejection: surface it with no catch branch, else swap to the catch branch. */
+    const settleError = (error: unknown): void => {
+        if (renderCatch === undefined) {
+            throw error
+        }
+        valueCell = undefined
+        place((host) => renderCatch(host, error))
+        activeKind = 'catch'
     }
 
     /* Render a settled-or-pending result into the current generation. */
     const render = (result: unknown): void => {
         const gen = generation
         if (!isThenable(result)) {
-            place((host) => renderThen(host, result)) // warm-sync → resolved now, no flash
+            settleThen(result) // warm-sync → resolved now, no flash
             return
         }
-        if (renderPending !== undefined) {
-            place((host) => renderPending(host))
-        } else {
-            detach()
+        /* A then-branch is already mounted (a revalidation): keep it visible and update in
+           place when the new value settles, instead of blanking to pending and rebuilding —
+           this is the no-flash live-update path. A first load (or a prior pending/catch)
+           shows the pending branch (or detaches) while the promise is in flight. */
+        if (activeKind !== 'then') {
+            if (renderPending !== undefined) {
+                place((host) => renderPending(host))
+                activeKind = 'pending'
+            } else {
+                detach()
+                activeKind = undefined
+            }
         }
         result.then(
             (value) => {
                 if (gen === generation) {
-                    place((host) => renderThen(host, value))
+                    settleThen(value)
                 }
             },
             (error) => {
-                if (gen !== generation) {
-                    return
-                }
-                /* No catch branch → surface the rejection instead of an empty branch. */
-                if (renderCatch === undefined) {
-                    throw error
+                if (gen === generation) {
+                    settleError(error)
                 }
-                place((host) => renderCatch(host, error))
             },
         )
     }
 
-    /* Adopt an SSR-resolved branch in place (its content claims the existing nodes),
-       then park an anchor just before the close marker for later swaps. The adopted
-       content is everything the build claimed between the open and close markers. */
+    /* Adopt an SSR-resolved branch in place (its content claims the existing nodes), then
+       wrap the adopted region in `[`…`]` markers and park an anchor just before the close
+       marker for later swaps. The adopted content is everything the build claimed between
+       the open and close markers; bracketing it makes the adopted branch a marker-bounded
+       range identical to a freshly-`place`d one, so the FIRST swap detaches it with
+       `removeRange` like every later swap (no node-array special case). */
     const adopt = (open: Node | null, build: (parent: Node) => void): void => {
         const cursor = hydration as NonNullable<typeof hydration>
-        cursor.next.set(parent, open?.nextSibling ?? null)
+        const firstAdopted = open?.nextSibling ?? null
+        cursor.next.set(parent, firstAdopted)
         const dispose = group.track(scope(() => build(parent)))
         const close = claimChild(cursor, parent)
         cursor.next.set(parent, close?.nextSibling ?? null)
-        const nodes: Node[] = []
-        for (let node = open?.nextSibling ?? null; node !== null && node !== close; ) {
-            nodes.push(node)
-            node = node.nextSibling
-        }
+        /* Bracket the adopted nodes: `[` before the first claimed node (or before `close`
+           for an empty branch), `]` then the anchor just before `close`. */
+        const start = document.createComment(RANGE_OPEN)
+        parent.insertBefore(start, firstAdopted ?? close)
+        const end = document.createComment(RANGE_CLOSE)
+        parent.insertBefore(end, close)
         anchor = document.createTextNode('')
         parent.insertBefore(anchor, close)
-        active = { nodes, dispose }
+        active = { start, end, dispose }
     }
 
     /* Discard the SSR boundary and (re)build the block from the live promise, fresh
@@ -176,11 +221,21 @@ export function awaitBlock(
             }
         }
         if (entry !== undefined) {
+            /* Build the adopted branch around a value CELL (then) so a later re-run updates
+               it in place, exactly like a fresh mount. The `throw` for a catch-less rejection
+               stays OUTSIDE the adopt try/catch so it surfaces rather than triggering the
+               cold-rebuild fallback. */
             let build: (host: Node) => void
+            let cell: State<unknown> | undefined
+            let kind: 'then' | 'catch'
             if (entry.ok) {
-                build = (host) => renderThen(host, entry.value)
+                cell = state(entry.value)
+                const resolved = cell
+                build = (host) => renderThen(host, resolved)
+                kind = 'then'
             } else if (renderCatch !== undefined) {
                 build = (host) => renderCatch(host, entry.error)
+                kind = 'catch'
             } else {
                 /* A resumed rejection with no catch branch surfaces (mirrors the cold
                    path); in practice the server 500s such a block, so none resumes. */
@@ -188,14 +243,19 @@ export function awaitBlock(
             }
             try {
                 adopt(open, build)
+                valueCell = cell
+                activeKind = kind
             } catch {
                 rebuildCold(open)
             }
             return
         }
         if (!isThenable(result)) {
+            const cell = state(result)
             try {
-                adopt(open, (host) => renderThen(host, result))
+                adopt(open, (host) => renderThen(host, cell))
+                valueCell = cell
+                activeKind = 'then'
             } catch {
                 rebuildCold(open)
             }

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

@@ -4,7 +4,9 @@ import { claimExpected } from '../runtime/claimExpected.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
 import { scopeGroup } from '../runtime/scopeGroup.ts'
-import { enterNamespace } from './enterNamespace.ts'
+import type { State } from '../runtime/types/State.ts'
+import { state } from '../state.ts'
+import { buildDetachedRange } from './buildDetachedRange.ts'
 import { moveRange } from './moveRange.ts'
 import { removeRange } from './removeRange.ts'
 import type { EachRow } from './types/EachRow.ts'
@@ -32,7 +34,11 @@ export function each<T>(
     parent: Node,
     items: () => Iterable<T>,
     keyOf: (item: T) => string,
-    render: (parent: Node, item: T) => void,
+    /* The row receives its item and its position as reactive cells (not raw snapshots): a
+       re-key with a changed value, or a reorder that shifts the row, sets the matching cell
+       and re-runs the row's effects in place. The compiler binds the `as`/`index` names to
+       read them; a direct caller reads `item.value` / `index.value`. */
+    render: (parent: Node, item: State<T>, index: State<number>) => void,
     before: Node | null = null,
 ): void {
     const rows = new Map<string, EachRow>()
@@ -49,27 +55,28 @@ export function each<T>(
        (`scope` builds untracked), so a raw reactive read in the row content — e.g. a
        nested `<script>` body — can't re-reconcile the whole list. Only `items()` drives
        the each; each row's own interpolations track through their own effects. */
-    const buildRow = (item: T): EachRow => {
+    const buildRow = (item: T, position: number): EachRow => {
+        /* Item and position are held in reactive cells the row reads, so a later re-key with
+           a changed value, or a reorder that shifts the row, updates it in place (see the
+           reconcile below) instead of rebuilding it. */
+        const cell = state(item) as State<unknown>
+        const indexCell = state(position)
         const hydration = RENDER.hydration
         if (hydration !== undefined) {
             const start = claimExpected(hydration, parent, 'each row start marker')
             hydration.next.set(parent, start.nextSibling)
-            const dispose = group.track(scope(() => render(parent, item)))
+            const dispose = group.track(scope(() => render(parent, cell as State<T>, indexCell)))
             const end = claimExpected(hydration, parent, 'each row end marker')
             hydration.next.set(parent, end.nextSibling)
-            return { start, end, dispose }
+            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, item))),
+        /* 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, 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
@@ -94,8 +101,10 @@ export function each<T>(
     let adopting = false
     const hydration = RENDER.hydration
     if (hydration !== undefined) {
+        let position = 0
         for (const item of items()) {
-            rows.set(keyOf(item), buildRow(item)) // claims the SSR row where it sits
+            rows.set(keyOf(item), buildRow(item, position)) // claims the SSR row where it sits
+            position += 1
         }
         anchor = document.createTextNode('')
         parent.insertBefore(anchor, claimChild(hydration, parent))
@@ -145,8 +154,15 @@ export function each<T>(
                 const key = keys[index] as string
                 let row = rows.get(key)
                 if (row === undefined) {
-                    row = buildRow(list[index] as T)
+                    row = buildRow(list[index] as T, index)
                     rows.set(key, row)
+                } else {
+                    /* Surviving key: push the (possibly new) item and position into the row's
+                       cells. Both write through `Object.is`, so an unchanged item/position is a
+                       no-op and a changed one re-runs only the row's own effects — the row's DOM
+                       is never rebuilt. A reorder thus repaints only the moved rows' `index`. */
+                    row.cell.value = list[index]
+                    row.indexCell.value = index
                 }
                 placeBefore(row, cursor)
                 cursor = row.start

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

@@ -2,9 +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 { enterNamespace } from './enterNamespace.ts'
+import type { State } from '../runtime/types/State.ts'
+import { state } from '../state.ts'
+import { buildDetachedRange } from './buildDetachedRange.ts'
 import { removeRange } from './removeRange.ts'
 import type { EachRow } from './types/EachRow.ts'
 
@@ -27,7 +28,10 @@ export function eachAsync<T>(
     parent: Node,
     items: () => AsyncIterable<T>,
     keyOf: (item: T) => string,
-    render: (parent: Node, item: T) => void,
+    /* The row receives its item and position as reactive cells — same contract as sync
+       `each`; the streaming runtime rebuilds the row on a re-yield rather than patching, and
+       the position is the stream arrival ordinal (a stream only appends, never reorders). */
+    render: (parent: Node, item: State<T>, index: State<number>) => void,
     /* Absent → an iterator rejection surfaces instead of rendering a catch branch. */
     renderCatch: ((parent: Node, error: unknown) => void) | undefined,
     before: Node | null = null,
@@ -44,25 +48,24 @@ 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). */
-    const insertRange = (build: (into: Node) => void): EachRow => {
-        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 }
+    /* 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 } => {
+        /* 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. */
-    let errorRange: EachRow | undefined
+    let errorRange: { start: Node; end: Node; dispose: () => void } | undefined
     const clearError = (): void => {
         if (errorRange !== undefined) {
             errorRange.dispose()
@@ -82,6 +85,7 @@ export function eachAsync<T>(
         clearError() // a fresh run drops a prior error branch
         const iterable = items() // read (subscribe) synchronously
         const present = new Set<string>()
+        let arrivals = 0 // stream arrival ordinal → each row's index
         const drain = async (): Promise<void> => {
             const active = iterable[Symbol.asyncIterator]()
             iterator = active
@@ -96,14 +100,18 @@ export function eachAsync<T>(
                 }
                 const key = keyOf(result.value)
                 present.add(key)
-                /* A re-yielded key rebuilds the row from the new value, swapping the old
-                   range out (v1 has no in-place field patch — rows bind plain snapshots). */
+                /* A re-yielded key rebuilds the row from the new value (arrival order), swapping
+                   the old range out. The item rides in a cell — the row reads it reactively, same
+                   contract as sync `each` — but the streaming runtime rebuilds rather than patches. */
                 const stale = rows.get(key)
-                const item = result.value
-                rows.set(
-                    key,
-                    insertRange((host) => render(host, item)),
-                )
+                const cell = state(result.value) as State<unknown>
+                const indexCell = state(arrivals)
+                arrivals += 1
+                rows.set(key, {
+                    ...insertRange((host) => render(host, cell as State<T>, indexCell)),
+                    cell,
+                    indexCell,
+                })
                 if (stale !== undefined) {
                     stale.dispose()
                     removeRange(stale.start, stale.end)

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