@abide/abide 0.42.0 → 0.43.1

package/src/lib/ui/remoteProxy.ts

@@ -6,17 +6,34 @@ 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 { HttpVerb } from '../shared/types/HttpVerb.ts'
+import type { HttpMethod } from '../shared/types/HttpMethod.ts'
+import type { Outbox } from '../shared/types/Outbox.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 { 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'
+
+/* 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'
+
+/* A durable RPC's per-call options. `outbox: true` parks an unreachable call for replay;
+   `store` exists for testing — production uses the default persistence store. */
+export type DurableOptions = {
+    outbox?: boolean
+    store?: PersistenceStore
+}
 
 /*
-Client-side substitute for a verb-defined handler. The bundler emits one
-call per verb export inside an `$rpc/**` module (GET / POST / …): server
-target uses defineVerb (real handler), browser target uses remoteProxy
+Client-side substitute for a rpc-defined handler. The bundler emits one
+call per rpc export inside an `$rpc/**` module (GET / POST / …): server
+target uses defineRpc (real handler), browser target uses remoteProxy
 (fetch over the network). Both paths produce identical RemoteFunction
 shapes and identical WeakMap metadata so cache() works the same on either
 side.
@@ -25,13 +42,26 @@ 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: HttpVerb,
+    method: HttpMethod,
     url: string,
+    durable?: DurableOptions,
 ): RemoteFunction<Args, Return> {
-    return createRemoteFunction<Args, Return>({
+    /* 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
+    const fn = createRemoteFunction<Args, Return>({
         method,
         url,
         clients: browserClientFlags,
@@ -49,12 +79,132 @@ export function remoteProxy<Args, Return>(
                 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.
+        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.
         */
-        invoke: (_args, getRequest, opts) => fetchWithTimeout(getRequest(), opts),
+        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,
+                    ),
+                )
+            }
+            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
+                },
+            )
+        },
     })
+    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
 }
 
 /*

package/src/lib/ui/router.ts

@@ -3,7 +3,7 @@ import { fillBoundary } from './dom/fillBoundary.ts'
 import { outlet } from './dom/outlet.ts'
 import { effect } from './effect.ts'
 import { matchRoute } from './matchRoute.ts'
-import { navigate } from './navigate.ts'
+import { navigatePath } from './navigate.ts'
 import { clientPage } from './runtime/clientPage.ts'
 import { enterRenderPass } from './runtime/enterRenderPass.ts'
 import { exitRenderPass } from './runtime/exitRenderPass.ts'
@@ -253,9 +253,16 @@ export function router(
     }
     const onPageHide = (): void => {
         /* Mirror the live scroll into the active entry's state before it unloads, so a
-           reload can recover it — the in-memory bucket is gone and `manual` keeps the
-           browser from restoring. */
+           non-hydratable reload (which tears the SSR DOM down) can recover it from the
+           manual bucket. */
         historyEntries.persist()
+        /* Re-enable native scroll restoration for the NEXT document load (a reload): the
+           browser restores the SSR DOM's offset before paint, flash-free — where the
+           manual bucket, gated behind the async chunk import, would re-apply post-paint
+           (a visible scroll). The first paint flips back to `manual` for in-session nav. */
+        if ('scrollRestoration' in history) {
+            history.scrollRestoration = 'auto'
+        }
     }
     const onClick = (event: MouseEvent): void => {
         /* Let the browser own anything that isn't a plain primary-button click:
@@ -294,15 +301,21 @@ export function router(
         event.preventDefault()
         /* Carry the query and hash, not just the pathname, so the destination page's
            page.url sees them and an SPA navigation matches a fresh server load. */
-        navigate(destination.pathname + destination.search + destination.hash)
+        navigatePath(destination.pathname + destination.search + destination.hash)
     }
     if (typeof window !== 'undefined') {
-        /* Own scroll restoration: the browser would restore against the pre-teardown
-           DOM. Adopt the initial entry's id (survives a reload) and stamp it onto the
-           landing entry — merging so any `scroll` a prior unload persisted into this
-           entry's state stays put for the first-paint `restore` to recover. */
+        /* Scroll restoration is the browser's job on a document load (reload / first
+           paint): native restoration runs BEFORE paint, so a hydrating in-place adopt
+           returns to the reload offset flash-free (`auto` here also self-heals an entry a
+           prior session left `manual`). The first paint then flips to `manual` (below) so
+           an in-session back/forward — which tears the page down and rebuilds — restores
+           against the new DOM instead of letting the browser restore against the
+           torn-down one; `onPageHide` flips back to `auto` for the next load. Still adopt
+           the initial entry's id (survives a reload) and stamp it onto the landing entry —
+           merging so any `scroll` a prior unload persisted stays put for a non-hydratable
+           first paint's manual `restore` to recover. */
         if ('scrollRestoration' in history) {
-            history.scrollRestoration = 'manual'
+            history.scrollRestoration = 'auto'
         }
         historyEntries.adopt(entryOf())
         const landingState = (history.state as AbideHistoryState | null) ?? {}
@@ -399,7 +412,7 @@ export function router(
                     /* handle() redirected: go where it pointed, replacing the blocked
                    URL so back doesn't trap on it. The router re-probes the target. */
                     if (decision.kind === 'redirect') {
-                        navigate(decision.path, { replace: true })
+                        navigatePath(decision.path, { replace: true })
                         return
                     }
                     /* handle() blocked it / redirected off-origin / the probe failed:
@@ -421,6 +434,7 @@ export function router(
                     ) {
                         divergence += 1
                     }
+                    const firstPaint = first
                     const hydrating = first && pageView?.hydratable === true
                     first = false
                     /* Same page, same layout chain — only params/url differ (e.g. stepping
@@ -483,11 +497,27 @@ export function router(
                         )
                         /* 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. Runs on the initial paint too: with
-                       `scrollRestoration='manual'` the browser does NOT restore a reload's
-                       offset, so first paint recovers it from the persisted `history.state`
-                       (a fresh load with no persisted offset falls through to hash/top). */
-                        historyEntries.restore(url.hash)
+                       anchor (now built) or the top. SKIPPED on a hydrating first paint:
+                       the SSR DOM is adopted in place, so the browser's native restoration
+                       already returned the entry to its reload offset before paint — the
+                       manual bucket, gated behind the async chunk import above, would only
+                       re-apply post-paint (a visible scroll = the flash). A non-hydratable
+                       first paint tore the SSR DOM down and rebuilt, so it still needs the
+                       manual restore (recovered from the persisted `history.state`). */
+                        if (!hydrating) {
+                            historyEntries.restore(url.hash)
+                        }
+                        /* Take over scroll restoration once abide owns the DOM: a later
+                       same-document back/forward must restore against the rebuilt page, so
+                       the browser must not. `onPageHide` flips back to `auto` so the next
+                       document load restores natively (flash-free) again. */
+                        if (
+                            firstPaint &&
+                            typeof history !== 'undefined' &&
+                            'scrollRestoration' in history
+                        ) {
+                            history.scrollRestoration = 'manual'
+                        }
                     }
                     /* Build / hydrate is the deterministic surface — a codegen defect or a
                        throw in user render code fails the SAME way every load, so reloading

package/src/lib/ui/rpcOutbox/createOutboxQueue.ts

@@ -0,0 +1,281 @@
+import { decodeResponse } from '../../shared/decodeResponse.ts'
+import type { OutboxEntry, OutboxStatus } from '../../shared/types/OutboxEntry.ts'
+import { UNREACHABLE_STATUSES } from '../../shared/UNREACHABLE_STATUSES.ts'
+import { persist } from '../persist.ts'
+import { createDoc as doc } from '../runtime/createDoc.ts'
+import type { PersistenceStore } from '../types/PersistenceStore.ts'
+
+/* Persisted form of an entry — the Request reduced to its replayable parts (a live
+   Request + AbortController don't serialize). `body`/`contentType` are captured
+   asynchronously just after park (Request.text() is async); they seed empty and fill
+   in before any reload, so a restored entry replays with its original body. */
+type StoredEntry<Args> = {
+    id: string
+    args: Args
+    method: string
+    url: string
+    body: string
+    contentType: string
+    status: OutboxStatus
+}
+
+/* Non-serializable identity for a live entry: its abort handle, the in-session Request
+   (body intact), and the per-entry retry trigger. Rebuilt from the persisted item on a
+   cold read after reload. */
+type Identity = { controller: AbortController; request: Request; retry: () => Promise<void> }
+
+export type OutboxQueue<Args> = {
+    park: (args: Args, request: Request, reason?: unknown) => OutboxEntry<Args>
+    entries: () => OutboxEntry<Args>[]
+    /* Undelivered-entry count — the same reactive read as `entries()`, without building
+       the entry objects. A caller parks straight to the tail when this is non-empty. */
+    size: () => number
+    retry: () => Promise<void>
+    drain: () => Promise<void>
+    dispose: () => void
+}
+
+/* Persistence key per RPC url — the queue's durable identity. */
+const keyFor = (url: string): string => `abide:outbox:${url}`
+
+/*
+A durable, app-owned FIFO retry queue for one RPC. A call fetches directly and throws as
+before while the queue is empty; when the server can't be reached — a transport failure or
+a 502/503/504/52x — the caller `park`s the request here (a side-effect; the call still
+throws), and once a backlog exists the caller parks every later call at the tail too, so
+FIFO order is preserved on replay. Built on `doc` + `persist`, so the queue IS a persisted
+document that survives a reload. Draining is manual — the app calls `retry()` (per-entry or
+whole-queue) when it decides to replay; nothing drains automatically. The drain re-sends
+head-first: any server response removes the entry — a 2xx (delivered) AND a real 4xx/500
+(the server handled+rejected it; retrying won't help, so it leaves the queue) — while a
+still-unreachable result keeps it `queued` for the next `retry()`, and an abort removes it.
+Resends run under the entry's OWN abort signal alone — scope-abort and the client timeout
+are deliberately not composed in, so a parked write survives an unmount and waits out the
+outage.
+*/
+export function createOutboxQueue<Args>(opts: {
+    url: string
+    send: (request: Request) => Promise<Response>
+    store?: PersistenceStore
+}): OutboxQueue<Args> {
+    const stored = doc({ items: [] as StoredEntry<Args>[] })
+    const persistence = persist(stored, keyFor(opts.url), { store: opts.store, debounce: 0 })
+    /* Live identity (controller + Request + retry) by id, rebuilt from persisted items on
+       a cold read; `errors` is transient last-failure state (never persisted). */
+    const live = new Map<string, Identity>()
+    const errors = new Map<string, unknown>()
+    /* Per-entry `settled` deferreds, created lazily on first read of `entry.settled` (so a
+       never-awaited refusal can't become an unhandled rejection) and resolved/rejected once
+       at the drain exit. Transient — a reload starts fresh. */
+    type Settler = {
+        promise: Promise<unknown>
+        resolve: (value: unknown) => void
+        reject: (error: unknown) => void
+    }
+    const settlers = new Map<string, Settler>()
+
+    /* The lazily-armed `settled` promise for an id: the outcome of this write as if the
+       original call had reached the server. */
+    const settledFor = (id: string): Promise<unknown> => {
+        const existing = settlers.get(id)
+        if (existing !== undefined) {
+            return existing.promise
+        }
+        let resolve!: (value: unknown) => void
+        let reject!: (error: unknown) => void
+        const promise = new Promise<unknown>((res, rej) => {
+            resolve = res
+            reject = rej
+        })
+        settlers.set(id, { promise, resolve, reject })
+        return promise
+    }
+
+    /* Settle an id's deferred (if armed) and drop it — single-shot. */
+    const settle = (id: string, run: (settler: Settler) => void): void => {
+        const settler = settlers.get(id)
+        if (settler !== undefined) {
+            run(settler)
+            settlers.delete(id)
+        }
+    }
+
+    const items = (): StoredEntry<Args>[] => stored.read('items') as StoredEntry<Args>[]
+
+    const remove = (id: string): void => {
+        const index = items().findIndex((item) => item.id === id)
+        if (index !== -1) {
+            stored.remove(`items/${index}`)
+            persistence.flush()
+        }
+        live.delete(id)
+        errors.delete(id)
+        /* A cancel/supersede removal with nobody having delivered first → reject `settled`
+           as a canceled call would. Delivery/refusal settle before calling remove, so this
+           is a no-op for them (single-shot). */
+        settle(id, (s) => s.reject(new DOMException('The outbox entry was canceled', 'AbortError')))
+    }
+
+    const setStatus = (id: string, status: OutboxStatus): void => {
+        const index = items().findIndex((item) => item.id === id)
+        if (index !== -1) {
+            stored.replace(`items/${index}/status`, status)
+            persistence.flush()
+        }
+    }
+
+    /* The non-serializable identity for an id: reuse the live one (Request body intact in
+       session), else rebuild from the persisted parts (fresh controller, cold reload). */
+    const identityFor = (item: StoredEntry<Args>): Identity => {
+        const existing = live.get(item.id)
+        if (existing !== undefined) {
+            return existing
+        }
+        const controller = new AbortController()
+        controller.signal.addEventListener('abort', () => remove(item.id), { once: true })
+        /* `body || undefined` so a bodyless method rebuilds without one (a Request with a
+           body-carrying method + no body is fine; GET/DELETE with a body throws). */
+        const request = new Request(item.url, {
+            method: item.method,
+            body: item.body || undefined,
+            headers: item.contentType ? { 'content-type': item.contentType } : undefined,
+        })
+        /* Per-entry `retry()` kicks a FIFO drain — every entry is `queued`, so it resends
+           head-first and reaches this one in order. */
+        const identity: Identity = { controller, request, retry: () => drain() }
+        live.set(item.id, identity)
+        return identity
+    }
+
+    const toLive = (item: StoredEntry<Args>): OutboxEntry<Args> => {
+        const { controller, request, retry } = identityFor(item)
+        return {
+            id: item.id,
+            controller,
+            request,
+            args: item.args,
+            status: item.status,
+            error: errors.get(item.id),
+            retry,
+            /* Lazy: the deferred is only armed when someone reads `settled`, so an
+               unawaited refusal can't surface as an unhandled rejection. */
+            get settled() {
+                return settledFor(item.id)
+            },
+        }
+    }
+
+    /* Persist the request body + content type just after park (Request.text() is async).
+       The in-session drain replays the LIVE request (body intact) regardless; this fills
+       the persisted form before any reload. A bodyless method leaves the empty seed. */
+    const captureRequest = async (id: string, request: Request): Promise<void> => {
+        const body = request.body === null ? '' : await request.clone().text()
+        const contentType = request.headers.get('content-type') ?? ''
+        const index = items().findIndex((item) => item.id === id)
+        if (index === -1) {
+            return
+        }
+        stored.replace(`items/${index}/body`, body)
+        stored.replace(`items/${index}/contentType`, contentType)
+        persistence.flush()
+    }
+
+    /* Resends run under the entry's OWN signal only — a parked write survives unmount +
+       waits out the outage, so scope-abort + client-timeout are NOT composed in. */
+    const sendable = (entry: OutboxEntry<Args>): Request =>
+        new Request(entry.request, { signal: entry.controller.signal })
+
+    let draining = false
+    let settled: Promise<void> = Promise.resolve()
+    const drain = (): Promise<void> => {
+        if (draining) {
+            return settled
+        }
+        draining = true
+        settled = (async () => {
+            try {
+                while (true) {
+                    const head = items()[0]
+                    if (head === undefined) {
+                        break
+                    }
+                    const entry = toLive(head)
+                    if (entry.controller.signal.aborted) {
+                        remove(head.id) // canceled while queued
+                        continue
+                    }
+                    setStatus(head.id, 'sending')
+                    try {
+                        const response = await opts.send(sendable(entry))
+                        if (UNREACHABLE_STATUSES.has(response.status)) {
+                            setStatus(head.id, 'queued') // still down → wait for the next trigger
+                            break
+                        }
+                        /* The server responded — 2xx OR a real 4xx/500. Either way it
+                           HANDLED the request (the outbox only holds the unreachable), so
+                           the entry leaves the queue and the next proceeds in order. Decode
+                           it exactly as a live call would so `settled` resolves with the
+                           result, or rejects with the real HttpError on a refusal. */
+                        try {
+                            const value = await decodeResponse(response)
+                            settle(head.id, (s) => s.resolve(value))
+                        } catch (responseError) {
+                            settle(head.id, (s) => s.reject(responseError))
+                        }
+                        remove(head.id)
+                        continue
+                    } catch {
+                        if (entry.controller.signal.aborted) {
+                            remove(head.id) // canceled mid-send
+                            continue
+                        }
+                        /* Transport failure on resend — still unreachable, keep queued. */
+                        setStatus(head.id, 'queued')
+                        break
+                    }
+                }
+            } finally {
+                draining = false
+            }
+        })()
+        return settled
+    }
+
+    return {
+        park(args, request, reason) {
+            const id = crypto.randomUUID()
+            const controller = new AbortController()
+            controller.signal.addEventListener('abort', () => remove(id), { once: true })
+            live.set(id, { controller, request, retry: () => drain() })
+            if (reason !== undefined) {
+                errors.set(id, reason)
+            }
+            stored.add('items/-', {
+                id,
+                args,
+                method: request.method,
+                url: request.url,
+                body: '',
+                contentType: '',
+                status: 'queued',
+            })
+            persistence.flush()
+            void captureRequest(id, request)
+            const item = items().find((entry) => entry.id === id) as StoredEntry<Args>
+            return toLive(item)
+        },
+        entries() {
+            return items().map(toLive)
+        },
+        size() {
+            return items().length
+        },
+        retry() {
+            return drain()
+        },
+        drain,
+        dispose() {
+            persistence.dispose()
+        },
+    }
+}

package/src/lib/ui/rpcOutbox/outboxRegistry.ts

@@ -0,0 +1,69 @@
+import { canonicalJson } from '../../shared/canonicalJson.ts'
+import { outboxProbeSlot } from '../../shared/outboxProbeSlot.ts'
+import type { OutboxQueue } from './createOutboxQueue.ts'
+
+/* One registered durable RPC: its url, the RemoteFunction it belongs to (tag for the
+   global aggregate), and its live queue. */
+type RegisteredOutbox = { url: string; rpc: unknown; queue: OutboxQueue<unknown> }
+
+/*
+Client registry of every durable RPC's outbox queue, keyed by url. A durable RPC
+(`outbox: true`) registers on first use so the global `outbox()` aggregate can
+flatten every queue and `pending()` can see queued entries. App-scoped, not component-
+scoped — the queues outlive any mount.
+*/
+const registered = new Map<string, RegisteredOutbox>()
+
+export const outboxRegistry = {
+    register(url: string, queue: OutboxQueue<unknown>, rpc: unknown): void {
+        registered.set(url, { url, rpc, queue })
+    },
+    get(url: string): OutboxQueue<unknown> | undefined {
+        return registered.get(url)?.queue
+    },
+    all(): RegisteredOutbox[] {
+        return [...registered.values()]
+    },
+    /* Drop every registered queue. App-scoped state outlives any mount, so tests that
+       park writes share one process-global registry; reset() gives each its own clean
+       slate. Only the in-memory registry is dropped — `queue.dispose()` keeps the
+       persisted snapshot (a reload rehydrates it), so a sign-out that must abandon
+       unsynced work has to clear persistence separately. */
+    reset(): void {
+        for (const { queue } of registered.values()) {
+            queue.dispose?.()
+        }
+        registered.clear()
+    },
+}
+
+/* The queues a pending() selector spans: a durable rpc selector carries the queue's
+   `url`, so it narrows to that one; the bare form spans every registered queue; any
+   other selector (producer fn, tags, subscribable) carries no url and matches none. */
+const queuesFor = (selector: unknown): OutboxQueue<unknown>[] => {
+    if (selector === undefined) {
+        return outboxRegistry.all().map(({ queue }) => queue)
+    }
+    const url = (selector as { url?: unknown }).url
+    if (typeof url !== 'string') {
+        return []
+    }
+    const queue = outboxRegistry.get(url)
+    return queue === undefined ? [] : [queue]
+}
+
+/* Prober for the shared pending() probe (see outboxProbeSlot). A parked write has no
+   value yet, so it counts as pending. Reads queue.entries() (doc-backed), so the probe
+   re-runs as writes park, drain, fail, or cancel; optional args narrow to one parked
+   call by structural compare — the double-submit guard for a form. The compare uses
+   canonicalJson (key-sorted, the encoder keyForRemoteCall keys body args with), not
+   JSON.stringify, so a selector's args match a parked entry regardless of key order —
+   the same equality the cache-side selector grammar already uses. */
+outboxProbeSlot.probe = (selector, args): boolean => {
+    const entries = queuesFor(selector).flatMap((queue) => queue.entries())
+    if (args === undefined) {
+        return entries.length > 0
+    }
+    const key = canonicalJson(args)
+    return entries.some((entry) => canonicalJson(entry.args) === key)
+}