h17-webpilot 0.1.0

package/LICENSE

@@ -0,0 +1,191 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 Hugo Palma
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,177 @@
+# Human Browser
+
+CDP-free browser automation with human-like behavior via Chrome extension + WebSocket.
+
+Control Chromium through a WebSocket protocol. Any language can connect. Built-in human-like mouse movement, typing, scrolling, and trap detection. No Puppeteer, no Playwright, no debugging port, no `navigator.webdriver`.
+
+## Install
+
+```bash
+npm install webpilot
+```
+
+## Quick Start
+
+### 1. Configure
+
+```bash
+cp node_modules/webpilot/human-browser.config.example.js human-browser.config.js
+```
+
+Edit `human-browser.config.js` — set your browser path:
+
+```javascript
+module.exports = {
+  browser: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+  // Linux:   "/usr/bin/google-chrome"
+  // Windows: "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
+  profile: "./profile",
+  port: 7331,
+};
+```
+
+### 2. Start
+
+```bash
+npx webpilot start
+```
+
+### 3. Connect
+
+#### Interactive CLI
+
+```bash
+npx webpilot
+```
+
+```
+wp> go example.com
+wp> discover
+wp> click h1
+wp> type #search hello world
+wp> ss
+```
+
+#### Node.js (programmatic)
+
+```javascript
+const { startWithPage } = require('webpilot');
+
+const { page } = await startWithPage();
+await page.goto('https://example.com');
+await page.humanClick('h1');
+await page.humanType('Hello world', { selector: '#search' });
+```
+
+#### Any language (WebSocket)
+
+Connect to `ws://localhost:7331` and send JSON:
+
+```json
+{ "id": "1", "action": "tabs.navigate", "params": { "url": "https://example.com" } }
+```
+
+## CLI Reference
+
+**Navigation:**
+- `go <url>` — navigate (auto-adds `https://`)
+- `reload` / `back` / `forward` — page navigation
+- `sd [px] [selector]` — scroll down
+- `su [px] [selector]` — scroll up
+
+**Query:**
+- `q <selector>` — find all matches with handle IDs
+- `wait <selector>` — wait for selector to appear
+- `discover` — list all interactive elements
+
+**Interact:**
+- `click <selector|handleId>` — human click (bezier cursor + safety checks)
+- `type [selector] <text>` — human type (character-by-character with variance)
+- `clear <selector>` — clear input field
+- `focus <selector>` — focus element
+- `key <name>` — key press (Enter, Tab, Escape...)
+
+**Inspect:**
+- `eval <js>` — evaluate JavaScript
+- `title` / `url` / `html` — quick page info
+- `ss` — screenshot (saves PNG to current directory)
+- `box <selector>` — bounding box
+- `cookies` — dump all cookies
+- `frames` — list all frames
+
+**Meta:**
+- `.tabs` — list tabs (with 0-9 aliases)
+- `.tab <n>` — switch active tab
+- `.events` — toggle event display
+- `.status` — connection info
+- `.quit` — exit
+
+**Raw mode:**
+- `action.name {"key": "value"}` — any protocol command
+- `{"id": "1", "action": "...", ...}` — raw WebSocket JSON
+
+## Programmatic API
+
+```javascript
+const {
+  start,           // Launch browser + WS server
+  startWithPage,   // start + return BridgePage on first tab
+  connectToServer, // Connect to already-running server
+  loadConfig,      // Load human-browser.config.js
+  BridgePage,      // Page automation class
+  BridgeElement,   // DOM element wrapper
+  BridgeKeyboard,  // Keyboard input
+  BridgeCursor,    // Mouse cursor with bezier movement
+} = require('webpilot');
+```
+
+## Architecture
+
+1. Node.js server starts a local WebSocket bridge on port 7331
+2. Chromium launches with the extension loaded into a clean profile
+3. The extension connects to the WS bridge from its service worker
+4. Your code (any language) connects to the same WS endpoint
+5. Commands are relayed to the extension and executed in-page
+
+The extension runs as a content script in Chrome's ISOLATED world. No CDP, no debugging protocol, no detectable automation flags.
+
+### Human Behavior
+
+All `human.*` commands include:
+
+- Bezier curve mouse movement with overshoot
+- Randomized timing and typing cadence
+- Scroll behavior with flick sub-scrolls and back-scroll variance
+- 13-point honeypot/trap detection (aria-hidden, offsetParent, opacity, visibility, sub-pixel, bounding-box shift, class-name regex)
+- Configurable `avoid` rules per-request and global
+
+### Safety Layer
+
+`human.click` returns `{ clicked: false, reason: "..." }` instead of clicking unsafe elements:
+
+- `aria-hidden` — screen reader hidden
+- `honeypot-class` — trap class names (ghost, sr-only, visually-hidden, etc.)
+- `opacity-zero` / `visibility-hidden` — invisible elements
+- `sub-pixel` — elements smaller than 5x5px
+- `element-shifted` — element moved during think time
+- `no-bounding-box` / `element-disappeared` — element not in DOM
+
+## Protocol
+
+Full WebSocket protocol specification: [`protocol/PROTOCOL.md`](protocol/PROTOCOL.md)
+
+## LLM Integration
+
+For AI agents that need to browse the web: [`SKILLS.md`](SKILLS.md)
+
+## Go CLI
+
+A compiled Go CLI is also available in `cli/` for users who prefer a standalone binary:
+
+```bash
+cd cli && go build -o hb && ./hb
+```
+
+## License
+
+Apache 2.0

package/SKILLS.md

@@ -0,0 +1,299 @@
+---
+name: human-browser
+description: Skill for LLM agents to browse the web through the Human Browser WebSocket protocol. Covers navigation, interaction, data extraction, and recovery.
+---
+
+# Human Browser — LLM Navigation Skill
+
+You control a real Chrome browser through WebSocket JSON messages (`ws://localhost:7331`). A Chrome extension receives your commands and executes them in-page with human-like behavior. You cannot see the page — you must look before every action.
+
+## Mental Model
+
+You are **blind**. The browser is a room you navigate by touch. Before every action:
+
+1. **Look** — read the page (`dom.getHTML`, `dom.discoverElements`, `tabs.screenshot`)
+2. **Think** — pick the right element from what you actually saw
+3. **Act** — interact with it (`human.click`, `human.type`, `human.scroll`)
+4. **Verify** — confirm the action worked (re-read, check URL, wait for expected element)
+
+Never guess selectors. Never assume page state. Always look first.
+
+## Wire Format
+
+Every message you send:
+```json
+{ "id": "unique-id", "tabId": 123, "action": "action.name", "params": {} }
+```
+
+Every response you receive:
+```json
+{ "id": "same-id", "result": { ... } }
+```
+
+Or on error:
+```json
+{ "id": "same-id", "error": "message" }
+```
+
+You may also receive unsolicited events:
+```json
+{ "type": "event", "event": "urlChanged", "data": { "tabId": 123, "url": "..." } }
+{ "type": "event", "event": "response", "data": { "url": "...", "status": 200, "tabId": 123 } }
+```
+
+Always use a unique `id` per request. Always include `tabId` (get it from `tabs.list`).
+
+## Your Eyes
+
+These are your tools for understanding the page. Use them constantly.
+
+| Command | What it gives you | When to use |
+|---------|-------------------|-------------|
+| `dom.getHTML` | Full page HTML (title, url, html) | Understanding page structure, extracting data |
+| `dom.discoverElements` | List of interactive elements with labels, roles, positions | Deciding what to click or type into |
+| `dom.queryAllInfo` | Elements matching a selector with handleId, tag, id, class, text, label | Narrowing down from a known selector pattern |
+| `tabs.screenshot` | Base64 PNG of the viewport | Visual debugging, understanding layout |
+| `dom.findScrollable` | All scrollable containers with handleIds | Finding panels to scroll for more content |
+| `dom.boundingBox` | Position and size of an element | Checking if element is visible/on-screen |
+
+### Looking strategy
+
+1. **First visit to a page**: Use `dom.getHTML` to understand the full structure. It returns raw HTML — parse it to find patterns, selectors, data attributes.
+2. **Before clicking**: Use `dom.discoverElements` to see what's interactive, or `dom.queryAllInfo` with a candidate selector to find your target.
+3. **After an action**: Use `dom.waitForSelector` on something you expect to appear, then look again to confirm.
+4. **When lost**: `tabs.screenshot` gives you a visual snapshot. `dom.getHTML` gives you the truth.
+
+## Your Hands
+
+Two tiers of interaction commands exist. **Always prefer human commands.**
+
+### Human commands (safe — use these)
+
+Human commands include bezier cursor movement, randomized timing, honeypot detection, and avoid-rule checking. They behave like a real person.
+
+| Command | Purpose | Key params |
+|---------|---------|------------|
+| `human.click` | Click an element | `handleId` or `selector`, optional `avoid` |
+| `human.type` | Type text character-by-character | `text`, optional `handleId`/`selector` |
+| `human.scroll` | Scroll a panel or the page | `handleId`/`selector`, `direction` |
+| `human.clearInput` | Focus + select-all + delete | `handleId` or `selector` |
+
+### Raw commands (direct — use only when you need precision)
+
+| Command | Purpose |
+|---------|---------|
+| `dom.click` | Same pipeline as human.click (this IS the human pipeline) |
+| `dom.type` | Direct text insertion, no per-character timing |
+| `dom.keyPress` | Single key press (`Enter`, `Tab`, `Escape`, etc.) |
+| `dom.keyDown` / `dom.keyUp` | Hold/release keys (for shortcuts like Ctrl+A) |
+| `dom.scroll` | Direct scroll with exact pixel amount |
+| `dom.focus` | Focus an element without clicking |
+| `dom.setValue` | Set input value directly (for hidden fields, React state) |
+
+### The avoid parameter
+
+All human commands accept `avoid` — rules for elements that should never be interacted with:
+
+```json
+{
+  "avoid": {
+    "selectors": [".cookie-banner", "#popup-overlay"],
+    "classes": ["sponsored", "ad-slot"],
+    "ids": ["newsletter-signup"],
+    "attributes": { "data-ad": "*", "data-tracking": "*" }
+  }
+}
+```
+
+If a human command returns `{ "clicked": false, "reason": "..." }`, the element was unsafe. Reasons include: `avoided`, `aria-hidden`, `no-offsetParent`, `honeypot-class`, `opacity-zero`, `visibility-hidden`, `sub-pixel`, `no-bounding-box`, `element-disappeared`, `element-shifted`. **Respect these. Do not retry the same element.**
+
+## Navigation
+
+### Going to a page
+
+```json
+{ "id": "1", "action": "tabs.navigate", "params": { "url": "https://example.com" } }
+```
+
+Then **wait for the page to load**:
+
+```json
+{ "id": "2", "action": "dom.waitForSelector", "params": { "selector": "body", "timeout": 10000 } }
+```
+
+Better: wait for a specific element you expect on that page, not just `body`.
+
+### SPA navigation (clicking links instead of URL changes)
+
+Many modern sites are single-page apps. Clicking a nav link doesn't trigger a full page load — it swaps content in-place. After clicking a link:
+
+1. Wait for expected content: `dom.waitForSelector` with a selector unique to the destination
+2. Do NOT rely on `urlChanged` events alone — the URL may update before content renders
+3. If content doesn't appear within timeout, re-read the page with `dom.getHTML`
+
+### Tab management
+
+```json
+{ "id": "1", "action": "tabs.list", "params": {} }
+{ "id": "2", "action": "tabs.create", "params": { "url": "https://example.com" } }
+{ "id": "3", "action": "tabs.activate", "params": {}, "tabId": 456 }
+{ "id": "4", "action": "tabs.close", "params": {}, "tabId": 456 }
+```
+
+Always `tabs.list` first to get the `tabId` you need. Commands sent without `tabId` go to the active tab.
+
+## Recipes
+
+### Recipe: Fill and submit a search form
+
+```
+1. dom.getHTML                                    → find the search input selector
+2. human.click    { selector: "#search-input" }   → focus the input
+3. human.type     { text: "my query" }            → type the search
+4. dom.keyPress   { key: "Enter" }                → submit
+5. dom.waitForSelector { selector: ".results" }   → wait for results
+6. dom.getHTML                                    → read results
+```
+
+### Recipe: Scroll through a list and collect items
+
+```
+1. dom.findScrollable                             → find scrollable panels
+2. dom.getHTML                                    → read initial content
+3. human.scroll   { handleId: "el_7", direction: "down" }  → scroll down
+4. sleep 1-2s                                     → let content render
+5. dom.getHTML                                    → read new content
+6. Repeat 3-5 until you have enough or scroll stops moving
+```
+
+Use `dom.scroll` return values (`before`, `after`) to detect when you've hit the bottom: if `before === after`, there's nothing more to scroll.
+
+### Recipe: Navigate a multi-page flow (e.g., checkout, wizard)
+
+```
+1. dom.getHTML                                    → understand current step
+2. Fill in fields (human.click → human.type for each)
+3. human.click    { selector: "button.next" }     → advance
+4. dom.waitForSelector { selector: ".step-2" }    → wait for next step
+5. dom.getHTML                                    → understand new step
+6. Repeat until done
+```
+
+### Recipe: Handle a login form
+
+```
+1. dom.getHTML                                    → find email/password fields
+2. human.click    { selector: "#email" }
+3. human.type     { text: "user@example.com" }
+4. human.click    { selector: "#password" }
+5. human.type     { text: "password123" }
+6. human.click    { selector: "button[type='submit']" }
+7. dom.waitForSelector { selector: ".dashboard" } → wait for post-login page
+```
+
+If the site uses 2FA or CAPTCHA, you'll need to detect that from the DOM and handle accordingly.
+
+### Recipe: Extract data from a detail page
+
+```
+1. dom.getHTML                                    → get full page HTML
+2. Parse the HTML to find the data you need
+3. If data is in specific elements:
+   dom.queryAllInfo  { selector: ".product-card" }   → get handles + text summary
+   dom.elementHTML   { handleId: "el_3" }            → get full HTML of one card
+4. If data requires page JS globals (rare):
+   dom.evaluate      { fn: "() => window.__DATA__" } → may fail on strict CSP sites
+```
+
+Prefer `dom.getHTML` + `dom.elementHTML` over `dom.evaluate`. They work on all sites regardless of CSP.
+
+## Waiting
+
+**This is the #1 source of failures.** Pages don't load instantly. SPAs swap content asynchronously. After every navigation or interaction that changes the page:
+
+- **Use `dom.waitForSelector`** with a selector you expect to appear
+- **Set a reasonable timeout** (5000-10000ms for navigation, 3000ms for in-page changes)
+- **If the wait times out**, don't retry blindly — re-read the page with `dom.getHTML` to understand what actually happened
+
+```json
+{ "id": "1", "action": "dom.waitForSelector", "params": { "selector": ".results-loaded", "timeout": 8000 } }
+```
+
+Do NOT use fixed sleeps as a substitute for `waitForSelector`. Fixed sleeps are for behavioral pacing (looking human), not for waiting on page state.
+
+## Recovery
+
+Things go wrong. Handles go stale, pages redirect, elements disappear.
+
+### Stale handle
+
+If a command returns an error about an invalid handleId, the element was garbage-collected or the page navigated. **Re-query the selector:**
+
+```
+1. dom.querySelector { selector: "the-same-selector" }  → get fresh handleId
+2. Retry your action with the new handleId
+```
+
+### Unexpected page
+
+If after clicking you end up somewhere unexpected:
+1. Check the URL: `dom.getHTML` returns `url` in its result
+2. If wrong page: `tabs.navigate` back, or click the browser back button via `dom.evaluate`
+3. If a popup/modal appeared: look for a close button, click it, then retry
+
+### Element blocked
+
+If `human.click` returns `{ clicked: false }`:
+- `reason: "avoided"` — your avoid rules blocked it. Check if the rules are too aggressive.
+- `reason: "no-offsetParent"` or `sub-pixel` — element is hidden or off-screen. Scroll first.
+- `reason: "honeypot-class"` — genuine trap. Do not click.
+- `reason: "element-disappeared"` — re-query and retry.
+- `reason: "element-shifted"` — page was still loading. Wait, then retry.
+
+### Timeout
+
+If a command times out (30s default), the extension may be disconnected or the page is unresponsive.
+1. Try `tabs.list` — if it works, the extension is alive
+2. Try targeting a different tab or reloading: `tabs.reload`
+3. If nothing responds, the server or extension may need restart
+
+## Selector Strategy
+
+**Never guess selectors.** Always derive them from what you see in `dom.getHTML` or `dom.discoverElements`.
+
+Good selector sources (most to least stable):
+1. **IDs**: `#login-form` — unique, stable
+2. **Data attributes**: `[data-testid="submit"]`, `[aria-label="Search"]` — designed for automation
+3. **Semantic HTML**: `button[type="submit"]`, `input[name="email"]`, `nav a[href="/about"]`
+4. **Role attributes**: `[role="dialog"]`, `[role="navigation"]`
+5. **Structural**: `.header > nav > ul > li:first-child a` — fragile, use as last resort
+
+Bad selectors (avoid these):
+- Hashed class names (`.css-1a2b3c`, `.sc-bZQynM`) — change every build
+- Deep structural paths — break on any DOM change
+- Guessed/assumed selectors you haven't verified in the actual HTML
+
+### When you can't find a good selector
+
+Use `dom.discoverElements` — it returns interactive elements with their labels, roles, and types. Pick from that list. Or use `dom.queryAllInfo` with a broad selector (like `button` or `a`) and filter by the `text` or `label` field.
+
+## CSP Compatibility
+
+The extension runs in Chrome's ISOLATED world (content script context). Most commands are immune to Content Security Policy restrictions.
+
+**Always works (CSP-safe):** `dom.getHTML`, `dom.querySelector*`, `dom.queryAllInfo`, `dom.elementHTML`, `dom.findScrollable`, `dom.discoverElements`, `human.*`, `tabs.*`, `cookies.*`, `frames.list`
+
+**May fail on strict-CSP sites:** `dom.evaluate`, `dom.elementEvaluate` — these try MAIN world first, fall back to ISOLATED. When falling back, they can access the DOM but NOT page JavaScript globals.
+
+If you need page globals (`window.__INITIAL_STATE__`) and the site has strict CSP, that data is not accessible. Extract from the rendered DOM instead.
+
+CSP errors in the browser console are harmless — sites cannot detect them.
+
+## Do Not
+
+- Do not guess selectors — always look at the page first
+- Do not skip waiting after navigation — pages need time to render
+- Do not retry a blocked click without understanding the reason
+- Do not use `dom.evaluate` when `dom.getHTML` or `dom.elementHTML` would work
+- Do not send commands without a `tabId` unless you're sure which tab is active
+- Do not treat `human.click` returning `{ clicked: false }` as an error to force through — it's the extension protecting you