@sun-asterisk/sungen 3.2.2-beta.10 → 3.2.2-beta.13

package/src/cli/commands/init.ts

@@ -4,11 +4,46 @@ export function registerInitCommand(program: Command): void {
   program
     .command('init [projectName]')
     .description('Initialize Sungen project (optionally create and initialize in a new project folder)')
-    .requiredOption('--base-url <url>', 'Base URL for Playwright tests (e.g. https://your-app.com)')
-    .action(async (projectName: string | undefined, options: { baseUrl: string }) => {
+    .option('--base-url <url>', 'Base URL for Playwright (web) tests (e.g. https://your-app.com). Required for web projects (omit only with --mobile)')
+    .option('--mobile', 'Mobile project (Appium/WebdriverIO): scaffold ONLY the mobile harness — no Playwright config, no Chromium download, no --base-url needed')
+    .option('--app-package <pkg>', 'Android appPackage for mobile (e.g. com.example.app). Used with --mobile')
+    .option('--app-activity <activity>', 'Android appActivity for mobile (e.g. com.example.app.MainActivity). OPTIONAL — omit to let Appium auto-resolve the launcher activity from --app-package; pass it only to pin a non-standard launcher. Used with --mobile')
+    .option('--app-apk <path>', 'Path to an .apk to install & run for mobile (alternative to package/activity). Used with --mobile')
+    .option('--android-udid <udid>', 'Default Android device/emulator UDID for mobile (default: emulator-5554)')
+    .option('--ios-bundle-id <id>', 'iOS bundle id for mobile (e.g. com.example.app.dev) — default app when MOBILE_PLATFORM=ios|both. Used with --mobile')
+    .option('--ios-device <name>', "iOS Simulator device name for mobile (default: 'iPhone 16'). Used with --mobile")
+    .option('--ios-version <ver>', "iOS Simulator platform version for mobile (default: '18.0'). Used with --mobile")
+    .action(async (projectName: string | undefined, options: {
+      baseUrl?: string;
+      mobile?: boolean;
+      appPackage?: string;
+      appActivity?: string;
+      appApk?: string;
+      androidUdid?: string;
+      iosBundleId?: string;
+      iosDevice?: string;
+      iosVersion?: string;
+    }) => {
       try {
+        // `--mobile` = a mobile-only project: no web scaffolding, no base URL needed.
+        // Plain `init` = a web project and requires `--base-url`.
+        const mobile = !!options.mobile;
+        if (!mobile && !options.baseUrl) {
+          console.error('❌ --base-url is required for a web project. For a mobile project pass --mobile (no base URL needed).');
+          process.exit(1);
+        }
         const { ProjectInitializer } = require('../../orchestrator/project-initializer');
-        const initializer = new ProjectInitializer(options.baseUrl);
+        const initializer = new ProjectInitializer(options.baseUrl || '', {
+          enabled: mobile,
+          mobileOnly: mobile,
+          appPackage: options.appPackage,
+          appActivity: options.appActivity,
+          appApk: options.appApk,
+          androidUdid: options.androidUdid,
+          iosBundleId: options.iosBundleId,
+          iosDevice: options.iosDevice,
+          iosVersion: options.iosVersion,
+        });
         await initializer.initialize(projectName);
       } catch (error) {
         console.error('❌ Init failed:', error);

package/src/dashboard/snapshot-builder.ts

@@ -22,6 +22,7 @@ import { loadSelectorKeyMap } from '../exporters/selector-key-resolver';
 import { loadPlaywrightReport } from '../exporters/playwright-report-parser';
 import { mergeFeatureAndSpec } from '../exporters/scenario-merger';
 import { buildScreenSnapshot } from '../exporters/json-exporter';
+import { resolvePlatformAppId } from '../exporters/mobile-app-id';
 import { getPackageVersion } from '../exporters/package-info';
 import { EnvironmentInfo } from '../exporters/types';
 import {
@@ -167,6 +168,12 @@ function buildOneFeature(
   // Discover locale variants by scanning <feature>-test-result*.json files.
   // Always includes base ('') as the first entry, even if its results file
   // is missing — UI still needs to render the feature.
+  // NOTE (mobile): for a `platform: mobile` project the "locale" variants are
+  // actually the per-OS runs (android / ios) — the dashboard reuses the locale
+  // switcher to surface them as tabs. The env column per tab is OS-precise (see
+  // resolvePlatformAppId below), but the top-level featurePath (base variant)
+  // defaults to the Android id. Delivery has a dedicated per-OS path; aligning the
+  // dashboard onto a distinct "platform" axis is a possible follow-up.
   const variants = discoverLocaleVariants(genBase, featureBaseName);
 
   // Build per-locale ScreenSnapshot, then collect into FeatureSnapshot.locales[].
@@ -185,7 +192,9 @@ function buildOneFeature(
       screen: featureBaseName,
       isFlow: target.isFlow,
       featureName: feature.featureName,
-      featurePath,
+      // OS-precise env column: a mobile dual-id Path resolves to just the android
+      // package / ios bundle id for the android|ios result variant.
+      featurePath: resolvePlatformAppId(featurePath, variant.locale),
       specLink,
       merged,
       testData,

package/src/exporters/csv-exporter.ts

@@ -202,7 +202,9 @@ export function buildSummary(screen: string, rows: TestCaseRow[], outputFile: st
 function formatEnv(baseURL: string, featurePath: string | undefined, projectName: string): string {
   const base = (baseURL || '').replace(/\/+$/, '');
   const p = (featurePath || '').replace(/^\/+/, '');
-  const url = p ? `${base}/${p}` : base;
+  // Join with '/' only when there is a baseURL (web). For mobile baseURL is empty
+  // and `p` is an app id (e.g. com.kngroup.media.converter) — emit it bare, no '/'.
+  const url = base && p ? `${base}/${p}` : (p || base);
   return `${url} (${projectName})`;
 }
 

package/src/exporters/json-exporter.ts

@@ -165,7 +165,9 @@ export function buildScreenSnapshot(input: BuildScreenSnapshotInput): ScreenSnap
 function formatTestEnvironment(baseURL: string, featurePath: string | undefined, projectName: string): string {
   const base = (baseURL || '').replace(/\/+$/, '');
   const p = (featurePath || '').replace(/^\/+/, '');
-  const url = p ? `${base}/${p}` : base;
+  // Join with '/' only when there is a baseURL (web). For mobile baseURL is empty
+  // and `p` is an app id (e.g. com.kngroup.media.converter) — emit it bare, no '/'.
+  const url = base && p ? `${base}/${p}` : (p || base);
   return `${url} (${projectName})`;
 }
 

package/src/exporters/mobile-app-id.ts

@@ -0,0 +1,34 @@
+/**
+ * Resolve the OS-specific app id from a feature `Path:` for the delivery /
+ * dashboard "Test Environment" column.
+ *
+ * Mobile features carry a DUAL-ID Path: `<androidPkg>[/<activity>] | <iosBundleId>`
+ * (e.g. `com.kngroup.media.converter | com.kngroup.media.converter.dev`). The
+ * deliverable's environment column must show ONLY the id for the OS the results
+ * came from — Android → the package (launch activity stripped), iOS → the bundle
+ * id — never the combined dual-id.
+ *
+ * Web features carry a URL Path (no `|`) and are returned unchanged.
+ *
+ * @param featurePath the feature `Path:` value (dual-id for mobile, URL for web)
+ * @param platform    the OS/result axis the row belongs to. The OS is the FIRST
+ *                     dot-segment, so env-suffixed result variants resolve too —
+ *                     `'ios'`, `'ios.staging'`, `'ios.ja'` all select the bundle id;
+ *                     anything else (`'android'`, `'android.staging'`, a bare locale,
+ *                     base) falls back to the Android package.
+ * @returns the resolved single id, or `featurePath` unchanged when it is not a dual-id.
+ */
+export function resolvePlatformAppId(
+  featurePath: string | undefined,
+  platform: string | undefined,
+): string | undefined {
+  if (!featurePath || !featurePath.includes('|')) return featurePath;
+  const [androidPart = '', iosPart = ''] = featurePath.split('|').map((s) => s.trim());
+  const androidId = androidPart.split('/')[0].trim(); // package only (drop /MainActivity)
+  const iosId = iosPart.trim();
+  // OS = first dot-segment so `ios.staging` / `ios.ja` (env-suffixed result files
+  // <name>-test-result.<os>[.<env>].json) still resolve to the iOS bundle id.
+  const os = (platform || '').toLowerCase().split('.')[0];
+  if (os === 'ios') return iosId || androidId;
+  return androidId || iosId;
+}

package/src/exporters/spec-parser.ts

@@ -25,7 +25,9 @@ function extractTestBlock(content: string, startIdx: number): {
   // The options object uses `\{.*?\}` (non-greedy, not `[^}]*`) so a tag value containing a
   // `}` — e.g. `@query:q(p={{var}})` — doesn't truncate the match (issue #271). The header is
   // single-line, so `.*?` anchored on `}, async` is safe.
-  const testRegex = /test\s*\(\s*(['"`])((?:(?!\1).)+)\1\s*,\s*(?:\{.*?\}\s*,\s*)?async\s*\([^)]*\)\s*=>\s*\{/g;
+  // Accept both Playwright `test(...)` and mobile/Appium mocha `it(...)` (issue #391). The leading
+  // `\b` prevents `it(` from matching the tail of a larger word like `submit(` / `edit(`.
+  const testRegex = /\b(?:test|it)\s*\(\s*(['"`])((?:(?!\1).)+)\1\s*,\s*(?:\{.*?\}\s*,\s*)?async\s*\([^)]*\)\s*=>\s*\{/g;
   testRegex.lastIndex = startIdx;
   const match = testRegex.exec(content);
   if (!match) return null;
@@ -57,7 +59,9 @@ function extractTestBlock(content: string, startIdx: number): {
  */
 function extractDescribeBlocks(content: string): Array<{ name: string; bodyStart: number; bodyEnd: number }> {
   const result: Array<{ name: string; bodyStart: number; bodyEnd: number }> = [];
-  const regex = /test\.describe(?:\.serial)?\s*\(\s*['"]([^'"]+)['"]\s*,\s*\(\s*\)\s*=>\s*\{/g;
+  // Accept Playwright `test.describe(...)` / `test.describe.serial(...)` AND mobile/Appium mocha
+  // `describe(...)` (issue #391). The optional `test.` prefix keeps web specs matching unchanged.
+  const regex = /(?:test\.)?describe(?:\.serial)?\s*\(\s*['"]([^'"]+)['"]\s*,\s*\(\s*\)\s*=>\s*\{/g;
   let match: RegExpExecArray | null;
   while ((match = regex.exec(content)) !== null) {
     const name = match[1];

package/src/generators/test-generator/adapters/adapter-interface.ts

@@ -23,11 +23,14 @@ export interface TestFileData {
   featureFileName?: string; // Feature file name for TestDataLoader.load()
   isParallel?: boolean; // @parallel tag: fresh page per test (opt-out from serial default)
   flowMode?: boolean;   // flow: cross-screen → longer per-test timeout (bug #243)
+  platform?: string;    // mobile @platform:* value (mobile|android|ios) → `// sungen:platform=` marker for wdio per-OS routing
   cleanup?: { overlay?: boolean; forms?: boolean; scroll?: boolean; storage?: boolean };
   backgroundSteps?: Array<{ comment?: string; code: string }>; // Raw background steps for serial beforeAll
   scenarios: string[];
   authGroups?: AuthGroup[]; // Grouped by auth role for nested describes
   singleAuthRole?: string;  // Auth role when all scenarios share the same role
+  appPackage?: string;      // Mobile (appium): Android package from the feature `Path:` → drives the per-scenario relaunch reset (beforeEach terminate+activate)
+  iosBundleId?: string;     // Mobile (appium): iOS bundle id from a dual-id `Path: <pkg>/<activity> | <bundleId>`
 }
 
 export interface ScenarioData {

package/src/generators/test-generator/adapters/appium/templates/steps/actions/scroll-action.hbs

@@ -1,10 +1,13 @@
 if (driver.isIOS) {
-  // iOS (XCUITest) has no UiScrollable. Swipe the screen up in bounded steps until the target is on
-  // screen (a below-fold element isn't in the XCUITest tree until scrolled, so getElementRect/tap on
-  // it would otherwise fail). Bounded so a missing target can't loop forever.
+  // iOS (XCUITest) has no UiScrollable. Swipe up in bounded steps until the target is on screen (a
+  // below-fold element isn't in the XCUITest tree until scrolled). A settle `pause` between swipes
+  // paces the loop so it doesn't flood `execute/sync` (rapid back-to-back swipes are a common source
+  // of flakiness; issue #394). Bounded (cap 10) so a missing target can't loop forever. NOTE: this
+  // does NOT fix an app that crashes mid-scroll on its own — that's an app-stability issue, not codegen.
   const __t = $({{> appium-selector-expr}});
-  for (let __i = 0; __i < 12 && !(await __t.isDisplayed().catch(() => false)); __i++) {
+  for (let __i = 0; __i < 10 && !(await __t.isDisplayed().catch(() => false)); __i++) {
     await driver.execute('mobile: swipe', { direction: 'up' });
+    await driver.pause(400); // settle: let the app render between swipes (don't flood execute/sync)
   }
 } else {
 {{#if (eq strategy 'accessibility-id')}}

package/src/generators/test-generator/adapters/appium/templates/steps/actions/toggle-action.hbs

@@ -1,3 +1,20 @@
-{{!-- A switch/toggle flips state on tap (mirrors the web toggle pattern: unconditional click).
-      Use `check`/`uncheck` instead when you need to drive it to a specific on/off state idempotently. --}}
-await {{> locator}}.click();
+{{!-- A switch/toggle flips state on tap. On Flutter (and many native layouts) the row's a11y node
+      spans the FULL width and merges the label with the switch, so a centre .click() lands on the
+      LABEL and does NOT flip the control — only the trailing visual switch toggles. So tap the
+      RIGHT portion (vertical centre) via getElementRect (W3C-standard → Android + iOS). Falls back to
+      a plain centre click when the rect is unavailable. Use `check`/`uncheck` to drive a specific
+      on/off state idempotently instead. --}}
+await (async () => {
+  const e = await {{> locator}};
+  const r = await driver.getElementRect(e.elementId);
+  if (r && r.width) {
+    // Trailing switch: ~right edge, vertical centre. The inset clears the label/track padding while
+    // staying on the switch even on a full-width composite row.
+    const x = Math.round(r.x + r.width - Math.max(48, r.width * 0.08));
+    const y = Math.round(r.y + r.height / 2);
+    if (driver.isIOS) { await driver.execute('mobile: tap', { x, y }); }
+    else { await driver.execute('mobile: clickGesture', { x, y }); }
+  } else {
+    await e.click();
+  }
+})();

package/src/generators/test-generator/adapters/appium/templates/steps/assertions/checked-assertion.hbs

@@ -1 +1,4 @@
-await expect({{> locator}}).toBeSelected();
+// Mobile toggle state lives in the `checked` attribute (Android) or `value` "1"/"0" (iOS) — NOT
+// `selected` (what toBeSelected() reads; always false for a Flutter Switch). The composite row node
+// carries it, so the row selector resolves the state directly.
+await expect({{> locator}}).toHaveAttribute(driver.isIOS ? 'value' : 'checked', driver.isIOS ? '1' : 'true');

package/src/generators/test-generator/adapters/appium/templates/steps/assertions/not-checked-assertion.hbs

@@ -1 +1,4 @@
-await expect({{> locator}}).not.toBeSelected();
+// Mobile toggle state lives in the `checked` attribute (Android) or `value` "1"/"0" (iOS) — NOT
+// `selected` (what toBeSelected() reads; always false for a Flutter Switch). The composite row node
+// carries it, so the row selector resolves the state directly.
+await expect({{> locator}}).not.toHaveAttribute(driver.isIOS ? 'value' : 'checked', driver.isIOS ? '1' : 'true');

package/src/generators/test-generator/adapters/appium/templates/test-file.hbs

@@ -152,6 +152,9 @@ describe('{{featureName}}', () => {
     const __APP_PKG__ = __resolveAppId();
     try { await driver.terminateApp(__APP_PKG__); } catch { /* app may not be running yet */ }
     await driver.activateApp(__APP_PKG__);
+    // Restore portrait so a prior scenario's `rotate to landscape` can't leak into this one — the
+    // app relaunch above resets in-app state, but device orientation is OS-level and persists.
+    try { await driver.setOrientation('PORTRAIT'); } catch { /* orientation control not supported */ }
     // Settle after a cold (re)launch: a Flutter app first renders a BLANK accessibility skeleton
     // (nested FrameLayout/View, no content-desc) for several seconds before the real tree appears.
     // That skeleton is static, so a "two equal reads" check alone false-positives on it and we'd

package/src/generators/test-generator/code-generator.ts

@@ -173,8 +173,10 @@ function getEffectiveAuthRole(
  * @manual at scenario level → skip that scenario
  */
 function isManual(tags: string[]): boolean {
-  // @deferred:flow is owned by a flow → not automated on this screen, so it skips like @manual (H6).
-  return tags.some(tag => tag === '@manual' || tag === '@deferred:flow');
+  // Recognize bare `@manual` AND the reason-coded `@manual:Mx` convention (what create-test emits) —
+  // must match harness/parse.ts + capability-plan.ts, else an `@manual:Mx` scenario is wrongly
+  // GENERATED (and run) instead of skipped. @deferred:flow is owned by a flow → also skips here (H6).
+  return tags.some(tag => /^@manual\b/i.test(tag) || tag === '@deferred:flow');
 }
 
 /**
@@ -487,7 +489,15 @@ export class CodeGenerator {
     let background: string | undefined;
     let backgroundSteps: Array<{ comment?: string; code: string }> | undefined;
     if (feature.background) {
-      if (isParallel) {
+      // Mobile (appium) ALWAYS inlines Background via `backgroundSteps`: the test-file template emits a
+      // relaunch-per-scenario beforeEach and renders Background INSIDE it (it has no separate `background`
+      // beforeEach slot), and that per-scenario relaunch already gives @parallel its reset semantics.
+      // Routing a @parallel *mobile* feature to generateBeforeEach() computes the nav steps into
+      // `background`, which the mobile template then ignores → the Background nav (e.g. `tap [Settings]
+      // tab`) is silently dropped and every scenario runs on the launcher. So branch on isParallel only
+      // for web; for appium always use generateBackgroundSteps().
+      const isMobile = this.adapter.frameworkName === 'appium';
+      if (isParallel && !isMobile) {
         background = await this.generateBeforeEach(feature.background);
       } else {
         backgroundSteps = await this.generateBackgroundSteps(feature.background);
@@ -597,6 +607,29 @@ export class CodeGenerator {
     const cleanup = extractCleanupFlags(feature.tags || []);
     const screenshotOnFailure = hasScreenshotOnFailure(feature.tags || []);
 
+    // Mobile: the @platform:* value (mobile|android|ios). Emitted as a `// sungen:platform=` marker
+    // so wdio.conf routes the spec per OS — android/ios = that OS only, mobile (default) = both.
+    // Only the appium adapter consumes it; web features have no @platform tag → undefined → no marker.
+    const platform = this.adapter.frameworkName === 'appium'
+      ? (feature.tags || []).find(t => t.startsWith('@platform:'))?.split(':')[1]
+      : undefined;
+
+    // Mobile: parse the feature `Path:` (the app entry) into the app id(s) the per-scenario relaunch
+    // reset needs. Dual-id form: `<androidPkg>[/<activity>] | <iosBundleId>` — appPackage is the Android
+    // package (activity stripped, it isn't needed for terminateApp/activateApp); iosBundleId is the part
+    // after `|` when present. Without these the test-file template's `{{#if appPackage}}` stays false and
+    // the beforeEach (terminate+activate) reset is never emitted → nav scenarios cascade-fail.
+    let appPackage: string | undefined;
+    let iosBundleId: string | undefined;
+    if (this.adapter.frameworkName === 'appium' && feature.path) {
+      const [androidPart, iosPart] = feature.path.split('|').map(s => s.trim());
+      // Guard against a web-style URL Path (`/login`): only treat as a package when it isn't a route.
+      if (androidPart && !androidPart.startsWith('/')) {
+        appPackage = androidPart.split('/')[0].trim() || undefined;
+      }
+      if (iosPart) iosBundleId = iosPart;
+    }
+
     // Use adapter to render the complete test file structure
     return this.adapter.renderTestFile({
       imports: '', // Not used in template as it's rendered separately
@@ -613,11 +646,14 @@ export class CodeGenerator {
       featureFileName: featureName,
       isParallel,
       flowMode: isFlowFeature,
+      platform,
       cleanup,
       backgroundSteps,
       scenarios: needsGrouping ? [] : scenarios,
       authGroups: needsGrouping ? authGroups : undefined,
       singleAuthRole,
+      appPackage,
+      iosBundleId,
     });
   }
 

package/src/generators/test-generator/template-engine.ts

@@ -21,9 +21,19 @@ export class TemplateEngine {
       return text.split('\n').map(line => indentation + line).join('\n');
     });
 
+    // Escape a raw string for embedding inside a single-quoted JS string literal. Every caller wraps
+    // the result in '…' (selector values, attribute values, scope), so a value containing a newline,
+    // backslash, or quote must be escaped or the generated spec is a syntax error (e.g. a Flutter
+    // composite content-desc like "Quick Convert\nSelect File\n…" used as an accessibility-id).
+    // Order matters: backslash first, then the rest.
     Handlebars.registerHelper('escapeQuotes', function(text: string) {
       if (text == null) return '';
-      return String(text).replace(/'/g, "\\'");
+      return String(text)
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
     });
 
     Handlebars.registerHelper('escapeRegex', function(text: string) {
@@ -259,11 +269,14 @@ export class TemplateEngine {
     screenName?: string;
     featureFileName?: string;
     isParallel?: boolean;
+    platform?: string;
     cleanup?: { overlay?: boolean; forms?: boolean; scroll?: boolean; storage?: boolean };
     backgroundSteps?: Array<{ comment?: string; code: string }>;
     scenarios: string[];
     authGroups?: Array<{ authRole?: string; scenarios: string[] }>;
     singleAuthRole?: string;
+    appPackage?: string;
+    iosBundleId?: string;
   }): string {
     return this.render('test-file', data);
   }

package/src/generators/test-generator/utils/selector-resolver.ts

@@ -20,6 +20,12 @@ interface SelectorEntry {
   scope?: string;         // Parent landmark aria-label to scope within (e.g., 'desktop navigation')
   match?: 'exact' | 'partial';  // For getByText matching (default: partial)
 
+  // === Mobile per-platform variant (issue #392) ===
+  // `android:`/`ios:` sub-selectors for one logical element whose locator differs per OS (composite
+  // content-desc, partial/dynamic text, native predicate). Each is a full SelectorEntry.
+  android?: SelectorEntry;
+  ios?: SelectorEntry;
+
   // === v2: Complex Elements ===
   variant?: 'native' | 'custom' | 'dragdrop';  // Dropdown/upload subtype
   trigger?: string;       // Visible button that triggers hidden file input
@@ -52,8 +58,17 @@ interface LegacySelectorFile {
 }
 
 export interface ResolvedSelector {
-  strategy: 'testid' | 'id' | 'placeholder' | 'label' | 'text' | 'css' | 'role' | 'locator';
+  // Web (Playwright) strategies + mobile (Appium) strategies. Mobile types pass through from
+  // selectors.yaml so the appium adapter's `appium-selector` switch can emit the right WDIO selector
+  // (`~` / raw xpath / `android=` / `-ios predicate string:` / `id=`). See issue #392.
+  strategy: 'testid' | 'id' | 'placeholder' | 'label' | 'text' | 'css' | 'role' | 'locator'
+    | 'accessibility-id' | 'xpath' | 'android-uiautomator' | 'ios-predicate';
   value: string;
+  // Mobile per-platform variant (`android:`/`ios:` in selectors.yaml). When set, the appium codegen
+  // emits a runtime `driver.isIOS ? '<ios>' : '<android>'` so one @platform:mobile spec resolves the
+  // right native selector per OS. Each side carries its own strategy+value (issue #392).
+  androidSelector?: { strategy: ResolvedSelector['strategy']; value: string; name?: string };
+  iosSelector?: { strategy: ResolvedSelector['strategy']; value: string; name?: string };
   role?: string;        // For role-based selectors (e.g., 'button', 'link')
   name?: string;        // For accessible name in role selectors
   locator?: string;     // CSS locator for fallback
@@ -472,6 +487,25 @@ export class SelectorResolver {
       return { ...resolved, ...v2Fields };
     };
 
+    // Mobile per-platform variant (issue #392): `{ android: {...}, ios: {...} }`. Resolve each side
+    // and emit androidSelector/iosSelector so the appium codegen renders `driver.isIOS ? ios : android`.
+    // The base strategy/value falls back to whichever side is present (a missing side falls back to it).
+    // `nth`/`scope` are shared (top-level) — they cannot diverge per-OS (the codegen ternary swaps only
+    // strategy+value); a case needing per-OS nth/scope is a sub-feature, not a variant.
+    if (entry.android || entry.ios) {
+      const av = entry.android ? this.resolveFromEntry(entry.android, originalLabel) : undefined;
+      const iv = entry.ios ? this.resolveFromEntry(entry.ios, originalLabel) : undefined;
+      const base = (av || iv) as ResolvedSelector;
+      return withExtras({
+        strategy: base.strategy,
+        value: base.value,
+        name: base.name,
+        nth,
+        ...(av ? { androidSelector: { strategy: av.strategy, value: av.value, name: av.name } } : {}),
+        ...(iv ? { iosSelector: { strategy: iv.strategy, value: iv.value, name: iv.name } } : {}),
+      });
+    }
+
     // If type is 'locator', use locator field (or value as fallback) as the CSS locator directly
     if (type === 'locator') {
       const locatorValue = locator && locator.trim() ? locator : value;
@@ -536,6 +570,22 @@ export class SelectorResolver {
           exact,
         });
 
+      // Mobile (Appium) native strategies — pass through unchanged; the appium adapter's
+      // `appium-selector` switch renders the right WDIO selector (`~` / raw xpath / `android=` /
+      // `-ios predicate string:` / `id=`). On web these types never appear. See issue #392.
+      case 'accessibility-id':
+      case 'xpath':
+      case 'android-uiautomator':
+      case 'ios-predicate':
+      case 'id':
+        return withExtras({
+          strategy: type,
+          value,
+          name,
+          nth,
+          exact,
+        });
+
       default:
         // Fallback to placeholder
         return withExtras({

package/src/harness/audit.ts

@@ -146,7 +146,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   const capGate = scoringCap?.gateProvider as
     ((i: { scenarios: ScenarioInfo[]; viewpoints: ViewpointEntry[]; catalog: Catalog; focus: typeof intent.focus; cwd: string; screenName: string; threshold: number; businessCriticalMethods?: string[] }) => { gate: GateResult; depth: DepthResult }) | undefined;
   const provided = capGate?.({ scenarios, viewpoints, catalog, focus: intent.focus, cwd: projectRootFromScreenDir(screenDir), screenName: catalogScreenName, threshold: depthThresholdFor(intent.focus), businessCriticalMethods: intent.businessCriticalMethods });
-  const gate = provided?.gate ?? viewpointGate(scenarios, viewpoints, catalog);
+  const gate = provided?.gate ?? viewpointGate(scenarios, viewpoints, catalog, platform === 'mobile');
   const depth = provided?.depth ?? assertionDepth(scenarios, dataThemesFor(catalog, gate.pageType), intent.focus);
 
   // TQ-4 — deferral-aware coverage credit: an inherently cross-screen theme (cart / detail /

package/src/harness/catalog/universal-viewpoints.yaml

@@ -91,6 +91,21 @@ page_types:
           keywords: ["success message", "saved", "created", "confirmation"]
           template: "User see [Success] message with {{success_text}}"
 
+  # Mobile launcher / home screen (Appium). Display + navigation only — no web form/validation.
+  # A `mobile-*` candidate (considered ONLY for mobile targets; never for web). Keywords are
+  # launcher-DISTINCTIVE (a tab-bar landing screen) and deliberately exclude generic tokens like
+  # "tab"/"navigation"/"home" that a mobile commerce/list screen also carries — so such a screen
+  # still selects ecommerce-list, not mobile-home. Both themes are presence/navigation (no `depth:`)
+  # — seeing the content and leaving Home (a destination marker OR the Home-only anchor going
+  # `is hidden`) IS the assertion; no data-assertion is forced.
+  mobile-home:
+    detect_keywords: ["bottom navigation", launcher, greeting, "home screen", "launcher screen"]
+    must_cover:
+      - theme: content-visibility
+        keywords: [displayed, render, loads, exposes, shown, visible]
+      - theme: navigation-correctness
+        keywords: [tap, navigate, "leaves home", "is hidden", opens, navigation]
+
   auth:
     detect_keywords: [login, logout, password, signin, "sign in", credential]
     must_cover:

package/src/harness/journey.ts

@@ -116,19 +116,31 @@ function computeFresh(projectRoot: string, unit: string): JourneyReport {
     detail: autoPending ? `${audit.automatableManual.automatable} @manual scenario(s) a driver could automate` : 'no capability-pending automatable cases',
   });
 
-  // Human sign-off: always pending until S5 explicit signoff; carries the review-queue count.
-  const manualCount = (audit.manualOracle && audit.manualOracle.total) || 0;
+  // Needs-you: the review queue. Prefer PRECISE per-scenario anchors from audit's structured
+  // depth data — each shallow business-critical scenario carries its own VP id — over regex-parsing
+  // the aggregate "DEPTH:" finding string (which names no scenario, so points nowhere). Then
+  // supplement with the remaining human-judgment findings.
+  const shallowBC: { name: string; category?: string }[] = (audit.depth && audit.depth.shallowBusinessCritical) || [];
+  for (const s of shallowBC) {
+    needsYou.push({
+      text: `DEEPEN — "${s.name}": assert data, not just visibility (\`… with {{value}}\` / \`see all … contain {{v}}\`), or defer cross-screen with @manual + reason.`,
+      anchor: extractAnchor(s.name),
+    });
+  }
+  const haveStructuredDepth = shallowBC.length > 0;
+  for (const f of (audit.findings || [])) {
+    if (!isHumanFinding(f)) continue;
+    if (haveStructuredDepth && /^\s*DEPTH\b/i.test(f)) continue; // superseded by the per-scenario items above
+    needsYou.push({ text: f, anchor: extractAnchor(f) });
+  }
+
+  // Human sign-off: always pending until S5 explicit signoff; carries the now-final review-queue count.
+  const manualCount = (audit.manualOracle && (audit.manualOracle.manualTotal ?? audit.manualOracle.total)) || 0;
   obligations.push({
     id: 'OB-signoff', title: 'Human sign-off', status: 'pending',
-    detail: `${needsYou.length} item(s) queued for your review (single sign-off at the end)`,
+    detail: `${needsYou.length} item(s) queued for your review · ${manualCount} @manual scenario(s)`,
   });
 
-  // Needs-you: human-judgment findings (the review-queue seed), with their anchors (titles) intact.
-  for (const f of (audit.findings || [])) if (isHumanFinding(f)) needsYou.push({ text: f, anchor: extractAnchor(f) });
-  // Re-stamp the signoff detail now that needsYou is filled.
-  const signoff = obligations.find((o) => o.id === 'OB-signoff');
-  if (signoff) signoff.detail = `${needsYou.length} item(s) queued for your review · ${manualCount} @manual scenario(s)`;
-
   // Next suggested = first non-satisfied obligation; if all satisfied but run-test not done → run.
   const firstGap = obligations.find((o) => o.status !== 'satisfied' && o.id !== 'OB-signoff');
   let nextSuggested: string;

package/src/harness/sensors.ts

@@ -59,9 +59,17 @@ export function loadCatalog(): Catalog {
   return parseYaml(fs.readFileSync(p, 'utf-8')) as Catalog;
 }
 
+// Word-aware keyword match: `\b<kw>(s|es|ed|ing)?\b`, so a keyword matches whole words (plus
+// simple plural/verb suffixes) but NOT as a substring of a larger word — e.g. `form` must not
+// match inside `Format` or `@platform`, while `product` still matches `products`. Multi-word
+// keywords ("add to cart", "is hidden") match the phrase with a boundary at each end.
+const wordRe = (kw: string) => {
+  const esc = kw.toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`\\b${esc}(?:s|es|ed|ing)?\\b`);
+};
 const has = (haystacks: string[], kw: string) => {
-  const k = kw.toLowerCase();
-  return haystacks.some((h) => h.includes(k));
+  const re = wordRe(kw);
+  return haystacks.some((h) => re.test(h));
 };
 
 // ---------- Sensor 1: Viewpoint Gate (catalog-driven) ----------
@@ -75,16 +83,21 @@ export interface GateResult {
   universalGaps: string[];
 }
 
-export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEntry[], catalog: Catalog): GateResult {
+export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEntry[], catalog: Catalog, isMobile = false): GateResult {
   const haystacks = [
     ...scenarios.map((s) => s.haystack),
     ...viewpoints.map((v) => `${v.id} ${v.reason}`.toLowerCase()),
   ];
 
-  // Detect page-type by detect_keywords hit count
+  // Detect page-type by detect_keywords hit count. `mobile-*` page-types are candidates ONLY for
+  // mobile targets; web targets never consider them. Mobile targets still consider the web types
+  // too, so a mobile commerce/form screen is selected as ecommerce-list/form by keyword fit —
+  // `mobile-home` does not crowd out a better-fitting type. With no type matching → pageType stays
+  // null → no themes required → the gate passes leniently rather than false-FAILing.
   let pageType: string | null = null;
   let best = 0;
   for (const [pt, def] of Object.entries(catalog.page_types)) {
+    if (pt.startsWith('mobile-') && !isMobile) continue;
     const hits = def.detect_keywords.filter((k) => has(haystacks, k)).length;
     if (hits > best) { best = hits; pageType = pt; }
   }
@@ -97,10 +110,14 @@ export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEn
       // Scenarios that cover this theme by keyword (include @manual — a manual
       // scenario with a real assertion still covers the viewpoint for design).
       const coverers = scenarios.filter((s) => t.keywords.some((k) => s.haystack.includes(k.toLowerCase())));
-      const deep = coverers.some((s) => s.hasDataAssertion);
-      if (deep) covered++;
-      else if (coverers.length > 0) gaps.push({ theme: t.theme, keywords: t.keywords, status: 'shallow' });
-      else gaps.push({ theme: t.theme, keywords: t.keywords, status: 'missing' });
+      if (coverers.length === 0) { gaps.push({ theme: t.theme, keywords: t.keywords, status: 'missing' }); continue; }
+      // A theme WITHOUT `depth:` is visibility/navigation — landing/seeing/leaving IS the
+      // assertion, so mere presence covers it. Only DATA-correctness themes (depth.requires:
+      // data-assertion) need a data assertion to count as deeply covered.
+      const needsDepth = t.depth?.requires === 'data-assertion';
+      if (!needsDepth) { covered++; continue; }
+      if (coverers.some((s) => s.hasDataAssertion)) covered++;
+      else gaps.push({ theme: t.theme, keywords: t.keywords, status: 'shallow' });
     }
   }