@abide/abide 0.48.0 → 0.50.0

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

@@ -46,7 +46,17 @@ export type TemplateNode =
           keyLoc?: number
           indexLoc?: number
       }
-    | { kind: 'if'; condition: string; children: TemplateNode[]; loc?: number }
+    | {
+          kind: 'if'
+          condition: string
+          children: TemplateNode[]
+          loc?: number
+          /* `condition` is a bare async subject — the WHOLE test was one promise/stream that
+             `lowerAsyncInterpolations` lifted to a single peek-cell (`{#if getX()}`). The binary
+             back-ends then read its pending facet so a still-loading subject renders NO branch,
+             not the falsy `{:else}`. Unset (or on an `{:elseif}` chain) → the plain truthy test. */
+          asyncSubject?: boolean
+      }
     | {
           kind: 'await'
           promise: string
@@ -77,11 +87,29 @@ export type TemplateNode =
           loc?: number
           /* Each authored attribute as a prop. A `spread` entry (`{...code}`) carries no
              `name`; its keys merge in at runtime (`mergeProps`/`spreadProps`). `nameLoc` is
-             the prop name's source offset — the anchor for an excess-prop diagnostic. */
-          props: { name: string; code: string; loc?: number; nameLoc?: number; spread?: boolean }[]
+             the prop name's source offset — the anchor for an excess-prop diagnostic. `bind`
+             marks a `bind:<name>={target}` two-way prop: `code` is the writable target (an
+             lvalue or a `{ get, set }` accessor), passed with a write-back channel so the
+             child can push changes upstream (`bindProp`/`bindableProp`). */
+          props: {
+              name: string
+              code: string
+              loc?: number
+              nameLoc?: number
+              spread?: boolean
+              bind?: true
+          }[]
           children: TemplateNode[]
       }
-    | { kind: 'switch'; subject: string; children: TemplateNode[]; loc?: number }
+    | {
+          kind: 'switch'
+          subject: string
+          children: TemplateNode[]
+          loc?: number
+          /* `subject` is a bare async subject (the whole expression lifted to one peek-cell) —
+             a still-loading subject selects no case (not even the default) until it settles. */
+          asyncSubject?: boolean
+      }
     /* A branch of a `<template switch>` (`match` set) or `<template if>` chain. Inside an
        `if`, `<template elseif={c}>` sets `condition` (match-less, truthy-tested), and
        `<template else>` leaves both unset (the default). `loc` points at whichever
@@ -92,6 +120,10 @@ export type TemplateNode =
           condition?: string
           children: TemplateNode[]
           loc?: number
+          /* An `{:elseif}` whose `condition` is a bare async subject (the whole test lifted to one
+             peek-cell) — the cond-chain holds at this branch while the cell is pending, resuming the
+             top-down walk (skip it / match it / fall to the next branch) once it settles. */
+          asyncSubject?: boolean
       }
     /* A `{#snippet row(item)}` snippet: a named, scope-capturing builder declared
        once and called like a function (`{row(item)}`). `params` is the raw

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

@@ -0,0 +1,13 @@
+/*
+A template interpolation sitting in a NON-content value position — where a
+`Promise`/`AsyncIterable` can't be rendered over time and would silently stringify
+to `[object Promise]` (Stage E of type-directed lowering, ADR-0019). `loc`/`code`
+are the expression's source offset and verbatim text (the classifier's key), and
+`position` names the position for the diagnostic. `for await` is the sanctioned
+`{#for await}` iterable — the one value position where an `AsyncIterable` is allowed.
+*/
+export type ValuePositionInterpolation = {
+    loc: number
+    code: string
+    position: 'attribute' | 'if' | 'switch' | 'each' | 'for await'
+}

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

@@ -0,0 +1,84 @@
+import ts from 'typescript'
+import { assignmentTargetNames } from './assignmentTargetNames.ts'
+import { isPlainIdentifier } from './isPlainIdentifier.ts'
+import type { TemplateNode } from './types/TemplateNode.ts'
+
+/*
+Every name the TEMPLATE writes — the counterpart to the leading script's own write
+scan. Two ways a prop's name shows up written in markup:
+  • forwarded as a `bind:` target — `bind:value={value}` on a child element or component
+    passes the name as a two-way target, so it must be a writable cell (a bare identifier
+    only; a `{ get, set }` accessor carries its own write path and reads the prop plainly);
+  • assigned in a template expression — an event handler like `onclick={() => value += 1}`.
+
+Collected across every JS fragment the markup carries (attribute/prop/event/text
+expressions and nested `<script>` bodies), then intersected with the actual prop names by
+the caller. Syntactic and conservative — see `assignmentTargetNames`.
+*/
+export function writtenTemplateNames(nodes: TemplateNode[]): Set<string> {
+    const names = new Set<string>()
+    /* One synthetic source of every expression fragment, parsed once for its write targets. */
+    let fragments = ''
+    const addFragment = (code: string | undefined): void => {
+        if (code !== undefined && code.trim() !== '') {
+            fragments += `${code};\n`
+        }
+    }
+    /* A bare-identifier `bind:` target names a prop forwarded as a two-way channel. */
+    const addBindTarget = (code: string): void => {
+        if (isPlainIdentifier(code.trim())) {
+            names.add(code.trim())
+        }
+    }
+    const walk = (node: TemplateNode): void => {
+        if (node.kind === 'text') {
+            for (const part of node.parts) {
+                if (part.kind === 'expression') {
+                    addFragment(part.code)
+                }
+            }
+            return
+        }
+        if (node.kind === 'script') {
+            addFragment(node.code)
+            return
+        }
+        if (node.kind === 'element') {
+            for (const attr of node.attrs) {
+                if (attr.kind === 'bind') {
+                    addBindTarget(attr.code)
+                    addFragment(attr.code)
+                } else if (attr.kind === 'interpolated') {
+                    for (const part of attr.parts) {
+                        if (part.kind === 'expression') {
+                            addFragment(part.code)
+                        }
+                    }
+                } else if (attr.kind !== 'static') {
+                    addFragment(attr.code)
+                }
+            }
+        }
+        if (node.kind === 'component') {
+            for (const prop of node.props) {
+                if (prop.bind === true) {
+                    addBindTarget(prop.code)
+                }
+                addFragment(prop.code)
+            }
+        }
+        if ('children' in node) {
+            for (const child of node.children) {
+                walk(child)
+            }
+        }
+    }
+    for (const node of nodes) {
+        walk(node)
+    }
+    if (fragments.trim() !== '') {
+        const source = ts.createSourceFile('template.ts', fragments, ts.ScriptTarget.Latest, true)
+        assignmentTargetNames(source, names)
+    }
+    return names
+}

package/src/lib/ui/computed.ts

@@ -1,4 +1,8 @@
+import type { AsyncComputed } from '../shared/types/AsyncComputed.ts'
+import type { NamedAsyncIterable } from '../shared/types/NamedAsyncIterable.ts'
+import { createAsyncCell } from './runtime/createAsyncCell.ts'
 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 type { Computed } from './runtime/types/Computed.ts'
@@ -13,8 +17,31 @@ would be a write to its *sources*, which is expressed at the binding site instea
 (`bind:value={{ get, set }}`), where the write actually originates. Lazy: it
 recomputes on read only when a dependency changed, and never serializes (it is
 re-derived from its inputs on resume). Read via `.value`.
+
+When the seed *tracks* an async source it becomes an async cell instead (ADR-0019
+D1): an `async () => await …` thunk (the compiler's `await` lowering) unwraps the
+promise, and a thunk producing a `NamedAsyncIterable` (socket / streaming rpc)
+auto-tracks its frames. Both yield an `AsyncComputed<T>` — no `.value`, read through
+the probe family (`peek`/`pending`/`refreshing`/`error`/`refresh`). A thunk that
+returns a *bare* promise (no `await`) is held opaquely as a normal `Computed<Promise<T>>`
+— render it with `{#await}`.
 */
-export function computed<T>(compute: () => T): Computed<T> {
+export function computed<T>(compute: () => NamedAsyncIterable<T>): AsyncComputed<T>
+export function computed<T>(compute: () => Promise<T>): AsyncComputed<T>
+export function computed<T>(compute: () => T): Computed<T>
+export function computed<T>(
+    compute: () => T | Promise<T> | NamedAsyncIterable<T>,
+): Computed<T> | AsyncComputed<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
+       seed (`computed(getStream())`) can only be told from a sync seed by running it, which
+       laziness forbids here; the compiler routes that eager path to `createAsyncCell` directly.
+       A bare (un-awaited) promise stays a lazy `Computed<Promise<T>>` — render it with `{#await}`. */
+    if (isAsyncFunction(compute)) {
+        return createAsyncCell(compute as () => unknown, { writable: false }) as AsyncComputed<T>
+    }
+    /* Sync value or a bare (opaque) promise: the lazy computed, unchanged. */
     const node = createComputedNode(compute as () => unknown)
     /* Tear down with the enclosing scope, the way an effect does. A computed only
        unlinks from its sources when it re-runs (`runNode` re-tracking); one read

package/src/lib/ui/createScope.ts

@@ -1,62 +1,68 @@
 import { computed } from './computed.ts'
 import { effect } from './effect.ts'
-import { history } from './history.ts'
 import { linked } from './linked.ts'
-import { persist as persistDoc } from './persist.ts'
+import { CURRENT_PATH } from './runtime/CURRENT_PATH.ts'
 import { createDoc } from './runtime/createDoc.ts'
-import { liveScopes } from './runtime/liveScopes.ts'
 import type { Cell } from './runtime/types/Cell.ts'
 import type { Doc } from './runtime/types/Doc.ts'
 import { state } from './state.ts'
-import { sync } from './sync.ts'
-import type { History } from './types/History.ts'
-import type { PersistHandle } from './types/PersistHandle.ts'
+import { trackedComputed } from './trackedComputed.ts'
 import type { Scope } from './types/Scope.ts'
 
-/* A process-stable counter id. The serialization-stable LEXICAL id (route +
-   component + tree position) that `persist`/`broadcast` want across reloads/peers
-   is stamped by the compiler later; until then a scope's id is unique within a
-   run — enough for in-session undo and the bus, and as an explicit key's fallback. */
+/* The counter fallback for a DETACHED scope — one created outside any render (a bare
+   `scope()` on first use), where the ambient render-path is empty.
+   A rendered scope instead takes the serialization-stable render-path id (`CURRENT_PATH`,
+   route + tree position), so an async cell's warm-seed key (`${scope.id}:${index}`) is
+   stable across the SSR→client handoff; only the counter path remains merely run-unique. */
 let nextId = 0
 
 /*
 Builds a lexical scope. Its data is a document — created eagerly from `initial`,
 or (when `awaiting`) ADOPTED from the first `doc()` a component body creates under
 it, so a scope can wrap the component's own model without changing the data
-lowering. Data methods mirror `Doc` and delegate to that document; capabilities
-are lazy (`record`/`persist` attach `history`/`persist` to it on first call);
-`child` nests; `dispose` tears the subtree down children-first.
+lowering. Data methods mirror `Doc` and delegate to that document; `child` nests;
+`dispose` tears the subtree down children-first.
 */
 export function createScope(
     initial: unknown = {},
     parent: Scope | undefined = undefined,
     awaiting = false,
-    label: string | undefined = undefined,
 ): Scope {
     /* Eager unless awaiting adoption; `data()` lazily mints an empty doc if a body
        never created one (a stateless component that still reaches for its scope). */
     let document: Doc | undefined = awaiting ? undefined : createDoc(initial)
     const data = (): Doc => (document ??= createDoc({}))
-    const id = parent === undefined ? `scope-${nextId++}` : `${parent.id}.${nextId++}`
-    const children: Scope[] = []
+    /* The scope's serialization-stable id: the ambient render-path when created inside a render
+       (route + layout + branch/row + component ordinal, composed by `withPath` at each nesting
+       site), else the run-unique counter for a detached scope. Snapshotted at creation, so a
+       nested push doesn't mutate an ancestor's id. */
+    const renderPath = CURRENT_PATH.current
+    const id =
+        renderPath !== ''
+            ? renderPath
+            : parent === undefined
+              ? `scope-${nextId++}`
+              : `${parent.id}.${nextId++}`
     /* Adopted build teardowns (the reactivity stopper from the mount core). Disposed
-       first and in reverse on teardown, before children and capabilities — so the one
-       `dispose` runs the order the call sites hand-composed as `stop(); lexical.dispose()`. */
+       first and in reverse on teardown — so the one `dispose` runs the order the call sites
+       hand-composed as `stop(); lexical.dispose()`. */
     const owned: Array<() => void> = []
     /* Context values shared down the tree, held apart from the reactive doc (which
        a child does not inherit): keyed by name, read by the closest ancestor walk. */
     const shared = new Map<string, unknown>()
-    let past: History | undefined
-    let persistence: PersistHandle | undefined
-    let unsync: (() => void) | undefined
+    /* Per-component monotonic index for the async cells constructed under this scope, in
+       declaration order — the local half of a cell's serialization-stable warm-seed key
+       (`${scope.id}:${index}`, see `createAsyncCell`). Per-scope (not global) so a client-only
+       sibling component can't shift another component's cell keys: divergence stays local. Both
+       SSR and client construct a component's cells in the same order, so the indices agree. */
+    let cellIndex = 0
 
-    /* `cell` is not on the public `Scope` type — it is the compiler-only leaf the
-       cell-hoisting lowering targets (`const _cell0 = $$scope().cell("path")`, see
-       `hoistCells`). It stays on the runtime object but off the documented surface,
-       so authors reach data through `read`/`replace`/`derive`, not a raw cell handle. */
-    const self: Scope & { cell: <T>(path: string) => Cell<T> } = {
+    /* `cell` and `nextCellIndex` are not on the public `Scope` type — `cell` is the compiler-only
+       cell-hoisting leaf; `nextCellIndex` is drawn by `createAsyncCell` for its warm-seed key.
+       Both stay on the runtime object but off the documented surface. */
+    const self: Scope & { cell: <T>(path: string) => Cell<T>; nextCellIndex: () => number } = {
         id,
-        label,
+        nextCellIndex: () => cellIndex++,
         parent,
         read: (path) => data().read(path),
         replace: (path, value) => data().replace(path, value),
@@ -73,16 +79,11 @@ export function createScope(
         state,
         linked,
         computed,
+        trackedComputed,
         effect,
         own: (dispose) => {
             owned.push(dispose)
         },
-        child: (childInitial = {}) => {
-            const created = createScope(childInitial, self)
-            children.push(created)
-            return created
-        },
-        root: () => (parent === undefined ? self : parent.root()),
         /* Reference store — no tracking, so a lookup never subscribes; reactivity comes
            from what is shared (a scope, whose doc is reactive), not from the share. */
         share: (key, value) => {
@@ -93,49 +94,15 @@ export function createScope(
            `undefined` from "not provided"; undefined at the root means no provider. */
         shared: <T>(key: string): T | undefined =>
             shared.has(key) ? (shared.get(key) as T) : parent?.shared<T>(key),
-        record: (options) => {
-            past ??= history(data(), options)
-        },
-        persist: (key) => {
-            persistence ??= persistDoc(data(), key ?? id)
-        },
-        broadcast: (transport) => {
-            unsync ??= sync(data(), transport)
-        },
-        undo: () => past?.undo(),
-        redo: () => past?.redo(),
-        canUndo: () => past?.canUndo() ?? false,
-        canRedo: () => past?.canRedo() ?? false,
         dispose: () => {
-            /* Stop the build's reactivity first (reverse order), before tearing down nested
-               children and the boundary-crossing capabilities — the order the call sites
+            /* Stop the build's reactivity in reverse order — the order the call sites
                hand-composed as `stop(); lexical.dispose()`. */
             for (let index = owned.length - 1; index >= 0; index -= 1) {
                 owned[index]?.()
             }
             owned.length = 0
-            /* Children reverse too (last created first), so a later child that captured an
-               earlier sibling tears down before the sibling it depends on — LIFO like `owned`. */
-            for (let index = children.length - 1; index >= 0; index -= 1) {
-                children[index]?.dispose()
-            }
-            children.length = 0
             shared.clear()
-            past?.dispose()
-            past = undefined
-            persistence?.dispose()
-            persistence = undefined
-            unsync?.()
-            unsync = undefined
-            if (liveScopes.enabled) {
-                liveScopes.scopes.delete(self)
-            }
         },
     }
-    /* Dev-only: register for the inspector's scope-tree view. Gated, so production
-       never touches the set. */
-    if (liveScopes.enabled) {
-        liveScopes.scopes.add(self)
-    }
     return self
 }

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

@@ -0,0 +1,142 @@
+import { scope } from '../runtime/scope.ts'
+import { buildDetachedRange } from './buildDetachedRange.ts'
+import { removeRange } from './removeRange.ts'
+
+/*
+The single-active-branch skeleton shared by `awaitBlock` and `tryBlock`: one
+marker-bounded `[`…`]` range parked before an `anchor`, swapped as a unit when the
+block settles to a different branch. Both blocks previously copy-pasted this skeleton —
+the `active` range record, `detach` (dispose + `removeRange`), the create-path `place`
+(build a detached range and insert it before the anchor), and the hydration `adoptStrand`
+guard — even though their ESSENTIAL orchestration (await's then/catch/finally settlement,
+try's boundary recovery) is genuinely bespoke and stays in each block. This carries only
+the accidental copy-paste, notably its two subtle guards:
+
+  1. the detached-anchor short-circuit in `place` (drop a late swap whose anchor has been
+     pulled from the tree), and
+  2. the adopt-strand-dispose guard in `adoptStrand` (a partial hydration build strands a
+     live sub-scope, so ALWAYS take its disposer and run it on ANY failure before
+     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.
+*/
+export function anchoredBranch(
+    parent: Node,
+    group: { track: (dispose: () => void) => () => void },
+): {
+    anchor: Node | undefined
+    detach: () => void
+    place: (build: (host: Node) => void, wrapBuild?: (run: () => void) => void) => void
+    adoptStrand: (
+        build: (host: Node) => void,
+        afterBuild: () => { start: Comment; end: Comment },
+    ) => void
+} {
+    let active: { start: Comment; end: Comment; dispose: () => void } | undefined
+    let anchor: Node | undefined
+
+    const detach = (): void => {
+        if (active !== undefined) {
+            active.dispose()
+            /* `removeRange` evicts the markers AND everything between them via the end
+               marker's LIVE parent — not the captured `parent`, which (when the block is a
+               bare child of a control-flow branch) is the branch's build fragment, emptied
+               into the document once the enclosing block placed it. */
+            removeRange(active.start, active.end)
+            active = undefined
+        }
+    }
+
+    /* Replace the current content with a freshly-built branch, before the anchor. The branch
+       builds into a detached `[`…`]`-bracketed fragment (so any content — components, text,
+       nested blocks — appends freely), the same create primitive the keyed-list runtimes use,
+       which lands as a marker-bounded range the next swap detaches with `removeRange`.
+       `wrapBuild` (tryBlock only) wraps just the build call so the guarded branch's effects
+       build under the ambient error boundary; detach/insert stay outside it. */
+    const place = (build: (host: Node) => void, wrapBuild?: (run: () => void) => void): void => {
+        /* Backstop for a swap whose anchor has been detached from the tree. The block's own
+           generation guard is the PRIMARY defense — it drops a late settle after the owner
+           tears down — but a gap (e.g. a nested hydration `adopt` that aborts to `rebuildCold`,
+           leaving the inner block's range removed while its guard stays live) can still route a
+           late swap here with `anchor` already pulled out of the DOM. Inserting before a node
+           that is no longer a child of any parent throws `NotFoundError` from `insertBefore` —
+           surfacing as a process-fatal unhandled rejection under Bun. A detached anchor
+           unambiguously means the block is gone, so drop the swap. */
+        if (anchor !== undefined && anchor.parentNode === null) {
+            return
+        }
+        detach()
+        const namespaceParent = anchor?.parentNode ?? parent
+        let built: ReturnType<typeof buildDetachedRange> | undefined
+        const run = (): void => {
+            built = buildDetachedRange(namespaceParent, build)
+        }
+        if (wrapBuild !== undefined) {
+            wrapBuild(run)
+        } else {
+            run()
+        }
+        const range = built as ReturnType<typeof buildDetachedRange>
+        const tracked = group.track(range.dispose)
+        namespaceParent.insertBefore(range.fragment, anchor ?? null)
+        active = { start: range.start, end: range.end, dispose: tracked }
+    }
+
+    /* Adopt an SSR branch in place (its content claims the existing nodes). Adoption is
+       guarded: a build that can't claim the server markup — a resume value that didn't
+       round-trip, a nested-adopt claim desync — throws, and the caller recovers by rebuilding
+       cold. But the partial build may have already created a live sub-scope (an inner `await`'s
+       effect/guard, a subscription) before it threw; letting the throw escape `scope()` would
+       strand that scope's disposer (unreachable → never disposed), leaking the effect AND
+       leaving its guard un-bumped so a late settle stays "live". So capture the build's error,
+       ALWAYS take the returned disposer, and dispose it on ANY failure before rethrowing — the
+       caller's cold rebuild then starts from a clean slate. `afterBuild` (bespoke per block)
+       claims/creates the range markers around the adopted nodes and parks the anchor, returning
+       the range's start/end; it runs only after a clean build. */
+    const adoptStrand = (
+        build: (host: Node) => void,
+        afterBuild: () => { start: Comment; end: Comment },
+    ): void => {
+        let dispose: (() => void) | undefined
+        try {
+            let buildFailed = false
+            let buildError: unknown
+            dispose = group.track(
+                scope(() => {
+                    try {
+                        build(parent)
+                    } catch (error) {
+                        buildFailed = true
+                        buildError = error
+                    }
+                }),
+            )
+            if (buildFailed) {
+                throw buildError
+            }
+            const range = afterBuild()
+            active = { start: range.start, end: range.end, dispose }
+        } catch (error) {
+            /* `dispose` (the group-tracked wrapper) is idempotent; running it here tears the
+               partial branch scope down and drops it from the group so the cold rebuild doesn't
+               inherit a stranded scope, then the caller falls back to a cold build. */
+            dispose?.()
+            throw error
+        }
+    }
+
+    return {
+        get anchor(): Node | undefined {
+            return anchor
+        },
+        set anchor(node: Node | undefined) {
+            anchor = node
+        },
+        detach,
+        place,
+        adoptStrand,
+    }
+}

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

@@ -38,7 +38,10 @@ export function appendText(parent: Node, read: () => unknown, splitAlways = fals
     const hydration = RENDER.hydration
     if (hydration !== undefined) {
         const claimed = claimChild(hydration, parent)
-        const value = String(read())
+        /* Nullish reads render as empty text, never the literal `"undefined"` — so a
+           pending async read (undefined-while-pending, ADR-0032 D3) shows nothing. */
+        const firstValue = read()
+        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
@@ -74,14 +77,16 @@ export function appendText(parent: Node, read: () => unknown, splitAlways = fals
            at the end). */
         hydration.next.set(parent, isText ? node.nextSibling : claimed)
         effect(() => {
-            node.data = String(read())
+            const next = read()
+            node.data = next == null ? '' : String(next)
         })
         return
     }
     const node = document.createTextNode('')
     parent.appendChild(node)
     effect(() => {
-        node.data = String(read())
+        const next = read()
+        node.data = next == null ? '' : String(next)
     })
 }