@hvakr/firestate 0.1.2 → 0.1.4

package/dist/index.mjs

@@ -1,8 +1,9 @@
 import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
-import { Timestamp, collection, deleteDoc, deleteField, doc as doc$1, onSnapshot, query, queryEqual, serverTimestamp, setDoc, updateDoc, writeBatch } from "firebase/firestore";
+import { useSyncExternalStoreWithSelector } from "use-sync-external-store/shim/with-selector";
+import { FieldPath, Timestamp, collection, deleteDoc, deleteField, doc as doc$1, onSnapshot, query, queryEqual, serverTimestamp, setDoc, updateDoc, writeBatch } from "firebase/firestore";
 import { jsx } from "react/jsx-runtime";
 
-//#region src/schema.ts
+//#region src/registry/schema.ts
 function defineDocument(definition) {
 	return definition;
 }
@@ -11,7 +12,7 @@ function defineCollection(definition) {
 }
 
 //#endregion
-//#region src/diff.ts
+//#region src/utils/diff.ts
 /**
 * Check if a value is a plain object (not array, null, or special Firestore type)
 */
@@ -60,6 +61,47 @@ const isDeepEqual = (a, b) => {
 	return false;
 };
 /**
+* Equality used solely to decide whether a write is a no-op (§3 of the
+* update-logic rewrite). Purpose-built to close the "Maximum update depth"
+* render loop, where a write whose result equals the current view must produce
+* NO new state identity. It differs from {@link isDeepEqual} in exactly the two
+* places that let the loop survive a naive guard:
+*
+* - `NaN` ≡ `NaN` (via `Object.is`). `computeDiff` compares primitives with
+*   `!==`, so a field that is `NaN` on both sides emits a spurious diff.
+* - An explicit-`undefined` key ≡ a missing key (`{x: undefined}` ≡ `{}`).
+*   `isDeepEqual` rejects these on a keys-length mismatch.
+*
+* Standalone ON PURPOSE — do NOT fold this into `isDeepEqual`. `computeDiff`
+* and `computeUndoDiff` depend on `isDeepEqual`'s current `NaN !== NaN` and
+* strict keys-length semantics; relaxing them there would change the wire
+* payload. Firestore opaque values (Timestamp, sentinels, refs) delegate to
+* their own `.isEqual`; arrays compare elementwise.
+*/
+const valuesEqualForNoOp = (a, b) => {
+	if (Object.is(a, b)) return true;
+	if (isFirestoreOpaque(a) || isFirestoreOpaque(b)) return isFirestoreOpaque(a) && isFirestoreOpaque(b) && a.isEqual(b);
+	if (Array.isArray(a) || Array.isArray(b)) {
+		if (!Array.isArray(a) || !Array.isArray(b)) return false;
+		if (a.length !== b.length) return false;
+		return a.every((item, i) => valuesEqualForNoOp(item, b[i]));
+	}
+	if (isPlainObject(a) && isPlainObject(b)) {
+		const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+		for (const key of keys) if (!valuesEqualForNoOp(a[key], b[key])) return false;
+		return true;
+	}
+	return false;
+};
+/**
+* Snapshot-side no-op collapse comparison over the observable fields shared by
+* DocumentState and CollectionState (§3/§4): returns `true` when something a
+* consumer can observe changed. `data` uses {@link valuesEqualForNoOp} so an
+* explicit-`undefined` ≡ missing key does not count as a change. Collection
+* state additionally checks `isActive` at the call site.
+*/
+const observableStateChanged = (prev, next) => prev.isLoading !== next.isLoading || prev.isSynced !== next.isSynced || prev.error !== next.error || !valuesEqualForNoOp(prev.data, next.data);
+/**
 * Compute the minimal diff between two objects for Firestore updates.
 * Returns only the fields that changed, using deleteField() for removed fields.
 *
@@ -94,6 +136,48 @@ const computeDiff = (from, to) => {
 	return diff;
 };
 /**
+* Strip FieldValue sentinels from a freshly-computed `edits` object when they
+* match a write the server has already durably accepted (`committed`).
+*
+* A sentinel (`serverTimestamp`, `increment`, `arrayUnion`, `arrayRemove`) is a
+* fire-once write intent: the client ships the sentinel, the server resolves it
+* to a concrete value, and the confirming snapshot carries that value. The
+* snapshot rebase re-derives pending edits with `computeDiff` and re-applies
+* them over the new server truth — but a sentinel can never compare equal to
+* its own resolved value (`isDeepEqual` only delegates to `.isEqual` when both
+* sides are opaque), so a committed sentinel would be re-derived and re-written
+* on every snapshot forever (and a non-idempotent `increment` would re-apply
+* each loop — data corruption).
+*
+* The fix: once a write's promise resolves, the caller records its payload as
+* `committed`. On the next snapshot the rebase calls this to drop any sentinel
+* that sits at the same path AND is `.isEqual` to the committed one — it has
+* landed, so the server's value is now the truth. Everything else is preserved:
+* a not-yet-sent sentinel (no `committed` entry), a re-edited sentinel (a
+* different `.isEqual` result), and every plain value flow through untouched,
+* so genuine pending edits and collaborator merges are unaffected.
+*
+* `edits` is mutated in place (it is always a fresh `computeDiff` result).
+* Recurses into plain objects, so collection diffs keyed by docId converge too:
+* when a doc's nested diff empties out, the doc entry itself is removed.
+*
+* @internal
+*/
+const dropCommittedSentinels = (edits, committed) => {
+	if (!committed) return edits;
+	for (const key of Object.keys(edits)) {
+		const value = edits[key];
+		const sent = committed[key];
+		if (isFirestoreOpaque(value)) {
+			if (isFirestoreOpaque(sent) && value.isEqual(sent)) delete edits[key];
+		} else if (isPlainObject(value) && isPlainObject(sent)) {
+			dropCommittedSentinels(value, sent);
+			if (Object.keys(value).length === 0) delete edits[key];
+		}
+	}
+	return edits;
+};
+/**
 * Apply a Firestore diff to a target object in place (mutating).
 * Handles deleteField(), serverTimestamp(), and nested objects.
 *
@@ -163,6 +247,13 @@ const isDiffEmpty = (diff) => Object.keys(diff).length === 0;
 * VectorValue) are NOT flattened — they're preserved at their path so
 * Firestore receives them in their original form.
 *
+* ⚠️ The dot-joined keys this produces are AMBIGUOUS to Firestore if any map
+* key itself contains a "." (e.g. an email key `a@b.com`): `updateDoc` parses
+* the "." as a path separator and writes to the wrong nested field. The
+* write path uses {@link flattenDiffToFieldPaths} + `FieldPath` instead, which
+* keeps every segment literal. Reach for this only when dotted-string keys are
+* what you actually want.
+*
 * @param diff - The nested diff object
 * @param prefix - Internal: current path prefix for recursion
 * @returns Flattened object with dotted keys
@@ -186,6 +277,60 @@ const flattenDiff = (diff, prefix = "") => {
 	return result;
 };
 /**
+* Flatten a nested diff into a list of `{ segments, value }` entries, where
+* `segments` is the path expressed as an array of *literal* key segments
+* (never joined into a dotted string).
+*
+* This is the segment-preserving sibling of {@link flattenDiff}. It exists
+* because dot-joined string keys are ambiguous to Firestore: `updateDoc(ref,
+* { "users.a@b.com.role": 4 })` parses the `.` inside the email key as a path
+* separator and writes to `users → "a@b" → "com" → role` instead of the
+* literal key `"a@b.com"`. Feeding these segments to `new FieldPath(...segments)`
+* (with the variadic `updateDoc(ref, fieldPath, value, …)` form) keeps every
+* segment literal, so a "." inside a map key is never re-interpreted.
+*
+* The opaque/plain-object rules mirror {@link flattenDiff} exactly: arrays,
+* FieldValue sentinels (deleteField, serverTimestamp, …), and Firestore value
+* types (Timestamp, DocumentReference, GeoPoint, Bytes, VectorValue) ride
+* through verbatim at their path; only plain objects are recursed into.
+*
+* @param diff - The nested diff object
+* @param prefix - Internal: accumulated path segments for recursion
+* @returns Flat list of `{ segments, value }` entries
+*/
+const flattenDiffToFieldPaths = (diff, prefix = []) => {
+	const result = [];
+	for (const key of Object.keys(diff)) {
+		const value = diff[key];
+		const segments = [...prefix, key];
+		if (Array.isArray(value) || isFirestoreOpaque(value)) {
+			result.push({
+				segments,
+				value
+			});
+			continue;
+		}
+		if (isPlainObject(value)) {
+			result.push(...flattenDiffToFieldPaths(value, segments));
+			continue;
+		}
+		result.push({
+			segments,
+			value
+		});
+	}
+	return result;
+};
+/**
+* Build the variadic `(fieldPath, value, …)` argument list for the
+* `updateDoc(ref, …)` / `batch.update(ref, …)` form from a nested diff. Each
+* segment array becomes a literal `FieldPath`, so a "." inside a map key (e.g.
+* the email key `a@b.com`) stays a single segment instead of being re-parsed
+* as a path separator. Returns `[]` for an empty diff — callers should skip
+* the update entirely in that case.
+*/
+const diffToFieldPathArgs = (diff) => flattenDiffToFieldPaths(diff).flatMap((e) => [new FieldPath(...e.segments), e.value]);
+/**
 * Merge two diffs together, with the second taking precedence
 */
 const mergeDiffs = (first, second) => {
@@ -413,120 +558,162 @@ const applyOverridesAtPaths = (merged, overrides) => {
 };
 
 //#endregion
-//#region src/document.ts
+//#region src/core/collection.ts
 let syncKeyCounter$1 = 0;
 /**
-* Create a document subscription.
-* This is a low-level API - prefer using useDocument hook in React.
+* Build the Firestore query a collection subscription runs: `definition`-level
+* constraints first, then hook-level `extraConstraints`. With no constraints at
+* all the bare collection reference is itself a valid `Query`.
+*
+* Single source of truth for query assembly. `useCollection` decides whether a
+* fresh `queryConstraints` array is semantically the same query — and so
+* whether to keep the existing listener instead of tearing it down — by
+* building the prospective query with this exact function and comparing via
+* Firestore's `queryEqual` (see hooks.ts). That comparison is only correct if
+* it assembles the query the same way the subscription does, so both paths MUST
+* go through here. Don't re-inline the merge order at either call site.
+*/
+const buildCollectionQuery = (ref, definitionConstraints, extraConstraints) => {
+	const all = [...definitionConstraints ?? [], ...extraConstraints ?? []];
+	return all.length > 0 ? query(ref, ...all) : ref;
+};
+/**
+* Create a collection subscription.
+* This is a low-level API - prefer using useCollection hook in React.
 *
 * @example
 * ```ts
-* const subscription = createDocumentSubscription({
+* const subscription = createCollectionSubscription({
 *   store,
-*   definition: projectDoc,
-*   docId: '123',
+*   definition: spacesCollection,
+*   collectionPath: 'projects/123/spaces',
 * })
 *
 * const unsubscribe = subscription.subscribe((state) => {
-*   console.log('Document state:', state)
+*   console.log('Collection state:', state)
 * })
 *
-* subscription.load()
+* subscription.load() // For lazy collections
 * ```
 */
-const createDocumentSubscription = (options) => {
-	const { store, definition, docId, collectionPath: resolvedCollectionPath, readOnly, onPushUndo } = options;
+const createCollectionSubscription = (options) => {
+	const { store, definition, collectionPath: resolvedPath, readOnly, queryConstraints: extraConstraints, onPushUndo } = options;
 	const { firestore, autosave: defaultAutosave, minLoadTime: defaultMinLoadTime } = store;
-	const { collection: collectionConfig, id, autosave = defaultAutosave, minLoadTime = defaultMinLoadTime, readOnly: definitionReadOnly, retryOnError = false, retryInterval = 5e3, schema } = definition;
+	const { path, autosave = defaultAutosave, minLoadTime = defaultMinLoadTime, readOnly: definitionReadOnly, lazy = false, queryConstraints: definitionConstraints, retryOnError = false, retryInterval = 5e3, schema } = definition;
 	const isReadOnly = readOnly ?? definitionReadOnly ?? false;
-	const documentId = docId ?? (typeof id === "string" ? id : void 0);
-	if (documentId === void 0) throw new Error(`createDocumentSubscription: definition.id is a function; pass a resolved docId in options.`);
-	const collectionPath = resolvedCollectionPath ?? (typeof collectionConfig === "string" ? collectionConfig : void 0);
-	if (collectionPath === void 0) throw new Error(`createDocumentSubscription: definition.collection is a function; pass a resolved collectionPath in options.`);
-	const docRef = doc$1(collection(firestore, collectionPath), documentId);
+	const collectionPath = resolvedPath ?? (typeof path === "string" ? path : void 0);
+	if (collectionPath === void 0) throw new Error(`createCollectionSubscription: definition.path is a function; pass a resolved collectionPath in options.`);
+	const collectionRef = collection(firestore, collectionPath);
 	const state = {
 		syncState: void 0,
 		localState: void 0,
-		isLoading: true,
+		isLoading: !lazy,
+		isActive: !lazy,
 		error: void 0,
-		waitingForUpdate: false,
-		inflightLocalState: void 0,
-		isSetOperation: false,
+		committedWrite: void 0,
 		displayOverrides: /* @__PURE__ */ new Map()
 	};
 	const subscribers = /* @__PURE__ */ new Set();
 	let unsubscribeListener = null;
 	let autosaveTimeout = null;
-	let retryTimeout = null;
 	let minLoadTimeout = null;
+	let retryTimeout = null;
 	let minLoadTimeElapsed = false;
 	let loaded = false;
 	let cachedHandle = null;
-	const syncKey = `doc:${collectionPath}/${documentId}#${++syncKeyCounter$1}`;
+	const syncKey = `col:${collectionPath}#${++syncKeyCounter$1}`;
 	const getMergedData = () => {
-		if (state.localState === null) return void 0;
-		const base = state.localState ?? state.syncState;
-		if (base === void 0) return void 0;
-		return applyOverridesAtPaths(base, state.displayOverrides);
+		return applyOverridesAtPaths(state.localState ?? state.syncState ?? {}, state.displayOverrides);
 	};
 	const getPublicState = () => ({
 		data: getMergedData(),
 		isLoading: state.isLoading,
+		isLoaded: state.isActive && !state.isLoading,
 		isSynced: state.localState === void 0,
+		isActive: state.isActive,
 		error: state.error
 	});
+	let lastPublished = null;
+	let cachedState = null;
+	const publicStateChanged = (prev, next) => prev.isActive !== next.isActive || observableStateChanged(prev, next);
 	const notify = () => {
-		reconcileDisplayOverrides(state.localState && typeof state.localState === "object" ? state.localState : void 0, state.displayOverrides);
-		cachedHandle = null;
+		reconcileDisplayOverrides(state.localState, state.displayOverrides);
 		const publicState = getPublicState();
+		if (lastPublished !== null && !publicStateChanged(lastPublished, publicState)) return;
+		lastPublished = publicState;
+		cachedHandle = null;
+		cachedState = publicState;
 		subscribers.forEach((fn) => fn(publicState));
 		store.reportSyncState(syncKey, publicState.isSynced);
 	};
+	const warnNoSnapshot = (method) => {
+		if (process.env.NODE_ENV !== "production") console.warn(`[firestate] ${method}() on ${collectionPath} was ignored: the first snapshot has not arrived yet. Gate calls on the collection's isLoading/isActive state, or await the first data before mutating.`);
+	};
 	const updateState = (diff, undoOptions = {}) => {
 		if (isReadOnly) return;
-		if (!getMergedData()) {
-			if (process.env.NODE_ENV !== "production") console.warn(`[firestate] update() on ${collectionPath}/${documentId} was ignored: there is no current data to diff against. This happens when the document is still loading, has been deleted, or doesn't exist yet. Use set() to create the document, or gate update calls on a non-undefined data value.`);
+		if (state.syncState === void 0) {
+			warnNoSnapshot("update");
 			return;
 		}
-		const rawBase = state.localState ?? state.syncState;
+		const rawBase = state.localState ?? state.syncState ?? {};
 		const newLocalState = deepClone(rawBase);
 		applyDiffMutable(newLocalState, diff);
+		for (const [docId, docData] of Object.entries(newLocalState)) if (docData && typeof docData === "object") docData.id = docId;
+		if (valuesEqualForNoOp(rawBase, newLocalState)) return;
 		if (undoOptions?.undoable !== false && onPushUndo) {
 			const undoDiff = computeDiff(newLocalState, rawBase);
 			const redoDiff = computeDiff(rawBase, newLocalState);
 			onPushUndo(() => updateState(undoDiff, { undoable: false }), () => updateState(redoDiff, { undoable: false }), undoOptions);
 		}
 		state.localState = newLocalState;
-		state.isSetOperation = false;
 		notify();
 		scheduleAutosave();
 	};
-	const setData = (data, undoOptions = {}) => {
-		if (isReadOnly) return;
-		if (schema) schema.parse(data);
+	function addDocument(idOrData, dataOrOptions, maybeUndoOptions) {
+		const hasExplicitId = typeof idOrData === "string";
+		const data = hasExplicitId ? dataOrOptions : idOrData;
+		const undoOptions = (hasExplicitId ? maybeUndoOptions : dataOrOptions) ?? {};
+		if (isReadOnly) return void 0;
+		if (state.syncState === void 0) {
+			warnNoSnapshot("add");
+			return;
+		}
+		const id = hasExplicitId ? idOrData : doc$1(collectionRef).id;
+		const newDoc = {
+			...data,
+			id
+		};
+		if (schema) schema.parse(newDoc);
 		const currentData = getMergedData();
+		const newLocalState = deepClone(currentData);
+		newLocalState[id] = newDoc;
+		if (valuesEqualForNoOp(currentData, newLocalState)) return id;
 		if (undoOptions?.undoable !== false && onPushUndo) {
-			const dataForRedo = deepClone(data);
-			if (currentData === void 0) onPushUndo(() => deleteDocument({ undoable: false }), () => setData(dataForRedo, { undoable: false }), undoOptions);
-			else {
-				const dataToRestore = deepClone(state.localState ?? state.syncState);
-				onPushUndo(() => setData(dataToRestore, { undoable: false }), () => setData(dataForRedo, { undoable: false }), undoOptions);
-			}
+			const undoDiff = computeDiff(newLocalState, currentData);
+			const redoDiff = computeDiff(currentData, newLocalState);
+			onPushUndo(() => updateState(undoDiff, { undoable: false }), () => updateState(redoDiff, { undoable: false }), undoOptions);
 		}
-		state.localState = deepClone(data);
-		state.isSetOperation = true;
+		state.localState = newLocalState;
 		notify();
 		scheduleAutosave();
-	};
-	const deleteDocument = (undoOptions = {}) => {
+		return id;
+	}
+	const removeDocument = (id, undoOptions = {}) => {
 		if (isReadOnly) return;
-		if (getMergedData() === void 0) return;
+		if (state.syncState === void 0) {
+			warnNoSnapshot("remove");
+			return;
+		}
+		const currentData = getMergedData();
+		if (!(id in currentData)) return;
+		const newLocalState = deepClone(currentData);
+		delete newLocalState[id];
 		if (undoOptions?.undoable !== false && onPushUndo) {
-			const dataToRestore = deepClone(state.localState ?? state.syncState);
-			onPushUndo(() => setData(dataToRestore, { undoable: false }), () => deleteDocument({ undoable: false }), undoOptions);
+			const undoDiff = computeDiff(newLocalState, currentData);
+			const redoDiff = computeDiff(currentData, newLocalState);
+			onPushUndo(() => updateState(undoDiff, { undoable: false }), () => updateState(redoDiff, { undoable: false }), undoOptions);
 		}
-		state.localState = null;
-		state.isSetOperation = false;
+		state.localState = newLocalState;
 		notify();
 		scheduleAutosave();
 	};
@@ -537,120 +724,94 @@ const createDocumentSubscription = (options) => {
 		}, autosave);
 	};
 	const sync = async () => {
-		if (state.localState === void 0) return;
-		if (state.localState === null) {
-			state.inflightLocalState = null;
-			state.waitingForUpdate = true;
-			try {
-				await deleteDoc(docRef);
-			} catch (error) {
-				console.error("Sync failed:", error);
-				state.waitingForUpdate = false;
-				state.inflightLocalState = void 0;
-				state.error = error;
-				store.reportError(error, {
-					type: "document",
-					path: `${collectionPath}/${documentId}`,
-					operation: "write"
-				});
-				notify();
-			}
-			return;
-		}
-		if (state.syncState && isDeepEqual(state.localState, state.syncState)) {
+		if (!state.localState) return;
+		if (state.syncState === void 0) return;
+		const syncState = state.syncState;
+		if (isDeepEqual(state.localState, syncState)) {
 			state.localState = void 0;
-			state.inflightLocalState = void 0;
 			notify();
 			return;
 		}
-		const wasSetOperation = state.isSetOperation;
-		state.isSetOperation = false;
-		const isCreation = !state.syncState;
-		const useSetDoc = wasSetOperation || isCreation;
-		const diff = state.syncState ? computeDiff(state.syncState, state.localState) : void 0;
-		state.inflightLocalState = deepClone(state.localState);
-		state.waitingForUpdate = true;
+		const diff = computeDiff(syncState, state.localState);
+		const committing = deepClone(state.localState);
 		try {
-			if (useSetDoc) await setDoc(docRef, state.localState);
-			else await updateDoc(docRef, flattenDiff(diff));
+			const batch = writeBatch(firestore);
+			const deleteFieldSentinel = deleteField();
+			for (const [docId, docDiff] of Object.entries(diff)) {
+				const docRef = doc$1(collectionRef, docId);
+				if (docDiff !== null && typeof docDiff === "object" && "isEqual" in docDiff && typeof docDiff.isEqual === "function" && docDiff.isEqual(deleteFieldSentinel)) batch.delete(docRef);
+				else if (!(docId in syncState)) batch.set(docRef, docDiff);
+				else {
+					const args = diffToFieldPathArgs(docDiff);
+					if (args.length) batch.update(docRef, ...args);
+				}
+			}
+			await batch.commit();
+			state.committedWrite = committing;
 		} catch (error) {
-			console.error("Sync failed:", error);
-			state.waitingForUpdate = false;
-			state.inflightLocalState = void 0;
+			console.error("Collection sync failed:", error);
 			state.error = error;
 			store.reportError(error, {
-				type: "document",
-				path: `${collectionPath}/${documentId}`,
+				type: "collection",
+				path: collectionPath,
 				operation: "write"
 			});
 			notify();
 		}
 	};
-	const handleSnapshot = (newSyncData) => {
-		state.syncState = newSyncData;
+	const handleSnapshot = (docs) => {
+		const newSyncState = {};
+		for (const { id, data } of docs) newSyncState[id] = {
+			...data,
+			id
+		};
+		const prevSync = state.syncState;
+		state.syncState = newSyncState;
 		state.error = void 0;
-		if (state.waitingForUpdate) {
-			state.waitingForUpdate = false;
-			const inflightState = state.inflightLocalState;
-			state.inflightLocalState = void 0;
-			const currentLocal = state.localState;
-			if (inflightState === null) {} else if (currentLocal === null) {} else if (inflightState && currentLocal && !isDeepEqual(currentLocal, inflightState)) {
-				const changesSinceInflight = computeDiff(inflightState, currentLocal);
-				const rebasedLocalState = deepClone(newSyncData);
-				applyDiffMutable(rebasedLocalState, changesSinceInflight);
-				state.localState = rebasedLocalState;
-			} else state.localState = void 0;
+		const committed = state.committedWrite;
+		state.committedWrite = void 0;
+		const currentLocal = state.localState;
+		if (currentLocal !== void 0 && prevSync !== void 0) {
+			const userEdits = computeDiff(prevSync, currentLocal);
+			dropCommittedSentinels(userEdits, committed);
+			const rebasedLocalState = applyDiff(newSyncState, userEdits);
+			for (const docId of Object.keys(prevSync)) if (!(docId in newSyncState)) delete rebasedLocalState[docId];
+			for (const [docId, docData] of Object.entries(rebasedLocalState)) if (docData && typeof docData === "object") docData.id = docId;
+			state.localState = isDeepEqual(rebasedLocalState, newSyncState) ? void 0 : rebasedLocalState;
 		}
 		if (minLoadTimeElapsed) state.isLoading = false;
 		loaded = true;
 		if (state.localState !== void 0) scheduleAutosave();
 		notify();
 	};
-	const handleMissingDocument = () => {
-		state.syncState = void 0;
-		state.error = void 0;
-		if (state.localState === null) {
-			state.localState = void 0;
-			state.isSetOperation = false;
-			if (autosaveTimeout) {
-				clearTimeout(autosaveTimeout);
-				autosaveTimeout = null;
-			}
-		}
-		if (state.waitingForUpdate) {
-			state.waitingForUpdate = false;
-			state.inflightLocalState = void 0;
-		}
-		if (minLoadTimeElapsed) state.isLoading = false;
-		loaded = true;
-		notify();
-	};
 	const handleError = (error) => {
 		if (retryOnError) {
-			console.warn("Document listener error, retrying:", error);
+			console.warn("Collection listener error, retrying:", error);
 			retryTimeout = setTimeout(() => {
 				stop();
-				load();
+				startListener();
 			}, retryInterval);
 		} else {
 			state.error = error;
 			state.isLoading = false;
 			loaded = true;
 			store.reportError(error, {
-				type: "document",
-				path: `${collectionPath}/${documentId}`,
+				type: "collection",
+				path: collectionPath,
 				operation: "read"
 			});
 			notify();
 		}
 	};
-	const load = () => {
+	const startListener = () => {
 		if (unsubscribeListener) return;
 		loaded = false;
 		minLoadTimeElapsed = false;
-		unsubscribeListener = onSnapshot(docRef, (snapshot) => {
-			if (snapshot.exists()) handleSnapshot(snapshot.data());
-			else if (!snapshot.metadata.fromCache) handleMissingDocument();
+		unsubscribeListener = onSnapshot(buildCollectionQuery(collectionRef, definitionConstraints, extraConstraints), (snapshot) => {
+			handleSnapshot(snapshot.docs.map((docSnap) => ({
+				id: docSnap.id,
+				data: docSnap.data()
+			})));
 		}, handleError);
 		minLoadTimeout = setTimeout(() => {
 			minLoadTimeout = null;
@@ -661,7 +822,20 @@ const createDocumentSubscription = (options) => {
 			minLoadTimeElapsed = true;
 		}, minLoadTime);
 	};
+	const load = () => {
+		if (unsubscribeListener) return;
+		if (!state.isActive) {
+			state.isActive = true;
+			state.isLoading = true;
+			notify();
+		}
+		startListener();
+	};
 	const stop = () => {
+		if (retryTimeout) {
+			clearTimeout(retryTimeout);
+			retryTimeout = null;
+		}
 		if (unsubscribeListener) {
 			unsubscribeListener();
 			unsubscribeListener = null;
@@ -670,10 +844,6 @@ const createDocumentSubscription = (options) => {
 			clearTimeout(autosaveTimeout);
 			autosaveTimeout = null;
 		}
-		if (retryTimeout) {
-			clearTimeout(retryTimeout);
-			retryTimeout = null;
-		}
 		if (minLoadTimeout) {
 			clearTimeout(minLoadTimeout);
 			minLoadTimeout = null;
@@ -687,177 +857,158 @@ const createDocumentSubscription = (options) => {
 	const buildHandle = () => ({
 		data: getMergedData(),
 		update: updateState,
-		set: setData,
-		delete: deleteDocument,
-		isLoading: state.isLoading,
-		isSynced: state.localState === void 0,
+		add: addDocument,
+		remove: removeDocument,
+		isLoaded: state.isActive && !state.isLoading,
+		isActive: state.isActive,
+		load,
 		sync,
 		error: state.error,
-		ref: docRef
+		ref: collectionRef
 	});
 	const getHandle = () => {
 		if (cachedHandle === null) cachedHandle = buildHandle();
 		return cachedHandle;
 	};
+	const getState = () => {
+		if (cachedState === null) cachedState = getPublicState();
+		return cachedState;
+	};
 	return {
 		load,
 		stop,
 		subscribe,
-		getState: getPublicState,
+		getState,
 		getHandle,
 		sync
 	};
 };
 
 //#endregion
-//#region src/collection.ts
+//#region src/core/document.ts
 let syncKeyCounter = 0;
 /**
-* Build the Firestore query a collection subscription runs: `definition`-level
-* constraints first, then hook-level `extraConstraints`. With no constraints at
-* all the bare collection reference is itself a valid `Query`.
-*
-* Single source of truth for query assembly. `useCollection` decides whether a
-* fresh `queryConstraints` array is semantically the same query — and so
-* whether to keep the existing listener instead of tearing it down — by
-* building the prospective query with this exact function and comparing via
-* Firestore's `queryEqual` (see hooks.ts). That comparison is only correct if
-* it assembles the query the same way the subscription does, so both paths MUST
-* go through here. Don't re-inline the merge order at either call site.
-*/
-const buildCollectionQuery = (ref, definitionConstraints, extraConstraints) => {
-	const all = [...definitionConstraints ?? [], ...extraConstraints ?? []];
-	return all.length > 0 ? query(ref, ...all) : ref;
-};
-/**
-* Create a collection subscription.
-* This is a low-level API - prefer using useCollection hook in React.
+* Create a document subscription.
+* This is a low-level API - prefer using useDocument hook in React.
 *
 * @example
 * ```ts
-* const subscription = createCollectionSubscription({
+* const subscription = createDocumentSubscription({
 *   store,
-*   definition: spacesCollection,
-*   collectionPath: 'projects/123/spaces',
+*   definition: projectDoc,
+*   docId: '123',
 * })
 *
 * const unsubscribe = subscription.subscribe((state) => {
-*   console.log('Collection state:', state)
+*   console.log('Document state:', state)
 * })
 *
-* subscription.load() // For lazy collections
+* subscription.load()
 * ```
 */
-const createCollectionSubscription = (options) => {
-	const { store, definition, collectionPath: resolvedPath, readOnly, queryConstraints: extraConstraints, onPushUndo } = options;
+const createDocumentSubscription = (options) => {
+	const { store, definition, docId, collectionPath: resolvedCollectionPath, readOnly, onPushUndo } = options;
 	const { firestore, autosave: defaultAutosave, minLoadTime: defaultMinLoadTime } = store;
-	const { path, autosave = defaultAutosave, minLoadTime = defaultMinLoadTime, readOnly: definitionReadOnly, lazy = false, queryConstraints: definitionConstraints, retryOnError = false, retryInterval = 5e3, schema } = definition;
+	const { collection: collectionConfig, id, autosave = defaultAutosave, minLoadTime = defaultMinLoadTime, readOnly: definitionReadOnly, retryOnError = false, retryInterval = 5e3, schema } = definition;
 	const isReadOnly = readOnly ?? definitionReadOnly ?? false;
-	const collectionPath = resolvedPath ?? (typeof path === "string" ? path : void 0);
-	if (collectionPath === void 0) throw new Error(`createCollectionSubscription: definition.path is a function; pass a resolved collectionPath in options.`);
-	const collectionRef = collection(firestore, collectionPath);
+	const documentId = docId ?? (typeof id === "string" ? id : void 0);
+	if (documentId === void 0) throw new Error(`createDocumentSubscription: definition.id is a function; pass a resolved docId in options.`);
+	const collectionPath = resolvedCollectionPath ?? (typeof collectionConfig === "string" ? collectionConfig : void 0);
+	if (collectionPath === void 0) throw new Error(`createDocumentSubscription: definition.collection is a function; pass a resolved collectionPath in options.`);
+	const docRef = doc$1(collection(firestore, collectionPath), documentId);
 	const state = {
 		syncState: void 0,
 		localState: void 0,
-		isLoading: !lazy,
-		isActive: !lazy,
+		isLoading: true,
 		error: void 0,
 		waitingForUpdate: false,
 		inflightLocalState: void 0,
+		committedWrite: void 0,
+		isSetOperation: false,
 		displayOverrides: /* @__PURE__ */ new Map()
 	};
 	const subscribers = /* @__PURE__ */ new Set();
 	let unsubscribeListener = null;
 	let autosaveTimeout = null;
-	let minLoadTimeout = null;
 	let retryTimeout = null;
+	let minLoadTimeout = null;
 	let minLoadTimeElapsed = false;
 	let loaded = false;
 	let cachedHandle = null;
-	const syncKey = `col:${collectionPath}#${++syncKeyCounter}`;
+	const syncKey = `doc:${collectionPath}/${documentId}#${++syncKeyCounter}`;
 	const getMergedData = () => {
-		return applyOverridesAtPaths(state.localState ?? state.syncState ?? {}, state.displayOverrides);
+		if (state.localState === null) return void 0;
+		const base = state.localState ?? state.syncState;
+		if (base === void 0) return void 0;
+		return applyOverridesAtPaths(base, state.displayOverrides);
 	};
 	const getPublicState = () => ({
 		data: getMergedData(),
 		isLoading: state.isLoading,
+		isLoaded: !state.isLoading,
 		isSynced: state.localState === void 0,
-		isActive: state.isActive,
 		error: state.error
 	});
+	let lastPublished = null;
+	let cachedState = null;
+	const publicStateChanged = observableStateChanged;
 	const notify = () => {
-		reconcileDisplayOverrides(state.localState, state.displayOverrides);
-		cachedHandle = null;
+		reconcileDisplayOverrides(state.localState && typeof state.localState === "object" ? state.localState : void 0, state.displayOverrides);
 		const publicState = getPublicState();
+		if (lastPublished !== null && !publicStateChanged(lastPublished, publicState)) return;
+		lastPublished = publicState;
+		cachedHandle = null;
+		cachedState = publicState;
 		subscribers.forEach((fn) => fn(publicState));
 		store.reportSyncState(syncKey, publicState.isSynced);
 	};
-	const warnNoSnapshot = (method) => {
-		if (process.env.NODE_ENV !== "production") console.warn(`[firestate] ${method}() on ${collectionPath} was ignored: the first snapshot has not arrived yet. Gate calls on the collection's isLoading/isActive state, or await the first data before mutating.`);
-	};
 	const updateState = (diff, undoOptions = {}) => {
 		if (isReadOnly) return;
-		if (state.syncState === void 0) {
-			warnNoSnapshot("update");
+		if (!getMergedData()) {
+			if (process.env.NODE_ENV !== "production") console.warn(`[firestate] update() on ${collectionPath}/${documentId} was ignored: there is no current data to diff against. This happens when the document is still loading, has been deleted, or doesn't exist yet. Use set() to create the document, or gate update calls on a non-undefined data value.`);
 			return;
 		}
-		const rawBase = state.localState ?? state.syncState ?? {};
+		const rawBase = state.localState ?? state.syncState;
 		const newLocalState = deepClone(rawBase);
 		applyDiffMutable(newLocalState, diff);
-		for (const [docId, docData] of Object.entries(newLocalState)) if (docData && typeof docData === "object") docData.id = docId;
+		if (valuesEqualForNoOp(rawBase, newLocalState)) return;
 		if (undoOptions?.undoable !== false && onPushUndo) {
 			const undoDiff = computeDiff(newLocalState, rawBase);
 			const redoDiff = computeDiff(rawBase, newLocalState);
 			onPushUndo(() => updateState(undoDiff, { undoable: false }), () => updateState(redoDiff, { undoable: false }), undoOptions);
 		}
 		state.localState = newLocalState;
+		state.isSetOperation = false;
 		notify();
 		scheduleAutosave();
 	};
-	function addDocument(idOrData, dataOrOptions, maybeUndoOptions) {
-		const hasExplicitId = typeof idOrData === "string";
-		const data = hasExplicitId ? dataOrOptions : idOrData;
-		const undoOptions = (hasExplicitId ? maybeUndoOptions : dataOrOptions) ?? {};
-		if (isReadOnly) return void 0;
-		if (state.syncState === void 0) {
-			warnNoSnapshot("add");
-			return;
-		}
-		const id = hasExplicitId ? idOrData : doc$1(collectionRef).id;
-		const newDoc = {
-			...data,
-			id
-		};
-		if (schema) schema.parse(newDoc);
+	const setData = (data, undoOptions = {}) => {
+		if (isReadOnly) return;
+		if (schema) schema.parse(data);
 		const currentData = getMergedData();
-		const newLocalState = deepClone(currentData);
-		newLocalState[id] = newDoc;
+		if (currentData !== void 0 && valuesEqualForNoOp(state.localState ?? state.syncState, data)) return;
 		if (undoOptions?.undoable !== false && onPushUndo) {
-			const undoDiff = computeDiff(newLocalState, currentData);
-			const redoDiff = computeDiff(currentData, newLocalState);
-			onPushUndo(() => updateState(undoDiff, { undoable: false }), () => updateState(redoDiff, { undoable: false }), undoOptions);
+			const dataForRedo = deepClone(data);
+			if (currentData === void 0) onPushUndo(() => deleteDocument({ undoable: false }), () => setData(dataForRedo, { undoable: false }), undoOptions);
+			else {
+				const dataToRestore = deepClone(state.localState ?? state.syncState);
+				onPushUndo(() => setData(dataToRestore, { undoable: false }), () => setData(dataForRedo, { undoable: false }), undoOptions);
+			}
 		}
-		state.localState = newLocalState;
+		state.localState = deepClone(data);
+		state.isSetOperation = true;
 		notify();
 		scheduleAutosave();
-		return id;
-	}
-	const removeDocument = (id, undoOptions = {}) => {
+	};
+	const deleteDocument = (undoOptions = {}) => {
 		if (isReadOnly) return;
-		if (state.syncState === void 0) {
-			warnNoSnapshot("remove");
-			return;
-		}
-		const currentData = getMergedData();
-		if (!(id in currentData)) return;
-		const newLocalState = deepClone(currentData);
-		delete newLocalState[id];
+		if (getMergedData() === void 0) return;
 		if (undoOptions?.undoable !== false && onPushUndo) {
-			const undoDiff = computeDiff(newLocalState, currentData);
-			const redoDiff = computeDiff(currentData, newLocalState);
-			onPushUndo(() => updateState(undoDiff, { undoable: false }), () => updateState(redoDiff, { undoable: false }), undoOptions);
+			const dataToRestore = deepClone(state.localState ?? state.syncState);
+			onPushUndo(() => setData(dataToRestore, { undoable: false }), () => deleteDocument({ undoable: false }), undoOptions);
 		}
-		state.localState = newLocalState;
+		state.localState = null;
+		state.isSetOperation = false;
 		notify();
 		scheduleAutosave();
 	};
@@ -868,98 +1019,126 @@ const createCollectionSubscription = (options) => {
 		}, autosave);
 	};
 	const sync = async () => {
-		if (!state.localState) return;
-		if (state.syncState === void 0) return;
-		const syncState = state.syncState;
-		if (isDeepEqual(state.localState, syncState)) {
+		if (state.localState === void 0) return;
+		if (state.localState === null) {
+			state.inflightLocalState = null;
+			state.waitingForUpdate = true;
+			try {
+				await deleteDoc(docRef);
+			} catch (error) {
+				console.error("Sync failed:", error);
+				state.waitingForUpdate = false;
+				state.inflightLocalState = void 0;
+				state.error = error;
+				store.reportError(error, {
+					type: "document",
+					path: `${collectionPath}/${documentId}`,
+					operation: "write"
+				});
+				notify();
+			}
+			return;
+		}
+		if (state.syncState && isDeepEqual(state.localState, state.syncState)) {
 			state.localState = void 0;
 			state.inflightLocalState = void 0;
 			notify();
 			return;
 		}
-		const diff = computeDiff(syncState, state.localState);
-		state.inflightLocalState = deepClone(state.localState);
+		const wasSetOperation = state.isSetOperation;
+		state.isSetOperation = false;
+		const isCreation = !state.syncState;
+		const useSetDoc = wasSetOperation || isCreation;
+		const diff = state.syncState ? computeDiff(state.syncState, state.localState) : void 0;
+		const committing = deepClone(state.localState);
+		state.inflightLocalState = committing;
 		state.waitingForUpdate = true;
 		try {
-			const batch = writeBatch(firestore);
-			const deleteFieldSentinel = deleteField();
-			for (const [docId, docDiff] of Object.entries(diff)) {
-				const docRef = doc$1(collectionRef, docId);
-				if (docDiff !== null && typeof docDiff === "object" && "isEqual" in docDiff && typeof docDiff.isEqual === "function" && docDiff.isEqual(deleteFieldSentinel)) batch.delete(docRef);
-				else if (!(docId in syncState)) batch.set(docRef, docDiff);
-				else {
-					const flatDiff = flattenDiff(docDiff);
-					batch.update(docRef, flatDiff);
-				}
+			if (useSetDoc) await setDoc(docRef, state.localState);
+			else {
+				const args = diffToFieldPathArgs(diff);
+				if (args.length) await updateDoc(docRef, ...args);
 			}
-			await batch.commit();
+			state.committedWrite = committing;
 		} catch (error) {
-			console.error("Collection sync failed:", error);
+			console.error("Sync failed:", error);
 			state.waitingForUpdate = false;
 			state.inflightLocalState = void 0;
 			state.error = error;
 			store.reportError(error, {
-				type: "collection",
-				path: collectionPath,
+				type: "document",
+				path: `${collectionPath}/${documentId}`,
 				operation: "write"
 			});
 			notify();
 		}
 	};
-	const handleSnapshot = (docs) => {
-		const newSyncState = {};
-		for (const { id, data } of docs) newSyncState[id] = {
-			...data,
-			id
-		};
-		state.syncState = newSyncState;
+	const handleSnapshot = (newSyncData) => {
+		const prevSync = state.syncState;
+		state.syncState = newSyncData;
+		state.error = void 0;
+		state.waitingForUpdate = false;
+		state.inflightLocalState = void 0;
+		const committed = state.committedWrite;
+		state.committedWrite = void 0;
+		const currentLocal = state.localState;
+		if (currentLocal === null) {} else if (currentLocal !== void 0 && prevSync !== void 0) {
+			const userEdits = computeDiff(prevSync, currentLocal);
+			dropCommittedSentinels(userEdits, committed);
+			const rebasedLocalState = applyDiff(newSyncData, userEdits);
+			state.localState = isDeepEqual(rebasedLocalState, newSyncData) ? void 0 : rebasedLocalState;
+		}
+		if (minLoadTimeElapsed) state.isLoading = false;
+		loaded = true;
+		if (state.localState !== void 0) scheduleAutosave();
+		notify();
+	};
+	const handleMissingDocument = () => {
+		state.syncState = void 0;
 		state.error = void 0;
+		state.committedWrite = void 0;
+		if (state.localState === null) {
+			state.localState = void 0;
+			state.isSetOperation = false;
+			if (autosaveTimeout) {
+				clearTimeout(autosaveTimeout);
+				autosaveTimeout = null;
+			}
+		}
 		if (state.waitingForUpdate) {
 			state.waitingForUpdate = false;
-			const inflightState = state.inflightLocalState;
 			state.inflightLocalState = void 0;
-			const currentLocal = state.localState;
-			if (inflightState && currentLocal && !isDeepEqual(currentLocal, inflightState)) {
-				const changesSinceInflight = computeDiff(inflightState, currentLocal);
-				const rebasedLocalState = deepClone(newSyncState);
-				applyDiffMutable(rebasedLocalState, changesSinceInflight);
-				for (const [docId, docData] of Object.entries(rebasedLocalState)) if (docData && typeof docData === "object") docData.id = docId;
-				state.localState = rebasedLocalState;
-			} else state.localState = void 0;
 		}
 		if (minLoadTimeElapsed) state.isLoading = false;
 		loaded = true;
-		if (state.localState !== void 0) scheduleAutosave();
 		notify();
 	};
 	const handleError = (error) => {
 		if (retryOnError) {
-			console.warn("Collection listener error, retrying:", error);
+			console.warn("Document listener error, retrying:", error);
 			retryTimeout = setTimeout(() => {
 				stop();
-				startListener();
+				load();
 			}, retryInterval);
 		} else {
 			state.error = error;
 			state.isLoading = false;
 			loaded = true;
 			store.reportError(error, {
-				type: "collection",
-				path: collectionPath,
+				type: "document",
+				path: `${collectionPath}/${documentId}`,
 				operation: "read"
 			});
 			notify();
 		}
 	};
-	const startListener = () => {
+	const load = () => {
 		if (unsubscribeListener) return;
 		loaded = false;
 		minLoadTimeElapsed = false;
-		unsubscribeListener = onSnapshot(buildCollectionQuery(collectionRef, definitionConstraints, extraConstraints), (snapshot) => {
-			handleSnapshot(snapshot.docs.map((docSnap) => ({
-				id: docSnap.id,
-				data: docSnap.data()
-			})));
+		unsubscribeListener = onSnapshot(docRef, (snapshot) => {
+			if (snapshot.exists()) handleSnapshot(snapshot.data());
+			else if (!snapshot.metadata.fromCache) handleMissingDocument();
 		}, handleError);
 		minLoadTimeout = setTimeout(() => {
 			minLoadTimeout = null;
@@ -970,20 +1149,7 @@ const createCollectionSubscription = (options) => {
 			minLoadTimeElapsed = true;
 		}, minLoadTime);
 	};
-	const load = () => {
-		if (unsubscribeListener) return;
-		if (!state.isActive) {
-			state.isActive = true;
-			state.isLoading = true;
-			notify();
-		}
-		startListener();
-	};
 	const stop = () => {
-		if (retryTimeout) {
-			clearTimeout(retryTimeout);
-			retryTimeout = null;
-		}
 		if (unsubscribeListener) {
 			unsubscribeListener();
 			unsubscribeListener = null;
@@ -992,6 +1158,10 @@ const createCollectionSubscription = (options) => {
 			clearTimeout(autosaveTimeout);
 			autosaveTimeout = null;
 		}
+		if (retryTimeout) {
+			clearTimeout(retryTimeout);
+			retryTimeout = null;
+		}
 		if (minLoadTimeout) {
 			clearTimeout(minLoadTimeout);
 			minLoadTimeout = null;
@@ -1005,32 +1175,279 @@ const createCollectionSubscription = (options) => {
 	const buildHandle = () => ({
 		data: getMergedData(),
 		update: updateState,
-		add: addDocument,
-		remove: removeDocument,
-		isLoading: state.isLoading,
-		isSynced: state.localState === void 0,
-		isActive: state.isActive,
-		load,
+		set: setData,
+		delete: deleteDocument,
+		isLoaded: !state.isLoading,
 		sync,
 		error: state.error,
-		ref: collectionRef
+		ref: docRef
 	});
 	const getHandle = () => {
 		if (cachedHandle === null) cachedHandle = buildHandle();
 		return cachedHandle;
 	};
+	const getState = () => {
+		if (cachedState === null) cachedState = getPublicState();
+		return cachedState;
+	};
 	return {
 		load,
 		stop,
 		subscribe,
-		getState: getPublicState,
+		getState,
 		getHandle,
 		sync
 	};
 };
 
 //#endregion
-//#region src/hooks.ts
+//#region src/core/shared-subscription.ts
+const registries = /* @__PURE__ */ new WeakMap();
+const getRegistry = (store) => {
+	let reg = registries.get(store);
+	if (!reg) {
+		reg = {
+			docs: /* @__PURE__ */ new WeakMap(),
+			cols: /* @__PURE__ */ new WeakMap()
+		};
+		registries.set(store, reg);
+	}
+	return reg;
+};
+const docKey = (collectionPath, docId) => `${collectionPath}\0${docId}`;
+const colBucketKey = (collectionPath) => collectionPath;
+/**
+* Semantic query match, hardened for two cases the raw `queryEqual` does not
+* cover here: the same reference (the common case — a hook reuses its memoized
+* query) short-circuits true, and a `queryEqual` that throws (test harnesses
+* that mock the query builders pass non-`Query` placeholders) is treated as a
+* non-match rather than crashing the lookup.
+*/
+const sameQuery = (a, b) => {
+	if (a === b) return true;
+	try {
+		return queryEqual(a, b);
+	} catch {
+		return false;
+	}
+};
+/** Push to the store-global undo manager, gated by the entry's shared flag. */
+const makeOnPushUndo = (store, entry) => (undoAction, redoAction, opts) => {
+	if (!entry.undoableEnabled) return;
+	store.undoManager.push({
+		undo: undoAction,
+		redo: redoAction,
+		groupId: opts?.undoGroupId
+	});
+};
+const noop = () => {};
+const asyncNoop = async () => {};
+const noopAdd = () => void 0;
+const readOnlyDocumentHandle = (handle) => ({
+	...handle,
+	update: noop,
+	set: noop,
+	delete: noop,
+	sync: asyncNoop
+});
+const readOnlyCollectionHandle = (handle) => ({
+	...handle,
+	update: noop,
+	add: noopAdd,
+	remove: noop,
+	sync: asyncNoop
+});
+/**
+* Find or create the shared subscription for a document resource and return a
+* facade bound to it. Creating the entry attaches no listener. Intended to be
+* called from a hook's render-phase `useMemo`.
+*/
+const getDocumentShared = ({ store, definition, collectionPath, docId, readOnly }) => {
+	const map = getDocMap(store, definition);
+	const key = docKey(collectionPath, docId);
+	const facadeReadOnly = readOnly ?? definition.readOnly ?? false;
+	const buildSub = (entry) => createDocumentSubscription({
+		store,
+		definition,
+		docId,
+		collectionPath,
+		readOnly: false,
+		onPushUndo: makeOnPushUndo(store, entry)
+	});
+	const buildEntry = () => {
+		const entry = {
+			sub: null,
+			refCount: 0,
+			undoableEnabled: true,
+			live: true
+		};
+		entry.sub = buildSub(entry);
+		return entry;
+	};
+	let ent = map.get(key) ?? buildEntry();
+	let desiredUndoable = true;
+	let readOnlySource = null;
+	let readOnlyHandle = null;
+	return {
+		getHandle: () => {
+			const handle = ent.sub.getHandle();
+			if (!facadeReadOnly) return handle;
+			if (handle !== readOnlySource) {
+				readOnlySource = handle;
+				readOnlyHandle = readOnlyDocumentHandle(handle);
+			}
+			return readOnlyHandle;
+		},
+		getState: () => ent.sub.getState(),
+		load: () => ent.sub.load(),
+		setUndoable: (enabled) => {
+			if (facadeReadOnly) return;
+			desiredUndoable = enabled;
+			ent.undoableEnabled = enabled;
+		},
+		acquire: (onChange) => {
+			const committed = map.get(key);
+			if (committed) ent = committed;
+			else map.set(key, ent);
+			if (!ent.live) {
+				ent.sub = buildSub(ent);
+				ent.live = true;
+			}
+			if (!facadeReadOnly) ent.undoableEnabled = desiredUndoable;
+			ent.refCount++;
+			const notifyUnsub = ent.sub.subscribe(onChange);
+			let released = false;
+			return () => {
+				if (released) return;
+				released = true;
+				notifyUnsub();
+				ent.refCount--;
+				if (ent.refCount <= 0) {
+					ent.sub.stop();
+					ent.live = false;
+					if (map.get(key) === ent) map.delete(key);
+				}
+			};
+		}
+	};
+};
+const getDocMap = (store, definition) => {
+	const reg = getRegistry(store);
+	let map = reg.docs.get(definition);
+	if (!map) {
+		map = /* @__PURE__ */ new Map();
+		reg.docs.set(definition, map);
+	}
+	return map;
+};
+/**
+* Find or create the shared subscription whose query is `queryEqual` to
+* `params.query` and return a facade bound to it. Entries on the same path but
+* with a different query coexist in the same bucket.
+*/
+const getCollectionShared = ({ store, definition, collectionPath, readOnly, queryConstraints, query: query$1 }) => {
+	const bucket = getColBucket(store, definition, collectionPath);
+	const facadeReadOnly = readOnly ?? definition.readOnly ?? false;
+	const buildSub = (entry) => createCollectionSubscription({
+		store,
+		definition,
+		collectionPath,
+		readOnly: false,
+		queryConstraints,
+		onPushUndo: makeOnPushUndo(store, entry)
+	});
+	const buildEntry = () => {
+		const entry = {
+			sub: null,
+			refCount: 0,
+			undoableEnabled: true,
+			live: true,
+			query: query$1
+		};
+		entry.sub = buildSub(entry);
+		return entry;
+	};
+	let ent = bucket.find((e) => sameQuery(e.query, query$1)) ?? buildEntry();
+	let desiredUndoable = true;
+	let readOnlySource = null;
+	let readOnlyHandle = null;
+	return {
+		getHandle: () => {
+			const handle = ent.sub.getHandle();
+			if (!facadeReadOnly) return handle;
+			if (handle !== readOnlySource) {
+				readOnlySource = handle;
+				readOnlyHandle = readOnlyCollectionHandle(handle);
+			}
+			return readOnlyHandle;
+		},
+		getState: () => ent.sub.getState(),
+		load: () => ent.sub.load(),
+		setUndoable: (enabled) => {
+			if (facadeReadOnly) return;
+			desiredUndoable = enabled;
+			ent.undoableEnabled = enabled;
+		},
+		acquire: (onChange) => {
+			const committed = bucket.find((e) => sameQuery(e.query, query$1));
+			if (committed) ent = committed;
+			else bucket.push(ent);
+			if (!ent.live) {
+				ent.sub = buildSub(ent);
+				ent.live = true;
+			}
+			if (!facadeReadOnly) ent.undoableEnabled = desiredUndoable;
+			ent.refCount++;
+			const notifyUnsub = ent.sub.subscribe(onChange);
+			let released = false;
+			return () => {
+				if (released) return;
+				released = true;
+				notifyUnsub();
+				ent.refCount--;
+				if (ent.refCount <= 0) {
+					ent.sub.stop();
+					ent.live = false;
+					const idx = bucket.indexOf(ent);
+					if (idx !== -1) bucket.splice(idx, 1);
+				}
+			};
+		}
+	};
+};
+const getColBucket = (store, definition, collectionPath) => {
+	const reg = getRegistry(store);
+	let byKey = reg.cols.get(definition);
+	if (!byKey) {
+		byKey = /* @__PURE__ */ new Map();
+		reg.cols.set(definition, byKey);
+	}
+	const key = colBucketKey(collectionPath);
+	let bucket = byKey.get(key);
+	if (!bucket) {
+		bucket = [];
+		byKey.set(key, bucket);
+	}
+	return bucket;
+};
+/**
+* Build the query a collection hook would subscribe to, or `null` when the
+* constraints cannot form a valid query (e.g. a gated empty-`in` placeholder
+* Firestore refuses to construct). The hook only resolves a shared entry when
+* this is non-null — matching the lazy-before-load and `enabled`-gating
+* contracts where no listener should run yet.
+*/
+const buildSharedCollectionQuery = (store, collectionPath, definitionConstraints, extraConstraints) => {
+	const ref = collection(store.firestore, collectionPath);
+	try {
+		return buildCollectionQuery(ref, definitionConstraints, extraConstraints);
+	} catch {
+		return null;
+	}
+};
+
+//#endregion
+//#region src/react/hooks.ts
 /**
 * Whether two hook-level `queryConstraints` arrays produce the same Firestore
 * query for a collection. `QueryConstraint` objects are opaque, so instead of
@@ -1073,8 +1490,7 @@ const DISABLED_DOCUMENT_HANDLE = {
 	update: NOOP,
 	set: NOOP,
 	delete: NOOP,
-	isLoading: false,
-	isSynced: true,
+	isLoaded: false,
 	sync: ASYNC_NOOP,
 	error: void 0,
 	ref: void 0
@@ -1085,14 +1501,37 @@ const DISABLED_COLLECTION_HANDLE = {
 	update: NOOP,
 	add: DISABLED_ADD,
 	remove: NOOP,
-	isLoading: false,
-	isSynced: true,
+	isLoaded: false,
 	isActive: false,
 	load: NOOP,
 	sync: ASYNC_NOOP,
 	error: void 0,
 	ref: void 0
 };
+const DISABLED_DOCUMENT_STATE = {
+	data: void 0,
+	isLoading: false,
+	isLoaded: false,
+	isSynced: true,
+	error: void 0
+};
+const DISABLED_COLLECTION_STATE = {
+	data: EMPTY_RECORD,
+	isLoading: false,
+	isLoaded: false,
+	isSynced: true,
+	isActive: false,
+	error: void 0
+};
+/**
+* Equality over a {@link DefaultSelection} (no-selector path): `isLoaded`,
+* `error`, and a collection's `isActive` compared by identity, the `data` slice
+* by `dataEqual` (the default value comparison). `isSynced` is absent by design,
+* so a sync flip cannot re-render the plain handle; a change to value-equal
+* `data` is still collapsed, while a load transition re-renders.
+*/
+const defaultSelectionEqual = (a, b, dataEqual) => a.isLoaded === b.isLoaded && a.error === b.error && a.isActive === b.isActive && dataEqual(a.data, b.data);
+const defaultDataEqual = valuesEqualForNoOp;
 /**
 * Context for providing the Firestate store
 */
@@ -1130,169 +1569,78 @@ const useIsSynced = () => {
 	const getSnapshot = useCallback(() => store.isSynced, [store]);
 	return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
 };
-/**
-* Hook to subscribe to a Firestore document with real-time updates.
-*
-* The subscription is keyed on the resolved document path (`definition` +
-* computed id) and `readOnly`. When that key changes — typically because
-* `params` produces a different id — the hook tears down the old Firestore
-* listener and attaches a new one. Toggling `undoable` does not rebuild the
-* subscription.
-*
-* Use `enabled: false` to suppress the subscription entirely (e.g., when
-* route params aren't ready yet).
-*
-* **SSR.** On the server there is no Firestore listener, so this hook returns
-* the initial handle (`{ data: undefined, isLoading: true }`). Mutations like
-* `update`/`set` will mutate orphaned local state with no effect — avoid
-* calling them server-side.
-*
-* @example
-* ```tsx
-* const projectDoc = defineDocument<Project>({
-*   collection: 'projects',
-*   id: (params) => params.projectId,
-* })
-*
-* function ProjectEditor({ projectId }: { projectId: string }) {
-*   const { data, update, isLoading, isSynced } = useDocument({
-*     definition: projectDoc,
-*     params: { projectId },
-*   })
-*
-*   if (isLoading) return <Spinner />
-*
-*   return (
-*     <input
-*       value={data?.name ?? ''}
-*       onChange={(e) => update({ name: e.target.value })}
-*     />
-*   )
-* }
-* ```
-*/
-const useDocument = (options) => {
-	const { definition, params = {}, readOnly, undoable = true, enabled = true } = options;
+function useDocument(options) {
+	const { definition, params = {}, readOnly, undoable = true, enabled = true, selector, isEqual } = options;
 	const store = useStore();
-	const undoManager = store.undoManager;
-	const undoableRef = useRef(undoable);
-	undoableRef.current = undoable;
-	const onPushUndo = useCallback((undoAction, redoAction, opts) => {
-		if (!undoableRef.current) return;
-		undoManager.push({
-			undo: undoAction,
-			redo: redoAction,
-			groupId: opts?.undoGroupId
-		});
-	}, [undoManager]);
 	const docId = enabled ? typeof definition.id === "function" ? definition.id(params) : definition.id : void 0;
 	const collectionPath = enabled ? typeof definition.collection === "function" ? definition.collection(params) : definition.collection : void 0;
-	const subscription = useMemo(() => enabled && docId !== void 0 && collectionPath !== void 0 ? createDocumentSubscription({
+	const shared = useMemo(() => enabled && docId !== void 0 && collectionPath !== void 0 ? getDocumentShared({
 		store,
 		definition,
-		docId,
 		collectionPath,
-		readOnly,
-		onPushUndo
+		docId,
+		readOnly
 	}) : null, [
 		enabled,
 		store,
 		definition,
 		docId,
 		collectionPath,
-		readOnly,
-		onPushUndo
+		readOnly
 	]);
+	useEffect(() => {
+		shared?.setUndoable(undoable);
+	}, [shared, undoable]);
 	const subscribe = useCallback((onChange) => {
-		if (!subscription) return NOOP;
-		const unsub = subscription.subscribe(() => onChange());
-		subscription.load();
-		return () => {
-			unsub();
-			subscription.stop();
+		if (!shared) return NOOP;
+		shared.setUndoable(undoable);
+		const release = shared.acquire(onChange);
+		try {
+			shared.load();
+		} catch (e) {
+			release();
+			throw e;
+		}
+		return release;
+	}, [shared]);
+	const getStateSnapshot = useCallback(() => shared ? shared.getState() : DISABLED_DOCUMENT_STATE, [shared]);
+	const getHandle = useCallback(() => shared ? shared.getHandle() : DISABLED_DOCUMENT_HANDLE, [shared]);
+	const selection = useSyncExternalStoreWithSelector(subscribe, getStateSnapshot, getStateSnapshot, useCallback((state) => selector ? selector(state) : {
+		data: state.data,
+		isLoaded: state.isLoaded,
+		error: state.error
+	}, [selector]), useCallback((a, b) => selector ? (isEqual ?? defaultDataEqual)(a, b) : defaultSelectionEqual(a, b, defaultDataEqual), [selector, isEqual]));
+	const hasSelector = selector != null;
+	return useMemo(() => {
+		const handle = getHandle();
+		if (hasSelector) return {
+			data: selection,
+			update: handle.update,
+			set: handle.set,
+			delete: handle.delete,
+			sync: handle.sync,
+			ref: handle.ref
 		};
-	}, [subscription]);
-	const getSnapshot = useCallback(() => subscription ? subscription.getHandle() : DISABLED_DOCUMENT_HANDLE, [subscription]);
-	return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
-};
-/**
-* Hook to subscribe to a Firestore collection with real-time updates.
-*
-* The subscription is keyed on the resolved collection path, `readOnly`, and
-* the *semantic identity* of `queryConstraints`. When any of these change, the
-* listener is torn down and re-attached with the new query. Toggling
-* `undoable` does not rebuild the subscription.
-*
-* **You do not need to memoize `queryConstraints`.** `QueryConstraint` objects
-* are opaque, so Firestate compares the *built query* with Firestore's own
-* `queryEqual` instead of comparing array references. A fresh array that
-* produces the same query (e.g. constraint inputs read from a document that
-* Firestate deep-clones on optimistic updates) does not rebuild the listener;
-* only a genuine change to the query does:
-*
-* ```tsx
-* // stationIds may change reference on every edit to its parent document,
-* // even when its contents are unchanged — the listener survives anyway.
-* const stations = useCollection({
-*   definition: weatherStations,
-*   queryConstraints: [where(documentId(), 'in', stationIds)],
-* })
-* ```
-*
-* Memoizing is still a fine micro-optimization (it skips the per-render query
-* build + compare via the reference fast-path), but it is no longer required
-* for listener stability.
-*
-* Use `enabled: false` to suppress the subscription entirely (e.g., when
-* route params aren't ready yet).
-*
-* **SSR.** On the server there is no Firestore listener, so this hook returns
-* the initial handle (`{ data: {}, isLoading: true }` for non-lazy, or
-* `isActive: false` for lazy). Avoid calling mutations server-side.
-*
-* @example
-* ```tsx
-* const spacesCollection = defineCollection<Space>({
-*   path: (params) => `projects/${params.projectId}/spaces`,
-*   lazy: true,
-* })
-*
-* function SpacesList({ projectId }: { projectId: string }) {
-*   const { data, update, load, isActive, isLoading } = useCollection({
-*     definition: spacesCollection,
-*     params: { projectId },
-*   })
-*
-*   // Lazy load on mount
-*   useEffect(() => { load() }, [load])
-*
-*   if (!isActive) return <Button onClick={load}>Load Spaces</Button>
-*   if (isLoading) return <Spinner />
-*
-*   return (
-*     <ul>
-*       {Object.values(data).map((space) => (
-*         <li key={space.id}>{space.name}</li>
-*       ))}
-*     </ul>
-*   )
-* }
-* ```
-*/
-const useCollection = (options) => {
-	const { definition, params = {}, readOnly, queryConstraints, undoable = true, enabled = true } = options;
+		const s = selection;
+		return {
+			data: s.data,
+			update: handle.update,
+			set: handle.set,
+			delete: handle.delete,
+			isLoaded: s.isLoaded,
+			sync: handle.sync,
+			error: s.error,
+			ref: handle.ref
+		};
+	}, [
+		selection,
+		getHandle,
+		hasSelector
+	]);
+}
+function useCollection(options) {
+	const { definition, params = {}, readOnly, queryConstraints, undoable = true, enabled = true, selector, isEqual } = options;
 	const store = useStore();
-	const undoManager = store.undoManager;
-	const undoableRef = useRef(undoable);
-	undoableRef.current = undoable;
-	const onPushUndo = useCallback((undoAction, redoAction, opts) => {
-		if (!undoableRef.current) return;
-		undoManager.push({
-			undo: undoAction,
-			redo: redoAction,
-			groupId: opts?.undoGroupId
-		});
-	}, [undoManager]);
 	const collectionPath = enabled ? typeof definition.path === "function" ? definition.path(params) : definition.path : void 0;
 	const stableConstraintsRef = useRef(queryConstraints);
 	const stableActiveRef = useRef(false);
@@ -1300,35 +1648,170 @@ const useCollection = (options) => {
 	if (collectionPath === void 0 || !stableActiveRef.current || !queryConstraintsEqual(store.firestore, collectionPath, definition.queryConstraints, stableConstraintsRef.current, queryConstraints)) stableConstraintsRef.current = queryConstraints;
 	stableActiveRef.current = active;
 	const stableConstraints = stableConstraintsRef.current;
-	const subscription = useMemo(() => enabled && collectionPath !== void 0 ? createCollectionSubscription({
+	const isLazy = definition.lazy ?? false;
+	const builtQuery = useMemo(() => active ? buildSharedCollectionQuery(store, collectionPath, definition.queryConstraints, stableConstraints) : null, [
+		active,
+		store,
+		collectionPath,
+		definition,
+		stableConstraints
+	]);
+	const shared = useMemo(() => active && builtQuery !== null ? getCollectionShared({
 		store,
 		definition,
 		collectionPath,
 		readOnly,
 		queryConstraints: stableConstraints,
-		onPushUndo
+		query: builtQuery
 	}) : null, [
-		enabled,
+		active,
 		store,
 		definition,
 		collectionPath,
 		readOnly,
 		stableConstraints,
-		onPushUndo
+		builtQuery
 	]);
-	const isLazy = definition.lazy ?? false;
+	useEffect(() => {
+		shared?.setUndoable(undoable);
+	}, [shared, undoable]);
 	const subscribe = useCallback((onChange) => {
-		if (!subscription) return NOOP;
-		const unsub = subscription.subscribe(() => onChange());
-		if (!isLazy) subscription.load();
-		return () => {
-			unsub();
-			subscription.stop();
+		if (!shared) return NOOP;
+		shared.setUndoable(undoable);
+		const release = shared.acquire(onChange);
+		if (!isLazy) try {
+			shared.load();
+		} catch (e) {
+			release();
+			throw e;
+		}
+		return release;
+	}, [shared, isLazy]);
+	const getStateSnapshot = useCallback(() => shared ? shared.getState() : DISABLED_COLLECTION_STATE, [shared]);
+	const getHandle = useCallback(() => shared ? shared.getHandle() : DISABLED_COLLECTION_HANDLE, [shared]);
+	const selection = useSyncExternalStoreWithSelector(subscribe, getStateSnapshot, getStateSnapshot, useCallback((state) => selector ? selector(state) : {
+		data: state.data,
+		isLoaded: state.isLoaded,
+		isActive: state.isActive,
+		error: state.error
+	}, [selector]), useCallback((a, b) => selector ? (isEqual ?? defaultDataEqual)(a, b) : defaultSelectionEqual(a, b, defaultDataEqual), [selector, isEqual]));
+	const hasSelector = selector != null;
+	return useMemo(() => {
+		const handle = getHandle();
+		if (hasSelector) return {
+			data: selection,
+			update: handle.update,
+			add: handle.add,
+			remove: handle.remove,
+			load: handle.load,
+			sync: handle.sync,
+			ref: handle.ref
 		};
-	}, [subscription, isLazy]);
-	const getSnapshot = useCallback(() => subscription ? subscription.getHandle() : DISABLED_COLLECTION_HANDLE, [subscription]);
-	return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
-};
+		const s = selection;
+		return {
+			data: s.data,
+			update: handle.update,
+			add: handle.add,
+			remove: handle.remove,
+			isLoaded: s.isLoaded,
+			isActive: s.isActive ?? false,
+			load: handle.load,
+			sync: handle.sync,
+			error: s.error,
+			ref: handle.ref
+		};
+	}, [
+		selection,
+		getHandle,
+		hasSelector
+	]);
+}
+const syncStatusSelector = (state) => ({
+	isSynced: state.isSynced,
+	isSaving: !state.isSynced
+});
+const loadingStatusSelector = (state) => ({
+	isLoading: state.isLoading,
+	isLoaded: state.isLoaded
+});
+/**
+* Subscribe to a document's **sync status only** — `{ isSynced, isSaving }`.
+*
+* The opt-in counterpart to the sync-agnostic default handle (see
+* {@link DocumentHandle}): it re-renders when sync state flips but never on data
+* changes, and shares the resource's one `onSnapshot` listener with
+* `useDocument` and any slice hooks, so opting in adds no listener. While
+* disabled it reports `{ isSynced: true, isSaving: false }`.
+*/
+function useDocumentSyncStatus(options) {
+	return useDocument({
+		definition: options.definition,
+		params: options.params,
+		enabled: options.enabled,
+		readOnly: true,
+		selector: syncStatusSelector
+	}).data;
+}
+/**
+* Subscribe to a document's **loading status only** — `{ isLoading, isLoaded }`.
+*
+* A spinner channel that shares the resource's listener and does NOT re-render
+* on data changes — for a progress indicator rendered apart from the data. The
+* data handle keeps `isLoaded` for the common render path; this is an extra
+* channel, not a replacement.
+*/
+function useDocumentLoadingStatus(options) {
+	return useDocument({
+		definition: options.definition,
+		params: options.params,
+		enabled: options.enabled,
+		readOnly: true,
+		selector: loadingStatusSelector
+	}).data;
+}
+/**
+* Collection counterpart of {@link useDocumentSyncStatus} — `{ isSynced,
+* isSaving }` over a collection query, sharing its one listener.
+*
+* **Lazy caveat.** On a `lazy` collection this hook never calls `load()` itself:
+* activating a lazy listener is the data hook's job, and a passive status reader
+* must not silently start the listener (and bill the reads) the laziness exists
+* to defer. As the *lone* subscriber it therefore attaches no listener and stays
+* at the idle `{ isSynced: true, isSaving: false }`. Mount it alongside a
+* {@link useCollection} on the same query whose `load()` has run — the status
+* hook rides that one shared listener and reports real sync state. Non-lazy
+* collections activate on mount, so this hook works standalone there.
+*/
+function useCollectionSyncStatus(options) {
+	return useCollection({
+		definition: options.definition,
+		params: options.params,
+		queryConstraints: options.queryConstraints,
+		enabled: options.enabled,
+		readOnly: true,
+		selector: syncStatusSelector
+	}).data;
+}
+/**
+* Collection counterpart of {@link useDocumentLoadingStatus} — `{ isLoading,
+* isLoaded }` over a collection query, sharing its one listener.
+*
+* Same lazy caveat as {@link useCollectionSyncStatus}: on a `lazy` collection it
+* never calls `load()`, so as the lone subscriber it attaches no listener and
+* stays at the idle `{ isLoading: false, isLoaded: false }` until a co-mounted
+* {@link useCollection} (or any active hook on the same query) activates the
+* shared listener via `load()`. Non-lazy collections activate on mount.
+*/
+function useCollectionLoadingStatus(options) {
+	return useCollection({
+		definition: options.definition,
+		params: options.params,
+		queryConstraints: options.queryConstraints,
+		enabled: options.enabled,
+		readOnly: true,
+		selector: loadingStatusSelector
+	}).data;
+}
 /**
 * Keyboard shortcut hook for undo/redo
 *
@@ -1359,7 +1842,7 @@ const useUndoKeyboardShortcuts = () => {
 };
 
 //#endregion
-//#region src/firestate.ts
+//#region src/registry/firestate.ts
 /**
 * Registry-driven Firestate API.
 *
@@ -1394,6 +1877,10 @@ const useUndoKeyboardShortcuts = () => {
 * directly — that escape hatch keeps the plain-TypeScript form, at the
 * cost of looser param typing on the hook and no runtime validation.
 *
+* `path` may also be a function returning the full document path at runtime —
+* for paths that branch on a param. Param keys can't be inferred from a
+* function, so they fall back to `Record<string, string>`. See {@link PathArg}.
+*
 * ```ts
 * import { z } from 'zod'
 *
@@ -1404,26 +1891,43 @@ const useUndoKeyboardShortcuts = () => {
 */
 function doc(opts) {
 	const { path, ...rest } = opts;
-	validateTemplate(path);
-	splitDocPath(path);
-	return {
+	if (typeof path === "string") {
+		validateTemplate(path);
+		splitDocPath(path);
+	}
+	const entry = {
 		__kind: "document",
 		path,
 		...rest
 	};
+	entry.select = (selector, options) => ({
+		__kind: "document-selected",
+		base: entry,
+		selector,
+		isEqual: options?.isEqual
+	});
+	return entry;
 }
 /**
 * Declare a collection entry for a Firestate registry. See {@link doc}
-* for the schema/typing contract.
+* for the schema/typing contract. `path` may also be a function returning
+* the collection path at runtime — see {@link PathArg}.
 */
 function col(opts) {
 	const { path, ...rest } = opts;
-	validateTemplate(path);
-	return {
+	if (typeof path === "string") validateTemplate(path);
+	const entry = {
 		__kind: "collection",
 		path,
 		...rest
 	};
+	entry.select = (selector, options) => ({
+		__kind: "collection-selected",
+		base: entry,
+		selector,
+		isEqual: options?.isEqual
+	});
+	return entry;
 }
 /**
 * Turn a Firestate registry into a map of typed React hooks. Each entry
@@ -1438,24 +1942,84 @@ function col(opts) {
 */
 function createFirestate(registry) {
 	const api = {};
+	const docDefs = /* @__PURE__ */ new Map();
+	const colDefs = /* @__PURE__ */ new Map();
+	const docDefFor = (base) => {
+		let def = docDefs.get(base);
+		if (!def) {
+			def = buildDocumentDefinition(base);
+			docDefs.set(base, def);
+		}
+		return def;
+	};
+	const colDefFor = (base) => {
+		let def = colDefs.get(base);
+		if (!def) {
+			def = buildCollectionDefinition(base);
+			colDefs.set(base, def);
+		}
+		return def;
+	};
 	for (const key of Object.keys(registry)) {
 		if (!isValidKey(key)) throw new Error(`[firestate] registry key "${key}" must start with a letter and contain only letters, digits, _ or $`);
 		const entry = registry[key];
 		const hookName = toHookName(key);
 		if (entry.__kind === "document") {
-			const definition = buildDocumentDefinition(entry);
+			const definition = docDefFor(entry);
 			api[hookName] = (params = {}, options = {}) => useDocument({
 				...options,
 				definition,
 				params
 			});
-		} else {
-			const definition = buildCollectionDefinition(entry);
+			api[`${hookName}SyncStatus`] = (params = {}, options = {}) => useDocumentSyncStatus({
+				definition,
+				params,
+				enabled: options.enabled
+			});
+			api[`${hookName}LoadingStatus`] = (params = {}, options = {}) => useDocumentLoadingStatus({
+				definition,
+				params,
+				enabled: options.enabled
+			});
+		} else if (entry.__kind === "collection") {
+			const definition = colDefFor(entry);
 			api[hookName] = (params = {}, options = {}) => useCollection({
 				...options,
 				definition,
 				params
 			});
+			api[`${hookName}SyncStatus`] = (params = {}, options = {}) => useCollectionSyncStatus({
+				definition,
+				params,
+				enabled: options.enabled,
+				queryConstraints: options.queryConstraints
+			});
+			api[`${hookName}LoadingStatus`] = (params = {}, options = {}) => useCollectionLoadingStatus({
+				definition,
+				params,
+				enabled: options.enabled,
+				queryConstraints: options.queryConstraints
+			});
+		} else if (entry.__kind === "document-selected") {
+			const definition = docDefFor(entry.base);
+			const { selector, isEqual } = entry;
+			api[hookName] = (params = {}, options = {}) => useDocument({
+				...options,
+				definition,
+				params,
+				selector: (state) => selector(state, params),
+				isEqual
+			});
+		} else {
+			const definition = colDefFor(entry.base);
+			const { selector, isEqual } = entry;
+			api[hookName] = (params = {}, options = {}) => useCollection({
+				...options,
+				definition,
+				params,
+				selector: (state) => selector(state, params),
+				isEqual
+			});
 		}
 	}
 	return api;
@@ -1468,16 +2032,25 @@ function createFirestate(registry) {
 * @internal
 */
 function buildDocumentDefinition(entry) {
-	const { collectionPath, idTemplate } = splitDocPath(entry.path);
-	return defineDocument({
+	const { path } = entry;
+	const common = {
 		schema: entry.schema,
-		collection: (params) => interpolate(collectionPath, params),
-		id: (params) => interpolate(idTemplate, params),
 		autosave: entry.autosave,
 		minLoadTime: entry.minLoadTime,
 		readOnly: entry.readOnly,
 		retryOnError: entry.retryOnError,
 		retryInterval: entry.retryInterval
+	};
+	if (typeof path === "function") return defineDocument({
+		...common,
+		collection: (params) => splitDocPath(path(params)).collectionPath,
+		id: (params) => splitDocPath(path(params)).idTemplate
+	});
+	const { collectionPath, idTemplate } = splitDocPath(path);
+	return defineDocument({
+		...common,
+		collection: (params) => interpolate(collectionPath, params),
+		id: (params) => interpolate(idTemplate, params)
 	});
 }
 /**
@@ -1486,9 +2059,10 @@ function buildDocumentDefinition(entry) {
 * @internal
 */
 function buildCollectionDefinition(entry) {
+	const { path } = entry;
 	return defineCollection({
 		schema: entry.schema,
-		path: (params) => interpolate(entry.path, params),
+		path: typeof path === "function" ? path : (params) => interpolate(path, params),
 		autosave: entry.autosave,
 		minLoadTime: entry.minLoadTime,
 		readOnly: entry.readOnly,
@@ -1544,7 +2118,48 @@ function splitDocPath(path) {
 }
 
 //#endregion
-//#region src/undo.ts
+//#region src/utils/shallow.ts
+/**
+* Shallow structural equality.
+*
+* Returns `true` when `a` and `b` are identical by `Object.is`, or are two
+* arrays / two plain objects whose entries are pairwise `Object.is`-equal one
+* level deep. Anything else (different shapes, nested objects that aren't
+* reference-equal) is `false`.
+*
+* Intended as the `isEqual` for a hook `selector` that builds a fresh array or
+* object every render — e.g. `data => Object.values(data).map(d => d.id)` or
+* `data => ({ name: data?.name, done: data?.done })`. The default selector
+* comparison is a *deep* value compare, which is correct but does more work
+* than needed for a flat projection; `shallow` re-renders on a genuine change
+* to any entry while collapsing the fresh-reference-same-entries case.
+*
+* Not recursive on purpose: if a selected entry is itself an object you mutate
+* in place rather than replace, prefer the default deep comparison or a
+* bespoke `isEqual`.
+*/
+const shallow = (a, b) => {
+	if (Object.is(a, b)) return true;
+	if (typeof a !== "object" || a === null || typeof b !== "object" || b === null) return false;
+	const aIsArray = Array.isArray(a);
+	if (aIsArray !== Array.isArray(b)) return false;
+	if (aIsArray) {
+		const arrA = a;
+		const arrB = b;
+		if (arrA.length !== arrB.length) return false;
+		for (let i = 0; i < arrA.length; i++) if (!Object.is(arrA[i], arrB[i])) return false;
+		return true;
+	}
+	const objA = a;
+	const objB = b;
+	const keysA = Object.keys(objA);
+	if (keysA.length !== Object.keys(objB).length) return false;
+	for (const key of keysA) if (!Object.prototype.hasOwnProperty.call(objB, key) || !Object.is(objA[key], objB[key])) return false;
+	return true;
+};
+
+//#endregion
+//#region src/utils/undo.ts
 /**
 * Create an undo manager instance.
 * This is a standalone, framework-agnostic implementation.
@@ -1672,7 +2287,7 @@ const createUndoManager = (config = {}) => {
 };
 
 //#endregion
-//#region src/store.ts
+//#region src/core/store.ts
 /**
 * Create a Firestate store.
 * This is the central configuration point for your Firestore state management.
@@ -1748,7 +2363,7 @@ const createStore = (config) => {
 };
 
 //#endregion
-//#region src/provider.tsx
+//#region src/react/provider.tsx
 /**
 * Provider component that sets up Firestate for your application.
 *
@@ -1851,5 +2466,5 @@ const useUnsavedChangesBlocker = () => {
 };
 
 //#endregion
-export { FirestateContext, FirestateProvider, FirestateStoreProvider, applyDiff, applyDiffMutable, col, computeDiff, computeUndoDiff, createCollectionSubscription, createDiffAtPath, createDocumentSubscription, createFirestate, createStore, createUndoManager, deepClone, defineCollection, defineDocument, diffContainsPath, doc, extractDiffValue, flattenDiff, isDeepEqual, isDiffEmpty, mergeDiffs, unflattenDiff, useCollection, useDocument, useIsSynced, useStore, useUndoKeyboardShortcuts, useUndoManager, useUnsavedChangesBlocker };
+export { FirestateContext, FirestateProvider, FirestateStoreProvider, applyDiff, applyDiffMutable, col, computeDiff, computeUndoDiff, createCollectionSubscription, createDiffAtPath, createDocumentSubscription, createFirestate, createStore, createUndoManager, deepClone, defineCollection, defineDocument, diffContainsPath, doc, extractDiffValue, flattenDiff, flattenDiffToFieldPaths, isDeepEqual, isDiffEmpty, mergeDiffs, shallow, unflattenDiff, useCollection, useCollectionLoadingStatus, useCollectionSyncStatus, useDocument, useDocumentLoadingStatus, useDocumentSyncStatus, useIsSynced, useStore, useUndoKeyboardShortcuts, useUndoManager, useUnsavedChangesBlocker };
 //# sourceMappingURL=index.mjs.map