@happyvertical/smrt-web 0.38.2 → 0.38.3

package/dist/index.js

@@ -1,6 +1,1038 @@
 import { createCollection } from "@tanstack/db";
 import { QueryClient } from "@tanstack/query-core";
 import { queryCollectionOptions } from "@tanstack/query-db-collection";
+//#region src/capability.ts
+async function runWrapMutation(capabilities, envelope, ctx) {
+	for (const capability of capabilities) {
+		if (!capability.wrapMutation) continue;
+		const outcome = await capability.wrapMutation(envelope, ctx);
+		if (outcome?.handled) return {
+			handled: true,
+			result: outcome.result
+		};
+	}
+	return { handled: false };
+}
+//#endregion
+//#region src/durable-store.ts
+function durableStoreNamespace(key) {
+	const optional = (value) => value === void 0 ? "" : `_${encodeURIComponent(value)}`;
+	return `smrt-web:${encodeURIComponent(key.apiBase)}:${optional(key.tenantId)}:${optional(key.identityId)}:${encodeURIComponent(key.manifestHash)}`;
+}
+var registry = /* @__PURE__ */ new Map();
+function registerDurableResource(namespace, resource) {
+	let resources = registry.get(namespace);
+	if (!resources) {
+		resources = /* @__PURE__ */ new Set();
+		registry.set(namespace, resources);
+	}
+	resources.add(resource);
+	return () => {
+		const current = registry.get(namespace);
+		if (!current) return;
+		current.delete(resource);
+		if (current.size === 0) registry.delete(namespace);
+	};
+}
+async function wipeDurableStore(namespace) {
+	const resources = registry.get(namespace);
+	if (!resources || resources.size === 0) {
+		registry.delete(namespace);
+		return;
+	}
+	const snapshot = [...resources];
+	registry.delete(namespace);
+	await Promise.allSettled(snapshot.map((resource) => resource.clear()));
+}
+//#endregion
+//#region src/offline/durable-queue.ts
+var OUTBOX_STORE = "outbox";
+var OUTBOX_STATE_INDEX = "state";
+function promisifyRequest(request) {
+	return new Promise((resolve, reject) => {
+		request.onsuccess = () => resolve(request.result);
+		request.onerror = () => reject(request.error ?? /* @__PURE__ */ new Error("[smrt-web] IndexedDB request failed"));
+	});
+}
+function awaitTransaction(tx) {
+	return new Promise((resolve, reject) => {
+		tx.oncomplete = () => resolve();
+		tx.onerror = () => reject(tx.error ?? /* @__PURE__ */ new Error("[smrt-web] IndexedDB transaction failed"));
+		tx.onabort = () => reject(tx.error ?? /* @__PURE__ */ new Error("[smrt-web] IndexedDB transaction aborted"));
+	});
+}
+async function probeIndexedDb() {
+	const idb = globalThis.indexedDB;
+	if (!idb) return false;
+	const probeName = "__smrt_web_outbox_probe__";
+	try {
+		(await new Promise((resolve, reject) => {
+			const request = idb.open(probeName, 1);
+			request.onsuccess = () => resolve(request.result);
+			request.onerror = () => reject(request.error ?? /* @__PURE__ */ new Error("probe failed"));
+			request.onblocked = () => reject(/* @__PURE__ */ new Error("probe blocked"));
+		})).close();
+		try {
+			idb.deleteDatabase(probeName);
+		} catch {}
+		return true;
+	} catch {
+		return false;
+	}
+}
+var DurableOutboxQueue = class {
+	db;
+	/** The IndexedDB database name (== the durable-store namespace). */
+	dbName;
+	constructor(db, dbName) {
+		this.db = db;
+		this.dbName = dbName;
+	}
+	/**
+	* Append a mutation to the tail of the queue in state `pending`, due
+	* immediately (`nextAttemptAt = 0`, `attempts = 0`). Resolves with the
+	* assigned `seq` once the write is durably committed.
+	*/
+	async enqueue(input) {
+		const now = Date.now();
+		const row = {
+			itemId: input.itemId,
+			object: input.object,
+			op: input.op,
+			id: input.id,
+			payload: input.payload,
+			baseUpdatedAt: input.baseUpdatedAt,
+			state: "pending",
+			attempts: 0,
+			nextAttemptAt: 0,
+			enqueuedAt: now
+		};
+		const tx = this.db.transaction(OUTBOX_STORE, "readwrite");
+		const seq = await promisifyRequest(tx.objectStore(OUTBOX_STORE).add(row));
+		await awaitTransaction(tx);
+		return seq;
+	}
+	/**
+	* Persist a state transition (and any of attempts/backoff/error) for the row
+	* at `seq`, reading-then-writing inside ONE transaction so a concurrent drain
+	* in the same tab can't lose the update. A no-op if the row is already gone
+	* (removed by a prior terminal transition).
+	*/
+	async markState(seq, patch) {
+		const tx = this.db.transaction(OUTBOX_STORE, "readwrite");
+		const store = tx.objectStore(OUTBOX_STORE);
+		const existing = await promisifyRequest(store.get(seq));
+		if (!existing) {
+			await awaitTransaction(tx);
+			return;
+		}
+		const next = {
+			...existing,
+			...patch,
+			seq
+		};
+		await promisifyRequest(store.put(next));
+		await awaitTransaction(tx);
+	}
+	/**
+	* All rows that are due to (re)send at `now`: state `pending` AND
+	* `nextAttemptAt <= now`, in ascending `seq` (FIFO). Uses the `state` index to
+	* avoid scanning terminal tombstones. Terminal rows (`synced`/`failed`) are
+	* excluded — they await removal, not replay.
+	*/
+	async listPending(now) {
+		const tx = this.db.transaction(OUTBOX_STORE, "readonly");
+		const rows = await promisifyRequest(tx.objectStore(OUTBOX_STORE).index(OUTBOX_STATE_INDEX).getAll(IDBKeyRange.only("pending")));
+		await awaitTransaction(tx);
+		return rows.filter((row) => row.nextAttemptAt <= now).sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
+	}
+	/** Remove the row at `seq` (a terminal transition drops it). */
+	async remove(seq) {
+		const tx = this.db.transaction(OUTBOX_STORE, "readwrite");
+		await promisifyRequest(tx.objectStore(OUTBOX_STORE).delete(seq));
+		await awaitTransaction(tx);
+	}
+	/** Every row currently in the queue (any state), ascending `seq`. */
+	async all() {
+		const tx = this.db.transaction(OUTBOX_STORE, "readonly");
+		const rows = await promisifyRequest(tx.objectStore(OUTBOX_STORE).getAll());
+		await awaitTransaction(tx);
+		return rows.sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
+	}
+	/**
+	* Drop every row — the durable-store `clear()` for `wipeDurableStore`. Empties
+	* the store but keeps the database (and its `seq` autoincrement counter) so a
+	* subsequent enqueue still gets fresh monotonic ids.
+	*/
+	async clear() {
+		const tx = this.db.transaction(OUTBOX_STORE, "readwrite");
+		await promisifyRequest(tx.objectStore(OUTBOX_STORE).clear());
+		await awaitTransaction(tx);
+	}
+	/** Close the underlying database handle (called on engine dispose). */
+	close() {
+		this.db.close();
+	}
+};
+function openDurableOutboxQueue(dbName) {
+	const idb = globalThis.indexedDB;
+	if (!idb) return Promise.reject(/* @__PURE__ */ new Error("[smrt-web] IndexedDB is unavailable in this environment"));
+	return new Promise((resolve, reject) => {
+		const request = idb.open(dbName, 1);
+		request.onupgradeneeded = () => {
+			const db = request.result;
+			if (!db.objectStoreNames.contains("outbox")) db.createObjectStore(OUTBOX_STORE, {
+				keyPath: "seq",
+				autoIncrement: true
+			}).createIndex(OUTBOX_STATE_INDEX, "state", { unique: false });
+		};
+		request.onsuccess = () => resolve(new DurableOutboxQueue(request.result, dbName));
+		request.onerror = () => reject(request.error ?? /* @__PURE__ */ new Error(`[smrt-web] failed to open outbox database "${dbName}"`));
+		request.onblocked = () => reject(/* @__PURE__ */ new Error(`[smrt-web] opening outbox database "${dbName}" was blocked`));
+	});
+}
+//#endregion
+//#region src/offline/leader.ts
+function getLockManager() {
+	const locks = globalThis.navigator?.locks;
+	if (locks && typeof locks.request === "function") return locks;
+}
+var warnedNoLocks = false;
+function acquireLeadership(lockName, onAcquired, onReleased) {
+	const locks = getLockManager();
+	if (!locks) {
+		if (!warnedNoLocks) {
+			warnedNoLocks = true;
+			console.warn("[smrt-web] Web Locks API unavailable — the offline outbox falls back to single-tab leadership; the multi-tab exactly-one-replayer guarantee does not hold across tabs.");
+		}
+		let released2 = false;
+		const release2 = () => {
+			if (released2) return;
+			released2 = true;
+			onReleased();
+		};
+		queueMicrotask(() => {
+			if (!released2) onAcquired();
+		});
+		return release2;
+	}
+	const controller = new AbortController();
+	let releaseHeldLock;
+	let released = false;
+	let acquired = false;
+	const release = () => {
+		if (released) return;
+		released = true;
+		if (acquired && releaseHeldLock) releaseHeldLock();
+		else controller.abort();
+		onReleased();
+	};
+	locks.request(lockName, {
+		signal: controller.signal,
+		mode: "exclusive"
+	}, () => {
+		acquired = true;
+		if (released) return Promise.resolve();
+		onAcquired();
+		return new Promise((resolve) => {
+			releaseHeldLock = resolve;
+		});
+	}).catch((error) => {
+		if (error?.name !== "AbortError") console.warn("[smrt-web] outbox leader lock request failed", error);
+		if (!released) {
+			released = true;
+			onReleased();
+		}
+	});
+	return release;
+}
+//#endregion
+//#region src/offline/types.ts
+var MAX_SYNC_APPLY_BATCH_SIZE = 1e3;
+var SYNC_APPLY_ROUTE_SEGMENTS = ["sync", "apply"];
+var DEFAULT_BACKOFF = {
+	initialDelayMs: 1e3,
+	multiplier: 2,
+	maxDelayMs: 6e4
+};
+function computeBackoffDelay(attempts, backoff, random = Math.random) {
+	const exponent = Math.max(0, attempts - 1);
+	const raw = backoff.initialDelayMs * backoff.multiplier ** exponent;
+	const capped = Math.min(backoff.maxDelayMs, raw);
+	const jitter = .5 + random() * .5;
+	return Math.round(capped * jitter);
+}
+//#endregion
+//#region src/offline/engine.ts
+function envelopeKindToOp(kind) {
+	return kind === "insert" ? "create" : kind;
+}
+function newItemId() {
+	const cryptoRef = globalThis.crypto;
+	if (cryptoRef?.randomUUID) return cryptoRef.randomUUID();
+	return `item-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+function isDefinitelyOffline() {
+	return globalThis.navigator?.onLine === false;
+}
+var OutboxEngine = class {
+	config;
+	/**
+	* Per-collection callback sets, keyed by the collection route segment
+	* (`object`). Keyed by `object` — NOT by the queue row's `itemId` — precisely
+	* so replayed rows that were REHYDRATED from IndexedDB after a reload (whose
+	* itemIds this session never enqueued) still route their state/conflict events
+	* to the reloaded collection's callbacks. A `Set` per object so N collections
+	* sharing one engine+object each get every event (the common case is one
+	* collection per object, but the shared-engine model does not forbid more).
+	*/
+	listenersByObject = /* @__PURE__ */ new Map();
+	/** Ref count: number of collections currently attached to this engine. */
+	refCount = 0;
+	/** The durable queue, once opened. undefined while opening / if IDB absent. */
+	queue;
+	/** Resolves once the async open settles (success or degraded). */
+	ready;
+	/** True when IndexedDB was unavailable and the engine is a durable no-op. */
+	degraded = false;
+	/** Leadership handle; set once we've requested the leader lock. */
+	leadership;
+	/** True while this tab holds leadership. */
+	isLeader = false;
+	/** Unregister fn from the durable-store registry. */
+	unregisterResource;
+	/** True once dispose() ran — guards late async continuations. */
+	disposed = false;
+	/**
+	* Paused by an auth_required/forbidden result: the loop stops draining until
+	* a later enqueue (the app re-authenticated and is writing again) or an
+	* explicit retry wakes it. Items stay queued.
+	*/
+	paused = false;
+	/** True while a drain pass is running, to coalesce concurrent triggers. */
+	draining = false;
+	/** A drain requested while one was in flight — run one more pass after. */
+	drainQueued = false;
+	/** Timer for the next backoff-scheduled drain, if any. */
+	backoffTimer;
+	/** The `online` event listener, so we can remove it on dispose. */
+	onlineListener;
+	constructor(config) {
+		this.config = config;
+		this.ready = this.open();
+		this.wireOnlineListener();
+		this.requestLeadership();
+		this.ready.then(() => {
+			if (!this.disposed) this.drain();
+		});
+	}
+	/** Open the durable queue (or mark degraded if IndexedDB is unusable). */
+	async open() {
+		if (!await probeIndexedDb()) {
+			this.degraded = true;
+			console.warn("[smrt-web] IndexedDB unavailable — the offline outbox is disabled; offline writes will not be durable.");
+			return;
+		}
+		try {
+			this.queue = await openDurableOutboxQueue(this.config.namespace);
+			this.unregisterResource = this.config.registerResource(async () => {
+				await this.queue?.clear();
+			});
+			if (this.disposed) {
+				this.queue.close();
+				this.queue = void 0;
+				this.unregisterResource?.();
+				this.unregisterResource = void 0;
+				return;
+			}
+		} catch (error) {
+			this.degraded = true;
+			console.warn("[smrt-web] failed to open the offline outbox", error);
+		}
+	}
+	/** Wake the drain loop immediately when connectivity returns. */
+	wireOnlineListener() {
+		const target = globalThis;
+		if (typeof target.addEventListener !== "function") return;
+		const listener = () => {
+			this.drain();
+		};
+		target.addEventListener("online", listener);
+		this.onlineListener = listener;
+	}
+	/** Request cross-tab leadership; drain whenever we hold it. */
+	requestLeadership() {
+		const lockName = `smrt-web-outbox-leader:${this.config.namespace}`;
+		this.leadership = acquireLeadership(lockName, () => {
+			this.isLeader = true;
+			this.drain();
+		}, () => {
+			this.isLeader = false;
+		});
+	}
+	/**
+	* Attach a collection: register its per-object callbacks and bump the ref
+	* count. Returns the exact callback record registered so the caller can pass
+	* it back to {@link unregisterCollection} for precise removal (two collections
+	* on the same object must each detach only their own callbacks). Registering
+	* by `object` is what lets rehydrated rows (reloaded from IDB) reach this
+	* collection's callbacks even though this session never enqueued them.
+	*/
+	registerCollection(binding) {
+		this.refCount += 1;
+		const record = {
+			onSyncStateChange: binding.onSyncStateChange,
+			onConflict: binding.onConflict
+		};
+		let set = this.listenersByObject.get(binding.object);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.listenersByObject.set(binding.object, set);
+		}
+		set.add(record);
+		return record;
+	}
+	/**
+	* Detach a collection: remove its callback record and decrement the ref count;
+	* when it reaches zero, dispose the engine (release the lock, unregister from
+	* the durable-store registry, close IndexedDB). The durable ROWS are NOT
+	* cleared — they must survive to replay after a reload; only the in-memory
+	* engine is torn down. Returns true if it disposed.
+	*/
+	async unregisterCollection(object, record) {
+		const set = this.listenersByObject.get(object);
+		if (set) {
+			set.delete(record);
+			if (set.size === 0) this.listenersByObject.delete(object);
+		}
+		this.refCount = Math.max(0, this.refCount - 1);
+		if (this.refCount > 0) return false;
+		await this.dispose();
+		return true;
+	}
+	/** Current ref count (test/introspection aid). */
+	get referenceCount() {
+		return this.refCount;
+	}
+	/**
+	* Enqueue an optimistic write into the durable queue and fire the initial
+	* `pending` state, then kick a drain. Resolves once the row is durably
+	* committed (so the caller's `wrapMutation` only reports handled after
+	* persistence). Replay events for this row (and for rows this session did not
+	* enqueue — reloaded from disk) route to the registered per-`object`
+	* callbacks, so a reload does not lose observability.
+	*
+	* In degraded (no-IndexedDB) mode the write is NOT durable, so this returns
+	* `undefined` and the capability falls through to the real fetcher instead
+	* of acknowledging an optimistic-only write.
+	*/
+	async enqueue(request) {
+		await this.ready;
+		if (!this.queue || this.degraded) return void 0;
+		const itemId = newItemId();
+		const op = envelopeKindToOp(request.kind);
+		const payload = op === "delete" ? void 0 : request.data;
+		await this.queue.enqueue({
+			itemId,
+			object: request.object,
+			op,
+			id: request.rowId,
+			payload,
+			baseUpdatedAt: request.baseUpdatedAt
+		});
+		this.emit({
+			itemId,
+			rowId: request.rowId,
+			object: request.object,
+			state: "pending",
+			attempts: 0
+		});
+		this.paused = false;
+		this.drain();
+		return itemId;
+	}
+	/**
+	* Force a retry of a specific queued item now: clears its backoff gate and
+	* wakes the loop. The bridge `OutboxHandle.retry(itemId)` calls this so an app
+	* "retry" button can flush a backed-off or auth-paused item. A no-op for an
+	* item that is not (or no longer) queued.
+	*/
+	async retry(itemId) {
+		await this.ready;
+		if (!this.queue) return;
+		const row = (await this.queue.all()).find((r) => r.itemId === itemId && r.state === "pending");
+		if (!row || row.seq === void 0) return;
+		await this.queue.markState(row.seq, { nextAttemptAt: 0 });
+		this.paused = false;
+		this.drain();
+	}
+	/**
+	* A read-only snapshot of the durable queue — the basis of
+	* `OutboxHandle.snapshot()`. Because the READ cache is NOT rehydrated after a
+	* reload in this slice (that's #1764's warmStart), the snapshot + the raw IDB
+	* store are how a test/app proves durability, not `collection.toArray()`.
+	*/
+	async snapshot() {
+		await this.ready;
+		if (!this.queue) return [];
+		return (await this.queue.all()).map((row) => ({
+			itemId: row.itemId,
+			object: row.object,
+			op: row.op,
+			rowId: row.id,
+			state: row.state,
+			attempts: row.attempts,
+			nextAttemptAt: row.nextAttemptAt,
+			lastError: row.lastError
+		}));
+	}
+	/**
+	* Deliver a state event to every callback registered for the event's
+	* collection `object` (best-effort). Routing by `object` — not `itemId` —
+	* means a row REHYDRATED from IndexedDB after a reload still reaches the
+	* reloaded collection's callback even though this session never enqueued it.
+	*/
+	emit(event) {
+		const set = this.listenersByObject.get(event.object);
+		if (!set) return;
+		for (const listener of set) try {
+			listener.onSyncStateChange?.(event);
+		} catch (error) {
+			console.warn("[smrt-web] onSyncStateChange callback threw", error);
+		}
+	}
+	/** Deliver a conflict to every callback registered for its collection. */
+	emitConflict(conflict) {
+		const set = this.listenersByObject.get(conflict.object);
+		if (!set) return;
+		for (const listener of set) try {
+			listener.onConflict?.(conflict);
+		} catch (error) {
+			console.warn("[smrt-web] onConflict callback threw", error);
+		}
+	}
+	/**
+	* The replay loop. Gated on: (a) holding leadership, (b) not paused by an
+	* auth failure, (c) `navigator.onLine !== false`, (d) IndexedDB usable. Drains
+	* all rows due now (`nextAttemptAt <= now`), oldest-first, chunked into
+	* batches of ≤1000 per POST, one POST at a time to preserve FIFO across
+	* chunks. Concurrency-coalesced: a drain requested while one runs sets a flag
+	* to run exactly one more pass, so overlapping triggers never interleave.
+	*/
+	async drain() {
+		if (this.draining) {
+			this.drainQueued = true;
+			return;
+		}
+		this.draining = true;
+		try {
+			for (;;) {
+				this.drainQueued = false;
+				await this.drainOnce();
+				if (!this.drainQueued) break;
+			}
+		} finally {
+			this.draining = false;
+		}
+	}
+	/** One drain pass: send every currently-due batch, then schedule backoff. */
+	async drainOnce() {
+		if (this.disposed) return;
+		if (!this.isLeader) return;
+		if (this.paused) return;
+		if (this.degraded || !this.queue) return;
+		if (isDefinitelyOffline()) return;
+		const pending = (await this.queue.all()).filter((row) => row.state === "pending");
+		if (pending.length === 0) return;
+		const now = Date.now();
+		const firstBlocked = pending.findIndex((row) => row.nextAttemptAt > now);
+		const due = firstBlocked === -1 ? pending : pending.slice(0, firstBlocked);
+		if (due.length === 0) {
+			await this.scheduleNextBackoff();
+			return;
+		}
+		for (let i = 0; i < due.length; i += MAX_SYNC_APPLY_BATCH_SIZE) {
+			if (this.disposed || this.paused || !this.isLeader) break;
+			const chunk = due.slice(i, i + MAX_SYNC_APPLY_BATCH_SIZE);
+			if (!await this.sendBatch(chunk)) break;
+		}
+		await this.scheduleNextBackoff();
+	}
+	/**
+	* Send one chunk through `POST {basePath}/sync/apply` and map results back
+	* onto durable transitions. On a network reject / non-200 / lost/mismatched
+	* response the WHOLE chunk stays `pending` (blind replay is safe) — every row
+	* goes back to `pending` with an incremented attempt + backoff so the loop
+	* doesn't hot-spin. Returns false when a retryable row remains pending, which
+	* stops this drain pass so newer FIFO chunks do not overtake it.
+	*/
+	async sendBatch(chunk) {
+		for (const row of chunk) this.emit({
+			itemId: row.itemId,
+			rowId: row.id,
+			object: row.object,
+			state: "uploading",
+			attempts: row.attempts
+		});
+		const items = chunk.map((row) => ({
+			itemId: row.itemId,
+			object: row.object,
+			op: row.op,
+			id: row.id,
+			payload: row.payload,
+			baseUpdatedAt: row.baseUpdatedAt
+		}));
+		let results;
+		try {
+			results = await this.postBatch(items);
+		} catch {
+			await this.requeueBatch(chunk, "network error during sync");
+			return false;
+		}
+		if (!results) {
+			await this.requeueBatch(chunk, "unexpected sync response shape");
+			return false;
+		}
+		let drained = true;
+		for (let i = 0; i < chunk.length; i += 1) {
+			const row = chunk[i];
+			const result = results[i];
+			if (!result) {
+				await this.requeueRow(row, "missing result for item");
+				drained = false;
+				continue;
+			}
+			const applied = await this.applyResult(row, result);
+			drained = drained && applied;
+		}
+		return drained;
+	}
+	/**
+	* POST a batch to `{basePath}/sync/apply`. Throws on a non-2xx or a network
+	* error (the caller treats a throw as "response lost → keep pending"). Returns
+	* the positional `results` array, or `undefined` on a malformed 200 body.
+	*/
+	async postBatch(items) {
+		const url = `${this.config.syncApplyBasePath}/${SYNC_APPLY_ROUTE_SEGMENTS.join("/")}`;
+		const response = await this.config.fetchFn(url, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({ items })
+		});
+		if (!response.ok) throw new Error(`[smrt-web] sync/apply returned HTTP ${response.status}`);
+		const body = await response.json().catch(() => null);
+		if (!body || !Array.isArray(body.results)) return void 0;
+		return body.results;
+	}
+	/**
+	* Map one positional apply result onto a durable transition + observable
+	* state, per the contract's consumer notes. See the class doc's mapping table.
+	*/
+	async applyResult(row, result) {
+		if (row.seq === void 0) return true;
+		if (result.status === "applied") {
+			await this.finishSynced(row);
+			return true;
+		}
+		if (result.status === "conflict") {
+			const reason2 = result.reason === "create_conflict" ? "create_conflict" : "stale_write";
+			this.emitConflict({
+				itemId: row.itemId,
+				object: row.object,
+				rowId: row.id,
+				reason: reason2,
+				serverUpdatedAt: result.updatedAt
+			});
+			await this.finishSynced(row);
+			return true;
+		}
+		const reason = result.reason;
+		if (reason === "auth_required" || reason === "forbidden") {
+			this.paused = true;
+			await this.queue?.markState(row.seq, {
+				state: "pending",
+				lastError: `sync ${reason}`
+			});
+			this.emit({
+				itemId: row.itemId,
+				rowId: row.id,
+				object: row.object,
+				state: "pending",
+				attempts: row.attempts,
+				error: `sync ${reason}`
+			});
+			return false;
+		}
+		if (reason === "write_failed") {
+			await this.requeueRow(row, "sync write_failed");
+			return false;
+		}
+		await this.queue?.remove(row.seq);
+		this.emit({
+			itemId: row.itemId,
+			rowId: row.id,
+			object: row.object,
+			state: "failed",
+			attempts: row.attempts,
+			error: reason ? `sync ${reason}` : "sync rejected"
+		});
+		return true;
+	}
+	/** Remove a successfully-applied (or conflict-resolved) row → `synced`. */
+	async finishSynced(row) {
+		if (row.seq !== void 0) await this.queue?.remove(row.seq);
+		this.emit({
+			itemId: row.itemId,
+			rowId: row.id,
+			object: row.object,
+			state: "synced",
+			attempts: row.attempts
+		});
+	}
+	/** Re-queue every row of a failed batch (network path) with backoff. */
+	async requeueBatch(chunk, error) {
+		for (const row of chunk) await this.requeueRow(row, error);
+	}
+	/** Re-queue one row: attempts++, backoff gate, `pending` event. */
+	async requeueRow(row, error) {
+		if (row.seq === void 0) return;
+		const attempts = row.attempts + 1;
+		const delay = computeBackoffDelay(attempts, this.config.backoff, this.config.random);
+		const nextAttemptAt = Date.now() + delay;
+		await this.queue?.markState(row.seq, {
+			state: "pending",
+			attempts,
+			nextAttemptAt,
+			lastError: error
+		});
+		this.emit({
+			itemId: row.itemId,
+			rowId: row.id,
+			object: row.object,
+			state: "pending",
+			attempts,
+			error
+		});
+	}
+	/**
+	* Schedule the next drain for the soonest backed-off row's `nextAttemptAt`.
+	* Only one timer is ever pending; a sooner schedule replaces a later one.
+	*/
+	async scheduleNextBackoff() {
+		if (this.disposed || this.paused || !this.queue) return;
+		const firstPending = (await this.queue.all()).find((r) => r.state === "pending");
+		if (!firstPending) return;
+		const now = Date.now();
+		const delay = Math.max(0, firstPending.nextAttemptAt - now);
+		if (this.backoffTimer) clearTimeout(this.backoffTimer);
+		const timers = globalThis;
+		if (typeof timers.setTimeout !== "function") return;
+		this.backoffTimer = timers.setTimeout(() => {
+			this.backoffTimer = void 0;
+			this.drain();
+		}, delay);
+		this.backoffTimer.unref?.();
+	}
+	/**
+	* Tear down the in-memory engine: release leadership, remove the online
+	* listener, clear timers, unregister from the durable-store registry, and
+	* close IndexedDB. Does NOT clear the durable rows — they must survive to
+	* replay on the next load.
+	*/
+	async dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		if (this.backoffTimer) {
+			clearTimeout(this.backoffTimer);
+			this.backoffTimer = void 0;
+		}
+		const target = globalThis;
+		if (this.onlineListener && typeof target.removeEventListener === "function") {
+			target.removeEventListener("online", this.onlineListener);
+			this.onlineListener = void 0;
+		}
+		this.leadership?.();
+		this.leadership = void 0;
+		this.unregisterResource?.();
+		this.unregisterResource = void 0;
+		await this.ready.catch(() => void 0);
+		this.queue?.close();
+		this.queue = void 0;
+		this.listenersByObject.clear();
+	}
+};
+var engines = /* @__PURE__ */ new Map();
+function getOrCreateOutboxEngine(config) {
+	let engine = engines.get(config.namespace);
+	if (!engine) {
+		engine = new OutboxEngine(config);
+		engines.set(config.namespace, engine);
+	}
+	return engine;
+}
+function acquireOutboxEngine(config, binding) {
+	const engine = getOrCreateOutboxEngine(config);
+	return {
+		engine,
+		record: engine.registerCollection(binding)
+	};
+}
+async function releaseOutboxEngine(namespace, engine, object, record) {
+	if (await engine.unregisterCollection(object, record) && engines.get(namespace) === engine) engines.delete(namespace);
+}
+//#endregion
+//#region src/offline.ts
+function resolveBackoff(backoff) {
+	return {
+		initialDelayMs: backoff?.initialDelayMs ?? DEFAULT_BACKOFF.initialDelayMs,
+		multiplier: backoff?.multiplier ?? DEFAULT_BACKOFF.multiplier,
+		maxDelayMs: backoff?.maxDelayMs ?? DEFAULT_BACKOFF.maxDelayMs
+	};
+}
+var handlesByNamespace = /* @__PURE__ */ new Map();
+function getPayloadUpdatedAt(data) {
+	const value = data.updatedAt ?? data.updated_at;
+	if (typeof value === "string") return value;
+	if (value instanceof Date) return value.toISOString();
+}
+function offlineOutbox(config) {
+	const namespace = durableStoreNamespace(config.namespace);
+	const syncApplyBasePath = config.syncApplyBasePath ?? "/api/v1";
+	const fetchFn = config.fetchFn ?? ((...args) => globalThis.fetch(...args));
+	const backoff = resolveBackoff(config.backoff);
+	const object = config.object.name;
+	let engine;
+	let record;
+	return {
+		name: "offline-outbox",
+		onAttach() {
+			const acquired = acquireOutboxEngine({
+				namespace,
+				syncApplyBasePath,
+				fetchFn,
+				backoff,
+				random: config.random,
+				registerResource: (clear) => registerDurableResource(namespace, {
+					kind: "outbox",
+					clear
+				})
+			}, {
+				object,
+				onSyncStateChange: config.onSyncStateChange,
+				onConflict: config.onConflict
+			});
+			engine = acquired.engine;
+			record = acquired.record;
+			handlesByNamespace.set(namespace, engine);
+		},
+		async wrapMutation(envelope) {
+			if (!engine) return { handled: false };
+			if (!await engine.enqueue({
+				kind: envelope.kind,
+				object,
+				rowId: envelope.key,
+				data: envelope.data,
+				baseUpdatedAt: envelope.baseUpdatedAt ?? getPayloadUpdatedAt(envelope.data)
+			})) return { handled: false };
+			return {
+				handled: true,
+				result: envelope.data
+			};
+		},
+		async teardown() {
+			if (!engine || !record) return;
+			const current = engine;
+			const currentRecord = record;
+			engine = void 0;
+			record = void 0;
+			const before = current.referenceCount;
+			await releaseOutboxEngine(namespace, current, object, currentRecord);
+			if (before <= 1 && handlesByNamespace.get(namespace) === current) handlesByNamespace.delete(namespace);
+		}
+	};
+}
+function getOutboxHandle(namespace) {
+	const engine = handlesByNamespace.get(namespace);
+	if (!engine) return void 0;
+	return {
+		snapshot: () => engine.snapshot(),
+		retry: (itemId) => engine.retry(itemId)
+	};
+}
+//#endregion
+//#region src/sse-client.ts
+var EVENT_SOURCE_CLOSED = 2;
+function defaultEventSourceFactory(url, init) {
+	const EventSourceCtor = globalThis.EventSource;
+	if (typeof EventSourceCtor !== "function") return void 0;
+	return new EventSourceCtor(url, init);
+}
+function createSmrtWebEventSubscriber(config) {
+	const { eventsUrl, changesUrl, fetchFn = (...args) => globalThis.fetch(...args), eventSourceFactory = defaultEventSourceFactory, pollIntervalMs = 5e3, withCredentials = true } = config;
+	const tableInvalidators = /* @__PURE__ */ new Map();
+	let lastSeq = null;
+	let transport = "idle";
+	let eventSource = null;
+	let pollTimer = null;
+	let closed = false;
+	const registeredTables = () => [...tableInvalidators.keys()].sort((a, b) => a.localeCompare(b));
+	const buildChangesUrl = (since, tables) => {
+		const url = new URL(changesUrl, "http://smrt.local/");
+		url.searchParams.set("since", String(since));
+		url.searchParams.set("tables", tables.join(","));
+		if (/^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(changesUrl)) return url.href;
+		const pathQueryHash = `${url.pathname}${url.search}${url.hash}`;
+		if (changesUrl.startsWith("//")) return `//${url.host}${pathQueryHash}`;
+		if (changesUrl.startsWith("/")) return pathQueryHash;
+		return pathQueryHash.startsWith("/") ? pathQueryHash.slice(1) : pathQueryHash;
+	};
+	const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+	const warn = (message, error) => {
+		console.warn(`[smrt-web] live subscriber: ${message}`, error);
+	};
+	const fireAll = (invalidators) => {
+		if (!invalidators || invalidators.size === 0) return;
+		for (const invalidate of [...invalidators]) try {
+			invalidate();
+		} catch (error) {
+			warn("an invalidator threw; ignoring", error);
+		}
+	};
+	const invalidateTable = (table) => {
+		fireAll(tableInvalidators.get(table));
+	};
+	const invalidateAll = () => {
+		for (const invalidators of tableInvalidators.values()) fireAll(invalidators);
+	};
+	const advanceLastSeqFromEventId = (lastEventId) => {
+		const seq = Number(lastEventId);
+		if (Number.isFinite(seq)) lastSeq = seq;
+	};
+	const onChange = (ev) => {
+		if (closed) return;
+		let table;
+		try {
+			const parsed = JSON.parse(ev.data);
+			if (typeof parsed.table === "string") table = parsed.table;
+		} catch (error) {
+			warn("dropping malformed change frame", error);
+			return;
+		}
+		if (table === void 0) {
+			warn("dropping change frame with no table", ev.data);
+			return;
+		}
+		advanceLastSeqFromEventId(ev.lastEventId);
+		invalidateTable(table);
+	};
+	const onResync = (ev) => {
+		if (closed) return;
+		advanceLastSeqFromEventId(ev.lastEventId);
+		invalidateAll();
+	};
+	const poll = async () => {
+		if (closed) return;
+		const tables = registeredTables();
+		if (tables.length === 0) return;
+		try {
+			const since = lastSeq ?? 0;
+			const url = buildChangesUrl(since, tables);
+			const response = await fetchFn(url, { credentials: "include" });
+			if (closed) return;
+			const page = await response.json();
+			if (closed) return;
+			if (page.resyncRequired) {
+				invalidateAll();
+				if (isFiniteNumber(page.resyncCursor)) lastSeq = page.resyncCursor;
+				else if (isFiniteNumber(page.cursor) && page.cursor > since) lastSeq = page.cursor;
+				else lastSeq = null;
+				return;
+			}
+			for (const change of page.changes ?? []) if (typeof change.table === "string") invalidateTable(change.table);
+			if (typeof page.cursor === "number") lastSeq = page.cursor;
+		} catch (error) {
+			warn("poll failed; will retry on the next interval", error);
+		}
+	};
+	const startPolling = () => {
+		if (closed || transport === "polling") return;
+		transport = "polling";
+		pollTimer = setInterval(() => {
+			poll();
+		}, pollIntervalMs);
+		pollTimer.unref?.();
+	};
+	const connectSse = (source) => {
+		transport = "sse";
+		eventSource = source;
+		source.addEventListener("change", onChange);
+		source.addEventListener("resync", onResync);
+		source.onerror = () => {
+			if (closed) return;
+			if (source.readyState === EVENT_SOURCE_CLOSED) {
+				try {
+					source.close();
+				} catch {}
+				eventSource = null;
+				startPolling();
+			}
+		};
+	};
+	const initialSource = eventSourceFactory(eventsUrl, { withCredentials });
+	if (initialSource) connectSse(initialSource);
+	else startPolling();
+	return {
+		get transport() {
+			return transport;
+		},
+		registerTable(table, invalidate) {
+			let set = tableInvalidators.get(table);
+			if (!set) {
+				set = /* @__PURE__ */ new Set();
+				tableInvalidators.set(table, set);
+			}
+			set.add(invalidate);
+			return () => {
+				const current = tableInvalidators.get(table);
+				if (!current) return;
+				current.delete(invalidate);
+				if (current.size === 0) tableInvalidators.delete(table);
+			};
+		},
+		invalidateAll,
+		close() {
+			if (closed) return;
+			closed = true;
+			if (eventSource) {
+				try {
+					eventSource.close();
+				} catch {}
+				eventSource = null;
+			}
+			if (pollTimer) {
+				clearInterval(pollTimer);
+				pollTimer = null;
+			}
+			tableInvalidators.clear();
+			transport = "idle";
+		}
+	};
+}
+function liveInvalidation(config) {
+	const { subscriber, tableName } = config;
+	let unregister;
+	return {
+		name: "live-invalidation",
+		onAttach(ctx) {
+			unregister = subscriber.registerTable(tableName, () => ctx.invalidate());
+		},
+		teardown() {
+			unregister?.();
+			unregister = void 0;
+		}
+	};
+}
+//#endregion
 //#region src/index.ts
 var SmrtWebRequestError = class extends Error {
 	payload;
@@ -95,24 +1127,34 @@ function projectChanges(changes) {
 		return projected;
 	});
 }
+function getBaseUpdatedAt(row) {
+	if (!row || typeof row !== "object") return void 0;
+	const record = row;
+	const value = record.updatedAt ?? record.updated_at;
+	if (typeof value === "string") return value;
+	if (value instanceof Date) return value.toISOString();
+}
 var engineCollections = /* @__PURE__ */ new WeakMap();
 function getEngineCollection(handle) {
 	const engine = engineCollections.get(handle);
 	if (engine === void 0) throw new SmrtWebRequestError("[smrt-web] getEngineCollection: not a smrt-web collection handle");
 	return engine;
 }
+function warnCapability(capability, hook, error) {
+	console.warn(`[smrt-web] capability "${capability.name}" ${hook} threw; ignoring`, error);
+}
 function createSmrtCollection(definition, options) {
 	const { staleTimeMs = 3e4, retry = false, scope, initialData } = options;
+	const capabilities = options.capabilities ?? [];
 	const fetchers = options.fetchers ?? createDefinitionFetchers(definition, options.basePath, options.fetchFn);
 	const queryClient = resolveQueryClient(options.client);
 	const idField = definition.idField || "id";
-	const cacheId = scope ? `smrt:${scope}:${definition.name}` : `smrt:${definition.name}`;
-	const queryKey = scope ? [
+	let cacheId = scope ? `smrt:${scope}:${definition.name}` : `smrt:${definition.name}`;
+	let queryKey = scope ? [
 		"smrt",
 		scope,
 		definition.name
 	] : ["smrt", definition.name];
-	if (initialData !== void 0) queryClient.setQueryData(queryKey, (existing) => existing ?? initialData);
 	const invalidationTargets = /* @__PURE__ */ new Set([definition.name]);
 	for (const relationship of definition.relationships ?? []) invalidationTargets.add(relationship.relatedCollection);
 	const invalidateRelated = () => {
@@ -123,6 +1165,108 @@ function createSmrtCollection(definition, options) {
 			return typeof collectionSegment === "string" && invalidationTargets.has(collectionSegment);
 		} });
 	};
+	const ctx = {
+		definition,
+		fetchers,
+		get cacheKey() {
+			return queryKey;
+		},
+		get cacheId() {
+			return cacheId;
+		},
+		invalidate: () => invalidateRelated()
+	};
+	for (const capability of capabilities) {
+		let extra;
+		try {
+			extra = capability.contributeCacheKey?.(ctx);
+		} catch (error) {
+			warnCapability(capability, "contributeCacheKey", error);
+		}
+		if (extra && extra.length > 0) {
+			const name = queryKey[queryKey.length - 1];
+			queryKey = [
+				...queryKey.slice(0, -1),
+				...extra,
+				name
+			];
+			cacheId = `${cacheId}:${extra.join(":")}`;
+		}
+	}
+	const seedCache = (rows) => {
+		queryClient.setQueryData(queryKey, (existing) => existing ?? rows);
+	};
+	let disposed = false;
+	const warmRowsFrom = async (capability, warm) => {
+		try {
+			return await warm;
+		} catch (error) {
+			warnCapability(capability, "warmStart", error);
+			return;
+		}
+	};
+	let warmStartPending;
+	if (initialData !== void 0) seedCache(initialData);
+	else for (let i = 0; i < capabilities.length; i += 1) {
+		const capability = capabilities[i];
+		let warm;
+		try {
+			warm = capability.warmStart?.(ctx);
+		} catch (error) {
+			warnCapability(capability, "warmStart", error);
+			continue;
+		}
+		if (warm === void 0) continue;
+		if (warm instanceof Promise) {
+			const firstPromise = warm;
+			warmStartPending = (async () => {
+				let rows = await warmRowsFrom(capability, firstPromise);
+				for (let j = i + 1; rows === void 0 && j < capabilities.length; j += 1) {
+					const later = capabilities[j];
+					let laterWarm;
+					try {
+						laterWarm = later.warmStart?.(ctx);
+					} catch (error) {
+						warnCapability(later, "warmStart", error);
+						continue;
+					}
+					if (laterWarm === void 0) continue;
+					rows = await warmRowsFrom(later, laterWarm);
+				}
+				if (rows !== void 0 && !disposed) seedCache(rows);
+			})();
+			break;
+		}
+		seedCache(warm);
+		break;
+	}
+	const notifySettled = (envelope, outcome) => {
+		for (const capability of capabilities) try {
+			capability.onSettled?.(envelope, outcome, ctx);
+		} catch (error) {
+			warnCapability(capability, "onSettled", error);
+		}
+	};
+	const persistMutation = async (envelope, runFetcher) => {
+		try {
+			const wrapped = await runWrapMutation(capabilities, envelope, ctx);
+			const result = wrapped.handled ? wrapped.result : await runFetcher();
+			notifySettled(envelope, {
+				ok: true,
+				result
+			});
+			return {
+				handled: wrapped.handled,
+				result
+			};
+		} catch (error) {
+			notifySettled(envelope, {
+				ok: false,
+				error
+			});
+			throw error;
+		}
+	};
 	const collection = createCollection(queryCollectionOptions({
 		id: cacheId,
 		queryKey,
@@ -132,22 +1276,54 @@ function createSmrtCollection(definition, options) {
 		queryFn: async () => unwrapListResult(await fetchers.list(), definition.name),
 		getKey: (row) => String(row[idField]),
 		onInsert: async ({ transaction }) => {
+			let anyHandled = false;
 			for (const mutation of transaction.mutations) {
-				const { [idField]: _localId, ...data } = mutation.modified;
-				unwrapItemResult(await fetchers.create(data), `create(${definition.name})`);
+				const modified = mutation.modified;
+				const envelope = {
+					kind: "insert",
+					key: String(modified[idField]),
+					data: modified
+				};
+				const outcome = await persistMutation(envelope, async () => {
+					const { [idField]: _localId, ...data } = modified;
+					return unwrapItemResult(await fetchers.create(data), `create(${definition.name})`);
+				});
+				anyHandled = anyHandled || outcome.handled;
 			}
+			if (anyHandled) return { refetch: false };
 			invalidateRelated();
 		},
 		onUpdate: fetchers.update ? async ({ transaction }) => {
+			let anyHandled = false;
 			for (const mutation of transaction.mutations) {
 				const key = String(mutation.key);
 				const changes = mutation.changes;
-				unwrapItemResult(await fetchers.update(key, changes), `update(${definition.name})`);
+				const envelope = {
+					kind: "update",
+					key,
+					data: changes,
+					baseUpdatedAt: getBaseUpdatedAt(mutation.original)
+				};
+				const outcome = await persistMutation(envelope, async () => unwrapItemResult(await fetchers.update(key, changes), `update(${definition.name})`));
+				anyHandled = anyHandled || outcome.handled;
 			}
+			if (anyHandled) return { refetch: false };
 			invalidateRelated();
 		} : void 0,
 		onDelete: fetchers.delete ? async ({ transaction }) => {
-			for (const mutation of transaction.mutations) await fetchers.delete(String(mutation.key));
+			let anyHandled = false;
+			for (const mutation of transaction.mutations) {
+				const key = String(mutation.key);
+				const envelope = {
+					kind: "delete",
+					key,
+					data: {},
+					baseUpdatedAt: getBaseUpdatedAt(mutation.original)
+				};
+				const outcome = await persistMutation(envelope, async () => fetchers.delete(key));
+				anyHandled = anyHandled || outcome.handled;
+			}
+			if (anyHandled) return { refetch: false };
 			invalidateRelated();
 		} : void 0
 	}));
@@ -166,10 +1342,20 @@ function createSmrtCollection(definition, options) {
 			return row === void 0 ? void 0 : toPlainRow(row);
 		},
 		preload() {
-			return collection.preload();
+			if (!warmStartPending) return collection.preload();
+			return warmStartPending.then(() => {
+				if (disposed) return;
+				return collection.preload();
+			});
 		},
-		cleanup() {
-			return collection.cleanup();
+		async cleanup() {
+			disposed = true;
+			await collection.cleanup();
+			for (const capability of capabilities) try {
+				await capability.teardown?.(ctx);
+			} catch (error) {
+				warnCapability(capability, "teardown", error);
+			}
 		},
 		subscribeChanges(callback) {
 			const subscription = collection.subscribeChanges((changes) => callback(projectChanges(changes)));
@@ -180,9 +1366,14 @@ function createSmrtCollection(definition, options) {
 		}
 	};
 	engineCollections.set(handle, collection);
+	for (const capability of capabilities) try {
+		capability.onAttach?.(ctx);
+	} catch (error) {
+		warnCapability(capability, "onAttach", error);
+	}
 	return handle;
 }
 //#endregion
-export { SmrtWebRequestError, createDefinitionFetchers, createSmrtCollection, createSmrtWebClient, getEngineCollection, newLocalId, unwrapItemResult, unwrapListResult };
+export { SmrtWebRequestError, createDefinitionFetchers, createSmrtCollection, createSmrtWebClient, createSmrtWebEventSubscriber, durableStoreNamespace, getEngineCollection, getOutboxHandle, liveInvalidation, newLocalId, offlineOutbox, registerDurableResource, runWrapMutation, unwrapItemResult, unwrapListResult, wipeDurableStore };
 
 //# sourceMappingURL=index.js.map