@abide/abide 0.28.0

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

@@ -0,0 +1,36 @@
+import { analyzeComponent } from './analyzeComponent.ts'
+import { generateSSR } from './generateSSR.ts'
+import { SSR_ESCAPE } from './SSR_ESCAPE.ts'
+import { stripEffects } from './stripEffects.ts'
+
+/*
+Compiles a component into the body of a server render function. Runs the shared
+front-end, then the SSR back-end, and returns `{ html, state, awaits }`:
+
+  - `html`  — server-rendered markup (await blocks render their pending shell);
+  - `state` — the document snapshot the client adopts on resume;
+  - `awaits` — pending await blocks (id + promise + resolved/error renderers) that
+    `renderToStream` flushes out of order; empty for a fully synchronous component.
+
+Effects are stripped — they are client lifecycle and emit no HTML, so the server
+render is a snapshot of the markup before any effect runs.
+
+Runs with `doc`/`state`/`derived`/`effect`/`nextBlockId`/`enterRenderPass`/
+`exitRenderPass` in scope and defines `model`. The body is bracketed by a render
+pass so the outermost render resets the block-id counter and an inlined child
+render continues it — keeping await/try ids unique and aligned with the client.
+*/
+export function compileSSR(source: string, isLayout = false, scopeSeed?: string): string {
+    const { script, stateNames, derivedNames, nodes } = analyzeComponent(source, scopeSeed)
+    const ssr = generateSSR(nodes, stateNames, derivedNames, isLayout)
+    /* No `<style>` in the markup — the scoped CSS is bundled into the entry stylesheet
+       the shell links (see `abideUiPlugin`), so SSR output is styled by that sheet. The
+       elements still carry their `data-a-…` scopes via `generateSSR`. */
+    /* `typeof model` guards a component with no reactive state (a pure-async or
+       static component declares no `model`); its snapshot is then empty. */
+    return (
+        `enterRenderPass();\ntry {\n${stripEffects(script)}\n${SSR_ESCAPE}\nconst $out = [];\nconst $awaits = [];\n${ssr}` +
+        `return { html: $out.join(''), state: (typeof model !== 'undefined' ? model.snapshot() : {}), awaits: $awaits };\n` +
+        `} finally { exitRenderPass(); }`
+    )
+}

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

@@ -0,0 +1,352 @@
+import ts from 'typescript'
+import { ABIDE_PACKAGE_NAME } from '../../shared/ABIDE_PACKAGE_NAME.ts'
+import { parseTemplate } from './parseTemplate.ts'
+import type { CompiledShadow, ShadowMapping } from './types/CompiledShadow.ts'
+import type { TemplateNode } from './types/TemplateNode.ts'
+
+/*
+Framework callables the `.abide` loader injects into a component's scope, imported
+into the shadow with their real types so author calls (`effect`, `html`, …)
+type-check. `state`/`derived` are imported too as a fallback for stray uses; their
+declarations are rewritten to value types so the import is normally unused (fine —
+the shadow program disables noUnusedLocals). `prop` has no runtime export, so it
+never appears here — every `prop()` declaration is rewritten away. `$props` is the
+legacy untyped prop bag (pre-`prop()` sugar) made available raw.
+*/
+const SHADOW_PREAMBLE = `import { state } from '${ABIDE_PACKAGE_NAME}/ui/state'
+import { derived } from '${ABIDE_PACKAGE_NAME}/ui/derived'
+import { effect } from '${ABIDE_PACKAGE_NAME}/ui/effect'
+import { doc } from '${ABIDE_PACKAGE_NAME}/ui/doc'
+import { html } from '${ABIDE_PACKAGE_NAME}/shared/html'
+import { snippet } from '${ABIDE_PACKAGE_NAME}/shared/snippet'
+declare const $props: Record<string, (() => unknown) | undefined>
+void [state, derived, effect, doc, html, snippet]
+`
+
+/*
+Compiles a `.abide` component into its type-checking shadow — a synthetic TS
+module that reconstructs the author scope with value types and references every
+template expression in a checkable position (see ADR-0010). The shadow is never
+executed; it exists only so `tsc`/the language service can type-check template
+expressions and child-component props, with diagnostics mapped back through the
+returned segments.
+
+The script's signal surface is rewritten to value types:
+  let count = state(0)            →  let count = (0)
+  const total = derived(() => …)  →  const total = (() => …)()
+  let title = prop<string>('t')   →  Props field + `let title = props['t']`
+Everything else (functions, plain consts, imports) is emitted verbatim, so
+expressions inside it (e.g. a derived's compute body) are checked and mapped too.
+*/
+export function compileShadow(source: string): CompiledShadow {
+    const builder = createBuilder()
+    const leadingScript = source.match(/^\s*<script[^>]*>([\s\S]*?)<\/script>/)
+    const scriptBody = leadingScript?.[1] ?? ''
+    /* Body starts just past the opening `<script …>`; template just past `</script>`. */
+    const scriptStart = leadingScript ? source.indexOf('>', leadingScript.index) + 1 : 0
+    const templateStart = leadingScript ? (leadingScript.index ?? 0) + leadingScript[0].length : 0
+
+    const { imports, scope, props } = analyzeScript(scriptBody, scriptStart)
+    builder.raw(SHADOW_PREAMBLE)
+    for (const line of imports) {
+        builder.flush(line)
+    }
+    builder.raw(`interface __Props {\n${props.join('\n')}\n}\n`)
+    /* async so `await` blocks are legal; never executed, so the return is void. */
+    builder.raw('export default async function (props: __Props): Promise<void> {\n')
+    /* Reference props so an all-optional bag with no reads doesn't read as unused. */
+    builder.raw('void props;\n')
+    for (const line of scope) {
+        builder.flush(line)
+    }
+    for (const node of parseTemplate(source.slice(templateStart), templateStart).nodes) {
+        emitNode(node, builder)
+    }
+    builder.raw('}\n')
+    return builder.result()
+}
+
+/* The shadow text builder: `raw` appends synthesised scaffolding (no mapping),
+   `expr` appends an inline parenthesised source span `(code)` and records its
+   segment, `stmt` wraps one as a standalone statement, `flush` appends a
+   pre-assembled scope line carrying its own embedded segments. */
+type Builder = {
+    raw: (text: string) => void
+    expr: (code: string, sourceLoc: number | undefined) => void
+    stmt: (code: string, sourceLoc: number | undefined) => void
+    flush: (line: ScopeLine) => void
+    result: () => CompiledShadow
+}
+
+/* A reconstructed scope statement plus the segments embedded inside it (the parts
+   emitted verbatim from the original script), offset-relative to the line start. */
+type ScopeLine = { text: string; segments: ShadowMapping[] }
+
+function createBuilder(): Builder {
+    let code = ''
+    const mappings: ShadowMapping[] = []
+    const builder: Builder = {
+        raw(text) {
+            code += text
+        },
+        expr(exprCode, sourceLoc) {
+            code += '('
+            if (sourceLoc !== undefined) {
+                mappings.push({
+                    shadowStart: code.length,
+                    sourceStart: sourceLoc,
+                    length: exprCode.length,
+                })
+            }
+            code += `${exprCode})`
+        },
+        stmt(exprCode, sourceLoc) {
+            code += ';'
+            builder.expr(exprCode, sourceLoc)
+            code += ';\n'
+        },
+        flush(line) {
+            const base = code.length
+            for (const segment of line.segments) {
+                mappings.push({ ...segment, shadowStart: base + segment.shadowStart })
+            }
+            code += `${line.text}\n`
+        },
+        result: () => ({ code, mappings }),
+    }
+    return builder
+}
+
+type ScriptAnalysis = { imports: ScopeLine[]; scope: ScopeLine[]; props: string[] }
+
+/* Walks the leading `<script>` and produces the shadow's module imports, the
+   value-typed scope lines, and the Props interface fields. `scriptStart` is the
+   body's absolute offset in the source, so verbatim spans map back exactly. */
+function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis {
+    const imports: ScopeLine[] = []
+    const scope: ScopeLine[] = []
+    const props: string[] = []
+    if (scriptBody.trim() === '') {
+        return { imports, scope, props }
+    }
+    const file = ts.createSourceFile('script.ts', scriptBody, ts.ScriptTarget.Latest, true)
+    /* A verbatim span: original text + the segment mapping it back, relative to the
+       line start (the caller rebases shadowStart onto the running shadow length). */
+    const span = (node: ts.Node, prefixLength: number): ScopeLine['segments'][number] => ({
+        shadowStart: prefixLength,
+        sourceStart: scriptStart + node.getStart(file),
+        length: node.getEnd() - node.getStart(file),
+    })
+    const verbatim = (node: ts.Node): string => scriptBody.slice(node.getStart(file), node.getEnd())
+
+    for (const statement of file.statements) {
+        if (ts.isImportDeclaration(statement)) {
+            /* Emit verbatim with a span so hover/go-to resolve on the imported names. */
+            imports.push({ text: verbatim(statement), segments: [span(statement, 0)] })
+            continue
+        }
+        const reactive = reactiveDeclarations(statement)
+        if (reactive === undefined) {
+            /* Plain statement (function, const, expression) — emit verbatim, mapped. */
+            scope.push({ text: verbatim(statement), segments: [span(statement, 0)] })
+            continue
+        }
+        for (const declaration of reactive) {
+            scope.push(scopeLineFor(declaration, props, verbatim, span))
+        }
+    }
+    return { imports, scope, props }
+}
+
+/* The `state`/`derived`/`prop` declarations in a variable statement, or undefined
+   if it isn't one declaring them (so the caller emits it verbatim). A statement
+   mixing reactive and plain declarations is rare; treated as all-verbatim. */
+function reactiveDeclarations(statement: ts.Statement): ts.VariableDeclaration[] | undefined {
+    if (!ts.isVariableStatement(statement)) {
+        return undefined
+    }
+    const declarations = statement.declarationList.declarations
+    const reactive = declarations.filter((declaration) => signalCallee(declaration) !== undefined)
+    return reactive.length === declarations.length && reactive.length > 0 ? reactive : undefined
+}
+
+/* The callee name of a `NAME = state(...)` / `derived(...)` / `prop(...)` decl. */
+function signalCallee(declaration: ts.VariableDeclaration): string | undefined {
+    const initializer = declaration.initializer
+    if (
+        initializer !== undefined &&
+        ts.isCallExpression(initializer) &&
+        ts.isIdentifier(initializer.expression) &&
+        ['state', 'derived', 'prop'].includes(initializer.expression.text)
+    ) {
+        return initializer.expression.text
+    }
+    return undefined
+}
+
+/* Builds one scope line for a reactive declaration, projecting it to its value
+   type. `prop` also contributes a Props field (pushed into `props`). */
+function scopeLineFor(
+    declaration: ts.VariableDeclaration,
+    props: string[],
+    verbatim: (node: ts.Node) => string,
+    span: (node: ts.Node, prefixLength: number) => ShadowMapping,
+): ScopeLine {
+    const name = ts.isIdentifier(declaration.name) ? declaration.name.text : '_'
+    const call = declaration.initializer as ts.CallExpression
+    const callee = (call.expression as ts.Identifier).text
+    if (callee === 'state') {
+        /* state<T>(initial): T is the value type — carry it onto the `let` so an
+           explicit annotation isn't lost to `any`/`any[]` inference of the initial. */
+        const typeNode = call.typeArguments?.[0]
+        const annotation = typeNode === undefined ? '' : `: ${verbatim(typeNode)}`
+        const init = call.arguments[0]
+        if (init === undefined) {
+            return { text: `let ${name}${annotation};`, segments: [] }
+        }
+        const prefix = `let ${name}${annotation} = (`
+        return { text: `${prefix}${verbatim(init)});`, segments: [span(init, prefix.length)] }
+    }
+    if (callee === 'derived') {
+        /* derived<T>(compute): T is the value type — annotate so an explicit
+           argument isn't lost to inference of the compute's return. */
+        const typeNode = call.typeArguments?.[0]
+        const annotation = typeNode === undefined ? '' : `: ${verbatim(typeNode)}`
+        const fn = call.arguments[0]
+        if (fn === undefined) {
+            return { text: `const ${name} = undefined;`, segments: [] }
+        }
+        const prefix = `const ${name}${annotation} = (`
+        return { text: `${prefix}${verbatim(fn)})();`, segments: [span(fn, prefix.length)] }
+    }
+    /* prop<T>('key'): Props field `key[?]: T`, scope binding read from props. */
+    const key = call.arguments[0]
+    const keyText = key !== undefined && ts.isStringLiteralLike(key) ? key.text : name
+    const typeNode = call.typeArguments?.[0]
+    const typeText = typeNode === undefined ? 'unknown' : verbatim(typeNode)
+    const optional = typeNode === undefined || /\bundefined\b/.test(typeText)
+    props.push(`    ${JSON.stringify(keyText)}${optional ? '?' : ''}: ${typeText}`)
+    return { text: `let ${name} = props[${JSON.stringify(keyText)}];`, segments: [] }
+}
+
+/* Emits a template node's expressions into the shadow's `if (false) {…}` render
+   body. Control flow introduces its binding so children type-check against it;
+   every expression is referenced in a statement so a type error surfaces and maps. */
+function emitNode(node: TemplateNode, builder: Builder): void {
+    switch (node.kind) {
+        case 'text':
+            for (const part of node.parts) {
+                if (part.kind === 'expression') {
+                    builder.stmt(part.code, part.loc)
+                }
+            }
+            return
+        case 'element':
+            for (const attr of node.attrs) {
+                if (attr.kind !== 'static') {
+                    builder.stmt(attr.code, attr.loc)
+                }
+            }
+            node.children.forEach((child) => {
+                emitNode(child, builder)
+            })
+            return
+        case 'component': {
+            /* Check each prop against the child's declared type. The imported tag
+               resolves (via the shadow host) to the child's `(props: Props) => …`
+               default, so `Parameters<typeof Child>[0]["name"]` is that prop's type;
+               assigning the mapped value to it lands a mismatch diagnostic on the
+               offending expression (an annotated target reports the error on the RHS,
+               unlike an object literal which reports it on the key). */
+            for (const prop of node.props) {
+                builder.raw(
+                    `((__prop: Parameters<typeof ${node.name}>[0][${JSON.stringify(prop.name)}]) => {})(`,
+                )
+                builder.expr(prop.code, prop.loc)
+                builder.raw(');\n')
+            }
+            node.children.forEach((child) => {
+                emitNode(child, builder)
+            })
+            return
+        }
+        case 'if':
+            builder.raw('if ')
+            builder.expr(node.condition, node.loc)
+            builder.raw(' {\n')
+            node.children.forEach((child) => {
+                emitNode(child, builder)
+            })
+            builder.raw('}\n')
+            return
+        case 'each':
+            builder.raw(`for (const ${node.as} of `)
+            builder.expr(node.items, node.loc)
+            builder.raw(') {\n')
+            if (node.key !== undefined) {
+                builder.raw(`void (${node.key});\n`)
+            }
+            node.children.forEach((child) => {
+                emitNode(child, builder)
+            })
+            builder.raw('}\n')
+            return
+        case 'await':
+            builder.raw('{\n')
+            builder.raw(node.as !== undefined ? `const ${node.as} = await ` : 'await ')
+            builder.expr(node.promise, node.loc)
+            builder.raw(';\n')
+            node.children.forEach((child) => {
+                emitNode(child, builder)
+            })
+            builder.raw('}\n')
+            return
+        case 'switch':
+            builder.stmt(node.subject, node.loc)
+            node.children.forEach((child) => {
+                emitNode(child, builder)
+            })
+            return
+        case 'case':
+            if (node.match !== undefined) {
+                builder.stmt(node.match, node.loc)
+            }
+            node.children.forEach((child) => {
+                emitNode(child, builder)
+            })
+            return
+        case 'branch':
+            /* then/catch bind the resolved value / error as `any` so children check. */
+            builder.raw('{\n')
+            if (node.as !== undefined) {
+                builder.raw(`const ${node.as} = undefined as any;\n`)
+            }
+            node.children.forEach((child) => {
+                emitNode(child, builder)
+            })
+            builder.raw('}\n')
+            return
+        case 'try':
+            builder.raw('{\n')
+            node.children.forEach((child) => {
+                emitNode(child, builder)
+            })
+            builder.raw('}\n')
+            return
+        case 'snippet':
+            builder.raw(`const ${node.name} = (${node.params ?? ''}) => {\n`)
+            node.children.forEach((child) => {
+                emitNode(child, builder)
+            })
+            builder.raw('};\n')
+            return
+        case 'script':
+            /* A scoped reactive `<script>` block — its body is author TS; emit it so
+               its references check. Not yet position-mapped (rare). */
+            builder.raw(`{\n${node.code}\n}\n`)
+            return
+        case 'style':
+            /* CSS, not TypeScript — nothing for the shadow to type-check. */
+            return
+    }
+}

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

@@ -0,0 +1,197 @@
+import { resolve } from 'node:path'
+import ts from 'typescript'
+import { assetModulesFile } from './assetModulesFile.ts'
+import { compileShadow } from './compileShadow.ts'
+import { loadShadowTsConfig } from './loadShadowTsConfig.ts'
+import { remapShadowDiagnostic } from './remapShadowDiagnostic.ts'
+import { resolveAbideImports } from './resolveAbideImports.ts'
+import { shadowNaming } from './shadowNaming.ts'
+import { sourceToShadowOffset } from './sourceToShadowOffset.ts'
+import type { AbideDiagnostic } from './types/AbideDiagnostic.ts'
+import type { CompiledShadow } from './types/CompiledShadow.ts'
+
+const { suffixed, isShadow, sourceOf } = shadowNaming
+
+/* Hover quick-info for a source position: TypeScript's signature line and doc
+   comment, with the covered span mapped back onto the `.abide` source. */
+export type ShadowQuickInfo = { text: string; documentation: string; start: number; length: number }
+
+export type ShadowLanguageService = {
+    /* Record/replace an open document's in-memory text (overrides disk). */
+    update: (abidePath: string, text: string) => void
+    /* Forget an open document; subsequent reads fall back to disk. */
+    close: (abidePath: string) => void
+    /* Current diagnostics for one component, mapped onto its source. */
+    diagnostics: (abidePath: string) => AbideDiagnostic[]
+    /* Hover info at a source offset, or undefined if the offset isn't a checked
+       expression (markup, whitespace) or TypeScript has nothing to report. */
+    quickInfo: (abidePath: string, sourceOffset: number) => ShadowQuickInfo | undefined
+}
+
+/*
+An incremental `ts.LanguageService` over the shadow world, for the LSP. Open
+documents are held as in-memory overlays that override disk, so diagnostics
+reflect unsaved edits; every other file (real `.ts`, unopened `.abide`) reads from
+disk. Shares the shadow compiler, module resolver, and tsconfig with the one-shot
+check Program — the editor and CLI report identically.
+*/
+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>()
+
+    /* Ambient declarations for bundler-handled asset imports (`*.css`, …). */
+    const assets = assetModulesFile(cwd)
+
+    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. */
+    const shadowText = (abidePath: string): string => {
+        const source = overlays.get(abidePath) ?? ts.sys.readFile(abidePath) ?? ''
+        try {
+            const compiled = compileShadow(source)
+            shadows.set(abidePath, compiled)
+            parseErrors.delete(abidePath)
+            return compiled.code
+        } catch (error) {
+            shadows.set(abidePath, { code: '', mappings: [] })
+            parseErrors.set(abidePath, error instanceof Error ? error.message : String(error))
+            return 'export default function (): void {}\n'
+        }
+    }
+
+    /* 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 })]
+            .filter((relative) => !relative.includes('node_modules'))
+            .map((relative) => resolve(cwd, relative))
+        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)
+            }
+            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),
+    }
+    const service = ts.createLanguageService(host, ts.createDocumentRegistry())
+
+    const bump = (abidePath: string): void => {
+        const fileName = suffixed(abidePath)
+        versions.set(fileName, (versions.get(fileName) ?? 0) + 1)
+    }
+
+    return {
+        update(abidePath, text) {
+            overlays.set(abidePath, text)
+            bump(abidePath)
+        },
+        close(abidePath) {
+            overlays.delete(abidePath)
+            bump(abidePath)
+        },
+        diagnostics(abidePath) {
+            const fileName = suffixed(abidePath)
+            /* Fetching diagnostics drives getScriptSnapshot → shadowText, so the
+               shadows/parseErrors caches are current before we read them. */
+            const raw = [
+                ...service.getSyntacticDiagnostics(fileName),
+                ...service.getSemanticDiagnostics(fileName),
+            ]
+            const parseError = parseErrors.get(abidePath)
+            if (parseError !== undefined) {
+                return [
+                    {
+                        file: abidePath,
+                        start: 0,
+                        length: 0,
+                        message: parseError,
+                        category: ts.DiagnosticCategory.Error,
+                    },
+                ]
+            }
+            const mappings = shadows.get(abidePath)?.mappings ?? []
+            return raw.flatMap((diagnostic) => {
+                if (diagnostic.start === undefined) {
+                    return []
+                }
+                const located = remapShadowDiagnostic(
+                    mappings,
+                    diagnostic.start,
+                    diagnostic.length ?? 0,
+                )
+                if (located === undefined) {
+                    return []
+                }
+                return [
+                    {
+                        file: abidePath,
+                        start: located.start,
+                        length: located.length,
+                        message: ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'),
+                        category: diagnostic.category,
+                    },
+                ]
+            })
+        },
+        quickInfo(abidePath, sourceOffset) {
+            const fileName = suffixed(abidePath)
+            /* Compile the shadow first so its mappings are current before we
+               translate the source offset into shadow coordinates. */
+            shadowText(abidePath)
+            const mappings = shadows.get(abidePath)?.mappings ?? []
+            const shadowOffset = sourceToShadowOffset(mappings, sourceOffset)
+            if (shadowOffset === undefined) {
+                return undefined
+            }
+            const info = service.getQuickInfoAtPosition(fileName, shadowOffset)
+            if (info === undefined) {
+                return undefined
+            }
+            /* The reported span is in shadow coordinates; map it back so the editor
+               highlights the matching source. Falls back to the hovered offset. */
+            const span = remapShadowDiagnostic(mappings, info.textSpan.start, info.textSpan.length)
+            return {
+                text: ts.displayPartsToString(info.displayParts),
+                documentation: ts.displayPartsToString(info.documentation),
+                start: span?.start ?? sourceOffset,
+                length: span?.length ?? 1,
+            }
+        },
+    }
+}

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

@@ -0,0 +1,96 @@
+import { resolve } from 'node:path'
+import ts from 'typescript'
+import { assetModulesFile } from './assetModulesFile.ts'
+import { compileShadow } from './compileShadow.ts'
+import { loadShadowTsConfig } from './loadShadowTsConfig.ts'
+import { resolveAbideImports } from './resolveAbideImports.ts'
+import { shadowNaming } from './shadowNaming.ts'
+import type { CompiledShadow } from './types/CompiledShadow.ts'
+
+const { suffixed, isShadow, sourceOf } = shadowNaming
+
+export type ShadowProgram = {
+    program: ts.Program
+    /* Compiled shadow (code + mappings) per `.abide` path, populated as the host
+       materialises each source file; the diagnostic remapper reads the mappings. */
+    shadows: Map<string, CompiledShadow>
+    /* Files whose template failed to parse — surfaced as a diagnostic at offset 0. */
+    parseErrors: Map<string, string>
+    abidePaths: string[]
+}
+
+/*
+Builds a `ts.Program` over the project's real `.ts` files plus a virtual shadow
+`.ts` for every `.abide` component, behind a CompilerHost that serves shadow text
+for any `*.abide.ts` name and resolves `.abide` imports to their shadows. Reuses
+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 {
+    const { options, fileNames } = loadShadowTsConfig(cwd)
+    const shadows = new Map<string, CompiledShadow>()
+    const parseErrors = new Map<string, string>()
+    /* The components to root the program at — caller-supplied (one project's files)
+       or, by default, every `.abide` under `cwd`. Imported components resolve on
+       demand through the host, so an explicit subset still type-checks fully. */
+    const rootAbidePaths =
+        abidePaths ??
+        [...new Bun.Glob('**/*.abide').scanSync({ cwd, onlyFiles: true })]
+            .filter((relative) => !relative.includes('node_modules'))
+            .map((relative) => resolve(cwd, relative))
+
+    /* Compiles (and caches) a `.abide` file's shadow; a template parse error yields
+       a minimal valid module and a recorded message so the program still builds. */
+    const shadowText = (abidePath: string): string => {
+        const source = ts.sys.readFile(abidePath) ?? ''
+        try {
+            const compiled = compileShadow(source)
+            shadows.set(abidePath, compiled)
+            parseErrors.delete(abidePath)
+            return compiled.code
+        } catch (error) {
+            shadows.set(abidePath, { code: '', mappings: [] })
+            parseErrors.set(abidePath, error instanceof Error ? error.message : String(error))
+            return 'export default function (): void {}\n'
+        }
+    }
+
+    /* Ambient declarations for bundler-handled asset imports (`*.css`, …). */
+    const assets = assetModulesFile(cwd)
+
+    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)
+        }
+        if (isShadow(fileName)) {
+            return ts.createSourceFile(
+                fileName,
+                shadowText(sourceOf(fileName)),
+                languageVersionOrOptions,
+                true,
+                ts.ScriptKind.TS,
+            )
+        }
+        return originalGetSourceFile(fileName, languageVersionOrOptions, onError, shouldCreate)
+    }
+    host.fileExists = (fileName) =>
+        fileName === assets.path ||
+        (isShadow(fileName) ? ts.sys.fileExists(sourceOf(fileName)) : ts.sys.fileExists(fileName))
+    host.readFile = (fileName) => {
+        if (fileName === assets.path) {
+            return assets.content
+        }
+        return isShadow(fileName) ? shadowText(sourceOf(fileName)) : ts.sys.readFile(fileName)
+    }
+    host.resolveModuleNames = resolveAbideImports(options, host)
+
+    const program = ts.createProgram({
+        rootNames: [assets.path, ...fileNames, ...rootAbidePaths.map((path) => suffixed(path))],
+        options,
+        host,
+    })
+    return { program, shadows, parseErrors, abidePaths: rootAbidePaths }
+}