@abide/abide 0.40.2 → 0.41.0

package/AGENTS.md

@@ -159,7 +159,7 @@ Control flow — native `<template>`:
 | Directive | Shape |
 | --- | --- |
 | `<template if={c}>` … `<template elseif={c2}>` … `<template else>` | conditional chain (`else` must be last) |
-| `<template each={list} as="x" key="x.id">` | keyed list |
+| `<template each={list} as="x" key="x.id" index="i">` | keyed list (`index` binds the row's reactive position) |
 | `<template await={p}>` `<template then="v">` `<template catch="e">` `<template finally>` | promise (streams; branch value bound by `then`/`catch`) |
 | `<template switch={s}>` `<template case={v}>` … `<template default>` | first strict-`===` match |
 | `<template try>` `<template catch="e">` `<template finally>` | synchronous error boundary |

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # abide
 
+## 0.41.0
+
+### Minor Changes
+
+- [`ba08127`](https://github.com/briancray/abide/commit/ba081270c4721d64655457681e4ebcc79681f1d4) - `index="i"` on `<template each>` — bind the row's reactive position
+
+    `<template each={list} as="item" key="item.id" index="i">` binds the iteration index to a name. In a keyed `each` the index is reactive: a reorder/insert/remove that shifts a surviving row repaints its `{i}` in place (same DOM, no rebuild), riding the same `Object.is` cell-write path as the item binding. SSR renders the index via `entries()` so hydration stays congruent; async `each await` carries the stream arrival ordinal.
+
+- [`ba08127`](https://github.com/briancray/abide/commit/ba081270c4721d64655457681e4ebcc79681f1d4) - In-place reactive updates for `<template await>` `then` values and keyed `each` items
+
+    A re-settling `await` block and a re-keyed `each` row no longer rebuild their subtree — they update through a reactive value cell instead, so a live cache patch updates only what changed and never flashes the surrounding DOM.
+
+    - `awaitBlock` keeps the mounted `then`-branch across a re-run, setting a reactive value cell rather than detaching + rebuilding. A revalidation now keeps the stale branch visible and patches in place; the branch is rebuilt only across a pending/catch ↔ then kind change.
+    - The `then` binding is lowered to read that cell reactively — both a single identifier (`then="value"`) and a destructure (`then="[a, b]"` / `{ x, y }`), where each leaf is derived per-read so only the leaves whose value changed propagate.
+    - Keyed `each` holds each row's item in a reactive cell; a re-key with a changed value (same key, new object) writes the cell through `Object.is`, re-running only that row's effects with no DOM rebuild. The row `render` now receives `State<T>` (the compiler binds the `as` name to read it).
+    - A destructuring `each … as="[a, b]"` (or `{ x, y }`) with no explicit `key` now defaults the key to the row's raw item identity, like a plain `as`. Previously the default key re-emitted the destructure pattern, allocating a fresh array/object per reconcile, so keys never matched and every row rebuilt on any list change.
+    - A block value binding (`then="x"` / `each … as="x"`) now correctly shadows a same-named component `state`/`computed`/`derived`: it is a nearer lexical scope, so `{x}` in the block reads the resolved/row cell rather than the component signal. A destructure pattern's default/computed-key initializer is also lowered, so `then="{ id, label = fallback }"` resolves `fallback` against the component scope instead of emitting it raw.
+
 ## 0.40.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.40.2",
+    "version": "0.41.0",
     "type": "module",
     "sideEffects": false,
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",

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

@@ -0,0 +1,38 @@
+import ts from 'typescript'
+
+/*
+The leaf binding names a destructuring pattern introduces, in source order —
+`[a, b]` → `a, b`; `{ x, y: z }` → `x, z`; `[a, ...rest]` → `a, rest`; nested
+patterns flatten. Used to re-bind an `await` `then` destructure as per-leaf
+reactive reads of the resolved-value cell, so a re-settle updates each leaf in
+place instead of rebuilding the branch.
+*/
+export function destructureBindingNames(pattern: string): string[] {
+    const source = ts.createSourceFile(
+        'pattern.ts',
+        `const ${pattern} = $;`,
+        ts.ScriptTarget.Latest,
+        true,
+    )
+    const names: string[] = []
+    const collect = (name: ts.BindingName): void => {
+        if (ts.isIdentifier(name)) {
+            names.push(name.text)
+            return
+        }
+        // Object/array pattern: each element binds; array holes are OmittedExpression, not BindingElement.
+        for (const element of name.elements) {
+            if (ts.isBindingElement(element)) {
+                collect(element.name)
+            }
+        }
+    }
+    for (const statement of source.statements) {
+        if (ts.isVariableStatement(statement)) {
+            for (const declaration of statement.declarationList.declarations) {
+                collect(declaration.name)
+            }
+        }
+    }
+    return names
+}

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

@@ -4,6 +4,7 @@ import { OUTLET_TAG } from '../runtime/OUTLET_TAG.ts'
 import { asOutlet } from './asOutlet.ts'
 import { bindListenEvent } from './bindListenEvent.ts'
 import { composeProps } from './composeProps.ts'
+import { destructureBindingNames } from './destructureBindingNames.ts'
 import { groupBindParts } from './groupBindParts.ts'
 import { isControlFlow } from './isControlFlow.ts'
 import { isWhitespaceText } from './isWhitespaceText.ts'
@@ -85,10 +86,50 @@ export function generateBuild(
         expression: lowerExpression,
         statement: lowerStatement,
         withNestedScripts,
+        withLocalDerived,
         bindRead,
         bindWrite,
     } = lowerContext(stateNames, derivedNames, computedNames)
 
+    /* A value binding the runtime can update in place (an `await` `then` value, a keyed `each`
+       item) is passed as a reactive `.value` cell; the consuming branch/row reads its NAME(s)
+       as a deref so it re-runs in place when a re-settle/re-key sets the cell. */
+    const isPlainIdentifier = (name: string | undefined): name is string =>
+        name !== undefined && /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name)
+
+    /* How a reactive value param binds: `param` is the thunk's value parameter (the cell),
+       `prefix` declares any per-leaf readers, `localNames` enter the deref scope for the body.
+       A plain identifier reads the cell directly (`item` → `item.value`); a destructure
+       re-applies over the cell per read so each leaf stays reactive (JS handles
+       defaults/rest/rename/nesting). The caller lowers the body with `localNames` derived. */
+    function reactiveBinding(authorParam: string): {
+        param: string
+        prefix: string
+        localNames: string[]
+    } {
+        if (isPlainIdentifier(authorParam)) {
+            return { param: authorParam, prefix: '', localNames: [authorParam] }
+        }
+        const cellParam = nextVar('aw')
+        const deriveVar = nextVar('ad')
+        const leaves = destructureBindingNames(authorParam)
+        /* Lower the destructure declaration so a default/computed-key initializer that
+           references a component signal (`{ label = fallback }`, `{ [key]: v }`) is rewritten
+           to its `model`/cell form — the bound leaf names are name-slots and stay untouched.
+           A pattern with no such initializer lowers to itself, so the common case is unchanged
+           and SSR (which lowers the same declaration) stays congruent. */
+        const declaration = lowerStatement(`const ${authorParam} = ${cellParam}.value`)
+        const prefix =
+            `const ${deriveVar} = { get value() { ${declaration} return { ${leaves.join(', ')} }; } };\n` +
+            leaves
+                .map(
+                    (leaf) =>
+                        `const ${leaf} = { get value() { return ${deriveVar}.value.${leaf}; } };\n`,
+                )
+                .join('')
+        return { param: cellParam, prefix, localNames: leaves }
+    }
+
     /* Emits the wiring for one non-static attribute against an already-obtained skeleton
        element var — reactive `attr`, `on` listener, `attach`, or a two-way `bind`. */
     function dynamicAttr(
@@ -498,13 +539,21 @@ export function generateBuild(
         const pending = node.blocking
             ? []
             : node.children.filter((child) => child.kind !== 'branch')
+        /* The resolved value is reactive: a re-settle updates it in place rather than
+           rebuilding the branch (see awaitBlock). The branch reads it as a `.value` cell. */
         const thenThunk = node.blocking
             ? branchThunk(
                   node.children.filter((child) => child.kind !== 'branch'),
                   node.as ?? '_value',
                   finallyChildren,
+                  true,
+              )
+            : branchThunk(
+                  thenBranch?.children ?? [],
+                  thenBranch?.as ?? '_value',
+                  finallyChildren,
+                  true,
               )
-            : branchThunk(thenBranch?.children ?? [], thenBranch?.as ?? '_value', finallyChildren)
         /* Neither catch nor finally → pass `undefined` so awaitBlock re-throws the
            rejection (surfacing it) instead of rendering an empty branch. A finally-only
            block keeps a catch thunk that renders just finally. */
@@ -536,18 +585,29 @@ export function generateBuild(
         children: TemplateNode[],
         valueParam?: string,
         finallyChildren: TemplateNode[] = [],
+        reactiveValue = false,
     ): string {
         const parentParam = nextVar('p')
-        const head =
-            valueParam === undefined ? `(${parentParam})` : `(${parentParam}, ${valueParam})`
-        const body = withNestedScripts(children, () => generateChildren(children, parentParam))
+        /* A reactive value (an `await` `then`) arrives as a `.value` cell the runtime can set
+           in place, so the branch re-runs in place on a re-settle instead of being rebuilt. */
+        const binding =
+            reactiveValue && valueParam !== undefined ? reactiveBinding(valueParam) : undefined
+        const param = binding?.param ?? valueParam
+        const prefix = binding?.prefix ?? ''
+        const localNames = binding?.localNames ?? []
+        const head = param === undefined ? `(${parentParam})` : `(${parentParam}, ${param})`
+        const body = withNestedScripts(children, () =>
+            localNames.length === 0
+                ? generateChildren(children, parentParam)
+                : withLocalDerived(localNames, () => generateChildren(children, parentParam)),
+        )
         const finallyBody =
             finallyChildren.length > 0
                 ? withNestedScripts(finallyChildren, () =>
                       generateChildren(finallyChildren, parentParam),
                   )
                 : ''
-        return `${head} => {\n${body}${finallyBody}}`
+        return `${head} => {\n${prefix}${body}${finallyBody}}`
     }
 
     /* True when a branch has content worth a render thunk — vs an absent/empty branch
@@ -626,13 +686,30 @@ export function generateBuild(
         before: string,
     ): string {
         const rowParam = nextVar('p')
+        /* The item is a reactive `.value` cell so a re-key with a changed value updates the row
+           in place (no rebuild). `keyOf` receives the RAW item; the key expression is lowered
+           with the author name plain — derive it BEFORE the row body puts that name in the
+           deref scope. With no explicit `key`, default the key to the item's own identity: a
+           plain `as` returns its name; a destructuring `as` binds a fresh param and returns
+           THAT, not the pattern re-wrapped (`[i,crumb]` → `[i,crumb]` would allocate a fresh
+           array per reconcile, so keys never match and every row rebuilds). An explicit `key`
+           destructures the item via `node.as` to read its leaves. */
+        const rawItemParam = isPlainIdentifier(node.as) ? node.as : nextVar('k')
+        const keyParam = node.key === undefined ? rawItemParam : node.as
+        const keyExpression = node.key === undefined ? rawItemParam : lowerExpression(node.key)
+        const binding = reactiveBinding(node.as)
+        /* `index="i"` binds the row's position as a third reactive cell param (the runtime
+           always passes it). It is a plain identifier — read as `i.value` — so it enters the
+           body's deref scope alongside the item's leaf names; an unnamed param when absent. */
+        const indexParam = node.index === undefined ? '' : `, ${node.index}`
+        const bodyLocalNames =
+            node.index === undefined ? binding.localNames : [...binding.localNames, node.index]
         /* The row body builds its children (a `<script>` declares per-row local signals,
            emitted in document order) into the row parent. A `<template catch>` child is
            consumed by the async-each, not the row — `generateChildren` skips it. */
         const rowBody = withNestedScripts(node.children, () =>
-            generateChildren(node.children, rowParam),
+            withLocalDerived(bodyLocalNames, () => generateChildren(node.children, rowParam)),
         )
-        const keyExpression = node.key === undefined ? node.as : lowerExpression(node.key)
         /* `await` → the AsyncIterable runtime, drained row-by-row on the client, with an
            optional `<template catch>` branch rendered (after the streamed rows) when the
            iterator rejects. Absent → `undefined`, so the rejection surfaces instead. */
@@ -643,7 +720,7 @@ export function generateBuild(
             : ''
         return (
             `${fn}(${parentVar}, () => (${lowerExpression(node.items)}), ` +
-            `(${node.as}) => (${keyExpression}), (${rowParam}, ${node.as}) => {\n${rowBody}}${catchArg}, ${before});\n`
+            `(${keyParam}) => (${keyExpression}), (${rowParam}, ${binding.param}${indexParam}) => {\n${binding.prefix}${rowBody}}${catchArg}, ${before});\n`
         )
     }
 

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

@@ -269,7 +269,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/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/dom/awaitBlock.ts

@@ -6,6 +6,8 @@ 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 { discardBoundary } from './discardBoundary.ts'
 import { enterNamespace } from './enterNamespace.ts'
 
@@ -52,6 +54,15 @@ export function awaitBlock(
     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) {
@@ -81,33 +92,61 @@ export function awaitBlock(
         active = { nodes, dispose }
     }
 
+    /* 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))
             },
         )
     }
@@ -176,11 +215,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 +237,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/each.ts

@@ -4,6 +4,8 @@ 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 type { State } from '../runtime/types/State.ts'
+import { state } from '../state.ts'
 import { enterNamespace } from './enterNamespace.ts'
 import { moveRange } from './moveRange.ts'
 import { removeRange } from './removeRange.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,15 +55,20 @@ 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(']')
@@ -66,10 +77,10 @@ export function each<T>(
         /* 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))),
+            enterNamespace(parent, () => scope(() => render(pending, cell as State<T>, indexCell))),
         )
         pending.appendChild(end)
-        return { start, end, dispose, pending }
+        return { start, end, dispose, cell, indexCell, pending }
     }
 
     /* Place a row so its range ends just before `cursor`: insert a fresh row's
@@ -94,8 +105,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 +158,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

@@ -4,6 +4,8 @@ import { OWNER } from '../runtime/OWNER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
 import { scopeGroup } from '../runtime/scopeGroup.ts'
+import type { State } from '../runtime/types/State.ts'
+import { state } from '../state.ts'
 import { enterNamespace } from './enterNamespace.ts'
 import { removeRange } from './removeRange.ts'
 import type { EachRow } from './types/EachRow.ts'
@@ -27,7 +29,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,8 +49,11 @@ 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 => {
+    /* Build a content range and insert it just before the anchor (arrival order). A bare
+       range (no item cell) — the data-row site adds the cell, the error branch needs none. */
+    const insertRange = (
+        build: (into: Node) => void,
+    ): { start: Node; end: Node; dispose: () => void } => {
         const start = document.createComment('[')
         const end = document.createComment(']')
         const fragment = document.createDocumentFragment()
@@ -62,7 +70,7 @@ export function eachAsync<T>(
     }
 
     /* 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 +90,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 +105,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/types/EachRow.ts

@@ -1,10 +1,17 @@
+import type { State } from '../../runtime/types/State.ts'
+
 /* A live row in a keyed list: a content RANGE bounded by two comment markers (so a
    row holds any content, not just one node), plus the disposer for the bindings
-   created in its ownership scope. `pending` holds a freshly built row's nodes in a
-   fragment until first placement inserts them. */
+   created in its ownership scope. `cell` holds the row's item as a reactive value, so a
+   re-key with a changed value (same key, new object) updates the row in place instead of
+   leaving it frozen. `indexCell` holds the row's reactive position, so a reorder repaints
+   its `index` binding in place without a rebuild. `pending` holds a freshly built row's
+   nodes in a fragment until first placement inserts them. */
 export type EachRow = {
     start: Node
     end: Node
     dispose: () => void
+    cell: State<unknown>
+    indexCell: State<number>
     pending?: DocumentFragment
 }