@agent-native/toolkit 0.227.0 → 0.228.0-nightly-20261111004142

package/src/app/settings/shell/pages/app-group-pages.spec.tsx

@@ -18,7 +18,7 @@ vi.mock("@agent-native/core/client/i18n", async () => {
     }
     return text;
   };
-  return { useT: () => t };
+  return { useT: () => t, useLocale: () => ({ locale: "en-US" }) };
 });
 
 const modelDefault = vi.hoisted(() => ({
@@ -85,15 +85,33 @@ vi.mock("../../../chat/index.js", () => ({
     </button>
   ),
 }));
-vi.mock("../../../resources/index.js", () => ({
+vi.mock("../../../resources/McpAccessSettings.js", () => ({
+  McpHostMark: () => <span />,
   McpAccessSettings: ({
     appName,
     hideHeader,
+    helpText,
+    guideId,
+    onSelectGuide,
+    guideHref,
   }: {
     appName: string;
     hideHeader: boolean;
+    helpText?: string;
+    guideId?: string | null;
+    onSelectGuide: (id: string) => void;
+    guideHref: (id: string) => string;
   }) => (
-    <div data-testid="mcp" data-app={appName} data-hide-header={hideHeader} />
+    <div
+      data-testid="mcp"
+      data-app={appName}
+      data-hide-header={hideHeader}
+      data-help={helpText}
+      data-guide={guideId}
+      data-cursor-href={guideHref("cursor")}
+    >
+      <button onClick={() => onSelectGuide("cursor")}>Choose Cursor</button>
+    </div>
   ),
 }));
 const changelogCard = vi.hoisted(() => ({
@@ -563,35 +581,27 @@ describe("app group pages", () => {
   });
 
   describe("MCP server", () => {
-    it("names the app in the about line and links Integrations", async () => {
+    it("routes client choices through the Settings shell", async () => {
       await renderPage(McpServerSettingsPage);
-      expect(container.textContent).toContain(
-        "Connect Clips to Claude, ChatGPT, Cursor, or any AI app that supports MCP.",
-      );
       const mcp = container.querySelector('[data-testid="mcp"]');
       expect(mcp?.getAttribute("data-app")).toBe("Clips");
       expect(mcp?.getAttribute("data-hide-header")).toBe("true");
-      expect(container.textContent).toContain(
-        "For tools the agent itself uses, see Integrations.",
+      expect(mcp?.getAttribute("data-cursor-href")).toBe(
+        "/settings/mcp/cursor",
       );
-      const link = [...container.querySelectorAll("a")].find(
-        (anchor) => anchor.textContent === "Integrations",
-      );
-      act(() => {
-        link?.dispatchEvent(
-          new MouseEvent("click", { bubbles: true, cancelable: true }),
-        );
-      });
-      expect(navigate).toHaveBeenCalledWith("integrations");
+      expect(mcp?.getAttribute("data-guide")).toBeNull();
+      expect(header).toBeNull();
+      act(() => container.querySelector<HTMLButtonElement>("button")?.click());
+      expect(navigate).toHaveBeenCalledWith("mcp", "cursor");
     });
 
     it("uses the app's own about line when it passes one", async () => {
       await renderPage(McpServerSettingsPage, {
         input: { mcpAbout: "Find recordings from any MCP app." },
       });
-      expect(container.textContent).toContain(
-        "Find recordings from any MCP app.",
-      );
+      expect(
+        container.querySelector("[data-testid=mcp]")?.getAttribute("data-help"),
+      ).toBe("Find recordings from any MCP app.");
     });
   });
 

package/src/app/settings/shell/pages/mcp.tsx

@@ -1,54 +1,62 @@
 import { useT } from "@agent-native/core/client/i18n";
-import type { MouseEvent } from "react";
+import { useLocale } from "@agent-native/core/client/i18n";
+import {
+  getMcpConnectGuides,
+  resolveMcpConnectGuideId,
+} from "@agent-native/core/shared/mcp-connect-content";
+import { useEffect, useMemo } from "react";
 
-import { McpAccessSettings } from "../../../resources/index.js";
-import { useSettingsShell } from "../context.js";
+import { BreadcrumbTitle } from "../../../integrations/IntegrationDetailParts.js";
+import {
+  McpAccessSettings,
+  McpHostMark,
+} from "../../../resources/McpAccessSettings.js";
+import { useSettingsPageHeader, useSettingsShell } from "../context.js";
 import type { SettingsPageProps } from "../registry.js";
 import { settingsPageHref } from "../routing.js";
 
-// Splits the translated footnote around the link, whatever the word order.
-const LINK_TOKEN = "\u0000";
-
-export default function McpServerSettingsPage({ bridge }: SettingsPageProps) {
+export default function McpServerSettingsPage({
+  bridge,
+  sub,
+}: SettingsPageProps) {
   const t = useT();
+  const { locale } = useLocale();
   const { navigate } = useSettingsShell();
+  const guides = useMemo(() => getMcpConnectGuides(locale), [locale]);
+  const guide = sub
+    ? (guides.find((item) => item.id === sub) ??
+      guides.find((item) => item.id === "other"))
+    : null;
+  const header = useMemo(
+    () =>
+      guide
+        ? {
+            title: (
+              <BreadcrumbTitle
+                name={guide.label}
+                mark={<McpHostMark id={guide.id} className="size-4" />}
+              />
+            ),
+          }
+        : null,
+    [guide],
+  );
+  useSettingsPageHeader(header);
+  useEffect(() => {
+    const query = new URLSearchParams(window.location.search).get("guide");
+    if (!sub && query)
+      navigate("mcp", resolveMcpConnectGuideId(query), { replace: true });
+  }, [navigate, sub]);
   const appName =
     bridge.appName ?? t("agentChat.settingsShell.appFallbackName");
-  const [beforeLink, afterLink = ""] = t(
-    "agentChat.settingsShell.appGroup.mcpFootnote",
-    { integrations: LINK_TOKEN },
-  ).split(LINK_TOKEN);
-  const openIntegrations = (event: MouseEvent<HTMLAnchorElement>) => {
-    if (
-      event.button !== 0 ||
-      event.metaKey ||
-      event.ctrlKey ||
-      event.shiftKey ||
-      event.altKey
-    ) {
-      return;
-    }
-    event.preventDefault();
-    navigate("integrations");
-  };
   return (
-    <div className="flex flex-col gap-6">
-      <p className="max-w-2xl text-sm leading-6 text-muted-foreground">
-        {bridge.mcpAbout ??
-          t("agentChat.settingsShell.appGroup.mcpAbout", { app: appName })}
-      </p>
-      <McpAccessSettings appName={appName} hideHeader />
-      <p className="text-xs text-muted-foreground">
-        {beforeLink}
-        <a
-          href={settingsPageHref("integrations")}
-          onClick={openIntegrations}
-          className="font-medium text-foreground underline-offset-4 hover:underline"
-        >
-          {t("agentChat.settingsShell.page.integrations")}
-        </a>
-        {afterLink}
-      </p>
-    </div>
+    <McpAccessSettings
+      appName={appName}
+      hideHeader
+      {...(bridge.mcpAbout != null ? { helpText: bridge.mcpAbout } : {})}
+      guideId={guide?.id ?? null}
+      onSelectGuide={(id) => navigate("mcp", id)}
+      guideHref={(id) => settingsPageHref("mcp", id)}
+    />
   );
 }

package/src/app/sharing/ShareButton.tsx

@@ -130,6 +130,8 @@ export interface ShareButtonProps {
     copiedLabel: string;
     onCopy: () => Promise<boolean | void> | boolean | void;
     size?: "default" | "sm";
+    /** `plain` draws Share as text, set apart from Copy link. */
+    appearance?: "joined" | "plain";
     className?: string;
   };
   /** Tooltip for the Copy link button: which link it copies. */
@@ -413,10 +415,11 @@ export function ShareButton(props: ShareButtonProps) {
     controller.handleShareTabChange,
   ]);
   const triggerLabel = t("agentChat.share.share", { defaultValue: "Share" });
+  const plainQuickCopy = props.quickCopy?.appearance === "plain";
   const trigger = (
     <ShareTrigger
       label={
-        props.quickCopy ? (
+        props.quickCopy && !plainQuickCopy ? (
           <span className="flex items-center gap-2">
             <IconUserPlus aria-hidden="true" />
             <span>{props.triggerContent ?? triggerLabel}</span>
@@ -428,8 +431,10 @@ export function ShareButton(props: ShareButtonProps) {
       className={props.triggerClassName}
       aria-label={triggerLabel}
       title={triggerLabel}
-      intent={props.quickCopy ? "primary" : undefined}
-      emphasis={props.quickCopy ? "solid" : undefined}
+      intent={props.quickCopy && !plainQuickCopy ? "primary" : undefined}
+      emphasis={
+        plainQuickCopy ? "ghost" : props.quickCopy ? "solid" : undefined
+      }
     />
   );
   if (isSmallScreen) {
@@ -442,6 +447,7 @@ export function ShareButton(props: ShareButtonProps) {
             copiedLabel={props.quickCopy.copiedLabel}
             onCopy={props.quickCopy.onCopy}
             size={props.quickCopy.size}
+            appearance={props.quickCopy.appearance}
             className={props.quickCopy.className}
           />
         ) : (
@@ -482,6 +488,7 @@ export function ShareButton(props: ShareButtonProps) {
             copiedLabel={props.quickCopy.copiedLabel}
             onCopy={props.quickCopy.onCopy}
             size={props.quickCopy.size}
+            appearance={props.quickCopy.appearance}
             className={props.quickCopy.className}
           />
         </PopoverAnchor>

package/src/composer/TiptapComposer.tsx

@@ -4824,6 +4824,8 @@ function TiptapComposerSurface({
         (e.metaKey || e.ctrlKey) &&
         !e.altKey;
       if (isToggleCombo) {
+        // A page that has already used the key keeps it.
+        if (e.defaultPrevented) return;
         e.preventDefault();
         if (voiceChatActiveRef.current) return;
         if (voice.state === "recording" || voice.state === "starting") {

package/src/composer/TiptapComposer.voice-toolbar.spec.tsx

@@ -559,6 +559,22 @@ describe("TiptapComposer voice chat", () => {
     expect(voice.start).not.toHaveBeenCalled();
   });
 
+  it("leaves the dictation key to a page that has already used it", async () => {
+    await act(async () => root.render(<Harness />));
+
+    const event = new KeyboardEvent("keydown", {
+      key: "m",
+      metaKey: true,
+      shiftKey: true,
+      cancelable: true,
+    });
+    event.preventDefault();
+    act(() => {
+      window.dispatchEvent(event);
+    });
+    expect(voice.start).not.toHaveBeenCalled();
+  });
+
   it("shows a failed session as an amber composer notice with a retry", async () => {
     activate("error");
     realtime.errorMessage = "The realtime voice connection failed.";

package/src/sharing/ShareControls.tsx

@@ -13,6 +13,8 @@ export interface JoinedShareControlProps {
   copiedLabel: string;
   onCopy: () => Promise<boolean | void> | boolean | void;
   size?: "default" | "sm";
+  /** `plain` sets the two apart, as quiet controls in a toolbar. */
+  appearance?: "joined" | "plain";
   disabled?: boolean;
   blocked?: boolean;
   className?: string;
@@ -29,6 +31,7 @@ export const JoinedShareControl = forwardRef<
     copiedLabel,
     onCopy,
     size = "default",
+    appearance = "joined",
     disabled,
     blocked,
     className,
@@ -55,6 +58,46 @@ export const JoinedShareControl = forwardRef<
   };
 
   const label = copied ? copiedLabel : copyLabel;
+  const plain = appearance === "plain";
+  const copyButton = (
+    // A click closes a tooltip, so the confirmation holds it open.
+    <Tooltip {...(copied ? { open: true } : {})}>
+      <TooltipTrigger asChild>
+        <Button
+          type="button"
+          size="sm"
+          variant={plain ? "ghost" : "default"}
+          className={cn(
+            "w-8 shrink-0 px-0 shadow-none",
+            plain && "text-muted-foreground hover:text-foreground",
+            blocked && "opacity-50",
+          )}
+          aria-label={label}
+          disabled={disabled}
+          data-blocked={blocked ? "" : undefined}
+          onClick={() => void copy()}
+        >
+          {copied ? (
+            <IconCheck aria-hidden="true" />
+          ) : (
+            <IconLink aria-hidden="true" />
+          )}
+        </Button>
+      </TooltipTrigger>
+      <TooltipContent side="bottom">{label}</TooltipContent>
+    </Tooltip>
+  );
+  if (plain) {
+    return (
+      <div
+        ref={ref}
+        className={cn("flex shrink-0 items-center gap-0.5", className)}
+      >
+        {trigger}
+        {copyButton}
+      </div>
+    );
+  }
   const segmentHeightClass =
     size === "sm"
       ? "[&>*:not([data-slot=button-group-separator]):not([data-button-group-ignore]):not(select[aria-hidden=true])]:!h-8"
@@ -69,30 +112,7 @@ export const JoinedShareControl = forwardRef<
       )}
     >
       {trigger}
-      <Tooltip>
-        <TooltipTrigger asChild>
-          <Button
-            type="button"
-            size="sm"
-            variant="default"
-            className={cn(
-              "w-8 shrink-0 px-0 shadow-none",
-              blocked && "opacity-50",
-            )}
-            aria-label={label}
-            disabled={disabled}
-            data-blocked={blocked ? "" : undefined}
-            onClick={() => void copy()}
-          >
-            {copied ? (
-              <IconCheck aria-hidden="true" />
-            ) : (
-              <IconLink aria-hidden="true" />
-            )}
-          </Button>
-        </TooltipTrigger>
-        <TooltipContent side="bottom">{label}</TooltipContent>
-      </Tooltip>
+      {copyButton}
     </ButtonGroup>
   );
 });

package/src/ui/index.ts

@@ -32,6 +32,7 @@ export * from "./label.js";
 export * from "./logo.js";
 export * from "./menubar.js";
 export * from "./navigation-menu.js";
+export * from "./numbered-steps.js";
 export * from "./pagination.js";
 export * from "./pointer-lock.js";
 export * from "./popover.js";

package/src/ui/numbered-steps.tsx

@@ -0,0 +1,104 @@
+import { Slot } from "@radix-ui/react-slot";
+import type { ComponentProps } from "react";
+
+import { cn } from "../utils.js";
+
+export function NumberedSteps({ className, ...props }: ComponentProps<"ol">) {
+  return (
+    <ol
+      data-slot="numbered-steps"
+      role="list"
+      className={cn("my-6 list-none p-0", className)}
+      {...props}
+    />
+  );
+}
+
+export function NumberedStep({
+  number,
+  last = false,
+  showConnector = true,
+  variant = "outline",
+  contentClassName,
+  className,
+  children,
+  ...props
+}: ComponentProps<"li"> & {
+  number: number;
+  last?: boolean;
+  showConnector?: boolean;
+  variant?: "outline" | "secondary";
+  contentClassName?: string;
+}) {
+  return (
+    <li
+      data-slot="numbered-step"
+      className={cn("flex items-stretch gap-4", className)}
+      {...props}
+    >
+      <div
+        data-slot="numbered-step-aside"
+        className={cn(
+          "flex shrink-0 flex-col items-center",
+          variant === "outline" && "pt-0.5",
+        )}
+        aria-hidden="true"
+      >
+        <span
+          data-slot="numbered-step-indicator"
+          className={cn(
+            "relative z-10 flex size-[26px] shrink-0 items-center justify-center rounded-full text-xs font-semibold leading-none",
+            variant === "secondary"
+              ? "bg-secondary text-secondary-foreground"
+              : "border-[1.5px] border-primary bg-background text-primary",
+          )}
+        >
+          {number}
+        </span>
+        {!last && showConnector && (
+          <span
+            data-slot="numbered-step-connector"
+            className="my-1.5 min-h-6 w-[1.5px] flex-1 bg-border"
+          />
+        )}
+      </div>
+      <div
+        data-slot="numbered-step-content"
+        className={cn("min-w-0 flex-1", !last && "pb-7", contentClassName)}
+      >
+        {children}
+      </div>
+    </li>
+  );
+}
+
+export function NumberedStepTitle({
+  asChild = false,
+  className,
+  ...props
+}: ComponentProps<"h3"> & { asChild?: boolean }) {
+  const Comp = asChild ? Slot : "h3";
+  return (
+    <Comp
+      data-slot="numbered-step-title"
+      className={cn(
+        "mt-0.5 mb-2 text-sm font-semibold leading-normal text-foreground",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function NumberedStepBody({
+  className,
+  ...props
+}: ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="numbered-step-body"
+      className={cn("text-sm leading-6 text-muted-foreground", className)}
+      {...props}
+    />
+  );
+}