@itmetsam/samurai-framework 0.6.0 → 0.7.0

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

@@ -0,0 +1,135 @@
+import type { LocatorCall } from "../../steps/model.js";
+/** The BiDi sandbox realm the toolbar script runs in */
+export declare const TOOLBAR_SANDBOX = "samurai-toolbar";
+/** `Symbol.for(TOOLBAR_KEY)` on the sandbox global holds the toolbar's hook: `update`, `reply`, `press`, `root` */
+export declare const TOOLBAR_KEY = "samurai.toolbar";
+export type MatcherChoice = "toBeVisible" | "toHaveText" | "toContainText" | "toHaveValue" | "toHaveAttribute" | "toHaveCount";
+/** What the toolbar draws; secrets are names only */
+export interface ToolbarState {
+    status: "recording" | "paused";
+    collapsed: boolean;
+    /** Top-left corner in CSS pixels; null = the default spot (top right, 12 px in) */
+    position: {
+        x: number;
+        y: number;
+    } | null;
+    steps: number;
+    environment: string;
+    /** False when the config has no `environments` */
+    canAddVariables: boolean;
+    variables: {
+        name: string;
+        value: string;
+    }[];
+    secrets: {
+        name: string;
+        set: boolean;
+    }[];
+    /** Whether `.env.<environment>` is git-ignored */
+    secretsIgnored: boolean;
+    /** Ask "Add a step that opens this page?" */
+    resumeQuestion: boolean;
+    /** Prefill for the Screenshot panel: `screenshot-<n>` */
+    nextScreenshot: string;
+    /** Shown once per id */
+    toast?: {
+        id: number;
+        text: string;
+    };
+}
+/** Element-carrying messages send the element itself (it arrives as a handle) and its candidates */
+export type ToolbarMessage = {
+    type: "toolbar";
+} & 
+/** `url` is the document's `location.href`; Firefox also runs the toolbar in a transient about:blank */
+({
+    action: "ready";
+    url?: string;
+} | {
+    action: "pause";
+} | {
+    action: "resume";
+} | {
+    action: "resume-goto";
+    add: boolean;
+} | {
+    action: "stop";
+} | {
+    action: "move";
+    x: number;
+    y: number;
+} | {
+    action: "collapse";
+    collapsed: boolean;
+} | {
+    action: "pick";
+    id: number;
+    target: unknown;
+    candidates: LocatorCall[];
+} | {
+    action: "assert";
+    id: number;
+    target: unknown;
+    candidates: LocatorCall[];
+    matcher: MatcherChoice;
+    expected?: string;
+    attribute?: string;
+    countIndex?: number;
+    not: boolean;
+} | {
+    action: "insert";
+    id: number;
+    target: unknown;
+    candidates: LocatorCall[];
+    kind: "env" | "secret";
+    name: string;
+} | {
+    action: "add-insertable";
+    id: number;
+    target: unknown;
+    candidates: LocatorCall[];
+    kind: "env" | "secret";
+    name: string;
+    value: string;
+} | {
+    action: "wait";
+    kind: "idle";
+} | {
+    action: "wait";
+    kind: "time";
+    ms: number;
+} | {
+    action: "screenshot";
+    name: string;
+    fullPage: boolean;
+});
+/** The answer to `pick` */
+export type PickInfo = {
+    ok: true;
+    label: string;
+    text: string;
+    value?: string;
+    attributes: {
+        name: string;
+        value: string;
+    }[];
+    first: {
+        matcher: MatcherChoice;
+        expected?: string;
+    };
+    counts: {
+        label: string;
+        count: number;
+    }[];
+} | {
+    ok: false;
+    error: string;
+};
+/** The answer to `insert`, `add-insertable` and `assert` */
+export type ActionReply = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+    field?: "name";
+};

package/dist/recorder/toolbar/protocol.js

@@ -0,0 +1,4 @@
+/** The BiDi sandbox realm the toolbar script runs in */
+export const TOOLBAR_SANDBOX = "samurai-toolbar";
+/** `Symbol.for(TOOLBAR_KEY)` on the sandbox global holds the toolbar's hook: `update`, `reply`, `press`, `root` */
+export const TOOLBAR_KEY = "samurai.toolbar";

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

@@ -0,0 +1,32 @@
+/**
+ * The recorder toolbar: a function declaration `(send) => { … }` installed as a preload script in the
+ * `samurai-toolbar` sandbox realm (the caller names the sandbox), top-level documents only. `send` is the
+ * toolbar's own channel (not the capture script's); it stays in this closure, which page script cannot
+ * reach, and the recorder takes toolbar messages only from this sandbox's realm. It draws a
+ * closed shadow root on a `<samurai-recorder-toolbar>` element and is a thin view: it renders the
+ * `ToolbarState` the recorder pushes and sends `ToolbarMessage`s; every step is decided by the recorder.
+ *
+ * `globalThis[Symbol.for("samurai.toolbar")]` in the sandbox holds the hook:
+ * - `update(state)`: the recorder's state, after every change and every page load.
+ * - `reply(id, result)`: the answer to `pick` (a `PickInfo`) or to `assert`, `insert` and `add-insertable`
+ *   (an `ActionReply`).
+ * - `root`: the shadow root, for tests.
+ * - `press(action, detail?)`: runs the handler a click on that control runs (for tests). Actions:
+ *   `pause`, `resume`, `stop`, `collapse`, `expand`, `resume-yes`, `resume-no` (rail);
+ *   `assert`, `insert`, `wait`, `screenshot` (open or close the tool);
+ *   `pick { target }` (the element a picking click hit);
+ *   `matcher { matcher }`, `not`, `assert-add` (Assert panel);
+ *   `insert-item { kind, name }`, `insert-first`, `insert-new { kind }` (Insert list);
+ *   `new-kind { kind }`, `new-save`, `new-cancel` (New variable or secret);
+ *   `wait-add`, `screenshot-add`; `escape` (the Esc key).
+ *   Form inputs carry `data-field` (`expected`, `attribute`, `countIndex`, `filter`, `name`, `value`,
+ *   `waitKind`, `seconds`, `shotName`, `fullPage`) and update on `input`/`change`.
+ * - `rebind(send)`: used by a second run in the same document (a new recording), which keeps the host and
+ *   swaps in that recording's toolbar channel.
+ * - `state()`, `picking()`: the last state from `update` and whether the Assert picker is on (for tests).
+ * - `dispose()`: removes the host and every listener the toolbar put on the window and document (the
+ *   recording ended while the document stays open).
+ *
+ * A string, so no transpiler helper can end up in it.
+ */
+export declare const TOOLBAR_SOURCE: string;