LLM USAGE GUIDE:
  Workflow: inspect -> read uids -> act (click/fill/select/check) -> inspect again.
  Headless by default. Add --stealth for bot-protected sites. Use --json for structured output.

  Quick start:
    chrome-agent goto https://example.com --inspect
    chrome-agent click n12 --inspect
    chrome-agent fill --uid n20 "hello@example.com"
    chrome-agent select --uid n15 "California"
    chrome-agent read                              # article content (Readability)
    chrome-agent eval "document.title"

  Stealth (bypass Cloudflare/bot detection):
    chrome-agent --stealth goto https://protected-site.com --inspect
    # Patches navigator.webdriver, chrome.runtime, UA, WebGL, input leak, skips Runtime.enable

  Logged-in sites (X.com, Gmail, dashboards — use your Chrome cookies):
    chrome-agent --stealth --copy-cookies goto x.com/home --inspect
    # Copies cookies from your real Chrome profile. No manual login needed.

  Heavy bot protection (DataDome, Kasada — when --stealth isn't enough):
    # Use your real Chrome instead of bundled Chromium:
    google-chrome --remote-debugging-port=9222 &
    chrome-agent --connect http://127.0.0.1:9222 goto https://protected-site.com --inspect
    # Real Chrome passes fingerprint checks that Chromium can't

  Targeting elements (3 modes):
    chrome-agent click n40                              # by uid from inspect
    chrome-agent click --selector "button.submit"      # by CSS selector
    chrome-agent click --xy 100,200                    # by coordinates
    chrome-agent fill --uid n20 "value"                 # fill by uid
    chrome-agent fill --selector "input[name=q]" "val" # fill by CSS selector

  Dropdowns (<select> elements only):
    chrome-agent select --uid n15 "Option text"        # select by value or visible text
    chrome-agent select --selector "#country" "France" # by CSS selector
    # For custom dropdowns (React, MUI, etc.): click to open, then click the option.

  Checkboxes and radios (idempotent, uid only):
    chrome-agent check n20                              # ensure checked (no-op if already)
    chrome-agent uncheck n20                            # ensure unchecked (no-op if already)
    # Prefer check/uncheck over click — they guarantee the target state.

  File upload:
    chrome-agent upload --uid n30 /path/to/file.pdf    # by uid
    chrome-agent upload --selector "input[type=file]" /path/to/file.pdf
    # File inputs are often hidden from the a11y tree. Use --selector to target them.

  Double-click:
    chrome-agent dblclick n42                           # by uid
    chrome-agent dblclick --selector ".editable-cell"  # by CSS selector
    chrome-agent dblclick --xy 300,200                  # by coordinates
    # Useful for: text selection, inline editing, expanding tree nodes.

  Drag and drop (mouse-event based):
    chrome-agent drag n10 n20                           # drag from uid to uid
    # Works with: Sortable.js, React DnD (mouse backend), custom mousedown handlers.
    # Does NOT work with HTML5 Drag and Drop API (sites using dragstart/dragover/drop).
    # For HTML5 DnD sites, use eval with custom JS to dispatch drag events.

  Iframes:
    chrome-agent frame "#payment-iframe"               # switch to iframe context
    chrome-agent inspect                                # re-inspect to get iframe UIDs
    chrome-agent fill --selector "input[name=card]" "4242..."  # interact inside iframe
    chrome-agent frame main                             # switch back to main page
    # Only works with <iframe>, not legacy <frame>/<frameset>.
    # Always re-inspect after switching — UIDs are scoped to the frame.

  Inspection + filtering:
    chrome-agent inspect                               # full accessibility tree
    chrome-agent inspect --max-depth 2                 # limit depth (saves tokens)
    chrome-agent inspect --filter "button,link"        # only these roles (flat list)
    chrome-agent inspect --uid n50                     # subtree only
    chrome-agent inspect --filter "link" --urls        # links with resolved href URLs
    chrome-agent inspect --filter "article" --scroll --limit 50  # infinite scroll (X.com, feeds)

  Content extraction (choose the right tool):
    chrome-agent read                                  # article/main content (Readability)
    chrome-agent read --truncate 1000                  # capped at N chars
    chrome-agent text --selector "main" --truncate 500 # visible text of CSS-matched element
    chrome-agent text                                  # full page innerText (verbose)
    chrome-agent extract                                # auto-detect repeating data (tables, cards, lists)
    chrome-agent extract --scroll                      # scroll first for lazy-loaded pages
    chrome-agent extract --a11y --scroll --limit 20    # React SPAs (X.com) -- uses a11y tree, not DOM
    chrome-agent eval "JSON.stringify(...)"            # structured data via JS
    chrome-agent eval --selector "h1" "el.textContent" # eval scoped to a CSS element (el = matched)
    chrome-agent network --filter "api" --body         # intercept API responses directly
    chrome-agent console --level error                 # see JS errors from the page

  Network capture and blocking:
    chrome-agent network                               # resources already loaded (stealth-safe)
    chrome-agent network --filter "graphql" --body     # filter + response bodies
    chrome-agent network --live 5 --body               # capture live traffic for 5 seconds
    chrome-agent network --abort "*tracking*" --live 30 # block requests matching pattern

  Console capture (stealth-safe):
    chrome-agent console                               # all messages
    chrome-agent console --level error                 # errors + exceptions only

  Batch mode (execute multiple commands at once):
    echo '[{"cmd":"goto","url":"https://example.com"},{"cmd":"inspect"},{"cmd":"click","uid":"n12"}]' | chrome-agent batch
    # Returns one JSON line per command. Faster than separate CLI calls.
    # UIDs from inspect are valid for subsequent commands in the same batch.
    # After goto in a batch, UIDs change — use the ones from the next inspect.

  Pipe mode (persistent connection, 10x faster):
    echo '{"cmd":"goto","url":"https://example.com","inspect":true}' | chrome-agent pipe
    # Returns one JSON line per command: {"ok":true,...}

  Navigation:
    chrome-agent goto https://example.com              # navigate
    chrome-agent goto https://spa.com --wait-for "main" # wait for selector after nav
    chrome-agent back                                  # history back
    chrome-agent forward                               # history forward
    chrome-agent scroll down                           # scroll page
    chrome-agent wait text "Success"                   # wait for content

  Multi-tab:
    chrome-agent --page tab2 goto https://other.com
    chrome-agent --page tab2 inspect

  Parallel agents (avoid session conflicts):
    chrome-agent --browser agent1 goto https://example.com  # isolated browser per agent
    chrome-agent --browser agent2 goto https://other.com    # separate Chrome instance

  JSON mode:
    chrome-agent --json goto https://example.com
    -> {"ok":true,"url":"...","title":"..."}
    Errors: {"ok":false,"error":"...","hint":"..."} (exit 1, JSON still on stdout)

  More commands:
    chrome-agent hover n30                             # hover over element
    chrome-agent fill-form n20="a@b.com" n30="pass"   # fill multiple fields at once
    chrome-agent diff                                  # what changed since last inspect
    chrome-agent tabs                                  # list open tabs
    chrome-agent history [--filter "pattern"]          # browsing history
    chrome-agent status                                # session info
    chrome-agent screenshot [--filename name]          # screenshot to file

  Cleanup:
    chrome-agent close                                 # stop browser
    chrome-agent close --purge                         # stop + delete cookies/profile

  Important tips:
    - Use --stealth on sites with bot protection (Cloudflare, Turnstile).
    - UIDs (n47, n123) are stable across inspects on the same page.
    - After SPA navigation (back, forward, click that triggers route change), re-inspect — UIDs change.
    - For SPA product pages, prefer `goto <direct-url>` over `click` (avoids modal routing).
    - Use `read` for articles, `text --selector` for scoped extraction, `eval` for structured data.
    - Prefer inspect over screenshot (~50 vs ~100K tokens).
    - Use --urls on inspect to get link destinations before deciding which to click.
    - check/uncheck are idempotent — prefer over click for checkboxes.
    - select matches by option value first, then by visible text.
    - After `frame <selector>`, re-inspect to get iframe UIDs. `frame main` to return.
    - --max-depth works on goto/click/fill --inspect too (not just standalone inspect).
    - --filter gives a flat list — great for finding interactive elements quickly.
