@sungen/driver-ui 3.1.2-beta.97

package/src/patterns/interaction-patterns.ts

@@ -0,0 +1,465 @@
+import { ParsedStep } from '@sun-asterisk/sungen';
+import { StepPattern } from '@sun-asterisk/sungen';
+
+/**
+ * Extract Playwright waitFor state from step text.
+ * Defaults to 'visible' if no known state keyword is found.
+ */
+function extractWaitState(text: string): string {
+  if (/\bhidden\b/.test(text)) return 'hidden';
+  if (/\bdetached\b/.test(text)) return 'detached';
+  if (/\bvisible\b/.test(text)) return 'visible';
+  return 'visible';
+}
+
+/**
+ * Map a plain element keyword (no brackets) to a Playwright ARIA role.
+ */
+function elementKeywordToRole(text: string): string | null {
+  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: Record<string, string> = {
+    modal: 'dialog',
+    alert: 'alertdialog',
+  };
+  return roleMap[keyword] || keyword;
+}
+
+/**
+ * Interaction patterns: click, hover, press, wait, alert
+ */
+export const interactionPatterns: StepPattern[] = [
+  // === Browser Alert (system dialog) patterns ===
+  // These must appear BEFORE the click that triggers the alert in Gherkin:
+  //   When User click [OK] alert       ← registers page.once('dialog', ...)
+  //   And User click [Delete] button   ← triggers the alert
+  {
+    name: 'alert-accept',
+    matcher: (step: ParsedStep) =>
+      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: ParsedStep) =>
+      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',
+    matcher: (step: ParsedStep) =>
+      step.elementType === 'alert' &&
+      step.text.includes('fill') &&
+      !!step.dataRef,
+    resolver: (step, context) => {
+      let fillValue: string;
+      try {
+        fillValue = context.dataResolver.resolveData(step.dataRef!, context.featureName);
+      } catch {
+        fillValue = `\${${step.dataRef}}`;
+      }
+      return {
+        templateName: 'alert-fill-action',
+        data: { fillValue },
+        comment: `Fill browser prompt with ${step.dataRef}`,
+      };
+    },
+    priority: 20,
+  },
+  {
+    name: 'unknown-element-action',
+    matcher: (step: ParsedStep) => {
+      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: number | undefined;
+      try {
+        const resolved = context.selectorResolver.resolveSelector(
+          step.selectorRef!, context.featureName, step.elementType, step.nth
+        );
+        selectorValue = resolved.value || '';
+        nth = resolved.nth;
+      } catch (error) {
+        selectorValue = '';
+        nth = undefined;
+      }
+
+      let dataValue: string;
+      try {
+        dataValue = context.dataResolver.resolveData(step.dataRef!, context.featureName);
+      } catch (error) {
+        dataValue = `\${${step.dataRef}}`;
+      }
+
+      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 },
+        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
+  },
+  {
+    name: 'click-element-with-text',
+    matcher: (step: ParsedStep) =>
+      (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: string;
+      if (step.value) {
+        dataValue = step.value;
+      } else {
+        try {
+          dataValue = context.dataResolver.resolveData(step.dataRef!, context.featureName);
+        } catch {
+          dataValue = `\${${step.dataRef}}`;
+        }
+      }
+
+      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: ParsedStep) =>
+      (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: ParsedStep) =>
+      (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,
+  },
+  {
+    name: 'hover-element',
+    matcher: (step: ParsedStep) =>
+      (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: ParsedStep) =>
+      (step.text.includes('clicks') || step.text.includes('click')) && !step.selectorRef && !!step.dataRef,
+    resolver: (step, context) => {
+      let value: string;
+      try {
+        value = context.dataResolver.resolveData(step.dataRef!, context.featureName);
+      } catch (error) {
+        value = `\${${step.dataRef}}`;
+      }
+
+      return {
+        templateName: 'click-action',
+        data: { strategy: 'text', value },
+        comment: `Click ${step.dataRef}`,
+      };
+    },
+    priority: 5,
+  },
+  {
+    name: 'wait-for-time',
+    matcher: (step: ParsedStep) =>
+      (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',
+    matcher: (step: ParsedStep) =>
+      (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: string;
+      try {
+        dataValue = context.dataResolver.resolveData(step.dataRef!, context.featureName);
+      } catch (error) {
+        dataValue = `\${${step.dataRef}}`;
+      }
+
+      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: ParsedStep) =>
+      (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: ParsedStep) =>
+      (step.text.includes('wait for') || step.text.includes('waits for')) && step.elementType === 'page',
+    resolver: (step, context) => {
+      let path = step.featurePath || '/';
+
+      if (step.selectorRef) {
+        try {
+          const resolved = context.selectorResolver.resolveSelector(
+            step.selectorRef, context.featureName, step.elementType, step.nth
+          );
+          path = resolved.value || path;
+        } catch (error) {
+          // fallback to featurePath
+        }
+      }
+
+      const isAbsoluteUrl = /^https?:\/\//.test(path);
+      let pathRegex: string;
+      if (isAbsoluteUrl) {
+        const url = new URL(path);
+        const hostEscaped = url.hostname.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+        const pathEscaped = url.pathname !== '/' ? url.pathname.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&') : '';
+        pathRegex = hostEscaped + pathEscaped;
+      } else {
+        pathRegex = path.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+      }
+
+      return {
+        templateName: 'wait-for-page',
+        data: { pathRegex },
+        comment: step.selectorRef ? `Wait for ${step.selectorRef} page` : `Wait for page`,
+      };
+    },
+    priority: 9,
+  },
+  {
+    name: 'wait-for-element-with-text',
+    matcher: (step: ParsedStep) =>
+      (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: string;
+      try {
+        dataValue = context.dataResolver.resolveData(step.dataRef!, context.featureName);
+      } catch (error) {
+        dataValue = `\${${step.dataRef}}`;
+      }
+
+      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',
+    matcher: (step: ParsedStep) =>
+      (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',
+    matcher: (step: ParsedStep) =>
+      (step.text.includes('toggles') || step.text.match(/\btoggle\b/)) && !!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: ParsedStep) =>
+      (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, targetLocator: 'page.locator(\'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);
+
+      // Build target locator expression from resolved selector
+      let targetLocator: string;
+      switch (targetResolved.strategy) {
+        case 'role':
+          targetLocator = targetResolved.name
+            ? `page.getByRole('${targetResolved.role}', { name: '${targetResolved.name}' })`
+            : `page.getByRole('${targetResolved.role}')`;
+          break;
+        case 'testid':
+          targetLocator = `page.getByTestId('${targetResolved.value}')`;
+          break;
+        case 'text':
+          targetLocator = `page.getByText('${targetResolved.value}')`;
+          break;
+        case 'locator':
+          targetLocator = `page.locator('${targetResolved.value}')`;
+          break;
+        default:
+          targetLocator = `page.getByText('${targetRef}')`;
+      }
+
+      return {
+        templateName: 'drag-action',
+        data: { ...sourceResolved, targetLocator },
+        comment: `Drag ${sourceRef} to ${targetRef}`,
+      };
+    },
+    priority: 10,
+  },
+  {
+    name: 'expand-element',
+    matcher: (step: ParsedStep) =>
+      (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: ParsedStep) =>
+      (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,
+  },
+];

package/src/patterns/keyboard-patterns.ts

@@ -0,0 +1,51 @@
+/**
+ * Keyboard Patterns
+ * Handles: press Key key, press Key on [Target] type
+ */
+
+import { StepPattern } from '@sun-asterisk/sungen';
+
+export const keyboardPatterns: StepPattern[] = [
+  {
+    name: 'press-key-global',
+    matcher: (step) => {
+      const text = step.text.toLowerCase();
+      return /\bpress(?:es)?\s+\w+\s+key\b/.test(text) && !text.includes(' on ');
+    },
+    resolver: (step, context) => {
+      // Extract key name: "User press Escape key" → "Escape"
+      const match = step.text.match(/press(?:es)?\s+(\w+)\s+key/i);
+      const key = match ? match[1] : 'Enter';
+
+      return {
+        templateName: 'keyboard-global-action',
+        data: { key },
+        comment: `Press ${key} key`,
+      };
+    },
+    priority: 12,
+  },
+  {
+    name: 'press-key-on-element',
+    matcher: (step) => {
+      const text = step.text.toLowerCase();
+      return /\bpress(?:es)?\s+\w+\s+on\b/.test(text) && !!step.selectorRef;
+    },
+    resolver: (step, context) => {
+      // Extract key: "User press Enter on [Search] field" → "Enter"
+      const match = step.text.match(/press(?:es)?\s+(\w+)\s+on/i);
+      const key = match ? match[1] : 'Enter';
+
+      const resolved = context.selectorResolver.resolveSelector(
+        step.selectorRef!, context.featureName, step.elementType, step.nth
+      );
+
+      return {
+        templateName: 'press-action',
+        data: { ...resolved, key },
+        comment: `Press ${key} on ${step.selectorRef}`,
+      };
+    },
+    priority: 12,
+  },
+];

package/src/patterns/navigation-patterns.ts

@@ -0,0 +1,140 @@
+import { ParsedStep } from '@sun-asterisk/sungen';
+import { StepPattern } from '@sun-asterisk/sungen';
+import { inferPath, resolvePathVariables, getPathCode } from '@sun-asterisk/sungen';
+
+/**
+ * Navigation patterns: goto, navigate, open page
+ */
+export const navigationPatterns: StepPattern[] = [
+  {
+    name: 'open-page-type',
+    matcher: (step: ParsedStep) =>
+      (step.text.includes('open') || step.text.includes('opens') || step.text.includes('is on') || step.text.includes('navigate to')) &&
+      step.elementType === 'page',
+    resolver: (step, context) => {
+      const isThen = context.effectiveKeyword === 'Then';
+      // Cross-screen page refs (e.g. Then User is on [dashboard] page) won't be in the
+      // current screen's selectors. Fall back to /<ref>/ for assertion paths instead of
+      // the current featurePath, which would silently make the assertion always pass.
+      const pathFallback = isThen && step.selectorRef
+        ? `/${step.selectorRef}/`
+        : (context.featurePath || '/');
+      let path = pathFallback;
+
+      if (step.selectorRef) {
+        try {
+          const resolved = context.selectorResolver.resolveSelector(
+            step.selectorRef, context.featureName, step.elementType, step.nth
+          );
+          path = resolved.value || pathFallback;
+        } catch (error) {
+          path = pathFallback;
+        }
+      }
+
+      const finalPath = resolvePathVariables(path, context.scenarioSteps || []);
+      const isAbsoluteUrl = /^https?:\/\//.test(finalPath);
+
+      // Then User is on [X] page — assert URL, don't navigate.
+      if (isThen) {
+        return {
+          templateName: 'route-assertion',
+          data: { path: finalPath },
+          comment: step.selectorRef ? `Assert on ${step.selectorRef} page` : `Assert page route`,
+        };
+      }
+
+      return {
+        templateName: 'navigation',
+        data: { baseURL: isAbsoluteUrl ? undefined : context.baseURL, path: finalPath },
+        comment: step.selectorRef ? `Open ${step.selectorRef} page` : `Navigate to page`,
+      };
+    },
+    priority: 16,
+  },
+  {
+    name: 'open-page',
+    matcher: (step: ParsedStep) =>
+      (step.text.includes('open') || step.text.includes('opens')) &&
+      step.text.includes('page') &&
+      step.elementType !== 'page',
+    resolver: (step, context) => {
+      const pageMatch = step.text.match(/open[s]?\s+\[([^\]]+)\]/i) ||
+                       step.text.match(/open[s]?\s+"([^"]+)"/i);
+      const pageName = pageMatch ? pageMatch[1] : 'page';
+
+      const inferredPath = inferPath(context.featurePath, {
+        featureName: context.featureName,
+        screenName: context.screenName,
+      });
+      const resolvedPath = resolvePathVariables(inferredPath, context.scenarioSteps || []);
+      const pathCode = getPathCode(resolvedPath);
+      const cleanPath = pathCode.replace(/^['`]|['`]$/g, '');
+      const isAbsoluteUrl = /^https?:\/\//.test(cleanPath);
+
+      return {
+        templateName: 'navigation',
+        data: { baseURL: isAbsoluteUrl ? undefined : context.baseURL, path: cleanPath },
+        comment: `Open ${pageName}`,
+      };
+    },
+    priority: 15,
+  },
+  {
+    name: 'navigate-to-route',
+    matcher: (step: ParsedStep) =>
+      (step.text.includes('navigate to') || step.text.includes('navigates to') || step.text.includes('is on')) &&
+      !!(step.selectorRef || step.dataRef),
+    resolver: (step, context) => {
+      const route = step.selectorRef || step.dataRef;
+      const isThen = context.effectiveKeyword === 'Then';
+
+      const inferredPath = inferPath(context.featurePath, {
+        featureName: context.featureName,
+        screenName: context.screenName,
+      });
+      const resolvedPath = resolvePathVariables(inferredPath, context.scenarioSteps || []);
+      const pathCode = getPathCode(resolvedPath);
+      const cleanPath = pathCode.replace(/^['`]|['`]$/g, '');
+      const isAbsoluteUrl = /^https?:\/\//.test(cleanPath);
+
+      if (isThen) {
+        return {
+          templateName: 'route-assertion',
+          data: { path: cleanPath },
+          comment: `Assert on ${route}`,
+        };
+      }
+
+      return {
+        templateName: 'navigation',
+        data: { baseURL: isAbsoluteUrl ? undefined : context.baseURL, path: cleanPath },
+        comment: `Navigate to ${route}`,
+      };
+    },
+    priority: 10,
+  },
+  {
+    name: 'route-assertion',
+    matcher: (step: ParsedStep) =>
+      (step.text.includes('should see route') || step.text.includes('should remain on')) &&
+      !!(step.selectorRef || step.dataRef),
+    resolver: (step, context) => {
+      const route = step.selectorRef || step.dataRef;
+
+      const inferredPath = inferPath(context.featurePath, {
+        featureName: context.featureName,
+        screenName: context.screenName,
+      });
+      const resolvedPath = resolvePathVariables(inferredPath, context.scenarioSteps || []);
+      const pathCode = getPathCode(resolvedPath);
+
+      return {
+        templateName: 'route-assertion',
+        data: { path: pathCode.replace(/^['`]|['`]$/g, '') },
+        comment: `Assert current route is ${route}`,
+      };
+    },
+    priority: 10,
+  },
+];

package/src/patterns/scope-patterns.ts

@@ -0,0 +1,40 @@
+/**
+ * Scope Patterns
+ * Handles: switch to [Target] frame, switch to [main] frame
+ */
+
+import { StepPattern } from '@sun-asterisk/sungen';
+
+export const scopePatterns: StepPattern[] = [
+  {
+    name: 'switch-to-frame',
+    matcher: (step) => {
+      return /\bswitch(?:es)?\s+to\b/i.test(step.text) &&
+             (step.elementType === 'frame' || step.elementType === 'iframe');
+    },
+    resolver: (step, context) => {
+      const selectorRef = step.selectorRef || '';
+
+      // "switch to [main] frame" → reset to page context
+      if (selectorRef.toLowerCase() === 'main') {
+        return {
+          templateName: 'frame-exit-action',
+          data: {},
+          comment: 'Exit frame scope, return to main page',
+        };
+      }
+
+      // "switch to [Payment] frame" → enter frame scope
+      const resolved = context.selectorResolver.resolveSelector(
+        selectorRef, context.featureName, 'frame', step.nth
+      );
+
+      return {
+        templateName: 'frame-enter-action',
+        data: { ...resolved, frameName: selectorRef },
+        comment: `Switch to ${selectorRef} frame`,
+      };
+    },
+    priority: 11,
+  },
+];