feat(PowerSync): add attachments support

.changeset/calm-oracles-check-loss.md

@@ -0,0 +1,17 @@
+---
+'@tanstack/db': patch
+'@tanstack/db-sqlite-persistence-core': patch
+'@tanstack/electric-db-collection': patch
+---
+
+Harden Electric resume and lifecycle handling so partial updates cannot materialize unknown or moved-out rows, stale async work and waiters cannot cross cleanup or restart—including automatic garbage collection—and valid batches behave the same across callback partitions and persistence hydration.
+
+Preserve hydrated baseline rows during persistence reloads, accept complete-row updates from explicit full-replica resumes, retain committed match evidence until reset, and restart persisted resumes when hydration completion cannot be verified.
+
+Replace stale cached rows atomically when an invalid resume falls back to a fresh snapshot. Keep subset acquisitions from restoring logically removed rows, and isolate utilities and tag visibility when collection options are reused while preserving compatible same-collection resume state.
+
+Accept partial updates to complete rows published independently by persistence, while preserving pending removal and reset boundaries. Avoid copying all applied keys at startup or each subset acquisition; presence checks overlay queued writes and buffered messages once per stream callback. Warn once when an older persistence adapter cannot verify hydration for safe resume.
+
+Keep buffered tag move-outs inside the progressive snapshot's existing transaction so later live updates are not discarded behind an orphaned truncate.
+
+Keep copied materialized configs and reentrant match callbacks scoped to their owning collection session. Cold tagged or legacy persisted state now recovers with a full snapshot behind cached rows, including in on-demand mode. Keep the reset marker through interrupted recovery and publish the replacement only after the full snapshot completes; known untagged and compatible warm resumes retain their saved offset.

.changeset/curly-planets-lead.md

@@ -0,0 +1,6 @@
+---
+'@tanstack/powersync-db-collection': minor
+---
+
+Add attachments support via `TanStackDBAttachmentQueue`. This extends the PowerSync SDK's `AttachmentQueue` and backs it with
+a TanStack DB collection, so attachment metadata and related rows commit atomically. Local files and remote uploads/deletes are managed separately.

.changeset/finish-review-recovery.md

@@ -0,0 +1,11 @@
+---
+'@tanstack/db': patch
+'@tanstack/db-sqlite-persistence-core': patch
+'@tanstack/powersync-db-collection': patch
+---
+
+Preserve native values, arbitrary class references, and draft cycles during mutation detachment; keep transaction persistence receipts settled after publication errors and avoid restoring an acknowledged direct insert over its server row. Keep a delete/reinsert visible when the old synced row has not yet been replaced.
+
+Retire replaced ordered prefixes without interrupting successful-load bookkeeping if release throws. Retry automatic ordered repair at most twice while retaining stale results and exposing the error; cleanup cancels retries and explicit window retry remains available.
+
+Keep persisted acquisitions independent, avoid retaining one-shot refreshes as permanent demand, and reject upstream load failures without discarding cached rows. Restore PowerSync readiness only after the recovered baseline also removes rows deleted or moved outside active filters during the tracking outage.

.changeset/fix-optimistic-field-reconciliation.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/db': patch
+---
+
+Preserve whole-row optimistic snapshots through sync and truncate. Fix insert-dependent update settlement, local origin tracking, and rollback publication while sibling requests remain pending. Keep source updates beneath an optimistic live-query delete when queued sync batches apply, without changing sync queue timing.

.changeset/fix-trailbase-stream-lifetimes.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/trailbase-db-collection': patch
+---
+
+Fix unhandled rejections and resource leaks when a TrailBase subscription closes, fails, or is cleaned up. Drain buffered events before releasing the reader and prevent a canceled startup from canceling a replacement sync session.

.changeset/lucky-donkeys-repeat.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/db': patch
+---
+
+Reclaim collections that start syncing without subscribers, releasing unused live-query subscriptions after a minimum 50ms grace period. Keep pending preloads alive until they settle and refresh retention when preloading ready data; `gcTime: 0` continues to disable automatic GC. Keep detached observer snapshots fresh after empty reloads and allow Node processes to exit while background collection cleanup is pending.

.changeset/powersync-attachment-startup-ownership.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/powersync-db-collection': patch
+---
+
+Load attachment IDs before save/delete in eager and on-demand collections. Preserve existing files when a duplicate save is rejected, reject overlapping saves of the same ID across queues sharing a database, and clean up partial local writes.

.changeset/reject-ignored-page-callback.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/react-db': minor
+'@tanstack/vue-db': minor
+'@tanstack/svelte-db': minor
+---
+
+Remove the ignored `getNextPageParam` option from `useLiveInfiniteQuery` and reject it with a clear error when passed at runtime. Delete this callback from your config; for server pagination, use an on-demand Query Collection whose `queryFn` fulfills `meta.loadSubsetOptions`. Document fixed-server-page loading and clarify that `initialPageParam` labels result pages rather than setting a server cursor.

.github/SSR_RELEASE_PLAN.md

@@ -0,0 +1,69 @@
+# TanStack DB SSR Release Plan
+
+## Release Goal
+
+Ship TanStack DB SSR as a single coherent story:
+
+- explicit collection-row hydration and live-query result snapshots through
+  `DbClient`
+- React and Svelte provider and descriptor resolution
+- derived live query identity with `queryKey` only when necessary
+- backwards-compatible dependency arrays with dev warnings until 1.0
+- a working TanStack Start demo and E2E proof
+
+## Pre-release Validation
+
+- Run `pnpm --filter @tanstack/db test`.
+- Run `pnpm --filter @tanstack/react-db test`.
+- Run `pnpm --filter @tanstack/svelte-db test`.
+- Run `pnpm --filter @tanstack/react-router-with-db test` (includes type
+  tests).
+- Run `pnpm --filter @tanstack/query-db-collection test`.
+- Run `pnpm --filter @tanstack/db-sqlite-persistence-core test`.
+- Run `pnpm --filter @tanstack/db-example-react-start-ssr-e2e test:e2e`.
+- Run `pnpm --filter @tanstack/db-example-react-next-ssr-e2e test:e2e`.
+- Run `pnpm test:docs`.
+- Run `pnpm test:sherif`.
+- Run `pnpm build`.
+
+## Demo
+
+- Live URL: https://tanstack-db-ssr-demo.netlify.app/ssr-db
+- Deploy `examples/react/start-ssr-e2e` to an SSR-capable host.
+- Verify the deployed `/ssr-db` route serves SSR HTML with hydrated rows.
+- Verify browser hydration succeeds without console/page errors.
+- Verify the streamed collection chunk updates the live query.
+- Verify `/ssr-db-stream` streams a projected result, omits source-only data,
+  and hands off to browser sync.
+- Run `PLAYWRIGHT_BASE_URL=https://tanstack-db-ssr-demo.netlify.app pnpm --filter @tanstack/db-example-react-start-ssr-e2e test:e2e:hosted`.
+- Add the live URL to the PR description and release notes.
+
+## Docs
+
+- Publish the [SSR and Hydration guide](../docs/guides/ssr.md).
+- Link the guide from overview, quick start, live queries, and React overview.
+- Regenerate API reference docs in a dedicated docs-maintenance pass if broad
+  TypeDoc output churn is acceptable.
+- Confirm docs explain when `queryKey` is necessary and when it should be
+  omitted.
+- Confirm docs say dependency arrays warn now and are removed in 1.0.
+
+## Migration Messaging
+
+- Lead with: explicit collection preloads transport normalized rows; live-query
+  preloads transport only their result snapshot.
+- Emphasize that existing apps keep working.
+- State that `createCollection(...)` remains available, but SSR apps should use
+  `collectionOptions(...)` plus `DbClient`.
+- Explain that React dependency arrays are deprecated with a 1.0 removal path.
+- Show `queryKey` only for opaque functional query logic or hot render paths.
+
+## Announcement Checklist
+
+- PR description includes high-level summary, migration cheat sheet, and test
+  commands.
+- Release notes include a "No removals in this release" compatibility section.
+- Discord announcement links the SSR guide and live demo.
+- Example migration diff is available from the Start SSR demo.
+- Follow-up issues are filed for the remaining framework adapters and API
+  reference generation if they are not part of the shipping PR.

.github/workflows/e2e-tests.yml

@@ -45,6 +45,7 @@ jobs:
         run: |
           pnpm --filter @tanstack/db-ivm build
           pnpm --filter @tanstack/db build
+          pnpm --filter @tanstack/react-db build
           pnpm --filter @tanstack/electric-db-collection build
           pnpm --filter @tanstack/offline-transactions build
           pnpm --filter @tanstack/query-db-collection build
@@ -68,6 +69,21 @@ jobs:
         env:
           ELECTRIC_URL: http://localhost:3000
 
+      - name: Install Playwright browsers
+        run: |
+          cd examples/react/start-ssr-e2e
+          pnpm exec playwright install --with-deps chromium
+
+      - name: Run React Start SSR E2E tests
+        run: |
+          cd examples/react/start-ssr-e2e
+          pnpm test:e2e
+
+      - name: Run Next.js SSR E2E tests
+        run: |
+          cd examples/react/next-ssr-e2e
+          pnpm test:e2e
+
       - name: Run Node SQLite persisted collection E2E tests
         run: |
           cd packages/node-db-sqlite-persistence

.gitignore

@@ -10,6 +10,8 @@ yarn.lock
 build
 coverage
 dist
+playwright-report
+test-results
 
 # misc
 .DS_Store
@@ -19,6 +21,7 @@ dist
 .env.test.local
 .env.production.local
 .next
+next-env.d.ts
 
 npm-debug.log*
 yarn-debug.log*

AGENTS.md

@@ -2,6 +2,17 @@
 
 This guide provides principles and patterns for AI agents contributing to the TanStack DB codebase. These guidelines are derived from PR review patterns and reflect the quality standards expected in this project.
 
+## Required reading: live-query materialization
+
+Before reading, analyzing, or modifying correlated live-query materialization
+code under `packages/db/src/query/live/`, read
+`packages/db/src/query/live/ARCHITECTURE.md` in full. Read it before changing
+the related includes oracle tests as well.
+
+Treat that document's component boundaries and normative laws as constraints.
+If a change intentionally revises an architectural contract, update the
+architecture document in the same pull request.
+
 ## Table of Contents
 
 1. [Type Safety](#type-safety)
@@ -351,7 +362,8 @@ const dependentBuilders = [] // Accurately describes dependents
 
 ### Always Add Tests for Bugs
 
-**Key Principle:** If you're fixing a bug, add a unit test that reproduces the bug before fixing it. This ensures:
+**Key Principle:** Reproduce a bug in a test before fixing it. Prefer extending
+an oracle as described below over adding an isolated unit test. This ensures:
 
 - The bug is actually fixed
 - The bug doesn't regress in the future
@@ -368,6 +380,60 @@ test('ignores snapshot that resolves after up-to-date message', async () => {
 })
 ```
 
+### Treat Every Review Bug as a Test Gap
+
+When a reviewer agent confirms a bug, it must also ask why the existing tests
+did not catch it. The finding should name the missing test law, state
+transition, generator dimension, adapter boundary, or assertion. If a test or
+oracle should already have caught the bug, identify the false-green model,
+classifier, fixture, or assertion that let it pass. Use that analysis to suggest
+the smallest test or oracle improvement that would catch the same class of bug,
+not only the reported example.
+
+### Keep Oracles Independent
+
+An oracle is useful only when its expected result comes from a source independent
+of the implementation under test. Do not translate production branches, state
+machines, classifiers, or helper functions into a second implementation and call
+that an oracle. Both copies can encode the same wrong assumption.
+
+- Derive expected behavior from public contracts, documented prior behavior,
+  mathematical laws, or a separately specified reference model.
+- Keep the reference model structurally different from production. Do not import
+  the production helper or reuse its classifications to compute expected results.
+- Preserve existing contract tests unless a product or design decision explicitly
+  changes the contract. Rewriting a passing expectation to match new production
+  behavior is a design review, not routine test maintenance.
+- When production work suggests an oracle change, compare the old and new
+  semantics with counterexamples before editing the oracle.
+- Use hostile mutants to prove the oracle rejects plausible wrong designs,
+  including the mistake production currently makes. A green oracle without a
+  demonstrated kill is weak evidence.
+- Use process grammar to explore lifecycle paths, and design grammar to challenge
+  the oracle's reference semantics. More generated traces cannot repair a wrong
+  reference model.
+
+### Prefer Oracle Coverage Over Isolated Regressions
+
+An oracle that checks general laws across generated states and histories is a
+stronger form of coverage than a unit test for one specific example. Prefer
+extending an existing oracle when it can cover the behavior. Add the missing
+model rule, generator dimension, state transition, or observable assertion;
+adding more pinned examples alone does not generalize the oracle.
+
+Use a focused regression to isolate and shrink a failure, then keep it as a
+replay example for the broader oracle where possible. Verify that the expanded
+oracle fails without the fix and passes with it. Keep valuable unit tests, but
+do not treat them as a substitute for applicable oracle coverage. If an oracle
+is not practical for the behavior, explain why a focused test is sufficient.
+
+### Name Tests After Behavior
+
+Test names should state the behavior they prove. Do not put issue or pull
+request numbers in test names; those references become stale and make the test
+suite harder to read. When an external report contains essential context that
+the test cannot express, link it in a nearby comment instead.
+
 ### Test Corner Cases
 
 Common corner cases to consider: