bireactive 0.3.2 → 0.3.4

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

@@ -1,20 +1,37 @@
 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>;
+import { type By, type Replace } from "./reconcile.js";
+/** Bridge options shared by every `connect*` entry. */
+export interface DocOptions {
+    /** Identity key for list elements, enabling keyed reconciliation (see `reconcile`). */
+    by?: By;
+    /** Keys whose values are written wholesale (a `put`) rather than deep-merged —
+     *  for opaque blobs a downstream bridge can only apply as whole-object puts
+     *  (see `reconcile`'s `Replace`). */
+    replace?: Replace;
+}
+/** Lifecycle shared by every bridge: retarget the doc, detach both directions. */
+export interface DocLifecycle<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;
 }
+/** Doc bridged to a writable cell; writes (direct or via a lens) flow to the CRDT. */
+export interface CellBridge<T> extends DocLifecycle<T> {
+    cell: Writable<Cell<T>>;
+}
+/** Doc bridged to a deep `store` — `bridge.store.a.b.value = x` commits to the doc. */
+export interface StoreBridge<T> extends DocLifecycle<T> {
+    store: Store<T>;
+}
+/** Doc bridged to both a cell and a deep store. */
+export interface DocBridge<T> extends CellBridge<T>, StoreBridge<T> {
+}
+/** Connect a `DocHandle` to a reactive cell, syncing both ways. */
+export declare function connectCell<T extends object>(handle: DocHandle<T>, opts?: DocOptions): CellBridge<T>;
+/** Connect a `DocHandle` to a deep `store`, syncing both ways. */
+export declare function connectStore<T extends object>(handle: DocHandle<T>, opts?: DocOptions): StoreBridge<T>;
 /** 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>;
+export declare function connectDoc<T extends object>(handle: DocHandle<T>, opts?: DocOptions): DocBridge<T>;

package/dist/automerge/doc-cell.js

@@ -39,42 +39,49 @@ function deepEqual(a, b) {
     return true;
 }
 /** Wire an existing cell to a handle in both directions; returns an unbind. */
-function bind(c, handle) {
+function bind(c, handle, by, replace) {
     const onChange = () => {
         c.value = structuredClone(handle.doc());
     };
     handle.on("change", onChange);
     const stop = effect(() => {
         const next = c.value;
-        handle.change((d) => reconcile(d, next));
+        handle.change((d) => reconcile(d, next, by, replace));
     });
     return () => {
         stop();
         handle.off("change", onChange);
     };
 }
-/** Connect a `DocHandle` to a reactive cell + store, syncing both ways. */
-export function connectDoc(handle) {
+/** Core: a doc-backed cell plus lifecycle. The cell projections layer on top. */
+function connect(handle, opts) {
+    const by = opts?.by;
+    const replace = opts?.replace;
     const c = cell(structuredClone(handle.doc()), { equals: deepEqual, name: "doc" });
-    let unbind = bind(c, handle);
+    let unbind = bind(c, handle, by, replace);
     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);
+            unbind = bind(c, next, by, replace);
         },
         dispose: () => unbind(),
     };
 }
-/** Doc as a writable cell (page-lifetime; use {@link connectDoc} when you need disposal). */
-export function docCell(handle) {
-    return connectDoc(handle).cell;
+/** Connect a `DocHandle` to a reactive cell, syncing both ways. */
+export function connectCell(handle, opts) {
+    return connect(handle, opts);
+}
+/** Connect a `DocHandle` to a deep `store`, syncing both ways. */
+export function connectStore(handle, opts) {
+    const { cell: c, retarget, dispose } = connect(handle, opts);
+    return { store: store(c), retarget, dispose };
 }
-/** Doc as a deep store (page-lifetime; use {@link connectDoc} when you need disposal). */
-export function docStore(handle) {
-    return connectDoc(handle).store;
+/** Connect a `DocHandle` to a reactive cell + store, syncing both ways. */
+export function connectDoc(handle, opts) {
+    const b = connect(handle, opts);
+    return { ...b, store: store(b.cell) };
 }

package/dist/automerge/index.d.ts

@@ -1,3 +1,4 @@
-export type { DocBridge } from "./doc-cell.js";
-export { connectDoc, docCell, docStore } from "./doc-cell.js";
+export type { CellBridge, DocBridge, DocLifecycle, DocOptions, StoreBridge } from "./doc-cell.js";
+export { connectCell, connectDoc, connectStore } from "./doc-cell.js";
+export type { By, Replace } from "./reconcile.js";
 export { reconcile } from "./reconcile.js";

package/dist/automerge/index.js

@@ -1,12 +1,13 @@
 // @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.
+// `store`, synced both ways; `connectCell`/`connectStore` give just one projection.
+// Lens/`store` views 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 { connectCell, connectDoc, connectStore } from "./doc-cell.js";
 export { reconcile } from "./reconcile.js";

package/dist/automerge/reconcile.d.ts

@@ -1,5 +1,17 @@
 type Any = any;
+/** Stable identity key for a list element; return a primitive. `undefined` (or a
+ *  collision) on any element makes that list fall back to positional. */
+export type By = (element: unknown) => unknown;
+/** Predicate over an object key (or list index): return `true` to *replace* that
+ *  field's value wholesale (a scalar assignment → an Automerge `put`) instead of
+ *  recursively merging into it. Use this for opaque JSON blobs that a downstream
+ *  bridge can only consume as whole-object puts — e.g. tldraw's `richText`, whose
+ *  patch applier rejects nested text `splice`s and mis-reads nested `del`s. The
+ *  value is still only written when it actually differs, so unrelated commits
+ *  don't churn it. */
+export type Replace = (key: string | number) => boolean;
 /** Minimally mutate the Automerge node `target` (inside `handle.change`) to equal
- *  the plain value `next`. */
-export declare function reconcile(target: Any, next: Any): void;
+ *  the plain value `next`. Pass `by` for identity-keyed list reconciliation, and
+ *  `replace` to assign chosen keys wholesale instead of merging into them. */
+export declare function reconcile(target: Any, next: Any, by?: By, replace?: Replace): void;
 export {};

package/dist/automerge/reconcile.js

@@ -9,38 +9,142 @@
 // `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`).
+// List handling is positional by default: element-wise in place, with a tail
+// push/truncate. Correct for edits/appends/truncations, but a reorder or mid
+// insert rewrites every shifted slot's scalars — merge-hostile. Pass `by` for
+// identity-keyed reconciliation (mirrors the `eachBy` lens's `by`): a longest
+// common subsequence keeps shared elements in place and emits minimal keyed
+// splices/inserts for the rest, so reorders and mid-inserts merge cleanly.
 import { updateText } from "@automerge/automerge-repo";
 const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+/** Structural equality, used to skip a wholesale `replace` write when the field
+ *  is already deep-equal (so reconciling an unrelated change doesn't rewrite it).
+ *  Note `a` may be a live Automerge proxy: its *lists* don't expose indices via
+ *  `Object.keys`, so arrays are walked by length/index, not key enumeration. */
+function deepEq(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;
+    if (aArr) {
+        const av = a;
+        const bv = b;
+        if (av.length !== bv.length)
+            return false;
+        for (let i = 0; i < av.length; i++)
+            if (!deepEq(av[i], bv[i]))
+                return false;
+        return true;
+    }
+    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 (!deepEq(a[k], b[k]))
+            return false;
+    }
+    return true;
+}
 /** Minimally mutate the Automerge node `target` (inside `handle.change`) to equal
- *  the plain value `next`. */
-export function reconcile(target, next) {
+ *  the plain value `next`. Pass `by` for identity-keyed list reconciliation, and
+ *  `replace` to assign chosen keys wholesale instead of merging into them. */
+export function reconcile(target, next, by, replace) {
+    const ctx = { by, replace };
     if (Array.isArray(next) && Array.isArray(target))
-        reconcileList(target, next);
+        reconcileList(target, next, ctx);
     else
-        reconcileObject(target, next);
+        reconcileObject(target, next, ctx);
 }
-function reconcileObject(target, next) {
+function reconcileObject(target, next, ctx) {
     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);
+        setKey(target, k, target[k], next[k], false, ctx);
 }
-function reconcileList(target, next) {
+function reconcileList(target, next, ctx) {
+    if (ctx.by !== undefined && reconcileKeyed(target, next, ctx))
+        return;
     const shared = Math.min(target.length, next.length);
     for (let i = 0; i < shared; i++)
-        setKey(target, i, target[i], next[i], true);
+        setKey(target, i, target[i], next[i], true, ctx);
     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) {
+/** Keyed list reconcile via LCS. Returns false (→ positional fallback) when keys
+ *  aren't total + unique on either side. */
+function reconcileKeyed(target, next, ctx) {
+    const by = ctx.by;
+    const tKeys = target.map(by);
+    const nKeys = next.map(by);
+    if (!totalUnique(tKeys) || !totalUnique(nKeys))
+        return false;
+    const keep = lcs(tKeys, nKeys);
+    let i = 0; // cursor into `target`, which mutates as we splice
+    for (let n = 0; n < next.length; n++) {
+        if (keep.has(nKeys[n])) {
+            while (i < target.length && !keep.has(by(target[i])))
+                target.splice(i, 1);
+            setKey(target, i, target[i], next[n], true, ctx); // same identity → merge edits
+            i++;
+        }
+        else {
+            target.splice(i, 0, next[n]); // insert (new key, or a moved element re-placed)
+            i++;
+        }
+    }
+    if (i < target.length)
+        target.splice(i);
+    return true;
+}
+function totalUnique(keys) {
+    if (keys.some(k => k === undefined))
+        return false;
+    return new Set(keys).size === keys.length;
+}
+/** Keys of the longest common subsequence of `a` and `b` (`===` on keys). */
+function lcs(a, b) {
+    const n = a.length;
+    const m = b.length;
+    const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--)
+        for (let j = m - 1; j >= 0; j--)
+            dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+    const keep = new Set();
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) {
+            keep.add(a[i]);
+            i++;
+            j++;
+        }
+        else if (dp[i + 1][j] >= dp[i][j + 1])
+            i++;
+        else
+            j++;
+    }
+    return keep;
+}
+function setKey(parent, key, a, b, inList, ctx) {
+    // Wholesale-replace keys bypass the merge entirely: assign the value so
+    // Automerge emits a single `put` of the (re)built subtree — no nested text
+    // `splice`s, no `del`s — which is all some bridges can apply. Guard on
+    // deep-equality so reconciling an unrelated change doesn't rewrite it.
+    if (ctx.replace?.(key)) {
+        if (!deepEq(a, b))
+            parent[key] = b;
+        return;
+    }
     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).
@@ -52,10 +156,10 @@ function setKey(parent, key, a, b, inList) {
         }
     }
     else if (Array.isArray(b) && Array.isArray(a)) {
-        reconcileList(a, b);
+        reconcileList(a, b, ctx);
     }
     else if (isPlainObject(b) && isPlainObject(a)) {
-        reconcileObject(a, b);
+        reconcileObject(a, b, ctx);
     }
     else if (a !== b) {
         parent[key] = b;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bireactive",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Bi-directional reactive programming.",
   "type": "module",
   "main": "./dist/index.js",
@@ -53,13 +53,21 @@
     "postversion": "npm publish && git push --follow-tags"
   },
   "dependencies": {
-    "@automerge/automerge-repo": "^2.6.0-subduction.34",
-    "@automerge/automerge-repo-network-broadcastchannel": "^2.6.0-subduction.34",
-    "@automerge/automerge-repo-storage-indexeddb": "^2.6.0-subduction.34",
     "prism-esm": "^1.29.0-fix.6",
     "temml": "^0.13.3"
   },
+  "peerDependencies": {
+    "@automerge/automerge-repo": "^2.6.0-subduction.34"
+  },
+  "peerDependenciesMeta": {
+    "@automerge/automerge-repo": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@automerge/automerge-repo": "^2.6.0-subduction.34",
+    "@automerge/automerge-repo-network-broadcastchannel": "^2.6.0-subduction.34",
+    "@automerge/automerge-repo-storage-indexeddb": "^2.6.0-subduction.34",
     "@biomejs/biome": "2.4.15",
     "@preact/signals-core": "^1.14.2",
     "@types/node": "^22.0.0",