@abide/abide 0.54.0 → 0.55.0

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

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

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

@@ -1,7 +1,8 @@
 import { decodeRefJson } from '../../shared/decodeRefJson.ts'
+import { isThenable } from '../../shared/isThenable.ts'
 import { effect } from '../effect.ts'
 import { CURRENT_BOUNDARY } from '../runtime/CURRENT_BOUNDARY.ts'
-import { claimExpected } from '../runtime/claimExpected.ts'
+import { claimMarker } from '../runtime/claimMarker.ts'
 import { generationGuard } from '../runtime/generationGuard.ts'
 import { RANGE_CLOSE, RANGE_OPEN } from '../runtime/RANGE_MARKER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
@@ -10,10 +11,9 @@ import { RESUME } from '../runtime/RESUME.ts'
 import { SuspenseSignal } from '../runtime/SuspenseSignal.ts'
 import { scopeGroup } from '../runtime/scopeGroup.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 { discardAndRebuild } from './discardAndRebuild.ts'
 
 /*
 Async binding — the runtime for `<template await>`. Renders the pending branch,
@@ -159,44 +159,42 @@ export function awaitBlock(
        bracketing — it runs only after a clean build. */
     const adopt = (open: Node | null, build: (parent: Node) => void): void => {
         const cursor = hydration as NonNullable<typeof hydration>
+        /* The cursor already sits here (claiming `open` advanced past it); kept for the
+           bracketing below. */
         const firstAdopted = open?.nextSibling ?? null
-        cursor.next.set(parent, firstAdopted)
         branch.adoptStrand(build, () => {
-            /* A guaranteed control-flow marker — claimExpected throws on a desync (caught by
+            /* A guaranteed control-flow marker — the claim throws on a desync (caught by
                firstHydrate's adopt try/catch → rebuildCold) instead of silently claiming null
                and over-clearing the parent. */
-            const close = claimExpected(cursor, parent, `/abide:await:${id} close marker`)
-            cursor.next.set(parent, close.nextSibling ?? null)
+            const close = claimMarker(cursor, parent, `/abide:await:${id} close marker`)
             /* Bracket the adopted nodes: `[` before the first claimed node (or before `close`
                for an empty branch), `]` then the anchor just before `close`. */
             const start = document.createComment(RANGE_OPEN)
             parent.insertBefore(start, firstAdopted ?? close)
             const end = document.createComment(RANGE_CLOSE)
             parent.insertBefore(end, close)
-            const anchorNode = document.createTextNode('')
-            parent.insertBefore(anchorNode, close)
-            branch.anchor = anchorNode
+            branch.parkAnchor(close)
             return { start, end }
         })
     }
 
-    /* Discard the SSR boundary and (re)build the block from the live promise, fresh
-       (hydration off) — the recovery path when adoption can't use the server markup. */
-    const rebuildCold = (open: Node | null): void => {
+    /* Discard the SSR boundary and (re)build the block from `result`, fresh (hydration
+       off) — the recovery path when adoption can't use the server markup. Insert the
+       anchor at the node AFTER the discarded boundary — NOT the captured `before`, which
+       for a skeleton-anchored block is the open boundary itself and is removed here, so
+       reusing it throws `NotFoundError` in a strict DOM. */
+    const rebuildCold = (open: Node | null, result: () => unknown): void => {
         branch.detach()
-        /* Insert at the node AFTER the discarded boundary (its return) — NOT the captured
-           `before`, which for a skeleton-anchored block is the open boundary itself and is
-           removed here, so reusing it throws `NotFoundError` in a strict DOM. */
-        const after = discardBoundary(
+        discardAndRebuild(
+            hydration as NonNullable<typeof hydration>,
             parent,
             open,
             `/abide:await:${id}`,
-            hydration as NonNullable<typeof hydration>,
+            (after) => {
+                branch.parkAnchor(after)
+                render(result())
+            },
         )
-        const anchorNode = document.createTextNode('')
-        branch.anchor = anchorNode
-        parent.insertBefore(anchorNode, after)
-        withoutHydration(() => render(promiseThunk()))
     }
 
     /* The first run when hydrating: adopt by precedence (resume / warm-sync), else
@@ -206,9 +204,9 @@ export function awaitBlock(
        warm cache (or re-fetches) instead of crashing hydration. */
     const firstHydrate = (): void => {
         const cursor = hydration as NonNullable<typeof hydration>
-        /* The await block's open marker is compiler-guaranteed — claimExpected throws a
+        /* The await block's open marker is compiler-guaranteed — the claim throws a
            legible desync here rather than propagating a null that over-clears the parent. */
-        const open = claimExpected(cursor, parent, `abide:await:${id} open marker`)
+        const open = claimMarker(cursor, parent, `abide:await:${id} open marker`)
         /* RESUME holds the ref-json-encoded entry STRING; decode here, where the codec
            lives. A decode failure (malformed/absent payload) reads as "no resume" — fall
            through to the live promise rather than crash hydration. */
@@ -233,7 +231,7 @@ export function awaitBlock(
                would otherwise surface as an unhandledrejection at boot (process-fatal under
                Bun) instead of being harmlessly dropped. */
             if (isThenable(result)) {
-                void (result as PromiseLike<unknown>).then(undefined, () => undefined)
+                void result.then(undefined, () => undefined)
             }
             /* Build the adopted branch around a value CELL (then) so a later re-run updates
                it in place, exactly like a fresh mount. The `throw` for a catch-less rejection
@@ -260,7 +258,7 @@ export function awaitBlock(
                 valueCell = cell
                 activeKind = kind
             } catch {
-                rebuildCold(open)
+                rebuildCold(open, promiseThunk)
             }
             return
         }
@@ -271,19 +269,14 @@ export function awaitBlock(
                 valueCell = cell
                 activeKind = 'then'
             } catch {
-                rebuildCold(open)
+                rebuildCold(open, promiseThunk)
             }
             return
         }
-        /* Insert at the node after the discarded boundary (see `rebuildCold`). */
-        const after = discardBoundary(parent, open, `/abide:await:${id}`, cursor)
-        const anchorNode = document.createTextNode('')
-        branch.anchor = anchorNode
-        parent.insertBefore(anchorNode, after)
-        /* The boundary's server nodes are gone, so the pending branch builds FRESH — clear
-           the claim cursor (see withoutHydration) so its `cloneStatic`/text don't try to
-           claim discarded nodes and silently render nothing. */
-        withoutHydration(() => render(result))
+        /* Genuinely pending — no resume, not warm: the boundary's server nodes can't be
+           adopted, so discard them and build the pending branch fresh from the already-read
+           promise (nothing was placed yet; the detach inside is a no-op). */
+        rebuildCold(open, () => result)
     }
 
     effect(() => {
@@ -296,9 +289,7 @@ export function awaitBlock(
                 firstHydrate()
                 return
             }
-            const anchorNode = document.createTextNode('')
-            branch.anchor = anchorNode
-            parent.insertBefore(anchorNode, before)
+            branch.parkAnchor(before)
         }
         /* Read the promise every subsequent run so an invalidate re-runs the block. ONLY this
            read is tracked (the branch builds untracked via `scope`), so the block re-runs only
@@ -321,8 +312,3 @@ export function awaitBlock(
         render(result)
     })
 }
-
-/* Whether a value is Promise-like (the cold path); a non-thenable is warm-sync. */
-function isThenable(value: unknown): value is Promise<unknown> {
-    return value !== null && typeof (value as { then?: unknown })?.then === 'function'
-}

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

@@ -0,0 +1,118 @@
+import { isAsyncCell } from '../../shared/isAsyncCell.ts'
+import type { AsyncComputed } from '../../shared/types/AsyncComputed.ts'
+import { createEffectNode } from '../runtime/createEffectNode.ts'
+import { SuspenseSignal } from '../runtime/SuspenseSignal.ts'
+import { readCell } from './readCell.ts'
+
+/*
+The subject of an `{#await X}` block, normalised so the block AWAITS an async cell's
+resolution instead of peeking its `undefined`-while-pending value (ADR-0047). `{#await}`
+means "wait", so when its subject is a `computed`/`linked` async cell the block should show
+its pending branch until the cell settles, then `{:then}` with the resolved value — but a
+cell reference otherwise lowers to `$$readCell(cell)`, a PEEK, which reads `undefined` while
+pending and fires `{:then}` with `undefined` (the `{#if}`/`{#switch}` cell subjects avoid this
+with a `cellPending` guard; `{#await}` had no equivalent).
+
+The compiler wraps ONLY a bare cell-reference subject in this (a plain-promise subject like
+`{#await getFoo()}` bypasses it), so `subject` is always some cell the `cellReadNames` set
+named — of two runtime shapes:
+
+  - **an async cell** (`AsyncComputed`/`AsyncState` — a `computed`/`linked` whose seed unwraps a
+    promise/stream). Pending (in flight, no value) → a PROMISE resolving to the cell's value once
+    it settles (rejecting with its error); the `pending()` read subscribes the reading block, so a
+    client reseed/`cache.invalidate` re-runs it and the SSR `renderToStream` awaits the returned
+    promise. Settled (a value, or a held value being refreshed — SWR) → the value now, so `{:then}`
+    shows it with no pending flash; an error with no retained value throws (→ `{:catch}`/`{#try}`).
+  - **a lazy `Computed`/`State`/derive** holding a bare promise (`computed(getFoo())` with no
+    `await` stays an opaque promise-holder, not an async cell) → read through `readCell` to its
+    `.value`, i.e. the promise itself, which `awaitBlock`/`renderToStream` then awaits — exactly the
+    pre-existing `{#await computedPromise}` behaviour, preserved.
+*/
+// @documentation plumbing
+export function awaitSubject(subject: unknown): unknown {
+    if (!isAsyncCell(subject)) {
+        /* A lazy `Computed`/`State`/derive reference: unwrap to its `.value` (the held promise or
+           value), which the await block awaits — never peeked to `undefined`. */
+        return readCell(subject)
+    }
+    const cell = subject as AsyncComputed<unknown> & {
+        settled?: () => Promise<unknown> | undefined
+    }
+    /* `pending()` — in flight AND no value — is the only state that WAITS; a settled or
+       refreshing cell reads its retained value now (SWR). The read subscribes the caller. */
+    if (cell.pending()) {
+        const inFlight = cell.settled?.()
+        if (inFlight !== undefined) {
+            /* Await the in-flight settle, then read the freshly-stored value (a `settled` cell
+               writes its value before this `.then` runs — it registered its handler first); an
+               error there rejects this promise → `{:catch}`. EXCEPT a `SuspenseSignal`
+               rejection, which is a PAUSE, not a failure (an async seed's sync prefix read a
+               pending blocking dep — the cell swallows it and stays pending, reseeding once the
+               dep settles); rejecting would render `{:catch SuspenseSignal}`, so keep waiting
+               for the real settle instead. */
+            return inFlight.then(
+                () => settledValue(cell),
+                (error) => {
+                    if (error instanceof SuspenseSignal) {
+                        return whenSettled(cell)
+                    }
+                    throw error
+                },
+            )
+        }
+        /* Pending with NO in-flight promise — a stream before its first frame, or a
+           `SuspenseSignal`-paused seed (both leave `pending()` true with `settled()` cleared).
+           Resolving now would read `undefined` into `{:then}` — the exact flash ADR-0047 kills;
+           wait for the cell to actually settle. */
+        return whenSettled(cell)
+    }
+    /* Settled: an error with no retained value becomes a REJECTED promise (never a synchronous
+       throw), so `awaitBlock`/`renderToStream` route it to `{:catch}` rather than letting it
+       escape the block; otherwise the retained value now. `settledValue` is the ONE statement
+       of the value-else-error rule for both the settled and the just-settled arms. */
+    try {
+        return settledValue(cell)
+    } catch (error) {
+        return Promise.reject(error)
+    }
+}
+
+/* The value of an in-flight cell once it settles: its retained value, or a throw when it holds
+   only an error — the throw rejects the awaiting promise, routing to `{:catch}`/`{#try}`. */
+function settledValue(cell: AsyncComputed<unknown>): unknown {
+    const value = cell.peek()
+    if (value === undefined) {
+        const error = cell.error()
+        if (error !== undefined) {
+            throw error
+        }
+    }
+    return value
+}
+
+/* A promise for the cell's NEXT settle, driven by the graph: an effect watches `pending()` and
+   resolves with the settled value (or rejects with its error) the moment it flips false — the
+   waiter for the states that hold no in-flight promise to chain on. The write that settles the
+   cell flushes effects synchronously (client and SSR alike), so this needs no polling; the
+   effect disposes itself on a microtask once done. */
+function whenSettled(cell: AsyncComputed<unknown>): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+        let done = false
+        let dispose: (() => void) | undefined
+        const settle = (): void => {
+            if (done || cell.pending()) {
+                return
+            }
+            done = true
+            try {
+                resolve(settledValue(cell))
+            } catch (error) {
+                reject(error)
+            }
+            /* Deferred: disposing mid-run would unlink the node while `runNode` is still
+               tracking it. */
+            queueMicrotask(() => dispose?.())
+        }
+        dispose = createEffectNode(settle)
+    })
+}

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

@@ -0,0 +1,38 @@
+import { claimChild } from '../runtime/claimChild.ts'
+import { parkCursor } from '../runtime/parkCursor.ts'
+import type { HydrationCursor } from '../runtime/types/HydrationCursor.ts'
+import { assertClaimedText } from './assertClaimedText.ts'
+
+/*
+Claims one text consumer's portion of the merged SSR text node at the parent's cursor:
+assert the node begins with `value` (or the split below misaligns and orphans the tail),
+split the node at the value's length so the remainder stays claimable, and advance past
+the claimed portion. `splitAlways` splits even on an exact-length consume — a non-final
+consumer in a run must leave a node behind for its sibling (an interpolation rendering
+empty otherwise has no node and the next claim grabs the wrong sibling); the final
+consumer keeps the cheaper split-only-when-shorter path.
+
+Returns undefined WITHOUT moving the cursor when the cursor doesn't hold a text node —
+a value that rendered empty on the server emitted no text node, so the cursor sits on
+the following element/comment or past the end. The caller owns that miss policy (bind a
+synthesized node, or skip); a text node is detected by `splitText`, not `nodeType`, so
+the test mini-dom is covered too.
+*/
+export function claimText(
+    hydration: HydrationCursor,
+    parent: Node,
+    value: string,
+    splitAlways: boolean,
+): Text | undefined {
+    const claimed = claimChild(hydration, parent)
+    if (claimed === null || typeof (claimed as Text).splitText !== 'function') {
+        return undefined
+    }
+    const node = claimed as Text
+    assertClaimedText(node, value)
+    if (splitAlways ? value.length <= node.data.length : value.length < node.data.length) {
+        node.splitText(value.length)
+    }
+    parkCursor(hydration, parent, node.nextSibling)
+    return node
+}

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

@@ -1,4 +1,4 @@
-import { claimChild } from '../runtime/claimChild.ts'
+import { claimRun } from '../runtime/claimRun.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { foreignWrapperTag } from './foreignWrapperTag.ts'
 import { templateFor } from './templateFor.ts'
@@ -29,13 +29,7 @@ export function cloneStatic(parent: Node, html: string): void {
     const source = wrapper === undefined ? template.content : (template.content.firstChild as Node)
     const hydration = RENDER.hydration
     if (hydration !== undefined) {
-        let node = claimChild(hydration, parent)
-        let remaining = source.childNodes.length
-        while (remaining > 0 && node !== null) {
-            node = node.nextSibling
-            remaining -= 1
-        }
-        hydration.next.set(parent, node)
+        claimRun(hydration, parent, source.childNodes.length)
         return
     }
     for (const child of source.childNodes) {

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

@@ -0,0 +1,23 @@
+import type { HydrationCursor } from '../runtime/types/HydrationCursor.ts'
+import { withoutHydration } from '../runtime/withoutHydration.ts'
+import { discardBoundary } from './discardBoundary.ts'
+
+/*
+The shared divergence-recovery mechanics of every named-boundary block: remove the SSR
+boundary (open marker through `closeData`, parking the cursor after it) and run a FRESH
+build at the freed position with the claim cursor cleared — so the build's helpers create
+nodes instead of claiming the discarded ones. `build` receives the node after the removed
+boundary (its insertion reference; null = parent's end). Each block keeps its own POLICY —
+when to give up on adoption (a resume value that didn't round-trip, a rejected guarded
+build, a boundary whose streamed fragment never arrived) — and delegates the dance here.
+*/
+export function discardAndRebuild<T>(
+    hydration: HydrationCursor,
+    parent: Node,
+    open: Node | null,
+    closeData: string,
+    build: (after: Node | null) => T,
+): T {
+    const after = discardBoundary(parent, open, closeData, hydration)
+    return withoutHydration(() => build(after))
+}

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

@@ -1,4 +1,5 @@
-import type { RENDER } from '../runtime/RENDER.ts'
+import { parkCursor } from '../runtime/parkCursor.ts'
+import type { HydrationCursor } from '../runtime/types/HydrationCursor.ts'
 
 /* Remove an SSR boundary — open marker through close marker (inclusive) — and park
    the hydration cursor on the node after it, returning that node. A fresh run then
@@ -8,11 +9,11 @@ export function discardBoundary(
     parent: Node,
     open: Node | null,
     closeData: string,
-    hydration: NonNullable<(typeof RENDER)['hydration']>,
+    hydration: HydrationCursor,
 ): Node | null {
     /* Nothing to discard (no open marker) — park the cursor and return, as before. */
     if (open === null) {
-        hydration.next.set(parent, null)
+        parkCursor(hydration, parent, null)
         return null
     }
     /* Locate the close marker WITHOUT mutating first. Removing as we walk would, on a
@@ -40,6 +41,6 @@ export function discardBoundary(
         }
         node = next
     }
-    hydration.next.set(parent, after)
+    parkCursor(hydration, parent, after)
     return after
 }

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

@@ -1,7 +1,7 @@
 import { effect } from '../effect.ts'
 import { CURRENT_PATH } from '../runtime/CURRENT_PATH.ts'
 import { claimChild } from '../runtime/claimChild.ts'
-import { claimExpected } from '../runtime/claimExpected.ts'
+import { claimMarker } from '../runtime/claimMarker.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
 import { scopeGroup } from '../runtime/scopeGroup.ts'
@@ -82,8 +82,7 @@ export function each<T>(
         const segment = keyed ? keyOf(item) : position
         const hydration = RENDER.hydration
         if (hydration !== undefined) {
-            const start = claimExpected(hydration, parent, 'each row start marker')
-            hydration.next.set(parent, start.nextSibling)
+            const start = claimMarker(hydration, parent, 'each row start marker')
             const dispose = group.track(
                 scope(() =>
                     withPathFrom(basePath, segment, () =>
@@ -91,8 +90,7 @@ export function each<T>(
                     ),
                 ),
             )
-            const end = claimExpected(hydration, parent, 'each row end marker')
-            hydration.next.set(parent, end.nextSibling)
+            const end = claimMarker(hydration, parent, 'each row end marker')
             return { start, end, dispose, cell, indexCell }
         }
         /* Shared detached-range create primitive: a `[ … ]` fragment built under `parent`'s

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

@@ -1,3 +1,4 @@
+import { parkCursor } from '../runtime/parkCursor.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
 import type { UiProps } from '../runtime/types/UiProps.ts'
@@ -31,7 +32,7 @@ export function fillBoundary(
     }
     /* Hydrate: adopt the server content between the markers in place. */
     const parent = open.parentNode as Node
-    hydration.next.set(parent, open.nextSibling)
+    parkCursor(hydration, parent, open.nextSibling)
     const scoped = withScope(() => scope(() => build(parent, props)))
     return { dispose: disposeRange(scoped, open, close) }
 }

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

@@ -1,5 +1,4 @@
-import { hydrationWindow } from '../../shared/hydrationWindow.ts'
-import { RENDER } from '../runtime/RENDER.ts'
+import { runHydrationPass } from '../runtime/runHydrationPass.ts'
 import { scope } from '../runtime/scope.ts'
 import { withScope } from './withScope.ts'
 
@@ -24,18 +23,12 @@ export function hydrate(
     build: (host: Element, props: unknown) => void,
     props?: unknown,
 ): () => void {
-    const previous = RENDER.hydration
-    RENDER.hydration = { next: new Map() }
-    hydrationWindow.enter()
-    try {
+    /* The pass lifecycle (claim cursor, withhold window, render pass, restore-on-throw)
+       is owned by `runHydrationPass` — the same bracket the router's hydrating mount runs. */
+    return runHydrationPass(() => {
         /* Same shared mount core as `mount` (see `withScope`) — a hydrated component owns a
            scope too, adopting the model its build adopts — run with the claim cursor active. */
         const { lexical } = withScope(() => scope(() => build(host, props)))
         return () => lexical.dispose()
-    } finally {
-        RENDER.hydration = previous
-        /* Outermost exit clears the window and wakes the peeks this pass withheld; a nested
-           child hydrate raises/lowers the depth without firing it early. */
-        hydrationWindow.exit()
-    }
+    })
 }

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

@@ -1,13 +1,37 @@
+import { CURRENT_PATH } from '../runtime/CURRENT_PATH.ts'
+import { claimChild } from '../runtime/claimChild.ts'
 import { OWNER } from '../runtime/OWNER.ts'
+import { RANGE_OPEN } from '../runtime/RANGE_MARKER.ts'
+import { RENDER } from '../runtime/RENDER.ts'
 import type { UiComponent } from '../runtime/types/UiComponent.ts'
 import { withOptionalPath } from '../runtime/withOptionalPath.ts'
+import { commentData } from './commentData.ts'
+import { discardAndRebuild } from './discardAndRebuild.ts'
 import { mountRange } from './mountRange.ts'
+import { openMarker } from './openMarker.ts'
 
 /*
-Mounts a child component as a marker-bounded range at `before` in `parent` — no
-wrapper element, so the child's root is a true direct child of the parent (see
-`mountRange`). Files the range's dispose with the mounting owner so its scope and DOM
-leave together when the parent (or branch/row) tears down.
+The client mount for a child component — a DUAL-MODE adopter, and the ONLY child mount the
+compiler emits. A child mounts as a marker-bounded range at `before` in `parent` (no wrapper
+element, so the child's root is a true direct child — see `mountRange`), its dispose filed
+with the mounting owner so scope and DOM leave together on teardown.
+
+The server decides per render whether a HOISTABLE child (ADR-0039) inlined (fast/settled) or
+streamed (still-pending), and the client build can't know which — nor whether this child was
+hoistable at all — so hydrate mode probes the cursor:
+
+  - `<!--[-->` (RANGE_OPEN) next → the server INLINED the child (every non-hoistable child,
+    and a hoistable one whose flight settled); adopt its range in place.
+  - `<!--abide:await:CHILDPATH-->` next → the server STREAMED it; `__abideSwap` has already
+    spliced the child's `<!--[-->…<!--]-->` between the boundary markers before the bundle
+    ran, so claim the boundary open, adopt the inner range in place, claim the boundary close.
+  - no hydration (a client-side navigation) → a plain create-mode mount.
+
+CHILDPATH is the child's render-path — `withPath(ordinal, () => CURRENT_PATH.current)` —
+computed the same way the server's `renderPath(ordinal)` wrote the boundary id, so the two
+agree with no counter. A streamed child re-mounts (no RESUME value of its own — the boundary
+is html-only); nested `{#await}` blocks and async cells inside it adopt through their own
+existing channels.
 */
 // @documentation plumbing
 export function mountChild(
@@ -21,6 +45,50 @@ export function mountChild(
        row key the each block already pushed). Absent (a non-compiled caller) → no path segment. */
     ordinal?: number,
 ): void {
-    const handle = withOptionalPath(ordinal, () => mountRange(parent, factory.build, props, before))
+    const run = <T>(build: () => T): T => withOptionalPath(ordinal, build)
+    const mount = (): { dispose: () => void } =>
+        run(() => mountRange(parent, factory.build, props, before))
+
+    const hydration = RENDER.hydration
+    if (hydration === undefined) {
+        /* Call mount() first, THEN register its dispose — `OWNER.current?.push(mount())` would
+           short-circuit the whole expression (never mounting) when there is no owner. */
+        const handle = mount()
+        OWNER.current?.push(handle.dispose)
+        return
+    }
+
+    /* Probe the cursor without consuming it. Streamed iff the next node is this child's boundary. */
+    const childPath = run(() => CURRENT_PATH.current)
+    const cursor = claimChild(hydration, parent)
+    const streamed = cursor !== null && commentData(cursor) === `abide:await:${childPath}`
+
+    if (!streamed) {
+        /* INLINE — the server inlined the child's `[ … ]` range; adopt it in place. */
+        const handle = mount()
+        OWNER.current?.push(handle.dispose)
+        return
+    }
+
+    /* STREAMED — claim the boundary open (advances the cursor to the swapped-in `[`). */
+    const open = openMarker(parent, `abide:await:${childPath}`)
+    const inner = claimChild(hydration, parent)
+    const warm = inner !== null && commentData(inner) === RANGE_OPEN
+    if (warm) {
+        const handle = mount()
+        openMarker(parent, `/abide:await:${childPath}`)
+        OWNER.current?.push(handle.dispose)
+        return
+    }
+    /* COLD (defensive — renderToStream drains every await before closing, so a warm boundary is the
+       deterministic path). The fragment never arrived: discard the empty boundary and create-mount
+       the child fresh at that position; its streamed cells resolve post-mount via receiveStreamedCell. */
+    const handle = discardAndRebuild(
+        hydration,
+        parent,
+        open,
+        `/abide:await:${childPath}`,
+        (after) => run(() => mountRange(parent, factory.build, props, after)),
+    )
     OWNER.current?.push(handle.dispose)
 }