@agent-native/toolkit 0.228.0-nightly-20261111212500 → 0.228.0

package/src/app/shared/AppShellSkeleton.spec.tsx

@@ -5,9 +5,10 @@ import { act } from "react";
 import { createRoot } from "react-dom/client";
 import { renderToStaticMarkup } from "react-dom/server";
 import { MemoryRouter } from "react-router";
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
 
 import { consumeFirstPaintPromptDraft } from "../../app-shell/first-paint-prompt-draft.js";
+import { FIRST_RUN_PENDING_ATTRIBUTE } from "../onboarding/first-run-first-paint.js";
 import { AppShellSkeleton } from "./AppShellSkeleton.js";
 import type { AppShellFirstPaintHome } from "./AppShellSkeleton.js";
 
@@ -21,6 +22,64 @@ function render(layout: Parameters<typeof AppShellSkeleton>[0]["layout"]) {
   )!;
 }
 
+function firstPaintFixture(): AppShellFirstPaintHome {
+  return {
+    appId: "slides",
+    appName: "Slides",
+    pageTitle: "Decks",
+    promptTitle: "Let's create your first presentation",
+    promptPlaceholder: "Describe your presentation",
+    suggestedPromptsLabel: "Suggested prompts",
+    sidebarItems: [{ label: "Decks", to: "/home", icon: IconHome }],
+    templatesLabel: "Templates",
+    recentLabel: "Recent",
+    browseAllLabel: "Browse all",
+    skipPromptLabel: "Skip prompt",
+    promptDraftScope: "slides:new:viewer-a:org-a",
+    promptHandoffScope: "viewer-a:org-a",
+    suggestions: [],
+    renderComposer: (props) => <textarea aria-label={props.ariaLabel} />,
+  };
+}
+
+describe("AppShellSkeleton first-paint home before first run", () => {
+  afterEach(() => {
+    document.documentElement.removeAttribute(FIRST_RUN_PENDING_ATTRIBUTE);
+    document.body.innerHTML = "";
+  });
+
+  function paint() {
+    document.body.innerHTML = renderToStaticMarkup(
+      <MemoryRouter>
+        <AppShellSkeleton
+          layout="prompt-library"
+          firstPaintHome={firstPaintFixture()}
+        />
+      </MemoryRouter>,
+    );
+    const display = (selector: string) =>
+      getComputedStyle(document.querySelector<HTMLElement>(selector)!).display;
+    return {
+      home: display("[data-agent-native-first-paint-home]"),
+      skeleton: display("[data-agent-native-first-run-skeleton]"),
+    };
+  }
+
+  it("paints the home when first run is not pending", () => {
+    expect(paint()).toEqual({ home: "contents", skeleton: "none" });
+  });
+
+  it("paints the plain skeleton instead of the home while first run is pending", () => {
+    document.documentElement.setAttribute(FIRST_RUN_PENDING_ATTRIBUTE, "");
+    expect(paint()).toEqual({ home: "none", skeleton: "contents" });
+    expect(
+      document.querySelector(
+        "[data-agent-native-first-run-skeleton] .agent-prompt-home-hero",
+      ),
+    ).toBeNull();
+  });
+});
+
 describe("AppShellSkeleton home layout", () => {
   it("paints the home hero and resource footer beside the sidebar, with no header row", () => {
     const shell = render("home");

package/src/app/shared/AppShellSkeleton.tsx

@@ -15,6 +15,7 @@ import { AgentSuggestionBar } from "../../composer/AgentSuggestionBar.js";
 import type { PromptComposerProps } from "../../composer/index.js";
 import type { TiptapComposerHandle } from "../../composer/TiptapComposer.js";
 import { Button } from "../../ui/button.js";
+import { FIRST_RUN_PENDING_ATTRIBUTE } from "../onboarding/first-run-first-paint.js";
 import { AppSidebar, AppSidebarFooter } from "./AppSidebar.js";
 import { ClientOnly } from "./ClientOnly.js";
 
@@ -1598,7 +1599,30 @@ export function AppShellSkeleton({
     ),
     welcome: <WelcomeLayout />,
   };
-  const content = layout ? layouts[layout] : null;
+  const layoutContent = layout ? layouts[layout] : null;
+  // A first-paint home is the app's real home. When first run may start, the
+  // role question comes next, so the plain skeleton stands in for it.
+  const content =
+    firstPaintHome && layout === "prompt-library" ? (
+      <>
+        <div
+          data-agent-native-first-paint-home=""
+          style={{ display: "contents" }}
+        >
+          {layoutContent}
+        </div>
+        <div
+          data-agent-native-first-run-skeleton=""
+          role="status"
+          aria-label={ariaLabel}
+          style={{ display: "none" }}
+        >
+          <PromptLibraryLayout />
+        </div>
+      </>
+    ) : (
+      layoutContent
+    );
 
   return (
     <div
@@ -1619,6 +1643,12 @@ export function AppShellSkeleton({
         html[${MCP_APP_WIDGET_EMBED_ATTRIBUTE}] [data-agent-native-app-skeleton] > :not(style) {
           display: none !important;
         }
+        html[${FIRST_RUN_PENDING_ATTRIBUTE}] [data-agent-native-first-paint-home] {
+          display: none !important;
+        }
+        html[${FIRST_RUN_PENDING_ATTRIBUTE}] [data-agent-native-first-run-skeleton] {
+          display: contents !important;
+        }
         [data-agent-native-skeleton-block] {
           animation: an-app-shell-skeleton-pulse 1.2s ease-in-out infinite;
         }

package/src/app/styles/agent-native.css

@@ -1471,12 +1471,12 @@
     --agentkit-composer-primary-control-size,
     var(--agent-kit-composer-control-size)
   );
-  border-radius: 999px;
+  border-radius: var(--agent-kit-radius-sm, 0.5rem);
 }
 
 .agent-composer-root:not(.agent-composer-root--hero)
   .agent-composer-send-button {
-  border-radius: 999px;
+  border-radius: var(--agent-kit-radius-sm, 0.5rem);
 }
 
 /* 12px text: plain muted-foreground misses 4.5:1 on dark composer surfaces. */

package/src/app/styles/agent-native.spec.ts

@@ -231,10 +231,10 @@ describe("agent-native shell surface tokens", () => {
     );
 
     expect(tokens).toMatch(
-      /:root\s*\{[\s\S]*?--agent-kit-composer-surface: var\(--agent-kit-raised-surface\);[\s\S]*?--agent-kit-composer-border-mix: 82%;[\s\S]*?--agent-kit-composer-focus-ring-mix: 40%;[\s\S]*?--agent-kit-composer-border-color: color-mix\([\s\S]*?--agent-kit-composer-focus-border-color: color-mix\(/s,
+      /:root\s*\{[\s\S]*?--agent-kit-composer-surface: var\(--agent-kit-raised-surface\);[\s\S]*?--agent-kit-composer-border-mix: 82%;[\s\S]*?--agent-kit-composer-focus-ring-mix: 70%;[\s\S]*?--agent-kit-composer-border-color: color-mix\([\s\S]*?--agent-kit-composer-focus-border-color: color-mix\(/s,
     );
     expect(tokens).toMatch(
-      /:is\(\.dark, :root\[data-theme="dark"\]:not\(\.light\)\)\s*\{[\s\S]*?--agent-kit-composer-surface: var\(--agent-kit-subtle-surface\);[\s\S]*?--agent-kit-composer-border-mix: 80%;[\s\S]*?--agent-kit-composer-focus-ring-mix: 40%;[\s\S]*?--agent-kit-composer-border-color: color-mix\([\s\S]*?--agent-kit-composer-focus-border-color: color-mix\(/s,
+      /:is\(\.dark, :root\[data-theme="dark"\]:not\(\.light\)\)\s*\{[\s\S]*?--agent-kit-composer-surface: var\(--agent-kit-subtle-surface\);[\s\S]*?--agent-kit-composer-border-mix: 80%;[\s\S]*?--agent-kit-composer-focus-ring-mix: 70%;[\s\S]*?--agent-kit-composer-border-color: color-mix\([\s\S]*?--agent-kit-composer-focus-border-color: color-mix\(/s,
     );
     expect(css).toMatch(
       /background:\s*var\(\s*--agent-kit-composer-surface,\s*var\(--agent-kit-raised-surface\)\s*\);/,

package/src/app/styles/tokens/agent-kit.css

@@ -14,10 +14,20 @@
   --agent-kit-accent: hsl(var(--primary));
   --agent-kit-accent-text: hsl(var(--primary-foreground));
   --agent-kit-danger: hsl(var(--destructive));
+  /* Themes size --destructive as a fill; as text it can sit under 3:1. */
+  --agent-kit-danger-text: color-mix(
+    in srgb,
+    hsl(var(--destructive)) 60%,
+    hsl(var(--foreground))
+  );
   --agent-kit-success: hsl(var(--success, var(--primary)));
   --agent-kit-warning-color: hsl(var(--agent-kit-warning));
   --agent-kit-focus: hsl(var(--ring));
+  --agent-kit-progress-color: hsl(217 91% 60%);
+  --agent-kit-diff-added-color: hsl(var(--agent-kit-positive));
+  --agent-kit-diff-removed-color: hsl(var(--destructive));
 
+  --agent-kit-body-font-size: 0.875rem;
   --agent-kit-density-font-size: 0.8125rem;
   --agent-kit-density-line-height: 1.25rem;
   --agent-kit-supporting-font-size: 0.75rem;
@@ -43,10 +53,16 @@
   --agent-kit-composer-block-padding-start: 0.5rem;
   --agent-kit-composer-block-padding-end: 1rem;
   --agent-kit-composer-min-height: 4.75rem;
-  --agent-kit-composer-radius: 1.25rem;
+  /* agentkit/react/styles.css maps elements onto this scale. */
+  --agent-kit-radius-xs: 0.25rem;
+  --agent-kit-radius-sm: 0.5rem;
+  --agent-kit-radius-md: 0.75rem;
+  --agent-kit-radius-lg: 1rem;
+  --agent-kit-composer-radius: var(--agent-kit-radius-lg);
   --agent-kit-composer-surface: var(--agent-kit-raised-surface);
   --agent-kit-composer-border-mix: 82%;
-  --agent-kit-composer-focus-ring-mix: 40%;
+  /* Keeps the focus border at 3:1+; the editor has no other focus indicator. */
+  --agent-kit-composer-focus-ring-mix: 70%;
   --agent-kit-composer-border-color: color-mix(
     in srgb,
     hsl(var(--border)) var(--agent-kit-composer-border-mix),
@@ -104,9 +120,10 @@
 }
 
 :is(.dark, :root[data-theme="dark"]:not(.light)) {
+  --agent-kit-progress-color: hsl(213 94% 68%);
   --agent-kit-composer-surface: var(--agent-kit-subtle-surface);
   --agent-kit-composer-border-mix: 80%;
-  --agent-kit-composer-focus-ring-mix: 40%;
+  --agent-kit-composer-focus-ring-mix: 70%;
   --agent-kit-composer-border-color: color-mix(
     in srgb,
     hsl(var(--border)) var(--agent-kit-composer-border-mix),

package/src/composer/AgentSuggestionBar.spec.tsx

@@ -68,7 +68,9 @@ describe("AgentSuggestionBar", () => {
     expect(buttons).toHaveLength(2);
     expect(bar?.className).toContain("py-2");
     expect(bar?.className).toContain("min-w-0");
-    expect(buttons[0]?.className).toContain("rounded-full");
+    expect(buttons[0]?.className).toContain(
+      "rounded-[var(--agent-kit-radius-xs,0.25rem)]",
+    );
     expect(buttons[0]?.className).toContain("whitespace-nowrap");
     expect(buttons[0]?.className).not.toContain("max-w-");
     expect(buttons[0]?.className).toContain("text-foreground");

package/src/composer/AgentSuggestionBar.tsx

@@ -224,7 +224,10 @@ export function AgentSuggestionBar({
                   key={index}
                   aria-hidden="true"
                   data-agent-suggestion-placeholder="true"
-                  className={cn("h-6 shrink-0 rounded-full", width)}
+                  className={cn(
+                    "h-6 shrink-0 rounded-[var(--agent-kit-radius-xs,0.25rem)]",
+                    width,
+                  )}
                 />
               ))
             : items.map((suggestion, index) => (
@@ -252,7 +255,7 @@ export function AgentSuggestionBar({
                   data-agent-suggestion-position={index + 1}
                   // The scroller clips overflow, so the focus ring sits inside.
                   className={cn(
-                    "agent-kit-caption-copy snap-start inline-flex h-6 shrink-0 items-center justify-center rounded-full border border-border bg-transparent px-2.5 py-0 text-center font-normal text-foreground shadow-none hover:bg-accent hover:text-accent-foreground focus-visible:ring-inset focus-visible:ring-offset-0 whitespace-nowrap",
+                    "agent-kit-caption-copy snap-start inline-flex h-6 shrink-0 items-center justify-center rounded-[var(--agent-kit-radius-xs,0.25rem)] border border-border bg-transparent px-2.5 py-0 text-center font-normal text-foreground shadow-none hover:bg-accent hover:text-accent-foreground focus-visible:ring-inset focus-visible:ring-offset-0 whitespace-nowrap",
                     size === "comfortable" && "h-8 px-3 text-sm",
                   )}
                 >

package/src/composer/ComposerContextMenu.tsx

@@ -828,7 +828,7 @@ export function ComposerContextMenu({
                 type="button"
                 variant="ghost"
                 size="icon"
-                className="size-[var(--agentkit-composer-toolbar-control-size,1.5rem)] shrink-0 rounded-[var(--agentkit-composer-control-radius,var(--radius-md))] text-muted-foreground hover:text-foreground"
+                className="size-[var(--agentkit-composer-toolbar-control-size,1.5rem)] shrink-0 rounded-[var(--agentkit-composer-control-radius,var(--agent-kit-radius-xs,0.25rem))] text-muted-foreground hover:text-foreground aria-expanded:bg-accent aria-expanded:text-accent-foreground"
                 data-agent-composer-slot="plus-button"
                 disabled={disabled}
                 aria-label={label}
@@ -924,7 +924,7 @@ export function ComposerContextMenu({
                   <div
                     role="presentation"
                     aria-hidden="true"
-                    className="px-2 py-1 text-sm text-destructive"
+                    className="px-2 py-1 text-sm agent-kit-tone-warning"
                   >
                     {searchError}
                   </div>
@@ -973,7 +973,7 @@ export function ComposerContextMenu({
                     <div
                       role="presentation"
                       aria-hidden="true"
-                      className="px-2 py-1 text-sm text-destructive"
+                      className="px-2 py-1 text-sm agent-kit-tone-warning"
                     >
                       {integrationStatus.error}
                     </div>
@@ -1050,7 +1050,7 @@ export function ComposerContextMenu({
         />
       )}
       {error && (
-        <span role="alert" className="text-xs text-destructive">
+        <span role="alert" className="text-xs agent-kit-tone-warning">
           {error}
         </span>
       )}

package/src/composer/ComposerContextPicker.tsx

@@ -104,7 +104,10 @@ export function ComposerContextPicker({
           <>
             {actionError && (
               <>
-                <div role="alert" className="p-3 text-sm text-destructive">
+                <div
+                  role="alert"
+                  className="p-3 text-sm agent-kit-tone-warning"
+                >
                   {actionError.message}
                 </div>
                 {actionError.retry && (
@@ -133,7 +136,10 @@ export function ComposerContextPicker({
           <>
             {error ? (
               <>
-                <div role="alert" className="p-3 text-sm text-destructive">
+                <div
+                  role="alert"
+                  className="p-3 text-sm agent-kit-tone-warning"
+                >
                   {error}
                 </div>
                 {retry && (

package/src/composer/ComposerContextPickerDialog.tsx

@@ -164,7 +164,7 @@ export function ComposerContextPickerDialog({
             </div>
             <CommandList aria-label={title}>
               {loading || searchPending ? null : error ? (
-                <div role="alert" className="p-3 text-destructive">
+                <div role="alert" className="p-3 agent-kit-tone-warning">
                   {error}
                 </div>
               ) : !items.length ? null : (
@@ -289,7 +289,10 @@ export function ComposerContextPickerDialog({
                 }}
               />
               {validation && (
-                <p id={`${id}-validation`} className="text-sm text-destructive">
+                <p
+                  id={`${id}-validation`}
+                  className="text-sm agent-kit-tone-warning"
+                >
                   {validation}
                 </p>
               )}

package/src/composer/ComposerModePicker.tsx

@@ -15,6 +15,7 @@ import {
   TooltipTrigger,
 } from "../ui/tooltip.js";
 import { cn } from "../utils.js";
+import { COMPOSER_POPOVER_SURFACE_CLASS } from "./popover-surface.js";
 
 export interface ComposerModeOption {
   /** Stable host-defined mode identifier. */
@@ -75,7 +76,7 @@ export function ComposerModePicker({
         side="top"
         align="start"
         collisionPadding={8}
-        className="agent-composer-mode-picker-menu min-w-48"
+        className={`agent-composer-mode-picker-menu min-w-48 ${COMPOSER_POPOVER_SURFACE_CLASS}`}
       >
         {/* Hosts may render this picker outside a TooltipProvider. */}
         <TooltipProvider>

package/src/composer/ComposerPlusMenu.tsx

@@ -497,7 +497,7 @@ export function useComposerDefaultActions({
                   className={cn(
                     "break-words text-xs",
                     skillUploadStatus.kind === "err"
-                      ? "text-destructive"
+                      ? "agent-kit-tone-warning"
                       : "text-muted-foreground",
                   )}
                 >

package/src/composer/MentionChip.tsx

@@ -30,7 +30,7 @@ export function MentionChip({
     <span
       {...props}
       className={cn(
-        "mx-0.5 inline-flex max-w-[200px] items-center gap-1 rounded-md border border-input bg-muted/50 px-1.5 py-0.5 align-middle text-xs font-medium text-foreground",
+        "mx-1 inline-flex max-w-[200px] items-center h-5 gap-1 rounded-[var(--agent-kit-radius-xs,0.25rem)] border border-border bg-muted/50 px-2 text-xs leading-4 font-medium text-foreground align-middle",
         className,
       )}
     >

package/src/composer/MentionPopover.spec.tsx

@@ -1,10 +1,11 @@
 // @vitest-environment happy-dom
 
-import { act } from "react";
+import { act, createRef } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { MentionPopover } from "./MentionPopover.js";
+import { MentionPopover, type MentionPopoverRef } from "./MentionPopover.js";
+import { ComposerRuntimeAdaptersProvider } from "./runtime-adapters.js";
 import type { MentionItem } from "./types.js";
 
 let container: HTMLDivElement;
@@ -74,3 +75,108 @@ describe("mention sections", () => {
     expect(rowLabels(true)).toEqual(["Alice", "Claude Haiku 5.5"]);
   });
 });
+
+describe("listbox semantics", () => {
+  it("exposes the rows as options and reports the highlighted one", () => {
+    const popover = createRef<MentionPopoverRef>();
+    const onActiveOptionChange = vi.fn();
+    act(() => {
+      root.render(
+        <MentionPopover
+          ref={popover}
+          type="@"
+          position={{ top: 400, left: 0, width: 320 }}
+          mentionItems={items}
+          skills={[]}
+          isLoading={false}
+          query=""
+          onSelectMention={() => undefined}
+          onSelectSkill={() => undefined}
+          onClose={() => undefined}
+          listboxId="mentions"
+          onActiveOptionChange={onActiveOptionChange}
+        />,
+      );
+    });
+    const listbox = document.getElementById("mentions");
+    expect(listbox?.getAttribute("role")).toBe("listbox");
+    expect(listbox?.getAttribute("aria-label")).toBe("Add context");
+    const options = [...document.querySelectorAll('[role="option"]')];
+    expect(options.map((option) => option.id)).toEqual([
+      "mentions-option-0",
+      "mentions-option-1",
+    ]);
+    expect(
+      options.map((option) => option.getAttribute("aria-selected")),
+    ).toEqual(["true", "false"]);
+    const group = options[0]?.closest('[role="group"]');
+    expect(
+      document.getElementById(group?.getAttribute("aria-labelledby") ?? "")
+        ?.textContent,
+    ).toBe("Agents");
+    expect(onActiveOptionChange).toHaveBeenLastCalledWith("mentions-option-0");
+
+    act(() => popover.current?.moveDown());
+    expect(onActiveOptionChange).toHaveBeenLastCalledWith("mentions-option-1");
+    expect(
+      document
+        .getElementById("mentions-option-1")
+        ?.getAttribute("aria-selected"),
+    ).toBe("true");
+
+    act(() => root.render(<></>));
+    expect(onActiveOptionChange).toHaveBeenLastCalledWith(undefined);
+  });
+});
+
+describe("provider section names", () => {
+  it("translates a provider label that is a catalog key and keeps a plain one", () => {
+    const providerItems: MentionItem[] = [
+      {
+        id: "chat:1",
+        label: "Planning chat",
+        source: "chats",
+        refType: "chat",
+        section: "composerSources.group",
+      },
+      {
+        id: "mail:1",
+        label: "Weekly digest",
+        source: "mail",
+        refType: "email",
+        section: "Emails",
+      },
+    ];
+    act(() => {
+      root.render(
+        <ComposerRuntimeAdaptersProvider
+          adapters={{
+            translate: (key, options) =>
+              key === "composerSources.group"
+                ? "Conversations"
+                : String(options?.defaultValue ?? key),
+          }}
+        >
+          <MentionPopover
+            type="@"
+            position={{ top: 400, left: 0, width: 320 }}
+            mentionItems={providerItems}
+            skills={[]}
+            isLoading={false}
+            query=""
+            onSelectMention={() => undefined}
+            onSelectSkill={() => undefined}
+            onClose={() => undefined}
+            keepSectionOrder
+          />
+        </ComposerRuntimeAdaptersProvider>,
+      );
+    });
+    const headers = [...document.querySelectorAll('[role="group"]')].map(
+      (group) =>
+        document.getElementById(group.getAttribute("aria-labelledby") ?? "")
+          ?.textContent,
+    );
+    expect(headers).toEqual(["Conversations", "Emails"]);
+  });
+});