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

package/src/orchestrator/templates/ai-src/skills/sungen-gherkin-syntax/SKILL.md

@@ -257,7 +257,7 @@ Full config + catalog examples → **Advanced → Database** doc.
 
 ### Unsupported DB engine — fallback (ask, don't improvise)
 
-Direct SQL verification (`@query`, the Data Driver) covers these SQL engines: **`{postgres, sqlite, mysql}`** — plus the three native NoSQL engines above (Cosmos, MongoDB, DynamoDB). When a datasource's `engine` (or the DB the user describes) is **outside all of those** — e.g. Cassandra, Oracle, Neo4j, a proprietary store:
+Direct SQL verification (`@query`, the Data Driver) covers these SQL engines: **`{postgres, sqlite, device-sqlite, mysql}`** (`device-sqlite` = an ON-DEVICE app database on a mobile project — pulled fresh per query through the Appium session via `package:` + `db_path:`; debuggable build or emulator required) — plus the three native NoSQL engines above (Cosmos, MongoDB, DynamoDB). When a datasource's `engine` (or the DB the user describes) is **outside all of those** — e.g. Cassandra, Oracle, Neo4j, a proprietary store:
 
 1. **Do not** attempt a direct connect. **Do not** improvise a verification method.
 2. Present a fixed `AskUserQuestion` with exactly these 3 branches (always these, no others invented):
@@ -275,7 +275,7 @@ Direct SQL verification (`@query`, the Data Driver) covers these SQL engines: **
 Example:
 ```
 AskUserQuestion:
-  question: "This datasource's engine (cassandra) isn't a supported Data Driver engine ({postgres, sqlite, mysql} + Cosmos/MongoDB/DynamoDB) — direct connect isn't supported. How should DB state be verified?"
+  question: "This datasource's engine (cassandra) isn't a supported Data Driver engine ({postgres, sqlite, device-sqlite, mysql} + Cosmos/MongoDB/DynamoDB) — direct connect isn't supported. How should DB state be verified?"
   options:
     - "@api — verify via the project's internal API (Recommended: qa/api/ catalog found)"
     - "@manual — emit a @manual step + cqlsh check"
@@ -317,7 +317,13 @@ Every claim below is checked against a shipped `.hbs` under
 
 **Mobile-only `[mobile]`** — the gesture catalog (swipe, long-press, pinch-zoom, pull-to-refresh,
 rotate, background/foreground, notifications, grant-permission, clipboard set, set-geolocation,
-hide-keyboard, tap-top-of) has no web counterpart. Full syntax → `sungen-mobile-gestures`.
+hide-keyboard, tap-top-of) has no web counterpart, and neither do the lifecycle / device-state /
+timing steps (`restart the app`, `reinstall the app`, `turn airplane mode|wifi|mobile data on|off`,
+`turn device location on|off` — the latter two Android-only, throw on iOS — the window
+assertions `see [X] disappear within N seconds` / `still visible after N seconds`, and the
+device-oracle trio `open deep link {{url}}` · `see device log contains {{v}}` · `pass|fail
+biometric authentication` (biometric = emulator/Simulator only).
+Full syntax → `sungen-mobile-gestures`.
 
 **Divergences — compiles on both, means something different:**
 
@@ -328,7 +334,7 @@ hide-keyboard, tap-top-of) has no web counterpart. Full syntax → `sungen-mobil
 | `wait for [T] page` | waits for the URL | fixed `driver.pause(500)` settle — not a real wait condition |
 | `hover [T] icon \| row` | real hover | no-op — hover-revealed content is normally already visible on mobile; use `tap` |
 | `fill [T] alert with {{v}}` | fills native `prompt()` | no-op (comment only) — app-specific, handle manually |
-| `switch to [T] frame` | enters an `<iframe>` | switches a hybrid app's WebView context; no-op on a pure-native screen (no WebView found) |
+| `switch to [T] frame` | enters an `<iframe>` | switches a hybrid app's WebView context; no-op on a pure-native screen. **Needs `APPIUM_CHROMEDRIVER_AUTODOWNLOAD=1`** (.env.appium) or the switch fails with "No Chromedriver found". INSIDE the webview, selectors are **css/xpath only** — UiSelector-based types and the text-value asserts (`label with {{v}}`) don't apply there; assert element presence via css/xpath refs, then `switch to [main] frame` back |
 | `see [X] with {{v}}` (filtered visibility forms) | CSS `hasText` filter | hand-rolled substring match over `getText()`/`content-desc` (Android) or `label`/`value` (iOS) — same substring semantics, different attribute set |
 | `… is sorted …` / `… is loading` inside a filtered row/state check | reads `aria-sort`/`aria-busy` | **throws** — no native analog for these two states specifically (the plain, unfiltered `is loading` on a spinner still works on both) |
 | `scope: dialog` selector option | resolves inside the dialog | no effect (`SG-W021`) — steps resolve against the whole screen |

package/src/orchestrator/templates/ai-src/skills/sungen-mobile-gestures/SKILL.md

@@ -38,6 +38,29 @@ patterns (`click`, `hover`, `fill`) don't cover.
 >   requests it yet — there is currently no phrasing that compiles to an actual clipboard-read
 >   assertion. Don't author "see clipboard contains X" expecting it to compile; tag it `@manual` instead.
 > - **`set location to {{lat}}, {{lng}}`** → `driver.setGeoLocation(...)`.
+> - **`restart the app`** → kill → relaunch → content settle (same oracle as the per-scenario
+>   relaunch). THE step for persistence oracles: pinned card, dismissal survival, show-once tooltips.
+> - **`reinstall the app`** → remove → install from the session's build file → launch. **Requires
+>   the session to have installed via `APP_APK` / `IOS_APP`** (the `appium:app` cap) — attaching by
+>   package only makes the step fail loud with that exact fix in the message.
+> - **`turn airplane mode|wifi|mobile data on|off`** → `mobile: setConnectivity`. **Android-only** —
+>   XCUITest cannot toggle connectivity; on iOS the step throws loud. Keep such scenarios
+>   `@platform:android`. Do NOT author cleanup steps to restore connectivity "in case the test
+>   dies": the generated `wdio.conf.ts` restores the baseline (airplane off, wifi/data/location on)
+>   via adb in `onPrepare`/`onComplete`, healing even a run whose Appium session died mid-toggle (#615).
+> - **`turn device location on|off`** → `mobile: isGpsEnabled` + `mobile: toggleGps` (the execute
+>   aliases — WDIO v9 dropped the legacy wrappers), idempotent. **Android-only**, throws loud on iOS.
+> - **`see [X] disappear within N seconds`** → reverse `waitForDisplayed` with the step's deadline
+>   (+2s churn grace) — the auto-dismiss / expiry oracle (a 5s tooltip, a 60s barcode).
+> - **`see [X] still visible after N seconds`** → wait out the window, then the platform-aware
+>   visibility oracle — the "must NOT auto-dismiss / must stay valid" counterpart.
+> - **`open deep link {{url}}`** → `mobile: deepLink` (VIEW intent / XCUITest deepLink with the
+>   feature's app id) — THE entry for push-param / universal-link routing scenarios.
+> - **`see device log contains {{v}}`** → logcat (Android) / syslog (iOS) poll-accumulate ≤10s —
+>   makes SILENT failure modes and analytics events observable (they leave only a log line).
+> - **`pass|fail biometric authentication`** (face wording → iOS faceId) → **emulator/Simulator
+>   only**: Android `mobile: fingerprint` (finger 1 must be ENROLLED; fail = unenrolled id), iOS
+>   `mobile: sendBiometricMatch`. Real devices reject the command — the step fails loud.
 >
 > 📜 **`scroll to [X]` — two failure modes seen, with the real cause (measured):**
 > 1. *"Default scrollable element '//android.widget.ScrollView' not found"* — wdio's mobile scroll runs

package/src/orchestrator/templates/env.appium.example

@@ -23,3 +23,14 @@ JAVA_HOME=/opt/homebrew/opt/openjdk@21
 # IOS_UDID=<device-udid>             # REQUIRED — physical device (`xcrun xctrace list devices`), not a sim
 # IOS_BUNDLE_ID=<ios bundle id>      # REQUIRED — the iOS bundle (⚠ NOT the Android package)
 # IOS_TEAM_ID=<Apple Team ID>        # REQUIRED — 10-char id (Xcode → Settings → Accounts)
+
+# ════════════ Appium server security (opt-in) ════════════
+# Allow `mobile: shell` (raw adb passthrough) for device-level oracles (e.g. pulling an app's
+# SQLite DB via run-as). Starts the server with --allow-insecure=uiautomator2:adb_shell.
+# SECURITY: gives the session shell access — enable only on trusted local/dev machines,
+# never on shared CI runners you don't control.
+# APPIUM_ALLOW_ADB_SHELL=1
+
+# Hybrid WebView: auto-download the chromedriver matching the device's WebView (needed by
+# `switch to [X] frame` on hybrid screens). Downloads a binary at session start — opt-in.
+# APPIUM_CHROMEDRIVER_AUTODOWNLOAD=1

package/src/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/src/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/src/utils/selector-types.ts

@@ -20,6 +20,7 @@ export const 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`)
 ] as const;
 
 export type SelectorType = (typeof VALID_SELECTOR_TYPES)[number];