@abide/abide 0.41.1 → 0.43.0

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/runtime/createDoc.ts

@@ -3,13 +3,13 @@ import { batch } from './batch.ts'
 import { createComputedNode } from './createComputedNode.ts'
 import { createSignalNode } from './createSignalNode.ts'
 import { PATCH_BUS } from './PATCH_BUS.ts'
+import { pathSegments } from './pathSegments.ts'
 import { readNode } from './readNode.ts'
 import { trigger } from './trigger.ts'
 import type { Cell } from './types/Cell.ts'
 import type { Doc } from './types/Doc.ts'
 import type { Patch } from './types/Patch.ts'
 import type { ReactiveNode } from './types/ReactiveNode.ts'
-import { unescapeKey } from './unescapeKey.ts'
 import { walkPath } from './walkPath.ts'
 import { writeNode } from './writeNode.ts'
 
@@ -132,7 +132,7 @@ export function createDoc(initial: unknown): Doc {
     function apply(patch: Patch): void {
         /* Segments index the tree, so they carry the REAL keys (unescaped); the path
            strings (parentPath, node-map keys) stay escaped, re-walked through walkPath. */
-        const segments = patch.path === '' ? [] : patch.path.split('/').map(unescapeKey)
+        const segments = patch.path === '' ? [] : pathSegments(patch.path)
         /* Capture the pre-image only when a consumer is listening (the inverse's only
            cost): a replace/remove inverts to the value it overwrote, an add to a
            remove (computed post-apply, below, to resolve an array append's index). */
@@ -220,7 +220,7 @@ export function createDoc(initial: unknown): Doc {
     */
     function cell<T>(path: string): Cell<T> {
         const node = nodeFor(path)
-        const segments = path.split('/').map(unescapeKey)
+        const segments = pathSegments(path)
         const leafKey = segments[segments.length - 1] as string
         /* Auto-vivify missing ancestor objects so binding a nested path on a doc
            booted shallow (e.g. `state({})`) doesn't crash, and a later `set` writes

package/src/lib/ui/runtime/pathSegments.ts

@@ -0,0 +1,10 @@
+import { unescapeKey } from './unescapeKey.ts'
+
+/*
+Splits an escaped JSON-Pointer-style doc path into its REAL key segments
+(each segment unescaped). The path strings (parentPath, node-map keys) stay
+escaped and re-walked through `walkPath`; segments index the live tree.
+*/
+export function pathSegments(path: string): string[] {
+    return path.split('/').map(unescapeKey)
+}

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/.zed/settings.json

@@ -0,0 +1,4 @@
+{
+  "auto_install_extensions": { "abide": true },
+  "semantic_tokens": "combined"
+}

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/src/ui/pages/page.abide

@@ -3,17 +3,17 @@
 Root page — served at GET /. Every folder under src/ui/pages/ that contains a
 page.abide mounts at that folder's URL; the root layout.abide wraps it.
 
-The blocking await-block below (the `then` attribute sits ON the <template await>)
+The blocking await-block below (the `then` clause sits in the `{#await}` head)
 resolves on the server during SSR and renders inline — no pending placeholder. The
 decoded body is captured into the per-request cache, serialized into the HTML, and
-replayed on the client during hydration with no second fetch. A `then` *child*
+replayed on the client during hydration with no second fetch. A `{:then}` *branch*
 instead would stream the resolution in out of order.
 */
 import { cache } from '@abide/abide/shared/cache'
 import { getHello } from '$server/rpc/getHello.ts'
 </script>
 
-<template await={cache(getHello)()} then="hello">
+{#await cache(getHello)() then hello}
     <h1>{hello.message}</h1>
-</template>
+{/await}
 <p>Edit <code>src/ui/pages/page.abide</code> and the page hot-reloads.</p>

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