syncorejs 0.2.1 → 0.2.3

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

@@ -1,63 +1,141 @@
 import { createSyncoreNextWorkerUrl, getSyncoreWorkerUrl } from "./config.js";
 import { ManagedWebWorkerClient } from "../platform-web/index.d.ts";
 import { ReactNode } from "react";
-import * as react_jsx_runtime0 from "react/jsx-runtime";
 
 //#region src/index.d.ts
+/**
+ * Shared configuration options for the Syncore Next.js integration.
+ *
+ * Accepted by both {@link SyncoreNextProvider} and
+ * {@link registerSyncoreServiceWorker}.
+ */
 interface SyncoreNextOptions {
-  /** Optional service worker URL used to cache the application shell. */
+  /**
+   * URL of the Next PWA service worker. Defaults to `"/sw.js"` (the path
+   * emitted by `next-pwa` or `@ducanh2912/next-pwa`).
+   */
   serviceWorkerUrl?: string;
-  /** Optional URL for the `sql.js` wasm asset. */
-  wasmAssetUrl?: string;
-  /** Optional URL for the worker asset used by the local Syncore runtime. */
+  /**
+   * Public path to the compiled Syncore worker asset. Defaults to
+   * `"/syncore.worker.js"`. Override if your build tool emits the worker to a
+   * different path.
+   */
   workerAssetUrl?: string;
 }
 /**
- * The result of registering the Syncore service worker in a Next app.
+ * Handle returned by {@link registerSyncoreServiceWorker}.
  */
 interface SyncoreServiceWorkerRegistration {
   /** Unregister the installed service worker. */
   unregister(): Promise<boolean>;
-  /** Ask the browser to check for an updated service worker. */
+  /**
+   * Instruct the browser to check for a new service worker version. Useful
+   * for implementing an “Update available” prompt.
+   */
   update(): Promise<ServiceWorkerRegistration>;
 }
 /**
- * Register the Syncore service worker used by the Next integration.
+ * Register the Syncore PWA service worker in a Next.js app.
+ *
+ * Call this once at app startup (e.g. in your root layout’s `useEffect`, or in
+ * `instrumentation.ts` with `"use client"`). Returns `null` on the server or
+ * when the browser does not support service workers.
+ *
+ * ```ts
+ * // app/layout.tsx (client component)
+ * import { registerSyncoreServiceWorker } from "syncorejs/next";
+ *
+ * useEffect(() => {
+ *   registerSyncoreServiceWorker({ serviceWorkerUrl: "/sw.js" });
+ * }, []);
+ * ```
+ *
+ * @param options - Optional configuration. Defaults to `"/sw.js"`.
+ * @returns A {@link SyncoreServiceWorkerRegistration} handle, or `null` on
+ *   the server / when unsupported.
  */
 declare function registerSyncoreServiceWorker(options?: SyncoreNextOptions): Promise<SyncoreServiceWorkerRegistration | null>;
 /**
- * Resolve the public URL used by SQL.js to load its wasm file in a Next app.
- */
-declare function resolveSqlJsWasmUrl(options?: SyncoreNextOptions): string;
-/**
- * Create a worker-backed Syncore client for a Next app.
+ * Create a worker-backed Syncore client for a Next.js app.
+ *
+ * The client communicates with a Syncore runtime running inside a `Worker`.
+ * The worker runs the SQLite engine and all function handlers off the main
+ * thread so the UI stays responsive.
+ *
+ * In most cases you should use {@link SyncoreNextProvider} instead, which
+ * manages the client lifecycle automatically. Use `createNextSyncoreClient`
+ * directly only when you need to control the client lifecycle yourself (e.g.
+ * in testing harnesses or custom providers).
+ *
+ * ```ts
+ * const managedClient = createNextSyncoreClient({
+ *   workerAssetUrl: "/syncore.worker.js",
+ * });
+ *
+ * // Later:
+ * managedClient.dispose();
+ * ```
  */
 declare function createNextSyncoreClient(options: {
   /**
-   * Optional custom worker factory for tests or framework-specific worker
-   * bundling patterns such as Next App Router development.
+   * Custom worker factory function. Useful in tests (supply a `Worker` backed
+   * by a mock or in-process runtime) or when using Next’s App Router dev-mode
+   * bundling where `new Worker(new URL(...))` must be used inside the component.
    */
-  createWorker?: () => Worker; /** Optional explicit module URL for an already-public worker asset. */
-  workerUrl?: URL | string; /** Optional public worker asset path for production builds. */
+  createWorker?: () => Worker; /** Explicit module URL for an already-public worker script. */
+  workerUrl?: URL | string; /** Public asset path for the compiled worker file. Defaults to `"/syncore.worker.js"`. */
   workerAssetUrl?: string;
 }): ManagedWebWorkerClient;
 /**
- * Register a service worker while rendering a React subtree.
+ * React component that registers a PWA service worker as a side-effect.
+ *
+ * Renders its `children` immediately (no loading state) and registers the
+ * service worker asynchronously. Safe to render on the server — the
+ * registration effect only runs in browsers that support service workers.
+ *
+ * ```tsx
+ * <SyncoreServiceWorker serviceWorkerUrl="/sw.js" onRegistered={console.log}>
+ *   <App />
+ * </SyncoreServiceWorker>
+ * ```
  */
 declare function SyncoreServiceWorker({
   children,
   serviceWorkerUrl,
   onRegistered
 }: {
-  children: ReactNode;
-  serviceWorkerUrl?: string;
+  children: ReactNode; /** URL of the service worker script. Defaults to `"/sw.js"`. */
+  serviceWorkerUrl?: string; /** Called after the service worker is successfully registered. */
   onRegistered?: (registration: ServiceWorkerRegistration) => void;
 }): ReactNode;
 /**
- * Provides a worker-backed Syncore client to a Next React tree.
+ * Root provider that wires a worker-backed Syncore runtime into a Next.js
+ * React tree.
+ *
+ * Place this at the top of your App Router layout. It spawns the Syncore
+ * worker on mount, exposes the client via React context (accessible with
+ * `useSyncore()`), and optionally registers the PWA service worker.
+ *
+ * ```tsx
+ * // app/layout.tsx
+ * import { SyncoreNextProvider } from "syncorejs/next";
  *
- * This is the shortest recommended integration for App Router pages that run
- * fully local in the browser.
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         <SyncoreNextProvider
+ *           createWorker={() => new Worker(
+ *             new URL("../syncore.worker.ts", import.meta.url)
+ *           )}
+ *         >
+ *           {children}
+ *         </SyncoreNextProvider>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
  */
 declare function SyncoreNextProvider({
   children,
@@ -68,13 +146,15 @@ declare function SyncoreNextProvider({
 }: {
   /** The React subtree that should receive the Syncore client. */children: ReactNode;
   /**
-   * Optional custom worker factory for tests or Next colocated worker modules.
+   * Factory function that creates the Syncore `Worker`. Required in Next App
+   * Router dev mode because `new Worker(new URL(..., import.meta.url))` must
+   * be called inside the module to be bundled correctly.
    */
-  createWorker?: () => Worker; /** Optional service worker URL used to cache the application shell. */
-  serviceWorkerUrl?: string; /** Optional explicit module URL for an already-public worker asset. */
-  workerUrl?: URL | string; /** Optional public worker asset path for production builds. */
+  createWorker?: () => Worker; /** URL of the PWA service worker script. Omit to skip service worker registration. */
+  serviceWorkerUrl?: string; /** Explicit module URL for an already-public worker asset. */
+  workerUrl?: URL | string; /** Public asset path for the compiled worker file. Defaults to `"/syncore.worker.js"`. */
   workerAssetUrl?: string;
-}): react_jsx_runtime0.JSX.Element | null;
+}): import("react/jsx-runtime").JSX.Element;
 //#endregion
-export { SyncoreNextOptions, SyncoreNextProvider, SyncoreServiceWorker, SyncoreServiceWorkerRegistration, createNextSyncoreClient, createSyncoreNextWorkerUrl, getSyncoreWorkerUrl, registerSyncoreServiceWorker, resolveSqlJsWasmUrl };
+export { SyncoreNextOptions, SyncoreNextProvider, SyncoreServiceWorker, SyncoreServiceWorkerRegistration, createNextSyncoreClient, createSyncoreNextWorkerUrl, getSyncoreWorkerUrl, registerSyncoreServiceWorker };
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.tsx"],"mappings":";;;;;;UAYiB,kBAAA;;EAEf,gBAAA;EAFiC;EAKjC,YAAA;EALiC;EAQjC,cAAA;AAAA;;;;UAMe,gCAAA;EAAgC;EAE/C,UAAA,IAAc,OAAA;EAAA;EAGd,MAAA,IAAU,OAAA,CAAQ,yBAAA;AAAA;;;;iBAME,4BAAA,CACpB,OAAA,GAAU,kBAAA,GACT,OAAA,CAAQ,gCAAA;;;;iBAkBK,mBAAA,CAAoB,OAAA,GAAU,kBAAA;;AApB9C;;iBA2BgB,uBAAA,CAAwB,OAAA;EA1B5B;;;;EA+BV,YAAA,SAAqB,MAAA,EA/BX;EAkCV,SAAA,GAAY,GAAA,WAjCX;EAoCD,cAAA;AAAA,IACE,sBAAA;;AAnBJ;;iBAmCgB,oBAAA,CAAA;EACd,QAAA;EACA,gBAAA;EACA;AAAA;EAEA,QAAA,EAAU,SAAA;EACV,gBAAA;EACA,YAAA,IAAgB,YAAA,EAAc,yBAAA;AAAA,IAC/B,SAAA;;;;;;;iBAsBe,mBAAA,CAAA;EACd,QAAA;EACA,YAAA;EACA,gBAAA;EACA,SAAA;EACA;AAAA;EA1DqB,gEA6DrB,QAAA,EAAU,SAAA;EA1DE;;;EA+DZ,YAAA,SAAqB,MAAA,EA3DG;EA8DxB,gBAAA,WA9Cc;EAiDd,SAAA,GAAY,GAAA;EAGZ,cAAA;AAAA,IACD,kBAAA,CAAA,GAAA,CAAA,OAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.tsx"],"mappings":";;;;;;AA4BA;;;;AAYgB;UAZC,kBAAA;EAkBgC;;;;EAb/C,gBAAA;EAqBiB;;;;;EAdjB,cAAc;AAAA;;AAc6B;AAuB7C;UA/BiB,gCAAA;;EAEf,UAAA,IAAc,OAAA;EA+BL;;;;EAzBT,MAAA,IAAU,OAAA,CAAQ,yBAAA;AAAA;;;;AAyBuB;AAoC3C;;;;;;;;;;;;;;;;iBAtCsB,4BAAA,CACpB,OAAA,GAAU,kBAAA,GACT,OAAA,CAAQ,gCAAA;AA2EX;;;;;;;;;;;;;;;;;;;;;AAAA,iBAvCgB,uBAAA,CAAwB,OAAA;EAgDtB;;;AACjB;AA6CD;EAxFE,YAAA,SAAqB,MAAA;EAGrB,SAAA,GAAY,GAAA,WAuFZ;EApFA,cAAA;AAAA,IACE,sBAAA;;;;;;;;;;;;;;iBA0BY,oBAAA,CAAA;EACd,QAAA;EACA,gBAAA;EACA;AAAA;EAEA,QAAA,EAAU,SAAA,EAuDV;EArDA,gBAAA,WAwDU;EAtDV,YAAA,IAAgB,YAAA,EAAc,yBAAA;AAAA,IAC/B,SAAA;;;;;;;;AAsEA;;;;;;;;;;;;;;;;;;;;;;iBAzBe,mBAAA,CAAA;EACd,QAAA;EACA,YAAA;EACA,gBAAA;EACA,SAAA;EACA;AAAA;kEAGA,QAAA,EAAU,SAAA;;;;;;EAOV,YAAA,SAAqB,MAAA;EAGrB,gBAAA;EAGA,SAAA,GAAY,GAAA;EAGZ,cAAA;AAAA,gCACD,GAAA,CAAA,OAAA"}

package/dist/_vendor/next/index.js

@@ -1,11 +1,29 @@
 import { createSyncoreNextWorkerUrl, getSyncoreWorkerUrl } from "./config.js";
+import { createUnavailableSyncoreClient } from "../core/index.mjs";
 import { createManagedWebWorkerClient, createSyncoreWebWorkerClient } from "../platform-web/index.js";
 import { SyncoreProvider } from "../react/index.js";
-import { useEffect, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/index.tsx
 /**
-* Register the Syncore service worker used by the Next integration.
+* Register the Syncore PWA service worker in a Next.js app.
+*
+* Call this once at app startup (e.g. in your root layout’s `useEffect`, or in
+* `instrumentation.ts` with `"use client"`). Returns `null` on the server or
+* when the browser does not support service workers.
+*
+* ```ts
+* // app/layout.tsx (client component)
+* import { registerSyncoreServiceWorker } from "syncorejs/next";
+*
+* useEffect(() => {
+*   registerSyncoreServiceWorker({ serviceWorkerUrl: "/sw.js" });
+* }, []);
+* ```
+*
+* @param options - Optional configuration. Defaults to `"/sw.js"`.
+* @returns A {@link SyncoreServiceWorkerRegistration} handle, or `null` on
+*   the server / when unsupported.
 */
 async function registerSyncoreServiceWorker(options) {
 	if (typeof window === "undefined" || !("serviceWorker" in navigator)) return null;
@@ -16,20 +34,42 @@ async function registerSyncoreServiceWorker(options) {
 	};
 }
 /**
-* Resolve the public URL used by SQL.js to load its wasm file in a Next app.
-*/
-function resolveSqlJsWasmUrl(options) {
-	return options?.wasmAssetUrl ?? "/sql-wasm.wasm";
-}
-/**
-* Create a worker-backed Syncore client for a Next app.
+* Create a worker-backed Syncore client for a Next.js app.
+*
+* The client communicates with a Syncore runtime running inside a `Worker`.
+* The worker runs the SQLite engine and all function handlers off the main
+* thread so the UI stays responsive.
+*
+* In most cases you should use {@link SyncoreNextProvider} instead, which
+* manages the client lifecycle automatically. Use `createNextSyncoreClient`
+* directly only when you need to control the client lifecycle yourself (e.g.
+* in testing harnesses or custom providers).
+*
+* ```ts
+* const managedClient = createNextSyncoreClient({
+*   workerAssetUrl: "/syncore.worker.js",
+* });
+*
+* // Later:
+* managedClient.dispose();
+* ```
 */
 function createNextSyncoreClient(options) {
 	if (options.createWorker) return createManagedWebWorkerClient({ createWorker: options.createWorker });
 	return createSyncoreWebWorkerClient({ workerUrl: options.workerUrl ?? options.workerAssetUrl ?? "/syncore.worker.js" });
 }
 /**
-* Register a service worker while rendering a React subtree.
+* React component that registers a PWA service worker as a side-effect.
+*
+* Renders its `children` immediately (no loading state) and registers the
+* service worker asynchronously. Safe to render on the server — the
+* registration effect only runs in browsers that support service workers.
+*
+* ```tsx
+* <SyncoreServiceWorker serviceWorkerUrl="/sw.js" onRegistered={console.log}>
+*   <App />
+* </SyncoreServiceWorker>
+* ```
 */
 function SyncoreServiceWorker({ children, serviceWorkerUrl, onRegistered }) {
 	useEffect(() => {
@@ -42,40 +82,78 @@ function SyncoreServiceWorker({ children, serviceWorkerUrl, onRegistered }) {
 	return children;
 }
 /**
-* Provides a worker-backed Syncore client to a Next React tree.
+* Root provider that wires a worker-backed Syncore runtime into a Next.js
+* React tree.
+*
+* Place this at the top of your App Router layout. It spawns the Syncore
+* worker on mount, exposes the client via React context (accessible with
+* `useSyncore()`), and optionally registers the PWA service worker.
+*
+* ```tsx
+* // app/layout.tsx
+* import { SyncoreNextProvider } from "syncorejs/next";
 *
-* This is the shortest recommended integration for App Router pages that run
-* fully local in the browser.
+* export default function RootLayout({ children }) {
+*   return (
+*     <html>
+*       <body>
+*         <SyncoreNextProvider
+*           createWorker={() => new Worker(
+*             new URL("../syncore.worker.ts", import.meta.url)
+*           )}
+*         >
+*           {children}
+*         </SyncoreNextProvider>
+*       </body>
+*     </html>
+*   );
+* }
+* ```
 */
 function SyncoreNextProvider({ children, createWorker, serviceWorkerUrl, workerUrl, workerAssetUrl }) {
-	const [managedClient, setManagedClient] = useState(null);
+	const createWorkerRef = useRef(createWorker);
+	createWorkerRef.current = createWorker;
 	const resolvedWorkerUrl = typeof workerUrl === "string" ? workerUrl : workerUrl?.toString();
+	const bootingClient = useMemo(() => createUnavailableSyncoreClient({
+		kind: "starting",
+		reason: "booting"
+	}), []);
+	const [client, setClient] = useState(bootingClient);
 	useEffect(() => {
-		const nextClient = createNextSyncoreClient({
-			...createWorker ? { createWorker } : {},
-			...resolvedWorkerUrl ? { workerUrl: process.env.NODE_ENV === "production" ? getSyncoreWorkerUrl() : resolvedWorkerUrl } : {},
-			...workerAssetUrl ? { workerAssetUrl } : {}
-		});
-		setManagedClient(nextClient);
+		let managedClient;
+		setClient(bootingClient);
+		try {
+			const workerFactory = createWorkerRef.current;
+			managedClient = createNextSyncoreClient({
+				...workerFactory ? { createWorker: () => workerFactory() } : {},
+				...resolvedWorkerUrl ? { workerUrl: process.env.NODE_ENV === "production" ? getSyncoreWorkerUrl() : resolvedWorkerUrl } : {},
+				...workerAssetUrl ? { workerAssetUrl } : {}
+			});
+			setClient(managedClient.client);
+		} catch (error) {
+			setClient(createUnavailableSyncoreClient({
+				kind: "unavailable",
+				reason: "worker-unavailable",
+				...error instanceof Error ? { error } : {}
+			}));
+		}
 		return () => {
-			nextClient.dispose();
-			setManagedClient(null);
+			managedClient?.dispose();
 		};
 	}, [
-		createWorker,
+		bootingClient,
 		resolvedWorkerUrl,
 		workerAssetUrl
 	]);
-	if (!managedClient) return null;
 	return /* @__PURE__ */ jsx(SyncoreServiceWorker, {
 		...serviceWorkerUrl ? { serviceWorkerUrl } : {},
 		children: /* @__PURE__ */ jsx(SyncoreProvider, {
-			client: managedClient.client,
+			client,
 			children
 		})
 	});
 }
 //#endregion
-export { SyncoreNextProvider, SyncoreServiceWorker, createNextSyncoreClient, createSyncoreNextWorkerUrl, getSyncoreWorkerUrl, registerSyncoreServiceWorker, resolveSqlJsWasmUrl };
+export { SyncoreNextProvider, SyncoreServiceWorker, createNextSyncoreClient, createSyncoreNextWorkerUrl, getSyncoreWorkerUrl, registerSyncoreServiceWorker };
 
 //# sourceMappingURL=index.js.map

package/dist/_vendor/next/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.tsx"],"sourcesContent":["import {\n  createManagedWebWorkerClient,\n  createSyncoreWebWorkerClient,\n  type ManagedWebWorkerClient\n} from \"@syncore/platform-web\";\nimport { SyncoreProvider } from \"@syncore/react\";\nimport { useEffect, useState, type ReactNode } from \"react\";\nimport { getSyncoreWorkerUrl } from \"./config.js\";\n\nexport { getSyncoreWorkerUrl } from \"./config.js\";\nexport { createSyncoreNextWorkerUrl } from \"./config.js\";\n\nexport interface SyncoreNextOptions {\n  /** Optional service worker URL used to cache the application shell. */\n  serviceWorkerUrl?: string;\n\n  /** Optional URL for the `sql.js` wasm asset. */\n  wasmAssetUrl?: string;\n\n  /** Optional URL for the worker asset used by the local Syncore runtime. */\n  workerAssetUrl?: string;\n}\n\n/**\n * The result of registering the Syncore service worker in a Next app.\n */\nexport interface SyncoreServiceWorkerRegistration {\n  /** Unregister the installed service worker. */\n  unregister(): Promise<boolean>;\n\n  /** Ask the browser to check for an updated service worker. */\n  update(): Promise<ServiceWorkerRegistration>;\n}\n\n/**\n * Register the Syncore service worker used by the Next integration.\n */\nexport async function registerSyncoreServiceWorker(\n  options?: SyncoreNextOptions\n): Promise<SyncoreServiceWorkerRegistration | null> {\n  if (typeof window === \"undefined\" || !(\"serviceWorker\" in navigator)) {\n    return null;\n  }\n\n  const registration = await navigator.serviceWorker.register(\n    options?.serviceWorkerUrl ?? \"/sw.js\"\n  );\n\n  return {\n    unregister: () => registration.unregister(),\n    update: () => registration.update()\n  };\n}\n\n/**\n * Resolve the public URL used by SQL.js to load its wasm file in a Next app.\n */\nexport function resolveSqlJsWasmUrl(options?: SyncoreNextOptions): string {\n  return options?.wasmAssetUrl ?? \"/sql-wasm.wasm\";\n}\n\n/**\n * Create a worker-backed Syncore client for a Next app.\n */\nexport function createNextSyncoreClient(options: {\n  /**\n   * Optional custom worker factory for tests or framework-specific worker\n   * bundling patterns such as Next App Router development.\n   */\n  createWorker?: () => Worker;\n\n  /** Optional explicit module URL for an already-public worker asset. */\n  workerUrl?: URL | string;\n\n  /** Optional public worker asset path for production builds. */\n  workerAssetUrl?: string;\n}): ManagedWebWorkerClient {\n  if (options.createWorker) {\n    return createManagedWebWorkerClient({\n      createWorker: options.createWorker\n    });\n  }\n\n  return createSyncoreWebWorkerClient({\n    workerUrl:\n      options.workerUrl ?? options.workerAssetUrl ?? \"/syncore.worker.js\"\n  });\n}\n\n/**\n * Register a service worker while rendering a React subtree.\n */\nexport function SyncoreServiceWorker({\n  children,\n  serviceWorkerUrl,\n  onRegistered\n}: {\n  children: ReactNode;\n  serviceWorkerUrl?: string;\n  onRegistered?: (registration: ServiceWorkerRegistration) => void;\n}) {\n  useEffect(() => {\n    void (async () => {\n      if (typeof window === \"undefined\" || !(\"serviceWorker\" in navigator)) {\n        return;\n      }\n      const registration = await navigator.serviceWorker.register(\n        serviceWorkerUrl ?? \"/sw.js\"\n      );\n      onRegistered?.(registration);\n    })();\n  }, [onRegistered, serviceWorkerUrl]);\n\n  return children;\n}\n\n/**\n * Provides a worker-backed Syncore client to a Next React tree.\n *\n * This is the shortest recommended integration for App Router pages that run\n * fully local in the browser.\n */\nexport function SyncoreNextProvider({\n  children,\n  createWorker,\n  serviceWorkerUrl,\n  workerUrl,\n  workerAssetUrl\n}: {\n  /** The React subtree that should receive the Syncore client. */\n  children: ReactNode;\n\n  /**\n   * Optional custom worker factory for tests or Next colocated worker modules.\n   */\n  createWorker?: () => Worker;\n\n  /** Optional service worker URL used to cache the application shell. */\n  serviceWorkerUrl?: string;\n\n  /** Optional explicit module URL for an already-public worker asset. */\n  workerUrl?: URL | string;\n\n  /** Optional public worker asset path for production builds. */\n  workerAssetUrl?: string;\n}) {\n  const [managedClient, setManagedClient] =\n    useState<ManagedWebWorkerClient | null>(null);\n  const resolvedWorkerUrl =\n    typeof workerUrl === \"string\" ? workerUrl : workerUrl?.toString();\n\n  useEffect(() => {\n    const nextClient = createNextSyncoreClient({\n      ...(createWorker ? { createWorker } : {}),\n      ...(resolvedWorkerUrl\n        ? {\n            workerUrl:\n              process.env.NODE_ENV === \"production\"\n                ? getSyncoreWorkerUrl()\n                : resolvedWorkerUrl\n          }\n        : {}),\n      ...(workerAssetUrl ? { workerAssetUrl } : {})\n    });\n    setManagedClient(nextClient);\n\n    return () => {\n      nextClient.dispose();\n      setManagedClient(null);\n    };\n  }, [createWorker, resolvedWorkerUrl, workerAssetUrl]);\n\n  if (!managedClient) {\n    return null;\n  }\n\n  return (\n    <SyncoreServiceWorker {...(serviceWorkerUrl ? { serviceWorkerUrl } : {})}>\n      <SyncoreProvider client={managedClient.client}>\n        {children}\n      </SyncoreProvider>\n    </SyncoreServiceWorker>\n  );\n}\n"],"mappings":";;;;;;;;;AAqCA,eAAsB,6BACpB,SACkD;AAClD,KAAI,OAAO,WAAW,eAAe,EAAE,mBAAmB,WACxD,QAAO;CAGT,MAAM,eAAe,MAAM,UAAU,cAAc,SACjD,SAAS,oBAAoB,SAC9B;AAED,QAAO;EACL,kBAAkB,aAAa,YAAY;EAC3C,cAAc,aAAa,QAAQ;EACpC;;;;;AAMH,SAAgB,oBAAoB,SAAsC;AACxE,QAAO,SAAS,gBAAgB;;;;;AAMlC,SAAgB,wBAAwB,SAYb;AACzB,KAAI,QAAQ,aACV,QAAO,6BAA6B,EAClC,cAAc,QAAQ,cACvB,CAAC;AAGJ,QAAO,6BAA6B,EAClC,WACE,QAAQ,aAAa,QAAQ,kBAAkB,sBAClD,CAAC;;;;;AAMJ,SAAgB,qBAAqB,EACnC,UACA,kBACA,gBAKC;AACD,iBAAgB;AACd,GAAM,YAAY;AAChB,OAAI,OAAO,WAAW,eAAe,EAAE,mBAAmB,WACxD;GAEF,MAAM,eAAe,MAAM,UAAU,cAAc,SACjD,oBAAoB,SACrB;AACD,kBAAe,aAAa;MAC1B;IACH,CAAC,cAAc,iBAAiB,CAAC;AAEpC,QAAO;;;;;;;;AAST,SAAgB,oBAAoB,EAClC,UACA,cACA,kBACA,WACA,kBAkBC;CACD,MAAM,CAAC,eAAe,oBACpB,SAAwC,KAAK;CAC/C,MAAM,oBACJ,OAAO,cAAc,WAAW,YAAY,WAAW,UAAU;AAEnE,iBAAgB;EACd,MAAM,aAAa,wBAAwB;GACzC,GAAI,eAAe,EAAE,cAAc,GAAG,EAAE;GACxC,GAAI,oBACA,EACE,WACE,QAAQ,IAAI,aAAa,eACrB,qBAAqB,GACrB,mBACP,GACD,EAAE;GACN,GAAI,iBAAiB,EAAE,gBAAgB,GAAG,EAAE;GAC7C,CAAC;AACF,mBAAiB,WAAW;AAE5B,eAAa;AACX,cAAW,SAAS;AACpB,oBAAiB,KAAK;;IAEvB;EAAC;EAAc;EAAmB;EAAe,CAAC;AAErD,KAAI,CAAC,cACH,QAAO;AAGT,QACE,oBAAC,sBAAD;EAAsB,GAAK,mBAAmB,EAAE,kBAAkB,GAAG,EAAE;YACrE,oBAAC,iBAAD;GAAiB,QAAQ,cAAc;GACpC;GACe,CAAA;EACG,CAAA"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.tsx"],"sourcesContent":["import {\n  createUnavailableSyncoreClient,\n  type SyncoreClient\n} from \"@syncore/core\";\nimport {\n  createManagedWebWorkerClient,\n  createSyncoreWebWorkerClient,\n  type ManagedWebWorkerClient\n} from \"@syncore/platform-web\";\nimport { SyncoreProvider } from \"@syncore/react\";\nimport {\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n  type ReactNode\n} from \"react\";\nimport { getSyncoreWorkerUrl } from \"./config.js\";\n\nexport { getSyncoreWorkerUrl } from \"./config.js\";\nexport { createSyncoreNextWorkerUrl } from \"./config.js\";\n\n/**\n * Shared configuration options for the Syncore Next.js integration.\n *\n * Accepted by both {@link SyncoreNextProvider} and\n * {@link registerSyncoreServiceWorker}.\n */\nexport interface SyncoreNextOptions {\n  /**\n   * URL of the Next PWA service worker. Defaults to `\"/sw.js\"` (the path\n   * emitted by `next-pwa` or `@ducanh2912/next-pwa`).\n   */\n  serviceWorkerUrl?: string;\n\n  /**\n   * Public path to the compiled Syncore worker asset. Defaults to\n   * `\"/syncore.worker.js\"`. Override if your build tool emits the worker to a\n   * different path.\n   */\n  workerAssetUrl?: string;\n}\n\n/**\n * Handle returned by {@link registerSyncoreServiceWorker}.\n */\nexport interface SyncoreServiceWorkerRegistration {\n  /** Unregister the installed service worker. */\n  unregister(): Promise<boolean>;\n\n  /**\n   * Instruct the browser to check for a new service worker version. Useful\n   * for implementing an “Update available” prompt.\n   */\n  update(): Promise<ServiceWorkerRegistration>;\n}\n\n/**\n * Register the Syncore PWA service worker in a Next.js app.\n *\n * Call this once at app startup (e.g. in your root layout’s `useEffect`, or in\n * `instrumentation.ts` with `\"use client\"`). Returns `null` on the server or\n * when the browser does not support service workers.\n *\n * ```ts\n * // app/layout.tsx (client component)\n * import { registerSyncoreServiceWorker } from \"syncorejs/next\";\n *\n * useEffect(() => {\n *   registerSyncoreServiceWorker({ serviceWorkerUrl: \"/sw.js\" });\n * }, []);\n * ```\n *\n * @param options - Optional configuration. Defaults to `\"/sw.js\"`.\n * @returns A {@link SyncoreServiceWorkerRegistration} handle, or `null` on\n *   the server / when unsupported.\n */\nexport async function registerSyncoreServiceWorker(\n  options?: SyncoreNextOptions\n): Promise<SyncoreServiceWorkerRegistration | null> {\n  if (typeof window === \"undefined\" || !(\"serviceWorker\" in navigator)) {\n    return null;\n  }\n\n  const registration = await navigator.serviceWorker.register(\n    options?.serviceWorkerUrl ?? \"/sw.js\"\n  );\n\n  return {\n    unregister: () => registration.unregister(),\n    update: () => registration.update()\n  };\n}\n\n/**\n * Create a worker-backed Syncore client for a Next.js app.\n *\n * The client communicates with a Syncore runtime running inside a `Worker`.\n * The worker runs the SQLite engine and all function handlers off the main\n * thread so the UI stays responsive.\n *\n * In most cases you should use {@link SyncoreNextProvider} instead, which\n * manages the client lifecycle automatically. Use `createNextSyncoreClient`\n * directly only when you need to control the client lifecycle yourself (e.g.\n * in testing harnesses or custom providers).\n *\n * ```ts\n * const managedClient = createNextSyncoreClient({\n *   workerAssetUrl: \"/syncore.worker.js\",\n * });\n *\n * // Later:\n * managedClient.dispose();\n * ```\n */\nexport function createNextSyncoreClient(options: {\n  /**\n   * Custom worker factory function. Useful in tests (supply a `Worker` backed\n   * by a mock or in-process runtime) or when using Next’s App Router dev-mode\n   * bundling where `new Worker(new URL(...))` must be used inside the component.\n   */\n  createWorker?: () => Worker;\n\n  /** Explicit module URL for an already-public worker script. */\n  workerUrl?: URL | string;\n\n  /** Public asset path for the compiled worker file. Defaults to `\"/syncore.worker.js\"`. */\n  workerAssetUrl?: string;\n}): ManagedWebWorkerClient {\n  if (options.createWorker) {\n    return createManagedWebWorkerClient({\n      createWorker: options.createWorker\n    });\n  }\n\n  return createSyncoreWebWorkerClient({\n    workerUrl:\n      options.workerUrl ?? options.workerAssetUrl ?? \"/syncore.worker.js\"\n  });\n}\n\n/**\n * React component that registers a PWA service worker as a side-effect.\n *\n * Renders its `children` immediately (no loading state) and registers the\n * service worker asynchronously. Safe to render on the server — the\n * registration effect only runs in browsers that support service workers.\n *\n * ```tsx\n * <SyncoreServiceWorker serviceWorkerUrl=\"/sw.js\" onRegistered={console.log}>\n *   <App />\n * </SyncoreServiceWorker>\n * ```\n */\nexport function SyncoreServiceWorker({\n  children,\n  serviceWorkerUrl,\n  onRegistered\n}: {\n  children: ReactNode;\n  /** URL of the service worker script. Defaults to `\"/sw.js\"`. */\n  serviceWorkerUrl?: string;\n  /** Called after the service worker is successfully registered. */\n  onRegistered?: (registration: ServiceWorkerRegistration) => void;\n}) {\n  useEffect(() => {\n    void (async () => {\n      if (typeof window === \"undefined\" || !(\"serviceWorker\" in navigator)) {\n        return;\n      }\n      const registration = await navigator.serviceWorker.register(\n        serviceWorkerUrl ?? \"/sw.js\"\n      );\n      onRegistered?.(registration);\n    })();\n  }, [onRegistered, serviceWorkerUrl]);\n\n  return children;\n}\n\n/**\n * Root provider that wires a worker-backed Syncore runtime into a Next.js\n * React tree.\n *\n * Place this at the top of your App Router layout. It spawns the Syncore\n * worker on mount, exposes the client via React context (accessible with\n * `useSyncore()`), and optionally registers the PWA service worker.\n *\n * ```tsx\n * // app/layout.tsx\n * import { SyncoreNextProvider } from \"syncorejs/next\";\n *\n * export default function RootLayout({ children }) {\n *   return (\n *     <html>\n *       <body>\n *         <SyncoreNextProvider\n *           createWorker={() => new Worker(\n *             new URL(\"../syncore.worker.ts\", import.meta.url)\n *           )}\n *         >\n *           {children}\n *         </SyncoreNextProvider>\n *       </body>\n *     </html>\n *   );\n * }\n * ```\n */\nexport function SyncoreNextProvider({\n  children,\n  createWorker,\n  serviceWorkerUrl,\n  workerUrl,\n  workerAssetUrl\n}: {\n  /** The React subtree that should receive the Syncore client. */\n  children: ReactNode;\n\n  /**\n   * Factory function that creates the Syncore `Worker`. Required in Next App\n   * Router dev mode because `new Worker(new URL(..., import.meta.url))` must\n   * be called inside the module to be bundled correctly.\n   */\n  createWorker?: () => Worker;\n\n  /** URL of the PWA service worker script. Omit to skip service worker registration. */\n  serviceWorkerUrl?: string;\n\n  /** Explicit module URL for an already-public worker asset. */\n  workerUrl?: URL | string;\n\n  /** Public asset path for the compiled worker file. Defaults to `\"/syncore.worker.js\"`. */\n  workerAssetUrl?: string;\n}) {\n  const createWorkerRef = useRef(createWorker);\n  createWorkerRef.current = createWorker;\n  const resolvedWorkerUrl =\n    typeof workerUrl === \"string\" ? workerUrl : workerUrl?.toString();\n  const bootingClient = useMemo(\n    () =>\n      createUnavailableSyncoreClient({\n        kind: \"starting\",\n        reason: \"booting\"\n      }),\n    []\n  );\n  const [client, setClient] = useState<SyncoreClient>(bootingClient);\n\n  useEffect(() => {\n    let managedClient: ManagedWebWorkerClient | undefined;\n\n    setClient(bootingClient);\n\n    try {\n      const workerFactory = createWorkerRef.current;\n      managedClient = createNextSyncoreClient({\n        ...(workerFactory\n          ? {\n              createWorker: () => workerFactory()\n            }\n          : {}),\n        ...(resolvedWorkerUrl\n          ? {\n              workerUrl:\n                process.env.NODE_ENV === \"production\"\n                  ? getSyncoreWorkerUrl()\n                  : resolvedWorkerUrl\n            }\n          : {}),\n        ...(workerAssetUrl ? { workerAssetUrl } : {})\n      });\n      setClient(managedClient.client);\n    } catch (error) {\n      setClient(\n        createUnavailableSyncoreClient({\n          kind: \"unavailable\",\n          reason: \"worker-unavailable\",\n          ...(error instanceof Error ? { error } : {})\n        })\n      );\n    }\n\n    return () => {\n      managedClient?.dispose();\n    };\n  }, [bootingClient, resolvedWorkerUrl, workerAssetUrl]);\n\n  return (\n    <SyncoreServiceWorker {...(serviceWorkerUrl ? { serviceWorkerUrl } : {})}>\n      <SyncoreProvider client={client}>{children}</SyncoreProvider>\n    </SyncoreServiceWorker>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA6EA,eAAsB,6BACpB,SACkD;CAClD,IAAI,OAAO,WAAW,eAAe,EAAE,mBAAmB,YACxD,OAAO;CAGT,MAAM,eAAe,MAAM,UAAU,cAAc,SACjD,SAAS,oBAAoB,QAC/B;CAEA,OAAO;EACL,kBAAkB,aAAa,WAAW;EAC1C,cAAc,aAAa,OAAO;CACpC;AACF;;;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,wBAAwB,SAab;CACzB,IAAI,QAAQ,cACV,OAAO,6BAA6B,EAClC,cAAc,QAAQ,aACxB,CAAC;CAGH,OAAO,6BAA6B,EAClC,WACE,QAAQ,aAAa,QAAQ,kBAAkB,qBACnD,CAAC;AACH;;;;;;;;;;;;;;AAeA,SAAgB,qBAAqB,EACnC,UACA,kBACA,gBAOC;CACD,gBAAgB;EACd,CAAM,YAAY;GAChB,IAAI,OAAO,WAAW,eAAe,EAAE,mBAAmB,YACxD;GAEF,MAAM,eAAe,MAAM,UAAU,cAAc,SACjD,oBAAoB,QACtB;GACA,eAAe,YAAY;EAC7B,GAAG;CACL,GAAG,CAAC,cAAc,gBAAgB,CAAC;CAEnC,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,SAAgB,oBAAoB,EAClC,UACA,cACA,kBACA,WACA,kBAoBC;CACD,MAAM,kBAAkB,OAAO,YAAY;CAC3C,gBAAgB,UAAU;CAC1B,MAAM,oBACJ,OAAO,cAAc,WAAW,YAAY,WAAW,SAAS;CAClE,MAAM,gBAAgB,cAElB,+BAA+B;EAC7B,MAAM;EACN,QAAQ;CACV,CAAC,GACH,CAAC,CACH;CACA,MAAM,CAAC,QAAQ,aAAa,SAAwB,aAAa;CAEjE,gBAAgB;EACd,IAAI;EAEJ,UAAU,aAAa;EAEvB,IAAI;GACF,MAAM,gBAAgB,gBAAgB;GACtC,gBAAgB,wBAAwB;IACtC,GAAI,gBACA,EACE,oBAAoB,cAAc,EACpC,IACA,CAAC;IACL,GAAI,oBACA,EACE,WACE,QAAQ,IAAI,aAAa,eACrB,oBAAoB,IACpB,kBACR,IACA,CAAC;IACL,GAAI,iBAAiB,EAAE,eAAe,IAAI,CAAC;GAC7C,CAAC;GACD,UAAU,cAAc,MAAM;EAChC,SAAS,OAAO;GACd,UACE,+BAA+B;IAC7B,MAAM;IACN,QAAQ;IACR,GAAI,iBAAiB,QAAQ,EAAE,MAAM,IAAI,CAAC;GAC5C,CAAC,CACH;EACF;EAEA,aAAa;GACX,eAAe,QAAQ;EACzB;CACF,GAAG;EAAC;EAAe;EAAmB;CAAc,CAAC;CAErD,OACE,oBAAC,sBAAD;EAAsB,GAAK,mBAAmB,EAAE,iBAAiB,IAAI,CAAC;YACpE,oBAAC,iBAAD;GAAyB;GAAS;EAA0B,CAAA;CACxC,CAAA;AAE1B"}

package/dist/_vendor/platform-expo/index.d.ts

@@ -1,70 +1,189 @@
 import { SQLiteDatabase } from "expo-sqlite";
-import * as _syncore_core0 from "../core/index.d.mts";
-import { AnySyncoreSchema, DevtoolsSink, SchedulerOptions, StorageObject, StorageWriteInput, SyncoreCapabilities, SyncoreExperimentalPlugin, SyncoreExternalChangeApplier, SyncoreExternalChangeSignal, SyncoreRuntime, SyncoreRuntimeOptions, SyncoreSqlDriver, SyncoreStorageAdapter } from "../core/index.d.mts";
+import { DevtoolsSink, SchedulerOptions, StorageObject, StorageWriteInput, SyncoreCapabilities, SyncoreDataModel, SyncoreExternalChangeApplier, SyncoreExternalChangeSignal, SyncoreRuntime, SyncoreRuntimeOptions, SyncoreSqlDriver, SyncoreStorageAdapter } from "../core/index.d.mts";
 
 //#region src/index.d.ts
-type ExpoSyncoreSchema = AnySyncoreSchema;
+type ExpoSyncoreSchema<TSchema extends SyncoreDataModel = SyncoreDataModel> = TSchema;
 /**
- * Options for constructing an Expo Syncore runtime.
+ * Options for {@link createExpoSyncoreRuntime}.
  *
- * Use this when you want Syncore to persist locally with `expo-sqlite` and the
- * Expo file system.
+ * On native (iOS/Android) Syncore uses `expo-sqlite` and `expo-file-system`
+ * automatically. When the same app is served on web (via `expo-router` or
+ * Metro’s web bundler) it falls back to the SQL.js + OPFS web stack instead.
+ *
+ * At minimum supply `schema` and `functions`. Everything else has platform
+ * defaults.
+ *
+ * ```ts
+ * const runtime = createExpoSyncoreRuntime({
+ *   schema,
+ *   functions,
+ *   databaseName: "app.db",
+ *   storageDirectoryName: "app-storage",
+ * });
+ * await runtime.start();
+ * ```
  */
-interface CreateExpoRuntimeOptions {
-  /** The schema for the local Syncore app. */
-  schema: ExpoSyncoreSchema;
-  /** The generated function registry for the local Syncore app. */
-  functions: SyncoreRuntimeOptions<ExpoSyncoreSchema>["functions"];
-  /** Optional platform capabilities exposed to function handlers. */
+interface CreateExpoRuntimeOptions<TSchema extends ExpoSyncoreSchema = ExpoSyncoreSchema> {
+  /** The data model that defines the available tables and indexes. */
+  schema: TSchema;
+  /**
+   * The registered function map. Use the `functions` export from
+   * `syncore/_generated/functions.ts`.
+   */
+  functions: SyncoreRuntimeOptions<TSchema>["functions"];
+  /**
+   * Resolved Syncore component instances. Only required when your app
+   * installs Syncore component packages.
+   */
+  components?: SyncoreRuntimeOptions<TSchema>["components"];
+  /**
+   * Platform capabilities injected into `ctx.capabilities` inside function
+   * handlers.
+   */
   capabilities?: SyncoreCapabilities;
-  /** Optional custom SQL driver. Defaults to `expo-sqlite`. */
+  /**
+   * Custom SQL driver. Defaults to an `ExpoSqliteDriver` backed by
+   * `expo-sqlite`.
+   */
   driver?: SyncoreSqlDriver;
-  /** Optional experimental plugins for runtime hooks. */
-  experimentalPlugins?: Array<SyncoreExperimentalPlugin<ExpoSyncoreSchema>>;
-  /** Optional custom file/blob storage adapter. */
+  /** Custom file/blob storage adapter. Defaults to `ExpoFileStorageAdapter`. */
   storage?: SyncoreStorageAdapter;
-  /** The SQLite database filename to open locally. */
+  /**
+   * SQLite database filename (e.g. `"app.db"`). Defaults to `"syncore.db"`.
+   * The file is created inside the app-local documents directory on device.
+   */
   databaseName?: string;
-  /** Optional directory for the SQLite database file. */
+  /**
+   * Absolute path to the directory where the SQLite file is stored.
+   * Defaults to `expo-sqlite`’s `defaultDatabaseDirectory`.
+   */
   databaseDirectory?: string;
-  /** Directory name used for local file/blob storage. */
+  /**
+   * Name of the sub-directory inside the app’s documents folder used for
+   * blob/file storage. Defaults to `"syncore-storage"`.
+   */
   storageDirectoryName?: string;
-  /** Optional runtime platform label shown in devtools snapshots. */
+  /**
+   * Platform label reported to devtools. Defaults to `"expo"`. Override to
+   * `"expo-web"` when running on web.
+   */
   platform?: string;
-  /** Optional devtools sink used during development. */
+  /**
+   * Devtools event sink. Omit to disable devtools. On-device devtools
+   * connections require pointing to your development machine’s IP address.
+   */
   devtools?: DevtoolsSink;
-  /** Optional scheduler configuration for jobs and recurring work. */
+  /** Scheduler configuration for background and recurring jobs. */
   scheduler?: SchedulerOptions;
-  /** Optional shared signal used to synchronize browser instances. */
+  /**
+   * External change signal used to keep multiple in-process instances in sync.
+   * On web, defaults to a `BroadcastChannel`-based signal automatically.
+   */
   externalChangeSignal?: SyncoreExternalChangeSignal;
-  /** Optional applier used to reconcile browser-side external changes. */
+  /**
+   * External change applier used when change events arrive from other tabs or
+   * processes. On web with `ExpoSqliteDriver`, defaults to
+   * `ExpoWebExternalChangeApplier` automatically.
+   */
   externalChangeApplier?: SyncoreExternalChangeApplier;
+  /**
+   * Direct URL to the SQL.js `.wasm` binary. Only needed when the app runs on
+   * web and the default CDN URL is unreachable.
+   */
+  wasmUrl?: string;
+  /**
+   * Resolver for SQL.js support files (`.wasm`, `.worker.js`). Equivalent to
+   * the `locateFile` option in `initSqlJs()`. Only used on web.
+   */
+  locateFile?: (fileName: string) => string;
 }
 /**
- * A reusable bootstrap that lazily creates, starts, and stops an Expo Syncore runtime.
+ * A reusable, lazily-started Expo Syncore runtime handle.
+ *
+ * Created by {@link createExpoSyncoreBootstrap}. The bootstrap defers actual
+ * runtime startup until the first call to `getClient()` and keeps a single
+ * instance alive across React Navigation reloads.
+ *
+ * ```ts
+ * const bootstrap = createExpoSyncoreBootstrap({ schema, functions });
+ *
+ * // In your root component:
+ * const client = await bootstrap.getClient();
+ * ```
  */
-interface ExpoSyncoreBootstrap {
-  /** Synchronous access is unavailable; use `getClient()` instead. */
+interface ExpoSyncoreBootstrap<TSchema extends ExpoSyncoreSchema = ExpoSyncoreSchema> {
+  /** @deprecated Access the runtime via `getClient()` instead. */
   getRuntime(): never;
-  /** Start the runtime if needed and return a ready client. */
-  getClient(): Promise<ReturnType<SyncoreRuntime<ExpoSyncoreSchema>["createClient"]>>;
-  /** Stop the current runtime instance if one exists. */
+  /**
+   * Start the runtime on first call, then return the same client on subsequent
+   * calls. Safe to call from multiple places concurrently.
+   */
+  getClient(): Promise<ReturnType<SyncoreRuntime<TSchema>["createClient"]>>;
+  /** Stop the running runtime instance if one is active. */
   stop(): Promise<void>;
-  /** Fully discard the runtime so the next call recreates it. */
+  /**
+   * Stop and discard the current runtime so the next `getClient()` call
+   * creates a fresh one. Useful after a full app reset or database migration.
+   */
   reset(): Promise<void>;
 }
 /**
- * Create an Expo Syncore runtime backed by `expo-sqlite` and local file storage.
+ * Create a Syncore runtime for Expo (React Native and Expo web) backed by
+ * `expo-sqlite` on native platforms and SQL.js on web.
+ *
+ * Returns an unstarted {@link SyncoreRuntime}. Call `await runtime.start()`
+ * before using the client:
+ *
+ * ```ts
+ * import { createExpoSyncoreRuntime } from "syncorejs/expo";
+ * import schema from "./syncore/schema";
+ * import { functions } from "./syncore/_generated/functions";
+ *
+ * const runtime = createExpoSyncoreRuntime({ schema, functions });
+ * await runtime.start();
+ * const client = runtime.createClient();
+ * ```
+ *
+ * For managed lifecycle in React components, prefer
+ * {@link createExpoSyncoreBootstrap} instead.
  */
-declare function createExpoSyncoreRuntime(options: CreateExpoRuntimeOptions): SyncoreRuntime<ExpoSyncoreSchema>;
+declare function createExpoSyncoreRuntime<TSchema extends ExpoSyncoreSchema>(options: CreateExpoRuntimeOptions<TSchema>): SyncoreRuntime<TSchema>;
 /**
- * Create a same-process Syncore client from a started Expo runtime.
+ * Create a same-process Syncore client directly from a started Expo runtime.
+ *
+ * Prefer this in scripts or non-component code. For React component trees,
+ * use {@link createExpoSyncoreBootstrap} instead to get automatic lifecycle
+ * management.
+ *
+ * ```ts
+ * const client = createExpoSyncoreClient(runtime);
+ * await client.mutation(api.todos.create, { text: "Buy milk" });
+ * ```
  */
-declare function createExpoSyncoreClient(runtime: SyncoreRuntime<ExpoSyncoreSchema>): _syncore_core0.SyncoreClient;
+declare function createExpoSyncoreClient<TSchema extends ExpoSyncoreSchema>(runtime: SyncoreRuntime<TSchema>): import("../core/index.d.mts").SyncoreClient;
 /**
- * Create a reusable Expo bootstrap that lazily starts the local runtime.
+ * Create a reusable Expo bootstrap that lazily starts the local runtime the
+ * first time a client is requested.
+ *
+ * The bootstrap keeps a single runtime instance alive across component
+ * remounts and safely handles concurrent `getClient()` calls.
+ *
+ * ```ts
+ * // app/_layout.tsx
+ * import { createExpoSyncoreBootstrap } from "syncorejs/expo";
+ * import schema from "../syncore/schema";
+ * import { functions } from "../syncore/_generated/functions";
+ *
+ * export const syncoreBootstrap = createExpoSyncoreBootstrap({
+ *   schema,
+ *   functions,
+ * });
+ *
+ * // Later in SyncoreProvider:
+ * const client = await syncoreBootstrap.getClient();
+ * ```
  */
-declare function createExpoSyncoreBootstrap(options: CreateExpoRuntimeOptions): ExpoSyncoreBootstrap;
+declare function createExpoSyncoreBootstrap<TSchema extends ExpoSyncoreSchema>(options: CreateExpoRuntimeOptions<TSchema>): ExpoSyncoreBootstrap<TSchema>;
 /**
  * Syncore SQL driver implementation backed by `expo-sqlite`.
  */