@spooky-sync/core 0.0.1-canary.153 → 0.0.1-canary.155

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as serializeRow, i as reviveRow, n as renderOrderSql, o as resolveRelations, r as renderWhereSql, s as stableKey, t as project } from "./sqlite-plan-sql.js";
+import { a as renderWhereSql, c as resolveRelations, i as renderOrderSql, l as stableKey, o as reviveRow, r as project, s as serializeRow, t as PROMOTION_OPEN_OPTIONS } from "./sqlite-open.js";
 import { DateTime, Duration, RecordId, Surreal, Uuid, applyDiagnostics, createRemoteEngines } from "surrealdb";
 import { QueryBuilder, RecordId as RecordId$1, cyrb53 } from "@spooky-sync/query-builder";
 import pino from "pino";
@@ -1141,6 +1141,7 @@ function renderRelationFetchSurql(req) {
 var SurrealCacheEngine = class extends LocalDatabaseService {
 	/** SurrealDB needs its SurrealQL schema provisioned locally. */
 	usesSurqlSchema = true;
+	engineKind = "surrealdb";
 	/** {@link LocalCacheEngine} alias for {@link LocalDatabaseService.switchStore}. */
 	switchBucket(bucketId) {
 		return this.switchStore(bucketId);
@@ -1441,6 +1442,171 @@ function setPath(obj, path, value) {
 	cur[parts[parts.length - 1]] = value;
 }
 
+//#endregion
+//#region src/services/database/sqlite-transport.ts
+/** Thrown into pending follower calls when the leader (or its port) goes away.
+*  Callers treat it like a transient error: the op may be retried once a new
+*  leader is attached; nothing was necessarily executed. */
+var BrokerPortClosedError = class extends Error {
+	retryable = true;
+	constructor(reason) {
+		super(`sqlite transport lost: ${reason}`);
+		this.name = "BrokerPortClosedError";
+	}
+};
+/** Shared request/response bookkeeping over any postMessage-shaped channel. */
+var BaseTransport = class {
+	pending = /* @__PURE__ */ new Map();
+	seq = 0;
+	closed = false;
+	constructor(logger) {
+		this.logger = logger;
+	}
+	get connected() {
+		return !this.closed;
+	}
+	handleMessage(data) {
+		const { id, ok, error, ...rest } = data ?? {};
+		const p = this.pending.get(id);
+		if (!p) return;
+		this.pending.delete(id);
+		if (ok) p.resolve(rest);
+		else p.reject(new Error(error));
+	}
+	call(type, payload) {
+		if (this.closed) return Promise.reject(this.makeError("transport closed"));
+		const id = ++this.seq;
+		return new Promise((resolve, reject) => {
+			this.pending.set(id, {
+				resolve,
+				reject
+			});
+			try {
+				this.post({
+					id,
+					type,
+					payload
+				});
+			} catch (e) {
+				this.pending.delete(id);
+				reject(e);
+			}
+		});
+	}
+	failAll(reason) {
+		if (this.pending.size === 0) return;
+		const err = this.makeError(reason);
+		for (const [, p] of this.pending) p.reject(err);
+		this.pending.clear();
+	}
+	close(reason = "closed") {
+		if (this.closed) return;
+		this.closed = true;
+		this.failAll(reason);
+	}
+};
+var WorkerSqliteTransport = class extends BaseTransport {
+	kind = "worker";
+	worker;
+	/** Fired when the worker reports it fenced itself after a leadership steal
+	*  (see sqlite-worker.js). The engine must treat the store as gone. */
+	onLockLost = null;
+	constructor(logger) {
+		super(logger);
+		this.worker = new Worker(new URL("./sqlite-worker.js", import.meta.url), { type: "module" });
+		this.worker.onmessage = (ev) => {
+			if (ev.data?.type === "lock-lost") {
+				this.logger.error({
+					reason: ev.data.reason,
+					Category: "sp00ky-client::SqliteCacheEngine::worker"
+				}, "SQLite worker fenced after leadership loss");
+				this.failAll("worker fenced");
+				this.onLockLost?.(String(ev.data.reason ?? "lock-lost"));
+				return;
+			}
+			this.handleMessage(ev.data);
+		};
+		const crash = (msg) => {
+			this.logger.error({
+				err: this.makeError(msg),
+				Category: "sp00ky-client::SqliteCacheEngine::worker"
+			}, "Worker error");
+			this.failAll(msg);
+		};
+		this.worker.onerror = (e) => crash(e.message || "onerror");
+		this.worker.onmessageerror = () => crash("messageerror");
+	}
+	post(msg, transfer) {
+		if (transfer) this.worker.postMessage(msg, transfer);
+		else this.worker.postMessage(msg);
+	}
+	makeError(reason) {
+		return /* @__PURE__ */ new Error(`SQLite worker crashed: ${reason}`);
+	}
+	/** Forward a follower's MessagePort into the worker as an extra client. */
+	addClientPort(clientId, port) {
+		if (this.closed) return Promise.reject(this.makeError("transport closed"));
+		const id = ++this.seq;
+		return new Promise((resolve, reject) => {
+			this.pending.set(id, {
+				resolve: () => resolve(),
+				reject
+			});
+			this.worker.postMessage({
+				id,
+				type: "add-client",
+				payload: { clientId }
+			}, [port]);
+		});
+	}
+	removeClientPort(clientId) {
+		return this.call("remove-client", { clientId }).then(() => void 0);
+	}
+	/** Ask the worker to close + pauseVfs + self-close (graceful pagehide). */
+	shutdown() {
+		return this.call("shutdown").then(() => void 0);
+	}
+	close(reason = "closed") {
+		if (this.closed) return;
+		super.close(reason);
+		this.worker.terminate();
+	}
+};
+var PortSqliteTransport = class extends BaseTransport {
+	kind = "port";
+	constructor(port, onPortDead, logger) {
+		super(logger);
+		this.port = port;
+		this.onPortDead = onPortDead;
+		port.onmessage = (ev) => this.handleMessage(ev.data);
+		port.onmessageerror = () => this.dead("messageerror");
+		port.start?.();
+	}
+	/** The broker/coordinator learned the leader is gone; the port itself has no
+	*  close event, so the coordinator calls this explicitly. */
+	markDead(reason) {
+		this.dead(reason);
+	}
+	dead(reason) {
+		if (this.closed) return;
+		this.closed = true;
+		this.failAll(reason);
+		try {
+			this.port.close();
+		} catch {}
+		this.onPortDead(reason);
+	}
+	post(msg) {
+		this.port.postMessage(msg);
+	}
+	makeError(reason) {
+		return new BrokerPortClosedError(reason);
+	}
+	close(reason = "closed") {
+		this.dead(reason);
+	}
+};
+
 //#endregion
 //#region src/services/database/sqlite-cache-engine.ts
 /**
@@ -1499,9 +1665,9 @@ function pureWriteOpResult(op) {
 *   oracle E2E in the browser.
 */
 var SqliteCacheEngine = class {
-	worker = null;
-	seq = 0;
-	pending = /* @__PURE__ */ new Map();
+	/** The wire to the SQLite worker: an owned dedicated Worker (solo/leader) or
+	*  a MessagePort into another tab's worker (follower). See sqlite-transport. */
+	transport = null;
 	storeEpoch = 0;
 	knownTables = /* @__PURE__ */ new Set();
 	useOpfs;
@@ -1509,6 +1675,9 @@ var SqliteCacheEngine = class {
 	*  Flipped off at runtime if the worker script predates the `select` op
 	*  (stale cached bundle) — degrade to the legacy multi-hop path, don't break. */
 	workerSelect;
+	/** What `workerSelect` was at construction, so DevTools can tell a runtime
+	*  downgrade (configured true, effective false) from a configured-off. */
+	workerSelectConfigured;
 	events = createDatabaseEventSystem();
 	bucketId = "anon";
 	/** Durability of the local store, set on every open. A plain Set of callbacks
@@ -1521,11 +1690,21 @@ var SqliteCacheEngine = class {
 	storageHealthSubs = /* @__PURE__ */ new Set();
 	/** Schemaless — tables are created lazily on first write; no migrator. */
 	usesSurqlSchema = false;
+	engineKind = "sqlite";
+	/** Shared-tabs mode: the engine's transport is swapped at runtime by the
+	*  TabsCoordinator (owner worker as leader, leader's port as follower). */
+	shared;
+	/** Leaderless parking (shared mode): ops entering the opQueue await this
+	*  gate until a new role lands or the timeout rejects them. */
+	roleGate = null;
+	roleGateTimer = null;
 	constructor(config, logger, opts = {}) {
 		this.config = config;
 		this.logger = logger;
 		this.useOpfs = opts.useOpfs ?? true;
 		this.workerSelect = opts.workerSelect ?? config.workerSelect ?? true;
+		this.workerSelectConfigured = this.workerSelect;
+		this.shared = opts.shared ?? false;
 	}
 	get epoch() {
 		return this.storeEpoch;
@@ -1553,6 +1732,40 @@ var SqliteCacheEngine = class {
 	getConfig() {
 		return this.config;
 	}
+	/**
+	* Storage numbers for the DevTools Storage tab. Uses {@link call} so the
+	* reads serialize with regular traffic (no SQLITE_BUSY). Never throws — the
+	* worker may be mid bucket-switch; a failure lands in `error` instead.
+	*/
+	async getStorageDiagnostics(opts) {
+		const diag = {
+			engine: "sqlite",
+			bucketId: this.bucketId,
+			useOpfs: this.useOpfs,
+			workerSelectConfigured: this.workerSelectConfigured,
+			workerSelectEffective: this.workerSelect
+		};
+		try {
+			const { rows } = await this.call("exec", { sql: "SELECT (SELECT * FROM pragma_page_count()) * (SELECT * FROM pragma_page_size()) AS bytes, (SELECT * FROM pragma_freelist_count()) * (SELECT * FROM pragma_page_size()) AS freelist" });
+			diag.dbSizeBytes = rows?.[0]?.bytes;
+			diag.freelistBytes = rows?.[0]?.freelist;
+			if (opts?.tableCounts) {
+				const { rows: tables } = await this.call("exec", { sql: "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name" });
+				const names = (tables ?? []).map((r) => r.name);
+				if (names.length) {
+					const sql = names.map((n) => `SELECT '${n.replace(/'/g, "''")}' AS t, COUNT(*) AS n FROM "${n.replace(/"/g, "\"\"")}"`).join(" UNION ALL ");
+					const { rows: counts } = await this.call("exec", { sql });
+					diag.tableCounts = (counts ?? []).map((r) => ({
+						table: r.t,
+						rows: r.n
+					}));
+				} else diag.tableCounts = [];
+			}
+		} catch (e) {
+			diag.error = e instanceof Error ? e.message : String(e);
+		}
+		return diag;
+	}
 	getEvents() {
 		return this.events;
 	}
@@ -1567,36 +1780,16 @@ var SqliteCacheEngine = class {
 	beginSwitch() {
 		return () => {};
 	}
-	spawnWorker() {
-		const worker = new Worker(new URL("./sqlite-worker.js", import.meta.url), { type: "module" });
-		worker.onmessage = (ev) => {
-			const { id, ok, error, ...rest } = ev.data ?? {};
-			const p = this.pending.get(id);
-			if (!p) return;
-			this.pending.delete(id);
-			if (ok) p.resolve(rest);
-			else p.reject(new Error(error));
-		};
-		const failAll = (msg) => {
-			const err = /* @__PURE__ */ new Error(`SQLite worker crashed: ${msg}`);
-			this.logger.error({
-				err,
-				Category: "sp00ky-client::SqliteCacheEngine::worker"
-			}, "Worker error");
-			for (const [, p] of this.pending) p.reject(err);
-			this.pending.clear();
-		};
-		worker.onerror = (e) => failAll(e.message || "onerror");
-		worker.onmessageerror = () => failAll("messageerror");
-		return worker;
-	}
 	/** Serializes every worker op so reads/writes never overlap at the VFS layer
 	*  (overlapping ops trip SQLITE_BUSY). Mirrors the SurrealDB engine's
-	*  single-flight query queue. */
+	*  single-flight query queue. (The worker keeps its own chain too, for
+	*  multi-client mode; this one additionally provides the queue-wait stat and
+	*  the boot/switch atomicity below.) */
 	opQueue = Promise.resolve();
 	call(type, payload) {
 		const enqueuedAt = performance.now();
-		const run = () => {
+		const run = async () => {
+			if (this.roleGate) await this.roleGate.promise;
 			getStats().queueWaitMs += performance.now() - enqueuedAt;
 			return this.rawCall(type, payload);
 		};
@@ -1605,8 +1798,7 @@ var SqliteCacheEngine = class {
 		return result;
 	}
 	rawCall(type, payload) {
-		if (!this.worker) throw new Error("SqliteCacheEngine: not connected");
-		const id = ++this.seq;
+		if (!this.transport) throw new Error("SqliteCacheEngine: not connected");
 		const s = getStats();
 		s.roundTrips++;
 		s.byType[type] = (s.byType[type] ?? 0) + 1;
@@ -1616,31 +1808,19 @@ var SqliteCacheEngine = class {
 		}
 		s.inFlight++;
 		s.maxInFlight = Math.max(s.maxInFlight, s.inFlight);
-		const done = () => {
-			s.inFlight--;
-		};
+		if (this.transport.kind === "port") s.proxiedOps = (s.proxiedOps ?? 0) + 1;
 		const sentAt = performance.now();
-		return new Promise((resolve, reject) => {
-			this.pending.set(id, {
-				resolve: (v) => {
-					done();
-					const wt = v?.wt;
-					if (typeof wt === "number") {
-						s.workerMs += wt;
-						s.rpcOverheadMs += Math.max(0, performance.now() - sentAt - wt);
-					}
-					resolve(v);
-				},
-				reject: (e) => {
-					done();
-					reject(e);
-				}
-			});
-			this.worker.postMessage({
-				id,
-				type,
-				payload
-			});
+		return this.transport.call(type, payload).then((v) => {
+			s.inFlight--;
+			const wt = v?.wt;
+			if (typeof wt === "number") {
+				s.workerMs += wt;
+				s.rpcOverheadMs += Math.max(0, performance.now() - sentAt - wt);
+			}
+			return v;
+		}, (e) => {
+			s.inFlight--;
+			throw e;
 		});
 	}
 	/**
@@ -1648,25 +1828,41 @@ var SqliteCacheEngine = class {
 	* {@link call}) so it can run as the body of an already-queued opQueue entry
 	* without re-queuing onto itself. Callers must run it through the opQueue.
 	*/
-	async openInternal(bucketId) {
-		this.worker = this.spawnWorker();
+	/** Seam for tests: swap in a fake transport instead of a real Worker. */
+	createTransport() {
+		return new WorkerSqliteTransport(this.logger);
+	}
+	async openInternal(bucketId, extras) {
+		if (!this.transport || this.transport.kind !== "worker" || !this.transport.connected) {
+			this.transport = this.createTransport();
+			if (this.transport instanceof WorkerSqliteTransport) this.transport.onLockLost = (reason) => {
+				this.transport = null;
+				this.storeEpoch++;
+				this.openRoleGate(`worker fenced: ${reason}`);
+			};
+		}
 		const { persisted, opfsError } = await this.rawCall("open", {
 			dbName: bucketId,
 			useOpfs: this.useOpfs,
-			systemTables: SYSTEM_TABLES
+			systemTables: SYSTEM_TABLES,
+			...extras?.workerLockName ? { workerLockName: extras.workerLockName } : {},
+			...extras?.openOptions ? { openOptions: extras.openOptions } : {}
 		});
 		this.knownTables.clear();
 		for (const t of SYSTEM_TABLES) this.knownTables.add(t);
 		this.bucketId = bucketId;
 		const fellBack = this.useOpfs && !persisted;
-		this.setStorageHealth({
+		const health = {
 			status: persisted ? "persistent" : "memory",
-			fallback: fellBack,
-			error: fellBack ? opfsError : void 0
-		});
+			fallback: fellBack
+		};
+		if (fellBack && opfsError) health.error = opfsError;
+		if (this.shared) health.role = this.roleLabel;
+		this.setStorageHealth(health);
 		const stats = getStats();
 		stats.persisted = persisted;
-		stats.opfsError = fellBack ? opfsError : void 0;
+		if (fellBack && opfsError) stats.opfsError = opfsError;
+		else delete stats.opfsError;
 		if (fellBack) this.logger.error({
 			bucketId,
 			opfsError,
@@ -1691,23 +1887,174 @@ var SqliteCacheEngine = class {
 	async switchBucket(bucketId) {
 		this.storeEpoch++;
 		await this.enqueue(async () => {
-			if (this.worker) {
+			if (this.transport) {
 				try {
 					await this.rawCall("close");
 				} catch {}
-				this.worker.terminate();
-				this.worker = null;
+				this.transport.close("bucket switch");
+				this.transport = null;
 			}
 			await this.openInternal(bucketId);
 		});
 	}
 	async close() {
-		if (!this.worker) return;
+		if (!this.transport) return;
 		try {
 			await this.call("close");
 		} catch {}
-		this.worker.terminate();
-		this.worker = null;
+		this.transport.close("engine closed");
+		this.transport = null;
+	}
+	/** Which role the current transport represents, for StorageHealth. */
+	roleLabel = "solo";
+	/** True once this engine has had a usable store at least once; role changes
+	*  after that point invalidate in-flight reads and must bump the epoch. */
+	hadStore = false;
+	/**
+	* Role transitions run on their OWN chain, never on the opQueue: parked ops
+	* sit INSIDE opQueue entries waiting for the role gate, so a transition
+	* queued behind them could never run to release them (deadlock). Transitions
+	* are safe off-queue because in-flight ops on a dead transport were already
+	* rejected, parked ops only resume after the transition completes, and the
+	* worker serializes everything worker-side anyway.
+	*/
+	transitionChain = Promise.resolve();
+	chainTransition(fn) {
+		const result = this.transitionChain.then(fn, fn);
+		this.transitionChain = result.then(() => void 0, () => void 0);
+		return result;
+	}
+	openRoleGate(reason) {
+		if (this.roleGate) return;
+		let release;
+		let rejectFn;
+		const promise = new Promise((res, rej) => {
+			release = res;
+			rejectFn = rej;
+		});
+		promise.catch(() => {});
+		this.roleGate = {
+			promise,
+			release
+		};
+		this.roleGateTimer = setTimeout(() => {
+			rejectFn(new BrokerPortClosedError(`no leader adopted this tab: ${reason}`));
+			this.roleGate = null;
+			this.roleGateTimer = null;
+		}, 2e4);
+	}
+	closeRoleGate() {
+		if (this.roleGateTimer) clearTimeout(this.roleGateTimer);
+		this.roleGateTimer = null;
+		this.roleGate?.release();
+		this.roleGate = null;
+	}
+	/**
+	* Become the store owner (leader). Boot and failover share this path; a
+	* failover (a previous transport existed) bumps the epoch FIRST so every
+	* in-flight chain that captured the old epoch fences itself. `resumeHeld`
+	* keeps the live worker after a broker restart and only rolls the
+	* per-leadership lock forward.
+	*/
+	async adoptOwner(bucketId, opts) {
+		this.roleLabel = "leader";
+		return this.chainTransition(async () => {
+			if (opts.resumeHeld && this.transport?.kind === "worker" && this.transport.connected && this.bucketId === bucketId) {
+				await this.rawCall("relock", { workerLockName: opts.workerLockName });
+				this.closeRoleGate();
+				return this.storageHealthValue;
+			}
+			if (this.hadStore) this.storeEpoch++;
+			if (this.transport) {
+				try {
+					if (this.transport.kind === "worker") await this.rawCall("close");
+				} catch {}
+				this.transport.close("adopting ownership");
+				this.transport = null;
+			}
+			await this.openInternal(bucketId, {
+				workerLockName: opts.workerLockName,
+				openOptions: {
+					...PROMOTION_OPEN_OPTIONS,
+					disallowMemoryFallback: !opts.allowMemoryFallback
+				}
+			});
+			try {
+				await this.rawCall("run", { sql: "DELETE FROM \"_00_query\"" });
+			} catch {}
+			getStats().roleChanges = (getStats().roleChanges ?? 0) + 1;
+			this.hadStore = true;
+			this.closeRoleGate();
+			return this.storageHealthValue;
+		});
+	}
+	/** Attach to a leader's worker through `dbPort` (follower). */
+	async adoptAttached(dbPort, snapshot, onPortDead) {
+		this.roleLabel = "follower";
+		return this.chainTransition(async () => {
+			if (this.hadStore) this.storeEpoch++;
+			this.transport?.close("adopting leader port");
+			this.transport = new PortSqliteTransport(dbPort, onPortDead, this.logger);
+			this.bucketId = snapshot.bucketId;
+			this.knownTables.clear();
+			for (const t of SYSTEM_TABLES) this.knownTables.add(t);
+			const health = {
+				...snapshot.storageHealth,
+				role: "follower"
+			};
+			this.setStorageHealth(health);
+			const stats = getStats();
+			stats.persisted = snapshot.storageHealth.status === "persistent";
+			stats.roleChanges = (stats.roleChanges ?? 0) + 1;
+			delete stats.opfsError;
+			this.hadStore = true;
+			this.closeRoleGate();
+		});
+	}
+	/** Demoted while owning the store (zombie thaw, stale promotion): tear the
+	*  worker down so its OPFS handles free up, then park until re-adopted. */
+	async releaseOwnership() {
+		await this.chainTransition(async () => {
+			if (this.transport) {
+				try {
+					if (this.transport.kind === "worker") await this.transport.shutdown();
+				} catch {}
+				this.transport.close("ownership released");
+				this.transport = null;
+			}
+			this.storeEpoch++;
+			this.openRoleGate("ownership released");
+		});
+	}
+	/** The leader (or its port) died. Called from the port-dead callback and the
+	*  coordinator; NOT enqueued, so in-flight ops reject immediately instead of
+	*  waiting behind whatever is stuck. */
+	onLeaderLost(reason) {
+		if (this.transport?.kind === "port") {
+			this.transport.close(reason);
+			this.transport = null;
+		}
+		this.storeEpoch++;
+		this.openRoleGate(reason);
+	}
+	/** Leader side: forward a follower's dbPort into the owned worker. */
+	async exposeClientPort(clientId, port) {
+		if (this.transport?.kind !== "worker") throw new Error("SqliteCacheEngine: not the store owner");
+		await this.transport.addClientPort(clientId, port);
+	}
+	async removeClientPort(clientId) {
+		if (this.transport?.kind !== "worker") return;
+		await this.transport.removeClientPort(clientId);
+	}
+	/** Graceful pagehide as owner: release OPFS handles NOW so the next leader
+	*  does not race the browser's worker GC. */
+	async shutdownOwnedWorker() {
+		if (this.transport?.kind !== "worker") return;
+		try {
+			await this.transport.shutdown();
+		} catch {}
+		this.transport.close("shutdown");
+		this.transport = null;
 	}
 	async ensureTable(table) {
 		if (this.knownTables.has(table)) return;
@@ -2098,9 +2445,12 @@ function normalizePlanForClone(plan) {
 *   `this.local` through the SurrealQL-vocabulary shim + verb surface.
 * - a custom object → used as-is (must satisfy {@link LocalStore}).
 */
-function createLocalEngine(choice, config, logger) {
+function createLocalEngine(choice, config, logger, opts = {}) {
 	if (choice === void 0 || choice === "surrealdb") return new SurrealCacheEngine(config, logger);
-	if (choice === "sqlite") return new SqliteCacheEngine(config, logger, { useOpfs: (config.store ?? "memory") !== "memory" });
+	if (choice === "sqlite") return new SqliteCacheEngine(config, logger, {
+		useOpfs: (config.store ?? "memory") !== "memory",
+		shared: opts.shared
+	});
 	return choice;
 }
 
@@ -2225,6 +2575,35 @@ function readNumberAfter(sql, from) {
 	return m ? parseInt(m[0], 10) : null;
 }
 
+//#endregion
+//#region src/modules/data/mutation-id.ts
+/**
+* Outbox mutation ids. Previously `_00_pending_mutations:${Date.now()}`, which
+* (a) collides when two mutations land in the same millisecond, a real case
+* once multiple tabs share one store, and (b) never actually ordered the
+* drain, because `loadFromDatabase` sorted by a `created_at` field that does
+* not exist on the table. The new shape is sortable AND collision-free:
+*
+*   <13-digit zero-padded ms timestamp>_<4-digit base36 seq>_<tabId>
+*
+* Lexicographic order == chronological order (per tab; cross-tab within-ms
+* ordering is arbitrary, which matches reality), so `ORDER BY id` in the
+* drain is now meaningful. The tabId suffix also routes rollbacks back to the
+* tab that owns the mutation in shared-tabs mode.
+*/
+let seq = 0;
+/** Tab identity for mutation ids in SOLO mode, minted once per session. In
+*  shared-tabs mode the coordinator's tabId is passed in instead. */
+const FALLBACK_TAB_ID = Math.random().toString(36).slice(2, 8);
+function mintMutationId(tabId) {
+	return `_00_pending_mutations:${Date.now().toString().padStart(13, "0")}_${(seq = (seq + 1) % 36 ** 4).toString(36).padStart(4, "0")}_${tabId ?? FALLBACK_TAB_ID}`;
+}
+/** The tab that created the mutation, or null for a legacy numeric id. */
+function mutationOwnerTabId(mutationId) {
+	const parts = (mutationId.startsWith("_00_pending_mutations:") ? mutationId.slice(22) : mutationId).split("_");
+	return parts.length >= 3 ? parts[parts.length - 1] : null;
+}
+
 //#endregion
 //#region src/modules/data/index.ts
 /** Push a timing sample (ms) into a rolling window, capped at the sample window. */
@@ -2258,6 +2637,9 @@ function phaseStatOf(samples, lastMs) {
 * Uses CacheModule for all storage operations.
 */
 var DataModule = class {
+	/** Tab identity baked into mutation ids (shared-tabs rollback routing);
+	*  undefined in solo mode, where mutation-id falls back to a session id. */
+	tabId;
 	activeQueries = /* @__PURE__ */ new Map();
 	pendingQueries = /* @__PURE__ */ new Map();
 	subscriptions = /* @__PURE__ */ new Map();
@@ -2317,6 +2699,11 @@ var DataModule = class {
 	setSessionId(sessionId) {
 		this.sessionId = sessionId;
 	}
+	/** Shared-tabs: bake this tab's identity into mutation ids so a rollback of
+	*  a follower's mutation routes back to the tab that made it. */
+	setTabId(tabId) {
+		this.tabId = tabId;
+	}
 	/**
 	* Update the authenticated user record id. Pass `null` on sign-out.
 	* Read by `Sp00kySync.listRefTable()` so the LIVE subscription and
@@ -3069,7 +3456,7 @@ var DataModule = class {
 		if (!tableSchema) throw new Error(`Table ${tableName} not found`);
 		const rid = parseRecordIdString(id);
 		const params = parseParams(tableSchema.columns, data);
-		const mutationId = parseRecordIdString(`_00_pending_mutations:${Date.now()}`);
+		const mutationId = parseRecordIdString(mintMutationId(this.tabId));
 		const dataKeys = Object.keys(params).map((key) => ({
 			key,
 			variable: `data_${key}`
@@ -3112,7 +3499,7 @@ var DataModule = class {
 		if (!tableSchema) throw new Error(`Table ${tableName} not found`);
 		const rid = parseRecordIdString(id);
 		const params = parseParams(tableSchema.columns, data);
-		const mutationId = parseRecordIdString(`_00_pending_mutations:${Date.now()}`);
+		const mutationId = parseRecordIdString(mintMutationId(this.tabId));
 		const [beforeRecord] = await withRetry(this.logger, () => this.local.query("SELECT * FROM ONLY $id", { id: rid }));
 		const query = surql.seal(surql.tx([
 			surql.updateSet("id", [{ statement: "_00_rv += 1" }]),
@@ -3163,7 +3550,7 @@ var DataModule = class {
 		const tableName = extractTablePart(id);
 		if (!this.schema.tables.find((t) => t.name === tableName)) throw new Error(`Table ${tableName} not found`);
 		const rid = parseRecordIdString(id);
-		const mutationId = parseRecordIdString(`_00_pending_mutations:${Date.now()}`);
+		const mutationId = parseRecordIdString(mintMutationId(this.tabId));
 		const [beforeRecords] = await this.local.query("SELECT * FROM ONLY $id", { id: rid });
 		const beforeRecord = beforeRecords ?? {};
 		const query = surql.seal(surql.tx([surql.delete("id"), surql.createMutation("delete", "mid", "id")]));
@@ -3613,39 +4000,31 @@ var UpQueue = class {
 	async removeEventFromDatabase(mutation_id) {
 		return this.local.query(`DELETE $mutation_id`, { mutation_id });
 	}
+	/**
+	* Shared-tabs: a follower committed an outbox row into the shared store and
+	* notified the leader; enqueue exactly that row. Idempotent: a replayed
+	* notify (failover) or a row already queued is a no-op, and a row that never
+	* committed simply is not found (the follower's own write promise already
+	* rejected in that case).
+	*/
+	async enqueueFromDatabase(mutationId) {
+		if (this.queue.some((e) => encodeUpEventId(e) === mutationId)) return;
+		try {
+			const [records] = await this.local.query(`SELECT * FROM $mutation_id`, { mutation_id: parseRecordIdString(mutationId) });
+			const event = Array.isArray(records) && records[0] ? rowToUpEvent(records[0], this.logger) : null;
+			if (event) this.addToQueue(event);
+		} catch (error) {
+			this.logger.error({
+				error,
+				mutationId,
+				Category: "sp00ky-client::UpQueue::enqueueFromDatabase"
+			}, "Failed to load a forwarded mutation");
+		}
+	}
 	async loadFromDatabase() {
 		try {
-			const [records] = await this.local.query(`SELECT * FROM _00_pending_mutations ORDER BY created_at ASC`);
-			this.queue = records.map((r) => {
-				switch (r.mutationType) {
-					case "create": return {
-						type: "create",
-						mutation_id: parseRecordIdString(r.id),
-						record_id: parseRecordIdString(r.recordId),
-						data: r.data,
-						tableName: extractTablePart(r.recordId)
-					};
-					case "update": return {
-						type: "update",
-						mutation_id: parseRecordIdString(r.id),
-						record_id: parseRecordIdString(r.recordId),
-						data: r.data,
-						beforeRecord: r.beforeRecord
-					};
-					case "delete": return {
-						type: "delete",
-						mutation_id: parseRecordIdString(r.id),
-						record_id: parseRecordIdString(r.recordId)
-					};
-					default:
-						this.logger.warn({
-							mutationType: r.mutationType,
-							record: r,
-							Category: "sp00ky-client::UpQueue::loadFromDatabase"
-						}, "Unknown mutation type");
-						return null;
-				}
-			}).filter((e) => e !== null);
+			const [records] = await this.local.query(`SELECT * FROM _00_pending_mutations ORDER BY id ASC`);
+			this.queue = records.map((r) => rowToUpEvent(r, this.logger)).filter((e) => e !== null);
 		} catch (error) {
 			this.logger.error({
 				error,
@@ -3654,6 +4033,41 @@ var UpQueue = class {
 		}
 	}
 };
+/** The stable string id of an event's outbox row. */
+function encodeUpEventId(event) {
+	return encodeRecordId(event.mutation_id);
+}
+/** Materialize one `_00_pending_mutations` row into an UpEvent. */
+function rowToUpEvent(r, logger) {
+	switch (r.mutationType) {
+		case "create": return {
+			type: "create",
+			mutation_id: parseRecordIdString(r.id),
+			record_id: parseRecordIdString(r.recordId),
+			data: r.data,
+			tableName: extractTablePart(r.recordId)
+		};
+		case "update": return {
+			type: "update",
+			mutation_id: parseRecordIdString(r.id),
+			record_id: parseRecordIdString(r.recordId),
+			data: r.data,
+			beforeRecord: r.beforeRecord
+		};
+		case "delete": return {
+			type: "delete",
+			mutation_id: parseRecordIdString(r.id),
+			record_id: parseRecordIdString(r.recordId)
+		};
+		default:
+			logger.warn({
+				mutationType: r.mutationType,
+				record: r,
+				Category: "sp00ky-client::UpQueue::rowToUpEvent"
+			}, "Unknown mutation type");
+			return null;
+	}
+}
 
 //#endregion
 //#region src/modules/sync/queue/queue-down.ts
@@ -4047,8 +4461,8 @@ var SyncScheduler = class {
 		this.onRollback = onRollback;
 		this.onSyncOutcome = onSyncOutcome;
 	}
-	async init() {
-		await this.upQueue.loadFromDatabase();
+	async init(opts = {}) {
+		if (opts.loadOutbox !== false) await this.upQueue.loadFromDatabase();
 		this.upQueue.events.subscribe(SyncQueueEventTypes.MutationEnqueued, this.syncUp.bind(this));
 		this.downQueue.events.subscribe(SyncQueueEventTypes.QueryItemEnqueued, this.syncDown.bind(this));
 	}
@@ -4166,6 +4580,10 @@ var Sp00kySync = class Sp00kySync {
 	wasDisconnected = false;
 	events = createSyncEventSystem();
 	currentUserId = null;
+	tabRole = "solo";
+	tabId = null;
+	hub = null;
+	forwarder = null;
 	refMode = DEFAULT_REF_MODE;
 	anonLiveEnabled;
 	currentLiveQueryUuid = null;
@@ -4338,7 +4756,7 @@ var Sp00kySync = class Sp00kySync {
 	async init() {
 		if (this.isInit) throw new Error("Sp00kySync is already initialized");
 		this.isInit = true;
-		await this.scheduler.init();
+		await this.scheduler.init({ loadOutbox: this.tabRole !== "follower" });
 		this.subscribeToReconnect();
 		this.scheduler.syncUp();
 		this.scheduler.syncDown();
@@ -4352,6 +4770,93 @@ var Sp00kySync = class Sp00kySync {
 			});
 		}
 	}
+	/** Set BEFORE init(): shapes what init boots (a follower loads no outbox and
+	*  never starts LIVE; its own registration/poll paths stay untouched). */
+	setTabContext(role, tabId) {
+		this.tabRole = role;
+		this.tabId = tabId;
+	}
+	/** Leader duties: drain the shared outbox, own the single list_ref LIVE,
+	*  relay LIVE events and rollbacks to followers via `hub`. Idempotent for a
+	*  boot-time leader; a runtime promotion (failover) reloads the outbox,
+	*  which now holds EVERY tab's rows, and restarts LIVE under this session. */
+	async promoteToLeader(hub) {
+		this.tabRole = "leader";
+		this.hub = hub;
+		this.forwarder = null;
+		hub.onFollowerMessage = (tabId, msg) => {
+			switch (msg.type) {
+				case "sync-hello": break;
+				case "mutation-enqueued":
+					this.enqueueForwardedMutation(msg.mutationId);
+					break;
+				case "request-poll":
+					this.listRefIdleStreak = 0;
+					break;
+			}
+		};
+		if (this.isInit) {
+			await this.upQueue.loadFromDatabase();
+			this.scheduler.syncUp();
+			if (this.currentUserId || this.anonLiveEnabled) {
+				this.startListRefPoll();
+				await this.restartRefLiveQuery().catch((err) => {
+					this.logger.warn({
+						err,
+						Category: "sp00ky-client::Sp00kySync::promoteToLeader"
+					}, "LIVE restart failed on promotion; poll fallback covers it");
+				});
+			}
+		}
+	}
+	/** Follower duties: no outbox drain, no LIVE. Mutations forward to the
+	*  leader; everything else (registration, per-query sync, poll) runs
+	*  against this tab's own remote session as usual. */
+	demoteToFollower(forwarder) {
+		this.tabRole = "follower";
+		this.hub = null;
+		this.forwarder = forwarder;
+		this.killRefLiveQuery();
+		forwarder.onLeaderMessage = (msg) => {
+			switch (msg.type) {
+				case "list-ref-change":
+					this.applyRelayedListRefChange(msg).catch((err) => {
+						this.logger.error({
+							err,
+							Category: "sp00ky-client::Sp00kySync::relay"
+						}, "Relayed list_ref change failed");
+					});
+					break;
+				case "mutation-rolled-back":
+					this.events.emit(SyncEventTypes.MutationRolledBack, {
+						eventType: msg.eventType,
+						recordId: msg.recordId,
+						error: msg.error
+					});
+					break;
+				default: break;
+			}
+		};
+	}
+	/** A forwarded outbox row from a follower: load + drain it. Idempotent. */
+	async enqueueForwardedMutation(mutationId) {
+		if (this.tabRole !== "leader") return;
+		await this.upQueue.enqueueFromDatabase(mutationId);
+	}
+	/** A relayed `_00_list_ref` LIVE event: resolve against THIS tab's queries
+	*  and run the exact same handling the LIVE subscription would have. */
+	async applyRelayedListRefChange(msg) {
+		const queryId = parseRecordIdString(msg.queryId);
+		if (!this.dataModule.getQueryById(queryId)) return;
+		const recordId = parseRecordIdString(msg.recordId);
+		if (msg.parent) await this.handleRemoteSubqueryChange(msg.action, queryId, recordId, msg.version);
+		else await this.handleRemoteListRefChange(msg.action, queryId, recordId, msg.version);
+	}
+	/** One immediate poll cycle (failover convergence). */
+	async forcePollRound() {
+		this.listRefIdleStreak = 0;
+		await this.pollListRefForActiveQueries().catch(() => false);
+	}
 	/**
 	* Quiesce all sync activity ahead of a local-bucket switch. After this
 	* resolves, nothing in the sync module writes to the local store: the poll
@@ -4632,6 +5137,7 @@ var Sp00kySync = class Sp00kySync {
 		});
 	}
 	async startRefLiveQueries() {
+		if (this.tabRole === "follower") return;
 		const tableName = this.listRefTable();
 		this.logger.debug({
 			tableName,
@@ -4665,9 +5171,17 @@ var Sp00kySync = class Sp00kySync {
 	async handleRemoteListRefChange(action, queryId, recordId, version) {
 		this.lastLiveEventAt = Date.now();
 		this.listRefIdleStreak = 0;
+		this.hub?.broadcast({
+			type: "list-ref-change",
+			action,
+			queryId: encodeRecordId(queryId),
+			recordId: encodeRecordId(recordId),
+			version,
+			parent: false
+		});
 		const existing = this.dataModule.getQueryById(queryId);
 		if (!existing) {
-			this.logger.warn({
+			if (!this.hub) this.logger.warn({
 				queryId: queryId.toString(),
 				Category: "sp00ky-client::Sp00kySync::handleRemoteListRefChange"
 			}, "Received remote update for unknown local query");
@@ -4702,6 +5216,14 @@ var Sp00kySync = class Sp00kySync {
 		this.lastLiveEventAt = Date.now();
 		this.listRefIdleStreak = 0;
 		if (action === "DELETE") return;
+		this.hub?.broadcast({
+			type: "list-ref-change",
+			action,
+			queryId: encodeRecordId(queryId),
+			recordId: encodeRecordId(childId),
+			version,
+			parent: true
+		});
 		const existing = this.dataModule.getQueryById(queryId);
 		if (!existing) return;
 		const item = {
@@ -4797,6 +5319,15 @@ var Sp00kySync = class Sp00kySync {
 			recordId,
 			error: error.message
 		});
+		const mutationId = encodeRecordId(event.mutation_id);
+		const owner = mutationOwnerTabId(mutationId);
+		if (this.hub && owner && this.tabId && owner !== this.tabId) this.hub.sendTo(owner, {
+			type: "mutation-rolled-back",
+			mutationId,
+			recordId,
+			eventType: event.type,
+			error: error.message
+		});
 	}
 	async processDownEvent(event) {
 		this.logger.debug({
@@ -4907,6 +5438,10 @@ var Sp00kySync = class Sp00kySync {
 	* @param mutations Array of UpEvents (create/update/delete) to enqueue.
 	*/
 	async enqueueMutation(mutations) {
+		if (this.tabRole === "follower") {
+			for (const m of mutations) this.forwarder?.mutationEnqueued(encodeRecordId(m.mutation_id));
+			return;
+		}
 		this.scheduler.enqueueMutation(mutations);
 	}
 	async registerQuery(queryHash) {
@@ -5088,10 +5623,79 @@ function parseBackendInfo(raw) {
 	};
 }
 
+//#endregion
+//#region src/modules/devtools/storage-info.ts
+/**
+* Recursively list the origin's OPFS. Sizes come from `handle.getFile()`,
+* which throws for a file another context holds an exclusive sync access
+* handle on — SAHPool does exactly that for its whole pool, so a locked file
+* (size omitted) is a live "who has the pool" signal, not a failure.
+*/
+async function walkOpfs(maxEntries = 2e3, maxDepth = 8) {
+	const nav = typeof navigator !== "undefined" ? navigator : void 0;
+	if (!nav?.storage?.getDirectory) return {
+		supported: false,
+		entries: [],
+		totalBytes: 0,
+		truncated: false
+	};
+	const entries = [];
+	let totalBytes = 0;
+	let truncated = false;
+	try {
+		const root = await nav.storage.getDirectory();
+		const walk = async (dir, prefix, depth) => {
+			if (depth > maxDepth) return;
+			for await (const [name, handle] of dir.entries()) {
+				if (entries.length >= maxEntries) {
+					truncated = true;
+					return;
+				}
+				const path = prefix ? `${prefix}/${name}` : name;
+				if (handle.kind === "directory") {
+					entries.push({
+						path,
+						kind: "directory"
+					});
+					await walk(handle, path, depth + 1);
+				} else {
+					let size;
+					try {
+						size = (await handle.getFile()).size;
+						totalBytes += size;
+					} catch {}
+					const entry = {
+						path,
+						kind: "file"
+					};
+					if (size !== void 0) entry.size = size;
+					entries.push(entry);
+				}
+			}
+		};
+		await walk(root, "", 0);
+		entries.sort((a, b) => a.path.localeCompare(b.path));
+		return {
+			supported: true,
+			entries,
+			totalBytes,
+			truncated
+		};
+	} catch (e) {
+		return {
+			supported: true,
+			entries,
+			totalBytes,
+			truncated,
+			error: e instanceof Error ? e.message : String(e)
+		};
+	}
+}
+
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.153";
-const WASM_VERSION = "0.0.1-canary.153";
+const CORE_VERSION = "0.0.1-canary.155";
+const WASM_VERSION = "0.0.1-canary.155";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class {
 	eventsHistory = [];
@@ -5099,6 +5703,11 @@ var DevToolsService = class {
 	version = CORE_VERSION;
 	backendInfo = emptyBackendInfo();
 	enabled = false;
+	/** Shared-tabs snapshot for the panel, wired by Sp00kyClient when active. */
+	tabsInfoProvider = null;
+	setTabsInfoProvider(provider) {
+		this.tabsInfoProvider = provider;
+	}
 	localTables = [];
 	localTablesFetching = false;
 	localTablesAt = 0;
@@ -5292,10 +5901,74 @@ var DevToolsService = class {
 				storage: this.databaseService.storageHealth ?? {
 					status: "unknown",
 					fallback: false
-				}
+				},
+				tabs: this.tabsInfoProvider?.() ?? null
 			}
 		});
 	}
+	/**
+	* Full storage diagnostics for the DevTools Storage tab. Every section is
+	* gathered independently and failures land in that section's `error` field,
+	* so one broken source (a mid-switch worker, a browser without OPFS) never
+	* blanks the whole panel.
+	*/
+	async getStorageInfo(opts) {
+		const nav = typeof navigator !== "undefined" ? navigator : void 0;
+		const info = {
+			at: Date.now(),
+			engine: {
+				kind: this.databaseService.engineKind ?? "custom",
+				store: this.databaseService.getConfig()?.store ?? "memory",
+				bucketId: this.databaseService.currentBucketId
+			},
+			health: this.databaseService.storageHealth ?? {
+				status: "unknown",
+				fallback: false
+			},
+			browser: {},
+			opfs: {
+				supported: false,
+				entries: [],
+				totalBytes: 0,
+				truncated: false
+			}
+		};
+		try {
+			if (nav?.storage?.estimate) {
+				const est = await nav.storage.estimate();
+				info.browser.usage = est.usage;
+				info.browser.quota = est.quota;
+				const details = est.usageDetails;
+				if (details && typeof details === "object") info.browser.usageDetails = details;
+			}
+			if (nav?.storage?.persisted) info.browser.persisted = await nav.storage.persisted();
+		} catch (e) {
+			info.browser.error = e instanceof Error ? e.message : String(e);
+		}
+		info.opfs = await walkOpfs();
+		const stats = globalThis.__sqliteStats;
+		if (stats && typeof stats === "object") info.sqliteStats = {
+			...stats,
+			byType: { ...stats.byType ?? {} }
+		};
+		try {
+			info.engineDiagnostics = await this.databaseService.getStorageDiagnostics?.(opts);
+		} catch (e) {
+			this.logger.warn({
+				err: e,
+				Category: "sp00ky-client::DevToolsService::getStorageInfo"
+			}, "Engine storage diagnostics failed");
+		}
+		return this.serializeForDevTools(info);
+	}
+	/** Ask the browser to exempt this origin's storage from eviction. */
+	async requestPersistentStorage() {
+		try {
+			return { granted: await navigator.storage?.persist?.() ?? false };
+		} catch {
+			return { granted: false };
+		}
+	}
 	notifyDevTools() {
 		if (!this.enabled) return;
 		if (typeof window !== "undefined") window.postMessage({
@@ -5319,7 +5992,10 @@ var DevToolsService = class {
 			if (seen.has(data)) return "[Circular Object]";
 			seen.add(data);
 			const result = {};
-			for (const key in data) if (Object.prototype.hasOwnProperty.call(data, key)) result[key] = this.serializeForDevTools(data[key], seen);
+			for (const key in data) if (Object.prototype.hasOwnProperty.call(data, key)) {
+				if (data[key] === void 0) continue;
+				result[key] = this.serializeForDevTools(data[key], seen);
+			}
 			return result;
 		}
 		return data;
@@ -5334,6 +6010,8 @@ var DevToolsService = class {
 					this.notifyDevTools();
 				},
 				refreshVersions: () => this.refreshBackendVersions(),
+				getStorageInfo: (opts) => this.getStorageInfo(opts),
+				requestPersistentStorage: () => this.requestPersistentStorage(),
 				getTableData: async (tableName) => {
 					try {
 						const result = await this.databaseService.query(`SELECT * FROM ${tableName}`);
@@ -5631,6 +6309,7 @@ var StreamProcessorService = class {
 	};
 	stateKeySuffix = "";
 	stateGeneration = 0;
+	persistState = true;
 	constructor(events, db, persistenceClient, logger) {
 		this.events = events;
 		this.db = db;
@@ -5758,8 +6437,12 @@ var StreamProcessorService = class {
 		this.processor = new Sp00kyProcessor();
 		this.logger.info({ Category: "sp00ky-client::StreamProcessorService::reset" }, "Stream processor reset (fresh circuit)");
 	}
+	/** Toggle circuit-state persistence (shared-tabs follower/leader role). */
+	setPersistenceEnabled(enabled) {
+		this.persistState = enabled;
+	}
 	async loadState() {
-		if (!this.processor) return;
+		if (!this.processor || !this.persistState) return;
 		try {
 			const result = await this.persistenceClient.get(this.stateKey());
 			if (Array.isArray(result) && result.length > 0 && Array.isArray(result[0]) && result[0].length > 0 && result[0][0]?.state) {
@@ -5817,7 +6500,7 @@ var StreamProcessorService = class {
 		}, "Session auth context updated");
 	}
 	async saveState() {
-		if (!this.processor) return;
+		if (!this.processor || !this.persistState) return;
 		const generation = this.stateGeneration;
 		try {
 			if (typeof this.processor.save_state === "function") {
@@ -6035,16 +6718,14 @@ function selectPredicateFromBody(body) {
 
 //#endregion
 //#region src/modules/cache/index.ts
-/**
-* CacheModule - Centralized storage and DBSP ingestion
-*
-* Single responsibility: Handle all local storage operations and DBSP ingestion.
-* This module acts as the bridge between data operations and persistence.
-*/
 var CacheModule = class {
 	logger;
 	streamUpdateCallback;
 	versionLookups = {};
+	/** Shared-tabs leader: fan every committed ingest out to follower circuits.
+	*  Fired AFTER the local tx (the rows are already in the shared store, so a
+	*  follower only needs the circuit feed). Never set on followers. */
+	ingestRelay = null;
 	constructor(local, streamProcessor, streamUpdateCallback, logger) {
 		this.local = local;
 		this.streamProcessor = streamProcessor;
@@ -6064,6 +6745,24 @@ var CacheModule = class {
 		}, "Stream update received");
 		this.streamUpdateCallback(update);
 	}
+	setIngestRelay(cb) {
+		this.ingestRelay = cb;
+	}
+	/**
+	* Shared-tabs follower: feed relayed tuples into THIS tab's circuit only.
+	* The rows are already in the shared store (the leader wrote them), so no
+	* local write happens here; the normal chain then runs: SSP -> stream update
+	* -> DataModule debounce -> materializeRecords (re-reads via the port
+	* transport) -> this tab's subscriptions fire with this tab's hashes.
+	*/
+	applyRelayedIngest(tuples) {
+		for (const t of tuples) {
+			const rv = t.record?._00_rv;
+			if (t.op === "DELETE") delete this.versionLookups[t.id];
+			else if (typeof rv === "number") this.versionLookups[t.id] = rv;
+		}
+		this.streamProcessor.ingestMany(tuples);
+	}
 	lookup(recordId) {
 		return this.versionLookups[recordId] ?? 0;
 	}
@@ -6128,6 +6827,7 @@ var CacheModule = class {
 				};
 			});
 			this.streamProcessor.ingestMany(bulk);
+			this.ingestRelay?.(bulk);
 			this.logger.debug({
 				count: records.length,
 				Category: "sp00ky-client::CacheModule::saveBatch"
@@ -6163,6 +6863,12 @@ var CacheModule = class {
 			if (this.local.epoch !== epoch) throw new StaleEpochError();
 			delete this.versionLookups[id];
 			this.streamProcessor.ingest(table, "DELETE", id, recordData);
+			this.ingestRelay?.([{
+				table,
+				op: "DELETE",
+				id,
+				record: recordData
+			}]);
 			this.logger.debug({
 				table,
 				id,
@@ -7156,6 +7862,747 @@ var ResilientPersistenceClient = class {
 	}
 };
 
+//#endregion
+//#region src/services/tabs/support.ts
+function detectSharedTabsSupport(config) {
+	if (config.sharedTabs !== true) return {
+		supported: false,
+		reason: "flag-off"
+	};
+	if (config.localEngine !== "sqlite") return {
+		supported: false,
+		reason: "engine-not-sqlite"
+	};
+	if (typeof window === "undefined") return {
+		supported: false,
+		reason: "not-browser"
+	};
+	if (typeof SharedWorker === "undefined") return {
+		supported: false,
+		reason: "no-shared-worker"
+	};
+	if (typeof MessageChannel === "undefined") return {
+		supported: false,
+		reason: "no-message-channel"
+	};
+	const locks = navigator.locks;
+	if (!locks || typeof locks.request !== "function") return {
+		supported: false,
+		reason: "no-web-locks"
+	};
+	return { supported: true };
+}
+
+//#endregion
+//#region src/services/tabs/protocol.ts
+const TABS_PROTOCOL_VERSION = 1;
+/** Broker pings every tab at this cadence. */
+const PING_INTERVAL_MS = 5e3;
+/** A tab that has not ponged for this long is presumed dead and evicted.
+*  MUST stay above the sqlite worker's freeze-suspect threshold (10s): a
+*  freeze shorter than that never triggers a steal, which is what makes the
+*  worker-side thaw gate sufficient. */
+const PONG_TIMEOUT_MS = 15e3;
+/** Deterministic JSON: objects with sorted keys, so equal inputs always
+*  produce equal fingerprints regardless of construction order. */
+function stableStringify(value) {
+	if (value === null || typeof value !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(",")}}`;
+}
+/** cyrb53: tiny, fast, good-enough 53-bit hash for identity strings. */
+function hash53(str, seed = 0) {
+	let h1 = 3735928559 ^ seed;
+	let h2 = 1103547991 ^ seed;
+	for (let i = 0; i < str.length; i++) {
+		const ch = str.charCodeAt(i);
+		h1 = Math.imul(h1 ^ ch, 2654435761);
+		h2 = Math.imul(h2 ^ ch, 1597334677);
+	}
+	h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507) ^ Math.imul(h2 ^ h2 >>> 13, 3266489909);
+	h2 = Math.imul(h2 ^ h2 >>> 16, 2246822507) ^ Math.imul(h1 ^ h1 >>> 13, 3266489909);
+	return (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(36);
+}
+function computeTabsFingerprint(input) {
+	return hash53(stableStringify({
+		v: TABS_PROTOCOL_VERSION,
+		...input
+	}));
+}
+/** Lock names. The worker lock embeds the leadershipId, so after a steal the
+*  exact name is never re-acquired by anyone: "not held" is an unambiguous
+*  fencing check for a thawed worker, with no clientId resolution needed. */
+function tabLockName(fingerprint, bucketId) {
+	return `sp00ky-tabs:${fingerprint}:${bucketId}:tab`;
+}
+function workerLockName(fingerprint, bucketId, leadershipId) {
+	return `sp00ky-tabs:${fingerprint}:${bucketId}:worker:${leadershipId}`;
+}
+
+//#endregion
+//#region src/services/tabs/broker-client.ts
+var TabBrokerClient = class {
+	worker = null;
+	brokerInstanceId = null;
+	watchdog = null;
+	lastPingAt = 0;
+	closed = false;
+	helloState = null;
+	constructor(workerUrl, tabId, events, logger) {
+		this.workerUrl = workerUrl;
+		this.tabId = tabId;
+		this.events = events;
+		this.logger = logger;
+	}
+	/** Connect and hello. Resolves once broker-hello arrives (or rejects on
+	*  timeout / SharedWorker error, in which case the caller goes solo). */
+	connect(hello) {
+		this.helloState = hello;
+		this.installLifecycleListeners();
+		return this.openWorker();
+	}
+	openWorker() {
+		if (this.closed || !this.helloState) return Promise.reject(/* @__PURE__ */ new Error("broker client closed"));
+		return new Promise((resolve, reject) => {
+			let settled = false;
+			const settle = (fn) => {
+				if (!settled) {
+					settled = true;
+					fn();
+				}
+			};
+			let worker;
+			try {
+				worker = new SharedWorker(this.workerUrl, {
+					type: "module",
+					name: "sp00ky-tabs-broker"
+				});
+			} catch (e) {
+				reject(e);
+				return;
+			}
+			this.worker = worker;
+			const timeout = setTimeout(() => settle(() => reject(/* @__PURE__ */ new Error("broker hello timeout"))), 5e3);
+			worker.onerror = () => {
+				clearTimeout(timeout);
+				settle(() => reject(/* @__PURE__ */ new Error("SharedWorker failed to start")));
+			};
+			worker.port.onmessage = (ev) => {
+				const msg = ev.data;
+				if (!msg || typeof msg !== "object") return;
+				if (msg.type === "broker-hello") {
+					clearTimeout(timeout);
+					this.noteInstance(msg.brokerInstanceId);
+					this.lastPingAt = Date.now();
+					this.startWatchdog();
+					settle(resolve);
+					return;
+				}
+				this.handleMessage(msg, ev.ports ?? []);
+			};
+			worker.port.onmessageerror = () => this.reconnect("messageerror");
+			worker.port.start?.();
+			this.send({
+				type: "hello",
+				tabId: this.tabId,
+				fingerprint: this.helloState.fingerprint,
+				bucketId: this.helloState.bucketId,
+				visibility: currentVisibility(),
+				heldLeadership: this.helloState.heldLeadership()
+			});
+		});
+	}
+	noteInstance(id) {
+		if (this.brokerInstanceId !== null && this.brokerInstanceId !== id) this.events.onBrokerRestarted();
+		this.brokerInstanceId = id;
+	}
+	handleMessage(msg, ports) {
+		if ("brokerInstanceId" in msg) this.noteInstance(msg.brokerInstanceId);
+		switch (msg.type) {
+			case "ping":
+				this.lastPingAt = Date.now();
+				this.send({
+					type: "pong",
+					tabId: this.tabId
+				});
+				break;
+			case "become-leader":
+				this.events.onBecomeLeader({
+					leadershipId: msg.leadershipId,
+					forceTakeover: msg.forceTakeover,
+					allowMemoryFallback: msg.allowMemoryFallback,
+					resumeHeld: msg.resumeHeld
+				});
+				break;
+			case "demote":
+				this.events.onDemote(msg.leadershipId);
+				break;
+			case "leader-ready":
+				this.events.onLeaderReady(msg.leadershipId, msg.leaderTabId);
+				break;
+			case "attach-follower-ports":
+				if (ports.length >= 2) this.events.onAttachFollowerPorts(msg.followerTabId, msg.leadershipId, ports[0], ports[1]);
+				break;
+			case "use-follower-ports":
+				if (ports.length >= 2) this.events.onUseFollowerPorts(msg.leaderTabId, msg.leadershipId, ports[0], ports[1]);
+				break;
+			case "close-follower-ports":
+				this.events.onCloseFollowerPorts(msg.leadershipId);
+				break;
+			case "unsupported":
+				this.logger.warn({
+					reason: msg.reason,
+					Category: "sp00ky-client::BrokerClient"
+				}, "Broker rejected this tab; running solo");
+				this.events.onUnsupported(msg.reason);
+				this.close();
+				break;
+		}
+	}
+	send(msg) {
+		try {
+			this.worker?.port.postMessage(msg);
+		} catch {}
+	}
+	/** The tab moved to a different bucket: re-hello under the new namespace.
+	*  The broker treats a re-hello of a known tabId as leave + rejoin. */
+	rehello(hello) {
+		this.helloState = hello;
+		if (!this.worker) return this.openWorker();
+		this.send({
+			type: "hello",
+			tabId: this.tabId,
+			fingerprint: hello.fingerprint,
+			bucketId: hello.bucketId,
+			visibility: currentVisibility(),
+			heldLeadership: hello.heldLeadership()
+		});
+		return Promise.resolve();
+	}
+	startWatchdog() {
+		if (this.watchdog) return;
+		this.watchdog = setInterval(() => {
+			if (Date.now() - this.lastPingAt > PING_INTERVAL_MS + PONG_TIMEOUT_MS) this.reconnect("broker pings stopped");
+		}, PING_INTERVAL_MS);
+	}
+	reconnect(reason) {
+		if (this.closed) return;
+		this.logger.info({
+			reason,
+			Category: "sp00ky-client::BrokerClient"
+		}, "Reconnecting to the tabs broker");
+		try {
+			this.worker?.port.close();
+		} catch {}
+		this.worker = null;
+		this.brokerInstanceId = null;
+		this.events.onBrokerRestarted();
+		this.openWorker().catch((e) => {
+			this.logger.warn({
+				err: e,
+				Category: "sp00ky-client::BrokerClient"
+			}, "Broker reconnect failed; staying detached until the next watchdog tick");
+		});
+	}
+	installLifecycleListeners() {
+		if (typeof window === "undefined" || typeof document === "undefined") return;
+		document.addEventListener("visibilitychange", () => {
+			if (!this.helloState) return;
+			this.send({
+				type: "visibility",
+				tabId: this.tabId,
+				bucketId: this.helloState.bucketId,
+				visibility: currentVisibility()
+			});
+		});
+		const leave = () => {
+			if (this.helloState) this.send({
+				type: "shutdown",
+				tabId: this.tabId,
+				bucketId: this.helloState.bucketId
+			});
+		};
+		window.addEventListener("pagehide", leave);
+		document.addEventListener("freeze", leave);
+		window.addEventListener("pageshow", (e) => {
+			if (e.persisted && this.helloState) this.rehello(this.helloState);
+		});
+		document.addEventListener("resume", () => {
+			if (this.helloState) this.rehello(this.helloState);
+		});
+	}
+	close() {
+		this.closed = true;
+		if (this.watchdog) clearInterval(this.watchdog);
+		this.watchdog = null;
+		try {
+			this.worker?.port.close();
+		} catch {}
+		this.worker = null;
+	}
+};
+function currentVisibility() {
+	if (typeof document === "undefined") return "visible";
+	return document.visibilityState === "hidden" ? "hidden" : "visible";
+}
+
+//#endregion
+//#region src/services/tabs/leader-locks.ts
+function lockManager() {
+	const nav = globalThis.navigator;
+	return nav?.locks && typeof nav.locks.request === "function" ? nav.locks : null;
+}
+/**
+* Acquire `name` exclusively. `steal: true` when the broker determined the
+* previous holder is a frozen zombie. Resolves null when the lock is held by
+* someone else and stealing was not requested.
+*/
+function acquireLeaderTabLock(name, opts) {
+	const locks = lockManager();
+	if (!locks) return Promise.resolve({
+		release() {},
+		onLost() {}
+	});
+	return new Promise((resolve) => {
+		let lostCb = null;
+		let releasedIntentionally = false;
+		let granted = false;
+		let release = null;
+		locks.request(name, opts.steal ? {
+			mode: "exclusive",
+			steal: true
+		} : {
+			mode: "exclusive",
+			ifAvailable: true
+		}, (lock) => {
+			if (!lock) {
+				resolve(null);
+				return;
+			}
+			granted = true;
+			resolve({
+				release() {
+					releasedIntentionally = true;
+					release?.();
+				},
+				onLost(cb) {
+					lostCb = cb;
+				}
+			});
+			return new Promise((r) => {
+				release = r;
+			});
+		}).then(() => {
+			if (granted && !releasedIntentionally) lostCb?.();
+		}, () => {
+			if (granted && !releasedIntentionally) lostCb?.();
+			else if (!granted) resolve(null);
+		});
+	});
+}
+
+//#endregion
+//#region src/services/tabs/coordinator.ts
+/** How long boot waits for a role (election + attach) before going solo. */
+const START_TIMEOUT_MS = 15e3;
+/** Leader-side fan-out surface handed to the sync layer. The sync router
+*  (modules/sync/tab-router.ts) registers itself as the message handler. */
+var LeaderSyncHub = class {
+	followers = /* @__PURE__ */ new Map();
+	seq = 0;
+	onFollowerMessage = null;
+	onFollowerDetached = null;
+	constructor(leadershipId, logger) {
+		this.leadershipId = leadershipId;
+		this.logger = logger;
+	}
+	attach(tabId, port) {
+		this.detach(tabId);
+		this.followers.set(tabId, port);
+		port.onmessage = (ev) => {
+			this.onFollowerMessage?.(tabId, ev.data);
+		};
+		port.onmessageerror = () => this.detach(tabId);
+		port.start?.();
+	}
+	detach(tabId) {
+		const port = this.followers.get(tabId);
+		if (!port) return;
+		this.followers.delete(tabId);
+		try {
+			port.close();
+		} catch {}
+		this.onFollowerDetached?.(tabId);
+	}
+	detachAll() {
+		for (const tabId of [...this.followers.keys()]) this.detach(tabId);
+	}
+	sendTo(tabId, msg) {
+		try {
+			this.followers.get(tabId)?.postMessage(msg);
+		} catch {}
+	}
+	broadcast(msg, exceptTabId) {
+		for (const [tabId, port] of this.followers) {
+			if (tabId === exceptTabId) continue;
+			try {
+				port.postMessage(msg);
+			} catch {}
+		}
+	}
+	/** Stamped ingest relay; seq lets followers detect gaps. */
+	relayIngest(tuples, exceptTabId) {
+		if (this.followers.size === 0) return;
+		this.broadcast({
+			type: "ingest-relay",
+			tuples,
+			leadershipId: this.leadershipId,
+			seq: ++this.seq
+		}, exceptTabId);
+	}
+	get followerCount() {
+		return this.followers.size;
+	}
+	get relayedBatches() {
+		return this.seq;
+	}
+};
+/** Follower half of the syncPort. Queues while detached (leaderless window)
+*  and flushes on rebind; a lost-in-flight mutation notify is additionally
+*  backstopped by the new leader reloading the shared outbox from the store. */
+var SyncForwarder = class {
+	port = null;
+	queued = [];
+	onLeaderMessage = null;
+	constructor(tabId) {
+		this.tabId = tabId;
+	}
+	rebind(port) {
+		this.unbind();
+		this.port = port;
+		port.onmessage = (ev) => {
+			this.onLeaderMessage?.(ev.data);
+		};
+		port.start?.();
+		this.post({
+			type: "sync-hello",
+			tabId: this.tabId
+		});
+		const backlog = this.queued;
+		this.queued = [];
+		for (const msg of backlog) this.post(msg);
+	}
+	unbind() {
+		if (this.port) try {
+			this.port.close();
+		} catch {}
+		this.port = null;
+	}
+	post(msg) {
+		if (!this.port) {
+			this.queued.push(msg);
+			return;
+		}
+		try {
+			this.port.postMessage(msg);
+		} catch {
+			this.queued.push(msg);
+		}
+	}
+	mutationEnqueued(mutationId) {
+		this.post({
+			type: "mutation-enqueued",
+			mutationId
+		});
+	}
+	requestPoll() {
+		this.post({ type: "request-poll" });
+	}
+};
+var TabsCoordinator = class {
+	role = "solo";
+	leadershipId = 0;
+	leaderTabId = null;
+	brokerRole = "pending";
+	fingerprint;
+	bucketId;
+	broker;
+	hub = null;
+	forwarder = null;
+	roleListeners = /* @__PURE__ */ new Set();
+	startResolve = null;
+	startReject = null;
+	/** Ports received before start() resolves or between roles. */
+	promotionChain = Promise.resolve();
+	closed = false;
+	constructor(deps) {
+		this.deps = deps;
+		this.fingerprint = deps.fingerprint;
+		this.bucketId = "anon";
+		this.broker = new TabBrokerClient(new URL("./tabs-broker-worker.js", import.meta.url), deps.tabId, {
+			onBecomeLeader: (msg) => this.enqueue(() => this.promote(msg)),
+			onDemote: (leadershipId) => this.enqueue(() => this.demote(leadershipId)),
+			onLeaderReady: (leadershipId, leaderTabId) => {
+				this.leaderTabId = leaderTabId;
+			},
+			onAttachFollowerPorts: (followerTabId, leadershipId, dbPort, syncPort) => this.enqueue(() => this.serveFollower(followerTabId, leadershipId, dbPort, syncPort)),
+			onUseFollowerPorts: (leaderTabId, leadershipId, dbPort, syncPort) => this.enqueue(() => this.attachToLeader(leaderTabId, leadershipId, dbPort, syncPort)),
+			onCloseFollowerPorts: (leadershipId) => this.enqueue(() => this.handleLeaderGone(leadershipId)),
+			onUnsupported: () => this.fallbackToSolo("broker rejected this tab"),
+			onBrokerRestarted: () => {}
+		}, deps.logger);
+		if (typeof window !== "undefined" && deps.onLeaderPageHide) window.addEventListener("pagehide", () => {
+			if (this.role === "leader") deps.onLeaderPageHide?.();
+		});
+	}
+	/** Serialize role transitions; each is small but async (worker opens). */
+	enqueue(fn) {
+		this.promotionChain = this.promotionChain.then(fn, fn).catch((e) => {
+			this.deps.logger.error({
+				err: e,
+				Category: "sp00ky-client::TabsCoordinator"
+			}, "Role transition failed");
+		});
+	}
+	onRoleChange(cb) {
+		this.roleListeners.add(cb);
+		return () => this.roleListeners.delete(cb);
+	}
+	setRole(role) {
+		if (this.role !== role) {
+			this.role = role;
+			this.deps.logger.info({
+				role,
+				leadershipId: this.leadershipId,
+				Category: "sp00ky-client::TabsCoordinator"
+			}, "Tab role changed");
+			for (const cb of this.roleListeners) cb(role);
+		}
+		if (this.startResolve && role !== "solo") {
+			this.startResolve(role);
+			this.startResolve = null;
+		}
+	}
+	/** Connect the broker and resolve once this tab has a usable store role.
+	*  Rejects when no role lands in time; the caller then boots solo. */
+	start(bucketId) {
+		this.bucketId = bucketId;
+		return new Promise((resolve, reject) => {
+			const timeout = setTimeout(() => {
+				this.startResolve = null;
+				this.startReject = null;
+				reject(/* @__PURE__ */ new Error("shared-tabs: no role assigned in time"));
+			}, START_TIMEOUT_MS);
+			this.startResolve = (role) => {
+				clearTimeout(timeout);
+				this.startReject = null;
+				resolve(role);
+			};
+			this.startReject = (e) => {
+				clearTimeout(timeout);
+				this.startResolve = null;
+				reject(e);
+			};
+			this.broker.connect({
+				fingerprint: this.fingerprint,
+				bucketId,
+				heldLeadership: () => this.role === "leader" ? {
+					leadershipId: this.leadershipId,
+					workerLockName: workerLockName(this.fingerprint, this.bucketId, this.leadershipId)
+				} : null
+			}).catch((e) => {
+				this.startReject?.(e instanceof Error ? e : new Error(String(e)));
+			});
+		});
+	}
+	/** Bucket switch: leave the old namespace, join the new one. Resolves when
+	*  a role lands in the new namespace. */
+	moveToBucket(bucketId) {
+		return new Promise((resolve, reject) => {
+			this.enqueue(async () => {
+				if (this.role === "leader") await this.teardownLeader();
+				else if (this.role === "follower") this.teardownFollower("bucket switch");
+				this.bucketId = bucketId;
+				const timeout = setTimeout(() => {
+					this.startResolve = null;
+					this.startReject = null;
+					reject(/* @__PURE__ */ new Error("shared-tabs: no role assigned after bucket switch"));
+				}, START_TIMEOUT_MS);
+				this.startResolve = (role) => {
+					clearTimeout(timeout);
+					this.startReject = null;
+					resolve(role);
+				};
+				this.startReject = (e) => {
+					clearTimeout(timeout);
+					this.startResolve = null;
+					reject(e);
+				};
+				await this.broker.rehello({
+					fingerprint: this.fingerprint,
+					bucketId,
+					heldLeadership: () => null
+				});
+			});
+		});
+	}
+	async promote(msg) {
+		if (this.closed) return;
+		if (msg.leadershipId <= this.leadershipId && !msg.resumeHeld) return;
+		const previousRole = this.role;
+		try {
+			if (previousRole === "follower") this.teardownFollower("promoted");
+			this.leadershipId = msg.leadershipId;
+			const lock = await acquireLeaderTabLock(tabLockName(this.fingerprint, this.bucketId), { steal: msg.forceTakeover });
+			if (!lock) throw new Error("leader tab lock unavailable");
+			this.tabLock?.release();
+			this.tabLock = lock;
+			lock.onLost(() => {
+				this.enqueue(async () => {
+					if (this.leadershipId !== msg.leadershipId || this.role !== "leader") return;
+					await this.teardownLeader();
+					this.deps.hooks.onLeaderLost("tab lock stolen");
+				});
+			});
+			await this.deps.hooks.adoptOwner(this.bucketId, {
+				workerLockName: workerLockName(this.fingerprint, this.bucketId, msg.leadershipId),
+				allowMemoryFallback: msg.allowMemoryFallback,
+				forceTakeover: msg.forceTakeover,
+				resumeHeld: msg.resumeHeld
+			});
+			this.hub = new LeaderSyncHub(msg.leadershipId, this.deps.logger);
+			await this.deps.hooks.becomeSyncLeader(this.hub);
+			this.setRole("leader");
+			this.broker.send({
+				type: "leader-ready",
+				tabId: this.deps.tabId,
+				bucketId: this.bucketId,
+				leadershipId: msg.leadershipId
+			});
+		} catch (e) {
+			const reason = e instanceof Error ? e.message : String(e);
+			this.deps.logger.error({
+				err: e,
+				Category: "sp00ky-client::TabsCoordinator"
+			}, "Promotion failed");
+			this.hub?.detachAll();
+			this.hub = null;
+			this.broker.send({
+				type: "leader-failed",
+				tabId: this.deps.tabId,
+				bucketId: this.bucketId,
+				leadershipId: msg.leadershipId,
+				reason
+			});
+		}
+	}
+	async demote(leadershipId) {
+		if (this.role !== "leader" || leadershipId !== this.leadershipId) return;
+		await this.teardownLeader();
+		this.deps.hooks.onLeaderLost("demoted");
+	}
+	tabLock = null;
+	async teardownLeader() {
+		this.hub?.detachAll();
+		this.hub = null;
+		await this.deps.hooks.releaseOwnership();
+		this.tabLock?.release();
+		this.tabLock = null;
+	}
+	teardownFollower(reason) {
+		this.forwarder?.unbind();
+		this.deps.hooks.onLeaderLost(reason);
+	}
+	async serveFollower(followerTabId, leadershipId, dbPort, syncPort) {
+		if (this.role !== "leader" || leadershipId !== this.leadershipId || !this.hub) {
+			dbPort.close();
+			syncPort.close();
+			return;
+		}
+		await this.deps.hooks.exposeClientPort(followerTabId, dbPort);
+		this.hub.attach(followerTabId, syncPort);
+		this.hub.sendTo(followerTabId, {
+			type: "db-ready",
+			leadershipId,
+			bucketId: this.bucketId,
+			storageHealth: this.deps.hooks.currentStorageHealth()
+		});
+		this.broker.send({
+			type: "follower-port-attached",
+			tabId: this.deps.tabId,
+			bucketId: this.bucketId,
+			leadershipId,
+			followerTabId
+		});
+	}
+	async attachToLeader(leaderTabId, leadershipId, dbPort, syncPort) {
+		if (this.closed || this.role === "leader") {
+			dbPort.close();
+			syncPort.close();
+			return;
+		}
+		this.leaderTabId = leaderTabId;
+		this.leadershipId = leadershipId;
+		if (!this.forwarder) this.forwarder = new SyncForwarder(this.deps.tabId);
+		const forwarder = this.forwarder;
+		await new Promise((resolve) => {
+			let adopted = false;
+			const previousHandler = forwarder.onLeaderMessage;
+			forwarder.onLeaderMessage = (msg) => {
+				if (msg.type === "db-ready" && !adopted) {
+					adopted = true;
+					this.deps.hooks.adoptAttached(dbPort, {
+						bucketId: msg.bucketId,
+						storageHealth: msg.storageHealth,
+						leadershipId: msg.leadershipId
+					}).then(() => {
+						this.deps.hooks.becomeSyncFollower(forwarder);
+						this.setRole("follower");
+						resolve();
+					});
+					return;
+				}
+				previousHandler?.(msg);
+			};
+			forwarder.rebind(syncPort);
+		});
+	}
+	async handleLeaderGone(leadershipId) {
+		if (this.role === "leader") return;
+		if (leadershipId < this.leadershipId) return;
+		this.teardownFollower("leader gone");
+	}
+	fallbackToSolo(reason) {
+		this.deps.logger.warn({
+			reason,
+			Category: "sp00ky-client::TabsCoordinator"
+		}, "Shared-tabs unavailable; running solo");
+		this.deps.hooks.becomeSyncSolo();
+		this.setRole("solo");
+		this.startReject?.(/* @__PURE__ */ new Error(`shared-tabs unavailable: ${reason}`));
+	}
+	get syncHub() {
+		return this.hub;
+	}
+	get syncForwarder() {
+		return this.forwarder;
+	}
+	get tabId() {
+		return this.deps.tabId;
+	}
+	async stop() {
+		this.closed = true;
+		if (this.role === "leader") await this.teardownLeader();
+		else this.forwarder?.unbind();
+		this.broker.send({
+			type: "shutdown",
+			tabId: this.deps.tabId,
+			bucketId: this.bucketId
+		});
+		this.broker.close();
+	}
+};
+
 //#endregion
 //#region src/sp00ky.ts
 var BucketHandle = class {
@@ -7238,6 +8685,12 @@ var Sp00kyClient = class {
 	logger;
 	auth;
 	streamProcessor;
+	tabsCoordinator = null;
+	sharedActive = false;
+	/** Current shared-tabs role, or null when the feature is off/fell back. */
+	get tabRole() {
+		return this.sharedActive ? this.tabsCoordinator.role : null;
+	}
 	get remoteClient() {
 		return this.remote.getClient();
 	}
@@ -7296,7 +8749,8 @@ var Sp00kyClient = class {
 			Category: "sp00ky-client::Sp00kyClient::constructor"
 		}, "Sp00kyClient initialized");
 		if (config.crdt) preloadLoro();
-		this.local = createLocalEngine(this.config.localEngine, this.config.database, logger);
+		const tabsSupport = detectSharedTabsSupport(this.config);
+		this.local = createLocalEngine(this.config.localEngine, this.config.database, logger, { shared: tabsSupport.supported });
 		this.remote = new RemoteDatabaseService(this.config.database, logger);
 		if (config.persistenceClient === "surrealdb") this.persistenceClient = new SurrealDBPersistenceClient(this.local, logger);
 		else if (config.persistenceClient === "localstorage" || !config.persistenceClient) this.persistenceClient = new LocalStoragePersistenceClient(logger);
@@ -7330,6 +8784,86 @@ var Sp00kyClient = class {
 		this.devTools = new DevToolsService(this.local, this.remote, logger, this.config.schema, this.auth, this.dataModule);
 		this.streamProcessor.addReceiver(this.devTools);
 		this.setupCallbacks();
+		if (tabsSupport.supported) {
+			this.tabsCoordinator = this.buildTabsCoordinator();
+			this.devTools.setTabsInfoProvider(() => {
+				if (!this.sharedActive || !this.tabsCoordinator) return null;
+				const c = this.tabsCoordinator;
+				return {
+					role: c.role,
+					tabId: c.tabId,
+					leadershipId: c.leadershipId,
+					leaderTabId: c.leaderTabId,
+					followers: c.syncHub?.followerCount ?? null,
+					relayedBatches: c.syncHub?.relayedBatches ?? null
+				};
+			});
+		} else if (this.config.sharedTabs) this.logger.info({
+			reason: tabsSupport.reason,
+			Category: "sp00ky-client::Sp00kyClient::tabs"
+		}, "sharedTabs requested but unsupported here; running solo");
+	}
+	/** The shared-tabs role machinery, wired to this client's modules. */
+	buildTabsCoordinator() {
+		const engine = this.local;
+		const tabId = typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : `tab_${Math.random().toString(36).slice(2)}`;
+		return new TabsCoordinator({
+			tabId,
+			fingerprint: computeTabsFingerprint({
+				coreVersion: "0.0.1-canary.155",
+				schemaHash: hash53(this.config.schemaSurql),
+				endpoint: this.config.database.endpoint ?? "",
+				namespace: this.config.database.namespace,
+				database: this.config.database.database
+			}),
+			hooks: {
+				adoptOwner: (bucketId, opts) => engine.adoptOwner(bucketId, {
+					workerLockName: opts.workerLockName,
+					allowMemoryFallback: opts.allowMemoryFallback,
+					resumeHeld: opts.resumeHeld
+				}),
+				adoptAttached: (dbPort, snapshot) => engine.adoptAttached(dbPort, snapshot, (reason) => engine.onLeaderLost(reason)),
+				releaseOwnership: () => engine.releaseOwnership(),
+				onLeaderLost: (reason) => engine.onLeaderLost(reason),
+				exposeClientPort: (clientId, port) => engine.exposeClientPort(clientId, port),
+				removeClientPort: (clientId) => engine.removeClientPort(clientId),
+				becomeSyncLeader: async (hub) => {
+					this.streamProcessor.setPersistenceEnabled(true);
+					this.cache.setIngestRelay((tuples) => hub.relayIngest(tuples));
+					this.sync.setTabContext("leader", tabId);
+					this.dataModule.setTabId(tabId);
+					await this.sync.promoteToLeader(hub);
+				},
+				becomeSyncFollower: (forwarder) => {
+					this.streamProcessor.setPersistenceEnabled(false);
+					this.cache.setIngestRelay(null);
+					this.sync.setTabContext("follower", tabId);
+					this.dataModule.setTabId(tabId);
+					this.sync.demoteToFollower(forwarder);
+					const inner = forwarder.onLeaderMessage;
+					forwarder.onLeaderMessage = (msg) => {
+						if (msg.type === "ingest-relay") {
+							this.cache.applyRelayedIngest(msg.tuples);
+							return;
+						}
+						inner?.(msg);
+					};
+				},
+				becomeSyncSolo: () => {
+					this.streamProcessor.setPersistenceEnabled(true);
+					this.cache.setIngestRelay(null);
+					this.sync.setTabContext("solo", tabId);
+				},
+				currentStorageHealth: () => this.local.storageHealth ?? {
+					status: "unknown",
+					fallback: false
+				}
+			},
+			logger: this.logger,
+			onLeaderPageHide: () => {
+				engine.shutdownOwnedWorker();
+			}
+		});
 	}
 	/**
 	* Setup direct callbacks instead of event subscriptions
@@ -7390,7 +8924,23 @@ var Sp00kyClient = class {
 		this.logger.info({ Category: "sp00ky-client::Sp00kyClient::init" }, "Sp00kyClient initialization started");
 		try {
 			const bootBucket = readBootBucketHint() ?? ANON_USER_ID;
-			await this.local.connect(bootBucket);
+			if (this.tabsCoordinator) try {
+				const role = await this.tabsCoordinator.start(bootBucket);
+				this.sharedActive = true;
+				this.logger.info({
+					role,
+					bootBucket,
+					Category: "sp00ky-client::Sp00kyClient::init"
+				}, "Shared-tabs role assigned");
+			} catch (e) {
+				this.logger.warn({
+					err: e,
+					Category: "sp00ky-client::Sp00kyClient::init"
+				}, "Shared-tabs unavailable; booting solo");
+				this.sharedActive = false;
+				await this.local.connect(bootBucket);
+			}
+			else await this.local.connect(bootBucket);
 			this.logger.debug({
 				bootBucket,
 				Category: "sp00ky-client::Sp00kyClient::init"
@@ -7501,9 +9051,26 @@ var Sp00kyClient = class {
 		this.crdtManager.closeAll({ flush: false });
 		const reopen = gateRelease ?? this.local.beginSwitch();
 		try {
-			await this.local.switchStore(target);
-			if (this.local.usesSurqlSchema) await this.migrator.provision(this.config.schemaSurql);
-			await this.local.queryUngated("DELETE _00_query;");
+			if (this.sharedActive && this.tabsCoordinator) try {
+				await this.tabsCoordinator.moveToBucket(target);
+			} catch (e) {
+				this.logger.warn({
+					err: e,
+					target,
+					Category: "sp00ky-client::Sp00kyClient::doSwitchBucket"
+				}, "Shared-tabs bucket move failed; switching solo");
+				this.sharedActive = false;
+				this.sync.setTabContext("solo", null);
+				this.cache.setIngestRelay(null);
+				this.streamProcessor.setPersistenceEnabled(true);
+				await this.local.switchStore(target);
+				await this.local.queryUngated("DELETE _00_query;");
+			}
+			else {
+				await this.local.switchStore(target);
+				if (this.local.usesSurqlSchema) await this.migrator.provision(this.config.schemaSurql);
+				await this.local.queryUngated("DELETE _00_query;");
+			}
 			this.streamProcessor.setStateKeySuffix(target);
 			await this.streamProcessor.reset();
 			this.streamProcessor.setPermissions(extractSelectPermissions(this.config.schemaSurql));
@@ -7536,6 +9103,7 @@ var Sp00kyClient = class {
 		await this.featureFlags.closeAll();
 		await this.appReleases.closeAll();
 		this.crdtManager.closeAll();
+		if (this.tabsCoordinator) await this.tabsCoordinator.stop();
 		await this.local.close();
 		await this.remote.close();
 	}