@abide/abide 0.53.0 → 0.54.0

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

@@ -1,4 +1,5 @@
-import { createShadowProgram, type ShadowProgram } from './createShadowProgram.ts'
+import { cachedShadowProgram } from './cachedShadowProgram.ts'
+import type { ShadowProgram } from './createShadowProgram.ts'
 import { shadowInterpolationClassifier } from './shadowInterpolationClassifier.ts'
 import type { InterpolationClassifier } from './types/InterpolationClassifier.ts'
 
@@ -12,24 +13,18 @@ The incremental `createShadowLanguageService` does not expose the checker, shado
 `ts.SourceFile`, or per-file mappings publicly, so v1 uses the one-shot
 `createShadowProgram` (reused per root) rather than the LS overlay path.
 
-FAIL-OPEN throughout: if the program can't be built, or the file has no shadow, the
-classifier is absent (→ today's plain-value binding); and the returned closure wraps
-its whole body so ANY throw (resolution failure, missing node, checker hiccup) returns
-`'sync'`. A type-resolution problem degrades to today's behavior, never breaks the build.
+FAIL-OPEN throughout: if the program can't be built (warned once per root by
+`cachedShadowProgram`), or the file has no shadow, the classifier is absent (→ today's
+plain-value binding); and the returned closure wraps its whole body so ANY throw
+(resolution failure, missing node, checker hiccup) returns `'sync'`. A type-resolution
+problem degrades to today's behavior, never breaks the build.
 */
 export function interpolationClassifierForRoot(
     cache: Map<string, ShadowProgram | undefined>,
     root: string,
     abidePath: string,
 ): InterpolationClassifier | undefined {
-    if (!cache.has(root)) {
-        try {
-            cache.set(root, createShadowProgram(root))
-        } catch {
-            cache.set(root, undefined)
-        }
-    }
-    const shadowProgram = cache.get(root)
+    const shadowProgram = cachedShadowProgram(cache, root)
     if (shadowProgram === undefined) {
         return undefined
     }

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

@@ -0,0 +1,49 @@
+import ts from 'typescript'
+
+/* Arithmetic compound assignments → their plain binary counterpart, lowered to a
+   read-combine-write (`x += y` → `write(read + y)`). */
+const ARITHMETIC_COMPOUND_OPERATORS = new Map<ts.SyntaxKind, ts.BinaryOperator>([
+    [ts.SyntaxKind.PlusEqualsToken, ts.SyntaxKind.PlusToken],
+    [ts.SyntaxKind.MinusEqualsToken, ts.SyntaxKind.MinusToken],
+    [ts.SyntaxKind.AsteriskEqualsToken, ts.SyntaxKind.AsteriskToken],
+    [ts.SyntaxKind.SlashEqualsToken, ts.SyntaxKind.SlashToken],
+])
+
+/* Logical compound assignments SHORT-CIRCUIT: the write fires only when the guard
+   passes (`x ??= v` is `x ?? (x = v)`), so they lower to `read <op> write(right)`, NOT
+   an unconditional write — matching JS, so a non-nullish/truthy/falsy guard does no
+   needless patch or cell reseed. */
+const LOGICAL_ASSIGNMENT_OPERATORS = new Map<ts.SyntaxKind, ts.BinaryOperator>([
+    [ts.SyntaxKind.QuestionQuestionEqualsToken, ts.SyntaxKind.QuestionQuestionToken],
+    [ts.SyntaxKind.BarBarEqualsToken, ts.SyntaxKind.BarBarToken],
+    [ts.SyntaxKind.AmpersandAmpersandEqualsToken, ts.SyntaxKind.AmpersandAmpersandToken],
+])
+
+/*
+Lowers an assignment (`=`, arithmetic `+=`, or logical `??=`/`||=`/`&&=`) to a reactive
+write, shared by the `$$model` doc path (lowerDocAccess) and the `$$writeCell` linked-cell
+path (renameSignalRefs) so the two lowerings can't drift. `makeRead` builds the target's
+read expression (only called for compound operators); `makeWrite` wraps a value in the
+write call. Returns undefined for an operator this doesn't handle so the caller can leave
+the node untouched. The write must evaluate to the written value (see `Cell.set` /
+`Doc.replace`) for the logical short-circuit to yield the right result.
+*/
+export function lowerCompoundAssignment(
+    operator: ts.SyntaxKind,
+    makeRead: () => ts.Expression,
+    right: ts.Expression,
+    makeWrite: (value: ts.Expression) => ts.Expression,
+): ts.Expression | undefined {
+    if (operator === ts.SyntaxKind.EqualsToken) {
+        return makeWrite(right)
+    }
+    const arithmetic = ARITHMETIC_COMPOUND_OPERATORS.get(operator)
+    if (arithmetic !== undefined) {
+        return makeWrite(ts.factory.createBinaryExpression(makeRead(), arithmetic, right))
+    }
+    const logical = LOGICAL_ASSIGNMENT_OPERATORS.get(operator)
+    if (logical !== undefined) {
+        return ts.factory.createBinaryExpression(makeRead(), logical, makeWrite(right))
+    }
+    return undefined
+}

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

@@ -1,6 +1,7 @@
 import ts from 'typescript'
 import { escapeKey } from '../runtime/escapeKey.ts'
-import { COMPOUND_ASSIGNMENT_OPERATORS } from './COMPOUND_ASSIGNMENT_OPERATORS.ts'
+import { lowerCompoundAssignment } from './lowerCompoundAssignment.ts'
+import { lowerUpdateExpression } from './lowerUpdateExpression.ts'
 
 /*
 The linchpin compiler pass. Rewrites idiomatic data access on a reactive document
@@ -91,33 +92,24 @@ export function docAccessTransformer(docName: string): ts.TransformerFactory<ts.
         }
 
         function visit(node: ts.Node): ts.Node {
-            /* Assignment (plain or compound) to a doc path → replace patch. */
+            /* Assignment (plain, compound, or logical) to a doc path → replace patch. */
             if (ts.isBinaryExpression(node)) {
                 const segments = pathSegments(node.left as ts.Expression)
                 if (segments) {
-                    const operator = node.operatorToken.kind
-                    if (operator === ts.SyntaxKind.EqualsToken) {
-                        return docCall(docName, 'replace', [
-                            buildPath(segments),
-                            ts.visitNode(node.right, visit) as ts.Expression,
-                        ])
-                    }
-                    const binary = COMPOUND_ASSIGNMENT_OPERATORS.get(operator)
-                    if (binary) {
-                        const next = ts.factory.createBinaryExpression(
-                            docCall(docName, 'read', [buildPath(segments)]),
-                            binary,
-                            ts.visitNode(node.right, visit) as ts.Expression,
-                        )
-                        return docCall(docName, 'replace', [buildPath(segments), next])
+                    const lowered = lowerCompoundAssignment(
+                        node.operatorToken.kind,
+                        () => docCall(docName, 'read', [buildPath(segments)]),
+                        ts.visitNode(node.right, visit) as ts.Expression,
+                        (value) => docCall(docName, 'replace', [buildPath(segments), value]),
+                    )
+                    if (lowered !== undefined) {
+                        return lowered
                     }
                 }
             }
-            /* `path++` / `++path` / `path--` on a doc path → a replace patch (the same
-               shape as `+= 1`). A bare `++` would otherwise survive onto the lowered read
-               (`model.read("n")++` / `cell.get()++`) — invalid, since a call result is not
-               an lvalue. abide handlers are statements, so the postfix/prefix value is
-               discarded and both lower identically. Only `++`/`--` are handled here; other
+            /* `path++` / `++path` / `path--` on a doc path → a replace patch. A bare `++`
+               would otherwise survive onto the lowered read (`model.read("n")++`) — invalid,
+               since a call result is not an lvalue. Only `++`/`--` are handled here; other
                unary operators (`!path`, `-path`) fall through so their operand lowers as a
                normal read. */
             if (
@@ -127,16 +119,12 @@ export function docAccessTransformer(docName: string): ts.TransformerFactory<ts.
             ) {
                 const segments = pathSegments(node.operand)
                 if (segments) {
-                    const step =
-                        node.operator === ts.SyntaxKind.PlusPlusToken
-                            ? ts.SyntaxKind.PlusToken
-                            : ts.SyntaxKind.MinusToken
-                    const next = ts.factory.createBinaryExpression(
-                        docCall(docName, 'read', [buildPath(segments)]),
-                        step,
-                        ts.factory.createNumericLiteral(1),
+                    return lowerUpdateExpression(
+                        ts.isPostfixUnaryExpression(node),
+                        node.operator === ts.SyntaxKind.PlusPlusToken,
+                        () => docCall(docName, 'read', [buildPath(segments)]),
+                        (value) => docCall(docName, 'replace', [buildPath(segments), value]),
                     )
-                    return docCall(docName, 'replace', [buildPath(segments), next])
                 }
             }
             /* doc array `.push(a, b, …)` → one `add` patch per argument at the array's `-`

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

@@ -0,0 +1,32 @@
+import ts from 'typescript'
+
+/*
+Lowers `x++` / `++x` / `x--` / `--x` on reactive state to a write of the stepped value,
+shared by the `$$model` doc path (lowerDocAccess) and the `$$writeCell` linked-cell path
+(renameSignalRefs). `makeRead`/`makeWrite` mirror `lowerCompoundAssignment`. The bare `++`
+can't survive onto the read form (`$$readCell(x)` / `$$model.read(...)` are calls, not
+lvalues), so it becomes an explicit write of `read ± 1`.
+
+Prefix evaluates to the NEW value, which is exactly what the write returns, so
+`write(read ± 1)` is correct as-is. POSTFIX must evaluate to the PREVIOUS value, so its
+result is corrected back by the opposite step (`x++` → `write(read + 1) - 1`) — no temp or
+closure, since the write returns the written value (`Cell.set` / `Doc.replace`). The
+correction is dead when the value is discarded (a statement `x++;`), so it costs nothing
+there.
+*/
+export function lowerUpdateExpression(
+    isPostfix: boolean,
+    isIncrement: boolean,
+    makeRead: () => ts.Expression,
+    makeWrite: (value: ts.Expression) => ts.Expression,
+): ts.Expression {
+    const step = isIncrement ? ts.SyntaxKind.PlusToken : ts.SyntaxKind.MinusToken
+    const write = makeWrite(
+        ts.factory.createBinaryExpression(makeRead(), step, ts.factory.createNumericLiteral(1)),
+    )
+    if (!isPostfix) {
+        return write
+    }
+    const correction = isIncrement ? ts.SyntaxKind.MinusToken : ts.SyntaxKind.PlusToken
+    return ts.factory.createBinaryExpression(write, correction, ts.factory.createNumericLiteral(1))
+}

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

@@ -1,5 +1,6 @@
 import ts from 'typescript'
-import { COMPOUND_ASSIGNMENT_OPERATORS } from './COMPOUND_ASSIGNMENT_OPERATORS.ts'
+import { lowerCompoundAssignment } from './lowerCompoundAssignment.ts'
+import { lowerUpdateExpression } from './lowerUpdateExpression.ts'
 
 /*
 Rewrites references to a component's signal bindings into the document form the
@@ -120,21 +121,19 @@ export function signalRefsTransformer(
                     !shadowed.has(node.left.text)
                 ) {
                     const target = node.left.text
-                    const right = ts.visitNode(node.right, visit) as ts.Expression
-                    if (node.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
-                        return writeCellCall(target, right)
-                    }
-                    const binary = COMPOUND_ASSIGNMENT_OPERATORS.get(node.operatorToken.kind)
-                    if (binary !== undefined) {
-                        return writeCellCall(
-                            target,
-                            ts.factory.createBinaryExpression(cellReadCall(target), binary, right),
-                        )
+                    const lowered = lowerCompoundAssignment(
+                        node.operatorToken.kind,
+                        () => cellReadCall(target),
+                        ts.visitNode(node.right, visit) as ts.Expression,
+                        (value) => writeCellCall(target, value),
+                    )
+                    if (lowered !== undefined) {
+                        return lowered
                     }
                 }
                 /* `draft++` / `++draft` / `draft--` on a `linked` cell → a `$$writeCell` of the
-                   stepped value, mirroring the `+= 1` shape (the bare `++` would otherwise land
-                   on `$$readCell(draft)`, an invalid lvalue). */
+                   stepped value (the bare `++` would otherwise land on `$$readCell(draft)`, an
+                   invalid lvalue). */
                 if (
                     (ts.isPostfixUnaryExpression(node) || ts.isPrefixUnaryExpression(node)) &&
                     (node.operator === ts.SyntaxKind.PlusPlusToken ||
@@ -143,17 +142,12 @@ export function signalRefsTransformer(
                     cellReadNames.has(node.operand.text) &&
                     !shadowed.has(node.operand.text)
                 ) {
-                    const step =
-                        node.operator === ts.SyntaxKind.PlusPlusToken
-                            ? ts.SyntaxKind.PlusToken
-                            : ts.SyntaxKind.MinusToken
-                    return writeCellCall(
-                        node.operand.text,
-                        ts.factory.createBinaryExpression(
-                            cellReadCall(node.operand.text),
-                            step,
-                            ts.factory.createNumericLiteral(1),
-                        ),
+                    const target = node.operand.text
+                    return lowerUpdateExpression(
+                        ts.isPostfixUnaryExpression(node),
+                        node.operator === ts.SyntaxKind.PlusPlusToken,
+                        () => cellReadCall(target),
+                        (value) => writeCellCall(target, value),
                     )
                 }
                 /* Shorthand `{ count }` → `{ count: $$model.count }` / `{ total: total.value }`,

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

@@ -1,5 +1,6 @@
+import { cachedShadowProgram } from './cachedShadowProgram.ts'
 import { classifyInterpolationType } from './classifyInterpolationType.ts'
-import { createShadowProgram, type ShadowProgram } from './createShadowProgram.ts'
+import type { ShadowProgram } from './createShadowProgram.ts'
 import { nodeAtShadowOffset } from './nodeAtShadowOffset.ts'
 import { shadowNaming } from './shadowNaming.ts'
 import { sourceToShadowOffset } from './sourceToShadowOffset.ts'
@@ -18,25 +19,19 @@ as `state.computed` — either way the seed sub-expression maps back to source a
 own type), so the identical `sourceToShadowOffset → nodeAtShadowOffset → classifyInterpolation
 Type` pipeline the interpolation half uses resolves a seed with no node-finder variant.
 
-FAIL-OPEN, but NOT to `'sync'`: if the program can't build, the file has no shadow, the seed's
-location doesn't map, no node is found, or the checker throws, the classifier is absent /
-returns `undefined` — the signal the caller reads as "degrade to `isBareCallComputed`", NOT as
-"the seed is sync". Collapsing failure to `'sync'` (as the interpolation classifier does) would
-mis-route a failed stream seed to the lazy `derive` slot instead of today's syntax heuristic.
+FAIL-OPEN, but NOT to `'sync'`: if the program can't build (warned once per root by
+`cachedShadowProgram`), the file has no shadow, the seed's location doesn't map, no node is
+found, or the checker throws, the classifier is absent / returns `undefined` — the signal the
+caller reads as "degrade to `isBareCallComputed`", NOT as "the seed is sync". Collapsing failure
+to `'sync'` (as the interpolation classifier does) would mis-route a failed stream seed to the
+lazy `derive` slot instead of today's syntax heuristic.
 */
 export function seedTypeClassifierForRoot(
     cache: Map<string, ShadowProgram | undefined>,
     root: string,
     abidePath: string,
 ): SeedTypeClassifier | undefined {
-    if (!cache.has(root)) {
-        try {
-            cache.set(root, createShadowProgram(root))
-        } catch {
-            cache.set(root, undefined)
-        }
-    }
-    const shadowProgram = cache.get(root)
+    const shadowProgram = cachedShadowProgram(cache, root)
     if (shadowProgram === undefined) {
         return undefined
     }

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

@@ -1,4 +1,5 @@
 import ts from 'typescript'
+import { AbideCompileError } from './AbideCompileError.ts'
 
 /*
 Folds a cell-source `watch(source, handler)` into the auto-tracked thunk form
@@ -51,7 +52,7 @@ export function wrapReactionCellSources(
        expression is read ONCE as a plain value (outside any tracking scope) and handed to the
        runtime as a dead value: nothing subscribes, the reaction never fires. It can't be folded
        like a bare cell (a member access isn't a whole-cell subscription), so return the base
-       name to warn on and leave the source for the author to rewrite. */
+       name to REJECT on and point the author at the corrective forms. */
     function cellMemberBase(source: ts.Expression): string | undefined {
         if (
             (ts.isPropertyAccessExpression(source) || ts.isElementAccessExpression(source)) &&
@@ -95,19 +96,22 @@ export function wrapReactionCellSources(
                 )
                 return ts.factory.createCallExpression(node.expression, undefined, [thunk])
             }
-            /* Warn on the inert member-expression form `watch(s.foo, handler)` — it looks valid but
-               subscribes to nothing (see `cellMemberBase`). Not foldable; the fix is the author's. */
+            /* Reject the inert member-expression form `watch(s.foo, handler)` — it looks valid but
+               subscribes to nothing (see `cellMemberBase`), so the handler silently never fires. Not
+               foldable; a compile error turns the silent no-op into a caught mistake. A member of a
+               cell is never itself a cell (no per-property cells), so this can't reject a valid watch. */
+            const memberBase = sourceArg !== undefined ? cellMemberBase(sourceArg) : undefined
             if (
                 ts.isCallExpression(node) &&
                 ts.isIdentifier(node.expression) &&
                 watchLocalNames.has(node.expression.text) &&
                 node.arguments.length === 2 &&
                 sourceArg !== undefined &&
-                cellMemberBase(sourceArg) !== undefined
+                memberBase !== undefined
             ) {
                 const sourceText = sourceArg.getText(root)
-                console.warn(
-                    `[abide] \`watch(${sourceText}, …)\` does not track \`${sourceText}\` — a member access on a cell is read once as a plain value (abide has no per-property cells), so the reaction is inert. Wrap it in a thunk (\`watch(() => …(${sourceText}))\`) or watch the whole cell (\`watch(${cellMemberBase(sourceArg)}, v => …)\`).`,
+                throw new AbideCompileError(
+                    `[abide] \`watch(${sourceText}, …)\` does not track \`${sourceText}\` — a member access on a cell is read once as a plain value (abide has no per-property cells), so the reaction never fires. Wrap it in a thunk (\`watch(() => …(${sourceText}))\`) or watch the whole cell (\`watch(${memberBase}, v => …)\`).`,
                 )
             }
             return ts.visitEachChild(node, visit, context)

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

@@ -7,8 +7,8 @@ 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'

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

@@ -4,8 +4,8 @@ import { CURRENT_BOUNDARY } from '../runtime/CURRENT_BOUNDARY.ts'
 import { claimExpected } from '../runtime/claimExpected.ts'
 import { OWNER } from '../runtime/OWNER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
-import { scopeGroup } from '../runtime/scopeGroup.ts'
 import { SuspenseSignal } from '../runtime/SuspenseSignal.ts'
+import { scopeGroup } from '../runtime/scopeGroup.ts'
 import type { Boundary } from '../runtime/types/Boundary.ts'
 import type { State } from '../runtime/types/State.ts'
 import { withoutHydration } from '../runtime/withoutHydration.ts'

package/src/lib/ui/router.ts

@@ -12,6 +12,7 @@ import { exitRenderPass } from './runtime/exitRenderPass.ts'
 import { historyEntries } from './runtime/historyEntries.ts'
 import { PENDING_OUTLET } from './runtime/PENDING_OUTLET.ts'
 import { RENDER } from './runtime/RENDER.ts'
+import { restoreWarmSeeds } from './runtime/restoreWarmSeeds.ts'
 import { runtimePath } from './runtime/runtimePath.ts'
 import type { AbideHistoryState } from './runtime/types/AbideHistoryState.ts'
 import type { NavVerdict } from './runtime/types/NavVerdict.ts'
@@ -566,6 +567,13 @@ export function router(
                             disposeFrom(0)
                             rootBoundary = undefined
                             mountedPageKey = undefined
+                            /* Re-seed the cell/doc warm partitions the failed hydration pass consumed,
+                               so the cold rebuild re-adopts the SSR-resolved values instead of
+                               refetching — a cold refetch leaves blocking `await` cells pending, and a
+                               top-level `$$readCellBlocking` sits in no suspense region, so its
+                               SuspenseSignal would escape this rebuild (it runs inside the catch, past
+                               the try) and kill the mount. Restored, the rebuild reads settled. */
+                            restoreWarmSeeds()
                             buildFrom(0, chainKeys, layoutViews, pageView, key, params, false)
                         }
                         /* Reapply the destination entry's scroll once its DOM exists — a

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

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

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

@@ -0,0 +1,20 @@
+import { CELL_SEED } from './CELL_SEED.ts'
+import { DOC_SEED } from './DOC_SEED.ts'
+import { warmSeedBackup } from './warmSeedBackup.ts'
+
+/*
+Re-populate the async-cell and doc-state warm-seed manifests from the pristine SSR copies stashed at
+boot, undoing the consume-once deletes the failed hydration pass made. The router's hydration-desync
+recovery calls this before it rebuilds the page COLD: with the seeds restored, each rebuilt cell
+re-adopts its SSR-resolved value (reads settled, not pending) instead of refetching — so a blocking
+`await` cell can't throw an uncaught SuspenseSignal at mount, and the cold render shows real data with
+no loading flash. A no-op when boot never seeded (a fresh client-only mount).
+*/
+export function restoreWarmSeeds(): void {
+    if (warmSeedBackup.cells !== undefined) {
+        Object.assign(CELL_SEED, warmSeedBackup.cells)
+    }
+    if (warmSeedBackup.docs !== undefined) {
+        Object.assign(DOC_SEED, warmSeedBackup.docs)
+    }
+}

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

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

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

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

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

@@ -0,0 +1,10 @@
+import type { SsrPayload } from '../../shared/types/SsrPayload.ts'
+
+/* The pristine SSR warm-seed manifests (`__SSR__.cells` / `__SSR__.docs`), stashed by `startClient`
+   before the hydration pass drains their client copies — each adopted seed is DELETED from CELL_SEED /
+   consumed from DOC_SEED as it hydrates. `Object.assign`-ing into those seeds leaves these source
+   records untouched, so they stay a clean re-seed source. The router's discard→cold-rebuild recovery
+   reads them via `restoreWarmSeeds` so the rebuilt cells re-adopt the SSR-resolved values instead of
+   refetching cold — a cold refetch would leave a blocking `await` cell pending and throw an uncaught
+   SuspenseSignal at mount, killing the page. Empty on a fresh client-only mount (nothing seeded). */
+export const warmSeedBackup: { cells?: SsrPayload['cells']; docs?: SsrPayload['docs'] } = {}

package/src/lib/ui/socketProxy.ts

@@ -1,4 +1,6 @@
 import { buildSocketOverChannel } from '../shared/buildSocketOverChannel.ts'
+import { decodeRefJson } from '../shared/decodeRefJson.ts'
+import { SOCKET_SEED } from '../shared/SOCKET_SEED.ts'
 import type { Socket } from '../shared/types/Socket.ts'
 import { getSocketChannel } from './socketChannel.ts'
 import { watch } from './watch.ts'
@@ -22,7 +24,21 @@ socketProxy API, not the wire layer.
 */
 // @documentation plumbing
 export function socketProxy<T>(name: string): Socket<T> {
-    const socket = buildSocketOverChannel<T>(name, getSocketChannel)
+    /* Warm-seed from the server's retained frame (shipped in `__SSR__.sockets`, drained into
+       SOCKET_SEED by startClient before mount) so `peek(socket)` returns the SAME value the SSR
+       render committed to instead of undefined on this not-yet-connected client — otherwise the two
+       disagree and hydration discards the server markup. A frame that failed to serialize server-side
+       simply isn't present, and the socket falls back to a cold peek. */
+    const seeded = SOCKET_SEED[name]
+    let initialFrame: T | undefined
+    if (seeded !== undefined) {
+        try {
+            initialFrame = decodeRefJson(seeded) as T
+        } catch {
+            initialFrame = undefined
+        }
+    }
+    const socket = buildSocketOverChannel<T>(name, getSocketChannel, initialFrame)
     /* Overwrite the shared builder's inert `.watch` with the real reaction sugar
        (`socket.watch(handler)` ≡ `watch(socket, handler)`). Attached here so the ui-only
        `watch` primitive never rides into a server bundle. */

package/src/lib/ui/startClient.ts

@@ -1,17 +1,23 @@
+import { amendBroadcastSlot } from '../shared/amendBroadcastSlot.ts'
+import { applyAmendLocally } from '../shared/applyAmendLocally.ts'
 import { applyCacheStalenessLocally } from '../shared/applyCacheStalenessLocally.ts'
+import { cacheReaderSocketSlot } from '../shared/cacheReaderSocketSlot.ts'
 import { cacheStalenessSlot } from '../shared/cacheStalenessSlot.ts'
 import { cacheStoreSlot } from '../shared/cacheStoreSlot.ts'
 import { createCacheStore } from '../shared/createCacheStore.ts'
 import { pageSlot } from '../shared/pageSlot.ts'
+import { SOCKET_SEED } from '../shared/SOCKET_SEED.ts'
 import { sharedCacheStoreSlot } from '../shared/sharedCacheStoreSlot.ts'
 import type { SsrPayload } from '../shared/types/SsrPayload.ts'
 import type { StreamedResolution } from '../shared/types/StreamedResolution.ts'
+import { createAmendReaderHook } from './amendReaderHook.ts'
 import { probeNavigation } from './probeNavigation.ts'
 import { router } from './router.ts'
 import { CELL_SEED } from './runtime/CELL_SEED.ts'
 import { clientPage } from './runtime/clientPage.ts'
 import { DOC_SEED } from './runtime/DOC_SEED.ts'
 import type { RouteLoader } from './runtime/types/RouteLoader.ts'
+import { warmSeedBackup } from './runtime/warmSeedBackup.ts'
 import { seedBootState } from './seedBootState.ts'
 import { seedStreamedResolution } from './seedStreamedResolution.ts'
 import { subscribeCacheStaleness } from './subscribeCacheStaleness.ts'
@@ -57,6 +63,13 @@ export function startClient(
        broadcaster instead — the ADR-0041 side-swap). Same function as the slot fallback so
        the local-apply path can't diverge. */
     cacheStalenessSlot.resolver = () => applyCacheStalenessLocally
+    /* amend(args, value) applies to THIS tab's cache too — the server entry broadcasts instead
+       (the ADR-0043 side-swap). Same function as the slot fallback for the same reason. */
+    amendBroadcastSlot.resolver = () => applyAmendLocally
+    /* Open/close a per-call amend value subscription as reactive readers of a key come and go
+       (ADR-0043), so a server amend(args, value) push lands on keys this tab is reading. */
+    const amendReader = createAmendReaderHook()
+    cacheReaderSocketSlot.resolver = () => amendReader.hook
     /* Seed both SSR cache partitions through the one streamed-resolution sink: `ssr.cache`
        (inline — reads settled at render-return, in __SSR__) and `__abideResumeCache` (pending
        {#await} reads whose `__abideResolve(...)` chunks the stream pushed during parse, before
@@ -80,6 +93,18 @@ export function startClient(
     if (ssr.docs !== undefined) {
         Object.assign(DOC_SEED, ssr.docs)
     }
+    /* Seed the socket warm partition into SOCKET_SEED before mount: a hydrating `socketProxy` reads
+       its name key to seed `lastFrame`, so `peek(socket)` returns the server's retained frame instead
+       of undefined on the not-yet-connected client — congruent with the SSR HTML. */
+    if (ssr.sockets !== undefined) {
+        Object.assign(SOCKET_SEED, ssr.sockets)
+    }
+    /* Stash the pristine cell/doc manifests for the router's hydration-desync recovery: the hydration
+       pass consumes CELL_SEED/DOC_SEED (each adopted key is deleted), so a discard→cold-rebuild would
+       otherwise refetch every blocking cell — leaving it pending and throwing an uncaught
+       SuspenseSignal at mount. `restoreWarmSeeds` re-seeds from these before the cold rebuild. */
+    warmSeedBackup.cells = ssr.cells
+    warmSeedBackup.docs = ssr.docs
     /* Keep the cache channel live past boot: replace the head's buffering collector with
        the store-connected sink so a post-boot resolution — the inline doc-stream cache
        script — seeds the store through `seedStreamedResolution` directly instead of pushing
@@ -94,6 +119,11 @@ export function startClient(
     const disposeRouter = router(target, routes, layoutRoutes, probeNavigation)
     return () => {
         disposeStaleness()
+        amendReader.dispose()
+        /* Clear the reader hook so a post-teardown cache read doesn't re-open amend subscriptions
+           — unlike the staleness/store slots (whose leaked resolver stays benign), a live hook on
+           the read path must not outlive the client it belongs to. */
+        cacheReaderSocketSlot.resolver = undefined
         disposeRouter()
     }
 }

package/src/lib/ui/types/Scope.ts

@@ -25,7 +25,7 @@ export type Scope = {
     readonly parent: Scope | undefined
     /* data — mirrors Doc */
     read: <T>(path: string) => T
-    replace: (path: string, value: unknown) => void
+    replace: (path: string, value: unknown) => unknown
     add: (path: string, value: unknown) => void
     remove: (path: string) => void
     apply: (patch: Patch) => void