@abide/abide 0.48.0 → 0.50.0

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

@@ -1,9 +1,152 @@
 import ts from 'typescript'
+import { assignmentTargetNames } from './assignmentTargetNames.ts'
 import { type ReactiveImportBindings, reactiveImportBindings } from './resolveReactiveExport.ts'
 import { signalCallee } from './signalCallee.ts'
+import type { InterpolationKind } from './types/InterpolationKind.ts'
+import type { SeedTypeClassifier } from './types/SeedTypeClassifier.ts'
+
+/* The routing decision for a no-marker `computed(seed)`: `true` routes to the eager
+   `trackedComputed` stream cell (read via `$$readCell`, the `cellReadNames` bucket), `false`
+   to the lazy `derive` doc slot (read as `name()`, the `computedNames` bucket). Shared by the
+   name-collection pass and the lowering so both land the binding in the identical bucket. */
+type EagerStreamPredicate = (declaration: ts.VariableDeclaration) => boolean
 
 const factory = ts.factory
 
+/* True when `node` holds an `await` that runs at the seed's own top level — one NOT nested
+   inside a further function. The walk stops at every nested function boundary, so an
+   `await` in an inner callback (`items.map(async (x) => await f(x))`) does not count: only
+   a top-level `await` marks the seed itself as an async thunk the async-cell path unwraps. */
+function hasTopLevelAwait(node: ts.Node): boolean {
+    let found = false
+    const visit = (child: ts.Node): void => {
+        if (found) {
+            return
+        }
+        /* A nested function is its own await scope — don't descend into it. */
+        if (
+            ts.isFunctionDeclaration(child) ||
+            ts.isFunctionExpression(child) ||
+            ts.isArrowFunction(child)
+        ) {
+            return
+        }
+        if (ts.isAwaitExpression(child)) {
+            found = true
+            return
+        }
+        ts.forEachChild(child, visit)
+    }
+    visit(node)
+    return found
+}
+
+/* Normalises a `computed`/`linked` argument into a seed THUNK: a literal `() => …` /
+   `function` argument passes through unchanged (the author already wrote the thunk), any
+   other expression is wrapped as `() => arg`. The wrapper arrow is made ASYNC when the
+   expression contains a top-level `await` (`computed(await load())` → `async () => await
+   load()`), which is exactly the marker the runtime primitive uses to route to an async cell. */
+function wrapSeed(argument: ts.Expression): ts.Expression {
+    if (ts.isArrowFunction(argument) || ts.isFunctionExpression(argument)) {
+        return argument
+    }
+    const modifiers = hasTopLevelAwait(argument)
+        ? [factory.createModifier(ts.SyntaxKind.AsyncKeyword)]
+        : undefined
+    return factory.createArrowFunction(
+        modifiers,
+        undefined,
+        [],
+        undefined,
+        factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+        argument,
+    )
+}
+
+/* True for an async seed thunk — an arrow/function carrying the `async` modifier, whether
+   from `wrapSeed`'s `await` lowering or a passthrough `async () => …` literal the author
+   wrote. The routing signal: an async seed becomes an async cell (read via `$$readCell`),
+   a sync seed stays the lazy `derive` computed. */
+function isAsyncSeed(node: ts.Expression): boolean {
+    if (!ts.isArrowFunction(node) && !ts.isFunctionExpression(node)) {
+        return false
+    }
+    const modifiers = ts.getModifiers(node)
+    return modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword) ?? false
+}
+
+/* The seed argument of a `computed`/`linked` declaration (undefined for the arg-less
+   `computed()` edge). Reused by both the name-collection pass and the lowering. */
+function seedArgument(declaration: ts.VariableDeclaration): ts.Expression | undefined {
+    return (declaration.initializer as ts.CallExpression).arguments[0]
+}
+
+/* True when a `computed(...)` declaration's wrapped seed is async — its await-lowered or
+   passthrough-async thunk routes to `scope().computed(...)` (an async cell) instead of the
+   lazy `scope().derive(...)`. The one predicate the collection pass and the lowering share. */
+function isAsyncComputed(declaration: ts.VariableDeclaration): boolean {
+    const argument = seedArgument(declaration)
+    if (argument === undefined) {
+        return false
+    }
+    return isAsyncSeed(wrapSeed(argument))
+}
+
+/* True for a SYNC `computed(...)` seed that is a bare CALL or IDENTIFIER — `computed(getStream())`
+   / `computed(ref)`, the shape that may produce a stream/promise source. These route to the
+   eager `scope().trackedComputed(...)` (which probes its seed and auto-tracks a
+   `NamedAsyncIterable`), read via `$$readCell`; an arithmetic/member/literal seed stays on the
+   lazy `derive` path (read as `name()`). Excludes the async case (`isAsyncComputed` owns it) and
+   a literal `() => …` thunk (a direct thunk the author wrote — left lazy on `derive`). */
+function isBareCallComputed(declaration: ts.VariableDeclaration): boolean {
+    const argument = seedArgument(declaration)
+    if (argument === undefined || isAsyncSeed(wrapSeed(argument))) {
+        return false
+    }
+    return ts.isCallExpression(argument) || ts.isIdentifier(argument)
+}
+
+/* Emits a compile WARNING (best-effort, never fatal) when a signal read appears AFTER the
+   first top-level `await` in an async seed — a value read there is no longer tracked, so the
+   cell won't reseed when it changes. Detection only: reads before the await (or with no
+   await) are fine. */
+function warnPostAwaitReads(seed: ts.Expression, signalNames: ReadonlySet<string>): void {
+    if (signalNames.size === 0) {
+        return
+    }
+    /* Walk the seed's BODY — the arrow/function itself is the seed, not a nested scope, so
+       descend into it; the guard below then skips any FURTHER nested function. */
+    const body = ts.isArrowFunction(seed) || ts.isFunctionExpression(seed) ? seed.body : seed
+    let awaited = false
+    const flagged = new Set<string>()
+    const visit = (child: ts.Node): void => {
+        /* Nested functions have their own tracking; the await that matters is at the seed's
+           own top level, so don't descend into them (mirrors `hasTopLevelAwait`). */
+        if (
+            ts.isFunctionDeclaration(child) ||
+            ts.isFunctionExpression(child) ||
+            ts.isArrowFunction(child)
+        ) {
+            return
+        }
+        if (ts.isAwaitExpression(child)) {
+            awaited = true
+            ts.forEachChild(child, visit)
+            return
+        }
+        if (awaited && ts.isIdentifier(child) && signalNames.has(child.text)) {
+            flagged.add(child.text)
+        }
+        ts.forEachChild(child, visit)
+    }
+    visit(body)
+    for (const name of flagged) {
+        console.warn(
+            `[abide] \`${name}\` is read after an \`await\` in an async computed/linked seed — reads after the first await are not tracked, so the cell will not reseed when \`${name}\` changes. Read it before the await (capture it into a local) to keep it tracked.`,
+        )
+    }
+}
+
 /* 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
@@ -44,13 +187,48 @@ between passes. Plain `state` becomes `model.x` access that `lowerDocAccess` low
 patches/reads. No reactive declarations → an identity transformer (the explicit
 `const model = doc(...)` form still works).
 */
-export function desugarSignals(source: ts.SourceFile): {
+export function desugarSignals(
+    source: ts.SourceFile,
+    /* Synthetic `const __cN = computed(...)` cells `analyzeComponent` injected for asyncIterable
+       interpolations (ADR-0019 Stage D). Their `computed` callee is UNIMPORTED, so import
+       resolution (`signalCallee`) can't recognize them — instead a declaration whose name is in
+       this set is treated as a bare-call computed slot: routed to an eager `trackedComputed`
+       stream cell and read via `$$readCell`, exactly as an explicit `state.computed(getStream())`
+       would be. Gated on the exact injected name (never a naming heuristic), so it can never
+       reclassify author code — an author's own `computed(...)` still needs its import. */
+    injectedCellNames: ReadonlySet<string> = new Set(),
+    /* The subset of `injectedCellNames` whose seed the author wrote `await` on (ADR-0032): a
+       BLOCKING peek-cell (`scope().trackedComputed(async …, false)` — an `AsyncComputed` that
+       joins the SSR barrier), vs a streaming one (`trackedComputed(async …, true)` — ships
+       pending, resolves on the client). Names not in this set are streaming. */
+    blockingCellNames: ReadonlySet<string> = new Set(),
+    /* Names the TEMPLATE writes (assigned in an event expression, or forwarded as a `bind:`
+       target) — see `writtenTemplateNames`. Unioned with the script's own write scan; a `props()`
+       binding whose name lands in the union is a WRITABLE prop (a `.value` cell via `bindableProp`)
+       rather than a read-only derive, so a two-way `bind:prop` on the parent can flow back. */
+    templateWrittenNames: ReadonlySet<string> = new Set(),
+    /* Type-directed seed classifier (ADR-0023): resolves a no-marker `computed(seed)`'s
+       async-ness from the seed's checker type via the warm shadow program. Absent (no warm
+       program, or any call site outside the shadow-warmed path) ⇒ every seed classifies
+       `undefined` ⇒ fail-open to the `isBareCallComputed` syntax heuristic — exactly today's
+       routing. The `await`-marker path (`isAsyncComputed`) is decided first and never consults it. */
+    seedClassify?: SeedTypeClassifier,
+    /* Absolute `.abide` source offset where this script's (trimmed) body begins — the base that
+       relocates a seed node's body-relative `getStart()` back to an ORIGINAL source location the
+       shadow's source→shadow `mappings` resolve. Unused when `seedClassify` is absent. */
+    scriptBase = 0,
+): {
     transformer: ts.TransformerFactory<ts.SourceFile>
     stateNames: Set<string>
     derivedNames: Set<string>
     computedNames: Set<string>
+    cellReadNames: Set<string>
 } {
     assertNoRemovedReaders(source)
+    /* The full set of names written anywhere (this script + the template). A prop in this set
+       is upgraded to a writable cell; a prop only read stays a cheap read-only derive. */
+    const writtenNames = new Set<string>(templateWrittenNames)
+    assignmentTargetNames(source, writtenNames)
     /* 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. */
@@ -58,9 +236,47 @@ export function desugarSignals(source: ts.SourceFile): {
     const stateNames = new Set<string>()
     const derivedNames = new Set<string>()
     const computedNames = new Set<string>()
+    /* Names read through `$$readCell(name)`: every `linked` (a plain `State` or, when its seed
+       tracks an async source, an `AsyncState`) and every async `computed` (an `AsyncComputed`).
+       One read shape covers both — `$$readCell` peeks an async cell and reads `.value` off a
+       sync one — so `linked(getStream())` auto-tracks with no read-site branching. */
+    const cellReadNames = new Set<string>()
     /* A `props()` destructure must be lowered even when it declares no reactive binding
        (a rest-only `const { ...rest } = props()`), so track its presence on its own. */
     let hasPropsDestructure = false
+    /* Resolves a computed seed's async-ness through the warm shadow classifier (ADR-0023):
+       maps the seed's absolute source location to its checker-type kind. `undefined` when no
+       classifier is threaded OR on any resolution failure (a throw / an unmapped seed), so the
+       caller degrades to `isBareCallComputed` — never mistakes a failure for a `sync` type. */
+    const seedKind = (seed: ts.Expression): InterpolationKind | undefined => {
+        if (seedClassify === undefined) {
+            return undefined
+        }
+        try {
+            const start = seed.getStart(source)
+            return seedClassify(scriptBase + start, source.text.slice(start, seed.getEnd()))
+        } catch {
+            return undefined
+        }
+    }
+    /* The single routing authority for a no-marker `computed(seed)` — shared by the
+       name-collection pass below and `computedStatements` so both land the binding in the same
+       read-name bucket (a divergence would lower a reference to the wrong read form). Type-
+       directed when the seed classifier resolves the seed (`asyncIterable` → the eager stream
+       cell; `promise`/`sync` → the lazy `derive` slot), fail-open to today's `isBareCallComputed`
+       syntax heuristic otherwise. The `await`-marker seed (`isAsyncComputed`) is decided first by
+       each caller and excluded here (its wrapped thunk is async → returns false). */
+    const isEagerStreamComputed: EagerStreamPredicate = (declaration) => {
+        const argument = seedArgument(declaration)
+        if (argument === undefined || isAsyncSeed(wrapSeed(argument))) {
+            return false
+        }
+        const kind = seedKind(argument)
+        if (kind !== undefined) {
+            return kind === 'asyncIterable'
+        }
+        return isBareCallComputed(declaration)
+    }
     for (const statement of source.statements) {
         if (!ts.isVariableStatement(statement)) {
             continue
@@ -78,25 +294,48 @@ export function desugarSignals(source: ts.SourceFile): {
                 }
                 hasPropsDestructure = true
                 for (const binding of propsDestructure(declaration).bindings) {
-                    computedNames.add(binding.local)
+                    /* A prop the component writes/forwards becomes a `.value` cell (`bindableProp`,
+                       read/written like `state(x, transform)` → `derivedNames`); one only read stays
+                       a read-only derive read as `name()` (`computedNames`). */
+                    if (writtenNames.has(binding.local)) {
+                        derivedNames.add(binding.local)
+                    } else {
+                        computedNames.add(binding.local)
+                    }
                 }
                 continue
             }
             if (!ts.isIdentifier(declaration.name)) {
                 continue
             }
+            if (injectedCellNames.has(declaration.name.text)) {
+                /* Injected asyncIterable-interpolation cell (`const __cN = computed(expr)`): an
+                   eager `trackedComputed` stream cell, read via `$$readCell` — recognized by its
+                   injected name since `computed` is unimported here. */
+                cellReadNames.add(declaration.name.text)
+                continue
+            }
             if (isPlainStateSlot(declaration, bindings)) {
                 /* Plain `state(initial)` → a serializable `model` doc slot. */
                 stateNames.add(declaration.name.text)
             } 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 === '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). */
+                /* `computed(compute)` → either a lazy `scope().derive` doc slot referenced as
+                   `name()` (a sync/promise seed), or an eager cell read via `$$readCell(name)`
+                   when the wrapped seed is async (an `await`-lowered / passthrough-`async` thunk)
+                   or its seed type resolves to a stream (`isEagerStreamComputed`, ADR-0023). */
+                if (isAsyncComputed(declaration) || isEagerStreamComputed(declaration)) {
+                    cellReadNames.add(declaration.name.text)
+                } else {
+                    computedNames.add(declaration.name.text)
+                }
+            } else if (callee === 'linked') {
+                /* `linked` → a cell read via `$$readCell(name)`: a plain `State` when the seed
+                   is synchronous, an `AsyncState` when it tracks a promise/stream — one read
+                   shape auto-tracks whichever source the runtime primitive resolved to. */
+                cellReadNames.add(declaration.name.text)
+            } else if (callee === 'state') {
+                /* `state(initial, transform)` → a `.value` cell (its write-coercion transform
+                   forces a local store); referenced as `name.value`, unchanged. */
                 derivedNames.add(declaration.name.text)
             }
         }
@@ -106,6 +345,7 @@ export function desugarSignals(source: ts.SourceFile): {
         stateNames.size > 0 ||
         derivedNames.size > 0 ||
         computedNames.size > 0 ||
+        cellReadNames.size > 0 ||
         hasPropsDestructure
 
     const transformer: ts.TransformerFactory<ts.SourceFile> = () => (root) => {
@@ -123,13 +363,31 @@ export function desugarSignals(source: ts.SourceFile): {
                 ),
             )
         }
+        /* Every component signal name — the read set the post-`await` tracking lint checks
+           an async seed's body against. */
+        const signalNames = new Set<string>([
+            ...stateNames,
+            ...derivedNames,
+            ...computedNames,
+            ...cellReadNames,
+        ])
         for (const statement of root.statements) {
-            statements.push(...loweredStatement(statement, bindings))
+            statements.push(
+                ...loweredStatement(
+                    statement,
+                    bindings,
+                    signalNames,
+                    injectedCellNames,
+                    blockingCellNames,
+                    writtenNames,
+                    isEagerStreamComputed,
+                ),
+            )
         }
         return factory.updateSourceFile(root, statements)
     }
 
-    return { transformer, stateNames, derivedNames, computedNames }
+    return { transformer, stateNames, derivedNames, computedNames, cellReadNames }
 }
 
 /* The lowered form of a top-level statement: state slots → `model.x = init`
@@ -139,16 +397,69 @@ export function desugarSignals(source: ts.SourceFile): {
 function loweredStatement(
     statement: ts.Statement,
     bindings: ReactiveImportBindings,
+    signalNames: ReadonlySet<string>,
+    injectedCellNames: ReadonlySet<string>,
+    blockingCellNames: ReadonlySet<string>,
+    writtenNames: ReadonlySet<string>,
+    isEagerStreamComputed: EagerStreamPredicate,
 ): ts.Statement[] {
     rejectMixedDeclaration(statement, bindings)
     return (
+        injectedComputedStatements(statement, injectedCellNames, blockingCellNames) ??
         stateAssignmentStatements(statement, bindings) ??
-        computedStatements(statement, bindings) ??
-        propsStatements(statement, bindings) ??
-        cellStatements(statement, bindings) ?? [statement]
+        computedStatements(statement, bindings, signalNames, isEagerStreamComputed) ??
+        propsStatements(statement, bindings, writtenNames) ??
+        cellStatements(statement, bindings, signalNames) ?? [statement]
     )
 }
 
+/* Lowers a synthetic `const __vN = computed(<seed>)` (an async (sub)expression peek-cell
+   `analyzeComponent` injected, ADR-0032) to a `scope().trackedComputed(...)` cell read via
+   `$$readCell`. Two shapes, by the seed:
+     - a PROMISE seed (`computed(await X)` → an async `() => await X` thunk) → `trackedComputed(
+       thunk, <streaming>)`, where `streaming = !blockingCellNames.has(name)`: a blocking cell
+       (author `await`) joins the SSR barrier and resolves inline; a streaming one ships pending.
+     - an `AsyncIterable` seed (`computed(getStream())` → a bare `() => getStream()` thunk) →
+       `trackedComputed(thunk)`, byte-identical to an explicit `state.computed(getStream())`.
+   Recognized by the injected name (`computed` is unimported here); returns undefined for any
+   statement that is not one of these injected cells (each is its own single-declaration statement). */
+function injectedComputedStatements(
+    statement: ts.Statement,
+    injectedCellNames: ReadonlySet<string>,
+    blockingCellNames: ReadonlySet<string>,
+): 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) || !injectedCellNames.has(declaration.name.text)) {
+            return undefined
+        }
+        const name = declaration.name.text
+        const argument = seedArgument(declaration)
+        const wrapped =
+            argument === undefined
+                ? factory.createArrowFunction(
+                      undefined,
+                      undefined,
+                      [],
+                      undefined,
+                      factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+                      factory.createIdentifier('undefined'),
+                  )
+                : wrapSeed(argument)
+        /* A promise seed (async thunk) unwraps to the resolved value and carries the SSR tier flag;
+           a stream seed (bare thunk) probes to a frame cell and needs no flag (a stream never joins
+           the barrier), so it stays a single-arg call to byte-match the explicit form. */
+        const args = isAsyncSeed(wrapped)
+            ? [wrapped, blockingCellNames.has(name) ? factory.createFalse() : factory.createTrue()]
+            : [wrapped]
+        statements.push(constDeclaration(name, scopeMethodCall('trackedComputed', args)))
+    }
+    return statements
+}
+
 /* 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-
@@ -243,6 +554,7 @@ function isComputedSlot(
 function cellStatements(
     statement: ts.Statement,
     bindings: ReactiveImportBindings,
+    signalNames: ReadonlySet<string>,
 ): ts.Statement[] | undefined {
     if (!ts.isVariableStatement(statement)) {
         return undefined
@@ -258,7 +570,23 @@ function cellStatements(
             return undefined
         }
         const args = (declaration.initializer as ts.CallExpression).arguments
-        statements.push(constDeclaration(declaration.name.text, scopeMethodCall(callee, args)))
+        /* `linked` wraps its seed argument (a bare value/`await`/stream expression becomes a
+           thunk, a literal `() => …` passes through) so the runtime primitive can route it to
+           an async cell; `state` is a value-taker — its args pass verbatim, never wrapped. */
+        if (callee === 'linked' && args[0] !== undefined) {
+            const wrapped = wrapSeed(args[0])
+            if (isAsyncSeed(wrapped)) {
+                warnPostAwaitReads(wrapped, signalNames)
+            }
+            statements.push(
+                constDeclaration(
+                    declaration.name.text,
+                    scopeMethodCall('linked', [wrapped, ...args.slice(1)]),
+                ),
+            )
+        } else {
+            statements.push(constDeclaration(declaration.name.text, scopeMethodCall(callee, args)))
+        }
     }
     return statements
 }
@@ -268,6 +596,8 @@ function cellStatements(
 function computedStatements(
     statement: ts.Statement,
     bindings: ReactiveImportBindings,
+    signalNames: ReadonlySet<string>,
+    isEagerStreamComputed: EagerStreamPredicate,
 ): ts.Statement[] | undefined {
     if (!ts.isVariableStatement(statement)) {
         return undefined
@@ -282,22 +612,40 @@ function computedStatements(
             return undefined
         }
         const name = declaration.name.text
-        const compute =
-            (declaration.initializer as ts.CallExpression).arguments[0] ??
-            factory.createArrowFunction(
-                undefined,
-                undefined,
-                [],
-                undefined,
-                factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
-                factory.createIdentifier('undefined'),
+        const argument = seedArgument(declaration)
+        /* The seed thunk: a wrapped argument (bare expr / `await` / literal thunk), or an arg-
+           less `computed()` degenerating to `() => undefined`. */
+        const wrapped =
+            argument === undefined
+                ? factory.createArrowFunction(
+                      undefined,
+                      undefined,
+                      [],
+                      undefined,
+                      factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+                      factory.createIdentifier('undefined'),
+                  )
+                : wrapSeed(argument)
+        if (isAsyncSeed(wrapped)) {
+            /* Async seed → the eager `computed` primitive (an `AsyncComputed` cell, read via
+               `$$readCell`); the runtime unwraps the promise. */
+            warnPostAwaitReads(wrapped, signalNames)
+            statements.push(constDeclaration(name, scopeMethodCall('computed', [wrapped])))
+        } else if (isEagerStreamComputed(declaration)) {
+            /* Stream seed → the eager `trackedComputed`, which probes the seed and auto-tracks a
+               stream (`AsyncComputed`) or falls back to a lazy computed; read via `$$readCell`.
+               Reached when the seed type resolves to `asyncIterable` (ADR-0023) or, fail-open with
+               no warm program, when it is a bare call/identifier (`isBareCallComputed`). */
+            statements.push(constDeclaration(name, scopeMethodCall('trackedComputed', [wrapped])))
+        } else {
+            /* Sync arithmetic/member/literal seed → the lazy `derive` doc slot, read as `name()`. */
+            statements.push(
+                constDeclaration(
+                    name,
+                    scopeMethodCall('derive', [factory.createStringLiteral(name), wrapped]),
+                ),
             )
-        statements.push(
-            constDeclaration(
-                name,
-                scopeMethodCall('derive', [factory.createStringLiteral(name), compute]),
-            ),
-        )
+        }
     }
     return statements
 }
@@ -374,14 +722,18 @@ function propsBindingKey(element: ts.BindingElement): string {
     throw new Error('abide: computed prop keys in `props()` destructuring are not supported')
 }
 
-/* If `statement` is a `const {…, ...rest} = props()` destructure, returns one reactive
-   computed per named binding — `scope().derive("name", () => $props["key"]?.() ?? default)`,
-   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. */
+/* If `statement` is a `const {…, ...rest} = props()` destructure, returns one binding per
+   named prop — plus a `const rest = restProps($props, [consumed])` for a rest binding;
+   otherwise undefined. A prop the component only READS is a read-only reactive computed
+   (`scope().derive("name", () => $props["key"]?.() ?? default)`, read as `name()`). A prop
+   it WRITES or forwards (in `writtenNames`) is a writable `.value` cell instead
+   (`$$bindableProp($props, "key", () => default)`, read/written as `name.value`), so a
+   two-way `bind:prop` on the parent flows back. The `?? default` / `fallback` thunk applies
+   the binding's `= default` when the prop is absent. */
 function propsStatements(
     statement: ts.Statement,
     bindings: ReactiveImportBindings,
+    writtenNames: ReadonlySet<string>,
 ): ts.Statement[] | undefined {
     if (!ts.isVariableStatement(statement)) {
         return undefined
@@ -396,6 +748,36 @@ function propsStatements(
         }
         const { bindings: propBindings, rest } = propsDestructure(declaration)
         for (const { local, key, initializer } of propBindings) {
+            /* A written/forwarded prop → `$$bindableProp($props, "key", () => default)`. */
+            if (writtenNames.has(local)) {
+                const args: ts.Expression[] = [
+                    factory.createIdentifier('$props'),
+                    factory.createStringLiteral(key),
+                ]
+                if (initializer !== undefined) {
+                    args.push(
+                        factory.createArrowFunction(
+                            undefined,
+                            undefined,
+                            [],
+                            undefined,
+                            factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+                            factory.createParenthesizedExpression(initializer),
+                        ),
+                    )
+                }
+                statements.push(
+                    constDeclaration(
+                        local,
+                        factory.createCallExpression(
+                            factory.createIdentifier('$$bindableProp'),
+                            undefined,
+                            args,
+                        ),
+                    ),
+                )
+                continue
+            }
             /* `$props["key"]?.()` — the parent thunk, optionally called. */
             const read = factory.createCallChain(
                 factory.createElementAccessExpression(
@@ -430,7 +812,7 @@ function propsStatements(
                 ),
             )
         }
-        /* The rest bag gathers every prop not named above (and not `$children`). */
+        /* The rest bag gathers every prop not named above (and not `children`). */
         if (rest !== undefined) {
             const consumed = propBindings.map((binding) => factory.createStringLiteral(binding.key))
             statements.push(

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

@@ -0,0 +1,19 @@
+import { referencedIdentifiers } from './referencedIdentifiers.ts'
+
+/* True when EVERY referenced identifier of `expression` is prefix-evaluable: none is a
+   template-local binder and none is an async-cell name (still pending at prefix time). Over-collects
+   identifiers, so any doubt fails closed. Shared by the await-flight classifier (hoistableAwaits) and
+   the child-render-flight classifier (hoistableChildRenders) — a hoisted await's promise and a
+   hoisted child's props must clear the same bar to start in the render prefix. */
+export function expressionIsPrefixEvaluable(
+    expression: string,
+    binders: ReadonlySet<string>,
+    cellReadNames: ReadonlySet<string>,
+): boolean {
+    for (const name of referencedIdentifiers(expression)) {
+        if (binders.has(name) || cellReadNames.has(name)) {
+            return false
+        }
+    }
+    return true
+}