@spooky-sync/core 0.0.1-canary.136 → 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);
@@ -1440,6 +1457,20 @@ function setPath(obj, path, value) {
 * full merged row is only materialized for a LET-wrapped upsert (see the 'let'
 * case). delete/deleteAll yield `[]`; noop yields `null`.
 */
+/**
+* The `_00_*` internal tables the client relies on. The LocalMigrator DEFINEs
+* them, but every DEFINE lowers to a noop on the SQLite engine, so they must be
+* created physically at open (see `openInternal`) or a read-before-first-write
+* on a fresh bucket throws "no such table". Keep in sync with the systemSchema
+* block in `local-migrator.ts`.
+*/
+const SYSTEM_TABLES = [
+	"_00_stream_processor_state",
+	"_00_query",
+	"_00_preload",
+	"_00_schema",
+	"_00_pending_mutations"
+];
 function pureWriteOpResult(op) {
 	switch (op.kind) {
 		case "upsert": return {
@@ -1594,9 +1625,11 @@ var SqliteCacheEngine = class {
 		this.worker = this.spawnWorker();
 		const { persisted } = await this.rawCall("open", {
 			dbName: bucketId,
-			useOpfs: this.useOpfs
+			useOpfs: this.useOpfs,
+			systemTables: SYSTEM_TABLES
 		});
 		this.knownTables.clear();
+		for (const t of SYSTEM_TABLES) this.knownTables.add(t);
 		this.bucketId = bucketId;
 		this.logger.info({
 			bucketId,
@@ -5073,8 +5106,8 @@ function parseBackendInfo(raw) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.136";
-const WASM_VERSION = "0.0.1-canary.136";
+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 = [];
@@ -6284,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;
@@ -6458,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
 /**
@@ -6529,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({
@@ -7079,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/sqlite-worker.js

@@ -96,7 +96,7 @@ async function executeSelect(plan, params, db) {
 * hot path; the per-statement ops remain for the write/shim paths.
 */
 let db = null;
-async function open(dbName, useOpfs) {
+async function open(dbName, useOpfs, systemTables = []) {
 	const sqlite3 = await sqlite3InitModule();
 	let persisted = false;
 	if (useOpfs && sqlite3.installOpfsSAHPoolVfs) try {
@@ -104,6 +104,7 @@ async function open(dbName, useOpfs) {
 		persisted = true;
 	} catch {}
 	if (!db) db = new sqlite3.oo1.DB(":memory:", "c");
+	for (const t of systemTables) db.exec({ sql: `CREATE TABLE IF NOT EXISTS "${t}" (id TEXT PRIMARY KEY, data TEXT NOT NULL)` });
 	try {
 		db.exec({ sql: "PRAGMA busy_timeout = 5000; PRAGMA cache_size = -32000;" });
 	} catch {}
@@ -157,7 +158,8 @@ self.onmessage = async (ev) => {
 		switch (type) {
 			case "open":
 				selectDb.knownTables.clear();
-				result = await open(payload.dbName, payload.useOpfs);
+				result = await open(payload.dbName, payload.useOpfs, payload.systemTables);
+				for (const t of payload.systemTables ?? []) selectDb.knownTables.add(t);
 				break;
 			case "select":
 				result = await executeSelect(payload.plan, payload.params ?? {}, selectDb);

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.136",
+  "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.136",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.136",
+    "@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/services/database/sqlite-cache-engine.test.ts

@@ -96,6 +96,45 @@ describe('SqliteCacheEngine.switchBucket serialization', () => {
   });
 });
 
+// Regression: DEFINE is a noop on this engine, so the `_00_*` internal tables
+// the migrator DEFINEs are never physically created — a fresh bucket that READS
+// one before any write (the sync layer selects `_00_query` at startup) threw
+// "no such table: _00_query" and wedged the client on "Loading database". The
+// fix seeds them inside `open`; assert the open message carries them.
+describe('SqliteCacheEngine system-table seeding', () => {
+  it('passes the _00_* system tables to the worker open (fresh-bucket safe)', async () => {
+    const msgs: any[] = [];
+    const engine = new SqliteCacheEngine({ namespace: 'n', database: 'd' } as any, makeLogger());
+    (engine as any).spawnWorker = () => {
+      const w: any = { onmessage: null, onerror: null, onmessageerror: null, terminate() {} };
+      w.postMessage = (msg: any) => {
+        msgs.push(msg);
+        Promise.resolve().then(() => {
+          const rest = msg.type === 'open' ? { persisted: true } : {};
+          w.onmessage?.({ data: { id: msg.id, ok: true, ...rest } });
+        });
+      };
+      // Wire pending resolution like the real spawnWorker.
+      const inner = w.onmessage;
+      w.onmessage = (ev: any) => {
+        const { id, ok, error, ...rest } = ev.data ?? {};
+        const p = (engine as any).pending.get(id);
+        if (!p) return;
+        (engine as any).pending.delete(id);
+        if (ok) p.resolve(rest);
+        else p.reject(new Error(error));
+        void inner;
+      };
+      return w as unknown as Worker;
+    };
+
+    await engine.connect('user:fresh');
+    const open = msgs.find((m) => m.type === 'open');
+    expect(open?.payload?.systemTables).toContain('_00_query');
+    expect(open?.payload?.systemTables).toContain('_00_pending_mutations');
+  });
+});
+
 // `pureWriteOpResult` is the single source of truth for what a pure-write op
 // contributes to a query's per-statement results. The batched fast path in
 // `query()` and the per-op `execOp` path BOTH route through it, so a caller that

package/src/services/database/sqlite-cache-engine.ts

@@ -34,6 +34,21 @@ import type { EngineTx, Id, LocalStore, OrderBy, RelationFetch, Row } from './ca
  * full merged row is only materialized for a LET-wrapped upsert (see the 'let'
  * case). delete/deleteAll yield `[]`; noop yields `null`.
  */
+/**
+ * The `_00_*` internal tables the client relies on. The LocalMigrator DEFINEs
+ * them, but every DEFINE lowers to a noop on the SQLite engine, so they must be
+ * created physically at open (see `openInternal`) or a read-before-first-write
+ * on a fresh bucket throws "no such table". Keep in sync with the systemSchema
+ * block in `local-migrator.ts`.
+ */
+const SYSTEM_TABLES = [
+  '_00_stream_processor_state',
+  '_00_query',
+  '_00_preload',
+  '_00_schema',
+  '_00_pending_mutations',
+] as const;
+
 export function pureWriteOpResult(op: SqlOp): unknown {
   switch (op.kind) {
     case 'upsert':
@@ -217,11 +232,22 @@ export class SqliteCacheEngine implements LocalStore {
    */
   private async openInternal(bucketId: string): Promise<void> {
     this.worker = this.spawnWorker();
+    // Seed the `_00_*` system tables as part of `open` (worker-side, one round
+    // trip). The LocalMigrator DEFINEs them, but `translateSurql` lowers every
+    // DEFINE to a noop on this engine (SQLite has no DDL vocabulary), so
+    // provisioning never actually creates them — they were only made lazily on
+    // first WRITE. A fresh bucket (e.g. right after signup) that READS one first
+    // (the sync layer selects `_00_query` before any row lands) hit
+    // "no such table: _00_query" and the client wedged on "Loading database".
+    // Creating them inside `open` guarantees any access order is safe without
+    // adding ops to the engine's queue.
     const { persisted } = await this.rawCall<{ persisted: boolean }>('open', {
       dbName: bucketId,
       useOpfs: this.useOpfs,
+      systemTables: SYSTEM_TABLES,
     });
     this.knownTables.clear();
+    for (const t of SYSTEM_TABLES) this.knownTables.add(t);
     this.bucketId = bucketId;
     this.logger.info(
       { bucketId, persisted, Category: 'sp00ky-client::SqliteCacheEngine::connect' },

package/src/services/database/sqlite-worker.ts

@@ -34,7 +34,11 @@ let db: {
   close: () => void;
 } | null = null;
 
-async function open(dbName: string, useOpfs: boolean): Promise<{ persisted: boolean }> {
+async function open(
+  dbName: string,
+  useOpfs: boolean,
+  systemTables: readonly string[] = []
+): Promise<{ persisted: boolean }> {
   const sqlite3: any = await sqlite3InitModule();
   let persisted = false;
   if (useOpfs && sqlite3.installOpfsSAHPoolVfs) {
@@ -47,6 +51,12 @@ async function open(dbName: string, useOpfs: boolean): Promise<{ persisted: bool
     }
   }
   if (!db) db = new sqlite3.oo1.DB(':memory:', 'c');
+  // Physically create the internal `_00_*` tables the client reads before any
+  // write (DEFINE is a noop on this engine, so the migrator can't). Prevents
+  // "no such table: _00_query" on a fresh bucket right after signup.
+  for (const t of systemTables) {
+    db!.exec({ sql: `CREATE TABLE IF NOT EXISTS "${t}" (id TEXT PRIMARY KEY, data TEXT NOT NULL)` });
+  }
   // Retry (rather than instantly failing with SQLITE_BUSY=5) if a lock is held.
   // Combined with the engine's single-flight op queue, overlap is avoided.
   // `cache_size` is negated → KiB (here 32 MiB) so SQLite's page cache can't
@@ -106,7 +116,10 @@ self.onmessage = async (ev: MessageEvent) => {
     switch (type) {
       case 'open':
         selectDb.knownTables.clear();
-        result = await open(payload.dbName, payload.useOpfs);
+        result = await open(payload.dbName, payload.useOpfs, payload.systemTables);
+        // The freshly seeded system tables exist — record them so the select
+        // path doesn't redundantly re-issue CREATE TABLE for each.
+        for (const t of (payload.systemTables ?? []) as string[]) selectDb.knownTables.add(t);
         break;
       case 'select':
         result = await executeSelect(payload.plan, payload.params ?? {}, selectDb);

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