@itmetsam/samurai-framework 0.10.0 → 0.12.1

package/dist/recorder/toolbar/controller-fixture.js

@@ -0,0 +1,129 @@
+import assert from "node:assert/strict";
+import { ElementHandle } from "../../script/element-handle.js";
+import { ToolbarController } from "./controller.js";
+export const SECRET = "hunter2-very-secret";
+export const NEW_SECRET = "n3w-s3cr3t-value";
+const OPTIONS = {
+    environment: "dev",
+    canAddVariables: true,
+    variables: { testUser: "dev@example.com", retries: 3 },
+    secrets: { ADMIN_PASSWORD: SECRET, API_TOKEN: undefined },
+    secretsIgnored: true,
+    screenshots: 0,
+};
+export const TARGET = new ElementHandle("el-1");
+export const CANDIDATES = [
+    { method: "getByRole", role: "textbox", name: "Email" },
+];
+export const LOCATOR = { chain: [CANDIDATES[0]], fallbacks: [] };
+export const COUNT_CALL = {
+    method: "getByRole",
+    role: "listitem",
+};
+export const INFO = {
+    ok: true,
+    label: `textbox "Email"`,
+    text: "",
+    value: "a@b.c",
+    attributes: [{ name: "id", value: "email" }],
+    first: { matcher: "toHaveValue", expected: "a@b.c" },
+    counts: [{ label: "listitem", count: 3 }],
+};
+export const lastOf = (items) => items[items.length - 1];
+export const msg = (message) => ({ type: "toolbar", ...message });
+export const insert = (id, kind, name) => msg({
+    action: "insert",
+    id,
+    target: TARGET,
+    candidates: CANDIDATES,
+    kind,
+    name,
+});
+export const add = (id, kind, name, value) => msg({
+    action: "add-insertable",
+    id,
+    target: TARGET,
+    candidates: CANDIDATES,
+    kind,
+    name,
+    value,
+});
+export const pick = (id) => msg({ action: "pick", id, target: TARGET, candidates: CANDIDATES });
+/** A controller over fakes that record everything */
+export function setup(options = {}, overrides = {}) {
+    const pushes = [];
+    const replies = [];
+    const observed = [];
+    const statuses = [];
+    const calls = [];
+    const page = { url: "http://localhost/a" };
+    let controller;
+    const deps = {
+        push: (state) => pushes.push(structuredClone(state)),
+        reply: (id, result) => replies.push({ id, result: structuredClone(result) }),
+        currentUrl: async () => page.url,
+        rank: async () => LOCATOR,
+        inspect: async () => ({
+            info: INFO,
+            counts: [COUNT_CALL],
+        }),
+        type: async (_locator, value) => {
+            calls.push(`type ${value}`);
+        },
+        mute: async () => {
+            calls.push("mute");
+        },
+        unmute: async () => {
+            calls.push("unmute");
+        },
+        addVariable: async (name, value) => {
+            calls.push(`addVariable ${name}=${value}`);
+        },
+        setSecret: async (name, value) => {
+            calls.push(`setSecret ${name}=${value}`);
+        },
+        secretAdded: (name) => {
+            calls.push(`secretAdded ${name}`);
+        },
+        // As the recorder does: an observation becomes a step, which is counted
+        observe: (observation) => {
+            observed.push(observation);
+            controller.stepAdded(observation.type === "screenshot"
+                ? {
+                    kind: "screenshot",
+                    name: observation.name,
+                    fullPage: observation.fullPage,
+                }
+                : { kind: "waitForNetworkIdle" });
+        },
+        stop: () => {
+            calls.push("stop");
+        },
+        onStatus: (status) => statuses.push(status),
+        ...overrides,
+    };
+    controller = new ToolbarController(deps, { ...OPTIONS, ...options });
+    const last = () => lastOf(pushes);
+    const noSecretLeaks = () => {
+        const sent = JSON.stringify(pushes) + JSON.stringify(replies);
+        assert.ok(!sent.includes(SECRET), "a secret value reached the page");
+        assert.ok(!sent.includes(NEW_SECRET), "a new secret value reached the page");
+    };
+    return {
+        controller,
+        pushes,
+        replies,
+        observed,
+        statuses,
+        calls,
+        page,
+        last,
+        noSecretLeaks,
+    };
+}
+/** Deps whose `type` fails, as a field that can't be typed into does */
+export const failingType = {
+    type: async () => {
+        throw new Error("not editable");
+    },
+};

package/dist/recorder/toolbar/controller.d.ts

@@ -1,51 +1,10 @@
-import type { ElementHandle } from "../../script/element-handle.js";
-import type { LocatorCall, LocatorSpec, Step } from "../../steps/model.js";
-import { type Observation } from "../normalise.js";
-import type { ActionReply, PickInfo, ToolbarMessage, ToolbarState } from "./protocol.js";
-/** What `inspect` found for a picked element: the reply, and the locator behind each Count choice */
-export interface Inspection {
-    info: PickInfo & {
-        ok: true;
-    };
-    /** `counts[i]` is the locator `info.counts[i]` describes */
-    counts: LocatorCall[];
-}
-/** Everything the controller does to the browser and the project; the recorder implements these */
-export interface ControllerDeps {
-    /** Sends the state to every loaded top-level document's toolbar */
-    push(state: ToolbarState): void;
-    reply(id: number, result: PickInfo | ActionReply): void;
-    currentUrl(): Promise<string>;
-    rank(target: ElementHandle, candidates: LocatorCall[]): Promise<LocatorSpec | undefined>;
-    inspect(target: ElementHandle, locator: LocatorSpec, candidates: LocatorCall[]): Promise<Inspection>;
-    /** Types into the field with capture muted */
-    type(locator: LocatorSpec, value: string): Promise<void>;
-    mute(): Promise<void>;
-    unmute(): Promise<void>;
-    addVariable(name: string, value: string): Promise<void>;
-    setSecret(name: string, value: string): Promise<void>;
-    /** A secret was written to the project (called before its value is typed) */
-    secretAdded(name: string): void;
-    observe(observation: Observation): void;
-    stop(): void;
-    onStatus(status: {
-        state: "recording" | "paused";
-        toolbar: boolean;
-    }): void;
-}
-export interface ControllerOptions {
-    environment: string;
-    canAddVariables: boolean;
-    variables: Record<string, string | number | boolean>;
-    /** Name → value; undefined when not set */
-    secrets: Record<string, string | undefined>;
-    secretsIgnored: boolean;
-    /** Screenshot steps already in the test, for the default name */
-    screenshots: number;
-}
-type Message = ToolbarMessage & {
-    target?: ElementHandle;
-};
+import type { Step } from "../../steps/model.js";
+import type { ControllerDeps, ControllerOptions, Message } from "./types.js";
+/**
+ * The recorder's side of the toolbar: owns its state (pause, the rail, the environment's variables and
+ * secrets) and turns its messages into observations. Secret values stay here; the page only ever gets
+ * their names and whether they are set.
+ */
 export declare class ToolbarController {
     private readonly deps;
     private readonly options;
@@ -64,24 +23,17 @@ export declare class ToolbarController {
     private savingName;
     private warnings;
     private warningId;
-    /** The picked element an `assert` with the same id refers to */
     private pick;
-    /** Ids of `assert`, `insert` and `add-insertable` being processed */
-    private readonly inFlight;
-    /** Ids `accept` let through whose `handle` hasn't started yet */
-    private readonly claimed;
-    /** Ids answered `{ ok: true }`: their step exists, a repeat is a double click */
-    private readonly done;
-    /** Bumped on every page load: work started for an older page is not answered */
-    private page;
-    /** Wake-ups for the work that is waiting on the current page: called, and forgotten, when the page changes */
-    private pageGone;
+    private readonly guard;
+    private readonly scope;
     private toolbar;
     /** A `ready` arrived since the last load: it counts for the next one */
     private readySinceLoad;
     private watchdog;
     private disposed;
     constructor(deps: ControllerDeps, options: ControllerOptions);
+    /** What the action handlers (assert, insert, add) use of this controller */
+    private readonly actions;
     get paused(): boolean;
     private state;
     private push;
@@ -101,10 +53,6 @@ export declare class ToolbarController {
      * and doesn't count for the coming load
      */
     navigating(): void;
-    /** Lets what waits on the current document stop waiting: its commands may never be answered once it is gone */
-    private leavePage;
-    /** Runs `work`, but stops waiting for it when the page is left; resolves `gone` then */
-    private whileOnPage;
     /** A step was emitted (any source): count it */
     stepAdded(step: Step): void;
     /** A recorded step was taken out again (a cancelled file picker's click) */
@@ -120,7 +68,6 @@ export declare class ToolbarController {
     private pause;
     private resume;
     private answer;
-    /** Runs an action that expects a reply; a second one with the same id while the first runs is dropped */
     /**
      * Whether to process `message`; call it as the message arrives, before queueing it. An `assert`, `insert` or
      * `add-insertable` whose id is in flight or was already answered `{ ok: true }` is a double click and is
@@ -128,19 +75,6 @@ export declare class ToolbarController {
      */
     accept(message: Message): boolean;
     /** Runs an action that expects a reply, unless it is a repeat (see `accept`) */
-    private once;
+    private replying;
     private picked;
-    /**
-     * A field may hold an inserted secret: its value (and any text or attribute equal to a secret) is left out,
-     * and the first matcher follows the Alt+click rule without a value, so neither the page nor the spec gets it.
-     */
-    private withoutSecrets;
-    private assert;
-    private insert;
-    private addInsertable;
-    /** Undefined when `work` succeeded, else the reply for its error */
-    private write;
-    private locate;
-    private typeIn;
 }
-export {};

package/dist/recorder/toolbar/controller.js

@@ -1,29 +1,20 @@
 import { cleanName } from "../../browser/evidence.js";
-import { ConfigEditError } from "../../project/config-edit.js";
-import { SECRET_NAME } from "../../project/secrets-file.js";
-import { ExistsError, VARIABLE_NAME } from "../../project/variables.js";
-import { expectationFor } from "../normalise.js";
+import { ActionGuard } from "./action-guard.js";
+import { assertAction } from "./actions/assert.js";
+import { addInsertableAction, insertAction } from "./actions/insert.js";
+import { withoutSecrets } from "./actions/pick.js";
+import { fail, PAUSED, UNIDENTIFIABLE } from "./actions/reply.js";
+import { LEFT, PageScope } from "./page-scope.js";
 /** A wait for time is 0.1–60 s */
 const WAIT_MIN_MS = 100;
 const WAIT_MAX_MS = 60000;
 /** How long a loaded page's toolbar has to say `ready` */
 const READY_WITHIN = 2000;
-const UNIDENTIFIABLE = "This element can't be identified uniquely";
-const TYPE_FAILED = "Couldn't type into that field";
-const NO_ENVIRONMENT = "This recording has no environment";
-const PAUSED = "Nothing you do now is recorded.";
-const fail = (error, field) => ({
-    ok: false,
-    error,
-    ...(field && { field }),
-});
 /**
  * The recorder's side of the toolbar: owns its state (pause, the rail, the environment's variables and
  * secrets) and turns its messages into observations. Secret values stay here; the page only ever gets
  * their names and whether they are set.
  */
-/** What a wait on the page ends with when the page was left first */
-const LEFT = Symbol("left the page");
 export class ToolbarController {
     constructor(deps, options) {
         this.deps = deps;
@@ -35,16 +26,8 @@ export class ToolbarController {
         this.toastId = 0;
         this.warnings = [];
         this.warningId = 0;
-        /** Ids of `assert`, `insert` and `add-insertable` being processed */
-        this.inFlight = new Set();
-        /** Ids `accept` let through whose `handle` hasn't started yet */
-        this.claimed = new Set();
-        /** Ids answered `{ ok: true }`: their step exists, a repeat is a double click */
-        this.done = new Set();
-        /** Bumped on every page load: work started for an older page is not answered */
-        this.page = 0;
-        /** Wake-ups for the work that is waiting on the current page: called, and forgotten, when the page changes */
-        this.pageGone = new Set();
+        this.guard = new ActionGuard();
+        this.scope = new PageScope();
         this.toolbar = true;
         /** A `ready` arrived since the last load: it counts for the next one */
         this.readySinceLoad = false;
@@ -55,6 +38,19 @@ export class ToolbarController {
             String(value),
         ]));
         this.secrets = new Map(Object.entries(options.secrets));
+        this.actions = {
+            deps,
+            options,
+            variables: this.variables,
+            secrets: this.secrets,
+            isPaused: () => this.paused,
+            pick: () => this.pick,
+            setPick: (pick) => {
+                this.pick = pick;
+            },
+            showToast: (text) => this.showToast(text),
+            push: () => this.push(),
+        };
     }
     get paused() {
         return this.status === "paused";
@@ -140,11 +136,11 @@ export class ToolbarController {
             case "pick":
                 return this.picked(message);
             case "assert":
-                return this.once(message, () => this.assert(message));
+                return this.replying(message, () => assertAction(this.actions, message));
             case "insert":
-                return this.once(message, () => this.insert(message));
+                return this.replying(message, () => insertAction(this.actions, message));
             case "add-insertable":
-                return this.once(message, () => this.addInsertable(message));
+                return this.replying(message, () => addInsertableAction(this.actions, message));
             case "wait":
                 if (this.paused)
                     return;
@@ -176,8 +172,7 @@ export class ToolbarController {
     loaded() {
         if (this.disposed)
             return;
-        this.page++;
-        this.leavePage();
+        this.scope.enter();
         this.pick = undefined;
         this.toast = undefined;
         this.push();
@@ -202,28 +197,7 @@ export class ToolbarController {
      */
     navigating() {
         this.readySinceLoad = false;
-        this.leavePage();
-    }
-    /** Lets what waits on the current document stop waiting: its commands may never be answered once it is gone */
-    leavePage() {
-        const waiting = [...this.pageGone];
-        this.pageGone.clear();
-        for (const wake of waiting)
-            wake();
-    }
-    /** Runs `work`, but stops waiting for it when the page is left; resolves `gone` then */
-    async whileOnPage(work, gone) {
-        let wake;
-        const left = new Promise((resolve) => {
-            wake = () => resolve(gone);
-            this.pageGone.add(wake);
-        });
-        try {
-            return await Promise.race([work(), left]);
-        }
-        finally {
-            this.pageGone.delete(wake);
-        }
+        this.scope.leave();
     }
     /** A step was emitted (any source): count it */
     stepAdded(step) {
@@ -297,229 +271,43 @@ export class ToolbarController {
             this.deps.observe({ type: "goto", url });
         this.push();
     }
-    /** Runs an action that expects a reply; a second one with the same id while the first runs is dropped */
     /**
      * Whether to process `message`; call it as the message arrives, before queueing it. An `assert`, `insert` or
      * `add-insertable` whose id is in flight or was already answered `{ ok: true }` is a double click and is
      * dropped (its first copy answers). A retry after `{ ok: false }` is accepted.
      */
     accept(message) {
-        if (message.action !== "assert" &&
-            message.action !== "insert" &&
-            message.action !== "add-insertable")
-            return true;
-        const { id } = message;
-        if (this.inFlight.has(id) || this.done.has(id))
-            return false;
-        this.inFlight.add(id);
-        this.claimed.add(id);
-        return true;
+        return this.guard.accept(message);
     }
     /** Runs an action that expects a reply, unless it is a repeat (see `accept`) */
-    async once(message, work) {
-        const { id } = message;
-        if (!this.claimed.has(id) && !this.accept(message))
-            return;
-        this.claimed.delete(id);
-        try {
-            const result = await work();
-            if (result.ok)
-                this.done.add(id);
-            this.reply(id, result);
-        }
-        finally {
-            this.inFlight.delete(id);
-        }
+    replying(message, work) {
+        return this.guard.run(message, work, (id, result) => this.reply(id, result));
     }
     async picked(message) {
-        const page = this.page;
+        const page = this.scope.current;
         if (this.paused)
             return this.reply(message.id, fail(PAUSED));
         let found;
         try {
             // Chrome never answers a command into a document that is being replaced, so a pick of the old page must not
             // keep the messages behind it waiting
-            found = await this.whileOnPage(async () => {
+            found = await this.scope.whileOn(async () => {
                 const locator = message.target &&
                     (await this.deps.rank(message.target, message.candidates));
                 if (!locator)
                     return undefined;
                 const inspected = await this.deps.inspect(message.target, locator, message.candidates);
-                if (page === this.page)
+                if (page === this.scope.current)
                     this.pick = { id: message.id, locator, counts: inspected.counts };
                 return inspected;
-            }, LEFT);
+            });
         }
         catch {
             found = undefined; // the element went away while it was inspected
         }
         // The page that asked is gone: its successor's toolbar isn't waiting for this
-        if (found === LEFT || page !== this.page)
+        if (found === LEFT || page !== this.scope.current)
             return;
-        this.reply(message.id, found ? this.withoutSecrets(found.info) : fail(UNIDENTIFIABLE));
-    }
-    /**
-     * A field may hold an inserted secret: its value (and any text or attribute equal to a secret) is left out,
-     * and the first matcher follows the Alt+click rule without a value, so neither the page nor the spec gets it.
-     */
-    withoutSecrets(info) {
-        const values = [...this.secrets.values()].filter((value) => value !== undefined && value !== "");
-        const secret = (text) => text !== undefined && values.some((value) => text.includes(value));
-        if (!secret(info.value) &&
-            !secret(info.text) &&
-            !secret(info.first.expected) &&
-            !info.attributes.some((a) => secret(a.value)))
-            return info;
-        const text = secret(info.text) ? "" : info.text;
-        const first = expectationFor(text, undefined);
-        const { value: _value, ...rest } = info;
-        return {
-            ...rest,
-            text,
-            attributes: info.attributes.filter((a) => !secret(a.value)),
-            first: {
-                matcher: first.matcher,
-                ...("expected" in first && { expected: String(first.expected) }),
-            },
-        };
-    }
-    async assert(message) {
-        if (this.paused)
-            return fail(PAUSED);
-        const pick = this.pick;
-        if (!pick || pick.id !== message.id)
-            return fail("Pick the element again");
-        let locator = pick.locator;
-        let expectation;
-        const expected = String(message.expected ?? "");
-        switch (message.matcher) {
-            case "toBeVisible":
-                expectation = { matcher: "toBeVisible" };
-                break;
-            case "toHaveText":
-            case "toContainText":
-            case "toHaveValue":
-                expectation = { matcher: message.matcher, expected };
-                break;
-            case "toHaveAttribute":
-                if (!message.attribute)
-                    return fail("Choose an attribute");
-                expectation = {
-                    matcher: "toHaveAttribute",
-                    name: message.attribute,
-                    expected,
-                };
-                break;
-            case "toHaveCount": {
-                const call = pick.counts[message.countIndex ?? 0];
-                const count = Number(expected);
-                if (!call)
-                    return fail("Choose what to count");
-                if (expected.trim() === "" || !Number.isInteger(count) || count < 0)
-                    return fail("A count is a whole number");
-                locator = { chain: [call], fallbacks: [] };
-                expectation = { matcher: "toHaveCount", expected: count };
-                break;
-            }
-            default:
-                return fail("Choose a matcher");
-        }
-        this.pick = undefined;
-        this.deps.observe({
-            type: "expect",
-            locator,
-            not: message.not === true,
-            expectation,
-        });
-        return { ok: true };
-    }
-    async insert(message) {
-        if (this.paused)
-            return fail(PAUSED);
-        const { kind, name } = message;
-        const value = kind === "secret" ? this.secrets.get(name) : this.variables.get(name);
-        if (value === undefined)
-            return fail(kind === "secret"
-                ? `Set a value for ${name} first`
-                : `There is no variable "${name}"`);
-        const locator = await this.locate(message);
-        if (!locator)
-            return fail(UNIDENTIFIABLE);
-        return this.typeIn(locator, kind, name, value);
-    }
-    async addInsertable(message) {
-        if (this.paused)
-            return fail(PAUSED);
-        const { kind, name } = message;
-        const value = String(message.value ?? "");
-        if (kind === "env" && !this.options.canAddVariables)
-            return fail(NO_ENVIRONMENT);
-        const known = kind === "env"
-            ? this.variables.has(name)
-            : this.secrets.get(name) !== undefined;
-        if (known)
-            return fail(`"${name}" already exists`, "name");
-        // Found before anything is written: an element that can't be filled leaves the project as it was
-        const locator = await this.locate(message);
-        if (!locator)
-            return fail(UNIDENTIFIABLE);
-        const written = kind === "env"
-            ? await this.write(() => this.deps.addVariable(name, value), (err) => err instanceof ConfigEditError
-                ? fail(`samurai.config.ts can't be changed automatically. Add ${name} to environments.${this.options.environment}.variables yourself.`)
-                : err instanceof ExistsError || !VARIABLE_NAME.test(name)
-                    ? fail(errorText(err), "name")
-                    : fail(errorText(err)))
-            : await this.write(() => this.deps.setSecret(name, value), (err) => 
-            // An error never echoes the value
-            SECRET_NAME.test(name)
-                ? fail(scrub(errorText(err), value))
-                : fail(scrub(errorText(err), value), "name"));
-        if (written)
-            return written;
-        if (kind === "env")
-            this.variables.set(name, value);
-        else {
-            this.secrets.set(name, value);
-            this.deps.secretAdded(name);
-        }
-        this.push();
-        return this.typeIn(locator, kind, name, value, true);
-    }
-    /** Undefined when `work` succeeded, else the reply for its error */
-    async write(work, replyFor) {
-        try {
-            await work();
-            return undefined;
-        }
-        catch (err) {
-            return replyFor(err);
-        }
-    }
-    async locate(message) {
-        if (!message.target)
-            return undefined;
-        try {
-            return await this.deps.rank(message.target, message.candidates);
-        }
-        catch {
-            return undefined; // the element went away
-        }
-    }
-    async typeIn(locator, kind, name, value, saved = false) {
-        try {
-            await this.deps.type(locator, value);
-        }
-        catch {
-            // Typing clicks the field, which closes the panel the reply is for: the toast is what the tester sees
-            this.showToast(saved
-                ? `Saved ${name}, but couldn't type into that field`
-                : TYPE_FAILED);
-            this.push();
-            return fail(TYPE_FAILED);
-        }
-        this.deps.observe({ type: "insert", locator, value: { kind, name } });
-        return { ok: true };
+        this.reply(message.id, found ? withoutSecrets(found.info, this.secrets) : fail(UNIDENTIFIABLE));
     }
 }
-const errorText = (err) => err instanceof Error ? err.message : String(err);
-const scrub = (text, secret) => secret === "" ? text : text.split(secret).join("••••••");

package/dist/recorder/toolbar/inspect.d.ts

@@ -2,9 +2,7 @@ import type Page from "../../browser/page.js";
 import type { ElementHandle } from "../../script/element-handle.js";
 import type { LocatorCall, LocatorSpec } from "../../steps/model.js";
 import type { BiDiConnector } from "../../transport/bidi-connection.js";
-import type { Inspection } from "./controller.js";
-/** A locator call in short, as the Assert panel shows it: `heading "Sign in"`, `label "Email"`, `li.item` */
-export declare function describeCall(call: LocatorCall): string;
+import type { Inspection } from "./types.js";
 /**
  * What the Assert panel needs for a picked element: its short label, text, value, attributes, the first
  * matcher (today's Alt+click rule) and up to three locators that match more than one element, with counts.

package/dist/recorder/toolbar/inspect.js

@@ -1,7 +1,7 @@
 import { callFunction } from "../../script/call-function.js";
 import { locatorFromSpec } from "../../steps/build.js";
 import { CANDIDATES_JS } from "../candidates.js";
-import { expectationFor } from "../normalise.js";
+import { expectationFor } from "../expectation.js";
 import { TOOLBAR_SANDBOX } from "./protocol.js";
 /** Most Count choices the Assert panel offers */
 const MAX_COUNTS = 3;
@@ -27,7 +27,7 @@ const INSPECT_SOURCE = String.raw `(el) => {
   };
 }`;
 /** A locator call in short, as the Assert panel shows it: `heading "Sign in"`, `label "Email"`, `li.item` */
-export function describeCall(call) {
+function describeCall(call) {
     switch (call.method) {
         case "getByRole":
             return call.name === undefined

package/dist/recorder/toolbar/page-scope.d.ts

@@ -0,0 +1,19 @@
+/** What a wait on the page ends with when the page was left first */
+export declare const LEFT: unique symbol;
+/**
+ * Tracks which document the toolbar is working for. Work started for an older document must not be answered, and
+ * Chrome never answers a command into a document that is being replaced, so such work stops being waited for.
+ */
+export declare class PageScope {
+    private page;
+    /** Wake-ups for the work waiting on the current page: called, and forgotten, when the page changes */
+    private readonly waiting;
+    /** Bumped on every page load */
+    get current(): number;
+    /** A new document loaded */
+    enter(): void;
+    /** Lets what waits on the current document stop waiting */
+    leave(): void;
+    /** Runs `work`, but stops waiting for it when the page is left; resolves `LEFT` then */
+    whileOn<T>(work: () => Promise<T>): Promise<T | typeof LEFT>;
+}