@matrajs/collab 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nahim Hossain Shohan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# @matrajs/collab
+
+Collaborative editing for Matra. No CRDT, no dependency — the engine can
+already rebase a step over someone else's edit, so this is a version counter
+and a transport on top of that.
+
+```bash
+npm i @matrajs/core @matrajs/collab
+```
+
+```ts
+import { collab, sendableSteps, getVersion } from '@matrajs/collab'
+
+const editor = createEditor({
+  extensions: [...starterKit, collab({ clientId })],
+  content,
+})
+
+// Send what we have; the authority accepts only if we are current.
+const sendable = sendableSteps(editor)
+if (sendable) {
+  const accepted = await post(sendable)
+  if (accepted) editor.commands.confirmCollabSteps(sendable.steps.length)
+}
+
+// Pull what we missed. Local work is rewound, remote steps applied, then local
+// work replayed on top — so unsent edits survive someone else's.
+editor.commands.receiveCollabSteps(await since(getVersion(editor)))
+```
+
+`Authority` is the server half, deliberately transport-free so the same object
+works over WebSocket, HTTP polling, or an in-memory channel in a test.
+
+`PresenceTracker` keeps other people's cursors inside the document as it
+changes. Rendering them is the host's job — the engine has no decoration layer,
+and inventing one here would be the wrong place for it.
+
+- Source: https://github.com/amrelaco/matra
+
+MIT.

package/dist/index.cjs

@@ -0,0 +1,198 @@
+'use strict';
+
+// src/authority.ts
+var Authority = class {
+  constructor(onChange) {
+    this.onChange = onChange;
+  }
+  onChange;
+  history = [];
+  get version() {
+    return this.history.length;
+  }
+  /**
+   * Append steps if the client is current.
+   *
+   * Returns false when it is not — the client should pull what it missed,
+   * rebase, and try again. Rejecting rather than merging is what keeps the
+   * history linear and every client's version meaningful.
+   */
+  receive(version, steps) {
+    if (version !== this.version) return false;
+    this.history.push(...steps);
+    this.onChange?.(this.version);
+    return true;
+  }
+  /** Everything that happened after `version`. */
+  since(version) {
+    return this.history.slice(version);
+  }
+};
+
+// src/collab.ts
+var REMOTE = "collab:remote";
+var CONFIRM = "collab:confirm";
+var REBASED = "collab:rebased";
+function collab(options) {
+  const clientId = options.clientId;
+  if (!clientId) throw new Error("Matra: collab needs a clientId");
+  return {
+    kind: "extension",
+    name: "collab",
+    state: {
+      init: () => ({ version: options.version ?? 0, unconfirmed: [] }),
+      apply: (ctx, previous) => {
+        const engine = readEngine(ctx);
+        const tr = engine.tr;
+        const confirmed = tr.getMeta(CONFIRM);
+        if (typeof confirmed === "number") {
+          return {
+            version: previous.version + confirmed,
+            unconfirmed: previous.unconfirmed.slice(confirmed)
+          };
+        }
+        const rebased = tr.getMeta(REBASED);
+        if (rebased) {
+          return {
+            version: previous.version + rebased.remote,
+            unconfirmed: rebased.unconfirmed
+          };
+        }
+        if (!tr.steps.length) return previous;
+        if (tr.getMeta(REMOTE)) return previous;
+        const pending = tr.steps.map((step, index) => ({
+          step,
+          inverted: step.invert(tr.docs[index]),
+          json: step.toJSON(),
+          clientId
+        }));
+        return {
+          version: previous.version,
+          unconfirmed: [...previous.unconfirmed, ...pending]
+        };
+      }
+    },
+    commands: {
+      /**
+       * Apply steps from other clients.
+       *
+       * Steps this client sent are skipped — they are already in the document,
+       * and applying them twice would duplicate the edit. A step that no longer
+       * applies is dropped rather than throwing: one bad message from a peer
+       * must not take the editor down.
+       */
+      receiveCollabSteps: (ctx, incoming) => {
+        if (!incoming?.length) return false;
+        const engine = readEngine(ctx);
+        const foreign = incoming.filter((entry) => entry.clientId !== clientId);
+        if (!foreign.length) return false;
+        const pending = engine.pluginState("collab")?.unconfirmed ?? [];
+        const tr = engine.tr;
+        for (let i = pending.length - 1; i >= 0; i--) {
+          tr.maybeStep(pending[i]?.inverted);
+        }
+        const beforeRemote = tr.steps.length;
+        let applied = 0;
+        for (const entry of foreign) {
+          const step = engine.stepFromJSON(entry.step);
+          if (step && tr.maybeStep(step)) applied++;
+        }
+        if (!applied) return false;
+        const remoteMapping = tr.mapping.slice(beforeRemote);
+        const rebased = [];
+        for (const entry of pending) {
+          const mapped = entry.step.map(remoteMapping);
+          if (!mapped) continue;
+          const docBefore = tr.doc;
+          if (!tr.maybeStep(mapped)) continue;
+          rebased.push({
+            step: mapped,
+            inverted: mapped.invert(docBefore),
+            json: mapped.toJSON(),
+            clientId
+          });
+        }
+        tr.setMeta(REBASED, { remote: applied, unconfirmed: rebased });
+        return true;
+      },
+      /** The authority accepted this many of our steps; stop tracking them. */
+      confirmCollabSteps: (ctx, count) => {
+        if (!Number.isInteger(count) || count <= 0) return false;
+        readEngine(ctx).tr.setMeta(CONFIRM, count);
+        return true;
+      }
+    }
+  };
+}
+function sendableSteps(editor) {
+  const state = editor.extensionState("collab");
+  if (!state?.unconfirmed.length) return null;
+  return {
+    version: state.version,
+    steps: state.unconfirmed.map((entry) => ({ step: entry.json, clientId: entry.clientId })),
+    clientId: state.unconfirmed[0]?.clientId ?? ""
+  };
+}
+function getVersion(editor) {
+  return editor.extensionState("collab")?.version ?? 0;
+}
+function readEngine(ctx) {
+  const access = ctx[/* @__PURE__ */ Symbol.for("matra.engine")];
+  if (!access) throw new Error("Matra: collab ctx was created outside the engine");
+  return access;
+}
+
+// src/presence.ts
+var PresenceTracker = class {
+  constructor(editor, onUpdate) {
+    this.editor = editor;
+    this.onUpdate = onUpdate;
+    editor.getJSON();
+    this.off = editor.on("change", () => {
+      const size = measure(editor.getJSON());
+      for (const [id, person] of this.people) {
+        this.people.set(id, {
+          ...person,
+          anchor: Math.min(person.anchor, size),
+          head: Math.min(person.head, size)
+        });
+      }
+      editor.getJSON();
+      this.onUpdate?.(this.list());
+    });
+  }
+  editor;
+  onUpdate;
+  people = /* @__PURE__ */ new Map();
+  off;
+  set(person) {
+    this.people.set(person.clientId, person);
+    this.onUpdate?.(this.list());
+  }
+  remove(clientId) {
+    if (this.people.delete(clientId)) this.onUpdate?.(this.list());
+  }
+  list() {
+    return [...this.people.values()];
+  }
+  destroy() {
+    this.off();
+    this.people.clear();
+  }
+};
+function measure(doc) {
+  if (typeof doc.text === "string") return doc.text.length;
+  let size = 0;
+  for (const child of doc.content ?? []) {
+    size += typeof child.text === "string" ? child.text.length : measure(child) + 2;
+  }
+  return size;
+}
+
+exports.Authority = Authority;
+exports.PresenceTracker = PresenceTracker;
+exports.collab = collab;
+exports.getVersion = getVersion;
+exports.sendableSteps = sendableSteps;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/authority.ts","../src/collab.ts","../src/presence.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["import type { CollabStep } from './types'\n\n/**\n * The server side of the protocol, as a plain object.\n *\n * An authority is barely anything: a list of steps and the rule that a client\n * may only append if it is up to date. Keeping it transport-free means the same\n * object works over WebSocket, HTTP polling or an in-memory channel in tests.\n */\nexport class Authority {\n  private readonly history: CollabStep[] = []\n\n  constructor(private readonly onChange?: (version: number) => void) {}\n\n  get version(): number {\n    return this.history.length\n  }\n\n  /**\n   * Append steps if the client is current.\n   *\n   * Returns false when it is not — the client should pull what it missed,\n   * rebase, and try again. Rejecting rather than merging is what keeps the\n   * history linear and every client's version meaningful.\n   */\n  receive(version: number, steps: CollabStep[]): boolean {\n    if (version !== this.version) return false\n    this.history.push(...steps)\n    this.onChange?.(this.version)\n    return true\n  }\n\n  /** Everything that happened after `version`. */\n  since(version: number): CollabStep[] {\n    return this.history.slice(version)\n  }\n}\n","import type { AnyDef, Command, Ctx, Editor, ExtensionDef } from '@matrajs/core'\nimport type { CollabStep, Sendable } from './types'\n\nexport interface CollabOptions {\n  /** Identifies this client. Two clients must never share one. */\n  clientId: string\n  /** The version this client starts from. */\n  version?: number\n}\n\n/** A local step, kept with what it takes to rewind and rebase it. */\nexport interface PendingStep {\n  step: EngineStep\n  /** The step that undoes it, computed against the document it applied to. */\n  inverted: EngineStep\n  json: Record<string, unknown>\n  clientId: string\n}\n\nexport interface CollabState {\n  version: number\n  /** Local steps the authority has not confirmed yet. */\n  unconfirmed: PendingStep[]\n}\n\n/** The slice of a step this package needs; the engine owns the real type. */\ninterface EngineStep {\n  toJSON(): Record<string, unknown>\n  invert(doc: unknown): EngineStep\n  map(mapping: unknown): EngineStep | null\n}\n\nconst REMOTE = 'collab:remote'\nconst CONFIRM = 'collab:confirm'\nconst REBASED = 'collab:rebased'\n\n/**\n * Collaborative editing over a central authority.\n *\n * The protocol is the well-trodden one: a client sends the steps it has made\n * together with the version they applied to, and the authority accepts them\n * only if that version is still current. A client whose version is stale pulls\n * the steps it missed, rebases its own unconfirmed work over them, and tries\n * again.\n *\n * There is no CRDT here and no dependency. Rebasing already lives in the engine\n * — `Step.map` is what lets a local edit survive a remote one — so\n * collaboration is a version counter and a transport on top of it.\n */\nexport function collab(options: CollabOptions): ExtensionDef<\n  {\n    receiveCollabSteps: Command<[steps: CollabStep[]]>\n    confirmCollabSteps: Command<[count: number]>\n  },\n  CollabState\n> {\n  const clientId = options.clientId\n  if (!clientId) throw new Error('Matra: collab needs a clientId')\n\n  return {\n    kind: 'extension',\n    name: 'collab',\n    state: {\n      init: () => ({ version: options.version ?? 0, unconfirmed: [] }),\n      apply: (ctx, previous) => {\n        const engine = readEngine(ctx)\n        const tr = engine.tr\n\n        const confirmed = tr.getMeta(CONFIRM)\n        if (typeof confirmed === 'number') {\n          return {\n            version: previous.version + confirmed,\n            unconfirmed: previous.unconfirmed.slice(confirmed),\n          }\n        }\n\n        const rebased = tr.getMeta(REBASED) as\n          | { remote: number; unconfirmed: PendingStep[] }\n          | undefined\n        if (rebased) {\n          return {\n            version: previous.version + rebased.remote,\n            unconfirmed: rebased.unconfirmed,\n          }\n        }\n\n        if (!tr.steps.length) return previous\n        if (tr.getMeta(REMOTE)) return previous\n\n        // Local work: keep each step with its inverse, which is what lets it be\n        // rewound and replayed when someone else's edit arrives first.\n        const pending: PendingStep[] = tr.steps.map((step, index) => ({\n          step,\n          inverted: step.invert(tr.docs[index]),\n          json: step.toJSON(),\n          clientId,\n        }))\n        return {\n          version: previous.version,\n          unconfirmed: [...previous.unconfirmed, ...pending],\n        }\n      },\n    },\n    commands: {\n      /**\n       * Apply steps from other clients.\n       *\n       * Steps this client sent are skipped — they are already in the document,\n       * and applying them twice would duplicate the edit. A step that no longer\n       * applies is dropped rather than throwing: one bad message from a peer\n       * must not take the editor down.\n       */\n      receiveCollabSteps: (ctx, incoming) => {\n        if (!incoming?.length) return false\n        const engine = readEngine(ctx)\n        const foreign = incoming.filter((entry) => entry.clientId !== clientId)\n        if (!foreign.length) return false\n\n        const pending =\n          (engine.pluginState('collab') as CollabState | undefined)?.unconfirmed ?? []\n        const tr = engine.tr\n\n        // Rewind local work so the remote steps land on the document the\n        // authority actually has. Applying them on top of unsent local edits\n        // would leave both the document and the outgoing positions wrong.\n        for (let i = pending.length - 1; i >= 0; i--) {\n          tr.maybeStep(pending[i]?.inverted as never)\n        }\n\n        const beforeRemote = tr.steps.length\n        let applied = 0\n        for (const entry of foreign) {\n          const step = engine.stepFromJSON(entry.step)\n          if (step && tr.maybeStep(step)) applied++\n        }\n        if (!applied) return false\n\n        // Replay local work over the remote changes.\n        const remoteMapping = tr.mapping.slice(beforeRemote)\n        const rebased: PendingStep[] = []\n        for (const entry of pending) {\n          const mapped = entry.step.map(remoteMapping)\n          if (!mapped) continue\n          const docBefore = tr.doc\n          if (!tr.maybeStep(mapped as never)) continue\n          rebased.push({\n            step: mapped,\n            inverted: mapped.invert(docBefore),\n            json: mapped.toJSON(),\n            clientId,\n          })\n        }\n\n        tr.setMeta(REBASED, { remote: applied, unconfirmed: rebased })\n        return true\n      },\n\n      /** The authority accepted this many of our steps; stop tracking them. */\n      confirmCollabSteps: (ctx, count) => {\n        if (!Number.isInteger(count) || count <= 0) return false\n        readEngine(ctx).tr.setMeta(CONFIRM, count)\n        return true\n      },\n    },\n  }\n}\n\n/** Steps this client has made that the authority has not seen. */\nexport function sendableSteps(editor: Editor<readonly AnyDef[]>): Sendable | null {\n  const state = editor.extensionState<CollabState>('collab')\n  if (!state?.unconfirmed.length) return null\n  return {\n    version: state.version,\n    steps: state.unconfirmed.map((entry) => ({ step: entry.json, clientId: entry.clientId })),\n    clientId: state.unconfirmed[0]?.clientId ?? '',\n  }\n}\n\n/** The version of the document this client believes it is on. */\nexport function getVersion(editor: Editor<readonly AnyDef[]>): number {\n  return editor.extensionState<CollabState>('collab')?.version ?? 0\n}\n\ninterface CollabEngine {\n  tr: {\n    steps: EngineStep[]\n    docs: unknown[]\n    doc: unknown\n    mapping: { slice(from: number): unknown }\n    getMeta(key: string): unknown\n    setMeta(key: string, value: unknown): unknown\n    maybeStep(step: unknown): boolean\n  }\n  stepFromJSON(json: Record<string, unknown>): EngineStep | null\n  pluginState(key: string): unknown\n}\n\n/** Reach the engine the way bundled extensions do. */\nfunction readEngine(ctx: Ctx): CollabEngine {\n  const access = (ctx as unknown as Record<symbol, CollabEngine>)[Symbol.for('matra.engine')]\n  if (!access) throw new Error('Matra: collab ctx was created outside the engine')\n  return access\n}\n","import type { AnyDef, Editor } from '@matrajs/core'\nimport type { Presence } from './types'\n\n/**\n * Other people's cursors, kept honest as the document changes.\n *\n * A remote caret arrives as a position in the sender's document. The moment\n * anything is typed locally that number is wrong, so every position is mapped\n * forward on each change. Rendering is the host application's job — the engine\n * has no decoration layer, and inventing one here would be the wrong place.\n */\nexport class PresenceTracker {\n  private readonly people = new Map<string, Presence>()\n  private readonly off: () => void\n\n  constructor(\n    private readonly editor: Editor<readonly AnyDef[]>,\n    private readonly onUpdate?: (people: Presence[]) => void,\n  ) {\n    let previous = editor.getJSON()\n    this.off = editor.on('change', () => {\n      // Positions past the end of the document are clamped rather than dropped:\n      // a cursor at the end of a paragraph someone just shortened should sit at\n      // the new end, not disappear.\n      const size = measure(editor.getJSON())\n      for (const [id, person] of this.people) {\n        this.people.set(id, {\n          ...person,\n          anchor: Math.min(person.anchor, size),\n          head: Math.min(person.head, size),\n        })\n      }\n      previous = editor.getJSON()\n      void previous\n      this.onUpdate?.(this.list())\n    })\n  }\n\n  set(person: Presence): void {\n    this.people.set(person.clientId, person)\n    this.onUpdate?.(this.list())\n  }\n\n  remove(clientId: string): void {\n    if (this.people.delete(clientId)) this.onUpdate?.(this.list())\n  }\n\n  list(): Presence[] {\n    return [...this.people.values()]\n  }\n\n  destroy(): void {\n    this.off()\n    this.people.clear()\n  }\n}\n\nfunction measure(doc: { content?: unknown[]; text?: string }): number {\n  if (typeof doc.text === 'string') return doc.text.length\n  let size = 0\n  for (const child of (doc.content ?? []) as Array<{ content?: unknown[]; text?: string }>) {\n    size += typeof child.text === 'string' ? child.text.length : measure(child) + 2\n  }\n  return size\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,116 @@
+import { ExtensionDef, Command, Editor, AnyDef } from '@matrajs/core';
+
+/** One change, as it travels between clients. */
+interface CollabStep {
+    /** The step, serialised. */
+    step: Record<string, unknown>;
+    /** Who made it, so a client can recognise its own work coming back. */
+    clientId: string;
+}
+interface Sendable {
+    /** The document version these steps apply to. */
+    version: number;
+    steps: CollabStep[];
+    clientId: string;
+}
+/** Where another person's caret is, in this client's coordinates. */
+interface Presence {
+    clientId: string;
+    anchor: number;
+    head: number;
+    /** Free-form, for a name and a colour. */
+    meta?: Record<string, unknown>;
+}
+
+/**
+ * The server side of the protocol, as a plain object.
+ *
+ * An authority is barely anything: a list of steps and the rule that a client
+ * may only append if it is up to date. Keeping it transport-free means the same
+ * object works over WebSocket, HTTP polling or an in-memory channel in tests.
+ */
+declare class Authority {
+    private readonly onChange?;
+    private readonly history;
+    constructor(onChange?: ((version: number) => void) | undefined);
+    get version(): number;
+    /**
+     * Append steps if the client is current.
+     *
+     * Returns false when it is not — the client should pull what it missed,
+     * rebase, and try again. Rejecting rather than merging is what keeps the
+     * history linear and every client's version meaningful.
+     */
+    receive(version: number, steps: CollabStep[]): boolean;
+    /** Everything that happened after `version`. */
+    since(version: number): CollabStep[];
+}
+
+interface CollabOptions {
+    /** Identifies this client. Two clients must never share one. */
+    clientId: string;
+    /** The version this client starts from. */
+    version?: number;
+}
+/** A local step, kept with what it takes to rewind and rebase it. */
+interface PendingStep {
+    step: EngineStep;
+    /** The step that undoes it, computed against the document it applied to. */
+    inverted: EngineStep;
+    json: Record<string, unknown>;
+    clientId: string;
+}
+interface CollabState {
+    version: number;
+    /** Local steps the authority has not confirmed yet. */
+    unconfirmed: PendingStep[];
+}
+/** The slice of a step this package needs; the engine owns the real type. */
+interface EngineStep {
+    toJSON(): Record<string, unknown>;
+    invert(doc: unknown): EngineStep;
+    map(mapping: unknown): EngineStep | null;
+}
+/**
+ * Collaborative editing over a central authority.
+ *
+ * The protocol is the well-trodden one: a client sends the steps it has made
+ * together with the version they applied to, and the authority accepts them
+ * only if that version is still current. A client whose version is stale pulls
+ * the steps it missed, rebases its own unconfirmed work over them, and tries
+ * again.
+ *
+ * There is no CRDT here and no dependency. Rebasing already lives in the engine
+ * — `Step.map` is what lets a local edit survive a remote one — so
+ * collaboration is a version counter and a transport on top of it.
+ */
+declare function collab(options: CollabOptions): ExtensionDef<{
+    receiveCollabSteps: Command<[steps: CollabStep[]]>;
+    confirmCollabSteps: Command<[count: number]>;
+}, CollabState>;
+/** Steps this client has made that the authority has not seen. */
+declare function sendableSteps(editor: Editor<readonly AnyDef[]>): Sendable | null;
+/** The version of the document this client believes it is on. */
+declare function getVersion(editor: Editor<readonly AnyDef[]>): number;
+
+/**
+ * Other people's cursors, kept honest as the document changes.
+ *
+ * A remote caret arrives as a position in the sender's document. The moment
+ * anything is typed locally that number is wrong, so every position is mapped
+ * forward on each change. Rendering is the host application's job — the engine
+ * has no decoration layer, and inventing one here would be the wrong place.
+ */
+declare class PresenceTracker {
+    private readonly editor;
+    private readonly onUpdate?;
+    private readonly people;
+    private readonly off;
+    constructor(editor: Editor<readonly AnyDef[]>, onUpdate?: ((people: Presence[]) => void) | undefined);
+    set(person: Presence): void;
+    remove(clientId: string): void;
+    list(): Presence[];
+    destroy(): void;
+}
+
+export { Authority, type CollabOptions, type CollabState, type CollabStep, type Presence, PresenceTracker, type Sendable, collab, getVersion, sendableSteps };

package/dist/index.d.ts

@@ -0,0 +1,116 @@
+import { ExtensionDef, Command, Editor, AnyDef } from '@matrajs/core';
+
+/** One change, as it travels between clients. */
+interface CollabStep {
+    /** The step, serialised. */
+    step: Record<string, unknown>;
+    /** Who made it, so a client can recognise its own work coming back. */
+    clientId: string;
+}
+interface Sendable {
+    /** The document version these steps apply to. */
+    version: number;
+    steps: CollabStep[];
+    clientId: string;
+}
+/** Where another person's caret is, in this client's coordinates. */
+interface Presence {
+    clientId: string;
+    anchor: number;
+    head: number;
+    /** Free-form, for a name and a colour. */
+    meta?: Record<string, unknown>;
+}
+
+/**
+ * The server side of the protocol, as a plain object.
+ *
+ * An authority is barely anything: a list of steps and the rule that a client
+ * may only append if it is up to date. Keeping it transport-free means the same
+ * object works over WebSocket, HTTP polling or an in-memory channel in tests.
+ */
+declare class Authority {
+    private readonly onChange?;
+    private readonly history;
+    constructor(onChange?: ((version: number) => void) | undefined);
+    get version(): number;
+    /**
+     * Append steps if the client is current.
+     *
+     * Returns false when it is not — the client should pull what it missed,
+     * rebase, and try again. Rejecting rather than merging is what keeps the
+     * history linear and every client's version meaningful.
+     */
+    receive(version: number, steps: CollabStep[]): boolean;
+    /** Everything that happened after `version`. */
+    since(version: number): CollabStep[];
+}
+
+interface CollabOptions {
+    /** Identifies this client. Two clients must never share one. */
+    clientId: string;
+    /** The version this client starts from. */
+    version?: number;
+}
+/** A local step, kept with what it takes to rewind and rebase it. */
+interface PendingStep {
+    step: EngineStep;
+    /** The step that undoes it, computed against the document it applied to. */
+    inverted: EngineStep;
+    json: Record<string, unknown>;
+    clientId: string;
+}
+interface CollabState {
+    version: number;
+    /** Local steps the authority has not confirmed yet. */
+    unconfirmed: PendingStep[];
+}
+/** The slice of a step this package needs; the engine owns the real type. */
+interface EngineStep {
+    toJSON(): Record<string, unknown>;
+    invert(doc: unknown): EngineStep;
+    map(mapping: unknown): EngineStep | null;
+}
+/**
+ * Collaborative editing over a central authority.
+ *
+ * The protocol is the well-trodden one: a client sends the steps it has made
+ * together with the version they applied to, and the authority accepts them
+ * only if that version is still current. A client whose version is stale pulls
+ * the steps it missed, rebases its own unconfirmed work over them, and tries
+ * again.
+ *
+ * There is no CRDT here and no dependency. Rebasing already lives in the engine
+ * — `Step.map` is what lets a local edit survive a remote one — so
+ * collaboration is a version counter and a transport on top of it.
+ */
+declare function collab(options: CollabOptions): ExtensionDef<{
+    receiveCollabSteps: Command<[steps: CollabStep[]]>;
+    confirmCollabSteps: Command<[count: number]>;
+}, CollabState>;
+/** Steps this client has made that the authority has not seen. */
+declare function sendableSteps(editor: Editor<readonly AnyDef[]>): Sendable | null;
+/** The version of the document this client believes it is on. */
+declare function getVersion(editor: Editor<readonly AnyDef[]>): number;
+
+/**
+ * Other people's cursors, kept honest as the document changes.
+ *
+ * A remote caret arrives as a position in the sender's document. The moment
+ * anything is typed locally that number is wrong, so every position is mapped
+ * forward on each change. Rendering is the host application's job — the engine
+ * has no decoration layer, and inventing one here would be the wrong place.
+ */
+declare class PresenceTracker {
+    private readonly editor;
+    private readonly onUpdate?;
+    private readonly people;
+    private readonly off;
+    constructor(editor: Editor<readonly AnyDef[]>, onUpdate?: ((people: Presence[]) => void) | undefined);
+    set(person: Presence): void;
+    remove(clientId: string): void;
+    list(): Presence[];
+    destroy(): void;
+}
+
+export { Authority, type CollabOptions, type CollabState, type CollabStep, type Presence, PresenceTracker, type Sendable, collab, getVersion, sendableSteps };

package/dist/index.js

@@ -0,0 +1,192 @@
+// src/authority.ts
+var Authority = class {
+  constructor(onChange) {
+    this.onChange = onChange;
+  }
+  onChange;
+  history = [];
+  get version() {
+    return this.history.length;
+  }
+  /**
+   * Append steps if the client is current.
+   *
+   * Returns false when it is not — the client should pull what it missed,
+   * rebase, and try again. Rejecting rather than merging is what keeps the
+   * history linear and every client's version meaningful.
+   */
+  receive(version, steps) {
+    if (version !== this.version) return false;
+    this.history.push(...steps);
+    this.onChange?.(this.version);
+    return true;
+  }
+  /** Everything that happened after `version`. */
+  since(version) {
+    return this.history.slice(version);
+  }
+};
+
+// src/collab.ts
+var REMOTE = "collab:remote";
+var CONFIRM = "collab:confirm";
+var REBASED = "collab:rebased";
+function collab(options) {
+  const clientId = options.clientId;
+  if (!clientId) throw new Error("Matra: collab needs a clientId");
+  return {
+    kind: "extension",
+    name: "collab",
+    state: {
+      init: () => ({ version: options.version ?? 0, unconfirmed: [] }),
+      apply: (ctx, previous) => {
+        const engine = readEngine(ctx);
+        const tr = engine.tr;
+        const confirmed = tr.getMeta(CONFIRM);
+        if (typeof confirmed === "number") {
+          return {
+            version: previous.version + confirmed,
+            unconfirmed: previous.unconfirmed.slice(confirmed)
+          };
+        }
+        const rebased = tr.getMeta(REBASED);
+        if (rebased) {
+          return {
+            version: previous.version + rebased.remote,
+            unconfirmed: rebased.unconfirmed
+          };
+        }
+        if (!tr.steps.length) return previous;
+        if (tr.getMeta(REMOTE)) return previous;
+        const pending = tr.steps.map((step, index) => ({
+          step,
+          inverted: step.invert(tr.docs[index]),
+          json: step.toJSON(),
+          clientId
+        }));
+        return {
+          version: previous.version,
+          unconfirmed: [...previous.unconfirmed, ...pending]
+        };
+      }
+    },
+    commands: {
+      /**
+       * Apply steps from other clients.
+       *
+       * Steps this client sent are skipped — they are already in the document,
+       * and applying them twice would duplicate the edit. A step that no longer
+       * applies is dropped rather than throwing: one bad message from a peer
+       * must not take the editor down.
+       */
+      receiveCollabSteps: (ctx, incoming) => {
+        if (!incoming?.length) return false;
+        const engine = readEngine(ctx);
+        const foreign = incoming.filter((entry) => entry.clientId !== clientId);
+        if (!foreign.length) return false;
+        const pending = engine.pluginState("collab")?.unconfirmed ?? [];
+        const tr = engine.tr;
+        for (let i = pending.length - 1; i >= 0; i--) {
+          tr.maybeStep(pending[i]?.inverted);
+        }
+        const beforeRemote = tr.steps.length;
+        let applied = 0;
+        for (const entry of foreign) {
+          const step = engine.stepFromJSON(entry.step);
+          if (step && tr.maybeStep(step)) applied++;
+        }
+        if (!applied) return false;
+        const remoteMapping = tr.mapping.slice(beforeRemote);
+        const rebased = [];
+        for (const entry of pending) {
+          const mapped = entry.step.map(remoteMapping);
+          if (!mapped) continue;
+          const docBefore = tr.doc;
+          if (!tr.maybeStep(mapped)) continue;
+          rebased.push({
+            step: mapped,
+            inverted: mapped.invert(docBefore),
+            json: mapped.toJSON(),
+            clientId
+          });
+        }
+        tr.setMeta(REBASED, { remote: applied, unconfirmed: rebased });
+        return true;
+      },
+      /** The authority accepted this many of our steps; stop tracking them. */
+      confirmCollabSteps: (ctx, count) => {
+        if (!Number.isInteger(count) || count <= 0) return false;
+        readEngine(ctx).tr.setMeta(CONFIRM, count);
+        return true;
+      }
+    }
+  };
+}
+function sendableSteps(editor) {
+  const state = editor.extensionState("collab");
+  if (!state?.unconfirmed.length) return null;
+  return {
+    version: state.version,
+    steps: state.unconfirmed.map((entry) => ({ step: entry.json, clientId: entry.clientId })),
+    clientId: state.unconfirmed[0]?.clientId ?? ""
+  };
+}
+function getVersion(editor) {
+  return editor.extensionState("collab")?.version ?? 0;
+}
+function readEngine(ctx) {
+  const access = ctx[/* @__PURE__ */ Symbol.for("matra.engine")];
+  if (!access) throw new Error("Matra: collab ctx was created outside the engine");
+  return access;
+}
+
+// src/presence.ts
+var PresenceTracker = class {
+  constructor(editor, onUpdate) {
+    this.editor = editor;
+    this.onUpdate = onUpdate;
+    editor.getJSON();
+    this.off = editor.on("change", () => {
+      const size = measure(editor.getJSON());
+      for (const [id, person] of this.people) {
+        this.people.set(id, {
+          ...person,
+          anchor: Math.min(person.anchor, size),
+          head: Math.min(person.head, size)
+        });
+      }
+      editor.getJSON();
+      this.onUpdate?.(this.list());
+    });
+  }
+  editor;
+  onUpdate;
+  people = /* @__PURE__ */ new Map();
+  off;
+  set(person) {
+    this.people.set(person.clientId, person);
+    this.onUpdate?.(this.list());
+  }
+  remove(clientId) {
+    if (this.people.delete(clientId)) this.onUpdate?.(this.list());
+  }
+  list() {
+    return [...this.people.values()];
+  }
+  destroy() {
+    this.off();
+    this.people.clear();
+  }
+};
+function measure(doc) {
+  if (typeof doc.text === "string") return doc.text.length;
+  let size = 0;
+  for (const child of doc.content ?? []) {
+    size += typeof child.text === "string" ? child.text.length : measure(child) + 2;
+  }
+  return size;
+}
+
+export { Authority, PresenceTracker, collab, getVersion, sendableSteps };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/authority.ts","../src/collab.ts","../src/presence.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { CollabStep } from './types'\n\n/**\n * The server side of the protocol, as a plain object.\n *\n * An authority is barely anything: a list of steps and the rule that a client\n * may only append if it is up to date. Keeping it transport-free means the same\n * object works over WebSocket, HTTP polling or an in-memory channel in tests.\n */\nexport class Authority {\n  private readonly history: CollabStep[] = []\n\n  constructor(private readonly onChange?: (version: number) => void) {}\n\n  get version(): number {\n    return this.history.length\n  }\n\n  /**\n   * Append steps if the client is current.\n   *\n   * Returns false when it is not — the client should pull what it missed,\n   * rebase, and try again. Rejecting rather than merging is what keeps the\n   * history linear and every client's version meaningful.\n   */\n  receive(version: number, steps: CollabStep[]): boolean {\n    if (version !== this.version) return false\n    this.history.push(...steps)\n    this.onChange?.(this.version)\n    return true\n  }\n\n  /** Everything that happened after `version`. */\n  since(version: number): CollabStep[] {\n    return this.history.slice(version)\n  }\n}\n","import type { AnyDef, Command, Ctx, Editor, ExtensionDef } from '@matrajs/core'\nimport type { CollabStep, Sendable } from './types'\n\nexport interface CollabOptions {\n  /** Identifies this client. Two clients must never share one. */\n  clientId: string\n  /** The version this client starts from. */\n  version?: number\n}\n\n/** A local step, kept with what it takes to rewind and rebase it. */\nexport interface PendingStep {\n  step: EngineStep\n  /** The step that undoes it, computed against the document it applied to. */\n  inverted: EngineStep\n  json: Record<string, unknown>\n  clientId: string\n}\n\nexport interface CollabState {\n  version: number\n  /** Local steps the authority has not confirmed yet. */\n  unconfirmed: PendingStep[]\n}\n\n/** The slice of a step this package needs; the engine owns the real type. */\ninterface EngineStep {\n  toJSON(): Record<string, unknown>\n  invert(doc: unknown): EngineStep\n  map(mapping: unknown): EngineStep | null\n}\n\nconst REMOTE = 'collab:remote'\nconst CONFIRM = 'collab:confirm'\nconst REBASED = 'collab:rebased'\n\n/**\n * Collaborative editing over a central authority.\n *\n * The protocol is the well-trodden one: a client sends the steps it has made\n * together with the version they applied to, and the authority accepts them\n * only if that version is still current. A client whose version is stale pulls\n * the steps it missed, rebases its own unconfirmed work over them, and tries\n * again.\n *\n * There is no CRDT here and no dependency. Rebasing already lives in the engine\n * — `Step.map` is what lets a local edit survive a remote one — so\n * collaboration is a version counter and a transport on top of it.\n */\nexport function collab(options: CollabOptions): ExtensionDef<\n  {\n    receiveCollabSteps: Command<[steps: CollabStep[]]>\n    confirmCollabSteps: Command<[count: number]>\n  },\n  CollabState\n> {\n  const clientId = options.clientId\n  if (!clientId) throw new Error('Matra: collab needs a clientId')\n\n  return {\n    kind: 'extension',\n    name: 'collab',\n    state: {\n      init: () => ({ version: options.version ?? 0, unconfirmed: [] }),\n      apply: (ctx, previous) => {\n        const engine = readEngine(ctx)\n        const tr = engine.tr\n\n        const confirmed = tr.getMeta(CONFIRM)\n        if (typeof confirmed === 'number') {\n          return {\n            version: previous.version + confirmed,\n            unconfirmed: previous.unconfirmed.slice(confirmed),\n          }\n        }\n\n        const rebased = tr.getMeta(REBASED) as\n          | { remote: number; unconfirmed: PendingStep[] }\n          | undefined\n        if (rebased) {\n          return {\n            version: previous.version + rebased.remote,\n            unconfirmed: rebased.unconfirmed,\n          }\n        }\n\n        if (!tr.steps.length) return previous\n        if (tr.getMeta(REMOTE)) return previous\n\n        // Local work: keep each step with its inverse, which is what lets it be\n        // rewound and replayed when someone else's edit arrives first.\n        const pending: PendingStep[] = tr.steps.map((step, index) => ({\n          step,\n          inverted: step.invert(tr.docs[index]),\n          json: step.toJSON(),\n          clientId,\n        }))\n        return {\n          version: previous.version,\n          unconfirmed: [...previous.unconfirmed, ...pending],\n        }\n      },\n    },\n    commands: {\n      /**\n       * Apply steps from other clients.\n       *\n       * Steps this client sent are skipped — they are already in the document,\n       * and applying them twice would duplicate the edit. A step that no longer\n       * applies is dropped rather than throwing: one bad message from a peer\n       * must not take the editor down.\n       */\n      receiveCollabSteps: (ctx, incoming) => {\n        if (!incoming?.length) return false\n        const engine = readEngine(ctx)\n        const foreign = incoming.filter((entry) => entry.clientId !== clientId)\n        if (!foreign.length) return false\n\n        const pending =\n          (engine.pluginState('collab') as CollabState | undefined)?.unconfirmed ?? []\n        const tr = engine.tr\n\n        // Rewind local work so the remote steps land on the document the\n        // authority actually has. Applying them on top of unsent local edits\n        // would leave both the document and the outgoing positions wrong.\n        for (let i = pending.length - 1; i >= 0; i--) {\n          tr.maybeStep(pending[i]?.inverted as never)\n        }\n\n        const beforeRemote = tr.steps.length\n        let applied = 0\n        for (const entry of foreign) {\n          const step = engine.stepFromJSON(entry.step)\n          if (step && tr.maybeStep(step)) applied++\n        }\n        if (!applied) return false\n\n        // Replay local work over the remote changes.\n        const remoteMapping = tr.mapping.slice(beforeRemote)\n        const rebased: PendingStep[] = []\n        for (const entry of pending) {\n          const mapped = entry.step.map(remoteMapping)\n          if (!mapped) continue\n          const docBefore = tr.doc\n          if (!tr.maybeStep(mapped as never)) continue\n          rebased.push({\n            step: mapped,\n            inverted: mapped.invert(docBefore),\n            json: mapped.toJSON(),\n            clientId,\n          })\n        }\n\n        tr.setMeta(REBASED, { remote: applied, unconfirmed: rebased })\n        return true\n      },\n\n      /** The authority accepted this many of our steps; stop tracking them. */\n      confirmCollabSteps: (ctx, count) => {\n        if (!Number.isInteger(count) || count <= 0) return false\n        readEngine(ctx).tr.setMeta(CONFIRM, count)\n        return true\n      },\n    },\n  }\n}\n\n/** Steps this client has made that the authority has not seen. */\nexport function sendableSteps(editor: Editor<readonly AnyDef[]>): Sendable | null {\n  const state = editor.extensionState<CollabState>('collab')\n  if (!state?.unconfirmed.length) return null\n  return {\n    version: state.version,\n    steps: state.unconfirmed.map((entry) => ({ step: entry.json, clientId: entry.clientId })),\n    clientId: state.unconfirmed[0]?.clientId ?? '',\n  }\n}\n\n/** The version of the document this client believes it is on. */\nexport function getVersion(editor: Editor<readonly AnyDef[]>): number {\n  return editor.extensionState<CollabState>('collab')?.version ?? 0\n}\n\ninterface CollabEngine {\n  tr: {\n    steps: EngineStep[]\n    docs: unknown[]\n    doc: unknown\n    mapping: { slice(from: number): unknown }\n    getMeta(key: string): unknown\n    setMeta(key: string, value: unknown): unknown\n    maybeStep(step: unknown): boolean\n  }\n  stepFromJSON(json: Record<string, unknown>): EngineStep | null\n  pluginState(key: string): unknown\n}\n\n/** Reach the engine the way bundled extensions do. */\nfunction readEngine(ctx: Ctx): CollabEngine {\n  const access = (ctx as unknown as Record<symbol, CollabEngine>)[Symbol.for('matra.engine')]\n  if (!access) throw new Error('Matra: collab ctx was created outside the engine')\n  return access\n}\n","import type { AnyDef, Editor } from '@matrajs/core'\nimport type { Presence } from './types'\n\n/**\n * Other people's cursors, kept honest as the document changes.\n *\n * A remote caret arrives as a position in the sender's document. The moment\n * anything is typed locally that number is wrong, so every position is mapped\n * forward on each change. Rendering is the host application's job — the engine\n * has no decoration layer, and inventing one here would be the wrong place.\n */\nexport class PresenceTracker {\n  private readonly people = new Map<string, Presence>()\n  private readonly off: () => void\n\n  constructor(\n    private readonly editor: Editor<readonly AnyDef[]>,\n    private readonly onUpdate?: (people: Presence[]) => void,\n  ) {\n    let previous = editor.getJSON()\n    this.off = editor.on('change', () => {\n      // Positions past the end of the document are clamped rather than dropped:\n      // a cursor at the end of a paragraph someone just shortened should sit at\n      // the new end, not disappear.\n      const size = measure(editor.getJSON())\n      for (const [id, person] of this.people) {\n        this.people.set(id, {\n          ...person,\n          anchor: Math.min(person.anchor, size),\n          head: Math.min(person.head, size),\n        })\n      }\n      previous = editor.getJSON()\n      void previous\n      this.onUpdate?.(this.list())\n    })\n  }\n\n  set(person: Presence): void {\n    this.people.set(person.clientId, person)\n    this.onUpdate?.(this.list())\n  }\n\n  remove(clientId: string): void {\n    if (this.people.delete(clientId)) this.onUpdate?.(this.list())\n  }\n\n  list(): Presence[] {\n    return [...this.people.values()]\n  }\n\n  destroy(): void {\n    this.off()\n    this.people.clear()\n  }\n}\n\nfunction measure(doc: { content?: unknown[]; text?: string }): number {\n  if (typeof doc.text === 'string') return doc.text.length\n  let size = 0\n  for (const child of (doc.content ?? []) as Array<{ content?: unknown[]; text?: string }>) {\n    size += typeof child.text === 'string' ? child.text.length : measure(child) + 2\n  }\n  return size\n}\n"]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@matrajs/collab",
+  "version": "0.3.0",
+  "description": "Collaborative editing for Matra — step exchange, rebasing and presence. No CRDT dependency.",
+  "license": "MIT",
+  "author": "Nahim Hossain Shohan",
+  "homepage": "https://matrajs.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amrelaco/matra.git",
+    "directory": "packages/collab"
+  },
+  "bugs": {
+    "url": "https://github.com/amrelaco/matra/issues"
+  },
+  "keywords": [
+    "editor",
+    "rich-text",
+    "collaborative",
+    "matra",
+    "ot"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@matrajs/core": "^0.3.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist"
+  }
+}