feat: overhaul AI devtools hook dashboard (#632)

* feat: overhaul ai devtools

* refactor(ai-client): consolidate devtools coupling, add E2E suite

- Extract bridge construction into buildDevtoolsBridgeOptions helpers on
  ChatClient, GenerationClient, VideoGenerationClient
- Add ChatDevtoolsAwareEventEmitter that auto-attaches run context and
  emits snapshots so clients call this.events.X(...) like normal events
- Ship NoOp bridges by default; tree-shake real bridges into the
  @tanstack/ai-client/devtools subpath entry
- Update React, Vue, Solid, Svelte, Preact hooks to pass the real
  bridge factory
- Expand E2E suite: registration, chat, structured output, tools,
  generation hooks, responsive layout
- Add devtools-name-types tests per framework integration

* ci: apply automated fixes

* fix: resolve eslint errors

- Sort imports alphabetically across ai-client, ai-react, ai-solid,
  ai-vue, and ai-devtools-core
- Drop leading underscore from NoOpGenerationDevtoolsBridge type
  parameter (used in constructor signature)
- Disable no-restricted-syntax on intentional `as unknown as` casts in
  no-op bridge factories and generation result assignment, with reasons
- Remove unnecessary type assertion in devtools.ts (auto-fixed)

* fix(ai-devtools): address PR feedback

- log + preserve raw localStorage payload on fixture parse failure instead
  of silently calling removeItem
- log + report full error name/message from tool-fixture execute, and
  narrow the try block to executeFunc only so unrelated bugs in
  addToolResultForFixture don't masquerade as tool failures
- cap seenEventIds at 10k via FIFO ring buffer to prevent unbounded
  memory growth over the lifetime of long-running sessions; also reset
  the order array in clearHookRegistry
- restore ai-code-mode/vite.config.ts to main (rename detection swapped
  it with ai-client's during the merge); ai-client now correctly
  declares devtools.ts as a separate entry

* docs: require pnpm test:pr locally before opening or updating a PR

Add a mandatory pre-PR quality gate to CLAUDE.md and a new AGENTS.md
(cross-agent file) documenting that `pnpm test:pr` — the exact target set
the CI `PR` workflow runs — must be run and pass locally before pushing.
Falling back on CI as the first signal wastes review cycles when a quick
local run would have caught the failure.

* fix(ai-devtools): address PR review feedback (critical + important + types + comments)

Critical
- ToolFixtureForm: remove dead `'{}' ? : '{}'` ternary leftover from refactor
- ChatDevtoolsBridge.executeFixture: warn when execute=true but no client tool
  is registered instead of silently substituting the saved output
- stringifyFixtureValue / parseFixtureResultContent: log + report the original
  error instead of swallowing JSON.stringify / JSON.parse failures
- devtools-middleware: replace `chunk: any` with a mirrored discriminated
  union (DevtoolsKnownChunk) + isKnownChunk type guard, drop the `as` cast
  on chunk.error, fall back with the raw chunk payload instead of "Unknown
  error" when RUN_ERROR.message is missing
- normalizeRunStatusFromSnapshot: return `null` for unknown statuses and let
  the caller skip + warn instead of silently coercing them to `'updated'`

Important
- Remove unreachable `'unmounted'` HookLifecycle variant + dead filters
- Drop unused `runs` prop on GenerationPanel
- removeHookRecord: also clean up TimelineEvents attached to the hook
- IterationTimeline `totalUsage`: compare on `totalTokens` (not
  prompt+completion) so providers that include reasoning tokens in
  totalTokens don't get their max overwritten by a smaller later reading
- jsonSafeValue / stringifyToolArguments: log + return an explicit
  placeholder instead of returning the original on failure
- No-op bridges: add compile-time parity checks (Exclude<keyof, keyof>)
  so adding a public method to the real bridge fails the build until the
  no-op is updated, instead of becoming a runtime TypeError
- devtools-middleware: wrap every emit with `safeEmit` so a subscriber
  throw can't bubble into the host chat engine
- markEventSeen: warn when a dedupe key falls back entirely to literal
  sentinels; tools:registered: warn when hookName is missing
- hook-registry tests: cover snapshot run backfill (success/error/idle/
  unknown statuses) and lifecycle inference from snapshot state

Type design
- AIDevtoolsGenerationRunStatus union ('idle' | 'generating' | 'success'
  | 'error' | 'cancelled') replacing the previous `status: string` and
  threaded through GenerationDevtoolsCoreState / SnapshotBase / RunPatch
- Drop redundant `unknown | null` on input / videoStatus fields
- Remove `extends Record<string, unknown>` from public snapshot interfaces;
  ClientDevtoolsBridge constraint relaxed to `extends object` and the
  wire-envelope widening is pushed to emitSnapshot
- Drop pointless `as Record<string, unknown>` casts at JsonTree call sites
  (JsonTree's TData accepts arbitrary value)

Comment hygiene
- Strip file-top docblocks and class-banner JSDoc rewriting the PR
  description (devtools-noop, use-real-devtools-bridges, devtools-system-
  prompt-mirror.test, several blocks in devtools.ts)
- Remove "for backward compatibility" / "exactly like it did before the
  devtools work landed" PR-narrative phrases
- Drop ASCII section-banner separators in devtools.ts, use-styles.ts,
  ai-context.tsx
- Compress multi-line JSDoc on short methods to one-liners or remove
  where the name was self-describing
- Strip obvious line-narration comments in ai-context.tsx batching helpers

* fix(ai-devtools): address re-review nits

- formatUnknown / stringifyToolArguments: warn + return explicit
  unserializable-value placeholder (mirroring jsonSafeValue) instead of
  silently returning String(value) on JSON.stringify failure
- Delete dead visibleHooks identity function and the redundant `active`
  summary field (== total after the unmounted lifecycle was removed);
  drop the two duplicate "active" overview metrics so the dashboard grid
  isn't showing the same number under three labels
- Strip remaining "what"-narration comments in ai-context.tsx and the
  section-divider comments in use-styles.ts

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Revert "fix(ai-devtools): address re-review nits"

This reverts commit 6ae5aaf.

* fix(ai-devtools): surface unserializable values in placeholder helpers

formatUnknown and stringifyToolArguments previously fell back to
String(value) (yielding "[object Object]") on JSON.stringify failure.
Mirror the jsonSafeValue pattern: warn with the original error and
return a self-describing placeholder so the failure is visible in both
the console and the rendered devtools panel.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Tom Beckenham <34339192+tombeckenham@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 4 people

.changeset/ai-devtools-hook-dashboard.md

@@ -0,0 +1,12 @@
+---
+'@tanstack/ai-client': minor
+'@tanstack/ai-devtools-core': minor
+'@tanstack/ai-event-client': minor
+'@tanstack/ai-preact': patch
+'@tanstack/ai-react': patch
+'@tanstack/ai-solid': patch
+'@tanstack/ai-svelte': patch
+'@tanstack/ai-vue': patch
+---
+
+Add hook-aware AI devtools registration, run tracking, state snapshots, and tool fixture replay.

AGENTS.md

@@ -0,0 +1,42 @@
+# AGENTS.md
+
+Cross-agent guidance for this repository. See `CLAUDE.md` for the full project
+overview, architecture, and conventions — this file mirrors the rules that
+apply to every coding agent regardless of tool.
+
+## Pre-PR Quality Gate (MANDATORY)
+
+**Before opening a PR or pushing changes intended for review, you MUST run the
+same checks CI runs and confirm they pass locally.** Pushing without running
+these is not acceptable — CI will fail and waste review cycles.
+
+The single canonical command is:
+
+```bash
+pnpm test:pr
+```
+
+This runs the exact target set the `PR` workflow runs in CI
+(`nx affected --targets=test:sherif,test:knip,test:docs,test:eslint,test:lib,test:types,test:build,build --exclude=examples/**,testing/**`).
+
+If you can't run `test:pr` (e.g. it's too slow on your machine), at minimum run
+each of these and confirm they're green before pushing:
+
+- `pnpm test:sherif` — workspace consistency
+- `pnpm test:knip` — unused dependencies
+- `pnpm test:docs` — doc link verification
+- `pnpm test:eslint` — lint
+- `pnpm test:types` — typecheck
+- `pnpm test:lib` — unit tests
+- `pnpm test:build` — build artifact verification
+- `pnpm build` — build all affected packages
+- `pnpm --filter @tanstack/ai-e2e test:e2e` — E2E suite (mandatory for any
+  behavior change; see `testing/e2e/README.md`)
+
+Do **not** rely on CI as your first signal. Run locally, fix, then push.
+
+## Everything Else
+
+For package manager (`pnpm@10.17.0`), monorepo layout, adapter architecture,
+tool system, framework integrations, E2E requirements, and all other
+conventions, read `CLAUDE.md` in this directory.

CLAUDE.md

@@ -215,6 +215,32 @@ Each framework integration uses the headless `ai-client` under the hood.
 8. Format code: `pnpm format`
 9. Verify build: `pnpm test:build` or `pnpm build`
 
+### Pre-PR Quality Gate (MANDATORY)
+
+**Before opening a PR or pushing changes intended for review, you MUST run the same checks CI runs and confirm they pass locally.** Pushing without running these is not acceptable — CI will fail and waste review cycles.
+
+The single canonical command is:
+
+```bash
+pnpm test:pr
+```
+
+This runs the exact target set the `PR` workflow runs in CI (`nx affected --targets=test:sherif,test:knip,test:docs,test:eslint,test:lib,test:types,test:build,build --exclude=examples/**,testing/**`).
+
+If you can't run `test:pr` (e.g. it's too slow on your machine), at minimum run each of these and confirm they're green before pushing:
+
+- `pnpm test:sherif` — workspace consistency
+- `pnpm test:knip` — unused dependencies
+- `pnpm test:docs` — doc link verification
+- `pnpm test:eslint` — lint
+- `pnpm test:types` — typecheck
+- `pnpm test:lib` — unit tests
+- `pnpm test:build` — build artifact verification
+- `pnpm build` — build all affected packages
+- `pnpm --filter @tanstack/ai-e2e test:e2e` — E2E suite (mandatory for any behavior change; see E2E Testing)
+
+Do **not** rely on CI as your first signal. Run locally, fix, then push.
+
 ### Working with Examples
 
 Examples are not built by Nx. To run an example:

docs/getting-started/devtools.md

@@ -16,11 +16,68 @@ keywords:
 TanStack Devtools is a unified devtools panel for inspecting and debugging TanStack libraries, including TanStack AI. It provides real-time insights into AI interactions, tool calls, and state changes, making it easier to develop and troubleshoot AI-powered applications.
 
 ## Features
+- **Hook dashboard** - Discover every active TanStack AI hook on the page, including chat, structured output, image, video, audio, speech, transcription, and summarize hooks.
+- **Run timeline** - Inspect user turns, linked runs, stream events, client snapshots, and server-only events by `threadId` and `runId`.
 - **Real-time Monitoring** - View live chat messages, tool invocations, and AI responses.
 - **Tool Call Inspection** - Inspect input and output of tool calls.
+- **Tool Fixture Replay** - Build tool payloads from a tool's standard-schema input, append the result into chat messages, and save fixtures in localStorage for repeated UI iteration.
 - **State Visualization** - Visualize chat state and message history.
 - **Error Tracking** - Monitor errors and exceptions in AI interactions.
 
+## Hook Dashboard
+
+The AI devtools panel listens for active TanStack AI clients and shows them in the left sidebar. Hooks register when they are created, emit a snapshot immediately, and respond again whenever the devtools panel opens or requests state. This keeps hooks discoverable even when the panel is opened after the app has already rendered.
+
+Each hook entry includes its type, lifecycle, message count, run count, and the latest linked `threadId`. Selecting a hook opens the full timeline for that hook. Chat hooks keep the current turn-based view: a user message wraps every run and event that happened while answering that turn. The details view also includes lightweight client/server state snapshots between runs so you can see exactly what changed.
+
+### Naming Hooks
+
+When a page has more than one AI hook, pass `devtools.name` to give each hook a user-facing label in the dashboard. The configured name is display-only; hook type, framework, thread id, and run correlation still come from the TanStack AI client.
+
+```tsx
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+
+export function SupportChat() {
+  const chat = useChat({
+    id: 'support-chat',
+    connection: fetchServerSentEvents('/api/chat'),
+    devtools: {
+      name: 'Support Chat',
+    },
+  })
+
+  // render your chat UI with `chat.messages`, `chat.sendMessage`, etc.
+}
+```
+
+The same display option works for specialized generation hooks:
+
+```tsx
+import { fetchServerSentEvents, useGenerateImage } from '@tanstack/ai-react'
+
+export function ImageStudio() {
+  const image = useGenerateImage({
+    id: 'generation-hooks:useGenerateImage',
+    connection: fetchServerSentEvents('/api/image'),
+    devtools: {
+      name: 'Image Studio',
+    },
+  })
+
+  // render your image generation UI with `image.generate` and `image.result`
+}
+```
+
+## Tool Fixtures
+
+When a `useChat` hook receives tools, the devtools panel lists those tools and their schemas. For standard-schema-compatible inputs, the panel renders a small form from the input schema so you can create a tool call payload without hand-writing JSON.
+
+Applying a tool fixture appends the tool call and result into the real chat messages for that hook. Saved fixtures are stored in browser localStorage under the AI devtools namespace so they are available the next time you open the panel.
+
+## Event Sources
+
+Client-visible state is emitted by the headless client. Server-only details, such as middleware and provider stream events that never exist on the client, are emitted from the server counterpart. Events include a source descriptor and stable envelope id so the panel can link related events and avoid displaying duplicates.
+
 ## Installation
 To use TanStack Devtools with TanStack AI, install the `@tanstack/react-ai-devtools` package:
 

examples/ts-react-chat/src/components/Header.tsx

@@ -2,6 +2,7 @@ import { Link } from '@tanstack/react-router'
 
 import { useState } from 'react'
 import {
+  Activity,
   Braces,
   FileAudio,
   FileText,
@@ -76,6 +77,19 @@ export default function Header() {
             Generations
           </p>
 
+          <Link
+            to="/generation-hooks"
+            onClick={() => setIsOpen(false)}
+            className="flex items-center gap-3 p-3 rounded-lg hover:bg-gray-800 transition-colors mb-1"
+            activeProps={{
+              className:
+                'flex items-center gap-3 p-3 rounded-lg bg-cyan-600 hover:bg-cyan-700 transition-colors mb-1',
+            }}
+          >
+            <Activity size={20} />
+            <span className="font-medium">Generation Hooks</span>
+          </Link>
+
           <Link
             to="/generations/image"
             onClick={() => setIsOpen(false)}

examples/ts-react-chat/src/routeTree.gen.ts

@@ -13,6 +13,7 @@ import { Route as ServerFnChatRouteImport } from './routes/server-fn-chat'
 import { Route as RealtimeRouteImport } from './routes/realtime'
 import { Route as Issue176ToolResultRouteImport } from './routes/issue-176-tool-result'
 import { Route as ImageGenRouteImport } from './routes/image-gen'
+import { Route as GenerationHooksRouteImport } from './routes/generation-hooks'
 import { Route as IndexRouteImport } from './routes/index'
 import { Route as GenerationsVideoRouteImport } from './routes/generations.video'
 import { Route as GenerationsTranscriptionRouteImport } from './routes/generations.transcription'
@@ -55,6 +56,11 @@ const ImageGenRoute = ImageGenRouteImport.update({
   path: '/image-gen',
   getParentRoute: () => rootRouteImport,
 } as any)
+const GenerationHooksRoute = GenerationHooksRouteImport.update({
+  id: '/generation-hooks',
+  path: '/generation-hooks',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const IndexRoute = IndexRouteImport.update({
   id: '/',
   path: '/',
@@ -166,6 +172,7 @@ const ApiGenerateAudioRoute = ApiGenerateAudioRouteImport.update({
 
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
+  '/generation-hooks': typeof GenerationHooksRoute
   '/image-gen': typeof ImageGenRoute
   '/issue-176-tool-result': typeof Issue176ToolResultRoute
   '/realtime': typeof RealtimeRoute
@@ -193,6 +200,7 @@ export interface FileRoutesByFullPath {
 }
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
+  '/generation-hooks': typeof GenerationHooksRoute
   '/image-gen': typeof ImageGenRoute
   '/issue-176-tool-result': typeof Issue176ToolResultRoute
   '/realtime': typeof RealtimeRoute
@@ -221,6 +229,7 @@ export interface FileRoutesByTo {
 export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/': typeof IndexRoute
+  '/generation-hooks': typeof GenerationHooksRoute
   '/image-gen': typeof ImageGenRoute
   '/issue-176-tool-result': typeof Issue176ToolResultRoute
   '/realtime': typeof RealtimeRoute
@@ -250,6 +259,7 @@ export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
   fullPaths:
     | '/'
+    | '/generation-hooks'
     | '/image-gen'
     | '/issue-176-tool-result'
     | '/realtime'
@@ -277,6 +287,7 @@ export interface FileRouteTypes {
   fileRoutesByTo: FileRoutesByTo
   to:
     | '/'
+    | '/generation-hooks'
     | '/image-gen'
     | '/issue-176-tool-result'
     | '/realtime'
@@ -304,6 +315,7 @@ export interface FileRouteTypes {
   id:
     | '__root__'
     | '/'
+    | '/generation-hooks'
     | '/image-gen'
     | '/issue-176-tool-result'
     | '/realtime'
@@ -332,6 +344,7 @@ export interface FileRouteTypes {
 }
 export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
+  GenerationHooksRoute: typeof GenerationHooksRoute
   ImageGenRoute: typeof ImageGenRoute
   Issue176ToolResultRoute: typeof Issue176ToolResultRoute
   RealtimeRoute: typeof RealtimeRoute
@@ -388,6 +401,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ImageGenRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/generation-hooks': {
+      id: '/generation-hooks'
+      path: '/generation-hooks'
+      fullPath: '/generation-hooks'
+      preLoaderRoute: typeof GenerationHooksRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/': {
       id: '/'
       path: '/'
@@ -540,6 +560,7 @@ declare module '@tanstack/react-router' {
 
 const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
+  GenerationHooksRoute: GenerationHooksRoute,
   ImageGenRoute: ImageGenRoute,
   Issue176ToolResultRoute: Issue176ToolResultRoute,
   RealtimeRoute: RealtimeRoute,