effect-browser 0.2.0-beta.9 → 0.3.0-beta.10

package/src/internal/input/guard.ts

@@ -0,0 +1,184 @@
+/**
+ * The input guard's host side. It asks the page what an action would touch, builds the request a
+ * policy decides on, binds an approval to the document and targets it saw, and runs the page
+ * script's changes in the approved document only.
+ */
+import { Effect } from "effect";
+
+import { type BrowserError, InvalidRequest, NotActionable, StaleRef } from "../../BrowserError.ts";
+import { InputRequest, redacted } from "../../Page.ts";
+import { type Bridge, scriptCall } from "../page/bridge.ts";
+import { contextGone, decodeWith, failWith, type PageContext } from "../page/context.ts";
+import * as Url from "../page/url.ts";
+import * as Script from "./guard.inpage.ts";
+
+export interface Approval {
+  readonly contextId: number;
+  readonly check: (options?: Script.ValidationOptions) => Effect.Effect<void, BrowserError>;
+}
+
+export interface PolicyPlan {
+  readonly request: InputRequest;
+  readonly validate: Effect.Effect<Approval, BrowserError>;
+}
+
+// A ref that names nothing is stale on every path, named by the target that failed.
+export const inputFailure = (
+  operation: string,
+  targets: Script.InputPlan["targets"],
+  failure: Script.InputFailure,
+) => {
+  const target = failure.index === undefined ? undefined : targets[failure.index];
+
+  return failWith(
+    operation,
+    failure.error === "outside"
+      ? new InvalidRequest({ detail: failure.detail })
+      : failure.error === "stale" && typeof target === "string"
+        ? new StaleRef({ ref: target })
+        : new NotActionable({ detail: failure.detail }),
+  );
+};
+
+export const editFailure = (
+  operation: string,
+  ref: string,
+  failure: { readonly error: string; readonly stale?: boolean | undefined },
+) =>
+  failWith(
+    operation,
+    failure.stale === true ? new StaleRef({ ref }) : new NotActionable({ detail: failure.error }),
+  );
+
+export const make = (page: PageContext, bridge: Bridge) => {
+  const { id } = page;
+  const { current, evaluateIn, evaluateWithContext } = bridge;
+
+  const preparePolicy = (
+    action: string,
+    info: { readonly target?: string | undefined; readonly text?: string | undefined },
+    targets: Script.InputPlan["targets"],
+    flags: {
+      readonly submit?: boolean;
+      readonly keys?: string;
+      readonly destination?: string;
+    } = {},
+  ): Effect.Effect<PolicyPlan, BrowserError> =>
+    Effect.gen(function* () {
+      for (const target of targets) {
+        if (typeof target === "string" && !/^e\d+$/.test(target))
+          return yield* failWith(
+            action,
+            new InvalidRequest({ detail: `"${target}" is not a ref; refs look like e12` }),
+          );
+        if (
+          target !== null &&
+          typeof target !== "string" &&
+          (!Number.isFinite(target.x) || !Number.isFinite(target.y))
+        )
+          return yield* failWith(
+            action,
+            new InvalidRequest({ detail: "point coordinates must be finite" }),
+          );
+      }
+
+      const input: Script.InputPlan = {
+        action,
+        targets,
+        submit: flags.submit ?? false,
+        keys: flags.keys ?? null,
+        destination: flags.destination ?? null,
+      };
+
+      const { contextId, value } = yield* evaluateWithContext(
+        action,
+        scriptCall("prepareInput", input),
+      );
+
+      const prepared = yield* decodeWith(action, Script.PreparedInputResultSchema)(value);
+
+      if ("error" in prepared) return yield* inputFailure(action, targets, prepared);
+      const first = prepared.targets[0];
+      const target = targets[0];
+      const { title, description, dialog, heading, nearby, form } = prepared.evidence;
+
+      // A guard may hand the request to a judge's model, so its addresses keep no secrets.
+      const request = new InputRequest({
+        page: id,
+        url: Url.redact(prepared.url),
+        title,
+        action,
+        target: info.target,
+        text:
+          info.text !== undefined && action === "type" && first?.secret === true
+            ? redacted
+            : info.text,
+        element: first?.element,
+        role: first?.role,
+        name: first?.name,
+        description,
+        href: first?.href === undefined ? undefined : Url.redact(first.href),
+        point: target !== null && typeof target === "object" ? target : undefined,
+        destination:
+          prepared.destination === undefined ? undefined : Url.redact(prepared.destination),
+        facts: prepared.facts,
+        context: { dialog, heading, nearby },
+        form,
+      });
+
+      const check = (options: Script.ValidationOptions = {}) =>
+        evaluateIn(action, scriptCall("validateInput", input, prepared, options), contextId).pipe(
+          Effect.catchIf(contextGone, () =>
+            failWith(
+              action,
+              new NotActionable({ detail: "the page changed while input policy was pending" }),
+            ),
+          ),
+          Effect.flatMap(decodeWith(action, Script.ValidatedInputResultSchema)),
+          Effect.flatMap((result) =>
+            "error" in result ? inputFailure(action, targets, result) : Effect.void,
+          ),
+        );
+
+      const validate = check().pipe(
+        Effect.as<Approval>({
+          contextId,
+          check,
+        }),
+      );
+
+      return { request, validate };
+    });
+
+  // `mayHaveRun` hears of a failure or interruption after the script may have started. A known
+  // missing context or API means it never ran; acquiring the context itself sends no mutation.
+  const mutate = (
+    operation: string,
+    call: string,
+    approval: Approval | undefined,
+    mayHaveRun: Effect.Effect<void> = Effect.void,
+  ) =>
+    (approval === undefined ? current(operation) : Effect.succeed(approval.contextId)).pipe(
+      Effect.flatMap((contextId) =>
+        evaluateIn(operation, call, contextId).pipe(
+          Effect.onInterrupt(() => mayHaveRun),
+          Effect.tapError((error) =>
+            error.reason._tag === "Failed" &&
+            /Cannot find context|__effectBrowser/i.test(error.reason.detail)
+              ? Effect.void
+              : mayHaveRun,
+          ),
+        ),
+      ),
+      Effect.catchIf(contextGone, () =>
+        failWith(
+          operation,
+          new NotActionable({ detail: "the page changed before the approved input could run" }),
+        ),
+      ),
+    );
+
+  return { preparePolicy, mutate };
+};
+
+export type Guard = ReturnType<typeof make>;

package/src/internal/input/keyboard.ts

@@ -0,0 +1,112 @@
+/**
+ * Keys and typing: a key chord held and released, each typed event, and the document a run of
+ * keys must stay in.
+ */
+import { Duration, Effect } from "effect";
+
+import { NotActionable } from "../../BrowserError.ts";
+import type { Bridge } from "../page/bridge.ts";
+import { failWith, type PageContext } from "../page/context.ts";
+import type { Dispatch } from "./dispatch.ts";
+import * as Keys from "./keys.ts";
+import type * as Replies from "./replies.ts";
+
+export const make = (page: PageContext, bridge: Bridge, dispatch: Dispatch) => {
+  const { playwright } = page;
+  const { send } = page.protocol;
+  const { currentDocument } = bridge;
+  const { stamp, inputCall, dispatchKey, dispatchText } = dispatch;
+
+  // A multi-key action stops before its next key once the page has moved to another document. The
+  // page's own session counts main-frame commits as the browser reports them, so a key sent within
+  // about one protocol round trip of a commit can still reach the new document.
+  const sameDocument = (operation: string, since: number) =>
+    currentDocument(operation).pipe(
+      Effect.flatMap((now) =>
+        now === since
+          ? Effect.void
+          : failWith(
+              operation,
+              new NotActionable({
+                detail: "the page moved to another document, so the remaining keys were not sent",
+              }),
+            ),
+      ),
+    );
+
+  const keyStroke = (
+    operation: string,
+    run: Replies.Run,
+    parts: ReadonlyArray<string>,
+    holdMillis = 0,
+  ) =>
+    Effect.gen(function* () {
+      yield* inputCall(operation, run.reserve(parts.length * 2));
+      for (const part of parts)
+        yield* inputCall(
+          operation,
+          run.down(
+            `playwright:${part}`,
+            () => dispatchKey(part, "down", () => playwright.keyboard.down(part), run),
+            () => dispatchKey(part, "up", () => playwright.keyboard.up(part), run),
+          ),
+        );
+      if (holdMillis > 0) yield* Effect.sleep(Duration.millis(holdMillis));
+      for (const part of parts.toReversed())
+        yield* inputCall(operation, run.up(`playwright:${part}`));
+    });
+
+  const typeEvent = (
+    run: Replies.Run,
+    event: { readonly phase: "down" | "up" | "insert"; readonly key: string },
+    secret: boolean,
+  ) =>
+    inputCall(
+      "type",
+      Effect.gen(function* () {
+        if (event.phase === "insert") {
+          yield* run.reserve(1);
+          yield* run.send(() => dispatchText(event.key, secret));
+
+          return;
+        }
+
+        const description = Keys.description(event.key);
+
+        if (description === undefined) return yield* Effect.die("invalid planned key");
+        const { key, code, keyCode, text } = description;
+        const held = "raw:" + code;
+
+        if (event.phase === "up") return yield* run.up(held);
+
+        // The key going down carries its text; going up, only the key.
+        const keyEvent = (phase: "down" | "up") => () =>
+          dispatchKey(
+            key,
+            phase,
+            (at, estimate) =>
+              send("Input.dispatchKeyEvent", {
+                type: phase === "down" ? "keyDown" : "keyUp",
+                ...stamp(estimate, at),
+                modifiers: 0,
+                windowsVirtualKeyCode: keyCode,
+                code,
+                key,
+                location: 0,
+                ...(phase === "down"
+                  ? { commands: [], text, unmodifiedText: text, autoRepeat: false, isKeypad: false }
+                  : {}),
+              }),
+            run,
+            secret,
+          );
+
+        yield* run.reserve(2);
+        yield* run.down(held, keyEvent("down"), keyEvent("up"));
+      }),
+    );
+
+  return { currentDocument, sameDocument, keyStroke, typeEvent };
+};
+
+export type Keyboard = ReturnType<typeof make>;

package/src/internal/input/keys.ts

@@ -0,0 +1,127 @@
+/**
+ * Key aliases for Playwright and printable US key descriptions for pipelined Chromium typing.
+ */
+
+const aliases: Record<string, string> = {
+  ctrl: "Control",
+  control: "Control",
+  cmd: "Meta",
+  command: "Meta",
+  meta: "Meta",
+  win: "Meta",
+  super: "Meta",
+  mod: "ControlOrMeta",
+  alt: "Alt",
+  option: "Alt",
+  shift: "Shift",
+  enter: "Enter",
+  return: "Enter",
+  esc: "Escape",
+  escape: "Escape",
+  tab: "Tab",
+  space: "Space",
+  spacebar: "Space",
+  " ": "Space",
+  backspace: "Backspace",
+  delete: "Delete",
+  del: "Delete",
+  insert: "Insert",
+  home: "Home",
+  end: "End",
+  pageup: "PageUp",
+  pagedown: "PageDown",
+  up: "ArrowUp",
+  down: "ArrowDown",
+  left: "ArrowLeft",
+  right: "ArrowRight",
+  arrowup: "ArrowUp",
+  arrowdown: "ArrowDown",
+  arrowleft: "ArrowLeft",
+  arrowright: "ArrowRight",
+};
+
+const named = new Set(Object.values(aliases));
+
+/** Parse and validate the whole chord before sending any down events. */
+export const parts = (keys: string): ReadonlyArray<string> | undefined => {
+  const tokens: Array<string> = [];
+  let building = "";
+
+  // Like Playwright, a plus without a preceding token is the literal plus key: Control++.
+  for (const character of keys) {
+    if (character === "+" && building.trim() !== "") {
+      tokens.push(building);
+      building = "";
+    } else building += character;
+  }
+  tokens.push(building);
+  if (tokens.length > 4) return undefined;
+  const out: Array<string> = [];
+
+  for (const token of tokens) {
+    const part = token === " " ? "Space" : token.trim();
+    const lower = part.toLowerCase();
+    const alias = Object.hasOwn(aliases, lower) ? aliases[lower] : undefined;
+
+    if (alias !== undefined) out.push(alias);
+    else if (
+      named.has(part) ||
+      /^F([1-9]|1[0-2])$/.test(part) ||
+      /^(Key[A-Z]|Digit[0-9]|Numpad[0-9])$/.test(part) ||
+      description(part) !== undefined
+    )
+      out.push(part);
+    else return undefined;
+  }
+
+  return out;
+};
+
+interface Description {
+  readonly code: string;
+  readonly keyCode: number;
+  readonly key: string;
+  readonly text: string;
+}
+
+const punctuation: ReadonlyArray<readonly [string, string, number]> = [
+  ["`~", "Backquote", 192],
+  ["-_", "Minus", 189],
+  ["=+", "Equal", 187],
+  ["\\|", "Backslash", 220],
+  ["[{", "BracketLeft", 219],
+  ["]}", "BracketRight", 221],
+  [";:", "Semicolon", 186],
+  ["'\"", "Quote", 222],
+  [",<", "Comma", 188],
+  [".>", "Period", 190],
+  ["/?", "Slash", 191],
+  [" ", "Space", 32],
+];
+
+/**
+ * Match Playwright's pinned US layout for literal typing. Uppercase and shifted punctuation
+ * carry their literal text without synthesizing Shift. Newlines also use insertText so a text
+ * payload cannot submit a form; only an explicit Enter or submit option may do that.
+ */
+export const description = (character: string): Description | undefined => {
+  // Prose correction uses the same raw key path so its deletion has a matched release.
+  if (character === "Backspace")
+    return { code: "Backspace", keyCode: 8, key: "Backspace", text: "" };
+  if (character.length !== 1) return undefined;
+  if (/^[A-Za-z]$/.test(character)) {
+    const upper = character.toUpperCase();
+
+    return { code: `Key${upper}`, keyCode: upper.charCodeAt(0), key: character, text: character };
+  }
+  const digit = "0123456789".indexOf(character);
+  const number = digit === -1 ? ")!@#$%^&*(".indexOf(character) : digit;
+
+  if (number !== -1)
+    return { code: `Digit${number}`, keyCode: 48 + number, key: character, text: character };
+  const symbol = punctuation.find(([characters]) => characters.includes(character));
+
+  return symbol === undefined
+    ? undefined
+    : { code: symbol[1], keyCode: symbol[2], key: character, text: character };
+};