@abide/abide 0.33.1 → 0.34.0

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

@@ -0,0 +1,29 @@
+import { PATCH_BUS } from './PATCH_BUS.ts'
+import type { Doc } from './types/Doc.ts'
+
+/*
+Runs a component `build` and returns its disposer alongside the component's own
+`model` document — the serializable `state` doc, needed so a hot swap can carry
+its value across (see `hotReplace`). The model is found, not threaded: a component
+seeds its `model` first (the desugared `const model = doc({})` + its init patches
+run before any child mounts or control-flow blocks), so the FIRST patch announced
+on the bus during the build names it. A component with no `state` mints no model
+and emits nothing first — `model` is then `undefined` and there is nothing to
+preserve. Used only on the hot path; the subscription is torn down with the build.
+*/
+export function captureModelDoc(build: () => () => void): {
+    dispose: () => void
+    model: Doc | undefined
+} {
+    let model: Doc | undefined
+    const unsubscribe = PATCH_BUS.subscribe((event) => {
+        model ??= event.doc
+    })
+    let dispose: () => void = () => undefined
+    try {
+        dispose = build()
+    } finally {
+        unsubscribe()
+    }
+    return { dispose, model }
+}

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

@@ -0,0 +1,26 @@
+import { claimChild } from './claimChild.ts'
+import type { RENDER } from './RENDER.ts'
+
+/*
+A hydration claim that MUST succeed. Like `claimChild`, but throws a structural error
+when the cursor has no node to claim. A null here means the SSR markup and the client
+build disagree about the tree at this position — a hydration desync. Cast away unguarded
+(as the claim sites did), that null/undefined derefs several mounts later, far from the
+cause; throwing names what was expected AT the divergence, turning the SSR == client DOM
+invariant from a compile-time-only parity test into a runtime guard. Use only where the
+compiled skeleton GUARANTEES a node — control-flow range markers, keyed-row boundaries —
+never where an end-of-list null is legitimate (e.g. a trailing reactive text binding).
+*/
+export function claimExpected(
+    hydration: NonNullable<(typeof RENDER)['hydration']>,
+    parent: Node,
+    expected: string,
+): Node {
+    const node = claimChild(hydration, parent)
+    if (node === null) {
+        throw new Error(
+            `[abide] hydration desync: expected ${expected} here, but the server DOM had no matching node — SSR markup and the client build disagree on structure at this position.`,
+        )
+    }
+    return node
+}

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

@@ -1,6 +1,6 @@
 import type { ReactiveNode } from './types/ReactiveNode.ts'
 
-/* Creates a lazy derived node. Born dirty so its first read computes; thereafter
+/* Creates a lazy computed node. Born dirty so its first read computes; thereafter
    it recomputes only when a dependency triggers it. */
 export function createComputedNode(compute: () => unknown): ReactiveNode {
     return {

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

@@ -1,6 +1,8 @@
 import { applyPatchToTree } from './applyPatchToTree.ts'
+import { createComputedNode } from './createComputedNode.ts'
 import { createSignalNode } from './createSignalNode.ts'
 import { flushEffects } from './flushEffects.ts'
+import { PATCH_BUS } from './PATCH_BUS.ts'
 import { REACTIVE_CONTEXT } from './REACTIVE_CONTEXT.ts'
 import { readNode } from './readNode.ts'
 import { trigger } from './trigger.ts'
@@ -8,6 +10,7 @@ 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'
 
@@ -34,6 +37,16 @@ the change.
 export function createDoc(initial: unknown): Doc {
     let tree = initial
     const nodes = new Map<string, ReactiveNode>()
+    /* Computed slots: a path whose value is a function of other paths, not stored
+       truth. Held apart from `nodes` so the structural wake/eviction never touches
+       them; their dirtiness is driven entirely by the deps they read (the signal
+       graph), not by tree mutations. They are not in `tree`, so `snapshot` omits
+       them, and they never pass through `apply`, so they never hit the patch bus —
+       a recompute is a downstream reaction, not a change to journal/persist/sync. */
+    const computed = new Map<string, ReactiveNode>()
+    /* Set to the returned document before any apply runs, so a PATCH_BUS event can
+       name the document it came from (reference identity, the undo/persistence key). */
+    let self: Doc
 
     function nodeFor(path: string): ReactiveNode {
         let node = nodes.get(path)
@@ -45,9 +58,27 @@ export function createDoc(initial: unknown): Doc {
     }
 
     function read<T>(path: string): T {
+        /* Size-gated so a doc with no computed slots pays nothing on the stored hot
+           path — only one `.size` check, not a `.get` per read. */
+        if (computed.size > 0) {
+            const computedNode = computed.get(path)
+            if (computedNode !== undefined) {
+                return readNode(computedNode) as T
+            }
+        }
         return readNode(nodeFor(path)) as T
     }
 
+    /* Registers a computed slot at `path` and returns a string-free reader bound to
+       its node — the hoisted accessor the compiler would emit (the `computed` form),
+       so a hot read skips the path lookup. Reading the compute subscribes it to
+       whatever doc paths it touches; those deps then drive its recomputation. */
+    function derive<T>(path: string, compute: () => T): () => T {
+        const node = createComputedNode(compute as () => unknown)
+        computed.set(path, node)
+        return () => readNode(node) as T
+    }
+
     /*
     Wakes readers from `rootPath`. `force` notifies the root unconditionally (a
     structural change keeps the container's identity, so there is no new value to
@@ -93,7 +124,13 @@ export function createDoc(initial: unknown): Doc {
     }
 
     function apply(patch: Patch): void {
-        const segments = patch.path === '' ? [] : patch.path.split('/')
+        /* 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)
+        /* 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). */
+        const before = PATCH_BUS.active ? walkPath(tree, patch.path) : undefined
         tree = applyPatchToTree(tree, patch, segments)
         /* parentPath is patch.path minus its last segment — the same string
            `segments.slice(0, -1).join('/')` rebuilds, taken by one slice instead. */
@@ -140,9 +177,40 @@ export function createDoc(initial: unknown): Doc {
         } finally {
             REACTIVE_CONTEXT.batchDepth -= 1
         }
+        /* Announce the change before flushing effects, so a patch an effect emits in
+           reaction lands AFTER this one on the bus — the journal stays chronological. */
+        if (PATCH_BUS.active) {
+            PATCH_BUS.emit({ doc: self, patch, inverse: inverseOf(patch, before) })
+        }
         flushEffects()
     }
 
+    /* The patch that undoes `patch`, from the pre-image `before` (a value the change
+       overwrote/removed) and the now-mutated tree. An add inverts to removing the slot
+       it created — resolving an array append (`-`) to the concrete last index it took.
+       A replace/remove of a path that held nothing inverts to remove/nothing. */
+    function inverseOf(
+        patch: Patch,
+        before: ReturnType<typeof walkPath> | undefined,
+    ): Patch | undefined {
+        if (patch.op === 'add') {
+            const lastSlash = patch.path.lastIndexOf('/')
+            const parentPath = lastSlash === -1 ? '' : patch.path.slice(0, lastSlash)
+            const parent = walkPath(tree, parentPath).value
+            const resolved =
+                Array.isArray(parent) && patch.path.endsWith('/-')
+                    ? `${parentPath}/${parent.length - 1}`
+                    : patch.path
+            return { op: 'remove', path: resolved }
+        }
+        if (patch.op === 'replace') {
+            return before?.exists
+                ? { op: 'replace', path: patch.path, value: before.value }
+                : { op: 'remove', path: patch.path }
+        }
+        return before?.exists ? { op: 'add', path: patch.path, value: before.value } : undefined
+    }
+
     /*
     A stable accessor bound to one scalar leaf — what the compiler emits so a hot
     loop has zero string work: the node, the parent container, and the leaf key
@@ -153,7 +221,7 @@ export function createDoc(initial: unknown): Doc {
     */
     function cell<T>(path: string): Cell<T> {
         const node = nodeFor(path)
-        const segments = path.split('/')
+        const segments = path.split('/').map(unescapeKey)
         const leafKey = segments[segments.length - 1] as string
         let parent = tree as Record<string, unknown>
         for (const segment of segments.slice(0, -1)) {
@@ -168,13 +236,15 @@ export function createDoc(initial: unknown): Doc {
         }
     }
 
-    return {
+    self = {
         read,
         cell,
+        derive,
         apply,
         replace: (path, value) => apply({ op: 'replace', path, value }),
         add: (path, value) => apply({ op: 'add', path, value }),
         remove: (path) => apply({ op: 'remove', path }),
         snapshot: () => tree,
     }
+    return self
 }

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

@@ -3,7 +3,7 @@ import { RENDER } from './RENDER.ts'
 /* Marks entry into a render/mount. The OUTERMOST one (depth 0) resets the block-id
    counter so every render pass starts at 0; a child component's render/mount runs
    at depth > 0 and continues the parent's counter. Pair with `exitRenderPass`. */
-// @readme plumbing
+// @documentation plumbing
 export function enterRenderPass(): void {
     if (RENDER.depth === 0) {
         RENDER.blockId = 0

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

@@ -0,0 +1,13 @@
+/*
+Escapes one object key into a JSON Pointer reference token (RFC 6901): `~`→`~0`,
+`/`→`~1`, so a key that itself contains `/` (a URL id, a date, a composite key)
+survives a `/`-joined path instead of being mis-split into segments. `~` is
+escaped first so a `/`→`~1` substitution isn't re-escaped. The common key (a
+plain identifier) contains neither char, so the scan returns it untouched.
+*/
+export function escapeKey(key: string): string {
+    if (!key.includes('~') && !key.includes('/')) {
+        return key
+    }
+    return key.replace(/~/g, '~0').replace(/\//g, '~1')
+}

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

@@ -1,7 +1,7 @@
 import { RENDER } from './RENDER.ts'
 
 /* Marks exit from a render/mount, unwinding the depth `enterRenderPass` raised. */
-// @readme plumbing
+// @documentation plumbing
 export function exitRenderPass(): void {
     RENDER.depth -= 1
 }

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

@@ -1,15 +1,18 @@
+import { captureModelDoc } from './captureModelDoc.ts'
 import { hotInstances } from './hotInstances.ts'
+import { seedModelDoc } from './seedModelDoc.ts'
 import type { UiComponent } from './types/UiComponent.ts'
 
 /*
 Swaps every live instance of an edited component to its new factory. Per instance:
-dispose the current scope and its DOM (the mount disposer clears the host), then
-re-run `next` into the same host with the same props — so state above the boundary
-survives (props are thunks that re-read the parent's live signals) while the
-component's own state resets. The hot module calls this on load with its freshly
-compiled `next`. Returns whether it swapped at least one instance: false (the edited
-component has none mounted — e.g. a router-mounted page, or a hidden branch) tells
-the caller to fall back to a full reload, since nothing on screen would update.
+snapshot its model, dispose the current scope and its DOM (the mount disposer clears
+the host), re-run `next` into the same host with the same props, then re-seed the
+fresh model from the snapshot — so the user's in-progress `state` survives the edit
+(state above the boundary already survives: props are thunks re-reading the parent's
+live signals). The hot module calls this on load with its freshly compiled `next`.
+Returns whether it swapped at least one instance: false (the edited component has
+none mounted — e.g. a router-mounted page, or a hidden branch) tells the caller to
+fall back to a full reload, since nothing on screen would update.
 */
 export function hotReplace(moduleId: string, next: UiComponent): boolean {
     const set = hotInstances.get(moduleId)
@@ -17,9 +20,15 @@ export function hotReplace(moduleId: string, next: UiComponent): boolean {
         return false
     }
     for (const instance of set) {
+        const saved = instance.model?.snapshot()
         instance.dispose()
         instance.factory = next
-        instance.dispose = next(instance.host, instance.props)
+        const { dispose, model } = captureModelDoc(() => next(instance.host, instance.props))
+        instance.dispose = dispose
+        instance.model = model
+        if (saved !== undefined && model !== undefined) {
+            seedModelDoc(model, saved)
+        }
     }
     return true
 }

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

@@ -0,0 +1,19 @@
+import type { Scope } from '../types/Scope.ts'
+import { CURRENT_SCOPE } from './CURRENT_SCOPE.ts'
+
+/*
+Runs `fn` with `scope` as the ambient current scope, restoring the previous one
+after. Deferred callbacks — an event handler, an effect re-run — fire after the
+build that registered them, when `CURRENT_SCOPE` has moved on; wrapping them in
+the scope captured at registration is what makes `scope()` inside them resolve the
+scope they belong to, not whatever happens to be current when they fire.
+*/
+export function inScope<T>(scope: Scope | undefined, fn: () => T): T {
+    const previous = CURRENT_SCOPE.current
+    CURRENT_SCOPE.current = scope
+    try {
+        return fn()
+    } finally {
+        CURRENT_SCOPE.current = previous
+    }
+}

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

@@ -0,0 +1,34 @@
+import type { PersistenceStore } from '../types/PersistenceStore.ts'
+
+/*
+The default `persist` backend: `localStorage` keyed by the persistence key, with
+JSON as the wire form (which also clones, so a stored snapshot can't alias the
+live tree). Returns `undefined` where there is no `localStorage` — the server, or
+a browser with storage disabled — which `persist` reads as "stay inert". A corrupt
+or unparseable entry loads as `undefined` rather than throwing, so one bad write
+can't wedge boot.
+*/
+export function localStoragePersistence(): PersistenceStore | undefined {
+    if (typeof localStorage === 'undefined') {
+        return undefined
+    }
+    return {
+        load: (key) => {
+            const raw = localStorage.getItem(key)
+            if (raw === null) {
+                return undefined
+            }
+            try {
+                return JSON.parse(raw)
+            } catch {
+                return undefined
+            }
+        },
+        save: (key, snapshot) => {
+            localStorage.setItem(key, JSON.stringify(snapshot))
+        },
+        remove: (key) => {
+            localStorage.removeItem(key)
+        },
+    }
+}

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

@@ -3,7 +3,7 @@ import { RENDER } from './RENDER.ts'
 /* The next block id in the current render pass. `await`/`try` blocks draw from it
    in document order — shared across a component and the children it inlines — so a
    page id and a child component's id never collide in the global `RESUME` manifest. */
-// @readme plumbing
+// @documentation plumbing
 export function nextBlockId(): number {
     const id = RENDER.blockId
     RENDER.blockId += 1

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

@@ -0,0 +1,26 @@
+import type { Doc } from './types/Doc.ts'
+
+/*
+Loads a `saved` snapshot (from the pre-swap instance) into a freshly-built `model`,
+restoring the user's in-progress state across a hot swap. A shallow per-top-level-key
+merge, not a wholesale root replace: a key present in both is restored from `saved`;
+a key the edit ADDED keeps its fresh default; a key the edit REMOVED is not re-added.
+So editing a component's state shape still loads cleanly instead of resurrecting a
+stale tree. Each restored key is one patch, so only the changed slots re-render.
+*/
+export function seedModelDoc(model: Doc, saved: unknown): void {
+    const current = model.snapshot()
+    if (
+        saved === null ||
+        typeof saved !== 'object' ||
+        current === null ||
+        typeof current !== 'object'
+    ) {
+        return
+    }
+    for (const key of Object.keys(saved)) {
+        if (key in current) {
+            model.replace(key, (saved as Record<string, unknown>)[key])
+        }
+    }
+}

package/src/lib/ui/runtime/types/{Derived.ts → Computed.ts}

@@ -1,3 +1,3 @@
 /* A read-only reactive cell computed from other cells. Reading `.value`
    subscribes the running observer and lazily recomputes if a dependency changed. */
-export type Derived<T> = { readonly value: T }
+export type Computed<T> = { readonly value: T }

package/src/lib/ui/runtime/types/Doc.ts

@@ -11,6 +11,9 @@ plain, serializable data, which is what makes the document resumable.
 export type Doc = {
     read: <T>(path: string) => T
     cell: <T>(path: string) => Cell<T>
+    /* Registers a computed slot at `path` (a value computed from other paths, never
+       stored/serialized/journalled) and returns a string-free reader bound to it. */
+    derive: <T>(path: string, compute: () => T) => () => T
     apply: (patch: Patch) => void
     replace: (path: string, value: unknown) => void
     add: (path: string, value: unknown) => void

package/src/lib/ui/runtime/types/HotInstance.ts

@@ -1,14 +1,18 @@
+import type { Doc } from './Doc.ts'
 import type { UiComponent } from './UiComponent.ts'
 
 /*
 A live component instance the hot-reload registry tracks: its wrapper host, the
 factory that built it, the props (thunks re-read on a swap so the parent's live
-state still flows through), and the disposer for its current scope + DOM. A swap
-mutates `factory`/`dispose` in place (see `hotReplace`).
+state still flows through), the disposer for its current scope + DOM, and its own
+`model` document (`undefined` when the component has no `state`) — snapshotted
+before a swap and re-seeded after, so the user's in-progress state survives the
+edit. A swap mutates `factory`/`dispose`/`model` in place (see `hotReplace`).
 */
 export type HotInstance = {
     host: Element
     factory: UiComponent
     props: Parameters<UiComponent>[1]
     dispose: () => void
+    model: Doc | undefined
 }

package/src/lib/ui/runtime/types/PatchEvent.ts

@@ -0,0 +1,16 @@
+import type { Doc } from './Doc.ts'
+import type { Patch } from './Patch.ts'
+
+/*
+A single applied change announced on the `PATCH_BUS`: the `doc` it hit (reference
+identity within the process — a serialization-stable id arrives with sync), the
+forward `patch`, and its `inverse` — the patch that exactly undoes it, or
+`undefined` for a no-op (e.g. removing an absent key). Consumers — undo history,
+persistence, sync — read this one shape; the inverse is what makes a journal
+reversible at O(size of the change), never a retained tree snapshot.
+*/
+export type PatchEvent = {
+    doc: Doc
+    patch: Patch
+    inverse: Patch | undefined
+}

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

@@ -0,0 +1,12 @@
+/*
+Reverses `escapeKey` for one path segment (JSON Pointer RFC 6901): `~1`→`/`,
+`~0`→`~`, in that order so a literal `~1` in the original key (escaped to `~01`)
+round-trips. A segment with no `~` can't carry an escape, so it returns untouched
+— the fast path for every plain-identifier segment on the hot read/split path.
+*/
+export function unescapeKey(segment: string): string {
+    if (!segment.includes('~')) {
+        return segment
+    }
+    return segment.replace(/~1/g, '/').replace(/~0/g, '~')
+}

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

@@ -1,4 +1,5 @@
 import type { PathWalk } from './types/PathWalk.ts'
+import { unescapeKey } from './unescapeKey.ts'
 
 /*
 Walks a `/`-joined path through a plain tree in one pass, returning both whether
@@ -17,7 +18,8 @@ export function walkPath(tree: unknown, path: string): PathWalk {
         return { exists: tree !== undefined, value: tree }
     }
     let current: unknown = tree
-    for (const segment of path.split('/')) {
+    for (const rawSegment of path.split('/')) {
+        const segment = unescapeKey(rawSegment)
         if (current === null || typeof current !== 'object' || !(segment in current)) {
             return { exists: false, value: undefined }
         }

package/src/lib/ui/scope.ts

@@ -0,0 +1,19 @@
+import { createScope } from './createScope.ts'
+import { CURRENT_SCOPE } from './runtime/CURRENT_SCOPE.ts'
+import type { Scope } from './types/Scope.ts'
+
+/*
+Resolves a lexical scope. `scope()` returns the current one — established per
+lexical level by the compiler, so it reads "where you are" with no handle. Outside
+any scope (boot, a script) it mints a detached root once and reuses it. `scope('/')`
+returns the root of the current tree (the app-global scope). The returned value is
+passable: hand it to a child or a helper and it can read/extend/undo that scope.
+*/
+// @documentation reactive-state
+export function scope(address?: string): Scope {
+    if (!CURRENT_SCOPE.current) {
+        CURRENT_SCOPE.current = createScope()
+    }
+    const current = CURRENT_SCOPE.current
+    return address === '/' ? current.root() : current
+}

package/src/lib/ui/socketProxy.ts

@@ -19,7 +19,7 @@ Backpressure is unbounded — a slow consumer with a chatty socket will
 grow the per-iterator buffer; bounded policies belong in a future
 socketProxy API, not the wire layer.
 */
-// @readme plumbing
+// @documentation plumbing
 export function socketProxy<T>(name: string): Socket<T> {
     return buildSocketOverChannel<T>(name, getSocketChannel)
 }

package/src/lib/ui/startClient.ts

@@ -24,7 +24,7 @@ navigation — importing each further page's chunk on first visit and probing th
 destination through the server's app.handle so auth/redirect gating still applies.
 Returns a disposer. `target` defaults to `#app`; pass one explicitly in tests.
 */
-// @readme plumbing
+// @documentation plumbing
 export function startClient(
     routes: Record<string, RouteLoader>,
     layoutRoutes: Record<string, RouteLoader> = {},

package/src/lib/ui/state.ts

@@ -14,7 +14,7 @@ needs no magic.
 `transform` is an optional coercion gate on the write path: every `.value =`
 runs it and stores what it returns, with `previous` for clamp-relative writes or
 rejection (`return previous` is an `Object.is` no-op). It is the local-truth
-mirror of `derived`'s write-through `set` — here the value lives in this cell, so
+mirror of `computed`'s write-through `set` — here the value lives in this cell, so
 the gate *returns* what to store rather than writing an external target. The
 construction `initial` is taken verbatim; the gate runs on writes only.
 */
@@ -22,7 +22,6 @@ construction `initial` is taken verbatim; the gate runs on writes only.
    `State<Foo | undefined>`. Without it `state<Foo>(undefined)` is an arity/assign
    error and `state(undefined)` infers `T = undefined` (every `.value` access then
    narrows to `never`). */
-// @readme plumbing
 export function state<T>(): State<T | undefined>
 export function state<T>(initial: T, transform?: (next: T, previous: T) => T): State<T>
 export function state<T>(

package/src/lib/ui/sync.ts

@@ -0,0 +1,42 @@
+import { PATCH_BUS } from './runtime/PATCH_BUS.ts'
+import type { Doc } from './runtime/types/Doc.ts'
+import type { SyncTransport } from './types/SyncTransport.ts'
+
+/*
+Shares a document's state across peers in real time. Two directions over one
+`transport`, both riding the patch bus:
+  - OUTBOUND: every local patch to `doc` is published (`transport.send`);
+  - INBOUND: every peer patch is applied to `doc`.
+An inbound apply emits on the bus like any change, so an `applying` guard stops it
+being echoed straight back — the thing that would otherwise ping-pong forever. The
+transport itself should not deliver a sender its own patch either; together the two
+guards keep a write to a path from looping. Last-write-wins by arrival order;
+edits to *different* paths never conflict, by construction of the doc's wake. A
+late joiner needs a snapshot seed before live patches (a transport concern, out of
+this core). Returns a disposer.
+*/
+// @documentation plumbing
+export function sync(doc: Doc, transport: SyncTransport): () => void {
+    /* True only while applying a received patch, so its bus echo isn't re-sent. */
+    let applying = false
+
+    const unsubscribeInbound = transport.subscribe((patch) => {
+        applying = true
+        try {
+            doc.apply(patch)
+        } finally {
+            applying = false
+        }
+    })
+
+    const unsubscribeBus = PATCH_BUS.subscribe((event) => {
+        if (event.doc === doc && !applying) {
+            transport.send(event.patch)
+        }
+    })
+
+    return () => {
+        unsubscribeBus()
+        unsubscribeInbound()
+    }
+}

package/src/lib/ui/tail.ts

@@ -108,7 +108,7 @@ from a $derived can't crash the component. Status distinguishes "haven't
 received the first frame" (pending) from "stream ended cleanly" (done) and
 "wire layer surfaced an error" (error).
 */
-// @readme tail
+// @documentation tail
 export function tail<T>(subscribable: Subscribable<T>): T | undefined
 export function tail<T>(subscribable: Subscribable<T>, options: TailOptions): T[]
 export function tail<T>(subscribable: Subscribable<T>, options?: TailOptions): T | T[] | undefined {

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

@@ -0,0 +1,14 @@
+/*
+The undo/redo handle returned by `history(doc)`. `undo`/`redo` step the journal
+of inverse patches; `canUndo`/`canRedo` report availability; `transaction` groups
+a burst of patches into one reversible step (one user action = one undo); `dispose`
+detaches from the `PATCH_BUS` and drops the journal.
+*/
+export type History = {
+    undo: () => void
+    redo: () => void
+    canUndo: () => boolean
+    canRedo: () => boolean
+    transaction: (run: () => void) => void
+    dispose: () => void
+}

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

@@ -0,0 +1,14 @@
+/*
+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
+}

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

@@ -0,0 +1,11 @@
+/*
+The handle returned by `persist(doc, key)`. `flush` writes the pending snapshot
+immediately (the debounced writer otherwise coalesces a burst); `clear` removes
+the stored snapshot; `dispose` stops persisting (unsubscribes, drops listeners).
+On the server or a store-less browser, every method is a no-op.
+*/
+export type PersistHandle = {
+    flush: () => void
+    clear: () => void
+    dispose: () => void
+}

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

@@ -0,0 +1,12 @@
+/*
+The durable backend `persist` writes a document snapshot to. Deliberately tiny
+and synchronous — `load` must return the saved value in time to seed the doc
+before first render, which a sync store (localStorage) gives for free. Inject a
+custom one for a different backend (a test memory store; a server data-dir store);
+an async backend (IndexedDB) needs an async-boot wrapper, out of this contract.
+*/
+export type PersistenceStore = {
+    load: (key: string) => unknown
+    save: (key: string, snapshot: unknown) => void
+    remove: (key: string) => void
+}