@spooky-sync/core 0.0.1-canary.52 → 0.0.1-canary.54

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import * as surrealdb0 from "surrealdb";
 import { Duration, RecordId, Surreal as Surreal$1, SurrealTransaction } from "surrealdb";
 import { AccessDefinition, BackendNames, BackendRoutes, BucketNames, ColumnSchema, GetTable, QueryBuilder, QueryOptions, RoutePayload, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap } from "@spooky-sync/query-builder";
 import { Logger } from "pino";
+import { LoroDoc } from "loro-crdt";
 
 //#region src/services/database/events/index.d.ts
 declare const DatabaseEventTypes: {
@@ -194,6 +195,74 @@ declare class AuthService<S extends SchemaStructure> {
   signIn<Name extends keyof S['access'] & string>(accessName: Name, params: ExtractAccessParams<S, Name, 'signIn'>): Promise<void>;
 }
 //#endregion
+//#region src/modules/crdt/crdt-field.d.ts
+declare const CURSOR_COLORS: string[];
+declare function cursorColorFromName(name: string): string;
+declare class CrdtField {
+  private fieldName;
+  private doc;
+  private pushTimer;
+  private remote;
+  private recordId;
+  private unsubscribe;
+  private lastPushTime;
+  private lastCursorPushTime;
+  private loadedFromCrdt;
+  private pushRetryCount;
+  private logger;
+  private _onCursorUpdate;
+  private pendingCursorUpdate;
+  /** Callback set by the editor to receive remote cursor updates.
+   *  Any cursor data that arrived before this callback was set will be replayed. */
+  set onCursorUpdate(cb: ((data: Uint8Array) => void) | null);
+  get onCursorUpdate(): ((data: Uint8Array) => void) | null;
+  constructor(fieldName: string, initialState?: string, logger?: Logger$1 | null);
+  getDoc(): LoroDoc;
+  /** Whether the LoroDoc was loaded from saved CRDT state */
+  hasContent(): boolean;
+  startSync(remote: RemoteDatabaseService, recordId: string): void;
+  stopSync(): void;
+  importRemote(base64State: string): void;
+  exportSnapshot(): string;
+  /** Push cursor ephemeral state to _00_crdt as a "_cursor_<fieldName>" entry */
+  pushCursorState(encoded: Uint8Array): Promise<void>;
+  /** Import remote cursor state (called by CrdtManager from LIVE SELECT) */
+  importRemoteCursor(base64State: string): void;
+  private schedulePush;
+  private pushToRemote;
+}
+//#endregion
+//#region src/modules/crdt/index.d.ts
+/**
+ * CrdtManager manages active CrdtField instances and their sync channels.
+ *
+ * Each open record gets a LIVE SELECT on _00_crdt that delivers remote
+ * changes in real time.
+ */
+declare class CrdtManager {
+  private schema;
+  private remote;
+  private fields;
+  private liveQueries;
+  private logger;
+  constructor(schema: SchemaStructure, remote: RemoteDatabaseService, logger: Logger$1);
+  /**
+   * Open a CRDT field for collaborative editing.
+   *
+   * @param table - Table name
+   * @param recordId - Full record ID (e.g., "thread:abc")
+   * @param field - Field name (e.g., "title", "content")
+   * @param fallbackText - Current plain text from the record, used to seed the
+   *                       LoroDoc if no CRDT state exists yet (migration path)
+   */
+  open(table: string, recordId: string, field: string, fallbackText?: string): Promise<CrdtField>;
+  close(table: string, recordId: string, field: string): void;
+  closeAll(): void;
+  private ensureLiveSelect;
+  private killLiveSelect;
+  private makeKey;
+}
+//#endregion
 //#region src/sp00ky.d.ts
 declare class BucketHandle {
   private bucketName;
@@ -218,6 +287,7 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   private dataModule;
   private sync;
   private devTools;
+  private crdtManager;
   private logger;
   auth: AuthService<S>;
   streamProcessor: StreamProcessorService;
@@ -233,6 +303,16 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   init(): Promise<void>;
   close(): Promise<void>;
   authenticate(token: string): Promise<surrealdb0.Tokens>;
+  /**
+   * Open a CRDT field for collaborative editing.
+   * Returns a CrdtField with a LoroDoc that can be bound to any editor.
+   * Also starts a LIVE SELECT on _00_crdt for real-time sync.
+   */
+  openCrdtField(table: string, recordId: string, field: string, fallbackText?: string): Promise<CrdtField>;
+  /**
+   * Close a CRDT field when editing is done.
+   */
+  closeCrdtField(table: string, recordId: string, field: string): void;
   deauthenticate(): Promise<void>;
   query<Table extends TableNames<S>>(table: Table, options: QueryOptions<TableModel<GetTable<S, Table>>, false>, ttl?: QueryTimeToLive): QueryBuilder<S, Table, Sp00kyQueryResultPromise>;
   private initQuery;
@@ -254,9 +334,14 @@ declare class Sp00kyClient<S extends SchemaStructure> {
 //#endregion
 //#region src/utils/index.d.ts
 declare function fileToUint8Array(file: File | Blob): Promise<Uint8Array>;
+/**
+ * Convert plain text to simple HTML paragraphs.
+ * Useful for seeding a rich-text editor (e.g. TipTap/ProseMirror) with fallback content.
+ */
+declare function textToHtml(text: string): string;
 /**
  * Helper for retrying DB operations with exponential backoff
  */
 
 //#endregion
-export { AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, DebounceOptions, EventSubscriptionOptions, Level, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PinoTransmit, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryTimeToLive, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StoreType, UpdateOptions, createAuthEventSystem, fileToUint8Array };
+export { AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, Level, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PinoTransmit, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryTimeToLive, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StoreType, UpdateOptions, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };

package/dist/index.js

@@ -3,6 +3,7 @@ import { QueryBuilder, RecordId as RecordId$1 } from "@spooky-sync/query-builder
 import { createWasmWorkerEngines } from "@surrealdb/wasm";
 import pino from "pino";
 import init, { Sp00kyProcessor } from "@spooky-sync/ssp-wasm";
+import { LoroDoc } from "loro-crdt";
 
 //#region src/utils/surql.ts
 const surql = {
@@ -71,7 +72,7 @@ const surql = {
 //#region src/utils/parser.ts
 function cleanRecord(tableSchema, record) {
 	const cleaned = {};
-	for (const [key, value] of Object.entries(record)) if (key === "id" || key in tableSchema) cleaned[key] = value;
+	for (const [key, value] of Object.entries(record)) if (key === "id" || key.startsWith("_00_") || key in tableSchema) cleaned[key] = value;
 	return cleaned;
 }
 function parseParams(tableSchema, params) {
@@ -169,6 +170,13 @@ async function fileToUint8Array(file) {
 	return new Uint8Array(buffer);
 }
 /**
+* Convert plain text to simple HTML paragraphs.
+* Useful for seeding a rich-text editor (e.g. TipTap/ProseMirror) with fallback content.
+*/
+function textToHtml(text) {
+	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").split("\n").map((l) => `<p>${l || "<br>"}</p>`).join("");
+}
+/**
 * Helper for retrying DB operations with exponential backoff
 */
 async function withRetry(logger, operation, retries = 3, delayMs = 100) {
@@ -1867,7 +1875,7 @@ var Sp00kySync = class {
 			Category: "sp00ky-client::Sp00kySync::processUpEvent"
 		}, "Processing up event");
 		switch (event.type) {
-			case "create":
+			case "create": {
 				const dataKeys = Object.keys(event.data).map((key) => ({
 					key,
 					variable: `data_${key}`
@@ -1879,6 +1887,7 @@ var Sp00kySync = class {
 					...prefixedParams
 				});
 				break;
+			}
 			case "update":
 				await this.remote.query(`UPDATE $id MERGE $data`, {
 					id: event.record_id,
@@ -2849,6 +2858,305 @@ var CacheModule = class {
 	}
 };
 
+//#endregion
+//#region src/modules/crdt/crdt-field.ts
+const CURSOR_COLORS = [
+	"#3b82f6",
+	"#ef4444",
+	"#22c55e",
+	"#f59e0b",
+	"#8b5cf6",
+	"#ec4899",
+	"#14b8a6",
+	"#f97316"
+];
+function cursorColorFromName(name) {
+	let hash = 0;
+	for (let i = 0; i < name.length; i++) hash = (hash << 5) - hash + name.charCodeAt(i) | 0;
+	return CURSOR_COLORS[Math.abs(hash) % CURSOR_COLORS.length];
+}
+var CrdtField = class {
+	doc;
+	pushTimer = null;
+	remote = null;
+	recordId = null;
+	unsubscribe = null;
+	lastPushTime = 0;
+	lastCursorPushTime = 0;
+	loadedFromCrdt = false;
+	pushRetryCount = 0;
+	logger;
+	_onCursorUpdate = null;
+	pendingCursorUpdate = null;
+	/** Callback set by the editor to receive remote cursor updates.
+	*  Any cursor data that arrived before this callback was set will be replayed. */
+	set onCursorUpdate(cb) {
+		this._onCursorUpdate = cb;
+		if (cb && this.pendingCursorUpdate) {
+			try {
+				cb(this.pendingCursorUpdate);
+			} catch (e) {
+				this.logger?.warn({
+					error: e,
+					Category: "sp00ky-client::CrdtField::onCursorUpdate"
+				}, "Failed to replay pending cursor update");
+			}
+			this.pendingCursorUpdate = null;
+		}
+	}
+	get onCursorUpdate() {
+		return this._onCursorUpdate;
+	}
+	constructor(fieldName, initialState, logger) {
+		this.fieldName = fieldName;
+		this.logger = logger ?? null;
+		this.doc = new LoroDoc();
+		if (initialState) {
+			this.doc.import(decodeBase64(initialState));
+			this.loadedFromCrdt = true;
+		}
+	}
+	getDoc() {
+		return this.doc;
+	}
+	/** Whether the LoroDoc was loaded from saved CRDT state */
+	hasContent() {
+		return this.loadedFromCrdt;
+	}
+	startSync(remote, recordId) {
+		this.remote = remote;
+		this.recordId = recordId;
+		this.unsubscribe = this.doc.subscribeLocalUpdates(() => {
+			this.schedulePush();
+		});
+	}
+	stopSync() {
+		if (this.unsubscribe) {
+			this.unsubscribe();
+			this.unsubscribe = null;
+		}
+		if (this.pushTimer) {
+			clearTimeout(this.pushTimer);
+			this.pushTimer = null;
+		}
+		if (this.remote && this.recordId) this.pushToRemote();
+	}
+	importRemote(base64State) {
+		if (Date.now() - this.lastPushTime < 500) return;
+		try {
+			this.doc.import(decodeBase64(base64State));
+		} catch (e) {
+			this.logger?.warn({
+				error: e,
+				Category: "sp00ky-client::CrdtField::importRemote"
+			}, "Failed to import remote CRDT state");
+		}
+	}
+	exportSnapshot() {
+		return encodeBase64(this.doc.export({ mode: "snapshot" }));
+	}
+	/** Push cursor ephemeral state to _00_crdt as a "_cursor_<fieldName>" entry */
+	async pushCursorState(encoded) {
+		if (!this.remote || !this.recordId) return;
+		this.lastCursorPushTime = Date.now();
+		try {
+			const state = encodeBase64(encoded);
+			await this.remote.query(`INSERT INTO _00_crdt (record_id, field, state) VALUES ($rid, $field, $state)
+         ON DUPLICATE KEY UPDATE state = $state`, {
+				rid: parseRecordIdString(this.recordId),
+				field: `_cursor_${this.fieldName}`,
+				state
+			});
+		} catch (e) {
+			this.logger?.warn({
+				error: e,
+				Category: "sp00ky-client::CrdtField::pushCursorState"
+			}, "Failed to push cursor state");
+		}
+	}
+	/** Import remote cursor state (called by CrdtManager from LIVE SELECT) */
+	importRemoteCursor(base64State) {
+		if (Date.now() - this.lastCursorPushTime < 300) return;
+		try {
+			const data = decodeBase64(base64State);
+			if (this._onCursorUpdate) this._onCursorUpdate(data);
+			else this.pendingCursorUpdate = data;
+		} catch (e) {
+			this.logger?.warn({
+				error: e,
+				Category: "sp00ky-client::CrdtField::importRemoteCursor"
+			}, "Failed to apply remote cursor data");
+		}
+	}
+	schedulePush() {
+		if (this.pushTimer) clearTimeout(this.pushTimer);
+		this.pushTimer = setTimeout(() => void this.pushToRemote(), 300);
+	}
+	async pushToRemote() {
+		if (!this.remote || !this.recordId) return;
+		this.lastPushTime = Date.now();
+		try {
+			await this.remote.query(`INSERT INTO _00_crdt (record_id, field, state) VALUES ($rid, $field, $state)
+         ON DUPLICATE KEY UPDATE state = $state`, {
+				rid: parseRecordIdString(this.recordId),
+				field: this.fieldName,
+				state: this.exportSnapshot()
+			});
+			this.pushRetryCount = 0;
+		} catch (e) {
+			this.logger?.warn({
+				error: e,
+				Category: "sp00ky-client::CrdtField::pushToRemote"
+			}, "Failed to push CRDT state to remote");
+			if (this.pushRetryCount < 2) {
+				this.pushRetryCount++;
+				this.schedulePush();
+			}
+		}
+	}
+};
+function decodeBase64(b64) {
+	if (typeof atob === "function") {
+		const binary = atob(b64);
+		const bytes = new Uint8Array(binary.length);
+		for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+		return bytes;
+	}
+	return new Uint8Array(Buffer.from(b64, "base64"));
+}
+function encodeBase64(bytes) {
+	if (typeof btoa === "function") {
+		let binary = "";
+		for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+		return btoa(binary);
+	}
+	return Buffer.from(bytes).toString("base64");
+}
+
+//#endregion
+//#region src/modules/crdt/index.ts
+/**
+* CrdtManager manages active CrdtField instances and their sync channels.
+*
+* Each open record gets a LIVE SELECT on _00_crdt that delivers remote
+* changes in real time.
+*/
+var CrdtManager = class {
+	fields = /* @__PURE__ */ new Map();
+	liveQueries = /* @__PURE__ */ new Map();
+	logger;
+	constructor(schema, remote, logger) {
+		this.schema = schema;
+		this.remote = remote;
+		this.logger = logger.child({ service: "CrdtManager" });
+	}
+	/**
+	* Open a CRDT field for collaborative editing.
+	*
+	* @param table - Table name
+	* @param recordId - Full record ID (e.g., "thread:abc")
+	* @param field - Field name (e.g., "title", "content")
+	* @param fallbackText - Current plain text from the record, used to seed the
+	*                       LoroDoc if no CRDT state exists yet (migration path)
+	*/
+	async open(table, recordId, field, fallbackText) {
+		const key = this.makeKey(table, recordId, field);
+		let crdtField = this.fields.get(key);
+		if (crdtField) return crdtField;
+		let initialCrdtState;
+		try {
+			const [result] = await this.remote.query("SELECT VALUE state FROM _00_crdt WHERE record_id = $rid AND field = $field LIMIT 1", {
+				rid: parseRecordIdString(recordId),
+				field
+			});
+			if (result && result.length > 0 && result[0]) initialCrdtState = result[0];
+		} catch (e) {
+			this.logger.debug({
+				error: e,
+				Category: "sp00ky-client::CrdtManager::open"
+			}, "No existing CRDT state found");
+		}
+		crdtField = new CrdtField(field, initialCrdtState, this.logger);
+		crdtField.startSync(this.remote, recordId);
+		this.fields.set(key, crdtField);
+		this.logger.info({
+			key,
+			hasInitialState: !!initialCrdtState,
+			hasFallback: !!fallbackText,
+			Category: "sp00ky-client::CrdtManager::open"
+		}, "CrdtField opened");
+		await this.ensureLiveSelect(table, recordId);
+		return crdtField;
+	}
+	close(table, recordId, field) {
+		const key = this.makeKey(table, recordId, field);
+		const crdtField = this.fields.get(key);
+		if (crdtField) {
+			crdtField.stopSync();
+			this.fields.delete(key);
+		}
+		const prefix = `${table}:${recordId}:`;
+		if (!Array.from(this.fields.keys()).some((k) => k !== key && k.startsWith(prefix))) this.killLiveSelect(recordId);
+		this.logger.debug({
+			key,
+			Category: "sp00ky-client::CrdtManager::close"
+		}, "CrdtField closed");
+	}
+	closeAll() {
+		for (const [_, field] of this.fields) field.stopSync();
+		this.fields.clear();
+		for (const recordId of this.liveQueries.keys()) this.killLiveSelect(recordId);
+	}
+	async ensureLiveSelect(table, recordId) {
+		if (this.liveQueries.has(recordId)) return;
+		try {
+			const [uuid] = await this.remote.query(`LIVE SELECT * FROM _00_crdt WHERE record_id = $rid`, { rid: parseRecordIdString(recordId) });
+			this.liveQueries.set(recordId, {
+				uuid,
+				table
+			});
+			(await this.remote.getClient().liveOf(uuid)).subscribe((message) => {
+				if (message.action === "KILLED") return;
+				if (message.action === "CREATE" || message.action === "UPDATE") {
+					const fieldName = message.value.field;
+					const state = message.value.state;
+					if (!fieldName || !state) return;
+					if (fieldName.startsWith("_cursor_")) {
+						const actualField = fieldName.slice(8);
+						const key = this.makeKey(table, recordId, actualField);
+						const crdtField = this.fields.get(key);
+						if (crdtField) crdtField.importRemoteCursor(state);
+						return;
+					}
+					const key = this.makeKey(table, recordId, fieldName);
+					const crdtField = this.fields.get(key);
+					if (crdtField) crdtField.importRemote(state);
+				}
+			});
+			this.logger.info({
+				recordId,
+				Category: "sp00ky-client::CrdtManager::ensureLiveSelect"
+			}, "LIVE SELECT on _00_crdt started");
+		} catch (e) {
+			this.logger.warn({
+				error: e,
+				recordId,
+				Category: "sp00ky-client::CrdtManager::ensureLiveSelect"
+			}, "Failed to start LIVE SELECT on _00_crdt");
+		}
+	}
+	killLiveSelect(recordId) {
+		const entry = this.liveQueries.get(recordId);
+		if (entry) {
+			this.remote.query("KILL $uuid", { uuid: entry.uuid }).catch(() => {});
+			this.liveQueries.delete(recordId);
+		}
+	}
+	makeKey(table, recordId, field) {
+		return `${table}:${recordId}:${field}`;
+	}
+};
+
 //#endregion
 //#region src/services/persistence/localstorage.ts
 var LocalStoragePersistenceClient = class {
@@ -2996,6 +3304,7 @@ var Sp00kyClient = class {
 	dataModule;
 	sync;
 	devTools;
+	crdtManager;
 	logger;
 	auth;
 	streamProcessor;
@@ -3033,6 +3342,7 @@ var Sp00kyClient = class {
 		this.cache = new CacheModule(this.local, this.streamProcessor, (update) => {
 			this.dataModule.onStreamUpdate(update);
 		}, logger);
+		this.crdtManager = new CrdtManager(this.config.schema, this.remote, logger);
 		this.dataModule = new DataModule(this.cache, this.local, this.config.schema, logger, this.config.streamDebounceTime);
 		this.auth = new AuthService(this.config.schema, this.remote, this.persistenceClient, logger);
 		this.sync = new Sp00kySync(this.local, this.remote, this.cache, this.dataModule, this.config.schema, this.logger);
@@ -3091,12 +3401,27 @@ var Sp00kyClient = class {
 		}
 	}
 	async close() {
+		this.crdtManager.closeAll();
 		await this.local.close();
 		await this.remote.close();
 	}
 	authenticate(token) {
 		return this.remote.getClient().authenticate(token);
 	}
+	/**
+	* Open a CRDT field for collaborative editing.
+	* Returns a CrdtField with a LoroDoc that can be bound to any editor.
+	* Also starts a LIVE SELECT on _00_crdt for real-time sync.
+	*/
+	async openCrdtField(table, recordId, field, fallbackText) {
+		return this.crdtManager.open(table, recordId, field, fallbackText);
+	}
+	/**
+	* Close a CRDT field when editing is done.
+	*/
+	closeCrdtField(table, recordId, field) {
+		this.crdtManager.close(table, recordId, field);
+	}
 	deauthenticate() {
 		return this.remote.getClient().invalidate();
 	}
@@ -3158,4 +3483,4 @@ var Sp00kyClient = class {
 };
 
 //#endregion
-export { AuthEventTypes, AuthService, BucketHandle, Sp00kyClient, createAuthEventSystem, fileToUint8Array };
+export { AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, Sp00kyClient, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.52",
+  "version": "0.0.1-canary.54",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -63,6 +63,7 @@
     "@spooky-sync/ssp-wasm": "workspace:*",
     "@surrealdb/wasm": "^3.0.0",
     "fast-json-patch": "^3.1.1",
+    "loro-crdt": "^1.5.6",
     "pino": "^10.1.0",
     "surrealdb": "2.0.0"
   },

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from './types';
 export * from './sp00ky';
 export * from './modules/auth/index';
-export { fileToUint8Array } from './utils/index';
+export { CrdtField, CrdtManager, cursorColorFromName, CURSOR_COLORS } from './modules/crdt/index';
+export { fileToUint8Array, textToHtml } from './utils/index';

package/src/modules/crdt/crdt-field.ts

@@ -0,0 +1,189 @@
+import { LoroDoc } from 'loro-crdt';
+import type { RemoteDatabaseService } from '../../services/database/index';
+import type { Logger } from '../../services/logger/index';
+import { parseRecordIdString } from '../../utils/index';
+
+// ==================== CURSOR UTILITIES ====================
+
+export const CURSOR_COLORS = [
+  '#3b82f6', '#ef4444', '#22c55e', '#f59e0b',
+  '#8b5cf6', '#ec4899', '#14b8a6', '#f97316',
+];
+
+export function cursorColorFromName(name: string): string {
+  let hash = 0;
+  for (let i = 0; i < name.length; i++) {
+    hash = ((hash << 5) - hash + name.charCodeAt(i)) | 0;
+  }
+  return CURSOR_COLORS[Math.abs(hash) % CURSOR_COLORS.length];
+}
+
+// ==================== CRDT FIELD ====================
+
+export class CrdtField {
+  private doc: LoroDoc;
+  private pushTimer: ReturnType<typeof setTimeout> | null = null;
+  private remote: RemoteDatabaseService | null = null;
+  private recordId: string | null = null;
+  private unsubscribe: (() => void) | null = null;
+  private lastPushTime = 0;
+  private lastCursorPushTime = 0;
+  private loadedFromCrdt = false;
+  private pushRetryCount = 0;
+  private logger: Logger | null;
+
+  private _onCursorUpdate: ((data: Uint8Array) => void) | null = null;
+  private pendingCursorUpdate: Uint8Array | null = null;
+
+  /** Callback set by the editor to receive remote cursor updates.
+   *  Any cursor data that arrived before this callback was set will be replayed. */
+  set onCursorUpdate(cb: ((data: Uint8Array) => void) | null) {
+    this._onCursorUpdate = cb;
+    if (cb && this.pendingCursorUpdate) {
+      try { cb(this.pendingCursorUpdate); } catch (e) {
+        this.logger?.warn(
+          { error: e, Category: 'sp00ky-client::CrdtField::onCursorUpdate' },
+          'Failed to replay pending cursor update'
+        );
+      }
+      this.pendingCursorUpdate = null;
+    }
+  }
+
+  get onCursorUpdate() { return this._onCursorUpdate; }
+
+  constructor(
+    private fieldName: string,
+    initialState?: string,
+    logger?: Logger | null,
+  ) {
+    this.logger = logger ?? null;
+    this.doc = new LoroDoc();
+    if (initialState) {
+      this.doc.import(decodeBase64(initialState));
+      this.loadedFromCrdt = true;
+    }
+  }
+
+  getDoc(): LoroDoc { return this.doc; }
+
+  /** Whether the LoroDoc was loaded from saved CRDT state */
+  hasContent(): boolean {
+    return this.loadedFromCrdt;
+  }
+
+  startSync(remote: RemoteDatabaseService, recordId: string): void {
+    this.remote = remote;
+    this.recordId = recordId;
+    this.unsubscribe = this.doc.subscribeLocalUpdates(() => {
+      this.schedulePush();
+    });
+  }
+
+  stopSync(): void {
+    if (this.unsubscribe) { this.unsubscribe(); this.unsubscribe = null; }
+    if (this.pushTimer) { clearTimeout(this.pushTimer); this.pushTimer = null; }
+    if (this.remote && this.recordId) { void this.pushToRemote(); }
+  }
+
+  importRemote(base64State: string): void {
+    // Suppress echo: skip imports within 500ms of our own push
+    if (Date.now() - this.lastPushTime < 500) return;
+    try {
+      this.doc.import(decodeBase64(base64State));
+    } catch (e) {
+      this.logger?.warn(
+        { error: e, Category: 'sp00ky-client::CrdtField::importRemote' },
+        'Failed to import remote CRDT state'
+      );
+    }
+  }
+
+  exportSnapshot(): string {
+    return encodeBase64(this.doc.export({ mode: 'snapshot' }));
+  }
+
+  /** Push cursor ephemeral state to _00_crdt as a "_cursor_<fieldName>" entry */
+  async pushCursorState(encoded: Uint8Array): Promise<void> {
+    if (!this.remote || !this.recordId) return;
+    this.lastCursorPushTime = Date.now();
+    try {
+      const state = encodeBase64(encoded);
+      await this.remote.query(
+        `INSERT INTO _00_crdt (record_id, field, state) VALUES ($rid, $field, $state)
+         ON DUPLICATE KEY UPDATE state = $state`,
+        { rid: parseRecordIdString(this.recordId), field: `_cursor_${this.fieldName}`, state }
+      );
+    } catch (e) {
+      this.logger?.warn(
+        { error: e, Category: 'sp00ky-client::CrdtField::pushCursorState' },
+        'Failed to push cursor state'
+      );
+    }
+  }
+
+  /** Import remote cursor state (called by CrdtManager from LIVE SELECT) */
+  importRemoteCursor(base64State: string): void {
+    if (Date.now() - this.lastCursorPushTime < 300) return; // echo suppression
+    try {
+      const data = decodeBase64(base64State);
+      if (this._onCursorUpdate) {
+        this._onCursorUpdate(data);
+      } else {
+        // Only keep the latest cursor state — older positions are useless
+        this.pendingCursorUpdate = data;
+      }
+    } catch (e) {
+      this.logger?.warn(
+        { error: e, Category: 'sp00ky-client::CrdtField::importRemoteCursor' },
+        'Failed to apply remote cursor data'
+      );
+    }
+  }
+
+  private schedulePush(): void {
+    if (this.pushTimer) clearTimeout(this.pushTimer);
+    this.pushTimer = setTimeout(() => void this.pushToRemote(), 300);
+  }
+
+  private async pushToRemote(): Promise<void> {
+    if (!this.remote || !this.recordId) return;
+    this.lastPushTime = Date.now();
+    try {
+      await this.remote.query(
+        `INSERT INTO _00_crdt (record_id, field, state) VALUES ($rid, $field, $state)
+         ON DUPLICATE KEY UPDATE state = $state`,
+        { rid: parseRecordIdString(this.recordId), field: this.fieldName, state: this.exportSnapshot() }
+      );
+      this.pushRetryCount = 0;
+    } catch (e) {
+      this.logger?.warn(
+        { error: e, Category: 'sp00ky-client::CrdtField::pushToRemote' },
+        'Failed to push CRDT state to remote'
+      );
+      if (this.pushRetryCount < 2) {
+        this.pushRetryCount++;
+        this.schedulePush();
+      }
+    }
+  }
+}
+
+export function decodeBase64(b64: string): Uint8Array {
+  if (typeof atob === 'function') {
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return bytes;
+  }
+  return new Uint8Array(Buffer.from(b64, 'base64'));
+}
+
+export function encodeBase64(bytes: Uint8Array): string {
+  if (typeof btoa === 'function') {
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+    return btoa(binary);
+  }
+  return Buffer.from(bytes).toString('base64');
+}

package/src/modules/crdt/index.ts

@@ -0,0 +1,178 @@
+import type { SchemaStructure } from '@spooky-sync/query-builder';
+import type { RemoteDatabaseService } from '../../services/database/index';
+import type { Logger } from '../../services/logger/index';
+import type { Uuid } from 'surrealdb';
+import { CrdtField } from './crdt-field';
+import { parseRecordIdString } from '../../utils/index';
+
+export { CrdtField, cursorColorFromName, CURSOR_COLORS } from './crdt-field';
+
+/**
+ * CrdtManager manages active CrdtField instances and their sync channels.
+ *
+ * Each open record gets a LIVE SELECT on _00_crdt that delivers remote
+ * changes in real time.
+ */
+export class CrdtManager {
+  private fields = new Map<string, CrdtField>();
+  private liveQueries = new Map<string, { uuid: Uuid; table: string }>();
+  private logger: Logger;
+
+  constructor(
+    private schema: SchemaStructure,
+    private remote: RemoteDatabaseService,
+    logger: Logger
+  ) {
+    this.logger = logger.child({ service: 'CrdtManager' });
+  }
+
+  /**
+   * Open a CRDT field for collaborative editing.
+   *
+   * @param table - Table name
+   * @param recordId - Full record ID (e.g., "thread:abc")
+   * @param field - Field name (e.g., "title", "content")
+   * @param fallbackText - Current plain text from the record, used to seed the
+   *                       LoroDoc if no CRDT state exists yet (migration path)
+   */
+  async open(
+    table: string,
+    recordId: string,
+    field: string,
+    fallbackText?: string,
+  ): Promise<CrdtField> {
+    const key = this.makeKey(table, recordId, field);
+    let crdtField = this.fields.get(key);
+
+    if (crdtField) {
+      return crdtField;
+    }
+
+    // Load saved CRDT state from remote _00_crdt table
+    let initialCrdtState: string | undefined;
+    try {
+      const [result] = await this.remote.query<[string[]]>(
+        'SELECT VALUE state FROM _00_crdt WHERE record_id = $rid AND field = $field LIMIT 1',
+        { rid: parseRecordIdString(recordId), field }
+      );
+      if (result && result.length > 0 && result[0]) {
+        initialCrdtState = result[0];
+      }
+    } catch (e) {
+      this.logger.debug(
+        { error: e, Category: 'sp00ky-client::CrdtManager::open' },
+        'No existing CRDT state found'
+      );
+    }
+
+    crdtField = new CrdtField(field, initialCrdtState, this.logger);
+    crdtField.startSync(this.remote, recordId);
+    this.fields.set(key, crdtField);
+
+    this.logger.info(
+      { key, hasInitialState: !!initialCrdtState, hasFallback: !!fallbackText, Category: 'sp00ky-client::CrdtManager::open' },
+      'CrdtField opened'
+    );
+
+    await this.ensureLiveSelect(table, recordId);
+
+    return crdtField;
+  }
+
+  close(table: string, recordId: string, field: string): void {
+    const key = this.makeKey(table, recordId, field);
+    const crdtField = this.fields.get(key);
+    if (crdtField) {
+      crdtField.stopSync();
+      this.fields.delete(key);
+    }
+
+    const prefix = `${table}:${recordId}:`;
+    const hasOtherFields = Array.from(this.fields.keys()).some(
+      (k) => k !== key && k.startsWith(prefix)
+    );
+    if (!hasOtherFields) {
+      this.killLiveSelect(recordId);
+    }
+
+    this.logger.debug(
+      { key, Category: 'sp00ky-client::CrdtManager::close' },
+      'CrdtField closed'
+    );
+  }
+
+  closeAll(): void {
+    for (const [_, field] of this.fields) {
+      field.stopSync();
+    }
+    this.fields.clear();
+    for (const recordId of this.liveQueries.keys()) {
+      this.killLiveSelect(recordId);
+    }
+  }
+
+  private async ensureLiveSelect(table: string, recordId: string): Promise<void> {
+    if (this.liveQueries.has(recordId)) return;
+
+    try {
+      const [uuid] = await this.remote.query<[Uuid]>(
+        `LIVE SELECT * FROM _00_crdt WHERE record_id = $rid`,
+        { rid: parseRecordIdString(recordId) },
+      );
+
+      this.liveQueries.set(recordId, { uuid, table });
+
+      const subscription = await this.remote.getClient().liveOf(uuid);
+      subscription.subscribe((message) => {
+        if (message.action === 'KILLED') return;
+
+        if (message.action === 'CREATE' || message.action === 'UPDATE') {
+          const fieldName = message.value.field as string;
+          const state = message.value.state as string;
+
+          if (!fieldName || !state) return;
+
+          // Route cursor updates to the corresponding CrdtField
+          if (fieldName.startsWith('_cursor_')) {
+            const actualField = fieldName.slice('_cursor_'.length);
+            const key = this.makeKey(table, recordId, actualField);
+            const crdtField = this.fields.get(key);
+            if (crdtField) {
+              crdtField.importRemoteCursor(state);
+            }
+            return;
+          }
+
+          // Route document updates
+          const key = this.makeKey(table, recordId, fieldName);
+          const crdtField = this.fields.get(key);
+          if (crdtField) {
+            crdtField.importRemote(state);
+          }
+        }
+      });
+
+      this.logger.info(
+        { recordId, Category: 'sp00ky-client::CrdtManager::ensureLiveSelect' },
+        'LIVE SELECT on _00_crdt started'
+      );
+    } catch (e) {
+      this.logger.warn(
+        { error: e, recordId, Category: 'sp00ky-client::CrdtManager::ensureLiveSelect' },
+        'Failed to start LIVE SELECT on _00_crdt'
+      );
+    }
+  }
+
+  private killLiveSelect(recordId: string): void {
+    const entry = this.liveQueries.get(recordId);
+    if (entry) {
+      this.remote.query('KILL $uuid', { uuid: entry.uuid }).catch(() => {});
+      this.liveQueries.delete(recordId);
+    }
+  }
+
+  private makeKey(table: string, recordId: string, field: string): string {
+    return `${table}:${recordId}:${field}`;
+  }
+}

package/src/modules/data/index.ts

@@ -468,6 +468,9 @@ export class DataModule<S extends SchemaStructure> {
     const params = parseParams(tableSchema.columns, data);
     const mutationId = parseRecordIdString(`_00_pending_mutations:${Date.now()}`);
 
+    // Note: CRDT state is pushed directly to the _00_crdt table by CrdtField.pushToRemote(),
+    // NOT through the record update pipeline. This keeps the record data clean.
+
     // Capture current record state before mutation for rollback support
     const [beforeRecord] = await withRetry(this.logger, () =>
       this.local.query<[Record<string, any>]>('SELECT * FROM ONLY $id', { id: rid })

package/src/modules/sync/sync.ts

@@ -183,7 +183,7 @@ export class Sp00kySync<S extends SchemaStructure> {
       'Processing up event'
     );
     switch (event.type) {
-      case 'create':
+      case 'create': {
         const dataKeys = Object.keys(event.data).map((key) => ({ key, variable: `data_${key}` }));
         const prefixedParams = Object.fromEntries(
           dataKeys.map(({ key, variable }) => [variable, event.data[key]])
@@ -194,6 +194,7 @@ export class Sp00kySync<S extends SchemaStructure> {
           ...prefixedParams,
         });
         break;
+      }
       case 'update':
         await this.remote.query(`UPDATE $id MERGE $data`, {
           id: event.record_id,

package/src/sp00ky.ts

@@ -34,6 +34,7 @@ import { AuthService } from './modules/auth/index';
 import { StreamProcessorService } from './services/stream-processor/index';
 import { EventSystem } from './events/index';
 import { CacheModule } from './modules/cache/index';
+import { CrdtManager, CrdtField } from './modules/crdt/index';
 import { LocalStoragePersistenceClient } from './services/persistence/localstorage';
 import { generateId, parseParams } from './utils/index';
 import { SurrealDBPersistenceClient } from './services/persistence/surrealdb';
@@ -90,6 +91,7 @@ export class Sp00kyClient<S extends SchemaStructure> {
   private dataModule: DataModule<S>;
   private sync: Sp00kySync<S>;
   private devTools: DevToolsService;
+  private crdtManager: CrdtManager;
 
   private logger: ReturnType<typeof createLogger>;
   public auth: AuthService<S>;
@@ -154,6 +156,9 @@ export class Sp00kyClient<S extends SchemaStructure> {
       logger
     );
 
+    // Initialize CRDT Manager (needs remote for _00_crdt LIVE SELECT)
+    this.crdtManager = new CrdtManager(this.config.schema, this.remote, logger);
+
     this.dataModule = new DataModule(
       this.cache,
       this.local,
@@ -275,6 +280,7 @@ export class Sp00kyClient<S extends SchemaStructure> {
   }
 
   async close() {
+    this.crdtManager.closeAll();
     await this.local.close();
     await this.remote.close();
   }
@@ -283,6 +289,27 @@ export class Sp00kyClient<S extends SchemaStructure> {
     return this.remote.getClient().authenticate(token);
   }
 
+  /**
+   * Open a CRDT field for collaborative editing.
+   * Returns a CrdtField with a LoroDoc that can be bound to any editor.
+   * Also starts a LIVE SELECT on _00_crdt for real-time sync.
+   */
+  async openCrdtField(
+    table: string,
+    recordId: string,
+    field: string,
+    fallbackText?: string,
+  ): Promise<CrdtField> {
+    return this.crdtManager.open(table, recordId, field, fallbackText);
+  }
+
+  /**
+   * Close a CRDT field when editing is done.
+   */
+  closeCrdtField(table: string, recordId: string, field: string): void {
+    this.crdtManager.close(table, recordId, field);
+  }
+
   deauthenticate() {
     return this.remote.getClient().invalidate();
   }

package/src/utils/index.ts

@@ -137,6 +137,18 @@ export async function fileToUint8Array(file: File | Blob): Promise<Uint8Array> {
   return new Uint8Array(buffer);
 }
 
+// ==================== TEXT UTILITIES ====================
+
+/**
+ * Convert plain text to simple HTML paragraphs.
+ * Useful for seeding a rich-text editor (e.g. TipTap/ProseMirror) with fallback content.
+ */
+export function textToHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+    .split('\n').map((l) => `<p>${l || '<br>'}</p>`).join('');
+}
+
 // ==================== DATABASE UTILITIES ====================
 
 /**

package/src/utils/parser.ts

@@ -9,7 +9,7 @@ export function cleanRecord(
 ): Record<string, any> {
   const cleaned: Record<string, any> = {};
   for (const [key, value] of Object.entries(record)) {
-    if (key === 'id' || key in tableSchema) {
+    if (key === 'id' || key.startsWith('_00_') || key in tableSchema) {
       cleaned[key] = value;
     }
   }