@abide/abide 0.49.0 → 0.50.0

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

@@ -0,0 +1,35 @@
+import ts from 'typescript'
+
+/* Every identifier read as a value in `code` — excludes property member names (`.name`) and object
+   literal keys, which are not free variable references. Deliberately generous elsewhere: an inner
+   arrow's param is still collected, so an expression shadowing a binder name inside a callback is
+   judged conservatively (NOT prefix-evaluable) rather than risking a false hoist. Shared by the
+   await-flight and child-render-flight prefix-evaluability checks (ADR-0034 / ADR-0037). */
+export function referencedIdentifiers(code: string): Set<string> {
+    const names = new Set<string>()
+    let source: ts.SourceFile
+    try {
+        source = ts.createSourceFile('expression.ts', code, ts.ScriptTarget.Latest, true)
+    } catch {
+        /* Unparseable expression → treat as non-hoistable by returning a sentinel the caller's
+           binder check can never clear; simplest is a name no scope defines. */
+        return new Set(['\0unparseable'])
+    }
+    const visit = (node: ts.Node): void => {
+        if (ts.isPropertyAccessExpression(node)) {
+            visit(node.expression)
+            return
+        }
+        if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name)) {
+            visit(node.initializer)
+            return
+        }
+        if (ts.isIdentifier(node)) {
+            names.add(node.text)
+            return
+        }
+        ts.forEachChild(node, visit)
+    }
+    visit(source)
+    return names
+}

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

@@ -1,10 +1,9 @@
 import ts from 'typescript'
-import { TS_PRINTER } from './TS_PRINTER.ts'
 
 /*
 Rewrites references to a component's signal bindings into the document form the
 rest of the pipeline understands: a `state` binding `count` becomes `$$model.count`
-(data access `lowerDocAccess` then lowers to a patch/read), and a `computed`
+(data access `docAccessTransformer` then lowers to a patch/read), and a `computed`
 binding `total` becomes `total.value`. Only value-position identifiers are
 touched — declaration names, parameter names, and property names are collected
 into a skip set first, and object shorthand (`{ count }`) is expanded to
@@ -17,27 +16,10 @@ to that inner binding, not the component signal, so it is left untouched. Withou
 this, a callback like `list.map(option => option.toUpperCase())` in a component
 that also has an `option` prop (`const { option } = props()`) would have its loop
 variable rewritten to `option()` and blow up at runtime (`option is not a function`).
-*/
-export function renameSignalRefs(
-    code: string,
-    stateNames: ReadonlySet<string>,
-    derivedNames: ReadonlySet<string>,
-    computedNames: ReadonlySet<string> = new Set(),
-): string {
-    const source = ts.createSourceFile('component.ts', code, ts.ScriptTarget.Latest, true)
-    const result = ts.transform(source, [
-        signalRefsTransformer(stateNames, derivedNames, computedNames),
-    ])
-    const output = TS_PRINTER.printFile(result.transformed[0] as ts.SourceFile)
-    result.dispose()
-    return output
-}
 
-/*
-The signal-rewrite as a `ts.TransformerFactory`, so the script pipeline can chain it
-with `docAccessTransformer` over a SINGLE parsed tree (see `lowerScript`) instead of
-print-then-reparse between passes. `renameSignalRefs` is the standalone string wrapper
-kept for test and one-off callers.
+Exposed as a `ts.TransformerFactory`, so the script pipeline can chain it with
+`docAccessTransformer` over a SINGLE parsed tree (see `lowerScript`) instead of
+print-then-reparse between passes.
 */
 export function signalRefsTransformer(
     stateNames: ReadonlySet<string>,
@@ -53,6 +35,10 @@ export function signalRefsTransformer(
        bare identifier, not `.value`: SSR declares `const foo = <resolved>`, so a reference
        reads the local directly. Seeded into the root shadow set so it is left untouched. */
     blockLocalPlain: ReadonlySet<string> = new Set(),
+    /* Component signals read through `$$readCell(name)` — every `linked` and every async
+       `computed` (see `desugarSignals`). A nearer lexical binding of the same name shadows
+       them like any other signal. */
+    cellReadNames: ReadonlySet<string> = new Set(),
 ): ts.TransformerFactory<ts.SourceFile> {
     /* The signal names that a nested binding can shadow — only these matter for
        scope tracking, so we ignore every other local binding. */
@@ -60,6 +46,7 @@ export function signalRefsTransformer(
         ...stateNames,
         ...derivedNames,
         ...computedNames,
+        ...cellReadNames,
         ...blockLocal,
         /* `scope` is the author-facing reactive entry (`scope().state(...)`), lowered to the
            reserved `$$scope` import so a user variable named `scope` can never collide — but
@@ -109,6 +96,7 @@ export function signalRefsTransformer(
                         derivedNames,
                         computedNames,
                         blockLocal,
+                        cellReadNames,
                     )
                     if (replacement !== undefined) {
                         return ts.factory.createPropertyAssignment(node.name.text, replacement)
@@ -121,6 +109,7 @@ export function signalRefsTransformer(
                         derivedNames,
                         computedNames,
                         blockLocal,
+                        cellReadNames,
                     )
                     if (replacement !== undefined) {
                         return replacement
@@ -338,6 +327,7 @@ function referenceFor(
     derivedNames: ReadonlySet<string>,
     computedNames: ReadonlySet<string>,
     blockLocal: ReadonlySet<string> = new Set(),
+    cellReadNames: ReadonlySet<string> = new Set(),
 ): ts.Expression | undefined {
     if (blockLocal.has(name)) {
         return ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier(name), 'value')
@@ -347,6 +337,15 @@ function referenceFor(
     if (name === 'scope') {
         return ts.factory.createIdentifier('$$scope')
     }
+    /* A `linked` / async `computed` cell → `$$readCell(name)`: one read shape that peeks an
+       async cell and reads `.value` off a sync one. */
+    if (cellReadNames.has(name)) {
+        return ts.factory.createCallExpression(
+            ts.factory.createIdentifier('$$readCell'),
+            undefined,
+            [ts.factory.createIdentifier(name)],
+        )
+    }
     if (stateNames.has(name)) {
         return ts.factory.createPropertyAccessExpression(
             ts.factory.createIdentifier('$$model'),

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

@@ -0,0 +1,65 @@
+import { classifyInterpolationType } from './classifyInterpolationType.ts'
+import { createShadowProgram, type ShadowProgram } from './createShadowProgram.ts'
+import { nodeAtShadowOffset } from './nodeAtShadowOffset.ts'
+import { shadowNaming } from './shadowNaming.ts'
+import { sourceToShadowOffset } from './sourceToShadowOffset.ts'
+import type { SeedTypeClassifier } from './types/SeedTypeClassifier.ts'
+
+/*
+Builds the type-directed SEED classifier for one `.abide` file (ADR-0023) — the cell
+transform's counterpart to `interpolationClassifierForRoot`, resolving a `computed`/`linked`
+seed's checker type through the SAME warm shadow program (kept once per project root, ADR-0019
+Stage B). Shares the `cache` the interpolation classifier populates, so no second program is
+built: whichever classifier is requested first for a root warms it, the other reuses it.
+
+A `computed(SEED)` declaration is emitted into the shadow's script region with `SEED` wrapped
+in parens (verbatim if the callee is unrecognized, or projected as `(SEED)()` when recognized
+as `state.computed` — either way the seed sub-expression maps back to source and resolves its
+own type), so the identical `sourceToShadowOffset → nodeAtShadowOffset → classifyInterpolation
+Type` pipeline the interpolation half uses resolves a seed with no node-finder variant.
+
+FAIL-OPEN, but NOT to `'sync'`: if the program can't build, the file has no shadow, the seed's
+location doesn't map, no node is found, or the checker throws, the classifier is absent /
+returns `undefined` — the signal the caller reads as "degrade to `isBareCallComputed`", NOT as
+"the seed is sync". Collapsing failure to `'sync'` (as the interpolation classifier does) would
+mis-route a failed stream seed to the lazy `derive` slot instead of today's syntax heuristic.
+*/
+export function seedTypeClassifierForRoot(
+    cache: Map<string, ShadowProgram | undefined>,
+    root: string,
+    abidePath: string,
+): SeedTypeClassifier | undefined {
+    if (!cache.has(root)) {
+        try {
+            cache.set(root, createShadowProgram(root))
+        } catch {
+            cache.set(root, undefined)
+        }
+    }
+    const shadowProgram = cache.get(root)
+    if (shadowProgram === undefined) {
+        return undefined
+    }
+    const { program, shadows } = shadowProgram
+    const shadowFile = program.getSourceFile(shadowNaming.suffixed(abidePath))
+    if (shadowFile === undefined) {
+        return undefined
+    }
+    const checker = program.getTypeChecker()
+    return (loc, code) => {
+        try {
+            const mappings = shadows.get(abidePath)?.mappings ?? []
+            const offset = sourceToShadowOffset(mappings, loc)
+            if (offset === undefined) {
+                return undefined
+            }
+            const node = nodeAtShadowOffset(shadowFile, offset, code.length)
+            if (node === undefined) {
+                return undefined
+            }
+            return classifyInterpolationType(checker.getTypeAtLocation(node), node, checker)
+        } catch {
+            return undefined
+        }
+    }
+}

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

@@ -0,0 +1,47 @@
+import type ts from 'typescript'
+import { classifyInterpolationType } from './classifyInterpolationType.ts'
+import { nodeAtShadowOffset } from './nodeAtShadowOffset.ts'
+import { shadowNaming } from './shadowNaming.ts'
+import { sourceToShadowOffset } from './sourceToShadowOffset.ts'
+import type { CompiledShadow } from './types/CompiledShadow.ts'
+import type { InterpolationClassifier } from './types/InterpolationClassifier.ts'
+
+/*
+Builds the type-directed interpolation classifier for one `.abide` file against an already-built
+shadow `program` (its `shadows` map carries each file's source→shadow `mappings`). Given an
+interpolation's absolute source offset and text, it maps into shadow coordinates, finds the emitted
+expression node, and reads its checker type — the shared core behind both `interpolationClassifier
+ForRoot` (the runtime lowering, over `createShadowProgram`) and the type-check shadow's own peek-wrap
+(over the check/LSP program). The classifier reads a VERBATIM shadow — one whose interpolations were
+NOT peek-wrapped — so `getFoo()` still types as `Promise<…>` and classifies as `promise`.
+
+FAIL-OPEN: no shadow file for the path ⇒ `undefined` (caller degrades to no wrap / plain binding);
+the returned closure wraps its body so ANY throw (missing node, checker hiccup) returns `'sync'`.
+*/
+export function shadowInterpolationClassifier(
+    program: ts.Program,
+    shadows: Map<string, CompiledShadow>,
+    abidePath: string,
+): InterpolationClassifier | undefined {
+    const shadowFile = program.getSourceFile(shadowNaming.suffixed(abidePath))
+    if (shadowFile === undefined) {
+        return undefined
+    }
+    const checker = program.getTypeChecker()
+    return (loc, code) => {
+        try {
+            const mappings = shadows.get(abidePath)?.mappings ?? []
+            const offset = sourceToShadowOffset(mappings, loc)
+            if (offset === undefined) {
+                return 'sync'
+            }
+            const node = nodeAtShadowOffset(shadowFile, offset, code.length)
+            if (node === undefined) {
+                return 'sync'
+            }
+            return classifyInterpolationType(checker.getTypeAtLocation(node), node, checker)
+        } catch {
+            return 'sync'
+        }
+    }
+}

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

@@ -0,0 +1,20 @@
+import type ts from 'typescript'
+
+/* The compiler-option fields that change how a source file parses or binds — the only inputs
+   (besides the text) that make two parses of the same path differ, so the `cachedSourceFile`
+   key folds them in to keep two projects with different targets/libs from sharing a file. */
+export function sourceFileOptionsSignature(options: ts.CompilerOptions): string {
+    return JSON.stringify([
+        options.target,
+        options.module,
+        options.moduleDetection,
+        options.jsx,
+        options.jsxImportSource,
+        options.useDefineForClassFields,
+        options.alwaysStrict,
+        options.strict,
+        options.verbatimModuleSyntax,
+        options.isolatedModules,
+        options.lib,
+    ])
+}

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

@@ -0,0 +1,107 @@
+import { BLOCK_CONNECTORS, BLOCK_OPENERS } from './BLOCK_KEYWORDS.ts'
+import type { SemanticToken } from './types/SemanticToken.ts'
+
+/*
+Semantic tokens for a `{#…}`/`{:…}`/`{/…}` control-block head, driven by the parse
+walk (`readBlockToken`) rather than a raw source regex — so the SAME grammar that
+builds the block tree colors it, and a `{#for}` sitting inside a `{expr}`/string/
+backtick region (which the walk skips as opaque expression text) is never miscolored.
+Emits an `operator` token for the `{`+sigil opener and a `keyword` token for the
+block word, plus the `of`/`by` connectors inside a `{#for …}` head. A keyword
+allowlist after the sigil keeps an arbitrary `{:foo}` uncolored (nothing emitted).
+*/
+/* The scan vocabulary, derived from the shared BLOCK_KEYWORDS source of truth (plus the
+   `for await` async-each phrase) so it can't drift from the parser. Sorted longest-first so
+   the match takes the whole phrase — `for await` beats `for`, `else if` beats `else` —
+   since a shorter prefix checked first would win otherwise. */
+const BLOCK_KEYWORDS = [...BLOCK_OPENERS, ...BLOCK_CONNECTORS, 'for await'].sort(
+    (a, b) => b.length - a.length,
+)
+
+const WORD_CHAR = /\w/
+
+/*
+Emits the head tokens for a block whose `{` sits at `braceStart`, whose sigil is
+`#`/`:`/`/`, and whose first directive word begins at `keywordStart` (already past the
+leading whitespace `{#  for}` allows). Matches the longest allowlist keyword at
+`keywordStart` requiring a trailing word boundary; if no keyword matches, emits NOTHING
+(not even the opener) — mirroring the old regex, which only colored an allowlist match.
+*/
+export function structuralHeadTokens(
+    source: string,
+    braceStart: number,
+    sigil: string,
+    keywordStart: number,
+): SemanticToken[] {
+    let matched: string | undefined
+    for (const keyword of BLOCK_KEYWORDS) {
+        if (
+            source.startsWith(keyword, keywordStart) &&
+            !WORD_CHAR.test(source.charAt(keywordStart + keyword.length))
+        ) {
+            matched = keyword
+            break
+        }
+    }
+    if (matched === undefined) {
+        return []
+    }
+    const tokens: SemanticToken[] = [
+        { start: braceStart, length: 2, type: 'operator', modifiers: [] },
+        { start: keywordStart, length: matched.length, type: 'keyword', modifiers: [] },
+    ]
+    /* A `{#for …}` head carries abide-only connectors `of`/`by` that the shadow lowers
+       away (`of`) or never emits (`by`), so color them here. */
+    if (sigil === '#' && (matched === 'for' || matched === 'for await')) {
+        forHeadConnectors(source, keywordStart + matched.length, tokens)
+    }
+    return tokens
+}
+
+/*
+Scans a `{#for …}` head from `from` to its closing `}`, pushing `keyword` tokens for the
+`of`/`by` connectors at brace depth 0 — skipping any `of`/`by` nested in a destructure,
+call, or string so an identifier or object key is never miscolored.
+*/
+function forHeadConnectors(source: string, from: number, tokens: SemanticToken[]): void {
+    let depth = 0
+    let cursor = from
+    while (cursor < source.length) {
+        const char = source.charAt(cursor)
+        if (char === '"' || char === "'" || char === '`') {
+            cursor += 1
+            while (cursor < source.length && source.charAt(cursor) !== char) {
+                if (source.charAt(cursor) === '\\') {
+                    cursor += 1
+                }
+                cursor += 1
+            }
+        } else if (char === '{' || char === '(' || char === '[') {
+            depth += 1
+        } else if (char === ')' || char === ']') {
+            depth -= 1
+        } else if (char === '}') {
+            if (depth === 0) {
+                break
+            }
+            depth -= 1
+        } else if (depth === 0 && (char === 'o' || char === 'b')) {
+            const word = source.startsWith('of', cursor)
+                ? 'of'
+                : source.startsWith('by', cursor)
+                  ? 'by'
+                  : undefined
+            const isWordBoundary = (offset: number): boolean => /\s/.test(source.charAt(offset))
+            if (
+                word !== undefined &&
+                isWordBoundary(cursor - 1) &&
+                isWordBoundary(cursor + word.length)
+            ) {
+                tokens.push({ start: cursor, length: word.length, type: 'keyword', modifiers: [] })
+                cursor += word.length
+                continue
+            }
+        }
+        cursor += 1
+    }
+}

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

@@ -0,0 +1,21 @@
+import { parseTemplateRecovering } from './parseTemplateRecovering.ts'
+import type { SemanticToken } from './types/SemanticToken.ts'
+
+/*
+The LSP's markup + structural highlighting for a full `.abide` component, driven by
+the ONE parse walk (`parseTemplateRecovering`) instead of a pair of hand-rolled
+lexers — so the same grammar that builds the tree colors it, and no coloring can
+drift from what the parser accepts. Runs over the FULL source at `baseOffset 0` with
+token collection on: element/component tag names (`tag`/`type`), attribute names
+(`attribute`), quoted/unquoted values (`string`), comments (`comment`), the
+`<`/`>`/`=`/`/` punctuation (`operator`), and the `{#…}`/`{:…}`/`{/…}` block framing
+(`operator` + `keyword`). The leading `<script>…</script>` reads through the same
+`readElement` path as a nested script, so its open+close tags color with no separate
+leading-region lexer. `{…}` expression interiors and raw `<script>`/`<style>` bodies
+are skipped — those are the type-checking shadow's job. The parse's `nodes` and
+`diagnostics` (including the spurious leading-script diagnostics a full-source parse
+raises) are discarded; only `.tokens` is used.
+*/
+export function templateSemanticTokens(source: string): SemanticToken[] {
+    return parseTemplateRecovering(source, 0, true).tokens
+}

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

@@ -0,0 +1,15 @@
+/* The regex that isolates a `.abide` file's leading `<script>` block, capturing its body (`[1]`) —
+   the single source `analyzeComponent`, `compileShadow`, and `templateStartOffset` all match on to
+   split script from template, so the three can never drift. Stateless (no `/g`), safe to share. */
+export const LEADING_SCRIPT = /^\s*<script[^>]*>([\s\S]*?)<\/script>/
+
+/*
+The source offset where the template markup begins — just past the closing `</script>` of a
+leading `<script>` block, or `0` when the file is template-only. A component's template
+interpolations all map to source offsets at or after this point, so it doubles as the boundary
+that separates template expressions from `<script>` code.
+*/
+export function templateStartOffset(source: string): number {
+    const leadingScript = source.match(LEADING_SCRIPT)
+    return leadingScript ? (leadingScript.index ?? 0) + leadingScript[0].length : 0
+}

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

@@ -16,8 +16,9 @@ export type TryPlan = {
     finallyChildren: TemplateNode[]
     /* No catch → a throw propagates to the enclosing boundary (re-throw / `undefined` thunk). */
     hasCatch: boolean
-    /* The catch branch's binding (`catchAs`, `plain`); empty when no catch branch. The
-       guarded and `finally` branches bind nothing. */
+    /* The catch branch's binding (`catchAs`, `reactive`); empty when no catch branch. The
+       error is a `.value` cell so a catch→catch swap updates `err` in place. The guarded and
+       `finally` branches bind nothing. */
     catchBindings: Binding[]
 }
 
@@ -31,6 +32,6 @@ export function tryPlan(node: Extract<TemplateNode, { kind: 'try' }>): TryPlan {
         catchAs,
         finallyChildren: finallyBranch?.children ?? [],
         hasCatch: catchBranch !== undefined,
-        catchBindings: catchBinding(catchAs, catchBranch !== undefined),
+        catchBindings: catchBinding(catchAs, catchBranch !== undefined, true),
     }
 }

package/src/lib/ui/compile/types/AnalyzedComponent.ts

@@ -24,6 +24,10 @@ export type AnalyzedComponent = {
     stateNames: Set<string>
     derivedNames: Set<string>
     computedNames: Set<string>
+    /* Component signals read through `$$readCell(name)`: every `linked` and every async
+       `computed`. Threaded to both back-ends so a template reference (`{draft}`) lowers to
+       the unified cell read consistently on client and server. */
+    cellReadNames: Set<string>
     nodes: TemplateNode[]
     /* One entry per non-empty `<style>` in the template (in source order): the scope
        attribute its covered elements carry (annotated onto `nodes`) and the scoped

package/src/lib/ui/compile/types/AsyncInterpolationField.ts

@@ -0,0 +1,19 @@
+import type { LiftPosition } from '../liftAsyncSubExpressions.ts'
+
+/* One async-liftable interpolation field of a template node — the shared reading both compile
+   front-ends drive their async lowering from (the block-Plan pattern of `ifPlan`/`awaitPlan`,
+   applied to interpolations instead of block structure). `code`/`loc` are the authored expression
+   and its absolute source offset; `position` is its value/content position (which feeds the shared
+   sub-expression walk's `each`-forbids-`AsyncIterable` rule). `subject` marks a control-flow test
+   (`{#if}` / `{:elseif}` / `{#switch}`) whose WHOLE expression lifting to one cell makes the block
+   hold while the cell is pending. `write` reseeds the field with the runtime's rewritten reference
+   and `setAsyncSubject` records the subject verdict — both are no-ops for a READER like the shadow,
+   which needs only `code`/`loc`/`position` to peek-wrap its projection. */
+export type AsyncInterpolationField = {
+    code: string
+    loc: number
+    position: LiftPosition
+    subject: boolean
+    write: (code: string) => void
+    setAsyncSubject: (asyncSubject: boolean) => void
+}

package/src/lib/ui/compile/types/InterpolationClassifier.ts

@@ -0,0 +1,12 @@
+import type { InterpolationKind } from './InterpolationKind.ts'
+
+/*
+Classifies a text-position `{expr}` interpolation from its checker type, keyed by
+the expression's source offset (`loc`) and verbatim `code`. Built by the bundler
+plugin over a warm shadow program (see `abideUiPlugin`) and threaded, OPTIONAL,
+through the compile front-end: when absent the pipeline behaves exactly as before
+(every interpolation binds as a plain value). Always fail-open — a resolution
+failure returns `'sync'`, never throws — so a type hiccup degrades to today's
+behavior instead of breaking the build.
+*/
+export type InterpolationClassifier = (loc: number, code: string) => InterpolationKind

package/src/lib/ui/compile/types/InterpolationKind.ts

@@ -0,0 +1,7 @@
+/*
+How a `{expr}` template interpolation resolves at runtime, from its checker type:
+`promise` (thenable — awaited), `asyncIterable` (drained over time), or `sync`
+(bound as a plain value). Stage A of type-directed interpolation lowering
+classifies into this; later stages pick the binding back-end from it.
+*/
+export type InterpolationKind = 'promise' | 'asyncIterable' | 'sync'

package/src/lib/ui/compile/types/ParseDiagnostic.ts

@@ -0,0 +1,8 @@
+/*
+A parser-local diagnostic — deliberately smaller than `AbideDiagnostic`, which
+additionally needs the `file` + `category` the parser cannot know. `start` is the
+absolute, `baseOffset`-relative offset (the same coordinate space every node `loc`
+uses, so it round-trips through the shadow `mappings`); `length` is 0 for a point
+diagnostic. Callers (`collectAbideDiagnostics`) adapt it to `AbideDiagnostic`.
+*/
+export type ParseDiagnostic = { message: string; start: number; length: number }

package/src/lib/ui/compile/types/SeedTypeClassifier.ts

@@ -0,0 +1,15 @@
+import type { InterpolationKind } from './InterpolationKind.ts'
+
+/*
+Classifies a `computed`/`linked` SEED expression from its checker type, keyed by the
+seed's source offset (`loc`) and verbatim `code` — the cell-transform counterpart of
+`InterpolationClassifier` (ADR-0023). Built by the bundler plugin over the SAME warm
+shadow program and threaded, OPTIONAL, through the compile front-end to `desugarSignals`.
+
+Unlike `InterpolationClassifier`, a resolution failure returns `undefined`, NOT `'sync'`:
+for a seed, fail-open means degrade to today's `isBareCallComputed` syntax heuristic, so a
+failure must be DISTINGUISHABLE from a genuine `sync` type (which routes to the lazy
+`derive` slot). Absent classifier ⇒ every seed resolves `undefined` ⇒ exactly today's
+behavior.
+*/
+export type SeedTypeClassifier = (loc: number, code: string) => InterpolationKind | undefined

package/src/lib/ui/compile/types/TemplateNode.ts

@@ -46,7 +46,17 @@ export type TemplateNode =
           keyLoc?: number
           indexLoc?: number
       }
-    | { kind: 'if'; condition: string; children: TemplateNode[]; loc?: number }
+    | {
+          kind: 'if'
+          condition: string
+          children: TemplateNode[]
+          loc?: number
+          /* `condition` is a bare async subject — the WHOLE test was one promise/stream that
+             `lowerAsyncInterpolations` lifted to a single peek-cell (`{#if getX()}`). The binary
+             back-ends then read its pending facet so a still-loading subject renders NO branch,
+             not the falsy `{:else}`. Unset (or on an `{:elseif}` chain) → the plain truthy test. */
+          asyncSubject?: boolean
+      }
     | {
           kind: 'await'
           promise: string
@@ -77,11 +87,29 @@ export type TemplateNode =
           loc?: number
           /* Each authored attribute as a prop. A `spread` entry (`{...code}`) carries no
              `name`; its keys merge in at runtime (`mergeProps`/`spreadProps`). `nameLoc` is
-             the prop name's source offset — the anchor for an excess-prop diagnostic. */
-          props: { name: string; code: string; loc?: number; nameLoc?: number; spread?: boolean }[]
+             the prop name's source offset — the anchor for an excess-prop diagnostic. `bind`
+             marks a `bind:<name>={target}` two-way prop: `code` is the writable target (an
+             lvalue or a `{ get, set }` accessor), passed with a write-back channel so the
+             child can push changes upstream (`bindProp`/`bindableProp`). */
+          props: {
+              name: string
+              code: string
+              loc?: number
+              nameLoc?: number
+              spread?: boolean
+              bind?: true
+          }[]
           children: TemplateNode[]
       }
-    | { kind: 'switch'; subject: string; children: TemplateNode[]; loc?: number }
+    | {
+          kind: 'switch'
+          subject: string
+          children: TemplateNode[]
+          loc?: number
+          /* `subject` is a bare async subject (the whole expression lifted to one peek-cell) —
+             a still-loading subject selects no case (not even the default) until it settles. */
+          asyncSubject?: boolean
+      }
     /* A branch of a `<template switch>` (`match` set) or `<template if>` chain. Inside an
        `if`, `<template elseif={c}>` sets `condition` (match-less, truthy-tested), and
        `<template else>` leaves both unset (the default). `loc` points at whichever
@@ -92,6 +120,10 @@ export type TemplateNode =
           condition?: string
           children: TemplateNode[]
           loc?: number
+          /* An `{:elseif}` whose `condition` is a bare async subject (the whole test lifted to one
+             peek-cell) — the cond-chain holds at this branch while the cell is pending, resuming the
+             top-down walk (skip it / match it / fall to the next branch) once it settles. */
+          asyncSubject?: boolean
       }
     /* A `{#snippet row(item)}` snippet: a named, scope-capturing builder declared
        once and called like a function (`{row(item)}`). `params` is the raw

package/src/lib/ui/compile/types/ValuePositionInterpolation.ts

@@ -0,0 +1,13 @@
+/*
+A template interpolation sitting in a NON-content value position — where a
+`Promise`/`AsyncIterable` can't be rendered over time and would silently stringify
+to `[object Promise]` (Stage E of type-directed lowering, ADR-0019). `loc`/`code`
+are the expression's source offset and verbatim text (the classifier's key), and
+`position` names the position for the diagnostic. `for await` is the sanctioned
+`{#for await}` iterable — the one value position where an `AsyncIterable` is allowed.
+*/
+export type ValuePositionInterpolation = {
+    loc: number
+    code: string
+    position: 'attribute' | 'if' | 'switch' | 'each' | 'for await'
+}