@sun-asterisk/sungen 3.2.28 → 3.2.30

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-match-data.hbs

@@ -1,6 +1,9 @@
 {
   const table = {{> locator}};
-  const rows = table.locator('tbody').getByRole('row', { includeHidden: true }).filter({ visible: true });
+{{!-- Row universe: `rows:` on the table entry (what EVERY row matches — a <div> list has no
+     role=row, so the ARIA chain below is 0 elements and this assertion would be vacuous, issue #688)
+     wins; otherwise the historical ARIA chain, byte-identical. --}}
+  const rows = table{{#if rows}}.locator('{{escapeQuotes rows}}'){{else}}.locator('tbody').getByRole('row', { includeHidden: true }){{/if}}.filter({ visible: true });
 {{#each assertions}}
   {{{this}}}
 {{/each~}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-row-count.hbs

@@ -1 +1,4 @@
-await expect({{> locator}}.locator('tbody').getByRole('row', { includeHidden: true }).filter({ visible: true })).toHaveCount({{expectedCount}});
+{{!-- Row universe: `rows:` on the table entry (what EVERY row matches — a <div> list has no
+     role=row, so the ARIA chain below is 0 elements and this assertion would be vacuous, issue #688)
+     wins; otherwise the historical ARIA chain, byte-identical. --}}
+await expect({{> locator}}{{#if rows}}.locator('{{escapeQuotes rows}}'){{else}}.locator('tbody').getByRole('row', { includeHidden: true }){{/if}}.filter({ visible: true })).toHaveCount({{expectedCount}});

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-row-exists.hbs

@@ -1,17 +1,25 @@
 {{~#if rowSelector}}
+{{!-- Declared row LABEL = one positioned row. The toHaveCount(1) guard is what turns "I used the
+     row label as the row SHAPE" (div.job-row, issue #688) into a named error instead of a
+     strict-mode message pointing at the wrong line. --}}
 {{~#if isGiven}}
-const tableRow = {{> locator}}.locator('{{rowSelector}}');
+const tableRow = {{> locator}}.locator('{{escapeQuotes rowSelector}}');
+await expect(tableRow, 'row label "[{{escapeQuotes rowLabel}}]" must position exactly ONE row (its selectors.yaml entry is relative to the table) — if this selector describes what EVERY row looks like, declare it as `rows:` on the TABLE entry instead').toHaveCount(1);
 await tableRow.filter({ hasText: '{{escapeQuotes filterValue}}' }).waitFor();
 {{~else}}
-const tableRow = {{> locator}}.locator('{{rowSelector}}');
+const tableRow = {{> locator}}.locator('{{escapeQuotes rowSelector}}');
+await expect(tableRow, 'row label "[{{escapeQuotes rowLabel}}]" must position exactly ONE row (its selectors.yaml entry is relative to the table) — if this selector describes what EVERY row looks like, declare it as `rows:` on the TABLE entry instead').toHaveCount(1);
 await expect(tableRow).toContainText('{{escapeQuotes filterValue}}');
 {{~/if}}
 {{~else}}
+{{!-- Row universe: `rows:` on the table entry (what EVERY row matches — a <div> list has no
+     role=row, so the ARIA chain below is 0 elements and this assertion would be vacuous, issue #688)
+     wins; otherwise the historical ARIA chain, byte-identical. --}}
 {{~#if isGiven}}
-const tableRow = {{> locator}}.getByRole('row', { includeHidden: true }).filter({ hasText: '{{escapeQuotes filterValue}}' }).filter({ visible: true });
+const tableRow = {{> locator}}{{#if rows}}.locator('{{escapeQuotes rows}}'){{else}}.getByRole('row', { includeHidden: true }){{/if}}.filter({ hasText: '{{escapeQuotes filterValue}}' }).filter({ visible: true });
 await tableRow.waitFor();
 {{~else}}
-const tableRow = {{> locator}}.getByRole('row', { includeHidden: true }).filter({ hasText: '{{escapeQuotes filterValue}}' }).filter({ visible: true });
+const tableRow = {{> locator}}{{#if rows}}.locator('{{escapeQuotes rows}}'){{else}}.getByRole('row', { includeHidden: true }){{/if}}.filter({ hasText: '{{escapeQuotes filterValue}}' }).filter({ visible: true });
 await expect(tableRow).toBeVisible();
 {{~/if}}
 {{~/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-row-not-exists.hbs

@@ -1,5 +1,17 @@
+{{~#if rowSelector}}
+{{!-- Declared row LABEL = one positioned row (same contract as the exists twin). The row must not
+     hold the value. Block-scoped: this step does not enter row scope, so it must not redeclare
+     the function-level tableRow the exists step binds. --}}
+{ const tableRow = {{> locator}}.locator('{{escapeQuotes rowSelector}}');
+await expect(tableRow, 'row label "[{{escapeQuotes rowLabel}}]" must position exactly ONE row (its selectors.yaml entry is relative to the table) — if this selector describes what EVERY row looks like, declare it as `rows:` on the TABLE entry instead').toHaveCount(1);
+await expect(tableRow).not.toContainText('{{escapeQuotes filterValue}}'); }
+{{~else}}
+{{!-- Row universe: `rows:` on the table entry (what EVERY row matches — a <div> list has no
+     role=row, so the ARIA chain below is 0 elements and this assertion would be vacuous, issue #688)
+     wins; otherwise the historical ARIA chain, byte-identical. --}}
 {{~#if isGiven}}
-await {{> locator}}.getByRole('row', { includeHidden: true }).filter({ hasText: '{{escapeQuotes filterValue}}' }).filter({ visible: true }).waitFor({ state: 'hidden' });
+await {{> locator}}{{#if rows}}.locator('{{escapeQuotes rows}}'){{else}}.getByRole('row', { includeHidden: true }){{/if}}.filter({ hasText: '{{escapeQuotes filterValue}}' }).filter({ visible: true }).waitFor({ state: 'hidden' });
 {{~else}}
-await expect({{> locator}}.getByRole('row', { includeHidden: true }).filter({ hasText: '{{escapeQuotes filterValue}}' }).filter({ visible: true })).toHaveCount(0);
+await expect({{> locator}}{{#if rows}}.locator('{{escapeQuotes rows}}'){{else}}.getByRole('row', { includeHidden: true }){{/if}}.filter({ hasText: '{{escapeQuotes filterValue}}' }).filter({ visible: true })).toHaveCount(0);
+{{~/if}}
 {{~/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/visible-with-role-variable-assertion.hbs

@@ -1,9 +1,9 @@
 {{#if name}}
 {{#if dataValue}}
-await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{#if (gte nth 0)}}.nth({{nth}}){{/if}}).toBeVisible();
+await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{> locator-nth}}).toBeVisible();
 {{else}}
-await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }){{#if (gte nth 0)}}.nth({{nth}}){{/if}}).toBeVisible();
+await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }){{> locator-nth}}).toBeVisible();
 {{/if}}
 {{else}}
-await expect(page.getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{#if (gte nth 0)}}.nth({{nth}}){{/if}}).toBeVisible();
+await expect(page.getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{> locator-nth}}).toBeVisible();
 {{/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/visible-with-value-assertion.hbs

@@ -1 +1 @@
-await expect(page.getByText('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{#if (gte nth 0)}}.nth({{nth}}){{/if}}).toBeVisible();
+await expect(page.getByText('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{> locator-nth}}).toBeVisible();

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/visible-with-variable-assertion.hbs

@@ -1 +1 @@
-await expect(page.getByText('{{escapeQuotes selectorValue}}').filter({ hasText: /.*{{escapeRegex dataValue}}$/ }){{#if (gte nth 0)}}.nth({{nth}}){{/if}}).toBeVisible();
+await expect(page.getByText('{{escapeQuotes selectorValue}}').filter({ hasText: /.*{{escapeRegex dataValue}}$/ }){{> locator-nth}}).toBeVisible();

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

@@ -0,0 +1,8 @@
+{{!-- The `checked:`/`selected:` signal from selectors.yaml, appended as the options argument of
+      setCheckedState/expectCheckedState (issue #730). One partial so all nine call sites carry it
+      identically, and so a site that declares nothing stays BYTE-IDENTICAL to before — the whole
+      argument disappears rather than becoming an empty object. Takes `cls`/`attr` so a caller can
+      pass a signal resolved from a DIFFERENT entry than the one it spread (table-action-in-row
+      spreads the TABLE but acts on the row's own control). A selector declares one or the other;
+      the resolver refuses both, so the two branches never collide here. --~}}
+{{~#if cls}}, { checkedClass: '{{escapeQuotes cls}}' }{{else if attr}}, { checkedAttribute: '{{escapeQuotes attr}}' }{{/if~}}

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-nth.hbs

@@ -1 +1 @@
-{{#if (gte nth 0)}}.nth({{nth}}){{/if}}
+{{#if (gte nth 0)}}.nth({{nth}}){{else if (eq nth -1)}}.last(){{/if}}

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/adapters/playwright/templates/test-file.hbs

@@ -98,6 +98,16 @@ test.describe.serial('{{featureName}}', () => {
   });
 {{/if}}
 
+{{#if beforeAll}}
+{{beforeAll}}
+
+{{/if}}
+{{#if afterAll}}
+  // User @afterAll runs BEFORE the built-in close below (Playwright runs afterAll hooks in registration
+  // order), so the shared page is still open for its cleanup steps.
+{{afterAll}}
+
+{{/if}}
   test.afterAll(async () => {
     await page.close();
     await context.close();
@@ -112,18 +122,10 @@ test.describe.serial('{{featureName}}', () => {
 {{#if screenshotOnFailure}}
   test.use({ screenshotOnFailure: true });
 
-{{/if}}
-{{#if beforeAll}}
-{{beforeAll}}
-
 {{/if}}
 {{#if afterEach}}
 {{afterEach}}
 
-{{/if}}
-{{#if afterAll}}
-{{afterAll}}
-
 {{/if}}
 {{#if authGroups}}
 {{#each authGroups}}

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

@@ -2,7 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import { ParsedFeature, ParsedScenario, ParsedStep } from '../gherkin-parser';
 import { StepMapper } from './step-mapper';
-import { TestGeneratorAdapter, adapterRegistry } from './adapters';
+import { TestGeneratorAdapter, adapterRegistry, HookStep } from './adapters';
 import { transformToRuntimeData } from './utils/runtime-data-transformer';
 import { DiagnosticsCollector } from './diagnostics';
 import { parseResetTier, DEFAULT_RESET_TIER } from './reset-tier';
@@ -12,6 +12,9 @@ import { readCapabilities } from '../../harness/capability';
 import { parseManualComments } from '../../exporters/scenario-merger';
 import { findSyntaxError } from './utils/spec-syntax-check';
 
+/** One capability-injected precondition statement (`@api:`/`@query:` → `testData.bind(name, …)`). */
+type CapabilityPrecondition = { comment?: string; code: string; boundVars?: string[] };
+
 /**
  * Filter base scenario steps for @extend: only keep Given→When steps.
  * Skips Then and any And/But that follow Then (since And/But inherit
@@ -346,7 +349,7 @@ export class CodeGenerator {
     // helper into every UI spec — including the many that touch no URL at all. Hence the body is
     // rendered BEFORE the imports. Importing exactly the names used keeps the import honest; the
     // helper file itself is synced only when something needs it (an api-only unit carries none).
-    const urlAssertImports = ['urlMatches', 'joinPath', 'expectPage'].filter((n) => testCode.includes(`${n}(`)).join(', ');
+    const urlAssertImports = ['urlMatches', 'joinPath', 'expectPage', 'waitForPage'].filter((n) => testCode.includes(`${n}(`)).join(', ');
     if (urlAssertImports) this.syncGeneratedHelper(outputDir, 'url-assert.ts', 'specs-url-assert.ts');
 
     // Same body-first rule for the runtime regex-escape helper: only a spec whose
@@ -354,7 +357,16 @@ export class CodeGenerator {
     const regexEscapeImport = /\bescapeRegExp\(/.test(testCode);
     if (regexEscapeImport) this.syncGeneratedHelper(outputDir, 'regex-escape.ts', 'specs-regex-escape.ts');
 
-    const imports = this.adapter.renderImports({ runtimeData: this.options.runtimeData, basePath, needsCleanupImport, needsDb, needsApi, needsMock, urlAssertImports, regexEscapeImport });
+    // Same body-first rule for the checked-state helper (#675): only a spec that actually compiled a
+    // `check`/`uncheck` step imports (and syncs) it, so the many specs that touch no toggle carry
+    // neither the import nor the file.
+    // Import exactly the names the body used, like urlAssertImports above — the action half and the
+    // assertion half of #675 are independent, and most specs need only one of them.
+    const checkedStateImports = ['setCheckedState', 'expectCheckedState']
+      .filter((n) => testCode.includes(`${n}(`)).join(', ');
+    if (checkedStateImports) this.syncGeneratedHelper(outputDir, 'checked-state.ts', 'specs-checked-state.ts');
+
+    const imports = this.adapter.renderImports({ runtimeData: this.options.runtimeData, basePath, needsCleanupImport, needsDb, needsApi, needsMock, urlAssertImports, regexEscapeImport, checkedStateImports });
 
     // Combine and collapse any runs of 3+ newlines down to 2 (one blank line max)
     const raw = `${imports}\n\n${testCode}`;
@@ -482,10 +494,10 @@ export class CodeGenerator {
    * Each capability owns its annotation codegen via the SPI (`preconditionCodegen`); the compiler
    * just composes + indents the returned statements (R4).
    */
-  private capabilityPreconditions(scenario: ParsedScenario): Array<{ comment?: string; code: string; boundVars?: string[] }> {
+  private capabilityPreconditions(scenario: ParsedScenario): CapabilityPrecondition[] {
     discoverAndRegisterCapabilities();
     const tags = scenario.tags || [];
-    const out: Array<{ comment?: string; code: string; boundVars?: string[] }> = [];
+    const out: CapabilityPrecondition[] = [];
     for (const cap of capabilityRegistry.all()) {
       if (!cap.preconditionCodegen) continue;
       out.push(...cap.preconditionCodegen({ tags, screenName: this.queryScreenName, cwd: process.cwd() }));
@@ -527,6 +539,11 @@ export class CodeGenerator {
     if (this.options.runtimeData) {
       this.syncGeneratedHelper(outputDir, 'test-data.ts', 'specs-test-data.ts');
     }
+    // The Playwright reporter that keeps machine paths out of the committed JSON result — refreshed
+    // like base.ts so an existing project picks it up on its next generate (mobile has no Playwright).
+    if (this.adapter.frameworkName !== 'appium') {
+      this.syncGeneratedHelper(outputDir, 'report-path-sanitize-reporter.ts', 'specs-report-path-sanitize-reporter.ts');
+    }
   }
 
   private async generateTestCode(feature: ParsedFeature): Promise<string> {
@@ -562,7 +579,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:'))) {
@@ -596,6 +617,26 @@ export class CodeGenerator {
     // never skip-cascades). `@serial` opts into the shared-page serial suite for a stateful sequence.
     const isParallel = !(feature.tags || []).includes('@serial');
 
+    // A `@beforeAll` hook runs before every test of the describe, so the `{{name}}` its `@api:`/`@query:`
+    // preconditions bind are readable from EVERY scenario of the feature. Register the bound heads
+    // before the scenarios map: the per-scenario captured set is cleared at each scenario, and without
+    // this a scenario's `{{login.body.token}}` compiles to a dead literal. `@afterEach`/`@afterAll` run
+    // after the tests — their bindings stay hook-local. The set is per feature: clear it FIRST, before
+    // the Background maps, or the previous feature's bindings would leak into this Background.
+    // Whether the Background itself may read them depends on where it runs: per-scenario (parallel)
+    // Background is a beforeEach and runs after the user beforeAll → register before it; @serial
+    // Background is inlined into the built-in beforeAll that runs BEFORE the user hook → register
+    // only after it has mapped, so a serial Background ref stays an unresolved literal, as it should.
+    this.stepMapper.clearFeatureCaptured();
+    const registerBeforeAllBindings = (): void => {
+      const beforeAllHook = hookScenarios.get('beforeAll');
+      if (!beforeAllHook) return;
+      for (const p of this.capabilityPreconditions(beforeAllHook)) {
+        for (const head of p.boundVars || []) this.stepMapper.registerFeatureCaptured(head);
+      }
+    };
+    if (isParallel) registerBeforeAllBindings();
+
     // Generate background if exists
     let background: string | undefined;
     let backgroundSteps: Array<{ comment?: string; code: string }> | undefined;
@@ -638,6 +679,8 @@ export class CodeGenerator {
       }
     }
 
+    if (!isParallel) registerBeforeAllBindings();
+
     // Generate hook blocks
     const beforeAll = hookScenarios.has('beforeAll')
       ? await this.generateHook(hookScenarios.get('beforeAll')!, 'beforeAll')
@@ -854,6 +897,21 @@ export class CodeGenerator {
       }
       if (iosPart) iosBundleId = iosPart;
     }
+    // SG-W029 — the appium adapter reached codegen with NO usable app package. Both ways in are
+    // silent: a feature with no `Path:` line at all, and a web-style route `Path: /applied-jobs`
+    // that the guard above deliberately rejects. Before this code that combination quietly emitted
+    // Mocha's `before()` — once per FILE — so Background ran once and every scenario shared one
+    // continuous app session, leaking tab/scroll/login state forward; the `@reset:` tier ladder was
+    // dropped along with it, making the tag inert. The generated spec now falls back to the session
+    // capability instead, but the feature file is still missing something it should declare, and
+    // the run throws if wdio.conf cannot supply it either — so it is reported, not assumed.
+    // A warning rather than an error on SG-W004's reasoning: the run usually still works (wdio.conf
+    // carries the id), and `--strict` already turns the channel non-zero for anyone who wants a gate.
+    if (this.adapter.frameworkName === 'appium' && !appPackage && !iosBundleId) {
+      this.diagnostics.add('SG-W029',
+        `this mobile feature declares no app-package \`Path:\`${feature.path ? ` (\`${feature.path}\` is a web route, not a package)` : ''}, so the compiler cannot name the app to reset between scenarios. The spec now resolves the app id from the session capability (APP_PACKAGE / IOS_BUNDLE_ID in wdio.conf) and THROWS at run time if that is absent too. Declare it on the feature instead: \`Path: com.example.app/.MainActivity\` (or \`<androidPkg>/<activity> | <iosBundleId>\` for a dual-id feature).`,
+        { feature: feature.name });
+    }
 
     // Use adapter to render the complete test file structure
     return this.adapter.renderTestFile({
@@ -916,23 +974,66 @@ export class CodeGenerator {
     });
   }
 
+  /**
+   * Hook block (`@beforeAll` / `@afterEach` / `@afterAll`). Shares prepare/finalize with ordinary
+   * scenarios, so an `@api:` / `@query:` precondition on the hook runs INSIDE it (bind {{name}}) and
+   * the hook's own `{{name.*}}` refs resolve at runtime — a hook used to map only its steps, so
+   * `@beforeAll @api:login` compiled to a beforeAll with no api.call and a testData.get() of nothing.
+   * Not applied to hooks: `@cases` (a hook has no dataset rows) and `@extend` (no base scenario) —
+   * warned and ignored; `@auth:` grouping and the mock epilogue are scenario-only. `@concurrent:N`
+   * IS valid: the api capability reads it off the same tags.
+   *
+   * Failure collection: a failing hook skips every test in its describe, so one run must report
+   * EVERY failed check, not just the first. The hook template wraps each mapped step in try/catch:
+   * an assertion step (effective keyword Then) records its failure and lets the next step run; an
+   * action step (Given/When) records it and fails the hook right there, since the steps after it
+   * would run on state the failed action never produced. The block ends with a guard that fails once
+   * with the full list. `expect.soft` is not an option here — a soft failure marks the owning test,
+   * and a hook has none.
+   */
   private async generateHook(
     scenario: ParsedScenario,
     hookType: 'beforeAll' | 'afterEach' | 'afterAll'
   ): Promise<string> {
-    const steps: Array<{ comment?: string; code: string }> = [];
-    for (const step of scenario.steps) {
+    const unsupported = scenario.tags.filter((t) => t.startsWith('@cases:') || t.startsWith('@extend:'));
+    for (const tag of unsupported) {
+      console.warn(`⚠ @${hookType} hook "${scenario.name}": ${tag} is not supported on hooks — ignored`);
+    }
+    const hookScenario: ParsedScenario = {
+      ...scenario,
+      tags: scenario.tags.filter((t) => !unsupported.includes(t)),
+      extendsName: undefined,
+    };
+    const { preconditions } = this.prepareScenarioBody(hookScenario, hookScenario.steps);
+
+    const steps: HookStep[] = [];
+    let effectiveKeyword = 'Given'; // And/But inherit the last Given/When/Then
+    for (const step of hookScenario.steps) {
+      const keyword = step.keyword.trim();
+      if (keyword === 'Given' || keyword === 'When' || keyword === 'Then') effectiveKeyword = keyword;
       const mapped = await Promise.resolve(this.stepMapper.mapStep(step));
+      // A step whose code declares a top-level binding (`const frame = …`, `let tableRow = …`) is read
+      // by the steps AFTER it — a try/catch would scope the binding away from them. Such a step runs
+      // unwrapped and throws on failure exactly as before.
+      if (/^(const|let|var)\s/m.test(mapped.code)) {
+        steps.push({ comment: mapped.comment, code: this.indentCode(mapped.code, 4) });
+        continue;
+      }
       steps.push({
         comment: mapped.comment,
-        code: this.indentCode(mapped.code, 4),
+        code: this.indentCode(mapped.code, 6),
+        wrap: true,
+        stopOnFailure: effectiveKeyword !== 'Then',
+        label: JSON.stringify(mapped.comment || step.text || 'hook step'),
       });
     }
+    this.finalizeScenarioBody(steps, preconditions);
+    const collect = steps.some((s) => s.wrap);
 
     const renderMap = {
-      beforeAll: () => this.adapter.renderBeforeAll({ steps }),
-      afterEach: () => this.adapter.renderAfterEach({ steps }),
-      afterAll: () => this.adapter.renderAfterAll({ steps }),
+      beforeAll: () => this.adapter.renderBeforeAll({ steps, collect }),
+      afterEach: () => this.adapter.renderAfterEach({ steps, collect }),
+      afterAll: () => this.adapter.renderAfterAll({ steps, collect }),
     };
     return renderMap[hookType]();
   }
@@ -952,6 +1053,63 @@ export class CodeGenerator {
     ].join('\n');
   }
 
+  /**
+   * Scenario-body preparation shared by ordinary scenarios and hook blocks — runs BEFORE the steps
+   * are mapped (the step mapper reads what it sets): scenario context, `@cases` row-column capture,
+   * and the capability preconditions (`@api:<name>` / `@query:<name>` → bind {{name}}) whose bound
+   * `{{name.*}}` refs exist only at runtime, so they are registered as captured and compile to a
+   * runtime get() instead of a compile-time YAML lookup that would fail. Pair with
+   * finalizeScenarioBody(), which prepends the preconditions once the steps are mapped.
+   */
+  private prepareScenarioBody(
+    scenario: ParsedScenario,
+    stepsToMap: ParsedStep[],
+  ): { preconditions: CapabilityPrecondition[]; casesDataset?: string } {
+    this.stepMapper.setScenarioContext(stepsToMap);
+
+    // Data-driven (@cases): the scenario's {{col}} refs are dataset *row columns* that
+    // exist only at runtime — register them as captured so they resolve to a runtime
+    // get() (→ rowData.get) instead of compile-time YAML lookup.
+    const casesTag = scenario.tags.find((t) => t.startsWith('@cases:'));
+    const casesDataset = casesTag ? casesTag.slice('@cases:'.length).trim() : undefined;
+    if (casesDataset) {
+      const refs = new Set<string>();
+      for (const st of stepsToMap) {
+        for (const m of (st.text || '').matchAll(/\{\{\s*([\w.]+)\s*\}\}/g)) refs.add(m[1]);
+      }
+      for (const r of refs) this.stepMapper.registerCaptured(r);
+    }
+
+    const preconditions = this.capabilityPreconditions(scenario);
+    const boundVars = preconditions.flatMap((p) => p.boundVars || []);
+    if (boundVars.length) {
+      for (const st of stepsToMap) {
+        for (const mt of (st.text || '').matchAll(/\{\{\s*([^}]+?)\s*\}\}/g)) {
+          const head = mt[1].split(/[.[]/)[0];
+          if (boundVars.includes(head)) this.stepMapper.registerCaptured(mt[1]);
+        }
+      }
+    }
+    return { preconditions, casesDataset };
+  }
+
+  /**
+   * Capability preconditions run BEFORE the body's own steps — prepend them (indented) once the
+   * steps are mapped. Second half of the prepareScenarioBody() pair.
+   */
+  private finalizeScenarioBody(steps: Array<{ comment?: string; code: string }>, preconditions: CapabilityPrecondition[]): void {
+    if (preconditions.length) {
+      steps.unshift(...preconditions.map((p) => ({ comment: p.comment, code: this.indentCode(p.code, 4) })));
+    }
+  }
+
+  /**
+   * Step-boundary trace (#673): scenario name → the ordered step-comment texts emitted for it.
+   * Read by script-check to attribute emitted code to steps structurally; see the populating
+   * site in generateScenario for why comment adjacency cannot do the job.
+   */
+  readonly stepTrace = new Map<string, string[]>();
+
   private async generateScenario(
     scenario: ParsedScenario,
     hasBackground: boolean,
@@ -983,35 +1141,7 @@ export class CodeGenerator {
       warnMultipleAuthTags(scenario.tags, `scenario '${scenario.name}'`);
     }
     
-    // Set scenario context for path variable resolution (full merged list)
-    this.stepMapper.setScenarioContext(stepsToMap);
-
-    // Data-driven (@cases): the scenario's {{col}} refs are dataset *row columns* that
-    // exist only at runtime — register them as captured so they resolve to a runtime
-    // get() (→ rowData.get) instead of compile-time YAML lookup.
-    const casesTag = scenario.tags.find((t) => t.startsWith('@cases:'));
-    const casesDataset = casesTag ? casesTag.slice('@cases:'.length).trim() : undefined;
-    if (casesDataset) {
-      const refs = new Set<string>();
-      for (const st of stepsToMap) {
-        for (const m of (st.text || '').matchAll(/\{\{\s*([\w.]+)\s*\}\}/g)) refs.add(m[1]);
-      }
-      for (const r of refs) this.stepMapper.registerCaptured(r);
-    }
-
-    // Capability preconditions (db `@query:<name>` → bind {{name}}) are owned by the capability via
-    // the SPI. Their bound `{{name.*}}` vars exist only at runtime → register them as captured so
-    // they resolve to a runtime get() instead of a compile-time YAML lookup that would fail.
-    const preconditions = this.capabilityPreconditions(scenario);
-    const boundVars = preconditions.flatMap((p) => p.boundVars || []);
-    if (boundVars.length) {
-      for (const st of stepsToMap) {
-        for (const mt of (st.text || '').matchAll(/\{\{\s*([^}]+?)\s*\}\}/g)) {
-          const head = mt[1].split(/[.[]/)[0];
-          if (boundVars.includes(head)) this.stepMapper.registerCaptured(mt[1]);
-        }
-      }
-    }
+    const { preconditions, casesDataset } = this.prepareScenarioBody(scenario, stepsToMap);
 
     const steps: Array<{ comment?: string; code: string }> = [];
 
@@ -1042,11 +1172,7 @@ export class CodeGenerator {
       }
     }
 
-    // Capability preconditions (db `@query:<name>` / api `@api:<name>` → bind {{name}}; computed
-    // above) run BEFORE the scenario's own steps — prepend them, indenting the capability statements.
-    if (preconditions.length) {
-      steps.unshift(...preconditions.map((p) => ({ comment: p.comment, code: this.indentCode(p.code, 4) })));
-    }
+    this.finalizeScenarioBody(steps, preconditions);
 
     // Mock scenario epilogue. (a) EVERY path: the fail-on-unmocked verdict — the guard
     // records+aborts unmatched requests (it must not throw inside a route handler:
@@ -1076,6 +1202,15 @@ export class CodeGenerator {
     const tags = formatPassThroughTags(extractPassThroughTags(scenario.tags, featureTags), this.adapter.frameworkName);
 
     // Use adapter to render scenario
+    // #673 — record which `//` lines of this scenario are STEP markers, in order. A generated
+    // spec has no textual way to tell a step comment from a template body comment (both land at
+    // the same indent), so script-check attributed code to steps by comment ADJACENCY: any two
+    // adjacent comments gave the first one an empty region → a false hollow BYPASS. Three shipped
+    // templates emit consecutive `//` lines (user-login-todo 6, clear-database 4,
+    // alert-text-assertion 2), as do `// [from @steps:…]` headers, so the check fired on sungen's
+    // own output. The trace makes the attribution structural instead of positional.
+    this.stepTrace.set(scenario.name, steps.map((s) => s.comment).filter((c): c is string => !!c));
+
     const rendered = this.adapter.renderScenario({
       scenarioName: scenario.name,
       steps,