@sun-asterisk/sungen 3.2.0-beta.141 → 3.2.0-beta.143

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

@@ -0,0 +1,226 @@
+{{#if platform}}
+// sungen:platform={{platform}}
+{{/if}}
+{{#if runtimeData}}
+
+const testData = TestDataLoader.load('{{screenName}}', '{{featureFileName}}');
+{{/if}}
+{{#if singleAuthRole}}
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+// ── @auth (mobile) ──────────────────────────────────────────────────────────
+// App-agnostic auth: the framework supplies the MECHANISM; each app supplies the DATA via a
+// gitignored contract at specs/.auth-mobile/<role>.json:
+//   { "authedMarker": {type,value},                 // present ⟺ already logged in
+//     "credentials": { ... },                        // referenced as {{key}} in step values
+//     "loginSteps": [ {action:"tap"|"fill"|"wait", selector:{type,value}, value?} ] }
+// ensureAuth is idempotent (skips when already logged in) and fail-loud (throws → the @auth spec is
+// blocked, never silently run logged-out). See MOBILE_INTEGRATION_PLAN.md §Phase 5.1.
+function __authSelector(s: { type: string; value: string }): string {
+  switch (s.type) {
+    case 'accessibility-id': case 'testid': case 'label': case 'placeholder': case 'text': return '~' + s.value;
+    case 'android-uiautomator': return 'android=' + s.value;
+    case 'ios-predicate': return '-ios predicate string:' + s.value;
+    case 'id': return 'id=' + s.value;
+    case 'xpath': case 'locator': default: return s.value;
+  }
+}
+function __authInterpolate(v: string, creds: Record<string, unknown> = {}): string {
+  return String(v).replace(/\{\{\s*(\w+)\s*\}\}/g, (_m, k) => (creds[k] != null ? String(creds[k]) : ''));
+}
+// Robust mobile text entry: Flutter often ignores a single setValue, and W3C key-streams can drop a
+// char — so we type, read back, and retry once. Masked (password) fields can't be verified → trusted.
+async function __robustFill(el: WebdriverIO.Element, value: string): Promise<void> {
+  await el.click();
+  try { await el.clearValue(); } catch { /* not clearable */ }
+  await el.setValue(value);
+  let got = '';
+  try { got = (await el.getText()) || (await el.getAttribute('text')) || ''; } catch { /* ignore */ }
+  const masked = /[•●*]/.test(got);
+  if (!masked && got.replace(/\s/g, '') !== value.replace(/\s/g, '')) {
+    try { await el.clearValue(); } catch { /* ignore */ }
+    await el.addValue(value);
+  }
+}
+async function __ensureAuth(role: string): Promise<void> {
+  const cfgPath = path.join(process.cwd(), 'specs', '.auth-mobile', role + '.json');
+  const rel = path.relative(process.cwd(), cfgPath);
+  if (!fs.existsSync(cfgPath)) {
+    throw new Error(`@auth:${role} requires ${rel} (loginSteps + credentials + a login-state marker). See MOBILE_INTEGRATION_PLAN.md §Phase 5.1.`);
+  }
+  const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
+  const present = async (marker: { type: string; value: string } | undefined, timeout = 6000): Promise<boolean> => {
+    if (!marker) return false;
+    try { await $(__authSelector(marker)).waitForDisplayed({ timeout }); return true; }
+    catch { return false; }
+  };
+  const absent = async (marker: { type: string; value: string } | undefined, timeout = 8000): Promise<boolean> => {
+    if (!marker) return true;
+    try { await $(__authSelector(marker)).waitForDisplayed({ reverse: true, timeout }); return true; }
+    catch { return false; }
+  };
+  const runSteps = async (steps: any[]): Promise<void> => {
+    for (const step of (steps || [])) {
+      // Selector-less actions first (no element to find).
+      if (step.action === 'hideKeyboard') { try { await driver.hideKeyboard(); } catch { /* no keyboard shown */ } continue; }
+      if (step.action === 'back') { try { await driver.back(); } catch { /* nothing to dismiss */ } continue; }
+      const el = await $(__authSelector(step.selector));
+      await el.waitForDisplayed();
+      if (step.action === 'fill') await __robustFill(el, __authInterpolate(step.value, cfg.credentials));
+      else if (step.action === 'tap') await el.click();
+      // 'wait' = just the waitForDisplayed above
+    }
+  };
+
+  // ── Mode A: navigation-based (preferred) ──────────────────────────────────
+  // For apps whose login state is NOT visible on the post-relaunch landing screen (e.g. a Flutter
+  // app that always opens on Home). We navigate to a DECISION screen (loginEntrySteps, e.g. My Page
+  // → Account Settings) and read `loggedOutMarker` there (present ⟺ logged out, e.g. the Login
+  // button). loginSteps then start FROM that decision screen.
+  if (cfg.loginEntrySteps && cfg.loggedOutMarker) {
+    await runSteps(cfg.loginEntrySteps);
+    if (!(await present(cfg.loggedOutMarker, 8000))) return; // logged-out marker absent ⟹ already logged in (noReset)
+    await runSteps(cfg.loginSteps);
+    // Verify: a credentials error means rejection; the login form staying put (logged-out marker
+    // never disappears) means it didn't submit. Success = the form navigated away with no error.
+    if (await present(cfg.errorMarker, 3000)) {
+      throw new Error(`@auth:${role} login rejected (error shown) — check credentials.email/password in ${rel}.`);
+    }
+    if (!(await absent(cfg.loggedOutMarker, 8000))) {
+      throw new Error(`@auth:${role} login did not complete (still on the login screen) — check loginSteps in ${rel}.`);
+    }
+    return;
+  }
+
+  // ── Mode B: legacy authedMarker (present on the landing screen ⟺ logged in) ──
+  const markerPresent = async (): Promise<boolean> => present(cfg.authedMarker, 6000);
+  if (await markerPresent()) return; // idempotent — already authenticated (session kept by noReset)
+  await runSteps(cfg.loginSteps);
+  if (!(await markerPresent())) {
+    throw new Error(`@auth:${role} login failed — verify credentials / loginSteps / authedMarker in ${rel}.`);
+  }
+}
+{{/if}}
+
+{{#if featureDescription}}
+/**
+ * Feature: {{featureName}}
+ * {{featureDescription}}
+ */
+{{/if}}
+describe('{{featureName}}', () => {
+{{#if singleAuthRole}}
+  // @auth:{{singleAuthRole}} — authenticate ONCE before any scenario; the session persists across
+  // the per-scenario relaunch below (noReset:true). Throws (blocks the spec) if login can't be done.
+  before(async () => {
+{{#if appPackage}}
+    // Relaunch to a known launch screen first — the session may attach to the app in any state.
+    // Platform-aware id (NOT the Android literal): on iOS a @platform:mobile feature's app is the
+    // dual-id bundle id — a literal appPackage here would throw and block the whole spec.
+    // (__resolveAppId is a hoisted function declaration in this describe scope.)
+    const __AUTH_APP__ = __resolveAppId();
+    try { await driver.terminateApp(__AUTH_APP__); } catch { /* not running */ }
+    await driver.activateApp(__AUTH_APP__);
+{{/if}}
+    await __ensureAuth('{{singleAuthRole}}');
+  });
+
+{{/if}}
+{{#if appPackage}}
+  // Multi-app: this feature's app (from the `Path:` line). Reset to its launch screen before each
+  // scenario so one `wdio run` can host screens from different apps — each spec launches its own.
+  // The `Path:` holds the ANDROID package (or, for an @platform:ios feature, the iOS bundle id).
+  const __APP_PKG_DEFAULT__ = '{{appPackage}}';
+{{#if iosBundleId}}
+  // Per-feature iOS bundle id from the dual-id `Path: <androidPkg>/<activity> | <iosBundleId>` —
+  // app ids differ per OS (e.g. an iOS `.dev` flavor), and keeping it in the feature file makes the
+  // spec self-describing + lets one iOS run host multiple apps.
+  const __IOS_BUNDLE__ = '{{iosBundleId}}';
+{{/if}}
+  // Platform-aware app id: an @platform:mobile spec runs on BOTH OSes. On iOS prefer the feature's own
+  // bundle id (dual-id Path), then the session cap (IOS_BUNDLE_ID in wdio.conf), then the Path value;
+  // on Android (or any non-iOS session) use the Path package unchanged.
+  function __resolveAppId(): string {
+    if (typeof driver !== 'undefined' && driver.isIOS) {
+      const caps = (driver.requestedCapabilities || {}) as Record<string, string>;
+      return {{#if iosBundleId}}__IOS_BUNDLE__ || {{/if}}caps['appium:bundleId'] || caps['bundleId'] || __APP_PKG_DEFAULT__;
+    }
+    return __APP_PKG_DEFAULT__;
+  }
+  beforeEach(async () => {
+    const __APP_PKG__ = __resolveAppId();
+    try { await driver.terminateApp(__APP_PKG__); } catch { /* app may not be running yet */ }
+    await driver.activateApp(__APP_PKG__);
+    // 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
+    // proceed before any element exists (→ every find fails). So require the tree to (a) contain
+    // rendered content — at least one non-empty content-desc/text — AND (b) be stable across two
+    // reads. A generous timeout covers slow cold renders on a stressed emulator. Best-effort: a
+    // timeout never fails the scenario, it just falls through to the step's own auto-wait.
+    let __prevSrc = '';
+    await driver
+      .waitUntil(
+        async () => {
+          const src = await driver.getPageSource();
+          const hasContent = /content-desc="[^"]+"|\btext="[^"]+"/.test(src);
+          const stable = hasContent && src === __prevSrc;
+          __prevSrc = src;
+          return stable;
+        },
+        { timeout: 30000, interval: 400, timeoutMsg: 'UI did not settle (no rendered content)' },
+      )
+      .catch(() => { /* best-effort — fall through to per-step auto-wait */ });
+{{#if backgroundSteps}}
+    // Background runs here (inside beforeEach) — the app resets to its launch screen every scenario,
+    // so Background setup (nav, dismiss launch promos…) must re-run after each relaunch, not once.
+{{#each backgroundSteps}}
+{{#if comment}}
+    // {{comment}}
+{{/if}}
+{{code}}
+{{/each}}
+{{/if}}
+  });
+
+{{/if}}
+{{#unless appPackage}}
+{{#if backgroundSteps}}
+  before(async () => {
+{{#each backgroundSteps}}
+{{#if comment}}
+    // {{comment}}
+{{/if}}
+{{code}}
+{{/each}}
+  });
+
+{{/if}}
+{{/unless}}
+{{#if beforeAll}}
+{{beforeAll}}
+
+{{/if}}
+{{#if afterEach}}
+{{afterEach}}
+
+{{/if}}
+{{#if afterAll}}
+{{afterAll}}
+
+{{/if}}
+{{#if authGroups}}
+{{#each authGroups}}
+{{#each scenarios}}
+{{this}}
+
+{{/each}}
+{{/each}}
+{{else}}
+{{#each scenarios}}
+{{this}}
+
+{{/each}}
+{{/if}}
+});

package/src/generators/test-generator/adapters/index.ts

@@ -1,12 +1,19 @@
 export { TestGeneratorAdapter, TestFileData, ScenarioData, StepTemplateData, LocatorExpression } from './adapter-interface';
 export { AdapterRegistry, adapterRegistry, DriverNotInstalledError } from './adapter-registry';
 export { PlaywrightAdapter } from './playwright/playwright-adapter';
+export { AppiumAdapter } from './appium/appium-adapter';
 
 // Auto-register built-in adapters
 import { adapterRegistry } from './adapter-registry';
 import { PlaywrightAdapter } from './playwright/playwright-adapter';
+import { AppiumAdapter } from './appium/appium-adapter';
 
 adapterRegistry.register('playwright', () => new PlaywrightAdapter());
 // Phase 2a: platform alias. `web` is the bundled Playwright adapter (back-compat
 // baseline) until it is externalized to @sungen/driver-web in a later cut.
 adapterRegistry.register('web', () => new PlaywrightAdapter());
+// MOB-2: the Appium codegen adapter — template strings only, NO appium/wdio dep in core.
+// `platform: mobile` (qa/capabilities.yaml) loads @sungen/driver-mobile (the SPI capability)
+// and selects this adapter (the runtime codegen). `appium` is the explicit alias.
+adapterRegistry.register('mobile', () => new AppiumAdapter());
+adapterRegistry.register('appium', () => new AppiumAdapter());

package/src/generators/test-generator/step-mapper.ts

@@ -1,9 +1,9 @@
 import { ParsedStep } from '../gherkin-parser';
 import { TemplateEngine } from './template-engine';
+import { adapterRegistry } from './adapters';
 import { PatternRegistry, PatternContext } from './patterns';
 import { SelectorResolver } from './utils/selector-resolver';
 import { DataResolver } from './utils/data-resolver';
-import * as path from 'path';
 
 export interface MappedStep {
   code: string; // Generated Playwright code
@@ -35,15 +35,18 @@ export class StepMapper {
   private inRowScope: boolean = false;
   private rowScopeTable: string = '';
 
-  constructor(options: { verbose?: boolean; baseURL?: string; featureName?: string; screenName?: string; featurePath?: string; runtimeData?: boolean } = {}) {
+  constructor(options: { verbose?: boolean; baseURL?: string; featureName?: string; screenName?: string; featurePath?: string; runtimeData?: boolean; framework?: string } = {}) {
     this.verbose = options.verbose ?? false;
     this.baseURL = options.baseURL || null;  // null means path-only navigation
     this.featureName = options.featureName;
     this.screenName = options.screenName;
     this.featurePath = options.featurePath;
-    // Use Playwright templates as default for pattern-based generation
-    const playwrightTemplatesDir = path.join(__dirname, 'adapters', 'playwright', 'templates');
-    this.templateEngine = new TemplateEngine(playwrightTemplatesDir);
+    // Render step templates from the ACTIVE adapter's template set (web→Playwright,
+    // mobile→Appium). The adapter owns its templatesDir; resolving it here keeps step
+    // rendering and the file skeleton (code-generator) on the same framework.
+    const framework = options.framework || 'web';
+    const templatesDir = adapterRegistry.getAdapter(framework).templatesDir;
+    this.templateEngine = new TemplateEngine(templatesDir);
     this.patternRegistry = new PatternRegistry();
     this.selectorResolver = new SelectorResolver(undefined, options.screenName);
     this.dataResolver = new DataResolver(undefined, options.screenName, options.runtimeData);

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

@@ -168,6 +168,18 @@ export class TemplateEngine {
       const dialogRootContent = fs.readFileSync(dialogRootPath, 'utf-8');
       Handlebars.registerPartial('dialog-root', dialogRootContent);
     }
+
+    // Adapter-agnostic: register any OTHER top-level partial in partials/ by its basename
+    // (the named registrations above are playwright's; the appium adapter ships
+    // appium-selector / appium-selector-expr). Idempotent — re-registering by name is harmless.
+    const partialsDir = path.join(this.stepsTemplatesDir, 'partials');
+    if (fs.existsSync(partialsDir)) {
+      for (const f of fs.readdirSync(partialsDir)) {
+        if (!f.endsWith('.hbs')) continue;
+        const name = f.replace(/\.hbs$/, '');
+        Handlebars.registerPartial(name, fs.readFileSync(path.join(partialsDir, f), 'utf-8'));
+      }
+    }
   }
 
   private loadTemplate(templateName: string, isStepTemplate: boolean = false): HandlebarsTemplateDelegate {
@@ -179,7 +191,7 @@ export class TemplateEngine {
     
     // Try to find template in organized folders
     if (isStepTemplate) {
-      const folders = ['actions', 'assertions', 'navigation', 'setup', 'partials'];
+      const folders = ['actions', 'assertions', 'navigation', 'setup', 'gestures', 'partials'];
       
       for (const folder of folders) {
         const templatePath = path.join(baseDir, folder, `${templateName}.hbs`);

package/src/harness/audit.ts

@@ -81,9 +81,14 @@ function catalogIdFromScreenDir(screenDir: string): string {
  * future `mobile/<x>` or `perf/<x>` unit routes to that capability with no core change. `flows/<flow>`
  * has no `flows` capability → default (UI), which is correct (flows are a UI concept).
  */
-export function scoringCapabilityFor(catalogScreenName: string, defaultCap: string | undefined): string | undefined {
+export function scoringCapabilityFor(catalogScreenName: string, defaultCap: string | undefined, platform?: string): string | undefined {
   const seg = catalogScreenName.split('/')[0];
-  return seg && capabilityRegistry.get(seg) ? seg : defaultCap;
+  // Path segment wins (api/<area> → api). Then the active platform capability (mobile → mobile),
+  // when a driver registered one with that id. Else the default (web/bare screen → ui — unchanged,
+  // since `web` has no capability of its own). See docs/spec/sungen-platform-capability-routing-spec.md.
+  if (seg && capabilityRegistry.get(seg)) return seg;
+  if (platform && capabilityRegistry.get(platform)) return platform;
+  return defaultCap;
 }
 
 export function runAudit(screenDir: string, screenName: string): AuditReport {
@@ -106,8 +111,11 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // UI capability). A capability that provides no catalog/gate falls back to the in-core UI
   // functions, so UI units — and api units until AO-2 adds the api providers — are byte-identical.
   discoverAndRegisterCapabilities();
+  // The active platform (web | mobile | …) activates its own capability for scoring + sensor routing.
+  // `web` has no capability of its own → scoringCap stays the default `ui` (byte-identical).
+  const platform = readCapabilities(projectRootFromScreenDir(screenDir)).platform;
   const defaultCap = capabilityRegistry.defaultCapabilityId();
-  const scoringCapId = scoringCapabilityFor(catalogScreenName, defaultCap);
+  const scoringCapId = scoringCapabilityFor(catalogScreenName, defaultCap, platform);
   const scoringCap = scoringCapId ? capabilityRegistry.get(scoringCapId) : undefined;
   const catalog = (scoringCap?.viewpoints?.() as Catalog | undefined) || loadCatalog();
   const spec = specCoverage(specPath, scenarios, featureText);
@@ -273,7 +281,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     ...(scenarios.some((s) => s.queryRefs && s.queryRefs.length) ? ['@query'] : []),
     ...(scenarios.some((s) => s.apiRefs && s.apiRefs.length) ? ['@api'] : []),
   ];
-  const routedGateIds = contextRouter.route({ target: { kind: 'screen', id: screenName }, artifact: 'feature', tags: featureTags }).gateSensorIds;
+  const routedGateIds = contextRouter.route({ target: { kind: 'screen', id: screenName }, artifact: 'feature', tags: featureTags, platform }).gateSensorIds;
   const gateSensorFindings = capabilityRegistry.sensors('gate')
     .filter((s) => routedGateIds.includes(s.id))
     .flatMap((s) => s.run({ screenName: catalogScreenName, cwd: projectRootFromScreenDir(screenDir), featureText, scenarios, universalGaps: gate.universalGaps }));

package/src/harness/catalog/drivers.yaml

@@ -31,7 +31,7 @@ drivers:
   mobile:
     kind: platform
     package: "@sungen/driver-mobile"
-    status: planned                     # PoC on the feat/mobile branch (Appium / Flutter)
+    status: shipped                     # @sungen/driver-mobile — Appium/WebdriverIO, gesture steps + web-parity gate
     runtime: appium
     adapter: mobile
     capabilities: ["@ui"]

package/src/orchestrator/ai-rules-updater.ts

@@ -65,6 +65,10 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['claude-skill-capture-mode-live.md', '.claude/skills/sungen-capture/mode-live.md'],
   ['claude-skill-capture-mode-local.md', '.claude/skills/sungen-capture/mode-local.md'],
   ['claude-skill-locale.md', '.claude/skills/sungen-locale/SKILL.md'],
+  // Mobile (Appium) skills — relevant for platform: mobile (MOB-5).
+  ['claude-skill-mobile-gestures.md', '.claude/skills/sungen-mobile-gestures/SKILL.md'],
+  ['claude-skill-capture-mobile.md', '.claude/skills/sungen-capture-mobile/SKILL.md'],
+  ['claude-skill-selector-fix-mobile.md', '.claude/skills/sungen-selector-fix-mobile/SKILL.md'],
 
   // Agents — Claude Code sub-agents (isolated context). Copilot runs these inline.
   ['claude-agent-reviewer.md', '.claude/agents/sungen-reviewer.md'],
@@ -96,6 +100,10 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['github-skill-sungen-capture-mode-live.md', '.github/skills/sungen-capture/mode-live.md'],
   ['github-skill-sungen-capture-mode-local.md', '.github/skills/sungen-capture/mode-local.md'],
   ['github-skill-sungen-locale.md', '.github/skills/sungen-locale/SKILL.md'],
+  // Mobile (Appium) skills — relevant for platform: mobile (MOB-5).
+  ['github-skill-sungen-mobile-gestures.md', '.github/skills/sungen-mobile-gestures/SKILL.md'],
+  ['github-skill-sungen-capture-mobile.md', '.github/skills/sungen-capture-mobile/SKILL.md'],
+  ['github-skill-sungen-selector-fix-mobile.md', '.github/skills/sungen-selector-fix-mobile/SKILL.md'],
 ];
 
 // Skill/asset directories retired in a previous refactor. `sungen update` removes

package/src/orchestrator/templates/ai-instructions/claude-skill-capture-mobile.md

@@ -0,0 +1,184 @@
+---
+name: sungen-capture-mobile
+description: 'Capture a live mobile app screen via Appium MCP — locator tree + screenshot for visual context. Auto-loaded by create-test when the screen is @platform:mobile/android/ios.'
+user-invocable: false
+---
+
+## Purpose
+
+Launch a mobile app on a device/emulator, capture **one locator tree** (`generate_locators`) and **one screenshot**, and save them as visual context for test generation. The mobile analogue of `sungen-capture-live` — same job, Appium MCP instead of Playwright MCP.
+
+Use when the target is a native/Flutter/React-Native app (`@platform:android` or `@platform:ios`) running on a connected device or emulator.
+
+---
+
+## Prerequisites
+
+- `appium-mcp` connected (see `/mcp`). It runs Appium **embedded** — no separate server needed.
+- A device/emulator booted: `adb devices` shows one for Android; a Simulator for iOS.
+- The app **installed** on the device (`adb install -r <app>.apk` for Android).
+- The screen's `Path:` (in `<screen>/features/*.feature` or `spec.md`) gives the app entry as
+  `<appPackage>/<appActivity>` (Android) or bundleId (iOS), e.g. `com.kngroup.media.converter/.MainActivity`.
+
+---
+
+## Steps
+
+### 1. Resolve target app + entry
+
+Resolve in this order:
+1. `Path:` line in the feature / `App ID` in `spec.md` → split into `appPackage` + `appActivity`.
+   A dual-id Path (`<pkg>/<activity> | <iosBundleId>`) → take the part for the OS you are exploring
+   (left of `|` = Android pkg/activity, right = iOS bundle id).
+2. If missing → `AskUserQuestion`: *"What is the appPackage/appActivity (Android) or bundleId (iOS)?"*
+3. **Navigation recipe** — read the feature's `Background:` (the in-app web-path analog). Line 1
+   `Given User is on [Home] screen` is the launcher/landing screen the app opens on; each following
+   `When/And User tap [...]` (or gesture) is one hop toward the target screen. You will **replay**
+   these in step 4.5 so you scan the screen this feature targets — not the launcher. An anchor-only
+   Background (no nav steps) ⇒ the target IS the launcher screen ⇒ no navigation needed.
+
+### 2. Select device
+
+`select_device` with `platform: android` (or `ios`). If exactly one device, it auto-selects.
+If several, list them and ask the user which `deviceUdid`.
+
+### 3. Create the session
+
+`appium_session_management` `action=create`, `platform=android`, capabilities (JSON string):
+```
+appium:appPackage, appium:appActivity, appium:udid,
+appium:noReset=true, appium:autoGrantPermissions=true, appium:newCommandTimeout=300
+```
+For iOS, call `prepare_ios_simulator` first, then create with `appium:bundleId`.
+
+### 4. ⚠️ Wait for the screen to actually render
+
+**This is the #1 gotcha for Flutter / RN apps.** Right after launch the app often shows a blank
+splash — and the locator tree will contain **zero usable elements** (just an empty `FrameLayout`).
+Do **not** capture yet. Take a quick `appium_screenshot`; if it's blank/splash, wait and re-check
+until real content is drawn. Only then capture. (A Flutter app on a loading screen looks "invisible"
+to Appium; the same app on a rendered screen exposes its full Semantics tree.)
+
+### 4.5. ⚠️ Navigate to the target screen (replay the navigation recipe)
+
+**This is what makes capture land on the RIGHT screen** — the mobile equivalent of `page.goto(url)`
+on web. After the launcher screen has rendered, replay the `Background:` nav steps so Appium ends up
+on the screen this feature targets, *then* capture there.
+
+For each nav step **after** the `Given User is on [Home] screen` anchor, in order:
+1. `generate_locators` (or `appium_get_page_source`) on the CURRENT screen.
+2. Resolve the step's `[Label]` against the live tree — prefer `accessibility id`, then visible
+   `text`/`content-desc`, then an `xpath` on a distinctive substring. Gestures (`scroll to [X]`,
+   `swipe …`) follow `sungen-mobile-gestures`.
+3. Perform the tap/gesture, then **wait for the next screen to render** (same blank-splash guard as
+   step 4) before the next step.
+
+After the LAST step you are on the target screen — capture HERE (steps 5–6).
+
+- **Anchor-only Background** (no nav steps) ⇒ the target IS the launcher screen ⇒ skip this step.
+- **A step won't resolve** (its `[Label]` matches no element) ⇒ **STOP. Do not capture the wrong
+  screen.** Screenshot where you are and report: *"recipe step N: [Label] not found — fix the
+  Background nav path."* Fail loud (run-test would fail at the same step anyway).
+- **No recipe yet** (guided-stub Background, but the target is NOT the launcher) ⇒ drive to the
+  screen interactively off the live tree (if unsure which control leads there, `AskUserQuestion`),
+  then **report the exact nav steps you took** so create-test/add-screen can write them into the
+  Background. Do **not** edit the `.feature` yourself — Gherkin authorship stays with those commands.
+
+### 5. Capture the locator tree (primary AI context)
+
+Call **`generate_locators`** — this is the mobile equivalent of the web accessibility snapshot. It
+returns priority-ranked locators per interactable element: `accessibility id`, `id`, platform-native
+(`-android uiautomator` / `-ios predicate string`), and `xpath`, plus `content-desc`/`text`,
+`clickable`, `enabled`. This is what `sungen-tc-generation` and `sungen-selector-keys` consume.
+
+If the tree is huge, also `appium_get_page_source` (saved to a file) and grep it — never dump the
+full XML inline.
+
+### 6. Screenshot
+
+`appium_screenshot` → save to:
+```
+qa/screens/<screen>/requirements/ui/mobile-<timestamp>.png
+```
+`<timestamp>` = `YYYYMMDD-HHMM` local (e.g. `mobile-20260605-1645.png`).
+
+### 7. Detect discrepancies vs spec
+
+If `spec.md` exists, cross-check `generate_locators` labels against spec sections (fields in spec but
+not on screen, and vice-versa). Report; do **not** auto-edit `spec.md`.
+
+### 8. End the session
+
+`appium_session_management` `action=delete` to free the device. Always clean up.
+
+### 9. Report back
+
+> Captured mobile screen `<appPackage>`:
+> - Reached via: <N nav steps replayed from the Background recipe, or "launcher screen — no nav">
+> - Locators: <N> interactable elements (M with accessibility-id)
+> - Screenshot: `requirements/ui/mobile-<timestamp>.png`
+> - Discrepancies vs spec: <count, or "none">
+> - Discovered nav steps (only if the recipe was empty): <the taps you took, for create-test/add-screen to write into the Background>
+
+Hand back to the calling command.
+
+---
+
+## Cross-platform discovery (`@platform:mobile` — explore one OS, layer the rest)
+
+When the screen is **`@platform:mobile`** (write-once-run-both), discover the **shared** cases first,
+then peel off only what is genuinely OS-specific. You do **not** need to explore both OSes up front —
+Flutter/RN expose the same Semantics on each, so one exploration covers most of it.
+
+1. **Explore whichever OS has a device up** (Android or iOS — symmetric for Flutter). Capture the tree.
+2. **Classify each component** into THREE buckets (not two):
+   - **Shared-exact** → a stable `accessibility id` equal on both OSes (Flutter Semantics → same value on
+     Android `content-desc` AND iOS `name`) → flat `type: accessibility-id` key in `<screen>.feature`.
+   - **Shared-variant** → SAME step/assertion on both OSes but the LOCATOR differs (composite
+     `content-desc` vs `-ios predicate`; partial/dynamic text via `descriptionContains` vs predicate
+     `CONTAINS`; a different attribute) → STILL `<screen>.feature`, with `android:`/`ios:` variant keys in
+     selectors.yaml. **A native locator alone is NOT a reason to split** — default for composite/partial text.
+   - **Sub-feature** → ONLY for genuine SCENARIO divergence: an element on ONE OS only, divergent
+     steps/flow, an OS-exclusive gesture/permission/dialog flow, or a case needing a per-platform
+     `nth`/`scope` (a variant can't diverge those). → `<screen>-android.feature` / `<screen>-ios.feature`.
+3. **Report the classification** so create-test/run-test scaffolds the right thing:
+   - `<screen>.feature`         `@platform:mobile`  ← shared-exact AND shared-variant (the vast majority)
+   - `<screen>-android.feature` `@platform:android` ← ONLY scenario-divergent Android cases
+   - `<screen>-ios.feature`     `@platform:ios`     ← ONLY scenario-divergent iOS cases
+4. **Verifying the other OS needs no second exploration** — just running the shared spec there
+   (`MOBILE_PLATFORM=both`) IS the check. Re-capture on the 2nd OS only for components that fail, and
+   move those into that OS's sub-feature. (Asking devs to add a Semantics label to an unlabeled element
+   converts an OS-specific case back into a shared one — prefer that when feasible.)
+
+## Selector-quality notes (carry into selectors.yaml)
+
+- **Prefer `accessibility id`** (Android `content-desc` / iOS `accessibilityIdentifier`) — most stable.
+- For **Flutter**, the Semantics label surfaces as `content-desc` ⇒ it usually equals the **visible
+  text**, so it is **locale-dependent** ("Good afternoon!", "English"). Keep such values in test-data
+  and use `{{variable}}` + locale overlays (see `sungen-locale`).
+- **Composite nodes**: cards may concatenate child text into one `content-desc` with `\n` → prefer an
+  xpath `contains(@content-desc,'…')` on a distinctive substring.
+- **Duplicate labels** → use `nth`. **Unlabelled controls** (search fields, icon buttons) → fall back
+  to `xpath` / class.
+
+---
+
+## What this skill does NOT do
+
+- Does not run tests or generate `selectors.yaml` (that's `/sungen:run-test` + `sungen-selector-fix-mobile`)
+- Does not generate Gherkin (that's `sungen-tc-generation`) — it may *report* discovered nav steps,
+  but writing them into the Background is create-test/add-screen's job
+- Does not handle login/auth state (mobile auth is a separate concern — deep link / test build)
+- Captures **the feature's target screen** per invocation — reached by replaying the Background
+  navigation recipe (step 4.5), not just the launcher. For a *different* screen, give it its own
+  feature + recipe and re-invoke.
+
+---
+
+## Relationship to other capture skills
+
+- `sungen-capture-figma` / `sungen-capture-local` — design/image sources (platform-agnostic)
+- `sungen-capture-live` — web (Playwright MCP)
+- `sungen-capture-mobile` — this skill, mobile (Appium MCP)
+
+All write to `requirements/ui/` and report back to the caller.