@spooky-sync/core 0.0.1-canary.322 → 0.0.1-canary.324

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

@@ -1,7 +1,5 @@
 import type { LoroDoc } from 'loro-crdt';
-import type { LocalStore, RemoteDatabaseService } from '../../services/database/index';
-import type { Logger } from '../../services/logger/index';
-import { parseRecordIdString } from '../../utils/index';
+import type { CrdtKind } from './mirror';
 
 // ==================== CURSOR UTILITIES ====================
 
@@ -18,277 +16,72 @@ export function cursorColorFromName(name: string): string {
   return CURSOR_COLORS[Math.abs(hash) % CURSOR_COLORS.length];
 }
 
+export { decodeBase64, encodeBase64 } from './bytes';
+
 // ==================== CRDT FIELD ====================
 
-export class CrdtField {
-  private doc: LoroDoc;
-  private pushTimer: ReturnType<typeof setTimeout> | null = null;
-  private local: LocalStore | null = null;
-  private remote: RemoteDatabaseService | null = null;
-  private recordId: string | null = null;
-  private sessionId: string = '';
-  private unsubscribe: (() => void) | null = null;
-  private lastPushTime = 0;
-  private lastCursorPushTime = 0;
-  private loadedFromCrdt = false;
-  private pushRetryCount = 0;
-  private logger: Logger | null;
-  private cursorsEnabled: boolean;
-  /** Remote-push debounce. Local writes happen immediately on every Loro
-   *  update; the remote UPSERT is coalesced over this window. Configured
-   *  via `Sp00kyConfig.crdtDebounceMs`, default 500. */
-  private remoteDebounceMs: number = 500;
+/** What a field handle needs from the manager that owns its session. */
+export interface CrdtFieldHost {
+  pushPresence(state: Uint8Array): void;
+}
 
+/**
+ * An open collaborative field: the Loro document an editor binds to. Edits
+ * made on it are sent as the client's own edit-log rows; other clients' rows
+ * are imported into it as they arrive. Every open of the same field in one tab
+ * shares this document.
+ */
+export class CrdtField {
   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; }
-
-  /**
-   * @param LoroDocClass the `LoroDoc` constructor, injected by the caller after
-   *   awaiting {@link loadLoro} — keeps `loro-crdt` out of this module's static
-   *   import graph so it only ships to apps that use CRDT fields.
-   */
   constructor(
-    private fieldName: string,
-    cursorsEnabled: boolean,
-    LoroDocClass: typeof LoroDoc,
-    initialState?: Uint8Array,
-    logger?: Logger | null,
-  ) {
-    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(fieldName)) {
-      throw new Error(
-        `CrdtField: refusing unsafe field identifier '${fieldName}' — must match [a-zA-Z_][a-zA-Z0-9_]*`
-      );
-    }
-    this.logger = logger ?? null;
-    this.cursorsEnabled = cursorsEnabled;
-    this.doc = new LoroDocClass();
-    if (initialState && initialState.length > 0) {
-      // Tolerance: catch bad-snapshot data (corrupt blob, stale legacy
-      // value left over from a pre-`bytes` migration) so the editor still
-      // mounts. Without this guard the rejection bubbles through
-      // `useCrdtField` → permanent fallback `<p>`, with no cursor.
-      try {
-        this.doc.import(initialState);
-        this.loadedFromCrdt = true;
-      } catch (e) {
-        this.logger?.warn(
-          {
-            error: e,
-            fieldName,
-            Category: 'sp00ky-client::CrdtField::constructor',
-          },
-          'Initial CRDT state is not a valid LoroDoc snapshot — starting empty and will seed from fallback text'
-        );
-      }
-    }
-  }
-
-  getDoc(): LoroDoc { return this.doc; }
-
-  /** Whether the LoroDoc was loaded from saved CRDT state */
-  hasContent(): boolean {
-    return this.loadedFromCrdt;
-  }
-
-  startSync(
-    local: LocalStore,
-    remote: RemoteDatabaseService,
-    recordId: string,
-    sessionId: string,
-    debounceMs: number,
-  ): void {
-    this.local = local;
-    this.remote = remote;
-    this.recordId = recordId;
-    this.sessionId = sessionId;
-    this.remoteDebounceMs = debounceMs;
-    // Every local Loro update writes the snapshot to the local cache
-    // *immediately* (so reload/offline see the latest text), then
-    // schedules a debounced push to remote. The local UPSERT is cheap —
-    // it's an in-memory SurrealKV write — but errors are swallowed so a
-    // bad write never blocks user input.
-    this.unsubscribe = this.doc.subscribeLocalUpdates(() => {
-      void this.persistLocal();
-      this.scheduleRemotePush();
-    });
-  }
+    readonly table: string,
+    readonly recordId: string,
+    readonly fieldName: string,
+    readonly kind: CrdtKind,
+    readonly cursorsEnabled: boolean,
+    private readonly doc: LoroDoc,
+    private readonly host: CrdtFieldHost
+  ) {}
 
-  /**
-   * Stop syncing this field. Flushes one final remote push by default so the
-   * last keystrokes aren't lost. Pass `{ flush: false }` on a bucket switch —
-   * the remote session already belongs to the NEXT user, and pushing this
-   * (previous user's) snapshot under it would clobber the record remotely.
-   */
-  stopSync(options: { flush?: boolean } = {}): void {
-    const flush = options.flush ?? true;
-    if (this.unsubscribe) { this.unsubscribe(); this.unsubscribe = null; }
-    if (this.pushTimer) { clearTimeout(this.pushTimer); this.pushTimer = null; }
-    if (flush && this.remote && this.recordId) { void this.pushToRemote(); }
+  getDoc(): LoroDoc {
+    return this.doc;
   }
 
-  importRemote(state: Uint8Array): void {
-    // Echo suppression: skip imports within `remoteDebounceMs + 200` of
-    // our own push. The +200 guards against round-trip jitter where our
-    // own write echoes back from the LIVE feed before the debounce
-    // window closes.
-    if (Date.now() - this.lastPushTime < this.remoteDebounceMs + 200) return;
-    try {
-      this.doc.import(state);
-      // Persist the merged snapshot locally so the next reload/offline
-      // open sees the freshest converged state without waiting for the
-      // LIVE feed.
-      void this.persistLocal();
-    } catch (e) {
-      this.logger?.warn(
-        { error: e, Category: 'sp00ky-client::CrdtField::importRemote' },
-        'Failed to import remote CRDT state'
-      );
-    }
-  }
-
-  exportSnapshot(): Uint8Array {
-    return this.doc.export({ mode: 'snapshot' });
-  }
-
-  /** Push this session's cursor blob into the parent row at
-   *  `<field>.cursors[$sid]`. No-op when cursors aren't enabled on this
-   *  field — the editor still calls this method optimistically, but
-   *  without `@cursor` on the schema there's nowhere to store the blob.
-   *  The UPDATE itself fires the parent table's LIVE feed, so other
-   *  browsers receive the cursor change without a separate `_00_rv` bump. */
-  async pushCursorState(encoded: Uint8Array): Promise<void> {
-    if (!this.remote || !this.recordId) return;
-    if (!this.cursorsEnabled) return;
-    this.lastCursorPushTime = Date.now();
-    try {
-      const state = encodeBase64(encoded);
-      await this.remote.query(
-        `UPDATE $id SET ${this.fieldName}.cursors[$sid] = $state RETURN NONE;`,
-        {
-          id: parseRecordIdString(this.recordId),
-          sid: this.sessionId,
-          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 scheduleRemotePush(): void {
-    if (this.pushTimer) clearTimeout(this.pushTimer);
-    this.pushTimer = setTimeout(() => void this.pushToRemote(), this.remoteDebounceMs);
-  }
-
-  /** SET path inside a parent row for the current snapshot. `@crdt`-only
-   *  fields hold the snapshot directly (`<field>`); `@crdt @cursor`
-   *  fields hold a `{ state, cursors }` object so the snapshot lives at
-   *  `<field>.state` next to per-session cursor blobs. */
-  private statePath(): string {
-    return this.cursorsEnabled ? `${this.fieldName}.state` : this.fieldName;
+  /** Whether the document holds anything yet (local state or edits). */
+  hasContent(): boolean {
+    return this.doc.oplogVersion().length() > 0;
   }
 
-  /** Mirror the LoroDoc snapshot into the parent row locally. Runs on
-   *  every local update and every remote import so reloads (online or
-   *  offline) see the freshest content immediately. Failures are
-   *  swallowed — a stale local write must never block user input. */
-  private async persistLocal(): Promise<void> {
-    if (!this.local || !this.recordId) return;
-    try {
-      await this.local.query(
-        `UPDATE $id SET ${this.statePath()} = $state RETURN NONE;`,
-        { id: parseRecordIdString(this.recordId), state: this.exportSnapshot() }
-      );
-    } catch (e) {
-      this.logger?.debug(
-        { error: e, Category: 'sp00ky-client::CrdtField::persistLocal' },
-        'Local CRDT persist failed (best-effort)'
-      );
-    }
+  /** Publish this session's presence (an `EphemeralStore` encoding, e.g. the
+   *  editor's cursor). No-op unless the field is `@cursor`. */
+  pushCursorState(encoded: Uint8Array): void {
+    if (this.cursorsEnabled) this.host.pushPresence(encoded);
   }
 
-  private async pushToRemote(): Promise<void> {
-    if (!this.remote || !this.recordId) return;
-    this.lastPushTime = Date.now();
-    try {
-      // The UPDATE on the parent fires the parent table's LIVE feed,
-      // so cross-browser receivers see this change directly in the LIVE
-      // payload — no separate `_00_rv` bump or sidecar UPSERT.
-      await this.remote.query(
-        `UPDATE $id SET ${this.statePath()} = $state RETURN NONE;`,
-        { id: parseRecordIdString(this.recordId), 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'
-      );
-      // Bounded retry. Offline first-loads will exhaust this and stop
-      // hammering; the next user keystroke (or the next time a remote
-      // event lands once we're back online) will kick off another push.
-      if (this.pushRetryCount < 2) {
-        this.pushRetryCount++;
-        this.scheduleRemotePush();
+  /** Called with every other session's presence blob. A blob that arrives
+   *  before the editor sets this is replayed when it does. */
+  set onCursorUpdate(cb: ((data: Uint8Array) => void) | null) {
+    this._onCursorUpdate = cb;
+    if (cb && this.pendingCursorUpdate) {
+      const data = this.pendingCursorUpdate;
+      this.pendingCursorUpdate = null;
+      try {
+        cb(data);
+      } catch {
+        /* the editor logs its own apply failures */
       }
     }
   }
-}
 
-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;
+  get onCursorUpdate() {
+    return this._onCursorUpdate;
   }
-  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);
+  /** @internal Deliver one remote presence blob. */
+  deliverPresence(data: Uint8Array): void {
+    if (this._onCursorUpdate) this._onCursorUpdate(data);
+    else this.pendingCursorUpdate = data;
   }
-  return Buffer.from(bytes).toString('base64');
 }