@moloodev/editor-sdk 0.0.0-stage → 0.1.0

package/src/crdt/diff.ts

@@ -0,0 +1,86 @@
+/** One contiguous replacement, in UTF-16 code units like `String.length`. */
+type TextEdit = {
+  start: number;
+  deleteCount: number;
+  insert: string;
+};
+
+const isHighSurrogate = (code: number) => code >= 0xd800 && code <= 0xdbff;
+const isLowSurrogate = (code: number) => code >= 0xdc00 && code <= 0xdfff;
+
+/** Minimal single-span edit turning `before` into `after`; null when equal. */
+export function diffText(before: string, after: string): TextEdit | null {
+  if (before === after) return null;
+  const shortest = Math.min(before.length, after.length);
+  let start = 0;
+  while (
+    start < shortest &&
+    before.charCodeAt(start) === after.charCodeAt(start)
+  )
+    start++;
+  let endBefore = before.length;
+  let endAfter = after.length;
+  while (
+    endBefore > start &&
+    endAfter > start &&
+    before.charCodeAt(endBefore - 1) === after.charCodeAt(endAfter - 1)
+  ) {
+    endBefore--;
+    endAfter--;
+  }
+  // Never split a surrogate pair: a concurrent merge would otherwise interleave halves.
+  if (start > 0 && isHighSurrogate(before.charCodeAt(start - 1))) start--;
+  if (endBefore < before.length && isLowSurrogate(before.charCodeAt(endBefore))) {
+    endBefore++;
+    endAfter++;
+  }
+  return {
+    start,
+    deleteCount: endBefore - start,
+    insert: after.slice(start, endAfter),
+  };
+}
+
+export function applyTextEdit(text: string, edit: TextEdit): string {
+  return (
+    text.slice(0, edit.start) +
+    edit.insert +
+    text.slice(edit.start + edit.deleteCount)
+  );
+}
+
+/**
+ * Re-express an edit made against `base` in the coordinates of `current`, the
+ * text a concurrent change produced from `base`. Disjoint spans commute exactly.
+ * When the spans overlap, the concurrent replacement is kept intact and the local
+ * insertion lands right after it; the editor shows the merged result immediately.
+ */
+export function rebaseEdit(
+  edit: TextEdit,
+  base: string,
+  current: string,
+): TextEdit {
+  const remote = diffText(base, current);
+  if (!remote) return edit;
+  const localEnd = edit.start + edit.deleteCount;
+  const remoteEnd = remote.start + remote.deleteCount;
+  if (localEnd <= remote.start) return edit;
+  if (edit.start >= remoteEnd) {
+    return {
+      ...edit,
+      start: edit.start + remote.insert.length - remote.deleteCount,
+    };
+  }
+  if (edit.start < remote.start) {
+    return {
+      start: edit.start,
+      deleteCount: remote.start - edit.start,
+      insert: edit.insert,
+    };
+  }
+  return {
+    start: remote.start + remote.insert.length,
+    deleteCount: Math.max(0, localEnd - remoteEnd),
+    insert: edit.insert,
+  };
+}

package/src/crdt/doc.ts

@@ -0,0 +1,67 @@
+import { Y } from "./yjs";
+
+export type Doc = Y.Doc;
+
+export const REMOTE_ORIGIN = "remote";
+export const LOCAL_ORIGIN = "local";
+/**
+ * Format schema migrations of the working copy. Synced and persisted like local
+ * edits, but never captured by undo: undoing one would unstamp the version.
+ */
+export const SCHEMA_ORIGIN = "schema";
+
+export function createDoc(): Doc {
+  return new Y.Doc();
+}
+
+export function destroyDoc(doc: Doc): void {
+  doc.destroy();
+}
+
+export function transact(
+  doc: Doc,
+  fn: () => void,
+  origin: unknown = LOCAL_ORIGIN,
+): void {
+  doc.transact(fn, origin);
+}
+
+export function applyUpdate(
+  doc: Doc,
+  update: Uint8Array,
+  origin: unknown = REMOTE_ORIGIN,
+): void {
+  Y.applyUpdate(doc, update, origin);
+}
+
+export function encodeState(doc: Doc, vector?: Uint8Array): Uint8Array {
+  return Y.encodeStateAsUpdate(doc, vector);
+}
+
+export function encodeVector(doc: Doc): Uint8Array {
+  return Y.encodeStateVector(doc);
+}
+
+export function mergeUpdates(updates: readonly Uint8Array[]): Uint8Array {
+  return Y.mergeUpdates([...updates]);
+}
+
+export function getMap(doc: Doc, name: string): Y.Map<unknown> {
+  return doc.getMap(name);
+}
+
+export function getArray(doc: Doc, name: string): Y.Array<unknown> {
+  return doc.getArray(name);
+}
+
+export function toJson(doc: Doc): Record<string, unknown> {
+  // `Doc.toJSON()` omits a map until it is accessed on this instance.
+  return { root: getMap(doc, "root").toJSON() };
+}
+
+export function observe(doc: Doc, listener: () => void): () => void {
+  doc.on("update", listener);
+  return () => {
+    doc.off("update", listener);
+  };
+}

package/src/crdt/front-matter.ts

@@ -0,0 +1,45 @@
+export type FrontMatterSpan = {
+  readonly from: number;
+  readonly to: number;
+  readonly yamlFrom: number;
+  readonly yamlTo: number;
+};
+
+function isFence(line: string): boolean {
+  if (line.length < 3 || line[0] !== "-" || line[1] !== "-" || line[2] !== "-") return false;
+  for (let index = 3; index < line.length; index += 1) {
+    const char = line[index];
+    if (char !== " " && char !== "\t") return false;
+  }
+  return true;
+}
+
+function readLine(text: string, start: number): { readonly end: number; readonly next: number } {
+  let index = start;
+  while (index < text.length) {
+    const char = text[index];
+    if (char === "\n") return { end: index, next: index + 1 };
+    if (char === "\r") {
+      const paired = index + 1 < text.length && text[index + 1] === "\n";
+      return { end: index, next: index + (paired ? 2 : 1) };
+    }
+    index += 1;
+  }
+  return { end: text.length, next: text.length };
+}
+
+export function frontMatterSpan(text: string): FrontMatterSpan | null {
+  const opener = readLine(text, 0);
+  if (opener.next === opener.end || !isFence(text.slice(0, opener.end))) return null;
+  const yamlFrom = opener.next;
+  let start = yamlFrom;
+  while (start < text.length) {
+    const line = readLine(text, start);
+    if (isFence(text.slice(start, line.end))) {
+      return { from: 0, to: line.next, yamlFrom, yamlTo: start };
+    }
+    if (line.next === line.end) return null;
+    start = line.next;
+  }
+  return null;
+}

package/src/crdt/index.ts

@@ -0,0 +1,76 @@
+export {
+  createDoc,
+  destroyDoc,
+  transact,
+  applyUpdate,
+  encodeState,
+  encodeVector,
+  mergeUpdates,
+  getMap,
+  getArray,
+  toJson,
+  observe,
+  REMOTE_ORIGIN,
+  LOCAL_ORIGIN,
+  SCHEMA_ORIGIN,
+  type Doc,
+} from "./doc";
+export { createUndo, stopCapturing, type DocUndo } from "./undo";
+export {
+  createAwareness,
+  setLocalPresence,
+  localPresence,
+  states,
+  destroyPresence,
+  type Presence,
+} from "./awareness";
+export { openLocal, type LocalPersist } from "./persist";
+export {
+  connectSync,
+  connectPresence,
+  shouldReconnect,
+  nextReconnectDelay,
+  type SocketFactory,
+  type SocketHandle,
+  type SyncControl,
+  type SyncStatus,
+} from "./connect";
+export { toBase64, fromBase64 } from "./bytes";
+export {
+  writeJson,
+  toShared,
+  createMap,
+  createArray,
+  createText,
+  isMap,
+  isArray,
+  isText,
+  rootMap,
+  type SharedMap,
+  type SharedArray,
+  type SharedText,
+} from "./shared";
+export {
+  encodeSyncStep1,
+  encodeSyncUpdate,
+  syncOpenMessages,
+  encodeAwarenessUpdate,
+  readSync,
+  isSyncStep1,
+  applyAwarenessMessage,
+  validateAwarenessMessage,
+  extractSyncUpdate,
+  peekType,
+  MSG_SYNC,
+  MSG_AWARENESS,
+} from "./protocol";
+export { applyTextEdit, diffText, rebaseEdit } from "./diff";
+export { frontMatterSpan, type FrontMatterSpan } from "./front-matter";
+export {
+  TEXT_BODY_SCHEMA_VERSION,
+  blankTextBodyPayload,
+  readBody,
+  readsTextBodySchemaVersion,
+  writeBody,
+  writeTextBodyContent,
+} from "./text-body";

package/src/crdt/persist.ts

@@ -0,0 +1,40 @@
+import type { Doc } from "./doc";
+
+export type LocalPersist = {
+  whenSynced: Promise<void>;
+  destroy: () => void;
+};
+
+type Persistence = {
+  whenSynced: Promise<unknown>;
+  destroy: () => Promise<void> | void;
+};
+
+/** IndexedDB is client-only. Load it on demand so server sync does not import `yjs` twice. */
+export function openLocal(doc: Doc, key: string): LocalPersist {
+  let persistence: Persistence | null = null;
+  let cancelled = false;
+  let resolveSynced: () => void = () => {};
+  const whenSynced = new Promise<void>((resolve) => {
+    resolveSynced = resolve;
+  });
+
+  void import("y-indexeddb")
+    .then(({ IndexeddbPersistence }) => {
+      if (cancelled) {
+        resolveSynced();
+        return;
+      }
+      persistence = new IndexeddbPersistence(key, doc);
+      void persistence.whenSynced.then(() => resolveSynced());
+    })
+    .catch(() => resolveSynced());
+
+  return {
+    whenSynced,
+    destroy() {
+      cancelled = true;
+      void persistence?.destroy();
+    },
+  };
+}

package/src/crdt/protocol.ts

@@ -0,0 +1,119 @@
+import { awarenessProtocol, decoding, encoding, syncProtocol } from "./yjs";
+import type { Doc } from "./doc";
+import { encodeState, REMOTE_ORIGIN } from "./doc";
+import type { Presence } from "./awareness";
+
+export const MSG_SYNC = 0;
+export const MSG_AWARENESS = 1;
+
+export function readSync(doc: Doc, message: Uint8Array): Uint8Array | null {
+  const decoder = decoding.createDecoder(message);
+  const encoder = encoding.createEncoder();
+  const messageType = decoding.readVarUint(decoder);
+  if (messageType !== MSG_SYNC) return null;
+  encoding.writeVarUint(encoder, MSG_SYNC);
+  const written = syncProtocol.readSyncMessage(
+    decoder,
+    encoder,
+    doc,
+    REMOTE_ORIGIN,
+    (error) => {
+      throw error;
+    },
+  );
+  if (decoding.hasContent(decoder)) throw new Error("invalid_sync_frame");
+  if (written === 0 && encoding.length(encoder) <= 1) return null;
+  return encoding.toUint8Array(encoder);
+}
+
+export function encodeSyncStep1(doc: Doc): Uint8Array {
+  const encoder = encoding.createEncoder();
+  encoding.writeVarUint(encoder, MSG_SYNC);
+  syncProtocol.writeSyncStep1(encoder, doc);
+  return encoding.toUint8Array(encoder);
+}
+
+export function encodeSyncUpdate(update: Uint8Array): Uint8Array {
+  const encoder = encoding.createEncoder();
+  encoding.writeVarUint(encoder, MSG_SYNC);
+  syncProtocol.writeUpdate(encoder, update);
+  return encoding.toUint8Array(encoder);
+}
+
+/** Handshake plus a persistable full-state update. Step1 alone cannot publish client-only edits. */
+export function syncOpenMessages(doc: Doc): Uint8Array[] {
+  return [encodeSyncStep1(doc), encodeSyncUpdate(encodeState(doc))];
+}
+
+export function encodeAwarenessUpdate(
+  presence: Presence,
+  clients?: number[],
+): Uint8Array {
+  const ids = clients ?? [...presence.getStates().keys()];
+  const encoder = encoding.createEncoder();
+  encoding.writeVarUint(encoder, MSG_AWARENESS);
+  encoding.writeVarUint8Array(
+    encoder,
+    awarenessProtocol.encodeAwarenessUpdate(presence, ids),
+  );
+  return encoding.toUint8Array(encoder);
+}
+
+export function applyAwarenessMessage(
+  presence: Presence,
+  message: Uint8Array,
+): void {
+  const decoder = decoding.createDecoder(message);
+  const messageType = decoding.readVarUint(decoder);
+  if (messageType !== MSG_AWARENESS) return;
+  awarenessProtocol.applyAwarenessUpdate(
+    presence,
+    decoding.readVarUint8Array(decoder),
+    REMOTE_ORIGIN,
+  );
+}
+
+export function peekType(message: Uint8Array): number {
+  const decoder = decoding.createDecoder(message);
+  return decoding.readVarUint(decoder);
+}
+
+/** Apply a raw Yjs update extracted from a sync-update frame, or pass through. */
+export function extractSyncUpdate(message: Uint8Array): Uint8Array | null {
+  const decoder = decoding.createDecoder(message);
+  const type = decoding.readVarUint(decoder);
+  if (type !== MSG_SYNC) return null;
+  const syncType = decoding.readVarUint(decoder);
+  if (syncType !== syncProtocol.messageYjsUpdate) return null;
+  return decoding.readVarUint8Array(decoder);
+}
+
+/** Validate the full awareness envelope before a server relays it to other clients. */
+export function validateAwarenessMessage(message: Uint8Array): void {
+  const outer = decoding.createDecoder(message);
+  if (decoding.readVarUint(outer) !== MSG_AWARENESS)
+    throw new Error("invalid_awareness");
+  const body = decoding.createDecoder(decoding.readVarUint8Array(outer));
+  const count = decoding.readVarUint(body);
+  if (count > message.byteLength) throw new Error("invalid_awareness");
+  for (let index = 0; index < count; index++) {
+    decoding.readVarUint(body); // client id
+    decoding.readVarUint(body); // clock
+    const state: unknown = JSON.parse(decoding.readVarString(body));
+    if (state !== null && (typeof state !== "object" || Array.isArray(state)))
+      throw new Error("invalid_awareness");
+  }
+  if (decoding.hasContent(body) || decoding.hasContent(outer))
+    throw new Error("invalid_awareness");
+}
+
+/** Step1 only asks for the missing state; answering it never mutates a document. */
+export function isSyncStep1(message: Uint8Array): boolean {
+  const decoder = decoding.createDecoder(message);
+  if (decoding.readVarUint(decoder) !== MSG_SYNC) return false;
+  if (decoding.readVarUint(decoder) !== syncProtocol.messageYjsSyncStep1)
+    return false;
+  decoding.readVarUint8Array(decoder);
+  if (decoding.hasContent(decoder)) throw new Error("invalid_sync_frame");
+  return true;
+}

package/src/crdt/shared.ts

@@ -0,0 +1,104 @@
+import { getMap, transact, type Doc } from "./doc";
+import { Y } from "./yjs";
+
+export type SharedMap = Y.Map<unknown>;
+export type SharedArray = Y.Array<unknown>;
+/** Character-level mergeable text. Projects to a plain string in `toJson`. */
+export type SharedText = Y.Text;
+
+export function createMap(): SharedMap {
+  return new Y.Map();
+}
+
+export function createArray(): SharedArray {
+  return new Y.Array();
+}
+
+export function createText(initial = ""): SharedText {
+  return new Y.Text(initial);
+}
+
+export function isMap(value: unknown): value is SharedMap {
+  return value instanceof Y.Map;
+}
+
+export function isArray(value: unknown): value is SharedArray {
+  return value instanceof Y.Array;
+}
+
+export function isText(value: unknown): value is SharedText {
+  return value instanceof Y.Text;
+}
+
+function writeIntoMap(map: SharedMap, value: Record<string, unknown>): void {
+  for (const [key, nested] of Object.entries(value)) {
+    writeInto(map, key, nested);
+  }
+}
+
+function writeInto(
+  parent: SharedMap,
+  key: string,
+  value: unknown,
+): void {
+  if (Array.isArray(value)) {
+    const arr = createArray();
+    parent.set(key, arr);
+    for (const item of value) {
+      if (item && typeof item === "object" && !Array.isArray(item)) {
+        const nested = createMap();
+        arr.push([nested]);
+        writeIntoMap(nested, item as Record<string, unknown>);
+        continue;
+      }
+      if (Array.isArray(item)) {
+        const nested = createArray();
+        arr.push([nested]);
+        for (const child of item) nested.push([child]);
+        continue;
+      }
+      arr.push([item]);
+    }
+    return;
+  }
+  if (value && typeof value === "object") {
+    const nested = createMap();
+    parent.set(key, nested);
+    writeIntoMap(nested, value as Record<string, unknown>);
+    return;
+  }
+  parent.set(key, value);
+}
+
+export function toShared(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    const arr = createArray();
+    for (const item of value) {
+      arr.push([toShared(item)]);
+    }
+    return arr;
+  }
+  if (value && typeof value === "object") {
+    const map = createMap();
+    for (const [key, nested] of Object.entries(value as Record<string, unknown>)) {
+      map.set(key, toShared(nested));
+    }
+    return map;
+  }
+  return value;
+}
+
+/** Write a JSON object as nested shared types under `root`. */
+export function writeJson(doc: Doc, payload: Record<string, unknown>): void {
+  transact(doc, () => {
+    const root = getMap(doc, "root");
+    for (const key of [...root.keys()]) {
+      root.delete(key);
+    }
+    writeIntoMap(root, payload);
+  });
+}
+
+export function rootMap(doc: Doc): SharedMap {
+  return getMap(doc, "root");
+}

package/src/crdt/text-body.ts

@@ -0,0 +1,125 @@
+import {
+  SCHEMA_ORIGIN,
+  transact,
+  type Doc,
+} from "./doc";
+import { diffText, rebaseEdit } from "./diff";
+import {
+  createText,
+  isText,
+  rootMap,
+  toShared,
+  type SharedMap,
+} from "./shared";
+
+/** v2 stores `body` as shared text so concurrent edits merge per character. */
+export const TEXT_BODY_SCHEMA_VERSION = 2;
+
+const READABLE_TEXT_BODY_VERSIONS: ReadonlySet<unknown> = new Set([
+  1,
+  TEXT_BODY_SCHEMA_VERSION,
+]);
+
+export function readsTextBodySchemaVersion(version: unknown): boolean {
+  return READABLE_TEXT_BODY_VERSIONS.has(version);
+}
+
+export function readBody(
+  data: Record<string, unknown> | null | undefined,
+): string {
+  if (!data) return "";
+  return typeof data.body === "string" ? data.body : "";
+}
+
+function assertReadable(root: SharedMap): void {
+  if (root.has("version") && !readsTextBodySchemaVersion(root.get("version")))
+    throw new Error("unsupported_schema");
+}
+
+/**
+ * Apply the editor's change to the shared body and return the merged text.
+ *
+ * `base` is the text the editor derived `body` from. Only the difference between
+ * them is written, so concurrent edits elsewhere in the body survive; when the
+ * shared body already moved past `base`, the edit is rebased onto it. Legacy
+ * string bodies migrate to the current schema on their first real edit. That
+ * migration is not undoable: undo restores the text, never the old version.
+ */
+export function writeBody(doc: Doc, body: string, base?: string): string {
+  const root = rootMap(doc);
+  assertReadable(root);
+  const current = root.get("body");
+  if (isText(current)) {
+    const currentText = current.toString();
+    const edit = diffText(base ?? currentText, body);
+    if (!edit) return currentText;
+    const placed =
+      base !== undefined && base !== currentText
+        ? rebaseEdit(edit, base, currentText)
+        : edit;
+    transact(doc, () => {
+      if (placed.deleteCount > 0)
+        current.delete(placed.start, placed.deleteCount);
+      if (placed.insert) current.insert(placed.start, placed.insert);
+    });
+    return current.toString();
+  }
+  if (current !== undefined && typeof current !== "string")
+    throw new Error("invalid_body");
+  const legacy = current ?? "";
+  const edit = diffText(base ?? legacy, body);
+  if (!edit) return legacy;
+  const placed =
+    base !== undefined && base !== legacy
+      ? rebaseEdit(edit, base, legacy)
+      : edit;
+  transact(
+    doc,
+    () => {
+      root.set("body", createText(legacy));
+      root.set("version", TEXT_BODY_SCHEMA_VERSION);
+    },
+    SCHEMA_ORIGIN,
+  );
+  const text = root.get("body");
+  if (!isText(text)) throw new Error("invalid_body");
+  transact(doc, () => {
+    if (placed.deleteCount > 0) text.delete(placed.start, placed.deleteCount);
+    if (placed.insert) text.insert(placed.start, placed.insert);
+  });
+  return text.toString();
+}
+
+/**
+ * Server-side JSON → shared types in the shape text documents store. Unversioned
+ * payloads become the current version; explicit versions are written as given
+ * so write gates can still judge them.
+ */
+export function writeTextBodyContent(
+  doc: Doc,
+  payload: Record<string, unknown>,
+): void {
+  transact(doc, () => {
+    const root = rootMap(doc);
+    for (const key of [...root.keys()]) root.delete(key);
+    const version = Object.hasOwn(payload, "version")
+      ? payload.version
+      : TEXT_BODY_SCHEMA_VERSION;
+    for (const [key, value] of Object.entries(payload)) {
+      if (key === "version") continue;
+      root.set(
+        key,
+        key === "body" &&
+          typeof value === "string" &&
+          version === TEXT_BODY_SCHEMA_VERSION
+          ? createText(value)
+          : toShared(value),
+      );
+    }
+    root.set("version", version);
+  });
+}
+
+export function blankTextBodyPayload(): Record<string, unknown> {
+  return { body: "" };
+}