@hvakr/firestate 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1779 @@
+import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
+import { Timestamp, collection, deleteDoc, deleteField, doc as doc$1, onSnapshot, query, serverTimestamp, setDoc, updateDoc, writeBatch } from "firebase/firestore";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/schema.ts
+function defineDocument(definition) {
+	return definition;
+}
+function defineCollection(definition) {
+	return definition;
+}
+
+//#endregion
+//#region src/diff.ts
+/**
+* Check if a value is a plain object (not array, null, or special Firestore type)
+*/
+const isPlainObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value) && !(value instanceof Timestamp) && Object.getPrototypeOf(value) === Object.prototype;
+/**
+* Check if a value is a Firestore opaque type: a FieldValue sentinel
+* (`serverTimestamp`, `deleteField`, `increment`, `arrayUnion`,
+* `arrayRemove`, …) or a value type the SDK ships with its own identity
+* semantics (`Timestamp`, `DocumentReference`, `GeoPoint`, `Bytes`,
+* `VectorValue`). They all expose `.isEqual()` and have a non-plain
+* prototype.
+*
+* The diff / clone pipeline must treat these as **opaque**: never iterate
+* their keys, never substitute their values, never compare them by `===`.
+* Doing any of those silently breaks the write path — see the C1
+* regression where `serverTimestamp()` was replaced with `Timestamp.now()`
+* before reaching Firestore.
+*/
+const isFirestoreOpaque = (value) => {
+	if (value === null || typeof value !== "object") return false;
+	if (Object.getPrototypeOf(value) === Object.prototype) return false;
+	return "isEqual" in value && typeof value.isEqual === "function";
+};
+const SERVER_TIMESTAMP_REF = serverTimestamp();
+const DELETE_FIELD_REF = deleteField();
+const isDeleteField = (value) => isFirestoreOpaque(value) && value.isEqual(DELETE_FIELD_REF);
+const isServerTimestamp = (value) => isFirestoreOpaque(value) && value.isEqual(SERVER_TIMESTAMP_REF);
+/**
+* Check if two values are deeply equal
+*/
+const isDeepEqual = (a, b) => {
+	if (a === b) return true;
+	if (a === null || b === null) return false;
+	if (typeof a !== typeof b) return false;
+	if (Array.isArray(a) && Array.isArray(b)) {
+		if (a.length !== b.length) return false;
+		return a.every((item, i) => isDeepEqual(item, b[i]));
+	}
+	if (isFirestoreOpaque(a) && isFirestoreOpaque(b)) return a.isEqual(b);
+	if (isPlainObject(a) && isPlainObject(b)) {
+		const keysA = Object.keys(a);
+		const keysB = Object.keys(b);
+		if (keysA.length !== keysB.length) return false;
+		return keysA.every((key) => isDeepEqual(a[key], b[key]));
+	}
+	return false;
+};
+/**
+* Compute the minimal diff between two objects for Firestore updates.
+* Returns only the fields that changed, using deleteField() for removed fields.
+*
+* @param from - The original object (sync state)
+* @param to - The target object (local state)
+* @returns A partial object containing only changed fields
+*/
+const computeDiff = (from, to) => {
+	if (to === void 0) return deleteField();
+	const diff = {};
+	for (const key of Object.keys(to)) {
+		const fromValue = from[key];
+		const toValue = to[key];
+		if (Array.isArray(toValue)) {
+			if (!isDeepEqual(fromValue, toValue)) diff[key] = toValue;
+			continue;
+		}
+		if (isPlainObject(toValue)) {
+			if (!isDeepEqual(fromValue, toValue)) {
+				const nestedDiff = computeDiff(fromValue ?? {}, toValue);
+				if (Object.keys(nestedDiff).length > 0) diff[key] = nestedDiff;
+			}
+			continue;
+		}
+		if (isFirestoreOpaque(toValue)) {
+			if (!isFirestoreOpaque(fromValue) || !toValue.isEqual(fromValue)) diff[key] = toValue;
+			continue;
+		}
+		if (toValue !== void 0 && fromValue !== toValue) diff[key] = toValue;
+	}
+	for (const key of Object.keys(from)) if (to[key] === void 0) diff[key] = deleteField();
+	return diff;
+};
+/**
+* Apply a Firestore diff to a target object in place (mutating).
+* Handles deleteField(), serverTimestamp(), and nested objects.
+*
+* Most code should use `applyDiff` (immutable) instead.
+* This mutable version is useful for performance-critical paths
+* where you're already working with a cloned object.
+*
+* @param target - The object to mutate
+* @param diff - The diff to apply
+*/
+const applyDiffMutable = (target, diff) => {
+	for (const key of Object.keys(diff)) {
+		const value = diff[key];
+		if (isFirestoreOpaque(value)) {
+			if (isDeleteField(value)) {
+				delete target[key];
+				continue;
+			}
+			target[key] = value;
+			continue;
+		}
+		if (isPlainObject(value)) {
+			const existingValue = target[key];
+			if (!isPlainObject(existingValue)) target[key] = {};
+			applyDiffMutable(target[key], value);
+			continue;
+		}
+		target[key] = value;
+	}
+};
+/**
+* Create a deep clone of an object that's safe for Firestore operations.
+*
+* Firestore opaque values (FieldValue sentinels, Timestamp,
+* DocumentReference, GeoPoint, Bytes, VectorValue) are returned **by
+* reference**. They are immutable from the user's perspective; cloning
+* them by walking keys would either lose their prototype — turning a
+* `DocumentReference` into a plain object Firestore can't recognize —
+* or destroy a sentinel that needed to reach the server intact.
+*/
+const deepClone = (value) => {
+	if (value === null || typeof value !== "object") return value;
+	if (isFirestoreOpaque(value)) return value;
+	if (Array.isArray(value)) return value.map(deepClone);
+	const result = {};
+	for (const key of Object.keys(value)) result[key] = deepClone(value[key]);
+	return result;
+};
+/**
+* Check if a diff is empty (no changes)
+*/
+const isDiffEmpty = (diff) => Object.keys(diff).length === 0;
+/**
+* Flatten a nested diff object to dot notation for use with Firestore's updateDoc.
+*
+* This converts:
+* ```
+* { building: { floors: 5, height: 100 }, name: 'Test' }
+* ```
+* To:
+* ```
+* { 'building.floors': 5, 'building.height': 100, 'name': 'Test' }
+* ```
+*
+* Arrays, FieldValue sentinels (deleteField, serverTimestamp, …) and
+* Firestore value types (Timestamp, DocumentReference, GeoPoint, Bytes,
+* VectorValue) are NOT flattened — they're preserved at their path so
+* Firestore receives them in their original form.
+*
+* @param diff - The nested diff object
+* @param prefix - Internal: current path prefix for recursion
+* @returns Flattened object with dotted keys
+*/
+const flattenDiff = (diff, prefix = "") => {
+	const result = {};
+	for (const key of Object.keys(diff)) {
+		const value = diff[key];
+		const path = prefix ? `${prefix}.${key}` : key;
+		if (Array.isArray(value) || isFirestoreOpaque(value)) {
+			result[path] = value;
+			continue;
+		}
+		if (isPlainObject(value)) {
+			const nested = flattenDiff(value, path);
+			Object.assign(result, nested);
+			continue;
+		}
+		result[path] = value;
+	}
+	return result;
+};
+/**
+* Merge two diffs together, with the second taking precedence
+*/
+const mergeDiffs = (first, second) => {
+	const result = deepClone(first);
+	for (const key of Object.keys(second)) {
+		const firstValue = result[key];
+		const secondValue = second[key];
+		if (isPlainObject(firstValue) && isPlainObject(secondValue)) result[key] = mergeDiffs(firstValue, secondValue);
+		else result[key] = secondValue;
+	}
+	return result;
+};
+/**
+* Apply a diff to an object, returning a new object.
+* The original object is not modified.
+*
+* @example
+* ```ts
+* const original = { name: 'Project', count: 5 }
+* const diff = { name: 'Updated', count: deleteField() }
+* const result = applyDiff(original, diff)
+* // result = { name: 'Updated' }
+* // original is unchanged
+* ```
+*/
+const applyDiff = (state, diff) => {
+	const result = deepClone(state);
+	applyDiffMutable(result, diff);
+	return result;
+};
+/**
+* Compute the undo diff that would reverse the effect of applying a diff to a state.
+*
+* Given a starting state and a diff that was (or will be) applied to it,
+* returns a new diff that when applied to the result would restore the original state.
+*
+* @example
+* ```ts
+* const startState = { name: 'Foo', count: 5 }
+* const diff = { name: 'Bar', count: deleteField() }
+*
+* // Apply the diff
+* const endState = applyDiff(startState, diff)
+* // endState = { name: 'Bar' }
+*
+* // Compute the undo
+* const undoDiff = computeUndoDiff(startState, diff)
+* // undoDiff = { name: 'Foo', count: 5 }
+*
+* // Applying undoDiff to endState restores startState
+* const restored = applyDiff(endState, undoDiff)
+* // restored = { name: 'Foo', count: 5 }
+* ```
+*/
+const computeUndoDiff = (startState, diff) => {
+	return computeDiff(applyDiff(startState, diff), startState);
+};
+/**
+* Check if a diff affects a specific path (supports dot notation).
+*
+* @example
+* ```ts
+* const diff = { building: { floors: 5 }, name: 'Test' }
+*
+* diffContainsPath(diff, 'name') // true
+* diffContainsPath(diff, 'building') // true
+* diffContainsPath(diff, 'building.floors') // true
+* diffContainsPath(diff, 'building.height') // false
+* diffContainsPath(diff, 'other') // false
+* ```
+*/
+const diffContainsPath = (diff, path) => {
+	const parts = path.split(".");
+	let current = diff;
+	for (const part of parts) {
+		if (current === null || typeof current !== "object") return false;
+		if (!(part in current)) return false;
+		current = current[part];
+	}
+	return true;
+};
+/**
+* Extract the value at a specific path from a diff (supports dot notation).
+* Returns undefined if the path doesn't exist in the diff.
+*
+* @example
+* ```ts
+* const diff = { building: { floors: 5, height: 100 }, name: 'Test' }
+*
+* extractDiffValue(diff, 'name') // 'Test'
+* extractDiffValue(diff, 'building') // { floors: 5, height: 100 }
+* extractDiffValue(diff, 'building.floors') // 5
+* extractDiffValue(diff, 'building.missing') // undefined
+* ```
+*/
+const extractDiffValue = (diff, path) => {
+	const parts = path.split(".");
+	let current = diff;
+	for (const part of parts) {
+		if (current === null || typeof current !== "object") return;
+		if (!(part in current)) return;
+		current = current[part];
+	}
+	return current;
+};
+/**
+* Create a diff that sets a value at a specific path (supports dot notation).
+*
+* @example
+* ```ts
+* createDiffAtPath('name', 'New Name')
+* // { name: 'New Name' }
+*
+* createDiffAtPath('building.floors', 5)
+* // { building: { floors: 5 } }
+*
+* createDiffAtPath('building.config.enabled', true)
+* // { building: { config: { enabled: true } } }
+* ```
+*/
+const createDiffAtPath = (path, value) => {
+	const parts = path.split(".");
+	const result = {};
+	let current = result;
+	for (let i = 0; i < parts.length - 1; i++) {
+		const part = parts[i];
+		if (part === void 0) continue;
+		current[part] = {};
+		current = current[part];
+	}
+	const lastPart = parts[parts.length - 1];
+	if (lastPart !== void 0) current[lastPart] = value;
+	return result;
+};
+/**
+* Invert a flattened diff back to nested object structure.
+* Opposite of flattenDiff.
+*
+* @example
+* ```ts
+* const flat = { 'building.floors': 5, 'building.height': 100, 'name': 'Test' }
+* const nested = unflattenDiff(flat)
+* // { building: { floors: 5, height: 100 }, name: 'Test' }
+* ```
+*/
+const unflattenDiff = (flatDiff) => {
+	const result = {};
+	for (const [path, value] of Object.entries(flatDiff)) {
+		const parts = path.split(".");
+		let current = result;
+		for (let i = 0; i < parts.length - 1; i++) {
+			const part = parts[i];
+			if (part === void 0) continue;
+			if (!(part in current) || typeof current[part] !== "object") current[part] = {};
+			current = current[part];
+		}
+		const lastPart = parts[parts.length - 1];
+		if (lastPart !== void 0) current[lastPart] = value;
+	}
+	return result;
+};
+/**
+* Walk a state object collecting every dotted path that currently holds
+* a `serverTimestamp()` sentinel. Arrays are not traversed — Firestore
+* doesn't allow sentinels inside arrays. Non-plain objects (Timestamps,
+* DocumentReferences, …) are leaves.
+*
+* @internal
+*/
+const collectServerTimestampPaths = (state, prefix = "", out = /* @__PURE__ */ new Set()) => {
+	if (!state) return out;
+	for (const key of Object.keys(state)) {
+		const value = state[key];
+		const path = prefix ? `${prefix}.${key}` : key;
+		if (isServerTimestamp(value)) {
+			out.add(path);
+			continue;
+		}
+		if (isPlainObject(value)) collectServerTimestampPaths(value, path, out);
+	}
+	return out;
+};
+/**
+* Reconcile a `displayOverrides` map against the current `localState`:
+*
+* - For each path that holds a `serverTimestamp()` sentinel but has no
+*   override yet, capture `Timestamp.now()` and store it (frozen-at-
+*   first-sighting).
+* - For each existing override whose path no longer holds a sentinel
+*   (sentinel was overwritten, or `localState` cleared on snapshot ack),
+*   drop it.
+*
+* The map is mutated in place. Pass a custom `now` for deterministic
+* tests; defaults to `Timestamp.now()`.
+*
+* @internal
+*/
+const reconcileDisplayOverrides = (localState, overrides, now = () => Timestamp.now()) => {
+	const currentPaths = collectServerTimestampPaths(localState);
+	for (const path of currentPaths) if (!overrides.has(path)) overrides.set(path, now());
+	for (const path of [...overrides.keys()]) if (!currentPaths.has(path)) overrides.delete(path);
+};
+const setAtPath = (obj, path, value) => {
+	const parts = path.split(".");
+	let cur = obj;
+	for (let i = 0; i < parts.length - 1; i++) {
+		const part = parts[i];
+		if (!isPlainObject(cur[part])) cur[part] = {};
+		cur = cur[part];
+	}
+	cur[parts[parts.length - 1]] = value;
+};
+/**
+* Apply a path → value override map to a merged view, returning a new
+* object. Used by document.ts / collection.ts to substitute display
+* values for sentinels still present in `localState`.
+*
+* @internal
+*/
+const applyOverridesAtPaths = (merged, overrides) => {
+	if (overrides.size === 0) return merged;
+	const result = deepClone(merged);
+	for (const [path, value] of overrides) setAtPath(result, path, value);
+	return result;
+};
+
+//#endregion
+//#region src/document.ts
+let syncKeyCounter$1 = 0;
+/**
+* Create a document subscription.
+* This is a low-level API - prefer using useDocument hook in React.
+*
+* @example
+* ```ts
+* const subscription = createDocumentSubscription({
+*   store,
+*   definition: projectDoc,
+*   docId: '123',
+* })
+*
+* const unsubscribe = subscription.subscribe((state) => {
+*   console.log('Document state:', state)
+* })
+*
+* subscription.load()
+* ```
+*/
+const createDocumentSubscription = (options) => {
+	const { store, definition, docId, collectionPath: resolvedCollectionPath, readOnly, 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 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 state = {
+		syncState: void 0,
+		localState: void 0,
+		isLoading: true,
+		error: void 0,
+		waitingForUpdate: false,
+		inflightLocalState: void 0,
+		isSetOperation: false,
+		displayOverrides: /* @__PURE__ */ new Map()
+	};
+	const subscribers = /* @__PURE__ */ new Set();
+	let unsubscribeListener = null;
+	let autosaveTimeout = null;
+	let retryTimeout = null;
+	let minLoadTimeout = null;
+	let minLoadTimeElapsed = false;
+	let loaded = false;
+	let cachedHandle = null;
+	const syncKey = `doc:${collectionPath}/${documentId}#${++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);
+	};
+	const getPublicState = () => ({
+		data: getMergedData(),
+		isLoading: state.isLoading,
+		isSynced: state.localState === void 0,
+		error: state.error
+	});
+	const notify = () => {
+		reconcileDisplayOverrides(state.localState && typeof state.localState === "object" ? state.localState : void 0, state.displayOverrides);
+		cachedHandle = null;
+		const publicState = getPublicState();
+		subscribers.forEach((fn) => fn(publicState));
+		store.reportSyncState(syncKey, publicState.isSynced);
+	};
+	const updateState = (diff, undoOptions = {}) => {
+		if (isReadOnly) return;
+		const currentData = getMergedData();
+		if (!currentData) {
+			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 newLocalState = deepClone(currentData);
+		applyDiffMutable(newLocalState, diff);
+		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);
+		}
+		state.localState = newLocalState;
+		state.isSetOperation = false;
+		notify();
+		scheduleAutosave();
+	};
+	const setData = (data, undoOptions = {}) => {
+		if (isReadOnly) return;
+		if (schema) schema.parse(data);
+		const currentData = getMergedData();
+		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(currentData);
+				onPushUndo(() => setData(dataToRestore, { undoable: false }), () => setData(dataForRedo, { undoable: false }), undoOptions);
+			}
+		}
+		state.localState = deepClone(data);
+		state.isSetOperation = true;
+		notify();
+		scheduleAutosave();
+	};
+	const deleteDocument = (undoOptions = {}) => {
+		if (isReadOnly) return;
+		const currentData = getMergedData();
+		if (currentData === void 0) return;
+		if (undoOptions?.undoable !== false && onPushUndo) {
+			const dataToRestore = deepClone(currentData);
+			onPushUndo(() => setData(dataToRestore, { undoable: false }), () => deleteDocument({ undoable: false }), undoOptions);
+		}
+		state.localState = null;
+		state.isSetOperation = false;
+		notify();
+		scheduleAutosave();
+	};
+	const scheduleAutosave = () => {
+		if (autosaveTimeout) clearTimeout(autosaveTimeout);
+		if (autosave > 0) autosaveTimeout = setTimeout(() => {
+			sync();
+		}, 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)) {
+			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;
+		try {
+			if (useSetDoc) await setDoc(docRef, state.localState);
+			else await updateDoc(docRef, flattenDiff(diff));
+		} 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();
+		}
+	};
+	const handleSnapshot = (newSyncData) => {
+		state.syncState = newSyncData;
+		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;
+		}
+		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);
+			retryTimeout = setTimeout(() => {
+				stop();
+				load();
+			}, retryInterval);
+		} else {
+			state.error = error;
+			state.isLoading = false;
+			loaded = true;
+			store.reportError(error, {
+				type: "document",
+				path: `${collectionPath}/${documentId}`,
+				operation: "read"
+			});
+			notify();
+		}
+	};
+	const load = () => {
+		if (unsubscribeListener) return;
+		loaded = false;
+		minLoadTimeElapsed = false;
+		unsubscribeListener = onSnapshot(docRef, (snapshot) => {
+			if (snapshot.exists()) handleSnapshot(snapshot.data());
+			else if (!snapshot.metadata.fromCache) handleMissingDocument();
+		}, handleError);
+		minLoadTimeout = setTimeout(() => {
+			minLoadTimeout = null;
+			if (loaded) {
+				state.isLoading = false;
+				notify();
+			}
+			minLoadTimeElapsed = true;
+		}, minLoadTime);
+	};
+	const stop = () => {
+		if (unsubscribeListener) {
+			unsubscribeListener();
+			unsubscribeListener = null;
+		}
+		if (autosaveTimeout) {
+			clearTimeout(autosaveTimeout);
+			autosaveTimeout = null;
+		}
+		if (retryTimeout) {
+			clearTimeout(retryTimeout);
+			retryTimeout = null;
+		}
+		if (minLoadTimeout) {
+			clearTimeout(minLoadTimeout);
+			minLoadTimeout = null;
+		}
+		store.unregisterSyncState(syncKey);
+	};
+	const subscribe = (fn) => {
+		subscribers.add(fn);
+		return () => subscribers.delete(fn);
+	};
+	const buildHandle = () => ({
+		data: getMergedData(),
+		update: updateState,
+		set: setData,
+		delete: deleteDocument,
+		isLoading: state.isLoading,
+		isSynced: state.localState === void 0,
+		sync,
+		error: state.error,
+		ref: docRef
+	});
+	const getHandle = () => {
+		if (cachedHandle === null) cachedHandle = buildHandle();
+		return cachedHandle;
+	};
+	return {
+		load,
+		stop,
+		subscribe,
+		getState: getPublicState,
+		getHandle,
+		sync
+	};
+};
+
+//#endregion
+//#region src/collection.ts
+let syncKeyCounter = 0;
+/**
+* Create a collection subscription.
+* This is a low-level API - prefer using useCollection hook in React.
+*
+* @example
+* ```ts
+* const subscription = createCollectionSubscription({
+*   store,
+*   definition: spacesCollection,
+*   collectionPath: 'projects/123/spaces',
+* })
+*
+* const unsubscribe = subscription.subscribe((state) => {
+*   console.log('Collection state:', state)
+* })
+*
+* subscription.load() // For lazy collections
+* ```
+*/
+const createCollectionSubscription = (options) => {
+	const { store, definition, collectionPath: resolvedPath, readOnly, queryConstraints: extraConstraints, 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 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 allConstraints = [...definitionConstraints ?? [], ...extraConstraints ?? []];
+	const collectionRef = collection(firestore, collectionPath);
+	const state = {
+		syncState: void 0,
+		localState: void 0,
+		isLoading: !lazy,
+		isActive: !lazy,
+		error: void 0,
+		waitingForUpdate: false,
+		inflightLocalState: void 0,
+		displayOverrides: /* @__PURE__ */ new Map()
+	};
+	const subscribers = /* @__PURE__ */ new Set();
+	let unsubscribeListener = null;
+	let autosaveTimeout = null;
+	let minLoadTimeout = null;
+	let retryTimeout = null;
+	let minLoadTimeElapsed = false;
+	let loaded = false;
+	let cachedHandle = null;
+	const syncKey = `col:${collectionPath}#${++syncKeyCounter}`;
+	const getMergedData = () => {
+		return applyOverridesAtPaths(state.localState ?? state.syncState ?? {}, state.displayOverrides);
+	};
+	const getPublicState = () => ({
+		data: getMergedData(),
+		isLoading: state.isLoading,
+		isSynced: state.localState === void 0,
+		isActive: state.isActive,
+		error: state.error
+	});
+	const notify = () => {
+		reconcileDisplayOverrides(state.localState, state.displayOverrides);
+		cachedHandle = null;
+		const publicState = getPublicState();
+		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");
+			return;
+		}
+		const currentData = getMergedData();
+		const newLocalState = deepClone(currentData);
+		applyDiffMutable(newLocalState, diff);
+		for (const [docId, docData] of Object.entries(newLocalState)) if (docData && typeof docData === "object") docData.id = docId;
+		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);
+		}
+		state.localState = newLocalState;
+		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 currentData = getMergedData();
+		const newLocalState = deepClone(currentData);
+		newLocalState[id] = newDoc;
+		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);
+		}
+		state.localState = newLocalState;
+		notify();
+		scheduleAutosave();
+		return id;
+	}
+	const removeDocument = (id, 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 (undoOptions?.undoable !== false && onPushUndo) {
+			const undoDiff = computeDiff(newLocalState, currentData);
+			const redoDiff = computeDiff(currentData, newLocalState);
+			onPushUndo(() => updateState(undoDiff, { undoable: false }), () => updateState(redoDiff, { undoable: false }), undoOptions);
+		}
+		state.localState = newLocalState;
+		notify();
+		scheduleAutosave();
+	};
+	const scheduleAutosave = () => {
+		if (autosaveTimeout) clearTimeout(autosaveTimeout);
+		if (autosave > 0) autosaveTimeout = setTimeout(() => {
+			sync();
+		}, autosave);
+	};
+	const sync = async () => {
+		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 diff = computeDiff(syncState, state.localState);
+		state.inflightLocalState = deepClone(state.localState);
+		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);
+				}
+			}
+			await batch.commit();
+		} catch (error) {
+			console.error("Collection sync failed:", error);
+			state.waitingForUpdate = false;
+			state.inflightLocalState = void 0;
+			state.error = error;
+			store.reportError(error, {
+				type: "collection",
+				path: collectionPath,
+				operation: "write"
+			});
+			notify();
+		}
+	};
+	const handleSnapshot = (docs) => {
+		const newSyncState = {};
+		for (const { id, data } of docs) newSyncState[id] = {
+			...data,
+			id
+		};
+		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 && 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);
+			retryTimeout = setTimeout(() => {
+				stop();
+				startListener();
+			}, retryInterval);
+		} else {
+			state.error = error;
+			state.isLoading = false;
+			loaded = true;
+			store.reportError(error, {
+				type: "collection",
+				path: collectionPath,
+				operation: "read"
+			});
+			notify();
+		}
+	};
+	const startListener = () => {
+		if (unsubscribeListener) return;
+		loaded = false;
+		minLoadTimeElapsed = false;
+		unsubscribeListener = onSnapshot(allConstraints.length > 0 ? query(collectionRef, ...allConstraints) : collectionRef, (snapshot) => {
+			handleSnapshot(snapshot.docs.map((docSnap) => ({
+				id: docSnap.id,
+				data: docSnap.data()
+			})));
+		}, handleError);
+		minLoadTimeout = setTimeout(() => {
+			minLoadTimeout = null;
+			if (loaded) {
+				state.isLoading = false;
+				notify();
+			}
+			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;
+		}
+		if (autosaveTimeout) {
+			clearTimeout(autosaveTimeout);
+			autosaveTimeout = null;
+		}
+		if (minLoadTimeout) {
+			clearTimeout(minLoadTimeout);
+			minLoadTimeout = null;
+		}
+		store.unregisterSyncState(syncKey);
+	};
+	const subscribe = (fn) => {
+		subscribers.add(fn);
+		return () => subscribers.delete(fn);
+	};
+	const buildHandle = () => ({
+		data: getMergedData(),
+		update: updateState,
+		add: addDocument,
+		remove: removeDocument,
+		isLoading: state.isLoading,
+		isSynced: state.localState === void 0,
+		isActive: state.isActive,
+		load,
+		sync,
+		error: state.error,
+		ref: collectionRef
+	});
+	const getHandle = () => {
+		if (cachedHandle === null) cachedHandle = buildHandle();
+		return cachedHandle;
+	};
+	return {
+		load,
+		stop,
+		subscribe,
+		getState: getPublicState,
+		getHandle,
+		sync
+	};
+};
+
+//#endregion
+//#region src/hooks.ts
+/**
+* Returned when a hook is called with `enabled: false`. Module-level constants
+* so getSnapshot returns a stable reference and useSyncExternalStore doesn't
+* re-render. Cast at the call site to the generic handle type — every method
+* is a no-op so the cast is sound.
+*/
+const NOOP = () => {};
+const ASYNC_NOOP = async () => {};
+const EMPTY_RECORD = {};
+const DISABLED_DOCUMENT_HANDLE = {
+	data: void 0,
+	update: NOOP,
+	set: NOOP,
+	delete: NOOP,
+	isLoading: false,
+	isSynced: true,
+	sync: ASYNC_NOOP,
+	error: void 0,
+	ref: void 0
+};
+const DISABLED_ADD = () => void 0;
+const DISABLED_COLLECTION_HANDLE = {
+	data: EMPTY_RECORD,
+	update: NOOP,
+	add: DISABLED_ADD,
+	remove: NOOP,
+	isLoading: false,
+	isSynced: true,
+	isActive: false,
+	load: NOOP,
+	sync: ASYNC_NOOP,
+	error: void 0,
+	ref: void 0
+};
+/**
+* Context for providing the Firestate store
+*/
+const FirestateContext = createContext(null);
+/**
+* Hook to access the Firestate store
+*/
+const useStore = () => {
+	const store = useContext(FirestateContext);
+	if (!store) throw new Error("useStore must be used within a FirestateProvider");
+	return store;
+};
+/**
+* Hook to access the undo manager
+*/
+const useUndoManager = () => {
+	const { undoManager } = useStore();
+	const subscribe = useCallback((onStoreChange) => undoManager.subscribe(onStoreChange), [undoManager]);
+	const getSnapshot = useCallback(() => undoManager.getState(), [undoManager]);
+	const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+	return useMemo(() => ({
+		...state,
+		push: undoManager.push,
+		undo: undoManager.undo,
+		redo: undoManager.redo,
+		clear: undoManager.clear
+	}), [state, undoManager]);
+};
+/**
+* Hook to check if all tracked resources are synced
+*/
+const useIsSynced = () => {
+	const store = useStore();
+	const subscribe = useCallback((onChange) => store.subscribeToSyncState(() => onChange()), [store]);
+	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;
+	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({
+		store,
+		definition,
+		docId,
+		collectionPath,
+		readOnly,
+		onPushUndo
+	}) : null, [
+		enabled,
+		store,
+		definition,
+		docId,
+		collectionPath,
+		readOnly,
+		onPushUndo
+	]);
+	const subscribe = useCallback((onChange) => {
+		if (!subscription) return NOOP;
+		const unsub = subscription.subscribe(() => onChange());
+		subscription.load();
+		return () => {
+			unsub();
+			subscription.stop();
+		};
+	}, [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 `queryConstraints` reference. When any of these change, the listener
+* is torn down and re-attached with the new query. Toggling `undoable` does
+* not rebuild the subscription.
+*
+* **Memoize `queryConstraints`.** An inline array (`queryConstraints={[where(...)]}`)
+* creates a new reference every render, which will thrash the listener.
+* Wrap in `useMemo` with the underlying filter values as deps.
+*
+* 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 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 subscription = useMemo(() => enabled && collectionPath !== void 0 ? createCollectionSubscription({
+		store,
+		definition,
+		collectionPath,
+		readOnly,
+		queryConstraints,
+		onPushUndo
+	}) : null, [
+		enabled,
+		store,
+		definition,
+		collectionPath,
+		readOnly,
+		queryConstraints,
+		onPushUndo
+	]);
+	const isLazy = definition.lazy ?? false;
+	const subscribe = useCallback((onChange) => {
+		if (!subscription) return NOOP;
+		const unsub = subscription.subscribe(() => onChange());
+		if (!isLazy) subscription.load();
+		return () => {
+			unsub();
+			subscription.stop();
+		};
+	}, [subscription, isLazy]);
+	const getSnapshot = useCallback(() => subscription ? subscription.getHandle() : DISABLED_COLLECTION_HANDLE, [subscription]);
+	return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+};
+/**
+* Keyboard shortcut hook for undo/redo
+*
+* @example
+* ```tsx
+* function App() {
+*   useUndoKeyboardShortcuts()
+*   return <YourApp />
+* }
+* ```
+*/
+const useUndoKeyboardShortcuts = () => {
+	const undoManager = useStore().undoManager;
+	useEffect(() => {
+		const handleKeyDown = (e) => {
+			if (!((navigator.userAgentData?.platform ?? navigator.platform).toUpperCase().includes("MAC") ? e.metaKey : e.ctrlKey)) return;
+			if (e.key === "z" && !e.shiftKey) {
+				e.preventDefault();
+				undoManager.undo();
+			} else if (e.key === "z" && e.shiftKey || e.key === "y") {
+				e.preventDefault();
+				undoManager.redo();
+			}
+		};
+		window.addEventListener("keydown", handleKeyDown);
+		return () => window.removeEventListener("keydown", handleKeyDown);
+	}, [undoManager]);
+};
+
+//#endregion
+//#region src/firestate.ts
+/**
+* Registry-driven Firestate API.
+*
+* Declare every document and collection in a single object and let the
+* library generate the typed read/write hooks. Replaces hand-writing a
+* `useSpaces`, `useWallTypes`, ... hook per Firestore collection.
+*
+* ```ts
+* interface TaskList { name: string; createdAt: number }
+* interface Task { title: string; completed: boolean }
+*
+* export const { useTaskList, useTasks } = createFirestate({
+*   taskList: doc<TaskList>('taskLists/{listId}'),
+*   tasks:    col<Task>('taskLists/{listId}/tasks'),
+* })
+*
+* // At the call site:
+* const taskList = useTaskList({ listId })
+* const tasks    = useTasks({ listId })
+* ```
+*/
+/**
+* Declare a single-document entry for a Firestate registry.
+*
+* **A Zod `schema` field is required.** Both the data type (`T`) and the
+* path's literal type (`P`) are inferred from the call — `T` via
+* `z.infer<S>`, `P` from `path` — so the generated hook can statically
+* type-check the params object the caller passes. The schema also runs
+* at runtime on full-payload writes (`set`/`add`).
+*
+* If you'd rather not provide a schema at all, use {@link defineDocument}
+* directly — that escape hatch keeps the plain-TypeScript form, at the
+* cost of looser param typing on the hook and no runtime validation.
+*
+* ```ts
+* import { z } from 'zod'
+*
+* const TaskListSchema = z.object({ name: z.string(), createdAt: z.number() })
+* doc({ path: 'taskLists/{listId}', schema: TaskListSchema })
+* // → DocEntry<{ name: string; createdAt: number }, 'taskLists/{listId}'>
+* ```
+*/
+function doc(opts) {
+	const { path, ...rest } = opts;
+	validateTemplate(path);
+	splitDocPath(path);
+	return {
+		__kind: "document",
+		path,
+		...rest
+	};
+}
+/**
+* Declare a collection entry for a Firestate registry. See {@link doc}
+* for the schema/typing contract.
+*/
+function col(opts) {
+	const { path, ...rest } = opts;
+	validateTemplate(path);
+	return {
+		__kind: "collection",
+		path,
+		...rest
+	};
+}
+/**
+* Turn a Firestate registry into a map of typed React hooks. Each entry
+* `K` produces a hook named `use{Capitalize<K>}`.
+*
+* ```ts
+* export const { useTaskList, useTasks } = createFirestate({
+*   taskList: doc<TaskList>('taskLists/{listId}'),
+*   tasks:    col<Task>('taskLists/{listId}/tasks'),
+* })
+* ```
+*/
+function createFirestate(registry) {
+	const api = {};
+	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);
+			api[hookName] = (params = {}, options = {}) => useDocument({
+				...options,
+				definition,
+				params
+			});
+		} else {
+			const definition = buildCollectionDefinition(entry);
+			api[hookName] = (params = {}, options = {}) => useCollection({
+				...options,
+				definition,
+				params
+			});
+		}
+	}
+	return api;
+}
+/**
+* Build the underlying {@link DocumentDefinition} for a registry doc entry.
+* Exported for unit testing — registry consumers should call
+* {@link createFirestate} instead.
+*
+* @internal
+*/
+function buildDocumentDefinition(entry) {
+	const { collectionPath, idTemplate } = splitDocPath(entry.path);
+	return defineDocument({
+		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
+	});
+}
+/**
+* Build the underlying {@link CollectionDefinition} for a registry col entry.
+*
+* @internal
+*/
+function buildCollectionDefinition(entry) {
+	return defineCollection({
+		schema: entry.schema,
+		path: (params) => interpolate(entry.path, params),
+		autosave: entry.autosave,
+		minLoadTime: entry.minLoadTime,
+		readOnly: entry.readOnly,
+		lazy: entry.lazy,
+		queryConstraints: entry.queryConstraints,
+		retryOnError: entry.retryOnError,
+		retryInterval: entry.retryInterval
+	});
+}
+const VALID_KEY = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function isValidKey(key) {
+	return VALID_KEY.test(key);
+}
+function toHookName(key) {
+	return `use${key[0].toUpperCase()}${key.slice(1)}`;
+}
+const PLACEHOLDER = /\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+/**
+* Validate that a path template uses only well-formed `{name}` placeholders
+* — no unclosed braces, no hyphens/dots inside placeholders, no `{1}` style
+* digit-leading names. Throws at definition time so a typo in the template
+* fails loud at `doc()` / `col()`, not three layers deep when a component
+* mounts.
+*/
+function validateTemplate(template) {
+	const stripped = template.replace(PLACEHOLDER, "");
+	if (stripped.includes("{") || stripped.includes("}")) throw new Error(`[firestate] path "${template}" contains a malformed placeholder. Placeholders must look like "{name}" where name starts with a letter or underscore.`);
+}
+function interpolate(template, params) {
+	return template.replace(PLACEHOLDER, (_, key) => {
+		const v = params[key];
+		if (v === void 0) throw new Error(`[firestate] missing param "${key}" for path "${template}"`);
+		if (v === "") throw new Error(`[firestate] param "${key}" for path "${template}" must not be an empty string`);
+		return v;
+	});
+}
+/**
+* Split a document path template into a collection path and an id template.
+* `'taskLists/{listId}'` → `{ collectionPath: 'taskLists', idTemplate: '{listId}' }`.
+*
+* @internal
+*/
+function splitDocPath(path) {
+	const lastSlash = path.lastIndexOf("/");
+	if (lastSlash === -1) throw new Error(`[firestate] document path "${path}" must contain at least one '/' separating the collection from the document id`);
+	const collectionPath = path.slice(0, lastSlash);
+	const idTemplate = path.slice(lastSlash + 1);
+	if (collectionPath === "" || idTemplate === "") throw new Error(`[firestate] document path "${path}" must have non-empty collection and id segments`);
+	return {
+		collectionPath,
+		idTemplate
+	};
+}
+
+//#endregion
+//#region src/undo.ts
+/**
+* Create an undo manager instance.
+* This is a standalone, framework-agnostic implementation.
+*
+* @example
+* ```ts
+* const undoManager = createUndoManager({ maxLength: 10 })
+*
+* undoManager.push({
+*   undo: () => restoreOldValue(),
+*   redo: () => applyNewValue(),
+*   description: 'Update project name',
+* })
+*
+* await undoManager.undo() // Calls restoreOldValue()
+* await undoManager.redo() // Calls applyNewValue()
+* ```
+*/
+const createUndoManager = (config = {}) => {
+	const { maxLength = 20, onNavigate } = config;
+	let undoStack = [];
+	let redoStack = [];
+	const subscribers = /* @__PURE__ */ new Set();
+	let cachedState = null;
+	const getState = () => {
+		if (cachedState === null) cachedState = {
+			undoStack,
+			redoStack,
+			canUndo: undoStack.length > 0,
+			canRedo: redoStack.length > 0
+		};
+		return cachedState;
+	};
+	const notify = () => {
+		cachedState = null;
+		const state = getState();
+		subscribers.forEach((fn) => fn(state));
+	};
+	const push = (action) => {
+		if (action.groupId && undoStack.length > 0) {
+			const last = undoStack[undoStack.length - 1];
+			if (last?.groupId === action.groupId) {
+				undoStack.pop();
+				undoStack.push({
+					undo: async () => {
+						await action.undo();
+						await last.undo();
+					},
+					redo: async () => {
+						await last.redo();
+						await action.redo();
+					},
+					groupId: action.groupId,
+					path: action.path ?? last.path,
+					description: action.description ?? last.description
+				});
+				redoStack = [];
+				notify();
+				return;
+			}
+		}
+		undoStack.push(action);
+		if (undoStack.length > maxLength) undoStack.shift();
+		redoStack = [];
+		notify();
+	};
+	const undo = async () => {
+		const action = undoStack.pop();
+		if (!action) return;
+		if (action.path && onNavigate) onNavigate(action.path);
+		try {
+			await action.undo();
+			redoStack.push(action);
+		} catch (error) {
+			undoStack.push(action);
+			console.error("Undo failed:", error);
+			throw error;
+		}
+		notify();
+	};
+	const redo = async () => {
+		const action = redoStack.pop();
+		if (!action) return;
+		if (action.path && onNavigate) onNavigate(action.path);
+		try {
+			await action.redo();
+			undoStack.push(action);
+			if (undoStack.length > maxLength) undoStack.shift();
+		} catch (error) {
+			redoStack.push(action);
+			console.error("Redo failed:", error);
+			throw error;
+		}
+		notify();
+	};
+	const clear = () => {
+		undoStack = [];
+		redoStack = [];
+		notify();
+	};
+	const subscribe = (fn) => {
+		subscribers.add(fn);
+		return () => subscribers.delete(fn);
+	};
+	return {
+		get undoStack() {
+			return undoStack;
+		},
+		get redoStack() {
+			return redoStack;
+		},
+		get canUndo() {
+			return undoStack.length > 0;
+		},
+		get canRedo() {
+			return redoStack.length > 0;
+		},
+		push,
+		undo,
+		redo,
+		clear,
+		subscribe,
+		getState
+	};
+};
+
+//#endregion
+//#region src/store.ts
+/**
+* Create a Firestate store.
+* This is the central configuration point for your Firestore state management.
+*
+* @example
+* ```ts
+* import { createStore } from 'firestate'
+* import { db } from './firebase'
+*
+* export const store = createStore({
+*   firestore: db,
+*   autosave: 1000,
+*   maxUndoLength: 20,
+*   onError: (error, context) => {
+*     console.error(`Error in ${context.type} ${context.path}:`, error)
+*   },
+* })
+* ```
+*/
+const createStore = (config) => {
+	const { firestore, autosave = 1e3, minLoadTime = 0, maxUndoLength = 20 } = config;
+	let onError = config.onError;
+	const undoManager = createUndoManager({ maxLength: maxUndoLength });
+	const syncStates = /* @__PURE__ */ new Map();
+	const syncSubscribers = /* @__PURE__ */ new Set();
+	const computeIsSynced = () => {
+		for (const synced of syncStates.values()) if (!synced) return false;
+		return true;
+	};
+	const notifySyncSubscribers = () => {
+		const isSynced = computeIsSynced();
+		syncSubscribers.forEach((fn) => fn(isSynced));
+	};
+	return {
+		firestore,
+		undoManager,
+		autosave,
+		minLoadTime,
+		reportError: (error, context) => {
+			if (onError) onError(error, context);
+			else console.error(`Firestate error in ${context.type} ${context.path} during ${context.operation}:`, error);
+		},
+		setOnError: (handler) => {
+			onError = handler;
+		},
+		subscribeToSyncState: (fn) => {
+			syncSubscribers.add(fn);
+			return () => syncSubscribers.delete(fn);
+		},
+		reportSyncState: (key, isSynced) => {
+			if (syncStates.get(key) !== isSynced) {
+				syncStates.set(key, isSynced);
+				notifySyncSubscribers();
+			}
+		},
+		unregisterSyncState: (key) => {
+			const prev = syncStates.get(key);
+			if (prev === void 0) return;
+			syncStates.delete(key);
+			if (prev === false) notifySyncSubscribers();
+		},
+		get isSynced() {
+			return computeIsSynced();
+		}
+	};
+};
+
+//#endregion
+//#region src/provider.tsx
+/**
+* Provider component that sets up Firestate for your application.
+*
+* @example
+* ```tsx
+* import { FirestateProvider } from 'firestate'
+* import { db } from './firebase'
+*
+* function App() {
+*   return (
+*     <FirestateProvider
+*       firestore={db}
+*       autosave={1000}
+*       maxUndoLength={20}
+*       onError={(error, ctx) => console.error(ctx.path, error)}
+*     >
+*       <YourApp />
+*     </FirestateProvider>
+*   )
+* }
+* ```
+*/
+const FirestateProvider = ({ firestore, autosave = 1e3, minLoadTime = 0, maxUndoLength = 20, onError, children }) => {
+	const store = useMemo(() => createStore({
+		firestore,
+		autosave,
+		minLoadTime,
+		maxUndoLength,
+		onError
+	}), [
+		firestore,
+		autosave,
+		minLoadTime,
+		maxUndoLength
+	]);
+	useEffect(() => {
+		store.setOnError(onError);
+	}, [store, onError]);
+	return /* @__PURE__ */ jsx(FirestateContext.Provider, {
+		value: store,
+		children
+	});
+};
+/**
+* Provider that uses an existing store instance.
+* Useful when you need to create the store outside of React.
+*
+* @example
+* ```tsx
+* const store = createStore({ firestore: db })
+*
+* function App() {
+*   return (
+*     <FirestateStoreProvider store={store}>
+*       <YourApp />
+*     </FirestateStoreProvider>
+*   )
+* }
+* ```
+*/
+const FirestateStoreProvider = ({ store, children }) => /* @__PURE__ */ jsx(FirestateContext.Provider, {
+	value: store,
+	children
+});
+/**
+* Hook to use navigation blocker when there are unsaved changes.
+* Works with react-router or similar routers.
+*
+* @example
+* ```tsx
+* function ProjectPage() {
+*   const shouldBlock = useUnsavedChangesBlocker()
+*
+*   // Use with react-router's useBlocker
+*   const blocker = useBlocker(
+*     ({ currentLocation, nextLocation }) =>
+*       currentLocation.pathname !== nextLocation.pathname && shouldBlock
+*   )
+*
+*   return (
+*     <>
+*       <ProjectEditor />
+*       {blocker.state === 'blocked' && (
+*         <Dialog>Your changes may not be saved!</Dialog>
+*       )}
+*     </>
+*   )
+* }
+* ```
+*/
+const useUnsavedChangesBlocker = () => {
+	const store = React.useContext(FirestateContext);
+	const subscribe = useCallback((onChange) => store ? store.subscribeToSyncState(() => onChange()) : () => {}, [store]);
+	const getSnapshot = useCallback(() => store ? !store.isSynced : false, [store]);
+	return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+};
+
+//#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 };
+//# sourceMappingURL=index.mjs.map