@particle-academy/agent-integrations 0.46.0 → 0.47.0

package/dist/chunk-JGJHPH65.js

@@ -0,0 +1,271 @@
+import { ensureUndoToolsRegistered, pushUndoEntry } from './chunk-R4XXOGQH.js';
+import { wrapToolWithActivity } from './chunk-2VENWGLZ.js';
+import { textResult, errorResult } from './chunk-CZV3WUW5.js';
+
+// src/bridges/navigation.ts
+var DEFAULT_AGENT = { id: "agent", name: "Agent", color: "#a855f7" };
+function registerNavigationBridge(host, options) {
+  const { adapter } = options;
+  const agent = { ...DEFAULT_AGENT, ...options.agent ?? {} };
+  const pendingMode = options.pendingMode ?? true;
+  const disposers = [];
+  let groundedRevision = null;
+  const staleIntent = async () => {
+    const current = await adapter.getRevision?.();
+    if (current === void 0) return null;
+    if (groundedRevision === null || groundedRevision !== current) {
+      return errorResult(
+        `Human took control at page revision ${current}. This agent action was cancelled; call page_describe before acting again.`
+      );
+    }
+    return null;
+  };
+  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.",
+    {},
+    [],
+    async () => {
+      const snap = await adapter.describe();
+      const revision = await adapter.getRevision?.();
+      if (revision !== void 0) {
+        snap.revision = revision;
+        groundedRevision = revision;
+      }
+      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);
+    },
+    () => target("Inspect page")
+  );
+  reg(
+    "page_read",
+    "Read the page's visible text / heading outline for grounding.",
+    {},
+    [],
+    async () => textResult(adapter.read ? await adapter.read() : "(host did not provide page text)"),
+    () => target("Read page")
+  );
+  reg(
+    "page_focus",
+    "Move the agent's visible focus to an interactive element by stable handle without activating it.",
+    { handle: { type: "string" } },
+    ["handle"],
+    async (args) => {
+      const stale = await staleIntent();
+      if (stale) return stale;
+      const handle = String(args.handle ?? "");
+      const action = (await adapter.describe()).actions.find((candidate) => candidate.handle === handle);
+      if (!action) return errorResult(`No element for handle "${handle}"`);
+      return textResult(`Focused ${handle}`, {
+        handle,
+        rect: await adapter.rectFor?.(handle) ?? void 0
+      });
+    },
+    (args) => target(`Focus ${String(args.handle ?? "")}`, String(args.handle ?? ""))
+  );
+  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 stale = await staleIntent();
+      if (stale) return stale;
+      const url = String(args.url ?? "");
+      if (!url) return errorResult("url is required");
+      const scheme = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(url)?.[1]?.toLowerCase();
+      if (scheme && scheme !== "http" && scheme !== "https") {
+        return errorResult(
+          `Refusing to navigate to a '${scheme}:' URL. Only http(s) URLs or same-site paths are allowed.`
+        );
+      }
+      const from = (await adapter.getLocation()).url;
+      await adapter.visit(url);
+      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 () => {
+      const stale = await staleIntent();
+      if (stale) return stale;
+      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 () => {
+      const stale = await staleIntent();
+      if (stale) return stale;
+      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" }
+    },
+    [],
+    async (args) => {
+      const stale = await staleIntent();
+      if (stale) return stale;
+      const handle = typeof args.handle === "string" ? args.handle : void 0;
+      await adapter.scrollTo({
+        handle,
+        x: typeof args.x === "number" ? args.x : void 0,
+        y: typeof args.y === "number" ? args.y : void 0
+      });
+      return textResult("Scrolled", handle ? { handle, rect: await adapter.rectFor?.(handle) ?? void 0 } : void 0);
+    },
+    () => target("Scroll")
+  );
+  reg(
+    "nav_scroll_by",
+    "Scroll the page by a vertical delta in pixels (negative scrolls up).",
+    { dy: { type: "number" } },
+    ["dy"],
+    async (args) => {
+      const stale = await staleIntent();
+      if (stale) return stale;
+      await 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"],
+    async (args) => {
+      const stale = await staleIntent();
+      if (stale) return stale;
+      const handle = String(args.handle ?? "");
+      const res = await 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, rect: await adapter.rectFor?.(handle) ?? void 0 });
+    },
+    (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 stale = await staleIntent();
+      if (stale) return stale;
+      const handle = String(args.handle ?? "");
+      const action = (await adapter.describe()).actions.find((a) => a.handle === handle);
+      const rect = await adapter.rectFor?.(handle) ?? void 0;
+      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 = await adapter.click(handle);
+      if (!res.ok) return errorResult(res.error ?? `Could not click ${handle}`);
+      return textResult(`Clicked ${handle}`, { handle, rect });
+    },
+    (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 stale = await staleIntent();
+      if (stale) return stale;
+      const handle = String(args.handle ?? "");
+      const rect = await adapter.rectFor?.(handle) ?? void 0;
+      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, rect });
+    },
+    (args) => target(`Submit ${String(args.handle ?? "")}`, String(args.handle ?? ""))
+  );
+  return {
+    id: "navigation",
+    title: "Co-browsing",
+    dispose: () => {
+      for (const d of disposers) d();
+    }
+  };
+}
+
+export { registerNavigationBridge };
+//# sourceMappingURL=chunk-JGJHPH65.js.map
+//# sourceMappingURL=chunk-JGJHPH65.js.map

package/dist/chunk-JGJHPH65.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/bridges/navigation.ts"],"names":[],"mappings":"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","file":"chunk-JGJHPH65.js","sourcesContent":["import { textResult, errorResult } from \"../mcp/server\";\nimport type { ToolHost } from \"../mcp/tool-host\";\nimport type { JsonObject } from \"../mcp/types\";\nimport type { Bridge } from \"./types\";\nimport { wrapToolWithActivity } from \"../presence/wrap-tool-with-activity\";\nimport type { AgentTarget } from \"../presence/types\";\nimport { pushUndoEntry } from \"../undo/undo-stack\";\nimport { ensureUndoToolsRegistered } from \"../undo/undo-tools\";\n\n/**\n * One interactive element the agent can act on, addressed by a STABLE handle\n * (not a CSS selector) so the agent drives the page the Human+ way — never DOM\n * scraping. The host builds these in `describe()` (data-co-handle → name/id →\n * ARIA role + accessible name).\n */\nexport type PageAction = {\n  /** Stable, opaque handle the agent passes back to act on this element. */\n  handle: string;\n  /** ARIA-ish role: \"link\" | \"button\" | \"textbox\" | \"checkbox\" | \"select\" | … */\n  role: string;\n  /** Accessible name / label. */\n  label: string;\n  /** Current value for inputs (omitted/masked for sensitive fields). */\n  value?: unknown;\n  /** True when activating this is destructive / submits (agent should stage). */\n  destructive?: boolean;\n};\n\n/** The page as the agent sees it: where it is + what it can do. */\nexport type PageSnapshot = {\n  url: string;\n  title: string;\n  actions: PageAction[];\n  /** Monotonic host revision. Human input advances it and invalidates stale agent intent. */\n  revision?: number;\n};\n\n/** A write the host may want the human to confirm (trust-but-verify). */\nexport type NavigationConfirmRequest = {\n  action: \"submit\" | \"click\";\n  handle: string;\n  label: string;\n};\n\ntype MaybePromise<T> = T | Promise<T>;\n\n/**\n * Host-provided adapter. In the sandbox this is backed by Inertia's `router` +\n * the DOM walker from `@particle-academy/agent-integrations/dom-navigation`.\n * Every method works on stable handles, never raw selectors.\n *\n * Any method may return a Promise: a host driving a page it does not run in\n * (an Electron WebContentsView, via `createRemoteNavigationAdapter`) can only\n * answer asynchronously. The bridge awaits every call.\n */\nexport type NavigationBridgeAdapter = {\n  /** Optional fancy-screens screen id for presence targeting. */\n  screenId?: string;\n  /** Current location. */\n  getLocation: () => MaybePromise<{ url: string; title: string }>;\n  /** Current human-control revision. Omit to disable stale-intent protection. */\n  getRevision?: () => MaybePromise<number>;\n  /** Snapshot of the page's actionable elements (stable handles + labels). */\n  describe: () => MaybePromise<PageSnapshot>;\n  /** Visible text / heading outline for grounding (optional). */\n  read?: () => MaybePromise<string>;\n  /** Navigate to a URL (host wires to router.visit). */\n  visit: (url: string) => void | Promise<void>;\n  back?: () => void | Promise<void>;\n  forward?: () => void | Promise<void>;\n  /** Scroll to coords or to a handle's element. */\n  scrollTo: (opts: { x?: number; y?: number; handle?: string }) => void | Promise<void>;\n  scrollBy: (dy: number) => void | Promise<void>;\n  /** Set a field's value by handle (host dispatches input/change for React). */\n  setField: (handle: string, value: unknown) => MaybePromise<{ ok: boolean; error?: string }>;\n  /** Activate an element by handle. */\n  click: (handle: string) => MaybePromise<{ ok: boolean; error?: string }>;\n  /** Submit a form by handle. */\n  submit: (handle: string) => Promise<{ ok: boolean; error?: string }> | { ok: boolean; error?: string };\n  /**\n   * Viewport rect of a handle's element, for agent-presence rendering (cursor +\n   * highlight). Returned in tool `meta.rect` so `<CoBrowseCursorLayer>` can show\n   * the agent acting on the page. Optional — omit and there's just no cursor.\n   */\n  rectFor?: (handle: string) => MaybePromise<{ x: number; y: number; width: number; height: number } | null>;\n  /**\n   * Trust-but-verify hook. When `pendingMode` is on, `page_submit` and\n   * destructive `page_click` route through this; the host shows a prompt and\n   * resolves true (proceed) / false (declined).\n   */\n  confirm?: (req: NavigationConfirmRequest) => Promise<boolean>;\n};\n\nexport type NavigationBridgeOptions = {\n  adapter: NavigationBridgeAdapter;\n  /** Identity tagged into activity events (so the human sees who's driving). */\n  agent?: { id: string; name?: string; color?: string };\n  /** Route submit + destructive clicks through `adapter.confirm`. Default true. */\n  pendingMode?: boolean;\n};\n\nconst DEFAULT_AGENT = { id: \"agent\", name: \"Agent\", color: \"#a855f7\" };\n\n/**\n * registerNavigationBridge — site-wide co-browsing. Lets a connected agent\n * navigate, scroll, and (with staged confirm) fill + click any page, addressed\n * by stable handles. Pairs with `useCoBrowseSession` (server + relay) and\n * `<CoBrowsePresence>` (the human's view of the agent). The 12th Fancy bridge.\n */\nexport function registerNavigationBridge(\n  host: ToolHost,\n  options: NavigationBridgeOptions,\n): Bridge {\n  const { adapter } = options;\n  const agent = { ...DEFAULT_AGENT, ...(options.agent ?? {}) };\n  const pendingMode = options.pendingMode ?? true;\n  const disposers: Array<() => void> = [];\n  let groundedRevision: number | null = null;\n\n  const staleIntent = async () => {\n    const current = await adapter.getRevision?.();\n    if (current === undefined) return null;\n    if (groundedRevision === null || groundedRevision !== current) {\n      return errorResult(\n        `Human took control at page revision ${current}. This agent action was cancelled; call page_describe before acting again.`,\n      );\n    }\n    return null;\n  };\n\n  ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });\n\n  const target = (label: string, elementId?: string): AgentTarget => ({\n    kind: \"navigation\",\n    screenId: adapter.screenId,\n    elementId,\n    label,\n  });\n\n  const reg = (\n    name: string,\n    description: string,\n    properties: Record<string, unknown>,\n    required: string[],\n    handler: (args: JsonObject) => Promise<any> | any,\n    activity: false | ((args: JsonObject) => AgentTarget),\n  ) => {\n    const wrapped = async (args: JsonObject) => {\n      try {\n        return await handler(args);\n      } catch (e) {\n        return errorResult(e instanceof Error ? e.message : String(e));\n      }\n    };\n    const final = activity\n      ? wrapToolWithActivity(wrapped, {\n          toolName: name,\n          agent: { id: agent.id, name: agent.name, color: agent.color },\n          kind: \"navigation\",\n          screenId: adapter.screenId,\n          resolveTarget: ({ args }) => activity(args),\n        })\n      : wrapped;\n    disposers.push(\n      host.registerTool(\n        {\n          name,\n          description,\n          inputSchema: { type: \"object\", properties: properties as any, required, additionalProperties: false },\n        },\n        final as any,\n      ),\n    );\n  };\n\n  // ───────────── Read ─────────────\n\n  reg(\n    \"page_describe\",\n    \"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.\",\n    {},\n    [],\n    async () => {\n      const snap = await adapter.describe();\n      const revision = await adapter.getRevision?.();\n      if (revision !== undefined) {\n        snap.revision = revision;\n        groundedRevision = revision;\n      }\n      const text = [\n        `URL: ${snap.url}`,\n        `Title: ${snap.title}`,\n        \"\",\n        ...snap.actions.map((a) => `[${a.handle}] ${a.role}: ${a.label}${a.destructive ? \" (destructive)\" : \"\"}`),\n      ].join(\"\\n\");\n      return textResult(text, snap);\n    },\n    () => target(\"Inspect page\"),\n  );\n\n  reg(\n    \"page_read\",\n    \"Read the page's visible text / heading outline for grounding.\",\n    {},\n    [],\n    async () => textResult(adapter.read ? await adapter.read() : \"(host did not provide page text)\"),\n    () => target(\"Read page\"),\n  );\n\n  reg(\n    \"page_focus\",\n    \"Move the agent's visible focus to an interactive element by stable handle without activating it.\",\n    { handle: { type: \"string\" } },\n    [\"handle\"],\n    async (args) => {\n      const stale = await staleIntent();\n      if (stale) return stale;\n      const handle = String(args.handle ?? \"\");\n      const action = (await adapter.describe()).actions.find((candidate) => candidate.handle === handle);\n      if (!action) return errorResult(`No element for handle \"${handle}\"`);\n      return textResult(`Focused ${handle}`, {\n        handle,\n        rect: (await adapter.rectFor?.(handle)) ?? undefined,\n      });\n    },\n    (args) => target(`Focus ${String(args.handle ?? \"\")}`, String(args.handle ?? \"\")),\n  );\n\n  // ───────────── Navigate / scroll ─────────────\n\n  reg(\n    \"nav_visit\",\n    \"Navigate to a URL (same-site path or absolute). The human watches the page change.\",\n    { url: { type: \"string\", description: \"Path like /packages or an absolute URL.\" } },\n    [\"url\"],\n    async (args) => {\n      const stale = await staleIntent();\n      if (stale) return stale;\n      const url = String(args.url ?? \"\");\n      if (!url) return errorResult(\"url is required\");\n      // Scheme allow-list: permit only same-site/relative paths and http(s)\n      // absolutes. A `javascript:` / `data:` / `file:` / `vbscript:` URL handed\n      // to a host that wires visit() to window.location would execute as the\n      // human — a semi-trusted agent (steerable via page_read prompt injection)\n      // must not reach those.\n      const scheme = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(url)?.[1]?.toLowerCase();\n      if (scheme && scheme !== \"http\" && scheme !== \"https\") {\n        return errorResult(\n          `Refusing to navigate to a '${scheme}:' URL. Only http(s) URLs or same-site paths are allowed.`,\n        );\n      }\n      const from = (await adapter.getLocation()).url;\n      await adapter.visit(url);\n      pushUndoEntry(agent.id, {\n        timestamp: Date.now(),\n        bridgeId: \"navigation\",\n        action: \"nav_visit\",\n        label: `Navigate to ${url}`,\n        undo: () => {\n          adapter.visit(from);\n        },\n        redo: () => {\n          adapter.visit(url);\n        },\n      });\n      return textResult(`Navigated to ${url}`, { url });\n    },\n    (args) => target(`Navigate → ${String(args.url ?? \"\")}`),\n  );\n\n  reg(\n    \"nav_back\",\n    \"Go back to the previous page.\",\n    {},\n    [],\n    async () => {\n      const stale = await staleIntent();\n      if (stale) return stale;\n      if (!adapter.back) return errorResult(\"Host did not provide back navigation.\");\n      await adapter.back();\n      return textResult(\"Went back\");\n    },\n    () => target(\"Back\"),\n  );\n\n  reg(\n    \"nav_forward\",\n    \"Go forward to the next page.\",\n    {},\n    [],\n    async () => {\n      const stale = await staleIntent();\n      if (stale) return stale;\n      if (!adapter.forward) return errorResult(\"Host did not provide forward navigation.\");\n      await adapter.forward();\n      return textResult(\"Went forward\");\n    },\n    () => target(\"Forward\"),\n  );\n\n  reg(\n    \"nav_scroll_to\",\n    \"Scroll the page to absolute coordinates, or to a specific element by its handle.\",\n    {\n      handle: { type: \"string\", description: \"Scroll this element into view.\" },\n      x: { type: \"number\" },\n      y: { type: \"number\" },\n    },\n    [],\n    async (args) => {\n      const stale = await staleIntent();\n      if (stale) return stale;\n      const handle = typeof args.handle === \"string\" ? args.handle : undefined;\n      await adapter.scrollTo({\n        handle,\n        x: typeof args.x === \"number\" ? args.x : undefined,\n        y: typeof args.y === \"number\" ? args.y : undefined,\n      });\n      return textResult(\"Scrolled\", handle ? { handle, rect: (await adapter.rectFor?.(handle)) ?? undefined } : undefined);\n    },\n    () => target(\"Scroll\"),\n  );\n\n  reg(\n    \"nav_scroll_by\",\n    \"Scroll the page by a vertical delta in pixels (negative scrolls up).\",\n    { dy: { type: \"number\" } },\n    [\"dy\"],\n    async (args) => {\n      const stale = await staleIntent();\n      if (stale) return stale;\n      await adapter.scrollBy(Number(args.dy ?? 0));\n      return textResult(`Scrolled by ${Number(args.dy ?? 0)}px`);\n    },\n    () => target(\"Scroll\"),\n  );\n\n  // ───────────── Co-drive (fill / click / submit) ─────────────\n\n  reg(\n    \"page_set_field\",\n    \"Set a form field's value by handle. The host updates the controlled input and the human sees it change.\",\n    {\n      handle: { type: \"string\" },\n      value: { description: \"Value to set; type matches the field.\" },\n    },\n    [\"handle\", \"value\"],\n    async (args) => {\n      const stale = await staleIntent();\n      if (stale) return stale;\n      const handle = String(args.handle ?? \"\");\n      const res = await adapter.setField(handle, args.value);\n      if (!res.ok) return errorResult(res.error ?? `Could not set ${handle}`);\n      return textResult(`${handle} ← ${JSON.stringify(args.value)}`, { handle, value: args.value, rect: (await adapter.rectFor?.(handle)) ?? undefined });\n    },\n    (args) => target(`Set ${String(args.handle ?? \"\")}`, String(args.handle ?? \"\")),\n  );\n\n  reg(\n    \"page_click\",\n    \"Activate an element by handle (link, button, checkbox…). Destructive elements are staged for the human to confirm.\",\n    { handle: { type: \"string\" } },\n    [\"handle\"],\n    async (args) => {\n      const stale = await staleIntent();\n      if (stale) return stale;\n      const handle = String(args.handle ?? \"\");\n      const action = (await adapter.describe()).actions.find((a) => a.handle === handle);\n      const rect = (await adapter.rectFor?.(handle)) ?? undefined; // capture before the click may navigate away\n      if (pendingMode && action?.destructive && adapter.confirm) {\n        const ok = await adapter.confirm({ action: \"click\", handle, label: action.label });\n        if (!ok) return errorResult(\"Declined by user\");\n      }\n      const res = await adapter.click(handle);\n      if (!res.ok) return errorResult(res.error ?? `Could not click ${handle}`);\n      return textResult(`Clicked ${handle}`, { handle, rect });\n    },\n    (args) => target(`Click ${String(args.handle ?? \"\")}`, String(args.handle ?? \"\")),\n  );\n\n  reg(\n    \"page_submit\",\n    \"Submit a form by handle. Always staged for the human to confirm when pendingMode is on.\",\n    { handle: { type: \"string\" } },\n    [\"handle\"],\n    async (args) => {\n      const stale = await staleIntent();\n      if (stale) return stale;\n      const handle = String(args.handle ?? \"\");\n      const rect = (await adapter.rectFor?.(handle)) ?? undefined; // capture before the submit navigates\n      if (pendingMode && adapter.confirm) {\n        const ok = await adapter.confirm({ action: \"submit\", handle, label: handle });\n        if (!ok) return errorResult(\"Declined by user\");\n      }\n      const res = await adapter.submit(handle);\n      if (!res.ok) return errorResult(res.error ?? \"Submit failed\");\n      return textResult(`Submitted ${handle}`, { handle, rect });\n    },\n    (args) => target(`Submit ${String(args.handle ?? \"\")}`, String(args.handle ?? \"\")),\n  );\n\n  return {\n    id: \"navigation\",\n    title: \"Co-browsing\",\n    dispose: () => {\n      for (const d of disposers) d();\n    },\n  };\n}\n"]}

package/dist/dom-navigation/index.d.cts

@@ -0,0 +1,164 @@
+import { PageSnapshot, NavigationConfirmRequest, NavigationBridgeAdapter } from '../bridges/navigation.cjs';
+export { PageAction } from '../bridges/navigation.cjs';
+import '../tool-host-D67N2a2h.cjs';
+import '../types-gzIpsUDE.cjs';
+import '../types-DP5yQZQU.cjs';
+
+/**
+ * The in-page half of DOM co-browsing: a framework-free walker that turns a
+ * live document into a {@link PageSnapshot} of stable handles, and acts on
+ * those handles.
+ *
+ * Extracted from px-ui-sandbox's CoBrowseProvider so a host that does NOT own
+ * the page (Genie's browser, showing sites through an Electron
+ * WebContentsView) can run the same walker, injected into an isolated world.
+ *
+ * Constraints this file holds, because the injected IIFE is built from it:
+ *
+ * - NO runtime imports. Type-only imports are erased; anything else would be
+ *   bundled into a script that must run with no module loader.
+ * - Nothing touches `document` / `window` until a method is called, so the
+ *   script can be evaluated in a context with no DOM at all.
+ * - Every result is plain, structured-cloneable data.
+ *
+ * Trust boundary: the page is hostile input. It controls every attribute,
+ * label and text node read here. Two consequences:
+ * - Sensitive values (passwords, card fields, one-time codes, anything marked
+ *   `data-private`) are masked HERE, before anything leaves the page — the host
+ *   cannot mask what it has already received.
+ * - Handles are compared as plain strings, never spliced into a CSS selector,
+ *   so a crafted handle cannot change what a lookup matches.
+ */
+
+/** Elements the walker considers actionable. */
+declare const INTERACTIVE = "a[href], button, input, select, textarea, [role=button], [role=link], [role=checkbox], [role=tab], [data-co-handle]";
+/** Every method the in-page agent answers. The wire protocol is exactly this list. */
+declare const DOM_NAVIGATION_METHODS: readonly ["getLocation", "describe", "read", "visit", "back", "forward", "scrollTo", "scrollBy", "setField", "click", "submit", "rectFor"];
+type DomNavigationMethod = (typeof DOM_NAVIGATION_METHODS)[number];
+type ActionResult = {
+    ok: boolean;
+    error?: string;
+};
+type HandleRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type FieldElement = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
+declare function isVisible(el: Element): boolean;
+/** Sensitive fields whose value is never read into the snapshot. */
+declare function isSensitive(el: Element): boolean;
+declare function roleOf(el: Element): string;
+declare function accessibleName(el: Element): string;
+declare function isDestructive(el: Element, label: string): boolean;
+/**
+ * The element's own stable handle: data-co-handle → name → id, or "" when it
+ * has none. An EMPTY attribute counts as absent — `button.name` is `""`, not
+ * null, on every button, anchor and input without one, so a plain `??` chain
+ * never reaches the id.
+ */
+declare function attributeHandle(el: Element): string;
+/**
+ * Build a fresh snapshot + a handle→element registry. Handle preference:
+ * data-co-handle → name → id → `role#index` (stable within a snapshot).
+ */
+declare function walk(doc?: Document): {
+    snapshot: PageSnapshot;
+    registry: Map<string, Element>;
+};
+/**
+ * Set a field's value so a React-controlled input sees the change: call the
+ * PROTOTYPE setter (React shadows `value` on the instance with its value
+ * tracker), then dispatch bubbling `input` + `change`.
+ */
+declare function setNativeValue(el: FieldElement, value: unknown): void;
+/** Visible text / heading outline, with sensitive text removed. */
+declare function readPage(doc?: Document): string;
+type DomNavigationAgentOptions = {
+    /** Document to drive. Default: the global `document`, read lazily. */
+    document?: Document;
+    /**
+     * Called just before the agent acts on the page — before resolving a field
+     * for `setField`, and after resolving (only when the element exists) for
+     * `click` / `submit`. The sandbox uses it to attribute the request an action
+     * causes to the agent.
+     */
+    beforeAction?: (action: "setField" | "click" | "submit") => void;
+};
+type DomNavigationAgent = {
+    getLocation(): {
+        url: string;
+        title: string;
+    };
+    describe(): PageSnapshot;
+    read(): string;
+    /** Navigate. Only http(s) or same-site paths; deferred a tick so a remote call returns first. */
+    visit(url: string): void;
+    back(): void;
+    forward(): void;
+    scrollTo(opts: {
+        x?: number;
+        y?: number;
+        handle?: string;
+    }): void;
+    scrollBy(dy: number): void;
+    setField(handle: string, value: unknown): ActionResult;
+    click(handle: string): ActionResult;
+    submit(handle: string): ActionResult;
+    rectFor(handle: string): HandleRect | null;
+    /** Element for a handle: this snapshot's registry, then a live attribute lookup. */
+    resolve(handle: string): Element | null;
+    /** Serialisable dispatch — what the injected script exposes to a host. */
+    call(method: DomNavigationMethod, args?: unknown[]): unknown;
+};
+declare function createDomNavigationAgent(options?: DomNavigationAgentOptions): DomNavigationAgent;
+
+/**
+ * The host half: a {@link NavigationBridgeAdapter} that drives a page it does
+ * not run in, through any transport that can carry a method name and plain
+ * arguments into the page and a plain result back — Electron's
+ * `executeJavaScript` / `executeJavaScriptInIsolatedWorld`, a MessagePort, a
+ * WebSocket to a remote browser.
+ *
+ * Every result is treated as hostile: the page owns the DOM the in-page walker
+ * reads, and if the script was injected into the MAIN world the page can
+ * replace the walker outright. So results are coerced to the declared shapes
+ * here, and anything malformed is dropped rather than passed on to the agent.
+ */
+
+/** The global the injected script installs in the world it runs in. */
+declare const DOM_NAVIGATION_GLOBAL = "__fancyDomNavigation";
+/** Bumped only if the wire protocol changes incompatibly. */
+declare const DOM_NAVIGATION_PROTOCOL = 1;
+/**
+ * Carries one call into the page. `args` and the resolved value are plain,
+ * structured-cloneable data. Reject (or throw) when the call could not be
+ * delivered — e.g. the page navigated and the script must be re-injected.
+ */
+type DomNavigationTransport = {
+    call(method: DomNavigationMethod, args: unknown[]): Promise<unknown>;
+};
+type RemoteNavigationAdapterOptions = {
+    transport: DomNavigationTransport;
+    /** Optional fancy-screens screen id for presence targeting. */
+    screenId?: string;
+    /** Human-control revision, if the host tracks one. Omit to disable stale-intent protection. */
+    getRevision?: () => number | Promise<number>;
+    /**
+     * Trust-but-verify. Without it, `page_submit` and destructive `page_click`
+     * are NOT staged — they run as soon as the agent asks. A host showing pages
+     * it does not own should always supply one.
+     */
+    confirm?: (req: NavigationConfirmRequest) => Promise<boolean>;
+};
+/**
+ * A JavaScript expression that performs one call against the injected global —
+ * what a host passes to `executeJavaScript`. Arguments are embedded as JSON,
+ * which is a valid JS expression, so no argument can break out of its literal.
+ */
+declare function domNavigationCallScript(method: DomNavigationMethod, args?: unknown[]): string;
+/** Build a NavigationBridgeAdapter backed by a transport into the page. */
+declare function createRemoteNavigationAdapter(options: RemoteNavigationAdapterOptions): NavigationBridgeAdapter;
+
+export { type ActionResult, DOM_NAVIGATION_GLOBAL, DOM_NAVIGATION_METHODS, DOM_NAVIGATION_PROTOCOL, type DomNavigationAgent, type DomNavigationAgentOptions, type DomNavigationMethod, type DomNavigationTransport, type HandleRect, INTERACTIVE, NavigationBridgeAdapter, NavigationConfirmRequest, PageSnapshot, type RemoteNavigationAdapterOptions, accessibleName, attributeHandle, createDomNavigationAgent, createRemoteNavigationAdapter, domNavigationCallScript, isDestructive, isSensitive, isVisible, readPage, roleOf, setNativeValue, walk };

package/dist/dom-navigation/index.d.ts

@@ -0,0 +1,164 @@
+import { PageSnapshot, NavigationConfirmRequest, NavigationBridgeAdapter } from '../bridges/navigation.js';
+export { PageAction } from '../bridges/navigation.js';
+import '../tool-host-LYfdPE8u.js';
+import '../types-gzIpsUDE.js';
+import '../types-VX_9je7w.js';
+
+/**
+ * The in-page half of DOM co-browsing: a framework-free walker that turns a
+ * live document into a {@link PageSnapshot} of stable handles, and acts on
+ * those handles.
+ *
+ * Extracted from px-ui-sandbox's CoBrowseProvider so a host that does NOT own
+ * the page (Genie's browser, showing sites through an Electron
+ * WebContentsView) can run the same walker, injected into an isolated world.
+ *
+ * Constraints this file holds, because the injected IIFE is built from it:
+ *
+ * - NO runtime imports. Type-only imports are erased; anything else would be
+ *   bundled into a script that must run with no module loader.
+ * - Nothing touches `document` / `window` until a method is called, so the
+ *   script can be evaluated in a context with no DOM at all.
+ * - Every result is plain, structured-cloneable data.
+ *
+ * Trust boundary: the page is hostile input. It controls every attribute,
+ * label and text node read here. Two consequences:
+ * - Sensitive values (passwords, card fields, one-time codes, anything marked
+ *   `data-private`) are masked HERE, before anything leaves the page — the host
+ *   cannot mask what it has already received.
+ * - Handles are compared as plain strings, never spliced into a CSS selector,
+ *   so a crafted handle cannot change what a lookup matches.
+ */
+
+/** Elements the walker considers actionable. */
+declare const INTERACTIVE = "a[href], button, input, select, textarea, [role=button], [role=link], [role=checkbox], [role=tab], [data-co-handle]";
+/** Every method the in-page agent answers. The wire protocol is exactly this list. */
+declare const DOM_NAVIGATION_METHODS: readonly ["getLocation", "describe", "read", "visit", "back", "forward", "scrollTo", "scrollBy", "setField", "click", "submit", "rectFor"];
+type DomNavigationMethod = (typeof DOM_NAVIGATION_METHODS)[number];
+type ActionResult = {
+    ok: boolean;
+    error?: string;
+};
+type HandleRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type FieldElement = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
+declare function isVisible(el: Element): boolean;
+/** Sensitive fields whose value is never read into the snapshot. */
+declare function isSensitive(el: Element): boolean;
+declare function roleOf(el: Element): string;
+declare function accessibleName(el: Element): string;
+declare function isDestructive(el: Element, label: string): boolean;
+/**
+ * The element's own stable handle: data-co-handle → name → id, or "" when it
+ * has none. An EMPTY attribute counts as absent — `button.name` is `""`, not
+ * null, on every button, anchor and input without one, so a plain `??` chain
+ * never reaches the id.
+ */
+declare function attributeHandle(el: Element): string;
+/**
+ * Build a fresh snapshot + a handle→element registry. Handle preference:
+ * data-co-handle → name → id → `role#index` (stable within a snapshot).
+ */
+declare function walk(doc?: Document): {
+    snapshot: PageSnapshot;
+    registry: Map<string, Element>;
+};
+/**
+ * Set a field's value so a React-controlled input sees the change: call the
+ * PROTOTYPE setter (React shadows `value` on the instance with its value
+ * tracker), then dispatch bubbling `input` + `change`.
+ */
+declare function setNativeValue(el: FieldElement, value: unknown): void;
+/** Visible text / heading outline, with sensitive text removed. */
+declare function readPage(doc?: Document): string;
+type DomNavigationAgentOptions = {
+    /** Document to drive. Default: the global `document`, read lazily. */
+    document?: Document;
+    /**
+     * Called just before the agent acts on the page — before resolving a field
+     * for `setField`, and after resolving (only when the element exists) for
+     * `click` / `submit`. The sandbox uses it to attribute the request an action
+     * causes to the agent.
+     */
+    beforeAction?: (action: "setField" | "click" | "submit") => void;
+};
+type DomNavigationAgent = {
+    getLocation(): {
+        url: string;
+        title: string;
+    };
+    describe(): PageSnapshot;
+    read(): string;
+    /** Navigate. Only http(s) or same-site paths; deferred a tick so a remote call returns first. */
+    visit(url: string): void;
+    back(): void;
+    forward(): void;
+    scrollTo(opts: {
+        x?: number;
+        y?: number;
+        handle?: string;
+    }): void;
+    scrollBy(dy: number): void;
+    setField(handle: string, value: unknown): ActionResult;
+    click(handle: string): ActionResult;
+    submit(handle: string): ActionResult;
+    rectFor(handle: string): HandleRect | null;
+    /** Element for a handle: this snapshot's registry, then a live attribute lookup. */
+    resolve(handle: string): Element | null;
+    /** Serialisable dispatch — what the injected script exposes to a host. */
+    call(method: DomNavigationMethod, args?: unknown[]): unknown;
+};
+declare function createDomNavigationAgent(options?: DomNavigationAgentOptions): DomNavigationAgent;
+
+/**
+ * The host half: a {@link NavigationBridgeAdapter} that drives a page it does
+ * not run in, through any transport that can carry a method name and plain
+ * arguments into the page and a plain result back — Electron's
+ * `executeJavaScript` / `executeJavaScriptInIsolatedWorld`, a MessagePort, a
+ * WebSocket to a remote browser.
+ *
+ * Every result is treated as hostile: the page owns the DOM the in-page walker
+ * reads, and if the script was injected into the MAIN world the page can
+ * replace the walker outright. So results are coerced to the declared shapes
+ * here, and anything malformed is dropped rather than passed on to the agent.
+ */
+
+/** The global the injected script installs in the world it runs in. */
+declare const DOM_NAVIGATION_GLOBAL = "__fancyDomNavigation";
+/** Bumped only if the wire protocol changes incompatibly. */
+declare const DOM_NAVIGATION_PROTOCOL = 1;
+/**
+ * Carries one call into the page. `args` and the resolved value are plain,
+ * structured-cloneable data. Reject (or throw) when the call could not be
+ * delivered — e.g. the page navigated and the script must be re-injected.
+ */
+type DomNavigationTransport = {
+    call(method: DomNavigationMethod, args: unknown[]): Promise<unknown>;
+};
+type RemoteNavigationAdapterOptions = {
+    transport: DomNavigationTransport;
+    /** Optional fancy-screens screen id for presence targeting. */
+    screenId?: string;
+    /** Human-control revision, if the host tracks one. Omit to disable stale-intent protection. */
+    getRevision?: () => number | Promise<number>;
+    /**
+     * Trust-but-verify. Without it, `page_submit` and destructive `page_click`
+     * are NOT staged — they run as soon as the agent asks. A host showing pages
+     * it does not own should always supply one.
+     */
+    confirm?: (req: NavigationConfirmRequest) => Promise<boolean>;
+};
+/**
+ * A JavaScript expression that performs one call against the injected global —
+ * what a host passes to `executeJavaScript`. Arguments are embedded as JSON,
+ * which is a valid JS expression, so no argument can break out of its literal.
+ */
+declare function domNavigationCallScript(method: DomNavigationMethod, args?: unknown[]): string;
+/** Build a NavigationBridgeAdapter backed by a transport into the page. */
+declare function createRemoteNavigationAdapter(options: RemoteNavigationAdapterOptions): NavigationBridgeAdapter;
+
+export { type ActionResult, DOM_NAVIGATION_GLOBAL, DOM_NAVIGATION_METHODS, DOM_NAVIGATION_PROTOCOL, type DomNavigationAgent, type DomNavigationAgentOptions, type DomNavigationMethod, type DomNavigationTransport, type HandleRect, INTERACTIVE, NavigationBridgeAdapter, NavigationConfirmRequest, PageSnapshot, type RemoteNavigationAdapterOptions, accessibleName, attributeHandle, createDomNavigationAgent, createRemoteNavigationAdapter, domNavigationCallScript, isDestructive, isSensitive, isVisible, readPage, roleOf, setNativeValue, walk };

package/dist/dom-navigation/script.d.cts

@@ -0,0 +1,3 @@
+declare const DOM_NAVIGATION_SCRIPT: string;
+
+export { DOM_NAVIGATION_SCRIPT };

package/dist/dom-navigation/script.d.ts

@@ -0,0 +1,3 @@
+declare const DOM_NAVIGATION_SCRIPT: string;
+
+export { DOM_NAVIGATION_SCRIPT };