mirror of
https://github.com/CopilotKit/CopilotKit.git
synced 2026-09-14 16:26:20 +08:00
Jordan Ritter
4b4923561b
## Summary Three connected features land together so the CopilotKit VS Code extension becomes a coherent debugger/preview surface: 1. **Hook Explorer** — every V1 + V2 render hook can be discovered and previewed live with auto-generated controls, an inline `▶️ Preview Component` CodeLens, and a sidebar that lists every captured site. 2. **AG-UI Event Inspector** — live SSE debug stream of all AG-UI events, filterable and color-coded, in a sidebar view + editor panel. 3. **A2UI Catalog sidebar → webview** — the last native TreeView gets replaced with a Tailwind-styled webview that matches the other two, now with a proper **Go to source** action on components and fixtures. ## Hook Explorer ### Discovery + preview - oxc-based scanner walks the workspace and finds every call-site of any hook in the registry (17 across V1 + V2, render + data). - Preview panel bundles the user's source via Rolldown (IIFE format, React externalized, CSS collected per `@copilotkit/a2ui-renderer` pattern), executes it in the webview with a capture-only **stub** for `@copilotkit/react-core` (+ `/v2`), and mounts the user's component just long enough to record each hook's config. - Auto-generated form on the left/top drives the `render` prop's args/parameters/state/event live. V1 parameter arrays and V2 Zod / Standard Schema all map through a unified `FormSchema` derived at runtime from the captured config. - `useCopilotAction`, `useCopilotAuthenticatedAction_c`, `useCoAgentStateRender`, `useLangGraphInterrupt`, `useRenderTool`, `useRenderToolCall`, `useDefaultRenderTool`, `useLazyToolRenderer`, `useRenderCustomMessages`, `useRenderActivityMessage`, `useHumanInTheLoop`, `useInterrupt`, `useFrontendTool`, `useComponent`, `useDefaultTool` all previewable. - Inline `▶️ Preview Component` CodeLens above every render-hook call site, backed by the same `copilotkit.hooks.preview` command as the sidebar. - Imported render components work: rolldown walks transitive imports from the hook's `render` prop through any number of sibling files. - Cross-file hook switches are robust: controls are reset on load, Harness only mounts once the real HostRoot is ready, a top-level error boundary auto-recovers when you pick a different hook. ### Why the stub approach Bundling the real `@copilotkit/react-core` through rolldown's IIFE output hit a `__commonJSMin` TDZ chain (`require_clipboard`, `require_graphql`, `require_context_helpers`, …) because the chat/runtime-client/markdown graph has circular imports. Externalizing react-core + routing to a Proxy-backed stub that captures hook configs avoids the whole CJS wrapping problem, shrinks the preview bundle from ~24 MB to ~1.3 KB, and keeps the preview runtime path completely runnable without a live CopilotKit backend. Tradeoff documented in `copilotkit-stubs.ts`. ### Weather-themed fixtures 14+ fixtures under `packages/vscode-extension/test-workspace/hooks`, each a distinct visual scenario (forecast card, severity-palette alerts with imported CSS, forecast strip, live radar grid, conic-gradient precipitation gauge, air-quality badge with imported render, pollen report with a 2-hop import graph, HITL evacuation confirm, sunrise/sunset gradient, etc.). Used both as regression fixtures and as the demo surface for video. ### Styling - Tailwind-via-CDN + VS Code CSS variables for theme-aware chrome. - User-provided CSS imports collected by rolldown and injected as a `<style>` tag per load. - Controls + form fields converted to Tailwind; textarea matches input styling. - Framed "Rendered output" card so the render prop is visually unmistakable. ## AG-UI Event Inspector ### Runtime (`@copilotkit/runtime` + `@copilotkit/shared`) - `DebugEventBus` — in-memory pub/sub on `BaseCopilotRuntime`, only instantiated when `NODE_ENV != production`. - Event tap in `createSseEventResponse` broadcasts every AG-UI event with metadata (agentId, threadId, runId, timestamp). - `GET /debug-events` SSE endpoint — returns 404 in production, streams `DebugEventEnvelope` JSON to connected clients, initial `: connected` comment flushes headers immediately. ### VSCode Extension - `DebugStream` — Node SSE client with auto-reconnect, exponential backoff, URL validation, error surfacing. - `InspectorPanel` (editor panel, command `CopilotKit: Open AG-UI Inspector`) and `InspectorViewProvider` (sidebar view) both use a shared `DebugStream` instance — events persist when switching tabs. - Inspector React app: `ConnectionBar`, `FilterBar`, `EventList`, `EventDetail`. - Color scheme: purple (lifecycle), red (errors), blue (text), orange (tools), green (reasoning), teal (state), yellow (activity), gray (unknown). ## A2UI Catalog → webview - Replaces `ComponentPreviewProvider` (native TreeDataProvider) with `CatalogListViewProvider` (WebviewViewProvider), matching the Hooks and Inspector sidebars. - New React webview with refresh header, component rows (name + relative path + `auto` badge when no fixture), expandable fixtures list. - Click a component row → preview (or toggle if it has fixtures); click a fixture row → preview that fixture. - Hover action buttons: `▷` preview + `</>` go-to-source on every row. - "Go to source" opens the component file for component rows; for fixture rows it opens the fixture file and jumps the cursor to the named fixture key. ## Test coverage - Runtime: DebugEventBus unit tests (8), handleDebugEvents endpoint (5), fetch-router routes (4), integration across Express/Hono/Node/Fetch (9). - Hooks: scanner + 16 fixture bundle-smoke test, regression guard against `node_<builtin>` self-references, CSS collector test, stub-based capture E2E, cross-kind controls remount, FormRenderer defensive rendering. - Inspector + webview: DebugStream reconnect (10), inspector components (17), colors (9). - Total: **178 tests** passing for the vscode-extension package; runtime suite unchanged. ## Test plan - [ ] `pnpm nx run copilotkit-vscode-extension:build` and `pnpm nx run copilotkit-vscode-extension:test` both green - [ ] F5 launches the Extension Dev Host with `test-workspace` open - [ ] Hooks sidebar lists every fixture hook; click a row → preview opens; `</>` button opens the source - [ ] `▶️ Preview Component` CodeLens shows above every render hook in a `.tsx` file; clicking it opens the preview - [ ] Form controls drive the render live; cross-kind hook switches (action ↔ custom-message) don't crash; a forced render-prop throw recovers when a different hook is picked - [ ] Imported-render fixtures (`ImportedAirQuality`, `ImportedPollenReport`) bundle and preview correctly - [ ] A2UI Catalog sidebar is the new webview, refresh works, `</>` on a fixture opens the fixture file and reveals the named key - [ ] AG-UI Inspector connects to `GET /debug-events`, filters + detail work, events survive sidebar/panel switch, invalid URL shows red error
fumadocs-test
This is a Next.js application generated with Create Fumadocs.
Run development server:
npm run dev
# or
pnpm dev
# or
yarn dev
Open http://localhost:3000 with your browser to see the result.
Learn More
To learn more about Next.js and Fumadocs, take a look at the following resources:
- Next.js Documentation - learn about Next.js features and API.
- Learn Next.js - an interactive Next.js tutorial.
- Fumadocs - learn about Fumadocs
Vercel Deployment with Git LFS
Docs assets are tracked with Git LFS. To ensure production builds always receive
real asset bytes (not pointer files), deploy docs through GitHub Actions using
.github/workflows/deploy_docs_vercel.yml.
Required GitHub repository secrets:
VERCEL_TOKENVERCEL_ORG_IDVERCEL_PROJECT_ID_DOCS
PR previews:
.github/workflows/deploy_docs_vercel_preview.ymldeploys docs previews for non-fork pull requests.- The workflow posts/updates a sticky PR comment with a clickable
Open Docs Previewlink.
Recommended Vercel project setting:
- Disable automatic Git-based deployments for the docs project and let the GitHub Actions workflow handle production deploys.