@abide/abide 0.44.0 → 0.45.0

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

@@ -5,6 +5,7 @@ import { assertRuntimeHelpersBound } from './assertRuntimeHelpersBound.ts'
 import { assertTranspiles } from './assertTranspiles.ts'
 import { compileComponent } from './compileComponent.ts'
 import { compileSSR } from './compileSSR.ts'
+import type { AnalyzedComponent } from './types/AnalyzedComponent.ts'
 import { UI_RUNTIME_IMPORTS } from './UI_RUNTIME_IMPORTS.ts'
 
 /*
@@ -26,7 +27,7 @@ what the `.abide` bundler loader emits.
 export function compileModule(
     source: string,
     options: { isLayout?: boolean; moduleId?: string; hot?: boolean } = {},
-): string {
+): { code: string; styles: AnalyzedComponent['styles'] } {
     const isLayout = options.isLayout ?? false
     /* Run the shared front-end once and feed it to both back-ends — the analysis is
        pure over (source, moduleId), so the client and SSR builds reuse one parse
@@ -52,7 +53,10 @@ export function compileModule(
                 : `${entry.name}: ${entry.alias}`,
         ).join(', ')
         const id = JSON.stringify(options.moduleId)
-        return `const { ${names}, hotReplace } = window.__abide
+        /* Hot mode never imports the scoped CSS (it reuses the live bundle's sheet), so
+           styles are empty here regardless of the analyzed blocks. */
+        return {
+            code: `const { ${names}, hotReplace } = window.__abide
 ${userImports}
 function build(host, $props) {
 ${body}
@@ -63,7 +67,9 @@ function component(host, $props) {
 component.build = build
 component.__abideId = ${id}
 if (!hotReplace(${id}, component)) location.reload()
-`
+`,
+            styles: [],
+        }
     }
 
     const ssrBody = indent(compileSSR(source, isLayout, options.moduleId, analyzed))
@@ -101,10 +107,24 @@ ${options.moduleId === undefined ? '' : `component.__abideId = ${JSON.stringify(
        string/comment/HTML literal (e.g. an `on`-attribute in static markup) no longer
        forces a spurious import, so no per-surface scoping is needed: a client-only helper
        simply doesn't appear as an identifier in the SSR body. */
-    const referenced = collectIdentifiers(`${userImports}\n${body}\n${ssrBody}\n${moduleBody}`)
-    const importBlock = UI_RUNTIME_IMPORTS.filter((entry) =>
+    /* Parse the generated bodies ONCE and feed the single tree to both AST passes: the
+       dead-import filter (`collectIdentifiers`) and the binding backstop
+       (`assertRuntimeHelpersBound`). The import block isn't in this tree yet — it is derived
+       from the filter's result — so the backstop is told the names that block will bind
+       (`importedHelpers`), which is exactly what it would have read from the prepended imports
+       had it re-parsed the whole module. `setParentNodes` is required by the backstop's
+       `getStart`/line lookups. */
+    const bodySource = ts.createSourceFile(
+        'module.ts',
+        `${userImports}\n${moduleBody}`,
+        ts.ScriptTarget.Latest,
+        /* setParentNodes */ true,
+    )
+    const referenced = collectIdentifiers(bodySource)
+    const keptImports = UI_RUNTIME_IMPORTS.filter((entry) =>
         referenced.has(entry.alias ?? entry.name),
     )
+    const importBlock = keptImports
         .map((entry) => {
             const local =
                 entry.alias === undefined || entry.alias === entry.name
@@ -126,9 +146,15 @@ ${moduleBody}`
     /* `assertTranspiles` only proves the output PARSES — a call to an un-imported helper is
        valid syntax, so it slips through. This second guard proves the output is BOUND: every
        runtime helper it calls is actually imported (an independent check of the dead-import
-       filter above), turning a runtime `ReferenceError` into a located compile error. */
-    assertRuntimeHelpersBound(module, 'component module generation')
-    return module
+       filter above), turning a runtime `ReferenceError` into a located compile error. It walks
+       the SAME tree the filter just parsed, with the kept helper imports supplied as the bound
+       set the prepended import block provides. */
+    assertRuntimeHelpersBound(
+        bodySource,
+        new Set(keptImports.map((entry) => entry.alias ?? entry.name)),
+        'component module generation',
+    )
+    return { code: module, styles: analyzed.styles }
 }
 
 /* Indents a body block for embedding inside a wrapper function. Lines whose start
@@ -170,14 +196,9 @@ function unescapedBacktickCount(line: string): number {
    in a handler — leaves the scanner unable to find the substitution's closing `}` without
    the parser's re-scan, so a token-only pass mis-reads the rest of the module as template
    text and drops every helper referenced after it (an `import`-less `effect`/`mountChild`
-   → a `ReferenceError` at mount → the router's reload fallback → a refresh loop). */
-function collectIdentifiers(code: string): Set<string> {
-    const source = ts.createSourceFile(
-        'module.ts',
-        code,
-        ts.ScriptTarget.Latest,
-        /* setParentNodes */ false,
-    )
+   → a `ReferenceError` at mount → the router's reload fallback → a refresh loop). Takes the
+   already-parsed source so the one tree feeds this pass and the binding backstop both. */
+function collectIdentifiers(source: ts.SourceFile): Set<string> {
     const names = new Set<string>()
     const visit = (node: ts.Node): void => {
         if (ts.isIdentifier(node)) {

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

@@ -97,7 +97,11 @@ export function compileShadow(source: string, propsType = 'Record<string, any>')
     for (const line of scope) {
         builder.flush(line)
     }
-    emitNodes(parseTemplate(source.slice(templateStart), templateStart).nodes, builder)
+    const templateNodes = parseTemplate(source.slice(templateStart), templateStart).nodes
+    /* Nested `<script>` blocks inline into the synchronous `build()` too, so a top-level
+       await in one is the same build-breaker — flag it, mapped via the node's body offset. */
+    collectNestedScriptAwaitDiagnostics(templateNodes, diagnostics)
+    emitNodes(templateNodes, builder)
     builder.raw('}\n')
     return { ...builder.result(), diagnostics }
 }
@@ -214,6 +218,73 @@ function collectReservedNameDiagnostics(
     visit(file)
 }
 
+/* Pushes a diagnostic for every `await` sitting at the script's top level — outside any
+   nested function. The generated `build()` runs the leading script synchronously, so a
+   top-level await transpiles to `await` in a non-async function and breaks the bundle; the
+   shadow's render fn is async, so `tsc` alone never flags it (a check/runtime parity gap).
+   Stops descending at function boundaries — their own async-ness is the author's concern —
+   and catches both `await expr` and `for await (… of …)`, flagging the `await` keyword. */
+function collectTopLevelAwaitDiagnostics(
+    file: ts.SourceFile,
+    scriptStart: number,
+    diagnostics: ShadowDiagnostic[],
+): void {
+    const message =
+        'top-level `await` is not allowed in a `<script>` — the component build runs synchronously. Use `{#await expr}…{:then value}…{/await}` markup for blocking data, or `await` inside an async event handler.'
+    const visit = (node: ts.Node): void => {
+        /* A nested function introduces its own (possibly async) scope; its awaits are legal. */
+        if (
+            ts.isFunctionDeclaration(node) ||
+            ts.isFunctionExpression(node) ||
+            ts.isArrowFunction(node) ||
+            ts.isMethodDeclaration(node) ||
+            ts.isGetAccessorDeclaration(node) ||
+            ts.isSetAccessorDeclaration(node) ||
+            ts.isConstructorDeclaration(node)
+        ) {
+            return
+        }
+        /* The `await` keyword token: the AwaitExpression's first child, or a `for await`'s
+           await modifier. */
+        const keyword = ts.isAwaitExpression(node)
+            ? node.getChildAt(0, file)
+            : ts.isForOfStatement(node)
+              ? node.awaitModifier
+              : undefined
+        if (keyword !== undefined) {
+            diagnostics.push({
+                start: scriptStart + keyword.getStart(file),
+                length: keyword.getEnd() - keyword.getStart(file),
+                message,
+            })
+        }
+        ts.forEachChild(node, visit)
+    }
+    visit(file)
+}
+
+/* Recursively visits every nested `<script>` in the template and flags a top-level await in
+   its body — the same trap as the leading script (it inlines into the sync `build()`), mapped
+   through the node's body offset (`loc`). Walks `children` on every node kind that carries
+   them, so a script buried in an `{#if}`/`{#for}`/`{#await}` branch is still reached. */
+function collectNestedScriptAwaitDiagnostics(
+    nodes: TemplateNode[],
+    diagnostics: ShadowDiagnostic[],
+): void {
+    for (const node of nodes) {
+        if (node === undefined) {
+            continue
+        }
+        if (node.kind === 'script' && node.loc !== undefined) {
+            const file = ts.createSourceFile('nested.ts', node.code, ts.ScriptTarget.Latest, true)
+            collectTopLevelAwaitDiagnostics(file, node.loc, diagnostics)
+        }
+        if ('children' in node) {
+            collectNestedScriptAwaitDiagnostics(node.children, diagnostics)
+        }
+    }
+}
+
 /* Walks the leading `<script>` and produces the shadow's module imports, the
    module-scope type declarations, the value-typed scope lines, and the `props<Shape>()`
    prop shapes. `scriptStart` is the body's absolute offset in the source, so verbatim
@@ -232,6 +303,9 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
        `$$scope`, …), so an author binding may not start with it — that's the contract that
        lets a user freely name a variable after any helper. Flag every such declaration. */
     collectReservedNameDiagnostics(file, scriptStart, diagnostics)
+    /* The leading script runs in the synchronous `build()`, so a top-level await breaks the
+       bundle — catch it here with a legible message instead of an opaque transpile error. */
+    collectTopLevelAwaitDiagnostics(file, scriptStart, diagnostics)
     /* A verbatim span: original text + the segment mapping it back, relative to the
        line start (the caller rebases shadowStart onto the running shadow length). */
     const span = (node: ts.Node, prefixLength: number): ScopeLine['segments'][number] => ({

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

@@ -47,6 +47,21 @@ export function createShadowLanguageService(cwd: string): ShadowLanguageService
     const versions = new Map<string, number>()
     const shadows = new Map<string, CompiledShadow>()
     const parseErrors = new Map<string, string>()
+    /* Memo of `shadowText` output keyed by source path, tagged with the shadow
+       version it was compiled at; a stale tag forces recompilation. `update`/`close`
+       bump that version, so the next read recompiles. */
+    const compiledAt = new Map<string, { version: number; code: string }>()
+    /* Memo of `pagePropsType` (route re-parse) per source path; the path → props
+       type mapping is immutable, so no version tag is needed. */
+    const propsTypes = new Map<string, string | undefined>()
+
+    /* The route props type for a component, parsed once and reused. */
+    const propsTypeOf = (abidePath: string): string | undefined => {
+        if (!propsTypes.has(abidePath)) {
+            propsTypes.set(abidePath, pagePropsType(abidePath))
+        }
+        return propsTypes.get(abidePath)
+    }
 
     /* Ambient declarations for bundler-handled asset imports (`*.css`, …). */
     const assets = assetModulesFile(cwd)
@@ -55,18 +70,29 @@ export function createShadowLanguageService(cwd: string): ShadowLanguageService
         overlays.has(abidePath) || ts.sys.fileExists(abidePath)
 
     /* Compiles (and caches) a component's shadow from its overlay or disk text; a
-       template parse error yields a minimal valid module + a recorded message. */
+       template parse error yields a minimal valid module + a recorded message.
+       Memoised against the shadow's version (bumped by `update`/`close`), so
+       repeated reads at the same version skip the ~700-line compile and the
+       `shadows`/`parseErrors` caches stay current. */
     const shadowText = (abidePath: string): string => {
+        const version = versions.get(suffixed(abidePath)) ?? 0
+        const memo = compiledAt.get(abidePath)
+        if (memo !== undefined && memo.version === version) {
+            return memo.code
+        }
         const source = overlays.get(abidePath) ?? ts.sys.readFile(abidePath) ?? ''
         try {
-            const compiled = compileShadow(source, pagePropsType(abidePath))
+            const compiled = compileShadow(source, propsTypeOf(abidePath))
             shadows.set(abidePath, compiled)
             parseErrors.delete(abidePath)
+            compiledAt.set(abidePath, { version, code: compiled.code })
             return compiled.code
         } catch (error) {
             shadows.set(abidePath, { code: '', mappings: [] })
             parseErrors.set(abidePath, messageFromError(error))
-            return 'export default function (): void {}\n'
+            const code = 'export default function (): void {}\n'
+            compiledAt.set(abidePath, { version, code })
+            return code
         }
     }
 

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

@@ -125,7 +125,13 @@ export function generateBuild(
             (typeof node.attrs)[number],
             {
                 kind:
-                    'expression' | 'interpolated' | 'event' | 'attach' | 'bind' | 'class' | 'style'
+                    | 'expression'
+                    | 'interpolated'
+                    | 'event'
+                    | 'attach'
+                    | 'bind'
+                    | 'class'
+                    | 'style'
             }
         >,
         varName: string,

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/compile/parseTemplate.ts

@@ -615,6 +615,9 @@ export function parseTemplate(source: string, baseOffset = 0): { nodes: Template
            verbatim to its `</script>` (not parsed as markup), scoped by the
            containing branch when compiled. */
         if (tag === 'script' && !selfClosing) {
+            /* Body starts at the current cursor; its absolute source offset lets the shadow
+               map a diagnostic raised inside it (e.g. a top-level await) back to source. */
+            const bodyLoc = baseOffset + cursor
             const close = source.indexOf('</script>', cursor)
             const end = close === -1 ? source.length : close
             const code = source.slice(cursor, end)
@@ -631,7 +634,7 @@ export function parseTemplate(source: string, baseOffset = 0): { nodes: Template
                     "import statements must live in the component's leading <script>, not a nested <template> script — they hoist to module scope for the whole template. For lazy loading, use a dynamic import() inside an effect.",
                 )
             }
-            return { kind: 'script', code }
+            return { kind: 'script', code, loc: bodyLoc }
         }
         /* A capitalised tag is a child component; its attributes become props and
            its children become slot content (rendered where the child puts <slot>). */

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

@@ -12,7 +12,7 @@ positions for the type-checking shadow, ignored by the runtime back-ends.
 */
 export type TemplateNode =
     | { kind: 'text'; parts: TextPart[] }
-    | { kind: 'script'; code: string }
+    | { kind: 'script'; code: string; loc?: number }
     /* A `<style>` declared in the template. `css` is its raw body, read structurally
        so a `<style>` inside an expression isn't mistaken for one. The node stays in
        place: it scopes its sibling subtree, so the front-end derives each scope

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