syncorejs 0.2.2 → 0.2.3

package/dist/_vendor/platform-web/worker.js

@@ -1,14 +1,30 @@
 import { SyncoreBridgeClient, attachRuntimeBridge } from "../core/index.mjs";
 //#region src/worker.ts
+/**
+* Syncore client that communicates with a runtime running in a browser Worker
+* over the `postMessage` bridge.
+*
+* Use `createSyncoreWebWorkerClient()` or `createManagedWebWorkerClient()` to
+* create instances. Prefer the React hooks (`useQuery`, `useMutation`, etc.)
+* over calling this directly in React apps.
+*/
 var SyncoreWebWorkerClient = class extends SyncoreBridgeClient {};
 /**
-* Create a web worker Syncore client from a low-level message endpoint.
+* Create a {@link SyncoreWebWorkerClient} from a low-level message endpoint.
+*
+* Use this when you already have a `Worker` or `MessagePort` reference and
+* want to wrap it manually. For the common case of spawning a new Worker from
+* a URL, use `createSyncoreWebWorkerClient` instead.
 */
 function createWebWorkerClient(endpoint) {
 	return new SyncoreWebWorkerClient(endpoint);
 }
 /**
-* Create and manage both a browser Worker and the Syncore client that talks to it.
+* Create a {@link ManagedWebWorkerClient} using a provided Worker factory.
+*
+* Useful when you need control over how the Worker is constructed (e.g. to
+* pass constructor options not exposed by `CreateWebWorkerClientProviderOptions`).
+* For the common URL-based case, use `createSyncoreWebWorkerClient`.
 */
 function createManagedWebWorkerClient(options) {
 	const worker = options.createWorker();
@@ -23,7 +39,21 @@ function createManagedWebWorkerClient(options) {
 	};
 }
 /**
-* Create a worker-backed Syncore client using the standard Worker constructor.
+* Create a {@link ManagedWebWorkerClient} by spawning a new Worker from a URL.
+*
+* This is the standard way to create a main-thread client in a browser app.
+* Pass the URL of your `syncore.worker.ts` file (which calls
+* `createWebWorkerRuntime`) and connect the returned `client` to your React
+* `SyncoreProvider` or Svelte context.
+*
+* ```ts
+* // main.ts (or React root)
+* import { createSyncoreWebWorkerClient } from "syncorejs/browser";
+*
+* const { client, dispose } = createSyncoreWebWorkerClient({
+*   workerUrl: new URL("./syncore.worker.ts", import.meta.url),
+* });
+* ```
 */
 function createSyncoreWebWorkerClient(options) {
 	return createManagedWebWorkerClient({ createWorker: () => new Worker(options.workerUrl, {
@@ -32,7 +62,10 @@ function createSyncoreWebWorkerClient(options) {
 	}) });
 }
 /**
-* Attach a Syncore runtime implementation to a worker message endpoint.
+* Wire a Syncore runtime factory to a worker message endpoint.
+*
+* Called internally by `createWebWorkerRuntime`. Exposed for cases where you
+* need to attach a runtime to a custom bridge endpoint (e.g. a `MessagePort`).
 */
 function attachWebWorkerRuntime(options) {
 	return attachRuntimeBridge(options);

package/dist/_vendor/platform-web/worker.js.map

@@ -1 +1 @@
-{"version":3,"file":"worker.js","names":[],"sources":["../src/worker.ts"],"sourcesContent":["import {\n  attachRuntimeBridge,\n  type AttachRuntimeBridgeOptions,\n  type AttachedRuntimeBridge,\n  type BridgeQueryWatch,\n  SyncoreBridgeClient,\n  type SyncoreDataModel,\n  type SyncoreBridgeMessageEndpoint,\n} from \"@syncore/core\";\n\nexport type WebWorkerSyncoreSchema<\n  TSchema extends SyncoreDataModel = SyncoreDataModel\n> = TSchema;\nexport type SyncoreWorkerMessageEndpoint = SyncoreBridgeMessageEndpoint;\nexport type WorkerQueryWatch<TValue> = BridgeQueryWatch<TValue>;\n\nexport class SyncoreWebWorkerClient extends SyncoreBridgeClient {\n  declare query: SyncoreBridgeClient[\"query\"];\n  declare mutation: SyncoreBridgeClient[\"mutation\"];\n  declare action: SyncoreBridgeClient[\"action\"];\n  declare watchQuery: SyncoreBridgeClient[\"watchQuery\"];\n}\n\nexport type AttachWebWorkerRuntimeOptions<\n  TSchema extends WebWorkerSyncoreSchema = WebWorkerSyncoreSchema\n> = AttachRuntimeBridgeOptions<TSchema>;\nexport type AttachedWebWorkerRuntime = AttachedRuntimeBridge;\n\n/**\n * A worker-backed browser client plus the Worker instance it owns.\n */\nexport interface ManagedWebWorkerClient {\n  client: SyncoreWebWorkerClient;\n  worker: Worker;\n  dispose(): void;\n}\n\n/**\n * Options for creating a worker-backed Syncore client in the browser.\n */\nexport interface CreateWebWorkerClientProviderOptions {\n  /** The worker module URL passed to `new Worker(...)`. */\n  workerUrl: URL | string;\n\n  /** Optional worker type, defaults to `module`. */\n  workerType?: WorkerOptions[\"type\"];\n\n  /** Optional name shown in browser devtools. */\n  workerName?: string;\n}\n\n/**\n * Create a web worker Syncore client from a low-level message endpoint.\n */\nexport function createWebWorkerClient(\n  endpoint: SyncoreWorkerMessageEndpoint\n): SyncoreWebWorkerClient {\n  return new SyncoreWebWorkerClient(endpoint);\n}\n\n/**\n * Create and manage both a browser Worker and the Syncore client that talks to it.\n */\nexport function createManagedWebWorkerClient(options: {\n  createWorker: () => Worker;\n}): ManagedWebWorkerClient {\n  const worker = options.createWorker();\n  const client = createWebWorkerClient(worker);\n  return {\n    client,\n    worker,\n    dispose() {\n      client.dispose();\n      worker.terminate();\n    }\n  };\n}\n\n/**\n * Create a worker-backed Syncore client using the standard Worker constructor.\n */\nexport function createSyncoreWebWorkerClient(\n  options: CreateWebWorkerClientProviderOptions\n): ManagedWebWorkerClient {\n  return createManagedWebWorkerClient({\n    createWorker: () =>\n      new Worker(options.workerUrl, {\n        type: options.workerType ?? \"module\",\n        ...(options.workerName ? { name: options.workerName } : {})\n      })\n  });\n}\n\n/**\n * Attach a Syncore runtime implementation to a worker message endpoint.\n */\nexport function attachWebWorkerRuntime(\n  options: AttachWebWorkerRuntimeOptions\n): AttachedWebWorkerRuntime {\n  return attachRuntimeBridge(options);\n}\n"],"mappings":";;AAgBA,IAAa,yBAAb,cAA4C,oBAAoB;;;;AAsChE,SAAgB,sBACd,UACwB;AACxB,QAAO,IAAI,uBAAuB,SAAS;;;;;AAM7C,SAAgB,6BAA6B,SAElB;CACzB,MAAM,SAAS,QAAQ,cAAc;CACrC,MAAM,SAAS,sBAAsB,OAAO;AAC5C,QAAO;EACL;EACA;EACA,UAAU;AACR,UAAO,SAAS;AAChB,UAAO,WAAW;;EAErB;;;;;AAMH,SAAgB,6BACd,SACwB;AACxB,QAAO,6BAA6B,EAClC,oBACE,IAAI,OAAO,QAAQ,WAAW;EAC5B,MAAM,QAAQ,cAAc;EAC5B,GAAI,QAAQ,aAAa,EAAE,MAAM,QAAQ,YAAY,GAAG,EAAE;EAC3D,CAAC,EACL,CAAC;;;;;AAMJ,SAAgB,uBACd,SAC0B;AAC1B,QAAO,oBAAoB,QAAQ"}
+{"version":3,"file":"worker.js","names":[],"sources":["../src/worker.ts"],"sourcesContent":["import {\n  attachRuntimeBridge,\n  type AttachRuntimeBridgeOptions,\n  type AttachedRuntimeBridge,\n  type BridgeQueryWatch,\n  SyncoreBridgeClient,\n  type SyncoreDataModel,\n  type SyncoreBridgeMessageEndpoint,\n} from \"@syncore/core\";\n\n/**\n * Schema type constraint for worker-side Syncore runtimes.\n *\n * Pass any schema produced by `defineSchema()` where this type is expected.\n * Defaults to the unconstrained `SyncoreDataModel` when omitted.\n */\nexport type WebWorkerSyncoreSchema<\n  TSchema extends SyncoreDataModel = SyncoreDataModel\n> = TSchema;\n/** Message endpoint shape required by the browser worker bridge (alias of `SyncoreBridgeMessageEndpoint`). */\nexport type SyncoreWorkerMessageEndpoint = SyncoreBridgeMessageEndpoint;\n/** Live-query subscription handle returned by `SyncoreWebWorkerClient.watchQuery`. */\nexport type WorkerQueryWatch<TValue> = BridgeQueryWatch<TValue>;\n\n/**\n * Syncore client that communicates with a runtime running in a browser Worker\n * over the `postMessage` bridge.\n *\n * Use `createSyncoreWebWorkerClient()` or `createManagedWebWorkerClient()` to\n * create instances. Prefer the React hooks (`useQuery`, `useMutation`, etc.)\n * over calling this directly in React apps.\n */\nexport class SyncoreWebWorkerClient extends SyncoreBridgeClient {\n  declare query: SyncoreBridgeClient[\"query\"];\n  declare mutation: SyncoreBridgeClient[\"mutation\"];\n  declare action: SyncoreBridgeClient[\"action\"];\n  declare watchQuery: SyncoreBridgeClient[\"watchQuery\"];\n}\n\n/** Options for attaching a runtime to a worker bridge endpoint. Alias of `AttachRuntimeBridgeOptions`. */\nexport type AttachWebWorkerRuntimeOptions<\n  TSchema extends WebWorkerSyncoreSchema = WebWorkerSyncoreSchema\n> = AttachRuntimeBridgeOptions<TSchema>;\n/** Handle returned by `attachWebWorkerRuntime` for controlling the attached bridge. */\nexport type AttachedWebWorkerRuntime = AttachedRuntimeBridge;\n\n/**\n * A browser Worker and its associated Syncore client, bundled for easy\n * lifecycle management.\n *\n * Returned by `createSyncoreWebWorkerClient` and `createManagedWebWorkerClient`.\n * Call `dispose()` to terminate the worker and release its resources.\n */\nexport interface ManagedWebWorkerClient {\n  /** The Syncore client connected to the worker. */\n  client: SyncoreWebWorkerClient;\n  /** The underlying `Worker` instance. Useful for low-level control. */\n  worker: Worker;\n  /** Terminate the worker and dispose the client. Call on app unmount or navigation. */\n  dispose(): void;\n}\n\n/**\n * Options for creating a managed worker Syncore client via\n * `createSyncoreWebWorkerClient`.\n */\nexport interface CreateWebWorkerClientProviderOptions {\n  /** The worker module URL passed to `new Worker(...)`. Typically an `import.meta.url`-relative `URL`. */\n  workerUrl: URL | string;\n  /** Worker module type. Defaults to `\"module\"` (ESM worker). */\n  workerType?: WorkerOptions[\"type\"];\n  /** Optional label shown in browser devtools’ Sources panel. */\n  workerName?: string;\n}\n\n/**\n * Create a {@link SyncoreWebWorkerClient} from a low-level message endpoint.\n *\n * Use this when you already have a `Worker` or `MessagePort` reference and\n * want to wrap it manually. For the common case of spawning a new Worker from\n * a URL, use `createSyncoreWebWorkerClient` instead.\n */\nexport function createWebWorkerClient(\n  endpoint: SyncoreWorkerMessageEndpoint\n): SyncoreWebWorkerClient {\n  return new SyncoreWebWorkerClient(endpoint);\n}\n\n/**\n * Create a {@link ManagedWebWorkerClient} using a provided Worker factory.\n *\n * Useful when you need control over how the Worker is constructed (e.g. to\n * pass constructor options not exposed by `CreateWebWorkerClientProviderOptions`).\n * For the common URL-based case, use `createSyncoreWebWorkerClient`.\n */\nexport function createManagedWebWorkerClient(options: {\n  createWorker: () => Worker;\n}): ManagedWebWorkerClient {\n  const worker = options.createWorker();\n  const client = createWebWorkerClient(worker);\n  return {\n    client,\n    worker,\n    dispose() {\n      client.dispose();\n      worker.terminate();\n    }\n  };\n}\n\n/**\n * Create a {@link ManagedWebWorkerClient} by spawning a new Worker from a URL.\n *\n * This is the standard way to create a main-thread client in a browser app.\n * Pass the URL of your `syncore.worker.ts` file (which calls\n * `createWebWorkerRuntime`) and connect the returned `client` to your React\n * `SyncoreProvider` or Svelte context.\n *\n * ```ts\n * // main.ts (or React root)\n * import { createSyncoreWebWorkerClient } from \"syncorejs/browser\";\n *\n * const { client, dispose } = createSyncoreWebWorkerClient({\n *   workerUrl: new URL(\"./syncore.worker.ts\", import.meta.url),\n * });\n * ```\n */\nexport function createSyncoreWebWorkerClient(\n  options: CreateWebWorkerClientProviderOptions\n): ManagedWebWorkerClient {\n  return createManagedWebWorkerClient({\n    createWorker: () =>\n      new Worker(options.workerUrl, {\n        type: options.workerType ?? \"module\",\n        ...(options.workerName ? { name: options.workerName } : {})\n      })\n  });\n}\n\n/**\n * Wire a Syncore runtime factory to a worker message endpoint.\n *\n * Called internally by `createWebWorkerRuntime`. Exposed for cases where you\n * need to attach a runtime to a custom bridge endpoint (e.g. a `MessagePort`).\n */\nexport function attachWebWorkerRuntime(\n  options: AttachWebWorkerRuntimeOptions\n): AttachedWebWorkerRuntime {\n  return attachRuntimeBridge(options);\n}\n"],"mappings":";;;;;;;;;;AAgCA,IAAa,yBAAb,cAA4C,oBAAoB,CAKhE;;;;;;;;AA6CA,SAAgB,sBACd,UACwB;CACxB,OAAO,IAAI,uBAAuB,QAAQ;AAC5C;;;;;;;;AASA,SAAgB,6BAA6B,SAElB;CACzB,MAAM,SAAS,QAAQ,aAAa;CACpC,MAAM,SAAS,sBAAsB,MAAM;CAC3C,OAAO;EACL;EACA;EACA,UAAU;GACR,OAAO,QAAQ;GACf,OAAO,UAAU;EACnB;CACF;AACF;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,6BACd,SACwB;CACxB,OAAO,6BAA6B,EAClC,oBACE,IAAI,OAAO,QAAQ,WAAW;EAC5B,MAAM,QAAQ,cAAc;EAC5B,GAAI,QAAQ,aAAa,EAAE,MAAM,QAAQ,WAAW,IAAI,CAAC;CAC3D,CAAC,EACL,CAAC;AACH;;;;;;;AAQA,SAAgB,uBACd,SAC0B;CAC1B,OAAO,oBAAoB,OAAO;AACpC"}

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,188 @@ 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 {@link 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
+ * {@link 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 {@link 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.initialNumItems - Number of items to load on the first page.
+ * @returns A {@link 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;;;;;;;;;;;;;;;;;;;;;;;;;iBA8MgB,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 {@link 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
+* {@link 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 {@link SyncoreQueryState}.
 */
 function useQueries(entries) {
 	const client = useSyncore();
@@ -125,7 +272,44 @@ 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.initialNumItems - Number of items to load on the first page.
+* @returns A {@link 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 +422,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) {