@abide/abide 0.49.0 → 0.50.0

package/src/lib/ui/runtime/AsyncCellError.ts

@@ -0,0 +1,20 @@
+import type { AsyncComputed } from '../../shared/types/AsyncComputed.ts'
+
+/*
+The throw a compiled async-cell read (`$$readCell`) raises when the cell is in error
+with no retained value — routed to the nearest reactive `{#try}`. It carries the
+originating cell so the boundary can subscribe to that cell's lifecycle and re-arm
+the guarded content when the cell recovers (error→value via a `refresh()` or a
+dependency change) — "keep watching what threw" (ADR-0019 D3.3). A plain `peek()` in
+JS never throws; the throw is a template-lowering behaviour only, so the cause is
+carried through unchanged for an author's `{:catch err}` binding.
+*/
+export class AsyncCellError extends Error {
+    readonly cell: AsyncComputed<unknown>
+
+    constructor(cell: AsyncComputed<unknown>, cause: unknown) {
+        super(cause instanceof Error ? cause.message : String(cause), { cause })
+        this.name = 'AsyncCellError'
+        this.cell = cell
+    }
+}

package/src/lib/ui/runtime/CELL_SEED.ts

@@ -0,0 +1,14 @@
+/* The async-cell warm-seed manifest: an SSR-resolved cell value, keyed by the cell's
+   serialization-stable render-path id (`${scope.id}:${index}`), as a ref-json-encoded STRING
+   (decoded lazily at the read site in `createAsyncCell`, so an in-process graph with cycles /
+   shared back-references survives where JSON would drop it — the same codec `RESUME` uses).
+   `startClient` drains `__SSR__.cells` into here before mount; a hydrating cell reads its key to
+   seed its value warm instead of re-running the seed (no refetch, no pending flash).
+
+   Backed by `globalThis.__abideCells` so an inline pre-bundle script and the framework share one
+   store — whoever runs first creates it, the other adopts the same reference (mirrors RESUME). */
+const globalScope = globalThis as { __abideCells?: Record<string, string> }
+globalScope.__abideCells ??= {}
+
+// @documentation plumbing
+export const CELL_SEED: Record<string, string> = globalScope.__abideCells

package/src/lib/ui/runtime/CURRENT_BOUNDARY.ts

@@ -0,0 +1,11 @@
+import type { Boundary } from './types/Boundary.ts'
+
+/*
+The ambient reactive error boundary — the `{#try}` mirror of `CURRENT_SCOPE`. A `tryBlock`
+sets `current` to its boundary around the guarded build so every effect created inside
+associates with it (`boundaryFor`), then restores the previous value (boundaries nest, the
+innermost wins). Undefined outside any `{#try}`; a plain mutable holder is enough — the
+value is only read on the cold path where an effect is created inside a boundary, never on
+the reactive hot path.
+*/
+export const CURRENT_BOUNDARY: { current: Boundary | undefined } = { current: undefined }

package/src/lib/ui/runtime/CURRENT_PATH.ts

@@ -0,0 +1,29 @@
+import { ambientPathBacking } from './ambientPathBacking.ts'
+
+/*
+The ambient RENDER-PATH — a serialization-stable lexical id for "where in the render tree
+am I", composed top-down as the tree builds. Each nesting site pushes a segment for the
+duration of its subtree (route → layout layer → slot → `{#each}` row key → `{#if}`/`{#switch}`
+branch → child-component ordinal), and a lexical scope (`createScope`) snapshots the current
+value as its id (replacing the old process-local `scope-${n}` counter, which restarted every
+run and drifted on any SSR/client divergence). Because the path is built from compiler-stamped
+positions and runtime data keys — NOT a creation-order counter — it is order-independent
+(streaming can't shift it), and it self-handles SSR/client branch divergence: different branches
+compose different paths, so a value keyed by one never mis-adopts under the other.
+
+Segments are joined with `/` and each is `escapeKey`-escaped (RFC 6901), so a segment holding
+a `/` (a URL-shaped row key) stays one segment. `current` is `''` outside any render (a detached
+`scope()` then falls back to the counter for in-run uniqueness).
+
+`current` reads through a SWAPPABLE backing (`ambientPathBacking`) rather than a raw field, and is
+READ-ONLY: a segment is established only by `withPath`/`withPathFrom` calling the backing's `run`
+(ADR-0033 D1), never by assigning `current`. The default backing is a module variable (correct on
+the client, one render tree), but the server installs an AsyncLocalStorage-backed `run` so the
+composed path survives the inline `await`s an SSR render suspends on (the cell barrier, child
+renders) and stays isolated across concurrent requests. Mirrors `CURRENT_SCOPE`/`ambientScopeBacking`.
+*/
+export const CURRENT_PATH: { readonly current: string } = {
+    get current(): string {
+        return ambientPathBacking.active.get()
+    },
+}

package/src/lib/ui/runtime/RENDER.ts

@@ -5,11 +5,14 @@ the next server-rendered child node to claim — a node pointer (not an index) s
 survives nodes a block inserts (anchors) mid-hydration. Helpers claim in build
 order, which matches the SSR order, advancing the pointer to the next sibling.
 
-`blockId`/`depth` drive the render-pass block-id counter: every `await`/`try` block
-draws an id from `blockId` in document order, shared across a component and the
-child components it inlines, so ids are globally unique within one render pass (the
-SSR stream and client hydration agree on them — `RESUME` is keyed by id). `depth`
-tracks nesting so the OUTERMOST render/mount resets the counter and a child render/
+`blockCounters`/`depth` drive the render-pass block-id counters: every `await`/`try`
+block draws a path-namespaced id via `nextBlockId` (ADR-0037) — `blockCounters` maps
+each render-path to its own 0,1,2… sequence, counted in document order within that
+path. Namespacing by path (not one flat counter shared across a component and the
+children it inlines) is what keeps ids congruent SSR↔client even when sibling child
+renders run concurrently on the server; the client mounts each child synchronously
+under the same path, so both sides compose the same ids (`RESUME` is keyed by them).
+`depth` tracks nesting so the OUTERMOST render/mount clears the map and a child render/
 mount continues it. See `enterRenderPass`/`nextBlockId`.
 
 `namespace` is the ambient foreign-content namespace (SVG/MathML) a control-flow block
@@ -19,12 +22,12 @@ undefined outside foreign content. See `enterNamespace`/`effectiveChildNamespace
 */
 export const RENDER: {
     hydration: { next: Map<Node, Node | null> } | undefined
-    blockId: number
+    blockCounters: Map<string, number>
     depth: number
     namespace: string | undefined
 } = {
     hydration: undefined,
-    blockId: 0,
+    blockCounters: new Map(),
     depth: 0,
     namespace: undefined,
 }

package/src/lib/ui/runtime/RESUME.ts

@@ -1,7 +1,7 @@
 /* The await-resume manifest: the resolved value (or error) of each streamed
    `await` block, keyed by its boundary id. The SSR stream serializes each entry
-   alongside its fragment; the client registers it (via `applyResolved` or the
-   inline swap script), and hydration reads it so an `await` block adopts the
+   alongside its fragment; the client registers it (via the inline swap script),
+   and hydration reads it so an `await` block adopts the
    resolved branch with the real value instead of re-running the promise.
 
    Each value is the ref-json-encoded ResumeEntry STRING, not the decoded object:
@@ -16,8 +16,8 @@
    same reference. */
 export type ResumeEntry = { ok: true; value: unknown } | { ok: false; error: unknown }
 
-const globalScope = globalThis as { __abideResume?: Record<number, string> }
+const globalScope = globalThis as { __abideResume?: Record<string, string> }
 globalScope.__abideResume ??= {}
 
 // @documentation plumbing
-export const RESUME: Record<number, string> = globalScope.__abideResume
+export const RESUME: Record<string, string> = globalScope.__abideResume

package/src/lib/ui/runtime/STREAMED_CELLS.ts

@@ -0,0 +1,57 @@
+/*
+Post-mount sink for STREAMING-cell resolutions (ADR-0035). Unlike `CELL_SEED` — the pre-mount
+warm-seed a blocking cell reads at construction — a streaming cell ships pending and its value
+arrives LATER (streamed after the shell, `__abideResolve({ cellKey, value })` →
+`seedStreamedResolution`). So a mounted streaming cell registers an `apply` fn keyed by its
+render-path id, and the streamed value is routed to it — the render-path analogue of the cache
+path's `markLifecycle` wake. A value that arrives before its cell registers is buffered and applied
+on registration (the two orderings race as the shell hydrates while chunks stream in).
+
+Backed by `globalThis.__abideStreamedCells` so an inline pre-bundle script and the framework share
+one store, mirroring `CELL_SEED`/`RESUME`.
+*/
+const globalScope = globalThis as {
+    __abideStreamedCells?: {
+        apply: Map<string, (value: unknown) => void>
+        buffer: Map<string, unknown>
+    }
+}
+globalScope.__abideStreamedCells ??= { apply: new Map(), buffer: new Map() }
+
+const store = globalScope.__abideStreamedCells
+
+/* Apply a streamed value to its cell as a POST-hydration reactive update. Deferred to a microtask
+   so it can NEVER run inside the synchronous hydration mount: the streamed `__abideResolve` chunk
+   parses (buffering the value) BEFORE the client mounts, so a synchronous apply at registration
+   would set the cell to the resolved value while the SSR DOM still shows the pending text — an
+   `assertClaimedText` desync (ADR-0033). The microtask runs after the whole synchronous mount
+   tree unwinds, so hydration claims the pending markup first and the value lands as a plain
+   reactive update (pending → resolved), congruent with a fresh mount. */
+function deferApply(apply: (value: unknown) => void, value: unknown): void {
+    queueMicrotask(() => apply(value))
+}
+
+/* A mounted streaming cell offers where to deliver its streamed value. If the value already
+   arrived (buffered), schedule it; otherwise hold the apply fn for when it streams in. */
+export function registerStreamedCell(key: string, apply: (value: unknown) => void): void {
+    if (store.buffer.has(key)) {
+        const value = store.buffer.get(key)
+        store.buffer.delete(key)
+        deferApply(apply, value)
+        return
+    }
+    store.apply.set(key, apply)
+}
+
+/* A streamed value landed for `key`. Deliver it to the registered cell (scheduled post-mount), or
+   buffer it until the cell registers. One-shot: the apply fn is consumed (a cell adopts a streamed
+   value once; later reactivity is its own reseed). */
+export function receiveStreamedCell(key: string, value: unknown): void {
+    const apply = store.apply.get(key)
+    if (apply !== undefined) {
+        store.apply.delete(key)
+        deferApply(apply, value)
+        return
+    }
+    store.buffer.set(key, value)
+}

package/src/lib/ui/runtime/ambientPathBacking.ts

@@ -0,0 +1,32 @@
+/*
+The swappable backing behind `CURRENT_PATH.current` — the render-path sibling of
+`ambientScopeBacking`. The default is a module variable with a synchronous save/restore `run`
+(correct on the client, whose mount is synchronous — the whole subtree builds and restores before
+control returns, so a slot never has to survive an `await`). The server swaps in an
+AsyncLocalStorage-backed `run` at boot (`installAmbientScopeStore`, ADR-0033 D1), because SSR
+composes the path while `await`ing inline (the Tier-2 cell barrier, child renders) and the pushed
+segment must be inherited by the render's own post-await continuation — a synchronously-restored slot
+cannot follow an async continuation. `run(composed, build)` establishes the composed path for
+`build`; `get()` reads the active path (`''` outside any push). Mirrors `ambientScopeBacking`.
+*/
+type PathBacking = {
+    run: <T>(composedPath: string, build: () => T) => T
+    get: () => string
+}
+
+let modulePath = ''
+
+export const ambientPathBacking: { active: PathBacking } = {
+    active: {
+        run: <T>(composedPath: string, build: () => T): T => {
+            const previous = modulePath
+            modulePath = composedPath
+            try {
+                return build()
+            } finally {
+                modulePath = previous
+            }
+        },
+        get: () => modulePath,
+    },
+}

package/src/lib/ui/runtime/applyPatchToTree.ts

@@ -7,7 +7,7 @@ value only when the root itself is replaced). In-place is the deliberate choice:
 the patch path already names exactly what changed, so we never need copy-on-write
 to *detect* a change — and cloning the spine made every leaf write O(width) of
 the widest ancestor (a 5k-item list copied 50k times in the bench). Mutating is
-O(depth). History/undo is served by journalling patches (the change is a value),
+O(depth). Change detection is served by announcing patches (the change is a value),
 not by retaining old roots — which is cheaper anyway. The wake step in createDoc
 force-notifies ancestor readers from the path, since their container keeps its
 identity now.

package/src/lib/ui/runtime/blockId.ts

@@ -0,0 +1,31 @@
+import { CURRENT_PATH } from './CURRENT_PATH.ts'
+
+/*
+Allocates an await/try block id NAMESPACED by the ambient render-path (ADR-0037). The id is
+`${CURRENT_PATH.current}:${n}` where `n` is a per-path counter incremented in document order —
+so blocks WITHIN one component/branch/row (one path) number 0,1,2… deterministically, while a
+child component (its own path segment) gets its own independent sequence. This replaces the old
+flat monotonic counter shared across a component and the children it inlines.
+
+Path-namespacing is what lets sibling child renders run CONCURRENTLY during SSR: their ids no
+longer depend on a globally-sequential draw order (which parallel renders would interleave), only
+on document order within each child's own path — and the server render-path is ALS-backed
+(pathStore), so each child's continuations keep their own path across awaits. The client mounts
+each child synchronously under the same path (mountChild → withPath), so both sides compose
+byte-identical ids and the resume manifest stays keyed congruently.
+
+`counters` is the per-render-pass map: the request-local `$ctx` threaded through the SSR render
+tree, or `RENDER.blockCounters` on the client (see nextBlockId). Concurrent sibling renders write
+DIFFERENT path keys, so a shared map needs no locking — each get/set is atomic and per-path.
+*/
+// @documentation plumbing
+export function blockId(counters: Map<string, number>): string {
+    const path = CURRENT_PATH.current
+    const next = counters.get(path) ?? 0
+    counters.set(path, next + 1)
+    /* Bare (pathless) render — a top-level page whose route key is `''`, or a component rendered
+       outside any route in a test — keeps the plain `0,1,2…` form; only a non-empty path qualifies
+       the id. Both sides compute the same path, so the branch is congruent, and the common bare case
+       stays identical to the pre-ADR-0037 flat counter. */
+    return path === '' ? String(next) : `${path}:${next}`
+}

package/src/lib/ui/runtime/boundaryFor.ts

@@ -0,0 +1,11 @@
+import type { Boundary } from './types/Boundary.ts'
+import type { ReactiveNode } from './types/ReactiveNode.ts'
+
+/*
+Associates an effect node with the reactive `{#try}` boundary it was created inside. Kept
+OFF the `ReactiveNode` shape — a WeakMap populated only for effects built while
+`CURRENT_BOUNDARY.current` is set — so the node stays monomorphic for signals/computeds/
+effects on the read/write hot path, and this map is consulted only on the cold throw path
+(`flushEffects.drain`'s catch), to route a guarded effect's later-run throw to its boundary.
+*/
+export const boundaryFor = new WeakMap<ReactiveNode, Boundary>()

package/src/lib/ui/runtime/cellBarrierBacking.ts

@@ -0,0 +1,30 @@
+import type { PendingAsyncCells } from '../../shared/types/PendingAsyncCells.ts'
+
+/*
+The swappable backing for the PER-RENDER async-cell barrier override (ADR-0037 Phase 2). Mirrors
+`ambientPathBacking`: the default is an inert passthrough (no override — the barrier list resolves
+through the per-request `pendingAsyncCellsSlot` as before), and the server installs an
+AsyncLocalStorage-backed variant (`renderCellBarrierStore`) so a hoisted child render can run its
+async cells under its OWN list.
+
+Why a per-render override at all: sibling child renders that run CONCURRENTLY (the parallel-SSR
+hoist) each register cells on the request-scoped pending list, and `settleAsyncCells` drains it with
+`splice(0)` — so one child's barrier would drain a sibling's cells, letting that sibling's template
+peek a still-pending value. Running each hoisted child under `isolateCellBarrier` gives it a fresh
+list (via `run`), so `activePendingCells()` returns that list for the child's registrations and its
+own barrier drain — isolated from every concurrent sibling and from the page. `current()` returns
+`undefined` outside any isolated render, so the page's own cells fall through to the request list
+unchanged. Kept out of `node:async_hooks` on the client: the default backing is pure JS, and the ALS
+variant is installed only server-side.
+*/
+export const cellBarrierBacking: {
+    active: {
+        current: () => PendingAsyncCells | undefined
+        run: <T>(list: PendingAsyncCells, render: () => T) => T
+    }
+} = {
+    active: {
+        current: () => undefined,
+        run: (_list, render) => render(),
+    },
+}

package/src/lib/ui/runtime/createAsyncCell.ts

@@ -0,0 +1,300 @@
+import { ASYNC_CELL } from '../../shared/ASYNC_CELL.ts'
+import { decodeRefJson } from '../../shared/decodeRefJson.ts'
+import { isAsyncIterable } from '../../shared/isAsyncIterable.ts'
+import { isThenable } from '../../shared/isThenable.ts'
+import { resolvedCellsSlot } from '../../shared/resolvedCellsSlot.ts'
+import { streamedCellsSlot } from '../../shared/streamedCellsSlot.ts'
+import type { AsyncComputed } from '../../shared/types/AsyncComputed.ts'
+import type { AsyncState } from '../../shared/types/AsyncState.ts'
+import type { NamedAsyncIterable } from '../../shared/types/NamedAsyncIterable.ts'
+import { warmSeedKey } from '../../shared/warmSeedKey.ts'
+import { activePendingCells } from '../activePendingCells.ts'
+import type { Scope } from '../types/Scope.ts'
+import { CELL_SEED } from './CELL_SEED.ts'
+import { CURRENT_SCOPE } from './CURRENT_SCOPE.ts'
+import { createEffectNode } from './createEffectNode.ts'
+import { createSignalNode } from './createSignalNode.ts'
+import { readNode } from './readNode.ts'
+import { registerStreamedCell } from './STREAMED_CELLS.ts'
+import { writeNode } from './writeNode.ts'
+
+/* The seed's transform gate (mirrors `state`/`linked`): coerces every value entering
+   the store, whether from a settling promise, a frame, or a `set()`. */
+type Transform = (next: unknown, previous: unknown) => unknown
+
+type AsyncCellOptions = {
+    writable: boolean
+    transform?: Transform
+    /* ADR-0032: a STREAMING cell must NOT join the SSR blocking barrier. A no-`await` async
+       value/content position lowers to a cell that ships pending-`undefined` in the shell and
+       resolves on the client, rather than blocking the first flush inline (that is the `await`
+       tier). Absent/false → today's blocking registration (`await` tier / a keyed bare read).
+       A stream (`isAsyncIterable`) never registers regardless — this only gates a promise seed. */
+    streaming?: boolean
+}
+
+/*
+The source-agnostic async cell — the runtime behind `computed`/`linked` when the seed
+tracks a promise or a NamedAsyncIterable (ADR-0019 D1). It is **eager**: a reactive
+effect runs the seed once at construction (capturing its synchronous dependencies) and
+re-runs — a *reseed* — whenever they change, so independent cells load in parallel and a
+dependent cell re-loads when its dependency settles. The seed's result drives the cell:
+
+  - a **promise** (an `async () => await …` thunk) → unwrap; resolve → value, reject → error;
+  - a **NamedAsyncIterable** (socket / streaming rpc) → `for await` its frames, each frame
+    updating the value; the terminal error/close land on `error()` / clear in-flight;
+  - a **synchronous value** (a seed that produced one directly) → settle immediately.
+
+Read through the probe family only — there is no `.value`. `pending()` is "no value yet",
+`refreshing()` is "a held value while a fresher source is in flight" (a reseed or a
+`refresh()`), `peek()` is the retained value/latest frame (stale-while-revalidate),
+`error()` the last rejection. Every out-of-order settle is guarded by a run id, so a slow
+prior flight never overwrites a newer one. `refresh()` re-invokes the seed keeping the
+value visible; a writable cell adds `set()`, which latches until the next reseed.
+*/
+export function createAsyncCell(
+    seed: () => unknown,
+    options: AsyncCellOptions,
+): AsyncComputed<unknown> | AsyncState<unknown> {
+    const transform = options.transform
+    /* Reactive state, each its own signal so a reader subscribes only to the facets it
+       touches (peeking the value does not re-run on a pending flip, and vice versa). */
+    const valueNode = createSignalNode(undefined)
+    const errorNode = createSignalNode(undefined)
+    const inFlightNode = createSignalNode(true)
+    const hasValueNode = createSignalNode(false)
+
+    /* This cell's serialization-stable warm-seed key: its scope's render-path id + a per-scope
+       index, drawn at construction (in declaration order) so SSR and client agree on it. Minted
+       through the shared `warmSeedKey` so BOTH sides of the handoff (this same isomorphic call,
+       server-side keying `resolvedCells`/`streamedCells` and client-side reading `CELL_SEED`) form
+       the identical string from one definition. Undefined for a detached cell (no scope) — such a
+       cell never crosses SSR→client, so never warm-seeds. */
+    const scope = CURRENT_SCOPE.current as (Scope & { nextCellIndex: () => number }) | undefined
+    const warmKey = scope !== undefined ? warmSeedKey(scope.id, scope.nextCellIndex()) : undefined
+
+    /* `linked` write latch: a local `set()` holds the cell until the next reseed, so an
+       arriving frame / settling promise never clobbers an in-progress edit. Cleared on reseed. */
+    let written = false
+    /* Supersedes out-of-order settles: only the latest run's promise/stream may write. */
+    let runId = 0
+    /* The current run's in-flight promise (undefined once settled, or for a stream/sync seed).
+       Surfaced through `settled()` for the SSR barrier's structural read; a stream never sets it. */
+    let inFlight: Promise<unknown> | undefined
+    /* Cancels the active stream subscription (a reseed, refresh, or dispose supersedes it). */
+    let cancelStream: (() => void) | undefined
+
+    /* Store a produced value, honouring the write latch and the transform gate. */
+    const acceptValue = (value: unknown): void => {
+        if (written) {
+            return
+        }
+        writeNode(valueNode, transform === undefined ? value : transform(value, valueNode.value))
+        writeNode(hasValueNode, true)
+    }
+
+    const settleValue = (myRun: number, value: unknown): void => {
+        if (myRun !== runId) {
+            return
+        }
+        inFlight = undefined
+        acceptValue(value)
+        writeNode(errorNode, undefined)
+        writeNode(inFlightNode, false)
+        /* Server-only: record the resolved value keyed by this cell's render-path id (the `window`
+           guard keeps client settles from ever recording). BLOCKING cells → `resolvedCells`: the
+           barrier awaits them before the template peeks, so the value bakes into the SSR HTML and
+           the page renderer stamps it into the PRE-mount `__SSR__.cells` warm-seed — a warm client
+           value MATCHES it (no flash, no duplication). STREAMING cells → `streamedCells` (ADR-0035):
+           they ship pending in the shell, so their value can't ride the pre-mount seed (it would
+           diverge from the pending markup); it's streamed AFTER the shell as an `__abideResolve`
+           chunk the client adopts POST-hydration. Recording a VALUE (not awaiting a promise) means a
+           cell that never settles this request is simply never recorded — no hang. */
+        if (warmKey !== undefined && typeof window === 'undefined') {
+            if (options.streaming === true) {
+                streamedCellsSlot.get()?.entries.push({ key: warmKey, value })
+            } else {
+                resolvedCellsSlot.get()?.entries.push({ key: warmKey, value })
+            }
+        }
+    }
+
+    /* An error retains the value (SWR): a failed background refresh keeps the stale value
+       visible and surfaces the rejection through `error()` — the read decides what to do. */
+    const settleError = (myRun: number, error: unknown): void => {
+        if (myRun !== runId) {
+            return
+        }
+        inFlight = undefined
+        writeNode(errorNode, error)
+        writeNode(inFlightNode, false)
+    }
+
+    /* Drive a NamedAsyncIterable: first frame clears pending, each later frame updates the
+       value (unless written), a throw lands in `error()`, and completion clears in-flight. */
+    const consumeStream = (myRun: number, source: NamedAsyncIterable<unknown>): void => {
+        const iterator = source[Symbol.asyncIterator]()
+        let live = true
+        cancelStream = (): void => {
+            live = false
+            void iterator.return?.(undefined)
+        }
+        const pump = async (): Promise<void> => {
+            try {
+                while (live && myRun === runId) {
+                    const step = await iterator.next()
+                    if (!live || myRun !== runId) {
+                        return
+                    }
+                    if (step.done === true) {
+                        writeNode(inFlightNode, false)
+                        return
+                    }
+                    acceptValue(step.value)
+                    writeNode(errorNode, undefined)
+                    writeNode(inFlightNode, false)
+                }
+            } catch (error) {
+                settleError(myRun, error)
+            }
+        }
+        /* The pump never rejects (its body is fully try/caught), so the kickoff is contained
+           — no unhandled rejection, never Bun-fatal. */
+        void pump()
+    }
+
+    /* Run (or re-run) the seed. `reseed` marks a dependency-driven new source, which clears
+       the write latch; a `refresh()` passes false so a held write and value survive. */
+    const run = (reseed: boolean): void => {
+        runId += 1
+        const myRun = runId
+        if (cancelStream !== undefined) {
+            cancelStream()
+            cancelStream = undefined
+        }
+        if (reseed) {
+            written = false
+        }
+        writeNode(inFlightNode, true)
+
+        let produced: unknown
+        try {
+            produced = seed()
+        } catch (error) {
+            settleError(myRun, error)
+            return
+        }
+
+        if (isAsyncIterable(produced)) {
+            consumeStream(myRun, produced as NamedAsyncIterable<unknown>)
+            return
+        }
+        if (isThenable(produced)) {
+            inFlight = produced as Promise<unknown>
+            /* Server-only: register the in-flight promise on the request-scoped pending list so
+               the SSR barrier (`$$settleAsyncCells`) awaits it before the template peeks the
+               cell — baking the resolved value into the first-pass HTML (ADR-0019 Tier-2). A
+               stream (the `isAsyncIterable` branch above) never registers: it never settles. The
+               `window` guard keeps client construction from ever registering. A `streaming`
+               cell (ADR-0032, a no-`await` position) opts OUT: it ships pending and resolves on
+               the client instead of blocking the flush. */
+            if (typeof window === 'undefined' && options.streaming !== true) {
+                activePendingCells()?.promises.push(inFlight)
+            }
+            /* `.then(onValue, onError)` handles the rejection inline — contained in `error()`,
+               never an unhandled rejection. A STREAMING cell's resolved value is recorded in
+               `settleValue` (ADR-0035), not here — awaiting the promise could hang if it never
+               settles this request. */
+            ;(produced as PromiseLike<unknown>).then(
+                (value) => settleValue(myRun, value),
+                (error) => settleError(myRun, error),
+            )
+            return
+        }
+        settleValue(myRun, produced)
+    }
+
+    /* Warm hydrate: if the server shipped this cell's resolved value (keyed by its render-path
+       id), adopt it NOW — before the eager run — so `hasValue` is already true. The cell then reads
+       as REFRESHING (not pending) through the eager run below, so the value shows instantly with no
+       flash and matches the SSR-rendered branch. The run still fires (revalidate + subscribe the
+       seed's deps for reactivity, SWR), and its settle supersedes via the `runId` guard. Client-
+       only in effect (the store is only ever populated by `startClient`, so it's empty on the
+       server — no `window` sniff needed); a decode failure falls through to a cold run. */
+    if (warmKey !== undefined) {
+        const seeded = CELL_SEED[warmKey]
+        if (seeded !== undefined) {
+            /* One-shot: consume the seed so a LATER fresh mount at the same render-path can't
+               warm-adopt this boot-time snapshot. `scope.id` is the route PATTERN (params-
+               independent), so an SPA navigation `/products/42`→`/products/99` — or a back-nav
+               that rebuilds the SSR page — recomputes the identical warmKey; without deleting,
+               the new cell would render `/products/42`'s stale value until revalidation. The seed
+               only ever hydrates the initial SSR render, where each cell is constructed once. */
+            delete CELL_SEED[warmKey]
+            try {
+                acceptValue(decodeRefJson(seeded))
+            } catch {
+                /* Unserializable/corrupt seed → cold run renders it. */
+            }
+        }
+    }
+
+    /* The eager first-run + reactive reseed: the effect tracks the seed's synchronous reads,
+       so a dependency change re-runs it. Its cleanup cancels any live stream on reseed/dispose. */
+    createEffectNode(() => {
+        run(true)
+        return (): void => {
+            if (cancelStream !== undefined) {
+                cancelStream()
+                cancelStream = undefined
+            }
+        }
+    })
+
+    /* Client-only, STREAMING cells (ADR-0035): a streaming cell ships pending and its value streams
+       in AFTER the shell. Register — AFTER the eager run above, so its `inFlight = true` is already
+       set — to receive that value by render-path id; when it lands, adopt it as a reactive update:
+       the value shows immediately (no `loading…` flash) and the in-flight cold seed run re-settles
+       the same value, superseded by the write latch. The streamed value only ever seeds the initial
+       render; a later dep-driven reseed is authoritative and runs the seed as usual. */
+    if (warmKey !== undefined && options.streaming === true && typeof window !== 'undefined') {
+        registerStreamedCell(warmKey, (value) => {
+            acceptValue(value)
+            writeNode(errorNode, undefined)
+            writeNode(inFlightNode, false)
+        })
+    }
+
+    /* The shared read surface, identical for read-only and writable cells. */
+    const readOnly: AsyncComputed<unknown> = {
+        [ASYNC_CELL]: true,
+        peek: () => readNode(valueNode),
+        /* No value yet: in flight and nothing retained. */
+        pending: () => readNode(inFlightNode) === true && readNode(hasValueNode) !== true,
+        /* A held value being superseded: in flight but a value is retained. */
+        refreshing: () => readNode(inFlightNode) === true && readNode(hasValueNode) === true,
+        error: () => readNode(errorNode),
+        /* Re-invoke the seed keeping the value visible (SWR); not a reseed, so a write holds. */
+        refresh: () => run(false),
+        /* The current in-flight promise (undefined once settled / not-a-promise) — an internal
+           runtime affordance the SSR barrier reads structurally; not on the public cell types. */
+        settled: () => inFlight,
+    } as AsyncComputed<unknown>
+    if (!options.writable) {
+        return readOnly
+    }
+    /* A writable cell adds `set()`: latches until the next reseed. `settled` rides along from
+       the `readOnly` spread (a runtime affordance not on the public type). */
+    const writable: AsyncState<unknown> = {
+        ...readOnly,
+        set: (value: unknown): void => {
+            written = true
+            writeNode(
+                valueNode,
+                transform === undefined ? value : transform(value, valueNode.value),
+            )
+            writeNode(hasValueNode, true)
+        },
+    }
+    return writable
+}