iframer-toolkit 0.10.8 → 0.11.0

package/extension/native-host.cjs

@@ -12,9 +12,16 @@
 // stdlib) and must read the same secret locations as src/lib/auth/crypto.ts.
 
 const fs = require("fs");
+const http = require("http");
 const os = require("os");
 const path = require("path");
 
+// Same window the local server allocates its port from
+// (src/mcp/local-server.ts, extension/background.js).
+const PORT_START = 3022;
+const PORT_END = 3042;
+const PROBE_TIMEOUT_MS = 1500;
+
 function readToken() {
   if (process.env.IFRAMER_SECRET) return process.env.IFRAMER_SECRET;
   const dataDir = process.env.IFRAMER_DATA_DIR || path.join(os.homedir(), ".iframer");
@@ -33,34 +40,107 @@ function readToken() {
   return "";
 }
 
-// Where is the iframer server right now? Reads the server registry the local
-// server writes on startup (src/lib/browser/registry.ts) and checks the pid is
-// actually alive — so the extension can connect straight to the right port
-// instead of blind-scanning 21 ports (each dead dial logs a console error).
-function readServerInfo() {
+function readRegisteredPort() {
   const dataDir = process.env.IFRAMER_DATA_DIR || path.join(os.homedir(), ".iframer");
   try {
     const info = JSON.parse(fs.readFileSync(path.join(dataDir, "server.json"), "utf8"));
-    let alive = false;
-    if (info && typeof info.pid === "number") {
-      try {
-        process.kill(info.pid, 0);
-        alive = true;
-      } catch {
-        /* pid gone — stale registry */
-      }
-    }
-    return { port: info && typeof info.port === "number" ? info.port : null, alive };
+    return info && typeof info.port === "number" ? info.port : null;
   } catch {
-    return { port: null, alive: false };
+    return null;
   }
 }
 
-function send(msg) {
+function probe(port) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (ok) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(ok);
+    };
+    const req = http.get({ host: "127.0.0.1", port, path: "/health", agent: false }, (res) => {
+      let body = "";
+      res.setEncoding("utf8");
+      res.on("data", (d) => {
+        if (body.length < 4096) body += d;
+      });
+      res.on("end", () => {
+        try {
+          finish(JSON.parse(body).ok === true);
+        } catch {
+          finish(false);
+        }
+      });
+      res.on("error", () => finish(false));
+    });
+    req.on("error", () => finish(false));
+    const timer = setTimeout(() => {
+      req.destroy();
+      finish(false);
+    }, PROBE_TIMEOUT_MS);
+  });
+}
+
+// Where is the iframer server right now? Only a server that actually answers
+// counts. A pid check can't decide this: on Windows a reused pid looks alive,
+// and a server running as another user looks dead. Probing from here also lets
+// the extension find the port without dialing dead ones (each dead dial logs a
+// console error in the extension).
+async function locateServer() {
+  const registered = readRegisteredPort();
+  if (registered && (await probe(registered))) return { port: registered, alive: true };
+
+  const ports = [];
+  for (let p = PORT_START; p <= PORT_END; p++) if (p !== registered) ports.push(p);
+  // All at once: Windows takes about 2s to refuse a closed port, one by one
+  // would take most of a minute.
+  const found = await new Promise((resolve) => {
+    let left = ports.length;
+    for (const p of ports) {
+      probe(p).then((ok) => {
+        if (ok) resolve(p);
+        else if (--left === 0) resolve(null);
+      });
+    }
+  });
+  return found ? { port: found, alive: true } : { port: registered, alive: false };
+}
+
+function send(msg, done) {
   const payload = Buffer.from(JSON.stringify(msg), "utf8");
   const header = Buffer.alloc(4);
   header.writeUInt32LE(payload.length, 0);
-  process.stdout.write(Buffer.concat([header, payload]));
+  process.stdout.write(Buffer.concat([header, payload]), done);
+}
+
+// Chrome may close stdin while a reply is still being worked out, so exit only
+// once stdin has ended AND every reply has been written.
+let pending = 0;
+let stdinEnded = false;
+function exitIfDone() {
+  if (stdinEnded && pending === 0) process.exit(0);
+}
+
+async function reply(msg) {
+  let out;
+  try {
+    if (msg && msg.cmd === "get-token") {
+      const token = readToken();
+      out = token ? { ok: true, token } : { ok: false, error: "no secret file found — run any iframer command once to create it" };
+    } else if (msg && msg.cmd === "get-info") {
+      // Token + live server location in one call.
+      out = { ok: true, token: readToken() || null, ...(await locateServer()) };
+    } else {
+      out = { ok: false, error: "unknown command" };
+    }
+  } catch (e) {
+    out = { ok: false, error: String((e && e.message) || e) };
+  }
+  send(out, () => {
+    pending--;
+    exitIfDone();
+  });
 }
 
 let buf = Buffer.alloc(0);
@@ -75,17 +155,13 @@ process.stdin.on("data", (chunk) => {
     try {
       msg = JSON.parse(body.toString("utf8"));
     } catch {
-      /* respond with error below */
-    }
-    if (msg && msg.cmd === "get-token") {
-      const token = readToken();
-      send(token ? { ok: true, token } : { ok: false, error: "no secret file found — run any iframer command once to create it" });
-    } else if (msg && msg.cmd === "get-info") {
-      // Token + live server location in one call.
-      send({ ok: true, token: readToken() || null, ...readServerInfo() });
-    } else {
-      send({ ok: false, error: "unknown command" });
+      /* answered as an unknown command */
     }
+    pending++;
+    reply(msg);
   }
 });
-process.stdin.on("end", () => process.exit(0));
+process.stdin.on("end", () => {
+  stdinEnded = true;
+  exitIfDone();
+});

package/extension/popup.js

@@ -15,10 +15,10 @@ function renderStatus(status) {
   const connected = status && status.connected;
   $("dot").className = "dot" + (connected ? " on" : "");
   const reasonText = {
-    "no-token": "No token set — try Pair automatically, or paste it below.",
-    "server-not-found": "iframer server not found. Is Claude Code / iframer running?",
+    "no-token": "No token yet. Run `iframer install extension chrome` in a terminal and this pairs by itself, or paste the output of `iframer extension token` below.",
+    "server-not-found": "iframer server not found. It starts with your Claude/iframer session. Will connect by itself.",
     "server-not-running": "iframer server not running — it starts with your Claude/iframer session. Will connect by itself.",
-    "bad-token": "Token rejected. Check it matches ~/.iframer/secret.",
+    "bad-token": "Token rejected by the server. Paste the output of `iframer extension token` below.",
     disconnected: "Disconnected — retrying…",
   };
   if (connected) {
@@ -86,7 +86,7 @@ $("autopair").addEventListener("click", async () => {
   const res = await send("auto-pair");
   if (res.ok) {
     if (res.token) $("token").value = res.token;
-    $("pairmsg").textContent = "✓ Paired.";
+    $("pairmsg").textContent = res.status && res.status.connected ? "✓ Paired." : "Token saved. See the status above.";
     renderStatus(res.status);
   } else {
     $("pairmsg").textContent = res.error || "Auto-pair failed — paste the token manually below.";
@@ -105,4 +105,13 @@ $("save").addEventListener("click", async () => {
   $("save").textContent = "Save & connect";
 });
 
+// Keep the popup live: pairing usually finishes while it's open.
+chrome.storage.onChanged.addListener((changes, area) => {
+  if (area !== "local") return;
+  if (changes.status) renderStatus(changes.status.newValue);
+  if (changes.token && changes.token.newValue && document.activeElement !== $("token")) {
+    $("token").value = changes.token.newValue;
+  }
+});
+
 init();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iframer-toolkit",
-  "version": "0.10.8",
+  "version": "0.11.0",
   "description": "Browser access toolkit for AI agents — CLI and MCP server for headless/headful browsing, login flows, and pipeline execution.",
   "keywords": [
     "iframer",
@@ -39,9 +39,6 @@
   },
   "scripts": {
     "start": "bun run index.ts",
-    "start:docker": "docker compose up --build -d",
-    "stop:docker": "docker compose down",
-    "logs:docker": "docker compose logs -f api",
     "test:smoke": "node tests/smoke.js",
     "mcp:install": "node bin/cli.js install-mcp",
     "mcp:remove": "node bin/cli.js remove-mcp",
@@ -50,13 +47,13 @@
     "test": "bun test tests/unit",
     "test:extension": "node tests/integration/extension-bridge.mjs",
     "prepublishOnly": "bun run build",
-    "test:cdp-relay": "bun tests/integration/cdp-relay.mjs"
+    "test:cdp-relay": "bun tests/integration/cdp-relay.mjs",
+    "test:kit": "bun tests/integration/kit-bridge.mjs"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.80.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^12.8.0",
-    "fingerprint-generator": "^2.1.81",
     "patchright": "^1.58.2",
     "playwright-core": "^1.58.0",
     "ws": "^8.18.0",

package/skills/iframer.md

@@ -10,10 +10,12 @@ You are an expert at using the iframer browser automation toolkit. The user want
 - `iframer.credentials` — list or store login credentials (NEVER re-store as recovery)
 - `iframer.execute` — run a browser pipeline (navigate, login, screenshot, snapshot, etc.)
 - `iframer.browse` — fast headless page fetch (no pipeline needed)
-- `iframer.session` — stop (save state) or clear session data
+- `iframer.session` — stop (save state, close the browser), clear (wipe session data), restart (recover from a freeze or crash), capture-start / capture-stop (record XHR/fetch), get-cookies, get-auth
 - `iframer.status` — system health, modes, stored credentials
 - `iframer.reverse-engineer` — capture API calls a site makes
 - `iframer.tabs` — list/open tabs in the user's REAL Chrome (needs the extension)
+- `iframer.remember` — per-domain element anchors, targeted as `@a:<name>` in any selector
+- `iframer.clipboard` — read/write the machine's clipboard (same one the user's Chrome uses)
 
 ## Core rules
 
@@ -39,7 +41,8 @@ The `execute` tool takes a `steps` array. Each step is an object with a `type` f
 | `snapshot` | — | Get interactive elements as structured list with @e refs. **Do this BEFORE interacting.** Fields no human can reach (honeypots pushed offscreen/clipped/transparent by an ancestor) are omitted; bait-looking ones (`website`, `fax`, tabindex=-1) are marked `[honeypot?]` — leave those empty unless the task clearly needs them. |
 | `find` | `role?`, `name?`, `text?`, `placeholder?`, `label?` | Find a specific element, returns a ref |
 | `screenshot` | `annotate?` | Take a screenshot. `annotate: true` overlays numbered badges. |
-| `click` | `selector` | Click element (use @e refs from snapshot/find). Text selectors (`text=`, `:has-text()`, `:text-is()`) are rejected: `find` by text, then click the ref. |
+| `click` | `selector` | Click element (use @e refs from snapshot/find). Text selectors (`text=`, `:has-text()`, `:text-is()`, `>>`) are rejected: `find` by text, then click the ref. |
+| `right-click` | `selector` or `x`, `y` | Right-click an element or coordinates |
 | `fill` | `selector`, `value`, `force?` | Fill input (use @e refs). Refuses honeypot fields (unreachable by a human) with an explanatory error — skip the field. `force: true` bypasses, only when you are certain it is real. |
 | `human-click` | `selector` or `x`, `y` | Human-like click with random offset |
 | `human-type` | `selector`, `value`, `clear?` | Human-like typing with variable delays. Appends by default; `clear: true` replaces the existing text. |
@@ -49,13 +52,19 @@ The `execute` tool takes a `steps` array. Each step is an object with a `type` f
 | `evaluate` | `expression` | Run JS, return result |
 | `extract` | `expression` | Run JS, include result in response |
 | `keyboard` | `key`, `meta?`, `ctrl?` | Press a key (Enter, Escape, Tab, etc.). Cmd/Ctrl+A selects all everywhere; other Cmd/Ctrl shortcuts are refused in extension mode. |
-| `solve-captcha` | — | Auto-detect and solve reCAPTCHA or hCaptcha |
+| `select` | `selector`, `value` | Pick an option in a native `<select>`, with real change events. Never set `.value` via `evaluate`. |
+| `type-code` | `value`, `selector?` | Type a verification code digit by digit. Default target: `input[type="tel"]`. |
+| `upload` | `selector`, `files` | Set absolute local file paths on an `<input type=file>` |
+| `paste` | `selector?` | Paste the OS clipboard into a field, or the focused element if omitted. More reliable than a ⌘V `keyboard` step. |
+| `download` | `url`, `path?` | Fetch a file with the browser's cookies and save it server-side, no Save-As dialog. Default path: `~/.iframer/downloads/<name>`. |
+| `solve-captcha` | — | Best-effort reCAPTCHA or hCaptcha solve with vision AI. Works in any mode; needs `ANTHROPIC_API_KEY`. Fails the run with `captcha-unsolvable` if it can't solve it. |
+| `recaptcha` | `action`, `tiles?` | Manual captcha control: `info`, `click`, `answer`, `select`, `verify`, `solve`. The full workflow arrives in the result when a captcha blocks a run. |
 
 ### Pipeline options
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `mode` | auto | `headless`, `binary-headful`, `docker-headful`. Omit for auto-select + auto-escalation. |
+| `mode` | auto | `headless`, `binary-headful`. Omit for auto-select + auto-escalation. |
 | `captureApi` | false | Record all XHR/fetch requests. Use for reverse-engineering, and when a form submit fails with only a vague on-page message: every HTTP >= 400 response is reported per step, so you read the server's real answer (e.g. `POST /api/apply → 422: {"error":"..."}`) instead of guessing. |
 | `staleTimeoutMs` | 20000 | Per-step stale-state timeout |
 | `continueOnError` | false | Don't abort pipeline on step failure |
@@ -157,6 +166,24 @@ execute: steps: [{ type: "click", selector: "@e3" }, { type: "screenshot" }]
 
 The more interactions (scroll, click tabs, navigate sub-pages), the more API calls get captured. Results feed into the knowledge cache automatically.
 
+### Reverse-engineer inside a browser iframer doesn't control (T3 Code, Playwright MCP, ...)
+
+When you already drive a browser through your own tools (a T3 Code preview tab, Playwright MCP, Chrome DevTools MCP), don't launch iframer's browser: load the in-page kit into that tab. It records the page's own calls on the user's real session and exports shapes, never values. Use the CLI for this, not the MCP tools.
+
+```
+1. iframer kit --for t3          # or --for playwright-mcp / --for any. Prints the exact tool calls.
+2. Follow the printed install steps (upload the kit file, stash it, top-level eval). Never paste the kit's source.
+3. Drive the site with your normal tools. After EVERY full page load, re-run the printed eval step (step 4).
+4. window.__ifk.dump(), then: iframer ingest --latest --typed
+   -> ./<host>-api/api.json, client.js, client.d.ts, plus the knowledge cache. The capture file is deleted.
+```
+
+- Replays run IN the page: `window.__ifk.call('GET','/path')`, or load the generated `client.js` (`iframer kit --for t3 --client ./<host>-api/client.js` prints the steps). HttpOnly cookies never leave the browser, so curl replays fail.
+- Writes need `{approved:true}`: ask the user first. Replays stop for good on 403, 429 or a captcha page. Do not retry or work around it.
+- Sites that detect tampering: `iframer kit --mode passive` (no patching; URLs and form posts only).
+- Report coverage as the kit states it. It is never complete: workers, redirect hops and cross-origin iframes are invisible.
+- `ingest` refuses (exit 2) if anything value-like slipped into the capture. Don't edit the file to force it through; tell the user what was found.
+
 ### Handle captchas
 
 Captcha handling depends on the browser mode:
@@ -171,16 +198,13 @@ Captcha handling depends on the browser mode:
 execute: steps: [{ type: "screenshot" }]  // verify captcha is gone, then continue
 ```
 
-**Docker-headful** (remote browser via noVNC):
-- Use the `solve-captcha` step — it auto-detects and solves reCAPTCHA/hCaptcha via vision AI.
+**Headless, or nobody at the screen**:
+- If you hit a captcha in headless, iframer auto-escalates to binary-headful.
+- If nobody can solve it by hand, try the `solve-captcha` step. It's best effort: it uses vision AI, needs `ANTHROPIC_API_KEY`, and fails on many challenges.
 ```
 execute: steps: [{ type: "solve-captcha" }, { type: "screenshot" }]
 ```
 
-**Headless**:
-- Captchas can't be solved in headless. If you hit one, iframer auto-escalates to binary-headful.
-- If it still fails, switch to docker-headful and use `solve-captcha`.
-
 ### Handle OTP / 2FA codes
 
 If the login step encounters a code field and no TOTP secret is stored:
@@ -201,7 +225,7 @@ When the browser crashes, freezes, or you get connection errors:
 ```
 session: { action: "restart" }
 ```
-This kills ALL running browser instances (local + Docker) and resets state. Credentials and knowledge cache are NOT affected. The next `execute` call launches a fresh browser automatically.
+This kills ALL running browser instances and resets state. Credentials and knowledge cache are NOT affected. The next `execute` call launches a fresh browser automatically.
 
 **The execute tool also auto-recovers:** if it detects a *connection-level* crash (connection closed, ECONNREFUSED/ECONNRESET/EPIPE, socket hang up), it restarts the browser server and retries once before reporting failure. Timeouts are deliberately NOT auto-retried — a slow-but-healthy pipeline that hit the client timeout must not be re-run, or non-idempotent steps (form submits, purchases) would double-execute. If auto-recovery fails, or a step timed out, call `session restart` manually and continue from where you left off (don't blindly re-run the whole pipeline).
 
@@ -232,7 +256,7 @@ knowledge: { action: "clear", domain: "example.com" }
 
 If an `execute` call takes a very long time (30s+), it's probably stuck on one of:
 
-1. **Captcha blocking progress** — the login/navigate step can't proceed because a captcha appeared. In binary-headful mode, tell the user to solve it in the visible window. In docker-headful mode, add a `solve-captcha` step.
+1. **Captcha blocking progress** — the login/navigate step can't proceed because a captcha appeared. In binary-headful mode, tell the user to solve it in the visible window. If nobody can, add a `solve-captcha` step.
 
 2. **Waiting for a page transition that never happens** — the site didn't redirect after form submission. Take a screenshot to see the current state, then decide what to do (wrong button clicked, error message on page, etc.).
 
@@ -245,7 +269,7 @@ If an `execute` call takes a very long time (30s+), it's probably stuck on one o
 
 2. If captcha visible:
    - binary-headful → ask user to solve it in the visible window
-   - docker-headful → execute: steps: [{ type: "solve-captcha" }]
+   - nobody at the screen → execute: steps: [{ type: "solve-captcha" }]
 
 3. If the page shows an error or unexpected state:
    - Take a snapshot to get element refs
@@ -256,11 +280,9 @@ If an `execute` call takes a very long time (30s+), it's probably stuck on one o
 
 **CRITICAL: Don't restart from scratch.** The browser session persists between execute calls (same daemon, same page context). If you were mid-login and hit a captcha, you don't need to navigate back to the login page — you're still there. Just solve the captcha and continue.
 
-**Timeouts:** Docker-headful is slower than local modes — Xvfb + VNC + Chrome share one container. Heavy SPAs (Slack, Figma) can take 30+ seconds to load. If an execute call times out:
+**Timeouts:** Heavy SPAs (Slack, Figma) can take 30+ seconds to load. If an execute call times out:
 1. Use `staleTimeoutMs: 60000` or higher for heavy sites
-2. Check `status` to confirm Docker is still running
-3. Take a screenshot to see where the browser is — the session is likely still alive
-4. If the container crashed, `docker compose up -d` restarts it; stored sessions/credentials survive since they're in the host's SQLite
+2. Take a screenshot to see where the browser is — the session is likely still alive
 
 ## Multi-step flows (email → code, OAuth, etc.)
 
@@ -295,7 +317,6 @@ Instead:
 **Your progress is NOT lost.** Credentials, sessions, and knowledge cache are in the SQLite database on disk — they survive MCP server restarts. You don't need to re-login or re-store anything.
 
 If the MCP disconnects repeatedly on the same operation, the site is probably too heavy for the current mode. Switch to a lighter approach:
-- If using `docker-headful` → switch to `binary-headful` (less overhead)
 - If doing a complex multi-step pipeline → break it into smaller execute calls
 - If just trying to capture APIs → you probably already have enough from previous runs. Check `knowledge get <domain>` before retrying.
 
@@ -305,7 +326,7 @@ If the MCP disconnects repeatedly on the same operation, the site is probably to
 |---------|-----------------|
 | Guessing CSS selectors like `button[data-qa='submit']` | Use `snapshot` → read refs → use `@e` refs |
 | Passing `usernameSelector`/`passwordSelector` to login step | Omit them — auto-detect handles it |
-| Re-storing credentials when login fails | Retry with stronger mode (`binary-headful` or `docker-headful`) |
+| Re-storing credentials when login fails | Retry with stronger mode (`binary-headful`) |
 | Launching browser without checking knowledge cache | Always call `knowledge get <domain>` first |
 | Using `browse` for a page that needs interaction | Use `execute` with a pipeline |
 | Running a huge pipeline without snapshots | Split into navigate+snapshot, then interact based on refs |
@@ -374,16 +395,13 @@ job to close it, not theirs.
 | Simple data extraction, no login | Omit mode (auto-select, starts headless) |
 | Site with login | Omit mode (auto-escalation if headless is blocked) |
 | Known bot-detection (Cloudflare, etc.) | `binary-headful` |
-| Heavy SPA (Slack, Figma, Linear, etc.) | `binary-headful` — Docker often stalls on heavy pages |
+| Heavy SPA (Slack, Figma, Linear, etc.) | `binary-headful` |
 | Interactive session (browsing, clicking around) | `binary-headful` — most stable for long flows |
-| Need automated captcha solving | `docker-headful` (uses vision AI to solve) |
-| Need to watch the browser remotely / headless server | `docker-headful` |
+| Nobody available to solve a captcha | Any mode, with a best-effort `solve-captcha` step (needs `ANTHROPIC_API_KEY`) |
 | Reverse-engineering after login | Same mode that login succeeded in |
 | "Use my browser" / user's own logins / their open tab | `extension` + `tabId` from the `tabs` tool |
 
-**Prefer `binary-headful` over `docker-headful` for most tasks.** Binary-headful runs Chrome directly on the user's machine — it's faster, more stable for long sessions, and the user can solve captchas manually. Docker-headful adds overhead (Xvfb, VNC, container networking) and heavy SPAs frequently stall or timeout inside the container.
-
-Use `docker-headful` only when: (a) automated captcha solving is needed, (b) the user asks for it explicitly, or (c) it's a remote/headless server with no display.
+**Prefer `binary-headful` for sites that block headless.** It runs Chrome directly on the user's machine, is stable for long sessions, and the user can solve captchas manually.
 
 ## Response handling