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

package/README.md

@@ -130,34 +130,45 @@ 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 element action and before
-each `browser.script` (`{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 element actions guards scripts as a
-whole.
-
-An element action (`click`, `fill`, `press`, `hover`, `focus`, `check`,
-`uncheck`, `select`, `drag`, and the coordinate actions `mousedown`, `mouseup`,
-`wheel`) carries a `target`, described from the browser side:
-
-- A locator is resolved once, waiting up to the action budget (5 s), so an
-  element that renders late is guarded, not skipped. The guard sees that
-  element and the action then runs on the same element handle.
-- A coordinate action (`browser.mouse` click/down/up/move, `browser.drag` from
-  or to x/y, `browser.wheel` at the mouse's position) is guarded on the element
-  at that point.
-- The elements are found in an isolated world the page's scripts cannot reach
-  (the element's exact box, open shadow roots included; for a point,
-  `elementFromPoint`), then described over CDP from each backend node:
-  `DOM.describeNode` for tag and attributes, `Accessibility.getPartialAXTree`
-  for role, name and accessibility ancestors. A page cannot change what the
-  guard reads by overriding DOM functions. Over AlmostCDP the CDP endpoint
-  itself runs in the page, so there the description is only as trustworthy as
-  the page's world.
-- A target that cannot be resolved or described (inside an embedded frame or a
-  closed shadow root, without a box, or a CDP failure) refuses the action with
-  `UNSUPPORTED`; the guard is never skipped.
+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

package/dist/executor.d.ts

@@ -41,9 +41,26 @@ export interface PlaywrightOperationExecutorOptions {
      * 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 = PlaywrightElementAction | PlaywrightScriptAction;
+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 {
@@ -51,6 +68,12 @@ export interface PlaywrightElementAction {
     /** 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`. */
@@ -71,7 +94,12 @@ export declare class PlaywrightOperationExecutor {
     private readonly options;
     private readonly ready;
     private readonly 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.
+     */
     private mouse;
     constructor(page: Page, options: PlaywrightOperationExecutorOptions);
     execute(raw: unknown): Promise<BrowserOperationResult>;
@@ -95,7 +123,18 @@ export declare class PlaywrightOperationExecutor {
      * action runs on the locator. Resolution or description failing refuses.
      */
     private guarded;
-    /** Asks the host's policy about the element at a viewport point. */
+    /** 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;