@spooky-sync/core 0.0.1-canary.7 → 0.0.1-canary.70

package/dist/index.d.ts

@@ -1,132 +1,10 @@
+import { A as Logger$1, C as RunOptions, D as StoreType, E as Sp00kyQueryResultPromise, M as EventSystem, O as TimingPhase, S as RegistrationTimings, T as Sp00kyQueryResult, _ as QueryTimeToLive, a as MutationCallback, b as RecordVersionArray, c as PersistenceClient, d as QueryConfig, f as QueryConfigRecord, g as QueryStatusCallback, h as QueryStatus, i as MATERIALIZATION_SAMPLE_WINDOW, j as EventDefinition, k as UpdateOptions, l as PhaseStat, m as QueryState, n as EventSubscriptionOptions, o as MutationEvent, p as QueryHash, r as Level, s as MutationEventType, t as DebounceOptions, u as PinoTransmit, v as QueryTimings, w as Sp00kyConfig, x as RecordVersionDiff, y as QueryUpdateCallback } from "./types.js";
 import * as surrealdb0 from "surrealdb";
-import { Duration, RecordId, Surreal, SurrealTransaction } from "surrealdb";
-import { AccessDefinition, BackendNames, BackendRoutes, BucketNames, ColumnSchema, GetTable, QueryBuilder, QueryOptions, RecordId as RecordId$1, RoutePayload, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap } from "@spooky-sync/query-builder";
-import { Level, Level as Level$1, Logger } from "pino";
+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/events/index.d.ts
-/**
- * Utility type to define the payload structure of an event.
- * If the payload type P is never, it defines payload as undefined.
- */
-type EventPayloadDefinition<P> = [P] extends [never] ? {
-  payload: undefined;
-} : {
-  payload: P;
-};
-/**
- * Defines the structure of an event with a specific type and payload.
- * @template T The string literal type of the event.
- * @template P The type of the event payload.
- */
-type EventDefinition<T extends string, P> = {
-  type: T;
-} & EventPayloadDefinition<P>;
-/**
- * A map of event types to their definitions.
- * Keys are event names, values are EventDefinitions.
- */
-type EventTypeMap = Record<string, EventDefinition<any, unknown> | EventDefinition<any, never>>;
-/**
- * Options for pushing/emitting events.
- */
-interface PushEventOptions {
-  /** Configuration for debouncing the event. */
-  debounced?: {
-    key: string;
-    delay: number;
-  };
-}
-/**
- * Extracts the full Event object type from the map for a given key.
- */
-type Event<E extends EventTypeMap, T extends EventType<E>> = E[T];
-/**
- * Extracts the payload type from the map for a given key.
- */
-type EventPayload<E extends EventTypeMap, T extends EventType<E>> = E[T]['payload'];
-/**
- * Array of available event type keys.
- */
-type EventTypes<E extends EventTypeMap> = (keyof E)[];
-/**
- * Represents a valid key (event name) from the EventTypeMap.
- */
-type EventType<E extends EventTypeMap> = keyof E;
-/**
- * Function signature for an event handler.
- */
-type EventHandler<E extends EventTypeMap, T extends EventType<E>> = (event: Event<E, T>) => void;
-/**
- * Options when subscribing to an event.
- */
-type EventSubscriptionOptions$1 = {
-  /** If true, the handler will be called immediately with the last emitted event of this type (if any). */
-  immediately?: boolean;
-  /** If true, the subscription will be automatically removed after the first event is handled. */
-  once?: boolean;
-};
-/**
- * A type-safe event system that handles subscription, emission (including debouncing), and buffering of events.
- * @template E The EventTypeMap defining all supported events.
- */
-declare class EventSystem<E extends EventTypeMap> {
-  private _eventTypes;
-  private subscriberId;
-  private isProcessing;
-  private buffer;
-  private subscribers;
-  private subscribersTypeMap;
-  private lastEvents;
-  private debouncedEvents;
-  constructor(_eventTypes: EventTypes<E>);
-  get eventTypes(): EventTypes<E>;
-  /**
-   * Subscribes a handler to a specific event type.
-   * @param type The event type to subscribe to.
-   * @param handler The function to call when the event occurs.
-   * @param options Subscription options (once, immediately).
-   * @returns A subscription ID that can be used to unsubscribe.
-   */
-  subscribe<T extends EventType<E>>(type: T, handler: EventHandler<E, T>, options?: EventSubscriptionOptions$1): number;
-  /**
-   * Subscribes a handler to multiple event types.
-   * @param types An array of event types to subscribe to.
-   * @param handler The function to call when any of the events occur.
-   * @param options Subscription options.
-   * @returns An array of subscription IDs.
-   */
-  subscribeMany<T extends EventType<E>>(types: T[], handler: EventHandler<E, T>, options?: EventSubscriptionOptions$1): number[];
-  /**
-   * Unsubscribes a specific subscription by ID.
-   * @param id The subscription ID returned by subscribe().
-   * @returns True if the subscription was found and removed, false otherwise.
-   */
-  unsubscribe(id: number): boolean;
-  /**
-   * Emits an event with the given type and payload.
-   * @param type The type of event to emit.
-   * @param payload The data associated with the event.
-   */
-  emit<T extends EventType<E>, P extends EventPayload<E, T>>(type: T, payload: P): void;
-  /**
-   * Adds a fully constructed event object to the system.
-   * Similar to emit, but takes the full event object directly.
-   * Supports debouncing if options are provided.
-   * @param event The event object.
-   * @param options Options for the event push (e.g., debouncing).
-   */
-  addEvent<T extends EventType<E>>(event: Event<E, T>, options?: PushEventOptions): void;
-  private handleDebouncedEvent;
-  private scheduleProcessing;
-  private processEvents;
-  private dequeue;
-  private setLastEvent;
-  private broadcastEvent;
-}
-//#endregion
-//#region src/services/logger/index.d.ts
-type Logger$1 = Logger;
-//#endregion
 //#region src/services/database/events/index.d.ts
 declare const DatabaseEventTypes: {
   readonly LocalQuery: "DATABASE_LOCAL_QUERY";
@@ -154,13 +32,13 @@ interface SealedQuery<T = void> {
 //#endregion
 //#region src/services/database/database.d.ts
 declare abstract class AbstractDatabaseService {
-  protected client: Surreal;
+  protected client: Surreal$1;
   protected logger: Logger$1;
   protected events: DatabaseEventSystem;
   protected abstract eventType: typeof DatabaseEventTypes.LocalQuery | typeof DatabaseEventTypes.RemoteQuery;
-  constructor(client: Surreal, logger: Logger$1, events: DatabaseEventSystem);
+  constructor(client: Surreal$1, logger: Logger$1, events: DatabaseEventSystem);
   abstract connect(): Promise<void>;
-  getClient(): Surreal;
+  getClient(): Surreal$1;
   getEvents(): DatabaseEventSystem;
   tx(): Promise<SurrealTransaction>;
   private queryQueue;
@@ -176,17 +54,33 @@ declare abstract class AbstractDatabaseService {
 declare class LocalDatabaseService extends AbstractDatabaseService {
   private config;
   protected eventType: "DATABASE_LOCAL_QUERY";
-  constructor(config: SpookyConfig<any>['database'], logger: Logger$1);
-  getConfig(): SpookyConfig<any>['database'];
+  constructor(config: Sp00kyConfig<any>['database'], logger: Logger$1);
+  getConfig(): Sp00kyConfig<any>['database'];
   connect(): Promise<void>;
+  private unloadCloseRegistered;
+  /**
+   * Close the local DB on page unload so the SurrealDB-WASM worker releases its
+   * IndexedDB connection cleanly. Without this, the previous page's connection
+   * lingers; the next load's `client.connect` opens the store but the first
+   * write transaction in `client.use` hits an "IndexedDB error" — which then
+   * (mis)triggered the corrupt-store recovery and WIPED the cache on every
+   * reload, making warm loads as slow as cold ones. `pagehide` is the reliable
+   * unload signal (fires on bfcache + normal navigation); `close()` is async but
+   * the WASM worker initiates the IndexedDB connection teardown synchronously.
+   */
+  private registerUnloadClose;
+  private openStore;
 }
+/** True for the SurrealDB-WASM error raised when its IndexedDB-backed key-value
+ *  store can't be opened (corrupt / version-incompatible / blocked). Exported
+ *  for unit testing the error-message match. */
 //#endregion
 //#region src/services/database/remote.d.ts
 declare class RemoteDatabaseService extends AbstractDatabaseService {
   private config;
   protected eventType: "DATABASE_REMOTE_QUERY";
-  constructor(config: SpookyConfig<any>['database'], logger: Logger$1);
-  getConfig(): SpookyConfig<any>['database'];
+  constructor(config: Sp00kyConfig<any>['database'], logger: Logger$1);
+  getConfig(): Sp00kyConfig<any>['database'];
   connect(): Promise<void>;
   signin(params: any): Promise<any>;
   signup(params: any): Promise<any>;
@@ -194,38 +88,17 @@ declare class RemoteDatabaseService extends AbstractDatabaseService {
   invalidate(): Promise<void>;
 }
 //#endregion
-//#region src/modules/sync/queue/queue-up.d.ts
-type CreateEvent = {
-  type: 'create';
-  mutation_id: RecordId;
-  record_id: RecordId;
-  data: Record<string, unknown>;
-  record?: Record<string, unknown>;
-  tableName?: string;
-  options?: PushEventOptions;
-};
-type UpdateEvent = {
-  type: 'update';
-  mutation_id: RecordId;
-  record_id: RecordId;
-  data: Record<string, unknown>;
-  record?: Record<string, unknown>;
-  beforeRecord?: Record<string, unknown>;
-  options?: PushEventOptions;
-};
-type DeleteEvent = {
-  type: 'delete';
-  mutation_id: RecordId;
-  record_id: RecordId;
-  options?: PushEventOptions;
-};
-type UpEvent = CreateEvent | UpdateEvent | DeleteEvent;
-//#endregion
 //#region src/services/stream-processor/wasm-types.d.ts
 interface WasmStreamUpdate {
   query_id: string;
   result_hash: string;
   result_data: RecordVersionArray;
+  timing_store_apply_ms?: number;
+  timing_circuit_step_ms?: number;
+  timing_transform_ms?: number;
+  timing_parse_ms?: number;
+  timing_plan_ms?: number;
+  timing_snapshot_ms?: number;
 }
 //#endregion
 //#region src/services/stream-processor/index.d.ts
@@ -246,6 +119,25 @@ interface StreamUpdate {
   queryHash: string;
   localArray: RecordVersionArray;
   op?: 'CREATE' | 'UPDATE' | 'DELETE';
+  /**
+   * End-to-end ingest latency for the WASM call that produced this update,
+   * in milliseconds. Populated by StreamProcessorService.ingest. Undefined
+   * for the initial register_view snapshot.
+   */
+  materializationTimeMs?: number;
+  /** SSP internal sub-phase timings (ms) for this ingest, from the WASM binding. */
+  storeApplyMs?: number;
+  circuitStepMs?: number;
+  transformMs?: number;
+  /**
+   * One-shot registration timings (ms). Only set on the StreamUpdate returned
+   * by `registerQueryPlan` (the register_view snapshot), not on ingest updates.
+   */
+  registration?: {
+    parseMs: number;
+    planMs: number;
+    snapshotMs: number;
+  };
 }
 type StreamProcessorEvents = {
   stream_update: EventDefinition<'stream_update', StreamUpdate[]>;
@@ -265,6 +157,8 @@ declare class StreamProcessorService {
   private processor;
   private isInitialized;
   private receivers;
+  private batching;
+  private batchBuffer;
   constructor(events: EventSystem<StreamProcessorEvents>, db: LocalDatabaseService, persistenceClient: PersistenceClient, logger: Logger);
   /**
    * Add a receiver for stream updates.
@@ -272,12 +166,53 @@ declare class StreamProcessorService {
    */
   addReceiver(receiver: StreamUpdateReceiver): void;
   private notifyUpdates;
+  private dispatchUpdates;
+  /**
+   * Ingest a batch of record changes as a single bulk operation, firing only
+   * one coalesced `StreamUpdate` per affected query once every record has been
+   * ingested (instead of one update per record). Use this whenever multiple
+   * records land at once — e.g. sync fetching N missing rows — so a list query
+   * re-runs and the UI re-renders once for the whole batch rather than
+   * row-by-row.
+   *
+   * Internally opens a coalescing window, ingests each record, then flushes;
+   * processor state is persisted once for the whole batch. No-op for an empty
+   * batch.
+   */
+  ingestMany(records: Array<{
+    table: string;
+    op: 'CREATE' | 'UPDATE' | 'DELETE';
+    id: string;
+    record: any;
+  }>): void;
+  /**
+   * Open a coalescing window. While open, the per-record stream updates
+   * emitted by `ingest` are buffered (one entry per queryHash) instead of
+   * dispatched. Always paired with `flushCoalescing()` in a try/finally by
+   * `ingestMany` so the window always closes — otherwise the processor stays
+   * stuck buffering forever.
+   *
+   * No-op if a window is already open (nested batches aren't expected here).
+   */
+  private beginCoalescing;
+  /**
+   * Close the coalescing window and flush: dispatch one coalesced
+   * `StreamUpdate` per buffered queryHash, then persist processor state once
+   * for the whole batch (instead of once per ingest).
+   */
+  private flushCoalescing;
   /**
    * Initialize the WASM module and processor.
    * This must be called before using other methods.
    */
   init(): Promise<void>;
   loadState(): Promise<void>;
+  /**
+   * Seed per-table `select` permission predicates ({ [table]: whereText }).
+   * Must run after the processor exists and before any `register_view`, else
+   * non-`_00_` tables are default-denied and registration fails.
+   */
+  setPermissions(permissions: Record<string, string>): void;
   saveState(): Promise<void>;
   /**
    * Ingest a record change into the processor.
@@ -297,205 +232,6 @@ declare class StreamProcessorService {
   private normalizeValue;
 }
 //#endregion
-//#region src/types.d.ts
-/**
- * The type of storage backend to use for the local database.
- * - 'memory': In-memory storage (transient).
- * - 'indexeddb': IndexedDB storage (persistent).
- */
-type StoreType = 'memory' | 'indexeddb';
-/**
- * Interface for a custom persistence client.
- * Allows providing a custom storage mechanism for the local database.
- */
-interface PersistenceClient {
-  /**
-   * Sets a value in the storage.
-   * @param key The key to set.
-   * @param value The value to store.
-   */
-  set<T>(key: string, value: T): Promise<void>;
-  /**
-   * Gets a value from the storage.
-   * @param key The key to retrieve.
-   * @returns The stored value or null if not found.
-   */
-  get<T>(key: string): Promise<T | null>;
-  /**
-   * Removes a value from the storage.
-   * @param key The key to remove.
-   */
-  remove(key: string): Promise<void>;
-}
-/**
- * Supported Time-To-Live (TTL) values for cached queries.
- * Format: number + unit (m=minutes, h=hours, d=days).
- */
-type QueryTimeToLive = '1m' | '5m' | '10m' | '15m' | '20m' | '25m' | '30m' | '1h' | '2h' | '3h' | '4h' | '5h' | '6h' | '7h' | '8h' | '9h' | '10h' | '11h' | '12h' | '1d';
-/**
- * Result object returned when a query is registered or executed.
- */
-interface SpookyQueryResult {
-  /** The unique hash identifier for the query. */
-  hash: string;
-}
-type SpookyQueryResultPromise = Promise<SpookyQueryResult>;
-interface EventSubscriptionOptions {
-  priority?: number;
-}
-/**
- * Configuration options for the Spooky client.
- * @template S The schema structure type.
- */
-interface SpookyConfig<S extends SchemaStructure> {
-  /** Database connection configuration. */
-  database: {
-    /** The SurrealDB endpoint URL. */
-    endpoint?: string;
-    /** The namespace to use. */
-    namespace: string;
-    /** The database name. */
-    database: string;
-    /** The local store type implementation. */
-    store?: StoreType;
-    /** Authentication token. */
-    token?: string;
-  };
-  /** Unique client identifier. If not provided, one will be generated. */
-  clientId?: string;
-  /** The schema definition. */
-  schema: S;
-  /** The compiled SURQL schema string. */
-  schemaSurql: string;
-  /** Logging level. */
-  logLevel: Level$1;
-  /**
-   * Persistence client to use.
-   * Can be a custom implementation, 'surrealdb' (default), or 'localstorage'.
-   */
-  persistenceClient?: PersistenceClient | 'surrealdb' | 'localstorage';
-  /** OpenTelemetry collector endpoint for telemetry data. */
-  otelEndpoint?: string;
-  /**
-   * Debounce time in milliseconds for stream updates.
-   * Defaults to 100ms.
-   */
-  streamDebounceTime?: number;
-}
-type QueryHash = string;
-type RecordVersionArray = Array<[string, number]>;
-/**
- * Represents the difference between two record version sets.
- * Used for synchronizing local and remote states.
- */
-interface RecordVersionDiff {
-  /** List of records added. */
-  added: Array<{
-    id: RecordId$1<string>;
-    version: number;
-  }>;
-  /** List of records updated. */
-  updated: Array<{
-    id: RecordId$1<string>;
-    version: number;
-  }>;
-  /** List of record IDs removed. */
-  removed: RecordId$1<string>[];
-}
-/**
- * Configuration for a specific query instance.
- * Stores metadata about the query's state, parameters, and versioning.
- */
-interface QueryConfig {
-  /** The unique ID of the query config record. */
-  id: RecordId$1<string>;
-  /** The SURQL query string. */
-  surql: string;
-  /** Parameters used in the query. */
-  params: Record<string, any>;
-  /** The version array representing the local state of results. */
-  localArray: RecordVersionArray;
-  /** The version array representing the remote (server) state of results. */
-  remoteArray: RecordVersionArray;
-  /** Time-To-Live for this query. */
-  ttl: QueryTimeToLive;
-  /** Timestamp when the query was last accessed/active. */
-  lastActiveAt: Date;
-  /** The name of the table this query targets (if applicable). */
-  tableName: string;
-}
-type QueryConfigRecord = QueryConfig & {
-  id: string;
-};
-/**
- * Internal state of a live query.
- */
-interface QueryState {
-  /** The configuration for this query. */
-  config: QueryConfig;
-  /** The current cached records for this query. */
-  records: Record<string, any>[];
-  /** Timer for TTL expiration. */
-  ttlTimer: NodeJS.Timeout | null;
-  /** TTL duration in milliseconds. */
-  ttlDurationMs: number;
-  /** Number of times the query has been updated. */
-  updateCount: number;
-}
-type QueryUpdateCallback = (records: Record<string, any>[]) => void;
-type MutationCallback = (mutations: UpEvent[]) => void;
-type MutationEventType = 'create' | 'update' | 'delete';
-/**
- * Represents a mutation event (create, update, delete) to be synchronized.
- */
-interface MutationEvent {
-  /** Example: 'create', 'update', or 'delete'. */
-  type: MutationEventType;
-  /** unique id of the mutation */
-  mutation_id: RecordId$1<string>;
-  /** The ID of the record being mutated. */
-  record_id: RecordId$1<string>;
-  /** The data payload for create/update operations. */
-  data?: any;
-  /** The full record data (optional context). */
-  record?: any;
-  /** Options for the mutation event (e.g., debounce settings). */
-  options?: PushEventOptions;
-  /** Timestamp when the event was created. */
-  createdAt: Date;
-}
-/**
- * Options for run operations.
- */
-interface RunOptions {
-  assignedTo?: string;
-  max_retries?: number;
-  retry_strategy?: 'linear' | 'exponential';
-}
-/**
- * Options for update operations.
- */
-interface UpdateOptions {
-  /**
-   * Debounce configuration for the update.
-   * If boolean, enables default debounce behavior.
-   */
-  debounced?: boolean | DebounceOptions;
-}
-/**
- * Configuration options for debouncing updates.
- */
-interface DebounceOptions {
-  /**
-   * The key to use for debouncing.
-   * - 'recordId': Debounce based on the specific record ID. WARNING: IT WILL ONLY ACCEPT THE LATEST CHANGE AND DOES *NOT* MERGE THE PREVIOUS ONCES. IF YOU ARE UNSURE JUST USE 'recordId_x_fields'.
-   * - 'recordId_x_fields': Debounce based on record ID and specific fields.
-   */
-  key?: 'recordId' | 'recordId_x_fields';
-  /** The debounce delay in milliseconds. */
-  delay?: number;
-}
-//#endregion
 //#region src/modules/auth/events/index.d.ts
 declare const AuthEventTypes: {
   readonly AuthStateChanged: "AUTH_STATE_CHANGED";
@@ -543,7 +279,151 @@ 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/spooky.d.ts
+//#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 local;
+  private remote;
+  private recordId;
+  private sessionId;
+  private unsubscribe;
+  private lastPushTime;
+  private lastCursorPushTime;
+  private loadedFromCrdt;
+  private pushRetryCount;
+  private logger;
+  private cursorsEnabled;
+  /** 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;
+  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, cursorsEnabled: boolean, initialState?: Uint8Array, logger?: Logger$1 | null);
+  getDoc(): LoroDoc;
+  /** Whether the LoroDoc was loaded from saved CRDT state */
+  hasContent(): boolean;
+  startSync(local: LocalDatabaseService, remote: RemoteDatabaseService, recordId: string, sessionId: string, debounceMs: number): void;
+  stopSync(): void;
+  importRemote(state: Uint8Array): void;
+  exportSnapshot(): Uint8Array;
+  /** 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. */
+  pushCursorState(encoded: Uint8Array): Promise<void>;
+  /** Import remote cursor state (called by CrdtManager from LIVE SELECT) */
+  importRemoteCursor(base64State: string): void;
+  private scheduleRemotePush;
+  /** 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;
+  /** 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 persistLocal;
+  private pushToRemote;
+}
+//#endregion
+//#region src/modules/crdt/index.d.ts
+/**
+ * CrdtManager manages active CrdtField instances and their sync channels.
+ *
+ * Collaborative state lives in two dedicated tables (defined in
+ * `apps/cli/src/meta_tables_remote.surql`):
+ *   - `_00_crdt`   { record_id, field, state } — one row per (record, field)
+ *   - `_00_cursor` { record_id, session_id, field, state } — one row per
+ *                    (record, session, field)
+ *
+ * Splitting them off the parent row is what makes offline edits mergeable:
+ * each (record, field) gets its own row, so concurrent offline writes don't
+ * collide on the parent's last-write-wins semantics.
+ *
+ * Cross-browser delivery still rides the parent table's existing LIVE feed
+ * to avoid SurrealDB v3 LIVE bugs around dereference-based permission rules
+ * (issues 3602, 4026). On every meta UPSERT the writer also bumps the
+ * parent's `_00_rv` (a no-op assignment); that fires the parent's LIVE
+ * feed, and the receiver pulls the matching `_00_crdt` / `_00_cursor` rows
+ * via subquery. Permission inheritance happens server-side via
+ * `record_id.id != NONE` (SELECT) and `fn::can_update_record` (UPDATE).
+ */
+declare class CrdtManager {
+  private schema;
+  private local;
+  private remote;
+  private debounceMs;
+  private fields;
+  private liveByTable;
+  private pendingLive;
+  private logger;
+  private sessionId;
+  constructor(schema: SchemaStructure, local: LocalDatabaseService, remote: RemoteDatabaseService, logger: Logger$1, debounceMs?: number);
+  /** Set the session id that scopes this client's cursor entries. Must be
+   *  called before `open()` for cursors to be pushed under a stable key.
+   *  Passed in from `sp00ky.ts` at boot (it already fetches `session::id()`
+   *  for the data-module salt). */
+  setSessionId(sessionId: string): void;
+  /**
+   * 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;
+  /** Ensure a single `LIVE SELECT * FROM <table>` is running, shared across
+   *  every open CrdtField on `table`. */
+  private ensureTableSubscription;
+  /** Apply a parent-row payload from a non-LIVE source (e.g. the
+   *  list_ref-driven sync engine, when the cross-user LIVE on the
+   *  parent table is filtered out by the SurrealDB cross-session
+   *  permission gap). Same semantics as the internal `dispatchRow`. */
+  applyRow(table: string, row: Record<string, unknown>): void;
+  /** Dispatch a parent-row LIVE event to every open CrdtField on that
+   *  record. Each open field reads its slice of the row directly — the
+   *  CRDT snapshot is a column on the parent now, so there is no
+   *  follow-up subquery. */
+  private dispatchRow;
+  /** One-shot remote fetch for a row whose CRDT field hasn't synced
+   *  locally yet (fresh device, memory-backed local DB after reload, …).
+   *  Used by `open()` when the local read came up empty. Subsequent
+   *  cross-browser updates ride `dispatchRow` via the parent LIVE feed. */
+  private fetchAndDispatchRow;
+  /** Schema lookup: does `<table>.<field>` carry a `@cursor` annotation?
+   *  Determines the on-disk shape (plain snapshot vs. `{ state, cursors }`). */
+  private fieldHasCursor;
+  /** Pull the LoroDoc snapshot bytes out of a row slice. For `@crdt`-only
+   *  the slice IS the snapshot (Uint8Array); for `@crdt @cursor` it's
+   *  `{ state, cursors }` where `state` carries the snapshot bytes. */
+  private extractSnapshot;
+  private killTableSubscription;
+  private makeKey;
+  /**
+   * Throws if `<table>.<field>` is not annotated `@crdt` in the schema. Catches
+   * typos, removed annotations, and stale schema codegen at the call site instead
+   * of silently producing a non-CRDT writer.
+   */
+  private assertCrdtField;
+}
+//#endregion
+//#region src/sp00ky.d.ts
 declare class BucketHandle {
   private bucketName;
   private remote;
@@ -557,7 +437,7 @@ declare class BucketHandle {
   rename(sourcePath: string, targetPath: string): Promise<void>;
   list(prefix?: string): Promise<string[]>;
 }
-declare class SpookyClient<S extends SchemaStructure> {
+declare class Sp00kyClient<S extends SchemaStructure> {
   private config;
   private local;
   private remote;
@@ -567,14 +447,21 @@ declare class SpookyClient<S extends SchemaStructure> {
   private dataModule;
   private sync;
   private devTools;
+  private crdtManager;
   private logger;
   auth: AuthService<S>;
   streamProcessor: StreamProcessorService;
-  get remoteClient(): Surreal;
-  get localClient(): Surreal;
+  get remoteClient(): surrealdb0.Surreal;
+  get localClient(): surrealdb0.Surreal;
   get pendingMutationCount(): number;
+  /** Number of times the initial list_ref LIVE subscription retried on
+   *  the most recent `setCurrentUserId` call. 0 when the SSP's
+   *  pre-emptive user-table creation got there first; >0 when LIVE
+   *  registration hit a "table not found" race. Exposed so the e2e
+   *  suite can guard the pre-emptive path against regression. */
+  get liveRetryCount(): number;
   subscribeToPendingMutations(cb: (count: number) => void): () => void;
-  constructor(config: SpookyConfig<S>);
+  constructor(config: Sp00kyConfig<S>);
   /**
    * Setup direct callbacks instead of event subscriptions
    */
@@ -582,13 +469,46 @@ declare class SpookyClient<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 the parent table for real-time sync;
+   * incoming events trigger a subquery fetch of `_00_crdt` / `_00_cursor`.
+   */
+  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, SpookyQueryResultPromise>;
+  query<Table extends TableNames<S>>(table: Table, options: QueryOptions<TableModel<GetTable<S, Table>>, false>, ttl?: QueryTimeToLive): QueryBuilder<S, Table, Sp00kyQueryResultPromise>;
   private initQuery;
   queryRaw(sql: string, params: Record<string, any>, ttl: QueryTimeToLive): Promise<string>;
   subscribe(queryHash: string, callback: (records: Record<string, any>[]) => void, options?: {
     immediate?: boolean;
   }): Promise<() => void>;
+  /**
+   * Opt-in eager teardown for a query whose last subscriber has gone away
+   * (e.g. a viewport-windowed list cancelling an off-screen window). No-op
+   * while any subscriber remains. Tears down the remote `_00_query` view +
+   * local WASM view instead of waiting for the TTL sweep. Default behavior
+   * (no call here) keeps the view resident for cheap re-subscription.
+   */
+  deregisterQuery(queryHash: string): void;
+  /**
+   * Subscribe to a query's fetch-status changes (idle/fetching). With
+   * `{ immediate: true }` the callback fires synchronously with the current
+   * status. Powers the `useQuery` hook's `isFetching()` accessor.
+   */
+  subscribeQueryStatus(queryHash: string, callback: QueryStatusCallback, options?: {
+    immediate?: boolean;
+  }): () => void;
+  /**
+   * Report the frontend processing time (ms) a client framework spent applying
+   * an update for a query (e.g. `useQuery`'s `reconcile()`), so DevTools/MCP can
+   * surface the "frontend" phase of the per-query timing breakdown.
+   */
+  reportFrontendTiming(queryHash: string, ms: number): void;
   run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(backend: B, path: R, payload: RoutePayload<S, B, R>, options?: RunOptions): Promise<void>;
   bucket<B extends BucketNames<S>>(name: B): BucketHandle;
   create(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
@@ -597,15 +517,25 @@ declare class SpookyClient<S extends SchemaStructure> {
   }>;
   delete(table: string, id: string): Promise<void>;
   useRemote<T>(fn: (client: Surreal) => Promise<T> | T): Promise<T>;
-  private persistClientId;
-  private loadOrGenerateClientId;
+  /**
+   * Fetch SurrealDB's `session::id()` as a string. Used as a salt for
+   * query-id hashing so two sessions for the same user get distinct
+   * `_00_query` rows. Returns empty string if the query fails (we still
+   * boot, just without session scoping for IDs).
+   */
+  private fetchSessionId;
 }
 //#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, type Level, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryTimeToLive, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RunOptions, SpookyClient, SpookyConfig, SpookyQueryResult, SpookyQueryResultPromise, StoreType, UpdateOptions, createAuthEventSystem, fileToUint8Array };
+export { AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, Level, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StoreType, TimingPhase, UpdateOptions, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };