@sun-asterisk/sungen 2.0.0 → 2.0.2

package/docs/gherkin-dictionary.md

@@ -0,0 +1,1071 @@
+# Sungen Gherkin Dictionary v2
+
+Complete mapping from Gherkin steps to Playwright code.
+This is the compiler rulebook — deterministic, no AI needed at compile time.
+
+---
+
+## Project Structure
+
+### Screen directory (multi-file)
+
+```
+qa/screens/<screen-name>/
+├── features/
+│   ├── <screen>.feature              # main scenarios (page load, content)
+│   ├── <screen>-navigation.feature   # navigation scenarios
+│   ├── <screen>-<feature>.feature    # additional feature-specific scenarios
+│   └── ...
+├── selectors/
+│   ├── <screen>.yaml                 # shared selectors (header, nav, page entry)
+│   ├── <screen>-<feature>.yaml       # feature-specific selectors
+│   ├── <screen>.override.yaml        # manual overrides (never auto-modified)
+│   └── ...
+└── test-data/
+    ├── <screen>.yaml                 # shared test data
+    ├── <screen>-<feature>.yaml       # feature-specific test data
+    ├── <screen>.override.yaml        # manual overrides (never auto-modified)
+    └── ...
+```
+
+### Merge rules at compile time
+
+1. **Selectors:** All `.yaml` in `selectors/` are merged into one map. `.override.yaml` takes precedence.
+2. **Test-data:** All `.yaml` in `test-data/` are merged. `.override.yaml` takes precedence.
+3. **Features:** Each `.feature` compiles to its own `.spec.ts`:
+
+```
+features/awards.feature             → specs/generated/awards/awards.spec.ts
+features/awards-navigation.feature  → specs/generated/awards/awards-navigation.spec.ts
+features/awards-table.feature       → specs/generated/awards/awards-table.spec.ts
+```
+
+### CLI commands
+
+```bash
+sungen init                                    # scaffold project + AI rules
+sungen add --screen awards --path /awards      # create screen with main feature
+sungen add --screen awards --feature navigation # add feature file to existing screen
+sungen makeauth <role>                         # capture browser auth state
+sungen generate --screen awards                # compile all features → .spec.ts
+sungen generate --all                          # compile all screens
+```
+
+### Feature file template
+
+Every `.feature` must include `Path:` so AI knows which URL to visit:
+
+```gherkin
+Feature: awards Screen
+
+  As a user
+  I want to interact with the awards screen
+  So that I can accomplish my tasks
+  Path: /awards
+```
+
+### AI rules files
+
+Generated by `sungen init`:
+
+```
+.github/copilot-instructions.md    # GitHub Copilot
+CLAUDE.md                          # Claude Code
+```
+
+Both contain this dictionary, YAML schema, and instructions for AI to generate/fix files.
+
+---
+
+## Selector YAML Schema v2
+
+Every `[element]` in Gherkin resolves to a selector entry:
+
+```yaml
+element.key:
+  # === Core ===
+  type: 'testid'|'role'|'text'|'label'|'placeholder'|'locator'|'page'|'upload'|'frame'
+  value: 'button'              # role name, testid value, CSS selector, etc.
+  name: 'Submit'               # accessible name (for role-based)
+  nth: 0                       # element index when multiple matches
+
+  # === Disambiguation ===
+  exact: true|false            # exact name/text match (default: false)
+  scope: 'desktop navigation'  # parent landmark aria-label to scope within
+  match: 'exact'|'partial'     # for getByText matching (default: partial)
+
+  # === Complex Elements ===
+  variant: 'native'|'custom'|'dragdrop'  # dropdown / upload type
+  trigger: 'Upload Photo'      # visible button that triggers hidden input
+  frame: '#payment-iframe'     # iframe selector for cross-frame elements
+  contenteditable: true         # rich text editor (contenteditable div)
+
+  # === Table Definition ===
+  columns:                     # only for type: 'table'
+    name:
+      index: 0
+      header: 'Name'
+    status:
+      index: 2
+      header: 'Status'
+      elements:                # interactive elements inside column cells
+        edit:
+          type: 'role'
+          value: 'button'
+          name: 'Edit'
+  pagination:                  # table pagination selectors
+    next: '[data-testid="next-page"]'
+    prev: '[data-testid="prev-page"]'
+    pageSize: '[data-testid="page-size"]'
+
+  # === Assertion Helpers ===
+  attribute: 'src'             # attribute to check (for "has" assertions)
+  pattern: '/.*\\.png$/'       # regex for attribute value
+```
+
+### Locator Resolution Priority
+
+```
+1. data-testid  →  page.getByTestId(value)
+2. role + name  →  page.getByRole(value, { name, exact })
+3. label        →  page.getByLabel(value, { exact })
+4. placeholder  →  page.getByPlaceholder(value, { exact })
+5. text         →  page.getByText(value, { exact: match=='exact' })
+6. locator      →  page.locator(value)
+7. page         →  page.goto(value)
+8. upload       →  page.locator(value).setInputFiles()
+9. frame        →  page.frameLocator(value)
+```
+
+---
+
+## Formal Grammar
+
+```
+STEP         := ACTOR VERB_PHRASE
+ACTOR        := "User"
+
+VERB_PHRASE  := ACTION_VP
+              | WAIT_VP
+              | NAV_VP
+              | SCROLL_VP
+              | SWITCH_VP
+              | TABLE_VP
+
+# ─── Basic actions ────────────────────────────────────────────
+ACTION_VP    := ACTION TARGET_EXPR (DATA_EXPR)? (STATE_EXPR)?       # ①②③④
+              | ACTION TARGET_EXPR "to" TARGET_EXPR                  # ⑤ drag
+              | ACTION KEY "key" ("on" TARGET_EXPR)?                 # ⑥⑦ keyboard
+              | ACTION TARGET_EXPR ("has"|"contains") DATA_EXPR      # ⑫⑰ has/contains
+              | ACTION TARGET_EXPR "has" TARGET_EXPR                 # ⑫ has column
+              | "double click" TARGET_EXPR                           # double click
+
+# ─── Wait ─────────────────────────────────────────────────────
+WAIT_VP      := "wait for" TIMEOUT                                   # ⑧
+              | "wait for" TARGET_EXPR (DATA_EXPR)? (STATE_EXPR)?    # ⑨
+
+# ─── Navigation ───────────────────────────────────────────────
+NAV_VP       := "is on" TARGET_EXPR "page"                           # ⑯
+              | "navigate to" TARGET_EXPR "page" (DATA_EXPR)?        # ⑯
+
+# ─── Scroll ───────────────────────────────────────────────────
+SCROLL_VP    := "scroll to" TARGET_EXPR                              # ⑩
+
+# ─── Frame switch ─────────────────────────────────────────────
+SWITCH_VP    := "switch to" TARGET_EXPR "frame"                      # ⑪
+
+# ─── Table ────────────────────────────────────────────────────
+TABLE_VP     := "see" TARGET_EXPR "table" TABLE_EXPR                 # ⑬⑭
+              | ACTION TARGET_EXPR "in" TARGET_EXPR "table"
+                TABLE_ROW_EXPR                                       # ⑮
+
+TABLE_EXPR   := TABLE_ROW_EXPR
+              | "has" DATA_EXPR "rows"                               # row count
+              | "has" TARGET_EXPR "column"                           # column exists
+              | "is empty"                                           # empty state
+              | "empty message" DATA_EXPR                            # empty message
+
+TABLE_ROW_EXPR := "row" (NUMBER)? (DATA_EXPR)? (TABLE_COL_EXPR)?
+                | "row" (DATA_EXPR)? ELEMENT_TYPE                    # row checkbox
+
+TABLE_COL_EXPR := ("has")? TARGET_EXPR ("cell")? (DATA_EXPR)?
+
+# ─── Terminals ────────────────────────────────────────────────
+TARGET_EXPR  := "[" IDENTIFIER "]" (ELEMENT_TYPE)?
+ELEMENT_TYPE := "button"|"link"|"field"|"heading"|"text"|"image"|"checkbox"
+              | "radio"|"switch"|"dropdown"|"option"|"dialog"|"modal"|"menu"
+              | "menuitem"|"tab"|"tabpanel"|"list"|"listitem"|"table"|"row"
+              | "cell"|"column"|"columnheader"|"region"|"section"|"nav"
+              | "banner"|"header"|"footer"|"alert"|"spinner"|"progressbar"
+              | "slider"|"tree"|"treeitem"|"tooltip"|"icon"|"uploader"
+              | "file"|"frame"|"iframe"|"textarea"|"page"
+DATA_EXPR    := "with" "{{" IDENTIFIER "}}"
+STATE_EXPR   := "is" STATE
+STATE        := "hidden"|"visible"|"disabled"|"enabled"|"checked"
+              | "unchecked"|"focused"|"empty"|"loading"|"selected"
+              | "sorted ascending"|"sorted descending"
+ACTION       := "click"|"fill"|"select"|"check"|"uncheck"|"toggle"
+              | "upload"|"hover"|"drag"|"clear"|"see"|"press"|"expand"
+              | "collapse"|"double click"
+KEY          := "Enter"|"Escape"|"Tab"|"Backspace"|"Delete"|"Space"
+              | "ArrowUp"|"ArrowDown"|"ArrowLeft"|"ArrowRight"
+              | "Home"|"End"|"PageUp"|"PageDown"
+TIMEOUT      := NUMBER ("seconds"|"ms")
+NUMBER       := [0-9]+
+IDENTIFIER   := [a-zA-Z0-9_ ./*:-]+
+```
+
+---
+
+## 17 Pattern Shapes
+
+### ① Simple action: `action [Target] type`
+
+```gherkin
+When User click [Submit] button
+When User check [Remember me] checkbox
+When User uncheck [Newsletter] checkbox
+When User toggle [Dark mode] switch
+When User clear [Search] field
+When User hover [Info] icon
+When User expand [Row 1] row
+When User collapse [Row 1] row
+```
+
+**Compiler rule:**
+```
+locator = resolve([Target], type)
+code = locator.{action}()
+```
+
+**Playwright output:**
+```typescript
+// click button
+await page.getByRole('button', { name: 'Submit', exact: true }).click();
+
+// check checkbox
+await page.getByRole('checkbox', { name: 'Remember me' }).check();
+
+// uncheck checkbox
+await page.getByRole('checkbox', { name: 'Newsletter' }).uncheck();
+
+// toggle switch
+await page.getByRole('switch', { name: 'Dark mode' }).click();
+
+// clear field
+await page.getByRole('textbox', { name: 'Search' }).clear();
+
+// hover
+await page.getByRole('img', { name: 'Info' }).hover();
+```
+
+---
+
+### ② Action with data: `action [Target] type with {{Value}}`
+
+```gherkin
+When User fill [Email] field with {{valid_email}}
+When User fill [Message] textarea with {{message_body}}
+When User select [Country] dropdown with {{country_name}}
+When User upload [Avatar] file with {{avatar_path}}
+When User click [Teammate] button with {{teammate_name}}
+Then User see [Title] heading with {{page_title}}
+Then User see [Price] text with {{item_price}}
+```
+
+**Compiler rule:**
+```
+locator = resolve([Target], type)
+value = resolveData({{Value}})
+if action == 'fill':      code = locator.fill(value)
+if action == 'select':    code = locator.selectOption(value) or click+click
+if action == 'upload':    code = locator.setInputFiles(value)
+if action == 'click':     code = page.getByText(value).click() or locator.filter({hasText}).click()
+if action == 'see':       code = expect(locator).toBeVisible() with text check
+```
+
+**Playwright output:**
+```typescript
+// fill text field
+await page.getByRole('textbox', { name: 'Email', exact: true }).fill('test@example.com');
+
+// fill contenteditable
+await page.locator('[contenteditable="true"]').click();
+await page.locator('[contenteditable="true"]').pressSequentially('Hello world!');
+
+// select native dropdown
+await page.getByRole('combobox', { name: 'Country' }).selectOption('Vietnam');
+
+// select custom dropdown
+await page.getByRole('combobox', { name: 'Country' }).click();
+await page.getByRole('option', { name: 'Vietnam' }).click();
+
+// upload file
+await page.getByLabel('Avatar').setInputFiles('specs/storage/avatar.png');
+
+// click with text filter
+await page.getByText('Nguyễn Thanh Tùng').click();
+
+// see heading with value
+await expect(page.getByRole('heading', { name: 'Hệ thống giải thưởng SAA 2025' })).toBeVisible();
+
+// see text with exact match
+await expect(page.getByText('5.000.000 VNĐ', { exact: true })).toBeVisible();
+```
+
+---
+
+### ③ State assertion: `action [Target] type is state`
+
+```gherkin
+Then User see [Submit] button is disabled
+Then User see [Submit] button is enabled
+Then User see [Modal] dialog is hidden
+Then User see [Welcome] heading is visible
+Then User see [Remember me] checkbox is checked
+Then User see [Newsletter] checkbox is unchecked
+Then User see [Email] field is focused
+Then User see [Search] field is empty
+```
+
+**Compiler rule:**
+```
+locator = resolve([Target], type)
+switch(state):
+  hidden    → expect(locator).toBeHidden()
+  visible   → expect(locator).toBeVisible()
+  disabled  → expect(locator).toBeDisabled()
+  enabled   → expect(locator).toBeEnabled()
+  checked   → expect(locator).toBeChecked()
+  unchecked → expect(locator).not.toBeChecked()
+  focused   → expect(locator).toBeFocused()
+  empty     → expect(locator).toHaveText('')
+```
+
+**Playwright output:**
+```typescript
+await expect(page.getByRole('button', { name: 'Submit' })).toBeDisabled();
+await expect(page.getByRole('dialog')).toBeHidden();
+await expect(page.getByRole('checkbox', { name: 'Remember me' })).toBeChecked();
+await expect(page.getByRole('textbox', { name: 'Email' })).toBeFocused();
+await expect(page.getByRole('textbox', { name: 'Search' })).toHaveText('');
+```
+
+---
+
+### ④ State with data: `action [Target] type with {{Value}} is state`
+
+```gherkin
+Then User see [Panel] dialog with {{dialog_title}} is hidden
+Then User see [Email] field with {{error_message}} is disabled
+```
+
+**Compiler rule:**
+```
+locator = resolve([Target], type).filter({ hasText: value })
+apply state assertion on locator
+```
+
+**Playwright output:**
+```typescript
+await expect(
+  page.getByRole('dialog').filter({ hasText: 'Confirm Delete' })
+).toBeHidden();
+```
+
+---
+
+### ⑤ Two targets: `action [Source] to [Destination]`
+
+```gherkin
+When User drag [Card A] to [Column B]
+```
+
+**Compiler rule:**
+```
+source = resolve([Source])
+dest = resolve([Destination])
+code = source.dragTo(dest)
+```
+
+**Playwright output:**
+```typescript
+await page.getByTestId('card-a').dragTo(page.getByTestId('column-b'));
+```
+
+---
+
+### ⑥ Global key: `action Key key`
+
+```gherkin
+When User press Escape key
+When User press Tab key
+When User press Space key
+```
+
+**Compiler rule:**
+```
+code = page.keyboard.press(Key)
+```
+
+**Playwright output:**
+```typescript
+await page.keyboard.press('Escape');
+```
+
+---
+
+### ⑦ Key on target: `action Key on [Target] type`
+
+```gherkin
+When User press Enter on [Search] field
+When User press Escape on [Modal] dialog
+```
+
+**Compiler rule:**
+```
+locator = resolve([Target], type)
+code = locator.press(Key)
+```
+
+**Playwright output:**
+```typescript
+await page.getByRole('textbox', { name: 'Search' }).press('Enter');
+```
+
+---
+
+### ⑧ Wait timeout: `wait for N seconds`
+
+```gherkin
+When User wait for 3 seconds
+When User wait for 500 ms
+```
+
+**Compiler rule:**
+```
+code = page.waitForTimeout(N * multiplier)
+```
+
+**Playwright output:**
+```typescript
+await page.waitForTimeout(3000);
+```
+
+---
+
+### ⑨ Wait for element: `wait for [Target] type (with {{Value}}) (is state)`
+
+```gherkin
+When User wait for [Modal] dialog
+When User wait for [Loading] spinner is hidden
+When User wait for [Dialog] dialog with {{dialog_title}}
+When User wait for [Dialog] dialog with {{dialog_title}} is hidden
+When User wait for [dashboard] page
+```
+
+**Compiler rule:**
+```
+locator = resolve([Target], type)
+if DATA_EXPR: locator = locator.filter({ hasText: value })
+state = STATE_EXPR ? mapState(state) : 'visible'
+if type == 'page': code = page.waitForURL(value)
+else: code = locator.waitFor({ state })
+```
+
+**Playwright output:**
+```typescript
+// wait for dialog visible
+await page.getByRole('dialog').waitFor({ state: 'visible' });
+
+// wait for spinner hidden
+await page.getByRole('progressbar').waitFor({ state: 'hidden' });
+
+// wait for dialog with title
+await page.getByRole('dialog').filter({ hasText: 'Confirm' }).waitFor({ state: 'visible' });
+
+// wait for dialog with title hidden
+await page.getByRole('dialog').filter({ hasText: 'Confirm' }).waitFor({ state: 'hidden' });
+
+// wait for page
+await page.waitForURL(/\/dashboard/);
+```
+
+---
+
+### ⑩ Scroll: `scroll to [Target] type`
+
+```gherkin
+When User scroll to [Footer] section
+When User scroll to [Comments] region
+```
+
+**Compiler rule:**
+```
+locator = resolve([Target], type)
+code = locator.scrollIntoViewIfNeeded()
+```
+
+**Playwright output:**
+```typescript
+await page.getByRole('contentinfo').scrollIntoViewIfNeeded();
+```
+
+---
+
+### ⑪ Frame switch: `switch to [Target] frame`
+
+```gherkin
+When User switch to [Payment] frame
+```
+
+After this step, all subsequent locators are scoped to the frame until the next `switch to [main] frame` or end of scenario.
+
+**Selector YAML:**
+```yaml
+payment:
+  type: 'frame'
+  value: '#payment-iframe'
+```
+
+**Compiler rule:**
+```
+frameContext = page.frameLocator(value)
+// All subsequent locators use frameContext instead of page
+```
+
+**Playwright output:**
+```typescript
+// Subsequent steps use frame scope:
+const frame = page.frameLocator('#payment-iframe');
+await frame.getByRole('textbox', { name: 'Card number' }).fill('4242...');
+```
+
+---
+
+### ⑫ Has (count/attribute): `action [Target] type has {{Value}}`
+
+```gherkin
+Then User see [Avatar] image has {{avatar_url}}
+Then User see [Link] link has {{href_value}}
+```
+
+**Selector YAML:**
+```yaml
+avatar:
+  type: 'role'
+  value: 'img'
+  name: 'Avatar'
+  attribute: 'src'
+```
+
+**Compiler rule:**
+```
+locator = resolve([Target], type)
+if selector.attribute:
+  code = expect(locator).toHaveAttribute(attribute, value)
+```
+
+**Playwright output:**
+```typescript
+// image has src
+await expect(page.getByRole('img', { name: 'Avatar' })).toHaveAttribute('src', /avatar\.png/);
+
+// link has href
+await expect(page.getByRole('link', { name: 'Home' })).toHaveAttribute('href', '/');
+```
+
+---
+
+### ⑬ Table cell by row index: `see [Table] table row N [Col] cell with {{Value}}`
+
+```gherkin
+Then User see [Users] table row 1 [Name] cell with {{first_name}}
+Then User see [Users] table row 1 [Email] cell with {{first_email}}
+Then User see [Users] table row 3 [Status] cell with {{third_status}}
+```
+
+**Selector YAML:**
+```yaml
+users:
+  type: 'table'
+  value: 'Users'
+  columns:
+    name:
+      index: 0
+      header: 'Name'
+    email:
+      index: 1
+      header: 'Email'
+    status:
+      index: 2
+      header: 'Status'
+```
+
+**Compiler rule:**
+```
+table = page.getByRole('table', { name: selector.value })
+row = table.getByRole('row').nth(N)  // N+1 to skip header
+cell = row.getByRole('cell').nth(columns[Col].index)
+code = expect(cell).toHaveText(value)
+```
+
+**Playwright output:**
+```typescript
+const table = page.getByRole('table', { name: 'Users' });
+const row = table.getByRole('row').nth(1); // skip header
+const cell = row.getByRole('cell').nth(0); // Name column
+await expect(cell).toHaveText('John Doe');
+```
+
+---
+
+### ⑭ Table cell by row filter: `see [Table] table row with {{Filter}} has [Col] with {{Value}}`
+
+```gherkin
+Then User see [Users] table row with {{user_name}} has [Status] with {{expected_status}}
+Then User see [Users] table row with {{user_name}} has [Email] with {{expected_email}}
+```
+
+**Compiler rule:**
+```
+table = page.getByRole('table', { name: selector.value })
+row = table.getByRole('row').filter({ hasText: filterValue })
+cell = row.getByRole('cell').nth(columns[Col].index)
+code = expect(cell).toHaveText(value)
+```
+
+**Playwright output:**
+```typescript
+const table = page.getByRole('table', { name: 'Users' });
+const row = table.getByRole('row').filter({ hasText: 'John Doe' });
+const cell = row.getByRole('cell').nth(2); // Status column
+await expect(cell).toHaveText('Active');
+```
+
+---
+
+### ⑮ Action in table row: `action [Element] in [Table] table row with {{Filter}}`
+
+```gherkin
+When User click [Edit] in [Users] table row with {{user_name}}
+When User click [Delete] in [Users] table row with {{user_name}}
+When User check [Users] table row with {{user_name}} checkbox
+When User check [Users] table select all checkbox
+```
+
+**Compiler rule:**
+```
+table = page.getByRole('table', { name: tableSelector.value })
+row = table.getByRole('row').filter({ hasText: filterValue })
+element = row.resolve([Element])
+code = element.{action}()
+```
+
+**Playwright output:**
+```typescript
+// click button in row
+const table = page.getByRole('table', { name: 'Users' });
+const row = table.getByRole('row').filter({ hasText: 'John Doe' });
+await row.getByRole('button', { name: 'Edit' }).click();
+
+// check row checkbox
+const row = table.getByRole('row').filter({ hasText: 'John Doe' });
+await row.getByRole('checkbox').check();
+
+// select all
+await table.getByRole('checkbox', { name: 'Select all' }).check();
+```
+
+---
+
+### ⑯ Navigation: `is on [Target] page` / `navigate to [Target] page`
+
+```gherkin
+Given User is on [login] page
+Given User is on [awards] page
+When User navigate to [profile] page with {{user_id}}
+Then User see [dashboard] page
+```
+
+**Selector YAML:**
+```yaml
+login:
+  type: 'page'
+  value: '/login'
+
+profile:
+  type: 'page'
+  value: '/users/{{user_id}}/profile'
+```
+
+**Compiler rule:**
+```
+if 'is on' or 'navigate to':
+  code = page.goto(value, { waitUntil: 'networkidle' })
+if 'see':
+  code = expect(page).toHaveURL(regex_from_value)
+```
+
+**Playwright output:**
+```typescript
+// Given: navigate
+await page.goto('/login', { waitUntil: 'networkidle' });
+
+// navigate with data interpolation
+await page.goto('/users/12345/profile', { waitUntil: 'networkidle' });
+
+// Then: assert URL
+await page.waitForLoadState('networkidle');
+await expect(page).toHaveURL(/\/dashboard/);
+```
+
+---
+
+### ⑰ Text assertions: `see [Target] type contains/has text {{Value}}`
+
+```gherkin
+Then User see [Message] text contains {{partial_text}}
+Then User see [Counter] text has text {{exact_count}}
+Then User see [Description] text has text {{full_description}}
+```
+
+**Compiler rule:**
+```
+locator = resolve([Target], type)
+if 'contains': code = expect(locator).toContainText(value)
+if 'has text': code = expect(locator).toHaveText(value)
+```
+
+**Playwright output:**
+```typescript
+// contains (partial match)
+await expect(page.getByText('Message')).toContainText('successfully');
+
+// has text (exact match)
+await expect(locator).toHaveText('42');
+```
+
+---
+
+## Table-Specific Patterns (extended)
+
+### Row count
+
+```gherkin
+Then User see [Users] table has {{row_count}} rows
+```
+
+```typescript
+const table = page.getByRole('table', { name: 'Users' });
+// subtract 1 for header row, or use tbody rows
+await expect(table.locator('tbody').getByRole('row')).toHaveCount(10);
+```
+
+### Column exists
+
+```gherkin
+Then User see [Users] table has [Email] column
+```
+
+```typescript
+await expect(
+  page.getByRole('table', { name: 'Users' }).getByRole('columnheader', { name: 'Email' })
+).toBeVisible();
+```
+
+### Empty state
+
+```gherkin
+Then User see [Users] table is empty
+Then User see [Users] table empty message with {{no_data_text}}
+```
+
+```typescript
+// empty: only header row
+await expect(
+  page.getByRole('table', { name: 'Users' }).locator('tbody').getByRole('row')
+).toHaveCount(0);
+
+// empty message
+await expect(page.getByText('No data available')).toBeVisible();
+```
+
+### Sort column
+
+```gherkin
+When User click [Name] columnheader
+Then User see [Name] columnheader is sorted ascending
+```
+
+```typescript
+await page.getByRole('columnheader', { name: 'Name' }).click();
+await expect(
+  page.getByRole('columnheader', { name: 'Name' })
+).toHaveAttribute('aria-sort', 'ascending');
+```
+
+### Pagination
+
+```gherkin
+When User click [Users] table next page
+When User select [Users] table page size with {{page_size}}
+Then User see [Users] table page info with {{page_info}}
+```
+
+Uses `pagination` from selector YAML:
+```typescript
+await page.locator('[data-testid="next-page"]').click();
+await page.locator('[data-testid="page-size"]').selectOption('25');
+await expect(page.locator('[data-testid="page-info"]')).toHaveText('Showing 1-25 of 100');
+```
+
+### Row expansion
+
+```gherkin
+When User expand [Users] table row with {{user_name}}
+When User collapse [Users] table row with {{user_name}}
+```
+
+```typescript
+const row = table.getByRole('row').filter({ hasText: 'John' });
+await row.getByRole('button', { name: 'Expand' }).click();
+```
+
+---
+
+## Dialog Scope
+
+When a dialog is opened, subsequent steps are scoped within it:
+
+```gherkin
+Then User see [panel] dialog with {{dialog_title}}
+# All steps below are scoped to this dialog:
+When User fill [Email] field with {{email}}
+When User click [Submit] button
+When User wait for [panel] dialog with {{dialog_title}} is hidden
+# Scope ends
+```
+
+**Compiler rule:** Track dialog context. When dialog is visible, wrap all locators:
+
+```typescript
+const dialog = page.getByRole('dialog').filter({ hasText: 'Gửi lời cảm ơn' });
+await expect(dialog).toBeVisible();
+
+// Scoped steps
+await dialog.getByRole('textbox', { name: 'Email' }).fill('test@example.com');
+await dialog.getByRole('button', { name: 'Submit' }).click();
+await dialog.waitFor({ state: 'hidden' });
+```
+
+---
+
+## Frame Scope
+
+Similar to dialog scope, but for iframes:
+
+```gherkin
+When User switch to [Payment] frame
+When User fill [Card number] field with {{card_number}}
+When User fill [Expiry] field with {{expiry_date}}
+When User click [Pay] button
+When User switch to [main] frame
+```
+
+**Compiler rule:** Track frame context.
+
+```typescript
+const frame = page.frameLocator('#payment-iframe');
+await frame.getByRole('textbox', { name: 'Card number' }).fill('4242424242424242');
+await frame.getByRole('textbox', { name: 'Expiry' }).fill('12/28');
+await frame.getByRole('button', { name: 'Pay' }).click();
+// switch to main = reset to page context
+```
+
+---
+
+## Element Type → Role Mapping
+
+| Gherkin type | Playwright role | Locator method |
+|---|---|---|
+| `page` | — | `page.goto(value)` |
+| `button` | `button` | `getByRole('button')` |
+| `link` | `link` | `getByRole('link')` |
+| `field` / `input` | `textbox` | `getByRole('textbox')` |
+| `textarea` | `textbox` | `getByRole('textbox')` or locator for contenteditable |
+| `heading` | `heading` | `getByRole('heading')` |
+| `text` | — | `getByText(value)` |
+| `image` / `img` / `icon` | `img` | `getByRole('img')` |
+| `checkbox` | `checkbox` | `getByRole('checkbox')` |
+| `radio` | `radio` | `getByRole('radio')` |
+| `switch` / `toggle` | `switch` | `getByRole('switch')` |
+| `dropdown` / `select` | `combobox` | `getByRole('combobox')` |
+| `option` | `option` | `getByRole('option')` |
+| `dialog` / `modal` | `dialog` | `getByRole('dialog')` |
+| `menu` | `menu` | `getByRole('menu')` |
+| `menuitem` | `menuitem` | `getByRole('menuitem')` |
+| `tab` | `tab` | `getByRole('tab')` |
+| `tabpanel` | `tabpanel` | `getByRole('tabpanel')` |
+| `list` | `list` | `getByRole('list')` |
+| `listitem` | `listitem` | `getByRole('listitem')` |
+| `table` | `table` | `getByRole('table')` |
+| `row` | `row` | `getByRole('row')` |
+| `cell` | `cell` | `getByRole('cell')` |
+| `column` / `columnheader` | `columnheader` | `getByRole('columnheader')` |
+| `region` / `section` | `region` | `getByRole('region')` |
+| `nav` / `navigation` | `navigation` | `getByRole('navigation')` |
+| `banner` / `header` | `banner` | `getByRole('banner')` |
+| `footer` | `contentinfo` | `getByRole('contentinfo')` |
+| `alert` | `alert` | `getByRole('alert')` |
+| `spinner` / `progressbar` | `progressbar` | `getByRole('progressbar')` |
+| `slider` | `slider` | `getByRole('slider')` |
+| `tree` | `tree` | `getByRole('tree')` |
+| `treeitem` | `treeitem` | `getByRole('treeitem')` |
+| `tooltip` | `tooltip` | `getByRole('tooltip')` |
+| `uploader` / `file` | — | `setInputFiles()` |
+| `frame` / `iframe` | — | `frameLocator()` |
+
+---
+
+## Compiler Rules Summary
+
+### Rule 1: Build locator from selector YAML
+
+```
+locator = buildLocator(selector)
+
+if selector.frame:     base = page.frameLocator(frame)
+elif dialogContext:     base = dialogLocator
+else:                  base = page
+
+if selector.scope:     base = base.getByLabel(scope)
+
+switch selector.type:
+  testid       → base.getByTestId(value)
+  role         → base.getByRole(value, { name, exact })
+  label        → base.getByLabel(value, { exact })
+  placeholder  → base.getByPlaceholder(value, { exact })
+  text         → base.getByText(value, { exact: match=='exact' })
+  locator      → base.locator(value)
+  page         → page.goto(value) or expect(page).toHaveURL()
+  upload       → base.locator(value)
+  frame        → page.frameLocator(value)
+  table        → base.getByRole('table', { name: value })
+
+if selector.nth > 0:   locator = locator.nth(selector.nth)
+```
+
+### Rule 2: Map Gherkin verb to Playwright method
+
+```
+click           → .click()
+double click    → .dblclick()
+fill            → .fill(value) or .pressSequentially(value) if contenteditable
+clear           → .clear()
+check           → .check()
+uncheck         → .uncheck()
+toggle          → .click()
+select (native) → .selectOption(value)
+select (custom) → .click() then getByRole('option', {name}).click()
+upload          → .setInputFiles('specs/storage/' + value)
+hover           → .hover()
+drag ... to     → .dragTo(targetLocator)
+press (global)  → page.keyboard.press(key)
+press (on elem) → locator.press(key)
+scroll to       → .scrollIntoViewIfNeeded()
+expand          → .getByRole('button', {name:'Expand'}).click()
+collapse        → .getByRole('button', {name:'Collapse'}).click()
+```
+
+### Rule 3: Map state to Playwright assertion
+
+```
+see             → expect(locator).toBeVisible()
+see ... hidden  → expect(locator).toBeHidden()
+see ... visible → expect(locator).toBeVisible()
+see ... enabled → expect(locator).toBeEnabled()
+see ... disabled→ expect(locator).toBeDisabled()
+see ... checked → expect(locator).toBeChecked()
+see ... unchecked→ expect(locator).not.toBeChecked()
+see ... focused → expect(locator).toBeFocused()
+see ... empty   → expect(locator).toHaveText('')
+see ... loading → expect(locator).toBeVisible() (spinner/progressbar)
+see ... selected→ expect(locator).toHaveAttribute('aria-selected', 'true')
+see ... sorted ascending  → expect(locator).toHaveAttribute('aria-sort', 'ascending')
+see ... sorted descending → expect(locator).toHaveAttribute('aria-sort', 'descending')
+contains        → expect(locator).toContainText(value)
+has text        → expect(locator).toHaveText(value)
+has (attribute) → expect(locator).toHaveAttribute(attr, value)
+has ... rows    → expect(locator.getByRole('row')).toHaveCount(N)
+has ... column  → expect(locator.getByRole('columnheader', {name})).toBeVisible()
+```
+
+### Rule 4: Scope management
+
+```
+Dialog enter: "see [X] dialog with {{title}}"
+  → dialogLocator = page.getByRole('dialog').filter({ hasText: title })
+  → all subsequent locators use dialogLocator as base
+
+Dialog exit: "wait for [X] dialog with {{title}} is hidden"
+  → dialogLocator.waitFor({ state: 'hidden' })
+  → reset to page context
+
+Frame enter: "switch to [X] frame"
+  → frameLocator = page.frameLocator(value)
+  → all subsequent locators use frameLocator as base
+
+Frame exit: "switch to [main] frame"
+  → reset to page context
+```
+
+### Rule 5: Table operations
+
+```
+Table locator: page.getByRole('table', { name: selector.value })
+
+Row by index:  table.getByRole('row').nth(N)
+Row by filter: table.getByRole('row').filter({ hasText: filterValue })
+Cell by col:   row.getByRole('cell').nth(columns[colName].index)
+Action in row: row.resolve([element])
+
+Count:         expect(table.locator('tbody').getByRole('row')).toHaveCount(N)
+Empty:         expect(table.locator('tbody').getByRole('row')).toHaveCount(0)
+Column exists: expect(table.getByRole('columnheader', { name })).toBeVisible()
+Sort:          table.getByRole('columnheader', { name }).click()
+Pagination:    page.locator(pagination.next).click()
+```
+
+---
+
+## What AI Discover Must Output
+
+When AI visits a page via MCP Playwright, it must produce YAML entries with:
+
+1. **Correct `type`** — detected from accessibility snapshot role
+2. **Correct `name`** — from accessible name in snapshot
+3. **`exact: true`** — when name is a substring of another element's name
+4. **`scope`** — when element appears in multiple landmarks (header + footer)
+5. **`match: exact`** — when text value is substring of other text on page
+6. **`variant`** — for dropdowns: inspect if `<select>` or custom div
+7. **`trigger`** — for uploads: find the visible button near hidden `input[type=file]`
+8. **`contenteditable`** — for rich editors: check if `[contenteditable="true"]`
+9. **`frame`** — for iframes: detect if element is inside a frame
+10. **`columns`** — for tables: map column headers to indices
+
+## What AI Verify Must Fix
+
+When tests fail, AI reads error messages and fixes YAML:
+
+| Error pattern | YAML fix |
+|---|---|
+| `strict mode violation: resolved to N elements` | Add `exact: true` or `scope` or increase `nth` |
+| `element(s) not found` | Fix `name`, `type`, or `value` in YAML |
+| `resolved to N elements` (getByText) | Add `match: 'exact'` |
+| `not visible` / timeout | Element may need scroll, wait, or page didn't load (auth issue) |
+| `intercepted by overlay` | Need to close overlay first (press Escape, click backdrop) |
+| timeout on click | Element in iframe, behind overlay, or auth redirect |
+| `toHaveText` mismatch | Fix expected value in test-data.yaml |
+| `toHaveURL` mismatch | Fix page value in selectors.yaml |
+| `toHaveAttribute` mismatch | Fix attribute/pattern in selectors.yaml |