@abide/abide 0.46.0 → 0.48.0

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

@@ -1,66 +1,23 @@
 import ts from 'typescript'
-import { REACTIVE_CALLEES } from './REACTIVE_CALLEES.ts'
+import { type ReactiveImportBindings, reactiveImportBindings } from './resolveReactiveExport.ts'
+import { signalCallee } from './signalCallee.ts'
 
 const factory = ts.factory
 
-/* The reactive primitives that must be reached through a scope. A bare call to one of
-   these is a compile error: a reactive primitive is owned by a scope and the surface must
-   show it (`scope().state(...)`), so a reader always sees the scope interaction. `effect`
-   is here too — a reaction is scope-owned (it tears down with the scope), so it joins the
-   one surface; unlike the cells it stays a runtime call (`scope().effect(...)` passes
-   through to the `effect` helper), not a doc slot. */
-const SCOPE_PRIMITIVES: ReadonlySet<string> = new Set(['state', 'linked', 'computed', 'effect'])
-
-/* The primitive names a top-level `const { state, computed } = scope()` destructure binds.
-   Such a name is scope-bound — its bare call below is the destructured method, not a stray
-   global — so it is exempt from the bare-primitive error. Only a destructure of a `scope()`
-   call counts (receiver-agnostic on the callee name, matching signalCallee); an aliased
-   binding (`{ state: s }`) is not recognised, so the canonical name must be kept. */
-function scopeDestructuredPrimitives(source: ts.SourceFile): Set<string> {
-    const bound = new Set<string>()
-    for (const statement of source.statements) {
-        if (!ts.isVariableStatement(statement)) {
-            continue
-        }
-        for (const declaration of statement.declarationList.declarations) {
-            if (
-                signalCallee(declaration) === 'scope' &&
-                ts.isObjectBindingPattern(declaration.name)
-            ) {
-                for (const element of declaration.name.elements) {
-                    if (
-                        element.propertyName === undefined &&
-                        ts.isIdentifier(element.name) &&
-                        SCOPE_PRIMITIVES.has(element.name.text)
-                    ) {
-                        bound.add(element.name.text)
-                    }
-                }
-            }
-        }
-    }
-    return bound
-}
-
-/* Throws on a bare scope primitive (`state(0)` instead of `scope().state(0)`) or on the
-   removed `prop(...)` reader — props are now read by destructuring `props()`. Walks all
-   calls, so a stray one nested in a function is caught too, not just top-level declarations.
-   A primitive destructured from `scope()` at the top is scope-bound and exempt. */
-function assertScopedPrimitives(source: ts.SourceFile): void {
-    const scopeBound = scopeDestructuredPrimitives(source)
+/* Throws on the removed `prop(...)` reader — props are now read by destructuring `props()`.
+   Walks all calls, so a stray one nested in a function is caught too. Bare reactive
+   primitives (`state(0)`) are the SURFACE now (recognised by import binding + lowered), so
+   they no longer throw — only the withdrawn `prop` reader does. */
+function assertNoRemovedReaders(source: ts.SourceFile): void {
     const visit = (node: ts.Node): void => {
-        if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
-            const name = node.expression.text
-            if (SCOPE_PRIMITIVES.has(name) && !scopeBound.has(name)) {
-                throw new Error(
-                    `abide: bare \`${name}(...)\` is not allowed — a reactive primitive lives on a scope. Use \`scope().${name}(...)\` (or a captured handle: \`const s = scope(); s.${name}(...)\`).`,
-                )
-            }
-            if (name === 'prop') {
-                throw new Error(
-                    'abide: `prop(...)` has been removed — read props by destructuring `props()`, e.g. `const { name } = props()` (with a default: `const { name = fallback } = props()`).',
-                )
-            }
+        if (
+            ts.isCallExpression(node) &&
+            ts.isIdentifier(node.expression) &&
+            node.expression.text === 'prop'
+        ) {
+            throw new Error(
+                'abide: `prop(...)` has been removed — read props by destructuring `props()`, e.g. `const { name } = props()` (with a default: `const { name = fallback } = props()`).',
+            )
         }
         ts.forEachChild(node, visit)
     }
@@ -93,7 +50,11 @@ export function desugarSignals(source: ts.SourceFile): {
     derivedNames: Set<string>
     computedNames: Set<string>
 } {
-    assertScopedPrimitives(source)
+    assertNoRemovedReaders(source)
+    /* The file's reactive import bindings — each local (alias-safe) mapped to its
+       canonical primitive. The single recognition authority: every callee below resolves
+       against these import bindings and nothing else. */
+    const bindings = reactiveImportBindings(source)
     const stateNames = new Set<string>()
     const derivedNames = new Set<string>()
     const computedNames = new Set<string>()
@@ -105,7 +66,7 @@ export function desugarSignals(source: ts.SourceFile): {
             continue
         }
         for (const declaration of statement.declarationList.declarations) {
-            const callee = signalCallee(declaration)
+            const callee = signalCallee(declaration, bindings)
             if (callee === 'props') {
                 /* `const {…, ...rest} = props()` — each named binding is a read-only computed
                    over the parent thunk (read as `name()`); a `...rest` binding stays a plain
@@ -124,15 +85,15 @@ export function desugarSignals(source: ts.SourceFile): {
             if (!ts.isIdentifier(declaration.name)) {
                 continue
             }
-            if (isPlainStateSlot(declaration)) {
+            if (isPlainStateSlot(declaration, bindings)) {
                 /* Plain `state(initial)` → a serializable `model` doc slot. */
                 stateNames.add(declaration.name.text)
-            } else if (isComputedSlot(declaration)) {
+            } else if (isComputedSlot(declaration, bindings)) {
                 /* Read-only `computed(compute)` → a computed `scope().derive` doc slot,
                    referenced as `name()` (its string-free reader): a function of other
                    paths, recomputed via the graph, never stored/serialized. */
                 computedNames.add(declaration.name.text)
-            } else if (callee !== undefined && REACTIVE_CALLEES.has(callee)) {
+            } else if (callee === 'linked' || callee === 'state') {
                 /* `.value` cells: `linked` and `state(initial, transform)` — they own
                    a local store, so they stay cells (`computed` is always the read-only
                    slot above; there is no writable-computed cell). */
@@ -163,7 +124,7 @@ export function desugarSignals(source: ts.SourceFile): {
             )
         }
         for (const statement of root.statements) {
-            statements.push(...loweredStatement(statement))
+            statements.push(...loweredStatement(statement, bindings))
         }
         return factory.updateSourceFile(root, statements)
     }
@@ -175,13 +136,65 @@ export function desugarSignals(source: ts.SourceFile): {
    assignments, computed → `scope().derive` consts, props → derive consts (+ restProps),
    cells → `scope().<callee>(...)` consts; anything else passes through verbatim. The
    per-statement dispatch mirrors the name-collection pass. */
-function loweredStatement(statement: ts.Statement): ts.Statement[] {
+function loweredStatement(
+    statement: ts.Statement,
+    bindings: ReactiveImportBindings,
+): ts.Statement[] {
+    rejectMixedDeclaration(statement, bindings)
     return (
-        stateAssignmentStatements(statement) ??
-        computedStatements(statement) ??
-        propsStatements(statement) ??
-        cellStatements(statement) ?? [statement]
+        stateAssignmentStatements(statement, bindings) ??
+        computedStatements(statement, bindings) ??
+        propsStatements(statement, bindings) ??
+        cellStatements(statement, bindings) ?? [statement]
+    )
+}
+
+/* Each lowering function above is all-or-nothing per VariableStatement: it returns
+   undefined the moment one declaration doesn't match its kind, so the whole statement
+   passes through verbatim. A statement mixing a reactive declaration with a differently-
+   lowered one (`let count = state(0), step = 5`) therefore ships literal — but the
+   collection pass already registered `count`, so references lower to `$$model.read("count")`
+   with no `$$model.count = 0` seed (silent undefined). Reject it with a legible error so
+   the author splits the declarations; a checker-free compiler must fail loud, not
+   mis-lower silently. Same-kind lists (`let a = state(0), b = state(1)`) are fine. */
+function rejectMixedDeclaration(statement: ts.Statement, bindings: ReactiveImportBindings): void {
+    if (!ts.isVariableStatement(statement)) {
+        return
+    }
+    const kinds = new Set(
+        statement.declarationList.declarations.map((declaration) =>
+            loweringKind(declaration, bindings),
+        ),
     )
+    /* Any two distinct kinds break: each lowering function bails on the non-matching
+       declaration, so the statement ships verbatim. A uniform list (size 1) is fine. */
+    if (kinds.size > 1) {
+        throw new Error(
+            'abide: declare each reactive signal in its own statement — a `let`/`const` that mixes a reactive declaration (state/linked/computed/props) with another kind cannot be lowered as one statement.',
+        )
+    }
+}
+
+/* The lowering bucket a single declaration falls into — mirrors the name-collection
+   dispatch so `rejectMixedDeclaration` can detect a statement spanning more than one. */
+function loweringKind(
+    declaration: ts.VariableDeclaration,
+    bindings: ReactiveImportBindings,
+): 'state' | 'computed' | 'props' | 'cell' | 'plain' {
+    const callee = signalCallee(declaration, bindings)
+    if (callee === 'props') {
+        return 'props'
+    }
+    if (isPlainStateSlot(declaration, bindings)) {
+        return 'state'
+    }
+    if (isComputedSlot(declaration, bindings)) {
+        return 'computed'
+    }
+    if (callee === 'linked' || callee === 'state') {
+        return 'cell'
+    }
+    return 'plain'
 }
 
 /* `const NAME = <init>` — a fresh const declaration reusing the original initializer node. */
@@ -210,10 +223,13 @@ function scopeMethodCall(method: string, args: readonly ts.Expression[]): ts.Cal
 /* True for a read-only computed slot — `computed(compute)` with no write-through
    `set`. The writable `computed(compute, set)` lens keeps a `.value` cell (handled by
    the caller). */
-function isComputedSlot(declaration: ts.VariableDeclaration): boolean {
+function isComputedSlot(
+    declaration: ts.VariableDeclaration,
+    bindings: ReactiveImportBindings,
+): boolean {
     const initializer = declaration.initializer
     return (
-        signalCallee(declaration) === 'computed' &&
+        signalCallee(declaration, bindings) === 'computed' &&
         initializer !== undefined &&
         ts.isCallExpression(initializer) &&
         initializer.arguments.length === 1
@@ -224,17 +240,20 @@ function isComputedSlot(declaration: ts.VariableDeclaration): boolean {
    routed onto the scope: `linked(seed)` → `const x = scope().linked(seed)`. The cell
    stays a standalone non-serializing cell (its refs stay `name.value`); the rewrite only
    removes the bare runtime import so the sole reactive surface is `scope()`. */
-function cellStatements(statement: ts.Statement): ts.Statement[] | undefined {
+function cellStatements(
+    statement: ts.Statement,
+    bindings: ReactiveImportBindings,
+): ts.Statement[] | undefined {
     if (!ts.isVariableStatement(statement)) {
         return undefined
     }
     const statements: ts.Statement[] = []
     for (const declaration of statement.declarationList.declarations) {
-        const callee = signalCallee(declaration)
+        const callee = signalCallee(declaration, bindings)
         if (
             !ts.isIdentifier(declaration.name) ||
             (callee !== 'linked' && callee !== 'state') ||
-            isPlainStateSlot(declaration)
+            isPlainStateSlot(declaration, bindings)
         ) {
             return undefined
         }
@@ -246,7 +265,10 @@ function cellStatements(statement: ts.Statement): ts.Statement[] | undefined {
 
 /* `let total = computed(compute)` → `const total = scope().derive("total", compute)`
    — a computed doc slot whose reader the references lower to `total()`. */
-function computedStatements(statement: ts.Statement): ts.Statement[] | undefined {
+function computedStatements(
+    statement: ts.Statement,
+    bindings: ReactiveImportBindings,
+): ts.Statement[] | undefined {
     if (!ts.isVariableStatement(statement)) {
         return undefined
     }
@@ -254,8 +276,8 @@ function computedStatements(statement: ts.Statement): ts.Statement[] | undefined
     for (const declaration of statement.declarationList.declarations) {
         if (
             !ts.isIdentifier(declaration.name) ||
-            signalCallee(declaration) !== 'computed' ||
-            !isComputedSlot(declaration)
+            signalCallee(declaration, bindings) !== 'computed' ||
+            !isComputedSlot(declaration, bindings)
         ) {
             return undefined
         }
@@ -294,29 +316,11 @@ function hasTransform(declaration: ts.VariableDeclaration): boolean {
 /* A plain `state(initial)` with no transform → a serializable `model` doc slot;
    every other reactive declaration is a `.value` cell. The one rule shared by the
    name-collection pass and the slot lowering. */
-function isPlainStateSlot(declaration: ts.VariableDeclaration): boolean {
-    return signalCallee(declaration) === 'state' && !hasTransform(declaration)
-}
-
-/* The callee name of a reactive declaration, else undefined. Recognises both the bare
-   form (`NAME = state(...)`) and the explicit scope form (`NAME = scope().state(...)` or
-   `NAME = c.state(...)` for any scope handle `c`) — receiver-agnostic: the METHOD name is
-   what marks the binding reactive. Since `scope()` is the ambient scope (one object per
-   level), the receiver is irrelevant to lowering — the slot keys off the binding name and
-   lands on the same `model`, so the explicit form lowers exactly like the bare one. */
-function signalCallee(declaration: ts.VariableDeclaration): string | undefined {
-    const initializer = declaration.initializer
-    if (initializer === undefined || !ts.isCallExpression(initializer)) {
-        return undefined
-    }
-    const callee = initializer.expression
-    if (ts.isIdentifier(callee)) {
-        return callee.text
-    }
-    if (ts.isPropertyAccessExpression(callee)) {
-        return callee.name.text
-    }
-    return undefined
+function isPlainStateSlot(
+    declaration: ts.VariableDeclaration,
+    bindings: ReactiveImportBindings,
+): boolean {
+    return signalCallee(declaration, bindings) === 'state' && !hasTransform(declaration)
 }
 
 /* One destructured prop: the local binding name, the parent prop key it reads, and
@@ -375,17 +379,23 @@ function propsBindingKey(element: ts.BindingElement): string {
    read as `name()` — plus a `const rest = restProps($props, [consumed])` for a rest
    binding; otherwise undefined. The `?? default` applies the binding's `= default`
    fallback when the prop is absent. */
-function propsStatements(statement: ts.Statement): ts.Statement[] | undefined {
+function propsStatements(
+    statement: ts.Statement,
+    bindings: ReactiveImportBindings,
+): ts.Statement[] | undefined {
     if (!ts.isVariableStatement(statement)) {
         return undefined
     }
     const statements: ts.Statement[] = []
     for (const declaration of statement.declarationList.declarations) {
-        if (signalCallee(declaration) !== 'props' || !ts.isObjectBindingPattern(declaration.name)) {
+        if (
+            signalCallee(declaration, bindings) !== 'props' ||
+            !ts.isObjectBindingPattern(declaration.name)
+        ) {
             return undefined
         }
-        const { bindings, rest } = propsDestructure(declaration)
-        for (const { local, key, initializer } of bindings) {
+        const { bindings: propBindings, rest } = propsDestructure(declaration)
+        for (const { local, key, initializer } of propBindings) {
             /* `$props["key"]?.()` — the parent thunk, optionally called. */
             const read = factory.createCallChain(
                 factory.createElementAccessExpression(
@@ -422,7 +432,7 @@ function propsStatements(statement: ts.Statement): ts.Statement[] | undefined {
         }
         /* The rest bag gathers every prop not named above (and not `$children`). */
         if (rest !== undefined) {
-            const consumed = bindings.map((binding) => factory.createStringLiteral(binding.key))
+            const consumed = propBindings.map((binding) => factory.createStringLiteral(binding.key))
             statements.push(
                 constDeclaration(
                     rest,
@@ -443,13 +453,16 @@ function propsStatements(statement: ts.Statement): ts.Statement[] | undefined {
 
 /* If `statement` declares `state(...)` bindings, returns `model.<name> = <init>`
    assignment statements (one per declaration); otherwise undefined. */
-function stateAssignmentStatements(statement: ts.Statement): ts.Statement[] | undefined {
+function stateAssignmentStatements(
+    statement: ts.Statement,
+    bindings: ReactiveImportBindings,
+): ts.Statement[] | undefined {
     if (!ts.isVariableStatement(statement)) {
         return undefined
     }
     const statements: ts.Statement[] = []
     for (const declaration of statement.declarationList.declarations) {
-        if (!ts.isIdentifier(declaration.name) || !isPlainStateSlot(declaration)) {
+        if (!ts.isIdentifier(declaration.name) || !isPlainStateSlot(declaration, bindings)) {
             /* Only a plain `state(initial)` becomes a slot; `state(initial, transform)`
                (and everything else) is a `.value` cell — pass it through so the
                runtime call (and its transform) survives. */

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

@@ -22,6 +22,7 @@ import { skeletonContext } from './skeletonContext.ts'
 import { snippetPlan } from './snippetPlan.ts'
 import { spreadExcludedNames } from './spreadExcludedNames.ts'
 import { staticAttr } from './staticAttr.ts'
+import { staticAttrValue } from './staticAttrValue.ts'
 import { staticTextPart } from './staticTextPart.ts'
 import { switchPlan } from './switchPlan.ts'
 import { tryPlan } from './tryPlan.ts'
@@ -43,7 +44,7 @@ attributes, reactive `attr`/`text` bindings, `on` listeners, keyed `each`, and
 conditional `when`. Every embedded expression is first rewritten from the signal
 surface (`count` → `model.count`) and then lowered to the doc patch/read API
 (cell-hoisting runs over the whole result afterwards). The output operates on
-`hostVar` and expects the `$$`-aliased dom bindings (`$$effect`, `$$each`, …)
+`hostVar` and expects the `$$`-aliased dom bindings (`$$watch`, `$$each`, …)
 and the component's `$$model` (emitted by `desugarSignals`) in scope — the body
 the component compiler wraps and hoists cells into.
 */
@@ -154,11 +155,11 @@ export function generateBuild(
         /* `class:<name>` — toggle the class by truthiness; surgical, no element re-render.
            Layers on top of any static `class="…"` in the skeleton (classList is additive). */
         if (attr.kind === 'class') {
-            return `$$effect(${namedThunk(`class_${attr.name}`, `${varName}.classList.toggle(${JSON.stringify(attr.name)}, !!(${lowerExpression(attr.code)}));`)});\n`
+            return `$$watch(${namedThunk(`class_${attr.name}`, `${varName}.classList.toggle(${JSON.stringify(attr.name)}, !!(${lowerExpression(attr.code)}));`)});\n`
         }
         /* `style:<property>` — write one inline style / custom property reactively. */
         if (attr.kind === 'style') {
-            return `$$effect(${namedThunk(`style_${attr.property}`, `${varName}.style.setProperty(${JSON.stringify(attr.property)}, String(${lowerExpression(attr.code)}));`)});\n`
+            return `$$watch(${namedThunk(`style_${attr.property}`, `${varName}.style.setProperty(${JSON.stringify(attr.property)}, String(${lowerExpression(attr.code)}));`)});\n`
         }
         if (attr.property === 'group') {
             /* Grouped two-way: radio binds the path to the single checked `value`;
@@ -171,24 +172,46 @@ export function generateBuild(
             const value = lowerExpression(valueCode)
             if (isRadio) {
                 return (
-                    `$$effect(${namedThunk('bind_group', `${varName}.checked = (${lowerExpression(attr.code)}) === (${value});`)});\n` +
+                    `$$watch(${namedThunk('bind_group', `${varName}.checked = (${lowerExpression(attr.code)}) === (${value});`)});\n` +
                     `$$on(${varName}, "change", () => { if (${varName}.checked) { ${lowerStatement(`${attr.code} = ${valueCode}`)} } });\n`
                 )
             }
             return (
-                `$$effect(${namedThunk('bind_group', `${varName}.checked = (${lowerExpression(attr.code)}).includes(${value});`)});\n` +
+                `$$watch(${namedThunk('bind_group', `${varName}.checked = (${lowerExpression(attr.code)}).includes(${value});`)});\n` +
                 `$$on(${varName}, "change", () => { const $groupValue = ${value}; if (${varName}.checked) { if (!(${lowerExpression(attr.code)}).includes($groupValue)) { ${lowerStatement(`${attr.code}.push($groupValue)`)} } } else { const $groupIndex = (${lowerExpression(attr.code)}).indexOf($groupValue); if ($groupIndex !== -1) { ${lowerStatement(`delete ${attr.code}[$groupIndex]`)} } } });\n`
             )
         }
+        /* `<select bind:value>` — options frequently mount after this binding runs (a
+           `{#for}` child, an async list) and the browser drops a `value` set naming a
+           not-yet-present option, so route to `bindSelectValue`: it re-applies on option
+           changes via a MutationObserver and switches single/array semantics on `multiple`
+           (`<select multiple>` binds an array of the selected option values). The read/write
+           are the same lvalue/accessor forms every bind uses; the helper decides how to
+           apply and collect them. */
+        if (attr.property === 'value' && node.tag === 'select') {
+            const multiple = staticAttrValue(node, 'multiple') !== undefined
+            return `$$bindSelectValue(${varName}, () => (${bindRead(attr.code)}), ($selectValue) => { ${bindWrite(attr.code, '$selectValue')} }, ${multiple});\n`
+        }
         /* Two-way: drive the property from the bind target, and write it back on the
            property's native event (`input` for most fields, but `toggle` for
            `<details open>`, `change` for checked/select). An lvalue target reads as
            itself and writes by assignment; an accessor object (`{ get, set }`) reads via
-           `.get()` and writes via `.set(v)` — see `bindRead`/`bindWrite`. */
+           `.get()` and writes via `.set(v)` — see `bindRead`/`bindWrite`. A numeric input
+           (`type="number"`/`"range"`) reports its edit as a string on `el.value`, which
+           would corrupt number-typed state; source the write-back from `valueAsNumber`
+           instead (empty field → `undefined`), gated on a statically-known type. */
         const event = bindListenEvent(attr.property, node.tag)
+        const staticType = staticAttrValue(node, 'type')
+        const isNumericInput =
+            attr.property === 'value' &&
+            node.tag === 'input' &&
+            (staticType === 'number' || staticType === 'range')
+        const writeSource = isNumericInput
+            ? `(${varName}.value === '' ? undefined : ${varName}.valueAsNumber)`
+            : `${varName}.${attr.property}`
         return (
-            `$$effect(${namedThunk(`bind_${attr.property}`, `${varName}.${attr.property} = ${bindRead(attr.code)};`)});\n` +
-            `$$on(${varName}, ${JSON.stringify(event)}, () => { ${bindWrite(attr.code, `${varName}.${attr.property}`)} });\n`
+            `$$watch(${namedThunk(`bind_${attr.property}`, `${varName}.${attr.property} = ${bindRead(attr.code)};`)});\n` +
+            `$$on(${varName}, ${JSON.stringify(event)}, () => { ${bindWrite(attr.code, writeSource)} });\n`
         )
     }
 
@@ -310,12 +333,12 @@ export function generateBuild(
                skeleton). */
             if (plan.merge.mergeClassBuild) {
                 binds.push(
-                    `$$effect(${namedThunk('class_merge', `${elVar}.setAttribute("class", [${plan.merge.classParts.join(', ')}].filter(Boolean).join(' '));`)});\n`,
+                    `$$watch(${namedThunk('class_merge', `${elVar}.setAttribute("class", [${plan.merge.classParts.join(', ')}].filter(Boolean).join(' '));`)});\n`,
                 )
             }
             if (plan.merge.mergeStyleBuild) {
                 binds.push(
-                    `$$effect(${namedThunk('style_merge', `${elVar}.setAttribute("style", [${plan.merge.styleParts.join(', ')}].filter(Boolean).join(';'));`)});\n`,
+                    `$$watch(${namedThunk('style_merge', `${elVar}.setAttribute("style", [${plan.merge.styleParts.join(', ')}].filter(Boolean).join(';'));`)});\n`,
                 )
             }
             for (const { attr, mergedBuild } of plan.attrs) {
@@ -558,11 +581,7 @@ export function generateBuild(
         parentVar: string,
         before: string,
     ): string {
-        /* `client:idle`/`client:visible` → the island trigger, the 6th mountChild arg. Omitted
-           (the common case) leaves the call byte-identical to before — eager hydration. */
-        const trigger =
-            node.clientTrigger !== undefined ? `, ${JSON.stringify(node.clientTrigger)}` : ''
-        return `$$mountChild(${parentVar}, ${node.name}, ${propsArg(node)}, ${before}, ${JSON.stringify(node.name)}${trigger});\n`
+        return `$$mountChild(${parentVar}, ${node.name}, ${propsArg(node)}, ${before}, ${JSON.stringify(node.name)});\n`
     }
 
     /* An await block: pending → resolved(value) / error branches. Each branch is a
@@ -719,7 +738,20 @@ export function generateBuild(
            destructures the item via `plan.as` to read its leaves. */
         const rawItemParam = isPlainIdentifier(plan.as) ? plan.as : nextVar('k')
         const keyParam = plan.key === undefined ? rawItemParam : plan.as
-        const keyExpression = plan.key === undefined ? rawItemParam : lowerExpression(plan.key)
+        /* The key callback binds the RAW item via `plan.as`, so lower the key expression with
+           the item's names shadowed as PLAIN locals — otherwise a `by item.id` whose `item`
+           collides with a component signal rewrites to `$$model.read("item/id")` (every row
+           keys off the same signal → keyed reconciliation degenerates). The plain kind (not
+           the row body's reactive `.value` kind) keeps it the bare param the callback binds. */
+        const keyExpression =
+            plan.key === undefined
+                ? rawItemParam
+                : withBindings(
+                      withShadow,
+                      [plan.bindings[0] as Binding],
+                      () => 'plain',
+                      () => lowerExpression(plan.key as string),
+                  )
         /* The item is the row's `reactive` binding (its `.value` cell + per-leaf reader prefix
            rendered by `reactiveBinding`); `index="i"` is a second reactive cell param, a plain
            identifier read as `i.value` (no prefix). The names of BOTH enter the deref scope via