@jxsuite/collab 0.8.5 → 0.9.0

package/README.md

@@ -1,11 +1,8 @@
 # @jxsuite/collab
 
-Realtime co-editing for Jx Studio: the shared Y.Doc schema for a Jx document, the bridge between
-Studio's transactional op-log and Yjs, a structural differ, the binary wire envelope every collab
-backend speaks, and the provider contract Studio consumes through its Platform Abstraction Layer.
+Realtime co-editing for Jx Studio: the shared Y.Doc schema for a Jx document, the bridge between Studio's transactional op-log and Yjs, a structural differ, the binary wire envelope every collab backend speaks, and the provider contract Studio consumes through its Platform Abstraction Layer.
 
-Everything here is environment-agnostic TypeScript (no DOM, no Node/Bun APIs): the same modules run
-in the browser, in the `@jxsuite/server` dev server, and on Cloudflare Workers.
+Everything here is environment-agnostic TypeScript (no DOM, no Node/Bun APIs): the same modules run in the browser, in the `@jxsuite/server` dev server, and on Cloudflare Workers.
 
 ## The document model
 
@@ -18,28 +15,16 @@ One `Y.Doc` per open file:
 | `frontmatter: Y.Map` | Per-field plain-JSON values.                                                                                                                |
 | `meta: Y.Map`        | `schemaVersion`, `structureSeeded`, `canonical`, `canonicalRev`, `sourceFormat`.                                                            |
 
-The CRDT granularity deliberately equals Studio's op-log granularity: mutators emit whole-value
-`set-key`s and children splices, so those are the only merge points.
+The CRDT granularity deliberately equals Studio's op-log granularity: mutators emit whole-value `set-key`s and children splices, so those are the only merge points.
 
-**Seeding contract.** Providers seed only `source` from file bytes; they never parse or serialize
-Jx documents. Clients derive `structure` on first sync via `seedStructure()`, which is safe under
-concurrent seeders because it only performs whole-key `Y.Map` sets (per-key LWW keeps one seeder's
-subtrees wholesale; it never uses array inserts, which would duplicate). A client's `Y.Doc` must
-start empty; never seed locally before the provider's sync completes.
+**Seeding contract.** Providers seed only `source` from file bytes; they never parse or serialize Jx documents. Clients derive `structure` on first sync via `seedStructure()`, which is safe under concurrent seeders because it only performs whole-key `Y.Map` sets (per-key LWW keeps one seeder's subtrees wholesale; it never uses array inserts, which would duplicate). A client's `Y.Doc` must start empty; never seed locally before the provider's sync completes.
 
 ## The op bridge
 
-- `applyDocOpsToY(doc, ops, origin)` replays Studio's recorded forward `JxDocOp`s onto the Y tree
-  in one origin-tagged transaction (`LOCAL_ORIGIN` for user edits, `MIRROR_ORIGIN` for derived
-  writes, `SEED_ORIGIN` for bootstraps).
-- `yEventsToDocOps(events)` converts a remote transaction's deep events back into `JxDocOp`s.
-  Call it **inside** the `observeDeep` callback. It returns `null` for shapes it cannot convert
-  safely; reconcile by diffing instead.
-- `diffDocs(a, b)` produces ops transforming `a` into `b` (invariant: `apply(clone(a), diff(a,b))
-≡ b`); returns `null` past `maxOps`, in which case `replaceYStructure()` hard-replaces and bumps
-  `meta.canonicalRev` so stale mirror writes are discarded.
-- `applyDocOpToDoc` (in `./ops`, yjs-free) is the canonical plain-JSON applier shared with
-  Studio's history replay and canvas shadow doc.
+- `applyDocOpsToY(doc, ops, origin)` replays Studio's recorded forward `JxDocOp`s onto the Y tree in one origin-tagged transaction (`LOCAL_ORIGIN` for user edits, `MIRROR_ORIGIN` for derived writes, `SEED_ORIGIN` for bootstraps).
+- `yEventsToDocOps(events)` converts a remote transaction's deep events back into `JxDocOp`s. Call it **inside** the `observeDeep` callback. It returns `null` for shapes it cannot convert safely; reconcile by diffing instead.
+- `diffDocs(a, b)` produces ops transforming `a` into `b` (invariant: `apply(clone(a), diff(a,b)) ≡ b`); returns `null` past `maxOps`, in which case `replaceYStructure()` hard-replaces and bumps `meta.canonicalRev` so stale mirror writes are discarded.
+- `applyDocOpToDoc` (in `./ops`, yjs-free) is the canonical plain-JSON applier shared with Studio's history replay and canvas shadow doc.
 
 ## The wire envelope (`./envelope`)
 
@@ -53,34 +38,18 @@ frame          := varUint frameType, body
 3 CONTROL      := varString json    — hello | open | opened | doc-reset | flush | flush-ack | error
 ```
 
-`docEpoch` is the server-owned lifetime counter of a doc's Y history. **Y history is never deleted
-or replaced without an epoch bump**: out-of-band content replacement (git discard/pull/rename,
-non-collab writes) bumps it and broadcasts `doc-reset`; clients destroy their `Y.Doc` and re-open.
-Stale-epoch frames are dropped. This invariant is what prevents divergent-history duplicate-content
-merges.
+`docEpoch` is the server-owned lifetime counter of a doc's Y history. **Y history is never deleted or replaced without an epoch bump**: out-of-band content replacement (git discard/pull/rename, non-collab writes) bumps it and broadcasts `doc-reset`; clients destroy their `Y.Doc` and re-open. Stale-epoch frames are dropped. This invariant is what prevents divergent-history duplicate-content merges.
 
-Session flow: connect → server sends `hello{login, name?, avatarUrl?, color, permission}` → client
-sends `open{path}` per document → server ensures the room (loads persisted Y state or seeds
-`source` from the file) → `opened{path, epoch}` → y-protocols sync handshake → updates flow.
-Read-only sockets receive sync and may publish awareness, but their doc updates are dropped with
-one `error{read-only}`.
+Session flow: connect → server sends `hello{login, name?, avatarUrl?, color, permission}` → client sends `open{path}` per document → server ensures the room (loads persisted Y state or seeds `source` from the file) → `opened{path, epoch}` → y-protocols sync handshake → updates flow. Read-only sockets receive sync and may publish awareness, but their doc updates are dropped with one `error{read-only}`.
 
 ## Awareness (`./awareness-types`)
 
-One project-level `Awareness` per connection. State shape:
-`{ user: {login, name?, avatarUrl?, color}, focusedPath, mode?, structuralSelection?, selection? }`.
-File-tree presence (the plain `selection` field is the code view's in-buffer cursor) and
-per-document cursor overlays both filter the same states. Identity comes from the server `hello`;
-colors are deterministic (`colorForKey`).
+One project-level `Awareness` per connection. State shape: `{ user: {login, name?, avatarUrl?, color}, focusedPath, mode?, structuralSelection?, selection? }`. File-tree presence (the plain `selection` field is the code view's in-buffer cursor) and per-document cursor overlays both filter the same states. Identity comes from the server `hello`; colors are deterministic (`colorForKey`).
 
 ## Provider contract (`./provider`, type-only)
 
-`StudioPlatform.collab?: (docPath) => Promise<CollabHandle | null>` where a handle carries
-`{doc, awareness, whenSynced, identity(), flush(), onStatus(), onReset(), destroy()}`. `onReset`
-fires on a `doc-reset`: the handle is dead, so destroy it and re-acquire.
+`StudioPlatform.collab?: (docPath) => Promise<CollabHandle | null>` where a handle carries `{doc, awareness, whenSynced, identity(), flush(), onStatus(), onReset(), destroy()}`. `onReset` fires on a `doc-reset`: the handle is dead, so destroy it and re-acquire.
 
 ## Versioning
 
-Published to npm as `@jxsuite/collab`, following the monorepo's release train. Like every `@jxsuite`
-package, it ships TypeScript source. Within the monorepo, other packages (`@jxsuite/server`,
-`@jxsuite/studio`) depend on it via `workspace:^`.
+Published to npm as `@jxsuite/collab`, following the monorepo's release train. Like every `@jxsuite` package, it ships TypeScript source. Within the monorepo, other packages (`@jxsuite/server`, `@jxsuite/studio`) depend on it via `workspace:^`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/collab",
-  "version": "0.8.5",
+  "version": "0.9.0",
   "description": "Realtime co-editing for Jx Studio — Y.Doc schema, op bridge, structural differ, wire envelope, and provider contracts shared by every collab backend",
   "license": "MIT",
   "repository": {
@@ -18,6 +18,7 @@
     "./schema": "./src/schema.ts",
     "./op-bridge": "./src/op-bridge.ts",
     "./diff": "./src/diff.ts",
+    "./diff-core": "./src/diff-core.ts",
     "./envelope": "./src/envelope.ts",
     "./negotiate": "./src/negotiate.ts",
     "./awareness-types": "./src/awareness-types.ts",
@@ -33,7 +34,7 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/schema": "^2.1.0",
+    "@jxsuite/schema": "^2.2.0",
     "lib0": "^0.2.117",
     "y-protocols": "^1.0.7",
     "yjs": "13.6.32"

package/src/diff-core.ts

@@ -0,0 +1,290 @@
+/**
+ * The structural differ's pure half: alignment, equality, and `diffDocs`.
+ *
+ * `diffDocs(a, b)` produces JxDocOps that transform document `a` into `b` when replayed
+ * sequentially (property invariant: `apply(clone(a), diffDocs(a, b)) ≡ b`). The collab bridge uses
+ * it wherever no op-log exists — whole-document bypass writes (Monaco parse-flush, navigation,
+ * reload), un-instrumented transactions, and inbound Y transactions too gnarly for the fast event
+ * path.
+ *
+ * Children alignment: an LCS over strong keys (full-content hashes) pins unchanged nodes as
+ * anchors; the gaps between anchors align by a second LCS over weak signatures (tagName +
+ * id/$props.key) whose pairs diff recursively. Unmatched items become splices. Reorders of
+ * identical siblings therefore degrade to remove+insert — exactly what the Y move mapping does, so
+ * no fidelity is lost relative to the wire.
+ *
+ * **This file has no runtime imports, and that is its reason for existing.** It was the top of
+ * `./diff.ts`, which value-imports `./schema.ts` for `replaceYStructure` alone — and `schema.ts`
+ * imports yjs. So every consumer of the alignment logic paid for yjs, which put the studio's diff
+ * highlighting (`canvas/diff-marks.ts`) behind a lazy import for a computation that never touches a
+ * Y type. `diff.ts` re-exports everything here, so nothing that already imported it changed.
+ *
+ * {@link matchChildren} is exported for that studio caller: `diffDocs` emits a REPLAY SCRIPT whose
+ * paths are post-splice coordinates valid only in `b`, and a side-by-side comparison needs both
+ * sides' coordinates and the pairing between them. That is what a `ChildMatch` is, and re-deriving
+ * it would mean a second definition of "the same node".
+ */
+
+import type { JxMutableNode, JxPath } from "@jxsuite/schema/types";
+import type { JxDocOp } from "./ops.ts";
+
+export interface DiffOptions {
+  /** Abort (return null) when the diff would exceed this many ops; caller hard-replaces instead. */
+  maxOps?: number;
+}
+
+const DEFAULT_MAX_OPS = 500;
+
+class MaxOpsExceededError extends Error {
+  override name = "MaxOpsExceededError";
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Order-insensitive for object keys, order-sensitive for arrays. */
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) {
+    return true;
+  }
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((item, i) => deepEqual(item, b[i]));
+  }
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    return (
+      keysA.length === keysB.length && keysA.every((key) => key in b && deepEqual(a[key], b[key]))
+    );
+  }
+  return false;
+}
+
+function contentHash(text: string): string {
+  let hash = 5381;
+  for (let i = 0; i < text.length; i++) {
+    hash = Math.imul(hash, 33) + (text.codePointAt(i) ?? 0);
+  }
+  return hash.toString(36);
+}
+
+/** Full-content identity: equal strong keys mean "treat as the same unchanged child". */
+function strongKey(item: unknown): string {
+  return typeof item === "string" ? `s:${item}` : `n:${contentHash(JSON.stringify(item))}`;
+}
+
+/** Alignment identity: equal weak keys mean "same logical child, diff its contents". */
+function weakKey(item: unknown): string {
+  if (typeof item === "string") {
+    return "s";
+  }
+  const node = item as Record<string, unknown>;
+  const attrs = node["attributes"];
+  const props = node["$props"];
+  const id =
+    (isPlainObject(attrs) ? attrs["id"] : undefined) ??
+    (isPlainObject(props) ? props["key"] : undefined) ??
+    "";
+  return `w:${String(node["tagName"] ?? "")}:${String(id)}`;
+}
+
+/**
+ * Longest common subsequence over key arrays; returns strictly-increasing index pairs.
+ *
+ * `maxCells` bounds the DP TABLE, which is the only unbounded cost in this file. The comment below
+ * assumes "typically < 200" children, which a generated listing page falsifies. Over budget this
+ * answers "no common subsequence", so the caller degrades that group to plain removals and
+ * insertions instead of allocating an n*m table. Unbounded by default, so `diffDocs` is unchanged.
+ */
+function lcsPairs(
+  aKeys: readonly string[],
+  bKeys: readonly string[],
+  maxCells = Number.POSITIVE_INFINITY,
+): [number, number][] {
+  const n = aKeys.length;
+  const m = bKeys.length;
+  if (n === 0 || m === 0 || n * m > maxCells) {
+    return [];
+  }
+  // Classic DP table; children arrays are small (bounded by document size, typically < 200).
+  const table: number[][] = Array.from({ length: n + 1 }, () =>
+    Array.from({ length: m + 1 }, () => 0),
+  );
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      table[i]![j] =
+        aKeys[i] === bKeys[j]
+          ? table[i + 1]![j + 1]! + 1
+          : Math.max(table[i + 1]![j]!, table[i]![j + 1]!);
+    }
+  }
+  const pairs: [number, number][] = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (aKeys[i] === bKeys[j]) {
+      pairs.push([i, j]);
+      i += 1;
+      j += 1;
+    } else if (table[i + 1]![j]! >= table[i]![j + 1]!) {
+      i += 1;
+    } else {
+      j += 1;
+    }
+  }
+  return pairs;
+}
+
+/** One aligned pair of children, carrying BOTH sides' indices. */
+export interface ChildMatch {
+  aIndex: number;
+  bIndex: number;
+  /** Strong matches are byte-identical — no recursion needed. */
+  identical: boolean;
+}
+
+/** How much DP table {@link matchChildren} may allocate for one pair of children arrays. */
+export interface MatchOptions {
+  /** Skip the LCS and degrade to splices when `a.length * b.length` exceeds this. */
+  maxCells?: number;
+}
+
+/**
+ * Anchor by strong LCS, then align each gap by weak LCS. Matches never cross.
+ *
+ * Exported because both sides' indices are exactly what a side-by-side comparison needs, and
+ * {@link diffDocs} throws half of them away: its ops are a replay script addressed in `b`, so a
+ * removal names an index in `a` that the very next splice invalidates. Re-deriving the pairing from
+ * that output would mean a second definition of "the same node", which is the drift this export
+ * exists to prevent.
+ */
+export function matchChildren(
+  a: readonly unknown[],
+  b: readonly unknown[],
+  opts: MatchOptions = {},
+): ChildMatch[] {
+  const maxCells = opts.maxCells ?? Number.POSITIVE_INFINITY;
+  const anchors = lcsPairs(
+    a.map((item) => strongKey(item)),
+    b.map((item) => strongKey(item)),
+    maxCells,
+  );
+  const matches: ChildMatch[] = [];
+  let prevA = -1;
+  let prevB = -1;
+  const gaps: [number, number, number, number][] = [];
+  for (const [ai, bi] of anchors) {
+    gaps.push([prevA + 1, ai, prevB + 1, bi]);
+    matches.push({ aIndex: ai, bIndex: bi, identical: true });
+    prevA = ai;
+    prevB = bi;
+  }
+  gaps.push([prevA + 1, a.length, prevB + 1, b.length]);
+  for (const [aStart, aEnd, bStart, bEnd] of gaps) {
+    const aGap = a.slice(aStart, aEnd);
+    const bGap = b.slice(bStart, bEnd);
+    for (const [gi, gj] of lcsPairs(
+      aGap.map((item) => weakKey(item)),
+      bGap.map((item) => weakKey(item)),
+      maxCells,
+    )) {
+      matches.push({ aIndex: aStart + gi, bIndex: bStart + gj, identical: false });
+    }
+  }
+  return matches.toSorted((x, y) => x.aIndex - y.aIndex);
+}
+
+class Differ {
+  private readonly ops: JxDocOp[] = [];
+  private readonly maxOps: number;
+
+  constructor(maxOps: number) {
+    this.maxOps = maxOps;
+  }
+
+  result(): JxDocOp[] {
+    return this.ops;
+  }
+
+  private push(op: JxDocOp): void {
+    if (this.ops.length >= this.maxOps) {
+      throw new MaxOpsExceededError();
+    }
+    this.ops.push(op);
+  }
+
+  diffNode(path: JxPath, a: Record<string, unknown>, b: Record<string, unknown>): void {
+    for (const key of new Set([...Object.keys(a), ...Object.keys(b)])) {
+      if (key === "children") {
+        continue;
+      }
+      if (!(key in b)) {
+        this.push({ key, op: "set-key", path });
+      } else if (!deepEqual(a[key], b[key])) {
+        this.push({ key, op: "set-key", path, value: b[key] });
+      }
+    }
+    const ca = a["children"];
+    const cb = b["children"];
+    if (Array.isArray(ca) && Array.isArray(cb)) {
+      this.diffChildren(path, ca, cb);
+    } else if (!deepEqual(ca, cb)) {
+      // Mapped-array children (or one side missing entirely) replace whole, like the mutators do.
+      this.push({ key: "children", op: "set-key", path, value: cb });
+    }
+  }
+
+  private diffChildren(path: JxPath, a: readonly unknown[], b: readonly unknown[]): void {
+    const matches = matchChildren(a, b);
+    const matchedA = new Set(matches.map((match) => match.aIndex));
+    const byB = new Map(matches.map((match) => [match.bIndex, match]));
+
+    // Removals first, in descending original index — each splice leaves lower indices intact.
+    for (let i = a.length - 1; i >= 0; i--) {
+      if (!matchedA.has(i)) {
+        this.push({ index: i, op: "remove-child", parentPath: path });
+      }
+    }
+    // Then walk b ascending: inserts land at their final index; matched pairs already sit there
+    // (matches never cross), so recursion paths are valid as emitted.
+    for (let i = 0; i < b.length; i++) {
+      const match = byB.get(i);
+      if (!match) {
+        this.push({ index: i, node: b[i], op: "insert-child", parentPath: path });
+        continue;
+      }
+      if (match.identical) {
+        continue;
+      }
+      const aItem = a[match.aIndex];
+      const bItem = b[i];
+      if (isPlainObject(aItem) && isPlainObject(bItem)) {
+        this.diffNode([...path, "children", i], aItem, bItem);
+      } else if (!deepEqual(aItem, bItem)) {
+        this.push({ index: i, node: bItem, op: "set-child", parentPath: path });
+      }
+    }
+  }
+}
+
+/**
+ * Ops that transform `a` into `b` when replayed sequentially, or null when the change is too large
+ * to express surgically (caller should hard-replace and reset).
+ */
+export function diffDocs(
+  a: JxMutableNode,
+  b: JxMutableNode,
+  opts: DiffOptions = {},
+): JxDocOp[] | null {
+  const differ = new Differ(opts.maxOps ?? DEFAULT_MAX_OPS);
+  try {
+    differ.diffNode([], a as Record<string, unknown>, b as Record<string, unknown>);
+  } catch (error) {
+    if (error instanceof MaxOpsExceededError) {
+      return null;
+    }
+    throw error;
+  }
+  return differ.result();
+}

package/src/diff.ts

@@ -1,249 +1,19 @@
 /**
- * Structural differ: `diffDocs(a, b)` produces JxDocOps that transform document `a` into `b` when
- * replayed sequentially (property invariant: `apply(clone(a), diffDocs(a, b)) ≡ b`). The collab
- * bridge uses it wherever no op-log exists — whole-document bypass writes (Monaco parse-flush,
- * navigation, reload), un-instrumented transactions, and inbound Y transactions too gnarly for the
- * fast event path.
+ * `replaceYStructure` — the diff-overflow escape hatch, and the one export here that needs yjs.
  *
- * Children alignment: an LCS over strong keys (full-content hashes) pins unchanged nodes as
- * anchors; the gaps between anchors align by a second LCS over weak signatures (tagName +
- * id/$props.key) whose pairs diff recursively. Unmatched items become splices. Reorders of
- * identical siblings therefore degrade to remove+insert — exactly what the Y move mapping does, so
- * no fidelity is lost relative to the wire.
+ * The alignment and equality logic this file used to hold lives in {@link file://./diff-core.ts} and
+ * is re-exported below, so every importer of `@jxsuite/collab/diff` is unchanged. It moved because
+ * THIS file's `./schema.ts` import is a value import and `schema.ts` imports yjs, while `diff.ts`'s
+ * own `import type * as Y` made it look otherwise: `diffDocs` and `deepEqual` are pure, and a
+ * caller that wanted them — the studio's diff highlighting — had no way to take them without taking
+ * a yjs-sized chunk with them.
  */
 
-import type { JxMutableNode, JxPath } from "@jxsuite/schema/types";
-import type { JxDocOp } from "./ops.ts";
+import type { JxMutableNode } from "@jxsuite/schema/types";
 import { metaMap, structureMap, toYChildren } from "./schema.ts";
 import type * as Y from "yjs";
 
-export interface DiffOptions {
-  /** Abort (return null) when the diff would exceed this many ops; caller hard-replaces instead. */
-  maxOps?: number;
-}
-
-const DEFAULT_MAX_OPS = 500;
-
-class MaxOpsExceededError extends Error {
-  override name = "MaxOpsExceededError";
-}
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-/** Order-insensitive for object keys, order-sensitive for arrays. */
-export function deepEqual(a: unknown, b: unknown): boolean {
-  if (a === b) {
-    return true;
-  }
-  if (Array.isArray(a) && Array.isArray(b)) {
-    return a.length === b.length && a.every((item, i) => deepEqual(item, b[i]));
-  }
-  if (isPlainObject(a) && isPlainObject(b)) {
-    const keysA = Object.keys(a);
-    const keysB = Object.keys(b);
-    return (
-      keysA.length === keysB.length && keysA.every((key) => key in b && deepEqual(a[key], b[key]))
-    );
-  }
-  return false;
-}
-
-function contentHash(text: string): string {
-  let hash = 5381;
-  for (let i = 0; i < text.length; i++) {
-    hash = Math.imul(hash, 33) + (text.codePointAt(i) ?? 0);
-  }
-  return hash.toString(36);
-}
-
-/** Full-content identity: equal strong keys mean "treat as the same unchanged child". */
-function strongKey(item: unknown): string {
-  return typeof item === "string" ? `s:${item}` : `n:${contentHash(JSON.stringify(item))}`;
-}
-
-/** Alignment identity: equal weak keys mean "same logical child, diff its contents". */
-function weakKey(item: unknown): string {
-  if (typeof item === "string") {
-    return "s";
-  }
-  const node = item as Record<string, unknown>;
-  const attrs = node["attributes"];
-  const props = node["$props"];
-  const id =
-    (isPlainObject(attrs) ? attrs["id"] : undefined) ??
-    (isPlainObject(props) ? props["key"] : undefined) ??
-    "";
-  return `w:${String(node["tagName"] ?? "")}:${String(id)}`;
-}
-
-/** Longest common subsequence over key arrays; returns strictly-increasing index pairs. */
-function lcsPairs(aKeys: readonly string[], bKeys: readonly string[]): [number, number][] {
-  const n = aKeys.length;
-  const m = bKeys.length;
-  if (n === 0 || m === 0) {
-    return [];
-  }
-  // Classic DP table; children arrays are small (bounded by document size, typically < 200).
-  const table: number[][] = Array.from({ length: n + 1 }, () =>
-    Array.from({ length: m + 1 }, () => 0),
-  );
-  for (let i = n - 1; i >= 0; i--) {
-    for (let j = m - 1; j >= 0; j--) {
-      table[i]![j] =
-        aKeys[i] === bKeys[j]
-          ? table[i + 1]![j + 1]! + 1
-          : Math.max(table[i + 1]![j]!, table[i]![j + 1]!);
-    }
-  }
-  const pairs: [number, number][] = [];
-  let i = 0;
-  let j = 0;
-  while (i < n && j < m) {
-    if (aKeys[i] === bKeys[j]) {
-      pairs.push([i, j]);
-      i += 1;
-      j += 1;
-    } else if (table[i + 1]![j]! >= table[i]![j + 1]!) {
-      i += 1;
-    } else {
-      j += 1;
-    }
-  }
-  return pairs;
-}
-
-interface ChildMatch {
-  aIndex: number;
-  bIndex: number;
-  /** Strong matches are byte-identical — no recursion needed. */
-  identical: boolean;
-}
-
-/** Anchor by strong LCS, then align each gap by weak LCS. Matches never cross. */
-function matchChildren(a: readonly unknown[], b: readonly unknown[]): ChildMatch[] {
-  const anchors = lcsPairs(
-    a.map((item) => strongKey(item)),
-    b.map((item) => strongKey(item)),
-  );
-  const matches: ChildMatch[] = [];
-  let prevA = -1;
-  let prevB = -1;
-  const gaps: [number, number, number, number][] = [];
-  for (const [ai, bi] of anchors) {
-    gaps.push([prevA + 1, ai, prevB + 1, bi]);
-    matches.push({ aIndex: ai, bIndex: bi, identical: true });
-    prevA = ai;
-    prevB = bi;
-  }
-  gaps.push([prevA + 1, a.length, prevB + 1, b.length]);
-  for (const [aStart, aEnd, bStart, bEnd] of gaps) {
-    const aGap = a.slice(aStart, aEnd);
-    const bGap = b.slice(bStart, bEnd);
-    for (const [gi, gj] of lcsPairs(
-      aGap.map((item) => weakKey(item)),
-      bGap.map((item) => weakKey(item)),
-    )) {
-      matches.push({ aIndex: aStart + gi, bIndex: bStart + gj, identical: false });
-    }
-  }
-  return matches.toSorted((x, y) => x.aIndex - y.aIndex);
-}
-
-class Differ {
-  private readonly ops: JxDocOp[] = [];
-  private readonly maxOps: number;
-
-  constructor(maxOps: number) {
-    this.maxOps = maxOps;
-  }
-
-  result(): JxDocOp[] {
-    return this.ops;
-  }
-
-  private push(op: JxDocOp): void {
-    if (this.ops.length >= this.maxOps) {
-      throw new MaxOpsExceededError();
-    }
-    this.ops.push(op);
-  }
-
-  diffNode(path: JxPath, a: Record<string, unknown>, b: Record<string, unknown>): void {
-    for (const key of new Set([...Object.keys(a), ...Object.keys(b)])) {
-      if (key === "children") {
-        continue;
-      }
-      if (!(key in b)) {
-        this.push({ key, op: "set-key", path });
-      } else if (!deepEqual(a[key], b[key])) {
-        this.push({ key, op: "set-key", path, value: b[key] });
-      }
-    }
-    const ca = a["children"];
-    const cb = b["children"];
-    if (Array.isArray(ca) && Array.isArray(cb)) {
-      this.diffChildren(path, ca, cb);
-    } else if (!deepEqual(ca, cb)) {
-      // Mapped-array children (or one side missing entirely) replace whole, like the mutators do.
-      this.push({ key: "children", op: "set-key", path, value: cb });
-    }
-  }
-
-  private diffChildren(path: JxPath, a: readonly unknown[], b: readonly unknown[]): void {
-    const matches = matchChildren(a, b);
-    const matchedA = new Set(matches.map((match) => match.aIndex));
-    const byB = new Map(matches.map((match) => [match.bIndex, match]));
-
-    // Removals first, in descending original index — each splice leaves lower indices intact.
-    for (let i = a.length - 1; i >= 0; i--) {
-      if (!matchedA.has(i)) {
-        this.push({ index: i, op: "remove-child", parentPath: path });
-      }
-    }
-    // Then walk b ascending: inserts land at their final index; matched pairs already sit there
-    // (matches never cross), so recursion paths are valid as emitted.
-    for (let i = 0; i < b.length; i++) {
-      const match = byB.get(i);
-      if (!match) {
-        this.push({ index: i, node: b[i], op: "insert-child", parentPath: path });
-        continue;
-      }
-      if (match.identical) {
-        continue;
-      }
-      const aItem = a[match.aIndex];
-      const bItem = b[i];
-      if (isPlainObject(aItem) && isPlainObject(bItem)) {
-        this.diffNode([...path, "children", i], aItem, bItem);
-      } else if (!deepEqual(aItem, bItem)) {
-        this.push({ index: i, node: bItem, op: "set-child", parentPath: path });
-      }
-    }
-  }
-}
-
-/**
- * Ops that transform `a` into `b` when replayed sequentially, or null when the change is too large
- * to express surgically (caller should hard-replace and reset).
- */
-export function diffDocs(
-  a: JxMutableNode,
-  b: JxMutableNode,
-  opts: DiffOptions = {},
-): JxDocOp[] | null {
-  const differ = new Differ(opts.maxOps ?? DEFAULT_MAX_OPS);
-  try {
-    differ.diffNode([], a as Record<string, unknown>, b as Record<string, unknown>);
-  } catch (error) {
-    if (error instanceof MaxOpsExceededError) {
-      return null;
-    }
-    throw error;
-  }
-  return differ.result();
-}
+export * from "./diff-core.ts";
 
 /**
  * Hard-replace the structure tree with `document` (the diff-overflow escape hatch) and bump the