@abide/abide 0.44.0 → 0.45.0

package/src/lib/shared/requestScopeResolver.ts

@@ -0,0 +1,12 @@
+import { createResolverSlot } from './createResolverSlot.ts'
+import type { RequestScopeInfo } from './types/RequestScopeInfo.ts'
+
+/*
+Slot + setter for the request-scope resolver. The server installs an ALS-backed
+resolver (createServer, reading the RequestStore); the client a module-singleton
+seeded from __SSR__ (startClient). No fallback creator — an unset resolver (or one
+returning undefined outside any request) means "no scope": callers read
+`.resolver?.()` and treat undefined as absent. requestScopeSlot /
+setRequestScopeResolver re-export the slot and setter.
+*/
+export const requestScopeResolver = createResolverSlot<RequestScopeInfo>()

package/src/lib/shared/requestScopeSlot.ts

@@ -1,15 +1,10 @@
-import type { RequestScopeInfo } from './types/RequestScopeInfo.ts'
+import { requestScopeResolver } from './requestScopeResolver.ts'
 
 /*
-Internal slot the runtime entries register their request-scope resolver into.
-The server installs an ALS-backed resolver (createServer, reading the
-RequestStore); the client installs a module-singleton resolver seeded from
-__SSR__ (startClient). Undefined resolver — or a resolver returning undefined
-outside any request — means "no scope": trace() returns undefined and log
-lines print without the context prefix. Mirrors pageSlot / cacheStoreSlot.
+Internal slot the runtime entries register their request-scope resolver into (see
+requestScopeResolver). Exposed so callers read `.resolver?.()` and test helpers
+snapshot/poke `.resolver` directly. Undefined resolver — or one returning
+undefined outside any request — means "no scope": trace() returns undefined and
+log lines print without the context prefix.
 */
-export const requestScopeSlot: {
-    resolver: (() => RequestScopeInfo | undefined) | undefined
-} = {
-    resolver: undefined,
-}
+export const requestScopeSlot = requestScopeResolver.slot

package/src/lib/shared/responseBodyKind.ts

@@ -0,0 +1,35 @@
+import { contentBodyKind } from './contentBodyKind.ts'
+import { contentTypeOf } from './contentTypeOf.ts'
+
+/*
+Compressible Content-Types — text and structured-text payloads. Binary or
+already-compressed bodies (images, fonts, archives, zstd/gzip blobs) gain
+nothing from a second pass and only burn CPU.
+*/
+const COMPRESSIBLE_TYPE =
+    /^(?:text\/|application\/(?:json|javascript|xml|[\w.-]+\+(?:json|xml))|image\/svg)/
+
+/*
+The post-handler body class that decides a dynamic response's wire handling:
+`streaming` (SSE / JSONL — drained frame-by-frame, never gzip-buffered, opted
+out of the idle timeout), `compressible` (text/structured-text — gzipped when
+the client accepts it), or `opaque` (binary/already-encoded — passed through).
+
+One header read + classify per response, threaded through the dispatch pipeline
+so `gzipResponse` and the idle-timeout opt-out don't each re-derive it from the
+Content-Type (the S2 finding: the same body was classified 3-4×). Mirrors the
+shared `contentBodyKind` streaming bucket so the wire path and the decode path
+can't disagree on what's a stream.
+*/
+export type ResponseBodyKind = 'streaming' | 'compressible' | 'opaque'
+
+export function responseBodyKind(response: Response): ResponseBodyKind {
+    const contentType = contentTypeOf(response.headers)
+    if (contentBodyKind(contentType) === 'streaming') {
+        return 'streaming'
+    }
+    if (COMPRESSIBLE_TYPE.test(contentType)) {
+        return 'compressible'
+    }
+    return 'opaque'
+}

package/src/lib/shared/setBaseResolver.ts

@@ -1,6 +1,4 @@
-import { baseSlot } from './baseSlot.ts'
+import { baseResolver } from './baseResolver.ts'
 
 // Registers the runtime's mount-base resolver. Called once per side at boot.
-export function setBaseResolver(fn: () => string): void {
-    baseSlot.resolver = fn
-}
+export const setBaseResolver = baseResolver.set

package/src/lib/shared/setCacheStoreResolver.ts

@@ -1,6 +1,4 @@
-import { cacheStoreSlot } from './cacheStoreSlot.ts'
-import type { CacheStore } from './types/CacheStore.ts'
+import { cacheStoreResolver } from './cacheStoreResolver.ts'
 
-export function setCacheStoreResolver(fn: () => CacheStore | undefined): void {
-    cacheStoreSlot.resolver = fn
-}
+// Registers the runtime's active-CacheStore resolver. Called once per side at boot.
+export const setCacheStoreResolver = cacheStoreResolver.set

package/src/lib/shared/setGlobalCacheStoreResolver.ts

@@ -1,6 +1,4 @@
-import { globalCacheStoreSlot } from './globalCacheStoreSlot.ts'
-import type { CacheStore } from './types/CacheStore.ts'
+import { globalCacheStoreResolver } from './globalCacheStoreResolver.ts'
 
-export function setGlobalCacheStoreResolver(fn: () => CacheStore | undefined): void {
-    globalCacheStoreSlot.resolver = fn
-}
+// Registers the process-level cache store resolver. Called once per side at boot.
+export const setGlobalCacheStoreResolver = globalCacheStoreResolver.set

package/src/lib/shared/setPageResolver.ts

@@ -1,7 +1,4 @@
-import { pageSlot } from './pageSlot.ts'
-import type { PageSnapshot } from './types/PageSnapshot.ts'
+import { pageResolver } from './pageResolver.ts'
 
 // Registers the runtime's page resolver. Called once per side at boot.
-export function setPageResolver(fn: () => PageSnapshot | undefined): void {
-    pageSlot.resolver = fn
-}
+export const setPageResolver = pageResolver.set

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/toTagSet.ts

@@ -1,4 +1,4 @@
-/* Normalizes a tags option (one tag or many) to a Set for O(1) membership. */
-export function toTagSet(tags: string | string[]): Set<string> {
-    return new Set(typeof tags === 'string' ? [tags] : tags)
+/* Normalizes a tags option to a Set for O(1) membership. */
+export function toTagSet(tags: string[]): Set<string> {
+    return new Set(tags)
 }

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

@@ -59,9 +59,24 @@ export type CacheEntry = {
     ttl: number | undefined
     expiresAt: number | undefined
     value?: unknown
+    /*
+    Lazy warm materializer (Tier 2 deferred seed): a memoized thunk that decodes the
+    shipped body into the warm value on first call, so a deferred snapshot pays no decode
+    at hydration — only when a read actually needs the value. `value` stays undefined until
+    then; the read gate treats an entry with `warm` set as warm without invoking it. Eager
+    snapshots set `value` and leave this undefined.
+    */
+    warm?: () => unknown
     tags?: Set<string>
     settled?: boolean
     hydrated?: boolean
+    /*
+    Marks that the SSR resume path deferred this entry's `{#await cache()}` value — shipped a
+    `{ defer, key }` marker instead of inlining it. The post-stream snapshot drain reads it to
+    ship the body as a LAZY seed (decoded on first read, not at hydration). Set server-side
+    only, on the request-scoped entry, during the stream.
+    */
+    deferred?: boolean
     refreshing?: boolean
     invalidation?: InvalidationState
 }

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

@@ -6,10 +6,10 @@ milliseconds-past-resolve that the entry stays live: omitted = forever, 0 =
 dedupe only (entry dropped once the promise settles — the mutation idiom:
 in-flight coalescing and pending() visibility, nothing retained), any other
 number = TTL.
-`tags` is one or more free-form labels grouping unrelated calls so one
-`cache.invalidate({ tags })` drops every entry sharing any of them — pass an
-array when a call belongs to multiple invalidation groups. A unique tag (e.g. a
-uuid) shared by a set of calls gives them their own private invalidation group.
+`tags` is an array of free-form labels grouping unrelated calls so one
+`cache.invalidate({ tags })` drops every entry sharing any of them — list
+multiple when a call belongs to multiple invalidation groups. A unique tag (e.g.
+a uuid) shared by a set of calls gives them their own private invalidation group.
 
 `global` opts the entry into the process-level store instead of the default
 request-scoped one (server) — so a value computed in one request is reused by
@@ -37,7 +37,7 @@ uncheckable — set `swr` only on a producer that is a pure read.
 */
 export type CacheOptions = {
     ttl?: number
-    tags?: string | string[]
+    tags?: string[]
     global?: boolean
     swr?: boolean | { throttle?: number; debounce?: number }
 }

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

@@ -14,4 +14,9 @@ export type CacheSnapshotEntry = {
     statusText: string
     headers: Array<[string, string]>
     body: string
+    /* Deferred seed (Tier 2): the client stores the body but does NOT decode it at boot —
+       the warm value is materialized lazily on the first read, off the hydration path. Set
+       by the server for a deferred `{#await cache()}` whose value ships via a `{defer,key}`
+       resume marker instead of inline, so hydration touches neither copy's decode. */
+    lazy?: boolean
 }

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/ErrorSpec.ts

@@ -1,11 +1,11 @@
 import type { StandardSchemaV1 } from './StandardSchemaV1.ts'
 
 /*
-A rpc's declared error set, keyed by error NAME (not status, so two errors can
-share a status). Each entry names its HTTP `status` and an optional `data`
-schema whose inferred input the error constructor requires. Passed as the rpc's
-`errors` opt; the client derives a typed `Result` union from it (see
-`RpcErrorUnion`), and the handler receives matching constructors (see
-`ErrorConstructors`).
+A rpc's error set, keyed by error NAME (not status, so two errors can share a
+status). Each entry names its HTTP `status` and an optional `data` schema whose
+inferred input the error constructor requires. Built at the type level from the
+`error.typed(...)` constructors a handler RETURNS (see `TypedError` +
+`InferredErrors` in RpcHelper); the client's `rpc.isError` narrows `.kind` /
+`.data` off it (see `RpcErrorGuard`).
 */
 export type ErrorSpec = Record<string, { status: number; data?: StandardSchemaV1 }>

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

@@ -43,6 +43,7 @@ export type RemoteFunction<
     Args,
     Return,
     Errors extends ErrorSpec = Record<never, never>,
+    Durable extends boolean = false,
 > = RemoteCallable<Args, Return> & {
     readonly method: HttpMethod
     readonly url: string
@@ -56,7 +57,10 @@ export type RemoteFunction<
        per-rpc replacement for a global guard, since the error name → data type mapping
        lives in the rpc's own spec. */
     readonly isError: RpcErrorGuard<Errors>
-    /* Present only on a durable (`outbox`) RPC's client proxy: callable for the reactive
-       list of undelivered entries, with `retry()` to drain the queue. Undefined otherwise. */
-    readonly outbox?: Outbox<Args>
-}
+} /* `outbox` presence follows the `outbox: true` opt: the mutating helper threads `Durable`
+     into the return type so a DURABLE rpc's `.outbox` is the required queue face (no optional
+     chain). A non-durable rpc keeps it optional — assignable to a durable one everywhere a
+     bare `RemoteFunction<Args, Return>` slot (cache selectors, registries) is expected, since
+     required→optional widens cleanly and no call site had to learn the `Durable` bit. */ & (Durable extends true
+        ? { readonly outbox: Outbox<Args> }
+        : { readonly outbox?: Outbox<Args> })

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/UI_RUNTIME_IMPORTS.ts

@@ -35,6 +35,7 @@ export const UI_RUNTIME_IMPORTS: { name: string; specifier: string; alias?: stri
     { name: 'eachAsync', specifier: 'ui/dom/eachAsync', alias: '$$eachAsync' },
     { name: 'when', specifier: 'ui/dom/when', alias: '$$when' },
     { name: 'awaitBlock', specifier: 'ui/dom/awaitBlock', alias: '$$awaitBlock' },
+    { name: 'deferResume', specifier: 'ui/deferResume', alias: '$$deferResume' },
     { name: 'tryBlock', specifier: 'ui/dom/tryBlock', alias: '$$tryBlock' },
     { name: 'switchBlock', specifier: 'ui/dom/switchBlock', alias: '$$switchBlock' },
     { name: 'mountSlot', specifier: 'ui/dom/mountSlot', alias: '$$mountSlot' },

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}`,
         )
     }
 }