@hvakr/firestate 0.1.3 → 0.1.4

package/README.md

@@ -220,22 +220,33 @@ 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 (
@@ -253,7 +264,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 +277,7 @@ function ProjectEditor({ projectId }: { projectId: string }) {
             )}
 
             {/* Sync indicator */}
-            {!project.isSynced && <span>Saving...</span>}
+            {isSaving && <span>Saving...</span>}
         </div>
     )
 }
@@ -622,8 +633,7 @@ const {
     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
+    isLoaded,       // Whether the initial snapshot has arrived (ready to render)
     sync,           // Force sync immediately
     error,          // Error from listener, if any
     ref,            // Firestore DocumentReference
@@ -634,6 +644,12 @@ const {
     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)`
@@ -646,9 +662,8 @@ const {
     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
+    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
@@ -688,12 +703,14 @@ 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
@@ -764,6 +781,59 @@ 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.
@@ -915,7 +985,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.
@@ -1008,9 +1078,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 +1145,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: {},

package/dist/index.d.mts

@@ -27,27 +27,43 @@ interface UpdateOptions {
   undoGroupId?: string;
 }
 /**
- * State of a document subscription
+ * The full observable state of a document subscription — what a hook `selector`
+ * receives. Carries every status flag (including `isSynced`, which the default
+ * data handle deliberately omits) so a selector can react to exactly the slice
+ * it reads.
  */
 interface DocumentState<T> {
   /** Current merged state (local changes applied to sync state) */
   data: T | undefined;
-  /** Whether initial data has loaded */
+  /** Whether the initial snapshot has not arrived yet */
   isLoading: boolean;
-  /** Whether there are pending local changes */
+  /**
+       * Whether the initial snapshot has arrived and data is ready to render — the
+       * completion of {@link DocumentState.isLoading} (`!isLoading` for a live
+       * subscription; `false` while the hook is disabled).
+       */
+  isLoaded: boolean;
+  /** Whether all local changes have synced to Firestore (no pending writes) */
   isSynced: boolean;
   /** Error from listener, if any */
   error: Error | undefined;
 }
 /**
- * State of a collection subscription
+ * The full observable state of a collection subscription — what a hook
+ * `selector` receives. See {@link DocumentState}.
  */
 interface CollectionState<T> {
   /** Current merged state keyed by document ID */
   data: Record<string, T>;
-  /** Whether initial data has loaded */
+  /** Whether the initial snapshot has not arrived yet */
   isLoading: boolean;
-  /** Whether there are pending local changes */
+  /**
+       * Whether the collection is active and its initial snapshot has arrived —
+       * `isActive && !isLoading`. `false` for a lazy collection before `load()`,
+       * and while the hook is disabled.
+       */
+  isLoaded: boolean;
+  /** Whether all local changes have synced to Firestore (no pending writes) */
   isSynced: boolean;
   /** Whether the collection has been activated (for lazy loading) */
   isActive: boolean;
@@ -55,7 +71,38 @@ interface CollectionState<T> {
   error: Error | undefined;
 }
 /**
- * Document handle returned by useDocument hook
+ * Sync status of a single resource, returned by the per-entry
+ * `use{Name}SyncStatus` hook. Opt-in: only components that render save/dirty
+ * state subscribe to it, so the common data path does not re-render when a write
+ * settles. Shares the resource's one `onSnapshot` listener.
+ */
+interface SyncStatus {
+  /** Whether all local changes have synced to Firestore (no pending writes) */
+  isSynced: boolean;
+  /** Whether there are pending local changes still being saved (`!isSynced`) */
+  isSaving: boolean;
+}
+/**
+ * Loading status of a single resource, returned by the per-entry
+ * `use{Name}LoadingStatus` hook. A spinner-only channel: it re-renders on load
+ * transitions but never on data changes. Shares the resource's listener.
+ */
+interface LoadingStatus {
+  /** Whether the initial snapshot has not arrived yet */
+  isLoading: boolean;
+  /** Whether the initial snapshot has arrived (the completion of `isLoading`) */
+  isLoaded: boolean;
+}
+/**
+ * Document handle returned by the `useDocument` hook.
+ *
+ * **Sync-agnostic by default.** The handle carries `data`, `isLoaded`, `error`,
+ * the writers, and `ref` — but NOT `isSynced`. A document hook therefore does
+ * not re-render when a write settles (the `isSynced` flip on every autosave),
+ * so "just render the record" is the cheap, default path. Components that
+ * actually render save/dirty state opt into the per-entry `use{Name}SyncStatus`
+ * hook ({@link SyncStatus}), which shares the same listener. The raw
+ * `isLoading`/`isSynced` flags remain on {@link DocumentState} for selectors.
  */
 interface DocumentHandle<T extends FirestoreObject> {
   /** Current document data */
@@ -66,10 +113,13 @@ interface DocumentHandle<T extends FirestoreObject> {
   set: (data: T, options?: UpdateOptions) => void;
   /** Delete the document */
   delete: (options?: UpdateOptions) => void;
-  /** Whether initial data is loading */
-  isLoading: boolean;
-  /** Whether all changes have synced to Firestore */
-  isSynced: boolean;
+  /**
+       * Whether the initial snapshot has arrived and data is ready to render — the
+       * completion of `isLoading`. `false` while loading or when the hook is
+       * disabled. (Use `use{Name}LoadingStatus` for an `isLoading`/`isLoaded`
+       * channel that does not re-render on data changes.)
+       */
+  isLoaded: boolean;
   /** Force sync pending changes immediately */
   sync: () => Promise<void>;
   /** Error from listener, if any */
@@ -81,7 +131,13 @@ interface DocumentHandle<T extends FirestoreObject> {
   ref: DocumentReference<T> | undefined;
 }
 /**
- * Collection handle returned by useCollection hook
+ * Collection handle returned by the `useCollection` hook.
+ *
+ * Sync-agnostic by default, exactly like {@link DocumentHandle}: it carries
+ * `data`, `isLoaded`, `isActive`, `error`, the writers, `load`, and `ref` — but
+ * NOT `isSynced`. Opt into `use{Name}SyncStatus` for save state. `isActive`
+ * stays (lazy collections gate a "Load" button on it); `isLoaded` is
+ * `isActive && !isLoading`.
  */
 interface CollectionHandle<T extends FirestoreObject> {
   /** Current collection data keyed by document ID */
@@ -102,10 +158,12 @@ interface CollectionHandle<T extends FirestoreObject> {
   };
   /** Remove a document from the collection */
   remove: (id: string, options?: UpdateOptions) => void;
-  /** Whether initial data is loading */
-  isLoading: boolean;
-  /** Whether all changes have synced to Firestore */
-  isSynced: boolean;
+  /**
+       * Whether the collection is active and its initial snapshot has arrived
+       * (ready to render) — `isActive && !isLoading`. `false` for a lazy
+       * collection before `load()`, while loading, or when the hook is disabled.
+       */
+  isLoaded: boolean;
   /** Whether subscription is active (for lazy collections) */
   isActive: boolean;
   /** Activate a lazy subscription */
@@ -121,7 +179,7 @@ interface CollectionHandle<T extends FirestoreObject> {
   ref: CollectionReference<T> | undefined;
 }
 /** Reactive status fields a selector drops unless it folds them into its slice. */
-type DocumentStatusKeys = "isLoading" | "isSynced" | "error";
+type DocumentStatusKeys = "isLoaded" | "error";
 type CollectionStatusKeys = DocumentStatusKeys | "isActive";
 /**
  * A {@link DocumentHandle} reduced to a hook-level `selector`'s output. The
@@ -131,8 +189,8 @@ type CollectionStatusKeys = DocumentStatusKeys | "isActive";
  *
  * A selected handle deliberately exposes **only** `data` (the slice) plus the
  * writer surface (`update`/`set`/`delete`/`sync`) and `ref` — never the status
- * fields (`isLoading`/`isSynced`/`error`). Status is not a freebie here: if a
- * component needs it, it must select it (`s => ({ slice: s.data?.x, loading:
+ * fields (`isLoaded`/`error`). Status is not a freebie here: if a component
+ * needs it, it must select it (`s => ({ slice: s.data?.x, loading:
  * s.isLoading })`), so what you re-render on is exactly what you select. The
  * writers stay typed against the full document `TData`, because a selector
  * changes what you *read*, never what you *write*.
@@ -152,9 +210,9 @@ interface SelectedDocumentHandle<TData extends FirestoreObject, TSelected> exten
  * with {@link SelectedDocumentHandle}, the selector receives the full
  * observable state ({@link CollectionState}) and the handle exposes only the
  * slice plus the writer surface (`update`/`add`/`remove`/`load`/`sync`) and
- * `ref` — status fields (`isLoading`/`isSynced`/`isActive`/`error`) are dropped
- * unless folded into the slice. Writers stay typed against the full collection
- * of `TData`.
+ * `ref` — status fields (`isLoaded`/`isActive`/`error`) are dropped unless
+ * folded into the slice. Writers stay typed against the full collection of
+ * `TData`.
  */
 interface SelectedCollectionHandle<TData extends FirestoreObject, TSelected> extends Omit<CollectionHandle<TData>, "data" | CollectionStatusKeys> {
   /** The slice produced by the hook's `selector`. */
@@ -506,8 +564,9 @@ interface DocumentSelectorOptions<TData extends FirestoreObject, TSelected> {
   /**
        * Project the document's observable state down to the slice this component
        * reacts to. The selector receives the full {@link DocumentState} —
-       * `{ data, isLoading, isSynced, error }`, where `data` is `undefined` while
-       * the document is loading or the hook is disabled — and the component
+       * `{ data, isLoading, isLoaded, isSynced, error }`, where `data` is
+       * `undefined` while the document is loading or the hook is disabled — and
+       * the component
        * re-renders *only* when the returned slice changes (per `isEqual`). Status
        * is not a freebie: read `s.isLoading`/`s.isSynced`/`s.error` here if you
        * want to react to them (e.g. `s => ({ title: s.data?.title, saving:
@@ -533,8 +592,9 @@ interface CollectionSelectorOptions<TData extends FirestoreObject, TSelected> {
   /**
        * Project the collection's observable state down to the slice this component
        * reacts to. The selector receives the full {@link CollectionState} —
-       * `{ data, isLoading, isSynced, isActive, error }`, where `data` is the keyed
-       * record (e.g. `s => s.data[id]` or `s => Object.keys(s.data)`) — and the
+       * `{ data, isLoading, isLoaded, isSynced, isActive, error }`, where `data` is
+       * the keyed record (e.g. `s => s.data[id]` or `s => Object.keys(s.data)`) —
+       * and the
        * component re-renders *only* when the returned slice changes. As with
        * {@link DocumentSelectorOptions.selector}, status is reactive only if you
        * select it, and the returned handle exposes just the slice plus
@@ -583,9 +643,8 @@ interface UseDocumentOptions<TData extends FirestoreObject> {
   undoable?: boolean;
   /**
        * If false, no subscription is created and a no-op handle is returned
-       * (`{ data: undefined, isLoading: false, isSynced: true, ref: undefined }`).
-       * Use this to gate subscriptions on route params that aren't ready yet.
-       * Default: true.
+       * (`{ data: undefined, isLoaded: false, ref: undefined }`). Use this to gate
+       * subscriptions on route params that aren't ready yet. Default: true.
        */
   enabled?: boolean;
 }
@@ -607,10 +666,15 @@ interface UseDocumentOptions<TData extends FirestoreObject> {
  * 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
+ * the initial handle (`{ data: undefined, isLoaded: false }`). Mutations like
  * `update`/`set` will mutate orphaned local state with no effect — avoid
  * calling them server-side.
  *
+ * The default handle is **sync-agnostic** — it carries `data`/`isLoaded`/`error`
+ * but not `isSynced`, so it does not re-render when a write settles. Render save
+ * state via the per-entry `use{Name}SyncStatus` hook, or fold `isSynced` into a
+ * `selector`.
+ *
  * @example
  * ```tsx
  * const projectDoc = defineDocument<Project>({
@@ -619,12 +683,12 @@ interface UseDocumentOptions<TData extends FirestoreObject> {
  * })
  *
  * function ProjectEditor({ projectId }: { projectId: string }) {
- *   const { data, update, isLoading, isSynced } = useDocument({
+ *   const { data, update, isLoaded } = useDocument({
  *     definition: projectDoc,
  *     params: { projectId },
  *   })
  *
- *   if (isLoading) return <Spinner />
+ *   if (!isLoaded) return <Spinner />
  *
  *   return (
  *     <input
@@ -669,7 +733,7 @@ interface UseCollectionOptions<TData extends FirestoreObject> {
   undoable?: boolean;
   /**
        * If false, no subscription is created and a no-op handle is returned
-       * (`{ data: {}, isLoading: false, isActive: false }`). Use this to gate on
+       * (`{ data: {}, isLoaded: false, isActive: false }`). Use this to gate on
        * route params that aren't ready yet. Default: true.
        */
   enabled?: boolean;
@@ -708,8 +772,13 @@ interface UseCollectionOptions<TData extends FirestoreObject> {
  * 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.
+ * the initial handle (`{ data: {}, isLoaded: false }`, `isActive: false` for
+ * lazy). Avoid calling mutations server-side.
+ *
+ * Like {@link useDocument}, the default handle is **sync-agnostic** — `data`,
+ * `isLoaded`, `isActive`, `error`, but not `isSynced`. `isActive` stays so a
+ * lazy collection can gate a "Load" button; `isLoaded` is `isActive &&
+ * !isLoading`. Render save state via `use{Name}SyncStatus`.
  *
  * @example
  * ```tsx
@@ -719,7 +788,7 @@ interface UseCollectionOptions<TData extends FirestoreObject> {
  * })
  *
  * function SpacesList({ projectId }: { projectId: string }) {
- *   const { data, update, load, isActive, isLoading } = useCollection({
+ *   const { data, update, load, isActive, isLoaded } = useCollection({
  *     definition: spacesCollection,
  *     params: { projectId },
  *   })
@@ -728,7 +797,7 @@ interface UseCollectionOptions<TData extends FirestoreObject> {
  *   useEffect(() => { load() }, [load])
  *
  *   if (!isActive) return <Button onClick={load}>Load Spaces</Button>
- *   if (isLoading) return <Spinner />
+ *   if (!isLoaded) return <Spinner />
  *
  *   return (
  *     <ul>
@@ -758,6 +827,78 @@ declare function useCollection<TData extends FirestoreObject>(options: UseCollec
  * ```
  */
 declare function useCollection<TData extends FirestoreObject, TSelected>(options: UseCollectionOptions<TData> & CollectionSelectorOptions<TData, TSelected>): SelectedCollectionHandle<TData, TSelected>;
+/** Options for the document status hooks (a subset of {@link UseDocumentOptions}). */
+interface UseDocumentStatusOptions<TData extends FirestoreObject> {
+  /** Document definition from defineDocument(). */
+  definition: DocumentDefinition<TData>;
+  /** Route/path parameters for dynamic paths. */
+  params?: Record<string, string>;
+  /**
+       * If false, no subscription is created and the idle status is returned
+       * (`{ isSynced: true, isSaving: false }` / `{ isLoading: false, isLoaded:
+       * false }`). Default: true.
+       */
+  enabled?: boolean;
+}
+/** Options for the collection status hooks. Adds `queryConstraints`. */
+interface UseCollectionStatusOptions<TData extends FirestoreObject> {
+  /** Collection definition from defineCollection(). */
+  definition: CollectionDefinition<TData>;
+  /** Route/path parameters for dynamic paths. */
+  params?: Record<string, string>;
+  /**
+       * Query constraints. Must produce the same query the data hook uses, or the
+       * status hook resolves a *different* shared entry (a second listener) —
+       * sharing is keyed by semantic query identity.
+       */
+  queryConstraints?: QueryConstraint[];
+  /** See {@link UseDocumentStatusOptions.enabled}. */
+  enabled?: boolean;
+}
+/**
+ * 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 }`.
+ */
+declare function useDocumentSyncStatus<TData extends FirestoreObject>(options: UseDocumentStatusOptions<TData>): SyncStatus;
+/**
+ * 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.
+ */
+declare function useDocumentLoadingStatus<TData extends FirestoreObject>(options: UseDocumentStatusOptions<TData>): LoadingStatus;
+/**
+ * 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.
+ */
+declare function useCollectionSyncStatus<TData extends FirestoreObject>(options: UseCollectionStatusOptions<TData>): SyncStatus;
+/**
+ * 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.
+ */
+declare function useCollectionLoadingStatus<TData extends FirestoreObject>(options: UseCollectionStatusOptions<TData>): LoadingStatus;
 /**
  * Keyboard shortcut hook for undo/redo
  *
@@ -1036,7 +1177,21 @@ type SelectedParams<P extends string, PExtra> = IsAny<PExtra> extends true ? Par
 type SelectedDocHookFor<T extends FirestoreObject, P extends string, PExtra, TSelected> = keyof SelectedParams<P, PExtra> extends never ? (params?: Record<string, string>, options?: DocHookOptions<T>) => SelectedDocumentHandle<T, TSelected> : (params: SelectedParams<P, PExtra>, options?: DocHookOptions<T>) => SelectedDocumentHandle<T, TSelected>;
 type SelectedColHookFor<T extends FirestoreObject, P extends string, PExtra, TSelected> = keyof SelectedParams<P, PExtra> extends never ? (params?: Record<string, string>, options?: ColHookOptions<T>) => SelectedCollectionHandle<T, TSelected> : (params: SelectedParams<P, PExtra>, options?: ColHookOptions<T>) => SelectedCollectionHandle<T, TSelected>;
 type HookFor<E> = E extends SelectedDocEntry<infer T, infer P, infer PExtra, infer TSelected> ? SelectedDocHookFor<T, P, PExtra, TSelected> : E extends SelectedColEntry<infer T, infer P, infer PExtra, infer TSelected> ? SelectedColHookFor<T, P, PExtra, TSelected> : E extends DocEntry<infer T, infer P> ? keyof ParamsOf<P> extends never ? DocHookOptionalParams<T> : DocHookRequiredParams<T, P> : E extends ColEntry<infer T, infer P> ? keyof ParamsOf<P> extends never ? ColHookOptionalParams<T> : ColHookRequiredParams<T, P> : never;
-type FirestateApi<R extends FirestateRegistry> = { [K in keyof R & string as HookName<K>]: HookFor<R[K]> };
+type SyncStatusHookName<K extends string> = `${HookName<K>}SyncStatus`;
+type LoadingStatusHookName<K extends string> = `${HookName<K>}LoadingStatus`;
+type BaseEntry = DocEntry<any, any> | ColEntry<any, any>;
+type DocStatusHookOptions = {
+  enabled?: boolean;
+};
+type ColStatusHookOptions = {
+  enabled?: boolean;
+  queryConstraints?: QueryConstraint[];
+};
+type DocStatusHookFor<P extends string, Ret> = keyof ParamsOf<P> extends never ? (params?: Record<string, string>, options?: DocStatusHookOptions) => Ret : (params: ParamsOf<P>, options?: DocStatusHookOptions) => Ret;
+type ColStatusHookFor<P extends string, Ret> = keyof ParamsOf<P> extends never ? (params?: Record<string, string>, options?: ColStatusHookOptions) => Ret : (params: ParamsOf<P>, options?: ColStatusHookOptions) => Ret;
+type SyncStatusHookFor<E> = E extends DocEntry<any, infer P> ? DocStatusHookFor<P, SyncStatus> : E extends ColEntry<any, infer P> ? ColStatusHookFor<P, SyncStatus> : never;
+type LoadingStatusHookFor<E> = E extends DocEntry<any, infer P> ? DocStatusHookFor<P, LoadingStatus> : E extends ColEntry<any, infer P> ? ColStatusHookFor<P, LoadingStatus> : never;
+type FirestateApi<R extends FirestateRegistry> = { [K in keyof R & string as HookName<K>]: HookFor<R[K]> } & { [K in keyof R & string as R[K] extends BaseEntry ? SyncStatusHookName<K> : never]: SyncStatusHookFor<R[K]> } & { [K in keyof R & string as R[K] extends BaseEntry ? LoadingStatusHookName<K> : never]: LoadingStatusHookFor<R[K]> };
 /**
  * Turn a Firestate registry into a map of typed React hooks. Each entry
  * `K` produces a hook named `use{Capitalize<K>}`.
@@ -1489,5 +1644,5 @@ declare const FirestateStoreProvider: React.FC<FirestateStoreProviderProps>;
  */
 declare const useUnsavedChangesBlocker: () => boolean;
 //#endregion
-export { type AnySelectedEntry, type ColEntry, type CollectionDefinition, type CollectionHandle, type CollectionOptions, type CollectionSelectorOptions, type CollectionState, type DeepPartial, type DocEntry, type DocumentDefinition, type DocumentHandle, type DocumentOptions, type DocumentSelectorOptions, type DocumentState, type ErrorContext, type FirestateApi, type FirestateConfig, FirestateContext, type FirestateEntry, FirestateProvider, type FirestateProviderProps, type FirestateRegistry, type FirestateStore, FirestateStoreProvider, type FirestateStoreProviderProps, type FirestoreObject, type InferCollectionData, type InferCollectionDocument, type InferDocument, type InferDocumentData, type SelectOptions, type SelectedColEntry, type SelectedCollectionHandle, type SelectedDocEntry, type SelectedDocumentHandle, type Store, type UndoAction, type UndoManager, type UndoManagerConfig, type UndoManagerState, type UndoManagerWithSubscribe, type UpdateOptions, type UseCollectionOptions, type UseDocumentOptions, 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, useDocument, useIsSynced, useStore, useUndoKeyboardShortcuts, useUndoManager, useUnsavedChangesBlocker };
+export { type AnySelectedEntry, type ColEntry, type CollectionDefinition, type CollectionHandle, type CollectionOptions, type CollectionSelectorOptions, type CollectionState, type DeepPartial, type DocEntry, type DocumentDefinition, type DocumentHandle, type DocumentOptions, type DocumentSelectorOptions, type DocumentState, type ErrorContext, type FirestateApi, type FirestateConfig, FirestateContext, type FirestateEntry, FirestateProvider, type FirestateProviderProps, type FirestateRegistry, type FirestateStore, FirestateStoreProvider, type FirestateStoreProviderProps, type FirestoreObject, type InferCollectionData, type InferCollectionDocument, type InferDocument, type InferDocumentData, type LoadingStatus, type SelectOptions, type SelectedColEntry, type SelectedCollectionHandle, type SelectedDocEntry, type SelectedDocumentHandle, type Store, type SyncStatus, type UndoAction, type UndoManager, type UndoManagerConfig, type UndoManagerState, type UndoManagerWithSubscribe, type UpdateOptions, type UseCollectionOptions, type UseCollectionStatusOptions, type UseDocumentOptions, type UseDocumentStatusOptions, 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.d.mts.map