@jxsuite/collab 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# @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.
+
+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
+
+One `Y.Doc` per open file:
+
+| Root type            | Purpose                                                                                                                                     |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `source: Y.Text`     | **The authoritative file content.** Providers persist `getText("source").toString()` — nothing else.                                        |
+| `structure: Y.Map`   | The `JxMutableNode` tree, projected by Studio. Only `children` nests (`Y.Array`); every other key is a plain-JSON value merged whole (LWW). |
+| `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.
+
+**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 — never 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.
+
+## The wire envelope (`./envelope`)
+
+One WebSocket per project, multiplexing every open document (lib0 binary frames):
+
+```
+frame          := varUint frameType, body
+0 DOC_SYNC     := varString path, varUint docEpoch, varUint8Array y-protocols sync body
+1 AWARENESS    := varUint8Array y-protocols awareness update (project-scoped)
+2 DOC_CLOSE    := varString path
+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.
+
+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?, selection? }` — file-tree presence
+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 — destroy it and re-acquire.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@jxsuite/collab",
+  "version": "0.1.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": {
+    "type": "git",
+    "url": "git+https://github.com/jxsuite/jx.git",
+    "directory": "packages/collab"
+  },
+  "files": [
+    "src/"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./ops": "./src/ops.ts",
+    "./schema": "./src/schema.ts",
+    "./op-bridge": "./src/op-bridge.ts",
+    "./diff": "./src/diff.ts",
+    "./envelope": "./src/envelope.ts",
+    "./awareness-types": "./src/awareness-types.ts",
+    "./provider": "./src/provider.ts",
+    "./client": "./src/ws-client.ts",
+    "./room": "./src/ws-room.ts"
+  },
+  "publishConfig": {
+    "provenance": false
+  },
+  "scripts": {
+    "test": "bun test --isolate",
+    "test:coverage": "bun test --isolate --coverage"
+  },
+  "dependencies": {
+    "@jxsuite/schema": "workspace:^",
+    "lib0": "^0.2.99",
+    "y-protocols": "^1.0.6",
+    "yjs": "13.6.27"
+  }
+}

package/src/awareness-types.ts

@@ -0,0 +1,54 @@
+/**
+ * The project-level awareness contract. One y-protocols Awareness instance rides each provider
+ * connection (not one per document): every client publishes a single state describing who they are
+ * and where they're working, which gives file-tree presence for free; per-document cursor overlays
+ * filter the same states by focusedPath.
+ */
+
+import type { JxPath } from "@jxsuite/schema/types";
+
+export interface CollabUser {
+  login: string;
+  name?: string;
+  avatarUrl?: string;
+  /** Presence color, assigned deterministically by the server (hello) or colorForKey. */
+  color: string;
+}
+
+export interface CollabAwarenessState {
+  user: CollabUser;
+  /** Project-relative path of the document the client is focused on, or null. */
+  focusedPath: string | null;
+  /** Which representation the client is editing (drives the Phase-B canonical lock). */
+  mode?: "structure" | "source";
+  /** The client's structural selection in the focused document. */
+  selection?: JxPath | null;
+  /**
+   * Whether this client may write (from the server hello). Drives reconciler election — the lowest
+   * write-capable clientID mirrors derived representations. Advisory only: the server drops updates
+   * from read-only sockets regardless.
+   */
+  canWrite?: boolean;
+}
+
+/** Eight distinguishable presence hues (dark-theme friendly). */
+export const PRESENCE_PALETTE = [
+  "#4f9cf9",
+  "#e5484d",
+  "#30a46c",
+  "#f5a524",
+  "#8e4ec6",
+  "#00a2c7",
+  "#e93d82",
+  "#a8845c",
+] as const;
+
+/** Deterministic palette pick — the same key always maps to the same color. */
+export function colorForKey(key: string): string {
+  let hash = 5381;
+  for (let i = 0; i < key.length; i++) {
+    hash = Math.imul(hash, 33) + (key.codePointAt(i) ?? 0);
+  }
+  const index = Math.abs(hash) % PRESENCE_PALETTE.length;
+  return PRESENCE_PALETTE[index]!;
+}

package/src/diff.ts

@@ -0,0 +1,277 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+
+import type { JxMutableNode, JxPath } from "@jxsuite/schema/types";
+import type { JxDocOp } from "./ops.ts";
+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();
+}
+
+/**
+ * Hard-replace the structure tree with `document` (the diff-overflow escape hatch) and bump the
+ * in-doc canonicalRev so stale mirror writes computed against the old tree are discarded.
+ */
+export function replaceYStructure(doc: Y.Doc, document: JxMutableNode, origin: unknown): void {
+  doc.transact(() => {
+    const structure = structureMap(doc);
+    const next = document as Record<string, unknown>;
+    // Detached copy: keys are deleted while iterating.
+    const existingKeys = [...structure.keys()];
+    for (const key of existingKeys) {
+      if (!(key in next) || next[key] === undefined) {
+        structure.delete(key);
+      }
+    }
+    for (const [key, value] of Object.entries(next)) {
+      if (value === undefined) {
+        continue;
+      }
+      if (key === "children" && Array.isArray(value)) {
+        structure.set(key, toYChildren(value));
+      } else {
+        // oxlint-disable-next-line unicorn/prefer-structured-clone -- JSON normalization is the point
+        structure.set(key, JSON.parse(JSON.stringify(value)));
+      }
+    }
+    const meta = metaMap(doc);
+    meta.set("canonicalRev", Number(meta.get("canonicalRev") ?? 0) + 1);
+  }, origin);
+}

package/src/envelope.ts

@@ -0,0 +1,137 @@
+/**
+ * The binary wire envelope every Jx collab provider speaks: the Cloudflare platform DO, the
+ * devserver endpoint in the server package, and the browser client. One WebSocket per project
+ * carries every open document, multiplexed by path:
+ *
+ *     frame          := varUint frameType, body
+ *     0 DOC_SYNC     := varString path, varUint docEpoch, varUint8Array y-protocols sync body
+ *     1 AWARENESS    := varUint8Array y-protocols awareness update (project-scoped)
+ *     2 DOC_CLOSE    := varString path                (client → server unsubscribe)
+ *     3 CONTROL      := varString json                (see ControlMessage)
+ *
+ * `docEpoch` is the server-owned lifetime counter of a document's Y history. Out-of-band content
+ * replacement (git discard/pull/rename, non-collab writes) bumps it; frames carrying a stale epoch
+ * are dropped and answered with a `doc-reset` control message, upon which the client destroys its
+ * Y.Doc and re-opens. The invariant "Y history is never deleted or replaced without an epoch bump"
+ * is what prevents divergent-history duplicate-content merges.
+ */
+
+import * as decoding from "lib0/decoding";
+import * as encoding from "lib0/encoding";
+
+export const FRAME_DOC_SYNC = 0;
+export const FRAME_AWARENESS = 1;
+export const FRAME_DOC_CLOSE = 2;
+export const FRAME_CONTROL = 3;
+
+export type CollabPermission = "admin" | "write" | "read";
+
+/** JSON payloads of CONTROL frames. */
+export type ControlMessage =
+  /** Server → client on accept: the socket's identity and effective permission. */
+  | {
+      type: "hello";
+      login: string;
+      name?: string;
+      avatarUrl?: string;
+      color: string;
+      permission: CollabPermission;
+    }
+  /** Client → server: subscribe to a document (the client's Y.Doc must start EMPTY). */
+  | { type: "open"; path: string }
+  /** Server → client: the room is ready at this epoch; sync follows. */
+  | { type: "opened"; path: string; epoch: number }
+  /** Server → client: the doc's history was replaced; destroy the local Y.Doc and re-open. */
+  | { type: "doc-reset"; path: string; epoch: number }
+  /** Client → server: persist this doc to durable storage now (Cmd+S). */
+  | { type: "flush"; path: string }
+  /** Server → client: the flush landed. */
+  | { type: "flush-ack"; path: string }
+  /**
+   * Server → client: a request was refused (codes: read-only, content-not-loaded, too-large,
+   * rate-limited, binary-file, unknown-frame).
+   */
+  | { type: "error"; path?: string; code: string; message: string };
+
+export type CollabFrame =
+  | { type: "doc-sync"; path: string; epoch: number; body: Uint8Array }
+  | { type: "awareness"; body: Uint8Array }
+  | { type: "doc-close"; path: string }
+  | { type: "control"; message: ControlMessage };
+
+export class EnvelopeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "EnvelopeError";
+  }
+}
+
+export function encodeFrame(frame: CollabFrame): Uint8Array {
+  const encoder = encoding.createEncoder();
+  switch (frame.type) {
+    case "doc-sync": {
+      encoding.writeVarUint(encoder, FRAME_DOC_SYNC);
+      encoding.writeVarString(encoder, frame.path);
+      encoding.writeVarUint(encoder, frame.epoch);
+      encoding.writeVarUint8Array(encoder, frame.body);
+      break;
+    }
+    case "awareness": {
+      encoding.writeVarUint(encoder, FRAME_AWARENESS);
+      encoding.writeVarUint8Array(encoder, frame.body);
+      break;
+    }
+    case "doc-close": {
+      encoding.writeVarUint(encoder, FRAME_DOC_CLOSE);
+      encoding.writeVarString(encoder, frame.path);
+      break;
+    }
+    case "control": {
+      encoding.writeVarUint(encoder, FRAME_CONTROL);
+      encoding.writeVarString(encoder, JSON.stringify(frame.message));
+      break;
+    }
+    default: {
+      throw new EnvelopeError(`unknown-frame:${(frame as CollabFrame).type}`);
+    }
+  }
+  return encoding.toUint8Array(encoder);
+}
+
+export function decodeFrame(data: Uint8Array): CollabFrame {
+  try {
+    const decoder = decoding.createDecoder(data);
+    const frameType = decoding.readVarUint(decoder);
+    switch (frameType) {
+      case FRAME_DOC_SYNC: {
+        const path = decoding.readVarString(decoder);
+        const epoch = decoding.readVarUint(decoder);
+        const body = decoding.readVarUint8Array(decoder);
+        return { body, epoch, path, type: "doc-sync" };
+      }
+      case FRAME_AWARENESS: {
+        return { body: decoding.readVarUint8Array(decoder), type: "awareness" };
+      }
+      case FRAME_DOC_CLOSE: {
+        return { path: decoding.readVarString(decoder), type: "doc-close" };
+      }
+      case FRAME_CONTROL: {
+        const message = JSON.parse(decoding.readVarString(decoder)) as ControlMessage;
+        if (typeof message !== "object" || typeof message.type !== "string") {
+          throw new EnvelopeError("malformed-control");
+        }
+        return { message, type: "control" };
+      }
+      default: {
+        throw new EnvelopeError(`unknown-frame-type:${frameType}`);
+      }
+    }
+  } catch (error) {
+    if (error instanceof EnvelopeError) {
+      throw error;
+    }
+    throw new EnvelopeError(
+      `malformed-frame: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+export type { JxDocOp, JxDocOpPair } from "./ops.ts";
+export { applyDocOpToDoc, childArray, cloneValue, getNodeAtPath } from "./ops.ts";
+export {
+  COLLAB_SCHEMA_VERSION,
+  FRONTMATTER_KEY,
+  frontmatterMap,
+  META_KEY,
+  metaMap,
+  resolveYPath,
+  seedStructure,
+  SOURCE_KEY,
+  sourceText,
+  STRUCTURE_KEY,
+  structureMap,
+  toYChildren,
+  toYNode,
+  updateSourceText,
+  yDocToJson,
+  yValueToJson,
+} from "./schema.ts";
+// Re-exported so consumers keep a single yjs import point (avoids dual-instance hazards).
+export { Doc as YDoc, UndoManager } from "yjs";
+export {
+  applyDocOpsToY,
+  CollabPathError,
+  LOCAL_ORIGIN,
+  MIRROR_ORIGIN,
+  SEED_ORIGIN,
+  yEventsToDocOps,
+} from "./op-bridge.ts";
+export { deepEqual, diffDocs, replaceYStructure } from "./diff.ts";
+export type { DiffOptions } from "./diff.ts";
+export {
+  decodeFrame,
+  encodeFrame,
+  EnvelopeError,
+  FRAME_AWARENESS,
+  FRAME_CONTROL,
+  FRAME_DOC_CLOSE,
+  FRAME_DOC_SYNC,
+} from "./envelope.ts";
+export type { CollabFrame, CollabPermission, ControlMessage } from "./envelope.ts";
+export { colorForKey, PRESENCE_PALETTE } from "./awareness-types.ts";
+export type { CollabAwarenessState, CollabUser } from "./awareness-types.ts";
+export type { CollabCapability, CollabHandle, CollabIdentity, CollabStatus } from "./provider.ts";