@abide/abide 0.49.0 → 0.50.0

package/src/lib/ui/remoteProxy.ts

@@ -6,32 +6,49 @@ import { HttpError } from '../shared/HttpError.ts'
 import { OFFLINE_HEADER } from '../shared/OFFLINE_HEADER.ts'
 import { rpcTimeoutSlot } from '../shared/rpcTimeoutSlot.ts'
 import { trace } from '../shared/trace.ts'
+import type { CachePolicy } from '../shared/types/CachePolicy.ts'
 import type { HttpMethod } from '../shared/types/HttpMethod.ts'
-import type { Outbox } from '../shared/types/Outbox.ts'
+import type { OutputWirePlan } from '../shared/types/OutputWirePlan.ts'
 import type { RemoteFunction } from '../shared/types/RemoteFunction.ts'
 import type { RpcOptions } from '../shared/types/RpcOptions.ts'
-import { UNREACHABLE_STATUSES } from '../shared/UNREACHABLE_STATUSES.ts'
+import type { StandardSchemaV1 } from '../shared/types/StandardSchemaV1.ts'
+import type { StreamPolicy } from '../shared/types/StreamPolicy.ts'
+import { validationHttpError } from '../shared/validationHttpError.ts'
 import { withBase } from '../shared/withBase.ts'
-import { createOutboxQueue, type OutboxQueue } from './rpcOutbox/createOutboxQueue.ts'
-import { outboxRegistry } from './rpcOutbox/outboxRegistry.ts'
 import { currentAbortSignal } from './runtime/currentAbortSignal.ts'
 import { REQUEST_SUPERSEDED } from './runtime/REQUEST_SUPERSEDED.ts'
-import type { PersistenceStore } from './types/PersistenceStore.ts'
 import { watch } from './watch.ts'
 
-/* The framework-reserved `HttpError.kind` for a request the durable outbox parked because
-   the server was unreachable — distinct from a handler-declared error name. Lets a caller
-   branch with `error instanceof HttpError && error.kind === 'queued'`. */
-const QUEUED = 'queued'
-
-/* Build-time options the bundler stamps onto the client proxy stub. `outbox: true` parks an
-   unreachable call for replay; `streaming: true` (handler returns jsonl()/sse()) makes the bare
-   call return the Subscribable directly; `store` exists for testing (production uses the default
-   persistence store). */
-export type DurableOptions = {
-    outbox?: boolean
+/* The proxy's third argument. ADR-0022 D2: the client rpc transform passes the endpoint's LIVE
+   `opts` object here verbatim, so the type widens to the endpoint opts shape — remoteProxy reads
+   only the keys below and IGNORES the rest (`crossOrigin` / `timeout` / `maxBodySize`), which ride
+   along harmlessly. `streaming: true` (handler returns jsonl()/sse(), build-injected) makes the
+   bare call return the NamedAsyncIterable directly; `cache` / `stream` carry the endpoint's declared
+   policy (ADR-0020) so the client honours the ttl (staleness/SWR), the refetch clock
+   (throttle/debounce), and tags. `schemas` — its live `input` validator now reaches the stub (ADR-0022
+   D2) — drives the ADR-0026 client-side pre-flight. */
+export type RemoteProxyOptions<Args = unknown> = {
     streaming?: boolean
-    store?: PersistenceStore
+    /* The client output wire codec plan (ADR-0029) the resolver plugin baked onto the stub — the
+       handler's structured success fields, so the proxy revives a `Set`/`Map`/`bigint`/`Date` off a
+       decoded response. Absent on the fail-open path (a response array then stays an array). */
+    outputWirePlan?: OutputWirePlan
+    cache?: CachePolicy<Args>
+    stream?: StreamPolicy
+    /* The endpoint's live schema group (ADR-0022 D2 forwards it verbatim). `input` is the
+       Standard Schema the ADR-0026 pre-flight validates the typed args against. */
+    schemas?: {
+        input?: StandardSchemaV1
+        output?: StandardSchemaV1
+        files?: StandardSchemaV1
+    }
+    /* Ignored endpoint opts keys, present only so the author's live `opts` object type-checks
+       when the client transform forwards it verbatim (ADR-0022). `clients` (surface flags) is
+       read only on the server. */
+    clients?: unknown
+    crossOrigin?: unknown
+    timeout?: unknown
+    maxBodySize?: unknown
 }
 
 /*
@@ -46,40 +63,33 @@ side.
 the query string (GET/DELETE/HEAD). Plain `fn(args)` decodes the Response
 by Content-Type and throws HttpError on non-2xx; `.raw(args)` is the
 escape hatch that returns the Response untouched.
-
-A durable (`outbox: true`) rpc is still a normal RemoteFunction — it fetches and
-throws exactly the same. The differences: when the server can't be reached
-(a transport failure, or a 502/503/504/52x), the request is `park`ed onto the
-RPC's app-owned outbox as a SIDE-EFFECT and the throw is a `kind: 'queued'`
-HttpError; and once a backlog exists, a fresh call parks straight to the TAIL
-(no fetch) so writes can't land out of order. The parked write waits for
-`rpc.outbox.retry()` (or the global `outbox.retry()`) — there is no auto-drain;
-the app owns when to replay. `rpc.outbox()` exposes the queue.
 */
 // @documentation plumbing
 export function remoteProxy<Args, Return>(
     method: HttpMethod,
     url: string,
-    durable: DurableOptions & { outbox: true },
-): RemoteFunction<Args, Return, Record<never, never>, true>
-export function remoteProxy<Args, Return>(
-    method: HttpMethod,
-    url: string,
-    durable?: DurableOptions,
-): RemoteFunction<Args, Return>
-export function remoteProxy<Args, Return>(
-    method: HttpMethod,
-    url: string,
-    durable?: DurableOptions,
-): RemoteFunction<Args, Return, Record<never, never>, boolean> {
-    /* Assigned after `createRemoteFunction` so the invoke closure (which runs later, per
-       call) parks through the shared queue; undefined leaves the plain fetch path. */
-    let queue: OutboxQueue<Args> | undefined
+    options?: RemoteProxyOptions<Args>,
+): RemoteFunction<Args, Return> {
+    /* ADR-0026 client-side pre-flight: validate the typed args against the endpoint's input
+       schema (forwarded to the stub, ADR-0022 D2) BEFORE the fetch whenever one is present — always
+       on, no opt-in. This is a UX optimization ONLY: the server's unconditional inputSchema validate
+       → 422 (defineRpc.ts `validateThenHandle`) stays the trust boundary, so a client that skips or
+       fakes this check is still fully validated on the server. undefined here (no input schema)
+       keeps today's behaviour — the client serializes and sends unvalidated. */
+    const preflightSchema = options?.schemas?.input
     const fn = createRemoteFunction<Args, Return>({
         method,
         url,
         clients: browserClientFlags,
-        streaming: durable?.streaming ?? false,
+        streaming: options?.streaming ?? false,
+        /* The client revives a decoded response's structured fields through this plan (ADR-0029
+           output path); undefined leaves the honest-JSON body untouched. */
+        outputWirePlan: options?.outputWirePlan,
+        /* Endpoint policy the resolver plugin spliced onto the stub — governs client cache
+           behaviour (ttl/staleness, refetch clock, tags). createRemoteFunction stamps it onto
+           `fn.cache` / `fn.stream` so readThrough reads it as the bottom policy layer. */
+        cache: options?.cache,
+        stream: options?.stream,
         /*
         The Request URL carries the mount base so the fetch routes through the
         proxy (/v2/rpc/…); the cache key keeps the bare `url` (keyForRemoteCall
@@ -96,56 +106,42 @@ export function remoteProxy<Args, Return>(
         /*
         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. On a durable rpc, an unreachable result parks a pristine CLONE and throws a
-        `queued`-tagged HttpError — `fetch` consumes the original (its body stream is read
-        and locked), so parking that same instance would leave the queue a request a resend
-        can't reconstruct and a capture can't read. The clone is parked, the original is
-        sent. The throw lets the caller branch on `error.kind === 'queued'` (parked, will
-        retry) vs. a real server rejection; `error.data` is the parked entry, so a caller
-        can `await (error.data as OutboxEntry).settled` for the eventual outcome.
+        it.
         */
         invoke: (args, getRequest, opts) => {
-            if (queue === undefined) {
-                return fetchWithTimeout(getRequest(), opts)
-            }
-            /* A non-empty queue means an undelivered backlog: park this call at the TAIL
-               and throw, rather than let a live fetch leapfrog the older writes and land
-               out of order. `retry()` then flushes the whole queue FIFO. */
-            if (queue.size() > 0) {
-                return Promise.reject(
-                    queuedThrow(
-                        queue,
-                        args as Args,
-                        getRequest().clone(),
-                        unreachableResponse(),
-                        undefined,
-                    ),
+            /* ADR-0026 D2/D3: an input schema present → validate the TYPED args (pre-serialization
+               — NOT the string-shaped serialized form, which sidesteps parseArgs's query-coercion
+               gap) before any fetch. The validate may return a Promise (StandardSchemaV1), so await
+               it (D3). On a returned failure throw an HttpError shaped IDENTICALLY to the server's
+               422 (validationHttpError) and make NO fetch — saving the round-trip. */
+            if (preflightSchema !== undefined) {
+                return (
+                    Promise.resolve()
+                        .then(() => preflightSchema['~standard'].validate(args))
+                        .then(
+                            (result) => {
+                                /* A returned `issues` result is a definitive "this input is invalid" —
+                               throw the same 422-shaped HttpError the server would (validationHttpError)
+                               so it rejects the chain and makes NO fetch, saving the round-trip. */
+                                if (result.issues) {
+                                    throw validationHttpError(result.issues)
+                                }
+                            },
+                            () => {
+                                /* A validate REJECTION (not an `issues` verdict) means the validator itself
+                               could not run here (a non-portable / async-resource refinement), which is
+                               NOT a verdict on the input: swallow it and fall through to the fetch, letting
+                               the server (the authoritative validator) decide. So a schema can never break
+                               a call merely by failing to run client-side. */
+                            },
+                        )
+                        /* Fetch exactly ONCE, only after validation settles — outside the validate handlers
+                       so a fetch/timeout rejection propagates to the caller untouched rather than being
+                       mistaken for a "validator couldn't run" fall-through and resending the request. */
+                        .then(() => fetchWithTimeout(getRequest(), opts))
                 )
             }
-            const request = getRequest()
-            const parkable = request.clone()
-            return fetchWithTimeout(request, opts).then(
-                (response) => {
-                    if (UNREACHABLE_STATUSES.has(response.status)) {
-                        throw queuedThrow(
-                            queue,
-                            args as Args,
-                            parkable,
-                            response,
-                            new HttpError(response.clone()),
-                        )
-                    }
-                    return response
-                },
-                (error: unknown) => {
-                    if (shouldParkRejection(error)) {
-                        const response =
-                            error instanceof HttpError ? error.response : unreachableResponse()
-                        throw queuedThrow(queue, args as Args, parkable, response, error)
-                    }
-                    throw error
-                },
-            )
+            return fetchWithTimeout(getRequest(), opts)
         },
     })
     /* Overwrite the inert `.watch` the shared attach bound: on the client the real reaction
@@ -159,80 +155,9 @@ export function remoteProxy<Args, Return>(
                 handler,
             ),
     })
-    if (durable?.outbox === true) {
-        queue = getOrCreateOutboxQueue<Args, Return>(url, fn, durable)
-        Object.assign(fn, { outbox: outboxFace(queue) })
-    }
     return fn
 }
 
-/* The synthetic "unreachable" Response a park reuses when there is no real one — a
-   transport failure (fetch rejected) or a backlog park that never fetched. */
-function unreachableResponse(): Response {
-    return new Response('queued', { status: 503, statusText: 'Service Unavailable' })
-}
-
-/* Park the unreachable request (`cause` becomes the entry's parked reason, `entry.error`)
-   and return the `kind: 'queued'` HttpError to throw — its `.data` is the parked entry, so
-   a caller can `await (error.data as OutboxEntry).settled` for the eventual delivered
-   result or server refusal. */
-function queuedThrow<Args>(
-    queue: OutboxQueue<Args> | undefined,
-    args: Args,
-    request: Request,
-    response: Response,
-    cause: unknown,
-): HttpError {
-    const entry = queue?.park(args, request, cause)
-    return new HttpError(response, QUEUED, entry)
-}
-
-/* A fetch REJECTION (no Response) the durable rpc should park: a transport failure or
-   the synthesized client-timeout 504. NOT a caller/scope abort — that's a deliberate
-   cancel, not the server being unreachable. (HTTP error STATUSES never reject — `fetch`
-   resolves with them — so 4xx/500 are classified on the response, not here.) */
-function shouldParkRejection(error: unknown): boolean {
-    if (error === REQUEST_SUPERSEDED) {
-        return false
-    }
-    if (error instanceof DOMException && error.name === 'AbortError') {
-        return false
-    }
-    if (error instanceof HttpError) {
-        return UNREACHABLE_STATUSES.has(error.response.status)
-    }
-    return true
-}
-
-/* The single app-owned queue for a durable RPC url — created + registered on first use
-   so every call site (and the global `outbox()`) shares one queue. The send is a plain
-   `fetch`; createOutboxQueue rides the entry's abort signal on the resent Request and
-   keeps scope-abort + the client timeout out. */
-function getOrCreateOutboxQueue<Args, Return>(
-    url: string,
-    rpc: RemoteFunction<Args, Return>,
-    durable: DurableOptions,
-): OutboxQueue<Args> {
-    const existing = outboxRegistry.get(url)
-    if (existing !== undefined) {
-        return existing as OutboxQueue<Args>
-    }
-    const queue = createOutboxQueue<Args>({
-        url,
-        send: (request) => fetch(request),
-        store: durable.store,
-    })
-    outboxRegistry.register(url, queue as OutboxQueue<unknown>, rpc)
-    return queue
-}
-
-/* The `.outbox` face: callable for the live entries, `retry()` to drain on demand. */
-function outboxFace<Args>(queue: OutboxQueue<Args>): Outbox<Args> {
-    const face = (() => queue.entries()) as Outbox<Args>
-    face.retry = () => queue.retry()
-    return face
-}
-
 /*
 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

package/src/lib/ui/renderChain.ts

@@ -1,9 +1,11 @@
+import { isolateCellBarrier } from './isolateCellBarrier.ts'
 import { CHILD_PRESENT } from './runtime/CHILD_PRESENT.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'
 import type { UiProps } from './runtime/types/UiProps.ts'
+import { withPath } from './runtime/withPath.ts'
 
 const OPEN = `<!--${OUTLET_OPEN}-->`
 const CLOSE = `<!--${OUTLET_CLOSE}-->`
@@ -13,11 +15,13 @@ 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 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.
+block-id counter map (`$ctx`): each `await`/`try` block draws a path-namespaced id
+(`${render-path}:${n}`, ADR-0037), so ids stay unique across layers by path rather than by
+a shared sequential draw — keeping the streamed fragments and the resume manifest aligned
+with the client (which composes the same path-keyed ids). The layers render IN PARALLEL
+(`Promise.all`, ADR-0038): each roots a distinct route-key path so their block ids never collide,
+and each runs under `isolateCellBarrier` so their async-cell barriers don't cross-drain — the html
+fold + state/awaits/resume aggregation below run after all settle and are order-independent.
 
 The html nests inner-to-outer: each parent layout's empty outlet boundary
 (`<!--abide:outlet--><!--/abide:outlet-->`) is filled with the accumulated child html —
@@ -30,8 +34,12 @@ A layout missing its `<slot/>` is a build error surfaced here.
 export async function renderChain(
     views: UiComponent[],
     params: Record<string, string>,
+    /* Each view's route key (layout directory URL / page route pattern), aligned 1:1 with `views`
+       and byte-identical to the client router's `chainKeys`/`pageKey`. Each roots its layer's
+       render-path (`withPath`) so a cell's scope id matches the client's for the warm-seed key. */
+    keys: string[] = [],
 ): Promise<SsrRender> {
-    const ctx: RenderContext = { next: 0 }
+    const ctx: RenderContext = new Map()
     const renders: SsrRender[] = []
     /* Route params as thunks (static server-side — only shape parity with the client so
        `props()` reads `$props["id"]?.()` resolve). A layout (every view but the last) also
@@ -43,13 +51,41 @@ export async function renderChain(
     for (const key of Object.keys(params)) {
         paramThunks[key] = () => params[key]
     }
-    for (let index = 0; index < views.length; index += 1) {
-        const view = views[index] as UiComponent
-        const hasChild = index < views.length - 1
-        const props: UiProps = hasChild
-            ? { ...paramThunks, children: () => CHILD_PRESENT }
-            : paramThunks
-        renders.push(await view.render(props, ctx))
+    if (views.length > 1) {
+        /* ADR-0038: a route WITH layouts renders its layers IN PARALLEL. Block ids are path-keyed
+           (ADR-0037) and each layer roots a DISTINCT route-key path, so their id allocations never
+           collide even as the async continuations interleave; the fold + state/awaits/resume
+           aggregation below run AFTER all settle and are order-independent (keyed merges /
+           index-ordered). Each layer runs under `isolateCellBarrier` so its async-cell barrier drains
+           its OWN pending list — without it, two layers registering cells concurrently into the one
+           request-scoped list would splice-drain each other (the hazard ADR-0037 fixed for sibling
+           children). Scope needs no isolation: the shipped parallel child renders tolerate the
+           identical per-request CURRENT_SCOPE clobber (all scope-sensitive construction is
+           synchronous in each render's prefix). */
+        const collected = await Promise.all(
+            views.map((view, index) => {
+                const hasChild = index < views.length - 1
+                const props: UiProps = hasChild
+                    ? { ...paramThunks, children: () => CHILD_PRESENT }
+                    : paramThunks
+                const key = keys[index]
+                const run = () => isolateCellBarrier(() => view.render(props, ctx))
+                return key === undefined ? run() : withPath(key, run)
+            }),
+        )
+        renders.push(...collected)
+    } else if (views.length === 1) {
+        /* A lone page (no layouts) — the common case — renders DIRECTLY: no parallelism to gain, and
+           no `Promise.all`/`isolateCellBarrier` wrap, so its bare-read/settle timing is byte-identical
+           to the pre-ADR-0038 path (a fast in-process read stays pending → streams, rather than
+           slipping settled → inline behind an extra microtask). */
+        const view = views[0] as UiComponent
+        const key = keys[0]
+        renders.push(
+            key === undefined
+                ? await view.render(paramThunks, ctx)
+                : await withPath(key, () => view.render(paramThunks, ctx)),
+        )
     }
     let html = renders[renders.length - 1]?.html ?? ''
     for (let index = renders.length - 2; index >= 0; index -= 1) {

package/src/lib/ui/renderToStream.ts

@@ -8,8 +8,8 @@ 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
+type="application/json">…</script>…</abide-resolve>` that the inline swap script 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.
 
@@ -38,14 +38,13 @@ export async function* renderToStream(
        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> = {}
+    const seededResume = new Set<string>(Object.keys(resume))
+    const resumeDelta = (): Record<string, ResumeEntry> => {
+        const delta: Record<string, ResumeEntry> = {}
         for (const [key, entry] of Object.entries(resume)) {
-            const id = Number(key)
-            if (!seededResume.has(id)) {
-                seededResume.add(id)
-                delta[id] = entry
+            if (!seededResume.has(key)) {
+                seededResume.add(key)
+                delta[key] = entry
             }
         }
         return delta
@@ -55,8 +54,8 @@ export async function* renderToStream(
        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>>()
-    const enqueued = new Set<number>()
+    const inflight = new Map<string, Promise<Settled>>()
+    const enqueued = new Set<string>()
     const enqueueNew = (): void => {
         for (const block of awaits) {
             if (!enqueued.has(block.id)) {
@@ -71,11 +70,14 @@ export async function* renderToStream(
         inflight.delete(resolved.id)
         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
+           with NO seed script: the inline swap script (SSR_SWAP_SCRIPT) skips
            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)
+        const encoded =
+            resolved.resume === undefined
+                ? undefined
+                : encodeStreamResume(resolved.resume, resolved.id)
         yield resumeSeedScript(resumeDelta()) +
             `<abide-resolve data-id="${resolved.id}">` +
             (encoded === undefined ? '' : `<script type="application/json">${encoded}</script>`) +
@@ -83,7 +85,7 @@ export async function* renderToStream(
     }
 }
 
-type Settled = { id: number; html: string; resume: ResumeEntry }
+type Settled = { id: string; html: string; resume: ResumeEntry | undefined }
 
 /* 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
@@ -95,7 +97,9 @@ function settle(block: SsrAwait): Promise<Settled> {
         async (value) => ({
             id: block.id,
             html: await block.then(value),
-            resume: { ok: true, value },
+            /* A standalone-unit (streamed component) boundary carries no resume value of its own —
+               its `then` already merged the child's nested awaits/resume for streaming composition. */
+            resume: block.htmlOnly === true ? undefined : { ok: true, value },
         }),
         async (error) => {
             /* No catch branch → surface the rejection (500 before the first flush,
@@ -117,8 +121,8 @@ function settle(block: SsrAwait): Promise<Settled> {
    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 {
+   script → the inline swap script skips registration → hydration re-runs that one promise).
+   The inline swap script stores it via `.textContent`; `awaitBlock` decodes it. */
+function encodeStreamResume(resume: ResumeEntry, id: string): string | undefined {
     return tryEncodeResume(resume, id)?.replace(/</g, '\\u003c')
 }

package/src/lib/ui/resumeSeedScript.ts

@@ -11,7 +11,7 @@ import { tryEncodeResume } from './tryEncodeResume.ts'
    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 {
+export function resumeSeedScript(resume: Record<string, 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),

package/src/lib/ui/router.ts

@@ -1,7 +1,6 @@
-import { hydratingSlot } from '../shared/hydratingSlot.ts'
+import { hydrationWindow } from '../shared/hydrationWindow.ts'
 import { layoutChainForRoute } from '../shared/layoutChainForRoute.ts'
 import { matchRoute } from '../shared/matchRoute.ts'
-import { wakeHydrationPeeks } from '../shared/wakeHydrationPeeks.ts'
 import { fillBoundary } from './dom/fillBoundary.ts'
 import { outlet } from './dom/outlet.ts'
 import { effect } from './effect.ts'
@@ -20,6 +19,7 @@ import type { Route } from './runtime/types/Route.ts'
 import type { RouteLoader } from './runtime/types/RouteLoader.ts'
 import type { UiProps } from './runtime/types/UiProps.ts'
 import { untrack } from './runtime/untrack.ts'
+import { withPath } from './runtime/withPath.ts'
 
 /* An outlet boundary — the `<!--abide:outlet-->`…`<!--/abide:outlet-->` marker pair a
    layer's content lives between (a layout's `<slot/>`, or the router's root boundary in
@@ -220,15 +220,17 @@ export function router(
             for (let depth = index; depth < layoutViews.length; depth += 1) {
                 const view = layoutViews[depth] as Route
                 PENDING_OUTLET.current = undefined
-                const { dispose } = fillBoundary(
-                    boundary.open,
-                    boundary.close,
-                    view.build,
-                    /* A layout always has a child below: a deeper layout, or the page. */
-                    propsBag(depth < layoutViews.length - 1 || pageView !== undefined),
-                    /* The layout's route key names its scope in the inspector's Reactive tab
-                       (no host element to read a tag from — see `scopeLabel`). */
-                    chainKeys[depth],
+                /* Root this layer's render-path at its route key (the directory URL — stable
+                   across reloads and globally unique), so every scope/cell it builds gets a
+                   serialization-stable id under it (`withPath`). */
+                const { dispose } = withPath(chainKeys[depth] as string, () =>
+                    fillBoundary(
+                        boundary.open,
+                        boundary.close,
+                        view.build,
+                        /* A layout always has a child below: a deeper layout, or the page. */
+                        propsBag(depth < layoutViews.length - 1 || pageView !== undefined),
+                    ),
                 )
                 const slot = PENDING_OUTLET.current
                 if (slot === undefined) {
@@ -241,34 +243,32 @@ export function router(
                 mountedPageKey = undefined
                 return
             }
-            disposePage = fillBoundary(
-                boundary.open,
-                boundary.close,
-                pageView.build,
-                /* A page is a leaf — no child layer. */
-                propsBag(false),
-                /* The page's route key names its scope in the inspector (see above). */
-                pageKey,
+            /* Root the page's render-path at its route key (stable, unique) — see the layout
+               layer above. */
+            disposePage = withPath(pageKey, () =>
+                fillBoundary(
+                    boundary.open,
+                    boundary.close,
+                    pageView.build,
+                    /* A page is a leaf — no child layer. */
+                    propsBag(false),
+                ),
             ).dispose
             mountedPageKey = pageKey
         }
         if (hydrating) {
             const previous = RENDER.hydration
-            const previousHydrating = hydratingSlot.active
             RENDER.hydration = { next: new Map() }
-            hydratingSlot.active = true
+            hydrationWindow.enter()
             enterRenderPass()
             try {
                 run()
             } finally {
                 exitRenderPass()
                 RENDER.hydration = previous
-                hydratingSlot.active = previousHydrating
-                /* Wake the peeks this pass withheld for SSR congruence, now that the pass is
-                   over and the warm value is congruent to show. Only on the outermost unwind. */
-                if (!previousHydrating) {
-                    wakeHydrationPeeks()
-                }
+                /* Outermost exit clears the window and wakes the peeks this pass withheld
+                   for SSR congruence, now that the warm value is congruent to show. */
+                hydrationWindow.exit()
             }
             return
         }
@@ -532,15 +532,42 @@ export function router(
                         disposeFrom(divergence)
                         const url = resolveUrl(path)
                         clientPage.value = { route: chainRoute, params, url, navigating: false }
-                        buildFrom(
-                            divergence,
-                            chainKeys,
-                            layoutViews,
-                            pageView,
-                            key,
-                            params,
-                            hydrating,
-                        )
+                        try {
+                            buildFrom(
+                                divergence,
+                                chainKeys,
+                                layoutViews,
+                                pageView,
+                                key,
+                                params,
+                                hydrating,
+                            )
+                        } catch (error) {
+                            /* A cold mount owns no claim cursor, so the SSR-vs-client claim asserts
+                               (`assertClaimedText`, `claimExpected`) can't fire there — a throw from
+                               it is a genuine codegen/user-render defect. Rethrow to `commit`, which
+                               surfaces it and stops (a reload would re-run the same failure). */
+                            if (!hydrating) {
+                                throw error
+                            }
+                            /* A HYDRATING first paint threw — a server↔client markup divergence (a
+                               blocking cell whose resolved value the server couldn't serialize into
+                               `__SSR__.cells`, so the client reads pending where SSR baked a value;
+                               or any other SSR/client mismatch). A reload re-runs the same SSR, so
+                               recover CLIENT-side: discard the server markup and mount the page fresh
+                               (cold — pending reads render their empty state and fill in on settle,
+                               congruent because nothing is being adopted). Reset to the pristine
+                               pre-mount state so `run` re-establishes the root boundary and clears the
+                               host, then rebuild the whole chain cold. */
+                            console.warn(
+                                `[abide] hydration mismatch at ${path} — discarding server markup and rendering on the client:`,
+                                error,
+                            )
+                            disposeFrom(0)
+                            rootBoundary = undefined
+                            mountedPageKey = undefined
+                            buildFrom(0, chainKeys, layoutViews, pageView, key, params, false)
+                        }
                         /* Reapply the destination entry's scroll once its DOM exists — a
                        back/forward restores its offset, a fresh nav scrolls to the `#hash`
                        anchor (now built) or the top. SKIPPED on a hydrating first paint: