cdp-skill 1.0.8 → 1.0.14

package/SKILL.md

@@ -19,7 +19,7 @@ Site profiles are per-domain cheatsheets stored at `~/.cdp-skill/sites/{domain}.
 
 ### How navigation uses profiles
 
-Every `goto` and `openTab` (with URL) checks for a profile. The result appears as a **top-level field** in the response:
+Every `goto`, `newTab` (with URL), and `switchTab` checks for a profile. The result appears as a **top-level field** in the response:
 
 - **`siteProfile`** present → read it before doing anything else. It contains strategies, quirks, and recipes. Apply its `settledWhen`/`readyWhen` hooks, use its selectors, and respect its quirks.
 - **`actionRequired`** present → **STOP. Create the profile NOW** before continuing your task:
@@ -33,69 +33,61 @@ The profile only needs to capture what's useful: environment, quirks, stable sel
 
 After completing your goal, update the site profile with anything you learned. Discovered a quirk? Found a reliable selector? Worked out a multi-step flow? Call `writeSiteProfile` again with the improved content before closing your tab. If you didn't learn anything new, skip the update.
 
-### readSiteProfile
-
-`"domain"` | `{domain}` — returns `{found, domain, content}` or `{found: false, domain}`
-
-Read a site profile without navigating. Use this to check or update a profile ad-hoc.
-
-### writeSiteProfile
-
-`{domain, content}` — returns `{written, path, domain}`
-
 ### Profile format
 
 ```
-# example.com
-Updated: 2026-02-03  |  Fingerprint: react18-next-spa
+# domain.com
+Updated: YYYY-MM-DD  |  Fingerprint: <tech-stack>
+
+## Environment / Quirks / Strategies / Regions / Recipes
+```
 
-## Environment
-- React 18.x, Next.js (SSR)
-- SPA with pushState navigation
+- **Environment**: tech stack, SPA behavior, main element selectors
+- **Quirks**: pitfalls that cause failures without foreknowledge
+- **Strategies**: how to fill, click, or wait on this specific site (include `settledWhen`/`readyWhen` hooks)
+- **Regions**: stable landmark selectors
+- **Recipes**: pre-built step sequences for common flows
 
-## Quirks
-- Turbo intercepts link clicks — use settledWhen with URL check
-- Search results load async — poll for .results-count before extracting
+Sections are optional — include what's useful. See EXAMPLES.md for a full profile template.
 
-## Strategies
-### fill (React controlled inputs)
-Use nativeSetter.call(el, value) then dispatch input event with bubbles.
+### readSiteProfile
 
-### Navigation readiness
-settledWhen: () => !document.querySelector('.loading-bar')
+`"domain"` | `{domain}` — returns `{found, domain, content}` or `{found: false, domain}`
 
-## Regions
-- mainContent: main, [role="main"]
-- navigation: .nav-bar
-- searchResults: #search-results
+### writeSiteProfile
 
-## Recipes
-### Login
-pipeline: find #username fill {{user}}, find #password fill {{pass}}, find #login click, waitFor () => location.pathname !== '/login'
+`{domain, content}` — returns `{written, path, domain}`
+```json
+{"writeSiteProfile": {"domain": "example.com", "content": "# example.com\nUpdated: 2025-01-15\n\n## Environment\n- React SPA\n..."}}
 ```
 
-Sections are optional — include what's useful. The key sections agents rely on:
-- **Quirks**: pitfalls that cause failures without foreknowledge
-- **Strategies**: how to fill, click, or wait on this specific site
-- **Recipes**: pre-built step sequences for common flows
-
 ## Quick Start
 
-**1. Check Chrome status** (auto-launches if needed):
-`node src/cdp-skill.js '{"steps":[{"chromeStatus":true}]}'`
+```bash
+echo '{"steps":[{"openTab":"https://google.com"}]}' | node src/cdp-skill.js
+echo '{"tab":"t1","steps":[{"click":"#btn"}]}' | node src/cdp-skill.js
+echo '{"tab":"t1","steps":[{"snapshot":true}]}' | node src/cdp-skill.js
+```
+
+Tab IDs (t1, t2, ...) persist across CLI invocations. Chrome auto-launches if not running.
 
-**2. Open a tab and navigate:**
-`node src/cdp-skill.js '{"steps":[{"openTab":"https://google.com"}]}'`
+## Reliability (v1.0.10-1.0.11)
 
-**3. Use the returned tab ID for subsequent calls:**
-`node src/cdp-skill.js '{"config":{"tab":"t1"},"steps":[{"click":"#btn"}]}'`
+Recent improvements to stability and correctness:
 
-Tab IDs (t1, t2, ...) persist across CLI invocations. Stdin pipe also works: `echo '{"steps":[...]}' | node src/cdp-skill.js`
+- **Validation robustness** — Fixed null pointer crashes in step validation for edge cases with missing or malformed parameters
+- **Race condition fixes** — Resolved timing issues in browser connection initialization, file lock contention, and scroll-wait coordination
+- **Resource cleanup** — Fixed HTTP connection leaks, event listener cleanup, and stderr stream handling
+- **Frame context** — Corrected iframe element location and interaction to respect frame boundaries
+- **Step simplification** — Consolidated 47 steps into 41 unified operations (fill, frame, elementsAt, pageFunction, sleep) for clearer API
+
+The skill now passes 1261/1263 unit tests (99.8%) and maintains SHS 99/100 on the cdp-bench evaluation suite.
 
 ## Input / Output Schema
 
 **Input fields:**
-- `config`: `{host, port, tab, timeout, headless}` — tab is required after first call
+- `tab`: tab alias (e.g. "t1") — required after first call
+- `timeout`: step timeout in ms (default 30000)
 - `steps`: array of step objects (one action per step)
 
 **Output fields:**
@@ -129,7 +121,7 @@ Use refs with `click`, `fill`, `hover`. Each snapshot increments the ID. Refs fr
 | Action | Waits For |
 |--------|-----------|
 | `click` | visible, enabled, stable, not covered, pointer-events |
-| `fill`, `type` | visible, enabled, editable |
+| `fill` | visible, enabled, editable |
 | `hover` | visible, stable |
 
 Use `force: true` to bypass all checks. **Auto-force**: when actionability times out but element exists, automatically retries with force (outputs `autoForced: true`).
@@ -144,195 +136,112 @@ Optional parameters on action steps to customize the step lifecycle:
 
 Hooks can be combined on any action step. Applies to: click, fill, press, hover, drag, selectOption, scroll.
 
-## Step Reference
-
-### Chrome Management
-
-> **IMPORTANT**: Never launch Chrome manually via shell commands. Always use `chromeStatus`.
-
-**chromeStatus**: true | {autoLaunch, headless}
-  returns: {running, launched, version, port, tabs[]}
-
-### Navigation
-
-**goto**: "url" | {url, waitUntil}
-  waitUntil: commit | domcontentloaded | load | networkidle
-  response: top-level `siteProfile` or `actionRequired` (see Site Profiles)
-
-**reload**: true | {waitUntil}
-
-**back** / **forward**: true
-  returns: {url, title} or {noHistory: true}
-
-**waitForNavigation**: true | {timeout, waitUntil}
-
-### Frames
-
-**listFrames**: true
-  returns: {mainFrameId, currentFrameId, frames[]}
-
-**switchToFrame**: "selector" | index | {selector, index, name, frameId}
-  returns: {frameId, url, name}
-
-**switchToMainFrame**: true
-
-### Waiting
-
-**wait**: "selector" | number(ms) | {selector, hidden, minCount} | {text} | {textRegex} | {urlContains}
-
-### Interaction
-
-**click**: "selector" | "ref" | {ref, selector, text, x/y, selectors[]}
-  options: force, jsClick, nativeOnly, doubleClick, scrollUntilVisible, searchFrames, exact, timeout, waitAfter
-  hooks: readyWhen, settledWhen, observe
-  returns: {clicked, method: "cdp"|"jsClick"|"jsClick-auto", navigated?, newUrl?}
-
-**fill**: {selector|ref|label, value}
-  options: clear(true), react, force, exact, timeout
-  hooks: readyWhen, settledWhen, observe
-  returns: {filled, navigated?, newUrl?}
-
-**fillForm**: {"#sel": "value", ...}
-  returns: {total, filled, failed, results[]}
-
-**fillActive**: "value" | {value, clear}
-  returns: {filled, tag, type, selector, valueBefore, valueAfter}
-
-**type**: {selector, text, delay}
-  returns: {selector, typed, length}
-
-**press**: "Enter" | "Control+a" | "Meta+Shift+Enter"
-
-**select**: "selector" | {selector, start, end}
-  returns: {selector, start, end, selectedText, totalLength}
-
-**hover**: "selector" | {selector, ref, duration, captureResult}
-  hooks: readyWhen, settledWhen, observe
-
-**drag**: {source, target}
-  source/target: "selector" | "ref" | {ref, offsetX, offsetY} | {x, y}
-  options: steps(10), delay(0)
-  hooks: readyWhen, settledWhen, observe
-  returns: {dragged, method: "html5-dnd"|"range-input"|"mouse-events", source, target}
-
-**selectOption**: {selector, value|label|index|values}
-  returns: {selected[], multiple}
-  notes: uses JS to set option.selected (native dropdowns can't be clicked via CDP)
-
-### Scrolling
-
-**scroll**: "top" | "bottom" | "selector" | {deltaY} | {x, y}
-  returns: {scrollX, scrollY}
-
-### Data Extraction
-
-**extract**: "selector" | {selector, type: auto|table|list|text, includeHeaders}
-  returns: table → {type, headers, rows, rowCount, columnCount}; list → {type, items, itemCount}
-
-**getDom**: true | "selector" | {selector, outer(true)}
-  returns: {html, tagName, selector, length}
-
-**getBox**: "ref" | ["ref1", "ref2"] | {refs: [...]}
-  returns: {x, y, width, height, center} per ref
-
-**refAt**: {x, y}
-  returns: {ref, existing, tag, selector, clickable, role, name, box}
-
-**elementsAt**: [{x, y}, ...]
-  returns: {count, elements[]}
-
-**elementsNear**: {x, y, radius(50), limit(20)}
-  returns: {center, radius, count, elements[]}
-
-**formState**: "selector" | {selector, includeHidden}
-  returns: {selector, action, method, fields[], valid, fieldCount}
-
-**query**: "selector" | {selector, limit(10), output} | {role, name, nameExact, nameRegex, checked, disabled, level, countOnly, refs}
-  output: text | html | href | value | tag | {attribute: "data-id"}
-  returns: {selector, total, showing, results[]}
-
-**queryAll**: {"label": "selector", ...}
-
-**inspect**: true | {selectors[], limit}
-  returns: {title, url, counts, custom}
-
-**console**: true | {level, type, since, limit, clear, stackTrace}
-  returns: {total, showing, messages[]}
-  notes: logs don't persist across CLI invocations
-
-### Accessibility Snapshot
-
-**snapshot**: true | {root, detail, mode, maxDepth, maxElements, includeText, includeFrames, pierceShadow, viewportOnly, inlineLimit, since}
-  detail: summary | interactive | full(default)
-  since: "s1" — returns {unchanged: true} if page hasn't changed
-  returns: YAML with role, "name", states, [ref=s{N}e{M}], snapshotId
-  notes: snapshots over 9KB saved to file (configurable via inlineLimit)
-
-**snapshotSearch**: {text, pattern, role, exact, limit(10), context, near: {x, y, radius}}
-  returns: {matches[], matchCount, searchedElements}
-  notes: refs from snapshotSearch persist across subsequent commands
-
-### Screenshots & PDF
-
-Screenshots auto-captured on every visual action to `/tmp/cdp-skill/<tab>.before.png` and `.after.png`.
-
-**pdf**: "filename" | {path, selector, landscape, printBackground, scale, paperWidth, paperHeight, margins, pageRanges, validate}
-  returns: {path, fileSize, fileSizeFormatted, pageCount, dimensions}
-
-### Dynamic Browser Execution
-
-**pageFunction**: "() => expr" | {fn, refs(bool), timeout}
-  notes: auto-wrapped as IIFE, refs passes window.__ariaRefs, return value auto-serialized, runs in current frame context
-
-**poll**: "() => predicate" | {fn, interval(100), timeout(30000)}
-  returns: {resolved, value|lastValue, elapsed}
-
-**pipeline**: [{find+fill|click|type|check|select}, {waitFor}, {sleep}, {return}] | {steps[], timeout(30000)}
-  returns: {completed, steps, results[]} or {completed: false, failedAt, error, results[]}
-  notes: compiles to single async JS function, zero roundtrips between micro-ops
-
-### Form Validation
-
-**validate**: "selector"
-  returns: {valid, message, validity}
-
-**submit**: "selector" | {selector, reportValidity}
-  returns: {submitted, valid, errors[]}
-
-### Assertions
-
-**assert**: {url: {contains|equals|startsWith|endsWith|matches}} | {text} | {selector, text, caseSensitive}
-
-### Tab Management
-
-**listTabs**: true
-  returns: {count, tabs[]}
-
-**closeTab**: "tabId"
-  returns: {closed}
-
-**openTab**: true | "url" | {url}
-  returns: {opened, tab, url, navigated, viewportSnapshot, fullSnapshot, context}
-  response: top-level `siteProfile` or `actionRequired` when URL provided (see Site Profiles)
-  notes: REQUIRED as first step when no tab specified
-
-### Viewport
-
-**viewport**: "preset" | {width, height, deviceScaleFactor, mobile, hasTouch, isLandscape}
-  presets: iphone-se, iphone-14, iphone-15-pro, ipad, ipad-pro-11, pixel-7, samsung-galaxy-s23, desktop, desktop-hd, macbook-pro-14
-  returns: {width, height, deviceScaleFactor, mobile, hasTouch}
-
-### Cookies
-
-**cookies**: {get: true|[urls], name?} | {set: [{name, value, domain, expires}]} | {delete: "name", domain?} | {clear: true, domain?}
-  expires formats: 30m, 1h, 7d, 1w, 1y, or Unix timestamp
-  returns: get → {cookies[]}; set → {action, count}; delete/clear → {action, count}
-  notes: get without URLs returns only current tab's domain cookies
-
-### JavaScript Execution
-
-**eval**: "expression" | {expression, await, timeout, serialize}
-  returns: typed results (Number, Date, Map, Set, Element, NodeList, etc.)
+## Core Steps
+
+### chromeStatus (optional diagnostic)
+`true` | `{host, port, headless, autoLaunch}` — returns `{running, launched, version, port, tabs[]}`
+
+> **Note**: You rarely need this — `newTab` auto-launches Chrome. Use `chromeStatus` only for diagnostics or non-default ports.
+
+### newTab
+`true` | `"url"` | `{url, host, port, headless}` — returns `{opened, tab, url, navigated, viewportSnapshot, fullSnapshot, context}`
+Response includes top-level `siteProfile` or `actionRequired` when URL provided (see Site Profiles).
+**REQUIRED as first step** when no tab specified. Chrome auto-launches if not running.
+Non-default Chrome: `{"steps":[{"newTab":{"url":"https://example.com","port":9333,"headless":true}}]}`
+
+### goto
+`"url"` | `{url, waitUntil}` — waitUntil: commit | domcontentloaded | load | networkidle
+Response includes top-level `siteProfile` or `actionRequired` (see Site Profiles).
+
+### click
+`"selector"` | `"ref"` | `{ref, selector, text, x/y, selectors[]}`
+Options: force, jsClick, nativeOnly, doubleClick, scrollUntilVisible, searchFrames, exact, timeout, waitAfter
+Hooks: readyWhen, settledWhen, observe
+Returns: `{clicked, method: "cdp"|"jsClick"|"jsClick-auto", navigated?, newUrl?, newTabs?: [{targetId, url, title}]}`
+
+### fill
+`{selector|ref|label, value}` — the primary way to input text.
+Options: clear(true), react, force, exact, timeout
+Hooks: readyWhen, settledWhen, observe
+Returns: `{filled, navigated?, newUrl?}`
+
+### press
+`"Enter"` | `"Control+a"` | `"Meta+Shift+Enter"` — keyboard shortcuts and key presses.
+
+### scroll
+`"top"` | `"bottom"` | `"selector"` | `{deltaY}` | `{x, y}`
+Returns: `{scrollX, scrollY}`
+
+### snapshot
+`true` | `{root, detail, mode, maxDepth, maxElements, includeText, includeFrames, pierceShadow, viewportOnly, inlineLimit, since}`
+Detail: summary | interactive | full(default)
+Since: `"s1"` — returns `{unchanged: true}` if page hasn't changed
+Returns: YAML with role, "name", states, `[ref=s{N}e{M}]`, snapshotId
+Notes: snapshots over 9KB saved to file (configurable via inlineLimit)
+
+### snapshotSearch
+`{text, pattern, role, exact, limit(10), context, near: {x, y, radius}}`
+Returns: `{matches[], matchCount, searchedElements}`
+Notes: refs from snapshotSearch persist across subsequent commands.
+
+### wait
+`"selector"` | `{selector, hidden, minCount}` | `{text}` | `{textRegex}` | `{urlContains}`
+
+### get
+`"selector"` (text) | `{selector, mode: "text"|"html"|"value"|"box"|"attributes"}` — unified content extraction.
+Returns: text → `{text}`, html → `{html, tagName, length}`, value → `{fields[], valid, fieldCount}`, box → `{x, y, width, height}`, attributes → `{attributes}`
+
+### getUrl
+`true` — returns `{url}`
+
+### getTitle
+`true` — returns `{title}`
+
+### pageFunction
+`"() => expr"` | `{fn, refs(bool), timeout}` — run custom JavaScript in the browser.
+Notes: auto-wrapped as IIFE, refs passes `window.__ariaRefs`, return value auto-serialized, runs in current frame context.
+
+### closeTab
+`"tabId"` — returns `{closed}`
+
+### listTabs
+`true` — returns `{count, tabs[]}`
+
+## Also Available
+
+These steps are fully functional — see EXAMPLES.md for usage details.
+
+| Step | Description |
+|------|-------------|
+| `fill` | Unified fill (replaces `type`): `"text"` (focused), `{selector, value}` (single), `{"#a":"x","#b":"y"}` (batch), `{fields:{...}, react}` (batch+options), `{value, clear}` (focused+options) |
+| `sleep` | Time delay: `2000` (ms, 0–60000) |
+| `pageFunction` | JS execution: `"() => expr"` (function) or `"document.title"` (bare expression) or `{fn, expression, refs, timeout}` |
+| `poll` | Poll predicate until truthy: `"() => expr"` or `{fn, interval, timeout}` |
+| `query` | CSS/ARIA query: `"selector"` or `{role, name}` → `{total, results[]}` |
+| `queryAll` | Batch queries: `{"label": "selector", ...}` |
+| `inspect` | Page overview: `true` → `{title, url, counts}` |
+| `get` | Unified content extraction (replaces `extract`, `getDom`, `getBox`, `formState`): `"selector"` (text), `{selector, mode: "text"\|"html"\|"value"\|"box"\|"attributes"}` |
+| `getUrl` | Get current URL: `true` → `{url}` |
+| `getTitle` | Get page title: `true` → `{title}` |
+| `hover` | Hover element: `"selector"` or `{selector, ref, text, x/y, duration}` |
+| `drag` | Drag and drop: `{source, target, steps, delay, method}` — method: `auto`(default)\|`mouse`\|`html5` |
+| `selectText` | Text selection (renamed from `select`): `"selector"` or `{selector, start, end}` |
+| `selectOption` | Dropdown: `{selector, value\|label\|index\|values}` |
+| `submit` | Submit form: `"selector"` → `{submitted, valid, errors[]}` |
+| `assert` | Assert conditions: `{url: {contains\|equals\|matches}}` or `{text}` or `{selector, text}` |
+| `elementsAt` | Coordinate lookup: `{x,y}` (point), `[{x,y},...]` (batch), `{x,y,radius}` (nearby) |
+| `frame` | Frame ops: `"selector"` (switch), `0` (by index), `"top"` (main frame), `{name}`, `{list:true}` |
+| `viewport` | Set viewport: `"iphone-14"` or `{width, height, mobile}` |
+| `cookies` | Get/set/delete: `{get: true}`, `{set: [...]}`, `{delete: "name"}`, `{clear: true}` |
+| `console` | Browser console: `true` or `{level, limit, clear}` → `{messages[]}` |
+| `pdf` | Generate PDF: `"filename"` or `{path, landscape, scale, pageRanges}` |
+| `back` / `forward` | History navigation: `true` → `{url, title}` or `{noHistory: true}` |
+| `reload` | Reload page: `true` or `{waitUntil}` |
+| `newTab` | Create new tab (renamed from `openTab`): `"url"` or `{url, wait}` → `{tab, url}` |
+| `switchTab` | Switch to existing tab (renamed from `connectTab`): `"t1"` or `{targetId}` or `{url: "regex"}` |
+| `closeTab` | Close tab: `"t1"` or `true` (current) |
+| `listTabs` | List all tabs: `true` → `{tabs[]}` |
+| `waitForNavigation` | Wait for nav: `true` or `{timeout, waitUntil}` |
 
 ### Optional Steps
 
@@ -342,25 +251,28 @@ Add `"optional": true` to any step to continue on failure (status becomes "skipp
 
 | Issue | Solution |
 |-------|----------|
-| Tabs accumulating | Include `tab` in config |
-| CONNECTION error | Use `chromeStatus` first |
+| Tabs accumulating | Include `tab` at top level |
+| CONNECTION error | Check Chrome is reachable; use `chromeStatus` to diagnose |
 | Chrome not found | Set `CHROME_PATH` env var |
 | Element not found | Add `wait` step first |
 | Clicks not working | Scroll into view first, or `force: true` |
 | `back` returns noHistory | New tabs start at about:blank; navigate first |
 | Select dropdown not working | Use click+click or press arrow keys |
 | Type not appearing | Click input first to focus, then type |
+| Elements missing from snapshot | Custom widgets may lack ARIA roles; use `pageFunction` or `get` with `mode: "html"` as fallback |
 | macOS: Chrome running but no CDP | `chromeStatus` launches new instance with CDP enabled |
 
 ## Best Practices
 
 - **Handle `actionRequired` immediately** — when a response contains this field, complete it before doing anything else
-- **Never launch Chrome directly** — always use `chromeStatus`
-- **Use openTab** as your first step to create a tab; use the returned tab ID for all subsequent calls
+- **Never launch Chrome directly** — `newTab` handles it automatically
+- **Use newTab** as your first step to create a tab; use the returned tab ID for all subsequent calls
 - **Reuse only your own tabs** — other agents may share the browser
 - **Update the site profile before closing** — add any quirks, selectors, or recipes you discovered
 - **Close your tab when done** — `closeTab` with your tab ID
-- **Discover before interacting** — use `snapshot` and `inspect` to understand the page
+- **Discover before interacting** — use `snapshot` to understand the page structure
 - **Use website navigation** — click links and submit forms; don't guess URLs
 - **Prefer refs** over CSS selectors — use `snapshot` + refs for resilient targeting
+- **Check `newTabs` after click** — clicks on `target="_blank"` links report new tabs; use `switchTab` to switch
+- **Use `switchTab` for popups** — connect by alias (`"t2"`), targetId, or URL regex (`{url: "pattern"}`)
 - **Be persistent** — try alternative selectors, add waits, scroll first

package/install.js

@@ -19,6 +19,7 @@ const targets = [
 
 const filesToCopy = [
   'SKILL.md',
+  'EXAMPLES.md',
   'src',
 ];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-skill",
-  "version": "1.0.8",
+  "version": "1.0.14",
   "description": "Browser automation skill using Chrome DevTools Protocol for Claude Code and AI agents",
   "type": "module",
   "main": "src/index.js",

package/src/aria/index.js

@@ -0,0 +1,8 @@
+/**
+ * ARIA Module
+ * Re-exports accessibility tree and role-based query functionality
+ */
+
+export { createQueryOutputProcessor } from './output-processor.js';
+export { createRoleQueryExecutor } from './role-query.js';
+export { createAriaSnapshot } from './snapshot.js';