@sun-asterisk/sungen 3.2.28 → 3.2.30

package/dist/orchestrator/templates/specs-url-assert.ts

@@ -2,7 +2,8 @@
 /**
  * Sungen URL assertion helper — auto-generated into specs/url-assert.ts. DO NOT EDIT.
  *
- * Every Then-side URL assertion (`see [X] page`, `is on [X] page`) compiles to one call here.
+ * Every URL step compiles to one call here: the Then-side assertions (`see [X] page`,
+ * `is on [X] page`) to `expectPage`, and `wait for [X] page` to `waitForPage`.
  *
  * Why a helper and not an inline predicate. The predicate used to be emitted inline into every
  * spec, so each correction to what "the URL matches" MEANS was a breaking change for every
@@ -28,6 +29,16 @@ export interface UrlExpectation {
    * against a full URL.
    */
   pathname: RegExp;
+  /**
+   * Anchored hostname pattern, emitted ONLY when the page selector's `value` is an ABSOLUTE URL
+   * (`https://app.example.com/reception/:id`) — a destination on a different host from the suite's
+   * baseURL. Absent means "whatever host we are on", which is what a relative page value says.
+   *
+   * It is a SEPARATE field rather than part of `pathname` because the two are read off different
+   * properties of the parsed URL: `u.hostname` never appears in `u.pathname`. One concatenated
+   * regex only worked while the match ran unanchored over the whole URL string (#677).
+   */
+  hostname?: RegExp;
   /**
    * The `with {{v}}` value, raw from test-data: '?q=1' · '/vi/search?q=1' · '#tab' · ''.
    * `undefined` means the step declared nothing, which is itself an assertion — see below.
@@ -83,6 +94,15 @@ function decodedPath(pathname: string): string {
   }
 }
 
+/**
+ * Is the URL at the expected LOCATION — right host, right path? The half every URL step shares.
+ * The Then-side assertion goes on to judge the query; the wait stops here (see `waitForPage`).
+ */
+function locationMatches(pathname: RegExp, hostname: RegExp | undefined, u: URL): boolean {
+  if (hostname && !hostname.test(u.hostname)) return false;
+  return pathname.test(u.pathname) || pathname.test(decodedPath(u.pathname));
+}
+
 /**
  * Build the predicate for `expect(page).toHaveURL(...)`.
  *
@@ -94,9 +114,9 @@ function decodedPath(pathname: string): string {
  *                      A declared fragment is asserted too; a declared value carrying no query
  *                      at all constrains the path only (the compiler warns: SG-W014).
  */
-export function urlMatches({ pathname, declared, dataRef }: UrlExpectation): (u: URL) => boolean {
+export function urlMatches({ pathname, hostname, declared, dataRef }: UrlExpectation): (u: URL) => boolean {
   return (u: URL): boolean => {
-    if (!pathname.test(u.pathname) && !pathname.test(decodedPath(u.pathname))) return false;
+    if (!locationMatches(pathname, hostname, u)) return false;
 
     // `dataRef`, not `declared`, decides which rule applies. Both "the step declared nothing" and
     // "the step declared {{v}} but the key resolved to nothing at runtime" arrive here as
@@ -135,38 +155,43 @@ export function urlMatches({ pathname, declared, dataRef }: UrlExpectation): (u:
   };
 }
 
+/** What `settleAndHold` needs of a page — Playwright's `Page` satisfies it; so does a test fake. */
+type SettleablePage = {
+  url(): string;
+  waitForLoadState(state: 'networkidle', opts?: { timeout?: number }): Promise<void>;
+};
+
+/** The two runtime knobs, shared by both URL steps. */
+interface SettleOpts { settleMs?: number; networkIdleMs?: number }
+
 /**
- * `toHaveURL` is a polling assertion: it passes on the FIRST sample that matches. A client-side
- * router pushes the destination URL before the route guard or the API has answered, so a user
- * with no permission is "on" `/items/detail` for a few hundred milliseconds — long enough for
- * the assertion to sample it, pass, and end the test green — and is then bounced to `/forbidden`
- * with no assertion left to see it. A real project shipped a permission matrix on that oracle;
- * the 403s were found by hand (#662).
+ * A URL that MATCHES is not a page the user is still on. A client-side router pushes the
+ * destination URL before the route guard or the API has answered, so a user with no permission is
+ * "on" `/items/detail` for a few hundred milliseconds — long enough for a polling assertion to
+ * sample it and pass, or for a `waitForURL` to resolve — and is then bounced to `/forbidden` with
+ * nothing left watching. A real project shipped a permission matrix on that oracle; the 403s were
+ * found by hand (#662).
  *
- * `expectPage` is the page oracle `see [X] page` compiles to now. Arriving is not enough: the URL
- * has to be STILL matching once the page has settled.
- *   1. arrive   — the same predicate `toHaveURL` always used;
- *   2. settle   — wait for network to go quiet (bounded: an app that polls forever must not hang
- *                 the test, so a timeout here is not a failure);
- *   3. hold     — sample the URL over a settle window; the moment it stops matching, fail and
- *                 NAME where it went, because that destination is the finding;
- *   4. re-assert — the arrival predicate, once more, on the settled page.
+ * So both URL steps go through this: having arrived,
+ *   1. settle    — wait for network to go quiet (bounded: an app that polls forever must not hang
+ *                  the test, so a timeout here is not a failure);
+ *   2. hold      — sample the URL over a settle window; the moment it stops matching, fail and
+ *                  NAME where it went, because that destination is the finding.
+ * The caller decides what arriving meant and what to do afterwards.
  *
  * `SUNGEN_URL_SETTLE_MS` (default 1000) is the hold window; `SUNGEN_URL_NETWORKIDLE_MS` (default
- * 3000) bounds step 2. Both are runtime knobs, so a slow environment is a config change, not a
+ * 3000) bounds step 1. Both are runtime knobs, so a slow environment is a config change, not a
  * regenerate.
  */
-export async function expectPage(
-  page: { url(): string; waitForLoadState(state: 'networkidle', opts?: { timeout?: number }): Promise<void> },
-  expectation: UrlExpectation,
-  opts: { settleMs?: number; networkIdleMs?: number; assertUrl?: (matches: (u: URL) => boolean) => Promise<void> } = {},
+async function settleAndHold(
+  page: SettleablePage,
+  matches: (u: URL) => boolean,
+  opts: SettleOpts,
+  label: string,
+  consequence: string,
 ): Promise<void> {
   const settleMs = opts.settleMs ?? Number(process.env.SUNGEN_URL_SETTLE_MS ?? 1000);
   const networkIdleMs = opts.networkIdleMs ?? Number(process.env.SUNGEN_URL_NETWORKIDLE_MS ?? 3000);
-  const matches = urlMatches(expectation);
-  const assertUrl = opts.assertUrl ?? (async (m: (u: URL) => boolean) => { await expect(page as unknown as Page).toHaveURL(m); });
-
-  await assertUrl(matches);
   const arrivedAt = page.url();
 
   await page.waitForLoadState('networkidle', { timeout: networkIdleMs }).catch(() => undefined);
@@ -176,13 +201,61 @@ export async function expectPage(
     const now = page.url();
     if (!matches(new URL(now))) {
       throw new Error(
-        `page assertion: reached ${arrivedAt} and then left for ${now} after ${Date.now() - started}ms — `
+        `${label}: reached ${arrivedAt} and then left for ${now} after ${Date.now() - started}ms — `
         + 'a route guard, an error boundary or a redirect moved the user away after the URL had already '
-        + 'matched. The page the test asserted is not the page the user ended on.',
+        + `matched. ${consequence}`,
       );
     }
     await new Promise((r) => setTimeout(r, 50));
   }
+}
+
+/**
+ * `expectPage` is the page oracle `see [X] page` / `is on [X] page` compile to. Arriving is not
+ * enough: the URL has to be STILL matching once the page has settled.
+ *   1. arrive    — the same predicate `toHaveURL` always used;
+ *   2. settle + hold — see `settleAndHold`;
+ *   3. re-assert — the arrival predicate, once more, on the settled page.
+ */
+export async function expectPage(
+  page: SettleablePage,
+  expectation: UrlExpectation,
+  opts: SettleOpts & { assertUrl?: (matches: (u: URL) => boolean) => Promise<void> } = {},
+): Promise<void> {
+  const matches = urlMatches(expectation);
+  const assertUrl = opts.assertUrl ?? (async (m: (u: URL) => boolean) => { await expect(page as unknown as Page).toHaveURL(m); });
 
   await assertUrl(matches);
+  await settleAndHold(page, matches, opts, 'page assertion',
+    'The page the test asserted is not the page the user ended on.');
+  await assertUrl(matches);
+}
+
+/**
+ * `waitForPage` is what `When User wait for [X] page` compiles to (#677).
+ *
+ * A bare `page.waitForURL(/…/)` resolves on the first URL sample that matches — the transient URL
+ * the router pushed before its guard decided. The wait then returned, and every step AFTER it ran
+ * against a page mid-redirect, so their failures pointed at the wrong thing. It was also the third
+ * hand-rolled copy of "does this URL match", drifting from the pair #662 consolidated here.
+ *
+ * Where this deliberately DIFFERS from `expectPage`: the query is not constrained. A Then-side page
+ * assertion is an oracle, so a bare page must be bare — `/vi/search` fails on `/vi/search?x=1`. A
+ * wait is not an oracle: `wait for [Results] page` after submitting a search legitimately lands on
+ * `/results?q=abc`, and reddening there would assert something the step never said. Prove the query
+ * with the `Then User see [Results] page with {{v}}` that follows.
+ */
+export async function waitForPage(
+  page: SettleablePage & { waitForURL(url: (u: URL) => boolean, opts?: { timeout?: number }): Promise<void> },
+  expectation: UrlExpectation,
+  opts: SettleOpts & { timeout?: number; waitUrl?: (matches: (u: URL) => boolean) => Promise<void> } = {},
+): Promise<void> {
+  const { pathname, hostname } = expectation;
+  const matches = (u: URL): boolean => locationMatches(pathname, hostname, u);
+  // Playwright's own navigation timeout governs the arrival; only the hold is sungen's.
+  const arrive = opts.waitUrl ?? (async (m: (u: URL) => boolean) => { await page.waitForURL(m, { timeout: opts.timeout }); });
+
+  await arrive(matches);
+  await settleAndHold(page, matches, opts, 'page wait',
+    'The steps after this wait would have run against a page the user is already being moved off.');
 }

package/dist/orchestrator/templates/wdio.conf.ts

@@ -28,6 +28,26 @@ import * as path from 'node:path';
 import { execSync } from 'node:child_process';
 import PwShapeReporter from './specs/reporters/pw-shape-reporter';
 
+/**
+ * Failure-evidence output. `test-results/` is already gitignored — screenshots and page sources
+ * of a real app routinely contain live data (a signed-in email, a token rendered on screen), so
+ * this directory must never become committable.
+ */
+const EVIDENCE_ROOT = path.join('test-results', 'mobile');
+/** A full logcat is unbounded; only the tail is ever diagnostic. */
+const EVIDENCE_LOG_TAIL_LINES = 500;
+/** ~2 MB of accessibility tree is already far more than anyone reads. */
+const EVIDENCE_PAGE_SOURCE_MAX = 2_000_000;
+
+/** Filesystem-safe path segment from a feature/test title. */
+function evidenceSlug(s: string): string {
+  return String(s)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80) || 'unnamed';
+}
+
 /**
  * Auto-select MOBILE specs and classify each by its target OS (dual-target routing).
  *
@@ -404,9 +424,93 @@ export const config: WebdriverIO.Config = {
   // Connectivity self-heal (#615): onPrepare heals a device wedged by a previous KILLED run
   // (its onComplete never fired) before the session starts; onComplete restores after this run,
   // pass or fail. Both run in the launcher process, so they fire even when the worker/session died.
-  onPrepare: () => { restoreConnectivity('onPrepare'); setShowTouches('onPrepare'); },
+  onPrepare: () => { restoreConnectivity('onPrepare'); setShowTouches('onPrepare'); fs.mkdirSync(EVIDENCE_ROOT, { recursive: true }); },
   onComplete: () => { restoreConnectivity('onComplete'); setShowTouches('onComplete'); },
 
+  /**
+   * Failure evidence. A mobile failure used to reach the report as a single error string — no
+   * image, no tree, no device log — which makes triaging a native UI almost impossible.
+   *
+   * Only runs on failure, so a passing suite pays nothing. Each capture is wrapped SEPARATELY:
+   * one unavailable command (a Flutter page source that blows the buffer, a driver with no log
+   * endpoint) must not cost us the other two, and nothing in here may convert an already-failing
+   * test into a different error.
+   */
+  afterTest: async (
+    test: { title?: string; parent?: string },
+    _context: unknown,
+    result: { passed?: boolean },
+  ): Promise<void> => {
+    if (result?.passed) return;
+
+    // Opt-out for constrained runners (a device farm billing per artifact, a CI box with no disk).
+    // A feature tagged @screenshot:on-failure declares its evidence essential and overrides it.
+    const forced = (globalThis as Record<string, unknown>).__sungenForceEvidence === true;
+    if (!forced && process.env.SUNGEN_MOBILE_EVIDENCE === 'off') return;
+
+    const feature = test?.parent || 'Tests';
+    const title = test?.title || 'test';
+    const dir = path.join(EVIDENCE_ROOT, evidenceSlug(feature), evidenceSlug(title));
+    const files: Array<{ name: string; path: string; contentType: string }> = [];
+
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+    } catch (e) {
+      console.warn(`[sungen] could not create evidence dir ${dir}: ${(e as Error).message}`);
+      return;
+    }
+
+    // 1. Screenshot — the single most useful artifact for a UI failure.
+    try {
+      const shot = path.join(dir, 'screenshot.png');
+      await driver.saveScreenshot(shot);
+      files.push({ name: 'screenshot', path: shot, contentType: 'image/png' });
+    } catch (e) {
+      console.warn(`[sungen] screenshot capture failed: ${(e as Error).message}`);
+    }
+
+    // 2. Page source — the accessibility tree, i.e. WHY a selector did not match. Capped: a
+    //    Flutter/RecyclerView tree can run to tens of MB and there is no value in writing that.
+    try {
+      const src = await driver.getPageSource();
+      const capped = src.length > EVIDENCE_PAGE_SOURCE_MAX
+        ? `${src.slice(0, EVIDENCE_PAGE_SOURCE_MAX)}\n<!-- [sungen] truncated at ${EVIDENCE_PAGE_SOURCE_MAX} of ${src.length} chars -->`
+        : src;
+      if (src.length > EVIDENCE_PAGE_SOURCE_MAX) {
+        console.warn(`[sungen] page source ${src.length} chars — truncated to ${EVIDENCE_PAGE_SOURCE_MAX}`);
+      }
+      const out = path.join(dir, 'page-source.xml');
+      fs.writeFileSync(out, capped, 'utf-8');
+      files.push({ name: 'page-source', path: out, contentType: 'application/xml' });
+    } catch (e) {
+      console.warn(`[sungen] page source capture failed: ${(e as Error).message}`);
+    }
+
+    // 3. Device log — logcat on Android, syslog on iOS. Tail only: a full logcat is unbounded.
+    try {
+      const logType = driver.isIOS ? 'syslog' : 'logcat';
+      const entries = (await driver.getLogs(logType)) as Array<{ message?: string } | string>;
+      const lines = entries.map((l) => (typeof l === 'string' ? l : l?.message || '')).filter(Boolean);
+      const tail = lines.slice(-EVIDENCE_LOG_TAIL_LINES).join('\n');
+      const out = path.join(dir, 'device.log');
+      fs.writeFileSync(out, tail, 'utf-8');
+      files.push({ name: 'device-log', path: out, contentType: 'text/plain' });
+    } catch (e) {
+      console.warn(`[sungen] device log capture failed: ${(e as Error).message}`);
+    }
+
+    // Hand the paths to the reporter so they land in the result's `attachments`. Resolved off
+    // globalThis, not imported — see the note in specs/reporters/pw-shape-reporter.ts.
+    try {
+      const attach = (globalThis as Record<string, unknown>).__sungenAttachEvidence;
+      if (typeof attach === 'function') {
+        (attach as (f: string, t: string, files: typeof files) => void)(feature, title, files);
+      }
+    } catch (e) {
+      console.warn(`[sungen] could not register evidence with the reporter: ${(e as Error).message}`);
+    }
+  },
+
   // iOS + locale: XCUITest's `noReset:false` does NOT actually clear the app's data container
   // (verified live 2026-06-11) — a Flutter app that persisted its language on a previous launch keeps
   // it and ignores the new device locale, so the i18n run asserts the wrong language. Wipe the app

package/dist/utils/selector-types.d.ts

@@ -1,7 +1,49 @@
 /**
  * Valid selector types used across scaffold generator, selector resolver, and validator.
  * Single source of truth — import this instead of hardcoding.
+ *
+ * The list is partitioned deliberately. A type is either a LOCATOR STRATEGY (the resolver's
+ * strategy switch turns it into a Playwright/WDIO locator) or a NON-STRATEGY declaration (the
+ * entry describes something other than how to find an element, and a reader downstream of the
+ * resolver consumes it). A type that is in neither set but is still accepted as valid is drift:
+ * it reaches the switch's `default:` and resolves as `getByPlaceholder('<whatever value held>')`,
+ * a selector that cannot match. `upload` sat in exactly that gap — valid, documented, and
+ * silently mis-resolved (issue #690).
+ *
+ * Keep the partition total. `tests/codegen/selector-type-dispatch.run.ts` fails if a new member
+ * of VALID_SELECTOR_TYPES is classified into neither half, or if a strategy type stops being
+ * dispatched and starts resolving as a placeholder.
  */
-export declare const VALID_SELECTOR_TYPES: readonly ["placeholder", "role", "testid", "label", "text", "page", "column", "locator", "id", "upload", "frame", "table", "accessibility-id", "xpath", "android-uiautomator", "ios-predicate", "css"];
+/**
+ * Types the resolver turns into a locator. Every member MUST be dispatched in
+ * `SelectorResolver.resolveFromEntry` — either by a `case` in its strategy switch or by an
+ * early return above it (`locator` and `upload` share one). The contract is on the RESOLVED
+ * STRATEGY, not on the syntax used to produce it.
+ */
+export declare const STRATEGY_SELECTOR_TYPES: readonly ["placeholder", "role", "testid", "label", "text", "locator", "id", "upload", "accessibility-id", "xpath", "android-uiautomator", "ios-predicate", "css"];
+/**
+ * Types that declare something OTHER than a locator strategy, so they have no `case` by design.
+ * Each is read after resolution via `ResolvedSelector.selectorType`, or by the pattern that owns
+ * the step, which reads the entry's fields directly:
+ *
+ *   page   — `value` is a URL path, not a locator. The page assertion reads `selectorType`
+ *            AFTER resolving (see StepMapper.checkPageStepFallback), so this type must
+ *            pass through the switch rather than throw.
+ *   table  — the table patterns read `columns` (StepMapper's column-index lookup), `rows` (the
+ *            row templates, backed by SG-W016) and `pagination` (the paginate step, #712) off
+ *            the entry. `pagination` was the NOTE that used to sit here: documented, plumbed,
+ *            and read by nothing — the same drift shape as #690, one level down. It has a
+ *            consumer now, and SG-W004 is the gate that makes the next such field fail a check
+ *            rather than wait to be grepped.
+ *   column — addressed through its table's `columns` map, never resolved standalone.
+ *   frame  — consumed by the frame-enter/exit steps, which need the raw iframe selector.
+ *
+ * Reaching the strategy switch is legitimate for these; the placeholder fallback there is inert
+ * because no consumer reads `strategy` for them.
+ */
+export declare const NON_STRATEGY_SELECTOR_TYPES: readonly ["page", "column", "frame", "table"];
+export declare const VALID_SELECTOR_TYPES: readonly ["placeholder", "role", "testid", "label", "text", "locator", "id", "upload", "accessibility-id", "xpath", "android-uiautomator", "ios-predicate", "css", "page", "column", "frame", "table"];
+export type StrategySelectorType = (typeof STRATEGY_SELECTOR_TYPES)[number];
+export type NonStrategySelectorType = (typeof NON_STRATEGY_SELECTOR_TYPES)[number];
 export type SelectorType = (typeof VALID_SELECTOR_TYPES)[number];
 //# sourceMappingURL=selector-types.d.ts.map

package/dist/utils/selector-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"selector-types.d.ts","sourceRoot":"","sources":["../../src/utils/selector-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,oBAAoB,wMAmBvB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC"}
+{"version":3,"file":"selector-types.d.ts","sourceRoot":"","sources":["../../src/utils/selector-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,oKAe1B,CAAC;AAEX;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,2BAA2B,+CAK9B,CAAC;AAEX,eAAO,MAAM,oBAAoB,wMAGvB,CAAC;AAEX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC5E,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AACnF,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/utils/selector-types.js

@@ -1,23 +1,37 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.VALID_SELECTOR_TYPES = void 0;
 /**
  * Valid selector types used across scaffold generator, selector resolver, and validator.
  * Single source of truth — import this instead of hardcoding.
+ *
+ * The list is partitioned deliberately. A type is either a LOCATOR STRATEGY (the resolver's
+ * strategy switch turns it into a Playwright/WDIO locator) or a NON-STRATEGY declaration (the
+ * entry describes something other than how to find an element, and a reader downstream of the
+ * resolver consumes it). A type that is in neither set but is still accepted as valid is drift:
+ * it reaches the switch's `default:` and resolves as `getByPlaceholder('<whatever value held>')`,
+ * a selector that cannot match. `upload` sat in exactly that gap — valid, documented, and
+ * silently mis-resolved (issue #690).
+ *
+ * Keep the partition total. `tests/codegen/selector-type-dispatch.run.ts` fails if a new member
+ * of VALID_SELECTOR_TYPES is classified into neither half, or if a strategy type stops being
+ * dispatched and starts resolving as a placeholder.
  */
-exports.VALID_SELECTOR_TYPES = [
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALID_SELECTOR_TYPES = exports.NON_STRATEGY_SELECTOR_TYPES = exports.STRATEGY_SELECTOR_TYPES = void 0;
+/**
+ * Types the resolver turns into a locator. Every member MUST be dispatched in
+ * `SelectorResolver.resolveFromEntry` — either by a `case` in its strategy switch or by an
+ * early return above it (`locator` and `upload` share one). The contract is on the RESOLVED
+ * STRATEGY, not on the syntax used to produce it.
+ */
+exports.STRATEGY_SELECTOR_TYPES = [
     'placeholder',
     'role',
     'testid',
     'label',
     'text',
-    'page',
-    'column',
     'locator',
     'id',
     'upload',
-    'frame',
-    'table',
     // === Mobile (Appium) strategies — resolved by the appium adapter (MOB-3) ===
     'accessibility-id', // cross-platform — Android content-desc / iOS accessibilityIdentifier
     'xpath', // cross-platform, last resort
@@ -25,4 +39,34 @@ exports.VALID_SELECTOR_TYPES = [
     'ios-predicate', // iOS only — NSPredicate strings
     'css', // hybrid WebView only — CSS inside a WEBVIEW context (after `switch to [X] frame`)
 ];
+/**
+ * Types that declare something OTHER than a locator strategy, so they have no `case` by design.
+ * Each is read after resolution via `ResolvedSelector.selectorType`, or by the pattern that owns
+ * the step, which reads the entry's fields directly:
+ *
+ *   page   — `value` is a URL path, not a locator. The page assertion reads `selectorType`
+ *            AFTER resolving (see StepMapper.checkPageStepFallback), so this type must
+ *            pass through the switch rather than throw.
+ *   table  — the table patterns read `columns` (StepMapper's column-index lookup), `rows` (the
+ *            row templates, backed by SG-W016) and `pagination` (the paginate step, #712) off
+ *            the entry. `pagination` was the NOTE that used to sit here: documented, plumbed,
+ *            and read by nothing — the same drift shape as #690, one level down. It has a
+ *            consumer now, and SG-W004 is the gate that makes the next such field fail a check
+ *            rather than wait to be grepped.
+ *   column — addressed through its table's `columns` map, never resolved standalone.
+ *   frame  — consumed by the frame-enter/exit steps, which need the raw iframe selector.
+ *
+ * Reaching the strategy switch is legitimate for these; the placeholder fallback there is inert
+ * because no consumer reads `strategy` for them.
+ */
+exports.NON_STRATEGY_SELECTOR_TYPES = [
+    'page',
+    'column',
+    'frame',
+    'table',
+];
+exports.VALID_SELECTOR_TYPES = [
+    ...exports.STRATEGY_SELECTOR_TYPES,
+    ...exports.NON_STRATEGY_SELECTOR_TYPES,
+];
 //# sourceMappingURL=selector-types.js.map

package/dist/utils/selector-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"selector-types.js","sourceRoot":"","sources":["../../src/utils/selector-types.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACU,QAAA,oBAAoB,GAAG;IAClC,aAAa;IACb,MAAM;IACN,QAAQ;IACR,OAAO;IACP,MAAM;IACN,MAAM;IACN,QAAQ;IACR,SAAS;IACT,IAAI;IACJ,QAAQ;IACR,OAAO;IACP,OAAO;IACP,8EAA8E;IAC9E,kBAAkB,EAAK,sEAAsE;IAC7F,OAAO,EAAgB,8BAA8B;IACrD,qBAAqB,EAAE,wCAAwC;IAC/D,eAAe,EAAQ,iCAAiC;IACxD,KAAK,EAAkB,mFAAmF;CAClG,CAAC"}
+{"version":3,"file":"selector-types.js","sourceRoot":"","sources":["../../src/utils/selector-types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAEH;;;;;GAKG;AACU,QAAA,uBAAuB,GAAG;IACrC,aAAa;IACb,MAAM;IACN,QAAQ;IACR,OAAO;IACP,MAAM;IACN,SAAS;IACT,IAAI;IACJ,QAAQ;IACR,8EAA8E;IAC9E,kBAAkB,EAAK,sEAAsE;IAC7F,OAAO,EAAgB,8BAA8B;IACrD,qBAAqB,EAAE,wCAAwC;IAC/D,eAAe,EAAQ,iCAAiC;IACxD,KAAK,EAAkB,mFAAmF;CAClG,CAAC;AAEX;;;;;;;;;;;;;;;;;;;GAmBG;AACU,QAAA,2BAA2B,GAAG;IACzC,MAAM;IACN,QAAQ;IACR,OAAO;IACP,OAAO;CACC,CAAC;AAEE,QAAA,oBAAoB,GAAG;IAClC,GAAG,+BAAuB;IAC1B,GAAG,mCAA2B;CACtB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.28",
+  "version": "3.2.30",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -40,8 +40,8 @@
     "@babel/types": "^7.28.5",
     "@cucumber/gherkin": "^37.0.0",
     "@cucumber/messages": "^31.0.0",
-    "@sungen/driver-data-factory": "3.2.28",
-    "@sungen/driver-ui": "3.2.28",
+    "@sungen/driver-data-factory": "3.2.30",
+    "@sungen/driver-ui": "3.2.30",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",