@abide/abide 0.53.0 → 0.55.0

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

@@ -1,11 +1,10 @@
+import { SEEDS } from '../../shared/SEEDS.ts'
+
 /* The doc-state warm-seed manifest: an SSR-captured reactive-document snapshot, keyed by its
    scope's serialization-stable render-path id, as a ref-json-encoded STRING (decoded at the read
    site in `createScope`). `startClient` drains `__SSR__.docs` into here before mount; a hydrating
    scope reads its key to seed a plain `state(initial)` to the SERVER value instead of the fresh
-   init — a uuid/timestamp/random otherwise diverges from the SSR HTML. Backed by
-   `globalThis.__abideDocs` so an inline pre-bundle script and the framework share one store —
-   whoever runs first creates it, the other adopts the same reference (mirrors CELL_SEED). */
-const globalScope = globalThis as { __abideDocs?: Record<string, string> }
-globalScope.__abideDocs ??= {}
+   init — a uuid/timestamp/random otherwise diverges from the SSR HTML.
 
-export const DOC_SEED: Record<string, string> = globalScope.__abideDocs
+   The `docs` partition of the one `__abideSeeds` manifest (ADR-0048, see SEEDS). */
+export const DOC_SEED: Record<string, string> = SEEDS.docs

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

@@ -1,9 +1,11 @@
+import type { HydrationCursor } from './types/HydrationCursor.ts'
+
 /*
 Render mode shared by the dom helpers. In the default (create) mode `hydration`
-is undefined and helpers build fresh nodes. During `hydrate` it holds, per parent,
-the next server-rendered child node to claim — a node pointer (not an index) so it
-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.
+is undefined and helpers build fresh nodes. During `hydrate` it holds the pass's
+claim cursor (see `HydrationCursor`): helpers claim in build order, which matches
+the SSR order, advancing through the claim verbs (`claimMarker`/`claimRun`/
+`claimText`) or parking explicitly (`parkCursor`).
 
 `blockCounters`/`depth` drive the render-pass block-id counters: every `await`/`try`
 block draws a path-namespaced id via `nextBlockId` (ADR-0037) — `blockCounters` maps
@@ -21,7 +23,7 @@ elements built there get the right namespace — the fragment itself carries non
 undefined outside foreign content. See `enterNamespace`/`effectiveChildNamespace`.
 */
 export const RENDER: {
-    hydration: { next: Map<Node, Node | null> } | undefined
+    hydration: HydrationCursor | undefined
     blockCounters: Map<string, number>
     depth: number
     namespace: string | undefined

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

@@ -1,3 +1,5 @@
+import { SEEDS } from '../../shared/SEEDS.ts'
+
 /* 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 the inline swap script),
@@ -11,13 +13,9 @@
    stream-swap script — vanilla, running before the bundle and the codec load — able
    to register an entry without the decoder.
 
-   Backed by `globalThis.__abideResume` so the inline stream-swap script and the
-   framework share one store: whoever runs first creates it, the other adopts the
-   same reference. */
+   The `resume` partition of the one `__abideSeeds` manifest (ADR-0048, see SEEDS) —
+   the inline scripts and the framework share the same reference. */
 export type ResumeEntry = { ok: true; value: unknown } | { ok: false; error: unknown }
 
-const globalScope = globalThis as { __abideResume?: Record<string, string> }
-globalScope.__abideResume ??= {}
-
 // @documentation plumbing
-export const RESUME: Record<string, string> = globalScope.__abideResume
+export const RESUME: Record<string, string> = SEEDS.resume

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

@@ -0,0 +1,14 @@
+/* The active hydration pass's consumed-seed marks (ADR-0048 two-phase consume): each seed a
+   pass adopts is MARKED here rather than deleted, so a THROWING pass leaves every value in
+   place for the cold rebuild to re-adopt (no shadow backup), while the OUTERMOST clean pass
+   exit deletes the marked keys — preserving the one-shot contract (an SPA re-nav to the same
+   render-path re-inits fresh). Keyed per store so a mark is an O(1) Set add on the hydrate
+   hot path. Owned by `runHydrationPass`: save/restore for nesting, and a nested clean exit
+   hands its marks to the enclosing pass instead of committing — only the outermost owner
+   spends seeds, so an outer-pass throw can still hand every value to the recovery rebuild.
+   undefined outside a pass, where `consumeSeed` falls back to delete-on-read. Deliberately
+   NOT cleared by `withoutHydration` — a fresh build inside a live pass (a block's cold
+   rebuild) still marks and re-adopts. */
+export const SEED_MARKS: {
+    current: Map<Record<string, string>, Set<string>> | undefined
+} = { current: undefined }

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

@@ -1,8 +1,8 @@
 import type { AsyncComputed } from '../../shared/types/AsyncComputed.ts'
 
 /*
-The sentinel a compiled blocking read (`$$readCellBlocking`, an `await`-marked cell) raises
-when the cell has no value *yet* — "not resolved," not an error (ADR-0042 D3). It is a sibling
+The sentinel `readCell` raises when a BLOCKING cell (`cell.blocking` — an `await`-marked cell)
+has no value *yet* — "not resolved," not an error (ADR-0042 D3). It is a sibling
 of `AsyncCellError` but a DISTINCT class so the two are told apart by `instanceof`: a suspend is
 caught LOCALLY by the reading region — each DOM primitive (`appendText`, `attr`, `each`,
 `spreadAttrs`, `watch`, and the `when`/`switchBlock` condition) swallows it and withholds to an

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

@@ -1,10 +1,8 @@
-import type { RENDER } from './RENDER.ts'
+import type { HydrationCursor } from './types/HydrationCursor.ts'
 
-/* The next server-rendered node to claim under `parent` during hydration,
-   defaulting to its first child when the pointer hasn't been set yet. */
-export function claimChild(
-    hydration: NonNullable<(typeof RENDER)['hydration']>,
-    parent: Node,
-): Node | null {
+/* The next server-rendered node to claim under `parent` during hydration — a PROBE
+   (the cursor doesn't move), defaulting to the first child when the pointer hasn't
+   been set yet. The claim verbs read through this and advance via `parkCursor`. */
+export function claimChild(hydration: HydrationCursor, parent: Node): Node | null {
     return hydration.next.has(parent) ? (hydration.next.get(parent) ?? null) : parent.firstChild
 }

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

@@ -1,7 +1,7 @@
 import { CURRENT_PATH } from './CURRENT_PATH.ts'
 import { claimChild } from './claimChild.ts'
-import type { RENDER } from './RENDER.ts'
 import { reportHydrationDivergence } from './reportHydrationDivergence.ts'
+import type { HydrationCursor } from './types/HydrationCursor.ts'
 
 /*
 A hydration claim that MUST succeed. Like `claimChild`, but throws a structural error
@@ -13,11 +13,7 @@ invariant from a compile-time-only parity test into a runtime guard. Use only wh
 compiled skeleton GUARANTEES a node — control-flow range markers, keyed-row boundaries —
 never where an end-of-list null is legitimate (e.g. a trailing reactive text binding).
 */
-export function claimExpected(
-    hydration: NonNullable<(typeof RENDER)['hydration']>,
-    parent: Node,
-    expected: string,
-): Node {
+export function claimExpected(hydration: HydrationCursor, parent: Node, expected: string): Node {
     const node = claimChild(hydration, parent)
     if (node === null) {
         /* Name where first on the `hydrate` channel (return ignored — a missing structural node

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

@@ -0,0 +1,13 @@
+import { claimExpected } from './claimExpected.ts'
+import { parkCursor } from './parkCursor.ts'
+import type { HydrationCursor } from './types/HydrationCursor.ts'
+
+/* Claims a compiler-guaranteed marker node (a range bracket, a block/boundary comment,
+   a keyed-row bracket) at the parent's cursor and advances past it. Throws a legible
+   structural desync when no node is there (`claimExpected`) — a missing marker means
+   SSR markup and the client build disagree on structure at this position. */
+export function claimMarker(hydration: HydrationCursor, parent: Node, expected: string): Comment {
+    const node = claimExpected(hydration, parent, expected)
+    parkCursor(hydration, parent, node.nextSibling)
+    return node as Comment
+}

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

@@ -0,0 +1,22 @@
+import { claimChild } from './claimChild.ts'
+import { parkCursor } from './parkCursor.ts'
+import type { HydrationCursor } from './types/HydrationCursor.ts'
+
+/* Claims a run of `count` top-level server-rendered siblings at the parent's cursor and
+   parks it past them (a short run — the server DOM ending early — parks on null). The
+   static-clone paths advance through this: the markup is byte-identical to the server's,
+   so nothing inside needs claiming individually. `into` collects the claimed nodes when
+   the caller resolves holes against them (`skeleton`); omitted, the run is only skipped. */
+export function claimRun(
+    hydration: HydrationCursor,
+    parent: Node,
+    count: number,
+    into?: Node[],
+): void {
+    let node = claimChild(hydration, parent)
+    for (let index = 0; index < count && node !== null; index += 1) {
+        into?.push(node)
+        node = node.nextSibling
+    }
+    parkCursor(hydration, parent, node)
+}

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

@@ -0,0 +1,38 @@
+import { SEED_MARKS } from './SEED_MARKS.ts'
+
+/*
+Reads a warm-seed entry (`CELL_SEED` / `DOC_SEED`) under the one-shot contract: a seed
+hydrates exactly one pass, so a LATER fresh mount at the same render-path can't
+warm-adopt a stale boot-time snapshot (an SPA navigation recomputes the identical key).
+
+Two-phase (ADR-0048): during a hydration pass the read MARKS the entry instead of deleting
+it — a clean pass exit deletes the marked keys, and a THROWING pass leaves every value in
+place, so the discard→cold-rebuild recovery re-adopts the SSR-resolved values instead of
+refetching (a cold refetch would leave blocking `await` cells pending and escape as an
+uncaught SuspenseSignal at mount). WITHIN a pass the read is idempotent — a repeat read
+re-adopts the still-present value, because the repeat is a block-level cold rebuild
+reconstructing the same render-path inside the live pass (its first construction marked
+the key, then the adopt desynced); the one-shot half is enforced at pass exit, not per
+read. Outside a pass — the recovery rebuild itself, a manual client-only mount — the
+read deletes immediately, the plain one-shot.
+*/
+export function consumeSeed(store: Record<string, string>, key: string): string | undefined {
+    const marks = SEED_MARKS.current
+    if (marks === undefined) {
+        const value = store[key]
+        if (value !== undefined) {
+            delete store[key]
+        }
+        return value
+    }
+    const value = store[key]
+    if (value !== undefined) {
+        let keys = marks.get(store)
+        if (keys === undefined) {
+            keys = new Set()
+            marks.set(store, keys)
+        }
+        keys.add(key)
+    }
+    return value
+}

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

@@ -12,10 +12,12 @@ 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 { consumeSeed } from './consumeSeed.ts'
 import { createEffectNode } from './createEffectNode.ts'
 import { createSignalNode } from './createSignalNode.ts'
 import { readNode } from './readNode.ts'
 import { registerStreamedCell } from './STREAMED_CELLS.ts'
+import { SuspenseSignal } from './SuspenseSignal.ts'
 import { writeNode } from './writeNode.ts'
 
 /* The seed's transform gate (mirrors `state`/`linked`): coerces every value entering
@@ -83,6 +85,14 @@ export function createAsyncCell(
     let inFlight: Promise<unknown> | undefined
     /* Cancels the active stream subscription (a reseed, refresh, or dispose supersedes it). */
     let cancelStream: (() => void) | undefined
+    /* Whether a pending read of this cell PAUSES its reader (ADR-0046). True only for a
+       BLOCKING source — a settling PROMISE the cell would join the SSR barrier for (author
+       `await`, or a fail-open bare-call that registers): `streaming !== true` AND the seed
+       produced a thenable. A STREAM (`isAsyncIterable`) never settles and always peeks, so it
+       is NOT blocking even though it carries the same default `streaming` flag; `run` clears
+       this when it sees a stream. Resolved from the produced source, not the flag alone, so
+       `streaming: false` cannot conflate "author `await`" with "stream". */
+    let blockingSource = false
 
     /* Store a produced value, honouring the write latch and the transform gate. */
     const acceptValue = (value: unknown): void => {
@@ -126,6 +136,16 @@ export function createAsyncCell(
             return
         }
         inFlight = undefined
+        /* A `SuspenseSignal` is a PAUSE, not a failure — the same as the synchronous case in
+           `run`, but arriving through a REJECTION: an async seed (`computed(await f(dep))`) reads a
+           pending blocking `dep` in its synchronous prefix, and the throw becomes the thunk's
+           rejection rather than a sync throw. Stay pending (leave `inFlightNode` true, hold no
+           error); the throwing read subscribed this seed's effect to `dep` during that prefix, so
+           it re-runs and produces the real source once `dep` settles. */
+        if (error instanceof SuspenseSignal) {
+            writeNode(errorNode, undefined)
+            return
+        }
         writeNode(errorNode, error)
         writeNode(inFlightNode, false)
     }
@@ -181,15 +201,35 @@ export function createAsyncCell(
         try {
             produced = seed()
         } catch (error) {
+            /* A `SuspenseSignal` is a PAUSE, not a failure: this seed read a blocking
+               dependency that has no value yet, so this cell's branch pauses too. Stay
+               pending — leave `inFlightNode` true, hold no value, carry no error — rather
+               than latching the pause into `error()`. The throwing read already subscribed
+               this seed's effect to the pending dependency, so when it settles the effect
+               re-runs the seed, which now reads a value and produces the real source. No
+               promise is registered (there is none), so the SSR barrier's fixpoint drain
+               picks this cell up on that re-run instead. */
+            if (error instanceof SuspenseSignal) {
+                if (myRun === runId) {
+                    inFlight = undefined
+                    writeNode(errorNode, undefined)
+                }
+                return
+            }
             settleError(myRun, error)
             return
         }
 
         if (isAsyncIterable(produced)) {
+            /* A stream never settles — it PEEKS `undefined` until its first frame, never pauses. */
+            blockingSource = false
             consumeStream(myRun, produced as NamedAsyncIterable<unknown>)
             return
         }
         if (isThenable(produced)) {
+            /* A settling promise the cell would join the SSR barrier for (author `await`, or a
+               fail-open bare-call) PAUSES a pending read; a `streaming` promise peeks. */
+            blockingSource = options.streaming !== true
             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
@@ -222,15 +262,15 @@ export function createAsyncCell(
        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]
+        /* One-shot via `consumeSeed` (two-phase, ADR-0048): 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; unconsumed,
+           the new cell would render `/products/42`'s stale value until revalidation. During a
+           hydration pass the consume only MARKS, so a desync throw hands the seed to the cold
+           rebuild instead of losing it. */
+        const seeded = consumeSeed(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 {
@@ -279,6 +319,14 @@ export function createAsyncCell(
         /* 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,
+        /* Whether a pending read of this cell PAUSES its reader (ADR-0046) — true only for a
+           blocking source (a barrier-joining settling promise), resolved from what the seed
+           produced (`blockingSource`) so a stream (which shares the default `streaming` flag)
+           is correctly NON-blocking. A getter, since the seed's eager run sets it. `readCell`
+           consults it; an internal affordance, not on the public cell type. */
+        get blocking(): boolean {
+            return blockingSource
+        },
     } as AsyncComputed<unknown>
     if (!options.writable) {
         return readOnly

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

@@ -13,6 +13,7 @@ export function createComputedNode(compute: () => unknown): ReactiveNode {
         subsHead: undefined,
         subsTail: undefined,
         status: NODE_STATE.DIRTY,
+        thrown: undefined,
         isEffect: false,
     }
 }

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

@@ -312,6 +312,7 @@ export function createDoc(initial: unknown): Doc {
                 parent ??= resolveParent()
                 parent[leafKey] = value
                 writeNode(node, value)
+                return value
             },
         }
     }
@@ -321,7 +322,10 @@ export function createDoc(initial: unknown): Doc {
         cell,
         derive,
         apply,
-        replace: (path, value) => apply({ op: 'replace', path, value }),
+        replace: (path, value) => {
+            apply({ op: 'replace', path, value })
+            return value
+        },
         add: (path, value) => apply({ op: 'add', path, value }),
         remove: (path) => apply({ op: 'remove', path }),
         snapshot: () => tree,

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

@@ -52,6 +52,7 @@ export function createEffectNode(fn: () => EffectResult): () => void {
         subsTail: undefined,
         /* Born DIRTY; the immediate `runNode` below captures deps and settles it CLEAN. */
         status: NODE_STATE.DIRTY,
+        thrown: undefined,
         isEffect: true,
     }
     runNode(node)

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

@@ -13,6 +13,7 @@ export function createSignalNode(value: unknown): ReactiveNode {
         subsHead: undefined,
         subsTail: undefined,
         status: NODE_STATE.CLEAN,
+        thrown: undefined,
         isEffect: false,
     }
 }

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

@@ -0,0 +1,10 @@
+import type { HydrationCursor } from './types/HydrationCursor.ts'
+
+/* Repositions the parent's claim cursor at `reference` (null = past the last child). The
+   ONE write site of the cursor invariant: every claim must leave the cursor on the next
+   unclaimed sibling, or the following claim grabs the wrong node — a silent desync. The
+   claim verbs advance through here; a block parks explicitly when it skips or discards a
+   region (an anchor's content, a boundary it re-claims later, a discarded range). */
+export function parkCursor(hydration: HydrationCursor, parent: Node, reference: Node | null): void {
+    hydration.next.set(parent, reference)
+}

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

@@ -8,10 +8,30 @@ settles first (the lazy pull — `updateIfNecessary` refreshes only the deps tha
 changed, recomputing if any did); a signal has no compute and returns its stored
 value directly. Tracking happens after the settle so the reader links to the
 computed itself, not its transitive deps.
+
+The settle runs in a `try` whose `finally` still links the reader: an edge to a
+node is an edge even when that node is currently PAUSED. A computed whose compute
+throws — the common case being a `SuspenseSignal` from a pending blocking cell it
+reads — must still leave its reader subscribed to it, or the reader would never
+re-run when the paused branch resolves (the compute re-runs on settle via its own
+retained deps, then this reader wakes off its edge to the computed). The signal
+fast-path stays a plain track — it has no compute to throw and is the hot read.
 */
 export function readNode(node: ReactiveNode): unknown {
     if (node.compute !== undefined) {
-        updateIfNecessary(node)
+        try {
+            updateIfNecessary(node)
+            /* Throw memoisation: a paused/erroring compute settled CLEAN with its throw
+               retained (`runNode`'s catch) — rethrow it so EVERY reader observes the
+               pause/error, not just the one whose read ran the compute. Cleared by the
+               next successful run once a dep change re-dirties the node. */
+            if (node.thrown !== undefined) {
+                throw node.thrown
+            }
+        } finally {
+            track(node)
+        }
+        return node.value
     }
     track(node)
     return node.value

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

@@ -3,8 +3,8 @@ import { withPath } from './withPath.ts'
 
 /*
 The render-path a `<Child/>` mounts under — the boundary id of a STREAMED child component (ADR-0039).
-Composes the child's ordinal segment onto the ambient path exactly as the client's `mountChild` /
-`mountStreamedChild` does (`withPath(ordinal, …)`), so the server-written `abide:await:CHILDPATH`
+Composes the child's ordinal segment onto the ambient path exactly as the client's dual-mode
+`mountChild` does (`withPath(ordinal, …)`), so the server-written `abide:await:CHILDPATH`
 boundary and the client adopter compute the SAME id with no counter to drift. It carries `/`
 separators and never a `:`, so a child path (`products/0`) can't collide with an await-block id
 (`products:0`). Server-emit-only (the streaming boundary is server codegen), so it tree-shakes out of

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

@@ -0,0 +1,28 @@
+import { isAsyncIterable } from '../../shared/isAsyncIterable.ts'
+import { isThenable } from '../../shared/isThenable.ts'
+import type { AsyncComputed } from '../../shared/types/AsyncComputed.ts'
+import type { AsyncState } from '../../shared/types/AsyncState.ts'
+import { createAsyncCell } from './createAsyncCell.ts'
+
+/*
+The ONE statement of the ADR-0045 bare-seed contract for `computed`/`linked`: a bare
+seed that reached the runtime literally (a branch-nested `<script>` keeps its
+`state.computed(...)` calls literal, and a direct JS caller never compiles) routes BY
+VALUE exactly as its thunk form would — a promise → a streaming unwrapped value cell, a
+stream → a frame cell. Anything else returns `undefined`: not async, the caller wraps it
+as a constant seed thunk. The classification order (thenable before async-iterable) and
+the streaming flag are load-bearing and shared here so the two primitives cannot drift.
+*/
+export function routeBareSeed(
+    value: unknown,
+    writable: boolean,
+    transform?: (next: unknown, previous: unknown) => unknown,
+): AsyncComputed<unknown> | AsyncState<unknown> | undefined {
+    if (isThenable(value)) {
+        return createAsyncCell(() => value, { writable, transform, streaming: true })
+    }
+    if (isAsyncIterable(value)) {
+        return createAsyncCell(() => value, { writable, transform })
+    }
+    return undefined
+}

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

@@ -0,0 +1,69 @@
+import { hydrationWindow } from '../../shared/hydrationWindow.ts'
+import { enterRenderPass } from './enterRenderPass.ts'
+import { exitRenderPass } from './exitRenderPass.ts'
+import { RENDER } from './RENDER.ts'
+import { SEED_MARKS } from './SEED_MARKS.ts'
+
+/*
+The one owner of a hydration pass's lifecycle. A pass is four lifetimes that must open
+and close together — the claim cursor (`RENDER.hydration`), the cache-withhold window
+(`hydrationWindow`, which `cache.peek` reads), the block-id render pass
+(`enterRenderPass`), and the two-phase seed consume (`SEED_MARKS`/`consumeSeed`,
+ADR-0048): the seeds a pass adopts are only MARKED while it runs, deleted on the
+OUTERMOST clean exit, and left in place on a throw — so the caller's
+discard→cold-rebuild recovery re-adopts the SSR-resolved values instead of refetching
+(a cold refetch would leave blocking `await` cells pending and escape as an uncaught
+SuspenseSignal at mount).
+
+Both entry points (`hydrate`, the router's hydrating first mount) run through here, so
+the bracket order and the throw semantics can't drift between them. Nesting is safe:
+the cursor saves/restores, the window/render-pass are depth-counted, and a nested
+clean exit hands its marks to the enclosing pass rather than committing — if the outer
+pass later throws, the nested pass's seeds are still in place for the recovery rebuild.
+*/
+export function runHydrationPass<T>(run: () => T): T {
+    const previous = RENDER.hydration
+    const previousMarks = SEED_MARKS.current
+    RENDER.hydration = { next: new Map() }
+    SEED_MARKS.current = new Map()
+    try {
+        hydrationWindow.enter()
+        enterRenderPass()
+        try {
+            const result = run()
+            const marks = SEED_MARKS.current
+            if (previousMarks === undefined) {
+                /* Outermost clean pass: spend the adopted seeds, preserving the one-shot
+                   contract (a later mount at the same render-path re-inits fresh, never a
+                   stale snapshot). */
+                for (const [store, keys] of marks) {
+                    for (const key of keys) {
+                        delete store[key]
+                    }
+                }
+            } else {
+                /* Nested clean pass: merge the marks upward — only the outermost owner
+                   commits, so an outer throw still leaves every value in place. */
+                for (const [store, keys] of marks) {
+                    let outerKeys = previousMarks.get(store)
+                    if (outerKeys === undefined) {
+                        outerKeys = new Set()
+                        previousMarks.set(store, outerKeys)
+                    }
+                    for (const key of keys) {
+                        outerKeys.add(key)
+                    }
+                }
+            }
+            return result
+        } finally {
+            exitRenderPass()
+            RENDER.hydration = previous
+            /* Outermost exit clears the window and wakes the peeks this pass withheld for
+               SSR congruence, now that the warm value is congruent to show. */
+            hydrationWindow.exit()
+        }
+    } finally {
+        SEED_MARKS.current = previousMarks
+    }
+}

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

@@ -52,7 +52,21 @@ export function runNode(node: ReactiveNode): unknown {
             }
         }
         node.status = NODE_STATE.CLEAN
+        node.thrown = undefined
         return node.value
+    } catch (error) {
+        /* The compute threw — commonly a `SuspenseSignal` from a pending blocking cell it read,
+           propagating the pause down this edge. Settle the node CLEAN anyway (its value is left
+           stale) so a later change to the deps it DID track before throwing re-marks it DIRTY and
+           re-propagates to its subscribers; left DIRTY, `mark`'s status gate would take the
+           settle's CLEAN→DIRTY edge as already-dirty and leave the node permanently inert — the
+           same reset `flushEffects` applies to a thrown effect. The throw is also RETAINED on the
+           node: a CLEAN settle memoises, so without it only this first reader would observe the
+           pause/error and every later reader would silently get the stale value — `readNode`
+           rethrows the retained throw until the next successful run clears it. */
+        node.status = NODE_STATE.CLEAN
+        node.thrown = error
+        throw error
     } finally {
         REACTIVE_CONTEXT.observer = previous
         /* Drop the edges `track` didn't reuse — last run's now-stale dependencies. */

package/src/lib/ui/runtime/types/Cell.ts

@@ -1,5 +1,7 @@
 /* A stable reactive accessor bound to one document path: `get` subscribes the
    running observer, `set` mutates that path and wakes its readers — all path
    resolution done once at bind time, so the access itself is string-free. This
-   is the shape the template compiler emits for a `{path}` read / write. */
-export type Cell<T> = { get: () => T; set: (value: T) => void }
+   is the shape the template compiler emits for a `{path}` read / write. `set`
+   returns the written value so a lowered assignment evaluates to that value in
+   expression position (chained `a = b = x`, the postfix `x++` correction). */
+export type Cell<T> = { get: () => T; set: (value: T) => T }

package/src/lib/ui/runtime/types/Doc.ts

@@ -15,7 +15,9 @@ export type Doc = {
        stored/serialized/journalled) and returns a string-free reader bound to it. */
     derive: <T>(path: string, compute: () => T) => () => T
     apply: (patch: Patch) => void
-    replace: (path: string, value: unknown) => void
+    /* Returns the written value so a lowered assignment/`++` evaluates to it in
+       expression position (mirrored by `Scope.replace` and `Cell.set`). */
+    replace: (path: string, value: unknown) => unknown
     add: (path: string, value: unknown) => void
     remove: (path: string) => void
     snapshot: () => unknown

package/src/lib/ui/runtime/types/HydrationCursor.ts

@@ -0,0 +1,8 @@
+/* The active hydration pass's claim cursor: per parent, the next server-rendered child
+   to claim — a node pointer (not an index) so it survives nodes a block inserts (anchors,
+   range brackets) mid-hydration. Read through `claimChild` (probe) / the claim verbs
+   (claim + advance); repositioned through `parkCursor`. The live instance hangs off
+   `RENDER.hydration` (undefined outside a pass). */
+export type HydrationCursor = {
+    next: Map<Node, Node | null>
+}

package/src/lib/ui/runtime/types/ReactiveNode.ts

@@ -24,5 +24,10 @@ export type ReactiveNode = {
        NODE_STATE). A signal is always CLEAN (no compute); a computed is born DIRTY and
        cycles CLEAN→CHECK/DIRTY→CLEAN as deps change and reads settle it. */
     status: number
+    /* Throw memoisation: what the last compute threw (commonly a `SuspenseSignal`
+       pause), retained while the node sits CLEAN so EVERY reader observes the pause or
+       error — not just the one whose read ran the compute. Cleared by the next
+       successful run; undefined on a signal (no compute to throw). */
+    thrown: unknown
     isEffect: boolean
 }