@spooky-sync/client-solid2 0.0.1-alpha.1

package/dist/index.cjs

@@ -0,0 +1,1290 @@
+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");
+
+//#region src/lib/conflate.ts
+/**
+* Latest-wins async iterable over a subscribe-callback source.
+*
+* Bridges spooky's push-callback subscriptions into the AsyncIterable shape
+* Solid 2 computations consume natively. Each spooky emission is a full result
+* set, so intermediate values are droppable: only the newest unconsumed value
+* is buffered, and a pending pull resolves with it immediately.
+*
+* Teardown contract (probed in rc-semantics.test.ts): Solid 2 does NOT
+* terminate a superseded/disposed computation's async generator — no
+* `return()`, no `finally`. Consumers MUST call `it.return()` themselves from
+* an `onCleanup` registered synchronously in the compute scope. `return()`
+* unsubscribes (awaiting the unsubscribe if the subscribe returned a promise,
+* as `sp00ky.subscribe` does) and resolves any parked pull as done.
+*/
+function conflate(subscribe) {
+	return { [Symbol.asyncIterator]() {
+		let buffered;
+		let resolveNext;
+		let done = false;
+		const unsubMaybe = subscribe((v) => {
+			if (done) return;
+			if (resolveNext) {
+				const r = resolveNext;
+				resolveNext = void 0;
+				r({
+					value: v,
+					done: false
+				});
+			} else buffered = { v };
+		});
+		const finish = () => {
+			if (done) return;
+			done = true;
+			buffered = void 0;
+			Promise.resolve(unsubMaybe).then((unsub) => unsub()).catch(() => {});
+			if (resolveNext) {
+				const r = resolveNext;
+				resolveNext = void 0;
+				r({
+					value: void 0,
+					done: true
+				});
+			}
+		};
+		return {
+			next() {
+				if (done) return Promise.resolve({
+					value: void 0,
+					done: true
+				});
+				if (buffered) {
+					const v = buffered.v;
+					buffered = void 0;
+					return Promise.resolve({
+						value: v,
+						done: false
+					});
+				}
+				return new Promise((r) => resolveNext = r);
+			},
+			return() {
+				finish();
+				return Promise.resolve({
+					value: void 0,
+					done: true
+				});
+			},
+			throw(e) {
+				finish();
+				return Promise.reject(e);
+			}
+		};
+	} };
+}
+
+//#endregion
+//#region src/lib/from-subscription.ts
+/**
+* Reactive view over a spooky subscribe-callback API.
+*
+* The memo's async generator pulls from a conflated (latest-wins) iterator;
+* `initial` is committed as the memo's `loadingValue`, so the accessor is
+* readable synchronously from birth and never suspends. Spooky's subscribe
+* APIs fire immediately with the current value, so the real value lands within
+* a tick of the first read.
+*
+* Teardown is manual by contract (see conflate.ts): onCleanup terminates the
+* iterator, which unsubscribes.
+*/
+function fromSubscription(subscribe, initial) {
+	return (0, solid_js.createMemo)(async function* () {
+		const it = conflate(subscribe)[Symbol.asyncIterator]();
+		(0, solid_js.onCleanup)(() => void it.return?.());
+		while (true) {
+			const r = await it.next();
+			if (r.done) break;
+			yield r.value;
+		}
+	}, { loadingValue: initial });
+}
+
+//#endregion
+//#region src/lib/context.ts
+const Sp00kyContext = (0, solid_js.createContext)();
+function useDb() {
+	try {
+		return (0, solid_js.useContext)(Sp00kyContext);
+	} catch {
+		throw new Error("useDb must be used within a <Sp00kyProvider>. Wrap your app in <Sp00kyProvider config={...}>.");
+	}
+}
+/**
+* Count of locally-committed mutations not yet acknowledged by the server.
+* Drive an "unsaved changes" indicator off this.
+*/
+function usePendingMutations() {
+	const db = useDb();
+	return fromSubscription((cb) => db.subscribeToPendingMutations(cb), db.pendingMutationCount);
+}
+
+//#endregion
+//#region src/lib/merge-rows.ts
+/**
+* Keyed in-place merge of a fresh row list into a store draft array.
+*
+* Why not `reconcile(rows, 'id')`: in Solid 2 rc.1 a reconcile REPLACES the row
+* objects, so a component that captured `data()[0]` sees a different object
+* after the next emission, and anything keyed on row identity (`<For>` without
+* an explicit key, a memo comparing rows) re-creates its subtree on every live
+* update. Mutating the draft in place keeps the identity AND keeps updates
+* fine-grained: only the fields that actually changed are written, so a row
+* whose data is unchanged notifies nobody.
+*
+* Rows are matched by `key` (default `id`); unmatched incoming rows are
+* inserted as-is and trailing rows are dropped, so add / remove / reorder all
+* reach coarse readers.
+*/
+/**
+* Field-level equality for the merge. `===` is not enough: the decoder hands
+* out a fresh RecordId / Date instance for every record-link and datetime
+* column on every emission, so by identity every one of those fields "changed"
+* on every update - and a store write on an unchanged `id` re-ran everything a
+* page keyed on that row (a thread's anchor, its composer, its whole subtree).
+* Compare those wrappers by value; everything else stays identity (nested
+* objects and arrays are reconciled by their own writes).
+*/
+function sameValue(a, b) {
+	if (a === b) return true;
+	if (a == null || b == null) return false;
+	if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+	if (typeof a === "object" && typeof b === "object") {
+		const ctor = a.constructor;
+		if (ctor && ctor === b.constructor && ctor !== Object && ctor !== Array) return String(a) === String(b);
+	}
+	return false;
+}
+function mergeRows(draft, next, key = "id") {
+	const byKey = /* @__PURE__ */ new Map();
+	for (const row of draft) {
+		const k = row?.[key];
+		if (k !== void 0) byKey.set(String(k), row);
+	}
+	for (let i = 0; i < next.length; i++) {
+		const incoming = next[i];
+		const k = incoming?.[key];
+		const reuse = k !== void 0 ? byKey.get(String(k)) : void 0;
+		if (reuse) {
+			for (const field of Object.keys(incoming)) if (!sameValue(reuse[field], incoming[field])) reuse[field] = incoming[field];
+			for (const field of Object.keys((0, solid_js.snapshot)(reuse))) if (!(field in incoming)) delete reuse[field];
+			if (draft[i] !== reuse) draft[i] = reuse;
+		} else if (draft[i] !== incoming) draft[i] = incoming;
+	}
+	if (draft.length > next.length) draft.splice(next.length);
+}
+
+//#endregion
+//#region src/lib/create-query.ts
+function createQuery(dbOrQuery, queryOrOptions, maybeOptions) {
+	let db;
+	let finalQuery;
+	let options;
+	if (dbOrQuery instanceof SyncedDb) {
+		db = dbOrQuery;
+		finalQuery = queryOrOptions;
+		options = maybeOptions;
+	} else {
+		db = useDb();
+		finalQuery = dbOrQuery;
+		options = queryOrOptions;
+	}
+	const sp00ky = db.getSp00ky();
+	const [error, setError] = (0, solid_js.createSignal)(void 0, { ownedWrite: true });
+	const [isAuthoritative, setIsAuthoritative] = (0, solid_js.createSignal)(false, { ownedWrite: true });
+	const [hasPainted, setHasPainted] = (0, solid_js.createSignal)(false, { ownedWrite: true });
+	const [isFetching, setIsFetching] = (0, solid_js.createSignal)(false, { ownedWrite: true });
+	let activeHash;
+	const [store, setStore] = (0, solid_js.createStore)({ value: null });
+	let runId = 0;
+	let readyWaiters = [];
+	const wakeReady = () => {
+		const waiters = readyWaiters;
+		readyWaiters = [];
+		for (const w of waiters) w();
+	};
+	(0, solid_js.createEffect)(() => {
+		return {
+			enabled: options?.enabled?.() ?? true,
+			query: typeof finalQuery === "function" ? finalQuery() : finalQuery
+		};
+	}, ({ enabled, query }) => {
+		const myRun = ++runId;
+		setIsAuthoritative(false);
+		setHasPainted(false);
+		setError(void 0);
+		if (!enabled || !query) return;
+		const cleanups = [];
+		let disposed = false;
+		const addCleanup = (c) => {
+			if (!c) return;
+			if (typeof c === "function") {
+				if (disposed) c();
+				else cleanups.push(c);
+				return;
+			}
+			Promise.resolve(c).then((fn) => {
+				if (typeof fn !== "function") return;
+				if (disposed) fn();
+				else cleanups.push(fn);
+			});
+		};
+		/**
+		* Registration can fail — the canonical case is the SSP answering 503
+		* NOT_READY while it bootstraps. Surface it as `error()` instead of
+		* throwing into the graph: the sync scheduler retries the registration
+		* underneath, so a transient failure still recovers, and a spinner
+		* driven by `isLoading()` resolves via `error()`.
+		*/
+		query.run().then(({ hash }) => {
+			if (disposed || myRun !== runId) return;
+			activeHash = hash;
+			addCleanup(sp00ky.subscribeQueryStatus(hash, (status) => setIsFetching(status === "fetching"), { immediate: true }));
+			addCleanup(sp00ky.subscribeQueryAuthority(hash, (known) => {
+				if (disposed || myRun !== runId) return;
+				setIsAuthoritative(known);
+				if (known) wakeReady();
+				else setHasPainted(false);
+			}, { immediate: true }));
+			addCleanup(sp00ky.subscribe(hash, (rows) => {
+				if (disposed || myRun !== runId) return;
+				const queryData = query.isOne ? rows[0] ?? null : rows;
+				if (query.isOne ? queryData !== null && queryData !== void 0 : rows.length > 0) {
+					setHasPainted(true);
+					wakeReady();
+				}
+				const t0 = performance.now();
+				setStore((s) => {
+					if (query.isOne || queryData === null || !Array.isArray(s.value)) s.value = queryData;
+					else mergeRows(s.value, queryData);
+				});
+				sp00ky.reportFrontendTiming(hash, performance.now() - t0);
+			}, { immediate: true }));
+		}).catch((err) => {
+			if (disposed || myRun !== runId) return;
+			setError(err instanceof Error ? err : new Error(String(err)));
+			wakeReady();
+		});
+		return () => {
+			disposed = true;
+			for (const c of cleanups) c();
+		};
+	});
+	const emptyList = [];
+	const data = () => {
+		const v = store.value;
+		if (v === null || v === void 0) {
+			const query = typeof finalQuery === "function" ? finalQuery() : finalQuery;
+			if (query && !query.isOne) return emptyList;
+		}
+		return v;
+	};
+	const readyGate = (0, solid_js.createMemo)(async () => {
+		if (isAuthoritative() || hasPainted() || error()) return true;
+		await new Promise((resolve) => readyWaiters.push(resolve));
+		return true;
+	}, { lazy: true });
+	const ready = () => {
+		readyGate();
+		return data();
+	};
+	(0, solid_js.onCleanup)(() => {
+		if (options?.deregisterOnCleanup && activeHash) sp00ky.deregisterQuery(activeHash);
+	});
+	const hasData = () => {
+		const v = store.value;
+		return Array.isArray(v) ? v.length > 0 : v !== null && v !== void 0;
+	};
+	const isLoading = () => !isAuthoritative() && !hasPainted() && error() === void 0;
+	const isEmpty = () => isAuthoritative() && !hasData();
+	const isSettled = () => isAuthoritative() && !isFetching();
+	return {
+		data,
+		ready,
+		error,
+		isLoading,
+		isFetching,
+		isAuthoritative,
+		hasData,
+		isEmpty,
+		isSettled
+	};
+}
+/** @deprecated Renamed `createQuery` in the Solid 2 binding. */
+const useQuery = createQuery;
+
+//#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 {
+		db = useDb();
+		finalQuery = dbOrQuery;
+		options = queryOrOptions;
+	}
+	let prevHash;
+	(0, solid_js.createEffect)(() => {
+		if (!(options?.enabled?.() ?? true)) return void 0;
+		const query = typeof finalQuery === "function" ? finalQuery() : finalQuery;
+		if (!query) return void 0;
+		if (query.hash === prevHash) return void 0;
+		prevHash = query.hash;
+		return query;
+	}, (query) => {
+		if (!query) return;
+		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 = fromSubscription((cb) => db.subscribeToSyncHealth(cb), db.syncHealth);
+	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-sync-activity.ts
+/**
+* The two directions of sync traffic, for an indicator in the app chrome.
+*
+* `fetchingQueries` is one subscription on the engine's aggregate fetch count,
+* not one per query; `pendingMutations` is the outbox depth. `isDownloading`
+* is the fetch count debounced ON by `downloadDelayMs` (and off at once), so a
+* local-first page that answers from cache and confirms with the server in a
+* few milliseconds never flickers. Must be used within a `<Sp00kyProvider>`, or
+* pass the `SyncedDb` explicitly.
+*/
+function useSyncActivity(dbOrOptions, maybeOptions) {
+	const explicitDb = dbOrOptions && typeof dbOrOptions.subscribeToFetchActivity === "function" ? dbOrOptions : void 0;
+	const options = (explicitDb ? maybeOptions : dbOrOptions) ?? {};
+	const db = explicitDb ?? useDb();
+	const downloadDelayMs = options.downloadDelayMs ?? 200;
+	const uploadThreshold = options.uploadThreshold ?? 1;
+	const fetchingQueries = fromSubscription((cb) => db.subscribeToFetchActivity(cb), db.fetchingQueryCount);
+	const pendingMutations = fromSubscription((cb) => db.subscribeToPendingMutations(cb), db.pendingMutationCount);
+	const [isDownloading, setIsDownloading] = (0, solid_js.createSignal)(false, { ownedWrite: true });
+	let timer;
+	(0, solid_js.createEffect)(() => fetchingQueries() > 0, (busy) => {
+		if (timer !== void 0) {
+			clearTimeout(timer);
+			timer = void 0;
+		}
+		if (!busy) {
+			setIsDownloading(false);
+			return;
+		}
+		if (downloadDelayMs <= 0) {
+			setIsDownloading(true);
+			return;
+		}
+		timer = setTimeout(() => {
+			timer = void 0;
+			setIsDownloading(true);
+		}, downloadDelayMs);
+	});
+	(0, solid_js.onCleanup)(() => {
+		if (timer !== void 0) clearTimeout(timer);
+	});
+	return {
+		fetchingQueries,
+		pendingMutations,
+		isDownloading,
+		isUploading: () => pendingMutations() > uploadThreshold
+	};
+}
+
+//#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 = fromSubscription((cb) => db.subscribeToStorageHealth(cb), db.storageHealth);
+	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 = useDb();
+	const [crdtField, setCrdtField] = (0, solid_js.createSignal)(null, { ownedWrite: true });
+	(0, solid_js.createEffect)(() => recordId(), (id) => {
+		if (!id) {
+			setCrdtField(null);
+			return;
+		}
+		const sp00ky = db.getSp00ky();
+		let superseded = false;
+		const text = fallbackText?.();
+		sp00ky.openCrdtField(table, id, field, text).then((cf) => {
+			if (!superseded) setCrdtField(cf);
+			else sp00ky.closeCrdtField(table, id, field);
+		}).catch((err) => {
+			console.error(`[useCrdtField] Failed to open CRDT field ${table}.${field} on ${id}:`, err);
+		});
+		return () => {
+			superseded = true;
+			if (crdtField()) {
+				sp00ky.closeCrdtField(table, id, 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 `createQuery`, 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);
+	(0, solid_js.onCleanup)(() => handle.close());
+	const state = fromSubscription((cb) => handle.subscribe((s) => cb({
+		variant: s.variant ?? options?.fallback,
+		payload: s.payload
+	})), {
+		variant: handle.variant(),
+		payload: handle.payload()
+	});
+	return {
+		variant: () => state().variant,
+		payload: () => state().payload,
+		enabled: () => {
+			const v = state().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 });
+	(0, solid_js.onCleanup)(() => handle.close());
+	const snapshot = fromSubscription((cb) => handle.subscribe(cb), handle.snapshot());
+	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())
+	};
+}
+
+//#endregion
+//#region src/lib/use-file-upload.ts
+function useFileUpload(dbOrBucketName, maybeBucketName) {
+	let db;
+	let bucketName;
+	if (typeof dbOrBucketName === "string") {
+		db = useDb();
+		bucketName = dbOrBucketName;
+	} else {
+		db = dbOrBucketName;
+		bucketName = maybeBucketName;
+	}
+	const [isUploading, setIsUploading] = (0, solid_js.createSignal)(false, { ownedWrite: true });
+	const [error, setError] = (0, solid_js.createSignal)(null, { ownedWrite: true });
+	const objectUrls = [];
+	(0, solid_js.onCleanup)(() => {
+		for (const url of objectUrls) URL.revokeObjectURL(url);
+	});
+	const clearError = () => setError(null);
+	const validate = (file) => {
+		const config = db.getBucketConfig(bucketName);
+		if (!config) return;
+		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.`);
+		}
+		if (config.allowedExtensions && config.allowedExtensions.length > 0) {
+			const fileName = file.name;
+			if (fileName) {
+				const ext = fileName.split(".").pop()?.toLowerCase();
+				if (!ext || !config.allowedExtensions.includes(ext)) throw new Error(`File type not allowed. Accepted: ${config.allowedExtensions.join(", ")}.`);
+			}
+		}
+	};
+	const upload = async (path, file, options) => {
+		setError(null);
+		try {
+			validate(file);
+		} catch (e) {
+			setError(e instanceof Error ? e : new Error(String(e)));
+			return;
+		}
+		setIsUploading(true);
+		try {
+			const bytes = await (0, _spooky_sync_core.fileToUint8Array)(file);
+			return await db.bucket(bucketName).put(path, bytes, options);
+		} catch (e) {
+			setError(e instanceof Error ? e : new Error(String(e)));
+		} finally {
+			setIsUploading(false);
+		}
+	};
+	const download = async (path) => {
+		setError(null);
+		try {
+			const content = await db.bucket(bucketName).get(path);
+			if (!content) return null;
+			const objectUrl = URL.createObjectURL(new Blob([content]));
+			objectUrls.push(objectUrl);
+			return objectUrl;
+		} catch (e) {
+			setError(e instanceof Error ? e : new Error(String(e)));
+			return null;
+		}
+	};
+	const remove = async (path) => {
+		setError(null);
+		try {
+			await db.bucket(bucketName).delete(path);
+		} catch (e) {
+			setError(e instanceof Error ? e : new Error(String(e)));
+		}
+	};
+	const exists = async (path) => {
+		setError(null);
+		try {
+			return await db.bucket(bucketName).exists(path);
+		} catch (e) {
+			setError(e instanceof Error ? e : new Error(String(e)));
+			return false;
+		}
+	};
+	return {
+		isUploading,
+		error,
+		clearError,
+		upload,
+		download,
+		remove,
+		exists
+	};
+}
+
+//#endregion
+//#region src/lib/use-download-file.ts
+function useDownloadFile(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 useCache = options.cache !== false;
+	const [url, setUrl] = (0, solid_js.createSignal)(null, { ownedWrite: true });
+	const [isLoading, setIsLoading] = (0, solid_js.createSignal)(false, { ownedWrite: true });
+	const [error, setError] = (0, solid_js.createSignal)(null, { ownedWrite: true });
+	let lease = null;
+	let privateUrl = null;
+	const [refetchSignal, setRefetchSignal] = (0, solid_js.createSignal)(0);
+	/** 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;
+		}
+	}
+	(0, solid_js.createEffect)(() => {
+		refetchSignal();
+		return path();
+	}, (filePath) => {
+		releaseCurrent();
+		if (!filePath) {
+			setUrl(null);
+			setIsLoading(false);
+			setError(null);
+			return;
+		}
+		const reload = reloadOnce;
+		reloadOnce = false;
+		let cancelled = false;
+		setIsLoading(true);
+		setError(null);
+		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);
+			}
+		}, (err) => {
+			if (!cancelled) {
+				setError(err instanceof Error ? err : new Error(String(err)));
+				setIsLoading(false);
+			}
+		});
+		return () => {
+			cancelled = true;
+		};
+	});
+	(0, solid_js.onCleanup)(() => {
+		releaseCurrent();
+	});
+	const refetch = () => {
+		reloadOnce = true;
+		setRefetchSignal((n) => n + 1);
+	};
+	return {
+		url,
+		isLoading,
+		error,
+		refetch
+	};
+}
+
+//#endregion
+//#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, { ownedWrite: true });
+	const [isLoading, setIsLoading] = (0, solid_js.createSignal)(false, { ownedWrite: true });
+	(0, solid_js.createEffect)(() => path(), (filePath) => {
+		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);
+		});
+		return () => {
+			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, { ownedWrite: true });
+	(0, solid_js.createEffect)(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)(() => props.class ?? "", (className) => {
+		canvas.className = className;
+	});
+	(0, solid_js.createEffect)(() => props.style ?? "", (style) => {
+		canvas.style.cssText = style;
+	});
+	(0, solid_js.createEffect)(() => ({
+		width: props.width ?? 32,
+		height: props.height ?? 32,
+		hash: props.hash,
+		punch: props.punch ?? 1
+	}), ({ width, height, hash, punch }) => {
+		canvas.width = width;
+		canvas.height = height;
+		if (!hash) return;
+		try {
+			const pixels = (0, _spooky_sync_core.decodeBlurhash)(hash, width, height, punch);
+			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)(() => props.class ?? "", (className) => {
+		root.className = className;
+	});
+	(0, solid_js.onSettled)(() => {
+		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)(() => resolvedFallback.toArray().filter((node) => node instanceof Node), (nodes) => {
+		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)(() => props.imgClass ?? "", (className) => {
+		img.className = className;
+	});
+	(0, solid_js.createEffect)(() => props.fit ?? "cover", (fit) => {
+		img.style.objectFit = fit;
+	});
+	(0, solid_js.createEffect)(() => props.alt ?? "", (alt) => {
+		img.alt = alt;
+	});
+	(0, solid_js.createEffect)(() => reducedMotion ? "none" : `opacity ${props.transition ?? 300}ms ${props.easing ?? "cubic-bezier(0.16, 1, 0.3, 1)"}`, (transition) => {
+		img.style.transition = transition;
+	});
+	(0, solid_js.createEffect)(() => image.url(), (url) => {
+		if (!url) {
+			img.removeAttribute("src");
+			return;
+		}
+		img.src = url;
+		image.gate(img);
+	});
+	(0, solid_js.createEffect)(() => image.ready(), (ready) => {
+		img.style.opacity = ready ? "1" : "0";
+	});
+	const [settled, setSettled] = (0, solid_js.createSignal)(false, { ownedWrite: true });
+	(0, solid_js.createEffect)(() => ({
+		ready: image.ready(),
+		transition: props.transition ?? 300
+	}), ({ ready, transition }) => {
+		if (!ready) {
+			setSettled(false);
+			return;
+		}
+		const wait = (reducedMotion ? 0 : transition) + 120;
+		const timer = setTimeout(() => setSettled(true), wait);
+		return () => clearTimeout(timer);
+	});
+	(0, solid_js.createEffect)(() => settled(), (isSettled) => {
+		if (isSettled) 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.merge)({ fallback: void 0 }, props);
+	const [db, setDb] = (0, solid_js.createSignal)(void 0, { ownedWrite: true });
+	let disposed = false;
+	(0, solid_js.onCleanup)(() => {
+		disposed = true;
+	});
+	(0, solid_js.onSettled)(() => {
+		(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("Sp00kyProvider: Failed to initialize database", error);
+			}
+		})();
+	});
+	return (0, solid_js.createMemo)(() => {
+		const instance = db();
+		if (!instance) return merged.fallback;
+		return (0, solid_js.createComponent)(Sp00kyContext, {
+			value: instance,
+			get children() {
+				return merged.children;
+			}
+		});
+	});
+}
+
+//#endregion
+//#region src/lib/create-submission.ts
+/**
+* Thin submission-state wrapper for mutations — button spinner/disable state
+* around `db.create/update/delete/run` calls.
+*
+* Deliberately NOT built on Solid 2's `action()`/`createOptimisticStore`: the
+* spooky engine is already optimistic local-first (writes commit to the local
+* DB and re-render through live queries before sync; `run()` is an outbox
+* CREATE), so a transaction/revert layer on top buys nothing and `action()`'s
+* await-vs-yield transaction escape is a real footgun. Errors here mean the
+* LOCAL commit failed — sync/push failures surface through `useSyncStatus`
+* and `usePendingMutations` instead.
+*/
+function createSubmission(fn) {
+	const [inFlight, setInFlight] = (0, solid_js.createSignal)(0, { ownedWrite: true });
+	const [error, setError] = (0, solid_js.createSignal)(void 0, { ownedWrite: true });
+	const [result, setResult] = (0, solid_js.createSignal)(void 0, { ownedWrite: true });
+	const submit = async (...args) => {
+		setError(void 0);
+		setInFlight((n) => n + 1);
+		try {
+			const r = await fn(...args);
+			setResult(() => r);
+			return r;
+		} catch (e) {
+			setError(e instanceof Error ? e : new Error(String(e)));
+			return;
+		} finally {
+			setInFlight((n) => n - 1);
+		}
+	};
+	return {
+		submit,
+		pending: () => inFlight() > 0,
+		error,
+		result,
+		clearError: () => setError(void 0)
+	};
+}
+
+//#endregion
+//#region src/index.ts
+/**
+* SyncedDb - A thin wrapper around sp00ky-ts for Solid.js integration.
+* Delegates all logic to the underlying sp00ky-ts instance.
+*
+* NOTE: keep in sync with packages/client-solid/src/index.ts (SyncedDb).
+* Copied rather than shared so this package's dependency graph never pulls
+* in solid-js 1.x; fold the two together once client-solid moves to Solid 2.
+* Solid-2-only differences: `delete` accepts 'bound RecordId', and write
+* payloads go through `snapshot()` (see `unproxy` below).
+*/
+/**
+* Solid 2 stores wrap every object read out of them (query rows, their nested
+* arrays, `createStore` docs) in a Proxy. Those proxies cannot cross
+* `postMessage` (the sqlite and shared-tabs workers): structuredClone throws
+* DataCloneError. `snapshot()` returns the underlying plain value for store
+* proxies and passes anything else through untouched.
+*/
+function unproxy(value) {
+	if (value === null || typeof value !== "object") return value;
+	return (0, solid_js.snapshot)(value);
+}
+var SyncedDb = class {
+	constructor(config) {
+		this.sp00ky = null;
+		this._initialized = false;
+		this.config = config;
+	}
+	getSp00ky() {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky;
+	}
+	/**
+	* Initialize the sp00ky-ts instance
+	*/
+	async init() {
+		if (this._initialized) return;
+		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.sp00ky) throw new Error("SyncedDb not initialized");
+		await this.sp00ky.create(id, unproxy(payload));
+	}
+	/**
+	* Update an existing record in the database
+	*/
+	async update(tableName, recordId, payload, options) {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		await this.sp00ky.update(tableName, recordId, unproxy(payload), options);
+	}
+	/**
+	* Delete an existing record in the database
+	*/
+	async delete(tableName, selector) {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		const raw = unproxy(selector);
+		const ctorName = raw?.constructor?.name;
+		const isRecordId = raw instanceof surrealdb.RecordId || ctorName === "RecordId" || ctorName === "bound RecordId";
+		let id;
+		if (typeof raw === "string") id = raw;
+		else if (isRecordId) id = `${tableName}:${raw.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 `createQuery` 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.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.query(table, {});
+	}
+	/**
+	* Run a backend operation
+	*/
+	async run(backend, path, payload, options) {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		await this.sp00ky.run(backend, path, unproxy(payload), options);
+	}
+	/**
+	* Sign out, clear session and local storage
+	*/
+	async 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.sp00ky) throw new Error("SyncedDb not initialized");
+		return await this.sp00ky.useRemote(fn);
+	}
+	/**
+	* Access the remote database service directly
+	*/
+	get remote() {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.remoteClient;
+	}
+	/**
+	* Access the local database service directly
+	*/
+	get local() {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.localClient;
+	}
+	/**
+	* Access the auth service
+	*/
+	get auth() {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.auth;
+	}
+	get 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.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.subscribeToPendingMutations(cb);
+	}
+	/** Queries mid-fetch right now. See {@link useSyncActivity}. */
+	get fetchingQueryCount() {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.fetchingQueryCount;
+	}
+	/**
+	* Observe how many queries are fetching from the server. Fires immediately
+	* and on every change. Prefer the `useSyncActivity` hook in components.
+	*/
+	subscribeToFetchActivity(cb) {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.subscribeToFetchActivity(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.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.bucket(name);
+	}
+	getBucketConfig(name) {
+		return this.config.schema.buckets?.find((b) => b.name === name);
+	}
+};
+
+//#endregion
+exports.Blurhash = Blurhash;
+exports.BucketImage = BucketImage;
+exports.RecordId = surrealdb.RecordId;
+exports.Sp00kyProvider = Sp00kyProvider;
+exports.SyncedDb = SyncedDb;
+exports.Uuid = surrealdb.Uuid;
+exports.conflate = conflate;
+exports.createPreload = createPreload;
+exports.createQuery = createQuery;
+exports.createSubmission = createSubmission;
+exports.fromSubscription = fromSubscription;
+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.usePendingMutations = usePendingMutations;
+exports.useQuery = useQuery;
+exports.useStorageStatus = useStorageStatus;
+exports.useSyncActivity = useSyncActivity;
+exports.useSyncStatus = useSyncStatus;
+//# sourceMappingURL=index.cjs.map