@abide/abide 0.51.0 → 0.53.0

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

@@ -0,0 +1,21 @@
+import { SuspenseSignal } from '../runtime/SuspenseSignal.ts'
+
+/*
+The text a reactive `{expr}` binding writes: the stringified value, or `''` while a blocking
+`await` read is pending — a `SuspenseSignal` (ADR-0042). Nullish stringifies to `''` (never the
+literal `"undefined"`), so a pending streaming read and a suspended blocking read both show nothing.
+A suspending read still tracked its cell before throwing, so the enclosing bind effect re-runs and
+fills in once the value resolves. Rethrows any non-suspense error unchanged.
+*/
+export function readTextOrSuspend(read: () => unknown): string {
+    let next: unknown
+    try {
+        next = read()
+    } catch (signal) {
+        if (!(signal instanceof SuspenseSignal)) {
+            throw signal
+        }
+        return ''
+    }
+    return next == null ? '' : String(next)
+}

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

@@ -5,6 +5,7 @@ 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 type { Boundary } from '../runtime/types/Boundary.ts'
 import type { State } from '../runtime/types/State.ts'
 import { withoutHydration } from '../runtime/withoutHydration.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/dom/writeCell.ts

@@ -0,0 +1,22 @@
+import { isAsyncCell } from '../../shared/isAsyncCell.ts'
+import type { AsyncState } from '../../shared/types/AsyncState.ts'
+
+/*
+Unified write for a `linked` reference the compiler lowers to `$$writeCell(NAME, value)`
+from an author assignment (`draft = x`, `draft += 1`, `draft++`). The read side is
+`$$readCell` — a call, so not an assignable target — which is why an assignment to a
+`linked` binding needs its own lowering. A `linked` cell is a writable `State` for a
+sync seed (write `.value`) or a writable `AsyncState` for an async/stream seed (write
+`.set(value)`, which latches until the next reseed); one write shape covers both, so
+codegen never branches on the seed kind. Returns `value` so the lowered assignment still
+evaluates to the written value in expression position (`a = b = draft = x`).
+*/
+// @documentation plumbing
+export function writeCell(cell: unknown, value: unknown): unknown {
+    if (isAsyncCell(cell)) {
+        ;(cell as AsyncState<unknown>).set(value)
+    } else {
+        ;(cell as { value: unknown }).value = value
+    }
+    return value
+}

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

@@ -0,0 +1,11 @@
+/* The doc-state warm-seed manifest: an SSR-captured reactive-document snapshot, keyed by its
+   scope's serialization-stable render-path id, as a ref-json-encoded STRING (decoded at the read
+   site in `createScope`). `startClient` drains `__SSR__.docs` into here before mount; a hydrating
+   scope reads its key to seed a plain `state(initial)` to the SERVER value instead of the fresh
+   init — a uuid/timestamp/random otherwise diverges from the SSR HTML. Backed by
+   `globalThis.__abideDocs` so an inline pre-bundle script and the framework share one store —
+   whoever runs first creates it, the other adopts the same reference (mirrors CELL_SEED). */
+const globalScope = globalThis as { __abideDocs?: Record<string, string> }
+globalScope.__abideDocs ??= {}
+
+export const DOC_SEED: Record<string, string> = globalScope.__abideDocs

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

@@ -1,5 +1,7 @@
+import { CURRENT_PATH } from './CURRENT_PATH.ts'
 import { claimChild } from './claimChild.ts'
 import type { RENDER } from './RENDER.ts'
+import { reportHydrationDivergence } from './reportHydrationDivergence.ts'
 
 /*
 A hydration claim that MUST succeed. Like `claimChild`, but throws a structural error
@@ -18,8 +20,11 @@ export function claimExpected(
 ): Node {
     const node = claimChild(hydration, parent)
     if (node === null) {
+        /* Name where first on the `hydrate` channel (return ignored — a missing structural node
+           desyncs the claim cursor, so unlike a text miss this can't safely continue) then throw. */
+        reportHydrationDivergence('structure desync', { expected })
         throw new Error(
-            `[abide] hydration desync: expected ${expected} here, but the server DOM had no matching node — SSR markup and the client build disagree on structure at this position.`,
+            `[abide] hydration desync at ${CURRENT_PATH.current || '(root)'}: expected ${expected} here, but the server DOM had no matching node — SSR markup and the client build disagree on structure at this position.`,
         )
     }
     return node

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

@@ -0,0 +1,30 @@
+import { log } from '../../shared/log.ts'
+import type { ChannelLog } from '../../shared/types/ChannelLog.ts'
+import { CURRENT_PATH } from './CURRENT_PATH.ts'
+
+/* The `hydrate` diagnostic channel. `createChannelLog` attaches a live `enabled()` (re-read per
+   call, so toggling `abide-debug` in devtools takes effect without reload) that the public
+   `ChannelLog` type narrows away — reach it here in the one place that needs it. The channel is
+   silent unless DEBUG/`abide-debug` matches `hydrate`. */
+const hydrateChannel = log.channel('hydrate') as ChannelLog & { enabled(): boolean }
+
+/*
+Reports an SSR↔client hydration divergence on the DEBUG-gated `hydrate` channel, tagged with the
+ambient render-path of the enclosing component/branch/row (`CURRENT_PATH` is coarse — it does not
+descend to the individual node/attribute, so the path locates the component, the detail names the
+value). Returns whether the caller should STILL THROW: with the channel off it returns `true`, so
+the caller's hard throw stays the default and a real desync fails loudly; with the channel on it
+warns and returns `false`, so the caller can keep hydrating and one reload surfaces EVERY
+divergence instead of aborting at the first. Structural callers ignore the return (continuing past
+a missing node desyncs the claim cursor) and throw regardless — the warn just names where first.
+*/
+export function reportHydrationDivergence(
+    summary: string,
+    detail: Record<string, unknown>,
+): boolean {
+    if (!hydrateChannel.enabled()) {
+        return true
+    }
+    hydrateChannel.warn(`${summary} at ${CURRENT_PATH.current || '(root)'}`, detail)
+    return false
+}

package/src/lib/ui/startClient.ts

@@ -1,3 +1,5 @@
+import { applyCacheStalenessLocally } from '../shared/applyCacheStalenessLocally.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'
@@ -8,9 +10,11 @@ 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 { seedBootState } from './seedBootState.ts'
 import { seedStreamedResolution } from './seedStreamedResolution.ts'
+import { subscribeCacheStaleness } from './subscribeCacheStaleness.ts'
 
 /*
 The official abide-ui client entry. Reads the server's `window.__SSR__` payload,
@@ -49,6 +53,10 @@ export function startClient(
     cacheStoreSlot.resolver = () => store
     /* One tab store: cache(fn, { shared: true }) shares it, so shared is a no-op here. */
     sharedCacheStoreSlot.resolver = () => store
+    /* invalidate()/refresh() apply to THIS tab's cache (the server entry installs a
+       broadcaster instead — the ADR-0041 side-swap). Same function as the slot fallback so
+       the local-apply path can't diverge. */
+    cacheStalenessSlot.resolver = () => applyCacheStalenessLocally
     /* 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
@@ -66,6 +74,12 @@ export function startClient(
     if (ssr.cells !== undefined) {
         Object.assign(CELL_SEED, ssr.cells)
     }
+    /* Seed the doc-state warm partition into DOC_SEED before mount: a hydrating `createScope` reads
+       its render-path key to adopt the SSR doc snapshot, so a plain `state(initial)` keeps the server
+       value (the consume-once swap in `scope.replace`) instead of re-running a divergent init. */
+    if (ssr.docs !== undefined) {
+        Object.assign(DOC_SEED, 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
@@ -74,5 +88,12 @@ export function startClient(
     ;(globalThis as { __abideResolve?: (resolution: StreamedResolution) => void }).__abideResolve =
         seedStreamedResolution
 
-    return router(target, routes, layoutRoutes, probeNavigation)
+    /* Subscribe to the reserved cache-staleness pipe (ADR-0041) AFTER seeding, so a server
+       broadcast drops/refetches this tab's freshly-hydrated cache — live-only, never replay. */
+    const disposeStaleness = subscribeCacheStaleness()
+    const disposeRouter = router(target, routes, layoutRoutes, probeNavigation)
+    return () => {
+        disposeStaleness()
+        disposeRouter()
+    }
 }

package/src/lib/ui/subscribeCacheStaleness.ts

@@ -0,0 +1,85 @@
+import { abideLog } from '../shared/abideLog.ts'
+import { CACHE_STALENESS_SOCKET } from '../shared/CACHE_STALENESS_SOCKET.ts'
+import { cache } from '../shared/cache.ts'
+import { matcherFromEnvelope } from '../shared/matcherFromEnvelope.ts'
+import { SocketDisconnectedError } from '../shared/SocketDisconnectedError.ts'
+import type { CacheStalenessFrame } from '../shared/types/CacheStalenessFrame.ts'
+import type { Socket } from '../shared/types/Socket.ts'
+import { socketProxy } from './socketProxy.ts'
+
+/*
+The client half of the cross-client staleness broadcast (ADR-0041): every tab
+subscribes to the reserved __abide/cache socket at boot and applies each frame to
+its own cache. A frame rebuilds the entry predicate via matcherFromEnvelope and
+drives the SAME store loop a local invalidate()/refresh() does
+(cache.invalidateMatching / cache.refreshMatching), so wire-driven and local applies
+can't diverge.
+
+LIVE-ONLY, never replay: bare iteration (replay 0) on both boot and reconnect — a
+client applies only frames published while it is connected. The reserved topic keeps
+no tail, so there is nothing to catch up on; a client offline when a frame was
+published misses it and falls back to SWR staleness. Applies are idempotent, so
+correctness has no dependency on frame ordering.
+
+No-op on the server (no window): the broadcast is the server's job, not something it
+consumes. Returns a disposer that stops the loop and closes the subscription.
+*/
+export function subscribeCacheStaleness(injectedSocket?: Socket<CacheStalenessFrame>): () => void {
+    if (typeof window === 'undefined') {
+        return () => undefined
+    }
+    /* Default to the browser channel proxy; tests inject a socket over their own channel. */
+    const socket = injectedSocket ?? socketProxy<CacheStalenessFrame>(CACHE_STALENESS_SOCKET)
+    const controller = new AbortController()
+    /* `let`: a reconnect swaps in a fresh live iterator after a transport loss. */
+    let iterator = socket[Symbol.asyncIterator]()
+    ;(async () => {
+        while (!controller.signal.aborted) {
+            let next: IteratorResult<CacheStalenessFrame>
+            try {
+                next = await iterator.next()
+            } catch (error) {
+                if (controller.signal.aborted) {
+                    return
+                }
+                /* Transport loss: re-open a fresh LIVE subscription (no replay) and keep going. */
+                if (error instanceof SocketDisconnectedError) {
+                    iterator = socket[Symbol.asyncIterator]()
+                    continue
+                }
+                abideLog.error(error)
+                return
+            }
+            if (controller.signal.aborted || next.done === true) {
+                return
+            }
+            /* One malformed frame must not tear down the live pipe: a throw from decode/apply
+               is logged and swallowed so every subsequent frame still delivers. Frames come
+               only from the trusted server (clientPublish is false), so this is defense in
+               depth, not an expected path. */
+            try {
+                applyFrame(next.value)
+            } catch (error) {
+                abideLog.error(error)
+            }
+        }
+    })()
+    return () => {
+        controller.abort()
+        iterator.return?.(undefined)?.catch(() => undefined)
+    }
+}
+
+/* Applies one decoded frame to this tab's cache via the shared apply-by-matcher seam. */
+function applyFrame(frame: CacheStalenessFrame): void {
+    const matches = matcherFromEnvelope(frame)
+    /* The tripwire label + the rpc-error-registry prefix, mirroring what a local selector
+       derives: a tag frame has no key prefix to clear. */
+    const label = frame.mode === 'tags' ? `tags: ${frame.tags.join(', ')}` : frame.match
+    const prefix = frame.mode === 'tags' ? undefined : frame.match
+    if (frame.op === 'invalidate') {
+        cache.invalidateMatching(matches, label, prefix)
+    } else {
+        cache.refreshMatching(matches, label, prefix)
+    }
+}

package/src/lib/ui/watch.ts

@@ -3,6 +3,7 @@ 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'
@@ -61,9 +62,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) {

package/src/serverEntry.ts

@@ -26,11 +26,14 @@ 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 { 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 { cacheStalenessSlot } from './lib/shared/cacheStalenessSlot.ts'
 import { cacheStoreSlot } from './lib/shared/cacheStoreSlot.ts'
 import { createCacheStore } from './lib/shared/createCacheStore.ts'
+import { docSnapshotsSlot } from './lib/shared/docSnapshotsSlot.ts'
 import { loadEnvFromDataDir } from './lib/shared/loadEnvFromDataDir.ts'
 import { pageSlot } from './lib/shared/pageSlot.ts'
 import { pendingAsyncCellsSlot } from './lib/shared/pendingAsyncCellsSlot.ts'
@@ -79,6 +82,13 @@ sharedCacheStoreSlot.resolver = () => sharedCacheStore
 
 cacheStoreSlot.resolver = () => requestContext.getStore()?.cache ?? sharedCacheStore
 
+/*
+Server-side invalidate()/refresh() broadcast to every connected client instead of
+mutating a throwaway request store (ADR-0041). The broadcaster is imported ONLY here
+so its server socket code never enters the client reachability graph.
+*/
+cacheStalenessSlot.resolver = () => broadcastCacheStaleness
+
 /* 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. */
@@ -89,6 +99,8 @@ const sharedResolvedCells = { entries: [] }
 resolvedCellsSlot.resolver = () => requestContext.getStore()?.resolvedCells ?? sharedResolvedCells
 const sharedStreamedCells = { entries: [] }
 streamedCellsSlot.resolver = () => requestContext.getStore()?.streamedCells ?? sharedStreamedCells
+const sharedDocSnapshots = { entries: [] }
+docSnapshotsSlot.resolver = () => requestContext.getStore()?.docSnapshots ?? sharedDocSnapshots
 
 pageSlot.resolver = resolvePageSnapshot