@spooky-sync/client-solid 0.0.1-canary.27 → 0.0.1-canary.271

package/dist/index.cjs

@@ -2,12 +2,13 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 let _spooky_sync_core = require("@spooky-sync/core");
 let surrealdb = require("surrealdb");
 let solid_js = require("solid-js");
+let solid_js_store = require("solid-js/store");
 
 //#region src/lib/context.ts
-const SpookyContext = (0, solid_js.createContext)();
+const Sp00kyContext = (0, solid_js.createContext)();
 function useDb() {
-	const db = (0, solid_js.useContext)(SpookyContext);
-	if (!db) throw new Error("useDb must be used within a <SpookyProvider>. Wrap your app in <SpookyProvider config={...}>.");
+	const db = (0, solid_js.useContext)(Sp00kyContext);
+	if (!db) throw new Error("useDb must be used within a <Sp00kyProvider>. Wrap your app in <Sp00kyProvider config={...}>.");
 	return db;
 }
 
@@ -22,30 +23,73 @@ function useQuery(dbOrQuery, queryOrOptions, maybeOptions) {
 		finalQuery = queryOrOptions;
 		options = maybeOptions;
 	} else {
-		const contextDb = (0, solid_js.useContext)(SpookyContext);
-		if (!contextDb) throw new Error("useQuery: No db argument provided and no SpookyContext found. Either pass a SyncedDb instance or wrap your app in <SpookyProvider>.");
+		const contextDb = (0, solid_js.useContext)(Sp00kyContext);
+		if (!contextDb) throw new Error("useQuery: No db argument provided and no Sp00kyContext found. Either pass a SyncedDb instance or wrap your app in <Sp00kyProvider>.");
 		db = contextDb;
 		finalQuery = dbOrQuery;
 		options = queryOrOptions;
 	}
-	const [data, setData] = (0, solid_js.createSignal)(void 0);
 	const [error, setError] = (0, solid_js.createSignal)(void 0);
 	const [isFetched, setIsFetched] = (0, solid_js.createSignal)(false);
-	const [unsubscribe, setUnsubscribe] = (0, solid_js.createSignal)(void 0);
+	const [isFetching, setIsFetching] = (0, solid_js.createSignal)(false);
+	const [state, setState] = (0, solid_js_store.createStore)({ value: void 0 });
+	const [version, setVersion] = (0, solid_js.createSignal)(0);
+	const data = () => {
+		version();
+		return state.value;
+	};
 	let prevQueryString;
-	const spooky = db.getSpooky();
-	const initQuery = async (query) => {
+	let runId = 0;
+	let activeUnsub;
+	let activeHash;
+	const teardownActive = () => {
+		activeUnsub?.();
+		activeUnsub = void 0;
+	};
+	const sp00ky = db.getSp00ky();
+	/**
+	* Registration can fail — the canonical case is the SSP answering 503
+	* NOT_READY while it bootstraps. Nothing here used to catch that: the
+	* rejection escaped as an unhandled promise, `isFetched` stayed false, and
+	* `isLoading()` therefore stayed true FOREVER, which is what a spinner that
+	* never resolves actually was. Surface it as `error()` instead; the sync
+	* scheduler retries the registration underneath, so a transient failure
+	* still recovers on its own.
+	*/
+	const initQuery = async (query, myRun) => {
+		try {
+			await subscribeQuery(query, myRun);
+		} catch (err) {
+			if (myRun !== runId) return;
+			setError(err instanceof Error ? err : new Error(String(err)));
+		}
+	};
+	const subscribeQuery = async (query, myRun) => {
 		const { hash } = await query.run();
+		if (myRun !== runId) return;
+		activeHash = hash;
 		setError(void 0);
 		let isFirstCall = true;
-		const unsub = await spooky.subscribe(hash, (e) => {
-			const data = query.isOne ? e[0] : e;
-			setData(() => data);
-			const hasData = query.isOne ? data != null : e.length > 0;
+		const unsub = await sp00ky.subscribe(hash, (e) => {
+			const queryData = query.isOne ? e[0] : e;
+			const reconcileStart = performance.now();
+			setState("value", (0, solid_js_store.reconcile)(queryData, { key: "id" }));
+			setVersion((v) => v + 1);
+			sp00ky.reportFrontendTiming(hash, performance.now() - reconcileStart);
+			const hasData = query.isOne ? queryData !== null && queryData !== void 0 : e.length > 0;
 			if (!isFirstCall || hasData) setIsFetched(true);
 			isFirstCall = false;
 		}, { immediate: true });
-		setUnsubscribe(() => unsub);
+		const unsubStatus = sp00ky.subscribeQueryStatus(hash, (status) => setIsFetching(status === "fetching"), { immediate: true });
+		const teardown = () => {
+			unsub();
+			unsubStatus();
+		};
+		if (myRun !== runId) {
+			teardown();
+			return;
+		}
+		activeUnsub = teardown;
 	};
 	(0, solid_js.createEffect)(() => {
 		if (!(options?.enabled?.() ?? true)) {
@@ -54,22 +98,257 @@ function useQuery(dbOrQuery, queryOrOptions, maybeOptions) {
 		}
 		const query = typeof finalQuery === "function" ? finalQuery() : finalQuery;
 		if (!query) return;
-		const queryString = JSON.stringify(query);
+		const queryString = String(query.hash);
 		if (queryString === prevQueryString) return;
 		prevQueryString = queryString;
+		const myRun = ++runId;
+		teardownActive();
 		setIsFetched(false);
-		initQuery(query);
-		(0, solid_js.onCleanup)(() => {
-			unsubscribe()?.();
-		});
+		setError(void 0);
+		initQuery(query, myRun);
+	});
+	(0, solid_js.onCleanup)(() => {
+		runId++;
+		teardownActive();
+		if (options?.deregisterOnCleanup && activeHash) sp00ky.deregisterQuery(activeHash);
 	});
 	const isLoading = () => {
 		return !isFetched() && error() === void 0;
 	};
+	const isSettled = () => isFetched() && !isFetching();
 	return {
 		data,
 		error,
-		isLoading
+		isLoading,
+		isFetching,
+		isSettled
+	};
+}
+
+//#endregion
+//#region src/lib/create-preload.ts
+/**
+* Reactive, fire-and-forget prewarm. Resolves the query (calling it if it's a
+* function so it tracks reactive deps), dedupes on the query's stable identity
+* hash, and registers it via `db.preload`: a live query nobody subscribes to,
+* evicted a ttl after it was registered unless a view mounts it first. Nothing
+* to clean up here.
+*
+* Typical use: inside a list row, preload the detail query the user is likely
+* to open next, so navigation paints from cache instead of the network.
+*/
+function createPreload(dbOrQuery, queryOrOptions, maybeOptions) {
+	let db;
+	let finalQuery;
+	let options;
+	if (dbOrQuery instanceof SyncedDb) {
+		db = dbOrQuery;
+		finalQuery = queryOrOptions;
+		options = maybeOptions;
+	} else {
+		const contextDb = (0, solid_js.useContext)(Sp00kyContext);
+		if (!contextDb) throw new Error("createPreload: No db argument provided and no Sp00kyContext found. Either pass a SyncedDb instance or wrap your app in <Sp00kyProvider>.");
+		db = contextDb;
+		finalQuery = dbOrQuery;
+		options = queryOrOptions;
+	}
+	let prevHash;
+	(0, solid_js.createEffect)(() => {
+		if (!(options?.enabled?.() ?? true)) return;
+		const query = typeof finalQuery === "function" ? finalQuery() : finalQuery;
+		if (!query) return;
+		if (query.hash === prevHash) return;
+		prevHash = query.hash;
+		db.getSp00ky().preload(query, { signal: options?.signal });
+	});
+}
+
+//#endregion
+//#region src/lib/use-sync-status.ts
+/**
+* Observe sync health for a "can't reach the server" banner / indicator.
+*
+* Backed by `db.subscribeToSyncHealth`. Individual sync failures (a transient
+* remote 500 on query registration, a dropped socket) are absorbed by the
+* retry and never flip this; `isDegraded()` only goes true once failures
+* persist for the configured number of consecutive rounds (sp00ky core config
+* `syncHealth.degradeAfterConsecutiveFailures`, default 3), and flips back on
+* the next successful round. Must be used within a `<Sp00kyProvider>`.
+*/
+function useSyncStatus() {
+	const db = useDb();
+	const [health, setHealth] = (0, solid_js.createSignal)(db.syncHealth);
+	(0, solid_js.onCleanup)(db.subscribeToSyncHealth(setHealth));
+	return {
+		health,
+		status: () => health().status,
+		isHealthy: () => health().status === "healthy",
+		isDegraded: () => health().status === "degraded",
+		everConnected: () => health().everConnected,
+		isOffline: () => health().status === "degraded" && health().everConnected,
+		connection: () => health().connection,
+		isReconnecting: () => health().connection === "reconnecting"
+	};
+}
+
+//#endregion
+//#region src/lib/use-impersonation.ts
+/**
+* Observe admin impersonation (started from the DevTools). The client already
+* shows its own warning bar with a Stop button; use this for anything extra,
+* such as hiding actions an admin should not take on someone's behalf.
+* Must be used within a `<Sp00kyProvider>`.
+*/
+function useImpersonation(options = {}) {
+	const db = useDb();
+	const [impersonation, setImpersonation] = (0, solid_js.createSignal)(db.auth.impersonation);
+	(0, solid_js.onCleanup)(db.auth.subscribeImpersonation(setImpersonation));
+	(0, solid_js.createEffect)(() => {
+		if (options.rendersBanner && impersonation()) db.acknowledgeImpersonationBanner();
+	});
+	return {
+		impersonation,
+		isImpersonating: () => impersonation() !== null,
+		stop: () => db.auth.stopImpersonating()
+	};
+}
+
+//#endregion
+//#region src/lib/use-storage-status.ts
+/**
+* Observe how durable the LOCAL cache is, for a "no local storage" warning.
+*
+* Under `localEngine: 'sqlite'` with `store: 'indexeddb'` the durable store is
+* the OPFS SAHPool VFS, and only ONE client per bucket can hold it open: a
+* second tab of the same app cannot get it and runs in memory instead (the
+* engine retries first, so a closing tab's lock is usually waited out). Must be
+* used within a `<Sp00kyProvider>`.
+*/
+function useStorageStatus() {
+	const db = useDb();
+	const [health, setHealth] = (0, solid_js.createSignal)(db.storageHealth);
+	(0, solid_js.onCleanup)(db.subscribeToStorageHealth(setHealth));
+	return {
+		health,
+		status: () => health().status,
+		isPersistent: () => health().status === "persistent",
+		isMemoryFallback: () => health().fallback
+	};
+}
+
+//#endregion
+//#region src/lib/use-crdt-field.ts
+function useCrdtField(table, recordId, field, fallbackText) {
+	const db = (0, solid_js.useContext)(Sp00kyContext);
+	if (!db) throw new Error("useCrdtField must be used within a <Sp00kyProvider>");
+	const [crdtField, setCrdtField] = (0, solid_js.createSignal)(null);
+	let currentId;
+	let initialized = false;
+	(0, solid_js.createEffect)(() => {
+		const id = recordId();
+		if (initialized && id === currentId) return;
+		if (currentId && crdtField()) {
+			db.getSp00ky().closeCrdtField(table, currentId, field);
+			setCrdtField(null);
+		}
+		currentId = id;
+		initialized = true;
+		if (!id) return;
+		const sp00ky = db.getSp00ky();
+		const text = fallbackText?.();
+		sp00ky.openCrdtField(table, id, field, text).then((cf) => {
+			if (currentId === id) setCrdtField(cf);
+		}).catch((err) => {
+			console.error(`[useCrdtField] Failed to open CRDT field ${table}.${field} on ${id}:`, err);
+		});
+	});
+	(0, solid_js.onCleanup)(() => {
+		if (currentId && crdtField()) {
+			db.getSp00ky().closeCrdtField(table, currentId, field);
+			setCrdtField(null);
+		}
+	});
+	return crdtField;
+}
+
+//#endregion
+//#region src/lib/use-feature-flag.ts
+/**
+* Subscribe to a feature flag for the currently authenticated user.
+*
+* Returns three Solid accessors that update reactively whenever the
+* server-materialized assignment in `_00_user_feature` changes. Backed by
+* the same SSP + sync pipeline that powers `useQuery`, so toggling a flag
+* via `spky flag enable <key>` propagates to the UI without a refresh.
+*
+* `enabled()` is `true` when the resolved variant exists and is not 'off'.
+* For multi-variant flags, prefer `variant()` directly.
+*/
+function useFeatureFlag(key, options) {
+	const handle = useDb().getSp00ky().feature(key, options);
+	const [variant, setVariant] = (0, solid_js.createSignal)(handle.variant());
+	const [payload, setPayload] = (0, solid_js.createSignal)(handle.payload());
+	const unsub = handle.subscribe((s) => {
+		setVariant(s.variant ?? options?.fallback);
+		setPayload(s.payload);
+	});
+	(0, solid_js.onCleanup)(() => {
+		unsub();
+		handle.close();
+	});
+	return {
+		variant,
+		payload,
+		enabled: () => {
+			const v = variant();
+			return v !== void 0 && v !== "off";
+		}
+	};
+}
+
+//#endregion
+//#region src/lib/use-app-release.ts
+async function reloadForSnapshot(snapshot) {
+	if (typeof window === "undefined") return;
+	if (snapshot.cacheBust) try {
+		if (window.caches) {
+			const keys = await window.caches.keys();
+			await Promise.all(keys.map((k) => window.caches.delete(k)));
+		}
+		if (navigator.serviceWorker) {
+			const regs = await navigator.serviceWorker.getRegistrations();
+			for (const r of regs) r.update().catch(() => {});
+		}
+		window.location.href = window.location.pathname + "?cb=" + Date.now();
+		return;
+	} catch {}
+	window.location.reload();
+}
+/**
+* Observe the app's announced release (`_00_app_release:<app>`, written by
+* `spky deploy` / `spky release`) and compare it against the running build.
+*
+* Typical use: mount a small "new version available — Reload" notification
+* gated on `updateAvailable()`, auto-invoking `reload()` when `mandatory()`
+* (guard the auto path against reload loops with a per-version marker, since
+* a client can reload while the deploy is still rolling out and land on the
+* old bundle again).
+*/
+function useAppRelease(options) {
+	const handle = useDb().getSp00ky().appRelease(options.app, { ttl: options.ttl });
+	const [snapshot, setSnapshot] = (0, solid_js.createSignal)(handle.snapshot());
+	const unsub = handle.subscribe(setSnapshot);
+	(0, solid_js.onCleanup)(() => {
+		unsub();
+		handle.close();
+	});
+	const updateAvailable = () => (0, _spooky_sync_core.semverGt)(snapshot().version, options.currentVersion);
+	return {
+		latestVersion: () => snapshot().version,
+		updateAvailable,
+		mandatory: () => updateAvailable() && snapshot().mandatory,
+		cacheBust: () => snapshot().cacheBust,
+		reload: () => reloadForSnapshot(snapshot())
 	};
 }
 
@@ -95,7 +374,7 @@ function useFileUpload(dbOrBucketName, maybeBucketName) {
 	const validate = (file) => {
 		const config = db.getBucketConfig(bucketName);
 		if (!config) return;
-		if (config.maxSize != null && file.size > config.maxSize) {
+		if (config.maxSize !== null && config.maxSize !== void 0 && file.size > config.maxSize) {
 			const maxMB = (config.maxSize / (1024 * 1024)).toFixed(1);
 			throw new Error(`File exceeds maximum size of ${maxMB} MB.`);
 		}
@@ -107,7 +386,7 @@ function useFileUpload(dbOrBucketName, maybeBucketName) {
 			}
 		}
 	};
-	const upload = async (path, file) => {
+	const upload = async (path, file, options) => {
 		setError(null);
 		try {
 			validate(file);
@@ -118,7 +397,7 @@ function useFileUpload(dbOrBucketName, maybeBucketName) {
 		setIsUploading(true);
 		try {
 			const bytes = await (0, _spooky_sync_core.fileToUint8Array)(file);
-			await db.bucket(bucketName).put(path, bytes);
+			return await db.bucket(bucketName).put(path, bytes, options);
 		} catch (e) {
 			setError(e instanceof Error ? e : new Error(String(e)));
 		} finally {
@@ -168,20 +447,6 @@ function useFileUpload(dbOrBucketName, maybeBucketName) {
 
 //#endregion
 //#region src/lib/use-download-file.ts
-const downloadCache = /* @__PURE__ */ new Map();
-const inflightRequests = /* @__PURE__ */ new Map();
-function cacheKey(bucket, path) {
-	return `${bucket}:${path}`;
-}
-function releaseEntry(key) {
-	const entry = downloadCache.get(key);
-	if (!entry) return;
-	entry.refCount--;
-	if (entry.refCount <= 0) {
-		URL.revokeObjectURL(entry.url);
-		downloadCache.delete(key);
-	}
-}
 function useDownloadFile(dbOrBucketName, bucketNameOrPath, pathOrOptions, maybeOptions) {
 	let db;
 	let bucketName;
@@ -202,63 +467,15 @@ function useDownloadFile(dbOrBucketName, bucketNameOrPath, pathOrOptions, maybeO
 	const [url, setUrl] = (0, solid_js.createSignal)(null);
 	const [isLoading, setIsLoading] = (0, solid_js.createSignal)(false);
 	const [error, setError] = (0, solid_js.createSignal)(null);
-	let currentKey = null;
+	let lease = null;
 	let privateUrl = null;
-	let refetchTrigger;
 	const [refetchSignal, setRefetchSignal] = (0, solid_js.createSignal)(0);
-	refetchTrigger = () => setRefetchSignal((n) => n + 1);
-	async function doDownload(key, filePath) {
-		if (useCache) {
-			const cached = downloadCache.get(key);
-			if (cached) {
-				cached.refCount++;
-				currentKey = key;
-				return cached.url;
-			}
-			const inflight = inflightRequests.get(key);
-			if (inflight) {
-				const result = await inflight;
-				if (result) {
-					const entry = downloadCache.get(key);
-					if (entry) {
-						entry.refCount++;
-						currentKey = key;
-					}
-				}
-				return result;
-			}
-			const promise = (async () => {
-				const content = await db.bucket(bucketName).get(filePath);
-				if (!content) return null;
-				const objectUrl = URL.createObjectURL(new Blob([content]));
-				downloadCache.set(key, {
-					url: objectUrl,
-					refCount: 1
-				});
-				return objectUrl;
-			})();
-			inflightRequests.set(key, promise);
-			try {
-				const result = await promise;
-				currentKey = key;
-				return result;
-			} finally {
-				inflightRequests.delete(key);
-			}
-		} else {
-			const content = await db.bucket(bucketName).get(filePath);
-			if (!content) return null;
-			const objectUrl = URL.createObjectURL(new Blob([content]));
-			privateUrl = objectUrl;
-			return objectUrl;
-		}
-	}
-	function releaseCurrentEntry() {
-		if (useCache && currentKey) {
-			releaseEntry(currentKey);
-			currentKey = null;
-		}
-		if (!useCache && privateUrl) {
+	/** Consumed by the next effect run, so `refetch()` bypasses every layer once. */
+	let reloadOnce = false;
+	function releaseCurrent() {
+		lease?.release();
+		lease = null;
+		if (privateUrl) {
 			URL.revokeObjectURL(privateUrl);
 			privateUrl = null;
 		}
@@ -266,29 +483,40 @@ function useDownloadFile(dbOrBucketName, bucketNameOrPath, pathOrOptions, maybeO
 	(0, solid_js.createEffect)(() => {
 		const filePath = path();
 		refetchSignal();
-		releaseCurrentEntry();
+		releaseCurrent();
 		if (!filePath) {
 			setUrl(null);
 			setIsLoading(false);
 			setError(null);
 			return;
 		}
-		const key = cacheKey(bucketName, filePath);
-		if (useCache) {
-			const cached = downloadCache.get(key);
-			if (cached) {
-				cached.refCount++;
-				currentKey = key;
-				setUrl(cached.url);
-				setIsLoading(false);
-				setError(null);
-				return;
-			}
-		}
+		const reload = reloadOnce;
+		reloadOnce = false;
 		let cancelled = false;
 		setIsLoading(true);
 		setError(null);
-		doDownload(key, filePath).then((result) => {
+		const bucket = db.bucket(bucketName);
+		(useCache ? bucket.url(filePath, {
+			persist: options.persist !== false,
+			pin: options.pin,
+			revalidate: options.revalidate,
+			reload
+		}).then((acquired) => {
+			if (!acquired) return null;
+			if (cancelled) {
+				acquired.release();
+				return null;
+			}
+			lease = acquired;
+			return acquired.url;
+		}) : bucket.read(filePath, {
+			persist: false,
+			reload: true
+		}).then((blob) => {
+			if (!blob || cancelled) return null;
+			privateUrl = URL.createObjectURL(blob);
+			return privateUrl;
+		})).then((result) => {
 			if (!cancelled) {
 				setUrl(result);
 				setIsLoading(false);
@@ -304,18 +532,11 @@ function useDownloadFile(dbOrBucketName, bucketNameOrPath, pathOrOptions, maybeO
 		});
 	});
 	(0, solid_js.onCleanup)(() => {
-		releaseCurrentEntry();
+		releaseCurrent();
 	});
 	const refetch = () => {
-		if (useCache && currentKey) {
-			const entry = downloadCache.get(currentKey);
-			if (entry) {
-				URL.revokeObjectURL(entry.url);
-				downloadCache.delete(currentKey);
-			}
-			currentKey = null;
-		}
-		refetchTrigger();
+		reloadOnce = true;
+		setRefetchSignal((n) => n + 1);
 	};
 	return {
 		url,
@@ -326,26 +547,251 @@ function useDownloadFile(dbOrBucketName, bucketNameOrPath, pathOrOptions, maybeO
 }
 
 //#endregion
-//#region src/lib/SpookyProvider.ts
-function SpookyProvider(props) {
+//#region src/lib/use-blurhash.ts
+function useBlurhash(dbOrBucketName, bucketNameOrPath, maybePath) {
+	let db;
+	let bucketName;
+	let path;
+	if (typeof dbOrBucketName === "string") {
+		db = useDb();
+		bucketName = dbOrBucketName;
+		path = bucketNameOrPath;
+	} else {
+		db = dbOrBucketName;
+		bucketName = bucketNameOrPath;
+		path = maybePath;
+	}
+	const [hash, setHash] = (0, solid_js.createSignal)(null);
+	const [isLoading, setIsLoading] = (0, solid_js.createSignal)(false);
+	(0, solid_js.createEffect)(() => {
+		const filePath = path();
+		if (!filePath) {
+			setHash(null);
+			setIsLoading(false);
+			return;
+		}
+		let cancelled = false;
+		setIsLoading(true);
+		db.bucket(bucketName).blurhash(filePath).then((result) => {
+			if (cancelled) return;
+			setHash(result);
+			setIsLoading(false);
+		}).catch(() => {
+			if (cancelled) return;
+			setHash(null);
+			setIsLoading(false);
+		});
+		(0, solid_js.onCleanup)(() => {
+			cancelled = true;
+		});
+	});
+	return {
+		hash,
+		isLoading
+	};
+}
+
+//#endregion
+//#region src/lib/use-bucket-image.ts
+function useBucketImage(dbOrBucketName, bucketNameOrPath, pathOrOptions, maybeOptions) {
+	let db;
+	let bucketName;
+	let path;
+	let options;
+	if (typeof dbOrBucketName === "string") {
+		db = useDb();
+		bucketName = dbOrBucketName;
+		path = bucketNameOrPath;
+		options = pathOrOptions ?? {};
+	} else {
+		db = dbOrBucketName;
+		bucketName = bucketNameOrPath;
+		path = pathOrOptions;
+		options = maybeOptions ?? {};
+	}
+	const wantHash = options.blurhash !== false;
+	const { hash } = useBlurhash(db, bucketName, () => wantHash ? path() : null);
+	const file = useDownloadFile(db, bucketName, path, options);
+	const [ready, setReady] = (0, solid_js.createSignal)(false);
+	(0, solid_js.createEffect)((0, solid_js.on)(file.url, () => setReady(false), { defer: true }));
+	const gate = (img) => {
+		const done = () => setReady(true);
+		if (typeof img.decode === "function") img.decode().then(done, done);
+		else if (img.complete) done();
+		else {
+			img.onload = done;
+			img.onerror = done;
+		}
+	};
+	return {
+		...file,
+		blurhash: hash,
+		ready,
+		gate
+	};
+}
+
+//#endregion
+//#region src/lib/Blurhash.ts
+/**
+* A blurhash painted onto a canvas, once per hash change. Size the canvas via
+* `class`/`style` (e.g. `absolute inset-0 w-full h-full`); the internal decode
+* resolution stays tiny regardless of the displayed size.
+*/
+function Blurhash(props) {
+	if (typeof document === "undefined") return null;
+	const canvas = document.createElement("canvas");
+	(0, solid_js.createEffect)(() => {
+		canvas.className = props.class ?? "";
+	});
+	(0, solid_js.createEffect)(() => {
+		canvas.style.cssText = props.style ?? "";
+	});
+	(0, solid_js.createEffect)(() => {
+		const width = props.width ?? 32;
+		const height = props.height ?? 32;
+		canvas.width = width;
+		canvas.height = height;
+		const hash = props.hash;
+		if (!hash) return;
+		try {
+			const pixels = (0, _spooky_sync_core.decodeBlurhash)(hash, width, height, props.punch ?? 1);
+			const ctx = canvas.getContext("2d");
+			if (!ctx) return;
+			const imageData = ctx.createImageData(width, height);
+			imageData.data.set(pixels);
+			ctx.putImageData(imageData, 0, 0);
+		} catch {}
+	});
+	return canvas;
+}
+
+//#endregion
+//#region src/lib/BucketImage.ts
+const LAYER_STYLE = "position:absolute;inset:0;width:100%;height:100%;";
+/**
+* A bucket image that never pops in: it layers (bottom to top) your `fallback`
+* plate, the automatically stored blurhash, and the real image, which stays
+* transparent until the bitmap is DECODED and then crossfades over the
+* placeholders. Placeholder layers unmount once the fade settles. Respects
+* prefers-reduced-motion (instant swap). The container is made
+* `position: relative` unless your `class` positions it already.
+*
+* ```tsx
+* <BucketImage bucket="covers" path={row.cover_key} class="absolute inset-0"
+*              fallback={<MyPlate />} alt="" />
+* ```
+*/
+function BucketImage(props) {
+	if (typeof document === "undefined") return null;
+	const image = useBucketImage(props.bucket, () => props.path, {
+		...props.options,
+		blurhash: props.blurhash !== false
+	});
+	const reducedMotion = typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+	const root = document.createElement("div");
+	(0, solid_js.createEffect)(() => {
+		root.className = props.class ?? "";
+	});
+	(0, solid_js.onMount)(() => {
+		if (getComputedStyle(root).position === "static") root.style.position = "relative";
+	});
+	const placeholder = document.createElement("div");
+	placeholder.style.cssText = LAYER_STYLE;
+	const fallbackHolder = document.createElement("div");
+	fallbackHolder.style.cssText = LAYER_STYLE;
+	placeholder.append(fallbackHolder);
+	const resolvedFallback = (0, solid_js.children)(() => props.fallback);
+	(0, solid_js.createEffect)(() => {
+		const nodes = resolvedFallback.toArray().filter((node) => node instanceof Node);
+		fallbackHolder.replaceChildren(...nodes);
+	});
+	const hashCanvas = Blurhash({
+		get hash() {
+			return image.blurhash();
+		},
+		style: LAYER_STYLE
+	});
+	if (hashCanvas instanceof Node) placeholder.append(hashCanvas);
+	const img = document.createElement("img");
+	img.decoding = "async";
+	img.style.cssText = `${LAYER_STYLE}opacity:0;`;
+	(0, solid_js.createEffect)(() => {
+		img.className = props.imgClass ?? "";
+	});
+	(0, solid_js.createEffect)(() => {
+		img.style.objectFit = props.fit ?? "cover";
+	});
+	(0, solid_js.createEffect)(() => {
+		img.alt = props.alt ?? "";
+	});
+	(0, solid_js.createEffect)(() => {
+		img.style.transition = reducedMotion ? "none" : `opacity ${props.transition ?? 300}ms ${props.easing ?? "cubic-bezier(0.16, 1, 0.3, 1)"}`;
+	});
+	(0, solid_js.createEffect)(() => {
+		const url = image.url();
+		if (!url) {
+			img.removeAttribute("src");
+			return;
+		}
+		img.src = url;
+		image.gate(img);
+	});
+	(0, solid_js.createEffect)(() => {
+		img.style.opacity = image.ready() ? "1" : "0";
+	});
+	const [settled, setSettled] = (0, solid_js.createSignal)(false);
+	(0, solid_js.createEffect)(() => {
+		if (!image.ready()) {
+			setSettled(false);
+			return;
+		}
+		const wait = (reducedMotion ? 0 : props.transition ?? 300) + 120;
+		const timer = setTimeout(() => setSettled(true), wait);
+		(0, solid_js.onCleanup)(() => clearTimeout(timer));
+	});
+	(0, solid_js.createEffect)(() => {
+		if (settled()) placeholder.remove();
+		else if (!placeholder.isConnected) root.insertBefore(placeholder, img);
+	});
+	root.append(placeholder, img);
+	return root;
+}
+
+//#endregion
+//#region src/lib/Sp00kyProvider.ts
+function Sp00kyProvider(props) {
 	const merged = (0, solid_js.mergeProps)({ fallback: void 0 }, props);
 	const [db, setDb] = (0, solid_js.createSignal)(void 0);
+	let disposed = false;
+	(0, solid_js.onCleanup)(() => {
+		disposed = true;
+	});
 	(0, solid_js.onMount)(async () => {
 		try {
 			const instance = new SyncedDb(merged.config);
 			await instance.init();
+			if (disposed) {
+				await instance.close();
+				return;
+			}
+			if (merged.preload) try {
+				await merged.preload(instance);
+			} catch (e) {
+				console.error("Sp00kyProvider: preload failed; revealing UI anyway", e);
+			}
 			setDb(() => instance);
 			merged.onReady?.(instance);
 		} catch (e) {
 			const error = e instanceof Error ? e : new Error(String(e));
 			if (merged.onError) merged.onError(error);
-			else console.error("SpookyProvider: Failed to initialize database", error);
+			else console.error("Sp00kyProvider: Failed to initialize database", error);
 		}
 	});
 	return (0, solid_js.createMemo)(() => {
 		const instance = db();
 		if (!instance) return merged.fallback;
-		return (0, solid_js.createComponent)(SpookyContext.Provider, {
+		return (0, solid_js.createComponent)(Sp00kyContext.Provider, {
 			value: instance,
 			get children() {
 				return merged.children;
@@ -357,69 +803,94 @@ function SpookyProvider(props) {
 //#endregion
 //#region src/index.ts
 /**
-* SyncedDb - A thin wrapper around spooky-ts for Solid.js integration
-* Delegates all logic to the underlying spooky-ts instance
+* SyncedDb - A thin wrapper around sp00ky-ts for Solid.js integration
+* Delegates all logic to the underlying sp00ky-ts instance
 */
 var SyncedDb = class {
 	constructor(config) {
-		this.spooky = null;
+		this.sp00ky = null;
 		this._initialized = false;
 		this.config = config;
 	}
-	getSpooky() {
-		if (!this.spooky) throw new Error("SyncedDb not initialized");
-		return this.spooky;
+	getSp00ky() {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky;
 	}
 	/**
-	* Initialize the spooky-ts instance
+	* Initialize the sp00ky-ts instance
 	*/
 	async init() {
 		if (this._initialized) return;
-		this.spooky = new _spooky_sync_core.SpookyClient(this.config);
-		await this.spooky.init();
+		this.sp00ky = new _spooky_sync_core.Sp00kyClient(this.config);
+		await this.sp00ky.init();
 		this._initialized = true;
 	}
 	/**
+	* Tear down the client: leaves the tabs broker, closes the local store and
+	* remote socket, and frees the wasm circuit. Without this a remounted provider
+	* (or an HMR reload) strands a whole client, and the abandoned wasm heaps stay
+	* resident because V8 cannot see how much wasm memory a dropped wrapper holds.
+	*/
+	async close() {
+		const instance = this.sp00ky;
+		this.sp00ky = null;
+		this._initialized = false;
+		if (instance) await instance.close();
+	}
+	/**
 	* Create a new record in the database
 	*/
 	async create(id, payload) {
-		if (!this.spooky) throw new Error("SyncedDb not initialized");
-		await this.spooky.create(id, payload);
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		await this.sp00ky.create(id, payload);
 	}
 	/**
 	* Update an existing record in the database
 	*/
 	async update(tableName, recordId, payload, options) {
-		if (!this.spooky) throw new Error("SyncedDb not initialized");
-		await this.spooky.update(tableName, recordId, payload, options);
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		await this.sp00ky.update(tableName, recordId, payload, options);
 	}
 	/**
 	* Delete an existing record in the database
 	*/
 	async delete(tableName, selector) {
-		if (!this.spooky) throw new Error("SyncedDb not initialized");
-		if (typeof selector !== "string") throw new Error("Only string ID selectors are supported currently with core");
-		await this.spooky.delete(tableName, selector);
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		const isRecordId = selector instanceof surrealdb.RecordId || selector?.constructor?.name === "RecordId";
+		let id;
+		if (typeof selector === "string") id = selector;
+		else if (isRecordId) id = `${tableName}:${selector.id}`;
+		else throw new Error("Only string ID or RecordId selectors are supported currently with core");
+		await this.sp00ky.delete(tableName, id);
+	}
+	/**
+	* Preload/prewarm a built query into the local cache without registering a
+	* live view. Fetches once and stores the rows (+ embedded related children)
+	* locally so a later `useQuery` for the same data paints instantly. Best-effort.
+	*/
+	async preload(finalQuery, options) {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		await this.sp00ky.preload(finalQuery, options);
 	}
 	/**
 	* Query data from the database
 	*/
 	query(table) {
-		if (!this.spooky) throw new Error("SyncedDb not initialized");
-		return this.spooky.query(table, {});
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.query(table, {});
 	}
 	/**
 	* Run a backend operation
 	*/
 	async run(backend, path, payload, options) {
-		if (!this.spooky) throw new Error("SyncedDb not initialized");
-		await this.spooky.run(backend, path, payload, options);
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		await this.sp00ky.run(backend, path, payload, options);
 	}
 	/**
 	* Authenticate with the database
 	*/
 	async authenticate(token) {
-		await this.spooky?.authenticate(token);
+		await this.sp00ky?.authenticate(token);
 		return new surrealdb.RecordId("user", "me");
 	}
 	/**
@@ -430,51 +901,93 @@ var SyncedDb = class {
 		await this.signOut();
 	}
 	/**
+	* Tell the client that this app's own impersonation banner is on screen.
+	* Only needed with `impersonationBanner: { mode: 'custom' }`; the
+	* `useImpersonation({ rendersBanner: true })` hook calls it for you.
+	*/
+	acknowledgeImpersonationBanner() {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		this.sp00ky.acknowledgeImpersonationBanner();
+	}
+	/**
 	* Sign out, clear session and local storage
 	*/
 	async signOut() {
-		if (!this.spooky) throw new Error("SyncedDb not initialized");
-		await this.spooky.auth.signOut();
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		await this.sp00ky.auth.signOut();
 	}
 	/**
 	* Execute a function with direct access to the remote database connection
 	*/
 	async useRemote(fn) {
-		if (!this.spooky) throw new Error("SyncedDb not initialized");
-		return await this.spooky.useRemote(fn);
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return await this.sp00ky.useRemote(fn);
 	}
 	/**
 	* Access the remote database service directly
 	*/
 	get remote() {
-		if (!this.spooky) throw new Error("SyncedDb not initialized");
-		return this.spooky.remoteClient;
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.remoteClient;
 	}
 	/**
 	* Access the local database service directly
 	*/
 	get local() {
-		if (!this.spooky) throw new Error("SyncedDb not initialized");
-		return this.spooky.localClient;
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.localClient;
 	}
 	/**
 	* Access the auth service
 	*/
 	get auth() {
-		if (!this.spooky) throw new Error("SyncedDb not initialized");
-		return this.spooky.auth;
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.auth;
 	}
 	get pendingMutationCount() {
-		if (!this.spooky) throw new Error("SyncedDb not initialized");
-		return this.spooky.pendingMutationCount;
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.pendingMutationCount;
+	}
+	/** Diagnostic — see `Sp00kyClient.liveRetryCount`. */
+	get liveRetryCount() {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.liveRetryCount;
 	}
 	subscribeToPendingMutations(cb) {
-		if (!this.spooky) throw new Error("SyncedDb not initialized");
-		return this.spooky.subscribeToPendingMutations(cb);
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.subscribeToPendingMutations(cb);
+	}
+	/** Current sync-health snapshot. See {@link useSyncStatus}. */
+	get syncHealth() {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.syncHealth;
+	}
+	/**
+	* Observe sync health. Fires immediately with the current status and again
+	* on every healthy↔degraded transition. Prefer the `useSyncStatus` hook in
+	* components; this is the imperative escape hatch.
+	*/
+	subscribeToSyncHealth(cb) {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.subscribeToSyncHealth(cb);
+	}
+	/** Current local-store durability snapshot. See {@link useStorageStatus}. */
+	get storageHealth() {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.storageHealth;
+	}
+	/**
+	* Observe local-store durability. Fires immediately with the current snapshot
+	* and again on change. Prefer the `useStorageStatus` hook in components; this
+	* is the imperative escape hatch.
+	*/
+	subscribeToStorageHealth(cb) {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.subscribeToStorageHealth(cb);
 	}
 	bucket(name) {
-		if (!this.spooky) throw new Error("SyncedDb not initialized");
-		return this.spooky.bucket(name);
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.bucket(name);
 	}
 	getBucketConfig(name) {
 		return this.config.schema.buckets?.find((b) => b.name === name);
@@ -482,12 +995,23 @@ var SyncedDb = class {
 };
 
 //#endregion
+exports.Blurhash = Blurhash;
+exports.BucketImage = BucketImage;
 exports.RecordId = surrealdb.RecordId;
-exports.SpookyProvider = SpookyProvider;
+exports.Sp00kyProvider = Sp00kyProvider;
 exports.SyncedDb = SyncedDb;
 exports.Uuid = surrealdb.Uuid;
+exports.createPreload = createPreload;
+exports.useAppRelease = useAppRelease;
+exports.useBlurhash = useBlurhash;
+exports.useBucketImage = useBucketImage;
+exports.useCrdtField = useCrdtField;
 exports.useDb = useDb;
 exports.useDownloadFile = useDownloadFile;
+exports.useFeatureFlag = useFeatureFlag;
 exports.useFileUpload = useFileUpload;
+exports.useImpersonation = useImpersonation;
 exports.useQuery = useQuery;
+exports.useStorageStatus = useStorageStatus;
+exports.useSyncStatus = useSyncStatus;
 //# sourceMappingURL=index.cjs.map