@abide/abide 0.42.0 → 0.43.0

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

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

package/src/lib/ui/socketChannel.ts

@@ -80,7 +80,13 @@ export function getSocketChannel(): SocketChannel {
         if (document.hidden) {
             return
         }
-        if (ws && (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)) {
+        /* A socket reference in ANY non-closed state means one is already in play — bail.
+           CONNECTING/OPEN are healthy; CLOSING means a close event is still pending and the
+           close handler (which alone nulls `ws` and re-arms the backoff) hasn't run yet.
+           Spawning here would orphan that socket: its deferred close fires against the shared
+           `ws`, draining the fresh connection's subs and nulling it. The close handler always
+           clears `ws`, so reconnection is never stranded — it just sequences after the close. */
+        if (ws) {
             return
         }
         const scheme = window.location.protocol === 'https:' ? 'wss:' : 'ws:'

package/src/lib/ui/types/Scope.ts

@@ -1,4 +1,5 @@
 import type { computed } from '../computed.ts'
+import type { effect } from '../effect.ts'
 import type { linked } from '../linked.ts'
 import type { Cell } from '../runtime/types/Cell.ts'
 import type { Patch } from '../runtime/types/Patch.ts'
@@ -35,14 +36,28 @@ export type Scope = {
     cell: <T>(path: string) => Cell<T>
     derive: <T>(path: string, compute: () => T) => () => T
     snapshot: () => unknown
-    /* the `.value`-cell signal forms, reachable only through a scope (the standalone
-       `state`/`linked`/`computed` are no longer exported): a writable `state(x, transform)`
-       gate, a reseeding `linked`, and the read-only `computed(compute)`. A writable
-       computed does not exist — that write is expressed at the binding (`bind:value={{
-       get, set }}`). The serializable computed doc slot is `derive` above. */
+    /* The reactive primitives — namespaced under the scope, but AMBIENT-bound, not
+       receiver-bound (unlike the data methods above, which act on THIS scope's doc).
+       `state`/`linked`/`computed`/`effect` create their cell in whatever scope is currently
+       rendering and own their teardown to the finest ambient BUILD WINDOW — a control-flow
+       branch or list row, not the whole component. So `someScope.computed(fn)` does NOT
+       create state in someScope; the receiver is namespacing only, the cells bind the
+       ambient window. Binding them to the receiver instead would leak a branch-local cell
+       past a branch flip (the build window is finer-grained than the lexical scope — see
+       ADR-0012). Forms: a writable `state(x, transform)` gate, a reseeding `linked`, the
+       read-only `computed(compute)` (a writable computed does not exist — that write is
+       expressed at the binding `bind:value={{ get, set }}`; the serializable computed doc
+       slot is `derive` above), and `effect`, the reaction re-run on dep change (the SSR
+       back-end strips it — effects are client lifecycle). */
     state: typeof state
     linked: typeof linked
     computed: typeof computed
+    effect: typeof effect
+    /* Adopts a teardown into this scope's lifetime — the build's reactivity stopper
+       (effects/listeners), run first on `dispose` (before children, before capabilities).
+       Internal: the mount core registers the build's disposer here so a component has ONE
+       teardown (`dispose`) rather than a separate stop + dispose composed at every site. */
+    own: (dispose: () => void) => void
     /* tree */
     child: (initial?: unknown) => Scope
     root: () => Scope

package/template/CLAUDE.md

@@ -15,7 +15,7 @@ at `node_modules/@abide/abide/README.md`.
 
 - One export per file, named after the file. No barrels — import each name by its
   own path (`@abide/abide/server/GET`, `@abide/abide/shared/cache`, …).
-- RPC verbs live in `src/server/rpc/<name>.ts`; sockets in `src/server/sockets/`;
+- RPCs live in `src/server/rpc/<name>.ts`; sockets in `src/server/sockets/`;
   pages are `**/page.abide`, layouts `**/layout.abide`.
 - Generated types land in `src/.abide/` — do not hand-edit them; run `abide dev`/
   `abide check` to regenerate.

package/template/src/server/rpc/getHello.ts

@@ -1,8 +1,8 @@
 /*
-RPC module — every file under src/server/rpc/ exposes exactly one verb-bound remote
+RPC module — every file under src/server/rpc/ exposes exactly one RPC: a remote
 function. The filename is the export name and the URL path (under `/rpc/`),
-and the imported verb (GET / POST / PUT / PATCH / DELETE / HEAD) picks the
-HTTP method. The bundler swaps the runtime per build target: direct call on
+and the imported method helper (GET / POST / PUT / PATCH / DELETE / HEAD) picks
+the HTTP method. The bundler swaps the runtime per build target: direct call on
 the server, fetch over the network on the client.
 
 Args (what the caller passes in) come from the handler's parameter type —

package/template/test/app.test.ts

@@ -3,12 +3,12 @@ Test module — `createTestApp()` boots your real app on an ephemeral port (the
 same wiring as `abide start`, no fixtures) and hands back the whole surface:
 
   app.fetch(path)        — pages and raw HTTP, origin + mount base resolved
-  app.rpc.<verb>(args)   — verbs over the real pipeline (CSRF, cookies, base),
+  app.rpc.<name>(args)   — RPCs over the real pipeline (CSRF, cookies, base),
                            typed and decoded; .raw(args) for the Response
   app.sockets.<name>     — a live Socket: iterate it, .tail(n), .publish(m)
   app.health()           — the /__abide/health payload
 
-`app.rpc` / `app.sockets` are typed from your own verbs and sockets — generated
+`app.rpc` / `app.sockets` are typed from your own RPCs and sockets — generated
 into src/.abide during a build, so the keys exist with no imports. The abide
 preload (see bunfig.toml) makes the project's routes resolvable under bun test.
 

package/src/lib/server/rpc/registerVerb.ts

@@ -1,6 +0,0 @@
-import type { VerbRegistryEntry } from './types/VerbRegistryEntry.ts'
-import { verbRegistry } from './verbRegistry.ts'
-
-export function registerVerb(entry: VerbRegistryEntry): void {
-    verbRegistry.set(entry.remote.url, entry)
-}

package/src/lib/server/runtime/types/InspectorVerb.ts

@@ -1,27 +0,0 @@
-/*
-One RPC verb projected for the inspector: the registry entry reduced to the
-serializable facts the UI renders — where it mounts, its method, which
-non-browser surfaces advertise it, and its argument/result shapes as JSON
-Schema. Schemas project through jsonSchemaForSchema (same as MCP/OpenAPI), so
-a verb whose library can't render a schema still lists with an opaque shape.
-*/
-export type InspectorVerb = {
-    /* Registry key — the rpc URL the verb mounts at (e.g. /rpc/users/create). */
-    url: string
-    /* HTTP method bound to the verb. */
-    method: string
-    /* Which surfaces advertise it (browser/mcp/cli), from the verb's ClientFlags. */
-    clients: Record<string, boolean>
-    /* Argument-bag shape as JSON Schema; undefined when the verb declares none. */
-    inputSchema: Record<string, unknown> | undefined
-    /* Success-body shape as JSON Schema; undefined when the verb declares none. */
-    outputSchema: Record<string, unknown> | undefined
-    /* True when the verb declares a filesSchema — it accepts multipart File parts. */
-    files: boolean
-    /* Per-verb handler deadline in ms; undefined = no deadline. */
-    timeout: number | undefined
-    /* Per-verb received-body cap in bytes; undefined = Bun's server-wide ceiling. */
-    maxBodySize: number | undefined
-    /* True when the verb opts out of the same-origin CSRF gate. */
-    crossOrigin: boolean | undefined
-}

package/src/lib/shared/detectVerbMethod.ts

@@ -1,17 +0,0 @@
-import type { HttpVerb } from './types/HttpVerb.ts'
-
-/*
-Reads the HTTP verb of an $rpc module from its source. Every file under
-src/server/rpc/ follows the convention `export const <name> = GET(fn)` (the
-verb helper picks the method, possibly with an explicit generic
-`GET<{…}>(fn)`), so the helper name at the export is the method. Returns
-undefined when no verb export matches — the caller skips the file rather
-than guessing. Used by the rpc.d.ts codegen to type url() against
-query-carrying verbs; matching the same convention the bundler rewrites
-keeps the two from drifting.
-*/
-const VERB_EXPORT = /export\s+const\s+\w+\s*=\s*(GET|POST|PUT|PATCH|DELETE|HEAD)\s*[<(]/
-
-export function detectVerbMethod(source: string): HttpVerb | undefined {
-    return (source.match(VERB_EXPORT)?.[1] as HttpVerb | undefined) ?? undefined
-}

package/src/lib/shared/types/HttpVerb.ts

@@ -1 +0,0 @@
-export type HttpVerb = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD'

package/src/lib/ui/types/Outbox.ts

@@ -1,14 +0,0 @@
-/*
-A durable, FIFO queue of pending mutations that drains when the client is online —
-the local-first half of "act now, sync later". `enqueue` records a serializable
-payload (persisted, so it survives a reload) and tries to drain; `pending` is a
-reactive read of the payloads still in flight (for a "3 unsynced" indicator);
-`flush` drains on demand (and is what the reconnect effect calls); `dispose` stops
-draining and detaches persistence.
-*/
-export type Outbox<T> = {
-    enqueue: (payload: T) => void
-    pending: () => T[]
-    flush: () => Promise<void>
-    dispose: () => void
-}