@copilotkit/vue 1.62.1 → 1.62.2

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

@@ -13,6 +13,7 @@ export { default as CopilotChatSuggestionView } from "./CopilotChatSuggestionVie
 export { default as CopilotChatToolCallsView } from "./CopilotChatToolCallsView.vue";
 export { default as CopilotChatUserMessage } from "./CopilotChatUserMessage.vue";
 export { default as CopilotChatView } from "./CopilotChatView.vue";
+export { default as CopilotThreadsDrawer } from "./CopilotThreadsDrawer.vue";
 import _CopilotChatToggleButton from "./CopilotChatToggleButton.vue";
 import CopilotChatToggleButtonCloseIcon from "./CopilotChatToggleButtonCloseIcon";
 import CopilotChatToggleButtonOpenIcon from "./CopilotChatToggleButtonOpenIcon";

package/src/v2/components/icons/index.ts

@@ -19,4 +19,5 @@ export {
   RefreshCw as IconRefreshCw,
   CheckCircle as IconCheckCircle,
   Circle as IconCircle,
+  PanelLeftOpen as IconPanelLeftOpen,
 } from "lucide-vue-next";

package/src/v2/hooks/__tests__/use-human-in-the-loop.e2e.test.ts

@@ -944,13 +944,13 @@ describe("HITL Thread Reconnection Bug", () => {
       expect(screen.getByTestId("hitl-action").textContent).toBe("delete");
     });
 
+    // Core-level coverage asserts that passive replay does not re-invoke local
+    // frontend handlers for replayed assistant tool calls.
     await waitFor(() => {
-      expect(screen.getByTestId("hitl-status").textContent).toBe(
-        ToolCallStatus.Executing,
+      expect(screen.getByTestId("hitl-status").textContent).toMatch(
+        /^(executing|inProgress)$/,
       );
     });
-
-    expect(screen.getByTestId("hitl-respond")).toBeDefined();
   });
 
   it("should handle tool call after connect (fresh run)", async () => {

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

@@ -22,6 +22,7 @@ type ThreadState = {
   error: Error | null;
   hasNextPage: boolean;
   isFetchingNextPage: boolean;
+  isMutating: boolean;
   context: {
     runtimeUrl: string;
     headers: Record<string, string>;
@@ -107,6 +108,7 @@ vi.mock("@copilotkit/core", () => {
       error: null,
       hasNextPage: false,
       isFetchingNextPage: false,
+      isMutating: false,
       context: null,
     };
     private listeners = new Set<() => void>();
@@ -121,6 +123,7 @@ vi.mock("@copilotkit/core", () => {
         error: null,
         hasNextPage: false,
         isFetchingNextPage: false,
+        isMutating: false,
         context: null,
       };
       if (this.socket) {
@@ -266,6 +269,27 @@ vi.mock("@copilotkit/core", () => {
       });
     }
 
+    async unarchiveThread(threadId: string): Promise<void> {
+      const context = this.requireContext();
+      await fetchMock(`${context.runtimeUrl}/threads/${threadId}/unarchive`, {
+        method: "POST",
+        headers: context.headers,
+        body: JSON.stringify({
+          agentId: context.agentId,
+        }),
+      });
+    }
+
+    refetchThreads(): void {
+      if (!this.state.context) return;
+      void this.fetchThreads(this.state.context);
+    }
+
+    startNewThread(): void {
+      // Test double: mirrors the real store's "reset to a fresh thread" no-op
+      // shape closely enough for surface-presence assertions.
+    }
+
     fetchNextPage(): void {
       this.state.isFetchingNextPage = true;
       this.notify();
@@ -319,6 +343,7 @@ vi.mock("@copilotkit/core", () => {
     ɵselectThreadsError: select((state) => state.error),
     ɵselectHasNextPage: select((state) => state.hasNextPage),
     ɵselectIsFetchingNextPage: select((state) => state.isFetchingNextPage),
+    ɵselectIsMutating: select((state) => state.isMutating),
   };
 });
 
@@ -336,22 +361,48 @@ function getDispatchedContexts(): Array<ThreadState["context"]> {
   return threadMocks.dispatchedContexts;
 }
 
+type ThreadEndpointRuntimeInfo = {
+  list: boolean;
+  inspect: boolean;
+  mutations: boolean;
+  realtimeMetadata: boolean;
+};
+
+const supportedThreadEndpoints: ThreadEndpointRuntimeInfo = {
+  list: true,
+  inspect: true,
+  mutations: true,
+  realtimeMetadata: true,
+};
+
+type MockCopilotKit = {
+  runtimeUrl: string | undefined;
+  runtimeConnectionStatus: CopilotKitCoreRuntimeConnectionStatus;
+  headers: Record<string, string>;
+  intelligence: { wsUrl?: string } | undefined;
+  threadEndpoints: ThreadEndpointRuntimeInfo | undefined;
+  registerThreadStore: ReturnType<typeof vi.fn>;
+  unregisterThreadStore: ReturnType<typeof vi.fn>;
+};
+
 function setupCopilotKit(
   runtimeUrl: string | undefined = "http://localhost:4000",
   runtimeConnectionStatus: CopilotKitCoreRuntimeConnectionStatus = CopilotKitCoreRuntimeConnectionStatus.Connected,
+  overrides: Partial<
+    Pick<MockCopilotKit, "threadEndpoints" | "intelligence">
+  > = {},
 ) {
-  const copilotkit = ref<{
-    runtimeUrl: string | undefined;
-    runtimeConnectionStatus: CopilotKitCoreRuntimeConnectionStatus;
-    headers: Record<string, string>;
-    intelligence: { wsUrl?: string } | undefined;
-  }>({
+  const copilotkit = ref<MockCopilotKit>({
     runtimeUrl,
     runtimeConnectionStatus,
     headers: { Authorization: "Bearer test-token" },
     intelligence: {
       wsUrl: "ws://localhost:4000/client",
     },
+    threadEndpoints: supportedThreadEndpoints,
+    registerThreadStore: vi.fn(),
+    unregisterThreadStore: vi.fn(),
+    ...overrides,
   });
   mockUseCopilotKit.mockReturnValue({ copilotkit });
   return copilotkit;
@@ -399,6 +450,7 @@ function mountHook(
     agentId: string | Ref<string>;
     includeArchived?: boolean | Ref<boolean | undefined>;
     limit?: number | Ref<number | undefined>;
+    enabled?: boolean | Ref<boolean | undefined>;
   } = defaultInput,
 ) {
   let result: UseThreadsResult | undefined;
@@ -1038,4 +1090,249 @@ describe("useThreads", () => {
       ]);
     });
   });
+
+  describe("useThreads augmented surface", () => {
+    it("exposes listError, isMutating, and the missing mutations/actions", async () => {
+      fetchMock
+        .mockReturnValueOnce(
+          jsonResponse({ threads: sampleThreads, joinCode: "jc-1" }),
+        )
+        .mockReturnValueOnce(jsonResponse({ joinToken: "jt-1" }));
+
+      const { getResult } = mountHook();
+
+      await vi.waitFor(() => {
+        expect(getResult().isLoading.value).toBe(false);
+      });
+
+      expect(getResult().listError).toBeDefined();
+      expect(getResult().listError.value).toBeNull();
+      expect(getResult().isMutating).toBeDefined();
+      expect(getResult().isMutating.value).toBe(false);
+      expect(typeof getResult().unarchiveThread).toBe("function");
+      expect(typeof getResult().refetchThreads).toBe("function");
+      expect(typeof getResult().startNewThread).toBe("function");
+    });
+
+    it("listError excludes the dev 'Runtime URL is not configured' error", async () => {
+      // No runtimeUrl -> `error` is the dev string, but `listError` stays null.
+      setupCopilotKit("");
+
+      const { getResult } = mountHook();
+
+      await nextTick();
+
+      expect(getResult().error.value).toBeInstanceOf(Error);
+      expect(getResult().error.value?.message).toBe(
+        "Runtime URL is not configured",
+      );
+      expect(getResult().listError.value).toBeNull();
+    });
+
+    it("unarchiveThread calls through to the store's unarchive contract", async () => {
+      fetchMock
+        .mockReturnValueOnce(
+          jsonResponse({ threads: sampleThreads, joinCode: "jc-1" }),
+        )
+        .mockReturnValueOnce(jsonResponse({ joinToken: "jt-1" }))
+        .mockReturnValueOnce(jsonResponse({}));
+
+      const { getResult } = mountHook();
+
+      await vi.waitFor(() => {
+        expect(getResult().isLoading.value).toBe(false);
+      });
+
+      await getResult().unarchiveThread("t-1");
+
+      const [url, options] = fetchMock.mock.calls[2];
+      expect(url).toContain("/threads/t-1/unarchive");
+      expect(options.method).toBe("POST");
+      expect(JSON.parse(options.body)).toMatchObject({
+        agentId: "agent-1",
+      });
+    });
+
+    it("does not dispatch a context (or fetch) when enabled is false", async () => {
+      const { getResult } = mountHook({ ...defaultInput, enabled: false });
+
+      await nextTick();
+
+      expect(fetchMock).not.toHaveBeenCalled();
+      expect(getResult().threads.value).toEqual([]);
+      const lastDispatched = getDispatchedContexts().at(-1);
+      expect(lastDispatched).toBeNull();
+      // A disabled consumer must not be stuck in a permanent loading state:
+      // preConnectLoading must factor in `enabled`, otherwise isLoading would
+      // stay true forever since hasDispatchedContext never gets set.
+      expect(getResult().isLoading.value).toBe(false);
+    });
+
+    it("re-arms the pre-connect loading indicator when enabled toggles false -> true", async () => {
+      const enabled = ref(false);
+
+      fetchMock
+        .mockReturnValueOnce(
+          jsonResponse({ threads: sampleThreads, joinCode: "jc-1" }),
+        )
+        .mockReturnValueOnce(jsonResponse({ joinToken: "jt-1" }));
+
+      const { getResult } = mountHook({ ...defaultInput, enabled });
+
+      await nextTick();
+
+      // Disabled: inert, not loading, no fetch.
+      expect(getResult().isLoading.value).toBe(false);
+      expect(fetchMock).not.toHaveBeenCalled();
+      expect(getDispatchedContexts().at(-1)).toBeNull();
+
+      // Re-enable: the pre-connect loading indicator must re-arm (i.e.
+      // hasDispatchedContext was reset to false on disable) so consumers see
+      // isLoading=true again rather than a stale empty-list flash while the
+      // new context dispatch/fetch is in flight.
+      enabled.value = true;
+      await nextTick();
+
+      expect(getResult().isLoading.value).toBe(true);
+
+      await vi.waitFor(() => {
+        expect(getResult().isLoading.value).toBe(false);
+      });
+
+      expect(fetchMock).toHaveBeenCalledWith(
+        expect.stringContaining("/threads?agentId=agent-1"),
+        expect.objectContaining({ method: "GET" }),
+      );
+      const nonNullContexts = getDispatchedContexts().filter(
+        (context) => context !== null,
+      );
+      expect(nonNullContexts).toHaveLength(1);
+    });
+  });
+
+  describe("thread store registration (core registry)", () => {
+    it("registers the thread store with core when enabled", async () => {
+      const copilotkit = setupCopilotKit();
+
+      fetchMock
+        .mockReturnValueOnce(
+          jsonResponse({ threads: sampleThreads, joinCode: "jc-1" }),
+        )
+        .mockReturnValueOnce(jsonResponse({ joinToken: "jt-1" }));
+
+      mountHook();
+
+      await vi.waitFor(() => {
+        expect(copilotkit.value.registerThreadStore).toHaveBeenCalledWith(
+          "agent-1",
+          expect.objectContaining({ select: expect.any(Function) }),
+        );
+      });
+    });
+
+    it("does not register the thread store when disabled (avoids evicting a live store for the same agent)", async () => {
+      const copilotkit = setupCopilotKit();
+
+      mountHook({ ...defaultInput, enabled: false });
+
+      await nextTick();
+
+      expect(copilotkit.value.registerThreadStore).not.toHaveBeenCalled();
+    });
+
+    it("unregisters the thread store with core on unmount", async () => {
+      const copilotkit = setupCopilotKit();
+
+      fetchMock
+        .mockReturnValueOnce(
+          jsonResponse({ threads: sampleThreads, joinCode: "jc-1" }),
+        )
+        .mockReturnValueOnce(jsonResponse({ joinToken: "jt-1" }));
+
+      const { wrapper } = mountHook();
+
+      await vi.waitFor(() => {
+        expect(copilotkit.value.registerThreadStore).toHaveBeenCalled();
+      });
+
+      wrapper.unmount();
+
+      expect(copilotkit.value.unregisterThreadStore).toHaveBeenCalledWith(
+        "agent-1",
+      );
+    });
+  });
+
+  describe("threadEndpoints gating", () => {
+    it("does not fetch when the runtime does not advertise the list endpoint and surfaces the endpoints-unavailable error", async () => {
+      setupCopilotKit(
+        "http://localhost:4000",
+        CopilotKitCoreRuntimeConnectionStatus.Connected,
+        {
+          threadEndpoints: {
+            list: false,
+            inspect: false,
+            mutations: false,
+            realtimeMetadata: false,
+          },
+          intelligence: undefined,
+        },
+      );
+
+      const { getResult } = mountHook();
+
+      await vi.waitFor(() => {
+        expect(getResult().isLoading.value).toBe(false);
+      });
+
+      expect(fetchMock).not.toHaveBeenCalled();
+      expect(getResult().threads.value).toEqual([]);
+      const lastDispatched = getDispatchedContexts().at(-1);
+      expect(lastDispatched).toBeNull();
+      expect(getResult().error.value?.message).toBe(
+        "Thread endpoints are not available on this CopilotKit runtime",
+      );
+      // The config error must NOT leak into the user-facing list error.
+      expect(getResult().listError.value).toBeNull();
+    });
+
+    it("rejects mutations locally when the runtime reports mutations are unsupported", async () => {
+      setupCopilotKit(
+        "http://localhost:4000",
+        CopilotKitCoreRuntimeConnectionStatus.Connected,
+        {
+          threadEndpoints: {
+            list: true,
+            inspect: true,
+            mutations: false,
+            realtimeMetadata: false,
+          },
+          intelligence: undefined,
+        },
+      );
+      fetchMock.mockReturnValueOnce(jsonResponse({ threads: sampleThreads }));
+
+      const { getResult } = mountHook();
+
+      await vi.waitFor(() => {
+        expect(getResult().isLoading.value).toBe(false);
+      });
+
+      fetchMock.mockClear();
+
+      await expect(getResult().renameThread("t-1", "Renamed")).rejects.toThrow(
+        "Thread mutations are not available on this CopilotKit runtime",
+      );
+      await expect(getResult().archiveThread("t-1")).rejects.toThrow(
+        "Thread mutations are not available on this CopilotKit runtime",
+      );
+      await expect(getResult().unarchiveThread("t-1")).rejects.toThrow(
+        "Thread mutations are not available on this CopilotKit runtime",
+      );
+      await expect(getResult().deleteThread("t-1")).rejects.toThrow(
+        "Thread mutations are not available on this CopilotKit runtime",
+      );
+      expect(fetchMock).not.toHaveBeenCalled();
+    });
+  });
 });

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