@livestore/react 0.4.0-dev.20 → 0.4.0-dev.22

package/dist/useStore.js

@@ -1,7 +1,79 @@
 import React from 'react';
-import { LiveStoreContext } from "./LiveStoreContext.js";
+import { useStoreRegistry } from "./StoreRegistryContext.js";
 import { useClientDocument } from "./useClientDocument.js";
 import { useQuery } from "./useQuery.js";
+/**
+ * Returns a store instance augmented with hooks (`store.useQuery()` and `store.useClientDocument()`) for reactive queries.
+ *
+ * @example
+ * ```tsx
+ * function Issue() {
+ *   // Suspends until loaded or returns immediately if already loaded
+ *   const issueStore = useStore(issueStoreOptions('abc123'))
+ *   const [issue] = issueStore.useQuery(queryDb(tables.issue.select()))
+ *
+ *   const toggleStatus = () =>
+ *     issueStore.commit(
+ *       issueEvents.issueStatusChanged({
+ *         id: issue.id,
+ *         status: issue.status === 'done' ? 'todo' : 'done',
+ *       }),
+ *     )
+ *
+ *   const preloadParentIssue = (issueId: string) =>
+ *     storeRegistry.preload({
+ *       ...issueStoreOptions(issueId),
+ *       unusedCacheTime: 10_000,
+ *     })
+ *
+ *   return (
+ *     <>
+ *       <h2>{issue.title}</h2>
+ *       <button onClick={() => toggleStatus()}>Toggle Status</button>
+ *       <button onMouseEnter={() => preloadParentIssue(issue.parentIssueId)}>Open Parent Issue</button>
+ *     </>
+ *   )
+ * }
+ * ```
+ *
+ * @remarks
+ * - Suspends until the store is loaded.
+ * - Store is cached by its `storeId` in the `StoreRegistry`. Multiple calls with the same `storeId` return the same store instance.
+ * - Store is cached as long as it's being used, and after `unusedCacheTime` expires (default `60_000` ms in browser, `Infinity` in non-browser)
+ * - Default store options can be configured in `StoreRegistry` constructor.
+ * - Store options are only applied when the store is loaded. Subsequent calls with different options will not affect the store if it's already loaded and cached in the registry.
+ *
+ * @typeParam TSchema - The schema type for the store
+ * @returns The loaded store instance augmented with React hooks
+ * @throws unknown - store loading error or if called outside `<StoreRegistryProvider>`
+ */
+export const useStore = (options) => {
+    const storeRegistry = useStoreRegistry();
+    // NOTE: retain() is called in useEffect (after render), while getOrLoadPromise() is called
+    // in useMemo (during render). This creates a timing gap where with very short unusedCacheTime
+    // values (e.g., 0), the store could theoretically be disposed before the effect fires.
+    // In practice, this is not an issue with the default 60s cache time, but it becomes an issue when
+    // `unusedCacheTime` is configured to values less than ~100ms.
+    // See https://github.com/livestorejs/livestore/issues/916
+    React.useEffect(() => storeRegistry.retain(options), [storeRegistry, options]);
+    const storeOrPromise = React.useMemo(() => storeRegistry.getOrLoadPromise(options), [storeRegistry, options]);
+    const store = storeOrPromise instanceof Promise ? React.use(storeOrPromise) : storeOrPromise;
+    // Expose store on the global object for browser console debugging.
+    globalThis.__debugLiveStore ??= {};
+    if (Object.keys(globalThis.__debugLiveStore).length === 0) {
+        globalThis.__debugLiveStore._ = store;
+    }
+    globalThis.__debugLiveStore[options.debug?.instanceId ?? options.storeId] = store;
+    return withReactApi(store);
+};
+/**
+ * Augments a Store instance with React-specific methods (`useQuery`, `useClientDocument`).
+ *
+ * This is called automatically by `useStore()`. You typically don't need to call it
+ * directly unless you're building custom integrations.
+ *
+ * @internal
+ */
 export const withReactApi = (store) => {
     // @ts-expect-error TODO properly implement this
     store.useQuery = (queryable) => useQuery(queryable, { store });
@@ -9,18 +81,4 @@ export const withReactApi = (store) => {
     store.useClientDocument = (table, idOrOptions, options) => useClientDocument(table, idOrOptions, options, { store });
     return store;
 };
-export const useStore = (options) => {
-    if (options?.store !== undefined) {
-        return { store: withReactApi(options.store) };
-    }
-    // biome-ignore lint/correctness/useHookAtTopLevel: store is stable
-    const storeContext = React.useContext(LiveStoreContext);
-    if (storeContext === undefined) {
-        throw new Error(`useStore can only be used inside StoreContext.Provider`);
-    }
-    if (storeContext.stage !== 'running') {
-        throw new Error(`useStore can only be used after the store is running`);
-    }
-    return { store: withReactApi(storeContext.store) };
-};
 //# sourceMappingURL=useStore.js.map

package/dist/useStore.js.map

@@ -1 +1 @@
-{"version":3,"file":"useStore.js","sourceRoot":"","sources":["../src/useStore.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,OAAO,CAAA;AAGzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC,MAAM,CAAC,MAAM,YAAY,GAAG,CAAkC,KAAqB,EAA6B,EAAE;IAChH,gDAAgD;IAEhD,KAAK,CAAC,QAAQ,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;IAC9D,gDAAgD;IAEhD,KAAK,CAAC,iBAAiB,GAAG,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;IACpH,OAAO,KAAkC,CAAA;AAC3C,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,OAA2B,EAA+B,EAAE;IACnF,IAAI,OAAO,EAAE,KAAK,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAA;IAC/C,CAAC;IAED,mEAAmE;IACnE,MAAM,YAAY,GAAG,KAAK,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAA;IAEvD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAA;IAC3E,CAAC;IAED,IAAI,YAAY,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAA;IACzE,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAA;AACpD,CAAC,CAAA"}
+{"version":3,"file":"useStore.js","sourceRoot":"","sources":["../src/useStore.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,MAAM,OAAO,CAAA;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA4B,CAAA;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAKtB,OAAoE,EAC/B,EAAE;IACvC,MAAM,aAAa,GAAG,gBAAgB,EAAE,CAAA;IAExC,2FAA2F;IAC3F,8FAA8F;IAC9F,uFAAuF;IACvF,kGAAkG;IAClG,8DAA8D;IAC9D,0DAA0D;IAC1D,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,aAAa,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC,CAAA;IAE9E,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,aAAa,CAAC,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC,CAAA;IAE7G,MAAM,KAAK,GAAG,cAAc,YAAY,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc,CAAA;IAE5F,mEAAmE;IACnE,UAAU,CAAC,gBAAgB,KAAK,EAAE,CAAA;IAClC,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1D,UAAU,CAAC,gBAAgB,CAAC,CAAC,GAAG,KAAK,CAAA;IACvC,CAAC;IACD,UAAU,CAAC,gBAAgB,CAAC,OAAO,CAAC,KAAK,EAAE,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,KAAK,CAAA;IAEjF,OAAO,YAAY,CAAC,KAAK,CAAC,CAAA;AAC5B,CAAC,CAAA;AAgBD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,KAA+B,EACM,EAAE;IACvC,gDAAgD;IAChD,KAAK,CAAC,QAAQ,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;IAE9D,gDAAgD;IAChD,KAAK,CAAC,iBAAiB,GAAG,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;IACpH,OAAO,KAA4C,CAAA;AACrD,CAAC,CAAA"}

package/dist/useStore.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStore.test.d.ts","sourceRoot":"","sources":["../src/useStore.test.tsx"],"names":[],"mappings":""}

package/dist/useStore.test.js

@@ -0,0 +1,196 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { makeInMemoryAdapter } from '@livestore/adapter-web';
+import { StoreInternalsSymbol, StoreRegistry, storeOptions, } from '@livestore/livestore';
+import { shouldNeverHappen } from '@livestore/utils';
+import { act, render, renderHook, waitFor } from '@testing-library/react';
+import * as React from 'react';
+import { describe, expect, it } from 'vitest';
+import { schema } from "./__tests__/fixture.js";
+import { StoreRegistryProvider } from "./StoreRegistryContext.js";
+import { useStore } from "./useStore.js";
+describe('experimental useStore', () => {
+    it('should return the same promise instance for concurrent getOrLoadStore calls', async () => {
+        const storeRegistry = new StoreRegistry();
+        const options = testStoreOptions();
+        // Make two concurrent calls during loading
+        const firstStore = storeRegistry.getOrLoadPromise(options);
+        const secondStore = storeRegistry.getOrLoadPromise(options);
+        // Both should be promises (store is loading)
+        expect(firstStore).toBeInstanceOf(Promise);
+        expect(secondStore).toBeInstanceOf(Promise);
+        // EXPECTED BEHAVIOR: Same promise instance for React.use() compatibility
+        // ACTUAL BEHAVIOR: Different promise instances (Effect.runPromise creates new wrapper)
+        expect(firstStore).toBe(secondStore);
+        // Cleanup
+        await firstStore;
+        await cleanupAfterUnmount(() => { });
+    });
+    it('works with Suspense boundary', async () => {
+        const storeRegistry = new StoreRegistry();
+        const options = testStoreOptions();
+        let view;
+        await act(async () => {
+            view = render(_jsx(StoreRegistryProvider, { storeRegistry: storeRegistry, children: _jsx(React.Suspense, { fallback: _jsx("div", { "data-testid": "fallback" }), children: _jsx(StoreConsumer, { options: options }) }) }));
+        });
+        const renderedView = view ?? shouldNeverHappen('render failed');
+        // After loading completes, should show the actual content
+        await waitForSuspenseResolved(renderedView);
+        expect(renderedView.getByTestId('ready')).toBeDefined();
+        await cleanupAfterUnmount(() => renderedView.unmount());
+    });
+    it('does not re-suspend on subsequent renders when store is already loaded', async () => {
+        const storeRegistry = new StoreRegistry();
+        const options = testStoreOptions();
+        const Wrapper = ({ opts }) => (_jsx(StoreRegistryProvider, { storeRegistry: storeRegistry, children: _jsx(React.Suspense, { fallback: _jsx("div", { "data-testid": "fallback" }), children: _jsx(StoreConsumer, { options: opts }) }) }));
+        let view;
+        await act(async () => {
+            view = render(_jsx(Wrapper, { opts: options }));
+        });
+        const renderedView = view ?? shouldNeverHappen('render failed');
+        // Wait for initial load
+        await waitForSuspenseResolved(renderedView);
+        expect(renderedView.getByTestId('ready')).toBeDefined();
+        // Rerender with new options object (but same storeId)
+        await act(async () => {
+            renderedView.rerender(_jsx(Wrapper, { opts: { ...options } }));
+        });
+        // Should not show fallback
+        expect(renderedView.queryByTestId('fallback')).toBeNull();
+        expect(renderedView.getByTestId('ready')).toBeDefined();
+        await cleanupAfterUnmount(() => renderedView.unmount());
+    });
+    it('throws when store loading fails', async () => {
+        const storeRegistry = new StoreRegistry();
+        const badOptions = testStoreOptions({
+            // @ts-expect-error - intentionally passing invalid adapter to trigger error
+            adapter: null,
+        });
+        // Pre-load the store to cache the error (error happens synchronously)
+        expect(() => storeRegistry.getOrLoadPromise(badOptions)).toThrow();
+        // Now when useStore tries to get it, it should throw synchronously
+        expect(() => renderHook(() => useStore(badOptions), {
+            wrapper: makeProvider(storeRegistry),
+        })).toThrow();
+    });
+    it.each([
+        { label: 'non-strict mode', strictMode: false },
+        { label: 'strict mode', strictMode: true },
+    ])('works in $label', async ({ strictMode }) => {
+        const storeRegistry = new StoreRegistry();
+        const options = testStoreOptions();
+        let hook;
+        await act(async () => {
+            hook = renderHook(() => useStore(options), {
+                wrapper: makeProvider(storeRegistry, { suspense: true }),
+                reactStrictMode: strictMode,
+            });
+        });
+        const { result, unmount } = hook ?? shouldNeverHappen('renderHook failed');
+        // Wait for store to be ready
+        await waitForStoreReady(result);
+        expect(result.current[StoreInternalsSymbol].clientSession).toBeDefined();
+        await cleanupAfterUnmount(unmount);
+    });
+    it('handles switching between different storeId values', async () => {
+        const storeRegistry = new StoreRegistry();
+        const optionsA = testStoreOptions({ storeId: 'store-a' });
+        const optionsB = testStoreOptions({ storeId: 'store-b' });
+        let hook;
+        await act(async () => {
+            hook = renderHook((opts) => useStore(opts), {
+                initialProps: optionsA,
+                wrapper: makeProvider(storeRegistry, { suspense: true }),
+            });
+        });
+        const { result, rerender, unmount } = hook ?? shouldNeverHappen('renderHook failed');
+        // Wait for first store to load
+        await waitForStoreReady(result);
+        const storeA = result.current;
+        expect(storeA[StoreInternalsSymbol].clientSession).toBeDefined();
+        // Switch to different storeId
+        await act(async () => {
+            rerender(optionsB);
+        });
+        // Wait for second store to load and verify it's different from the first
+        await waitFor(() => {
+            expect(result.current).not.toBe(storeA);
+            expect(result.current?.[StoreInternalsSymbol].clientSession).toBeDefined();
+        });
+        const storeB = result.current;
+        expect(storeB[StoreInternalsSymbol].clientSession).toBeDefined();
+        expect(storeB).not.toBe(storeA);
+        await cleanupAfterUnmount(unmount);
+    });
+    // useStore doesn't handle unusedCacheTime=0 correctly because retain is called in useEffect (after render)
+    // See https://github.com/livestorejs/livestore/issues/916
+    it.skip('should load store with unusedCacheTime set to 0', async () => {
+        const storeRegistry = new StoreRegistry({ defaultOptions: { unusedCacheTime: 0 } });
+        const options = testStoreOptions({ unusedCacheTime: 0 });
+        const StoreConsumerWithVerification = ({ opts }) => {
+            const store = useStore(opts);
+            // Verify store is usable - access internals to confirm it's not disposed
+            const clientSession = store[StoreInternalsSymbol].clientSession;
+            return _jsx("div", { "data-testid": "ready", "data-has-session": String(clientSession !== undefined) });
+        };
+        let view;
+        await act(async () => {
+            view = render(_jsx(StoreRegistryProvider, { storeRegistry: storeRegistry, children: _jsx(React.Suspense, { fallback: _jsx("div", { "data-testid": "fallback" }), children: _jsx(StoreConsumerWithVerification, { opts: options }) }) }));
+        });
+        const renderedView = view ?? shouldNeverHappen('render failed');
+        await waitForSuspenseResolved(renderedView);
+        // Store should be usable while component is mounted
+        const readyElement = renderedView.getByTestId('ready');
+        expect(readyElement.getAttribute('data-has-session')).toBe('true');
+        // Allow some time to pass to ensure store isn't prematurely disposed
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        // Store should still be usable after waiting
+        expect(readyElement.getAttribute('data-has-session')).toBe('true');
+        await cleanupAfterUnmount(() => renderedView.unmount());
+    });
+});
+const StoreConsumer = ({ options }) => {
+    useStore(options);
+    return _jsx("div", { "data-testid": "ready" });
+};
+const makeProvider = (storeRegistry, { suspense = false } = {}) => ({ children }) => {
+    let content = _jsx(StoreRegistryProvider, { storeRegistry: storeRegistry, children: children });
+    if (suspense) {
+        content = _jsx(React.Suspense, { fallback: null, children: content });
+    }
+    return content;
+};
+let testStoreCounter = 0;
+const testStoreOptions = (overrides = {}) => storeOptions({
+    storeId: overrides.storeId ?? `test-store-${testStoreCounter++}`,
+    schema,
+    adapter: makeInMemoryAdapter(),
+    ...overrides,
+});
+/**
+ * Cleans up after component unmount and waits for pending operations to settle.
+ *
+ * When components using stores unmount, the StoreRegistry schedules garbage collection
+ * timers for inactive stores. This helper waits for those timers to complete naturally.
+ */
+const cleanupAfterUnmount = async (cleanup) => {
+    cleanup();
+    // Allow any pending microtasks/timers to settle
+    await new Promise((resolve) => setTimeout(resolve, 100));
+};
+/**
+ * Waits for React Suspense fallback to resolve and the actual content to render.
+ */
+const waitForSuspenseResolved = async (view) => {
+    await waitFor(() => expect(view.queryByTestId('fallback')).toBeNull());
+};
+/**
+ * Waits for a store to be fully loaded and ready to use.
+ * The store is considered ready when it has a defined clientSession.
+ */
+const waitForStoreReady = async (result) => {
+    await waitFor(() => {
+        expect(result.current).not.toBeNull();
+        expect(result.current[StoreInternalsSymbol].clientSession).toBeDefined();
+    });
+};
+//# sourceMappingURL=useStore.test.js.map

package/dist/useStore.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStore.test.js","sourceRoot":"","sources":["../src/useStore.test.tsx"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livestore/react",
-  "version": "0.4.0-dev.20",
+  "version": "0.4.0-dev.22",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -9,12 +9,12 @@
   },
   "dependencies": {
     "@opentelemetry/api": "1.9.0",
-    "@livestore/common": "0.4.0-dev.20",
-    "@livestore/livestore": "0.4.0-dev.20",
-    "@livestore/utils": "0.4.0-dev.20"
+    "@livestore/common": "0.4.0-dev.22",
+    "@livestore/livestore": "0.4.0-dev.22",
+    "@livestore/utils": "0.4.0-dev.22"
   },
   "devDependencies": {
-    "@opentelemetry/sdk-trace-base": "2.0.1",
+    "@opentelemetry/sdk-trace-base": "2.2.0",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.0",
     "@types/react": "19.1.13",
@@ -26,8 +26,8 @@
     "typescript": "5.9.2",
     "vite": "7.2.4",
     "vitest": "3.2.4",
-    "@livestore/utils-dev": "0.4.0-dev.20",
-    "@livestore/adapter-web": "0.4.0-dev.20"
+    "@livestore/utils-dev": "0.4.0-dev.22",
+    "@livestore/adapter-web": "0.4.0-dev.22"
   },
   "files": [
     "package.json",

package/src/StoreRegistryContext.tsx

@@ -0,0 +1,69 @@
+import type { StoreRegistry } from '@livestore/livestore'
+import * as React from 'react'
+
+export const StoreRegistryContext = React.createContext<StoreRegistry | undefined>(undefined)
+
+export type StoreRegistryProviderProps = {
+  storeRegistry: StoreRegistry
+  children: React.ReactNode
+}
+
+/**
+ * React context provider that makes a {@link StoreRegistry} available to descendant components.
+ *
+ * Wrap your application (or a subtree) with this provider to enable {@link useStore} and
+ * {@link useStoreRegistry} hooks within that tree.
+ *
+ * @example
+ * ```tsx
+ * import { StoreRegistry } from '@livestore/livestore'
+ * import { StoreRegistryProvider } from '@livestore/react'
+ * import { unstable_batchedUpdates as batchUpdates } from 'react-dom'
+ *
+ * const storeRegistry = new StoreRegistry({
+ *   defaultOptions: { batchUpdates }
+ * })
+ *
+ * function App() {
+ *   return (
+ *     <StoreRegistryProvider storeRegistry={storeRegistry}>
+ *       <MyComponent />
+ *     </StoreRegistryProvider>
+ *   )
+ * }
+ * ```
+ */
+export const StoreRegistryProvider = ({ storeRegistry, children }: StoreRegistryProviderProps): React.JSX.Element => {
+  return <StoreRegistryContext value={storeRegistry}>{children}</StoreRegistryContext>
+}
+
+/**
+ * Hook to access the {@link StoreRegistry} from context. Useful for advanced operations like preloading.
+ *
+ * @param override - Optional registry to use instead of the context value.
+ *   When provided, skips context lookup entirely.
+ * @returns The registry provided by the nearest {@link StoreRegistryProvider} ancestor, or the `override` if provided.
+ * @throws Error if called outside a {@link StoreRegistryProvider} and no override is provided
+ *
+ * @example
+ * ```tsx
+ * function PreloadButton({ issueId }: { issueId: string }) {
+ *   const storeRegistry = useStoreRegistry()
+ *
+ *   const handleMouseEnter = () => {
+ *     storeRegistry.preload(issueStoreOptions(issueId))
+ *   }
+ *
+ *   return <button onMouseEnter={handleMouseEnter}>View Issue</button>
+ * }
+ * ```
+ */
+export const useStoreRegistry = (override?: StoreRegistry) => {
+  if (override) return override
+
+  const storeRegistry = React.use(StoreRegistryContext)
+
+  if (!storeRegistry) throw new Error('useStoreRegistry() must be used within <StoreRegistryProvider>')
+
+  return storeRegistry
+}

package/src/__tests__/fixture.tsx

@@ -136,21 +136,9 @@ export const makeTodoMvcReact: (opts?: MakeTodoMvcReactOptions) => Effect.Effect
 
     const storeWithReactApi = LiveStoreReact.withReactApi(store)
 
-    // TODO improve typing of `LiveStoreContext`
-    const storeContext = {
-      stage: 'running' as const,
-      store: storeWithReactApi,
-    }
-
     const MaybeStrictMode = strictMode ? React.StrictMode : React.Fragment
 
-    const wrapper = ({ children }: any) => (
-      <MaybeStrictMode>
-        <LiveStoreReact.LiveStoreContext.Provider value={storeContext}>
-          {children}
-        </LiveStoreReact.LiveStoreContext.Provider>
-      </MaybeStrictMode>
-    )
+    const wrapper = ({ children }: any) => <MaybeStrictMode>{children}</MaybeStrictMode>
 
     const renderCount = makeRenderCount()
 

package/src/experimental/components/LiveList.tsx

@@ -1,4 +1,4 @@
-import type { LiveQueryDef } from '@livestore/livestore'
+import type { LiveQueryDef, Store } from '@livestore/livestore'
 import { computed } from '@livestore/livestore'
 import React from 'react'
 
@@ -16,6 +16,8 @@ export type LiveListProps<TItem> = {
   renderItem: (item: TItem, opts: { index: number; isInitialListRender: boolean }) => React.ReactNode
   /** Needs to be unique across all list items */
   getKey: (item: TItem, index: number) => string | number
+  /** The store instance to use for queries */
+  store: Store<any, any>
 }
 
 /**
@@ -26,12 +28,15 @@ export type LiveListProps<TItem> = {
  * In the future we want to make this component even more efficient by using incremental rendering (https://github.com/livestorejs/livestore/pull/55)
  * e.g. when an item is added/removed/moved to only re-render the affected DOM nodes.
  */
-export const LiveList = <TItem,>({ items$, renderItem, getKey }: LiveListProps<TItem>): React.ReactNode => {
+export const LiveList = <TItem,>({ items$, renderItem, getKey, store }: LiveListProps<TItem>): React.ReactNode => {
   const [hasMounted, setHasMounted] = React.useState(false)
 
   React.useEffect(() => setHasMounted(true), [])
 
-  const keys = useQuery(computed((get) => get(items$).map(getKey)))
+  const keys = useQuery(
+    computed((get) => get(items$).map(getKey)),
+    { store },
+  )
   const arr = React.useMemo(
     () =>
       keys.map(
@@ -54,6 +59,7 @@ export const LiveList = <TItem,>({ items$, renderItem, getKey }: LiveListProps<T
           key={key}
           itemKey={key}
           item$={item$}
+          store={store}
           opts={{ isInitialListRender: !hasMounted, index }}
           renderItem={renderItem}
         />
@@ -66,13 +72,15 @@ const ItemWrapper = <TItem,>({
   item$,
   opts,
   renderItem,
+  store,
 }: {
   itemKey: string | number
   item$: LiveQueryDef<TItem>
   opts: { index: number; isInitialListRender: boolean }
   renderItem: (item: TItem, opts: { index: number; isInitialListRender: boolean }) => React.ReactNode
+  store: Store<any, any>
 }) => {
-  const item = useQuery(item$)
+  const item = useQuery(item$, { store })
 
   return <>{renderItem(item, opts)}</>
 }
@@ -82,6 +90,7 @@ const ItemWrapperMemo = React.memo(
   (prev, next) =>
     prev.itemKey === next.itemKey &&
     prev.renderItem === next.renderItem &&
+    prev.store === next.store &&
     prev.opts.index === next.opts.index &&
     prev.opts.isInitialListRender === next.opts.isInitialListRender,
 ) as typeof ItemWrapper

package/src/experimental/mod.ts

@@ -1,2 +1 @@
 export { LiveList, type LiveListProps } from './components/LiveList.tsx'
-export * from './multi-store/mod.ts'

package/src/mod.ts

@@ -1,5 +1,6 @@
-export { LiveStoreContext, type ReactApi } from './LiveStoreContext.ts'
-export { LiveStoreProvider } from './LiveStoreProvider.tsx'
+export { StoreRegistry, storeOptions } from '@livestore/livestore'
+export { LiveList, type LiveListProps } from './experimental/components/LiveList.tsx'
+export * from './StoreRegistryContext.tsx'
 export {
   type Dispatch,
   type SetStateAction,
@@ -9,5 +10,5 @@ export {
   useClientDocument,
 } from './useClientDocument.ts'
 export { useQuery, useQueryRef } from './useQuery.ts'
-export { useStore, withReactApi } from './useStore.ts'
+export { type ReactApi, useStore, withReactApi } from './useStore.ts'
 export { useStackInfo } from './utils/stack-info.ts'

package/src/useClientDocument.ts

@@ -6,9 +6,19 @@ import { queryDb } from '@livestore/livestore'
 import { omitUndefineds, shouldNeverHappen } from '@livestore/utils'
 import React from 'react'
 
-import { LiveStoreContext } from './LiveStoreContext.ts'
 import { useQueryRef } from './useQuery.ts'
 
+/**
+ * Return type of `useClientDocument` hook.
+ *
+ * A tuple providing React-style state access to a client-document table row:
+ * - `[0]` row: The current value (decoded according to the table schema)
+ * - `[1]` setRow: Setter function to update the document
+ * - `[2]` id: The document's ID (resolved from `SessionIdSymbol` if applicable)
+ * - `[3]` query$: The underlying `LiveQuery` for advanced use cases
+ *
+ * @typeParam TTableDef - The client-document table definition type
+ */
 export type UseClientDocumentResult<TTableDef extends State.SQLite.ClientDocumentTableDef.TraitAny> = [
   row: TTableDef['Value'],
   setRow: StateSetters<TTableDef>,
@@ -104,10 +114,7 @@ export const useClientDocument: {
 
   const tableName = table.sqliteDef.name
 
-  const store =
-    storeArg?.store ?? // biome-ignore lint/correctness/useHookAtTopLevel: store is stable
-    React.useContext(LiveStoreContext)?.store ??
-    shouldNeverHappen(`No store provided to useClientDocument`)
+  const store = storeArg?.store ?? shouldNeverHappen(`No store provided to useClientDocument`)
 
   // console.debug('useClientDocument', tableName, id)
 
@@ -140,10 +147,34 @@ export const useClientDocument: {
   return [queryRef.valueRef.current, setState, idStr, queryRef.queryRcRef.value]
 }
 
+/**
+ * A function that dispatches an action. Mirrors React's `Dispatch` type.
+ * @typeParam A - The action type
+ */
 export type Dispatch<A> = (action: A) => void
+
+/**
+ * A state update that can be either a partial value or a function returning a partial value.
+ * Used when the client-document table has `partialSet: true`.
+ * @typeParam S - The state type
+ */
 export type SetStateActionPartial<S> = Partial<S> | ((previousValue: S) => Partial<S>)
+
+/**
+ * A state update that can be either a full value or a function returning a full value.
+ * Mirrors React's `SetStateAction` type.
+ * @typeParam S - The state type
+ */
 export type SetStateAction<S> = S | ((previousValue: S) => S)
 
+/**
+ * The setter function type for `useClientDocument`, determined by the table's `partialSet` option.
+ *
+ * - If `partialSet: false` (default), requires full state replacement
+ * - If `partialSet: true`, accepts partial updates merged with existing state
+ *
+ * @typeParam TTableDef - The client-document table definition type
+ */
 export type StateSetters<TTableDef extends State.SQLite.ClientDocumentTableDef.TraitAny> = Dispatch<
   TTableDef[State.SQLite.ClientDocumentTableDefSymbol]['options']['partialSet'] extends false
     ? SetStateAction<TTableDef['Value']>

package/src/useQuery.ts

@@ -14,7 +14,6 @@ import { deepEqual, indent, shouldNeverHappen } from '@livestore/utils'
 import * as otel from '@opentelemetry/api'
 import React from 'react'
 
-import { LiveStoreContext } from './LiveStoreContext.ts'
 import { useRcResource } from './useRcResource.ts'
 import { originalStackLimit } from './utils/stack-info.ts'
 import { useStateRefWithReactiveInput } from './utils/useStateRefWithReactiveInput.ts'
@@ -49,7 +48,7 @@ export const useQuery = <TQueryable extends Queryable<any>>(
  *
  * Parameters
  * - `queryable`: The query definition/instance/builder to run and subscribe to.
- * - `options.store`: Optional store to use; by default the store from `LiveStoreContext` is used.
+ * - `options.store`: The store to use. Required when calling `useQueryRef` directly; automatically provided when using `store.useQuery()`.
  * - `options.otelContext`: Optional parent otel context for the query span.
  * - `options.otelSpanName`: Optional explicit span name; otherwise derived from the query label.
  *
@@ -71,10 +70,7 @@ export const useQueryRef = <TQueryable extends Queryable<any>>(
   valueRef: React.RefObject<Queryable.Result<TQueryable>>
   queryRcRef: LiveQueries.RcRef<LiveQuery<Queryable.Result<TQueryable>>>
 } => {
-  const store =
-    options?.store ?? // biome-ignore lint/correctness/useHookAtTopLevel: store is stable
-    React.useContext(LiveStoreContext)?.store ??
-    shouldNeverHappen(`No store provided to useQuery`)
+  const store = options?.store ?? shouldNeverHappen(`No store provided to useQuery`)
 
   type TResult = Queryable.Result<TQueryable>
   type NormalizedQueryable =