@abide/abide 0.53.0 → 0.55.0

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

@@ -2,10 +2,11 @@ import { rawHtmlString } from '../../shared/html.ts'
 import { snippetPayload } from '../../shared/snippet.ts'
 import { effect } from '../effect.ts'
 import { claimChild } from '../runtime/claimChild.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 { assertClaimedText } from './assertClaimedText.ts'
+import { claimText } from './claimText.ts'
 import { isComment } from './isComment.ts'
 import { parseRawNodes } from './parseRawNodes.ts'
 import { readTextOrSuspend } from './readTextOrSuspend.ts'
@@ -34,7 +35,15 @@ cold client render (on hydrate the warm-seed makes the cell `refreshing()`, not
 decided from the first resolved value.
 */
 // @documentation plumbing
-export function appendText(parent: Node, read: () => unknown, splitAlways = false): void {
+export function appendText(
+    parent: Node,
+    read: () => unknown,
+    splitAlways = false,
+    /* Create-mode insertion reference: content lands before this node instead of at the end of
+       `parent` (`null` appends). Lets `appendTextAt` mount at a skeleton anchor through this one
+       create path. Ignored on hydrate, where the cursor decides position. */
+    before: Node | null = null,
+): void {
     /* Probe the first value once, tolerating a suspend (a pending blocking read) — a suspended
        interpolation skips snippet/html detection and takes the text path, starting empty. */
     let probe: unknown
@@ -50,62 +59,51 @@ export function appendText(parent: Node, read: () => unknown, splitAlways = fals
     /* A snippet call (`{row(args)}`) mounts its builder; a `html\`\`` value inserts
        raw markup; everything else is escaped text — decided by the first value. */
     if (!suspended && typeof snippetPayload(probe) === 'function') {
-        appendSnippet(parent, read)
+        if (before === null) {
+            appendSnippet(parent, read)
+            return
+        }
+        /* Positioned mount: buffer the snippet in a fragment, then splice it in at `before` —
+           `appendSnippet` itself only appends, and its markers track position from then on. */
+        const fragment = document.createDocumentFragment()
+        appendSnippet(fragment, read)
+        parent.insertBefore(fragment, before)
         return
     }
     if (!suspended && rawHtmlString(probe) !== undefined) {
-        appendRawHtml(parent, read)
+        appendRawHtml(parent, read, before)
         return
     }
     const hydration = RENDER.hydration
     if (hydration !== undefined) {
-        const claimed = claimChild(hydration, parent)
         /* Nullish reads render as empty text, never the literal `"undefined"` — so a
            pending async read (undefined-while-pending, ADR-0032 D3) shows nothing. A blocking
            read never suspends here (warm-seeded → `refreshing()`), so `probe` holds its value. */
         const firstValue = probe
         const value = firstValue == null ? '' : String(firstValue)
-        /* A value that first rendered empty produced NO server text node, so the cursor
-           points at the following node (an element/comment) or past the end (null) — not a
-           text node to claim. Bind to a Text node either way: claim the merged SSR node when
-           one is here, else synthesize an empty one at the cursor and leave the claimed node
-           for the next consumer (a following element hole, a sibling binding, or nothing).
-           Without this the bind effect below derefs a null/element `node`. A text node is
-           detected by `splitText` (not `nodeType`), so the test mini-dom is covered too. */
-        const isText = claimed !== null && typeof (claimed as Text).splitText === 'function'
-        const node = (
-            isText ? claimed : parent.insertBefore(document.createTextNode(''), claimed)
-        ) as Text
-        /* The claimed SSR node must begin with this binding's value, or the split below
-           lands mid-run and orphans the tail — throw legibly at the divergence instead. A
-           synthesized empty node is this binding's own, so there's nothing to disagree. */
-        if (isText) {
-            assertClaimedText(node, value)
-        }
-        /* Peel this binding's text off the merged SSR node. A non-final binding in a
-           run (`splitAlways`) splits even when it consumes the whole node, leaving an
-           empty node for the next binding — otherwise an interpolation that renders to
-           empty string (or whose followers do) has no node and the next claim grabs the
-           wrong sibling. The final binding keeps `<` so it doesn't leave a stray node a
-           following element would claim. A synthesized node is already this binding's own,
-           so it never splits. */
-        if (
-            isText &&
-            (splitAlways ? value.length <= node.data.length : value.length < node.data.length)
-        ) {
-            node.splitText(value.length)
+        /* Claim this binding's portion of the merged SSR text node (assert + split +
+           advance — see `claimText`). A value that first rendered empty produced NO server
+           text node, so the cursor points at the following node (an element/comment) or past
+           the end — the miss arm: bind a synthesized empty Text at the cursor and leave the
+           unclaimed node for the next consumer (a following element hole, a sibling binding,
+           or nothing). Without it the bind effect below derefs a null/element node. */
+        let node = claimText(hydration, parent, value, splitAlways)
+        if (node === undefined) {
+            const unclaimed = claimChild(hydration, parent)
+            node = parent.insertBefore(document.createTextNode(''), unclaimed)
+            /* Pin the cursor on the still-unclaimed node — the synthesized node is this
+               binding's own, and an unset cursor would default back to the (now synthesized)
+               first child. */
+            parkCursor(hydration, parent, unclaimed)
         }
-        /* Advance past the claimed text node; for a synthesized node leave the cursor on the
-           still-unclaimed `claimed` node it was inserted before (an element/comment, or null
-           at the end). */
-        hydration.next.set(parent, isText ? node.nextSibling : claimed)
+        const bound = node
         effect(() => {
-            node.data = readTextOrSuspend(read)
+            bound.data = readTextOrSuspend(read)
         })
         return
     }
     const node = document.createTextNode('')
-    parent.appendChild(node)
+    parent.insertBefore(node, before)
     effect(() => {
         node.data = readTextOrSuspend(read)
     })
@@ -113,7 +111,7 @@ export function appendText(parent: Node, read: () => unknown, splitAlways = fals
 
 /* Raw-markup interpolation: parse the branded string into nodes behind an anchor,
    re-parsing on change; on hydrate adopt the server markup between its markers. */
-function appendRawHtml(parent: Node, read: () => unknown): void {
+function appendRawHtml(parent: Node, read: () => unknown, before: Node | null): void {
     const hydration = RENDER.hydration
     const markup = (): string => rawHtmlString(read()) ?? ''
     const anchor = document.createTextNode('')
@@ -141,7 +139,7 @@ function appendRawHtml(parent: Node, read: () => unknown): void {
             nodes.push(node)
             node = node.nextSibling
         }
-        hydration.next.set(parent, node === null ? null : node.nextSibling)
+        parkCursor(hydration, parent, node === null ? null : node.nextSibling)
         parent.insertBefore(anchor, node)
         let first = true
         effect(() => {
@@ -155,7 +153,7 @@ function appendRawHtml(parent: Node, read: () => unknown): void {
         return
     }
 
-    parent.appendChild(anchor)
+    parent.insertBefore(anchor, before)
     effect(() => {
         set(markup())
     })

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,19 +1,19 @@
 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'
 import type { ResumeEntry } from '../runtime/RESUME.ts'
 import { RESUME } from '../runtime/RESUME.ts'
-import { scopeGroup } from '../runtime/scopeGroup.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
 }