@scenetest/scenes 0.2.0 → 0.4.0

package/dist/keyboard.d.ts

@@ -0,0 +1,168 @@
+import type { Page, Locator } from 'playwright';
+/**
+ * Navigation mode for an actor.
+ *
+ * - `'pointer'` — mouse/touch interaction. When fuzzy-fingers is enabled,
+ *   clicks occasionally miss the target first, pause, then click correctly
+ *   (simulating imprecise human touch input).
+ *
+ * - `'keyboard'` — navigate entirely via Tab key and activate via Enter/Space.
+ *   Tests that the app is keyboard-accessible.
+ *
+ * All modes are transparent to test authors. The same `click('submit')` call
+ * works in every mode.
+ */
+export type NavigationMode = 'pointer' | 'keyboard';
+/**
+ * Options for tabToElement
+ */
+interface TabToElementOptions {
+    /** Maximum number of Tab presses before giving up. Default: 100. */
+    maxTabs?: number;
+    /** Action timeout in ms (for the overall operation). */
+    timeout?: number;
+}
+/**
+ * Tab forward through the page until the target element (or a focusable
+ * descendant of it) receives focus.
+ *
+ * This simulates a real keyboard user pressing Tab repeatedly to reach
+ * an interactive element.  If the element can't be reached after `maxTabs`
+ * presses, it throws — indicating a keyboard-accessibility problem.
+ *
+ * @param page - Playwright Page
+ * @param target - Locator for the element to reach
+ * @param opts - Options (maxTabs, timeout)
+ */
+export declare function tabToElement(page: Page, target: Locator, opts?: TabToElementOptions): Promise<void>;
+/**
+ * Press Enter on the currently focused element.
+ */
+export declare function pressEnter(page: Page): Promise<void>;
+/**
+ * Press Space on the currently focused element.
+ * Used for toggling checkboxes and activating certain controls.
+ */
+export declare function pressSpace(page: Page): Promise<void>;
+/**
+ * Type text character by character into the currently focused element.
+ * Clears existing content first by selecting all.
+ */
+export declare function clearAndType(page: Page, value: string): Promise<void>;
+/**
+ * Navigate a <select> element's options using arrow keys.
+ * Assumes the select is already focused.
+ *
+ * Strategy: open the dropdown, then press ArrowDown/ArrowUp to reach
+ * the desired option, then press Enter to select it.
+ *
+ * For simplicity, we use a hybrid: the select is focused via Tab,
+ * then we use Playwright's selectOption which works via the browser
+ * API. This is a pragmatic choice — real keyboard users interact
+ * with selects differently across browsers.
+ */
+export declare function keyboardSelectOption(page: Page, target: Locator, value: string): Promise<void>;
+/**
+ * Fuzzy-finger strategy, alternated per interaction:
+ *
+ * - `'miss-center'` — clicks 15px from the element's center instead of
+ *   dead-center.  Tests WCAG 2.5.8 minimum target size (24×24 CSS-px).
+ *
+ * - `'miss-edge'` — clicks a few pixels *outside* the element's bounding
+ *   box.  Tests touch-target *spacing* between neighbors.
+ *
+ * Both strategies follow the same flow: miss → pause → correct click.
+ * If the correct click succeeds, we move on silently (humans miss all
+ * the time). If the correct click fails because the element vanished
+ * (the mis-click activated something else), we throw FuzzyFingerError.
+ */
+type FuzzyFingerStrategy = 'miss-center' | 'miss-edge';
+/**
+ * Thrown when a fuzzy-finger mis-click caused the target element to
+ * vanish (because the mis-click activated a neighboring element that
+ * navigated away or altered the DOM).
+ *
+ * This is a real UX problem: touch targets are too close together.
+ * The `strategy` field tells you which test surfaced the issue:
+ * - `'miss-center'` → element is undersized (WCAG 2.5.8)
+ * - `'miss-edge'`   → element is too close to a neighbor
+ */
+export declare class FuzzyFingerError extends Error {
+    readonly strategy: FuzzyFingerStrategy;
+    readonly selector: string;
+    readonly originalError: Error;
+    constructor(strategy: FuzzyFingerStrategy, selector: string, originalError: Error);
+}
+/**
+ * Fuzzy-finger click: miss → pause → correct click.
+ *
+ * Simulates imprecise human touch input. The mis-click lands either
+ * 15px from center (testing target size) or just outside the bounding
+ * box (testing target spacing), alternating between strategies.
+ *
+ * After the mis-click, pauses ~1s (like a human noticing the miss),
+ * then clicks the correct element. If the correct click succeeds,
+ * we move on silently — humans miss all the time, no big deal.
+ *
+ * If the correct click *fails* (element vanished because the mis-click
+ * activated a neighbor), we throw FuzzyFingerError — that's a real
+ * touch-target problem in the UI.
+ */
+export declare function fuzzyFingerClick(page: Page, target: Locator, timeout: number, selector?: string): Promise<void>;
+/**
+ * Fuzzy-finger fill: miss → pause → correct click → fill.
+ */
+export declare function fuzzyFingerFill(page: Page, target: Locator, value: string, timeout: number, selector?: string): Promise<void>;
+/**
+ * Fuzzy-finger check: miss → pause → correct check.
+ */
+export declare function fuzzyFingerCheck(page: Page, target: Locator, timeout: number, selector?: string): Promise<void>;
+/**
+ * Assigns navigation modes to actors via round-robin rotation.
+ *
+ * The default pool alternates: pointer, keyboard.
+ * Fuzzy-finger behavior is controlled separately and applies to
+ * pointer-mode actors.
+ *
+ * @example
+ * ```ts
+ * const rotation = new NavigationModeRotation()
+ * rotation.next() // 'pointer'
+ * rotation.next() // 'keyboard'
+ * rotation.next() // 'pointer'
+ * ```
+ *
+ * @example Keyboard only disabled
+ * ```ts
+ * const rotation = new NavigationModeRotation(['pointer'])
+ * rotation.next() // 'pointer'
+ * rotation.next() // 'pointer'
+ * ```
+ */
+export declare class NavigationModeRotation {
+    private pool;
+    private index;
+    constructor(modes?: NavigationMode[]);
+    /**
+     * Get the next navigation mode in rotation.
+     */
+    next(): NavigationMode;
+    /**
+     * Peek at the next mode without advancing.
+     */
+    peek(): NavigationMode;
+    /**
+     * Reset rotation to the beginning.
+     */
+    reset(): void;
+    /**
+     * Current rotation index (for reporting).
+     */
+    get currentIndex(): number;
+    /**
+     * The full mode pool.
+     */
+    get modes(): readonly NavigationMode[];
+}
+export {};
+//# sourceMappingURL=keyboard.d.ts.map

package/dist/keyboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyboard.d.ts","sourceRoot":"","sources":["../src/keyboard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAE/C;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,CAAA;AAEnD;;GAEG;AACH,UAAU,mBAAmB;IAC3B,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,OAAO,EACf,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAuDf;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1D;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1D;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAM3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAMf;AAMD;;;;;;;;;;;;;GAaG;AACH,KAAK,mBAAmB,GAAG,aAAa,GAAG,WAAW,CAAA;AA+FtD;;;;;;;;;GASG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAA;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,aAAa,EAAE,KAAK,CAAA;gBAEjB,QAAQ,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK;CAUlF;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,SAAY,GACnB,OAAO,CAAC,IAAI,CAAC,CAoCf;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,QAAQ,SAAY,GACnB,OAAO,CAAC,IAAI,CAAC,CA0Bf;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,SAAY,GACnB,OAAO,CAAC,IAAI,CAAC,CA0Bf;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,IAAI,CAAkB;IAC9B,OAAO,CAAC,KAAK,CAAI;gBAEL,KAAK,CAAC,EAAE,cAAc,EAAE;IAIpC;;OAEG;IACH,IAAI,IAAI,cAAc;IAMtB;;OAEG;IACH,IAAI,IAAI,cAAc;IAItB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,SAAS,cAAc,EAAE,CAErC;CACF"}

package/dist/keyboard.js

@@ -0,0 +1,370 @@
+/**
+ * Tab forward through the page until the target element (or a focusable
+ * descendant of it) receives focus.
+ *
+ * This simulates a real keyboard user pressing Tab repeatedly to reach
+ * an interactive element.  If the element can't be reached after `maxTabs`
+ * presses, it throws — indicating a keyboard-accessibility problem.
+ *
+ * @param page - Playwright Page
+ * @param target - Locator for the element to reach
+ * @param opts - Options (maxTabs, timeout)
+ */
+export async function tabToElement(page, target, opts = {}) {
+    const maxTabs = opts.maxTabs ?? 100;
+    const timeout = opts.timeout ?? 10000;
+    const deadline = Date.now() + timeout;
+    // Get a handle to the target element so we can compare in-page
+    const targetHandle = await target.elementHandle({ timeout: Math.min(5000, timeout) });
+    if (!targetHandle) {
+        throw new Error('Keyboard navigation: target element not found in DOM');
+    }
+    // Track where we started to detect full cycles
+    let startElement = null;
+    for (let i = 0; i < maxTabs; i++) {
+        if (Date.now() > deadline) {
+            throw new Error(`Keyboard navigation: timed out after ${timeout}ms trying to Tab to element`);
+        }
+        await page.keyboard.press('Tab');
+        // Check if focus landed on or within the target element
+        const result = await targetHandle.evaluate((el) => {
+            const active = document.activeElement;
+            if (!active || active === document.body)
+                return 'nobody';
+            if (el === active || el.contains(active))
+                return 'found';
+            // Return a stable identifier so we can detect cycles
+            return active.tagName + active.id;
+        });
+        if (result === 'found') {
+            return; // Successfully tabbed to element
+        }
+        // Detect full cycle (focus wrapped back to start)
+        if (i === 0) {
+            startElement = result;
+        }
+        else if (i > 2 && result === startElement) {
+            throw new Error('Keyboard navigation: Tab focus cycled back to the starting element without ' +
+                'reaching the target. The element may not be keyboard-accessible ' +
+                '(missing tabindex, not a natively focusable element, or hidden from tab order).');
+        }
+    }
+    throw new Error(`Keyboard navigation: could not reach element via Tab after ${maxTabs} key presses. ` +
+        'The element may not be keyboard-accessible (missing tabindex, not a ' +
+        'natively focusable element, or the page has too many focusable elements).');
+}
+/**
+ * Press Enter on the currently focused element.
+ */
+export async function pressEnter(page) {
+    await page.keyboard.press('Enter');
+}
+/**
+ * Press Space on the currently focused element.
+ * Used for toggling checkboxes and activating certain controls.
+ */
+export async function pressSpace(page) {
+    await page.keyboard.press('Space');
+}
+/**
+ * Type text character by character into the currently focused element.
+ * Clears existing content first by selecting all.
+ */
+export async function clearAndType(page, value) {
+    // Select all existing content and delete it
+    await page.keyboard.press('Control+a');
+    await page.keyboard.press('Backspace');
+    // Type the new value character by character
+    await page.keyboard.type(value);
+}
+/**
+ * Navigate a <select> element's options using arrow keys.
+ * Assumes the select is already focused.
+ *
+ * Strategy: open the dropdown, then press ArrowDown/ArrowUp to reach
+ * the desired option, then press Enter to select it.
+ *
+ * For simplicity, we use a hybrid: the select is focused via Tab,
+ * then we use Playwright's selectOption which works via the browser
+ * API. This is a pragmatic choice — real keyboard users interact
+ * with selects differently across browsers.
+ */
+export async function keyboardSelectOption(page, target, value) {
+    // The element is already focused via Tab. Use selectOption which
+    // works via the browser's native select API. This is consistent
+    // across browsers and matches what keyboard users experience when
+    // interacting with native selects (which vary by platform).
+    await target.selectOption(value);
+}
+/** Global counter — alternates strategy on every fuzzy-finger interaction. */
+let fuzzyFingerCounter = 0;
+function nextStrategy() {
+    return fuzzyFingerCounter++ % 2 === 0 ? 'miss-center' : 'miss-edge';
+}
+// -- miss-center helpers ----------------------------------------------------
+/**
+ * Distance from center for the miss-center strategy (px).
+ *
+ * WCAG 2.5.8 requires a minimum 24×24 CSS-px target size, so the
+ * center-to-edge distance is 12px.  Clicking 15px from center will
+ * miss a compliant-minimum element, surfacing undersized targets.
+ */
+const CENTER_OFFSET_PX = 15;
+/**
+ * Pick a random point that is CENTER_OFFSET_PX away from the
+ * element's center, in a random direction.
+ */
+function missCenterPoint(box) {
+    const cx = box.x + box.width / 2;
+    const cy = box.y + box.height / 2;
+    const angle = Math.random() * 2 * Math.PI;
+    return {
+        x: cx + CENTER_OFFSET_PX * Math.cos(angle),
+        y: cy + CENTER_OFFSET_PX * Math.sin(angle),
+    };
+}
+// -- miss-edge helpers ------------------------------------------------------
+/**
+ * Overshoot distance beyond the element edge (px).
+ *
+ * We land 3px *outside* the bounding box.  If the element meets the
+ * WCAG minimum (12px from center to edge), the mis-tap ends up ~15px
+ * from center — outside the target but close enough to hit a neighbor
+ * that is packed too tightly.
+ */
+const EDGE_OVERSHOOT_PX = 3;
+/**
+ * Pick a random point just outside the element's bounding box.
+ *
+ * Strategy: pick a random edge (top / right / bottom / left),
+ * place the coordinate EDGE_OVERSHOOT_PX beyond that edge, and
+ * randomize position along the edge so we don't always hit the
+ * same neighbor.
+ */
+function missEdgePoint(box) {
+    const edge = Math.floor(Math.random() * 4); // 0=top, 1=right, 2=bottom, 3=left
+    const t = 0.2 + Math.random() * 0.6; // bias toward center of edge, not corners
+    switch (edge) {
+        case 0: // top — above the element
+            return { x: box.x + box.width * t, y: box.y - EDGE_OVERSHOOT_PX };
+        case 1: // right — past the right edge
+            return { x: box.x + box.width + EDGE_OVERSHOOT_PX, y: box.y + box.height * t };
+        case 2: // bottom — below the element
+            return { x: box.x + box.width * t, y: box.y + box.height + EDGE_OVERSHOOT_PX };
+        case 3: // left — past the left edge
+        default:
+            return { x: box.x - EDGE_OVERSHOOT_PX, y: box.y + box.height * t };
+    }
+}
+// -- shared helpers ---------------------------------------------------------
+/**
+ * Probability of a mis-click on any given interaction.
+ * ~20% (1 in 5) — most clicks go through cleanly, but every now and
+ * then one goes slightly astray.
+ */
+const MISS_PROBABILITY = 0.2;
+/**
+ * Returns true if this interaction should be a mis-click.
+ */
+function shouldMiss() {
+    return Math.random() < MISS_PROBABILITY;
+}
+/**
+ * Pause duration (ms) after a mis-click before the correction.
+ * Short pause — human noticing the miss and re-tapping.
+ */
+const FUZZY_PAUSE_MS = 100;
+// -- diagnostic error -------------------------------------------------------
+/**
+ * Thrown when a fuzzy-finger mis-click caused the target element to
+ * vanish (because the mis-click activated a neighboring element that
+ * navigated away or altered the DOM).
+ *
+ * This is a real UX problem: touch targets are too close together.
+ * The `strategy` field tells you which test surfaced the issue:
+ * - `'miss-center'` → element is undersized (WCAG 2.5.8)
+ * - `'miss-edge'`   → element is too close to a neighbor
+ */
+export class FuzzyFingerError extends Error {
+    strategy;
+    selector;
+    originalError;
+    constructor(strategy, selector, originalError) {
+        const reason = strategy === 'miss-center'
+            ? `target too small (mis-click ${CENTER_OFFSET_PX}px from center hit something else — WCAG 2.5.8 requires minimum 24×24 CSS-px)`
+            : `target too close to neighbor (mis-click ${EDGE_OVERSHOOT_PX}px outside edge activated adjacent element)`;
+        super(`Fuzzy-finger failure on "${selector}": ${reason}`);
+        this.name = 'FuzzyFingerError';
+        this.strategy = strategy;
+        this.selector = selector;
+        this.originalError = originalError;
+    }
+}
+// -- exported fuzzy-finger actions ------------------------------------------
+/**
+ * Fuzzy-finger click: miss → pause → correct click.
+ *
+ * Simulates imprecise human touch input. The mis-click lands either
+ * 15px from center (testing target size) or just outside the bounding
+ * box (testing target spacing), alternating between strategies.
+ *
+ * After the mis-click, pauses ~1s (like a human noticing the miss),
+ * then clicks the correct element. If the correct click succeeds,
+ * we move on silently — humans miss all the time, no big deal.
+ *
+ * If the correct click *fails* (element vanished because the mis-click
+ * activated a neighbor), we throw FuzzyFingerError — that's a real
+ * touch-target problem in the UI.
+ */
+export async function fuzzyFingerClick(page, target, timeout, selector = '(scope)') {
+    await target.waitFor({ state: 'visible', timeout });
+    // ~1 in 5 clicks will miss — most go through cleanly
+    if (shouldMiss()) {
+        const strategy = nextStrategy();
+        const box = await target.boundingBox({ timeout });
+        if (box) {
+            // Step 1: Miss click
+            const missPoint = strategy === 'miss-center' ? missCenterPoint(box) : missEdgePoint(box);
+            await page.mouse.click(missPoint.x, missPoint.y);
+            // Step 2: Pause (human noticing the miss)
+            await new Promise(resolve => setTimeout(resolve, FUZZY_PAUSE_MS));
+        }
+        // Step 3: Correct click — this is where we detect problems
+        try {
+            await target.click({ timeout });
+        }
+        catch (err) {
+            // The correct click failed. Did the element vanish because our
+            // mis-click activated something else?
+            const stillExists = await target.count() > 0;
+            if (!stillExists) {
+                // Element is gone — the mis-click caused navigation or DOM change
+                throw new FuzzyFingerError(strategy, selector, err instanceof Error ? err : new Error(String(err)));
+            }
+            // Element still exists but click failed for another reason — real bug
+            throw err;
+        }
+        return;
+    }
+    // Normal click (no mis-click this time)
+    await target.click({ timeout });
+}
+/**
+ * Fuzzy-finger fill: miss → pause → correct click → fill.
+ */
+export async function fuzzyFingerFill(page, target, value, timeout, selector = '(scope)') {
+    await target.waitFor({ state: 'visible', timeout });
+    if (shouldMiss()) {
+        const strategy = nextStrategy();
+        const box = await target.boundingBox({ timeout });
+        if (box) {
+            const missPoint = strategy === 'miss-center' ? missCenterPoint(box) : missEdgePoint(box);
+            await page.mouse.click(missPoint.x, missPoint.y);
+            await new Promise(resolve => setTimeout(resolve, FUZZY_PAUSE_MS));
+        }
+        try {
+            await target.fill(value, { timeout });
+        }
+        catch (err) {
+            const stillExists = await target.count() > 0;
+            if (!stillExists) {
+                throw new FuzzyFingerError(strategy, selector, err instanceof Error ? err : new Error(String(err)));
+            }
+            throw err;
+        }
+        return;
+    }
+    await target.fill(value, { timeout });
+}
+/**
+ * Fuzzy-finger check: miss → pause → correct check.
+ */
+export async function fuzzyFingerCheck(page, target, timeout, selector = '(scope)') {
+    await target.waitFor({ state: 'visible', timeout });
+    if (shouldMiss()) {
+        const strategy = nextStrategy();
+        const box = await target.boundingBox({ timeout });
+        if (box) {
+            const missPoint = strategy === 'miss-center' ? missCenterPoint(box) : missEdgePoint(box);
+            await page.mouse.click(missPoint.x, missPoint.y);
+            await new Promise(resolve => setTimeout(resolve, FUZZY_PAUSE_MS));
+        }
+        try {
+            await target.check({ timeout });
+        }
+        catch (err) {
+            const stillExists = await target.count() > 0;
+            if (!stillExists) {
+                throw new FuzzyFingerError(strategy, selector, err instanceof Error ? err : new Error(String(err)));
+            }
+            throw err;
+        }
+        return;
+    }
+    await target.check({ timeout });
+}
+// ---------------------------------------------------------------------------
+// NavigationModeRotation
+// ---------------------------------------------------------------------------
+/**
+ * Assigns navigation modes to actors via round-robin rotation.
+ *
+ * The default pool alternates: pointer, keyboard.
+ * Fuzzy-finger behavior is controlled separately and applies to
+ * pointer-mode actors.
+ *
+ * @example
+ * ```ts
+ * const rotation = new NavigationModeRotation()
+ * rotation.next() // 'pointer'
+ * rotation.next() // 'keyboard'
+ * rotation.next() // 'pointer'
+ * ```
+ *
+ * @example Keyboard only disabled
+ * ```ts
+ * const rotation = new NavigationModeRotation(['pointer'])
+ * rotation.next() // 'pointer'
+ * rotation.next() // 'pointer'
+ * ```
+ */
+export class NavigationModeRotation {
+    pool;
+    index = 0;
+    constructor(modes) {
+        this.pool = modes && modes.length > 0 ? modes : ['pointer', 'keyboard'];
+    }
+    /**
+     * Get the next navigation mode in rotation.
+     */
+    next() {
+        const mode = this.pool[this.index % this.pool.length];
+        this.index++;
+        return mode;
+    }
+    /**
+     * Peek at the next mode without advancing.
+     */
+    peek() {
+        return this.pool[this.index % this.pool.length];
+    }
+    /**
+     * Reset rotation to the beginning.
+     */
+    reset() {
+        this.index = 0;
+    }
+    /**
+     * Current rotation index (for reporting).
+     */
+    get currentIndex() {
+        return this.index;
+    }
+    /**
+     * The full mode pool.
+     */
+    get modes() {
+        return this.pool;
+    }
+}
+//# sourceMappingURL=keyboard.js.map

package/dist/keyboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyboard.js","sourceRoot":"","sources":["../src/keyboard.ts"],"names":[],"mappings":"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"}

package/dist/markdown-scene.d.ts

@@ -58,8 +58,10 @@
 export interface MarkdownScene {
     name: string;
     group?: string;
-    /** Pre-cleanup expression from `cleanup:` directive */
-    cleanup?: string;
+    /** Pre/post-cleanup expressions from `cleanup:` directives (one per line) */
+    cleanup: string[];
+    /** Setup expressions from `setup:` directives — run after pre-cleanup, before scene */
+    setup: string[];
     blocks: ActorBlock[];
 }
 export interface ActorBlock {

package/dist/markdown-scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown-scene.d.ts","sourceRoot":"","sources":["../src/markdown-scene.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAYH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,UAAU,EAAE,CAAA;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,WAAW,EAAE,CAAA;CACvB;AAED;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEtC,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,EAAE,CAAA;CAAE,CAAA;AAMrD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,aAAa,EAAE,CAyJjB;AAmLD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,aAAa,EAAE,EACvB,QAAQ,EAAE,MAAM,GACf,IAAI,CAsHN;AAMD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOvE"}
+{"version":3,"file":"markdown-scene.d.ts","sourceRoot":"","sources":["../src/markdown-scene.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAYH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,6EAA6E;IAC7E,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,uFAAuF;IACvF,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,MAAM,EAAE,UAAU,EAAE,CAAA;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,WAAW,EAAE,CAAA;CACvB;AAED;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEtC,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,EAAE,CAAA;CAAE,CAAA;AAMrD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,aAAa,EAAE,CAkKjB;AAmLD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,aAAa,EAAE,EACvB,QAAQ,EAAE,MAAM,GACf,IAAI,CAwHN;AAMD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOvE"}

package/dist/markdown-scene.js

@@ -90,7 +90,7 @@ export function parseMarkdownScenes(content, filePath) {
             // # = group, ## = scene
             if (/^## /.test(trimmed)) {
                 const name = trimmed.slice(3).trim();
-                currentScene = { name, group: currentGroup, blocks: [] };
+                currentScene = { name, group: currentGroup, cleanup: [], setup: [], blocks: [] };
                 scenes.push(currentScene);
                 currentBlock = null;
                 continue;
@@ -104,17 +104,23 @@ export function parseMarkdownScenes(content, filePath) {
             // No ## headings — # = scene
             if (/^# /.test(trimmed)) {
                 const name = trimmed.slice(2).trim();
-                currentScene = { name, group: undefined, blocks: [] };
+                currentScene = { name, group: undefined, cleanup: [], setup: [], blocks: [] };
                 scenes.push(currentScene);
                 currentBlock = null;
                 continue;
             }
         }
-        // ── Cleanup directive ─────────────────────────────────────────────
-        // `cleanup: <expression>` — one per scene, before actor cues
+        // ── Cleanup / setup directives ────────────────────────────────────
+        // `cleanup: <expression>` — multiple allowed, run before AND after scene
+        // `setup: <expression>`   — multiple allowed, run after pre-cleanup, before scene
         const cleanupMatch = trimmed.match(/^cleanup:\s+(.+)$/);
         if (cleanupMatch && currentScene && !currentBlock) {
-            currentScene.cleanup = cleanupMatch[1];
+            currentScene.cleanup.push(cleanupMatch[1]);
+            continue;
+        }
+        const setupMatch = trimmed.match(/^setup:\s+(.+)$/);
+        if (setupMatch && currentScene && !currentBlock) {
+            currentScene.setup.push(setupMatch[1]);
             continue;
         }
         // ── Content lines (need an active scene) ──────────────────────────
@@ -124,6 +130,8 @@ export function parseMarkdownScenes(content, filePath) {
             currentScene = {
                 name: path.basename(filePath, '.spec.md'),
                 group: undefined,
+                cleanup: [],
+                setup: [],
                 blocks: [],
             };
             scenes.push(currentScene);
@@ -221,7 +229,7 @@ function stripListPrefix(line) {
 const KNOWN_ACTIONS = [
     'openTo', 'see', 'seeInView', 'notSee', 'seeText', 'seeToast', 'click',
     'typeInto', 'check', 'select', 'wait', 'emit', 'waitFor',
-    'warnIf', 'up', 'prev', 'scrollToBottom', 'if',
+    'warnIf', 'up', 'prev', 'scrollToBottom', 'if', 'pressKey',
 ];
 /** Check if a line looks like a DSL action or macro invocation */
 function isActionLine(line) {
@@ -444,9 +452,13 @@ export function registerMarkdownScenes(scenes, filePath) {
                 }
             }
         });
-        // Propagate cleanup expression to the registered scene
-        if (mdScene.cleanup && sceneRegistry.length > 0) {
-            sceneRegistry[sceneRegistry.length - 1].cleanup = mdScene.cleanup;
+        // Propagate cleanup/setup expressions to the registered scene
+        if (sceneRegistry.length > 0) {
+            const registered = sceneRegistry[sceneRegistry.length - 1];
+            if (mdScene.cleanup.length > 0)
+                registered.cleanup = mdScene.cleanup;
+            if (mdScene.setup.length > 0)
+                registered.setup = mdScene.setup;
         }
     }
 }