@sun-asterisk/sungen 2.2.3 → 2.3.0

package/docs/gherkin-dictionary.md

@@ -1,1126 +0,0 @@
-# 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"|"toggle"|"dropdown"|"option"|"dialog"|"modal"
-              | "drawer"|"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"|"tag"
-              | "file"|"frame"|"iframe"|"textarea"|"page"|"search"|"date-picker"
-              | "badge"|"breadcrumb"|"overlay"|"step"|"card"|"item"|"key"
-              | "message"|"label"
-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"
-              | "upload"|"hover"|"drag"|"clear"|"see"|"press"|"expand"
-              | "collapse"|"double click"|"toggle"
-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':
-  if type in (field, textarea, search, dropdown, slider, date-picker):
-    code = expect(locator).toHaveValue(value)    # input types → toHaveValue
-  else:
-    code = expect(locator).toHaveText(value)     # text types → toHaveText (exact match)
-```
-
-**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 → toHaveText (exact match)
-await expect(page.getByRole('heading', { name: 'Welcome' })).toHaveText('Welcome back, Admin');
-
-// see field with value → toHaveValue (input types)
-await expect(page.getByPlaceholder('Email')).toHaveValue('user@example.com');
-
-// see message with value → toHaveText (text types)
-await expect(page.getByText('Error')).toHaveText('Invalid credentials');
-```
-
----
-
-### ③ 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();
-```
-
----
-
-## Browser Alert (System Dialog)
-
-For native browser dialogs (`window.alert`, `window.confirm`, `window.prompt`):
-
-```gherkin
-# Alert steps must appear BEFORE the action that triggers the dialog
-When User click [OK] alert              # accept
-And User click [Delete] button           # triggers the alert
-
-When User click [Cancel] alert           # dismiss
-And User click [Delete] button
-
-When User fill [Name] alert with {{v}}   # fill prompt + accept
-And User click [Rename] button
-
-Then User see [Are you sure?] alert      # assert dialog message
-```
-
-**Compiler rule:**
-```
-click [OK/Accept/Yes/Confirm] alert  → page.once('dialog', d => d.accept())
-click [Cancel/Dismiss/No] alert      → page.once('dialog', d => d.dismiss())
-fill [T] alert with {{v}}           → page.once('dialog', d => d.accept(value))
-see [text] alert                     → Promise-based dialog.message() check
-```
-
-**Playwright output:**
-```typescript
-// accept alert (register BEFORE triggering action)
-page.once('dialog', dialog => dialog.accept());
-await page.getByRole('button', { name: 'Delete' }).click();
-
-// dismiss alert
-page.once('dialog', dialog => dialog.dismiss());
-await page.getByRole('button', { name: 'Delete' }).click();
-
-// fill prompt
-page.once('dialog', dialog => dialog.accept('New name'));
-await page.getByRole('button', { name: 'Rename' }).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')` |
-| `search` | `searchbox` | `getByRole('searchbox')` |
-| `slider` | `slider` | `getByRole('slider')` |
-| `dialog` / `modal` / `drawer` | `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` | `alertdialog` | `getByRole('alertdialog')` or `page.on('dialog')` for browser alerts |
-| `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 with {{v}}  → expect(locator).toHaveText(value)       # text types (message, header, label, row...)
-see with {{v}}  → expect(locator).toHaveValue(value)      # input types (field, textarea, search, dropdown, slider, date-picker)
-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 (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 |