feat: A2UI v0.9 + Open Generative UI — BYOC catalogs, dark mode, sandboxed UI generation (CopilotKit#3588)

## Summary

- **A2UI v0.9**: New protocol with `a2ui_operations` container, custom
BYOC catalogs (FlightCard, HotelCard, ProductCard, TeamMemberCard), dark
mode support via CSS variables, ActionButton with click state,
component-neutral LLM guidelines
- **Open Generative UI**: Sandboxed HTML/CSS/JS UI generation streamed
live into chat via iframe, with designSkill styling guidelines and
auto-resize
- **Runtime**: `includeBasicCatalog` defaults to false, removed `a2ui:
true` boolean shorthand, `before_agent` SystemMessage ID reuse fix
- **CLI**: Added `a2ui` and `opengenui` scaffold options
- **Python SDK**: `copilotkit.a2ui` helpers, `before_agent` ID reuse fix
(0.1.84a2)
- **Dojo**: Custom A2UI components shared across demos, aimock fixtures
updated, e2e flaky test fix

## Pre-release packages
- ag-ui: `pkg.pr.new@10147076ab8247ce088a4e43e6c7a1660e9fa291`
- Python SDK: `copilotkit==0.1.84a2`

## Test plan
- [ ] A2UI fixed schema (flight + hotel search) renders correctly
- [ ] A2UI dynamic schema (hotel, product, team) renders correctly
- [ ] Button clicks produce agent responses (action dispatch)
- [ ] Dark mode support works
- [ ] Open Generative UI sandbox renders in iframe
- [ ] `npx copilotkit create` with `a2ui` and `opengenui` options work
- [ ] E2e tests pass in ag-ui dojo

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: tylerslaton

.changeset/stupid-parents-run.md

@@ -0,0 +1,9 @@
+---
+"@copilotkit/a2ui-renderer": minor
+"@copilotkit/react-core": minor
+"@copilotkit/runtime": minor
+"@copilotkit/shared": patch
+"@copilotkit/cli": patch
+---
+
+A2UI v0.9 + Open Generative UI: BYOC catalogs, dark mode, sandboxed UI generation

.pnpmfile.cjs

@@ -0,0 +1,39 @@
+const path = require("path");
+const fs = require("fs");
+
+/**
+ * When A2UI_LOCAL=1, rewrites @a2ui/* dependencies to link against
+ * locally-built packages from the sibling A2UI repo.
+ *
+ * Usage:
+ *   A2UI_LOCAL=1 pnpm install   # link to local A2UI packages
+ *   pnpm install                 # install from npm (default)
+ *
+ * Expects:
+ *   /some/path/CopilotKit/  (this repo)
+ *   /some/path/A2UI/        (sibling A2UI repo)
+ */
+
+const A2UI_ROOT = path.resolve(__dirname, "..", "A2UI");
+
+const A2UI_PACKAGES = {
+  "@a2ui/web_core": "renderers/web_core",
+  "@a2ui/react": "renderers/react",
+};
+
+function readPackage(pkg) {
+  if (!process.env.A2UI_LOCAL) return pkg;
+
+  for (const [dep, relPath] of Object.entries(A2UI_PACKAGES)) {
+    if (pkg.dependencies && pkg.dependencies[dep]) {
+      const localPath = path.join(A2UI_ROOT, relPath);
+      if (fs.existsSync(localPath)) {
+        pkg.dependencies[dep] = `link:${localPath}`;
+      }
+    }
+  }
+
+  return pkg;
+}
+
+module.exports = { hooks: { readPackage } };

docs/components/ui/integrations-sidebar/integration-selector.tsx

@@ -199,8 +199,10 @@ const IntegrationSelector = ({
       return;
     }
 
-    // Only clear selection if we're specifically on /integrations page
-    if (pathname === "/integrations" && selectedIntegration) {
+    // Clear selection on any non-integration route so the picker returns to
+    // its default "Select integration..." state on the homepage and other
+    // docs sections.
+    if (selectedIntegration) {
       setSelectedIntegration(null);
     }
   }, [pathname, selectedIntegration, setSelectedIntegration]);

docs/components/ui/sidebar/folder.tsx

@@ -20,6 +20,39 @@ interface FolderProps {
   onNavigate?: () => void;
 }
 
+function getFolderDisplayName(node: Node & { children?: Node[] }): string {
+  const folderName = typeof node.name === "string" ? node.name : "";
+  const folderUrl =
+    typeof (node as any).index?.url === "string"
+      ? (node as any).index.url
+      : typeof node.url === "string"
+        ? node.url
+        : "";
+
+  const childUrls = (node.children || [])
+    .map((child) => {
+      if (
+        child.type === "folder" &&
+        typeof (child as any).index?.url === "string"
+      ) {
+        return (child as any).index.url;
+      }
+      return typeof child.url === "string" ? child.url : "";
+    })
+    .filter(Boolean);
+
+  const isA2UIFolder =
+    folderName === "A2UI" ||
+    folderUrl.endsWith("/a2ui") ||
+    childUrls.some((url) => url.includes("/a2ui/"));
+
+  if (isA2UIFolder) {
+    return "Declerative Gen-UI (A2UI)";
+  }
+
+  return folderName;
+}
+
 /**
  * Checks if a folder's index URL matches the current pathname.
  * Handles:
@@ -77,6 +110,9 @@ const Folder = ({ node }: FolderProps) => {
   const router = useRouter();
   const folderUrl = node.index?.url;
   const folderId = node.$id;
+  const displayName = getFolderDisplayName(
+    node as Node & { children?: Node[] },
+  );
 
   // Check if folder should be open by default from meta.json defaultOpen property
   // Fumadocs exposes this property from meta.json files
@@ -138,7 +174,7 @@ const Folder = ({ node }: FolderProps) => {
           onClick={handleLinkClick}
           className="flex gap-2 justify-between items-center px-3 w-full h-10 cursor-pointer"
         >
-          <span className="w-max text-sm shrink-0">{node.name}</span>
+          <span className="w-max text-sm shrink-0">{displayName}</span>
           <ChevronDownIcon className={cn(isOpen ? "rotate-180" : "")} />
         </button>
       </li>

docs/content/docs/(root)/generative-ui/a2ui.mdx

@@ -1,5 +1,5 @@
 ---
-title: "A2UI"
+title: "Declarative Gen-UI (A2UI)"
 icon: "lucide/FileJson"
 description: "Render declarative UI components using the A2UI specification."
 hideTOC: true

docs/content/docs/(root)/generative-ui/meta.json

@@ -6,6 +6,7 @@
     "tool-rendering",
     "state-rendering",
     "mcp-apps",
+    "open-generative-ui",
     "a2ui"
   ]
 }

docs/content/docs/(root)/generative-ui/open-generative-ui.mdx

@@ -0,0 +1,213 @@
+---
+title: "Open Generative UI"
+icon: "lucide/Code"
+description: "Let agents generate fully interactive HTML/CSS/JS UIs that stream live into the chat."
+---
+
+import { Tabs, Tab } from "fumadocs-ui/components/tabs";
+
+## What is this?
+
+Open Generative UI lets the agent generate complete, sandboxed UI on the fly — HTML, CSS, and JavaScript — and stream it live into the chat. The user sees the interface build in real time: styles apply first, then HTML streams in progressively, and finally JavaScript expressions execute one by one.
+
+Key benefits:
+- **No predefined components** — the agent creates any UI it needs, on demand
+- **Live streaming** — HTML streams into a preview as it's generated
+- **CDN libraries** — the generated UI can load external libraries (Chart.js, D3, Three.js, etc.) via `<script>` tags
+- **Secure sandboxing** — content runs in an isolated iframe without same-origin access
+- **Sandbox functions** — expose host application functions to the sandboxed UI for two-way communication
+
+## Basic setup
+
+Enable Open Generative UI by setting `openGenerativeUI: true` in your runtime configuration. That's it — the middleware handles the rest.
+
+<Steps>
+  <Step>
+    ### Add the dependencies
+
+    ```npm
+    npm install @copilotkit/react-ui @copilotkit/react-core @copilotkit/runtime
+    ```
+  </Step>
+  <Step>
+    ### Configure the runtime
+
+    ```typescript title="app/api/copilotkit/route.ts"
+    import {
+      CopilotRuntime,
+      createCopilotEndpoint,
+      InMemoryAgentRunner,
+    } from "@copilotkit/runtime";
+    import { BuiltInAgent } from "@copilotkit/runtime/v2";
+    import { handle } from "hono/vercel";
+
+    const agent = new BuiltInAgent({
+      model: "openai/gpt-5.2",
+      prompt: "You are a helpful assistant.",
+    });
+
+    const runtime = new CopilotRuntime({
+      agents: { default: agent },
+      runner: new InMemoryAgentRunner(),
+      // Enable Open Generative UI
+      openGenerativeUI: true,
+    });
+
+    const app = createCopilotEndpoint({
+      runtime,
+      basePath: "/api/copilotkit",
+    });
+
+    export const GET = handle(app);
+    export const POST = handle(app);
+    ```
+
+    You can also pass options instead of `true`:
+
+    ```typescript
+    openGenerativeUI: {
+      instructions: "Always use a dark color scheme.",
+    }
+    ```
+
+    The `instructions` string is appended to the tool description, letting you customize what the agent generates.
+  </Step>
+  <Step>
+    ### Configure the frontend
+
+    ```tsx title="app/page.tsx"
+    "use client";
+
+    import { CopilotKit } from "@copilotkit/react-core/v2";
+    import { CopilotChat } from "@copilotkit/react-core/v2";
+    import "@copilotkit/react-ui/v2/styles.css";
+
+    export default function Page() {
+      return (
+        <CopilotKit runtimeUrl="/api/copilotkit">
+          <CopilotChat />
+        </CopilotKit>
+      );
+    }
+    ```
+
+    No special frontend prop is needed — Open Generative UI rendering is built in.
+  </Step>
+</Steps>
+
+That's it. Ask the agent to "build a calculator" or "show me a bar chart of sales data" and it will generate and stream the UI live.
+
+## Advanced: Sandbox functions
+
+Sandbox functions let the generated UI call back into your host application. This enables two-way communication — for example, a generated settings panel that can toggle your app's theme, or a product card that adds items to your cart.
+
+### Defining sandbox functions
+
+Pass `sandboxFunctions` to the `openGenerativeUI` prop on `CopilotKit`:
+
+```tsx title="app/page.tsx"
+"use client";
+
+import { CopilotKit, CopilotChat } from "@copilotkit/react-core/v2";
+import "@copilotkit/react-ui/v2/styles.css";
+import { useState } from "react";
+import { z } from "zod";
+
+export default function Page() {
+  const [theme, setTheme] = useState<"light" | "dark">("light");
+
+  return (
+    <CopilotKit
+      runtimeUrl="/api/copilotkit"
+      openGenerativeUI={{
+        sandboxFunctions: [
+          {
+            name: "setTheme",
+            description: "Switch the app theme between light and dark mode.",
+            parameters: z.object({
+              mode: z.enum(["light", "dark"]).describe("The theme mode to set"),
+            }),
+            handler: async ({ mode }) => {
+              setTheme(mode);
+              return `Theme set to ${mode}`;
+            },
+          },
+        ],
+      }}
+    >
+      <CopilotChat />
+    </CopilotKit>
+  );
+}
+```
+
+### How sandbox functions work
+
+Each sandbox function has:
+
+| Property | Type | Description |
+|---|---|---|
+| `name` | `string` | Function name, callable from the sandbox |
+| `description` | `string` | Tells the agent what this function does |
+| `parameters` | Zod schema | Validates arguments passed from the sandbox |
+| `handler` | `(args) => Promise<string>` | Runs in the host app, returns a result string |
+
+Inside the generated UI, the agent calls these functions via:
+
+```javascript
+// Inside the sandboxed iframe
+const result = await Websandbox.connection.remote.setTheme({ mode: "dark" });
+```
+
+The function descriptions are automatically included in the agent's context, so it knows which functions are available and how to use them.
+
+### Use cases
+
+- **Theme toggling** — generated UI controls your app's appearance
+- **Cart / state management** — product cards that add items to the host app's state
+- **Navigation** — generated UI that triggers route changes in the host app
+- **Data fetching** — sandbox calls the host to fetch data the iframe can't access directly (due to same-origin restrictions)
+
+## How streaming works
+
+The agent generates parameters in a specific order optimized for the user experience:
+
+1. **`placeholderMessages`** — shown immediately while generating
+2. **`css`** — all styles generated first; the preview starts once CSS is complete
+3. **`html`** — streams live into the preview as it's generated
+4. **`jsFunctions`** — reusable helper functions injected before expressions
+5. **`jsExpressions`** — executed one by one; the user sees each take effect
+
+The middleware parses the tool call arguments incrementally and emits activity events as each parameter completes, so the frontend can show progressive updates.
+
+## Using CDN libraries
+
+The sandboxed iframe can load external libraries from CDNs. Include `<script>` or `<link>` tags in the generated HTML `<head>`:
+
+```html
+<head>
+  <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
+</head>
+<body>
+  <canvas id="myChart"></canvas>
+</body>
+```
+
+Libraries like Chart.js, D3, Three.js, x-data-spreadsheet, and any other CDN-hosted library work out of the box.
+
+## Middleware API
+
+If you prefer to apply the middleware to specific agents rather than globally, use `OpenGenerativeUIMiddleware` directly:
+
+```typescript
+import { OpenGenerativeUIMiddleware } from "@copilotkit/runtime";
+
+const agent = new BuiltInAgent({
+  model: "openai/gpt-5.2",
+  prompt: "You are a helpful assistant.",
+}).use(
+  new OpenGenerativeUIMiddleware({
+    instructions: "Use a modern, minimal design.",
+  }),
+);
+```