@jxsuite/collab 0.1.0

package/src/op-bridge.ts

@@ -0,0 +1,218 @@
+/**
+ * The two-way bridge between Studio's JxDocOp op-log and the shared Y.Doc structure tree.
+ *
+ * Outbound ({@link applyDocOpsToY}): forward ops recorded by a local transaction replay onto the Y
+ * tree inside one Y transaction tagged with the caller's origin, so observers can tell local
+ * mirroring from remote edits.
+ *
+ * Inbound ({@link yEventsToDocOps}): a remote transaction's Y events convert back into JxDocOps for
+ * `applyExternalDocOps`. Only provably safe event shapes take this fast path (it keeps canvas
+ * patches surgical); anything gnarlier returns null and the caller reconciles by diffing — the
+ * correctness anchor.
+ */
+
+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";
+
+/** Origin of Y transactions produced by mirroring the local tab's ops. */
+export const LOCAL_ORIGIN = "jx-local";
+/** Origin of derived-representation writes (the elected reconciler's structure↔source mirrors). */
+export const MIRROR_ORIGIN = "jx-mirror";
+/** Origin of seeding/bootstrap writes. */
+export const SEED_ORIGIN = "jx-seed";
+
+/** Thrown when an op's path does not resolve in the Y tree; callers fall back to diffing. */
+export class CollabPathError extends Error {
+  constructor(path: JxPath) {
+    super(`collab-path-unresolved:${path.join("/")}`);
+    this.name = "CollabPathError";
+  }
+}
+
+function requireNode(doc: Y.Doc, path: JxPath): Y.Map<unknown> {
+  const target = resolveYPath(doc, path);
+  if (!(target instanceof Y.Map)) {
+    throw new CollabPathError(path);
+  }
+  return target;
+}
+
+function childrenOf(doc: Y.Doc, parentPath: JxPath, create: boolean): Y.Array<unknown> {
+  const parent = requireNode(doc, parentPath);
+  const children = parent.get("children");
+  if (children instanceof Y.Array) {
+    return children;
+  }
+  if (create && children === undefined) {
+    const fresh = new Y.Array<unknown>();
+    parent.set("children", fresh);
+    return fresh;
+  }
+  throw new CollabPathError([...parentPath, "children"]);
+}
+
+/** JSON round-trip clone (matches the ops applier's normalization). */
+function cloneJson<T>(value: T): T {
+  // oxlint-disable-next-line unicorn/prefer-structured-clone -- JSON normalization is the point
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+function toYChild(node: unknown): unknown {
+  return typeof node === "string" ? node : toYNode(node);
+}
+
+function applyOneOp(doc: Y.Doc, op: JxDocOp): void {
+  switch (op.op) {
+    case "set-key": {
+      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));
+      }
+      return;
+    }
+    case "insert-child": {
+      const children = childrenOf(doc, op.parentPath, true);
+      if (op.index < 0 || op.index > children.length) {
+        throw new CollabPathError([...op.parentPath, "children", op.index]);
+      }
+      children.insert(op.index, [toYChild(op.node)]);
+      return;
+    }
+    case "remove-child": {
+      const children = childrenOf(doc, op.parentPath, false);
+      if (op.index < 0 || op.index >= children.length) {
+        throw new CollabPathError([...op.parentPath, "children", op.index]);
+      }
+      children.delete(op.index, 1);
+      return;
+    }
+    case "set-child": {
+      const children = childrenOf(doc, op.parentPath, false);
+      if (op.index < 0 || op.index >= children.length) {
+        throw new CollabPathError([...op.parentPath, "children", op.index]);
+      }
+      children.delete(op.index, 1);
+      children.insert(op.index, [toYChild(op.node)]);
+      return;
+    }
+    case "move-child": {
+      // Y.Array has no native move: re-insert the node's current JSON at the target. A remote
+      // Edit landing inside the moved subtree during the same round-trip is lost (documented v1
+      // Limitation); convergence itself is unaffected. Both parent paths resolve BEFORE the
+      // Removal splice — matching the plain applier's semantics — while toIndex is expressed in
+      // Post-removal coordinates (the mutators pre-adjust same-parent moves).
+      const from = childrenOf(doc, op.fromParentPath, false);
+      const to = childrenOf(doc, op.toParentPath, true);
+      if (op.fromIndex < 0 || op.fromIndex >= from.length) {
+        throw new CollabPathError([...op.fromParentPath, "children", op.fromIndex]);
+      }
+      const json = yValueToJson(from.get(op.fromIndex));
+      from.delete(op.fromIndex, 1);
+      if (op.toIndex < 0 || op.toIndex > to.length) {
+        throw new CollabPathError([...op.toParentPath, "children", op.toIndex]);
+      }
+      to.insert(op.toIndex, [toYChild(json)]);
+      return;
+    }
+    default: {
+      throw new Error(`unknown-doc-op:${(op as JxDocOp).op}`);
+    }
+  }
+}
+
+/**
+ * Replay forward ops onto the Y structure tree in one transaction. Throws {@link CollabPathError}
+ * when any op's path does not resolve — the transaction still commits the ops applied before the
+ * failure, so callers catching it must reconcile by diff (which corrects any partial state).
+ */
+export function applyDocOpsToY(doc: Y.Doc, ops: readonly JxDocOp[], origin: unknown): void {
+  doc.transact(() => {
+    for (const op of ops) {
+      applyOneOp(doc, op);
+    }
+  }, origin);
+}
+
+function isStructurePath(segments: readonly (string | number)[]): segments is JxPath {
+  return segments.every((seg) => typeof seg === "string" || typeof seg === "number");
+}
+
+/**
+ * Convert a remote transaction's deep events on the structure tree into JxDocOps (positions valid
+ * at sequential apply time). Returns null when the shape is not provably safe to convert — multiple
+ * overlapping events, more than one array event, or non-contiguous delete runs — and the caller
+ * must reconcile by diffing instead.
+ */
+export function yEventsToDocOps(events: readonly Y.YEvent<never>[]): JxDocOp[] | null {
+  if (events.length === 0) {
+    return [];
+  }
+  const paths = events.map((event) => event.path);
+  if (!paths.every((p) => isStructurePath(p))) {
+    return null;
+  }
+  // Overlap guard: one event's target must not sit inside another's subtree — later paths would
+  // Describe positions the earlier splice already shifted.
+  for (let i = 0; i < paths.length; i++) {
+    for (let j = 0; j < paths.length; j++) {
+      if (i === j) {
+        continue;
+      }
+      const a = paths[i]!;
+      const b = paths[j]!;
+      if (a.length <= b.length && a.every((seg, k) => seg === b[k])) {
+        return null;
+      }
+    }
+  }
+  const arrayEvents = events.filter((event) => event instanceof Y.YArrayEvent).length;
+  if (arrayEvents > 1) {
+    return null;
+  }
+
+  const ops: JxDocOp[] = [];
+  for (const event of events) {
+    const path = event.path as JxPath;
+    if (event instanceof Y.YMapEvent) {
+      const target = event.target as Y.Map<unknown>;
+      for (const [key, change] of event.changes.keys) {
+        if (change.action === "delete") {
+          ops.push({ key, op: "set-key", path });
+        } else {
+          ops.push({ key, op: "set-key", path, value: yValueToJson(target.get(key)) });
+        }
+      }
+    } else if (event instanceof Y.YArrayEvent) {
+      // The array event's path points at the children array; ops address its parent node.
+      if (path.at(-1) !== "children") {
+        return null;
+      }
+      const parentPath = path.slice(0, -1);
+      let index = 0;
+      for (const delta of event.changes.delta) {
+        if (delta.retain !== undefined) {
+          index += delta.retain;
+        } else if (delta.delete !== undefined) {
+          for (let i = 0; i < delta.delete; i++) {
+            ops.push({ index, op: "remove-child", parentPath });
+          }
+        } else if (delta.insert !== undefined) {
+          const items = Array.isArray(delta.insert) ? delta.insert : [delta.insert];
+          for (const item of items) {
+            ops.push({ index, node: yValueToJson(item), op: "insert-child", parentPath });
+            index += 1;
+          }
+        }
+      }
+    } else {
+      return null;
+    }
+  }
+  return ops;
+}

package/src/ops.ts

@@ -0,0 +1,128 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+
+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}`);
+    }
+  }
+}

package/src/provider.ts

@@ -0,0 +1,45 @@
+/**
+ * Provider contract types — what `StudioPlatform.collab?.(docPath)` resolves to. Type-only on
+ * purpose: Studio's base bundle imports this without pulling yjs in; the runtime lives behind a
+ * dynamic import of the concrete provider.
+ */
+
+import type { Awareness } from "y-protocols/awareness";
+import type * as Y from "yjs";
+import type { CollabPermission } from "./envelope.ts";
+
+export type CollabStatus = "connecting" | "connected" | "offline";
+
+export interface CollabIdentity {
+  login: string;
+  name?: string;
+  avatarUrl?: string;
+  color: string;
+  permission: CollabPermission;
+}
+
+/**
+ * A live co-editing session for one document. The Y.Doc starts EMPTY and fills from the provider
+ * (server-seeded source; client-derived structure) — never seed it locally before whenSynced.
+ */
+export interface CollabHandle {
+  doc: Y.Doc;
+  /** The connection's shared project-level awareness (one instance across all open docs). */
+  awareness: Awareness;
+  /** Resolves after the initial sync handshake completes for this doc. */
+  whenSynced: Promise<void>;
+  /** Identity issued by the server's hello; null until the connection greeted. */
+  identity: () => CollabIdentity | null;
+  /** Ask the provider to persist this doc to durable storage now (Cmd+S). */
+  flush: () => Promise<void>;
+  /** Connection status changes (shared per connection). Returns an unsubscribe. */
+  onStatus: (cb: (status: CollabStatus) => void) => () => void;
+  /**
+   * The server reset this doc's history (epoch bump after discard/pull/external write). The handle
+   * is dead: destroy it and re-acquire a fresh one via platform.collab.
+   */
+  onReset: (cb: () => void) => () => void;
+  destroy: () => void;
+}
+
+export type CollabCapability = (docPath: string) => Promise<CollabHandle | null>;

package/src/schema.ts

@@ -0,0 +1,205 @@
+/**
+ * The shared Y.Doc schema for a Jx document, and the JSON ↔ Y mapping.
+ *
+ * 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
+ * `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.
+ *
+ * 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
+ * array inserts, which would duplicate.
+ */
+
+import * as Y from "yjs";
+import type { JxMutableNode, JxPath } from "@jxsuite/schema/types";
+
+export const META_KEY = "meta";
+export const FRONTMATTER_KEY = "frontmatter";
+export const STRUCTURE_KEY = "structure";
+export const SOURCE_KEY = "source";
+
+export const COLLAB_SCHEMA_VERSION = 1;
+
+export function metaMap(doc: Y.Doc): Y.Map<unknown> {
+  return doc.getMap(META_KEY);
+}
+
+export function frontmatterMap(doc: Y.Doc): Y.Map<unknown> {
+  return doc.getMap(FRONTMATTER_KEY);
+}
+
+export function structureMap(doc: Y.Doc): Y.Map<unknown> {
+  return doc.getMap(STRUCTURE_KEY);
+}
+
+export function sourceText(doc: Y.Doc): Y.Text {
+  return doc.getText(SOURCE_KEY);
+}
+
+/** JSON round-trip clone (normalizes away proxies/undefined; matches the ops applier). */
+function cloneJson<T>(value: T): T {
+  // oxlint-disable-next-line unicorn/prefer-structured-clone -- JSON normalization is the point
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+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. */
+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))),
+  );
+  return arr;
+}
+
+/** A node object becomes a Y.Map; only its "children" key nests further Y types. */
+export function toYNode(node: unknown): Y.Map<unknown> {
+  if (!isPlainObject(node)) {
+    throw new TypeError("collab-schema: a document node must be a plain object");
+  }
+  const map = new Y.Map<unknown>();
+  for (const [key, value] of Object.entries(node)) {
+    if (value === undefined) {
+      continue;
+    }
+    if (key === "children" && Array.isArray(value)) {
+      map.set(key, toYChildren(value));
+    } else {
+      map.set(key, cloneJson(value));
+    }
+  }
+  return map;
+}
+
+/** Convert any structure value (Y.Map node, Y.Array children, or plain leaf) back to JSON. */
+export function yValueToJson(value: unknown): unknown {
+  if (value instanceof Y.Map) {
+    const out: Record<string, unknown> = {};
+    for (const [key, entry] of value.entries()) {
+      out[key] = yValueToJson(entry);
+    }
+    return out;
+  }
+  if (value instanceof Y.Array) {
+    return value.toArray().map((entry) => yValueToJson(entry));
+  }
+  return value;
+}
+
+/** The whole structure tree as a plain document (deep, detached copy). */
+export function yDocToJson(doc: Y.Doc): JxMutableNode {
+  return yValueToJson(structureMap(doc)) as JxMutableNode;
+}
+
+/**
+ * Resolve a JxPath against the structure tree. Returns the Y value at the path (a node Y.Map, a
+ * children Y.Array, a string child, or a plain leaf) or undefined when any segment is missing.
+ */
+export function resolveYPath(doc: Y.Doc, path: JxPath): unknown {
+  let current: unknown = structureMap(doc);
+  for (const segment of path) {
+    if (current instanceof Y.Map) {
+      current = current.get(String(segment));
+    } else if (current instanceof Y.Array) {
+      const index = typeof segment === "number" ? segment : Number(segment);
+      if (!Number.isInteger(index) || index < 0 || index >= current.length) {
+        return undefined;
+      }
+      current = current.get(index);
+    } else {
+      return undefined;
+    }
+  }
+  return current;
+}
+
+/**
+ * Update the source Y.Text to `next` with a minimal edit (common prefix/suffix trimmed), so mirror
+ * refreshes don't ship the whole document over the wire. Returns false when already identical.
+ */
+export function updateSourceText(doc: Y.Doc, next: string, origin?: unknown): boolean {
+  const text = sourceText(doc);
+  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;
+  }
+  doc.transact(() => {
+    if (endCurrent > start) {
+      text.delete(start, endCurrent - start);
+    }
+    if (endNext > start) {
+      text.insert(start, next.slice(start, endNext));
+    }
+  }, origin);
+  return true;
+}
+
+/**
+ * Populate the structure tree (and frontmatter/meta) from a parsed document — the client-side
+ * first-sync step. Safe under concurrent seeders: every write is a whole-key Y.Map set, so two
+ * racing seeds converge to one seeder's subtrees via per-key LWW with no duplication. No-op when
+ * another seeder already won.
+ */
+export function seedStructure(
+  doc: Y.Doc,
+  document: JxMutableNode,
+  opts: {
+    frontmatter?: Record<string, unknown>;
+    sourceFormat?: string | null;
+    origin?: unknown;
+  } = {},
+): boolean {
+  const meta = metaMap(doc);
+  if (meta.get("structureSeeded") === true) {
+    return false;
+  }
+  doc.transact(() => {
+    const structure = structureMap(doc);
+    for (const [key, value] of Object.entries(document)) {
+      if (value === undefined) {
+        continue;
+      }
+      if (key === "children" && Array.isArray(value)) {
+        structure.set(key, toYChildren(value));
+      } else {
+        structure.set(key, cloneJson(value));
+      }
+    }
+    const frontmatter = frontmatterMap(doc);
+    for (const [key, value] of Object.entries(opts.frontmatter ?? {})) {
+      if (value !== undefined) {
+        frontmatter.set(key, cloneJson(value));
+      }
+    }
+    meta.set("schemaVersion", COLLAB_SCHEMA_VERSION);
+    meta.set("canonical", "structure");
+    meta.set("canonicalRev", 0);
+    meta.set("sourceFormat", opts.sourceFormat ?? null);
+    meta.set("structureSeeded", true);
+  }, opts.origin);
+  return true;
+}