@agent-native/toolkit 0.10.0 → 0.10.2

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,59 @@ 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(
+      [
+        { "--agent-realtime-voice-angle": "0deg" },
+        { "--agent-realtime-voice-angle": "360deg" },
+      ] as Keyframe[],
+      {
+        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 +981,21 @@ 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",
+                  )}
+                >
+                  <span className="agent-realtime-voice-edge-light" />
+                </span>
+              ) : 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");
+  });
 });

package/src/conformance/runner.tsx

@@ -122,6 +122,87 @@ function elementWithText(document: Document, selector: string, text: string) {
   );
 }
 
+function assertInlineLayout(
+  container: Element,
+  iconSelector: string,
+  labelSelector: string,
+  message: string,
+) {
+  const icon = container.querySelector<HTMLElement>(iconSelector);
+  const label = container.querySelector<HTMLElement>(labelSelector);
+  invariant(icon && label, message);
+
+  const iconRect = icon.getBoundingClientRect();
+  const labelRect = label.getBoundingClientRect();
+  const hasGeometry =
+    iconRect.width > 0 ||
+    iconRect.height > 0 ||
+    labelRect.width > 0 ||
+    labelRect.height > 0;
+  if (hasGeometry) {
+    const verticalOverlap =
+      Math.min(iconRect.bottom, labelRect.bottom) -
+      Math.max(iconRect.top, labelRect.top);
+    invariant(
+      verticalOverlap > 0 || Math.abs(iconRect.top - labelRect.top) <= 2,
+      message,
+    );
+    return;
+  }
+
+  // happy-dom does not calculate layout. Still reject adapters that explicitly
+  // stack the tab contents, while browser-backed runs use the geometry check.
+  const commonAncestor = (() => {
+    let candidate: Element | null = icon;
+    while (candidate && !candidate.contains(label)) {
+      candidate = candidate.parentElement;
+    }
+    return candidate;
+  })();
+  const styles = [
+    container,
+    commonAncestor,
+    icon.parentElement,
+    label.parentElement,
+  ]
+    .filter((element): element is Element => Boolean(element))
+    .map((element) =>
+      element.ownerDocument.defaultView?.getComputedStyle(element),
+    );
+  invariant(
+    !styles.some(
+      (style) => style?.display === "flex" && style.flexDirection === "column",
+    ),
+    message,
+  );
+}
+
+function assertContainedFooter(dialog: Element, footerSelector: string) {
+  const footer = dialog.querySelector<HTMLElement>(footerSelector);
+  invariant(
+    footer,
+    "Dialog footer controls must be rendered inside the dialog surface.",
+  );
+
+  const dialogRect = (dialog as HTMLElement).getBoundingClientRect();
+  const footerRect = footer.getBoundingClientRect();
+  const hasGeometry =
+    dialogRect.width > 0 ||
+    dialogRect.height > 0 ||
+    footerRect.width > 0 ||
+    footerRect.height > 0;
+  if (!hasGeometry) return;
+
+  const epsilon = 2;
+  invariant(
+    footerRect.top >= dialogRect.top - epsilon &&
+      footerRect.bottom <= dialogRect.bottom + epsilon &&
+      footerRect.left >= dialogRect.left - epsilon &&
+      footerRect.right <= dialogRect.right + epsilon,
+    "Dialog footer controls must remain within the dialog surface bounds.",
+  );
+}
+
 const checks: readonly ConformanceCheck[] = [
   {
     id: "contract.components",
@@ -308,6 +389,21 @@ const checks: readonly ConformanceCheck[] = [
         "Tooltip must honor controlled open and portalContainer.",
       );
       unmount(probe);
+
+      const defaultOpenProbe = mount(
+        <components.Tooltip
+          trigger={<button>Help by default</button>}
+          content="Default tooltip"
+          defaultOpen
+          portalContainer={portal}
+        />,
+      );
+      await settle();
+      invariant(
+        portal.textContent?.includes("Default tooltip"),
+        "Tooltip must honor defaultOpen and portalContainer.",
+      );
+      unmount(defaultOpenProbe);
       portal.remove();
     },
   },
@@ -331,6 +427,21 @@ const checks: readonly ConformanceCheck[] = [
       click(item, document);
       invariant(selected === "archive", "Menu must report selected item ids.");
       unmount(probe);
+
+      const defaultOpenProbe = mount(
+        <components.Menu
+          trigger={<button>Default actions</button>}
+          items={[{ id: "restore", label: "Restore" }]}
+          defaultOpen
+          onAction={() => {}}
+        />,
+      );
+      await settle();
+      invariant(
+        elementWithText(document, '[role="menuitem"]', "Restore"),
+        "Menu must honor defaultOpen.",
+      );
+      unmount(defaultOpenProbe);
     },
   },
   {
@@ -393,6 +504,30 @@ const checks: readonly ConformanceCheck[] = [
         "Dialog must not invent actions when footer is omitted.",
       );
       unmount(probe);
+
+      const footerProbe = mount(
+        <components.Dialog
+          open
+          onOpenChange={() => {}}
+          title="Footer probe"
+          portalContainer={portal}
+          footer={
+            <button data-conformance-dialog-footer-action="true" type="button">
+              Save
+            </button>
+          }
+        >
+          Footer content
+        </components.Dialog>,
+      );
+      await settle();
+      const footerDialog = portal.querySelector('[role="dialog"]');
+      invariant(footerDialog, "Dialog footer probe did not render a dialog.");
+      assertContainedFooter(
+        footerDialog,
+        '[data-conformance-dialog-footer-action="true"]',
+      );
+      unmount(footerProbe);
       portal.remove();
     },
   },
@@ -466,7 +601,16 @@ const checks: readonly ConformanceCheck[] = [
           orientation="vertical"
           onChange={(next) => (value = next)}
           items={[
-            { value: "first", label: "First", content: "One" },
+            {
+              value: "first",
+              label: <span data-conformance-tab-label="true">First</span>,
+              icon: (
+                <span data-conformance-tab-icon="true" aria-hidden="true">
+                  ●
+                </span>
+              ),
+              content: "One",
+            },
             { value: "second", label: "Second", content: "Two" },
           ]}
         />,
@@ -477,6 +621,14 @@ const checks: readonly ConformanceCheck[] = [
         tabList.getAttribute("aria-orientation") === "vertical",
         "Tabs must honor vertical orientation in their tablist semantics.",
       );
+      const first = elementWithText(document, '[role="tab"]', "First");
+      invariant(first, "Tabs must expose the icon-bearing tab.");
+      assertInlineLayout(
+        first,
+        '[data-conformance-tab-icon="true"]',
+        '[data-conformance-tab-label="true"]',
+        "Tabs must lay out an icon and its label on the same row.",
+      );
       const second = elementWithText(document, '[role="tab"]', "Second");
       invariant(second, "Tabs must expose tab semantics.");
       click(second, document);

package/src/editor/SharedRichEditor.tsx

@@ -14,7 +14,12 @@ import {
   type SharedEditorFeatures,
 } from "./extensions.js";
 import type { ImageUploadFn } from "./ImageExtension.js";
-import { SlashCommandMenu, type SlashCommandItem } from "./SlashCommandMenu.js";
+import {
+  DEFAULT_SLASH_COMMANDS,
+  filterSlashCommandItems,
+  SlashCommandMenu,
+  type SlashCommandItem,
+} from "./SlashCommandMenu.js";
 import {
   useCollabReconcile,
   getEditorMarkdown,
@@ -200,6 +205,12 @@ export function SharedRichEditor({
 
   const collab = !!ydoc;
 
+  const effectiveSlashItems = useMemo(
+    () =>
+      filterSlashCommandItems(slashItems ?? DEFAULT_SLASH_COMMANDS, features),
+    [features, slashItems],
+  );
+
   // The collab hook needs the editor, but useEditor's `onUpdate` needs the
   // hook's guards. Break the cycle with a ref: `onUpdate` reads the guards
   // through `guardsRef`, which is populated right after the hook runs below.
@@ -313,7 +324,7 @@ export function SharedRichEditor({
         <BubbleToolbar editor={editor} buildItems={buildBubbleItems} />
       ) : null}
       {editable ? (
-        <SlashCommandMenu editor={editor} items={slashItems} />
+        <SlashCommandMenu editor={editor} items={effectiveSlashItems} />
       ) : null}
       <EditorContent editor={editor} />
     </div>

package/src/editor/SlashCommandMenu.spec.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  DEFAULT_SLASH_COMMANDS,
+  filterSlashCommandItems,
+} from "./SlashCommandMenu.js";
+
+describe("filterSlashCommandItems", () => {
+  it("hides commands whose editor extensions are disabled", () => {
+    const commands = filterSlashCommandItems(DEFAULT_SLASH_COMMANDS, {
+      codeBlock: false,
+      tables: false,
+      tasks: false,
+    });
+
+    expect(commands.map((command) => command.title)).not.toEqual(
+      expect.arrayContaining(["Code block", "Table", "To-do list"]),
+    );
+  });
+
+  it("keeps commands enabled when their feature is unspecified", () => {
+    const commands = filterSlashCommandItems(DEFAULT_SLASH_COMMANDS, {
+      tasks: false,
+    });
+
+    expect(commands.map((command) => command.title)).toEqual(
+      expect.arrayContaining(["Code block", "Table"]),
+    );
+    expect(commands.map((command) => command.title)).not.toContain(
+      "To-do list",
+    );
+  });
+});