syncorejs 0.2.2 → 0.2.4

package/dist/_vendor/react/index.d.ts

@@ -1,5 +1,4 @@
 import { ReactNode } from "react";
-import * as react_jsx_runtime0 from "react/jsx-runtime";
 import { FunctionArgs, FunctionReference, FunctionResult, PaginationOptions, PaginationResult, SyncoreClient, SyncoreQueryState, SyncoreRuntimeStatus, UsePaginatedQueryResult } from "../core/index.d.mts";
 
 //#region src/index.d.ts
@@ -20,13 +19,46 @@ type PaginatedQueryArgs<TReference extends FunctionReference<"query">> = Functio
 } ? Omit<FunctionArgs<TReference>, "paginationOpts"> : never;
 type PaginatedQueryItem<TReference extends FunctionReference<"query">> = FunctionResult<TReference> extends PaginationResult<infer TItem> ? TItem : never;
 /**
- * Pass `"skip"` as the args argument to `useQuery`, `useQueryState`,
- * `useQueries`, or `usePaginatedQuery` to suppress the subscription entirely.
+ * Pass `skip` as the `args` argument to any Syncore React hook to suppress
+ * that subscription entirely.
+ *
+ * Useful when the query arguments depend on state that is not yet available
+ * (e.g. a selected item ID) — instead of conditionally calling the hook
+ * (which violates the Rules of Hooks), pass `skip` to deactivate it:
+ *
+ * ```tsx
+ * const task = useQuery(api.tasks.get, selectedId ? { id: selectedId } : skip);
+ * // task is `undefined` while selectedId is null/undefined
+ * ```
+ *
+ * Skipped queries return `undefined` for `data`, `"skipped"` for `status`,
+ * and `false` for `isLoading`.
  */
 declare const skip: "skip";
 type Skip = typeof skip;
 /**
- * Provide a Syncore client to React descendants.
+ * Provides a Syncore client to all React descendants via context.
+ *
+ * Wrap your app (or any subtree that uses Syncore hooks) with
+ * `SyncoreProvider`. All `useQuery`, `useMutation`, `useAction`, and
+ * `useQueries` calls inside the tree will automatically use the client you
+ * supply.
+ *
+ * ```tsx
+ * // For a browser worker setup
+ * const client = createBrowserWorkerClient();
+ *
+ * function App() {
+ *   return (
+ *     <SyncoreProvider client={client}>
+ *       <TaskList />
+ *     </SyncoreProvider>
+ *   );
+ * }
+ * ```
+ *
+ * For Next.js apps use `SyncoreNextProvider` which also handles service worker
+ * and worker URL configuration.
  */
 declare function SyncoreProvider({
   client,
@@ -34,37 +66,189 @@ declare function SyncoreProvider({
 }: {
   client: SyncoreClient;
   children: ReactNode;
-}): react_jsx_runtime0.JSX.Element;
+}): import("react/jsx-runtime").JSX.Element;
 /**
- * Read the active Syncore client from React context.
+ * Returns the active `SyncoreClient` from the nearest {@link SyncoreProvider}
+ * in the React tree.
+ *
+ * Throws if called outside of a `SyncoreProvider`. Prefer the higher-level
+ * hooks (`useQuery`, `useMutation`, etc.) for common operations — use
+ * `useSyncore` only when you need direct access to the client object.
+ *
+ * ```ts
+ * const client = useSyncore();
+ * const tasks = await client.query(api.tasks.list);
+ * ```
  */
 declare function useSyncore(): SyncoreClient;
 /**
- * Subscribe to the active Syncore client's runtime lifecycle status.
+ * Subscribe to the runtime’s lifecycle status.
+ *
+ * Returns a SyncoreRuntimeStatus that updates whenever the underlying
+ * runtime changes state (e.g. starting, ready, error). Use it to gate your UI
+ * on the runtime being ready or to display an error boundary:
+ *
+ * ```tsx
+ * function TaskList() {
+ *   const status = useSyncoreStatus();
+ *   if (status.kind === "starting") return <Spinner />;
+ *   if (status.kind === "error")    return <ErrorScreen error={status.error} />;
+ *   return <Tasks />;
+ * }
+ * ```
+ *
+ * Most components do not need this — `useQuery` already incorporates runtime
+ * status into the `SyncoreQueryState.runtimeStatus` field.
  */
 declare function useSyncoreStatus(): SyncoreRuntimeStatus;
 /**
- * Load a reactive Syncore query and return only the data for the common case.
+ * Subscribe to a reactive Syncore query and return the current data.
+ *
+ * The component re-renders automatically whenever the query result changes.
+ * If the query throws, `useQuery` re-throws the error so a React error
+ * boundary can catch it — use {@link useQueryState} if you need to handle
+ * errors inline.
+ *
+ * ```tsx
+ * // Basic usage
+ * const tasks = useQuery(api.tasks.list);
+ *
+ * // With arguments
+ * const task = useQuery(api.tasks.get, { id: taskId });
+ *
+ * // Conditionally skip when arguments are not yet available
+ * const task = useQuery(api.tasks.get, taskId ? { id: taskId } : skip);
+ * ```
+ *
+ * @param reference - A typed function reference (from the generated `api` object).
+ * @param args      - The query’s arguments, or `skip` to suppress the subscription.
+ * @returns The current query result, or `undefined` while loading.
  */
 declare function useQuery<TArgs, TResult>(reference: FunctionReference<"query", TArgs, TResult>, ...args: OptionalArgsTuple<TArgs> | [Skip]): TResult | undefined;
 /**
- * Load a reactive Syncore query and keep the full local state.
+ * Subscribe to a reactive Syncore query and return the full
+ * SyncoreQueryState including loading, error, and runtime status.
+ *
+ * Use this instead of {@link useQuery} when you need to:
+ * - Differentiate between `undefined` data and an error.
+ * - React to `isLoading` / `isError` without relying on error boundaries.
+ * - Inspect `runtimeStatus` for the underlying runtime’s health.
+ *
+ * ```tsx
+ * const { data, isLoading, isError, error } = useQueryState(api.tasks.list);
+ *
+ * if (isLoading) return <Spinner />;
+ * if (isError)   return <ErrorBanner message={error.message} />;
+ * return <TaskList tasks={data} />;
+ * ```
  */
 declare function useQueryState<TArgs, TResult>(reference: FunctionReference<"query", TArgs, TResult>, ...args: OptionalArgsTuple<TArgs> | [Skip]): SyncoreQueryState<TResult>;
 /**
- * Construct a stable function that executes a Syncore mutation.
+ * Returns a stable callback for executing a Syncore mutation.
+ *
+ * The returned function is type-safe: its parameter types are inferred from
+ * the mutation definition and remain stable across re-renders (no need to
+ * wrap in `useCallback`).
+ *
+ * ```tsx
+ * const createTask = useMutation(api.tasks.create);
+ *
+ * return (
+ *   <button onClick={() => createTask({ title: "New task" })}>
+ *     Add task
+ *   </button>
+ * );
+ * ```
+ *
+ * @param reference - A typed mutation reference from the generated `api` object.
+ * @returns A function that, when called, executes the mutation and returns a
+ *   promise that resolves to the mutation’s return value.
  */
 declare function useMutation<TArgs, TResult>(reference: FunctionReference<"mutation", TArgs, TResult>): (...args: OptionalArgsTuple<TArgs>) => Promise<TResult>;
 /**
- * Construct a stable function that executes a Syncore action.
+ * Returns a stable callback for executing a Syncore action.
+ *
+ * Identical to {@link useMutation} but for actions. Use this when the work you
+ * need to do cannot run inside a transaction (external API calls, long-running
+ * tasks, etc.).
+ *
+ * ```tsx
+ * const importTasks = useAction(api.tasks.importFromCsv);
+ *
+ * return (
+ *   <button onClick={() => importTasks({ url: csvUrl })}>
+ *     Import
+ *   </button>
+ * );
+ * ```
+ *
+ * @param reference - A typed action reference from the generated `api` object.
+ * @returns A function that, when called, executes the action and returns a
+ *   promise that resolves to the action’s return value.
  */
 declare function useAction<TArgs, TResult>(reference: FunctionReference<"action", TArgs, TResult>): (...args: OptionalArgsTuple<TArgs>) => Promise<TResult>;
 /**
- * Load a keyed set of Syncore queries at once with per-entry state.
+ * Subscribe to multiple Syncore queries simultaneously and receive per-entry
+ * state objects in a single hook call.
+ *
+ * More efficient than calling `useQuery` in a loop when the set of queries is
+ * known at component render time. The hook maintains only one subscription per
+ * unique `(reference, args)` combination even if entries are duplicated.
+ *
+ * ```tsx
+ * const { header, sidebar } = useQueries({
+ *   header:  { query: api.layout.header },
+ *   sidebar: { query: api.layout.sidebar, args: { userId } },
+ * });
+ *
+ * if (header.isLoading || sidebar.isLoading) return <Spinner />;
+ * ```
+ *
+ * @param entries - A record of named query requests. Each entry can include
+ *   `args: skip` to suppress that specific subscription.
+ * @returns A record with the same keys, each holding a SyncoreQueryState.
  */
 declare function useQueries<TEntries extends QueriesRequestInput>(entries: TEntries): UseQueriesResult<TEntries>;
 /**
- * Load a paginated Syncore query as a growing reactive list.
+ * Subscribe to a paginated Syncore query, incrementally loading more pages.
+ *
+ * The query must accept a `paginationOpts` argument and return a
+ * `PaginationResult`. The hook manages cursors automatically — call the
+ * returned `loadMore` function to append the next page to the results.
+ *
+ * ```tsx
+ * const { results, status, loadMore, hasMore } = usePaginatedQuery(
+ *   api.tasks.list,
+ *   { projectId },
+ *   { initialNumItems: 20 },
+ * );
+ *
+ * return (
+ *   <>
+ *     {results.map((t) => <TaskRow key={t._id} task={t} />)}
+ *     {hasMore && (
+ *       <button
+ *         onClick={() => loadMore(20)}
+ *         disabled={status === "loadingMore"}
+ *       >
+ *         Load more
+ *       </button>
+ *     )}
+ *   </>
+ * );
+ * ```
+ *
+ * Pass `skip` as `args` to suppress the subscription until arguments are
+ * ready.
+ *
+ * @param reference          - A typed query reference whose handler calls
+ *   `ctx.db.query(…).paginate(paginationOpts)`.
+ * @param args               - Arguments for the query (excluding
+ *   `paginationOpts`, which is managed internally), or `skip`.
+ * @param options - Pagination options. `initialNumItems` controls the number
+ *   of items to load on the first page.
+ * @returns A UsePaginatedQueryResult with the accumulated results and
+ *   a `loadMore` callback.
  */
 declare function usePaginatedQuery<TReference extends PaginatedQueryReference>(reference: TReference, args: PaginatedQueryArgs<TReference> | Skip, options: {
   initialNumItems: number;

package/dist/_vendor/react/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.tsx"],"mappings":";;;;;KA0BK,iBAAA,UACH,MAAA,uBAA6B,KAAA,IAAS,IAAA,GAAO,KAAA,KAAU,IAAA,EAAM,KAAA;AAAA,KAE1D,iBAAA,oBACgB,iBAAA,YAA6B,iBAAA,aAC9C,MAAA,uBAA6B,YAAA,CAAa,UAAA;EAExC,KAAA,EAAO,UAAA;EACP,IAAA,GAAO,YAAA,CAAa,UAAA,IAAc,IAAA;AAAA;EAGlC,KAAA,EAAO,UAAA;EACP,IAAA,EAAM,YAAA,CAAa,UAAA,IAAc,IAAA;AAAA;AAAA,KAGlC,mBAAA,GAAsB,MAAA,SAAe,iBAAA;AAAA,KAErC,kBAAA,WAA6B,MAAA,SAAe,iBAAA,qBAG7C,iBAAA,CAAkB,cAAA,CAAe,UAAA;AAAA,KAGzB,gBAAA,kBAAkC,mBAAA,qBAC7B,QAAA,GAAW,kBAAA,CAAmB,QAAA,CAAS,IAAA;AAAA,KAGnD,uBAAA,GAA0B,iBAAA,UAE7B,MAAA,mBACA,gBAAA;AAAA,KAGG,kBAAA,oBAAsC,iBAAA,aACzC,YAAA,CAAa,UAAA;EAAsB,cAAA,EAAgB,iBAAA;AAAA,IAC/C,IAAA,CAAK,YAAA,CAAa,UAAA;AAAA,KAGnB,kBAAA,oBAAsC,iBAAA,aACzC,cAAA,CAAe,UAAA,UAAoB,gBAAA,gBAC/B,KAAA;;;;AAvC8D;cA2EvD,IAAA;AAAA,KACR,IAAA,UAAc,IAAA;;;;iBAYH,eAAA,CAAA;EACd,MAAA;EACA;AAAA;EAEA,MAAA,EAAQ,aAAA;EACR,QAAA,EAAU,SAAA;AAAA,IACX,kBAAA,CAAA,GAAA,CAAA,OAAA;;;;iBASe,UAAA,CAAA,GAAc,aAAA;;;;iBAWd,gBAAA,CAAA,GAAoB,oBAAA;;;;iBA+BpB,QAAA,gBAAA,CACd,SAAA,EAAW,iBAAA,UAA2B,KAAA,EAAO,OAAA,MAC1C,IAAA,EAAM,iBAAA,CAAkB,KAAA,KAAU,IAAA,IACpC,OAAA;;;;iBAWa,aAAA,gBAAA,CACd,SAAA,EAAW,iBAAA,UAA2B,KAAA,EAAO,OAAA,MAC1C,IAAA,EAAM,iBAAA,CAAkB,KAAA,KAAU,IAAA,IACpC,iBAAA,CAAkB,OAAA;;;;iBAkCL,WAAA,gBAAA,CACd,SAAA,EAAW,iBAAA,aAA8B,KAAA,EAAO,OAAA,QAC3C,IAAA,EAAM,iBAAA,CAAkB,KAAA,MAAW,OAAA,CAAQ,OAAA;;;;iBAQlC,SAAA,gBAAA,CACd,SAAA,EAAW,iBAAA,WAA4B,KAAA,EAAO,OAAA,QACzC,IAAA,EAAM,iBAAA,CAAkB,KAAA,MAAW,OAAA,CAAQ,OAAA;;;;iBAQlC,UAAA,kBAA4B,mBAAA,CAAA,CAC1C,OAAA,EAAS,QAAA,GACR,gBAAA,CAAiB,QAAA;AA/MuB;;;AAAA,iBAuQ3B,iBAAA,oBAAqC,uBAAA,CAAA,CACnD,SAAA,EAAW,UAAA,EACX,IAAA,EAAM,kBAAA,CAAmB,UAAA,IAAc,IAAA,EACvC,OAAA;EACE,eAAA;AAAA,IAED,uBAAA,CAAwB,kBAAA,CAAmB,UAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.tsx"],"mappings":";;;;KA0BK,iBAAA,UACH,MAAA,uBAA6B,KAAA,IAAS,IAAA,GAAO,KAAA,KAAU,IAAA,EAAM,KAAA;AAAA,KAE1D,iBAAA,oBACgB,iBAAA,YAA6B,iBAAA,aAC9C,MAAA,uBAA6B,YAAA,CAAa,UAAA;EAExC,KAAA,EAAO,UAAA;EACP,IAAA,GAAO,YAAA,CAAa,UAAA,IAAc,IAAA;AAAA;EAGlC,KAAA,EAAO,UAAA;EACP,IAAA,EAAM,YAAA,CAAa,UAAA,IAAc,IAAA;AAAA;AAAA,KAGlC,mBAAA,GAAsB,MAAM,SAAS,iBAAA;AAAA,KAErC,kBAAA,WAA6B,MAAA,SAAe,iBAAA,qBAG7C,iBAAA,CAAkB,cAAA,CAAe,UAAA;AAAA,KAGzB,gBAAA,kBAAkC,mBAAA,qBAC7B,QAAA,GAAW,kBAAA,CAAmB,QAAA,CAAS,IAAA;AAAA,KAGnD,uBAAA,GAA0B,iBAAA,UAE7B,MAAA,mBACA,gBAAA;AAAA,KAGG,kBAAA,oBAAsC,iBAAA,aACzC,YAAA,CAAa,UAAA;EAAsB,cAAA,EAAgB,iBAAA;AAAA,IAC/C,IAAA,CAAK,YAAA,CAAa,UAAA;AAAA,KAGnB,kBAAA,oBAAsC,iBAAA,aACzC,cAAA,CAAe,UAAA,UAAoB,gBAAA,gBAC/B,KAAA;;AAvC8D;AAAA;;;;;;;;;;;;;;cAuFvD,IAAA;AAAA,KACR,IAAA,UAAc,IAAI;;;;;;;;;;;;;;;;;;;;;;AA7EoB;AAAA;;iBA8G3B,eAAA,CAAA;EACd,MAAA;EACA;AAAA;EAEA,MAAA,EAAQ,aAAA;EACR,QAAA,EAAU,SAAA;AAAA,gCACX,GAAA,CAAA,OAAA;;;;;;;;;;;;;;iBAmBe,UAAA,CAAA,GAAc,aAAa;;;;AA/HI;AAG/C;;;;;;;;;;;;;;;iBAuJgB,gBAAA,CAAA,GAAoB,oBAAoB;;;AAtJI;AAC1D;;;;;;;;;;;;AAKgB;AAAA;;;;;;;iBAmMF,QAAA,gBAAA,CACd,SAAA,EAAW,iBAAA,UAA2B,KAAA,EAAO,OAAA,MAC1C,IAAA,EAAM,iBAAA,CAAkB,KAAA,KAAU,IAAA,IACpC,OAAA;;;;;;;;;;;;;;;AAjM+B;AAAA;;iBA0NlB,aAAA,gBAAA,CACd,SAAA,EAAW,iBAAA,UAA2B,KAAA,EAAO,OAAA,MAC1C,IAAA,EAAM,iBAAA,CAAkB,KAAA,KAAU,IAAA,IACpC,iBAAA,CAAkB,OAAA;;;;;;;;;;;;;;;AAxNV;AAgDX;;;;AAAmC;AAAC;iBA4NpB,WAAA,gBAAA,CACd,SAAA,EAAW,iBAAA,aAA8B,KAAA,EAAO,OAAA,QAC3C,IAAA,EAAM,iBAAA,CAAkB,KAAA,MAAW,OAAA,CAAQ,OAAA;;;AA7N3B;AAiCvB;;;;;;;;;;;;;;;;;;iBAsNgB,SAAA,gBAAA,CACd,SAAA,EAAW,iBAAA,WAA4B,KAAA,EAAO,OAAA,QACzC,IAAA,EAAM,iBAAA,CAAkB,KAAA,MAAW,OAAA,CAAQ,OAAA;;AAlNjD;AAmBD;;;;AAA2C;AA2B3C;;;;AAAwD;AAmDxD;;;;;;;;;iBA2IgB,UAAA,kBAA4B,mBAAA,CAAA,CAC1C,OAAA,EAAS,QAAA,GACR,gBAAA,CAAiB,QAAA;;;;;;;;;;;;;;;AA1IV;AAyBV;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+MgB,iBAAA,oBAAqC,uBAAA,CAAA,CACnD,SAAA,EAAW,UAAA,EACX,IAAA,EAAM,kBAAA,CAAmB,UAAA,IAAc,IAAA,EACvC,OAAA;EACE,eAAA;AAAA,IAED,uBAAA,CAAwB,kBAAA,CAAmB,UAAA"}

package/dist/_vendor/react/index.js

@@ -2,8 +2,20 @@ import { createContext, useContext, useEffect, useMemo, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/index.tsx
 /**
-* Pass `"skip"` as the args argument to `useQuery`, `useQueryState`,
-* `useQueries`, or `usePaginatedQuery` to suppress the subscription entirely.
+* Pass `skip` as the `args` argument to any Syncore React hook to suppress
+* that subscription entirely.
+*
+* Useful when the query arguments depend on state that is not yet available
+* (e.g. a selected item ID) — instead of conditionally calling the hook
+* (which violates the Rules of Hooks), pass `skip` to deactivate it:
+*
+* ```tsx
+* const task = useQuery(api.tasks.get, selectedId ? { id: selectedId } : skip);
+* // task is `undefined` while selectedId is null/undefined
+* ```
+*
+* Skipped queries return `undefined` for `data`, `"skipped"` for `status`,
+* and `false` for `isLoading`.
 */
 const skip = "skip";
 const defaultRuntimeStatus = {
@@ -12,7 +24,28 @@ const defaultRuntimeStatus = {
 };
 const SyncoreContext = createContext(null);
 /**
-* Provide a Syncore client to React descendants.
+* Provides a Syncore client to all React descendants via context.
+*
+* Wrap your app (or any subtree that uses Syncore hooks) with
+* `SyncoreProvider`. All `useQuery`, `useMutation`, `useAction`, and
+* `useQueries` calls inside the tree will automatically use the client you
+* supply.
+*
+* ```tsx
+* // For a browser worker setup
+* const client = createBrowserWorkerClient();
+*
+* function App() {
+*   return (
+*     <SyncoreProvider client={client}>
+*       <TaskList />
+*     </SyncoreProvider>
+*   );
+* }
+* ```
+*
+* For Next.js apps use `SyncoreNextProvider` which also handles service worker
+* and worker URL configuration.
 */
 function SyncoreProvider({ client, children }) {
 	return /* @__PURE__ */ jsx(SyncoreContext.Provider, {
@@ -21,7 +54,17 @@ function SyncoreProvider({ client, children }) {
 	});
 }
 /**
-* Read the active Syncore client from React context.
+* Returns the active `SyncoreClient` from the nearest {@link SyncoreProvider}
+* in the React tree.
+*
+* Throws if called outside of a `SyncoreProvider`. Prefer the higher-level
+* hooks (`useQuery`, `useMutation`, etc.) for common operations — use
+* `useSyncore` only when you need direct access to the client object.
+*
+* ```ts
+* const client = useSyncore();
+* const tasks = await client.query(api.tasks.list);
+* ```
 */
 function useSyncore() {
 	const client = useContext(SyncoreContext);
@@ -29,7 +72,23 @@ function useSyncore() {
 	return client;
 }
 /**
-* Subscribe to the active Syncore client's runtime lifecycle status.
+* Subscribe to the runtime’s lifecycle status.
+*
+* Returns a SyncoreRuntimeStatus that updates whenever the underlying
+* runtime changes state (e.g. starting, ready, error). Use it to gate your UI
+* on the runtime being ready or to display an error boundary:
+*
+* ```tsx
+* function TaskList() {
+*   const status = useSyncoreStatus();
+*   if (status.kind === "starting") return <Spinner />;
+*   if (status.kind === "error")    return <ErrorScreen error={status.error} />;
+*   return <Tasks />;
+* }
+* ```
+*
+* Most components do not need this — `useQuery` already incorporates runtime
+* status into the `SyncoreQueryState.runtimeStatus` field.
 */
 function useSyncoreStatus() {
 	const client = useSyncore();
@@ -48,7 +107,27 @@ function useSyncoreStatus() {
 	return status;
 }
 /**
-* Load a reactive Syncore query and return only the data for the common case.
+* Subscribe to a reactive Syncore query and return the current data.
+*
+* The component re-renders automatically whenever the query result changes.
+* If the query throws, `useQuery` re-throws the error so a React error
+* boundary can catch it — use {@link useQueryState} if you need to handle
+* errors inline.
+*
+* ```tsx
+* // Basic usage
+* const tasks = useQuery(api.tasks.list);
+*
+* // With arguments
+* const task = useQuery(api.tasks.get, { id: taskId });
+*
+* // Conditionally skip when arguments are not yet available
+* const task = useQuery(api.tasks.get, taskId ? { id: taskId } : skip);
+* ```
+*
+* @param reference - A typed function reference (from the generated `api` object).
+* @param args      - The query’s arguments, or `skip` to suppress the subscription.
+* @returns The current query result, or `undefined` while loading.
 */
 function useQuery(reference, ...args) {
 	const state = useQueryState(reference, ...args);
@@ -56,7 +135,21 @@ function useQuery(reference, ...args) {
 	return state.data;
 }
 /**
-* Load a reactive Syncore query and keep the full local state.
+* Subscribe to a reactive Syncore query and return the full
+* SyncoreQueryState including loading, error, and runtime status.
+*
+* Use this instead of {@link useQuery} when you need to:
+* - Differentiate between `undefined` data and an error.
+* - React to `isLoading` / `isError` without relying on error boundaries.
+* - Inspect `runtimeStatus` for the underlying runtime’s health.
+*
+* ```tsx
+* const { data, isLoading, isError, error } = useQueryState(api.tasks.list);
+*
+* if (isLoading) return <Spinner />;
+* if (isError)   return <ErrorBanner message={error.message} />;
+* return <TaskList tasks={data} />;
+* ```
 */
 function useQueryState(reference, ...args) {
 	const isSkipped = args[0] === skip;
@@ -78,21 +171,75 @@ function useQueryState(reference, ...args) {
 	return toQueryState(snapshot, runtimeStatus, isSkipped);
 }
 /**
-* Construct a stable function that executes a Syncore mutation.
+* Returns a stable callback for executing a Syncore mutation.
+*
+* The returned function is type-safe: its parameter types are inferred from
+* the mutation definition and remain stable across re-renders (no need to
+* wrap in `useCallback`).
+*
+* ```tsx
+* const createTask = useMutation(api.tasks.create);
+*
+* return (
+*   <button onClick={() => createTask({ title: "New task" })}>
+*     Add task
+*   </button>
+* );
+* ```
+*
+* @param reference - A typed mutation reference from the generated `api` object.
+* @returns A function that, when called, executes the mutation and returns a
+*   promise that resolves to the mutation’s return value.
 */
 function useMutation(reference) {
 	const client = useSyncore();
 	return (...args) => client.mutation(reference, normalizeOptionalArgs(args));
 }
 /**
-* Construct a stable function that executes a Syncore action.
+* Returns a stable callback for executing a Syncore action.
+*
+* Identical to {@link useMutation} but for actions. Use this when the work you
+* need to do cannot run inside a transaction (external API calls, long-running
+* tasks, etc.).
+*
+* ```tsx
+* const importTasks = useAction(api.tasks.importFromCsv);
+*
+* return (
+*   <button onClick={() => importTasks({ url: csvUrl })}>
+*     Import
+*   </button>
+* );
+* ```
+*
+* @param reference - A typed action reference from the generated `api` object.
+* @returns A function that, when called, executes the action and returns a
+*   promise that resolves to the action’s return value.
 */
 function useAction(reference) {
 	const client = useSyncore();
 	return (...args) => client.action(reference, normalizeOptionalArgs(args));
 }
 /**
-* Load a keyed set of Syncore queries at once with per-entry state.
+* Subscribe to multiple Syncore queries simultaneously and receive per-entry
+* state objects in a single hook call.
+*
+* More efficient than calling `useQuery` in a loop when the set of queries is
+* known at component render time. The hook maintains only one subscription per
+* unique `(reference, args)` combination even if entries are duplicated.
+*
+* ```tsx
+* const { header, sidebar } = useQueries({
+*   header:  { query: api.layout.header },
+*   sidebar: { query: api.layout.sidebar, args: { userId } },
+* });
+*
+* if (header.isLoading || sidebar.isLoading) return <Spinner />;
+* ```
+*
+* @param entries - A record of named query requests. Each entry can include
+*   `args: skip` to suppress that specific subscription.
+* @returns A record with the same keys, each holding a SyncoreQueryState.
 */
 function useQueries(entries) {
 	const client = useSyncore();
@@ -125,7 +272,45 @@ function useQueries(entries) {
 	]);
 }
 /**
-* Load a paginated Syncore query as a growing reactive list.
+* Subscribe to a paginated Syncore query, incrementally loading more pages.
+*
+* The query must accept a `paginationOpts` argument and return a
+* `PaginationResult`. The hook manages cursors automatically — call the
+* returned `loadMore` function to append the next page to the results.
+*
+* ```tsx
+* const { results, status, loadMore, hasMore } = usePaginatedQuery(
+*   api.tasks.list,
+*   { projectId },
+*   { initialNumItems: 20 },
+* );
+*
+* return (
+*   <>
+*     {results.map((t) => <TaskRow key={t._id} task={t} />)}
+*     {hasMore && (
+*       <button
+*         onClick={() => loadMore(20)}
+*         disabled={status === "loadingMore"}
+*       >
+*         Load more
+*       </button>
+*     )}
+*   </>
+* );
+* ```
+*
+* Pass `skip` as `args` to suppress the subscription until arguments are
+* ready.
+*
+* @param reference          - A typed query reference whose handler calls
+*   `ctx.db.query(…).paginate(paginationOpts)`.
+* @param args               - Arguments for the query (excluding
+*   `paginationOpts`, which is managed internally), or `skip`.
+* @param options - Pagination options. `initialNumItems` controls the number
+*   of items to load on the first page.
+* @returns A UsePaginatedQueryResult with the accumulated results and
+*   a `loadMore` callback.
 */
 function usePaginatedQuery(reference, args, options) {
 	if (typeof options.initialNumItems !== "number" || options.initialNumItems <= 0) throw new Error(`options.initialNumItems must be a positive number. Received ${String(options.initialNumItems)}.`);
@@ -238,16 +423,23 @@ const noOpWatch = {
 };
 function useManagedQueryWatch(client, reference, args, isSkipped = false) {
 	const argsKey = isSkipped ? skip : stableStringify(args ?? {});
-	const normalizedArgs = useMemo(() => isSkipped ? void 0 : JSON.parse(argsKey), [argsKey, isSkipped]);
-	const watch = useMemo(() => isSkipped ? noOpWatch : client.watchQuery(reference, normalizedArgs), [
+	const [watch, setWatch] = useState(() => noOpWatch);
+	useEffect(() => {
+		if (isSkipped) {
+			setWatch(noOpWatch);
+			return;
+		}
+		const nextWatch = client.watchQuery(reference, JSON.parse(argsKey));
+		setWatch(nextWatch);
+		return () => {
+			nextWatch.dispose?.();
+		};
+	}, [
+		argsKey,
 		client,
 		isSkipped,
-		normalizedArgs,
 		reference
 	]);
-	useEffect(() => () => {
-		if (!isSkipped) watch.dispose?.();
-	}, [isSkipped, watch]);
 	return watch;
 }
 function normalizeOptionalArgs(args) {