@livestore/react 0.4.0-dev.9 → 0.4.0

package/src/useRcResource.ts

@@ -25,10 +25,10 @@ import * as React from 'react'
  * - Upon component unmount, the reference count is decremented, leading to disposal (via the `dispose` function)
  *   if the reference count drops to zero. An unmount is either detected via React's `useEffect` callback or
  *   in the useMemo hook when the key changes.
- * 
+ *
  * Why this is needed in LiveStore:
  * Let's first take a look at the "trivial implementation":
- * 
+ *
  * ```ts
  * const useSimpleResource = <T>(create: () => T, dispose: (resource: T) => void) => {
  *     const val = React.useMemo(() => create(), [create])
@@ -42,7 +42,7 @@ import * as React from 'react'
  *     return val
  * }
  * ```
- * 
+ *
  * LiveStore uses this hook to create LiveQuery instances which are stateful and must not be leaked.
  * The simple implementation above would leak the LiveQuery instance if the component is unmounted or props change.
  *
@@ -72,87 +72,87 @@ import * as React from 'react'
  * @returns The stateful entity corresponding to the provided key.
  */
 export const useRcResource = <T>(
+  scope: object,
   key: string,
   create: () => T,
   dispose: (resource: NoInfer<T>) => void,
   _options?: { debugPrint?: (resource: NoInfer<T>) => ReadonlyArray<any> },
 ): T => {
   const keyRef = React.useRef<string | undefined>(undefined)
+  const scopeRef = React.useRef<object | undefined>(undefined)
   const didDisposeInMemo = React.useRef(false)
+  const createRef = React.useRef(create)
+  const disposeRef = React.useRef(dispose)
 
-  // biome-ignore lint/correctness/useExhaustiveDependencies: Dependency is deliberately limited to `key` to avoid unintended re-creations.
+  createRef.current = create
+  disposeRef.current = dispose
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: Dependencies are deliberately limited to `scope` and `key` to avoid unintended re-creations.
   const resource = React.useMemo(() => {
-    // console.debug('useMemo', key)
-    if (didDisposeInMemo.current) {
-      // console.debug('useMemo', key, 'skip')
-      const cachedItem = cache.get(key)
+    const bucket = getBucket(scope)
+
+    if (didDisposeInMemo.current === true) {
+      const cachedItem = bucket.get(key)
       if (cachedItem !== undefined && cachedItem._tag === 'active') {
         return cachedItem.resource
       }
     }
 
-    // Check if the key has changed (or is undefined)
-    if (keyRef.current !== undefined && keyRef.current !== key) {
-      // If the key has changed, decrement the reference on the previous key
+    // Check if the (scope, key) pair has changed (or is undefined)
+    if (keyRef.current !== undefined && (keyRef.current !== key || scopeRef.current !== scope)) {
       const previousKey = keyRef.current
-      const cachedItemForPreviousKey = cache.get(previousKey)
+      // scopeRef.current is set together with keyRef.current below, so it's defined here.
+      const previousBucket = getBucket(scopeRef.current!)
+      const cachedItemForPreviousKey = previousBucket.get(previousKey)
       if (cachedItemForPreviousKey !== undefined && cachedItemForPreviousKey._tag === 'active') {
-        // previousKeyRef.current = previousKey
         cachedItemForPreviousKey.rc--
 
-        // console.debug('useMemo', key, 'rc--', previousKey, cachedItemForPreviousKey.rc)
-
         if (cachedItemForPreviousKey.rc === 0) {
           // Clean up the stateful resource if no longer referenced
-          dispose(cachedItemForPreviousKey.resource)
-          cache.set(previousKey, { _tag: 'destroyed' })
+          disposeRef.current(cachedItemForPreviousKey.resource)
+          previousBucket.set(previousKey, { _tag: 'destroyed' })
           didDisposeInMemo.current = true
         }
       }
     }
 
-    const cachedItem = cache.get(key)
+    const cachedItem = bucket.get(key)
     if (cachedItem !== undefined && cachedItem._tag === 'active') {
       // In React Strict Mode, the `useMemo` hook is called multiple times,
       // so we only increment the reference from the first call for this component.
       cachedItem.rc++
-      // console.debug('rc++', cachedItem.rc, ...(_options?.debugPrint?.(cachedItem.resource) ?? []))
-
       return cachedItem.resource
     }
 
     // Create a new stateful resource if not cached
-    const resource = create()
-    cache.set(key, { _tag: 'active', rc: 1, resource })
+    const resource = createRef.current()
+    bucket.set(key, { _tag: 'active', rc: 1, resource })
     return resource
-  }, [key])
+  }, [scope, key])
 
   // biome-ignore lint/correctness/useExhaustiveDependencies: We assume the `dispose` function is stable and won't change across renders
   React.useEffect(() => {
     return () => {
-      if (didDisposeInMemo.current) {
-        // console.debug('unmount', keyRef.current, 'skip')
+      if (didDisposeInMemo.current === true) {
         didDisposeInMemo.current = false
         return
       }
 
-      // console.debug('unmount', keyRef.current)
-      const cachedItem = cache.get(key)
-      // If the stateful resource is already cleaned up, do nothing.
+      const bucket = getBucket(scope)
+      const cachedItem = bucket.get(key)
       if (cachedItem === undefined || cachedItem._tag === 'destroyed') return
 
       cachedItem.rc--
 
-      // console.debug('rc--', cachedItem.rc, ...(_options?.debugPrint?.(cachedItem.resource) ?? []))
-
       if (cachedItem.rc === 0) {
-        dispose(cachedItem.resource)
-        cache.delete(key)
+        disposeRef.current(cachedItem.resource)
+        bucket.delete(key)
       }
     }
-  }, [key])
+  }, [scope, key])
 
   keyRef.current = key
+  scopeRef.current = scope
 
   return resource
 }
@@ -161,8 +161,7 @@ export const useRcResource = <T>(
 // we are using this cache to avoid starting multiple queries/spans for the same component.
 // This is somewhat against some recommended React best practices, but it should be fine in our case below.
 // Please definitely open an issue if you see or run into any problems with this approach!
-const cache = new Map<
-  string,
+type Entry =
   | {
       _tag: 'active'
       rc: number
@@ -171,8 +170,23 @@ const cache = new Map<
   | {
       _tag: 'destroyed'
     }
->()
+
+type Bucket = Map<string, Entry>
+
+// Per-scope buckets. Keying by the scope object (e.g. a Store instance) ensures that
+// when the scope is replaced (store dispose/recreate), the new scope gets a fresh bucket
+// and stale entries from the disposed scope become GC-eligible. See issue #1186.
+let scopedBuckets = new WeakMap<object, Bucket>()
+
+const getBucket = (scope: object): Bucket => {
+  let bucket = scopedBuckets.get(scope)
+  if (bucket === undefined) {
+    bucket = new Map()
+    scopedBuckets.set(scope, bucket)
+  }
+  return bucket
+}
 
 export const __resetUseRcResourceCache = () => {
-  cache.clear()
+  scopedBuckets = new WeakMap()
 }

package/src/useStore.test.tsx

@@ -0,0 +1,347 @@
+import { makeInMemoryAdapter } from '@livestore/adapter-web'
+import {
+  type RegistryStoreOptions,
+  type Store,
+  StoreInternalsSymbol,
+  StoreRegistry,
+  storeOptions,
+} from '@livestore/livestore'
+import { shouldNeverHappen } from '@livestore/utils'
+import { act, type RenderHookResult, type RenderResult, 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.tsx'
+import { StoreRegistryProvider } from './StoreRegistryContext.tsx'
+import { useStore } from './useStore.ts'
+
+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: RenderResult | undefined
+    await act(async () => {
+      view = render(
+        <StoreRegistryProvider storeRegistry={storeRegistry}>
+          <React.Suspense fallback={makeSuspenseFallback()}>
+            <StoreConsumer options={options} />
+          </React.Suspense>
+        </StoreRegistryProvider>,
+      )
+    })
+    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 }: { opts: RegistryStoreOptions<typeof schema> }) => (
+      <StoreRegistryProvider storeRegistry={storeRegistry}>
+        <React.Suspense fallback={makeSuspenseFallback()}>
+          <StoreConsumer options={opts} />
+        </React.Suspense>
+      </StoreRegistryProvider>
+    )
+
+    let view: RenderResult | undefined
+    await act(async () => {
+      view = render(<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(<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: RenderHookResult<Store<typeof schema>, RegistryStoreOptions<typeof schema>> | undefined
+    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: RenderHookResult<Store<typeof schema>, RegistryStoreOptions<typeof schema>> | undefined
+    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: RenderResult | undefined
+    await act(async () => {
+      view = render(
+        <StoreRegistryProvider storeRegistry={storeRegistry}>
+          <React.Suspense fallback={makeSuspenseFallback()}>
+            <StoreWithActionState options={options} />
+          </React.Suspense>
+        </StoreRegistryProvider>,
+      )
+    })
+    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 }: { opts: RegistryStoreOptions<typeof schema> }) => {
+      const store = useStore(opts)
+      // Verify store is usable - access internals to confirm it's not disposed
+      const clientSession = store[StoreInternalsSymbol].clientSession
+      return <div data-testid="ready" data-has-session={String(clientSession !== undefined)} />
+    }
+
+    let view: RenderResult | undefined
+    await act(async () => {
+      view = render(
+        <StoreRegistryProvider storeRegistry={storeRegistry}>
+          <React.Suspense fallback={makeSuspenseFallback()}>
+            <StoreConsumerWithVerification opts={options} />
+          </React.Suspense>
+        </StoreRegistryProvider>,
+      )
+    })
+    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 }: { options: RegistryStoreOptions<any> }) => {
+  useStore(options)
+  return <div data-testid="ready" />
+}
+
+/** Component that combines useStore with useActionState to test transition compatibility. */
+const StoreWithActionState = ({ options }: { options: RegistryStoreOptions<any> }) => {
+  useStore(options)
+
+  const [state, dispatch, isPending] = React.useActionState(
+    (_prev: string | undefined, value: string): string => value,
+    undefined,
+  )
+
+  return (
+    <div>
+      <button
+        data-testid="submit"
+        // eslint-disable-next-line react-perf/jsx-no-new-function-as-prop -- test component
+        onClick={() => React.startTransition(() => dispatch('updated'))}
+      >
+        Submit
+      </button>
+      <div data-testid="state">{state ?? 'none'}</div>
+      <div data-testid="pending">{String(isPending)}</div>
+    </div>
+  )
+}
+
+const makeSuspenseFallback = () => React.createElement('div', { 'data-testid': 'fallback' })
+
+const cloneStoreOptions = <TOptions extends object>(options: TOptions): TOptions => {
+  return { ...options }
+}
+
+const makeProvider =
+  (storeRegistry: StoreRegistry, { suspense = false }: { suspense?: boolean } = {}) =>
+  ({ children }: { children: React.ReactNode }) => {
+    let content = <StoreRegistryProvider storeRegistry={storeRegistry}>{children}</StoreRegistryProvider>
+
+    if (suspense !== undefined) {
+      content = <React.Suspense fallback={null}>{content}</React.Suspense>
+    }
+
+    return content
+  }
+
+let testStoreCounter = 0
+
+const testStoreOptions = (overrides: Partial<RegistryStoreOptions<typeof schema>> = {}) =>
+  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: () => void): Promise<void> => {
+  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: RenderResult): Promise<void> => {
+  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: { current: Store<any> }): Promise<void> => {
+  await waitFor(() => {
+    expect(result.current).not.toBeNull()
+    expect(result.current[StoreInternalsSymbol].clientSession).toBeDefined()
+  })
+}

package/src/useStore.ts

@@ -1,36 +1,129 @@
-import type { Store } from '@livestore/livestore'
 import React from 'react'
 
-import type { ReactApi } from './LiveStoreContext.ts'
-import { LiveStoreContext } from './LiveStoreContext.ts'
+import type { LiveStoreSchema } from '@livestore/common/schema'
+import type { RegistryStoreOptions, Store, SyncStatus } from '@livestore/livestore'
+import type { Schema } from '@livestore/utils/effect'
+
+import { useStoreRegistry } from './StoreRegistryContext.tsx'
 import { useClientDocument } from './useClientDocument.ts'
 import { useQuery } from './useQuery.ts'
+import { useSyncStatus } from './useSyncStatus.ts'
 
-export const withReactApi = (store: Store): Store & ReactApi => {
-  // @ts-expect-error TODO properly implement this
+/**
+ * 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 = <
+  TSchema extends LiveStoreSchema,
+  TContext = {},
+  TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+>(
+  options: RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema>,
+): Store<TSchema, TContext> & ReactApi => {
+  const storeRegistry = useStoreRegistry()
 
-  store.useQuery = (queryDef) => useQuery(queryDef, { store })
-  // @ts-expect-error TODO properly implement this
+  // 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)
 
-  store.useClientDocument = (table, idOrOptions, options) => useClientDocument(table, idOrOptions, options, { store })
-  return store as Store & ReactApi
+  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)
 }
 
-export const useStore = (options?: { store?: Store }): { store: Store & ReactApi } => {
-  if (options?.store !== undefined) {
-    return { store: withReactApi(options.store) }
-  }
+/**
+ * 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
+}
 
-  // biome-ignore lint/correctness/useHookAtTopLevel: store is stable
-  const storeContext = React.useContext(LiveStoreContext)
+/**
+ * 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 = <TSchema extends LiveStoreSchema, TContext = {}>(
+  store: Store<TSchema, TContext>,
+): Store<TSchema, TContext> & ReactApi => {
+  // @ts-expect-error TODO properly implement this
+  store.useQuery = (queryable) => useQuery(queryable, { store })
 
-  if (storeContext === undefined) {
-    throw new Error(`useStore can only be used inside StoreContext.Provider`)
-  }
+  // @ts-expect-error TODO properly implement this
+  store.useClientDocument = (table, idOrOptions, options) => useClientDocument(table, idOrOptions, options, { store })
 
-  if (storeContext.stage !== 'running') {
-    throw new Error(`useStore can only be used after the store is running`)
-  }
+  // @ts-expect-error TODO properly implement this
+  store.useSyncStatus = () => useSyncStatus({ store })
 
-  return { store: withReactApi(storeContext.store) }
+  return store as Store<TSchema, TContext> & ReactApi
 }