@sungen/driver-ui 3.2.28 → 3.2.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-ui",
-  "version": "3.2.28",
+  "version": "3.2.29",
   "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.29"
   },
   "peerDependencies": {
     "@playwright/test": "^1.57.0"

package/src/patterns/assertion-patterns.ts

@@ -30,6 +30,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 +81,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 &&
@@ -466,21 +482,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 +957,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 +975,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' &&

package/src/patterns/interaction-patterns.ts

@@ -106,6 +106,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') &&
@@ -295,6 +298,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 +337,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) => {

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-patterns.ts

@@ -18,6 +18,62 @@
 import { StepPattern, PatternContext } from '@sun-asterisk/sungen';
 import { rowIndexExpr, TABLE_ROW_NTH } from '../utils/row-index';
 
+/**
+ * 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 {
   return context.effectiveKeyword === 'Given';
@@ -38,6 +94,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 +110,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 +125,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) &&
@@ -95,6 +158,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 +170,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 +219,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 +250,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 +268,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 +292,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 +317,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,6 +335,7 @@ 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';
@@ -283,9 +357,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, rowIndexExpr: rowIndex },
         comment: `${action} ${elementName} in ${tableName} table row ${rowToken}`,
       };
     },
@@ -293,6 +369,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,6 +395,7 @@ 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);
@@ -358,6 +438,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 +452,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/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);