@eventcatalog/core 5.0.0-beta.4 → 5.0.0-beta.6

package/eventcatalog/src/features/studio/components/Comments.tsx

@@ -0,0 +1,455 @@
+import { memo, useEffect, useRef, useState, type ReactNode } from 'react';
+import { useInternalNode, useReactFlow, useStore, ViewportPortal, type Node, type XYPosition } from '@xyflow/react';
+import { Check, MessageCircle, RotateCcw, Trash2, X } from 'lucide-react';
+import { getAbsolutePosition } from '../grouping';
+import type { Author, CommentAnchor, Thread } from '../hooks/use-comments';
+import { STATUS } from './status';
+
+const initials = (name: string) => name.slice(0, 2).toUpperCase();
+
+const timeAgo = (timestamp: number) => {
+  const seconds = Math.round((Date.now() - timestamp) / 1000);
+  if (seconds < 60) return 'just now';
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  return new Date(timestamp).toLocaleDateString();
+};
+
+/** Where a pin sits on the canvas: on its node (so it moves with it), or where it was dropped */
+export const getAnchorPosition = (anchor: CommentAnchor, nodesById: Map<string, Node>): XYPosition => {
+  const node = anchor.nodeId ? nodesById.get(anchor.nodeId) : undefined;
+  if (!node || !anchor.offset) return anchor.position;
+  // Nodes in containers are positioned relative to them
+  const position = getAbsolutePosition(node, nodesById);
+  return { x: position.x + anchor.offset.x, y: position.y + anchor.offset.y };
+};
+
+/** Pinned to a node, a comment keeps its offset from the node so it moves with it */
+export const anchorAt = (position: XYPosition, node?: Node, nodesById?: Map<string, Node>): CommentAnchor => {
+  if (!node) return { position };
+  const nodePosition = getAbsolutePosition(node, nodesById ?? new Map([[node.id, node]]));
+  return { position, nodeId: node.id, offset: { x: position.x - nodePosition.x, y: position.y - nodePosition.y } };
+};
+
+const DRAG_THRESHOLD_PX = 4;
+
+const panelClass =
+  'nowheel nodrag nopan absolute z-40 w-72 rounded-xl border shadow-xl bg-[rgb(var(--ec-card-bg))] border-[rgb(var(--ec-page-border))] text-[rgb(var(--ec-page-text))]';
+
+/**
+ * A comment pin. Click opens it, dragging moves it: `onDrag` gets the screen point the pin's tip
+ * (its bottom left corner) is over, keeping where on the pin it was grabbed.
+ */
+function Pin({
+  author,
+  active,
+  resolved,
+  onClick,
+  onDrag,
+}: {
+  author: Author;
+  active?: boolean;
+  resolved?: boolean;
+  onClick?: () => void;
+  onDrag?: (tip: XYPosition, phase: 'move' | 'end') => void;
+}) {
+  const drag = useRef<{ start: XYPosition; grab: XYPosition; moved: boolean } | null>(null);
+  const tipOf = (event: { clientX: number; clientY: number }) => ({
+    x: event.clientX - drag.current!.grab.x,
+    y: event.clientY - drag.current!.grab.y,
+  });
+
+  return (
+    <button
+      onPointerDown={(event) => {
+        if (event.button !== 0) return;
+        // Keeps pointer events coming while the pointer is outside the pin (throws if the pointer has gone)
+        try {
+          event.currentTarget.setPointerCapture(event.pointerId);
+        } catch {}
+        const rect = event.currentTarget.getBoundingClientRect();
+        drag.current = {
+          start: { x: event.clientX, y: event.clientY },
+          grab: { x: event.clientX - rect.left, y: event.clientY - rect.bottom },
+          moved: false,
+        };
+      }}
+      onPointerMove={(event) => {
+        const current = drag.current;
+        if (!current || !onDrag) return;
+        const distance = Math.hypot(event.clientX - current.start.x, event.clientY - current.start.y);
+        if (!current.moved && distance < DRAG_THRESHOLD_PX) return;
+        current.moved = true;
+        onDrag(tipOf(event), 'move');
+      }}
+      onPointerUp={(event) => {
+        const current = drag.current;
+        if (!current) return;
+        if (current.moved) onDrag?.(tipOf(event), 'end');
+        else onClick?.();
+        drag.current = null;
+      }}
+      onPointerCancel={() => (drag.current = null)}
+      // Keyboard activation (pointer clicks are handled on pointer up)
+      onClick={(event) => event.detail === 0 && onClick?.()}
+      className={`flex h-8 w-8 cursor-grab items-center justify-center rounded-full rounded-bl-none border-2 border-[rgb(var(--ec-card-bg))] text-[11px] font-semibold text-white shadow-md transition-transform hover:scale-110 active:cursor-grabbing ${
+        active ? 'scale-110 ring-2 ring-[rgb(var(--ec-accent))]' : ''
+      }`}
+      // Resolved threads are greyed out, in the theme's muted colour
+      style={{ backgroundColor: resolved ? 'rgb(var(--ec-page-text-muted))' : author.color }}
+    >
+      {initials(author.name)}
+    </button>
+  );
+}
+
+function Composer({
+  placeholder,
+  onSubmit,
+  onCancel,
+}: {
+  placeholder: string;
+  onSubmit: (text: string) => void;
+  onCancel?: () => void;
+}) {
+  const [text, setText] = useState('');
+  const submit = () => {
+    if (!text.trim()) return;
+    onSubmit(text.trim());
+    setText('');
+  };
+
+  return (
+    <div className="flex items-end gap-2 p-2">
+      <textarea
+        autoFocus
+        rows={1}
+        value={text}
+        placeholder={placeholder}
+        onChange={(e) => setText(e.target.value)}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter' && !e.shiftKey) {
+            e.preventDefault();
+            submit();
+          }
+          if (e.key === 'Escape') onCancel?.();
+        }}
+        className="max-h-32 min-h-[34px] flex-1 resize-none rounded-md border px-2 py-1.5 text-sm bg-[rgb(var(--ec-input-bg))] border-[rgb(var(--ec-input-border))] text-[rgb(var(--ec-input-text))]"
+      />
+      <button
+        onClick={submit}
+        disabled={!text.trim()}
+        className="rounded-md px-2.5 py-1.5 text-xs font-medium disabled:opacity-40 bg-[rgb(var(--ec-button-bg))] text-[rgb(var(--ec-button-text))]"
+      >
+        Post
+      </button>
+    </div>
+  );
+}
+
+function IconButton({ title, onClick, children }: { title: string; onClick: () => void; children: ReactNode }) {
+  return (
+    <button
+      title={title}
+      onClick={onClick}
+      className="rounded p-1 text-[rgb(var(--ec-icon-color))] hover:bg-[rgb(var(--ec-page-border)/0.5)] hover:text-[rgb(var(--ec-icon-hover))]"
+    >
+      {children}
+    </button>
+  );
+}
+
+function ThreadPopover({
+  thread,
+  onReply,
+  onResolve,
+  onDelete,
+  onClose,
+}: {
+  thread: Thread;
+  onReply: (text: string) => void;
+  onResolve: (resolved: boolean) => void;
+  onDelete: () => void;
+  onClose: () => void;
+}) {
+  const listRef = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    listRef.current?.scrollTo({ top: listRef.current.scrollHeight });
+  }, [thread.messages.length]);
+
+  return (
+    <>
+      <div className="flex items-center justify-between border-b px-3 py-2 border-[rgb(var(--ec-page-border))]">
+        <span className="text-xs font-semibold">{thread.resolved ? 'Resolved thread' : 'Thread'}</span>
+        <span className="flex items-center gap-0.5">
+          <IconButton title={thread.resolved ? 'Reopen' : 'Resolve'} onClick={() => onResolve(!thread.resolved)}>
+            {thread.resolved ? <RotateCcw size={14} /> : <Check size={14} />}
+          </IconButton>
+          <IconButton title="Delete thread" onClick={onDelete}>
+            <Trash2 size={14} />
+          </IconButton>
+          <IconButton title="Close" onClick={onClose}>
+            <X size={14} />
+          </IconButton>
+        </span>
+      </div>
+      <div ref={listRef} className="max-h-72 space-y-3 overflow-y-auto px-3 py-3">
+        {thread.messages.map((message) => (
+          <div key={message.id} className="flex gap-2">
+            <span
+              className="flex h-6 w-6 shrink-0 items-center justify-center rounded-full text-[10px] font-semibold text-white"
+              style={{ backgroundColor: message.author.color }}
+            >
+              {initials(message.author.name)}
+            </span>
+            <div className="min-w-0">
+              <p className="text-xs">
+                <span className="font-semibold">{message.author.name}</span>{' '}
+                <span className="text-[rgb(var(--ec-page-text-muted))]">{timeAgo(message.createdAt)}</span>
+              </p>
+              <p className="whitespace-pre-wrap break-words text-sm">{message.text}</p>
+            </div>
+          </div>
+        ))}
+      </div>
+      <div className="border-t border-[rgb(var(--ec-page-border))]">
+        <Composer placeholder="Reply" onSubmit={onReply} onCancel={onClose} />
+      </div>
+    </>
+  );
+}
+
+/** Where a pin goes on the canvas, following only the node it's on (if it's on one), counter-scaled */
+function PinAt({ anchor, zoom, zIndex, children }: { anchor: CommentAnchor; zoom: number; zIndex: number; children: ReactNode }) {
+  const node = useInternalNode(anchor.nodeId ?? '');
+  const origin = anchor.nodeId && anchor.offset ? node?.internals.positionAbsolute : undefined;
+  const { x, y } = origin && anchor.offset ? { x: origin.x + anchor.offset.x, y: origin.y + anchor.offset.y } : anchor.position;
+  return (
+    <div className="absolute" style={{ left: x, top: y, transform: `scale(${1 / zoom})`, transformOrigin: '0 0', zIndex }}>
+      {/* The pin's tip (bottom left corner) sits on the anchor point */}
+      <div className="nopan nodrag nowheel pointer-events-auto absolute left-0 -top-8">{children}</div>
+    </div>
+  );
+}
+
+/**
+ * Comment pins (and the open thread) on the canvas, in its own coordinates (React Flow's viewport portal) so
+ * they move with it without re-rendering, counter-scaled to stay the same size on screen. Each pin follows
+ * only its own node, so other nodes moving don't re-render them.
+ */
+export const CommentLayer = memo(function CommentLayer({
+  threads,
+  author,
+  openThreadId,
+  draft,
+  showResolved,
+  onOpen,
+  onCreate,
+  onCancelDraft,
+  onReply,
+  onResolve,
+  onDelete,
+  onMove,
+  onMoveDraft,
+}: {
+  threads: Thread[];
+  author: Author;
+  openThreadId: string | null;
+  draft: CommentAnchor | null;
+  showResolved: boolean;
+  onOpen: (threadId: string | null) => void;
+  onCreate: (text: string) => void;
+  onCancelDraft: () => void;
+  onReply: (threadId: string, text: string) => void;
+  onResolve: (threadId: string, resolved: boolean) => void;
+  onDelete: (threadId: string) => void;
+  onMove: (threadId: string, anchor: CommentAnchor) => void;
+  onMoveDraft: (anchor: CommentAnchor) => void;
+}) {
+  const zoom = useStore((state) => state.transform[2]);
+  const { screenToFlowPosition, getInternalNode } = useReactFlow();
+  // A pin being dragged stays here until it's dropped, then moves for everyone
+  const [moving, setMoving] = useState<{ threadId: string; anchor: CommentAnchor } | null>(null);
+
+  // While dragging, a pin follows the pointer. Dropped on a node it attaches to it (and moves with it),
+  // anywhere else it stays on the canvas.
+  const nodeUnder = (point: XYPosition) => {
+    const element = document.elementsFromPoint(point.x, point.y).find((el) => el.closest('.react-flow__node'));
+    const id = element?.closest('.react-flow__node')?.getAttribute('data-id');
+    return id ? getInternalNode(id) : undefined;
+  };
+  const anchorFor = (tip: XYPosition, phase: 'move' | 'end'): CommentAnchor => {
+    const position = screenToFlowPosition(tip);
+    const node = phase === 'end' ? nodeUnder(tip) : undefined;
+    if (!node) return { position };
+    const origin = node.internals.positionAbsolute;
+    return { position, nodeId: node.id, offset: { x: position.x - origin.x, y: position.y - origin.y } };
+  };
+
+  const visible = threads.filter((thread) => showResolved || !thread.resolved || thread.id === openThreadId);
+
+  return (
+    <ViewportPortal>
+      {/* Above nodes (selected ones are raised to 1000) and other people's pointers */}
+      <div className="absolute left-0 top-0" style={{ zIndex: 2001 }}>
+        {visible.map((thread) => {
+          const isOpen = thread.id === openThreadId;
+          return (
+            <PinAt
+              key={thread.id}
+              anchor={moving?.threadId === thread.id ? moving.anchor : thread}
+              zoom={zoom}
+              zIndex={isOpen ? 2 : 1}
+            >
+              <Pin
+                author={thread.author}
+                active={isOpen}
+                resolved={thread.resolved}
+                onClick={() => onOpen(isOpen ? null : thread.id)}
+                onDrag={(tip, phase) => {
+                  if (phase === 'move') return setMoving({ threadId: thread.id, anchor: anchorFor(tip, phase) });
+                  onMove(thread.id, anchorFor(tip, phase));
+                  setMoving(null);
+                }}
+              />
+              {isOpen && (
+                <div className={panelClass} style={{ left: 40, top: 0 }}>
+                  <ThreadPopover
+                    thread={thread}
+                    onReply={(text) => onReply(thread.id, text)}
+                    onResolve={(resolved) => onResolve(thread.id, resolved)}
+                    onDelete={() => onDelete(thread.id)}
+                    onClose={() => onOpen(null)}
+                  />
+                </div>
+              )}
+            </PinAt>
+          );
+        })}
+
+        {draft && (
+          <PinAt anchor={draft} zoom={zoom} zIndex={3}>
+            <Pin author={author} active onDrag={(tip, phase) => onMoveDraft(anchorFor(tip, phase))} />
+            <div className={panelClass} style={{ left: 40, top: 0 }}>
+              <Composer placeholder="Add a comment" onSubmit={onCreate} onCancel={onCancelDraft} />
+            </div>
+          </PinAt>
+        )}
+      </div>
+    </ViewportPortal>
+  );
+});
+
+export type ContextMenuState = { x: number; y: number; flowPosition: XYPosition; node?: Node } | null;
+
+export const CanvasContextMenu = memo(function CanvasContextMenu({
+  menu,
+  onAddComment,
+  onDeleteNode,
+  onClose,
+}: {
+  menu: ContextMenuState;
+  onAddComment: () => void;
+  onDeleteNode: (id: string) => void;
+  onClose: () => void;
+}) {
+  useEffect(() => {
+    if (!menu) return;
+    const close = (event: Event) => {
+      if (event instanceof KeyboardEvent && event.key !== 'Escape') return;
+      onClose();
+    };
+    window.addEventListener('pointerdown', close);
+    window.addEventListener('keydown', close);
+    window.addEventListener('wheel', close);
+    return () => {
+      window.removeEventListener('pointerdown', close);
+      window.removeEventListener('keydown', close);
+      window.removeEventListener('wheel', close);
+    };
+  }, [menu, onClose]);
+
+  if (!menu) return null;
+
+  const itemClass =
+    'flex w-full items-center gap-2 rounded px-2.5 py-1.5 text-left text-xs hover:bg-[rgb(var(--ec-page-border)/0.5)]';
+
+  return (
+    <div
+      // Keep the window pointerdown listener from closing the menu before a click lands
+      onPointerDown={(e) => e.stopPropagation()}
+      className="fixed z-50 w-44 rounded-lg border p-1 shadow-xl bg-[rgb(var(--ec-card-bg))] border-[rgb(var(--ec-page-border))] text-[rgb(var(--ec-page-text))]"
+      style={{ left: menu.x, top: menu.y }}
+    >
+      <button className={itemClass} onClick={onAddComment}>
+        <MessageCircle size={14} />
+        Add comment
+        <span className="ml-auto text-[rgb(var(--ec-page-text-muted))]">C</span>
+      </button>
+      {menu.node && (
+        <button className={`${itemClass} ${STATUS.danger.text}`} onClick={() => onDeleteNode(menu.node!.id)}>
+          <Trash2 size={14} />
+          Delete
+        </button>
+      )}
+    </div>
+  );
+});
+
+/** All threads, for the left panel. Clicking one opens it on the canvas. */
+export function CommentList({
+  threads,
+  showResolved,
+  onToggleResolved,
+  onOpen,
+}: {
+  threads: Thread[];
+  showResolved: boolean;
+  onToggleResolved: () => void;
+  onOpen: (thread: Thread) => void;
+}) {
+  const shown = threads.filter((thread) => showResolved || !thread.resolved).reverse();
+
+  return (
+    <div className="flex min-h-0 flex-1 flex-col">
+      <label className="mx-3 mb-2 flex items-center gap-2 text-xs text-[rgb(var(--ec-page-text-muted))]">
+        <input type="checkbox" checked={showResolved} onChange={onToggleResolved} />
+        Show resolved
+      </label>
+      <div className="min-h-0 flex-1 space-y-1.5 overflow-y-auto px-3 pb-3">
+        {shown.length === 0 && (
+          <p className="py-6 text-center text-xs text-[rgb(var(--ec-page-text-muted))]">
+            No comments yet. Right click the canvas, or press C, to add one.
+          </p>
+        )}
+        {shown.map((thread) => {
+          const [first, ...replies] = thread.messages;
+          return (
+            <button
+              key={thread.id}
+              onClick={() => onOpen(thread)}
+              className={`w-full space-y-1 rounded-md border px-2.5 py-2 text-left bg-[rgb(var(--ec-page-bg))] border-[rgb(var(--ec-page-border))] hover:border-[rgb(var(--ec-accent))] ${
+                thread.resolved ? 'opacity-60' : ''
+              }`}
+            >
+              <p className="flex items-center gap-1.5 text-xs">
+                <span className="h-2 w-2 shrink-0 rounded-full" style={{ backgroundColor: thread.author.color }} />
+                <span className="font-semibold">{thread.author.name}</span>
+                <span className="text-[rgb(var(--ec-page-text-muted))]">{timeAgo(thread.createdAt)}</span>
+                {thread.resolved && <Check size={12} className={`ml-auto ${STATUS.success.text}`} />}
+              </p>
+              <p className="line-clamp-2 text-xs">{first?.text}</p>
+              {replies.length > 0 && (
+                <p className="text-[11px] text-[rgb(var(--ec-page-text-muted))]">
+                  {replies.length} {replies.length === 1 ? 'reply' : 'replies'}
+                </p>
+              )}
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

package/eventcatalog/src/features/studio/components/ConnectAgentDialog.tsx

@@ -0,0 +1,217 @@
+import { useEffect, useState, type ReactNode } from 'react';
+import { Bot, Check, Copy, X } from 'lucide-react';
+import type { WebMcpStatus } from '../hooks/use-canvas-webmcp';
+import { STATUS } from './status';
+
+type CanvasLink = { canvasId: string; title?: string; canvasUrl: string; mcpUrl: string };
+
+export const RELAY_COMMAND = 'npx -y @mcp-b/webmcp-local-relay@5.1.0';
+const RELAY_KEY = 'eventcatalog-webmcp-relay';
+const WEBMCP_KEY = 'eventcatalog-webmcp';
+
+const isOn = (key: string) => {
+  try {
+    return localStorage.getItem(key) === 'true';
+  } catch {
+    return false;
+  }
+};
+const turnOn = (key: string) => {
+  try {
+    localStorage.setItem(key, 'true');
+  } catch {}
+};
+
+/**
+ * WebMCP through the polyfill (for browsers without WebMCP of their own) is opt in, remembered in this browser:
+ * the polyfill watches every change to the page, which on a canvas is every drag and pan. The relay needs it.
+ */
+export const isWebMcpEnabled = () => isOn(WEBMCP_KEY) || isOn(RELAY_KEY);
+export const enableWebMcp = () => turnOn(WEBMCP_KEY);
+
+/**
+ * The WebMCP local relay hands this tab's tools to desktop agents. Opt in: its script keeps looking for a
+ * relay on localhost, so it only loads once someone turns it on (remembered in this browser).
+ */
+export const isRelayEnabled = () => isOn(RELAY_KEY);
+
+export const loadRelay = (scriptPath: string) => {
+  if (document.querySelector('script[data-webmcp-relay-embed]')) return;
+  const script = document.createElement('script');
+  script.src = scriptPath;
+  script.dataset.webmcpRelayEmbed = '';
+  script.dataset.relayPort = '9333';
+  document.body.appendChild(script);
+};
+
+const enableRelay = (scriptPath: string) => {
+  turnOn(RELAY_KEY);
+  loadRelay(scriptPath);
+};
+
+/**
+ * The prompt people give their agent to join this canvas. It works out how to connect from what the agent
+ * can do: the EventCatalog MCP server (and openCanvas in chats that show MCP Apps), WebMCP in the open tab,
+ * or the WebMCP local relay for desktop agents.
+ */
+export const buildAgentPrompt = ({ canvasId, title, canvasUrl, mcpUrl }: CanvasLink) =>
+  `Join me on an EventCatalog canvas so we can design this together, live.
+
+Canvas: ${title ? `"${title}"` : 'Untitled'}
+Canvas id: ${canvasId}
+Link: ${canvasUrl}
+
+Connect with the first of these you can use:
+
+1. EventCatalog MCP server (Streamable HTTP): ${mcpUrl}
+   - If you already have it (tools like getCanvas, addToCanvas), use them with canvasId "${canvasId}".
+   - If not and you can add MCP servers, add it. For example, in Claude Code: claude mcp add --transport http eventcatalog ${mcpUrl}
+   - If you can show MCP Apps in this chat (e.g. ChatGPT, Claude), call openCanvas with canvasId "${canvasId}" so I can work on the canvas with you right here.
+2. WebMCP: if you can use tools from my browser tab, I have the canvas open there and it offers tools like get_canvas, add_to_canvas and add_comment.
+3. WebMCP local relay: if you run on my computer (e.g. Claude Code, Cursor) and can't reach the MCP server, add the MCP server \`${RELAY_COMMAND}\`. It gives you the tools of my open canvas tab.
+
+Once connected:
+- Read the canvas first (getCanvas / get_canvas) and tell me who else is on it.
+- Ask me what we are designing, then work on the canvas as we talk: add catalog resources (find them with getResources / search_catalog), add new components for things that don't exist yet, and connect them. Leave out positions so new nodes go next to what they connect to; only re-lay the whole canvas (layoutCanvas / layout_canvas) when I ask.
+- Leave questions and suggestions as comments on the canvas, and reply to comments people leave for you.
+- Pass agentName with your name on MCP tools, so people on the canvas can see who you are.`;
+
+function CopyButton({ text, label = 'Copy' }: { text: string; label?: string }) {
+  const [copied, setCopied] = useState(false);
+  return (
+    <button
+      onClick={async () => {
+        await navigator.clipboard.writeText(text);
+        setCopied(true);
+        setTimeout(() => setCopied(false), 1500);
+      }}
+      className="flex shrink-0 items-center gap-1.5 rounded-md px-2.5 py-1.5 text-xs font-medium bg-[rgb(var(--ec-button-bg))] text-[rgb(var(--ec-button-text))]"
+    >
+      {copied ? <Check size={14} /> : <Copy size={14} />}
+      {copied ? 'Copied' : label}
+    </button>
+  );
+}
+
+function Detail({ title, value, children }: { title: string; value?: string; children: ReactNode }) {
+  return (
+    <div className="space-y-1.5">
+      <h3 className="text-xs font-semibold">{title}</h3>
+      <p className="text-xs text-[rgb(var(--ec-page-text-muted))]">{children}</p>
+      {value && (
+        <div className="flex items-center gap-2">
+          <code className="min-w-0 flex-1 truncate rounded-md border px-2 py-1.5 text-xs bg-[rgb(var(--ec-input-bg))] border-[rgb(var(--ec-input-border))]">
+            {value}
+          </code>
+          <CopyButton text={value} />
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default function ConnectAgentDialog({
+  link,
+  webMcp,
+  relayScriptPath,
+  onEnableWebMcp,
+  onClose,
+}: {
+  link: CanvasLink;
+  webMcp: WebMcpStatus;
+  /** Turn WebMCP on for this tab (through the polyfill, when the browser has none) */
+  onEnableWebMcp: () => void;
+  /** Where the relay's script is served (only on EventCatalog's own canvas page) */
+  relayScriptPath?: string;
+  onClose: () => void;
+}) {
+  const prompt = buildAgentPrompt(link);
+  const [relayOn, setRelayOn] = useState(isRelayEnabled);
+
+  useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent) => event.key === 'Escape' && onClose();
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+  }, [onClose]);
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/40 p-4" onClick={onClose}>
+      <div
+        role="dialog"
+        aria-label="Connect your agent"
+        onClick={(event) => event.stopPropagation()}
+        className="flex max-h-full w-full max-w-2xl flex-col rounded-xl border shadow-2xl bg-[rgb(var(--ec-card-bg))] border-[rgb(var(--ec-page-border))] text-[rgb(var(--ec-page-text))]"
+      >
+        <div className="flex items-start justify-between gap-4 border-b p-5 border-[rgb(var(--ec-page-border))]">
+          <div className="space-y-1">
+            <h2 className="flex items-center gap-2 text-base font-semibold">
+              <Bot size={18} />
+              Connect your agent
+            </h2>
+            <p className="text-sm text-[rgb(var(--ec-page-text-muted))]">
+              Give this prompt to your agent (Claude, ChatGPT, Codex, Cursor...). It joins this canvas and works on it with you,
+              live, using whatever it can connect with.
+            </p>
+          </div>
+          <button
+            onClick={onClose}
+            aria-label="Close"
+            className="rounded p-1 text-[rgb(var(--ec-icon-color))] hover:bg-[rgb(var(--ec-page-border)/0.5)]"
+          >
+            <X size={16} />
+          </button>
+        </div>
+
+        <div className="min-h-0 space-y-5 overflow-y-auto p-5">
+          <div className="space-y-2">
+            <div className="flex items-center justify-between">
+              <h3 className="text-xs font-semibold uppercase tracking-wide text-[rgb(var(--ec-page-text-muted))]">Prompt</h3>
+              <CopyButton text={prompt} label="Copy prompt" />
+            </div>
+            <pre className="max-h-64 overflow-y-auto whitespace-pre-wrap rounded-lg border p-3 font-mono text-xs leading-relaxed bg-[rgb(var(--ec-page-bg))] border-[rgb(var(--ec-page-border))]">
+              {prompt}
+            </pre>
+          </div>
+
+          <div className="space-y-4 border-t pt-4 border-[rgb(var(--ec-page-border))]">
+            <Detail title="MCP server" value={link.mcpUrl}>
+              For agents that can add an MCP server. Chats that show MCP Apps (ChatGPT, Claude) can open the canvas right in the
+              chat. Agents running in the cloud need this EventCatalog on a public URL.
+            </Detail>
+            <Detail title="WebMCP (this tab)">
+              {webMcp.state === 'on'
+                ? `On: this tab offers ${webMcp.tools} canvas tools to agents in your browser (${webMcp.source === 'native' ? "your browser's WebMCP" : 'WebMCP polyfill, e.g. for the MCP-B extension'}).`
+                : 'Off: this tab is not offering tools to agents in your browser (e.g. through the MCP-B extension).'}{' '}
+              {webMcp.state === 'off' && (
+                <button onClick={onEnableWebMcp} className="font-medium text-[rgb(var(--ec-accent))] hover:underline">
+                  Turn on for this tab
+                </button>
+              )}
+            </Detail>
+            {relayScriptPath && (
+              <Detail title="WebMCP local relay" value={RELAY_COMMAND}>
+                For agents on your computer (Claude Code, Cursor...): add this as an MCP server, and turn the relay on for this
+                tab. They get the tools of this tab while it stays open.{' '}
+                {relayOn ? (
+                  <span className={`font-medium ${STATUS.success.text}`}>The relay is on for this tab.</span>
+                ) : (
+                  <button
+                    onClick={() => {
+                      enableRelay(relayScriptPath);
+                      setRelayOn(true);
+                      // The relay hands this tab's WebMCP tools to desktop agents
+                      onEnableWebMcp();
+                    }}
+                    className="font-medium text-[rgb(var(--ec-accent))] hover:underline"
+                  >
+                    Turn on for this tab
+                  </button>
+                )}
+              </Detail>
+            )}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}