@particle-academy/agent-integrations 0.12.0 → 0.14.0

package/dist/index.cjs

@@ -2216,6 +2216,459 @@ function registerTerminalBridge(host, options) {
     pending: () => [...staged.values()]
   };
 }
+
+// src/bridges/navigation.ts
+var DEFAULT_AGENT9 = { id: "agent", name: "Agent", color: "#a855f7" };
+function registerNavigationBridge(host, options) {
+  const { adapter } = options;
+  const agent = { ...DEFAULT_AGENT9, ...options.agent ?? {} };
+  const pendingMode = options.pendingMode ?? true;
+  const disposers = [];
+  ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });
+  const target = (label, elementId) => ({
+    kind: "navigation",
+    screenId: adapter.screenId,
+    elementId,
+    label
+  });
+  const reg = (name, description, properties, required, handler, activity) => {
+    const wrapped = async (args) => {
+      try {
+        return await handler(args);
+      } catch (e) {
+        return errorResult(e instanceof Error ? e.message : String(e));
+      }
+    };
+    const final = activity ? wrapToolWithActivity(wrapped, {
+      toolName: name,
+      agent: { id: agent.id, name: agent.name, color: agent.color },
+      kind: "navigation",
+      screenId: adapter.screenId,
+      resolveTarget: ({ args }) => activity(args)
+    }) : wrapped;
+    disposers.push(
+      host.registerTool(
+        {
+          name,
+          description,
+          inputSchema: { type: "object", properties, required, additionalProperties: false }
+        },
+        final
+      )
+    );
+  };
+  reg(
+    "page_describe",
+    "Describe the current page: its URL, title, and the interactive elements you can act on (each with a stable `handle`, role, and label). Call this first, and again after navigating.",
+    {},
+    [],
+    () => {
+      const snap = adapter.describe();
+      const text = [
+        `URL: ${snap.url}`,
+        `Title: ${snap.title}`,
+        "",
+        ...snap.actions.map((a) => `[${a.handle}] ${a.role}: ${a.label}${a.destructive ? " (destructive)" : ""}`)
+      ].join("\n");
+      return textResult(text, snap);
+    },
+    false
+  );
+  reg(
+    "page_read",
+    "Read the page's visible text / heading outline for grounding.",
+    {},
+    [],
+    () => textResult(adapter.read ? adapter.read() : "(host did not provide page text)"),
+    false
+  );
+  reg(
+    "nav_visit",
+    "Navigate to a URL (same-site path or absolute). The human watches the page change.",
+    { url: { type: "string", description: "Path like /packages or an absolute URL." } },
+    ["url"],
+    async (args) => {
+      const url = String(args.url ?? "");
+      if (!url) return errorResult("url is required");
+      const from = adapter.getLocation().url;
+      await adapter.visit(url);
+      fancyAutoCommon.pushUndoEntry(agent.id, {
+        timestamp: Date.now(),
+        bridgeId: "navigation",
+        action: "nav_visit",
+        label: `Navigate to ${url}`,
+        undo: () => {
+          adapter.visit(from);
+        },
+        redo: () => {
+          adapter.visit(url);
+        }
+      });
+      return textResult(`Navigated to ${url}`, { url });
+    },
+    (args) => target(`Navigate \u2192 ${String(args.url ?? "")}`)
+  );
+  reg(
+    "nav_back",
+    "Go back to the previous page.",
+    {},
+    [],
+    async () => {
+      if (!adapter.back) return errorResult("Host did not provide back navigation.");
+      await adapter.back();
+      return textResult("Went back");
+    },
+    () => target("Back")
+  );
+  reg(
+    "nav_forward",
+    "Go forward to the next page.",
+    {},
+    [],
+    async () => {
+      if (!adapter.forward) return errorResult("Host did not provide forward navigation.");
+      await adapter.forward();
+      return textResult("Went forward");
+    },
+    () => target("Forward")
+  );
+  reg(
+    "nav_scroll_to",
+    "Scroll the page to absolute coordinates, or to a specific element by its handle.",
+    {
+      handle: { type: "string", description: "Scroll this element into view." },
+      x: { type: "number" },
+      y: { type: "number" }
+    },
+    [],
+    (args) => {
+      adapter.scrollTo({
+        handle: typeof args.handle === "string" ? args.handle : void 0,
+        x: typeof args.x === "number" ? args.x : void 0,
+        y: typeof args.y === "number" ? args.y : void 0
+      });
+      return textResult("Scrolled");
+    },
+    () => target("Scroll")
+  );
+  reg(
+    "nav_scroll_by",
+    "Scroll the page by a vertical delta in pixels (negative scrolls up).",
+    { dy: { type: "number" } },
+    ["dy"],
+    (args) => {
+      adapter.scrollBy(Number(args.dy ?? 0));
+      return textResult(`Scrolled by ${Number(args.dy ?? 0)}px`);
+    },
+    () => target("Scroll")
+  );
+  reg(
+    "page_set_field",
+    "Set a form field's value by handle. The host updates the controlled input and the human sees it change.",
+    {
+      handle: { type: "string" },
+      value: { description: "Value to set; type matches the field." }
+    },
+    ["handle", "value"],
+    (args) => {
+      const handle = String(args.handle ?? "");
+      const res = adapter.setField(handle, args.value);
+      if (!res.ok) return errorResult(res.error ?? `Could not set ${handle}`);
+      return textResult(`${handle} \u2190 ${JSON.stringify(args.value)}`, { handle, value: args.value });
+    },
+    (args) => target(`Set ${String(args.handle ?? "")}`, String(args.handle ?? ""))
+  );
+  reg(
+    "page_click",
+    "Activate an element by handle (link, button, checkbox\u2026). Destructive elements are staged for the human to confirm.",
+    { handle: { type: "string" } },
+    ["handle"],
+    async (args) => {
+      const handle = String(args.handle ?? "");
+      const action = adapter.describe().actions.find((a) => a.handle === handle);
+      if (pendingMode && action?.destructive && adapter.confirm) {
+        const ok = await adapter.confirm({ action: "click", handle, label: action.label });
+        if (!ok) return errorResult("Declined by user");
+      }
+      const res = adapter.click(handle);
+      if (!res.ok) return errorResult(res.error ?? `Could not click ${handle}`);
+      return textResult(`Clicked ${handle}`, { handle });
+    },
+    (args) => target(`Click ${String(args.handle ?? "")}`, String(args.handle ?? ""))
+  );
+  reg(
+    "page_submit",
+    "Submit a form by handle. Always staged for the human to confirm when pendingMode is on.",
+    { handle: { type: "string" } },
+    ["handle"],
+    async (args) => {
+      const handle = String(args.handle ?? "");
+      if (pendingMode && adapter.confirm) {
+        const ok = await adapter.confirm({ action: "submit", handle, label: handle });
+        if (!ok) return errorResult("Declined by user");
+      }
+      const res = await adapter.submit(handle);
+      if (!res.ok) return errorResult(res.error ?? "Submit failed");
+      return textResult(`Submitted ${handle}`, { handle });
+    },
+    (args) => target(`Submit ${String(args.handle ?? "")}`, String(args.handle ?? ""))
+  );
+  return {
+    id: "navigation",
+    title: "Co-browsing",
+    dispose: () => {
+      for (const d of disposers) d();
+    }
+  };
+}
+
+// src/sharing/token.ts
+var TOKEN_BYTES = 24;
+function createSessionDescriptor() {
+  const id = randomId(8);
+  const token = randomToken();
+  return { id, token, display: token.slice(0, 8) };
+}
+function describeSession(id, token) {
+  return { id, token, display: token.slice(0, 8) };
+}
+function buildShareUrl(descriptor, baseUrl = typeof window !== "undefined" ? window.location.href.split("?")[0] : "") {
+  const u = new URL(baseUrl);
+  u.searchParams.set("session", descriptor.id);
+  u.searchParams.set("token", descriptor.token);
+  return u.toString();
+}
+function buildShareConfig(descriptor, transport = "broadcast-channel") {
+  return {
+    name: `whiteboard-${descriptor.id}`,
+    transport,
+    session: descriptor.id,
+    token: descriptor.token,
+    channel: `fai:share:${descriptor.id}`,
+    protocol_version: "2025-06-18"
+  };
+}
+function readSessionFromUrl() {
+  if (typeof window === "undefined") return null;
+  const params = new URL(window.location.href).searchParams;
+  const id = params.get("session");
+  const token = params.get("token");
+  if (!id || !token) return null;
+  return describeSession(id, token);
+}
+function randomToken() {
+  const bytes = new Uint8Array(TOKEN_BYTES);
+  crypto.getRandomValues(bytes);
+  return base64Url(bytes);
+}
+function randomId(len) {
+  const bytes = new Uint8Array(Math.ceil(len * 3 / 4));
+  crypto.getRandomValues(bytes);
+  return base64Url(bytes).slice(0, len);
+}
+function base64Url(bytes) {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+
+// src/sharing/sse-relay.ts
+var SseRelayTransport = class {
+  constructor(options) {
+    this.sendQueue = [];
+    this.connected = false;
+    this.listeners = /* @__PURE__ */ new Set();
+    this.state = "idle";
+    this.opts = options;
+    this.expectedToken = options.token;
+  }
+  bindServer(server) {
+    this.server = server;
+  }
+  /** Open the SSE channel. Idempotent. */
+  start() {
+    if (this.connected || typeof window === "undefined") return;
+    const url = `${this.opts.baseUrl}/${encodeURIComponent(this.opts.sessionId)}/events?token=${encodeURIComponent(this.opts.token)}`;
+    this.setState("connecting");
+    const es = new EventSource(url, { withCredentials: false });
+    this.es = es;
+    es.addEventListener("open", () => {
+      this.connected = true;
+      this.setState("open");
+      const queued = this.sendQueue.splice(0);
+      for (const msg of queued) this.postOut(msg);
+    });
+    es.addEventListener("mcp", (ev) => {
+      const raw = ev.data;
+      this.handleInbound(raw);
+    });
+    es.addEventListener("error", () => {
+      this.setState("error");
+    });
+  }
+  send(message) {
+    if (!this.connected) {
+      this.sendQueue.push(message);
+      return;
+    }
+    this.postOut(message);
+  }
+  close() {
+    this.es?.close();
+    this.es = void 0;
+    this.connected = false;
+    this.setState("closed");
+  }
+  onStateChange(listener) {
+    this.listeners.add(listener);
+    listener(this.state);
+    return () => this.listeners.delete(listener);
+  }
+  /**
+   * For relays that wrap each frame with auth metadata: hosts can call this
+   * directly when a frame arrives via a non-SSE path. The transport will
+   * dispatch it to the bound server.
+   */
+  async deliverFromRemote(payload, token) {
+    if (token !== void 0 && !constantTimeEqual(token, this.expectedToken)) return;
+    if (!this.server) throw new Error("SseRelayTransport has no bound server");
+    const message = typeof payload === "string" ? JSON.parse(payload) : payload;
+    await this.server.receive(this, message);
+  }
+  async postOut(message) {
+    const url = `${this.opts.baseUrl}/${encodeURIComponent(this.opts.sessionId)}/outbox?token=${encodeURIComponent(this.opts.token)}`;
+    const f = this.opts.fetch ?? fetch;
+    try {
+      await f(url, {
+        method: "POST",
+        headers: { "content-type": "application/json", "accept": "application/json" },
+        body: JSON.stringify(message)
+      });
+    } catch {
+    }
+  }
+  async handleInbound(raw) {
+    if (!this.server) return;
+    let message;
+    try {
+      message = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    await this.server.receive(this, message);
+  }
+  setState(state) {
+    this.state = state;
+    for (const l of this.listeners) l(state);
+  }
+};
+function attachSseRelay(server, options) {
+  const transport = new SseRelayTransport(options);
+  transport.bindServer(server);
+  server.attach(transport);
+  transport.start();
+  Promise.resolve().then(() => (init_registry(), registry_exports)).then(({ onActivity: onActivity2 }) => {
+    const off = onActivity2((event) => {
+      transport.send({
+        jsonrpc: "2.0",
+        method: "notifications/agent_activity",
+        params: event
+      });
+    });
+    const origClose = transport.close.bind(transport);
+    transport.close = () => {
+      off();
+      origClose();
+    };
+  }).catch(() => {
+  });
+  return transport;
+}
+
+// src/sharing/use-co-browse-session.ts
+init_registry();
+var DEFAULT_AGENT10 = { id: "agent", name: "Agent", color: "#a855f7" };
+var USER = { id: "human", name: "You" };
+function useCoBrowseSession(options) {
+  const { adapter, extraBridges } = options;
+  const agent = { ...DEFAULT_AGENT10, ...options.agent ?? {} };
+  const relayBaseUrl = options.relayBaseUrl ?? "/whiteboard-share";
+  const serverRef = react.useRef(null);
+  const relayRef = react.useRef(null);
+  const detachInProc = react.useRef(null);
+  const disposeBridge = react.useRef(null);
+  const [session, setSession] = react.useState(null);
+  const [relayState, setRelayState] = react.useState("idle");
+  react.useEffect(() => {
+    const server = new MicroMcpServer({
+      info: options.info ?? { name: "fancy-co-browse", version: "0.1.0" },
+      instructions: options.info?.instructions ?? `Co-browse with a watching human. Call page_describe first; navigate, scroll, and (with confirm) fill/click via stable handles. You receive notifications/agent_activity for the human's actions (source:"user").`
+    });
+    const bridge = registerNavigationBridge(server, { adapter, agent, pendingMode: options.pendingMode });
+    extraBridges?.(server);
+    const inProc = attachInProcess(server);
+    detachInProc.current = () => inProc.close();
+    disposeBridge.current = bridge.dispose;
+    serverRef.current = server;
+    return () => {
+      relayRef.current?.close();
+      relayRef.current = null;
+      disposeBridge.current?.();
+      detachInProc.current?.();
+      serverRef.current = null;
+    };
+  }, []);
+  const startShare = react.useCallback(async () => {
+    const server = serverRef.current;
+    if (!server || relayRef.current) return;
+    const descriptor = createSessionDescriptor();
+    const csrf = options.csrfToken?.() ?? "";
+    await fetch(`${relayBaseUrl}/register`, {
+      method: "POST",
+      headers: { "content-type": "application/json", "x-csrf-token": csrf },
+      body: JSON.stringify({ session: descriptor.id, token: descriptor.token })
+    });
+    const relay = attachSseRelay(server, { baseUrl: relayBaseUrl, sessionId: descriptor.id, token: descriptor.token });
+    relay.onStateChange(setRelayState);
+    relayRef.current = relay;
+    setSession(descriptor);
+  }, [relayBaseUrl, options]);
+  const stopShare = react.useCallback(() => {
+    const current = session;
+    relayRef.current?.close();
+    relayRef.current = null;
+    setRelayState("idle");
+    setSession(null);
+    if (current) {
+      const csrf = options.csrfToken?.() ?? "";
+      void fetch(`${relayBaseUrl}/${current.id}/unregister`, {
+        method: "POST",
+        headers: { "content-type": "application/json", "x-csrf-token": csrf },
+        body: JSON.stringify({ token: current.token })
+      }).catch(() => {
+      });
+    }
+  }, [relayBaseUrl, options, session]);
+  const observeUser = react.useCallback((event) => {
+    const label = event.kind === "navigation" ? `You navigated to ${event.url}` : event.kind === "scroll" ? "You scrolled" : `You edited ${event.handle}${event.masked ? " (hidden)" : ""}`;
+    fancyAutoCommon.emitActivity({
+      agentId: USER.id,
+      agentName: USER.name,
+      source: "user",
+      target: { kind: "navigation", label },
+      action: `user_${event.kind}`,
+      timestamp: Date.now(),
+      meta: event
+    });
+  }, []);
+  return { server: serverRef.current, session, relayState, startShare, stopShare, observeUser };
+}
 function AgentPanel({ agent, activity, onSubmit, busy, actions, className, style }) {
   const scrollRef = react.useRef(null);
   const inputRef = react.useRef(null);
@@ -2474,62 +2927,6 @@ function ScreensActivityBridge({ system, fadeMs = 1500 }) {
   }, [system, fadeMs]);
   return null;
 }
-
-// src/sharing/token.ts
-var TOKEN_BYTES = 24;
-function createSessionDescriptor() {
-  const id = randomId(8);
-  const token = randomToken();
-  return { id, token, display: token.slice(0, 8) };
-}
-function describeSession(id, token) {
-  return { id, token, display: token.slice(0, 8) };
-}
-function buildShareUrl(descriptor, baseUrl = typeof window !== "undefined" ? window.location.href.split("?")[0] : "") {
-  const u = new URL(baseUrl);
-  u.searchParams.set("session", descriptor.id);
-  u.searchParams.set("token", descriptor.token);
-  return u.toString();
-}
-function buildShareConfig(descriptor, transport = "broadcast-channel") {
-  return {
-    name: `whiteboard-${descriptor.id}`,
-    transport,
-    session: descriptor.id,
-    token: descriptor.token,
-    channel: `fai:share:${descriptor.id}`,
-    protocol_version: "2025-06-18"
-  };
-}
-function readSessionFromUrl() {
-  if (typeof window === "undefined") return null;
-  const params = new URL(window.location.href).searchParams;
-  const id = params.get("session");
-  const token = params.get("token");
-  if (!id || !token) return null;
-  return describeSession(id, token);
-}
-function randomToken() {
-  const bytes = new Uint8Array(TOKEN_BYTES);
-  crypto.getRandomValues(bytes);
-  return base64Url(bytes);
-}
-function randomId(len) {
-  const bytes = new Uint8Array(Math.ceil(len * 3 / 4));
-  crypto.getRandomValues(bytes);
-  return base64Url(bytes).slice(0, len);
-}
-function base64Url(bytes) {
-  let s = "";
-  for (const b of bytes) s += String.fromCharCode(b);
-  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
-function constantTimeEqual(a, b) {
-  if (a.length !== b.length) return false;
-  let diff = 0;
-  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
-  return diff === 0;
-}
 function ShareControls({
   session,
   onStart,
@@ -2649,9 +3046,6 @@ function buildCurlRecipe(session) {
   ].join("\n");
 }
 
-// src/presence/index.ts
-init_registry();
-
 // src/presence/use-agent-activity.ts
 init_registry();
 function useAgentActivity(filter, options = {}) {
@@ -2684,6 +3078,314 @@ function useAgentActivityForScreen(screenId, options = {}) {
   }, [latest, fadeAfter]);
   return { events, latest, isAgentActive };
 }
+
+// src/connectors/targets.ts
+var CLAUDE_CONNECTORS_URL = "https://claude.ai/settings/connectors";
+function encodeBase64Json(value) {
+  const json = JSON.stringify(value);
+  if (typeof btoa === "function") {
+    return btoa(unescape(encodeURIComponent(json)));
+  }
+  return Buffer.from(json, "utf8").toString("base64");
+}
+function buildCursorDeeplink(server) {
+  const config = encodeBase64Json({ url: server.url });
+  return `cursor://anysphere.cursor-deeplink/mcp/install?name=${encodeURIComponent(
+    server.name
+  )}&config=${config}`;
+}
+function buildVscodeDeeplink(server, opts = {}) {
+  const scheme = opts.insiders ? "vscode-insiders" : "vscode";
+  const payload = encodeURIComponent(
+    JSON.stringify({ name: server.name, url: server.url })
+  );
+  return `${scheme}://mcp/install?${payload}`;
+}
+function slugifyServerName(name) {
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug || "mcp-server";
+}
+function buildManualConfig(server) {
+  return {
+    mcpServers: {
+      [slugifyServerName(server.name)]: {
+        command: "npx",
+        args: ["-y", "mcp-remote", server.url]
+      }
+    }
+  };
+}
+function buildManualConfigSnippet(server) {
+  return JSON.stringify(buildManualConfig(server), null, 2);
+}
+var CONNECTOR_TARGETS = {
+  "claude-web": {
+    id: "claude-web",
+    label: "Add to Claude",
+    mechanism: "copy-open",
+    hint: "Copy the MCP URL and open Claude's Connectors page \u2014 click 'Add custom connector' and paste."
+  },
+  "claude-desktop": {
+    id: "claude-desktop",
+    label: "Claude Desktop",
+    mechanism: "download",
+    hint: "Download a .mcpb bundle and double-click it to install in Claude Desktop."
+  },
+  cursor: {
+    id: "cursor",
+    label: "Add to Cursor",
+    mechanism: "deeplink",
+    hint: "Open Cursor with this MCP server pre-filled \u2014 confirm to install."
+  },
+  vscode: {
+    id: "vscode",
+    label: "Add to VS Code",
+    mechanism: "deeplink",
+    hint: "Open VS Code with this MCP server pre-filled \u2014 confirm to install."
+  },
+  manual: {
+    id: "manual",
+    label: "Manual setup",
+    mechanism: "snippet",
+    hint: "Show a config snippet to paste into any stdio MCP client."
+  }
+};
+function connectorHref(client, server, opts = {}) {
+  switch (client) {
+    case "cursor":
+      return buildCursorDeeplink(server);
+    case "vscode":
+      return buildVscodeDeeplink(server, opts);
+    default:
+      return null;
+  }
+}
+function ClaudeMark(props) {
+  return /* @__PURE__ */ jsxRuntime.jsx("svg", { viewBox: "0 0 24 24", fill: "currentColor", "aria-hidden": true, ...props, children: /* @__PURE__ */ jsxRuntime.jsx("path", { d: "M12 2 L 14 10 L 22 12 L 14 14 L 12 22 L 10 14 L 2 12 L 10 10 Z" }) });
+}
+function CursorMark(props) {
+  return /* @__PURE__ */ jsxRuntime.jsx("svg", { viewBox: "0 0 24 24", fill: "currentColor", "aria-hidden": true, ...props, children: /* @__PURE__ */ jsxRuntime.jsx("path", { d: "M3 3 L 20 11 L 12 13 L 9 21 Z" }) });
+}
+function VscodeMark(props) {
+  return /* @__PURE__ */ jsxRuntime.jsx("svg", { viewBox: "0 0 24 24", fill: "currentColor", "aria-hidden": true, ...props, children: /* @__PURE__ */ jsxRuntime.jsx("path", { d: "M17 2 L 22 4.5 V 19.5 L 17 22 L 6.5 13.2 L 3 16 L 1.5 15 V 9 L 3 8 L 6.5 10.8 Z M 17 6.5 L 10 12 L 17 17.5 Z" }) });
+}
+function DesktopMark(props) {
+  return /* @__PURE__ */ jsxRuntime.jsx("svg", { viewBox: "0 0 24 24", fill: "currentColor", "aria-hidden": true, ...props, children: /* @__PURE__ */ jsxRuntime.jsx("path", { d: "M3 4 H 21 A 1 1 0 0 1 22 5 V 16 A 1 1 0 0 1 21 17 H 14 V 19 H 16 V 21 H 8 V 19 H 10 V 17 H 3 A 1 1 0 0 1 2 16 V 5 A 1 1 0 0 1 3 4 Z" }) });
+}
+function WrenchMark(props) {
+  return /* @__PURE__ */ jsxRuntime.jsx("svg", { viewBox: "0 0 24 24", fill: "currentColor", "aria-hidden": true, ...props, children: /* @__PURE__ */ jsxRuntime.jsx("path", { d: "M21 4 a 5 5 0 0 1 -6.5 6.5 L 6 19 l -3 -3 l 8.5 -8.5 A 5 5 0 0 1 17 1 l -2.5 2.5 l 1.5 3 l 3 1.5 Z" }) });
+}
+var CONNECTOR_GLYPHS = {
+  "claude-web": ClaudeMark,
+  "claude-desktop": DesktopMark,
+  cursor: CursorMark,
+  vscode: VscodeMark,
+  manual: WrenchMark
+};
+var DEFAULT_CLIENTS = [
+  "claude-web",
+  "cursor",
+  "vscode",
+  "manual"
+];
+function ConnectorButtons({
+  serverName,
+  mcpUrl,
+  clients,
+  mcpbDownloadUrl,
+  claudeConnectorsUrl = CLAUDE_CONNECTORS_URL,
+  vscodeInsiders,
+  onCopy,
+  onAction,
+  labels,
+  className,
+  style
+}) {
+  const server = { name: serverName, url: mcpUrl };
+  const [copied, setCopied] = react.useState(null);
+  const [manualOpen, setManualOpen] = react.useState(false);
+  const manualId = react.useId();
+  const list = (clients ?? defaultClients(mcpbDownloadUrl)).filter(
+    (c) => c === "claude-desktop" ? !!mcpbDownloadUrl : true
+  );
+  const flashCopied = (target) => {
+    setCopied(target);
+    window.setTimeout(() => setCopied((c) => c === target ? null : c), 2e3);
+  };
+  const copy = async (value, target) => {
+    try {
+      await navigator.clipboard?.writeText(value);
+      flashCopied(target);
+      onCopy?.(target);
+    } catch {
+    }
+  };
+  const labelFor = (c) => labels?.[c] ?? CONNECTOR_TARGETS[c].label;
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "div",
+    {
+      className: ["fai-connect", className].filter(Boolean).join(" "),
+      style,
+      children: list.map((client) => {
+        const meta = CONNECTOR_TARGETS[client];
+        const Glyph = CONNECTOR_GLYPHS[client];
+        const base = `fai-connect__btn fai-connect__btn--${client}`;
+        const href = connectorHref(client, server, { insiders: vscodeInsiders });
+        if (href) {
+          return /* @__PURE__ */ jsxRuntime.jsxs(
+            "a",
+            {
+              href,
+              className: base,
+              title: meta.hint,
+              onClick: () => onAction?.(client),
+              children: [
+                /* @__PURE__ */ jsxRuntime.jsx(Glyph, { className: "fai-connect__glyph" }),
+                labelFor(client)
+              ]
+            },
+            client
+          );
+        }
+        if (client === "claude-desktop") {
+          return /* @__PURE__ */ jsxRuntime.jsxs(
+            "a",
+            {
+              href: mcpbDownloadUrl,
+              download: true,
+              className: base,
+              title: meta.hint,
+              onClick: () => onAction?.(client),
+              children: [
+                /* @__PURE__ */ jsxRuntime.jsx(Glyph, { className: "fai-connect__glyph" }),
+                labelFor(client)
+              ]
+            },
+            client
+          );
+        }
+        if (client === "claude-web") {
+          return /* @__PURE__ */ jsxRuntime.jsxs(
+            "button",
+            {
+              type: "button",
+              className: base,
+              title: meta.hint,
+              onClick: () => {
+                void copy(mcpUrl, client);
+                window.open(
+                  claudeConnectorsUrl,
+                  "_blank",
+                  "noopener,noreferrer"
+                );
+                onAction?.(client);
+              },
+              children: [
+                /* @__PURE__ */ jsxRuntime.jsx(Glyph, { className: "fai-connect__glyph" }),
+                copied === client ? "Copied \u2014 paste in Claude" : labelFor(client)
+              ]
+            },
+            client
+          );
+        }
+        return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "fai-connect__manual-wrap", children: [
+          /* @__PURE__ */ jsxRuntime.jsxs(
+            "button",
+            {
+              type: "button",
+              className: base,
+              title: meta.hint,
+              "aria-expanded": manualOpen,
+              "aria-controls": manualId,
+              onClick: () => {
+                setManualOpen((o) => !o);
+                onAction?.(client);
+              },
+              children: [
+                /* @__PURE__ */ jsxRuntime.jsx(Glyph, { className: "fai-connect__glyph" }),
+                labelFor(client)
+              ]
+            }
+          ),
+          manualOpen && /* @__PURE__ */ jsxRuntime.jsx(
+            ManualPopover,
+            {
+              id: manualId,
+              snippet: buildManualConfigSnippet(server),
+              copied: copied === client,
+              onCopy: () => copy(buildManualConfigSnippet(server), client),
+              onClose: () => setManualOpen(false)
+            }
+          )
+        ] }, client);
+      })
+    }
+  );
+}
+function defaultClients(mcpbDownloadUrl) {
+  return mcpbDownloadUrl ? ["claude-web", "claude-desktop", "cursor", "vscode", "manual"] : DEFAULT_CLIENTS;
+}
+function ManualPopover({
+  id,
+  snippet,
+  copied,
+  onCopy,
+  onClose
+}) {
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { id, className: "fai-connect__popover", role: "dialog", children: [
+    /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "fai-connect__popover-head", children: [
+      /* @__PURE__ */ jsxRuntime.jsx("span", { children: "Add to any stdio MCP client" }),
+      /* @__PURE__ */ jsxRuntime.jsx(
+        "button",
+        {
+          type: "button",
+          className: "fai-connect__popover-close",
+          "aria-label": "Close",
+          onClick: onClose,
+          children: "\xD7"
+        }
+      )
+    ] }),
+    /* @__PURE__ */ jsxRuntime.jsxs("p", { className: "fai-connect__popover-hint", children: [
+      "Paste into ",
+      /* @__PURE__ */ jsxRuntime.jsx("code", { children: "claude_desktop_config.json" }),
+      " (or any stdio MCP client config). Needs Node 18+."
+    ] }),
+    /* @__PURE__ */ jsxRuntime.jsx("pre", { className: "fai-connect__snippet", children: snippet }),
+    /* @__PURE__ */ jsxRuntime.jsx("button", { type: "button", className: "fai-connect__copy-btn", onClick: onCopy, children: copied ? "Copied" : "Copy snippet" })
+  ] });
+}
+function CoBrowsePresence({ session, connectUrl, shareBaseUrl, className }) {
+  const { events } = useAgentActivity(void 0, { capacity: 40 });
+  const lastAgentAction = [...events].reverse().find((e) => (e.source ?? "agent") !== "user");
+  const connected = session.relayState === "open";
+  if (!session.session) {
+    return /* @__PURE__ */ jsxRuntime.jsx("div", { className, "data-co-browse-presence": "idle", children: /* @__PURE__ */ jsxRuntime.jsx("button", { type: "button", onClick: () => void session.startShare(), "data-co-browse-start": true, children: "Let an agent drive" }) });
+  }
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className, "data-co-browse-presence": connected ? "connected" : "waiting", children: [
+    /* @__PURE__ */ jsxRuntime.jsxs("div", { "data-co-browse-bar": true, children: [
+      /* @__PURE__ */ jsxRuntime.jsx("span", { "data-co-browse-dot": true, "data-state": session.relayState }),
+      /* @__PURE__ */ jsxRuntime.jsx("span", { "data-co-browse-status": true, children: connected ? "Agent is driving" : `Waiting for an agent\u2026 (${session.relayState})` }),
+      lastAgentAction && /* @__PURE__ */ jsxRuntime.jsx("span", { "data-co-browse-last": true, children: lastAgentAction.target?.label ?? lastAgentAction.action }),
+      /* @__PURE__ */ jsxRuntime.jsx("button", { type: "button", onClick: session.stopShare, "data-co-browse-stop": true, children: "Stop" })
+    ] }),
+    /* @__PURE__ */ jsxRuntime.jsx(
+      ShareControls,
+      {
+        session: session.session,
+        onStart: () => void session.startShare(),
+        onStop: session.stopShare,
+        status: session.relayState,
+        shareBaseUrl
+      }
+    ),
+    connectUrl && /* @__PURE__ */ jsxRuntime.jsx(ConnectorButtons, { serverName: "Fancy UI co-browse", mcpUrl: connectUrl })
+  ] });
+}
+CoBrowsePresence.displayName = "CoBrowsePresence";
+
+// src/presence/index.ts
+init_registry();
 function useUndoStack(agentId, intervalMs = 500) {
   const [history, setHistory] = react.useState(() => fancyAutoCommon.readHistory(agentId));
   react.useEffect(() => {
@@ -2703,117 +3405,63 @@ function useUndoStack(agentId, intervalMs = 500) {
   return { history, refresh };
 }
 
-// src/sharing/sse-relay.ts
-var SseRelayTransport = class {
-  constructor(options) {
-    this.sendQueue = [];
-    this.connected = false;
-    this.listeners = /* @__PURE__ */ new Set();
-    this.state = "idle";
-    this.opts = options;
-    this.expectedToken = options.token;
-  }
-  bindServer(server) {
-    this.server = server;
-  }
-  /** Open the SSE channel. Idempotent. */
-  start() {
-    if (this.connected || typeof window === "undefined") return;
-    const url = `${this.opts.baseUrl}/${encodeURIComponent(this.opts.sessionId)}/events?token=${encodeURIComponent(this.opts.token)}`;
-    this.setState("connecting");
-    const es = new EventSource(url, { withCredentials: false });
-    this.es = es;
-    es.addEventListener("open", () => {
-      this.connected = true;
-      this.setState("open");
-      const queued = this.sendQueue.splice(0);
-      for (const msg of queued) this.postOut(msg);
-    });
-    es.addEventListener("mcp", (ev) => {
-      const raw = ev.data;
-      this.handleInbound(raw);
-    });
-    es.addEventListener("error", () => {
-      this.setState("error");
-    });
-  }
-  send(message) {
-    if (!this.connected) {
-      this.sendQueue.push(message);
-      return;
-    }
-    this.postOut(message);
-  }
-  close() {
-    this.es?.close();
-    this.es = void 0;
-    this.connected = false;
-    this.setState("closed");
-  }
-  onStateChange(listener) {
-    this.listeners.add(listener);
-    listener(this.state);
-    return () => this.listeners.delete(listener);
-  }
-  /**
-   * For relays that wrap each frame with auth metadata: hosts can call this
-   * directly when a frame arrives via a non-SSE path. The transport will
-   * dispatch it to the bound server.
-   */
-  async deliverFromRemote(payload, token) {
-    if (token !== void 0 && !constantTimeEqual(token, this.expectedToken)) return;
-    if (!this.server) throw new Error("SseRelayTransport has no bound server");
-    const message = typeof payload === "string" ? JSON.parse(payload) : payload;
-    await this.server.receive(this, message);
-  }
-  async postOut(message) {
-    const url = `${this.opts.baseUrl}/${encodeURIComponent(this.opts.sessionId)}/outbox?token=${encodeURIComponent(this.opts.token)}`;
-    const f = this.opts.fetch ?? fetch;
-    try {
-      await f(url, {
-        method: "POST",
-        headers: { "content-type": "application/json", "accept": "application/json" },
-        body: JSON.stringify(message)
-      });
-    } catch {
-    }
-  }
-  async handleInbound(raw) {
-    if (!this.server) return;
-    let message;
-    try {
-      message = JSON.parse(raw);
-    } catch {
-      return;
+// src/connectors/mcpb.ts
+var MCPB_MANIFEST_VERSION = "0.2";
+var MCPB_MIN_NODE = ">=18.0.0";
+var DEFAULT_MCPB_ENTRY_POINT = "server/proxy.js";
+function buildMcpbManifest(input) {
+  const entryPoint = input.entryPoint ?? DEFAULT_MCPB_ENTRY_POINT;
+  return {
+    manifest_version: MCPB_MANIFEST_VERSION,
+    name: input.name,
+    display_name: input.display_name ?? input.name,
+    version: input.version,
+    description: input.description,
+    ...input.long_description ? { long_description: input.long_description } : {},
+    author: input.author,
+    ...input.homepage ? { homepage: input.homepage } : {},
+    ...input.documentation ? { documentation: input.documentation } : {},
+    ...input.support ? { support: input.support } : {},
+    server: {
+      type: "node",
+      entry_point: entryPoint,
+      mcp_config: {
+        command: "npx",
+        args: ["-y", "mcp-remote", input.mcpUrl]
+      }
+    },
+    tools: input.tools ?? [],
+    tools_generated: false,
+    prompts_generated: false,
+    ...input.keywords ? { keywords: input.keywords } : {},
+    license: input.license ?? "MIT",
+    compatibility: {
+      claude_desktop: ">=0.10.0",
+      platforms: ["darwin", "win32", "linux"],
+      runtimes: { node: MCPB_MIN_NODE }
     }
-    await this.server.receive(this, message);
-  }
-  setState(state) {
-    this.state = state;
-    for (const l of this.listeners) l(state);
-  }
-};
-function attachSseRelay(server, options) {
-  const transport = new SseRelayTransport(options);
-  transport.bindServer(server);
-  server.attach(transport);
-  transport.start();
-  Promise.resolve().then(() => (init_registry(), registry_exports)).then(({ onActivity: onActivity2 }) => {
-    const off = onActivity2((event) => {
-      transport.send({
-        jsonrpc: "2.0",
-        method: "notifications/agent_activity",
-        params: event
-      });
-    });
-    const origClose = transport.close.bind(transport);
-    transport.close = () => {
-      off();
-      origClose();
-    };
-  }).catch(() => {
-  });
-  return transport;
+  };
+}
+function buildMcpbProxyStub(mcpUrl) {
+  const urlLiteral = JSON.stringify(mcpUrl);
+  return `#!/usr/bin/env node
+// MCPB proxy shim (generated by @particle-academy/agent-integrations).
+//
+// MCPB (Claude Desktop Extensions) only supports local stdio servers, but this
+// MCP server is a remote HTTP endpoint. The manifest's \`mcp_config\` invokes
+// \`npx -y mcp-remote <url>\` to bridge the gap \u2014 this file is the entry_point
+// fallback the manifest validator requires. If you're seeing this run,
+// mcp_config wasn't honored; spawn mcp-remote directly so the bundle still works.
+
+const { spawn } = require("node:child_process");
+
+const url = ${urlLiteral};
+const child = spawn("npx", ["-y", "mcp-remote", url], { stdio: "inherit" });
+
+child.on("exit", (code) => process.exit(code ?? 0));
+process.on("SIGINT", () => child.kill("SIGINT"));
+process.on("SIGTERM", () => child.kill("SIGTERM"));
+`;
 }
 
 Object.defineProperty(exports, "clearUndoStack", {
@@ -2860,7 +3508,18 @@ exports.AgentActivityHighlight = AgentActivityHighlight;
 exports.AgentCursor = AgentCursor;
 exports.AgentPanel = AgentPanel;
 exports.BridgedForm = BridgedForm;
+exports.CLAUDE_CONNECTORS_URL = CLAUDE_CONNECTORS_URL;
+exports.CONNECTOR_GLYPHS = CONNECTOR_GLYPHS;
+exports.CONNECTOR_TARGETS = CONNECTOR_TARGETS;
+exports.ClaudeMark = ClaudeMark;
+exports.CoBrowsePresence = CoBrowsePresence;
+exports.ConnectorButtons = ConnectorButtons;
+exports.CursorMark = CursorMark;
+exports.DEFAULT_MCPB_ENTRY_POINT = DEFAULT_MCPB_ENTRY_POINT;
+exports.DesktopMark = DesktopMark;
 exports.InProcessTransport = InProcessTransport;
+exports.MCPB_MANIFEST_VERSION = MCPB_MANIFEST_VERSION;
+exports.MCPB_MIN_NODE = MCPB_MIN_NODE;
 exports.MCP_PROTOCOL_VERSION = MCP_PROTOCOL_VERSION;
 exports.MicroMcpServer = MicroMcpServer;
 exports.RelayTransport = RelayTransport;
@@ -2868,19 +3527,30 @@ exports.ScreensActivityBridge = ScreensActivityBridge;
 exports.ShareControls = ShareControls;
 exports.SseRelayTransport = SseRelayTransport;
 exports.ToolRegistry = ToolRegistry;
+exports.VscodeMark = VscodeMark;
+exports.WrenchMark = WrenchMark;
 exports.attachInProcess = attachInProcess;
 exports.attachRelay = attachRelay;
 exports.attachSseRelay = attachSseRelay;
+exports.buildCursorDeeplink = buildCursorDeeplink;
+exports.buildManualConfig = buildManualConfig;
+exports.buildManualConfigSnippet = buildManualConfigSnippet;
+exports.buildMcpbManifest = buildMcpbManifest;
+exports.buildMcpbProxyStub = buildMcpbProxyStub;
 exports.buildShareConfig = buildShareConfig;
 exports.buildShareUrl = buildShareUrl;
+exports.buildVscodeDeeplink = buildVscodeDeeplink;
+exports.connectorHref = connectorHref;
 exports.createSessionDescriptor = createSessionDescriptor;
 exports.describeSession = describeSession;
+exports.encodeBase64Json = encodeBase64Json;
 exports.ensureUndoToolsRegistered = ensureUndoToolsRegistered;
 exports.errorResult = errorResult;
 exports.readSessionFromUrl = readSessionFromUrl;
 exports.registerChartsBridge = registerChartsBridge;
 exports.registerCodeBridge = registerCodeBridge;
 exports.registerFormBridge = registerFormBridge;
+exports.registerNavigationBridge = registerNavigationBridge;
 exports.registerSceneBridge = registerSceneBridge;
 exports.registerScreensBridge = registerScreensBridge;
 exports.registerSheetsBridge = registerSheetsBridge;
@@ -2888,9 +3558,11 @@ exports.registerSlidesBridge = registerSlidesBridge;
 exports.registerTerminalBridge = registerTerminalBridge;
 exports.registerUndoTools = registerUndoTools;
 exports.rpcError = rpcError;
+exports.slugifyServerName = slugifyServerName;
 exports.textResult = textResult;
 exports.useAgentActivity = useAgentActivity;
 exports.useAgentActivityForScreen = useAgentActivityForScreen;
+exports.useCoBrowseSession = useCoBrowseSession;
 exports.useSheetsActivityHighlights = useSheetsActivityHighlights;
 exports.useSheetsAdapter = useSheetsAdapter;
 exports.useUndoStack = useUndoStack;