@volter-ai-dev/supercode-browser-playwright 0.2.0 → 0.2.1

package/dist/index.mjs

@@ -6,6 +6,8 @@ var UnidentifiedTarget = class extends Error {
 };
 var HostElementTarget = class extends Error {
 };
+var DocumentChanged = class extends Error {
+};
 var WORLD = "supercode-guard";
 var GROUP = "supercode-guard";
 var MAX_NODES = 8;
@@ -20,6 +22,15 @@ function findInWorld(query) {
     }
     return false;
   };
+  const frame = (element) => /^(IFRAME|FRAME|OBJECT|EMBED)$/.test(element.tagName);
+  if (query.kind === "focus") {
+    let element = document.activeElement ?? document.body;
+    while (element?.shadowRoot?.activeElement) element = element.shadowRoot.activeElement;
+    if (!element) return "Nothing has focus.";
+    if (frame(element)) return "Focus is inside an embedded frame, which the guard cannot inspect.";
+    if (onHost(element)) return "host";
+    return [element];
+  }
   if (query.kind === "point") {
     let element = document.elementFromPoint(query.x, query.y);
     if (!element) return "Nothing is at that point.";
@@ -30,24 +41,43 @@ function findInWorld(query) {
       element = inner;
       if (onHost(element)) return "host";
     }
-    if (/^(IFRAME|FRAME|OBJECT|EMBED)$/.test(element.tagName))
-      return "The point is inside an embedded frame, which the guard cannot inspect.";
+    if (frame(element)) return "The point is inside an embedded frame, which the guard cannot inspect.";
     return [element];
   }
   const { box } = query;
+  const marked = [];
   const found = [];
   const near = (a, b) => Math.abs(a - b) <= 1;
   const visit = (root) => {
     for (const element of Array.from(root.querySelectorAll("*"))) {
-      if (found.length >= query.max) return;
+      if (found.length > query.max - 1) return;
       const rect = element.getBoundingClientRect();
+      if (element.hasAttribute(query.marker)) {
+        marked.push(element);
+        element.removeAttribute(query.marker);
+      }
       if (near(rect.x, box.x) && near(rect.y, box.y) && near(rect.width, box.width) && near(rect.height, box.height))
         found.push(element);
       if (element.shadowRoot) visit(element.shadowRoot);
     }
   };
+  const cap = query.max;
+  query.max = Number.MAX_SAFE_INTEGER;
   visit(document);
-  return found.length ? found : "The element could not be found in the page's top document (it may be inside an embedded frame or a closed shadow root).";
+  query.max = cap;
+  if (marked.length !== 1 || !found.includes(marked[0]))
+    return "The element the action targets could not be confirmed at its place on the page.";
+  if (!found.length)
+    return "The element could not be found in the page's top document (it may be inside an embedded frame or a closed shadow root).";
+  if (found.length >= query.max)
+    return `More than ${query.max - 1} elements share the target's box, so which one the action lands on cannot be told.`;
+  if (found.some(frame)) return "The target is an embedded frame, whose content the guard cannot inspect.";
+  for (const element of [...found]) {
+    const label = element.closest("label");
+    const control = label ? label.control : null;
+    if (control && !found.includes(control)) found.push(control);
+  }
+  return found;
 }
 var BrowserSideTargets = class {
   constructor(page, host) {
@@ -55,20 +85,150 @@ var BrowserSideTargets = class {
     this.host = host;
   }
   session = null;
-  /** The element a resolved handle is, scrolled into view. */
+  /** A main-frame navigation has been requested or is loading and has not finished. */
+  navigating = false;
+  mainFrame = "";
+  /**
+   * The element a resolved handle is, scrolled into view. It must be in the
+   * page's main frame, and it must be one of the elements found browser-side
+   * at its box (the handle is marked with a one-off attribute the isolated
+   * world looks for, then removes).
+   */
   async ofHandle(handle, timeout) {
+    if (await handle.ownerFrame() !== this.page.mainFrame())
+      throw new UnidentifiedTarget("The element is inside an embedded frame, which the guard cannot inspect.");
     await handle.scrollIntoViewIfNeeded({ timeout });
     const box = await handle.boundingBox();
     if (!box || box.width === 0 || box.height === 0)
       throw new UnidentifiedTarget("The element has no box on the page.");
-    return await this.resolve({ kind: "box", box, host: this.host, max: MAX_NODES });
+    const marker = `data-supercode-guard-${Array.from(crypto.getRandomValues(new Uint8Array(8)), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+    await handle.evaluate((element, name) => element.setAttribute(name, ""), marker);
+    try {
+      return await this.resolve({ kind: "box", box, host: this.host, max: MAX_NODES + 1, marker });
+    } finally {
+      await handle.evaluate((element, name) => element.removeAttribute(name), marker).catch(() => void 0);
+    }
+  }
+  /**
+   * Where a key press goes: the focused element. Focus inside an embedded
+   * frame or a closed shadow root is refused.
+   */
+  async focused() {
+    return await this.resolve({ kind: "focus", host: this.host });
+  }
+  /**
+   * Whether focus is now on one of the target's elements or inside one (open
+   * shadow roots included), judged in the isolated world: a locator press is
+   * refused when focusing its element left focus elsewhere.
+   */
+  async focusWithin(target) {
+    return await this.inWorld(target, `function (...nodes) {
+      let active = document.activeElement;
+      while (active && active.shadowRoot && active.shadowRoot.activeElement) active = active.shadowRoot.activeElement;
+      for (let node = active; node; node = node.parentNode || node.host) if (nodes.includes(node)) return true;
+      return false;
+    }`) === true;
+  }
+  /** The options a select action will choose, by value or label, read browser-side. */
+  async selectOptions(target, wanted) {
+    const select = { ...target, nodes: target.nodes.filter((node) => node.tag === "select") };
+    if (!select.nodes.length) return [];
+    const options = await this.inWorld(select, `function (wanted) {
+      return Array.from(this.options).filter((option) => wanted.includes(option.value) || wanted.includes(option.label))
+        .map((option) => ({ label: option.label, value: option.value }));
+    }`, [wanted]);
+    return Array.isArray(options) ? options : [];
+  }
+  /**
+   * Calls `source` in the isolated world with the target's first node as
+   * `this`, and its nodes (or `extra` values) as arguments.
+   */
+  async inWorld(target, source, extra) {
+    const cdp = await this.cdp();
+    const contextId = await this.world(cdp);
+    try {
+      const objects = [];
+      for (const node of target.nodes) {
+        const resolved = await cdp.send("DOM.resolveNode", { backendNodeId: node.backendNodeId, executionContextId: contextId, objectGroup: GROUP });
+        if (resolved.object.objectId) objects.push(resolved.object.objectId);
+      }
+      if (!objects.length) return void 0;
+      const called = await cdp.send("Runtime.callFunctionOn", {
+        objectId: objects[0],
+        functionDeclaration: source,
+        arguments: extra ? extra.map((value) => ({ value })) : objects.map((objectId) => ({ objectId })),
+        returnByValue: true
+      });
+      return called.exceptionDetails ? void 0 : called.result.value;
+    } finally {
+      await cdp.send("Runtime.releaseObjectGroup", { objectGroup: GROUP }).catch(() => void 0);
+    }
+  }
+  async world(cdp) {
+    const tree = await cdp.send("Page.getFrameTree");
+    const world = await cdp.send("Page.createIsolatedWorld", { frameId: tree.frameTree.frame.id, worldName: WORLD });
+    return world.executionContextId;
   }
-  /** The element at a viewport point. */
+  /**
+   * The element at a viewport point, as best known. A point on the host's own
+   * interface is refused; a point whose element cannot be identified is
+   * returned with no nodes and the reason, for a guard that decides on raw
+   * pointer input regardless.
+   */
   async atPoint(x, y) {
-    return { ...await this.resolve({ kind: "point", x, y, host: this.host }), point: { x, y } };
+    try {
+      return { ...await this.resolve({ kind: "point", x, y, host: this.host }), point: { x, y } };
+    } catch (error) {
+      if (error instanceof HostElementTarget) throw error;
+      return {
+        url: this.page.url(),
+        nodes: [],
+        ancestors: [],
+        point: { x, y },
+        unidentified: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
+  /** The main frame's document now. */
+  async documentState() {
+    const cdp = await this.cdp();
+    const tree = await cdp.send("Page.getFrameTree");
+    this.mainFrame = tree.frameTree.frame.id;
+    return { loaderId: tree.frameTree.frame.loaderId, url: tree.frameTree.frame.url };
+  }
+  /**
+   * Just before input is dispatched: the main frame must still hold the
+   * document the target was checked on, with no navigation in flight.
+   */
+  async sameDocument(checked) {
+    const now = await this.documentState();
+    if (this.navigating) throw new DocumentChanged("The page is navigating, so nothing was sent; ask again once it has loaded.");
+    if (now.loaderId !== checked.loaderId || now.url !== checked.url)
+      throw new DocumentChanged("The page changed since the action was checked, so nothing was sent; ask again.");
   }
   cdp() {
-    this.session ??= this.page.context().newCDPSession(this.page).catch((error) => {
+    this.session ??= this.page.context().newCDPSession(this.page).then(async (session) => {
+      const main2 = (frameId) => !this.mainFrame || frameId === this.mainFrame;
+      session.on("Page.frameRequestedNavigation", (event) => {
+        if (main2(event.frameId)) this.navigating = true;
+      });
+      session.on("Page.frameStartedNavigating", (event) => {
+        if (main2(event.frameId)) this.navigating = true;
+      });
+      session.on("Page.frameStartedLoading", (event) => {
+        if (main2(event.frameId)) this.navigating = true;
+      });
+      const settled = (event) => {
+        const frameId = event.frameId ?? event.frame?.id;
+        if (main2(frameId) && !event.frame?.parentId) this.navigating = false;
+      };
+      session.on("Page.frameStoppedLoading", settled);
+      session.on("Page.frameNavigated", settled);
+      session.on("Page.navigatedWithinDocument", settled);
+      session.on("Page.downloadWillBegin", settled);
+      await session.send("Page.enable").catch(() => void 0);
+      return session;
+    }, (error) => {
       this.session = null;
       throw error;
     });
@@ -76,12 +236,11 @@ var BrowserSideTargets = class {
   }
   async resolve(query) {
     const cdp = await this.cdp();
-    const tree = await cdp.send("Page.getFrameTree");
-    const world = await cdp.send("Page.createIsolatedWorld", { frameId: tree.frameTree.frame.id, worldName: WORLD });
+    const contextId = await this.world(cdp);
     try {
       const evaluated = await cdp.send("Runtime.evaluate", {
         expression: `(${findInWorld.toString()})(${JSON.stringify(query)})`,
-        contextId: world.executionContextId,
+        contextId,
         objectGroup: GROUP,
         returnByValue: false
       });
@@ -99,7 +258,14 @@ var BrowserSideTargets = class {
       const ancestors = [];
       const seen = /* @__PURE__ */ new Set();
       for (const objectId of objects) {
-        const described = await cdp.send("DOM.describeNode", { objectId });
+        const described = await cdp.send("DOM.describeNode", { objectId, depth: 1, pierce: true });
+        if (query.kind === "focus" && described.node.shadowRoots?.some((root) => root.shadowRootType === "closed"))
+          throw new UnidentifiedTarget("Focus is inside a closed shadow root, which the guard cannot inspect.");
+        const facts = await cdp.send("Runtime.callFunctionOn", {
+          objectId,
+          functionDeclaration: "function () { return { form: !!(this.form || (this.closest && this.closest('form'))), text: (this.textContent || '').replace(/\\s+/g, ' ').trim().slice(0, 80) }; }",
+          returnByValue: true
+        });
         const attributes = {};
         const list = described.node.attributes ?? [];
         for (let index = 0; index + 1 < list.length; index += 2) attributes[list[index].toLowerCase()] = list[index + 1];
@@ -109,7 +275,9 @@ var BrowserSideTargets = class {
           tag: described.node.nodeName.toLowerCase(),
           attributes,
           role: ax.self?.role ?? "",
-          name: ax.self?.name ?? ""
+          name: ax.self?.name ?? "",
+          inForm: facts.result.value?.form === true,
+          ...typeof facts.result.value?.text === "string" && facts.result.value.text ? { text: facts.result.value.text } : {}
         });
         seen.add(described.node.backendNodeId);
         for (const ancestor of ax.ancestors) {
@@ -137,6 +305,78 @@ var BrowserSideTargets = class {
   }
 };
 
+// src/script-scope.ts
+function isData(value) {
+  if (Array.isArray(value) || ArrayBuffer.isView(value) || value instanceof ArrayBuffer || value instanceof Date || value instanceof RegExp || value instanceof Map || value instanceof Set || value instanceof Promise || value instanceof Error) return true;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+var ScriptScope = class {
+  closed = false;
+  proxies = /* @__PURE__ */ new WeakMap();
+  targets = /* @__PURE__ */ new WeakMap();
+  disposables = [];
+  /** The membrane's view of `value`. */
+  wrap(value) {
+    if (value === null || typeof value !== "object" && typeof value !== "function") return value;
+    const object = value;
+    if (typeof value === "object" && isData(object)) return value;
+    const existing = this.proxies.get(object);
+    if (existing) return existing;
+    const scope = this;
+    const proxy = new Proxy(object, {
+      get(target, property) {
+        scope.check();
+        const member = Reflect.get(target, property, target);
+        if (typeof member !== "function") return scope.wrap(member);
+        return function(...args) {
+          scope.check();
+          return scope.returned(Reflect.apply(member, target, args.map((arg) => scope.unwrap(arg))));
+        };
+      },
+      set() {
+        throw new Error("A script cannot change Playwright's objects.");
+      },
+      apply(target, _self, args) {
+        scope.check();
+        return scope.returned(Reflect.apply(target, void 0, args.map((arg) => scope.unwrap(arg))));
+      }
+    });
+    this.proxies.set(object, proxy);
+    this.targets.set(proxy, object);
+    return proxy;
+  }
+  /**
+   * Ends the script's hold on the page: later calls through the membrane
+   * throw, and what it installed is removed.
+   */
+  async close(page) {
+    this.closed = true;
+    for (const disposable of this.disposables.splice(0)) {
+      try {
+        await disposable.dispose();
+      } catch {
+      }
+    }
+    await page.unrouteAll({ behavior: "ignoreErrors" }).catch(() => void 0);
+    await page.context().unrouteAll({ behavior: "ignoreErrors" }).catch(() => void 0);
+    page.removeAllListeners();
+    page.context().removeAllListeners();
+  }
+  check() {
+    if (this.closed) throw new Error("The script has ended or was cancelled; it can no longer use the page.");
+  }
+  unwrap(value) {
+    return value !== null && (typeof value === "object" || typeof value === "function") ? this.targets.get(value) ?? value : value;
+  }
+  returned(value) {
+    if (value instanceof Promise) return value.then((resolved) => this.returned(resolved));
+    if (value !== null && typeof value === "object" && typeof value.dispose === "function")
+      this.disposables.push(value);
+    return this.wrap(value);
+  }
+};
+
 // src/protocol.ts
 var SUPERCODE_BROWSER_PROVIDER_PROTOCOL = "supercode/browser-provider-v1";
 var SUPERCODE_BROWSER_OPERATION_PROTOCOL = "supercode/browser-operation-v1";
@@ -566,7 +806,12 @@ var PlaywrightOperationExecutor = class {
   options;
   ready;
   targets;
-  /** Where the mouse is: `page.mouse` keeps it, but does not report it. */
+  /**
+   * Where the mouse is: `page.mouse` keeps it, but does not report it. A
+   * locator action moves it to the element's clickable point; it is then the
+   * centre of that element's box as measured after the action, or unknown
+   * (null) when that cannot be measured, and a press needs coordinates.
+   */
   mouse = { x: 0, y: 0 };
   constructor(page, options) {
     this.page = page;
@@ -664,22 +909,63 @@ var PlaywrightOperationExecutor = class {
     }
     if (!handle) throw new BrowserActionRefusal("NOT_FOUND", `${action} found no element for the locator.`);
     try {
-      await guard({
-        action,
-        target: await this.describe(() => this.targets.ofHandle(handle, ACTION_TIMEOUT_MS)),
-        ...value !== void 0 ? { value } : {}
-      });
+      const target = await this.describe(() => this.targets.ofHandle(handle, ACTION_TIMEOUT_MS));
+      const described = typeof value === "function" ? await value(target) : value;
+      await guard({ action, target, ...described !== void 0 ? { value: described } : {} });
+      return { handle, target };
     } catch (error) {
       await handle.dispose().catch(() => void 0);
       throw error;
     }
-    return handle;
   }
-  /** Asks the host's policy about the element at a viewport point. */
-  async guardPoint(action, x, y) {
+  /** The document an action is checked on; input later goes only to it. */
+  async checkpoint() {
+    if (!this.options.actionGuard) return null;
+    try {
+      return await this.targets.documentState();
+    } catch (error) {
+      throw new BrowserActionRefusal("UNSUPPORTED", `The page's document could not be identified, so nothing was sent: ${errorMessage(error)}`);
+    }
+  }
+  /** Just before input: the same document, no navigation in flight, and the host's own last check. */
+  async dispatching(state) {
+    if (!state) return;
+    try {
+      await this.targets.sameDocument(state);
+    } catch (error) {
+      if (error instanceof DocumentChanged) throw new BrowserActionRefusal("STALE_PAGE", error.message);
+      throw new BrowserActionRefusal("UNSUPPORTED", `The page's document could not be confirmed, so nothing was sent: ${errorMessage(error)}`);
+    }
+    await this.options.beforeInput?.({ url: state.url });
+  }
+  /** The page-level action's guard. */
+  async guardPage(action, value) {
+    if (this.options.actionGuard)
+      await this.options.actionGuard({ action, url: this.page.url(), ...value !== void 0 ? { value } : {} });
+  }
+  /** The pointer's position for a press that names none; unknown after a locator action. */
+  pointer(input) {
+    if (typeof input.x === "number" && typeof input.y === "number") return { x: input.x, y: input.y };
+    if (!this.mouse)
+      throw new BrowserActionRefusal(
+        "INVALID_INPUT",
+        "Where the mouse is after a locator action is not known exactly; give x and y, or move the mouse first."
+      );
+    return this.mouse;
+  }
+  /**
+   * Asks the host's policy about raw pointer input at a viewport point; the
+   * target is the element there as best known (`unidentified` when not).
+   */
+  async guardPoint(action, x, y, value) {
     const guard = this.options.actionGuard;
     if (!guard) return;
-    await guard({ action, target: await this.describe(() => this.targets.atPoint(x, y)) });
+    await guard({
+      action,
+      target: await this.describe(() => this.targets.atPoint(x, y)),
+      pointer: true,
+      ...value !== void 0 ? { value } : {}
+    });
   }
   /** A browser-side description, or the refusal that replaces the action. */
   async describe(run) {
@@ -759,6 +1045,9 @@ var PlaywrightOperationExecutor = class {
     }
     if (call.operation === "browser.scroll") {
       const direction = input.direction;
+      const state2 = await this.checkpoint();
+      await this.guardPage("scroll", { direction, ...typeof input.amount === "number" ? { amount: input.amount } : {} });
+      await this.dispatching(state2);
       const position = await page.evaluate(scrollInPage, {
         left: direction === "left" ? -1 : direction === "right" ? 1 : 0,
         top: direction === "up" ? -1 : direction === "down" ? 1 : 0,
@@ -769,43 +1058,50 @@ var PlaywrightOperationExecutor = class {
     if (call.operation === "browser.script") return this.script(call);
     if (call.operation === "browser.mouse") {
       const action = input.action;
-      const at = typeof input.x === "number" && typeof input.y === "number" ? { x: input.x, y: input.y } : this.mouse;
-      if (action === "move") await this.guardPoint("hover", at.x, at.y);
-      else await this.guardPoint(action === "click" ? "click" : action === "down" ? "mousedown" : "mouseup", at.x, at.y);
-      if (action === "move") await page.mouse.move(at.x, at.y);
-      else if (action === "click") await page.mouse.click(at.x, at.y);
+      if (action === "move") {
+        const at2 = { x: input.x, y: input.y };
+        await page.mouse.move(at2.x, at2.y);
+        this.mouse = at2;
+        return this.success(call.operation, { action, x: at2.x, y: at2.y });
+      }
+      const at = this.pointer(input);
+      const state2 = await this.checkpoint();
+      await this.guardPoint(action === "click" ? "click" : action === "down" ? "mousedown" : "mouseup", at.x, at.y);
+      await this.dispatching(state2);
+      await page.mouse.move(at.x, at.y);
+      if (action === "click") await page.mouse.click(at.x, at.y);
       else if (action === "down") await page.mouse.down();
       else await page.mouse.up();
-      if (action === "move" || action === "click") this.mouse = { x: at.x, y: at.y };
-      return this.success(call.operation, { action, ...typeof input.x === "number" ? { x: input.x, y: input.y } : {} });
+      this.mouse = at;
+      return this.success(call.operation, { action, x: at.x, y: at.y });
     }
     if (call.operation === "browser.wheel") {
       const deltaX = typeof input.deltaX === "number" ? input.deltaX : 0;
       const deltaY = typeof input.deltaY === "number" ? input.deltaY : 0;
-      await this.guardPoint("wheel", this.mouse.x, this.mouse.y);
+      const at = this.pointer(input);
+      const state2 = await this.checkpoint();
+      await this.guardPoint("wheel", at.x, at.y, { deltaX, deltaY });
+      await this.dispatching(state2);
+      await page.mouse.move(at.x, at.y);
       await page.mouse.wheel(deltaX, deltaY);
+      this.mouse = at;
       return this.success(call.operation, { deltaX, deltaY });
     }
     if (call.operation === "browser.drag") {
       const resolve = async (endpoint) => {
-        if (endpoint.locator === void 0) {
-          const point = { x: endpoint.x, y: endpoint.y };
-          await this.guardPoint("drag", point.x, point.y);
-          return point;
-        }
+        if (endpoint.locator === void 0) return { x: endpoint.x, y: endpoint.y };
         await this.refreshRefs(endpoint.locator);
         const locator2 = this.locator(endpoint.locator).first();
-        const handle2 = await this.guarded(locator2, "drag");
-        try {
-          const box = handle2 ? await handle2.boundingBox() : await locator2.count() === 0 ? null : await locator2.boundingBox({ timeout: ACTION_TIMEOUT_MS });
-          if (!box) throw new BrowserActionRefusal("NOT_FOUND", "The drag locator matched no element.");
-          return { x: box.x + box.width / 2, y: box.y + box.height / 2 };
-        } finally {
-          await handle2?.dispose().catch(() => void 0);
-        }
+        const box = await locator2.boundingBox({ timeout: ACTION_TIMEOUT_MS }).catch(() => null);
+        if (!box) throw new BrowserActionRefusal("NOT_FOUND", "The drag locator matched no element.");
+        return { x: box.x + box.width / 2, y: box.y + box.height / 2 };
       };
       const from = await resolve(input.from);
       const to = await resolve(input.to);
+      const drop = await this.describe(() => this.targets.atPoint(to.x, to.y));
+      const state2 = await this.checkpoint();
+      await this.guardPoint("drag", from.x, from.y, { from, to, drop });
+      await this.dispatching(state2);
       await page.mouse.move(from.x, from.y);
       await page.mouse.down();
       await page.mouse.move(to.x, to.y, { steps: typeof input.steps === "number" ? input.steps : 8 });
@@ -814,14 +1110,23 @@ var PlaywrightOperationExecutor = class {
       return this.success(call.operation, { from, to });
     }
     if (call.operation === "browser.back") {
+      const state2 = await this.checkpoint();
+      await this.guardPage("back");
+      await this.dispatching(state2);
       await page.goBack({ waitUntil: "commit", timeout: ACTION_TIMEOUT_MS });
       return this.success(call.operation, { requested: true });
     }
     if (call.operation === "browser.forward") {
+      const state2 = await this.checkpoint();
+      await this.guardPage("forward");
+      await this.dispatching(state2);
       await page.goForward({ waitUntil: "commit", timeout: ACTION_TIMEOUT_MS });
       return this.success(call.operation, { requested: true });
     }
     if (call.operation === "browser.reload") {
+      const state2 = await this.checkpoint();
+      await this.guardPage("reload");
+      await this.dispatching(state2);
       await page.reload({ waitUntil: "commit", timeout: ACTION_TIMEOUT_MS });
       return this.success(call.operation, { requested: true });
     }
@@ -834,37 +1139,64 @@ var PlaywrightOperationExecutor = class {
       return this.success(call.operation, box);
     }
     if (call.operation === "browser.press" && !locator) {
-      const focused = page.locator("*:focus").first();
-      const handle2 = await this.guarded(await focused.count() ? focused : page.locator("body"), "press", input.key);
-      try {
-        await page.keyboard.press(input.key);
-      } finally {
-        await handle2?.dispose().catch(() => void 0);
-      }
+      const state2 = await this.checkpoint();
+      if (this.options.actionGuard)
+        await this.options.actionGuard({ action: "press", target: await this.describe(() => this.targets.focused()), value: input.key });
+      await this.dispatching(state2);
+      await page.keyboard.press(input.key);
       return this.success(call.operation, { key: input.key });
     }
     const target = locator;
     const guardedAction = call.operation === "browser.select" ? "select" : call.operation.slice("browser.".length);
-    const handle = await this.guarded(
+    const state = await this.checkpoint();
+    const guarded = await this.guarded(
       target.first(),
       guardedAction,
-      call.operation === "browser.fill" ? input.value : call.operation === "browser.press" ? input.key : call.operation === "browser.select" ? input.values : void 0
+      call.operation === "browser.fill" ? input.value : call.operation === "browser.press" ? input.key : call.operation === "browser.select" ? async (described) => ({ values: input.values, options: await this.targets.selectOptions(described, input.values) }) : void 0
     );
+    const handle = guarded?.handle ?? null;
     const element = handle ?? { ...bind(target), focus: () => target.focus({ timeout }) };
+    const press = async () => {
+      if (!guarded) {
+        await element.press(input.key, { timeout });
+        return;
+      }
+      await guarded.handle.focus();
+      if (!await this.targets.focusWithin(guarded.target))
+        throw new BrowserActionRefusal(
+          "UNSUPPORTED",
+          "Focusing the element left focus elsewhere, so the key would go to another element; the press was refused."
+        );
+      await this.dispatching(state);
+      await page.keyboard.press(input.key);
+    };
     const before = await this.inspect(target).catch(() => null);
     try {
-      if (call.operation === "browser.click") await this.act(target, "click", () => element.click({ timeout }));
-      else if (call.operation === "browser.fill") await this.act(target, "fill", () => element.fill(input.value, { timeout }));
-      else if (call.operation === "browser.press") await this.act(target, "press", () => element.press(input.key, { timeout }));
-      else if (call.operation === "browser.hover") await this.act(target, "hover", () => element.hover({ timeout }));
-      else if (call.operation === "browser.focus") await this.act(target, "focus", () => element.focus());
-      else if (call.operation === "browser.check") await this.act(target, "check", () => element.check({ timeout }));
-      else if (call.operation === "browser.uncheck") await this.act(target, "uncheck", () => element.uncheck({ timeout }));
+      const pointer = (run) => async () => {
+        if (guarded) await run({ timeout, trial: true });
+        await this.dispatching(state);
+        await run({ timeout });
+      };
+      const direct = (run) => async () => {
+        await this.dispatching(state);
+        return await run();
+      };
+      if (call.operation === "browser.click") await this.act(target, "click", pointer((options) => element.click(options)));
+      else if (call.operation === "browser.fill") await this.act(target, "fill", direct(() => element.fill(input.value, { timeout })));
+      else if (call.operation === "browser.press") await this.act(target, "press", press);
+      else if (call.operation === "browser.hover") await this.act(target, "hover", pointer((options) => element.hover(options)));
+      else if (call.operation === "browser.focus") await this.act(target, "focus", direct(() => element.focus()));
+      else if (call.operation === "browser.check") await this.act(target, "check", pointer((options) => element.check(options)));
+      else if (call.operation === "browser.uncheck") await this.act(target, "uncheck", pointer((options) => element.uncheck(options)));
       else if (call.operation === "browser.select") {
-        const values = await this.act(target, "selectOption", () => element.selectOption(input.values, { timeout }));
+        const values = await this.act(target, "selectOption", direct(() => element.selectOption(input.values, { timeout })));
         return this.success(call.operation, { values });
       }
     } finally {
+      if (["browser.click", "browser.hover", "browser.check", "browser.uncheck"].includes(call.operation)) {
+        const box = await (handle ?? target).boundingBox().catch(() => null);
+        this.mouse = box ? { x: box.x + box.width / 2, y: box.y + box.height / 2 } : null;
+      }
       await handle?.dispose().catch(() => void 0);
     }
     const after = await this.inspect(target).catch(() => null);
@@ -889,9 +1221,10 @@ var PlaywrightOperationExecutor = class {
     }
     const notice = timeout < requested ? `The script timeout is clamped to ${SCRIPT_TIMEOUT_CLAMP_MS}ms: the harness abandons a provider call at 12 s.` : void 0;
     let timer;
+    const scope = new ScriptScope();
     try {
       const value = await Promise.race([
-        run(this.page, args),
+        run(scope.wrap(this.page), args),
         new Promise((_resolve, reject) => {
           timer = setTimeout(() => reject(new BrowserActionRefusal("FAILED", `The script exceeded ${timeout}ms.` + (notice ? ` ${notice}` : ""))), timeout);
         })
@@ -902,7 +1235,7 @@ var PlaywrightOperationExecutor = class {
       });
     } finally {
       clearTimeout(timer);
-      this.page.removeAllListeners();
+      await scope.close(this.page);
     }
   }
   async target() {