docs: add ADR-004 TanStack Query migration

- Document migration rationale and trade-offs
- Add TanStack Query patterns to CLAUDE.md
- Include testing patterns and key benefits

Co-Authored-By: Claude

Author: Wintus

CLAUDE.md

@@ -77,6 +77,50 @@ Key implementation details:
 - Fetches in batches via `rvlimit=max` with continuation tokens (`rvcontinue`)
 - Client-side dump processing was considered and rejected due to prohibitive download times (ADR-003)
 
+## TanStack Query Integration (ADR-004)
+
+The application uses TanStack Query for page ID fetching with the following patterns:
+
+### Query Configuration
+
+- **QueryClientProvider** in @src/App.tsx with:
+  - 5-minute `staleTime` for automatic caching
+  - Single retry on failure
+  - ReactQueryDevtools in development mode
+
+### Page ID Fetching Pattern
+
+@src/components/PageTitleInput.tsx:
+- Uses TanStack Pacer's `useDebouncedValue` (300ms) for input debouncing
+- Always renders ErrorBoundary > Suspense > PageIdFetcher (no conditional branching)
+
+@src/components/PageIdFetcher.tsx:
+- Uses `useSuspenseQuery` with query key `['pageId', wikiUrl.href, pageTitle]`
+- Handles empty title inside `queryFn`: returns `null` for empty title (quick-resolving, no Suspense flash)
+- Passes `AbortSignal` from query to `fetchPageId` for request cancellation
+- Throws errors for ErrorBoundary to catch (no inline error handling)
+
+### Key Benefits
+
+- **Request cancellation**: In-flight requests automatically aborted on input change
+- **Automatic caching**: Same page title returns cached result (5min staleTime)
+- **Deduplication**: Multiple components requesting same data share one request
+- **Promise stability**: Query cache handles promise reference stability
+
+### Testing Pattern
+
+All components using queries must be wrapped in `QueryClientProvider`:
+
+```tsx
+const renderWithQuery = (component: React.ReactElement) => {
+  return render(
+    <QueryClientProvider client={queryClient}>
+      {component}
+    </QueryClientProvider>
+  );
+};
+```
+
 ## Testing Requirements (TDD Workflow)
 
 Uses **Vitest** with **in-source testing** pattern. All source files MUST include tests:
@@ -130,6 +174,7 @@ Located in @docs/adr/:
 - **ADR-001**: Removed revision sampling in favor of linear streaming search for code simplicity
 - **ADR-002**: Enabled client-side caching with `maxage` parameter (60s for recent, 600s for historical)
 - **ADR-003**: Rejected client-side dump processing due to prohibitive download speeds
+- **ADR-004**: Migrated to TanStack Query for page ID fetching (replaced useMemo + use() pattern)
 
 ## Deployment
 

docs/adr/004-tanstack-query-migration.md

@@ -0,0 +1,102 @@
+# ADR-004: Migration to TanStack Query
+
+## Status
+
+Accepted
+
+## Context
+
+The application initially used a `useMemo` + `use()` hook pattern for fetching page IDs in `PageTitleInput.tsx`. While functional, this pattern has several issues:
+
+1. **Anti-pattern**: React 19 documentation explicitly warns against creating promises in Client Components
+2. **No request cancellation**: In-flight requests cannot be aborted when dependencies change
+3. **Manual memoization**: Requires careful dependency array management
+4. **Promise recreation**: Every dependency change creates a new promise
+5. **No caching**: Repeated searches for the same title refetch unnecessarily
+6. **Future risk**: React may tighten enforcement of this pattern in future versions
+
+## Decision
+
+Migrate from the `useMemo` + `use()` pattern to TanStack Query with the following architecture:
+
+- Use `useSuspenseQuery` for data fetching (idiomatic React 19 pattern)
+- Use TanStack Pacer's `useDebouncedValue` for input debouncing (300ms)
+- Implement component composition pattern for conditional rendering (since `useSuspenseQuery` doesn't support `enabled` option)
+- Add `AbortSignal` support to `fetchPageId` for proper request cancellation
+- Set 5-minute `staleTime` for automatic caching
+
+## Consequences
+
+### Positive
+
+- **Idiomatic React 19**: Follows official React guidance for data fetching
+- **Automatic caching**: Same title returns cached response (5min staleTime)
+- **Request cancellation**: AbortSignal propagated to fetch, cancels in-flight requests
+- **Promise stability**: Global query cache handles stability automatically
+- **Deduplication**: Multiple components requesting same data share one request
+- **DevTools**: TanStack Query DevTools available for debugging cache/queries
+- **Background refetch**: Configurable stale-while-revalidate behavior
+
+### Negative
+
+- **Bundle size increase**: ~6.3 KB gzipped (77.93 KB → 84.25 KB)
+- **Additional dependency**: Requires TanStack Query and Pacer packages
+- **Increased complexity**: Requires QueryProvider setup and understanding query concepts
+- **Learning curve**: Team needs to understand TanStack Query patterns
+
+### Implementation Details
+
+#### Component Composition Pattern
+
+`PageTitleInput.tsx` always renders the same structure without conditional branching:
+
+```tsx
+<ErrorBoundary fallback={<ErrorFallback />}>
+  <Suspense fallback={<LoadingIndicator />}>
+    <PageIdFetcher wikiUrl={wikiUrl} pageTitle={debouncedTitle} />
+  </Suspense>
+</ErrorBoundary>
+```
+
+`PageIdFetcher.tsx` handles empty title in `queryFn` to avoid Rules of Hooks violations:
+
+```tsx
+const { data: pageId } = useSuspenseQuery({
+  queryKey: ['pageId', wikiUrl.href, pageTitle],
+  queryFn: ({ signal }) => pageTitle ? fetchPageId(wikiUrl, pageTitle, signal) : null,
+});
+```
+
+When `pageTitle` is empty, the `queryFn` returns `null` immediately (no network request, no Suspense flash).
+
+#### AbortSignal Propagation
+
+```tsx
+export async function fetchPageId(
+  baseUrl: URL,
+  pageTitle: string,
+  signal: AbortSignal | null = null,
+): Promise<number> {
+  const response = await fetch(url, { signal });
+  // ...
+}
+```
+
+#### Query Configuration
+
+```tsx
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 5 * 60 * 1000, // 5 minutes
+      retry: 1,
+    },
+  },
+});
+```
+
+## References
+
+- [React 19 Documentation on use() hook](https://react.dev/reference/react/use)
+- [TanStack Query Documentation](https://tanstack.com/query/latest)
+- [TanStack Pacer Documentation](https://tanstack.com/pacer/latest)