@rebasepro/client 0.22.0 → 0.23.0

package/dist/index.es.js

@@ -1,5 +1,5 @@
 import { DEFAULT_STORAGE_SOURCE_KEY, EntityReference, EntityRelation, GeoPoint, PUBLIC_STORAGE_PREFIX, RebaseApiError, RebaseApiError as RebaseApiError$1, RebaseClientError, RebaseClientError as RebaseClientError$1, SCHEMA_VERSION_HEADER, Vector, hasFieldOperation, isPublicStoragePath, isUnsupported, parseRelationAggregateSort, sortKeyToString, toCanonicalOp, unsupportedMethod } from "@rebasepro/types";
-import { COMPOSITE_ID_SEPARATOR, QueryBuilder, RebasePaginationError, and, buildCompositeId, collectAllPages, cond, mergeIncludeSpecs, normalizeOrderBy, not, or, paginateFind, resolveFindWindow, serializeFilter, serializeInclude, serializeLogicalCondition, serializeOrderBy } from "@rebasepro/common";
+import { COMPOSITE_ID_SEPARATOR, QueryBuilder, RESERVED_QUERY_KEYS, RebasePaginationError, and, buildCompositeId, collectAllPages, cond, mergeIncludeSpecs, normalizeOrderBy, not, or, paginateFind, resolveFindWindow, serializeFilter, serializeInclude, serializeLogicalCondition, serializeOrderBy } from "@rebasepro/common";
 import { splitSearchTerms, toSnakeCase, unref } from "@rebasepro/utils";
 //#region src/reviver.ts
 function rebaseReviver(_key, value) {
@@ -118,13 +118,33 @@ function buildQueryString(params) {
 		const serialized = (root.conditions ?? []).map(serializeLogicalCondition).join(",");
 		parts.push(`${root.type}=${encodeURIComponent(`(${serialized})`)}`);
 	}
-	if (params.where) {
-		assertNoUndefinedFilterValues(params.where);
-		const serialized = serializeFilter(params.where);
-		for (const [field, value] of Object.entries(serialized)) if (Array.isArray(value)) for (const v of value) parts.push(`${encodeURIComponent(field)}=${encodeURIComponent(v)}`);
+	if (params.where) appendWhere(parts, params.where);
+	return parts.length > 0 ? "?" + parts.join("&") : "";
+}
+/**
+* Append a `where` to a query string, one `?<field>=<op>.<value>` parameter per
+* condition.
+*
+* Except on a column whose name the server reads as a parameter of its own —
+* `page`, `select`, `hard`, `where` ({@link RESERVED_QUERY_KEYS}). A filter on
+* such a column sent as its own parameter is read as that parameter, and the
+* filter is never applied. Those conditions go inside `?where=` instead, in the
+* same dot-string spelling, which the server decodes through the same codec and
+* merges in. A collection with no such column sends exactly what it did before.
+*/
+function appendWhere(parts, where) {
+	assertNoUndefinedFilterValues(where);
+	const serialized = serializeFilter(where);
+	const reserved = {};
+	for (const [field, value] of Object.entries(serialized)) {
+		if (RESERVED_QUERY_KEYS.has(field)) {
+			reserved[field] = value;
+			continue;
+		}
+		if (Array.isArray(value)) for (const v of value) parts.push(`${encodeURIComponent(field)}=${encodeURIComponent(v)}`);
 		else parts.push(`${encodeURIComponent(field)}=${encodeURIComponent(value)}`);
 	}
-	return parts.length > 0 ? "?" + parts.join("&") : "";
+	if (Object.keys(reserved).length > 0) parts.push(`where=${encodeURIComponent(JSON.stringify(reserved))}`);
 }
 /**
 * The query string for `GET /<collection>/aggregate`.
@@ -151,12 +171,7 @@ function buildAggregateQueryString(params) {
 		const serialized = (root.conditions ?? []).map(serializeLogicalCondition).join(",");
 		parts.push(`${root.type}=${encodeURIComponent(`(${serialized})`)}`);
 	}
-	if (params.where) {
-		assertNoUndefinedFilterValues(params.where);
-		const serialized = serializeFilter(params.where);
-		for (const [field, value] of Object.entries(serialized)) if (Array.isArray(value)) for (const v of value) parts.push(`${encodeURIComponent(field)}=${encodeURIComponent(v)}`);
-		else parts.push(`${encodeURIComponent(field)}=${encodeURIComponent(value)}`);
-	}
+	if (params.where) appendWhere(parts, params.where);
 	return "?" + parts.join("&");
 }
 /**
@@ -251,12 +266,14 @@ function createTransport(config, environment) {
 		...config.schemaVersion ? { [SCHEMA_VERSION_HEADER]: config.schemaVersion } : {}
 	};
 	function getHeaders(activeToken, init) {
-		return {
+		const headers = {
 			"Content-Type": "application/json",
 			...defaultHeaders,
 			...activeToken ? { Authorization: `Bearer ${activeToken}` } : {},
 			...init?.headers || {}
 		};
+		if (init?.body instanceof FormData) delete headers["Content-Type"];
+		return headers;
 	}
 	/**
 	* The refusal for a success status carrying a body this client cannot read.
@@ -330,7 +347,6 @@ function createTransport(config, environment) {
 		} catch (e) {}
 		warnIfAnonymousServerClient(activeToken);
 		const headers = getHeaders(activeToken, init);
-		if (init?.body instanceof FormData) delete headers["Content-Type"];
 		const res = await fetchFn(url, {
 			...init,
 			headers
@@ -505,9 +521,22 @@ function createAuth(transport, options) {
 	const REFRESH_RETRY_BASE_MS = 1e3;
 	const REFRESH_RETRY_MAX_MS = 3e4;
 	let currentSession = null;
+	/**
+	* Which sign-in `currentSession` belongs to. Bumped whenever the session
+	* is replaced by anything other than its own refresh — a sign-in, a
+	* sign-out, a revocation, a local abandon — so a refresh already in flight
+	* can tell, when its answer lands, that the session it was refreshing has
+	* ended. Its answer is then dropped: adopting it put a signed-out session
+	* back in memory, in storage and on the transport, announced
+	* TOKEN_REFRESHED after SIGNED_OUT, and overwrote whoever had signed in
+	* since.
+	*/
+	let sessionEpoch = 0;
 	const listeners = /* @__PURE__ */ new Set();
 	let refreshTimeout = null;
 	let inFlightRefresh = null;
+	/** The `sessionEpoch` the in-flight refresh was started for. */
+	let inFlightEpoch = -1;
 	let resolveInitialized;
 	const isInitialized = new Promise((resolve) => {
 		resolveInitialized = resolve;
@@ -569,10 +598,25 @@ function createAuth(transport, options) {
 	* may be stale precisely because a sibling tab holds a live one, and
 	* logging out on its behalf would turn one tab's bad luck into everybody
 	* being signed out — the exact failure this work exists to remove.
+	*
+	* Storage is left alone when it no longer holds the session being
+	* abandoned. It is shared with every other tab of the app, so a different
+	* session there is a sibling's live one — a rotation this tab missed, or
+	* another sign-in — and deleting it signed that tab out on its next load.
 	*/
 	function abandonSessionLocally() {
+		endSession(storageHoldsCurrentSession());
+	}
+	/** Whether storage holds this client's session — or no session at all. */
+	function storageHoldsCurrentSession() {
+		const persisted = loadStoredSession();
+		return !persisted || !currentSession || persisted.refreshToken === currentSession.refreshToken;
+	}
+	/** Drop the session from memory, storage and the transport, and say so. */
+	function endSession(clearStorage = true) {
+		sessionEpoch++;
 		currentSession = null;
-		clearStoredSession();
+		if (clearStorage) clearStoredSession();
 		if (refreshTimeout) {
 			clearTimeout(refreshTimeout);
 			refreshTimeout = null;
@@ -600,32 +644,39 @@ function createAuth(transport, options) {
 			abandonSessionLocally();
 			return false;
 		}
+		const epoch = sessionEpoch;
 		try {
 			await refreshSession();
-			return true;
+			return epoch === sessionEpoch;
 		} catch (err) {
-			if (isFatalRefreshError(err)) abandonSessionLocally();
+			if (epoch === sessionEpoch && isFatalRefreshError(err)) abandonSessionLocally();
 			return false;
 		}
 	}
 	async function attemptScheduledRefresh(attempt) {
+		const epoch = sessionEpoch;
 		try {
 			await refreshSession();
 		} catch (err) {
+			if (epoch !== sessionEpoch) return;
 			if (isFatalRefreshError(err)) {
 				abandonSessionLocally();
 				return;
 			}
 			if (attempt >= MAX_REFRESH_RETRIES) {
-				abandonSessionLocally();
+				if (err instanceof RebaseApiError && (err.status === 401 || err.status === 403)) abandonSessionLocally();
 				return;
 			}
-			const backoff = Math.min(REFRESH_RETRY_BASE_MS * 2 ** attempt, REFRESH_RETRY_MAX_MS);
-			refreshTimeout = setTimeout(() => {
-				attemptScheduledRefresh(attempt + 1);
-			}, backoff);
+			scheduleRetry(attempt);
 		}
 	}
+	/** Try the scheduled refresh again after a backoff: 1s, 2s, 4s, … capped. */
+	function scheduleRetry(attempt) {
+		const backoff = Math.min(REFRESH_RETRY_BASE_MS * 2 ** attempt, REFRESH_RETRY_MAX_MS);
+		refreshTimeout = setTimeout(() => {
+			attemptScheduledRefresh(attempt + 1);
+		}, backoff);
+	}
 	function scheduleRefresh(expiresAt) {
 		if (refreshTimeout) clearTimeout(refreshTimeout);
 		if (!autoRefresh) return;
@@ -666,6 +717,7 @@ function createAuth(transport, options) {
 		}
 	}
 	function handleAuthResponse(data, event) {
+		sessionEpoch++;
 		const user = mapRawUser(data.user);
 		const session = {
 			accessToken: data.tokens.accessToken,
@@ -847,6 +899,7 @@ function createAuth(transport, options) {
 		});
 	}
 	async function signOut() {
+		sessionEpoch++;
 		const fetchFn = getFetch();
 		try {
 			if (authFlowMode === "cookie" || currentSession?.refreshToken) await fetchFn(authUrl("/logout"), {
@@ -856,14 +909,7 @@ function createAuth(transport, options) {
 				credentials: authFlowMode === "cookie" ? "include" : void 0
 			});
 		} catch (e) {}
-		currentSession = null;
-		clearStoredSession();
-		if (refreshTimeout) {
-			clearTimeout(refreshTimeout);
-			refreshTimeout = null;
-		}
-		transport.setToken(null);
-		emit("SIGNED_OUT", null);
+		endSession();
 	}
 	/**
 	* Serialise refreshes across TABS, not just within one.
@@ -899,13 +945,85 @@ function createAuth(transport, options) {
 		}
 	}
 	function refreshSession() {
-		if (inFlightRefresh) return inFlightRefresh;
-		inFlightRefresh = withRefreshLock(() => doRefreshSession()).finally(() => {
-			inFlightRefresh = null;
+		if (inFlightRefresh && inFlightEpoch === sessionEpoch) return inFlightRefresh;
+		const refresh = withRefreshLock(() => doRefreshSession()).finally(() => {
+			if (inFlightRefresh === refresh) inFlightRefresh = null;
 		});
-		return inFlightRefresh;
+		inFlightRefresh = refresh;
+		inFlightEpoch = sessionEpoch;
+		return refresh;
+	}
+	/**
+	* What a refresh answers when its session ended while it was in flight.
+	*
+	* The tokens it received belong to a session this client no longer holds,
+	* so they are dropped, and so is any error it hit: a refusal of the old
+	* session's token says nothing about the new one, and acting on it signed
+	* out whoever had signed in since. The caller gets the session there is
+	* now — or, if there is none, is told so.
+	*/
+	function supersededRefresh() {
+		if (currentSession) return currentSession;
+		throw new RebaseClientError$1("The session was signed out while it was being refreshed.", { code: "NOT_SIGNED_IN" });
+	}
+	/**
+	* The session a sibling tab has persisted since this one last looked, when
+	* it continues this one.
+	*
+	* Tabs of one app share `localStorage` but each holds its session in
+	* memory, and a refresh rotates the refresh token. Once one tab has
+	* refreshed, every other tab is holding a token the server has already
+	* superseded: presented after the server's reuse window it is refused
+	* with TOKEN_ALREADY_USED, again on every retry, until the tab gives up
+	* and signs out. Its replacement was in storage all along.
+	*
+	* Only a session of the same user counts. A different user in storage
+	* means another tab signed someone else in, and that is not this tab's
+	* session to take over.
+	*/
+	function siblingSession() {
+		if (!persistSession || authFlowMode === "cookie" || !currentSession) return null;
+		const persisted = loadStoredSession();
+		if (!persisted?.accessToken || !persisted.refreshToken) return null;
+		if (persisted.refreshToken === currentSession.refreshToken) return null;
+		if (!persisted.user?.uid || persisted.user.uid !== currentSession.user?.uid) return null;
+		return persisted;
+	}
+	/**
+	* Take over a sibling's session. Its access token is used as it is while
+	* it has time left — exactly as a session restored on load would be — and
+	* otherwise this answers `null` and the caller refreshes, now with the
+	* sibling's refresh token rather than the superseded one.
+	*/
+	function adoptSibling(sibling) {
+		currentSession = sibling;
+		if (sibling.expiresAt - REFRESH_BUFFER_MS <= Date.now()) return null;
+		transport.setToken(sibling.accessToken);
+		scheduleRefresh(sibling.expiresAt);
+		emit("TOKEN_REFRESHED", sibling);
+		return sibling;
 	}
 	async function doRefreshSession() {
+		const epoch = sessionEpoch;
+		try {
+			const sibling = siblingSession();
+			if (sibling) {
+				const adopted = adoptSibling(sibling);
+				if (adopted) return adopted;
+			}
+			try {
+				return await requestRefresh(epoch);
+			} catch (err) {
+				const late = epoch === sessionEpoch && err instanceof RebaseApiError && err.code === "TOKEN_ALREADY_USED" ? siblingSession() : null;
+				if (!late) throw err;
+				return adoptSibling(late) ?? await requestRefresh(epoch);
+			}
+		} catch (err) {
+			if (epoch !== sessionEpoch) return supersededRefresh();
+			throw err;
+		}
+	}
+	async function requestRefresh(epoch) {
 		if (authFlowMode !== "cookie" && !currentSession?.refreshToken) throw new RebaseClientError$1("No active session to refresh. Sign in first, or set `authFlowMode: \"cookie\"` if the refresh token is held in an HttpOnly cookie.", { code: "NOT_SIGNED_IN" });
 		const res = await getFetch()(authUrl("/refresh"), {
 			method: "POST",
@@ -914,14 +1032,18 @@ function createAuth(transport, options) {
 			credentials: authFlowMode === "cookie" ? "include" : void 0
 		});
 		const body = await res.json().catch(() => ({}));
+		if (epoch !== sessionEpoch) return supersededRefresh();
 		if (!res.ok) throwApiError(res.status, body, res.statusText);
 		const accessToken = body.tokens.accessToken;
 		transport.setToken(accessToken);
 		let user = currentSession?.user;
 		if (body.user && typeof body.user.uid === "string") user = mapRawUser(body.user);
-		else if (!user || !user.uid) try {
-			user = await getUser();
-		} catch {}
+		else if (!user || !user.uid) {
+			try {
+				user = await getUser();
+			} catch {}
+			if (epoch !== sessionEpoch) return supersededRefresh();
+		}
 		const session = {
 			accessToken,
 			refreshToken: body.tokens.refreshToken || currentSession?.refreshToken || "",
@@ -1203,27 +1325,38 @@ function createAuth(transport, options) {
 				body: JSON.stringify({ factorId })
 			});
 		},
-		/** Open a challenge against a verified factor. Expires in five minutes. */
-		async challenge(factorId) {
+		/**
+		* Open a challenge against a verified factor. Expires in five minutes.
+		*
+		* Pass `mfaToken` to finish a sign-in that was refused with
+		* `MFA_REQUIRED`: it is the `details.mfaToken` of that refusal, and the
+		* challenge is opened with it as this one request's credential. Without
+		* it, the challenge steps up the session this client already holds.
+		*/
+		async challenge(factorId, options) {
+			const payload = JSON.stringify({ factorId });
+			if (options?.mfaToken) return withPendingToken("/mfa/challenge", payload, options.mfaToken);
 			return transport.request(authPath + "/mfa/challenge", {
 				method: "POST",
-				body: JSON.stringify({ factorId })
+				body: payload
 			});
 		},
 		/**
 		* Answer a challenge with a TOTP code or a recovery code.
 		*
 		* This is where an MFA-enrolled account's real session is minted, at
-		* `aal2` — so the returned tokens replace the ones the sign-in handed
-		* back, and this client adopts them.
+		* `aal2` — so this client adopts the returned tokens and announces
+		* `SIGNED_IN`, exactly as any other sign-in does. Pass the same
+		* `mfaToken` the challenge was opened with when finishing a sign-in.
 		*/
-		async verifyChallenge(challengeId, code) {
-			const session = handleAuthResponse(await transport.request(authPath + "/mfa/challenge/verify", {
+		async verifyChallenge(challengeId, code, options) {
+			const payload = JSON.stringify({
+				challengeId,
+				code
+			});
+			const session = handleAuthResponse(options?.mfaToken ? await withPendingToken("/mfa/challenge/verify", payload, options.mfaToken) : await transport.request(authPath + "/mfa/challenge/verify", {
 				method: "POST",
-				body: JSON.stringify({
-					challengeId,
-					code
-				})
+				body: payload
 			}), "SIGNED_IN");
 			return {
 				user: session.user,
@@ -1232,6 +1365,31 @@ function createAuth(transport, options) {
 			};
 		}
 	};
+	/**
+	* POST to a challenge route with a sign-in's pending token as the credential.
+	*
+	* Straight to `fetch`, like the sign-in routes, and never through the
+	* transport: the token is a credential for these two requests only. Set on
+	* the transport it would go out on every request the app made while the
+	* code step was open — and stay there if the step were abandoned. It would
+	* also displace a session the client already holds, and a refused code
+	* (401 `INVALID_CODE`) would be taken for an expired session and refreshed
+	* and re-sent, spending a second of the challenge's attempts on it.
+	*/
+	async function withPendingToken(endpoint, payload, mfaToken) {
+		const res = await getFetch()(authUrl(endpoint), {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${mfaToken}`
+			},
+			body: payload,
+			credentials: authFlowMode === "cookie" ? "include" : void 0
+		});
+		const body = await res.json().catch(() => ({}));
+		if (!res.ok) throwApiError(res.status, body, res.statusText);
+		return body;
+	}
 	async function getSessions() {
 		return (await transport.request(authPath + "/sessions", { method: "GET" })).sessions;
 	}
@@ -1240,14 +1398,7 @@ function createAuth(transport, options) {
 	}
 	async function revokeAllSessions() {
 		const result = await transport.request(authPath + "/sessions", { method: "DELETE" });
-		currentSession = null;
-		clearStoredSession();
-		if (refreshTimeout) {
-			clearTimeout(refreshTimeout);
-			refreshTimeout = null;
-		}
-		transport.setToken(null);
-		emit("SIGNED_OUT", null);
+		endSession();
 		return result;
 	}
 	async function getAuthConfig() {
@@ -1275,12 +1426,18 @@ function createAuth(transport, options) {
 			resolveInitialized();
 		} else if (authFlowMode === "cookie" || stored.refreshToken) {
 			currentSession = stored;
+			const epoch = sessionEpoch;
 			refreshSession().then(() => {
 				resolveInitialized();
-			}).catch(() => {
-				currentSession = null;
-				clearStoredSession();
-				transport.setToken(null);
+			}).catch((err) => {
+				if (epoch === sessionEpoch && currentSession) if (isFatalRefreshError(err)) {
+					if (storageHoldsCurrentSession()) clearStoredSession();
+					currentSession = null;
+					transport.setToken(null);
+				} else {
+					transport.setToken(currentSession.accessToken);
+					if (autoRefresh) scheduleRetry(0);
+				}
 				resolveInitialized();
 			});
 		} else resolveInitialized();
@@ -1378,8 +1535,14 @@ function createCookieStorage(options = {}) {
 //#region src/admin.ts
 function createAdmin(transport, options) {
 	const adminPath = (options || {}).adminPath || "/admin";
-	async function listUsers() {
-		return transport.request(adminPath + "/users", { method: "GET" });
+	/**
+	* One page of users — the route's default is 25 — with the `total` that
+	* says whether there are more. Takes the same window as
+	* {@link listUsersPaginated}; without one, it used to hand back the first
+	* page typed as the whole list.
+	*/
+	async function listUsers(options) {
+		return listUsersPaginated(options);
 	}
 	async function listUsersPaginated(options) {
 		const params = new URLSearchParams();
@@ -1474,17 +1637,24 @@ function createBackups(transport, options) {
 		return transport.request(backupsPath, { method: "GET" });
 	}
 	/**
-	* Download a backup's bytes. Uses an authenticated fetch (not the JSON
-	* transport) so the octet-stream response comes back as a Blob.
+	* Download a backup's bytes. Not through the JSON `request()`, since the
+	* answer is an octet-stream to hand back as a Blob — but through the
+	* transport's own `fetch` and headers all the same. It used the global
+	* `fetch` and a bare `Authorization` header, so a client configured with
+	* its own `fetch` or with default headers (a gateway key, the schema
+	* version) had every call but this one go where it was told.
 	*/
 	async function download(key) {
-		const token = await transport.resolveToken();
 		const url = `${transport.baseUrl}${transport.apiPath}${backupsPath}/download?key=${encodeURIComponent(key)}`;
-		const res = await fetch(url, {
+		const token = await transport.resolveToken();
+		const headers = transport.getHeaders();
+		delete headers["Content-Type"];
+		if (token) headers.Authorization = `Bearer ${token}`;
+		const res = await transport.fetchFn(url, {
 			method: "GET",
-			headers: token ? { Authorization: `Bearer ${token}` } : {}
+			headers
 		});
-		if (!res.ok) throw new Error(`Failed to download backup (${res.status})`);
+		if (!res.ok) throw new RebaseApiError$1(`Failed to download backup (${res.status})`, { status: res.status });
 		return res.blob();
 	}
 	return {
@@ -1816,6 +1986,28 @@ var SDKQueryBuilder = class {
 */
 var NO_SOCKET = "Listen is only available when RebaseClient is configured with a websocketUrl, and not when it was created with realtime: false.";
 /**
+* Why a live query cannot be opened for these parameters, or `undefined` when
+* it can.
+*
+* A `listen()` is the same query as the `find()` beside it, so what `find()`
+* refuses it refuses too. The socket would not: a frame is JSON, where an
+* `undefined` filter value becomes `null`, so `["!=", uid]` with `uid` unset
+* subscribed to every row whose column is NOT NULL — an ownership filter
+* widened instead of refused. And `after` names a place in one run of the
+* query, which a subscription re-runs on every write; the server keeps no
+* cursor for one, so it was dropped, and page one streamed to a caller who had
+* asked for page two.
+*/
+function listenRefusal(params) {
+	if (params?.where) try {
+		assertNoUndefinedFilterValues(params.where);
+	} catch (error) {
+		if (error instanceof RebaseClientError$1) return error;
+		throw error;
+	}
+	if (params?.after) return new RebaseClientError$1("listen() cannot continue from a cursor: a subscription re-runs its query on every write, and `after` names a place in one run of it. Use `offset` or `page` for a live window, or `find({ after })` to read the page once.", { code: "CURSOR_NOT_LIVE" });
+}
+/**
 * Counts currently in flight, **per client**, keyed by the exact request they
 * issue. Entries live only for the duration of the request — see `count()` for
 * why they exist at all.
@@ -2067,10 +2259,20 @@ function createCollectionClient(transport, slug, ws) {
 					partial: false
 				});
 			};
+			const wantsLive = options?.realtime !== false && !isUnsupported(client.listen);
+			const refusal = wantsLive ? listenRefusal(params) : void 0;
+			if (refusal) {
+				queueMicrotask(() => {
+					if (!closed) onError?.(refusal);
+				});
+				return () => {
+					closed = true;
+				};
+			}
 			client.find(params).then((result) => deliver(result, false)).catch((error) => {
 				if (!closed) onError?.(error);
 			});
-			const live = options?.realtime !== false && !isUnsupported(client.listen) ? client.listen(params, (result) => deliver(result, true), onError) : void 0;
+			const live = wantsLive ? client.listen(params, (result) => deliver(result, true), onError) : void 0;
 			return () => {
 				closed = true;
 				live?.();
@@ -2152,6 +2354,15 @@ function createCollectionClient(transport, slug, ws) {
 	if (ws) {
 		client.listen = (params, onUpdate, onError) => {
 			let active = true;
+			const refusal = listenRefusal(params);
+			if (refusal) {
+				queueMicrotask(() => {
+					if (active) onError?.(refusal);
+				});
+				return () => {
+					active = false;
+				};
+			}
 			let lastUpdateId = 0;
 			let lastKnownTotal;
 			const window = resolveFindWindow(params);
@@ -2504,6 +2715,26 @@ var CHANNEL_MESSAGE_TYPES = /* @__PURE__ */ new Set([
 	"channel_history"
 ]);
 /**
+* Subscription frames. Like channel frames they get no response envelope, and
+* like them they go out without an account when there is none: whether an
+* anonymous visitor may subscribe is the server's `requireAuth` to decide, and
+* a server that refuses answers the frame, which reaches the listener's
+* `onError`.
+*/
+var SUBSCRIPTION_MESSAGE_TYPES = /* @__PURE__ */ new Set([
+	"subscribe_collection",
+	"subscribe_one",
+	"unsubscribe"
+]);
+/**
+* The token getter's "there is no account" — an empty token, or its own
+* "not logged in". Distinct from a getter that failed, which says nothing about
+* whether there is one.
+*/
+function isNotSignedIn(error) {
+	return (error instanceof Error ? error.message : String(error)).includes("not logged in");
+}
+/**
 * The other direction: the frame types the *server* addresses by channel.
 *
 * Not the mirror of {@link CHANNEL_MESSAGE_TYPES} — a request and its answer
@@ -2614,6 +2845,17 @@ var RebaseWebSocketClient = class {
 	pendingRequests = /* @__PURE__ */ new Map();
 	reconnectAttempts = 0;
 	maxReconnectAttempts = 5;
+	/**
+	* Whether a socket of this client has ever opened — what makes the next
+	* open a *reconnect*, whose server has forgotten every subscription and
+	* channel membership and must be told them again.
+	*
+	* Not `reconnectAttempts > 0`: that counter is a backoff budget, and a
+	* fresh one (after giving up, or after a sign-out dropped the socket)
+	* starts at zero, so the socket that finally came back looked like a first
+	* connect and nothing was re-sent.
+	*/
+	hadConnection = false;
 	isConnected = false;
 	messageQueue = [];
 	requestTimeoutMs = 3e4;
@@ -2737,6 +2979,7 @@ var RebaseWebSocketClient = class {
 			this.reconnectTimeout = null;
 		}
 		this.suspendSubscribeWatchdogs();
+		this.forgetCachedData();
 		if (this.ws) {
 			this.ws.onclose = null;
 			this.ws.onerror = null;
@@ -2759,7 +3002,8 @@ var RebaseWebSocketClient = class {
 			this.ws = socket;
 			this.ws.onopen = async () => {
 				console.debug("Connected to PostgreSQL backend");
-				const wasReconnect = this.reconnectAttempts > 0;
+				const wasReconnect = this.hadConnection;
+				this.hadConnection = true;
 				this.isConnected = true;
 				this.reconnectAttempts = 0;
 				if (this.getAuthToken && !this.isAuthenticated) try {
@@ -2772,7 +3016,7 @@ var RebaseWebSocketClient = class {
 					console.debug("WebSocket connected without auth:", error?.message || error);
 				}
 				this.emit(wasReconnect ? "reconnect" : "connect");
-				this.processMessageQueue();
+				this.processMessageQueue(wasReconnect);
 				if (wasReconnect) this.resubscribeAll();
 				this.armPendingSubscribeWatchdogs();
 			};
@@ -2813,11 +3057,45 @@ var RebaseWebSocketClient = class {
 			this.attemptReconnect();
 		}
 	}
-	processMessageQueue() {
+	processMessageQueue(isReconnect) {
 		while (this.messageQueue.length > 0 && this.isConnected) {
 			const message = this.messageQueue.shift();
-			if (message) this.sendMessage(message);
+			if (!message) continue;
+			if (!this.shouldSendQueued(message, isReconnect)) {
+				const resolveQueued = message._queuedResolve;
+				if (typeof resolveQueued === "function") resolveQueued(void 0);
+				continue;
+			}
+			this.sendMessage(message);
+		}
+	}
+	/**
+	* Whether a frame that waited in the queue should go out on the socket
+	* that just opened. Only a subscribe can be refused, and one is exactly
+	* when sending it would give the server a subscription this side will not
+	* read:
+	*
+	* - Its registration is gone, or has been given a new id, while it waited.
+	*   A listener that unmounted before the socket opened (a StrictMode double
+	*   mount does exactly this) sends no `unsubscribe`, because there was no
+	*   socket to send it on, so the server would keep that one forever.
+	* - This open is a reconnect. `resubscribeAll` sends every registration
+	*   under a fresh id right after the queue drains, so the queued copy would
+	*   be the second of two. It is handed back to that pass instead.
+	*/
+	shouldSendQueued(message, isReconnect) {
+		if (message.type !== "subscribe_collection" && message.type !== "subscribe_one") return true;
+		const payload = message.payload;
+		if (!payload || typeof payload !== "object" || !("subscriptionId" in payload)) return true;
+		const subscriptionId = payload.subscriptionId;
+		if (typeof subscriptionId !== "string") return true;
+		const registration = message.type === "subscribe_collection" ? this.collectionSubscriptions.get(this.backendToCollectionKey.get(subscriptionId) ?? "") : this.singleSubscriptions.get(this.backendToEntityKey.get(subscriptionId) ?? "");
+		if (!registration || registration.backendSubscriptionId !== subscriptionId) return false;
+		if (isReconnect) {
+			registration.subscribeInFlight = false;
+			return false;
 		}
+		return true;
 	}
 	attemptReconnect() {
 		if (this.reconnectAttempts >= this.maxReconnectAttempts) {
@@ -2977,8 +3255,9 @@ var RebaseWebSocketClient = class {
 				}
 			}
 		}
-		if (subscriptionId && (type === "ERROR" || message.error)) {
-			const collectionKey = this.backendToCollectionKey.get(subscriptionId);
+		const erroredSubscriptionId = subscriptionId ?? requestId;
+		if (erroredSubscriptionId && (type === "ERROR" || message.error)) {
+			const collectionKey = this.backendToCollectionKey.get(erroredSubscriptionId);
 			if (collectionKey) {
 				const collectionSub = this.collectionSubscriptions.get(collectionKey);
 				if (collectionSub) {
@@ -2996,7 +3275,7 @@ var RebaseWebSocketClient = class {
 					return;
 				}
 			}
-			const entityKey = this.backendToEntityKey.get(subscriptionId);
+			const entityKey = this.backendToEntityKey.get(erroredSubscriptionId);
 			if (entityKey) {
 				const entitySub = this.singleSubscriptions.get(entityKey);
 				if (entitySub) {
@@ -3095,15 +3374,18 @@ var RebaseWebSocketClient = class {
 		});
 	}
 	async doSendMessage(message, resolve, reject) {
+		const isSubscriptionFrame = SUBSCRIPTION_MESSAGE_TYPES.has(message.type);
 		if (message.type !== "AUTHENTICATE" && !CHANNEL_MESSAGE_TYPES.has(message.type) && this.getAuthToken && !this.isAuthenticated) try {
 			await this.ensureAuthenticated();
 		} catch (error) {
-			reject(new RebaseApiError$1(error instanceof Error ? error.message : "Authentication required"));
-			return;
+			if (!(isSubscriptionFrame && isNotSignedIn(error))) {
+				reject(new RebaseApiError$1(error instanceof Error ? error.message : "Authentication required"));
+				return;
+			}
 		}
 		const requestId = message.requestId || `req_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
 		message.requestId = requestId;
-		const expectsResponse = !(message.type === "subscribe_collection" || message.type === "subscribe_one" || message.type === "unsubscribe" || CHANNEL_MESSAGE_TYPES.has(message.type));
+		const expectsResponse = !(isSubscriptionFrame || CHANNEL_MESSAGE_TYPES.has(message.type));
 		if (expectsResponse && !this.pendingRequests.has(requestId)) {
 			const timeoutHandle = setTimeout(() => {
 				if (this.pendingRequests.has(requestId)) {
@@ -3476,6 +3758,7 @@ var RebaseWebSocketClient = class {
 		if (this.isConnected) this.sendCollectionSubscribeWatchdog(subscriptionKey);
 		this.sendMessage({
 			type: "subscribe_collection",
+			requestId: backendSubscriptionId,
 			payload: {
 				...subscription.props,
 				subscriptionId: backendSubscriptionId
@@ -3497,6 +3780,7 @@ var RebaseWebSocketClient = class {
 		if (this.isConnected) this.sendEntitySubscribeWatchdog(subscriptionKey);
 		this.sendMessage({
 			type: "subscribe_one",
+			requestId: backendSubscriptionId,
 			payload: {
 				...subscription.props,
 				subscriptionId: backendSubscriptionId
@@ -3564,6 +3848,26 @@ var RebaseWebSocketClient = class {
 		}
 	}
 	/**
+	* Drop every registration's cached rows, keeping the registrations.
+	*
+	* A registration without rows counts as not loaded, so the next listener
+	* to attach asks the server (or waits for the resubscribe) instead of
+	* being handed what is cached.
+	*/
+	forgetCachedData() {
+		for (const sub of this.collectionSubscriptions.values()) {
+			sub.latestData = void 0;
+			sub.latestMeta = void 0;
+			sub.lastUpdated = void 0;
+			sub.isInitialDataReceived = false;
+		}
+		for (const sub of this.singleSubscriptions.values()) {
+			sub.latestData = void 0;
+			sub.lastUpdated = void 0;
+			sub.isInitialDataReceived = false;
+		}
+	}
+	/**
 	* Arm watchdogs for subscribes that were requested while offline and have
 	* just been flushed to the socket. Their timers were deliberately not set at
 	* request time, so without this they would have no timeout at all.
@@ -3616,6 +3920,7 @@ var RebaseWebSocketClient = class {
 	resubscribeAll() {
 		console.debug(`[WS] Re-subscribing: ${this.collectionSubscriptions.size} collection(s), ${this.singleSubscriptions.size} row(ies)`);
 		for (const [key, sub] of this.collectionSubscriptions.entries()) {
+			if (sub.subscribeInFlight) continue;
 			const oldBackendId = sub.backendSubscriptionId;
 			const newBackendId = `collection_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
 			sub.backendSubscriptionId = newBackendId;
@@ -3624,6 +3929,7 @@ var RebaseWebSocketClient = class {
 			this.sendCollectionSubscribe(key);
 		}
 		for (const [key, sub] of this.singleSubscriptions.entries()) {
+			if (sub.subscribeInFlight) continue;
 			const oldBackendId = sub.backendSubscriptionId;
 			const newBackendId = `entity_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
 			sub.backendSubscriptionId = newBackendId;
@@ -3702,6 +4008,27 @@ var RebaseRealtimeChannel = class {
 	pendingLive = [];
 	catchUpInFlight = false;
 	/**
+	* Whether {@link lastSeq} is a position this client reached, rather than
+	* the zero of a handle that has not caught up yet.
+	*
+	* A client joining for the first time asks for whatever is retained, so
+	* history pruned before it ever joined is not something it missed. Only a
+	* client with a position can have a hole in what it saw.
+	*/
+	positioned = false;
+	/** The page size the catch-up in flight asked for, reused for its later pages. */
+	catchUpLimit;
+	/**
+	* `latestSeq` of an empty page that left this client behind, while a
+	* second request confirms it.
+	*
+	* The server reads the retained messages and then the cursor, so a message
+	* committed between the two shows up in `latestSeq` and not in the page.
+	* The second request returns it if it exists; only a second empty page
+	* means the messages up to this seq are gone.
+	*/
+	emptyTailSeq = null;
+	/**
 	* Deadline for a catch-up response.
 	*
 	* Buffering live messages is only safe because the wait is bounded. A
@@ -3793,6 +4120,7 @@ var RebaseRealtimeChannel = class {
 	*/
 	async requestHistory(limit) {
 		this.catchUpInFlight = true;
+		this.catchUpLimit = limit;
 		if (this.catchUpTimeout) clearTimeout(this.catchUpTimeout);
 		this.catchUpTimeout = setTimeout(() => this.abandonCatchUp(), CATCH_UP_TIMEOUT_MS);
 		unref(this.catchUpTimeout);
@@ -3820,6 +4148,7 @@ var RebaseRealtimeChannel = class {
 		}
 		if (!this.catchUpInFlight) return;
 		this.catchUpInFlight = false;
+		this.emptyTailSeq = null;
 		for (const resolve of this.historyWaiters.splice(0)) resolve({
 			messages: [],
 			retained: false
@@ -3886,6 +4215,12 @@ var RebaseRealtimeChannel = class {
 	* retention cannot be served; `CHANNEL_BUS_PAYLOAD_TOO_LARGE` when a
 	* broadcast on an ephemeral channel is too big to cross the bus.
 	*
+	* `CHANNEL_HISTORY_GAP` is raised by the client: a catch-up found that the
+	* server no longer retains messages this client never received, so its
+	* state has a hole a replay cannot fill. `details` is `{ from, to }`, the
+	* inclusive range of sequence numbers missed. Resync the channel's state
+	* from its source of truth.
+	*
 	* These used to be dropped on the floor — there is no promise to reject on
 	* a fire-and-forget frame, so a forbidden broadcast looked exactly like a
 	* delivered one. With no handler attached they are logged as a warning,
@@ -3927,7 +4262,10 @@ var RebaseRealtimeChannel = class {
 	*/
 	async history(options = {}) {
 		await this.join();
-		if (options.sinceSeq !== void 0) this.lastSeq = options.sinceSeq;
+		if (options.sinceSeq !== void 0) {
+			this.lastSeq = options.sinceSeq;
+			this.positioned = options.sinceSeq > 0;
+		}
 		const result = new Promise((resolve) => {
 			this.historyWaiters.push(resolve);
 		});
@@ -3942,6 +4280,8 @@ var RebaseRealtimeChannel = class {
 		this.presenceHandlers.clear();
 		this.broadcastHandlers.clear();
 		this.lastSeq = 0;
+		this.positioned = false;
+		this.emptyTailSeq = null;
 		this.pendingLive = [];
 		this.catchUpInFlight = false;
 		if (this.catchUpTimeout) {
@@ -3999,11 +4339,11 @@ var RebaseRealtimeChannel = class {
 				}
 				if (seq <= this.lastSeq) break;
 				this.lastSeq = seq;
+				this.positioned = true;
 				this.deliver(event);
 				break;
 			}
 			case "channel_history": {
-				this.catchUpInFlight = false;
 				if (this.catchUpTimeout) {
 					clearTimeout(this.catchUpTimeout);
 					this.catchUpTimeout = null;
@@ -4014,6 +4354,9 @@ var RebaseRealtimeChannel = class {
 					retained,
 					latestSeq
 				});
+				const wasPositioned = this.positioned;
+				const firstNew = entries.find((entry) => entry.seq > this.lastSeq);
+				if (firstNew && wasPositioned && firstNew.seq > this.lastSeq + 1) this.reportHistoryGap(this.lastSeq + 1, firstNew.seq - 1);
 				for (const entry of entries) {
 					if (entry.seq <= this.lastSeq) continue;
 					this.lastSeq = entry.seq;
@@ -4024,6 +4367,28 @@ var RebaseRealtimeChannel = class {
 						replayed: true
 					});
 				}
+				if (retained) this.positioned = true;
+				const behind = retained && latestSeq !== void 0 && latestSeq > this.lastSeq;
+				if (behind && firstNew) {
+					this.emptyTailSeq = null;
+					this.requestHistory(this.catchUpLimit);
+					break;
+				}
+				if (behind && wasPositioned) {
+					if (this.emptyTailSeq === null) {
+						this.emptyTailSeq = latestSeq;
+						this.requestHistory(this.catchUpLimit);
+						break;
+					}
+					const firstLive = this.pendingLive.reduce((min, event) => event.seq !== void 0 && (min === void 0 || event.seq < min) ? event.seq : min, void 0);
+					const end = firstLive !== void 0 ? Math.min(this.emptyTailSeq, firstLive - 1) : this.emptyTailSeq;
+					if (end > this.lastSeq) {
+						this.reportHistoryGap(this.lastSeq + 1, end);
+						this.lastSeq = end;
+					}
+				}
+				this.emptyTailSeq = null;
+				this.catchUpInFlight = false;
 				this.flushPendingLive();
 				break;
 			}
@@ -4032,20 +4397,32 @@ var RebaseRealtimeChannel = class {
 				const raw = message.payload?.error;
 				const asObject = typeof raw === "object" ? raw : void 0;
 				const text = asObject?.message ?? (typeof raw === "string" ? raw : void 0) ?? message.error ?? "The server refused a channel operation.";
-				const error = new RebaseApiError$1(text, { ...asObject?.code ? { code: asObject.code } : {} });
-				if (this.errorHandlers.size === 0) {
-					console.warn(`[Rebase] Channel "${this.name}" error${asObject?.code ? ` (${asObject.code})` : ""}: ${text}. Attach \`channel.onError(...)\` to handle it.`);
-					break;
-				}
-				for (const handler of [...this.errorHandlers]) try {
-					handler(error);
-				} catch (e) {
-					console.error("Error in channel error handler:", e);
-				}
+				this.emitError(new RebaseApiError$1(text, { ...asObject?.code ? { code: asObject.code } : {} }));
 				break;
 			}
 		}
 	}
+	/** Tell the app that retention dropped messages it never received. */
+	reportHistoryGap(from, to) {
+		this.emitError(new RebaseApiError$1(`Channel "${this.name}" missed messages ${from}–${to}: the server no longer retains them. Resync this channel's state.`, {
+			code: "CHANNEL_HISTORY_GAP",
+			details: {
+				from,
+				to
+			}
+		}));
+	}
+	emitError(error) {
+		if (this.errorHandlers.size === 0) {
+			console.warn(`[Rebase] Channel "${this.name}" error${error.code ? ` (${error.code})` : ""}: ${error.message}. Attach \`channel.onError(...)\` to handle it.`);
+			return;
+		}
+		for (const handler of [...this.errorHandlers]) try {
+			handler(error);
+		} catch (e) {
+			console.error("Error in channel error handler:", e);
+		}
+	}
 	/** Deliver everything held back during a catch-up, in sequence order. */
 	flushPendingLive() {
 		if (this.pendingLive.length === 0) return;
@@ -4056,6 +4433,7 @@ var RebaseRealtimeChannel = class {
 			if (seq !== void 0) {
 				if (seq <= this.lastSeq) continue;
 				this.lastSeq = seq;
+				this.positioned = true;
 			}
 			this.deliver(event);
 		}
@@ -4200,6 +4578,16 @@ var IDEMPOTENCY_IN_PROGRESS = "IDEMPOTENCY_KEY_IN_PROGRESS";
 function isIdempotencyInProgressError(error) {
 	return error instanceof RebaseApiError && error.status === 409 && error.code === IDEMPOTENCY_IN_PROGRESS;
 }
+/**
+* Is this key held for a different request than the one just sent with it?
+*
+* For a create the queue already sent once, that is an answer rather than a
+* failure: the key is live only because the first attempt got through and
+* committed, and only its response went missing.
+*/
+function isIdempotencyKeyReusedError(error) {
+	return error instanceof RebaseApiError && error.status === 422 && error.code === "IDEMPOTENCY_KEY_REUSED";
+}
 /** Is this failure worth another attempt later? */
 function isRetryableError(error) {
 	if (isNetworkError(error)) return true;
@@ -4550,9 +4938,10 @@ var IndexedDBOfflineStore = class {
 *   would have included them.
 * - `ORDER BY` puts nulls last ascending and first descending, which is the
 *   Postgres default.
-* - The wire format carries no types, so values arriving as strings are
-*   compared numerically against numeric columns and as instants against
-*   date columns. `["==", "3"]` matches the number `3`, as it does server-side.
+* - A filter value may arrive as a string (off a URL, say), so a string is
+*   compared numerically against a number and as an instant against a date.
+*   `["==", "3"]` matches the number `3`, as it does server-side. Two strings
+*   compare as text: `"01234"` is not `"1234"`.
 *
 * Two things it deliberately approximates, both flagged by
 * {@link isExactlyEvaluable}: `searchString` becomes a case-insensitive
@@ -4592,9 +4981,11 @@ function compareValues(a, b) {
 	const right = toComparable(b);
 	if (isNullish(left) || isNullish(right)) return void 0;
 	if (typeof left === "boolean" || typeof right === "boolean") return (left === true || left === "true" || left === 1 ? 1 : 0) - (right === true || right === "true" || right === 1 ? 1 : 0);
-	const leftNum = typeof left === "number" ? left : numericOrNaN(left);
-	const rightNum = typeof right === "number" ? right : numericOrNaN(right);
-	if (!Number.isNaN(leftNum) && !Number.isNaN(rightNum)) return leftNum < rightNum ? -1 : leftNum > rightNum ? 1 : 0;
+	if (isNumeric(left) || isNumeric(right)) {
+		const leftNum = numericOrNaN(left);
+		const rightNum = numericOrNaN(right);
+		if (!Number.isNaN(leftNum) && !Number.isNaN(rightNum)) return leftNum < rightNum ? -1 : leftNum > rightNum ? 1 : 0;
+	}
 	if (typeof left === "number" || typeof right === "number") {
 		const leftTime = toTime(left);
 		const rightTime = toTime(right);
@@ -4605,6 +4996,9 @@ function compareValues(a, b) {
 	if (collator) return collator.compare(leftStr, rightStr);
 	return leftStr < rightStr ? -1 : leftStr > rightStr ? 1 : 0;
 }
+function isNumeric(value) {
+	return typeof value === "number" || typeof value === "bigint";
+}
 function numericOrNaN(value) {
 	if (typeof value === "number") return value;
 	if (typeof value === "string" && value.trim() !== "") {
@@ -4621,12 +5015,17 @@ function toTime(value) {
 		return Number.isNaN(t) ? void 0 : t;
 	}
 }
-/** Equality with the wire's type erasure allowed for, but never across NULL. */
+/**
+* Equality with a string filter value allowed to name a number, a boolean or
+* an instant, but never across NULL. Two strings are equal only when they are
+* the same string, as text is in Postgres.
+*/
 function looseEquals(a, b) {
 	const left = toComparable(a);
 	const right = toComparable(b);
 	if (isNullish(left) || isNullish(right)) return isNullish(left) && isNullish(right);
 	if (left === right) return true;
+	if (typeof left === "string" && typeof right === "string") return false;
 	return compareValues(left, right) === 0;
 }
 /**
@@ -4911,14 +5310,14 @@ function logicalReachesThroughRelation(condition, depth = 0) {
 *
 * Asked of the rows rather than of the query, because unlike a filter this one
 * *is* decidable from the data in hand: {@link compareValues} reaches the
-* collator only when it cannot read both operands as numbers, and `toComparable`
-* has already turned dates and relations into numbers and ids by then. If every
+* collator only when neither operand is a number, and `toComparable` has
+* already turned dates and relations into numbers and ids by then. If every
 * value on the sort column normalises to a number, the collator is unreachable
 * and the local order is the server's order.
 *
 * A text column is therefore refused — see {@link isExactlyEvaluable} for why
-* the two cannot be made to agree — and so is a column this page happens to see
-* only as strings, which is the same thing from here.
+* the two cannot be made to agree — including one holding only digits, which
+* Postgres orders as text ("10", "100", "9").
 *
 * Nulls are fine either way: they are ordered by an explicit rule (last
 * ascending, first descending) that matches Postgres and never reaches the
@@ -4933,7 +5332,6 @@ function isLocallySortable(rows, orderBy) {
 		if (isNullish(value)) return true;
 		if (typeof value === "number" || typeof value === "boolean") return true;
 		if (typeof value === "bigint") return true;
-		if (typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value))) return true;
 		return false;
 	}));
 }
@@ -5025,6 +5423,29 @@ function optimisticRow(fields, id) {
 		id
 	};
 }
+/**
+* Whether a query answers with something narrower than whole rows: `fields`
+* returns only the columns it names (and the key), and `distinct` collapses
+* rows into their distinct projections. Either way what comes back is not a
+* row of the collection, and must not be stored as one.
+*/
+function isProjection(params) {
+	return (params?.fields?.length ?? 0) > 0 || params?.distinct === true;
+}
+/** `row` narrowed to `keys`: a local row in the shape a projection has. */
+function pick(row, keys) {
+	const out = {};
+	for (const key of keys) if (key in row) out[key] = row[key];
+	return out;
+}
+/** A snapshot as read back from the store, its projected rows revived. */
+function readSnapshot(value) {
+	const snapshot = value;
+	return snapshot.rows ? {
+		...snapshot,
+		rows: snapshot.rows.map((row) => hydrateRow(row))
+	} : snapshot;
+}
 var MISSING = "\0missing";
 /**
 * Replays to spend on a mutation whose idempotency key the server is still
@@ -5203,7 +5624,7 @@ var OfflineManager = class {
 				if (this.connectivity.shouldAttempt()) try {
 					const res = await inner.find(params);
 					this.connectivity.markSuccess();
-					await this.ingest(slug, res.data ?? []);
+					await this.ingest(slug, res.data ?? [], isProjection(params));
 					const snapshot = this.recordSnapshot(slug, params, res);
 					const answer = this.answer(slug, params, snapshot);
 					this.notifyCollection(slug, false);
@@ -5259,10 +5680,15 @@ var OfflineManager = class {
 				});
 				return row;
 			},
-			create: async (data, id) => {
+			create: async (data, id, options) => {
 				await this.ensureCollection(slug);
+				const idempotencyKey = options?.idempotencyKey ?? createMutationId();
+				let sent = false;
 				if (this.connectivity.shouldAttempt()) try {
-					const row = await inner.create(data, id);
+					const row = await inner.create(data, id, {
+						...options,
+						idempotencyKey
+					});
 					this.connectivity.markSuccess();
 					await this.ingest(slug, [row]);
 					this.notifyCollection(slug);
@@ -5271,6 +5697,7 @@ var OfflineManager = class {
 				} catch (error) {
 					if (!isNetworkError(error)) throw error;
 					this.connectivity.markFailure();
+					sent = true;
 				}
 				const providedId = id ?? data.id;
 				const rowId = providedId ?? this.mintOfflineId(slug);
@@ -5281,6 +5708,11 @@ var OfflineManager = class {
 					id: rowId,
 					data: row,
 					generatedId: providedId === void 0,
+					...sent ? { sent: {
+						idempotencyKey,
+						data: { ...data },
+						id
+					} } : {},
 					rollback: { rows: { [String(rowId)]: this.rawLocalRow(slug, rowId) ?? null } }
 				});
 				this.setLocalRow(slug, rowId, row);
@@ -5291,8 +5723,13 @@ var OfflineManager = class {
 				await this.ensureCollection(slug);
 				if (!Array.isArray(data)) throw new TypeError("createMany expects an array of records.");
 				if (data.length === 0) return [];
+				const idempotencyKey = options?.idempotencyKey ?? createMutationId();
+				let sent = false;
 				if (this.connectivity.shouldAttempt()) try {
-					const rows = await inner.createMany(data, options);
+					const rows = await inner.createMany(data, {
+						...options,
+						idempotencyKey
+					});
 					this.connectivity.markSuccess();
 					await this.ingest(slug, rows);
 					this.notifyCollection(slug);
@@ -5301,7 +5738,9 @@ var OfflineManager = class {
 				} catch (error) {
 					if (!isNetworkError(error)) throw error;
 					this.connectivity.markFailure();
+					sent = true;
 				}
+				if (!sent && options?.onConflict?.length) throw new RebaseClientError(`Cannot upsert into "${slug}" while offline: the rows it would replace can only be found by the server. Upserting on the primary key, with the key in each row, is queued; upserting on a natural key is not.`, { code: "OFFLINE_UPSERT_UNSUPPORTED" });
 				const rows = data.map((r) => optimisticRow(r, r.id ?? this.mintOfflineId(slug)));
 				const rollback = {};
 				for (const row of rows) {
@@ -5313,6 +5752,11 @@ var OfflineManager = class {
 					type: "createMany",
 					data: rows,
 					upsert: options?.upsert,
+					...sent ? { sent: {
+						idempotencyKey,
+						data: data.map((r) => ({ ...r })),
+						...options?.onConflict?.length ? { onConflict: [...options.onConflict] } : {}
+					} } : {},
 					rollback: { rows: rollback }
 				});
 				for (const row of rows) this.setLocalRow(slug, row.id, row);
@@ -5424,8 +5868,14 @@ var OfflineManager = class {
 			},
 			update: async (id, data, options) => {
 				await this.ensureCollection(slug);
+				const idempotencyKey = options?.idempotencyKey ?? createMutationId();
+				let sent = false;
+				let sendFailure;
 				if (this.connectivity.shouldAttempt() && !this.hasPending(slug, id)) try {
-					const row = await inner.update(id, data, options);
+					const row = await inner.update(id, data, {
+						...options,
+						idempotencyKey
+					});
 					this.connectivity.markSuccess();
 					await this.ingest(slug, [row]);
 					this.notifyCollection(slug);
@@ -5433,14 +5883,25 @@ var OfflineManager = class {
 				} catch (error) {
 					if (!isNetworkError(error)) throw error;
 					this.connectivity.markFailure();
+					sent = true;
+					sendFailure = error;
+				}
+				if (hasFieldOperation(data)) {
+					if (sent) throw new RebaseApiError(`The connection failed after a field operation on "${slug}" was sent, so it may or may not have been applied. Retry it with the idempotencyKey in \`details\` to apply it at most once.`, {
+						status: 0,
+						code: "NETWORK_ERROR",
+						details: { idempotencyKey },
+						cause: sendFailure
+					});
+					throw new RebaseClientError(`Cannot apply a field operation to "${slug}" while offline: it is evaluated against the stored value, which this device does not have a current copy of. Send the value itself, or retry when the connection is back.`, { code: "OFFLINE_FIELD_OP_UNSUPPORTED" });
 				}
-				if (hasFieldOperation(data)) throw new RebaseClientError(`Cannot apply a field operation to "${slug}" while offline: it is evaluated against the stored value, which this device does not have a current copy of. Send the value itself, or retry when the connection is back.`, { code: "OFFLINE_FIELD_OP_UNSUPPORTED" });
 				const base = this.rawLocalRow(slug, id);
 				await this.enqueue({
 					collection: slug,
 					type: "update",
 					id,
 					data,
+					...sent ? { sent: { idempotencyKey } } : {},
 					rollback: { rows: { [String(id)]: base ?? null } }
 				});
 				const optimistic = optimisticRow({
@@ -5453,8 +5914,13 @@ var OfflineManager = class {
 			},
 			delete: async (id, options) => {
 				await this.ensureCollection(slug);
+				const idempotencyKey = options?.idempotencyKey ?? createMutationId();
+				let sent = false;
 				if (this.connectivity.shouldAttempt() && !this.hasPending(slug, id)) try {
-					await inner.delete(id, options);
+					await inner.delete(id, {
+						...options,
+						idempotencyKey
+					});
 					this.connectivity.markSuccess();
 					this.removeLocalRow(slug, id, true);
 					this.notifyCollection(slug);
@@ -5463,11 +5929,13 @@ var OfflineManager = class {
 				} catch (error) {
 					if (!isNetworkError(error)) throw error;
 					this.connectivity.markFailure();
+					sent = true;
 				}
 				await this.enqueue({
 					collection: slug,
 					type: "delete",
 					id,
+					...sent ? { sent: { idempotencyKey } } : {},
 					rollback: { rows: { [String(id)]: this.rawLocalRow(slug, id) ?? null } }
 				});
 				this.removeLocalRow(slug, id);
@@ -5511,7 +5979,7 @@ var OfflineManager = class {
 			listenById: inner.listenById
 		};
 		if (!isUnsupported(inner.listen)) wrapped.listen = (params, onUpdate, onError) => inner.listen(params, (response) => {
-			this.ingest(slug, response.data ?? []).then(() => this.notifyCollection(slug, false));
+			this.ingest(slug, response.data ?? [], isProjection(params)).then(() => this.notifyCollection(slug, false));
 			onUpdate(response);
 		}, onError);
 		if (!isUnsupported(inner.listenById)) wrapped.listenById = (id, onUpdate, onError) => inner.listenById(id, (row) => {
@@ -5560,7 +6028,7 @@ var OfflineManager = class {
 			if (!closed) observer.emit();
 		})();
 		if (options?.realtime !== false && !isUnsupported(inner.listen)) unlisten = inner.listen(params, (response) => {
-			this.ingest(slug, response.data ?? []).then(() => {
+			this.ingest(slug, response.data ?? [], isProjection(params)).then(() => {
 				this.recordSnapshot(slug, params, response);
 				this.notifyCollection(slug, false);
 			});
@@ -5638,7 +6106,8 @@ var OfflineManager = class {
 		const state = this.collections.get(slug);
 		return `${total}|${rows.map((row) => {
 			const key = String(row.id);
-			return `${key}:${state?.rows.get(key)?.rev ?? 0}`;
+			const entry = state?.rows.get(key);
+			return entry?.row === row ? `${key}:${entry.rev}` : `${key}=${JSON.stringify(row)}`;
 		}).join(",")}`;
 	}
 	notifyCollection(slug, broadcast = true) {
@@ -5694,7 +6163,7 @@ var OfflineManager = class {
 				}
 				for (const entry of snapshots) {
 					const key = entry.key.slice(`${scope}|q|${slug}|`.length);
-					if (entry.value) state.snapshots.set(key, entry.value);
+					if (entry.value) state.snapshots.set(key, readSnapshot(entry.value));
 				}
 				for (const entry of absent) state.absent.add(entry.key.slice(`${scope}|abs|${slug}|`.length));
 			})().catch(() => void 0).finally(() => {
@@ -5744,6 +6213,7 @@ var OfflineManager = class {
 				partial: true
 			};
 		}
+		if (snapshot.rows) return this.projectedAnswer(slug, params, snapshot, snapshot.rows, fromCache);
 		const rows = [];
 		const seen = /* @__PURE__ */ new Set();
 		/** Rows the server counted that we know are no longer in the result. */
@@ -5786,6 +6256,71 @@ var OfflineManager = class {
 			partial: !exact || !orderIsLocal
 		};
 	}
+	/**
+	* Answer a projected query (`fields`, `distinct`) from the server's own
+	* answer to it.
+	*
+	* The server's rows are the answer. The local database contributes only
+	* what it knows better: a row with unsynced writes shows them, narrowed to
+	* the columns the server sent, or drops out if it was deleted here or
+	* edited out of a filter this side can evaluate; and rows created here
+	* join the first page when there is somewhere to put them. A distinct
+	* query, or an order on a column the projection does not carry, leaves
+	* them out, and the result says it is partial.
+	*/
+	projectedAnswer(slug, params, snapshot, served, fromCache) {
+		const state = this.collectionState(slug);
+		const exact = isExactlyEvaluable(params);
+		const rows = [];
+		const seen = /* @__PURE__ */ new Set();
+		let removed = 0;
+		for (const row of served) {
+			const key = row.id === void 0 || row.id === null ? void 0 : String(row.id);
+			if (key !== void 0) seen.add(key);
+			if (key === void 0 || !this.hasPending(slug, key)) {
+				rows.push(row);
+				continue;
+			}
+			const local = state.rows.get(key)?.row;
+			if (!local || exact && !matchesParams(local, params)) {
+				removed++;
+				continue;
+			}
+			rows.push(pick(local, Object.keys(row)));
+		}
+		let added = 0;
+		let unplaced = false;
+		const offset = snapshot.offset ?? 0;
+		if (exact && offset === 0) {
+			const shape = served.length > 0 ? Object.keys(served[0]) : ["id", ...params?.fields ?? []];
+			const placeable = !params?.distinct && (normalizeOrderBy(params?.orderBy) ?? []).every(([field]) => shape.includes(field));
+			for (const [key, entry] of state.rows) {
+				if (seen.has(key) || !this.hasPending(slug, key)) continue;
+				if (!this.isLocallyCreated(slug, key)) continue;
+				if (!matchesParams(entry.row, params)) continue;
+				if (!placeable) {
+					unplaced = true;
+					continue;
+				}
+				rows.push(pick(entry.row, shape));
+				added++;
+			}
+		}
+		const orderIsLocal = added === 0 || isLocallySortable(rows, params?.orderBy);
+		if (added > 0 && params?.orderBy && orderIsLocal) sortRows(rows, params.orderBy);
+		return {
+			data: rows,
+			meta: {
+				total: Math.max(rows.length, snapshot.total - removed + added),
+				limit: snapshot.limit,
+				offset,
+				hasMore: snapshot.hasMore
+			},
+			fromCache,
+			hasPendingWrites: rows.some((row) => row.id !== void 0 && row.id !== null && this.hasPending(slug, row.id)),
+			partial: !exact || !orderIsLocal || unplaced
+		};
+	}
 	localFind(slug, params) {
 		const state = this.collections.get(slug);
 		const snapshot = this.snapshotFor(slug, params);
@@ -5869,8 +6404,14 @@ var OfflineManager = class {
 	* Rows that came back unchanged keep their identity and revision, so a
 	* refetch that changed nothing does not re-render every live query that
 	* touches them — or rewrite them all to disk.
+	*
+	* A `projection` (see {@link isProjection}) only refreshes the columns it
+	* carries on rows already held, and never creates one. It is not a row:
+	* stored as one, it replaced the full row every other query reads and
+	* wrote the narrowed copy to disk, so a list lost its columns because a
+	* dropdown elsewhere asked for titles.
 	*/
-	async ingest(slug, rows) {
+	async ingest(slug, rows, projection = false) {
 		if (rows.length === 0) return;
 		const state = await this.ensureCollection(slug);
 		const cachedAt = Date.now();
@@ -5879,15 +6420,20 @@ var OfflineManager = class {
 		for (const raw of rows) {
 			if (!raw || raw.id === void 0 || raw.id === null) continue;
 			const key = String(raw.id);
-			const merged = this.hasPending(slug, key) ? this.applyPendingToRow(slug, key, { ...raw }) : { ...raw };
+			const existing = state.rows.get(key);
+			if (projection && !existing) continue;
+			const base = projection && existing ? {
+				...existing.row,
+				...raw
+			} : { ...raw };
+			const merged = this.hasPending(slug, key) ? this.applyPendingToRow(slug, key, base) : base;
 			if (merged === void 0) {
 				state.rows.delete(key);
 				deletes.push(this.rowKey(slug, key));
 				continue;
 			}
 			this.forgetTombstone(slug, key);
-			state.freshRows.add(key);
-			const existing = state.rows.get(key);
+			if (!projection) state.freshRows.add(key);
 			if (existing && JSON.stringify(existing.row) === JSON.stringify(merged)) {
 				existing.cachedAt = cachedAt;
 				continue;
@@ -5952,13 +6498,17 @@ var OfflineManager = class {
 			total: meta.total ?? result.data?.length ?? 0,
 			limit: meta.limit ?? window.limit,
 			offset: meta.offset ?? window.offset,
-			hasMore: meta.hasMore ?? false
+			hasMore: meta.hasMore ?? false,
+			...isProjection(params) ? { rows: (result.data ?? []).map((row) => ({ ...row })) } : {}
 		};
 		const state = this.collectionState(slug);
 		const key = buildQueryString(params);
 		state.snapshots.set(key, snapshot);
 		state.fresh.add(key);
-		this.writeCache(`${this.scope}|q|${slug}|${key}`, snapshot);
+		this.writeCache(`${this.scope}|q|${slug}|${key}`, snapshot.rows ? {
+			...snapshot,
+			rows: snapshot.rows.map((row) => dehydrateRow(row))
+		} : snapshot);
 		this.evictSnapshots(slug);
 		return snapshot;
 	}
@@ -6022,7 +6572,7 @@ var OfflineManager = class {
 			await this.ensureQueueLoaded();
 			if (mutation.type === "update") {
 				const tail = this.queue[this.queue.length - 1];
-				if (tail && tail.mutationId !== this.inFlightId && tail.collection === mutation.collection && (tail.type === "create" || tail.type === "update") && tail.id === mutation.id) {
+				if (tail && tail.mutationId !== this.inFlightId && tail.sent === void 0 && tail.collection === mutation.collection && (tail.type === "create" || tail.type === "update") && tail.id === mutation.id) {
 					tail.data = {
 						...tail.data,
 						...mutation.data,
@@ -6033,7 +6583,7 @@ var OfflineManager = class {
 				}
 			}
 			if (mutation.type === "delete") {
-				if (this.queue.some((m) => m.collection === mutation.collection && m.type === "create" && m.id === mutation.id && m.generatedId === true && m.mutationId !== this.inFlightId)) {
+				if (this.queue.some((m) => m.collection === mutation.collection && m.type === "create" && m.id === mutation.id && m.generatedId === true && m.sent === void 0 && m.mutationId !== this.inFlightId)) {
 					const doomed = this.queue.filter((m) => m.collection === mutation.collection && m.id === mutation.id && (m.type === "create" || m.type === "update") && m.mutationId !== this.inFlightId);
 					for (const op of doomed) await this.store.dequeue(this.queueKey(op));
 					this.queue = this.queue.filter((m) => !doomed.includes(m));
@@ -6158,7 +6708,7 @@ var OfflineManager = class {
 		if (op.type === "create") {
 			let row;
 			try {
-				row = await inner.create(op.data, void 0, { idempotencyKey: op.mutationId });
+				row = await this.sendQueuedWrite(op, (idempotencyKey) => inner.create(op.data, void 0, { idempotencyKey }), (sent) => inner.create(sent.data, sent.id, { idempotencyKey: sent.idempotencyKey }));
 			} catch (error) {
 				if (!(op.generatedId === true && isDuplicateKeyError(error))) throw error;
 				row = await inner.findById(op.id).catch(() => void 0);
@@ -6167,10 +6717,15 @@ var OfflineManager = class {
 			await this.adoptServerRow(op, op.id, row);
 		} else if (op.type === "createMany") {
 			const queued = op.data ?? [];
-			const rows = await inner.createMany(queued, {
+			const asSent = (sent) => inner.createMany(sent.data, {
 				...op.upsert ? { upsert: true } : {},
-				idempotencyKey: op.mutationId
+				...sent.onConflict?.length ? { onConflict: sent.onConflict } : {},
+				idempotencyKey: sent.idempotencyKey
 			});
+			const rows = op.sent?.onConflict?.length ? await asSent(op.sent) : await this.sendQueuedWrite(op, (idempotencyKey) => inner.createMany(queued, {
+				...op.upsert ? { upsert: true } : {},
+				idempotencyKey
+			}), asSent);
 			for (let i = 0; i < rows.length; i++) await this.adoptServerRow(op, queued[i]?.id, rows[i]);
 		} else if (op.type === "updateMany") {
 			const queued = op.updates ?? [];
@@ -6180,18 +6735,36 @@ var OfflineManager = class {
 			})), { idempotencyKey: op.mutationId });
 			for (let i = 0; i < rows.length; i++) await this.ingestReplaced(op, queued[i].id, rows[i]);
 		} else if (op.type === "update") {
-			const row = await inner.update(op.id, op.data);
+			const row = await inner.update(op.id, op.data, op.sent ? { idempotencyKey: op.sent.idempotencyKey } : void 0);
 			await this.ingestReplaced(op, op.id, row);
 		} else if (op.type === "deleteMany") {
 			const ids = op.ids ?? [];
 			await inner.deleteMany(ids, { idempotencyKey: op.mutationId });
 			for (const id of ids) this.removeLocalRow(op.collection, id, true);
 		} else if (op.type === "delete") {
-			await inner.delete(op.id);
+			await inner.delete(op.id, { idempotencyKey: op.sent?.idempotencyKey ?? op.mutationId });
 			this.removeLocalRow(op.collection, op.id, true);
 		}
 	}
 	/**
+	* Send a queued write under its key.
+	*
+	* A write the queue sent once already, before it was queued, carries that
+	* attempt's key and is sent under it again, as queued. If the server holds
+	* the key for a different request, the difference is the ids minted here
+	* — so the first attempt committed and only its answer was lost, and
+	* sending that request again returns the stored answer instead of a
+	* second copy of the rows.
+	*/
+	async sendQueuedWrite(op, asQueued, asSent) {
+		try {
+			return await asQueued(op.sent?.idempotencyKey ?? op.mutationId);
+		} catch (error) {
+			if (!op.sent || !isIdempotencyKeyReusedError(error)) throw error;
+			return asSent(op.sent);
+		}
+	}
+	/**
 	* Take the server's version of a row the client created offline.
 	*
 	* The server may have assigned a different id — a serial column ignores
@@ -6362,7 +6935,7 @@ var OfflineManager = class {
 		state.snapshots = /* @__PURE__ */ new Map();
 		for (const entry of snapshots) {
 			const key = entry.key.slice(`${scope}|q|${slug}|`.length);
-			if (entry.value) state.snapshots.set(key, entry.value);
+			if (entry.value) state.snapshots.set(key, readSnapshot(entry.value));
 		}
 		state.absent = new Set(absent.map((entry) => entry.key.slice(`${scope}|abs|${slug}|`.length)));
 		this.notifyCollection(slug, false);
@@ -6503,15 +7076,28 @@ function createRebaseClient(options) {
 				let session = auth.getSession();
 				if (session && session.expiresAt <= Date.now() + 1e4) try {
 					session = await auth.refreshSession();
-				} catch (e) {}
+				} catch (e) {
+					session = auth.getSession();
+				}
 				return session?.accessToken || options.token || "";
 			},
 			onUnauthorized: options.onUnauthorized || (() => auth.handleUnauthorized())
 		});
+		let realtimeUid = auth.getSession()?.user?.uid ?? null;
 		auth.onAuthStateChange((event, session) => {
 			if (!ws) return;
-			if (event === "SIGNED_OUT") ws.disconnect();
-			else if (event === "SIGNED_IN" || event === "TOKEN_REFRESHED") {
+			if (event === "SIGNED_OUT") {
+				realtimeUid = null;
+				ws.disconnect();
+			} else if (event === "SIGNED_IN" || event === "TOKEN_REFRESHED") {
+				const uid = session?.user?.uid ?? null;
+				if (uid !== realtimeUid) {
+					realtimeUid = uid;
+					const hadSocket = ws.hasSocket;
+					ws.disconnect();
+					if (hadSocket) ws.ensureConnected();
+					return;
+				}
 				if (session?.accessToken && ws.hasSocket) ws.authenticate(session.accessToken).catch(console.warn);
 			}
 		});
@@ -6651,7 +7237,7 @@ channel: (name, options) => {
 			const prefix = endpoint.startsWith("/") ? "" : "/";
 			return transport.request(`${prefix}${endpoint}`, {
 				method: "POST",
-				body: payload ? JSON.stringify(payload) : void 0
+				body: payload !== void 0 ? JSON.stringify(payload) : void 0
 			});
 		},
 		batch: async (operations, options) => {