@abide/abide 0.52.0 → 0.54.0

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

@@ -1,3 +1,5 @@
+import { effect } from '../effect.ts'
+import { SuspenseSignal } from '../runtime/SuspenseSignal.ts'
 import { attr } from './attr.ts'
 import { on } from './on.ts'
 
@@ -19,7 +21,51 @@ export function spreadAttrs(
     exclude: string[] = [],
 ): void {
     const skip = new Set(exclude)
-    const object = source()
+    let object: Record<string, unknown>
+    try {
+        object = source()
+    } catch (signal) {
+        /* A spread over a PENDING blocking `await` read throws a `SuspenseSignal` here (ADR-0042):
+           its keys can't be enumerated yet. Binding the empty object now would create no `attr`/`on`
+           effects, so the attributes would never appear after the cell resolves — instead defer the
+           enumeration into a one-shot effect that re-runs on settle (the read tracked its cell). The
+           effect is pinned to this build's scope, so the `attr` binds it creates own their lifetime
+           correctly; a `spread` flag makes the enumeration fire exactly once (later value changes
+           re-read per key via `attr`, never re-enumerate). */
+        if (!(signal instanceof SuspenseSignal)) {
+            throw signal
+        }
+        let spread = false
+        effect(() => {
+            let resolved: Record<string, unknown>
+            try {
+                resolved = source()
+            } catch (retry) {
+                if (!(retry instanceof SuspenseSignal)) {
+                    throw retry
+                }
+                return
+            }
+            if (spread) {
+                return
+            }
+            spread = true
+            bindKeys(element, source, resolved, skip)
+        })
+        return
+    }
+    bindKeys(element, source, object, skip)
+}
+
+/* Binds each own key of `object` onto `element`: an `on<event>` function attaches as a listener,
+   any other non-function value binds as a reactive attribute re-reading `source()[key]` per change.
+   A key in `skip` is left to its explicit binding. */
+function bindKeys(
+    element: Element,
+    source: () => Record<string, unknown>,
+    object: Record<string, unknown>,
+    skip: Set<string>,
+): void {
     for (const key in object) {
         if (skip.has(key)) {
             continue

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

@@ -1,3 +1,4 @@
+import { SuspenseSignal } from '../runtime/SuspenseSignal.ts'
 import { mountSwappableRange } from './mountSwappableRange.ts'
 import type { SwitchCase } from './types/SwitchCase.ts'
 
@@ -47,8 +48,24 @@ export function switchBlock(
         parent,
         /* A pending bare async subject (compiler-supplied `isPending`) selects no case — not
            even the default — so the block renders nothing until the cell settles, rather than
-           conflating "still loading" with a subject that matched the default. */
-        () => (isPending?.() === true ? -1 : select(subject())),
+           conflating "still loading" with a subject that matched the default. A blocking `await`
+           cell embedded in the subject or a `match` (a member access / compound the `isPending`
+           gate doesn't cover) throws a `SuspenseSignal` while pending (ADR-0042); select no case
+           until it settles, exactly as a bare async subject holds — the read tracked its cell, so
+           the swap effect re-runs on resolve. */
+        () => {
+            if (isPending?.() === true) {
+                return -1
+            }
+            try {
+                return select(subject())
+            } catch (signal) {
+                if (!(signal instanceof SuspenseSignal)) {
+                    throw signal
+                }
+                return -1
+            }
+        },
         (index) => {
             const chosen = index === -1 ? undefined : cases[index]
             return chosen && ((p) => chosen.render(p))

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

@@ -4,6 +4,7 @@ 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 { 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'
@@ -104,6 +105,15 @@ export function tryBlock(
             activeKind = 'try'
             errorCell = undefined
         } catch (error) {
+            /* A `SuspenseSignal` is "value pending", not an error, and must NEVER render `{:catch}`
+               (ADR-0042 D3, mirroring `flushEffects`, which refuses to route it to a boundary) — that
+               would flash the author's catch during loading and, since `rewatch` only arms on an
+               `AsyncCellError`, stick there forever. Every reading region withholds its own suspend
+               locally (post-ADR-0042 the `{#await}`/`{#each await}` subjects included), so this is
+               unreachable in a compiled template; rethrow defensively rather than mislabel it. */
+            if (error instanceof SuspenseSignal) {
+                throw error
+            }
             if (!hasCatch) {
                 throw error
             }

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

@@ -1,3 +1,4 @@
+import { SuspenseSignal } from '../runtime/SuspenseSignal.ts'
 import { mountSwappableRange } from './mountSwappableRange.ts'
 
 /*
@@ -26,7 +27,24 @@ export function when(
 ): void {
     mountSwappableRange(
         parent,
-        () => (isPending?.() === true ? 'pending' : condition() ? 'then' : 'else'),
+        () => {
+            if (isPending?.() === true) {
+                return 'pending'
+            }
+            /* A blocking `await` cell embedded in the condition — a member access or compound the
+               whole-subject `isPending` gate doesn't cover (`{#if !sources.length}`, `{#if user &&
+               await load()}`) — throws a `SuspenseSignal` while pending (ADR-0042). Withhold the
+               block (render neither branch) until it settles, exactly as a bare async subject holds;
+               the read tracked its cell, so the swap effect re-runs on resolve. */
+            try {
+                return condition() ? 'then' : 'else'
+            } catch (signal) {
+                if (!(signal instanceof SuspenseSignal)) {
+                    throw signal
+                }
+                return 'pending'
+            }
+        },
         (branch) => (branch === 'then' ? render : branch === 'else' ? renderElse : undefined),
         before,
         /* An async subject (compiler supplies `isPending`) can render a different branch on the

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

@@ -0,0 +1,22 @@
+import { SuspenseSignal } from '../runtime/SuspenseSignal.ts'
+
+/*
+Runs `read`, returning `fallback` when it SUSPENDS — a pending blocking `await` read throws a
+`SuspenseSignal` (ADR-0042). The reading region shows `fallback` until the value resolves; the
+throwing read subscribed the enclosing effect to the cell, so the effect re-runs and fills in on
+settle. Any non-suspense error propagates unchanged (a real rejection still reaches `{#try}`). The
+single place the `instanceof SuspenseSignal` swallow lives for a value-returning bind, so the read
+sites (`each`, `watch`, …) share one definition rather than copying the try/catch. Text binds use
+the sibling `readTextOrSuspend` (fallback `''` with String coercion); an attribute leaves itself
+unset inline (a side effect, not a fallback value).
+*/
+export function withSuspense<T>(read: () => T, fallback: T): T {
+    try {
+        return read()
+    } catch (signal) {
+        if (!(signal instanceof SuspenseSignal)) {
+            throw signal
+        }
+        return fallback
+    }
+}

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/SuspenseSignal.ts

@@ -0,0 +1,24 @@
+import type { AsyncComputed } from '../../shared/types/AsyncComputed.ts'
+
+/*
+The sentinel a compiled blocking read (`$$readCellBlocking`, an `await`-marked cell) raises
+when the cell has no value *yet* — "not resolved," not an error (ADR-0042 D3). It is a sibling
+of `AsyncCellError` but a DISTINCT class so the two are told apart by `instanceof`: a suspend is
+caught LOCALLY by the reading region — each DOM primitive (`appendText`, `attr`, `each`,
+`spreadAttrs`, `watch`, and the `when`/`switchBlock` condition) swallows it and withholds to an
+empty fallback, re-running on settle because the throwing read already subscribed the region's
+effect to the cell. It must never be handled as an error: `flushEffects` refuses to route a
+`SuspenseSignal` to a reactive `{#try}` (that would flash the author's `{:catch}` during loading),
+while an `AsyncCellError` still passes through. It carries the originating cell for diagnostics.
+Extends `Error` only to satisfy throw-an-Error lint and match `AsyncCellError`; it carries no
+`cause` — there is nothing wrong, the value is simply pending.
+*/
+export class SuspenseSignal extends Error {
+    readonly cell: AsyncComputed<unknown>
+
+    constructor(cell: AsyncComputed<unknown>) {
+        super('abide: suspense (value pending)')
+        this.name = 'SuspenseSignal'
+        this.cell = cell
+    }
+}

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/flushEffects.ts

@@ -1,6 +1,7 @@
 import { boundaryFor } from './boundaryFor.ts'
 import { NODE_STATE } from './NODE_STATE.ts'
 import { REACTIVE_CONTEXT } from './REACTIVE_CONTEXT.ts'
+import { SuspenseSignal } from './SuspenseSignal.ts'
 import type { ReactiveNode } from './types/ReactiveNode.ts'
 import { updateIfNecessary } from './updateIfNecessary.ts'
 
@@ -50,16 +51,23 @@ function drain(): void {
             try {
                 updateIfNecessary(node)
             } catch (error) {
-                /* A node built inside a reactive `{#try}` routes its throw to that boundary
-                   (swap the guarded content to the catch branch) instead of the rethrow
-                   fallback — this is the "later re-run throw" the sync boundary could not
-                   catch. Reset it CLEAN either way so a later write to its deps can re-queue
-                   it (otherwise `mark`'s CLEAN→dirty gate leaves it permanently inert). */
-                const boundary = boundaryFor.get(node)
-                if (boundary !== undefined) {
-                    boundary.handle(error)
-                    node.status = NODE_STATE.CLEAN
-                    continue
+                /* A `SuspenseSignal` is "no value yet", not an error, and must NEVER route to a
+                   reactive `{#try}` (that would flash the author's `{:catch}` during loading,
+                   ADR-0042 D3). Every reading region catches its own suspend locally and re-runs on
+                   settle (the throwing read subscribed its cell), so a `SuspenseSignal` reaches here
+                   only if it escaped an unguarded read — surface it via the error collector below
+                   rather than leaking it to a boundary. A normal error routes to the node's nearest
+                   `{#try}` boundary: swap the guarded content to the catch branch instead of the
+                   rethrow fallback — the "later re-run throw" the sync boundary could not catch.
+                   Reset it CLEAN either way so a later write to its deps can re-queue it (otherwise
+                   `mark`'s CLEAN→dirty gate leaves it permanently inert). */
+                if (!(error instanceof SuspenseSignal)) {
+                    const boundary = boundaryFor.get(node)
+                    if (boundary !== undefined) {
+                        boundary.handle(error)
+                        node.status = NODE_STATE.CLEAN
+                        continue
+                    }
                 }
                 /* No boundary — one effect throwing must not strand the effects queued behind
                    it (they live in this same `batch`, unreachable once we swap

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

package/src/lib/ui/watch.ts

@@ -3,10 +3,12 @@ import { REMOTE_FUNCTION } from '../shared/REMOTE_FUNCTION.ts'
 import type { CacheOnContext } from '../shared/types/CacheOnContext.ts'
 import type { NamedAsyncIterable } from '../shared/types/NamedAsyncIterable.ts'
 import type { RemoteFunction } from '../shared/types/RemoteFunction.ts'
+import { withSuspense } from './dom/withSuspense.ts'
 import { effect } from './effect.ts'
 import { generationGuard } from './runtime/generationGuard.ts'
 import type { EffectResult } from './runtime/types/EffectResult.ts'
 import type { State } from './runtime/types/State.ts'
+import { untrack } from './runtime/untrack.ts'
 
 /*
 The single reaction primitive: `watch(source, handler)` names its trigger and runs
@@ -24,6 +26,14 @@ into a server bundle; server-side it is an inert no-op. Unlike bare `watch(…)`
 the SSR back-end strips — a `.watch(…)` member call survives to the server and relies on
 that inert stub.
 
+Tracking contract (ADR-0044): the named source(s) are the sole triggers — the handler
+is a sink, run untracked, so a reactive read in its body never becomes an accidental
+extra trigger. Only the bare `watch(thunk)` form auto-tracks everything it reads (that
+IS its job — it is the compiler binding). This makes all explicit-source forms uniform:
+the subscribable (cache.on, per-frame) and rpc (handler in a .then microtask) branches
+already ran their handlers out of the tracking window; the two synchronous cell branches
+now match by wrapping the handler in `untrack`.
+
 Sources (discriminated at runtime, monomorphic per branch):
   watch(thunk)                       // compiler binding form — auto-tracked, == effect(thunk)
   watch(count, n => …)               // a state cell → handler(newValue)
@@ -61,9 +71,13 @@ export function watch(
        also silence the compiler's generated bindings, which build on the client where the test
        DOM sets no global `window`). SSR-safety comes from the compiler stripping author
        `watch(...)` calls, and the subscribable branch's own server guard (cache.on). */
-    /* Compiler binding form watch(thunk): a bare auto-tracked effect (== today's $$effect). */
+    /* Compiler binding form watch(thunk): a bare auto-tracked effect (== today's $$effect). A
+       pending blocking `await` read throws a `SuspenseSignal` (ADR-0042) — withhold this reaction
+       (e.g. leave a `class:`/`style:` binding untouched) until the value resolves; the read tracked
+       its cell, so the effect re-runs on settle. Rethrows any real error. */
     if (argsOrHandler === undefined) {
-        return effect(source as () => EffectResult)
+        const thunk = source as () => EffectResult
+        return effect(() => withSuspense<EffectResult>(thunk, undefined))
     }
     /* watch(fn, args, handler): an rpc selector with explicit args. */
     if (maybeHandler !== undefined) {
@@ -88,18 +102,22 @@ export function watch(
     ) {
         return reactToRpc(source, undefined, handler)
     }
-    /* Multiple cells → fire on any change; hand the handler the current values. */
+    /* Multiple cells → fire on any change; hand the handler the current values. Read every
+       cell (the tracked triggers), then run the handler untracked so a reactive read in its
+       body is not captured as an extra trigger (ADR-0044). */
     if (Array.isArray(source)) {
         const cells = source as ReadonlyArray<State<unknown>>
         return effect(() => {
             const values = cells.map((cell) => cell.value)
-            handler(values)
+            untrack(() => handler(values))
         })
     }
-    /* A single state cell → handler(newValue) on change. */
+    /* A single state cell → handler(newValue) on change. The cell read is the tracked
+       trigger; the handler is a sink, run untracked (ADR-0044). */
     const cell = source as State<unknown>
     return effect(() => {
-        handler(cell.value)
+        const value = cell.value
+        untrack(() => handler(value))
     })
 }
 
@@ -115,7 +133,7 @@ function isSubscribable(source: unknown): boolean {
 /*
 Reacts to an rpc's cached value: an effect that runs the smart read (subscribing
 its key synchronously, so the effect re-runs when the value changes — a refresh,
-a patch, an invalidate) and pipes the resolved value to the handler. Triggers the
+an amend, an invalidate) and pipes the resolved value to the handler. Triggers the
 read, unlike peek: `watch` observes a live query, so it keeps it flowing.
 */
 function reactToRpc(fn: unknown, args: unknown, handler: (value: unknown) => void): () => void {

package/src/serverEntry.ts

@@ -26,10 +26,12 @@ import { shell } from './_virtual/shell.ts'
 import { sockets } from './_virtual/sockets.ts'
 import { exitWithParent } from './lib/bundle/exitWithParent.ts'
 import { loadEnvFromBinaryDir } from './lib/cli/loadEnvFromBinaryDir.ts'
+import { broadcastAmend } from './lib/server/runtime/amendBroadcaster.ts'
 import { broadcastCacheStaleness } from './lib/server/runtime/cacheStalenessBroadcaster.ts'
 import { createServer } from './lib/server/runtime/createServer.ts'
 import { requestContext } from './lib/server/runtime/requestContext.ts'
 import { resolvePageSnapshot } from './lib/server/runtime/resolvePageSnapshot.ts'
+import { amendBroadcastSlot } from './lib/shared/amendBroadcastSlot.ts'
 import { cacheStalenessSlot } from './lib/shared/cacheStalenessSlot.ts'
 import { cacheStoreSlot } from './lib/shared/cacheStoreSlot.ts'
 import { createCacheStore } from './lib/shared/createCacheStore.ts'
@@ -40,6 +42,7 @@ import { pendingAsyncCellsSlot } from './lib/shared/pendingAsyncCellsSlot.ts'
 import { resolvedCellsSlot } from './lib/shared/resolvedCellsSlot.ts'
 import { runningAsStandaloneBinary } from './lib/shared/runningAsStandaloneBinary.ts'
 import { sharedCacheStoreSlot } from './lib/shared/sharedCacheStoreSlot.ts'
+import { socketTailsSlot } from './lib/shared/socketTailsSlot.ts'
 import { streamedCellsSlot } from './lib/shared/streamedCellsSlot.ts'
 
 /*
@@ -89,6 +92,14 @@ so its server socket code never enters the client reachability graph.
 */
 cacheStalenessSlot.resolver = () => broadcastCacheStaleness
 
+/*
+Server-side amend(args, value) broadcasts the keyed value to every authorized reader
+instead of mutating a throwaway request store (ADR-0043). Imported ONLY here so the
+broadcaster's socket code never enters the client reachability graph — the same import
+discipline as the staleness broadcaster above.
+*/
+amendBroadcastSlot.resolver = () => broadcastAmend
+
 /* One process-wide fallback list for reads with no request in flight (boot/cron/socket) —
    real requests each carry their own `pendingAsyncCells`, so the SSR barrier drains a
    per-request list and concurrent renders never cross-contaminate. */
@@ -99,6 +110,10 @@ const sharedResolvedCells = { entries: [] }
 resolvedCellsSlot.resolver = () => requestContext.getStore()?.resolvedCells ?? sharedResolvedCells
 const sharedStreamedCells = { entries: [] }
 streamedCellsSlot.resolver = () => requestContext.getStore()?.streamedCells ?? sharedStreamedCells
+/* No shared fallback: `defineSocket.peek` records into this on every retained-frame read, including
+   reads outside any request (ws handlers, boot) — a fallback list would accumulate entries no render
+   ever drains. Off-request this resolves undefined and the record is skipped (see socketTailsSlot). */
+socketTailsSlot.resolver = () => requestContext.getStore()?.socketTails
 const sharedDocSnapshots = { entries: [] }
 docSnapshotsSlot.resolver = () => requestContext.getStore()?.docSnapshots ?? sharedDocSnapshots
 

package/src/lib/shared/patch.ts

@@ -1,41 +0,0 @@
-import { cache } from './cache.ts'
-import type { CacheOptions } from './types/CacheOptions.ts'
-import type { CacheSelector } from './types/CacheSelector.ts'
-import type { RemoteFunction } from './types/RemoteFunction.ts'
-
-/*
-Mutate the retained value of the matching cached read(s) in place — reactive
-(readers re-render), no network. The optimistic-update / real-time primitive:
-patch a cached list from a socket frame (`on(chat, m => getList.patch(l => [...l,
-m]))`) or apply an optimistic edit before a write lands. The updater receives the
-current decoded value and returns the next.
-
-  patch(getFoo, args, updater)   → that exact call
-  patch(getFoo, updater)         → every args-variant of that rpc
-  patch({ tags }, updater)       → every entry sharing a tag
-
-Instance sugar `getFoo.patch(args?, updater)` ≡ `patch(getFoo, args, updater)`.
-The updater is always the last argument; a not-yet-read key has nothing to patch.
-*/
-// @documentation cache
-export function patch<Args, Return>(
-    fn: RemoteFunction<Args, Return> | ((args?: Args) => Promise<Return>),
-    args: Args | undefined,
-    updater: (current: Return) => Return,
-): void
-export function patch<Args, Return>(
-    fn: RemoteFunction<Args, Return> | ((args?: Args) => Promise<Return>),
-    updater: (current: Return) => Return,
-): void
-export function patch<Return>(
-    selector: Pick<CacheOptions, 'tags'>,
-    updater: (current: Return) => Return,
-): void
-export function patch(selector: unknown, argsOrUpdater: unknown, maybeUpdater?: unknown): void {
-    /* Updater is always last: 3 args → (selector, args, updater); 2 args → (selector, updater). */
-    const updater = (maybeUpdater !== undefined ? maybeUpdater : argsOrUpdater) as (
-        current: unknown,
-    ) => unknown
-    const args = maybeUpdater !== undefined ? argsOrUpdater : undefined
-    cache.patch(selector as CacheSelector<unknown, unknown>, args, updater)
-}

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

@@ -1,19 +0,0 @@
-import ts from 'typescript'
-
-/*
-Maps a compound-assignment operator to its plain binary counterpart, for lowering
-`x += y` into an unconditional read-combine-write. Logical assignments
-(`||=`/`&&=`/`??=`) lower the same way — the patch/cell write always fires,
-consistent with how `+=` lowers. Shared by lowerDocAccess (the `$$model` write path)
-and renameSignalRefs (the `$$writeCell` linked-cell path) so the two lowerings can't
-drift.
-*/
-export const COMPOUND_ASSIGNMENT_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],
-    [ts.SyntaxKind.BarBarEqualsToken, ts.SyntaxKind.BarBarToken],
-    [ts.SyntaxKind.AmpersandAmpersandEqualsToken, ts.SyntaxKind.AmpersandAmpersandToken],
-    [ts.SyntaxKind.QuestionQuestionEqualsToken, ts.SyntaxKind.QuestionQuestionToken],
-])