@jxsuite/collab 0.8.5 → 0.10.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`, `inverseOf` and `applyDocOpsWithInverse` (in `./ops`, yjs-free) re-export the canonical plain-JSON op vocabulary from `@jxsuite/schema/doc-ops`, shared with Studio's history replay and the canvas shadow doc, so a host without yjs can apply the same ops.
 
 ## 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.10.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,9 +34,9 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/schema": "^2.1.0",
-    "lib0": "^0.2.117",
+    "@jxsuite/schema": "^2.3.0",
+    "lib0": "^0.2.119",
     "y-protocols": "^1.0.7",
-    "yjs": "13.6.32"
+    "yjs": "13.6.33"
   }
 }

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

package/src/ops.ts

@@ -1,128 +1,16 @@
 /**
- * The canonical Jx document-op vocabulary and its pure applier. A `JxDocOp` is a value-carrying,
- * replayable mutation of a plain-JSON Jx document tree, addressed by `JxPath` (alternating
- * "children" / index segments for structure, plus node keys). Studio's transaction pipeline records
- * forward/inverse pairs of these for history replay; the collab bridge mirrors them into a shared
- * Y.Doc.
+ * The Jx document-op vocabulary, re-exported from its home in `@jxsuite/schema/doc-ops`.
  *
- * This module is deliberately yjs-free and dependency-light: the slim canvas-iframe bundle imports
- * the applier for its non-reactive shadow doc, and it MUST stay byte-identical in behavior to the
- * parent's history replay — both sides import this one implementation.
+ * It moved so a host with no yjs (a Durable Object, a headless tool) can edit a document the way
+ * Studio does. This subpath stays so every existing `@jxsuite/collab/ops` import keeps working.
  */
 
-import type { JxMutableNode, JxPath } from "@jxsuite/schema/types";
-
-/** Value-carrying document mutation, replayable in either direction. */
-export type JxDocOp =
-  /** Set (or delete, when value is undefined) a key on the node at path. */
-  | { op: "set-key"; path: JxPath; key: string; value?: unknown }
-  /** Insert a node at parentPath.children[index]. */
-  | { op: "insert-child"; parentPath: JxPath; index: number; node: unknown }
-  /** Remove parentPath.children[index]. */
-  | { op: "remove-child"; parentPath: JxPath; index: number }
-  /** Replace parentPath.children[index] with node. */
-  | { op: "set-child"; parentPath: JxPath; index: number; node: unknown }
-  /** Raw two-splice move: remove fromParent.children[fromIndex], insert at toParent[toIndex]. */
-  | {
-      op: "move-child";
-      fromParentPath: JxPath;
-      fromIndex: number;
-      toParentPath: JxPath;
-      toIndex: number;
-    };
-
-export interface JxDocOpPair {
-  forward: JxDocOp;
-  inverse: JxDocOp;
-}
-
-/** JSON round-trip clone — also normalizes away reactive proxies / functions / undefined. */
-function jsonClone<T>(value: T): T {
-  // oxlint-disable-next-line unicorn/prefer-structured-clone -- structuredClone throws on reactive proxies; JSON normalization is the point
-  return JSON.parse(JSON.stringify(value)) as T;
-}
-
-/** Deep-clone a recorded value (undefined/null pass through; reactive proxies are read through). */
-export function cloneValue<T>(v: T): T {
-  return v === undefined || v === null ? v : (jsonClone(v as object) as T);
-}
-
-/**
- * Walk a plain document tree by path. Paths address nodes by construction; missing segments and
- * non-node leaves surface as undefined (typed as node for caller ergonomics, matching Studio's
- * historical helper).
- */
-export function getNodeAtPath(doc: JxMutableNode, path: JxPath): JxMutableNode {
-  let node = doc;
-  for (const key of path) {
-    if (node == null) {
-      return undefined as unknown as JxMutableNode;
-    }
-    node = node[key] as JxMutableNode;
-  }
-  return node;
-}
-
-/** The node's children array, lazily created; throws if `node` is itself a children array or mapped. */
-export function childArray(node: JxMutableNode): (JxMutableNode | string)[] {
-  // Defense-in-depth: a path that resolves to a children array (rather than a node) would
-  // Otherwise get a bogus `.children` property tacked on here, silently storing the insert where
-  // Nothing renders. Callers must pass a node; fail loudly if they don't.
-  if (Array.isArray(node)) {
-    throw new TypeError("Cannot insert into a children array; parentPath must point at a node");
-  }
-  if (!node.children) {
-    node.children = [];
-  }
-  if (!Array.isArray(node.children)) {
-    throw new TypeError("Cannot insert into mapped-array children; edit the map template instead");
-  }
-  return node.children;
-}
-
-/**
- * Apply a replayable doc op to a bare document tree. Values/nodes are cloned in, so the tree never
- * aliases the op object. Throws (with a machine-readable reason) when a target path is missing.
- */
-export function applyDocOpToDoc(doc: JxMutableNode, op: JxDocOp): void {
-  switch (op.op) {
-    case "set-key": {
-      const node = getNodeAtPath(doc, op.path);
-      if (!node) {
-        throw new Error(`doc-op-node-not-found:${op.path.join("/")}`);
-      }
-      const target = node as Record<string, unknown>;
-      if (op.value === undefined) {
-        delete target[op.key];
-      } else {
-        target[op.key] = cloneValue(op.value);
-      }
-      return;
-    }
-    case "insert-child": {
-      const parent = getNodeAtPath(doc, op.parentPath);
-      childArray(parent).splice(op.index, 0, cloneValue(op.node) as JxMutableNode);
-      return;
-    }
-    case "remove-child": {
-      const parent = getNodeAtPath(doc, op.parentPath);
-      childArray(parent).splice(op.index, 1);
-      return;
-    }
-    case "set-child": {
-      const parent = getNodeAtPath(doc, op.parentPath);
-      childArray(parent).splice(op.index, 1, cloneValue(op.node) as JxMutableNode);
-      return;
-    }
-    case "move-child": {
-      const fromParent = getNodeAtPath(doc, op.fromParentPath);
-      const toParent = getNodeAtPath(doc, op.toParentPath);
-      const [node] = childArray(fromParent).splice(op.fromIndex, 1);
-      childArray(toParent).splice(op.toIndex, 0, node!);
-      return;
-    }
-    default: {
-      throw new Error(`unknown-doc-op:${(op as JxDocOp).op}`);
-    }
-  }
-}
+export {
+  applyDocOpToDoc,
+  applyDocOpsWithInverse,
+  childArray,
+  cloneValue,
+  getNodeAtPath,
+  inverseOf,
+} from "@jxsuite/schema/doc-ops";
+export type { JxDocOp, JxDocOpPair } from "@jxsuite/schema/doc-ops";