From 176e7f9f3a24868088b6d7c71e2a4d34b2602218 Mon Sep 17 00:00:00 2001
From: Anthony Ettinger <anthony@chovy.com>
Date: Thu, 24 Sep 2026 07:03:03 +0000
Subject: [PATCH] Make browser automation work on real ATS forms (upload,
 custom selects, stable refs)

Dogfooding `tron automate` on Greenhouse and Ashby job applications hit
seven problems; each one broke form filling:

- No way to set a file input. Add browser_upload (MCP), `tron upload`
  (CLI) and Page.upload, via DOM.setFileInputFiles. Snapshots now list
  file inputs as role "file" even when an Attach button hides them.
- browser_select only handled native <select>. It now also drives
  custom comboboxes (react-select, ARIA listboxes) with trusted CDP
  mouse and text input, then clicks the matching [role=option].
  [role=option]/[role=combobox] are collectable in snapshots.
- browser_press dispatched untrusted KeyboardEvents that widgets ignore.
  It now uses Input.dispatchKeyEvent. Adds `tron press`.
- Every snapshot renumbered all refs, and every mutating tool takes one,
  so opening a dropdown shifted later refs and the next fill hit the
  wrong field. Refs are now stable per element; new elements get new
  numbers and a vanished element's ref is never reused.
- scrollIntoView under scroll-behavior:smooth measured mid-animation, so
  trusted clicks landed off-screen. Scroll instantly.
- extract text used body.textContent: script source filled the 20k cap
  before visible words, hiding "Thanks for applying" on Ashby. Use
  rendered text.
- Snapshots carry `required` (attribute or aria-required), since ATS
  forms mark it outside the label; fill on a file input now says to
  upload instead of throwing InvalidStateError.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 apps/web/public/install.sh                    |   5 +-
 .../browser-core/src/automate-cli.test.ts     |  46 ++++++
 packages/browser-core/src/automate-cli.ts     |  43 ++++-
 .../src/automation/action-script.ts           |   8 +-
 .../src/automation/extract-script.test.ts     |  10 ++
 .../src/automation/extract-script.ts          |  15 +-
 packages/browser-core/src/automation/page.ts  | 154 ++++++++++++++++++
 .../src/automation/snapshot-script.test.ts    |  38 +++++
 .../src/automation/snapshot-script.ts         |  36 +++-
 packages/sdk/src/mcp/automate.test.ts         |   3 +
 packages/sdk/src/mcp/mcp.test.ts              |  24 ++-
 packages/sdk/src/mcp/session.ts               |   3 +
 packages/sdk/src/mcp/tools.ts                 |  36 +++-
 packages/sdk/src/page.ts                      |  21 +++
 14 files changed, 423 insertions(+), 19 deletions(-)

diff --git a/apps/web/public/install.sh b/apps/web/public/install.sh
index 4eaf5b64..199e406a 100755
--- a/apps/web/public/install.sh
+++ b/apps/web/public/install.sh
@@ -87,6 +87,9 @@ Usage:
   tron snapshot         Structured, ref-tagged page snapshot (--json)
   tron click <ref>      Click a snapshot ref, e.g. @e3
   tron fill <ref> <val> Fill an input by ref, e.g. tron fill @e4 "hi@x.com"
+  tron upload <ref> <f> Attach file(s) to a file input, e.g. tron upload @e7 ~/cv.pdf
+  tron select <ref> <v> Pick an option by value or label (native or custom dropdowns)
+  tron press <key>      Trusted key press on the focused element (Enter, Tab, ArrowDown…)
   tron extract <mode>   Extract text|links|forms|tables|main (JSON)
   tron screenshot <p>   Save a PNG of the current page (--full-page)
   tron headless <url>   One-shot: --snapshot | --screenshot <p> | --extract <mode>
@@ -209,7 +212,7 @@ case "${1:-}" in
     SESSION="$(session_bin)"
     [ -x "$SESSION" ] || { echo "This TronBrowser build has no managed-session support (missing tron-session). Run: tron upgrade" >&2; exit 1; }
     exec "$SESSION" browser "$@" ;;
-  snapshot|click|fill|type|extract|screenshot|pdf|trace|replay)
+  snapshot|click|fill|type|upload|select|press|extract|screenshot|pdf|trace|replay)
     # CDP automation on the managed session's current page (PRD M3.2/M3.3/M3.7).
     run_automation "$@" ;;
   analyze)
diff --git a/packages/browser-core/src/automate-cli.test.ts b/packages/browser-core/src/automate-cli.test.ts
index 72cf28d2..c7a5d8aa 100644
--- a/packages/browser-core/src/automate-cli.test.ts
+++ b/packages/browser-core/src/automate-cli.test.ts
@@ -81,6 +81,52 @@ describe('automate-cli run', () => {
     expect(out.join('\n')).toContain('filled @e2');
   });
 
+  it('uploads files to a file input by object id', async () => {
+    const sent: Array<[string, unknown]> = [];
+    const c: CdpConnection = {
+      send: (async (method: string, params: unknown) => {
+        sent.push([method, params]);
+        if (method === 'Runtime.evaluate') return { result: { objectId: 'obj-1' } };
+        if (method === 'Runtime.callFunctionOn') return { result: { value: true } };
+        return {};
+      }) as CdpConnection['send'],
+      on: vi.fn(),
+      close: vi.fn(),
+    };
+    const { deps, out } = harness({ connect: async () => c });
+    const code = await run(['upload', '@e7', '/tmp/cv.pdf'], deps);
+    expect(code).toBe(EXIT.ok);
+    expect(sent).toContainEqual(['DOM.setFileInputFiles', { objectId: 'obj-1', files: ['/tmp/cv.pdf'] }]);
+    expect(out.join('\n')).toContain('uploaded 1 file(s) to @e7');
+  });
+
+  it('presses keys with trusted input events', async () => {
+    const sent: Array<[string, unknown]> = [];
+    const c: CdpConnection = {
+      send: (async (method: string, params: unknown) => { sent.push([method, params]); return {}; }) as CdpConnection['send'],
+      on: vi.fn(),
+      close: vi.fn(),
+    };
+    const { deps } = harness({ connect: async () => c });
+    expect(await run(['press', 'Enter'], deps)).toBe(EXIT.ok);
+    const keys = sent.filter(([m]) => m === 'Input.dispatchKeyEvent').map(([, p]) => (p as { type: string; key: string }).type + ':' + (p as { key: string }).key);
+    expect(keys).toEqual(['keyDown:Enter', 'keyUp:Enter']);
+  });
+
+  it('selects a native option by label', async () => {
+    const { deps, out } = harness({ connect: async () => conn({ ok: true, chosen: 'United States' }) });
+    expect(await run(['select', '@e3', 'united states'], deps)).toBe(EXIT.ok);
+    expect(out.join('\n')).toContain('selected "United States" in @e3');
+  });
+
+  it('prints usage for upload/select/press without arguments', async () => {
+    for (const cmd of ['upload', 'select', 'press']) {
+      const { deps, err } = harness();
+      expect(await run([cmd], deps)).toBe(EXIT.usage);
+      expect(err.join('\n')).toContain(`tron ${cmd}`);
+    }
+  });
+
   it('exits staleRef when a ref no longer resolves', async () => {
     const { deps, err } = harness({
       connect: async () => conn({ ok: false, error: 'STALE_REF', ref: '@e9' }),
diff --git a/packages/browser-core/src/automate-cli.ts b/packages/browser-core/src/automate-cli.ts
index 70816866..56013c1d 100644
--- a/packages/browser-core/src/automate-cli.ts
+++ b/packages/browser-core/src/automate-cli.ts
@@ -4,6 +4,7 @@
  *
  *   tron snapshot [--json] [--include-hidden]
  *   tron click <ref> | fill <ref> <value>
+ *   tron upload <ref> <file...> | select <ref> <value> | press <key>
  *   tron extract <text|links|forms|tables|main|selector> [--field n=sel[@attr]]
  *   tron screenshot <path> [--full-page] | tron pdf <path>
  *   tron headless <url> [--snapshot|--screenshot <path>|--pdf <path>|--extract <mode>] [--json]
@@ -16,7 +17,7 @@
 import { execFile } from 'node:child_process';
 import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { join, resolve as resolvePath } from 'node:path';
 import { promisify } from 'node:util';
 import { CdpClient, type CdpConnection } from './automation/cdp-client.js';
 import { cdpListUrl } from './automation/cdp.js';
@@ -39,7 +40,10 @@ import {
   fillRef,
   formatSnapshotText,
   goto,
+  pressKey,
+  selectRef,
   StaleRefError,
+  uploadRef,
 } from './automation/page.js';
 import { resolvePageWsUrl } from './automation/page-target.js';
 import type { CdpTarget, SessionDescriptor } from './automation/types.js';
@@ -209,6 +213,7 @@ async function runOp(deps: CliDeps, conn: CdpConnection, op: HeadlessOp): Promis
 
 const USAGE =
   'usage: tron snapshot [--json] | click <ref> | fill <ref> <value> | ' +
+  'upload <ref> <file...> | select <ref> <value> | press <key> | ' +
   'extract <text|links|forms|tables|main|selector> [--field n=sel] | ' +
   'screenshot <path> [--full-page] | pdf <path> | ' +
   'headless <url> [--snapshot|--screenshot <path>|--pdf <path>|--extract <mode>] [--json]';
@@ -260,6 +265,42 @@ export async function run(argv: string[], overrides: Partial<CliDeps> = {}): Pro
         deps.out(`filled ${filled.ref}`);
         return EXIT.ok;
       }
+      case 'upload': {
+        const [ref, ...files] = rest;
+        if (!ref || !files.length) {
+          deps.err('usage: tron upload <ref> <file> [file...]');
+          return EXIT.usage;
+        }
+        const paths = files.map((f) => resolvePath(f));
+        conn = await attach(deps);
+        const up = await uploadRef(conn, ref, paths);
+        await traceRecord(deps.env, conn, 'upload', { ref });
+        deps.out(`uploaded ${paths.length} file(s) to ${up.ref}`);
+        return EXIT.ok;
+      }
+      case 'select': {
+        const [ref, value] = rest;
+        if (!ref || value === undefined) {
+          deps.err('usage: tron select <ref> <value-or-label>');
+          return EXIT.usage;
+        }
+        conn = await attach(deps);
+        const sel = await selectRef(conn, ref, value);
+        await traceRecord(deps.env, conn, 'select', { ref, value });
+        deps.out(`selected ${JSON.stringify(sel.chosen ?? value)} in ${sel.ref}`);
+        return EXIT.ok;
+      }
+      case 'press': {
+        const key = rest[0];
+        if (!key) {
+          deps.err('usage: tron press <key>   (Enter, Tab, Escape, ArrowDown, one character…)');
+          return EXIT.usage;
+        }
+        conn = await attach(deps);
+        await pressKey(conn, key);
+        deps.out(`pressed ${key}`);
+        return EXIT.ok;
+      }
       case 'extract': {
         const target = rest.find((a) => !a.startsWith('--'));
         if (!target) {
diff --git a/packages/browser-core/src/automation/action-script.ts b/packages/browser-core/src/automation/action-script.ts
index 868137e6..a212bde6 100644
--- a/packages/browser-core/src/automation/action-script.ts
+++ b/packages/browser-core/src/automation/action-script.ts
@@ -30,7 +30,7 @@ function resolvePrelude(ref: string): string {
 export function clickExpression(ref: string): string {
   return `(() => {
   ${resolvePrelude(ref)}
-  el.scrollIntoView({ block: 'center', inline: 'center' });
+  el.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant' });
   el.click();
   return { ok: true, ref: ${JSON.stringify('@' + normalizeRef(ref))} };
 })()`;
@@ -41,13 +41,16 @@ export function fillExpression(ref: string, value: string): string {
   return `(() => {
   ${resolvePrelude(ref)}
   const value = ${JSON.stringify(value)};
-  el.scrollIntoView({ block: 'center', inline: 'center' });
+  el.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant' });
   if (el.isContentEditable) {
     el.focus();
     el.textContent = value;
     el.dispatchEvent(new Event('input', { bubbles: true }));
     return { ok: true, ref: ${JSON.stringify('@' + normalizeRef(ref))} };
   }
+  if (el instanceof HTMLInputElement && el.type === 'file') {
+    return { ok: false, error: 'NOT_FILLABLE', ref: ${JSON.stringify('@' + normalizeRef(ref))}, message: 'a file input takes files: use upload (browser_upload / tron upload)' };
+  }
   const proto = el instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
   const desc = Object.getOwnPropertyDescriptor(proto, 'value');
   el.focus();
@@ -63,4 +66,5 @@ export interface ActionResult {
   ok: boolean;
   ref: string;
   error?: string;
+  message?: string;
 }
diff --git a/packages/browser-core/src/automation/extract-script.test.ts b/packages/browser-core/src/automation/extract-script.test.ts
index 91b12042..d5789ac4 100644
--- a/packages/browser-core/src/automation/extract-script.test.ts
+++ b/packages/browser-core/src/automation/extract-script.test.ts
@@ -11,6 +11,16 @@ beforeEach(() => {
   document.body.innerHTML = '';
 });
 
+describe('text extraction', () => {
+  it('returns visible words, not <script>/<style> source that would eat the 20k cap', () => {
+    document.body.innerHTML = `<script>${'var bundle = 1;'.repeat(3000)}</script><style>.x{color:red}</style><main><h1>Thanks for applying</h1></main>`;
+    const { text } = run<{ text: string }>(extractExpression('text'));
+    expect(text).toContain('Thanks for applying');
+    expect(text).not.toContain('var bundle');
+    expect(text).not.toContain('color:red');
+  });
+});
+
 describe('parseFieldSpec', () => {
   it('parses name=selector', () => {
     expect(parseFieldSpec('title=.t')).toEqual({ name: 'title', selector: '.t' });
diff --git a/packages/browser-core/src/automation/extract-script.ts b/packages/browser-core/src/automation/extract-script.ts
index 1323a040..d07bc288 100644
--- a/packages/browser-core/src/automation/extract-script.ts
+++ b/packages/browser-core/src/automation/extract-script.ts
@@ -84,9 +84,20 @@ export function extractExpression(target: string, fields: FieldSpec[] = []): str
     return { headers, rows };
   });
 
+  // Rendered text, not textContent: textContent includes <script>/<style>
+  // source, and on script-heavy pages (Ashby inlines its bundle) the 20k cap
+  // was spent on code before any visible words, e.g. "Thanks for applying".
+  const visibleText = (root) => {
+    if (!root) return '';
+    if (typeof root.innerText === 'string' && root.isConnected && getComputedStyle(root).display !== 'none') return clean(root.innerText);
+    const copy = root.cloneNode(true);
+    for (const n of copy.querySelectorAll('script, style, noscript, template')) n.remove();
+    return clean(copy.textContent);
+  };
+
   const mainText = () => {
     const m = document.querySelector('main, article, [role=main]') || document.body;
-    return { text: clean(m.textContent).slice(0, 20000) };
+    return { text: visibleText(m).slice(0, 20000) };
   };
 
   const target = ${JSON.stringify(target)};
@@ -105,7 +116,7 @@ export function extractExpression(target: string, fields: FieldSpec[] = []): str
   }
 
   switch (target) {
-    case 'text': return { text: clean(document.body ? document.body.textContent : '').slice(0, 20000) };
+    case 'text': return { text: visibleText(document.body).slice(0, 20000) };
     case 'links': return links();
     case 'forms': return forms();
     case 'tables': return tables();
diff --git a/packages/browser-core/src/automation/page.ts b/packages/browser-core/src/automation/page.ts
index 9e5b11b5..a55b45ed 100644
--- a/packages/browser-core/src/automation/page.ts
+++ b/packages/browser-core/src/automation/page.ts
@@ -102,9 +102,162 @@ export async function fillRef(
 ): Promise<ActionResult> {
   const result = await evaluate<ActionResult>(conn, fillExpression(ref, value));
   if (!result.ok && result.error === 'STALE_REF') throw new StaleRefError(`@${normalizeRef(ref)}`);
+  if (!result.ok) throw new Error(`Cannot fill @${normalizeRef(ref)}: ${result.message ?? result.error ?? 'failed'}`);
   return result;
 }
 
+/** Resolve a ref to a remote object id (throws StaleRefError if gone). */
+async function refObjectId(conn: CdpConnection, ref: string): Promise<string> {
+  const bare = normalizeRef(ref);
+  const res = await conn.send<{ result?: { objectId?: string; subtype?: string } }>('Runtime.evaluate', {
+    expression: `document.querySelector('[data-tron-ref=' + ${JSON.stringify(JSON.stringify(bare))} + ']')`,
+    returnByValue: false,
+  });
+  const objectId = res.result?.subtype === 'null' ? undefined : res.result?.objectId;
+  if (!objectId) throw new StaleRefError(`@${bare}`);
+  return objectId;
+}
+
+/**
+ * Set the files of an `<input type=file>` by ref. Forms usually hide the real
+ * input behind an "Attach" button, which is why snapshots always list file
+ * inputs. `DOM.setFileInputFiles` fires input/change like a real pick.
+ */
+export async function uploadRef(conn: CdpConnection, ref: string, files: string[]): Promise<ActionResult> {
+  const objectId = await refObjectId(conn, ref);
+  const isFile = await conn.send<{ result?: { value?: boolean } }>('Runtime.callFunctionOn', {
+    objectId,
+    functionDeclaration: 'function () { return this instanceof HTMLInputElement && this.type === "file"; }',
+    returnByValue: true,
+  });
+  if (!isFile.result?.value) throw new Error(`Ref @${normalizeRef(ref)} is not a file input`);
+  await conn.send('DOM.setFileInputFiles', { objectId, files });
+  return { ok: true, ref: `@${normalizeRef(ref)}` };
+}
+
+const KEYS: Record<string, { key: string; code: string; keyCode: number; text?: string }> = {
+  Enter: { key: 'Enter', code: 'Enter', keyCode: 13, text: '\r' },
+  Tab: { key: 'Tab', code: 'Tab', keyCode: 9 },
+  Escape: { key: 'Escape', code: 'Escape', keyCode: 27 },
+  Backspace: { key: 'Backspace', code: 'Backspace', keyCode: 8 },
+  ArrowDown: { key: 'ArrowDown', code: 'ArrowDown', keyCode: 40 },
+  ArrowUp: { key: 'ArrowUp', code: 'ArrowUp', keyCode: 38 },
+  ArrowLeft: { key: 'ArrowLeft', code: 'ArrowLeft', keyCode: 37 },
+  ArrowRight: { key: 'ArrowRight', code: 'ArrowRight', keyCode: 39 },
+  Space: { key: ' ', code: 'Space', keyCode: 32, text: ' ' },
+};
+
+/** CDP key-event params for a key name (`Enter`, `ArrowDown`) or one character. */
+export function keyEventParams(key: string): { key: string; code: string; keyCode: number; text?: string } {
+  const known = KEYS[key];
+  if (known) return known;
+  if (key.length === 1) {
+    const upper = key.toUpperCase();
+    const code = /[A-Z]/.test(upper) ? `Key${upper}` : /[0-9]/.test(key) ? `Digit${key}` : '';
+    return { key, code, keyCode: upper.charCodeAt(0), text: key };
+  }
+  throw new Error(`Unknown key "${key}" (use Enter, Tab, Escape, Backspace, Space, Arrow*, or one character)`);
+}
+
+/**
+ * Press a key on the focused element with trusted input events. A synthetic
+ * `KeyboardEvent` is `isTrusted: false`, and comboboxes (react-select and
+ * friends) ignore it, so Enter to pick an option did nothing.
+ */
+export async function pressKey(conn: CdpConnection, key: string): Promise<void> {
+  const k = keyEventParams(key);
+  const base = { key: k.key, code: k.code, windowsVirtualKeyCode: k.keyCode, nativeVirtualKeyCode: k.keyCode };
+  await conn.send('Input.dispatchKeyEvent', { type: k.text ? 'keyDown' : 'rawKeyDown', ...base, ...(k.text ? { text: k.text } : {}) });
+  await conn.send('Input.dispatchKeyEvent', { type: 'keyUp', ...base });
+}
+
+/** A trusted left click at viewport coordinates (move, press, release). */
+export async function mouseClick(conn: CdpConnection, x: number, y: number): Promise<void> {
+  await conn.send('Input.dispatchMouseEvent', { type: 'mouseMoved', x, y });
+  await conn.send('Input.dispatchMouseEvent', { type: 'mousePressed', x, y, button: 'left', buttons: 1, clickCount: 1 });
+  await conn.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x, y, button: 'left', buttons: 0, clickCount: 1 });
+}
+
+const refQuery = (bare: string) => `document.querySelector('[data-tron-ref=' + ${JSON.stringify(JSON.stringify(bare))} + ']')`;
+
+/**
+ * Choose `value` in the control at `ref`. A native `<select>` matches an
+ * option's value or visible text. Anything else is treated as a custom
+ * combobox (ARIA listbox, react-select, ATS pickers): open it, type the value
+ * to filter when it is a text input, then click the visible `[role=option]`
+ * whose text matches.
+ */
+export async function selectRef(
+  conn: CdpConnection,
+  ref: string,
+  value: string,
+  options: { timeoutMs?: number } = {},
+): Promise<ActionResult & { chosen?: string | undefined }> {
+  const bare = normalizeRef(ref);
+  const want = JSON.stringify(value.trim().toLowerCase());
+  const native = await evaluate<{ ok: boolean; error?: string; chosen?: string; custom?: boolean }>(conn, `(() => {
+  const el = ${refQuery(bare)};
+  if (!el) return { ok: false, error: 'STALE_REF' };
+  if (el.tagName !== 'SELECT') return { ok: false, custom: true };
+  const want = ${want};
+  const t = (o) => o.text.trim().toLowerCase();
+  const opt = [...el.options].find((o) => o.value.toLowerCase() === want) || [...el.options].find((o) => t(o) === want) || [...el.options].find((o) => t(o).startsWith(want));
+  if (!opt) return { ok: false, error: 'NO_OPTION' };
+  el.value = opt.value;
+  el.dispatchEvent(new Event('input', { bubbles: true }));
+  el.dispatchEvent(new Event('change', { bubbles: true }));
+  return { ok: true, chosen: opt.text.trim() };
+})()`);
+  if (native.error === 'STALE_REF') throw new StaleRefError(`@${bare}`);
+  if (native.ok) return { ok: true, ref: `@${bare}`, chosen: native.chosen };
+  if (!native.custom) throw new Error(`No option matching "${value}" in @${bare}`);
+
+  // Custom widgets (react-select and friends) open on a real mousedown and
+  // filter on real key input; synthetic events leave the menu closed. So this
+  // path uses trusted CDP input throughout.
+  const box = await evaluate<{ x: number; y: number; typeable: boolean } | null>(conn, `(() => {
+  const el = ${refQuery(bare)};
+  if (!el) return null;
+  // 'instant': with scroll-behavior:smooth (Greenhouse sets it) the default
+  // animates, the rect is read mid-scroll, and the click lands off-screen.
+  el.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant' });
+  const r = el.getBoundingClientRect();
+  const typeable = el.tagName === 'INPUT' && !['checkbox', 'radio', 'button', 'submit'].includes(el.type);
+  return { x: r.left + Math.max(1, Math.min(r.width / 2, 12)), y: r.top + r.height / 2, typeable };
+})()`);
+  if (!box) throw new StaleRefError(`@${bare}`);
+  if (box.y < 0 || box.x < 0) throw new Error(`@${bare} is outside the viewport; cannot open it`);
+  await mouseClick(conn, box.x, box.y);
+  if (box.typeable) {
+    await evaluate(conn, `(() => { const el = ${refQuery(bare)}; if (el) { el.focus(); el.select && el.select(); } })()`);
+    await conn.send('Input.insertText', { text: value });
+  }
+  const find = `(() => {
+  const want = ${want};
+  const text = (o) => (o.textContent || '').replace(/\\s+/g, ' ').trim();
+  const opts = [...document.querySelectorAll('[role=option], [role=menuitemradio]')].filter((o) => { const r = o.getBoundingClientRect(); return r.width > 0 && r.height > 0; });
+  const hit = opts.find((o) => text(o).toLowerCase() === want) || opts.find((o) => text(o).toLowerCase().startsWith(want)) || opts.find((o) => text(o).toLowerCase().includes(want));
+  if (!hit) return { ok: false, seen: opts.slice(0, 12).map(text) };
+  hit.scrollIntoView({ block: 'nearest', behavior: 'instant' });
+  const r = hit.getBoundingClientRect();
+  return { ok: true, chosen: text(hit), x: r.left + r.width / 2, y: r.top + r.height / 2 };
+})()`;
+  const deadline = Date.now() + (options.timeoutMs ?? 5000);
+  let last: { ok: boolean; chosen?: string; seen?: string[]; x?: number; y?: number } = { ok: false };
+  for (;;) {
+    last = await evaluate(conn, find);
+    if (last.ok && last.x !== undefined && last.y !== undefined) {
+      await mouseClick(conn, last.x, last.y);
+      return { ok: true, ref: `@${bare}`, chosen: last.chosen };
+    }
+    if (Date.now() > deadline) break;
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  throw new Error(
+    `No option matching "${value}" appeared for @${bare}` + (last.seen?.length ? ` (saw: ${last.seen.join(' | ')})` : ''),
+  );
+}
+
 /** Render a snapshot as compact text (the default `tron snapshot` output). */
 export function formatSnapshotText(snapshot: AgentSnapshot): string {
   const lines: string[] = [
@@ -121,6 +274,7 @@ export function formatSnapshotText(snapshot: AgentSnapshot): string {
 
 function formatElementLine(el: SnapshotElement): string {
   let line = `${el.ref} ${el.role} ${JSON.stringify(el.name)}`;
+  if (el.required) line += ' [required]';
   if (el.value !== undefined && el.value !== '') line += ` = ${JSON.stringify(el.value)}`;
   if (el.href) line += ` -> ${el.href}`;
   return line;
diff --git a/packages/browser-core/src/automation/snapshot-script.test.ts b/packages/browser-core/src/automation/snapshot-script.test.ts
index dbfde35a..05d27737 100644
--- a/packages/browser-core/src/automation/snapshot-script.test.ts
+++ b/packages/browser-core/src/automation/snapshot-script.test.ts
@@ -14,11 +14,49 @@ function run<T>(expr: string): T {
 beforeEach(() => {
   document.head.innerHTML = '';
   document.body.innerHTML = '';
+  // A real navigation gets a fresh window; the ref sequence lives on it.
+  delete (window as unknown as { __tronRefSeq?: number }).__tronRefSeq;
   Element.prototype.getBoundingClientRect = function () {
     return { width: 120, height: 20, top: 0, left: 0, right: 120, bottom: 20, x: 0, y: 0, toJSON() {} };
   } as typeof Element.prototype.getBoundingClientRect;
 });
 
+describe('snapshotExpression refs across snapshots', () => {
+  it('keeps an element\'s ref when new elements appear before it (an opened dropdown)', () => {
+    document.body.innerHTML = `<input aria-label="Sponsorship" role="combobox" /><div id="menu"></div><input aria-label="LinkedIn" />`;
+    const first = run<AgentSnapshot>(snapshotExpression());
+    const linkedIn = first.elements.find((e) => e.name === 'LinkedIn')!.ref;
+    document.getElementById('menu')!.innerHTML = '<div role="option">Yes</div><div role="option">No</div>';
+    const second = run<AgentSnapshot>(snapshotExpression());
+    expect(second.elements.find((e) => e.name === 'LinkedIn')!.ref).toBe(linkedIn);
+    expect(second.elements.filter((e) => e.role === 'option').map((e) => e.ref)).toEqual(['@e3', '@e4']);
+  });
+  it('never hands a vanished element\'s ref to a new one', () => {
+    document.body.innerHTML = `<button>One</button><button>Two</button>`;
+    run<AgentSnapshot>(snapshotExpression());
+    document.body.innerHTML = `<button>Three</button>`;
+    const snap = run<AgentSnapshot>(snapshotExpression());
+    expect(snap.elements.map((e) => e.ref)).toEqual(['@e3']);
+    expect(run<ActionResult>(clickExpression('@e1')).error).toBe('STALE_REF');
+  });
+  it('flags required fields from the attribute or aria-required', () => {
+    document.body.innerHTML = `<input aria-label="Why us?" required /><div role="combobox" aria-label="Visa" aria-required="true" tabindex="0"></div><input aria-label="Nickname" />`;
+    const snap = run<AgentSnapshot>(snapshotExpression());
+    expect(snap.elements.map((e) => [e.name, e.required ?? false])).toEqual([['Why us?', true], ['Visa', true], ['Nickname', false]]);
+  });
+  it('refuses to fill a file input and says to upload instead', () => {
+    document.body.innerHTML = `<input type="file" aria-label="Resume" />`;
+    run<AgentSnapshot>(snapshotExpression());
+    expect(run<ActionResult>(fillExpression('@e1', 'x'))).toMatchObject({ ok: false, error: 'NOT_FILLABLE' });
+  });
+  it('lists a visually hidden file input as role "file"', () => {
+    document.body.innerHTML = `<button>Attach</button><label for="resume">Resume</label><input id="resume" type="file" style="display:none" />`;
+    const snap = run<AgentSnapshot>(snapshotExpression());
+    const file = snap.elements.find((e) => e.role === 'file');
+    expect(file).toMatchObject({ name: 'Resume', visible: false, tag: 'input' });
+  });
+});
+
 describe('snapshotExpression', () => {
   it('tags interactive + heading elements with refs in document order', () => {
     document.body.innerHTML = `
diff --git a/packages/browser-core/src/automation/snapshot-script.ts b/packages/browser-core/src/automation/snapshot-script.ts
index 17a174e9..0e03c98f 100644
--- a/packages/browser-core/src/automation/snapshot-script.ts
+++ b/packages/browser-core/src/automation/snapshot-script.ts
@@ -21,6 +21,8 @@ export interface SnapshotElement {
   visible: boolean;
   value?: string;
   href?: string;
+  /** `required` attribute or aria-required=true (ATS forms often mark it outside the label). */
+  required?: boolean;
 }
 
 export interface AgentSnapshot {
@@ -46,11 +48,21 @@ export function snapshotExpression(options: SnapshotOptions = {}): string {
   const includeHidden = ${includeHidden ? 'true' : 'false'};
   const INTERACTIVE = 'a[href], button, input:not([type=hidden]), select, textarea, ' +
     '[role=button], [role=link], [role=checkbox], [role=radio], [role=tab], ' +
-    '[role=menuitem], [role=switch], [role=textbox], [contenteditable=""], ' +
+    '[role=menuitem], [role=switch], [role=textbox], [role=combobox], [role=option], ' +
+    '[role=menuitemradio], [contenteditable=""], ' +
     '[contenteditable=true], summary, [tabindex]:not([tabindex="-1"])';
   const HEADING = 'h1, h2, h3, h4, h5, h6, [role=heading]';
 
-  for (const el of document.querySelectorAll('[' + ATTR + ']')) el.removeAttribute(ATTR);
+  // Refs are stable: an element keeps the ref an earlier snapshot gave it, and
+  // only new elements get new numbers. Renumbering on every snapshot shifted
+  // every ref after an opened dropdown, so an agent's next fill hit the wrong field.
+  const previous = [...document.querySelectorAll('[' + ATTR + ']')];
+  let seq = 0;
+  for (const el of previous) {
+    const m = /^e([0-9]+)$/.exec(el.getAttribute(ATTR) || '');
+    if (m) seq = Math.max(seq, Number(m[1]));
+  }
+  seq = Math.max(seq, Number(window.__tronRefSeq || 0));
 
   const isVisible = (el) => {
     if (el.hasAttribute('hidden')) return false;
@@ -76,6 +88,7 @@ export function snapshotExpression(options: SnapshotOptions = {}): string {
       if (t === 'radio') return 'radio';
       if (t === 'button' || t === 'submit' || t === 'reset') return 'button';
       if (t === 'range') return 'slider';
+      if (t === 'file') return 'file';
       return 'textbox';
     }
     return 'generic';
@@ -143,7 +156,10 @@ export function snapshotExpression(options: SnapshotOptions = {}): string {
       if (seen.has(el)) continue;
       seen.add(el);
       const visible = isVisible(el);
-      if (!visible && !includeHidden) continue;
+      // File inputs are nearly always visually hidden behind an "Attach"
+      // button, yet they are the only thing an upload can target.
+      const isFile = el.tagName === 'INPUT' && (el.getAttribute('type') || '').toLowerCase() === 'file';
+      if (!visible && !includeHidden && !isFile) continue;
       nodes.push({ el, interactive, visible });
     }
   };
@@ -158,10 +174,17 @@ export function snapshotExpression(options: SnapshotOptions = {}): string {
     return 0;
   });
 
+  // Keep a surfaced element's ref (unless a cloned node copied it); untag
+  // elements that dropped out so their old ref reads as STALE_REF.
+  const surfaced = new Set(nodes.map((n) => n.el));
+  for (const el of previous) if (!surfaced.has(el)) el.removeAttribute(ATTR);
+  const used = new Set();
   const active = document.activeElement;
   let focusedRef;
-  const elements = nodes.map((n, i) => {
-    const ref = 'e' + (i + 1);
+  const elements = nodes.map((n) => {
+    let ref = n.el.getAttribute(ATTR);
+    if (!ref || !/^e[0-9]+$/.test(ref) || used.has(ref)) ref = 'e' + (++seq);
+    used.add(ref);
     n.el.setAttribute(ATTR, ref);
     if (n.el === active) focusedRef = '@' + ref;
     const out = {
@@ -175,9 +198,12 @@ export function snapshotExpression(options: SnapshotOptions = {}): string {
     const v = valueOf(n.el);
     if (v !== undefined) out.value = v;
     if (n.el.tagName.toLowerCase() === 'a' && n.el.href) out.href = n.el.href;
+    if (n.el.required === true || n.el.getAttribute('aria-required') === 'true') out.required = true;
     return out;
   });
 
+  window.__tronRefSeq = seq;
+
   return {
     url: location.href,
     title: document.title,
diff --git a/packages/sdk/src/mcp/automate.test.ts b/packages/sdk/src/mcp/automate.test.ts
index c9f4a754..1723a4a1 100644
--- a/packages/sdk/src/mcp/automate.test.ts
+++ b/packages/sdk/src/mcp/automate.test.ts
@@ -17,6 +17,9 @@ function fakePage(answers: { markdown?: string; text?: string; links?: unknown;
     snapshot: async () => SNAP,
     click: async () => {},
     fill: async () => {},
+    upload: async () => {},
+    select: async () => undefined,
+    press: async () => {},
     extract: async (m) => { calls.push('extract:' + m); return m === 'links' ? (answers.links ?? []) : { text: answers.text ?? 'chromium text ' + LONG }; },
     screenshot: async () => Buffer.from('PNG'),
     eval: (async (code: string) => {
diff --git a/packages/sdk/src/mcp/mcp.test.ts b/packages/sdk/src/mcp/mcp.test.ts
index 3bc8c6a0..ade198cf 100644
--- a/packages/sdk/src/mcp/mcp.test.ts
+++ b/packages/sdk/src/mcp/mcp.test.ts
@@ -18,6 +18,9 @@ function fakePage() {
     snapshot: async () => SNAP,
     click: async (r) => { calls.push('click:' + r); },
     fill: async (r, v) => { calls.push('fill:' + r + '=' + v); },
+    upload: async (r, f) => { calls.push('upload:' + r + '=' + f.join(',')); },
+    select: async (r, v) => { calls.push('select:' + r + '=' + v); return 'Yes'; },
+    press: async (k) => { calls.push('press:' + k); },
     extract: async (m) => ({ mode: m }),
     screenshot: async () => Buffer.from('PNG'),
     eval: async () => { calls.push('eval'); return null as never; },
@@ -52,7 +55,7 @@ describe('MCP protocol', () => {
     const r = await server.handle({ jsonrpc: '2.0', id: 2, method: 'tools/list' });
     const names = (r!.result as { tools: Array<{ name: string }> }).tools.map((t) => t.name);
     expect(names).toEqual(expect.arrayContaining([
-      'browser_open', 'browser_snapshot', 'browser_click', 'browser_fill', 'browser_extract',
+      'browser_open', 'browser_snapshot', 'browser_click', 'browser_fill', 'browser_select', 'browser_upload', 'browser_press', 'browser_extract',
       'browser_screenshot', 'browser_tabs', 'browser_close', 'browser_analyze', 'browser_step', 'browser_run_task',
     ]));
   });
@@ -80,6 +83,25 @@ describe('MCP tools', () => {
     expect(calls).toContain('click:@e1');
     expect(calls).toContain('fill:@e2=hi');
   });
+  it('browser_select / browser_press go through the page, not synthetic events', async () => {
+    const { call, calls } = harness();
+    const r = await call('browser_select', { ref: '@e3', value: 'yes' });
+    await call('browser_press', { key: 'Enter' });
+    expect(calls).toEqual(['select:@e3=yes', 'press:Enter']);
+    expect((r!.result as { content: Array<{ text: string }> }).content[0].text).toBe('Selected "Yes".');
+  });
+  it('browser_upload attaches existing absolute paths only', async () => {
+    const { call, calls } = harness();
+    const file = new URL(import.meta.url).pathname;
+    const ok = await call('browser_upload', { ref: '@e4', paths: [file] });
+    expect(calls).toContain('upload:@e4=' + file);
+    expect((ok!.result as { content: Array<{ text: string }> }).content[0].text).toMatch(/^Attached mcp\.test\.ts/);
+    const rel = await call('browser_upload', { ref: '@e4', path: 'resume.pdf' });
+    expect((rel!.result as { isError?: boolean }).isError).toBe(true);
+    const missing = await call('browser_upload', { ref: '@e4', path: '/nope/resume.pdf' });
+    expect((missing!.result as { isError?: boolean }).isError).toBe(true);
+    expect(calls.filter((c) => c.startsWith('upload:'))).toHaveLength(1);
+  });
   it('browser_screenshot returns image content', async () => {
     const { call } = harness();
     const r = await call('browser_screenshot');
diff --git a/packages/sdk/src/mcp/session.ts b/packages/sdk/src/mcp/session.ts
index 7f98301c..1fd24fc5 100644
--- a/packages/sdk/src/mcp/session.ts
+++ b/packages/sdk/src/mcp/session.ts
@@ -13,6 +13,9 @@ export interface McpPage {
   snapshot(): Promise<AgentSnapshot>;
   click(ref: string): Promise<void>;
   fill(ref: string, value: string): Promise<void>;
+  upload(ref: string, files: string[]): Promise<void>;
+  select(ref: string, value: string): Promise<string | undefined>;
+  press(key: string): Promise<void>;
   extract(target: string): Promise<unknown>;
   screenshot(): Promise<Uint8Array>;
   eval<T = unknown>(code: string): Promise<T>;
diff --git a/packages/sdk/src/mcp/tools.ts b/packages/sdk/src/mcp/tools.ts
index 43c36dd8..450ab193 100644
--- a/packages/sdk/src/mcp/tools.ts
+++ b/packages/sdk/src/mcp/tools.ts
@@ -3,6 +3,8 @@
  * browser_analyze / browser_step / browser_run_task. Mutating tools return a
  * fresh snapshot (PRD §10). All action on the managed session's current page.
  */
+import { existsSync } from 'node:fs';
+import { basename, isAbsolute } from 'node:path';
 import { formatSnapshotText, type AgentSnapshot } from '@tronbrowser/browser-core';
 import type { McpContent, McpTool } from './protocol.js';
 import type { McpBrowserSession, McpPage } from './session.js';
@@ -76,21 +78,41 @@ export function browserTools(session: McpBrowserSession): McpTool[] {
       inputSchema: obj({ key: { type: 'string' } }, ['key']),
       handler: async (a) => {
         const p = await page();
-        const key = JSON.stringify(str(a.key));
-        await p.eval(`(() => { const el = document.activeElement || document.body; for (const t of ['keydown','keyup']) el.dispatchEvent(new KeyboardEvent(t, { key: ${key}, bubbles: true, cancelable: true })); })()`);
+        await p.press(str(a.key));
         return freshSnapshot(p);
       },
     },
     {
       name: 'browser_select',
-      description: 'Select an option by value in a <select> referenced by ref.',
+      description:
+        'Choose an option by value or visible text. Works on a native <select> and on custom ' +
+        'comboboxes/listboxes (opens it, filters, clicks the matching option).',
       inputSchema: obj({ ref: { type: 'string' }, value: { type: 'string' } }, ['ref', 'value']),
       handler: async (a) => {
         const p = await page();
-        const ref = JSON.stringify(str(a.ref).replace(/^@/, ''));
-        const value = JSON.stringify(str(a.value));
-        await p.eval(`(() => { const el = document.querySelector('[data-tron-ref=' + ${JSON.stringify(ref)} + ']'); if (el) { el.value = ${value}; el.dispatchEvent(new Event('change', { bubbles: true })); } })()`);
-        return freshSnapshot(p);
+        const chosen = await p.select(str(a.ref), str(a.value));
+        return [{ type: 'text', text: `Selected ${JSON.stringify(chosen ?? str(a.value))}.` }, ...(await freshSnapshot(p))];
+      },
+    },
+    {
+      name: 'browser_upload',
+      description:
+        'Attach local files (absolute paths) to a file input by ref. Snapshots list file inputs ' +
+        '(role "file") even when a styled "Attach" button hides them.',
+      inputSchema: obj(
+        { ref: { type: 'string' }, paths: { type: 'array', items: { type: 'string' } }, path: { type: 'string' } },
+        ['ref'],
+      ),
+      handler: async (a) => {
+        const paths = Array.isArray(a.paths) ? a.paths.map((v) => str(v)) : a.path !== undefined ? [str(a.path)] : [];
+        if (!paths.length) throw new Error('browser_upload needs `paths` (or `path`)');
+        for (const f of paths) {
+          if (!isAbsolute(f)) throw new Error(`Upload path must be absolute: ${f}`);
+          if (!existsSync(f)) throw new Error(`No such file: ${f}`);
+        }
+        const p = await page();
+        await p.upload(str(a.ref), paths);
+        return [{ type: 'text', text: `Attached ${paths.map((f) => basename(f)).join(', ')}.` }, ...(await freshSnapshot(p))];
       },
     },
     {
diff --git a/packages/sdk/src/page.ts b/packages/sdk/src/page.ts
index 64f87b2d..cbbcc4de 100644
--- a/packages/sdk/src/page.ts
+++ b/packages/sdk/src/page.ts
@@ -12,8 +12,11 @@ import {
   fillRef,
   formatSnapshotText,
   goto,
+  pressKey,
   printPdf,
   screenshotPng,
+  selectRef,
+  uploadRef,
   type AgentSnapshot,
   type CdpConnection,
   type FieldSpec,
@@ -89,6 +92,24 @@ export class Page {
     await fillRef(this.#conn, ref, value);
   }
 
+  /** Attach local files to an `<input type=file>` by ref (paths are not traced). */
+  async upload(ref: string, files: string | string[]): Promise<void> {
+    this.#tracer?.record('upload', ref);
+    await uploadRef(this.#conn, ref, Array.isArray(files) ? files : [files]);
+  }
+
+  /** Choose an option by value or visible text in a native or custom select; returns the chosen label. */
+  async select(ref: string, value: string): Promise<string | undefined> {
+    this.#tracer?.record('select', ref);
+    return (await selectRef(this.#conn, ref, value)).chosen;
+  }
+
+  /** Press a key on the focused element with trusted input (Enter, Tab, ArrowDown, one character…). */
+  async press(key: string): Promise<void> {
+    this.#tracer?.record('press', key);
+    await pressKey(this.#conn, key);
+  }
+
   /** Alias of fill for MVP (character-level typing lands with richer input in M3.5+). */
   type(ref: string, value: string): Promise<void> {
     return this.fill(ref, value);