@agent-native/toolkit 0.10.0 → 0.10.1

package/src/composer/RealtimeVoiceMode.spec.tsx

@@ -89,9 +89,28 @@ const copy: RealtimeVoiceModeCopy = {
 describe("RealtimeVoiceMode", () => {
   let container: HTMLDivElement;
   let root: Root;
+  let animate: ReturnType<typeof vi.fn>;
+  let cancelGlowAnimation: ReturnType<typeof vi.fn>;
+  let updateGlowPlaybackRate: ReturnType<typeof vi.fn>;
+  let originalAnimate: typeof HTMLElement.prototype.animate | undefined;
 
   beforeEach(() => {
     vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    originalAnimate = HTMLElement.prototype.animate;
+    cancelGlowAnimation = vi.fn();
+    updateGlowPlaybackRate = vi.fn();
+    animate = vi.fn(
+      () =>
+        ({
+          cancel: cancelGlowAnimation,
+          playbackRate: 1,
+          updatePlaybackRate: updateGlowPlaybackRate,
+        }) as unknown as Animation,
+    );
+    Object.defineProperty(HTMLElement.prototype, "animate", {
+      configurable: true,
+      value: animate,
+    });
     container = document.createElement("div");
     document.body.appendChild(container);
     root = createRoot(container);
@@ -100,6 +119,14 @@ describe("RealtimeVoiceMode", () => {
   afterEach(() => {
     act(() => root.unmount());
     container.remove();
+    if (originalAnimate) {
+      Object.defineProperty(HTMLElement.prototype, "animate", {
+        configurable: true,
+        value: originalAnimate,
+      });
+    } else {
+      Reflect.deleteProperty(HTMLElement.prototype, "animate");
+    }
     vi.unstubAllGlobals();
   });
 
@@ -291,22 +318,21 @@ describe("RealtimeVoiceMode", () => {
     expect(document.body.textContent).toContain("Set up voice mode");
     const prompt = document.querySelector<HTMLElement>('[role="dialog"]');
     expect(prompt?.className).toContain(
-      "w-[min(calc(100vw-2rem),var(--radix-popover-content-available-width,30rem),30rem)]",
+      "w-[min(calc(100vw-2rem),var(--radix-popover-content-available-width,24rem),24rem)]",
     );
     expect(prompt?.dataset.collisionBoundary).toBe("agent-panel");
     const actions = Array.from(prompt?.querySelectorAll("div") ?? []).find(
-      (element) => element.className.includes("sm:flex-row"),
+      (element) => element.className.includes("bg-muted/30"),
     );
     const actionClasses = actions?.className.split(/\s+/) ?? [];
-    expect(actionClasses).toContain("sm:flex-wrap");
-    expect(actionClasses).not.toContain("sm:flex-nowrap");
+    expect(actionClasses).toContain("grid");
+    expect(actionClasses).toContain("rounded-lg");
     const buttons = Array.from(
       document.querySelectorAll<HTMLButtonElement>("button"),
     );
     expect(
-      buttons.find((button) => button.textContent === "Connect Builder.io")
-        ?.className,
-    ).toContain("whitespace-nowrap");
+      buttons.find((button) => button.textContent === "Connect Builder.io"),
+    ).toBeDefined();
     act(() =>
       buttons
         .find((button) => button.textContent === "Connect Builder.io")
@@ -766,7 +792,28 @@ describe("RealtimeVoiceMode", () => {
     },
   );
 
-  it("shines only while the agent is working", () => {
+  it.each(["listening", "speaking"] as const)(
+    "keeps a soft session glow while %s",
+    (state) => {
+      render(
+        <RealtimeVoiceModeDock
+          state={state}
+          copy={copy}
+          chatVisible={false}
+          onToggleChat={vi.fn()}
+          onEndVoiceMode={vi.fn()}
+        />,
+      );
+      expect(
+        document.querySelector(".agent-realtime-voice-glow"),
+      ).not.toBeNull();
+      expect(
+        document.querySelector(".agent-realtime-voice-working"),
+      ).toBeNull();
+    },
+  );
+
+  it("brightens the live glow while working", () => {
     render(
       <RealtimeVoiceModeDock
         state="working"
@@ -776,10 +823,14 @@ describe("RealtimeVoiceMode", () => {
         onEndVoiceMode={vi.fn()}
       />,
     );
+    expect(document.querySelector(".agent-realtime-voice-glow")).not.toBeNull();
     expect(
       document.querySelector(".agent-realtime-voice-working"),
     ).not.toBeNull();
+  });
 
+  it("changes glow speed without restarting or jumping its rotation", () => {
+    vi.useFakeTimers();
     render(
       <RealtimeVoiceModeDock
         state="listening"
@@ -789,9 +840,66 @@ describe("RealtimeVoiceMode", () => {
         onEndVoiceMode={vi.fn()}
       />,
     );
-    expect(document.querySelector(".agent-realtime-voice-working")).toBeNull();
+    const glow = document.querySelector('[data-realtime-voice-glow="true"]');
+
+    expect(animate).toHaveBeenCalledTimes(1);
+    expect(updateGlowPlaybackRate).toHaveBeenLastCalledWith(1);
+
+    render(
+      <RealtimeVoiceModeDock
+        state="working"
+        copy={copy}
+        chatVisible={false}
+        onToggleChat={vi.fn()}
+        onEndVoiceMode={vi.fn()}
+      />,
+    );
+
+    expect(document.querySelector('[data-realtime-voice-glow="true"]')).toBe(
+      glow,
+    );
+    expect(animate).toHaveBeenCalledTimes(1);
+    expect(cancelGlowAnimation).not.toHaveBeenCalled();
+    expect(updateGlowPlaybackRate).toHaveBeenLastCalledWith(2.4);
+
+    render(
+      <RealtimeVoiceModeDock
+        state="speaking"
+        copy={copy}
+        chatVisible={false}
+        onToggleChat={vi.fn()}
+        onEndVoiceMode={vi.fn()}
+      />,
+    );
+
+    expect(animate).toHaveBeenCalledTimes(1);
+    expect(cancelGlowAnimation).not.toHaveBeenCalled();
+    expect(updateGlowPlaybackRate).toHaveBeenLastCalledWith(2.4);
+
+    act(() => vi.advanceTimersByTime(800));
+    expect(updateGlowPlaybackRate).toHaveBeenLastCalledWith(1);
+    vi.useRealTimers();
   });
 
+  it.each(["connecting", "error", "ending"] as const)(
+    "does not show the live glow while %s",
+    (state) => {
+      render(
+        <RealtimeVoiceModeDock
+          state={state}
+          copy={copy}
+          chatVisible={false}
+          onToggleChat={vi.fn()}
+          onEndVoiceMode={vi.fn()}
+        />,
+      );
+      expect(document.querySelector(".agent-realtime-voice-glow")).toBeNull();
+      expect(
+        document.querySelector(".agent-realtime-voice-working"),
+      ).toBeNull();
+    },
+  );
+
   it("shows an unmistakable loader and ignores early audio until connected", () => {
     const audioLevels = createRealtimeVoiceAudioLevelStore();
     audioLevels.set({ input: 0.8, output: 0 });

package/src/composer/RealtimeVoiceMode.tsx

@@ -10,10 +10,12 @@ import {
 import {
   IconAlertTriangle,
   IconBrain,
+  IconKey,
   IconLanguage,
   IconLoader2,
   IconMicrophone,
   IconPhoneOff,
+  IconPlugConnected,
   IconSettings,
   IconVolume,
 } from "@tabler/icons-react";
@@ -225,72 +227,90 @@ export function RealtimeVoiceModeEntry({
         collisionPadding={16}
         data-collision-boundary={collisionBoundary ? "agent-panel" : "viewport"}
         className={cn(
-          setupRequired ? "p-4" : "p-3",
+          setupRequired ? "p-3.5" : "p-3",
           setupRequired
-            ? "w-[min(calc(100vw-2rem),var(--radix-popover-content-available-width,30rem),30rem)]"
+            ? "w-[min(calc(100vw-2rem),var(--radix-popover-content-available-width,24rem),24rem)]"
             : "w-[min(calc(100vw-2rem),var(--radix-popover-content-available-width,18rem),18rem)]",
         )}
         aria-labelledby={titleId}
         aria-describedby={setupRequired ? descriptionId : undefined}
       >
-        <div className={cn("grid", setupRequired ? "gap-3" : "gap-2.5")}>
-          <div className="grid gap-1">
-            <h2 id={titleId} className="text-sm font-semibold text-foreground">
-              {setupRequired ? copy.setupTitle : copy.promptTitle}
-            </h2>
+        <div className={cn("grid", setupRequired ? "gap-3.5" : "gap-2.5")}>
+          <div
+            className={cn(
+              setupRequired ? "flex items-start gap-3" : "grid gap-1",
+            )}
+          >
             {setupRequired ? (
-              <p
-                id={descriptionId}
-                className="text-sm leading-relaxed text-muted-foreground"
-              >
-                {copy.setupDescription}
-              </p>
+              <div className="flex size-9 shrink-0 items-center justify-center rounded-lg bg-primary/10 text-primary">
+                <IconMicrophone aria-hidden="true" />
+              </div>
             ) : null}
+            <div className="grid gap-1">
+              <h2
+                id={titleId}
+                className="text-sm font-semibold leading-5 text-foreground"
+              >
+                {setupRequired ? copy.setupTitle : copy.promptTitle}
+              </h2>
+              {setupRequired ? (
+                <p
+                  id={descriptionId}
+                  className="text-xs leading-5 text-muted-foreground"
+                >
+                  {copy.setupDescription}
+                </p>
+              ) : null}
+            </div>
           </div>
 
           <div
             className={cn(
-              "gap-2",
-              setupRequired
-                ? "flex flex-col-reverse sm:flex-row sm:flex-wrap sm:justify-end"
-                : "grid",
+              "grid gap-2",
+              setupRequired ? "rounded-lg bg-muted/30 p-1" : null,
             )}
           >
             {setupRequired ? (
               <>
                 <Button
                   type="button"
-                  variant="ghost"
                   size="sm"
-                  onClick={() => choose("dictation", onKeepDictating)}
+                  className="w-full justify-start px-3"
+                  disabled={connectingBuilder}
+                  onClick={() =>
+                    choose("realtime", onConnectBuilder ?? onStartVoiceMode)
+                  }
                 >
-                  {copy.keepDictating}
+                  {connectingBuilder ? (
+                    <IconLoader2 className="animate-spin" />
+                  ) : (
+                    <IconPlugConnected aria-hidden="true" />
+                  )}
+                  {copy.connectBuilder}
                 </Button>
                 <Button
                   type="button"
                   variant="outline"
                   size="sm"
+                  className="w-full justify-start bg-background px-3"
                   onClick={() =>
                     choose("realtime", onUseOpenAiKey ?? onStartVoiceMode)
                   }
                 >
+                  <IconKey aria-hidden="true" />
                   {openAiConfigured
                     ? copy.startWithOpenAiKey
                     : copy.useOpenAiKey}
                 </Button>
                 <Button
                   type="button"
+                  variant="ghost"
                   size="sm"
-                  className="whitespace-nowrap"
-                  disabled={connectingBuilder}
-                  onClick={() =>
-                    choose("realtime", onConnectBuilder ?? onStartVoiceMode)
-                  }
+                  className="w-full justify-start px-3 text-muted-foreground"
+                  onClick={() => choose("dictation", onKeepDictating)}
                 >
-                  {connectingBuilder ? (
-                    <IconLoader2 className="animate-spin" />
-                  ) : null}
-                  {copy.connectBuilder}
+                  <IconMicrophone aria-hidden="true" />
+                  {copy.keepDictating}
                 </Button>
               </>
             ) : (
@@ -382,9 +402,14 @@ export interface RealtimeVoiceModeInlineSettings {
 const SILENT_AUDIO_LEVELS = createRealtimeVoiceAudioLevelStore();
 const WAVEFORM_WEIGHTS = [0.55, 0.82, 1, 0.82, 0.55];
 const AUDIO_ACTIVITY_THRESHOLD = 0.1;
+const WORKING_GLOW_HOLD_MS = 800;
 
 function usePrefersReducedMotion(): boolean {
-  const [reduced, setReduced] = useState(false);
+  const [reduced, setReduced] = useState(
+    () =>
+      typeof window !== "undefined" &&
+      Boolean(window.matchMedia?.("(prefers-reduced-motion: reduce)").matches),
+  );
   useEffect(() => {
     if (typeof window === "undefined" || !window.matchMedia) return;
     const query = window.matchMedia("(prefers-reduced-motion: reduce)");
@@ -697,6 +722,9 @@ export function RealtimeVoiceModeDock({
   const controlsId = useId();
   const [controlsOpen, setControlsOpen] = useState(false);
   const [settingsOpen, setSettingsOpen] = useState(false);
+  const [workingGlowHeld, setWorkingGlowHeld] = useState(state === "working");
+  const glowRef = useRef<HTMLSpanElement>(null);
+  const glowAnimationRef = useRef<Animation | null>(null);
   const selectInteractionRef = useRef(false);
   const selectInteractionFrameRef = useRef<number | null>(null);
   const levels = useSyncExternalStore(
@@ -724,6 +752,56 @@ export function RealtimeVoiceModeDock({
   const errorDetailVisible = state === "error" && Boolean(errorMessage);
   const controlsVisible = controlsOpen || settingsOpen;
   const chatPanelTranslation = useChatPanelTranslation(chatVisible);
+  const workingGlowActive = state === "working" || workingGlowHeld;
+
+  useEffect(() => {
+    if (state === "working") {
+      setWorkingGlowHeld(true);
+      return;
+    }
+    if (!workingGlowHeld) return;
+    const timer = window.setTimeout(
+      () => setWorkingGlowHeld(false),
+      WORKING_GLOW_HOLD_MS,
+    );
+    return () => window.clearTimeout(timer);
+  }, [state, workingGlowHeld]);
+
+  useEffect(() => {
+    if (!connected || reducedMotion || !glowRef.current) {
+      glowAnimationRef.current?.cancel();
+      glowAnimationRef.current = null;
+      return;
+    }
+
+    const animation = glowRef.current.animate(
+      [{ transform: "rotate(0turn)" }, { transform: "rotate(1turn)" }],
+      {
+        duration: 12_000,
+        easing: "linear",
+        iterations: Number.POSITIVE_INFINITY,
+      },
+    );
+    glowAnimationRef.current = animation;
+
+    return () => {
+      animation.cancel();
+      if (glowAnimationRef.current === animation) {
+        glowAnimationRef.current = null;
+      }
+    };
+  }, [connected, reducedMotion]);
+
+  useEffect(() => {
+    const animation = glowAnimationRef.current;
+    if (!animation) return;
+    const playbackRate = workingGlowActive ? 2.4 : 1;
+    if (typeof animation.updatePlaybackRate === "function") {
+      animation.updatePlaybackRate(playbackRate);
+    } else {
+      animation.playbackRate = playbackRate;
+    }
+  }, [workingGlowActive]);
 
   const handleSelectOpenChange = useCallback((open: boolean) => {
     if (selectInteractionFrameRef.current !== null) {
@@ -900,9 +978,19 @@ export function RealtimeVoiceModeDock({
               className={cn(
                 "relative isolate size-16 overflow-visible rounded-full ring-1 backdrop-blur-xl transition-transform duration-150 ease-out focus-visible:ring-offset-2 active:scale-[0.97] motion-reduce:transition-none",
                 ORB_STATE_CLASSES[state],
-                state === "working" && "agent-realtime-voice-working",
               )}
             >
+              {connected ? (
+                <span
+                  ref={glowRef}
+                  aria-hidden="true"
+                  data-realtime-voice-glow="true"
+                  className={cn(
+                    "agent-realtime-voice-glow",
+                    workingGlowActive && "agent-realtime-voice-working",
+                  )}
+                />
+              ) : null}
               <span className="relative z-10 flex items-center justify-center">
                 {state === "connecting" ? (
                   <VoiceConnectingIndicator />

package/src/composer/useRealtimeVoiceMode.spec.ts

@@ -522,7 +522,7 @@ describe("Realtime voice dynamic tool manifests", () => {
 });
 
 describe("extractRealtimeVoiceFunctionCalls", () => {
-  it("waits for the terminal response event before returning a function call", () => {
+  it("returns a function call as soon as its final arguments arrive", () => {
     expect(
       extractRealtimeVoiceFunctionCalls({
         type: "response.function_call_arguments.done",
@@ -530,7 +530,13 @@ describe("extractRealtimeVoiceFunctionCalls", () => {
         call_id: "call-1",
         arguments: '{"path":"/inbox"}',
       }),
-    ).toEqual([]);
+    ).toEqual([
+      {
+        name: "navigate",
+        callId: "call-1",
+        argumentsText: '{"path":"/inbox"}',
+      },
+    ]);
   });
 
   it("falls back to completed function items on response.done", () => {
@@ -559,6 +565,26 @@ describe("extractRealtimeVoiceFunctionCalls", () => {
     ]);
   });
 
+  it("accepts a completed function output item as a provider fallback", () => {
+    expect(
+      extractRealtimeVoiceFunctionCalls({
+        type: "response.output_item.done",
+        item: {
+          type: "function_call",
+          name: "navigate",
+          call_id: "call-output-item",
+          arguments: '{"path":"/todos"}',
+        },
+      }),
+    ).toEqual([
+      {
+        name: "navigate",
+        callId: "call-output-item",
+        argumentsText: '{"path":"/todos"}',
+      },
+    ]);
+  });
+
   it("ignores function items from failed or cancelled responses", () => {
     const output = [
       {

package/src/composer/useRealtimeVoiceMode.tsx

@@ -1005,6 +1005,36 @@ export function createRealtimeVoiceToolManifestCoordinator(
 export function extractRealtimeVoiceFunctionCalls(
   event: RealtimeServerEvent,
 ): Array<{ name: string; callId: string; argumentsText: string }> {
+  if (event.type === "response.function_call_arguments.done") {
+    const name = typeof event.name === "string" ? event.name : "";
+    const callId = typeof event.call_id === "string" ? event.call_id : "";
+    if (!name || !callId) return [];
+    return [
+      {
+        name,
+        callId,
+        argumentsText:
+          typeof event.arguments === "string" ? event.arguments : "{}",
+      },
+    ];
+  }
+  if (event.type === "response.output_item.done") {
+    const item = event.item;
+    if (!item || typeof item !== "object") return [];
+    const record = item as Record<string, unknown>;
+    if (record.type !== "function_call") return [];
+    const name = typeof record.name === "string" ? record.name : "";
+    const callId = typeof record.call_id === "string" ? record.call_id : "";
+    if (!name || !callId) return [];
+    return [
+      {
+        name,
+        callId,
+        argumentsText:
+          typeof record.arguments === "string" ? record.arguments : "{}",
+      },
+    ];
+  }
   if (event.type !== "response.done") return [];
   const response = event.response;
   if (!response || typeof response !== "object") return [];

package/src/conformance/conformance.spec.tsx

@@ -3,7 +3,10 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { defaultDesignSystemComponents } from "../design-system/default-adapter.js";
-import { DESIGN_SYSTEM_CONTRACT_VERSION } from "../design-system/types.js";
+import {
+  DESIGN_SYSTEM_CONTRACT_VERSION,
+  type DesignSystemComponents,
+} from "../design-system/types.js";
 import { cssInJsFixtureAdapter } from "./__fixtures__/css-in-js-adapter.js";
 import {
   assertDesignSystemConformance,
@@ -80,4 +83,61 @@ describe("design-system conformance kit", () => {
     });
     expect(report.results.filter((result) => !result.passed)).toEqual([]);
   });
+
+  it("rejects tabs that stack an icon above its label", async () => {
+    const stackedTabsAdapter: DesignSystemComponents = {
+      ...cssInJsFixtureAdapter,
+      Tabs: ({ items, value, onChange, orientation }) => (
+        <div>
+          <div role="tablist" aria-orientation={orientation}>
+            {items.map((item) => (
+              <button
+                key={String(item.value)}
+                role="tab"
+                aria-selected={item.value === value}
+                style={{ display: "flex", flexDirection: "column" }}
+                onClick={() => onChange(item.value)}
+              >
+                {item.icon}
+                {item.label}
+              </button>
+            ))}
+          </div>
+          {items.find((item) => item.value === value)?.content}
+        </div>
+      ),
+    };
+    const report = await runDesignSystemConformance({
+      adapterName: "stacked-tabs fixture",
+      components: stackedTabsAdapter,
+      contractVersion: DESIGN_SYSTEM_CONTRACT_VERSION,
+    });
+    const tabsResult = report.results.find(
+      (result) => result.id === "behavior.tabs",
+    );
+    expect(tabsResult?.passed).toBe(false);
+    expect(tabsResult?.message).toContain("same row");
+  });
+
+  it("rejects dialogs that render footer controls outside the dialog", async () => {
+    const detachedFooterAdapter: DesignSystemComponents = {
+      ...cssInJsFixtureAdapter,
+      Dialog: ({ footer, ...props }) => (
+        <>
+          <cssInJsFixtureAdapter.Dialog {...props} />
+          {footer}
+        </>
+      ),
+    };
+    const report = await runDesignSystemConformance({
+      adapterName: "detached-footer fixture",
+      components: detachedFooterAdapter,
+      contractVersion: DESIGN_SYSTEM_CONTRACT_VERSION,
+    });
+    const dialogResult = report.results.find(
+      (result) => result.id === "behavior.dialog",
+    );
+    expect(dialogResult?.passed).toBe(false);
+    expect(dialogResult?.message).toContain("footer");
+  });
 });