@tanstack/devtools-utils 0.3.2 → 0.3.4

package/bin/intent.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// Auto-generated by @tanstack/intent setup
+// Exposes the intent end-user CLI for consumers of this library.
+// Commit this file, then add to your package.json:
+//   "bin": { "intent": "./bin/intent.js" }
+try {
+  await import('@tanstack/intent/intent-library')
+} catch (e) {
+  if (e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND') {
+    console.error('@tanstack/intent is not installed.')
+    console.error('')
+    console.error('Install it as a dev dependency:')
+    console.error('  npm add -D @tanstack/intent')
+    console.error('')
+    console.error('Or run directly:')
+    console.error('  npx @tanstack/intent@latest list')
+    process.exit(1)
+  }
+  throw e
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/devtools-utils",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "TanStack Devtools utilities for creating your own devtools.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -65,6 +65,9 @@
     },
     "./package.json": "./package.json"
   },
+  "bin": {
+    "intent": "./bin/intent.js"
+  },
   "sideEffects": false,
   "engines": {
     "node": ">=18"
@@ -98,7 +101,9 @@
   },
   "files": [
     "dist/",
-    "src"
+    "src",
+    "skills",
+    "bin"
   ],
   "devDependencies": {
     "tsup": "^8.5.0",

package/skills/devtools-framework-adapters/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: devtools-framework-adapters
+description: >
+  Use devtools-utils factory functions to create per-framework plugin adapters.
+  createReactPlugin/createSolidPlugin/createVuePlugin/createPreactPlugin,
+  createReactPanel/createSolidPanel/createVuePanel/createPreactPanel.
+  [Plugin, NoOpPlugin] tuple for tree-shaking. DevtoolsPanelProps (theme).
+  Vue uses (name, component) not options object. Solid render must be function.
+type: framework
+library: tanstack-devtools
+library_version: '0.10.12'
+requires:
+  - tanstack-devtools/plugin-panel
+sources:
+  - 'TanStack/devtools:docs/devtools-utils.md'
+  - 'TanStack/devtools:packages/devtools-utils/src/react/plugin.tsx'
+  - 'TanStack/devtools:packages/devtools-utils/src/vue/plugin.ts'
+  - 'TanStack/devtools:packages/devtools-utils/src/solid/plugin.tsx'
+  - 'TanStack/devtools:packages/devtools-utils/src/preact/plugin.tsx'
+---
+
+Use `@tanstack/devtools-utils` factory functions to create per-framework devtools plugin adapters. Each framework has a subpath export (`/react`, `/vue`, `/solid`, `/preact`) with two factories:
+
+1. **`createXPlugin`** -- wraps a component into a `[Plugin, NoOpPlugin]` tuple for tree-shaking.
+2. **`createXPanel`** -- wraps a class-based devtools core (`mount`/`unmount`) into a `[Panel, NoOpPanel]` component tuple.
+
+## Key Source Files
+
+- `packages/devtools-utils/src/react/plugin.tsx` -- createReactPlugin
+- `packages/devtools-utils/src/react/panel.tsx` -- createReactPanel, DevtoolsPanelProps
+- `packages/devtools-utils/src/vue/plugin.ts` -- createVuePlugin (different API)
+- `packages/devtools-utils/src/vue/panel.ts` -- createVuePanel, DevtoolsPanelProps (includes 'system' theme)
+- `packages/devtools-utils/src/solid/plugin.tsx` -- createSolidPlugin
+- `packages/devtools-utils/src/solid/panel.tsx` -- createSolidPanel
+- `packages/devtools-utils/src/solid/class.ts` -- constructCoreClass (Solid-specific)
+- `packages/devtools-utils/src/preact/plugin.tsx` -- createPreactPlugin
+- `packages/devtools-utils/src/preact/panel.tsx` -- createPreactPanel
+
+## Shared Pattern
+
+All four frameworks follow the same two-factory pattern:
+
+### Plugin Factory
+
+Every `createXPlugin` returns `readonly [Plugin, NoOpPlugin]`:
+
+- **Plugin** -- returns a plugin object with metadata and a `render` function that renders your component.
+- **NoOpPlugin** -- returns a plugin object with the same metadata but renders an empty fragment.
+
+### Panel Factory
+
+Every `createXPanel` returns `readonly [Panel, NoOpPanel]`:
+
+- **Panel** -- a framework component that creates a `<div style="height:100%">`, instantiates the core class, calls `core.mount(el, theme)` on mount, and `core.unmount()` on cleanup.
+- **NoOpPanel** -- renders an empty fragment.
+
+### DevtoolsPanelProps
+
+```ts
+// React, Solid, Preact
+interface DevtoolsPanelProps {
+  theme?: 'light' | 'dark'
+}
+
+// Vue (note: includes 'system')
+interface DevtoolsPanelProps {
+  theme?: 'dark' | 'light' | 'system'
+}
+```
+
+Import from the framework subpath:
+
+```ts
+import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/react'
+import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/vue'
+import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/solid'
+import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/preact'
+```
+
+## Primary Example (React)
+
+```tsx
+import { createReactPlugin } from '@tanstack/devtools-utils/react'
+
+function MyStorePanel({ theme }: { theme?: 'light' | 'dark' }) {
+  return <div className={theme}>My Store Devtools</div>
+}
+
+const [MyPlugin, NoOpPlugin] = createReactPlugin({
+  name: 'My Store',
+  id: 'my-store',
+  defaultOpen: false,
+  Component: MyStorePanel,
+})
+
+// Tree-shaking: use NoOp in production
+const ActivePlugin =
+  process.env.NODE_ENV === 'development' ? MyPlugin : NoOpPlugin
+```
+
+### With Class-Based Panel
+
+```tsx
+import {
+  createReactPanel,
+  createReactPlugin,
+} from '@tanstack/devtools-utils/react'
+
+class MyDevtoolsCore {
+  mount(el: HTMLElement, theme: 'light' | 'dark') {
+    /* render into el */
+  }
+  unmount() {
+    /* cleanup */
+  }
+}
+
+const [MyPanel, NoOpPanel] = createReactPanel(MyDevtoolsCore)
+
+const [MyPlugin, NoOpPlugin] = createReactPlugin({
+  name: 'My Store',
+  Component: MyPanel,
+})
+```
+
+## Framework API Differences
+
+### React & Preact -- Options Object
+
+```ts
+createReactPlugin({ name, id?, defaultOpen?, Component })  // => [Plugin, NoOpPlugin]
+createPreactPlugin({ name, id?, defaultOpen?, Component }) // => [Plugin, NoOpPlugin]
+```
+
+- `Component` receives `DevtoolsPanelProps` (with `theme`).
+- `Plugin()` returns `{ name, id?, defaultOpen?, render(el, theme) }`.
+- Preact is identical to React but uses Preact JSX types and `preact/hooks`.
+
+### Vue -- Positional Arguments, NOT Options Object
+
+```ts
+createVuePlugin(name: string, component: DefineComponent) // => [Plugin, NoOpPlugin]
+```
+
+- Takes `(name, component)` as separate arguments, NOT an options object.
+- `Plugin(props)` returns `{ name, component, props }` -- it passes props through.
+- `NoOpPlugin(props)` returns `{ name, component: Fragment, props }`.
+- Vue's `DevtoolsPanelProps.theme` also accepts `'system'`.
+
+### Solid -- Same API as React, Different Internals
+
+```ts
+createSolidPlugin({ name, id?, defaultOpen?, Component }) // => [Plugin, NoOpPlugin]
+```
+
+- Same options-object API as React.
+- `Component` must be a Solid component function `(props: DevtoolsPanelProps) => JSX.Element`.
+- The render function internally returns `<Component theme={theme} />` -- Solid handles reactivity.
+- Solid also exports `constructCoreClass` from `@tanstack/devtools-utils/solid/class` for building lazy-loaded devtools cores.
+
+## Common Mistakes
+
+### CRITICAL: Using React JSX Pattern in Vue Adapter
+
+Vue uses positional `(name, component)` arguments, NOT an options object.
+
+```ts
+// WRONG -- will fail at compile time or produce garbage at runtime
+const [MyPlugin, NoOpPlugin] = createVuePlugin({
+  name: 'My Plugin',
+  Component: MyPanel,
+})
+
+// CORRECT
+const [MyPlugin, NoOpPlugin] = createVuePlugin('My Plugin', MyPanel)
+```
+
+Vue plugins also work differently at call time -- you pass props:
+
+```ts
+// WRONG -- calling Plugin() with no args (React pattern)
+const plugin = MyPlugin()
+
+// CORRECT -- Vue Plugin takes props
+const plugin = MyPlugin({ theme: 'dark' })
+```
+
+### CRITICAL: Solid Render Prop Not Wrapped in Function
+
+When using Solid components, `Component` must be a function reference, not raw JSX.
+
+```tsx
+// WRONG -- evaluates immediately, breaks Solid reactivity
+createSolidPlugin({
+  name: 'My Store',
+  Component: <MyPanel />, // This is JSX.Element, not a component function
+})
+
+// CORRECT -- pass the component function itself
+createSolidPlugin({
+  name: 'My Store',
+  Component: (props) => <MyPanel theme={props.theme} />,
+})
+
+// ALSO CORRECT -- pass the component reference directly
+createSolidPlugin({
+  name: 'My Store',
+  Component: MyPanel,
+})
+```
+
+### HIGH: Ignoring NoOp Variant for Production
+
+The factory returns `[Plugin, NoOpPlugin]`. Both must be destructured and used for proper tree-shaking.
+
+```tsx
+// WRONG -- NoOp variant discarded, devtools code ships to production
+const [MyPlugin] = createReactPlugin({ name: 'Store', Component: MyPanel })
+
+// CORRECT -- conditionally use NoOp in production
+const [MyPlugin, NoOpPlugin] = createReactPlugin({
+  name: 'Store',
+  Component: MyPanel,
+})
+const ActivePlugin =
+  process.env.NODE_ENV === 'development' ? MyPlugin : NoOpPlugin
+```
+
+### MEDIUM: Not Passing Theme Prop to Panel Component
+
+`DevtoolsPanelProps` includes `theme`. The devtools shell passes it so panels can match light/dark mode. If your component ignores it, the panel will not adapt to theme changes.
+
+```tsx
+// WRONG -- theme is ignored
+const Component = () => <div>My Panel</div>
+
+// CORRECT -- use theme for styling
+const Component = ({ theme }: DevtoolsPanelProps) => (
+  <div className={theme === 'dark' ? 'dark-mode' : 'light-mode'}>My Panel</div>
+)
+```
+
+## Design Tension
+
+The core architecture is framework-agnostic, but each framework has different idioms:
+
+- React/Preact use an options object with `Component` as a JSX function component.
+- Vue uses positional arguments with a `DefineComponent` and passes props through.
+- Solid uses the same options API as React but with Solid's JSX and reactivity model.
+
+Agents trained on React patterns will get Vue wrong. Always check the import path to determine which factory API to use.
+
+## Cross-References
+
+- **devtools-plugin-panel** -- Build your panel component first, then wrap it with the appropriate framework adapter.
+- **devtools-production** -- NoOp variants are the primary mechanism for stripping devtools from production bundles.
+
+## Reference Files
+
+- `references/react.md` -- Full React factory API and examples
+- `references/vue.md` -- Full Vue factory API and examples (different from React)
+- `references/solid.md` -- Full Solid factory API and examples
+- `references/preact.md` -- Full Preact factory API and examples

package/skills/devtools-framework-adapters/references/preact.md

@@ -0,0 +1,262 @@
+# Preact Framework Adapter Reference
+
+## Import
+
+```ts
+import {
+  createPreactPlugin,
+  createPreactPanel,
+} from '@tanstack/devtools-utils/preact'
+import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/preact'
+```
+
+## DevtoolsPanelProps
+
+```ts
+interface DevtoolsPanelProps {
+  theme?: 'light' | 'dark'
+}
+```
+
+## createPreactPlugin
+
+Creates a `[Plugin, NoOpPlugin]` tuple from a Preact component and plugin metadata. Identical API to `createReactPlugin`.
+
+### Signature
+
+```ts
+function createPreactPlugin(options: {
+  name: string
+  id?: string
+  defaultOpen?: boolean
+  Component: (props: DevtoolsPanelProps) => JSX.Element
+}): readonly [Plugin, NoOpPlugin]
+```
+
+### Parameters
+
+| Parameter     | Type                                         | Required | Description                             |
+| ------------- | -------------------------------------------- | -------- | --------------------------------------- |
+| `name`        | `string`                                     | Yes      | Display name shown in the devtools tab  |
+| `id`          | `string`                                     | No       | Unique identifier for the plugin        |
+| `defaultOpen` | `boolean`                                    | No       | Whether the plugin panel starts open    |
+| `Component`   | `(props: DevtoolsPanelProps) => JSX.Element` | Yes      | Preact component to render in the panel |
+
+### Return Value
+
+A `readonly [Plugin, NoOpPlugin]` tuple:
+
+- **`Plugin()`** -- returns `{ name, id?, defaultOpen?, render(el, theme) }`. The `render` function renders `<Component theme={theme} />`.
+- **`NoOpPlugin()`** -- returns the same shape but `render` returns `<></>`.
+
+### Source
+
+```tsx
+// packages/devtools-utils/src/preact/plugin.tsx
+/** @jsxImportSource preact */
+import type { JSX } from 'preact'
+import type { DevtoolsPanelProps } from './panel'
+
+export function createPreactPlugin({
+  Component,
+  ...config
+}: {
+  name: string
+  id?: string
+  defaultOpen?: boolean
+  Component: (props: DevtoolsPanelProps) => JSX.Element
+}) {
+  function Plugin() {
+    return {
+      ...config,
+      render: (_el: HTMLElement, theme: 'light' | 'dark') => (
+        <Component theme={theme} />
+      ),
+    }
+  }
+  function NoOpPlugin() {
+    return {
+      ...config,
+      render: (_el: HTMLElement, _theme: 'light' | 'dark') => <></>,
+    }
+  }
+  return [Plugin, NoOpPlugin] as const
+}
+```
+
+### Usage
+
+#### Basic
+
+```tsx
+import { createPreactPlugin } from '@tanstack/devtools-utils/preact'
+
+function MyStorePanel({ theme }: { theme?: 'light' | 'dark' }) {
+  return (
+    <div class={theme === 'dark' ? 'dark' : 'light'}>
+      <h2>My Store Devtools</h2>
+    </div>
+  )
+}
+
+const [MyPlugin, NoOpPlugin] = createPreactPlugin({
+  name: 'My Store',
+  id: 'my-store',
+  defaultOpen: false,
+  Component: MyStorePanel,
+})
+```
+
+#### Inline Component
+
+```tsx
+const [MyPlugin, NoOpPlugin] = createPreactPlugin({
+  name: 'My Store',
+  Component: ({ theme }) => <MyStorePanel theme={theme} />,
+})
+```
+
+#### Production Tree-Shaking
+
+```tsx
+const [MyPlugin, NoOpPlugin] = createPreactPlugin({
+  name: 'My Store',
+  Component: MyStorePanel,
+})
+
+const ActivePlugin =
+  process.env.NODE_ENV === 'development' ? MyPlugin : NoOpPlugin
+```
+
+## createPreactPanel
+
+Wraps a class-based devtools core in a Preact component. Identical behavior to `createReactPanel` but uses `preact/hooks`.
+
+### Signature
+
+```ts
+function createPreactPanel<
+  TComponentProps extends DevtoolsPanelProps | undefined,
+  TCoreDevtoolsClass extends {
+    mount: (el: HTMLElement, theme: 'light' | 'dark') => void
+    unmount: () => void
+  },
+>(CoreClass: new () => TCoreDevtoolsClass): readonly [Panel, NoOpPanel]
+```
+
+### Parameters
+
+| Parameter   | Type                                                    | Required | Description                             |
+| ----------- | ------------------------------------------------------- | -------- | --------------------------------------- |
+| `CoreClass` | `new () => { mount(el, theme): void; unmount(): void }` | Yes      | Class constructor for the devtools core |
+
+### Return Value
+
+- **`Panel`** -- A Preact component that:
+  - Creates a `<div style={{ height: '100%' }}>` with a ref.
+  - Instantiates `CoreClass` on mount via `useEffect` (from `preact/hooks`).
+  - Calls `core.mount(el, props.theme ?? 'dark')`.
+  - Calls `core.unmount()` on cleanup.
+  - Re-runs the effect when `theme` prop changes.
+- **`NoOpPanel`** -- Renders `<></>`.
+
+### Source
+
+```tsx
+// packages/devtools-utils/src/preact/panel.tsx
+/** @jsxImportSource preact */
+import { useEffect, useRef } from 'preact/hooks'
+
+export function createPreactPanel<
+  TComponentProps extends DevtoolsPanelProps | undefined,
+  TCoreDevtoolsClass extends {
+    mount: (el: HTMLElement, theme: 'light' | 'dark') => void
+    unmount: () => void
+  },
+>(CoreClass: new () => TCoreDevtoolsClass) {
+  function Panel(props: TComponentProps) {
+    const devToolRef = useRef<HTMLDivElement>(null)
+    const devtools = useRef<TCoreDevtoolsClass | null>(null)
+    useEffect(() => {
+      if (devtools.current) return
+      devtools.current = new CoreClass()
+      if (devToolRef.current) {
+        devtools.current.mount(devToolRef.current, props?.theme ?? 'dark')
+      }
+      return () => {
+        if (devToolRef.current) {
+          devtools.current?.unmount()
+          devtools.current = null
+        }
+      }
+    }, [props?.theme])
+    return <div style={{ height: '100%' }} ref={devToolRef} />
+  }
+
+  function NoOpPanel(_props: TComponentProps) {
+    return <></>
+  }
+  return [Panel, NoOpPanel] as const
+}
+```
+
+### Usage
+
+```tsx
+import {
+  createPreactPanel,
+  createPreactPlugin,
+} from '@tanstack/devtools-utils/preact'
+
+class MyDevtoolsCore {
+  mount(el: HTMLElement, theme: 'light' | 'dark') {
+    // Use DOM APIs to render your devtools UI into the provided element
+    const container = document.createElement('div')
+    container.className = theme
+    container.textContent = 'Devtools loaded'
+    el.appendChild(container)
+  }
+  unmount() {
+    // cleanup
+  }
+}
+
+// Step 1: Create panel from class
+const [MyPanel, NoOpPanel] = createPreactPanel(MyDevtoolsCore)
+
+// Step 2: Create plugin from panel
+const [MyPlugin, NoOpPlugin] = createPreactPlugin({
+  name: 'My Store',
+  Component: MyPanel,
+})
+
+// Step 3: Conditional for production
+const ActivePlugin =
+  process.env.NODE_ENV === 'development' ? MyPlugin : NoOpPlugin
+```
+
+## Preact-Specific Notes
+
+1. **Identical to React API.** `createPreactPlugin` and `createPreactPanel` have the exact same API signatures as their React counterparts. The only difference is the JSX runtime (`preact` vs `react`) and hooks import (`preact/hooks` vs `react`).
+
+2. **Use `class` not `className`.** Preact supports both, but idiomatic Preact uses `class` in JSX.
+
+3. **No Strict Mode double-mount by default.** Preact does not have React's Strict Mode double-invocation behavior, but the ref guard (`if (devtools.current) return`) is still present and harmless.
+
+4. **Default theme is `'dark'`.** If `props.theme` is undefined, the panel defaults to `'dark'`.
+
+5. **Same hooks behavior.** The `useEffect` dependency on `[props?.theme]` means the panel re-mounts when theme changes, same as React.
+
+## Comparison with React
+
+| Aspect                    | React                            | Preact                            |
+| ------------------------- | -------------------------------- | --------------------------------- |
+| Import path               | `@tanstack/devtools-utils/react` | `@tanstack/devtools-utils/preact` |
+| JSX types                 | `react` JSX                      | `preact` JSX                      |
+| Hooks import              | `react`                          | `preact/hooks`                    |
+| API shape                 | Identical                        | Identical                         |
+| `createXPlugin` signature | Same                             | Same                              |
+| `createXPanel` signature  | Same                             | Same                              |
+| `DevtoolsPanelProps`      | Same                             | Same                              |
+
+If you have working React adapter code, converting to Preact is a matter of changing the import paths.

package/skills/devtools-framework-adapters/references/react.md

@@ -0,0 +1,241 @@
+# React Framework Adapter Reference
+
+## Import
+
+```ts
+import {
+  createReactPlugin,
+  createReactPanel,
+} from '@tanstack/devtools-utils/react'
+import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/react'
+```
+
+## DevtoolsPanelProps
+
+```ts
+interface DevtoolsPanelProps {
+  theme?: 'light' | 'dark'
+}
+```
+
+## createReactPlugin
+
+Creates a `[Plugin, NoOpPlugin]` tuple from a React component and plugin metadata.
+
+### Signature
+
+```ts
+function createReactPlugin(options: {
+  name: string
+  id?: string
+  defaultOpen?: boolean
+  Component: (props: DevtoolsPanelProps) => JSX.Element
+}): readonly [Plugin, NoOpPlugin]
+```
+
+### Parameters
+
+| Parameter     | Type                                         | Required | Description                            |
+| ------------- | -------------------------------------------- | -------- | -------------------------------------- |
+| `name`        | `string`                                     | Yes      | Display name shown in the devtools tab |
+| `id`          | `string`                                     | No       | Unique identifier for the plugin       |
+| `defaultOpen` | `boolean`                                    | No       | Whether the plugin panel starts open   |
+| `Component`   | `(props: DevtoolsPanelProps) => JSX.Element` | Yes      | React component to render in the panel |
+
+### Return Value
+
+A `readonly [Plugin, NoOpPlugin]` tuple:
+
+- **`Plugin()`** -- returns `{ name, id?, defaultOpen?, render(el: HTMLElement, theme: 'light' | 'dark') => JSX.Element }`. The `render` function renders `<Component theme={theme} />`.
+- **`NoOpPlugin()`** -- returns the same shape but `render` returns `<></>`.
+
+### Source
+
+```tsx
+// packages/devtools-utils/src/react/plugin.tsx
+export function createReactPlugin({
+  Component,
+  ...config
+}: {
+  name: string
+  id?: string
+  defaultOpen?: boolean
+  Component: (props: DevtoolsPanelProps) => JSX.Element
+}) {
+  function Plugin() {
+    return {
+      ...config,
+      render: (_el: HTMLElement, theme: 'light' | 'dark') => (
+        <Component theme={theme} />
+      ),
+    }
+  }
+  function NoOpPlugin() {
+    return {
+      ...config,
+      render: (_el: HTMLElement, _theme: 'light' | 'dark') => <></>,
+    }
+  }
+  return [Plugin, NoOpPlugin] as const
+}
+```
+
+### Usage
+
+#### Basic
+
+```tsx
+import { createReactPlugin } from '@tanstack/devtools-utils/react'
+
+function MyStorePanel({ theme }: { theme?: 'light' | 'dark' }) {
+  return (
+    <div className={theme === 'dark' ? 'dark' : 'light'}>
+      <h2>My Store Devtools</h2>
+    </div>
+  )
+}
+
+const [MyPlugin, NoOpPlugin] = createReactPlugin({
+  name: 'My Store',
+  id: 'my-store',
+  defaultOpen: false,
+  Component: MyStorePanel,
+})
+```
+
+#### Inline Component
+
+```tsx
+const [MyPlugin, NoOpPlugin] = createReactPlugin({
+  name: 'My Store',
+  Component: ({ theme }) => <MyStorePanel theme={theme} />,
+})
+```
+
+#### Production Tree-Shaking
+
+```tsx
+const [MyPlugin, NoOpPlugin] = createReactPlugin({
+  name: 'My Store',
+  Component: MyStorePanel,
+})
+
+const ActivePlugin =
+  process.env.NODE_ENV === 'development' ? MyPlugin : NoOpPlugin
+```
+
+## createReactPanel
+
+Wraps a class-based devtools core (with `mount` and `unmount` methods) in a React component that handles lifecycle.
+
+### Signature
+
+```ts
+function createReactPanel<
+  TComponentProps extends DevtoolsPanelProps | undefined,
+  TCoreDevtoolsClass extends {
+    mount: (el: HTMLElement, theme: 'light' | 'dark') => void
+    unmount: () => void
+  },
+>(CoreClass: new () => TCoreDevtoolsClass): readonly [Panel, NoOpPanel]
+```
+
+### Parameters
+
+| Parameter   | Type                                                    | Required | Description                             |
+| ----------- | ------------------------------------------------------- | -------- | --------------------------------------- |
+| `CoreClass` | `new () => { mount(el, theme): void; unmount(): void }` | Yes      | Class constructor for the devtools core |
+
+### Return Value
+
+A `readonly [Panel, NoOpPanel]` tuple:
+
+- **`Panel`** -- A React component that:
+  - Creates a `<div style={{ height: '100%' }}>` with a ref.
+  - Instantiates `CoreClass` on mount via `useEffect`.
+  - Calls `core.mount(el, props.theme ?? 'dark')`.
+  - Calls `core.unmount()` on cleanup.
+  - Re-runs the effect when `theme` prop changes.
+- **`NoOpPanel`** -- Renders `<></>`.
+
+### Source
+
+```tsx
+// packages/devtools-utils/src/react/panel.tsx
+export function createReactPanel<
+  TComponentProps extends DevtoolsPanelProps | undefined,
+  TCoreDevtoolsClass extends {
+    mount: (el: HTMLElement, theme: 'light' | 'dark') => void
+    unmount: () => void
+  },
+>(CoreClass: new () => TCoreDevtoolsClass) {
+  function Panel(props: TComponentProps) {
+    const devToolRef = useRef<HTMLDivElement>(null)
+    const devtools = useRef<TCoreDevtoolsClass | null>(null)
+    useEffect(() => {
+      if (devtools.current) return
+      devtools.current = new CoreClass()
+      if (devToolRef.current) {
+        devtools.current.mount(devToolRef.current, props?.theme ?? 'dark')
+      }
+      return () => {
+        if (devToolRef.current) {
+          devtools.current?.unmount()
+          devtools.current = null
+        }
+      }
+    }, [props?.theme])
+    return <div style={{ height: '100%' }} ref={devToolRef} />
+  }
+
+  function NoOpPanel(_props: TComponentProps) {
+    return <></>
+  }
+  return [Panel, NoOpPanel] as const
+}
+```
+
+### Usage
+
+#### Composing Panel + Plugin
+
+```tsx
+import {
+  createReactPanel,
+  createReactPlugin,
+} from '@tanstack/devtools-utils/react'
+
+class MyDevtoolsCore {
+  mount(el: HTMLElement, theme: 'light' | 'dark') {
+    // Use DOM APIs to render your devtools UI into the provided element
+    const container = document.createElement('div')
+    container.className = theme
+    container.textContent = 'Devtools loaded'
+    el.appendChild(container)
+  }
+  unmount() {
+    // Clean up event listeners, subscriptions, etc.
+  }
+}
+
+// Step 1: Create the panel component from the class
+const [MyPanel, NoOpPanel] = createReactPanel(MyDevtoolsCore)
+
+// Step 2: Create the plugin from the panel component
+const [MyPlugin, NoOpPlugin] = createReactPlugin({
+  name: 'My Store',
+  Component: MyPanel,
+})
+
+// Step 3: Use conditionally for production
+const ActivePlugin =
+  process.env.NODE_ENV === 'development' ? MyPlugin : NoOpPlugin
+```
+
+## React-Specific Gotchas
+
+1. **`useEffect` dependency on `theme`**: The panel re-runs the mount effect when `theme` changes. This means the core class is unmounted and re-mounted on theme change. Design your core class to handle this gracefully.
+
+2. **Ref guard**: `createReactPanel` uses `if (devtools.current) return` to prevent double-mounting in React Strict Mode. Do not remove this guard.
+
+3. **Default theme is `'dark'`**: If `props.theme` is undefined, the panel defaults to `'dark'`.

package/skills/devtools-framework-adapters/references/solid.md

@@ -0,0 +1,274 @@
+# Solid Framework Adapter Reference
+
+## Import
+
+```ts
+import {
+  createSolidPlugin,
+  createSolidPanel,
+} from '@tanstack/devtools-utils/solid'
+import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/solid'
+
+// For class-based lazy loading (separate subpath)
+import { constructCoreClass } from '@tanstack/devtools-utils/solid/class'
+```
+
+## DevtoolsPanelProps
+
+```ts
+interface DevtoolsPanelProps {
+  theme?: 'light' | 'dark'
+}
+```
+
+## createSolidPlugin
+
+Creates a `[Plugin, NoOpPlugin]` tuple from a Solid component and plugin metadata. Same options-object API as React.
+
+### Signature
+
+```ts
+function createSolidPlugin(options: {
+  name: string
+  id?: string
+  defaultOpen?: boolean
+  Component: (props: DevtoolsPanelProps) => JSX.Element
+}): readonly [Plugin, NoOpPlugin]
+```
+
+### Parameters
+
+| Parameter     | Type                                         | Required | Description                            |
+| ------------- | -------------------------------------------- | -------- | -------------------------------------- |
+| `name`        | `string`                                     | Yes      | Display name shown in the devtools tab |
+| `id`          | `string`                                     | No       | Unique identifier for the plugin       |
+| `defaultOpen` | `boolean`                                    | No       | Whether the plugin panel starts open   |
+| `Component`   | `(props: DevtoolsPanelProps) => JSX.Element` | Yes      | Solid component function               |
+
+### Return Value
+
+A `readonly [Plugin, NoOpPlugin]` tuple:
+
+- **`Plugin()`** -- returns `{ name, id?, defaultOpen?, render(el, theme) }`. The `render` function returns `<Component theme={theme} />`.
+- **`NoOpPlugin()`** -- returns the same shape but `render` returns `<></>`.
+
+### Source
+
+```tsx
+// packages/devtools-utils/src/solid/plugin.tsx
+/** @jsxImportSource solid-js */
+import type { JSX } from 'solid-js'
+import type { DevtoolsPanelProps } from './panel'
+
+export function createSolidPlugin({
+  Component,
+  ...config
+}: {
+  name: string
+  id?: string
+  defaultOpen?: boolean
+  Component: (props: DevtoolsPanelProps) => JSX.Element
+}) {
+  function Plugin() {
+    return {
+      ...config,
+      render: (_el: HTMLElement, theme: 'light' | 'dark') => {
+        return <Component theme={theme} />
+      },
+    }
+  }
+  function NoOpPlugin() {
+    return {
+      ...config,
+      render: (_el: HTMLElement, _theme: 'light' | 'dark') => <></>,
+    }
+  }
+  return [Plugin, NoOpPlugin] as const
+}
+```
+
+### Usage
+
+#### Basic
+
+```tsx
+import { createSolidPlugin } from '@tanstack/devtools-utils/solid'
+
+function MyStorePanel(props: { theme?: 'light' | 'dark' }) {
+  return (
+    <div class={props.theme === 'dark' ? 'dark' : 'light'}>
+      <h2>My Store Devtools</h2>
+    </div>
+  )
+}
+
+const [MyPlugin, NoOpPlugin] = createSolidPlugin({
+  name: 'My Store',
+  id: 'my-store',
+  defaultOpen: false,
+  Component: MyStorePanel,
+})
+```
+
+#### Inline Component
+
+```tsx
+const [MyPlugin, NoOpPlugin] = createSolidPlugin({
+  name: 'My Store',
+  Component: (props) => <MyStorePanel theme={props.theme} />,
+})
+```
+
+#### Production Tree-Shaking
+
+```tsx
+const [MyPlugin, NoOpPlugin] = createSolidPlugin({
+  name: 'My Store',
+  Component: MyStorePanel,
+})
+
+const ActivePlugin = import.meta.env.DEV ? MyPlugin : NoOpPlugin
+```
+
+## createSolidPanel
+
+Wraps a class-based devtools core in a Solid component.
+
+### Signature
+
+```ts
+function createSolidPanel<
+  TComponentProps extends DevtoolsPanelProps | undefined,
+>(CoreClass: ClassType): readonly [Panel, NoOpPanel]
+```
+
+Where `ClassType` is `ReturnType<typeof constructCoreClass>[0]` -- a class with `mount(el, theme)` and `unmount()`.
+
+### Return Value
+
+- **`Panel`** -- A Solid component that:
+  - Creates a `<div style={{ height: '100%' }}>` with a ref.
+  - Instantiates `CoreClass` immediately via `createSignal`.
+  - Calls `core.mount(el, props.theme ?? 'dark')` inside `onMount`.
+  - Calls `core.unmount()` via `onCleanup` (nested inside `onMount`).
+- **`NoOpPanel`** -- Renders `<></>`.
+
+### Source
+
+```tsx
+// packages/devtools-utils/src/solid/panel.tsx
+/** @jsxImportSource solid-js */
+import { createSignal, onCleanup, onMount } from 'solid-js'
+import type { ClassType } from './class'
+
+export function createSolidPanel<
+  TComponentProps extends DevtoolsPanelProps | undefined,
+>(CoreClass: ClassType) {
+  function Panel(props: TComponentProps) {
+    let devToolRef: HTMLDivElement | undefined
+    const [devtools] = createSignal(new CoreClass())
+    onMount(() => {
+      if (devToolRef) {
+        devtools().mount(devToolRef, props?.theme ?? 'dark')
+      }
+      onCleanup(() => {
+        devtools().unmount()
+      })
+    })
+    return <div style={{ height: '100%' }} ref={devToolRef} />
+  }
+
+  function NoOpPanel(_props: TComponentProps) {
+    return <></>
+  }
+
+  return [Panel, NoOpPanel] as const
+}
+```
+
+### Usage
+
+```tsx
+import {
+  createSolidPanel,
+  createSolidPlugin,
+} from '@tanstack/devtools-utils/solid'
+import { constructCoreClass } from '@tanstack/devtools-utils/solid/class'
+
+// Step 1: Build a core class with lazy loading
+const [MyDevtoolsCore, NoOpCore] = constructCoreClass(
+  () => import('./MyDevtoolsUI'),
+)
+
+// Step 2: Create panel from core class
+const [MyPanel, NoOpPanel] = createSolidPanel(MyDevtoolsCore)
+
+// Step 3: Create plugin from panel
+const [MyPlugin, NoOpPlugin] = createSolidPlugin({
+  name: 'My Store',
+  Component: MyPanel,
+})
+```
+
+## constructCoreClass
+
+Solid has an additional utility for building lazy-loaded devtools cores. Import from the separate subpath `@tanstack/devtools-utils/solid/class`.
+
+### Signature
+
+```ts
+function constructCoreClass(
+  importFn: () => Promise<{ default: () => JSX.Element }>,
+): readonly [DevtoolsCore, NoOpDevtoolsCore]
+```
+
+### Behavior
+
+- **`DevtoolsCore`** -- Has an async `mount(el, theme)` that dynamically imports the component, then mounts it into `el`. Tracks mounting state to prevent double-mounting. Supports abort if `unmount()` is called during the async import.
+- **`NoOpDevtoolsCore`** -- Extends `DevtoolsCore` but `mount` and `unmount` are no-ops.
+
+### Usage
+
+```ts
+import { constructCoreClass } from '@tanstack/devtools-utils/solid/class'
+
+const [DevtoolsCore, NoOpDevtoolsCore] = constructCoreClass(
+  () => import('./MyDevtoolsPanel'),
+)
+
+// Use DevtoolsCore with createSolidPanel
+// Use NoOpDevtoolsCore for production
+```
+
+## Solid-Specific Gotchas
+
+1. **Component must be a function, not JSX.** The `Component` field expects a function `(props) => JSX.Element`, not evaluated JSX.
+
+   ```tsx
+   // WRONG -- <MyPanel /> is JSX.Element, not a component function
+   Component: <MyPanel />
+
+   // CORRECT -- pass the component function
+   Component: MyStorePanel
+
+   // ALSO CORRECT -- wrap in arrow function
+   Component: (props) => <MyStorePanel theme={props.theme} />
+   ```
+
+2. **Solid props are accessed via `props.theme`, not destructured.** Solid's reactivity requires accessing props through the props object. Destructuring breaks reactivity.
+
+   ```tsx
+   // CAUTION -- destructuring may break reactivity tracking
+   const Component = ({ theme }: DevtoolsPanelProps) => <div>{theme}</div>
+
+   // PREFERRED -- access via props object
+   const Component = (props: DevtoolsPanelProps) => <div>{props.theme}</div>
+   ```
+
+3. **Default theme is `'dark'`.** If `props.theme` is undefined, the panel defaults to `'dark'`.
+
+4. **`onCleanup` is nested inside `onMount`.** In `createSolidPanel`, cleanup is registered inside `onMount`, which is the Solid idiom for pairing mount/unmount lifecycle.
+
+5. **Core class instantiation is eager.** `createSignal(new CoreClass())` runs immediately when the Panel component is created, not lazily. The actual `mount` call happens in `onMount`.
+
+6. **`constructCoreClass` handles async import abort.** If `unmount()` is called while the dynamic import is still in flight, the mount is aborted cleanly. No need to handle this manually.

package/skills/devtools-framework-adapters/references/vue.md

@@ -0,0 +1,270 @@
+# Vue Framework Adapter Reference
+
+## Import
+
+```ts
+import { createVuePlugin, createVuePanel } from '@tanstack/devtools-utils/vue'
+import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/vue'
+```
+
+## DevtoolsPanelProps
+
+```ts
+// NOTE: Vue includes 'system' -- unlike React/Solid/Preact
+interface DevtoolsPanelProps {
+  theme?: 'dark' | 'light' | 'system'
+}
+```
+
+## createVuePlugin
+
+Creates a `[Plugin, NoOpPlugin]` tuple from a Vue component.
+
+**CRITICAL: Vue uses positional arguments `(name, component)`, NOT an options object.**
+
+### Signature
+
+```ts
+function createVuePlugin<TComponentProps extends Record<string, any>>(
+  name: string,
+  component: DefineComponent<TComponentProps, {}, unknown>,
+): readonly [Plugin, NoOpPlugin]
+```
+
+### Parameters
+
+| Parameter   | Type                               | Required | Description                            |
+| ----------- | ---------------------------------- | -------- | -------------------------------------- |
+| `name`      | `string`                           | Yes      | Display name shown in the devtools tab |
+| `component` | `DefineComponent<TComponentProps>` | Yes      | Vue component to render in the panel   |
+
+Note: There is **no** `id` or `defaultOpen` parameter. Vue plugins are simpler.
+
+### Return Value
+
+A `readonly [Plugin, NoOpPlugin]` tuple. Both are **functions that accept props**:
+
+- **`Plugin(props: TComponentProps)`** -- returns `{ name, component, props }` where `component` is your Vue component.
+- **`NoOpPlugin(props: TComponentProps)`** -- returns `{ name, component: Fragment, props }` where `Fragment` is Vue's built-in fragment (renders nothing visible).
+
+**This differs from React/Solid/Preact** where `Plugin()` takes no arguments.
+
+### Source
+
+```ts
+// packages/devtools-utils/src/vue/plugin.ts
+import { Fragment } from 'vue'
+import type { DefineComponent } from 'vue'
+
+export function createVuePlugin<TComponentProps extends Record<string, any>>(
+  name: string,
+  component: DefineComponent<TComponentProps, {}, unknown>,
+) {
+  function Plugin(props: TComponentProps) {
+    return {
+      name,
+      component,
+      props,
+    }
+  }
+  function NoOpPlugin(props: TComponentProps) {
+    return {
+      name,
+      component: Fragment,
+      props,
+    }
+  }
+  return [Plugin, NoOpPlugin] as const
+}
+```
+
+### Usage
+
+#### Basic
+
+```vue
+<!-- MyStorePanel.vue -->
+<script setup lang="ts">
+import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/vue'
+
+const props = defineProps<DevtoolsPanelProps>()
+</script>
+
+<template>
+  <div :class="props.theme">
+    <h2>My Store Devtools</h2>
+  </div>
+</template>
+```
+
+```ts
+import { createVuePlugin } from '@tanstack/devtools-utils/vue'
+import MyStorePanel from './MyStorePanel.vue'
+
+const [MyPlugin, NoOpPlugin] = createVuePlugin('My Store', MyStorePanel)
+```
+
+#### Using the Plugin (Vue-specific -- pass props)
+
+```ts
+// Vue plugins are called WITH props
+const plugin = MyPlugin({ theme: 'dark' })
+// Returns: { name: 'My Store', component: MyStorePanel, props: { theme: 'dark' } }
+
+const noopPlugin = NoOpPlugin({ theme: 'dark' })
+// Returns: { name: 'My Store', component: Fragment, props: { theme: 'dark' } }
+```
+
+#### Production Tree-Shaking
+
+```ts
+const [MyPlugin, NoOpPlugin] = createVuePlugin('My Store', MyStorePanel)
+
+const ActivePlugin = import.meta.env.DEV ? MyPlugin : NoOpPlugin
+```
+
+## createVuePanel
+
+Wraps a class-based devtools core in a Vue `defineComponent`.
+
+### Signature
+
+```ts
+function createVuePanel<
+  TComponentProps extends DevtoolsPanelProps,
+  TCoreDevtoolsClass extends {
+    mount: (el: HTMLElement, theme?: DevtoolsPanelProps['theme']) => void
+    unmount: () => void
+  },
+>(
+  CoreClass: new (props: TComponentProps) => TCoreDevtoolsClass,
+): readonly [Panel, NoOpPanel]
+```
+
+### Parameters
+
+| Parameter   | Type                                                                           | Required | Description                                                                                      |
+| ----------- | ------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------ |
+| `CoreClass` | `new (props: TComponentProps) => { mount(el, theme?): void; unmount(): void }` | Yes      | Class constructor. **Note:** Vue's constructor takes `props`, unlike React's no-arg constructor. |
+
+### Return Value
+
+A tuple of two Vue `DefineComponent`s:
+
+- **`Panel`** -- Accepts `theme` and `devtoolsProps` as props. On `onMounted`, instantiates `CoreClass(devtoolsProps)` and calls `mount(el, theme)`. On `onUnmounted`, calls `unmount()`. Renders a `<div style="height:100%">`.
+- **`NoOpPanel`** -- Renders `null`.
+
+Both components have the type:
+
+```ts
+DefineComponent<{
+  theme?: 'dark' | 'light' | 'system'
+  devtoolsProps: TComponentProps
+}>
+```
+
+### Source
+
+```ts
+// packages/devtools-utils/src/vue/panel.ts
+export function createVuePanel<
+  TComponentProps extends DevtoolsPanelProps,
+  TCoreDevtoolsClass extends {
+    mount: (el: HTMLElement, theme?: DevtoolsPanelProps['theme']) => void
+    unmount: () => void
+  },
+>(CoreClass: new (props: TComponentProps) => TCoreDevtoolsClass) {
+  const props = {
+    theme: { type: String as () => DevtoolsPanelProps['theme'] },
+    devtoolsProps: { type: Object as () => TComponentProps },
+  }
+
+  const Panel = defineComponent({
+    props,
+    setup(config) {
+      const devToolRef = ref<HTMLElement | null>(null)
+      const devtools = ref<TCoreDevtoolsClass | null>(null)
+      onMounted(() => {
+        const instance = new CoreClass(config.devtoolsProps as TComponentProps)
+        devtools.value = instance
+        if (devToolRef.value) {
+          instance.mount(devToolRef.value, config.theme)
+        }
+      })
+      onUnmounted(() => {
+        if (devToolRef.value && devtools.value) {
+          devtools.value.unmount()
+        }
+      })
+      return () => h('div', { style: { height: '100%' }, ref: devToolRef })
+    },
+  })
+
+  const NoOpPanel = defineComponent({
+    props,
+    setup() {
+      return () => null
+    },
+  })
+
+  return [Panel, NoOpPanel] as unknown as [
+    DefineComponent<{
+      theme?: DevtoolsPanelProps['theme']
+      devtoolsProps: TComponentProps
+    }>,
+    DefineComponent<{
+      theme?: DevtoolsPanelProps['theme']
+      devtoolsProps: TComponentProps
+    }>,
+  ]
+}
+```
+
+### Usage
+
+```ts
+import { createVuePanel, createVuePlugin } from '@tanstack/devtools-utils/vue'
+
+class MyDevtoolsCore {
+  constructor(private props: { theme?: string }) {}
+  mount(el: HTMLElement, theme?: 'dark' | 'light' | 'system') {
+    // render into el
+  }
+  unmount() {
+    // cleanup
+  }
+}
+
+// Step 1: Create panel from class
+const [MyPanel, NoOpPanel] = createVuePanel(MyDevtoolsCore)
+
+// Step 2: Create plugin from panel
+const [MyPlugin, NoOpPlugin] = createVuePlugin('My Store', MyPanel)
+```
+
+#### Using the Panel Directly in a Template
+
+```vue
+<template>
+  <MyPanel
+    theme="dark"
+    :devtools-props="{
+      /* ... */
+    }"
+  />
+</template>
+```
+
+## Vue-Specific Gotchas
+
+1. **Positional arguments, not options object.** This is the most common mistake. `createVuePlugin('name', Component)`, not `createVuePlugin({ name, Component })`.
+
+2. **Plugin functions accept props.** `MyPlugin(props)` returns `{ name, component, props }`. This differs from React/Solid/Preact where `Plugin()` takes no arguments.
+
+3. **Theme includes `'system'`.** Vue's `DevtoolsPanelProps` accepts `'dark' | 'light' | 'system'`, while all other frameworks only accept `'light' | 'dark'`.
+
+4. **No `id` or `defaultOpen`.** The Vue `createVuePlugin` API only takes `name` and `component`. There is no `id` or `defaultOpen` parameter.
+
+5. **Panel constructor takes props.** `createVuePanel`'s `CoreClass` constructor receives props: `new CoreClass(devtoolsProps)`. React/Preact/Solid constructors take no arguments.
+
+6. **`devtoolsProps` prop on panel.** The Vue panel component has a separate `devtoolsProps` prop for forwarding data to the core class, in addition to the `theme` prop.