Implement Web Inspector (#16)

Author: mme

.gitignore

@@ -27,6 +27,9 @@ out/
 build
 dist
 
+# Generated Tailwind assets
+packages/web-inspector/src/styles/generated.css
+
 
 # Debug
 npm-debug.log*
@@ -42,4 +45,4 @@ storybook-static
 
 # Angular
 .angular/
-.playwright-mcp/
+.playwright-mcp/

apps/react/storybook/package.json

@@ -3,9 +3,9 @@
   "private": true,
   "version": "0.0.0",
   "scripts": {
-    "dev": "pnpm --filter @copilotkitnext/react run build:css && sleep 1 && concurrently \"pnpm --filter @copilotkitnext/react run dev:css\" \"storybook dev -p 6006 --no-open\"",
+    "dev": "pnpm --filter @copilotkitnext/react run build:css && sleep 1 && concurrently \"pnpm --filter @copilotkitnext/react run dev\" \"pnpm --filter @copilotkitnext/web-inspector run dev\" \"storybook dev -p 6006 --no-open\"",
     "build": "storybook build",
-    "storybook:dev": "pnpm --filter @copilotkitnext/react run build:css && sleep 1 && concurrently \"pnpm --filter @copilotkitnext/react run dev:css\" \"storybook dev -p 6006 --no-open\"",
+    "storybook:dev": "pnpm --filter @copilotkitnext/react run build:css && sleep 1 && concurrently \"pnpm --filter @copilotkitnext/react run dev\" \"pnpm --filter @copilotkitnext/web-inspector run dev\" \"storybook dev -p 6006 --no-open\"",
     "storybook:build": "storybook build"
   },
   "dependencies": {

apps/react/storybook/stories/WebInspector.stories.tsx

@@ -0,0 +1,15 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { WebInspector } from "@copilotkitnext/react";
+
+const meta: Meta<typeof WebInspector> = {
+  title: "Components/Web Inspector",
+  component: WebInspector,
+};
+
+export default meta;
+
+type Story = StoryObj<typeof WebInspector>;
+
+export const Default: Story = {
+  args: {},
+};

package.json

@@ -2,11 +2,11 @@
   "name": "CopilotKitNext",
   "private": true,
   "scripts": {
-    "predev": "turbo run build --filter='@copilotkitnext/core' --filter='@copilotkitnext/shared' --filter='@copilotkitnext/react' --filter='@copilotkitnext/angular' --filter='@copilotkitnext/agent'",
+    "predev": "turbo run build --filter='@copilotkitnext/core' --filter='@copilotkitnext/shared' --filter='@copilotkitnext/web-inspector' --filter='@copilotkitnext/react' --filter='@copilotkitnext/angular' --filter='@copilotkitnext/agent'",
     "build": "turbo run build",
     "clean": "turbo run clean",
-    "dev": "turbo run dev --filter='@copilotkitnext/core' --filter='@copilotkitnext/shared' --filter='@copilotkitnext/runtime' --filter='@copilotkitnext/react' --filter='@copilotkitnext/angular' --filter='@copilotkitnext/agent' --concurrency=15",
-    "dev:packages": "turbo run dev --filter='@copilotkitnext/core' --filter='@copilotkitnext/shared' --filter='@copilotkitnext/runtime' --filter='@copilotkitnext/react' --filter='@copilotkitnext/angular' --filter='@copilotkitnext/agent'",
+    "dev": "turbo run dev --filter='@copilotkitnext/core' --filter='@copilotkitnext/shared' --filter='@copilotkitnext/web-inspector' --filter='@copilotkitnext/runtime' --filter='@copilotkitnext/react' --filter='@copilotkitnext/angular' --filter='@copilotkitnext/agent' --concurrency=15",
+    "dev:packages": "turbo run dev --filter='@copilotkitnext/core' --filter='@copilotkitnext/shared' --filter='@copilotkitnext/web-inspector' --filter='@copilotkitnext/runtime' --filter='@copilotkitnext/react' --filter='@copilotkitnext/angular' --filter='@copilotkitnext/agent'",
     "demo:angular": "turbo run dev --filter='@copilotkitnext/angular-demo-server' --filter='@copilotkitnext/angular-demo'",
     "storybook:angular": "pnpm -C apps/angular/storybook dev",
     "demo:react": "pnpm -C apps/react/demo dev",

packages/react/package.json

@@ -57,6 +57,8 @@
     "@ag-ui/core": "0.0.40-alpha.3",
     "@copilotkitnext/core": "workspace:*",
     "@copilotkitnext/shared": "workspace:*",
+    "@copilotkitnext/web-inspector": "workspace:*",
+    "@lit-labs/react": "^2.0.2",
     "@radix-ui/react-dropdown-menu": "^2.1.15",
     "@radix-ui/react-slot": "^1.2.3",
     "@radix-ui/react-tooltip": "^1.2.7",

packages/react/src/components/WebInspector.tsx

@@ -0,0 +1,40 @@
+import * as React from "react";
+import { createComponent } from "@lit-labs/react";
+import {
+  WEB_INSPECTOR_TAG,
+  WebInspectorElement,
+  defineWebInspector,
+} from "@copilotkitnext/web-inspector";
+import type { CopilotKitCore } from "@copilotkitnext/core";
+
+defineWebInspector();
+
+const WebInspectorBase = createComponent({
+  tagName: WEB_INSPECTOR_TAG,
+  elementClass: WebInspectorElement,
+  react: React,
+});
+
+export type WebInspectorBaseProps = React.ComponentProps<typeof WebInspectorBase>;
+
+export interface WebInspectorProps extends Omit<WebInspectorBaseProps, "core"> {
+  core?: CopilotKitCore | null;
+}
+
+export const WebInspector = React.forwardRef<WebInspectorElement, WebInspectorProps>(
+  ({ core, ...rest }, ref) => {
+    const innerRef = React.useRef<WebInspectorElement>(null);
+
+    React.useImperativeHandle(ref, () => innerRef.current as WebInspectorElement, []);
+
+    React.useEffect(() => {
+      if (innerRef.current) {
+        innerRef.current.core = core ?? null;
+      }
+    }, [core]);
+
+    return <WebInspectorBase {...(rest as WebInspectorBaseProps)} ref={innerRef} />; // eslint-disable-line react/jsx-props-no-spreading
+  },
+);
+
+WebInspector.displayName = "WebInspector";

packages/react/src/components/index.ts

@@ -3,3 +3,4 @@
 
 export * from "./chat";
 export * from "./WildcardToolCallRender";
+export * from "./WebInspector";

packages/react/src/providers/CopilotKitProvider.tsx

@@ -1,6 +1,15 @@
 "use client";
 
-import React, { createContext, useContext, ReactNode, useMemo, useEffect, useReducer, useRef } from "react";
+import React, {
+  createContext,
+  useContext,
+  ReactNode,
+  useMemo,
+  useEffect,
+  useReducer,
+  useRef,
+  useState,
+} from "react";
 import { ReactToolCallRenderer } from "../types/react-tool-call-renderer";
 import { ReactCustomMessageRenderer } from "../types/react-custom-message-renderer";
 import { ReactFrontendTool } from "../types/frontend-tool";
@@ -9,6 +18,7 @@ import { z } from "zod";
 import { FrontendTool } from "@copilotkitnext/core";
 import { AbstractAgent } from "@ag-ui/client";
 import { CopilotKitCoreReact } from "../lib/react-core";
+import { WebInspector } from "../components/WebInspector";
 
 // Define the context value interface - idiomatic React naming
 export interface CopilotKitContextValue {
@@ -68,6 +78,18 @@ export const CopilotKitProvider: React.FC<CopilotKitProviderProps> = ({
   frontendTools,
   humanInTheLoop,
 }) => {
+  const [shouldRenderInspector, setShouldRenderInspector] = useState(false);
+
+  useEffect(() => {
+    if (typeof window === "undefined") {
+      return;
+    }
+    const localhostHosts = new Set(["localhost", "127.0.0.1"]);
+    if (localhostHosts.has(window.location.hostname)) {
+      setShouldRenderInspector(true);
+    }
+  }, []);
+
   // Normalize array props to stable references with clear dev warnings
   const renderToolCallsList = useStableArrayProp<ReactToolCallRenderer<any>>(
     renderToolCalls,
@@ -223,6 +245,7 @@ export const CopilotKitProvider: React.FC<CopilotKitProviderProps> = ({
       }}
     >
       {children}
+      {shouldRenderInspector ? <WebInspector core={copilotkit} /> : null}
     </CopilotKitContext.Provider>
   );
 };

packages/react/tsconfig.json

@@ -14,6 +14,10 @@
       "@copilotkitnext/shared": [
         "../shared/dist/index.d.ts",
         "../shared/src/index.ts"
+      ],
+      "@copilotkitnext/web-inspector": [
+        "../web-inspector/dist/index.d.ts",
+        "../web-inspector/src/index.ts"
       ]
     },
     "types": ["vitest/globals"]

packages/web-inspector/eslint.config.mjs

@@ -0,0 +1,3 @@
+import { config as baseConfig } from "@copilotkitnext/eslint-config/base";
+
+export default [...baseConfig];