@abide/abide 0.38.1 → 0.40.0

package/src/lib/ui/installHotBridge.ts

@@ -12,12 +12,17 @@ import { cloneStatic } from './dom/cloneStatic.ts'
 import { each } from './dom/each.ts'
 import { eachAsync } from './dom/eachAsync.ts'
 import { hydrate } from './dom/hydrate.ts'
+import { mergeProps } from './dom/mergeProps.ts'
 import { mount } from './dom/mount.ts'
 import { mountChild } from './dom/mountChild.ts'
 import { mountSlot } from './dom/mountSlot.ts'
 import { on } from './dom/on.ts'
 import { outlet } from './dom/outlet.ts'
+import { readCall } from './dom/readCall.ts'
+import { restProps } from './dom/restProps.ts'
 import { skeleton } from './dom/skeleton.ts'
+import { spreadAttrs } from './dom/spreadAttrs.ts'
+import { spreadProps } from './dom/spreadProps.ts'
 import { switchBlock } from './dom/switchBlock.ts'
 import { tryBlock } from './dom/tryBlock.ts'
 import { when } from './dom/when.ts'
@@ -70,6 +75,11 @@ export function installHotBridge(): void {
         mountSlot,
         outlet,
         mountChild,
+        mergeProps,
+        spreadProps,
+        restProps,
+        spreadAttrs,
+        readCall,
         hydrate,
         escapeKey,
         nextBlockId,

package/src/lib/ui/navigate.ts

@@ -1,6 +1,13 @@
 import { historyEntries } from './runtime/historyEntries.ts'
 import { runtimePath } from './runtime/runtimePath.ts'
 
+/* Options for `navigate`. `replace` swaps the current history entry instead of pushing.
+   `keepScroll` carries the live scroll offset onto the destination so it isn't reset. */
+export type NavigateOptions = {
+    replace?: boolean
+    keepScroll?: boolean
+}
+
 /* Navigates to `path`: writes a history entry (when available) and updates the
    reactive route, which re-mounts the matching page via `router`. `replace` swaps
    the current entry instead of pushing — used when honouring a server redirect, so
@@ -9,16 +16,34 @@ import { runtimePath } from './runtime/runtimePath.ts'
    teardown the rebuild does. A push leaves the current entry behind — its scroll is
    bucketed so back restores it — and mints a fresh id. A replace destroys the current
    entry and lands fresh content (a redirect), so its saved scroll no longer applies:
-   the bucket is discarded and the id kept, so the new page restores to top/anchor. */
+   the bucket is discarded and the id kept, so the new page restores to top/anchor.
+   `keepScroll` opts the destination out of that reset — for an in-page URL swap (e.g.
+   selecting another episode on the same detail page) where a top jump is jarring: the
+   live offset is bucketed under the destination entry id, so the post-rebuild `restore`
+   reapplies it instead of scrolling to top. */
 // @documentation navigate
-export function navigate(path: string, replace = false): void {
+export function navigate(
+    path: string,
+    { replace = false, keepScroll = false }: NavigateOptions = {},
+): void {
     if (typeof history !== 'undefined') {
         if (replace) {
-            historyEntries.discard()
+            /* keepScroll buckets the live offset under the (unchanged) entry id so
+               restore reapplies it; otherwise the superseded content drops its bucket. */
+            if (keepScroll) {
+                historyEntries.save()
+            } else {
+                historyEntries.discard()
+            }
             history.replaceState({ abideEntry: historyEntries.current }, '', path)
         } else {
             historyEntries.save()
             history.pushState({ abideEntry: historyEntries.next() }, '', path)
+            /* Re-bucket the same offset under the freshly minted id so the pushed entry
+               restores to it rather than to top. */
+            if (keepScroll) {
+                historyEntries.save()
+            }
         }
     }
     runtimePath.value = path

package/src/lib/ui/remoteProxy.ts

@@ -1,5 +1,6 @@
 import { browserClientFlags } from '../shared/browserClientFlags.ts'
 import { buildRpcRequest } from '../shared/buildRpcRequest.ts'
+import { cacheManagedSlot } from '../shared/cacheManagedSlot.ts'
 import { createRemoteFunction } from '../shared/createRemoteFunction.ts'
 import { HttpError } from '../shared/HttpError.ts'
 import { OFFLINE_HEADER } from '../shared/OFFLINE_HEADER.ts'
@@ -7,6 +8,7 @@ import { rpcTimeoutSlot } from '../shared/rpcTimeoutSlot.ts'
 import { trace } from '../shared/trace.ts'
 import type { HttpVerb } from '../shared/types/HttpVerb.ts'
 import type { RemoteFunction } from '../shared/types/RemoteFunction.ts'
+import type { RpcOptions } from '../shared/types/RpcOptions.ts'
 import { withBase } from '../shared/withBase.ts'
 import { currentAbortSignal } from './runtime/currentAbortSignal.ts'
 import { REQUEST_SUPERSEDED } from './runtime/REQUEST_SUPERSEDED.ts'
@@ -38,41 +40,51 @@ export function remoteProxy<Args, Return>(
         proxy (/v2/rpc/…); the cache key keeps the bare `url` (keyForRemoteCall
         reads fn.url), so SSR snapshots round-trip base-independently.
         */
-        buildRequest: (args) =>
+        buildRequest: (args, opts) =>
             buildRpcRequest({
                 method,
                 url: withBase(url),
                 args,
                 baseUrl: window.location.href,
-                headers: rpcHeaders(),
+                headers: rpcHeaders(opts?.headers),
             }),
         /*
         Forcing `getRequest()` once builds the Request and seeds the
         cache meta thunk in createRemoteFunction with the same instance,
         so cache() readers don't reconstruct it.
         */
-        invoke: (_args, getRequest) => fetchWithTimeout(getRequest()),
+        invoke: (_args, getRequest, opts) => fetchWithTimeout(getRequest(), opts),
     })
 }
 
 /*
-Fetches under two optional aborts: the reactive scope that fired the call (so a
-superseded/torn-down read cancels its in-flight request — currentAbortSignal) and
-the env-configured client timeout (ABIDE_CLIENT_TIMEOUT, ms). Neither present →
-the unbounded fetch, exactly as before. A timeout surfaces as a 504 HttpError so a
-consumer reads an honest status instead of a raw DOMException → 500. Our scope abort
-(reason REQUEST_SUPERSEDED) is swallowed into a never-settling promise: the reactive
-owner is gone, so the result must neither resolve into a dead tree nor surface as a
-rejection. Other rejections (genuine network failure) propagate untouched.
+Fetches under three optional aborts: the reactive scope that fired the call (so a
+superseded/torn-down read cancels its in-flight request — currentAbortSignal), the
+caller-supplied opts.signal, and the env-configured client timeout
+(ABIDE_CLIENT_TIMEOUT, ms). None present and no transport opts → the unbounded
+fetch, exactly as before. A timeout surfaces as a 504 HttpError so a consumer reads
+an honest status instead of a raw DOMException → 500. Our scope abort (reason
+REQUEST_SUPERSEDED) is swallowed into a never-settling promise: the reactive owner is
+gone, so the result must neither resolve into a dead tree nor surface as a rejection.
+Other rejections (genuine network failure) propagate untouched. The caller's
+keepalive/priority/cache opts pass through to fetch unchanged.
 */
-function fetchWithTimeout(request: Request): Promise<Response> {
+function fetchWithTimeout(request: Request, opts?: RpcOptions): Promise<Response> {
     const timeout = rpcTimeoutSlot.ms
     const timeoutSignal = timeout === undefined ? undefined : AbortSignal.timeout(timeout)
-    const signal = combineSignals(currentAbortSignal(), timeoutSignal)
-    if (signal === undefined) {
+    /*
+    A cache-managed flight is shared across readers (cache() owns its lifetime), so a
+    single caller's signal must not abort it for the others — the same opt-out
+    currentAbortSignal makes for the scope signal. keepalive/priority/cache are
+    harmless to keep there.
+    */
+    const callerSignal = cacheManagedSlot.active ? undefined : (opts?.signal ?? undefined)
+    const signal = combineSignals(currentAbortSignal(), callerSignal, timeoutSignal)
+    const init = fetchInit(signal, opts)
+    if (init === undefined) {
         return fetch(request)
     }
-    return fetch(request, { signal }).catch((error: unknown) => {
+    return fetch(request, init).catch((error: unknown) => {
         if (error === REQUEST_SUPERSEDED) {
             return new Promise<Response>(() => {})
         }
@@ -85,39 +97,59 @@ function fetchWithTimeout(request: Request): Promise<Response> {
     })
 }
 
-/* One AbortSignal from the scope-abort and timeout sources: whichever is present,
-   AbortSignal.any when both, or undefined when neither (the unbounded fetch). */
-function combineSignals(
-    scopeSignal: AbortSignal | undefined,
-    timeoutSignal: AbortSignal | undefined,
-): AbortSignal | undefined {
-    if (scopeSignal === undefined) {
-        return timeoutSignal
+/*
+The fetch init from the merged abort signal plus the caller's transport opts
+(keepalive/priority/cache). headers are deliberately absent — they live on the
+Request built in buildRequest, since fetch(request, { headers }) replaces rather than
+merges. undefined when nothing applies, preserving the allocation-free unbounded
+fetch for the common reactive-free call.
+*/
+function fetchInit(signal: AbortSignal | undefined, opts?: RpcOptions): RequestInit | undefined {
+    const init: RequestInit = {}
+    if (signal !== undefined) {
+        init.signal = signal
+    }
+    if (opts?.keepalive !== undefined) {
+        init.keepalive = opts.keepalive
+    }
+    if (opts?.priority !== undefined) {
+        init.priority = opts.priority
     }
-    if (timeoutSignal === undefined) {
-        return scopeSignal
+    if (opts?.cache !== undefined) {
+        init.cache = opts.cache
+    }
+    return Object.keys(init).length === 0 ? undefined : init
+}
+
+/* One AbortSignal merging the scope abort, the caller signal, and the timeout:
+   AbortSignal.any over those present, the lone one when one, undefined when none
+   (the unbounded fetch). */
+function combineSignals(...signals: Array<AbortSignal | undefined>): AbortSignal | undefined {
+    const present = signals.filter((signal): signal is AbortSignal => signal !== undefined)
+    if (present.length <= 1) {
+        return present[0]
     }
-    return AbortSignal.any([scopeSignal, timeoutSignal])
+    return AbortSignal.any(present)
 }
 
 /*
-abide's per-RPC headers: the page traceparent (continues the server trace) and,
-only while offline, the offline marker so the handler's online() reflects the
-caller's connectivity. Returns undefined when neither applies so the
-allocation-free fetch path stays the common case.
+abide's per-RPC headers, merged onto the caller's opts.headers: the page traceparent
+(continues the server trace) and, only while offline, the offline marker so the
+handler's online() reflects the caller's connectivity. Caller headers go in first and
+the framework's are set last, so a caller adds transport metadata (idempotency-key,
+authorization) but can never overwrite traceparent or the offline marker; content-type
+stays owned by buildRpcRequest. Returns undefined when neither caller nor framework set
+a header, so the allocation-free fetch path stays the common case.
 */
-function rpcHeaders(): Headers | undefined {
-    const headers = new Headers()
-    let any = false
+function rpcHeaders(callerHeaders?: HeadersInit): Headers | undefined {
+    const headers = new Headers(callerHeaders)
     const traceparent = trace()
     if (traceparent) {
         headers.set('traceparent', traceparent)
-        any = true
     }
     /* Presence = offline; absence = online/unknown. navigator.onLine's offline signal is the reliable direction. */
     if (typeof navigator !== 'undefined' && navigator.onLine === false) {
         headers.set(OFFLINE_HEADER, '1')
-        any = true
     }
-    return any ? headers : undefined
+    return headers.keys().next().done ? undefined : headers
 }

package/src/lib/ui/renderChain.ts

@@ -1,6 +1,5 @@
-import { enterRenderPass } from './runtime/enterRenderPass.ts'
-import { exitRenderPass } from './runtime/exitRenderPass.ts'
 import { OUTLET_CLOSE, OUTLET_OPEN } from './runtime/OUTLET_MARKER.ts'
+import type { RenderContext } from './runtime/types/RenderContext.ts'
 import type { SsrRender } from './runtime/types/SsrRender.ts'
 import type { UiComponent } from './runtime/types/UiComponent.ts'
 
@@ -11,48 +10,51 @@ const OUTLET_PLACEHOLDER = `${OPEN}${CLOSE}`
 
 /*
 Server-renders a route's layout chain wrapped around its page into one SsrRender.
-`views` is ordered outermost layout → … → page. The whole chain renders under a
-SINGLE render pass: one outer `enterRenderPass` resets the block-id counter, then
-each `render()` runs nested (depth > 0, no reset), so every `await`/`try` block
-across all layers draws a unique id from the shared counter — in the same
-layer-sequential order the client hydrates them, keeping the streamed fragments and
-the resume manifest aligned.
+`views` is ordered outermost layout → … → page. The whole chain shares ONE request-local
+block-id counter (`$ctx`): each `render()` is awaited sequentially (render is async), so
+every `await`/`try` block across all layers draws a unique id from the shared counter — in
+the same layer-sequential order the client hydrates them, keeping the streamed fragments
+and the resume manifest aligned. Sequential (not `Promise.all`) so the counter advances
+deterministically and the reactive scopes never interleave.
 
 The html nests inner-to-outer: each parent layout's empty outlet boundary
 (`<!--abide:outlet--><!--/abide:outlet-->`) is filled with the accumulated child html —
 no `<abide-outlet>` ELEMENT, so the filled child lays out as a direct child of the
 slot's parent (the router mounts/hydrates it as a marker range, see `outlet`/`fillBoundary`).
 The whole chain is wrapped in a ROOT boundary the router fills into `#app`. Awaits
-concatenate (already uniquely numbered); state merges. A layout missing its `<slot/>` is
-a build error surfaced here.
+concatenate (already uniquely numbered); state and inline blocking `resume` values merge.
+A layout missing its `<slot/>` is a build error surfaced here.
 */
-export function renderChain(views: UiComponent[], params: Record<string, string>): SsrRender {
-    enterRenderPass()
-    try {
-        const renders = views.map((view) => view.render(params))
-        let html = renders[renders.length - 1]?.html ?? ''
-        for (let index = renders.length - 2; index >= 0; index -= 1) {
-            const parent = renders[index] as SsrRender
-            /* EXACTLY one outlet, not at-least-one: `.replace` fills only the first, and
-               the client router fills the LAST `outlet()` call's boundary (`PENDING_OUTLET`),
-               so a second outlet would mount the SSR child and the hydrated child into
-               DIFFERENT slots — a silent desync. Throw at build instead. */
-            if (parent.html.split(OUTLET_PLACEHOLDER).length - 1 !== 1) {
-                throw new Error('[abide] a layout.abide must contain exactly one <slot/> outlet')
-            }
-            /* Fold the child between the outlet markers (function replacement so `$&`/`$\``
-               in the child html insert literally). */
-            const child = html
-            html = parent.html.replace(OUTLET_PLACEHOLDER, () => OPEN + child + CLOSE)
-        }
-        return {
-            /* Root boundary — the router fills `#app` by claiming/creating this same
-               boundary and mounting the outermost layer (or lone page) into it. */
-            html: OPEN + html + CLOSE,
-            awaits: renders.flatMap((render) => render.awaits),
-            state: Object.assign({}, ...renders.map((render) => render.state)),
+export async function renderChain(
+    views: UiComponent[],
+    params: Record<string, string>,
+): Promise<SsrRender> {
+    const ctx: RenderContext = { next: 0 }
+    const renders: SsrRender[] = []
+    for (const view of views) {
+        renders.push(await view.render(params, ctx))
+    }
+    let html = renders[renders.length - 1]?.html ?? ''
+    for (let index = renders.length - 2; index >= 0; index -= 1) {
+        const parent = renders[index] as SsrRender
+        /* EXACTLY one outlet, not at-least-one: `.replace` fills only the first, and
+           the client router fills the LAST `outlet()` call's boundary (`PENDING_OUTLET`),
+           so a second outlet would mount the SSR child and the hydrated child into
+           DIFFERENT slots — a silent desync. Throw at build instead. */
+        if (parent.html.split(OUTLET_PLACEHOLDER).length - 1 !== 1) {
+            throw new Error('[abide] a layout.abide must contain exactly one <slot/> outlet')
         }
-    } finally {
-        exitRenderPass()
+        /* Fold the child between the outlet markers (function replacement so `$&`/`$\``
+           in the child html insert literally). */
+        const child = html
+        html = parent.html.replace(OUTLET_PLACEHOLDER, () => OPEN + child + CLOSE)
+    }
+    return {
+        /* Root boundary — the router fills `#app` by claiming/creating this same
+           boundary and mounting the outermost layer (or lone page) into it. */
+        html: OPEN + html + CLOSE,
+        awaits: renders.flatMap((render) => render.awaits),
+        state: Object.assign({}, ...renders.map((render) => render.state)),
+        resume: Object.assign({}, ...renders.map((render) => render.resume)),
     }
 }

package/src/lib/ui/renderToStream.ts

@@ -1,88 +1,102 @@
+import { resumeSeedScript } from './resumeSeedScript.ts'
 import type { ResumeEntry } from './runtime/RESUME.ts'
 import type { SsrAwait, SsrRender } from './runtime/types/SsrRender.ts'
+import { tryEncodeResume } from './tryEncodeResume.ts'
 
 /*
-Out-of-order SSR streaming. Yields the pending shell first (so the browser paints
-immediately), then one resolved fragment per await block as its promise settles —
-in completion order, not source order, so a slow read never blocks a fast one.
-Each resolved fragment is a `<abide-resolve data-id="ID"><script type="application/json">
-…</script>…</abide-resolve>` that `applyResolved` swaps into the matching
-`<!--abide:await:ID-->` boundary; the leading script holds the JSON-serialized value,
-registered for hydration so an `await` block adopts the resolved branch on resume
-instead of re-running.
+Out-of-order SSR streaming. Yields the shell first (so the browser paints
+immediately), then one resolved fragment per STREAMING await block as its promise
+settles — in completion order, not source order, so a slow read never blocks a fast
+one. Each resolved fragment is a `<abide-resolve data-id="ID"><script
+type="application/json">…</script>…</abide-resolve>` that `applyResolved` swaps into
+the matching `<!--abide:await:ID-->` boundary; the leading script holds the
+JSON-serialized value, registered for hydration so an `await` block adopts the
+resolved branch on resume instead of re-running.
 
 This is the await-block-streams half of the cache rule: a top-level `await` in the
-script would have blocked the shell (inlined), but an await *block* flushes its
-shell now and streams the value when ready. Driven by a plain `render()` result,
+script would have blocked the shell (inlined), but a streaming await *block* flushes
+its shell now and streams the value when ready. Driven by an async `render()` result,
 so it composes with any transport (HTTP chunked, a socket frame, a test).
 
-A `then` on the `await` tag makes the block BLOCKING: it settles before the first
-flush, its resolved branch spliced into its (empty) boundary and its value seeded
-into the resume manifest inline — so the value is in the first paint, no pending
-shell, no swap. The first yield therefore awaits all blocking blocks; only the
-remaining streaming blocks flush out of order after it.
+A `then` on the `await` tag makes the block BLOCKING: it is NOT streamed — it renders
+inline during the async render pass (depth-first, matching the client) and its value
+lands in `render().resume`. The shell already carries the resolved branch, so the
+first yield just seeds those values into the manifest; only streaming blocks flush
+out of order after it.
 */
 // @documentation plumbing
-export async function* renderToStream(render: () => SsrRender): AsyncGenerator<string> {
-    const { html, awaits } = render()
-    /* Blocking awaits (a `then` on the `await` tag) settle BEFORE the first flush:
-       their resolved branch is spliced into its empty boundary and its value registered
-       inline, so the first paint already has the value — no pending, no swap. */
-    const blocking = awaits.filter((block) => block.blocking === true)
-    let shell = html
-    const resumed: Record<number, ResumeEntry> = {}
-    for (const settled of await Promise.all(blocking.map(settle))) {
-        shell = spliceResolved(shell, settled.id, settled.html)
-        resumed[settled.id] = settled.resume
+export async function* renderToStream(
+    render: () => SsrRender | Promise<SsrRender>,
+): AsyncGenerator<string> {
+    const { html, awaits, resume } = await render()
+    /* The shell already contains every blocking await's resolved branch (rendered
+       inline); seed their values so hydration adopts them without a refetch. */
+    yield html + resumeSeedScript(resume)
+    /* A BLOCKING await nested inside a streaming branch renders inline during `settle`
+       (after the seed above), writing its value onto this same `$resume` object — so the
+       initial seed misses it. Track which resume ids are already seeded and emit the delta
+       alongside each streamed fragment, so the client adopts the nested blocking branch
+       instead of refetching. (`resume` is the render body's live object, so late writes
+       appear here.) */
+    const seededResume = new Set<number>(Object.keys(resume).map(Number))
+    const resumeDelta = (): Record<number, ResumeEntry> => {
+        const delta: Record<number, ResumeEntry> = {}
+        for (const [key, entry] of Object.entries(resume)) {
+            const id = Number(key)
+            if (!seededResume.has(id)) {
+                seededResume.add(id)
+                delta[id] = entry
+            }
+        }
+        return delta
     }
-    yield shell + resumeScript(resumed)
-    /* Streaming awaits flush their resolved fragment out of order as each settles. */
+    /* Streaming awaits flush their resolved fragment out of order as each settles. A
+       streaming block's async resolved/error renderer may itself register NESTED streaming
+       awaits — its `branchContent` runs `$awaits.push(...)` onto this same `awaits` array
+       during `settle`, AFTER the initial scan. So re-scan for newly-appended blocks after
+       every settle (tracking which ids are already enqueued), composing to any depth. */
     const inflight = new Map<number, Promise<Settled>>()
-    for (const block of awaits) {
-        if (block.blocking !== true) {
-            inflight.set(block.id, settle(block))
+    const enqueued = new Set<number>()
+    const enqueueNew = (): void => {
+        for (const block of awaits) {
+            if (!enqueued.has(block.id)) {
+                enqueued.add(block.id)
+                inflight.set(block.id, settle(block))
+            }
         }
     }
+    enqueueNew()
     while (inflight.size > 0) {
         const resolved = await Promise.race(inflight.values())
         inflight.delete(resolved.id)
-        const resume = encodeResume(resolved.resume)
-        yield `<abide-resolve data-id="${resolved.id}">` +
-            `<script type="application/json">${resume}</script>` +
+        enqueueNew()
+        /* An unserializable value (e.g. a cyclic media tree) streams its rendered HTML
+           with NO seed script: both swap consumers (SSR_SWAP_SCRIPT, applyResolved) skip
+           registration when the leading child isn't a parseable script, so hydration
+           re-runs this one branch's promise — degrading to a refetch instead of aborting
+           the whole stream. */
+        const encoded = encodeStreamResume(resolved.resume, resolved.id)
+        yield resumeSeedScript(resumeDelta()) +
+            `<abide-resolve data-id="${resolved.id}">` +
+            (encoded === undefined ? '' : `<script type="application/json">${encoded}</script>`) +
             `${resolved.html}</abide-resolve>`
     }
 }
 
-/* Inserts a blocking await's resolved markup into its (empty) boundary in the shell,
-   between the open and close markers. */
-function spliceResolved(shell: string, id: number, resolved: string): string {
-    const open = `<!--abide:await:${id}-->`
-    const close = `<!--/abide:await:${id}-->`
-    /* A function replacement, so a `$&`/`$\`` etc. in the rendered value is inserted
-       literally rather than interpreted as a special replacement pattern. */
-    return shell.replace(`${open}${close}`, () => `${open}${resolved}${close}`)
-}
-
-/* A self-contained script seeding the resume manifest with the blocking values, so
-   client hydration adopts each resolved branch instead of re-running the promise.
-   Empty when no blocking awaits settled. */
-function resumeScript(resumed: Record<number, ResumeEntry>): string {
-    if (Object.keys(resumed).length === 0) {
-        return ''
-    }
-    const payload = JSON.stringify(resumed).replace(/</g, '\\u003c')
-    return `<script>Object.assign(window.__abideResume=window.__abideResume||{},${payload})</script>`
-}
-
 type Settled = { id: number; html: string; resume: ResumeEntry }
 
-/* Awaits one block's promise and renders the resolved or error branch to HTML,
-   capturing the value (serializable) for the resume manifest. Errors serialize as
-   their message — enough for the catch branch, without leaking a stack. */
+/* Awaits one streaming block's promise and renders the resolved or error branch to
+   HTML (the renderers are async so a nested `await` block composes), capturing the
+   value (serializable) for the resume manifest. Errors serialize as their message —
+   enough for the catch branch, without leaking a stack. */
 function settle(block: SsrAwait): Promise<Settled> {
     return Promise.resolve(block.promise()).then(
-        (value) => ({ id: block.id, html: block.then(value), resume: { ok: true, value } }),
-        (error) => {
+        async (value) => ({
+            id: block.id,
+            html: await block.then(value),
+            resume: { ok: true, value },
+        }),
+        async (error) => {
             /* No catch branch → surface the rejection (500 before the first flush,
                mid-stream error after) instead of swallowing it into an empty fragment. */
             if (block.catch === undefined) {
@@ -90,18 +104,20 @@ function settle(block: SsrAwait): Promise<Settled> {
             }
             return {
                 id: block.id,
-                html: block.catch(error),
+                html: await block.catch(error),
                 resume: { ok: false, error: String(error) },
             }
         },
     )
 }
 
-/* JSON for a `<script type="application/json">` data block: script content is raw
-   text, so only `<` needs neutralizing (emitted as a unicode escape) to keep a
-   literal `</script>` from closing the block early — quotes stay raw. Far cheaper
-   than attribute escaping (no full-string `"`/`&` passes) and JSON.parse decodes it
-   back. `applyResolved`/the inline swap script read it via `.textContent`. */
-function encodeResume(resume: ResumeEntry): string {
-    return JSON.stringify(resume).replace(/</g, '\\u003c')
+/* ref-json for a `<script type="application/json">` data block: script content is
+   raw text, so only `<` needs neutralizing (emitted as a unicode escape) to keep a
+   literal `</script>` from closing the block early — quotes stay raw, and the escape
+   survives `decodeRefJson`'s inner JSON.parse since `<` only ever appears inside JSON
+   strings. `tryEncodeResume` handles the serialize-or-refetch policy (undefined → no
+   script → the swap consumers skip registration → hydration re-runs that one promise).
+   `applyResolved`/the inline swap script store it via `.textContent`; `awaitBlock` decodes it. */
+function encodeStreamResume(resume: ResumeEntry, id: number): string | undefined {
+    return tryEncodeResume(resume, id)?.replace(/</g, '\\u003c')
 }

package/src/lib/ui/resumeSeedScript.ts

@@ -0,0 +1,27 @@
+import { safeJsonForScript } from '../shared/safeJsonForScript.ts'
+import type { ResumeEntry } from './runtime/RESUME.ts'
+import { tryEncodeResume } from './tryEncodeResume.ts'
+
+/* A self-contained `<script>` seeding the await-resume manifest with the blocking
+   values rendered inline on the server, so client hydration adopts each resolved
+   branch instead of re-running its promise. Empty when nothing blocking resolved.
+   Each entry is ref-json-encoded to a string (decoded at read in `awaitBlock`); the
+   id→string map runs as JS (`Object.assign`), so it's wrapped in `safeJsonForScript`
+   — escaping `<`, `-->`, and U+2028/U+2029 so an encoded value can't close the script
+   early or parse as a line terminator. Shared by the buffered (`createUiPageRenderer`)
+   and streaming (`renderToStream`) paths. */
+// @documentation plumbing
+export function resumeSeedScript(resume: Record<number, ResumeEntry>): string {
+    /* ref-json (not JSON) so a value carrying cycles or shared back-references — a
+       media tree with parent↔child links — seeds instead of being dropped. `tryEncodeResume`
+       drops just an unserializable entry (the client re-runs that one branch's promise),
+       keeping every other branch seeded rather than blanking the whole page. */
+    const encoded = Object.entries(resume).flatMap(([id, entry]) => {
+        const text = tryEncodeResume(entry, id)
+        return text === undefined ? [] : [[id, text] as const]
+    })
+    if (encoded.length === 0) {
+        return ''
+    }
+    return `<script>Object.assign(window.__abideResume=window.__abideResume||{},${safeJsonForScript(Object.fromEntries(encoded))})</script>`
+}