@sun-asterisk/sungen 3.2.9 → 3.2.10-beta.11

package/src/generators/test-generator/app-profile.ts

@@ -0,0 +1,185 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import yaml from 'yaml';
+
+/**
+ * App Profile (`qa/app.yaml`) — the per-project BEHAVIOR layer (spec:
+ * docs/spec/sungen_app_profile_spec.md). Three kinds of knowledge live in three files:
+ *   INTENT   → .feature + test-data      (portable across projects)
+ *   IDENTITY → selectors.yaml            (per-screen: WHERE an element is)
+ *   BEHAVIOR → qa/app.yaml               (per-project: HOW this app's UI behaves)
+ *
+ * The file describes the app under test, never the tool (no timeouts/retries/sleeps —
+ * those belong to sungen.config.yaml). One file per project; presets merge in via
+ * `extends:`; per-element `variant:`/`scope:` in selectors.yaml wins over the profile.
+ * No file → the built-in defaults below → pre-profile behavior stays intact.
+ */
+
+export interface AppProfile {
+  version?: number;
+  extends?: string | string[];
+  app?: { ui_library?: string; framework?: string; locales?: string[]; base_locale?: string };
+  widgets?: Record<string, string | { recipe?: string; variant?: string }>;
+  recipes?: Record<string, unknown>;
+  layers?: { portal_roles?: string[] };
+  feedback?: {
+    toast?: { role?: string; named_by?: 'content' | 'label'; stacking?: string };
+    loading?: { indicator?: string };
+    field_error?: { locate?: string; indicator?: string };
+    confirm?: string;
+  };
+  conventions?: Record<string, unknown>;
+  detection?: Record<string, unknown>;
+}
+
+export interface ProfileWarning {
+  code: 'SG-W005' | 'SG-W006';
+  message: string;
+}
+
+export interface ResolvedAppProfile {
+  /** ARIA roles rendered via portal — never wrapped in dialog/landmark scope (issue #465). */
+  portalRoles: string[];
+  /** Roles whose accessible name derives from CONTENT — defaulting name from the Gherkin
+   *  reference can never match (issue #467). */
+  contentNamedRoles: string[];
+  /** widget kind → variant/recipe name, normalized (`select: radix-select`). Per-element
+   *  `variant:` in selectors.yaml overrides this. */
+  widgetVariants: Record<string, string>;
+  /** recipe name → { intent → primitive list } — built-in variant recipes merged under
+   *  project-defined ones (project wins). */
+  recipes: Record<string, Record<string, unknown[]>>;
+  /** Refresh/loading signal for `wait for [T] table to refresh` (feedback.loading.indicator). */
+  loadingIndicator: string;
+  /** Positional-row conventions (`row {{n}}` steps): first row number + whether the header
+   *  counts as a row in getByRole('row') indexing. */
+  tableRowBase: number;
+  tableHeaderIsRow: boolean;
+  /** The merged profile (presets ← project), or null when qa/app.yaml does not exist. */
+  raw: AppProfile | null;
+  warnings: ProfileWarning[];
+}
+
+/** Portal-rendered option layers (Radix/MUI/Headless UI/antd portal to document.body). */
+export const DEFAULT_PORTAL_ROLES = ['option', 'listbox', 'menu', 'menuitem', 'tooltip'];
+
+/** ARIA name-from-content roles (per spec): a `{ name }` filter invented from the Gherkin
+ *  reference text can never match these. */
+export const DEFAULT_CONTENT_NAMED_ROLES = ['status', 'alert', 'log', 'marquee', 'timer'];
+
+/** Default refresh signal — apps that set aria-busy while loading need zero config. */
+export const DEFAULT_LOADING_INDICATOR = '[aria-busy="true"]';
+
+const KNOWN_TOP_KEYS = ['version', 'extends', 'app', 'widgets', 'recipes', 'layers', 'feedback', 'conventions', 'detection'];
+
+/** Reserved preset key: always merged as the base layer (built-in widget recipes ship here). */
+const BUILTIN_PRESET_KEY = 'builtin';
+
+export function defaultAppProfile(presets: Record<string, unknown> = {}): ResolvedAppProfile {
+  return finalizeProfile((presets[BUILTIN_PRESET_KEY] as AppProfile) ?? {}, null, []);
+}
+
+/** Derive the compiler-consumed slices from a merged profile document. */
+function finalizeProfile(merged: AppProfile, raw: AppProfile | null, warnings: ProfileWarning[]): ResolvedAppProfile {
+  const portalRoles = merged.layers?.portal_roles ?? DEFAULT_PORTAL_ROLES;
+  const contentNamed = new Set(DEFAULT_CONTENT_NAMED_ROLES);
+  if (merged.feedback?.toast?.named_by === 'content' && merged.feedback.toast.role) {
+    contentNamed.add(merged.feedback.toast.role);
+  }
+  const widgetVariants: Record<string, string> = {};
+  for (const [kind, v] of Object.entries(merged.widgets ?? {})) {
+    const name = typeof v === 'string' ? v : (v?.recipe ?? v?.variant);
+    if (name) widgetVariants[kind] = name;
+  }
+  const conventions = merged.conventions as { table?: { row_base?: number; header_is_row?: boolean } } | undefined;
+  return {
+    portalRoles,
+    contentNamedRoles: [...contentNamed],
+    widgetVariants,
+    recipes: (merged.recipes ?? {}) as Record<string, Record<string, unknown[]>>,
+    loadingIndicator: merged.feedback?.loading?.indicator ?? DEFAULT_LOADING_INDICATOR,
+    tableRowBase: conventions?.table?.row_base ?? 1,
+    tableHeaderIsRow: conventions?.table?.header_is_row ?? false,
+    raw,
+    warnings,
+  };
+}
+
+/**
+ * Load and resolve `qa/app.yaml`: merge the `extends` preset chain (project wins),
+ * validate top-level keys, and derive the compiler-consumed slices. Never throws on
+ * a bad profile — problems surface as SG-W005/W006 diagnostics, and each slice falls
+ * back to its built-in default.
+ */
+export function loadAppProfile(cwd: string, presets: Record<string, unknown> = {}): ResolvedAppProfile {
+  const warnings: ProfileWarning[] = [];
+  const qaDir = path.join(cwd, 'qa');
+
+  // Per-environment profiles are unsupported BY DESIGN — widget behavior must not differ
+  // between environments (test-data/locale overlays already cover what legitimately does).
+  if (fs.existsSync(qaDir)) {
+    for (const name of fs.readdirSync(qaDir)) {
+      if (/^app\.[^.]+\.ya?ml$/.test(name)) {
+        warnings.push({
+          code: 'SG-W006',
+          message: `qa/${name}: per-environment app profiles are unsupported by design — describe the app once in qa/app.yaml`,
+        });
+      }
+    }
+  }
+
+  const file = path.join(qaDir, 'app.yaml');
+  if (!fs.existsSync(file)) {
+    return { ...defaultAppProfile(presets), warnings };
+  }
+
+  let doc: AppProfile;
+  try {
+    doc = (yaml.parse(fs.readFileSync(file, 'utf-8')) ?? {}) as AppProfile;
+  } catch (e) {
+    warnings.push({ code: 'SG-W005', message: `qa/app.yaml: unparseable YAML (${e instanceof Error ? e.message : e}) — using built-in defaults` });
+    return { ...defaultAppProfile(presets), warnings };
+  }
+
+  for (const key of Object.keys(doc)) {
+    if (!KNOWN_TOP_KEYS.includes(key)) {
+      warnings.push({ code: 'SG-W005', message: `qa/app.yaml: unknown key "${key}" (known: ${KNOWN_TOP_KEYS.join(', ')})` });
+    }
+  }
+
+  // extends: preset chain, merged in order, project file last (narrow beats broad).
+  // The reserved `builtin` preset (built-in widget recipes from driver-ui) is always
+  // the base layer, so per-element `variant: radix-select` works without any extends.
+  const extendNames = doc.extends ? (Array.isArray(doc.extends) ? doc.extends : [doc.extends]) : [];
+  const availableNames = Object.keys(presets).filter((k) => k !== BUILTIN_PRESET_KEY);
+  const chain: AppProfile[] = presets[BUILTIN_PRESET_KEY] ? [presets[BUILTIN_PRESET_KEY] as AppProfile] : [];
+  for (const name of extendNames) {
+    const key = String(name).replace(/^@sungen\/app-/, '');
+    const preset = presets[key] as AppProfile | undefined;
+    if (!preset || key === BUILTIN_PRESET_KEY) {
+      warnings.push({
+        code: 'SG-W005',
+        message: `qa/app.yaml: unknown preset "${name}" in extends (available: ${availableNames.join(', ') || 'none — is the driver that ships it installed?'})`,
+      });
+    } else {
+      chain.push(preset);
+    }
+  }
+  const merged = [...chain, doc].reduce<AppProfile>((acc, layer) => deepMerge(acc, layer) as AppProfile, {});
+
+  return finalizeProfile(merged, merged, warnings);
+}
+
+/** Plain-object deep merge; arrays and scalars replace (a preset's list is a whole answer). */
+function deepMerge(base: unknown, layer: unknown): unknown {
+  if (!isPlainObject(base) || !isPlainObject(layer)) return layer === undefined ? base : layer;
+  const out: Record<string, unknown> = { ...base };
+  for (const [k, v] of Object.entries(layer)) {
+    out[k] = k in out ? deepMerge(out[k], v) : v;
+  }
+  return out;
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}

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

@@ -4,6 +4,7 @@ import { ParsedFeature, ParsedScenario, ParsedStep } from '../gherkin-parser';
 import { StepMapper } from './step-mapper';
 import { TestGeneratorAdapter, adapterRegistry } from './adapters';
 import { transformToRuntimeData } from './utils/runtime-data-transformer';
+import { DiagnosticsCollector } from './diagnostics';
 import { capabilityRegistry } from '../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
 import { readCapabilities } from '../../harness/capability';
@@ -227,10 +228,13 @@ export class CodeGenerator {
   // Steps registry built per feature during generateTestCode(); used by countSteps()
   private stepsRegistry = new Map<string, ParsedScenario>();
 
+  private diagnostics = new DiagnosticsCollector();
+
   constructor(options: { useAI?: boolean; verbose?: boolean; framework?: string; baseURL?: string; screenName?: string; runtimeData?: boolean; flowMode?: boolean } = {}) {
     this.options = options;
     this.screenName = options.screenName;
     this.stepMapper = new StepMapper(options);
+    this.stepMapper.setDiagnostics(this.diagnostics);
     // Get adapter from registry. Platform comes from the caller (resolved from
     // qa/capabilities.yaml); default `web` = the bundled Playwright adapter
     // (back-compat baseline). External platforms (e.g. mobile) are loaded by the
@@ -243,6 +247,11 @@ export class CodeGenerator {
     }
   }
 
+  /** Compile diagnostics collected across all generateTest calls (SG-W001/W002...) */
+  getDiagnostics(): DiagnosticsCollector {
+    return this.diagnostics;
+  }
+
   /**
    * Generate test file from parsed feature
    */

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

@@ -0,0 +1,51 @@
+/**
+ * Compile-time diagnostics — the warning channel for "the compiler knows something
+ * and would otherwise silently discard or invent it" (spec: sungen_app_profile_spec.md §4).
+ *
+ * Codes:
+ *   SG-W001 — step matched no pattern (compiles to a no-op `// TODO` comment)
+ *   SG-W002 — step parsed a {{dataRef}} value but the generated code never uses it
+ *   SG-W003 — `name` filter defaulted from the Gherkin reference on a name-from-content
+ *             role (status/alert/…) — such a filter can never match; opt out with `name: null`
+ *   SG-W005 — qa/app.yaml problem (unknown key, unknown preset, unparseable)
+ *   SG-W006 — qa/app.<env>.yaml found (per-environment profiles are unsupported by design)
+ *   SG-W007 — browser-alert handler step written AFTER an action step: the listener
+ *             registers too late, an earlier dialog auto-dismisses with no error
+ *
+ * Diagnostics never block generation by themselves; `sungen generate --strict`
+ * turns any collected diagnostic into a non-zero exit.
+ */
+
+export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007';
+
+export interface Diagnostic {
+  code: DiagnosticCode;
+  message: string;
+  feature?: string;
+  step?: string;
+}
+
+export class DiagnosticsCollector {
+  private items: Diagnostic[] = [];
+
+  add(code: DiagnosticCode, message: string, context: { feature?: string; step?: string } = {}): void {
+    this.items.push({ code, message, ...context });
+  }
+
+  all(): Diagnostic[] {
+    return this.items;
+  }
+
+  get count(): number {
+    return this.items.length;
+  }
+
+  /** One line per diagnostic, ready for CLI output. */
+  formatLines(): string[] {
+    return this.items.map((d) => {
+      const where = d.feature ? `${d.feature}: ` : '';
+      const step = d.step ? ` — "${d.step}"` : '';
+      return `[${d.code}] ${where}${d.message}${step}`;
+    });
+  }
+}

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

@@ -44,6 +44,18 @@ export interface PatternContext {
   scenarioSteps?: ParsedStep[];
   /** Effective Gherkin keyword (Given/When/Then), resolved from And/But */
   effectiveKeyword?: string;
+  /** App profile (qa/app.yaml merged over presets/defaults) — widget variants, recipes,
+   *  loading indicator, table row conventions. Typed loosely to keep the SPI decoupled;
+   *  the concrete shape is ResolvedAppProfile. */
+  appProfile?: {
+    widgetVariants: Record<string, string>;
+    recipes: Record<string, Record<string, unknown[]>>;
+    loadingIndicator: string;
+    tableRowBase: number;
+    tableHeaderIsRow: boolean;
+    portalRoles: string[];
+    contentNamedRoles: string[];
+  };
 }
 
 /**

package/src/generators/test-generator/recipe-expander.ts

@@ -0,0 +1,129 @@
+/**
+ * Widget-recipe expander (spec: sungen_app_profile_spec.md §3.1 [recipes]).
+ *
+ * A recipe is a LINEAR sequence of closed primitives that describes one widget
+ * intent ("select", "fill", …). Recipes come from `qa/app.yaml` `recipes:` or from
+ * driver-shipped built-ins (the reserved `builtin` preset), selected by the widget's
+ * variant name (per-element `variant:` > profile `widgets.<kind>`).
+ *
+ * This expander holds ZERO framework syntax. It resolves each primitive to a
+ * `{ partial, ...data }` NODE; the actual Playwright code lives in the per-primitive
+ * `recipe-*.hbs` partials, rendered by the template engine via `recipe-sequence.hbs`
+ * (dynamic partial lookup). The only strings it builds are locator/value EXPRESSIONS
+ * (data — the same split every resolver uses when it hands the locator template a value).
+ *
+ * Placeholders: `$trigger` = the resolved widget element; `$value` = the step's data
+ * value (a runtime marker in runtime mode, transformed to testData.get later); `$item`
+ * = the current forEach item. Throws on an unknown primitive/shape — callers fall back
+ * to the generic template.
+ */
+
+export interface RecipeExpandContext {
+  /** Pre-rendered locator code for the widget element (dialog/frame scoping included). */
+  triggerCode: string;
+  /** The step's value — a literal or a __SUNGEN_TD__ runtime marker. */
+  value: string;
+}
+
+/** A render node: the partial name plus the data it interpolates. */
+export interface RecipeNode {
+  partial: string;
+  [key: string]: unknown;
+}
+
+const escape = (s: string): string => String(s).replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+
+export function expandRecipe(primitives: unknown[], ctx: RecipeExpandContext): RecipeNode[] {
+  if (!Array.isArray(primitives) || primitives.length === 0) {
+    throw new Error('recipe intent is not a primitive list');
+  }
+  return primitives.map((p) => expandPrimitive(p, ctx, null));
+}
+
+/** `itemVar` is non-null inside a forEach body — `$item` renders as that identifier. */
+function expandPrimitive(prim: unknown, ctx: RecipeExpandContext, itemVar: string | null): RecipeNode {
+  if (typeof prim !== 'object' || prim === null || Array.isArray(prim)) {
+    throw new Error(`invalid primitive: ${JSON.stringify(prim)}`);
+  }
+  const entries = Object.entries(prim as Record<string, unknown>);
+  if (entries.length !== 1) throw new Error(`a primitive must have exactly one key: ${JSON.stringify(prim)}`);
+  const [kind, arg] = entries[0];
+
+  // Resolve a `$trigger`/css target into a locator EXPRESSION (data for the partial).
+  const targetExpr = (v: unknown): string =>
+    v === '$trigger' ? ctx.triggerCode : `page.locator('${escape(String(v))}')`;
+  // Resolve a `$value`/`$item`/literal into a JS value EXPRESSION (quoted unless $item;
+  // a quoted __SUNGEN_TD__ marker is rewritten to testData.get(...) by the runtime transform).
+  const valueExpr = (v: unknown): string => {
+    if (v === '$item') {
+      if (!itemVar) throw new Error('$item is only valid inside forEach');
+      return itemVar;
+    }
+    const s = v === '$value' ? ctx.value : String(v);
+    return `'${escape(s)}'`;
+  };
+
+  switch (kind) {
+    case 'click':
+      return { partial: 'recipe-click', targetExpr: targetExpr(arg) };
+    case 'hover':
+      return { partial: 'recipe-hover', targetExpr: targetExpr(arg) };
+    case 'type': {
+      const v = typeof arg === 'object' && arg !== null ? (arg as any).value : arg;
+      return { partial: 'recipe-type', valueExpr: valueExpr(v ?? '$value') };
+    }
+    case 'press':
+      return { partial: 'recipe-press', key: escape(String(arg)) };
+    case 'waitFor': {
+      // `waitFor: '<css>'` → wait visible. `waitFor: { target, state }` allows an explicit
+      // state ('attached' | 'visible' | 'hidden' | 'detached'); `attached` covers the AntD
+      // case where a selected chip collapses the input to ~0px (node exists before actionable).
+      const o = (typeof arg === 'object' && arg !== null ? arg : { target: arg }) as Record<string, unknown>;
+      const state = ['attached', 'visible', 'hidden', 'detached'].includes(String(o.state)) ? String(o.state) : 'visible';
+      return { partial: 'recipe-wait-for', targetExpr: targetExpr(o.target), state };
+    }
+    case 'waitForHidden':
+      return { partial: 'recipe-wait-for', targetExpr: targetExpr(arg), state: 'hidden' };
+    case 'scrollIntoView':
+      // Playwright's own actionability scroll (not arbitrary evaluate) — nudges a lazy list
+      // to render+reveal the target before a click. Deterministic, no loop.
+      return { partial: 'recipe-scroll-into-view', targetExpr: targetExpr(arg) };
+    case 'blur':
+      // One bounded el.blur() to dismiss a widget's own overlay (AntD DatePicker panel keeps
+      // pointer-blocking after fill; Escape/force-click are unreliable). No retry loop.
+      return { partial: 'recipe-blur', targetExpr: targetExpr(arg) };
+    case 'clickText': {
+      const o = (typeof arg === 'object' && arg !== null ? arg : { text: arg }) as Record<string, unknown>;
+      const text = valueExpr(o.text ?? '$value');
+      const exact = o.exact === true;
+      // Build the option-locator expression; the partial scrolls it into view then clicks.
+      const expr = o.role
+        ? `page.getByRole('${escape(String(o.role))}', { name: ${text}${exact ? ', exact: true' : ''} })`
+        : `${o.within ? `page.locator('${escape(String(o.within))}')` : 'page'}.getByText(${text}${exact ? ', { exact: true }' : ''}).first()`;
+      return { partial: 'recipe-click-text', targetExpr: expr };
+    }
+    case 'expectText': {
+      const o = (typeof arg === 'object' && arg !== null ? arg : {}) as Record<string, unknown>;
+      return { partial: 'recipe-expect-text', targetExpr: targetExpr(o.locator ?? '$trigger'), valueExpr: valueExpr(o.value ?? '$value') };
+    }
+    case 'expectValue': {
+      const o = (typeof arg === 'object' && arg !== null ? arg : {}) as Record<string, unknown>;
+      return { partial: 'recipe-expect-value', targetExpr: targetExpr(o.locator ?? '$trigger'), valueExpr: valueExpr(o.value ?? '$value') };
+    }
+    case 'forEach': {
+      const o = (typeof arg === 'object' && arg !== null ? arg : {}) as Record<string, unknown>;
+      if (itemVar) throw new Error('nested forEach is not supported');
+      const inner = o.do;
+      if (!Array.isArray(inner) || inner.length === 0) throw new Error('forEach.do must be a primitive list');
+      const source = o.in === '$values' || o.in === undefined ? '$value' : o.in;
+      return {
+        partial: 'recipe-for-each',
+        sourceExpr: valueExpr(source),
+        split: escape(String(o.split ?? '>')),
+        body: inner.map((p) => expandPrimitive(p, ctx, 'item')),
+      };
+    }
+    default:
+      throw new Error(`unknown recipe primitive "${kind}"`);
+  }
+}

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

@@ -4,6 +4,9 @@ import { adapterRegistry } from './adapters';
 import { PatternRegistry, PatternContext } from './patterns';
 import { SelectorResolver } from './utils/selector-resolver';
 import { DataResolver } from './utils/data-resolver';
+import { DiagnosticsCollector } from './diagnostics';
+import { loadAppProfile, ResolvedAppProfile } from './app-profile';
+import { capabilityRegistry } from '../../capabilities/registry';
 
 export interface MappedStep {
   code: string; // Generated Playwright code
@@ -34,6 +37,12 @@ export class StepMapper {
   /** Row scope: when active, column assertions are scoped to this row */
   private inRowScope: boolean = false;
   private rowScopeTable: string = '';
+  /** SG-W007: an action step already ran in this scenario (alert handlers registered after it are too late) */
+  private sawActionStep: boolean = false;
+  /** Compile-time warning channel (SG-W001/W002); optional — absent means silent legacy behavior */
+  private diagnostics?: DiagnosticsCollector;
+  /** App profile (qa/app.yaml merged over presets/defaults) — the per-project BEHAVIOR layer */
+  private appProfile: ResolvedAppProfile;
 
   constructor(options: { verbose?: boolean; baseURL?: string; featureName?: string; screenName?: string; featurePath?: string; runtimeData?: boolean; framework?: string } = {}) {
     this.verbose = options.verbose ?? false;
@@ -51,11 +60,26 @@ export class StepMapper {
     this.selectorResolver = new SelectorResolver(undefined, options.screenName);
     this.dataResolver = new DataResolver(undefined, options.screenName, options.runtimeData);
 
+    // App profile (qa/app.yaml) — loaded after PatternRegistry so capability discovery has
+    // populated the preset registry (driver-ui ships native/radix/antd). Missing file →
+    // built-in defaults → pre-profile behavior.
+    this.appProfile = loadAppProfile(process.cwd(), capabilityRegistry.appProfilePresets());
+    this.templateEngine.setPersistentContext({ portalRoles: this.appProfile.portalRoles });
+    this.selectorResolver.setContentNamedRoles(this.appProfile.contentNamedRoles);
+
     if (this.verbose) {
       console.log(`  [StepMapper] ${this.patternRegistry.getPatternCount()} patterns loaded`);
     }
   }
 
+  /** Attach the compile-diagnostics collector (owned by CodeGenerator) */
+  setDiagnostics(collector: DiagnosticsCollector): void {
+    this.diagnostics = collector;
+    this.selectorResolver.setDiagnostics(collector);
+    // Flush profile-load warnings (SG-W005/W006) gathered before the collector existed.
+    for (const w of this.appProfile.warnings) collector.add(w.code, w.message);
+  }
+
   /**
    * Set feature context for data and selector resolution
    */
@@ -92,6 +116,7 @@ export class StepMapper {
     this.inFrameScope = false;
     this.inRowScope = false;
     this.rowScopeTable = '';
+    this.sawActionStep = false;
     this.lastPrimaryKeyword = 'Given';
     this.dataResolver.clearCaptured(); // captured vars are scenario-scoped
     this.templateEngine.resetBaseContext();
@@ -119,6 +144,23 @@ export class StepMapper {
       this.lastPrimaryKeyword = keyword;
     }
 
+    // SG-W007 — a two-step-form browser-alert handler (`click [OK] alert`) written AFTER
+    // an action step registers its page.once('dialog') listener too late: a dialog
+    // triggered by the earlier action auto-dismisses with no error (issue #472).
+    // Fix: move the alert step BEFORE the trigger, or use the compound form
+    // `click [X] button and accept [OK] alert`.
+    const isAlertHandlerStep = step.elementType === 'alert' &&
+      /\b(click|clicks|fill|fills)\b/.test(step.text) &&
+      !/\band\s+(accept|accepts|dismiss|dismisses)\b/i.test(step.text);
+    if (isAlertHandlerStep && this.sawActionStep) {
+      this.diagnostics?.add('SG-W007',
+        'browser-alert handler registered AFTER an action step — a dialog triggered earlier auto-dismisses silently. Move the alert step before the trigger, or use `click [X] button and accept [OK] alert`',
+        { feature: this.featureName, step: step.text });
+    } else if (!isAlertHandlerStep &&
+      /\b(click|clicks|fill|fills|select|selects|press|presses|check|checks|uncheck|unchecks|drag|drags)\b/.test(step.text)) {
+      this.sawActionStep = true;
+    }
+
     // Frame scope directives — intercept before pattern matching
     if (/\bswitch(?:es)?\s+to\b/i.test(step.text) &&
         (step.elementType === 'frame' || step.elementType === 'iframe')) {
@@ -215,16 +257,46 @@ export class StepMapper {
       if (this.verbose) {
         console.log(`  ✓ Pattern matched: ${step.text.substring(0, 50)}...`);
       }
+      this.checkDataRefConsumed(step, mappedStep);
       return mappedStep;
     }
 
     // No pattern matched - return TODO comment
+    this.diagnostics?.add('SG-W001', 'step matched no pattern — compiled to a no-op // TODO comment', {
+      feature: this.featureName,
+      step: step.text,
+    });
     return {
       code: `// TODO: Implement step: ${step.text}`,
       comment: `Unrecognized step pattern: ${step.text}`,
     };
   }
 
+  /**
+   * SG-W002 — a step carried a parsed {{dataRef}} but the matched pattern's generated
+   * code never uses it (neither the runtime marker, the ${ref} fallback, nor the
+   * inline-resolved value). This is the class of bug where `with {{v}}` silently
+   * disappears from the output (e.g. issue #464). Warning-only: loose containment
+   * checks err on the side of NOT flagging.
+   */
+  private checkDataRefConsumed(step: ParsedStep, mapped: MappedStep): void {
+    if (!step.dataRef || !this.diagnostics) return;
+    const code = mapped.code || '';
+    if (code.includes(DataResolver.encodeMarker(step.dataRef))) return; // runtime marker
+    if (code.includes(`\${${step.dataRef}}`)) return;                    // unresolved fallback
+    if (code.includes(step.dataRef)) return;                             // testData.set('ref'), comments
+    try {
+      const value = this.dataResolver.resolveData(step.dataRef, this.featureName);
+      if (value && (code.includes(value) || code.includes(value.replace(/'/g, "\\'")))) return; // inline mode
+    } catch {
+      return; // unresolvable ref → other errors surface elsewhere; don't double-report
+    }
+    this.diagnostics.add('SG-W002', `parsed {{${step.dataRef}}} but the generated code does not use it`, {
+      feature: this.featureName,
+      step: step.text,
+    });
+  }
+
   /**
    * Generate column assertion scoped to the current row.
    * Uses columns config for exact cell targeting (nth), or filter fallback.
@@ -296,6 +368,7 @@ export class StepMapper {
       selectorResolver: this.selectorResolver,
       dataResolver: this.dataResolver,
       renderLocator: (resolved) => this.templateEngine.renderStep('locator', resolved),
+      appProfile: this.appProfile,
       baseURL: this.baseURL,
       featureName: this.featureName,
       screenName: this.screenName,

package/src/generators/test-generator/template-engine.ts

@@ -7,6 +7,8 @@ export class TemplateEngine {
   private templatesDir: string;
   private stepsTemplatesDir: string;
   private baseContext: Record<string, any> = {};
+  /** Per-project context that survives scenario resets (e.g. app-profile portalRoles) */
+  private persistentContext: Record<string, any> = {};
 
   constructor(templatesDir: string) {
     this.templatesDir = templatesDir;
@@ -127,7 +129,17 @@ export class TemplateEngine {
     Handlebars.registerHelper('pageRoot', function(this: any) {
       // Frame scope takes precedence (frame > dialog > page)
       if (this.inFrame) return 'frame';
-      if (!this.inDialog) return 'page';
+      // `scope: dialog` on the selector entry is the explicit opt-IN sentinel — the
+      // element is dialog-rooted even if its role is portal-exempt (issue #465).
+      const explicitDialog = this.scope === 'dialog';
+      if (!this.inDialog && !explicitDialog) return 'page';
+      // Portal-rendered roles (Radix/MUI/Headless UI/antd render option/menu/tooltip
+      // layers onto document.body) live OUTSIDE the dialog's DOM subtree — wrapping
+      // them in the dialog root guarantees a timeout. List comes from the app profile
+      // (qa/app.yaml layers.portal_roles), default DEFAULT_PORTAL_ROLES.
+      if (!explicitDialog && this.role && Array.isArray(this.portalRoles) && this.portalRoles.includes(this.role)) {
+        return 'page';
+      }
       const partial = Handlebars.partials['dialog-root'];
       if (partial) {
         const fn = typeof partial === 'string' ? Handlebars.compile(partial) : partial;
@@ -152,6 +164,14 @@ export class TemplateEngine {
       Handlebars.registerPartial('locator-base', locatorBaseContent);
     }
 
+    // Register has-text-value partial — the ONE place that renders a .filter({ hasText })
+    // value, so action templates cannot drift from the exact/anchored-regex standard the
+    // assertion templates follow (issue #466).
+    const hasTextValuePath = path.join(this.stepsTemplatesDir, 'partials', 'has-text-value.hbs');
+    if (fs.existsSync(hasTextValuePath)) {
+      Handlebars.registerPartial('has-text-value', fs.readFileSync(hasTextValuePath, 'utf-8'));
+    }
+
     // Register locator strategy partials
     const strategiesDir = path.join(this.stepsTemplatesDir, 'partials', 'locator-strategies');
     if (fs.existsSync(strategiesDir)) {
@@ -246,9 +266,15 @@ export class TemplateEngine {
     this.baseContext = { ...this.baseContext, ...ctx };
   }
 
-  /** Reset base context (e.g., on new scenario) */
+  /** Context that survives resetBaseContext (per-project facts, e.g. app-profile portalRoles) */
+  setPersistentContext(ctx: Record<string, any>): void {
+    this.persistentContext = { ...this.persistentContext, ...ctx };
+    this.baseContext = { ...this.baseContext, ...ctx };
+  }
+
+  /** Reset base context (e.g., on new scenario) — persistent (per-project) context stays */
   resetBaseContext(): void {
-    this.baseContext = {};
+    this.baseContext = { ...this.persistentContext };
   }
 
   renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean }): string {