@abide/abide 0.33.1 → 0.34.1

package/src/lib/ui/dom/on.ts

@@ -1,15 +1,21 @@
+import { CURRENT_SCOPE } from '../runtime/CURRENT_SCOPE.ts'
+import { inScope } from '../runtime/inScope.ts'
 import { OWNER } from '../runtime/OWNER.ts'
 
 /*
 Attaches an event listener and registers its removal with the current ownership
 scope, so a component's listeners detach when it disposes. This is the runtime
 target for an `onclick={…}` binding; the handler body is where the compiler's
-lowered patches (`model.replace(...)`) run.
+lowered patches (`model.replace(...)`) run. The handler is pinned to the scope it
+was attached under, so an ambient `scope()` inside it (e.g. `scope().undo()`)
+resolves the component, not whatever is current when the event fires.
 */
-// @readme plumbing
+// @documentation plumbing
 export function on(element: Element, type: string, handler: EventListener): void {
-    element.addEventListener(type, handler)
+    const captured = CURRENT_SCOPE.current
+    const wrapped: EventListener = (event) => inScope(captured, () => handler(event))
+    element.addEventListener(type, wrapped)
     if (OWNER.current !== undefined) {
-        OWNER.current.push(() => element.removeEventListener(type, handler))
+        OWNER.current.push(() => element.removeEventListener(type, wrapped))
     }
 }

package/src/lib/ui/dom/openMarker.ts

@@ -1,4 +1,4 @@
-import { claimChild } from '../runtime/claimChild.ts'
+import { claimExpected } from '../runtime/claimExpected.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 
 /*
@@ -12,8 +12,8 @@ rather than a list of single nodes.
 export function openMarker(parent: Node, data: string, before: Node | null = null): Comment {
     const hydration = RENDER.hydration
     if (hydration !== undefined) {
-        const node = claimChild(hydration, parent) as unknown as Comment
-        hydration.next.set(parent, node === null ? null : node.nextSibling)
+        const node = claimExpected(hydration, parent, `control-flow marker "${data}"`) as Comment
+        hydration.next.set(parent, node.nextSibling)
         return node
     }
     const node = document.createComment(data)

package/src/lib/ui/dom/skeleton.ts

@@ -53,7 +53,7 @@ function isCloseMarker(data: string): boolean {
    SHALLOW template (block positions are `<!--a-->` anchors, no content), so on hydrate the
    expanded tree must skip that inline content or a hole positioned after a block shifts. In
    create mode the clone is shallow (no markers), so depth stays 0 — a plain element count. */
-function elementChildAt(children: ArrayLike<Node>, index: number): Element {
+function elementChildAt(children: ArrayLike<Node>, index: number): Element | undefined {
     let seen = 0
     let depth = 0
     for (let cursor = 0; cursor < children.length; cursor += 1) {
@@ -72,7 +72,7 @@ function elementChildAt(children: ArrayLike<Node>, index: number): Element {
             depth += 1
         }
     }
-    return undefined as unknown as Element
+    return undefined
 }
 
 /* Records each element hole's element-only path in PRE-ORDER (the `HOLE_ATTRIBUTE`
@@ -152,12 +152,20 @@ function compile(html: string, wrapper: string | undefined): CompiledSkeleton {
     return compiled
 }
 
-/* Walks an element-only path from the top-level node list to the target element. */
+/* Walks an element-only path from the top-level node list to the target element. A step
+   that resolves to nothing means the claimed server run is missing an element the skeleton
+   expects here — a hydration desync; throw AT it (naming the path) rather than returning
+   the undefined that derefs in the downstream `mountChild`/`attr`, far from the cause. */
 function resolveElementHole(topLevel: ArrayLike<Node>, path: number[]): Element {
     let node = elementChildAt(topLevel, path[0] as number)
-    for (let depth = 1; depth < path.length; depth += 1) {
+    for (let depth = 1; depth < path.length && node !== undefined; depth += 1) {
         node = elementChildAt(node.childNodes, path[depth] as number)
     }
+    if (node === undefined) {
+        throw new Error(
+            `[abide] hydration desync: skeleton element hole [${path.join(',')}] resolved to no node — the server DOM is missing an element the client build expects here.`,
+        )
+    }
     return node
 }
 
@@ -173,7 +181,7 @@ client-side — no server marker). Anchor holes resolve by scanning for their `a
 markers (present in both clone and server DOM). Create mode clones the parsed top-level
 nodes; hydrate mode claims the matching server run.
 */
-// @readme plumbing
+// @documentation plumbing
 export function skeleton(parent: Node, html: string): SkeletonHoles {
     const { source, elementPaths, topLevelCount } = compile(html, foreignWrapperTag(parent))
     const hydration = RENDER.hydration

package/src/lib/ui/dom/switchBlock.ts

@@ -18,7 +18,7 @@ On hydrate it adopts the case the server rendered: claim the start marker, run t
 matching case in place, claim the end marker. The effect's first run picks the same
 case and is a no-op; later changes swap the range.
 */
-// @readme plumbing
+// @documentation plumbing
 export function switchBlock(
     parent: Node,
     subject: () => unknown,

package/src/lib/ui/dom/text.ts

@@ -10,7 +10,7 @@ that may yield an `html\`…\`` or snippet value the compiler emits `appendText`
 which branches on the branded value and inserts raw markup; `text` cannot host
 multiple nodes and would stringify such a value to `[object Object]`.
 */
-// @readme plumbing
+// @documentation plumbing
 export function text(read: () => unknown): Text {
     const node = document.createTextNode('')
     effect(() => {

package/src/lib/ui/dom/tryBlock.ts

@@ -20,7 +20,7 @@ builds. On hydrate it claims the SSR boundary
 (`<!--abide:try:N-->…<!--/abide:try:N-->`): the happy path adopts the guarded nodes
 in place; a throw discards the boundary's server nodes and builds the catch fresh.
 */
-// @readme plumbing
+// @documentation plumbing
 export function tryBlock(
     parent: Node,
     id: number,

package/src/lib/ui/dom/when.ts

@@ -18,7 +18,7 @@ matching render in place (its content claims the existing nodes), then claim the
 end marker. The effect's first run sees the same branch and is a no-op; later
 toggles clear the range and build fresh into a fragment.
 */
-// @readme plumbing
+// @documentation plumbing
 export function when(
     parent: Node,
     condition: () => unknown,

package/src/lib/ui/effect.ts

@@ -1,4 +1,6 @@
+import { CURRENT_SCOPE } from './runtime/CURRENT_SCOPE.ts'
 import { createEffectNode } from './runtime/createEffectNode.ts'
+import { inScope } from './runtime/inScope.ts'
 import type { EffectResult } from './runtime/types/EffectResult.ts'
 
 /*
@@ -10,7 +12,10 @@ the final teardown and detaches it from the graph. This is abide's from-scratch
 effect primitive: the open-on-first-read / close-on-last-reader lifecycle,
 grounded in abide's own reactive core.
 */
-// @readme plumbing
+// @documentation effect
 export function effect(fn: () => EffectResult): () => void {
-    return createEffectNode(fn)
+    /* Re-runs fire after the build, so pin the scope this effect was created under
+       (the dep-tracking observer is managed separately, so this can't disturb it). */
+    const captured = CURRENT_SCOPE.current
+    return createEffectNode(() => inScope(captured, fn))
 }

package/src/lib/ui/enterScope.ts

@@ -0,0 +1,18 @@
+import { createScope } from './createScope.ts'
+import { CURRENT_SCOPE } from './runtime/CURRENT_SCOPE.ts'
+import type { Scope } from './types/Scope.ts'
+
+/*
+Establishes a fresh lexical scope for an SSR render and returns the previous one
+to restore (see `exitScope`). The client gets its per-component scope from
+`mount`/`hydrate`; a server render has no mount, so its body brackets itself with
+`enterScope`/`exitScope` — each render (and each nested child render) owns an
+isolated scope, so `scope()` and `model` don't bleed across renders. Nests via the
+returned previous, like `mount`'s save/restore.
+*/
+// @documentation plumbing
+export function enterScope(): Scope | undefined {
+    const previous = CURRENT_SCOPE.current
+    CURRENT_SCOPE.current = createScope({}, previous, true)
+    return previous
+}

package/src/lib/ui/exitScope.ts

@@ -0,0 +1,8 @@
+import { CURRENT_SCOPE } from './runtime/CURRENT_SCOPE.ts'
+import type { Scope } from './types/Scope.ts'
+
+/* Restores the scope `enterScope` saved, closing an SSR render's scope. */
+// @documentation plumbing
+export function exitScope(previous: Scope | undefined): void {
+    CURRENT_SCOPE.current = previous
+}

package/src/lib/ui/history.ts

@@ -0,0 +1,102 @@
+import { PATCH_BUS } from './runtime/PATCH_BUS.ts'
+import type { Doc } from './runtime/types/Doc.ts'
+import type { Patch } from './runtime/types/Patch.ts'
+import type { History } from './types/History.ts'
+
+/*
+Undo/redo for a document. Subscribes the `PATCH_BUS`, filters to this `doc`, and
+journals each applied patch's `inverse` into a bounded stack — O(size of the
+change) per step, never a tree snapshot. `undo`/`redo` replay inverses through
+`doc.apply`; the patches that replay itself emits are routed into a `sink` so a
+replay never opens a fresh entry nor clears the opposite stack (it instead fills
+it, keeping the move reversible). A genuine new edit clears the redo stack.
+`transaction(fn)` groups every patch `fn` emits into one entry. `limit` caps
+depth — the oldest entry drops. Inert (but harmless) on the server.
+*/
+// @documentation plumbing
+export function history(doc: Doc, { limit = 100 }: { limit?: number } = {}): History {
+    const undoStack: Patch[][] = []
+    const redoStack: Patch[][] = []
+    /* When set, captured inverses accumulate here instead of opening a new undo entry
+       — held by an in-progress transaction and by an undo/redo replay. */
+    let sink: Patch[] | undefined
+
+    /* Push one finished entry, evicting the oldest past `limit`; a fresh edit (no
+       sink) also invalidates the redo stack. */
+    const push = (stack: Patch[][], entry: Patch[]): void => {
+        stack.push(entry)
+        if (stack.length > limit) {
+            stack.shift()
+        }
+    }
+
+    const unsubscribe = PATCH_BUS.subscribe((event) => {
+        if (event.doc !== doc || event.inverse === undefined) {
+            return
+        }
+        if (sink !== undefined) {
+            sink.push(event.inverse)
+            return
+        }
+        push(undoStack, [event.inverse])
+        redoStack.length = 0
+    })
+
+    /* Apply an entry's inverses in reverse application order (LIFO), capturing the
+       inverses they emit — the original forward patches — onto `target`, so the move
+       is itself reversible and lands on the opposite stack. */
+    const replay = (entry: Patch[], target: Patch[][]): void => {
+        const captured: Patch[] = []
+        sink = captured
+        try {
+            for (let index = entry.length - 1; index >= 0; index -= 1) {
+                doc.apply(entry[index] as Patch)
+            }
+        } finally {
+            sink = undefined
+        }
+        if (captured.length > 0) {
+            push(target, captured)
+        }
+    }
+
+    return {
+        undo: () => {
+            const entry = undoStack.pop()
+            if (entry !== undefined) {
+                replay(entry, redoStack)
+            }
+        },
+        redo: () => {
+            const entry = redoStack.pop()
+            if (entry !== undefined) {
+                replay(entry, undoStack)
+            }
+        },
+        canUndo: () => undoStack.length > 0,
+        canRedo: () => redoStack.length > 0,
+        transaction: (run: () => void) => {
+            /* A nested transaction folds into the one already collecting. */
+            if (sink !== undefined) {
+                run()
+                return
+            }
+            const entry: Patch[] = []
+            sink = entry
+            try {
+                run()
+            } finally {
+                sink = undefined
+            }
+            if (entry.length > 0) {
+                push(undoStack, entry)
+                redoStack.length = 0
+            }
+        },
+        dispose: () => {
+            unsubscribe()
+            undoStack.length = 0
+            redoStack.length = 0
+        },
+    }
+}

package/src/lib/ui/installHotBridge.ts

@@ -1,7 +1,5 @@
 import { html } from '../shared/html.ts'
 import { snippet } from '../shared/snippet.ts'
-import { derived } from './derived.ts'
-import { doc } from './doc.ts'
 import { anchorCursor } from './dom/anchorCursor.ts'
 import { appendSnippet } from './dom/appendSnippet.ts'
 import { appendStatic } from './dom/appendStatic.ts'
@@ -23,13 +21,14 @@ import { switchBlock } from './dom/switchBlock.ts'
 import { tryBlock } from './dom/tryBlock.ts'
 import { when } from './dom/when.ts'
 import { effect } from './effect.ts'
-import { linked } from './linked.ts'
+import { enterScope } from './enterScope.ts'
+import { exitScope } from './exitScope.ts'
 import { enterRenderPass } from './runtime/enterRenderPass.ts'
 import { exitRenderPass } from './runtime/exitRenderPass.ts'
 import { hotReloadEnabled } from './runtime/hotReloadEnabled.ts'
 import { hotReplace } from './runtime/hotReplace.ts'
 import { nextBlockId } from './runtime/nextBlockId.ts'
-import { state } from './state.ts'
+import { scope } from './scope.ts'
 
 /*
 Dev-only: exposes the abide-ui runtime plus `hotReplace` on `window.__abide`, and
@@ -45,10 +44,9 @@ export function installHotBridge(): void {
     ;(globalThis as { __abide?: Record<string, unknown> }).__abide = {
         html,
         snippet,
-        doc,
-        state,
-        linked,
-        derived,
+        scope,
+        enterScope,
+        exitScope,
         effect,
         mount,
         appendText,

package/src/lib/ui/linked.ts

@@ -17,7 +17,6 @@ never holds an un-coerced value (`return previous` rejects via the `Object.is`
 no-op). The seed is captured by reference: callers clone in the thunk
 (`linked(() => structuredClone(x))`) when they want isolation.
 */
-// @readme plumbing
 export function linked<T>(seed: () => T, transform?: (next: T, previous: T) => T): State<T> {
     /* The cell is a plain `state` — same store, same write path, so `transform` gates
        reseeds and explicit writes identically. */

package/src/lib/ui/navigate.ts

@@ -4,7 +4,7 @@ import { runtimePath } from './runtime/runtimePath.ts'
    reactive route, which re-mounts the matching page via `router`. `replace` swaps
    the current entry instead of pushing — used when honouring a server redirect, so
    the blocked URL isn't left behind in history. */
-// @readme plumbing
+// @documentation navigate
 export function navigate(path: string, replace = false): void {
     if (typeof history !== 'undefined') {
         if (replace) {

package/src/lib/ui/outbox.ts

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

package/src/lib/ui/persist.ts

@@ -0,0 +1,112 @@
+import { localStoragePersistence } from './runtime/localStoragePersistence.ts'
+import { PATCH_BUS } from './runtime/PATCH_BUS.ts'
+import type { Doc } from './runtime/types/Doc.ts'
+import type { PersistenceStore } from './types/PersistenceStore.ts'
+import type { PersistHandle } from './types/PersistHandle.ts'
+
+/*
+Makes a document durable: seeds it from the saved snapshot on boot, then writes
+its snapshot back (debounced) on every change the patch bus announces — so the
+state survives a reload. The bus is the single tap; `persist` adds no bookkeeping
+to the doc. A store-less environment (the server, or a browser without
+localStorage and no injected store) returns an inert handle, so the same call is
+safe to write isomorphically.
+
+Restore is a per-top-level-key overlay (saved wins, current keeps keys saved
+lacks), so a doc that boots empty fills from the snapshot while a key added in a
+newer app version keeps its fresh default. Writes coalesce into one per `debounce`
+window and flush when the tab is hidden, so the tail of a burst isn't lost.
+*/
+// @documentation plumbing
+export function persist(
+    doc: Doc,
+    key: string,
+    {
+        store = localStoragePersistence(),
+        debounce = 200,
+    }: { store?: PersistenceStore; debounce?: number } = {},
+): PersistHandle {
+    /* No durable store → inert: server render, or a browser without localStorage. */
+    if (store === undefined) {
+        return { flush: () => undefined, clear: () => undefined, dispose: () => undefined }
+    }
+
+    const saved = store.load(key)
+    if (saved !== undefined) {
+        restore(doc, saved)
+    }
+
+    /* Coalesce a burst into one write: the timer is armed by the first patch and
+       writes the latest snapshot when it fires, bounding staleness to `debounce`. */
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const flush = (): void => {
+        if (timer !== undefined) {
+            clearTimeout(timer)
+            timer = undefined
+        }
+        store.save(key, doc.snapshot())
+    }
+    const schedule = (): void => {
+        if (timer === undefined) {
+            timer = setTimeout(flush, debounce)
+        }
+    }
+
+    const unsubscribe = PATCH_BUS.subscribe((event) => {
+        if (event.doc === doc) {
+            schedule()
+        }
+    })
+
+    /* Flush the tail before the tab goes away, so a pending debounced write survives. */
+    const onHidden = (): void => {
+        if (typeof document !== 'undefined' && document.visibilityState === 'hidden') {
+            flush()
+        }
+    }
+    const canListen = typeof window !== 'undefined' && typeof window.addEventListener === 'function'
+    if (canListen) {
+        window.addEventListener('pagehide', flush)
+        document.addEventListener('visibilitychange', onHidden)
+    }
+
+    return {
+        flush,
+        clear: () => {
+            if (timer !== undefined) {
+                clearTimeout(timer)
+                timer = undefined
+            }
+            store.remove(key)
+        },
+        dispose: () => {
+            unsubscribe()
+            if (timer !== undefined) {
+                clearTimeout(timer)
+                timer = undefined
+            }
+            if (canListen) {
+                window.removeEventListener('pagehide', flush)
+                document.removeEventListener('visibilitychange', onHidden)
+            }
+        },
+    }
+}
+
+/* Load `saved` into `doc`: a per-key overlay for object roots (so the doc's own
+   keys that the snapshot lacks keep their value), else a wholesale root replace
+   (a primitive or array root). */
+function restore(doc: Doc, saved: unknown): void {
+    const current = doc.snapshot()
+    if (isPlainObject(saved) && isPlainObject(current)) {
+        for (const key of Object.keys(saved)) {
+            doc.replace(key, saved[key])
+        }
+        return
+    }
+    doc.replace('', saved)
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+}

package/src/lib/ui/probeNavigation.ts

@@ -12,7 +12,7 @@ cross-origin a full browser load. A non-OK status (handle() blocked it) or a thr
 fetch (offline) also hands off to the browser, so the server's real response —
 a login page, an error page — is what renders.
 */
-// @readme plumbing
+// @documentation plumbing
 export async function probeNavigation(path: string): Promise<NavVerdict> {
     let response: Response
     try {

package/src/lib/ui/remoteProxy.ts

@@ -22,7 +22,7 @@ the query string (GET/DELETE/HEAD). Plain `fn(args)` decodes the Response
 by Content-Type and throws HttpError on non-2xx; `.raw(args)` is the
 escape hatch that returns the Response untouched.
 */
-// @readme plumbing
+// @documentation plumbing
 export function remoteProxy<Args, Return>(
     method: HttpVerb,
     url: string,

package/src/lib/ui/renderToStream.ts

@@ -22,7 +22,7 @@ into the resume manifest inline — so the value is in the first paint, no pendi
 shell, no swap. The first yield therefore awaits all blocking blocks; only the
 remaining streaming blocks flush out of order after it.
 */
-// @readme plumbing
+// @documentation plumbing
 export async function* renderToStream(render: () => SsrRender): AsyncGenerator<string> {
     const { html, awaits } = render()
     /* Blocking awaits (a `then` on the `await` tag) settle BEFORE the first flush:

package/src/lib/ui/router.ts

@@ -42,7 +42,7 @@ adopts a document handle() already ran on, so it isn't probed. There is no serve
 router — the server picks the page by request URL directly; this is the client
 half. `*` is the fallback route.
 */
-// @readme plumbing
+// @documentation plumbing
 export function router(
     host: Element,
     loaders: Record<string, RouteLoader>,

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

@@ -0,0 +1,10 @@
+import type { Scope } from '../types/Scope.ts'
+
+/*
+The ambient lexical scope. The compiler establishes one per lexical level (a
+component, a control-flow branch) by setting `current` around the build, so the
+bare `scope()` accessor and the scope-bound primitives resolve "where they are"
+with no handle threaded. Undefined outside any scope, where `scope()` mints a
+detached root on first use.
+*/
+export const CURRENT_SCOPE: { current: Scope | undefined } = { current: undefined }

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

@@ -4,5 +4,5 @@
    it; on the client the router mounts/hydrates the child into it and finds it by
    tag. Shared by both compiler back-ends, the SSR chain composer, and the router so
    they all agree on the marker. */
-// @readme plumbing
+// @documentation plumbing
 export const OUTLET_TAG = 'abide-outlet'

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

@@ -0,0 +1,28 @@
+import type { PatchEvent } from './types/PatchEvent.ts'
+
+/*
+Process-global tap for every document mutation. `createDoc` emits a `PatchEvent`
+here on each applied patch; cross-cutting consumers (undo history, persistence,
+sync) subscribe. One chokepoint means those features journal a single uniform
+stream instead of each re-deriving change detection. `active` lets the emitter
+skip computing an inverse — its only real cost — when nobody is listening.
+*/
+const listeners = new Set<(event: PatchEvent) => void>()
+
+export const PATCH_BUS = {
+    /* True only while at least one consumer is attached; gates inverse capture. */
+    get active(): boolean {
+        return listeners.size > 0
+    },
+    emit(event: PatchEvent): void {
+        for (const listener of listeners) {
+            listener(event)
+        }
+    },
+    subscribe(listener: (event: PatchEvent) => void): () => void {
+        listeners.add(listener)
+        return () => {
+            listeners.delete(listener)
+        }
+    },
+}