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

package/dist/index.mjs

@@ -1,6 +1,382 @@
 // src/executor.ts
 import { errors } from "playwright-core";
 
+// src/guard.ts
+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;
+var MAX_ANCESTORS = 6;
+function findInWorld(query) {
+  const onHost = (element) => {
+    if (!query.host) return false;
+    for (let node = element; node; ) {
+      if (node.matches(query.host)) return true;
+      const parent = node.parentElement;
+      node = parent ?? (node.getRootNode().host ?? null);
+    }
+    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.";
+    if (onHost(element)) return "host";
+    while (element.shadowRoot) {
+      const inner = element.shadowRoot.elementFromPoint(query.x, query.y);
+      if (!inner || inner === element) break;
+      element = inner;
+      if (onHost(element)) return "host";
+    }
+    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 - 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);
+  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) {
+    this.page = page;
+    this.host = host;
+  }
+  session = null;
+  /** 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.");
+    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, 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) {
+    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).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;
+    });
+    return this.session;
+  }
+  async resolve(query) {
+    const cdp = await this.cdp();
+    const contextId = await this.world(cdp);
+    try {
+      const evaluated = await cdp.send("Runtime.evaluate", {
+        expression: `(${findInWorld.toString()})(${JSON.stringify(query)})`,
+        contextId,
+        objectGroup: GROUP,
+        returnByValue: false
+      });
+      if (evaluated.exceptionDetails)
+        throw new UnidentifiedTarget(`The target could not be resolved: ${evaluated.exceptionDetails.text ?? "exception"}.`);
+      if (evaluated.result.type === "string") {
+        if (evaluated.result.value === "host") throw new HostElementTarget("The point is on the host's own interface, which agents cannot operate.");
+        throw new UnidentifiedTarget(String(evaluated.result.value));
+      }
+      if (!evaluated.result.objectId) throw new UnidentifiedTarget("The target could not be resolved.");
+      const properties = await cdp.send("Runtime.getProperties", { objectId: evaluated.result.objectId, ownProperties: true });
+      const objects = properties.result.filter((property) => /^\d+$/.test(property.name) && property.value?.objectId).map((property) => property.value.objectId);
+      if (!objects.length) throw new UnidentifiedTarget("The target could not be resolved.");
+      const nodes = [];
+      const ancestors = [];
+      const seen = /* @__PURE__ */ new Set();
+      for (const objectId of objects) {
+        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];
+        const ax = await this.accessibility(cdp, described.node.backendNodeId);
+        nodes.push({
+          backendNodeId: described.node.backendNodeId,
+          tag: described.node.nodeName.toLowerCase(),
+          attributes,
+          role: ax.self?.role ?? "",
+          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) {
+          if (ancestors.length >= MAX_ANCESTORS || seen.has(ancestor.backendNodeId)) continue;
+          seen.add(ancestor.backendNodeId);
+          ancestors.push(ancestor);
+        }
+      }
+      return { url: this.page.url(), nodes, ancestors };
+    } finally {
+      await cdp.send("Runtime.releaseObjectGroup", { objectGroup: GROUP }).catch(() => void 0);
+    }
+  }
+  async accessibility(cdp, backendNodeId) {
+    const tree = await cdp.send("Accessibility.getPartialAXTree", { backendNodeId, fetchRelatives: true });
+    const byId = new Map(tree.nodes.map((node) => [node.nodeId, node]));
+    const text = (value) => typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "";
+    const self = tree.nodes.find((node) => node.backendDOMNodeId === backendNodeId) ?? null;
+    const ancestors = [];
+    for (let node = self?.parentId ? byId.get(self.parentId) : void 0; node && ancestors.length < MAX_ANCESTORS; node = node.parentId ? byId.get(node.parentId) : void 0) {
+      if (node.ignored || typeof node.backendDOMNodeId !== "number") continue;
+      ancestors.push({ backendNodeId: node.backendDOMNodeId, tag: "", attributes: {}, role: text(node.role?.value), name: text(node.name?.value) });
+    }
+    return { self: self ? { role: text(self.role?.value), name: text(self.name?.value) } : null, ancestors };
+  }
+};
+
+// 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";
@@ -429,9 +805,18 @@ var PlaywrightOperationExecutor = class {
   page;
   options;
   ready;
+  targets;
+  /**
+   * 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;
     this.options = options;
+    this.targets = new BrowserSideTargets(page, options.snapshotExclude ?? null);
     this.ready = (async () => {
       await page.addInitScript(installRevisionCounter, REVISION_KEY);
       await page.evaluate(installRevisionCounter, REVISION_KEY).catch(() => void 0);
@@ -505,10 +890,96 @@ var PlaywrightOperationExecutor = class {
       throw error;
     }
   }
-  /** The host's policy for an action; an element that is not there is the action's own failure. */
-  async guard(action) {
-    if (!this.options.actionGuard || await action.locator.count().catch(() => 0) === 0) return;
-    await this.options.actionGuard(action);
+  /**
+   * Resolves the locator's element once (waiting up to the action budget),
+   * asks the host's policy about it, and returns the handle the action must
+   * use, so the element guarded is the element acted on. Without a policy the
+   * action runs on the locator. Resolution or description failing refuses.
+   */
+  async guarded(locator, action, value) {
+    const guard = this.options.actionGuard;
+    if (!guard) return null;
+    let handle;
+    try {
+      handle = await locator.elementHandle({ timeout: ACTION_TIMEOUT_MS });
+    } catch (error) {
+      if (error instanceof errors.TimeoutError)
+        throw new BrowserActionRefusal("NOT_FOUND", `${action} found no element for the locator in ${ACTION_TIMEOUT_MS}ms.`);
+      throw error;
+    }
+    if (!handle) throw new BrowserActionRefusal("NOT_FOUND", `${action} found no element for the locator.`);
+    try {
+      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;
+    }
+  }
+  /** 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)),
+      pointer: true,
+      ...value !== void 0 ? { value } : {}
+    });
+  }
+  /** A browser-side description, or the refusal that replaces the action. */
+  async describe(run) {
+    try {
+      return await run();
+    } catch (error) {
+      if (error instanceof HostElementTarget) throw new BrowserActionRefusal("UNSUPPORTED", error.message);
+      if (error instanceof UnidentifiedTarget)
+        throw new BrowserActionRefusal("UNSUPPORTED", `${error.message} The action was refused because its target could not be checked.`);
+      throw new BrowserActionRefusal(
+        "UNSUPPORTED",
+        `The action was refused because its target could not be checked: ${errorMessage(error)}`
+      );
+    }
   }
   /** The aria refs of the elements `snapshotExclude` matches, and of their contents. */
   async excludedRefs() {
@@ -574,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,
@@ -584,16 +1058,33 @@ var PlaywrightOperationExecutor = class {
     if (call.operation === "browser.script") return this.script(call);
     if (call.operation === "browser.mouse") {
       const action = input.action;
-      if (action === "move") await page.mouse.move(input.x, input.y);
-      else if (action === "click") await page.mouse.click(input.x, input.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();
-      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;
+      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") {
@@ -601,29 +1092,41 @@ var PlaywrightOperationExecutor = class {
         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 box = await locator2.count() === 0 ? null : await locator2.boundingBox({ timeout: ACTION_TIMEOUT_MS });
+        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 };
       };
-      for (const end of [input.from, input.to])
-        if (end.locator !== void 0) await this.guard({ action: "drag", locator: this.locator(end.locator).first() });
       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 });
       await page.mouse.up();
+      this.mouse = to;
       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 });
     }
@@ -636,28 +1139,65 @@ var PlaywrightOperationExecutor = class {
       return this.success(call.operation, box);
     }
     if (call.operation === "browser.press" && !locator) {
-      await this.guard({ action: "press", locator: page.locator("*:focus").first(), value: input.key });
+      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 guarded = call.operation === "browser.select" ? "select" : call.operation.slice("browser.".length);
-    await this.guard({
-      action: guarded,
-      locator: target.first(),
-      ...call.operation === "browser.fill" ? { value: input.value } : call.operation === "browser.press" ? { value: input.key } : call.operation === "browser.select" ? { value: input.values } : {}
-    });
+    const guardedAction = call.operation === "browser.select" ? "select" : call.operation.slice("browser.".length);
+    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" ? 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);
-    if (call.operation === "browser.click") await this.act(target, "click", () => target.click({ timeout }));
-    else if (call.operation === "browser.fill") await this.act(target, "fill", () => target.fill(input.value, { timeout }));
-    else if (call.operation === "browser.press") await this.act(target, "press", () => target.press(input.key, { timeout }));
-    else if (call.operation === "browser.hover") await this.act(target, "hover", () => target.hover({ timeout }));
-    else if (call.operation === "browser.focus") await this.act(target, "focus", () => target.focus({ timeout }));
-    else if (call.operation === "browser.check") await this.act(target, "check", () => target.check({ timeout }));
-    else if (call.operation === "browser.uncheck") await this.act(target, "uncheck", () => target.uncheck({ timeout }));
-    else if (call.operation === "browser.select") {
-      const values = await this.act(target, "selectOption", () => target.selectOption(input.values, { timeout }));
-      return this.success(call.operation, { values });
+    try {
+      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", 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);
     const inspection = after ?? before;
@@ -681,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);
         })
@@ -694,7 +1235,7 @@ var PlaywrightOperationExecutor = class {
       });
     } finally {
       clearTimeout(timer);
-      this.page.removeAllListeners();
+      await scope.close(this.page);
     }
   }
   async target() {
@@ -725,6 +1266,17 @@ function operationName(raw) {
   const candidate = raw && typeof raw === "object" && !Array.isArray(raw) ? raw.operation : void 0;
   return typeof candidate === "string" && BROWSER_OPERATION_NAMES.includes(candidate) ? candidate : "browser.status";
 }
+function bind(locator) {
+  return {
+    click: locator.click.bind(locator),
+    fill: locator.fill.bind(locator),
+    press: locator.press.bind(locator),
+    hover: locator.hover.bind(locator),
+    check: locator.check.bind(locator),
+    uncheck: locator.uncheck.bind(locator),
+    selectOption: locator.selectOption.bind(locator)
+  };
+}
 
 // src/provider.ts
 import { timingSafeEqual } from "node:crypto";