@sun-asterisk/sungen 3.2.24-beta.6 → 3.2.24

package/dist/orchestrator/templates/specs-db.ts

@@ -27,7 +27,7 @@ const ident = (s: string): string => {
 // SQL engines: verified via the direct guarded-SELECT path and needing the `$n`→`?` placeholder
 // rewrite. This literal is the single source of truth for that rewrite condition and is quoted, by
 // name, in the sungen-gherkin-syntax skill's "direct SQL verification" note — keep them in sync.
-const SUPPORTED_ENGINES = ['postgres', 'sqlite', 'mysql'] as const;
+const SUPPORTED_ENGINES = ['postgres', 'sqlite', 'device-sqlite', 'mysql'] as const;
 // NoSQL engines: implement the Engine contract natively (no SQL rewrite). Tracked separately so the
 // SQL-rewrite guard and its skill-parity test stay pinned to the three SQL engines above.
 const NOSQL_ENGINES = ['cosmos', 'mongodb', 'dynamodb'] as const;
@@ -43,9 +43,15 @@ interface SshConfig {
 }
 
 interface DataSourceConfig {
-  engine: 'postgres' | 'mysql' | 'sqlite' | 'cosmos' | 'mongodb' | 'dynamodb';
+  engine: 'postgres' | 'mysql' | 'sqlite' | 'device-sqlite' | 'cosmos' | 'mongodb' | 'dynamodb';
   url: string;
   readonly?: boolean;
+  // device-sqlite (mobile): an ON-DEVICE app database, pulled FRESH per query through the active
+  // Appium session (pullFile's `@<package>/<path>` app-container syntax — run-as under the hood,
+  // so it needs a debuggable build or an emulator). `package` = the app id, `db_path` = the
+  // path inside the app's data dir (e.g. databases/app.db). No `url`. Same SQLite dialect.
+  package?: string;
+  db_path?: string;
   statement_timeout_ms?: number;
   max_rows?: number;
   // Fallback path: tunnel the DB SOCKET through an SSH bastion. DB-only — the browser/E2E
@@ -160,7 +166,7 @@ function loadConfig(): Record<string, DataSourceConfig> {
  * reorder is essential there too (an author-written PartiQL `WHERE sk = $2 AND pk = $1`).
  */
 export function rewritePlaceholders(engine: string, sql: string, params: any[]): { sql: string; params: any[] } {
-  if (engine !== 'sqlite' && engine !== 'mysql' && engine !== 'dynamodb') return { sql, params };
+  if (engine !== 'sqlite' && engine !== 'device-sqlite' && engine !== 'mysql' && engine !== 'dynamodb') return { sql, params };
   let out = '';
   let inStr = false;
   const newParams: any[] = [];
@@ -517,10 +523,11 @@ class DataSource {
     const { key, conf } = this.cfg(name);
     if (this.engines.has(key)) return { engine: this.engines.get(key)!, conf };
     let engine: Engine;
-    if (conf.engine === 'postgres' || conf.engine === 'mysql' || conf.engine === 'sqlite') {
-      // url is required for the SQL engines (host-based, or a sqlite file path). NoSQL engines that
-      // have no connection URL (e.g. DynamoDB region+creds) supply their own config and skip this.
-      if (!conf.url) throw new Error(`Data Driver: datasource "${key}" has no url (set it in .env.qa).`);
+    if (conf.engine === 'postgres' || conf.engine === 'mysql' || conf.engine === 'sqlite' || conf.engine === 'device-sqlite') {
+      // url is required for the HOST-based SQL engines (or a sqlite file path). device-sqlite has
+      // no url — the file comes off the device (package + db_path, validated in its exec builder);
+      // NoSQL engines without a URL (e.g. DynamoDB region+creds) also supply their own config.
+      if (!conf.url && conf.engine !== 'device-sqlite') throw new Error(`Data Driver: datasource "${key}" has no url (set it in .env.qa).`);
       engine = new SqlEngine(conf.engine, await this.sqlExec(key, conf));
     } else if (conf.engine === 'cosmos') {
       engine = this.cosmosEngine(key, conf);
@@ -586,6 +593,62 @@ class DataSource {
         }
       };
     }
+    // device-sqlite — an ON-DEVICE app database. Every query pulls a FRESH copy through the
+    // active Appium session so the oracle always reads CURRENT device state (persistence checks
+    // assert AFTER actions). pullFile's `@<package>/<path>` app-container syntax uses run-as
+    // under the hood → needs a debuggable build or an emulator. SQLite WAL sidecars (-wal/-shm)
+    // are pulled best-effort alongside: Room defaults to WAL, where recent commits live in the
+    // -wal file — without it the main file silently misses the newest writes.
+    if (conf.engine === 'device-sqlite') {
+      if (!conf.package || !conf.db_path) {
+        throw new Error(`Data Driver: datasource "${key}" (device-sqlite) needs package: and db_path: (path inside the app data dir, e.g. databases/app.db).`);
+      }
+      const pkg = conf.package;
+      const rel = conf.db_path.replace(/^\/+/, '');
+      return async (sql, params) => {
+        const wd = (globalThis as any).driver;
+        if (!wd || typeof wd.pullFile !== 'function') {
+          throw new Error(`Data Driver: datasource "${key}" (device-sqlite) needs an active Appium session — device @query steps only run inside mobile specs.`);
+        }
+        const fs = require('node:fs'); const os = require('node:os'); const path = require('node:path');
+        const base = path.join(os.tmpdir(), `sungen-devdb-${process.pid}-${Date.now()}`);
+        const files: string[] = [];
+        const pull = async (suffix: string, required: boolean): Promise<void> => {
+          let b64: string | null = null;
+          let pullErr: unknown;
+          try {
+            b64 = await wd.pullFile(`@${pkg}/${rel}${suffix}`);
+          } catch (e) {
+            pullErr = e;
+            // pullFile's container route does `run-as cp → /data/local/tmp`, which newer Android
+            // blocks for the app UID. Fallback: stream base64 over run-as via `mobile: shell`
+            // (opt-in — APPIUM_ALLOW_ADB_SHELL=1, see the wdio.conf template).
+            try {
+              const out = await wd.execute('mobile: shell', { command: 'run-as', args: [pkg, 'base64', `${rel}${suffix}`] });
+              b64 = String(out).replace(/\s+/g, '');
+            } catch (e2) {
+              if (required) {
+                throw new Error(`Data Driver: could not pull @${pkg}/${rel} from the device. pullFile: ${pullErr} · shell fallback: ${e2} — needs a DEBUGGABLE build; if pullFile's container route fails on this Android version, set APPIUM_ALLOW_ADB_SHELL=1 (.env.appium).`);
+              }
+              return;
+            }
+          }
+          if (b64 == null) return;
+          fs.writeFileSync(base + suffix, Buffer.from(b64, 'base64'));
+          files.push(base + suffix);
+        };
+        await pull('', true);
+        await pull('-wal', false);
+        await pull('-shm', false);
+        try {
+          const Database = require('better-sqlite3');
+          const db = new Database(base, { readonly: false }); // WAL recovery needs write access to the TEMP copy
+          try { return db.prepare(sql).all(...params); } finally { db.close(); }
+        } finally {
+          for (const f of files) { try { fs.unlinkSync(f); } catch { /* best-effort */ } }
+        }
+      };
+    }
     // sqlite
     if (conf.ssh) console.warn(`Data Driver: datasource "${key}" sets ssh: but engine is sqlite (file-based) — ssh ignored.`);
     const Database = require('better-sqlite3');

package/dist/orchestrator/templates/wdio.conf.ts

@@ -178,6 +178,61 @@ function resolveLocaleCaps(): Record<string, unknown> {
 }
 const localeCaps = resolveLocaleCaps();
 
+// ── Connectivity self-heal (#615) ───────────────────────────────────────────
+// The connectivity/location steps mutate DEVICE state (airplane, wifi, data, GPS). A run that
+// aborts mid-toggle — e.g. an Appium session timeout during an airplane round-trip — leaves the
+// device offline as PERSISTENT state, so every later launch fails with the app's network error
+// and the next run dies at cold start. Restore the baseline around the run via host-side adb:
+// it works even when no Appium session survives (a spec-level after() cannot — the session is
+// exactly what died). Android-only (the mutating steps are Android-only), idempotent (on/on/on
+// is the baseline every suite assumes; offline scenarios set their own state mid-test), and
+// best-effort per command (a device lacking one command just skips that line).
+function restoreConnectivity(hook: string): void {
+  if (!RUN_ANDROID) return;
+  // Appium finds adb via ANDROID_HOME — PATH may not carry it (fresh CI runner), which would
+  // make every heal command fail silently. Resolve the same way Appium does, fall back to PATH.
+  const adbBin = process.env.ANDROID_HOME ? path.join(process.env.ANDROID_HOME, 'platform-tools', 'adb') : 'adb';
+  const adb = `"${adbBin}" -s ${process.env.ANDROID_UDID || '__ANDROID_UDID__'} shell`;
+  // stderr ignored: with a detached device the reads would otherwise spray raw adb errors on every run.
+  const sh = (cmd: string) => execSync(`${adb} ${cmd}`, { timeout: 10000, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+  // Detect-first: read each state and only touch what is actually wedged, so a healthy run
+  // costs four quick reads, mutates nothing, and logs nothing. Each fix lists every command
+  // variant (emulator `svc`, real-device `cmd`, API<30 fallbacks) — all best-effort, same
+  // direction, idempotent, so running the inapplicable ones is harmless.
+  let touched = false;
+  const heal = (read: string, wedged: string, fixes: string[]) => {
+    try {
+      if (sh(read) !== wedged) return;
+      for (const fix of fixes) { try { sh(fix); } catch { /* variant not on this API — fine */ } }
+      touched = true;
+    } catch { /* unreadable state (device gone / key absent) — leave untouched */ }
+  };
+  heal('settings get global airplane_mode_on', '1', [
+    'cmd connectivity airplane-mode disable',                       // API 30+
+    'settings put global airplane_mode_on 0',                       // API<30 wedge (settings+broadcast)
+    'am broadcast -a android.intent.action.AIRPLANE_MODE --ez state false',
+  ]);
+  heal('settings get global wifi_on', '0', [
+    'svc wifi enable',                                              // emulator flavor
+    'cmd -w wifi set-wifi-enabled enabled',                         // real-device flavor (svc can no-op silently)
+  ]);
+  heal('settings get global mobile_data', '0', [
+    'svc data enable',
+    'cmd phone data enable',
+  ]);
+  heal('cmd location is-location-enabled', 'false', ['cmd location set-location-enabled true']);
+  if (!touched) return;
+  console.log(`[sungen] connectivity self-heal (${hook}): device was offline — a previous run likely aborted mid-toggle. Baseline restored (airplane off, wifi/data/location on).`);
+  // Radios re-associate asynchronously (emulator wifi can take 10-30s) — wait for REAL IP
+  // connectivity before the session starts, or the app's first cold start still lands on its
+  // network-error dialog and the auth/first assert fails despite the heal.
+  for (let i = 0; i < 10; i++) {
+    try { execSync(`${adb} ping -c 1 -W 2 8.8.8.8`, { stdio: 'ignore', timeout: 8000 }); return; } catch { /* not yet */ }
+    try { execSync(`${adb} sleep 2`, { stdio: 'ignore', timeout: 8000 }); } catch { /* device gone — stop waiting */ return; }
+  }
+  console.log('[sungen] connectivity self-heal: no ICMP reply within ~30s — continuing (fine if this network blocks ping; otherwise the device may need a cold boot).');
+}
+
 export const config: WebdriverIO.Config = {
   runner: 'local',
   tsConfigPath: './tsconfig.json',
@@ -192,7 +247,10 @@ export const config: WebdriverIO.Config = {
   // Global auto-wait for $/$$ matchers (toBeDisplayed, click, …). Default is 3s, too short for a
   // heavy app's cold (re)launch — each scenario terminates+activates its app, so the first
   // find/click must wait out the splash/first-frame. 20s keeps slow native/Flutter apps green.
-  waitforTimeout: 20000,
+  // 30s (not the classic 20s): on a Compose app with looping in-app animations the accessibility
+  // manager can starve for 10s+ per query ("Timed out waiting for the root AccessibilityNodeInfo",
+  // observed live) — a 20s budget turns that latency into flaky not-found failures.
+  waitforTimeout: 30000,
 
   // Capability set(s) selected by MOBILE_PLATFORM (android | ios | both). Each cap carries its OWN
   // `specs` (per-OS routing): the Android cap runs android + mobile specs, the iOS cap runs ios +
@@ -217,6 +275,14 @@ export const config: WebdriverIO.Config = {
             'appium:noReset': true,
             'appium:autoGrantPermissions': true,
             'appium:newCommandTimeout': 300,
+            // Compose/animated UIs (a looping promo animation is enough) never report accessibility-idle,
+            // so every find first waits out UiAutomator2's full idle timeout — 10000ms by default. 2s keeps
+            // interactions responsive while still absorbing screen transitions. NOTE: milliseconds — the
+            // same-named XCUITest cap below is in seconds; the two drivers define the knob differently.
+            'appium:settings[waitForIdleTimeout]': 2000,
+            // Disable SYSTEM animation scales for the session — trims accessibility-tree churn so
+            // queries stall less on animation-heavy apps (in-app Compose animations still run).
+            'appium:disableWindowAnimation': true,
             // i18n: when SUNGEN_ENV/SUNGEN_LOCALE is a locale code, this overrides noReset→false and
             // adds appium:language/appium:locale so the app boots in that locale. Empty otherwise.
             ...localeCaps,
@@ -275,7 +341,23 @@ export const config: WebdriverIO.Config = {
   reporters: ['spec', [PwShapeReporter, {}]],
 
   // Auto-start a local Appium server on :4723 (base path '/')
-  services: ['appium'],
+  // Appium server options — security-gated features, each opt-in via .env.appium:
+  //   APPIUM_ALLOW_ADB_SHELL=1            → --allow-insecure uiautomator2:adb_shell
+  //     (raw shell access — device-level oracles like device-sqlite's run-as fallback)
+  //   APPIUM_CHROMEDRIVER_AUTODOWNLOAD=1  → --allow-insecure uiautomator2:chromedriver_autodownload
+  //     (hybrid WebView: downloads the chromedriver matching the device's WebView at session start —
+  //      without it, `switch to [X] frame` fails with "No Chromedriver found that can automate Chrome N")
+  // Both stay OFF by default (see docs/spec/security-and-telemetry-roadmap.md).
+  services: [
+    ['appium', (() => {
+      const feats: string[] = [];
+      if (process.env.APPIUM_ALLOW_ADB_SHELL) feats.push('uiautomator2:adb_shell');
+      if (process.env.APPIUM_CHROMEDRIVER_AUTODOWNLOAD) feats.push('uiautomator2:chromedriver_autodownload');
+      // NOTE: pass a comma-joined STRING — @wdio/appium-service JSON.stringifies arrays, which the
+      // appium server then reads as a JSON literal and the features silently never register.
+      return feats.length ? { args: { allowInsecure: feats.join(',') } } : {};
+    })()],
+  ],
   port: 4723,
   path: '/',
 
@@ -291,12 +373,27 @@ export const config: WebdriverIO.Config = {
     retries: 1,
   },
 
+  // expect-webdriverio's default assertion budget (~2s wait / 100ms interval) is tuned for
+  // sub-second finds. On an accessibility tree churned by looping in-app animations (a rotating
+  // promo carousel is enough) a single server-side find can take 5-15s, so every toBeDisplayed()
+  // would expire before its first query even returns — align the budget with waitforTimeout.
+  before: async () => {
+    const { setOptions } = await import('expect-webdriverio');
+    setOptions({ wait: 20000, interval: 500 });
+  },
+
+  // Connectivity self-heal (#615): onPrepare heals a device wedged by a previous KILLED run
+  // (its onComplete never fired) before the session starts; onComplete restores after this run,
+  // pass or fail. Both run in the launcher process, so they fire even when the worker/session died.
+  onPrepare: () => restoreConnectivity('onPrepare'),
+  onComplete: () => restoreConnectivity('onComplete'),
+
   // iOS + locale: XCUITest's `noReset:false` does NOT actually clear the app's data container
   // (verified live 2026-06-11) — a Flutter app that persisted its language on a previous launch keeps
   // it and ignores the new device locale, so the i18n run asserts the wrong language. Wipe the app
   // data via simctl BEFORE the session so first-launch locale detection re-runs. Android needs no
   // hook (its noReset:false reset works natively).
-  beforeSession: async (_config, capabilities) => {
+  beforeSession: async (_config, capabilities, specs) => {
     if (Object.keys(localeCaps).length === 0) return; // not a locale run
     const caps = capabilities as Record<string, unknown>;
     if (String(caps['platformName'] || '').toLowerCase() !== 'ios') return;

package/dist/utils/selector-types.d.ts

@@ -2,6 +2,6 @@
  * Valid selector types used across scaffold generator, selector resolver, and validator.
  * Single source of truth — import this instead of hardcoding.
  */
-export declare const VALID_SELECTOR_TYPES: readonly ["placeholder", "role", "testid", "label", "text", "page", "column", "locator", "id", "upload", "frame", "table", "accessibility-id", "xpath", "android-uiautomator", "ios-predicate"];
+export declare const VALID_SELECTOR_TYPES: readonly ["placeholder", "role", "testid", "label", "text", "page", "column", "locator", "id", "upload", "frame", "table", "accessibility-id", "xpath", "android-uiautomator", "ios-predicate", "css"];
 export type SelectorType = (typeof VALID_SELECTOR_TYPES)[number];
 //# sourceMappingURL=selector-types.d.ts.map

package/dist/utils/selector-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"selector-types.d.ts","sourceRoot":"","sources":["../../src/utils/selector-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,oBAAoB,iMAkBvB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC"}
+{"version":3,"file":"selector-types.d.ts","sourceRoot":"","sources":["../../src/utils/selector-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,oBAAoB,wMAmBvB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/utils/selector-types.js

@@ -23,5 +23,6 @@ exports.VALID_SELECTOR_TYPES = [
     'xpath', // cross-platform, last resort
     'android-uiautomator', // Android only — UiSelector expressions
     'ios-predicate', // iOS only — NSPredicate strings
+    'css', // hybrid WebView only — CSS inside a WEBVIEW context (after `switch to [X] frame`)
 ];
 //# sourceMappingURL=selector-types.js.map

package/dist/utils/selector-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"selector-types.js","sourceRoot":"","sources":["../../src/utils/selector-types.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACU,QAAA,oBAAoB,GAAG;IAClC,aAAa;IACb,MAAM;IACN,QAAQ;IACR,OAAO;IACP,MAAM;IACN,MAAM;IACN,QAAQ;IACR,SAAS;IACT,IAAI;IACJ,QAAQ;IACR,OAAO;IACP,OAAO;IACP,8EAA8E;IAC9E,kBAAkB,EAAK,sEAAsE;IAC7F,OAAO,EAAgB,8BAA8B;IACrD,qBAAqB,EAAE,wCAAwC;IAC/D,eAAe,EAAQ,iCAAiC;CAChD,CAAC"}
+{"version":3,"file":"selector-types.js","sourceRoot":"","sources":["../../src/utils/selector-types.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACU,QAAA,oBAAoB,GAAG;IAClC,aAAa;IACb,MAAM;IACN,QAAQ;IACR,OAAO;IACP,MAAM;IACN,MAAM;IACN,QAAQ;IACR,SAAS;IACT,IAAI;IACJ,QAAQ;IACR,OAAO;IACP,OAAO;IACP,8EAA8E;IAC9E,kBAAkB,EAAK,sEAAsE;IAC7F,OAAO,EAAgB,8BAA8B;IACrD,qBAAqB,EAAE,wCAAwC;IAC/D,eAAe,EAAQ,iCAAiC;IACxD,KAAK,EAAkB,mFAAmF;CAClG,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.24-beta.6",
+  "version": "3.2.24",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -39,8 +39,8 @@
     "@babel/types": "^7.28.5",
     "@cucumber/gherkin": "^37.0.0",
     "@cucumber/messages": "^31.0.0",
-    "@sungen/driver-data-factory": "3.2.24-beta.6",
-    "@sungen/driver-ui": "3.2.24-beta.6",
+    "@sungen/driver-data-factory": "3.2.24",
+    "@sungen/driver-ui": "3.2.24",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",

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

@@ -0,0 +1,9 @@
+// Simulated biometric input — EMULATOR/SIMULATOR only (a real device needs a real finger; the
+// command is rejected there and the step fails loud). Android: `mobile: fingerprint` — finger 1
+// must be ENROLLED on the emulator (Settings → Security); an unenrolled id gives the no-match
+// path. iOS Simulator: `mobile: sendBiometricMatch` (Features → Touch/Face ID enrolled).
+if (driver.isIOS) {
+  await driver.execute('mobile: sendBiometricMatch', { type: '{{#if faceId}}faceId{{else}}touchId{{/if}}', match: {{#if match}}true{{else}}false{{/if}} });
+} else {
+  await driver.execute('mobile: fingerprint', { fingerprintId: {{#if match}}1{{else}}9{{/if}} });
+}

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

@@ -1,9 +1,10 @@
 {{!-- WebdriverIO/Appium has no .check(). Ensure the toggle ends up ON: read the current state and
       tap only if it's not already on, so the step is idempotent (re-running a passing test, or
       running under `noReset` with unknown persisted state, won't flip it back off). State is read
-      the same way the checked/unchecked assertions read it — `checked` attribute on Android,
-      `value` attribute on iOS ('1' = on) — since that's what actually carries state on a Flutter
-      composite row; `isSelected()` is a fallback for widgets where it doesn't. The tap itself uses
+      the same way the checked/unchecked assertions read it — through the __assertCheckedState
+      oracle's __probeCheckedSignals (test-file preamble), which weighs `checked`/`value`, `selected`
+      and isSelected() on the node and its descendants, because no single one of them is reliable on
+      a custom-rendered control. The tap itself uses
       the trailing-edge coordinate method (not a centre .click()): on a full-width composite row the
       a11y node merges the label with the switch, so a centre tap lands on the label and doesn't
       flip the control. --}}
@@ -12,9 +13,13 @@ await (async () => {
   // Fail loud with the REAL cause when the element never resolved — getElementRect(undefined)
   // otherwise throws a cryptic `Malformed type for "elementId"` that masks the not-found (#430).
   if (!__cb.elementId) throw new Error((__cb as any).error?.message || `Element not found: ${__cb.selector}`);
-  let __on = false;
-  try { __on = driver.isIOS ? (await __cb.getAttribute('value')) === '1' : (await __cb.getAttribute('checked')) === 'true'; }
-  catch { try { __on = await __cb.isSelected(); } catch { /* state unreadable — tap anyway */ } }
+  // Read the CURRENT state through the same oracle the checked assertions use. The old read here
+  // was `getAttribute('checked') === 'true'` with an isSelected() fallback in a `catch` — but on
+  // Android that read never throws (UiAutomator2 defaults `checked` to "false" on every node), so
+  // the fallback never fired and a custom-rendered toggle already ON read as OFF. This step then
+  // tapped it and turned it OFF — the idempotence guard silently inverted.
+  const __signals = await __probeCheckedSignals(__cb);
+  const __on = __signals.some(s => s.value);
   if (__on) return;
 
   const r = await driver.getElementRect(__cb.elementId);

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

@@ -0,0 +1,8 @@
+// Open a deep link into the app — VIEW intent on Android, XCUITest deepLink on iOS (Simulator).
+// THE entry point for push-param / universal-link routing scenarios.
+await (async () => {
+  {{#if dataRef}}const __url = String(testData.get('{{dataRef}}'));{{else}}const __url = '{{escapeQuotes url}}';{{/if}}
+  const __pkg = __resolveAppId();
+  await driver.execute('mobile: deepLink', driver.isIOS ? { url: __url, bundleId: __pkg } : { url: __url, package: __pkg });
+  await driver.pause(1500); // let the routed screen mount before the next step asserts on it
+})();

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

@@ -0,0 +1,11 @@
+// Android-only: XCUITest cannot toggle Location Services — fail loud, never silently skip.
+if (driver.isIOS) {
+  throw new Error('turn device location {{#if on}}on{{else}}off{{/if}}: iOS/XCUITest cannot toggle Location Services — run this scenario on Android or tag it @platform:android');
+}
+// `mobile: toggleGps` flips blindly, so read `mobile: isGpsEnabled` first and only toggle when the
+// state differs (idempotent). NOTE: the execute-method aliases, not the legacy JSONWP wrappers —
+// WDIO v9 removed driver.isLocationServicesEnabled()/toggleLocationServices().
+await (async () => {
+  const __locOn = await driver.execute('mobile: isGpsEnabled');
+  if (__locOn !== {{#if on}}true{{else}}false{{/if}}) { await driver.execute('mobile: toggleGps'); }
+})();

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

@@ -0,0 +1,21 @@
+// Reinstall the app: remove → install from the session's build file → launch → settle.
+// Persistence oracles (dismissals, pins) hinge on what survives a reinstall.
+await (async () => {
+  const __pkg = __resolveAppId();
+  const __caps = (driver.requestedCapabilities || {}) as Record<string, string>;
+  const __appPath = __caps['appium:app'] || __caps['app'];
+  if (!__appPath) {
+    throw new Error('reinstall the app: the session must install from a build file — set APP_APK (Android) / IOS_APP (iOS) so the appium:app capability is present.');
+  }
+  try { await driver.removeApp(__pkg); } catch { /* not installed */ }
+  await driver.installApp(__appPath);
+  await driver.activateApp(__pkg);
+  let __prevHad = false;
+  await driver
+    .waitUntil(async () => {
+      const src = await driver.getPageSource();
+      const has = /content-desc="[^"]+"|\btext="[^"]+"/.test(src);
+      const ok = has && __prevHad; __prevHad = has; return ok;
+    }, { timeout: 45000, interval: 400 })
+    .catch(() => { /* best-effort — first launch after install can be the slowest */ });
+})();

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

@@ -0,0 +1,16 @@
+// Restart the app: kill → relaunch → wait for rendered content (same settle oracle as the
+// per-scenario relaunch hook — a cold start first paints a contentless skeleton).
+await (async () => {
+  const __pkg = __resolveAppId();
+  try { await driver.terminateApp(__pkg); } catch { /* not running */ }
+  await driver.pause(500);
+  await driver.activateApp(__pkg);
+  let __prevHad = false;
+  await driver
+    .waitUntil(async () => {
+      const src = await driver.getPageSource();
+      const has = /content-desc="[^"]+"|\btext="[^"]+"/.test(src);
+      const ok = has && __prevHad; __prevHad = has; return ok;
+    }, { timeout: 30000, interval: 400 })
+    .catch(() => { /* best-effort — the next step has its own wait */ });
+})();

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

@@ -0,0 +1,11 @@
+// Android-only: XCUITest exposes no connectivity control — fail loud, never silently skip.
+if (driver.isIOS) {
+  throw new Error('turn {{kind}} {{#if on}}on{{else}}off{{/if}}: iOS/XCUITest cannot toggle device connectivity — run this scenario on Android or tag it @platform:android');
+}
+{{#if isAirplane}}
+// Airplane {{#if on}}ON kills wifi+data{{else}}OFF restores wifi+data{{/if}} — set all three explicitly.
+await driver.execute('mobile: setConnectivity', { wifi: {{#if on}}false{{else}}true{{/if}}, data: {{#if on}}false{{else}}true{{/if}}, airplaneMode: {{#if on}}true{{else}}false{{/if}} });
+{{else}}
+await driver.execute('mobile: setConnectivity', { {{kindKey}}: {{#if on}}true{{else}}false{{/if}} });
+{{/if}}
+await driver.pause(1500); // let the radio state settle before the next step acts on the UI

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

@@ -1,7 +1,7 @@
 {{!-- WebdriverIO/Appium has no .uncheck(). Ensure the toggle ends up OFF: tap only if currently on,
       so the step is idempotent under repeat runs / persisted `noReset` state. State read + tap
-      method mirror check-action.hbs (see there for why): platform-correct attribute read
-      (`checked`/`value`) with an isSelected() fallback, then a trailing-edge coordinate tap rather
+      method mirror check-action.hbs (see there for why): state via __probeCheckedSignals (the
+      multi-signal oracle), then a trailing-edge coordinate tap rather
       than a centre .click() (a centre tap on a full-width composite row hits the label, not the
       switch). --}}
 await (async () => {
@@ -9,9 +9,13 @@ await (async () => {
   // Fail loud with the REAL cause when the element never resolved — getElementRect(undefined)
   // otherwise throws a cryptic `Malformed type for "elementId"` that masks the not-found (#430).
   if (!__cb.elementId) throw new Error((__cb as any).error?.message || `Element not found: ${__cb.selector}`);
-  let __on = false;
-  try { __on = driver.isIOS ? (await __cb.getAttribute('value')) === '1' : (await __cb.getAttribute('checked')) === 'true'; }
-  catch { try { __on = await __cb.isSelected(); } catch { /* state unreadable — leave as-is */ } }
+  // Read the CURRENT state through the same oracle the checked assertions use. The old read here
+  // was `getAttribute('checked') === 'true'` with an isSelected() fallback in a `catch` — but on
+  // Android that read never throws (UiAutomator2 defaults `checked` to "false" on every node), so
+  // the fallback never fired and a custom-rendered toggle already ON read as OFF. This step then
+  // tapped it and turned it ON — the idempotence guard silently inverted.
+  const __signals = await __probeCheckedSignals(__cb);
+  const __on = __signals.some(s => s.value);
   if (!__on) return;
 
   const r = await driver.getElementRect(__cb.elementId);

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

@@ -1,4 +1,10 @@
-// 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');
+{{!-- Checkbox/toggle state via the __assertCheckedState oracle (test-file preamble), NOT a bare
+      toHaveAttribute. A single `checked`(Android)/`value`(iOS) read cannot be trusted on its own:
+      UiAutomator2 defaults `checked` to "false" on EVERY node, so a custom-rendered control that
+      publishes no checked semantics (Flutter without Semantics(checked:), RN without
+      accessibilityState) reports a confident false while sitting visibly ON. The oracle probes
+      `checked`/`value`, `selected` and isSelected() on the node AND on its descendants (on a
+      composite row the state routinely sits on an inner node), and passes on ANY positive signal.
+      `selected` alone is no substitute either — toBeSelected() is always false for a Flutter
+      Switch, which is why this template stopped using it. --}}
+await __assertCheckedState(await ({{> locator}}), true, '{{escapeQuotes selectorRef}}');

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

@@ -0,0 +1,16 @@
+{{!-- Device-log oracle (Android: logcat · iOS: syslog) — makes SILENT failure modes and analytics
+      events observable. getLogs returns entries SINCE THE LAST CALL (incremental buffer), so
+      poll-accumulate up to 10s before failing loud with the log type in the message. --}}
+await (async () => {
+  {{#if dataRef}}const __needle = String(testData.get('{{dataRef}}'));{{else}}const __needle = '{{escapeQuotes value}}';{{/if}}
+  const __type = driver.isIOS ? 'syslog' : 'logcat';
+  let __buf = '';
+  const __t0 = Date.now();
+  while (Date.now() - __t0 < 10000) {
+    const __entries = (await driver.getLogs(__type)) as Array<{ message?: string } | string>;
+    __buf += __entries.map((e) => (typeof e === 'string' ? e : (e && e.message) || '')).join('\n') + '\n';
+    if (__buf.includes(__needle)) return;
+    await driver.pause(500);
+  }
+  throw new Error(`device log (${__type}) did not contain ${JSON.stringify(__needle)} within 10s`);
+})();

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

@@ -0,0 +1,5 @@
+{{!-- The element must vanish within the window (auto-dismiss / expiry oracle). Plain $() on
+      purpose — never __ensureVisible: scroll-hunting for something that should disappear would
+      drag the screen away. A 2s grace absorbs accessibility-tree churn latency without hiding a
+      genuinely stuck element. --}}
+await $({{> appium-selector-expr}}).waitForDisplayed({ reverse: true, timeout: {{seconds}} * 1000 + 2000, timeoutMsg: '{{selectorRef}} still visible after the {{seconds}}s disappear window' });

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

@@ -1,4 +1,6 @@
-// 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');
+{{!-- The unchecked twin of checked-assertion — same __assertCheckedState oracle, expected=false.
+      Deliberately NOT symmetric with the checked direction: "unchecked" requires that NO probed
+      signal anywhere (node or descendant, `checked`/`value`/`selected`/isSelected()) reads
+      positive, so a visibly-ON custom-rendered control cannot slip through as a false PASS the way
+      a single Android `checked="false"` read would let it. --}}
+await __assertCheckedState(await ({{> locator}}), false, '{{escapeQuotes selectorRef}}');

package/src/generators/test-generator/adapters/appium/templates/steps/assertions/state-with-filter-assertion.hbs

@@ -1,6 +1,7 @@
 {{!-- State-with-filter (mobile): $$ over the base selector, per-OS text read (hand-rolled — no
       CSS filter() combinator on Appium) matched against dataValue, then assert the state on the
-      match. checked/selected map to the composite-row attribute (mirrors checked-assertion);
+      match. checked/selected go through the __assertCheckedState oracle (mirrors checked-assertion) —
+      a single `checked`/`value` read is unreliable on a custom-rendered control;
       empty is a text read; enabled/focused use direct WDIO matchers. A state with no
       native-mobile analog (sorted*, aria-busy loading) fails loud, matching sorted-assertion's
       house style. --}}
@@ -13,8 +14,8 @@
     if (String(__s.find(s => s && String(s).trim() !== '') ?? '').trim() === __expected) { __el = __c; break; }
   }
   if (!__el) throw new Error(`[sungen] No match with text "${__expected}" to assert state on`);
-  {{#if (or selectedProbe (eq stateAssertion "toBeChecked()"))}}await expect(__el).toHaveAttribute(driver.isIOS ? 'value' : 'checked', driver.isIOS ? '1' : 'true');
-  {{else if (eq stateAssertion "toBeChecked({ checked: false })")}}await expect(__el).not.toHaveAttribute(driver.isIOS ? 'value' : 'checked', driver.isIOS ? '1' : 'true');
+  {{#if (or selectedProbe (eq stateAssertion "toBeChecked()"))}}await __assertCheckedState(__el, true, `item with "${__expected}"`);
+  {{else if (eq stateAssertion "toBeChecked({ checked: false })")}}await __assertCheckedState(__el, false, `item with "${__expected}"`);
   {{else if (eq stateAssertion "toBeEnabled()")}}await expect(__el).toBeEnabled();
   {{else if (eq stateAssertion "toBeFocused()")}}await expect(__el).toBeFocused();
   {{else if (eq stateAssertion "toBeEmpty()")}}await expect(__el).toHaveText('');

package/src/generators/test-generator/adapters/appium/templates/steps/assertions/still-visible-after-assertion.hbs

@@ -0,0 +1,4 @@
+{{!-- The element must SURVIVE the window (e.g. a barcode valid for 60s, a banner that must not
+      auto-dismiss). Wait out the window first, then run the platform-aware visibility oracle. --}}
+await driver.pause({{seconds}} * 1000);
+await __assertVisible({{> appium-selector-expr}});

package/src/generators/test-generator/adapters/appium/templates/steps/gestures/pull-to-refresh-action.hbs

@@ -1,4 +1,7 @@
 await (async () => { const e = await {{> locator}};
+  // Fail loud on a missing target — an undefined elementId otherwise surfaces as the opaque
+  // server error "The swipe area coordinates must be provided if element is not set".
+  if (!e.elementId) { throw new Error('pull-to-refresh target not found: ' + {{> appium-selector-expr}}); }
   // Pull-to-refresh = drag the content down. Platform-native swipe per OS.
   if (driver.isIOS) { await driver.execute('mobile: swipe', { elementId: e.elementId, direction: 'down' }); }
   else { await driver.execute('mobile: swipeGesture', { elementId: e.elementId, direction: 'down', percent: 0.9, speed: 5000 }); }

package/src/generators/test-generator/adapters/appium/templates/steps/gestures/swipe-action.hbs

@@ -1,4 +1,7 @@
 await (async () => { const e = await {{> locator}};
+  // Fail loud on a missing target — an undefined elementId otherwise surfaces as the opaque
+  // server error "The swipe area coordinates must be provided if element is not set".
+  if (!e.elementId) { throw new Error('swipe target not found: ' + {{> appium-selector-expr}}); }
   // Platform-native swipe: XCUITest `mobile: swipe` (direction only) vs UiAutomator2 `mobile: swipeGesture`.
   if (driver.isIOS) { await driver.execute('mobile: swipe', { elementId: e.elementId, direction: '{{direction}}' }); }
   else { await driver.execute('mobile: swipeGesture', { elementId: e.elementId, direction: '{{direction}}', percent: 0.75 }); }

package/src/generators/test-generator/adapters/appium/templates/steps/partials/appium-selector.hbs

@@ -8,7 +8,13 @@
 {{~#case 'xpath'}}{{escapeQuotes value}}{{/case~}}
 {{~#case 'android-uiautomator'}}android={{escapeQuotes value}}{{/case~}}
 {{~#case 'ios-predicate'}}-ios predicate string:{{escapeQuotes value}}{{/case~}}
-{{~#case 'id'}}id={{escapeQuotes value}}{{/case~}}
+{{~!--
+  'id' — Appium's id strategy prepends `<appPackage>:id/` to any value WITHOUT a colon, so a bare
+  Compose testTagsAsResourceId value ("bottom_bar") silently never matches. Bare values therefore
+  compile to an exact UiSelector.resourceId match (Android); package-qualified classic View ids
+  ("com.foo:id/btn") keep the plain id strategy, which passes them through unchanged.
+--~}}
+{{~#case 'id'}}{{#if (includes value ':')}}id={{escapeQuotes value}}{{else}}android=new UiSelector().resourceId("{{escapeQuotes value}}"){{/if}}{{/case~}}
 {{~#case 'locator'}}{{escapeQuotes value}}{{/case~}}
 {{~#case 'css'}}{{escapeQuotes value}}{{/case~}}
 {{~#default}}~{{escapeQuotes value}}{{/default~}}