browserzap 0.5.0 → 0.6.0

package/bridge-server/extension-id.js

@@ -7,6 +7,11 @@
  * extension id. The private half lives outside the repository at
  * %USERPROFILE%\.browserzap-extension\key.pem and is never committed.
  *
+ * The Chrome Web Store signs its own build and does not accept a manifest
+ * `key`, so the store build may get a different id. Fill in
+ * STORE_EXTENSION_ID from the developer dashboard after the first upload; the
+ * native host then lets both builds in (docs/RELEASE.md §3b).
+ *
  * Everything that has to name the extension — the native messaging host
  * manifest's allowed_origins, `browserzap doctor`, the tests — reads the id
  * from here. `extensionIdFromKey` derives it again from the manifest key, so a
@@ -22,6 +27,12 @@ const crypto = require('crypto');
 /** chrome-extension://gienkaoaimdjmcjdejjanmbkpfakmkno/ */
 const EXTENSION_ID = 'gienkaoaimdjmcjdejjanmbkpfakmkno';
 
+/** The Chrome Web Store build's id (assigned on the first upload, 2026-10-29). */
+const STORE_EXTENSION_ID = 'bbnmhaonicbmljhbahimpgfafbjoijpe';
+
+/** Every build the native host lets in: the unpacked build first, then the store build. */
+const ALLOWED_EXTENSION_IDS = Object.freeze([EXTENSION_ID, STORE_EXTENSION_ID].filter(Boolean));
+
 /** Name Chrome uses for the native messaging host; also the registry key's leaf. */
 const HOST_NAME = 'com.browserzap.bridge';
 
@@ -29,6 +40,11 @@ function extensionOrigin(id = EXTENSION_ID) {
   return `chrome-extension://${id}/`;
 }
 
+/** allowed_origins for the native host manifest, one per allowed build. */
+function allowedOrigins(ids = ALLOWED_EXTENSION_IDS) {
+  return ids.map((id) => extensionOrigin(id));
+}
+
 /**
  * Chrome's extension id for a manifest `key` value (base64 SPKI DER).
  * Returns null when the key is missing or is not a valid public key.
@@ -51,4 +67,12 @@ function extensionIdFromKey(key) {
     .join('');
 }
 
-module.exports = { EXTENSION_ID, HOST_NAME, extensionOrigin, extensionIdFromKey };
+module.exports = {
+  EXTENSION_ID,
+  STORE_EXTENSION_ID,
+  ALLOWED_EXTENSION_IDS,
+  HOST_NAME,
+  extensionOrigin,
+  allowedOrigins,
+  extensionIdFromKey,
+};

package/bridge-server/feedback.js

@@ -0,0 +1,255 @@
+/**
+ * BrowserZap — Comment mode batches kept on this device (docs/COMMENT_MODE.md).
+ *
+ * The person's comments arrive from the side panel in one `feedback_submit`
+ * panel request and are written here for the agent's `feedback_get`:
+ *
+ *   <config dir>/feedback/<batch id>/batch.json   comments, element details, component, page
+ *   <config dir>/feedback/<batch id>/c<n>.png      the element screenshot (sensitive fields covered)
+ *   <config dir>/feedback/<batch id>/c<n>-a<k>.*   images the person attached
+ *
+ * Folders are 0700 and files 0600. Nothing is uploaded anywhere. A batch is
+ * kept BROWSERZAP_FEEDBACK_DAYS days (default 7) and at most MAX_BATCHES
+ * batches; the oldest go first. Comments never contain form values: the
+ * extension sends labels and element details only.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const { configDir } = require('./secret');
+
+const DEFAULT_KEEP_DAYS = 7;
+const MAX_BATCHES = 50;
+const MAX_COMMENTS = 30;
+const MAX_ATTACHMENTS = 3;
+const MAX_IMAGE_CHARS = 6 * 1024 * 1024;
+const ID_RE = /^fb-\d{14}-[0-9a-f]{6}$/;
+const IMAGE_TYPES = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/gif': 'gif' };
+const BASE64_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+
+class FeedbackError extends Error {
+  constructor(message) {
+    super(message);
+    this.code = 'INVALID_ARGUMENT';
+  }
+}
+
+const feedbackDir = () => path.join(configDir(), 'feedback');
+
+function keepDays() {
+  const raw = process.env.BROWSERZAP_FEEDBACK_DAYS;
+  if (raw === undefined || raw === '') return DEFAULT_KEEP_DAYS;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 && n <= 365 ? n : DEFAULT_KEEP_DAYS;
+}
+
+const str = (v, max) => (typeof v === 'string' ? v.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, '').slice(0, max) : null);
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? Math.round(v) : null);
+
+function rectOf(r) {
+  if (!r || typeof r !== 'object') return null;
+  return { x: num(r.x), y: num(r.y), width: num(r.width), height: num(r.height) };
+}
+
+/** Plain JSON of bounded size: target objects are small; anything deeper or larger is dropped. */
+function smallJson(value, maxChars = 2000) {
+  try {
+    const text = JSON.stringify(value);
+    return text && text.length <= maxChars ? JSON.parse(text) : null;
+  } catch {
+    return null;
+  }
+}
+
+function elementOf(info) {
+  const i = info && typeof info === 'object' ? info : {};
+  return {
+    role: str(i.role, 60),
+    name: str(i.name, 300),
+    target: smallJson(i.target),
+    targetUnique: i.targetUnique === true,
+    tag: str(i.tag, 40),
+    id: str(i.id, 200),
+    testId: str(i.testId, 200),
+    classes: Array.isArray(i.classes) ? i.classes.map((c) => str(c, 100)).filter(Boolean).slice(0, 6) : [],
+    domPath: str(i.domPath, 600),
+    text: str(i.text, 200),
+    sensitive: i.sensitive === true ? true : undefined,
+    rect: rectOf(i.rect),
+  };
+}
+
+function componentOf(c) {
+  if (!c || typeof c !== 'object') return null;
+  const source = c.source && typeof c.source === 'object' && typeof c.source.file === 'string'
+    ? { file: str(c.source.file, 400), line: num(c.source.line), column: num(c.source.column) }
+    : null;
+  return {
+    framework: str(c.framework, 20),
+    component: str(c.component, 100),
+    chain: Array.isArray(c.chain) ? c.chain.map((n) => str(n, 100)).filter(Boolean).slice(0, 5) : [],
+    source,
+  };
+}
+
+function pageOf(p) {
+  const page = p && typeof p === 'object' ? p : {};
+  const url = str(page.url, 2000);
+  if (!url || !/^https?:\/\//i.test(url)) throw new FeedbackError('Every comment needs the http(s) page it was made on.');
+  return {
+    url,
+    title: str(page.title, 200),
+    viewport: page.viewport && typeof page.viewport === 'object' ? { width: num(page.viewport.width), height: num(page.viewport.height) } : null,
+  };
+}
+
+function imageData(data, what) {
+  if (typeof data !== 'string' || !data) return null;
+  if (data.length > MAX_IMAGE_CHARS) throw new FeedbackError(`${what} is too large.`);
+  if (!BASE64_RE.test(data)) throw new FeedbackError(`${what} is not a valid image.`);
+  return Buffer.from(data, 'base64');
+}
+
+function newId(now = new Date()) {
+  const p = (n, w = 2) => String(n).padStart(w, '0');
+  const stamp = `${now.getFullYear()}${p(now.getMonth() + 1)}${p(now.getDate())}${p(now.getHours())}${p(now.getMinutes())}${p(now.getSeconds())}`;
+  return `fb-${stamp}-${crypto.randomBytes(3).toString('hex')}`;
+}
+
+function writePrivate(file, content) {
+  fs.writeFileSync(file, content, { mode: 0o600 });
+}
+
+/** Check and store one batch. Returns { id, dir, count }. Throws FeedbackError on bad input. */
+function saveBatch(batch, { now = new Date() } = {}) {
+  const comments = batch && Array.isArray(batch.comments) ? batch.comments : null;
+  if (!comments || comments.length === 0) throw new FeedbackError('The batch has no comments.');
+  if (comments.length > MAX_COMMENTS) throw new FeedbackError(`A batch holds at most ${MAX_COMMENTS} comments.`);
+
+  const id = newId(now);
+  const dir = path.join(feedbackDir(), id);
+  const files = [];
+  const stored = comments.map((c, index) => {
+    if (!c || typeof c !== 'object') throw new FeedbackError(`Comment ${index + 1} is not an object.`);
+    const text = str(c.text, 2000)?.trim();
+    if (!text) throw new FeedbackError(`Comment ${index + 1} has no text.`);
+    const n = Number.isInteger(c.n) && c.n > 0 && c.n < 1000 ? c.n : index + 1;
+    const shot = imageData(c.screenshot, `The screenshot of comment ${n}`);
+    const attachments = Array.isArray(c.attachments) ? c.attachments.slice(0, MAX_ATTACHMENTS) : [];
+    const entry = {
+      n,
+      text,
+      page: pageOf(c.page),
+      element: elementOf(c.info),
+      component: componentOf(c.component),
+      screenshot: null,
+      attachments: [],
+      createdAt: num(c.createdAt),
+    };
+    if (shot) {
+      entry.screenshot = `c${n}.png`;
+      files.push([entry.screenshot, shot]);
+    }
+    attachments.forEach((a, k) => {
+      const ext = a && IMAGE_TYPES[a.mimeType];
+      const data = ext ? imageData(a.data, `Image ${k + 1} of comment ${n}`) : null;
+      if (!data) return;
+      const name = `c${n}-a${k + 1}.${ext}`;
+      entry.attachments.push(name);
+      files.push([name, data]);
+    });
+    return entry;
+  });
+
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  for (const [name, data] of files) writePrivate(path.join(dir, name), data);
+  const record = { id, createdAt: now.toISOString(), delivered: false, deliveredAt: null, comments: stored };
+  writePrivate(path.join(dir, 'batch.json'), JSON.stringify(record, null, 2));
+  prune({ now: now.getTime() });
+  return { id, dir, count: stored.length };
+}
+
+function readBatch(id) {
+  if (!ID_RE.test(id)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(path.join(feedbackDir(), id, 'batch.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function batchIds() {
+  try {
+    return fs.readdirSync(feedbackDir()).filter((d) => ID_RE.test(d)).sort();
+  } catch {
+    return [];
+  }
+}
+
+/** Newest first: { id, createdAt, count, pages, delivered }. */
+function list({ includeDelivered = false } = {}) {
+  return batchIds().reverse()
+    .map((id) => readBatch(id))
+    .filter((b) => b && (includeDelivered || !b.delivered))
+    .map((b) => ({
+      id: b.id,
+      createdAt: b.createdAt,
+      count: b.comments.length,
+      pages: [...new Set(b.comments.map((c) => c.page.url))].slice(0, 5),
+      delivered: b.delivered,
+    }));
+}
+
+/** One batch with absolute file paths, or the newest one not yet delivered. */
+function get(id) {
+  const chosen = id ?? list()[0]?.id;
+  const batch = chosen ? readBatch(chosen) : null;
+  if (!batch) return null;
+  const dir = path.join(feedbackDir(), batch.id);
+  return {
+    ...batch,
+    dir,
+    comments: batch.comments.map((c) => ({
+      ...c,
+      screenshot: c.screenshot ? path.join(dir, c.screenshot) : null,
+      attachments: c.attachments.map((a) => path.join(dir, a)),
+    })),
+  };
+}
+
+function markDelivered(id, { now = new Date() } = {}) {
+  const batch = readBatch(id);
+  if (!batch || batch.delivered) return false;
+  batch.delivered = true;
+  batch.deliveredAt = now.toISOString();
+  writePrivate(path.join(feedbackDir(), id, 'batch.json'), JSON.stringify(batch, null, 2));
+  return true;
+}
+
+function pendingCount() {
+  return list().length;
+}
+
+/** Delete batches older than the retention, and the oldest beyond MAX_BATCHES. Never throws. */
+function prune({ now = Date.now(), days = keepDays() } = {}) {
+  const cutoff = now - days * 86_400_000;
+  const ids = batchIds();
+  let removed = 0;
+  ids.forEach((id, index) => {
+    const batch = readBatch(id);
+    const created = batch ? Date.parse(batch.createdAt) : 0;
+    if (created < cutoff || index < ids.length - MAX_BATCHES) {
+      try {
+        fs.rmSync(path.join(feedbackDir(), id), { recursive: true, force: true });
+        removed++;
+      } catch { /* in use: next time */ }
+    }
+  });
+  return removed;
+}
+
+module.exports = { saveBatch, list, get, markDelivered, pendingCount, prune, feedbackDir, FeedbackError, MAX_COMMENTS };

package/bridge-server/index.js

@@ -265,7 +265,16 @@ function uninstallExtension(purge, { register = true } = {}) {
  */
 const command = args[0] && !args[0].startsWith('-') ? args[0] : null;
 
-const SUBCOMMANDS = new Set(['setup', 'doctor', 'uninstall', 'run']);
+// Inside WSL there is no Chrome to pair with and no Windows registry: BrowserZap
+// runs on the Windows side and the agent in WSL starts it through interop.
+if (require('./setup').insideWsl() && !process.env.BROWSERZAP_ALLOW_LINUX) {
+  process.stderr.write('BrowserZap runs on Windows, next to Chrome. From WSL, start it through Windows:\n' +
+    '  claude mcp add browserzap -- cmd.exe /c browserzap\n' +
+    '(install it on Windows first: npm install -g browserzap, then browserzap setup). See docs/WSL.md.\n');
+  process.exit(2);
+}
+
+const SUBCOMMANDS = new Set(['setup', 'doctor', 'uninstall', 'run', 'restart-bridge']);
 
 if (command === 'setup') {
   // From an installed package, copy the extension to a folder that outlives an
@@ -298,12 +307,29 @@ if (command === 'setup') {
 `);
       process.exit(1);
     });
+} else if (command === 'restart-bridge') {
+  // A bridge that will not pair (another secret, an old version) holds the
+  // port. Stop the node process holding it (never anything that is not node);
+  // the extension's native host starts the current one with this install's secret.
+  const { stopBridgeOnPort, isListening } = require('./probe');
+  const portIdx = args.indexOf('--port');
+  const port = portIdx !== -1 && args[portIdx + 1] ? parseInt(args[portIdx + 1], 10) : DEFAULT_PORT;
+  stopBridgeOnPort(port).then(async (pids) => {
+    const still = await isListening(port);
+    process.stdout.write(pids.length
+      ? `Stopped the bridge on 127.0.0.1:${port} (pid ${pids.join(', ')}). Open the BrowserZap side panel (or press Reconnect) to start the current one.\n`
+      : `No BrowserZap bridge was holding 127.0.0.1:${port}.${still ? ' Something else listens there; it was left alone.' : ''}\n`);
+    process.exit(still ? 1 : 0);
+  }).catch((err) => {
+    process.stderr.write(`[browserzap] restart-bridge failed: ${err.message}\n`);
+    process.exit(1);
+  });
 } else if (command === 'uninstall') {
   uninstallExtension(args.includes('--purge'), { register: !args.includes('--no-registry') });
 } else if (command === 'help') {
   args.push('--help');
 } else if (command) {
-  process.stderr.write(`Unknown command "${command}". Use: setup, doctor, run, uninstall, or --help.\n`);
+  process.stderr.write(`Unknown command "${command}". Use: setup, doctor, restart-bridge, run, uninstall, or --help.\n`);
   process.exit(2);
 }
 
@@ -468,6 +494,7 @@ Usage:
   browserzap setup                      One-time setup: register the native messaging host and
                                         optionally add the MCP server to detected clients
   browserzap doctor                     Check the host manifest, registry, extension id and bridge
+  browserzap restart-bridge             Replace a bridge that will not pair (another secret or version)
   browserzap uninstall [--purge]        Remove the host registration and installed extension copy
   browserzap run <workflow> [--params <file.csv|file.json>] [--stop-on-error]
                                         Run a saved workflow with no agent; one run per row (Pro for

package/bridge-server/limits.js

@@ -26,6 +26,13 @@ const LIMITS = Object.freeze({
   SETTLE_QUIET_MS: 500,
   /** How long that settle waits for a busy page (it costs nothing on a quiet one). */
   SETTLE_MAX_MS: 5000,
+  /** A wait whose condition makes no progress for this long ends early: a page that is stuck does not get better. */
+  STALL_MS: 3000,
+  /**
+   * Before "Re-run failed" resumes at the step that failed, that step's target
+   * must be actionable within this. A bounded probe, not a pause (A6-09).
+   */
+  RESUME_PROBE_MS: 3000,
   /** Longest per-step pacing a person may set on a saved workflow step. */
   MAX_STEP_PACING_MS: 30000,
   /** A tab with no agent action for this long is detached, so Chrome's "debugging" bar goes away (D-35). */
@@ -60,6 +67,16 @@ const STATUS_DEADLINE_MS = 4_000;
  */
 const RUN_DEADLINE_MS = 600_000;
 
+/**
+ * Resolver engine bounds (`bridge-server/resolvers.js`, 0.6.0, D-37).
+ * A step may spend at most MAX_STEP_RESOLVE_MS resolving blockers in place,
+ * across at most MAX_RESOLVER_ATTEMPTS attempts, and a reversible click with
+ * no effect at all is repeated at most MAX_INPLACE_CLICK_RETRIES times (AU-08).
+ */
+const MAX_STEP_RESOLVE_MS = 45_000;
+const MAX_RESOLVER_ATTEMPTS = 2;
+const MAX_INPLACE_CLICK_RETRIES = 2;
+
 /**
  * How long the caller waits for the extension to answer one call: the sum of
  * every wait the call can do, plus a margin, and never less than
@@ -97,4 +114,13 @@ function callDeadlineMs(tool, args = {}) {
   return Math.max(CALL_DEADLINE_MS, waits + DEADLINE_MARGIN_MS);
 }
 
-module.exports = { LIMITS, CALL_DEADLINE_MS, STATUS_DEADLINE_MS, RUN_DEADLINE_MS, callDeadlineMs };
+module.exports = {
+  LIMITS,
+  CALL_DEADLINE_MS,
+  STATUS_DEADLINE_MS,
+  RUN_DEADLINE_MS,
+  MAX_STEP_RESOLVE_MS,
+  MAX_RESOLVER_ATTEMPTS,
+  MAX_INPLACE_CLICK_RETRIES,
+  callDeadlineMs,
+};