@livestore/react 0.4.0-dev.8 → 0.4.0

package/src/useQuery.test.tsx

@@ -1,17 +1,19 @@
 /** biome-ignore-all lint/a11y: test */
+import { makeInMemoryAdapter } from '@livestore/adapter-web'
+import { provideOtel } from '@livestore/common'
 import * as LiveStore from '@livestore/livestore'
-import { queryDb, signal } from '@livestore/livestore'
+import { createStore, queryDb, StoreInternalsSymbol, signal } from '@livestore/livestore'
 import { RG } from '@livestore/livestore/internal/testing-utils'
 import { Effect, Schema } from '@livestore/utils/effect'
 import { Vitest } from '@livestore/utils-dev/node-vitest'
 import * as ReactTesting from '@testing-library/react'
 import React from 'react'
-// @ts-expect-error no types
 import * as ReactWindow from 'react-window'
 import { expect } from 'vitest'
 
-import { events, makeTodoMvcReact, tables } from './__tests__/fixture.js'
-import { __resetUseRcResourceCache } from './useRcResource.js'
+import { events, makeTodoMvcReact, schema, tables } from './__tests__/fixture.tsx'
+import { __resetUseRcResourceCache } from './useRcResource.ts'
+import { withReactApi } from './useStore.ts'
 
 Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
   'useQuery (strictMode=%s)',
@@ -38,14 +40,14 @@ Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
 
         expect(result.current.length).toBe(0)
         expect(renderCount.val).toBe(1)
-        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+        expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
 
         ReactTesting.act(() => store.commit(events.todoCreated({ id: 't1', text: 'buy milk', completed: false })))
 
         expect(result.current.length).toBe(1)
         expect(result.current[0]!.text).toBe('buy milk')
         expect(renderCount.val).toBe(2)
-        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+        expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
       }),
     )
 
@@ -80,19 +82,25 @@ Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
 
         expect(result.current).toBe('buy milk')
         expect(renderCount.val).toBe(1)
-        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot('1: after first render')
+        expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot(
+          '1: after first render',
+        )
 
         ReactTesting.act(() => store.commit(events.todoUpdated({ id: 't1', text: 'buy soy milk' })))
 
         expect(result.current).toBe('buy soy milk')
         expect(renderCount.val).toBe(2)
-        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot('2: after first commit')
+        expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot(
+          '2: after first commit',
+        )
 
         rerender('t2')
 
         expect(result.current).toBe('buy eggs')
         expect(renderCount.val).toBe(3)
-        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot('3: after forced rerender')
+        expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot(
+          '3: after forced rerender',
+        )
       }),
     )
 
@@ -120,19 +128,19 @@ Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
 
         expect(result.current).toBe('buy milk')
         expect(renderCount.val).toBe(1)
-        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+        expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
 
         ReactTesting.act(() => store.commit(events.todoUpdated({ id: 't1', text: 'buy soy milk' })))
 
         expect(result.current).toBe('buy soy milk')
         expect(renderCount.val).toBe(2)
-        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+        expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
 
         ReactTesting.act(() => store.setSignal(filter$, 't2'))
 
         expect(result.current).toBe('buy eggs')
         expect(renderCount.val).toBe(3)
-        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+        expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
       }),
     )
 
@@ -150,7 +158,7 @@ Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
               width={100}
               itemSize={10}
               itemCount={numItems}
-              itemData={Array.from({ length: numItems }, (_, i) => i).reverse()}
+              itemData={Array.from({ length: numItems }, (_, i) => i).toReversed()}
             >
               {ListItem}
             </ReactWindow.FixedSizeList>
@@ -187,5 +195,83 @@ Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
         expect(result.current).toBe(1)
       }),
     )
+
+    Vitest.scopedLive('supports query builders directly', () =>
+      Effect.gen(function* () {
+        const { wrapper, store } = yield* makeTodoMvcReact({ strictMode })
+
+        store.commit(
+          events.todoCreated({ id: 't1', text: 'buy milk', completed: false }),
+          events.todoCreated({ id: 't2', text: 'buy eggs', completed: true }),
+        )
+
+        const todosWhereIncomplete = tables.todos.where({ completed: false })
+
+        const { result } = ReactTesting.renderHook(() => store.useQuery(todosWhereIncomplete).map((todo) => todo.id), {
+          wrapper,
+        })
+
+        expect(result.current).toEqual(['t1'])
+      }),
+    )
+
+    Vitest.scopedLive('derives a fresh LiveQuery per Store instance', () =>
+      Effect.gen(function* () {
+        const makeStore = () =>
+          createStore({
+            schema,
+            storeId: 'reset-test',
+            adapter: makeInMemoryAdapter({ clientId: 'stable-client', sessionId: 'stable-session' }),
+            debug: { instanceId: 'test' },
+          }).pipe(provideOtel({}))
+
+        const storeA = withReactApi(yield* makeStore())
+        const storeB = withReactApi(yield* makeStore())
+
+        const allTodos$ = queryDb({ query: `select * from todos`, schema: Schema.Array(tables.todos.rowSchema) })
+
+        const MaybeStrictMode = strictMode === true ? React.StrictMode : React.Fragment
+        const wrapper = ({ children }: any) => <MaybeStrictMode>{children}</MaybeStrictMode>
+
+        storeA.commit(events.todoCreated({ id: 't1', text: 'buy milk', completed: false }))
+
+        const { result, rerender } = ReactTesting.renderHook(
+          ({ store }: { store: typeof storeA }) => store.useQuery(allTodos$).length,
+          { wrapper, initialProps: { store: storeA } },
+        )
+
+        expect(result.current).toBe(1)
+
+        rerender({ store: storeB })
+
+        expect(result.current).toBe(0)
+      }),
+    )
+
+    Vitest.scopedLive('union of different result types with useQuery', () =>
+      Effect.gen(function* () {
+        const { wrapper, store, renderCount } = yield* makeTodoMvcReact({ strictMode })
+
+        const str$ = signal('hello', { label: 'str' })
+        const num$ = signal(123, { label: 'num' })
+
+        const { result, rerender } = ReactTesting.renderHook(
+          (useNum: boolean) => {
+            renderCount.inc()
+            const query$ = React.useMemo(() => (useNum === true ? num$ : str$), [useNum])
+            return store.useQuery(query$)
+          },
+          { wrapper, initialProps: false },
+        )
+
+        expect(result.current).toBe('hello')
+        expect(renderCount.val).toBe(1)
+
+        rerender(true)
+
+        expect(result.current).toBe(123)
+        expect(renderCount.val).toBe(2)
+      }),
+    )
   },
 )

package/src/useQuery.ts

@@ -1,13 +1,19 @@
-import type { LiveQuery, LiveQueryDef, Store } from '@livestore/livestore'
-import { extractStackInfoFromStackTrace, stackInfoToString } from '@livestore/livestore'
-import type { LiveQueries } from '@livestore/livestore/internal'
-import { deepEqual, indent, shouldNeverHappen } from '@livestore/utils'
-import * as otel from '@opentelemetry/api'
+import type * as otel from '@opentelemetry/api'
 import React from 'react'
 
-import { LiveStoreContext } from './LiveStoreContext.ts'
+import {
+  captureStackInfo,
+  computeRcRefKey,
+  createQueryResource,
+  type NormalizedQueryable,
+  normalizeQueryable,
+  runInitialQuery,
+} from '@livestore/framework-toolkit'
+import type { LiveQuery, Queryable, Store } from '@livestore/livestore'
+import type { LiveQueries } from '@livestore/livestore/internal'
+import { deepEqual, shouldNeverHappen } from '@livestore/utils'
+
 import { useRcResource } from './useRcResource.ts'
-import { originalStackLimit } from './utils/stack-info.ts'
 import { useStateRefWithReactiveInput } from './utils/useStateRefWithReactiveInput.ts'
 
 /**
@@ -21,15 +27,36 @@ import { useStateRefWithReactiveInput } from './utils/useStateRefWithReactiveInp
  * }
  * ```
  */
-export const useQuery = <TQuery extends LiveQueryDef.Any>(
-  queryDef: TQuery,
+export const useQuery = <TQueryable extends Queryable<any>>(
+  queryable: TQueryable,
   options?: { store?: Store },
-): LiveQueries.GetResult<TQuery> => useQueryRef(queryDef, options).valueRef.current
+): Queryable.Result<TQueryable> => useQueryRef(queryable, options).valueRef.current
 
 /**
+ * Like `useQuery`, but also returns a reference to the underlying LiveQuery instance.
+ *
+ * Usage
+ * - Accepts any `Queryable<TResult>`: a `LiveQueryDef`, `SignalDef`, a `LiveQuery` instance
+ *   or a SQL `QueryBuilder`. Unions of queryables are supported and the result type is
+ *   inferred via `Queryable.Result<TQueryable>`.
+ * - Creates an OpenTelemetry span per unique query, reusing it while the ref-counted
+ *   resource is alive. The span name is updated once the dynamic label is known.
+ * - Manages a reference-counted resource under-the-hood so query instances are shared
+ *   across re-renders and properly disposed once no longer referenced.
+ *
+ * Parameters
+ * - `queryable`: The query definition/instance/builder to run and subscribe to.
+ * - `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.
+ *
+ * Returns
+ * - `valueRef`: A React ref whose `current` holds the latest query result. The type is
+ *   `Queryable.Result<TQueryable>` with full inference for unions.
+ * - `queryRcRef`: The underlying reference-counted `LiveQuery` instance used by the store.
  */
-export const useQueryRef = <TQuery extends LiveQueryDef.Any>(
-  queryDef: TQuery,
+export const useQueryRef = <TQueryable extends Queryable<any>>(
+  queryable: TQueryable,
   options?: {
     store?: Store
     /** Parent otel context for the query */
@@ -38,102 +65,58 @@ export const useQueryRef = <TQuery extends LiveQueryDef.Any>(
     otelSpanName?: string
   },
 ): {
-  valueRef: React.RefObject<LiveQueries.GetResult<TQuery>>
-  queryRcRef: LiveQueries.RcRef<LiveQuery<LiveQueries.GetResult<TQuery>>>
+  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`)
-
-  // It's important to use all "aspects" of a store instance here, otherwise we get unexpected cache mappings
-  const rcRefKey = `${store.storeId}_${store.clientId}_${store.sessionId}_${queryDef.hash}`
+  const store = options?.store ?? shouldNeverHappen(`No store provided to useQuery`)
 
-  const stackInfo = React.useMemo(() => {
-    Error.stackTraceLimit = 10
-    const stack = new Error().stack!
-    Error.stackTraceLimit = originalStackLimit
-    return extractStackInfoFromStackTrace(stack)
-  }, [])
+  type TResult = Queryable.Result<TQueryable>
 
-  const { queryRcRef, span, otelContext } = useRcResource(
-    rcRefKey,
-    () => {
-      const queryDefLabel = queryDef.label
-
-      const span = store.otel.tracer.startSpan(
-        options?.otelSpanName ?? `LiveStore:useQuery:${queryDefLabel}`,
-        { attributes: { label: queryDefLabel, firstStackInfo: JSON.stringify(stackInfo) } },
-        options?.otelContext ?? store.otel.queriesSpanContext,
-      )
+  const normalized = React.useMemo<NormalizedQueryable<TResult>>(
+    () => normalizeQueryable(queryable as Queryable<TResult>),
+    [queryable],
+  )
 
-      const otelContext = otel.trace.setSpan(otel.context.active(), span)
+  const rcRefKey = React.useMemo(() => computeRcRefKey(store, normalized), [normalized, store])
 
-      const queryRcRef = queryDef.make(store.reactivityGraph.context!, otelContext)
+  const stackInfo = React.useMemo(() => captureStackInfo(), [])
 
-      return { queryRcRef, span, otelContext }
-    },
+  const { queryRcRef, span, otelContext } = useRcResource(
+    store,
+    rcRefKey,
+    () =>
+      createQueryResource(store, normalized, stackInfo, {
+        otelSpanName: options?.otelSpanName,
+        otelContext: options?.otelContext,
+      }),
     // We need to keep the queryRcRef alive a bit longer, so we have a second `useRcResource` below
     // which takes care of disposing the queryRcRef
     () => {},
   )
 
-  // if (queryRcRef.value._tag === 'signal') {
-  //   const  queryRcRef.value.get()
-  // }
-
-  const query$ = queryRcRef.value as LiveQuery<LiveQueries.GetResult<TQuery>>
+  const query$ = queryRcRef.value
 
   React.useDebugValue(`LiveStore:useQuery:${query$.id}:${query$.label}`)
-  // console.debug(`LiveStore:useQuery:${query$.id}:${query$.label}`)
-
-  const initialResult = React.useMemo(() => {
-    try {
-      return query$.run({
-        otelContext,
-        debugRefreshReason: {
-          _tag: 'react',
-          api: 'useQuery',
-          label: `useQuery:initial-run:${query$.label}`,
-          stackInfo,
-        },
-      })
-    } catch (cause: any) {
-      console.error('[@livestore/react:useQuery] Error running query', cause)
-      throw new Error(
-        `\
-[@livestore/react:useQuery] Error running query: ${cause.name}
-
-Query: ${query$.label}
 
-React trace:
-
-${indent(stackInfoToString(stackInfo), 4)}
-
-Stack trace:
-`,
-        { cause },
-      )
-    }
-  }, [otelContext, query$, stackInfo])
+  const initialResult = React.useMemo(
+    () => runInitialQuery(query$, otelContext, stackInfo, 'react'),
+    [otelContext, query$, stackInfo],
+  )
 
   // We know the query has a result by the time we use it; so we can synchronously populate a default state
-  const [valueRef, setValue] = useStateRefWithReactiveInput<LiveQueries.GetResult<TQuery>>(initialResult)
-
-  // TODO we probably need to change the order of `useEffect` calls, so we destroy the query at the end
-  // before calling the LS `onEffect` on it
+  const [valueRef, setValue] = useStateRefWithReactiveInput<TResult>(initialResult)
 
   // Subscribe to future updates for this query
   React.useEffect(() => {
-    // TODO double check whether we still need `activeSubscriptions`
     query$.activeSubscriptions.add(stackInfo)
 
     // Dynamic queries only set their actual label after they've been run the first time,
     // so we're also updating the span name here.
     span.updateName(options?.otelSpanName ?? `LiveStore:useQuery:${query$.label}`)
 
-    return store.subscribe(query$, {
-      onUpdate: (newValue) => {
+    return store.subscribe(
+      query$,
+      (newValue) => {
         // NOTE: we return a reference to the result object within LiveStore;
         // this implies that app code must not mutate the results, or else
         // there may be weird reactivity bugs.
@@ -141,19 +124,21 @@ Stack trace:
           setValue(newValue)
         }
       },
-      onUnsubsubscribe: () => {
-        query$.activeSubscriptions.delete(stackInfo)
+      {
+        onUnsubsubscribe: () => {
+          query$.activeSubscriptions.delete(stackInfo)
+        },
+        label: query$.label,
+        otelContext,
       },
-      label: query$.label,
-      otelContext,
-    })
+    )
   }, [stackInfo, query$, setValue, store, valueRef, otelContext, span, options?.otelSpanName])
 
   useRcResource(
+    store,
     rcRefKey,
     () => ({ queryRcRef, span }),
     ({ queryRcRef, span }) => {
-      // console.debug('deref', queryRcRef.value.id, queryRcRef.value.label)
       queryRcRef.deref()
       span.end()
     },

package/src/useRcResource.test.tsx

@@ -2,20 +2,23 @@ import * as ReactTesting from '@testing-library/react'
 import * as React from 'react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
-import { __resetUseRcResourceCache, useRcResource } from './useRcResource.js'
+import { __resetUseRcResourceCache, useRcResource } from './useRcResource.ts'
 
 describe.each([{ strictMode: true }, { strictMode: false }])('useRcResource (strictMode=%s)', ({ strictMode }) => {
   beforeEach(() => {
     __resetUseRcResourceCache()
   })
 
-  const wrapper = strictMode ? React.StrictMode : React.Fragment
+  const wrapper = strictMode === true ? React.StrictMode : React.Fragment
 
   it('should create a stateful entity using make and call cleanup on unmount', () => {
+    const scope = {}
     const makeSpy = vi.fn(() => Symbol('statefulResource'))
     const cleanupSpy = vi.fn()
 
-    const { result, unmount } = ReactTesting.renderHook(() => useRcResource('key-1', makeSpy, cleanupSpy), { wrapper })
+    const { result, unmount } = ReactTesting.renderHook(() => useRcResource(scope, 'key-1', makeSpy, cleanupSpy), {
+      wrapper,
+    })
 
     expect(makeSpy).toHaveBeenCalledTimes(1)
     expect(result.current).toBeDefined()
@@ -26,11 +29,12 @@ describe.each([{ strictMode: true }, { strictMode: false }])('useRcResource (str
   })
 
   it('should reuse the same entity when the key remains unchanged', () => {
+    const scope = {}
     const makeSpy = vi.fn(() => Symbol('statefulResource'))
     const cleanupSpy = vi.fn()
 
     const { result, rerender, unmount } = ReactTesting.renderHook(
-      ({ key }) => useRcResource(key, makeSpy, cleanupSpy),
+      ({ key }) => useRcResource(scope, key, makeSpy, cleanupSpy),
       { initialProps: { key: 'consistent-key' }, wrapper },
     )
 
@@ -48,11 +52,12 @@ describe.each([{ strictMode: true }, { strictMode: false }])('useRcResource (str
   })
 
   it('should dispose the previous instance when the key changes', () => {
+    const scope = {}
     const makeSpy = vi.fn(() => Symbol('statefulResource'))
     const cleanupSpy = vi.fn()
 
     const { result, rerender, unmount } = ReactTesting.renderHook(
-      ({ key }) => useRcResource(key, makeSpy, cleanupSpy),
+      ({ key }) => useRcResource(scope, key, makeSpy, cleanupSpy),
       { initialProps: { key: 'a' }, wrapper },
     )
 
@@ -71,18 +76,18 @@ describe.each([{ strictMode: true }, { strictMode: false }])('useRcResource (str
   })
 
   it('should not dispose the entity until all consumers unmount', () => {
+    const scope = {}
     const makeSpy = vi.fn(() => Symbol('statefulResource'))
     const cleanupSpy = vi.fn()
 
-    // Simulate two consumers using the same key independently.
-    const { unmount: unmount1 } = ReactTesting.renderHook(() => useRcResource('shared-key', makeSpy, cleanupSpy), {
-      wrapper,
-    })
+    // Simulate two consumers using the same (scope, key) pair independently.
+    const { unmount: unmount1 } = ReactTesting.renderHook(
+      () => useRcResource(scope, 'shared-key', makeSpy, cleanupSpy),
+      { wrapper },
+    )
     const { unmount: unmount2, result } = ReactTesting.renderHook(
-      () => useRcResource('shared-key', makeSpy, cleanupSpy),
-      {
-        wrapper,
-      },
+      () => useRcResource(scope, 'shared-key', makeSpy, cleanupSpy),
+      { wrapper },
     )
 
     expect(result.current).toBeDefined()
@@ -98,10 +103,11 @@ describe.each([{ strictMode: true }, { strictMode: false }])('useRcResource (str
   })
 
   it('should handle rapid key changes correctly', () => {
+    const scope = {}
     const makeSpy = vi.fn(() => Symbol('statefulResource'))
     const cleanupSpy = vi.fn()
 
-    const { rerender, unmount } = ReactTesting.renderHook(({ key }) => useRcResource(key, makeSpy, cleanupSpy), {
+    const { rerender, unmount } = ReactTesting.renderHook(({ key }) => useRcResource(scope, key, makeSpy, cleanupSpy), {
       initialProps: { key: '1' },
       wrapper,
     })
@@ -119,49 +125,99 @@ describe.each([{ strictMode: true }, { strictMode: false }])('useRcResource (str
     // Unmounting the final consumer disposes the key '3' instance.
     expect(cleanupSpy).toHaveBeenCalledTimes(3)
   })
-})
 
-// This code was useful to better understand the hook behaviour with and without strict mode
-// describe('debug', () => {
-//  const useStrictTest = (key: string) => {
-//   const id = React.useId()
-//   console.log(key, 'id', id)
-
-//   const x = React.useMemo(() => {
-//     console.log('useMemo', key)
-//     return 'hi' + key
-//   }, [key])
-
-//   React.useEffect(() => {
-//     console.log('useEffect', key)
-//     return () => {
-//       console.log('unmount', key)
-//     }
-//   }, [])
-
-//   return x
-// }
-
-//   it('strict mode component', () => {
-//     console.log('strict mode component')
-//     const Root = () => {
-//       useStrictTest('a')
-//       return null
-//     }
-//     const { unmount } = ReactTesting.render(
-//       <React.StrictMode>
-//         <Root />
-//       </React.StrictMode>,
-//     )
-
-//     unmount()
-//   })
-
-//   it('strict mode hook', () => {
-//     console.log('strict mode hook')
-//     const wrapper: React.FC<{ children: React.ReactNode }> = React.StrictMode
-//     const { unmount } = ReactTesting.renderHook(() => useStrictTest('b'), { wrapper })
-
-//     unmount()
-//   })
-// })
+  it('should isolate entities created with the same key but different scopes', () => {
+    const scopeA = { tag: 'A' }
+    const scopeB = { tag: 'B' }
+    const makeSpy = vi.fn(() => Symbol('statefulResource'))
+    const cleanupSpy = vi.fn()
+
+    const { result: resultA } = ReactTesting.renderHook(
+      () => useRcResource(scopeA, 'shared-key', makeSpy, cleanupSpy),
+      { wrapper },
+    )
+    const { result: resultB } = ReactTesting.renderHook(
+      () => useRcResource(scopeB, 'shared-key', makeSpy, cleanupSpy),
+      { wrapper },
+    )
+
+    expect(resultA.current).not.toBe(resultB.current)
+    expect(makeSpy).toHaveBeenCalledTimes(2)
+  })
+
+  it('should dispose the previous entity when the scope changes (key unchanged)', () => {
+    const scopeA = { tag: 'A' }
+    const scopeB = { tag: 'B' }
+    const makeSpy = vi.fn(() => Symbol('statefulResource'))
+    const cleanupSpy = vi.fn()
+
+    const { result, rerender, unmount } = ReactTesting.renderHook(
+      ({ scope }) => useRcResource(scope, 'k', makeSpy, cleanupSpy),
+      { initialProps: { scope: scopeA }, wrapper },
+    )
+
+    const instanceA = result.current
+    expect(makeSpy).toHaveBeenCalledTimes(1)
+
+    rerender({ scope: scopeB })
+    const instanceB = result.current
+
+    expect(instanceA).not.toBe(instanceB)
+    expect(makeSpy).toHaveBeenCalledTimes(2)
+    // The scopeA entry's last consumer left when we switched scopes → cleaned up.
+    expect(cleanupSpy).toHaveBeenCalledTimes(1)
+
+    unmount()
+    expect(cleanupSpy).toHaveBeenCalledTimes(2)
+  })
+
+  it('should not reuse a cached entity after the scope is replaced', () => {
+    const makeSpy = vi.fn(() => Symbol('statefulResource'))
+    const cleanupSpy = vi.fn()
+
+    const scope1 = {}
+    const { result: result1, unmount: unmount1 } = ReactTesting.renderHook(
+      () => useRcResource(scope1, 'k', makeSpy, cleanupSpy),
+      { wrapper },
+    )
+    const instance1 = result1.current
+    unmount1()
+    expect(cleanupSpy).toHaveBeenCalledTimes(1)
+
+    // Fresh scope, same string key — must NOT reuse the (already-disposed) entry.
+    const scope2 = {}
+    const { result: result2, unmount: unmount2 } = ReactTesting.renderHook(
+      () => useRcResource(scope2, 'k', makeSpy, cleanupSpy),
+      { wrapper },
+    )
+
+    expect(result2.current).not.toBe(instance1)
+    expect(makeSpy).toHaveBeenCalledTimes(2)
+
+    unmount2()
+    expect(cleanupSpy).toHaveBeenCalledTimes(2)
+  })
+
+  it('should share the entity across components within the same scope', () => {
+    const scope = {}
+    const makeSpy = vi.fn(() => Symbol('statefulResource'))
+    const cleanupSpy = vi.fn()
+
+    const { result: r1, unmount: unmount1 } = ReactTesting.renderHook(
+      () => useRcResource(scope, 'k', makeSpy, cleanupSpy),
+      { wrapper },
+    )
+    const { result: r2, unmount: unmount2 } = ReactTesting.renderHook(
+      () => useRcResource(scope, 'k', makeSpy, cleanupSpy),
+      { wrapper },
+    )
+
+    expect(r1.current).toBe(r2.current)
+    expect(makeSpy).toHaveBeenCalledTimes(1)
+
+    unmount1()
+    expect(cleanupSpy).not.toHaveBeenCalled()
+    unmount2()
+    expect(cleanupSpy).toHaveBeenCalledTimes(1)
+  })
+})