@copilotkit/vue 1.62.1 → 1.62.2

package/src/v2/lib/is-mobile-viewport.ts

@@ -0,0 +1,23 @@
+/**
+ * Media query for the mobile breakpoint, shared so the string literal isn't
+ * duplicated across call sites within this package (e.g. `CopilotModalHeader`,
+ * which needs a live `matchMedia` change-listener and so can't call
+ * `isMobileViewport()` directly).
+ */
+export const MOBILE_MAX_WIDTH_QUERY = "(max-width: 767px)";
+
+/**
+ * Reports whether the viewport is in the mobile range (`<768px`), where the
+ * drawer and chat modal are mutually exclusive. SSR-safe (returns `false`
+ * when `window` is absent) and guards environments where `window` exists but
+ * `window.matchMedia` does not (some test runners, embedded webviews).
+ */
+export function isMobileViewport(): boolean {
+  if (
+    typeof window === "undefined" ||
+    typeof window.matchMedia !== "function"
+  ) {
+    return false;
+  }
+  return window.matchMedia(MOBILE_MAX_WIDTH_QUERY).matches;
+}

package/src/v2/providers/CopilotChatConfigurationProvider.vue

@@ -7,6 +7,7 @@ import { CopilotChatDefaultLabels } from "./types";
 import type { CopilotChatConfigurationValue, CopilotChatLabels } from "./types";
 import type { CopilotChatConfigurationProviderProps } from "./CopilotChatConfigurationProvider.types";
 import { useShallowStableRef } from "../lib/shallow-stable";
+import { isMobileViewport } from "../lib/is-mobile-viewport";
 
 // Vue normalizes optional Boolean props to `false` when not supplied; declare
 // `undefined` defaults so we can faithfully distinguish "caller passed false"
@@ -24,6 +25,20 @@ const parentConfig = inject<ComputedRef<CopilotChatConfigurationValue> | null>(
   null,
 );
 const parentConfigValue = computed(() => parentConfig?.value ?? null);
+
+// Caller-authoritative when a threadId prop is supplied AND not explicitly
+// flagged non-explicit. A <CopilotKit>-seeded non-explicit id
+// (threadId + hasExplicitThreadId=false) stays overridable — the round-2 fix.
+const propIsAuthoritative = computed(
+  () => props.threadId !== undefined && props.hasExplicitThreadId !== false,
+);
+
+// Imperative active-thread override (a picked row or a fresh startNewThread).
+const activeThreadOverride = ref<{
+  threadId: string;
+  explicit: boolean;
+} | null>(null);
+
 const stableLabels = useShallowStableRef(computed(() => props.labels));
 
 const mergedLabels = computed<CopilotChatLabels>(() => ({
@@ -38,6 +53,8 @@ const resolvedAgentId = computed(
 
 const fallbackThreadId = randomUUID();
 const resolvedThreadId = computed(() => {
+  if (propIsAuthoritative.value) return props.threadId as string;
+  if (activeThreadOverride.value) return activeThreadOverride.value.threadId;
   if (props.threadId) return props.threadId;
   if (parentConfigValue.value?.threadId)
     return parentConfigValue.value.threadId;
@@ -45,11 +62,13 @@ const resolvedThreadId = computed(() => {
 });
 
 const resolvedHasExplicitThreadId = computed(() => {
-  const ownExplicit =
-    props.hasExplicitThreadId !== undefined
+  if (propIsAuthoritative.value) return true;
+  const own = activeThreadOverride.value
+    ? activeThreadOverride.value.explicit
+    : props.hasExplicitThreadId !== undefined
       ? props.hasExplicitThreadId
       : !!props.threadId;
-  return ownExplicit || !!parentConfigValue.value?.hasExplicitThreadId;
+  return own || !!parentConfigValue.value?.hasExplicitThreadId;
 });
 
 const shouldCreateModalState = computed(
@@ -76,13 +95,110 @@ const resolvedSetModalOpen = computed(() =>
     : parentConfigValue.value?.setModalOpen,
 );
 
+function setActiveThreadId(threadId: string, options?: { explicit?: boolean }) {
+  if (propIsAuthoritative.value) {
+    console.warn(
+      "[CopilotKit] Ignoring setActiveThreadId(): threadId is controlled " +
+        "via the `threadId` prop on CopilotChatConfigurationProvider.",
+    );
+    return;
+  }
+  activeThreadOverride.value = {
+    threadId,
+    explicit: options?.explicit ?? true,
+  };
+}
+
+function startNewThread() {
+  if (propIsAuthoritative.value) {
+    console.warn(
+      "[CopilotKit] Ignoring startNewThread(): threadId is controlled via " +
+        "the `threadId` prop on CopilotChatConfigurationProvider.",
+    );
+    return;
+  }
+  activeThreadOverride.value = { threadId: randomUUID(), explicit: false };
+}
+
+// Drawer presence + open state. The top-most provider owns the state; a nested
+// provider proxies its parent so the whole chain shares one drawer.
+const ownDrawerOpen = ref(false);
+const ownDrawerCount = ref(0);
+
+function ownSetDrawerOpen(open: boolean) {
+  ownDrawerOpen.value = open;
+  // Mobile mutual-exclusion: opening the drawer closes the chat modal.
+  if (open && isMobileViewport()) {
+    resolvedSetModalOpen.value?.(false);
+  }
+}
+
+function ownRegisterDrawer(): () => void {
+  ownDrawerCount.value += 1;
+  return () => {
+    ownDrawerCount.value = Math.max(0, ownDrawerCount.value - 1);
+  };
+}
+
+const resolvedDrawerOpen = computed(() =>
+  parentConfigValue.value
+    ? parentConfigValue.value.drawerOpen
+    : ownDrawerOpen.value,
+);
+const resolvedSetDrawerOpen = computed(() =>
+  parentConfigValue.value
+    ? parentConfigValue.value.setDrawerOpen
+    : ownSetDrawerOpen,
+);
+const resolvedDrawerRegistered = computed(() =>
+  parentConfigValue.value
+    ? parentConfigValue.value.drawerRegistered
+    : ownDrawerCount.value > 0,
+);
+const resolvedRegisterDrawer = computed(() =>
+  parentConfigValue.value
+    ? parentConfigValue.value.registerDrawer
+    : ownRegisterDrawer,
+);
+
+// Public modal setter (mobile mutual-exclusion, other direction: opening the
+// chat modal closes the drawer). Preserve the contract that it is `undefined`
+// when this provider owns no modal state AND no parent provides one —
+// CopilotChatToggleButton relies on that absence to fall back to its own
+// local open-state. When a real modal setter exists (own `isModalDefaultOpen`
+// state or an inherited parent setter), wrap it so opening the modal on
+// mobile also closes the drawer.
+//
+// Note: this diverges from the React reference (CopilotChatConfigurationProvider.tsx),
+// which keeps `setModalOpen` always-defined and always backed by internal state. We
+// intentionally take the minimal Vue-local fix here — preserving the `undefined`
+// contract CopilotChatToggleButton depends on — rather than also reworking
+// `resolvedIsModalOpen`'s backing, to avoid changing bare-provider modal-open
+// semantics.
+const publicSetModalOpen = computed(() => {
+  const base = resolvedSetModalOpen.value; // undefined when no modal state + no parent
+  if (!base) return undefined;
+  return (open: boolean) => {
+    if (open && isMobileViewport()) {
+      resolvedSetDrawerOpen.value?.(false);
+    }
+    base(open);
+  };
+});
+
 const configurationValue = computed<CopilotChatConfigurationValue>(() => ({
   labels: mergedLabels.value,
   agentId: resolvedAgentId.value,
   threadId: resolvedThreadId.value,
   hasExplicitThreadId: resolvedHasExplicitThreadId.value,
   isModalOpen: resolvedIsModalOpen.value,
-  setModalOpen: resolvedSetModalOpen.value,
+  setModalOpen: publicSetModalOpen.value,
+  drawerOpen: resolvedDrawerOpen.value,
+  setDrawerOpen: resolvedSetDrawerOpen.value,
+  drawerRegistered: resolvedDrawerRegistered.value,
+  registerDrawer: resolvedRegisterDrawer.value,
+  setActiveThreadId,
+  startNewThread,
 }));
 
 provide(CopilotChatConfigurationKey, configurationValue);

package/src/v2/providers/__tests__/CopilotChatConfigurationProvider.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { mount } from "@vue/test-utils";
 import { defineComponent, h, nextTick } from "vue";
 import { DEFAULT_AGENT_ID } from "@copilotkit/shared";
@@ -307,3 +307,107 @@ describe("CopilotChatConfigurationProvider", () => {
     expect(wrapper.find("[data-testid=child-modal]").text()).toBe("false");
   });
 });
+
+function harness(providerProps: Record<string, unknown>) {
+  let cfg!: ReturnType<typeof useCopilotChatConfiguration>;
+  const Probe = defineComponent({
+    setup() {
+      cfg = useCopilotChatConfiguration();
+      return () => h("div", cfg.value?.threadId ?? "none");
+    },
+  });
+  mount(CopilotChatConfigurationProvider, {
+    props: providerProps,
+    slots: { default: () => h(Probe) },
+  });
+  return () => cfg.value!;
+}
+
+describe("CopilotChatConfiguration active-thread setters", () => {
+  it("setActiveThreadId overrides a non-explicit seed and flags it explicit", async () => {
+    // A <CopilotKit>-style non-explicit seed: threadId prop + hasExplicitThreadId=false.
+    const cfg = harness({ threadId: "seed-uuid", hasExplicitThreadId: false });
+    cfg().setActiveThreadId("picked-thread");
+    await nextTick();
+    expect(cfg().threadId).toBe("picked-thread");
+    expect(cfg().hasExplicitThreadId).toBe(true);
+  });
+
+  it("startNewThread mints a fresh non-explicit thread", async () => {
+    const cfg = harness({ threadId: "seed-uuid", hasExplicitThreadId: false });
+    cfg().setActiveThreadId("picked-thread");
+    await nextTick();
+    cfg().startNewThread();
+    await nextTick();
+    expect(cfg().threadId).not.toBe("picked-thread");
+    expect(cfg().hasExplicitThreadId).toBe(false);
+  });
+
+  it("a caller-authoritative threadId prop is NOT overridable", async () => {
+    const cfg = harness({ threadId: "controlled" }); // no hasExplicitThreadId => authoritative
+    cfg().setActiveThreadId("ignored");
+    await nextTick();
+    expect(cfg().threadId).toBe("controlled");
+  });
+});
+
+describe("CopilotChatConfiguration drawer-awareness", () => {
+  it("registerDrawer flips drawerRegistered and cleans up", async () => {
+    const cfg = harness({ isModalDefaultOpen: true });
+    expect(cfg().drawerRegistered).toBe(false);
+    const unregister = cfg().registerDrawer();
+    await nextTick();
+    expect(cfg().drawerRegistered).toBe(true);
+    unregister();
+    await nextTick();
+    expect(cfg().drawerRegistered).toBe(false);
+  });
+
+  it("opening the drawer on mobile closes the modal", async () => {
+    vi.spyOn(window, "matchMedia").mockReturnValue({
+      matches: true,
+    } as MediaQueryList);
+    const cfg = harness({ isModalDefaultOpen: true });
+    expect(cfg().isModalOpen).toBe(true);
+    cfg().setDrawerOpen(true);
+    await nextTick();
+    expect(cfg().drawerOpen).toBe(true);
+    expect(cfg().isModalOpen).toBe(false);
+    vi.restoreAllMocks();
+  });
+
+  it("opening the modal on mobile closes the drawer", async () => {
+    vi.spyOn(window, "matchMedia").mockReturnValue({
+      matches: true,
+    } as MediaQueryList);
+    const cfg = harness({ isModalDefaultOpen: true });
+
+    // First open the drawer (closing the modal via the existing exclusion).
+    cfg().setDrawerOpen(true);
+    await nextTick();
+    expect(cfg().drawerOpen).toBe(true);
+    expect(cfg().isModalOpen).toBe(false);
+
+    // Now open the modal and confirm the reverse exclusion closes the drawer.
+    cfg().setModalOpen(true);
+    await nextTick();
+    expect(cfg().isModalOpen).toBe(true);
+    expect(cfg().drawerOpen).toBe(false);
+    vi.restoreAllMocks();
+  });
+});
+
+describe("CopilotChatConfiguration modal-setter presence contract", () => {
+  it("bare provider (no isModalDefaultOpen, no parent) exposes setModalOpen as undefined", () => {
+    const cfg = harness({ threadId: "thread-1" });
+    expect(cfg().setModalOpen).toBeUndefined();
+  });
+
+  it("provider with isModalDefaultOpen exposes a working setModalOpen", async () => {
+    const cfg = harness({ isModalDefaultOpen: true });
+    expect(typeof cfg().setModalOpen).toBe("function");
+    cfg().setModalOpen(false);
+    await nextTick();
+    expect(cfg().isModalOpen).toBe(false);
+  });
+});

package/src/v2/providers/types.ts

@@ -37,4 +37,29 @@ export interface CopilotChatConfigurationValue {
   hasExplicitThreadId: boolean;
   isModalOpen?: boolean;
   setModalOpen?: (open: boolean) => void;
+  /**
+   * Switches the active thread to `threadId`. `explicit` (default `true`)
+   * marks it a caller-driven choice so the welcome screen is suppressed.
+   * No-op when the provider's `threadId` prop is caller-authoritative.
+   */
+  setActiveThreadId: (
+    threadId: string,
+    options?: { explicit?: boolean },
+  ) => void;
+  /**
+   * Switches to a freshly-minted, non-explicit thread (welcome screen shows).
+   * No-op when the provider's `threadId` prop is caller-authoritative.
+   */
+  startNewThread: () => void;
+  /** Whether the mobile off-canvas drawer overlay is open. */
+  drawerOpen: boolean;
+  /**
+   * Toggles the drawer. On mobile (`<=767px`) opening the drawer closes the
+   * chat modal (mutual-exclusion). Desktop imposes no constraint.
+   */
+  setDrawerOpen: (open: boolean) => void;
+  /** True when at least one drawer has registered (gates the header launcher). */
+  drawerRegistered: boolean;
+  /** Announces drawer presence; returns a cleanup that de-registers it. */
+  registerDrawer: () => () => void;
 }