@sungen/driver-ui 3.2.34-beta.1 → 3.3.0-alpha.1

package/dist/patterns/interaction-patterns.js

@@ -0,0 +1,633 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.interactionPatterns = void 0;
+exports.parseClickPosition = parseClickPosition;
+const url_path_regex_1 = require("../utils/url-path-regex");
+/**
+ * Extract Playwright waitFor state from step text.
+ * Defaults to 'visible' if no known state keyword is found.
+ */
+function extractWaitState(text) {
+    if (/\bhidden\b/.test(text))
+        return 'hidden';
+    if (/\bdetached\b/.test(text))
+        return 'detached';
+    if (/\bdisabled\b/.test(text))
+        return 'disabled';
+    if (/\benabled\b/.test(text))
+        return 'enabled';
+    if (/\bvisible\b/.test(text))
+        return 'visible';
+    return 'visible';
+}
+/**
+ * Map a plain element keyword (no brackets) to a Playwright ARIA role.
+ */
+function elementKeywordToRole(text) {
+    const match = text.match(/\bwait(?:s)?\s+for\s+(dialog|modal|alert|alertdialog|tooltip|menu|listbox|combobox|grid|table|status|banner|navigation|main|region)\b/i);
+    if (!match)
+        return null;
+    const keyword = match[1].toLowerCase();
+    const roleMap = {
+        modal: 'dialog',
+        alert: 'alertdialog',
+    };
+    return roleMap[keyword] || keyword;
+}
+/**
+ * Interaction patterns: click, hover, press, wait, alert
+ */
+/** Corner presets: 5% in from each corner, so the point stays on the element under any padding. */
+const CLICK_POSITION_PRESETS = {
+    'top-left': { x: 5, y: 5 },
+    'top-right': { x: 95, y: 5 },
+    'bottom-left': { x: 5, y: 95 },
+    'bottom-right': { x: 95, y: 95 },
+};
+/**
+ * Parse the `at position "<preset>"` / `at offset x=<n>px|%, y=<n>px|%` suffix. Strict on purpose:
+ * anything the grammar does not accept is an error the compiler reports — a position that is half
+ * understood would click somewhere the author did not ask for.
+ */
+function parseClickPosition(text) {
+    const presetNames = Object.keys(CLICK_POSITION_PRESETS).map((k) => `"${k}"`).join(' | ');
+    // Both forms end the sentence: anything after the position is text no form reads, so it is refused
+    // rather than carried along silently.
+    const preset = /\bat\s+position\s+"([^"]*)"\s*$/i.exec(text);
+    if (preset) {
+        const p = CLICK_POSITION_PRESETS[preset[1].trim().toLowerCase()];
+        if (!p)
+            return { error: `unknown click position preset "${preset[1]}" — use ${presetNames}` };
+        return { x: p.x, xUnit: '%', xRatio: p.x / 100, y: p.y, yUnit: '%', yRatio: p.y / 100 };
+    }
+    if (/\bat\s+position\b/i.test(text))
+        return { error: `\`at position\` needs a quoted preset (${presetNames}) as the last thing in the step` };
+    const offset = /\bat\s+offset\s+x\s*=\s*(-?\d+(?:\.\d+)?)\s*(px|%)\s*,\s*y\s*=\s*(-?\d+(?:\.\d+)?)\s*(px|%)\s*$/i.exec(text);
+    if (!offset)
+        return { error: '`at offset` needs `x=<n>px|%, y=<n>px|%` with both axes (e.g. `x=24px, y=10%`) as the last thing in the step' };
+    const axis = (raw, unit, name) => {
+        const value = Number(raw);
+        if (value < 0)
+            return { error: `${name}=${raw}${unit} is negative — offsets are measured from the element's top-left corner` };
+        if (unit === '%' && value > 100)
+            return { error: `${name}=${raw}% exceeds 100% of the element` };
+        return { value, unit: unit.toLowerCase() };
+    };
+    const x = axis(offset[1], offset[2], 'x');
+    if ('error' in x)
+        return x;
+    const y = axis(offset[3], offset[4], 'y');
+    if ('error' in y)
+        return y;
+    return {
+        x: x.value, xUnit: x.unit, xRatio: x.unit === '%' ? x.value / 100 : x.value,
+        y: y.value, yUnit: y.unit, yRatio: y.unit === '%' ? y.value / 100 : y.value,
+    };
+}
+exports.interactionPatterns = [
+    // === Browser Alert (system dialog) patterns ===
+    // Compound form (preferred since v3.3): trigger + dialog response in ONE step, in the
+    // user's natural order — the compiler emits the listener FIRST (Playwright requires
+    // registration before the triggering action; a late handler lets the dialog
+    // auto-dismiss with no error):
+    //   When User click [Đăng xuất] button and accept [OK] alert
+    //   When User click [Xoá] button and dismiss [Cancel] alert
+    {
+        name: 'click-with-alert',
+        matcher: (step) => /\b(click|clicks)\b/.test(step.text) &&
+            /\band\s+(accept|accepts|dismiss|dismisses)\s+\[[^\]]*\]\s+alert\b/i.test(step.text) &&
+            (step.text.match(/\[[^\]]+\]/g) || []).length >= 2,
+        resolver: (step, context) => {
+            // brackets[0] = trigger element, brackets[1] = alert button (verb decides the action)
+            const brackets = step.text.match(/\[([^\]]+)\]/g) || [];
+            const triggerName = brackets[0].replace(/[\[\]]/g, '');
+            const dialogAction = /\band\s+dismiss(?:es)?\b/i.test(step.text) ? 'dismiss' : 'accept';
+            // Element type = the word right after the trigger bracket (button/link/…)
+            const typeMatch = step.text.match(/\]\s+([\w-]+)\s+and\b/i);
+            const triggerType = typeMatch ? typeMatch[1].toLowerCase() : 'button';
+            const resolved = context.selectorResolver.resolveSelector(triggerName, context.featureName, triggerType, step.nth);
+            return {
+                templateName: 'click-with-alert-action',
+                data: { ...resolved, dialogAction },
+                comment: `Click ${triggerName} and ${dialogAction} the browser dialog`,
+            };
+        },
+        priority: 21,
+    },
+    // Two-step form (still valid): the alert step must appear BEFORE the click that
+    // triggers the alert in Gherkin — SG-W007 warns when it is written after:
+    //   When User click [OK] alert       ← registers page.once('dialog', ...)
+    //   And User click [Delete] button   ← triggers the alert
+    {
+        name: 'alert-accept',
+        matcher: (step) => step.elementType === 'alert' &&
+            (step.text.includes('click') || step.text.includes('clicks')) &&
+            !step.dataRef &&
+            !!(step.selectorRef && /^(ok|accept|yes|confirm)$/i.test(step.selectorRef)),
+        resolver: (step, context) => {
+            return {
+                templateName: 'alert-accept-action',
+                data: {},
+                comment: `Accept browser alert`,
+            };
+        },
+        priority: 20,
+    },
+    {
+        name: 'alert-dismiss',
+        matcher: (step) => step.elementType === 'alert' &&
+            (step.text.includes('click') || step.text.includes('clicks')) &&
+            !step.dataRef &&
+            !!(step.selectorRef && /^(cancel|dismiss|no)$/i.test(step.selectorRef)),
+        resolver: (step, context) => {
+            return {
+                templateName: 'alert-dismiss-action',
+                data: {},
+                comment: `Dismiss browser alert`,
+            };
+        },
+        priority: 20,
+    },
+    {
+        name: 'alert-fill',
+        platforms: ['web'],
+        platformAlternative: 'Appium ships no fill for a native prompt - accept or dismiss the alert instead (the `alert` element type still works), drive the app own text field as a normal element, or tag the scenario @manual:M10',
+        matcher: (step) => step.elementType === 'alert' &&
+            step.text.includes('fill') &&
+            !!step.dataRef,
+        resolver: (step, context) => {
+            let fillValue;
+            fillValue = context.dataResolver.resolveData(step.dataRef, context.featureName);
+            return {
+                templateName: 'alert-fill-action',
+                data: { fillValue },
+                comment: `Fill browser prompt with ${step.dataRef}`,
+            };
+        },
+        priority: 20,
+    },
+    {
+        // `try to click [X] button` — the DISABLED-element probe (issue: no way to write
+        // "click a disabled control and confirm nothing happens").
+        //
+        // A plain `click` compiles to Playwright's `.click()`, which auto-waits for the element to
+        // be ACTIONABLE (visible + enabled + stable). That wait is the whole point for a real click,
+        // but it makes the inverse scenario — "the re-send link is in cooldown, clicking it must do
+        // nothing" — impossible to express: the step can only ever time out on an element that is
+        // disabled BY DESIGN.
+        //
+        // This variant bypasses the actionability wait (`{ force: true }`), so the click is really
+        // dispatched at the element's position. A natively-`disabled` control swallows it and nothing
+        // happens (the following assertions prove that); an `aria-disabled`/CSS-only "disabled"
+        // control that still handles the click is caught as the bug it is. Note the element must
+        // still exist and be rendered — this is not a silent no-op.
+        //
+        //   When User try to click [Re-send] link          # cooldown active → must stay inert
+        //   Then User see [Re-send] link is disabled
+        //   And User see [Cooldown] text                   # …and no re-send happened
+        name: 'try-click-element',
+        matcher: (step) => /\b(?:tr(?:y|ies)|attempts?)\s+to\s+click\b/i.test(step.text) &&
+            // `… and accept/dismiss [OK] alert` stays with click-with-alert: force-clicking here would
+            // drop the page.once('dialog') listener the compound form exists to register.
+            !/\band\s+(?:accept|accepts|dismiss|dismisses)\s+\[[^\]]*\]\s+alert\b/i.test(step.text) &&
+            !!step.selectorRef,
+        resolver: (step, context) => {
+            const resolved = context.selectorResolver.resolveSelector(step.selectorRef, undefined, step.elementType, step.nth);
+            // No `with {{v}}` → plain forced click. Mirrors click-element.
+            if (!(step.dataRef || step.value) || !step.text.includes('with')) {
+                return {
+                    templateName: 'click-action',
+                    data: { ...resolved, selectorRef: step.selectorRef, force: true },
+                    comment: `Try to click ${step.selectorRef} (bypasses the enabled/actionability wait)`,
+                };
+            }
+            // `with {{v}}` → filter to the matching row/item first. Mirrors click-element-with-text.
+            let dataValue;
+            if (step.value) {
+                dataValue = step.value;
+            }
+            else {
+                dataValue = context.dataResolver.resolveData(step.dataRef, context.featureName);
+            }
+            const { name: _name, ...resolvedWithoutName } = resolved;
+            return {
+                templateName: 'click-element-with-text',
+                data: { ...resolvedWithoutName, dataValue, force: true },
+                comment: `Try to click ${step.selectorRef} with text ${step.dataRef || step.value} (bypasses the enabled/actionability wait)`,
+            };
+        },
+        priority: 22, // above click-with-alert (21) and every other click pattern — the verb wins
+    },
+    {
+        name: 'unknown-element-action',
+        matcher: (step) => {
+            const isTargetElement = step.selectorRef && /^target\s/i.test(step.selectorRef);
+            const isInteractionAction = !step.text.includes('see') && !step.text.includes('sees');
+            return isTargetElement && !!step.dataRef && step.text.includes('with') && isInteractionAction;
+        },
+        resolver: (step, context) => {
+            let selectorValue = '';
+            let nth;
+            let exact = false;
+            try {
+                const resolved = context.selectorResolver.resolveSelector(step.selectorRef, context.featureName, step.elementType, step.nth);
+                selectorValue = resolved.value || '';
+                nth = resolved.nth;
+                exact = resolved.exact === true;
+            }
+            catch (error) {
+                selectorValue = '';
+                nth = undefined;
+            }
+            let dataValue;
+            dataValue = context.dataResolver.resolveData(step.dataRef, context.featureName);
+            let actionMethod = 'click';
+            if (step.text.includes('hover'))
+                actionMethod = 'hover';
+            else if (step.text.includes('double'))
+                actionMethod = 'dblclick';
+            return {
+                templateName: 'unknown-element-action',
+                data: { selectorValue, dataValue, action: actionMethod, nth, exact },
+                comment: `${actionMethod.charAt(0).toUpperCase() + actionMethod.slice(1)} ${step.selectorRef} with ${step.dataRef}`,
+            };
+        },
+        priority: 14, // Below click-element-with-text (15) so known selectors use proper locator
+    },
+    {
+        // `click [X] overlay at position "top-left"` / `… at offset x=24px, y=10%` — a click AWAY from the
+        // centre, for backdrop-dismiss overlays and any control whose centre is covered by a child.
+        // `.click()` always lands on the centre; there was no way to say "click the overlay, not the
+        // dialog sitting in the middle of it". Presets are 5% in from the corners so the point stays on
+        // the element under any padding. Positions are checked against the element's PADDING box at
+        // run time (`clientWidth/Height`, the same box `click({ position })` measures from), so a px
+        // offset beyond the real size fails with the real size in the message instead of clicking the
+        // neighbour. A suffix the grammar cannot parse is refused at compile time (SG-E026, via the core
+        // guard) — never a silent centre click.
+        name: 'click-element-at-position',
+        platforms: ['web'],
+        platformAlternative: 'Appium has no positioned click on an element — tap the control the position targets directly (`User tap [X] button`), or tag the scenario @manual',
+        matcher: (step) => /\b(click|clicks)\b/.test(step.text)
+            // a positioned DOUBLE/RIGHT click is not offered — leave those to their own forms so the core
+            // guard refuses the suffix instead of this form silently turning them into a single click
+            && !/\b(?:double|right)[\s-]*click/i.test(step.text)
+            && /\bat\s+(position|offset)\b/i.test(step.text) && !!step.selectorRef,
+        resolver: (step, context) => {
+            const resolved = context.selectorResolver.resolveSelector(step.selectorRef, undefined, step.elementType, step.nth);
+            const suffix = step.text.match(/\bat\s+(?:position|offset)\b.*$/i)?.[0].trim() ?? 'at position';
+            // JSON.stringify quotes the label for the generated code — the step text is author text.
+            const label = JSON.stringify(`click [${step.selectorRef}] ${suffix}`);
+            const parsed = parseClickPosition(step.text);
+            if ('error' in parsed) {
+                // The template is not what refuses this — the core compiler does (SG-E026 + a loud throw);
+                // `positionError` is the signal it reads. Emitted here so the reason names the exact fault.
+                return {
+                    templateName: 'click-at-position-action',
+                    data: { ...resolved, selectorRef: step.selectorRef, label, positionError: parsed.error },
+                    comment: `Click ${step.selectorRef} ${suffix}`,
+                };
+            }
+            return {
+                templateName: 'click-at-position-action',
+                data: { ...resolved, selectorRef: step.selectorRef, label, clickPosition: parsed },
+                comment: `Click ${step.selectorRef} ${suffix}`,
+            };
+        },
+        priority: 12, // above click-element (10): the suffix wins; below click-element-with-text (15) and the
+        // alert/try-to forms — those combinations are refused by the core guard, not compiled
+    },
+    {
+        name: 'click-element-with-text',
+        matcher: (step) => (step.text.includes('clicks') || step.text.includes('click'))
+            && !!step.selectorRef
+            && !!(step.dataRef || step.value)
+            && step.text.includes('with'),
+        resolver: (step, context) => {
+            const resolved = context.selectorResolver.resolveSelector(step.selectorRef, undefined, step.elementType, step.nth);
+            let dataValue;
+            if (step.value) {
+                dataValue = step.value;
+            }
+            else {
+                dataValue = context.dataResolver.resolveData(step.dataRef, context.featureName);
+            }
+            const { name: _name, ...resolvedWithoutName } = resolved;
+            return {
+                templateName: 'click-element-with-text',
+                data: { ...resolvedWithoutName, dataValue },
+                comment: `Click ${step.selectorRef} with text ${step.dataRef || step.value}`,
+            };
+        },
+        priority: 15,
+    },
+    {
+        name: 'click-element',
+        matcher: (step) => (step.text.includes('clicks') || step.text.includes('click')) && !!step.selectorRef,
+        resolver: (step, context) => {
+            const resolved = context.selectorResolver.resolveSelector(step.selectorRef, undefined, step.elementType, step.nth);
+            return {
+                templateName: 'click-action',
+                data: { ...resolved, selectorRef: step.selectorRef },
+                comment: `Click ${step.selectorRef}`,
+            };
+        },
+        priority: 10,
+    },
+    {
+        name: 'double-click',
+        matcher: (step) => (step.text.includes('double click') || step.text.includes('double-click') ||
+            (step.text.includes('double') && step.text.includes('clicks'))) && !!step.selectorRef,
+        resolver: (step, context) => {
+            const resolved = context.selectorResolver.resolveSelector(step.selectorRef, undefined, step.elementType, step.nth);
+            return {
+                templateName: 'double-click-action',
+                data: { ...resolved, selectorRef: step.selectorRef },
+                comment: `Double click ${step.selectorRef}`,
+            };
+        },
+        priority: 11,
+    },
+    {
+        // `hover [X] item with {{v}}` — pick the element whose text matches the value, mirroring
+        // click-element-with-text. Without this, hover fell through to hover-element which IGNORED
+        // the value and hovered the first match (strict-mode / wrong element on dynamic lists).
+        name: 'hover-element-with-text',
+        // Pure: this resolver requests `hover-element-with-text` and nothing else, which is what makes
+        // the declaration safe. A pattern that can reach a shared template (click, recipe-sequence) must
+        // NOT be declared — see the mixed `unknown-element-action` below, which also serves click.
+        platforms: ['web'],
+        platformAlternative: 'a touch screen has no hover, so filtering a list by text and hovering it has no mobile meaning — tap the matching item with `User tap [X] item with {{value}}`, or tag the scenario @manual:M10',
+        matcher: (step) => (step.text.includes('hovers') || step.text.match(/\bhover\b/))
+            && !!step.selectorRef
+            && !!(step.dataRef || step.value)
+            && step.text.includes('with'),
+        resolver: (step, context) => {
+            const resolved = context.selectorResolver.resolveSelector(step.selectorRef, undefined, step.elementType, step.nth);
+            let dataValue;
+            if (step.value) {
+                dataValue = step.value;
+            }
+            else {
+                dataValue = context.dataResolver.resolveData(step.dataRef, context.featureName);
+            }
+            const { name: _name, ...resolvedWithoutName } = resolved;
+            return {
+                templateName: 'hover-element-with-text',
+                data: { ...resolvedWithoutName, dataValue },
+                comment: `Hover ${step.selectorRef} with text ${step.dataRef || step.value}`,
+            };
+        },
+        priority: 9, // above hover-element (8) so `with {{v}}` filters instead of hovering the first
+    },
+    {
+        name: 'hover-element',
+        // Pure: requests `hover-action` only.
+        platforms: ['web'],
+        platformAlternative: 'there is no hover on a touch screen — content a hover reveals is normally already visible on mobile; if the interaction is genuinely required, tap it with `User tap [X]`, otherwise tag the scenario @manual:M10',
+        matcher: (step) => (step.text.includes('hovers') || step.text.match(/\bhover\b/)) && !!step.selectorRef,
+        resolver: (step, context) => {
+            const resolved = context.selectorResolver.resolveSelector(step.selectorRef, undefined, step.elementType, step.nth);
+            return {
+                templateName: 'hover-action',
+                data: { ...resolved, selectorRef: step.selectorRef },
+                comment: `Hover ${step.selectorRef}`,
+            };
+        },
+        priority: 8,
+    },
+    {
+        name: 'click-by-data-text',
+        matcher: (step) => (step.text.includes('clicks') || step.text.includes('click')) && !step.selectorRef && !!step.dataRef,
+        resolver: (step, context) => {
+            let value;
+            value = context.dataResolver.resolveData(step.dataRef, context.featureName);
+            return {
+                templateName: 'click-action',
+                data: { strategy: 'text', value },
+                comment: `Click ${step.dataRef}`,
+            };
+        },
+        priority: 5,
+    },
+    {
+        name: 'wait-for-time',
+        matcher: (step) => (step.text.includes('wait for') || step.text.includes('waits for')) && /\d+/.test(step.text),
+        resolver: (step, context) => {
+            const match = step.text.match(/(\d+)\s*(seconds?|ms|milliseconds?)/);
+            let duration = 1000;
+            if (match) {
+                const num = parseInt(match[1]);
+                const unit = match[2].toLowerCase();
+                duration = unit.startsWith('s') ? num * 1000 : num;
+            }
+            return {
+                templateName: 'wait-timeout',
+                data: { duration },
+                comment: `Wait for ${duration}ms`,
+            };
+        },
+        priority: 7,
+    },
+    {
+        name: 'wait-for-role-with-text',
+        // Shares `extractWaitState()` with wait-for-element — same four, same reason for the
+        // omissions.
+        states: ['hidden', 'disabled', 'enabled', 'visible'],
+        matcher: (step) => (step.text.includes('wait for') || step.text.includes('waits for')) &&
+            !step.selectorRef &&
+            !!step.dataRef &&
+            !!elementKeywordToRole(step.text),
+        resolver: (step, context) => {
+            const role = elementKeywordToRole(step.text);
+            let dataValue;
+            dataValue = context.dataResolver.resolveData(step.dataRef, context.featureName);
+            const state = extractWaitState(step.text);
+            return {
+                templateName: 'wait-for-role-with-data',
+                data: { role, dataValue, state },
+                comment: `Wait for ${role} with ${step.dataRef} to be ${state}`,
+            };
+        },
+        priority: 11,
+    },
+    {
+        name: 'wait-for-role',
+        matcher: (step) => (step.text.includes('wait for') || step.text.includes('waits for')) &&
+            !step.selectorRef &&
+            !step.dataRef &&
+            !!elementKeywordToRole(step.text),
+        resolver: (step, context) => {
+            const role = elementKeywordToRole(step.text);
+            const state = extractWaitState(step.text);
+            return {
+                templateName: 'wait-for-role',
+                data: { role, state },
+                comment: `Wait for ${role} to be ${state}`,
+            };
+        },
+        priority: 11,
+    },
+    {
+        name: 'wait-for-page',
+        matcher: (step) => (step.text.includes('wait for') || step.text.includes('waits for')) && step.elementType === 'page',
+        resolver: (step, context) => {
+            // Fallback is the feature's declared Path (context.featurePath) — `step.featurePath` is
+            // never populated by the parser, so it always degraded to '/'.
+            const fallbackPath = context.featurePath || '/';
+            let path = fallbackPath;
+            if (step.selectorRef) {
+                try {
+                    const resolved = context.selectorResolver.resolveSelector(step.selectorRef, context.featureName, step.elementType, step.nth);
+                    // Only a `page`-type entry carries a URL in `value`. A key collision with a non-page
+                    // entry (e.g. a role/button sharing the key) must fall back to featurePath, never feed
+                    // its value ('button') into waitForURL. See page-assertion for the mirror guard.
+                    path = resolved.selectorType === 'page' ? (resolved.value || fallbackPath) : fallbackPath;
+                }
+                catch (error) {
+                    // fallback to featurePath
+                }
+            }
+            // Host and path are matched SEPARATELY since #677 — see urlToPatternParts, which now serves
+            // every URL pattern in the compiler so the two assertion forms cannot drift from this wait.
+            return {
+                templateName: 'wait-for-page',
+                data: (0, url_path_regex_1.urlToPatternParts)(path),
+                comment: step.selectorRef ? `Wait for ${step.selectorRef} page` : `Wait for page`,
+            };
+        },
+        priority: 9,
+    },
+    {
+        // FR3 (issue #468): `User wait for [T] table to refresh` — the dedicated wait for
+        // filter/search/pagination round-trips. Signal = the app profile's loading indicator
+        // (qa/app.yaml feedback.loading.indicator, default [aria-busy="true"]): soft-wait for
+        // it to appear (the spinner may already be gone), hard-wait for it to disappear.
+        name: 'wait-table-refresh',
+        matcher: (step) => /\bwait(?:s)?\s+for\b/i.test(step.text) && /\btable\s+to\s+refresh\b/i.test(step.text),
+        resolver: (step, context) => ({
+            templateName: 'wait-table-refresh',
+            data: { indicator: context.appProfile?.loadingIndicator ?? '[aria-busy="true"]' },
+            comment: `Wait for ${step.selectorRef || 'table'} to refresh`,
+        }),
+        priority: 12,
+    },
+    {
+        name: 'wait-for-element-with-text',
+        matcher: (step) => (step.text.includes('wait for') || step.text.includes('waits for')) &&
+            !!step.selectorRef &&
+            !!step.dataRef,
+        resolver: (step, context) => {
+            const resolved = context.selectorResolver.resolveSelector(step.selectorRef, undefined, step.elementType, step.nth);
+            let dataValue;
+            dataValue = context.dataResolver.resolveData(step.dataRef, context.featureName);
+            const state = extractWaitState(step.text);
+            return {
+                templateName: 'wait-for-element-with-text',
+                data: { ...resolved, selectorRef: step.selectorRef, dataValue, state },
+                comment: `Wait for ${step.selectorRef} with ${step.dataRef} to be ${state}`,
+            };
+        },
+        priority: 10,
+    },
+    {
+        name: 'wait-for-element',
+        // Exactly what `extractWaitState()` resolves. Every other clause falls back to 'visible', i.e.
+        // is silently dropped — so it is deliberately NOT declared and now reports SG-E021.
+        states: ['hidden', 'disabled', 'enabled', 'visible'],
+        matcher: (step) => (step.text.includes('wait for') || step.text.includes('waits for')) && !!step.selectorRef,
+        resolver: (step, context) => {
+            const resolved = context.selectorResolver.resolveSelector(step.selectorRef, undefined, step.elementType, step.nth);
+            const state = extractWaitState(step.text);
+            return {
+                templateName: 'wait-for-element',
+                data: { ...resolved, selectorRef: step.selectorRef, state },
+                comment: `Wait for ${step.selectorRef} to be ${state}`,
+            };
+        },
+        priority: 8,
+    },
+    {
+        name: 'toggle-switch',
+        // Matches the unconditional-flip verb "toggle(s)" — e.g. `When User toggles [X]`. Steps that
+        // say `check`/`uncheck [X] toggle` also contain the word "toggle" (as the element-type suffix)
+        // but express a desired on/off STATE, not a blind flip — those must fall through to the
+        // idempotent check-checkbox/uncheck-checkbox patterns below instead (priority 8), so excluding
+        // the check/uncheck verbs here is what makes that routing possible.
+        matcher: (step) => (step.text.includes('toggles') || step.text.match(/\btoggle\b/)) &&
+            !/\b(checks?|unchecks?)\b/.test(step.text) &&
+            !!step.selectorRef,
+        resolver: (step, context) => {
+            const resolved = context.selectorResolver.resolveSelector(step.selectorRef, undefined, step.elementType, step.nth);
+            return {
+                templateName: 'toggle-action',
+                data: { ...resolved, selectorRef: step.selectorRef },
+                comment: `Toggle ${step.selectorRef}`,
+            };
+        },
+        priority: 9,
+    },
+    {
+        name: 'drag-to',
+        matcher: (step) => (step.text.includes('drags') || step.text.match(/\bdrag\b/)) &&
+            /\bto\s+\[/.test(step.text) && !!step.selectorRef,
+        resolver: (step, context) => {
+            // Extract both selector refs: [Source] ... to [Target]
+            const allRefs = step.text.match(/\[([^\]]+)\]/g);
+            if (!allRefs || allRefs.length < 2) {
+                return {
+                    templateName: 'drag-action',
+                    data: { strategy: 'text', value: step.selectorRef, targetStrategy: 'locator', targetValue: 'TODO' },
+                    comment: `Drag ${step.selectorRef} (missing target)`,
+                };
+            }
+            const sourceRef = allRefs[0].slice(1, -1);
+            const targetRef = allRefs[1].slice(1, -1);
+            const sourceResolved = context.selectorResolver.resolveSelector(sourceRef, undefined, step.elementType, step.nth);
+            const targetResolved = context.selectorResolver.resolveSelector(targetRef, undefined, undefined, 0);
+            // C3 — pass the resolved TARGET selector FIELDS, not a built Playwright locator string.
+            // Each adapter's own drag-action template renders the target locator for its own
+            // framework (Playwright: page.getByRole/getByText/...; Appium: an accessibility-id/xpath
+            // $() lookup — it already consumes this exact shape).
+            return {
+                templateName: 'drag-action',
+                data: {
+                    ...sourceResolved,
+                    targetStrategy: targetResolved.strategy,
+                    targetValue: targetResolved.value,
+                    targetName: targetResolved.name,
+                    targetRole: targetResolved.role,
+                    targetRef,
+                },
+                comment: `Drag ${sourceRef} to ${targetRef}`,
+            };
+        },
+        priority: 10,
+    },
+    {
+        name: 'expand-element',
+        matcher: (step) => (step.text.includes('expands') || step.text.match(/\bexpand\b/)) && !!step.selectorRef,
+        resolver: (step, context) => {
+            const resolved = context.selectorResolver.resolveSelector(step.selectorRef, undefined, step.elementType, step.nth);
+            return {
+                templateName: 'expand-action',
+                data: { ...resolved, selectorRef: step.selectorRef, direction: 'expand' },
+                comment: `Expand ${step.selectorRef}`,
+            };
+        },
+        priority: 9,
+    },
+    {
+        name: 'collapse-element',
+        matcher: (step) => (step.text.includes('collapses') || step.text.match(/\bcollapse\b/)) && !!step.selectorRef,
+        resolver: (step, context) => {
+            const resolved = context.selectorResolver.resolveSelector(step.selectorRef, undefined, step.elementType, step.nth);
+            return {
+                templateName: 'expand-action',
+                data: { ...resolved, selectorRef: step.selectorRef, direction: 'collapse' },
+                comment: `Collapse ${step.selectorRef}`,
+            };
+        },
+        priority: 9,
+    },
+];
+//# sourceMappingURL=interaction-patterns.js.map