TanStack
diff --git a/‎.changeset/thick-ghosts-burn.md‎
Lines changed: 5 additions & 0 deletions b/‎.changeset/thick-ghosts-burn.md‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎.github/workflows/e2e.yml‎
Lines changed: 77 additions & 0 deletions b/‎.github/workflows/e2e.yml‎
Lines changed: 77 additions & 0 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 47 additions & 5 deletions b/‎CLAUDE.md‎
Lines changed: 47 additions & 5 deletions
diff --git a/‎knip.json‎
Lines changed: 0 additions & 5 deletions b/‎knip.json‎
Lines changed: 0 additions & 5 deletions
diff --git a/‎packages/typescript/ai-ollama/src/adapters/text.ts‎
Lines changed: 18 additions & 7 deletions b/‎packages/typescript/ai-ollama/src/adapters/text.ts‎
Lines changed: 18 additions & 7 deletions
diff --git a/‎packages/typescript/ai-ollama/src/utils/client.ts‎
Lines changed: 2 additions & 0 deletions b/‎packages/typescript/ai-ollama/src/utils/client.ts‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎packages/typescript/smoke-tests/adapters/.env.example‎
Lines changed: 0 additions & 31 deletions b/‎packages/typescript/smoke-tests/adapters/.env.example‎
Lines changed: 0 additions & 31 deletions
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-ollama': patch
+---
+
+Add `headers` support to `OllamaClientConfig` and `createOllamaChat`. The Ollama SDK already accepts `config.headers` and passes them on every request — this change exposes the option through the TanStack AI adapter, enabling custom headers like `X-Test-Id` for test isolation.
@@ -0,0 +1,77 @@
+name: E2E Tests
+
+on:
+  pull_request:
+  push:
+    branches: [main, alpha, beta, rc]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
+
+permissions:
+  contents: read
+
+jobs:
+  e2e:
+    name: E2E Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6.0.2
+        with:
+          fetch-depth: 0
+
+      - name: Setup Tools
+        uses: TanStack/config/.github/setup@main
+
+      - name: Cache Playwright Browsers
+        id: playwright-cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ hashFiles('testing/e2e/package.json') }}
+          restore-keys: |
+            playwright-
+
+      - name: Build Packages
+        run: pnpm run build:all
+
+      - name: Install Playwright Chromium
+        if: steps.playwright-cache.outputs.cache-hit != 'true'
+        run: pnpm --filter @tanstack/ai-e2e exec playwright install --with-deps chromium
+
+      - name: Install Playwright Deps (if cached)
+        if: steps.playwright-cache.outputs.cache-hit == 'true'
+        run: pnpm --filter @tanstack/ai-e2e exec playwright install-deps chromium
+
+      - name: Run E2E Tests
+        run: pnpm --filter @tanstack/ai-e2e test:e2e
+
+      - name: Upload Video Recordings
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: e2e-videos
+          path: testing/e2e/test-results/**/*.webm
+          retention-days: 14
+
+      - name: Upload Playwright Report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: e2e-report
+          path: testing/e2e/playwright-report/
+          retention-days: 14
+
+      - name: Upload Traces (on failure)
+        uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: e2e-traces
+          path: testing/e2e/test-results/**/*.zip
+          retention-days: 14
@@ -36,6 +36,10 @@ pnpm test:coverage         # Generate coverage reports
 pnpm test:knip             # Check for unused dependencies
 pnpm test:sherif           # Check pnpm workspace consistency
 pnpm test:docs             # Verify documentation links
+
+# E2E tests (required for all changes)
+pnpm --filter @tanstack/ai-e2e test:e2e    # Run E2E tests
+pnpm --filter @tanstack/ai-e2e test:e2e:ui # Run with Playwright UI
 ```
 
 ### Testing Individual Packages
@@ -100,6 +104,10 @@ packages/
 ├── php/                 # PHP packages (future)
 └── python/              # Python packages (future)
 
+testing/
+├── e2e/                 # E2E tests (Playwright + aimock) — MANDATORY for all changes
+└── panel/               # Vendor integration panel
+
 examples/                # Example applications
 ├── ts-react-chat/       # React chat example
 ├── ts-solid-chat/       # Solid chat example
@@ -204,11 +212,13 @@ Each framework integration uses the headless `ai-client` under the hood.
 
 1. Create a changeset: `pnpm changeset`
 2. Make changes in the appropriate package(s)
-3. Run tests: `pnpm test:lib` (or package-specific tests)
-4. Run type checks: `pnpm test:types`
-5. Run linter: `pnpm test:eslint`
-6. Format code: `pnpm format`
-7. Verify build: `pnpm test:build` or `pnpm build`
+3. **Add or update E2E tests** (see E2E Testing below) — this is mandatory for any feature, bug fix, or behavior change
+4. Run tests: `pnpm test:lib` (or package-specific tests)
+5. Run E2E tests: `pnpm --filter @tanstack/ai-e2e test:e2e`
+6. Run type checks: `pnpm test:types`
+7. Run linter: `pnpm test:eslint`
+8. Format code: `pnpm format`
+9. Verify build: `pnpm test:build` or `pnpm build`
 
 ### Working with Examples
 
@@ -247,6 +257,38 @@ Each package uses `exports` field in package.json for subpath exports (e.g., `@t
 - Unit tests in `*.test.ts` files alongside source
 - Uses Vitest with happy-dom for DOM testing
 - Test coverage via `pnpm test:coverage`
+- **E2E tests are mandatory** — see E2E Testing section below
+
+### E2E Testing (REQUIRED)
+
+**Every feature, bug fix, or behavior change MUST include E2E test coverage.** The E2E suite lives at `testing/e2e/` and uses Playwright + [aimock](https://github.com/CopilotKit/aimock) for deterministic LLM mocking.
+
+```bash
+# Run all E2E tests
+pnpm --filter @tanstack/ai-e2e test:e2e
+
+# Run with Playwright UI (for debugging)
+pnpm --filter @tanstack/ai-e2e test:e2e:ui
+
+# Run a specific spec
+pnpm --filter @tanstack/ai-e2e test:e2e -- --grep "openai -- chat"
+
+# Record real LLM responses as fixtures
+OPENAI_API_KEY=sk-... pnpm --filter @tanstack/ai-e2e record
+```
+
+**What to add for your change:**
+
+| Change type                             | What E2E test to add                                                                      |
+| --------------------------------------- | ----------------------------------------------------------------------------------------- |
+| New provider adapter                    | Add provider to `feature-support.ts` + `test-matrix.ts`. Existing feature tests auto-run. |
+| New feature (e.g., new generation type) | Add feature to types, feature config, support matrix. Create fixture + spec file.         |
+| Bug fix in chat/streaming               | Add a test case to `chat.spec.ts` or `tools-test/` that reproduces the bug.               |
+| Tool system change                      | Add scenario to `tools-test-scenarios.ts` + test in `tools-test/` specs.                  |
+| Middleware change                       | Add test to `middleware.spec.ts` with appropriate scenario.                               |
+| Client-side change (useChat, etc.)      | Add test covering the observable behavior change.                                         |
+
+**Guide:** See `testing/e2e/README.md` for full instructions on adding tests, recording fixtures, and troubleshooting.
 
 ### Documentation
 
 
@@ -4,7 +4,6 @@
   "ignoreWorkspaces": [
     "examples/**",
     "testing/**",
-    "**/smoke-tests/**",
     "packages/typescript/ai-code-mode/models-eval"
   ],
   "ignore": [
@@ -16,10 +15,6 @@
     "packages/typescript/ai-openai/src/audio/audio-provider-options.ts",
     "packages/typescript/ai-openai/src/audio/transcribe-provider-options.ts",
     "packages/typescript/ai-openai/src/image/image-provider-options.ts",
-    "packages/typescript/smoke-tests/adapters/src/**",
-    "packages/typescript/smoke-tests/e2e/playwright.config.ts",
-    "packages/typescript/smoke-tests/e2e/src/**",
-    "packages/typescript/smoke-tests/e2e/vite.config.ts",
     "packages/typescript/ai-devtools/src/production.ts"
   ],
   "ignoreExportsUsedInFile": true,
 
@@ -1,6 +1,7 @@
 import { BaseTextAdapter } from '@tanstack/ai/adapters'
 
 import { createOllamaClient, generateId, getOllamaHostFromEnv } from '../utils'
+import type { OllamaClientConfig } from '../utils/client'
 
 import type {
   OLLAMA_TEXT_MODELS,
@@ -119,12 +120,22 @@ export class OllamaTextAdapter<TModel extends string> extends BaseTextAdapter<
 
   private client: Ollama
 
-  constructor(hostOrClient: string | Ollama | undefined, model: TModel) {
+  constructor(
+    hostOrClientOrConfig: string | Ollama | OllamaClientConfig | undefined,
+    model: TModel,
+  ) {
     super({}, model)
-    if (typeof hostOrClient === 'string' || hostOrClient === undefined) {
-      this.client = createOllamaClient({ host: hostOrClient })
+    if (
+      typeof hostOrClientOrConfig === 'string' ||
+      hostOrClientOrConfig === undefined
+    ) {
+      this.client = createOllamaClient({ host: hostOrClientOrConfig })
+    } else if ('chat' in hostOrClientOrConfig) {
+      // Ollama client instance (has a chat method)
+      this.client = hostOrClientOrConfig
     } else {
-      this.client = hostOrClient
+      // OllamaClientConfig object
+      this.client = createOllamaClient(hostOrClientOrConfig)
     }
   }
 
@@ -476,14 +487,14 @@ export class OllamaTextAdapter<TModel extends string> extends BaseTextAdapter<
 }
 
 /**
- * Creates an Ollama chat adapter with explicit host.
+ * Creates an Ollama chat adapter with explicit host and optional config.
  * Type resolution happens here at the call site.
  */
 export function createOllamaChat<TModel extends string>(
   model: TModel,
-  host?: string,
+  hostOrConfig?: string | OllamaClientConfig,
 ): OllamaTextAdapter<TModel> {
-  return new OllamaTextAdapter(host, model)
+  return new OllamaTextAdapter(hostOrConfig, model)
 }
 
 /**
 
@@ -2,6 +2,7 @@ import { Ollama } from 'ollama'
 
 export interface OllamaClientConfig {
   host?: string
+  headers?: Record<string, string>
 }
 
 /**
@@ -10,6 +11,7 @@ export interface OllamaClientConfig {
 export function createOllamaClient(config: OllamaClientConfig = {}): Ollama {
   return new Ollama({
     host: config.host || 'http://localhost:11434',
+    headers: config.headers,
   })
 }
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@tanstack/ai-ollama': patch
 +---
++
 +Add `headers` support to `OllamaClientConfig` and `createOllamaChat`. The Ollama SDK already accepts `config.headers` and passes them on every request — this change exposes the option through the TanStack AI adapter, enabling custom headers like `X-Test-Id` for test isolation.
Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,7 @@ import { Ollama } from 'ollama'`
`2`	`2`
`3`	`3`	`export interface OllamaClientConfig {`
`4`	`4`	`host?: string`
	`5`	`+ headers?: Record<string, string>`
`5`	`6`	`}`
`6`	`7`
`7`	`8`	`/**`
`@@ -10,6 +11,7 @@ export interface OllamaClientConfig {`
`10`	`11`	`export function createOllamaClient(config: OllamaClientConfig = {}): Ollama {`
`11`	`12`	`return new Ollama({`
`12`	`13`	`host: config.host \|\| 'http://localhost:11434',`
	`14`	`+ headers: config.headers,`
`13`	`15`	`})`
`14`	`16`	`}`
`15`	`17`