@spooky-sync/core 0.0.1-canary.21 → 0.0.1-canary.210

package/src/modules/cache/index.ts

@@ -1,13 +1,14 @@
-import { LocalDatabaseService } from '../../services/database/index';
-import {
+import type { LocalStore } from '../../services/database/index';
+import { StaleEpochError } from '../../services/database/index';
+import type {
   StreamProcessorService,
   StreamUpdate,
   StreamUpdateReceiver,
 } from '../../services/stream-processor/index';
-import { Logger } from '../../services/logger/index';
+import type { Logger } from '../../services/logger/index';
 import { parseRecordIdString, encodeRecordId, surql } from '../../utils/index';
-import { CacheRecord, QueryConfig } from './types';
-import { RecordVersionArray } from '../../types';
+import type { CacheRecord, QueryConfig } from './types';
+import type { RecordVersionArray } from '../../types';
 
 export * from './types';
 
@@ -17,13 +18,29 @@ export * from './types';
  * Single responsibility: Handle all local storage operations and DBSP ingestion.
  * This module acts as the bridge between data operations and persistence.
  */
+/** One ingested change, in exactly the shape `ingestMany` consumes. Shared
+ *  with the tabs protocol so a leader can relay its ingests to followers. */
+export interface CacheIngestTuple {
+  table: string;
+  op: 'CREATE' | 'UPDATE' | 'DELETE';
+  id: string;
+  record: Record<string, unknown>;
+}
+
 export class CacheModule implements StreamUpdateReceiver {
   private logger: Logger;
   private streamUpdateCallback: (update: StreamUpdate) => void;
   private versionLookups: Record<string, number> = {};
+  /** Shared-tabs leader: fan every committed ingest out to follower circuits.
+   *  Fired AFTER the local tx (the rows are already in the shared store, so a
+   *  follower only needs the circuit feed). A follower relays its own
+   *  mutations to the leader the same way, see {@link setIngestRelay}. */
+  private ingestRelay: ((tuples: CacheIngestTuple[]) => void) | null = null;
+  /** See {@link setIngestRelay}. */
+  private relayLocalWritesOnly = false;
 
   constructor(
-    private local: LocalDatabaseService,
+    private local: LocalStore,
     private streamProcessor: StreamProcessorService,
     streamUpdateCallback: (update: StreamUpdate) => void,
     logger: Logger
@@ -43,17 +60,69 @@ export class CacheModule implements StreamUpdateReceiver {
       {
         queryHash: update.queryHash,
         arrayLength: update.localArray?.length,
-        Category: 'spooky-client::CacheModule::onStreamUpdate',
+        Category: 'sp00ky-client::CacheModule::onStreamUpdate',
       },
       'Stream update received'
     );
     this.streamUpdateCallback(update);
   }
 
+  /**
+   * Fan every committed ingest out to the other tabs. The leader relays
+   * everything (its sync fetches are the only copy the followers get). A
+   * follower relays with `localWritesOnly`: just the mutation path, which is
+   * the only thing it knows that the leader does not. Its sync-fetched
+   * batches are the leader's data coming back and must not be re-broadcast,
+   * or every follower registration would fan its whole working set to
+   * every tab.
+   */
+  setIngestRelay(
+    cb: ((tuples: CacheIngestTuple[]) => void) | null,
+    opts: { localWritesOnly?: boolean } = {}
+  ): void {
+    this.ingestRelay = cb;
+    this.relayLocalWritesOnly = opts.localWritesOnly === true;
+  }
+
+  /**
+   * Shared-tabs follower: feed relayed tuples into THIS tab's circuit only.
+   * The rows are already in the shared store (the leader wrote them), so no
+   * local write happens here; the normal chain then runs: SSP -> stream update
+   * -> DataModule debounce -> materializeRecords (re-reads via the port
+   * transport) -> this tab's subscriptions fire with this tab's hashes.
+   */
+  applyRelayedIngest(tuples: CacheIngestTuple[]): void {
+    for (const t of tuples) {
+      const rv = (t.record as { _00_rv?: number } | undefined)?._00_rv;
+      if (t.op === 'DELETE') delete this.versionLookups[t.id];
+      else if (typeof rv === 'number') this.versionLookups[t.id] = rv;
+    }
+    this.streamProcessor.ingestMany(tuples as Parameters<StreamProcessorService['ingestMany']>[0]);
+  }
+
   public lookup(recordId: string): number {
     return this.versionLookups[recordId] ?? 0;
   }
 
+  /**
+   * Seed the version memo from rows the circuit was primed with out of the
+   * local store, so the first post-reload sync diff does not re-download
+   * bodies the browser already has. Only rows the prime actually put into the
+   * circuit belong here: a memo entry with no circuit row would make the diff
+   * flag the id forever while nothing ever fetches it.
+   */
+  public primeVersions(entries: [string, number][]): void {
+    for (const [id, rv] of entries) {
+      if (rv > (this.versionLookups[id] ?? 0)) this.versionLookups[id] = rv;
+    }
+  }
+
+  /** Drop the version cache on a bucket switch — a stale version would make
+   *  the sync diff skip fetching a body the new bucket legitimately needs. */
+  public clearVersionLookups(): void {
+    this.versionLookups = {};
+  }
+
   /**
    * Save a single record to local DB and ingest into DBSP
    * Used by mutations (create/update)
@@ -70,10 +139,17 @@ export class CacheModule implements StreamUpdateReceiver {
   async saveBatch(records: CacheRecord[], skipDbInsert: boolean = false): Promise<void> {
     if (records.length === 0) return;
 
+    // Fence against bucket switches: this batch's records were derived from
+    // reads against the CURRENT store/user. If a switch lands while we await
+    // the (gated) local write, the write throws StaleEpochError and the whole
+    // batch — including the SSP ingest — is dropped: the new bucket re-syncs
+    // its own data from the server.
+    const epoch = this.local.epoch;
+
     this.logger.debug(
       {
         count: records.length,
-        Category: 'spooky-client::CacheModule::saveBatch',
+        Category: 'sp00ky-client::CacheModule::saveBatch',
       },
       'Saving record batch'
     );
@@ -85,7 +161,7 @@ export class CacheModule implements StreamUpdateReceiver {
           ...record,
           record: {
             ...record.record,
-            spooky_rv: record.version,
+            _00_rv: record.version,
           },
         };
       });
@@ -94,40 +170,69 @@ export class CacheModule implements StreamUpdateReceiver {
         const query = surql.seal<void>(
           surql.tx(
             populatedRecords.map((_, i) => {
-              return surql.upsert(`id${i}`, `content${i}`);
+              // MERGE, not REPLACE: the remote payload omits local-only
+              // fields (`_00_crdt`, `_00_cursor`) injected by the CLI's
+              // local schema, so REPLACE would wipe the persisted CRDT
+              // snapshot on every sync-down round-trip and break offline
+              // reload of formatted text.
+              return surql.upsertMerge(`id${i}`, `content${i}`);
             })
           )
         );
 
-        const params = populatedRecords.reduce(
-          (acc, record, i) => {
-            const { id, ...content } = record.record;
-            return {
-              ...acc,
-              [`id${i}`]: id,
-              [`content${i}`]: content,
-            };
-          },
-          {} as Record<string, any>
-        );
+        // Filled in place, NOT with a spread-per-iteration reduce: spreading the
+        // accumulator copies every key written so far on each record, which is
+        // O(n^2) in the batch size. On a cold start that batches thousands of
+        // rows (a game library, a player-name registry) it was the single
+        // biggest main-thread cost of the whole boot - ~36% of samples, seconds
+        // of blocking - for a loop that does no real work.
+        const params: Record<string, any> = {};
+        for (let i = 0; i < populatedRecords.length; i++) {
+          const { id, ...content } = populatedRecords[i].record;
+          params[`id${i}`] = id;
+          params[`content${i}`] = content;
+        }
 
-        await this.local.execute(query, params);
+        await this.local.execute(query, params, { epoch });
       }
 
-      // 2. Batch ingest into DBSP (use populatedRecords which has spooky_rv set)
-      for (const record of populatedRecords) {
+      // Late fence for the skipDbInsert path (no gated write above to trip on).
+      if (this.local.epoch !== epoch) throw new StaleEpochError();
+
+      // 2. Bulk ingest into DBSP (use populatedRecords which has _00_rv set).
+      // ingestMany coalesces the per-record stream updates into a single
+      // notification per affected query — the UI then updates once, after the
+      // whole batch is ingested, instead of row-by-row.
+      const versionOf = new Map<string, number>();
+      const bulk = populatedRecords.map((record) => {
         const recordId = encodeRecordId(record.record.id);
-        this.versionLookups[recordId] = record.version;
-        this.streamProcessor.ingest(record.table, record.op, recordId, record.record);
+        versionOf.set(recordId, record.version);
+        return { table: record.table, op: record.op, id: recordId, record: record.record };
+      });
+      // Memo and relay only what the circuit actually took: a chunk that
+      // failed mid-batch is neither "known" here nor fanned out to followers.
+      const ingested = this.streamProcessor.ingestMany(bulk);
+      for (const t of ingested) this.versionLookups[t.id] = versionOf.get(t.id) ?? 0;
+      // `skipDbInsert` is exactly the mutation path (the tx already wrote the
+      // row); sync-fetched batches pass false.
+      if (ingested.length > 0 && (!this.relayLocalWritesOnly || skipDbInsert)) {
+        this.ingestRelay?.(ingested as CacheIngestTuple[]);
       }
 
       this.logger.debug(
-        { count: records.length, Category: 'spooky-client::CacheModule::saveBatch' },
+        { count: records.length, Category: 'sp00ky-client::CacheModule::saveBatch' },
         'Batch saved successfully'
       );
     } catch (err) {
+      if (err instanceof StaleEpochError) {
+        this.logger.debug(
+          { count: records.length, Category: 'sp00ky-client::CacheModule::saveBatch' },
+          'Dropped batch from before a bucket switch'
+        );
+        return;
+      }
       this.logger.error(
-        { err, count: records.length, Category: 'spooky-client::CacheModule::saveBatch' },
+        { err, count: records.length, Category: 'sp00ky-client::CacheModule::saveBatch' },
         'Failed to save batch'
       );
       throw err;
@@ -137,29 +242,41 @@ export class CacheModule implements StreamUpdateReceiver {
   /**
    * Delete a record from local DB and ingest deletion into DBSP
    */
-  async delete(table: string, id: string, skipDbDelete: boolean = false): Promise<void> {
+  async delete(table: string, id: string, skipDbDelete: boolean = false, recordData: Record<string, any> = {}): Promise<void> {
     this.logger.debug(
-      { table, id, Category: 'spooky-client::CacheModule::delete' },
+      { table, id, Category: 'sp00ky-client::CacheModule::delete' },
       'Deleting record'
     );
 
+    const epoch = this.local.epoch;
     try {
       // 1. Delete from local database
       if (!skipDbDelete) {
-        await this.local.query('DELETE $id', { id: parseRecordIdString(id) });
+        await this.local.query('DELETE $id', { id: parseRecordIdString(id) }, { epoch });
       }
+      if (this.local.epoch !== epoch) throw new StaleEpochError();
 
-      // 2. Ingest deletion into DBSP
+      // 2. Ingest deletion into DBSP (pass record data so predicates can be matched)
       delete this.versionLookups[id];
-      await this.streamProcessor.ingest(table, 'DELETE', id, {});
+      this.streamProcessor.ingestMany([{ table, op: 'DELETE', id, record: recordData }]);
+      if (!this.relayLocalWritesOnly || skipDbDelete) {
+        this.ingestRelay?.([{ table, op: 'DELETE', id, record: recordData }]);
+      }
 
       this.logger.debug(
-        { table, id, Category: 'spooky-client::CacheModule::delete' },
+        { table, id, Category: 'sp00ky-client::CacheModule::delete' },
         'Record deleted successfully'
       );
     } catch (err) {
+      if (err instanceof StaleEpochError) {
+        this.logger.debug(
+          { table, id, Category: 'sp00ky-client::CacheModule::delete' },
+          'Dropped delete from before a bucket switch'
+        );
+        return;
+      }
       this.logger.error(
-        { err, table, id, Category: 'spooky-client::CacheModule::delete' },
+        { err, table, id, Category: 'sp00ky-client::CacheModule::delete' },
         'Failed to delete record'
       );
       throw err;
@@ -170,12 +287,15 @@ export class CacheModule implements StreamUpdateReceiver {
    * Register a query with DBSP to create a materialized view
    * Returns the initial result array
    */
-  registerQuery(config: QueryConfig): { localArray: RecordVersionArray } {
+  registerQuery(config: QueryConfig): {
+    localArray: RecordVersionArray;
+    registrationTimings?: { parseMs: number; planMs: number; snapshotMs: number };
+  } {
     this.logger.debug(
       {
         queryHash: config.queryHash,
         surql: config.surql,
-        Category: 'spooky-client::CacheModule::registerQuery',
+        Category: 'sp00ky-client::CacheModule::registerQuery',
       },
       'Registering query'
     );
@@ -202,15 +322,15 @@ export class CacheModule implements StreamUpdateReceiver {
         {
           queryHash: config.queryHash,
           arrayLength: update.localArray?.length,
-          Category: 'spooky-client::CacheModule::registerQuery',
+          Category: 'sp00ky-client::CacheModule::registerQuery',
         },
         'Query registered successfully'
       );
 
-      return { localArray: update.localArray };
+      return { localArray: update.localArray, registrationTimings: update.registration };
     } catch (err) {
       this.logger.error(
-        { err, queryHash: config.queryHash, Category: 'spooky-client::CacheModule::registerQuery' },
+        { err, queryHash: config.queryHash, Category: 'sp00ky-client::CacheModule::registerQuery' },
         'Failed to register query'
       );
       throw err;
@@ -222,18 +342,18 @@ export class CacheModule implements StreamUpdateReceiver {
    */
   unregisterQuery(queryHash: string): void {
     this.logger.debug(
-      { queryHash, Category: 'spooky-client::CacheModule::unregisterQuery' },
+      { queryHash, Category: 'sp00ky-client::CacheModule::unregisterQuery' },
       'Unregistering query'
     );
     try {
       this.streamProcessor.unregisterQueryPlan(queryHash);
       this.logger.debug(
-        { queryHash, Category: 'spooky-client::CacheModule::unregisterQuery' },
+        { queryHash, Category: 'sp00ky-client::CacheModule::unregisterQuery' },
         'Query unregistered successfully'
       );
     } catch (err) {
       this.logger.error(
-        { err, queryHash, Category: 'spooky-client::CacheModule::unregisterQuery' },
+        { err, queryHash, Category: 'sp00ky-client::CacheModule::unregisterQuery' },
         'Failed to unregister query'
       );
     }

package/src/modules/cache/types.ts

@@ -1,5 +1,5 @@
-import { RecordId, Duration } from 'surrealdb';
-import { QueryTimeToLive, RecordVersionArray } from '../../types';
+import type { RecordId, Duration } from 'surrealdb';
+import type { QueryTimeToLive } from '../../types';
 
 export type RecordWithId = Record<string, any> & { id: RecordId<string> };
 

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

@@ -0,0 +1,294 @@
+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';
+
+// ==================== 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 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;
+
+  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();
+    });
+  }
+
+  /**
+   * 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(); }
+  }
+
+  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;
+  }
+
+  /** 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)'
+      );
+    }
+  }
+
+  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();
+      }
+    }
+  }
+}
+
+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');
+}