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

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/specs-regex-escape.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Sungen regex-escape helper — auto-generated into specs/regex-escape.ts. DO NOT EDIT.
+ *
+ * Test-data values are LITERAL TEXT. When a generated assertion needs an anchored
+ * match (`filter({ hasText: /^…$/ })`), the runtime value is interpolated into a
+ * `new RegExp(...)` — so a value containing `( [ $ . * +` would either throw a
+ * SyntaxError or silently match the wrong element unless it is escaped HERE, at
+ * runtime, where the real value is finally known. Template-time escaping cannot do
+ * this: at generate time the value is still a placeholder marker.
+ */
+/** Escape a runtime string so RegExp treats every character literally. */
+export declare function escapeRegExp(text: string): string;
+//# sourceMappingURL=specs-regex-escape.d.ts.map

package/dist/orchestrator/templates/specs-regex-escape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"specs-regex-escape.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-regex-escape.ts"],"names":[],"mappings":"AACA;;;;;;;;;GASG;AAEH,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD"}

package/dist/orchestrator/templates/specs-regex-escape.js

@@ -0,0 +1,19 @@
+"use strict";
+/* eslint-disable */
+/**
+ * Sungen regex-escape helper — auto-generated into specs/regex-escape.ts. DO NOT EDIT.
+ *
+ * Test-data values are LITERAL TEXT. When a generated assertion needs an anchored
+ * match (`filter({ hasText: /^…$/ })`), the runtime value is interpolated into a
+ * `new RegExp(...)` — so a value containing `( [ $ . * +` would either throw a
+ * SyntaxError or silently match the wrong element unless it is escaped HERE, at
+ * runtime, where the real value is finally known. Template-time escaping cannot do
+ * this: at generate time the value is still a placeholder marker.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeRegExp = escapeRegExp;
+/** Escape a runtime string so RegExp treats every character literally. */
+function escapeRegExp(text) {
+    return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=specs-regex-escape.js.map

package/dist/orchestrator/templates/specs-regex-escape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"specs-regex-escape.js","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-regex-escape.ts"],"names":[],"mappings":";AAAA,oBAAoB;AACpB;;;;;;;;;GASG;;AAGH,oCAEC;AAHD,0EAA0E;AAC1E,SAAgB,YAAY,CAAC,IAAY;IACvC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AAC7D,CAAC"}

package/dist/orchestrator/templates/specs-regex-escape.ts

@@ -0,0 +1,16 @@
+/* eslint-disable */
+/**
+ * Sungen regex-escape helper — auto-generated into specs/regex-escape.ts. DO NOT EDIT.
+ *
+ * Test-data values are LITERAL TEXT. When a generated assertion needs an anchored
+ * match (`filter({ hasText: /^…$/ })`), the runtime value is interpolated into a
+ * `new RegExp(...)` — so a value containing `( [ $ . * +` would either throw a
+ * SyntaxError or silently match the wrong element unless it is escaped HERE, at
+ * runtime, where the real value is finally known. Template-time escaping cannot do
+ * this: at generate time the value is still a placeholder marker.
+ */
+
+/** Escape a runtime string so RegExp treats every character literally. */
+export function escapeRegExp(text: string): string {
+  return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/orchestrator/templates/specs-test-data.ts

@@ -50,16 +50,42 @@ export class TestDataLoader {
     if (value === undefined || value === null) {
       throw new Error(`Test data key not found: ${key}`);
     }
-    // A projected array (e.g. `{{q.rows[*].name}}`) serializes as a JSON list so the full
-    // ordered set is preserved for the assert-compare — String([...]) would flatten it to a
-    // lossy comma-join that can't be distinguished from a scalar containing commas.
-    const result = Array.isArray(value)
-      ? this.interpolate(JSON.stringify(value))
+    // A projected array (e.g. `{{q.rows[*].name}}`) and a PLAIN object (an API response
+    // body) serialize as JSON text — String([...]) flattens to a lossy comma-join and
+    // String({}) is "[object Object]", both un-assertable. Embedded `{{ref}}`s interpolate
+    // INSIDE the value before stringify, so a ref carrying quotes/backslashes can never
+    // corrupt the serialized JSON (the old order substituted raw text into JSON text).
+    // Only PLAIN objects take this path: Date/Buffer/ObjectId values bound by @query from
+    // a real driver keep their String()/toString() output — JSON.stringify would wrap a
+    // Date in quotes and flip every assertion that already compares its string form.
+    const result = isJsonContainer(value)
+      ? JSON.stringify(this.interpolateDeep(value))
       : this.interpolate(String(value));
     assertNoUnresolvedEnvRef(key, result);
     return result;
   }
 
+  /**
+   * Interpolate `{{ref}}`s in every string leaf AND key of a JSON container,
+   * recursively (matching the old whole-JSON-text pass). Non-plain nested
+   * objects are passed through untouched — JSON.stringify serializes them via
+   * toJSON. A truly cyclic object throws a RangeError; every current bind
+   * source (JSON.parse output, DB rows, YAML after load-time resolution) is
+   * acyclic. Built with Object.fromEntries, which DEFINES data properties — a
+   * body field literally named "__proto__" survives instead of silently
+   * rewiring the result's prototype to external input.
+   */
+  private interpolateDeep(value: any): any {
+    if (typeof value === 'string') return this.interpolate(value);
+    if (Array.isArray(value)) return value.map((v) => this.interpolateDeep(v));
+    if (isPlainObject(value)) {
+      return Object.fromEntries(
+        Object.entries(value).map(([k, v]) => [this.interpolate(k), this.interpolateDeep(v)])
+      );
+    }
+    return value;
+  }
+
   /**
    * Resolve a key to its RAW, uncoerced value (array/object/number kept as-is) — for binding
    * DB query / API request params, where type-strict sinks (MySQL numeric columns, MongoDB,
@@ -68,7 +94,8 @@ export class TestDataLoader {
    * as get()), so an override like `token={{login.body.token}}` or `id={{prefix}}-001` still
    * interpolates — only the final scalar/array/object type is preserved uncoerced. Arrays and
    * objects are returned as-is; refs embedded inside their elements are not interpolated (unlike
-   * get()'s JSON-text pass), since raw() callers bind structured values directly, not text.
+   * get(), which interpolates every string leaf of a plain container before serializing), since
+   * raw() callers bind structured values directly, not text.
    * Throws on missing, mirroring get()'s guard.
    */
   raw(key: string): any {
@@ -202,6 +229,26 @@ export class TestDataLoader {
   }
 }
 
+/**
+ * A value get() must serialize as JSON: an array, or a PLAIN object (literal or
+ * null-prototype). Class instances at the TOP level (Date, Buffer, ObjectId…,
+ * and driver row wrappers like mysql2's RowDataPacket) are NOT containers —
+ * they keep the String()/toString() path their existing assertions rely on;
+ * nested inside a plain container they serialize through JSON.stringify/toJSON.
+ */
+function isJsonContainer(value: any): boolean {
+  return Array.isArray(value) || isPlainObject(value);
+}
+
+// Prototype check only — a `value.constructor === Object` probe is defeated by
+// a body FIELD literally named "constructor" (JSON.parse gives it as an own
+// property), which would silently fall back to "[object Object]" again.
+function isPlainObject(value: any): boolean {
+  if (value === null || typeof value !== 'object') return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
 function loadYamlSync(filePath: string): Record<string, any> | null {
   if (!fs.existsSync(filePath)) return null;
   const content = fs.readFileSync(filePath, 'utf-8');

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

@@ -178,6 +178,80 @@ 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).');
+}
+
+// Evidence readability: render a dot at every injected tap so screen recordings show WHERE the
+// test touched. Android-only (iOS has no supported equivalent). The pre-run value is remembered
+// and restored on onComplete, so a developer's own device setting is not permanently mutated.
+let showTouchesBefore: string | null = null;
+function setShowTouches(hook: 'onPrepare' | 'onComplete'): void {
+  if (!RUN_ANDROID) return;
+  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`;
+  const sh = (cmd: string) => execSync(`${adb} ${cmd}`, { timeout: 10000, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+  try {
+    if (hook === 'onPrepare') {
+      showTouchesBefore = sh('settings get system show_touches');
+      if (showTouchesBefore !== '1') sh('settings put system show_touches 1');
+    } else if (showTouchesBefore !== null && showTouchesBefore !== '1') {
+      sh(`settings put system show_touches ${showTouchesBefore === 'null' ? '0' : showTouchesBefore}`);
+    }
+  } catch { /* device gone / key absent — cosmetic feature, never block the run */ }
+}
+
 export const config: WebdriverIO.Config = {
   runner: 'local',
   tsConfigPath: './tsconfig.json',
@@ -192,7 +266,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 +
@@ -207,16 +284,24 @@ export const config: WebdriverIO.Config = {
             'appium:udid': process.env.ANDROID_UDID || '__ANDROID_UDID__',
             // APP_APK installs from a file (Appium reads pkg/activity from the manifest);
             // otherwise target an already-installed app by package + activity.
-            ...(APP_APK
-              ? { 'appium:app': APP_APK }
-              : {
-                  'appium:appPackage': APP_PACKAGE,
-                  // Omit when unset → UiAutomator2 launches the package's default launcher activity.
-                  ...(HAS_REAL_APP_ACTIVITY ? { 'appium:appActivity': APP_ACTIVITY } : {}),
-                }),
+            ...(APP_APK ? { 'appium:app': APP_APK } : {}),
+            // Explicit APP_PACKAGE/APP_ACTIVITY are passed even alongside APP_APK: the driver's
+            // APK-manifest parse can flake (empty activity → bare MAIN/LAUNCHER intent, which
+            // Android rejects as "matches multiple activities"), and explicit caps override it.
+            ...(process.env.APP_PACKAGE || !APP_APK ? { 'appium:appPackage': APP_PACKAGE } : {}),
+            // Omit when unset → UiAutomator2 launches the package's default launcher activity.
+            ...(HAS_REAL_APP_ACTIVITY ? { 'appium:appActivity': APP_ACTIVITY } : {}),
             '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 +360,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 +392,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'); setShowTouches('onPrepare'); },
+  onComplete: () => { restoreConnectivity('onComplete'); setShowTouches('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.25",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -12,6 +12,7 @@
     "copy-templates": "mkdir -p dist/generators/test-generator/adapters/playwright/templates/steps && mkdir -p dist/generators/test-generator/templates && mkdir -p dist/orchestrator/templates && mkdir -p dist/dashboard/templates && cp -r src/generators/test-generator/adapters/playwright/templates/*.hbs dist/generators/test-generator/adapters/playwright/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/playwright/templates/steps dist/generators/test-generator/adapters/playwright/templates/ && mkdir -p dist/generators/test-generator/adapters/appium/templates/steps && cp -r src/generators/test-generator/adapters/appium/templates/*.hbs dist/generators/test-generator/adapters/appium/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/appium/templates/steps dist/generators/test-generator/adapters/appium/templates/ && cp src/generators/test-generator/templates/*.hbs dist/generators/test-generator/templates/ 2>/dev/null || true && cp -r src/orchestrator/templates/* dist/orchestrator/templates/ && cp src/dashboard/templates/index.html dist/dashboard/templates/index.html && mkdir -p dist/harness/catalog && cp src/harness/catalog/*.yaml dist/harness/catalog/",
     "build:dashboard": "cd ../../dashboard && npm install --silent && npm run build && cd - && cp ../../dashboard/dist/index.html src/dashboard/templates/index.html",
     "dev": "tsx src/cli/index.ts",
+    "gen:step-matrix": "tsx tools/step-support-matrix/index.ts",
     "test": "tsx tests/run-all.ts",
     "test:update": "tsx tests/golden/run.ts --update && tsx tests/audit/run.ts --update && tsx tests/ingest/run.ts --update",
     "prepublishOnly": "npm run build:dashboard && npm run build"
@@ -39,8 +40,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.25",
+    "@sungen/driver-ui": "3.2.25",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",
@@ -66,9 +67,10 @@
     "LICENSE"
   ],
   "devDependencies": {
-    "mysql2": "^3",
-    "mongodb": "^7",
     "@aws-sdk/client-dynamodb": "^3",
-    "@aws-sdk/lib-dynamodb": "^3"
+    "@aws-sdk/lib-dynamodb": "^3",
+    "fast-xml-parser": "^5.3.3",
+    "mongodb": "^7",
+    "mysql2": "^3"
   }
 }

package/src/capabilities/context-router.ts

@@ -46,11 +46,19 @@ class ContextRouter {
    */
   capabilitiesFor(tags: string[] = [], platform?: string): string[] {
     const ids = new Set<string>();
-    const def = capabilityRegistry.defaultCapabilityId();
-    if (def) ids.add(def);
-    // A platform capability (mobile/native/…) is activated by the project's platform, not by a tag.
-    // `web` has no capability of its own → falls through to the default `ui` (byte-identical).
-    if (platform && capabilityRegistry.get(platform)) ids.add(platform);
+    // A platform capability (mobile/native/…) is activated by the project's platform, not by a tag,
+    // and it REPLACES the default rather than stacking on it. The default `ui` exists because `web`
+    // has no capability of its own; when a real platform capability is active, its gate is the one
+    // that applies. Adding both meant a mobile project ran `ui-viewpoint` AND `mobile-viewpoint` —
+    // two sensors emitting the same UNIVERSAL finding, so every mobile audit printed it twice while
+    // web printed it once (#626). Scoring already resolved this the same way
+    // (`scoringCapabilityFor` prefers the platform over the default).
+    const platformCap = platform && capabilityRegistry.get(platform) ? platform : undefined;
+    if (platformCap) ids.add(platformCap);
+    else {
+      const def = capabilityRegistry.defaultCapabilityId();
+      if (def) ids.add(def);
+    }
     for (const cap of capabilityRegistry.all()) {
       if ((cap.annotations ?? []).some((a) => tags.includes(a))) ids.add(cap.id);
     }

package/src/cli/commands/capability.ts

@@ -9,43 +9,9 @@ import {
 import { buildPlan, MANUAL_REASONS } from '../../harness/capability-plan';
 import { adapterRegistry } from '../../generators/test-generator/adapters';
 import { emitMobileRuntime, installMobileDriver } from '../../orchestrator/mobile-runtime-scaffolder';
+import { coreVersion, resolveDriverVersion } from '../../orchestrator/lockstep-version';
 import { findUnitDir, resolveUnit } from '../resolve-unit';
 
-/** The running CLI's (core) version — opt-in drivers install in lockstep with it (not `@latest`). */
-function coreVersion(): string {
-  try { return require('../../../package.json').version || 'latest'; } catch { return 'latest'; }
-}
-
-/**
- * Resolve the driver version to install for the running core `core`.
- *
- * Lockstep wants the EXACT `core` version. But the beta channel publishes `<core>-beta.N` before a
- * stable `<core>` ever exists — so a released core (e.g. 3.2.10) asking for `@3.2.10` hits ETARGET
- * out-of-the-box when npm only has `3.2.10-beta.2` (`sungen capability add` then fails for a fresh
- * user). Fall back on the SAME version line: prefer exact `core`, else the highest `core-beta.N`,
- * else the `beta` dist-tag as a last resort. Keeps the driver's pinned core-dep on the same line.
- */
-function resolveDriverVersion(pkg: string, core: string): string {
-  if (core === 'latest') return 'beta';
-  try {
-    const out = spawnSync('npm', ['view', pkg, 'versions', '--json'], { encoding: 'utf-8', shell: true });
-    if (out.status !== 0 || !out.stdout) return core; // can't query → let the exact install try/fail
-    let versions: string[] = [];
-    const parsed = JSON.parse(out.stdout);
-    versions = Array.isArray(parsed) ? parsed : [parsed];
-    if (versions.includes(core)) return core; // exact exists → lockstep
-    const prefix = `${core}-beta.`;
-    const betas = versions
-      .filter((v) => typeof v === 'string' && v.startsWith(prefix))
-      .map((v) => parseInt(v.slice(prefix.length), 10))
-      .filter((n) => Number.isInteger(n));
-    if (betas.length) return `${core}-beta.${Math.max(...betas)}`; // highest same-line prerelease
-    return 'beta'; // nothing on this line → newest beta dist-tag
-  } catch {
-    return core;
-  }
-}
-
 /**
  * Add `test:mobile` to the project's package.json scripts (if absent).
  * Idempotent — skips if the script is already set.
@@ -140,7 +106,7 @@ export function registerCapabilityCommand(program: Command): void {
         const resolved = resolveUnit(o.screen);
         if (!resolved) throw new Error(`Screen/flow not found: qa/screens/${o.screen} or qa/flows/${o.screen}`);
         // The catalog unit id carries the unit KIND, which gates which drivers can serve it.
-        const plan = buildPlan(resolved.dir, o.screen, resolved.unitId);
+        const plan = buildPlan(resolved.dir, o.screen, resolved.unitId, readCapabilities(process.cwd()).platform);
 
         const outDir = path.join(process.cwd(), '.sungen', 'reports');
         fs.mkdirSync(outDir, { recursive: true });
@@ -166,9 +132,9 @@ export function registerCapabilityCommand(program: Command): void {
           }
         }
         if (plan.unavailable.length) {
-          L('  Cannot help here (driver does not support this unit kind — do NOT install):');
+          L('  Cannot help here (driver cannot serve this unit kind or platform — do NOT install):');
           for (const r of plan.unavailable) {
-            L(`     • ${r.count} @manual:${r.reason} → \`${r.driver}\` has no ${r.unitKind} support; automate the behaviour on the owning SCREEN unit instead`);
+            L(`     • ${r.count} @manual:${r.reason} → \`${r.driver}\` ${r.why}`);
           }
         }
         if (plan.keep.length) {