@abide/abide 0.48.0 → 0.50.0

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

@@ -0,0 +1,166 @@
+import ts from 'typescript'
+import { AbideCompileError } from './AbideCompileError.ts'
+import type { InjectedCell } from './lowerAsyncInterpolations.ts'
+import type { InterpolationClassifier } from './types/InterpolationClassifier.ts'
+import type { InterpolationKind } from './types/InterpolationKind.ts'
+
+/* The value/content position a lifted (sub)expression sits in — only `each` (a plain `{#for}`
+   source) forbids an `AsyncIterable` (D4a). Every other position renders a stream's latest frame. */
+export type LiftPosition = 'content' | 'attribute' | 'if' | 'switch' | 'each'
+
+/* A lifted (sub)expression's span within the interpolation `code` and how it lifts: `start`/`end`
+   index `code`, `kind` picks the peek flavour, `blocking` marks a leading `await`. The runtime uses
+   these to rewrite the span to a cell ref; the type-check shadow uses the non-blocking ones to wrap
+   the seed in a peek helper so its resolved type composes (ADR-0032). */
+export type LiftSpan = {
+    start: number
+    end: number
+    kind: 'promise' | 'asyncIterable'
+    blocking: boolean
+}
+
+/* The binary operators whose result reacts to a pending-`undefined` operand: the walk does NOT
+   lift the composition, it descends into the operands so the operator composes the peek(s)
+   (ADR-0032 D1). `?.` needs no entry — a member/call on a promise is sync-typed, so the default
+   sync-recurse already reaches and lifts the async base. */
+const PENDING_TOLERANT = new Set<ts.SyntaxKind>([
+    ts.SyntaxKind.QuestionQuestionToken,
+    ts.SyntaxKind.BarBarToken,
+    ts.SyntaxKind.AmpersandAmpersandToken,
+])
+
+/*
+ADR-0032 — the sub-expression walk. Given an interpolation's verbatim `code`, its absolute source
+offset `loc`, and the warm classifier, lifts every promise/`AsyncIterable`-typed (sub)expression
+into an injected peek-cell and rewrites it in place to a bare `__vN` reference, returning the
+rewritten code and the cells to inject. Pending is `undefined` at the value level, so `??` / `?.` /
+member access compose around the peek (`getFoo() ?? 'Loading…'` shows the fallback while pending).
+
+Three rules, top-down (ADR D1 "The walk"):
+  1. `await X`             → lift `X` BLOCKING (SSR-inline); syntactic, needs no classifier.
+  2. `a ?? b` / `||` / `&&`→ NOT lifted; recurse into the operands (pending stays visible to the op).
+  3. any other promise/`AsyncIterable` node → lift as a unit, STREAMING; a sync node recurses
+     (a sync parent can wrap an async child: `String(getFoo())`, `` `${getFoo()}` ``).
+
+`classify` absent (no warm program) ⇒ only rule 1 fires — fail-open: `await` still works, a bare
+async position degrades to today's stringify. A promise seed is emitted `await X` so the cell
+UNWRAPS to the resolved value; an `AsyncIterable` seed stays bare (its latest frame). D4: an
+`AsyncIterable` in a plain `{#for}` source, or an `await` on an `AsyncIterable`, throw.
+*/
+export function liftAsyncSubExpressions(
+    code: string,
+    loc: number,
+    classify: InterpolationClassifier | undefined,
+    mint: () => string,
+    position: LiftPosition = 'content',
+): { code: string; lifts: InjectedCell[]; spans: LiftSpan[] } {
+    const source = ts.createSourceFile('__lift.ts', code, ts.ScriptTarget.Latest, true)
+    const first = source.statements[0]
+    /* Only a single bare expression is walkable; anything else (a statement, empty) passes through. */
+    if (first === undefined || source.statements.length !== 1 || !ts.isExpressionStatement(first)) {
+        return { code, lifts: [], spans: [] }
+    }
+    const lifts: InjectedCell[] = []
+    /* Each lifted span, in walk (source) order; spliced right-to-left so earlier offsets stay valid.
+       `start`/`end` index `code`; `name` replaces that span. */
+    const edits: { start: number; end: number; name: string }[] = []
+    /* The same lifted spans with their kind/tier — the shadow's peek-wrap consumes these directly. */
+    const spans: LiftSpan[] = []
+
+    const text = (node: ts.Node): string => code.slice(node.getStart(source), node.getEnd())
+
+    /* The checker kind of a sub-node, keyed by its absolute source offset through the linear
+       interpolation→shadow mapping. `undefined` when no classifier (only `await` lifts then). */
+    const kindOf = (node: ts.Node): InterpolationKind | undefined => {
+        if (classify === undefined) {
+            return undefined
+        }
+        const start = node.getStart(source)
+        return classify(loc + start, code.slice(start, node.getEnd()))
+    }
+
+    /* Record a lift of `node`'s span. `seed` is the RAW (sub)expression text — `analyzeComponent`
+       wraps a `promise` seed as `computed(async () => await (<seed>))` (so `await` is a keyword in
+       an async context — a bare-text `await (X)` reparsed at module scope becomes a call to a
+       function `await`) and an `asyncIterable` seed as `computed(<seed>)` (a bare stream thunk). */
+    const lift = (
+        node: ts.Node,
+        seed: string,
+        kind: 'promise' | 'asyncIterable',
+        blocking: boolean,
+    ): void => {
+        const name = mint()
+        const start = node.getStart(source)
+        const end = node.getEnd()
+        lifts.push({ name, code: seed, kind, blocking })
+        edits.push({ start, end, name })
+        spans.push({ start, end, kind, blocking })
+    }
+
+    const visit = (node: ts.Node): void => {
+        /* A nested function is its own evaluation scope — an async (sub)expression inside a callback
+           (`items.map(x => fetchName(x))`, `items.map(async x => await load(x))`) must NOT be hoisted
+           to a top-level cell: its parameters/closure vars would become free identifiers, and it
+           would run once instead of per row. Stop at the boundary, mirroring
+           `desugarSignals.hasTopLevelAwait`. */
+        if (
+            ts.isArrowFunction(node) ||
+            ts.isFunctionExpression(node) ||
+            ts.isFunctionDeclaration(node)
+        ) {
+            return
+        }
+        if (ts.isAwaitExpression(node)) {
+            /* `await X` → a BLOCKING promise cell (its operand). D4b: `await` on a stream is
+               meaningless. The operand text is already a bounded unary — no parens needed. */
+            if (kindOf(node.expression) === 'asyncIterable') {
+                throw new AbideCompileError(
+                    '[abide] `await` unwraps a promise, but this is an `AsyncIterable` — drop the `await`; a stream auto-tracks (render its frames, or `{#for await}`).',
+                    loc + node.getStart(source),
+                )
+            }
+            lift(node, text(node.expression), 'promise', true)
+            return
+        }
+        if (ts.isBinaryExpression(node) && PENDING_TOLERANT.has(node.operatorToken.kind)) {
+            /* Pending-tolerant: don't lift the composition — descend so the operator sees the
+               operands' `undefined` (`getFoo() ?? 'Loading…'`, `x || getFoo()`). */
+            visit(node.left)
+            visit(node.right)
+            return
+        }
+        const kind = kindOf(node)
+        if (kind === 'promise') {
+            /* Lift as a unit, streaming; the cell unwraps the seed to its resolved value. */
+            lift(node, text(node), 'promise', false)
+            return
+        }
+        if (kind === 'asyncIterable') {
+            if (position === 'each') {
+                throw new AbideCompileError(
+                    "[abide] an `AsyncIterable` can't drive a plain `{#for}` — iterate its frames with `{#for await}`.",
+                    loc + node.getStart(source),
+                )
+            }
+            /* A stream cell: its latest frame. */
+            lift(node, text(node), 'asyncIterable', false)
+            return
+        }
+        /* Sync (or classifier-absent): a sync parent can still wrap an async child. */
+        ts.forEachChild(node, visit)
+    }
+
+    visit(first.expression)
+
+    if (edits.length === 0) {
+        return { code, lifts: [], spans: [] }
+    }
+    edits.sort((a, b) => b.start - a.start)
+    let rewritten = code
+    for (const edit of edits) {
+        rewritten = rewritten.slice(0, edit.start) + edit.name + rewritten.slice(edit.end)
+    }
+    /* Spans in ascending source order — the shadow's peek-wrap walks them left-to-right. */
+    spans.sort((a, b) => a.start - b.start)
+    return { code: rewritten, lifts, spans }
+}

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

@@ -0,0 +1,92 @@
+import { asyncInterpolationFields } from './asyncInterpolationFields.ts'
+import { liftAsyncSubExpressions } from './liftAsyncSubExpressions.ts'
+import type { InterpolationClassifier } from './types/InterpolationClassifier.ts'
+import type { TemplateNode } from './types/TemplateNode.ts'
+
+/* A synthetic peek-cell an async (sub)expression lowers to: a unique local name, the RAW seed
+   expression, its `kind` (a `promise` cell UNWRAPS to the resolved value; an `asyncIterable` cell
+   tracks its latest frame), and whether the author wrote `await` (BLOCKING: joins the SSR barrier,
+   resolved inline; else STREAMING: ships pending-`undefined`, resolves on the client). By kind,
+   `analyzeComponent` prepends `const <name> = computed(async () => await (<code>))` (promise) or
+   `const <name> = computed(<code>)` (stream); `desugarSignals` routes it (by injected name) to a
+   `trackedComputed` cell read via `$$readCell(<name>)`. */
+export type InjectedCell = {
+    name: string
+    code: string
+    kind: 'promise' | 'asyncIterable'
+    blocking: boolean
+}
+
+/* The result of the async-interpolation lowering: the (mutated-in-place) template plus the cells
+   the lifted (sub)expressions were rewritten into (empty when none). */
+export type LoweredInterpolations = { nodes: TemplateNode[]; cells: InjectedCell[] }
+
+/*
+ADR-0032 type-directed lowering of async (sub)expressions, in EVERY position — content
+interpolations and value positions (attribute, `{#if}`/`{#switch}` subject, plain `{#for}` source)
+alike. Each interpolation is walked (`liftAsyncSubExpressions`): a promise/`AsyncIterable`-typed
+(sub)expression is lifted to an injected peek-cell and rewritten IN PLACE to a bare `__vN`
+reference, so pending reads as `undefined` and composes with `??`/`?.`. A leading `await` marks the
+SSR BLOCKING tier; no `await` is STREAMING. Runs even without a classifier — then only syntactic
+`await`s lift (fail-open), matching the pre-classifier path for everything else.
+*/
+export function lowerAsyncInterpolations(
+    nodes: TemplateNode[],
+    classify: InterpolationClassifier | undefined,
+): LoweredInterpolations {
+    const counter = { n: 0 }
+    const mint = (): string => `__v${counter.n++}`
+    const cells: InjectedCell[] = []
+    lowerList(nodes, classify, mint, cells)
+    return { nodes, cells }
+}
+
+/* Lifts every async (sub)expression in a sibling list, then recurses into children. Each node's
+   async-liftable fields come from the shared `asyncInterpolationFields` plan (the single reading the
+   shadow front-end also drives from), so the two can't disagree on which interpolations are async;
+   this side owns the RENDERING — lift the field to a peek-cell, write the `__vN` reference back, and
+   for a control-flow subject that collapsed to one bare cell mark `asyncSubject`. */
+function lowerList(
+    nodes: TemplateNode[],
+    classify: InterpolationClassifier | undefined,
+    mint: () => string,
+    cells: InjectedCell[],
+): void {
+    for (const node of nodes) {
+        for (const field of asyncInterpolationFields(node)) {
+            const lifted = cells.length
+            const result = liftAsyncSubExpressions(
+                field.code,
+                field.loc,
+                classify,
+                mint,
+                field.position,
+            )
+            for (const lift of result.lifts) {
+                cells.push(lift)
+            }
+            field.write(result.code)
+            if (field.subject) {
+                field.setAsyncSubject(isBareLiftedCell(result.code, cells, lifted))
+            }
+        }
+        if ('children' in node) {
+            lowerList(node.children, classify, mint, cells)
+        }
+    }
+}
+
+/* True when a control-flow subject's WHOLE expression was lifted to one peek-cell — the
+   rewritten code is exactly a single injected name (`{#if getX()}` → `__v3`), not a compound
+   the peek composes into (`{#if getX()?.ok}` → `__v3?.ok`, still the falsy-else peek). `cells`
+   past index `lifted` are the ones this subject minted, so an equal name means the subject IS
+   that bare cell. Only then do the back-ends read its pending facet to hold the block. */
+function isBareLiftedCell(code: string, cells: InjectedCell[], lifted: number): boolean {
+    const name = code.trim()
+    for (let index = lifted; index < cells.length; index++) {
+        if (cells[index]?.name === name) {
+            return true
+        }
+    }
+    return false
+}

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

@@ -25,6 +25,8 @@ export function lowerContext(
     stateNames: ReadonlySet<string>,
     derivedNames: ReadonlySet<string>,
     computedNames: ReadonlySet<string> = new Set(),
+    /* `linked` / async `computed` names, read through `$$readCell(name)`. */
+    cellReadNames: ReadonlySet<string> = new Set(),
 ) {
     /* The typed branch-local shadow stack: one auto-popping value owning both kinds.
        `derived` names deref to `.value` like a `computed` (block value params the client
@@ -48,6 +50,7 @@ export function lowerContext(
                 computedNames,
                 new Set(scope.names('derived')),
                 new Set(scope.names('plain')),
+                cellReadNames,
             ),
             docAccessTransformer('$$model'),
         ])
@@ -101,6 +104,13 @@ export function lowerContext(
             return `(${expression(code)}).set(${valueExpr});`
         }
         guardWritableBind(code)
+        /* A `linked` cell (a writable `State`) is read through `$$readCell`, but that call is
+           not an lvalue — the WRITE goes straight to the cell's `.value` setter (`NAME.value =
+           …`). The name is a real local holding the cell, so it needs no reference lowering. */
+        const name = code.trim()
+        if (cellReadNames.has(name)) {
+            return `${name}.value = ${valueExpr};`
+        }
         return statement(`${code} = ${valueExpr}`)
     }
 

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

@@ -1,6 +1,5 @@
 import ts from 'typescript'
 import { escapeKey } from '../runtime/escapeKey.ts'
-import { TS_PRINTER } from './TS_PRINTER.ts'
 
 /*
 The linchpin compiler pass. Rewrites idiomatic data access on a reactive document
@@ -23,15 +22,10 @@ many — literal keys at compile time, dynamic ones wrapped in a runtime
 `escapeKey(...)`. Reads are lowered to `read(path)`; a later pass hoists
 static-path reads to a `cell` bound once at component init (the string-free hot
 path the bench measured). Index expressions are themselves visited, so a read
-used as an index lowers too.
+used as an index lowers too. Exposed as `docAccessTransformer` (a
+`ts.TransformerFactory`) so the script pipeline chains it after
+`signalRefsTransformer` over a single parsed tree (see `lowerScript`).
 */
-export function lowerDocAccess(code: string, docName: string): string {
-    const source = ts.createSourceFile('component.ts', code, ts.ScriptTarget.Latest, true)
-    const result = ts.transform(source, [docAccessTransformer(docName)])
-    const output = TS_PRINTER.printFile(result.transformed[0] as ts.SourceFile)
-    result.dispose()
-    return output
-}
 
 /* A path segment is either a literal key or a runtime expression (a dynamic index). */
 type Segment = { kind: 'literal'; value: string } | { kind: 'expression'; node: ts.Expression }
@@ -39,6 +33,30 @@ type Segment = { kind: 'literal'; value: string } | { kind: 'expression'; node:
 /* Maps a compound-assignment operator to its plain binary counterpart. Logical
    assignments (`||=`/`&&=`/`??=`) lower to an unconditional replace of the
    combined value — consistent with how `+=` lowers (the patch always writes). */
+/* Methods that mutate a doc-rooted container in place — Array, Map and Set (the three
+   mutable containers the doc codec serializes). Called on a doc value these can't lower to
+   a bare `readCall` (which would mutate the live tree by reference and never emit a patch —
+   so nothing re-renders); they route through `$$mutateDocContainer`, which
+   clones-applies-replaces so a real patch fires. The names are disjoint across the three
+   container kinds, so one set routes them all and the runtime helper decides the kind by the
+   value's type. `push` is handled separately above (fine-grained `add` patches). */
+const MUTATING_CONTAINER_METHODS = new Set([
+    // Array
+    'pop',
+    'shift',
+    'unshift',
+    'splice',
+    'sort',
+    'reverse',
+    'fill',
+    'copyWithin',
+    // Map / Set (`delete` + `clear` shared; `set` is Map, `add` is Set)
+    'set',
+    'add',
+    'delete',
+    'clear',
+])
+
 const COMPOUND_OPERATORS = new Map<ts.SyntaxKind, ts.BinaryOperator>([
     [ts.SyntaxKind.PlusEqualsToken, ts.SyntaxKind.PlusToken],
     [ts.SyntaxKind.MinusEqualsToken, ts.SyntaxKind.MinusToken],
@@ -151,6 +169,7 @@ export function docAccessTransformer(docName: string): ts.TransformerFactory<ts.
                     )
                     /* `node.arguments.length > 0` above guarantees `adds` is non-empty, so the
                        single-element branch's `adds[0]` is defined. */
+                    // biome-ignore lint/style/noNonNullAssertion: length === 1 guarantees adds[0] is defined
                     return adds.length === 1 ? adds[0]! : ts.factory.createCommaListExpression(adds)
                 }
             }
@@ -162,10 +181,32 @@ export function docAccessTransformer(docName: string): ts.TransformerFactory<ts.
                 const access = node.expression
                 const segments = pathSegments(access.expression)
                 if (segments) {
-                    const read = docCall(docName, 'read', [buildPath(segments)])
                     const args = node.arguments.map(
                         (arg) => ts.visitNode(arg, visit) as ts.Expression,
                     )
+                    /* An in-place-mutating container method (Array/Map/Set) on a doc path →
+                       route through `$$mutateDocContainer(doc, path, member, [args])` so the
+                       mutation lands as a patch instead of silently mutating the live tree by
+                       reference. Optional chaining (`model.items?.splice(…)`) keeps the bare-call
+                       semantics below — skip-if-absent is the author's explicit choice, and a
+                       nullish container has nothing to mutate. */
+                    if (
+                        MUTATING_CONTAINER_METHODS.has(access.name.text) &&
+                        !access.questionDotToken &&
+                        !node.questionDotToken
+                    ) {
+                        return ts.factory.createCallExpression(
+                            ts.factory.createIdentifier('$$mutateDocContainer'),
+                            undefined,
+                            [
+                                ts.factory.createIdentifier(docName),
+                                buildPath(segments),
+                                ts.factory.createStringLiteral(access.name.text),
+                                ts.factory.createArrayLiteralExpression(args),
+                            ],
+                        )
+                    }
+                    const read = docCall(docName, 'read', [buildPath(segments)])
                     /* Optional chaining is the author's explicit skip-if-absent: a nullish
                        read short-circuits the whole call to `undefined`. Keep it bare —
                        routing it through the throwing guard would invert that semantics.

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

@@ -7,12 +7,13 @@ import { docAccessTransformer } from './lowerDocAccess.ts'
 import { signalRefsTransformer } from './renameSignalRefs.ts'
 import { stripEffectsTransformer } from './stripEffects.ts'
 import { TS_PRINTER } from './TS_PRINTER.ts'
+import type { SeedTypeClassifier } from './types/SeedTypeClassifier.ts'
 
 /* The `abide/ui/*` modules the reactive surface is imported from. An author's import of
    one is compiler-recognised and lowered, so its binding is often fully consumed — a plain
    `state(...)` becomes `$$model`/`$$scope` with no `state` reference left. Such a dead
-   import is dropped from the emitted module (see `deadReactiveImport`) so the output has no
-   spurious static `@abide/ui` dependency — load-bearing for hot modules, which forbid one. */
+   import is dropped from the emitted module (see `deadReactiveImport`) so the output carries
+   no spurious static `@abide/ui` dependency — a dead import a bundler would still resolve. */
 const REACTIVE_IMPORT_SPECIFIERS = new Set([
     `${ABIDE_PACKAGE_NAME}/ui/state`,
     `${ABIDE_PACKAGE_NAME}/ui/effect`,
@@ -61,6 +62,25 @@ export function lowerScript(
        desugared away. Folded into the dead-import usage check so a live import isn't dropped
        (→ `ReferenceError: state is not defined` in the branch). Empty for a nested script. */
     externalUsage = '',
+    /* Names of synthetic `const __cN = computed(...)` cells `analyzeComponent` prepended for
+       asyncIterable interpolations (ADR-0019 Stage D). `computed` here is an unimported callee,
+       so `desugarSignals` recognizes these declarations by name — routing each to an eager
+       `trackedComputed` stream cell — rather than by import resolution. Empty on every other path. */
+    injectedCellNames: ReadonlySet<string> = new Set(),
+    /* The subset of `injectedCellNames` whose author wrote `await` (ADR-0032): a BLOCKING peek-cell
+       that joins the SSR barrier (resolved inline), vs a streaming one that ships pending. Threaded
+       to `desugarSignals` so `injectedComputedStatements` passes the right `trackedComputed`
+       streaming flag. Empty on every other path. */
+    blockingCellNames: ReadonlySet<string> = new Set(),
+    /* Names the template writes/forwards (`writtenTemplateNames`), so a `props()` binding used
+       two-way is desugared to a writable cell rather than a read-only derive. Empty for a nested
+       script (which declares no props). */
+    templateWrittenNames: ReadonlySet<string> = new Set(),
+    /* Type-directed seed classifier + this script's absolute source base (ADR-0023), threaded
+       to `desugarSignals` so a no-marker `computed(seed)` routes on the seed's checker type.
+       Absent ⇒ fail-open to the `isBareCallComputed` syntax heuristic (today's behavior). */
+    seedClassify?: SeedTypeClassifier,
+    scriptBase = 0,
 ): {
     body: string
     imports: string
@@ -68,13 +88,28 @@ export function lowerScript(
     stateNames: Set<string>
     derivedNames: Set<string>
     computedNames: Set<string>
+    cellReadNames: Set<string>
     droppedReactiveImports: Set<string>
 } {
     const source = ts.createSourceFile('component.ts', scriptBody, ts.ScriptTarget.Latest, true)
-    const { transformer, stateNames, derivedNames, computedNames } = desugarSignals(source)
+    const { transformer, stateNames, derivedNames, computedNames, cellReadNames } = desugarSignals(
+        source,
+        injectedCellNames,
+        blockingCellNames,
+        templateWrittenNames,
+        seedClassify,
+        scriptBase,
+    )
     const result = ts.transform(source, [
         transformer,
-        signalRefsTransformer(stateNames, derivedNames, computedNames),
+        signalRefsTransformer(
+            stateNames,
+            derivedNames,
+            computedNames,
+            new Set(),
+            new Set(),
+            cellReadNames,
+        ),
         docAccessTransformer('$$model'),
     ])
     const transformed = result.transformed[0] as ts.SourceFile
@@ -126,6 +161,7 @@ export function lowerScript(
         stateNames,
         derivedNames,
         computedNames,
+        cellReadNames,
         droppedReactiveImports,
     }
 }

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

@@ -0,0 +1,28 @@
+import type ts from 'typescript'
+
+/*
+Finds the shadow AST node for a template interpolation given its span in shadow
+coordinates. An interpolation is emitted as a parenthesised expression, so the
+node we want starts and ends exactly on the span; we descend only into nodes that
+still cover the whole span and keep the deepest exact match (the innermost node
+whose `getStart()/getEnd()` equal the span bounds).
+*/
+export function nodeAtShadowOffset(
+    sourceFile: ts.SourceFile,
+    offset: number,
+    length: number,
+): ts.Node | undefined {
+    let best: ts.Node | undefined
+    const visit = (node: ts.Node): void => {
+        const start = node.getStart(sourceFile)
+        const end = node.getEnd()
+        if (start <= offset && end >= offset + length) {
+            if (start === offset && end === offset + length) {
+                best = node
+            }
+            node.forEachChild(visit)
+        }
+    }
+    visit(sourceFile)
+    return best
+}