@abide/abide 0.48.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,12 +46,8 @@ export function signalRefsTransformer(
         ...stateNames,
         ...derivedNames,
         ...computedNames,
+        ...cellReadNames,
         ...blockLocal,
-        /* The reserved slot reader (`{#if children}` → `$props?.$children`) is rewritten
-           through `referenceFor` like a signal, so it inherits the same lexical-scope
-           tracking: a `{#snippet row(children)}` arg, a `{#for children of …}` item, a
-           script param named `children` re-binds it for that subtree and is left untouched. */
-        'children',
         /* `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
            shadowably: a `const scope`/param `scope` re-binds it for that subtree and is left
@@ -114,6 +96,7 @@ export function signalRefsTransformer(
                         derivedNames,
                         computedNames,
                         blockLocal,
+                        cellReadNames,
                     )
                     if (replacement !== undefined) {
                         return ts.factory.createPropertyAssignment(node.name.text, replacement)
@@ -126,6 +109,7 @@ export function signalRefsTransformer(
                         derivedNames,
                         computedNames,
                         blockLocal,
+                        cellReadNames,
                     )
                     if (replacement !== undefined) {
                         return replacement
@@ -332,34 +316,36 @@ function functionParameters(node: ts.Node): ts.NodeArray<ts.ParameterDeclaration
 
 /* `$$model.<name>` for a state binding, `<name>()` for a computed doc-slot (the
    string-free reader `scope().derive` returns), `<name>.value` for a runtime cell
-   (linked / lens / transform-state), `$props?.$children` for the reserved slot reader,
-   else undefined. A `blockLocal` binding shadows any same-named component signal — it is
-   a nearer lexical scope — so it derefs as a cell (`<name>.value`) regardless of a
-   colliding `state`/`computed`/`derived`, and ahead of the `children` slot reader. */
+   (linked / lens / transform-state), else undefined. A `blockLocal` binding shadows
+   any same-named component signal — it is a nearer lexical scope — so it derefs as a
+   cell (`<name>.value`) regardless of a colliding `state`/`computed`/`derived`.
+   `children` is an ordinary destructured prop now — it rewrites via the `derivedNames`
+   branch below like any other, with no special case. */
 function referenceFor(
     name: string,
     stateNames: ReadonlySet<string>,
     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')
     }
-    /* `{children()}` is a slot NODE the parser handles; any other bare `children` read
-       (notably `{#if children}`) is the reserved reader. `?.` guards a propless mount. */
-    if (name === 'children') {
-        return ts.factory.createPropertyAccessChain(
-            ts.factory.createIdentifier('$props'),
-            ts.factory.createToken(ts.SyntaxKind.QuestionDotToken),
-            ts.factory.createIdentifier('$children'),
-        )
-    }
     /* The author-facing reactive entry `scope` lowers to its reserved `$$scope` import (the
        value read only — a `.scope` member or a shadowing local is never reached here). */
     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/resolveReactiveExport.ts

@@ -9,9 +9,7 @@ export type ReactivePrimitive = 'state' | 'linked' | 'computed' | 'effect' | 'wa
 
 /* The `abide/ui/*` specifier each importable reactive primitive is published at,
    mapped to its canonical name. Built from the package name so a rename is one edit.
-   `linked`/`computed` are members of `state`, not standalone imports; `props` is
-   ambient sugar today (no module) — kept here so a future `abide/ui/props` resolves
-   with no code change. */
+   `linked`/`computed` are members of `state`, not standalone imports. */
 const REACTIVE_SPECIFIERS: Record<string, ReactivePrimitive> = {
     [`${ABIDE_PACKAGE_NAME}/ui/state`]: 'state',
     [`${ABIDE_PACKAGE_NAME}/ui/effect`]: 'effect',
@@ -39,6 +37,7 @@ export const NESTED_REACTIVE_BINDINGS: ReactiveImportBindings = {
         ['state', 'state'],
         ['effect', 'effect'],
         ['watch', 'watch'],
+        ['props', 'props'],
     ]),
     stateRoots: new Set(['state']),
 }
@@ -70,9 +69,7 @@ export function reactiveImportBindings(source: ts.SourceFile): ReactiveImportBin
     return { direct, stateRoots }
 }
 
-/* The reactive primitive a call's callee resolves to, or undefined. A bare `props`
-   identifier is always the ambient prop reader — the one primitive with no runtime module
-   (pure compiler sugar), so it resolves with no import. Every other bare identifier
+/* The reactive primitive a call's callee resolves to, or undefined. Every bare identifier
    resolves through the direct import bindings (alias-safe); a `stateRoot.linked` /
    `.computed` member call resolves off a local bound to `state`. Every other callee is
    undefined (a user's own function, an unrelated member access). */
@@ -81,7 +78,7 @@ export function resolveReactiveExport(
     bindings: ReactiveImportBindings,
 ): ReactivePrimitive | undefined {
     if (ts.isIdentifier(callee)) {
-        return callee.text === 'props' ? 'props' : bindings.direct.get(callee.text)
+        return bindings.direct.get(callee.text)
     }
     if (
         ts.isPropertyAccessExpression(callee) &&

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

@@ -79,12 +79,35 @@ function scopeSelector(selector: string, attribute: string): string {
     if (selector === '') {
         return selector
     }
-    const match = selector.match(/^(.*?)([^\s>+~]+)$/)
-    if (match === null) {
+    /* The last compound begins just after the final combinator (whitespace / `>` / `+` / `~`)
+       at bracket depth zero. Bracket-aware so a space inside a quoted attribute value
+       (`[data-label="Read more"]`) is NOT mistaken for a descendant combinator — a plain
+       `/\s/` split there desyncs pseudoIndex's bracket count and drops the whole rule. */
+    let depth = 0
+    let lastCompoundStart = 0
+    for (let index = 0; index < selector.length; index += 1) {
+        const char = selector[index] as string
+        if (char === '[') {
+            depth += 1
+        } else if (char === ']') {
+            depth -= 1
+        } else if (
+            depth === 0 &&
+            (char === ' ' ||
+                char === '\t' ||
+                char === '\n' ||
+                char === '>' ||
+                char === '+' ||
+                char === '~')
+        ) {
+            lastCompoundStart = index + 1
+        }
+    }
+    const prefix = selector.slice(0, lastCompoundStart)
+    const last = selector.slice(lastCompoundStart)
+    if (last === '') {
         return `${selector}[${attribute}]`
     }
-    const prefix = match[1] ?? ''
-    const last = match[2] ?? ''
     const pseudo = pseudoIndex(last)
     const scopedLast =
         pseudo === -1

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