jevway 0.1.2 → 0.3.0

package/SETUP.md

@@ -0,0 +1,212 @@
+# 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 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`, the client lists the `jevway_*` tools, and the smoke test
+ended `done` with a run page you showed the person.
+
+## Rules
+
+- **Show a diff before editing any MCP config file, and wait for approval.** Keep the person's other servers as they
+  are. When the client has an `mcp add` command, prefer it.
+- **Never ask for the key in the chat, and never echo it.** The person puts it in `~/.config/jevway/env` themselves
+  (below), or in the client's env block. Don't write a key into config that is committed to git or synced between
+  machines.
+- **Never relaunch, close or restart a browser you didn't start.** For the person's own Chrome, ask them to allow
+  remote debugging. If they'd rather keep it untouched, use `JEVWAY_BROWSER=launch` (a throwaway profile jevway starts
+  and closes).
+- **Pass the key explicitly when the client filters the environment.** Codex, for example, gives MCP servers only a few
+  variables. The env file works on every client, because jevway reads it itself; the client only has to pass `HOME`.
+  Otherwise put `TYPESAFE_API_KEY` in that server's env block.
+- **Stop and ask** when a step would change another browser tool's config, or when the doctor reports something this
+  file doesn't cover.
+
+## 1. Check the machine
+
+```bash
+npx -y jevway doctor --json
+```
+
+It prints `{ ready, findings: [{ check, level, message, fix? }] }`; `--plan` prints the steps still missing, numbered.
+It needs no key to run and never prints one. It checks:
+- Node 24 or later;
+- a key, and which route it selects;
+- 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`.
+
+## 2. The key
+
+jevway needs one of these:
+- `TYPESAFE_API_KEY` (preferred): Jev on the TypeSafe API, with screenshots and Box.
+- `OPENROUTER_API_KEY`: Jev, and the other models, through OpenRouter.
+
+The easiest way for the person: run `npx -y jevway setup` in their own terminal. It reads the key with hidden input,
+writes only that line to `~/.config/jevway/env` (mode 600), tests the browser, and offers to register their MCP
+clients, showing each change first.
+
+Or they add the line themselves, in their own editor or terminal, never in this chat:
+
+```bash
+mkdir -p ~/.config/jevway && touch ~/.config/jevway/env && chmod 600 ~/.config/jevway/env
+# then, in an editor: TYPESAFE_API_KEY=<their key>
+```
+
+How the file is read:
+- `jevway` and `jevway-mcp` read it at start (`$XDG_CONFIG_HOME/jevway/env` when that is set).
+- They take only the keys, `CHROME_PATH` and `JEVWAY_*` settings.
+- A variable already in the environment wins.
+
+Without a key the MCP server still starts and lists its tools. `jevway_look` works, and each other call answers with
+the fix.
+
+## 3. Register the MCP server
+
+Use the server name `jevway`. Add `JEVWAY_BROWSER` only if the person chose something other than `auto`.
+
+**Claude Code.** The plugin brings the server and the skill in one install. Run these inside Claude Code:
+
+```text
+/plugin marketplace add AbdallahAHO/jevway
+/plugin install jevway@jevway
+```
+
+Otherwise ask jevway for the exact command or snippet. It prints, and changes nothing:
+
+```bash
+npx -y jevway setup --client claude-code --print   # also: codex, cursor, opencode, other
+npx -y jevway setup --client cursor --print --json # { client, kind, command?, file?, snippet }
+```
+
+- `kind: "command"` (Claude Code, Codex): run `command`. For Codex, `snippet` is the table it writes to `file`.
+- `kind: "config"` (Cursor, OpenCode): merge `snippet` into `file`, keeping every other server; show the person the
+  diff first and wait for approval. `other` gives the `command` and `args` for any stdio MCP client.
+
+## 4. The browser
+
+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 |
+| --- | --- | --- |
+| `auto` (default) | their running Chrome, shared with `chrome-devtools-mcp --auto-connect` | open `chrome://inspect/#remote-debugging` and allow it; Chrome asks once more on jevway's first connection |
+| `launch` / `launch-headless` | a throwaway profile jevway starts and closes | nothing (Chrome must be installed, or `CHROME_PATH` set) |
+| `http://127.0.0.1:<port>` | a Chrome started with `--remote-debugging-port=<port>` and its own `--user-data-dir` | start that Chrome; never point it at their everyday profile |
+
+## 5. The skill (clients other than the Claude Code plugin)
+
+The skill says when to use `jevway_task` and when to use chrome-devtools. It ships in the package; `jevway skill`
+prints it, and this copies it into a client's skills folder as `<folder>/jevway/`:
+
+```bash
+npx -y jevway skill --install ~/.codex/skills   # or ~/.claude/skills, ~/.cursor/skills, ~/.config/opencode/skills
+```
+
+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 setup
+
+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:
+     `npx @modelcontextprotocol/inspector --cli npx -y -p jevway jevway-mcp --method tools/list`.
+3. Optional, costs a fraction of a cent: `npx -y jevway doctor --live` makes one real Jev request and reports its
+   latency.
+
+## 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/daemon-call.js

@@ -0,0 +1,78 @@
+import { resolve } from 'node:path';
+import { DaemonFailure } from '../daemon/client.js';
+import { outRoot } from '../output/layout.js';
+import { CliError, usageError } from './flags.js';
+import { eventPrinter } from './output.js';
+const BROWSER = /^(auto|launch|launch-headless|https?:\/\/\S+|wss?:\/\/\S+)$/;
+/** The browser and model a new session or one-shot run uses: the flags, else `JEVWAY_BROWSER` / `JEVWAY_MODEL` / `JEVWAY_SCREENSHOTS`. */
+export const runnerChoice = (flags, env) => {
+    const pick = (flag, variable) => (typeof flags[flag] === 'string' ? flags[flag] : env[variable]?.trim() || undefined);
+    const browser = pick('browser', 'JEVWAY_BROWSER') ?? 'auto';
+    if (!BROWSER.test(browser)) {
+        throw usageError('invalid_value', `--browser must be auto, launch, launch-headless or a debugging URL, got "${browser}"`, 'Example: --browser launch-headless');
+    }
+    const model = pick('model', 'JEVWAY_MODEL');
+    const screenshots = pick('screenshots', 'JEVWAY_SCREENSHOTS');
+    return { browser, ...(model && { model }), ...(screenshots && { screenshots }) };
+};
+/** A runner for `choice`; an unknown model or screenshot mode is a usage error. */
+export const runnerFor = (deps, { browser, ...choice }) => {
+    try {
+        return deps.createRunner(browser, choice);
+    }
+    catch (error) {
+        throw usageError('invalid_value', error.message, 'jevway run --help lists the models and screenshot modes');
+    }
+};
+/** Fails with `missing_key` (exit 2) before any browser or daemon starts when the model's key is not set. */
+export const requireKey = (runner) => {
+    try {
+        runner.requireKey();
+    }
+    catch (error) {
+        throw usageError('missing_key', error.message, 'Run jevway setup in a terminal, or see jevway doctor');
+    }
+};
+/** Where this caller's files go: resolved here, so they land under its working directory whoever started the daemon. */
+export const placement = ({ env, cwd }) => ({
+    outDir: outRoot(env, cwd),
+    ...(env.JEVWAY_JOURNEYS_DIR?.trim() && { journeysDir: resolve(cwd, env.JEVWAY_JOURNEYS_DIR.trim()) }),
+    cwd,
+});
+/** The running daemon, started when needed (a new session), or found (a session it should already hold). */
+export const daemonFor = async (deps, need) => {
+    if ('start' in need)
+        return deps.daemon.ensure(eventPrinter(deps.io));
+    const running = await deps.daemon.find();
+    if (running)
+        return running;
+    throw new CliError(1, 'unknown_session', `Unknown ${need.kind} "${need.session}": no jevway daemon is running, and sessions end when it stops (or after its idle time).`, need.kind === 'session' ? 'Start a new one with jevway run --session new --url <url> --goal <goal>' : 'Start a new one with jevway journey start --url <url>');
+};
+/**
+ * Calls the daemon and closes the connection. A connection lost mid-call is `outcome_unknown` for a call that may
+ * have clicked or typed (`writes`), pointing at `jevway look` for the session, else `daemon_unavailable`.
+ */
+export const callDaemon = async (connection, method, params, { writes, session, log, ...options }) => {
+    try {
+        return await connection.request(method, params, options);
+    }
+    catch (error) {
+        if (!(error instanceof DaemonFailure) || !error.lost)
+            throw error;
+        if (!writes)
+            throw new CliError(1, 'daemon_unavailable', error.message, `See ${log}; jevway stop and run the command again`);
+        const id = session?.();
+        throw new CliError(1, 'outcome_unknown', 'The daemon stopped answering while the call was running; it may already have clicked or typed.', id ? `Check the page with jevway look --session ${id} before repeating the call.` : 'Find the session with jevway sessions and check its page with jevway look --session <id> before repeating the call.');
+    }
+    finally {
+        connection.close();
+    }
+};
+/** How long a client waits for a call: always longer than the daemon's own limit for it. */
+export const TIMEOUTS = {
+    /** A task call: its time budget (`--max-seconds`, default 300; a continue may carry up to 3600) plus two minutes. */
+    task: (maxSeconds, continuing) => ((maxSeconds ?? (continuing ? 3600 : 300)) + 120) * 1000,
+    quick: 60_000,
+    /** Autopilot has no step limit of its own. */
+    journey: 30 * 60_000,
+};