chrometools-mcp 3.3.8 → 3.4.0

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.4.0] - 2026-02-08
+
+### Added
+- **Adaptive click strategy with elementFromPoint pre-check** — Before each click, verifies the target element is topmost via `document.elementFromPoint()`. If covered by another element (e.g. small button under `<a routerLink>`), uses DOM dispatch to bypass coordinate hit-testing. Fixes clicks on absolutely-positioned elements over links.
+- **Auth redirect detection** — `navigateTo`, `openBrowser`, and `click` now warn when landing on a login page with returnUrl parameter. Broad login detection: password forms, phone/OTP forms, URL path (`/login`, `/signin`, `/auth`), CSS class matching.
+- **Post-click element detachment detection** — Detects when clicked element is removed from DOM during click (Angular `*ngFor` + Zone.js pattern). Shows actionable hint with app fix (trackBy) and executeScript workaround.
+- **Auth redirect in post-click diagnostics** — `formatDiagnosticsForAI` detects navigation to login pages with returnUrl and shows targeted warning.
+
+### Performance
+- **findElementsByText early exit** — Stops DOM traversal at 40 results, preventing 120s timeout on heavy Angular Material pages with CDK overlay.
+
+## [3.3.9] - 2026-02-08
+
+### Added
+- **AI Hints: modal content extraction** — Modals now show title, body text (200 chars), and action buttons
+  - Expanded selectors: mat-dialog-container, cdk-overlay-pane, `[class*="dialog"]`
+  - Topmost modal dedup for pages with multiple modals
+  - Actions extracted from `.modal-footer` / `[mat-dialog-actions]` (limit 5)
+
+- **AI Hints: dropdown/menu item extraction** — Overlays now list actual option texts
+  - 11 overlay selectors: Angular CDK/Material, PrimeNG, Ant Design, custom `select-options`
+  - Menu vs dropdown auto-classification (role="menu", role="listbox", menuitem detection)
+  - Item text extraction (limit 10 items, shows total count)
+  - Deduplication of nested overlay elements
+
+- **AI Hints: page heading in navigation** — `navigateTo` and `openBrowser` now show page heading
+  - Extracts h1 or `.page-title` / `[class*="page-title"]` fallback for SPAs
+  - Filters sr-only/visually-hidden elements (clip, 1px size, opacity)
+  - 500ms SPA render delay for Angular/React/Vue frameworks
+
+- **Swagger/OpenAPI tools** — `loadSwagger` and `generateApiModels` (Phase 1)
+  - `loadSwagger`: Parse OpenAPI 2.0/3.x specs from URL or file (JSON/YAML)
+  - `generateApiModels`: Generate TypeScript interfaces or Python models (dataclass/pydantic/TypedDict)
+  - $ref resolution, enum generation, snake_case conversion for Python
+  - Supports filtering specific schemas
+
+- **Page Object Model integration in exported tests** — `pageObjectMode` parameter
+  - `generate-integrated`: Generate POM + test using it
+  - `use-existing`: Generate test referencing existing POM file
+  - Works with `exportScenarioAsCode` and `appendScenarioToFile`
+
+- **Synthetic drag mode** — `drag` tool now supports `mode: 'synthetic'`
+  - Better compatibility with JS libraries (frappe-gantt, jQuery UI, Sortable.js)
+  - Native mode (default) for standard HTML drag operations
+
+- **analyzePage: framework click handler detection** — Detect addEventListener-based handlers
+  - APOM IDs returned from `smartFindElement` and `findElementsByText`
+
+### Fixed
+- Swagger Phase 1 code review fixes (error handling, edge cases)
+
 ## [3.3.8] - 2026-02-03
 
 ### Added

package/README.md

@@ -7,7 +7,7 @@
 ## Why ChromeTools MCP?
 
 **For AI Agents & Developers:**
-- 🎯 **54 specialized tools** for browser automation - from simple clicks to Figma comparisons
+- 🎯 **56 specialized tools** for browser automation - from simple clicks to Figma comparisons
 - 🧠 **APOM (Agent Page Object Model)** - AI-friendly page representation (~8-10k tokens vs 15-25k for screenshots)
 - 🔄 **Persistent browser sessions** - pages stay open between commands for iterative workflows
 - ⚡ **Framework-aware** - handles React, Vue, Angular events and state updates automatically
@@ -219,7 +219,7 @@ The Chrome Extension is **required** for scenario recording and other advanced f
 - [Installation](#installation)
   - [Chrome Extension Setup](#chrome-extension-setup)
 - [AI Optimization Features](#ai-optimization-features)- [Scenario Recorder](#scenario-recorder)  - Visual UI-based recording with smart optimization
-- [Available Tools](#available-tools) - **46+ Tools Total**
+- [Available Tools](#available-tools) - **48+ Tools Total**
   - [AI-Powered Tools](#ai-powered-tools)  - smartFindElement, analyzePage, getElementDetails, findElementsByText
   - [Core Tools](#1-core-tools) - ping, openBrowser
   - [Interaction Tools](#2-interaction-tools) - click, type, scrollTo, selectOption, selectFromGroup, drag, scrollHorizontal
@@ -227,6 +227,7 @@ The Chrome Extension is **required** for scenario recording and other advanced f
   - [Advanced Tools](#4-advanced-tools) - executeScript, getConsoleLogs, listNetworkRequests, getNetworkRequest, filterNetworkRequests, hover, setStyles, setViewport, getViewport, navigateTo
   - [Tab Management Tools](#5-tab-management-tools)  - listTabs, switchTab
   - [Recorder Tools](#7-recorder-tools)  - enableRecorder, executeScenario, listScenarios, searchScenarios, getScenarioInfo, deleteScenario, exportScenarioAsCode, appendScenarioToFile, generatePageObject
+  - [API / Swagger Tools](#8-api--swagger-tools) - loadSwagger, generateApiModels
 - [Typical Workflow Example](#typical-workflow-example)
 - [Tool Usage Tips](#tool-usage-tips)
 - [Configuration](#configuration)
@@ -260,7 +261,7 @@ AI: smartFindElement("login button")
 
 1. **`analyzePage`** - 🔥 **USE FREQUENTLY** - Get current page state after loads, clicks, submissions (cached, use refresh:true)
 2. **`smartFindElement`** - Natural language element search with multilingual support
-3. **AI Hints** - Automatic context in all tools (page type, available actions, suggestions)
+3. **AI Hints** - Automatic context in all tools (page type, page heading, modal content, dropdown/menu items, suggestions)
 4. **Text search** - `findElementsByText` for finding elements by visible text
 
 **Performance:** 3-5x faster, 5-10x fewer requests
@@ -499,6 +500,10 @@ Click an element with optional result screenshot. **PREFERRED**: Use APOM ID fro
 - **Use case**: Buttons, links, form submissions, Django admin forms
 - **Returns**: Confirmation text + optional screenshot + network diagnostics
 - **Performance**: 2-10x faster without screenshot, instant with skipNetworkWait
+- **Click strategy**: Three-tier fallback for maximum compatibility:
+  1. Puppeteer native click (trusted CDP events)
+  2. CDP coordinate click at element center (trusted, bypasses interception check)
+  3. JavaScript `element.click()` (untrusted, last resort)
 - **Example**:
   ```javascript
   // PREFERRED: Using APOM ID
@@ -603,10 +608,16 @@ Drag element by mouse (click-hold-move-release). Simulates real mouse drag, not
   - `direction` (required): 'up', 'down', 'left', 'right', 'up-left', 'up-right', 'down-left', 'down-right'
   - `distance` (optional): Distance in pixels (default: 100)
   - `duration` (optional): Drag duration in milliseconds (default: 500)
+  - `mode` (optional): 'native' (default) or 'synthetic'
+    - **'native'**: Uses Puppeteer mouse API - faster, works for most cases
+    - **'synthetic'**: Dispatches DOM events (pointerdown/pointermove/pointerup) - better compatibility with JS libraries (frappe-gantt, jQuery UI Draggable, custom drag handlers)
 - **Use case**: Interactive maps (Google Maps, Leaflet), Gantt charts, SVG diagrams, canvas elements, sliders, drag-to-pan interfaces
-- **How it works**: Moves mouse to element center, presses mouse button, drags to target position, releases button
+- **How it works**:
+  - **Native mode**: Uses Puppeteer's mouse API (mousedown → mousemove → mouseup)
+  - **Synthetic mode**: Dispatches PointerEvent/MouseEvent on element with intermediate pointermove events during drag
+- **When to use synthetic mode**: If native drag doesn't trigger JS library event handlers (e.g., frappe-gantt, jQuery UI, React DnD)
 - **NOT for**: Standard overflow scrollbars (use `scrollTo` or `scrollHorizontal` instead)
-- **Returns**: Start/end mouse positions and drag delta
+- **Returns**: Start/end mouse positions, drag delta, and mode used
 
 #### scrollHorizontal
 Scroll element horizontally (for tables, carousels, wide content).
@@ -1118,17 +1129,24 @@ Delete a scenario and its associated secrets. Searches all projects to find the
   - `language` (required): Target framework - `"playwright-typescript"`, `"playwright-python"`, `"selenium-python"`, `"selenium-java"`
   - `cleanSelectors` (optional): Remove unstable CSS classes (default: true)
   - `includeComments` (optional): Include descriptive comments (default: true)
-  - `generatePageObject` (optional): Also generate Page Object class for the page (default: false)
+  - `generatePageObject` (optional): Also generate Page Object class for the page (default: false). Legacy - use `pageObjectMode` instead.
   - `pageObjectClassName` (optional): Custom Page Object class name (auto-generated if not provided)
+  - `pageObjectMode` (optional): POM integration mode:
+    - `"none"` (default) - no Page Object
+    - `"generate"` - generate separate POM file (same as `generatePageObject: true`)
+    - `"generate-integrated"` - generate POM + test that **uses** POM methods (imports, instantiates, calls POM methods)
+    - `"use-existing"` - generate test that uses an **existing** POM file (requires `pageObjectFile`)
+  - `pageObjectFile` (optional): Path to existing POM file (required for `"use-existing"` mode)
 
-- **Use case**: Create new test files from recorded scenarios with optional Page Objects
+- **Use case**: Create new test files from recorded scenarios with optional Page Object integration
 
 - **Returns**: JSON with:
   - `action`: `"create_new_file"`
   - `suggestedFileName`: Suggested test filename
   - `testCode`: Full test code with imports
   - `instruction`: Instructions for Claude Code
-  - `pageObject` (if `generatePageObject=true`): Page Object code and metadata
+  - `pageObject` (if POM generated): Page Object code and metadata
+  - `pomIntegration` (if POM integrated): `{ className, mode }` info
 
 - **Example 1 - Test only**:
   ```javascript
@@ -1147,29 +1165,46 @@ Delete a scenario and its associated secrets. Searches all projects to find the
   }
   ```
 
-- **Example 2 - Test + Page Object**:
+- **Example 2 - Test + separate Page Object** (legacy):
   ```javascript
-  // Export with Page Object class
   exportScenarioAsCode({
     scenarioName: "login_test",
     language: "playwright-typescript",
     generatePageObject: true,
     pageObjectClassName: "LoginPage"
   })
+  ```
 
-  // Returns JSON with both files:
-  {
-    "action": "create_new_file",
-    "suggestedFileName": "login_test.spec.ts",
-    "testCode": "import { test } from '@playwright/test';\nimport { LoginPage } from './LoginPage';\n\ntest('login_test', async ({ page }) => {\n  const loginPage = new LoginPage(page);\n  await loginPage.goto();\n  await loginPage.fillEmailInput('user@test.com');\n  await loginPage.clickLoginButton();\n});",
-    "pageObject": {
-      "code": "import { Page, Locator } from '@playwright/test';\n\nexport class LoginPage { ... }",
-      "className": "LoginPage",
-      "suggestedFileName": "LoginPage.ts",
-      "elementCount": 12
-    },
-    "instruction": "Create a new test file 'login_test.spec.ts' with the testCode. Also create a Page Object file 'LoginPage.ts' with the pageObject.code."
-  }
+- **Example 3 - Test + integrated Page Object** (recommended):
+  ```javascript
+  // Generate POM and test that USES POM methods (not raw selectors)
+  exportScenarioAsCode({
+    scenarioName: "login_test",
+    language: "playwright-typescript",
+    pageObjectMode: "generate-integrated",
+    pageObjectClassName: "LoginPage"
+  })
+
+  // Returns test code using POM:
+  // import { LoginPage } from './LoginPage';
+  // test('login_test', async ({ page }) => {
+  //   const loginPage = new LoginPage(page);
+  //   await loginPage.goto();
+  //   await loginPage.fillUsername('admin');
+  //   await loginPage.clickLoginBtn();
+  // });
+  ```
+
+- **Example 4 - Test using existing POM file**:
+  ```javascript
+  // Use pre-existing Page Object file
+  exportScenarioAsCode({
+    scenarioName: "login_test",
+    language: "playwright-typescript",
+    pageObjectMode: "use-existing",
+    pageObjectFile: "./pages/LoginPage.ts"
+  })
+  // Test will import and use methods from the existing LoginPage
   ```
 
 - **Selector Cleaning**: Automatically removes unstable patterns:
@@ -1191,8 +1226,10 @@ Append recorded scenario as test code to an **EXISTING** test file. Automaticall
   - `referenceTestName` (optional): Reference test name for 'before'/'after' insertion
   - `cleanSelectors` (optional): Remove unstable CSS classes (default: true)
   - `includeComments` (optional): Include descriptive comments (default: true)
-  - `generatePageObject` (optional): Also generate Page Object class for the page (default: false)
+  - `generatePageObject` (optional): Also generate Page Object class for the page (default: false). Legacy - use `pageObjectMode` instead.
   - `pageObjectClassName` (optional): Custom Page Object class name (auto-generated if not provided)
+  - `pageObjectMode` (optional): POM integration mode - `"none"`, `"generate"`, `"generate-integrated"`, `"use-existing"` (see exportScenarioAsCode for details)
+  - `pageObjectFile` (optional): Path to existing POM file (required for `"use-existing"` mode)
 
 - **Use case**: Add tests to existing test files without overwriting current tests
 
@@ -1325,6 +1362,78 @@ Append recorded scenario as test code to an **EXISTING** test file. Automaticall
   - `selenium-python`: Selenium with Python (WebDriver, explicit waits, By locators)
   - `selenium-java`: Selenium with Java (WebDriver, Page Factory compatible)
 
+### 8. API / Swagger Tools
+
+Tools for loading OpenAPI/Swagger specs and generating typed API models.
+
+#### `loadSwagger`
+
+Parse an OpenAPI 2.0 (Swagger) or 3.x spec and return a structured summary of endpoints, schemas, and auth.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `source` | string | Yes | URL (`https://...`) or local file path to `swagger.json` / `openapi.yaml` |
+| `format` | `'auto'` \| `'json'` \| `'yaml'` | No | Parse format (default: `auto` — detects from content) |
+
+**Response includes:**
+- API title, version, base URL
+- All endpoints with method, path, operationId, parameters, request body, responses
+- Schema summaries (property names, types, enums)
+- Auth schemes (Bearer, API key, OAuth2)
+
+```javascript
+// Load from URL
+loadSwagger({ source: "https://petstore.swagger.io/v2/swagger.json" })
+
+// Load from local file
+loadSwagger({ source: "/path/to/openapi.yaml" })
+```
+
+#### `generateApiModels`
+
+Generate TypeScript interfaces or Python dataclasses/pydantic models from an OpenAPI spec.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `source` | string | Yes | URL or file path to spec |
+| `language` | `'typescript'` \| `'python'` | Yes | Target language |
+| `format` | `'auto'` \| `'json'` \| `'yaml'` | No | Parse format (default: `auto`) |
+| `style` | `'interface'` \| `'type'` | No | TypeScript style (default: `interface`) |
+| `pythonStyle` | `'dataclass'` \| `'pydantic'` \| `'typeddict'` | No | Python style (default: `dataclass`) |
+| `includeEnums` | boolean | No | Generate enum types (default: `true`) |
+| `schemas` | string[] | No | Filter to specific schema names |
+
+**Features:**
+- Topological sort ensures correct declaration order
+- Enum deduplication (property enums reuse top-level enums)
+- `allOf` → extends/inheritance, `oneOf`/`anyOf` → union types
+- Circular reference detection with forward references
+- Swagger 2.0 automatically normalized to OpenAPI 3.x
+
+```javascript
+// Generate TypeScript interfaces
+generateApiModels({
+  source: "https://petstore.swagger.io/v2/swagger.json",
+  language: "typescript"
+})
+// Returns: { code: "export interface Pet { ... }", suggestedFileName: "pet-store-api.models.ts" }
+
+// Generate Python pydantic models
+generateApiModels({
+  source: "/path/to/openapi.yaml",
+  language: "python",
+  pythonStyle: "pydantic"
+})
+// Returns: { code: "class Pet(BaseModel): ...", suggestedFileName: "pet_store_api_models.py" }
+
+// Generate only specific schemas
+generateApiModels({
+  source: "https://api.example.com/openapi.json",
+  language: "typescript",
+  schemas: ["User", "Order"]
+})
+```
+
 ---
 
 ## Typical Workflow Example
@@ -1817,6 +1926,32 @@ npx chrometools-mcp --install-bridge
 - Close and reopen Chrome
 - Check Extension Service Worker console for errors
 
+## Known Limitations
+
+### Angular *ngFor with Dynamic Bindings
+
+In Angular apps using Zone.js, **any** programmatic click (including CDP trusted events) can trigger change detection **between** event listener callbacks. If `*ngFor` iterates over a getter that returns a new array reference each time (e.g., `[options]="getOptions()"`), Angular destroys and recreates all child elements mid-dispatch, causing `@HostListener('click')` on the target element to never fire. Only real hardware mouse events (physical mouse) are immune — CDP events, despite being `isTrusted: true`, are not dispatched through the OS event queue.
+
+ChromeTools **automatically detects** this: after each click, it checks if the target element was removed from DOM. If so, the `ELEMENT DETACHED` hint is shown with a workaround guide.
+
+**App fix** (recommended): add `trackBy` to `*ngFor`, or cache the array reference instead of returning a new one each time.
+
+**Workaround** when app fix is not possible — use `executeScript` to call the Angular component API directly:
+```javascript
+// 1. Find the component instance
+executeScript({ script: `
+  const comp = ng.getComponent(document.querySelector('my-component'));
+  // 2. Explore available events
+  Object.keys(comp).filter(k => k.includes('Event'));
+` })
+
+// 3. Emit the event directly (bypasses DOM click entirely)
+executeScript({ script: `
+  const comp = ng.getComponent(document.querySelector('my-component'));
+  comp.selectedOptionChangeEvent.emit(comp.options.find(o => o.name === 'Delete'));
+` })
+```
+
 ## Architecture
 
 - **Puppeteer** for Chrome automation

package/SPEC-pom-integration.md

@@ -0,0 +1,227 @@
+# Спецификация: Интеграция Page Object Model в экспортируемые тесты
+
+## Контекст
+
+QA-автоматизаторы жалуются, что тесты, экспортируемые через `exportScenarioAsCode` / `appendScenarioToFile`, **не используют Page Object**. Даже при `generatePageObject: true` генерируются два несвязанных файла — тест с raw-селекторами и POM-класс отдельно.
+
+**Сейчас** (raw-селекторы):
+```typescript
+test('login', async ({ page }) => {
+  await page.goto('https://example.com/login');
+  await page.locator('#username').fill('admin');
+  await page.locator('#password').fill('secret');
+  await page.locator('#login-btn').click();
+});
+```
+
+**Нужно** (POM-интеграция):
+```typescript
+import { LoginPage } from './LoginPage';
+
+test('login', async ({ page }) => {
+  const loginPage = new LoginPage(page);
+  await loginPage.goto();
+  await loginPage.fillUsername('admin');
+  await loginPage.fillPassword('secret');
+  await loginPage.clickLoginBtn();
+});
+```
+
+## Подход
+
+Добавить новый параметр `pageObjectMode` к тулам экспорта. Два сценария:
+
+1. **`generate-integrated`** — сгенерировать POM + тест, который его использует
+2. **`use-existing`** — прочитать существующий POM-файл, сгенерировать тест, который его использует
+
+Ключевой механизм — **selector matching**: сопоставление селекторов из записанного сценария с локаторами POM-элементов.
+
+## Изменения по файлам
+
+### 1. Новый файл: `utils/code-generators/pom-integrator.js`
+
+Модуль связки POM с экшнами сценария:
+
+- **`matchActionToPomElement(actionSelector, pomElements)`** — сопоставляет селектор экшна с элементом POM:
+  1. Exact match (`#username` === `#username`)
+  2. Normalized match (strip tag prefix: `input#username` → `#username`)
+  3. Key-based match (извлечь id/name/data-testid и сравнить значения)
+  4. Не найдено → null (fallback на raw-селектор)
+
+- **`parsePomFile(fileContent, framework)`** — парсит существующий POM-файл regex'ами, возвращает `{ className, elements: [{name, selector, methodName, methodType}] }`:
+  - Playwright TS: ищет `this.X = page.locator('...')` и `async fillX(` / `async clickX(`
+  - Playwright Python: ищет `self.X = page.locator('...')` и `def fill_X(` / `def click_X(`
+  - Selenium Python: ищет `X = (By.CSS_SELECTOR, '...')` и `def fill_X(` / `def click_X(`
+  - Selenium Java: ищет `By X = By.cssSelector("...")` и `void fillX(` / `void clickX(`
+
+### 2. Изменить: `recorder/page-object-generator.js`
+
+Добавить в return `generatePageObject()` поле **`elements`** — массив структурированных метаданных:
+```js
+elements: uniqueElements.map(el => ({
+  name: sanitizeIdentifier(el.name, lang),
+  selector: el.selector,
+  tag: el.tag,
+  type: el.type,
+  methodName: generateMethodName(el, framework), // "fillUsername" / "clickSubmit"
+  methodType: getMethodType(el)  // "fill" | "click" | "select"
+}))
+```
+Добавить вспомогательные функции `generateMethodName()` и `getMethodType()` (логика уже есть в `generateActionMethods()`, нужно её вынести).
+
+### 3. Изменить: `utils/code-generators/code-generator-base.js`
+
+Добавить в конструктор опции `pomElements`, `pomClassName`, `pomImportPath`.
+
+Добавить методы с дефолтными реализациями (no-op):
+- `generatePomImports(className, importPath)` → `[]`
+- `generatePomInstantiation(className)` → `[]`
+- `generatePomAction(action, pomElement)` → `null` (значит fallback)
+
+Модифицировать `generate()` и `generateTestOnly()`:
+```js
+// После generateImports(), если POM mode:
+if (this.options.pomClassName) {
+  lines.push(...this.generatePomImports(this.options.pomClassName, this.options.pomImportPath));
+}
+
+// После generateTestHeader(), если POM mode:
+if (this.options.pomClassName) {
+  lines.push(...this.generatePomInstantiation(this.options.pomClassName));
+}
+
+// В цикле экшнов:
+for (const action of scenario.chain) {
+  let actionCode = null;
+  if (this.options.pomElements) {
+    const match = matchActionToPomElement(this.prepareSelector(action), this.options.pomElements);
+    if (match) {
+      actionCode = this.generatePomAction(action, match);
+    }
+  }
+  if (!actionCode) {
+    actionCode = this.generateAction(action);
+  }
+  if (actionCode?.length > 0) lines.push(...actionCode);
+}
+```
+
+Специальная обработка `navigate` → если URL совпадает с POM entryUrl, заменить на `pomInstance.goto()`.
+
+### 4. Изменить: `playwright-typescript.js`
+
+Реализовать 3 POM-метода:
+```js
+generatePomImports(className, importPath) {
+  return [`import { ${className} } from '${importPath || './' + className}';`];
+}
+
+generatePomInstantiation(className) {
+  const varName = className.charAt(0).toLowerCase() + className.slice(1);
+  return [this.indent(`const ${varName} = new ${className}(page);`), ''];
+}
+
+generatePomAction(action, pomElement) {
+  const varName = this.options.pomClassName.charAt(0).toLowerCase() + this.options.pomClassName.slice(1);
+  // fill → await varName.fillUsername('text');
+  // click → await varName.clickSubmit();
+  // select → await varName.selectCountry('US');
+  // other → await varName.elementName.hover();
+}
+```
+
+### 5. Изменить: `playwright-python.js`
+
+```python
+# Import: from login_page import LoginPage
+# Instantiation: login_page = LoginPage(page)
+# Fill: login_page.fill_username('text')
+# Click: login_page.click_submit()
+```
+
+### 6. Изменить: `selenium-python.js`
+
+```python
+# Import: from login_page import LoginPage
+# Instantiation: login_page = LoginPage(driver)
+# Fill: login_page.fill_username('text')
+# Click: login_page.click_submit()
+```
+
+### 7. Изменить: `selenium-java.js`
+
+```java
+// Import: import pages.LoginPage;
+// Instantiation: LoginPage loginPage = new LoginPage(driver);
+// Fill: loginPage.fillUsername("text");
+// Click: loginPage.clickSubmit();
+```
+
+### 8. Изменить: `server/tool-schemas.js`
+
+Добавить к `ExportScenarioAsCodeSchema` и `AppendScenarioToFileSchema`:
+```js
+pageObjectMode: z.enum(['none', 'generate', 'generate-integrated', 'use-existing']).optional()
+  .describe("POM integration: 'none' (default), 'generate' (separate POM, current behavior), 'generate-integrated' (POM + test using it), 'use-existing' (test uses existing POM file)"),
+pageObjectFile: z.string().optional()
+  .describe("Path to existing POM file (for 'use-existing' mode)"),
+```
+
+### 9. Изменить: `server/tool-definitions.js`
+
+Обновить описания тулов `exportScenarioAsCode` и `appendScenarioToFile` — добавить `pageObjectMode` и `pageObjectFile` в `inputSchema.properties`.
+
+### 10. Изменить: `index.js` (экспорт-хендлеры)
+
+**`exportScenarioAsCode` (~строка 3321):**
+- При `pageObjectMode === 'generate-integrated'`: сгенерировать POM, передать `pomElements`/`pomClassName` в генератор → получить тест с POM-вызовами
+- При `pageObjectMode === 'use-existing'`: прочитать POM-файл через `FileAppender.readFile()`, распарсить через `parsePomFile()`, передать в генератор
+- При `pageObjectMode === 'generate'` или `generatePageObject: true`: текущее поведение (обратная совместимость)
+
+**`appendScenarioToFile` (~строка 3182):**
+- Аналогичная логика для `generateTestOnly()`
+
+### 11. Обновить: `README.md`
+
+Документировать `pageObjectMode` и `pageObjectFile` параметры для обеих тул.
+
+## Обратная совместимость
+
+- `generatePageObject: true` (bool) — работает как раньше (maps to `pageObjectMode: 'generate'`)
+- Новое поведение только при явном `pageObjectMode: 'generate-integrated'` или `'use-existing'`
+- Fallback: если экшн не сматчился с POM-элементом — raw-селектор (как сейчас)
+
+## Алгоритм Selector Matching
+
+| Action selector | POM selector | Результат |
+|---|---|---|
+| `#username` | `#username` | Exact match |
+| `input#username` | `#username` | Normalized (strip tag) |
+| `[name="email"]` | `[name="email"]` | Exact match |
+| `input[name="email"]` | `[name="email"]` | Key match (name=email) |
+| `.complex > path:nth(2)` | `#username` | No match → raw fallback |
+
+## Порядок реализации
+
+1. `page-object-generator.js` — добавить `elements` metadata + helper-функции
+2. `pom-integrator.js` — создать (matching + parsing)
+3. `code-generator-base.js` — POM-методы + модифицированный generate-цикл
+4. `playwright-typescript.js` — имплементация POM-методов (reference)
+5. `playwright-python.js` — имплементация POM-методов
+6. `selenium-python.js` — имплементация POM-методов
+7. `selenium-java.js` — имплементация POM-методов
+8. `tool-schemas.js` — новые параметры
+9. `tool-definitions.js` — обновить descriptions + schema
+10. `index.js` — оркестрация в хендлерах экспорта
+11. `README.md` — документация
+
+## Верификация
+
+1. Записать сценарий на тестовой странице (например, Google Search)
+2. Вызвать `exportScenarioAsCode` с `pageObjectMode: 'generate-integrated'`
+3. Проверить что тест-файл содержит import POM-класса и вызывает его методы
+4. Вызвать `generatePageObject`, сохранить файл, затем `exportScenarioAsCode` с `pageObjectMode: 'use-existing'`
+5. Проверить что тест использует существующий POM
+6. Проверить fallback: экшны без матча → raw-селекторы
+7. Проверить все 4 фреймворка
+8. Проверить `appendScenarioToFile` с POM-интеграцией