@hvakr/firestate 0.1.1 → 0.1.3

package/dist/index.d.mts

@@ -120,6 +120,46 @@ 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 CollectionStatusKeys = DocumentStatusKeys | "isActive";
+/**
+ * A {@link DocumentHandle} reduced to a hook-level `selector`'s output. The
+ * selector receives the full observable state ({@link DocumentState}) and
+ * returns the slice this component reacts to; the handle re-renders *only* when
+ * that slice changes.
+ *
+ * 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:
+ * 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*.
+ *
+ * Note: `update(diff)` takes a *partial* of the full document and merges it, so
+ * writing a selected field is `update({ field: next })`. `set(data)` still
+ * *replaces the entire document*, not the slice — never pass the selected value
+ * to `set`, or you will overwrite every other field. Prefer `update` from a
+ * narrowed handle; reach for `set` only when you hold the full document.
+ */
+interface SelectedDocumentHandle<TData extends FirestoreObject, TSelected> extends Omit<DocumentHandle<TData>, "data" | DocumentStatusKeys> {
+  /** The slice produced by the hook's `selector`. */
+  data: TSelected;
+}
+/**
+ * A {@link CollectionHandle} reduced to a hook-level `selector`'s output. As
+ * 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`.
+ */
+interface SelectedCollectionHandle<TData extends FirestoreObject, TSelected> extends Omit<CollectionHandle<TData>, "data" | CollectionStatusKeys> {
+  /** The slice produced by the hook's `selector`. */
+  data: TSelected;
+}
 /**
  * An undo/redo action
  */
@@ -269,7 +309,7 @@ type Subscriber<T> = (state: T) => void;
  */
 type Unsubscribe = () => void;
 //#endregion
-//#region src/schema.d.ts
+//#region src/registry/schema.d.ts
 /**
  * Define a typed document. `TData` is the document's TypeScript shape.
  *
@@ -355,7 +395,7 @@ type InferCollectionDocument<T extends CollectionDefinition<FirestoreObject>> =
   id: string;
 };
 //#endregion
-//#region src/undo.d.ts
+//#region src/utils/undo.d.ts
 /**
  * Configuration for creating an undo manager
  */
@@ -392,7 +432,7 @@ declare const createUndoManager: (config?: UndoManagerConfig) => UndoManager & {
  */
 type UndoManagerWithSubscribe = ReturnType<typeof createUndoManager>;
 //#endregion
-//#region src/store.d.ts
+//#region src/core/store.d.ts
 /**
  * Firestate store that holds configuration and shared state
  */
@@ -456,7 +496,63 @@ declare const createStore: (config: FirestateConfig) => FirestateStore;
  */
 type Store = ReturnType<typeof createStore>;
 //#endregion
-//#region src/hooks.d.ts
+//#region src/react/hooks.d.ts
+/**
+ * Opts a {@link useDocument} call into a selected slice. The hook still returns
+ * a full handle (writers, `ref`, status) — only `data` is narrowed to whatever
+ * `selector` returns.
+ */
+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
+       * 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:
+       * !s.isSynced })`). What you select is exactly what re-renders, and the
+       * returned handle exposes only the slice plus writers/`ref`.
+       */
+  selector: (state: DocumentState<TData>) => TSelected;
+  /**
+       * Decide whether two consecutive slices are equal; the hook re-renders only
+       * when this returns `false`. Defaults to a deep value comparison, so a
+       * selector that returns a fresh object/array of the same shape does not
+       * over-render. Pass {@link shallow} for a one-level compare, or a custom
+       * comparator.
+       */
+  isEqual?: (a: TSelected, b: TSelected) => boolean;
+}
+/**
+ * Opts a {@link useCollection} call into a selected slice. See
+ * {@link DocumentSelectorOptions}; the only difference is the selector receives
+ * the collection's keyed record.
+ */
+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
+       * 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
+       * writers/`ref`.
+       */
+  selector: (state: CollectionState<TData>) => TSelected;
+  /** See {@link DocumentSelectorOptions.isEqual}. */
+  isEqual?: (a: TSelected, b: TSelected) => boolean;
+}
+/**
+ * Shape used by the non-selector hook overload to *exclude* selector options,
+ * so passing a real `selector` falls through to the selector overload (which
+ * infers `TSelected`) instead of silently resolving to the full-data return.
+ */
+type WithoutSelector = {
+  selector?: undefined;
+  isEqual?: undefined;
+};
 /**
  * Context for providing the Firestate store
  */
@@ -497,10 +593,15 @@ interface UseDocumentOptions<TData extends FirestoreObject> {
  * 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.
+ * computed id). 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.
+ *
+ * `readOnly` is a *per-handle capability*, not part of the key: a `readOnly`
+ * hook shares the same listener and optimistic state as a writable hook on the
+ * same document (a write through the writable handle is instantly visible to
+ * the read-only reader), and only this handle's own writers (`update`/`set`/
+ * `delete`) and `sync` are disabled.
  *
  * Use `enabled: false` to suppress the subscription entirely (e.g., when
  * route params aren't ready yet).
@@ -534,7 +635,24 @@ interface UseDocumentOptions<TData extends FirestoreObject> {
  * }
  * ```
  */
-declare const useDocument: <TData extends FirestoreObject>(options: UseDocumentOptions<TData>) => DocumentHandle<TData>;
+declare function useDocument<TData extends FirestoreObject>(options: UseDocumentOptions<TData> & WithoutSelector): DocumentHandle<TData>;
+/**
+ * Selector overload: pass `selector` to narrow the returned `data` to a slice
+ * and re-render only when that slice changes. Writers (`update`/`set`/`delete`)
+ * and `ref` keep operating on the full document. See
+ * {@link DocumentSelectorOptions}.
+ *
+ * @example
+ * ```tsx
+ * // Re-renders only when the title changes, not on any other field.
+ * const { data: title, update } = useDocument({
+ *   definition: projectDoc,
+ *   params: { projectId },
+ *   selector: (s) => s.data?.title,
+ * })
+ * ```
+ */
+declare function useDocument<TData extends FirestoreObject, TSelected>(options: UseDocumentOptions<TData> & DocumentSelectorOptions<TData, TSelected>): SelectedDocumentHandle<TData, TSelected>;
 /**
  * Options for useCollection hook
  */
@@ -559,14 +677,32 @@ interface UseCollectionOptions<TData extends FirestoreObject> {
 /**
  * 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.
+ * The subscription is keyed on the resolved collection path and the *semantic
+ * identity* of `queryConstraints`. When either changes, the listener is torn
+ * down and re-attached with the new query. Toggling `undoable` does not rebuild
+ * the subscription. `readOnly` is a per-handle capability, not part of the key —
+ * a `readOnly` hook shares one listener and optimistic state with a writable
+ * hook on the same query (see {@link useDocument}).
  *
- * **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.
+ * **You do not need to memoize `queryConstraints`.** `QueryConstraint` objects
+ * are opaque, so Firestate compares the *built query* with Firestore's own
+ * `queryEqual` instead of comparing array references. A fresh array that
+ * produces the same query (e.g. constraint inputs read from a document that
+ * Firestate deep-clones on optimistic updates) does not rebuild the listener;
+ * only a genuine change to the query does:
+ *
+ * ```tsx
+ * // stationIds may change reference on every edit to its parent document,
+ * // even when its contents are unchanged — the listener survives anyway.
+ * const stations = useCollection({
+ *   definition: weatherStations,
+ *   queryConstraints: [where(documentId(), 'in', stationIds)],
+ * })
+ * ```
+ *
+ * Memoizing is still a fine micro-optimization (it skips the per-render query
+ * build + compare via the reference fast-path), but it is no longer required
+ * for listener stability.
  *
  * Use `enabled: false` to suppress the subscription entirely (e.g., when
  * route params aren't ready yet).
@@ -604,7 +740,24 @@ interface UseCollectionOptions<TData extends FirestoreObject> {
  * }
  * ```
  */
-declare const useCollection: <TData extends FirestoreObject>(options: UseCollectionOptions<TData>) => CollectionHandle<TData>;
+declare function useCollection<TData extends FirestoreObject>(options: UseCollectionOptions<TData> & WithoutSelector): CollectionHandle<TData>;
+/**
+ * Selector overload: pass `selector` to narrow the returned `data` to a slice
+ * of the collection and re-render only when that slice changes. Writers
+ * (`update`/`add`/`remove`) and `ref` keep operating on the full collection.
+ * See {@link CollectionSelectorOptions}.
+ *
+ * @example
+ * ```tsx
+ * // Re-renders only when this one document's slice changes.
+ * const { data: space } = useCollection({
+ *   definition: spacesCollection,
+ *   params: { projectId },
+ *   selector: (s) => s.data[spaceId],
+ * })
+ * ```
+ */
+declare function useCollection<TData extends FirestoreObject, TSelected>(options: UseCollectionOptions<TData> & CollectionSelectorOptions<TData, TSelected>): SelectedCollectionHandle<TData, TSelected>;
 /**
  * Keyboard shortcut hook for undo/redo
  *
@@ -618,7 +771,7 @@ declare const useCollection: <TData extends FirestoreObject>(options: UseCollect
  */
 declare const useUndoKeyboardShortcuts: () => void;
 //#endregion
-//#region src/firestate.d.ts
+//#region src/registry/firestate.d.ts
 /**
  * Knobs forwarded from a generated document hook to {@link useDocument}.
  * Same shape as `UseDocumentOptions` minus the fields the registry already
@@ -652,8 +805,13 @@ interface CommonEntryOptions {
 interface DocEntry<T extends FirestoreObject, P extends string = string> extends CommonEntryOptions {
   readonly __kind: "document";
   readonly __type?: T;
-  /** Path template, e.g. `'taskLists/{listId}'`. */
-  path: P;
+  /**
+       * Path template, e.g. `'taskLists/{listId}'`, or a function returning the
+       * **full document path** at runtime (the collection/id split happens
+       * per-call via {@link splitDocPath}). Use the function form for paths that
+       * branch on a param. See {@link PathArg}.
+       */
+  path: PathArg<P>;
   /**
        * Zod schema. **Required** — firestate's registry API is opinionated
        * about Zod. The schema is the source of `T` for the generated hooks
@@ -667,22 +825,126 @@ interface DocEntry<T extends FirestoreObject, P extends string = string> extends
        * param typing and no runtime validation.
        */
   schema: ZodType<T>;
+  /**
+       * Derive a **named slice-hook** off this document, sharing its schema and
+       * path — the schema is handed to firestate once, here, and never
+       * re-specified. The `selector` receives the full {@link DocumentState};
+       * return the slice the generated hook reacts to. For a *parameterized* slice,
+       * declare the extra params as the selector's second argument — the generated
+       * hook then requires the path params **and** those, merged into one bag.
+       *
+       * Pass the result to {@link createFirestate} under the key the hook is named
+       * for. Status is reactive only if the slice reads it, exactly as the inline
+       * `selector` option (see {@link DocumentHandle}); the comparator (`isEqual`)
+       * is baked in here, not passed per call.
+       *
+       * ```ts
+       * const project = doc({ path: 'projects/{projectId}', schema: ProjectSchema })
+       * const { useProject, useProjectTitle } = createFirestate({
+       *   project,                                           // → useProject (full)
+       *   projectTitle: project.select((s) => s.data?.name), // → useProjectTitle
+       * })
+       * ```
+       *
+       * A derived entry is a leaf, not a base: there is intentionally no
+       * `.select(...).select(...)` chaining.
+       *
+       * `PExtra` (the selector's own params) defaults to `{}`: a one-argument
+       * selector leaves it unbound, a two-argument one infers it from the annotated
+       * second parameter. One signature keeps the selector's `state` arg reliably
+       * typed in both cases. `PExtra` is intentionally unconstrained — leaving it
+       * `extends Record<string, string>` made TS resolve a param-less selector's
+       * `PExtra` to that constraint (not the `{}` default), wrongly forcing a
+       * `params` arg on no-placeholder paths; unconstrained also lets a slice take
+       * non-string params (e.g. `{ index: number }`).
+       */
+  select<TSelected, PExtra = {}>(selector: (state: DocumentState<T>, params: PExtra) => TSelected, options?: SelectOptions<TSelected>): SelectedDocEntry<T, P, PExtra, TSelected>;
 }
 /** Collection entry in a Firestate registry. Produced by {@link col}. */
 interface ColEntry<T extends FirestoreObject, P extends string = string> extends CommonEntryOptions {
   readonly __kind: "collection";
   readonly __type?: T;
-  /** Path template, e.g. `'taskLists/{listId}/tasks'`. */
-  path: P;
+  /**
+       * Path template, e.g. `'taskLists/{listId}/tasks'`, or a function returning
+       * the **collection path** at runtime. Use the function form for paths that
+       * branch on a param. See {@link PathArg}.
+       */
+  path: PathArg<P>;
   /** Zod schema. Required. See {@link DocEntry.schema}. */
   schema: ZodType<T>;
   /** Only subscribe when `load()` is called. */
   lazy?: boolean;
   /** Additional Firestore query constraints. */
   queryConstraints?: QueryConstraint[];
+  /**
+       * Derive a **named slice-hook** off this collection, sharing its schema,
+       * path, and query — see {@link DocEntry.select}. The `selector` receives the
+       * full {@link CollectionState} (`s.data` is the keyed record), and a
+       * parameterized slice declares its extra params as the selector's second
+       * argument.
+       *
+       * ```ts
+       * const tasks = col({ path: 'projects/{projectId}/tasks', schema: TaskSchema })
+       * const { useTasks, useTaskIds, useTaskById } = createFirestate({
+       *   tasks,                                                  // → useTasks (full)
+       *   taskIds:  tasks.select((s) => Object.keys(s.data)),     // → useTaskIds
+       *   taskById: tasks.select((s, p: { id: string }) => s.data[p.id]), // → useTaskById
+       * })
+       * // useTaskById requires the merged bag: useTaskById({ projectId, id })
+       * ```
+       *
+       * `PExtra` defaults to `{}` and is unconstrained — see {@link DocEntry.select}.
+       */
+  select<TSelected, PExtra = {}>(selector: (state: CollectionState<T>, params: PExtra) => TSelected, options?: SelectOptions<TSelected>): SelectedColEntry<T, P, PExtra, TSelected>;
+}
+/**
+ * Options bundled into a `.select(...)` entry at definition time. Kept separate
+ * from the runtime hook options (`enabled`/`readOnly`/`queryConstraints`)
+ * because these are baked into the named hook, not passed per call.
+ */
+interface SelectOptions<TSelected> {
+  /**
+       * Comparator for this named hook's slice; the hook re-renders only when it
+       * returns `false`. Defaults to a deep value compare (so a fresh object/array
+       * of equal shape does not over-render). Pass {@link shallow} or a custom fn.
+       */
+  isEqual?: (a: TSelected, b: TSelected) => boolean;
+}
+/**
+ * A {@link DocEntry} narrowed by a `.select(...)` projection. Produced by
+ * {@link DocEntry.select}, consumed by {@link createFirestate}, which turns it
+ * into a hook whose `data` is the slice (`TSelected`) and whose params are the
+ * path params (`P`) merged with the selector's own params (`PExtra`).
+ *
+ * The schema/path/options live on `base` — a derived entry never re-declares
+ * them. `PExtra` is `{}` for an un-parameterized selector.
+ */
+interface SelectedDocEntry<T extends FirestoreObject, P extends string, PExtra, TSelected> {
+  readonly __kind: "document-selected";
+  /** Base entry carrying schema/path/options — handed to firestate once. */
+  readonly base: DocEntry<T, P>;
+  /** Projection over the full state; receives the merged params bag at runtime. */
+  readonly selector: (state: DocumentState<T>, params: PExtra) => TSelected;
+  /** Comparator baked in at definition time (see {@link SelectOptions}). */
+  readonly isEqual?: (a: TSelected, b: TSelected) => boolean;
+}
+/**
+ * A {@link ColEntry} narrowed by a `.select(...)` projection. See
+ * {@link SelectedDocEntry}; the selector receives the collection's keyed state.
+ */
+interface SelectedColEntry<T extends FirestoreObject, P extends string, PExtra, TSelected> {
+  readonly __kind: "collection-selected";
+  /** Base entry carrying schema/path/query/options — handed to firestate once. */
+  readonly base: ColEntry<T, P>;
+  /** Projection over the full state; receives the merged params bag at runtime. */
+  readonly selector: (state: CollectionState<T>, params: PExtra) => TSelected;
+  /** Comparator baked in at definition time (see {@link SelectOptions}). */
+  readonly isEqual?: (a: TSelected, b: TSelected) => boolean;
 }
 type FirestateEntry<T extends FirestoreObject = FirestoreObject, P extends string = string> = DocEntry<T, P> | ColEntry<T, P>;
-type FirestateRegistry = Record<string, FirestateEntry<any, any>>;
+/** Any `.select(...)`-derived entry, regardless of its type parameters. */
+type AnySelectedEntry = SelectedDocEntry<any, any, any, any> | SelectedColEntry<any, any, any, any>;
+type FirestateRegistry = Record<string, FirestateEntry<any, any> | AnySelectedEntry>;
 /**
  * Extract `{name}` placeholders from a path template into a params shape.
  *
@@ -696,8 +958,20 @@ type FirestateRegistry = Record<string, FirestateEntry<any, any>>;
 type ParamsOf<P extends string> = string extends P ? Record<string, string> : Prettify<RawParamsOf<P>>;
 type RawParamsOf<P extends string> = P extends `${string}{${infer K}}${infer Rest}` ? { [Key in K]: string } & RawParamsOf<Rest> : {};
 type Prettify<T> = { [K in keyof T]: T[K] } & {};
-type DocOpts<T extends FirestoreObject> = Omit<DocEntry<T>, "__kind" | "__type" | "path">;
-type ColOpts<T extends FirestoreObject> = Omit<ColEntry<T>, "__kind" | "__type" | "path">;
+/**
+ * The `path` accepted by {@link doc} / {@link col}. Either a static template
+ * (whose `{param}` placeholders are interpolated and whose param keys are
+ * inferred via {@link ParamsOf}), or a function that returns the path at
+ * runtime — for paths that branch on a param, e.g. live
+ * `projects/{projectId}/spaces` vs. revision
+ * `projects/{projectId}/revisions/{revisionId}/spaces`.
+ *
+ * With the function form, params can't be inferred from a template, so the
+ * generated hook's params fall back to `Record<string, string>`.
+ */
+type PathArg<P extends string> = P | ((params: Record<string, string>) => string);
+type DocOpts<T extends FirestoreObject> = Omit<DocEntry<T>, "__kind" | "__type" | "path" | "select">;
+type ColOpts<T extends FirestoreObject> = Omit<ColEntry<T>, "__kind" | "__type" | "path" | "select">;
 /**
  * Declare a single-document entry for a Firestate registry.
  *
@@ -711,6 +985,10 @@ type ColOpts<T extends FirestoreObject> = Omit<ColEntry<T>, "__kind" | "__type"
  * directly — that escape hatch keeps the plain-TypeScript form, at the
  * cost of looser param typing on the hook and no runtime validation.
  *
+ * `path` may also be a function returning the full document path at runtime —
+ * for paths that branch on a param. Param keys can't be inferred from a
+ * function, so they fall back to `Record<string, string>`. See {@link PathArg}.
+ *
  * ```ts
  * import { z } from 'zod'
  *
@@ -721,18 +999,43 @@ type ColOpts<T extends FirestoreObject> = Omit<ColEntry<T>, "__kind" | "__type"
  */
 declare function doc<S extends ZodType<FirestoreObject>, const P extends string = string>(opts: Omit<DocOpts<z.infer<S>>, "schema"> & {
   schema: S;
-  path: P;
+  path: PathArg<P>;
 }): DocEntry<z.infer<S>, P>;
 /**
  * Declare a collection entry for a Firestate registry. See {@link doc}
- * for the schema/typing contract.
+ * for the schema/typing contract. `path` may also be a function returning
+ * the collection path at runtime — see {@link PathArg}.
  */
 declare function col<S extends ZodType<FirestoreObject>, const P extends string = string>(opts: Omit<ColOpts<z.infer<S>>, "schema"> & {
   schema: S;
-  path: P;
+  path: PathArg<P>;
 }): ColEntry<z.infer<S>, P>;
 type HookName<K extends string> = `use${Capitalize<K>}`;
-type HookFor<E> = E extends DocEntry<infer T, infer P> ? keyof ParamsOf<P> extends never ? (params?: Record<string, string>, options?: DocHookOptions<T>) => DocumentHandle<T> : (params: ParamsOf<P>, options?: DocHookOptions<T>) => DocumentHandle<T> : E extends ColEntry<infer T, infer P> ? keyof ParamsOf<P> extends never ? (params?: Record<string, string>, options?: ColHookOptions<T>) => CollectionHandle<T> : (params: ParamsOf<P>, options?: ColHookOptions<T>) => CollectionHandle<T> : never;
+type NoSelector = {
+  selector?: undefined;
+  isEqual?: undefined;
+};
+interface DocHookOptionalParams<T extends FirestoreObject> {
+  (params?: Record<string, string>, options?: DocHookOptions<T> & NoSelector): DocumentHandle<T>;
+  <TSelected>(params: Record<string, string> | undefined, options: DocHookOptions<T> & DocumentSelectorOptions<T, TSelected>): SelectedDocumentHandle<T, TSelected>;
+}
+interface DocHookRequiredParams<T extends FirestoreObject, P extends string> {
+  (params: ParamsOf<P>, options?: DocHookOptions<T> & NoSelector): DocumentHandle<T>;
+  <TSelected>(params: ParamsOf<P>, options: DocHookOptions<T> & DocumentSelectorOptions<T, TSelected>): SelectedDocumentHandle<T, TSelected>;
+}
+interface ColHookOptionalParams<T extends FirestoreObject> {
+  (params?: Record<string, string>, options?: ColHookOptions<T> & NoSelector): CollectionHandle<T>;
+  <TSelected>(params: Record<string, string> | undefined, options: ColHookOptions<T> & CollectionSelectorOptions<T, TSelected>): SelectedCollectionHandle<T, TSelected>;
+}
+interface ColHookRequiredParams<T extends FirestoreObject, P extends string> {
+  (params: ParamsOf<P>, options?: ColHookOptions<T> & NoSelector): CollectionHandle<T>;
+  <TSelected>(params: ParamsOf<P>, options: ColHookOptions<T> & CollectionSelectorOptions<T, TSelected>): SelectedCollectionHandle<T, TSelected>;
+}
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type SelectedParams<P extends string, PExtra> = IsAny<PExtra> extends true ? ParamsOf<P> : Prettify<ParamsOf<P> & PExtra>;
+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]> };
 /**
  * Turn a Firestate registry into a map of typed React hooks. Each entry
@@ -747,7 +1050,7 @@ type FirestateApi<R extends FirestateRegistry> = { [K in keyof R & string as Hoo
  */
 declare function createFirestate<R extends FirestateRegistry>(registry: R): FirestateApi<R>;
 //#endregion
-//#region src/diff.d.ts
+//#region src/utils/diff.d.ts
 /**
  * Check if two values are deeply equal
  */
@@ -805,11 +1108,44 @@ declare const isDiffEmpty: (diff: Record<string, unknown>) => boolean;
  * VectorValue) are NOT flattened — they're preserved at their path so
  * Firestore receives them in their original form.
  *
+ * ⚠️ The dot-joined keys this produces are AMBIGUOUS to Firestore if any map
+ * key itself contains a "." (e.g. an email key `a@b.com`): `updateDoc` parses
+ * the "." as a path separator and writes to the wrong nested field. The
+ * write path uses {@link flattenDiffToFieldPaths} + `FieldPath` instead, which
+ * keeps every segment literal. Reach for this only when dotted-string keys are
+ * what you actually want.
+ *
  * @param diff - The nested diff object
  * @param prefix - Internal: current path prefix for recursion
  * @returns Flattened object with dotted keys
  */
 declare const flattenDiff: (diff: Record<string, unknown>, prefix?: string) => Record<string, unknown>;
+/**
+ * Flatten a nested diff into a list of `{ segments, value }` entries, where
+ * `segments` is the path expressed as an array of *literal* key segments
+ * (never joined into a dotted string).
+ *
+ * This is the segment-preserving sibling of {@link flattenDiff}. It exists
+ * because dot-joined string keys are ambiguous to Firestore: `updateDoc(ref,
+ * { "users.a@b.com.role": 4 })` parses the `.` inside the email key as a path
+ * separator and writes to `users → "a@b" → "com" → role` instead of the
+ * literal key `"a@b.com"`. Feeding these segments to `new FieldPath(...segments)`
+ * (with the variadic `updateDoc(ref, fieldPath, value, …)` form) keeps every
+ * segment literal, so a "." inside a map key is never re-interpreted.
+ *
+ * The opaque/plain-object rules mirror {@link flattenDiff} exactly: arrays,
+ * FieldValue sentinels (deleteField, serverTimestamp, …), and Firestore value
+ * types (Timestamp, DocumentReference, GeoPoint, Bytes, VectorValue) ride
+ * through verbatim at their path; only plain objects are recursed into.
+ *
+ * @param diff - The nested diff object
+ * @param prefix - Internal: accumulated path segments for recursion
+ * @returns Flat list of `{ segments, value }` entries
+ */
+declare const flattenDiffToFieldPaths: (diff: Record<string, unknown>, prefix?: string[]) => Array<{
+  segments: string[];
+  value: unknown;
+}>;
 /**
  * Merge two diffs together, with the second taking precedence
  */
@@ -912,7 +1248,29 @@ declare const createDiffAtPath: (path: string, value: unknown) => Record<string,
  */
 declare const unflattenDiff: (flatDiff: Record<string, unknown>) => Record<string, unknown>;
 //#endregion
-//#region src/document.d.ts
+//#region src/utils/shallow.d.ts
+/**
+ * Shallow structural equality.
+ *
+ * Returns `true` when `a` and `b` are identical by `Object.is`, or are two
+ * arrays / two plain objects whose entries are pairwise `Object.is`-equal one
+ * level deep. Anything else (different shapes, nested objects that aren't
+ * reference-equal) is `false`.
+ *
+ * Intended as the `isEqual` for a hook `selector` that builds a fresh array or
+ * object every render — e.g. `data => Object.values(data).map(d => d.id)` or
+ * `data => ({ name: data?.name, done: data?.done })`. The default selector
+ * comparison is a *deep* value compare, which is correct but does more work
+ * than needed for a flat projection; `shallow` re-renders on a genuine change
+ * to any entry while collapsing the fresh-reference-same-entries case.
+ *
+ * Not recursive on purpose: if a selected entry is itself an object you mutate
+ * in place rather than replace, prefer the default deep comparison or a
+ * bespoke `isEqual`.
+ */
+declare const shallow: <T>(a: T, b: T) => boolean;
+//#endregion
+//#region src/core/document.d.ts
 /**
  * Options for creating a document subscription
  */
@@ -965,7 +1323,7 @@ declare const createDocumentSubscription: <TData extends FirestoreObject>(option
   sync: () => Promise<void>;
 };
 //#endregion
-//#region src/collection.d.ts
+//#region src/core/collection.d.ts
 /**
  * Options for creating a collection subscription
  */
@@ -1015,7 +1373,7 @@ declare const createCollectionSubscription: <TData extends FirestoreObject>(opti
   sync: () => Promise<void>;
 };
 //#endregion
-//#region src/provider.d.ts
+//#region src/react/provider.d.ts
 /**
  * Props for FirestateProvider
  */
@@ -1131,5 +1489,5 @@ declare const FirestateStoreProvider: React.FC<FirestateStoreProviderProps>;
  */
 declare const useUnsavedChangesBlocker: () => boolean;
 //#endregion
-export { type ColEntry, type CollectionDefinition, type CollectionHandle, type CollectionOptions, type CollectionState, type DeepPartial, type DocEntry, type DocumentDefinition, type DocumentHandle, type DocumentOptions, 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 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, isDeepEqual, isDiffEmpty, mergeDiffs, 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 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 };
 //# sourceMappingURL=index.d.mts.map