@spooky-sync/core 0.0.1-canary.162 → 0.0.1-canary.164

package/dist/index.js

@@ -1081,8 +1081,12 @@ var ConnectionSupervisor = class ConnectionSupervisor {
 	disposed = false;
 	heartbeatTimer = null;
 	heartbeatInFlight = false;
+	/** Consecutive failed probes. See {@link FAILURES_BEFORE_TEARDOWN}. */
+	heartbeatFailures = 0;
 	reviveTimer = null;
 	reviveAttempts = 0;
+	/** Timestamp of the last wake-triggered probe, for rate limiting. */
+	lastWakeProbeAt = 0;
 	reviving = false;
 	/**
 	* Set while the browser reports itself offline. Retrying a socket against a
@@ -1091,6 +1095,23 @@ var ConnectionSupervisor = class ConnectionSupervisor {
 	suspended = false;
 	teardown = [];
 	static REVIVE_BASE_MS = 1e3;
+	/**
+	* How many consecutive heartbeat failures it takes to tear the socket down.
+	*
+	* The probe rides the same serialized queue as every other RPC (deliberately
+	* — see {@link beat}), which means it cannot distinguish a WEDGED queue from
+	* a merely BUSY one. A single slow window (a large sync burst, one heavy
+	* app query) used to be enough to force-close a perfectly healthy socket,
+	* and the resulting reconnect re-registered every active query about a
+	* second later. That self-inflicted teardown manufactured the very reconnect
+	* storms this class exists to survive. A genuinely dead socket still fails
+	* every probe, so it is torn down one interval later than before.
+	*/
+	static FAILURES_BEFORE_TEARDOWN = 2;
+	/** Retry delay after an inconclusive (first) heartbeat failure. */
+	static HEARTBEAT_RETRY_MS = 5e3;
+	/** Floor between probes triggered by wake events (tab focus, pageshow). */
+	static WAKE_PROBE_MIN_INTERVAL_MS = 1e4;
 	constructor(remote, logger, config) {
 		this.remote = remote;
 		this.logger = logger.child({ service: "ConnectionSupervisor" });
@@ -1244,12 +1265,26 @@ var ConnectionSupervisor = class ConnectionSupervisor {
 		this.heartbeatInFlight = true;
 		try {
 			await withTimeout(this.remote.query("RETURN true"), this.config.heartbeatTimeoutMs, `Heartbeat timed out after ${this.config.heartbeatTimeoutMs}ms`);
+			this.heartbeatFailures = 0;
 			this.startHeartbeat();
 		} catch (err) {
+			this.heartbeatFailures++;
+			if (this.heartbeatFailures < ConnectionSupervisor.FAILURES_BEFORE_TEARDOWN) {
+				this.logger.debug({
+					err,
+					failures: this.heartbeatFailures,
+					Category: "sp00ky-client::ConnectionSupervisor::heartbeat"
+				}, "Heartbeat failed; re-probing before tearing the socket down");
+				this.stopHeartbeat();
+				if (!this.disposed && !this.suspended) this.heartbeatTimer = setTimeout(() => void this.beat(), Math.min(ConnectionSupervisor.HEARTBEAT_RETRY_MS, this.config.heartbeatIntervalMs));
+				return;
+			}
 			this.logger.warn({
 				err,
+				failures: this.heartbeatFailures,
 				Category: "sp00ky-client::ConnectionSupervisor::heartbeat"
-			}, "Heartbeat failed; tearing the socket down to force a reconnect");
+			}, "Heartbeat failed repeatedly; tearing the socket down to force a reconnect");
+			this.heartbeatFailures = 0;
 			await this.remote.forceClose();
 			if (this.remote.getStatus() !== "connected") this.scheduleRevive();
 		} finally {
@@ -1297,6 +1332,9 @@ var ConnectionSupervisor = class ConnectionSupervisor {
 	*/
 	wake(reason) {
 		if (this.disposed || this.suspended) return;
+		const now = Date.now();
+		if (this.remote.getStatus() === "connected" && now - this.lastWakeProbeAt < ConnectionSupervisor.WAKE_PROBE_MIN_INTERVAL_MS) return;
+		this.lastWakeProbeAt = now;
 		this.logger.debug({
 			reason,
 			state: this.state,
@@ -1353,7 +1391,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_preload SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_window 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_window 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      DEFINE TABLE IF NOT EXISTS _00_blob 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];
@@ -2025,6 +2063,7 @@ const SYSTEM_TABLES = [
 	"_00_window",
 	"_00_schema",
 	"_00_pending_mutations",
+	"_00_blob",
 	"_00_user_feature",
 	"_00_app_release"
 ];
@@ -5276,6 +5315,14 @@ var Sp00kySync = class Sp00kySync {
 	* initial connect. See {@link subscribeToReconnect}.
 	*/
 	needsResubscribe = false;
+	/** When the last reconnect-driven full refetch ran, for burst coalescing. */
+	lastReconnectRefetchAt = 0;
+	/**
+	* Minimum gap between reconnect-driven full refetches. Long enough to absorb
+	* a flapping socket (the SDK reconnect ladder starts at 1s), short enough
+	* that a genuine drop minutes later still refetches.
+	*/
+	static RECONNECT_REFETCH_COOLDOWN_MS = 1e4;
 	events = createSyncEventSystem();
 	currentUserId = null;
 	tabRole = "solo";
@@ -5901,8 +5948,21 @@ var Sp00kySync = class Sp00kySync {
 		client.subscribe("connected", () => {
 			if (!this.needsResubscribe) return;
 			this.needsResubscribe = false;
-			this.logger.info({ Category: "sp00ky-client::Sp00kySync::onReconnect" }, "Remote reconnected, refetching active queries");
-			for (const hash of this.dataModule.getActiveQueryHashes()) this.scheduler.enqueueDownEvent({
+			const sinceLast = Date.now() - this.lastReconnectRefetchAt;
+			if (sinceLast < Sp00kySync.RECONNECT_REFETCH_COOLDOWN_MS) {
+				this.logger.debug({
+					sinceLast,
+					Category: "sp00ky-client::Sp00kySync::onReconnect"
+				}, "Reconnected again within the cooldown; skipping duplicate refetch");
+				return;
+			}
+			this.lastReconnectRefetchAt = Date.now();
+			const hashes = this.dataModule.getActiveQueryHashes();
+			this.logger.info({
+				queries: hashes.length,
+				Category: "sp00ky-client::Sp00kySync::onReconnect"
+			}, "Remote reconnected, refetching active queries");
+			for (const hash of hashes) this.scheduler.enqueueDownEvent({
 				type: "register",
 				payload: { hash }
 			});
@@ -6483,8 +6543,8 @@ async function walkOpfs(maxEntries = 2e3, maxDepth = 8) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.162";
-const WASM_VERSION = "0.0.1-canary.162";
+const CORE_VERSION = "0.0.1-canary.164";
+const WASM_VERSION = "0.0.1-canary.164";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -6501,6 +6561,11 @@ var DevToolsService = class DevToolsService {
 	setTabsInfoProvider(provider) {
 		this.tabsInfoProvider = provider;
 	}
+	/** Blob cache counters for the panel, wired by Sp00kyClient. */
+	blobInfoProvider = null;
+	setBlobInfoProvider(provider) {
+		this.blobInfoProvider = provider;
+	}
 	localTables = [];
 	localTablesFetching = false;
 	localTablesAt = 0;
@@ -6740,6 +6805,14 @@ var DevToolsService = class DevToolsService {
 			info.browser.error = e instanceof Error ? e.message : String(e);
 		}
 		info.opfs = await walkOpfs();
+		try {
+			info.blobs = this.blobInfoProvider?.();
+		} catch (e) {
+			this.logger.warn({
+				err: e,
+				Category: "sp00ky-client::DevToolsService::getStorageInfo"
+			}, "Blob cache diagnostics failed");
+		}
 		const stats = globalThis.__sqliteStats;
 		if (stats && typeof stats === "object") info.sqliteStats = {
 			...stats,
@@ -9579,22 +9652,1022 @@ var TabsCoordinator = class {
 	}
 };
 
+//#endregion
+//#region src/services/blobs/blob-store.ts
+const BLOB_ROOT_DIR = "sp00ky-blobs";
+/**
+* Marks a half-written file. Committed names can never contain a literal `.`
+* (see {@link encodeSegment}), so this suffix is unambiguous — anything wearing
+* it at walk time is a write that died before commit, and is swept.
+*/
+const PART_MARKER = ".part-";
+/** OPFS names are capped around 255 bytes; stay well clear. */
+const MAX_SEGMENT_LENGTH = 200;
+/** Walk guards, mirroring `walkOpfs` in the DevTools storage report. */
+const MAX_WALK_DEPTH = 12;
+const MAX_WALK_ENTRIES = 5e3;
+/** A path segment we refuse to store — the caller degrades to no persistence. */
+var BlobKeyError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "BlobKeyError";
+	}
+};
+/**
+* Percent-encode a path segment, and escape `.` on top of that. Escaping the
+* dot is what makes {@link PART_MARKER} safe: a real file called `x.part-1`
+* would otherwise be swept as a torn write on the next boot.
+*/
+function encodeSegment(segment) {
+	const encoded = encodeURIComponent(segment).replace(/\./g, "%2E");
+	if (encoded.length > MAX_SEGMENT_LENGTH) throw new BlobKeyError(`path segment too long to store (${encoded.length} > ${MAX_SEGMENT_LENGTH})`);
+	return encoded;
+}
+function decodeSegment(segment) {
+	return decodeURIComponent(segment);
+}
+/** Path segments, `..`/`.`/empty stripped so a crafted path can't escape the root. */
+function pathSegments(path) {
+	return path.split("/").filter((s) => s.length > 0 && s !== "." && s !== "..");
+}
+/** `<bucket>/<...path>` — the directory chain plus filename for a key. */
+function keySegments(key) {
+	const parts = pathSegments(key.path);
+	if (parts.length === 0) throw new BlobKeyError(`empty file path for bucket "${key.bucket}"`);
+	return [key.bucket, ...parts].map(encodeSegment);
+}
+/** Stable manifest row id. Mirrors the on-disk layout, decoded. */
+function blobKeyId(key) {
+	return `${key.bucket}/${pathSegments(key.path).join("/")}`;
+}
+/** Whether OPFS is usable for read AND write in this environment. Writes need
+*  `createWritable`, which arrived late in Safari; without it we run
+*  memory-only rather than dragging in a sync-access-handle worker. */
+function opfsWritableSupported() {
+	if (typeof navigator === "undefined" || !navigator.storage?.getDirectory) return false;
+	return typeof (globalThis.FileSystemFileHandle?.prototype)?.createWritable === "function";
+}
+function supportsHandleMove() {
+	return typeof (globalThis.FileSystemFileHandle?.prototype)?.move === "function";
+}
+function isNotFound(err) {
+	return err instanceof Error && err.name === "NotFoundError";
+}
+/** OPFS-backed byte storage. All calls are async — nothing blocks the main thread. */
+var OpfsBlobStore = class {
+	persistent = true;
+	ns;
+	useTempCommit = supportsHandleMove();
+	tempCounter = 0;
+	tempToken = typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID().slice(0, 8) : "tmp";
+	constructor(namespace) {
+		this.ns = namespace;
+	}
+	get namespace() {
+		return this.ns;
+	}
+	setNamespace(namespace) {
+		this.ns = namespace;
+	}
+	async root(create) {
+		const opfs = await navigator.storage.getDirectory();
+		return this.resolveDir(opfs, [BLOB_ROOT_DIR, encodeSegment(this.ns)], create);
+	}
+	async resolveDir(from, segments, create) {
+		let dir = from;
+		for (const segment of segments) try {
+			dir = await dir.getDirectoryHandle(segment, { create });
+		} catch (err) {
+			if (!create && isNotFound(err)) return null;
+			throw err;
+		}
+		return dir;
+	}
+	async read(key) {
+		const segments = keySegments(key);
+		const root = await this.root(false);
+		if (!root) return null;
+		const dir = await this.resolveDir(root, segments.slice(0, -1), false);
+		if (!dir) return null;
+		try {
+			return await (await dir.getFileHandle(segments[segments.length - 1])).getFile();
+		} catch (err) {
+			if (isNotFound(err)) return null;
+			throw err;
+		}
+	}
+	async write(key, bytes) {
+		const segments = keySegments(key);
+		const root = await this.root(true);
+		if (!root) throw new Error("OPFS root unavailable");
+		const dir = await this.resolveDir(root, segments.slice(0, -1), true);
+		const name = segments[segments.length - 1];
+		const target = this.useTempCommit ? `${name}${PART_MARKER}${this.tempToken}-${this.tempCounter++}` : name;
+		const handle = await dir.getFileHandle(target, { create: true });
+		const writable = await handle.createWritable();
+		try {
+			await writable.write(bytes);
+			await writable.close();
+		} catch (err) {
+			await writable.abort?.().catch(() => {});
+			await dir.removeEntry(target).catch(() => {});
+			throw err;
+		}
+		if (this.useTempCommit) await handle.move(name);
+		return bytes.size;
+	}
+	async remove(key) {
+		const segments = keySegments(key);
+		const root = await this.root(false);
+		if (!root) return;
+		const dir = await this.resolveDir(root, segments.slice(0, -1), false);
+		if (!dir) return;
+		try {
+			await dir.removeEntry(segments[segments.length - 1]);
+		} catch (err) {
+			if (!isNotFound(err)) throw err;
+		}
+	}
+	async list() {
+		const root = await this.root(false);
+		if (!root) return [];
+		const out = [];
+		await this.walk(root, [], out, 0);
+		return out;
+	}
+	async walk(dir, trail, out, depth) {
+		if (depth > MAX_WALK_DEPTH || out.length >= MAX_WALK_ENTRIES) return;
+		for await (const [name, handle] of dir.entries()) {
+			if (out.length >= MAX_WALK_ENTRIES) return;
+			if (handle.kind === "directory") {
+				await this.walk(handle, [...trail, name], out, depth + 1);
+				continue;
+			}
+			if (name.includes(PART_MARKER)) {
+				await dir.removeEntry(name).catch(() => {});
+				continue;
+			}
+			if (trail.length === 0) continue;
+			try {
+				const file = await handle.getFile();
+				out.push({
+					key: {
+						bucket: decodeSegment(trail[0]),
+						path: [...trail.slice(1), name].map(decodeSegment).join("/")
+					},
+					size: file.size,
+					mtime: file.lastModified
+				});
+			} catch {}
+		}
+	}
+	async clear() {
+		const opfs = await navigator.storage.getDirectory();
+		const root = await this.resolveDir(opfs, [BLOB_ROOT_DIR], false);
+		if (!root) return;
+		try {
+			await root.removeEntry(encodeSegment(this.ns), { recursive: true });
+		} catch (err) {
+			if (!isNotFound(err)) throw err;
+		}
+	}
+};
+/**
+* In-memory byte store. Used when OPFS is unavailable (the cache still dedupes
+* and serves within the tab, matching the pre-existing behaviour) and as the
+* test double for {@link BlobCache} — `blob-cache.test.ts` runs in node.
+*/
+var MemoryBlobStore = class {
+	persistent = false;
+	ns;
+	files = /* @__PURE__ */ new Map();
+	clock = 0;
+	constructor(namespace = "anon") {
+		this.ns = namespace;
+	}
+	get namespace() {
+		return this.ns;
+	}
+	setNamespace(namespace) {
+		this.ns = namespace;
+	}
+	bucketFiles() {
+		let ns = this.files.get(this.ns);
+		if (!ns) {
+			ns = /* @__PURE__ */ new Map();
+			this.files.set(this.ns, ns);
+		}
+		return ns;
+	}
+	async read(key) {
+		keySegments(key);
+		return this.bucketFiles().get(blobKeyId(key))?.blob ?? null;
+	}
+	async write(key, bytes) {
+		keySegments(key);
+		this.bucketFiles().set(blobKeyId(key), {
+			blob: bytes,
+			mtime: ++this.clock
+		});
+		return bytes.size;
+	}
+	async remove(key) {
+		this.bucketFiles().delete(blobKeyId(key));
+	}
+	async list() {
+		const out = [];
+		for (const [id, entry] of this.bucketFiles()) {
+			const slash = id.indexOf("/");
+			out.push({
+				key: {
+					bucket: id.slice(0, slash),
+					path: id.slice(slash + 1)
+				},
+				size: entry.blob.size,
+				mtime: entry.mtime
+			});
+		}
+		return out;
+	}
+	async clear() {
+		this.files.delete(this.ns);
+	}
+};
+
+//#endregion
+//#region src/services/blobs/blob-manifest.ts
+/**
+* Metadata index for the blob cache, persisted in the `_00_blob` table of the
+* local engine.
+*
+* The manifest is deliberately NOT the source of truth for existence — OPFS is.
+* Several existing recovery paths destroy the local store while leaving OPFS
+* intact (the SQLite leader's wipe-on-pool-open, the memory fallback when OPFS
+* refuses to open for SQLite, IndexedDB corruption recovery on the SurrealDB
+* engine). Treating the manifest as an index that `reconcile()` can rebuild
+* from a directory walk means those paths cost metadata, not the offline cache.
+*
+* Runtime reads hit the in-memory map; writes are batched. `lastAccess` changes
+* on every single cache hit, so flushing each one would turn an image render
+* into a local-DB write.
+*/
+const BLOB_TABLE = "_00_blob";
+function rowToEntry(id, row) {
+	const bucket = typeof row.bucket === "string" ? row.bucket : "";
+	const path = typeof row.path === "string" ? row.path : "";
+	if (!bucket || !path) return null;
+	return {
+		id,
+		bucket,
+		path,
+		size: Number(row.size) || 0,
+		contentType: typeof row.contentType === "string" ? row.contentType : "",
+		createdAt: Number(row.createdAt) || 0,
+		lastAccess: Number(row.lastAccess) || 0,
+		hits: Number(row.hits) || 0,
+		pinned: row.pinned === true
+	};
+}
+function entryToRow(entry) {
+	return {
+		bucket: entry.bucket,
+		path: entry.path,
+		size: entry.size,
+		contentType: entry.contentType,
+		createdAt: entry.createdAt,
+		lastAccess: entry.lastAccess,
+		hits: entry.hits,
+		pinned: entry.pinned
+	};
+}
+var BlobManifest = class {
+	entries = /* @__PURE__ */ new Map();
+	/** Ids whose in-memory state has not been written back yet. */
+	dirty = /* @__PURE__ */ new Set();
+	removed = /* @__PURE__ */ new Set();
+	flushing = null;
+	constructor(local) {
+		this.local = local;
+	}
+	/**
+	* Hydrate from the rows matching `keys`. Ids come from the OPFS listing, so
+	* this never needs a full-table scan (and therefore never needs a QueryPlan).
+	* Any read failure yields an empty manifest: reconcile then rebuilds every
+	* row from disk, which is exactly the desired degradation.
+	*/
+	async load(ids) {
+		this.entries.clear();
+		this.dirty.clear();
+		this.removed.clear();
+		if (ids.length === 0) return;
+		let rows = [];
+		try {
+			rows = await this.local.selectByIds(BLOB_TABLE, ids.map((id) => new RecordId(BLOB_TABLE, id)));
+		} catch {
+			return;
+		}
+		for (const row of rows) {
+			const id = readRowId(row);
+			if (!id) continue;
+			const entry = rowToEntry(id, row);
+			if (entry) this.entries.set(id, entry);
+		}
+	}
+	get(key) {
+		return this.entries.get(blobKeyId(key));
+	}
+	getById(id) {
+		return this.entries.get(id);
+	}
+	all() {
+		return [...this.entries.values()];
+	}
+	totalBytes() {
+		let total = 0;
+		for (const entry of this.entries.values()) total += entry.size;
+		return total;
+	}
+	pinnedBytes() {
+		let total = 0;
+		for (const entry of this.entries.values()) if (entry.pinned) total += entry.size;
+		return total;
+	}
+	put(entry) {
+		this.entries.set(entry.id, entry);
+		this.removed.delete(entry.id);
+		this.dirty.add(entry.id);
+	}
+	touch(id, now) {
+		const entry = this.entries.get(id);
+		if (!entry) return;
+		entry.lastAccess = now;
+		entry.hits += 1;
+		this.dirty.add(id);
+	}
+	setPinned(id, pinned) {
+		const entry = this.entries.get(id);
+		if (!entry || entry.pinned === pinned) return false;
+		entry.pinned = pinned;
+		this.dirty.add(id);
+		return true;
+	}
+	remove(id) {
+		if (!this.entries.delete(id)) return;
+		this.dirty.delete(id);
+		this.removed.add(id);
+	}
+	/** Forget everything without scheduling deletes — for a bucket switch, where
+	*  the rows belong to the store we are leaving and must stay put. */
+	reset() {
+		this.entries.clear();
+		this.dirty.clear();
+		this.removed.clear();
+	}
+	hasPendingWrites() {
+		return this.dirty.size > 0 || this.removed.size > 0;
+	}
+	/**
+	* Write back pending changes. Serialized: a second concurrent flush awaits
+	* the first rather than racing it into the same rows. Failures are swallowed
+	* on purpose — a lost metadata write costs an LRU timestamp, and the entry is
+	* rebuilt from disk on the next reconcile.
+	*/
+	async flush() {
+		if (this.flushing) return this.flushing;
+		if (!this.hasPendingWrites()) return;
+		const run = this.doFlush();
+		this.flushing = run;
+		try {
+			await run;
+		} finally {
+			this.flushing = null;
+		}
+	}
+	async doFlush() {
+		const dirty = [...this.dirty];
+		const removed = [...this.removed];
+		this.dirty.clear();
+		this.removed.clear();
+		for (const id of dirty) {
+			const entry = this.entries.get(id);
+			if (!entry) continue;
+			try {
+				await this.local.upsert(BLOB_TABLE, new RecordId(BLOB_TABLE, id), entryToRow(entry), "replace");
+			} catch {}
+		}
+		for (const id of removed) try {
+			await this.local.delete(BLOB_TABLE, new RecordId(BLOB_TABLE, id));
+		} catch {}
+	}
+};
+/** Row ids come back as a `RecordId` (SurrealDB) or a `table:id` string (SQLite). */
+function readRowId(row) {
+	const raw = row.id;
+	if (raw instanceof RecordId) return String(raw.id);
+	if (typeof raw === "string") {
+		const prefix = `${BLOB_TABLE}:`;
+		return raw.startsWith(prefix) ? raw.slice(prefix.length) : raw;
+	}
+	return null;
+}
+
+//#endregion
+//#region src/services/blobs/blob-cache.ts
+/**
+* Three-layer cache for bucket files.
+*
+*   L0  object URLs, refcounted, per tab      (this class)
+*   L1  bytes in OPFS, durable                (BlobStore)
+*   L2  the remote bucket over the sync WS    (injected `fetchRemote`)
+*
+* Nothing is ever dropped because it got old. A TTL would silently break the
+* offline case this cache exists to serve: the row referencing an image is in
+* the local cache indefinitely, so the image has to be too. Bytes only ever go
+* away for one of four reasons:
+*
+*  1. the app invalidated them — `bucket.put()`/`bucket.delete()` on that path;
+*  2. boot reconcile found no file behind the row (or a torn `.part-` write);
+*  3. a read found a size that disagrees with the manifest;
+*  4. the cache is over budget, and this is the least recently used unpinned
+*     entry that nothing is currently rendering.
+*/
+/** Evict down to this fraction of the budget, so eviction is not per-write. */
+const LOW_WATER = .8;
+/** Object URLs kept alive at zero references, so list scrolling doesn't thrash. */
+const HOT_URL_LIMIT = 32;
+/** Parallel remote reads during `prefetch`. Shares the sync socket's queue. */
+const PREFETCH_CONCURRENCY = 3;
+/** Debounce on manifest write-back. Every cache hit moves `lastAccess`, so
+*  flushing eagerly would turn rendering a list of avatars into a write storm. */
+const FLUSH_DEBOUNCE_MS = 2e3;
+function defaultUrlFactory() {
+	if (typeof URL === "undefined" || typeof URL.createObjectURL !== "function") return void 0;
+	return {
+		create: (blob) => URL.createObjectURL(blob),
+		revoke: (url) => URL.revokeObjectURL(url)
+	};
+}
+function isQuotaError(err) {
+	return err instanceof Error && (err.name === "QuotaExceededError" || err.name === "NS_ERROR_FILE_NO_DEVICE_SPACE");
+}
+var BlobCache = class {
+	store;
+	manifest;
+	fetchRemote;
+	headRemote;
+	logger;
+	now;
+	urlFactory;
+	maxBytes;
+	persistPaused = false;
+	/** Set after a quota failure survives one forced eviction. */
+	persistDisabled = false;
+	urls = /* @__PURE__ */ new Map();
+	/** Ids at zero references, oldest first — the hot-URL window. */
+	idleUrls = [];
+	inflight = /* @__PURE__ */ new Map();
+	flushTimer = null;
+	onPageHide = () => {
+		this.manifest.flush();
+	};
+	/**
+	* Resolves once the manifest has been reconciled against disk. Reads await
+	* it, so `start()` does NOT have to be awaited on the boot path — blocking
+	* boot on an OPFS directory walk delayed the WebSocket connect (and with it
+	* the connection supervisor) for no benefit.
+	*/
+	ready = Promise.resolve();
+	hits = 0;
+	misses = 0;
+	evictedEntries = 0;
+	evictedBytes = 0;
+	reconciledEntries = 0;
+	constructor(opts) {
+		this.store = opts.store;
+		this.manifest = opts.manifest;
+		this.fetchRemote = opts.fetchRemote;
+		this.headRemote = opts.headRemote;
+		this.logger = opts.logger.child({ service: "BlobCache" });
+		this.maxBytes = opts.maxBytes;
+		this.now = opts.now ?? (() => Date.now());
+		this.urlFactory = opts.urls ?? defaultUrlFactory();
+		if (typeof addEventListener === "function") addEventListener("pagehide", this.onPageHide);
+	}
+	/** Coalesce manifest write-back. Metadata only, so losing the tail costs an
+	*  LRU timestamp that reconcile reseeds from the file mtime. */
+	scheduleFlush() {
+		if (this.flushTimer) return;
+		this.flushTimer = setTimeout(() => {
+			this.flushTimer = null;
+			this.manifest.flush();
+		}, FLUSH_DEBOUNCE_MS);
+		this.flushTimer.unref?.();
+	}
+	/**
+	* Resolve the bytes for `key`, filling L1 on the way when `persist` is on.
+	* Returns null when the file does not exist remotely and is not cached.
+	*/
+	async read(key, options = {}) {
+		await this.ready;
+		const id = blobKeyId(key);
+		const persist = options.persist !== false && !this.persistDisabled;
+		if (!options.reload) {
+			const cached = await this.readLocal(key, id, options);
+			if (cached) {
+				this.hits++;
+				if (options.pin) this.manifest.setPinned(id, true);
+				return cached;
+			}
+		}
+		this.misses++;
+		const bytes = await this.fetchDeduped(key, id);
+		if (!bytes) {
+			await this.dropLocal(key, id);
+			return null;
+		}
+		if (persist) await this.persist(key, id, bytes, options.pin === true);
+		return bytes;
+	}
+	/**
+	* An object URL for `key`, refcounted. Callers MUST `release()`; the URL is
+	* revoked once the last holder lets go and it falls out of the hot window.
+	*/
+	async acquireUrl(key, options = {}) {
+		if (!this.urlFactory) return null;
+		const id = blobKeyId(key);
+		if (options.reload) this.revokeUrl(id);
+		else {
+			const live = this.urls.get(id);
+			if (live) return this.lease(id, live);
+		}
+		const blob = await this.read(key, options);
+		if (!blob) return null;
+		const existing = this.urls.get(id);
+		if (existing) return this.lease(id, existing);
+		const entry = {
+			url: this.urlFactory.create(blob),
+			refCount: 0
+		};
+		this.urls.set(id, entry);
+		return this.lease(id, entry);
+	}
+	lease(id, entry) {
+		entry.refCount++;
+		const idle = this.idleUrls.indexOf(id);
+		if (idle !== -1) this.idleUrls.splice(idle, 1);
+		let released = false;
+		return {
+			url: entry.url,
+			release: () => {
+				if (released) return;
+				released = true;
+				this.releaseUrl(id);
+			}
+		};
+	}
+	releaseUrl(id) {
+		const entry = this.urls.get(id);
+		if (!entry) return;
+		entry.refCount--;
+		if (entry.refCount > 0) return;
+		this.idleUrls.push(id);
+		while (this.idleUrls.length > HOT_URL_LIMIT) {
+			const evicted = this.idleUrls.shift();
+			const stale = this.urls.get(evicted);
+			if (stale && stale.refCount <= 0) this.revokeUrl(evicted);
+		}
+	}
+	revokeUrl(id) {
+		const entry = this.urls.get(id);
+		if (!entry) return;
+		this.urls.delete(id);
+		const idle = this.idleUrls.indexOf(id);
+		if (idle !== -1) this.idleUrls.splice(idle, 1);
+		this.urlFactory?.revoke(entry.url);
+	}
+	/** L1 lookup with the size check that catches torn and cross-tab writes. */
+	async readLocal(key, id, options) {
+		let blob;
+		try {
+			blob = await this.store.read(key);
+		} catch (err) {
+			if (err instanceof BlobKeyError) return null;
+			this.logger.warn({
+				err,
+				id
+			}, "blob read from local store failed");
+			return null;
+		}
+		const entry = this.manifest.getById(id);
+		if (!blob) {
+			if (entry) this.manifest.remove(id);
+			return null;
+		}
+		if (entry && entry.size !== blob.size) {
+			await this.dropLocal(key, id);
+			return null;
+		}
+		if (options.revalidate === "head" && !await this.headMatches(key, blob.size)) {
+			await this.dropLocal(key, id);
+			return null;
+		}
+		if (entry) this.manifest.touch(id, this.now());
+		else this.manifest.put({
+			id,
+			bucket: key.bucket,
+			path: key.path,
+			size: blob.size,
+			contentType: blob.type ?? "",
+			createdAt: this.now(),
+			lastAccess: this.now(),
+			hits: 1,
+			pinned: false
+		});
+		this.scheduleFlush();
+		return blob;
+	}
+	/** True when the remote agrees with the cached size, or cannot be reached. */
+	async headMatches(key, size) {
+		if (!this.headRemote) return true;
+		try {
+			const head = await this.headRemote(key);
+			const remoteSize = Number(head?.size);
+			return !Number.isFinite(remoteSize) || remoteSize === size;
+		} catch {
+			return true;
+		}
+	}
+	fetchDeduped(key, id) {
+		const running = this.inflight.get(id);
+		if (running) return running;
+		const promise = this.fetchRemote(key).finally(() => this.inflight.delete(id));
+		this.inflight.set(id, promise);
+		return promise;
+	}
+	async persist(key, id, bytes, pin) {
+		if (this.persistPaused) return;
+		try {
+			await this.writeThrough(key, id, bytes, pin);
+		} catch (err) {
+			if (!isQuotaError(err)) {
+				if (!(err instanceof BlobKeyError)) this.logger.warn({
+					err,
+					id
+				}, "blob write failed");
+				return;
+			}
+			await this.evictTo(Math.floor(this.maxBytes * .5));
+			try {
+				await this.writeThrough(key, id, bytes, pin);
+			} catch (retryErr) {
+				this.persistDisabled = true;
+				this.logger.warn({ err: retryErr }, "blob cache disabled: storage quota exhausted");
+			}
+		}
+	}
+	async writeThrough(key, id, bytes, pin) {
+		const size = await this.store.write(key, bytes);
+		const now = this.now();
+		const previous = this.manifest.getById(id);
+		this.manifest.put({
+			id,
+			bucket: key.bucket,
+			path: key.path,
+			size,
+			contentType: bytes.type ?? "",
+			createdAt: previous?.createdAt ?? now,
+			lastAccess: now,
+			hits: (previous?.hits ?? 0) + 1,
+			pinned: pin || previous?.pinned === true
+		});
+		this.scheduleFlush();
+		await this.enforceBudget();
+	}
+	/** Forget one path everywhere. Called on `bucket.put()`/`bucket.delete()`. */
+	async invalidate(key) {
+		await this.dropLocal(key, blobKeyId(key));
+	}
+	async dropLocal(key, id) {
+		this.revokeUrl(id);
+		this.manifest.remove(id);
+		this.scheduleFlush();
+		try {
+			await this.store.remove(key);
+		} catch (err) {
+			if (!(err instanceof BlobKeyError)) this.logger.warn({
+				err,
+				id
+			}, "blob delete failed");
+		}
+	}
+	setPinned(key, pinned) {
+		if (this.manifest.setPinned(blobKeyId(key), pinned)) this.scheduleFlush();
+	}
+	/**
+	* Bring total bytes under budget by dropping the least recently used
+	* entries. Pinned entries and anything with a live object URL are skipped —
+	* evicting bytes that a mounted `<img>` is displaying would blank it.
+	*/
+	async enforceBudget() {
+		if (this.manifest.totalBytes() <= this.maxBytes) {
+			this.persistPaused = false;
+			return;
+		}
+		const remaining = await this.evictTo(Math.floor(this.maxBytes * LOW_WATER));
+		if (remaining > this.maxBytes) {
+			if (!this.persistPaused) this.logger.warn({
+				totalBytes: remaining,
+				budgetBytes: this.maxBytes,
+				pinnedBytes: this.manifest.pinnedBytes()
+			}, "blob cache over budget with nothing evictable; pausing new writes");
+			this.persistPaused = true;
+		} else this.persistPaused = false;
+	}
+	/** Evict LRU-first until at or below `target`. Returns the resulting total. */
+	async evictTo(target) {
+		let total = this.manifest.totalBytes();
+		if (total <= target) return total;
+		const candidates = this.manifest.all().filter((e) => !e.pinned && (this.urls.get(e.id)?.refCount ?? 0) <= 0).sort((a, b) => a.lastAccess - b.lastAccess);
+		const dropped = [];
+		for (const entry of candidates) {
+			if (total <= target) break;
+			await this.dropLocal({
+				bucket: entry.bucket,
+				path: entry.path
+			}, entry.id);
+			total -= entry.size;
+			this.evictedEntries++;
+			this.evictedBytes += entry.size;
+			dropped.push(entry.id);
+		}
+		if (dropped.length > 0) this.logger.info({
+			count: dropped.length,
+			totalBytes: total,
+			budgetBytes: this.maxBytes
+		}, "blob cache evicted least-recently-used entries");
+		return total;
+	}
+	/**
+	* Rebuild the manifest from what is actually on disk. OPFS wins on existence
+	* in both directions: files with no row get a row (seeded from mtime), rows
+	* are only loaded for files that exist, and torn `.part-` writes are swept by
+	* the walk itself.
+	*
+	* Rows whose file vanished outside our control (a browser origin eviction)
+	* are left in `_00_blob`. They are inert — `load()` only ever asks for ids it
+	* found on disk — and are overwritten if that path is cached again.
+	*/
+	async reconcile() {
+		let stats;
+		try {
+			stats = await this.store.list();
+		} catch (err) {
+			this.logger.warn({ err }, "blob cache reconcile failed to list local store");
+			return;
+		}
+		await this.manifest.load(stats.map((s) => blobKeyId(s.key)));
+		let rebuilt = 0;
+		for (const stat of stats) {
+			const id = blobKeyId(stat.key);
+			const existing = this.manifest.getById(id);
+			if (!existing) {
+				this.manifest.put({
+					id,
+					bucket: stat.key.bucket,
+					path: stat.key.path,
+					size: stat.size,
+					contentType: "",
+					createdAt: stat.mtime,
+					lastAccess: stat.mtime,
+					hits: 0,
+					pinned: false
+				});
+				rebuilt++;
+			} else if (existing.size !== stat.size) this.manifest.put({
+				...existing,
+				size: stat.size
+			});
+		}
+		this.reconciledEntries = stats.length;
+		if (rebuilt > 0) this.logger.info({
+			rebuilt,
+			entries: stats.length
+		}, "blob cache rebuilt manifest rows from disk");
+		await this.enforceBudget();
+		await this.manifest.flush();
+	}
+	/** Warm the cache for offline use. Skips anything already cached. */
+	async prefetch(keys) {
+		const queue = keys.filter((key) => !this.manifest.get(key));
+		let cursor = 0;
+		const worker = async () => {
+			while (cursor < queue.length) {
+				const key = queue[cursor++];
+				try {
+					await this.read(key);
+				} catch (err) {
+					this.logger.warn({
+						err,
+						id: blobKeyId(key)
+					}, "blob prefetch failed");
+				}
+			}
+		};
+		await Promise.all(Array.from({ length: Math.min(PREFETCH_CONCURRENCY, queue.length) }, worker));
+	}
+	/** Bind to the boot bucket and hydrate the manifest from disk. Separate from
+	*  {@link setNamespace} because boot must reconcile even when the namespace
+	*  it lands on is the one the store was constructed with. */
+	async start(namespace) {
+		this.store.setNamespace(namespace);
+		this.ready = this.reconcile().catch(() => {});
+		await this.ready;
+	}
+	/** Repoint at another local bucket. The bytes of the old one stay on disk so
+	*  switching back (or signing back in) is still warm. */
+	async setNamespace(namespace) {
+		if (namespace === this.store.namespace) return;
+		await this.manifest.flush();
+		for (const id of [...this.urls.keys()]) this.revokeUrl(id);
+		this.inflight.clear();
+		this.manifest.reset();
+		this.store.setNamespace(namespace);
+		this.persistPaused = false;
+		this.ready = this.reconcile().catch(() => {});
+		await this.ready;
+	}
+	setMaxBytes(maxBytes) {
+		this.maxBytes = maxBytes;
+	}
+	/** Delete every cached byte in the current namespace. */
+	async clear() {
+		for (const id of [...this.urls.keys()]) this.revokeUrl(id);
+		for (const entry of this.manifest.all()) this.manifest.remove(entry.id);
+		this.inflight.clear();
+		try {
+			await this.store.clear();
+		} catch (err) {
+			this.logger.warn({ err }, "blob cache clear failed");
+		}
+		await this.manifest.flush();
+	}
+	async flush() {
+		await this.manifest.flush();
+	}
+	/** Flush metadata and drop every object URL. Must run before the local store
+	*  closes — the flush writes through it. */
+	async close() {
+		if (this.flushTimer) {
+			clearTimeout(this.flushTimer);
+			this.flushTimer = null;
+		}
+		if (typeof removeEventListener === "function") removeEventListener("pagehide", this.onPageHide);
+		await this.manifest.flush();
+		for (const id of [...this.urls.keys()]) this.revokeUrl(id);
+		this.inflight.clear();
+	}
+	stats() {
+		return {
+			entries: this.manifest.all().length,
+			totalBytes: this.manifest.totalBytes(),
+			budgetBytes: this.maxBytes,
+			pinnedBytes: this.manifest.pinnedBytes(),
+			evictedEntries: this.evictedEntries,
+			evictedBytes: this.evictedBytes,
+			reconciledEntries: this.reconciledEntries,
+			hits: this.hits,
+			misses: this.misses,
+			persistent: this.store.persistent && !this.persistDisabled,
+			persistPaused: this.persistPaused
+		};
+	}
+};
+
+//#endregion
+//#region src/services/blobs/index.ts
+/** Ceiling on the default budget, before the quota fraction is applied. */
+const MAX_DEFAULT_BUDGET_BYTES = 512 * 1024 * 1024;
+/** Share of the origin quota the blob cache may claim by default. The local
+*  database, the SQLite pool and any app storage share the same quota. */
+const QUOTA_FRACTION = .25;
+/** Used until `resolveBlobBudget()` reports back, and when there is no
+*  `navigator.storage.estimate()` to ask. */
+const FALLBACK_BLOB_BUDGET_BYTES = 128 * 1024 * 1024;
+/**
+* Budget from the real origin quota when the browser will tell us, otherwise a
+* conservative constant. Async because `estimate()` is; call it once at init
+* and hand the result to {@link BlobCache.setMaxBytes}.
+*/
+async function resolveBlobBudget(configured) {
+	if (typeof configured === "number" && configured > 0) return configured;
+	try {
+		const { quota } = await navigator.storage.estimate() ?? {};
+		if (typeof quota === "number" && quota > 0) return Math.min(MAX_DEFAULT_BUDGET_BYTES, Math.floor(quota * QUOTA_FRACTION));
+	} catch {}
+	return FALLBACK_BLOB_BUDGET_BYTES;
+}
+/**
+* Build the cache for a client. Falls back to an in-memory store when OPFS
+* cannot be written (Safari before `createWritable`, private modes, non-browser
+* hosts): the cache still dedupes and serves within the tab, which is exactly
+* the behaviour that existed before it — nothing regresses, nothing persists.
+*/
+function createBlobCache(opts) {
+	return new BlobCache({
+		store: opts.store ?? (opfsWritableSupported() ? new OpfsBlobStore(opts.namespace) : new MemoryBlobStore(opts.namespace)),
+		manifest: new BlobManifest(opts.local),
+		fetchRemote: opts.fetchRemote,
+		headRemote: opts.headRemote,
+		logger: opts.logger,
+		maxBytes: opts.maxBytes ?? FALLBACK_BLOB_BUDGET_BYTES
+	});
+}
+
 //#endregion
 //#region src/sp00ky.ts
+/** Coerce whatever the `.get()` RPC hands back into a Blob. */
+function bucketContentToBlob(content) {
+	if (content == null) return null;
+	if (content instanceof Blob) return content;
+	if (typeof content === "string") return new Blob([content]);
+	if (content instanceof ArrayBuffer) return new Blob([content]);
+	if (ArrayBuffer.isView(content)) return new Blob([content]);
+	return null;
+}
 var BucketHandle = class {
-	constructor(bucketName, remote) {
+	constructor(bucketName, remote, blobs) {
 		this.bucketName = bucketName;
 		this.remote = remote;
+		this.blobs = blobs;
 	}
 	async put(path, content) {
 		await this.remote.query(`RETURN f"${this.bucketName}:/${path}".put($content);`, { content });
+		await this.blobs?.invalidate({
+			bucket: this.bucketName,
+			path
+		});
 	}
 	async get(path) {
 		const [result] = await this.remote.query(`RETURN f"${this.bucketName}:/${path}".get();`);
 		return result;
 	}
+	/**
+	* Read through the local blob cache: OPFS first, the bucket second. Unlike
+	* {@link get} this survives a reload and works offline. Returns null when the
+	* file exists in neither place.
+	*/
+	async read(path, options) {
+		if (!this.blobs) return bucketContentToBlob(await this.get(path));
+		return this.blobs.read({
+			bucket: this.bucketName,
+			path
+		}, options);
+	}
+	/**
+	* A refcounted object URL for `path`, suitable for `<img src>`. The caller
+	* MUST call `release()` when the URL goes off screen. Returns null when the
+	* file does not exist, or when object URLs are unavailable (non-browser).
+	*/
+	async url(path, options) {
+		if (!this.blobs) return null;
+		return this.blobs.acquireUrl({
+			bucket: this.bucketName,
+			path
+		}, options);
+	}
+	/** Exempt `path` from pressure eviction. Pinned bytes never expire. */
+	pin(path) {
+		this.blobs?.setPinned({
+			bucket: this.bucketName,
+			path
+		}, true);
+	}
+	unpin(path) {
+		this.blobs?.setPinned({
+			bucket: this.bucketName,
+			path
+		}, false);
+	}
+	/** Drop `path` from the local cache without touching the remote file. */
+	async evict(path) {
+		await this.blobs?.invalidate({
+			bucket: this.bucketName,
+			path
+		});
+	}
+	/** Warm the cache for offline use. Already-cached paths are skipped. */
+	async prefetch(paths) {
+		await this.blobs?.prefetch(paths.map((path) => ({
+			bucket: this.bucketName,
+			path
+		})));
+	}
 	async delete(path) {
 		await this.remote.query(`RETURN f"${this.bucketName}:/${path}".delete();`);
+		await this.blobs?.invalidate({
+			bucket: this.bucketName,
+			path
+		});
 	}
 	async exists(path) {
 		const [result] = await this.remote.query(`RETURN f"${this.bucketName}:/${path}".exists();`);
@@ -9647,6 +10720,7 @@ function writeBootBucketHint(bucketId) {
 var Sp00kyClient = class {
 	local;
 	remote;
+	blobs;
 	connectionSupervisor;
 	persistenceClient;
 	migrator;
@@ -9730,6 +10804,15 @@ var Sp00kyClient = class {
 		this.local = createLocalEngine(this.config.localEngine, this.config.database, logger, { shared: tabsSupport.supported });
 		this.remote = new RemoteDatabaseService(this.config.database, logger);
 		this.connectionSupervisor = new ConnectionSupervisor(this.remote, logger);
+		this.blobs = createBlobCache({
+			local: this.local,
+			namespace: ANON_USER_ID,
+			logger,
+			fetchRemote: async (key) => bucketContentToBlob(await this.rawBucket(key.bucket).get(key.path)),
+			headRemote: (key) => this.rawBucket(key.bucket).head(key.path),
+			maxBytes: this.config.blobCache?.maxBytes,
+			store: this.config.blobCache?.enabled === false ? new MemoryBlobStore(ANON_USER_ID) : void 0
+		});
 		if (config.persistenceClient === "surrealdb") this.persistenceClient = new SurrealDBPersistenceClient(this.local, logger);
 		else if (config.persistenceClient === "localstorage" || !config.persistenceClient) this.persistenceClient = new LocalStoragePersistenceClient(logger);
 		else this.persistenceClient = config.persistenceClient;
@@ -9792,6 +10875,7 @@ var Sp00kyClient = class {
 				};
 			});
 		}
+		this.devTools.setBlobInfoProvider(() => this.blobs.stats());
 	}
 	/** The shared-tabs role machinery, wired to this client's modules. */
 	buildTabsCoordinator() {
@@ -9800,7 +10884,7 @@ var Sp00kyClient = class {
 		return new TabsCoordinator({
 			tabId,
 			fingerprint: computeTabsFingerprint({
-				coreVersion: "0.0.1-canary.162",
+				coreVersion: "0.0.1-canary.164",
 				schemaHash: hash53(this.config.schemaSurql),
 				endpoint: this.config.database.endpoint ?? "",
 				namespace: this.config.database.namespace,
@@ -9942,6 +11026,17 @@ var Sp00kyClient = class {
 			await this.remote.connect();
 			this.connectionSupervisor.start();
 			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "Remote database connected");
+			(async () => {
+				try {
+					this.blobs.setMaxBytes(await resolveBlobBudget(this.config.blobCache?.maxBytes));
+					await this.blobs.start(bootBucket);
+				} catch (e) {
+					this.logger.warn({
+						err: e,
+						Category: "sp00ky-client::Sp00kyClient::init"
+					}, "Blob cache failed to start; bucket files will not be cached locally");
+				}
+			})();
 			this.streamProcessor.setStateKeySuffix(bootBucket);
 			await this.streamProcessor.init();
 			this.streamProcessor.setPermissions(extractSelectPermissions(this.config.schemaSurql));
@@ -10037,6 +11132,7 @@ var Sp00kyClient = class {
 			from: this.local.currentBucketId,
 			Category: "sp00ky-client::Sp00kyClient::doSwitchBucket"
 		}, "Switching local bucket");
+		const leavingBucket = this.local.currentBucketId;
 		await this.sync.prepareBucketSwitch();
 		this.dataModule.quiesce();
 		this.crdtManager.closeAll({ flush: false });
@@ -10062,6 +11158,16 @@ var Sp00kyClient = class {
 				if (this.local.usesSurqlSchema) await this.migrator.provision(this.config.schemaSurql);
 				await this.local.queryUngated("DELETE _00_query;");
 			}
+			try {
+				if (this.config.blobCache?.clearOnSignOut && target === ANON_USER_ID && leavingBucket !== ANON_USER_ID) await this.blobs.clear();
+				await this.blobs.setNamespace(target);
+			} catch (e) {
+				this.logger.warn({
+					err: e,
+					target,
+					Category: "sp00ky-client::Sp00kyClient::doSwitchBucket"
+				}, "Blob cache bucket switch failed");
+			}
 			this.streamProcessor.setStateKeySuffix(target);
 			await this.streamProcessor.reset();
 			this.streamProcessor.setPermissions(extractSelectPermissions(this.config.schemaSurql));
@@ -10096,6 +11202,7 @@ var Sp00kyClient = class {
 		await this.appReleases.closeAll();
 		this.crdtManager.closeAll();
 		this.crdtManager.dispose();
+		await this.blobs.close().catch(() => {});
 		if (this.tabsCoordinator) await this.tabsCoordinator.stop();
 		await this.local.close();
 		await this.remote.close();
@@ -10301,7 +11408,16 @@ var Sp00kyClient = class {
 		return this.dataModule.run(backend, path, payload, options);
 	}
 	bucket(name) {
-		return new BucketHandle(name, this.remote);
+		return new BucketHandle(name, this.remote, this.blobs);
+	}
+	/** Cache-free handle. The blob cache reads the remote through this, so a
+	*  cache miss can't loop back into the cache. */
+	rawBucket(name) {
+		return new BucketHandle(name, this.remote, null);
+	}
+	/** Blob cache counters for DevTools. */
+	getBlobCacheStats() {
+		return this.blobs.stats();
 	}
 	create(id, data) {
 		return this.dataModule.create(id, data);
@@ -10336,4 +11452,4 @@ var Sp00kyClient = class {
 };
 
 //#endregion
-export { AppReleaseHandle, AppReleaseModule, AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, FeatureFlagHandle, FeatureFlagModule, MATERIALIZATION_SAMPLE_WINDOW, Sp00kyClient, createAuthEventSystem, cursorColorFromName, fileToUint8Array, semverGt, textToHtml };
+export { AppReleaseHandle, AppReleaseModule, AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, FeatureFlagHandle, FeatureFlagModule, MATERIALIZATION_SAMPLE_WINDOW, Sp00kyClient, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, fileToUint8Array, semverGt, textToHtml };