@abide/abide 0.44.0 → 0.44.1

package/src/lib/shared/setRequestScopeResolver.ts

@@ -1,6 +1,4 @@
-import { requestScopeSlot } from './requestScopeSlot.ts'
-import type { RequestScopeInfo } from './types/RequestScopeInfo.ts'
+import { requestScopeResolver } from './requestScopeResolver.ts'
 
-export function setRequestScopeResolver(fn: () => RequestScopeInfo | undefined): void {
-    requestScopeSlot.resolver = fn
-}
+// Registers the runtime's request-scope resolver. Called once per side at boot.
+export const setRequestScopeResolver = requestScopeResolver.set

package/src/lib/shared/types/DebugGate.ts

@@ -0,0 +1,10 @@
+/*
+The two questions a DEBUG string answers for one channel name. `enabled` gates a
+diagnostic channel (inclusion, with exclusions winning); `negated` is the off
+switch for always-on channels (a `-name` pattern silencing the app's own or
+abide's framework voice). Returned by debugGate, already bound to one env value.
+*/
+export type DebugGate = {
+    enabled(name: string): boolean
+    negated(name: string): boolean
+}

package/src/lib/shared/types/ResolverSlot.ts

@@ -0,0 +1,10 @@
+/*
+The mutable cell a runtime entry registers its resolver into, plus the single
+lazy/value fallback used when no resolver is registered. createServer and
+startClient install side-specific resolvers; isolated tests poke `.resolver` /
+`.fallback` directly, so both fields stay public and mutable.
+*/
+export type ResolverSlot<T> = {
+    resolver: (() => T | undefined) | undefined
+    fallback: T | undefined
+}

package/src/lib/shared/writeDts.ts

@@ -8,5 +8,12 @@ src tsconfig include picks up), wrapping `body` in the shared banner + the
 differ only in `body`, so the envelope lives here.
 */
 export async function writeDts(cwd: string, name: string, body: string): Promise<void> {
-    await Bun.write(`${cwd}/src/.abide/${name}.d.ts`, `${DTS_BANNER}\n${body}\n\nexport {}\n`)
+    const next = `${DTS_BANNER}\n${body}\n\nexport {}\n`
+    const file = Bun.file(`${cwd}/src/.abide/${name}.d.ts`)
+    // Skip the write when byte-identical — an unchanged rebuild (the common case)
+    // otherwise bumps mtime every save, forcing the editor's TS server to re-typecheck.
+    if ((await file.exists()) && (await file.text()) === next) {
+        return
+    }
+    await Bun.write(file, next)
 }

package/src/lib/shared/writePublicAssetsDts.ts

@@ -1,3 +1,4 @@
+import { augmentModule } from './augmentModule.ts'
 import { writeDts } from './writeDts.ts'
 
 /*
@@ -19,13 +20,8 @@ export async function writePublicAssetsDts({
     importName: string
 }): Promise<void> {
     const entries = publicFiles
-        .map((file) => `        ${JSON.stringify(`/${file}`)}: true`)
-        .toSorted()
-        .join('\n')
-    const body = `declare module '${importName}/shared/url' {
-    interface PublicAssets {
-${entries}
-    }
-}`
-    await writeDts(cwd, 'publicAssets', body)
+        .map((file): [string, string] => [`/${file}`, 'true'])
+        .toSorted(([a], [b]) => (JSON.stringify(a) < JSON.stringify(b) ? -1 : 1))
+    const module = augmentModule(`${importName}/shared/url`, 'PublicAssets', entries)
+    await writeDts(cwd, 'publicAssets', module)
 }

package/src/lib/shared/writeRoutesDts.ts

@@ -1,3 +1,4 @@
+import { augmentModule } from './augmentModule.ts'
 import { pageUrlForFile } from './pageUrlForFile.ts'
 import { routeParamsShape } from './routeParamsShape.ts'
 import { writeDts } from './writeDts.ts'
@@ -25,21 +26,16 @@ export async function writeRoutesDts({
     const routes = pageFiles
         .map((file) => ({ route: pageUrlForFile(file) }))
         .toSorted((a, b) => a.route.localeCompare(b.route))
-    const entries = routes
-        .map(({ route }) => `        ${JSON.stringify(route)}: ${routeParamsShape(route)}`)
-        .join('\n')
+    const routesModule = augmentModule(
+        `${importName}/shared/page`,
+        'Routes',
+        routes.map(({ route }): [string, string] => [route, routeParamsShape(route)]),
+    )
     /* Keys-only mirror for url()'s autocomplete (values unused — PathParams derives the shape). */
-    const urlKeys = routes.map(({ route }) => `        ${JSON.stringify(route)}: true`).join('\n')
-    const body = `declare module '${importName}/shared/page' {
-    interface Routes {
-${entries}
-    }
-}
-
-declare module '${importName}/shared/url' {
-    interface PageRoutes {
-${urlKeys}
-    }
-}`
-    await writeDts(cwd, 'routes', body)
+    const urlModule = augmentModule(
+        `${importName}/shared/url`,
+        'PageRoutes',
+        routes.map(({ route }): [string, string] => [route, 'true']),
+    )
+    await writeDts(cwd, 'routes', `${routesModule}\n\n${urlModule}`)
 }

package/src/lib/shared/writeRpcDts.ts

@@ -1,6 +1,8 @@
+import { augmentModule } from './augmentModule.ts'
 import { carriesBodyArgs } from './carriesBodyArgs.ts'
 import { detectRpcMethod } from './detectRpcMethod.ts'
 import { fileStem } from './fileStem.ts'
+import { RPC_ARGS_TYPE } from './RPC_ARGS_TYPE.ts'
 import { rpcUrlForFile } from './rpcUrlForFile.ts'
 import { writeDts } from './writeDts.ts'
 
@@ -26,24 +28,23 @@ export async function writeRpcDts({
     rpcFiles: string[]
     importName: string
 }): Promise<void> {
-    const lines = await Promise.all(
-        rpcFiles.map(async (file) => {
+    const pairs = await Promise.all(
+        rpcFiles.map(async (file): Promise<[string, string] | undefined> => {
             const method = detectRpcMethod(await Bun.file(`${rpcDir}/${file}`).text())
             // A body rpc's args can't ride a URL — leave it out of the url() rpc map.
             if (!method || carriesBodyArgs(method)) {
                 return undefined
             }
             const importPath = `../server/rpc/${file}`
-            return `        ${JSON.stringify(rpcUrlForFile(file))}: RpcArgs<typeof import(${JSON.stringify(importPath)}).${fileStem(file)}>`
+            return [
+                rpcUrlForFile(file),
+                `RpcArgs<typeof import(${JSON.stringify(importPath)}).${fileStem(file)}>`,
+            ]
         }),
     )
-    const entries = lines.filter((line) => line !== undefined).toSorted()
-    const body = `type RpcArgs<Fn> = Fn extends (args: infer Args) => unknown ? Exclude<Args, FormData> : never
-
-declare module '${importName}/shared/url' {
-    interface RpcRoutes {
-${entries.join('\n')}
-    }
-}`
-    await writeDts(cwd, 'rpc', body)
+    const entries = pairs
+        .filter((pair) => pair !== undefined)
+        .toSorted(([a], [b]) => (JSON.stringify(a) < JSON.stringify(b) ? -1 : 1))
+    const module = augmentModule(`${importName}/shared/url`, 'RpcRoutes', entries)
+    await writeDts(cwd, 'rpc', `${RPC_ARGS_TYPE}\n\n${module}`)
 }

package/src/lib/shared/writeTestRpcDts.ts

@@ -1,5 +1,7 @@
+import { augmentModule } from './augmentModule.ts'
 import { commandNameForUrl } from './commandNameForUrl.ts'
 import { fileStem } from './fileStem.ts'
+import { RPC_ARGS_TYPE } from './RPC_ARGS_TYPE.ts'
 import { rpcUrlForFile } from './rpcUrlForFile.ts'
 import { writeDts } from './writeDts.ts'
 
@@ -24,22 +26,20 @@ export async function writeTestRpcDts({
     importName: string
 }): Promise<void> {
     const entries = rpcFiles
-        .map((file) => {
+        .map((file): [string, string] => {
             const name = commandNameForUrl(rpcUrlForFile(file))
             const importPath = `../server/rpc/${file}`
-            return `        ${JSON.stringify(name)}: RpcInvoker<typeof import(${JSON.stringify(importPath)}).${fileStem(file)}>`
+            return [
+                name,
+                `RpcInvoker<typeof import(${JSON.stringify(importPath)}).${fileStem(file)}>`,
+            ]
         })
-        .toSorted()
-    const body = `type RpcArgs<Fn> = Fn extends (args: infer Args) => unknown ? Exclude<Args, FormData> : never
+        .toSorted(([a], [b]) => (JSON.stringify(a) < JSON.stringify(b) ? -1 : 1))
+    const helperTypes = `${RPC_ARGS_TYPE}
 type RpcReturn<Fn> = Fn extends (...args: never[]) => Promise<infer Return> ? Return : never
 type RpcInvoker<Fn> = ((args?: RpcArgs<Fn>) => Promise<RpcReturn<Fn>>) & {
     raw: (args?: RpcArgs<Fn>) => Promise<Response>
-}
-
-declare module '${importName}/test/createTestApp' {
-    interface RpcClient {
-${entries.join('\n')}
-    }
 }`
-    await writeDts(cwd, 'testRpc', body)
+    const module = augmentModule(`${importName}/test/createTestApp`, 'RpcClient', entries)
+    await writeDts(cwd, 'testRpc', `${helperTypes}\n\n${module}`)
 }

package/src/lib/shared/writeTestSocketsDts.ts

@@ -1,3 +1,4 @@
+import { augmentModule } from './augmentModule.ts'
 import { fileStem } from './fileStem.ts'
 import { socketNameForFile } from './socketNameForFile.ts'
 import { writeDts } from './writeDts.ts'
@@ -20,15 +21,14 @@ export async function writeTestSocketsDts({
     importName: string
 }): Promise<void> {
     const entries = socketFiles
-        .map((file) => {
+        .map((file): [string, string] => {
             const importPath = `../server/sockets/${file}`
-            return `        ${JSON.stringify(socketNameForFile(file))}: typeof import(${JSON.stringify(importPath)}).${fileStem(file)}`
+            return [
+                socketNameForFile(file),
+                `typeof import(${JSON.stringify(importPath)}).${fileStem(file)}`,
+            ]
         })
-        .toSorted()
-    const body = `declare module '${importName}/test/createTestApp' {
-    interface SocketClient {
-${entries.join('\n')}
-    }
-}`
-    await writeDts(cwd, 'testSockets', body)
+        .toSorted(([a], [b]) => (JSON.stringify(a) < JSON.stringify(b) ? -1 : 1))
+    const module = augmentModule(`${importName}/test/createTestApp`, 'SocketClient', entries)
+    await writeDts(cwd, 'testSockets', module)
 }

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

@@ -3,7 +3,6 @@ import type { BunPlugin } from 'bun'
 import { fileName } from '../../shared/fileName.ts'
 import { messageFromError } from '../../shared/messageFromError.ts'
 import { AbideCompileError } from './AbideCompileError.ts'
-import { analyzeComponent } from './analyzeComponent.ts'
 import { compileModule } from './compileModule.ts'
 import { nearestProjectRoot } from './nearestProjectRoot.ts'
 import { offsetToLineColumn } from './offsetToLineColumn.ts'
@@ -63,14 +62,17 @@ export const abideUiPlugin: BunPlugin = {
                     throw new Error(`${message.replace(/^\[abide\]\s*/, `[abide] ${at} — `)}`)
                 }
             }
-            const code = compileAbide(() => compileModule(source, { isLayout, moduleId }))
+            /* One compile pass yields both the module code and its scoped `<style>` blocks —
+               the styles come from the analysis `compileModule` already ran, so the loader no
+               longer re-analyzes the source just to recover them. */
+            const { code, styles } = compileAbide(() =>
+                compileModule(source, { isLayout, moduleId }),
+            )
             /* Browser build with `<style>`(s): concatenate every scoped block's CSS and
                pull it into the bundle via one virtual import, keyed by `moduleId` so the
-               registry id and the CSS id agree. */
-            const styles = compileAbide(() =>
-                toBrowser ? analyzeComponent(source, moduleId).styles : [],
-            )
-            if (styles.length === 0) {
+               registry id and the CSS id agree. Server builds skip the import (SSR styling
+               comes from the already-linked sheet). */
+            if (!toBrowser || styles.length === 0) {
                 return { contents: code, loader: 'ts' }
             }
             const virtual = `abide-style:${moduleId}`

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

@@ -15,20 +15,32 @@ and require that name to be imported or locally bound. A helper name inside a st
 comment is not a `CallExpression` callee, so a docs component quoting framework code
 (`mount(...)` in a snippet) never false-positives. Compile-time only; never on the hot path.
 */
-export function assertRuntimeHelpersBound(module: string, context: string): void {
+/* `module` is either the source string (standalone use — parsed here) or the already-parsed
+   tree of the bodies WITHOUT the prepended import block (compile pipeline — shares the one
+   parse the dead-import filter made). In the latter case the import block's bindings aren't in
+   the tree, so `importedHelpers` supplies the helper names that block will bind. */
+export function assertRuntimeHelpersBound(
+    module: string | ts.SourceFile,
+    importedHelpers: Set<string>,
+    context: string,
+): void {
     /* The EMITTED local names (the `$$` alias when set) — codegen calls those, and the
        aliased import binds them, so the bound/called check must use the same form. */
     const helperNames = new Set(UI_RUNTIME_IMPORTS.map((entry) => entry.alias ?? entry.name))
-    const source = ts.createSourceFile(
-        'module.ts',
-        module,
-        ts.ScriptTarget.Latest,
-        /* setParentNodes */ true,
-    )
-    /* Names a bare call can resolve to: every import binding plus every declared name.
-       Collected generously (any identifier in a binding position) — over-approximating the
-       bound set only risks missing a defect, never raising a false alarm on valid output. */
-    const bound = new Set<string>()
+    const source =
+        typeof module === 'string'
+            ? ts.createSourceFile(
+                  'module.ts',
+                  module,
+                  ts.ScriptTarget.Latest,
+                  /* setParentNodes */ true,
+              )
+            : module
+    /* Names a bare call can resolve to: the import block's helper bindings (supplied when the
+       tree omits them) plus every import binding and declared name in the tree. Collected
+       generously (any identifier in a binding position) — over-approximating the bound set only
+       risks missing a defect, never raising a false alarm on valid output. */
+    const bound = new Set<string>(importedHelpers)
     const calledHelpers: { name: string; position: number }[] = []
     const visit = (node: ts.Node): void => {
         if (
@@ -62,7 +74,7 @@ export function assertRuntimeHelpersBound(module: string, context: string): void
     if (unbound !== undefined) {
         const { line, character } = source.getLineAndCharacterOfPosition(unbound.position)
         throw new Error(
-            `[abide] ${context} calls runtime helper \`${unbound.name}\` at line ${line + 1}:${character + 1} but never imports it — the dead-import filter dropped it. Please report this with the component source.\nOutput:\n${module}`,
+            `[abide] ${context} calls runtime helper \`${unbound.name}\` at line ${line + 1}:${character + 1} but never imports it — the dead-import filter dropped it. Please report this with the component source.\nOutput:\n${source.text}`,
         )
     }
 }

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

@@ -5,6 +5,7 @@ import { assertRuntimeHelpersBound } from './assertRuntimeHelpersBound.ts'
 import { assertTranspiles } from './assertTranspiles.ts'
 import { compileComponent } from './compileComponent.ts'
 import { compileSSR } from './compileSSR.ts'
+import type { AnalyzedComponent } from './types/AnalyzedComponent.ts'
 import { UI_RUNTIME_IMPORTS } from './UI_RUNTIME_IMPORTS.ts'
 
 /*
@@ -26,7 +27,7 @@ what the `.abide` bundler loader emits.
 export function compileModule(
     source: string,
     options: { isLayout?: boolean; moduleId?: string; hot?: boolean } = {},
-): string {
+): { code: string; styles: AnalyzedComponent['styles'] } {
     const isLayout = options.isLayout ?? false
     /* Run the shared front-end once and feed it to both back-ends — the analysis is
        pure over (source, moduleId), so the client and SSR builds reuse one parse
@@ -52,7 +53,10 @@ export function compileModule(
                 : `${entry.name}: ${entry.alias}`,
         ).join(', ')
         const id = JSON.stringify(options.moduleId)
-        return `const { ${names}, hotReplace } = window.__abide
+        /* Hot mode never imports the scoped CSS (it reuses the live bundle's sheet), so
+           styles are empty here regardless of the analyzed blocks. */
+        return {
+            code: `const { ${names}, hotReplace } = window.__abide
 ${userImports}
 function build(host, $props) {
 ${body}
@@ -63,7 +67,9 @@ function component(host, $props) {
 component.build = build
 component.__abideId = ${id}
 if (!hotReplace(${id}, component)) location.reload()
-`
+`,
+            styles: [],
+        }
     }
 
     const ssrBody = indent(compileSSR(source, isLayout, options.moduleId, analyzed))
@@ -101,10 +107,24 @@ ${options.moduleId === undefined ? '' : `component.__abideId = ${JSON.stringify(
        string/comment/HTML literal (e.g. an `on`-attribute in static markup) no longer
        forces a spurious import, so no per-surface scoping is needed: a client-only helper
        simply doesn't appear as an identifier in the SSR body. */
-    const referenced = collectIdentifiers(`${userImports}\n${body}\n${ssrBody}\n${moduleBody}`)
-    const importBlock = UI_RUNTIME_IMPORTS.filter((entry) =>
+    /* Parse the generated bodies ONCE and feed the single tree to both AST passes: the
+       dead-import filter (`collectIdentifiers`) and the binding backstop
+       (`assertRuntimeHelpersBound`). The import block isn't in this tree yet — it is derived
+       from the filter's result — so the backstop is told the names that block will bind
+       (`importedHelpers`), which is exactly what it would have read from the prepended imports
+       had it re-parsed the whole module. `setParentNodes` is required by the backstop's
+       `getStart`/line lookups. */
+    const bodySource = ts.createSourceFile(
+        'module.ts',
+        `${userImports}\n${moduleBody}`,
+        ts.ScriptTarget.Latest,
+        /* setParentNodes */ true,
+    )
+    const referenced = collectIdentifiers(bodySource)
+    const keptImports = UI_RUNTIME_IMPORTS.filter((entry) =>
         referenced.has(entry.alias ?? entry.name),
     )
+    const importBlock = keptImports
         .map((entry) => {
             const local =
                 entry.alias === undefined || entry.alias === entry.name
@@ -126,9 +146,15 @@ ${moduleBody}`
     /* `assertTranspiles` only proves the output PARSES — a call to an un-imported helper is
        valid syntax, so it slips through. This second guard proves the output is BOUND: every
        runtime helper it calls is actually imported (an independent check of the dead-import
-       filter above), turning a runtime `ReferenceError` into a located compile error. */
-    assertRuntimeHelpersBound(module, 'component module generation')
-    return module
+       filter above), turning a runtime `ReferenceError` into a located compile error. It walks
+       the SAME tree the filter just parsed, with the kept helper imports supplied as the bound
+       set the prepended import block provides. */
+    assertRuntimeHelpersBound(
+        bodySource,
+        new Set(keptImports.map((entry) => entry.alias ?? entry.name)),
+        'component module generation',
+    )
+    return { code: module, styles: analyzed.styles }
 }
 
 /* Indents a body block for embedding inside a wrapper function. Lines whose start
@@ -170,14 +196,9 @@ function unescapedBacktickCount(line: string): number {
    in a handler — leaves the scanner unable to find the substitution's closing `}` without
    the parser's re-scan, so a token-only pass mis-reads the rest of the module as template
    text and drops every helper referenced after it (an `import`-less `effect`/`mountChild`
-   → a `ReferenceError` at mount → the router's reload fallback → a refresh loop). */
-function collectIdentifiers(code: string): Set<string> {
-    const source = ts.createSourceFile(
-        'module.ts',
-        code,
-        ts.ScriptTarget.Latest,
-        /* setParentNodes */ false,
-    )
+   → a `ReferenceError` at mount → the router's reload fallback → a refresh loop). Takes the
+   already-parsed source so the one tree feeds this pass and the binding backstop both. */
+function collectIdentifiers(source: ts.SourceFile): Set<string> {
     const names = new Set<string>()
     const visit = (node: ts.Node): void => {
         if (ts.isIdentifier(node)) {

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

@@ -97,7 +97,11 @@ export function compileShadow(source: string, propsType = 'Record<string, any>')
     for (const line of scope) {
         builder.flush(line)
     }
-    emitNodes(parseTemplate(source.slice(templateStart), templateStart).nodes, builder)
+    const templateNodes = parseTemplate(source.slice(templateStart), templateStart).nodes
+    /* Nested `<script>` blocks inline into the synchronous `build()` too, so a top-level
+       await in one is the same build-breaker — flag it, mapped via the node's body offset. */
+    collectNestedScriptAwaitDiagnostics(templateNodes, diagnostics)
+    emitNodes(templateNodes, builder)
     builder.raw('}\n')
     return { ...builder.result(), diagnostics }
 }
@@ -214,6 +218,73 @@ function collectReservedNameDiagnostics(
     visit(file)
 }
 
+/* Pushes a diagnostic for every `await` sitting at the script's top level — outside any
+   nested function. The generated `build()` runs the leading script synchronously, so a
+   top-level await transpiles to `await` in a non-async function and breaks the bundle; the
+   shadow's render fn is async, so `tsc` alone never flags it (a check/runtime parity gap).
+   Stops descending at function boundaries — their own async-ness is the author's concern —
+   and catches both `await expr` and `for await (… of …)`, flagging the `await` keyword. */
+function collectTopLevelAwaitDiagnostics(
+    file: ts.SourceFile,
+    scriptStart: number,
+    diagnostics: ShadowDiagnostic[],
+): void {
+    const message =
+        'top-level `await` is not allowed in a `<script>` — the component build runs synchronously. Use `{#await expr}…{:then value}…{/await}` markup for blocking data, or `await` inside an async event handler.'
+    const visit = (node: ts.Node): void => {
+        /* A nested function introduces its own (possibly async) scope; its awaits are legal. */
+        if (
+            ts.isFunctionDeclaration(node) ||
+            ts.isFunctionExpression(node) ||
+            ts.isArrowFunction(node) ||
+            ts.isMethodDeclaration(node) ||
+            ts.isGetAccessorDeclaration(node) ||
+            ts.isSetAccessorDeclaration(node) ||
+            ts.isConstructorDeclaration(node)
+        ) {
+            return
+        }
+        /* The `await` keyword token: the AwaitExpression's first child, or a `for await`'s
+           await modifier. */
+        const keyword = ts.isAwaitExpression(node)
+            ? node.getChildAt(0, file)
+            : ts.isForOfStatement(node)
+              ? node.awaitModifier
+              : undefined
+        if (keyword !== undefined) {
+            diagnostics.push({
+                start: scriptStart + keyword.getStart(file),
+                length: keyword.getEnd() - keyword.getStart(file),
+                message,
+            })
+        }
+        ts.forEachChild(node, visit)
+    }
+    visit(file)
+}
+
+/* Recursively visits every nested `<script>` in the template and flags a top-level await in
+   its body — the same trap as the leading script (it inlines into the sync `build()`), mapped
+   through the node's body offset (`loc`). Walks `children` on every node kind that carries
+   them, so a script buried in an `{#if}`/`{#for}`/`{#await}` branch is still reached. */
+function collectNestedScriptAwaitDiagnostics(
+    nodes: TemplateNode[],
+    diagnostics: ShadowDiagnostic[],
+): void {
+    for (const node of nodes) {
+        if (node === undefined) {
+            continue
+        }
+        if (node.kind === 'script' && node.loc !== undefined) {
+            const file = ts.createSourceFile('nested.ts', node.code, ts.ScriptTarget.Latest, true)
+            collectTopLevelAwaitDiagnostics(file, node.loc, diagnostics)
+        }
+        if ('children' in node) {
+            collectNestedScriptAwaitDiagnostics(node.children, diagnostics)
+        }
+    }
+}
+
 /* Walks the leading `<script>` and produces the shadow's module imports, the
    module-scope type declarations, the value-typed scope lines, and the `props<Shape>()`
    prop shapes. `scriptStart` is the body's absolute offset in the source, so verbatim
@@ -232,6 +303,9 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
        `$$scope`, …), so an author binding may not start with it — that's the contract that
        lets a user freely name a variable after any helper. Flag every such declaration. */
     collectReservedNameDiagnostics(file, scriptStart, diagnostics)
+    /* The leading script runs in the synchronous `build()`, so a top-level await breaks the
+       bundle — catch it here with a legible message instead of an opaque transpile error. */
+    collectTopLevelAwaitDiagnostics(file, scriptStart, diagnostics)
     /* 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] => ({

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

@@ -47,6 +47,21 @@ export function createShadowLanguageService(cwd: string): ShadowLanguageService
     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>()
+
+    /* The route props type for a component, parsed once and reused. */
+    const propsTypeOf = (abidePath: string): string | undefined => {
+        if (!propsTypes.has(abidePath)) {
+            propsTypes.set(abidePath, pagePropsType(abidePath))
+        }
+        return propsTypes.get(abidePath)
+    }
 
     /* Ambient declarations for bundler-handled asset imports (`*.css`, …). */
     const assets = assetModulesFile(cwd)
@@ -55,18 +70,29 @@ export function createShadowLanguageService(cwd: string): ShadowLanguageService
         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. */
+       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, pagePropsType(abidePath))
+            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))
-            return 'export default function (): void {}\n'
+            const code = 'export default function (): void {}\n'
+            compiledAt.set(abidePath, { version, code })
+            return code
         }
     }
 

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

@@ -125,7 +125,13 @@ export function generateBuild(
             (typeof node.attrs)[number],
             {
                 kind:
-                    'expression' | 'interpolated' | 'event' | 'attach' | 'bind' | 'class' | 'style'
+                    | 'expression'
+                    | 'interpolated'
+                    | 'event'
+                    | 'attach'
+                    | 'bind'
+                    | 'class'
+                    | 'style'
             }
         >,
         varName: string,

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

@@ -615,6 +615,9 @@ export function parseTemplate(source: string, baseOffset = 0): { nodes: Template
            verbatim to its `</script>` (not parsed as markup), scoped by the
            containing branch when compiled. */
         if (tag === 'script' && !selfClosing) {
+            /* Body starts at the current cursor; its absolute source offset lets the shadow
+               map a diagnostic raised inside it (e.g. a top-level await) back to source. */
+            const bodyLoc = baseOffset + cursor
             const close = source.indexOf('</script>', cursor)
             const end = close === -1 ? source.length : close
             const code = source.slice(cursor, end)
@@ -631,7 +634,7 @@ export function parseTemplate(source: string, baseOffset = 0): { nodes: Template
                     "import statements must live in the component's leading <script>, not a nested <template> script — they hoist to module scope for the whole template. For lazy loading, use a dynamic import() inside an effect.",
                 )
             }
-            return { kind: 'script', code }
+            return { kind: 'script', code, loc: bodyLoc }
         }
         /* A capitalised tag is a child component; its attributes become props and
            its children become slot content (rendered where the child puts <slot>). */

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

@@ -12,7 +12,7 @@ positions for the type-checking shadow, ignored by the runtime back-ends.
 */
 export type TemplateNode =
     | { kind: 'text'; parts: TextPart[] }
-    | { kind: 'script'; code: string }
+    | { kind: 'script'; code: string; loc?: number }
     /* A `<style>` declared in the template. `css` is its raw body, read structurally
        so a `<style>` inside an expression isn't mistaken for one. The node stays in
        place: it scopes its sibling subtree, so the front-end derives each scope