fix: Address critical Suspense lifecycle bugs from code review

Fixed two critical bugs identified in senior-level code review:

1. **Error after success bug**: Previously threw errors to Error Boundary
   even after initial success. Now only throws during initial load.
   After first success, errors surface as stale data (matches TanStack
   Query behavior).

2. **Promise lifecycle bug**: When deps changed, could throw old promise
   from previous collection. Now properly resets promise when collection
   changes.

Implementation:
- Track current collection reference to detect changes
- Track hasBeenReady state to distinguish initial vs post-success errors
- Reset promise and ready state when collection/deps change
- Only throw errors during initial load (!hasBeenReadyRef.current)

Tests added:
- Verify NO re-suspension on live updates after initial load
- Verify suspension only on deps change, not on re-renders

This aligns with TanStack Query's Suspense semantics:
- Block once during initial load
- Stream updates after success without re-suspending
- Show stale data if errors occur post-success

Credit: Fixes identified by external code review

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: claude

packages/react-db/src/useLiveSuspenseQuery.ts

@@ -124,10 +124,25 @@ export function useLiveSuspenseQuery(
   deps: Array<unknown> = []
 ) {
   const promiseRef = useRef<Promise<void> | null>(null)
+  const collectionRef = useRef<Collection<any, any, any> | null>(null)
+  const hasBeenReadyRef = useRef(false)
 
   // Use useLiveQuery to handle collection management and reactivity
   const result = useLiveQuery(configOrQueryOrCollection, deps)
 
+  // Reset promise and ready state when collection changes (deps changed)
+  if (collectionRef.current !== result.collection) {
+    promiseRef.current = null
+    collectionRef.current = result.collection
+    hasBeenReadyRef.current = false
+  }
+
+  // Track when we reach ready state
+  if (result.status === `ready`) {
+    hasBeenReadyRef.current = true
+    promiseRef.current = null
+  }
+
   // SUSPENSE LOGIC: Throw promise or error based on collection status
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
   if (!result.isEnabled) {
@@ -137,27 +152,24 @@ export function useLiveSuspenseQuery(
     )
   }
 
-  if (result.status === `error`) {
-    // Clear promise and throw error to Error Boundary
+  // Only throw errors during initial load (before first ready)
+  // After success, errors surface as stale data (matches TanStack Query behavior)
+  if (result.status === `error` && !hasBeenReadyRef.current) {
     promiseRef.current = null
     throw new Error(`Collection "${result.collection.id}" failed to load`)
   }
 
   if (result.status === `loading` || result.status === `idle`) {
-    // Create or reuse promise
+    // Create or reuse promise for current collection
     if (!promiseRef.current) {
       promiseRef.current = result.collection.preload()
     }
     // THROW PROMISE - React Suspense catches this (React 18+ compatible)
     throw promiseRef.current
   }
 
-  // Collection is ready - clear promise
-  if (result.status === `ready`) {
-    promiseRef.current = null
-  }
-
   // Return data without status/loading flags (handled by Suspense/ErrorBoundary)
+  // If error after success, return last known good state (stale data)
   return {
     state: result.state,
     data: result.data,

packages/react-db/tests/useLiveSuspenseQuery.test.tsx

@@ -403,4 +403,149 @@ describe(`useLiveSuspenseQuery`, () => {
       { timeout: 1000 }
     )
   })
+
+  it(`should NOT re-suspend on live updates after initial load`, async () => {
+    const collection = createCollection(
+      mockSyncCollectionOptions<Person>({
+        id: `test-persons-suspense-11`,
+        getKey: (person: Person) => person.id,
+        initialData: initialPersons,
+      })
+    )
+
+    let suspenseCount = 0
+    const SuspenseCounter = ({ children }: { children: ReactNode }) => {
+      return (
+        <Suspense
+          fallback={
+            <div>
+              {(() => {
+                suspenseCount++
+                return `Loading...`
+              })()}
+            </div>
+          }
+        >
+          {children}
+        </Suspense>
+      )
+    }
+
+    const { result } = renderHook(
+      () => useLiveSuspenseQuery((q) => q.from({ persons: collection })),
+      {
+        wrapper: SuspenseCounter,
+      }
+    )
+
+    // Wait for initial load
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(3)
+    })
+
+    const initialSuspenseCount = suspenseCount
+
+    // Make multiple live updates
+    collection.insert({
+      id: `4`,
+      name: `New Person 1`,
+      age: 40,
+      email: `[email protected]`,
+      isActive: true,
+      team: `team1`,
+    })
+
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(4)
+    })
+
+    collection.insert({
+      id: `5`,
+      name: `New Person 2`,
+      age: 45,
+      email: `[email protected]`,
+      isActive: true,
+      team: `team2`,
+    })
+
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(5)
+    })
+
+    collection.delete(`4`)
+
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(4)
+    })
+
+    // Verify suspense count hasn't increased (no re-suspension)
+    expect(suspenseCount).toBe(initialSuspenseCount)
+  })
+
+  it(`should only suspend on deps change, not on every re-render`, async () => {
+    const collection = createCollection(
+      mockSyncCollectionOptions<Person>({
+        id: `test-persons-suspense-12`,
+        getKey: (person: Person) => person.id,
+        initialData: initialPersons,
+      })
+    )
+
+    let suspenseCount = 0
+    const SuspenseCounter = ({ children }: { children: ReactNode }) => {
+      return (
+        <Suspense
+          fallback={
+            <div>
+              {(() => {
+                suspenseCount++
+                return `Loading...`
+              })()}
+            </div>
+          }
+        >
+          {children}
+        </Suspense>
+      )
+    }
+
+    const { result, rerender } = renderHook(
+      ({ minAge }) =>
+        useLiveSuspenseQuery(
+          (q) =>
+            q
+              .from({ persons: collection })
+              .where(({ persons }) => gt(persons.age, minAge)),
+          [minAge]
+        ),
+      {
+        wrapper: SuspenseCounter,
+        initialProps: { minAge: 20 },
+      }
+    )
+
+    // Wait for initial load
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(3)
+    })
+
+    const suspenseCountAfterInitial = suspenseCount
+
+    // Re-render with SAME deps - should NOT suspend
+    rerender({ minAge: 20 })
+    rerender({ minAge: 20 })
+    rerender({ minAge: 20 })
+
+    expect(suspenseCount).toBe(suspenseCountAfterInitial)
+
+    // Change deps - SHOULD suspend
+    rerender({ minAge: 30 })
+
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(1)
+    })
+
+    // Verify suspension happened exactly once more
+    expect(suspenseCount).toBe(suspenseCountAfterInitial + 1)
+  })
 })