bireactive 0.3.0 → 0.3.2

package/README.md

@@ -1,6 +1,6 @@
 # bi-reactive
 
-[npm](https://www.npmjs.com/package/bireactive) · [GitHub](https://github.com/OrionReed/bireactive) · [site](https://orionreed.github.io/bireactive/) · [API](https://orionreed.github.io/bireactive/api/)
+[NPM](https://www.npmjs.com/package/bireactive) · [GitHub](https://github.com/OrionReed/bireactive) · [Demos](https://orionreed.github.io/bireactive/) · [API](https://orionreed.github.io/bireactive/api/)
 
 A signals-like bidirectional reactive programming system where edges can go both ways. Forward and backward propagation are handled by the engine, with the same set of caveats as regular reactive programming.
 
@@ -10,9 +10,9 @@ A signals-like bidirectional reactive programming system where edges can go both
 npm install bireactive
 ```
 
-Runtime dependencies [`temml`](https://temml.org) (for `tex`) and
+Runtime dependencies [`temml`](https://temml.org) (for `tex`), [`Automerge`](https://automerge.org) and
 [`prism-esm`](https://github.com/orionhealthotago/prism-esm) (for `code`) are
-installed automatically. They may be split into separate packages later so the
+installed automatically. These will be split into separate packages later so the
 core stays dependency-free.
 
 ## Sketch
@@ -61,20 +61,27 @@ inside.value = true; // assert membership…
 q.value; // { x: 100, y: 50 } — q snaps to the nearest in-box point
 ```
 
+## Documentation
+
+- **Guide** — start with the [Overview](guide/overview.md) (a map of every
+  capability) and [Getting Started](guide/getting-started.md).
+- **[API reference](https://orionreed.github.io/bireactive/api/)** — every
+  export, grouped by domain; the guide lives in its sidebar too.
+- **[Demos](https://orionreed.github.io/bireactive/)** — live, interactive examples.
+
 ## Develop
 
 ```sh
 npm run dev        # serve the landing page at :5555
-npm run site       # build the static site into dist-web/
+npm run site       # build the static site + API docs into dist-web/
+npm run docs       # build just the API reference + guide into dist-web/api/
 npm run build      # compile the library into dist/
 npm test           # run the test suite
 ```
 
 ## Status
 
-`0.x` — APIs are still moving. The package is a single bundle today;
-sub-packages (`@bireactive/core`, `@bireactive/animation`, `@bireactive/shapes`, …) are used
-internally as path aliases and will be split out once the surface settles.
+`0.x` — APIs are still moving frequently. The package is a single bundle today; sub-packages will be split out once the surface settles.
 
 ## License
 

package/dist/automerge/doc-cell.d.ts

@@ -0,0 +1,20 @@
+import type { DocHandle } from "@automerge/automerge-repo";
+import { type Cell, type Writable } from "../core/cell.js";
+import { type Store } from "../core/store.js";
+/** Two-way bridge between an Automerge doc and the reactive graph. */
+export interface DocBridge<T> {
+    /** Source cell mirroring the doc; writes (direct or via a lens) flow back to the CRDT. */
+    cell: Writable<Cell<T>>;
+    /** Deep `store` view over `cell` — `bridge.store.a.b.value = x` commits to the doc. */
+    store: Store<T>;
+    /** Point the same cell at a different doc, keeping every bound lens/view alive. */
+    retarget: (handle: DocHandle<T>) => void;
+    /** Detach both directions (call from `disconnectedCallback`). */
+    dispose: () => void;
+}
+/** Connect a `DocHandle` to a reactive cell + store, syncing both ways. */
+export declare function connectDoc<T extends object>(handle: DocHandle<T>): DocBridge<T>;
+/** Doc as a writable cell (page-lifetime; use {@link connectDoc} when you need disposal). */
+export declare function docCell<T extends object>(handle: DocHandle<T>): Writable<Cell<T>>;
+/** Doc as a deep store (page-lifetime; use {@link connectDoc} when you need disposal). */
+export declare function docStore<T extends object>(handle: DocHandle<T>): Store<T>;

package/dist/automerge/doc-cell.js

@@ -0,0 +1,80 @@
+// doc-cell.ts — bridge an Automerge document to the reactive graph.
+//
+// An Automerge `DocHandle` is a writable source of truth that lives outside the
+// cell graph: it emits `change` events and is mutated through `handle.change`.
+// `connectDoc` wires it to a `Writable<Cell<T>>` in both directions so the doc
+// becomes an ordinary cell you can lens, `store`, and bind in JSX.
+//
+//   doc → cell : on every `change`, snapshot the doc into the cell.
+//   cell → doc : an effect mirrors each commit back via `reconcile` (minimal
+//                ops, so concurrent edits merge).
+//
+// The cell uses structural equality, so the two directions converge in one hop:
+// a write reconciles into the doc, the doc echoes a `change`, the snapshot is
+// deep-equal to what we already hold, and the engine stops. No flags, no echo
+// storm. Because the doc is the apex, many independent lens/`store` views can
+// hang off one `connectDoc` — that's the symmetric, no-primary topology: the
+// CRDT is the shared core, every schema is just a projection.
+import { cell, effect } from "../core/cell.js";
+import { store } from "../core/store.js";
+import { reconcile } from "./reconcile.js";
+function deepEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (a === null || b === null || typeof a !== "object" || typeof b !== "object")
+        return false;
+    const aArr = Array.isArray(a);
+    if (aArr !== Array.isArray(b))
+        return false;
+    const ak = Object.keys(a);
+    const bk = Object.keys(b);
+    if (ak.length !== bk.length)
+        return false;
+    for (const k of ak) {
+        if (!Object.hasOwn(b, k))
+            return false;
+        if (!deepEqual(a[k], b[k]))
+            return false;
+    }
+    return true;
+}
+/** Wire an existing cell to a handle in both directions; returns an unbind. */
+function bind(c, handle) {
+    const onChange = () => {
+        c.value = structuredClone(handle.doc());
+    };
+    handle.on("change", onChange);
+    const stop = effect(() => {
+        const next = c.value;
+        handle.change((d) => reconcile(d, next));
+    });
+    return () => {
+        stop();
+        handle.off("change", onChange);
+    };
+}
+/** Connect a `DocHandle` to a reactive cell + store, syncing both ways. */
+export function connectDoc(handle) {
+    const c = cell(structuredClone(handle.doc()), { equals: deepEqual, name: "doc" });
+    let unbind = bind(c, handle);
+    return {
+        cell: c,
+        store: store(c),
+        retarget: next => {
+            unbind();
+            // Seed the cell from the new doc *before* re-binding, so the cell→doc
+            // effect doesn't push the old value into the freshly targeted doc.
+            c.value = structuredClone(next.doc());
+            unbind = bind(c, next);
+        },
+        dispose: () => unbind(),
+    };
+}
+/** Doc as a writable cell (page-lifetime; use {@link connectDoc} when you need disposal). */
+export function docCell(handle) {
+    return connectDoc(handle).cell;
+}
+/** Doc as a deep store (page-lifetime; use {@link connectDoc} when you need disposal). */
+export function docStore(handle) {
+    return connectDoc(handle).store;
+}

package/dist/automerge/index.d.ts

@@ -0,0 +1,3 @@
+export type { DocBridge } from "./doc-cell.js";
+export { connectDoc, docCell, docStore } from "./doc-cell.js";
+export { reconcile } from "./reconcile.js";

package/dist/automerge/index.js

@@ -0,0 +1,12 @@
+// @bireactive/automerge — view an Automerge CRDT through the reactive graph.
+//
+// `connectDoc(handle)` turns a `DocHandle` into a `Writable<Cell<T>>` plus a deep
+// `store`, synced both ways. Lens/`store` projections off that one cell give you
+// many schemas over a single shared doc with no privileged "primary" — the CRDT
+// is the apex, every view is a leg. `reconcile` is the doc-side diff that keeps
+// writes merge-friendly; it's exported for custom bridges.
+//
+// Automerge is an optional peer dependency: import this entry only when you've
+// installed `@automerge/automerge-repo`.
+export { connectDoc, docCell, docStore } from "./doc-cell.js";
+export { reconcile } from "./reconcile.js";

package/dist/automerge/reconcile.d.ts

@@ -0,0 +1,5 @@
+type Any = any;
+/** Minimally mutate the Automerge node `target` (inside `handle.change`) to equal
+ *  the plain value `next`. */
+export declare function reconcile(target: Any, next: Any): void;
+export {};

package/dist/automerge/reconcile.js

@@ -0,0 +1,63 @@
+// reconcile.ts — bring an Automerge document to equal a plain POJO with the
+// *minimum* mutations, so concurrent edits merge instead of clobbering.
+//
+// Automerge's docs warn that spread-assignment (`d.x = {...d.x, k}`) replaces the
+// whole object and destroys its merge history. The reactive side, by contrast,
+// hands us a fresh immutable snapshot on every write (spread-replace all the way
+// up). `reconcile` bridges the two: called inside `handle.change`, it walks the
+// live doc against the snapshot and emits only the ops that actually differ —
+// `updateText` for strings (char-level), in-place splices for lists, recursive
+// descent for objects, scalar sets for the rest.
+//
+// List handling is intentionally simple for now: element-wise in place, with a
+// tail push/truncate. Correct for edits/appends/truncations; a reorder or mid
+// insert produces more ops than ideal. Identity-keyed list reconciliation is the
+// obvious upgrade (mirror the `eachBy` lens's `by`).
+import { updateText } from "@automerge/automerge-repo";
+const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+/** Minimally mutate the Automerge node `target` (inside `handle.change`) to equal
+ *  the plain value `next`. */
+export function reconcile(target, next) {
+    if (Array.isArray(next) && Array.isArray(target))
+        reconcileList(target, next);
+    else
+        reconcileObject(target, next);
+}
+function reconcileObject(target, next) {
+    for (const k of Object.keys(target))
+        if (!(k in next))
+            delete target[k];
+    for (const k of Object.keys(next))
+        setKey(target, k, target[k], next[k], false);
+}
+function reconcileList(target, next) {
+    const shared = Math.min(target.length, next.length);
+    for (let i = 0; i < shared; i++)
+        setKey(target, i, target[i], next[i], true);
+    if (next.length < target.length)
+        target.splice(next.length);
+    else
+        for (let i = target.length; i < next.length; i++)
+            target.push(next[i]);
+}
+function setKey(parent, key, a, b, inList) {
+    if (typeof b === "string" && typeof a === "string") {
+        // Char-level merge for object text fields; list string elements just assign
+        // (path-relative updateText targets a keyed field, not an array slot).
+        if (a !== b) {
+            if (inList)
+                parent[key] = b;
+            else
+                updateText(parent, [key], b);
+        }
+    }
+    else if (Array.isArray(b) && Array.isArray(a)) {
+        reconcileList(a, b);
+    }
+    else if (isPlainObject(b) && isPlainObject(a)) {
+        reconcileObject(a, b);
+    }
+    else if (a !== b) {
+        parent[key] = b;
+    }
+}

package/dist/core/_counts.d.ts

@@ -0,0 +1,48 @@
+export interface Counts {
+    /** A computed/lens/merge getter actually ran (the forward "work" unit). */
+    recompute: number;
+    /** `propagate` entered (a mark sweep down `subs`). */
+    propagate: number;
+    /** `checkDirty` entered (a validity pull up `deps`). */
+    checkDirty: number;
+    /** A dynamic forward edge (`Link`) was created. */
+    link: number;
+    /** A dynamic forward edge was dropped. */
+    unlink: number;
+    /** A back-write was armed (legal). */
+    arm: number;
+    /** A structurally-impossible write was rejected at `arm` (no work done). */
+    armBlocked: number;
+    /** Nodes visited descending the back-path in `markDown`. */
+    markDownVisit: number;
+    /** A reverse edge was spliced onto a parent's up-list. */
+    linkChild: number;
+    /** A reverse edge was released (view unwatched). */
+    unlinkChild: number;
+    /** Frames entered resolving back-cones (`enterCone`). */
+    resolveConeVisit: number;
+    /** Nodes popped committing a back-write (`writeBack`). */
+    writeBackVisit: number;
+    /** Steps of the co-writer re-assert scan (the fan-in re-assert cost). */
+    reassertScan: number;
+    /** A user `put` (1→1, tuple, or stateful backward) was invoked. */
+    put: number;
+    /** A merge `fold` was invoked. */
+    fold: number;
+    /** A stateful `step` was invoked (backward commit path). */
+    step: number;
+}
+/** Live counter record. Mutated in place so importers hold a stable reference. */
+export declare const counts: Counts;
+/** The single gate. Read at every instrumented site; flip via `withCounts`. */
+export declare let COUNTS: boolean;
+/** Reset all counters to zero (keeps the same object identity). */
+export declare function resetCounts(): void;
+/** Shallow copy of the current counts. */
+export declare function snapshotCounts(): Counts;
+/** Run `fn` with counting on from a zero baseline; returns the result and the
+ *  counts it accrued. Restores the prior gate state (counters left as measured). */
+export declare function withCounts<T>(fn: () => T): {
+    result: T;
+    counts: Counts;
+};

package/dist/core/_counts.js

@@ -0,0 +1,51 @@
+// Counts-first instrumentation: judge engine work by discrete event *counts*
+// (callbacks invoked, codepaths entered, nodes visited, edges spliced), not
+// timings, so a minimal engine has a calculable target. Off by default — each
+// site reads `if (COUNTS) counts.x++`, so a minifier drops it when off and it
+// costs one branch when on. Flip via `withCounts`.
+function fresh() {
+    return {
+        recompute: 0,
+        propagate: 0,
+        checkDirty: 0,
+        link: 0,
+        unlink: 0,
+        arm: 0,
+        armBlocked: 0,
+        markDownVisit: 0,
+        linkChild: 0,
+        unlinkChild: 0,
+        resolveConeVisit: 0,
+        writeBackVisit: 0,
+        reassertScan: 0,
+        put: 0,
+        fold: 0,
+        step: 0,
+    };
+}
+/** Live counter record. Mutated in place so importers hold a stable reference. */
+export const counts = fresh();
+/** The single gate. Read at every instrumented site; flip via `withCounts`. */
+export let COUNTS = false;
+/** Reset all counters to zero (keeps the same object identity). */
+export function resetCounts() {
+    Object.assign(counts, fresh());
+}
+/** Shallow copy of the current counts. */
+export function snapshotCounts() {
+    return { ...counts };
+}
+/** Run `fn` with counting on from a zero baseline; returns the result and the
+ *  counts it accrued. Restores the prior gate state (counters left as measured). */
+export function withCounts(fn) {
+    const prevOn = COUNTS;
+    resetCounts();
+    COUNTS = true;
+    try {
+        const result = fn();
+        return { result, counts: snapshotCounts() };
+    }
+    finally {
+        COUNTS = prevOn;
+    }
+}