@particle-academy/agent-integrations 0.46.0 → 0.47.1

package/dist/chunk-OHNGURUJ.js

@@ -0,0 +1,317 @@
+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" };
+var isControl = (code) => code < 32 || code >= 127 && code <= 159 || code === 8232 || code === 8233;
+function oneLine(value, max) {
+  const raw = typeof value === "string" ? value : value == null ? "" : String(value);
+  const bounded = raw.length > max * 4 ? raw.slice(0, max * 4) : raw;
+  let out = "";
+  for (const c of bounded) out += isControl(c.charCodeAt(0)) ? " " : c;
+  out = out.replace(/\s+/g, " ").trim();
+  return out.length > max ? out.slice(0, max - 3) + "..." : out;
+}
+var SAFE_HANDLE = /^[A-Za-z0-9_.:#@/-]{1,80}$/;
+var CAP = { url: 500, title: 200, role: 40, label: 200, heading: 200, text: 4e3, error: 300, headings: 50 };
+function formatReadout(r) {
+  if (typeof r === "string") return oneLine(r, CAP.text);
+  const headings = (Array.isArray(r.headings) ? r.headings : []).slice(0, CAP.headings).map((h) => `H${Math.min(6, Math.max(1, Math.trunc(Number(h?.level)) || 1))}: ${oneLine(h?.text, CAP.heading)}`);
+  return [oneLine(r.title, CAP.title), ...headings, "", oneLine(r.text, CAP.text)].join("\n");
+}
+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;
+  };
+  let aliases = /* @__PURE__ */ new Map();
+  const pageHandle = (handle) => aliases.get(handle) ?? handle;
+  const failure = (message, fallback) => errorResult(oneLine(message ?? fallback, CAP.error) || fallback);
+  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 failure(e instanceof Error ? e.message : String(e), `${name} failed`);
+      }
+    };
+    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 raw = await adapter.describe();
+      const next = /* @__PURE__ */ new Map();
+      const actions = (Array.isArray(raw.actions) ? raw.actions : []).map((a) => {
+        const handle = String(a.handle ?? "");
+        if (SAFE_HANDLE.test(handle)) return a;
+        const alias = `~${next.size}`;
+        next.set(alias, handle);
+        return { ...a, handle: alias };
+      });
+      aliases = next;
+      const snap = { ...raw, actions };
+      const revision = await adapter.getRevision?.();
+      if (revision !== void 0) {
+        snap.revision = revision;
+        groundedRevision = revision;
+      }
+      const text = [
+        `URL: ${oneLine(snap.url, CAP.url)}`,
+        `Title: ${oneLine(snap.title, CAP.title)}`,
+        "",
+        ...actions.map(
+          (a) => `[${a.handle}] ${oneLine(a.role, CAP.role)}: ${oneLine(a.label, CAP.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 () => {
+      const r = adapter.read ? await adapter.read() : void 0;
+      return textResult(r == null ? "(host did not provide page text)" : formatReadout(r));
+    },
+    () => 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 shown = String(args.handle ?? "");
+      const handle = pageHandle(shown);
+      const action = (await adapter.describe()).actions.find((candidate) => candidate.handle === handle);
+      if (!action) return failure(`No element for handle "${shown}"`, "No element for that handle");
+      return textResult(`Focused ${oneLine(shown, CAP.label)}`, {
+        handle: shown,
+        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 shown = typeof args.handle === "string" ? args.handle : void 0;
+      const handle = shown === void 0 ? void 0 : pageHandle(shown);
+      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: shown, 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 shown = String(args.handle ?? "");
+      const handle = pageHandle(shown);
+      const res = await adapter.setField(handle, args.value);
+      if (!res.ok) return failure(res.error, `Could not set ${oneLine(shown, CAP.label)}`);
+      return textResult(`${oneLine(shown, CAP.label)} \u2190 ${JSON.stringify(args.value)}`, {
+        handle: shown,
+        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 shown = String(args.handle ?? "");
+      const handle = pageHandle(shown);
+      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 failure(res.error, `Could not click ${oneLine(shown, CAP.label)}`);
+      return textResult(`Clicked ${oneLine(shown, CAP.label)}`, { handle: shown, 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 shown = String(args.handle ?? "");
+      const handle = pageHandle(shown);
+      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 failure(res.error, "Submit failed");
+      return textResult(`Submitted ${oneLine(shown, CAP.label)}`, { handle: shown, 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-OHNGURUJ.js.map
+//# sourceMappingURL=chunk-OHNGURUJ.js.map

package/dist/chunk-OHNGURUJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/bridges/navigation.ts"],"names":[],"mappings":"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","file":"chunk-OHNGURUJ.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/**\n * Structured page text. Preferred over a plain string from `read()`: the bridge\n * can then put every page-supplied string on its own single line and keep the\n * outline. A plain string is untrusted as a whole and is rendered as ONE line.\n */\nexport type PageReadout = {\n  title: string;\n  headings: Array<{ level: number; text: string }>;\n  text: string;\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). Prefer a {@link PageReadout}. */\n  read?: () => MaybePromise<string | PageReadout>;\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// ───────────── Text safety ─────────────\n//\n// Every string below the adapter is page-supplied, and the page may be hostile.\n// The tool TEXT is what lands in the agent's context, so a line break inside a\n// label would let the page write its own lines there: a forged action, a forged\n// heading, forged tool framing. Each page string is therefore rendered on ONE\n// line, with C0/C1 controls and the Unicode line/paragraph separators replaced,\n// and capped. (Control characters are tested by code point, so no escape\n// sequence is involved.)\n\nconst isControl = (code: number) =>\n  code < 0x20 || (code >= 0x7f && code <= 0x9f) || code === 0x2028 || code === 0x2029;\n\n/** One line, controls replaced by spaces, whitespace collapsed, capped at `max`. */\nfunction oneLine(value: unknown, max: number): string {\n  const raw = typeof value === \"string\" ? value : value == null ? \"\" : String(value);\n  // Bound the work on a hostile multi-megabyte string before scanning it.\n  const bounded = raw.length > max * 4 ? raw.slice(0, max * 4) : raw;\n  let out = \"\";\n  for (const c of bounded) out += isControl(c.charCodeAt(0)) ? \" \" : c;\n  out = out.replace(/\\s+/g, \" \").trim();\n  return out.length > max ? out.slice(0, max - 3) + \"...\" : out;\n}\n\n/**\n * A handle shown verbatim must not be able to imitate the `[handle] role:`\n * syntax, so only this charset is shown as-is. Anything else — spaces,\n * brackets, controls, or a `~`, which is reserved so a page cannot squat on an\n * alias — is shown as a bridge-minted `~N` alias that resolves back to it.\n */\nconst SAFE_HANDLE = /^[A-Za-z0-9_.:#@/-]{1,80}$/;\n\nconst CAP = { url: 500, title: 200, role: 40, label: 200, heading: 200, text: 4000, error: 300, headings: 50 };\n\nfunction formatReadout(r: string | PageReadout): string {\n  if (typeof r === \"string\") return oneLine(r, CAP.text);\n  const headings = (Array.isArray(r.headings) ? r.headings : [])\n    .slice(0, CAP.headings)\n    .map((h) => `H${Math.min(6, Math.max(1, Math.trunc(Number(h?.level)) || 1))}: ${oneLine(h?.text, CAP.heading)}`);\n  return [oneLine(r.title, CAP.title), ...headings, \"\", oneLine(r.text, CAP.text)].join(\"\\n\");\n}\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  /** Alias → page handle, from the latest page_describe. */\n  let aliases = new Map<string, string>();\n  /** The handle the adapter knows, for a handle the agent passed back. */\n  const pageHandle = (handle: string) => aliases.get(handle) ?? handle;\n  /** A failure message that may carry page-supplied text. */\n  const failure = (message: unknown, fallback: string) => errorResult(oneLine(message ?? fallback, CAP.error) || fallback);\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        // A transport into the page can surface the page's own error text.\n        return failure(e instanceof Error ? e.message : String(e), `${name} failed`);\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 raw = await adapter.describe();\n      const next = new Map<string, string>();\n      const actions = (Array.isArray(raw.actions) ? raw.actions : []).map((a) => {\n        const handle = String(a.handle ?? \"\");\n        if (SAFE_HANDLE.test(handle)) return a;\n        const alias = `~${next.size}`;\n        next.set(alias, handle);\n        return { ...a, handle: alias };\n      });\n      aliases = next;\n      const snap: PageSnapshot = { ...raw, actions };\n      const revision = await adapter.getRevision?.();\n      if (revision !== undefined) {\n        snap.revision = revision;\n        groundedRevision = revision;\n      }\n      const text = [\n        `URL: ${oneLine(snap.url, CAP.url)}`,\n        `Title: ${oneLine(snap.title, CAP.title)}`,\n        \"\",\n        ...actions.map(\n          (a) =>\n            `[${a.handle}] ${oneLine(a.role, CAP.role)}: ${oneLine(a.label, CAP.label)}${a.destructive ? \" (destructive)\" : \"\"}`,\n        ),\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 () => {\n      const r = adapter.read ? await adapter.read() : undefined;\n      return textResult(r == null ? \"(host did not provide page text)\" : formatReadout(r));\n    },\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 shown = String(args.handle ?? \"\");\n      const handle = pageHandle(shown);\n      const action = (await adapter.describe()).actions.find((candidate) => candidate.handle === handle);\n      if (!action) return failure(`No element for handle \"${shown}\"`, \"No element for that handle\");\n      return textResult(`Focused ${oneLine(shown, CAP.label)}`, {\n        handle: shown,\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 shown = typeof args.handle === \"string\" ? args.handle : undefined;\n      const handle = shown === undefined ? undefined : pageHandle(shown);\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(\n        \"Scrolled\",\n        handle ? { handle: shown, rect: (await adapter.rectFor?.(handle)) ?? undefined } : undefined,\n      );\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 shown = String(args.handle ?? \"\");\n      const handle = pageHandle(shown);\n      const res = await adapter.setField(handle, args.value);\n      if (!res.ok) return failure(res.error, `Could not set ${oneLine(shown, CAP.label)}`);\n      return textResult(`${oneLine(shown, CAP.label)} ← ${JSON.stringify(args.value)}`, {\n        handle: shown,\n        value: args.value,\n        rect: (await adapter.rectFor?.(handle)) ?? undefined,\n      });\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 shown = String(args.handle ?? \"\");\n      const handle = pageHandle(shown);\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 failure(res.error, `Could not click ${oneLine(shown, CAP.label)}`);\n      return textResult(`Clicked ${oneLine(shown, CAP.label)}`, { handle: shown, 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 shown = String(args.handle ?? \"\");\n      const handle = pageHandle(shown);\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 failure(res.error, \"Submit failed\");\n      return textResult(`Submitted ${oneLine(shown, CAP.label)}`, { handle: shown, 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,175 @@
+import { PageSnapshot, PageReadout, 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.
+ *
+ * - Text, textarea, select: call the PROTOTYPE `value` setter (React shadows
+ *   `value` on the instance with its value tracker), then dispatch bubbling
+ *   `input` + `change`.
+ * - Checkbox, radio: React's onChange for these listens to `click`, not
+ *   `input` / `change`, so the write is a real `click()` — the browser toggles
+ *   the box and fires click, input and change itself. Only when the state
+ *   actually differs, so setting the current value is a no-op rather than a
+ *   toggle. A radio cannot be unchecked by clicking it; that one case falls
+ *   back to the setter.
+ */
+declare function setNativeValue(el: FieldElement, value: unknown): void;
+/**
+ * Visible text / heading outline, with sensitive text removed. Structured, so
+ * the bridge can render each page-supplied string on its own single line.
+ */
+declare function readPage(doc?: Document): PageReadout;
+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(): PageReadout;
+    /** 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, PageReadout, PageSnapshot, type RemoteNavigationAdapterOptions, accessibleName, attributeHandle, createDomNavigationAgent, createRemoteNavigationAdapter, domNavigationCallScript, isDestructive, isSensitive, isVisible, readPage, roleOf, setNativeValue, walk };