Skip to content

Commit 8f3c47e

Browse files
AlemTuzlakAlemTuzlak
committed
docs(vscode-extension): restructure as three-feature hub + refresh Hook Explorer page
Persona fix: the landing page at /vs-code-extension only documented the A2UI catalog preview, so builders using CopilotKit hooks and runtime debuggers never discovered their respective features. Restructured into a three-section hub that surfaces Hook Explorer, A2UI Catalog, and AG-UI Inspector side-by-side, with install steps at the top and cross-links to the deep-dive pages. /troubleshooting/hook-explorer refreshed end-to-end: - Replaced stale TreeDataProvider description with the current webview sidebar + row-click-previews + '</>' go-to-source UX. - Documented the inline '▶️ Preview Component' CodeLens. - Expanded hook coverage table to include useComponent, useDefaultTool, useHumanInTheLoop, useInterrupt, useRenderCustomMessages, useRenderActivityMessage, useDefaultRenderTool, useLazyToolRenderer, useCopilotAuthenticatedAction_c, useRenderToolCall — all 15 render hooks covered with their preview shape. - Added 'Behavior notes' section: auto-recovery on crash + reset on selection change, controls persistence, Tailwind + local CSS flow- through. - Added imported-render support note. /troubleshooting/event-inspector — added a back-link to Hook Explorer at the bottom callout so the cross-link is bidirectional.
1 parent 449f736 commit 8f3c47e

3 files changed

Lines changed: 118 additions & 81 deletions

File tree

‎docs/content/docs/(root)/troubleshooting/event-inspector.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,5 +91,5 @@ Click any event row to expand the full JSON payload in the detail panel. This sh
9191
| **Activity/UI** | Yellow | `ACTIVITY_SNAPSHOT`, `ACTIVITY_DELTA` | UI activity indicators and progress updates |
9292

9393
<Callout type="info">
94-
For console-level debug logging and programmatic error handling in your app, see [Error Debugging](/troubleshooting/error-debugging).
94+
For console-level debug logging and programmatic error handling in your app, see [Error Debugging](/troubleshooting/error-debugging). If you're debugging a render prop rather than a runtime event stream, the [Hook Explorer](/troubleshooting/hook-explorer) is the offline, render-first complement to this tool.
9595
</Callout>

‎docs/content/docs/(root)/troubleshooting/hook-explorer.mdx‎

Lines changed: 58 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,102 +1,111 @@
11
---
22
title: "Hook Explorer"
3-
description: "Discover and live-preview CopilotKit render hooks without leaving VS Code"
3+
description: "Discover and live-preview CopilotKit render hooks without leaving VS Code."
44
icon: "lucide/Binoculars"
55
---
66

77
import { Steps, Step } from "fumadocs-ui/components/steps";
88
import { Callout } from "fumadocs-ui/components/callout";
99

10-
The **Hook Explorer** is a sidebar view in the CopilotKit VS Code extension that scans your workspace for every CopilotKit hook call and — for hooks that carry a `render` component — opens a live preview inside VS Code. You get auto-generated form controls for `args`, `state`, `status`, and `result`, and your changes hot-reload as you edit the source file.
10+
You have a file that calls `useCopilotAction`, `useRenderTool`, `useCoAgentStateRender`, or any of the other render-capable CopilotKit hooks, and you want to iterate on the `render` prop — tweak the layout, test different statuses, feed different args — without running the full chat loop. The Hook Explorer is a sidebar and inline-CodeLens UI inside the [VS Code extension](/vs-code-extension) that does exactly that.
1111

12-
Use it when:
12+
By the end of this page you'll have:
1313

14-
- You're building an action render and want to iterate without round-tripping through the full chat UI.
15-
- You want to see every `useCopilotAction` / `useRenderTool` / `useCoAgentStateRender` in your project at a glance.
16-
- You need to verify how a render behaves at `inProgress` / `executing` / `complete` states without firing a real agent run.
14+
- Every CopilotKit hook call in your workspace listed in a sidebar.
15+
- A live preview panel for any render hook, with auto-generated form controls driven by the hook's declared parameters.
16+
- A one-click `▶️ Preview Component` CodeLens above every hook call in your editor.
1717

1818
## Prerequisites
1919

2020
- The [CopilotKit VS Code extension](/vs-code-extension) installed.
2121
- `@copilotkit/react-core` or `@copilotkit/react-core/v2` imported somewhere in your workspace.
2222

2323
<Callout type="info">
24-
The Hook Explorer runs locally against your source files — no runtime or agent is required to use it.
24+
The Hook Explorer runs entirely against your source files — no runtime, no API keys, no agent run required.
2525
</Callout>
2626

2727
## Explore and preview
2828

2929
<Steps>
3030

3131
<Step>
32-
### Open the Hook Explorer view
32+
### Open the Hook Explorer
3333

34-
Click the CopilotKit icon in the Activity Bar, then expand **CopilotKit Hooks** in the sidebar. The tree shows two groups:
35-
36-
- **Render hooks** — hooks whose `render` prop can be previewed (`useCopilotAction`, `useRenderTool`, `useCoAgentStateRender`, `useLangGraphInterrupt`, `useHumanInTheLoop`, and friends).
37-
- **Data hooks** — hooks that don't render anything (`useCopilotReadable`, `useCoAgent`, `useCopilotAdditionalInstructions`, etc.). These are navigable but not previewable.
38-
39-
Each hook type collapses into a list of per-site leaves labeled by the action name (or `line:N` for nameless hooks).
34+
Click the CopilotKit icon in the Activity Bar and expand the **CopilotKit Hooks** sidebar (first of the three views). You'll see every CopilotKit hook call in your workspace, grouped by hook name. Each row shows the action/tool name (or `line:N` for nameless hooks like `useLangGraphInterrupt`) alongside the file path and line.
4035
</Step>
4136

4237
<Step>
43-
### Open source
38+
### Preview a render hook
4439

45-
Click any leaf to jump to the hook call in your editor — works for both render and data hooks. Handy for finding every `useCopilotReadable` in a large codebase.
46-
</Step>
40+
Click any row under a render hook (`useCopilotAction`, `useRenderTool`, …) to open the preview panel in an editor pane. The first time you open a panel for a file, the extension bundles that file through Rolldown with a capture-only stub for `@copilotkit/react-core` — your component mounts into the webview, the hook's config is captured, and the `render` prop is driven by controls on the left (or on top at narrow widths):
4741

48-
<Step>
49-
### Preview a render
42+
- **Status** — `inProgress` / `executing` / `complete`.
43+
- **Args / parameters** — form built from your hook's `parameters` array (V1) or Zod / Standard Schema (V2). Missing fields, enum options, nested objects and arrays all work.
44+
- **Result** — editable once status is `complete`.
45+
- **Hook-specific extras** — `nodeName` for `useCoAgentStateRender`, `toolCallId` for `useRenderTool`, an event-value editor for interrupts.
5046

51-
Click a leaf under **Render hooks** to open the preview panel. The first time you open a panel for a file, CopilotKit bundles it with your installed `@copilotkit/*` version and mounts it inside a fake provider so the render is captured with its closures intact.
47+
The rendered output sits inside a labeled frame on the right (or below) so it's unmistakably "the component your `render` returned." Your Tailwind classes and any `.css` imports your file uses are bundled in and injected per load.
48+
</Step>
5249

53-
The panel has two columns:
50+
<Step>
51+
### Jump to source
5452

55-
- **Controls** (left) — status dropdown, auto-generated `args` form, result editor, and hook-specific extras like `nodeName` (for `useCoAgentStateRender`) or `toolCallId` (for `useRenderTool`).
56-
- **Preview** (right) — your render output, re-invoked on every control change.
53+
Each sidebar row has a `</>` button on hover that opens the file at the exact line of the hook call. For data hooks (non-previewable), the row click itself opens the source — they stay useful as a navigation index even without a preview.
5754
</Step>
5855

5956
<Step>
60-
### Edit the source
57+
### Use the inline CodeLens
6158

62-
Save the file containing the hook. The panel rebundles, re-captures, and re-renders automatically — your form values are preserved wherever the field names and types still match the new schema.
59+
Open any `.ts` or `.tsx` file that calls a render hook. You'll see a `▶️ Preview Component` CodeLens directly above each hook call — clicking it opens the same preview panel. This is handy when you're already in the source file and don't want to round-trip through the sidebar.
6360
</Step>
6461

6562
<Step>
66-
### Toggle status and arguments
67-
68-
Use the status dropdown to cycle through `inProgress` → `executing` → `complete`. The result editor activates when status is `complete`. Type into the args form to see how your render handles different inputs — tool call arguments, missing fields, enum options, etc.
63+
### Edit and re-render
6964

70-
Form values persist in VS Code workspace state, so your last-used args are restored the next time you open the same hook.
65+
Save the file. The extension re-scans the file, rebundles the preview, and re-captures. Your form values are preserved wherever the field names and types still match the new schema.
7166
</Step>
7267

7368
</Steps>
7469

75-
## What gets discovered
70+
## Hook coverage
7671

77-
The scanner walks your workspace and looks for direct imports from `@copilotkit/react-core` or `@copilotkit/react-core/v2`. It respects your root and nested `.gitignore` files, and skips `node_modules`, `dist`, `.git`, `.next`, `build`, `.turbo`, `out`, plus `.test.*` / `.spec.*` / `.stories.*` files.
72+
Every render-capable CopilotKit hook is discoverable and previewable:
7873

79-
| Hook | Category | Preview |
74+
| Hook | Source | Preview shape |
8075
|---|---|---|
81-
| `useCopilotAction`, `useCopilotAuthenticatedAction_c` | Render | ✔ |
82-
| `useCoAgentStateRender` | Render | ✔ |
83-
| `useLangGraphInterrupt`, `useInterrupt` | Render | ✔ |
84-
| `useRenderTool`, `useRenderToolCall`, `useDefaultRenderTool`, `useLazyToolRenderer` | Render | ✔ |
85-
| `useRenderCustomMessages`, `useRenderActivityMessage` | Render | ✔ |
86-
| `useHumanInTheLoop` | Render | ✔ |
87-
| `useFrontendTool` | Render | ✔ (when a `render` prop is present) |
88-
| `useCopilotReadable`, `useCopilotAdditionalInstructions` | Data | — |
89-
| `useCoAgent`, `useAgent`, `useCopilotChat` | Data | — |
90-
| `useSuggestions`, `useConfigureSuggestions`, `useCopilotChatSuggestions` | Data | — |
91-
92-
## Limitations (MVP)
93-
94-
- **Barrel-file re-exports** aren't resolved — import hooks directly from `@copilotkit/react-core` or `@copilotkit/react-core/v2`. If you re-export through your own index file, the scanner won't pick up the call sites.
95-
- **Non-CopilotKit providers**: if your component requires `<ThemeProvider>`, Redux, Auth context, or another custom provider to render, the mount will fail. Isolate the hook into a provider-free component for preview.
76+
| `useCopilotAction` | `@copilotkit/react-core` | action (`args`, `status`, `result`) |
77+
| `useCopilotAuthenticatedAction_c` | `@copilotkit/react-core` | action |
78+
| `useCoAgentStateRender` | `@copilotkit/react-core` | coagent-state (`state`, `status`, `nodeName`) |
79+
| `useLangGraphInterrupt` | `@copilotkit/react-core` | interrupt (`event`, `resolve`) |
80+
| `useRenderTool` | `@copilotkit/react-core/v2` | render-tool (`parameters`, `status`, `toolCallId`) |
81+
| `useRenderToolCall` | `@copilotkit/react-core/v2` | render-tool |
82+
| `useDefaultRenderTool` | `@copilotkit/react-core/v2` | render-tool |
83+
| `useLazyToolRenderer` | `@copilotkit/react-core/v2` | render-tool |
84+
| `useFrontendTool` | `@copilotkit/react-core/v2` | render-tool |
85+
| `useComponent` | `@copilotkit/react-core/v2` | render-tool |
86+
| `useDefaultTool` | `@copilotkit/react-core/v2` | action |
87+
| `useHumanInTheLoop` | `@copilotkit/react-core/v2` | action |
88+
| `useInterrupt` | `@copilotkit/react-core/v2` | interrupt |
89+
| `useRenderCustomMessages` | `@copilotkit/react-core/v2` | custom-messages (`message`) |
90+
| `useRenderActivityMessage` | `@copilotkit/react-core/v2` | activity-message (`message`) |
91+
92+
Data hooks (`useCopilotReadable`, `useCoAgent`, `useAgent`, `useCopilotChat`, etc.) appear in the sidebar for navigation but have no preview — the row click opens the source.
93+
94+
Imported render components work too: if your `render` prop is a reference to a component defined in a sibling file (instead of an inline arrow), Rolldown walks the import chain and the preview binds to the actual component.
95+
96+
## Behavior notes
97+
98+
- **Auto-recovery**: if a render prop throws, the preview surface shows a readable error screen — and picking a different hook in the sidebar automatically resets the boundary. You're never stuck on a crashed preview.
99+
- **Controls persist**: your last-used args, status, and result are stored in VS Code workspace state per hook, so they're restored next time you open the same preview.
100+
- **Styles flow through**: Tailwind classes in your `render` prop work via the Tailwind browser CDN loaded into the preview panel. Local `.css` imports are collected by the bundler and injected as a `<style>` tag on each load.
101+
102+
## Limitations
103+
104+
- **Barrel-file re-exports aren't resolved** — import hooks directly from `@copilotkit/react-core` or `@copilotkit/react-core/v2`. If you re-export through your own index file, the scanner won't pick up the call sites.
105+
- **Non-CopilotKit providers**: if your component requires `<ThemeProvider>`, Redux, Auth, or another custom provider to render, the mount will throw. Isolate the hook into a provider-free component for preview, or stub the provider in the preview-only path.
96106
- **Agent state typing**: `useCoAgentStateRender` state has no runtime schema (types live in TypeScript only), so the state control falls back to a raw-JSON editor.
97-
- **No fixture files**: control values are stored in VS Code workspace state, not a checked-in file. Sharing preview scenarios with your team is follow-up work.
98107
- **Dynamic action names**: if `useCopilotAction({ name: someVariable })` uses a non-literal name, the sidebar labels the entry `(dynamic) · file:line` until the runtime capture resolves it.
99108

100109
<Callout type="info">
101-
For live inspection of AG-UI events while an agent is actually running, see [AG-UI Event Inspector](/troubleshooting/event-inspector).
110+
Need to see the live AG-UI event stream while the agent is actually running? Hook Explorer is the offline, render-first tool — the [AG-UI Event Inspector](/troubleshooting/event-inspector) is the runtime, events-first complement.
102111
</Callout>

‎docs/content/docs/(root)/vs-code-extension.mdx‎

Lines changed: 59 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,65 +1,84 @@
11
---
22
title: VS Code Extension
33
icon: "lucide/Monitor"
4-
description: Live preview A2UI catalog components directly inside VS Code with hot-reload.
4+
description: Live preview your CopilotKit render hooks, A2UI catalog components, and AG-UI event stream — without leaving VS Code.
55
---
66

77
import { Steps, Step } from "fumadocs-ui/components/steps";
88
import { Tabs, Tab } from "fumadocs-ui/components/tabs";
99
import { Callout } from "fumadocs-ui/components/callout";
1010

11-
## What is this?
11+
The CopilotKit VS Code extension is a three-in-one workbench for iterating on CopilotKit features inside your editor. Install it once and you get three sidebars under the CopilotKit activity-bar icon:
1212

13-
The CopilotKit VS Code extension gives you a live preview of your A2UI catalog components inside your editor. Edit a component file, save, and see the rendered result update instantly in a side panel — no localhost server, no browser tab.
13+
- **CopilotKit Hooks** — discover every `useCopilotAction`, `useRenderTool`, `useCoAgentStateRender`, etc. in your workspace, and live-preview their `render` components with auto-generated form controls.
14+
- **A2UI Catalog** — live preview of your A2UI catalog components with fixture-driven scenarios and hot-reload on save.
15+
- **AG-UI Inspector** — a real-time, color-coded, filterable stream of every AG-UI event your runtime emits.
1416

15-
## When should I use this?
17+
No localhost server, no browser tab, no agent run required for the first two — you can iterate on rendering and UI structure entirely offline.
1618

17-
- Iterating on data visualization or agent UI components
18-
- Testing components with different data scenarios via fixture files
19-
- Previewing catalog components without running a full agent loop
20-
21-
<Callout type="info">
22-
New to CopilotKit? Start with the [Quickstart](/quickstart) to set up a project first,
23-
then come back here to supercharge your component development workflow.
24-
</Callout>
25-
26-
## Get started
19+
## Install
2720

2821
<Steps>
2922
<Step>
3023
### Install the extension
3124

32-
Open VS Code, go to Extensions (Ctrl+Shift+X), and search for **CopilotKit**. Click Install.
33-
34-
Alternatively, install from the command line:
25+
Open VS Code, go to Extensions (`Ctrl+Shift+X` / `Cmd+Shift+X`), search for **CopilotKit**, and click Install. Or from a terminal:
3526

3627
```bash
3728
code --install-extension copilotkit.copilotkit
3829
```
3930
</Step>
4031

4132
<Step>
42-
### Open the CopilotKit sidebar
33+
### Open the CopilotKit activity bar
34+
35+
Click the **CopilotKit icon** in the Activity Bar on the left edge of VS Code. Three sidebar views expand underneath it, in this order:
36+
37+
1. **CopilotKit Hooks**
38+
2. **A2UI Catalog**
39+
3. **AG-UI Inspector**
40+
41+
Each is a self-contained tool — pick the one that matches what you're working on.
42+
</Step>
43+
</Steps>
44+
45+
## Hook Explorer
46+
47+
You have a file that calls `useCopilotAction`, `useRenderTool`, or any other render-capable CopilotKit hook, and you want to iterate on the `render` prop. The **CopilotKit Hooks** sidebar lists every call-site in your workspace; clicking one opens a live preview panel where the `render` output is driven by a form built from your hook's declared parameters.
48+
49+
Extra niceties:
50+
51+
- A `▶️ Preview Component` CodeLens sits directly above every render-hook call in your editor — one click opens the preview for exactly that site.
52+
- A `</>` button on each sidebar row jumps to the source file.
53+
- Cross-file hook switches auto-recover — a forced render-prop crash in one hook doesn't strand the whole webview.
54+
55+
<Callout type="info">
56+
Full walkthrough, hook coverage table, and limitations: [Hook Explorer](/troubleshooting/hook-explorer).
57+
</Callout>
58+
59+
## A2UI Catalog
60+
61+
You have a file that exports an A2UI catalog via `createCatalog` (or imports `@copilotkit/a2ui-renderer`). The **A2UI Catalog** sidebar lists every catalog file in your workspace, plus any named fixtures you've defined alongside them. Clicking a component opens a live preview; edit the file and the preview updates on save while preserving interaction state.
62+
63+
<Steps>
64+
<Step>
65+
### Find your catalog files
4366

44-
Click the **CopilotKit icon** in the Activity Bar (left edge of VS Code, alongside Explorer and Search). The **Component Preview** panel lists all A2UI catalog components discovered in your workspace.
67+
Open the **A2UI Catalog** sidebar. Each row is a catalog file (discovered by scanning for `@copilotkit/a2ui-renderer` imports). Rows with fixture files expand to show named scenarios; rows without one get an `auto` badge and render with a default empty surface.
4568

46-
The extension automatically finds any `.ts`/`.tsx` file that imports from `@copilotkit/a2ui-renderer` and exports a catalog.
69+
Hover any row to reveal a `</>` button that jumps to the source — on fixture rows, it jumps to the named fixture key inside the fixture file.
4770
</Step>
4871

4972
<Step>
5073
### Preview a component
5174

52-
Click any component in the sidebar to open a live preview panel. You can also:
53-
- Open a catalog file and run **CopilotKit: Preview Component** from the command palette (Ctrl+Shift+P)
54-
- Right-click a `.ts`/`.tsx` file in the Explorer and select **CopilotKit: Preview Component**
55-
56-
Edit the component file and save — the preview updates instantly while preserving interaction state.
75+
Click a component row to open the preview. If the component has fixtures, click the row to expand and pick a fixture — otherwise the click previews directly. Edit the file and save — the preview rebundles and re-renders automatically.
5776
</Step>
58-
</Steps>
5977

60-
## Fixture files
78+
<Step>
79+
### Add fixtures
6180

62-
Fixtures provide named test data scenarios for your component previews. Create a fixture file next to your component:
81+
Fixtures are named test-data scenarios. Create a fixture file next to your component:
6382

6483
<Tabs items={["JSON", "TypeScript"]}>
6584
<Tab value="JSON">
@@ -100,9 +119,18 @@ export default {
100119
</Tab>
101120
</Tabs>
102121

103-
Each key is a named fixture. Use the dropdown at the top of the preview panel to switch between them. Components without a fixture file get an auto-generated default.
122+
Each top-level key is a named fixture. Switch between them from the fixture dropdown inside the preview panel.
123+
</Step>
124+
</Steps>
125+
126+
<Callout type="info">
127+
The extension validates fixture files on save and surfaces structural warnings (missing `surfaceId`, invalid `messages`, unknown component types) as in-editor diagnostics.
128+
</Callout>
129+
130+
## AG-UI Inspector
131+
132+
You're running a CopilotKit runtime and something in an agent interaction is off — a tool call isn't firing, a state delta is wrong, or the run ends before the UI settles. The **AG-UI Inspector** sidebar opens a dedicated SSE connection to your runtime's `/cpk-debug-events` endpoint and renders every event in a filterable, color-coded stream. Click any event row to expand the full JSON payload.
104133

105134
<Callout type="info">
106-
The extension validates fixture files on save and shows warnings as editor diagnostics
107-
if the structure is invalid (missing `surfaceId` or `messages` fields).
135+
Full walkthrough, event-type color reference, and production guard details: [AG-UI Event Inspector](/troubleshooting/event-inspector).
108136
</Callout>

0 commit comments

Comments
 (0)