@abide/abide 0.46.0 → 0.47.0

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

@@ -1,44 +1,58 @@
 import ts from 'typescript'
 import { ABIDE_PACKAGE_NAME } from '../../shared/ABIDE_PACKAGE_NAME.ts'
 import { parseTemplate } from './parseTemplate.ts'
-import { REACTIVE_CALLEES } from './REACTIVE_CALLEES.ts'
+import {
+    NESTED_REACTIVE_BINDINGS,
+    type ReactiveImportBindings,
+    reactiveImportBindings,
+    resolveReactiveExport,
+} from './resolveReactiveExport.ts'
+import { signalCallee } from './signalCallee.ts'
 import type { CompiledShadow, ShadowDiagnostic, ShadowMapping } from './types/CompiledShadow.ts'
 import type { TemplateNode } from './types/TemplateNode.ts'
 
 /*
-Runtime helpers published as package subpaths solely so generated component code
-can import them; an author must reach them through their namespaced surface
-instead. The module resolver can't tell codegen from user source (same specifier),
-so the ban can only live in the check — map each forbidden specifier to the
-guidance shown when an author imports it.
+Framework callables the `.abide` loader injects into a component's scope. `snippet`
+and `scope` keep their real published types via imports so author calls type-check —
+`scope()` is the internal lowering host (a captured handle `const s = scope()` + its
+capability calls type-check against the real `Scope`; generated code targets it too).
+`state`/`linked`/`computed`/`effect` are the imported reactive surface; when the author
+imports one its own binding provides the type, so the ambient fallback for that name is
+OMITTED (see `shadowPreamble`) to avoid a duplicate identifier. Otherwise
+`state`/`linked`/`computed` are declared ambiently and `effect` is imported as a fallback
+for a bare/nested use the top-level rewrite doesn't project (unused when projected — fine,
+the shadow disables noUnusedLocals). `props` is the prop reader — destructured
+(`const { a = 1 } = props<Shape>()`); declared returning its type argument (default
+`Record<string, any>`) so each binding inherits its prop type and its `= default` narrows.
 */
-const INTERNAL_ONLY_IMPORTS: Record<string, string> = {
-    [`${ABIDE_PACKAGE_NAME}/ui/effect`]:
-        '`effect` is compiler-internal — author it as `scope().effect(...)`',
+function shadowPreamble(importedReactives: ReadonlySet<string>): string {
+    /* Omit the ambient fallback for a primitive the author imports — its own binding is
+       the type, and a second declaration would be a duplicate-identifier error. */
+    const lines = [
+        importedReactives.has('effect')
+            ? undefined
+            : `import { effect } from '${ABIDE_PACKAGE_NAME}/ui/effect'`,
+        importedReactives.has('watch')
+            ? undefined
+            : `import { watch } from '${ABIDE_PACKAGE_NAME}/ui/watch'`,
+        `import { snippet } from '${ABIDE_PACKAGE_NAME}/shared/snippet'`,
+        `import { scope } from '${ABIDE_PACKAGE_NAME}/ui/currentScope'`,
+        importedReactives.has('state')
+            ? undefined
+            : 'declare function state<T>(initial?: T, transform?: (next: T, previous: T) => T): { value: T }',
+        importedReactives.has('linked')
+            ? undefined
+            : 'declare function linked<T>(seed: () => T, transform?: (next: T, previous: T) => T): { value: T }',
+        importedReactives.has('computed')
+            ? undefined
+            : 'declare function computed<T>(compute: () => T): { readonly value: T }',
+        'declare const children: (() => void) | undefined',
+        /* `effect` is defined either way — the preamble import or the author's own import. */
+        'void [effect, snippet, scope]',
+    ]
+    return `${lines.filter((line) => line !== undefined).join('\n')}\n`
 }
 
-/*
-Framework callables the `.abide` loader injects into a component's scope. `effect`,
-`snippet`, and `scope` keep their real published types via imports so author
-calls type-check — `scope()` is the authored reactive surface (`scope().state(...)` /
-`.computed(...)` / `.undo()` …), so it must resolve like any import. `state`/`linked`/
-`computed` are ALSO declared ambiently as a fallback for the rare bare/nested use the
-top-level rewrite doesn't project (their top-level declarations become value types, so
-these are normally unused — fine, the shadow disables noUnusedLocals). `props` is the prop
-reader — destructured (`const { a = 1 } = props<Shape>()`); declared returning its type
-argument (default `Record<string, any>`) so each binding inherits its prop type and its
-`= default` narrows.
-*/
-const SHADOW_PREAMBLE = `import { effect } from '${ABIDE_PACKAGE_NAME}/ui/effect'
-import { snippet } from '${ABIDE_PACKAGE_NAME}/shared/snippet'
-import { scope } from '${ABIDE_PACKAGE_NAME}/ui/scope'
-declare function state<T>(initial?: T, transform?: (next: T, previous: T) => T): { value: T }
-declare function linked<T>(seed: () => T, transform?: (next: T, previous: T) => T): { value: T }
-declare function computed<T>(compute: () => T): { readonly value: T }
-declare const children: (() => void) | undefined
-void [effect, snippet, scope]
-`
-
 /*
 Compiles a `.abide` component into its type-checking shadow — a synthetic TS
 module that reconstructs the author scope with value types and references every
@@ -62,11 +76,11 @@ export function compileShadow(source: string, propsType = 'Record<string, any>')
     const scriptStart = leadingScript ? source.indexOf('>', leadingScript.index) + 1 : 0
     const templateStart = leadingScript ? (leadingScript.index ?? 0) + leadingScript[0].length : 0
 
-    const { imports, types, scope, propsShapes, diagnostics } = analyzeScript(
+    const { imports, types, scope, propsShapes, diagnostics, importedReactives } = analyzeScript(
         scriptBody,
         scriptStart,
     )
-    builder.raw(SHADOW_PREAMBLE)
+    builder.raw(shadowPreamble(importedReactives))
     /* `props()` defaults to the file's type — a page/layout's route param shape, else
        `Record<string, any>` — so `const { id } = props()` infers from the route. */
     builder.raw(`declare function props<T = ${propsType}>(): T\n`)
@@ -80,6 +94,17 @@ export function compileShadow(source: string, propsType = 'Record<string, any>')
     for (const line of types) {
         builder.flush(line)
     }
+    /* The author's scope (value consts, functions, reactive projections, the `props()`
+       destructure) is hoisted to module scope — above `__Props` — for the same reason the
+       types are: a prop annotation can then reference a value const by `typeof`
+       (`size: keyof typeof sizes`), which fails when the const sits in the function body and
+       `__Props` at module scope can't see it. Narrowing is unaffected: a template's guard and
+       read are both in the render function below, so control-flow narrowing flows regardless
+       of where the binding is declared, and reactive projections are never rebound (writes go
+       through `.value`), so they narrow like consts even into nested handlers. */
+    for (const line of scope) {
+        builder.flush(line)
+    }
     /* `__Props` is the parent-facing prop shape: each `props<Shape>()` destructure
        contributes its whole `Shape` (intersected if there's more than one), or an empty
        object for a component that reads no props. */
@@ -94,9 +119,6 @@ export function compileShadow(source: string, propsType = 'Record<string, any>')
     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)
-    }
     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. */
@@ -184,6 +206,9 @@ type ScriptAnalysis = {
     scope: ScopeLine[]
     propsShapes: string[]
     diagnostics: ShadowDiagnostic[]
+    /* The reactive primitives the author imports (`state`/`effect`), so the preamble
+       omits the ambient fallback for each and avoids a duplicate-identifier error. */
+    importedReactives: Set<string>
 }
 
 /* Pushes a diagnostic for every author binding whose name starts with the reserved `$$`
@@ -296,9 +321,14 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
     const propsShapes: string[] = []
     const diagnostics: ShadowDiagnostic[] = []
     if (scriptBody.trim() === '') {
-        return { imports, types, scope, propsShapes, diagnostics }
+        return { imports, types, scope, propsShapes, diagnostics, importedReactives: new Set() }
     }
     const file = ts.createSourceFile('script.ts', scriptBody, ts.ScriptTarget.Latest, true)
+    /* The author's reactive import bindings (alias-safe) — recognition source for
+       `state`/`state.linked`/`state.computed`/`effect`, and the set of imported primitives
+       the preamble omits its ambient fallback for. */
+    const bindings = reactiveImportBindings(file)
+    const importedReactives = new Set(bindings.direct.values())
     /* The `$$` prefix is reserved for the compiler's injected runtime (`$$each`, `$$model`,
        `$$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. */
@@ -317,21 +347,9 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
 
     for (const statement of file.statements) {
         if (ts.isImportDeclaration(statement)) {
-            const specifier = ts.isStringLiteral(statement.moduleSpecifier)
-                ? statement.moduleSpecifier.text
-                : undefined
-            const banned = specifier !== undefined ? INTERNAL_ONLY_IMPORTS[specifier] : undefined
-            if (banned !== undefined) {
-                /* Flag and drop it — leaving it out keeps `effect` resolving via the
-                   preamble (no duplicate-identifier noise on top of our message). */
-                diagnostics.push({
-                    start: scriptStart + statement.getStart(file),
-                    length: statement.getEnd() - statement.getStart(file),
-                    message: banned,
-                })
-                continue
-            }
-            /* Emit verbatim with a span so hover/go-to resolve on the imported names. */
+            /* Emit verbatim with a span so hover/go-to resolve on the imported names.
+               `abide/ui/state` / `abide/ui/effect` are ordinary author imports now — the
+               preamble drops its ambient fallback for whichever names are imported. */
             imports.push({ text: verbatim(statement), segments: [span(statement, 0)] })
             continue
         }
@@ -340,17 +358,17 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
             types.push({ text: verbatim(statement), segments: [span(statement, 0)] })
             continue
         }
-        const reactive = reactiveDeclarations(statement)
+        const reactive = reactiveDeclarations(statement, bindings)
         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, propsShapes, verbatim, span))
+            scope.push(scopeLineFor(declaration, propsShapes, verbatim, span, bindings))
         }
     }
-    return { imports, types, scope, propsShapes, diagnostics }
+    return { imports, types, scope, propsShapes, diagnostics, importedReactives }
 }
 
 /* Value-projects a nested control-flow `<script>` body the way `analyzeScript`
@@ -360,16 +378,20 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
    reads a nested signal as its value type instead of the raw `State`/`Computed`. */
 function projectNestedScript(code: string): string {
     const file = ts.createSourceFile('nested.ts', code, ts.ScriptTarget.Latest, true)
+    /* A nested script can't import — it inherits the module-scope surface by canonical name. */
+    const bindings = NESTED_REACTIVE_BINDINGS
     const verbatim = (node: ts.Node): string => code.slice(node.getStart(file), node.getEnd())
     /* No mapping: a zero-length segment the caller drops. */
     const span = (): ShadowMapping => ({ shadowStart: 0, sourceStart: 0, length: 0 })
     return file.statements
         .flatMap((statement) => {
-            const reactive = reactiveDeclarations(statement)
+            const reactive = reactiveDeclarations(statement, bindings)
             if (reactive === undefined) {
                 return [verbatim(statement)]
             }
-            return reactive.map((declaration) => scopeLineFor(declaration, [], verbatim, span).text)
+            return reactive.map(
+                (declaration) => scopeLineFor(declaration, [], verbatim, span, bindings).text,
+            )
         })
         .join('\n')
 }
@@ -377,32 +399,20 @@ function projectNestedScript(code: string): string {
 /* The `state`/`computed`/`linked`/`props()` 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 {
+function reactiveDeclarations(
+    statement: ts.Statement,
+    bindings: ReactiveImportBindings,
+): ts.VariableDeclaration[] | undefined {
     if (!ts.isVariableStatement(statement)) {
         return undefined
     }
     const declarations = statement.declarationList.declarations
-    const reactive = declarations.filter((declaration) => signalCallee(declaration) !== undefined)
+    const reactive = declarations.filter(
+        (declaration) => signalCallee(declaration, bindings) !== undefined,
+    )
     return reactive.length === declarations.length && reactive.length > 0 ? reactive : undefined
 }
 
-/* The callee name of a `NAME = state(...)` / `linked(...)` / `computed(...)` /
-   `props()` decl — bare or the explicit scope form (`scope().state(...)` / `c.state(...)`),
-   receiver-agnostic (the method name marks it reactive). */
-function signalCallee(declaration: ts.VariableDeclaration): string | undefined {
-    const initializer = declaration.initializer
-    if (initializer === undefined || !ts.isCallExpression(initializer)) {
-        return undefined
-    }
-    const callee = initializer.expression
-    const name = ts.isIdentifier(callee)
-        ? callee.text
-        : ts.isPropertyAccessExpression(callee)
-          ? callee.name.text
-          : undefined
-    return name !== undefined && REACTIVE_CALLEES.has(name) ? name : undefined
-}
-
 /* Builds one scope line for a reactive declaration, projecting it to its value
    type. A `props()` destructure contributes its whole shape (pushed into `propsShapes`). */
 function scopeLineFor(
@@ -410,13 +420,14 @@ function scopeLineFor(
     propsShapes: string[],
     verbatim: (node: ts.Node) => string,
     span: (node: ts.Node, prefixLength: number) => ShadowMapping,
+    bindings: ReactiveImportBindings,
 ): ScopeLine {
     const name = ts.isIdentifier(declaration.name) ? declaration.name.text : '_'
     const call = declaration.initializer as ts.CallExpression
-    /* Bare callee (`state`) or member callee (`scope().state` / `c.state`). */
-    const callee = ts.isPropertyAccessExpression(call.expression)
-        ? call.expression.name.text
-        : (call.expression as ts.Identifier).text
+    /* The CANONICAL primitive drives value-projection — resolved purely from the import
+       binding (so an aliased `s(0)` / `state.computed(...)` projects correctly).
+       `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
@@ -737,8 +748,10 @@ function emitNode(node: TemplateNode, builder: Builder): void {
             emitNodes(node.children, builder)
             return
         case 'branch':
-            /* Reached only for a stray branch outside an await (none today); the await
-               handler binds resolved/error types for its own branch children. */
+            /* Reached for a `{#try}`'s `catch`/`finally`: the `try` handler emits its
+               children directly (guarded content + these branch nodes), so a `{:catch err}`
+               binds its error here as `any` (statically unknowable). The `await`/`if`/`switch`
+               handlers consume their own branches inline and never route through this case. */
             builder.raw('{\n')
             if (node.as !== undefined) {
                 builder.raw(`const ${node.as} = undefined as any;\n`)
@@ -759,9 +772,13 @@ function emitNode(node: TemplateNode, builder: Builder): void {
             if (node.params !== undefined) {
                 builder.mapped(node.params, node.loc)
             }
-            builder.raw(') => {\n')
+            /* Wrap the body in `snippet(() => …)` so the shadow types the snippet as
+               `(args) => Snippet<…>` — mirroring the runtime lowering (which returns
+               `$$snippet(($host) => …)`) so a snippet passed to a `Snippet`-typed prop
+               type-checks instead of reading as `() => void`. */
+            builder.raw(') => snippet(() => {\n')
             emitNodes(node.children, builder)
-            builder.raw('};\n')
+            builder.raw('});\n')
             return
         case 'script':
             /* A scoped reactive `<script>`: value-project its reactive declarations to