@sun-asterisk/sungen 3.2.28 → 3.2.29

package/src/generators/test-generator/adapters/playwright/templates/steps/partials/locator-base.hbs

@@ -1,22 +1,22 @@
 {{#if parentLocator}}{{parentLocator}}.{{#switch strategy~}}
-  {{~#case 'testid'}}getByTestId('{{value}}'){{/case~}}
+  {{~#case 'testid'}}getByTestId('{{escapeQuotes value}}'){{/case~}}
   {{~#case 'role'}}{{#if name}}getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }){{else}}getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}){{/if}}{{/case~}}
   {{~#case 'placeholder'}}getByPlaceholder('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
   {{~#case 'label'}}getByLabel('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
   {{~#case 'text'}}getByText('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
-  {{~#case 'locator'}}locator('{{value}}'){{/case~}}
-  {{~#case 'id'}}locator('{{value}}'){{/case~}}
-  {{~#default}}locator('{{value}}'){{/default~}}
+  {{~#case 'locator'}}locator('{{escapeQuotes value}}'){{/case~}}
+  {{~#case 'id'}}locator('{{escapeQuotes value}}'){{/case~}}
+  {{~#default}}locator('{{escapeQuotes value}}'){{/default~}}
 {{~/switch}}{{else~}}
 {{#if scope}}{{#if (eq scope "dialog")}}{{pageRoot}}.{{else}}{{pageRoot}}.getByLabel('{{escapeQuotes scope}}').{{/if}}{{#switch strategy~}}
-  {{~#case 'testid'}}getByTestId('{{value}}'){{/case~}}
+  {{~#case 'testid'}}getByTestId('{{escapeQuotes value}}'){{/case~}}
   {{~#case 'role'}}{{#if name}}getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }){{else}}getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}){{/if}}{{/case~}}
   {{~#case 'placeholder'}}getByPlaceholder('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
   {{~#case 'label'}}getByLabel('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
   {{~#case 'text'}}getByText('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
-  {{~#case 'locator'}}locator('{{value}}'){{/case~}}
-  {{~#case 'id'}}locator('{{value}}'){{/case~}}
-  {{~#default}}locator('{{value}}'){{/default~}}
+  {{~#case 'locator'}}locator('{{escapeQuotes value}}'){{/case~}}
+  {{~#case 'id'}}locator('{{escapeQuotes value}}'){{/case~}}
+  {{~#default}}locator('{{escapeQuotes value}}'){{/default~}}
 {{~/switch}}{{else}}{{#switch strategy~}}
   {{~#case 'testid'}}{{> locator-strategies/testid}}{{/case~}}
   {{~#case 'role'}}{{> locator-strategies/role}}{{/case~}}

package/src/generators/test-generator/adapters/playwright/templates/steps/partials/locator-strategies/id.hbs

@@ -1 +1 @@
-page.locator('{{selector}}')
+page.locator('{{escapeQuotes selector}}')

package/src/generators/test-generator/adapters/playwright/templates/steps/partials/locator-strategies/testid.hbs

@@ -1 +1 @@
-{{pageRoot}}.getByTestId('{{value}}')
+{{pageRoot}}.getByTestId('{{escapeQuotes value}}')

package/src/generators/test-generator/adapters/playwright/templates/steps/partials/locator.hbs

@@ -1,22 +1,22 @@
 {{#if parentLocator}}{{parentLocator}}.{{#switch strategy~}}
-  {{~#case 'testid'}}getByTestId('{{value}}'){{/case~}}
+  {{~#case 'testid'}}getByTestId('{{escapeQuotes value}}'){{/case~}}
   {{~#case 'role'}}{{#if name}}getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }){{else}}getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}){{/if}}{{/case~}}
   {{~#case 'placeholder'}}getByPlaceholder('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
   {{~#case 'label'}}getByLabel('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
   {{~#case 'text'}}getByText('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
-  {{~#case 'locator'}}locator('{{value}}'){{/case~}}
-  {{~#case 'id'}}locator('{{value}}'){{/case~}}
-  {{~#default}}locator('{{value}}'){{/default~}}
+  {{~#case 'locator'}}locator('{{escapeQuotes value}}'){{/case~}}
+  {{~#case 'id'}}locator('{{escapeQuotes value}}'){{/case~}}
+  {{~#default}}locator('{{escapeQuotes value}}'){{/default~}}
 {{~/switch}}{{> locator-nth}}{{else~}}
 {{#if scope}}{{#if (eq scope "dialog")}}{{pageRoot}}.{{else}}{{pageRoot}}.getByLabel('{{escapeQuotes scope}}').{{/if}}{{#switch strategy~}}
-  {{~#case 'testid'}}getByTestId('{{value}}'){{/case~}}
+  {{~#case 'testid'}}getByTestId('{{escapeQuotes value}}'){{/case~}}
   {{~#case 'role'}}{{#if name}}getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }){{else}}getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}){{/if}}{{/case~}}
   {{~#case 'placeholder'}}getByPlaceholder('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
   {{~#case 'label'}}getByLabel('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
   {{~#case 'text'}}getByText('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
-  {{~#case 'locator'}}locator('{{value}}'){{/case~}}
-  {{~#case 'id'}}locator('{{value}}'){{/case~}}
-  {{~#default}}locator('{{value}}'){{/default~}}
+  {{~#case 'locator'}}locator('{{escapeQuotes value}}'){{/case~}}
+  {{~#case 'id'}}locator('{{escapeQuotes value}}'){{/case~}}
+  {{~#default}}locator('{{escapeQuotes value}}'){{/default~}}
 {{~/switch}}{{> locator-nth}}{{else}}{{#switch strategy~}}
   {{~#case 'testid'}}{{> locator-strategies/testid}}{{/case~}}
   {{~#case 'role'}}{{> locator-strategies/role}}{{/case~}}

package/src/generators/test-generator/code-generator.ts

@@ -562,7 +562,11 @@ export class CodeGenerator {
     this.stepMapper.setFlowMode(isFlowFeature);
 
     // Set feature context for data resolution and navigation
-    this.stepMapper.setFeatureContext(featureName, feature.path);
+    // The feature's declared OS rides along so the pattern layer can refuse an Android-only step
+    // in a feature that says it runs on iOS (SG-E025). Read from the tag, not from the adapter.
+    const declaredOs = (feature.tags || [])
+      .find((tg) => tg.startsWith('@platform:'))?.split(':')[1] as 'mobile' | 'android' | 'ios' | undefined;
+    this.stepMapper.setFeatureContext(featureName, feature.path, declaredOs);
     
     // Warn if multiple auth tags at feature level
     if (feature.tags && feature.tags.some(tag => tag.startsWith('@auth:'))) {

package/src/generators/test-generator/diagnostics.ts

@@ -45,6 +45,12 @@
  *             "3 cards are shown" gets an assertion that can only pass if the card's text
  *             IS the digit. Count semantics exist on row/table ("see [T] table with {{n}}",
  *             "see [Ref] row with {{n}}") and lists ("should have count") only
+ *   SG-W016 — a table step on a table located by CSS/testid whose value does not mention `table`
+ *             and that declares no `rows:`. The table templates find rows by `getByRole('row')`;
+ *             on a <div> list that is 0 elements, so `is hidden` / `is empty` pass without checking
+ *             anything and counts/clicks time out (issue #688). A heuristic — the compiler cannot
+ *             see the DOM — so a warning that names both ways out: `rows: '<row shape>'` on the
+ *             table entry, or `role: table`. Once per table per feature
  *   SG-E024 — a mobile app-lifecycle step (restart / reinstall) in a feature that declares no
  *             `Path:` app id. The templates resolve the app through a helper the test-file only
  *             emits when the id is present, so the spec used to compile clean and then die at
@@ -74,7 +80,10 @@
  *             (11), the clause vanished, and the step compiled to `toHaveURL(...)` — asserting the
  *             page IS displayed, the exact opposite of what it reads as, and passing while doing so.
  *             The pattern layer declares what it accounts for via `StepPattern.states`; anything
- *             undeclared reports here and compiles to a loud `throw`
+ *             undeclared reports here and compiles to a loud `throw`. One shape is NOT the author's:
+ *             a pattern NAMED for the state (`is-hidden`) with no `states` at all is a
+ *             @sungen/driver-* older than core — the message then names `sungen update` as the
+ *             fix, and discovery prefers core's own copy of a bundled driver over a stale project one
  *   SG-W022 — a `page` assertion on the mobile adapter that emitted NO executable code. A native app
  *             has no URL, so `Then User see [X] page` compiles to a bare comment: the step reads as
  *             an assertion, checks nothing, and the scenario PASSES regardless. Worse than the
@@ -91,6 +100,33 @@
  *             mobile suite already carrying one of these steps. The remedy is a feature-level reset
  *             tier (`@reset:data`), which is what the message names — app state is reset between
  *             scenarios in the `beforeEach` hook, not mid-scenario by a step.
+ *   SG-E025 — a feature that declares `@platform:ios` uses a step the Appium adapter does NOT serve
+ *             on iOS. The template ships and the step compiles, so nothing about the feature file
+ *             looks wrong; on a simulator it either throws deep in the run (set-connectivity,
+ *             location-services, open-notifications) or — worse — silently does nothing
+ *             (hide-keyboard, guarded `if (!driver.isIOS …)`). Derived from the template body via
+ *             the per-OS axis of the step-support matrix, so it cannot disagree with the adapter.
+ *             SCOPE, stated plainly because the name oversells it: only `@platform:ios` is caught.
+ *             A feature tagged `@platform:mobile` runs on whichever OS `MOBILE_PLATFORM` selects at
+ *             RUN time, so the compiler cannot know — the matrix, not this code, is the net that
+ *             covers that case. Reported as an E-code and compiled to a loud throw, because the
+ *             feature has declared the one OS where the step is known not to work.
+ *   SG-W026 — a mobile ACTIVE-NAVIGATION step that emitted NO executable code, so a promised screen
+ *             change never happens. `When User open [Settings] page` compiles to the one-line
+ *             `navigation` template — a comment noting the app was already launched by the wdio
+ *             capabilities — so the step reads as "go to Settings" and goes nowhere. Pair it with a
+ *             `page` assertion (itself a no-op, reported as SG-W022) and the scenario passes without
+ *             ever touching the app. Completes a half-finished class: `route-assertion` already
+ *             throws and `page-assertion` already reports W022; only `navigation` was silent.
+ *             Scoped to the ACTIVE forms (`open [X] page`, `navigate to [X] page`). The `is on [X]
+ *             page|screen` anchor is EXCLUDED on purpose: that is mobile's app-launch directive and
+ *             its empty output is correct, so warning on it would cry wolf on valid features — and a
+ *             diagnostic that cries wolf gets filtered out, taking the real ones with it.
+ *             Like W021/W022/W023 this stays a WARNING by default. `generate --strict` already fails
+ *             on ANY diagnostic, so this code is blocking under it from the day it lands — which
+ *             means a project running --strict today with an `open [X] page` step starts failing.
+ *             That is the intended outcome (the step was never navigating), but it is a migration
+ *             step, not a silent one: the message names the tap/gesture rewrite.
  *   SG-W024 — two or more scenarios in one feature share a name and at least ONE carries a `@reset:`
  *             tag. The generated per-scenario lookup is keyed on the scenario NAME (a @cases title is
  *             built at runtime, so no compile-time key can match the rendered title), so every
@@ -118,7 +154,7 @@
  * Generation always COMPLETES — the rest of the scenario and the rest of the file still compile.
  */
 
-export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010' | 'SG-W011' | 'SG-W012' | 'SG-W013' | 'SG-W014' | 'SG-W015' | 'SG-E020' | 'SG-E021' | 'SG-W020' | 'SG-W021' | 'SG-W022' | 'SG-W023' | 'SG-W024' | 'SG-E022' | 'SG-E023' | 'SG-E024';
+export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010' | 'SG-W011' | 'SG-W012' | 'SG-W013' | 'SG-W014' | 'SG-W015' | 'SG-W016' | 'SG-E020' | 'SG-E021' | 'SG-W020' | 'SG-W021' | 'SG-W022' | 'SG-W023' | 'SG-W024' | 'SG-W026' | 'SG-E025' | 'SG-E022' | 'SG-E023' | 'SG-E024';
 
 export interface Diagnostic {
   code: DiagnosticCode;
@@ -142,6 +178,7 @@ export class DiagnosticsCollector {
     return this.items.length;
   }
 
+
   /** One line per diagnostic, ready for CLI output. */
   formatLines(): string[] {
     return this.items.map((d) => {

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

@@ -1,10 +1,11 @@
 import { ParsedStep } from '../../gherkin-parser';
 import { MappedStep } from '../step-mapper';
-import { StepPattern, PatternContext, Platform } from './types';
+import { StepPattern, PatternContext, Platform, StateClause } from './types';
 import { capabilityRegistry } from '../../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../../capabilities/discover';
 import { maskRefsForMatching } from '../utils/mask-refs-for-matching';
 import { unsupportedStepCode } from './unsupported-step-code';
+import { osSupportOfTemplate } from '../adapters/appium/os-support';
 
 // Both helpers moved out of this file so the Gherkin parser (state-clause extraction) and the
 // step-mapper (SG-W001 no-pattern fallback) can use them without importing the pattern registry.
@@ -31,12 +32,18 @@ const TAP_GESTURE_FORMS = /\bdouble[-\s]?tap|\btap(?:s)?\b[^.]*\b(?:top of|at th
  * The rewrite is ADDITIVE — `tap` becomes `tap click`, it does not become `click`. Two reasons, and
  * the first one cost a full golden run to learn:
  *
- *   1. `@sungen/driver-mobile` is registered on WEB projects too (same non-opt-in bundling as
- *      driver-ui). Substituting the verb re-keys `mobile-tap` onto "click", where its priority 15
- *      outranks the generic `click-element` (10) — so it captured every plain click on every WEB
- *      feature and relabelled it a tap. 8 golden fixtures caught it. Adding a verb instead of
- *      swapping one means text with no "tap" in it is returned untouched, so web output cannot
- *      change here BY CONSTRUCTION rather than by our vigilance.
+ *   1. `@sungen/driver-mobile` can be registered on a WEB project. (It is NOT bundled — an earlier
+ *      version of this comment said it was, which was never true: it is not in `BUNDLED_DRIVERS`
+ *      and not a core dependency. Discovery simply loaded whatever it could resolve, which in this
+ *      monorepo is everything; discovery now gates an opt-in platform driver by the project
+ *      `platform:`, so this reaches web only when both drivers are present and no platform is
+ *      declared.) Substituting the verb re-keys `mobile-tap` onto "click", where its
+ *      priority 15 outranks the generic `click-element` (10) — so it captured every plain click on
+ *      every WEB feature and relabelled it a tap. 8 golden fixtures caught it. Adding a verb instead
+ *      of swapping one means text with no "tap" in it is returned untouched, so web output cannot
+ *      change here BY CONSTRUCTION rather than by our vigilance. `platforms:` does not remove the
+ *      need for that: `mobile-tap` resolves to `click-action`, which both adapters ship, so it is
+ *      one of the two mobile patterns that must stay UNDECLARED.
  *   2. Both vocabularies then see their own verb, and ordinary PRIORITY decides the winner —
  *      no matcher has to learn about the other. `tap … and accept alert` reaches
  *      `click-with-alert` (21); `tap … in [T] table row 2` reaches `table-action-in-row-nth` (19);
@@ -143,6 +150,12 @@ export class PatternRegistry {
           const resolved = pattern.resolver(step, context);
           if (!resolved) continue; // resolver declined — fall through
 
+          // iOS gate — AFTER the resolver, because it needs the template the step actually reached.
+          // The sibling of platformMiss above: that one refuses a pattern off-platform, this one
+          // refuses a template the declared OS cannot serve.
+          const iosMiss = PatternRegistry.iosUnsupported(resolved.templateName, context, step);
+          if (iosMiss) return iosMiss;
+
           // State-clause gate. Deliberately AFTER the resolver, not before it: a resolver may return
           // null to say "not mine after all", and the search then continues to a lower-priority
           // pattern that may well be the one that asserts the state. Gating earlier judged a pattern
@@ -190,6 +203,45 @@ export class PatternRegistry {
   /**
    * SG-W020 — the matched pattern declares `platforms` and the active one is not among them.
    */
+  /**
+   * SG-E025 — the feature says `@platform:ios`, and the template it reached does not work there.
+   *
+   * Derived from the template body (`osSupportOfTemplate`), never from a list, so it cannot drift
+   * from the adapter the way a hand-kept table would. Two states are refused, for different
+   * reasons: `refuses` would throw deep inside a device run instead of at compile time, and `noop`
+   * would not fail at all — the step would run, do nothing, and the scenario would pass.
+   *
+   * Only an EXPLICIT `@platform:ios` is gated. `@platform:mobile` picks its OS from
+   * MOBILE_PLATFORM at run time, so gating it would mean guessing; the per-OS matrix columns are
+   * what cover that case, and they are the primary deliverable of this axis.
+   */
+  private static iosUnsupported(
+    templateName: string, context: PatternContext, step: ParsedStep
+  ): MappedStep | null {
+    if (context.featurePlatform !== 'ios') return null;
+    if ((context.platform ?? 'web') !== 'mobile') return null;
+
+    const pair = osSupportOfTemplate(templateName);
+    // No appium template of that name is a different failure, already reported by template
+    // resolution — a second message here would give one cause two names.
+    if (!pair || pair.ios === 'yes' || pair.ios === 'inherit') return null;
+
+    const why = pair.ios === 'noop'
+      ? 'does nothing on iOS — it is guarded out with no error, so the step would run and the scenario would PASS having done nothing'
+      : 'throws on iOS — the template refuses there, so the failure would surface deep inside a device run instead of here';
+    const reason =
+      `step "${step.text}" compiles to \`${templateName}\`, which ${why}. ` +
+      `This feature declares @platform:ios. Either drop to @platform:android (the OS that serves this step), ` +
+      `move the step out of the iOS feature, or tag the scenario @manual:M10 (device/OS capability). ` +
+      `See the Android/iOS columns in docs/spec/step-support-matrix.md.`;
+
+    context.diagnostics?.add('SG-E025', reason, { feature: context.featureName, step: step.text });
+    return {
+      code: unsupportedStepCode(reason),
+      comment: `iOS-unsupported step in an @platform:ios feature — see SG-E025`,
+    };
+  }
+
   private static platformMiss(
     pattern: StepPattern, context: PatternContext, step: ParsedStep
   ): MappedStep | null {
@@ -241,7 +293,8 @@ export class PatternRegistry {
       `("${pattern.name}") does not assert that state — the clause would be SILENTLY DROPPED and the ` +
       `step would check something other than what it reads as. Use a step form that owns the state ` +
       `(e.g. "User see [Ref] <type> is ${state}" on the element itself), or drop the clause if the ` +
-      `bare assertion is what you meant. If sungen cannot express the check, tag the scenario @manual.`;
+      `bare assertion is what you meant. If sungen cannot express the check, tag the scenario @manual.` +
+      PatternRegistry.stateMissSkewHint(pattern, state);
 
     context.diagnostics?.add('SG-E021', reason, {
       feature: context.featureName,
@@ -253,6 +306,23 @@ export class PatternRegistry {
     };
   }
 
+  /**
+   * The one SG-E021 that is NOT the author's to fix. A pattern NAMED for the state (`is-hidden`,
+   * `should-be-disabled`) that declares no `states` at all is not under-annotated — it is a driver
+   * built before the field existed, loaded against a core that requires it (a stale project copy of
+   * @sungen/driver-ui). The generic message then tells the author to use the exact form they wrote,
+   * which cost a QA team a day of Gherkin rewrites that could never work. Name the real cause.
+   */
+  private static stateMissSkewHint(pattern: StepPattern, state: StateClause): string {
+    const namesTheState = pattern.name.includes(state.replace(/\s+/g, '-'));
+    if (pattern.states !== undefined || !namesTheState) return '';
+    return (
+      ` NOTE: "${pattern.name}" is named for this very state yet declares no states at all — that is a ` +
+      `@sungen/driver-* package older than sungen itself, not a Gherkin problem. Run \`sungen update\` in the ` +
+      `project so the drivers match the sungen version, then generate again.`
+    );
+  }
+
   /**
    * SG-E020 — the pattern is in-platform but the active adapter ships no template for it. A gap in
    * the adapter, not in the authored Gherkin: name every coordinate a reader needs to act on it.

package/src/generators/test-generator/patterns/types.ts

@@ -84,6 +84,14 @@ export interface PatternContext {
   effectiveKeyword?: string;
   /** The platform the ACTIVE adapter compiles for. Absent = 'web' (back-compat default). */
   platform?: Platform;
+  /**
+   * The OS the FEATURE declares via `@platform:<mobile|android|ios>` — distinct from `platform`
+   * above, which is the adapter. Only `ios` is actionable at compile time: it is the single case
+   * where the compiler knows which mobile OS will run, so it can refuse a step that does nothing
+   * (or throws) there. `mobile` means both OSes and is deliberately NOT gated — the real OS is
+   * chosen at run time by MOBILE_PLATFORM, so a compile-time verdict would be a guess.
+   */
+  featurePlatform?: 'mobile' | 'android' | 'ios';
   /** The adapter's own name ('playwright' | 'appium' | …) — quoted verbatim in SG-E020/SG-W020. */
   adapterName?: string;
   /** Compile-diagnostics channel, so the pattern layer can report instead of throwing. */

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

@@ -9,6 +9,31 @@ import { unsupportedStepCode } from './patterns/unsupported-step-code';
 import { loadAppProfile, ResolvedAppProfile } from './app-profile';
 import { capabilityRegistry } from '../../capabilities/registry';
 
+/**
+ * The correction SG-W001 owes a project that gated a platform driver away.
+ *
+ * Gating (plan `260903-1654` phase 11) keeps a mobile-only pattern out of a web project's registry.
+ * Right isolation — but `platformMiss` then has nothing to catch, so a mobile-only step falls
+ * through to SG-W001, whose sentence "sungen has no step form for it" is FALSE: the form exists in
+ * a vocabulary this project declined. Ungated, the author would have seen SG-W020 naming the
+ * alternative.
+ *
+ * It states only what discovery knows. Which STEP the skipped driver owned is unknowable here — the
+ * patterns were never loaded — and a static list of off-platform step texts would rot on the next
+ * pattern anyone adds, putting a second wrong sentence where the first one was.
+ *
+ * Returns '' when nothing was gated, so every project that predates the platform profile keeps the
+ * message it has today, word for word.
+ */
+function offPlatformHint(): string {
+  const gated = capabilityRegistry.gatedDrivers();
+  if (!gated.length) return '';
+  const platform = capabilityRegistry.gatedForPlatform();
+  const names = gated.map(([pkg, serves]) => `${pkg} (${serves})`).join(', ');
+  return `this project declares platform: ${platform}, so ${names} was not loaded; a ${gated[0][1]}-only step form exists but is out of scope here. Per-platform vocabulary: docs/spec/step-support-matrix.md.`;
+}
+
+
 export interface MappedStep {
   code: string; // Generated Playwright code
   comment?: string; // Optional comment
@@ -28,6 +53,8 @@ export class StepMapper {
   private dataResolver: DataResolver;
   private baseURL: string;
   private featureName?: string;
+  /** The feature's declared `@platform:` OS, for the compile-time iOS gate (SG-E025). */
+  private featurePlatform?: 'mobile' | 'android' | 'ios';
   private screenName?: string;
   private featurePath?: string;
   private currentScenarioSteps?: ParsedStep[];
@@ -74,7 +101,9 @@ export class StepMapper {
     this.platform = adapter.frameworkName === 'appium' ? 'mobile' : 'web';
     this.templateEngine = new TemplateEngine(templatesDir);
     this.patternRegistry = new PatternRegistry();
-    this.selectorResolver = new SelectorResolver(undefined, options.screenName);
+    // `platform` is set just above from the ADAPTER — the resolver needs it to decline the
+    // list-member auto-infer that has no mobile equivalent (#665).
+    this.selectorResolver = new SelectorResolver(undefined, options.screenName, this.platform);
     this.dataResolver = new DataResolver(undefined, options.screenName, options.runtimeData);
 
     // App profile (qa/app.yaml) — loaded after PatternRegistry so capability discovery has
@@ -100,8 +129,9 @@ export class StepMapper {
   /**
    * Set feature context for data and selector resolution
    */
-  setFeatureContext(featureName: string, featurePath?: string): void {
+  setFeatureContext(featureName: string, featurePath?: string, featurePlatform?: 'mobile' | 'android' | 'ios'): void {
     this.featureName = featureName;
+    this.featurePlatform = featurePlatform;
     this.featurePath = featurePath;
     this.selectorResolver.setFeatureContext(featureName);
     // One StepMapper serves every feature in a run, so the step counter that names the
@@ -396,6 +426,7 @@ export class StepMapper {
       this.checkDataRefConsumed(step, mappedStep);
       this.checkPageAssertionNoOpOnMobile(step, mappedStep);
       this.checkSetupNoOpOnMobile(step, mappedStep);
+      this.checkNavigationNoOpOnMobile(step, mappedStep);
       this.checkPageAssertionFallback(step, mappedStep);
       this.checkDeclaredUrlHasNoQuery(step, mappedStep);
       const swallowed = this.checkAssertionClauseSwallowed(step, mappedStep);
@@ -422,7 +453,13 @@ export class StepMapper {
         step: step.text,
       });
     } else {
-      reason = `step "${step.text}" 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 if the check cannot be automated.`;
+      // Two shapes, because the ORIGINAL CLAUSE is what was wrong. Appending a correction to
+      // "sungen has no step form for it" leaves the reader a sentence that contradicts itself one
+      // clause later. When the gate dropped a vocabulary, that clause is simply not written.
+      const hint = offPlatformHint();
+      reason = hint
+        ? `step "${step.text}" matched no pattern here — ${hint} If that is not what you meant, rephrase using a supported step form (see the sungen-gherkin-syntax reference), or tag the scenario @manual if the check cannot be automated.`
+        : `step "${step.text}" 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 if the check cannot be automated.`;
       this.diagnostics?.add('SG-W001', reason, {
         feature: this.featureName,
         step: step.text,
@@ -665,6 +702,70 @@ export class StepMapper {
   /**
    * Create pattern context for generators
    */
+  /**
+   * Whether a mapped step emits anything that actually RUNS.
+   *
+   * Comments are stripped — block comments as well as line ones, because a template written with
+   * `/* … *\/` would otherwise read as executable code and silence the no-op diagnostics exactly
+   * when they were needed. Keyed on the emitted CODE rather than on a template name (MappedStep
+   * does not carry one), so any future template that degrades to a comment is caught without being
+   * enumerated anywhere.
+   *
+   * Shared by the SG-W022 / SG-W023 / SG-W026 checks — the three of them ask the same question, and
+   * three copies of this would drift.
+   */
+  private emitsExecutableCode(mapped: MappedStep): boolean {
+    return Boolean(
+      (mapped.code || '')
+        .replace(/\/\*[\s\S]*?\*\//g, '')
+        .split('\n')
+        .map((l) => l.replace(/\/\/.*$/, '').trim())
+        .filter(Boolean)
+        .join(''),
+    );
+  }
+
+  /**
+   * SG-W026 — a mobile ACTIVE-NAVIGATION step that emitted no executable code, so a promised screen
+   * change never happens.
+   *
+   * `When User open [Settings] page` compiles to the one-line `navigation` template: a comment
+   * noting the app was already launched by the wdio capabilities. The step reads as "go to Settings"
+   * and goes nowhere. Pair it with `Then User see [X] page` — itself a no-op, reported as SG-W022 —
+   * and the whole scenario passes without ever touching the app.
+   *
+   * This completes a class that was handled in halves: `route-assertion` already throws loudly and
+   * `page-assertion` already reports W022; `navigation` alone was silent.
+   *
+   * Scoped to the ACTIVE forms. `is on [X] page` and its mobile `screen` twin are mobile's
+   * app-LAUNCH anchor, whose empty output is correct and documented as such where IS_ON_TYPES is
+   * defined — warning there would cry wolf on every valid mobile feature, and a diagnostic that
+   * cries wolf gets filtered out, taking the real ones with it. The exclusion is matched on
+   * `is on` FIRST, before the open/navigate test, because "the user is on the page they opened"
+   * phrasings contain both.
+   *
+   * Deliberately NOT a `throw`, for the same reason as SG-W023: an unfulfilled navigation weakens
+   * the scenario rather than inverting an assertion, and throwing would break every mobile suite
+   * already carrying one of these steps. `generate --strict` is the opt-in that makes it fail.
+   */
+  private checkNavigationNoOpOnMobile(step: ParsedStep, mapped: MappedStep): void {
+    if (this.platform !== 'mobile' || !this.diagnostics) return;
+
+    const text = step.text.toLowerCase();
+    // The anchor is checked first and wins: it is legitimately empty on mobile.
+    if (/\bis\s+on\b/.test(text)) return;
+    if (!/\bopens?\b|\bnavigates?\s+to\b|\bgo(es)?\s+to\b/.test(text)) return;
+    // Only the navigation TARGET forms — `open [X] page|screen`. `open [X] dialog`/`menu` is a tap
+    // on a control, which compiles to real code and never reaches here anyway.
+    if (step.elementType && !['page', 'screen'].includes(step.elementType)) return;
+
+    if (this.emitsExecutableCode(mapped)) return;
+
+    this.diagnostics.add('SG-W026',
+      'this navigation step compiled to a COMMENT — a native app is already launched by the wdio capabilities, so nothing navigates and the following steps run against whatever screen the app happens to be on. Change screens the way a user does, with a tap/gesture on the control that opens it (`When User tap [Settings] button`), and assert a marker on the new screen; keep `is on [X] screen` only as the feature\'s opening anchor',
+      { feature: this.featureName, step: step.text });
+  }
+
   /**
    * SG-W023 — a mobile SETUP step that emitted no executable code, so a declared precondition is
    * never actually established.
@@ -699,13 +800,7 @@ export class StepMapper {
     // Strip comments; whatever remains is what actually runs. Block comments too — a template written
     // with `/* … */` would otherwise read as executable code and silence this check exactly when it
     // was needed.
-    const executable = (mapped.code || '')
-      .replace(/\/\*[\s\S]*?\*\//g, '')
-      .split('\n')
-      .map((l) => l.replace(/\/\/.*$/, '').trim())
-      .filter(Boolean)
-      .join('');
-    if (executable) return;
+    if (this.emitsExecutableCode(mapped)) return;
 
     const remedy = isBackendState
       ? 'backend state is not app state — reset it through a test API/script, or bind a `@query:` precondition, the same way the web adapter has to'
@@ -738,13 +833,7 @@ export class StepMapper {
     // Strip comments; whatever remains is what actually runs. Block comments are handled as well as
     // line ones: a template written with `/* … */` would otherwise read as executable code and
     // silently defeat this check — the diagnostic would go quiet exactly when it was needed.
-    const executable = (mapped.code || '')
-      .replace(/\/\*[\s\S]*?\*\//g, '')
-      .split('\n')
-      .map((l) => l.replace(/\/\/.*$/, '').trim())
-      .filter(Boolean)
-      .join('');
-    if (executable) return;
+    if (this.emitsExecutableCode(mapped)) return;
     this.diagnostics.add('SG-W022',
       'a native app has no URL, so this page assertion compiled to a COMMENT — it asserts nothing and the scenario passes regardless. Assert a marker that is actually on the screen instead (`Then User see [Some Element] ...`), or tag the scenario @manual',
       { feature: this.featureName, step: step.text });
@@ -779,6 +868,7 @@ export class StepMapper {
       renderLocator: (resolved) => this.templateEngine.renderStep('locator', resolved),
       appProfile: this.appProfile,
       platform: this.platform,
+      featurePlatform: this.featurePlatform,
       adapterName: this.adapterName,
       diagnostics: this.diagnostics,
       baseURL: this.baseURL,