From a549580bad7b1d527d88331690d8b02c756b3ae3 Mon Sep 17 00:00:00 2001 From: sh z Date: Mon, 2 Nov 2026 18:45:37 +0800 Subject: [PATCH] docs(browser-debug): pane-first recipes for dialog/iframe/shadow Align the shared workflow skill with Octopus pane agents: prefer the user-visible pane, pre-arm dialogs, use f{seq}/e{n} frame refs, and dual-leg highlight/locator tools. --- core/skills/browser-debug/SKILL.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/core/skills/browser-debug/SKILL.md b/core/skills/browser-debug/SKILL.md index b6265b2..7734c25 100644 --- a/core/skills/browser-debug/SKILL.md +++ b/core/skills/browser-debug/SKILL.md @@ -100,6 +100,25 @@ not by familiarity: | Keyboard navigation | `browser_press_key` | For tab order, focus rings, escape-to-close. | | Record a video / trace | `browser_start_tracing`, `browser_stop_tracing` | Heavy; use only when a bug is timing-sensitive and console+snapshot can't catch it. | +## Pane-first recipe (prefer over headless) + +Default to the **user-visible browser pane** unless the task explicitly needs +an isolated headless Chromium (`surface: "headless"`). Pane agents now match +or exceed Playwright for the hard cases: + +| Need | Pane tool / pattern | Notes | +| --- | --- | --- | +| Open / bind pane | `browser_open` (default surface) | Never touch the user's pane from a headless-only intent — pass `surface: "headless"` or `browser_pane_release` first. | +| Structure + refs | `browser_snapshot` | Open shadow is pierced; cross-origin iframes expose `f{seq}/e{n}` synthetic refs — prefer those over attr ids when acting into child frames. | +| Act (click/type/…) | `browser_act` / `browser_act_batch` | Locators (`role=` / `text=` / …) walk open shadow. Cross-origin click/type route through CDP trusted events. | +| Native dialogs | `browser_handle_dialog` **before** the act | Prefer `mode: "arm"` (or `act_batch.dialog_prearm`) so the pane parks the answer before the click that opens confirm/prompt — avoids the 1.5s auto-dismiss / widget-cancel race. Bind with `messageIncludes` when the page can raise multiple dialogs. Call `mode: "disarm"` if the trigger was cancelled. | +| Highlight / locator | `browser_highlight`, `browser_generate_locator` | Dual-leg: both pane and headless. Use highlight to confirm the ref before a write. | +| Failure recovery | re-snapshot + path candidates | Act/locator failures may return `pathCandidates` (frame/shadow path hints). Heal scores framePath so sibling iframes do not auto-heal across frames. | + +Headless remains the right tool for parallel CI-style isolation and when the +user must not see the session. For interactive debug of `packages/app`, stay +on the pane. + ## Standard recipe — reproduce a UI bug Follow these steps in order. Do not skip the snapshot step: the `ref` it