@hvakr/firestate 0.1.3 → 0.1.5

package/README.md

@@ -33,35 +33,35 @@ Firestate provides a declarative, schema-first approach that eliminates boilerpl
 Firestate exposes two layers. Pick one based on what you're building:
 
 - **`createFirestate` + `doc` / `col`** (recommended for app code) — declare a Firestore resource (a document or collection) with a `path` template and a Zod `schema`, and the library generates one typed React hook per entry. In return you get:
-  - the data type (`TaskList`) inferred from the schema via `z.infer`
-  - the param keys (`{ listId }`) inferred from the path template and enforced at call sites
-  - runtime validation on `set` / `add` writes — bad data throws at the call site instead of after a Firestore round trip
+    - the data type (`TaskList`) inferred from the schema via `z.infer`
+    - the param keys (`{ listId }`) inferred from the path template and enforced at call sites
+    - runtime validation on `set` / `add` writes — bad data throws at the call site instead of after a Firestore round trip
 
-  Partial `update(diff)` calls are intentionally NOT validated: diffs commonly include Firestore sentinels like `serverTimestamp()` that a strict schema would reject.
+    Partial `update(diff)` calls are intentionally NOT validated: diffs commonly include Firestore sentinels like `serverTimestamp()` that a strict schema would reject.
 
-  Treat `createFirestate` as a **per-resource hook factory**, not an app-wide registry: give each document/collection its own module (`firestore/taskList.ts`, `firestore/tasks.ts`, …) with one `createFirestate` call, and export the hooks flat. See [Organizing by resource](#organizing-by-resource).
+    Treat `createFirestate` as a **per-resource hook factory**, not an app-wide registry: give each document/collection its own module (`firestore/taskList.ts`, `firestore/tasks.ts`, …) with one `createFirestate` call, and export the hooks flat. See [Organizing by resource](#organizing-by-resource).
 
-  ```ts
-  // firestore/taskList.ts
-  import { z } from 'zod'
-  import { createFirestate, doc } from '@hvakr/firestate'
+    ```ts
+    // firestore/taskList.ts
+    import { z } from 'zod'
+    import { createFirestate, doc } from '@hvakr/firestate'
 
-  const TaskListSchema = z.object({ name: z.string(), createdAt: z.number() })
+    const TaskListSchema = z.object({ name: z.string(), createdAt: z.number() })
 
-  const taskList = doc({ path: 'taskLists/{listId}', schema: TaskListSchema })
+    const taskList = doc({ path: 'taskLists/{listId}', schema: TaskListSchema })
 
-  export const { useTaskList } = createFirestate({ taskList })
+    export const { useTaskList } = createFirestate({ taskList })
 
-  // useTaskList({ listId })           — { listId: string } statically required
-  // useTaskList()                     — type error: missing listId
-  // useTaskList({ wrong: 'a' })       — type error: wrong key
-  ```
+    // useTaskList({ listId })           — { listId: string } statically required
+    // useTaskList()                     — type error: missing listId
+    // useTaskList({ wrong: 'a' })       — type error: wrong key
+    ```
 
 - **`defineDocument` / `defineCollection` + `useDocument` / `useCollection`** (lower-level escape hatch) — write the path-derivation function yourself, use the standalone hooks. Reach for these when:
-  - your path doesn't fit the `{name}` template (computed from non-string state, conditional segments)
-  - you need the definition outside React (Node scripts, server-side, tests)
-  - your control flow doesn't fit a module-level registry
-  - you want plain TypeScript types without a Zod schema (the schema field is optional here)
+    - your path doesn't fit the `{name}` template (computed from non-string state, conditional segments)
+    - you need the definition outside React (Node scripts, server-side, tests)
+    - your control flow doesn't fit a module-level registry
+    - you want plain TypeScript types without a Zod schema (the schema field is optional here)
 
 Both layers share the same store, undo manager, and sync semantics — the registry is a thin layer on top of the lower-level primitives.
 
@@ -74,12 +74,16 @@ Both layers share the same store, undo manager, and sync semantics — the regis
 import { z } from 'zod'
 import { createFirestate, col } from '@hvakr/firestate'
 
-const TaskSchema = z.object({ title: z.string(), completed: z.boolean(), createdAt: z.number() })
+const TaskSchema = z.object({
+    title: z.string(),
+    completed: z.boolean(),
+    createdAt: z.number(),
+})
 const tasks = col({ path: 'taskLists/{listId}/tasks', schema: TaskSchema })
 
 export const { useTasks, useTaskById } = createFirestate({
-  tasks,                                                  // → useTasks (full handle)
-  taskById: tasks.select((s, p: { id: string }) => s.data[p.id]),
+    tasks, // → useTasks (full handle)
+    taskById: tasks.select((s, p: { id: string }) => s.data[p.id]),
 })
 
 // firestore/taskList.ts is a sibling module with its own createFirestate call.
@@ -89,10 +93,10 @@ export const { useTasks, useTaskById } = createFirestate({
 Why per-resource rather than one central call:
 
 - **It scales.** A central registry becomes a chokepoint every feature edits; resource modules keep a resource's schema, hooks, and slices colocated and let you code-split.
-- **Sharing still works app-wide.** Subscriptions are keyed by *definition identity*, and a resource module's definition lives at module scope (one stable object), so every component using `useTasks`/`useTaskById` shares one `onSnapshot` listener and one optimistic state — no matter how many modules.
+- **Sharing still works app-wide.** Subscriptions are keyed by _definition identity_, and a resource module's definition lives at module scope (one stable object), so every component using `useTasks`/`useTaskById` shares one `onSnapshot` listener and one optimistic state — no matter how many modules.
 - **The store stays global.** All resource modules mount under one `FirestateProvider`, so undo/redo and sync tracking span every resource regardless of how you split the files.
 
-**The one rule:** keep a resource's base hook *and* all its `.select` slices in the **same** `createFirestate` call. Each call builds its own definitions, so splitting one resource across two calls would fork it into two listeners. Separate *resources* in separate calls is exactly what you want; separating *one* resource is the mistake.
+**The one rule:** keep a resource's base hook _and_ all its `.select` slices in the **same** `createFirestate` call. Each call builds its own definitions, so splitting one resource across two calls would fork it into two listeners. Separate _resources_ in separate calls is exactly what you want; separating _one_ resource is the mistake.
 
 ## Table of Contents
 
@@ -125,9 +129,9 @@ Firestate requires the following peer dependencies:
 
 ```json
 {
-  "firebase": "^10.0.0 || ^11.0.0",
-  "react": "^18.0.0 || ^19.0.0",
-  "zod": "^4.0.0"
+    "firebase": "^10.0.0 || ^11.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "zod": "^4.0.0"
 }
 ```
 
@@ -205,11 +209,7 @@ import { db } from './firebase'
 
 function App() {
     return (
-        <FirestateProvider
-            firestore={db}
-            autosave={1000}
-            maxUndoLength={20}
-        >
+        <FirestateProvider firestore={db} autosave={1000} maxUndoLength={20}>
             <YourApp />
         </FirestateProvider>
     )
@@ -220,29 +220,47 @@ function App() {
 
 ```tsx
 // ProjectEditor.tsx
-import { useDocument, useCollection, useUndoManager } from '@hvakr/firestate'
+import {
+    useDocument,
+    useCollection,
+    useDocumentSyncStatus,
+    useUndoManager,
+} from '@hvakr/firestate'
 import { projectDoc, spacesCollection } from './schemas'
 
 function ProjectEditor({ projectId }: { projectId: string }) {
     const params = { projectId }
 
-    // Subscribe to project document
+    // Subscribe to project document. The default handle is sync-agnostic — it
+    // carries `data`/`isLoaded`/`error`, not `isSynced`, so it does NOT
+    // re-render when a save settles.
     const project = useDocument({ definition: projectDoc, params })
 
     // Subscribe to spaces collection (lazy)
     const spaces = useCollection({ definition: spacesCollection, params })
 
+    // Opt into save state only where you render it — shares the project's one
+    // listener, so it doesn't add a subscription.
+    const { isSaving } = useDocumentSyncStatus({
+        definition: projectDoc,
+        params,
+    })
+
     // Access undo/redo
     const { undo, redo, canUndo, canRedo } = useUndoManager()
 
-    if (project.isLoading) return <Spinner />
+    if (!project.isLoaded) return <Spinner />
     if (!project.data) return <NotFound />
 
     return (
         <div>
             {/* Undo/Redo buttons */}
-            <button onClick={undo} disabled={!canUndo}>Undo</button>
-            <button onClick={redo} disabled={!canRedo}>Redo</button>
+            <button onClick={undo} disabled={!canUndo}>
+                Undo
+            </button>
+            <button onClick={redo} disabled={!canRedo}>
+                Redo
+            </button>
 
             {/* Edit project name - changes auto-save */}
             <input
@@ -253,7 +271,7 @@ function ProjectEditor({ projectId }: { projectId: string }) {
             {/* Lazy-load spaces */}
             {!spaces.isActive ? (
                 <button onClick={spaces.load}>Load Spaces</button>
-            ) : spaces.isLoading ? (
+            ) : !spaces.isLoaded ? (
                 <Spinner />
             ) : (
                 <ul>
@@ -266,7 +284,7 @@ function ProjectEditor({ projectId }: { projectId: string }) {
             )}
 
             {/* Sync indicator */}
-            {!project.isSynced && <span>Saving...</span>}
+            {isSaving && <span>Saving...</span>}
         </div>
     )
 }
@@ -332,6 +350,9 @@ project.update({ name: 'New Name' }, { undoGroupId: groupId })
 spaces.update({ space1: { name: 'Updated' } }, { undoGroupId: groupId })
 ```
 
+Grouped actions undo newest-first and redo oldest-first, so one undo/redo
+always applies the complete group in write order.
+
 To skip undo tracking:
 
 ```tsx
@@ -354,6 +375,12 @@ function App() {
         <FirestateProvider
             firestore={db}
             onNavigate={(path) => navigate(path)}
+            onUndo={(action) =>
+                analytics.track('undo', { description: action.description })
+            }
+            onRedo={(action) =>
+                analytics.track('redo', { description: action.description })
+            }
         >
             {children}
         </FirestateProvider>
@@ -376,7 +403,7 @@ Actions record a path via the `path` field on `UndoAction`:
 undoManager.push({
     undo: () => restoreValue(),
     redo: () => applyValue(),
-    path: '/projects/123',  // navigate here on undo/redo
+    path: '/projects/123', // navigate here on undo/redo
 })
 ```
 
@@ -488,10 +515,7 @@ Use the second argument for hook options such as `enabled`, `readOnly`,
 ```tsx
 const spaces = useSpaces(
     { projectId },
-    {
-        enabled: Boolean(projectId),
-        queryConstraints,
-    }
+    { enabled: Boolean(projectId), queryConstraints }
 )
 ```
 
@@ -583,14 +607,14 @@ type parameter, or let it be inferred from a Zod schema.
 
 ```typescript
 const projectDoc = defineDocument<Project>({
-    collection: 'projects',     // Collection path
-    id: (params) => params.id,  // Document ID (string or function)
-    autosave: 1000,             // Optional: debounce interval (ms)
-    minLoadTime: 0,             // Optional: minimum loading time (ms)
-    readOnly: false,            // Optional: prevent updates
-    retryOnError: false,        // Optional: retry on listener errors
-    retryInterval: 5000,        // Optional: retry interval (ms)
-    schema: ProjectSchema,      // Optional: Zod schema (validates set/add)
+    collection: 'projects', // Collection path
+    id: (params) => params.id, // Document ID (string or function)
+    autosave: 1000, // Optional: debounce interval (ms)
+    minLoadTime: 0, // Optional: minimum loading time (ms)
+    readOnly: false, // Optional: prevent updates
+    retryOnError: false, // Optional: retry on listener errors
+    retryInterval: 5000, // Optional: retry interval (ms)
+    schema: ProjectSchema, // Optional: Zod schema (validates set/add)
 })
 ```
 
@@ -601,12 +625,12 @@ Creates a collection definition.
 ```typescript
 const spacesCollection = defineCollection<Space>({
     path: (params) => `projects/${params.id}/spaces`, // Collection path
-    autosave: 1000,                                   // Optional: debounce interval
-    minLoadTime: 0,                                   // Optional: minimum loading time
-    readOnly: false,                                  // Optional: prevent updates
-    lazy: false,                                      // Optional: defer subscription
-    queryConstraints: [],                             // Optional: Firestore constraints
-    schema: SpaceSchema,                              // Optional: Zod schema (validates add)
+    autosave: 1000, // Optional: debounce interval
+    minLoadTime: 0, // Optional: minimum loading time
+    readOnly: false, // Optional: prevent updates
+    lazy: false, // Optional: defer subscription
+    queryConstraints: [], // Optional: Firestore constraints
+    schema: SpaceSchema, // Optional: Zod schema (validates add)
 })
 ```
 
@@ -618,22 +642,27 @@ Subscribe to a document.
 
 ```typescript
 const {
-    data,           // Current document data (T | undefined)
-    update,         // Update with partial diff
-    set,            // Replace entire document
-    delete: del,    // Delete the document
-    isLoading,      // Whether initial data is loading
-    isSynced,       // Whether all changes are synced
-    sync,           // Force sync immediately
-    error,          // Error from listener, if any
-    ref,            // Firestore DocumentReference
+    data, // Current document data (T | undefined)
+    update, // Update with partial diff
+    set, // Replace entire document
+    delete: del, // Delete the document
+    isLoaded, // Whether the initial snapshot has arrived (ready to render)
+    sync, // Force sync immediately
+    error, // Error from listener, if any
+    ref, // Firestore DocumentReference
 } = useDocument({
     definition: projectDoc,
     params: { projectId: '123' },
-    readOnly: false,     // Optional: override read-only
-    undoable: true,      // Optional: enable undo (default: true)
-    enabled: true,       // Optional: set false until required params exist
+    readOnly: false, // Optional: override read-only
+    undoable: true, // Optional: enable undo (default: true)
+    enabled: true, // Optional: set false until required params exist
 })
+
+// The default handle is SYNC-AGNOSTIC: no `isSynced`, so a save settling does
+// not re-render it. For save state, use the per-entry sync-status hook (with the
+// registry API) or fold `isSynced` into a `selector`. `isLoading` likewise moved
+// to the loading-status hook; the data handle keeps `isLoaded` for the common
+// "spinner until ready" gate.
 ```
 
 #### `useCollection(options)`
@@ -642,23 +671,22 @@ Subscribe to a collection.
 
 ```typescript
 const {
-    data,           // Record<string, T> of documents
-    update,         // Update one or more documents
-    add,            // Add a new document (explicit or auto-generated id)
-    remove,         // Remove a document
-    isLoading,      // Whether initial data is loading
-    isSynced,       // Whether all changes are synced
-    isActive,       // Whether subscription is active
-    load,           // Activate a lazy subscription
-    sync,           // Force sync immediately
-    error,          // Error from listener, if any
-    ref,            // Firestore CollectionReference
+    data, // Record<string, T> of documents
+    update, // Update one or more documents
+    add, // Add a new document (explicit or auto-generated id)
+    remove, // Remove a document
+    isLoaded, // Active AND past the initial load (isActive && !isLoading)
+    isActive, // Whether subscription is active (for lazy collections)
+    load, // Activate a lazy subscription
+    sync, // Force sync immediately
+    error, // Error from listener, if any
+    ref, // Firestore CollectionReference
 } = useCollection({
     definition: spacesCollection,
     params: { projectId: '123' },
     queryConstraints: [where('floor', '==', 1)],
     undoable: true,
-    enabled: true,       // Optional: set false until required params exist
+    enabled: true, // Optional: set false until required params exist
 })
 
 // queryConstraints are keyed by query identity, not array reference: the
@@ -688,18 +716,20 @@ remove('oldSpaceId')
 
 #### Selecting a slice (`selector` + `isEqual`)
 
-By default a component re-renders whenever *any* field — or any status flag — of
-the subscribed document or collection changes, and the hook returns the **full
-handle** (`data`, `isLoading`, `isSynced`, `error`, the writers, and `ref`). Pass
-a `selector` to take control: it receives the resource's full observable state
-and returns the slice the component reacts to, so the component re-renders
-**only** when that slice changes.
+By default a component re-renders when the data, the load state (`isLoaded`), or
+`error` of the subscribed document/collection changes, and the hook returns the
+**sync-agnostic default handle** (`data`, `isLoaded`, `error`, the writers, and
+`ref` — plus a collection's `isActive`). It deliberately omits `isSynced`, so a
+save settling does not re-render it (see [Sync status and loading status](#sync-status-and-loading-status)).
+Pass a `selector` to take further control: it receives the resource's _full_
+observable state — including `isLoading`/`isSynced` — and returns the slice the
+component reacts to, so the component re-renders **only** when that slice changes.
 
 A selected handle exposes exactly your slice as `data`, plus the writer surface
 (`update`/`set`/`delete`/`add`/`remove`/`load`/`sync`) and `ref` — the status
 flags are **not** on it. You react to precisely what you select; status is not a
 freebie, so read it from the state inside the selector when you need it. A
-selector changes what you *read*, never what you *write*.
+selector changes what you _read_, never what you _write_.
 
 ```typescript
 // Re-renders only when the title changes — not on any other field, and not on a
@@ -729,7 +759,7 @@ const { data: space } = useCollection({
 `s.data` is `undefined` while a document is loading (and the collection record is
 `{}`), so selectors should handle the empty case.
 
-When writing from a narrowed handle, use `update` — it takes a *partial* and
+When writing from a narrowed handle, use `update` — it takes a _partial_ and
 merges, so a selected field is just `update({ field: next })`. `set` still
 **replaces the entire document**, not the slice: never pass the selected value
 to `set` (e.g. `set(title)`) or you will overwrite every other field. Reach for
@@ -764,19 +794,72 @@ writable hook on the same resource, so the common provider/leaf pattern (one
 writable owner, many `readOnly: true` read-selectors) sees the writer's
 optimistic edits live. Only the read-only handle's own writers are disabled.
 
+#### Sync status and loading status
+
+The default data handle is **sync-agnostic**: it carries `data`/`isLoaded`/
+`error` but never `isSynced`. That matters because `isSynced` flips on _every_
+autosave settle — so if the data handle carried it, every component that merely
+reads a record would re-render an extra time after each save. Most readers only
+want the data; the few that render save state (a "Saving…" indicator, a
+navigation blocker) opt in explicitly.
+
+For each registry entry, `createFirestate` generates two opt-in status hooks
+beside the data hook:
+
+```typescript
+const { useSpaces, useSpacesSyncStatus, useSpacesLoadingStatus } =
+    createFirestate({ spaces: spacesEntry })
+
+// Only this component re-renders when a save settles — not every data reader.
+function SaveIndicator(params) {
+    const { isSynced, isSaving } = useSpacesSyncStatus(params)
+    return isSaving ? <Spinner /> : <Check />
+}
+
+// A spinner that shows load progress WITHOUT re-rendering when data changes.
+function SpacesSpinner(params) {
+    const { isLoading, isLoaded } = useSpacesLoadingStatus(params)
+    return isLoading ? <Spinner /> : null
+}
+```
+
+Both share the entry's **one** `onSnapshot` listener with the data hook (and any
+slice hooks) — sharing is keyed by `(definition, path, query)`, not by which
+hook you call — so opting in costs no extra subscription. `useSpacesSyncStatus`
+re-renders only when sync state flips; `useSpacesLoadingStatus` re-renders only
+on the load transition, never on data. Collection status hooks take the same
+`queryConstraints` as the data hook (pass the same query to share the listener).
+
+On a **lazy** collection, a status hook does not call `load()` itself — so as
+the _only_ subscriber it stays idle (`{ isSynced: true, isSaving: false }` /
+`{ isLoading: false, isLoaded: false }`) and attaches no listener. Pair it with
+the data hook, whose `load()` activates the one shared listener the status hook
+then rides. Non-lazy collections activate on mount, so this is lazy-only.
+
+`.select` (slice) entries do **not** get their own status hooks — a slice's sync
+and loading state is the resource's, read through the base entry's status hooks.
+
+With the lower-level API there are standalone equivalents —
+`useDocumentSyncStatus` / `useDocumentLoadingStatus` /
+`useCollectionSyncStatus` / `useCollectionLoadingStatus`, each taking
+`{ definition, params, enabled }` (collections also `queryConstraints`).
+
+This is the per-resource counterpart to [`useIsSynced()`](#useissynced), which
+reports a single provider-wide aggregate across _all_ tracked resources.
+
 #### `useUndoManager()`
 
 Access the undo manager.
 
 ```typescript
 const {
-    canUndo,        // Whether undo is available
-    canRedo,        // Whether redo is available
-    undo,           // Undo the last action
-    redo,           // Redo the last undone action
-    clear,          // Clear undo/redo history
-    undoStack,      // Array of undo actions
-    redoStack,      // Array of redo actions
+    canUndo, // Whether undo is available
+    canRedo, // Whether redo is available
+    undo, // Undo the last action
+    redo, // Redo the last undone action
+    clear, // Clear undo/redo history
+    undoStack, // Array of undo actions
+    redoStack, // Array of redo actions
 } = useUndoManager()
 ```
 
@@ -804,11 +887,17 @@ Main provider component.
 
 ```tsx
 <FirestateProvider
-    firestore={db}              // Required: Firestore instance
-    autosave={1000}             // Optional: default debounce (ms)
-    minLoadTime={0}             // Optional: minimum loading time (ms)
-    maxUndoLength={20}          // Optional: max undo stack size
-    onNavigate={(path) => navigate(path)}  // Optional: router navigate for path-aware undo/redo
+    firestore={db} // Required: Firestore instance
+    autosave={1000} // Optional: default debounce (ms)
+    minLoadTime={0} // Optional: minimum loading time (ms)
+    maxUndoLength={20} // Optional: max undo stack size
+    onNavigate={(path) => navigate(path)} // Optional: router navigate for path-aware undo/redo
+    onUndo={(action) =>
+        analytics.track('undo', { description: action.description })
+    }
+    onRedo={(action) =>
+        analytics.track('redo', { description: action.description })
+    }
     onError={(error, context) => {
         // Optional: custom error handler
         console.error(context.path, error)
@@ -878,7 +967,11 @@ const restored = unflattenDiff(flat)
 ### Path-Based Utilities
 
 ```typescript
-import { diffContainsPath, extractDiffValue, createDiffAtPath } from '@hvakr/firestate'
+import {
+    diffContainsPath,
+    extractDiffValue,
+    createDiffAtPath,
+} from '@hvakr/firestate'
 
 const diff = { building: { floors: 5 }, name: 'Test' }
 
@@ -897,7 +990,12 @@ createDiffAtPath('building.config.enabled', true)
 ### General Utilities
 
 ```typescript
-import { isDeepEqual, deepClone, isDiffEmpty, mergeDiffs } from '@hvakr/firestate'
+import {
+    isDeepEqual,
+    deepClone,
+    isDiffEmpty,
+    mergeDiffs,
+} from '@hvakr/firestate'
 
 // Deep equality check (handles Timestamps, arrays, nested objects)
 isDeepEqual(obj1, obj2)
@@ -915,7 +1013,7 @@ const combined = mergeDiffs(diff1, diff2)
 ## Notes
 
 - **`enabled` flag** — pass `enabled: false` to generated hooks or to `useDocument`/`useCollection` when route params or auth-derived ids are not ready yet. Disabled hooks do not resolve paths or attach listeners, which avoids building invalid Firestore paths like `projects//spaces`.
-- **Navigation flicker** — changing `params` rebuilds the listener and briefly shows `isLoading: true`. To keep the previous data visible across the transition, wrap your param in `useDeferredValue`.
+- **Navigation flicker** — changing `params` rebuilds the listener and briefly shows the loading state (`isLoaded: false`). To keep the previous data visible across the transition, wrap your param in `useDeferredValue`.
 - **No cross-doc transactions** — writes are atomic per document and per collection (via `writeBatch`), but not across them. For now, use Firestore's `runTransaction` directly via `handle.ref`.
 - **Per-client undo** — `useUndoManager` is local; one user's undo doesn't propagate to others.
 - **Multi-tab sync** — handled automatically by Firestore's listeners; no extra setup.
@@ -935,8 +1033,15 @@ const store = createStore({
     maxUndoLength: 50,
     onError: (error, context) => {
         // Send to error tracking service
+        if (context.type === 'undo') {
+            analytics.track('undo_error', { operation: context.operation })
+        }
         Sentry.captureException(error, { extra: context })
-    }
+    },
+    onUndo: (action) =>
+        analytics.track('undo', { description: action.description }),
+    onRedo: (action) =>
+        analytics.track('redo', { description: action.description }),
 })
 
 const subscription = createDocumentSubscription({
@@ -965,13 +1070,17 @@ import { createUndoManager } from '@hvakr/firestate'
 const undoManager = createUndoManager({
     maxLength: 50,
     onNavigate: (path) => router.push(path),
+    onUndo: (action) =>
+        analytics.track('undo', { description: action.description }),
+    onRedo: (action) =>
+        analytics.track('redo', { description: action.description }),
 })
 
 undoManager.push({
     undo: () => restoreOldValue(),
     redo: () => applyNewValue(),
     groupId: 'myGroup',
-    path: '/projects/123',  // Navigate here on undo/redo
+    path: '/projects/123', // Navigate here on undo/redo
     description: 'Update project name',
 })
 
@@ -1008,9 +1117,9 @@ const project = useDocument({
     params: { projectId: '123' },
 })
 
-// Missing documents are not errors — `data` is undefined and `isLoading`
-// is false. Render a create/empty state for that case.
-if (!project.isLoading && !project.data) {
+// Missing documents are not errors — once loaded, `data` is undefined.
+// Render a create/empty state for that case.
+if (project.isLoaded && !project.data) {
     return <CreateProject />
 }
 
@@ -1075,8 +1184,7 @@ vi.mock('@hvakr/firestate', () => ({
         update: vi.fn(),
         set: vi.fn(),
         delete: vi.fn(),
-        isLoading: false,
-        isSynced: true,
+        isLoaded: true,
         sync: vi.fn(),
         error: undefined,
         ref: {},
@@ -1141,8 +1249,14 @@ export const spacesCollection = defineCollection<Space>({
 
 // Component.tsx
 function ProjectEditor({ projectId }) {
-    const project = useDocument({ definition: projectDoc, params: { projectId } })
-    const spaces = useCollection({ definition: spacesCollection, params: { projectId } })
+    const project = useDocument({
+        definition: projectDoc,
+        params: { projectId },
+    })
+    const spaces = useCollection({
+        definition: spacesCollection,
+        params: { projectId },
+    })
     const isSynced = useIsSynced() // Automatic!
 
     // That's it. Undo/redo is automatic.