@copilotkit/react-core 1.71.0 → 1.71.1

package/skills/react-core/references/rendering-activity-messages.md

@@ -1,201 +0,0 @@
-# CopilotKit Rendering Activity Messages (React)
-
-This skill builds on `copilotkit/provider-setup`. Activity-message
-renderers are registered as entries in the `renderActivityMessages` array
-prop on the `CopilotKit` provider and resolved at render time by
-`useRenderActivityMessage` (consumed internally by chat components).
-
-User renderers are placed first in the array so they override the built-in
-`MCPAppsActivityType` and `OpenGenerativeUIActivityType` renderers for the
-same `activityType`.
-
-Resolver order:
-
-1. `(activityType, agentId)` match
-2. `(activityType, unscoped)` match
-3. `'*'` wildcard
-4. `null`
-
-## Setup
-
-```tsx
-"use client";
-import { CopilotKit } from "@copilotkit/react-core/v2";
-import type { ReactActivityMessageRenderer } from "@copilotkit/react-core/v2";
-import { z } from "zod";
-import { useMemo } from "react";
-import { Card, CardContent } from "@/components/ui/card";
-import { Progress } from "@/components/ui/progress";
-
-const progressRenderer: ReactActivityMessageRenderer<{
-  percent: number;
-  label: string;
-}> = {
-  activityType: "progress",
-  content: z.object({ percent: z.number().min(0).max(1), label: z.string() }),
-  render: ({ content }) => (
-    <Card>
-      <CardContent>
-        <div>{content.label}</div>
-        <Progress value={content.percent * 100} />
-      </CardContent>
-    </Card>
-  ),
-};
-
-export function Providers({ children }: { children: React.ReactNode }) {
-  const renderers = useMemo(() => [progressRenderer], []);
-  return (
-    <CopilotKit runtimeUrl="/api/copilotkit" renderActivityMessages={renderers}>
-      {children}
-    </CopilotKit>
-  );
-}
-```
-
-## Core Patterns
-
-### Agent-scoped renderer
-
-```tsx
-const researchProgress: ReactActivityMessageRenderer<{ step: string }> = {
-  activityType: "research-step",
-  agentId: "research",
-  content: z.object({ step: z.string() }),
-  render: ({ content }) => <ResearchStepBadge step={content.step} />,
-};
-```
-
-### Override a built-in (MCP Apps)
-
-Place your renderer for the same `activityType` — user renderers are
-evaluated before built-ins.
-
-```tsx
-import { MCPAppsActivityType } from "@copilotkit/react-core/v2";
-
-const customMcpRenderer: ReactActivityMessageRenderer<unknown> = {
-  activityType: MCPAppsActivityType, // "mcp-apps" — must match the exported constant
-  content: z.unknown(),
-  render: ({ content, message }) => <CustomMCPCard payload={content} />,
-};
-```
-
-### Using the hook directly (custom chat surface)
-
-```tsx
-import { useRenderActivityMessage } from "@copilotkit/react-core/v2";
-import type { ActivityMessage } from "@ag-ui/core";
-
-export function ActivityList({ messages }: { messages: ActivityMessage[] }) {
-  const { renderActivityMessage } = useRenderActivityMessage();
-  return (
-    <div>
-      {messages.map((m) => (
-        <div key={m.id}>{renderActivityMessage(m)}</div>
-      ))}
-    </div>
-  );
-}
-```
-
-## Common Mistakes
-
-### HIGH — Incompatible content schema
-
-Wrong:
-
-```tsx
-// Renderer expects `pct`
-const r: ReactActivityMessageRenderer<{ pct: number }> = {
-  activityType: "progress",
-  content: z.object({ pct: z.number() }),
-  render: ({ content }) => <Bar value={content.pct} />,
-};
-// But the server emits { percent: 0.5 } — mismatched field name
-```
-
-Correct:
-
-```tsx
-const r: ReactActivityMessageRenderer<{ percent: number }> = {
-  activityType: "progress",
-  content: z.object({ percent: z.number() }),
-  render: ({ content }) => <Bar value={content.percent} />,
-};
-```
-
-`safeParse` is called on every incoming activity message. Mismatched
-schemas return `null` with only a `console.warn("Failed to parse content
-for activity message …")` — the UI renders nothing and the failure is
-silent unless you read the console.
-
-Source: `packages/react-core/src/v2/hooks/use-render-activity-message.tsx:44-50`
-
-### MEDIUM — Side effects in `render`
-
-Wrong:
-
-```tsx
-render: ({ content }) => {
-  trackEvent(content); // fires on every re-render
-  return <Badge>{content.label}</Badge>;
-};
-```
-
-Wrong (Rules of Hooks violation):
-
-```tsx
-render: ({ content }) => {
-  // `render` is invoked as a plain function by the resolver — NOT as a
-  // React component — so calling hooks directly inside it is illegal.
-  useEffect(() => trackEvent(content), [content]);
-  return <Badge>{content.label}</Badge>;
-};
-```
-
-Correct:
-
-```tsx
-function TrackedBadge({ content }: { content: { label: string } }) {
-  useEffect(() => {
-    trackEvent(content);
-  }, [content]);
-  return <Badge>{content.label}</Badge>;
-}
-
-// In the renderer:
-render: ({ content }) => <TrackedBadge content={content} />;
-```
-
-Activity-message renderers re-render on every message-list tick. Side
-effects in the render body fire repeatedly. Hooks cannot be called
-directly inside `render` because the resolver invokes it as a plain
-function; hoist the effect into a wrapper component that React mounts as
-a real element.
-
-Source: `packages/react-core/src/v2/hooks/use-render-activity-message.tsx`
-
-### MEDIUM — Building the `renderActivityMessages` array inline
-
-Wrong:
-
-```tsx
-<CopilotKit
-  runtimeUrl="/api/copilotkit"
-  renderActivityMessages={[progressRenderer, customMcpRenderer]}
-/>
-```
-
-Correct:
-
-```tsx
-const renderers = useMemo(() => [progressRenderer, customMcpRenderer], []);
-<CopilotKit runtimeUrl="/api/copilotkit" renderActivityMessages={renderers} />;
-```
-
-The provider uses `useStableArrayProp` and console-errors when a new array
-identity appears every render. Memoize or hoist the array to module
-scope.
-
-Source: `packages/react-core/src/v2/providers/CopilotKitProvider.tsx` (useStableArrayProp)

package/skills/react-core/references/rendering-tool-calls.md

@@ -1,319 +0,0 @@
-# CopilotKit Rendering Tool Calls (React)
-
-This skill builds on `copilotkit/provider-setup` and
-`copilotkit/client-side-tools`.
-
-Four hooks, distinct roles:
-
-| Hook                   | Role                                                              |
-| ---------------------- | ----------------------------------------------------------------- |
-| `useRenderTool`        | Primary registration hook for a named tool's progress/result UI   |
-| `useComponent`         | Register a NEW render-only tool (agent calls it just to render)   |
-| `useDefaultRenderTool` | Sanctioned wildcard fallback for tools without a dedicated render |
-| `useRenderToolCall`    | Resolver — returns a function. For custom chat surfaces only      |
-
-Status is camelCase: `"inProgress" | "executing" | "complete"`. The
-`RenderToolProps` discriminated union narrows `parameters` per state.
-
-## UI-kit detection rule
-
-Before writing raw JSX, check the consumer's `package.json` for shadcn /
-MUI / Chakra / Ant / Mantine and reuse those primitives.
-
-## Setup
-
-```tsx
-"use client";
-import { useRenderTool } from "@copilotkit/react-core/v2";
-import { z } from "zod";
-import { Card, CardContent } from "@/components/ui/card";
-import { Skeleton } from "@/components/ui/skeleton";
-
-export function SearchRenderer() {
-  useRenderTool({
-    name: "searchDocs",
-    parameters: z.object({ query: z.string() }),
-    render: ({ status, parameters, result }) => {
-      if (status === "inProgress") return <Skeleton className="h-16 w-full" />;
-      if (status === "executing") {
-        return (
-          <Card>
-            <CardContent>Searching "{parameters.query}"…</CardContent>
-          </Card>
-        );
-      }
-      return (
-        <Card>
-          <CardContent>{result}</CardContent>
-        </Card>
-      );
-    },
-  });
-  return null;
-}
-```
-
-## Core Patterns
-
-### Wildcard fallback with the built-in card
-
-```tsx
-import { useDefaultRenderTool } from "@copilotkit/react-core/v2";
-
-useDefaultRenderTool(); // renders the built-in expandable tool-call card
-```
-
-### Custom wildcard fallback
-
-```tsx
-import { useDefaultRenderTool } from "@copilotkit/react-core/v2";
-
-useDefaultRenderTool({
-  render: ({ name, status, parameters, result }) => {
-    // parameters is unknown — narrow by tool name
-    if (name === "search") {
-      const args = parameters as { q: string };
-      return <SearchCard q={args.q} status={status} result={result} />;
-    }
-    return <GenericCard name={name} status={status} />;
-  },
-});
-```
-
-### Render-only tool (the agent's only reason to call it is to render)
-
-```tsx
-import { useComponent } from "@copilotkit/react-core/v2";
-import { z } from "zod";
-
-useComponent({
-  name: "productCard",
-  parameters: z.object({ productId: z.string() }),
-  render: ({ productId }) => <ProductCard id={productId} />,
-});
-// `useComponent` registers a NEW tool called "productCard".
-// The agent calls it to render; there is no handler to run.
-```
-
-### Custom chat surface (resolver hook)
-
-`useRenderToolCall` is for building your own message list, NOT for
-registering renderers.
-
-```tsx
-import { useRenderToolCall } from "@copilotkit/react-core/v2";
-import { useAgent } from "@copilotkit/react-core/v2";
-
-export function CustomToolList() {
-  const { agent } = useAgent({ agentId: "default" });
-  const renderToolCall = useRenderToolCall();
-
-  const toolCalls = agent.messages.flatMap((m) =>
-    "toolCalls" in m ? (m.toolCalls ?? []) : [],
-  );
-
-  return (
-    <>
-      {toolCalls.map((tc) => (
-        <div key={tc.id}>{renderToolCall({ toolCall: tc })}</div>
-      ))}
-    </>
-  );
-}
-```
-
-## Common Mistakes
-
-### CRITICAL — Using `useRenderToolCall` for registration
-
-Wrong:
-
-```tsx
-useRenderToolCall({
-  name: "search",
-  args: z.object({ q: z.string() }),
-  render: ({ status, args }) => <Card>…</Card>,
-});
-```
-
-Correct:
-
-```tsx
-useRenderTool({
-  name: "search",
-  parameters: z.object({ q: z.string() }),
-  render: ({ status, parameters }) => <Card>…</Card>,
-});
-```
-
-`useRenderToolCall` takes no arguments — it returns a resolver function for
-custom chat surfaces. Passing config to it does nothing. `useRenderTool` is
-the registration hook.
-
-Source: `packages/react-core/src/v2/hooks/index.ts:2,7`;
-`packages/react-core/src/v2/hooks/use-render-tool.tsx:37-40`
-
-### CRITICAL — Using hyphenated `"in-progress"` status
-
-Wrong:
-
-```tsx
-render: ({ status, parameters, result }) => {
-  if (status === "in-progress") return <Spinner />;
-  if (status === "executing") return <RunningCard args={parameters} />;
-  return <ResultCard result={result} />;
-};
-```
-
-Correct:
-
-```tsx
-render: ({ status, parameters, result }) => {
-  if (status === "inProgress") return <Spinner />;
-  if (status === "executing") return <RunningCard args={parameters} />;
-  return <ResultCard result={result} />;
-};
-```
-
-Real status values are camelCase: `"inProgress" | "executing" | "complete"`.
-Hyphenated branches never match — users see no progress UI and the fallback
-path fires.
-
-Source: `packages/react-core/src/v2/hooks/use-render-tool.tsx:8-35`
-
-### CRITICAL — Writing JSX from scratch when the app has a UI kit
-
-Wrong:
-
-```tsx
-useRenderTool({
-  name: "search",
-  parameters: z.object({ q: z.string() }),
-  render: () => <div className="my-badge">…</div>,
-});
-```
-
-Correct:
-
-```tsx
-import { Badge } from "@/components/ui/badge";
-
-useRenderTool({
-  name: "search",
-  parameters: z.object({ q: z.string() }),
-  render: () => <Badge variant="secondary">…</Badge>,
-});
-```
-
-Check consumer `package.json` for shadcn / MUI / Chakra / Ant / Mantine
-first. Raw JSX ignores their design system.
-
-Source: maintainer interview (Phase 2c)
-
-### HIGH — Dereferencing required fields from `Partial<T>` during `inProgress`
-
-Wrong:
-
-```tsx
-render: ({ status, parameters }) => (
-  <span>{parameters.user.id.toUpperCase()}</span>
-);
-// `parameters` is Partial<T> during inProgress — `parameters.user` may be undefined.
-```
-
-Correct:
-
-```tsx
-render: ({ status, parameters }) =>
-  status === "inProgress" ? (
-    <Skeleton />
-  ) : (
-    <span>{parameters.user.id.toUpperCase()}</span>
-  );
-```
-
-During streaming, `RenderToolInProgressProps` has
-`parameters: Partial<InferSchemaOutput<S>>`. Fields are `undefined` until
-the stream completes. Narrow with `status === "inProgress"` first.
-
-Source: `packages/react-core/src/v2/hooks/use-render-tool.tsx:8-14`
-
-### HIGH — Using `useComponent` to decorate an existing tool
-
-Wrong:
-
-```tsx
-useFrontendTool({ name: "search", parameters, handler });
-useComponent({
-  name: "search", // creates a SECOND tool named "search" — collision
-  parameters: z.object({ q: z.string() }),
-  render: ({ q }) => <SearchCard q={q} />,
-});
-```
-
-Correct:
-
-```tsx
-useFrontendTool({ name: "search", parameters, handler });
-useRenderTool({
-  name: "search",
-  parameters: z.object({ q: z.string() }),
-  render: ({ status, parameters, result }) => {
-    if (status === "inProgress") return <Skeleton />;
-    if (status === "executing") return <div>Searching {parameters.q}…</div>;
-    return <div>{result}</div>;
-  },
-});
-
-// useComponent is only for render-only tools the agent invokes:
-useComponent({
-  name: "productCard",
-  parameters: z.object({ productId: z.string() }),
-  render: ({ productId }) => <ProductCard id={productId} />,
-});
-```
-
-`useComponent` synthesizes a NEW tool whose only job is to render —
-description is auto-prefixed with "Use this tool to display the …
-component". It does NOT decorate an existing tool. The misleading name
-trap: agents read "useComponent" as "register a component for this tool"
-and end up with two tools colliding on the same name.
-
-Source: `packages/react-core/src/v2/hooks/use-component.tsx:59-88`
-
-### HIGH — Hand-rolling `useRenderTool({ name: "*" })` instead of `useDefaultRenderTool`
-
-Wrong:
-
-```tsx
-useRenderTool({
-  name: "*",
-  render: ({ parameters }) => <pre>{JSON.stringify(parameters)}</pre>,
-});
-```
-
-Correct:
-
-```tsx
-// Use the built-in default card:
-useDefaultRenderTool();
-
-// Or customize, with the correct DefaultRenderProps typing (parameters: unknown):
-useDefaultRenderTool({
-  render: ({ name, status, parameters, result }) => {
-    if (name === "search") {
-      const args = parameters as { q: string };
-      return <SearchCard q={args.q} status={status} />;
-    }
-    return <GenericCard name={name} status={status} />;
-  },
-});
-```
-
-The sanctioned wildcard API is `useDefaultRenderTool`. It wraps
-`useRenderTool({ name: "*" })` with the correct `DefaultRenderProps`
-typing (`parameters: unknown`) and provides a built-in default card when
-no `render` is passed. Hand-rolling loses the default card and invites
-the untyped-args footgun.
-
-Source: `packages/react-core/src/v2/hooks/use-default-render-tool.tsx:15-64`