@jxsuite/collab 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/collab",
-  "version": "0.5.0",
+  "version": "0.6.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": {
@@ -32,7 +32,7 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/schema": "^1.3.0",
+    "@jxsuite/schema": "^1.5.0",
     "lib0": "^0.2.99",
     "y-protocols": "^1.0.6",
     "yjs": "13.6.27"

package/src/op-bridge.ts

@@ -14,7 +14,17 @@
 import * as Y from "yjs";
 import type { JxPath } from "@jxsuite/schema/types";
 import type { JxDocOp } from "./ops.ts";
-import { resolveYPath, toYChildren, toYNode, yValueToJson } from "./schema.ts";
+import {
+  applyTextEdit,
+  GRANULAR_OBJECT_KEYS,
+  mergeYObject,
+  resolveYPath,
+  TEXT_KEYS,
+  toYChild,
+  toYChildren,
+  toYObject,
+  yValueToJson,
+} from "./schema.ts";
 
 /** Origin of Y transactions produced by mirroring the local tab's ops. */
 export const LOCAL_ORIGIN = "jx-local";
@@ -59,8 +69,47 @@ function cloneJson<T>(value: T): T {
   return JSON.parse(JSON.stringify(value)) as T;
 }
 
-function toYChild(node: unknown): unknown {
-  return typeof node === "string" ? node : toYNode(node);
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Write a node key, preserving CRDT identity wherever the schema stores it granularly.
+ *
+ * Studio's mutators record whole-value `set-key` ops — `mutateUpdateStyle` replaces the entire
+ * style object, an inline-edit commit replaces the entire `textContent`. Writing those straight
+ * through with `Y.Map.set` mints a fresh Y type each time and throws away whatever a peer
+ * concurrently did to the old one, which is exactly how "two people typing in one paragraph" became
+ * last-writer-wins.
+ *
+ * So a whole-value op is diffed down onto the existing structure: text through {@link applyTextEdit}
+ * (character-level), granular objects through {@link mergeYObject} (per-property). Only a TYPE
+ * change — string text becoming a `$ref`, an object becoming a scalar — falls back to replacement,
+ * because then there is no shared structure left to preserve.
+ */
+function setNodeKey(node: Y.Map<unknown>, key: string, value: unknown): void {
+  const existing = node.get(key);
+  if (key === "children" && Array.isArray(value)) {
+    node.set(key, toYChildren(value));
+    return;
+  }
+  if (TEXT_KEYS.has(key) && typeof value === "string") {
+    if (existing instanceof Y.Text) {
+      applyTextEdit(existing, value);
+    } else {
+      node.set(key, new Y.Text(value));
+    }
+    return;
+  }
+  if (GRANULAR_OBJECT_KEYS.has(key) && isPlainObject(value)) {
+    if (existing instanceof Y.Map) {
+      mergeYObject(existing, value);
+    } else {
+      node.set(key, toYObject(value));
+    }
+    return;
+  }
+  node.set(key, cloneJson(value));
 }
 
 function applyOneOp(doc: Y.Doc, op: JxDocOp): void {
@@ -69,10 +118,8 @@ function applyOneOp(doc: Y.Doc, op: JxDocOp): void {
       const node = requireNode(doc, op.path);
       if (op.value === undefined) {
         node.delete(op.key);
-      } else if (op.key === "children" && Array.isArray(op.value)) {
-        node.set(op.key, toYChildren(op.value));
       } else {
-        node.set(op.key, cloneJson(op.value));
+        setNodeKey(node, op.key, op.value);
       }
       return;
     }
@@ -97,6 +144,14 @@ function applyOneOp(doc: Y.Doc, op: JxDocOp): void {
       if (op.index < 0 || op.index >= children.length) {
         throw new CollabPathError([...op.parentPath, "children", op.index]);
       }
+      // Text child → text child: edit the existing Y.Text in place. A delete+insert would replace the
+      // Whole element and discard a peer's concurrent characters, which is the same clobber
+      // `setNodeKey` avoids for `textContent` — bare-string children are the other half of prose.
+      const existing = children.get(op.index);
+      if (existing instanceof Y.Text && typeof op.node === "string") {
+        applyTextEdit(existing, op.node);
+        return;
+      }
       children.delete(op.index, 1);
       children.insert(op.index, [toYChild(op.node)]);
       return;
@@ -139,6 +194,34 @@ export function applyDocOpsToY(doc: Y.Doc, ops: readonly JxDocOp[], origin: unkn
   }, origin);
 }
 
+/**
+ * When `path` addresses a granular container (or something nested inside one), the node that owns
+ * it and the key it sits under; otherwise null.
+ *
+ * The event path is relative to the structure map, so the first segment matching a granular key
+ * marks the boundary: everything before it is the node path, and anything after it is interior
+ * detail the op log does not model.
+ *
+ * `children`/index segments need no special handling: they are not granular keys, so the scan
+ * passes over them and the returned node path keeps the full prefix — `["children", 0, "style"]`
+ * resolves to the style of the node at `children/0`, not of the root.
+ */
+function granularOwner(path: JxPath): { nodePath: JxPath; key: string } | null {
+  for (let i = 0; i < path.length; i++) {
+    const segment = path[i];
+    if (typeof segment !== "string") {
+      continue;
+    }
+    if (GRANULAR_OBJECT_KEYS.has(segment)) {
+      return { key: segment, nodePath: path.slice(0, i) };
+    }
+    if (TEXT_KEYS.has(segment)) {
+      return { key: segment, nodePath: path.slice(0, i) };
+    }
+  }
+  return null;
+}
+
 function isStructurePath(segments: readonly (string | number)[]): segments is JxPath {
   return segments.every((seg) => typeof seg === "string" || typeof seg === "number");
 }
@@ -179,6 +262,45 @@ export function yEventsToDocOps(events: readonly Y.YEvent<never>[]): JxDocOp[] |
   const ops: JxDocOp[] = [];
   for (const event of events) {
     const path = event.path as JxPath;
+    /*
+     * A remote edit inside a granular container (a `Y.Text` for prose, a nested `Y.Map` for
+     * style/attributes/$props) reports its event at the CONTAINER's path, not the node's. Studio's op
+     * vocabulary addresses nodes, so those collapse back to one whole-value op for the owning key —
+     * the same shape a local mutator would have produced. Granularity buys merge; it deliberately does
+     * not leak into the op log, the canvas patcher, or the history ring.
+     */
+    const granular = granularOwner(path);
+    if (granular) {
+      const { doc } = event.target as { doc?: Y.Doc | null };
+      if (!doc) {
+        return null;
+      }
+      const container = resolveYPath(doc, [...granular.nodePath, granular.key]);
+      if (container === undefined) {
+        return null;
+      }
+      ops.push({
+        key: granular.key,
+        op: "set-key",
+        path: granular.nodePath,
+        value: yValueToJson(container),
+      });
+      continue;
+    }
+    if (event instanceof Y.YTextEvent) {
+      // A bare-string child: the text IS the child, so it round-trips as a child replacement.
+      const index = path.at(-1);
+      if (path.at(-2) === "children" && typeof index === "number") {
+        ops.push({
+          index,
+          node: (event.target as Y.Text).toString(),
+          op: "set-child",
+          parentPath: path.slice(0, -2),
+        });
+        continue;
+      }
+      return null;
+    }
     if (event instanceof Y.YMapEvent) {
       const target = event.target as Y.Map<unknown>;
       for (const [key, change] of event.changes.keys) {

package/src/schema.ts

@@ -4,15 +4,24 @@
  * Layout (all top-level types, created on demand): - `meta: Y.Map` — schemaVersion,
  * structureSeeded, canonical ("structure" | "source"), canonicalRev (representation-flip counter —
  * distinct from the provider's wire docEpoch), sourceFormat. - `frontmatter: Y.Map` — per-field
- * plain-JSON values (LWW per field). - `structure: Y.Map` — the root JxMutableNode. Every node is a
- * Y.Map whose ONLY nested Y container is "children" (a Y.Array of node Y.Maps and plain strings);
- * every other key holds a plain deep-JSON value merged whole (LWW). The CRDT granularity
- * deliberately equals Studio's op-log granularity — mutators emit whole-value set-keys and children
- * splices, so deeper Y types would add merge surface nothing can target. - `source: Y.Text` — the
- * serialized source. THE authoritative file content: providers persist
+ * plain-JSON values (LWW per field). - `structure: Y.Map` — the root JxMutableNode. - `source:
+ * Y.Text` — the serialized source. THE authoritative file content: providers persist
  * `getText("source").toString()` and never parse or serialize Jx documents themselves; the
  * structure tree is a Studio-side projection kept in sync by the bridge.
  *
+ * **CRDT granularity is deliberately FINER than Studio's op-log granularity.** Every node is a
+ * Y.Map; within it, "children" is a Y.Array, {@link TEXT_KEYS} are `Y.Text`,
+ * {@link GRANULAR_OBJECT_KEYS} are nested Y.Maps, and everything else is a whole-JSON LWW value.
+ *
+ * The two granularities used to match, on the reasoning that mutators emit whole-value set-keys so
+ * deeper Y types would add merge surface nothing targets. That reasoning was wrong: it conflated
+ * what an EDIT addresses with what a MERGE must resolve. Two authors typing in one paragraph, or
+ * setting `color` and `padding` on one element, produce whole-value ops that a whole-value CRDT can
+ * only resolve by discarding one of them. The bridge therefore diffs a whole-value op down onto the
+ * granular representation ({@link applyTextEdit}, {@link mergeYObject}) and {@link yValueToJson}
+ * reassembles whole values on the way out — so `JxDocOp`, the canvas patcher and the history ring
+ * are unchanged, while concurrent edits actually merge.
+ *
  * Seeding contract: providers seed only `source` (from file bytes). Clients derive `structure` on
  * first sync via {@link seedStructure}, which is convergence-safe under concurrent seeders because
  * it only performs whole-key Y.Map sets (per-key LWW picks one seeder's subtrees wholesale) — never
@@ -27,7 +36,16 @@ export const FRONTMATTER_KEY = "frontmatter";
 export const STRUCTURE_KEY = "structure";
 export const SOURCE_KEY = "source";
 
-export const COLLAB_SCHEMA_VERSION = 1;
+/**
+ * Bumped to 2 when prose moved to `Y.Text` and style/attributes/$props to nested `Y.Map`s.
+ *
+ * Written into `meta` at seed time and not currently validated on load. A room persisted under 1
+ * still READS correctly ({@link yValueToJson} passes plain values through) and self-heals on the
+ * first edit to a given key, since the bridge replaces a non-granular container. Two clients
+ * running DIFFERENT versions in one room would disagree about merge granularity — see §5 of
+ * specs/collab.md on version skew, which this does not attempt to solve.
+ */
+export const COLLAB_SCHEMA_VERSION = 2;
 
 export function metaMap(doc: Y.Doc): Y.Map<unknown> {
   return doc.getMap(META_KEY);
@@ -55,17 +73,137 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-/** A children array becomes a Y.Array of node Y.Maps and plain strings. */
+/**
+ * Node keys whose STRING value is stored as a `Y.Text` rather than an opaque string.
+ *
+ * This is the character-level-collaboration decision. Whole-paragraph last-writer-wins was never a
+ * Yjs limitation — it was this schema storing prose as a plain LWW value, so two people typing in
+ * one paragraph clobbered each other and only `source` (which the canvas does not edit) merged per
+ * character.
+ *
+ * `innerHTML` is deliberately absent: it is an opaque markup blob, never caret-edited.
+ */
+export const TEXT_KEYS: ReadonlySet<string> = new Set(["textContent"]);
+
+/**
+ * Node keys stored as a nested `Y.Map` so concurrent edits to DIFFERENT properties both survive.
+ *
+ * `mutateUpdateStyle` and friends record a whole-object `set-key`, so writing the object as one LWW
+ * value meant A's `color` and B's `padding` raced and one lost. Per-property merge fixes that
+ * without touching the op vocabulary: {@link yValueToJson} reassembles the whole object on the way
+ * out, so `JxDocOp`, the canvas patcher and the history ring keep seeing whole values.
+ *
+ * Declaration VALUES stay plain (a CSS value is never partially edited); only the key space is
+ * granular. Nesting recurses, which covers `style`'s media (`@--sm`) and pseudo (`&:hover`)
+ * blocks.
+ */
+export const GRANULAR_OBJECT_KEYS: ReadonlySet<string> = new Set(["style", "attributes", "$props"]);
+
+/**
+ * Rewrite a `Y.Text` to `next` with a minimal edit (common prefix/suffix trimmed).
+ *
+ * Minimal rather than replace-all for two reasons: the wire carries only the delta, and — the
+ * load-bearing one — the surviving characters keep their identity, so a concurrent remote insert
+ * inside the untouched region merges instead of being clobbered. Returns false when already equal.
+ */
+export function applyTextEdit(text: Y.Text, next: string): boolean {
+  const current = text.toString();
+  if (current === next) {
+    return false;
+  }
+  let start = 0;
+  const minLen = Math.min(current.length, next.length);
+  while (start < minLen && current[start] === next[start]) {
+    start += 1;
+  }
+  let endCurrent = current.length;
+  let endNext = next.length;
+  while (endCurrent > start && endNext > start && current[endCurrent - 1] === next[endNext - 1]) {
+    endCurrent -= 1;
+    endNext -= 1;
+  }
+  if (endCurrent > start) {
+    text.delete(start, endCurrent - start);
+  }
+  if (endNext > start) {
+    text.insert(start, next.slice(start, endNext));
+  }
+  return true;
+}
+
+/** A plain object becomes a Y.Map, recursing into nested objects; other values stay plain JSON. */
+export function toYObject(value: Record<string, unknown>): Y.Map<unknown> {
+  const map = new Y.Map<unknown>();
+  for (const [key, entry] of Object.entries(value)) {
+    if (entry === undefined) {
+      continue;
+    }
+    map.set(key, isPlainObject(entry) ? toYObject(entry) : cloneJson(entry));
+  }
+  return map;
+}
+
+/**
+ * Merge a plain object into an existing Y.Map per key: set changed keys, delete removed ones,
+ * recurse into nested maps. Whole-value replacement would mint a new Y.Map and discard a peer's
+ * concurrent edit to an untouched sibling property — the very thing granularity exists to prevent.
+ */
+export function mergeYObject(map: Y.Map<unknown>, value: Record<string, unknown>): void {
+  // Detached key list: deleting from a Y.Map while iterating its live keys is unsafe.
+  // oxlint-disable-next-line unicorn/no-useless-spread -- the copy is the point (mutation during iteration)
+  for (const key of [...map.keys()]) {
+    if (!(key in value) || value[key] === undefined) {
+      map.delete(key);
+    }
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    if (entry === undefined) {
+      continue;
+    }
+    const existing = map.get(key);
+    if (isPlainObject(entry)) {
+      if (existing instanceof Y.Map) {
+        mergeYObject(existing, entry);
+      } else {
+        map.set(key, toYObject(entry));
+      }
+    } else if (!deepEqualJson(existing, entry)) {
+      map.set(key, cloneJson(entry));
+    }
+  }
+}
+
+/** Structural equality over plain JSON, used to skip no-op key writes. */
+function deepEqualJson(a: unknown, b: unknown): boolean {
+  if (a === b) {
+    return true;
+  }
+  if (a instanceof Y.Map || a instanceof Y.Array || a instanceof Y.Text) {
+    return false;
+  }
+  return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+}
+
+/** A child value: a bare string becomes a Y.Text (per-character merge), a node becomes a Y.Map. */
+export function toYChild(child: unknown): unknown {
+  return typeof child === "string" ? new Y.Text(child) : toYNode(child);
+}
+
+/** A children array becomes a Y.Array of node Y.Maps and Y.Texts. */
 export function toYChildren(children: readonly unknown[]): Y.Array<unknown> {
   const arr = new Y.Array<unknown>();
   arr.insert(
     0,
-    children.map((child) => (typeof child === "string" ? child : toYNode(child))),
+    children.map((child) => toYChild(child)),
   );
   return arr;
 }
 
-/** A node object becomes a Y.Map; only its "children" key nests further Y types. */
+/**
+ * A node object becomes a Y.Map. Nesting is no longer limited to `children`: text keys become
+ * `Y.Text` and {@link GRANULAR_OBJECT_KEYS} become nested `Y.Map`s, so the CRDT merges at the
+ * granularity edits actually happen at. Everything else stays a whole-JSON LWW value.
+ */
 export function toYNode(node: unknown): Y.Map<unknown> {
   if (!isPlainObject(node)) {
     throw new TypeError("collab-schema: a document node must be a plain object");
@@ -77,6 +215,10 @@ export function toYNode(node: unknown): Y.Map<unknown> {
     }
     if (key === "children" && Array.isArray(value)) {
       map.set(key, toYChildren(value));
+    } else if (TEXT_KEYS.has(key) && typeof value === "string") {
+      map.set(key, new Y.Text(value));
+    } else if (GRANULAR_OBJECT_KEYS.has(key) && isPlainObject(value)) {
+      map.set(key, toYObject(value));
     } else {
       map.set(key, cloneJson(value));
     }
@@ -84,7 +226,7 @@ export function toYNode(node: unknown): Y.Map<unknown> {
   return map;
 }
 
-/** Convert any structure value (Y.Map node, Y.Array children, or plain leaf) back to JSON. */
+/** Convert any structure value (Y.Map, Y.Array, Y.Text, or plain leaf) back to JSON. */
 export function yValueToJson(value: unknown): unknown {
   if (value instanceof Y.Map) {
     const out: Record<string, unknown> = {};
@@ -96,6 +238,9 @@ export function yValueToJson(value: unknown): unknown {
   if (value instanceof Y.Array) {
     return value.toArray().map((entry) => yValueToJson(entry));
   }
+  if (value instanceof Y.Text) {
+    return value.toString();
+  }
   return value;
 }
 
@@ -132,28 +277,11 @@ export function resolveYPath(doc: Y.Doc, path: JxPath): unknown {
  */
 export function updateSourceText(doc: Y.Doc, next: string, origin?: unknown): boolean {
   const text = sourceText(doc);
-  const current = text.toString();
-  if (current === next) {
+  if (text.toString() === next) {
     return false;
   }
-  let start = 0;
-  const minLen = Math.min(current.length, next.length);
-  while (start < minLen && current[start] === next[start]) {
-    start += 1;
-  }
-  let endCurrent = current.length;
-  let endNext = next.length;
-  while (endCurrent > start && endNext > start && current[endCurrent - 1] === next[endNext - 1]) {
-    endCurrent -= 1;
-    endNext -= 1;
-  }
   doc.transact(() => {
-    if (endCurrent > start) {
-      text.delete(start, endCurrent - start);
-    }
-    if (endNext > start) {
-      text.insert(start, next.slice(start, endNext));
-    }
+    applyTextEdit(text, next);
   }, origin);
   return true;
 }