@abide/abide 0.49.0 → 0.50.1

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

@@ -1,101 +1,265 @@
+import { effect } from '../effect.ts'
+import { AsyncCellError } from '../runtime/AsyncCellError.ts'
+import { CURRENT_BOUNDARY } from '../runtime/CURRENT_BOUNDARY.ts'
 import { claimExpected } from '../runtime/claimExpected.ts'
 import { OWNER } from '../runtime/OWNER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scopeGroup } from '../runtime/scopeGroup.ts'
+import type { Boundary } from '../runtime/types/Boundary.ts'
+import type { State } from '../runtime/types/State.ts'
 import { withoutHydration } from '../runtime/withoutHydration.ts'
+import { state } from '../state.ts'
+import { anchoredBranch } from './anchoredBranch.ts'
 import { discardBoundary } from './discardBoundary.ts'
-import { enterNamespace } from './enterNamespace.ts'
 
 /*
-Synchronous error boundary — the runtime for `<template try>`. Builds the guarded
-subtree (`renderTry`); if building it throws — including a throw from an initial
-reactive read, since effects run during build — it tears down the partial scope and
-builds `renderCatch(error)` instead. Each branch builds its content (any content)
-into the parent. No `renderCatch` (no `<template catch>`) re-throws, so the error
-propagates to the nearest enclosing boundary. The block renders once and never
-re-renders, so its content needs no range markers — an enclosing block's range
-removes it on teardown.
+Reactive error boundary — the runtime for `<template try>` (ADR-0019 D3). Unlike the old
+synchronous render-once version it is render-MANY and reactive both directions: it catches
+a build throw AND an initial reactive-read throw (as before) AND — the headline capability
+— a throw from a LATER re-run, where an async error lives (an async cell that rejects after
+mount, read via a throwing peek → `AsyncCellError`).
 
-On create the guarded content is built into a fragment first, so a throw mid-build
-discards the partial nodes (they never entered the document) before the catch
-builds. On hydrate it claims the SSR boundary
-(`<!--abide:try:N-->…<!--/abide:try:N-->`): the happy path adopts the guarded nodes
-in place; a throw discards the boundary's server nodes and builds the catch fresh.
+Each branch's content lives in a `[`…`]`-bracketed RANGE (the model `when`/`await`/`each`
+share) parked before an anchor, so a swap detaches one unit and builds the other. The
+guarded branch builds under an ambient `CURRENT_BOUNDARY` so every effect created inside
+associates with this boundary (`boundaryFor`); when such an effect throws on a re-run the
+scheduler (`flushEffects.drain`) calls `boundary.handle(error)` — which swaps to the catch
+branch. No `renderCatch` (no `<template catch>`) means no boundary is installed, so a later
+throw propagates to the nearest ENCLOSING `{#try}` unchanged, and an initial throw rethrows.
+
+Keep-the-watch: the terminal alternative would dispose the guarded scope on throw, killing
+the only subscription to the failing cell — the boundary would go deaf to recovery. So the
+throw carries the originating cell (`AsyncCellError.cell`); on catching an async-cell error
+the boundary subscribes to that cell's lifecycle and, when it recovers (error→value via a
+`refresh()` or a dep change), rebuilds the guarded content fresh — one rebuild, then
+fine-grained. On catch→catch (a fresh error while still failing) the catch branch rebuilds
+with the new error (the codegen catch binding is a plain local, so the error passes by
+value; in-place `err` update is a v2 refinement).
+
+Hydration claims the SSR boundary (`<!--abide:try:N-->…<!--/abide:try:N-->`): the happy
+path adopts the guarded nodes in place and brackets them into a range (so the first swap
+detaches them like any later one); a throw discards the server nodes and builds the catch
+fresh.
 */
 // @documentation plumbing
 export function tryBlock(
     parent: Node,
-    id: number,
+    id: string,
     renderTry: (parent: Node) => void,
-    renderCatch?: (parent: Node, error: unknown) => void,
+    renderCatch?: (parent: Node, error: State<unknown>) => void,
     before: Node | null = null,
 ): void {
-    /* The guarded subtree's scope, registered with the owner so it disposes on owner
-       teardown. The block renders once, so there is at most one tracked subtree (the
-       try branch, or the catch branch if try threw). */
+    const hydration = RENDER.hydration
+    /* The live branch's scope, registered with the owner so it disposes on owner teardown —
+       not only when a swap detaches it. */
     const group = scopeGroup()
-    /* Run a void build under a fresh ownership scope. On success, hand its disposers to
-       the group so the subtree tears down with the owner (they were previously dropped —
-       the leak). On throw, tear down the partial build now and rethrow so the caller can
-       fall back to the catch branch. */
-    const guard = (build: () => void): void => {
-        const previous = OWNER.current
-        const disposers: Array<() => void> = []
-        OWNER.current = disposers
-        const disposeAll = (): void => {
-            for (let index = disposers.length - 1; index >= 0; index -= 1) {
-                disposers[index]?.()
-            }
+    /* Only a block WITH a catch branch installs a boundary: with no catch it cannot handle a
+       throw, so its guarded effects must inherit the ENCLOSING boundary (a nested throw then
+       propagates outward) and an initial throw rethrows. */
+    const hasCatch = renderCatch !== undefined
+    /* The single active branch mounted before an anchor — owns `active`/`detach`/`place`/
+       adopt-strand guard (shared with `awaitBlock`); this block keeps its bespoke boundary
+       recovery. */
+    const branch = anchoredBranch(parent, group)
+    /* The keep-the-watch subscription on the throwing cell, live while the catch branch is
+       shown (async-cell errors only); disposed on recover / swap / teardown. */
+    let watchDispose: (() => void) | undefined
+    /* Which branch is mounted, and the reactive error cell the catch branch reads. A
+       catch→catch (a fresh error while still failing) WRITES this cell — the `err` binding
+       re-runs in place, no rebuild — mirroring how `awaitBlock` updates its then-value cell. */
+    let activeKind: 'try' | 'catch' | undefined
+    let errorCell: State<unknown> | undefined
+
+    const boundary: Boundary = { handle: (error) => showCatch(error) }
+
+    const disposeWatch = (): void => {
+        if (watchDispose !== undefined) {
+            watchDispose()
+            watchDispose = undefined
         }
+    }
+
+    /* Install this boundary as the ambient one around the guarded branch's build (passed as
+       `place`'s `wrapBuild`) so its effects associate for later-throw routing; the catch branch
+       builds WITHOUT it, so a throw in catch content propagates to the enclosing boundary rather
+       than back to this one. */
+    const withBoundary = (run: () => void): void => {
+        const previousBoundary = CURRENT_BOUNDARY.current
+        CURRENT_BOUNDARY.current = boundary
         try {
-            build()
-            OWNER.current = previous
-            group.track(disposeAll)
-        } catch (error) {
-            OWNER.current = previous
-            disposeAll()
-            throw error
+            run()
+        } finally {
+            CURRENT_BOUNDARY.current = previousBoundary
         }
     }
 
-    const hydration = RENDER.hydration
-    if (hydration !== undefined) {
-        // Guaranteed control-flow markers — claimExpected throws a legible desync (the close
-        // is caught below → rebuild the catch fresh) instead of claiming null and over-clearing.
-        const open = claimExpected(hydration, parent, `abide:try:${id} open marker`)
-        hydration.next.set(parent, open.nextSibling ?? null) // advance past the open marker
+    /* Build (or rebuild) the guarded branch. A SYNCHRONOUS throw during the build — an
+       initial reactive-read throw or a plain build throw — falls to the catch branch (or
+       rethrows with no catch, preserving the old boundary's semantics). Later-run throws
+       arrive via `boundary.handle` instead. */
+    const showTry = (): void => {
+        disposeWatch()
         try {
-            guard(() => renderTry(parent)) // claims the guarded nodes in place
-            const close = claimExpected(hydration, parent, `/abide:try:${id} close marker`)
-            hydration.next.set(parent, close.nextSibling ?? null)
+            branch.place((host) => renderTry(host), hasCatch ? withBoundary : undefined)
+            activeKind = 'try'
+            errorCell = undefined
         } catch (error) {
-            /* The server markup didn't adopt — drop the whole boundary and build the
-               catch fresh in its place. */
-            const after = discardBoundary(parent, open, `/abide:try:${id}`, hydration)
-            if (renderCatch === undefined) {
+            if (!hasCatch) {
                 throw error
             }
-            withoutHydration(() => {
-                const fragment = document.createDocumentFragment()
-                enterNamespace(parent, () => guard(() => renderCatch(fragment, error)))
-                parent.insertBefore(fragment, after)
+            showCatch(error)
+        }
+    }
+
+    /* Swap to the catch branch. A catch→catch (a fresh error while the catch branch is
+       already mounted) updates the reactive `err` cell IN PLACE — the binding re-runs, no
+       rebuild, focus/scroll inside the catch branch survive. Otherwise (try→catch, or the
+       initial throw) it builds the catch branch fresh around a new error cell. Either way it
+       keeps a watch on the throwing async cell so a recovery re-arms the guarded branch. */
+    const showCatch = (error: unknown): void => {
+        if (activeKind === 'catch' && errorCell !== undefined) {
+            errorCell.value = error
+            rewatch(error)
+            return
+        }
+        const cell = state<unknown>(error)
+        errorCell = cell
+        branch.place((host) => (renderCatch as NonNullable<typeof renderCatch>)(host, cell))
+        activeKind = 'catch'
+        rewatch(error)
+    }
+
+    /* (Re)subscribe the keep-the-watch to whatever cell threw this time. Only a reactive
+       async-cell error carries a source to watch; a plain render bug is terminal in v1 (a bug
+       is not a data state that self-heals). */
+    const rewatch = (error: unknown): void => {
+        disposeWatch()
+        if (error instanceof AsyncCellError) {
+            watchCell(error.cell)
+        }
+    }
+
+    /* Subscribe to the throwing cell's lifecycle. On recovery (its error clears or a value
+       arrives — error→value via `refresh()` or a dep change) rebuild the guarded branch
+       fresh; on a fresh error while still failing, rebuild catch with the new error. Created
+       OUTSIDE this boundary and the owner (it must not route its own reads here and must not
+       double-register), tracked in the group so it disposes with the block. */
+    const watchCell = (cell: AsyncCellError['cell']): void => {
+        const previousBoundary = CURRENT_BOUNDARY.current
+        const previousOwner = OWNER.current
+        CURRENT_BOUNDARY.current = undefined
+        OWNER.current = undefined
+        let firstRun = true
+        let dispose: () => void
+        try {
+            dispose = effect(() => {
+                const cellError = cell.error()
+                const value = cell.peek()
+                /* The first run only subscribes — the cell is still in its error state that
+                   drove us here, so acting on it would immediately re-arm. */
+                if (firstRun) {
+                    firstRun = false
+                    return
+                }
+                /* Recovered: rebuild guarded fresh. Still failing with a fresh error: rebuild
+                   catch with it. Either path disposes THIS watch first (safe: an effect fully
+                   unlinks itself, so its own end-of-run tracking trims nothing). */
+                if (cellError === undefined || value !== undefined) {
+                    showTry()
+                } else {
+                    showCatch(new AsyncCellError(cell, cellError))
+                }
             })
+        } finally {
+            CURRENT_BOUNDARY.current = previousBoundary
+            OWNER.current = previousOwner
         }
+        watchDispose = group.track(dispose)
+    }
+
+    if (hydration !== undefined) {
+        firstHydrate()
         return
     }
+    const anchorNode = document.createTextNode('')
+    branch.anchor = anchorNode
+    parent.insertBefore(anchorNode, before)
+    showTry()
+
+    /* The first run when hydrating: claim the boundary's open marker, adopt the guarded
+       server nodes in place, then bracket them into a range so the first swap detaches them
+       like every later one. A guarded throw (the server rendered catch, or the client build
+       throws too) discards the boundary and builds the catch fresh. */
+    function firstHydrate(): void {
+        const cursor = hydration as NonNullable<typeof hydration>
+        const open = claimExpected(cursor, parent, `abide:try:${id} open marker`)
+        try {
+            adopt(open)
+        } catch (error) {
+            rebuildCold(open, error)
+        }
+    }
+
+    /* Adopt the guarded branch in place: claim the server's `[` range-open marker, build the
+       guarded content (which claims its nodes) under the boundary, then claim the `]`
+       range-close and the boundary close, parking an anchor so a later swap detaches this
+       range like any other. A build throw disposes the partial scope and rethrows so
+       `firstHydrate` rebuilds cold. */
+    function adopt(open: Node): void {
+        const cursor = hydration as NonNullable<typeof hydration>
+        cursor.next.set(parent, open.nextSibling ?? null)
+        /* The server emits the `[ … ]` range inside the boundary — claim `[` as the live
+           range start, then advance the cursor to the first content node. */
+        const start = claimExpected(cursor, parent, `abide:try:${id} range-open marker`) as Comment
+        cursor.next.set(parent, start.nextSibling ?? null)
+        /* Install the boundary around the whole adopt (build + marker claims); the shared
+           strand-dispose guard in `adoptStrand` disposes the partial scope and rethrows on any
+           failure, and this `finally` restores the boundary before the rethrow reaches
+           `firstHydrate`. */
+        const previousBoundary = CURRENT_BOUNDARY.current
+        if (hasCatch) {
+            CURRENT_BOUNDARY.current = boundary
+        }
+        try {
+            branch.adoptStrand(
+                (host) => renderTry(host),
+                () => {
+                    const end = claimExpected(
+                        cursor,
+                        parent,
+                        `abide:try:${id} range-close marker`,
+                    ) as Comment
+                    cursor.next.set(parent, end.nextSibling ?? null)
+                    const close = claimExpected(cursor, parent, `/abide:try:${id} close marker`)
+                    cursor.next.set(parent, close.nextSibling ?? null)
+                    const anchorNode = document.createTextNode('')
+                    parent.insertBefore(anchorNode, close)
+                    branch.anchor = anchorNode
+                    return { start, end }
+                },
+            )
+            activeKind = 'try'
+        } finally {
+            CURRENT_BOUNDARY.current = previousBoundary
+        }
+    }
 
-    /* Create: build into a fragment so a throw mid-build discards the partial nodes
-       (they never entered the document) before the catch builds. */
-    try {
-        const fragment = document.createDocumentFragment()
-        enterNamespace(parent, () => guard(() => renderTry(fragment)))
-        parent.insertBefore(fragment, before)
-    } catch (error) {
-        if (renderCatch === undefined) {
+    /* Discard the SSR boundary and build the catch branch fresh in its place (hydration off).
+       No catch → rethrow (the throw surfaces past the boundary, as the sync version did). */
+    function rebuildCold(open: Node, error: unknown): void {
+        branch.detach()
+        const after = discardBoundary(
+            parent,
+            open,
+            `/abide:try:${id}`,
+            hydration as NonNullable<typeof hydration>,
+        )
+        if (!hasCatch) {
             throw error
         }
-        const fragment = document.createDocumentFragment()
-        enterNamespace(parent, () => guard(() => renderCatch(fragment, error)))
-        parent.insertBefore(fragment, before)
+        const anchorNode = document.createTextNode('')
+        branch.anchor = anchorNode
+        parent.insertBefore(anchorNode, after)
+        withoutHydration(() => showCatch(error))
     }
 }

package/src/lib/ui/dom/types/SwitchCase.ts

@@ -1,7 +1,11 @@
 /* One branch of a `switch`: `match` returns the value this case selects on
    (undefined = the default branch); `render` builds the branch's content into the
-   parent (the block tracks it as a range between markers). */
+   parent (the block tracks it as a range between markers). `pending` (only on an
+   async `{#if}`/`{:elseif}` cond-chain branch) reports whether this branch's own
+   async condition is still loading — a true reading holds the whole chain here, so a
+   later branch never renders on a not-yet-known earlier condition. */
 export type SwitchCase = {
     match: (() => unknown) | undefined
     render: (parent: Node) => void
+    pending?: () => boolean
 }

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

@@ -8,6 +8,12 @@ just element roots. A 2-case swappable range tracks `condition()` and swaps the
 range's content on a truthy↔falsy flip (`render` truthy, `renderElse` falsy); an
 unchanged condition is a no-op. See `mountSwappableRange` for the shared
 hydrate/swap/teardown semantics.
+
+`isPending` (compiler-supplied only for a bare async subject) adds a third state: while
+it returns true the block renders NEITHER branch, so a still-loading promise never flashes
+its `{:else}` before settling — "pending" is not conflated with a settled falsy value. It is
+consulted first, so `condition()` (the throwing peek) runs only once the cell is no longer
+pending; an error then throws to the nearest `{#try}`.
 */
 // @documentation plumbing
 export function when(
@@ -16,11 +22,15 @@ export function when(
     render: (parent: Node) => void,
     renderElse?: (parent: Node) => void,
     before: Node | null = null,
+    isPending?: () => boolean,
 ): void {
     mountSwappableRange(
         parent,
-        () => (condition() ? 'then' : 'else'),
-        (branch) => (branch === 'then' ? render : renderElse),
+        () => (isPending?.() === true ? 'pending' : condition() ? 'then' : 'else'),
+        (branch) => (branch === 'then' ? render : branch === 'else' ? renderElse : undefined),
         before,
+        /* An async subject (compiler supplies `isPending`) can render a different branch on the
+           server than the pending client, so hydration must not adopt the SSR range in place. */
+        isPending !== undefined,
     )
 }

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

@@ -15,9 +15,9 @@ build, so the restore is exact). `build` returns its reactivity stopper (from `s
 the caller wraps its own DOM teardown (clear host vs clear range) around one
 `lexical.dispose()`, no longer composing a separate `stop()` at every site.
 */
-export function withScope(label: string | undefined, build: () => () => void): { lexical: Scope } {
+export function withScope(build: () => () => void): { lexical: Scope } {
     const parentScope = CURRENT_SCOPE.current
-    const lexical = createScope({}, parentScope, true, label)
+    const lexical = createScope({}, parentScope, true)
     enterRenderPass()
     CURRENT_SCOPE.current = lexical
     try {

package/src/lib/ui/finalizeStreamedChildren.ts

@@ -0,0 +1,89 @@
+import type { FlightPromise } from './flight.ts'
+import { RANGE_CLOSE, RANGE_OPEN } from './runtime/RANGE_MARKER.ts'
+import type { ResumeEntry } from './runtime/RESUME.ts'
+import type { SsrAwait, SsrRender } from './runtime/types/SsrRender.ts'
+
+/* Comment-wrapped range markers — imported from the shared constant (not a local literal) so the
+   inline branch below can never drift from `generateSSR`'s own range emit. */
+const OPEN = `<!--${RANGE_OPEN}-->`
+const CLOSE = `<!--${RANGE_CLOSE}-->`
+
+/* One hoistable child render staged by generateSSR: the reserved index in its output array, the
+   array itself, the child's render-path (the streamed boundary id), and its in-flight render. */
+export type StagedChild = {
+    slot: number
+    out: string[]
+    id: string
+    flight: FlightPromise
+}
+
+/*
+The ADR-0039 WHEN-TO-STREAM decision, run once after a component's body walk (compileSSR emits
+`await $$finalizeStreamedChildren($childSlots, $awaits, $resume)` before the render returns). Each
+hoistable child was started as an isolated `$$flight` in the prefix and its output position RESERVED
+(an empty `$out` slot); here we fill that slot per child:
+
+- A flight that has already SETTLED (a synchronous / warm-cache child, or a fast read) inlines its
+  html into the reserved slot as `<!--[-->…<!--]-->` — BYTE-IDENTICAL to the pre-ADR-0039 inline
+  `await Child.render()` path, so an all-fast page's wire and hydration are unchanged. Its awaits /
+  resume merge exactly as the inline path did.
+- A flight settled REJECTED rethrows here — same as a rejecting inline await (500 before flush).
+- A still-PENDING flight (genuine I/O) STREAMS: the slot gets an empty `abide:await:CHILDPATH`
+  boundary, and an html-only SsrAwait is pushed so `renderToStream` flushes the shell now and streams
+  the child's fragment when it settles (its own nested awaits/resume compose through the same drain).
+
+Timing: one microtask drain settles every synchronous child; a single shared macrotask is paid ONLY
+if some child is still pending after that (a page whose children are all fast never reaches it), so
+the inline fast path costs one microtask and a genuinely-slow child — which was going to block the
+shell anyway — trades ~one tick for a progressively-flushed shell.
+*/
+// @documentation plumbing
+export async function finalizeStreamedChildren(
+    slots: StagedChild[],
+    awaits: SsrAwait[],
+    resume: Record<string, ResumeEntry>,
+): Promise<void> {
+    if (slots.length === 0) {
+        return
+    }
+    await Promise.resolve()
+    if (slots.some((staged) => !staged.flight.settled)) {
+        await new Promise<void>((resolve) => setTimeout(resolve, 0))
+    }
+    for (const staged of slots) {
+        if (staged.flight.settled && staged.flight.error === undefined) {
+            const rendered = staged.flight.value as SsrRender
+            staged.out[staged.slot] = OPEN + rendered.html + CLOSE
+            mergeChildRender(rendered, awaits, resume)
+        } else if (staged.flight.settled) {
+            throw staged.flight.error
+        } else {
+            staged.out[staged.slot] =
+                `<!--abide:await:${staged.id}--><!--/abide:await:${staged.id}-->`
+            awaits.push({
+                id: staged.id,
+                htmlOnly: true,
+                promise: () => staged.flight,
+                // biome-ignore lint/suspicious/noThenProperty: `then` is the SsrAwait renderer callback the stream drain invokes explicitly with the resolved value — this object is stored in `awaits[]`, never awaited as a thenable
+                then: async (rendered) => {
+                    mergeChildRender(rendered as SsrRender, awaits, resume)
+                    return (rendered as SsrRender).html
+                },
+            })
+        }
+    }
+}
+
+/* Fold a child render's contribution (its nested awaits, its resume map) up into the parent's — the
+   single definition both the inlined-settled arm and the still-pending stream arm merge through, so
+   the two can never drift on what a child contributes upward. */
+function mergeChildRender(
+    rendered: SsrRender,
+    awaits: SsrAwait[],
+    resume: Record<string, ResumeEntry>,
+): void {
+    for (const nested of rendered.awaits) {
+        awaits.push(nested)
+    }
+    Object.assign(resume, rendered.resume)
+}

package/src/lib/ui/flight.ts

@@ -0,0 +1,56 @@
+/*
+Server-only flight-starter behind the SSR codegen's `$$flight` alias (ADR-0034). The
+SSR back-end hoists a *hoistable* await's promise into the synchronous render prefix as
+`const $flightN = $$flight(() => (<promise expr>))`, so the flight is already in-flight
+when the body walk reaches its blocking `await $flightN` / streaming `promise: () =>
+$flightN` — independent flights overlap instead of serializing (prefix → barrier → body
+→ drain). Server-only: the client build never emits `$$flight`, so it tree-shakes out of
+the browser bundle (like `$$settleAsyncCells`).
+
+Two behaviours the raw promise expression can't provide on its own:
+
+- A SYNCHRONOUS throw in the loader (before it returns a promise) is normalised to a
+  rejected promise, so a hoisted flight's throw still lands in the block's `{:catch}` /
+  500 path exactly as an inline `await (expr)` would — the expression no longer evaluates
+  inside the block's try/catch, so the thunk wrapper restores that reach.
+- The settledness `.then(onValue, onError)` below is itself a rejection handler attached
+  synchronously to `promise`, so a flight that rejects in the window before its real
+  consumer (the inline await / the `renderToStream` drain) attaches a handler is never a
+  Bun-fatal unhandled rejection — the `onError` branch never rethrows, so the block's
+  surface-rejection → 500 / catch-branch semantics are unchanged. Mirrors the inline
+  `.then(onValue, onError)` guard in `createAsyncCell`.
+*/
+// @documentation plumbing
+export function flight(thunk: () => unknown): FlightPromise {
+    let promise: Promise<unknown>
+    try {
+        promise = Promise.resolve(thunk())
+    } catch (error) {
+        promise = Promise.reject(error)
+    }
+    /* Synchronous settledness signal (ADR-0039): the post-walk `finalizeStreamedChildren` reads
+       `.settled` to decide inline-vs-stream — a child flight that already resolved by finalize time
+       inlines its html into the shell (byte-identical to today), a still-pending one streams. Its
+       `onError` branch doubles as the rejection keeper (see the header note): it marks `promise`
+       handled, so a pre-consumer rejection is never a Bun-fatal unhandled rejection. */
+    const flightPromise = promise as FlightPromise
+    flightPromise.settled = false
+    promise.then(
+        (value) => {
+            flightPromise.value = value
+            flightPromise.settled = true
+        },
+        (error) => {
+            flightPromise.error = error
+            flightPromise.settled = true
+        },
+    )
+    return flightPromise
+}
+
+/* A flight promise carrying a synchronous settledness snapshot for `finalizeStreamedChildren`. */
+export type FlightPromise = Promise<unknown> & {
+    settled: boolean
+    value?: unknown
+    error?: unknown
+}

package/src/lib/ui/html.ts

@@ -16,7 +16,18 @@ written inside a template, so it lives in `ui/` (the reader, `rawHtmlString`, is
 isomorphic plumbing and stays in `shared/`).
 */
 // @documentation templating
-export function html(strings: TemplateStringsArray | string, ...values: unknown[]): RawHtml {
+export function html(
+    strings: TemplateStringsArray | string | null | undefined,
+    ...values: unknown[]
+): RawHtml {
+    /* A plain call with a nullish argument renders nothing. A bare async read (ADR-0032)
+       hands `html()` `undefined` while pending — `{html(highlight(code)?.html)}` — so the
+       plain-call path degrades to empty raw instead of throwing on `strings[0]`, matching
+       how a bare `{value}` stringifies `undefined` to `""`. Mirrors the null-tolerance
+       ADR-0032 added to `done()`/`peek()` for the same inline-async ergonomics. */
+    if (strings === null || strings === undefined) {
+        return { [RAW_HTML]: '' }
+    }
     if (typeof strings === 'string') {
         return { [RAW_HTML]: strings }
     }

package/src/lib/ui/isolateCellBarrier.ts

@@ -0,0 +1,17 @@
+import { cellBarrierBacking } from './runtime/cellBarrierBacking.ts'
+
+/*
+Runs a hoisted child render (`$$isolateCellBarrier`) under its OWN async-cell barrier list, so its
+cells register and its `$$settleAsyncCells` drain are isolated from every concurrent sibling and from
+the page (ADR-0037 Phase 2). Wraps the render start emitted by the SSR flight hoist:
+`$$flight(() => $$isolateCellBarrier(() => $$withPath(ordinal, () => Child.render(props, $ctx))))`.
+The server backing runs it inside an AsyncLocalStorage so the fresh list is inherited across the
+child render's own awaits (its top-level script await, its barrier); the default (client / no server
+install) backing is an inert passthrough — the client mounts synchronously and has no SSR barrier, so
+there is nothing to isolate. Only the pending (barrier) list is isolated; resolved/streamed cell
+values still aggregate on the per-request store for the warm-seed snapshot.
+*/
+// @documentation plumbing
+export function isolateCellBarrier<T>(render: () => T): T {
+    return cellBarrierBacking.active.run({ promises: [] }, render)
+}

package/src/lib/ui/linked.ts

@@ -1,4 +1,9 @@
+import { isAsyncIterable } from '../shared/isAsyncIterable.ts'
+import type { AsyncState } from '../shared/types/AsyncState.ts'
+import type { NamedAsyncIterable } from '../shared/types/NamedAsyncIterable.ts'
+import { createAsyncCell } from './runtime/createAsyncCell.ts'
 import { createEffectNode } from './runtime/createEffectNode.ts'
+import { isAsyncFunction } from './runtime/isAsyncFunction.ts'
 import type { State } from './runtime/types/State.ts'
 import { state } from './state.ts'
 
@@ -16,8 +21,49 @@ entering the store — explicit `.value =` writes and reseeds alike — so the s
 never holds an un-coerced value (`return previous` rejects via the `Object.is`
 no-op). The seed is captured by reference: callers clone in the thunk
 (`linked(() => structuredClone(x))`) when they want isolation.
+
+When the seed tracks an async source it becomes a writable async cell (`AsyncState<T>`,
+ADR-0019 D1): an `async () => await …` thunk unwraps its promise, a `NamedAsyncIterable`
+seed auto-tracks its frames. Same probe surface as `AsyncComputed` plus `set()`, which
+latches until the next reseed — an arriving frame never clobbers an in-progress edit.
 */
-export function linked<T>(seed: () => T, transform?: (next: T, previous: T) => T): State<T> {
+export function linked<T>(
+    seed: () => NamedAsyncIterable<T>,
+    transform?: (next: T, previous: T) => T,
+): AsyncState<T>
+export function linked<T>(
+    seed: () => Promise<T>,
+    transform?: (next: T, previous: T) => T,
+): AsyncState<T>
+export function linked<T>(seed: () => T, transform?: (next: T, previous: T) => T): State<T>
+export function linked<T>(
+    seed: () => T | Promise<T> | NamedAsyncIterable<T>,
+    transform?: (next: T, previous: T) => T,
+): State<T> | AsyncState<T> {
+    const coerce = transform as ((next: unknown, previous: unknown) => unknown) | undefined
+    /* `await` marker: an async-function seed unwraps its promise into a writable async cell. */
+    if (isAsyncFunction(seed)) {
+        return createAsyncCell(seed as () => unknown, {
+            writable: true,
+            transform: coerce,
+        }) as AsyncState<T>
+    }
+    /* Peek the seed once to detect a self-identifying stream source (auto-track); `linked`
+       already runs its seed eagerly, so an early probe matches its semantics. A throw or a
+       non-stream value falls through to the plain synchronous cell. */
+    let probe: unknown
+    let threw = false
+    try {
+        probe = seed()
+    } catch {
+        threw = true
+    }
+    if (!threw && isAsyncIterable(probe)) {
+        return createAsyncCell(seed as () => unknown, {
+            writable: true,
+            transform: coerce,
+        }) as AsyncState<T>
+    }
     /* The cell is a plain `state` — same store, same write path, so `transform` gates
        reseeds and explicit writes identically. */
     const cell = state<T>(undefined as T, transform)
@@ -27,7 +73,7 @@ export function linked<T>(seed: () => T, transform?: (next: T, previous: T) => T
        what `seed` reads can retrigger it. `createEffectNode` registers the disposer
        with the enclosing scope. */
     createEffectNode(() => {
-        cell.value = seed()
+        cell.value = seed() as T
     })
     return cell
 }