synapse-hub 0.0.0-stage → 2.0.0

package/.agents/skills/playwright-live-interaction/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: playwright-live-interaction
+description: >-
+  Fast live web interaction and interactive debugging via Playwright MCP.
+  Use for rapid feedback, testing selectors, verifying Angular/PrimeNG components,
+  and executing test actions across enterprise web test suites without restarting Katalon/Selenium.
+---
+
+# Playwright Live Interaction & Fast Debugging Handbook (Enterprise Web & Clean POM)
+
+Direct in-browser interaction and rapid debugging via **Playwright MCP Tools** (`browser_run_code_unsafe` / `call_mcp_tool`), executing live JavaScript/Playwright commands without rebuilding or restarting test runs.
+
+---
+
+## 1. Scope & Enterprise Architecture Coverage
+
+All live web flows map strictly to the **Clean Page Object Model Architecture** (`BasePage` + Domain Page Classes in `Keywords/<project_namespace>/pages/` or `pages/*.ts`):
+
+1. **Authentication & Session:** Login, multi-factor, session renewal, profile update, logout.
+2. **Administration & RBAC:** User accounts, roles, permission matrices, tenant management.
+3. **Master Data & System Catalogs:** Lookup dictionaries, unit definitions, category trees.
+4. **Business Workflows & Approvals:** Multi-step submission, validation state gates, approval chains.
+5. **Data Tables & Search:** Server-side pagination, two-phase search filtering, batch mutations.
+6. **Reporting & Analytics:** Dashboard metrics, dynamic chart canvases, Excel/CSV exports.
+7. **Integrations & API Tokens:** Token lifecycle management, webhook verification, data sharing.
+
+### 1.1. Cross-Harness Tool Mapping (Portability Matrix)
+
+To ensure skills operate seamlessly across different AI agent environments:
+
+| Action / Intent | Antigravity MCP | Claude Code / Cursor / Standard Playwright MCP | Vanilla Playwright Script |
+|---|---|---|---|
+| **Run JS in Browser** | `browser_run_code_unsafe` | `browser_evaluate` | `page.evaluate(...)` |
+| **Navigate to URL** | `browser_navigate` | `navigate_page` / `page.goto` | `page.goto(url)` |
+| **Click Element** | `browser_click` | `click_element` | `page.locator(sel).click()` |
+| **Inspect DOM/AOM** | `browser_snapshot` | `get_accessibility_tree` | `page.accessibility.snapshot()` |
+| **Wait for State** | `browser_wait_for` | `wait_for_selector` | `page.waitForSelector(...)` |
+
+---
+
+## 2. Three-Stage Fast-Loop Workflow
+
+```mermaid
+flowchart LR
+    A["1. Flow Discovery<br/>Inspect live DOM & AOM"] --> B["2. Script Generation<br/>Verify 100% selector hit rate"]
+    B --> C["3. In-Place Debugging<br/>Fix error at current screen"]
+    C --> D["4. Codify Clean POM<br/>Package into Page Classes"]
+```
+
+1. **Flow Discovery:** Probe accessibility tree (`accessibility.snapshot()`) or DOM to extract live URLs, menus, and dialogs in under 2 minutes.
+2. **Script Generation:** Test selectors live (`await page.locator(...).count() > 0`). Only codify when the selector hits 100% in 200ms.
+3. **In-Place Debugging:** When step $N$ fails, **keep the browser paused at that step**. Use `page.evaluate()` to diagnose disabled buttons, obscuring overlays, or validation errors. Fix in place; never re-run from step 1.
+
+---
+
+## 3. Mapping Matrix (Playwright Live Code ↔ Clean POM)
+
+| UI Action | Playwright Live Code (MCP) | Clean POM Groovy / Java Code | Clean POM TypeScript (Playwright) |
+|---|---|---|---|
+| **Fill Input** | `await page.locator(sel).fill(val);` | `WebElement el = findElement(By.cssSelector(sel)); jsSetInput(el, val);` | `await this.inputField.fill(val);` |
+| **Safe Click / Overlay** | `await page.locator(sel).click();` | `WebElement el = findElement(By.cssSelector(sel)); clickElement(el);` | `await this.submitButton.click();` |
+| **Dropdown Selection** | `await page.locator('p-dropdown').click(); await page.locator('.p-dropdown-item:has-text("X")').click();` | `selectDropdownByText(dropdownEl, "X")` | `await this.dropdown.selectOption("X");` |
+| **Calendar Picker** | Synthetic `input` + `change` event | `jsSetInput(calendarInput, "25/10/2026")` | `await this.datePicker.fill("2026-10-25");` |
+| **Catch Success Toast** | `await page.waitForSelector('.toast-success')` | `verifyToastMessage("Success")` | `await expect(this.toast).toBeVisible();` |
+| **Two-Phase Search** | Click search icon -> Enter Keyword -> Enter | `searchRecord(keyword)` in Page Class | `await this.search(keyword);` |
+| **Delete & Confirm** | Click Trash -> Accept Confirm -> Verify Gone | `deleteRecord(keyword)` in Page Class | `await this.delete(keyword);` |
+
+---
+
+## 4. Pre-Codify Quality Checklist
+
+Mandatory 5-point verification before committing POM code:
+- [x] **100% UTF-8 No BOM:** Must NOT contain `0xEF, 0xBB, 0xBF`.
+- [x] **Flat Architecture:** Zero raw XPaths or unencapsulated selectors in test scripts.
+- [x] **Dynamic Test Data:** Use `BasePage.uniqueCode("PREFIX_")`; no static colliding strings.
+- [x] **Truth Anchor (No Fake Pass):** Real toast assertions or live data table row verification.
+- [x] **Synthetic Event Dispatch:** 100% framework inputs trigger synthetic `input` and `change` events.
+
+---
+
+## 5. Reference Documentation (Progressive Disclosure)
+
+- [**20 Complete UI Recipes**](references/recipes.md): Code recipes for Auth, Data Tables, Dropdowns, Modals, Confirm Dialogs, File Upload, Calendar, MultiSelect, Stale Retries, Form Audit, Smart Action Batching, and Self-Healing Locators.
+- [**Runtime Browser Helper (`tools/browser_helpers.js`)**](tools/browser_helpers.js): Unified JavaScript module providing `window.__qa` (`batch`, `audit`, `heal`, `clickSafe`, `exportSession`).
+- [**5 Superpowers & 5 AI Paradigms**](references/advanced_superpowers.md): Zero-Second Auth (`session.json`), Direct API Seeding, AOM Snapshots, Multi-Context Dual Role, Route Mocking, Self-Healing Locators, Fuzzing, CDP Profiling.
+- [**Multi-Agent Swarm Orchestration**](references/swarm_orchestration.md): Specialized swarm roles and collaboration protocol.

package/.agents/skills/playwright-live-interaction/references/advanced_superpowers.md

@@ -0,0 +1,160 @@
+# 5 Advanced Superpowers & 5 AI Paradigms for Playwright Live Interaction
+
+In-depth technical reference for complex testing scenarios across enterprise web test suites.
+
+---
+
+## 1. Five Native Advanced Superpowers
+
+### 1.1. Zero-Second Auth (Bypass Login Form)
+```javascript
+// Step 1: Save storage state after login
+async (page) => {
+  await page.context().storageState({ path: '.agents/session.json' });
+  return { status: "Session saved successfully" };
+}
+
+// Step 2: Load stored session in subsequent contexts
+const context = await browser.newContext({ storageState: '.agents/session.json' });
+```
+
+### 1.2. Network Interception & Direct Seeding
+```javascript
+async (page) => {
+  page.on('request', request => {
+    if (request.url().includes('/api/') && request.method() === 'POST') {
+      console.log('API URL:', request.url());
+      console.log('Headers:', request.headers());
+      console.log('Payload:', request.postData());
+    }
+  });
+}
+```
+
+### 1.3. Accessibility Tree (AOM Snapshot — 90% Token Reduction)
+```javascript
+async (page) => {
+  const a11yTree = await page.accessibility.snapshot({
+    interestingOnly: true // Captures interactive elements only
+  });
+  return a11yTree;
+}
+```
+
+### 1.4. Multi-Context Dual Role Testing (Parallel Roles)
+```javascript
+async (browser) => {
+  const specialistContext = await browser.newContext();
+  const leaderContext = await browser.newContext();
+
+  const pageSpecialist = await specialistContext.newPage();
+  const pageLeader = await leaderContext.newPage();
+
+  // Specialist submits dossier
+  await pageSpecialist.goto('https://app.example.com/planning');
+  // Leader reviews and approves
+  await pageLeader.goto('https://app.example.com/planning-approval');
+}
+```
+
+### 1.5. API Route Mocking (Negative Scenarios & Fault Injection)
+```javascript
+async (page) => {
+  await page.route('**/api/**', route => {
+    route.fulfill({
+      status: 500,
+      contentType: 'application/json',
+      body: JSON.stringify({ message: 'Database connection failed!' })
+    });
+  });
+
+  await page.locator('button:has-text("Lưu")').click();
+  await page.waitForTimeout(500);
+  const toastMsg = await page.locator('.p-toast-message').innerText();
+  return { toastMsg };
+}
+```
+
+---
+
+## 2. Five AI Engineering Paradigms
+
+### 2.1. Self-Healing Locator Engine (Multi-Tier Fallback)
+```javascript
+async (page, targetName) => {
+  const strategies = [
+    () => page.locator(`button[formcontrolname="${targetName}"]`),
+    () => page.getByRole('button', { name: targetName }),
+    () => page.locator(`button:has-text("${targetName}")`),
+    () => page.locator(`button[title*="${targetName}"]`),
+    () => page.locator(`.p-button:has-text("${targetName}")`)
+  ];
+
+  for (const getLocator of strategies) {
+    const loc = getLocator();
+    if (await loc.count() > 0 && await loc.first().isVisible()) {
+      return loc.first(); // Self-healed successfully
+    }
+  }
+  throw new Error(`Self-healing failed: Element not found: ${targetName}`);
+}
+```
+
+### 2.2. Multimodal Visual Verification (GIS & Layout)
+```javascript
+async (page) => {
+  const mapElement = page.locator('div.ol-viewport');
+  const screenshotBuffer = await mapElement.screenshot({ path: '.agents/screenshots/gis_canvas_live.png' });
+  const box = await mapElement.boundingBox();
+  return {
+    isRenderedProperly: box && box.width > 300 && box.height > 200,
+    width: box ? box.width : 0,
+    height: box ? box.height : 0,
+    screenshotPath: '.agents/screenshots/gis_canvas_live.png'
+  };
+}
+```
+
+### 2.3. Autonomous Exploratory Fuzzing (Edge & Crash Hunting)
+```javascript
+async (page) => {
+  const edgePayloads = [
+    "'-DROP TABLE--",
+    "<script>alert(1)</script>",
+    "-99999999",
+    "   ",
+    "A".repeat(500)
+  ];
+  const results = [];
+  const input = page.locator('input[formcontrolname="code"]').first();
+
+  for (const payload of edgePayloads) {
+    await input.fill(payload);
+    await page.locator('button:has-text("Lưu"), button:has-text("Xác nhận")').first().click();
+    await page.waitForTimeout(600);
+
+    const hasCrash = await page.evaluate(() => {
+      const text = document.body.innerText;
+      return text.includes('500 Internal') || text.includes('HttpErrorResponse');
+    });
+    results.push({ payload, hasCrash });
+  }
+  return results;
+}
+```
+
+### 2.4. CDP Deep Profiling (RAM & Heap Monitoring)
+```javascript
+async (page) => {
+  const memoryInfo = await page.evaluate(() => {
+    return window.performance && window.performance.memory ? {
+      usedJSHeapSizeMB: (window.performance.memory.usedJSHeapSize / (1024 * 1024)).toFixed(2),
+      totalJSHeapSizeMB: (window.performance.memory.totalJSHeapSize / (1024 * 1024)).toFixed(2)
+    } : { note: "Memory API only available in Chromium" };
+  });
+  return memoryInfo;
+}
+```
+
+### 2.5. Multi-Agent Swarm Orchestration
+For swarm roles (Lead Orchestrator, Live Explorer, Code Crafter, Test Runner, Quality Gatekeeper, Scribe), refer to [swarm_orchestration.md](swarm_orchestration.md).

package/.agents/skills/playwright-live-interaction/references/compact_accessibility_snapshots.md

@@ -0,0 +1,75 @@
+# Compact Accessibility-Tree Snapshots for PrimeNG Inspection
+
+*(Inherited from `vercel-labs/agent-browser`)*
+
+A token-efficient browser inspection technique for exploring enterprise Angular & PrimeNG single-page interface without dumping heavy raw DOM HTML.
+
+---
+
+## 1. Problem: The Raw HTML Token Trap
+
+On modern Angular/PrimeNG applications:
+- A single complex screen (e.g. `DataMiningPage` with GIS Canvas, sidebar, and multi-field dialogs) contains **3,000+ lines of HTML**.
+- Dumping raw DOM trees consumes **15,000 to 30,000 tokens** per inspection, cluttering the agent's context window.
+
+---
+
+## 2. Solution: Semantic Accessibility Snapshot
+
+Following the `agent-browser` architecture, we extract a **Compact Accessibility Tree** focused exclusively on interactive elements (`button`, `input`, `select`, `p-dropdown`, `p-calendar`, `p-table` headers and rows) assigned with lightweight identifier references (`@e1`, `@e2`, ...).
+
+### 2.1. In-Browser JavaScript Extractor
+Inject the following lightweight snippet via Playwright browser evaluate:
+
+```javascript
+(() => {
+  const interactiveSelectors = [
+    'button:not([disabled])',
+    'input:not([type="hidden"])',
+    'select',
+    'textarea',
+    'p-dropdown',
+    'p-calendar input',
+    'p-multiselect',
+    'a[href]',
+    '[role="button"]',
+    '[role="dialog"]',
+    '.p-toast-message'
+  ];
+  
+  const elements = Array.from(document.querySelectorAll(interactiveSelectors.join(',')))
+    .filter(el => {
+      const rect = el.getBoundingClientRect();
+      return rect.width > 0 && rect.height > 0 && window.getComputedStyle(el).visibility !== 'hidden';
+    });
+
+  return elements.map((el, idx) => {
+    const tag = el.tagName.toLowerCase();
+    const type = el.getAttribute('type') || '';
+    const name = el.getAttribute('name') || el.getAttribute('formcontrolname') || '';
+    const label = (el.innerText || el.placeholder || el.getAttribute('aria-label') || el.title || '').trim().replace(/\s+/g, ' ').slice(0, 50);
+    const role = el.getAttribute('role') || tag;
+    return `[@e${idx + 1}] <${tag}${type ? ' type=' + type : ''}${name ? ' name=' + name : ''}> "${label}"`;
+  }).join('\n');
+})();
+```
+
+### 2.2. Sample Compact Output (Under 500 Tokens vs 25,000 Tokens)
+
+```text
+[@e1] <input name=username> "Tên đăng nhập"
+[@e2] <input type=password name=password> "Mật khẩu"
+[@e3] <button type=submit> "Đăng nhập"
+[@e4] <p-dropdown name=layerSelect> "Chọn lớp dữ liệu"
+[@e5] <input placeholder="Nhập từ khóa tìm kiếm..."> "Tìm kiếm"
+[@e6] <button> "Thêm mới"
+[@e7] <button title="Xóa"> "Xóa"
+```
+
+---
+
+## 3. Benefits for Enterprise Test Automation
+
+1. **Token Savings:** Reduces DOM inspection size by **90% - 95%**.
+2. **Speed:** Instant parsing in `< 20ms`.
+3. **Selector Mapping:** Once an element reference `@eN` is identified on screen, map it directly into the Clean POM Page Class using `BasePage.x()`.