@sungen/driver-mobile 3.2.28 → 3.2.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-mobile",
-  "version": "3.2.28",
+  "version": "3.2.29",
   "description": "Sungen mobile platform driver (Appium / WebdriverIO) — gesture vocabulary, mobile selector strategies, viewpoint gate, and the WDIO runner. Plugs into @sun-asterisk/sungen via the capability SPI.",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -13,11 +13,12 @@
   "author": "eqe team (engineer & quality) — Sun Asterisk",
   "license": "MIT",
   "dependencies": {
-    "@sun-asterisk/sungen": "3.2.28",
+    "@sun-asterisk/sungen": "3.2.29",
     "@wdio/appium-service": "^9.0.0",
     "@wdio/cli": "^9.0.0",
     "@wdio/local-runner": "^9.0.0",
     "@wdio/mocha-framework": "^9.0.0",
+    "@wdio/reporter": "^9.0.0",
     "@wdio/spec-reporter": "^9.0.0",
     "appium": "^3.0.0",
     "webdriverio": "^9.0.0"

package/src/index.ts

@@ -41,6 +41,7 @@ import { lifecyclePatterns } from './patterns/lifecycle-patterns';
 import { devicePatterns } from './patterns/device-patterns';
 import { timingPatterns } from './patterns/timing-patterns';
 import { logPatterns } from './patterns/log-patterns';
+import { mobileRepair } from './mobile-repair';
 
 /** Surfaces universal-viewpoint theme gaps (low-priority reminder; does not move the score). */
 const mobileViewpointGateSensor: Sensor<GateInput> = {
@@ -88,6 +89,10 @@ export function register(registry: CapabilityRegistry): void {
     // resolved @sun-asterisk/sungen copy, which npm can nest at an older published version whose
     // catalog predates `mobile-home` → stale-catalog version-skew. See the module header.
     sensors: [mobileViewpointGateSensor],
+    // MOB-4 harness parity: the fix catalog `sungen repair` consults for a mobile unit. Its rules
+    // key on what the audit sensors and the Appium runtime actually emit — never on the SG-W02x
+    // codes, which are console-only and never reach either channel. See mobile-repair.ts.
+    repair: mobileRepair,
   });
 }
 

package/src/mobile-repair.ts

@@ -0,0 +1,126 @@
+/**
+ * Mobile repair catalog (MOB-4 / CG-9) — the `mobile` capability's deterministic fix rules.
+ *
+ * `sungen repair --screen <unit>` on a `platform: mobile` project matches each audit finding and
+ * each Playwright-reported failure against these rules and proposes the concrete fix. Same shape as
+ * `driver-api`'s `apiRepair` (#343): capability-owned DATA, so audit + runtime signals compose into
+ * one plan. Type-only dependency on core.
+ *
+ * WHAT THESE RULES MATCH, AND WHY IT IS NOT `SG-W02x`.
+ * The mobile compile diagnostics are the obvious thing to key on, and they cannot be used:
+ *   · they are console-only — `sungen generate` prints them and keeps nothing, so they never enter
+ *     `.sungen/reports/<unit>-audit.json`, which is the only audit input `planRepair` reads;
+ *   · the loud ones DO reach a test-result, but through `unsupportedStepCode(reason)`, which
+ *     prefixes `[sungen]` and embeds the diagnostic's REASON PROSE — never the code itself.
+ * So a `/SG-W023/` rule would be a rule that can never fire, which is worse than no rule: it
+ * inflates `rulesAvailable` while the finding still sits in `unmatched`. The audit half below keys
+ * on what the audit sensors emit; the runtime half keys on the reason text that actually arrives.
+ * The purely silent diagnostics (SG-W021/W022/W023/W026 emit no code and no runtime failure) have
+ * no signal to match at all — they are review-time concerns, and `sungen-tc-review`'s A8 gate owns
+ * them.
+ *
+ * EVERY RULE CARRIES A VERBATIM `example`, and `tests/harness/mobile-repair-plan.run.ts` asserts
+ * that each rule matches its own example and that no earlier rule steals it. That is what keeps a
+ * reworded emitter from silently retiring a rule, and a broad regex from swallowing its neighbours.
+ * Ids are stable — reports quote them.
+ */
+import type { RepairProvider, RepairRule } from '@sun-asterisk/sungen';
+
+/** A rule plus the real message it was written against (the test's reachability oracle). */
+export interface MobileRepairRule extends RepairRule {
+  /** Verbatim from the emitter — an audit sensor, a diagnostic reason, or an appium template. */
+  example: string;
+}
+
+/**
+ * Order is significant: `planRepair` takes the FIRST matching rule. Compile-time causes come before
+ * runtime infrastructure, which comes before element-level symptoms — a step that could not be
+ * compiled honestly is a better explanation than the missing element it also produces.
+ */
+export const mobileRepairRules: MobileRepairRule[] = [
+  // ── Audit findings (`.sungen/reports/<unit>-audit.json`) ────────────────────────────────────
+  { id: 'mobile-universal-theme', match: /^UNIVERSAL: missing theme/,
+    example: 'UNIVERSAL: missing theme(s): app-lifecycle-resume, permission-prompt (low priority reminder).',
+    fix: 'Unscored mobile-universal theme(s) have no scenario. Each has a compiling step: app-lifecycle-resume → `User background the app for 5 seconds` then assert the screen state survived; orientation-stability → `User rotate the device to landscape`; connectivity-degraded → `User turn on airplane mode` (Android — tag `@platform:android`); permission-prompt → `User deny [Camera] permission`; gesture-reachability → `User scroll to [X]` / `User tap top of [X]`; deep-link-entry → `User open the deep link {{url}}`. Pick from the Group F tables in `sungen-viewpoint`.' },
+
+  { id: 'mobile-gate-theme-uncovered', match: /^GATE: critical theme .* has NO covering scenario/,
+    example: 'GATE: critical theme "keyboard-overlap" for page-type "mobile-form" has NO covering scenario → generate it (often cross-screen → consider add-flow).',
+    fix: 'A critical theme of this `mobile-*` page-type is unclaimed. Write the scenario from the matching Group F pattern in `sungen-viewpoint` (mobile-form → 21 Native Picker / 30 Soft-Keyboard Overlap; mobile-list → 20 Swipe-to-Delete Row / 29 Pull-to-Refresh List; mobile-settings → 31 Settings Toggle List), then re-run `sungen audit`. Do NOT answer it with `Then User see [X] page` — that emits nothing on Appium (SG-W022) and would pass having proven nothing.' },
+
+  { id: 'mobile-gate-theme-shallow', match: /^GATE: critical theme .* covered only by SHALLOW/,
+    example: 'GATE: critical theme "list-data" is covered only by SHALLOW scenarios (no data assertion) → deepen with `... with {{value}}` / `table ... with {{value}}` (count @manual cross-screen too).',
+    fix: 'The theme is named but nothing reads a value. Deepen the scenario with a data oracle: `Then User see [Row Title] contains {{expected}}` / `... has text {{expected}}`, or a survival oracle across a lifecycle step (`User restart the app`, then assert the value). The one exception is `keyboard-overlap`, whose oracle is a SIGHTING (`User see [Submit] button` while the keyboard is up) — a data assertion there proves nothing extra.' },
+
+  { id: 'mobile-gesture-substituted', match: /^VIEWPOINT-GESTURE-SUBSTITUTED/,
+    example: 'VIEWPOINT-GESTURE-SUBSTITUTED: the viewpoint asks for "the OS/hardware back gesture" ("Returning by hardware back keeps the draft…") but the suite exercises an in-app control instead.',
+    fix: 'On mobile all three substituted gestures now have real steps, so `@manual` is no longer the honest answer: the OS/hardware back → `When User go back` (Android KEYCODE_BACK, iOS WDA navigation-back — NOT `tap [Back]`, which runs the screen\'s own handler); backgrounding and resuming → `When User background the app for 5 seconds`; rotation → `When User rotate the device to landscape`. Swap the in-app control for the gesture the viewpoint asked for.' },
+
+  { id: 'mobile-manual-uncoded', match: /^MANUAL-CODE-MISSING/,
+    example: 'MANUAL-CODE-MISSING: 7 @manual tag(s) carry no reason code — tag @manual:M1-M11 (M5 = external dependency e.g. inbox, M3 = mock/network, M7 = environment, M10 = device/OS capability, M11 = real-device only) so the capability planner can route what a driver would automate.',
+    fix: 'Code each `@manual` so the capability planner can route it. On mobile the two that matter are `@manual:M10` (device/OS capability — process death, a real push notification, the iOS permission dialog) and `@manual:M11` (real-device only — biometrics and fingerprint, which emulator-only commands cannot stand in for). Before tagging, confirm no step already exists: airplane mode, GPS toggle, deep links, clipboard, `go back`, rotate and background all compile now.' },
+
+  { id: 'mobile-page-type-undetermined', match: /^PAGE-TYPE-UNDETERMINED/,
+    example: 'PAGE-TYPE-UNDETERMINED: no page type fits this screen with enough confidence (best 0 keyword hit(s)), so NO critical themes were demanded and the coverage axis is excluded from the score — declare it in test-viewpoint.md (`page-type: <id>`) to have the theme checklist applied.',
+    fix: 'Declare the page type in `requirements/test-viewpoint.md` as `page-type: <id>`, choosing a MOBILE id — `mobile-home`, `mobile-list`, `mobile-detail`, `mobile-form`, `mobile-auth` or `mobile-settings`. Until it is declared the coverage axis is excluded, so the unit is unmeasured rather than passing; a web id (`form`, `list`) would demand the wrong themes.' },
+
+  // ── Runtime: a step sungen refused to compile honestly, surfacing as a loud throw ────────────
+  { id: 'mobile-web-only-step', match: /\[sungen\][^\n]*?(?:\bweb-only\b|not supported on the appium adapter|no native-mobile equivalent|adapter cannot express it)/,
+    example: '[sungen] table/column steps target HTML table roles and are not supported on the appium adapter. Use list / accessibility-id assertions, or tag this scenario @manual.',
+    fix: 'A web-only step form reached the Appium adapter (reported at compile time as SG-W020/SG-E020) and throws by design rather than passing silently. Swap in the native equivalent: a table/column assertion → per-element `[Row N Title]` accessibility-id assertions; a URL/route assertion → a screen marker (`Then User see [Header Title] is visible`); tab-order or `sorted` → read the element texts and compare, or `@manual:M10`.' },
+
+  { id: 'mobile-step-unmatched', match: /\[sungen\] step "[^"]*" matched no pattern/,
+    example: '[sungen] step "User pinches the map twice" matched no pattern — sungen has no step form for it. Rephrase using a supported step form (see the sungen-gherkin-syntax reference), or tag the scenario @manual.',
+    fix: 'The sentence is outside the vocabulary (SG-W001), so it throws instead of quietly asserting nothing. Rephrase from the mobile catalogue in `sungen-mobile-gestures` (tap / double tap / long press / swipe / pinch / scroll to / tap top of / pull to refresh / go back / rotate / background / restart / reinstall / deep link / clipboard / permission / airplane mode), or tag the scenario `@manual:M10` with the reason.' },
+
+  { id: 'mobile-lifecycle-no-app-id', match: /needs the app id: the mobile lifecycle steps resolve the target app from the feature/,
+    example: "restart the app needs the app id: the mobile lifecycle steps resolve the target app from the feature's Path, and this feature declares none, so the generated helper would be missing and the whole spec would fail at runtime.",
+    fix: 'Declare the app id on the Feature line so `__resolveAppId()` is emitted: `Path: com.example.app/.MainActivity | com.example.app`. For a mobile unit `--path` carries the APP ID and `--reach` carries the navigation recipe — a unit scaffolded with the route in `--path` produces exactly this (SG-E024), and without the line the whole spec dies in a before hook, not just the step.' },
+
+  { id: 'mobile-ios-unsupported-step', match: /This feature declares @platform:ios/,
+    example: 'step "User turn on airplane mode" compiles to `connectivity-action`, which does nothing on iOS — it is guarded out with no error, so the step would run and the scenario would PASS having done nothing. This feature declares @platform:ios.',
+    fix: 'The step has no iOS implementation and the feature pins iOS (SG-E025). Either move the scenario to an `@platform:android` feature — connectivity, the GPS toggle and the offline banner are Android-only at runtime — or drop the step and tag the scenario `@manual:M10`. The per-OS columns in `docs/spec/step-support-matrix.md` say which OS serves each template.' },
+
+  // ── Runtime: the Appium session / driver layer ───────────────────────────────────────────────
+  { id: 'mobile-session-not-created', match: /A new session could not be created/,
+    example: 'A new session could not be created. Details: The requested application does not appear to be installed on the device (com.example.app)',
+    fix: 'The Appium session never started, so nothing in the suite ran. Reconcile the capabilities in `.env.appium` / `wdio.conf.ts` with the device: `appium:appPackage` + `appium:appActivity` (or `appium:app` pointing at an installed build), `appium:platformVersion` against `adb shell getprop ro.build.version.release`, and `appium:deviceName`/`appium:udid` against `adb devices`. Install the build first if the details name a missing package.' },
+
+  { id: 'mobile-driver-proxy-lost', match: /Could not proxy command to (?:the )?remote server|socket hang up|ECONNRESET/,
+    example: 'Could not proxy command to the remote server. Original error: socket hang up',
+    fix: 'The device-side driver (UiAutomator2 server / WebDriverAgent) died mid-run, so every later step in the file fails for one cause. Raise `appium:newCommandTimeout` (the 60s default kills the session during a long pause), keep the device awake and unlocked, and read the Appium server log for the crash. If it recurs at the same step, that step is crashing the app — capture the failure evidence for it instead of retrying the suite.' },
+
+  { id: 'mobile-instrumentation-failed', match: /instrumentation process (?:cannot|could not) be (?:initialized|started)|Cannot start the instrumentation process/,
+    example: "Cannot start the 'com.example.app' application. Original error: The instrumentation process cannot be initialized",
+    fix: 'The UiAutomator2 instrumentation could not attach. Uninstall its two helper packages and let Appium reinstall them: `adb uninstall io.appium.uiautomator2.server` and `adb uninstall io.appium.uiautomator2.server.test`. If it persists, the build under test is signed with a different key than the installed copy — uninstall the app itself and reinstall the exact APK the run points at.' },
+
+  { id: 'mobile-chromedriver-mismatch', match: /No Chromedriver found|chromedriver.*(?:version|mismatch)|Chrome version must be/i,
+    example: "No Chromedriver found that can automate Chrome '112.0.5615'. See the appium chromedriver documentation.",
+    fix: 'A WebView step needs a Chromedriver matching the device\'s System WebView. Set `appium:chromedriverAutodownload: true` in the capabilities, or pin `appium:chromedriverExecutableDir` to a directory holding the right build. If this unit is a native screen that only crossed a WebView by accident, assert the native markers instead so the run never enters WEBVIEW context.' },
+
+  // ── Runtime: element-level symptoms (both measured on a real device) ─────────────────────────
+  { id: 'mobile-scroll-no-scrollable', match: /Default scrollable element .* not found/,
+    example: "Default scrollable element '//android.widget.ScrollView' not found",
+    fix: 'MEASURED: wdio\'s mobile scroll runs `$$(\'//android.widget.ScrollView\')` and throws when 0 match — that node exists on a list/Home screen but not on every screen, so this is STATE-dependent, not "the screen cannot scroll". Assert the app is on the scrollable screen before scrolling; on Flutter/Compose (no native ScrollView) or a screen whose content fits, drop the scroll entirely. For an element merely hidden behind a floating bottom nav use `When User tap top of [X]` — scroll cannot fix occlusion, because `.scrollIntoView()` is a NO-OP once the target is inside the viewport.' },
+
+  { id: 'mobile-tap-intercepted', match: /element click intercepted|is not clickable at point|element is obscured/i,
+    example: 'element click intercepted: Element <button id="submit"> is not clickable at point (540, 1830). Other element would receive the click: <div class="bottom-nav">',
+    fix: 'Another element owns that point — on mobile almost always a floating bottom nav or a sticky footer sitting over it. Use `When User tap top of [X]`, which taps a visible point of the element rather than its centre. Do NOT reach for `scroll to [X]`: it was measured to be a NO-OP here (element bounds identical before and after), because scrollIntoView has no concept of z-order occlusion.' },
+
+  { id: 'mobile-element-absent', match: /no such element|Element not found:|An element could not be located/,
+    example: 'Element not found: ~submit-button',
+    fix: 'The locator resolved to nothing. Regenerate the key from the live screen with `/sungen:run-test` (the `sungen-selector-fix` skill reads the page source), preferring `accessibility-id` — an XPath over the native tree breaks on the first layout change. If the element only appears after a gesture, add the step that reveals it (`scroll to` / `tap`), since `__ensureVisible` scrolls but does not navigate.' },
+
+  { id: 'mobile-ios-offscreen', match: /iOS geometry oracle: rect=/,
+    example: 'Expect "~photo-view" to be displayed — iOS geometry oracle: rect={"x":0,"y":0,"width":0,"height":0} is not on screen (0x0 = not rendered / scrolled out)',
+    fix: 'On iOS the element EXISTS in the tree but occupies no on-screen rectangle — 0x0 means not rendered yet, and non-zero-but-off-screen means scrolled out. Add the step that brings it on screen (`When User scroll to [X]`) or an explicit settle before the assertion; if the screen renders it lazily behind a fetch, assert a loading marker disappears first so the oracle runs against the settled screen.' },
+
+  { id: 'mobile-auth-session', match: /@auth:\w+ (?:requires|login rejected|login did not complete|could not decide the login state|login failed)/,
+    example: '@auth:admin login did not complete (still on the login screen) — check loginSteps in qa/screens/login/test-data/login.yaml.',
+    fix: 'The mobile `@auth:<role>` bootstrap could not reach a logged-in state, so the scenario never got to its own subject. Complete the four parts it needs in the role\'s test-data: `loginSteps`, `credentials.email` / `credentials.password`, an `authedMarker` that only the signed-in screen renders, and a `loggedOutMarker`. A marker both screens render is the usual cause of "could not decide the login state".' },
+
+  { id: 'mobile-device-log-silent', match: /device log \([^)]+\) did not contain/,
+    example: 'device log (logcat) did not contain "checkout_completed" within 10s',
+    fix: 'The log oracle polled for 10s and never saw the line — a real finding when the step is the oracle for a SILENT behaviour (an analytics event, a swallowed error). Confirm the needle against a manual run\'s `adb logcat` output before treating it as a test defect: a wrong log type (`logcat` vs `syslog`) or a substring the app formats differently is the other half of the cases, and both look identical from here.' },
+];
+
+export const mobileRepair: RepairProvider = { rules: mobileRepairRules };

package/src/patterns/device-patterns.ts

@@ -20,6 +20,9 @@ export const devicePatterns: StepPattern[] = [
     // Keyed on the device noun + turn/enable/disable so it never collides with UI toggles
     // (`tap [Wifi Switch]` carries a selectorRef and a tap verb).
     name: 'set-connectivity',
+    platforms: ['mobile'],
+    platformAlternative:
+      'a browser cannot toggle the device radio — intercept the network in the Playwright config (or `@mock`) to test offline behaviour, or tag the scenario @manual',
     matcher: (step) =>
       /\b(airplane(?:\s+mode)?|wi-?fi|mobile\s+data)\b/i.test(step.text) &&
       /\b(turn(s)?|enable(s)?|disable(s)?|switch(es)?)\b/i.test(step.text) &&
@@ -42,6 +45,9 @@ export const devicePatterns: StepPattern[] = [
     // `User turn device location on|off` / `User disable location services`. Distinct from
     // `set-geolocation` (set/mock/simulate coordinates) — this toggles the SERVICE.
     name: 'location-services',
+    platforms: ['mobile'],
+    platformAlternative:
+      'a browser has no GPS switch — set/clear geolocation on the Playwright context, or tag the scenario @manual',
     matcher: (step) =>
       /\b(device\s+location|location\s+services?)\b/i.test(step.text) &&
       /\b(turn(s)?|enable(s)?|disable(s)?|switch(es)?)\b/i.test(step.text) &&
@@ -56,6 +62,9 @@ export const devicePatterns: StepPattern[] = [
     // `User pass|fail biometric authentication` — simulated biometric input on emulator/simulator
     // (#603). Face wording (`face id`) selects the iOS faceId type; Android is fingerprint-only.
     name: 'biometric-auth',
+    platforms: ['mobile'],
+    platformAlternative:
+      'a browser has no biometric prompt (WebAuthn is a different mechanism) — tag the scenario @manual',
     matcher: (step) =>
       /\b(biometric|fingerprint|face\s?id|touch\s?id)\b/i.test(step.text) &&
       /\b(pass(es)?|fail(s)?|match(es)?|reject(s)?)\b/i.test(step.text) &&

package/src/patterns/gesture-patterns.ts

@@ -68,6 +68,9 @@ export const gesturePatterns: StepPattern[] = [
   // --- gestures ---
   {
     name: 'swipe-element',
+    platforms: ['mobile'],
+    platformAlternative:
+      'a browser has no swipe — drive the control the swipe reveals (`User click [X]`), or tag the scenario @manual',
     matcher: (step) => /\bswipe(s)?\b/i.test(step.text) && !!step.selectorRef,
     resolver: (step, context) => {
       const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, context.featureName, step.elementType, step.nth);
@@ -78,6 +81,9 @@ export const gesturePatterns: StepPattern[] = [
   },
   {
     name: 'long-press-element',
+    platforms: ['mobile'],
+    platformAlternative:
+      'a browser has no long press — drive the control the long press reveals, or tag the scenario @manual',
     matcher: (step) => /\blong[-\s]?press(es)?\b/i.test(step.text) && !!step.selectorRef,
     resolver: (step, context) => {
       const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, context.featureName, step.elementType, step.nth);
@@ -89,6 +95,9 @@ export const gesturePatterns: StepPattern[] = [
   },
   {
     name: 'pull-to-refresh',
+    platforms: ['mobile'],
+    platformAlternative:
+      'a browser has no pull-to-refresh — re-enter the page with `User is on [X] page`, or tag the scenario @manual',
     matcher: (step) => /\bpull[-\s]?to[-\s]?refresh\b/i.test(step.text) && !!step.selectorRef,
     resolver: (step, context) => {
       const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, context.featureName, step.elementType, step.nth);
@@ -98,6 +107,9 @@ export const gesturePatterns: StepPattern[] = [
   },
   {
     name: 'pinch-zoom',
+    platforms: ['mobile'],
+    platformAlternative:
+      'a browser has no pinch — set the viewport/zoom in the Playwright config, or tag the scenario @manual',
     matcher: (step) => /\bpinch[-\s]?zoom\b/i.test(step.text) && !!step.selectorRef,
     resolver: (step, context) => {
       const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, context.featureName, step.elementType, step.nth);
@@ -108,6 +120,9 @@ export const gesturePatterns: StepPattern[] = [
   },
   {
     name: 'tap-top-of-element',
+    platforms: ['mobile'],
+    platformAlternative:
+      'a browser click already lands on a visible point — use `User click [X]`',
     matcher: (step) => /\btap(s)?\b/i.test(step.text) && /\b(top of|at the top|at top)\b/i.test(step.text) && !!step.selectorRef,
     resolver: (step, context) => {
       const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, context.featureName, step.elementType, step.nth);
@@ -117,6 +132,9 @@ export const gesturePatterns: StepPattern[] = [
   },
   {
     name: 'dismiss-if-present',
+    platforms: ['mobile'],
+    platformAlternative:
+      'there is no OS dialog on web — close the in-app dialog with its own control (`User click [Close] button`)',
     matcher: (step) => /\bdismiss(es)?\b/i.test(step.text) && !!step.selectorRef && step.elementType !== 'alert',
     resolver: (step, context) => {
       const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, context.featureName, step.elementType, step.nth);
@@ -126,6 +144,9 @@ export const gesturePatterns: StepPattern[] = [
   },
   {
     name: 'rotate-device',
+    platforms: ['mobile'],
+    platformAlternative:
+      'a browser has no orientation — set the viewport size in the Playwright config for the responsive check',
     matcher: (step) => /\brotate\b/i.test(step.text) && /\b(landscape|portrait)\b/i.test(step.text) && !step.selectorRef,
     resolver: (step) => {
       const orientation = /\blandscape\b/i.test(step.text) ? 'LANDSCAPE' : 'PORTRAIT';
@@ -133,8 +154,42 @@ export const gesturePatterns: StepPattern[] = [
     },
     priority: 16,
   },
+  {
+    // The OS/hardware back, deliberately distinct from tapping an in-app Back control. The two are
+    // different behaviours — Android's system back skips the screen's own handler unless the app
+    // wires it — and `viewpoint-ledger` already refuses the second as an answer to the first. Before
+    // this pattern the ledger asked a question the vocabulary could not answer, so the only reply
+    // was @manual.
+    //
+    // What separates `tap [Back] button` from this pattern is REF MASKING, not `!selectorRef`:
+    // matchers see `[~]`, so the word "back" is not in the text they read. Mutation testing proved
+    // it — dropping `!selectorRef` broke nothing, because masking had already done that job. The
+    // guard's real and only job is `User go back to [List] screen`: verb AND ref, where a match
+    // would silently DISCARD the named screen. That is the case the test now covers.
+    //
+    // Every phrasing the ledger's theme regex recognises is accepted here on purpose; a phrasing it
+    // matches but the vocabulary rejects would re-open the same dead end one word over. `tap the back
+    // button` is NOT accepted: with no ref it is far more likely an in-app control the author forgot
+    // to bracket, and reading it as the OS gesture would change the meaning of their test silently.
+    name: 'os-back',
+    platforms: ['mobile'],
+    platformAlternative: 'a browser has no OS back — use `User is on [X] page` to re-enter the screen, or tag the scenario @manual',
+    matcher: (step) =>
+      !step.selectorRef && (
+        /\bgo(es)?\s+back\b/i.test(step.text) ||
+        /\bpress(es)?\s+(?:the\s+)?back\s+button\b/i.test(step.text) ||
+        /\b(?:hardware|system|os|device|android|physical)[-\s]?back\b/i.test(step.text) ||
+        /\bback\s+gesture\b/i.test(step.text) ||
+        /\bswipe[-\s]?back\b/i.test(step.text)
+      ),
+    resolver: () => ({ templateName: 'go-back-action', data: {}, comment: 'OS/hardware back' }),
+    priority: 16,
+  },
   {
     name: 'background-app',
+    platforms: ['mobile'],
+    platformAlternative:
+      'a browser tab has no background/resume — re-enter with `User is on [X] page` to test re-hydration, or tag the scenario @manual',
     matcher: (step) => /\bbackground\b/i.test(step.text) && /\bapp\b/i.test(step.text) && !step.selectorRef,
     resolver: (step) => {
       const secs = step.text.match(/(\d+)\s*second/i)?.[1];
@@ -145,18 +200,27 @@ export const gesturePatterns: StepPattern[] = [
   },
   {
     name: 'open-notifications',
+    platforms: ['mobile'],
+    platformAlternative:
+      'a browser has no notification shade — tag the scenario @manual',
     matcher: (step) => /\bnotification(s)?\s+(panel|shade|tray)\b/i.test(step.text) || /\bopen(s)?\s+notifications\b/i.test(step.text),
     resolver: () => ({ templateName: 'open-notifications-action', data: {}, comment: 'Open notification panel' }),
     priority: 16,
   },
   {
     name: 'hide-keyboard',
+    platforms: ['mobile'],
+    platformAlternative:
+      'a browser has no soft keyboard, so nothing overlaps and the step has no web meaning — remove it',
     matcher: (step) => /\bkeyboard\b/i.test(step.text) && /\b(hide|hides|dismiss|dismisses|close|closes)\b/i.test(step.text) && !step.selectorRef,
     resolver: () => ({ templateName: 'hide-keyboard-action', data: {}, comment: 'Hide the soft keyboard' }),
     priority: 16,
   },
   {
     name: 'grant-permission',
+    platforms: ['mobile'],
+    platformAlternative:
+      'browser permissions are granted on the Playwright context, not by a step — configure them there, or tag the scenario @manual',
     matcher: (step) => /\bgrant(s)?\b/i.test(step.text) && /\bpermission(s)?\b/i.test(step.text),
     resolver: (step) => {
       const raw = step.selectorRef || step.text.match(/grant(?:s)?\s+(?:the\s+)?([\w.]+)\s+permission/i)?.[1] || '';
@@ -168,6 +232,9 @@ export const gesturePatterns: StepPattern[] = [
   },
   {
     name: 'set-clipboard',
+    platforms: ['mobile'],
+    platformAlternative:
+      'the browser clipboard is permission-gated and not a step — seed the value through the UI instead, or tag the scenario @manual',
     matcher: (step) => /\bclipboard\b/i.test(step.text) && /\b(set|sets|copy|copies|put|puts)\b/i.test(step.text) && (!!step.dataRef || step.value != null),
     resolver: (step, context) => {
       let value: string;
@@ -180,14 +247,42 @@ export const gesturePatterns: StepPattern[] = [
   },
   {
     name: 'set-geolocation',
+    platforms: ['mobile'],
+    platformAlternative:
+      'browser geolocation is set on the Playwright context, not by a step — configure it there',
     matcher: (step) => /\b(location|geolocation|gps|coordinates)\b/i.test(step.text) && /\b(set|sets|mock|mocks|simulate|simulates|move|moves)\b/i.test(step.text),
-    resolver: (step, context) => {
-      let raw = '';
-      if (step.dataRef) { try { raw = context.dataResolver.resolveData(step.dataRef, context.featureName); } catch { raw = ''; } }
-      const nums = (raw || step.text).match(/-?\d+\.\d+|-?\d+/g) || [];
-      const latitude = nums[0] ?? '0';
-      const longitude = nums[1] ?? '0';
-      return { templateName: 'set-geolocation-action', data: { latitude, longitude }, comment: `Set location to ${latitude}, ${longitude}` };
+    // Resolves nothing itself — it CLASSIFIES and forwards, like `set-clipboard` above and
+    // `deep-link` in lifecycle-patterns.ts. Reading the coordinates here is what caused S1: under the
+    // default runtime-data mode `resolveData` throws, the catch fell back to scanning the step TEXT
+    // for digits (there are none in a `{{ref}}`), and `?? '0'` shipped `0, 0` — Null Island, a real
+    // place off the coast of Africa — as a valid coordinate. A geofence test passed there, silently.
+    resolver: (step) => {
+      // A ref goes to the template untouched: the TEST reads test-data, so one compiled spec works
+      // across environments (`SUNGEN_ENV` swaps the overlay, never the code).
+      if (step.dataRef) {
+        return {
+          templateName: 'set-geolocation-action',
+          data: { dataRef: step.dataRef },
+          comment: `Set location from ${step.dataRef}`,
+        };
+      }
+      const nums = step.text.match(/-?\d+\.\d+|-?\d+/g) || [];
+      // No ref and fewer than two numbers: there is nothing to set. `PatternResolver` cannot return
+      // "no" (types.ts:66 is non-nullable), so the refusal is the template's job — the treatment
+      // `alert-fill-action` got. Defaulting is the one thing that must not happen: an unanswered
+      // coordinate is still somewhere, and the test would pass there.
+      if (nums.length < 2) {
+        return {
+          templateName: 'set-geolocation-action',
+          data: { missing: step.text },
+          comment: `Cannot set location — no coordinates in "${step.text}"`,
+        };
+      }
+      return {
+        templateName: 'set-geolocation-action',
+        data: { latitude: nums[0], longitude: nums[1] },
+        comment: `Set location to ${nums[0]}, ${nums[1]}`,
+      };
     },
     priority: 16,
   },

package/src/patterns/lifecycle-patterns.ts

@@ -46,6 +46,9 @@ export const lifecyclePatterns: StepPattern[] = [
     // `User restart the app` / `User restarts the app`. Must NOT match when a selectorRef is
     // present — `tap [Restart Button]` belongs to the tap pattern, not here.
     name: 'restart-app',
+    platforms: ['mobile'],
+    platformAlternative:
+      'a browser has no app process — re-enter with `User is on [X] page` (and clear storage) to test persistence',
     matcher: (step) => /\brestart(s)?\b/i.test(step.text) && /\bapp\b/i.test(step.text) && !step.selectorRef,
     resolver: (step, context) => requiresAppId(step, context, 'restart the app')
       ?? { templateName: 'restart-app-action', data: {}, comment: 'Restart the app (kill → relaunch → settle)' },
@@ -55,6 +58,9 @@ export const lifecyclePatterns: StepPattern[] = [
     // `User reinstall the app` — needs the session to have installed from a build file
     // (appium:app); the template fails loud with the fix when the cap is absent.
     name: 'reinstall-app',
+    platforms: ['mobile'],
+    platformAlternative:
+      'a browser has no install — clear storage/cookies to reach the first-run state',
     matcher: (step) => /\bre-?install(s)?\b/i.test(step.text) && /\bapp\b/i.test(step.text) && !step.selectorRef,
     resolver: (step, context) => requiresAppId(step, context, 'reinstall the app')
       ?? { templateName: 'reinstall-app-action', data: {}, comment: 'Reinstall the app (remove → install → launch)' },
@@ -64,6 +70,9 @@ export const lifecyclePatterns: StepPattern[] = [
     // `User open deep link {{url}}` (or a quoted literal) — routes the app via a VIEW intent /
     // XCUITest deepLink. THE entry for push-param / universal-link routing matrices (#603).
     name: 'open-deep-link',
+    platforms: ['mobile'],
+    platformAlternative:
+      'a browser URL is not a deep link — use `User is on [X] page` with the route',
     matcher: (step) => /\bdeep\s?-?link\b/i.test(step.text) && (!!step.dataRef || step.value != null) && !step.selectorRef,
     resolver: (step) => ({
       templateName: 'deep-link-action',

package/src/patterns/log-patterns.ts

@@ -12,6 +12,9 @@ export const logPatterns: StepPattern[] = [
     // `Then User see device log contains {{v}}` / `… contains "literal"`. No selectorRef — the
     // element-scoped `contains` assertions all carry one, so there is no collision.
     name: 'device-log-contains',
+    platforms: ['mobile'],
+    platformAlternative:
+      'a browser has no device log — assert the behaviour on the UI, or tag the scenario @manual',
     matcher: (step) =>
       /\b(device\s+)?logs?\b/i.test(step.text) &&
       /\bcontains?\b/i.test(step.text) &&

package/src/patterns/timing-patterns.ts

@@ -13,6 +13,9 @@ export const timingPatterns: StepPattern[] = [
   {
     // `Then User see [X] disappear within 5 seconds` — the element must vanish inside the window.
     name: 'disappears-within',
+    platforms: ['mobile'],
+    platformAlternative:
+      'the web adapter auto-waits — use `Then User see [X] is hidden`',
     matcher: (step) => /\bdisappears?\b/i.test(step.text) && /\bwithin\b/i.test(step.text) && SECONDS.test(step.text) && !!step.selectorRef,
     resolver: (step, context) => {
       const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, context.featureName, step.elementType, step.nth);
@@ -28,6 +31,9 @@ export const timingPatterns: StepPattern[] = [
   {
     // `Then User see [X] still visible after 3 seconds` — the element must survive the window.
     name: 'still-visible-after',
+    platforms: ['mobile'],
+    platformAlternative:
+      'the web adapter auto-waits — assert `Then User see [X] is visible` after the action that might have removed it',
     matcher: (step) => /\bstill\s+visible\s+after\b/i.test(step.text) && SECONDS.test(step.text) && !!step.selectorRef,
     resolver: (step, context) => {
       const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, context.featureName, step.elementType, step.nth);