@sungen/driver-ui 3.2.29 → 3.2.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-ui",
-  "version": "3.2.29",
+  "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.29"
+    "@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
@@ -102,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,
@@ -360,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}` };
     },

package/src/patterns/form-patterns.ts

@@ -100,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';
 
@@ -117,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 {
@@ -131,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
@@ -231,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) =>
@@ -470,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/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,7 @@
 
 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).
@@ -145,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`,
       };
     },
@@ -337,19 +342,32 @@ export const tablePatterns: StepPattern[] = [
       );
       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, "\\'")
@@ -361,7 +379,7 @@ export const tablePatterns: StepPattern[] = [
       const rowIndex = rowIndexExpr(rowToken, context, { headerInRows: !tableResolved.rows });
       return {
         templateName: 'table-action-in-row-nth',
-        data: { ...tableResolved, elementName, action, actionLocator, rowIndexExpr: rowIndex },
+        data: { ...tableResolved, elementName, action, actionLocator, actionCheckedClass, actionCheckedAttribute, rowIndexExpr: rowIndex },
         comment: `${action} ${elementName} in ${tableName} table row ${rowToken}`,
       };
     },
@@ -398,8 +416,13 @@ export const tablePatterns: StepPattern[] = [
       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);
@@ -412,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, "\\'")
@@ -426,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}`,
       };
     },

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/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)