@abide/abide 0.54.0 → 0.56.0

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

@@ -28,9 +28,9 @@ export function shadowInterpolationClassifier(
         return undefined
     }
     const checker = program.getTypeChecker()
+    const mappings = shadows.get(abidePath)?.mappings ?? []
     return (loc, code) => {
         try {
-            const mappings = shadows.get(abidePath)?.mappings ?? []
             const offset = sourceToShadowOffset(mappings, loc)
             if (offset === undefined) {
                 return 'sync'

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

@@ -26,12 +26,10 @@ export type AnalyzedComponent = {
     computedNames: Set<string>
     /* Component signals read through `$$readCell(name)`: every `linked` and every async
        `computed`. Threaded to both back-ends so a template reference (`{draft}`) lowers to
-       the unified cell read consistently on client and server. */
+       the unified cell read consistently on client and server. Whether a pending read pauses
+       (blocking `await`) or peeks (streaming) is decided at runtime by the cell's own
+       `blocking` bit (ADR-0042), so no blocking subset is threaded through codegen. */
     cellReadNames: Set<string>
-    /* The subset of `cellReadNames` that are BLOCKING `await` cells (ADR-0042): a template-injected
-       `{await X}` cell or a script `computed(await …)`. The CLIENT back-end reads these via
-       `$$readCellBlocking` (suspend-on-pending) rather than `$$readCell`. */
-    blockingCellNames: Set<string>
     nodes: TemplateNode[]
     /* One entry per non-empty `<style>` in the template (in source order): the scope
        attribute its covered elements carry (annotated onto `nodes`) and the scoped

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

@@ -0,0 +1,44 @@
+import ts from 'typescript'
+import { NESTED_REACTIVE_BINDINGS, resolveReactiveExport } from './resolveReactiveExport.ts'
+import { wrapSeed } from './wrapSeed.ts'
+
+/*
+Normalises every `state.computed(seed)` / `state.linked(seed)` in a nested branch
+`<script>` so a BARE-VALUE seed becomes a thunk (`state.computed(a * 2)` →
+`state.computed(() => a * 2)`), exactly as the top-level desugar (`desugarSignals` via
+`wrapSeed`) does. A nested script keeps its reactive calls literal — it is not desugared to
+the doc — so absent this the bare value reaches the runtime primitive, which stores it as
+the compute function and calls it on read (`a * 2 is not a function`, a runtime crash). A
+literal `() => …` / `function` thunk passes through unchanged, so the wrap is a no-op on the
+already-thunked form the author usually writes.
+
+Recognition is name-based (`NESTED_REACTIVE_BINDINGS`) because a nested script carries no
+import of its own — it inherits the surface by the canonical `state` name, the same way
+`nestedBindingNames` resolves it. Only the seed argument (`arguments[0]`) is wrapped; a
+`state.linked(seed, ...)`'s trailing args pass through. Exposed as a `ts.TransformerFactory`
+so the nested-script lowering can chain it ahead of the reference rename over ONE parsed tree.
+*/
+export function wrapReactiveSeedsTransformer(): ts.TransformerFactory<ts.SourceFile> {
+    return (context) => (root) => {
+        const visit = (node: ts.Node): ts.Node => {
+            if (ts.isCallExpression(node) && node.arguments.length > 0) {
+                const primitive = resolveReactiveExport(node.expression, NESTED_REACTIVE_BINDINGS)
+                if (primitive === 'computed' || primitive === 'linked') {
+                    const seed = node.arguments[0] as ts.Expression
+                    const wrapped = wrapSeed(ts.visitNode(seed, visit) as ts.Expression)
+                    const rest = node.arguments
+                        .slice(1)
+                        .map((argument) => ts.visitNode(argument, visit) as ts.Expression)
+                    return ts.factory.updateCallExpression(
+                        node,
+                        node.expression,
+                        node.typeArguments,
+                        [wrapped, ...rest],
+                    )
+                }
+            }
+            return ts.visitEachChild(node, visit, context)
+        }
+        return ts.visitNode(root, visit) as ts.SourceFile
+    }
+}

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

@@ -0,0 +1,28 @@
+import ts from 'typescript'
+import { hasTopLevelAwait } from './hasTopLevelAwait.ts'
+
+const factory = ts.factory
+
+/* Normalises a `computed`/`linked` argument into a seed THUNK: a literal `() => …` /
+   `function` argument passes through unchanged (the author already wrote the thunk), any
+   other expression is wrapped as `() => arg`. The wrapper arrow is made ASYNC when the
+   expression contains a top-level `await` (`computed(await load())` → `async () => await
+   load()`), which is exactly the marker the runtime primitive uses to route to an async cell.
+   Shared by the top-level desugar (`desugarSignals`) and the nested-`<script>` lowering
+   (`wrapReactiveSeeds`) so a bare-value seed is normalised identically on both surfaces. */
+export function wrapSeed(argument: ts.Expression): ts.Expression {
+    if (ts.isArrowFunction(argument) || ts.isFunctionExpression(argument)) {
+        return argument
+    }
+    const modifiers = hasTopLevelAwait(argument)
+        ? [factory.createModifier(ts.SyntaxKind.AsyncKeyword)]
+        : undefined
+    return factory.createArrowFunction(
+        modifiers,
+        undefined,
+        [],
+        undefined,
+        factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+        argument,
+    )
+}

package/src/lib/ui/computed.ts

@@ -5,6 +5,7 @@ import { createComputedNode } from './runtime/createComputedNode.ts'
 import { isAsyncFunction } from './runtime/isAsyncFunction.ts'
 import { OWNER } from './runtime/OWNER.ts'
 import { readNode } from './runtime/readNode.ts'
+import { routeBareSeed } from './runtime/routeBareSeed.ts'
 import type { Computed } from './runtime/types/Computed.ts'
 import { unlinkDeps } from './runtime/unlinkDeps.ts'
 
@@ -32,6 +33,21 @@ export function computed<T>(compute: () => T): Computed<T>
 export function computed<T>(
     compute: () => T | Promise<T> | NamedAsyncIterable<T>,
 ): Computed<T> | AsyncComputed<T> {
+    /* A BARE seed that reached the runtime literally — a branch-nested `<script>` (which
+       keeps its `state.computed(...)` calls literal; see lowerScript) or a direct JS caller.
+       The compile-time `wrapSeed` normalization only covers the leading script, so honor the
+       same authored contract (ADR-0045: a bare seed behaves like its thunk form) by VALUE via
+       the shared `routeBareSeed`; a non-async value becomes a constant computed over it.
+       Without this a raw value lands as `node.compute` and the first read calls it
+       (`node.compute is 3` — a dead render mid-stream). */
+    if (typeof compute !== 'function') {
+        const seed: unknown = compute
+        const cell = routeBareSeed(seed, false)
+        if (cell !== undefined) {
+            return cell as AsyncComputed<T>
+        }
+        compute = () => seed as T
+    }
     /* `await` marker: an async-function thunk unwraps its promise into a tracked async cell.
        This is the only classification the read-only primitive can make without running the
        seed — a sync `computed` MUST stay lazy (it does not compute until first read). A stream

package/src/lib/ui/createScope.ts

@@ -4,6 +4,7 @@ import { computed } from './computed.ts'
 import { effect } from './effect.ts'
 import { linked } from './linked.ts'
 import { CURRENT_PATH } from './runtime/CURRENT_PATH.ts'
+import { consumeSeed } from './runtime/consumeSeed.ts'
 import { createDoc } from './runtime/createDoc.ts'
 import { DOC_SEED } from './runtime/DOC_SEED.ts'
 import type { Cell } from './runtime/types/Cell.ts'
@@ -50,13 +51,13 @@ export function createScope(
        on the client, so a uuid/timestamp/random would diverge from the SSR HTML. The server snapshot
        for this scope's render-path id is decoded here and consumed by `replace` on each slot's FIRST
        write (the eager init), keeping the server value while the throwaway init is discarded. One-shot
-       — deleted on read so an SPA re-nav to the same path re-inits fresh; empty on the server. */
+       via `consumeSeed` (two-phase, ADR-0048) — an SPA re-nav to the same path re-inits fresh, and a
+       hydration-desync throw hands the seed to the cold rebuild; empty on the server. */
     let pendingSeed: Map<string, unknown> | undefined
     /* `DOC_SEED` is populated only on the client by `startClient` (empty on the server), so the read
        needs no window guard — it mirrors the async-cell warm read. */
-    const encodedSeed = DOC_SEED[id]
+    const encodedSeed = consumeSeed(DOC_SEED, id)
     if (encodedSeed !== undefined) {
-        delete DOC_SEED[id]
         try {
             pendingSeed = new Map(
                 Object.entries(decodeRefJson(encodedSeed) as Record<string, unknown>),

package/src/lib/ui/dom/anchorCursor.ts

@@ -1,3 +1,4 @@
+import { parkCursor } from '../runtime/parkCursor.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 
 /*
@@ -18,7 +19,7 @@ export function anchorCursor(anchor: Node): Node | null {
     const reference = anchor.nextSibling
     const hydration = RENDER.hydration
     if (hydration !== undefined) {
-        hydration.next.set(anchor.parentNode as Node, reference)
+        parkCursor(hydration, anchor.parentNode as Node, reference)
     }
     return reference
 }

package/src/lib/ui/dom/anchoredBranch.ts

@@ -19,9 +19,10 @@ the accidental copy-paste, notably its two subtle guards:
      rethrowing, so the caller's cold rebuild starts clean).
 
 `anchor` is a mutable field: each block parks its own anchor text node at create /
-hydrate / rebuild time (placement is bespoke), and `place` reads it. The block owns its
-`scopeGroup`; each built branch's disposer is tracked in it so it disposes on owner
-teardown, not only on a swap.
+hydrate / rebuild time via `parkAnchor` (WHERE it parks is bespoke — before the boundary
+close, after a discarded boundary, at the create-mode `before`), and `place` reads it. The
+block owns its `scopeGroup`; each built branch's disposer is tracked in it so it disposes
+on owner teardown, not only on a swap.
 */
 export function anchoredBranch(
     parent: Node,
@@ -29,6 +30,7 @@ export function anchoredBranch(
 ): {
     anchor: Node | undefined
     detach: () => void
+    parkAnchor: (before: Node | null) => void
     place: (build: (host: Node) => void, wrapBuild?: (run: () => void) => void) => void
     adoptStrand: (
         build: (host: Node) => void,
@@ -128,6 +130,14 @@ export function anchoredBranch(
         }
     }
 
+    /* Park a fresh empty text node as the branch's swap anchor at `before` (null appends) —
+       the create/hydrate/rebuild triple every block repeated by hand. */
+    const parkAnchor = (before: Node | null): void => {
+        const node = document.createTextNode('')
+        anchor = node
+        parent.insertBefore(node, before)
+    }
+
     return {
         get anchor(): Node | undefined {
             return anchor
@@ -136,6 +146,7 @@ export function anchoredBranch(
             anchor = node
         },
         detach,
+        parkAnchor,
         place,
         adoptStrand,
     }

package/src/lib/ui/dom/appendStatic.ts

@@ -1,34 +1,25 @@
 import { claimChild } from '../runtime/claimChild.ts'
+import { parkCursor } from '../runtime/parkCursor.ts'
 import { RENDER } from '../runtime/RENDER.ts'
-import { assertClaimedText } from './assertClaimedText.ts'
+import { claimText } from './claimText.ts'
 
 /*
 A static (non-reactive) text node under `parent`: created and appended (create
-mode), or claimed from the server-rendered text (hydrate mode). As with reactive
-text, a merged SSR text node is split at this literal's length so the next claim
-lines up; nothing is bound since the text never changes.
+mode), or claimed from the server-rendered text (hydrate mode) — the shared
+`claimText` asserts, splits the merged SSR node at this literal's length so the
+next claim lines up, and advances. Nothing is bound since the text never changes.
+A static always renders on the server, so a non-text node at the cursor is a
+tolerated desync: advance past it (assertClaimedText's domain is a text mismatch;
+a structural one is claimExpected's).
 */
 // @documentation plumbing
 export function appendStatic(parent: Node, value: string, splitAlways = false): void {
     const hydration = RENDER.hydration
     if (hydration !== undefined) {
-        const node = claimChild(hydration, parent) as unknown as Text
-        const isText = node !== null && typeof node.splitText === 'function'
-        /* The claimed SSR node must begin with this literal, or the split misaligns — throw
-           legibly at the divergence (only when a text node is actually here; a structural
-           mismatch is claimExpected's domain). */
-        if (isText) {
-            assertClaimedText(node, value)
+        if (claimText(hydration, parent, value, splitAlways) === undefined) {
+            const node = claimChild(hydration, parent)
+            parkCursor(hydration, parent, node === null ? null : node.nextSibling)
         }
-        /* Split even on an exact-length consume when a sibling text binding follows
-           (`splitAlways`), so it gets its own node; see appendText for the rationale. */
-        if (
-            isText &&
-            (splitAlways ? value.length <= node.data.length : value.length < node.data.length)
-        ) {
-            node.splitText(value.length)
-        }
-        hydration.next.set(parent, node === null ? null : node.nextSibling)
         return
     }
     parent.appendChild(document.createTextNode(value))

package/src/lib/ui/dom/appendText.ts

@@ -2,10 +2,11 @@ import { rawHtmlString } from '../../shared/html.ts'
 import { snippetPayload } from '../../shared/snippet.ts'
 import { effect } from '../effect.ts'
 import { claimChild } from '../runtime/claimChild.ts'
+import { parkCursor } from '../runtime/parkCursor.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { SuspenseSignal } from '../runtime/SuspenseSignal.ts'
 import { appendSnippet } from './appendSnippet.ts'
-import { assertClaimedText } from './assertClaimedText.ts'
+import { claimText } from './claimText.ts'
 import { isComment } from './isComment.ts'
 import { parseRawNodes } from './parseRawNodes.ts'
 import { readTextOrSuspend } from './readTextOrSuspend.ts'
@@ -34,7 +35,15 @@ cold client render (on hydrate the warm-seed makes the cell `refreshing()`, not
 decided from the first resolved value.
 */
 // @documentation plumbing
-export function appendText(parent: Node, read: () => unknown, splitAlways = false): void {
+export function appendText(
+    parent: Node,
+    read: () => unknown,
+    splitAlways = false,
+    /* Create-mode insertion reference: content lands before this node instead of at the end of
+       `parent` (`null` appends). Lets `appendTextAt` mount at a skeleton anchor through this one
+       create path. Ignored on hydrate, where the cursor decides position. */
+    before: Node | null = null,
+): void {
     /* Probe the first value once, tolerating a suspend (a pending blocking read) — a suspended
        interpolation skips snippet/html detection and takes the text path, starting empty. */
     let probe: unknown
@@ -50,62 +59,51 @@ export function appendText(parent: Node, read: () => unknown, splitAlways = fals
     /* A snippet call (`{row(args)}`) mounts its builder; a `html\`\`` value inserts
        raw markup; everything else is escaped text — decided by the first value. */
     if (!suspended && typeof snippetPayload(probe) === 'function') {
-        appendSnippet(parent, read)
+        if (before === null) {
+            appendSnippet(parent, read)
+            return
+        }
+        /* Positioned mount: buffer the snippet in a fragment, then splice it in at `before` —
+           `appendSnippet` itself only appends, and its markers track position from then on. */
+        const fragment = document.createDocumentFragment()
+        appendSnippet(fragment, read)
+        parent.insertBefore(fragment, before)
         return
     }
     if (!suspended && rawHtmlString(probe) !== undefined) {
-        appendRawHtml(parent, read)
+        appendRawHtml(parent, read, before)
         return
     }
     const hydration = RENDER.hydration
     if (hydration !== undefined) {
-        const claimed = claimChild(hydration, parent)
         /* Nullish reads render as empty text, never the literal `"undefined"` — so a
            pending async read (undefined-while-pending, ADR-0032 D3) shows nothing. A blocking
            read never suspends here (warm-seeded → `refreshing()`), so `probe` holds its value. */
         const firstValue = probe
         const value = firstValue == null ? '' : String(firstValue)
-        /* A value that first rendered empty produced NO server text node, so the cursor
-           points at the following node (an element/comment) or past the end (null) — not a
-           text node to claim. Bind to a Text node either way: claim the merged SSR node when
-           one is here, else synthesize an empty one at the cursor and leave the claimed node
-           for the next consumer (a following element hole, a sibling binding, or nothing).
-           Without this the bind effect below derefs a null/element `node`. A text node is
-           detected by `splitText` (not `nodeType`), so the test mini-dom is covered too. */
-        const isText = claimed !== null && typeof (claimed as Text).splitText === 'function'
-        const node = (
-            isText ? claimed : parent.insertBefore(document.createTextNode(''), claimed)
-        ) as Text
-        /* The claimed SSR node must begin with this binding's value, or the split below
-           lands mid-run and orphans the tail — throw legibly at the divergence instead. A
-           synthesized empty node is this binding's own, so there's nothing to disagree. */
-        if (isText) {
-            assertClaimedText(node, value)
-        }
-        /* Peel this binding's text off the merged SSR node. A non-final binding in a
-           run (`splitAlways`) splits even when it consumes the whole node, leaving an
-           empty node for the next binding — otherwise an interpolation that renders to
-           empty string (or whose followers do) has no node and the next claim grabs the
-           wrong sibling. The final binding keeps `<` so it doesn't leave a stray node a
-           following element would claim. A synthesized node is already this binding's own,
-           so it never splits. */
-        if (
-            isText &&
-            (splitAlways ? value.length <= node.data.length : value.length < node.data.length)
-        ) {
-            node.splitText(value.length)
+        /* Claim this binding's portion of the merged SSR text node (assert + split +
+           advance — see `claimText`). A value that first rendered empty produced NO server
+           text node, so the cursor points at the following node (an element/comment) or past
+           the end — the miss arm: bind a synthesized empty Text at the cursor and leave the
+           unclaimed node for the next consumer (a following element hole, a sibling binding,
+           or nothing). Without it the bind effect below derefs a null/element node. */
+        let node = claimText(hydration, parent, value, splitAlways)
+        if (node === undefined) {
+            const unclaimed = claimChild(hydration, parent)
+            node = parent.insertBefore(document.createTextNode(''), unclaimed)
+            /* Pin the cursor on the still-unclaimed node — the synthesized node is this
+               binding's own, and an unset cursor would default back to the (now synthesized)
+               first child. */
+            parkCursor(hydration, parent, unclaimed)
         }
-        /* Advance past the claimed text node; for a synthesized node leave the cursor on the
-           still-unclaimed `claimed` node it was inserted before (an element/comment, or null
-           at the end). */
-        hydration.next.set(parent, isText ? node.nextSibling : claimed)
+        const bound = node
         effect(() => {
-            node.data = readTextOrSuspend(read)
+            bound.data = readTextOrSuspend(read)
         })
         return
     }
     const node = document.createTextNode('')
-    parent.appendChild(node)
+    parent.insertBefore(node, before)
     effect(() => {
         node.data = readTextOrSuspend(read)
     })
@@ -113,7 +111,7 @@ export function appendText(parent: Node, read: () => unknown, splitAlways = fals
 
 /* Raw-markup interpolation: parse the branded string into nodes behind an anchor,
    re-parsing on change; on hydrate adopt the server markup between its markers. */
-function appendRawHtml(parent: Node, read: () => unknown): void {
+function appendRawHtml(parent: Node, read: () => unknown, before: Node | null): void {
     const hydration = RENDER.hydration
     const markup = (): string => rawHtmlString(read()) ?? ''
     const anchor = document.createTextNode('')
@@ -141,7 +139,7 @@ function appendRawHtml(parent: Node, read: () => unknown): void {
             nodes.push(node)
             node = node.nextSibling
         }
-        hydration.next.set(parent, node === null ? null : node.nextSibling)
+        parkCursor(hydration, parent, node === null ? null : node.nextSibling)
         parent.insertBefore(anchor, node)
         let first = true
         effect(() => {
@@ -155,7 +153,7 @@ function appendRawHtml(parent: Node, read: () => unknown): void {
         return
     }
 
-    parent.appendChild(anchor)
+    parent.insertBefore(anchor, before)
     effect(() => {
         set(markup())
     })

package/src/lib/ui/dom/appendTextAt.ts

@@ -1,12 +1,6 @@
-import { rawHtmlString } from '../../shared/html.ts'
-import { snippetPayload } from '../../shared/snippet.ts'
-import { effect } from '../effect.ts'
+import { parkCursor } from '../runtime/parkCursor.ts'
 import { RENDER } from '../runtime/RENDER.ts'
-import { SuspenseSignal } from '../runtime/SuspenseSignal.ts'
-import { appendSnippet } from './appendSnippet.ts'
 import { appendText } from './appendText.ts'
-import { parseRawNodes } from './parseRawNodes.ts'
-import { readTextOrSuspend } from './readTextOrSuspend.ts'
 
 /*
 A reactive `{expr}` interpolation mounted at a skeleton anchor comment (`<!--a-->`), used
@@ -20,67 +14,26 @@ The anchor is KEPT (in both the SSR markup and the client DOM, like control flow
 `<!--[-->` range markers), so server and client render identical markup — `appendTextAt`
 never strips it.
 
-Hydrate delegates to `appendText` with the cursor temporarily pointed at the anchor's
-content (the server rendered `<!--a-->value`, so the value is the anchor's next sibling),
-reusing its text-split / snippet / raw-html claiming.
+Both paths delegate to `appendText`: hydrate with the cursor temporarily pointed at the
+anchor's content (the server rendered `<!--a-->value`, so the value is the anchor's next
+sibling), create with the anchor's next sibling as the insertion reference — one
+text-split / snippet / raw-html implementation, positioned two ways.
 */
 // @documentation plumbing
 export function appendTextAt(anchor: Node, read: () => unknown): void {
     const parent = anchor.parentNode as Node
-    if (RENDER.hydration !== undefined) {
-        const hydration = RENDER.hydration
+    const hydration = RENDER.hydration
+    if (hydration !== undefined) {
         const had = hydration.next.has(parent)
         const saved = hydration.next.get(parent)
-        hydration.next.set(parent, anchor.nextSibling)
+        parkCursor(hydration, parent, anchor.nextSibling)
         appendText(parent, read)
         if (had) {
-            hydration.next.set(parent, saved ?? null)
+            parkCursor(hydration, parent, saved ?? null)
         } else {
             hydration.next.delete(parent)
         }
         return
     }
-
-    /* Probe once, tolerating a suspend (a pending blocking read): a suspended interpolation skips
-       snippet/html detection and takes the text path, starting empty until the value resolves. */
-    let first: unknown
-    let suspended = false
-    try {
-        first = read()
-    } catch (signal) {
-        if (!(signal instanceof SuspenseSignal)) {
-            throw signal
-        }
-        suspended = true
-    }
-    if (!suspended && typeof snippetPayload(first) === 'function') {
-        const fragment = document.createDocumentFragment()
-        appendSnippet(fragment, read)
-        parent.insertBefore(fragment, anchor.nextSibling)
-        return
-    }
-    if (!suspended && rawHtmlString(first) !== undefined) {
-        let nodes: Node[] = []
-        effect(() => {
-            for (const node of nodes) {
-                parent.removeChild(node)
-            }
-            nodes = parseRawNodes(parent, rawHtmlString(read()) ?? '')
-            /* Insert the fresh markup just after the anchor (its live re-insertion point). */
-            const after = anchor.nextSibling
-            for (const node of nodes) {
-                parent.insertBefore(node, after)
-            }
-        })
-        return
-    }
-    const node = document.createTextNode('')
-    parent.insertBefore(node, anchor.nextSibling)
-    /* Text/suspend handling shared with `appendText`'s bind via `readTextOrSuspend`: stringify the
-       value, show '' while a blocking read is pending (re-running on settle, since the read tracked
-       its cell), and coerce nullish to '' (never the literal "undefined") — keeping this create path
-       congruent with the hydrate path above, which delegates to `appendText`. */
-    effect(() => {
-        node.data = readTextOrSuspend(read)
-    })
+    appendText(parent, read, false, anchor.nextSibling)
 }