@abide/abide 0.44.1 → 0.45.0

package/src/lib/shared/cache.ts

@@ -12,6 +12,7 @@ import { keyForRemoteCall } from './keyForRemoteCall.ts'
 import { producerKey } from './producerKey.ts'
 import { REMOTE_FUNCTION } from './REMOTE_FUNCTION.ts'
 import { REPLAYABLE_METHODS } from './REPLAYABLE_METHODS.ts'
+import { recordCacheKey } from './recordCacheKey.ts'
 import { SocketDisconnectedError } from './SocketDisconnectedError.ts'
 import { selectorMatcher } from './selectorMatcher.ts'
 import { selectorPrefix } from './selectorPrefix.ts'
@@ -198,8 +199,22 @@ export function cache<Args, Return>(
         reader of the key, so one mutating it would corrupt the others. A live
         fetch hands each reader a fresh object; cloning keeps warm reads the same.
         */
-        if (!isRaw && existing?.value !== undefined) {
-            return Promise.resolve(cloneWarmValue(existing.value)) as Promise<Return>
+        if (
+            !isRaw &&
+            existing !== undefined &&
+            (existing.value !== undefined || existing.warm !== undefined)
+        ) {
+            /* A deferred seed carries a lazy materializer instead of a decoded value: decode
+               it here, on the first read that needs it (off the hydration path), and cache the
+               result onto the entry so later reads skip the decode. Drop the materializer once
+               used — its closure pins the raw body string, so keeping it alongside the decoded
+               value would double memory for exactly the large payloads deferral targets. */
+            const warmValue = existing.value !== undefined ? existing.value : existing.warm?.()
+            existing.value = warmValue
+            existing.warm = undefined
+            const warmed = Promise.resolve(cloneWarmValue(warmValue)) as Promise<Return>
+            recordCacheKey(warmed, key)
+            return warmed
         }
         const responsePromise = invokeRemote(
             store,
@@ -209,7 +224,14 @@ export function cache<Args, Return>(
             args,
             options,
         )
-        return isRaw ? responsePromise : (responsePromise.then(decodeResponse) as Promise<Return>)
+        if (isRaw) {
+            return responsePromise
+        }
+        /* Tag the decoded value promise with its key so the SSR resume path can recognise a
+           cache-backed await value and defer a large one to a `{ defer, key }` marker. */
+        const decoded = responsePromise.then(decodeResponse) as Promise<Return>
+        recordCacheKey(decoded, key)
+        return decoded
     }
     /* Non-enumerable brand; selectorMatcher and the re-wrap guard read it. */
     Object.defineProperty(read, CACHE_WRAPPED, { value: fn })
@@ -812,7 +834,7 @@ function settleRefetchFailure(store: CacheStore, entry: CacheEntry, status?: num
 }
 
 /* Folds new tags into an entry's existing set without duplicating them. */
-function mergeTags(existing: Set<string> | undefined, incoming: string | string[]): Set<string> {
+function mergeTags(existing: Set<string> | undefined, incoming: string[]): Set<string> {
     return new Set([...(existing ?? []), ...toTagSet(incoming)])
 }
 

package/src/lib/shared/cacheEntryFromSnapshot.ts

@@ -19,18 +19,38 @@ export function cacheEntryFromSnapshot(entry: CacheSnapshotEntry): CacheEntry {
         statusText: entry.statusText,
         headers,
     })
+    /* Deferred seed: decode nothing now — hand back a memoized materializer the first read
+       invokes, so hydration pays no payload decode. Eager seed: decode up front as before. */
+    const warm = entry.lazy
+        ? memoizeWarm(() => warmValueFromSnapshot(entry.status, headers, entry.body))
+        : undefined
     return {
         key: entry.key,
         promise: Promise.resolve(response),
         request: new Request(entry.url, { method: entry.method }),
         ttl: undefined,
         expiresAt: undefined,
-        value: warmValueFromSnapshot(entry.status, headers, entry.body),
+        value: entry.lazy ? undefined : warmValueFromSnapshot(entry.status, headers, entry.body),
+        warm,
         settled: true,
         hydrated: true,
     }
 }
 
+/* Wraps a warm decode so it runs at most once — the materialized value (including a
+   legitimate undefined for a non-warmable status) is cached after the first call. */
+function memoizeWarm(decode: () => unknown): () => unknown {
+    let materialized = false
+    let value: unknown
+    return () => {
+        if (!materialized) {
+            value = decode()
+            materialized = true
+        }
+        return value
+    }
+}
+
 /*
 Synchronously decodes a snapshot body so the warm entry reads without a
 microtask hop on first render. The json/text branches go through the shared

package/src/lib/shared/cacheKeyOf.ts

@@ -0,0 +1,7 @@
+import { cacheKeyStore } from './cacheKeyStore.ts'
+
+/* The store key behind a cache() read's promise, or undefined if it carries none
+   (a producer read, a raw Response read, or a non-cache promise). */
+export function cacheKeyOf(promise: Promise<unknown>): string | undefined {
+    return cacheKeyStore.get(promise)
+}

package/src/lib/shared/cacheKeyStore.ts

@@ -0,0 +1,8 @@
+/*
+WeakMap recording the cache key behind a `cache()` read's returned promise, so a
+consumer holding only the promise can recover its key. Mirrors remoteMetaStore (which
+records the synthesized Request the same way). The SSR resume path uses it to decide
+whether a `{#await cache()}` value is a large cache-backed read it can defer — shipping a
+`{ defer, key }` marker instead of the value. Collected with the promise.
+*/
+export const cacheKeyStore = new WeakMap<Promise<unknown>, string>()

package/src/lib/shared/httpErrorFor.ts

@@ -4,7 +4,7 @@ import { HttpError } from './HttpError.ts'
 
 /*
 Builds the HttpError for a non-2xx response, parsing a typed-error body
-(`{ $abideError, data }`, emitted by `error(errors.x(...))` and validation 422)
+(`{ $abideError, data }`, emitted by an `error.typed(...)` constructor and validation 422)
 onto `.kind` / `.data`. Reads a clone so the original `response.body` stays
 unread for callers that inspect it. A non-JSON or malformed body leaves
 `.kind` / `.data` undefined (a plain `error(status, text)`). Shared by the

package/src/lib/shared/recordCacheKey.ts

@@ -0,0 +1,6 @@
+import { cacheKeyStore } from './cacheKeyStore.ts'
+
+/* Tags a cache() read's returned promise with its store key (see cacheKeyStore). */
+export function recordCacheKey(promise: Promise<unknown>, key: string): void {
+    cacheKeyStore.set(promise, key)
+}

package/src/lib/shared/toTagSet.ts

@@ -1,4 +1,4 @@
-/* Normalizes a tags option (one tag or many) to a Set for O(1) membership. */
-export function toTagSet(tags: string | string[]): Set<string> {
-    return new Set(typeof tags === 'string' ? [tags] : tags)
+/* Normalizes a tags option to a Set for O(1) membership. */
+export function toTagSet(tags: string[]): Set<string> {
+    return new Set(tags)
 }

package/src/lib/shared/types/CacheEntry.ts

@@ -59,9 +59,24 @@ export type CacheEntry = {
     ttl: number | undefined
     expiresAt: number | undefined
     value?: unknown
+    /*
+    Lazy warm materializer (Tier 2 deferred seed): a memoized thunk that decodes the
+    shipped body into the warm value on first call, so a deferred snapshot pays no decode
+    at hydration — only when a read actually needs the value. `value` stays undefined until
+    then; the read gate treats an entry with `warm` set as warm without invoking it. Eager
+    snapshots set `value` and leave this undefined.
+    */
+    warm?: () => unknown
     tags?: Set<string>
     settled?: boolean
     hydrated?: boolean
+    /*
+    Marks that the SSR resume path deferred this entry's `{#await cache()}` value — shipped a
+    `{ defer, key }` marker instead of inlining it. The post-stream snapshot drain reads it to
+    ship the body as a LAZY seed (decoded on first read, not at hydration). Set server-side
+    only, on the request-scoped entry, during the stream.
+    */
+    deferred?: boolean
     refreshing?: boolean
     invalidation?: InvalidationState
 }

package/src/lib/shared/types/CacheOptions.ts

@@ -6,10 +6,10 @@ milliseconds-past-resolve that the entry stays live: omitted = forever, 0 =
 dedupe only (entry dropped once the promise settles — the mutation idiom:
 in-flight coalescing and pending() visibility, nothing retained), any other
 number = TTL.
-`tags` is one or more free-form labels grouping unrelated calls so one
-`cache.invalidate({ tags })` drops every entry sharing any of them — pass an
-array when a call belongs to multiple invalidation groups. A unique tag (e.g. a
-uuid) shared by a set of calls gives them their own private invalidation group.
+`tags` is an array of free-form labels grouping unrelated calls so one
+`cache.invalidate({ tags })` drops every entry sharing any of them — list
+multiple when a call belongs to multiple invalidation groups. A unique tag (e.g.
+a uuid) shared by a set of calls gives them their own private invalidation group.
 
 `global` opts the entry into the process-level store instead of the default
 request-scoped one (server) — so a value computed in one request is reused by
@@ -37,7 +37,7 @@ uncheckable — set `swr` only on a producer that is a pure read.
 */
 export type CacheOptions = {
     ttl?: number
-    tags?: string | string[]
+    tags?: string[]
     global?: boolean
     swr?: boolean | { throttle?: number; debounce?: number }
 }

package/src/lib/shared/types/CacheSnapshotEntry.ts

@@ -14,4 +14,9 @@ export type CacheSnapshotEntry = {
     statusText: string
     headers: Array<[string, string]>
     body: string
+    /* Deferred seed (Tier 2): the client stores the body but does NOT decode it at boot —
+       the warm value is materialized lazily on the first read, off the hydration path. Set
+       by the server for a deferred `{#await cache()}` whose value ships via a `{defer,key}`
+       resume marker instead of inline, so hydration touches neither copy's decode. */
+    lazy?: boolean
 }

package/src/lib/shared/types/ErrorSpec.ts

@@ -1,11 +1,11 @@
 import type { StandardSchemaV1 } from './StandardSchemaV1.ts'
 
 /*
-A rpc's declared error set, keyed by error NAME (not status, so two errors can
-share a status). Each entry names its HTTP `status` and an optional `data`
-schema whose inferred input the error constructor requires. Passed as the rpc's
-`errors` opt; the client derives a typed `Result` union from it (see
-`RpcErrorUnion`), and the handler receives matching constructors (see
-`ErrorConstructors`).
+A rpc's error set, keyed by error NAME (not status, so two errors can share a
+status). Each entry names its HTTP `status` and an optional `data` schema whose
+inferred input the error constructor requires. Built at the type level from the
+`error.typed(...)` constructors a handler RETURNS (see `TypedError` +
+`InferredErrors` in RpcHelper); the client's `rpc.isError` narrows `.kind` /
+`.data` off it (see `RpcErrorGuard`).
 */
 export type ErrorSpec = Record<string, { status: number; data?: StandardSchemaV1 }>

package/src/lib/shared/types/RemoteFunction.ts

@@ -43,6 +43,7 @@ export type RemoteFunction<
     Args,
     Return,
     Errors extends ErrorSpec = Record<never, never>,
+    Durable extends boolean = false,
 > = RemoteCallable<Args, Return> & {
     readonly method: HttpMethod
     readonly url: string
@@ -56,7 +57,10 @@ export type RemoteFunction<
        per-rpc replacement for a global guard, since the error name → data type mapping
        lives in the rpc's own spec. */
     readonly isError: RpcErrorGuard<Errors>
-    /* Present only on a durable (`outbox`) RPC's client proxy: callable for the reactive
-       list of undelivered entries, with `retry()` to drain the queue. Undefined otherwise. */
-    readonly outbox?: Outbox<Args>
-}
+} /* `outbox` presence follows the `outbox: true` opt: the mutating helper threads `Durable`
+     into the return type so a DURABLE rpc's `.outbox` is the required queue face (no optional
+     chain). A non-durable rpc keeps it optional — assignable to a durable one everywhere a
+     bare `RemoteFunction<Args, Return>` slot (cache selectors, registries) is expected, since
+     required→optional widens cleanly and no call site had to learn the `Durable` bit. */ & (Durable extends true
+        ? { readonly outbox: Outbox<Args> }
+        : { readonly outbox?: Outbox<Args> })

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

@@ -35,6 +35,7 @@ export const UI_RUNTIME_IMPORTS: { name: string; specifier: string; alias?: stri
     { name: 'eachAsync', specifier: 'ui/dom/eachAsync', alias: '$$eachAsync' },
     { name: 'when', specifier: 'ui/dom/when', alias: '$$when' },
     { name: 'awaitBlock', specifier: 'ui/dom/awaitBlock', alias: '$$awaitBlock' },
+    { name: 'deferResume', specifier: 'ui/deferResume', alias: '$$deferResume' },
     { name: 'tryBlock', specifier: 'ui/dom/tryBlock', alias: '$$tryBlock' },
     { name: 'switchBlock', specifier: 'ui/dom/switchBlock', alias: '$$switchBlock' },
     { name: 'mountSlot', specifier: 'ui/dom/mountSlot', alias: '$$mountSlot' },

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

@@ -527,10 +527,15 @@ export function generateSSR(
            `withBindings` shadow models, so a reference to the binding reads the plain
            local rather than the (unresolved) component signal it shadows. */
         const resolved = nextVar('$av')
+        /* Keep the promise object: a cache() read tagged it with its store key, which
+           `$$deferResume` reads to defer a cache-backed value (ship a `{defer,key}` marker +
+           lazy seed) instead of inlining it — the blocking form's contract. */
+        const promiseVar = nextVar('$ap')
         let code = `const ${id} = $ctx.next++;\n`
         code += `${target}.push("<!--abide:await:" + ${id} + "-->");\n`
         code += `try {\n`
-        code += `const ${resolved} = await (${lowerExpression(node.promise)});\n`
+        code += `const ${promiseVar} = (${lowerExpression(node.promise)});\n`
+        code += `const ${resolved} = await ${promiseVar};\n`
         code += `{\n`
         code += `const ${plan.resolvedAs} = ${resolved};\n`
         code += withBindings(withShadow, plan.resolvedBindings, ssrBindingKind, () =>
@@ -540,7 +545,7 @@ export function generateSSR(
            shadow — matching the catch branch below, so a finally expression naming the
            same identifier as the `then` binding reads the component signal, not the local. */
         code += branchContent(plan.finallyChildren, target)
-        code += `$resume[${id}] = { ok: true, value: ${plan.resolvedAs} };\n`
+        code += `$resume[${id}] = $$deferResume(${promiseVar}, ${plan.resolvedAs});\n`
         code += `}\n`
         if (plan.surfaceRejection) {
             /* No catch/finally → let the rejection surface instead of an empty branch. */
@@ -564,7 +569,9 @@ export function generateSSR(
        `await` block inside the branch composes. `finally` appends after the outcome,
        matching the client's concatenated node range. Neither catch nor finally → omit
        `catch` so a rejection surfaces (renderToStream re-throws); a finally-only block
-       keeps a catch renderer that renders just finally. */
+       keeps a catch renderer that renders just finally. A cache-backed streaming value is
+       DEFERRED at settle time (renderToStream ships a `{defer,key}` marker + lazy body, the
+       client adopts the streamed branch inert) — the machinery here is unchanged. */
     function generateStreamingAwait(
         node: Extract<TemplateNode, { kind: 'await' }>,
         target: string,

package/src/lib/ui/createScope.ts

@@ -5,6 +5,7 @@ import { linked } from './linked.ts'
 import { persist as persistDoc } from './persist.ts'
 import { createDoc } from './runtime/createDoc.ts'
 import { liveScopes } from './runtime/liveScopes.ts'
+import type { Cell } from './runtime/types/Cell.ts'
 import type { Doc } from './runtime/types/Doc.ts'
 import { state } from './state.ts'
 import { sync } from './sync.ts'
@@ -49,7 +50,11 @@ export function createScope(
     let persistence: PersistHandle | undefined
     let unsync: (() => void) | undefined
 
-    const self: Scope = {
+    /* `cell` is not on the public `Scope` type — it is the compiler-only leaf the
+       cell-hoisting lowering targets (`const _cell0 = $$scope().cell("path")`, see
+       `hoistCells`). It stays on the runtime object but off the documented surface,
+       so authors reach data through `read`/`replace`/`derive`, not a raw cell handle. */
+    const self: Scope & { cell: <T>(path: string) => Cell<T> } = {
         id,
         label,
         parent,
@@ -79,7 +84,7 @@ export function createScope(
         },
         root: () => (parent === undefined ? self : parent.root()),
         /* Reference store — no tracking, so a lookup never subscribes; reactivity comes
-           from what is shared (a cell/scope), not from the share. */
+           from what is shared (a scope, whose doc is reactive), not from the share. */
         share: (key, value) => {
             shared.set(key, value)
         },
@@ -109,8 +114,10 @@ export function createScope(
                 owned[index]?.()
             }
             owned.length = 0
-            for (const created of children) {
-                created.dispose()
+            /* Children reverse too (last created first), so a later child that captured an
+               earlier sibling tears down before the sibling it depends on — LIFO like `owned`. */
+            for (let index = children.length - 1; index >= 0; index -= 1) {
+                children[index]?.dispose()
             }
             children.length = 0
             shared.clear()

package/src/lib/ui/deferResume.ts

@@ -0,0 +1,29 @@
+import { activeCacheStore } from '../shared/activeCacheStore.ts'
+import { cacheKeyOf } from '../shared/cacheKeyOf.ts'
+import { snapshotShippable } from '../shared/snapshotShippable.ts'
+import type { DeferMarker, ResumeEntry } from './runtime/RESUME.ts'
+
+/*
+The resume-manifest entry for a blocking `{#await expr then value}`. When the awaited value
+is a shippable cache-backed read, DEFER it: flag the store entry so its SSR snapshot seeds
+lazily (the body is decoded on first read, not at hydration) and return a `{ defer, key }`
+marker in place of the value. Hydration then adopts the server branch inert and decodes
+neither copy — the blocking form's contract: "render it on the server, keep the page, refetch
+only when I read or invalidate it." A non-cache value (a plain promise, a computation) or a
+cache read whose entry can't ship inlines its value as before. Server-only in practice — the
+client codegen never calls it. */
+// @documentation plumbing
+export function deferResume(promise: unknown, value: unknown): ResumeEntry | DeferMarker {
+    const isPromise =
+        promise !== null && typeof (promise as { then?: unknown })?.then === 'function'
+    const key = isPromise ? cacheKeyOf(promise as Promise<unknown>) : undefined
+    if (key === undefined) {
+        return { ok: true, value }
+    }
+    const entry = activeCacheStore().entries.get(key)
+    if (entry === undefined || !snapshotShippable(entry)) {
+        return { ok: true, value }
+    }
+    entry.deferred = true
+    return { defer: true, key }
+}

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

@@ -36,21 +36,36 @@ export function appendText(parent: Node, read: () => unknown, splitAlways = fals
     }
     const hydration = RENDER.hydration
     if (hydration !== undefined) {
-        const node = claimChild(hydration, parent) as unknown as Text
+        const claimed = claimChild(hydration, parent)
         const value = String(read())
+        /* A value that first rendered empty produced NO server text node, so the cursor
+           points at the following node (an element/comment) or past the end (null) — not a
+           text node to claim. Bind to a Text node either way: claim the merged SSR node when
+           one is here, else synthesize an empty one at the cursor and leave the claimed node
+           for the next consumer (a following element hole, a sibling binding, or nothing).
+           Without this the bind effect below derefs a null/element `node`. A text node is
+           detected by `splitText` (not `nodeType`), so the test mini-dom is covered too. */
+        const isText = claimed !== null && typeof (claimed as Text).splitText === 'function'
+        const node = (
+            isText ? claimed : parent.insertBefore(document.createTextNode(''), claimed)
+        ) as Text
         /* Peel this binding's text off the merged SSR node. A non-final binding in a
            run (`splitAlways`) splits even when it consumes the whole node, leaving an
            empty node for the next binding — otherwise an interpolation that renders to
            empty string (or whose followers do) has no node and the next claim grabs the
            wrong sibling. The final binding keeps `<` so it doesn't leave a stray node a
-           following element would claim. */
+           following element would claim. A synthesized node is already this binding's own,
+           so it never splits. */
         if (
-            node !== null &&
+            isText &&
             (splitAlways ? value.length <= node.data.length : value.length < node.data.length)
         ) {
             node.splitText(value.length)
         }
-        hydration.next.set(parent, node === null ? null : node.nextSibling)
+        /* Advance past the claimed text node; for a synthesized node leave the cursor on the
+           still-unclaimed `claimed` node it was inserted before (an element/comment, or null
+           at the end). */
+        hydration.next.set(parent, isText ? node.nextSibling : claimed)
         effect(() => {
             node.data = String(read())
         })

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

@@ -1,9 +1,11 @@
+import { activeCacheStore } from '../../shared/activeCacheStore.ts'
 import { decodeRefJson } from '../../shared/decodeRefJson.ts'
 import { effect } from '../effect.ts'
 import { claimChild } from '../runtime/claimChild.ts'
+import { generationGuard } from '../runtime/generationGuard.ts'
 import { RANGE_CLOSE, RANGE_OPEN } from '../runtime/RANGE_MARKER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
-import type { ResumeEntry } from '../runtime/RESUME.ts'
+import type { DeferMarker, ResumeEntry } from '../runtime/RESUME.ts'
 import { RESUME } from '../runtime/RESUME.ts'
 import { scope } from '../runtime/scope.ts'
 import { scopeGroup } from '../runtime/scopeGroup.ts'
@@ -56,8 +58,11 @@ export function awaitBlock(
     let active: { start: Comment; end: Comment; dispose: () => void } | undefined
     let anchor: Node | undefined
     let first = true
-    /* Bumped each run so a prior run's in-flight promise can't clobber a newer one. */
-    let generation = 0
+    /* Bumped each run so a prior run's in-flight promise can't clobber a newer one, AND on
+       owner teardown so an in-flight promise that settles AFTER the enclosing `{#if}`/
+       `{#for}`/component tears this block out is abandoned — otherwise its settle runs
+       `place` on the block's now-detached anchor and `insertBefore` throws NotFoundError. */
+    const guard = generationGuard()
     /* The resolved value, held as a reactive cell so the then-branch reads it through its
        own effects. A re-run that resolves to a NEW value SETS this cell instead of rebuilding
        the branch — the branch (and any keyed `each` inside it) survives and updates in place,
@@ -120,7 +125,7 @@ export function awaitBlock(
 
     /* Render a settled-or-pending result into the current generation. */
     const render = (result: unknown): void => {
-        const gen = generation
+        const gen = guard.token()
         if (!isThenable(result)) {
             settleThen(result) // warm-sync → resolved now, no flash
             return
@@ -140,12 +145,12 @@ export function awaitBlock(
         }
         result.then(
             (value) => {
-                if (gen === generation) {
+                if (guard.live(gen)) {
                     settleThen(value)
                 }
             },
             (error) => {
-                if (gen === generation) {
+                if (guard.live(gen)) {
                     settleError(error)
                 }
             },
@@ -176,6 +181,42 @@ export function awaitBlock(
         active = { start, end, dispose }
     }
 
+    /* Inert adoption — a deferred `{#await cache()}` (large payload, shipped as a `{defer,key}`
+       resume marker). Adopt the SSR then-branch WITHOUT building its bindings or materializing
+       the awaited value: the server markup is already correct, so keep it verbatim and skip the
+       payload decode entirely (the boot-path cost deferral targets). Only subscribe THIS block's
+       effect to the cache key — reads, decodes and fetches all wait. A later cache.invalidate
+       re-runs the effect, which then reads the value for real and builds a fresh branch. Sound
+       because a display-first read replaces the whole branch on re-read anyway, so there is no
+       extra flash beyond the swap the re-read already performs. */
+    const adoptInert = (open: Node | null, key: string): void => {
+        const cursor = hydration as NonNullable<typeof hydration>
+        const firstKept = open?.nextSibling ?? null
+        /* Scan to THIS block's close marker, leaving every server node in place. Nested
+           blocks carry different ids, so the first data match is our own close. */
+        let node: Node | null = firstKept
+        while (node !== null && (node as { data?: string }).data !== `/abide:await:${id}`) {
+            node = node.nextSibling
+        }
+        const close = node
+        cursor.next.set(parent, close?.nextSibling ?? null)
+        /* Bracket the kept nodes as a `[`…`]` range + park an anchor, identical to `adopt`,
+           so the first re-run's `place`/`detach` evicts them like any other branch. */
+        const start = document.createComment(RANGE_OPEN)
+        parent.insertBefore(start, firstKept ?? close)
+        const end = document.createComment(RANGE_CLOSE)
+        parent.insertBefore(end, close)
+        anchor = document.createTextNode('')
+        parent.insertBefore(anchor, close)
+        /* No scope/effects were built for the kept nodes, so disposal only evicts the range. */
+        active = { start, end, dispose: () => undefined }
+        /* Not 'then' — the first re-run rebuilds the branch fresh via `place`. */
+        activeKind = 'pending'
+        /* Subscribe without a value read: no clone, no decode, no fetch — just the key, so
+           cache.invalidate re-runs this effect (createSubscriber ties it to the running scope). */
+        activeCacheStore().subscribe(key)
+    }
+
     /* Discard the SSR boundary and (re)build the block from the live promise, fresh
        (hydration off) — the recovery path when adoption can't use the server markup. */
     const rebuildCold = (open: Node | null): void => {
@@ -205,21 +246,34 @@ export function awaitBlock(
        didn't round-trip (e.g. a non-serializable Response) throws while building the
        branch — fall back to the live promise, which reads the properly-reconstructed
        warm cache (or re-fetches) instead of crashing hydration. */
-    const firstHydrate = (result: unknown): void => {
+    const firstHydrate = (): void => {
         const cursor = hydration as NonNullable<typeof hydration>
         const open = claimChild(cursor, parent)
         /* RESUME holds the ref-json-encoded entry STRING; decode here, where the codec
            lives. A decode failure (malformed/absent payload) reads as "no resume" — fall
            through to the live promise rather than crash hydration. */
         const raw = RESUME[id]
-        let entry: ResumeEntry | undefined
+        let decoded: ResumeEntry | DeferMarker | undefined
         if (raw !== undefined) {
             try {
-                entry = decodeRefJson(raw) as ResumeEntry
+                decoded = decodeRefJson(raw) as ResumeEntry | DeferMarker
             } catch {
-                entry = undefined
+                decoded = undefined
             }
         }
+        /* A deferred marker ships the cache key, not the value — adopt the server branch inert
+           and skip the decode. Intercept before the ok/catch logic. Object-guard the `in`: a
+           corrupt manifest decoding to a primitive/null must read as "no resume" (fall through),
+           not throw past the decode try/catch and crash hydration. */
+        if (typeof decoded === 'object' && decoded !== null && 'defer' in decoded) {
+            adoptInert(open, decoded.key)
+            return
+        }
+        /* Non-deferred: read the promise now so the block subscribes to its reactive source
+           (a cache key) — warm on resume, so no round-trip — then adopt the resume value /
+           warm-sync result below, or discard and build the pending branch fresh. */
+        const result = promiseThunk()
+        const entry = decoded as ResumeEntry | undefined
         if (entry !== undefined) {
             /* Build the adopted branch around a value CELL (then) so a later re-run updates
                it in place, exactly like a fresh mount. The `throw` for a catch-less rejection
@@ -278,30 +332,24 @@ export function awaitBlock(
     }
 
     effect(() => {
-        generation += 1
-        /* Read the promise EVERY run, including the first hydrate run, so the block
-           subscribes to its reactive source (a cache key). A cache-remote read is warm
-           on resume — it serves the snapshot without a network round-trip, so adoption
-           stays no-flash AND a later cache.invalidate re-runs the block. Without this
-           read a resume-adopted block has no deps and invalidate is a no-op.
-
-           ONLY the promise read is tracked. The warm-sync resolve, the hydration adopt,
-           and the pending render all BUILD the branch through `scope`, which builds
-           untracked — so the branch's own reactive reads don't subscribe THIS effect
-           (otherwise the whole block re-runs and re-suspends on any branch-state change,
-           e.g. a sibling route param updating in place). The branch's own child effects
-           still track normally; the block re-runs only when the promise source does. */
-        const result = promiseThunk()
+        guard.renew()
         if (first) {
             first = false
             if (hydration !== undefined) {
-                firstHydrate(result)
+                /* firstHydrate reads the promise ITSELF, after checking the resume marker: a
+                   deferred block must not invoke promiseThunk (it would materialize/fetch the
+                   value we're deferring) and subscribes by key instead; every other path reads
+                   it so the block subscribes to its reactive source (a cache key). */
+                firstHydrate()
                 return
             }
             anchor = document.createTextNode('')
             parent.insertBefore(anchor, before)
         }
-        render(result)
+        /* Read the promise every subsequent run so an invalidate re-runs the block. ONLY this
+           read is tracked (the branch builds untracked via `scope`), so the block re-runs only
+           when its promise source does, not on any branch-state change. */
+        render(promiseThunk())
     })
 }