@livestore/react 0.4.0-dev.8 → 0.4.0

package/dist/useStore.d.ts

@@ -1,9 +1,76 @@
-import type { Store } from '@livestore/livestore';
-import type { ReactApi } from './LiveStoreContext.ts';
-export declare const withReactApi: (store: Store) => Store & ReactApi;
-export declare const useStore: (options?: {
-    store?: Store;
-}) => {
-    store: Store & ReactApi;
+import type { LiveStoreSchema } from '@livestore/common/schema';
+import type { RegistryStoreOptions, Store, SyncStatus } from '@livestore/livestore';
+import type { Schema } from '@livestore/utils/effect';
+import { useClientDocument } from './useClientDocument.ts';
+import { useQuery } from './useQuery.ts';
+/**
+ * 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 declare const useStore: <TSchema extends LiveStoreSchema, TContext = {}, TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue>(options: RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema>) => Store<TSchema, TContext> & ReactApi;
+/**
+ * React-specific methods added to the Store when used via React hooks.
+ *
+ * These methods are attached by `withReactApi()` and `useStore()`, allowing you
+ * to call `store.useQuery()` and `store.useClientDocument()` directly on the
+ * Store instance.
+ */
+export type ReactApi = {
+    /** Hook version of query subscription—re-renders component when query result changes */
+    useQuery: typeof useQuery;
+    /** Hook for reading and writing client-document tables with React state semantics */
+    useClientDocument: typeof useClientDocument;
+    /** Hook for subscribing to sync status changes */
+    useSyncStatus: () => SyncStatus;
 };
+/**
+ * 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 declare const withReactApi: <TSchema extends LiveStoreSchema, TContext = {}>(store: Store<TSchema, TContext>) => Store<TSchema, TContext> & ReactApi;
 //# sourceMappingURL=useStore.d.ts.map

package/dist/useStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useStore.d.ts","sourceRoot":"","sources":["../src/useStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAA;AAGjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAKrD,eAAO,MAAM,YAAY,GAAI,OAAO,KAAK,KAAG,KAAK,GAAG,QAQnD,CAAA;AAED,eAAO,MAAM,QAAQ,GAAI,UAAU;IAAE,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,KAAG;IAAE,KAAK,EAAE,KAAK,GAAG,QAAQ,CAAA;CAiB/E,CAAA"}
+{"version":3,"file":"useStore.d.ts","sourceRoot":"","sources":["../src/useStore.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAC/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACnF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAGrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAGxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,QAAQ,GACnB,OAAO,SAAS,eAAe,EAC/B,QAAQ,GAAG,EAAE,EACb,kBAAkB,SAAS,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,OAAO,MAAM,CAAC,SAAS,EAEvE,SAAS,oBAAoB,CAAC,OAAO,EAAE,QAAQ,EAAE,kBAAkB,CAAC,KACnE,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,GAAG,QA2B7B,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,wFAAwF;IACxF,QAAQ,EAAE,OAAO,QAAQ,CAAA;IACzB,qFAAqF;IACrF,iBAAiB,EAAE,OAAO,iBAAiB,CAAA;IAC3C,kDAAkD;IAClD,aAAa,EAAE,MAAM,UAAU,CAAA;CAChC,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,SAAS,eAAe,EAAE,QAAQ,GAAG,EAAE,EACzE,OAAO,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,KAC9B,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,GAAG,QAW7B,CAAA"}

package/dist/useStore.js

@@ -1,26 +1,92 @@
 import React from 'react';
-import { LiveStoreContext } from "./LiveStoreContext.js";
+import { useStoreRegistry } from "./StoreRegistryContext.js";
 import { useClientDocument } from "./useClientDocument.js";
 import { useQuery } from "./useQuery.js";
+import { useSyncStatus } from "./useSyncStatus.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();
+    // Called on every render (intentionally not memoized). For already-loaded stores this returns
+    // the Store synchronously, so React.use() is skipped entirely. Caching the initial Promise via
+    // useMemo would cause React.use() to be called with a resolved Promise on subsequent renders,
+    // which blocks React transitions from committing.
+    const storeOrPromise = storeRegistry.getOrLoadPromise(options);
+    const store = storeOrPromise instanceof Promise ? React.use(storeOrPromise) : storeOrPromise;
+    // NOTE: retain() must be declared AFTER the React.use() call above. When React.use() suspends
+    // the component, any hooks declared before it get committed while hooks after the suspension
+    // point (including those in the caller) don't. On re-render when the store resolves synchronously,
+    // those late hooks appear for the first time, causing a hook-order violation in strict mode.
+    // By placing useEffect after React.use(), no effect hooks are committed during suspension,
+    // so React treats all effects as fresh mounts on the first successful render.
+    //
+    // retain() is called in useEffect (after render), while getOrLoadPromise() is called 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]);
+    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 = (queryDef) => useQuery(queryDef, { store });
+    store.useQuery = (queryable) => useQuery(queryable, { store });
     // @ts-expect-error TODO properly implement this
     store.useClientDocument = (table, idOrOptions, options) => useClientDocument(table, idOrOptions, options, { store });
+    // @ts-expect-error TODO properly implement this
+    store.useSyncStatus = () => useSyncStatus({ 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":"AACA,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,CAAC,KAAY,EAAoB,EAAE;IAC7D,gDAAgD;IAEhD,KAAK,CAAC,QAAQ,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;IAC5D,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,KAAyB,CAAA;AAClC,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":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAMzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA4B,CAAA;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAKtB,OAAoE,EAC/B,EAAE;IACvC,MAAM,aAAa,GAAG,gBAAgB,EAAE,CAAA;IAExC,8FAA8F;IAC9F,+FAA+F;IAC/F,8FAA8F;IAC9F,kDAAkD;IAClD,MAAM,cAAc,GAAG,aAAa,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAE9D,MAAM,KAAK,GAAG,cAAc,YAAY,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc,CAAA;IAE5F,8FAA8F;IAC9F,6FAA6F;IAC7F,mGAAmG;IACnG,6FAA6F;IAC7F,2FAA2F;IAC3F,8EAA8E;IAC9E,EAAE;IACF,4FAA4F;IAC5F,4FAA4F;IAC5F,8FAA8F;IAC9F,8FAA8F;IAC9F,yCAAyC;IACzC,0DAA0D;IAC1D,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,aAAa,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC,CAAA;IAE9E,OAAO,YAAY,CAAC,KAAK,CAAC,CAAA;AAC5B,CAAC,CAAA;AAkBD;;;;;;;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;IAEpH,gDAAgD;IAChD,KAAK,CAAC,aAAa,GAAG,GAAG,EAAE,CAAC,aAAa,CAAC,EAAE,KAAK,EAAE,CAAC,CAAA;IAEpD,OAAO,KAA4C,CAAA;AACrD,CAAC,CAAA"}

package/dist/useStore.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=useStore.test.d.ts.map

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,241 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { makeInMemoryAdapter } from '@livestore/adapter-web';
+import { StoreInternalsSymbol, StoreRegistry, storeOptions, } from '@livestore/livestore';
+import { shouldNeverHappen } from '@livestore/utils';
+import { act, fireEvent, render, renderHook, waitFor } from '@testing-library/react';
+import * as React from 'react';
+import { describe, expect, it, vi } 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: makeSuspenseFallback(), 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: makeSuspenseFallback(), 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)
+        const rerenderOptions = cloneStoreOptions(options);
+        await act(async () => {
+            renderedView.rerender(_jsx(Wrapper, { opts: rerenderOptions }));
+        });
+        // 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);
+    });
+    it('does not block useActionState transitions from committing', async () => {
+        const storeRegistry = new StoreRegistry();
+        const options = testStoreOptions();
+        const getOrLoadSpy = vi.spyOn(storeRegistry, 'getOrLoadPromise');
+        let view;
+        await act(async () => {
+            view = render(_jsx(StoreRegistryProvider, { storeRegistry: storeRegistry, children: _jsx(React.Suspense, { fallback: makeSuspenseFallback(), children: _jsx(StoreWithActionState, { options: options }) }) }));
+        });
+        const renderedView = view ?? shouldNeverHappen('render failed');
+        // Wait for store to load
+        await waitForSuspenseResolved(renderedView);
+        expect(renderedView.getByTestId('state').textContent).toBe('none');
+        expect(renderedView.getByTestId('pending').textContent).toBe('false');
+        // After store is loaded, clear spy to only track calls during the transition render
+        getOrLoadSpy.mockClear();
+        // Trigger a useActionState transition
+        await act(async () => {
+            fireEvent.click(renderedView.getByTestId('submit'));
+        });
+        // getOrLoadPromise must be called on each render (not cached via useMemo).
+        // When the initial Promise is cached, React.use() is called with a resolved Promise
+        // on every subsequent render, which blocks React transitions (e.g. useActionState)
+        // from ever committing in browser environments.
+        expect(getOrLoadSpy).toHaveBeenCalled();
+        // The transition should commit: state updates and isPending returns to false
+        await waitFor(() => {
+            expect(renderedView.getByTestId('state').textContent).toBe('updated');
+            expect(renderedView.getByTestId('pending').textContent).toBe('false');
+        });
+        getOrLoadSpy.mockRestore();
+        await cleanupAfterUnmount(() => renderedView.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: makeSuspenseFallback(), 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" });
+};
+/** Component that combines useStore with useActionState to test transition compatibility. */
+const StoreWithActionState = ({ options }) => {
+    useStore(options);
+    const [state, dispatch, isPending] = React.useActionState((_prev, value) => value, undefined);
+    return (_jsxs("div", { children: [_jsx("button", { "data-testid": "submit", 
+                // eslint-disable-next-line react-perf/jsx-no-new-function-as-prop -- test component
+                onClick: () => React.startTransition(() => dispatch('updated')), children: "Submit" }), _jsx("div", { "data-testid": "state", children: state ?? 'none' }), _jsx("div", { "data-testid": "pending", children: String(isPending) })] }));
+};
+const makeSuspenseFallback = () => React.createElement('div', { 'data-testid': 'fallback' });
+const cloneStoreOptions = (options) => {
+    return { ...options };
+};
+const makeProvider = (storeRegistry, { suspense = false } = {}) => ({ children }) => {
+    let content = _jsx(StoreRegistryProvider, { storeRegistry: storeRegistry, children: children });
+    if (suspense !== undefined) {
+        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/dist/useSyncStatus.d.ts

@@ -0,0 +1,22 @@
+import type { Store, SyncStatus } from '@livestore/livestore';
+/**
+ * React hook that subscribes to sync status changes.
+ *
+ * Returns the current synchronization status between the client session and
+ * the leader thread. The component re-renders whenever the sync status changes.
+ *
+ * @example
+ * ```tsx
+ * function SyncIndicator() {
+ *   const status = store.useSyncStatus()
+ *   return <span>{status.isSynced ? '✓ Synced' : `Syncing (${status.pendingCount} pending)...`}</span>
+ * }
+ * ```
+ *
+ * @param options - Options containing the store instance
+ * @returns The current sync status
+ */
+export declare const useSyncStatus: (options: {
+    store: Store<any>;
+}) => SyncStatus;
+//# sourceMappingURL=useSyncStatus.d.ts.map

package/dist/useSyncStatus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSyncStatus.d.ts","sourceRoot":"","sources":["../src/useSyncStatus.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAE7D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS;IAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAA;CAAE,KAAG,UAY9D,CAAA"}

package/dist/useSyncStatus.js

@@ -0,0 +1,28 @@
+import React from 'react';
+/**
+ * React hook that subscribes to sync status changes.
+ *
+ * Returns the current synchronization status between the client session and
+ * the leader thread. The component re-renders whenever the sync status changes.
+ *
+ * @example
+ * ```tsx
+ * function SyncIndicator() {
+ *   const status = store.useSyncStatus()
+ *   return <span>{status.isSynced ? '✓ Synced' : `Syncing (${status.pendingCount} pending)...`}</span>
+ * }
+ * ```
+ *
+ * @param options - Options containing the store instance
+ * @returns The current sync status
+ */
+export const useSyncStatus = (options) => {
+    const { store } = options;
+    const [status, setStatus] = React.useState(() => store.syncStatus());
+    React.useEffect(() => {
+        return store.subscribeSyncStatus(setStatus);
+    }, [store]);
+    React.useDebugValue(`LiveStore:useSyncStatus:${status.isSynced === true ? 'synced' : 'pending'}`);
+    return status;
+};
+//# sourceMappingURL=useSyncStatus.js.map

package/dist/useSyncStatus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSyncStatus.js","sourceRoot":"","sources":["../src/useSyncStatus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAIzB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,OAA8B,EAAc,EAAE;IAC1E,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAA;IAEzB,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAa,GAAG,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC,CAAA;IAEhF,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE;QACnB,OAAO,KAAK,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAA;IAC7C,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAA;IAEX,KAAK,CAAC,aAAa,CAAC,2BAA2B,MAAM,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAA;IAEjG,OAAO,MAAM,CAAA;AACf,CAAC,CAAA"}