@spooky-sync/core 0.0.1-canary.137 → 0.0.1-canary.138

package/dist/index.d.ts

@@ -997,7 +997,12 @@ declare class CrdtField {
    *  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);
+  /**
+   * @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(fieldName: string, cursorsEnabled: boolean, LoroDocClass: typeof LoroDoc, initialState?: Uint8Array, logger?: Logger$1 | null);
   getDoc(): LoroDoc;
   /** Whether the LoroDoc was loaded from saved CRDT state */
   hasContent(): boolean;

package/dist/index.js

@@ -1,11 +1,9 @@
 import { a as serializeRow, i as reviveRow, n as renderOrderSql, o as resolveRelations, r as renderWhereSql, s as stableKey, t as project } from "./sqlite-plan-sql.js";
 import { DateTime, Duration, RecordId, Surreal, Uuid, applyDiagnostics, createRemoteEngines } from "surrealdb";
-import { createWasmWorkerEngines } from "@surrealdb/wasm";
 import { QueryBuilder, RecordId as RecordId$1, cyrb53 } from "@spooky-sync/query-builder";
 import pino from "pino";
 import { applyPatch } from "fast-json-patch";
 import init, { Sp00kyProcessor } from "@spooky-sync/ssp-wasm";
-import { LoroDoc } from "loro-crdt";
 
 //#region src/types.ts
 /** Cap on the rolling materialization-sample window kept per query in memory. */
@@ -540,13 +538,31 @@ function bucketStoreUrl(bucketId) {
 function bucketStoreName(bucketId) {
 	return `sp00ky-${bucketId}`;
 }
-function createLocalSurrealClient(logger) {
+/** Shared codec: mirrors SurrealDB RecordId/DateTime into our own encodings. */
+const localCodecOptions = { valueDecodeVisitor(value) {
+	if (value instanceof RecordId) return encodeRecordId(value);
+	if (value instanceof DateTime) return value.toDate();
+	return value;
+} };
+/**
+* Engine-less Surreal client used as the constructor placeholder. Building this
+* pulls in NO `@surrealdb/wasm` — the ~6 MB wasm engine is deferred to
+* {@link createLocalSurrealClient}, which runs lazily in `connect`/`switchStore`.
+* `connect()` replaces `this.client` with an engine-backed client before any
+* query runs, so this bare client is never actually opened against a store.
+*/
+function createBareSurrealClient() {
+	return new Surreal({ codecOptions: localCodecOptions });
+}
+/**
+* Engine-backed client. Dynamically imports `@surrealdb/wasm` so the wasm engine
+* only enters the graph as a separate chunk fetched on first connect (module-
+* cached thereafter — `switchStore`'s await is instant).
+*/
+async function createLocalSurrealClient(logger) {
+	const { createWasmWorkerEngines } = await import("@surrealdb/wasm");
 	return new Surreal({
-		codecOptions: { valueDecodeVisitor(value) {
-			if (value instanceof RecordId) return encodeRecordId(value);
-			if (value instanceof DateTime) return value.toDate();
-			return value;
-		} },
+		codecOptions: localCodecOptions,
 		engines: applyDiagnostics(createWasmWorkerEngines(), ({ key, type, phase, ...other }) => {
 			if (phase === "progress" || phase === "after") logger.trace({
 				...other,
@@ -578,7 +594,7 @@ var LocalDatabaseService = class extends AbstractDatabaseService {
 	pendingSwitchClient = null;
 	constructor(config, logger) {
 		const events = createDatabaseEventSystem();
-		super(createLocalSurrealClient(logger), logger, events);
+		super(createBareSurrealClient(), logger, events);
 		this.config = config;
 	}
 	getConfig() {
@@ -630,6 +646,7 @@ var LocalDatabaseService = class extends AbstractDatabaseService {
 			Category: "sp00ky-client::LocalDatabaseService::connect"
 		}, "Connecting to local database");
 		this.registerUnloadClose();
+		this.client = await createLocalSurrealClient(this.logger);
 		await this.openWithRecovery(this.client, storeUrl, namespace, database, bucketId, store);
 	}
 	/**
@@ -659,7 +676,7 @@ var LocalDatabaseService = class extends AbstractDatabaseService {
 			}, "Reset in-memory local store for bucket switch");
 			return;
 		}
-		const next = createLocalSurrealClient(this.logger);
+		const next = await createLocalSurrealClient(this.logger);
 		this.pendingSwitchClient = next;
 		try {
 			await this.openWithRecovery(next, bucketStoreUrl(bucketId), namespace, database, bucketId, store);
@@ -5089,8 +5106,8 @@ function parseBackendInfo(raw) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.137";
-const WASM_VERSION = "0.0.1-canary.137";
+const CORE_VERSION = "0.0.1-canary.138";
+const WASM_VERSION = "0.0.1-canary.138";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class {
 	eventsHistory = [];
@@ -6300,12 +6317,17 @@ var CrdtField = class {
 	get onCursorUpdate() {
 		return this._onCursorUpdate;
 	}
-	constructor(fieldName, cursorsEnabled, initialState, logger) {
+	/**
+	* @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(fieldName, cursorsEnabled, LoroDocClass, initialState, logger) {
 		this.fieldName = fieldName;
 		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 LoroDoc();
+		this.doc = new LoroDocClass();
 		if (initialState && initialState.length > 0) try {
 			this.doc.import(initialState);
 			this.loadedFromCrdt = true;
@@ -6474,6 +6496,19 @@ function encodeBase64(bytes) {
 	return Buffer.from(bytes).toString("base64");
 }
 
+//#endregion
+//#region src/modules/crdt/loro-loader.ts
+let loroPromise = null;
+/** Start (or return the in-flight/cached) `loro-crdt` import. Fire-and-forget. */
+function preloadLoro() {
+	loroPromise ??= import("loro-crdt");
+	return loroPromise;
+}
+/** Await the loro module, starting the import if `preloadLoro` hasn't run. */
+function loadLoro() {
+	return preloadLoro();
+}
+
 //#endregion
 //#region src/modules/crdt/index.ts
 /**
@@ -6545,7 +6580,8 @@ var CrdtManager = class {
 				Category: "sp00ky-client::CrdtManager::open"
 			}, "No existing CRDT state found in local cache (continuing with empty doc)");
 		}
-		crdtField = new CrdtField(field, cursorsEnabled, initialCrdtState, this.logger);
+		const { LoroDoc } = await loadLoro();
+		crdtField = new CrdtField(field, cursorsEnabled, LoroDoc, initialCrdtState, this.logger);
 		crdtField.startSync(this.local, this.remote, recordId, this.sessionId, this.debounceMs);
 		this.fields.set(key, crdtField);
 		this.logger.info({
@@ -7095,6 +7131,7 @@ var Sp00kyClient = class {
 			},
 			Category: "sp00ky-client::Sp00kyClient::constructor"
 		}, "Sp00kyClient initialized");
+		if (config.crdt) preloadLoro();
 		this.local = createLocalEngine(this.config.localEngine, this.config.database, logger);
 		this.remote = new RemoteDatabaseService(this.config.database, logger);
 		if (config.persistenceClient === "surrealdb") this.persistenceClient = new SurrealDBPersistenceClient(this.local, logger);

package/dist/types.d.ts

@@ -449,6 +449,14 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    * collaborators. Defaults to 500ms.
    */
   crdtDebounceMs?: number;
+  /**
+   * Enable collaborative CRDT fields. When `true`, the `loro-crdt` engine is
+   * preloaded at client startup (fetched as a separate chunk on page load) so
+   * the first `openCrdtField` is instant. When omitted/`false`, loro is never
+   * loaded unless a CRDT field is explicitly opened — keeping the loro chunk
+   * out of apps that don't use collaboration. Defaults to `false`.
+   */
+  crdt?: boolean;
   /**
    * Cadence (ms) for the `_00_list_ref` poll that catches cross-session
    * UPDATEs the SurrealDB v3 LIVE-permission gap drops. Lower = faster

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.137",
+  "version": "0.0.1-canary.138",
   "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -59,8 +60,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.137",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.137",
+    "@spooky-sync/query-builder": "0.0.1-canary.138",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.138",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",

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

@@ -1,4 +1,4 @@
-import { LoroDoc } from 'loro-crdt';
+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';
@@ -59,9 +59,15 @@ export class CrdtField {
 
   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,
   ) {
@@ -72,7 +78,7 @@ export class CrdtField {
     }
     this.logger = logger ?? null;
     this.cursorsEnabled = cursorsEnabled;
-    this.doc = new LoroDoc();
+    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

package/src/modules/crdt/index.ts

@@ -3,6 +3,7 @@ import type { LocalStore, RemoteDatabaseService } from '../../services/database/
 import type { Logger } from '../../services/logger/index';
 import type { Uuid } from 'surrealdb';
 import { CrdtField } from './crdt-field';
+import { loadLoro } from './loro-loader';
 import { parseRecordIdString } from '../../utils/index';
 
 export { CrdtField, cursorColorFromName, CURSOR_COLORS } from './crdt-field';
@@ -101,7 +102,10 @@ export class CrdtManager {
       );
     }
 
-    crdtField = new CrdtField(field, cursorsEnabled, initialCrdtState, this.logger);
+    // Load loro lazily (usually already resolved — the client preloads it at
+    // startup when `config.crdt` is on).
+    const { LoroDoc } = await loadLoro();
+    crdtField = new CrdtField(field, cursorsEnabled, LoroDoc, initialCrdtState, this.logger);
     crdtField.startSync(this.local, this.remote, recordId, this.sessionId, this.debounceMs);
     this.fields.set(key, crdtField);
 

package/src/modules/crdt/loro-loader.ts

@@ -0,0 +1,25 @@
+/**
+ * Lazy, cached loader for `loro-crdt`. Keeping loro behind a dynamic `import()`
+ * (instead of a static top-level import in `crdt-field.ts`, which is re-exported
+ * from the package entry) breaks the static graph edge, so the loro chunk only
+ * ships to apps that actually use CRDT fields.
+ *
+ * `preloadLoro()` is fired from the client constructor when `config.crdt` is on,
+ * so the chunk is fetched at page load and the first `openCrdtField` doesn't
+ * block on a network round-trip. `loadLoro()` kicks the same import if it hasn't
+ * started, so opening a field still works when the flag is off.
+ */
+type LoroModule = typeof import('loro-crdt');
+
+let loroPromise: Promise<LoroModule> | null = null;
+
+/** Start (or return the in-flight/cached) `loro-crdt` import. Fire-and-forget. */
+export function preloadLoro(): Promise<LoroModule> {
+  loroPromise ??= import('loro-crdt');
+  return loroPromise;
+}
+
+/** Await the loro module, starting the import if `preloadLoro` hasn't run. */
+export function loadLoro(): Promise<LoroModule> {
+  return preloadLoro();
+}

package/src/services/database/local.ts

@@ -1,6 +1,5 @@
 import type { Diagnostic} from 'surrealdb';
 import { applyDiagnostics, DateTime, RecordId, Surreal } from 'surrealdb';
-import { createWasmWorkerEngines } from '@surrealdb/wasm';
 import type { Sp00kyConfig } from '../../types';
 import type { Logger } from '../logger/index';
 import { AbstractDatabaseService } from './database';
@@ -30,21 +29,41 @@ export function bucketStoreName(bucketId: string): string {
   return `sp00ky-${bucketId}`;
 }
 
-function createLocalSurrealClient(logger: Logger): Surreal {
-  return new Surreal({
-    codecOptions: {
-      valueDecodeVisitor(value) {
-        if (value instanceof RecordId) {
-          return encodeRecordId(value);
-        }
+/** Shared codec: mirrors SurrealDB RecordId/DateTime into our own encodings. */
+const localCodecOptions = {
+  valueDecodeVisitor(value: unknown) {
+    if (value instanceof RecordId) {
+      return encodeRecordId(value);
+    }
 
-        if (value instanceof DateTime) {
-          return value.toDate();
-        }
+    if (value instanceof DateTime) {
+      return value.toDate();
+    }
+
+    return value;
+  },
+};
+
+/**
+ * Engine-less Surreal client used as the constructor placeholder. Building this
+ * pulls in NO `@surrealdb/wasm` — the ~6 MB wasm engine is deferred to
+ * {@link createLocalSurrealClient}, which runs lazily in `connect`/`switchStore`.
+ * `connect()` replaces `this.client` with an engine-backed client before any
+ * query runs, so this bare client is never actually opened against a store.
+ */
+function createBareSurrealClient(): Surreal {
+  return new Surreal({ codecOptions: localCodecOptions });
+}
 
-        return value;
-      },
-    },
+/**
+ * Engine-backed client. Dynamically imports `@surrealdb/wasm` so the wasm engine
+ * only enters the graph as a separate chunk fetched on first connect (module-
+ * cached thereafter — `switchStore`'s await is instant).
+ */
+async function createLocalSurrealClient(logger: Logger): Promise<Surreal> {
+  const { createWasmWorkerEngines } = await import('@surrealdb/wasm');
+  return new Surreal({
+    codecOptions: localCodecOptions,
     engines: applyDiagnostics(
       createWasmWorkerEngines(),
       ({ key, type, phase, ...other }: Diagnostic) => {
@@ -87,7 +106,9 @@ export class LocalDatabaseService extends AbstractDatabaseService {
 
   constructor(config: Sp00kyConfig<any>['database'], logger: Logger) {
     const events = createDatabaseEventSystem();
-    super(createLocalSurrealClient(logger), logger, events);
+    // Placeholder client with no wasm engine; `connect()` swaps in the real
+    // engine-backed client (built lazily) before any query is issued.
+    super(createBareSurrealClient(), logger, events);
     this.config = config;
   }
 
@@ -159,6 +180,10 @@ export class LocalDatabaseService extends AbstractDatabaseService {
     );
 
     this.registerUnloadClose();
+    // Build the real engine-backed client lazily here (first `@surrealdb/wasm`
+    // load), replacing the constructor's engine-less placeholder before any
+    // query runs.
+    this.client = await createLocalSurrealClient(this.logger);
     await this.openWithRecovery(this.client, storeUrl, namespace, database, bucketId, store);
   }
 
@@ -195,7 +220,7 @@ export class LocalDatabaseService extends AbstractDatabaseService {
       return;
     }
 
-    const next = createLocalSurrealClient(this.logger);
+    const next = await createLocalSurrealClient(this.logger);
     this.pendingSwitchClient = next;
     try {
       await this.openWithRecovery(

package/src/sp00ky.ts

@@ -43,6 +43,7 @@ import { EventSystem } from './events/index';
 import { CacheModule } from './modules/cache/index';
 import type { RecordWithId } from './modules/cache/index';
 import { CrdtManager, CrdtField } from './modules/crdt/index';
+import { preloadLoro } from './modules/crdt/loro-loader';
 import { FeatureFlagModule, FeatureFlagHandle } from './modules/feature-flag/index';
 import type { FeatureFlagOptions } from './modules/feature-flag/index';
 import { LocalStoragePersistenceClient } from './services/persistence/localstorage';
@@ -196,6 +197,11 @@ export class Sp00kyClient<S extends SchemaStructure> {
       'Sp00kyClient initialized'
     );
 
+    // Preload the loro CRDT engine at startup (fetches the chunk on page load)
+    // so the first `openCrdtField` doesn't block on a network round-trip. Left
+    // off, loro is never loaded unless a CRDT field is explicitly opened.
+    if (config.crdt) void preloadLoro();
+
     // The default ('surrealdb') engine is a SurrealCacheEngine — a drop-in
     // subclass of LocalDatabaseService that adds the engine-neutral verb surface
     // with zero behavior change. Alternate engines (e.g. 'sqlite') require the

package/src/types.ts

@@ -162,6 +162,14 @@ export interface Sp00kyConfig<S extends SchemaStructure> {
    * collaborators. Defaults to 500ms.
    */
   crdtDebounceMs?: number;
+  /**
+   * Enable collaborative CRDT fields. When `true`, the `loro-crdt` engine is
+   * preloaded at client startup (fetched as a separate chunk on page load) so
+   * the first `openCrdtField` is instant. When omitted/`false`, loro is never
+   * loaded unless a CRDT field is explicitly opened — keeping the loro chunk
+   * out of apps that don't use collaboration. Defaults to `false`.
+   */
+  crdt?: boolean;
   /**
    * Cadence (ms) for the `_00_list_ref` poll that catches cross-session
    * UPDATEs the SurrealDB v3 LIVE-permission gap drops. Lower = faster