@abide/abide 0.48.0 → 0.50.0

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

@@ -1,5 +1,8 @@
 import ts from 'typescript'
 import { ABIDE_PACKAGE_NAME } from '../../shared/ABIDE_PACKAGE_NAME.ts'
+import { attrLiftPosition } from './attrLiftPosition.ts'
+import { isWhitespaceText } from './isWhitespaceText.ts'
+import { type LiftPosition, liftAsyncSubExpressions } from './liftAsyncSubExpressions.ts'
 import { parseTemplate } from './parseTemplate.ts'
 import {
     NESTED_REACTIVE_BINDINGS,
@@ -8,7 +11,9 @@ import {
     resolveReactiveExport,
 } from './resolveReactiveExport.ts'
 import { signalCallee } from './signalCallee.ts'
+import { LEADING_SCRIPT } from './templateStartOffset.ts'
 import type { CompiledShadow, ShadowDiagnostic, ShadowMapping } from './types/CompiledShadow.ts'
+import type { InterpolationClassifier } from './types/InterpolationClassifier.ts'
 import type { TemplateNode } from './types/TemplateNode.ts'
 
 /*
@@ -22,8 +27,10 @@ OMITTED (see `shadowPreamble`) to avoid a duplicate identifier. Otherwise
 `state`/`linked`/`computed` are declared ambiently and `effect` is imported as a fallback
 for a bare/nested use the top-level rewrite doesn't project (unused when projected — fine,
 the shadow disables noUnusedLocals). `props` is the prop reader — destructured
-(`const { a = 1 } = props<Shape>()`); declared returning its type argument (default
-`Record<string, any>`) so each binding inherits its prop type and its `= default` narrows.
+(`const { a = 1 } = props<Shape>()`); a required import (`abide/ui/props`), so the shadow
+declares it only when imported, returning the file's contextual shape (route params or
+`Record<string, any>`) intersected with its own type argument — additive, so declared props
+like `children: Snippet` layer on top instead of re-spelling the route shape.
 */
 function shadowPreamble(importedReactives: ReadonlySet<string>): string {
     /* Omit the ambient fallback for a primitive the author imports — its own binding is
@@ -46,7 +53,6 @@ function shadowPreamble(importedReactives: ReadonlySet<string>): string {
         importedReactives.has('computed')
             ? undefined
             : 'declare function computed<T>(compute: () => T): { readonly value: T }',
-        'declare const children: (() => void) | undefined',
         /* `effect` is defined either way — the preamble import or the author's own import. */
         'void [effect, snippet, scope]',
     ]
@@ -68,23 +74,56 @@ The script's signal surface is rewritten to value types:
 Everything else (functions, plain consts, imports) is emitted verbatim, so
 expressions inside it (e.g. a computed's compute body) are checked and mapped too.
 */
-export function compileShadow(source: string, propsType = 'Record<string, any>'): CompiledShadow {
-    const builder = createBuilder()
-    const leadingScript = source.match(/^\s*<script[^>]*>([\s\S]*?)<\/script>/)
+export function compileShadow(
+    source: string,
+    propsType = 'Record<string, any>',
+    classify?: InterpolationClassifier,
+): CompiledShadow {
+    const builder = createBuilder(classify)
+    const leadingScript = source.match(LEADING_SCRIPT)
     const scriptBody = leadingScript?.[1] ?? ''
     /* Body starts just past the opening `<script …>`; template just past `</script>`. */
     const scriptStart = leadingScript ? source.indexOf('>', leadingScript.index) + 1 : 0
     const templateStart = leadingScript ? (leadingScript.index ?? 0) + leadingScript[0].length : 0
 
-    const { imports, types, scope, propsShapes, diagnostics, importedReactives } = analyzeScript(
-        scriptBody,
-        scriptStart,
-    )
+    const { imports, types, scope, propsShapes, diagnostics, importedReactives, propsLocalName } =
+        analyzeScript(scriptBody, scriptStart)
     builder.raw(shadowPreamble(importedReactives))
-    /* `props()` defaults to the file's type — a page/layout's route param shape, else
-       `Record<string, any>` — so `const { id } = props()` infers from the route. */
-    builder.raw(`declare function props<T = ${propsType}>(): T\n`)
+    /* The peek helpers the async-interpolation wrap targets (ADR-0032): `$$peek` unwraps a promise
+       sub-expression to its resolved value (`undefined` while pending) and `$$peekStream` reads an
+       async iterable's latest frame, so `getFoo()?.name`/`{#if getFoo()}` type-check against the
+       RESOLVED value the runtime peeks — not the raw `Promise`. Emitted only when a classifier is
+       present (the wrap is type-directed); their names carry the reserved `$$` prefix an author
+       binding can never take, so they cannot collide with user code. */
+    if (classify !== undefined) {
+        builder.raw('declare function $$peek<T>(v: T): Awaited<T> | undefined\n')
+        builder.raw(
+            'declare function $$peekStream<S>(v: S): (S extends AsyncIterable<infer F> ? F : unknown) | undefined\n',
+        )
+    }
+    /* `props` is a required import (`abide/ui/props`). The shadow owns its type so the
+       return is file-contextual — the route param shape (page/layout) or `Record<string,
+       any>` (component), intersected with the author's annotation `T` so declared props
+       (notably `children: Snippet`) are ADDITIVE and route params never need re-spelling.
+       Emitted only when imported: a missing import surfaces as "Cannot find name 'props'"
+       (or the author's local alias), so `abide check` flags it. Declared under the LOCAL
+       binding name (alias-safe, like `state`/`effect`) — a `props as p` import must get a
+       `p` declare, or `p()` reads as undefined once the import below is stripped. */
+    if (propsLocalName !== undefined) {
+        builder.raw(`declare function ${propsLocalName}<T = {}>(): (${propsType}) & T\n`)
+    }
+    const propsSpecifier = `${ABIDE_PACKAGE_NAME}/ui/props`
     for (const line of imports) {
+        /* The `props` import is replaced by the contextual `declare function` above;
+           emitting it too would be a duplicate-identifier error. Matched by EXACT specifier
+           (either quote style, not a loose suffix match) so an unrelated user module merely
+           named `.../ui/props` survives verbatim. */
+        if (
+            line.text.includes(`from '${propsSpecifier}'`) ||
+            line.text.includes(`from "${propsSpecifier}"`)
+        ) {
+            continue
+        }
         builder.flush(line)
     }
     /* Component-local `type`/`interface` declarations are hoisted to module scope —
@@ -123,6 +162,19 @@ export function compileShadow(source: string, propsType = 'Record<string, any>')
     /* Nested `<script>` blocks inline into the synchronous `build()` too, so a top-level
        await in one is the same build-breaker — flag it, mapped via the node's body offset. */
     collectNestedScriptAwaitDiagnostics(templateNodes, diagnostics)
+    /* Emit the DOM-typed attachment aliases only when an element `attach` uses them: they
+       reference `HTMLElementTagNameMap`/`Element`, so a template with no element attach never
+       forces DOM lib into its shadow. `__ElementFor` maps a tag to its element interface
+       (HTML-first; unknown/custom tags fall back to `Element`); `__Attachment` sources its
+       return type from the real `attach` runtime signature so it never drifts. */
+    if (hasElementAttach(templateNodes)) {
+        builder.raw(
+            'type __ElementFor<T extends string> = T extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[T] : T extends keyof SVGElementTagNameMap ? SVGElementTagNameMap[T] : T extends keyof MathMLElementTagNameMap ? MathMLElementTagNameMap[T] : Element;\n',
+        )
+        builder.raw(
+            `type __Attachment<E extends Element> = (node: E) => ReturnType<Parameters<typeof import('${ABIDE_PACKAGE_NAME}/ui/dom/attach').attach>[1]>;\n`,
+        )
+    }
     emitNodes(templateNodes, builder)
     builder.raw('}\n')
     return { ...builder.result(), diagnostics }
@@ -140,6 +192,12 @@ type Builder = {
     mapped: (text: string, sourceLoc: number | undefined) => void
     expr: (code: string, sourceLoc: number | undefined) => void
     stmt: (code: string, sourceLoc: number | undefined) => void
+    /* Like `expr`/`stmt` but for a template interpolation: async (sub)expressions are wrapped in a
+       peek helper (`$$peek`/`$$peekStream`) so their RESOLVED type composes (ADR-0032). Every source
+       span still maps 1:1 — the inserted wrapper chars are unmapped — so diagnostics land precisely.
+       With no classifier (or no async sub-expression) these are byte-identical to `expr`/`stmt`. */
+    asyncExpr: (code: string, sourceLoc: number | undefined, position: LiftPosition) => void
+    asyncStmt: (code: string, sourceLoc: number | undefined, position: LiftPosition) => void
     flush: (line: ScopeLine) => void
     /* A fresh shadow-local binding name (`__<base>_<n>`) — for synthesised bindings
        like an await's resolved value, kept distinct so nested blocks never collide. */
@@ -151,10 +209,55 @@ type Builder = {
    emitted verbatim from the original script), offset-relative to the line start. */
 type ScopeLine = { text: string; segments: ShadowMapping[] }
 
-function createBuilder(): Builder {
+function createBuilder(classify?: InterpolationClassifier): Builder {
     let code = ''
     let uniqueCounter = 0
     const mappings: ShadowMapping[] = []
+    /* The non-blocking async (sub)expression spans in one interpolation — the peek-wrap targets.
+       A leading `await` (blocking) stays verbatim: `await X` already resolves in the async shadow
+       render fn. Fail-open: no classifier, an unparseable field, or the D4a `AsyncIterable`-in-`each`
+       throw all yield no spans, so the emit is verbatim (`collectValuePositionDiagnostics` still
+       reports the D4a error separately). */
+    const peekSpans = (exprCode: string, sourceLoc: number, position: LiftPosition) => {
+        if (classify === undefined) {
+            return []
+        }
+        try {
+            let counter = 0
+            const result = liftAsyncSubExpressions(
+                exprCode,
+                sourceLoc,
+                classify,
+                () => `__v${counter++}`,
+                position,
+            )
+            return result.spans.filter((span) => !span.blocking)
+        } catch {
+            return []
+        }
+    }
+    /* Appends `exprCode` mapped 1:1 to source, but wraps each async span in its peek helper — the
+       wrapper chars are unmapped, every original char keeps its true source offset. */
+    const emitPeeked = (exprCode: string, sourceLoc: number, position: LiftPosition): void => {
+        const spans = peekSpans(exprCode, sourceLoc, position)
+        if (spans.length === 0) {
+            builder.mapped(exprCode, sourceLoc)
+            return
+        }
+        let cursor = 0
+        for (const span of spans) {
+            if (span.start > cursor) {
+                builder.mapped(exprCode.slice(cursor, span.start), sourceLoc + cursor)
+            }
+            builder.raw(span.kind === 'asyncIterable' ? '$$peekStream(' : '$$peek(')
+            builder.mapped(exprCode.slice(span.start, span.end), sourceLoc + span.start)
+            builder.raw(')')
+            cursor = span.end
+        }
+        if (cursor < exprCode.length) {
+            builder.mapped(exprCode.slice(cursor), sourceLoc + cursor)
+        }
+    }
     const builder: Builder = {
         unique(base) {
             return `__${base}_${uniqueCounter++}`
@@ -188,6 +291,21 @@ function createBuilder(): Builder {
             builder.expr(exprCode, sourceLoc)
             code += ';\n'
         },
+        asyncExpr(exprCode, sourceLoc, position) {
+            /* No source offset ⇒ can't map or classify — emit verbatim, like `expr`. */
+            if (sourceLoc === undefined) {
+                code += `(${exprCode})`
+                return
+            }
+            code += '('
+            emitPeeked(exprCode, sourceLoc, position)
+            code += ')'
+        },
+        asyncStmt(exprCode, sourceLoc, position) {
+            code += ';'
+            builder.asyncExpr(exprCode, sourceLoc, position)
+            code += ';\n'
+        },
         flush(line) {
             const base = code.length
             for (const segment of line.segments) {
@@ -209,6 +327,10 @@ type ScriptAnalysis = {
     /* The reactive primitives the author imports (`state`/`effect`), so the preamble
        omits the ambient fallback for each and avoids a duplicate-identifier error. */
     importedReactives: Set<string>
+    /* The LOCAL binding name the author's `props` import is bound to (alias-safe — `props`
+       for the canonical import, `p` for `props as p`), or undefined when not imported. The
+       `declare function` for `props` must target this name, not the canonical `'props'`. */
+    propsLocalName: string | undefined
 }
 
 /* Pushes a diagnostic for every author binding whose name starts with the reserved `$$`
@@ -321,7 +443,15 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
     const propsShapes: string[] = []
     const diagnostics: ShadowDiagnostic[] = []
     if (scriptBody.trim() === '') {
-        return { imports, types, scope, propsShapes, diagnostics, importedReactives: new Set() }
+        return {
+            imports,
+            types,
+            scope,
+            propsShapes,
+            diagnostics,
+            importedReactives: new Set(),
+            propsLocalName: undefined,
+        }
     }
     const file = ts.createSourceFile('script.ts', scriptBody, ts.ScriptTarget.Latest, true)
     /* The author's reactive import bindings (alias-safe) — recognition source for
@@ -329,6 +459,15 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
        the preamble omits its ambient fallback for. */
     const bindings = reactiveImportBindings(file)
     const importedReactives = new Set(bindings.direct.values())
+    /* The local name bound to `props` (alias-safe): the key whose value is the canonical
+       `'props'`. At most one — a file imports `props` from one specifier. */
+    let propsLocalName: string | undefined
+    for (const [local, canonical] of bindings.direct) {
+        if (canonical === 'props') {
+            propsLocalName = local
+            break
+        }
+    }
     /* The `$$` prefix is reserved for the compiler's injected runtime (`$$each`, `$$model`,
        `$$scope`, …), so an author binding may not start with it — that's the contract that
        lets a user freely name a variable after any helper. Flag every such declaration. */
@@ -368,7 +507,7 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
             scope.push(scopeLineFor(declaration, propsShapes, verbatim, span, bindings))
         }
     }
-    return { imports, types, scope, propsShapes, diagnostics, importedReactives }
+    return { imports, types, scope, propsShapes, diagnostics, importedReactives, propsLocalName }
 }
 
 /* Value-projects a nested control-flow `<script>` body the way `analyzeScript`
@@ -429,12 +568,20 @@ function scopeLineFor(
        `verbatim(call.expression)` below keeps the AUTHOR's text for the trailing hover ref. */
     const callee = resolveReactiveExport(call.expression, bindings)
     if (callee === 'props') {
-        /* `const {…} = props<Shape>()`: the type arg (default `Record<string, any>`)
-           IS the parent-facing prop shape, and the destructure projects verbatim against
-           the declared typed `props()` so each binding inherits its value type. */
-        const shape = call.typeArguments?.[0]
+        /* The parent-facing prop shape. Like `state`/`computed` below, it comes from the
+           generic (`const {…} = props<Shape>()`) OR the destructure's binding annotation
+           (`const {…}: Shape = props()`) — either TS-idiomatic form resolves through the
+           shadow's own imports, so an imported/aliased type just works, no inline gotcha.
+           Default `Record<string, any>`; the destructure then projects verbatim so each
+           binding inherits its value type. */
+        const shape = call.typeArguments?.[0] ?? declaration.type
         propsShapes.push(shape === undefined ? 'Record<string, any>' : verbatim(shape))
-        return { text: `const ${verbatim(declaration)};`, segments: [span(declaration, 6)] }
+        /* `let`, not `const`: a prop the component writes back through a two-way `bind:prop`
+           (`value += 1`, or forwarding it to another `bind:`) is a legal reassignment, so the
+           destructure must not read as a `const`. Bindability is dynamic (decided by what the
+           parent passed), so the shadow can't single out which props are written — it relaxes
+           the whole destructure, matching the runtime's usage-inferred upgrade. */
+        return { text: `let ${verbatim(declaration)};`, segments: [span(declaration, 4)] }
     }
     /* The rewrite drops the callee from the line, so hovering `state`/`computed`/
        `linked` at its call site has nothing to resolve. Append the callee as a
@@ -446,14 +593,22 @@ function scopeLineFor(
     })
     if (callee === 'state') {
         /* state<T>(initial): T is the value type — carry it onto the `let` so an
-           explicit annotation isn't lost to `any`/`any[]` inference of the initial. */
-        const typeNode = call.typeArguments?.[0]
+           explicit annotation isn't lost to `any`/`any[]` inference of the initial. The
+           type comes from the generic (`state<T>(v)`), else the binding annotation
+           (`let x: T = state(v)`) — either form pins the cell type, so a narrow/`any`
+           inference of the initial (`state([])` → `any[]`) can't leak. */
+        const typeNode = call.typeArguments?.[0] ?? declaration.type
         const annotation = typeNode === undefined ? '' : `: ${verbatim(typeNode)}`
         const init = call.arguments[0]
-        if (init === undefined) {
-            /* No initial (`state<T>()`): the value is `T | undefined`. A definite-
-               assignment assertion (`!`) gives that union without a use-before-assign
-               false-positive AND without control-flow narrowing it to just `undefined`
+        /* A literal `undefined` initial is the no-arg form spelled out (`state<T>(undefined)`):
+           the value is `T | undefined`, never `= (undefined)` checked against a non-optional
+           `T` — which would spuriously flag "undefined not assignable to T". */
+        const initIsUndefined =
+            init !== undefined && ts.isIdentifier(init) && init.text === 'undefined'
+        if (init === undefined || initIsUndefined) {
+            /* No initial (`state<T>()` / `state<T>(undefined)`): the value is `T | undefined`.
+               A definite-assignment assertion (`!`) gives that union without a use-before-
+               assign false-positive AND without control-flow narrowing it to just `undefined`
                (an `= undefined` initializer, never reassigned in the shadow, would make
                a guard like `x !== undefined` collapse to `never`). Unguarded access is
                then correctly flagged possibly-undefined; a guard narrows cleanly. */
@@ -471,9 +626,12 @@ function scopeLineFor(
         })
     }
     /* computed<T>(compute) / linked<T>(seed) — the only callees left: T is the value
-       type — the call's first arg is a thunk, so invoking it yields the value. Annotate
-       so an explicit type argument isn't lost to inference of the thunk's return. */
-    const typeNode = call.typeArguments?.[0]
+       type — the call's first arg is a thunk, so invoking it yields the value. The type
+       comes from the generic (`computed<T>(fn)`), else the binding annotation
+       (`let x: T = state.computed(fn)`) — same fallback as `state` above, so a binding
+       annotation isn't dropped and `abide check` doesn't emit `never`-inference false
+       positives on the thunk's return. */
+    const typeNode = call.typeArguments?.[0] ?? declaration.type
     const annotation = typeNode === undefined ? '' : `: ${verbatim(typeNode)}`
     const fn = call.arguments[0]
     /* `linked` is a writable `State<T>` at runtime (it reseeds AND accepts `.value =`
@@ -494,6 +652,28 @@ function scopeLineFor(
     })
 }
 
+/* Whether any ELEMENT in the tree carries an `attach` — gates emitting the DOM-typed
+   attachment aliases. All nested content (block bodies, await/switch branches, snippet
+   bodies) routes through `children`, so a recursive `children` walk is complete. */
+function hasElementAttach(nodes: TemplateNode[]): boolean {
+    for (const node of nodes) {
+        if (node === undefined) {
+            continue
+        }
+        if (node.kind === 'element') {
+            for (const attr of node.attrs) {
+                if (attr.kind === 'attach') {
+                    return true
+                }
+            }
+        }
+        if ('children' in node && node.children !== undefined && hasElementAttach(node.children)) {
+            return true
+        }
+    }
+    return false
+}
+
 /* Emits a sibling list — each node standalone via `emitNode`. */
 function emitNodes(nodes: TemplateNode[], builder: Builder): void {
     for (const node of nodes) {
@@ -511,22 +691,43 @@ function emitNode(node: TemplateNode, builder: Builder): void {
         case 'text':
             for (const part of node.parts) {
                 if (part.kind === 'expression') {
-                    builder.stmt(part.code, part.loc)
+                    builder.asyncStmt(part.code, part.loc, 'content')
                 }
             }
             return
         case 'element':
             for (const attr of node.attrs) {
-                /* An interpolated value checks each `{expr}` part on its own offset; every
-                   other dynamic attribute checks its single `code`. */
-                if (attr.kind === 'interpolated') {
+                if (attr.kind === 'attach') {
+                    /* `attach={code}` types its callback's `node` param from the element's tag
+                       (via `__ElementFor`) and checks the whole value is an attachment: an inline
+                       arrow's `node` reads the specific DOM interface, and a non-function value is
+                       rejected. Same IIFE-parameter contextual-typing trick the component-prop
+                       path uses; the leading `;` guards an unterminated preceding statement. */
+                    builder.raw(
+                        `;((__attach: __Attachment<__ElementFor<${JSON.stringify(node.tag)}>>) => {})(`,
+                    )
+                    builder.expr(attr.code, attr.loc)
+                    builder.raw(');\n')
+                } else if (attr.kind === 'interpolated') {
+                    /* An interpolated value checks each `{expr}` part on its own offset. */
                     for (const part of attr.parts) {
                         if (part.kind === 'expression') {
-                            builder.stmt(part.code, part.loc)
+                            builder.asyncStmt(part.code, part.loc, 'attribute')
                         }
                     }
                 } else if (attr.kind !== 'static') {
-                    builder.stmt(attr.code, attr.loc)
+                    /* Every other dynamic attribute checks its single `code`. `attrLiftPosition` —
+                       the shared gate the runtime front-end lifts through — decides whether the
+                       value is async-liftable: only `name={code}` peek-wraps (its promise/stream
+                       sub-expressions project to their resolved type), while a directive
+                       (`on*`/`bind:`/`class:`/`style:`/`{...}`) checks its code verbatim, matching
+                       that the runtime never injects a cell for it. */
+                    const position = attrLiftPosition(attr)
+                    if (position !== undefined) {
+                        builder.asyncStmt(attr.code, attr.loc, position)
+                    } else {
+                        builder.stmt(attr.code, attr.loc)
+                    }
                 }
             }
             emitNodes(node.children, builder)
@@ -548,6 +749,12 @@ function emitNode(node: TemplateNode, builder: Builder): void {
                 prop.name.startsWith('style:') ||
                 prop.name === 'attach'
             const hasSpread = node.props.some((prop) => prop.spread)
+            /* Default slot content (`<Card>…</Card>`) lowers to a `children` Snippet prop at
+               runtime (see generateBuild.slotPart), so the completeness check must treat
+               `children` as supplied when it's present (handled below). Mirror the runtime's
+               predicate: any child that isn't whitespace-only text is renderable slot content
+               — an empty/whitespace slot sets no `children` layer, so it doesn't count. */
+            const hasSlotContent = node.children.some((child) => !isWhitespaceText(child))
             for (const prop of node.props.filter(handled)) {
                 /* Lead with a defensive `;`: an IIFE/object-literal arg starts with `(` or
                    `{`, so without it a preceding scope statement left unterminated (a script
@@ -583,14 +790,30 @@ function emitNode(node: TemplateNode, builder: Builder): void {
                     builder.raw(');\n')
                 }
             } else {
-                builder.raw(`;((__c: Parameters<typeof ${node.name}>[0]): void => { void __c })({`)
+                /* With slot content the child's `children` prop is supplied by the slot, so
+                   check completeness against the shape with `children` made OPTIONAL rather
+                   than removed — dropping it via a bare `Omit` collapses a children-only
+                   shape to `{}`, a weak type that then lets excess props slip by. `Omit` +
+                   `Partial<Pick<…>>` keeps every other prop required and `children` as a
+                   known-optional key (a no-op `Partial<{}>` when the child declares none), so
+                   completeness and excess-prop checks both stay intact. The explicit
+                   `children={…}` attribute is dropped from the literal — the slot's key wins
+                   (`composeProps`), and leaving it in would read as excess. */
+                const propsShape = `Parameters<typeof ${node.name}>[0]`
+                const completenessType = hasSlotContent
+                    ? `Omit<${propsShape}, 'children'> & Partial<Pick<${propsShape}, Extract<keyof ${propsShape}, 'children'>>>`
+                    : propsShape
+                const literalProps = hasSlotContent
+                    ? dataProps.filter((prop) => prop.name !== 'children')
+                    : dataProps
+                builder.raw(`;((__c: ${completenessType}): void => { void __c })({`)
                 /* A zero-length anchor right after `{`, pointing at the tag: a missing-
                    required-prop error spans the literal from `{`, so it overlaps this and
                    maps to the tag (an empty span trivially satisfies the source-text ==
                    shadow-text invariant). */
                 builder.mapped('', node.loc)
                 builder.raw('\n')
-                for (const prop of dataProps) {
+                for (const prop of literalProps) {
                     /* The key mapped to its source name (excess-prop errors land on the key);
                        the value verbatim-mapped (wrong-type errors land on the value).
                        Hyphenated names (`aria-label`, `data-*`) aren't valid identifiers, so
@@ -630,7 +853,7 @@ function emitNode(node: TemplateNode, builder: Builder): void {
             )
             const thenChildren = node.children.filter((child) => child.kind !== 'case')
             builder.raw('if ')
-            builder.expr(node.condition, node.loc)
+            builder.asyncExpr(node.condition, node.loc, 'if')
             builder.raw(' {\n')
             emitNodes(thenChildren, builder)
             builder.raw('}')
@@ -639,7 +862,7 @@ function emitNode(node: TemplateNode, builder: Builder): void {
             for (const branch of branches) {
                 if (branch.condition !== undefined) {
                     builder.raw(' else if ')
-                    builder.expr(branch.condition, branch.loc)
+                    builder.asyncExpr(branch.condition, branch.loc, 'if')
                     builder.raw(' {\n')
                 } else {
                     builder.raw(' else {\n')
@@ -721,7 +944,7 @@ function emitNode(node: TemplateNode, builder: Builder): void {
                non-case children (whitespace between cases) carry nothing and are
                skipped. `break` keeps cases independent under `noFallthroughCasesInSwitch`. */
             builder.raw('switch (')
-            builder.expr(node.subject, node.loc)
+            builder.asyncExpr(node.subject, node.loc, 'switch')
             builder.raw(') {\n')
             for (const child of node.children) {
                 if (child.kind !== 'case') {
@@ -773,7 +996,7 @@ function emitNode(node: TemplateNode, builder: Builder): void {
                 builder.mapped(node.params, node.loc)
             }
             /* Wrap the body in `snippet(() => …)` so the shadow types the snippet as
-               `(args) => Snippet<…>` — mirroring the runtime lowering (which returns
+               `(args) => SnippetValue` — mirroring the runtime lowering (which returns
                `$$snippet(($host) => …)`) so a snippet passed to a `Snippet`-typed prop
                type-checks instead of reading as `() => void`. */
             builder.raw(') => snippet(() => {\n')

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

@@ -11,17 +11,28 @@ SSR/client prop congruence rests on. No spread → the plain object literal of n
 value thunks (+ the trailing slot). With a `{...expr}` spread → a `mergeProps` of
 ordered layers — explicit-prop runs, `$$spreadProps(expr)` spreads, the slot —
 resolved last-wins per key, so source order decides overrides (like JSX).
-`lowerExpression` is the caller's expression lowering; `slotPart` is its `$children`
-layer (a host-taking builder for the client, a string-returning thunk for SSR) or
+`lowerExpression` is the caller's expression lowering; `slotPart` is its `children`
+layer — slotted content as a `Snippet` under the `children` prop key (a builder-
+returning callable for the client, a `$snip`-string-returning callable for SSR) — or
 undefined when the component has no slotted children.
 */
 export function composeProps(
     props: ComponentProps,
     lowerExpression: (code: string) => string,
     slotPart: string | undefined,
+    /* The two-way bind accessors (`lowerContext`): `bindRead` lowers a target to its
+       current value, `bindWrite` to the statement that writes a value back. Shared with
+       element `bind:`, so a component bind accepts the same lvalue / `{ get, set }` targets. */
+    bindRead: (code: string) => string,
+    bindWrite: (code: string, valueExpr: string) => string,
 ): string {
-    const propThunk = (prop: { name: string; code: string }): string =>
-        `${JSON.stringify(prop.name)}: () => (${lowerExpression(prop.code)})`
+    /* A `bind:<name>={target}` prop: the normal `() => value` entry, annotated with a
+       `set` write-back channel (`bindProp`) so the child can push changes upstream. A
+       read-only consumer still just calls the thunk; the setter rides along unseen. */
+    const propThunk = (prop: { name: string; code: string; bind?: true }): string =>
+        prop.bind === true
+            ? `${JSON.stringify(prop.name)}: $$bindProp(() => (${bindRead(prop.code)}), ($value) => { ${bindWrite(prop.code, '$value')} })`
+            : `${JSON.stringify(prop.name)}: () => (${lowerExpression(prop.code)})`
     if (!props.some((prop) => prop.spread)) {
         const parts = props.map(propThunk)
         if (slotPart !== undefined) {