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

package/README.md

@@ -58,7 +58,8 @@ Both carry the same envelope, `{protocol, id, token, call}` in and
 
 - **TCP** is the wire the harness speaks (`crates/harness/src/browser.rs`): one
   newline-terminated JSON request per connection, one JSON response, then the
-  provider closes. The provider listens on `127.0.0.1` and writes an owner-only
+  provider closes. A provider waiting for the person may first write
+  `{protocol, id, pending}` lines; each extends the harness's wait to 120 s. The provider listens on `127.0.0.1` and writes an owner-only
   discovery record (file `0600`, directory `0700`) to
   `<providers dir>/browser/playwright.cdp.<port>.json`, scoped to the
   canonical workspace, and removes it on stop.
@@ -129,15 +130,48 @@ Two entry points use no Node API:
   `@volter/almostcdp/playwright`, and answers the operations against an
   AlmostCDP surface with no Node process.
 
-A host's `actionGuard(action)` is asked before each locator action (`click`,
-`fill`, `press`, `hover`, `focus`, `check`, `uncheck`, `select`, `drag`) with
-the action's `Locator` and value, and before each `browser.script` with
-`{action: "script", source, args}`; throwing a `BrowserActionRefusal` answers
-the call with its code, such as `APPROVAL_REQUIRED`. A script's own locator
-calls are the real `page`'s and are not asked again, so a host that guards
-locator actions guards scripts as a whole.
+A host's `actionGuard(action)` is asked before every action that can change the
+page or send it input, and before each `browser.script` (`{action: "script", source,
+args}`); throwing a `BrowserActionRefusal` answers the call with its code, such as
+`APPROVAL_REQUIRED`. Reading (status, snapshot, query, wait, box) is not asked;
+`hover` is asked like any element action, and moving the mouse is not.
+
+- Element actions (`click`, `fill`, `press`, `hover`, `focus`, `check`, `uncheck`,
+  `select`) carry a `target` described from the browser side. The locator is
+  resolved once (waiting up to 5 s) and the action runs on that same element
+  handle. The handle must be in the page's main frame and must be one of the
+  elements found at its box in an isolated world (a one-off marker attribute on
+  the handle confirms it); each is described over CDP (`DOM.describeNode` for tag
+  and attributes, `Accessibility.getPartialAXTree` for role, name and ancestors,
+  plus its form membership and, when unnamed, its own text). An element in a
+  `<label>` brings the control the label forwards to. A locator that resolves in
+  another frame, to a frame, or to a box more than eight elements share is refused.
+  A `select` carries the chosen options' labels and values.
+- A locator `press` focuses its element and is refused unless focus is then on or
+  inside it; a press without a locator is described from the focused element and
+  refused inside a frame or a closed shadow root.
+- Raw pointer input (`browser.mouse` click/down/up, `browser.wheel`,
+  `browser.drag`) carries `pointer: true` and the element at the point as best
+  known (`target.unidentified` says why when it cannot be told); a drag carries
+  both points and the element at the drop point. The mouse is moved to the point
+  before every down, up and wheel. After a locator action the position is that
+  element's box centre, or unknown, and a press then needs coordinates.
+- `back`, `forward`, `reload` and `scroll` are page actions (`{action, url}`).
+- Just before any input is dispatched, the executor confirms the page's main frame
+  still holds the document the action was checked on (its `loaderId` and URL) with
+  no navigation requested or loading (a navigation counts as settled once its
+  document commits, it moves within the document, loading stops, as for a 204
+  answer, or it becomes a download), then calls the host's `beforeInput({url})`;
+  a change refuses the action with `STALE_PAGE` and nothing is sent. A pointer
+  action on a locator first waits for its element in a trial run, so the
+  confirmation comes as late as it can.
+
+A script gets the page through a membrane. When the script ends or its time runs
+out, every later call through it throws, and the routes, exposed bindings and
+functions, init scripts and listeners it installed are removed.
 
 A host's `snapshotExclude` is a CSS selector for its own elements in the page
 (an overlay, a launcher): `browser.snapshot` leaves out the nodes of every
-element it matches, found by their aria refs, and a node left empty by that.
-The page is not changed, so assistive technology still reads those elements.
+element it matches, found by their aria refs, and a node left empty by that,
+and a coordinate action that lands on one is refused with `UNSUPPORTED`. The
+page is not changed, so assistive technology still reads those elements.

package/dist/executor.d.ts

@@ -4,7 +4,8 @@
  * over CDP. No Node API is used, so the executor also runs in a browser realm
  * with a browser build of playwright-core (`@volter/almostcdp/playwright`).
  */
-import { type Locator, type Page } from "playwright-core";
+import { type Page } from "playwright-core";
+import { type GuardedTarget } from "./guard.js";
 import { type BrowserOperationErrorCode, type BrowserOperationResult } from "./protocol.js";
 /** The implementation this provider reports; the pinned playwright-core. */
 export declare const PLAYWRIGHT_IMPLEMENTATION = "playwright-core 1.63.0";
@@ -23,25 +24,56 @@ export interface PlaywrightOperationExecutorOptions {
     endpoint: string;
     /**
      * The host's policy for one action, asked before it runs: each locator
-     * action, and each `browser.script` before its source is compiled. Throwing
-     * a `BrowserActionRefusal` refuses the operation with that code.
+     * action, each coordinate action (`browser.mouse`, `browser.drag`,
+     * `browser.wheel`), and each `browser.script` before its source is
+     * compiled. An element action's target is resolved once, described from the
+     * browser side (see `GuardedTarget`), and the action then runs on that same
+     * element. A target that cannot be resolved or described refuses the
+     * operation without asking. Throwing a `BrowserActionRefusal` refuses the
+     * operation with that code.
      */
     actionGuard?: (action: PlaywrightAction) => void | Promise<void>;
     /**
-     * A CSS selector (Playwright's, which pierces open shadow roots) for the
-     * host's own elements: `browser.snapshot` leaves out every matching
-     * element's nodes, and a node left with nothing by that. The page itself is
-     * not changed, so what assistive technology reads stays the same.
+     * A CSS selector for the host's own elements: `browser.snapshot` leaves out
+     * every matching element's nodes (Playwright's selector, which pierces open
+     * shadow roots), and a coordinate action that lands on one is refused. The
+     * page itself is not changed, so what assistive technology reads stays the
+     * same.
      */
     snapshotExclude?: string;
+    /**
+     * The host's last check just before input is dispatched to the page, after
+     * the executor has confirmed the main frame still holds the checked
+     * document with no navigation in flight. `url` is the page URL the action
+     * was checked on. Throwing a `BrowserActionRefusal` refuses the action; no
+     * input has been sent.
+     */
+    beforeInput?: (checked: {
+        url: string;
+    }) => void | Promise<void>;
 }
 /** One action an operation is about to perform. */
-export type PlaywrightAction = PlaywrightLocatorAction | PlaywrightScriptAction;
-/** A locator action. */
-export interface PlaywrightLocatorAction {
-    action: "click" | "fill" | "press" | "hover" | "focus" | "check" | "uncheck" | "select" | "drag";
-    locator: Locator;
+export type PlaywrightAction = PlaywrightElementAction | PlaywrightPageAction | PlaywrightScriptAction;
+/** An action on the page as a whole: history navigation, reload, scrolling. */
+export interface PlaywrightPageAction {
+    action: "back" | "forward" | "reload" | "scroll";
+    /** The page's URL when the action was asked about. */
+    url: string;
+    value?: unknown;
+}
+export type { GuardedNode, GuardedTarget } from "./guard.js";
+/** An action that lands on an element: by locator, or at a viewport point. */
+export interface PlaywrightElementAction {
+    action: "click" | "fill" | "press" | "hover" | "focus" | "check" | "uncheck" | "select" | "drag" | "mousedown" | "mouseup" | "wheel";
+    /** What the action lands on, described from the browser side. */
+    target: GuardedTarget;
     value?: unknown;
+    /**
+     * Raw pointer input (`browser.mouse` down/up/click, `browser.wheel`,
+     * `browser.drag`): the target is the element at `target.point` as best
+     * known, which a page can change between the look and the press.
+     */
+    pointer?: boolean;
 }
 export interface PlaywrightScriptAction {
     /** `browser.script`: the author's source, run with the real `page`. */
@@ -61,6 +93,14 @@ export declare class PlaywrightOperationExecutor {
     private readonly page;
     private readonly options;
     private readonly ready;
+    private readonly 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.
+     */
+    private mouse;
     constructor(page: Page, options: PlaywrightOperationExecutorOptions);
     execute(raw: unknown): Promise<BrowserOperationResult>;
     private locator;
@@ -76,8 +116,28 @@ export declare class PlaywrightOperationExecutor {
     private inspect;
     /** Run a locator action; a failure on a locator that matches nothing is NOT_FOUND. */
     private act;
-    /** The host's policy for an action; an element that is not there is the action's own failure. */
-    private guard;
+    /**
+     * 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.
+     */
+    private guarded;
+    /** The document an action is checked on; input later goes only to it. */
+    private checkpoint;
+    /** Just before input: the same document, no navigation in flight, and the host's own last check. */
+    private dispatching;
+    /** The page-level action's guard. */
+    private guardPage;
+    /** The pointer's position for a press that names none; unknown after a locator action. */
+    private pointer;
+    /**
+     * 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).
+     */
+    private guardPoint;
+    /** A browser-side description, or the refusal that replaces the action. */
+    private describe;
     /** The aria refs of the elements `snapshotExclude` matches, and of their contents. */
     private excludedRefs;
     private revision;