@sun-asterisk/sungen 3.2.24 → 3.2.25

package/src/generators/test-generator/utils/runtime-data-transformer.ts

@@ -1,3 +1,5 @@
+import { scanSegments, type Segment } from './js-literal-scanner';
+
 /**
  * Wire format of a runtime test-data marker: `__SUNGEN_TD$<key>$__`.
  *
@@ -14,12 +16,12 @@
  * swallowed one `_` of the `___` run and decoding produced `get('code_')` plus
  * a detached `ACCESS_TOKEN`. `$` is also identifier-safe — the whole marker
  * still parses as ONE bare JS token, so it survives the bare-identifier
- * (numeric) positions Pass 3 handles.
+ * (numeric) positions the code context handles.
  *
- * Single source of truth: every pass and every whole-literal probe below is
- * built from these constants. Invariant: every marker producer goes through
- * DataResolver.encodeMarker and every consumer through this module — a
- * drifting hand-copied char class is what let the suffix bug hide.
+ * Single source of truth: every context below is built from these constants.
+ * Invariant: every marker producer goes through DataResolver.encodeMarker and
+ * every consumer through this module — a drifting hand-copied char class is what
+ * let the suffix bug hide.
  */
 const MARKER_KEY = '[A-Za-z0-9_-]+';
 // Templates that embed a value into a regex literal run it through the escapeRegex
@@ -27,100 +29,148 @@ const MARKER_KEY = '[A-Za-z0-9_-]+';
 // arrive here spelled `__SUNGEN_TD\$key\$__`. `\\\\?` accepts that optional backslash
 // before each delimiter; the replacement consumes it, so no escape leaks to output.
 const DELIM = '\\\\?\\$';
-/** Marker with no capture group — for "contains a marker" positions inside bigger regexes. */
+/** Marker with no capture group — for "contains a marker" probes. */
 const MARKER = `__SUNGEN_TD${DELIM}${MARKER_KEY}${DELIM}__`;
 /** Marker capturing the encoded key. */
 const MARKER_CAP = `__SUNGEN_TD${DELIM}(${MARKER_KEY})${DELIM}__`;
 
 const MARKER_PATTERN = new RegExp(MARKER);
-// Pass 0: full-line // comments carrying a marker (anchored — see pass comment).
-const RE_COMMENT_LINE = new RegExp(`^(\\s*)\\/\\/(.*)${MARKER_CAP}(.*)$`, 'gm');
-// Pass 1: a quoted string literal containing at least one marker. Covers ', " and
-// backtick containers; `\\.` lets an ESCAPED quote (`'it\'s {{x}}'`) sit inside the
-// body instead of terminating the literal early. The single-char branch excludes `\`
-// so every backslash is consumed by exactly ONE branch — an ambiguous `(?!\1).`
-// alternative enumerates 2^n segmentations when a marker-less escape-heavy literal
-// (escapeQuotes output: multi-line Flutter content-desc) fails to match, hanging
-// the generate run. `\n` exclusion just makes the dot's no-newline behavior explicit.
-const RE_STRING_LITERAL = new RegExp('([\'"`])((?:\\\\.|(?!\\1)[^\\\\\\n])*?' + MARKER + '(?:\\\\.|(?!\\1)[^\\\\\\n])*)\\1', 'g');
-// Pass 2: a single-line regex literal containing at least one marker.
-const RE_REGEX_LITERAL = new RegExp(`\\/((?:[^/\\\\\\n]|\\\\.)*?${MARKER}(?:[^/\\\\\\n]|\\\\.)*)\\/([gimsuy]*)`, 'g');
-// Whole-literal probe: the body is EXACTLY one marker (bare accessor call, no template).
+/** Whole-literal probe: the body is EXACTLY one marker (bare accessor call, no template). */
 const RE_WHOLE_MARKER = new RegExp(`^${MARKER_CAP}$`);
-// Every marker occurrence, capturing the key (Pass 3 + interpolation).
+/** Every marker occurrence, capturing the key. */
 const RE_MARKER_G = new RegExp(MARKER_CAP, 'g');
 
 /**
  * Replace __SUNGEN_TD$…$__ markers with testData.get() calls in generated code.
- * Four passes: comments, string literals, regex literals, then bare identifiers.
+ *
+ * The code is scanned ONCE into literal/regex/comment/code segments and each
+ * segment is rewritten for the context it is actually in. This replaced four
+ * independent global-regex passes whose ordering was the defect: the string pass
+ * ran first and, finding no marker inside a genuine literal, re-matched from that
+ * literal's CLOSING quote — pairing it with the OPENING quote of the next literal
+ * and rewriting the regex literal between them into a broken backtick template
+ * (`getByText('Tìm thấy`)` … `state: `visible' })`, a .spec.ts that would not
+ * parse at all). See js-literal-scanner.ts for the full field report.
  */
 export function transformToRuntimeData(code: string, accessor: string = 'testData'): string {
-  // Pass 0: Comments — replace markers in // comments with decoded key name.
-  // Prevents Pass 2 from misinterpreting // comment markers as regex delimiters.
-  // ANCHORED to line start (^\s*//) so a `//` INSIDE a string literal on a code line
-  // — e.g. a URL `https://careerforum.aki-inc.jp/` in a selector name — is NOT mistaken
-  // for a comment. Before this anchor, such a URL preceding a marker on the same line
-  // made Pass 0 strip the marker to its bare key, so Pass 1 never wrapped it in
-  // testData.get() (silent: `toHaveAttribute('href', 'official_site_url')`). Generated
-  // comments are always full-line, so anchoring loses nothing.
-  code = code.replace(
-    RE_COMMENT_LINE,
-    (_, indent, before, enc, after) => `${indent}//${before}${decodeKey(enc)}${after}`
-  );
-
-  // Pass 1: String literal context — a literal may carry SEVERAL markers
-  // ('/{{code}}/car-search?{{prefill}}' compiles to two markers in ONE literal).
-  // Match the whole quoted literal that contains at least one marker, then
-  // interpolate EVERY marker inside it. The old shape (one marker + lazy
-  // prefix/suffix) swallowed trailing markers into its suffix verbatim; they
-  // escaped the quote context (the literal had become a backtick template) and
-  // Pass 3's numeric catch-all emitted them as literal
-  // `Number(testData.get(...))` TEXT inside the template — a compiling spec
-  // navigating to a garbage URL.
-  // 'marker'          → testData.get('key')
-  // 'a__m1__b__m2__c' → `a${testData.get('k1')}b${testData.get('k2')}c`
-  code = code.replace(
-    RE_STRING_LITERAL,
-    (_, _quote, body) => {
-      const whole = RE_WHOLE_MARKER.exec(body);
-      if (whole) return `${accessor}.get('${decodeKey(whole[1])}')`;
-      return `\`${interpolateMarkers(body, accessor)}\``;
-    }
-  );
+  if (!MARKER_PATTERN.test(code)) return code;
+  return scanSegments(code).map((seg) => transformSegment(seg, accessor)).join('');
+}
 
-  // Pass 2: Regex literal context — /…$marker$…/ → new RegExp(`…`). Same
-  // several-markers-per-literal rule as Pass 1 (/{{min}}-{{max}} items/).
-  // Only matches within a single line (no newlines in the body).
-  code = code.replace(
-    RE_REGEX_LITERAL,
-    (_, body, flags) => {
-      const flagStr = flags ? `, '${flags}'` : '';
-      const whole = RE_WHOLE_MARKER.exec(body);
-      if (whole) return `new RegExp(${accessor}.get('${decodeKey(whole[1])}')${flagStr})`;
-      return `new RegExp(\`${interpolateMarkers(body, accessor)}\`${flagStr})`;
-    }
-  );
+export function hasRuntimeDataMarkers(code: string): boolean {
+  return MARKER_PATTERN.test(code);
+}
 
-  // Pass 3: Bare-identifier context — any marker left after the string/regex passes
-  // sits as a bare token in a numeric position (e.g. `toHaveCount(__marker__)` from the
-  // table/list count templates). testData.get() returns a string, so coerce with Number().
-  code = code.replace(
-    RE_MARKER_G,
-    (_, enc) => `Number(${accessor}.get('${decodeKey(enc)}'))`
-  );
+function transformSegment(seg: Segment, accessor: string): string {
+  if (!MARKER_PATTERN.test(seg.text)) return seg.text;
+  switch (seg.kind) {
+    // Decode to the plain key: a marker in a comment documents the ref, it is not code.
+    case 'comment':
+      return seg.text.replace(RE_MARKER_G, (_, enc) => decodeKey(enc));
+    case 'string':
+      return transformStringLiteral(seg.text, accessor);
+    case 'regex':
+      return transformRegexLiteral(seg.text, accessor);
+    // Bare-token position (e.g. `toHaveCount(__marker__)` from the table/list count
+    // templates). testData.get() returns a string, so coerce with Number().
+    case 'code':
+      return seg.text.replace(RE_MARKER_G, (_, enc) => `Number(${accessor}.get('${decodeKey(enc)}'))`);
+  }
+}
 
-  return code;
+/**
+ * 'marker'          → testData.get('key')
+ * 'a__m1__b__m2__c' → `a${testData.get('k1')}b${testData.get('k2')}c`
+ *
+ * A literal may carry SEVERAL markers ('/{{code}}/car-search?{{prefill}}' compiles
+ * to two markers in ONE literal), so every marker inside it is interpolated.
+ */
+function transformStringLiteral(text: string, accessor: string): string {
+  const quote = text[0];
+  const body = text.slice(1, -1);
+  const whole = RE_WHOLE_MARKER.exec(body);
+  if (whole) return `${accessor}.get('${decodeKey(whole[1])}')`;
+  return `\`${interpolateMarkers(escapeForTemplate(body, quote === '`'), accessor)}\``;
 }
 
-export function hasRuntimeDataMarkers(code: string): boolean {
-  return MARKER_PATTERN.test(code);
+/**
+ * /…$marker$…/flags → new RegExp(`…`, 'flags'). Same several-markers rule as above.
+ *
+ * Two regex-only twists on top of the string path:
+ * - The runtime VALUE is literal text (test-data holds data, not patterns), so every
+ *   accessor is wrapped in the runtime escapeRegExp helper — a value containing
+ *   `( [ $ . * +` must not throw a SyntaxError or silently widen the match. The helper
+ *   lives in the synced specs/regex-escape.ts; the generator imports it when the
+ *   transformed body references it. Templates that intend PATTERN semantics (attribute
+ *   `pattern:`) emit a string container instead of a regex literal, so they skip this.
+ * - Marker-less SEGMENTS get their backslashes doubled for the template context: regex
+ *   source text like a hand-written `\s*` (or escapeRegex output `\)`) means one thing
+ *   in a /…/ literal but loses its backslash when the template cooks one escape level —
+ *   the constructed RegExp would read `s*` / a bare `)`. Segments are escaped AFTER the
+ *   markers are cut out, so an escapeRegex-spelled marker delimiter (`\$`) is never
+ *   double-escaped into something the marker regex can no longer see.
+ */
+function transformRegexLiteral(text: string, accessor: string): string {
+  // Flags never contain `/`, so the last slash always closes the pattern.
+  const close = text.lastIndexOf('/');
+  const body = text.slice(1, close);
+  const flags = text.slice(close + 1);
+  const flagStr = flags ? `, '${flags}'` : '';
+  const whole = RE_WHOLE_MARKER.exec(body);
+  if (whole) return `new RegExp(escapeRegExp(${accessor}.get('${decodeKey(whole[1])}'))${flagStr})`;
+  return `new RegExp(\`${interpolateMarkersInRegexBody(body, accessor)}\`${flagStr})`;
 }
 
 function decodeKey(encoded: string): string {
   return encoded.replace(/_D_/g, '.');
 }
 
-/** Replace every marker in a literal's body with a `${accessor.get('key')}` interpolation. */
+/** Replace every marker in a body with a `${accessor.get('key')}` interpolation. */
 function interpolateMarkers(body: string, accessor: string): string {
   return body.replace(RE_MARKER_G, (_, enc) => `\${${accessor}.get('${decodeKey(enc)}')}`);
 }
+
+/**
+ * Regex-body variant: markers are cut out FIRST, each accessor is wrapped in the
+ * runtime escapeRegExp helper, and only the marker-less segments between them are
+ * re-escaped for the template context (backslashes doubled, backtick/`${` neutralized).
+ */
+function interpolateMarkersInRegexBody(body: string, accessor: string): string {
+  let out = '';
+  let last = 0;
+  for (const m of body.matchAll(RE_MARKER_G)) {
+    out += escapeRegexSegmentForTemplate(body.slice(last, m.index!)) +
+      `\${escapeRegExp(${accessor}.get('${decodeKey(m[1])}'))}`;
+    last = m.index! + m[0].length;
+  }
+  return out + escapeRegexSegmentForTemplate(body.slice(last));
+}
+
+/**
+ * Regex pattern text moving into a template literal: the template layer cooks one
+ * level of escapes BEFORE RegExp ever sees the string, so `\)` arrives as a bare `)`
+ * (SyntaxError: unmatched paren) and `\.` as a match-anything dot. Double the
+ * backslashes and neutralize the template's own metacharacters so the constructed
+ * RegExp source equals the original pattern text.
+ */
+const escapeRegexSegmentForTemplate = (segment: string): string =>
+  segment.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+
+/**
+ * Both rewrites move a body into a backtick template, where a raw backtick or `${`
+ * would be read as syntax rather than text — a `'…'` selector value or a regex
+ * pattern is allowed to contain either (escapeQuotes/escapeRegex escape neither).
+ * Escape before interpolating so the `${…}` this module inserts is the only live one.
+ * An already-backtick container needs no pass: its body was valid template text.
+ *
+ * PRECONDITION: the body must already have its backslashes DOUBLED — which every caller
+ * satisfies, because every dynamic value reaches a literal through escapeQuotes or
+ * escapeRegex (template-engine.ts) and both double `\` before anything else. An unpaired
+ * backslash immediately before a backtick would make the pass below emit `\\\``, i.e. an
+ * escaped backslash followed by a LIVE backtick, ending the template early. If you
+ * hand-write a backslash into a .hbs template, keep it paired.
+ */
+function escapeForTemplate(body: string, alreadyTemplate: boolean): string {
+  if (alreadyTemplate) return body;
+  return body.replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+}

package/src/generators/test-generator/utils/selector-resolver.ts

@@ -229,6 +229,24 @@ export class SelectorResolver {
    * - Legacy format: "login:email_field" or "login.email_field" (with screen prefix)
    */
   resolveSelector(selectorRef: string, featureName?: string, elementType?: string, nth?: number): ResolvedSelector {
+    // A [Reference] is a selectors.yaml KEY, looked up verbatim (generateKey only lowercases and
+    // normalizes whitespace) — it is never interpolated. Embedding a {{var}} in it is therefore
+    // unsupported, and silence was the harmful part: with no matching entry the ref fell through
+    // to auto-infer and produced getByRole(..., { name: '{{var}}' }) — an accessible name that can
+    // never match — so the run failed far from the cause. Fail here instead, naming the two
+    // supported ways to target dynamic text. Browser-storage keys legitimately embed vars but are
+    // not selectors and never reach this method (see driver-ui storage-patterns).
+    const templateVarInRef = /\{\{\s*([^}]+?)\s*\}\}/.exec(selectorRef);
+    if (templateVarInRef) {
+      throw new Error(
+        `Selector reference "[${selectorRef}]" embeds a template variable ({{${templateVarInRef[1]}}}). ` +
+        `A [Reference] is a selectors.yaml key and is matched verbatim, not interpolated. ` +
+        `To target text that varies (locale, @cases column), keep the reference static and put the ` +
+        `variable in the entry instead — e.g. "confirm answer": { type: role, value: button, name: "{{${templateVarInRef[1]}}}" } ` +
+        `used as [Confirm Answer] button. To pick an element by its text inside a container, use ` +
+        `\`with {{${templateVarInRef[1]}}}\` (e.g. User click [Answer List] item with {{${templateVarInRef[1]}}}).`
+      );
+    }
     const contextName = featureName || this.featureName;
 
     // Check if it's legacy format (contains : or has dot with screen prefix)
@@ -590,7 +608,9 @@ export class SelectorResolver {
       });
     }
 
-    // If type is 'locator', use locator field (or value as fallback) as the CSS locator directly
+    // If type is 'locator', use locator field (or value as fallback) as the CSS locator directly.
+    // `exact` travels along: a locator LIST filtered by a test-data value (hasText) matches by
+    // substring by default, and `exact: true` in the YAML opts into the anchored full-text match.
     if (type === 'locator') {
       const locatorValue = locator && locator.trim() ? locator : value;
       return withExtras({
@@ -598,6 +618,7 @@ export class SelectorResolver {
         value: locatorValue,
         locator: locatorValue,
         nth,
+        exact,
       });
     }
 

package/src/generators/test-generator/utils/spec-syntax-check.ts

@@ -0,0 +1,22 @@
+import { parse } from '@babel/parser';
+
+/**
+ * Compiler self-check for emitted spec files.
+ *
+ * Every template and post-processor in the generator assembles TEXT, so a delimiter
+ * bug in any one of them produces a file Playwright cannot parse AT ALL: one
+ * SyntaxError, zero scenarios run, and nothing points at the compiler. That is how the
+ * runtime-data quote-pairing defect reached a user (3.2.23) — `sungen generate` printed
+ * success and the breakage only surfaced a step later, at `npx playwright test`.
+ *
+ * Parsing what we are about to write costs one parse per spec file and makes the
+ * compiler name its own bad output at the moment it makes it (SG-E022).
+ */
+export function findSyntaxError(code: string): string | null {
+  try {
+    parse(code, { sourceType: 'module', plugins: ['typescript'] });
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}

package/src/harness/annotation-overrides.ts

@@ -3,13 +3,18 @@
  *
  * Parses `name(a={{x}},b="lit",c=3)` overrides into a map of JS expressions, e.g.
  * `{ a: "testData.raw('x')", b: "\"lit\"", c: "3" }`. Used by the DB and API capability drivers'
- * precondition codegen; lives in core so both drivers can share it. Gherkin tags carry no whitespace,
- * so values are single tokens — flows thread a prior response via a whole-value ref, e.g.
+ * precondition codegen; lives in core so both drivers can share it. Gherkin tags carry no
+ * whitespace, but a QUOTED value can still embed `{{ref}}` next to static text
+ * (`user_email="pre-{{id}}-x"`) — those interpolate through literalExpr; shipping the braces
+ * verbatim would bind `{{...}}` text as a SQL parameter or POST it in a live request body.
+ * Flows thread a prior response via a whole-value ref, e.g.
  * `@api:get_profile(token={{login.body.token}})`, with the auth scheme declared in the catalog header.
- * A `{{ref}}` override binds into a typed sink (DB query param, JSON request body), so it resolves
- * via `testData.raw()` (native type, still interpolates embedded refs) rather than `get()`
+ * A bare `{{ref}}` override binds into a typed sink (DB query param, JSON request body), so it
+ * resolves via `testData.raw()` (native type, still interpolates embedded refs) rather than `get()`
  * (Gherkin-text stringify) — a numeric override otherwise reaches the DB/API as a JSON string.
  */
+import { literalExpr } from '../generators/test-generator/patterns/expect-patterns';
+
 export function parseQueryOverrides(raw?: string): Record<string, string> {
   const out: Record<string, string> = {};
   if (!raw) return out;
@@ -22,7 +27,7 @@ export function parseQueryOverrides(raw?: string): Record<string, string> {
     const v = val.match(/^\{\{\s*([^}]+?)\s*\}\}$/);
     const q = val.match(/^["'](.*)["']$/);
     if (v) out[key] = `testData.raw(${JSON.stringify(v[1])})`;
-    else if (q) out[key] = JSON.stringify(q[1]);
+    else if (q) out[key] = literalExpr(q[1]);
     else if (/^-?\d+(?:\.\d+)?$/.test(val)) out[key] = val;
     else out[key] = JSON.stringify(val);
   }

package/src/harness/audit.ts

@@ -460,7 +460,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
       }
     }
     // #595 — a viewpoint item naming a browser-level gesture, answered with an in-app control.
-    for (const g of browserGestureSubstitutions(viewpointPath, scenarios).slice(0, 4)) {
+    for (const g of browserGestureSubstitutions(viewpointPath, scenarios, platform).slice(0, 4)) {
       findings.push(`VIEWPOINT-GESTURE-SUBSTITUTED: the viewpoint asks for "${g.gesture}" ("${g.item.slice(0, 80)}…") but the suite exercises an in-app control instead. They are different mechanisms — an app button runs the screen's own re-hydrate logic, browser history does not, and a defect that only shows on history navigation lives in exactly that gap. The step vocabulary has no reload/back step (#593), so defer it with \`@manual\` naming the gesture rather than substituting silently.`);
     }
     // #595 — a flow whose requirement list is a hand restatement of the screen specs it
@@ -643,7 +643,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   if (intent.capabilitySuggestions) {
     // The catalog unit id (`flows/<f>`, `api/<a>`) carries the unit KIND, which gates which
     // drivers can serve it at all.
-    const plan = buildPlan(screenDir, screenName, catalogScreenName);
+    const plan = buildPlan(screenDir, screenName, catalogScreenName, platform);
     if (plan.recommendations.length) {
       const recs = plan.recommendations.map((r) => `\`sungen capability add ${r.driver}\` (automates ${r.count})`).join(' · ');
       findings.push(`CAPABILITY-SUGGESTION: ${plan.capabilityManual} @manual scenario(s) are capability-manual (a driver could automate them) — ${recs}. Recommend-only: nothing is installed automatically; the ${plan.judgmentManual} judgment-manual (M6/M8/M9) correctly stay manual.`);
@@ -651,8 +651,8 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     // Named, not dropped: without this the scenarios read as "nothing could help", and the
     // operator's only clue was an install that dead-ends (#597).
     if (plan.unavailable.length) {
-      const un = plan.unavailable.map((r) => `${r.driver} (would automate ${r.count})`).join(' · ');
-      findings.push(`CAPABILITY-UNAVAILABLE: ${un} — ${plan.unavailable.length === 1 ? 'that driver does' : 'those drivers do'} not support a ${plan.unavailable[0].unitKind} unit, so ${plan.unavailable.length === 1 ? 'it' : 'they'} cannot automate these scenarios here. Do NOT install: the scenarios stay @manual until the driver gains ${plan.unavailable[0].unitKind} support. Automating the same behaviour on the owning SCREEN unit is the available route today.`);
+      const un = plan.unavailable.map((r) => `${r.driver} (would automate ${r.count}) — ${r.why}`).join(' · ');
+      findings.push(`CAPABILITY-UNAVAILABLE: ${un}. Do NOT install: the scenarios stay @manual until the driver gains that support, and installing it buys an install, a dead end and a manual rollback. ${plan.unavailable.some((r) => /no .* support/.test(r.why)) ? 'On this platform, verify the same behaviour through `@api`/`@query` against the real dependency instead.' : 'Automating the same behaviour on the owning SCREEN unit is the available route today.'}`);
     }
   }
   // TQ-11b — automation-ready (pending capability): @requires:<cap> scenarios whose cap isn't enabled.

package/src/harness/capability-plan.ts

@@ -8,7 +8,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { loadDriverCatalog, unitKindOf, driverServesUnit } from './capability';
+import { loadDriverCatalog, driverMeta, unitKindOf, driverServesUnit, driverServesPlatform } from './capability';
 import { readTextFile } from './read-text';
 import { featureFilesFor } from './unit-paths';
 
@@ -197,11 +197,11 @@ export interface CapabilityPlan {
    * dropped: the scenarios stay manual for a reason the operator needs to know, and a silent
    * omission would read as "nothing could help here" (#597).
    */
-  unavailable: { driver: string; reason: string; count: number; unitKind: string }[];
+  unavailable: { driver: string; reason: string; count: number; unitKind: string; why: string }[];
   keep: { code: string; count: number }[];
 }
 
-export function buildPlan(screenDir: string, screenName: string, unitId = screenName): CapabilityPlan {
+export function buildPlan(screenDir: string, screenName: string, unitId = screenName, platform?: string): CapabilityPlan {
   const scenarios = featureFilesFor(screenDir, screenName).flatMap(parseScenarios);
   const catalog = loadDriverCatalog();
   // Recommending a driver that cannot serve this unit KIND costs an install, a dead end and a
@@ -241,14 +241,19 @@ export function buildPlan(screenDir: string, screenName: string, unitId = screen
     }
   }
 
-  const servable = [...recByDriver.entries()].filter(([d]) => driverServesUnit(d, unitKind));
+  // Two axes, same guarantee: a driver must be able to serve this unit KIND and this PLATFORM.
+  const serves = (d: string): boolean => driverServesUnit(d, unitKind) && driverServesPlatform(d, platform);
+  const servable = [...recByDriver.entries()].filter(([d]) => serves(d));
   const unavailable = [...recByDriver.entries()]
-    .filter(([d]) => !driverServesUnit(d, unitKind))
+    .filter(([d]) => !serves(d))
     .map(([driver, v]) => ({
       driver,
       reason: v.reason,
       count: v.scenarios.length,
       unitKind,
+      why: !driverServesUnit(driver, unitKind)
+        ? `does not support a ${unitKind} unit`
+        : `has no ${platform} support (its step patterns are ${(driverMeta(driver)?.platforms ?? []).join('/')}-only)`,
     }))
     .sort((a, b) => b.count - a.count);
   const recommendations = servable

package/src/harness/capability.ts

@@ -81,6 +81,15 @@ export interface DriverMeta {
    * driver on a flow: install, dead end, manual rollback (#597).
    */
   units?: Array<'screen' | 'flow' | 'api'>;
+  /**
+   * Platforms this driver can serve. Absent = all.
+   *
+   * The same guarantee as `units`, on the other axis. Step patterns already gate themselves
+   * (`platforms: ['web']` → SG-W020 at compile time), but the PLANNER did not know, so a mobile
+   * project was still told to install a web-only driver — install, dead end, manual rollback,
+   * exactly as in #597 (#626).
+   */
+  platforms?: string[];
 }
 
 /** The unit kind of a catalog unit id: `flows/<f>` → flow, `api/<a>` → api, else screen. */
@@ -97,6 +106,13 @@ export function driverServesUnit(driverId: string, kind: 'screen' | 'flow' | 'ap
   return !units || units.includes(kind);
 }
 
+/** Can this driver serve that platform? No declared platform on either side → assume yes. */
+export function driverServesPlatform(driverId: string, platform?: string): boolean {
+  const platforms = driverMeta(driverId)?.platforms;
+  if (!platforms || !platform) return true;
+  return platforms.includes(platform.toLowerCase());
+}
+
 export function capabilitiesPath(cwd: string): string {
   return path.join(cwd, 'qa', 'capabilities.yaml');
 }

package/src/harness/catalog/drivers.yaml

@@ -66,6 +66,11 @@ drivers:
     # (mockCatalogPath is hardcoded to that shape), so it cannot serve a flow. Recommending
     # it for one sent an operator through an install, a dead end and a manual rollback (#597).
     units: [screen]
+    # `platforms:` is the same guarantee on the other axis. Absent → every platform.
+    # `mock.install` is Playwright route interception (page.route) and its step patterns already
+    # declare `platforms: ['web']`, so on mobile they compile to SG-W020. The PLANNER did not know
+    # that, so a mobile project was still told to install it — the #597 dead end, one axis over.
+    platforms: [web]
   mail-file:
     kind: capability
     package: "@sungen/driver-mail-file"

package/src/harness/parse.ts

@@ -230,7 +230,11 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
       // assert persisted state — without this they'd be scored `shallow`, penalizing
       // exactly the checks the review encourages. `tab order` is a STRUCTURAL
       // assertion (a data table of focus stops) with the same no-{{ref}} property.
-      if (/\{\{|contains|match data|toHaveText|in (local|session) storage|tab order/i.test(step.text)) hasData = true;
+      // `matches "<format>"` belongs here for the same reason: it carries no {{ref}} because
+      // the contract IS the shape ("Format: yyyy/mm/dd ~ yyyy/mm/dd"), and it is a stricter
+      // check than the value assert it replaces — scoring it shallow would penalize the
+      // stronger assertion.
+      if (/\{\{|contains|match data|matches\s+"|toHaveText|in (local|session) storage|tab order/i.test(step.text)) hasData = true;
     }
   }