@abide/abide 0.49.0 → 0.50.1

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'
 
 /*
@@ -69,9 +74,13 @@ 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
@@ -80,6 +89,18 @@ export function compileShadow(source: string, propsType = 'Record<string, any>')
     const { imports, types, scope, propsShapes, diagnostics, importedReactives, propsLocalName } =
         analyzeScript(scriptBody, scriptStart)
     builder.raw(shadowPreamble(importedReactives))
+    /* 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
@@ -171,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. */
@@ -182,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++}`
@@ -219,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) {
@@ -481,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
@@ -596,7 +691,7 @@ 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
@@ -617,12 +712,22 @@ function emitNode(node: TemplateNode, builder: Builder): void {
                     /* 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') {
-                    /* Every other dynamic attribute checks its single `code`. */
-                    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)
@@ -644,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
@@ -679,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
@@ -726,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('}')
@@ -735,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')
@@ -817,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') {

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

@@ -20,9 +20,19 @@ 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) {

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

@@ -4,14 +4,18 @@ import { messageFromError } from '../../shared/messageFromError.ts'
 import { mapSyntacticClassification, mapTsClassification } from './ABIDE_SEMANTIC_TOKENS_LEGEND.ts'
 import { assetModulesFile } from './assetModulesFile.ts'
 import { compileShadow } from './compileShadow.ts'
+import { isSpuriousAsyncReadDiagnostic } from './isSpuriousAsyncReadDiagnostic.ts'
 import { loadShadowTsConfig } from './loadShadowTsConfig.ts'
 import { pagePropsType } from './pagePropsType.ts'
 import { remapShadowDiagnostic } from './remapShadowDiagnostic.ts'
 import { resolveAbideImports } from './resolveAbideImports.ts'
+import { shadowInterpolationClassifier } from './shadowInterpolationClassifier.ts'
 import { shadowNaming } from './shadowNaming.ts'
 import { sourceToShadowOffset } from './sourceToShadowOffset.ts'
+import { templateStartOffset } from './templateStartOffset.ts'
 import type { AbideDiagnostic } from './types/AbideDiagnostic.ts'
 import type { CompiledShadow } from './types/CompiledShadow.ts'
+import type { InterpolationClassifier } from './types/InterpolationClassifier.ts'
 import type { SemanticToken } from './types/SemanticToken.ts'
 
 const { suffixed, isShadow, sourceOf } = shadowNaming
@@ -45,12 +49,6 @@ export function createShadowLanguageService(cwd: string): ShadowLanguageService
     const { options, fileNames } = loadShadowTsConfig(cwd)
     const overlays = new Map<string, string>()
     const versions = new Map<string, number>()
-    const shadows = new Map<string, CompiledShadow>()
-    const parseErrors = new Map<string, string>()
-    /* Memo of `shadowText` output keyed by source path, tagged with the shadow
-       version it was compiled at; a stale tag forces recompilation. `update`/`close`
-       bump that version, so the next read recompiles. */
-    const compiledAt = new Map<string, { version: number; code: string }>()
     /* Memo of `pagePropsType` (route re-parse) per source path; the path → props
        type mapping is immutable, so no version tag is needed. */
     const propsTypes = new Map<string, string | undefined>()
@@ -69,33 +67,6 @@ export function createShadowLanguageService(cwd: string): ShadowLanguageService
     const exists = (abidePath: string): boolean =>
         overlays.has(abidePath) || ts.sys.fileExists(abidePath)
 
-    /* Compiles (and caches) a component's shadow from its overlay or disk text; a
-       template parse error yields a minimal valid module + a recorded message.
-       Memoised against the shadow's version (bumped by `update`/`close`), so
-       repeated reads at the same version skip the ~700-line compile and the
-       `shadows`/`parseErrors` caches stay current. */
-    const shadowText = (abidePath: string): string => {
-        const version = versions.get(suffixed(abidePath)) ?? 0
-        const memo = compiledAt.get(abidePath)
-        if (memo !== undefined && memo.version === version) {
-            return memo.code
-        }
-        const source = overlays.get(abidePath) ?? ts.sys.readFile(abidePath) ?? ''
-        try {
-            const compiled = compileShadow(source, propsTypeOf(abidePath))
-            shadows.set(abidePath, compiled)
-            parseErrors.delete(abidePath)
-            compiledAt.set(abidePath, { version, code: compiled.code })
-            return compiled.code
-        } catch (error) {
-            shadows.set(abidePath, { code: '', mappings: [] })
-            parseErrors.set(abidePath, messageFromError(error))
-            const code = 'export default function (): void {}\n'
-            compiledAt.set(abidePath, { version, code })
-            return code
-        }
-    }
-
     /* All component shadows: those on disk plus any opened (possibly unsaved) ones. */
     const shadowNames = (): string[] => {
         const disk = [...new Bun.Glob('**/*.abide').scanSync({ cwd, onlyFiles: true })]
@@ -104,44 +75,99 @@ export function createShadowLanguageService(cwd: string): ShadowLanguageService
         return [...new Set([...disk, ...overlays.keys()])].map(suffixed)
     }
 
-    const moduleResolutionHost: ts.ModuleResolutionHost = {
-        fileExists: (fileName) =>
-            fileName === assets.path ||
-            (isShadow(fileName) ? exists(sourceOf(fileName)) : ts.sys.fileExists(fileName)),
-        readFile: (fileName) =>
-            fileName === assets.path
-                ? assets.content
-                : isShadow(fileName)
-                  ? shadowText(sourceOf(fileName))
-                  : ts.sys.readFile(fileName),
-    }
-
-    const host: ts.LanguageServiceHost = {
-        getScriptFileNames: () => [assets.path, ...fileNames, ...shadowNames()],
-        getScriptVersion: (fileName) => String(versions.get(fileName) ?? 0),
-        getScriptSnapshot: (fileName) => {
-            if (fileName === assets.path) {
-                return ts.ScriptSnapshot.fromString(assets.content)
+    /* One incremental language service over the shadow world, its shadows built by `compile`. Two
+       are made: a VERBATIM one (the classifier source — interpolations un-wrapped, so `getFoo()`
+       still types as `Promise`), and the WRAPPED main one (async interpolations peek-wrapped, ADR-
+       0032, so hover/completions/diagnostics see the RESOLVED value). They share `overlays`/`versions`
+       so both reflect unsaved edits, but hold SEPARATE shadow caches + document registries (the same
+       shadow file name carries different text in each). */
+    const buildService = (compile: (source: string, abidePath: string) => CompiledShadow) => {
+        const shadows = new Map<string, CompiledShadow>()
+        const parseErrors = new Map<string, string>()
+        /* Memo of `shadowText` output keyed by source path, tagged with the shadow version it was
+           compiled at; a stale tag forces recompilation. `update`/`close` bump that version. */
+        const compiledAt = new Map<string, { version: number; code: string }>()
+        const shadowText = (abidePath: string): string => {
+            const version = versions.get(suffixed(abidePath)) ?? 0
+            const memo = compiledAt.get(abidePath)
+            if (memo !== undefined && memo.version === version) {
+                return memo.code
             }
-            if (isShadow(fileName)) {
-                return exists(sourceOf(fileName))
-                    ? ts.ScriptSnapshot.fromString(shadowText(sourceOf(fileName)))
-                    : undefined
+            const source = overlays.get(abidePath) ?? ts.sys.readFile(abidePath) ?? ''
+            try {
+                const compiled = compile(source, abidePath)
+                shadows.set(abidePath, compiled)
+                parseErrors.delete(abidePath)
+                compiledAt.set(abidePath, { version, code: compiled.code })
+                return compiled.code
+            } catch (error) {
+                shadows.set(abidePath, { code: '', mappings: [] })
+                parseErrors.set(abidePath, messageFromError(error))
+                const code = 'export default function (): void {}\n'
+                compiledAt.set(abidePath, { version, code })
+                return code
             }
-            const text = ts.sys.readFile(fileName)
-            return text === undefined ? undefined : ts.ScriptSnapshot.fromString(text)
-        },
-        getCurrentDirectory: () => cwd,
-        getCompilationSettings: () => options,
-        getDefaultLibFileName: (compilerOptions) => ts.getDefaultLibFilePath(compilerOptions),
-        fileExists: moduleResolutionHost.fileExists,
-        readFile: moduleResolutionHost.readFile,
-        readDirectory: ts.sys.readDirectory,
-        directoryExists: ts.sys.directoryExists,
-        getDirectories: ts.sys.getDirectories,
-        resolveModuleNames: resolveAbideImports(options, moduleResolutionHost),
+        }
+        const moduleResolutionHost: ts.ModuleResolutionHost = {
+            fileExists: (fileName) =>
+                fileName === assets.path ||
+                (isShadow(fileName) ? exists(sourceOf(fileName)) : ts.sys.fileExists(fileName)),
+            readFile: (fileName) =>
+                fileName === assets.path
+                    ? assets.content
+                    : isShadow(fileName)
+                      ? shadowText(sourceOf(fileName))
+                      : ts.sys.readFile(fileName),
+        }
+        const host: ts.LanguageServiceHost = {
+            getScriptFileNames: () => [assets.path, ...fileNames, ...shadowNames()],
+            getScriptVersion: (fileName) => String(versions.get(fileName) ?? 0),
+            getScriptSnapshot: (fileName) => {
+                if (fileName === assets.path) {
+                    return ts.ScriptSnapshot.fromString(assets.content)
+                }
+                if (isShadow(fileName)) {
+                    return exists(sourceOf(fileName))
+                        ? ts.ScriptSnapshot.fromString(shadowText(sourceOf(fileName)))
+                        : undefined
+                }
+                const text = ts.sys.readFile(fileName)
+                return text === undefined ? undefined : ts.ScriptSnapshot.fromString(text)
+            },
+            getCurrentDirectory: () => cwd,
+            getCompilationSettings: () => options,
+            getDefaultLibFileName: (compilerOptions) => ts.getDefaultLibFilePath(compilerOptions),
+            fileExists: moduleResolutionHost.fileExists,
+            readFile: moduleResolutionHost.readFile,
+            readDirectory: ts.sys.readDirectory,
+            directoryExists: ts.sys.directoryExists,
+            getDirectories: ts.sys.getDirectories,
+            resolveModuleNames: resolveAbideImports(options, moduleResolutionHost),
+        }
+        return {
+            service: ts.createLanguageService(host, ts.createDocumentRegistry()),
+            shadows,
+            parseErrors,
+            shadowText,
+        }
+    }
+
+    const verbatim = buildService((source, abidePath) =>
+        compileShadow(source, propsTypeOf(abidePath)),
+    )
+    /* The wrapped shadow's peek-wrap is type-directed: it asks the verbatim program which
+       sub-expressions are async. `getProgram()` reflects the shared overlays/versions, so the
+       classifier tracks unsaved edits; fail-open to `undefined` (verbatim shadow) if unavailable. */
+    const classifierFor = (abidePath: string): InterpolationClassifier | undefined => {
+        const program = verbatim.service.getProgram()
+        return program === undefined
+            ? undefined
+            : shadowInterpolationClassifier(program, verbatim.shadows, abidePath)
     }
-    const service = ts.createLanguageService(host, ts.createDocumentRegistry())
+    const main = buildService((source, abidePath) =>
+        compileShadow(source, propsTypeOf(abidePath), classifierFor(abidePath)),
+    )
+    const { service, shadows, parseErrors, shadowText } = main
 
     const bump = (abidePath: string): void => {
         const fileName = suffixed(abidePath)
@@ -178,6 +204,12 @@ export function createShadowLanguageService(cwd: string): ShadowLanguageService
                 ]
             }
             const mappings = shadows.get(abidePath)?.mappings ?? []
+            /* The shadow file + checker + template boundary, for the ADR-0032 bare-async-read
+               suppression (mirrors `collectAbideDiagnostics` so the editor and CLI agree). */
+            const shadowFile = service.getProgram()?.getSourceFile(fileName)
+            const checker = service.getProgram()?.getTypeChecker()
+            const source = overlays.get(abidePath) ?? ts.sys.readFile(abidePath) ?? ''
+            const templateStart = templateStartOffset(source)
             return raw.flatMap((diagnostic) => {
                 if (diagnostic.start === undefined) {
                     return []
@@ -190,6 +222,22 @@ export function createShadowLanguageService(cwd: string): ShadowLanguageService
                 if (located === undefined) {
                     return []
                 }
+                /* Drop the spurious "property missing on Promise" / "condition always defined" a
+                   bare async read provokes — the runtime peeks the resolved value (ADR-0032). */
+                if (
+                    shadowFile !== undefined &&
+                    checker !== undefined &&
+                    located.start >= templateStart &&
+                    isSpuriousAsyncReadDiagnostic(
+                        shadowFile,
+                        checker,
+                        diagnostic.code,
+                        diagnostic.start,
+                        diagnostic.length ?? 0,
+                    )
+                ) {
+                    return []
+                }
                 return [
                     {
                         file: abidePath,

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

@@ -2,12 +2,15 @@ import { resolve } from 'node:path'
 import ts from 'typescript'
 import { messageFromError } from '../../shared/messageFromError.ts'
 import { assetModulesFile } from './assetModulesFile.ts'
+import { cachedSourceFile } from './cachedSourceFile.ts'
 import { compileShadow } from './compileShadow.ts'
 import { loadShadowTsConfig } from './loadShadowTsConfig.ts'
 import { pagePropsType } from './pagePropsType.ts'
 import { resolveAbideImports } from './resolveAbideImports.ts'
 import { shadowNaming } from './shadowNaming.ts'
+import { sourceFileOptionsSignature } from './sourceFileOptionsSignature.ts'
 import type { CompiledShadow } from './types/CompiledShadow.ts'
+import type { InterpolationClassifier } from './types/InterpolationClassifier.ts'
 
 const { suffixed, isShadow, sourceOf } = shadowNaming
 
@@ -29,7 +32,16 @@ the project's tsconfig (lib/paths/baseUrl) so the shadows type-check against the
 same world the app does; `noUnusedLocals`/`noUnusedParameters` are forced off
 because the shadow legitimately declares scope bindings a template may not read.
 */
-export function createShadowProgram(cwd: string, abidePaths?: string[]): ShadowProgram {
+export function createShadowProgram(
+    cwd: string,
+    abidePaths?: string[],
+    /* Per-file interpolation classifier (ADR-0032). When provided, each shadow peek-wraps its async
+       sub-expressions so they type-check against the RESOLVED value; it must be backed by a SEPARATE
+       verbatim program (see `checkAbide`), since a classifier reading these same wrapped shadows
+       would be circular. Absent ⇒ verbatim shadows (the classifier-source pass, and any caller that
+       doesn't need the peek types). */
+    classifierFor?: (abidePath: string) => InterpolationClassifier | undefined,
+): ShadowProgram {
     const { options, fileNames } = loadShadowTsConfig(cwd)
     const shadows = new Map<string, CompiledShadow>()
     const parseErrors = new Map<string, string>()
@@ -47,7 +59,11 @@ export function createShadowProgram(cwd: string, abidePaths?: string[]): ShadowP
     const shadowText = (abidePath: string): string => {
         const source = ts.sys.readFile(abidePath) ?? ''
         try {
-            const compiled = compileShadow(source, pagePropsType(abidePath))
+            const compiled = compileShadow(
+                source,
+                pagePropsType(abidePath),
+                classifierFor?.(abidePath),
+            )
             shadows.set(abidePath, compiled)
             parseErrors.delete(abidePath)
             return compiled.code
@@ -61,22 +77,35 @@ export function createShadowProgram(cwd: string, abidePaths?: string[]): ShadowP
     /* Ambient declarations for bundler-handled asset imports (`*.css`, …). */
     const assets = assetModulesFile(cwd)
 
+    /* The parse/bind-affecting options are identical for every source in a program, so compute
+       the cache signature once and reuse it for every file (see `cachedSourceFile`). */
+    const signature = sourceFileOptionsSignature(options)
+
     const host = ts.createCompilerHost(options, true)
     const originalGetSourceFile = host.getSourceFile.bind(host)
     host.getSourceFile = (fileName, languageVersionOrOptions, onError, shouldCreate) => {
         if (fileName === assets.path) {
-            return ts.createSourceFile(fileName, assets.content, languageVersionOrOptions, true)
+            return cachedSourceFile(fileName, assets.content, languageVersionOrOptions, signature)
         }
         if (isShadow(fileName)) {
-            return ts.createSourceFile(
+            /* `shadowText` populates the per-program `shadows`/`parseErrors` maps as a side effect,
+               so it must run on every call — only its expensive TS parse is memoised by `cachedSourceFile`. */
+            return cachedSourceFile(
                 fileName,
                 shadowText(sourceOf(fileName)),
                 languageVersionOrOptions,
-                true,
+                signature,
                 ts.ScriptKind.TS,
             )
         }
-        return originalGetSourceFile(fileName, languageVersionOrOptions, onError, shouldCreate)
+        /* Real `.ts`/`.d.ts` inputs (the ~3MB of default libs plus resolved dependencies) — read the
+           text and reuse the parsed file across programs when it is byte-identical. Fall back to the
+           default host on a read failure so its missing-file / `onError` handling is preserved. */
+        const text = ts.sys.readFile(fileName)
+        if (text === undefined) {
+            return originalGetSourceFile(fileName, languageVersionOrOptions, onError, shouldCreate)
+        }
+        return cachedSourceFile(fileName, text, languageVersionOrOptions, signature)
     }
     host.fileExists = (fileName) =>
         fileName === assets.path ||