@greendrake/vue-api 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eugene Greendrake
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# @greendrake/vue-api
+
+The Vue/Pinia binding of `@greendrake/rpc`. `ApiClient` adds loading-state wiring, a response cache, an error-UX pipeline (one blocking retry/acknowledge toast), offline parking and per-code error handlers to a typed method map; alongside it a connectivity store, a retry helper for plain fetches, and a component-scoped WebSocket push subscription.
+
+## Install
+
+```sh
+bun add @greendrake/vue-api vue pinia
+```
+
+`vue` (^3.5.34) and `pinia` (^3.0.4) are peers. The package ships TypeScript source and one Vue SFC with an SCSS style block as-is (no build step, no `.d.ts`): the consuming Vite + Vue 3 app compiles them, so it needs `@vitejs/plugin-vue` and a Sass implementation in its toolchain. `@greendrake/rpc`, `@greendrake/ui` (the toast and its message strings), `@greendrake/util` and `@greendrake/vue-kit` (the global loading state) install as dependencies.
+
+## The app's `api.ts`
+
+One module declares the typed method map, builds the transport and exports the client; every store and component imports from it.
+
+```ts
+// src/api.ts
+import { HttpTransport } from '@greendrake/rpc'
+import { ApiClient } from '@greendrake/vue-api'
+import type { Host, ListResult, PageArgs, Vlan } from './types'
+
+export interface Methods {
+    'host.list': (query: PageArgs) => ListResult<Host>
+    'host.get': (id: number) => Host
+    'host.update': (record: { id: number } & Partial<Host>) => Host
+    'host.delete': (args: { id: number }) => void
+    'vlan.list': (query: Record<string, never>) => Vlan[]
+}
+
+export const api = new ApiClient<Methods>({
+    transport: new HttpTransport({
+        url: __API_URL__,
+        headers: () => ({ 'x-api-key': __API_KEY__ })
+    })
+})
+```
+
+The same with a WebSocket transport, in-band session auth and server push:
+
+```ts
+// src/api.ts
+import { WebSocketPipe, WsTransport, type WsAuthStrategy } from '@greendrake/rpc'
+import { ApiClient, configureApiUX } from '@greendrake/vue-api'
+
+export interface Methods {
+    'auth.token': (token: string) => void
+    'auth.logout': () => void
+    'taxonomy.tree': (args: { taxonomy: string }) => TaxonomyNode[]
+    'thread.message.create': (args: { thread_id: string; body: string }) => { message: Message }
+}
+
+export interface Pushes {
+    'thread.message': ThreadMessageEvent
+}
+
+const auth: WsAuthStrategy = {
+    authenticate: (send, token) => send({ method: 'auth.token', arguments: [token] }),
+    deauthenticate: send => send({ method: 'auth.logout' })
+}
+
+export const transport = new WsTransport<Pushes>({ pipe: new WebSocketPipe({ url: __WS_URL__ }), auth })
+
+// This socket carries every call, so it is the app's connectivity oracle.
+configureApiUX({ connectionSource: transport })
+
+export const api = new ApiClient<Methods>({
+    transport,
+    locale: () => i18n.global.locale.value,
+    cache: { ttl: 300, endpoints: { 'taxonomy.tree': true } },
+    errorHandlers: {
+        UNAUTHENTICATED: () => session.end(),
+        INVALID_INPUT: e => {
+            throw e
+        }
+    }
+})
+```
+
+Calls from components and stores:
+
+```ts
+import { ref } from 'vue'
+import { api } from '@/api'
+
+const host = await api.call('host.get', [42]) // Host; the global spinner shows while pending
+
+const saving = ref(false)
+await api.call('host.update', [{ id: 42, name: 'nas' }], { pending: saving }) // this ref instead
+
+const vlans = await api.call('vlan.list', [{}], { silent: true }) // no spinner, no toast; errors reject
+```
+
+`call(method, args, options?)` takes the arguments as a tuple (`Parameters<M[K]>`), unlike `RpcClient.call`'s variadic form.
+
+## ApiClient
+
+`ApiClientOptions`:
+
+- `transport` — any `@greendrake/rpc` `Transport`.
+- `cache?: CacheConfig` — the `@greendrake/rpc` `ResponseCache` config. The endpoint list decides two things at once: a listed method is served from and stored in the cache and goes out without a nonce; every other method carries a nonce and is never cached. List only stateless, platform-static reads.
+- `errorHandlers?: Record<string, (e: Error) => void>` — keyed by server error code (`codeOf`), consulted before the toast. A handler that throws bubbles the error to the caller with its `ApiError.details` intact, bypassing the toast; a handler that returns parks the call forever — its side effect (logout, redirect) supersedes the call's flow.
+- `locale?: () => string | undefined` — the UI language tag put in every request envelope, evaluated per call.
+
+`CallOptions`:
+
+- `pending` — `undefined`: the call holds a slot in `@greendrake/vue-kit`'s `useAppState` loading counter (the global spinner). A `Ref<boolean>`: that scoped busy flag is set instead. `false`: no loading indication.
+- `validate: (result) => boolean | Error` — rejects a result the server calls success: a returned `Error` is thrown, `false` throws `UnacceptableResultError`. Feeds the same retry pipeline as a failure.
+- `silent: true` — no loading indication and no error UX; errors reject straight to the caller. For background calls and callers owning their own error presentation.
+- `cache: false` — reads past the cache and does not store the answer. Cannot opt an unlisted method in and leaves the nonce rule alone.
+
+Cache access on the client: `invalidateCache(method, ...args)` (with args, that entry; without, the whole method), `clearCache()`, `primeCache(method, args, data)`.
+
+`setDebugDelay(method, ms)` — dev builds only: holds a call pending for `ms` so its loading state can be inspected; `0` clears. Inert in production.
+
+## Error-UX pipeline
+
+A non-silent call that fails, and that no error handler claimed, raises the failure on `useExceptionState()`, which shows one blocking toast at a time (`@greendrake/ui`'s `showToast`, `variant: 'warning'`, behind a full-screen overlay). The toast's kind is `classifyException(e)`:
+
+| kind | error | toast |
+| --- | --- | --- |
+| `notfound` | `NotFoundError` | acknowledge-only: "To the home page" when nothing usable is on screen yet, otherwise "OK" and the visitor stays put |
+| `oneoutcome` | any other `OneOutcomeError` | acknowledge-only, shows the error's own message |
+| `network` | `NetworkError` (fetch failure, socket closed) | Try again / Cancel |
+| `other` | everything else | Try again / Cancel; also reported to the error sink and logged with `console.warn` |
+
+Retry re-runs the same call (the button reads "Trying..." until the retried attempt settles, and a repeat failure counts up in the message); Cancel rejects the call's promise with the original error. A call's success clears its own toast, never one raised by a concurrent call. A same-kind failure while a toast is showing re-drives the existing toast rather than stacking another. The copy is `@greendrake/ui`'s `messages` (`errorNetwork`, `errorNotFound`, `errorOther`, `tryAgain`, `trying`, `cancel`, `ok`, `toHomePage`), overridable with `configureUiMessages`.
+
+`useExceptionState()`: state `exception: ExceptionKind` (`'network' | 'notfound' | 'oneoutcome' | 'other' | false`); action `fail(e: Error | false, options?: FailOptions)`, where `false` clears the toast. `FailOptions`: `retry?: () => Promise<void>`, `cancel?: () => void`, `onDismiss?: () => void` (runs when an acknowledge-only toast is acknowledged), `reportContext?: Record<string, unknown>` (attached to the error report). An app raises its own errors through the same store, e.g. `fail(new NotFoundError())` from a route that resolved to nothing.
+
+Boot wiring, `configureApiUX({ errorSink?, goHome?, connectionSource? })`:
+
+- `errorSink: ErrorSink` — `(error, context?) => void`; receives `other`-kind failures and abnormal WebSocket closes (`WebSocketClosedError.isAbnormal`) for reporting. Nothing is reported without one.
+- `goHome` — the not-found toast's home action; default `location.assign('/')`. `@greendrake/vue-app` sets it to `router.push('/')`. `getGoHome()` returns the configured function for modules that navigate home outside a component.
+- `connectionSource: ConnectionSource` — `{ readonly connected: boolean; onConnectionChange(listener) }`, read once when `useConnectivity` first materialises, so configure it before the store is first used. `@greendrake/rpc`'s `WsTransport` satisfies it as-is.
+
+### Offline parking
+
+A non-silent call that fails with a `NetworkError` while `useConnectivity().offline` is true is parked instead of toasted, provided re-issuing it cannot double-apply: it carries no nonce (a cacheable read), or the transport rejected it before writing it (`WebSocketClosedError` with `inFlight === false`). A parked call releases its global loading slot — a scoped `pending` ref stays on, so the submitting control stays disabled — waits on `whenOnline()`, and re-runs once per reconnection. A nonce-carrying request that was on the wire when the socket went may have executed server-side with only its response lost, so it keeps the toast and the decision stays with the user.
+
+## Connectivity
+
+`useConnectivity()` is a Pinia setup store:
+
+- `offline` — calls cannot currently succeed. Driven by the configured `ConnectionSource`; with none, by `navigator.onLine` and the window's `online`/`offline` events. With a source it starts `false` (not yet known), so the boot handshake does not flash offline surfaces.
+- `confirmedOffline` — offline and a reconnect attempt has failed too (the second consecutive `false` report). Surfaces that interrupt a working screen wait for this, so a socket that reconnects on its first try passes unremarked. Without a source the device signal confirms itself.
+- `deviceOffline` — the device's own claim. With a source it is never authoritative; it only picks wording.
+- `whenOnline(): Promise<void>` — resolves the moment calls can succeed; immediately when they already can.
+
+`retryWhenOnline(attempt)` re-runs `attempt` each time connectivity returns, for fetch sites that bypass `ApiClient` (static content, locale files) and would otherwise be a dead end after an offline miss. Only a `NetworkError` while `offline` is retried; anything else propagates on the first attempt.
+
+```ts
+import { fetchJson } from '@greendrake/util'
+import { retryWhenOnline } from '@greendrake/vue-api'
+
+const strings = await retryWhenOnline(() => fetchJson<Strings>(`/locales/${locale}.json`))
+```
+
+## Live updates
+
+`bindLive(transport, options)` is `@greendrake/rpc`'s `liveBinding` under this package's UX policy, and `useLive` is the component-scoped form that releases on unmount.
+
+```ts
+import { backgroundCall, useLive } from '@greendrake/vue-api'
+import { api, transport } from '@/api'
+
+useLive(transport, {
+    events: {
+        'thread.message': { when: pushed => pushed.thread_id === props.threadId }
+    },
+    resync: async () => {
+        thread.value = await api.call('thread.get', [props.threadId], backgroundCall(true))
+    }
+})
+```
+
+The mechanism — relevance, `apply` versus `resync`, the reconnect re-read, coalescing, release — is documented in `@greendrake/rpc`. What this package adds is what happens around a `resync`:
+
+- It runs unseen. `backgroundCall(background)` is the one place that decides what that means: `{ silent: true }`, which bypasses both the loading counter and the error-UX pipeline. `pending: false` is not enough — it suppresses the spinner and still raises the blocking retry toast over a screen the user is reading.
+- Its failure neither interrupts nor vanishes. A `NotFoundError` is dropped (the entity went away while the socket was down; the next navigation says so), a `NetworkError` is dropped (the socket went again mid-read, and the binding's own reconnect rule re-reads when it returns), and anything else goes to the `errorSink` configured through `configureApiUX` — reported, never toasted.
+- It must read past a response cache the missed pushes would have invalidated: invalidate the entries the read would hit, then read, so the stale entry is repaired rather than stepped around.
+
+`backgroundCall` also serves a table's loader, which is where a panel's re-read actually calls the API — see `@greendrake/ui-data`'s loader contract:
+
+```ts
+const loader = listLoader((args, background) => api.call('admin.thread.list', [args], backgroundCall(background)))
+```

package/package.json

@@ -0,0 +1,53 @@
+{
+    "name": "@greendrake/vue-api",
+    "version": "0.1.0",
+    "description": "Vue binding of @greendrake/rpc: loading-state wiring, response cache, error-UX pipeline, silent calls, live bindings to server push",
+    "license": "MIT",
+    "author": "Eugene Greendrake <eugene@greendrake.nz>",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/greendrake/lib.git",
+        "directory": "vue-api"
+    },
+    "homepage": "https://github.com/greendrake/lib/tree/main/vue-api#readme",
+    "bugs": {
+        "url": "https://github.com/greendrake/lib/issues"
+    },
+    "type": "module",
+    "main": "src/main.ts",
+    "types": "src/main.ts",
+    "exports": {
+        ".": {
+            "types": "./src/main.ts",
+            "default": "./src/main.ts"
+        }
+    },
+    "files": [
+        "src"
+    ],
+    "sideEffects": false,
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "check": "vue-tsc --noEmit"
+    },
+    "prettier": "@greendrake/dev-config/prettier",
+    "dependencies": {
+        "@greendrake/rpc": "0.1.0",
+        "@greendrake/ui": "0.1.0",
+        "@greendrake/util": "0.1.0",
+        "@greendrake/vue-kit": "0.1.0"
+    },
+    "peerDependencies": {
+        "pinia": "^3.0.4",
+        "vue": "^3.5.34"
+    },
+    "devDependencies": {
+        "@greendrake/dev-config": "0.1.0",
+        "pinia": "^3.0.4",
+        "typescript": "6.0.3",
+        "vue": "^3.5.34",
+        "vue-tsc": "^2.2.0"
+    }
+}

package/src/ApiClient.ts

@@ -0,0 +1,299 @@
+import { isRef, type Ref } from 'vue'
+import { createDeferred, NetworkError, TimeOutPromise } from '@greendrake/util'
+import { ResponseCache, WebSocketClosedError, codeOf, packRequest } from '@greendrake/rpc'
+import type { CacheConfig, MethodMap, MethodMapConstraint, Transport } from '@greendrake/rpc'
+import { useAppState } from '@greendrake/vue-kit'
+import { useConnectivity } from './connectivity'
+import { useExceptionState } from './exceptionState'
+
+export class UnacceptableResultError extends Error {
+    constructor() {
+        super('Unacceptable result')
+        this.name = 'UnacceptableResultError'
+    }
+}
+
+export interface CallOptions {
+    // Loading indication: undefined → the global spinner counter; a Ref →
+    // that scoped busy flag; false → none (a button label is already
+    // communicating progress).
+    pending?: Ref<boolean> | false
+    // Reject results the server calls success but the caller cannot accept.
+    // Returning an Error throws it; returning false throws
+    // UnacceptableResultError. Feeds the same retry pipeline as failures.
+    validate?: (result: unknown) => boolean | Error
+    // Bypass loading indication AND the error-UX pipeline: errors reject
+    // straight to the caller. For background calls (token refresh) and callers
+    // owning their own error presentation.
+    silent?: boolean
+    // Refuse the response cache for this call: read past whatever is stored,
+    // and do not store the answer either. For the read whose whole promise is
+    // freshness on a method that is worth caching everywhere else — the same
+    // query serving a "what's here right now" surface and a search box. It
+    // says nothing about the method: an unlisted one cannot be opted in, and a
+    // listed one keeps its nonce-lessness (see `call`). See DATA_CACHING.md §4.
+    cache?: false
+}
+
+export interface ApiClientOptions {
+    transport: Transport
+    // Which methods may be answered from an in-browser response cache, and for
+    // how long. THE list drives two things at once — see `call` below: a listed
+    // method is served/stored from the cache and goes out nonce-less; every
+    // other method carries a nonce and is never cached. Only list stateless,
+    // platform-static reads — never per-user data that mutates in-session.
+    cache?: CacheConfig
+    // Per-error-code interception, keyed by code (the error's message). A
+    // handler that re-throws bubbles the error to the caller (bypassing the
+    // toast); a handler that returns parks the call forever — its flow is
+    // abandoned, superseded by the handler's side effect (logout, redirect).
+    errorHandlers?: Record<string, (e: Error) => void>
+    // The caller's UI language tag, evaluated per request. Server-resolved
+    // labels (taxonomy names, breadcrumbs, facet chips) come back in it, so a
+    // locale switch must take effect on the next call rather than at
+    // construction — and it scopes the response cache, which would otherwise
+    // answer a call made in one language with a reply written in another.
+    locale?: () => string | undefined
+}
+
+// The Vue-facing API client: typed calls with loading-state wiring, response
+// caching, and the blocking-toast retry pipeline.
+export class ApiClient<M extends MethodMapConstraint<M> = MethodMap> {
+    readonly transport: Transport
+    readonly #cache?: ResponseCache
+    readonly #errorHandlers?: Record<string, (e: Error) => void>
+    // Dev-only per-method artificial delays (ms), keyed by method name. See
+    // setDebugDelay / #debugDelay.
+    readonly #debugDelays = new Map<string, number>()
+    readonly #locale?: () => string | undefined
+
+    constructor(options: ApiClientOptions) {
+        this.transport = options.transport
+        // The locale scopes the cache as well as stamping the request: a
+        // response carries server-resolved labels in the language it was asked
+        // in, so it may only answer a later call asking in that same one.
+        this.#cache = options.cache && new ResponseCache(options.cache, options.locale)
+        this.#errorHandlers = options.errorHandlers
+        this.#locale = options.locale
+    }
+
+    // DEV DEBUGGING ONLY. Register an artificial delay (ms) for a method, held
+    // while the call is pending — so the pending/loading state (spinner, busy
+    // ref, disabled controls) can be inspected in devtools before the response
+    // lands. Set it from the console, e.g. `api.setDebugDelay('search.listings',
+    // 3000)`; pass 0 to clear. The delay is applied only in dev builds (see
+    // #debugDelay), so a stray registration is inert in production. A `read`
+    // served from cache is instant and bypasses the delay (no pending to see);
+    // opt out of the cache to delay it.
+    setDebugDelay(method: keyof M & string, ms: number): void {
+        if (ms > 0) {
+            this.#debugDelays.set(method, ms)
+        } else {
+            this.#debugDelays.delete(method)
+        }
+    }
+
+    // Node-safe DEV probe (mirrors rpc/protocol.ts): import.meta.env only exists
+    // under Vite, and is statically replaced so the delay is dead-code-stripped
+    // from production builds.
+    async #debugDelay(method: string): Promise<void> {
+        const ms = this.#debugDelays.get(method)
+        if (ms && (import.meta as ImportMeta & { env?: { DEV?: boolean } }).env?.DEV) {
+            await TimeOutPromise.wait(ms)
+        }
+    }
+
+    // The one way to invoke a method. Whether the request carries a nonce is
+    // not a per-call-site choice: it follows from the cache config, which is
+    // the single declaration of "this answer may be reused".
+    //
+    //   listed in cache.endpoints → served from / stored in the cache, sent
+    //                               WITHOUT a nonce
+    //   not listed                → straight to the wire WITH a nonce
+    //
+    // Why that pairing, and why it is safe to let one list decide both: a
+    // nonce's only server-side effect is `SETNX` dedup (the server's dispatch
+    // rejects a repeat with DUPLICATE_REQUEST), and a fresh random nonce is
+    // minted per call, so on a read it buys nothing and costs one Redis write.
+    // Sending it is therefore harmless but pointless — which makes "cacheable"
+    // the only axis worth declaring. The protocol's rule that nonce-bearing
+    // requests are never cached is preserved by construction.
+    //
+    // The trade being made: a method that is idempotent but deliberately
+    // uncached — left off the list, not merely read past it by a call site —
+    // now pays that one Redis write per call. Revisit the split — declaring idempotency per method,
+    // separate from cacheability — if those writes ever start to matter, or if
+    // server-side response caching is built (there is none today, so nonce-less
+    // buys nothing extra), or if `Request.Abort` (which cancels by nonce) gets
+    // wired up on a cacheable method.
+    async call<K extends keyof M & string>(method: K, args: Parameters<M[K]>, options?: CallOptions): Promise<Awaited<ReturnType<M[K]>>> {
+        const cacheable = this.#cache?.ttlFor(method) !== false && this.#cache !== undefined
+        // Refusing the cache is about this answer, not about the method: it
+        // suppresses the lookup and the store, and deliberately does NOT touch
+        // the nonce. The protocol's rule runs one way — a nonce-bearing request
+        // is never cached — so a cacheable method read fresh stays nonce-less
+        // and keeps what nonce-lessness buys it, which is not only the Redis
+        // write it saves but offline parking: a nonce-less read dropped in
+        // flight waits out the outage instead of asking the user to retry it.
+        const useCache = cacheable && options?.cache !== false
+        if (useCache) {
+            const cached = this.#cache!.get(method, args)
+            if (cached.hit) {
+                return cached.data as Awaited<ReturnType<M[K]>>
+            }
+        }
+        return this.#run(!cacheable, useCache, method, args, options)
+    }
+
+    invalidateCache(method: keyof M & string, ...args: unknown[]): void {
+        this.#cache?.invalidate(method, ...args)
+    }
+
+    // Drop every cached response. What the session identity changing costs: a
+    // cached read was answered for whoever was signed in when it was made, and
+    // the audience-dependent ones (what a listing shows, what a search returns,
+    // what an account owns) do not survive that change even when their TTL has
+    // not run out.
+    clearCache(): void {
+        this.#cache?.clear()
+    }
+
+    // Seed the cache from a server push already carrying the full DTO a read
+    // would return. `args` must match the read's args to hit the same key.
+    primeCache(method: keyof M & string, args: unknown[], data: unknown): void {
+        this.#cache?.prime(method, args, data)
+    }
+
+    async #run<K extends keyof M & string>(nonce: boolean, store: boolean, method: K, args: Parameters<M[K]>, options?: CallOptions): Promise<Awaited<ReturnType<M[K]>>> {
+        const send = async (): Promise<Awaited<ReturnType<M[K]>>> => {
+            const result = await this.transport.send(packRequest(method, args, nonce, this.#locale?.()))
+            if (options?.validate) {
+                const verdict = options.validate(result)
+                if (verdict instanceof Error) {
+                    throw verdict
+                }
+                if (!verdict) {
+                    throw new UnacceptableResultError()
+                }
+            }
+            // Stores exactly the responses the config asked to be reusable,
+            // minus any the caller read fresh: those must not be left behind
+            // for the next reader either, or refusing the cache would amount to
+            // refreshing it. set() is a no-op for anything unlisted.
+            if (store) {
+                this.#cache?.set(method, args, result)
+            }
+            return result as Awaited<ReturnType<M[K]>>
+        }
+
+        if (options?.silent) {
+            return send()
+        }
+
+        const appState = useAppState()
+        const exceptionState = useExceptionState()
+        const connectivity = useConnectivity()
+        const pending = options?.pending
+        const switchLoading = (on: boolean): void => {
+            if (isRef(pending)) {
+                pending.value = on
+            } else if (pending === undefined) {
+                appState.setLoading(on)
+            }
+        }
+
+        let settleRetryAttempt: (() => void) | undefined
+        // Whether THIS call raised the exception currently on screen. A
+        // success only clears its own error toast — never one a concurrent
+        // call is showing (e.g. a background list refresh must not dismiss a
+        // navigation's "not found" toast it had nothing to do with).
+        let raisedException = false
+        // Drop this call's own toast once it no longer needs one: on success,
+        // and on parking to wait out an outage (which takes the failure off
+        // the user's hands entirely). Clearing the flag with it keeps the
+        // claim honest across a park — whatever appears on screen afterwards
+        // belongs to someone else until this call raises again.
+        const clearOwnException = (): void => {
+            if (raisedException && exceptionState.exception) {
+                exceptionState.fail(false)
+            }
+            raisedException = false
+        }
+        while (true) {
+            switchLoading(true)
+            try {
+                // Held inside the pending window so the delay prolongs the
+                // observable loading state (dev only; see #debugDelay).
+                await this.#debugDelay(method)
+                const result = await send()
+                switchLoading(false)
+                clearOwnException()
+                return result
+            } catch (e) {
+                settleRetryAttempt?.()
+                // Offline: wait for the connection instead of asking the user
+                // to. Each attempt re-runs send(), which mints a fresh nonce
+                // (see packRequest), so the server's SETNX dedup cannot span a
+                // retry — parking is only safe where re-issuing cannot
+                // double-apply. That holds when the request demonstrably never
+                // left this machine (the socket was already down, so the
+                // transport rejected before writing), and when it carries no
+                // nonce at all (a cacheable read; see call). A nonce-carrying
+                // request that was on the wire when the socket went may have
+                // executed with only its response lost, so whether to re-send
+                // it stays the user's decision and keeps the toast.
+                const neverSent = e instanceof WebSocketClosedError && !e.inFlight
+                if (e instanceof NetworkError && connectivity.offline && (!nonce || neverSent)) {
+                    // Park OUTSIDE the loading window: holding the global
+                    // counter for the whole outage would pin the spinner and
+                    // wedge isFirstLoading (which flips when the counter
+                    // empties). A scoped pending ref is the opposite case and
+                    // stays on — the page remains interactive under the
+                    // offline banner, and that busy flag is what keeps its
+                    // control disabled so a form cannot queue duplicate
+                    // submissions that all fire at once on reconnect.
+                    if (pending === undefined) {
+                        appState.setLoading(false)
+                    }
+                    clearOwnException()
+                    await connectivity.whenOnline()
+                    continue
+                }
+                switchLoading(false)
+                // Keyed by backend code, which for a *_NOT_FOUND lives on the
+                // error rather than in its message — see codeOf.
+                const handler = this.#errorHandlers?.[codeOf(e as Error)]
+                if (handler) {
+                    // Pass the original error so a handler that re-throws (the
+                    // bubble pattern) preserves its payload (ApiError.details).
+                    handler(e as Error)
+                    // A non-throwing handler's side effect (logout, redirect)
+                    // supersedes this call's flow: park it forever rather than
+                    // lie with an undefined result.
+                    return new Promise<never>(() => {})
+                }
+                const decision = createDeferred<void>()
+                const retryAttempt = createDeferred<void>()
+                settleRetryAttempt = retryAttempt.resolve
+                exceptionState.fail(e as Error, {
+                    // The toast's "Trying..." state lasts until the retried
+                    // attempt settles (tracked via retryAttempt).
+                    retry: () => {
+                        decision.resolve()
+                        return retryAttempt.promise
+                    },
+                    cancel: decision.reject,
+                    // Identifies the failed RPC in error reports. Args are
+                    // deliberately omitted — they can carry credentials/PII.
+                    reportContext: { apiMethod: method }
+                })
+                raisedException = true
+                try {
+                    await decision.promise
+                } catch {
+                    throw e
+                }
+            }
+        }
+    }
+}

package/src/ExceptionToast.vue

@@ -0,0 +1,112 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { messages } from '@greendrake/ui'
+import { getGoHome } from './uxConfig'
+import type { ExceptionKind } from './exceptionState'
+
+const props = defineProps<{
+    error: Error
+    kind: Exclude<ExceptionKind, false>
+    // Whether a usable page is already on screen (see exceptionState). It
+    // decides what a not-found can offer: somewhere to go, or just an
+    // acknowledgement.
+    canStayPut: boolean
+    hide: () => void
+    retry: () => Promise<void> | void
+    cancel: () => void
+}>()
+
+const counter = ref(1)
+const isRetrying = ref(false)
+
+const kindMessages = computed<Record<string, string>>(() => ({
+    other: messages.errorOther,
+    network: messages.errorNetwork,
+    notfound: messages.errorNotFound
+}))
+
+// A not-found reached from a page the visitor is already on leaves them there:
+// the navigation never happened, what they were looking at is still behind the
+// toast, and offering the home page would be sending them away from it. Only a
+// visitor who arrived straight at the missing thing — a shared link opened
+// cold, so nothing else is loaded — has anywhere to be sent.
+const notFoundLeavesNowhere = computed(() => props.kind === 'notfound' && !props.canStayPut)
+
+const button = computed(() => {
+    if (notFoundLeavesNowhere.value) {
+        return messages.toHomePage
+    }
+    if (props.kind === 'oneoutcome' || props.kind === 'notfound') {
+        return messages.ok
+    }
+    return isRetrying.value ? messages.trying : messages.tryAgain
+})
+
+// Retryable kinds (network/other) get a Cancel button; acknowledge-only kinds
+// (notfound/oneoutcome) have a single outcome.
+const isAcknowledgeOnly = computed(() => props.kind === 'notfound' || props.kind === 'oneoutcome')
+
+const onClick = (): void => {
+    switch (props.kind) {
+        case 'notfound':
+            props.cancel()
+            if (notFoundLeavesNowhere.value) {
+                getGoHome()()
+            }
+            break
+        case 'oneoutcome':
+            props.cancel()
+            break
+        default: {
+            const retried = props.retry()
+            if (retried instanceof Promise) {
+                isRetrying.value = true
+                retried
+                    .then(() => {
+                        counter.value++
+                    })
+                    .finally(() => {
+                        isRetrying.value = false
+                    })
+            }
+            break
+        }
+    }
+}
+
+const message = computed(() => {
+    if (props.kind === 'oneoutcome') {
+        return props.error.message || messages.errorOther
+    }
+    return `${kindMessages.value[props.kind]}${counter.value > 1 ? ` (${counter.value})` : ''}`
+})
+</script>
+<template>
+    <Teleport to="body">
+        <div class="BlockingOverlay" />
+    </Teleport>
+    <div class="ExceptionToast">
+        <div>{{ message }}</div>
+        <div class="ExceptionToast__buttons">
+            <button v-if="!isAcknowledgeOnly" @click.prevent="cancel">{{ messages.cancel }}</button>
+            <div />
+            <button :class="{ disabled: isRetrying }" @click.prevent="onClick">{{ button }}</button>
+        </div>
+    </div>
+</template>
+<style lang="scss" scoped>
+.ExceptionToast {
+    &__buttons {
+        margin-top: 8px;
+        display: flex;
+        justify-content: space-between;
+        div {
+            flex-grow: 1;
+        }
+        button {
+            padding: 0 8px;
+            height: 32px;
+        }
+    }
+}
+</style>

package/src/connectivity.ts

@@ -0,0 +1,78 @@
+import { ref } from 'vue'
+import { defineStore } from 'pinia'
+import { createDeferred } from '@greendrake/util'
+import { getConnectionSource } from './uxConfig'
+
+// Connectivity as the app's UX layer sees it, driven by the transport that
+// actually carries the calls (see ConnectionSource) rather than by
+// navigator.onLine — a captive portal, a dead tunnel or an unreachable backend
+// all leave the device "online" while nothing can succeed.
+//
+// A setup store: the subscription below is a side effect that must run exactly
+// once, when the store first materialises.
+export const useConnectivity = defineStore('connectivity', () => {
+    const source = getConnectionSource()
+
+    // The device's own claim. Never authoritative — it only picks the wording
+    // ("you appear to be offline" vs "cannot reach the site"), and kicks a
+    // waiting reconnect early where the app wires that.
+    const deviceOffline = ref(!navigator.onLine)
+    // With a transport oracle, connectivity starts out "not yet known" rather
+    // than offline: the eager connect at boot has not had its chance yet, and
+    // flipping now would flash the offline surfaces over every start. Without
+    // one, the device signal is the whole story and is authoritative already.
+    const offline = ref(!source && deviceOffline.value)
+    // Offline *and* an attempt to come back has failed too. The surfaces that
+    // interrupt a working screen wait for this, so a socket that reconnects on
+    // its first try — a rolling deploy, a momentary drop — passes unremarked.
+    const confirmedOffline = ref(offline.value)
+    // Calls parked until connectivity returns. Plain array, not state: wiring,
+    // and settling them must not depend on anything reactive.
+    const waiters: Array<() => void> = []
+
+    const connected = (): void => {
+        offline.value = false
+        confirmedOffline.value = false
+        waiters.splice(0).forEach(resolve => resolve())
+    }
+
+    // What confirms an outage differs by source: the transport reports once
+    // per failed attempt, so the second consecutive report is the confirmation,
+    // while the device signal has no attempts to count and speaks for itself.
+    const disconnected = (confirmed: boolean): void => {
+        confirmedOffline.value = confirmed || offline.value
+        offline.value = true
+    }
+
+    addEventListener('online', () => {
+        deviceOffline.value = false
+        if (!source) {
+            connected()
+        }
+    })
+    addEventListener('offline', () => {
+        deviceOffline.value = true
+        if (!source) {
+            disconnected(true)
+        }
+    })
+    source?.onConnectionChange(up => (up ? connected() : disconnected(false)))
+
+    // Resolves the moment calls can succeed again — immediately when they
+    // already can. Event-driven: no polling, no timers.
+    const whenOnline = (): Promise<void> => {
+        if (!offline.value) {
+            return Promise.resolve()
+        }
+        const { promise, resolve } = createDeferred()
+        waiters.push(resolve)
+        return promise
+    }
+
+    return {
+        offline,
+        confirmedOffline,
+        deviceOffline,
+        whenOnline
+    }
+})

package/src/exceptionState.ts

@@ -0,0 +1,121 @@
+import { h } from 'vue'
+import { defineStore } from 'pinia'
+import { NetworkError } from '@greendrake/util'
+import { NotFoundError, OneOutcomeError, WebSocketClosedError } from '@greendrake/rpc'
+import { showToast } from '@greendrake/ui'
+import { useAppState } from '@greendrake/vue-kit'
+import ExceptionToast from './ExceptionToast.vue'
+import { getErrorSink } from './uxConfig'
+
+export type ExceptionKind = 'network' | 'notfound' | 'oneoutcome' | 'other' | false
+
+export const classifyException = (e: Error): Exclude<ExceptionKind, false> => {
+    if (e instanceof NotFoundError) return 'notfound'
+    if (e instanceof OneOutcomeError) return 'oneoutcome'
+    if (e instanceof NetworkError) return 'network'
+    return 'other'
+}
+
+interface ExceptionState {
+    exception: ExceptionKind
+}
+
+export interface FailOptions {
+    retry?: () => Promise<void>
+    cancel?: () => void
+    // Runs when the user acknowledges an acknowledge-only (notfound/
+    // oneoutcome) toast — the UI-side successor of the dismiss callback the
+    // old transport error type carried.
+    onDismiss?: () => void
+    // Attached to the error report (e.g. the failed RPC's method name).
+    reportContext?: Record<string, unknown>
+}
+
+// Non-reactive callback slots: wiring, not state. Refreshed on every fail()
+// so a repeated same-kind failure re-drives the existing toast.
+const handlers: {
+    hideToast?: () => void
+    retry?: () => Promise<void>
+    cancel?: () => void
+    onDismiss?: () => void
+} = {}
+
+// Global exception surface: one blocking toast at a time, with Retry/Cancel
+// wired back to the failed call's deferred (see ApiClient). fail(false)
+// clears it.
+export const useExceptionState = defineStore('exceptionstate', {
+    state: (): ExceptionState => ({
+        exception: false
+    }),
+    actions: {
+        fail(e: Error | false, options?: FailOptions): void {
+            if (!e) {
+                if (this.exception !== false) {
+                    this.exception = false
+                    handlers.hideToast?.()
+                    delete handlers.hideToast
+                }
+                return
+            }
+            const kind = classifyException(e)
+            // Report genuine unexpected failures. notfound/oneoutcome and
+            // ordinary network blips are expected operational conditions and
+            // would only be noise — but an *abnormal* WebSocket close is
+            // reported so server-side or idle-timeout drops stay diagnosable.
+            // Done before the same-kind dedup below so every distinct report
+            // fires even while a toast of the same kind is showing.
+            const sink = getErrorSink()
+            if (sink && (kind === 'other' || (e instanceof WebSocketClosedError && e.isAbnormal))) {
+                sink(e, options?.reportContext)
+            }
+            // Leave a trace whether or not a sink is configured, and in shipped
+            // builds as well as dev. This toast is the one surface saying a call
+            // failed unexpectedly, and on a device there are no devtools to open
+            // — but `logcat` and the Web Inspector both carry the console, so
+            // without this line an on-device failure is undiagnosable. `warn`
+            // for the reason the RPC layer picks it: the condition is handled
+            // and surfaced, and an error would fail the E2E fixtures' teardown
+            // guard on specs that provoke this toast deliberately.
+            // One preformatted string, not several arguments: the native
+            // WebView console bridge does not serialise them, so anything
+            // structured reaches `logcat` as a bare "[object Object]".
+            if (kind === 'other') {
+                const where = options?.reportContext ? ` ${JSON.stringify(options.reportContext)}` : ''
+                console.warn(`[exception]${where} ${e.name}: ${e.message}`)
+            }
+            handlers.retry = options?.retry
+            handlers.cancel = options?.cancel
+            handlers.onDismiss = options?.onDismiss
+            if (this.exception === kind) {
+                return
+            }
+            handlers.hideToast?.()
+            this.exception = kind
+            const { destroy } = showToast({
+                content: h(ExceptionToast, {
+                    error: e,
+                    kind,
+                    // Whether there is a page to stay on. A committed
+                    // navigation is exactly that: something usable is already
+                    // on screen, so a not-found has somewhere to leave the
+                    // visitor and needs offer them nothing. Read here rather
+                    // than in the toast — this is a store action, so pinia is
+                    // certainly active, and the answer cannot change while the
+                    // toast blocks the app anyway.
+                    canStayPut: useAppState().hasNavigated,
+                    retry: () => handlers.retry?.(),
+                    hide: () => destroy(),
+                    cancel: () => {
+                        destroy()
+                        this.exception = false
+                        handlers.cancel?.()
+                        handlers.onDismiss?.()
+                    }
+                }),
+                hideOnClick: false,
+                variant: 'warning'
+            })
+            handlers.hideToast = destroy
+        }
+    }
+})

package/src/live.ts

@@ -0,0 +1,50 @@
+import { onUnmounted } from 'vue'
+import { NetworkError } from '@greendrake/util'
+import { NotFoundError, liveBinding } from '@greendrake/rpc'
+import type { LiveOptions, PushMapConstraint, WsTransport } from '@greendrake/rpc'
+import type { CallOptions } from './ApiClient'
+import { getErrorSink } from './uxConfig'
+
+// The call options a background read runs under, in one place so every resync
+// and every background loader means the same thing by "background". `silent`
+// is the option that matters: it bypasses the loading counter AND the
+// error-UX pipeline, whereas `pending: false` suppresses only the spinner and
+// would still put the blocking retry toast over a screen the user is reading.
+export const backgroundCall = (background: boolean): CallOptions | undefined => (background ? { silent: true } : undefined)
+
+// @greendrake/rpc's liveBinding under this package's UX policy: a resync runs
+// unseen, and its failure neither interrupts the user nor vanishes.
+//
+// A resync must read in the background (see backgroundCall) and must not be
+// served by a response cache the missed pushes would have invalidated —
+// invalidate the entries its read would hit, then read, so the stale entry is
+// repaired for the next reader rather than merely stepped around.
+export const bindLive = <PEvents extends PushMapConstraint<PEvents>, PData extends PushMapConstraint<PData>>(transport: WsTransport<PEvents, PData>, options: LiveOptions<PEvents, PData>): (() => void) => {
+    const { resync } = options
+    if (!resync) return liveBinding(transport, options)
+    return liveBinding(transport, {
+        ...options,
+        resync: async () => {
+            try {
+                await resync()
+            } catch (e) {
+                // Gone while the socket was down: there is nothing to show and
+                // nothing to report — the next navigation says so.
+                if (e instanceof NotFoundError) return
+                // The socket went again mid-read (WebSocketClosedError is a
+                // NetworkError). The binding's own reconnect rule owns this
+                // one: it re-reads when the socket returns, so reporting it
+                // would file one entry per binding per blip.
+                if (e instanceof NetworkError) return
+                getErrorSink()?.(e as Error, { resync: true })
+            }
+        }
+    })
+}
+
+// Component-scoped live binding: releases with the component. The transport is
+// passed explicitly — an HTTP-only app has none, which is a compile-time error
+// here rather than a silent no-op.
+export const useLive = <PEvents extends PushMapConstraint<PEvents>, PData extends PushMapConstraint<PData>>(transport: WsTransport<PEvents, PData>, options: LiveOptions<PEvents, PData>): void => {
+    onUnmounted(bindLive(transport, options))
+}

package/src/main.ts

@@ -0,0 +1,6 @@
+export { ApiClient, UnacceptableResultError, type ApiClientOptions, type CallOptions } from './ApiClient'
+export { useExceptionState, classifyException, type ExceptionKind, type FailOptions } from './exceptionState'
+export { configureApiUX, getGoHome, type ConnectionSource, type ErrorSink } from './uxConfig'
+export { useConnectivity } from './connectivity'
+export { retryWhenOnline } from './retryWhenOnline'
+export { backgroundCall, bindLive, useLive } from './live'

package/src/retryWhenOnline.ts

@@ -0,0 +1,29 @@
+import { NetworkError } from '@greendrake/util'
+import { useConnectivity } from './connectivity'
+
+// Re-runs `attempt` each time connectivity returns, for as long as the app is
+// offline. For the fetch sites that reach the network WITHOUT going through
+// ApiClient — static content, the i18n locale file — whose failure would
+// otherwise be a dead end: nothing re-drives them, so an offline miss leaves
+// the surface permanently empty even after the connection is back.
+//
+// ApiClient keeps its own integrated version of this loop rather than calling
+// here: its parking interleaves with the loading windows, the retry-toast
+// deferral and the in-flight carve-out, none of which apply to a plain fetch.
+//
+// Only network failures while the oracle corroborates an outage are retried;
+// everything else (a 404, a parse error, a network failure the oracle does not
+// see) propagates on the first attempt.
+export const retryWhenOnline = async <T>(attempt: () => Promise<T>): Promise<T> => {
+    const connectivity = useConnectivity()
+    while (true) {
+        try {
+            return await attempt()
+        } catch (e) {
+            if (!(e instanceof NetworkError) || !connectivity.offline) {
+                throw e
+            }
+            await connectivity.whenOnline()
+        }
+    }
+}

package/src/uxConfig.ts

@@ -0,0 +1,41 @@
+// App-level wiring for the error-UX pipeline, injected at boot. Inverted
+// dependencies: this package never knows where error reports go or how the
+// app navigates home.
+
+export type ErrorSink = (error: Error, context?: Record<string, unknown>) => void
+
+// The connectivity oracle useConnectivity reads. Supplied by the app because
+// only it knows which transport carries its calls — @greendrake/rpc's
+// WsTransport satisfies this shape as-is. An app that wires none falls back to
+// navigator.onLine, which is all an HTTP-only client has to go on.
+export interface ConnectionSource {
+    // Whether calls can currently succeed.
+    readonly connected: boolean
+    // Fires per underlying transition, NOT deduplicated: repeated `false`
+    // reports are consecutive failed attempts, which is what distinguishes a
+    // momentary drop from a sustained outage.
+    onConnectionChange(listener: (connected: boolean) => void): void
+}
+
+interface ApiUXConfig {
+    // Receives genuine unexpected failures (and abnormal WebSocket drops) for
+    // reporting — e.g. the visit subsystem's error channel.
+    errorSink?: ErrorSink
+    // Drives the not-found toast's "To the home page" action; typically
+    // router.push('/'). @greendrake/vue-app wires this automatically.
+    goHome?: () => void
+    // Read once, when useConnectivity is first instantiated.
+    connectionSource?: ConnectionSource
+}
+
+const config: ApiUXConfig = {}
+
+export const configureApiUX = (overrides: ApiUXConfig): void => {
+    Object.assign(config, overrides)
+}
+
+export const getErrorSink = (): ErrorSink | undefined => config.errorSink
+
+export const getConnectionSource = (): ConnectionSource | undefined => config.connectionSource
+
+export const getGoHome = (): (() => void) => config.goHome ?? (() => location.assign('/'))