@happyvertical/smrt-web 0.51.27 → 0.51.29

package/dist/chunks/{src-0IQGhPIM.js → src-B2uQWayW.js}

@@ -372,6 +372,82 @@ async function executeSmrtWebDataSurfaceAction(transport, request, options) {
 	if (result.requestId !== request.requestId || result.actionId !== request.actionId || result.phase !== request.phase || !sameIdentity(result.identity, request.identity)) throw new TypeError("Data surface action result does not match its request");
 	return result;
 }
+var RETRYABLE_ACTION_REASONS = /* @__PURE__ */ new Set([
+	"idempotency_in_progress",
+	"background_unavailable",
+	"execution_failed"
+]);
+var AUTH_ACTION_REASONS = /* @__PURE__ */ new Set([
+	"auth_required",
+	"unauthenticated",
+	"unauthorized"
+]);
+var STALE_ACTION_REASONS = /* @__PURE__ */ new Set(["stale_revision", "stale_preview"]);
+var UNUSABLE_CONFIRMATION_REASONS = /* @__PURE__ */ new Set([
+	"invalid_or_expired_confirmation",
+	"confirmation_mismatch",
+	"confirmation_replayed",
+	"confirmation_required",
+	"stale_preview"
+]);
+function classifySmrtWebDataSurfaceActionResult(result) {
+	if (result.ok) return { status: "applied" };
+	const reason = result.reason ?? "rejected";
+	if (RETRYABLE_ACTION_REASONS.has(reason)) return {
+		status: "rejected",
+		reason: "write_failed"
+	};
+	if (AUTH_ACTION_REASONS.has(reason)) return {
+		status: "rejected",
+		reason: "auth_required"
+	};
+	if (STALE_ACTION_REASONS.has(reason)) return {
+		status: "conflict",
+		reason: "stale_write"
+	};
+	return {
+		status: "rejected",
+		reason
+	};
+}
+function dataSurfaceActionCommandTransport(options) {
+	const classify = options.classify ?? classifySmrtWebDataSurfaceActionResult;
+	return async (command) => {
+		let pinned = command.pinned;
+		if (pinned === void 0) {
+			pinned = { request: await options.request(command) };
+			await command.pin(pinned);
+		}
+		const base = pinned.request;
+		const requestId = (phase) => `${command.idempotencyKey}:${command.attempt}:${phase}`;
+		const apply = (confirmationToken) => executeSmrtWebDataSurfaceAction(options.transport, {
+			...base,
+			version: 1,
+			phase: "apply",
+			requestId: requestId("apply"),
+			idempotencyKey: command.idempotencyKey,
+			...confirmationToken === void 0 ? {} : { confirmationToken }
+		});
+		if (!options.preview) return classify(await apply(void 0));
+		if (pinned.confirmationToken !== void 0) {
+			const applied = await apply(pinned.confirmationToken);
+			if (applied.ok || !UNUSABLE_CONFIRMATION_REASONS.has(applied.reason ?? "")) return classify(applied);
+		}
+		const preview = await executeSmrtWebDataSurfaceAction(options.transport, {
+			...base,
+			version: 1,
+			phase: "preview",
+			requestId: requestId("preview")
+		});
+		if (!preview.ok) return classify(preview);
+		pinned = {
+			request: base,
+			...preview.confirmationToken === void 0 ? {} : { confirmationToken: preview.confirmationToken }
+		};
+		await command.pin(pinned);
+		return classify(await apply(preview.confirmationToken));
+	};
+}
 //#endregion
 //#region src/durable-store.ts
 function durableStoreNamespace(key) {
@@ -461,6 +537,7 @@ var DurableOutboxQueue = class {
 			id: input.id,
 			payload: input.payload,
 			baseUpdatedAt: input.baseUpdatedAt,
+			...input.transport === void 0 ? {} : { transport: input.transport },
 			state: "pending",
 			attempts: 0,
 			nextAttemptAt: 0,
@@ -626,6 +703,10 @@ function computeBackoffDelay(attempts, backoff, random = Math.random) {
 function envelopeKindToOp(kind) {
 	return kind === "insert" ? "create" : kind;
 }
+var SYNC_APPLY_ROUTE = "sync-apply";
+function routeOf(row) {
+	return row.transport === void 0 ? SYNC_APPLY_ROUTE : `transport:${row.transport}`;
+}
 function newItemId() {
 	const cryptoRef = globalThis.crypto;
 	if (cryptoRef?.randomUUID) return cryptoRef.randomUUID();
@@ -646,6 +727,12 @@ var OutboxEngine = class {
 	* collection per object, but the shared-engine model does not forbid more).
 	*/
 	listenersByObject = /* @__PURE__ */ new Map();
+	/**
+	* The sync-apply endpoint, adopted from the first binding that declares one.
+	* A tab without one never leads the sync-apply route, so its rows wait for a
+	* tab that does (never dropped) — see `drainOnce`.
+	*/
+	syncApply;
 	/** Ref count: number of collections currently attached to this engine. */
 	refCount = 0;
 	/** The durable queue, once opened. undefined while opening / if IDB absent. */
@@ -654,10 +741,12 @@ var OutboxEngine = class {
 	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;
+	/**
+	* Per-route leadership, requested when the first binding serving a route
+	* attaches and released when the last one detaches. Exactly one tab replays a
+	* given route; a tab never leads a route it has no binding for.
+	*/
+	leaders = /* @__PURE__ */ new Map();
 	/** Unregister fn from the durable-store registry. */
 	unregisterResource;
 	/** True once dispose() ran — guards late async continuations. */
@@ -668,8 +757,14 @@ var OutboxEngine = class {
 	* explicit retry wakes it. Items stay queued.
 	*/
 	paused = false;
+	/** Wipes issued but not yet cleared; replay is suspended meanwhile. */
+	wipesPending = 0;
+	/** Those wipes, so `dispose()` can let them finish before closing. */
+	pendingWipes = /* @__PURE__ */ new Set();
 	/** True while a drain pass is running, to coalesce concurrent triggers. */
 	draining = false;
+	/** The running drain, while `draining`. */
+	activeDrain;
 	/** A drain requested while one was in flight — run one more pass after. */
 	drainQueued = false;
 	/** Timer for the next backoff-scheduled drain, if any. */
@@ -679,8 +774,8 @@ var OutboxEngine = class {
 	constructor(config) {
 		this.config = config;
 		this.ready = this.open();
+		this.registerForWipe();
 		this.wireOnlineListener();
-		this.requestLeadership();
 		this.ready.then(() => {
 			if (!this.disposed) this.drain();
 		});
@@ -694,21 +789,39 @@ var OutboxEngine = class {
 		}
 		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);
 		}
 	}
+	/**
+	* Register the queue as a durable resource. A wipe drops the namespace's
+	* registrations, so the clear callback forgets ours and the next enqueue
+	* registers again — otherwise a second wipe would miss rows written after
+	* the first.
+	*/
+	registerForWipe() {
+		if (this.unregisterResource || this.disposed) return;
+		this.unregisterResource = this.config.registerResource(async () => {
+			this.unregisterResource = void 0;
+			this.wipesPending += 1;
+			const wipe = (async () => {
+				try {
+					await this.ready;
+					await this.queue?.clear();
+				} finally {
+					this.wipesPending -= 1;
+					if (!this.disposed) this.drain();
+				}
+			})();
+			this.pendingWipes.add(wipe);
+			try {
+				await wipe;
+			} finally {
+				this.pendingWipes.delete(wipe);
+			}
+		});
+	}
 	/** Wake the drain loop immediately when connectivity returns. */
 	wireOnlineListener() {
 		const target = globalThis;
@@ -719,16 +832,46 @@ var OutboxEngine = class {
 		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;
+	/**
+	* Request cross-tab leadership for `route` (ref-counted per tab). The
+	* sync-apply route keeps the pre-#3021 lock name, so it stays mutually
+	* exclusive with tabs running an older build; each transport route has its
+	* own lock.
+	*/
+	acquireRoute(route) {
+		const existing = this.leaders.get(route);
+		if (existing) {
+			existing.refs += 1;
+			return;
+		}
+		const root = `smrt-web-outbox-leader:${this.config.namespace}`;
+		const lockName = route === SYNC_APPLY_ROUTE ? root : `${root}:${route}`;
+		const entry = {
+			release: () => {},
+			isLeader: false,
+			refs: 1
+		};
+		this.leaders.set(route, entry);
+		entry.release = acquireLeadership(lockName, () => {
+			entry.isLeader = true;
 			this.drain();
 		}, () => {
-			this.isLeader = false;
+			entry.isLeader = false;
 		});
 	}
+	/** Drop one reference to `route`; the last one releases its lock. */
+	releaseRoute(route) {
+		const entry = this.leaders.get(route);
+		if (!entry) return;
+		entry.refs -= 1;
+		if (entry.refs > 0) return;
+		this.leaders.delete(route);
+		this.settled().then(() => entry.release());
+	}
+	/** Does this tab currently lead `route`? */
+	leads(route) {
+		return this.leaders.get(route)?.isLeader === true;
+	}
 	/**
 	* Attach a collection: register its per-object callbacks and bump the ref
 	* count. Returns the exact callback record registered so the caller can pass
@@ -739,9 +882,12 @@ var OutboxEngine = class {
 	*/
 	registerCollection(binding) {
 		this.refCount += 1;
+		const route = binding.transport ? routeOf({ transport: binding.object }) : binding.syncApply ? SYNC_APPLY_ROUTE : void 0;
 		const record = {
 			onSyncStateChange: binding.onSyncStateChange,
-			onConflict: binding.onConflict
+			onConflict: binding.onConflict,
+			transport: binding.transport,
+			route
 		};
 		let set = this.listenersByObject.get(binding.object);
 		if (!set) {
@@ -749,8 +895,16 @@ var OutboxEngine = class {
 			this.listenersByObject.set(binding.object, set);
 		}
 		set.add(record);
+		if (binding.syncApply && !this.syncApply) this.syncApply = binding.syncApply;
+		if (route && !this.disposed) this.acquireRoute(route);
 		return record;
 	}
+	/** The first live transport registered under `name`, if any. */
+	transportFor(name) {
+		const set = this.listenersByObject.get(name);
+		if (!set) return void 0;
+		for (const record of set) if (record.transport) return record.transport;
+	}
 	/**
 	* Detach a collection: remove its callback record and decrement the ref count;
 	* when it reaches zero, dispose the engine (release the lock, unregister from
@@ -760,9 +914,10 @@ var OutboxEngine = class {
 	*/
 	async unregisterCollection(object, record) {
 		const set = this.listenersByObject.get(object);
-		if (set) {
-			set.delete(record);
+		if (set?.delete(record)) {
 			if (set.size === 0) this.listenersByObject.delete(object);
+			const route = record.route;
+			if (route) this.releaseRoute(route);
 		}
 		this.refCount = Math.max(0, this.refCount - 1);
 		if (this.refCount > 0) return false;
@@ -788,20 +943,23 @@ var OutboxEngine = class {
 	async enqueue(request) {
 		await this.ready;
 		if (!this.queue || this.degraded) return void 0;
+		this.registerForWipe();
 		const itemId = newItemId();
 		const op = envelopeKindToOp(request.kind);
-		const payload = op === "delete" ? void 0 : request.data;
+		const rowId = request.rowId || itemId;
+		const payload = op === "delete" && request.transport === void 0 ? void 0 : request.data;
 		await this.queue.enqueue({
 			itemId,
 			object: request.object,
 			op,
-			id: request.rowId,
+			id: rowId,
 			payload,
-			baseUpdatedAt: request.baseUpdatedAt
+			baseUpdatedAt: request.baseUpdatedAt,
+			transport: request.transport
 		});
 		this.emit({
 			itemId,
-			rowId: request.rowId,
+			rowId,
 			object: request.object,
 			state: "pending",
 			attempts: 0
@@ -842,7 +1000,8 @@ var OutboxEngine = class {
 			state: row.state,
 			attempts: row.attempts,
 			nextAttemptAt: row.nextAttemptAt,
-			lastError: row.lastError
+			lastError: row.lastError,
+			...row.transport === void 0 ? {} : { transport: row.transport }
 		}));
 	}
 	/**
@@ -871,53 +1030,124 @@ var OutboxEngine = class {
 		}
 	}
 	/**
-	* The replay loop. Gated on: (a) holding leadership, (b) not paused by an
+	* The replay loop. Gated on: (a) leading at least one route, (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
+	* every led route's rows due now (`nextAttemptAt <= now`), oldest-first per
+	* route; sync-apply chunks into batches of ≤1000 per POST, one send at a time
+	* to preserve each route's FIFO. Concurrency-coalesced: a drain requested while one runs sets a flag
 	* to run exactly one more pass, so overlapping triggers never interleave.
 	*/
-	async drain() {
+	drain() {
 		if (this.draining) {
 			this.drainQueued = true;
-			return;
+			return this.activeDrain ?? Promise.resolve();
 		}
 		this.draining = true;
-		try {
-			for (;;) {
-				this.drainQueued = false;
-				await this.drainOnce();
-				if (!this.drainQueued) break;
+		this.activeDrain = (async () => {
+			try {
+				for (;;) {
+					this.drainQueued = false;
+					await this.drainOnce();
+					if (!this.drainQueued) break;
+				}
+			} finally {
+				this.draining = false;
+				this.activeDrain = void 0;
 			}
-		} finally {
-			this.draining = false;
-		}
+		})();
+		return this.activeDrain;
+	}
+	/**
+	* Settles once the drain in flight (if any) has finished its request AND its
+	* durable result transition. A route's lock is released only after this, so
+	* another tab can never replay a row this tab is still settling.
+	*/
+	settled() {
+		return (this.activeDrain ?? Promise.resolve()).catch(() => void 0);
 	}
 	/** One drain pass: send every currently-due batch, then schedule backoff. */
 	async drainOnce() {
 		if (this.disposed) return;
-		if (!this.isLeader) return;
+		if (this.wipesPending > 0) 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;
+		const byRoute = /* @__PURE__ */ new Map();
+		for (const row of await this.queue.all()) {
+			if (row.state !== "pending") continue;
+			const route = routeOf(row);
+			if (!this.leads(route)) continue;
+			const rows = byRoute.get(route);
+			if (rows) rows.push(row);
+			else byRoute.set(route, [row]);
 		}
-		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;
+		const now = Date.now();
+		for (const [route, rows] of byRoute) {
+			const firstBlocked = rows.findIndex((row) => row.nextAttemptAt > now);
+			const due = firstBlocked === -1 ? rows : rows.slice(0, firstBlocked);
+			if (route === SYNC_APPLY_ROUTE) {
+				const syncApply = this.syncApply;
+				if (!syncApply) continue;
+				for (let i = 0; i < due.length; i += MAX_SYNC_APPLY_BATCH_SIZE) {
+					if (this.disposed || this.paused || !this.leads(route)) break;
+					const chunk = due.slice(i, i + MAX_SYNC_APPLY_BATCH_SIZE);
+					if (!await this.sendBatch(chunk, syncApply)) break;
+				}
+			} else for (const row of due) {
+				if (this.disposed || this.paused || !this.leads(route)) break;
+				const transport = this.transportFor(row.transport ?? row.object);
+				if (!transport) break;
+				if (!await this.sendCommand(row, transport)) break;
+			}
+			if (this.disposed || this.paused) return;
 		}
 		await this.scheduleNextBackoff();
 	}
 	/**
+	* Replay one transport row through its consumer-declared transport (#3021)
+	* and map the outcome through the SAME transitions as a sync-apply result. A
+	* throw is the ambiguous path (request may or may not have landed): the row
+	* stays `pending` with backoff and is resent under the same idempotency key.
+	* Returns false when the row remains pending, stopping this route's pass
+	* (FIFO per route).
+	*/
+	async sendCommand(row, transport) {
+		this.emit({
+			itemId: row.itemId,
+			rowId: row.id,
+			object: row.object,
+			state: "uploading",
+			attempts: row.attempts
+		});
+		let outcome;
+		try {
+			outcome = await transport({
+				idempotencyKey: row.itemId,
+				name: row.transport ?? row.object,
+				op: row.op,
+				rowId: row.id,
+				...row.payload === void 0 ? {} : { payload: row.payload },
+				...row.baseUpdatedAt === void 0 ? {} : { baseUpdatedAt: row.baseUpdatedAt },
+				attempt: row.attempts + 1,
+				...row.pinned === void 0 ? {} : { pinned: row.pinned },
+				pin: async (value) => {
+					if (row.seq === void 0 || !this.queue) throw new Error("[smrt-web] outbox row is no longer queued");
+					await this.queue.markState(row.seq, { pinned: value });
+					row.pinned = value;
+				}
+			});
+		} catch {
+			await this.requeueRow(row, "network error during command replay");
+			return false;
+		}
+		const result = commandResultToApplyResult(row, outcome);
+		if (!result) {
+			await this.requeueRow(row, "unexpected command result shape");
+			return false;
+		}
+		return this.applyResult(row, result);
+	}
+	/**
 	* 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
@@ -925,7 +1155,7 @@ var OutboxEngine = class {
 	* 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) {
+	async sendBatch(chunk, syncApply) {
 		for (const row of chunk) this.emit({
 			itemId: row.itemId,
 			rowId: row.id,
@@ -943,7 +1173,7 @@ var OutboxEngine = class {
 		}));
 		let results;
 		try {
-			results = await this.postBatch(items);
+			results = await this.postBatch(items, syncApply);
 		} catch {
 			await this.requeueBatch(chunk, "network error during sync");
 			return false;
@@ -971,9 +1201,9 @@ var OutboxEngine = class {
 	* 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, {
+	async postBatch(items, syncApply) {
+		const url = `${syncApply.basePath}/${SYNC_APPLY_ROUTE_SEGMENTS.join("/")}`;
+		const response = await syncApply.fetchFn(url, {
 			method: "POST",
 			headers: { "Content-Type": "application/json" },
 			body: JSON.stringify({ items })
@@ -1079,10 +1309,18 @@ var OutboxEngine = class {
 	*/
 	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);
+		let nextAt;
+		const seen = /* @__PURE__ */ new Set();
+		for (const row of await this.queue.all()) {
+			if (row.state !== "pending") continue;
+			const route = routeOf(row);
+			if (seen.has(route)) continue;
+			seen.add(route);
+			if (!this.leads(route)) continue;
+			nextAt = nextAt === void 0 ? row.nextAttemptAt : Math.min(nextAt, row.nextAttemptAt);
+		}
+		if (nextAt === void 0) return;
+		const delay = Math.max(0, nextAt - Date.now());
 		if (this.backoffTimer) clearTimeout(this.backoffTimer);
 		const timers = globalThis;
 		if (typeof timers.setTimeout !== "function") return;
@@ -1110,11 +1348,14 @@ var OutboxEngine = class {
 			target.removeEventListener("online", this.onlineListener);
 			this.onlineListener = void 0;
 		}
-		this.leadership?.();
-		this.leadership = void 0;
+		const leaders = [...this.leaders.values()];
+		this.leaders.clear();
+		await this.settled();
+		for (const entry of leaders) entry.release();
 		this.unregisterResource?.();
 		this.unregisterResource = void 0;
 		await this.ready.catch(() => void 0);
+		await Promise.allSettled([...this.pendingWipes]);
 		this.queue?.close();
 		this.queue = void 0;
 		this.listenersByObject.clear();
@@ -1129,6 +1370,29 @@ function getOrCreateOutboxEngine(config) {
 	}
 	return engine;
 }
+function commandResultToApplyResult(row, outcome) {
+	if (!outcome || typeof outcome !== "object") return void 0;
+	const { status, reason, updatedAt } = outcome;
+	const base = {
+		itemId: row.itemId,
+		id: row.id,
+		...typeof updatedAt === "string" ? { updatedAt } : {}
+	};
+	if (status === "applied") return {
+		...base,
+		status
+	};
+	if (status === "conflict") return {
+		...base,
+		status,
+		reason: reason === "create_conflict" ? "create_conflict" : "stale_write"
+	};
+	if (status === "rejected" && typeof reason === "string" && reason) return {
+		...base,
+		status,
+		reason
+	};
+}
 function acquireOutboxEngine(config, binding) {
 	const engine = getOrCreateOutboxEngine(config);
 	return {
@@ -1149,6 +1413,11 @@ function resolveBackoff(backoff) {
 	};
 }
 var handlesByNamespace = /* @__PURE__ */ new Map();
+async function releaseBinding(namespace, engine, object, record) {
+	const before = engine.referenceCount;
+	await releaseOutboxEngine(namespace, engine, object, record);
+	if (before <= 1 && handlesByNamespace.get(namespace) === engine) handlesByNamespace.delete(namespace);
+}
 function getPayloadUpdatedAt(data) {
 	const value = data.updatedAt ?? data.updated_at;
 	if (typeof value === "string") return value;
@@ -1159,6 +1428,7 @@ function offlineOutbox(config) {
 	const syncApplyBasePath = config.syncApplyBasePath ?? "/api/v1";
 	const fetchFn = config.fetchFn ?? ((...args) => globalThis.fetch(...args));
 	const backoff = resolveBackoff(config.backoff);
+	const transport = config.transport;
 	const object = config.object.name;
 	let engine;
 	let record;
@@ -1167,8 +1437,6 @@ function offlineOutbox(config) {
 		onAttach() {
 			const acquired = acquireOutboxEngine({
 				namespace,
-				syncApplyBasePath,
-				fetchFn,
 				backoff,
 				random: config.random,
 				registerResource: (clear) => registerDurableResource(namespace, {
@@ -1178,7 +1446,11 @@ function offlineOutbox(config) {
 			}, {
 				object,
 				onSyncStateChange: config.onSyncStateChange,
-				onConflict: config.onConflict
+				onConflict: config.onConflict,
+				...transport ? { transport } : { syncApply: {
+					basePath: syncApplyBasePath,
+					fetchFn
+				} }
 			});
 			engine = acquired.engine;
 			record = acquired.record;
@@ -1191,7 +1463,8 @@ function offlineOutbox(config) {
 				object,
 				rowId: envelope.key,
 				data: envelope.data,
-				baseUpdatedAt: envelope.baseUpdatedAt ?? getPayloadUpdatedAt(envelope.data)
+				baseUpdatedAt: envelope.baseUpdatedAt ?? getPayloadUpdatedAt(envelope.data),
+				...transport ? { transport: object } : {}
 			})) return { handled: false };
 			return {
 				handled: true,
@@ -1204,9 +1477,53 @@ function offlineOutbox(config) {
 			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);
+			await releaseBinding(namespace, current, object, currentRecord);
+		}
+	};
+}
+function offlineCommandQueue(config) {
+	if (typeof config.name !== "string" || config.name.length === 0) throw new TypeError("offlineCommandQueue requires a non-empty name");
+	if (typeof config.transport !== "function") throw new TypeError("offlineCommandQueue requires a transport function");
+	const namespace = durableStoreNamespace(config.namespace);
+	const name = config.name;
+	const acquired = acquireOutboxEngine({
+		namespace,
+		backoff: resolveBackoff(config.backoff),
+		random: config.random,
+		registerResource: (clear) => registerDurableResource(namespace, {
+			kind: "outbox",
+			clear
+		})
+	}, {
+		object: name,
+		transport: config.transport,
+		onSyncStateChange: config.onSyncStateChange,
+		onConflict: config.onConflict
+	});
+	let engine = acquired.engine;
+	const record = acquired.record;
+	handlesByNamespace.set(namespace, engine);
+	return {
+		async enqueue(input) {
+			if (!engine) return void 0;
+			return engine.enqueue({
+				kind: input.op === "create" || input.op === void 0 ? "insert" : input.op,
+				object: name,
+				rowId: input.rowId ?? "",
+				data: input.payload ?? {},
+				baseUpdatedAt: input.baseUpdatedAt,
+				transport: name
+			});
+		},
+		snapshot: async () => engine ? engine.snapshot() : [],
+		retry: async (itemId) => {
+			await engine?.retry(itemId);
+		},
+		async dispose() {
+			const current = engine;
+			if (!current) return;
+			engine = void 0;
+			await releaseBinding(namespace, current, name, record);
 		}
 	};
 }
@@ -1331,6 +1648,17 @@ function openSnapshotStore(namespace) {
 //#endregion
 //#region src/persistence.ts
 var DEFAULT_PERSIST_DEBOUNCE_MS = 250;
+function registerForWipe(engine, namespace) {
+	if (engine.unregister) return;
+	engine.unregister = registerDurableResource(namespace, {
+		kind: "persisted-collection",
+		clear: async () => {
+			engine.wipeEpoch += 1;
+			engine.unregister = void 0;
+			await (await engine.ready)?.clear();
+		}
+	});
+}
 var enginesByNamespace = /* @__PURE__ */ new Map();
 var warnedNoIndexedDb = false;
 function warnNoIndexedDbOnce() {
@@ -1342,13 +1670,15 @@ function acquireSnapshotEngine(namespace) {
 	const existing = enginesByNamespace.get(namespace);
 	if (existing) {
 		existing.refCount += 1;
+		registerForWipe(existing, namespace);
 		return existing;
 	}
 	const engine = {
 		store: void 0,
 		refCount: 1,
 		unregister: void 0,
-		ready: Promise.resolve(void 0)
+		ready: Promise.resolve(void 0),
+		wipeEpoch: 0
 	};
 	engine.ready = (async () => {
 		if (!await probeIndexedDb()) {
@@ -1358,10 +1688,6 @@ function acquireSnapshotEngine(namespace) {
 		try {
 			const store = await openSnapshotStore(namespace);
 			engine.store = store;
-			engine.unregister = registerDurableResource(namespace, {
-				kind: "persisted-collection",
-				clear: () => store.clear()
-			});
 			return store;
 		} catch {
 			warnNoIndexedDbOnce();
@@ -1369,6 +1695,7 @@ function acquireSnapshotEngine(namespace) {
 		}
 	})();
 	enginesByNamespace.set(namespace, engine);
+	registerForWipe(engine, namespace);
 	return engine;
 }
 async function releaseSnapshotEngine(namespace) {
@@ -1458,6 +1785,74 @@ function persistCollection(config) {
 		}
 	};
 }
+function dataSurfaceSnapshotKey(identity) {
+	if (!identity || typeof identity.surfaceId !== "string" || identity.surfaceId.length === 0 || typeof identity.kind !== "string") throw new TypeError("persistDataSurface requires an identity with a surfaceId and kind");
+	return `data-surface:${JSON.stringify([
+		identity.kind,
+		identity.surfaceId,
+		identity.subject?.type ?? null,
+		identity.subject?.id ?? null
+	])}`;
+}
+function persistDataSurface(config) {
+	const namespace = durableStoreNamespace(config.namespace);
+	const key = dataSurfaceSnapshotKey(config.identity);
+	const debounceMs = config.debounceMs ?? 250;
+	let engine = acquireSnapshotEngine(namespace);
+	const bornEpoch = engine.wipeEpoch;
+	const wiped = (current) => current.wipeEpoch !== bornEpoch;
+	let pending;
+	let timer;
+	let writing = Promise.resolve();
+	const writePending = () => {
+		if (timer) {
+			clearTimeout(timer);
+			timer = void 0;
+		}
+		const rows = pending;
+		pending = void 0;
+		const current = engine;
+		if (!rows || !current) return writing;
+		writing = writing.then(async () => {
+			const store = await current.ready;
+			if (!store || wiped(current)) return;
+			try {
+				await store.save(key, rows);
+			} catch {}
+		});
+		return writing;
+	};
+	return {
+		async load() {
+			const current = engine;
+			if (!current) return void 0;
+			const store = await current.ready;
+			if (!store || wiped(current)) return void 0;
+			const rows = await store.load(key);
+			if (!rows || rows.length === 0) return void 0;
+			return rows;
+		},
+		save(rows) {
+			if (!engine) return;
+			if (!Array.isArray(rows)) throw new TypeError("persistDataSurface.save requires an array of rows");
+			if (wiped(engine)) return;
+			pending = rows.map((row) => ({ ...row }));
+			if (timer) clearTimeout(timer);
+			timer = setTimeout(() => {
+				timer = void 0;
+				writePending();
+			}, Math.max(0, debounceMs));
+			timer.unref?.();
+		},
+		flush: () => writePending(),
+		async dispose() {
+			if (!engine) return;
+			await writePending();
+			engine = void 0;
+			await releaseSnapshotEngine(namespace);
+		}
+	};
+}
 //#endregion
 //#region src/remote-query.ts
 function canonicalize(value) {
@@ -3151,6 +3546,6 @@ function createSmrtCollection(definition, options) {
 	return handle;
 }
 //#endregion
-export { MAX_SMRT_WEB_DATA_SURFACE_ACTION_RESULT_BYTES as A, MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH as B, offlineOutbox as C, MAX_SMRT_WEB_DATA_SURFACE_ACTION_CONTAINER_ITEMS as D, wipeDurableStore as E, MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES as F, executeSmrtWebDataQuery as H, MAX_SMRT_WEB_DATA_QUERY_OFFSET as I, MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT as L, normalizeSmrtWebDataSurfaceActionResult as M, MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS as N, MAX_SMRT_WEB_DATA_SURFACE_ACTION_IDENTIFIER_LENGTH as O, MAX_SMRT_WEB_DATA_QUERY_FACETS as P, MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES as R, getOutboxHandle as S, registerDurableResource as T, normalizeSmrtWebDataQueryResult as U, MAX_SMRT_WEB_DATA_QUERY_WARNINGS as V, runWrapMutation as W, createSmrtWebEventSubscriber as _, createSmrtWebClient as a, DEFAULT_PERSIST_DEBOUNCE_MS as b, newLocalId as c, unwrapListResult as d, validateSmrtWebClient as f, createUpdateState as g, registerWebMcpTools as h, createSmrtCollection as i, executeSmrtWebDataSurfaceAction as j, MAX_SMRT_WEB_DATA_SURFACE_ACTION_JSON_DEPTH as k, throwIfSmrtWebError as l, registerWebMcpBespokeTool as m, buildListQuery as n, getEngineCollection as o, registerViewIntent as p, createDefinitionFetchers as r, invalidateSmrtWebCollections as s, SmrtWebRequestError as t, unwrapItemResult as u, liveInvalidation as v, durableStoreNamespace as w, persistCollection as x, createSmrtWebQuery as y, MAX_SMRT_WEB_DATA_QUERY_ROWS as z };
+export { MAX_SMRT_WEB_DATA_SURFACE_ACTION_IDENTIFIER_LENGTH as A, MAX_SMRT_WEB_DATA_QUERY_OFFSET as B, getOutboxHandle as C, registerDurableResource as D, durableStoreNamespace as E, executeSmrtWebDataSurfaceAction as F, MAX_SMRT_WEB_DATA_QUERY_WARNINGS as G, MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES as H, normalizeSmrtWebDataSurfaceActionResult as I, runWrapMutation as J, executeSmrtWebDataQuery as K, MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS as L, MAX_SMRT_WEB_DATA_SURFACE_ACTION_RESULT_BYTES as M, classifySmrtWebDataSurfaceActionResult as N, wipeDurableStore as O, dataSurfaceActionCommandTransport as P, MAX_SMRT_WEB_DATA_QUERY_FACETS as R, persistDataSurface as S, offlineOutbox as T, MAX_SMRT_WEB_DATA_QUERY_ROWS as U, MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT as V, MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH as W, createSmrtWebEventSubscriber as _, createSmrtWebClient as a, DEFAULT_PERSIST_DEBOUNCE_MS as b, newLocalId as c, unwrapListResult as d, validateSmrtWebClient as f, createUpdateState as g, registerWebMcpTools as h, createSmrtCollection as i, MAX_SMRT_WEB_DATA_SURFACE_ACTION_JSON_DEPTH as j, MAX_SMRT_WEB_DATA_SURFACE_ACTION_CONTAINER_ITEMS as k, throwIfSmrtWebError as l, registerWebMcpBespokeTool as m, buildListQuery as n, getEngineCollection as o, registerViewIntent as p, normalizeSmrtWebDataQueryResult as q, createDefinitionFetchers as r, invalidateSmrtWebCollections as s, SmrtWebRequestError as t, unwrapItemResult as u, liveInvalidation as v, offlineCommandQueue as w, persistCollection as x, createSmrtWebQuery as y, MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES as z };
 
-//# sourceMappingURL=src-0IQGhPIM.js.map
+//# sourceMappingURL=src-B2uQWayW.js.map