Skip to content

The open-source app everyone uses to manage agents at work

feat(ui): share animated agent setup prompts (#14862)

Dotta527e146980ad
diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md
index 5d37d441c8..983f2a4ca6 100644
--- a/doc/DEVELOPING.md
+++ b/doc/DEVELOPING.md
@@ -100,6 +100,20 @@ pnpm build-storybook
These run the `@paperclipai/ui` Storybook on port `6006` and build the static output to `ui/storybook-static/`.
+Use **Components → Agent setup prompt** to review the shared setup handoff:
+hover/focus logo motion, one-click copying with a prompt preview, animated
+confirmation, and manual-copy recovery. Opening the preview copies immediately;
+clicking its trigger again copies without closing. Close and Escape only dismiss;
+the inner copy button remains available for retries and later copies. Stories include Slack and API copy, a compact quick-access placement,
+light and mobile views, and a clipboard paste check. `AgentSetupPrompt` accepts
+the complete `prompt`, `title`, `description`, trigger `label`, and popover
+placement. Use it for prompts handed to an external agent: Slack and GitHub
+connections, MCP configuration help, routine webhook setup, external-agent
+invitations, and task continuation. The **App placements** story collects the
+production controls; **Inside MCP help** exercises the popover inside a dialog.
+Prompt generation can pass `initialCopyStatus` to preserve its automatic copy
+result, and `onCopied` to clear an earlier generation-time clipboard error.
+
Use **Design explorations → Agent chat sidebar** to review the production secondary
agent navigation. **Components** covers selection, search, loading, empty results,
and larger teams. **Pages** puts it beside the production agent chat inside the
diff --git a/ui/src/components/AgentSetupPrompt.tsx b/ui/src/components/AgentSetupPrompt.tsx
new file mode 100644
index 0000000000..df025d7eb3
--- /dev/null
+++ b/ui/src/components/AgentSetupPrompt.tsx
@@ -0,0 +1,281 @@
+import { useEffect, useId, useLayoutEffect, useRef, useState, type Ref } from "react";
+import { createPortal } from "react-dom";
+import { Check, Copy, Terminal, X } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
+import { Textarea } from "@/components/ui/textarea";
+import { usePrefersReducedMotion } from "@/hooks/usePrefersReducedMotion";
+import { copyTextToClipboard } from "@/lib/clipboard";
+import { motionMilliseconds, motionNumber } from "@/lib/onboarding-motion-tokens";
+import { cn } from "@/lib/utils";
+
+export interface AgentSetupPromptProps {
+ /** The complete text to preview and copy; never truncated on the clipboard. */
+ prompt: string;
+ title?: string;
+ description?: string;
+ label?: string;
+ variant?: "outline" | "ghost";
+ side?: "top" | "bottom" | "left" | "right";
+ align?: "start" | "center" | "end";
+ className?: string;
+ /** Carry over the clipboard result when generating a prompt already copied it. */
+ initialCopyStatus?: "idle" | "copied" | "failed";
+ onCopied?: () => void;
+}
+
+const agents = [
+ { name: "Codex", src: "/brands/codex-color.svg", className: "" },
+ { name: "ChatGPT", src: "/brands/apps/openai.svg", className: "dark:invert" },
+ { name: "Claude", src: "/brands/claude-color.svg", className: "" },
+];
+
+function AgentLogos({ ref, hidden }: { ref: Ref<HTMLSpanElement>; hidden: boolean }) {
+ return (
+ <span ref={ref} className="agent-setup-logos" data-hidden={hidden} aria-hidden="true">
+ {agents.map((agent) => (
+ <span key={agent.name} className="agent-setup-logo-slot">
+ <span className="agent-setup-logo">
+ <img src={agent.src} alt="" className={cn("size-5", agent.className)} draggable={false} />
+ </span>
+ </span>
+ ))}
+ </span>
+ );
+}
+
+function readLogoPositions(group: HTMLSpanElement | null) {
+ return Array.from(group?.querySelectorAll<HTMLElement>(".agent-setup-logo") ?? []).map((logo) => {
+ const bounds = logo.getBoundingClientRect();
+ const transform = getComputedStyle(logo).transform;
+ const matrix = transform && transform !== "none" ? new DOMMatrixReadOnly(transform) : null;
+ return {
+ // A rotated bounding box is larger than the logo. Anchor its unscaled
+ // box at the same center, preserving the current hover angle separately.
+ left: bounds.left + (bounds.width - logo.offsetWidth) / 2,
+ top: bounds.top + (bounds.height - logo.offsetHeight) / 2,
+ width: logo.offsetWidth,
+ height: logo.offsetHeight,
+ transform: `rotate(${matrix ? Math.atan2(matrix.b, matrix.a) * 180 / Math.PI : 0}deg)`,
+ };
+ });
+}
+
+/** A small handoff to the user's agent, with an inspectable prompt and local copy feedback. */
+export function AgentSetupPrompt({
+ prompt,
+ title = "Agent setup",
+ description = "Paste this into your agent to take care of setup.",
+ label = "Set up with an agent",
+ variant = "outline",
+ side = "top",
+ align = "start",
+ className,
+ initialCopyStatus = "idle",
+ onCopied,
+}: AgentSetupPromptProps) {
+ const id = useId();
+ const reducedMotion = usePrefersReducedMotion();
+ const [open, setOpen] = useState(false);
+ const [status, setStatus] = useState<"idle" | "copying" | "copied" | "failed">(initialCopyStatus);
+ const [flight, setFlight] = useState<{ origins: ReturnType<typeof readLogoPositions>; toPreview: boolean } | null>(null);
+ const triggerLogos = useRef<HTMLSpanElement>(null);
+ const previewLogos = useRef<HTMLSpanElement>(null);
+ const flyingLogos = useRef<HTMLSpanElement>(null);
+ const activationOrigins = useRef<ReturnType<typeof readLogoPositions> | null>(null);
+ const copyAttempt = useRef(0);
+ const hasUserCopyAttempt = useRef(false);
+ const copying = useRef(false);
+ const copyButton = useRef<HTMLButtonElement>(null);
+
+ useEffect(() => {
+ setStatus("idle");
+ copying.current = false;
+ hasUserCopyAttempt.current = false;
+ // A pending clipboard result must not label a changed prompt as copied.
+ return () => { copyAttempt.current += 1; };
+ }, [prompt]);
+
+ useEffect(() => {
+ // A delayed generation-time copy must not replace the user's newer result.
+ if (!hasUserCopyAttempt.current) setStatus(initialCopyStatus);
+ }, [prompt, initialCopyStatus]);
+
+ useEffect(() => {
+ if (status !== "copied") return;
+ const hold = motionMilliseconds("--agent-setup-copied-hold");
+ if (hold <= 0) return;
+ const timeout = window.setTimeout(() => setStatus("idle"), hold);
+ return () => window.clearTimeout(timeout);
+ }, [status]);
+
+ useLayoutEffect(() => {
+ if (!flight) return;
+ if (reducedMotion || typeof Element.prototype.animate !== "function") {
+ setFlight(null);
+ return;
+ }
+ let frame: number;
+ let cancelled = false;
+ let animations: Animation[] = [];
+ const finish = () => { if (!cancelled) setFlight(null); };
+ const start = () => {
+ const destination = flight.toPreview ? previewLogos.current : triggerLogos.current;
+ // Radix publishes this measurement only after positioning its portal.
+ // Until then the full-size flight logos remain at the captured origin.
+ if (!destination || (flight.toPreview && !getComputedStyle(destination).getPropertyValue("--radix-popover-content-transform-origin").trim())) {
+ frame = requestAnimationFrame(start);
+ return;
+ }
+ const targets = readLogoPositions(destination);
+ const logos = flyingLogos.current?.querySelectorAll<HTMLElement>(".agent-setup-logo");
+ const easing = getComputedStyle(document.documentElement).getPropertyValue("--motion-ease-out-expo").trim();
+ animations = Array.from(logos ?? []).map((logo, index) => logo.animate(
+ [flight.origins[index], targets[index]].map(({ left, top, transform }) => ({ left: `${left}px`, top: `${top}px`, transform })),
+ { duration: motionMilliseconds("--agent-setup-flight-duration"), easing, fill: "both" },
+ ));
+ void Promise.all(animations.map((animation) => animation.finished)).then(finish, () => {});
+ };
+ frame = requestAnimationFrame(start);
+ // If the viewport moves mid-flight, settle at its live destination.
+ window.addEventListener("resize", finish);
+ document.addEventListener("scroll", finish, true);
+ return () => {
+ cancelled = true;
+ cancelAnimationFrame(frame);
+ animations.forEach((animation) => animation.cancel());
+ window.removeEventListener("resize", finish);
+ document.removeEventListener("scroll", finish, true);
+ };
+ }, [flight, reducedMotion]);
+
+ function changeOpen(nextOpen: boolean) {
+ const origins = activationOrigins.current ?? readLogoPositions(flyingLogos.current ?? (open ? previewLogos.current : triggerLogos.current));
+ activationOrigins.current = null;
+ setFlight(!reducedMotion && origins.length === agents.length ? { origins, toPreview: nextOpen } : null);
+ setOpen(nextOpen);
+ }
+
+ async function copyPrompt() {
+ if (copying.current || !prompt.trim()) return;
+ hasUserCopyAttempt.current = true;
+ copying.current = true;
+ const attempt = ++copyAttempt.current;
+ setStatus("copying");
+ try {
+ await copyTextToClipboard(prompt);
+ if (attempt === copyAttempt.current) {
+ setStatus("copied");
+ onCopied?.();
+ }
+ } catch {
+ if (attempt === copyAttempt.current) setStatus("failed");
+ } finally {
+ if (attempt === copyAttempt.current) copying.current = false;
+ }
+ }
+
+ return (
+ <>
+ <Popover open={open} onOpenChange={changeOpen}>
+ <PopoverTrigger asChild>
+ <Button
+ type="button"
+ variant={variant}
+ aria-label={label}
+ data-copied={status === "copied"}
+ onClick={(event) => {
+ // The trigger remains a copy action while open. Dismiss with
+ // Close, Escape, or outside interaction without writing again.
+ if (open) event.preventDefault();
+ else activationOrigins.current = readLogoPositions(flyingLogos.current ?? triggerLogos.current);
+ void copyPrompt();
+ }}
+ className={cn("agent-setup-trigger h-auto min-h-10 max-w-full gap-3 whitespace-normal text-left", variant === "ghost" && "w-full justify-start", className)}
+ >
+ {status === "copied" ? <Check className="agent-setup-check size-4" /> : <Terminal className="size-4 text-muted-foreground" />}
+ <span className="relative min-w-0">
+ <span className={status === "copied" ? "invisible" : undefined}>{label}</span>
+ {status === "copied" && <span className="agent-setup-confirmation absolute inset-0 flex items-center">Copied!</span>}
+ </span>
+ <span className="agent-setup-trigger-logos"><AgentLogos ref={triggerLogos} hidden={open || Boolean(flight)} /></span>
+ </Button>
+ </PopoverTrigger>
+ <PopoverContent
+ side={side}
+ align={align}
+ collisionPadding={motionNumber("--agent-setup-collision-padding")}
+ className="agent-setup-popover flex flex-col gap-4 rounded-xl p-4"
+ aria-labelledby={`${id}-title`}
+ aria-describedby={`${id}-description`}
+ onOpenAutoFocus={(event) => {
+ event.preventDefault();
+ copyButton.current?.focus();
+ }}
+ onFocusOutside={(event) => {
+ // The legacy clipboard fallback briefly focuses a textarea in
+ // document.body. Keep the preview open so its result stays visible.
+ if (copying.current) event.preventDefault();
+ }}
+ >
+ <div className="flex items-start gap-3">
+ <div className="flex min-w-0 flex-1 flex-col gap-1">
+ <h2 id={`${id}-title`} className="text-sm font-semibold">{title}</h2>
+ <p id={`${id}-description`} className="text-sm leading-relaxed text-muted-foreground">{description}</p>
+ </div>
+ <Button type="button" variant="ghost" size="icon-xs" aria-label="Close agent setup" onClick={() => changeOpen(false)}>
+ <X className="size-3.5" />
+ </Button>
+ </div>
+
+ <div className="agent-setup-preview-wrap relative pt-2">
+ <div className="agent-setup-preview-logos absolute right-3 top-0 z-10"><AgentLogos ref={previewLogos} hidden={Boolean(flight)} /></div>
+ {status === "failed" ? (
+ <Textarea
+ aria-label="Setup prompt"
+ readOnly
+ value={prompt}
+ onFocus={(event) => event.currentTarget.select()}
+ className="agent-setup-preview resize-none rounded-lg bg-muted/50 p-3 pt-5 font-mono text-xs leading-relaxed"
+ />
+ ) : (
+ <pre tabIndex={0} aria-label="Setup prompt" className="agent-setup-preview m-0 overflow-auto whitespace-pre-wrap break-words rounded-lg border border-border/60 bg-muted/50 p-3 pt-5 font-mono text-xs leading-relaxed text-muted-foreground">{prompt}</pre>
+ )}
+ </div>
+
+ <div className="flex flex-col gap-2">
+ {status === "failed" && (
+ <p role="alert" className="text-xs text-destructive">Could not copy automatically. Select and copy the prompt above, or try again.</p>
+ )}
+ <Button
+ ref={copyButton}
+ type="button"
+ variant="cta"
+ className="agent-setup-copy w-full"
+ data-copied={status === "copied"}
+ aria-disabled={status === "copying" || !prompt.trim()}
+ onClick={() => { if (prompt.trim()) void copyPrompt(); }}
+ >
+ {status === "copied" ? <Check className="agent-setup-check size-4" /> : <Copy className="size-4" />}
+ {status === "copied" ? "Copied to clipboard" : status === "copying" ? "Copying…" : status === "failed" ? "Try copying again" : "Copy prompt"}
+ </Button>
+ <p className="text-center text-xs text-muted-foreground">
+ {status === "copied" ? "Ready to paste into your agent." : "Works with Codex, ChatGPT, Claude, and more."}
+ </p>
+ </div>
+ </PopoverContent>
+ </Popover>
+ <span role="status" className="sr-only">{status === "copied" ? "Setup prompt copied. Ready to paste into your agent." : ""}</span>
+ {flight && createPortal(
+ <span ref={flyingLogos} className="agent-setup-flight-layer" aria-hidden="true">
+ {agents.map((agent, index) => (
+ <span key={agent.name} className="agent-setup-logo agent-setup-flying-logo" style={flight.origins[index]}>
+ <img src={agent.src} alt="" className={cn("size-5", agent.className)} draggable={false} />
+ </span>
+ ))}
+ </span>,
+ document.body,
+ )}
+ </>
+ );
+}
diff --git a/ui/src/components/IssueContinuationHandoff.test.tsx b/ui/src/components/IssueContinuationHandoff.test.tsx
index 78278569e4..e2573c5498 100644
--- a/ui/src/components/IssueContinuationHandoff.test.tsx
+++ b/ui/src/components/IssueContinuationHandoff.test.tsx
@@ -75,7 +75,7 @@ describe("IssueContinuationHandoff", () => {
expect(container.textContent).not.toContain("Resume from the activity tab.");
const copyButton = Array.from(container.querySelectorAll("button"))
- .find((button) => button.textContent?.includes("Copy"));
+ .find((button) => button.getAttribute("aria-label") === "Continue with an agent");
expect(copyButton).toBeTruthy();
await act(async () => {
@@ -84,6 +84,7 @@ describe("IssueContinuationHandoff", () => {
expect(navigator.clipboard.writeText).toHaveBeenCalledWith(handoff.body);
expect(container.textContent).toContain("Copied");
+ expect(document.querySelector('pre[aria-label="Setup prompt"]')?.textContent).toBe(handoff.body);
await act(async () => {
root.unmount();
diff --git a/ui/src/components/IssueContinuationHandoff.tsx b/ui/src/components/IssueContinuationHandoff.tsx
index cc4f0531f3..e1a181b865 100644
--- a/ui/src/components/IssueContinuationHandoff.tsx
+++ b/ui/src/components/IssueContinuationHandoff.tsx
@@ -1,12 +1,11 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useEffect, useRef, useState } from "react";
import type { IssueDocument } from "@paperclipai/shared";
import { ISSUE_CONTINUATION_SUMMARY_DOCUMENT_KEY } from "@paperclipai/shared";
-import { Button } from "@/components/ui/button";
+import { AgentSetupPrompt } from "@/components/AgentSetupPrompt";
import { cn, relativeTime } from "../lib/utils";
import { MarkdownBody, type MarkdownExternalReferenceMap } from "./MarkdownBody";
-import { Check, ChevronDown, ChevronRight, Copy, History } from "lucide-react";
+import { ChevronDown, ChevronRight, History } from "lucide-react";
import { Badge } from "@/components/ui/badge";
-import { copyTextToClipboard } from "@/lib/clipboard";
type IssueContinuationHandoffProps = {
document: IssueDocument | null | undefined;
@@ -20,18 +19,8 @@ export function IssueContinuationHandoff({
externalReferences,
}: IssueContinuationHandoffProps) {
const [expanded, setExpanded] = useState(false);
- const [copied, setCopied] = useState(false);
const [highlighted, setHighlighted] = useState(false);
const rootRef = useRef<HTMLDivElement | null>(null);
- const copiedTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
- useEffect(() => {
- return () => {
- if (copiedTimerRef.current) {
- clearTimeout(copiedTimerRef.current);
- }
- };
- }, []);
useEffect(() => {
if (!document || focusSignal <= 0) return;
@@ -42,20 +31,6 @@ export function IssueContinuationHandoff({
return () => clearTimeout(timer);
}, [document, focusSignal]);
- const copyBody = useCallback(async () => {
- if (!document) return;
- try {
- await copyTextToClipboard(document.body);
- } catch {
- return;
- }
- setCopied(true);
- if (copiedTimerRef.current) {
- clearTimeout(copiedTimerRef.current);
- }
- copiedTimerRef.current = setTimeout(() => setCopied(false), 1500);
- }, [document]);
-
if (!document) return null;
const title = document.title?.trim() || "Continuation handoff";
@@ -92,10 +67,13 @@ export function IssueContinuationHandoff({
{document.latestRevisionNumber > 0 ? ` - revision ${document.latestRevisionNumber}` : ""}
</div>
</div>
- <Button variant="ghost" size="sm" onClick={copyBody} className="shrink-0">
- {copied ? <Check className="mr-1.5 h-3.5 w-3.5" /> : <Copy className="mr-1.5 h-3.5 w-3.5" />}
- {copied ? "Copied" : "Copy"}
- </Button>
+ <AgentSetupPrompt
+ prompt={document.body}
+ label="Continue with an agent"
+ title="Task handoff"
+ description="Paste this into your agent to continue from this handoff."
+ align="end"
+ />
</div>
{expanded ? (
<div className="mt-3 rounded-md border border-border bg-background/80 p-3">
diff --git a/ui/src/components/NewAgentDialog.test.tsx b/ui/src/components/NewAgentDialog.test.tsx
index da2afdf88c..2098a38e44 100644
--- a/ui/src/components/NewAgentDialog.test.tsx
+++ b/ui/src/components/NewAgentDialog.test.tsx
@@ -184,7 +184,12 @@ it("keeps agent-only invitations reachable from the new-agent flow", async () =>
allowedJoinTypes: "agent", humanRole: null, agentMessage: "Help with research",
});
expect(document.querySelector<HTMLTextAreaElement>('textarea[readonly]')?.value).toContain("/api/invites/one-time-token/onboarding.txt");
- expect(invites.copy).toHaveBeenCalled();
+ expect(invites.copy).toHaveBeenCalledTimes(1);
+ expect(document.querySelector('[aria-label="Copy onboarding prompt"]')?.getAttribute("data-copied")).toBe("true");
+ await act(async () => document.querySelector<HTMLButtonElement>('[aria-label="Copy onboarding prompt"]')!.click());
+ expect(invites.copy).toHaveBeenCalledTimes(2);
+ expect(invites.createCompanyInvite).toHaveBeenCalledTimes(1);
+ expect(document.querySelector('pre[aria-label="Setup prompt"]')?.textContent).toBe(invites.copy.mock.calls[0][0]);
expect(state.navigate).not.toHaveBeenCalled();
});
@@ -197,3 +202,47 @@ it("keeps the generated invitation readable when clipboard access fails", async
expect(document.body.textContent).toContain("Copy the prompt manually");
expect(document.querySelector<HTMLTextAreaElement>('textarea[readonly]')?.value).toContain("/api/invites/one-time-token/onboarding.txt");
});
+
+it("clears the invitation copy failure after retrying without generating another invite", async () => {
+ invites.copy.mockRejectedValueOnce(new Error("Clipboard unavailable"));
+ await click("Invite an external agent");
+ await click("Generate onboarding prompt");
+ await act(async () => { await new Promise(resolve => setTimeout(resolve, 20)); });
+ expect(document.body.textContent).toContain("Clipboard unavailable");
+ await click("Copy onboarding prompt");
+ expect(invites.copy).toHaveBeenCalledTimes(2);
+ expect(invites.createCompanyInvite).toHaveBeenCalledTimes(1);
+ expect(document.body.textContent).not.toContain("Clipboard unavailable");
+ expect(document.body.textContent).toContain("Copied to clipboard");
+});
+
+it("shows the generated invitation while automatic clipboard access is pending", async () => {
+ let finishCopy!: () => void;
+ invites.copy.mockImplementationOnce(() => new Promise<void>((resolve) => { finishCopy = resolve; }));
+ await click("Invite an external agent");
+ await click("Generate onboarding prompt");
+ await act(async () => { await new Promise(resolve => setTimeout(resolve, 20)); });
+ expect(document.querySelector<HTMLTextAreaElement>('textarea[readonly]')?.value).toContain("/api/invites/one-time-token/onboarding.txt");
+ expect(document.querySelector('[aria-label="Copy onboarding prompt"]')?.getAttribute("data-copied")).toBe("false");
+ await act(async () => finishCopy());
+ expect(document.querySelector('[aria-label="Copy onboarding prompt"]')?.getAttribute("data-copied")).toBe("true");
+});
+
+it("keeps a newer user copy result when the automatic invitation copy fails", async () => {
+ let failAutomaticCopy!: (error: Error) => void;
+ let finishUserCopy!: () => void;
+ invites.copy
+ .mockImplementationOnce(() => new Promise<void>((_resolve, reject) => { failAutomaticCopy = reject; }))
+ .mockImplementationOnce(() => new Promise<void>((resolve) => { finishUserCopy = resolve; }));
+ await click("Invite an external agent");
+ await click("Generate onboarding prompt");
+ await act(async () => { await new Promise(resolve => setTimeout(resolve, 20)); });
+ await click("Copy onboarding prompt");
+ await act(async () => failAutomaticCopy(new Error("Automatic copy failed")));
+ expect(document.querySelector(".agent-setup-copy")?.textContent).toBe("Copying…");
+ await act(async () => finishUserCopy());
+ expect(document.querySelector(".agent-setup-copy")?.textContent).toBe("Copied to clipboard");
+ expect(document.body.textContent).not.toContain("Clipboard unavailable");
+ expect(invites.copy).toHaveBeenCalledTimes(2);
+ expect(invites.createCompanyInvite).toHaveBeenCalledTimes(1);
+});
diff --git a/ui/src/components/new-agent/ExternalAgentInviteDialog.tsx b/ui/src/components/new-agent/ExternalAgentInviteDialog.tsx
index 1a750bb82b..1d1acffd8d 100644
--- a/ui/src/components/new-agent/ExternalAgentInviteDialog.tsx
+++ b/ui/src/components/new-agent/ExternalAgentInviteDialog.tsx
@@ -4,6 +4,7 @@ import { accessApi } from "@/api/access";
import { queryKeys } from "@/lib/queryKeys";
import { buildAgentOnboardingPrompt } from "@/lib/agent-onboarding-prompt";
import { copyTextToClipboard } from "@/lib/clipboard";
+import { AgentSetupPrompt } from "@/components/AgentSetupPrompt";
import { Button } from "../ui/button";
import { Textarea } from "../ui/textarea";
import { Dialog, DialogContent, DialogDescription, DialogTitle } from "../ui/dialog";
@@ -21,17 +22,8 @@ export function ExternalAgentInviteDialog({ companyId, onClose, onBack }: {
return () => { mounted.current = false; };
}, []);
const [message, setMessage] = useState("");
- const [prompt, setPrompt] = useState<string | null>(null);
- const [copied, setCopied] = useState(false);
- const [copyError, setCopyError] = useState(false);
- async function copy(value: string) {
- try {
- await copyTextToClipboard(value);
- if (mounted.current) { setCopied(true); setCopyError(false); }
- } catch {
- if (mounted.current) setCopyError(true);
- }
- }
+ const [result, setResult] = useState<{ prompt: string; copyStatus: "idle" | "copied" | "failed" } | null>(null);
+ const prompt = result?.prompt;
const createInvite = useMutation({
mutationFn: async () => {
const invite = await accessApi.createCompanyInvite(companyId, {
@@ -51,8 +43,15 @@ export function ExternalAgentInviteDialog({ companyId, onClose, onBack }: {
},
onSuccess: async (value) => {
if (!mounted.current) return;
- setPrompt(value);
- await copy(value);
+ // Keep the invitation readable while a browser clipboard request is pending.
+ setResult({ prompt: value, copyStatus: "idle" });
+ let copyStatus: "copied" | "failed" = "copied";
+ try {
+ await copyTextToClipboard(value);
+ } catch {
+ copyStatus = "failed";
+ }
+ if (mounted.current) setResult((current) => current?.copyStatus === "idle" ? { ...current, copyStatus } : current);
},
});
return <Dialog open onOpenChange={(open) => { if (!open) onClose(); }}>
@@ -64,10 +63,17 @@ export function ExternalAgentInviteDialog({ companyId, onClose, onBack }: {
</DialogDescription>
{prompt ? <>
<Textarea aria-label="Agent onboarding prompt" readOnly value={prompt} className="min-h-64 font-mono text-xs" />
- {copyError && <p role="alert" className="text-sm text-muted-foreground">Clipboard unavailable. Copy the prompt manually from the field above.</p>}
- <div className="flex justify-between gap-4">
+ {result?.copyStatus === "failed" && <p role="alert" className="text-sm text-muted-foreground">Clipboard unavailable. Copy the prompt manually from the field above, or use the button below to try again.</p>}
+ <div className="flex flex-wrap items-center justify-between gap-4">
<Button variant="ghost" onClick={onClose}>Done</Button>
- <Button variant="outline" onClick={() => void copy(prompt)}>{copied ? "Copied prompt" : "Copy prompt"}</Button>
+ <AgentSetupPrompt
+ prompt={prompt}
+ label="Copy onboarding prompt"
+ title="Invite your agent"
+ description="Paste this into your external agent to request access to your organization."
+ initialCopyStatus={result?.copyStatus}
+ onCopied={() => setResult((current) => current && { ...current, copyStatus: "copied" })}
+ />
</div>
</> : <>
<label className="space-y-2 text-sm">
diff --git a/ui/src/components/routine-triggers/WebhookFields.tsx b/ui/src/components/routine-triggers/WebhookFields.tsx
index 6278803acb..e55e10ebf6 100644
--- a/ui/src/components/routine-triggers/WebhookFields.tsx
+++ b/ui/src/components/routine-triggers/WebhookFields.tsx
@@ -3,6 +3,7 @@ import { Check, Copy } from "lucide-react";
import { Button } from "@/components/ui/button";
import { Label } from "@/components/ui/label";
import { copyTextToClipboard } from "@/lib/clipboard";
+import { AgentSetupPrompt } from "@/components/AgentSetupPrompt";
export function CopyField({
label,
@@ -64,8 +65,6 @@ export function CopyField({
}
export function AgentInstructions({ value }: { value: string }) {
- const [copied, setCopied] = useState(false);
- const [error, setError] = useState(false);
return (
<section
aria-label="Agent instructions"
@@ -78,41 +77,12 @@ export function AgentInstructions({ value }: { value: string }) {
authentication key, and step-by-step instructions.
</p>
</div>
- <Button
- variant="outline"
- size="sm"
- aria-label="Copy for your agent"
- onClick={async () => {
- try {
- await copyTextToClipboard(value);
- setCopied(true);
- setError(false);
- } catch {
- setError(true);
- }
- }}
- >
- {copied ? (
- <Check className="h-3.5 w-3.5" />
- ) : (
- <Copy className="h-3.5 w-3.5" />
- )}
- {copied ? "Copied instructions" : "Copy for your agent"}
- </Button>
- {error && (
- <div className="space-y-2">
- <p role="alert" className="text-xs text-destructive">
- Copy failed. Select and copy the instructions below.
- </p>
- <textarea
- readOnly
- aria-label="Agent instructions text"
- value={value}
- rows={5}
- className="w-full rounded-md border border-input bg-background p-3 text-sm"
- />
- </div>
- )}
+ <AgentSetupPrompt
+ prompt={value}
+ label="Copy for your agent"
+ title="Webhook setup"
+ description="Paste this into your agent to connect this webhook to your routine."
+ />
</section>
);
}
diff --git a/ui/src/index.css b/ui/src/index.css
index 3ab7ed7312..bec5ab10ee 100644
--- a/ui/src/index.css
+++ b/ui/src/index.css
@@ -3217,3 +3217,79 @@ span.paperclip-mention-chip[data-mention-kind="external-object"] {
.skill-import-enter, .skill-import-sweep { animation: none; }
.skill-import-progress::-webkit-progress-value { transition: none; }
}
+
+/* Agent setup handoff: the same logo stack travels from trigger to prompt. */
+:root {
+ --agent-setup-flight-duration: var(--motion-duration-deliberate);
+ --agent-setup-copied-hold: 2400ms;
+ --agent-setup-popover-width: 21rem;
+ --agent-setup-collision-padding: 12;
+ --agent-setup-preview-height: clamp(6rem, 27dvh, 12rem);
+ --agent-setup-logo-size: calc(var(--spacing) * 7);
+ --agent-setup-logo-overlap: calc(var(--spacing) * -1.5);
+ --agent-setup-logo-lift: calc(var(--spacing) * -1.5);
+ --agent-setup-logo-tilt: 14deg;
+}
+.agent-setup-trigger-logos {
+ display: inline-flex;
+ flex-shrink: 0;
+ width: calc(var(--agent-setup-logo-size) * 3 + var(--agent-setup-logo-overlap) * 2);
+ height: var(--agent-setup-logo-size);
+ margin-left: auto;
+}
+.agent-setup-logos { display: inline-flex; isolation: isolate; }
+.agent-setup-logos[data-hidden="true"] { visibility: hidden; }
+.agent-setup-logo-slot { display: inline-flex; position: relative; }
+.agent-setup-logo-slot + .agent-setup-logo-slot { margin-left: var(--agent-setup-logo-overlap); }
+.agent-setup-flight-layer { position: fixed; inset: 0; z-index: 51; pointer-events: none; }
+.agent-setup-flight-layer .agent-setup-flying-logo { position: absolute; transition: none; }
+.agent-setup-logo {
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ width: var(--agent-setup-logo-size);
+ height: var(--agent-setup-logo-size);
+ border-radius: var(--radius-lg);
+ border: 1px solid var(--border);
+ background: var(--popover);
+ box-shadow: var(--shadow-xs);
+ transition: transform var(--motion-duration-slow) var(--motion-ease-out-expo);
+}
+.agent-setup-trigger:is(:hover, :focus-visible) .agent-setup-logo-slot:nth-child(1) .agent-setup-logo {
+ transform: translateY(var(--agent-setup-logo-lift)) rotate(calc(-1 * var(--agent-setup-logo-tilt)));
+}
+.agent-setup-trigger:is(:hover, :focus-visible) .agent-setup-logo-slot:nth-child(2) .agent-setup-logo {
+ transform: translateY(calc(var(--agent-setup-logo-lift) * 1.6));
+}
+.agent-setup-trigger:is(:hover, :focus-visible) .agent-setup-logo-slot:nth-child(3) .agent-setup-logo {
+ transform: translateY(calc(var(--agent-setup-logo-lift) * 0.6)) rotate(var(--agent-setup-logo-tilt));
+}
+.agent-setup-popover {
+ width: min(var(--agent-setup-popover-width), calc(100vw - var(--spacing) * 6));
+ max-height: var(--radix-popover-content-available-height);
+ box-shadow: var(--shadow-profile-popover);
+}
+.agent-setup-popover[data-state="open"] { animation: tc-fade-in var(--motion-duration-base) var(--motion-ease-out-expo); }
+.agent-setup-popover[data-state="closed"] { animation: none; }
+.agent-setup-preview {
+ height: var(--agent-setup-preview-height);
+ max-height: max(3rem, calc(var(--radix-popover-content-available-height) - 12rem));
+ scrollbar-width: thin;
+}
+.agent-setup-preview-logos { transform: translateY(-25%); }
+.agent-setup-preview-logos .agent-setup-logo-slot:first-child .agent-setup-logo { transform: rotate(calc(var(--agent-setup-logo-tilt) * -0.5)); }
+.agent-setup-preview-logos .agent-setup-logo-slot:last-child .agent-setup-logo { transform: rotate(calc(var(--agent-setup-logo-tilt) * 0.5)); }
+.agent-setup-check { animation: agent-setup-check var(--motion-duration-slow) var(--motion-ease-out-expo) both; }
+.agent-setup-confirmation { animation: tc-fade-rise var(--motion-duration-base) var(--motion-ease-out-expo) both; }
+.agent-setup-copy[aria-disabled="true"] { opacity: 0.5; }
+@keyframes agent-setup-check {
+ from { opacity: 0; transform: scale(0.6) rotate(-20deg); }
+ to { opacity: 1; transform: scale(1) rotate(0); }
+}
+@media (prefers-reduced-motion: reduce) {
+ .agent-setup-logo { transition: none; transform: none !important; }
+ .agent-setup-popover, .agent-setup-check, .agent-setup-confirmation { animation: none !important; }
+}
+@media (max-height: 420px) {
+ .agent-setup-popover { overflow-y: auto; }
+}
diff --git a/ui/src/lib/mention-chips.ts b/ui/src/lib/mention-chips.ts
index 7d0f783960..bc721c5c5e 100644
--- a/ui/src/lib/mention-chips.ts
+++ b/ui/src/lib/mention-chips.ts
@@ -212,12 +212,15 @@ function resolveLucideIconNode(
const render = (
icon as {
render?: (props: Record<string, unknown>, ref: unknown) => {
- props?: { iconNode?: Array<[string, Record<string, string>]> };
+ props?: {
+ iconNode?: Array<[string, Record<string, string>]>;
+ icon?: { node?: Array<[string, Record<string, string>]> };
+ };
} | null;
}
).render;
const rendered = typeof render === "function" ? render({}, null) : null;
- const renderedIconNode = rendered?.props?.iconNode;
+ const renderedIconNode = rendered?.props?.icon?.node ?? rendered?.props?.iconNode;
return Array.isArray(renderedIconNode) && renderedIconNode.length > 0
? renderedIconNode
: null;
diff --git a/ui/src/pages/DesignGuide.tsx b/ui/src/pages/DesignGuide.tsx
index bf60ce5984..4002febed8 100644
--- a/ui/src/pages/DesignGuide.tsx
+++ b/ui/src/pages/DesignGuide.tsx
@@ -2286,7 +2286,7 @@ export function DesignGuide() {
</Section>
<Section title="Browser setup prompt">
- <p className="text-sm text-muted-foreground">A shared copy action for provider setup instructions. Confirms success inline and offers selectable text if clipboard access fails.</p>
+ <p className="text-sm text-muted-foreground">Use AgentSetupPrompt for prompts handed to an external agent: connections, webhook setup, onboarding, and task handoffs. One click copies the complete prompt, opens its preview, and confirms success inline; clipboard failures offer selectable text.</p>
<SetupPrompt prompt="Design guide example. This is a preview, not a real provider setup request." />
</Section>
diff --git a/ui/src/pages/apps/chat/GitHubSetupPrompt.test.tsx b/ui/src/pages/apps/chat/GitHubSetupPrompt.test.tsx
index 7f548d8c70..66674a8499 100644
--- a/ui/src/pages/apps/chat/GitHubSetupPrompt.test.tsx
+++ b/ui/src/pages/apps/chat/GitHubSetupPrompt.test.tsx
@@ -24,36 +24,48 @@ describe("GitHub setup prompt", () => {
container.remove();
});
- it("copies the complete instructions and confirms success", async () => {
- vi.mocked(copyTextToClipboard).mockResolvedValue(undefined);
+ async function openPrompt() {
await act(async () => container.querySelector("button")!.click());
+ return document.querySelector('[role="dialog"]')!;
+ }
+
+ async function copyPrompt(dialog: Element) {
+ await act(async () => dialog.querySelector<HTMLButtonElement>(".agent-setup-copy")!.click());
+ }
+
+ it("copies on the opening click and confirms success in both buttons", async () => {
+ vi.mocked(copyTextToClipboard).mockResolvedValue(undefined);
+ const dialog = await openPrompt();
+ expect(copyTextToClipboard).toHaveBeenCalledTimes(1);
expect(copyTextToClipboard).toHaveBeenCalledWith(buildGitHubSetupPrompt(window.location.origin));
expect(vi.mocked(copyTextToClipboard).mock.calls[0][0]).toContain(`Paperclip instance URL: ${window.location.origin}`);
- expect(container.querySelector("button")?.textContent).toBe("Copied setup prompt");
- expect(container.querySelector('[role="status"]')?.textContent).toContain("Paste it into Codex or Claude");
- expect(container.querySelector("textarea")).toBeNull();
+ expect(dialog.querySelector(".agent-setup-copy")?.textContent).toBe("Copied to clipboard");
+ expect(container.querySelector('[role="status"]')?.textContent).toContain("Ready to paste into your agent.");
+ expect(container.querySelector("button")?.dataset.copied).toBe("true");
+ expect(dialog.querySelector("textarea")).toBeNull();
});
it("offers selectable instructions when clipboard access fails and allows retry", async () => {
vi.mocked(copyTextToClipboard).mockRejectedValueOnce(new Error("Clipboard unavailable"));
- await act(async () => container.querySelector("button")!.click());
- const fallback = container.querySelector("textarea")!;
+ const dialog = await openPrompt();
+ const fallback = dialog.querySelector("textarea")!;
expect(fallback.value).toBe(buildGitHubSetupPrompt(window.location.origin));
expect(fallback.readOnly).toBe(true);
fallback.focus();
expect(fallback.selectionStart).toBe(0);
expect(fallback.selectionEnd).toBe(fallback.value.length);
- expect(container.querySelector('[role="alert"]')?.textContent).toContain("Could not copy");
+ expect(dialog.querySelector('[role="alert"]')?.textContent).toContain("Could not copy");
vi.mocked(copyTextToClipboard).mockResolvedValueOnce(undefined);
- await act(async () => container.querySelector("button")!.click());
- expect(container.querySelector('[role="alert"]')).toBeNull();
- expect(container.querySelector("textarea")).toBeNull();
+ await copyPrompt(dialog);
+ expect(dialog.querySelector('[role="alert"]')).toBeNull();
+ expect(dialog.querySelector("textarea")).toBeNull();
});
it("uses the preview's configured instance instead of its Storybook host", async () => {
await act(async () => root.render(<GitHubSetupPrompt instanceUrl="https://my-company.paperclip.app" />));
vi.mocked(copyTextToClipboard).mockResolvedValue(undefined);
- await act(async () => container.querySelector("button")!.click());
+ const dialog = await openPrompt();
+ expect(copyTextToClipboard).toHaveBeenCalledTimes(1);
expect(copyTextToClipboard).toHaveBeenCalledWith(buildGitHubSetupPrompt("https://my-company.paperclip.app"));
});
diff --git a/ui/src/pages/apps/chat/GitHubSetupPrompt.tsx b/ui/src/pages/apps/chat/GitHubSetupPrompt.tsx
index 0b2027448a..787e700ac6 100644
--- a/ui/src/pages/apps/chat/GitHubSetupPrompt.tsx
+++ b/ui/src/pages/apps/chat/GitHubSetupPrompt.tsx
@@ -43,5 +43,5 @@ export function buildGitHubSetupPrompt(instanceUrl: string) {
}
export function GitHubSetupPrompt({ instanceUrl = window.location.origin }: { instanceUrl?: string }) {
- return <SetupPrompt prompt={buildGitHubSetupPrompt(instanceUrl)} />;
+ return <SetupPrompt prompt={buildGitHubSetupPrompt(instanceUrl)} description="Paste this into your agent to configure your GitHub review bot." />;
}
diff --git a/ui/src/pages/apps/chat/SetupPrompt.tsx b/ui/src/pages/apps/chat/SetupPrompt.tsx
index 6106b44e78..1cdf3b2500 100644
--- a/ui/src/pages/apps/chat/SetupPrompt.tsx
+++ b/ui/src/pages/apps/chat/SetupPrompt.tsx
@@ -1,8 +1,4 @@
-import { useState } from "react";
-import { Check, Copy } from "lucide-react";
-import { Button } from "@/components/ui/button";
-import { Textarea } from "@/components/ui/textarea";
-import { copyTextToClipboard } from "@/lib/clipboard";
+export { AgentSetupPrompt as SetupPrompt } from "@/components/AgentSetupPrompt";
export function buildSetupPrompt(instanceUrl: string, instructions: string) {
let instanceOrigin: string | null = null;
@@ -17,38 +13,3 @@ export function buildSetupPrompt(instanceUrl: string, instructions: string) {
: "Paperclip instance URL is unavailable. Ask me for it before starting setup.";
return `${context}\n\n${instructions}`;
}
-
-export function SetupPrompt({ prompt }: { prompt: string }) {
- const [status, setStatus] = useState<"idle" | "copied" | "failed">("idle");
- return (
- <div className="space-y-2">
- <Button
- type="button"
- variant="outline"
- className="gap-2 border-dashed text-muted-foreground"
- onClick={async () => {
- try {
- await copyTextToClipboard(prompt);
- setStatus("copied");
- } catch {
- setStatus("failed");
- }
- }}
- >
- <span className="flex -space-x-1" aria-hidden="true">
- <img src="/brands/claude-color.svg" alt="" className="size-4 rounded-full bg-background ring-2 ring-background" />
- <img src="/brands/codex-color.svg" alt="" className="size-4 rounded-full bg-background ring-2 ring-background" />
- </span>
- {status === "copied" ? "Copied setup prompt" : "Copy setup prompt"}
- {status === "copied" ? <Check className="size-3.5" /> : <Copy className="size-3.5" />}
- </Button>
- <span className="sr-only" role="status">{status === "copied" ? "Setup prompt copied. Paste it into Codex or Claude with browser tools." : ""}</span>
- {status === "failed" && (
- <div className="space-y-2">
- <p role="alert" className="text-sm text-muted-foreground">Could not copy automatically. Select and copy the setup prompt below.</p>
- <Textarea aria-label="Setup prompt" readOnly value={prompt} onFocus={(event) => event.currentTarget.select()} rows={8} />
- </div>
- )}
- </div>
- );
-}
diff --git a/ui/src/pages/apps/chat/SlackSetupPrompt.test.tsx b/ui/src/pages/apps/chat/SlackSetupPrompt.test.tsx
index 24e0e428f5..2774c17b97 100644
--- a/ui/src/pages/apps/chat/SlackSetupPrompt.test.tsx
+++ b/ui/src/pages/apps/chat/SlackSetupPrompt.test.tsx
@@ -24,39 +24,93 @@ describe("Slack setup prompt", () => {
container.remove();
});
- it("copies the complete instructions and confirms success", async () => {
- vi.mocked(copyTextToClipboard).mockResolvedValue(undefined);
+ async function openPrompt() {
await act(async () => container.querySelector("button")!.click());
+ return document.querySelector('[role="dialog"]')!;
+ }
+
+ async function copyPrompt(dialog: Element) {
+ await act(async () => dialog.querySelector<HTMLButtonElement>(".agent-setup-copy")!.click());
+ }
+
+ it("copies on the opening click and confirms success in both buttons", async () => {
+ vi.mocked(copyTextToClipboard).mockResolvedValue(undefined);
+ const dialog = await openPrompt();
+ expect(copyTextToClipboard).toHaveBeenCalledTimes(1);
expect(copyTextToClipboard).toHaveBeenCalledWith(buildSlackSetupPrompt(window.location.origin));
expect(vi.mocked(copyTextToClipboard).mock.calls[0][0]).toContain(`Paperclip instance URL: ${window.location.origin}`);
- expect(container.querySelector("button")?.textContent).toBe("Copied setup prompt");
- expect(container.querySelector('[role="status"]')?.textContent).toContain("Paste it into Codex or Claude");
- expect(container.querySelector("textarea")).toBeNull();
+ expect(dialog.querySelector(".agent-setup-copy")?.textContent).toBe("Copied to clipboard");
+ expect(container.querySelector('[role="status"]')?.textContent).toContain("Ready to paste into your agent.");
+ expect(container.querySelector("button")?.dataset.copied).toBe("true");
+ expect(dialog.querySelector("textarea")).toBeNull();
});
it("offers selectable instructions when clipboard access fails and allows retry", async () => {
- vi.mocked(copyTextToClipboard).mockRejectedValueOnce(new Error("Clipboard unavailable"));
- await act(async () => container.querySelector("button")!.click());
- const fallback = container.querySelector("textarea")!;
+ vi.mocked(copyTextToClipboard).mockImplementationOnce(async () => {
+ // The browser fallback focuses an off-screen textarea outside the popover.
+ const clipboardField = document.createElement("textarea");
+ document.body.append(clipboardField);
+ clipboardField.focus();
+ clipboardField.remove();
+ throw new Error("Clipboard unavailable");
+ });
+ const dialog = await openPrompt();
+ const fallback = dialog.querySelector("textarea")!;
expect(fallback.value).toBe(buildSlackSetupPrompt(window.location.origin));
expect(fallback.readOnly).toBe(true);
fallback.focus();
expect(fallback.selectionStart).toBe(0);
expect(fallback.selectionEnd).toBe(fallback.value.length);
- expect(container.querySelector('[role="alert"]')?.textContent).toContain("Could not copy");
+ expect(dialog.querySelector('[role="alert"]')?.textContent).toContain("Could not copy");
vi.mocked(copyTextToClipboard).mockResolvedValueOnce(undefined);
- await act(async () => container.querySelector("button")!.click());
- expect(container.querySelector('[role="alert"]')).toBeNull();
- expect(container.querySelector("textarea")).toBeNull();
+ await copyPrompt(dialog);
+ expect(dialog.querySelector('[role="alert"]')).toBeNull();
+ expect(dialog.querySelector("textarea")).toBeNull();
});
it("uses the preview's configured instance instead of its Storybook host", async () => {
await act(async () => root.render(<SlackSetupPrompt instanceUrl="https://my-company.paperclip.app" />));
vi.mocked(copyTextToClipboard).mockResolvedValue(undefined);
- await act(async () => container.querySelector("button")!.click());
+ const dialog = await openPrompt();
+ expect(copyTextToClipboard).toHaveBeenCalledTimes(1);
expect(copyTextToClipboard).toHaveBeenCalledWith(buildSlackSetupPrompt("https://my-company.paperclip.app"));
});
+ it("ignores stale copy results when the prompt changes", async () => {
+ let finishCopy!: () => void;
+ vi.mocked(copyTextToClipboard).mockImplementationOnce(() => new Promise<void>((resolve) => { finishCopy = resolve; }));
+ const dialog = await openPrompt();
+ await copyPrompt(dialog);
+ await copyPrompt(dialog);
+ expect(copyTextToClipboard).toHaveBeenCalledTimes(1);
+ expect(dialog.querySelector(".agent-setup-copy")?.textContent).toBe("Copying…");
+ await act(async () => root.render(<SlackSetupPrompt instanceUrl="https://another.paperclip.app" />));
+ await act(async () => finishCopy());
+ expect(dialog.querySelector(".agent-setup-copy")?.textContent).toBe("Copy prompt");
+ expect(dialog.querySelector("pre")?.textContent).toContain("https://another.paperclip.app");
+ });
+
+ it("copies again on every opening", async () => {
+ vi.mocked(copyTextToClipboard).mockResolvedValue(undefined);
+ const dialog = await openPrompt();
+ await act(async () => dialog.querySelector<HTMLButtonElement>('[aria-label="Close agent setup"]')!.click());
+ expect(document.querySelector('[role="dialog"]')).toBeNull();
+ await act(async () => container.querySelector("button")!.click());
+ expect(document.querySelector(".agent-setup-copy")?.textContent).toBe("Copied to clipboard");
+ expect(copyTextToClipboard).toHaveBeenCalledTimes(2);
+ });
+
+ it("keeps the preview open when copying again from the trigger and does not copy on dismissal", async () => {
+ vi.mocked(copyTextToClipboard).mockResolvedValue(undefined);
+ const dialog = await openPrompt();
+ await act(async () => container.querySelector("button")!.click());
+ expect(document.querySelector('[role="dialog"]')).toBe(dialog);
+ expect(copyTextToClipboard).toHaveBeenCalledTimes(2);
+ await act(async () => dialog.querySelector<HTMLButtonElement>('[aria-label="Close agent setup"]')!.click());
+ expect(document.querySelector('[role="dialog"]')).toBeNull();
+ expect(copyTextToClipboard).toHaveBeenCalledTimes(2);
+ });
+
it("includes only the instance origin, without URL credentials or callback state", () => {
const prompt = buildSlackSetupPrompt("https://user:[email protected]/GIT/apps/chat/connect?code=private-code#private-state");
expect(prompt).toContain("Paperclip instance URL: https://my-company.paperclip.app\n");
diff --git a/ui/src/pages/apps/chat/SlackSetupPrompt.tsx b/ui/src/pages/apps/chat/SlackSetupPrompt.tsx
index 686492400c..5afc69b6e1 100644
--- a/ui/src/pages/apps/chat/SlackSetupPrompt.tsx
+++ b/ui/src/pages/apps/chat/SlackSetupPrompt.tsx
@@ -38,5 +38,5 @@ export function buildSlackSetupPrompt(instanceUrl: string) {
}
export function SlackSetupPrompt({ instanceUrl = window.location.origin }: { instanceUrl?: string }) {
- return <SetupPrompt prompt={buildSlackSetupPrompt(instanceUrl)} />;
+ return <SetupPrompt prompt={buildSlackSetupPrompt(instanceUrl)} description="Paste this into your agent to configure your Slack bot." />;
}
diff --git a/ui/src/pages/tools/McpConfigHelpDialog.test.tsx b/ui/src/pages/tools/McpConfigHelpDialog.test.tsx
index 1b6faba813..6b2e72fb4e 100644
--- a/ui/src/pages/tools/McpConfigHelpDialog.test.tsx
+++ b/ui/src/pages/tools/McpConfigHelpDialog.test.tsx
@@ -126,13 +126,14 @@ describe("Paste a config — MCP config help", () => {
await openHelp();
await act(async () => {
- buttonWithText("Copy prompt")!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ buttonWithText("Get a config with an agent")!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
});
await flushReact();
await flushReact();
- expect(copyTextToClipboardMock).toHaveBeenCalledWith(MCP_CONFIG_HELP_PROMPT);
- expect(document.body.textContent).toContain("Copied to clipboard.");
+ expect(copyTextToClipboardMock).toHaveBeenCalledExactlyOnceWith(MCP_CONFIG_HELP_PROMPT);
+ expect(document.querySelector('pre[aria-label="Setup prompt"]')?.textContent).toBe(MCP_CONFIG_HELP_PROMPT);
+ expect(document.body.textContent).toContain("Copied to clipboard");
});
it("tells the operator to copy by hand when the clipboard is unavailable", async () => {
@@ -141,14 +142,15 @@ describe("Paste a config — MCP config help", () => {
await openHelp();
await act(async () => {
- buttonWithText("Copy prompt")!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ buttonWithText("Get a config with an agent")!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
});
await flushReact();
await flushReact();
await vi.waitFor(() => {
- expect(document.body.textContent).toContain("select the text above and copy it");
+ expect(document.body.textContent).toContain("Select and copy the prompt above");
});
+ expect(document.querySelector<HTMLTextAreaElement>('textarea[aria-label="Setup prompt"]')?.value).toBe(MCP_CONFIG_HELP_PROMPT);
});
it("makes no connection or import request when opened or copied", async () => {
@@ -163,7 +165,7 @@ describe("Paste a config — MCP config help", () => {
await openHelp();
await act(async () => {
- buttonWithText("Copy prompt")!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ buttonWithText("Get a config with an agent")!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
});
await flushReact();
diff --git a/ui/src/pages/tools/McpConfigHelpDialog.tsx b/ui/src/pages/tools/McpConfigHelpDialog.tsx
index a5df2df149..49b935337e 100644
--- a/ui/src/pages/tools/McpConfigHelpDialog.tsx
+++ b/ui/src/pages/tools/McpConfigHelpDialog.tsx
@@ -1,5 +1,5 @@
-import { useEffect, useRef, useState } from "react";
-import { Check, Copy, HelpCircle } from "lucide-react";
+import { HelpCircle } from "lucide-react";
+import { AgentSetupPrompt } from "@/components/AgentSetupPrompt";
import { Button } from "@/components/ui/button";
import {
Dialog,
@@ -10,11 +10,8 @@ import {
DialogTrigger,
} from "@/components/ui/dialog";
import { Textarea } from "@/components/ui/textarea";
-import { copyTextToClipboard } from "@/lib/clipboard";
import { MCP_CONFIG_HELP_INSTRUCTIONS, MCP_CONFIG_HELP_PROMPT } from "@paperclipai/shared";
-const COPIED_RESET_MS = 2_000;
-
/**
* Compact question-mark help beside the Paste-a-config copy (PAP-17087, plan 3A).
*
@@ -24,33 +21,8 @@ const COPIED_RESET_MS = 2_000;
* anything the operator has typed.
*/
export function McpConfigHelpDialog() {
- const [open, setOpen] = useState(false);
- const [copyState, setCopyState] = useState<"idle" | "copied" | "failed">("idle");
- const resetTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
-
- useEffect(() => () => {
- if (resetTimer.current) clearTimeout(resetTimer.current);
- }, []);
-
- // Reset the copy affordance each time the dialog opens, so a stale "Copied"
- // from a previous visit never reads as confirmation of this one.
- useEffect(() => {
- if (open) setCopyState("idle");
- }, [open]);
-
- const copyPrompt = async () => {
- try {
- await copyTextToClipboard(MCP_CONFIG_HELP_PROMPT);
- setCopyState("copied");
- } catch {
- setCopyState("failed");
- }
- if (resetTimer.current) clearTimeout(resetTimer.current);
- resetTimer.current = setTimeout(() => setCopyState("idle"), COPIED_RESET_MS);
- };
-
return (
- <Dialog open={open} onOpenChange={setOpen}>
+ <Dialog>
<DialogTrigger asChild>
<Button
type="button"
@@ -92,20 +64,13 @@ export function McpConfigHelpDialog() {
/>
</div>
- <div className="flex flex-wrap items-center gap-3">
- <Button type="button" onClick={() => void copyPrompt()}>
- {copyState === "copied" ? <Check className="mr-2 h-4 w-4" /> : <Copy className="mr-2 h-4 w-4" />}
- Copy prompt
- </Button>
- {/* aria-live so a screen reader hears the outcome without moving focus
- off the button the operator just pressed. */}
- <span aria-live="polite" className="text-xs text-muted-foreground">
- {copyState === "copied"
- ? "Copied to clipboard."
- : copyState === "failed"
- ? "Couldn't copy automatically — select the text above and copy it."
- : null}
- </span>
+ <div>
+ <AgentSetupPrompt
+ prompt={MCP_CONFIG_HELP_PROMPT}
+ label="Get a config with an agent"
+ title="MCP configuration"
+ description="Paste this into your agent to create an MCP config, then paste its JSON reply back into Paperclip."
+ />
</div>
</DialogContent>
</Dialog>
diff --git a/ui/storybook/stories/agent-setup-prompt.stories.tsx b/ui/storybook/stories/agent-setup-prompt.stories.tsx
new file mode 100644
index 0000000000..8ee95576a4
--- /dev/null
+++ b/ui/storybook/stories/agent-setup-prompt.stories.tsx
@@ -0,0 +1,194 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, fn, userEvent, waitFor, within } from "storybook/test";
+import { MCP_CONFIG_HELP_PROMPT } from "@paperclipai/shared";
+import { BookOpen, KeyRound } from "lucide-react";
+import { AgentSetupPrompt } from "@/components/AgentSetupPrompt";
+import { Button } from "@/components/ui/button";
+import { Textarea } from "@/components/ui/textarea";
+import { buildSlackSetupPrompt, SlackSetupPrompt } from "@/pages/apps/chat/SlackSetupPrompt";
+import { GitHubSetupPrompt } from "@/pages/apps/chat/GitHubSetupPrompt";
+import { McpConfigHelpDialog } from "@/pages/tools/McpConfigHelpDialog";
+import { AgentInstructions } from "@/components/routine-triggers/WebhookFields";
+import { IssueContinuationHandoff } from "@/components/IssueContinuationHandoff";
+import { webhookAgentInstructions } from "../fixtures/routineTriggerWizard";
+import { storybookContinuationHandoff } from "../fixtures/paperclipData";
+
+const slackPrompt = buildSlackSetupPrompt(import.meta.env.VITE_PAPERCLIP_INSTANCE_URL ?? "");
+const apiPrompt = `Help me connect my agent to the Paperclip API.
+
+First, ask me for my Paperclip instance URL if it is not already available. Read its API documentation and identify the company and agent I want to use.
+
+Guide me through creating a dedicated agent API key. Store it securely in my agent's environment; do not paste it into code, logs, or chat.
+
+Configure the base URL and authentication, then verify the connection with a read-only request. Show me what worked and ask before making any changes to my company.`;
+
+const meta = {
+ title: "Components/Agent setup prompt",
+ component: AgentSetupPrompt,
+ parameters: {
+ layout: "fullscreen",
+ docs: { description: { component: "A reusable handoff to an agent. Hover or focus to fan out the logos, click once to copy the prompt and open its preview. Logos travel into the preview; clipboard success stays in place. Supports reduced motion, keyboard dismissal, and manual copying when clipboard access fails. The default story copies the complete production Slack setup prompt." } },
+ },
+ args: {
+ prompt: slackPrompt,
+ title: "Agent setup",
+ description: "Paste this into your agent to configure your Slack bot.",
+ label: "Set up with an agent",
+ side: "top",
+ align: "start",
+ variant: "outline",
+ },
+ argTypes: {
+ variant: { control: "select", options: ["outline", "ghost"] },
+ side: { control: "select", options: ["top", "bottom", "left", "right"] },
+ align: { control: "select", options: ["start", "center", "end"] },
+ },
+ render: (args) => <div className="flex min-h-screen items-center justify-center p-6"><AgentSetupPrompt {...args} /></div>,
+} satisfies Meta<typeof AgentSetupPrompt>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+ parameters: { layout: "fullscreen" },
+ render: (args) => (
+ <div className="mx-auto flex min-h-screen w-full max-w-xl flex-col justify-center gap-8 p-6">
+ <div className="flex flex-col gap-3">
+ <span className="text-xs font-medium uppercase tracking-widest text-muted-foreground">A little help with setup</span>
+ <h1 className="text-3xl font-semibold tracking-tight">Let your agent handle it.</h1>
+ <p className="max-w-md text-sm leading-relaxed text-muted-foreground">Give your agent the instructions. Get back to what you were building.</p>
+ </div>
+ <div className="flex flex-col gap-6 rounded-xl border border-border bg-card p-6">
+ <div className="flex items-start gap-3">
+ <div className="flex size-10 shrink-0 items-center justify-center rounded-lg bg-muted">
+ <img src="/brands/apps/slack.svg" alt="" className="size-6" />
+ </div>
+ <div className="flex flex-col gap-1">
+ <h2 className="text-base font-medium">Connect Slack</h2>
+ <p className="text-sm leading-relaxed text-muted-foreground">Bring your Paperclip agent into your workspace.</p>
+ </div>
+ </div>
+ <div><AgentSetupPrompt {...args} /></div>
+ </div>
+ <p className="text-xs text-muted-foreground">Hover the logos. Click once to copy and preview.</p>
+ </div>
+ ),
+};
+
+export const ButtonOnly: Story = {};
+export const OpenPreview: Story = {
+ play: async ({ canvasElement }) => {
+ await userEvent.click(within(canvasElement).getByRole("button", { name: "Set up with an agent" }));
+ await expect(within(canvasElement.ownerDocument.body).getByRole("dialog", { name: "Agent setup" })).toBeVisible();
+ },
+};
+export const Light: Story = { ...Playground, globals: { theme: "light" } };
+export const Mobile: Story = {
+ ...Playground,
+ globals: { viewport: { value: "mobile1", isRotated: false } },
+};
+export const ApiSetup: Story = {
+ args: { prompt: apiPrompt, description: "Paste this into your agent to configure the API.", label: "Configure with an agent" },
+};
+export const ClipboardCheck: Story = {
+ render: (args) => (
+ <div className="mx-auto flex min-h-screen w-full max-w-lg flex-col justify-center gap-4 p-6">
+ <div><AgentSetupPrompt {...args} /></div>
+ <label htmlFor="clipboard-check" className="text-sm text-muted-foreground">Click the setup button, then paste here to check the full text.</label>
+ <Textarea id="clipboard-check" placeholder="Paste the copied prompt here" rows={8} className="font-mono text-xs" />
+ </div>
+ ),
+};
+export const QuickAccess: Story = {
+ args: { prompt: apiPrompt, description: "Paste this into your agent to configure the API.", variant: "ghost", label: "Agent setup" },
+ render: (args) => (
+ <div className="flex min-h-screen items-center p-6">
+ <div className="flex w-64 flex-col gap-1 rounded-xl border border-border bg-card p-2">
+ <p className="px-3 py-2 text-xs text-muted-foreground">Quick access</p>
+ <Button variant="ghost" className="justify-start" disabled><KeyRound />API key</Button>
+ <AgentSetupPrompt {...args} />
+ <Button variant="ghost" className="justify-start" disabled><BookOpen />Documentation</Button>
+ </div>
+ </div>
+ ),
+};
+
+export const ClipboardUnavailable: Story = {
+ beforeEach: () => {
+ const clipboard = Object.getOwnPropertyDescriptor(navigator, "clipboard");
+ const execCommand = Object.getOwnPropertyDescriptor(document, "execCommand");
+ Object.defineProperty(navigator, "clipboard", { configurable: true, value: { writeText: async () => { throw new Error("Clipboard disabled for this story"); } } });
+ Object.defineProperty(document, "execCommand", { configurable: true, value: () => false });
+ return () => {
+ if (clipboard) Object.defineProperty(navigator, "clipboard", clipboard);
+ else Reflect.deleteProperty(navigator, "clipboard");
+ if (execCommand) Object.defineProperty(document, "execCommand", execCommand);
+ else Reflect.deleteProperty(document, "execCommand");
+ };
+ },
+ play: async ({ canvasElement }) => {
+ const body = within(canvasElement.ownerDocument.body);
+ await userEvent.click(within(canvasElement).getByRole("button", { name: "Set up with an agent" }));
+ await expect(body.getByRole("alert")).toHaveTextContent("Could not copy automatically");
+ await expect(body.getByRole("textbox", { name: "Setup prompt" })).toHaveValue(slackPrompt);
+ },
+};
+
+export const AppPlacements: Story = {
+ render: () => (
+ <div className="mx-auto flex min-h-screen w-full max-w-2xl flex-col gap-8 p-6">
+ <div className="space-y-2">
+ <h1 className="text-2xl font-semibold">Hand it to your agent</h1>
+ <p className="text-sm text-muted-foreground">The same one-click handoff across the app. These are the production controls, with sample data for webhooks and task continuation.</p>
+ </div>
+ <section className="space-y-3">
+ <h2 className="text-sm font-medium">Slack connection</h2>
+ <SlackSetupPrompt instanceUrl={import.meta.env.VITE_PAPERCLIP_INSTANCE_URL ?? ""} />
+ </section>
+ <section className="space-y-3">
+ <h2 className="text-sm font-medium">GitHub connection</h2>
+ <GitHubSetupPrompt instanceUrl={import.meta.env.VITE_PAPERCLIP_INSTANCE_URL ?? ""} />
+ </section>
+ <section className="space-y-3">
+ <div className="flex items-center gap-2">
+ <h2 className="text-sm font-medium">MCP configuration help</h2>
+ <McpConfigHelpDialog />
+ </div>
+ </section>
+ <AgentInstructions value={webhookAgentInstructions("github")} />
+ <IssueContinuationHandoff document={storybookContinuationHandoff} />
+ </div>
+ ),
+};
+
+export const InsideMcpHelp: Story = {
+ render: () => <div className="p-6"><McpConfigHelpDialog /></div>,
+ play: async ({ canvasElement }) => {
+ const body = within(canvasElement.ownerDocument.body);
+ // Synthetic play events lack clipboard user activation in some browsers.
+ // Restore the real clipboard after the assertions for manual exploration.
+ const clipboard = Object.getOwnPropertyDescriptor(navigator, "clipboard");
+ const writeText = fn().mockResolvedValue(undefined);
+ Object.defineProperty(navigator, "clipboard", { configurable: true, value: { writeText } });
+ try {
+ await userEvent.click(within(canvasElement).getByRole("button", { name: "Get help creating an MCP config" }));
+ const trigger = await body.findByRole("button", { name: "Get a config with an agent" });
+ await userEvent.click(trigger);
+ await waitFor(async () => {
+ await expect(body.getByRole("dialog", { name: "MCP configuration" })).toBeVisible();
+ await expect(body.getByRole("button", { name: "Copied to clipboard" })).toHaveFocus();
+ await expect(writeText).toHaveBeenCalledTimes(1);
+ await expect(writeText).toHaveBeenCalledWith(MCP_CONFIG_HELP_PROMPT);
+ });
+ await userEvent.keyboard("{Escape}");
+ await waitFor(async () => {
+ await expect(body.queryByRole("dialog", { name: "MCP configuration" })).not.toBeInTheDocument();
+ await expect(body.getByRole("dialog", { name: "Ask an agent for an MCP config" })).toBeVisible();
+ await expect(trigger).toHaveFocus();
+ await expect(writeText).toHaveBeenCalledTimes(1);
+ });
+ } finally {
+ if (clipboard) Object.defineProperty(navigator, "clipboard", clipboard);
+ else Reflect.deleteProperty(navigator, "clipboard");
+ }
+ },
+};
diff --git a/ui/storybook/stories/slack-setup-prompt.stories.tsx b/ui/storybook/stories/slack-setup-prompt.stories.tsx
index fa1aad37b9..7577222e85 100644
--- a/ui/storybook/stories/slack-setup-prompt.stories.tsx
+++ b/ui/storybook/stories/slack-setup-prompt.stories.tsx
@@ -10,7 +10,7 @@ const meta = {
component: SlackSetupPrompt,
parameters: {
layout: "padded",
- docs: { description: { component: "Production copy button and full browser-agent prompt. The surrounding agent selection is a static placement preview; it does not create a connection. Configure PAPERCLIP_STORYBOOK_API_URL to include a real instance origin in copied instructions. Otherwise the prompt asks for the instance URL." } },
+ docs: { description: { component: "Production animated setup button, prompt preview, and clipboard feedback. The surrounding agent selection is a static placement preview; it does not create a connection. Configure PAPERCLIP_STORYBOOK_API_URL to include a real instance origin in copied instructions. Otherwise the prompt asks for the instance URL." } },
},
args: { instanceUrl },
} satisfies Meta<typeof SlackSetupPrompt>;