@copilotkit/vue 1.62.0 → 1.62.2

package/src/v2/hooks/use-threads.ts

@@ -5,6 +5,7 @@ import {
   ɵcreateThreadStore,
   ɵselectHasNextPage,
   ɵselectIsFetchingNextPage,
+  ɵselectIsMutating,
   ɵselectThreads,
   ɵselectThreadsError,
   ɵselectThreadsIsLoading,
@@ -32,17 +33,29 @@ export interface UseThreadsInput {
   agentId: MaybeRefOrGetter<string>;
   includeArchived?: MaybeRefOrGetter<boolean | undefined>;
   limit?: MaybeRefOrGetter<number | undefined>;
+  /**
+   * When `false`, the hook clears the store context and issues no `/threads`
+   * request — used by the drawer to skip fetching while unlicensed. Defaults
+   * to `true`.
+   */
+  enabled?: MaybeRefOrGetter<boolean | undefined>;
 }
 
 export interface UseThreadsResult {
   threads: Ref<Thread[]>;
   isLoading: Ref<boolean>;
   error: Ref<Error | null>;
+  /** Genuine list-load/mutation errors only — excludes dev/config errors. */
+  listError: Ref<Error | null>;
   hasMoreThreads: Ref<boolean>;
   isFetchingMoreThreads: Ref<boolean>;
+  isMutating: Ref<boolean>;
   fetchMoreThreads: () => void;
+  refetchThreads: () => void;
+  startNewThread: () => void;
   renameThread: (threadId: string, name: string) => Promise<void>;
   archiveThread: (threadId: string) => Promise<void>;
+  unarchiveThread: (threadId: string) => Promise<void>;
   deleteThread: (threadId: string) => Promise<void>;
 }
 
@@ -77,6 +90,41 @@ export function useThreads(input: UseThreadsInput): UseThreadsResult {
     toValue(input.includeArchived),
   );
   const resolvedLimit = computed(() => toValue(input.limit));
+  const resolvedEnabled = computed(() => toValue(input.enabled) ?? true);
+
+  // Thread-endpoint capability, derived from the runtime's `/info` payload.
+  // `threadEndpoints` is `undefined` on legacy runtimes that don't advertise
+  // the capability, so we treat "not explicitly false" as supported (matching
+  // React's `!== false` semantics) to preserve legacy thread behavior.
+  const threadListEndpointSupported = computed(
+    () => copilotkit.value.threadEndpoints?.list !== false,
+  );
+  const threadMutationsSupported = computed(
+    () => copilotkit.value.threadEndpoints?.mutations !== false,
+  );
+  // Connected, but the runtime explicitly does not serve the list endpoint.
+  const threadEndpointsUnavailable = computed(
+    () =>
+      !!copilotkit.value.runtimeUrl &&
+      copilotkit.value.runtimeConnectionStatus ===
+        CopilotKitCoreRuntimeConnectionStatus.Connected &&
+      !threadListEndpointSupported.value,
+  );
+  const threadEndpointsError = computed<Error | null>(() =>
+    threadEndpointsUnavailable.value
+      ? new Error(
+          "Thread endpoints are not available on this CopilotKit runtime",
+        )
+      : null,
+  );
+  const threadMutationsError = computed<Error | null>(() =>
+    threadMutationsSupported.value
+      ? null
+      : new Error(
+          "Thread mutations are not available on this CopilotKit runtime",
+        ),
+  );
+
   const headersKey = computed(() =>
     JSON.stringify(
       Object.entries(copilotkit.value.headers ?? {}).sort(([left], [right]) =>
@@ -90,6 +138,7 @@ export function useThreads(input: UseThreadsInput): UseThreadsResult {
   const storeError = ref<Error | null>(null);
   const hasMoreThreads = ref(false);
   const isFetchingMoreThreads = ref(false);
+  const isMutating = ref(false);
 
   bindThreadStoreSelector(store, ɵselectThreads, threads as Ref<Thread[]>);
   bindThreadStoreSelector(store, ɵselectThreadsIsLoading, storeIsLoading);
@@ -100,12 +149,33 @@ export function useThreads(input: UseThreadsInput): UseThreadsResult {
     ɵselectIsFetchingNextPage,
     isFetchingMoreThreads,
   );
+  bindThreadStoreSelector(store, ɵselectIsMutating, isMutating);
 
   store.start();
   onScopeDispose(() => {
     store.stop();
   });
 
+  // Register this store in core's single-slot thread-store registry so other
+  // surfaces (e.g. the chat view) can resolve the same store for the agent.
+  //
+  // Gated on `resolvedEnabled`: a disabled (e.g. unlicensed) drawer must not
+  // claim the agentId slot. The registry is single-slot/last-writer-wins, so
+  // registering an inert store would evict — and on unmount tear down — a
+  // co-mounted live store for the same agent. Staying unregistered while
+  // disabled leaves the live store's registration intact.
+  watch(
+    [resolvedEnabled, resolvedAgentId],
+    ([enabled, agentId], _prev, onCleanup) => {
+      if (!enabled) return;
+      copilotkit.value.registerThreadStore(agentId, store);
+      onCleanup(() => {
+        copilotkit.value.unregisterThreadStore(agentId);
+      });
+    },
+    { immediate: true },
+  );
+
   // Tracks whether we've dispatched the first real context to the store.
   // The store itself starts with `isLoading: false`, so before we dispatch
   // consumers would otherwise see an empty, non-loading state (empty-list
@@ -135,10 +205,23 @@ export function useThreads(input: UseThreadsInput): UseThreadsResult {
       resolvedAgentId,
       resolvedIncludeArchived,
       resolvedLimit,
+      resolvedEnabled,
+      threadListEndpointSupported,
     ],
-    ([runtimeUrl, runtimeStatus, , wsUrl, agentId, includeArchived, limit]) => {
-      if (!runtimeUrl) {
+    ([
+      runtimeUrl,
+      runtimeStatus,
+      ,
+      wsUrl,
+      agentId,
+      includeArchived,
+      limit,
+      enabled,
+      listEndpointSupported,
+    ]) => {
+      if (!runtimeUrl || !enabled) {
         store.setContext(null);
+        hasDispatchedContext.value = false;
         return;
       }
 
@@ -146,6 +229,15 @@ export function useThreads(input: UseThreadsInput): UseThreadsResult {
         return;
       }
 
+      // Connected, but the runtime explicitly does not serve the list
+      // endpoint: stay inert so no `/threads` fetch fires. The
+      // `threadEndpointsError` surfaces via `error` instead.
+      if (!listEndpointSupported) {
+        store.setContext(null);
+        hasDispatchedContext.value = false;
+        return;
+      }
+
       const context: ɵThreadRuntimeContext = {
         runtimeUrl,
         headers: { ...copilotkit.value.headers },
@@ -168,19 +260,44 @@ export function useThreads(input: UseThreadsInput): UseThreadsResult {
   );
 
   const preConnectLoading = computed(
-    () => !!copilotkit.value.runtimeUrl && !hasDispatchedContext.value,
+    () =>
+      !!copilotkit.value.runtimeUrl &&
+      resolvedEnabled.value &&
+      !threadEndpointsUnavailable.value &&
+      !hasDispatchedContext.value,
   );
 
   const isLoading = computed(() =>
-    runtimeError.value
+    runtimeError.value || threadEndpointsError.value
       ? false
       : preConnectLoading.value || storeIsLoading.value,
   );
 
+  // Folds developer/config errors (missing runtime URL, runtime without
+  // thread endpoints) together with genuine store errors. `listError` below
+  // deliberately excludes the config errors.
   const error = computed<Error | null>(
-    () => runtimeError.value ?? storeError.value,
+    () => runtimeError.value ?? threadEndpointsError.value ?? storeError.value,
   );
 
+  // Genuine store errors only. Unlike `error`, this omits the dev/config
+  // `runtimeError`/`threadEndpointsError` strings so they are never shown in
+  // user-facing error UI.
+  const listError = computed<Error | null>(() => storeError.value);
+
+  // Reject mutations locally (before touching the network) when the runtime
+  // reports mutations are unsupported, matching React's `guardMutation`.
+  function guardMutation<TArgs extends unknown[]>(
+    mutation: (...args: TArgs) => Promise<void>,
+  ): (...args: TArgs) => Promise<void> {
+    return (...args: TArgs) => {
+      if (threadMutationsError.value) {
+        return Promise.reject(threadMutationsError.value);
+      }
+      return mutation(...args);
+    };
+  }
+
   return {
     threads: computed(() =>
       threads.value.map(
@@ -197,12 +314,24 @@ export function useThreads(input: UseThreadsInput): UseThreadsResult {
     ),
     isLoading,
     error,
+    listError,
     hasMoreThreads,
     isFetchingMoreThreads,
+    isMutating,
     fetchMoreThreads: () => store.fetchNextPage(),
-    renameThread: (threadId: string, name: string) =>
+    refetchThreads: () => store.refetchThreads(),
+    startNewThread: () => store.startNewThread(),
+    renameThread: guardMutation((threadId: string, name: string) =>
       store.renameThread(threadId, name),
-    archiveThread: (threadId: string) => store.archiveThread(threadId),
-    deleteThread: (threadId: string) => store.deleteThread(threadId),
+    ),
+    archiveThread: guardMutation((threadId: string) =>
+      store.archiveThread(threadId),
+    ),
+    unarchiveThread: guardMutation((threadId: string) =>
+      store.unarchiveThread(threadId),
+    ),
+    deleteThread: guardMutation((threadId: string) =>
+      store.deleteThread(threadId),
+    ),
   };
 }

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

@@ -0,0 +1,48 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { isMobileViewport } from "../is-mobile-viewport";
+
+describe("isMobileViewport", () => {
+  const originalMatchMedia = window.matchMedia;
+
+  afterEach(() => {
+    window.matchMedia = originalMatchMedia;
+    vi.restoreAllMocks();
+  });
+
+  it("returns false when window.matchMedia is undefined", () => {
+    // @ts-expect-error - simulating an environment without matchMedia support.
+    delete window.matchMedia;
+
+    expect(isMobileViewport()).toBe(false);
+  });
+
+  it("returns true when the mobile media query matches", () => {
+    window.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(),
+    } as unknown as MediaQueryList);
+
+    expect(isMobileViewport()).toBe(true);
+  });
+
+  it("returns false when the mobile media query does not match", () => {
+    window.matchMedia = vi.fn().mockReturnValue({
+      matches: false,
+      media: "(max-width: 767px)",
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    } as unknown as MediaQueryList);
+
+    expect(isMobileViewport()).toBe(false);
+  });
+});

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;
 }