jev-cdp 0.1.4 → 0.1.6

package/dist/cli.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "jev-cdp",
-  version: "0.1.4",
+  version: "0.1.6",
   description: "A small Jev-powered bridge to Chrome through the Chrome DevTools Protocol.",
   type: "module",
   license: "MIT",
@@ -38,9 +38,9 @@ var package_default = {
 
 // src/browser.ts
 import { createHash } from "crypto";
-import { mkdir, mkdtemp, rm } from "fs/promises";
-import { tmpdir } from "os";
-import { dirname, join, resolve } from "path";
+import { mkdir, mkdtemp as mkdtemp2, rm as rm2 } from "fs/promises";
+import { tmpdir as tmpdir2 } from "os";
+import { dirname, join as join2, resolve } from "path";
 
 // src/cdp.ts
 async function listChromeTargets(cdpUrl) {
@@ -143,6 +143,88 @@ class CdpClient {
   }
 }
 
+// src/ffmpeg.ts
+import { mkdtemp, rm } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+function selectFrameSyncOption(help) {
+  if (/^\s*-fps_mode(?:\[:<stream_spec>\])?\s/m.test(help))
+    return "-fps_mode";
+  if (/^\s*-vsync\s/m.test(help))
+    return "-vsync";
+  throw new Error("FFmpeg supports neither -fps_mode nor -vsync");
+}
+async function run(command) {
+  const process2 = Bun.spawn(command, { stdout: "ignore", stderr: "pipe" });
+  const stderr = await new Response(process2.stderr).text();
+  return { code: await process2.exited, stderr };
+}
+async function recordingEncoder(ffmpeg = Bun.which("ffmpeg")) {
+  if (!ffmpeg)
+    throw new Error("FFmpeg not found on PATH");
+  const process2 = Bun.spawn([ffmpeg, "-hide_banner", "-h", "full"], { stdout: "pipe", stderr: "pipe" });
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(process2.stdout).text(),
+    new Response(process2.stderr).text(),
+    process2.exited
+  ]);
+  if (code !== 0)
+    throw new Error(`Could not inspect FFmpeg options: ${stderr.slice(-500)}`);
+  return { path: ffmpeg, sync: selectFrameSyncOption(stdout + stderr) };
+}
+function recordingCommand(encoder, manifest, output) {
+  return [
+    encoder.path,
+    "-y",
+    "-f",
+    "concat",
+    "-safe",
+    "0",
+    "-i",
+    manifest,
+    encoder.sync,
+    "vfr",
+    "-c:v",
+    "libx264",
+    "-pix_fmt",
+    "yuv420p",
+    "-movflags",
+    "+faststart",
+    output
+  ];
+}
+async function renderRecording(encoder, manifest, output) {
+  const result = await run(recordingCommand(encoder, manifest, output));
+  if (result.code !== 0)
+    throw new Error(`Could not render recording: ${result.stderr.slice(-800)}`);
+}
+async function checkRecordingEncoder() {
+  const encoder = await recordingEncoder();
+  const directory = await mkdtemp(join(tmpdir(), "jev-cdp-ffmpeg-check-"));
+  try {
+    const frame = join(directory, "frame.ppm");
+    const manifest = join(directory, "frames.ffconcat");
+    const output = join(directory, "check.mp4");
+    await Bun.write(frame, Buffer.concat([Buffer.from(`P6
+16 16
+255
+`), Buffer.alloc(16 * 16 * 3, 90)]));
+    const quoted = frame.replaceAll("'", "'\\''");
+    await Bun.write(manifest, `ffconcat version 1.0
+file '${quoted}'
+duration 0.12
+file '${quoted}'
+`);
+    await renderRecording(encoder, manifest, output);
+    const decoded = await run([encoder.path, "-v", "error", "-i", output, "-f", "null", "-"]);
+    if (decoded.code !== 0)
+      throw new Error(`Could not decode recording: ${decoded.stderr.slice(-500)}`);
+    return `FFmpeg at ${encoder.path}; ${encoder.sync} vfr and libx264 encode/decode passed`;
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
 // src/snapshot.js
 var snapshot_default = `// Ported from browser-use/jev-ultrafast at commit 452c1ad2 under the MIT License.
 (() => {
@@ -207,8 +289,15 @@ var snapshot_default = `// Ported from browser-use/jev-ultrafast at commit 452c1
     const r=e.getBoundingClientRect(), x=r.x+r.width/2, y=r.y+r.height/2, rname=role(e);
     if (!rname || r.width<=0 || r.height<=0 || x<0 || y<0 || x>=innerWidth || y>=innerHeight) continue;
     if (rname==='gridcell' && e.querySelector('button,[role="button"]')) continue;
+    const hit=document.elementFromPoint(x,y);
+    const coveredBy=hit && !e.contains(hit) && !hit.contains(e) ?
+      {tag:hit.tagName.toLowerCase(),text:(hit.innerText||hit.getAttribute('aria-label')||'').trim().slice(0,160),role:hit.getAttribute('role')} : null;
+    const region=e.closest('form,dialog,[role="dialog"],article,section,li,tr,[role="row"],main,nav,header,footer');
+    const nearbyText=(region?.innerText||e.parentElement?.innerText||'').trim().replace(/\\s+/g,' ').slice(0,240);
     const base={node:identity(e),role:rname,label:name(e)||rname,...(sensitive(e)?{sensitive:true}:{}),
-      rect:{x:r.x,y:r.y,w:r.width,h:r.height}};
+      rect:{x:r.x,y:r.y,w:r.width,h:r.height},frameUrl:location.href,
+      nearbyText,region:region?.getAttribute('aria-label')||region?.getAttribute('role')||region?.tagName.toLowerCase()||'',
+      clickable:!coveredBy,coveredBy};
     for (const key of ['checked','selected','expanded','pressed']) {
       const value=e.getAttribute('aria-'+key);
       if (value!==null) base[key]=value;
@@ -228,14 +317,20 @@ var snapshot_default = `// Ported from browser-use/jev-ultrafast at commit 452c1
       if (editable) actions.push({...base,kind:'click',value,label:'Open '+base.label});
     }
   }
-  const words=[], walker=document.createTreeWalker(document.body,NodeFilter.SHOW_TEXT);
-  const range=document.createRange(); let node,length=0;
-  while ((node=walker.nextNode()) && length<6000) {
-    const value=node.textContent.trim(), parent=node.parentElement;
-    if (!value || !parent || parent.closest('script,style,noscript,template') || !visible(parent)) continue;
-    range.selectNodeContents(node); const r=range.getBoundingClientRect();
-    if (r.width>0 && r.height>0 && r.bottom>0 && r.top<innerHeight && r.right>0 && r.left<innerWidth) {
-      words.push(value); length+=value.length;
+  const roots=[document.body], shadowRoots=[];
+  for (const root of roots) for (const e of root.querySelectorAll('*')) {
+    if (e.shadowRoot) { roots.push(e.shadowRoot); shadowRoots.push(e.shadowRoot); }
+  }
+  const words=[], range=document.createRange(); let length=0;
+  for (const root of [...shadowRoots,document.body]) {
+    const walker=document.createTreeWalker(root,NodeFilter.SHOW_TEXT); let node;
+    while ((node=walker.nextNode()) && length<6000) {
+      const value=node.textContent.trim(), parent=node.parentElement;
+      if (!value || !parent || parent.closest('script,style,noscript,template') || !visible(parent)) continue;
+      range.selectNodeContents(node); const r=range.getBoundingClientRect();
+      if (r.width>0 && r.height>0 && r.bottom>0 && r.top<innerHeight && r.right>0 && r.left<innerWidth) {
+        words.push(value); length+=value.length;
+      }
     }
   }
   const text=words.join('\\n').slice(0,6000), height=document.documentElement.scrollHeight;
@@ -249,7 +344,6 @@ var snapshot_default = `// Ported from browser-use/jev-ultrafast at commit 452c1
   actions.forEach((a,i)=>a.id='e'+(i+1));
   if (scrollY+innerHeight<height-2) actions.push({id:'scroll_down',kind:'scroll',label:'Scroll down',delta:560});
   if (scrollY>0) actions.push({id:'scroll_up',kind:'scroll',label:'Scroll up',delta:-560});
-  actions.push({id:'wait',kind:'wait',label:'Wait for the page to update'});
   return {url:location.href,title:document.title,w:innerWidth,h:innerHeight,text,
     scroll:{y:scrollY,height},actions,marker,page_key,guards,omitted_actions};
 })()
@@ -278,6 +372,18 @@ var RECORDING_CURSOR_INIT = `(() => {
 
 class StalePageError extends Error {
 }
+
+class WaitTimeoutError extends Error {
+  elapsedMs;
+  pendingCondition;
+  state;
+  constructor(elapsedMs, pendingCondition, state) {
+    super(`Wait timed out after ${elapsedMs}ms: ${pendingCondition}`);
+    this.elapsedMs = elapsedMs;
+    this.pendingCondition = pendingCondition;
+    this.state = state;
+  }
+}
 function stableValue(value) {
   if (Array.isArray(value))
     return value.map(stableValue);
@@ -323,6 +429,17 @@ class Browser {
   #openedTabs = [];
   #cdpUrl;
   #switchOnPopup = false;
+  #loadingFrames = new Set;
+  #waitBudgetMs;
+  #waitSpentMs = 0;
+  #transitions = [];
+  #origin = null;
+  #changeListeners = new Set;
+  #targetUrls = new Map;
+  #newTargets = new Set;
+  #popupListeners = new Set;
+  #consoleErrors = [];
+  #watchedConsoleSessions = new Set;
   constructor(cdp, sessionId, targetId, ownsTarget, browserContextId, options) {
     this.#cdp = cdp;
     this.#cdpUrl = options.cdpUrl;
@@ -333,6 +450,7 @@ class Browser {
     this.#keepOpen = options.keepOpen ?? false;
     this.#screenshots = options.screenshots ?? false;
     this.#interactionPauses = options.interactionPauses ?? 0;
+    this.#waitBudgetMs = options.waitBudgetMs ?? 15000;
     this.#recordingPath = options.recordingPath ? resolve(options.recordingPath) : undefined;
     this.#screenshotPath = options.screenshotPath ? resolve(options.screenshotPath) : undefined;
   }
@@ -385,10 +503,30 @@ class Browser {
     const browser = new Browser(cdp, attached.sessionId, targetId, ownsTarget, browserContextId, options);
     browser.#knownTargets = new Set((await listChromeTargets(options.cdpUrl)).map((target) => target.id));
     try {
+      const recordTargetUrl = (params) => {
+        const info = params.targetInfo;
+        if (info?.type === "page" && info.targetId && !browser.#knownTargets.has(info.targetId)) {
+          browser.#newTargets.add(info.targetId);
+          for (const listener of browser.#popupListeners)
+            listener();
+        }
+        if (!info?.targetId || !info.url || info.url === "about:blank")
+          return;
+        const urls = browser.#targetUrls.get(info.targetId) ?? [];
+        if (urls.at(-1) !== info.url)
+          urls.push(info.url);
+        browser.#targetUrls.set(info.targetId, urls);
+      };
+      browser.#stopPageEvents.push(cdp.on("Target.targetCreated", "", recordTargetUrl), cdp.on("Target.targetInfoChanged", "", recordTargetUrl));
+      await cdp.command("Target.setDiscoverTargets", { discover: true });
       browser.#stopPageEvents.push(cdp.on("Target.attachedToTarget", browser.#sessionId, (params) => {
         const info = params.targetInfo;
-        if (info?.type === "iframe" && info.targetId && typeof params.sessionId === "string")
+        if (info?.type === "iframe" && info.targetId && typeof params.sessionId === "string") {
           browser.#frameSessions.set(info.targetId, params.sessionId);
+          browser.watchConsole(params.sessionId, info.targetId).catch(() => {
+            return;
+          });
+        }
       }));
       browser.#stopPageEvents.push(cdp.on("Page.frameNavigated", browser.#sessionId, (params) => {
         const frame = params.frame;
@@ -396,6 +534,7 @@ class Browser {
           browser.#frameContexts.delete(frame.id);
       }));
       await browser.call("Target.setAutoAttach", { autoAttach: true, waitForDebuggerOnStart: false, flatten: true });
+      await browser.watchConsole();
       await browser.call("Page.enable");
       await browser.call("Emulation.setDeviceMetricsOverride", {
         width: 1120,
@@ -412,7 +551,9 @@ class Browser {
       await browser.startRecording();
       return browser;
     } catch (error) {
-      await browser.close();
+      await browser.close().catch(() => {
+        return;
+      });
       throw error;
     }
   }
@@ -422,13 +563,65 @@ class Browser {
   get targetId() {
     return this.#targetId;
   }
-  async watchPageLoads() {
-    if (!this.#interactionPauses)
+  takeConsoleErrors() {
+    return this.#consoleErrors.splice(0);
+  }
+  pendingConsoleErrors() {
+    return [...this.#consoleErrors];
+  }
+  async watchConsole(sessionId = this.#sessionId, targetId = this.#targetId) {
+    if (this.#watchedConsoleSessions.has(sessionId))
       return;
+    this.#watchedConsoleSessions.add(sessionId);
+    const record = (source, message, url, timestamp) => {
+      if (!message.trim())
+        return;
+      this.#consoleErrors.push({
+        source,
+        message: message.slice(0, 4000),
+        ...url ? { url } : {},
+        ...timestamp !== undefined ? { timestamp } : {},
+        targetId
+      });
+    };
+    this.#stopPageEvents.push(this.#cdp.on("Runtime.consoleAPICalled", sessionId, (params) => {
+      if (params.type !== "error")
+        return;
+      const args = params.args;
+      const message = args?.map((arg) => String(arg.value ?? arg.description ?? "")).join(" ") ?? "";
+      const frame = params.stackTrace?.callFrames?.[0];
+      record("console", message, frame?.url, typeof params.timestamp === "number" ? params.timestamp : undefined);
+    }), this.#cdp.on("Runtime.exceptionThrown", sessionId, (params) => {
+      const details = params.exceptionDetails;
+      record("exception", details?.exception?.description ?? details?.text ?? "Uncaught exception", details?.url, typeof params.timestamp === "number" ? params.timestamp : undefined);
+    }), this.#cdp.on("Log.entryAdded", sessionId, (params) => {
+      const entry = params.entry;
+      if (entry?.level === "error")
+        record("log", entry.text ?? "", entry.url, entry.timestamp);
+    }));
+    await this.#cdp.command("Runtime.enable", {}, sessionId);
+    await this.#cdp.command("Log.enable", {}, sessionId);
+  }
+  async watchPageLoads() {
     await this.call("Page.enable");
     const tree = await this.call("Page.getFrameTree");
     this.#mainFrameId = tree.frameTree.frame.id;
+    await this.call("Runtime.addBinding", { name: "__jevDomChanged" });
+    const observeDom = `(() => {
+      if (window.__jevDomWatching) return;
+      window.__jevDomWatching = true;
+      const start = () => new MutationObserver(() => window.__jevDomChanged?.('change'))
+        .observe(document, {subtree:true, childList:true, attributes:true, characterData:true});
+      if (document.documentElement) start(); else document.addEventListener('DOMContentLoaded', start, {once:true});
+    })()`;
+    await this.call("Page.addScriptToEvaluateOnNewDocument", { source: observeDom });
+    await this.evaluate(observeDom).catch(() => {
+      return;
+    });
     const loading = (params) => {
+      if (typeof params.frameId === "string")
+        this.#loadingFrames.add(params.frameId);
+      this.signalChange();
       if (params.frameId !== this.#mainFrameId || this.#pageLoadPromise)
         return;
       this.#pageLoadPromise = new Promise((resolve2) => {
@@ -436,6 +629,9 @@ class Browser {
       });
     };
     const loaded = () => {
+      if (this.#mainFrameId)
+        this.#loadingFrames.delete(this.#mainFrameId);
+      this.signalChange();
       if (!this.#pageLoadPromise)
         return;
       this.#pauseUntil = performance.now() + this.#interactionPauses;
@@ -445,34 +641,69 @@ class Browser {
     };
     this.#stopPageEvents.push(this.#cdp.on("Page.frameStartedLoading", this.#sessionId, loading), this.#cdp.on("Page.frameNavigated", this.#sessionId, (params) => {
       const frame = params.frame;
+      this.signalChange();
       if (frame && frame.id === this.#mainFrameId && !frame.parentId)
         loading({ frameId: frame.id });
     }), this.#cdp.on("Page.loadEventFired", this.#sessionId, loaded), this.#cdp.on("Page.frameStoppedLoading", this.#sessionId, (params) => {
+      if (typeof params.frameId === "string")
+        this.#loadingFrames.delete(params.frameId);
+      this.signalChange();
       if (params.frameId === this.#mainFrameId)
         loaded();
     }), this.#cdp.on("Page.navigatedWithinDocument", this.#sessionId, (params) => {
+      this.signalChange();
       if (params.frameId === this.#mainFrameId) {
         this.#pauseUntil = performance.now() + this.#interactionPauses;
         this.resetRecordingCursor().catch(() => {
           return;
         });
       }
-    }));
+    }), this.#cdp.on("Page.frameAttached", this.#sessionId, () => this.signalChange()), this.#cdp.on("Page.frameDetached", this.#sessionId, () => this.signalChange()), this.#cdp.on("Runtime.bindingCalled", this.#sessionId, () => this.signalChange()));
+  }
+  signalChange() {
+    for (const listener of this.#changeListeners)
+      listener();
+  }
+  async waitForChange(ms) {
+    await new Promise((resolve2) => {
+      const done = () => {
+        clearTimeout(timer);
+        this.#changeListeners.delete(done);
+        resolve2();
+      };
+      const timer = setTimeout(done, Math.min(ms, 150));
+      this.#changeListeners.add(done);
+    });
+  }
+  async waitForNewTarget(ms) {
+    if (this.#newTargets.size)
+      return;
+    await new Promise((resolve2) => {
+      const done = () => {
+        clearTimeout(timer);
+        this.#popupListeners.delete(done);
+        resolve2();
+      };
+      const timer = setTimeout(done, ms);
+      this.#popupListeners.add(done);
+    });
   }
   async waitForInteractionPause() {
     if (!this.#interactionPauses)
       return;
+    const waitStarted = performance.now();
     while (true) {
       const pageLoad = this.#pageLoadPromise;
       if (pageLoad) {
-        await Promise.race([
-          pageLoad,
-          Bun.sleep(15000).then(() => {
-            throw new Error("Page did not finish loading within 15 seconds");
-          })
-        ]);
+        const remainingBudget = this.#waitBudgetMs - this.#waitSpentMs - (performance.now() - waitStarted);
+        if (remainingBudget <= 0)
+          throw new WaitTimeoutError(Math.round(this.#waitSpentMs + performance.now() - waitStarted), "main document loading", null);
+        await Promise.race([pageLoad, Bun.sleep(remainingBudget).then(() => {
+          throw new WaitTimeoutError(Math.round(this.#waitSpentMs + performance.now() - waitStarted), "main document loading", null);
+        })]);
         continue;
       }
+      this.#waitSpentMs += performance.now() - waitStarted;
       const remaining = this.#pauseUntil - performance.now();
       if (remaining <= 0)
         return;
@@ -482,11 +713,10 @@ class Browser {
   async startRecording() {
     if (!this.#recordingPath)
       return;
-    if (!Bun.which("ffmpeg"))
-      throw new Error("--recording requires ffmpeg on PATH");
+    await recordingEncoder();
     const firstSegment = !this.#recordingDirectory;
     if (firstSegment)
-      this.#recordingDirectory = await mkdtemp(join(tmpdir(), "jev-cdp-recording-"));
+      this.#recordingDirectory = await mkdtemp2(join2(tmpdir2(), "jev-cdp-recording-"));
     await this.call("Page.enable");
     await this.call("Page.addScriptToEvaluateOnNewDocument", { source: RECORDING_CURSOR_INIT });
     const viewport = await this.evaluate("({width: innerWidth, height: innerHeight})");
@@ -494,7 +724,7 @@ class Browser {
       throw new Error("Could not read the recording viewport");
     await this.animateCursor(viewport.width / 2, viewport.height / 2);
     const initial = await this.call("Page.captureScreenshot", { format: "jpeg", quality: 70 });
-    const initialPath = join(this.#recordingDirectory, `${String(this.#recordingSequence++).padStart(6, "0")}.jpg`);
+    const initialPath = join2(this.#recordingDirectory, `${String(this.#recordingSequence++).padStart(6, "0")}.jpg`);
     await Bun.write(initialPath, Buffer.from(initial.data, "base64"));
     if (firstSegment)
       this.#recordingStartedAt = performance.now();
@@ -505,7 +735,7 @@ class Browser {
         return;
       });
       const sequence = this.#recordingSequence++;
-      const path = join(this.#recordingDirectory, `${String(sequence).padStart(6, "0")}.jpg`);
+      const path = join2(this.#recordingDirectory, `${String(sequence).padStart(6, "0")}.jpg`);
       const elapsedMs = sequence ? performance.now() - this.#recordingStartedAt : 0;
       this.#recordingWrites = this.#recordingWrites.then(async () => {
         await Bun.write(path, Buffer.from(frame.data, "base64"));
@@ -543,33 +773,12 @@ class Browser {
       lines.push(`file '${quoted(frame.path)}'`, `duration ${duration.toFixed(4)}`);
     }
     lines.push(`file '${quoted(this.#recordingFrames.at(-1).path)}'`);
-    const manifest = join(this.#recordingDirectory, "frames.ffconcat");
+    const manifest = join2(this.#recordingDirectory, "frames.ffconcat");
     await Bun.write(manifest, `${lines.join(`
 `)}
 `);
-    const process2 = Bun.spawn([
-      Bun.which("ffmpeg"),
-      "-y",
-      "-f",
-      "concat",
-      "-safe",
-      "0",
-      "-i",
-      manifest,
-      "-vsync",
-      "vfr",
-      "-c:v",
-      "libx264",
-      "-pix_fmt",
-      "yuv420p",
-      "-movflags",
-      "+faststart",
-      this.#recordingPath
-    ], { stdout: "ignore", stderr: "pipe" });
-    const stderr = await new Response(process2.stderr).text();
-    if (await process2.exited !== 0)
-      throw new Error(`Could not render recording: ${stderr.slice(-800)}`);
-    await rm(this.#recordingDirectory, { recursive: true, force: true });
+    await renderRecording(await recordingEncoder(), manifest, this.#recordingPath);
+    await rm2(this.#recordingDirectory, { recursive: true, force: true });
     this.#recordingDirectory = undefined;
   }
   async saveFinalScreenshot() {
@@ -612,18 +821,52 @@ class Browser {
     })()`);
   }
   async waitForReady() {
-    const deadline = Date.now() + 15000;
-    while (Date.now() < deadline) {
+    const started = performance.now();
+    const deadline = started + this.#waitBudgetMs - this.#waitSpentMs;
+    while (performance.now() < deadline) {
       try {
-        if (!this.#pageLoadPromise && await this.evaluate("document.readyState") === "complete")
+        if (!this.#pageLoadPromise && await this.evaluate("document.readyState") === "complete") {
+          this.#waitSpentMs += performance.now() - started;
           return;
+        }
+      } catch (error) {
+        if (!(error instanceof StalePageError))
+          throw error;
+      }
+      await this.waitForChange(Math.max(1, deadline - performance.now()));
+    }
+    this.#waitSpentMs += performance.now() - started;
+    const state = await this.observe(false).catch(() => null);
+    throw new WaitTimeoutError(Math.round(this.#waitSpentMs), "main document loading", state);
+  }
+  async waitForSemanticReady(initial, screenshot = this.#screenshots) {
+    const started = performance.now();
+    const spentAtStart = this.#waitSpentMs;
+    const deadline = started + Math.max(0, this.#waitBudgetMs - this.#waitSpentMs);
+    const accountWait = () => {
+      this.#waitSpentMs += Math.max(0, performance.now() - started - (this.#waitSpentMs - spentAtStart));
+    };
+    let state = initial;
+    while (true) {
+      const pending = state.frames.find((frame) => frame.loading || frame.readyState !== "complete");
+      const loadingText = state.frames.length > 1 && !state.actions.some((action) => action.frameId) && /(?:^|\n)loading(?:\.{0,3}|\s)/i.test(state.text);
+      if (!pending && !loadingText) {
+        accountWait();
+        return state;
+      }
+      const condition = pending ? `frame ${pending.url || pending.id} loading` : "embedded content loading";
+      if (performance.now() >= deadline) {
+        accountWait();
+        throw new WaitTimeoutError(Math.round(this.#waitSpentMs), condition, state);
+      }
+      await this.waitForChange(Math.max(1, deadline - performance.now()));
+      try {
+        state = await this.observe(screenshot);
       } catch (error) {
         if (!(error instanceof StalePageError))
           throw error;
       }
-      await Bun.sleep(20);
     }
-    throw new Error("Page did not finish loading within 15 seconds");
   }
   async evaluate(expression, awaitPromise = false) {
     const response = await this.call("Runtime.evaluate", { expression, returnByValue: true, awaitPromise }, awaitPromise ? 15000 : undefined);
@@ -644,14 +887,48 @@ class Browser {
       throw new StalePageError("Frame changed during evaluation");
     return response.result?.value;
   }
-  async frameOffset(frameId) {
-    const owner = await this.call("DOM.getFrameOwner", { frameId });
-    const box = await this.call("DOM.getBoxModel", { backendNodeId: owner.backendNodeId });
+  async frameOffset(frameId, parentId = null) {
+    const session = parentId ? this.#frameSessions.get(parentId) ?? this.#sessionId : this.#sessionId;
+    const owner = await this.#cdp.command("DOM.getFrameOwner", { frameId }, session);
+    const box = await this.#cdp.command("DOM.getBoxModel", { backendNodeId: owner.backendNodeId }, session);
     return { x: box.model.content[0], y: box.model.content[1] };
   }
-  async childFrames() {
+  async frameScreenOffset(frameId, frames) {
+    const states = frames ?? await this.frameStates();
+    let id = frameId;
+    let x = 0, y = 0;
+    while (id) {
+      const frame = states.find((item) => item.id === id);
+      if (!frame?.parentId)
+        break;
+      const offset = await this.frameOffset(id, frame.parentId);
+      x += offset.x;
+      y += offset.y;
+      id = frame.parentId;
+    }
+    return { x, y };
+  }
+  async frameStates() {
     const tree = await this.call("Page.getFrameTree");
-    return (tree.frameTree.childFrames ?? []).map((child) => child.frame.id);
+    const frames = [];
+    const visit = async (node, parentId) => {
+      const { id, url = "" } = node.frame;
+      let readyState = null;
+      try {
+        readyState = id === this.#mainFrameId ? await this.evaluate("document.readyState") ?? null : await this.evaluateFrame(id, "document.readyState") ?? null;
+      } catch {}
+      frames.push({
+        id,
+        parentId,
+        url,
+        readyState,
+        loading: this.#loadingFrames.has(id) || readyState !== "complete"
+      });
+      for (const child of node.childFrames ?? [])
+        await visit(child, id);
+    };
+    await visit(tree.frameTree, null);
+    return frames;
   }
   async discoverTabs() {
     if (!this.#switchOnPopup)
@@ -660,6 +937,7 @@ class Browser {
       if (target.type !== "page" || this.#knownTargets.has(target.id))
         continue;
       this.#knownTargets.add(target.id);
+      this.#newTargets.delete(target.id);
       const attached = await this.#cdp.command("Target.attachToTarget", { targetId: target.id, flatten: true });
       try {
         await this.#cdp.command("Emulation.setDeviceMetricsOverride", {
@@ -680,6 +958,9 @@ class Browser {
           }
           this.#sessionId = attached.sessionId;
           this.#targetId = target.id;
+          this.#loadingFrames.clear();
+          await this.watchConsole();
+          await this.watchPageLoads();
           this.#switchOnPopup = false;
           await this.startRecording();
         } else {
@@ -687,7 +968,30 @@ class Browser {
         }
       }
       this.#openedTabs.push({ id: target.id, url: target.url, title: target.title });
+      if (this.#origin)
+        this.#transitions.push({
+          kind: "new_tab",
+          control: this.#origin.control,
+          fromTargetId: this.#origin.targetId,
+          targetId: target.id,
+          fromUrl: this.#origin.url,
+          destinationUrl: target.url,
+          settled: false
+        });
+      const urls = this.#targetUrls.get(target.id) ?? [];
+      const requested = this.#origin?.href ?? urls[0];
+      if (this.#origin && requested && requested !== target.url)
+        this.#transitions.push({
+          kind: "redirect",
+          control: this.#origin.control,
+          fromTargetId: this.#origin.targetId,
+          targetId: target.id,
+          fromUrl: requested,
+          destinationUrl: target.url,
+          settled: false
+        });
     }
+    this.#switchOnPopup = false;
   }
   async settleAfterInput() {
     const action = this.#afterInput;
@@ -726,32 +1030,42 @@ class Browser {
     await this.settleAfterInput();
     await this.discoverTabs();
     let info;
-    for (let attempt = 0;attempt < 10; attempt++) {
+    const waitStarted = performance.now();
+    const deadline = waitStarted + Math.max(0, this.#waitBudgetMs - this.#waitSpentMs);
+    let waited = false;
+    while (true) {
       try {
         info = await this.evaluate(snapshot_default);
         if (info)
           break;
       } catch (error) {
-        if (!(error instanceof StalePageError) || attempt === 9)
+        if (!(error instanceof StalePageError))
           throw error;
       }
-      await Bun.sleep(20);
+      if (performance.now() >= deadline) {
+        this.#waitSpentMs += performance.now() - waitStarted;
+        throw new WaitTimeoutError(Math.round(this.#waitSpentMs), "document navigating", null);
+      }
+      waited = true;
+      await this.waitForChange(Math.max(1, deadline - performance.now()));
     }
-    if (!info)
-      throw new StalePageError("Document is navigating");
+    if (waited)
+      this.#waitSpentMs += performance.now() - waitStarted;
     if (this.#openedTabs.length) {
-      const targets = await listChromeTargets(this.#cdpUrl);
+      const targets2 = await listChromeTargets(this.#cdpUrl);
       this.#openedTabs = this.#openedTabs.map((tab) => {
-        const current = targets.find((target) => target.id === tab.id);
+        const current = targets2.find((target) => target.id === tab.id);
         return current ? { ...tab, url: current.url, title: current.title } : tab;
       });
       info.text = `${info.text}
 ${this.#openedTabs.map((tab) => `Opened new tab: ${tab.title} ${tab.url} (target ${tab.id})`).join(`
 `)}`;
     }
-    for (const frameId of await this.childFrames()) {
+    const frames = await this.frameStates();
+    for (const frame of frames.filter((frame2) => frame2.parentId !== null)) {
+      const frameId = frame.id;
       try {
-        const offset = await this.frameOffset(frameId);
+        const offset = await this.frameScreenOffset(frameId, frames);
         const child = await this.evaluateFrame(frameId, snapshot_default);
         if (!child)
           continue;
@@ -763,13 +1077,67 @@ ${child.text}`.slice(0, 6000);
           const rect = { ...action.rect, x: action.rect.x + offset.x, y: action.rect.y + offset.y };
           if (rect.x < 0 || rect.y < 0 || rect.x >= info.w || rect.y >= info.h)
             continue;
-          info.actions.push({ ...action, frameId, rect, id: `e${info.actions.length + 1}` });
+          const covering = await this.evaluate(`(() => {
+            const e=document.elementFromPoint(${rect.x + rect.w / 2},${rect.y + rect.h / 2});
+            if (!e || e.tagName==='IFRAME') return null;
+            return {tag:e.tagName.toLowerCase(),text:(e.innerText||e.getAttribute('aria-label')||'').trim().slice(0,160),role:e.getAttribute('role')};
+          })()`);
+          info.actions.push({
+            ...action,
+            frameId,
+            rect,
+            id: `e${info.actions.length + 1}`,
+            clickable: action.clickable && !covering,
+            coveredBy: covering ?? action.coveredBy
+          });
           info.guards[`${frameId}:${action.node}`] = child.guards[String(action.node)];
         }
         info.marker = [info.marker, frameId, child.marker];
       } catch {}
     }
-    const page = { ...info, fingerprint: fingerprint(info) };
+    if (this.#origin && this.#targetId === this.#origin.targetId && info.url !== this.#origin.url && !this.#transitions.some((transition) => transition.control === this.#origin.control && transition.fromUrl === this.#origin.url && transition.targetId === this.#targetId)) {
+      this.#transitions.push({
+        kind: "navigation",
+        control: this.#origin.control,
+        fromTargetId: this.#origin.targetId,
+        targetId: this.#targetId,
+        fromUrl: this.#origin.url,
+        destinationUrl: info.url,
+        settled: false
+      });
+      if (this.#origin.href && this.#origin.href !== info.url)
+        this.#transitions.push({
+          kind: "redirect",
+          control: this.#origin.control,
+          fromTargetId: this.#origin.targetId,
+          targetId: this.#targetId,
+          fromUrl: this.#origin.href,
+          destinationUrl: info.url,
+          settled: false
+        });
+    }
+    const targets = this.#transitions.length ? await listChromeTargets(this.#cdpUrl) : [];
+    for (const transition of this.#transitions) {
+      const target = targets.find((item) => item.id === transition.targetId);
+      if (target)
+        transition.destinationUrl = target.url;
+      transition.settled = frames.every((frame) => !frame.loading);
+    }
+    if (this.#origin?.href)
+      for (const transition of this.#transitions.filter((item) => item.kind === "new_tab" && item.control === this.#origin.control)) {
+        if (transition.destinationUrl !== this.#origin.href && !this.#transitions.some((item) => item.kind === "redirect" && item.targetId === transition.targetId && item.fromUrl === this.#origin.href)) {
+          this.#transitions.push({
+            kind: "redirect",
+            control: transition.control,
+            fromTargetId: transition.fromTargetId,
+            targetId: transition.targetId,
+            fromUrl: this.#origin.href,
+            destinationUrl: transition.destinationUrl,
+            settled: transition.settled
+          });
+        }
+      }
+    const page = { ...info, frames, transitions: [...this.#transitions], fingerprint: fingerprint(info) };
     if (screenshot) {
       const capture = await this.call("Page.captureScreenshot", { format: "jpeg", quality: 72 });
       page.screenshot = capture.data;
@@ -792,15 +1160,49 @@ ${child.text}`.slice(0, 6000);
       })()`);
       return stableStringify(current) === stableStringify([page.page_key, page.guards[String(action.node)]]);
     }
-    const marker = await this.evaluate(MARKER);
+    let marker = await this.evaluate(MARKER);
+    for (const frame of (await this.frameStates()).filter((item) => item.parentId !== null)) {
+      try {
+        const childMarker = await this.evaluateFrame(frame.id, MARKER);
+        if (childMarker !== undefined)
+          marker = [marker ?? null, frame.id, childMarker];
+      } catch {
+        return false;
+      }
+    }
     return stableStringify(marker) === stableStringify(page.marker);
   }
+  async describeElement(action) {
+    const expression = `(node => {
+      const e = window.__jevFast?.nodes.get(node);
+      if (!e?.isConnected) return null;
+      const path = [];
+      for (let current = e; current; current = current.parentElement) {
+        if (current.id && document.querySelectorAll('#' + CSS.escape(current.id)).length === 1) {
+          path.unshift('#' + CSS.escape(current.id));
+          break;
+        }
+        let position = 1;
+        for (let sibling = current.previousElementSibling; sibling; sibling = sibling.previousElementSibling) {
+          if (sibling.tagName === current.tagName) position++;
+        }
+        path.unshift(current.tagName.toLowerCase() + ':nth-of-type(' + position + ')');
+      }
+      return {css:path.join(' > '),tag:e.tagName.toLowerCase(),
+        href:typeof e.href === 'string' ? e.href : e.getAttribute('href'),
+        inputType:e.getAttribute('type'),frameUrl:location.href,target:e.getAttribute('target')};
+    })(${action.node})`;
+    const details = action.frameId ? await this.evaluateFrame(action.frameId, expression) : await this.evaluate(expression);
+    if (!details)
+      throw new StalePageError("Target changed before replay details were captured");
+    return details;
+  }
   async act(action, page, text) {
     if (!await this.fresh(page, action))
       throw new StalePageError("Page changed since this decision");
     if (action.kind === "wait") {
       await Bun.sleep(100);
-      return;
+      return { element: null, performedAt: performance.now() };
     }
     if (action.kind === "scroll") {
       await this.animateCursor(550, 650);
@@ -811,14 +1213,24 @@ ${child.text}`.slice(0, 6000);
         deltaX: 0,
         deltaY: action.delta ?? 0
       });
-      return;
+      return { element: null, performedAt: performance.now() };
     }
     if (typeof action.node !== "number")
       throw new Error("Invalid observed node");
+    const details = await this.describeElement(action);
+    if (action.kind === "click")
+      this.#origin = {
+        control: action.label,
+        targetId: this.#targetId,
+        url: page.url,
+        href: details.href
+      };
     const target = await (action.frameId ? this.evaluateFrame(action.frameId, `(action => {
       const e=window.__jevFast?.nodes.get(action.node);
       if (!e?.isConnected || !e.checkVisibility({checkOpacity:true,checkVisibilityCSS:true})) return null;
-      const r=e.getBoundingClientRect(); return {x:r.x+r.width/2,y:r.y+r.height/2};
+      const r=e.getBoundingClientRect(), x=r.x+r.width/2, y=r.y+r.height/2;
+      if (!e.contains(document.elementFromPoint(x,y))) return null;
+      return {x,y};
     })(${JSON.stringify(action)})`) : this.evaluate(`(action => {
       const e=window.__jevFast?.nodes.get(action.node);
       if (!e?.isConnected || e.matches(':disabled') || e.closest('[aria-disabled="true"],[inert]') ||
@@ -841,11 +1253,37 @@ ${child.text}`.slice(0, 6000);
         throw new Error("Dropdown execution was not confirmed");
       throw new StalePageError("Target changed or is covered");
     }
+    let performedAt = action.kind === "select" ? performance.now() : 0;
     if (action.frameId) {
-      const offset = await this.frameOffset(action.frameId);
+      const offset = await this.frameScreenOffset(action.frameId);
       target.x += offset.x;
       target.y += offset.y;
+      const covered = await this.evaluate(`(() => {
+        const e=document.elementFromPoint(${target.x},${target.y});
+        return !e || e.tagName!=='IFRAME';
+      })()`);
+      if (covered)
+        throw new StalePageError("Target is covered in the parent page");
+    }
+    let frame = null;
+    if (action.frameId) {
+      const frames = await this.frameStates();
+      const parentId = frames.find((item) => item.id === action.frameId)?.parentId ?? null;
+      const index = frames.filter((item) => item.parentId === parentId).findIndex((item) => item.id === action.frameId);
+      if (index < 0)
+        throw new StalePageError("Target frame changed before input");
+      frame = { id: action.frameId, parentId, url: details.frameUrl, index };
     }
+    const element = {
+      css: details.css,
+      role: action.role ?? null,
+      name: action.label,
+      tag: details.tag,
+      href: details.href,
+      inputType: details.inputType,
+      point: { x: target.x, y: target.y },
+      frame
+    };
     await this.animateCursor(target.x, target.y);
     if (action.kind !== "select") {
       if (action.kind === "click" && this.#interactionPauses > 0) {
@@ -867,6 +1305,7 @@ ${child.text}`.slice(0, 6000);
         if (type === "mousePressed")
           await this.animateCursor(target.x, target.y, true);
       }
+      performedAt = performance.now();
       if (action.kind === "fill") {
         const modifiers = process.platform === "darwin" ? 4 : 2;
         await this.call("Input.dispatchKeyEvent", {
@@ -883,13 +1322,15 @@ ${child.text}`.slice(0, 6000);
           modifiers
         });
         await this.call("Input.insertText", { text: text ?? "" });
+        performedAt = performance.now();
       }
     }
     this.#afterInput = action;
-    if (action.frameId && action.kind === "click") {
+    if (action.kind === "click") {
       this.#switchOnPopup = true;
-      await Bun.sleep(650);
+      await this.waitForNewTarget(details.target === "_blank" ? 650 : 100);
     }
+    return { element, performedAt };
   }
   async close() {
     if (this.#closed)
@@ -926,9 +1367,9 @@ ${child.text}`.slice(0, 6000);
 }
 
 // src/model.ts
-import { mkdtemp as mkdtemp2, readFile, rm as rm2 } from "fs/promises";
-import { tmpdir as tmpdir2 } from "os";
-import { join as join2 } from "path";
+import { mkdtemp as mkdtemp3, readFile, rm as rm3 } from "fs/promises";
+import { tmpdir as tmpdir3 } from "os";
+import { join as join3 } from "path";
 
 // src/questions.ts
 var NEXT_ACTION = `Advance the user's entire goal from the CURRENT page using one operation.
@@ -938,9 +1379,9 @@ its matching autocomplete suggestion selected. For date pickers, CLICK the field
 Set every requested filter/control; a matching result alone does not prove a requested filter was set.
 Do not toggle a checkbox, switch, or radio already in the requested state.
 Submit populated search fields before opening a result; a populated field alone is not an applied search.
-WAIT only when the needed control is absent/disabled, or submitted results are still loading.
 If Search/Submit is visible and the required fields are ready, CLICK it immediately.
-Recent WAIT actions are not evidence of loading. Prefer a useful visible control over WAIT.
+Loading and frame readiness are handled by the browser adapter before this decision.
+Use frame URL, nearby text, bounds, and clickability to distinguish repeated labels.
 DONE requires visible evidence that ALL requirements are satisfied. If asked to open a result,
 a matching link is not enough. BLOCKED means no supported operation can make progress.`;
 var TARGET = `Choose the best observed target if the next operation is the one specified in this question.
@@ -1012,13 +1453,21 @@ function actionSpace(actions) {
     }
     if (typeof action.node !== "number")
       continue;
-    if (!indices.has(action.node)) {
+    const identity = `${action.frameId ?? "main"}:${action.node}`;
+    if (!indices.has(identity)) {
       const index2 = String(elements.length + 1);
-      indices.set(action.node, index2);
+      indices.set(identity, index2);
       const element2 = {
         index: index2,
         label: action.label.split(" \u2192 ")[0] ?? action.label,
-        operations: []
+        operations: [],
+        frameId: action.frameId ?? null,
+        frameUrl: action.frameUrl ?? null,
+        bounds: action.rect ?? null,
+        nearbyText: action.nearbyText ?? "",
+        region: action.region ?? "",
+        clickable: action.clickable ?? true,
+        coveredBy: action.coveredBy ?? null
       };
       for (const key of ["role", "value", "checked", "selected", "expanded", "pressed", "sensitive"]) {
         if (action[key] !== undefined)
@@ -1030,7 +1479,9 @@ function actionSpace(actions) {
       }
       elements.push(element2);
     }
-    const index = indices.get(action.node);
+    const index = indices.get(identity);
+    if (action.clickable === false)
+      continue;
     const group = targets[operation] ??= {};
     const element = elements[Number(index) - 1];
     if (!element.operations.includes(operation))
@@ -1069,6 +1520,13 @@ async function choose(page, goal, history, providedFields = []) {
       type: "choice",
       criteria: Object.fromEntries(Object.entries(candidates).map(([index, action]) => [index, {
         element: `[${index}] ${action.label}`,
+        frame_id: action.frameId ?? null,
+        frame: action.frameUrl ?? page.url,
+        region: action.region ?? "",
+        nearby_text: action.nearbyText ?? "",
+        bounds: action.rect ?? null,
+        clickable: action.clickable ?? true,
+        covered_by: action.coveredBy ?? null,
         current_value: action.current_value ?? action.value ?? "",
         ...Object.fromEntries(["role", "checked", "selected", "expanded", "pressed", "sensitive"].filter((name) => action[name] !== undefined).map((name) => [name, action[name]]))
       }])),
@@ -1151,9 +1609,9 @@ async function codexFieldText(context) {
   if (!["none", "low", "medium", "high", "xhigh", "max"].includes(reasoning)) {
     throw new Error("Unsupported Codex reasoning effort");
   }
-  const folder = await mkdtemp2(join2(tmpdir2(), "jev-codex-text-"));
-  const outputPath = join2(folder, "output.json");
-  const schemaPath = join2(folder, "schema.json");
+  const folder = await mkdtemp3(join3(tmpdir3(), "jev-codex-text-"));
+  const outputPath = join3(folder, "output.json");
+  const schemaPath = join3(folder, "schema.json");
   await Bun.write(schemaPath, JSON.stringify(text_value_schema_default));
   const childEnvironment = Object.fromEntries(Object.entries(process.env).filter(([name, value]) => value !== undefined && !["TYPESAFE_API_KEY", "TEXT_MODEL_API_KEY"].includes(name)).map(([name, value]) => [name, value]));
   const command = [
@@ -1216,7 +1674,7 @@ ${JSON.stringify(context)}`;
       usage: {}
     }];
   } finally {
-    await rm2(folder, { recursive: true, force: true });
+    await rm3(folder, { recursive: true, force: true });
   }
 }
 async function apiFieldText(context) {
@@ -1248,12 +1706,23 @@ function fieldText(context) {
 }
 
 // src/agent.ts
+function redactConsoleErrors(errors, secrets) {
+  const redact = (text) => secrets.reduce((value, secret) => value.replaceAll(secret, "[redacted]"), text);
+  return errors.map((error) => ({
+    ...error,
+    message: redact(error.message),
+    ...error.url ? { url: redact(error.url) } : {}
+  }));
+}
+
 class Agent {
   #browser;
   #goal;
   #maxSteps;
   #screenshots;
   #fieldValues;
+  #sensitiveFieldLabels;
+  #secretValues;
   #page;
   #decision = null;
   #history = [];
@@ -1262,6 +1731,8 @@ class Agent {
   #status = "ready";
   #startedAt = null;
   #pendingText = null;
+  #waitTimeout;
+  #initialConsoleErrors = [];
   constructor(browser, page, options) {
     this.#browser = browser;
     this.#page = page;
@@ -1269,6 +1740,9 @@ class Agent {
     this.#maxSteps = options.maxSteps;
     this.#screenshots = options.screenshots ?? false;
     this.#fieldValues = options.fieldValues ?? {};
+    this.#sensitiveFieldLabels = new Set(options.sensitiveFieldLabels ?? []);
+    this.#secretValues = Object.entries(this.#fieldValues).filter(([label, value]) => this.#sensitiveFieldLabels.has(label) && value.length > 0).map(([, value]) => value);
+    this.#startedAt = performance.now();
   }
   static async create(options) {
     if (!options.goal.trim())
@@ -1286,12 +1760,24 @@ class Agent {
       recordingPath: options.recordingPath,
       screenshotPath: options.screenshotPath,
       freshContext: options.freshContext,
-      interactionPauses: options.interactionPauses
+      interactionPauses: options.interactionPauses,
+      waitBudgetMs: options.waitBudgetMs
     });
     try {
-      return new Agent(browser, await browser.observe(options.screenshots), options);
+      const agent = new Agent(browser, await browser.observe(options.screenshots), options);
+      try {
+        await agent.waitForReadiness();
+      } catch (error) {
+        if (!(error instanceof WaitTimeoutError))
+          throw error;
+        agent.recordWaitTimeout(error);
+      }
+      agent.#initialConsoleErrors = redactConsoleErrors(browser.takeConsoleErrors(), agent.#secretValues);
+      return agent;
     } catch (error) {
-      await browser.close();
+      await browser.close().catch(() => {
+        return;
+      });
       throw error;
     }
   }
@@ -1306,7 +1792,14 @@ class Agent {
       status: this.#status,
       elapsedMs: this.elapsedMs(),
       maxSteps: this.#maxSteps,
-      elements: actionSpace(this.#page.actions).elements
+      elements: actionSpace(this.#page.actions).elements,
+      initialConsoleErrors: [...this.#initialConsoleErrors],
+      consoleErrors: [
+        ...this.#initialConsoleErrors,
+        ...this.#history.flatMap((entry) => entry.consoleErrors),
+        ...redactConsoleErrors(this.#browser.pendingConsoleErrors(), this.#secretValues)
+      ],
+      ...this.#waitTimeout ? { waitTimeout: this.#waitTimeout } : {}
     };
   }
   get targetId() {
@@ -1320,15 +1813,12 @@ class Agent {
       this.#startedAt = performance.now();
     if (!await this.#browser.fresh(this.#page)) {
       this.#page = await this.#browser.observe(this.#screenshots);
+      await this.waitForReadiness();
     }
     this.#decision = null;
-    if (["done", "blocked", "budget_exhausted"].includes(this.#status)) {
+    if (["done", "blocked", "budget_exhausted", "wait_timeout"].includes(this.#status)) {
       throw new Error("This run has stopped");
     }
-    if (this.#decisions.length >= this.#maxSteps * 2) {
-      this.#status = "budget_exhausted";
-      return;
-    }
     this.#decision = await choose(this.#page, this.#goal, this.#history, Object.keys(this.#fieldValues));
     this.#decisions.push(this.#decision);
     this.#status = "predicted";
@@ -1369,7 +1859,7 @@ class Agent {
       if (provided !== undefined) {
         text = provided;
         helper = { model: "provided-field-value", provider: "caller", latency_ms: 0, usage: {} };
-        this.#textCalls.push({ ...helper, field: action.label, value: action.sensitive ? "[redacted]" : text });
+        this.#textCalls.push({ ...helper, field: action.label, value: action.sensitive || this.#sensitiveFieldLabels.has(action.label) ? "[redacted]" : text });
       } else if (this.#pendingText?.contextKey === contextKey) {
         ({ text, helper } = this.#pendingText);
       } else {
@@ -1379,7 +1869,8 @@ class Agent {
       }
     }
     await this.#browser.waitForInteractionPause();
-    await this.#browser.act(action, page, text ?? undefined);
+    const fromTargetId = this.#browser.targetId;
+    const { element, performedAt } = await this.#browser.act(action, page, text ?? undefined);
     this.#pendingText = null;
     const entry = {
       step: this.#history.length + 1,
@@ -1389,21 +1880,33 @@ class Agent {
       probability: decision.probabilities[selected] ?? 0,
       confidence: decision.confidence,
       latency_ms: decision.latency_ms,
-      text: action.sensitive && text !== null ? "[redacted]" : text,
+      text: (action.sensitive || this.#sensitiveFieldLabels.has(action.label)) && text !== null ? "[redacted]" : text,
       text_helper: helper?.model ?? null,
       text_latency_ms: helper?.latency_ms ?? 0,
       operation: decision.operation,
       target: decision.target,
       page_changed: null,
+      from_url: page.url,
       url: page.url,
+      viewport: { width: page.w, height: page.h },
+      from_target_id: fromTargetId,
+      target_id: this.#browser.targetId,
+      element,
+      value: action.kind === "select" ? action.value ?? null : null,
+      delta_y: action.kind === "scroll" ? action.delta ?? 0 : null,
+      redacted: action.kind === "fill" && (Boolean(action.sensitive) || this.#sensitiveFieldLabels.has(action.label)),
       usage: decision.usage,
-      executed_ms: this.elapsedMs(),
-      elapsed_ms: this.elapsedMs()
+      executed_ms: Math.round(performedAt - this.#startedAt),
+      elapsed_ms: this.elapsedMs(),
+      consoleErrors: []
     };
     this.#history.push(entry);
     this.#page = await this.#browser.observe(this.#screenshots);
+    await this.waitForReadiness();
+    entry.consoleErrors = redactConsoleErrors(this.#browser.takeConsoleErrors(), this.#secretValues);
     entry.page_changed = this.#page.fingerprint !== page.fingerprint;
     entry.url = this.#page.url;
+    entry.target_id = this.#browser.targetId;
     entry.elapsed_ms = this.elapsedMs();
     this.#status = "ready";
   }
@@ -1412,21 +1915,41 @@ class Agent {
       await this.predict();
       await this.act();
     } catch (error) {
+      if (error instanceof WaitTimeoutError) {
+        this.recordWaitTimeout(error);
+        return this.snapshot();
+      }
       if (!(error instanceof StalePageError))
         throw error;
       this.#decision = null;
       this.#status = "ready";
       this.#page = await this.#browser.observe(this.#screenshots);
+      try {
+        await this.waitForReadiness();
+      } catch (waitError) {
+        if (!(waitError instanceof WaitTimeoutError))
+          throw waitError;
+        this.recordWaitTimeout(waitError);
+      }
     }
     return this.snapshot();
   }
   async run(onStep) {
-    while (!["done", "blocked", "budget_exhausted"].includes(this.#status)) {
+    while (!["done", "blocked", "budget_exhausted", "wait_timeout"].includes(this.#status)) {
       const state = await this.tick();
       onStep?.(state);
     }
     return this.snapshot();
   }
+  async waitForReadiness() {
+    this.#page = await this.#browser.waitForSemanticReady(this.#page, this.#screenshots);
+  }
+  recordWaitTimeout(error) {
+    this.#status = "wait_timeout";
+    this.#waitTimeout = { elapsedMs: error.elapsedMs, pendingCondition: error.pendingCondition };
+    if (error.state)
+      this.#page = error.state;
+  }
   close() {
     return this.#browser.close();
   }
@@ -1502,6 +2025,8 @@ Goal control:
   --goal <text>                  One bounded browser goal. Required.
   --max-steps <number>           Maximum executed browser actions.
                                  [env: JEV_MAX_STEPS] [default: 12]
+  --wait-budget-ms <number>      Total wall-clock budget for page and frame readiness.
+                                 [default: 15000]
 
 Browser behavior:
   --visible                      Activate the controlled tab.
@@ -1525,12 +2050,15 @@ Evidence and output:
   -h, --help                     Show this help and exit.
 
 Output:
-  The final result is one JSON object on stdout. Progress and diagnostics use stderr.
+  Stdout is JSON Lines: one object per executed action, then one result object.
+  Each action includes new console errors observed during that step. The result
+  includes initial errors and all errors observed during the run.
+  Errors and diagnostics use stderr.
 
 Exit codes:
   0  Jev reported the goal complete.
   1  Invalid configuration or runtime failure.
-  2  Jev reported that it was blocked.
+  2  Jev was blocked or the wait budget timed out.
   3  The maximum browser-step budget was exhausted.
 
 Examples:
@@ -1613,6 +2141,7 @@ function addFieldValue(options, assignment, fromEnvironment) {
     if (!supplied)
       throw new CliError(`Environment variable is missing or empty: ${environmentName}`);
     options.fieldValues[label] = supplied;
+    options.sensitiveFieldLabels.push(label);
   } else {
     options.fieldValues[label] = assignment.slice(separator + 1);
   }
@@ -1622,10 +2151,12 @@ function parseRunOptions(args) {
     cdpUrl: process.env.CHROME_CDP_URL ?? DEFAULT_CDP_URL,
     maxSteps: parsePositiveInteger(process.env.JEV_MAX_STEPS ?? "12", "JEV_MAX_STEPS"),
     interactionPauses: 0,
+    waitBudgetMs: 15000,
     visible: enabled(process.env.JEV_BROWSER_VISIBLE),
     keepOpen: enabled(process.env.JEV_BROWSER_KEEP_OPEN),
     finalState: false,
     fieldValues: {},
+    sensitiveFieldLabels: [],
     freshContext: enabled(process.env.JEV_BROWSER_FRESH_CONTEXT)
   };
   for (let index = 0;index < args.length; index++) {
@@ -1642,6 +2173,8 @@ function parseRunOptions(args) {
       options.maxSteps = parsePositiveInteger(nextValue(args, index++, argument), argument);
     else if (argument === "--interaction-pauses")
       options.interactionPauses = parseNonNegativeInteger(nextValue(args, index++, argument), argument);
+    else if (argument === "--wait-budget-ms")
+      options.waitBudgetMs = parsePositiveInteger(nextValue(args, index++, argument), argument);
     else if (argument === "--recording")
       options.recordingPath = nextValue(args, index++, argument);
     else if (argument === "--screenshot")
@@ -1689,17 +2222,45 @@ function parseCommonOptions(args, help) {
   }
   return options;
 }
-function latencyStats(values) {
+function actionEvent(entry, maxSteps) {
+  return {
+    type: "action",
+    status: "executed",
+    step: entry.step,
+    elapsedMs: entry.executed_ms,
+    budget: { used: entry.step, max: maxSteps, remaining: maxSteps - entry.step },
+    page: { before: entry.from_url, after: entry.url, changed: entry.page_changed, viewport: entry.viewport },
+    tab: { before: entry.from_target_id, after: entry.target_id },
+    consoleErrors: entry.consoleErrors,
+    action: {
+      kind: entry.kind,
+      label: entry.action,
+      element: entry.element,
+      ...entry.kind === "fill" ? { text: entry.text, redacted: entry.redacted } : {},
+      ...entry.kind === "select" ? { optionValue: entry.value } : {},
+      ...entry.kind === "scroll" ? { deltaY: entry.delta_y, point: { x: 550, y: 650 } } : {},
+      ...entry.kind === "wait" ? { durationMs: 100 } : {}
+    }
+  };
+}
+function semanticState(page, elements) {
+  const frameTree = (parentId) => page.frames.filter((frame) => frame.parentId === parentId).map((frame) => ({ ...frame, children: frameTree(frame.id) }));
   return {
-    count: values.length,
-    totalMs: values.reduce((sum, value) => sum + value, 0),
-    averageMs: values.length ? Math.round(values.reduce((sum, value) => sum + value, 0) / values.length) : null,
-    maxMs: values.length ? Math.max(...values) : null
+    url: page.url,
+    title: page.title,
+    text: page.text,
+    viewport: { width: page.w, height: page.h },
+    scroll: page.scroll,
+    elements,
+    frameTree: frameTree(null),
+    transitions: page.transitions,
+    omittedActions: page.omitted_actions
   };
 }
 async function runGoal(args) {
   const options = parseRunOptions(args);
   let agent;
+  let reportedActions = 0;
   try {
     agent = await Agent.create({
       url: options.url,
@@ -1708,50 +2269,65 @@ async function runGoal(args) {
       cdpUrl: options.cdpUrl,
       maxSteps: options.maxSteps,
       interactionPauses: options.interactionPauses,
+      waitBudgetMs: options.waitBudgetMs,
       visible: options.visible,
       keepOpen: options.keepOpen,
       recordingPath: options.recordingPath,
       screenshotPath: options.screenshotPath,
       fieldValues: options.fieldValues,
+      sensitiveFieldLabels: options.sensitiveFieldLabels,
       freshContext: options.freshContext
     });
-    let reportedActions = 0;
-    const result = await agent.run((state) => {
+    await agent.run((state) => {
       const action = state.history.length > reportedActions ? state.history.at(-1) : undefined;
-      const decision = state.decisions.at(-1);
       reportedActions = state.history.length;
-      const operation = action?.operation ?? decision?.operation ?? "none";
-      const jevLatency = action?.latency_ms ?? decision?.latency_ms;
-      const helper = action?.text_helper ? ` text=${action.text_helper}:${action.text_latency_ms}ms` : "";
-      console.error(`elapsed=${state.elapsedMs}ms actions=${state.history.length}/${state.maxSteps} status=${state.status} operation=${operation} jev=${jevLatency ?? 0}ms${helper}`);
+      if (action)
+        console.log(JSON.stringify(actionEvent(action, state.maxSteps)));
     });
+    await agent.close();
+    const result = agent.snapshot();
     console.log(JSON.stringify({
+      type: "result",
       status: result.status,
       targetId: agent.targetId,
       url: result.page.url,
       actions: result.history.length,
       maxSteps: result.maxSteps,
+      budget: { used: result.history.length, max: result.maxSteps, remaining: result.maxSteps - result.history.length },
       elapsedMs: result.elapsedMs,
       textCalls: result.textCalls.length,
-      latency: {
-        jev: latencyStats(result.decisions.map((decision) => decision.latency_ms)),
-        textHelper: latencyStats(result.textCalls.map((call) => call.latency_ms))
-      },
+      initialConsoleErrors: result.initialConsoleErrors,
+      consoleErrors: result.consoleErrors,
+      ...result.waitTimeout ? { waitTimeout: result.waitTimeout } : {},
       ...options.recordingPath ? { recording: options.recordingPath } : {},
       ...options.screenshotPath ? { screenshot: options.screenshotPath } : {},
-      ...options.finalState ? {
-        finalState: {
-          url: result.page.url,
-          title: result.page.title,
-          text: result.page.text,
-          viewport: { width: result.page.w, height: result.page.h },
-          scroll: result.page.scroll,
-          elements: result.elements,
-          omittedActions: result.page.omitted_actions
-        }
+      ...options.finalState || result.status === "wait_timeout" ? {
+        finalState: semanticState(result.page, result.elements)
       } : {}
     }));
     return result.status === "done" ? 0 : result.status === "budget_exhausted" ? 3 : 2;
+  } catch (error) {
+    const state = agent?.snapshot();
+    for (const action of state?.history.slice(reportedActions) ?? []) {
+      console.log(JSON.stringify(actionEvent(action, options.maxSteps)));
+    }
+    console.log(JSON.stringify({
+      type: "result",
+      status: error instanceof WaitTimeoutError ? "wait_timeout" : "error",
+      targetId: agent?.targetId ?? null,
+      url: state?.page.url ?? (error instanceof WaitTimeoutError ? error.state?.url ?? null : null),
+      actions: state?.history.length ?? 0,
+      maxSteps: options.maxSteps,
+      budget: { used: state?.history.length ?? 0, max: options.maxSteps, remaining: options.maxSteps - (state?.history.length ?? 0) },
+      elapsedMs: state?.elapsedMs ?? 0,
+      initialConsoleErrors: state?.initialConsoleErrors ?? [],
+      consoleErrors: state?.consoleErrors ?? [],
+      ...error instanceof WaitTimeoutError ? { waitTimeout: { elapsedMs: error.elapsedMs, pendingCondition: error.pendingCondition } } : {},
+      ...state ? { finalState: semanticState(state.page, state.elements) } : error instanceof WaitTimeoutError && error.state ? { finalState: semanticState(error.state, actionSpace(error.state.actions).elements) } : {}
+    }));
+    if (error instanceof WaitTimeoutError)
+      return 2;
+    throw error;
   } finally {
     await agent?.close();
   }
@@ -1791,8 +2367,11 @@ async function doctor(args) {
       required: true
     });
   }
-  const ffmpeg = Bun.which("ffmpeg");
-  checks.push(ffmpeg ? { name: "recording", status: "ok", detail: `FFmpeg found at ${ffmpeg}`, required: false } : { name: "recording", status: "warning", detail: "FFmpeg not found; --recording will be unavailable", required: false });
+  try {
+    checks.push({ name: "recording", status: "ok", detail: await checkRecordingEncoder(), required: false });
+  } catch (error) {
+    checks.push({ name: "recording", status: "warning", detail: `${error instanceof Error ? error.message : String(error)}; --recording will be unavailable`, required: false });
+  }
   if (process.env.TEXT_MODEL_PROVIDER === "api") {
     checks.push(process.env.TEXT_MODEL_API_KEY ? { name: "text-helper", status: "ok", detail: `API helper configured (${process.env.TEXT_MODEL ?? "deepseek-chat"})`, required: false } : { name: "text-helper", status: "warning", detail: "TEXT_MODEL_PROVIDER=api but TEXT_MODEL_API_KEY is not set", required: false });
   } else {
@@ -1859,5 +2438,6 @@ async function main(args = Bun.argv.slice(2)) {
 if (import.meta.main)
   process.exitCode = await main();
 export {
+  actionEvent,
   main
 };