@abide/abide 0.54.0 → 0.55.0

package/src/lib/ui/compile/lowerContext.ts

@@ -6,6 +6,7 @@ import { signalRefsTransformer } from './renameSignalRefs.ts'
 import { TS_PRINTER } from './TS_PRINTER.ts'
 import type { TemplateNode } from './types/TemplateNode.ts'
 import { unwrapParens } from './unwrapParens.ts'
+import { wrapReactiveSeedsTransformer } from './wrapReactiveSeeds.ts'
 
 /* Compiled once — strips the trailing `;` off every lowered expression. */
 const TRAILING_SEMICOLON = /;$/
@@ -25,11 +26,10 @@ export function lowerContext(
     stateNames: ReadonlySet<string>,
     derivedNames: ReadonlySet<string>,
     computedNames: ReadonlySet<string> = new Set(),
-    /* `linked` / async `computed` names, read through `$$readCell(name)`. */
+    /* `linked` / async `computed` names, read through `$$readCell(name)` — one read form
+       whose pause-vs-peek is decided at runtime by the cell's own `blocking` bit (ADR-0042),
+       so both back-ends lower a cell read identically with nothing site-specific to thread. */
     cellReadNames: ReadonlySet<string> = new Set(),
-    /* The subset that are BLOCKING `await` cells (ADR-0042), read through `$$readCellBlocking(name)`
-       (suspend-on-pending). Passed only by the CLIENT back-end; SSR leaves it empty. */
-    blockingCellNames: ReadonlySet<string> = new Set(),
 ) {
     /* The typed branch-local shadow stack: one auto-popping value owning both kinds.
        `derived` names deref to `.value` like a `computed` (block value params the client
@@ -44,9 +44,13 @@ export function lowerContext(
        one tree — the two string passes would each parse + reprint. `localDerived` is
        snapshotted per call (as the transformer's block-local shadow set) so a binding
        pushed mid-compile is honoured AND shadows a same-named component signal. */
-    function lowerOnce(code: string): string {
+    function lowerOnce(
+        code: string,
+        leadingTransformers: ts.TransformerFactory<ts.SourceFile>[] = [],
+    ): string {
         const source = ts.createSourceFile('expr.ts', code, ts.ScriptTarget.Latest, true)
         const result = ts.transform(source, [
+            ...leadingTransformers,
             signalRefsTransformer(
                 stateNames,
                 derivedNames,
@@ -54,7 +58,6 @@ export function lowerContext(
                 new Set(scope.names('derived')),
                 new Set(scope.names('plain')),
                 cellReadNames,
-                blockingCellNames,
             ),
             docAccessTransformer('$$model'),
         ])
@@ -75,6 +78,16 @@ export function lowerContext(
         return lowerOnce(code)
     }
 
+    /* A nested branch `<script>` body. Same lowering as `statement`, but first normalises its
+       literal `state.computed`/`state.linked` seeds into thunks (`wrapReactiveSeeds`) so a bare-
+       value seed (`state.computed(a * 2)`) matches the top-level desugar rather than reaching the
+       runtime primitive un-thunked (which would call the value as the compute function and crash).
+       The wrap runs BEFORE the reference rename so it wraps the raw seed and the renamed refs land
+       inside the thunk. */
+    function script(code: string): string {
+        return lowerOnce(code, [wrapReactiveSeedsTransformer()])
+    }
+
     /* A two-way bind target is either an LVALUE (`count`, `model.lines[i]`) — reads as
        itself, writes by assignment — or an ACCESSOR object from `bind:value={{ get, set }}`
        — reads via `.get()`, writes via `.set(v)`. The accessor is the only way to bind a
@@ -136,11 +149,18 @@ export function lowerContext(
     return {
         expression,
         statement,
+        script,
         withNestedScripts,
         /* The raw branch-local shadow registration both back-ends drive `withBindings`
            through: a block's bindings flow to a `ShadowKind` only via that one shared loop,
            never through a per-block `scope.withShadow` call here. */
         withShadow: scope.withShadow,
+        /* Whether `name` is currently shadowed by a block binding (either kind) at this point
+           of the walk — the live query classification sites (e.g. `awaitSubjectExpr`) consult
+           so a binder that shadows a component cell name is lowered as the local it is, never
+           wrapped as the cell it hides. */
+        isShadowed: (name: string): boolean =>
+            scope.names('plain').has(name) || scope.names('derived').has(name),
         bindRead,
         bindWrite,
     }

package/src/lib/ui/compile/lowerScript.ts

@@ -91,19 +91,10 @@ export function lowerScript(
     derivedNames: Set<string>
     computedNames: Set<string>
     cellReadNames: Set<string>
-    /* Template-injected + script-level `await` cells (ADR-0042), read via `$$readCellBlocking`. */
-    blockingCellNames: Set<string>
     droppedReactiveImports: Set<string>
 } {
     const source = ts.createSourceFile('component.ts', scriptBody, ts.ScriptTarget.Latest, true)
-    const {
-        transformer,
-        stateNames,
-        derivedNames,
-        computedNames,
-        cellReadNames,
-        blockingCellNames: allBlockingNames,
-    } = desugarSignals(
+    const { transformer, stateNames, derivedNames, computedNames, cellReadNames } = desugarSignals(
         source,
         injectedCellNames,
         blockingCellNames,
@@ -194,7 +185,6 @@ export function lowerScript(
         derivedNames,
         computedNames,
         cellReadNames,
-        blockingCellNames: allBlockingNames,
         droppedReactiveImports,
     }
 }

package/src/lib/ui/compile/renameSignalRefs.ts

@@ -54,12 +54,10 @@ export function signalRefsTransformer(
     blockLocalPlain: ReadonlySet<string> = new Set(),
     /* Component signals read through `$$readCell(name)` — every `linked` and every async
        `computed` (see `desugarSignals`). A nearer lexical binding of the same name shadows
-       them like any other signal. */
+       them like any other signal. Whether a read PAUSES (blocking `await` cell) or peeks
+       (streaming) is decided at runtime by the cell itself (`readCell` consults `cell.blocking`),
+       so there is one read form here for every cell and nothing site-specific to thread. */
     cellReadNames: ReadonlySet<string> = new Set(),
-    /* The subset of `cellReadNames` that are BLOCKING `await` cells (ADR-0042), read through
-       `$$readCellBlocking(name)` (suspend-on-pending) instead of `$$readCell`. Non-empty only on
-       the CLIENT template lowering; the script pass and SSR keep it empty (`$$readCell`). */
-    blockingCellNames: ReadonlySet<string> = new Set(),
 ): ts.TransformerFactory<ts.SourceFile> {
     /* The signal names that a nested binding can shadow — only these matter for
        scope tracking, so we ignore every other local binding. */
@@ -160,7 +158,6 @@ export function signalRefsTransformer(
                         computedNames,
                         blockLocal,
                         cellReadNames,
-                        blockingCellNames,
                     )
                     if (replacement !== undefined) {
                         return ts.factory.createPropertyAssignment(node.name.text, replacement)
@@ -174,7 +171,6 @@ export function signalRefsTransformer(
                         computedNames,
                         blockLocal,
                         cellReadNames,
-                        blockingCellNames,
                     )
                     if (replacement !== undefined) {
                         return replacement
@@ -393,7 +389,6 @@ function referenceFor(
     computedNames: ReadonlySet<string>,
     blockLocal: ReadonlySet<string> = new Set(),
     cellReadNames: ReadonlySet<string> = new Set(),
-    blockingCellNames: ReadonlySet<string> = new Set(),
 ): ts.Expression | undefined {
     if (blockLocal.has(name)) {
         return ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier(name), 'value')
@@ -403,19 +398,10 @@ function referenceFor(
     if (name === 'scope') {
         return ts.factory.createIdentifier('$$scope')
     }
-    /* A BLOCKING `await` cell → `$$readCellBlocking(name)` (ADR-0042): the throwing peek that
-       SUSPENDS the render region while pending, so an `await` binding reads as a resolved value
-       and its region withholds until it settles. Client template lowering only — `blockingCellNames`
-       is empty in the script pass and SSR, which keep the plain `$$readCell` peek below. */
-    if (blockingCellNames.has(name)) {
-        return ts.factory.createCallExpression(
-            ts.factory.createIdentifier('$$readCellBlocking'),
-            undefined,
-            [ts.factory.createIdentifier(name)],
-        )
-    }
-    /* A `linked` / async `computed` cell → `$$readCell(name)`: one read shape that peeks an
-       async cell and reads `.value` off a sync one. */
+    /* A `linked` / async `computed` cell → `$$readCell(name)`: ONE read shape for every cell,
+       script and template. It peeks a sync cell's `.value`, and for an async cell decides at
+       runtime whether to pause (blocking `await`) or peek `undefined` (streaming) by the cell's
+       own `blocking` bit — so no blocking/streaming distinction is threaded through codegen. */
     if (cellReadNames.has(name)) {
         return ts.factory.createCallExpression(
             ts.factory.createIdentifier('$$readCell'),

package/src/lib/ui/compile/seedTypeClassifierForRoot.ts

@@ -41,9 +41,9 @@ export function seedTypeClassifierForRoot(
         return undefined
     }
     const checker = program.getTypeChecker()
+    const mappings = shadows.get(abidePath)?.mappings ?? []
     return (loc, code) => {
         try {
-            const mappings = shadows.get(abidePath)?.mappings ?? []
             const offset = sourceToShadowOffset(mappings, loc)
             if (offset === undefined) {
                 return undefined

package/src/lib/ui/compile/shadowInterpolationClassifier.ts

@@ -28,9 +28,9 @@ export function shadowInterpolationClassifier(
         return undefined
     }
     const checker = program.getTypeChecker()
+    const mappings = shadows.get(abidePath)?.mappings ?? []
     return (loc, code) => {
         try {
-            const mappings = shadows.get(abidePath)?.mappings ?? []
             const offset = sourceToShadowOffset(mappings, loc)
             if (offset === undefined) {
                 return 'sync'

package/src/lib/ui/compile/types/AnalyzedComponent.ts

@@ -26,12 +26,10 @@ export type AnalyzedComponent = {
     computedNames: Set<string>
     /* Component signals read through `$$readCell(name)`: every `linked` and every async
        `computed`. Threaded to both back-ends so a template reference (`{draft}`) lowers to
-       the unified cell read consistently on client and server. */
+       the unified cell read consistently on client and server. Whether a pending read pauses
+       (blocking `await`) or peeks (streaming) is decided at runtime by the cell's own
+       `blocking` bit (ADR-0042), so no blocking subset is threaded through codegen. */
     cellReadNames: Set<string>
-    /* The subset of `cellReadNames` that are BLOCKING `await` cells (ADR-0042): a template-injected
-       `{await X}` cell or a script `computed(await …)`. The CLIENT back-end reads these via
-       `$$readCellBlocking` (suspend-on-pending) rather than `$$readCell`. */
-    blockingCellNames: Set<string>
     nodes: TemplateNode[]
     /* One entry per non-empty `<style>` in the template (in source order): the scope
        attribute its covered elements carry (annotated onto `nodes`) and the scoped

package/src/lib/ui/compile/wrapReactiveSeeds.ts

@@ -0,0 +1,44 @@
+import ts from 'typescript'
+import { NESTED_REACTIVE_BINDINGS, resolveReactiveExport } from './resolveReactiveExport.ts'
+import { wrapSeed } from './wrapSeed.ts'
+
+/*
+Normalises every `state.computed(seed)` / `state.linked(seed)` in a nested branch
+`<script>` so a BARE-VALUE seed becomes a thunk (`state.computed(a * 2)` →
+`state.computed(() => a * 2)`), exactly as the top-level desugar (`desugarSignals` via
+`wrapSeed`) does. A nested script keeps its reactive calls literal — it is not desugared to
+the doc — so absent this the bare value reaches the runtime primitive, which stores it as
+the compute function and calls it on read (`a * 2 is not a function`, a runtime crash). A
+literal `() => …` / `function` thunk passes through unchanged, so the wrap is a no-op on the
+already-thunked form the author usually writes.
+
+Recognition is name-based (`NESTED_REACTIVE_BINDINGS`) because a nested script carries no
+import of its own — it inherits the surface by the canonical `state` name, the same way
+`nestedBindingNames` resolves it. Only the seed argument (`arguments[0]`) is wrapped; a
+`state.linked(seed, ...)`'s trailing args pass through. Exposed as a `ts.TransformerFactory`
+so the nested-script lowering can chain it ahead of the reference rename over ONE parsed tree.
+*/
+export function wrapReactiveSeedsTransformer(): ts.TransformerFactory<ts.SourceFile> {
+    return (context) => (root) => {
+        const visit = (node: ts.Node): ts.Node => {
+            if (ts.isCallExpression(node) && node.arguments.length > 0) {
+                const primitive = resolveReactiveExport(node.expression, NESTED_REACTIVE_BINDINGS)
+                if (primitive === 'computed' || primitive === 'linked') {
+                    const seed = node.arguments[0] as ts.Expression
+                    const wrapped = wrapSeed(ts.visitNode(seed, visit) as ts.Expression)
+                    const rest = node.arguments
+                        .slice(1)
+                        .map((argument) => ts.visitNode(argument, visit) as ts.Expression)
+                    return ts.factory.updateCallExpression(
+                        node,
+                        node.expression,
+                        node.typeArguments,
+                        [wrapped, ...rest],
+                    )
+                }
+            }
+            return ts.visitEachChild(node, visit, context)
+        }
+        return ts.visitNode(root, visit) as ts.SourceFile
+    }
+}

package/src/lib/ui/compile/wrapSeed.ts

@@ -0,0 +1,28 @@
+import ts from 'typescript'
+import { hasTopLevelAwait } from './hasTopLevelAwait.ts'
+
+const factory = ts.factory
+
+/* Normalises a `computed`/`linked` argument into a seed THUNK: a literal `() => …` /
+   `function` argument passes through unchanged (the author already wrote the thunk), any
+   other expression is wrapped as `() => arg`. The wrapper arrow is made ASYNC when the
+   expression contains a top-level `await` (`computed(await load())` → `async () => await
+   load()`), which is exactly the marker the runtime primitive uses to route to an async cell.
+   Shared by the top-level desugar (`desugarSignals`) and the nested-`<script>` lowering
+   (`wrapReactiveSeeds`) so a bare-value seed is normalised identically on both surfaces. */
+export function wrapSeed(argument: ts.Expression): ts.Expression {
+    if (ts.isArrowFunction(argument) || ts.isFunctionExpression(argument)) {
+        return argument
+    }
+    const modifiers = hasTopLevelAwait(argument)
+        ? [factory.createModifier(ts.SyntaxKind.AsyncKeyword)]
+        : undefined
+    return factory.createArrowFunction(
+        modifiers,
+        undefined,
+        [],
+        undefined,
+        factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+        argument,
+    )
+}

package/src/lib/ui/computed.ts

@@ -5,6 +5,7 @@ import { createComputedNode } from './runtime/createComputedNode.ts'
 import { isAsyncFunction } from './runtime/isAsyncFunction.ts'
 import { OWNER } from './runtime/OWNER.ts'
 import { readNode } from './runtime/readNode.ts'
+import { routeBareSeed } from './runtime/routeBareSeed.ts'
 import type { Computed } from './runtime/types/Computed.ts'
 import { unlinkDeps } from './runtime/unlinkDeps.ts'
 
@@ -32,6 +33,21 @@ export function computed<T>(compute: () => T): Computed<T>
 export function computed<T>(
     compute: () => T | Promise<T> | NamedAsyncIterable<T>,
 ): Computed<T> | AsyncComputed<T> {
+    /* A BARE seed that reached the runtime literally — a branch-nested `<script>` (which
+       keeps its `state.computed(...)` calls literal; see lowerScript) or a direct JS caller.
+       The compile-time `wrapSeed` normalization only covers the leading script, so honor the
+       same authored contract (ADR-0045: a bare seed behaves like its thunk form) by VALUE via
+       the shared `routeBareSeed`; a non-async value becomes a constant computed over it.
+       Without this a raw value lands as `node.compute` and the first read calls it
+       (`node.compute is 3` — a dead render mid-stream). */
+    if (typeof compute !== 'function') {
+        const seed: unknown = compute
+        const cell = routeBareSeed(seed, false)
+        if (cell !== undefined) {
+            return cell as AsyncComputed<T>
+        }
+        compute = () => seed as T
+    }
     /* `await` marker: an async-function thunk unwraps its promise into a tracked async cell.
        This is the only classification the read-only primitive can make without running the
        seed — a sync `computed` MUST stay lazy (it does not compute until first read). A stream

package/src/lib/ui/createScope.ts

@@ -4,6 +4,7 @@ import { computed } from './computed.ts'
 import { effect } from './effect.ts'
 import { linked } from './linked.ts'
 import { CURRENT_PATH } from './runtime/CURRENT_PATH.ts'
+import { consumeSeed } from './runtime/consumeSeed.ts'
 import { createDoc } from './runtime/createDoc.ts'
 import { DOC_SEED } from './runtime/DOC_SEED.ts'
 import type { Cell } from './runtime/types/Cell.ts'
@@ -50,13 +51,13 @@ export function createScope(
        on the client, so a uuid/timestamp/random would diverge from the SSR HTML. The server snapshot
        for this scope's render-path id is decoded here and consumed by `replace` on each slot's FIRST
        write (the eager init), keeping the server value while the throwaway init is discarded. One-shot
-       — deleted on read so an SPA re-nav to the same path re-inits fresh; empty on the server. */
+       via `consumeSeed` (two-phase, ADR-0048) — an SPA re-nav to the same path re-inits fresh, and a
+       hydration-desync throw hands the seed to the cold rebuild; empty on the server. */
     let pendingSeed: Map<string, unknown> | undefined
     /* `DOC_SEED` is populated only on the client by `startClient` (empty on the server), so the read
        needs no window guard — it mirrors the async-cell warm read. */
-    const encodedSeed = DOC_SEED[id]
+    const encodedSeed = consumeSeed(DOC_SEED, id)
     if (encodedSeed !== undefined) {
-        delete DOC_SEED[id]
         try {
             pendingSeed = new Map(
                 Object.entries(decodeRefJson(encodedSeed) as Record<string, unknown>),

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

@@ -1,3 +1,4 @@
+import { parkCursor } from '../runtime/parkCursor.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 
 /*
@@ -18,7 +19,7 @@ export function anchorCursor(anchor: Node): Node | null {
     const reference = anchor.nextSibling
     const hydration = RENDER.hydration
     if (hydration !== undefined) {
-        hydration.next.set(anchor.parentNode as Node, reference)
+        parkCursor(hydration, anchor.parentNode as Node, reference)
     }
     return reference
 }

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

@@ -19,9 +19,10 @@ the accidental copy-paste, notably its two subtle guards:
      rethrowing, so the caller's cold rebuild starts clean).
 
 `anchor` is a mutable field: each block parks its own anchor text node at create /
-hydrate / rebuild time (placement is bespoke), and `place` reads it. The block owns its
-`scopeGroup`; each built branch's disposer is tracked in it so it disposes on owner
-teardown, not only on a swap.
+hydrate / rebuild time via `parkAnchor` (WHERE it parks is bespoke — before the boundary
+close, after a discarded boundary, at the create-mode `before`), and `place` reads it. The
+block owns its `scopeGroup`; each built branch's disposer is tracked in it so it disposes
+on owner teardown, not only on a swap.
 */
 export function anchoredBranch(
     parent: Node,
@@ -29,6 +30,7 @@ export function anchoredBranch(
 ): {
     anchor: Node | undefined
     detach: () => void
+    parkAnchor: (before: Node | null) => void
     place: (build: (host: Node) => void, wrapBuild?: (run: () => void) => void) => void
     adoptStrand: (
         build: (host: Node) => void,
@@ -128,6 +130,14 @@ export function anchoredBranch(
         }
     }
 
+    /* Park a fresh empty text node as the branch's swap anchor at `before` (null appends) —
+       the create/hydrate/rebuild triple every block repeated by hand. */
+    const parkAnchor = (before: Node | null): void => {
+        const node = document.createTextNode('')
+        anchor = node
+        parent.insertBefore(node, before)
+    }
+
     return {
         get anchor(): Node | undefined {
             return anchor
@@ -136,6 +146,7 @@ export function anchoredBranch(
             anchor = node
         },
         detach,
+        parkAnchor,
         place,
         adoptStrand,
     }

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

@@ -1,34 +1,25 @@
 import { claimChild } from '../runtime/claimChild.ts'
+import { parkCursor } from '../runtime/parkCursor.ts'
 import { RENDER } from '../runtime/RENDER.ts'
-import { assertClaimedText } from './assertClaimedText.ts'
+import { claimText } from './claimText.ts'
 
 /*
 A static (non-reactive) text node under `parent`: created and appended (create
-mode), or claimed from the server-rendered text (hydrate mode). As with reactive
-text, a merged SSR text node is split at this literal's length so the next claim
-lines up; nothing is bound since the text never changes.
+mode), or claimed from the server-rendered text (hydrate mode) — the shared
+`claimText` asserts, splits the merged SSR node at this literal's length so the
+next claim lines up, and advances. Nothing is bound since the text never changes.
+A static always renders on the server, so a non-text node at the cursor is a
+tolerated desync: advance past it (assertClaimedText's domain is a text mismatch;
+a structural one is claimExpected's).
 */
 // @documentation plumbing
 export function appendStatic(parent: Node, value: string, splitAlways = false): void {
     const hydration = RENDER.hydration
     if (hydration !== undefined) {
-        const node = claimChild(hydration, parent) as unknown as Text
-        const isText = node !== null && typeof node.splitText === 'function'
-        /* The claimed SSR node must begin with this literal, or the split misaligns — throw
-           legibly at the divergence (only when a text node is actually here; a structural
-           mismatch is claimExpected's domain). */
-        if (isText) {
-            assertClaimedText(node, value)
+        if (claimText(hydration, parent, value, splitAlways) === undefined) {
+            const node = claimChild(hydration, parent)
+            parkCursor(hydration, parent, node === null ? null : node.nextSibling)
         }
-        /* Split even on an exact-length consume when a sibling text binding follows
-           (`splitAlways`), so it gets its own node; see appendText for the rationale. */
-        if (
-            isText &&
-            (splitAlways ? value.length <= node.data.length : value.length < node.data.length)
-        ) {
-            node.splitText(value.length)
-        }
-        hydration.next.set(parent, node === null ? null : node.nextSibling)
         return
     }
     parent.appendChild(document.createTextNode(value))

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())
     })