@spooky-sync/core 0.0.1-canary.114 → 0.0.1-canary.118

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { A as SyncHealthStatus, B as EventDefinition, C as RunOptions, D as StoreType, E as Sp00kyQueryResultPromise, F as SealedQuery, I as DatabaseEventSystem, L as DatabaseEventTypes, M as UpdateOptions, N as UpEvent, O as SyncHealth, P as LocalStore, R as Logger$1, S as RegistrationTimings, T as Sp00kyQueryResult, V as EventSystem, _ 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 TimingPhase, k as SyncHealthConfig, 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, z as SyncEventSystem } from "./types.js";
+import { A as SyncHealth, B as Logger$1, C as RecordVersionDiff, D as Sp00kyQueryResult, E as Sp00kyConfig, F as UpEvent, H as EventDefinition, I as LocalStore, L as SealedQuery, M as SyncHealthStatus, N as TimingPhase, O as Sp00kyQueryResultPromise, P as UpdateOptions, R as DatabaseEventSystem, S as RecordVersionArray, T as RunOptions, U as EventSystem, V as SyncEventSystem, _ as QueryStatus, a as MutationCallback, b as QueryTimings, c as PersistenceClient, d as PreloadOptions, f as PreloadRefresh, g as QueryState, h as QueryHash, i as MATERIALIZATION_SAMPLE_WINDOW, j as SyncHealthConfig, k as StoreType, l as PhaseStat, m as QueryConfigRecord, n as EventSubscriptionOptions, o as MutationEvent, p as QueryConfig, r as Level, s as MutationEventType, t as DebounceOptions, u as PinoTransmit, v as QueryStatusCallback, w as RegistrationTimings, x as QueryUpdateCallback, y as QueryTimeToLive, z as DatabaseEventTypes } from "./types.js";
 import * as surrealdb0 from "surrealdb";
 import { Duration, RecordId, Surreal as Surreal$1, SurrealTransaction } from "surrealdb";
-import { AccessDefinition, BackendNames, BackendRoutes, BucketNames, ColumnSchema, GetTable, QueryBuilder, QueryOptions, QueryPlan, RoutePayload, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap } from "@spooky-sync/query-builder";
+import { AccessDefinition, BackendNames, BackendRoutes, BucketNames, ColumnSchema, FinalQuery, GetTable, QueryBuilder, QueryOptions, QueryPlan, RoutePayload, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap } from "@spooky-sync/query-builder";
 import { Logger } from "pino";
 import { LoroDoc } from "loro-crdt";
 
@@ -484,6 +484,37 @@ declare class DataModule<S extends SchemaStructure> {
    * local-circuit issue). Runs at most once per query (the `hydrated` flag).
    */
   applyHydration(hash: string, rows: RecordWithId[]): Promise<void>;
+  /**
+   * Build the cache batch for a set of one-shot rows and persist it to the
+   * local DB + in-browser SSP. Maps each row to a `CREATE` op on its own table
+   * and extracts EMBEDDED related children (any nesting depth) as their own
+   * records — a `.related()` query returns its children embedded, and a later
+   * correlated re-materialization needs them present as standalone rows.
+   * Shared by `applyHydration` (live registration) and `persistSnapshot`
+   * (preload).
+   */
+  private buildAndSaveCacheBatch;
+  /**
+   * Preload/prewarm: persist one-shot rows (and their embedded related children)
+   * into the local cache WITHOUT registering a query — no `activeQueries` entry,
+   * no `_00_query` view, no TTL heartbeat. The rows live in the local DB as
+   * ordinary bodies (never GC'd on their own) so a later `useQuery` seeds its
+   * first paint from them instantly, then registers a live view to freshen.
+   */
+  persistSnapshot(tableName: string, rows: RecordWithId[]): Promise<void>;
+  /**
+   * Read the durable preload freshness marker for a query hash, or null if this
+   * query was never preloaded in the current bucket. Co-located with the cached
+   * rows (per-bucket `_00_preload` table) so a bucket switch that clears the
+   * data also clears the marker — a stale marker can't claim "warm" when the
+   * rows are gone. Any read error is treated as cold.
+   */
+  getPreloadMarker(hash: string): Promise<{
+    fetchedAt: number;
+    rowCount: number;
+  } | null>;
+  /** Stamp the preload freshness marker after a successful snapshot fetch. */
+  writePreloadMarker(hash: string, rowCount: number): Promise<void>;
   /** True while ≥1 live subscriber is watching this query (refcount guard). */
   hasSubscribers(hash: string): boolean;
   /**
@@ -1172,6 +1203,7 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   private devTools;
   private crdtManager;
   private featureFlags;
+  private preloadedHashes;
   private logger;
   auth: AuthService<S>;
   streamProcessor: StreamProcessorService;
@@ -1253,6 +1285,30 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   deauthenticate(): Promise<void>;
   query<Table extends TableNames<S>>(table: Table, options: QueryOptions<TableModel<GetTable<S, Table>>, false>, ttl?: QueryTimeToLive): QueryBuilder<S, Table, Sp00kyQueryResultPromise>;
   private initQuery;
+  /**
+   * Smart, awaitable preload/prewarm into the LOCAL cache — without registering a
+   * live view (NO `_00_query`, NO subscription, NO TTL heartbeat).
+   *
+   * Cache-aware via a durable per-bucket freshness marker (`_00_preload`):
+   * - COLD (never preloaded in this bucket): fetch the query one-shot from the
+   *   remote, persist the rows (+ embedded `.related()` children), stamp the
+   *   marker — and AWAIT it. This is the "smart waiting" first load: callers can
+   *   `await db.preload(...)` to hold the UI until the data is ready.
+   * - WARM (marker present): return instantly — NEVER blocks. `refresh` decides
+   *   whether to also kick a one-time silent refetch (see {@link PreloadOptions}).
+   *   Default `onUse` does nothing; the data freshens when the real `useQuery`
+   *   mounts and registers its live view.
+   *
+   * Best-effort: any fetch failure (offline, etc.) is a no-op warn (no marker
+   * written, so it's retried next load). Deduped per session by query hash.
+   */
+  preload(finalQuery: FinalQuery<S, any, any, any, any, any>, options?: PreloadOptions): Promise<void>;
+  /**
+   * One-shot remote fetch + local persist for a preload query. Returns the row
+   * count on success, or -1 on failure (best-effort: logged, never thrown) so
+   * the caller skips stamping the freshness marker and retries next load.
+   */
+  private fetchAndPersist;
   queryRaw(sql: string, params: Record<string, any>, ttl: QueryTimeToLive): Promise<string>;
   subscribe(queryHash: string, callback: (records: Record<string, any>[]) => void, options?: {
     immediate?: boolean;
@@ -1318,4 +1374,4 @@ declare function textToHtml(text: string): string;
  */
 
 //#endregion
-export { AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagSnapshot, 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, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };
+export { AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagSnapshot, Level, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };

package/dist/index.js

@@ -947,7 +947,7 @@ var LocalMigrator = class {
 			return;
 		}
 		await this.recreateDatabase(database);
-		const fullSchema = schemaSurql + "\n\n      DEFINE TABLE IF NOT EXISTS _00_stream_processor_state SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_query SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_schema SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_pending_mutations SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n    ";
+		const fullSchema = schemaSurql + "\n\n      DEFINE TABLE IF NOT EXISTS _00_stream_processor_state SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_query SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_preload SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_schema SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_pending_mutations SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n    ";
 		const statements = this.splitStatements(fullSchema);
 		for (let i = 0; i < statements.length; i++) {
 			const statement = statements[i];
@@ -1222,7 +1222,7 @@ function renderRelationFetchSurql(req) {
 		vars: { __keys: req.keys },
 		n: 0
 	};
-	let sql = `SELECT ${req.select && req.select.length > 0 ? ["id", ...req.select].join(", ") : "*"} FROM ${req.table} WHERE ${req.matchField} IN $__keys`;
+	let sql = `SELECT ${req.select && req.select.length > 0 ? ["id", ...req.select].join(", ") : "*"} FROM ${req.table} WHERE ${req.matchField} IN $__keys.map(|$__k| type::record(<string> $__k))`;
 	if (req.where && req.where.length > 0) sql += ` AND ${renderWhereSurql(req.where, ctx)}`;
 	if (req.orderBy && req.orderBy.length > 0) sql += renderOrderBy(req.orderBy);
 	return {
@@ -2708,6 +2708,22 @@ var DataModule = class {
 		queryState.hydrated = true;
 		if (rows.length === 0) return;
 		const tableName = queryState.config.tableName;
+		await this.buildAndSaveCacheBatch(tableName, rows);
+		queryState.config.remoteArray = rows.map((r) => [encodeRecordId(r.id), r._00_rv || 1]);
+		queryState.records = await this.materializeRecords(queryState);
+		const subscribers = this.subscriptions.get(hash);
+		if (subscribers) for (const cb of subscribers) cb(queryState.records);
+	}
+	/**
+	* Build the cache batch for a set of one-shot rows and persist it to the
+	* local DB + in-browser SSP. Maps each row to a `CREATE` op on its own table
+	* and extracts EMBEDDED related children (any nesting depth) as their own
+	* records — a `.related()` query returns its children embedded, and a later
+	* correlated re-materialization needs them present as standalone rows.
+	* Shared by `applyHydration` (live registration) and `persistSnapshot`
+	* (preload).
+	*/
+	async buildAndSaveCacheBatch(tableName, rows) {
 		const batch = rows.map((record) => ({
 			table: tableName,
 			op: "CREATE",
@@ -2717,10 +2733,43 @@ var DataModule = class {
 		const seen = new Set(rows.map((r) => encodeRecordId(r.id)));
 		for (const record of rows) this.collectEmbeddedChildren(record, batch, seen);
 		await this.cache.saveBatch(batch);
-		queryState.config.remoteArray = rows.map((r) => [encodeRecordId(r.id), r._00_rv || 1]);
-		queryState.records = await this.materializeRecords(queryState);
-		const subscribers = this.subscriptions.get(hash);
-		if (subscribers) for (const cb of subscribers) cb(queryState.records);
+	}
+	/**
+	* Preload/prewarm: persist one-shot rows (and their embedded related children)
+	* into the local cache WITHOUT registering a query — no `activeQueries` entry,
+	* no `_00_query` view, no TTL heartbeat. The rows live in the local DB as
+	* ordinary bodies (never GC'd on their own) so a later `useQuery` seeds its
+	* first paint from them instantly, then registers a live view to freshen.
+	*/
+	async persistSnapshot(tableName, rows) {
+		if (rows.length === 0) return;
+		await this.buildAndSaveCacheBatch(tableName, rows);
+	}
+	/**
+	* Read the durable preload freshness marker for a query hash, or null if this
+	* query was never preloaded in the current bucket. Co-located with the cached
+	* rows (per-bucket `_00_preload` table) so a bucket switch that clears the
+	* data also clears the marker — a stale marker can't claim "warm" when the
+	* rows are gone. Any read error is treated as cold.
+	*/
+	async getPreloadMarker(hash) {
+		try {
+			const row = await this.local.getById("_00_preload", hash);
+			if (!row) return null;
+			return {
+				fetchedAt: Number(row.fetchedAt) || 0,
+				rowCount: Number(row.rowCount) || 0
+			};
+		} catch {
+			return null;
+		}
+	}
+	/** Stamp the preload freshness marker after a successful snapshot fetch. */
+	async writePreloadMarker(hash, rowCount) {
+		await this.local.upsert("_00_preload", hash, {
+			fetchedAt: Date.now(),
+			rowCount
+		}, "replace");
 	}
 	/** True while ≥1 live subscriber is watching this query (refcount guard). */
 	hasSubscribers(hash) {
@@ -5051,8 +5100,8 @@ function parseBackendInfo(raw) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.114";
-const WASM_VERSION = "0.0.1-canary.114";
+const CORE_VERSION = "0.0.1-canary.118";
+const WASM_VERSION = "0.0.1-canary.118";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class {
 	eventsHistory = [];
@@ -5080,7 +5129,8 @@ var DevToolsService = class {
 			} else if (type === "SP00KY_DEVTOOLS_DISCONNECT") this.enabled = false;
 		});
 		this.authService.eventSystem.subscribe(AuthEventTypes.AuthStateChanged, () => {
-			this.notifyDevTools();
+			if (this.authService.isAuthenticated && this.backendInfo.versions.ssp === UNAVAILABLE) this.refreshBackendVersions();
+			else this.notifyDevTools();
 		});
 		this.refreshBackendVersions();
 		this.logger.debug({ Category: "sp00ky-client::DevToolsService::init" }, "Service initialized");
@@ -7009,6 +7059,7 @@ var Sp00kyClient = class {
 	devTools;
 	crdtManager;
 	featureFlags;
+	preloadedHashes = /* @__PURE__ */ new Set();
 	logger;
 	auth;
 	streamProcessor;
@@ -7206,13 +7257,18 @@ var Sp00kyClient = class {
 	ensureLocalBucket(userId) {
 		const target = bucketIdForUser(userId);
 		this.pendingBucketTarget = target;
+		const release = this.local.currentBucketId !== target ? this.local.beginSwitch() : null;
 		this.bucketSwitchChain = this.bucketSwitchChain.then(async () => {
-			if (this.pendingBucketTarget !== target) return;
-			if (this.local.currentBucketId === target) return;
-			await this.doSwitchBucket(target);
+			if (this.pendingBucketTarget !== target || this.local.currentBucketId === target) {
+				release?.();
+				return;
+			}
+			await this.doSwitchBucket(target, release);
 		});
 		const result = this.bucketSwitchChain;
-		this.bucketSwitchChain = this.bucketSwitchChain.catch(() => {});
+		this.bucketSwitchChain = this.bucketSwitchChain.catch(() => {
+			release?.();
+		});
 		return result;
 	}
 	/**
@@ -7235,7 +7291,7 @@ var Sp00kyClient = class {
 	* re-homed keeping their hashes, sync resumed on the new bucket's own
 	* outbox, and every query re-registered remotely to refill from the server.
 	*/
-	async doSwitchBucket(target) {
+	async doSwitchBucket(target, gateRelease) {
 		this.logger.info({
 			target,
 			from: this.local.currentBucketId,
@@ -7244,7 +7300,7 @@ var Sp00kyClient = class {
 		await this.sync.prepareBucketSwitch();
 		this.dataModule.quiesce();
 		this.crdtManager.closeAll({ flush: false });
-		const reopen = this.local.beginSwitch();
+		const reopen = gateRelease ?? this.local.beginSwitch();
 		try {
 			await this.local.switchStore(target);
 			if (this.local.usesSurqlSchema) await this.migrator.provision(this.config.schemaSurql);
@@ -7339,6 +7395,71 @@ var Sp00kyClient = class {
 		});
 		return hash;
 	}
+	/**
+	* Smart, awaitable preload/prewarm into the LOCAL cache — without registering a
+	* live view (NO `_00_query`, NO subscription, NO TTL heartbeat).
+	*
+	* Cache-aware via a durable per-bucket freshness marker (`_00_preload`):
+	* - COLD (never preloaded in this bucket): fetch the query one-shot from the
+	*   remote, persist the rows (+ embedded `.related()` children), stamp the
+	*   marker — and AWAIT it. This is the "smart waiting" first load: callers can
+	*   `await db.preload(...)` to hold the UI until the data is ready.
+	* - WARM (marker present): return instantly — NEVER blocks. `refresh` decides
+	*   whether to also kick a one-time silent refetch (see {@link PreloadOptions}).
+	*   Default `onUse` does nothing; the data freshens when the real `useQuery`
+	*   mounts and registers its live view.
+	*
+	* Best-effort: any fetch failure (offline, etc.) is a no-op warn (no marker
+	* written, so it's retried next load). Deduped per session by query hash.
+	*/
+	async preload(finalQuery, options) {
+		const q = finalQuery.innerQuery;
+		if (this.preloadedHashes.has(q.hash)) return;
+		const tableName = q.tableName;
+		const tableSchema = this.config.schema.tables.find((t) => t.name === tableName);
+		if (!tableSchema) throw new Error(`Table ${tableName} not found`);
+		const params = parseParams(tableSchema.columns, q.selectQuery.vars ?? {});
+		const hashKey = String(q.hash);
+		const marker = await this.dataModule.getPreloadMarker(hashKey);
+		if (!marker) {
+			const rowCount = await this.fetchAndPersist(q, tableName, params);
+			if (rowCount >= 0) {
+				await this.dataModule.writePreloadMarker(hashKey, rowCount);
+				this.preloadedHashes.add(q.hash);
+			}
+			return;
+		}
+		this.preloadedHashes.add(q.hash);
+		const refresh = options?.refresh ?? "onUse";
+		if (refresh === "onUse") return;
+		if (refresh === "stale") {
+			const maxAgeMs = parseDuration(options?.staleTime ?? "1h");
+			if (Date.now() - marker.fetchedAt <= maxAgeMs) return;
+		}
+		this.fetchAndPersist(q, tableName, params).then((rowCount) => {
+			if (rowCount >= 0) return this.dataModule.writePreloadMarker(hashKey, rowCount);
+		});
+	}
+	/**
+	* One-shot remote fetch + local persist for a preload query. Returns the row
+	* count on success, or -1 on failure (best-effort: logged, never thrown) so
+	* the caller skips stamping the freshness marker and retries next load.
+	*/
+	async fetchAndPersist(q, tableName, params) {
+		try {
+			const [rows] = await this.remote.query(q.selectQuery.query, params);
+			const list = rows ?? [];
+			await this.dataModule.persistSnapshot(tableName, list);
+			return list.length;
+		} catch (err) {
+			this.logger.warn({
+				err,
+				hash: q.hash,
+				Category: "sp00ky-client::Sp00kyClient::preload"
+			}, "Preload fetch failed; data will be fetched on demand");
+			return -1;
+		}
+	}
 	async queryRaw(sql, params, ttl) {
 		const tableName = sql.split("FROM ")[1].split(" ")[0];
 		return this.dataModule.query(tableName, sql, params, ttl);

package/dist/types.d.ts

@@ -360,6 +360,22 @@ interface PersistenceClient {
  * 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';
+/**
+ * Refresh behavior for `preload` when the data is already cached locally (warm).
+ * The FIRST load (cold) always fetches + blocks regardless.
+ * - `onUse` (default): do nothing when warm — the data freshens on use, when the
+ *   real `useQuery` mounts and registers its live view. No network on load.
+ * - `background`: return instantly, but kick a one-time silent refetch.
+ * - `stale`: like `background`, but only if the cached copy is older than
+ *   `staleTime`.
+ */
+type PreloadRefresh = 'onUse' | 'background' | 'stale';
+interface PreloadOptions {
+  /** How to refresh when the query is already cached locally. Default `onUse`. */
+  refresh?: PreloadRefresh;
+  /** For `refresh: 'stale'` — max age before a warm copy is refetched. Default `1h`. */
+  staleTime?: QueryTimeToLive;
+}
 /**
  * Result object returned when a query is registered or executed.
  */
@@ -724,4 +740,4 @@ interface DebounceOptions {
   delay?: number;
 }
 //#endregion
-export { SyncHealthStatus as A, EventDefinition as B, RunOptions as C, StoreType as D, Sp00kyQueryResultPromise as E, SealedQuery as F, DatabaseEventSystem as I, DatabaseEventTypes as L, UpdateOptions as M, UpEvent as N, SyncHealth as O, LocalStore as P, Logger$1 as R, RegistrationTimings as S, Sp00kyQueryResult as T, EventSystem as V, QueryTimeToLive as _, MutationCallback as a, RecordVersionArray as b, PersistenceClient as c, QueryConfig as d, QueryConfigRecord as f, QueryStatusCallback as g, QueryStatus as h, MATERIALIZATION_SAMPLE_WINDOW as i, TimingPhase as j, SyncHealthConfig as k, PhaseStat as l, QueryState as m, EventSubscriptionOptions as n, MutationEvent as o, QueryHash as p, Level$1 as r, MutationEventType as s, DebounceOptions as t, PinoTransmit as u, QueryTimings as v, Sp00kyConfig as w, RecordVersionDiff as x, QueryUpdateCallback as y, SyncEventSystem as z };
+export { SyncHealth as A, Logger$1 as B, RecordVersionDiff as C, Sp00kyQueryResult as D, Sp00kyConfig as E, UpEvent as F, EventDefinition as H, LocalStore as I, SealedQuery as L, SyncHealthStatus as M, TimingPhase as N, Sp00kyQueryResultPromise as O, UpdateOptions as P, DatabaseEventSystem as R, RecordVersionArray as S, RunOptions as T, EventSystem as U, SyncEventSystem as V, QueryStatus as _, MutationCallback as a, QueryTimings as b, PersistenceClient as c, PreloadOptions as d, PreloadRefresh as f, QueryState as g, QueryHash as h, MATERIALIZATION_SAMPLE_WINDOW as i, SyncHealthConfig as j, StoreType as k, PhaseStat as l, QueryConfigRecord as m, EventSubscriptionOptions as n, MutationEvent as o, QueryConfig as p, Level$1 as r, MutationEventType as s, DebounceOptions as t, PinoTransmit as u, QueryStatusCallback as v, RegistrationTimings as w, QueryUpdateCallback as x, QueryTimeToLive as y, DatabaseEventTypes as z };

package/package.json

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

package/src/modules/data/index.ts

@@ -763,6 +763,35 @@ export class DataModule<S extends SchemaStructure> {
     if (rows.length === 0) return;
 
     const tableName = queryState.config.tableName;
+    await this.buildAndSaveCacheBatch(tableName, rows);
+
+    // Prime remoteArray from the hydrated id+version pairs: `materializeRecords`
+    // prefers it for windowed queries (correct window) and it feeds the version
+    // dedup. Registration later overwrites it with the authoritative `_00_list_ref`.
+    queryState.config.remoteArray = rows.map(
+      (r) => [encodeRecordId(r.id), (r._00_rv as number) || 1] as [string, number]
+    );
+
+    queryState.records = await this.materializeRecords(queryState);
+    const subscribers = this.subscriptions.get(hash);
+    if (subscribers) {
+      for (const cb of subscribers) cb(queryState.records);
+    }
+  }
+
+  /**
+   * Build the cache batch for a set of one-shot rows and persist it to the
+   * local DB + in-browser SSP. Maps each row to a `CREATE` op on its own table
+   * and extracts EMBEDDED related children (any nesting depth) as their own
+   * records — a `.related()` query returns its children embedded, and a later
+   * correlated re-materialization needs them present as standalone rows.
+   * Shared by `applyHydration` (live registration) and `persistSnapshot`
+   * (preload).
+   */
+  private async buildAndSaveCacheBatch(
+    tableName: string,
+    rows: RecordWithId[]
+  ): Promise<void> {
     const batch: CacheRecord[] = rows.map((record) => ({
       table: tableName,
       op: 'CREATE' as const,
@@ -770,35 +799,58 @@ export class DataModule<S extends SchemaStructure> {
       version: (record._00_rv as number) || 1,
     }));
 
-    // Flicker-free related data on cold first paint: a `.related()` query's
-    // rows arrive with their child rows EMBEDDED (the correlated subquery,
-    // e.g. `(SELECT * FROM comment WHERE game=$parent.id) AS comments`). The
-    // primary batch above persists only the parent table, so the immediate
-    // `materializeRecords` below would re-run the correlated surql against a
-    // local DB with no child rows and overwrite the embedded result with
-    // empties. Extract those embedded children (any nesting depth) and
-    // persist them as their own records so the re-materialization finds them.
     const seen = new Set<string>(rows.map((r) => encodeRecordId(r.id)));
     for (const record of rows) {
       this.collectEmbeddedChildren(record, batch, seen);
     }
 
     await this.cache.saveBatch(batch);
+  }
 
-    // Prime remoteArray from the hydrated id+version pairs: `materializeRecords`
-    // prefers it for windowed queries (correct window) and it feeds the version
-    // dedup. Registration later overwrites it with the authoritative `_00_list_ref`.
-    queryState.config.remoteArray = rows.map(
-      (r) => [encodeRecordId(r.id), (r._00_rv as number) || 1] as [string, number]
-    );
+  /**
+   * Preload/prewarm: persist one-shot rows (and their embedded related children)
+   * into the local cache WITHOUT registering a query — no `activeQueries` entry,
+   * no `_00_query` view, no TTL heartbeat. The rows live in the local DB as
+   * ordinary bodies (never GC'd on their own) so a later `useQuery` seeds its
+   * first paint from them instantly, then registers a live view to freshen.
+   */
+  async persistSnapshot(tableName: string, rows: RecordWithId[]): Promise<void> {
+    if (rows.length === 0) return;
+    await this.buildAndSaveCacheBatch(tableName, rows);
+  }
 
-    queryState.records = await this.materializeRecords(queryState);
-    const subscribers = this.subscriptions.get(hash);
-    if (subscribers) {
-      for (const cb of subscribers) cb(queryState.records);
+  /**
+   * Read the durable preload freshness marker for a query hash, or null if this
+   * query was never preloaded in the current bucket. Co-located with the cached
+   * rows (per-bucket `_00_preload` table) so a bucket switch that clears the
+   * data also clears the marker — a stale marker can't claim "warm" when the
+   * rows are gone. Any read error is treated as cold.
+   */
+  async getPreloadMarker(
+    hash: string
+  ): Promise<{ fetchedAt: number; rowCount: number } | null> {
+    try {
+      const row = await this.local.getById('_00_preload', hash);
+      if (!row) return null;
+      return {
+        fetchedAt: Number((row as any).fetchedAt) || 0,
+        rowCount: Number((row as any).rowCount) || 0,
+      };
+    } catch {
+      return null;
     }
   }
 
+  /** Stamp the preload freshness marker after a successful snapshot fetch. */
+  async writePreloadMarker(hash: string, rowCount: number): Promise<void> {
+    await this.local.upsert(
+      '_00_preload',
+      hash,
+      { fetchedAt: Date.now(), rowCount },
+      'replace'
+    );
+  }
+
   /** True while ≥1 live subscriber is watching this query (refcount guard). */
   hasSubscribers(hash: string): boolean {
     return (this.subscriptions.get(hash)?.size ?? 0) > 0;

package/src/modules/devtools/index.ts

@@ -20,6 +20,7 @@ import {
   type BackendInfo,
   emptyBackendInfo,
   parseBackendInfo,
+  UNAVAILABLE,
 } from './versions';
 
 // Real bundled frontend versions, injected at build time by tsdown's
@@ -82,9 +83,17 @@ export class DevToolsService implements StreamUpdateReceiver {
       });
     }
 
-    // Subscribe to auth events
+    // Subscribe to auth events. The initial fire-and-forget version fetch (below)
+    // races the remote connection; on the free plan the remote DB (SurrealDB
+    // Cloud) has no guest access, so `fn::spooky::info()` is only callable once
+    // signed in. Re-fetch when auth resolves — until the versions actually land —
+    // instead of leaving them 'unavailable' forever.
     this.authService.eventSystem.subscribe(AuthEventTypes.AuthStateChanged, () => {
-      this.notifyDevTools();
+      if (this.authService.isAuthenticated && this.backendInfo.versions.ssp === UNAVAILABLE) {
+        void this.refreshBackendVersions();
+      } else {
+        this.notifyDevTools();
+      }
     });
 
     // Fire-and-forget backend version discovery; re-push state when it lands.

package/src/modules/sync/sync.subquery.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { Sp00kySync } from './sync';
+import { buildSubqueryListRefSelect } from './utils';
+import { encodeRecordId } from '../../utils/index';
+
+// Guards the CLIENT half of `.related()` (author/comments) delivery: given
+// subquery-child edges on the server (`_00_list_ref…` rows with
+// `parent IS NOT NONE`), `syncSubqueryChildren` MUST pull the child bodies
+// through the sync engine so a later re-materialization attaches them to the
+// parent. If this stops forwarding the child ids, related fields come back
+// empty (threads render with an "Anonymous" author, comments vanish) even
+// though the server wrote the edges correctly.
+
+function makeSync() {
+  const logger: any = {
+    child: () => logger,
+    debug: () => {}, info: () => {}, warn: () => {}, error: () => {}, trace: () => {},
+  };
+  const remote: any = { query: vi.fn() };
+  const queryId = new RecordId('_00_query', 'h1');
+  const queryState: any = { config: { id: queryId, subqueryRemoteArray: [] } };
+  const dataModule: any = { getQueryByHash: vi.fn().mockReturnValue(queryState) };
+
+  const sync = new Sp00kySync(
+    {} as any, remote, {} as any, dataModule, {} as any, logger,
+  );
+
+  // syncEngine is constructed internally; replace it with a spy.
+  const syncRecords = vi.fn().mockResolvedValue(undefined);
+  (sync as any).syncEngine = { syncRecords };
+  // Pin the resolved per-user list_ref table (auth routing is out of scope here).
+  (sync as any).listRefTable = () => '_00_list_ref_user_x';
+
+  const run = (hash: string) => (sync as any).syncSubqueryChildren(hash) as Promise<void>;
+  return { remote, syncRecords, queryState, queryId, run };
+}
+
+describe('syncSubqueryChildren — related-child delivery', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('reads the subquery edges (parent IS NOT NONE) scoped to the query id', async () => {
+    const { remote, run, queryId } = makeSync();
+    remote.query.mockResolvedValue([[]]);
+
+    await run('h1');
+
+    expect(remote.query).toHaveBeenCalledWith(
+      buildSubqueryListRefSelect('_00_list_ref_user_x'),
+      { in: queryId }
+    );
+  });
+
+  it('forwards each subquery child id to the sync engine so its body is cached', async () => {
+    const { remote, syncRecords, run } = makeSync();
+    // Server has one author child edge for this query.
+    remote.query.mockResolvedValue([[
+      { out: new RecordId('user', 'u'), version: 1 },
+    ]]);
+
+    await run('h1');
+
+    expect(syncRecords).toHaveBeenCalledTimes(1);
+    const arg = syncRecords.mock.calls[0][0];
+    expect(arg.added).toHaveLength(1);
+    expect(encodeRecordId(arg.added[0].id)).toBe('user:u');
+    expect(arg.added[0].version).toBe(1);
+    expect(arg.removed).toEqual([]); // shared child bodies are never deleted here
+  });
+
+  it('is idempotent: unchanged edges do not refetch bodies', async () => {
+    const { remote, syncRecords, run, queryState } = makeSync();
+    queryState.config.subqueryRemoteArray = [['user:u', 1]];
+    remote.query.mockResolvedValue([[
+      { out: new RecordId('user', 'u'), version: 1 },
+    ]]);
+
+    await run('h1');
+
+    expect(syncRecords).not.toHaveBeenCalled();
+  });
+});

package/src/services/database/local-migrator.ts

@@ -45,6 +45,7 @@ export class LocalMigrator {
     const systemSchema = `
       DEFINE TABLE IF NOT EXISTS _00_stream_processor_state SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;
       DEFINE TABLE IF NOT EXISTS _00_query SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;
+      DEFINE TABLE IF NOT EXISTS _00_preload SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;
       DEFINE TABLE IF NOT EXISTS _00_schema SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;
       DEFINE TABLE IF NOT EXISTS _00_pending_mutations SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;
     `;

package/src/services/database/plan-render.test.ts

@@ -51,7 +51,7 @@ describe('renderRelationFetchSurql', () => {
       where: [{ field: 'hidden', op: '=', value: false }],
       orderBy: [['rank', 'asc']],
     });
-    expect(sql).toBe('SELECT * FROM comment WHERE post IN $__keys AND hidden = $__p0 ORDER BY rank asc;');
+    expect(sql).toBe('SELECT * FROM comment WHERE post IN $__keys.map(|$__k| type::record(<string> $__k)) AND hidden = $__p0 ORDER BY rank asc;');
     expect(vars).toEqual({ __keys: ['post:1', 'post:2'], __p0: false });
   });
 });

package/src/services/database/plan-render.ts

@@ -77,7 +77,12 @@ export function renderRelationFetchSurql(req: RelationFetch): RenderedQuery {
   const ctx: RenderCtx = { vars: { __keys: req.keys }, n: 0 };
   const projection =
     req.select && req.select.length > 0 ? ['id', ...req.select].join(', ') : '*';
-  let sql = `SELECT ${projection} FROM ${req.table} WHERE ${req.matchField} IN $__keys`;
+  // The correlation keys arrive as record-id STRINGS (`"user:abc"`), but the
+  // matched column (`id`, or a `record<…>` foreign key) is a RecordId. In
+  // SurrealDB `id IN ["user:abc"]` never matches (string ≠ record), so every
+  // `.related()` field would resolve empty. Coerce each key to a record id with
+  // `type::record(<string> …)` (idempotent if a key is already a RecordId).
+  let sql = `SELECT ${projection} FROM ${req.table} WHERE ${req.matchField} IN $__keys.map(|$__k| type::record(<string> $__k))`;
   if (req.where && req.where.length > 0) {
     sql += ` AND ${renderWhereSurql(req.where, ctx)}`;
   }

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

@@ -106,7 +106,10 @@ export class SqliteCacheEngine implements LocalStore {
   // ---- worker plumbing -----------------------------------------------------
 
   private spawnWorker(): Worker {
-    // The worker is a separate module entry; the bundler rewrites this URL.
+    // The worker is a separate tsdown entry emitted at `dist/sqlite-worker.js`
+    // (see tsdown.config.ts). This URL must point at the emitted `.js` so it
+    // resolves after bundling into the flat `dist/index.js`; a `.ts` here ships
+    // a dangling reference the consumer's bundler can't resolve.
     const worker = new Worker(new URL('./sqlite-worker.js', import.meta.url), { type: 'module' });
     worker.onmessage = (ev: MessageEvent) => {
       const { id, ok, error, ...rest } = ev.data ?? {};

package/src/sp00ky.ts

@@ -5,6 +5,7 @@ import type {
   QueryStatusCallback,
   Sp00kyQueryResultPromise,
   PersistenceClient,
+  PreloadOptions,
   UpdateOptions,
   RunOptions,
   SyncHealth} from './types';
@@ -17,6 +18,7 @@ import type { LocalStore } from './services/database/index';
 import type { UpEvent } from './modules/sync/index';
 import { Sp00kySync } from './modules/sync/index';
 import type {
+  FinalQuery,
   GetTable,
   InnerQuery,
   QueryOptions,
@@ -44,7 +46,7 @@ import { FeatureFlagModule, FeatureFlagHandle } from './modules/feature-flag/ind
 import type { FeatureFlagOptions } from './modules/feature-flag/index';
 import { LocalStoragePersistenceClient } from './services/persistence/localstorage';
 import { ANON_USER_ID, bucketIdForUser } from './modules/ref-tables';
-import { parseParams, encodeRecordId } from './utils/index';
+import { parseParams, encodeRecordId, parseDuration } from './utils/index';
 import { SurrealDBPersistenceClient } from './services/persistence/surrealdb';
 import { ResilientPersistenceClient } from './services/persistence/resilient';
 
@@ -128,6 +130,10 @@ export class Sp00kyClient<S extends SchemaStructure> {
   private devTools: DevToolsService;
   private crdtManager: CrdtManager;
   private featureFlags!: FeatureFlagModule<S>;
+  // Query hashes already preloaded this session — skip redundant one-shot
+  // fetches when the same preload query is requested again (e.g. a list row
+  // re-rendering). Cleared on process/session end only.
+  private preloadedHashes = new Set<number>();
 
   private logger: ReturnType<typeof createLogger>;
   public auth: AuthService<S>;
@@ -510,15 +516,32 @@ export class Sp00kyClient<S extends SchemaStructure> {
   private ensureLocalBucket(userId: string | null): Promise<void> {
     const target = bucketIdForUser(userId);
     this.pendingBucketTarget = target;
+    // Close the query gate SYNCHRONOUSLY the instant a switch is pending — the
+    // AuthProvider's own auth subscriber fires right after this (same tick) and
+    // enables queries, and `doSwitchBucket` only runs a microtask later on the
+    // chain. Without closing the gate here, that query is issued through the
+    // still-open gate and is in-flight on the local wasm engine when
+    // `switchStore` closes the client — which wedges the engine (every
+    // subsequent query, including provisioning, hangs → no view ever registers).
+    // No-op when already on the target bucket.
+    const needsSwitch = this.local.currentBucketId !== target;
+    const release = needsSwitch ? this.local.beginSwitch() : null;
     this.bucketSwitchChain = this.bucketSwitchChain.then(async () => {
-      if (this.pendingBucketTarget !== target) return; // superseded by a newer flip
-      if (this.local.currentBucketId === target) return;
-      await this.doSwitchBucket(target);
+      // Superseded by a newer flip, or already on target: reopen the gate we
+      // closed above and skip the switch.
+      if (this.pendingBucketTarget !== target || this.local.currentBucketId === target) {
+        release?.();
+        return;
+      }
+      await this.doSwitchBucket(target, release);
     });
     // Isolate chain failures per-caller: a failed switch must not poison every
-    // future switch. The caller (auth listener) logs it.
+    // future switch. The caller (auth listener) logs it. Reopen the gate on
+    // failure so the client never gets stuck closed.
     const result = this.bucketSwitchChain;
-    this.bucketSwitchChain = this.bucketSwitchChain.catch(() => {});
+    this.bucketSwitchChain = this.bucketSwitchChain.catch(() => {
+      release?.();
+    });
     return result;
   }
 
@@ -542,7 +565,7 @@ export class Sp00kyClient<S extends SchemaStructure> {
    * re-homed keeping their hashes, sync resumed on the new bucket's own
    * outbox, and every query re-registered remotely to refill from the server.
    */
-  private async doSwitchBucket(target: string): Promise<void> {
+  private async doSwitchBucket(target: string, gateRelease?: (() => void) | null): Promise<void> {
     this.logger.info(
       { target, from: this.local.currentBucketId, Category: 'sp00ky-client::Sp00kyClient::doSwitchBucket' },
       'Switching local bucket'
@@ -552,7 +575,10 @@ export class Sp00kyClient<S extends SchemaStructure> {
     this.dataModule.quiesce();
     this.crdtManager.closeAll({ flush: false });
 
-    const reopen = this.local.beginSwitch();
+    // Reuse the gate the caller (`ensureLocalBucket`) closed synchronously; only
+    // open our own if called without one (keeps the gate continuously closed
+    // from the auth flip through the swap — no window for a racing query).
+    const reopen = gateRelease ?? this.local.beginSwitch();
     try {
       await this.local.switchStore(target);
       if (this.local.usesSurqlSchema) {
@@ -701,6 +727,90 @@ export class Sp00kyClient<S extends SchemaStructure> {
     return hash;
   }
 
+  /**
+   * Smart, awaitable preload/prewarm into the LOCAL cache — without registering a
+   * live view (NO `_00_query`, NO subscription, NO TTL heartbeat).
+   *
+   * Cache-aware via a durable per-bucket freshness marker (`_00_preload`):
+   * - COLD (never preloaded in this bucket): fetch the query one-shot from the
+   *   remote, persist the rows (+ embedded `.related()` children), stamp the
+   *   marker — and AWAIT it. This is the "smart waiting" first load: callers can
+   *   `await db.preload(...)` to hold the UI until the data is ready.
+   * - WARM (marker present): return instantly — NEVER blocks. `refresh` decides
+   *   whether to also kick a one-time silent refetch (see {@link PreloadOptions}).
+   *   Default `onUse` does nothing; the data freshens when the real `useQuery`
+   *   mounts and registers its live view.
+   *
+   * Best-effort: any fetch failure (offline, etc.) is a no-op warn (no marker
+   * written, so it's retried next load). Deduped per session by query hash.
+   */
+  async preload(
+    finalQuery: FinalQuery<S, any, any, any, any, any>,
+    options?: PreloadOptions
+  ): Promise<void> {
+    const q = finalQuery.innerQuery;
+    if (this.preloadedHashes.has(q.hash)) return;
+
+    const tableName = q.tableName;
+    const tableSchema = this.config.schema.tables.find((t) => t.name === tableName);
+    if (!tableSchema) {
+      throw new Error(`Table ${tableName} not found`);
+    }
+    const params = parseParams(tableSchema.columns, q.selectQuery.vars ?? {});
+    const hashKey = String(q.hash);
+
+    const marker = await this.dataModule.getPreloadMarker(hashKey);
+
+    // COLD → fetch + persist + stamp, awaited so the caller can block on it.
+    if (!marker) {
+      const rowCount = await this.fetchAndPersist(q, tableName, params);
+      if (rowCount >= 0) {
+        await this.dataModule.writePreloadMarker(hashKey, rowCount);
+        this.preloadedHashes.add(q.hash);
+      }
+      return;
+    }
+
+    // WARM → never block. Mark handled for this session, then optionally refresh.
+    this.preloadedHashes.add(q.hash);
+    const refresh = options?.refresh ?? 'onUse';
+    if (refresh === 'onUse') return;
+
+    if (refresh === 'stale') {
+      const maxAgeMs = parseDuration(options?.staleTime ?? '1h');
+      if (Date.now() - marker.fetchedAt <= maxAgeMs) return; // still fresh
+    }
+
+    // `background`, or `stale` past its staleTime → one-time silent refetch.
+    void this.fetchAndPersist(q, tableName, params).then((rowCount) => {
+      if (rowCount >= 0) return this.dataModule.writePreloadMarker(hashKey, rowCount);
+    });
+  }
+
+  /**
+   * One-shot remote fetch + local persist for a preload query. Returns the row
+   * count on success, or -1 on failure (best-effort: logged, never thrown) so
+   * the caller skips stamping the freshness marker and retries next load.
+   */
+  private async fetchAndPersist(
+    q: InnerQuery<any, any, any>,
+    tableName: string,
+    params: Record<string, any>
+  ): Promise<number> {
+    try {
+      const [rows] = await this.remote.query<[RecordWithId[]]>(q.selectQuery.query, params);
+      const list = rows ?? [];
+      await this.dataModule.persistSnapshot(tableName, list);
+      return list.length;
+    } catch (err) {
+      this.logger.warn(
+        { err, hash: q.hash, Category: 'sp00ky-client::Sp00kyClient::preload' },
+        'Preload fetch failed; data will be fetched on demand'
+      );
+      return -1;
+    }
+  }
+
   async queryRaw(sql: string, params: Record<string, any>, ttl: QueryTimeToLive) {
     const tableName = sql.split('FROM ')[1].split(' ')[0];
     return this.dataModule.query(tableName, sql, params, ttl);

package/src/types.ts

@@ -68,6 +68,24 @@ export type QueryTimeToLive =
   | '12h'
   | '1d';
 
+/**
+ * Refresh behavior for `preload` when the data is already cached locally (warm).
+ * The FIRST load (cold) always fetches + blocks regardless.
+ * - `onUse` (default): do nothing when warm — the data freshens on use, when the
+ *   real `useQuery` mounts and registers its live view. No network on load.
+ * - `background`: return instantly, but kick a one-time silent refetch.
+ * - `stale`: like `background`, but only if the cached copy is older than
+ *   `staleTime`.
+ */
+export type PreloadRefresh = 'onUse' | 'background' | 'stale';
+
+export interface PreloadOptions {
+  /** How to refresh when the query is already cached locally. Default `onUse`. */
+  refresh?: PreloadRefresh;
+  /** For `refresh: 'stale'` — max age before a warm copy is refetched. Default `1h`. */
+  staleTime?: QueryTimeToLive;
+}
+
 /**
  * Result object returned when a query is registered or executed.
  */