@sungen/driver-ui 3.2.28 → 3.2.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-ui",
-  "version": "3.2.28",
+  "version": "3.2.30",
   "description": "Sungen UI capability (Playwright) — step patterns, viewpoint gate, and phase hooks. Plugs into @sun-asterisk/sungen via the capability SPI.",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -13,7 +13,7 @@
   "author": "eqe team (engineer & quality) — Sun Asterisk",
   "license": "MIT",
   "dependencies": {
-    "@sun-asterisk/sungen": "3.2.28"
+    "@sun-asterisk/sungen": "3.2.30"
   },
   "peerDependencies": {
     "@playwright/test": "^1.57.0"

package/src/index.ts

@@ -36,6 +36,7 @@ import { keyboardPatterns } from './patterns/keyboard-patterns';
 import { scrollPatterns } from './patterns/scroll-patterns';
 import { scopePatterns } from './patterns/scope-patterns';
 import { tablePatterns } from './patterns/table-patterns';
+import { tablePaginationPatterns } from './patterns/table-pagination-patterns';
 import { capturePatterns } from './patterns/capture-patterns';
 import { storagePatterns } from './patterns/storage-patterns';
 import { focusPatterns } from './patterns/focus-patterns';
@@ -109,6 +110,7 @@ export function register(registry: CapabilityRegistry): void {
       ...scrollPatterns,
       ...scopePatterns,
       ...tablePatterns,
+      ...tablePaginationPatterns,
       ...capturePatterns,
       ...storagePatterns,
       ...focusPatterns,

package/src/patterns/assertion-patterns.ts

@@ -3,6 +3,7 @@ import { formatToRegexLiteral } from '@sun-asterisk/sungen';
 import { StepPattern, StepTemplateData, expandRecipe } from '@sun-asterisk/sungen';
 import { LIST_MEMBER_ROLES } from '@sun-asterisk/sungen';
 import { pathToRegexSource } from '../utils/url-path-regex';
+import { resolveColumnHeaderName } from '../utils/column-header';
 
 /**
  * Assertion patterns: visibility, text content, state, attributes
@@ -30,6 +31,19 @@ function qualifiedState(text: string): { assertion: string; label: string; probe
  *  locator strict-mode-fails. The role-strategy counterpart is LIST_MEMBER_ROLES. */
 const LOCATOR_LIST_MEMBER_TYPES = new Set(['item', 'listitem', 'option', 'cell']);
 
+/** Resolved strategies that pin a node by IDENTITY rather than by the text it renders. A
+ *  `see [X] label with {{v}}` step honours these as real locators and asserts their text (#666).
+ *
+ *  The omissions are deliberate, not an oversight: `text` finds the node by the very caption the
+ *  label pattern is about, so honouring it would assert the caption contains the value; `label`
+ *  (getByLabel) and `placeholder` resolve the labelled CONTROL, whose content is a `value`, not
+ *  text; `role` names an element through its accessible name, which for a caption IS the caption.
+ *  Each of those keeps the caption+value text reading. */
+const IDENTITY_STRATEGIES = new Set([
+  'testid', 'id', 'css', 'locator', 'xpath',
+  'accessibility-id', 'android-uiautomator', 'ios-predicate',
+]);
+
 /**
  * INVARIANT — a pattern whose generated code accounts for a trailing state clause (`… is hidden`)
  * MUST declare it in `states`. Undeclared, the clause reaches SG-E021 and the step compiles to a
@@ -68,6 +82,9 @@ export const assertionPatterns: StepPattern[] = [
   // Column cell assertion: "see [Department] column 1 with {{value}}" -> check table cell text
   {
     name: 'column-cell-assertion',
+    platforms: ['web'],
+    platformAlternative:
+      'HTML table roles have no native equivalent - assert the row element itself by accessibility-id (`Then User see [Row 2 Amount] has text {{v}}`), or tag the scenario @manual',
     matcher: (step: ParsedStep) =>
       (step.text.includes('should see') || step.text.match(/\b(see|sees)\s+\[/)) &&
       !!step.selectorRef &&
@@ -86,10 +103,15 @@ export const assertionPatterns: StepPattern[] = [
       // Create a safe variable name from column name
       const columnIndexVar = `colIndex${step.selectorRef!.replace(/[^a-zA-Z0-9]/g, '')}`;
 
+      // The header TEXT this template matches on — both the visibility assertion and the
+      // findIndex scan — is declarable; the bracket label is only the fallback (issue #674).
+      // No table is named by this step form, so only the `<col>--columnheader` entry applies.
+      const columnName = resolveColumnHeaderName(step.selectorRef!, context);
+
       return {
         templateName: 'column-cell-assertion',
         data: {
-          columnName: step.selectorRef,
+          columnName,
           rowNth,
           columnIndexVar,
           dataValue,
@@ -344,16 +366,26 @@ export const assertionPatterns: StepPattern[] = [
       // aria-selected — their state is `checked`; other targets probe at runtime.
       let stateAssertion = state.assertion;
       let selectedProbe = state.probe === true;
+      // A checked/unchecked assertion must NOT compile to toBeChecked() — it throws
+      // "Not a checkbox or radio button" on an aria-pressed toggle exactly as the action side did
+      // (#675). Flag it so the template can route it through expectCheckedState instead, which
+      // reads the same signals setCheckedState drives.
+      let isCheckedAssertion = state.label === 'checked' || state.label === 'unchecked';
+      let checkedWant = state.label === 'checked';
       if (selectedProbe && resolved.role && ['checkbox', 'radio', 'switch'].includes(resolved.role)) {
         stateAssertion = 'toBeChecked()';
         selectedProbe = false;
+        isCheckedAssertion = true;
+        checkedWant = true;
       }
-
       const code = context.templateEngine.renderStep('state-with-filter-assertion', {
         ...resolved,
+        selectorRef: step.selectorRef,
         dataValue,
         stateAssertion,
         selectedProbe,
+        isCheckedAssertion,
+        checkedWant,
       });
       return { code, comment: `Assert ${step.selectorRef} with ${step.dataRef} is ${state.label}` };
     },
@@ -466,21 +498,40 @@ export const assertionPatterns: StepPattern[] = [
 
       // --- Label-value pattern: "User see [X] label with {{Y}}" ---
       if (step.elementType === 'label' && step.dataRef) {
-        let label: string | undefined = step.selectorRef;
-        try {
-          const labelResolved = context.selectorResolver.resolveSelector(
-            step.selectorRef!,
-            context.featureName,
-            step.elementType,
-            step.nth
+        // A `label` ref reads two different ways, and the selectors.yaml entry decides which.
+        //
+        // NO ENTRY, or an entry that finds its element BY TEXT — the ref names on-screen
+        // CAPTION text rather than an element, so the assertion is "the screen shows
+        // `X <value>`". That is what label-value-assertion renders, and it stays the default.
+        //
+        // AN ENTRY NAMING A CONCRETE NODE (xpath / accessibility-id / testid / id / css / …) —
+        // the author has said WHERE the value lives. That locator used to be resolved and then
+        // thrown away, leaving a page-wide text match: on Android `UiSelector().text(v)`, which
+        // reads only @text, so a Flutter/RN node exposing @content-desc never matched. The
+        // entry was correct and the step failed every time (#666). Honouring it puts `label`
+        // alongside `header`, which never had the special case.
+        //
+        // CONTAINS, not exact: an entry for a label/value pair points legitimately either at
+        // the value node ("JD-001") or at the row holding both ("Job No: JD-001"), and the web
+        // regex it replaces was itself anchored only at the end. `exact: true` opts into the
+        // strict comparison.
+        //
+        // `resolved` is the SAME lookup, already performed above — this branch used to repeat it.
+        if (IDENTITY_STRATEGIES.has(resolved.strategy)) {
+          const code = context.templateEngine.renderStep(
+            resolved.exact ? 'have-text-assertion' : 'contain-text-assertion',
+            { ...resolved, expectedText: dataValue },
           );
-          if (labelResolved.value !== undefined && labelResolved.value.trim() === '') {
-            label = undefined;
-          }
-        } catch {
-          // No selector entry — use label from selectorRef
+          return {
+            code,
+            comment: `Assert ${step.selectorRef} label ${resolved.exact ? 'has' : 'contains'} value ${step.dataRef}`,
+          };
         }
 
+        // `value: ''` is the declared opt-out: drop the caption prefix, match the value alone.
+        const label = resolved.value !== undefined && resolved.value.trim() === ''
+          ? undefined
+          : step.selectorRef;
         const code = context.templateEngine.renderStep('label-value-assertion', {
           label,
           dataValue,
@@ -922,6 +973,9 @@ export const assertionPatterns: StepPattern[] = [
   },
   {
     name: 'is-sorted-ascending',
+    platforms: ['web'],
+    platformAlternative:
+      'aria-sort has no native equivalent - read the item texts with per-element assertions and compare them, or tag the scenario @manual',
     states: ['sorted ascending'],
     matcher: (step: ParsedStep) =>
       /\b(see|sees)\s+\[/.test(step.text) && /\bsorted ascending\b/.test(step.text) && !!step.selectorRef,
@@ -937,6 +991,9 @@ export const assertionPatterns: StepPattern[] = [
   },
   {
     name: 'is-sorted-descending',
+    platforms: ['web'],
+    platformAlternative:
+      'aria-sort has no native equivalent - read the item texts with per-element assertions and compare them, or tag the scenario @manual',
     states: ['sorted descending'],
     matcher: (step: ParsedStep) =>
       /\b(see|sees)\s+\[/.test(step.text) && /\bsorted descending\b/.test(step.text) && !!step.selectorRef,

package/src/patterns/capture-patterns.ts

@@ -30,6 +30,9 @@ export const capturePatterns: StepPattern[] = [
     // NOTE: the `table-` name prefix opts out of generateStep's parentRef auto-scoping
     // (the table locator is resolved internally from the step text, like all table-* patterns).
     name: 'table-capture-row-nth',
+    platforms: ['web'],
+    platformAlternative:
+      'there is no HTML table on a native screen - remember the value from the row element itself with the generic capture step (`User remember [Row 2 Amount] as {{v}}`)',
     matcher: (step: ParsedStep) =>
       /\bremember\b/i.test(step.text) && /\bas\s+\{\{[^}]+\}\}/i.test(step.text) && TABLE_ROW_NTH.test(step.text),
     resolver: (step, context): StepTemplateData => {

package/src/patterns/focus-patterns.ts

@@ -30,6 +30,9 @@ const CELL = /^\s*\[([^\]]+)\]\s*([A-Za-z][A-Za-z-]*)?\s*$/;
 export const focusPatterns: StepPattern[] = [
   {
     name: 'tab-order-assertion',
+    platforms: ['web'],
+    platformAlternative:
+      'a touch screen has no keyboard focus traversal - run the accessibility audit manually and tag the scenario @manual:M10',
     matcher: (step) => reTabOrder.test(step.text),
     resolver: (step, context) => {
       const table = step.dataTable;

package/src/patterns/form-patterns.ts

@@ -7,6 +7,9 @@ import { StepPattern, StepTemplateData, expandRecipe } from '@sun-asterisk/sunge
 export const formPatterns: StepPattern[] = [
   {
     name: 'upload-file',
+    platforms: ['web'],
+    platformAlternative:
+      'the file picker is a separate app on mobile - push the file with the driver and drive that picker app-specifically, or tag the scenario @manual:M10',
     matcher: (step: ParsedStep) =>
       (step.text.includes('fill') || step.text.includes('fills')) &&
       step.elementType === 'uploader' &&
@@ -97,8 +100,15 @@ export const formPatterns: StepPattern[] = [
         };
       }
 
-      // Use pressSequentially template for contenteditable/rich-text editors (auto-detected by live-scan)
-      // or when Gherkin explicitly uses 'editor' element type
+      // Rich-text editors fill with pressSequentially, not .fill(). Two ways in: the selector
+      // entry (`contenteditable: true`, which the resolver translates into `inputMethod`, #712 —
+      // or `inputMethod` written out), and the Gherkin `editor` element type, which is a property
+      // of the STEP and so is read separately.
+      //
+      // The note that used to sit here said live-scan auto-detected this. Nothing in any package
+      // writes `inputMethod` — that was the same false-consumer claim #712 was filed over, and it
+      // mattered: with `contenteditable:` dead and no auto-detection, an author who hit a
+      // rich-text field had no working field to reach for at all.
       const isEditor = resolved.inputMethod === 'pressSequentially' || step.elementType === 'editor';
       const templateName = isEditor ? 'fill-editor-action' : 'fill-action';
 
@@ -114,8 +124,13 @@ export const formPatterns: StepPattern[] = [
   },
   {
     name: 'check-checkbox',
+    // `\bchecks?\b` rather than `includes('checks')`: "unchecks" CONTAINS "checks", and this
+    // pattern is declared before uncheck-checkbox at the same priority 8 — so the substring test
+    // made every `unchecks [X]` step compile to a CHECK, turning the control ON and even labelling
+    // the comment "Check". A word boundary cannot match inside "unchecks" (both neighbours are word
+    // characters), so it separates the two verbs on its own.
     matcher: (step: ParsedStep) =>
-      (step.text.includes('checks') || step.text.match(/\bcheck\b/)) && !!step.selectorRef,
+      /\bchecks?\b/.test(step.text) && !!step.selectorRef,
     resolver: (step, context) => {
       const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, undefined, step.elementType, step.nth);
       return {
@@ -128,8 +143,11 @@ export const formPatterns: StepPattern[] = [
   },
   {
     name: 'uncheck-checkbox',
+    // One regex covers both forms: `\buncheck\b` alone cannot match "unchecks" (the trailing "s"
+    // is a word character, so there is no boundary after "k") — which is why the substring test
+    // was here in the first place.
     matcher: (step: ParsedStep) =>
-      (step.text.includes('unchecks') || step.text.match(/\buncheck\b/)) && !!step.selectorRef,
+      /\bunchecks?\b/.test(step.text) && !!step.selectorRef,
     resolver: (step, context) => {
       const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, undefined, step.elementType, step.nth);
       return {

package/src/patterns/interaction-patterns.ts

@@ -32,6 +32,54 @@ function elementKeywordToRole(text: string): string | null {
 /**
  * Interaction patterns: click, hover, press, wait, alert
  */
+/** Corner presets: 5% in from each corner, so the point stays on the element under any padding. */
+const CLICK_POSITION_PRESETS: Record<string, { x: number; y: number }> = {
+  'top-left': { x: 5, y: 5 },
+  'top-right': { x: 95, y: 5 },
+  'bottom-left': { x: 5, y: 95 },
+  'bottom-right': { x: 95, y: 95 },
+};
+
+/** A parsed click position: each axis is `px` or `%` of the element's padding box (ratio precomputed). */
+export interface ClickPosition {
+  x: number; xUnit: 'px' | '%'; xRatio: number;
+  y: number; yUnit: 'px' | '%'; yRatio: number;
+}
+
+/**
+ * Parse the `at position "<preset>"` / `at offset x=<n>px|%, y=<n>px|%` suffix. Strict on purpose:
+ * anything the grammar does not accept is an error the compiler reports — a position that is half
+ * understood would click somewhere the author did not ask for.
+ */
+export function parseClickPosition(text: string): ClickPosition | { error: string } {
+  const presetNames = Object.keys(CLICK_POSITION_PRESETS).map((k) => `"${k}"`).join(' | ');
+  // Both forms end the sentence: anything after the position is text no form reads, so it is refused
+  // rather than carried along silently.
+  const preset = /\bat\s+position\s+"([^"]*)"\s*$/i.exec(text);
+  if (preset) {
+    const p = CLICK_POSITION_PRESETS[preset[1].trim().toLowerCase()];
+    if (!p) return { error: `unknown click position preset "${preset[1]}" — use ${presetNames}` };
+    return { x: p.x, xUnit: '%', xRatio: p.x / 100, y: p.y, yUnit: '%', yRatio: p.y / 100 };
+  }
+  if (/\bat\s+position\b/i.test(text)) return { error: `\`at position\` needs a quoted preset (${presetNames}) as the last thing in the step` };
+  const offset = /\bat\s+offset\s+x\s*=\s*(-?\d+(?:\.\d+)?)\s*(px|%)\s*,\s*y\s*=\s*(-?\d+(?:\.\d+)?)\s*(px|%)\s*$/i.exec(text);
+  if (!offset) return { error: '`at offset` needs `x=<n>px|%, y=<n>px|%` with both axes (e.g. `x=24px, y=10%`) as the last thing in the step' };
+  const axis = (raw: string, unit: string, name: 'x' | 'y'): { value: number; unit: 'px' | '%' } | { error: string } => {
+    const value = Number(raw);
+    if (value < 0) return { error: `${name}=${raw}${unit} is negative — offsets are measured from the element's top-left corner` };
+    if (unit === '%' && value > 100) return { error: `${name}=${raw}% exceeds 100% of the element` };
+    return { value, unit: unit.toLowerCase() as 'px' | '%' };
+  };
+  const x = axis(offset[1], offset[2], 'x');
+  if ('error' in x) return x;
+  const y = axis(offset[3], offset[4], 'y');
+  if ('error' in y) return y;
+  return {
+    x: x.value, xUnit: x.unit, xRatio: x.unit === '%' ? x.value / 100 : x.value,
+    y: y.value, yUnit: y.unit, yRatio: y.unit === '%' ? y.value / 100 : y.value,
+  };
+}
+
 export const interactionPatterns: StepPattern[] = [
   // === Browser Alert (system dialog) patterns ===
   // Compound form (preferred since v3.3): trigger + dialog response in ONE step, in the
@@ -106,6 +154,9 @@ export const interactionPatterns: StepPattern[] = [
   },
   {
     name: 'alert-fill',
+    platforms: ['web'],
+    platformAlternative:
+      'Appium ships no fill for a native prompt - accept or dismiss the alert instead (the `alert` element type still works), drive the app own text field as a normal element, or tag the scenario @manual:M10',
     matcher: (step: ParsedStep) =>
       step.elementType === 'alert' &&
       step.text.includes('fill') &&
@@ -228,6 +279,52 @@ export const interactionPatterns: StepPattern[] = [
     },
     priority: 14,  // Below click-element-with-text (15) so known selectors use proper locator
   },
+  {
+    // `click [X] overlay at position "top-left"` / `… at offset x=24px, y=10%` — a click AWAY from the
+    // centre, for backdrop-dismiss overlays and any control whose centre is covered by a child.
+    // `.click()` always lands on the centre; there was no way to say "click the overlay, not the
+    // dialog sitting in the middle of it". Presets are 5% in from the corners so the point stays on
+    // the element under any padding. Positions are checked against the element's PADDING box at
+    // run time (`clientWidth/Height`, the same box `click({ position })` measures from), so a px
+    // offset beyond the real size fails with the real size in the message instead of clicking the
+    // neighbour. A suffix the grammar cannot parse is refused at compile time (SG-E026, via the core
+    // guard) — never a silent centre click.
+    name: 'click-element-at-position',
+    platforms: ['web'],
+    platformAlternative:
+      'Appium has no positioned click on an element — tap the control the position targets directly (`User tap [X] button`), or tag the scenario @manual',
+    matcher: (step: ParsedStep) =>
+      /\b(click|clicks)\b/.test(step.text)
+      // a positioned DOUBLE/RIGHT click is not offered — leave those to their own forms so the core
+      // guard refuses the suffix instead of this form silently turning them into a single click
+      && !/\b(?:double|right)[\s-]*click/i.test(step.text)
+      && /\bat\s+(position|offset)\b/i.test(step.text) && !!step.selectorRef,
+    resolver: (step, context) => {
+      const resolved = context.selectorResolver.resolveSelector(
+        step.selectorRef!, undefined, step.elementType, step.nth
+      );
+      const suffix = step.text.match(/\bat\s+(?:position|offset)\b.*$/i)?.[0].trim() ?? 'at position';
+      // JSON.stringify quotes the label for the generated code — the step text is author text.
+      const label = JSON.stringify(`click [${step.selectorRef}] ${suffix}`);
+      const parsed = parseClickPosition(step.text);
+      if ('error' in parsed) {
+        // The template is not what refuses this — the core compiler does (SG-E026 + a loud throw);
+        // `positionError` is the signal it reads. Emitted here so the reason names the exact fault.
+        return {
+          templateName: 'click-at-position-action',
+          data: { ...resolved, selectorRef: step.selectorRef, label, positionError: parsed.error },
+          comment: `Click ${step.selectorRef} ${suffix}`,
+        };
+      }
+      return {
+        templateName: 'click-at-position-action',
+        data: { ...resolved, selectorRef: step.selectorRef, label, clickPosition: parsed },
+        comment: `Click ${step.selectorRef} ${suffix}`,
+      };
+    },
+    priority: 12,  // above click-element (10): the suffix wins; below click-element-with-text (15) and the
+                   // alert/try-to forms — those combinations are refused by the core guard, not compiled
+  },
   {
     name: 'click-element-with-text',
     matcher: (step: ParsedStep) =>
@@ -295,6 +392,12 @@ export const interactionPatterns: StepPattern[] = [
     // click-element-with-text. Without this, hover fell through to hover-element which IGNORED
     // the value and hovered the first match (strict-mode / wrong element on dynamic lists).
     name: 'hover-element-with-text',
+    // Pure: this resolver requests `hover-element-with-text` and nothing else, which is what makes
+    // the declaration safe. A pattern that can reach a shared template (click, recipe-sequence) must
+    // NOT be declared — see the mixed `unknown-element-action` below, which also serves click.
+    platforms: ['web'],
+    platformAlternative:
+      'a touch screen has no hover, so filtering a list by text and hovering it has no mobile meaning — tap the matching item with `User tap [X] item with {{value}}`, or tag the scenario @manual:M10',
     matcher: (step: ParsedStep) =>
       (step.text.includes('hovers') || step.text.match(/\bhover\b/))
       && !!step.selectorRef
@@ -328,6 +431,10 @@ export const interactionPatterns: StepPattern[] = [
   },
   {
     name: 'hover-element',
+    // Pure: requests `hover-action` only.
+    platforms: ['web'],
+    platformAlternative:
+      'there is no hover on a touch screen — content a hover reveals is normally already visible on mobile; if the interaction is genuinely required, tap it with `User tap [X]`, otherwise tag the scenario @manual:M10',
     matcher: (step: ParsedStep) =>
       (step.text.includes('hovers') || step.text.match(/\bhover\b/)) && !!step.selectorRef,
     resolver: (step, context) => {
@@ -457,19 +564,23 @@ export const interactionPatterns: StepPattern[] = [
 
       const isAbsoluteUrl = /^https?:\/\//.test(path);
       let pathRegex: string;
+      let hostRegex: string | undefined;
       if (isAbsoluteUrl) {
         const url = new URL(path);
-        const hostEscaped = escapeRegex(url.hostname);
-        // Dynamic :id segments in the path → [^/]+ wildcard (host stays literal)
-        const pathEscaped = url.pathname !== '/' ? pathToRegexSource(url.pathname) : '';
-        pathRegex = hostEscaped + pathEscaped;
+        // Host and path are matched SEPARATELY since #677: the wait tests `u.hostname` and
+        // `u.pathname`, and neither string contains the other. Concatenating them into one regex
+        // only worked while the match ran unanchored across the whole URL — the very looseness
+        // that let the wait resolve on a transient URL. Dynamic :id segments still wildcard;
+        // the host stays a literal.
+        hostRegex = escapeRegex(url.hostname);
+        pathRegex = pathToRegexSource(url.pathname);
       } else {
         pathRegex = pathToRegexSource(path);
       }
 
       return {
         templateName: 'wait-for-page',
-        data: { pathRegex },
+        data: { pathRegex, hostRegex },
         comment: step.selectorRef ? `Wait for ${step.selectorRef} page` : `Wait for page`,
       };
     },

package/src/patterns/navigation-patterns.ts

@@ -172,6 +172,9 @@ export const navigationPatterns: StepPattern[] = [
   },
   {
     name: 'route-assertion',
+    platforms: ['web'],
+    platformAlternative:
+      'a native app has no URL - assert a marker element on the destination screen (`Then User see [Header Title] is visible`) plus the origin marker `is hidden`',
     matcher: (step: ParsedStep) =>
       (step.text.includes('should see route') || step.text.includes('should remain on')) &&
       !!(step.selectorRef || step.dataRef),

package/src/patterns/storage-patterns.ts

@@ -104,6 +104,9 @@ function buildCheck(text: string, area: string): StorageCheck | null {
 export const storagePatterns: StepPattern[] = [
   {
     name: 'storage-key-assertion',
+    platforms: ['web'],
+    platformAlternative:
+      'browser local/session storage has no native equivalent - assert the state through a UI element, or through @api/@query against the backend',
     matcher: (step) =>
       reExists.test(step.text) || reNotExist.test(step.text) ||
       reNotEmpty.test(step.text) || reHasLength.test(step.text),
@@ -130,6 +133,9 @@ export const storagePatterns: StepPattern[] = [
   },
   {
     name: 'storage-key-matching-assertion',
+    platforms: ['web'],
+    platformAlternative:
+      'browser local/session storage has no native equivalent - assert the state through a UI element, or through @api/@query against the backend',
     matcher: (step) => reKeyMatching.test(step.text),
     resolver: (step) => {
       const area = storageArea(step.text);

package/src/patterns/table-pagination-patterns.ts

@@ -0,0 +1,102 @@
+/**
+ * Table Pagination Patterns (issue #712)
+ *
+ * Syntax:
+ * - User go to next page in [Orders] table
+ * - User go to prev page in [Orders] table          # `previous` accepted too
+ *
+ * These are the consumers for the table entry's `pagination:` map, which was documented in the
+ * selector reference and plumbed onto ResolvedSelector while nothing read it back — writing it
+ * changed nothing, with no diagnostic (#712, the same drift class as #690).
+ *
+ *   orders:
+ *     type: 'table'
+ *     value: 'table.orders'
+ *     pagination:
+ *       next: '[data-testid="next-page"]'
+ *       prev: '[data-testid="prev-page"]'
+ *
+ * Three deliberate choices:
+ *
+ * PAGE-LEVEL, NOT TABLE-SCOPED. The control is located from `page`, not from inside the table
+ * locator, because in every component library that ships a paginator (antd, MUI, Radix) the
+ * control is a SIBLING of the <table>, not a descendant. Scoping it to the table would resolve 0
+ * elements for the common case — the same vacuous-universe failure `rows:` exists to fix
+ * (SG-W016). The field lives on the table entry because it BELONGS to that table logically, not
+ * because it is nested under it in the DOM.
+ *
+ * NO IMPLICIT WAIT. Clicking next does one thing: click. The round-trip afterwards is
+ * `User wait for [Orders] table to refresh`, which already owns signal resolution (aria-busy,
+ * then the profile's loading indicator). Folding a hidden wait in here would duplicate that
+ * logic and hide which signal was used. A disabled control (already on the last page) needs no
+ * guard either: Playwright's click waits for enabled and fails loud, so the step cannot pass
+ * without having done anything.
+ *
+ * REFUSAL VIA THE SHARED PATH, NOT A WEB TEMPLATE. An undeclared direction reports SG-W017 and
+ * compiles through `unsupportedStepCode`, rather than rendering a refusal template of its own:
+ * playwright's refusal-only template count is a deliberate floor of 0 (refusals there are the
+ * platform's job, not a step's), and a one-sided .hbs would fail the adapter-parity gate.
+ */
+
+import { StepPattern, PatternContext, MappedStep, unsupportedStepCode } from '@sun-asterisk/sungen';
+
+/** `go to next page in` / `goes to previous page in` — the direction is captured. */
+const PAGINATE_STEP = /\bgo(?:es)?\s+to\s+(next|prev|previous)\s+page\s+in\b/i;
+
+/** Gherkin direction word → the key authors write under `pagination:` in selectors.yaml. */
+function paginationKey(direction: string): 'next' | 'prev' {
+  return /^next$/i.test(direction) ? 'next' : 'prev';
+}
+
+export const tablePaginationPatterns: StepPattern[] = [
+  {
+    name: 'table-paginate',
+    platforms: ['web'],
+    platformAlternative:
+      'a native screen has no HTML paginator - scroll the list instead (`When User scroll to [Last Row]`), or tap the pager control directly as a plain tap step',
+    matcher: (step) => PAGINATE_STEP.test(step.text) && /\btable\b/i.test(step.text),
+    generator: (step, context: PatternContext): MappedStep => {
+      const tableName = (step.text.match(/\[([^\]]+)\]/)?.[1] ?? '').trim();
+      const direction = step.text.match(PAGINATE_STEP)![1];
+      const key = paginationKey(direction);
+
+      const resolved = context.selectorResolver.resolveSelector(
+        tableName, context.featureName, 'table', 0,
+      );
+
+      const declared = resolved.pagination?.[key];
+      const paginationSelector = typeof declared === 'string' ? declared.trim() : '';
+
+      // Nothing honest to emit: refuse at compile time and name the field to add. Guessing a
+      // locator here (hunting a button called `Next`) is exactly what #690 punished.
+      if (!paginationSelector) {
+        const known = Object.keys(resolved.pagination ?? {});
+        const found = known.length
+          ? `that entry declares pagination.${known.join('/')} only`
+          : 'that entry declares no pagination at all';
+        const reason =
+          `step "${step.text}" needs "pagination.${key}" on the [${tableName}] table entry, but `
+          + `${found}. Add it in selectors.yaml, e.g. pagination: { ${key}: '[data-testid="${key}-page"]' }.`;
+
+        context.diagnostics?.add('SG-W017', reason, {
+          feature: context.featureName,
+          step: step.text,
+        });
+        return {
+          code: unsupportedStepCode(reason),
+          comment: `pagination.${key} not declared for ${tableName} table — see SG-W017`,
+        };
+      }
+
+      return {
+        code: context.templateEngine.renderStep('table-paginate-action', {
+          ...resolved, paginationSelector, direction: key, tableName,
+        }),
+        comment: `Go to ${key === 'next' ? 'next' : 'previous'} page in ${tableName} table`,
+      };
+    },
+    // Above the table family (10-20) so the strict matcher is never shadowed by a generic
+    // table step; `go to` is claimed by no navigation pattern (those match open/is on/navigate to).
+    priority: 21,
+  },
+];

package/src/patterns/table-patterns.ts

@@ -17,6 +17,63 @@
 
 import { StepPattern, PatternContext } from '@sun-asterisk/sungen';
 import { rowIndexExpr, TABLE_ROW_NTH } from '../utils/row-index';
+import { resolveColumnHeaderName } from '../utils/column-header';
+
+/**
+ * Row LABEL resolution — `[First Contact Row] row in [T] table` (cb59e157, SG-W010).
+ *
+ * A `type: locator` entry for the row label positions ONE row (`tbody tr:first-child`, relative to
+ * the table) and the step asserts that exact row. No entry → the label is display-only and the
+ * historical filter-by-value query runs, byte-identical. Shared by the exists/hidden twins so the
+ * two can never drift apart again — `is hidden` used to compute the label and use it only in the
+ * comment (issue #688).
+ *
+ * NOT the row SHAPE. `div.job-row` (what every row matches) is a property of the table and lives on
+ * the table entry as `rows:`; put through this branch it strict-mode-fails, which is what the
+ * runtime `toHaveCount(1)` guard in the positioned templates now says out loud.
+ */
+function resolveRowLabel(rowLabel: string, tableName: string, context: PatternContext): string | undefined {
+  if (!rowLabel || rowLabel === tableName) return undefined;
+  try {
+    const rowResolved = context.selectorResolver.resolveSelector(rowLabel, context.featureName, 'row', 0);
+    if (rowResolved.strategy === 'locator' && rowResolved.value && rowResolved.value.trim()) {
+      return rowResolved.value;
+    }
+  } catch {
+    // no selectors.yaml entry for the row label — display-only label (fallback)
+  }
+  return undefined;
+}
+
+/**
+ * SG-W016 — a table located by CSS that declares no `rows:` (issue #688).
+ *
+ * Every table template assumes an ARIA table: rows are `getByRole('row')`. A list built from plain
+ * <div>s has no role=row, so that universe is 0 elements — `is hidden` and `is empty` then pass
+ * without checking anything, counts and clicks time out. The compiler cannot see the DOM, so this is
+ * a heuristic and a WARNING: a CSS/testid-located table whose value does not even mention `table`
+ * is the shape where the assumption most often fails. `role: table`, `table.users`, or a declared
+ * `rows:` are all evidence the author has thought about it, and stay silent. Once per table per
+ * feature — the same table is named by every row step of a scenario.
+ */
+const warnedTables = new WeakMap<object, Set<string>>();
+function warnIfRowsLikelyMissing(
+  resolved: { strategy?: string; value?: string; rows?: string }, tableName: string,
+  context: PatternContext, stepText: string,
+): void {
+  const sink = context.diagnostics;
+  if (!sink || resolved.rows) return;
+  if (!['css', 'locator', 'testid', 'id'].includes(String(resolved.strategy))) return;
+  if (/\btable\b/i.test(String(resolved.value ?? ''))) return;
+  const key = `${context.featureName ?? ''}::${tableName}`;
+  let seen = warnedTables.get(sink);
+  if (!seen) { seen = new Set(); warnedTables.set(sink, seen); }
+  if (seen.has(key)) return;
+  seen.add(key);
+  sink.add('SG-W016',
+    `table "[${tableName}]" is located by ${resolved.strategy} ("${resolved.value}") and declares no "rows:" — if its rows are not role="row" (a <div> list), every table step resolves 0 rows: "is hidden" and "is empty" pass without checking anything, counts and clicks time out. Declare the row shape on the table entry, e.g. "rows: 'div.job-row'", or locate the table by role: table.`,
+    { feature: context.featureName, step: stepText });
+}
 
 /** Helper: check if current step is in a Given context */
 function isGivenContext(context: PatternContext): boolean {
@@ -38,6 +95,9 @@ export const tablePatterns: StepPattern[] = [
   // "User see [Table] table with {{count}}" — row count (no "rows" keyword needed)
   {
     name: 'table-row-count',
+    platforms: ['web'],
+    platformAlternative:
+      'there is no HTML table on a native screen - assert the list count through a visible counter element, or through @query against the backend',
     matcher: (step) => {
       return step.elementType === 'table' &&
              /\btable\s+with\b/i.test(step.text) &&
@@ -51,6 +111,7 @@ export const tablePatterns: StepPattern[] = [
         step.selectorRef!, context.featureName, 'table', step.nth
       );
       const count = context.dataResolver.resolveData(step.dataRef!, context.featureName);
+      warnIfRowsLikelyMissing(resolved, step.selectorRef!, context, step.text);
 
       const isGiven = isGivenContext(context);
       return {
@@ -65,6 +126,9 @@ export const tablePatterns: StepPattern[] = [
   // "User see [Col] column in [Table] table"
   {
     name: 'table-column-exists',
+    platforms: ['web'],
+    platformAlternative:
+      'there is no HTML table on a native screen - assert the header element by accessibility-id instead',
     matcher: (step) => {
       return /\bcolumn\s+in\b/i.test(step.text) &&
              /\btable\b/i.test(step.text) &&
@@ -82,10 +146,14 @@ export const tablePatterns: StepPattern[] = [
         tableName, context.featureName, 'table', step.nth
       );
 
+      // The DOM header text is declarable — the bracket label is the TEST's name for the column,
+      // not the page's (issue #674). See resolveColumnHeaderName for the precedence.
+      const headerName = resolveColumnHeaderName(columnName, context, resolved);
+
       const isGiven = isGivenContext(context);
       return {
         templateName: 'table-column-exists',
-        data: { ...resolved, columnName, isGiven },
+        data: { ...resolved, columnName: headerName, isGiven },
         comment: `${isGiven ? 'Wait' : 'Assert'} ${columnName} column in ${tableName} table`,
       };
     },
@@ -95,6 +163,9 @@ export const tablePatterns: StepPattern[] = [
   // "User see [Table] table is empty"
   {
     name: 'table-is-empty',
+    platforms: ['web'],
+    platformAlternative:
+      'there is no HTML table on a native screen - assert the empty-state element is visible and a row marker `is hidden`',
     states: ['empty'],
     matcher: (step) => {
       return /\btable\s+is\s+empty\b/i.test(step.text);
@@ -104,6 +175,8 @@ export const tablePatterns: StepPattern[] = [
         step.selectorRef!, context.featureName, 'table', step.nth
       );
 
+      warnIfRowsLikelyMissing(resolved, step.selectorRef!, context, step.text);
+
       const isGiven = isGivenContext(context);
       return {
         templateName: 'table-empty',
@@ -151,6 +224,9 @@ export const tablePatterns: StepPattern[] = [
   // "User see [Ref] row in [Table] table with {{value}}" — row exists (enters row scope)
   {
     name: 'table-row-exists',
+    platforms: ['web'],
+    platformAlternative:
+      'there is no HTML table on a native screen - assert the row element by accessibility-id (`Then User see [Row 1 Title] has text {{v}}`)',
     matcher: (step) => {
       return step.elementType === 'row' &&
              /\bin\b.*\btable\b/i.test(step.text) &&
@@ -179,24 +255,13 @@ export const tablePatterns: StepPattern[] = [
       // (RELATIVE to the table, e.g. `tbody tr:first-child`) positions the row,
       // and the assertion becomes toContainText on that exact row. No entry →
       // the historical filter-by-value behavior, byte-identical.
-      let rowSelector: string | undefined;
-      if (rowLabel && rowLabel !== tableName) {
-        try {
-          const rowResolved = context.selectorResolver.resolveSelector(
-            rowLabel, context.featureName, 'row', 0
-          );
-          if (rowResolved.strategy === 'locator' && rowResolved.value && rowResolved.value.trim()) {
-            rowSelector = rowResolved.value;
-          }
-        } catch {
-          // no selectors.yaml entry for the row label — display-only label (fallback)
-        }
-      }
+      const rowSelector = resolveRowLabel(rowLabel, tableName, context);
+      if (!rowSelector) warnIfRowsLikelyMissing(resolved, tableName, context, step.text);
 
       const isGiven = isGivenContext(context);
       return {
         templateName: 'table-row-exists',
-        data: { ...resolved, filterValue, isGiven, rowSelector },
+        data: { ...resolved, filterValue, isGiven, rowSelector, rowLabel },
         comment: rowSelector
           ? `${isGiven ? 'Wait' : 'Assert'} ${rowLabel} (positioned row) in ${tableName} table contains ${step.dataRef}`
           : `${isGiven ? 'Wait' : 'Assert'} ${rowLabel} row in ${tableName} table with ${step.dataRef}`,
@@ -208,6 +273,9 @@ export const tablePatterns: StepPattern[] = [
   // "User see [Ref] row in [Table] table with {{value}} is hidden"
   {
     name: 'table-row-hidden',
+    platforms: ['web'],
+    platformAlternative:
+      'there is no HTML table on a native screen - assert the row element `is hidden` by accessibility-id',
     states: ['hidden'],
     matcher: (step) => {
       return step.elementType === 'row' &&
@@ -229,11 +297,18 @@ export const tablePatterns: StepPattern[] = [
       );
       const filterValue = context.dataResolver.resolveData(step.dataRef!, context.featureName);
 
+      // Same label contract as the exists twin (issue #688): a declared positioned row is asserted
+      // NOT to hold the value; an undeclared label keeps the filter-by-value count-0 query.
+      const rowSelector = resolveRowLabel(rowLabel, tableName, context);
+      if (!rowSelector) warnIfRowsLikelyMissing(resolved, tableName, context, step.text);
+
       const isGiven = isGivenContext(context);
       return {
         templateName: 'table-row-not-exists',
-        data: { ...resolved, filterValue, isGiven },
-        comment: `${isGiven ? 'Wait' : 'Assert'} ${rowLabel} row in ${tableName} table is hidden`,
+        data: { ...resolved, filterValue, isGiven, rowSelector, rowLabel },
+        comment: rowSelector
+          ? `${isGiven ? 'Wait' : 'Assert'} ${rowLabel} (positioned row) in ${tableName} table does not contain ${step.dataRef}`
+          : `${isGiven ? 'Wait' : 'Assert'} ${rowLabel} row in ${tableName} table is hidden`,
       };
     },
     priority: 19,
@@ -247,6 +322,9 @@ export const tablePatterns: StepPattern[] = [
     // where a re-render between queries hits two different rows. Row numbering follows
     // qa/app.yaml conventions.table (row_base, header_is_row).
     name: 'table-action-in-row-nth',
+    platforms: ['web'],
+    platformAlternative:
+      'there is no HTML table on a native screen - tap the control on the nth row element itself (`When User tap [Row 2 Delete] button`)',
     matcher: (step) => {
       return TABLE_ROW_NTH.test(step.text) &&
              /\b(click|clicks|check|checks|uncheck|unchecks)\b/i.test(step.text) &&
@@ -262,20 +340,34 @@ export const tablePatterns: StepPattern[] = [
       const tableResolved = context.selectorResolver.resolveSelector(
         tableName, context.featureName, 'table', 0
       );
+      warnIfRowsLikelyMissing(tableResolved, tableName, context, step.text);
 
-      const actionMatch = step.text.match(/\b(click|check|uncheck)\b/i);
-      const action = actionMatch ? actionMatch[1].toLowerCase() : 'click';
+      // Plural forms are admitted by the matcher above, so they must be READ here too: the old
+      // `\b(click|check|uncheck)\b` matched none of "clicks"/"checks"/"unchecks" (the trailing "s"
+      // kills the closing boundary), so every plural step silently fell back to 'click' — an
+      // `unchecks` step compiled to a click. `uncheck` is listed before `check` so the longer verb
+      // wins the alternation.
+      const actionMatch = step.text.match(/\b(clicks?|unchecks?|checks?)\b/i);
+      const action = actionMatch ? actionMatch[1].toLowerCase().replace(/s$/, '') : 'click';
 
       const elementTypeMatch = step.text.match(/\]\s+([\w-]+)\s+in\b/i);
       const elementType = elementTypeMatch ? elementTypeMatch[1].toLowerCase() : 'button';
       const elementRole = typeToRole[elementType] || elementType;
 
       let actionLocator: string;
+      // Resolved from the ROW'S CONTROL, never from the table: the template data below spreads
+      // `tableResolved`, so a bare `checkedClass` there would be the TABLE's signal pinned onto the
+      // control inside the row (issue #730). The catch path leaves it undefined — with no YAML entry
+      // there is no declaration to read, and the emitted call stays byte-identical to before.
+      let actionCheckedClass: string | undefined;
+      let actionCheckedAttribute: string | undefined;
       try {
         const elementResolved = context.selectorResolver.resolveSelector(
           elementName, context.featureName, elementType, step.nth
         );
         actionLocator = context.renderLocator({ ...elementResolved, parentLocator: 'tableRow' });
+        actionCheckedClass = elementResolved.checkedClass;
+        actionCheckedAttribute = elementResolved.checkedAttribute;
       } catch {
         const escapedName = String(elementName)
           .replace(/\\/g, '\\\\').replace(/'/g, "\\'")
@@ -283,9 +375,11 @@ export const tablePatterns: StepPattern[] = [
         actionLocator = `tableRow.getByRole('${elementRole}', { name: '${escapedName}' })`;
       }
 
+      // A declared row SHAPE never matches the header row, so the header offset does not apply.
+      const rowIndex = rowIndexExpr(rowToken, context, { headerInRows: !tableResolved.rows });
       return {
         templateName: 'table-action-in-row-nth',
-        data: { ...tableResolved, elementName, action, actionLocator, rowIndexExpr: rowIndexExpr(rowToken, context) },
+        data: { ...tableResolved, elementName, action, actionLocator, actionCheckedClass, actionCheckedAttribute, rowIndexExpr: rowIndex },
         comment: `${action} ${elementName} in ${tableName} table row ${rowToken}`,
       };
     },
@@ -293,6 +387,9 @@ export const tablePatterns: StepPattern[] = [
   },
   {
     name: 'table-action-in-row',
+    platforms: ['web'],
+    platformAlternative:
+      'there is no HTML table on a native screen - tap the control on the row element itself (`When User tap [Row 1 Delete] button`)',
     matcher: (step) => {
       return /\bin\b.*\btable\b/i.test(step.text) &&
              /\bwith\b/i.test(step.text) &&
@@ -316,10 +413,16 @@ export const tablePatterns: StepPattern[] = [
       const tableResolved = context.selectorResolver.resolveSelector(
         tableName, context.featureName, 'table', 0
       );
+      warnIfRowsLikelyMissing(tableResolved, tableName, context, step.text);
 
       // Determine action from step text
-      const actionMatch = step.text.match(/\b(click|check|uncheck)\b/i);
-      const action = actionMatch ? actionMatch[1].toLowerCase() : 'click';
+      // Plural forms are admitted by the matcher above, so they must be READ here too: the old
+      // `\b(click|check|uncheck)\b` matched none of "clicks"/"checks"/"unchecks" (the trailing "s"
+      // kills the closing boundary), so every plural step silently fell back to 'click' — an
+      // `unchecks` step compiled to a click. `uncheck` is listed before `check` so the longer verb
+      // wins the alternation.
+      const actionMatch = step.text.match(/\b(clicks?|unchecks?|checks?)\b/i);
+      const action = actionMatch ? actionMatch[1].toLowerCase().replace(/s$/, '') : 'click';
 
       // Extract element type (word after [Act]) and map to ARIA role
       const elementTypeMatch = step.text.match(/\]\s+([\w-]+)\s+in\b/i);
@@ -332,11 +435,19 @@ export const tablePatterns: StepPattern[] = [
       // and when resolution throws we rebuild the historical getByRole string — so the
       // no-entry / unmapped cases stay byte-identical to the previous hardcoded output.
       let actionLocator: string;
+      // Resolved from the ROW'S CONTROL, never from the table: the template data below spreads
+      // `tableResolved`, so a bare `checkedClass` there would be the TABLE's signal pinned onto the
+      // control inside the row (issue #730). The catch path leaves it undefined — with no YAML entry
+      // there is no declaration to read, and the emitted call stays byte-identical to before.
+      let actionCheckedClass: string | undefined;
+      let actionCheckedAttribute: string | undefined;
       try {
         const elementResolved = context.selectorResolver.resolveSelector(
           elementName, context.featureName, elementType, step.nth
         );
         actionLocator = context.renderLocator({ ...elementResolved, parentLocator: 'tableRow' });
+        actionCheckedClass = elementResolved.checkedClass;
+        actionCheckedAttribute = elementResolved.checkedAttribute;
       } catch {
         const escapedName = String(elementName)
           .replace(/\\/g, '\\\\').replace(/'/g, "\\'")
@@ -346,7 +457,7 @@ export const tablePatterns: StepPattern[] = [
 
       return {
         templateName: 'table-action-in-row',
-        data: { ...tableResolved, elementName, filterValue, action, elementRole, actionLocator },
+        data: { ...tableResolved, elementName, filterValue, action, elementRole, actionLocator, actionCheckedClass, actionCheckedAttribute },
         comment: `${action} ${elementName} in ${tableName} table row with ${step.dataRef}`,
       };
     },
@@ -358,6 +469,9 @@ export const tablePatterns: StepPattern[] = [
   // Uses filter({ hasText }) per row — resilient to data changes, row ordering, extra rows
   {
     name: 'table-match-data',
+    platforms: ['web'],
+    platformAlternative:
+      'there is no HTML table on a native screen - assert each row element by accessibility-id, or verify the set through @query against the backend',
     matcher: (step) => {
       return step.elementType === 'table' &&
              /\btable\s+match\s+data\b/i.test(step.text) &&
@@ -369,6 +483,7 @@ export const tablePatterns: StepPattern[] = [
       );
 
       const dataTable = step.dataTable!;
+      warnIfRowsLikelyMissing(resolved, step.selectorRef!, context, step.text);
 
       // Resolve {{variable}} references in a cell (headers included — i18n headers are legal)
       const resolveCell = (cell: string): string => {

package/src/utils/column-header.ts

@@ -0,0 +1,54 @@
+import { PatternContext, normalizeRefLabel } from '@sun-asterisk/sungen';
+
+/** The `columns:` map as it reaches a pattern from a resolved TABLE entry. */
+interface ColumnsCarrier {
+  columns?: Record<string, { index?: number; header?: string } | undefined>;
+}
+
+/**
+ * The DOM accessible name of a table COLUMN HEADER (issue #674).
+ *
+ * `see [Category] column in [Article List] table` used to bake the bracket label straight into
+ * `getByRole('columnheader', { name: … })`. Only the TABLE went through resolveSelector; the column
+ * never did. On a Japanese DOM the header reads 記事分類, so the step could not pass and there was
+ * no override — QA's only escape was to rename the Gherkin reference to the Japanese header text.
+ * That reference is what ships in the delivered test case, and it has to stay readable in the
+ * project's working language: the DOM text is a property of the PAGE, the label is a property of
+ * the TEST. They are allowed to differ, so both need a home.
+ *
+ * Most specific declaration first:
+ *   1. the table entry's `columns: { <col>: { header: … } }` — scoped to this one table, and the
+ *      same map the row-scoped cell steps already index by, so a column is described in one place;
+ *   2. a `<col>--columnheader` entry's `name:` — the column key's own selector, which is already
+ *      how `click [Name] columnheader` and `[Name] columnheader is sorted …` resolve. Reading it
+ *      here is what makes the whole columnheader surface behave the same way;
+ *   3. the bracket label verbatim — the historical behaviour, so an undeclared column compiles
+ *      byte-identically to before.
+ *
+ * (2) accepts the entry ONLY when it actually resolved to a columnheader role. resolveSelector
+ * falls back to the BASE key when no `--columnheader` key matches, so an unrelated `category`
+ * combobox on the same screen would otherwise hand its accessible name to the column step — a
+ * silent wrong locator, worse than the bug being fixed. Auto-infer reaches this branch too, but it
+ * names the role after the label, so it returns exactly what (3) would.
+ */
+export function resolveColumnHeaderName(
+  columnLabel: string,
+  context: PatternContext,
+  tableResolved?: ColumnsCarrier,
+): string {
+  const declared = tableResolved?.columns?.[normalizeRefLabel(columnLabel)]?.header;
+  if (declared && declared.trim()) return declared.trim();
+
+  try {
+    const resolved = context.selectorResolver.resolveSelector(
+      columnLabel, context.featureName, 'column', 0,
+    );
+    if (resolved.role === 'columnheader' && resolved.name && resolved.name.trim()) {
+      return resolved.name.trim();
+    }
+  } catch {
+    // No entry for the column key and auto-infer declined — the label is the header.
+  }
+
+  return columnLabel;
+}

package/src/utils/row-index.ts

@@ -11,9 +11,15 @@ import { PatternContext } from '@sun-asterisk/sungen';
  * becomes `Number(testData.get('var'))` via the runtime-data transform, so the offset
  * is emitted as ` + k` / ` - k` around it.
  */
-export function rowIndexExpr(rowToken: string, context: PatternContext): string {
+export function rowIndexExpr(
+  rowToken: string, context: PatternContext, opts: { headerInRows?: boolean } = {},
+): string {
   const rowBase = context.appProfile?.tableRowBase ?? 1;
-  const offset = (context.appProfile?.tableHeaderIsRow ? 0 : 1) - rowBase;
+  // `headerInRows: false` — the table declares a row SHAPE (`rows: 'div.job-row'`, issue #688), and a
+  // shape never matches the header, so `header_is_row` has nothing to correct for.
+  const headerInRows = opts.headerInRows ?? true;
+  const headerOffset = headerInRows && !context.appProfile?.tableHeaderIsRow ? 1 : 0;
+  const offset = headerOffset - rowBase;
 
   const varMatch = rowToken.match(/^\{\{([^}]+)\}\}$/);
   if (!varMatch) return String(Number(rowToken) + offset);

package/src/utils/url-path-regex.ts

@@ -19,10 +19,18 @@ export function escapeRegex(text: string): string {
 /**
  * Convert a URL path into a RegExp source string, turning dynamic route
  * placeholders (`:name`) into `[^/]+` wildcards while escaping literal segments.
- * `/` is emitted as the escaped `\/` so the result drops straight into `/…/`.
+ * `/` is emitted as the escaped `\/` so the result drops straight into `/…/`. A query or
+ * fragment in the input is dropped — see the comment in the body.
  */
 export function pathToRegexSource(path: string): string {
+  // Every caller compiles this into a pattern tested against `u.pathname`, which never carries a
+  // query or a fragment. A page selector whose `value` includes one ('/search?tab=1' — off the
+  // documented "the value carries the PATH only" contract, but written in the field) would
+  // otherwise escape the `?` into the pattern and produce a match no real URL can satisfy: an
+  // assertion that can never pass, a wait that can only time out. Dropped here, once, rather than
+  // in each of the four resolvers that build a pathname pattern.
   return path
+    .replace(/[?#].*$/, '')
     .split('/')
     .map((segment) =>
       /^:[A-Za-z_][A-Za-z0-9_]*$/.test(segment) ? '[^/]+' : escapeRegex(segment)