jevway 0.2.0 → 0.3.0

package/README.md

@@ -40,6 +40,7 @@ optional tools unlock more.
 | **Google Chrome** (or Chromium) | every run: your running Chrome, or a throwaway one jevway starts | runs fail; set `CHROME_PATH` if Chrome isn't in the usual place |
 | **An API key**: `TYPESAFE_API_KEY` (recommended) or `OPENROUTER_API_KEY` | every decision Jev makes | the server still starts and lists its tools, and `jevway_look` works, but tasks and journeys answer with the setup fix |
 | `ffmpeg` *(optional)* | the `run.mp4` video in a recording | recordings keep their step screenshots and HTML page, without the video |
+| `notify-send` *(optional, Linux)* | the desktop notification when a person is needed (macOS has it built in) | the agent still asks you; there's just no pop-up |
 | chrome-devtools MCP *(optional)* | inspecting what jevway left on screen: console, network, performance, DOM details | nothing is lost in jevway itself; your agent just has no deeper inspection tool |
 
 **Which key?** Both run the same Jev model. The TypeSafe key adds **Box**, which locates controls on the screenshot:
@@ -78,6 +79,20 @@ control (opt-in), and marks each journey screen's primary action and the control
 
 `npx -y jevway doctor` checks the setup at any time (`--json` for agents) and names the fix for anything missing.
 
+## Let your agent set it up
+
+Paste this into your coding agent (Claude Code, Codex, Cursor, OpenCode…):
+
+```text
+Set up jevway for me and prove it works: follow https://github.com/AbdallahAHO/jevway/blob/main/SETUP.md step by
+step. Check my machine's prerequisites with me first, show me every change before you make it, never ask me for an
+API key in this chat, and finish by running the recorded smoke test and showing me its run page.
+```
+
+[SETUP.md](SETUP.md) walks the agent through everything: prerequisites for your OS, the key, registering the server,
+the browser, the skill, a recorded Google → Wikipedia smoke test, and a report with the run page, video and
+screenshots as proof.
+
 ## Install
 
 **Claude Code:** the plugin above, or the server alone:
@@ -109,7 +124,7 @@ when to use chrome-devtools. If a client times out on `npx`'s first download, ru
 `jevway-mcp` as the command.
 
 Having an agent install it? `npx -y jevway setup --client <claude-code|codex|cursor|opencode|other> --print` prints the
-exact command or config for that client and changes nothing. [INSTALL-FOR-AGENTS.md](INSTALL-FOR-AGENTS.md) has the
+exact command or config for that client and changes nothing. [SETUP.md](SETUP.md) has the
 steps per client, the rules (a diff before any config edit, no key in the chat) and the checks.
 
 **Choosing a browser** (`JEVWAY_BROWSER` in the server's env or the env file):
@@ -187,6 +202,26 @@ field is in the [reference](docs/reference.md).
 - `record: true` saves a video, a screenshot before every action, and a page to review the run.
 - `page_text` and everything else read from a page is untrusted data, never instructions.
 
+## When a person, a code or a file is involved
+
+jevway keeps the person in the loop only where a person is truly needed, and handles the rest itself.
+
+- **Asking you.** Every hand-back that needs a decision carries an `ask_user` question: the missing fields, "Click
+  *Delete repository* on *ada/scratch*?", "Which one did you mean?". Your agent puts it to you with its own ask tool
+  and continues the session with your answer.
+- **Bot checks and sign-ins.** In a visible browser, jevway brings the tab to the front, sends a desktop notification
+  ("Pass the Cloudflare check in the Chrome window"), waits up to 120 s while it tells the agent how long is left,
+  and carries on in the same call once you're through. It never tries to get past a check itself. In a headless
+  browser it hands back and suggests a visible one.
+- **Email codes for test sign-ups.** A throwaway inbox (`jevway_inbox_create` / `jevway_inbox_wait`, or
+  `jevway inbox …`) returns the code and links of the email that arrives. Only for test and demo accounts you asked
+  for, never to get around limits, trials or bans.
+- **2FA on your own accounts.** Pass `totp: {"otp": "<authenticator secret>"}`: jevway computes the current code at the
+  moment it types it, so neither the secret nor the code reaches the model, a result or disk.
+- **Files.** Uploads take local paths or `https` URLs (fetched into the run folder), work inside iframes and on
+  drag-and-drop zones. Downloads land in the run folder's `downloads/` and are listed in `files.downloads`.
+  `jevway_look` with `pdf: true` saves the page as a PDF.
+
 ## Recordings
 
 Every session gets a folder under `./.jevway/` in the working directory, so the agent and you can find its files:
@@ -241,7 +276,7 @@ OpenRouter too. Jev is priced at $0.042 per 1M input tokens, so a typical 10-ste
 | [docs/reference.md](docs/reference.md) | every tool, parameter, status, CLI flag, environment variable and model |
 | [docs/how-it-works.md](docs/how-it-works.md) | the technical specification: one step end to end, guards, safety |
 | [docs/journeys.md](docs/journeys.md) | the journey-map tools |
-| [INSTALL-FOR-AGENTS.md](INSTALL-FOR-AGENTS.md) | agents installing jevway for a person |
+| [SETUP.md](SETUP.md) | agents setting jevway up for a person, with a recorded smoke test |
 | [skill/jevway/SKILL.md](skill/jevway/SKILL.md) | the skill agents load: when and how to call jevway |
 | [docs/verification.md](docs/verification.md) | the test suites and their results |
 | [docs/prior-art.md](docs/prior-art.md) | other open-source Jev browser projects, and what was taken from them |

package/{INSTALL-FOR-AGENTS.md → SETUP.md}

@@ -1,20 +1,34 @@
-# Installing jevway (for agents)
-
-You are an agent asked to install jevway for a person. jevway is an MCP server, `jevway-mcp`, plus a CLI, `jevway`.
-It hands browser goals to TypeSafe Jev. Both come from the npm package `jevway`.
-
-Read this whole file before you run anything. Run only these:
+# Setting up jevway (for agents)
+
+You are an agent asked to set up jevway for a person and prove it works. jevway is an MCP server, `jevway-mcp`, plus a
+CLI, `jevway`, both from the npm package `jevway`. It hands browser goals to TypeSafe Jev and returns one checked
+summary per goal.
+
+Read this whole file before you run anything. You will:
+1. check the machine's prerequisites with the person and help install what's missing;
+2. get the API key in place (the person does that part);
+3. register the MCP server with the client you're running in;
+4. pick the browser with the person;
+5. install the skill;
+6. check the setup;
+7. run a recorded smoke test, from Google to Wikipedia;
+8. report back with the run page, its video and screenshots, as proof.
+
+Run only these yourself:
+- `node --version`, `ffmpeg -version`, and the person-approved install commands from step 1;
 - `npx -y jevway doctor --json` (or `--plan`, or `jevway doctor`);
 - `npx -y jevway setup --client <name> --print [--json]`, which prints how to register jevway with a client and
   changes nothing;
 - `npx -y jevway skill --install <skills folder>`;
 - `npm install -g jevway`;
-- the client's own `mcp add` command, or an edit to its MCP config file that the person approved.
+- the client's own `mcp add` command, or an edit to its MCP config file that the person approved;
+- the jevway tools themselves (or `npx -y jevway run …`) for the smoke test.
 
 Never run plain `jevway setup` yourself: it is the person's interactive setup, and without a terminal it exits 2 with
 `{ "ok": false, "error": { "code": "needs_tty", … } }`.
 
-Done means: `jevway doctor --json` prints `"ready": true` (exit 0), and the client lists the `jevway_*` tools.
+Done means: `jevway doctor --json` prints `"ready": true`, the client lists the `jevway_*` tools, and the smoke test
+ended `done` with a run page you showed the person.
 
 ## Rules
 
@@ -45,6 +59,19 @@ It needs no key to run and never prints one. It checks:
 - the browser source;
 - ffmpeg (optional: only for recordings).
 
+`npx` itself needs Node, so check `node --version` first. For anything missing, propose the command that fits the
+person's OS and package manager, and run it only after they say yes (or wait while they install it themselves, then
+check again):
+
+| Tool | Needed for | macOS (Homebrew) | Debian / Ubuntu | Fedora | Windows (winget) |
+| --- | --- | --- | --- | --- | --- |
+| Node.js 24+ | running jevway (required) | `brew install node` | Node 24 from NodeSource or nvm | `sudo dnf install nodejs` (check it's 24+) | `winget install OpenJS.NodeJS` |
+| Chrome or Chromium | every run (required) | `brew install --cask google-chrome` | Google's `.deb`, or `sudo apt install chromium` | `sudo dnf install chromium` | `winget install Google.Chrome` |
+| ffmpeg | the video in a recording (optional) | `brew install ffmpeg` | `sudo apt install ffmpeg` | `sudo dnf install ffmpeg-free` | `winget install Gyan.FFmpeg` |
+| notify-send | the desktop notification when a person is needed (optional, Linux) | built in | `sudo apt install libnotify-bin` | `sudo dnf install libnotify` | not used |
+
+A Chrome in an unusual place: set `CHROME_PATH` in `~/.config/jevway/env`.
+
 If the first `npx` start is slow, or a client times out starting the server, install once with `npm install -g jevway`.
 Then use `jevway-mcp` as the command instead of `npx -y -p jevway jevway-mcp`.
 
@@ -97,7 +124,8 @@ npx -y jevway setup --client cursor --print --json # { client, kind, command?, f
 
 ## 4. The browser
 
-`JEVWAY_BROWSER` (the server's env, or `--browser` for the CLI):
+Ask the person which browser jevway should use, and set `JEVWAY_BROWSER` in the server's env (or `--browser` for
+the CLI) when it isn't `auto`. For the smoke test a visible one is best, so they can pass a check if one appears.
 
 | Value | What it uses | What the person does |
 | --- | --- | --- |
@@ -117,11 +145,13 @@ npx -y jevway skill --install ~/.codex/skills   # or ~/.claude/skills, ~/.cursor
 It prints `{ ok, status, path, files }`. A different `jevway` skill already there (or a symlink to one) is left alone
 with `"code": "skill_exists"` and exit 1; replace it with `--force` only if the person agrees.
 
-## 6. Check the outcome
+## 6. Check the setup
 
-1. `npx -y jevway doctor --json` prints `"ready": true` and exits 0 (every finding `ok` or `warn`).
-2. The client lists the tools: `jevway_task`, `jevway_look`, `jevway_end` and `jevway_journey_start`, `_step`,
-   `_autopilot`, `_annotate`, `_finish`.
+1. `npx -y jevway doctor --json` prints `"ready": true` and exits 0 (every finding `ok` or `warn`). For every finding
+   that isn't `ok`, tell the person the fix in one line and wait; re-run it after each fix (`--plan` lists the steps
+   left).
+2. The client lists the tools: `jevway_task`, `jevway_look`, `jevway_end`, the five `jevway_journey_*` tools and
+   `jevway_inbox_create` / `jevway_inbox_wait`.
    - In Claude Code: `/mcp`.
    - Elsewhere, the client's MCP list.
    - Or the MCP Inspector:
@@ -129,4 +159,54 @@ with `"code": "skill_exists"` and exit 1; replace it with `--force` only if the
 3. Optional, costs a fraction of a cent: `npx -y jevway doctor --live` makes one real Jev request and reports its
    latency.
 
-When a check fails, the doctor names the cause and the fix, and `--plan` lists the steps left. Re-run it after each fix.
+## 7. The smoke test
+
+Call `jevway_task` with:
+
+```json
+{
+  "url": "https://www.google.com",
+  "goal": "Search Google for the Rosetta Stone and open its English Wikipedia article",
+  "values": { "query": "Rosetta Stone Wikipedia" },
+  "done_when": "The English Wikipedia article about the Rosetta Stone is open",
+  "allowed_hosts": ["google.com", "*.google.com", "en.wikipedia.org"],
+  "record": true,
+  "detail": "full"
+}
+```
+
+What to expect, and what to do:
+- **A cookie banner** is handled by jevway (it declines when it can).
+- **A reCAPTCHA ("unusual traffic")** is common for automated browsers on Google. In a visible browser jevway brings
+  the tab to the front, sends the person a desktop notification and waits up to 2 minutes for them to pass it; it
+  never solves it. Tell the person it may happen before you start.
+- **A result with `ask_user`** (a bot check, a sign-in, a missing value): put that question to the person with your
+  own ask tool, then do what its `then` says.
+- **Google keeps blocking**: run the same goal from `https://duckduckgo.com` with
+  `allowed_hosts: ["duckduckgo.com", "en.wikipedia.org"]`. It usually finishes in 5 steps.
+- **No MCP in your client**: run the same test with the CLI, which prints one JSON result on stdout:
+
+  ```bash
+  npx -y jevway run --browser launch --record --detail full --url https://www.google.com \
+    --goal "Search Google for the Rosetta Stone and open its English Wikipedia article" \
+    --values '{"query":"Rosetta Stone Wikipedia"}' \
+    --done-when "The English Wikipedia article about the Rosetta Stone is open" \
+    --allowed-hosts "google.com,*.google.com,en.wikipedia.org"
+  ```
+
+End the session with `jevway_end` when you have what you need.
+
+## 8. Report back
+
+Tell the person, in this shape:
+- **Outcome:** `status` and `reason`, and the `story` as a numbered list.
+- **Proof:** the run page `files.page` (open it for them: `open` on macOS, `xdg-open` on Linux, `start` on Windows),
+  the video `files.video` (present when ffmpeg is installed), the end screenshot `files.screenshot` (show it if you
+  can display images), and the run folder `files.run_dir` with its `manifest.json`.
+- **Cost:** `jev.requests` and `jev.est_cost_usd` (an estimate; a typical smoke test is well under a cent).
+- **Setup:** what you installed or changed, with the person's yes for each.
+- **Anything that needed them**, and anything that didn't work, with the fix.
+
+The run page opens with the goal and how it ended, then the video with every step on a timeline and a strip of
+screenshots kept in sync. It is the proof that the whole chain works: the client, the MCP server, the key, the
+browser and Jev.

package/dist/browser/downloads.js

@@ -0,0 +1,103 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, relative, isAbsolute } from 'node:path';
+const STAGING = new WeakMap();
+/**
+ * Sets how the browser behind `cdp` downloads, once per connection: jevway's launched browser saves every download under
+ * its guid in a staging folder of its own; the person's Chrome (`auto`, a debugging URL) keeps its own behaviour and only
+ * reports downloads. A browser that refuses never fails a run: its downloads go unreported.
+ *
+ * @example
+ * await useDownloads(cdp, 'launch-headless'); // Browser.setDownloadBehavior { behavior: 'allowAndName', downloadPath: '/tmp/jevway-downloads-…' }
+ */
+export const useDownloads = async (cdp, source) => {
+    if (source !== 'launch' && source !== 'launch-headless') {
+        await cdp.send('Browser.setDownloadBehavior', { behavior: 'default', eventsEnabled: true }).catch(() => undefined);
+        return;
+    }
+    const downloadPath = mkdtempSync(join(tmpdir(), 'jevway-downloads-'));
+    STAGING.set(cdp, downloadPath);
+    await cdp.send('Browser.setDownloadBehavior', { behavior: 'allowAndName', downloadPath, eventsEnabled: true }).catch(() => undefined);
+};
+/** Removes the staging folder of a launched browser's connection, with whatever was never kept. */
+export const dropStagedDownloads = (cdp) => {
+    const dir = STAGING.get(cdp);
+    if (dir)
+        rmSync(dir, { recursive: true, force: true });
+    STAGING.delete(cdp);
+};
+const inside = (dir, path) => {
+    if (!dir || !path)
+        return false;
+    const rel = relative(dir, path);
+    return Boolean(rel) && !rel.startsWith('..') && !isAbsolute(rel);
+};
+/**
+ * The downloads one tab started: `owns` says whether a frame id is the tab's (its page, one of its frames, a tab it
+ * opened). Every other download, in the person's other tabs too, is never recorded.
+ *
+ * @example
+ * const downloads = new TabDownloads(cdp, (frameId) => frameId === targetId);
+ * const finished = await downloads.settle({ waitMs: 30_000 });
+ */
+export class TabDownloads {
+    #cdp;
+    #owns;
+    #all = new Map();
+    #untaken = [];
+    #changed = new Set();
+    constructor(cdp, owns) {
+        this.#cdp = cdp;
+        this.#owns = owns;
+    }
+    /** Starts listening; returns the unsubscribe. */
+    watch() {
+        return this.#cdp.onEvent((method, params, sessionId) => {
+            if (sessionId || !method.startsWith('Browser.download'))
+                return;
+            if (method === 'Browser.downloadWillBegin' && this.#owns(params.frameId)) {
+                this.#all.set(params.guid, { guid: params.guid, name: params.suggestedFilename, url: params.url, state: 'inProgress', bytes: 0, staged: false });
+                this.#untaken.push(params.guid);
+            }
+            const known = method === 'Browser.downloadProgress' && this.#all.get(params.guid);
+            if (!known)
+                return;
+            const filePath = params.filePath ?? known.filePath;
+            this.#all.set(params.guid, {
+                ...known,
+                state: params.state,
+                bytes: params.receivedBytes ?? known.bytes,
+                ...(filePath && { filePath }),
+                staged: inside(STAGING.get(this.#cdp), filePath),
+            });
+            for (const changed of this.#changed)
+                changed();
+        });
+    }
+    /**
+     * Takes the downloads begun since the last take, after waiting up to `waitMs` (or until `signal`) for those still
+     * running. Each comes back as it stands then: completed, canceled, or still in progress.
+     */
+    async settle({ waitMs, signal }) {
+        const taken = this.#untaken.splice(0);
+        const running = () => taken.some((guid) => this.#all.get(guid)?.state === 'inProgress');
+        if (taken.length && running() && !signal?.aborted) {
+            await new Promise((resolve) => {
+                const done = () => {
+                    clearTimeout(timer);
+                    signal?.removeEventListener('abort', done);
+                    this.#changed.delete(check);
+                    resolve();
+                };
+                const check = () => {
+                    if (!running())
+                        done();
+                };
+                const timer = setTimeout(done, waitMs);
+                signal?.addEventListener('abort', done, { once: true });
+                this.#changed.add(check);
+            });
+        }
+        return taken.map((guid) => ({ ...this.#all.get(guid) }));
+    }
+}

package/dist/browser/frames.js

@@ -134,6 +134,7 @@ export class Frames {
     #sessionId;
     #counter;
     #touch = false;
+    #files = false;
     #mainFrameId = '';
     #viewport = { w: 0, h: 0 };
     /** Out-of-process frames attached so far, by target id (= frame id). */
@@ -164,6 +165,20 @@ export class Frames {
         for (const { sessionId } of this.#children.values())
             void this.#emulateTouch(sessionId);
     }
+    /**
+     * The caller declared files: frame reads list file inputs and drop zones, and out-of-process frames keep native file
+     * pickers closed too (the page's own session does that for same-process frames).
+     */
+    set files(enabled) {
+        if (enabled && !this.#files)
+            for (const { sessionId } of this.#children.values())
+                void this.#interceptFileChooser(sessionId);
+        this.#files = enabled;
+    }
+    /** Whether a protocol frame id is this tab's: its page, a frame read on it, or an out-of-process frame attached to it. */
+    holds(frameId) {
+        return Boolean(frameId) && (frameId === this.#mainFrameId || this.#known.has(frameId) || this.#children.has(frameId));
+    }
     /** The frame holding an element id: undefined for the main frame and for a frame no longer on the page. */
     ofNode(node) {
         const base = idBaseOf(node);
@@ -228,7 +243,7 @@ export class Frames {
         // The text walk keeps to the part of the frame the page shows, in the frame's own coordinates.
         const { offset, region } = placement;
         const view = { x: region.x - offset.x, y: region.y - offset.y, w: region.w, h: region.h };
-        const response = await this.evaluate(frame, `window.__jevIdBase=${frame.base};window.__jevView=${JSON.stringify(view)};window.__jevWanted=${JSON.stringify(wanted)};${script}`, { timeout: FRAME_READ_MS });
+        const response = await this.evaluate(frame, `window.__jevIdBase=${frame.base};window.__jevView=${JSON.stringify(view)};window.__jevWanted=${JSON.stringify(wanted)};window.__jevFiles=${this.#files};${script}`, { timeout: FRAME_READ_MS });
         const state = response.exceptionDetails ? null : response.result?.value;
         if (!state)
             return null;
@@ -404,6 +419,8 @@ export class Frames {
             await this.#send('Page.addScriptToEvaluateOnNewDocument', { source: this.#counter, worldName: WORLD }, sessionId);
             await this.#send('Emulation.setFocusEmulationEnabled', { enabled: true }, sessionId).catch(() => undefined);
             await this.#emulateTouch(sessionId);
+            if (this.#files)
+                await this.#interceptFileChooser(sessionId);
             await this.#autoAttach(sessionId);
         }
         catch {
@@ -418,6 +435,9 @@ export class Frames {
         const enabled = this.#touch;
         return this.#send('Emulation.setTouchEmulationEnabled', { enabled, maxTouchPoints: enabled ? 5 : 1 }, sessionId).catch(() => undefined);
     }
+    #interceptFileChooser(sessionId) {
+        return this.#send('Page.setInterceptFileChooserDialog', { enabled: true }, sessionId).catch(() => undefined);
+    }
     #autoAttach(sessionId) {
         return this.#send('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: true, flatten: true, filter: [{ type: 'iframe' }] }, sessionId);
     }

package/dist/browser/snapshot.js

@@ -424,10 +424,12 @@
       }
       return null;
     };
+    const anchors = [];
     for (const input of fileInputs) {
       if (input.matches(':disabled') || input.closest('[aria-disabled="true"],[inert]')) continue;
       const anchor = standInFor(input);
       if (!anchor || outOfView(anchor.getBoundingClientRect())) continue;
+      anchors.push(anchor);
       const r = cache.clickRect(anchor),
         own = (anchor === input ? name(input) : name(input) || name(anchor)).replace(/\s+/g, ' ').trim();
       actions.push({
@@ -439,6 +441,57 @@
         rect: { x: r.x, y: r.y, w: r.width, h: r.height },
       });
     }
+    // jevway: a drop zone with no file input in it is listed only on clear markers: an ondrop attribute, a drop-zone
+    // name in its class, id or a data- attribute, or a short text asking for a file to be dropped ("Drag and drop",
+    // "Drop your CV here"; its nearest box of 40×40 or more). The innermost zone wins; one holding or inside a file field's stand-in
+    // is that field already. The file is dropped onto it.
+    const DROP_NAME = /drop-?zone|drop-?area|file-?drop|drop-?target/i;
+    const DROP_TEXT =
+      /\bdrag\s*(?:and|&|'?n'?)\s*drop\b|\bdrop\s+(?:your\s+|a\s+|an\s+|the\s+)?(?:files?|cv|resume|résumé|images?|photos?|documents?|attachments?)\b/i;
+    const named = (e) =>
+      e.hasAttribute('ondrop') ||
+      DROP_NAME.test(typeof e.className === 'string' ? e.className : '') ||
+      DROP_NAME.test(e.id) ||
+      [...e.attributes].some((a) => a.name.startsWith('data-') && DROP_NAME.test(a.name));
+    const big = (e) => {
+      const r = e.getBoundingClientRect();
+      return r.width >= 40 && r.height >= 40;
+    };
+    const zones = new Set(
+      [...document.querySelectorAll('[ondrop],[class*="drop" i],[id*="drop" i]')].filter(named),
+    );
+    const texts = document.createTreeWalker(document.body ?? document.documentElement, NodeFilter.SHOW_TEXT, {
+      acceptNode: (t) => (t.data.length <= 200 && DROP_TEXT.test(t.data) ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP),
+    });
+    for (let t = texts.nextNode(), seen = 0; t && seen < 20; t = texts.nextNode(), seen++) {
+      let box = t.parentElement;
+      for (let up = 0; box && up < 4 && !big(box); up++) box = box.parentElement;
+      if (box && big(box)) zones.add(box);
+    }
+    const listed = [...zones].filter(
+      (zone) =>
+        zone !== document.body &&
+        zone !== document.documentElement &&
+        visible(zone) &&
+        big(zone) &&
+        !outOfView(zone.getBoundingClientRect()) &&
+        !zone.querySelector('input[type=file]') &&
+        !anchors.some((anchor) => anchor.contains(zone) || zone.contains(anchor)),
+    );
+    for (const zone of listed) {
+      if (listed.some((other) => other !== zone && zone.contains(other))) continue;
+      const r = cache.clickRect(zone),
+        text = (zone.innerText || '').replace(/\s+/g, ' ').trim();
+      actions.push({
+        node: identity(zone),
+        role: 'file',
+        kind: 'upload',
+        drop: true,
+        label: cap(name(zone).replace(/\s+/g, ' ').trim() || text || 'drop zone', 120) + ' (drop zone)',
+        value: '',
+        rect: { x: r.x, y: r.y, w: r.width, h: r.height },
+      });
+    }
   }
   // jevway: controls sharing a role and label (a product grid's "Add to cart" buttons) are told apart by the card or
   // row each sits in, as a person reads the page: "Add to cart — Sauce Labs Bike Light". Only colliding labels change;

package/dist/browser/tab.js

@@ -4,6 +4,7 @@ import { readFileSync } from 'node:fs';
 import { isDeepStrictEqual } from 'node:util';
 import { CdpError } from './cdp.js';
 import { DEVICES } from './devices.js';
+import { TabDownloads } from './downloads.js';
 import { Frames, idBaseOf, mergeFrames, whenAborted } from './frames.js';
 import { messageNames } from './words.js';
 // Atomic DOM read from browser-use/jev-ultrafast (MIT): visible text + indexed controls + freshness guards.
@@ -72,6 +73,9 @@ export class Tab {
     #device;
     /** Page tabs this tab opened (target=_blank, window.open) that the run has not taken yet, oldest first. */
     #opened = [];
+    /** Every page tab this tab opened, taken or not: a download one of them starts is this tab's. */
+    #openedEver = new Set();
+    #downloads;
     #closed = false;
     #unsubscribe = [];
     /** The running call's stop signal: the waits after an input end early on it (see `stopSignal`). */
@@ -85,6 +89,7 @@ export class Tab {
         this.targetId = targetId;
         this.sessionId = sessionId;
         this.#frames = new Frames(cdp, sessionId, INPUT_COUNTER);
+        this.#downloads = new TabDownloads(cdp, (frameId) => frameId === targetId || this.#openedEver.has(frameId) || this.#frames.holds(frameId));
     }
     /**
      * Opens a background tab so the user's visible tab stays put. `newWindow` keeps the page rendering
@@ -233,13 +238,16 @@ export class Tab {
         // opened (the user's own, in their Chrome) is never attached, read or changed.
         tab.#unsubscribe.push(cdp.onEvent((method, params, sessionId) => {
             const info = params?.targetInfo;
-            if (method === 'Target.targetCreated' && info?.type === 'page' && info.openerId === targetId)
+            if (method === 'Target.targetCreated' && info?.type === 'page' && info.openerId === targetId) {
                 tab.#opened.push(info.targetId);
+                tab.#openedEver.add(info.targetId);
+            }
             if (method === 'Target.targetDestroyed' && params?.targetId === targetId)
                 tab.#closed = true;
             if (method === 'Target.detachedFromTarget' && params?.sessionId === tab.sessionId && !sessionId)
                 tab.#closed = true;
         }));
+        tab.#unsubscribe.push(tab.#downloads.watch());
         await cdp.send('Target.setDiscoverTargets', { discover: true }).catch(() => undefined);
         return tab;
     }
@@ -376,29 +384,64 @@ export class Tab {
         if (files && !this.#files)
             void this.#call('Page.setInterceptFileChooserDialog', { enabled: true }).catch(() => undefined);
         this.#files = files;
+        this.#frames.files = files;
     }
     /**
-     * Sets a declared file on an observed file input (hidden ones too), after the same element-level freshness check
-     * as a click. The path comes from the caller's `files`, never from the model or `values`.
+     * Sets a declared file on an observed file input (hidden ones too, in the page or in a frame), or drops it onto an
+     * observed drop zone, after the same element-level freshness check as a click. The path comes from the caller's
+     * `files`, never from the model or `values`.
      *
      * @example
      * await tab.upload(page.actions.find((a) => a.kind === 'upload')!, page, '/Users/ada/me.png');
      */
     async upload(action, page, path) {
-        // The file is set through the page's own session; a frame's node lives in another context, so it is refused by name.
-        if (action.node !== undefined && idBaseOf(action.node)) {
-            throw new TargetUnreachable(`"${action.label}" is inside a frame, and jevway uploads only to file fields in the page itself`);
-        }
         if (!(await this.fresh(page, action)))
             throw new StalePage('Page changed since this decision');
-        const { result } = await this.#call('Runtime.evaluate', {
-            expression: `(() => { const e = window.__jevFast?.nodes.get(${Number(action.node)}); return e?.isConnected && e.matches('input[type=file]:not(:disabled)') ? e : null; })()`,
+        if (action.drop)
+            return this.#drop(action, path);
+        // A frame's node lives in the frame's own world, and its file is set through the session that owns the frame.
+        const frame = this.#frameOf(action.node);
+        const expression = `(() => { const e = window.__jevFast?.nodes.get(${Number(action.node)}); return e?.isConnected && e.matches('input[type=file]:not(:disabled)') ? e : null; })()`;
+        const { result } = await (frame ? this.#frames.evaluate(frame, expression, { returnByValue: false }) : this.#call('Runtime.evaluate', { expression })).catch((error) => {
+            throw error instanceof CdpError && !TIMED_OUT.test(error.message) ? new StalePage(error.message) : error;
         });
         if (!result?.objectId)
             throw new TargetUnreachable('The file field is gone or disabled');
-        await this.#call('DOM.setFileInputFiles', { files: [path], objectId: result.objectId });
+        await this.cdp.send('DOM.setFileInputFiles', { files: [path], objectId: result.objectId }, frame?.sessionId ?? this.sessionId);
         this.#afterInput = action;
     }
+    // A drop zone with no file input: a trusted drag of the file onto its visible centre, checked to have reached the page.
+    async #drop(action, path) {
+        const frame = this.#frameOf(action.node);
+        const resolved = await this.#evaluateFor(frame, `(${RESOLVE_TARGET})(${JSON.stringify(action)})`);
+        if (!resolved || resolved.covered)
+            throw new TargetUnreachable('Target changed or is covered', Boolean(resolved?.byPopup), resolved?.coverNodes ?? []);
+        const target = frame ? await this.#frames.toViewport(frame, resolved) : resolved;
+        if ('covered' in target)
+            throw new TargetUnreachable('Target changed or is covered', false, target.coverNodes);
+        await this.#evaluateFor(frame, WATCH_DROP);
+        const data = { items: [], files: [path], dragOperationsMask: DRAG_COPY };
+        for (const type of ['dragEnter', 'dragOver', 'drop'])
+            await this.#call('Input.dispatchDragEvent', { type, x: target.x, y: target.y, data });
+        if (!(await this.#evaluateFor(frame, 'window.__jevDropped===true')))
+            throw new TargetUnreachable('The drop zone did not take the file');
+        this.#afterInput = action;
+    }
+    /**
+     * The downloads this tab (its page, its frames, a tab it opened) started since the last call, after waiting up to
+     * `waitMs` for those still running; the run's stop signal ends the wait early.
+     *
+     * @example
+     * await tab.downloadsAfterInput(); // [{ name: 'invoice-1042.pdf', state: 'completed', bytes: 86016, filePath, staged: true, … }]
+     */
+    downloadsAfterInput({ waitMs = DOWNLOAD_WAIT_MS } = {}) {
+        return this.#downloads.settle({ waitMs, signal: this.#stop });
+    }
+    /** The page as a PDF (its print styles, backgrounds included); headless and headed Chrome both print. */
+    async pdf() {
+        const { data } = await this.#call('Page.printToPDF', { printBackground: true });
+        return Buffer.from(data, 'base64');
+    }
     async observe() {
         if (this.#closed)
             throw new StalePage('The tab was closed');
@@ -845,6 +888,12 @@ const INTERACTIVE = 'a,button,input,select,textarea,[contenteditable="true"],' +
 const FIELD_LIKE = 'input:not([type="checkbox"],[type="radio"],[type="button"],[type="submit"],[type="reset"],[type="image"]),textarea,' +
     '[contenteditable="true"],[role="combobox"],[role="textbox"],[role="searchbox"],[role="spinbutton"]';
 // Resolves the observed node, rejects hidden/disabled/covered targets, and applies native selects in-page.
+// How long a step waits for the downloads it started to finish.
+const DOWNLOAD_WAIT_MS = 30_000;
+// Input.dispatchDragEvent's operation mask for a copy, as a file dragged from the desktop offers.
+const DRAG_COPY = 1;
+// Notes a drop reaching the document (in the target's world): a page that refuses the drag never gets one.
+const WATCH_DROP = `(() => { window.__jevDropped = false; window.addEventListener('drop', () => { window.__jevDropped = true; }, { capture: true, once: true }); return true; })()`;
 const RESOLVE_TARGET = `action => {
   const e=window.__jevFast?.nodes.get(action.node);
   if (!e?.isConnected || e.matches(':disabled') || e.closest('[aria-disabled="true"],[inert]') ||

package/dist/cli/dispatch.js

@@ -3,6 +3,7 @@ import { SETUP_USAGE, runSetup } from '../setup/setup-command.js';
 import { SKILL_USAGE, runSkill } from '../setup/skill-command.js';
 import { closestName, usageError } from './flags.js';
 import { topHelp } from './help.js';
+import { inboxCommand } from './inbox-command.js';
 import { journeyCommand } from './journey-command.js';
 import { lookCommand } from './look-command.js';
 import { printFailure } from './output.js';
@@ -12,6 +13,7 @@ const COMMANDS = {
     run: { summary: 'hand a browser goal to Jev (one-shot, or a session with --session)', run: runCommand },
     look: { summary: 'print what a page or a session\'s tab shows, with no model call', run: lookCommand },
     journey: { summary: 'map mobile user journeys: start, step, autopilot, annotate, finish', run: journeyCommand },
+    inbox: { summary: 'a throwaway email inbox for test and demo sign-ups: create, wait, list, read', run: inboxCommand },
     sessions: { summary: 'list the open sessions and journeys', run: sessionsCommand },
     end: { summary: 'end a session and close the tabs it opened', run: endCommand },
     serve: { summary: 'run the session daemon in the foreground', run: serveCommand },