@abide/abide 0.41.1 → 0.43.0

package/src/lib/ui/outbox.ts

@@ -1,115 +1,35 @@
-import { online as systemOnline } from '../shared/online.ts'
-import { effect } from './effect.ts'
-import { persist } from './persist.ts'
-import { createDoc as doc } from './runtime/createDoc.ts'
-import type { Outbox } from './types/Outbox.ts'
-import type { PersistenceStore } from './types/PersistenceStore.ts'
+import type { OutboxEntry } from '../shared/types/OutboxEntry.ts'
+import type { RemoteFunction } from '../shared/types/RemoteFunction.ts'
+import { outboxRegistry } from './rpcOutbox/outboxRegistry.ts'
 
-/* One queued mutation: a stable id plus the serializable payload to replay. */
-type OutboxEntry<T> = { id: string; payload: T }
+/* One entry in the global outbox, tagged with the RPC it belongs to. */
+export type GlobalOutboxEntry = OutboxEntry<unknown> & { rpc: RemoteFunction<unknown, unknown> }
+
+/* The global outbox: callable for the flat entry list, awaitable `retry()` to drain every
+   queue (resolves when every replay settles). */
+export type GlobalOutbox = (() => GlobalOutboxEntry[]) & { retry: () => Promise<void> }
+
+function list(): GlobalOutboxEntry[] {
+    return outboxRegistry.all().flatMap(({ rpc, queue }) =>
+        queue.entries().map((entry) => ({
+            ...entry,
+            rpc: rpc as RemoteFunction<unknown, unknown>,
+        })),
+    )
+}
 
 /*
-A durable, FIFO mutation queue for local-first writes. Built on `doc` + `persist`,
-so the queue IS a persisted document — it survives a reload with no extra
-machinery — and on the patch bus the same as everything else. `enqueue` appends a
-payload and tries to drain; the drain sends entries head-first while `online()`
-holds:
-  - success → dequeue and continue;
-  - rejected while now offline → keep the head, retry when connectivity returns
-    (the effect below re-drains on the online edge);
-  - rejected while still online → a real server/validation failure: drop the entry
-    so the queue can't wedge, and report it via `onDrop` so the caller can roll back
-    the optimistic change it applied (e.g. `history().undo()` or a `cache.patch`).
-Delivery is at-least-once (a crash between a successful send and its dequeue
-re-sends on reload), so `send` should be idempotent. Reconnect RESYNC of reads is
-`cache.on`'s job, not this. Client-intended: `send` performs a network mutation.
+The global, reactive view of every durable RPC's outbox — a flat list of undelivered
+entries across all `outbox` rpcs, each tagged with its `rpc`. Reactive: reading it in a
+template/effect subscribes to each registered queue, so it updates as writes park, drain,
+fail, or cancel. Use it for an app-wide "N unsynced" badge or a sync panel; cancel a
+pending write through `entry.controller.abort()`, retry one through `entry.retry()`, or
+drain everything through `outbox.retry()`. A single rpc's slice is `rpc.outbox`. Server-
+side there are no client queues, so it returns an empty list.
 */
 // @documentation ui
-export function outbox<T>({
-    key,
-    send,
-    store,
-    online = systemOnline,
-    onDrop,
-}: {
-    key: string
-    send: (payload: T) => Promise<void>
-    store?: PersistenceStore
-    online?: () => boolean
-    onDrop?: (payload: T, error: unknown) => void
-}): Outbox<T> {
-    const queue = doc({ items: [] as OutboxEntry<T>[] })
-    /* `debounce: 0` because the queue writes itself synchronously below — a queued
-       mutation must be durable the instant it's recorded, not after a debounce
-       window where a crash could lose it. */
-    const persistence = persist(queue, key, { store, debounce: 0 })
-    /* Drop the head and make the dequeue durable at once, so a reload never re-sends
-       an entry already acknowledged. */
-    const dequeue = (): void => {
-        queue.remove('items/0')
-        persistence.flush()
-    }
-
-    /* At most one drain runs at a time; `settled` lets a caller await the active one.
-       A drain re-reads the queue each step, so entries enqueued mid-drain are picked
-       up by the running loop. An empty drain finishes synchronously (it hits no
-       `await`), so `draining` is back to false before the next `enqueue` — there is no
-       resolved-but-still-flagged window for a new entry to fall into. */
-    let draining = false
-    let settled: Promise<void> = Promise.resolve()
-    const flush = (): Promise<void> => {
-        if (draining) {
-            return settled
-        }
-        draining = true
-        settled = (async () => {
-            try {
-                while (online()) {
-                    const { items } = queue.snapshot() as { items: OutboxEntry<T>[] }
-                    const head = items[0]
-                    if (head === undefined) {
-                        break
-                    }
-                    try {
-                        await send(head.payload)
-                    } catch (error) {
-                        /* Went offline mid-send → keep the head, retry on reconnect. */
-                        if (!online()) {
-                            break
-                        }
-                        /* Online but rejected → permanent: drop it, report for rollback. */
-                        dequeue()
-                        onDrop?.(head.payload, error)
-                        continue
-                    }
-                    dequeue()
-                }
-            } finally {
-                draining = false
-            }
-        })()
-        return settled
-    }
-
-    /* Re-drain whenever connectivity returns — reading `online()` subscribes this
-       effect, so the offline→online edge fires it. */
-    const stop = effect(() => {
-        if (online()) {
-            void flush()
-        }
-    })
-
-    return {
-        enqueue: (payload: T) => {
-            queue.add('items/-', { id: crypto.randomUUID(), payload })
-            persistence.flush() // durable before we attempt the network
-            void flush()
-        },
-        pending: () => (queue.read('items') as OutboxEntry<T>[]).map((entry) => entry.payload),
-        flush,
-        dispose: () => {
-            stop()
-            persistence.dispose()
-        },
-    }
-}
+export const outbox: GlobalOutbox = Object.assign(list, {
+    async retry(): Promise<void> {
+        await Promise.all(outboxRegistry.all().map(({ queue }) => queue.retry()))
+    },
+})

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'
@@ -294,7 +294,7 @@ 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
@@ -399,7 +399,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:

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