@pencil-agent/nano-pencil 2.0.0-beta.9 → 2.0.0

package/dist/extensions/builtin/browser/interaction-skills/dialogs.md

@@ -1,64 +1,64 @@
-# Dialogs
-
-Browser dialogs (`alert`, `confirm`, `prompt`, `beforeunload`) freeze the JS thread. Two approaches depending on timing.
-
-## Detection
-
-`page_info()` auto-surfaces any open dialog: if one is pending it returns `{"dialog": {"type", "message", ...}}` instead of the usual viewport dict (because the page's JS is frozen anyway). So if you call `page_info()` after an action and see a `dialog` key, handle it before doing anything else.
-
-## Reactive: dismiss via CDP (preferred)
-
-Works even when JS is frozen. Handles all dialog types including `beforeunload`.
-
-```python
-# Dismiss and read the message
-cdp("Page.handleJavaScriptDialog", accept=True)   # accept / click OK
-cdp("Page.handleJavaScriptDialog", accept=False)  # cancel / click Cancel
-
-# Read what the dialog said (from buffered CDP events)
-events = drain_events()
-for e in events:
-    if e["method"] == "Page.javascriptDialogOpening":
-        print(e["params"]["type"])     # "alert", "confirm", "prompt", "beforeunload"
-        print(e["params"]["message"])  # the dialog text
-```
-
-Undetectable by antibot — no JS injected into the page.
-
-## Proactive: stub via JS
-
-Prevents dialogs from ever appearing. Good when you expect multiple `alert()`/`confirm()` calls in sequence.
-
-```python
-js("""
-window.__dialogs__=[];
-window.alert=m=>window.__dialogs__.push(String(m));
-window.confirm=m=>{window.__dialogs__.push(String(m));return true;};
-window.prompt=(m,d)=>{window.__dialogs__.push(String(m));return d||'';};
-""")
-# ... do actions that trigger dialogs ...
-msgs = js("window.__dialogs__||[]")
-```
-
-Tradeoffs:
-- Stubs are lost on page navigation -- must re-run the snippet
-- `confirm()` always returns `true` (auto-approves)
-- Detectable by antibot (`window.alert.toString()` reveals non-native code)
-- Does NOT handle `beforeunload`
-
-## beforeunload specifically
-
-Fires when navigating away from a page with unsaved changes (forms, editors, upload pages). The page freezes until the user clicks Leave/Stay.
-
-```python
-# Option A: dismiss after navigating (CDP-level, safe)
-goto_url("https://new-url.com")
-try:
-    cdp("Page.handleJavaScriptDialog", accept=True)  # click "Leave"
-except:
-    pass  # no dialog — normal
-
-# Option B: prevent before navigating (JS injection, detectable)
-js("window.onbeforeunload=null")
-goto_url("https://new-url.com")
-```
+# Dialogs
+
+Browser dialogs (`alert`, `confirm`, `prompt`, `beforeunload`) freeze the JS thread. Two approaches depending on timing.
+
+## Detection
+
+`page_info()` auto-surfaces any open dialog: if one is pending it returns `{"dialog": {"type", "message", ...}}` instead of the usual viewport dict (because the page's JS is frozen anyway). So if you call `page_info()` after an action and see a `dialog` key, handle it before doing anything else.
+
+## Reactive: dismiss via CDP (preferred)
+
+Works even when JS is frozen. Handles all dialog types including `beforeunload`.
+
+```python
+# Dismiss and read the message
+cdp("Page.handleJavaScriptDialog", accept=True)   # accept / click OK
+cdp("Page.handleJavaScriptDialog", accept=False)  # cancel / click Cancel
+
+# Read what the dialog said (from buffered CDP events)
+events = drain_events()
+for e in events:
+    if e["method"] == "Page.javascriptDialogOpening":
+        print(e["params"]["type"])     # "alert", "confirm", "prompt", "beforeunload"
+        print(e["params"]["message"])  # the dialog text
+```
+
+Undetectable by antibot — no JS injected into the page.
+
+## Proactive: stub via JS
+
+Prevents dialogs from ever appearing. Good when you expect multiple `alert()`/`confirm()` calls in sequence.
+
+```python
+js("""
+window.__dialogs__=[];
+window.alert=m=>window.__dialogs__.push(String(m));
+window.confirm=m=>{window.__dialogs__.push(String(m));return true;};
+window.prompt=(m,d)=>{window.__dialogs__.push(String(m));return d||'';};
+""")
+# ... do actions that trigger dialogs ...
+msgs = js("window.__dialogs__||[]")
+```
+
+Tradeoffs:
+- Stubs are lost on page navigation -- must re-run the snippet
+- `confirm()` always returns `true` (auto-approves)
+- Detectable by antibot (`window.alert.toString()` reveals non-native code)
+- Does NOT handle `beforeunload`
+
+## beforeunload specifically
+
+Fires when navigating away from a page with unsaved changes (forms, editors, upload pages). The page freezes until the user clicks Leave/Stay.
+
+```python
+# Option A: dismiss after navigating (CDP-level, safe)
+goto_url("https://new-url.com")
+try:
+    cdp("Page.handleJavaScriptDialog", accept=True)  # click "Leave"
+except:
+    pass  # no dialog — normal
+
+# Option B: prevent before navigating (JS injection, detectable)
+js("window.onbeforeunload=null")
+goto_url("https://new-url.com")
+```

package/dist/extensions/builtin/browser/interaction-skills/downloads.md

@@ -1,3 +1,3 @@
-# Downloads
-
-Separate browser-triggered downloads from direct `http_get(...)` fetches, and document the minimal signals that prove a download actually started.
+# Downloads
+
+Separate browser-triggered downloads from direct `http_get(...)` fetches, and document the minimal signals that prove a download actually started.

package/dist/extensions/builtin/browser/interaction-skills/drag-and-drop.md

@@ -1,3 +1,3 @@
-# Drag And Drop
-
-Focus on when drag-and-drop can be driven with low-level input events versus when the site really expects a file upload or DOM-specific drag sequence.
+# Drag And Drop
+
+Focus on when drag-and-drop can be driven with low-level input events versus when the site really expects a file upload or DOM-specific drag sequence.

package/dist/extensions/builtin/browser/interaction-skills/dropdowns.md

@@ -1,3 +1,3 @@
-# Dropdowns
-
-Split dropdowns into native selects, custom overlays, searchable comboboxes, and virtualized menus, and always re-measure after opening because option geometry often appears late.
+# Dropdowns
+
+Split dropdowns into native selects, custom overlays, searchable comboboxes, and virtualized menus, and always re-measure after opening because option geometry often appears late.

package/dist/extensions/builtin/browser/interaction-skills/iframes.md

@@ -1,3 +1,3 @@
-# Iframes
-
-Cover same-origin iframe traversal through `contentDocument` / `contentWindow`, and keep the frame-local versus page-coordinate warning explicit for clicks.
+# Iframes
+
+Cover same-origin iframe traversal through `contentDocument` / `contentWindow`, and keep the frame-local versus page-coordinate warning explicit for clicks.

package/dist/extensions/builtin/browser/interaction-skills/network-requests.md

@@ -1,3 +1,3 @@
-# Network Requests
-
-Document how to watch or infer network activity when page state is ambiguous, especially for submit flows, downloads, and SPA actions that succeed without obvious DOM changes.
+# Network Requests
+
+Document how to watch or infer network activity when page state is ambiguous, especially for submit flows, downloads, and SPA actions that succeed without obvious DOM changes.

package/dist/extensions/builtin/browser/interaction-skills/print-as-pdf.md

@@ -1,3 +1,3 @@
-# Print As PDF
-
-Cover both direct PDF generation via CDP and sites that only expose a visible "Print" button which must be clicked before handling the browser print flow.
+# Print As PDF
+
+Cover both direct PDF generation via CDP and sites that only expose a visible "Print" button which must be clicked before handling the browser print flow.

package/dist/extensions/builtin/browser/interaction-skills/profile-sync.md

@@ -1,90 +1,90 @@
-# Profile sync
-
-Make a remote Browser Use browser start already logged in, by uploading cookies from a local Chrome profile.
-
-## One-time install
-
-```bash
-curl -fsSL https://browser-use.com/profile.sh | sh
-```
-
-Downloads `profile-use` (macOS / Linux / Windows, x64 / arm64). The Python helpers shell out to it; you don't run `profile-use` directly.
-
-## Python API (pre-imported in `browser-harness -c`)
-
-```python
-list_cloud_profiles()
-# [{id, name, userId, cookieDomains, lastUsedAt}, ...] — every profile under this API key
-
-list_local_profiles()
-# [{BrowserName, ProfileName, DisplayName, ProfilePath, ...}, ...] — detected on this machine
-
-sync_local_profile(local_profile_name, browser=None,
-                   cloud_profile_id=None,      # update an existing cloud profile instead of creating new
-                   include_domains=None,       # only these domains (and subdomains); leading dot optional
-                   exclude_domains=None)       # drop these domains; applied before include
-# Shells out to `profile-use sync`. Returns the cloud profile UUID
-# (the existing one if cloud_profile_id was passed, else the newly-created one).
-
-start_remote_daemon("work", profileName="my-work")   # name→id resolved client-side
-start_remote_daemon("work", profileId="<uuid>")      # or pass UUID directly
-
-stop_remote_daemon("work")                           # shut the daemon and PATCH the cloud browser to stop — billing ends
-```
-
-`sync_local_profile` prints `♻️  Using existing cloud profile` when `cloud_profile_id` is accepted, or `📝  Creating remote profile...` → `✓ Profile created: <uuid>` when it creates a new one. Check that line if you want to confirm which path ran.
-
-## Chat-driven flow (don't guess — ask the user)
-
-Cookies are real auth. Don't sync or pick a profile unilaterally.
-
-```python
-# 1. Show what's already in the cloud.
-for p in list_cloud_profiles():
-    print(f"{p['name']:25}  {len(p['cookieDomains']):3} domains  {p['id']}")
-```
-→ Agent: *"You have these cloud profiles (<N> domains each). Want to reuse one, sync a local profile, or start clean?"*
-
-```python
-# 2a. Reuse cloud → one call.
-start_remote_daemon("work", profileName="browser-use.com")
-
-# 2b. Sync local first. Show the options:
-for lp in list_local_profiles():
-    print(lp["DisplayName"])
-```
-→ Agent: *"Which local profile?"* → user picks → before syncing, inspect domain-level cookie counts with `profile-use inspect --profile <name>` (or `--verbose` for individual cookies) and report the summary; never dump 500 cookies into chat.
-
-```python
-# 3. Sync + use. Returns the cloud UUID.
-uuid = sync_local_profile("browser-use.com")
-start_remote_daemon("work", profileId=uuid)
-
-# 3b. Refresh that same cloud profile later (idempotent — no duplicate profiles).
-sync_local_profile("browser-use.com", cloud_profile_id=uuid)
-
-# 3c. Scoped: push *only* Stripe cookies into a dedicated cloud profile.
-sync_local_profile("browser-use.com",
-                   cloud_profile_id=uuid,
-                   include_domains=["stripe.com"])
-```
-
-## What actually gets synced
-
-**Cookies only.** No localStorage, no IndexedDB, no extensions. Enough for session-cookie sites (Google, GitHub, Stripe, most SaaS); not for sites that store auth in localStorage.
-
-Cookies mutated during a remote session only persist on a clean `PATCH /browsers/{id} {"action":"stop"}` — the daemon does this on shutdown when `BU_BROWSER_ID` + `BROWSER_USE_API_KEY` are set (default for remote daemons). Sessions that hit the timeout lose in-session state.
-
-## Cloud profile CRUD
-
-- UI: https://cloud.browser-use.com/settings?tab=profiles
-- API: `GET /profiles`, `GET/PATCH/DELETE /profiles/{id}` (paths are relative to `BU_API = "https://api.browser-use.com/api/v3"` in `admin.py`). Fields: `id`, `name`, `userId`, `lastUsedAt`, `cookieDomains[]`. `list_cloud_profiles()` wraps this.
-- Name → UUID: `profileName=` on `start_remote_daemon` resolves client-side; no API change needed.
-- Need the UUID for an existing profile? `matches = [p["id"] for p in list_cloud_profiles() if p["name"] == "<name>"]` — then verify `len(matches) == 1` before using it. Profile names are not unique; syncs create duplicates unless you pass `cloud_profile_id=`.
-- Lower-level raw calls: `from admin import _browser_use; _browser_use("/profiles/<id>", "DELETE")`. Pass the path *without* the `/api/v3` prefix — it's already on `BU_API`.
-
-## Traps
-
-- **Default proxy (`proxyCountryCode="us"`) blocks some destinations** with `ERR_TUNNEL_CONNECTION_FAILED` (e.g. `cloud.browser-use.com` itself). `proxyCountryCode=None` disables the BU proxy; a different country code picks a different exit.
-- **Prefer a dedicated work profile over your personal one.** Especially while testing.
-- **Older than `profile-use` v1.0.5?** Pre-1.0.5 the sync needed the Chrome profile to be closed (exclusive SQLite lock on the `Cookies` DB). v1.0.5+ copies the profile dir to a temp and syncs from the copy — Chrome can stay open.
+# Profile sync
+
+Make a remote Browser Use browser start already logged in, by uploading cookies from a local Chrome profile.
+
+## One-time install
+
+```bash
+curl -fsSL https://browser-use.com/profile.sh | sh
+```
+
+Downloads `profile-use` (macOS / Linux / Windows, x64 / arm64). The Python helpers shell out to it; you don't run `profile-use` directly.
+
+## Python API (pre-imported in `browser-harness -c`)
+
+```python
+list_cloud_profiles()
+# [{id, name, userId, cookieDomains, lastUsedAt}, ...] — every profile under this API key
+
+list_local_profiles()
+# [{BrowserName, ProfileName, DisplayName, ProfilePath, ...}, ...] — detected on this machine
+
+sync_local_profile(local_profile_name, browser=None,
+                   cloud_profile_id=None,      # update an existing cloud profile instead of creating new
+                   include_domains=None,       # only these domains (and subdomains); leading dot optional
+                   exclude_domains=None)       # drop these domains; applied before include
+# Shells out to `profile-use sync`. Returns the cloud profile UUID
+# (the existing one if cloud_profile_id was passed, else the newly-created one).
+
+start_remote_daemon("work", profileName="my-work")   # name→id resolved client-side
+start_remote_daemon("work", profileId="<uuid>")      # or pass UUID directly
+
+stop_remote_daemon("work")                           # shut the daemon and PATCH the cloud browser to stop — billing ends
+```
+
+`sync_local_profile` prints `♻️  Using existing cloud profile` when `cloud_profile_id` is accepted, or `📝  Creating remote profile...` → `✓ Profile created: <uuid>` when it creates a new one. Check that line if you want to confirm which path ran.
+
+## Chat-driven flow (don't guess — ask the user)
+
+Cookies are real auth. Don't sync or pick a profile unilaterally.
+
+```python
+# 1. Show what's already in the cloud.
+for p in list_cloud_profiles():
+    print(f"{p['name']:25}  {len(p['cookieDomains']):3} domains  {p['id']}")
+```
+→ Agent: *"You have these cloud profiles (<N> domains each). Want to reuse one, sync a local profile, or start clean?"*
+
+```python
+# 2a. Reuse cloud → one call.
+start_remote_daemon("work", profileName="browser-use.com")
+
+# 2b. Sync local first. Show the options:
+for lp in list_local_profiles():
+    print(lp["DisplayName"])
+```
+→ Agent: *"Which local profile?"* → user picks → before syncing, inspect domain-level cookie counts with `profile-use inspect --profile <name>` (or `--verbose` for individual cookies) and report the summary; never dump 500 cookies into chat.
+
+```python
+# 3. Sync + use. Returns the cloud UUID.
+uuid = sync_local_profile("browser-use.com")
+start_remote_daemon("work", profileId=uuid)
+
+# 3b. Refresh that same cloud profile later (idempotent — no duplicate profiles).
+sync_local_profile("browser-use.com", cloud_profile_id=uuid)
+
+# 3c. Scoped: push *only* Stripe cookies into a dedicated cloud profile.
+sync_local_profile("browser-use.com",
+                   cloud_profile_id=uuid,
+                   include_domains=["stripe.com"])
+```
+
+## What actually gets synced
+
+**Cookies only.** No localStorage, no IndexedDB, no extensions. Enough for session-cookie sites (Google, GitHub, Stripe, most SaaS); not for sites that store auth in localStorage.
+
+Cookies mutated during a remote session only persist on a clean `PATCH /browsers/{id} {"action":"stop"}` — the daemon does this on shutdown when `BU_BROWSER_ID` + `BROWSER_USE_API_KEY` are set (default for remote daemons). Sessions that hit the timeout lose in-session state.
+
+## Cloud profile CRUD
+
+- UI: https://cloud.browser-use.com/settings?tab=profiles
+- API: `GET /profiles`, `GET/PATCH/DELETE /profiles/{id}` (paths are relative to `BU_API = "https://api.browser-use.com/api/v3"` in `admin.py`). Fields: `id`, `name`, `userId`, `lastUsedAt`, `cookieDomains[]`. `list_cloud_profiles()` wraps this.
+- Name → UUID: `profileName=` on `start_remote_daemon` resolves client-side; no API change needed.
+- Need the UUID for an existing profile? `matches = [p["id"] for p in list_cloud_profiles() if p["name"] == "<name>"]` — then verify `len(matches) == 1` before using it. Profile names are not unique; syncs create duplicates unless you pass `cloud_profile_id=`.
+- Lower-level raw calls: `from admin import _browser_use; _browser_use("/profiles/<id>", "DELETE")`. Pass the path *without* the `/api/v3` prefix — it's already on `BU_API`.
+
+## Traps
+
+- **Default proxy (`proxyCountryCode="us"`) blocks some destinations** with `ERR_TUNNEL_CONNECTION_FAILED` (e.g. `cloud.browser-use.com` itself). `proxyCountryCode=None` disables the BU proxy; a different country code picks a different exit.
+- **Prefer a dedicated work profile over your personal one.** Especially while testing.
+- **Older than `profile-use` v1.0.5?** Pre-1.0.5 the sync needed the Chrome profile to be closed (exclusive SQLite lock on the `Cookies` DB). v1.0.5+ copies the profile dir to a temp and syncs from the copy — Chrome can stay open.

package/dist/extensions/builtin/browser/interaction-skills/screenshots.md

@@ -1,17 +1,17 @@
-# Screenshots
-
-`capture_screenshot()` writes a PNG of the current viewport. The file is in **device pixels** — on a 2× display a 2296×1143 CSS viewport produces a 4592×2286 PNG.
-
-That matters for two reasons:
-
-1. **Click coordinates are CSS pixels.** Don't read a target off the image and pass it to `click_at_xy()` directly without dividing by `devicePixelRatio`. The simplest workflow is to take the screenshot, look at it in a viewer that shows CSS coordinates, or measure relative positions and use `js("window.devicePixelRatio")` to convert.
-
-2. **Some LLMs reject images > 2000 px per side.** Long sessions on 2× displays will eventually hit this. Pass `max_dim=1800` to downscale the file before it gets into the conversation:
-
-```python
-capture_screenshot("/tmp/shot.png", max_dim=1800)
-```
-
-The downscale only happens when the image actually exceeds `max_dim`, so it's safe to leave on for every shot.
-
-Use full-page screenshots (`full=True`) only when you need to see content below the fold — they are much larger and slower than viewport-only.
+# Screenshots
+
+`capture_screenshot()` writes a PNG of the current viewport. The file is in **device pixels** — on a 2× display a 2296×1143 CSS viewport produces a 4592×2286 PNG.
+
+That matters for two reasons:
+
+1. **Click coordinates are CSS pixels.** Don't read a target off the image and pass it to `click_at_xy()` directly without dividing by `devicePixelRatio`. The simplest workflow is to take the screenshot, look at it in a viewer that shows CSS coordinates, or measure relative positions and use `js("window.devicePixelRatio")` to convert.
+
+2. **Some LLMs reject images > 2000 px per side.** Long sessions on 2× displays will eventually hit this. Pass `max_dim=1800` to downscale the file before it gets into the conversation:
+
+```python
+capture_screenshot("/tmp/shot.png", max_dim=1800)
+```
+
+The downscale only happens when the image actually exceeds `max_dim`, so it's safe to leave on for every shot.
+
+Use full-page screenshots (`full=True`) only when you need to see content below the fold — they are much larger and slower than viewport-only.

package/dist/extensions/builtin/browser/interaction-skills/scrolling.md

@@ -1,3 +1,3 @@
-# Scrolling
-
-Separate page scroll, nested containers, virtualized lists, and dropdown menus, and identify which element is actually consuming wheel events before scrolling.
+# Scrolling
+
+Separate page scroll, nested containers, virtualized lists, and dropdown menus, and identify which element is actually consuming wheel events before scrolling.

package/dist/extensions/builtin/browser/interaction-skills/shadow-dom.md

@@ -1,3 +1,3 @@
-# Shadow DOM
-
-Focus on recursive `shadowRoot` traversal, and note when coordinate clicking is simpler than piercing deeply nested component trees.
+# Shadow DOM
+
+Focus on recursive `shadowRoot` traversal, and note when coordinate clicking is simpler than piercing deeply nested component trees.

package/dist/extensions/builtin/browser/interaction-skills/tabs.md

@@ -1,69 +1,69 @@
-# Tabs
-
-Use **CDP for control**, **UI automation for user-visible order**.
-
-## Pure CDP (portable: macOS / Linux / Windows)
-
-```python
-tabs = list_tabs()                    # includes chrome:// pages too
-real_tabs = list_tabs(include_chrome=False)
-tid = new_tab("https://example.com")  # create + attach
-switch_tab(tid)                       # attach harness to tab
-cdp("Target.activateTarget", targetId=tid)  # show it in Chrome
-print(current_tab())
-print(page_info())
-```
-
-What CDP is good at:
-- attach to a tab
-- open a tab
-- activate a known target
-- inspect URL/title/viewport
-- capture the attached tab's screenshot even if another tab is visibly frontmost
-
-What CDP is bad at:
-- matching the **left-to-right tab strip order** the user sees
-- telling whether the attached target is an omnibox popup / internal page without URL filtering
-
-## Visible order (platform UI)
-
-### macOS
-
-```applescript
-tell application "Google Chrome"
-  set out to {}
-  set i to 1
-  repeat with t in every tab of front window
-    set end of out to {tab_index:i, tab_title:(title of t), tab_url:(URL of t)}
-    set i to i + 1
-  end repeat
-  return out
-end tell
-```
-
-```applescript
-tell application "Google Chrome"
-  set active tab index of front window to 2
-  activate
-end tell
-```
-
-### Linux
-
-No AppleScript. Same split still applies:
-- use CDP for `new_tab`, attach, inspect, activate known targets
-- use window-manager / browser UI automation when the user means visible order
-
-Typical tools:
-- `xdotool`
-- `wmctrl`
-- desktop-environment scripting (`gdbus`, KWin, GNOME Shell extensions, etc.)
-
-## Rules that held up in practice
-
-- `switch_tab()` is **not enough** if the user expects Chrome to visibly change.
-- `Target.activateTarget` is the CDP-side "show this tab".
-- `list_tabs()` includes `chrome://newtab/` by default; ask for `include_chrome=False` when you want only real pages.
-- `chrome://omnibox-popup.top-chrome/` can appear as a fake page target; ignore it for user-facing tab lists.
-- If a page has `w=0 h=0`, you may be attached to the wrong target or a non-window surface.
-- For dynamic UIs, re-read element rects after opening dropdowns / modals before coordinate-clicking.
+# Tabs
+
+Use **CDP for control**, **UI automation for user-visible order**.
+
+## Pure CDP (portable: macOS / Linux / Windows)
+
+```python
+tabs = list_tabs()                    # includes chrome:// pages too
+real_tabs = list_tabs(include_chrome=False)
+tid = new_tab("https://example.com")  # create + attach
+switch_tab(tid)                       # attach harness to tab
+cdp("Target.activateTarget", targetId=tid)  # show it in Chrome
+print(current_tab())
+print(page_info())
+```
+
+What CDP is good at:
+- attach to a tab
+- open a tab
+- activate a known target
+- inspect URL/title/viewport
+- capture the attached tab's screenshot even if another tab is visibly frontmost
+
+What CDP is bad at:
+- matching the **left-to-right tab strip order** the user sees
+- telling whether the attached target is an omnibox popup / internal page without URL filtering
+
+## Visible order (platform UI)
+
+### macOS
+
+```applescript
+tell application "Google Chrome"
+  set out to {}
+  set i to 1
+  repeat with t in every tab of front window
+    set end of out to {tab_index:i, tab_title:(title of t), tab_url:(URL of t)}
+    set i to i + 1
+  end repeat
+  return out
+end tell
+```
+
+```applescript
+tell application "Google Chrome"
+  set active tab index of front window to 2
+  activate
+end tell
+```
+
+### Linux
+
+No AppleScript. Same split still applies:
+- use CDP for `new_tab`, attach, inspect, activate known targets
+- use window-manager / browser UI automation when the user means visible order
+
+Typical tools:
+- `xdotool`
+- `wmctrl`
+- desktop-environment scripting (`gdbus`, KWin, GNOME Shell extensions, etc.)
+
+## Rules that held up in practice
+
+- `switch_tab()` is **not enough** if the user expects Chrome to visibly change.
+- `Target.activateTarget` is the CDP-side "show this tab".
+- `list_tabs()` includes `chrome://newtab/` by default; ask for `include_chrome=False` when you want only real pages.
+- `chrome://omnibox-popup.top-chrome/` can appear as a fake page target; ignore it for user-facing tab lists.
+- If a page has `w=0 h=0`, you may be attached to the wrong target or a non-window surface.
+- For dynamic UIs, re-read element rects after opening dropdowns / modals before coordinate-clicking.

package/dist/extensions/builtin/browser/interaction-skills/uploads.md

@@ -1 +1 @@
-# Uploads
+# Uploads

package/dist/extensions/builtin/browser/interaction-skills/viewport.md

@@ -1,3 +1,3 @@
-# Viewport
-
-Cover how viewport size changes affect layout, coordinate clicks, and any workflow that depends on stable geometry.
+# Viewport
+
+Cover how viewport size changes affect layout, coordinate clicks, and any workflow that depends on stable geometry.

package/dist/extensions/builtin/browser/src/browser_harness/AGENT.md

@@ -1,15 +1,15 @@
-# extensions/builtin/browser/src/browser_harness/
-
-> P2 | Parent: ../../AGENT.md
-
-Member List
-__init__.py: Package marker for the vendored Browser Harness Python module
-run.py: CLI-compatible Browser Harness runner, command dispatch, daemon bootstrap, and snippet execution
-helpers.py: Core CDP browser helpers for tabs, navigation, screenshots, JS, clicks, uploads, and HTTP
-admin.py: Setup, doctor, reload, update, remote browser, and profile management helpers
-daemon.py: Long-lived CDP daemon, session relay, event buffering, and browser attachment logic
-_ipc.py: Cross-platform IPC plumbing for daemon socket or TCP loopback transport
-
-Rule: Members complete, one item per line, parent links valid, precise terms first
-
-[COVENANT]: Update this file header on changes and verify against parent AGENT.md
+# extensions/builtin/browser/src/browser_harness/
+
+> P2 | Parent: ../../AGENT.md
+
+Member List
+__init__.py: Package marker for the vendored Browser Harness Python module
+run.py: CLI-compatible Browser Harness runner, command dispatch, daemon bootstrap, and snippet execution
+helpers.py: Core CDP browser helpers for tabs, navigation, screenshots, JS, clicks, uploads, and HTTP
+admin.py: Setup, doctor, reload, update, remote browser, and profile management helpers
+daemon.py: Long-lived CDP daemon, session relay, event buffering, and browser attachment logic
+_ipc.py: Cross-platform IPC plumbing for daemon socket or TCP loopback transport
+
+Rule: Members complete, one item per line, parent links valid, precise terms first
+
+[COVENANT]: Update this file header on changes and verify against parent AGENT.md

package/dist/extensions/builtin/browser/src/browser_harness/__init__.py

@@ -1,8 +1,8 @@
-"""Browser Harness core package.
-
-[WHO]: Provides browser_harness package marker for the vendored CDP bridge
-[FROM]: Depends on Python import machinery only
-[TO]: Consumed by browser_harness.run, browser_harness.daemon, and NanoPencil browser extension subprocesses
-[HERE]: extensions/builtin/browser/src/browser_harness/__init__.py within vendored Browser Harness package
-"""
-
+"""Browser Harness core package.
+
+[WHO]: Provides browser_harness package marker for the vendored CDP bridge
+[FROM]: Depends on Python import machinery only
+[TO]: Consumed by browser_harness.run, browser_harness.daemon, and NanoPencil browser extension subprocesses
+[HERE]: extensions/builtin/browser/src/browser_harness/__init__.py within vendored Browser Harness package
+"""
+