swipium 1.4.0 → 2.0.0

package/dist/automationGen/jsEmitter.js

@@ -1,16 +1,75 @@
-// SWIPIUM-REQ-04 — JS/TS WebdriverIO + Appium emitter. Pure: turns the shared Appium model into a
+// JS/TS WebdriverIO + Appium emitter. Pure: turns the shared Appium model into a
 // runnable WebdriverIO POM suite (page/screen classes with locator getters + action methods, env-
 // driven capabilities, structured waits). No XPath is ever emitted; coordinate fallbacks are marked
 // non-release-grade. Aligns with the Appium JS quickstart (WebdriverIO) locator-strategy guidance.
+import { defaultPlatformOf } from './platformResolve.js';
+import { NameAllocator, UnemittableStepError, checkDirection, checkKey, className, commentSafe, isJsIdentifier, jsMemberName, pascalWords, screensOf, } from './identifiers.js';
 const DEFAULT_TIMEOUT = 15000;
-function pascal(s) {
-    const parts = s.replace(/[^A-Za-z0-9]+/g, ' ').trim().split(/\s+/).filter(Boolean);
-    return parts.map((p) => p[0].toUpperCase() + p.slice(1)).join('') || 'X';
+const MAX_SCROLLS = 8;
+/** Every member BaseScreen declares. A generated field/method must never shadow one (a field named
+ *  `tap` would replace the tap() helper, and in TS it is a type error). */
+const JS_BASE_MEMBERS = [
+    'constructor',
+    'element',
+    'tap',
+    'type',
+    'typeFocused',
+    'scrollTo',
+    'scrollToText',
+    'scrollOnce',
+    'isVisible',
+    'assertVisible',
+    'assertTextVisible',
+    'textSelector',
+    'tapAt',
+    'pressKey',
+    'swipe',
+    'openUrl',
+];
+function methodKey(action, element) {
+    return `${action}|${element}`;
 }
-/** Env var (SWIPIUM_TEST_PASSWORD) → a stable testData key (password). */
+function planJsNames(model) {
+    const classes = new NameAllocator(['BaseScreen', 'TestData', 'PlatformLocator'], (s) => s.toLowerCase());
+    const instances = new NameAllocator(['testData', 'driver', 'browser', 'describe', 'it', 'expect', '$', '$$']);
+    const plan = new Map();
+    for (const screen of screensOf(model)) {
+        const cls = classes.alloc(className(screen.className));
+        const instance = instances.alloc(cls[0].toLowerCase() + cls.slice(1));
+        const members = new NameAllocator(JS_BASE_MEMBERS);
+        const fields = new Map();
+        for (const el of screen.elements)
+            if (!fields.has(el.name))
+                fields.set(el.name, members.alloc(jsMemberName(el.name)));
+        const methods = new Map();
+        for (const s of model.steps) {
+            if (s.screen !== screen.className || !s.element)
+                continue;
+            const field = fields.get(s.element);
+            if (!field) {
+                throw new UnemittableStepError(`cannot emit ${s.action} step on ${screen.className}: element ${JSON.stringify(s.element)} is not declared on that screen`);
+            }
+            const key = methodKey(s.action, s.element);
+            if (methods.has(key))
+                continue;
+            methods.set(key, members.alloc(methodBase(s.action, pascalWords(field) || 'Element')));
+        }
+        plan.set(screen.className, { cls, instance, fields, methods });
+    }
+    return plan;
+}
+function jsProp(obj, key) {
+    return isJsIdentifier(key) ? `${obj}.${key}` : `${obj}[${JSON.stringify(key)}]`;
+}
+/** Env var (SWIPIUM_TEST_PASSWORD) > a stable testData key (password). */
 export function varToKey(v) {
     const stripped = v.replace(/^SWIPIUM_(TEST_)?/i, '');
-    const parts = stripped.replace(/[^A-Za-z0-9]+/g, ' ').trim().toLowerCase().split(/\s+/).filter(Boolean);
+    const parts = stripped
+        .replace(/[^A-Za-z0-9]+/g, ' ')
+        .trim()
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean);
     if (!parts.length)
         return 'value';
     return parts.map((p, i) => (i === 0 ? p : p[0].toUpperCase() + p.slice(1))).join('');
@@ -51,8 +110,11 @@ function platformLocatorLiteral(el) {
 export function emitJsSuite(input) {
     const ts = input.language === 'typescript';
     const ext = ts ? 'ts' : 'js';
-    const t = (annotation) => (ts ? annotation : '');
     const files = [];
+    // Plan every class/field/method name up front (H4) and validate every step is emittable (§4);
+    // generation fails loudly here rather than writing a suite with silent no-op steps.
+    const names = planJsNames(input.model);
+    const smoke = smokeTest(input.model, names);
     files.push({ path: 'package.json', content: packageJson(input) });
     if (ts)
         files.push({ path: 'tsconfig.json', content: tsconfigJson() });
@@ -61,11 +123,12 @@ export function emitJsSuite(input) {
     files.push({ path: `src/utils/locators.${ext}`, content: locatorsUtil(ts) });
     files.push({ path: `src/utils/waits.${ext}`, content: waitsUtil(ts) });
     files.push({ path: `src/screens/BaseScreen.${ext}`, content: baseScreen(ts) });
-    for (const screen of input.model.screens) {
-        files.push({ path: `src/screens/${screen.className}.${ext}`, content: screenClass(screen, input.model.steps, ts, t) });
+    for (const screen of screensOf(input.model)) {
+        const n = names.get(screen.className);
+        files.push({ path: `src/screens/${n.cls}.${ext}`, content: screenClass(screen, n, input.model.steps, ts) });
     }
     files.push({ path: `src/data/testData.${ext}`, content: testData(input.model, ts) });
-    files.push({ path: `test/smoke.e2e.${ext}`, content: smokeTest(input.model, ts) });
+    files.push({ path: `test/smoke.e2e.${ext}`, content: smoke });
     return files;
 }
 function packageJson(input) {
@@ -75,7 +138,7 @@ function packageJson(input) {
         name,
         private: true,
         type: 'module',
-        description: 'Generated by Swipium — WebdriverIO + Appium POM suite (review before committing).',
+        description: 'Generated by Swipium: WebdriverIO + Appium POM suite (review before committing).',
         scripts: {
             test: 'wdio run ./wdio.conf.' + (ts ? 'ts' : 'js'),
         },
@@ -92,7 +155,7 @@ function packageJson(input) {
     return JSON.stringify(pkg, null, 2) + '\n';
 }
 function tsconfigJson() {
-    return JSON.stringify({
+    return (JSON.stringify({
         compilerOptions: {
             target: 'ES2022',
             module: 'NodeNext',
@@ -103,10 +166,10 @@ function tsconfigJson() {
             skipLibCheck: true,
         },
         include: ['src/**/*.ts', 'test/**/*.ts', 'wdio.conf.ts'],
-    }, null, 2) + '\n';
+    }, null, 2) + '\n');
 }
 function wdioConf(ts, ext) {
-    const header = '// Generated by Swipium. WebdriverIO + Appium config — capabilities come from env (see src/config/capabilities).';
+    const header = '// Generated by Swipium. WebdriverIO + Appium config. Capabilities come from env (see src/config/capabilities).';
     const importLine = `import { buildCapabilities } from './src/config/capabilities.js';`;
     const typeAnno = ts ? `\nimport type { Options } from '@wdio/types';\n` : '\n';
     const cfgType = ts ? ': WebdriverIO.Config' : '';
@@ -130,38 +193,39 @@ export const config${cfgType} = {
 `;
 }
 function capabilities(input, ts) {
-    const android = input.model.platforms.android;
-    const ios = input.model.platforms.ios;
+    const primary = defaultPlatformOf(input.profile, input.model);
     const ret = ts ? ': WebdriverIO.Capabilities' : '';
     const appId = input.appId ?? '';
     const lines = [];
-    lines.push('// Generated by Swipium. ALL device/app config is environment-driven — no secrets, no hardcoded paths.');
-    lines.push('// Android is the default fast-feedback backend; set SWIPIUM_PLATFORM=ios to target iOS (XCUITest).');
+    lines.push('// Generated by Swipium. ALL device/app config is environment-driven: no secrets, no hardcoded paths.');
+    lines.push(primary === 'ios'
+        ? '// iOS (XCUITest) is the default for this suite; set SWIPIUM_PLATFORM=android to target Android (UiAutomator2).'
+        : '// Android (UiAutomator2) is the default for this suite; set SWIPIUM_PLATFORM=ios to target iOS (XCUITest).');
     lines.push('');
     lines.push(`export function buildCapabilities()${ret} {`);
-    lines.push(`  const platform = (process.env.SWIPIUM_PLATFORM || ${JSON.stringify(android ? 'android' : 'ios')}).toLowerCase();`);
-    lines.push('  if (platform === \'ios\') {');
+    lines.push(`  const platform = (process.env.SWIPIUM_PLATFORM || ${JSON.stringify(primary)}).toLowerCase();`);
+    lines.push("  if (platform === 'ios') {");
     lines.push('    return {');
-    lines.push('      platformName: \'iOS\',');
-    lines.push('      \'appium:automationName\': \'XCUITest\',');
-    lines.push('      \'appium:deviceName\': process.env.IOS_DEVICE_NAME || \'iPhone 15\',');
-    lines.push('      \'appium:platformVersion\': process.env.IOS_PLATFORM_VERSION,');
+    lines.push("      platformName: 'iOS',");
+    lines.push("      'appium:automationName': 'XCUITest',");
+    lines.push("      'appium:deviceName': process.env.IOS_DEVICE_NAME || 'iPhone 15',");
+    lines.push("      'appium:platformVersion': process.env.IOS_PLATFORM_VERSION,");
     lines.push(`      'appium:bundleId': process.env.IOS_BUNDLE_ID${appId ? ` || ${JSON.stringify(appId)}` : ''},`);
-    lines.push('      \'appium:app\': process.env.IOS_APP_PATH,');
-    lines.push('      \'appium:udid\': process.env.IOS_UDID,');
-    lines.push('      \'appium:noReset\': process.env.SWIPIUM_NO_RESET === \'true\',');
+    lines.push("      'appium:app': process.env.IOS_APP_PATH,");
+    lines.push("      'appium:udid': process.env.IOS_UDID,");
+    lines.push("      'appium:noReset': process.env.SWIPIUM_NO_RESET === 'true',");
     lines.push('    };');
     lines.push('  }');
-    lines.push('  // Android UiAutomator2 (default).');
+    lines.push('  // Android UiAutomator2.');
     lines.push('  return {');
-    lines.push('    platformName: \'Android\',');
-    lines.push('    \'appium:automationName\': \'UiAutomator2\',');
-    lines.push('    \'appium:deviceName\': process.env.ANDROID_DEVICE_NAME || \'Android Emulator\',');
+    lines.push("    platformName: 'Android',");
+    lines.push("    'appium:automationName': 'UiAutomator2',");
+    lines.push("    'appium:deviceName': process.env.ANDROID_DEVICE_NAME || 'Android Emulator',");
     lines.push(`    'appium:appPackage': process.env.ANDROID_APP_PACKAGE${appId ? ` || ${JSON.stringify(appId)}` : ''},`);
-    lines.push('    \'appium:appActivity\': process.env.ANDROID_APP_ACTIVITY,');
-    lines.push('    \'appium:app\': process.env.ANDROID_APP_PATH,');
-    lines.push('    \'appium:udid\': process.env.ANDROID_UDID,');
-    lines.push('    \'appium:noReset\': process.env.SWIPIUM_NO_RESET === \'true\',');
+    lines.push("    'appium:appActivity': process.env.ANDROID_APP_ACTIVITY,");
+    lines.push("    'appium:app': process.env.ANDROID_APP_PATH,");
+    lines.push("    'appium:udid': process.env.ANDROID_UDID,");
+    lines.push("    'appium:noReset': process.env.SWIPIUM_NO_RESET === 'true',");
     lines.push('  };');
     lines.push('}');
     lines.push('');
@@ -169,7 +233,7 @@ function capabilities(input, ts) {
 }
 function locatorsUtil(ts) {
     const typeBlock = ts
-        ? `export interface PlatformLocator {\n  android?: string;\n  ios?: string;\n  /** "x,y" coordinate fallback — non-release-grade. */\n  coordinate?: string;\n}\n\n`
+        ? `export interface PlatformLocator {\n  android?: string;\n  ios?: string;\n  /** "x,y" coordinate fallback, non-release-grade. */\n  coordinate?: string;\n}\n\n`
         : '';
     const param = ts ? 'loc: PlatformLocator' : 'loc';
     const ret = ts ? ': string' : '';
@@ -179,7 +243,7 @@ ${typeBlock}export function resolveSelector(${param})${ret} {
   const android = typeof driver !== 'undefined' ? driver.isAndroid : true;
   const selector = android ? loc.android : loc.ios;
   if (!selector) {
-    throw new Error('No durable selector for this platform — element relies on a coordinate fallback (non-release-grade). Add an accessibility id / resource-id / testID.');
+    throw new Error('No durable selector for this platform. Element relies on a coordinate fallback (non-release-grade). Add an accessibility id / resource-id / testID.');
   }
   return selector;
 }
@@ -194,7 +258,7 @@ export function coordinateOf(${param})${ts ? ': [number, number] | undefined' :
 function waitsUtil(ts) {
     const elAnno = ts ? ': WebdriverIO.Element' : '';
     const numAnno = ts ? ': number' : '';
-    return `// Generated by Swipium. Structured waits — never a bare sleep. Auto-wait before interaction
+    return `// Generated by Swipium. Structured waits, never a bare sleep. Auto-wait before interaction
 // (Playwright-style resilience, applied to mobile Appium).
 export const DEFAULT_TIMEOUT = ${DEFAULT_TIMEOUT};
 
@@ -212,36 +276,92 @@ export async function waitEnabled(el${elAnno}, timeout${numAnno} = DEFAULT_TIMEO
 function baseScreen(ts) {
     const locImport = ts ? `import type { PlatformLocator } from '../utils/locators.js';\n` : '';
     const p = (name, type) => (ts ? `${name}: ${type}` : name);
+    // H3: TS-only modifiers/annotations are gated on the TypeScript flag so the .js output parses.
+    const prot = ts ? 'protected ' : '';
+    const dirType = ts ? `: 'up' | 'down' | 'left' | 'right'` : '';
     return `// Generated by Swipium. BaseScreen centralizes all element interaction so selectors are
 // resolved per-platform in ONE place and tests never touch raw selectors.
-${locImport}import { resolveSelector, coordinateOf } from '../utils/locators.js';
-import { waitVisible, waitEnabled, DEFAULT_TIMEOUT } from '../utils/waits.js';
+${locImport}import { resolveSelector } from '../utils/locators.js';
+import { waitVisible, waitEnabled } from '../utils/waits.js';
+
+/** Upper bound on scroll gestures while looking for an element, so never an endless loop. */
+export const MAX_SCROLLS = ${MAX_SCROLLS};
 
 export class BaseScreen {
-  protected async element(${p('loc', 'PlatformLocator')}) {
+  ${prot}async element(${p('loc', 'PlatformLocator')}) {
     // @ts-ignore wdio global
     return $(resolveSelector(loc));
   }
 
-  protected async tap(${p('loc', 'PlatformLocator')}) {
+  ${prot}async tap(${p('loc', 'PlatformLocator')}) {
     const el = await this.element(loc);
     await waitEnabled(await waitVisible(el));
     await el.click();
   }
 
-  protected async type(${p('loc', 'PlatformLocator')}, ${p('value', 'string')}) {
+  ${prot}async type(${p('loc', 'PlatformLocator')}, ${p('value', 'string')}) {
     const el = await this.element(loc);
     await waitVisible(el);
     await el.setValue(value);
   }
 
-  protected async scrollTo(${p('loc', 'PlatformLocator')}) {
-    const el = await this.element(loc);
-    await el.scrollIntoView();
-    await waitVisible(el);
+  /** Type into whichever field currently has focus (the recording had no locator for it). */
+  async typeFocused(${p('value', 'string')}) {
+    // @ts-ignore wdio global
+    const active = await $(await driver.getActiveElement());
+    await active.addValue(value);
+  }
+
+  /**
+   * One real content-scroll gesture. direction is the CONTENT direction: 'down' reveals what is below.
+   * Android: UiAutomator2 \`mobile: scrollGesture\` (returns false once the end is reached).
+   * iOS: XCUITest \`mobile: scroll\`.
+   */
+  async scrollOnce(${p('direction', 'string')} = 'down')${ts ? ': Promise<boolean>' : ''} {
+    // @ts-ignore wdio global
+    if (driver.isAndroid) {
+      // @ts-ignore wdio global
+      const { width, height } = await driver.getWindowSize();
+      // @ts-ignore wdio global
+      const canScrollMore = await driver.execute('mobile: scrollGesture', {
+        left: Math.round(width * 0.1),
+        top: Math.round(height * 0.2),
+        width: Math.round(width * 0.8),
+        height: Math.round(height * 0.6),
+        direction,
+        percent: 0.75,
+      });
+      return canScrollMore !== false;
+    }
+    // @ts-ignore wdio global
+    await driver.execute('mobile: scroll', { direction });
+    return true;
+  }
+
+  /** Scroll (bounded by maxScrolls) until the element is displayed; throws if it never appears. */
+  ${prot}async scrollTo(${p('loc', 'PlatformLocator')}, ${p('direction', 'string')} = 'down', ${p('maxScrolls', 'number')} = MAX_SCROLLS) {
+    let atEnd = false;
+    for (let i = 0; i <= maxScrolls; i++) {
+      if (await this.isVisible(loc)) return;
+      if (i === maxScrolls || atEnd) break;
+      atEnd = !(await this.scrollOnce(direction));
+    }
+    throw new Error('Element not visible after scrolling ' + direction + ' (max ' + maxScrolls + ' scrolls)');
   }
 
-  protected async isVisible(${p('loc', 'PlatformLocator')})${ts ? ': Promise<boolean>' : ''} {
+  /** Scroll (bounded) until an element whose text/label contains \`text\` is displayed. */
+  async scrollToText(${p('text', 'string')}, ${p('direction', 'string')} = 'down', ${p('maxScrolls', 'number')} = MAX_SCROLLS) {
+    let atEnd = false;
+    for (let i = 0; i <= maxScrolls; i++) {
+      // @ts-ignore wdio global
+      if (await $(this.textSelector(text)).isDisplayed()) return;
+      if (i === maxScrolls || atEnd) break;
+      atEnd = !(await this.scrollOnce(direction));
+    }
+    throw new Error('Text ' + JSON.stringify(text) + ' not visible after scrolling ' + direction + ' (max ' + maxScrolls + ' scrolls)');
+  }
+
+  ${prot}async isVisible(${p('loc', 'PlatformLocator')})${ts ? ': Promise<boolean>' : ''} {
     const el = await this.element(loc);
     return el.isDisplayed();
   }
@@ -251,28 +371,60 @@ export class BaseScreen {
     await waitVisible(el);
   }
 
+  /** Platform-appropriate "text contains" selector. JSON.stringify escapes backslashes and quotes. */
+  textSelector(${p('text', 'string')})${ts ? ': string' : ''} {
+    // @ts-ignore wdio global
+    if (driver.isAndroid) return 'android=new UiSelector().textContains(' + JSON.stringify(text) + ')';
+    return '-ios predicate string:label CONTAINS ' + JSON.stringify(text) + ' OR name CONTAINS ' + JSON.stringify(text);
+  }
+
   async assertTextVisible(${p('text', 'string')}) {
-    // Non-release-grade text/OCR assertion — prefer a structured locator.
+    // Non-release-grade text/OCR assertion. Prefer a structured locator.
     // @ts-ignore wdio global
-    const el = await $('android=new UiSelector().textContains(' + JSON.stringify(text) + ')');
+    const el = await $(this.textSelector(text));
     await waitVisible(el);
   }
 
-  // Coordinate tap — brittle, non-release-grade fallback. Only used when no durable locator exists.
+  // Coordinate tap: brittle, non-release-grade fallback. Only used when no durable locator exists.
   async tapAt(${p('x', 'number')}, ${p('y', 'number')}) {
     // @ts-ignore wdio global
-    await driver.action('pointer')
+    await driver.action('pointer', { parameters: { pointerType: 'touch' } })
       .move({ x, y }).down().pause(50).up().perform();
   }
 
-  async pressKey(${p('key', 'string')}) {
-    // @ts-ignore wdio global
-    if (driver.isAndroid && key === 'back') { await driver.back(); return; }
+  async pressKey(${p('key', `'back' | 'home' | 'enter'`)}) {
     // @ts-ignore wdio global
-    await driver.keys([key]);
+    const android = driver.isAndroid;
+    if (key === 'back') {
+      // @ts-ignore wdio global
+      if (android) { await driver.back(); return; }
+      // iOS has no system back key: swipe in from the left edge (UINavigationController back gesture).
+      // @ts-ignore wdio global
+      const { width, height } = await driver.getWindowSize();
+      // @ts-ignore wdio global
+      await driver.action('pointer', { parameters: { pointerType: 'touch' } })
+        .move({ x: 2, y: Math.round(height / 2) }).down().pause(50)
+        .move({ duration: 400, x: Math.round(width * 0.7), y: Math.round(height / 2) }).up().perform();
+      return;
+    }
+    if (key === 'home') {
+      // @ts-ignore wdio global
+      if (android) await driver.execute('mobile: pressKey', { keycode: 3 });
+      // @ts-ignore wdio global
+      else await driver.execute('mobile: pressButton', { name: 'home' });
+      return;
+    }
+    if (key === 'enter') {
+      // @ts-ignore wdio global
+      if (android) { await driver.execute('mobile: pressKey', { keycode: 66 }); return; }
+      await this.typeFocused('\\n');
+      return;
+    }
+    throw new Error('Unsupported key: ' + key);
   }
 
-  async swipe(${p('direction', 'string')}) {
+  /** Real window-size-relative swipe. direction is the FINGER direction ('up' drags from bottom to top). */
+  async swipe(${p('direction', dirType.slice(2) || 'string')}) {
     // @ts-ignore wdio global
     const { width, height } = await driver.getWindowSize();
     const cx = Math.round(width / 2), cy = Math.round(height / 2);
@@ -282,9 +434,11 @@ export class BaseScreen {
       left: [Math.round(width * 0.8), cy, Math.round(width * 0.2), cy],
       right: [Math.round(width * 0.2), cy, Math.round(width * 0.8), cy],
     };
-    const [x1, y1, x2, y2] = map[${ts ? 'direction as keyof typeof map' : 'direction'}] || map.up;
+    const vec = map[direction];
+    if (!vec) throw new Error('Unsupported swipe direction: ' + direction);
+    const [x1, y1, x2, y2] = vec;
     // @ts-ignore wdio global
-    await driver.action('pointer')
+    await driver.action('pointer', { parameters: { pointerType: 'touch' } })
       .move({ x: x1, y: y1 }).down().pause(100).move({ duration: 600, x: x2, y: y2 }).up().perform();
   }
 
@@ -295,9 +449,8 @@ export class BaseScreen {
 }
 `;
 }
-/** Per-screen action method name for an (element, action) pair. */
-function methodName(action, element) {
-    const E = pascal(element);
+/** Base (pre-dedupe) action-method name for an (action, element) pair. */
+function methodBase(action, E) {
     switch (action) {
         case 'tap':
             return `tap${E}`;
@@ -308,22 +461,23 @@ function methodName(action, element) {
         case 'assertVisible':
             return `assert${E}Visible`;
         default:
-            return `act${E}`;
+            throw new UnemittableStepError(`cannot emit a ${action} step bound to an element: no generated action exists for it`);
     }
 }
-function screenClass(screen, steps, ts, t) {
-    const locImport = ts ? `import type { PlatformLocator } from '../utils/locators.js';\n` : '';
+function screenClass(screen, names, steps, ts) {
     const lines = [];
-    lines.push(`// Generated by Swipium. Screen object for ${screen.pageName}${screen.screenSignature ? ` (${screen.screenSignature})` : ''}.`);
+    lines.push(`// Generated by Swipium. Screen object for ${commentSafe(screen.pageName)}${screen.screenSignature ? ` (${commentSafe(screen.screenSignature)})` : ''}.`);
     lines.push('// Selectors are centralized here; tests call the action methods below.');
-    lines.push(locImport.trimEnd());
+    if (ts)
+        lines.push(`import type { PlatformLocator } from '../utils/locators.js';`);
     lines.push(`import { BaseScreen } from './BaseScreen.js';`);
     lines.push('');
-    lines.push(`export class ${screen.className} extends BaseScreen {`);
-    // Locators (centralized).
+    lines.push(`export class ${names.cls} extends BaseScreen {`);
+    // Locators (centralized). H3: `readonly` + the type annotation are TypeScript-only.
     for (const el of screen.elements) {
-        const durabilityNote = el.durability === 'durable' ? '' : ` // ${el.durability} locator${el.remediation ? ` — ${el.remediation}` : ''}`;
-        lines.push(`  readonly ${el.name}${t(': PlatformLocator')} = ${platformLocatorLiteral(el)};${durabilityNote}`);
+        const field = names.fields.get(el.name);
+        const durabilityNote = el.durability === 'durable' ? '' : ` // ${el.durability} locator${el.remediation ? `: ${commentSafe(el.remediation)}` : ''}`;
+        lines.push(`  ${ts ? 'readonly ' : ''}${field}${ts ? ': PlatformLocator' : ''} = ${platformLocatorLiteral(el)};${durabilityNote}`);
     }
     lines.push('');
     // Action methods for each (element, action) used in steps on this screen.
@@ -331,47 +485,47 @@ function screenClass(screen, steps, ts, t) {
     for (const s of steps) {
         if (s.screen !== screen.className || !s.element)
             continue;
-        const el = screen.elements.find((e) => e.name === s.element);
-        if (!el)
+        const key = methodKey(s.action, s.element);
+        if (seen.has(key))
             continue;
-        const name = methodName(s.action, s.element);
-        if (seen.has(name))
-            continue;
-        seen.add(name);
+        seen.add(key);
+        const name = names.methods.get(key);
+        const field = `this.${names.fields.get(s.element)}`;
         if (s.action === 'inputText') {
             lines.push(`  async ${name}(${ts ? 'value: string' : 'value'}) {`);
-            lines.push(`    await this.type(this.${s.element}, value);`);
-            lines.push('  }');
+            lines.push(`    await this.type(${field}, value);`);
         }
         else if (s.action === 'tap') {
             lines.push(`  async ${name}() {`);
-            lines.push(`    await this.tap(this.${s.element});`);
-            lines.push('  }');
+            lines.push(`    await this.tap(${field});`);
         }
         else if (s.action === 'scrollTo') {
-            lines.push(`  async ${name}() {`);
-            lines.push(`    await this.scrollTo(this.${s.element});`);
-            lines.push('  }');
+            lines.push(`  async ${name}(${ts ? "direction: string = 'down'" : "direction = 'down'"}) {`);
+            lines.push(`    await this.scrollTo(${field}, direction);`);
         }
-        else if (s.action === 'assertVisible') {
+        else {
             lines.push(`  async ${name}() {`);
-            lines.push(`    await this.assertVisible(this.${s.element});`);
-            lines.push('  }');
+            lines.push(`    await this.assertVisible(${field});`);
         }
+        lines.push('  }');
     }
     lines.push('}');
     lines.push('');
     return lines.join('\n');
 }
+function envRef(v) {
+    return jsProp('process.env', v);
+}
 function testData(model, ts) {
     const lines = [];
-    lines.push('// Generated by Swipium. Test data comes from the ENVIRONMENT — secrets are never inlined.');
+    const key = (v) => (isJsIdentifier(varToKey(v)) ? varToKey(v) : JSON.stringify(varToKey(v)));
+    lines.push('// Generated by Swipium. Test data comes from the ENVIRONMENT. Secrets are never inlined.');
     lines.push('export const testData = {');
     for (const v of model.variables) {
-        lines.push(`  ${varToKey(v)}: process.env.${v} || '',`);
+        lines.push(`  ${key(v)}: ${envRef(v)} || '',`);
     }
     for (const v of model.secrets) {
-        lines.push(`  ${varToKey(v)}: process.env.${v} || '', // secret — provide via environment only`);
+        lines.push(`  ${key(v)}: ${envRef(v)} || '', // secret, provide via environment only`);
     }
     lines.push('};');
     lines.push('');
@@ -380,61 +534,74 @@ function testData(model, ts) {
     lines.push('');
     return lines.join('\n');
 }
-function smokeTest(model, ts) {
+function smokeTest(model, names) {
     const classes = [...new Set(model.steps.map((s) => s.screen))];
     const lines = [];
     lines.push('// Generated by Swipium. Smoke test driving the recorded flow through the screen objects.');
     for (const c of classes) {
-        lines.push(`import { ${c} } from '../src/screens/${c}.js';`);
+        const cls = names.get(c).cls;
+        lines.push(`import { ${cls} } from '../src/screens/${cls}.js';`);
     }
     lines.push(`import { testData } from '../src/data/testData.js';`);
     lines.push('');
-    lines.push(`describe('${model.testName} smoke', () => {`);
-    // instantiate one screen object per class.
-    const inst = new Map();
-    for (const c of classes) {
-        const v = c[0].toLowerCase() + c.slice(1);
-        inst.set(c, v);
-    }
-    lines.push(`  it('completes the recorded flow', async () => {`);
-    for (const [c, v] of inst)
-        lines.push(`    const ${v} = new ${c}();`);
+    // H3: titles come from recorded data, so always a JSON-escaped literal, never raw interpolation.
+    lines.push(`describe(${JSON.stringify(`${model.testName} smoke`)}, () => {`);
+    lines.push(`  it(${JSON.stringify('completes the recorded flow')}, async () => {`);
+    for (const c of classes)
+        lines.push(`    const ${names.get(c).instance} = new ${names.get(c).cls}();`);
     for (const s of model.steps) {
-        const v = inst.get(s.screen);
-        lines.push('    ' + stepCall(v, s));
+        lines.push('    ' + stepCall(names.get(s.screen), s));
     }
     lines.push('  });');
     lines.push('});');
     lines.push('');
     return lines.join('\n');
 }
-function stepCall(screenVar, s) {
+function dataArg(s) {
+    return s.varName ? jsProp('testData', varToKey(s.varName)) : JSON.stringify(s.text ?? '');
+}
+function num(n) {
+    return Number.isFinite(n) ? Math.round(n) : 0;
+}
+function stepCall(n, s) {
+    const v = n.instance;
     if (s.element) {
-        const name = methodName(s.action, s.element);
-        if (s.action === 'inputText') {
-            const arg = s.varName ? `testData.${varToKey(s.varName)}` : JSON.stringify(s.text ?? '');
-            return `await ${screenVar}.${name}(${arg});`;
-        }
-        return `await ${screenVar}.${name}();`;
+        const name = n.methods.get(methodKey(s.action, s.element));
+        if (s.action === 'inputText')
+            return `await ${v}.${name}(${dataArg(s)});`;
+        if (s.action === 'scrollTo')
+            return `await ${v}.${name}(${JSON.stringify(checkDirection(s.direction ?? 'down', 'scrollTo step'))});`;
+        return `await ${v}.${name}();`;
     }
     // No element: generic BaseScreen helpers.
     switch (s.action) {
         case 'tapAt':
-            return `await ${screenVar}.tapAt(${s.coords?.[0] ?? 0}, ${s.coords?.[1] ?? 0}); // coordinate fallback — non-release-grade`;
-        case 'inputText': {
-            const arg = s.varName ? `testData.${varToKey(s.varName)}` : JSON.stringify(s.text ?? '');
-            return `await ${screenVar}.type({ android: '' }, ${arg}); // focused-field input`;
-        }
+            if (!s.coords)
+                throw new UnemittableStepError('cannot emit a coordinate tap without coordinates');
+            return `await ${v}.tapAt(${num(s.coords[0])}, ${num(s.coords[1])}); // coordinate fallback, non-release-grade`;
+        case 'inputText':
+            return `await ${v}.typeFocused(${dataArg(s)}); // focused-field input`;
         case 'press':
-            return `await ${screenVar}.pressKey(${JSON.stringify(s.key ?? 'back')});`;
+            return `await ${v}.pressKey(${JSON.stringify(checkKey(s.key))});`;
         case 'swipe':
-            return `await ${screenVar}.swipe(${JSON.stringify(s.direction ?? 'up')});`;
+            return `await ${v}.swipe(${JSON.stringify(checkDirection(s.direction ?? 'up', 'swipe step'))});`;
+        case 'scrollTo':
+            if (!s.text)
+                throw new UnemittableStepError('cannot emit a scrollTo step with neither an element nor a target text');
+            return `await ${v}.scrollToText(${JSON.stringify(s.text)}, ${JSON.stringify(checkDirection(s.direction ?? 'down', 'scrollTo step'))});`;
         case 'openUrl':
-            return `await ${screenVar}.openUrl(${JSON.stringify(s.url ?? '')});`;
+            if (!s.url)
+                throw new UnemittableStepError('cannot emit an openUrl step without a URL');
+            return `await ${v}.openUrl(${JSON.stringify(s.url)});`;
         case 'assertVisible':
-            return `await ${screenVar}.assertTextVisible(${JSON.stringify(s.text ?? '')});`;
+            if (!s.text)
+                throw new UnemittableStepError('cannot emit a text assertion without text');
+            return `await ${v}.assertTextVisible(${JSON.stringify(s.text)});`;
+        case 'visualCheck':
+            // Visual judgement prose is not on-screen text. It's a manual checkpoint, never a failing text check.
+            return `// TODO(manual visual check, not automated): ${commentSafe(s.text ?? 'visual checkpoint')}`;
         default:
-            return `// unsupported step: ${s.action}`;
+            throw new UnemittableStepError(`cannot emit step action ${JSON.stringify(s.action)}: no WebdriverIO equivalent is generated for it`);
     }
 }
 //# sourceMappingURL=jsEmitter.js.map