browserzap 0.4.0 → 0.5.5

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.5.5 (2026-10-30)
+
+Comment mode, debugging tools, files, Edge and WSL, a much better doctor, and the Chrome Web Store build. Known items to review are listed in docs/REVIEW_LATER.md (upload approval visibility, a file the person picks themselves, a download re-test, wider Comment screenshots, a calmer side panel).
+
+- No more stuck file dialogs: when the agent clicks a page's "Choose file" control, no Windows file picker opens; the result says the page asked for a file and to use `file_upload`. Your own clicks open the picker as usual. If Chrome is set to ask where to save each download, `browserzap doctor` and `browser_downloads` say so and how to turn it off (an extension cannot skip that dialog).
+- Messages for people who installed from npm: the side panel, the extension and the agent no longer point to source-only commands (`npm run health`, `npm run bridge:restart`, …) but to `browserzap doctor`, `browserzap restart-bridge`, `browserzap --print-token`. When a bridge from another install holds the port, the side panel now says so and shows the fix instead of staying grey.
+- Agents are told about Comment mode, console/network, downloads and uploads when they connect.
+- The helper accepts the Chrome Web Store build of the extension (id bbnmhaonicbmljhbahimpgfafbjoijpe) as well as the unpacked one; setup and the README point to the store listing first (in review).
+- Fixed: with `BROWSERZAP_PROFILE` set to a profile name such as "Work", auto-launch asked Chrome for a profile folder of that name, which made Chrome create a new, empty profile. It now opens the matching profile (looked up in Chrome's profile list), or Chrome's last profile when there is no match.
+- **Downloads**: a click that starts a download now says so ("It started a download: invoice.pdf"), and the new `browser_downloads` tool lists what was downloaded during the session — name, size, full path, still downloading or complete — and can wait for a download to finish. No new extension permission; set `BROWSERZAP_DOWNLOAD_DIR` if Chrome saves somewhere other than your Downloads folder.
+- **`file_upload`**: your agent can attach a file from your computer to a site's "Choose file" input, including the common kind hidden behind a styled button. You approve that exact file (name and size) in the side panel every time; `BROWSERZAP_UPLOAD_DIR` can limit uploads to one folder.
+- A screenshot of an element with no visible box now says so instead of failing with an internal error.
+- **WSL**: use BrowserZap from Claude Code running inside WSL. The agent starts the Windows helper through interop (claude mcp add browserzap -- cmd.exe /c browserzap); setup prints the line when the machine has WSL, and starting BrowserZap inside WSL explains what to do instead (docs/WSL.md).
+- **Microsoft Edge**: `browserzap setup` registers the helper for Edge as well as Chrome (Windows registry; the Edge folders on macOS and Linux), and `browserzap doctor` checks it. Edge installs Chrome Web Store extensions and loads the same unpacked folder with the same id. Not yet tested in a real Edge; auto-launch still opens Chrome.
+- **Comment mode** (free): in the side panel press **Comment on this page**, click elements, write what should change, add images, and send every note to your agent at once. The agent reads them with the new `feedback_get` tool: the element, its component and source file on development builds (React, Vue, Svelte, Angular) and a screenshot with password and card fields covered. Saved only on your computer (docs/COMMENT_MODE.md).
+- `browserzap doctor` now explains three silent ways the side panel stays grey: the helper launcher points at a Node that is gone (after switching Node with fnm, Volta or nvm), a Chrome enterprise policy blocks the helper or the extension, or a bridge with a different pairing secret holds the port. New `browserzap restart-bridge` replaces that bridge.
+- **`page_console` and `page_network`** (free): your agent can read the page's console messages (logs, warnings, errors, uncaught exceptions, failed loads) and its requests (status, timing, size, failures) while it debugs your app. Headers, cookies and bodies are never read; other sites' URLs lose their query string.
+- The extension zip on each GitHub release is ready for the Chrome Web Store: it leaves out the manifest `key`, which the store refuses (`npm run package:store` builds it locally).
+- The helper can let in a second extension id, for the Chrome Web Store build, next to the Load-unpacked one; `browserzap doctor` checks both once it is set.
+
+## 0.5.0 (2026-10-29)
+
+- Chrome's "BrowserZap started debugging this browser" bar now goes away: when the agent ends, when you take the tab (Stop or a hand-off), and after the agent has not used the tab for a minute. It comes back only while the agent works (D-35).
+- No more piles of tabs. An agent works in one main tab and closes the helper tabs it opens for side trips (new tool `browser_close_tab`); tabs a site opens from the agent's tab count as helpers. At most 5 tabs while it works, 3 once it is idle, and **none** after the agent ends or its connection is lost for 30 s. A tab you are looking at, or drag out of the BrowserZap group, is never closed (D-36, D-38).
+
 ## 0.4.0 — first public release (2026-10-28)
 
 The first version published on npm (`npm install -g browserzap`, then `browserzap setup`).

package/README.md

@@ -2,23 +2,27 @@
 
 **Let the AI agent on your computer use your own Chrome — your tab, your logins — while you watch and stay in control.**
 
-Website: <https://browserzap.com> · Contact: <hello@browserzap.com> · Security: <security@browserzap.com>
+Website and docs: <https://browserzap.com/docs> · Contact: <hello@browserzap.com> · Security: <security@browserzap.com>
 
 BrowserZap connects an MCP agent (Claude Code, Codex CLI, Cursor, …) to the Chrome you already use. There is no cloud
 browser, no copied cookies and no new login: the agent works in your real tab, and you can see every step.
 
 - **Exact, not approximate.** Every click and fill is resolved to exactly one element by its role and name. If two
   elements match, nothing happens and the agent is told which ones.
-- **You approve what matters.** Submits, payments, deletions and posts wait for **Approve once** in the side panel.
+- **You approve what matters.** Submits, payments, deletions, posts and file uploads wait for **Approve once** in the
+  side panel.
 - **Your passwords stay yours.** The agent never types a password, one-time code or card number. The page asks you
   to (**Your turn** → **Done**), and what you type is never logged.
 - **Stop at any time.** A pill on the page and a switch in the side panel take the tab back at once.
+- **Comment mode.** Click what is wrong on any page, write a note, and send every note to your coding agent at once —
+  with the component, source file and a screenshot of each element.
+- **Debug with your agent.** It reads the page's console errors and failed network requests itself.
 - **Record once, replay many.** Save a task as a workflow and run it again with new values, step by step and checked.
 
 ## Requirements
 
 - Windows 10 or 11 (macOS and Linux are not supported yet)
-- Google Chrome
+- Google Chrome (Microsoft Edge works too)
 - Node.js 22 or newer; 24 recommended (<https://nodejs.org>)
 - An MCP client: Claude Code, Codex CLI, Cursor or another
 
@@ -29,64 +33,82 @@ npm install -g browserzap
 browserzap setup
 ```
 
-`browserzap setup` does three things:
+`browserzap setup` does three things, and is safe to run again:
 
-1. Registers a small helper with Chrome for your Windows user only (no administrator rights), so the extension
-   connects by itself. There is no token to copy.
+1. Registers a small helper with Chrome and Edge for your Windows user only (no administrator rights), so the
+   extension connects by itself. There is no token to copy.
 2. Copies the BrowserZap extension to `%USERPROFILE%\BrowserZap\extension` and prints that path.
 3. Finds Claude Code, Codex CLI and Cursor, shows the exact entry it would add for BrowserZap, and adds it only after
    you answer `y`.
 
-Then load the extension (Chrome does not allow this step to be automated):
+Then add the extension to Chrome:
 
-1. Open `chrome://extensions` and turn on **Developer mode**.
-2. Click **Load unpacked** and choose the folder `setup` printed.
-3. Click the BrowserZap icon to open the side panel. It turns green when it is connected.
+- **From the Chrome Web Store** (in review; this link works once it is published):
+  <https://chromewebstore.google.com/detail/bbnmhaonicbmljhbahimpgfafbjoijpe>. Chrome keeps it updated.
+- **Until then, load it unpacked** (Chrome does not allow this step to be automated):
+  1. Open `chrome://extensions` and turn on **Developer mode**.
+  2. Click **Load unpacked** and choose the folder `setup` printed.
 
-A Chrome Web Store listing is on its way; until then the extension is loaded from the package as above.
-
-Check everything with:
+Click the BrowserZap icon to open the side panel. It turns green when it is connected. Check everything with:
 
 ```cmd
 browserzap doctor
 ```
 
+Using Claude Code inside WSL? BrowserZap stays on Windows; in WSL run
+`claude mcp add browserzap -- cmd.exe /c browserzap` (details: <https://browserzap.com/docs/platforms>).
+
 ## Use it
 
 Restart your MCP client and ask for something in the browser, for example: *"Open example.com and tell me what the
 main heading says."* If Chrome is closed, the first browser request opens it.
 
-While the agent works, a small cursor shows where it is acting, and a pill at the top of the page says the agent is
-working. Press **Stop** on the pill, or switch control in the side panel, to take over.
+While the agent works, a small cursor shows where it is acting, a pill at the top of the page says the agent is
+working, and its tabs sit in a labelled **BrowserZap** tab group that it cleans up when it is done. Press **Stop** on
+the pill, or switch control in the side panel, to take over.
 
 Things to try:
 
 - *"Search Wikipedia for 'Model Context Protocol' and summarise the first paragraph."*
 - *"In my GitHub notifications, list the unread ones from this week."* (uses your existing login)
 - *"Fill in the contact form on this page with my details, but let me approve before sending."*
-- *"Record a workflow called `export-report` while I show you how to download last month's report."*
+- *"Open my app on localhost:3000, click Save, and tell me why it fails — check the console and the network."*
+- In the side panel: **Comments → Comment on this page**, click a few elements, write notes, **Send**, then tell your
+  agent *"Apply my BrowserZap feedback"*.
+
+Every tool and option: <https://browserzap.com/docs/tools>.
 
 ## Troubleshooting
 
+Start with `browserzap doctor`: every failed line says what to do.
+
 | You see | Do this |
 |---|---|
-| The side panel stays grey or says *Not paired yet* | Run `browserzap setup`, then press the reload icon on the BrowserZap card in `chrome://extensions`. `browserzap doctor` says which part is missing |
-| Chrome says *Disable developer mode extensions* on start-up | Expected while the extension is loaded unpacked. Choose **Keep**; the Chrome Web Store version will not show it |
-| A bar says *"BrowserZap" started debugging this browser* | Expected: Chrome shows it whenever an agent can act. Press **Stop** in the page to end control |
+| The side panel stays grey or says *Not paired yet* | Run `browserzap setup`, then reload the extension in `chrome://extensions` |
+| Doctor: *a bridge with a different pairing secret holds 127.0.0.1:9334* | `browserzap restart-bridge`, then **Reconnect** in the side panel |
+| Doctor: *Launcher finds Node and the helper* fails | Node moved (a version switch with fnm, Volta or nvm): run `browserzap setup` again |
+| Doctor: *Not blocked by Chrome policy* fails | Your computer is managed; ask IT to allow the helper `com.browserzap.bridge` and the extension |
+| Chrome says *Disable developer mode extensions* on start-up | Expected while the extension is loaded unpacked. Choose **Keep**; the Chrome Web Store version does not show it |
+| A bar says *"BrowserZap" started debugging this browser* | Expected while an agent can act; it goes away when the agent ends or after a minute idle |
 | Your agent does not list BrowserZap's tools | Restart the agent app after `browserzap setup`. To add it by hand, `browserzap --help` prints the exact MCP configuration |
-| A step stops with *"needs you"* | The page asked for a password, a code or an approval. Do it in the page, press **Done**, and the agent continues |
-| Anything else | Run `browserzap doctor` and email <hello@browserzap.com> with its output (it contains no passwords or page content) |
+| A step stops with *"needs you"* | The page asked for a password, a code or an approval. Do it, press **Done**, and the agent continues |
+| Anything else | Email <hello@browserzap.com> with the output of `browserzap doctor` (it contains no passwords or page content) |
+
+More: <https://browserzap.com/docs/troubleshooting>.
 
 ## Commands
 
 | Command | What it does |
 |---|---|
 | `browserzap setup` | One-time setup (above). Safe to run again |
-| `browserzap doctor` | Checks the helper registration, the extension id and the connection |
+| `browserzap doctor` | Checks the helper registration, the launcher, Chrome policy, the extension id and the connection |
+| `browserzap restart-bridge` | Replaces a bridge that will not pair (another install's secret or an old version) |
 | `browserzap run <workflow> --params rows.csv` | Runs a saved workflow without an agent (one row on the free plan) |
 | `browserzap uninstall` | Removes the helper registration and the extension copy; keeps your data |
 | `browserzap uninstall --purge` | Also removes your BrowserZap data folder (cannot be undone) |
 
+Environment variables (allowed sites, profile, upload folder, retention, …): <https://browserzap.com/docs/configuration>.
+
 ## Update
 
 ```cmd
@@ -94,25 +116,26 @@ npm install -g browserzap@latest
 browserzap setup
 ```
 
-Then press the reload icon on the BrowserZap card in `chrome://extensions`. Your workflows, run reports and settings
-are kept.
+A Web Store install updates itself; an unpacked one needs the reload icon on its card in `chrome://extensions`. Your
+workflows, run reports and settings are kept.
 
 ## Free and Pro
 
-The free plan includes every browser tool and every safety control, plus up to 10 saved workflows. BrowserZap Pro
-(running a workflow over many rows, workflow history, run reports) is coming soon. Safety controls are never paid
-features.
+Every live browser tool, Comment mode, console and network reading, and every safety control are free; today up to
+10 saved workflows are free too. BrowserZap Pro — automation at scale: workflows over many rows, background runs,
+history and run reports — is coming, as a monthly, yearly or lifetime licence. Any change to plans is announced on
+<https://browserzap.com> first. Safety controls are never paid features.
 
 ## Privacy
 
 BrowserZap runs on your machine. It has no cloud service, no account, no telemetry and no analytics. The bridge
 listens only on `127.0.0.1` and accepts only authenticated connections. Form values, passwords and cookies are never
-logged. What the agent reads on a page goes to the AI client you connected, under that client's terms. Full policy:
-<https://browserzap.com/privacy>.
+logged; Comment mode screenshots cover password and card fields and stay on your computer. What the agent reads on a
+page goes to the AI client you connected, under that client's terms. Full policy: <https://browserzap.com/privacy>.
 
 ## Known limitations
 
-- Windows only so far; Chrome only.
+- Windows only so far (Chrome or Edge). macOS and Linux are planned.
 - `chrome://` pages and the Chrome Web Store cannot be automated.
 - Canvas apps, some custom widgets and cross-origin frames may need you to do the step.
 - In a background tab, clicks are made inside the page; a site that requires a real user click needs the tab in front.

package/bridge-server/chrome-launcher.js

@@ -20,6 +20,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 const { execFileSync, spawn } = require('child_process');
 
 /** Set to 0 (or false/off/no) to stop BrowserZap opening Chrome itself. */
@@ -131,6 +132,41 @@ function cleanProfileDirectory(value) {
   return cleaned || null;
 }
 
+/** Chrome's User Data folder, where `Local State` lists the profiles. */
+function userDataDir({ platform = process.platform, env = process.env, home = os.homedir() } = {}) {
+  if (platform === 'win32') return path.win32.join(env.LOCALAPPDATA || path.win32.join(home, 'AppData', 'Local'), 'Google', 'Chrome', 'User Data');
+  if (platform === 'darwin') return path.posix.join(home, 'Library', 'Application Support', 'Google', 'Chrome');
+  return path.posix.join(home, '.config', 'google-chrome');
+}
+
+/** Directory names Chrome itself uses, safe to pass when Local State cannot be read. */
+const PROFILE_DIR_RE = /^(Default|Profile \d+)$/;
+
+/**
+ * Turn BROWSERZAP_PROFILE into a profile directory Chrome can open, or null.
+ *
+ * The variable holds the name a person gave the profile ("Work": the same name
+ * the MCP server selects by), while Chrome's --profile-directory wants the folder
+ * ("Profile 1"). Passing "Work" made Chrome create a new, empty profile. So:
+ * a folder listed in Local State is used as is; otherwise a profile whose Chrome
+ * name matches (any case) gives its folder; otherwise null, and Chrome opens the
+ * last profile used — the session then picks its profile by name once connected.
+ */
+function resolveProfileDirectory(value, { readFile = (f) => fs.readFileSync(f, 'utf8'), dataDir = userDataDir() } = {}) {
+  const wanted = cleanProfileDirectory(value);
+  if (!wanted) return null;
+  let cache = null;
+  try {
+    cache = JSON.parse(readFile(path.join(dataDir, 'Local State')))?.profile?.info_cache ?? null;
+  } catch {
+    cache = null;
+  }
+  if (!cache || typeof cache !== 'object') return PROFILE_DIR_RE.test(wanted) ? wanted : null;
+  if (Object.hasOwn(cache, wanted)) return wanted;
+  const byName = Object.entries(cache).find(([, info]) => typeof info?.name === 'string' && info.name.trim().toLowerCase() === wanted.toLowerCase());
+  return byName ? byName[0] : null;
+}
+
 /**
  * The arguments Chrome is started with. One optional flag and nothing else:
  * a profile directory tells Chrome which of the user's own profiles to open.
@@ -177,7 +213,10 @@ function ensureChromeRunning(options = {}) {
   if (isChromeRunning(options)) return { status: 'already_running', launched: false, path: null };
   const found = findChrome(options);
   if (!found) return { status: 'not_found', launched: false, path: null };
-  const profileDirectory = options.profileDirectory ?? env[PROFILE_ENV] ?? null;
+  const requested = options.profileDirectory ?? env[PROFILE_ENV] ?? null;
+  const profileDirectory = requested
+    ? resolveProfileDirectory(requested, { readFile: options.readFile, dataDir: options.userDataDir ?? userDataDir({ platform: options.platform, env }) })
+    : null;
   const result = launchChrome({ chromePath: found.path, profileDirectory, spawnChild: options.spawnChild });
   if (!result.launched) {
     return { status: 'launch_failed', launched: false, path: found.path, error: result.error ?? 'Chrome did not start.' };
@@ -198,4 +237,6 @@ module.exports = {
   isChromeRunning,
   launchChrome,
   readRegistryDefault,
+  resolveProfileDirectory,
+  userDataDir,
 };

package/bridge-server/downloads.js

@@ -0,0 +1,173 @@
+/**
+ * BrowserZap — what the browser downloaded during a session (ROADMAP 0.5.4).
+ *
+ * Chrome writes downloads to the user's Downloads folder, first as
+ * `<name>.crdownload` (or `Unconfirmed <n>.crdownload`), then renamed to the
+ * final name. The MCP server watches that folder, so a click that starts a
+ * download can say so and `browser_downloads` can list and wait for files —
+ * with no new extension permission (a `downloads` permission would mean a new
+ * Chrome Web Store review).
+ *
+ *   - Folder: BROWSERZAP_DOWNLOAD_DIR, else the Windows "Downloads" known
+ *     folder (User Shell Folders), else ~/Downloads.
+ *   - Only files that arrived after a given time are reported: names, sizes,
+ *     paths and state. File contents are never read.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const DOWNLOADS_GUID = '{374DE290-123F-4565-9164-39C4925E467B}';
+const SHELL_FOLDERS = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\User Shell Folders';
+const PARTIAL_RE = /\.(crdownload|part|download|tmp)$/i;
+const POLL_MS = 250;
+const MAX_WAIT_MS = 120_000;
+const MAX_LISTED = 50;
+
+function defaultRun(argv) {
+  const result = spawnSync(process.env.BROWSERZAP_REG_BIN || 'reg', argv, { encoding: 'utf8', windowsHide: true });
+  return { status: result.status ?? 1, stdout: result.stdout ?? '' };
+}
+
+/** Expand %VAR% the way Windows does for REG_EXPAND_SZ values. */
+function expandWindowsVars(value, env) {
+  return value.replace(/%([^%]+)%/g, (whole, name) => {
+    const key = Object.keys(env).find((k) => k.toLowerCase() === name.toLowerCase());
+    return key ? env[key] : whole;
+  });
+}
+
+/** Where the browser saves downloads. */
+function downloadDir({ env = process.env, platform = process.platform, home = os.homedir(), run = defaultRun } = {}) {
+  if (env.BROWSERZAP_DOWNLOAD_DIR) return path.resolve(env.BROWSERZAP_DOWNLOAD_DIR);
+  if (platform === 'win32') {
+    const result = run(['query', SHELL_FOLDERS, '/v', DOWNLOADS_GUID]);
+    const match = result.status === 0 && /REG_(?:EXPAND_)?SZ\s+(.+?)\s*$/m.exec(result.stdout ?? '');
+    if (match) {
+      const dir = expandWindowsVars(match[1], env);
+      if (!/%/.test(dir)) return dir;
+    }
+  }
+  return path.join(home, 'Downloads');
+}
+
+/** name → { size, mtimeMs } for the folder's files (top level only). Never throws. */
+function snapshot(dir) {
+  const out = new Map();
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch { return out; }
+  for (const name of names) {
+    try {
+      const st = fs.statSync(path.join(dir, name));
+      if (st.isFile()) out.set(name, { size: st.size, mtimeMs: st.mtimeMs, birthtimeMs: st.birthtimeMs || st.mtimeMs });
+    } catch { /* gone meanwhile */ }
+  }
+  return out;
+}
+
+function finalName(name) {
+  return name.replace(PARTIAL_RE, '');
+}
+
+/** The folder's file names: one directory read, cheap enough to take before every click. Never throws. */
+function names(dir) {
+  try {
+    return new Set(fs.readdirSync(dir));
+  } catch {
+    return new Set();
+  }
+}
+
+/** Downloads that appeared since `before` (a Set from names()): only the new names are looked at. */
+function arrived(before, dir) {
+  const entries = [];
+  for (const name of names(dir)) {
+    if (before.has(name)) continue;
+    try {
+      const st = fs.statSync(path.join(dir, name));
+      if (st.isFile()) entries.push(entry(dir, name, { size: st.size, mtimeMs: st.mtimeMs, birthtimeMs: st.birthtimeMs || st.mtimeMs }));
+    } catch { /* gone meanwhile (a .crdownload renamed) */ }
+  }
+  return collapse(entries);
+}
+
+function entry(dir, name, info) {
+  const partial = PARTIAL_RE.test(name);
+  return {
+    fileName: partial ? (/^Unconfirmed \d+\./i.test(name) ? null : finalName(name)) : name,
+    path: path.join(dir, name),
+    sizeBytes: info.size,
+    state: partial ? 'in_progress' : 'complete',
+    at: new Date(info.birthtimeMs || info.mtimeMs).toISOString(),
+  };
+}
+
+/** A finished file replaces its own partial entry. */
+function collapse(entries) {
+  const done = new Set(entries.filter((e) => e.state === 'complete').map((e) => e.fileName));
+  return entries
+    .filter((e) => e.state === 'complete' || !e.fileName || !done.has(e.fileName))
+    .sort((a, b) => a.at.localeCompare(b.at));
+}
+
+/** Downloads that arrived at or after `sinceMs` (new files only; touched old files are not downloads). */
+function since(dir, sinceMs) {
+  const entries = [];
+  for (const [name, info] of snapshot(dir)) {
+    const born = Math.max(info.birthtimeMs || 0, 0);
+    // A rename keeps the birth time of the .crdownload, which is after sinceMs.
+    if ((born || info.mtimeMs) + 1000 < sinceMs) continue;
+    entries.push(entry(dir, name, info));
+  }
+  return collapse(entries).slice(-MAX_LISTED);
+}
+
+/**
+ * Wait (bounded poll) until no download that arrived since `sinceMs` is still
+ * in progress and at least one exists, or `waitMs` passes. Returns the entries
+ * and whether it timed out.
+ */
+async function waitFor(dir, sinceMs, waitMs, { sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now } = {}) {
+  const deadline = now() + Math.min(Math.max(waitMs, 0), MAX_WAIT_MS);
+  let entries = since(dir, sinceMs);
+  while (now() < deadline && (entries.length === 0 || entries.some((e) => e.state === 'in_progress'))) {
+    await sleep(POLL_MS);
+    entries = since(dir, sinceMs);
+  }
+  const settled = entries.length > 0 && entries.every((e) => e.state === 'complete');
+  return { entries, timedOut: !settled && waitMs > 0 };
+}
+
+/**
+ * Whether Chrome asks where to save each download (Settings → Downloads), which
+ * opens a "Save as" dialog BrowserZap cannot answer. Read from the Preferences of
+ * the profile Chrome used last (Local State), or the one named. Null when unknown.
+ */
+function asksWhereToSave({ dataDir, profileDir = null, readFile = (f) => fs.readFileSync(f, 'utf8') } = {}) {
+  if (!dataDir) return null;
+  try {
+    let dir = profileDir;
+    if (!dir) {
+      const state = JSON.parse(readFile(path.join(dataDir, 'Local State')));
+      dir = state?.profile?.last_used || 'Default';
+    }
+    const prefs = JSON.parse(readFile(path.join(dataDir, dir, 'Preferences')));
+    return prefs?.download?.prompt_for_download === true;
+  } catch {
+    return null;
+  }
+}
+
+const ASK_HINT = 'Chrome is set to ask where to save each download, so every download opens a "Save as" dialog that ' +
+  'BrowserZap cannot answer. Turn off "Ask where to save each file before downloading" in chrome://settings/downloads.';
+
+function describe(e) {
+  const kb = e.sizeBytes < 1024 ? `${e.sizeBytes} B` : e.sizeBytes < 1048576 ? `${Math.round(e.sizeBytes / 1024)} KB` : `${(e.sizeBytes / 1048576).toFixed(1)} MB`;
+  return `${e.fileName ?? 'a file'} (${e.state === 'complete' ? kb : 'still downloading'})`;
+}
+
+module.exports = { asksWhereToSave, ASK_HINT, downloadDir, snapshot, names, arrived, since, waitFor, describe, finalName, expandWindowsVars, PARTIAL_RE };