@copilotkit/vue 1.81.0 → 1.83.0

package/src/v2/components/__tests__/A2UICatalogContext.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { Catalog } from "@a2ui/web_core/v0_9";
+import type { ComponentApi } from "@a2ui/web_core/v0_9";
+import { buildCatalogContextValue } from "../a2ui/A2UICatalogContext";
+import { vueBasicCatalog } from "../a2ui/catalog";
+
+function makeCustomCatalog(): Catalog<ComponentApi> {
+  const components: ComponentApi[] = [
+    { name: "FlightCard", schema: z.object({ airline: z.string() }) },
+    {
+      name: "PieChart",
+      schema: z.object({ innerRadius: z.number().optional() }),
+    },
+  ];
+  return new Catalog<ComponentApi>(
+    "copilotkit://custom-catalog",
+    components,
+    [],
+  );
+}
+
+describe("buildCatalogContextValue", () => {
+  it("includes each custom component's JSON schema by default", () => {
+    const value = buildCatalogContextValue(makeCustomCatalog());
+
+    expect(value).toContain("- copilotkit://custom-catalog");
+    expect(value).toContain("  - FlightCard:");
+    expect(value).toContain('"airline"');
+    expect(value).toContain('"innerRadius"');
+  });
+
+  it("includes schemas when includeSchema is true", () => {
+    const catalog = makeCustomCatalog();
+
+    expect(buildCatalogContextValue(catalog, { includeSchema: true })).toBe(
+      buildCatalogContextValue(catalog),
+    );
+  });
+
+  it("lists custom components by name only when includeSchema is false", () => {
+    const value = buildCatalogContextValue(makeCustomCatalog(), {
+      includeSchema: false,
+    });
+
+    expect(value).toBe(
+      [
+        "Available A2UI catalog:",
+        "- copilotkit://custom-catalog",
+        "  Custom catalog (does NOT include all basic components).",
+        "  Custom components:",
+        "  - FlightCard",
+        "  - PieChart",
+      ].join("\n"),
+    );
+  });
+
+  it("describes the basic catalog the same way regardless of includeSchema", () => {
+    expect(
+      buildCatalogContextValue(vueBasicCatalog, { includeSchema: false }),
+    ).toBe(buildCatalogContextValue(vueBasicCatalog));
+  });
+});

package/src/v2/components/a2ui/A2UICatalogContext.ts

@@ -25,8 +25,14 @@ const A2UI_SCHEMA_CONTEXT_DESCRIPTION =
 /**
  * Build a context string describing the available A2UI catalog.
  * Vue-native equivalent of buildCatalogContextValue from a2ui-renderer.
+ *
+ * When `options.includeSchema` is `false`, custom components are listed by name
+ * only and their JSON schemas are omitted.
  */
-function buildCatalogContextValue(catalog?: Catalog<ComponentApi>): string {
+export function buildCatalogContextValue(
+  catalog?: Catalog<ComponentApi>,
+  options?: { includeSchema?: boolean },
+): string {
   const resolved = catalog ?? vueBasicCatalog;
   const BASIC_CATALOG_ID =
     "https://a2ui.org/specification/v0_9/basic_catalog.json";
@@ -68,6 +74,10 @@ function buildCatalogContextValue(catalog?: Catalog<ComponentApi>): string {
   for (const name of customNames) {
     const comp = resolved.components.get(name);
     if (!comp) continue;
+    if (options?.includeSchema === false) {
+      lines.push(`  - ${name}`);
+      continue;
+    }
     const jsonSchema = zodToJsonSchema(comp.schema);
     lines.push(`  - ${name}:`);
     lines.push(
@@ -127,7 +137,9 @@ export function registerA2UICatalogContext(
   },
 ): void {
   const contextValue = computed(() =>
-    buildCatalogContextValue(options.catalog()),
+    buildCatalogContextValue(options.catalog(), {
+      includeSchema: options.includeSchema(),
+    }),
   );
 
   // Register catalog capabilities context

package/src/v2/components/a2ui/catalog.ts

@@ -88,7 +88,13 @@ const Text = createVueComponent(TextApi, ({ props }) => {
     case "caption":
       return h(
         "small",
-        { style: { ...style, color: "#666", textAlign: "left" } },
+        {
+          style: {
+            ...style,
+            color: "var(--a2ui-color-muted, #666)",
+            textAlign: "left",
+          },
+        },
         text,
       );
     case "body":
@@ -175,7 +181,12 @@ const AudioPlayer = createVueComponent(AudioPlayerApi, ({ props }) => {
       props.description
         ? h(
             "span",
-            { style: { fontSize: "12px", color: "#666" } },
+            {
+              style: {
+                fontSize: "12px",
+                color: "var(--a2ui-color-muted, #666)",
+              },
+            },
             props.description,
           )
         : null,
@@ -239,7 +250,7 @@ const List = createVueComponent(ListApi, ({ props, buildChild }) => {
 const Card = createVueComponent(CardApi, ({ props, buildChild }) => {
   const style = {
     ...getBaseContainerStyle(),
-    backgroundColor: "#fff",
+    backgroundColor: "var(--a2ui-color-surface, #fff)",
     boxShadow: "0 2px 4px rgba(0,0,0,0.1)",
     width: "100%",
   };
@@ -268,7 +279,7 @@ const Tabs = createVueComponent(
           {
             style: {
               display: "flex",
-              borderBottom: "1px solid #ccc",
+              borderBottom: STANDARD_BORDER,
               marginBottom: "8px",
             },
           },
@@ -321,7 +332,7 @@ const Divider = createVueComponent(DividerApi, ({ props }) => {
   const style: Record<string, string> = {
     margin: LEAF_MARGIN,
     border: "none",
-    backgroundColor: "#ccc",
+    backgroundColor: "var(--a2ui-color-border, #ccc)",
   };
 
   if (isVertical) {
@@ -374,7 +385,7 @@ const Modal = createVueComponent(
                 "div",
                 {
                   style: {
-                    backgroundColor: "#fff",
+                    backgroundColor: "var(--a2ui-color-surface, #fff)",
                     padding: "24px",
                     borderRadius: "8px",
                     maxWidth: "90%",
@@ -426,13 +437,13 @@ const Button = createVueComponent(ButtonApi, ({ props, buildChild }) => {
     margin: LEAF_MARGIN,
     padding: "8px 16px",
     cursor: "pointer",
-    border: props.variant === "borderless" ? "none" : "1px solid #ccc",
+    border: props.variant === "borderless" ? "none" : STANDARD_BORDER,
     backgroundColor:
       props.variant === "primary"
         ? "var(--a2ui-primary-color, #007bff)"
         : props.variant === "borderless"
           ? "transparent"
-          : "#fff",
+          : "var(--a2ui-color-surface, #fff)",
     color: props.variant === "primary" ? "#fff" : "inherit",
     borderRadius: "4px",
     display: "inline-flex",
@@ -469,7 +480,7 @@ const TextField = createVueComponent(
       width: "100%",
       border:
         props.validationErrors && props.validationErrors.length > 0
-          ? "1px solid red"
+          ? "1px solid var(--a2ui-color-error, red)"
           : STANDARD_BORDER,
       borderRadius: STANDARD_RADIUS,
       boxSizing: "border-box",
@@ -519,7 +530,12 @@ const TextField = createVueComponent(
         hasError
           ? h(
               "span",
-              { style: { fontSize: "12px", color: "red" } },
+              {
+                style: {
+                  fontSize: "12px",
+                  color: "var(--a2ui-color-error, red)",
+                },
+              },
               props.validationErrors![0],
             )
           : null,
@@ -558,7 +574,9 @@ const CheckBox = createVueComponent(
                 props.setValue((e.target as HTMLInputElement).checked),
               style: {
                 cursor: "pointer",
-                outline: hasError ? "1px solid red" : "none",
+                outline: hasError
+                  ? "1px solid var(--a2ui-color-error, red)"
+                  : "none",
               },
             }),
             props.label
@@ -568,7 +586,9 @@ const CheckBox = createVueComponent(
                     for: uniqueId,
                     style: {
                       cursor: "pointer",
-                      color: hasError ? "red" : "inherit",
+                      color: hasError
+                        ? "var(--a2ui-color-error, red)"
+                        : "inherit",
                     },
                   },
                   props.label,
@@ -580,7 +600,11 @@ const CheckBox = createVueComponent(
           ? h(
               "span",
               {
-                style: { fontSize: "12px", color: "red", marginTop: "4px" },
+                style: {
+                  fontSize: "12px",
+                  color: "var(--a2ui-color-error, red)",
+                  marginTop: "4px",
+                },
               },
               props.validationErrors?.[0],
             )
@@ -681,7 +705,7 @@ const ChoicePicker = createVueComponent(
                       : STANDARD_BORDER,
                     backgroundColor: isSelected
                       ? "var(--a2ui-primary-color, #007bff)"
-                      : "#fff",
+                      : "var(--a2ui-color-surface, #fff)",
                     color: isSelected ? "#fff" : "inherit",
                     cursor: "pointer",
                     fontSize: "12px",
@@ -754,7 +778,12 @@ const Slider = createVueComponent(
               : null,
             h(
               "span",
-              { style: { fontSize: "12px", color: "#666" } },
+              {
+                style: {
+                  fontSize: "12px",
+                  color: "var(--a2ui-color-muted, #666)",
+                },
+              },
               String(props.value),
             ),
           ],

package/src/v2/components/a2ui/utils.ts

@@ -12,7 +12,7 @@ export const LEAF_MARGIN = "8px";
 export const CONTAINER_PADDING = "16px";
 
 /** Standard border for cards and inputs. */
-export const STANDARD_BORDER = "1px solid #ccc";
+export const STANDARD_BORDER = "1px solid var(--a2ui-color-border, #ccc)";
 
 /** Standard border radius. */
 export const STANDARD_RADIUS = "8px";

package/src/v2/components/chat/CopilotChatAttachmentQueue.vue

@@ -7,6 +7,8 @@ import {
 } from "@copilotkit/shared";
 import type { Attachment } from "@copilotkit/shared";
 import type { CopilotChatAttachmentQueueProps } from "./types";
+import { useCopilotChatConfiguration } from "../../providers/useCopilotChatConfiguration";
+import { CopilotChatDefaultLabels } from "../../providers/types";
 
 const props = withDefaults(defineProps<CopilotChatAttachmentQueueProps>(), {
   attachments: () => [],
@@ -17,6 +19,9 @@ const emit = defineEmits<{
   "remove-attachment": [id: string];
 }>();
 
+const config = useCopilotChatConfiguration();
+const labels = computed(() => config.value?.labels ?? CopilotChatDefaultLabels);
+
 const activeLightboxAttachment = ref<Attachment | null>(null);
 const documentBlobUrl = ref<string | null>(null);
 
@@ -215,7 +220,7 @@ function createBlobUrl(
           <button
             type="button"
             class="cpk:absolute cpk:inset-0 cpk:flex cpk:items-center cpk:justify-center cpk:z-10 cpk:cursor-pointer cpk:bg-black/20 cpk:border-none cpk:p-0"
-            aria-label="Play video"
+            :aria-label="labels.attachmentPlayVideoButtonLabel"
             data-testid="copilot-chat-attachment-video-play"
             @click="openLightbox(attachment)"
           >
@@ -294,7 +299,7 @@ function createBlobUrl(
       <button
         type="button"
         class="cpk:absolute cpk:bg-black/60 cpk:text-white cpk:border-none cpk:rounded-full cpk:w-5 cpk:h-5 cpk:flex cpk:items-center cpk:justify-center cpk:cursor-pointer cpk:text-[10px] cpk:z-20 cpk:top-1 cpk:right-1"
-        aria-label="Remove attachment"
+        :aria-label="labels.attachmentRemoveButtonLabel"
         @click="emit('remove-attachment', attachment.id)"
       >
         ✕
@@ -312,7 +317,7 @@ function createBlobUrl(
       <button
         type="button"
         class="cpk:absolute cpk:top-4 cpk:right-4 cpk:text-white cpk:bg-white/10 cpk:hover:bg-white/20 cpk:rounded-full cpk:w-10 cpk:h-10 cpk:flex cpk:items-center cpk:justify-center cpk:cursor-pointer cpk:border-none"
-        aria-label="Close preview"
+        :aria-label="labels.attachmentPreviewCloseButtonLabel"
         @click.stop="closeLightbox"
       >
         ✕

package/src/v2/components/chat/CopilotChatInput.vue

@@ -1118,7 +1118,7 @@ onBeforeUnmount(() => {
                   ref="slashMenuRef"
                   data-testid="copilot-slash-menu"
                   role="listbox"
-                  aria-label="Slash commands"
+                  :aria-label="labels.chatInputSlashMenuLabel"
                   class="cpk:absolute cpk:bottom-full cpk:left-0 cpk:right-0 cpk:z-30 cpk:mb-2 cpk:max-h-64 cpk:overflow-y-auto cpk:rounded-lg cpk:border cpk:border-border cpk:bg-white cpk:shadow-lg cpk:dark:border-[#3a3a3a] cpk:dark:bg-[#1f1f1f]"
                   :style="{ maxHeight: `${5 * 40}px` }"
                 >
@@ -1126,7 +1126,7 @@ onBeforeUnmount(() => {
                     v-if="filteredCommands.length === 0"
                     class="cpk:px-3 cpk:py-2 cpk:text-sm cpk:text-muted-foreground"
                   >
-                    No commands found
+                    {{ labels.chatInputSlashMenuEmptyText }}
                   </div>
                   <button
                     v-for="(command, index) in filteredCommands"

package/src/v2/components/chat/CopilotChatReasoningMessage.vue

@@ -3,6 +3,8 @@ import { computed, onBeforeUnmount, ref, watch } from "vue";
 import type { Message, ReasoningMessage } from "@ag-ui/core";
 import { StreamMarkdown } from "streamdown-vue";
 import { IconChevronRight } from "../icons";
+import { useCopilotChatConfiguration } from "../../providers/useCopilotChatConfiguration";
+import { CopilotChatDefaultLabels } from "../../providers/types";
 
 const props = withDefaults(
   defineProps<{
@@ -26,6 +28,7 @@ defineSlots<{
       label: string;
       hasContent: boolean;
       isStreaming: boolean;
+      elapsedSeconds: number;
       onClick?: () => void;
     };
     contentView: {
@@ -47,6 +50,8 @@ defineSlots<{
     label: string;
     hasContent: boolean;
     isStreaming: boolean;
+    /** Seconds spent reasoning so far, for building a localized label. */
+    elapsedSeconds: number;
     onClick?: () => void;
   }) => unknown;
   "content-view"?: (props: {
@@ -128,9 +133,12 @@ onBeforeUnmount(() => {
   clearElapsedInterval();
 });
 
+const config = useCopilotChatConfiguration();
+/** `labels.reasoningMessageThinkingLabel` while streaming, then "Thought for …". */
 const label = computed(() =>
   isStreaming.value
-    ? "Thinking…"
+    ? (config.value?.labels ?? CopilotChatDefaultLabels)
+        .reasoningMessageThinkingLabel
     : `Thought for ${formatDuration(elapsed.value)}`,
 );
 
@@ -153,6 +161,7 @@ function toggleOpen() {
         label,
         hasContent,
         isStreaming,
+        elapsedSeconds: elapsed,
         onClick: hasContent ? toggleOpen : undefined,
       }"
       :content-view="{
@@ -175,6 +184,7 @@ function toggleOpen() {
         :label="label"
         :has-content="hasContent"
         :is-streaming="isStreaming"
+        :elapsed-seconds="elapsed"
         :on-click="hasContent ? toggleOpen : undefined"
       >
         <button

package/src/v2/components/chat/CopilotModalHeader.vue

@@ -107,7 +107,10 @@ function toggleDrawer() {
             data-testid="drawer-launcher"
             class="cpk:inline-flex cpk:size-8 cpk:items-center cpk:justify-center cpk:rounded-full cpk:text-muted-foreground cpk:transition cpk:cursor-pointer cpk:hover:bg-muted cpk:hover:text-foreground cpk:focus-visible:outline-none cpk:focus-visible:ring-2 cpk:focus-visible:ring-ring"
             :aria-expanded="config?.drawerOpen ?? false"
-            aria-label="Open threads"
+            :aria-label="
+              config?.labels.modalHeaderThreadsButtonLabel ??
+              CopilotChatDefaultLabels.modalHeaderThreadsButtonLabel
+            "
             @click="toggleDrawer"
           >
             <IconPanelLeftOpen class="cpk:h-4 cpk:w-4" aria-hidden="true" />

package/src/v2/components/chat/CopilotModalHeaderCloseButton.ts

@@ -1,13 +1,23 @@
 import { computed, defineComponent, h, useAttrs } from "vue";
 import { IconX } from "../icons";
+import { useCopilotChatConfiguration } from "../../providers/useCopilotChatConfiguration";
+import { CopilotChatDefaultLabels } from "../../providers/types";
 
+/**
+ * Closes the popup or sidebar. Its accessible name is the `aria-label` the
+ * parent passes, or `labels.modalHeaderCloseButtonLabel`.
+ */
 export default defineComponent({
   name: "CopilotModalHeaderCloseButton",
   inheritAttrs: false,
   setup(_, { slots }) {
     const attrs = useAttrs();
+    const config = useCopilotChatConfiguration();
     const ariaLabel = computed(() =>
-      typeof attrs["aria-label"] === "string" ? attrs["aria-label"] : "Close",
+      typeof attrs["aria-label"] === "string"
+        ? attrs["aria-label"]
+        : (config.value?.labels ?? CopilotChatDefaultLabels)
+            .modalHeaderCloseButtonLabel,
     );
 
     return () => {

package/src/v2/components/chat/CopilotSidebarViewInternal.vue

@@ -277,7 +277,9 @@ onBeforeUnmount(() => {
     data-copilot-sidebar
     :class="asideClass"
     :style="asideStyle"
-    aria-label="Copilot chat sidebar"
+    :aria-label="
+      config?.labels.sidebarLabel ?? CopilotChatDefaultLabels.sidebarLabel
+    "
     :aria-hidden="!isSidebarOpen"
     role="complementary"
     v-bind="asideAttrs"

package/src/v2/components/chat/__tests__/CopilotChat.labels.test.ts

@@ -0,0 +1,198 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { defineComponent, nextTick, onMounted } from "vue";
+import { fireEvent, render, screen } from "@testing-library/vue";
+import type { Message, ReasoningMessage } from "@ag-ui/core";
+import type { Attachment } from "@copilotkit/shared";
+import CopilotKitProvider from "../../../providers/CopilotKitProvider.vue";
+import CopilotChatConfigurationProvider from "../../../providers/CopilotChatConfigurationProvider.vue";
+import { useCopilotChatConfiguration } from "../../../providers/useCopilotChatConfiguration";
+import type { CopilotChatLabels } from "../../../providers/types";
+import CopilotChatReasoningMessage from "../CopilotChatReasoningMessage.vue";
+import CopilotChatAttachmentQueue from "../CopilotChatAttachmentQueue.vue";
+import CopilotChatInput from "../CopilotChatInput.vue";
+import { CopilotModalHeader, CopilotSidebarView } from "../index";
+
+// Strings an app translates through `labels`. Every one of them used to be
+// hard-coded English.
+const germanLabels: Partial<Record<keyof CopilotChatLabels, string>> = {
+  reasoningMessageThinkingLabel: "Denkt nach…",
+  chatInputSlashMenuLabel: "Befehle",
+  chatInputSlashMenuEmptyText: "Keine Befehle gefunden",
+  attachmentRemoveButtonLabel: "Anhang entfernen",
+  attachmentPlayVideoButtonLabel: "Video abspielen",
+  attachmentPreviewCloseButtonLabel: "Vorschau schließen",
+  modalHeaderCloseButtonLabel: "Schließen",
+  modalHeaderThreadsButtonLabel: "Unterhaltungen öffnen",
+  sidebarLabel: "Chat-Seitenleiste",
+};
+
+const reasoning = {
+  id: "reasoning-1",
+  role: "reasoning",
+  content: "",
+} as ReasoningMessage;
+
+const video: Attachment = {
+  id: "clip",
+  type: "video",
+  source: { type: "data", value: "AAAA", mimeType: "video/mp4" },
+  filename: "clip.mp4",
+  status: "ready",
+};
+
+/** Registers a threads drawer, which the header needs before it shows its launcher. */
+const DrawerRegistrar = defineComponent({
+  setup() {
+    const config = useCopilotChatConfiguration();
+    onMounted(() => config.value?.registerDrawer());
+  },
+  template: `<span />`,
+});
+
+/** Renders `template` inside the providers, with the German labels configured. */
+function renderWithLabels(template: string) {
+  const Host = defineComponent({
+    components: {
+      CopilotKitProvider,
+      CopilotChatConfigurationProvider,
+      CopilotChatReasoningMessage,
+      CopilotChatAttachmentQueue,
+      CopilotChatInput,
+      CopilotModalHeader,
+      CopilotSidebarView,
+      DrawerRegistrar,
+    },
+    setup() {
+      return {
+        labels: germanLabels,
+        reasoning,
+        reasoningMessages: [reasoning] as Message[],
+        attachments: [video],
+        toolsMenu: [{ label: "Say hi", action: vi.fn() }],
+      };
+    },
+    template: `
+      <CopilotKitProvider runtime-url="/api/copilotkit">
+        <CopilotChatConfigurationProvider thread-id="thread-1" :labels="labels">
+          ${template}
+        </CopilotChatConfigurationProvider>
+      </CopilotKitProvider>
+    `,
+  });
+  return render(Host);
+}
+
+describe("chat strings from labels", () => {
+  beforeEach(() => {
+    vi.stubGlobal(
+      "ResizeObserver",
+      class {
+        observe() {}
+        unobserve() {}
+        disconnect() {}
+      },
+    );
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+  });
+
+  it("uses the configured reasoning label while the model reasons", () => {
+    renderWithLabels(`
+      <CopilotChatReasoningMessage
+        :message="reasoning"
+        :messages="reasoningMessages"
+        :is-running="true"
+      />
+    `);
+
+    expect(screen.getByText("Denkt nach…")).toBeDefined();
+    expect(screen.queryByText("Thinking…")).toBeNull();
+  });
+
+  it("passes the elapsed reasoning time to a custom header", async () => {
+    vi.useFakeTimers();
+    renderWithLabels(`
+      <CopilotChatReasoningMessage
+        :message="reasoning"
+        :messages="reasoningMessages"
+        :is-running="true"
+      >
+        <template #header="{ elapsedSeconds }">
+          <span>{{ Math.round(elapsedSeconds) }} Sekunden</span>
+        </template>
+      </CopilotChatReasoningMessage>
+    `);
+
+    expect(screen.getByText("0 Sekunden")).toBeDefined();
+    vi.advanceTimersByTime(3000);
+    await nextTick();
+    expect(screen.getByText("3 Sekunden")).toBeDefined();
+  });
+
+  it("names the slash-command menu and its empty state", async () => {
+    renderWithLabels(`<CopilotChatInput :tools-menu="toolsMenu" />`);
+
+    await fireEvent.input(screen.getByRole("textbox"), {
+      target: { value: "/zzz" },
+    });
+
+    expect(
+      await screen.findByRole("listbox", { name: "Befehle" }),
+    ).toBeDefined();
+    expect(screen.getByText("Keine Befehle gefunden")).toBeDefined();
+  });
+
+  it("names the attachment queue buttons and the preview close button", async () => {
+    renderWithLabels(
+      `<CopilotChatAttachmentQueue :attachments="attachments" />`,
+    );
+
+    expect(
+      screen.getByRole("button", { name: "Anhang entfernen" }),
+    ).toBeDefined();
+    await fireEvent.click(
+      screen.getByRole("button", { name: "Video abspielen" }),
+    );
+    expect(
+      await screen.findByRole("button", { name: "Vorschau schließen" }),
+    ).toBeDefined();
+  });
+
+  it("names the modal header close and threads buttons", async () => {
+    // A mobile viewport: the threads launcher only renders there.
+    vi.stubGlobal(
+      "matchMedia",
+      vi.fn().mockReturnValue({
+        matches: true,
+        media: "(max-width: 767px)",
+        onchange: null,
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+        addListener: vi.fn(),
+        removeListener: vi.fn(),
+        dispatchEvent: vi.fn(),
+      }),
+    );
+    renderWithLabels(`<CopilotModalHeader /><DrawerRegistrar />`);
+
+    expect(
+      await screen.findByRole("button", { name: "Unterhaltungen öffnen" }),
+    ).toBeDefined();
+    expect(screen.getByRole("button", { name: "Schließen" })).toBeDefined();
+  });
+
+  it("names the sidebar", () => {
+    renderWithLabels(`<CopilotSidebarView />`);
+
+    // The sidebar starts closed, so it is aria-hidden until opened.
+    expect(
+      screen.getByRole("complementary", {
+        name: "Chat-Seitenleiste",
+        hidden: true,
+      }),
+    ).toBeDefined();
+  });
+});

package/src/v2/providers/CopilotKitProvider.types.ts

@@ -90,6 +90,21 @@ export interface CopilotKitProviderProps {
     theme?: A2UITheme;
     catalog?: any;
     loadingComponent?: Component;
+    /**
+     * When true (the default), the full component schemas from the catalog are
+     * sent as agent context so the agent knows what components and props are
+     * available. The A2UI middleware can overwrite this with a server-side
+     * schema if configured.
+     *
+     * When false, the agent context still describes the catalog, but only by its
+     * catalog ID and the names of its custom components, without their JSON
+     * schemas. The component schema entry and the A2UI generation and design
+     * guidelines are not sent. With the CopilotKit LangGraph middleware's
+     * injected A2UI tool, the A2UI subagent then gets the component names only;
+     * a host can still give it a composition guide through the middleware's
+     * guidelines (`a2uiParams.guidelines.compositionGuide` in TypeScript,
+     * `a2ui_params["guidelines"]["composition_guide"]` in Python).
+     */
     includeSchema?: boolean;
   };
   /** Configuration for the built-in MCP Apps renderer. */