web-browser

Web Browser

Environment-aware browser operations skill. Detects the runtime environment and routes to the appropriate browser backend, then runs one of two workflows: UI testing/verification (ui-test) or browser-login-assisted credential issuance (credential-issue).

Topics

Topic Dependencies

web-browser (Step 0: environment detection — shared by all topics)
  ├─→ ui-test (UI verification)
  │     └─→ cdp-trace (extends ui-test for closed shadow DOM)
  └─→ credential-issue (browser-login-assisted token/key issuance)
        └─→ chrome-devtools backend preferred (reuses the user's real logged-in session)

• Step 0 (below) is shared — every topic detects the backend first, then runs its workflow.
• ui-test, cdp-trace are the UI-testing family.
• credential-issue reuses the same backend routing + the user-visibility rule, generalized into a service+command parameterized auth flow.
• Authentik SSO verification (sso-verify) is not included in this skill — it remains in a separate local-only sso-verify skill (user-environment specific, untracked).

CRITICAL — user visibility is the top priority (HARD STOP)

The primary purpose of browser diagnosis/verification is "the user sees it on their own screen". Screenshot capture is supporting evidence, not a substitute for visibility.

API-capable environment without credentials — fallback to credential-issue (HARD STOP)

When a task can be performed via API (e.g., Google Forms API, GitHub API, AWS API), but required API tokens or access keys are missing in the environment, do NOT recommend manual user UI clicking or surrender to direct manual UI operation. You MUST recommend credential-issue topic to issue the access key/token via browser login first, then proceed with backend API automation.

Self-check (every time before launching Playwright/chromium)

1. Did the user use a visibility request keyword such as "show me", "open it", "web-browser", or "browser test"? → If yes, force headless: false
2. Is this work interactive verification or diagnosis for the user? → If yes, headless: false
3. headless is justified only when (a) CI assertion (b) the user explicitly said "in headless" (c) Playwright MCP is used (the UI shows itself)
4. screenshot is supporting evidence — it can be attached to a chat report, but it does not replace user visibility

Violation case (2026-05-28, 1st)

During a closed shadow DOM ak-library cascade investigation, used a npx playwright Bash invocation + chromium.launch({ headless: true }) and only attached a screenshot in chat. The user requested "show it via web-ui-test" and no visible browser was provided. The user reacted angrily that the Chromium UI never appeared.

Login wall mid-capture — ask before stopping, don't silently defer (HARD STOP)

When a capture/documentation task (report evidence, purchase/registration flow guide, etc.) hits a screen that requires login, and completing that login would reveal materially different information than what's already captured (e.g., the real final price vs. a promotional pre-login price, actual post-login UI state vs. an assumption), do NOT silently stop and paper over the gap with a deferral disclaimer. Ask the user via AskUserQuestion whether to continue (via interactive login in a visible backend) or whether the pre-login capture is sufficient for the purpose at hand.

Violation case (2026-07-22, 1st)

While building a domain-registration payment-request report, captured the domain-search-result page (showing a promotional price) and the login screen, then stopped at the login wall with a disclaimer ("have finance/ops enter payment details"), never asking whether to continue via login to verify the real checkout price. The report's stated price differed from the actual payment-screen price. User feedback (paraphrased): "don't arbitrarily skip capturing screens that require login — ask first."

---

Step 0: Environment Detection (MANDATORY — before any browser action)

Check environment variables AND CLI presence to determine the browser backend:

# wmux
echo "WMUX=$WMUX"
# cmux — detect via ANY of these (cmux app does NOT set CMUX_SESSION; use multi-var OR)
echo "CMUX_BUNDLE_ID=$CMUX_BUNDLE_ID"
echo "CMUX_PANEL_ID=$CMUX_PANEL_ID"
echo "CMUX_BUNDLED_CLI_PATH=$CMUX_BUNDLED_CLI_PATH"
# CLI fallback (env may be unset in nested shells but CLI still works)
command -v cmux && echo "cmux CLI present"
command -v wmux && echo "wmux CLI present"

Do & Don't — Browser Backend Selection

cmux detection — multi-var OR rationale

cmux app sets several env vars when launching a shell, but CMUX_SESSION is NOT one of them (a legacy guess by analogy with WMUX). Real vars observed in a cmux-launched shell:

• CMUX_BUNDLE_ID (e.g. com.cmuxterm.app)
• CMUX_PANEL_ID (UUID per panel)
• CMUX_BUNDLED_CLI_PATH (CLI absolute path)
• CMUX_SHELL_INTEGRATION_DIR
• CMUX_AGENT_LAUNCH_*
• GHOSTTY_RESOURCES_DIR (cmux uses Ghostty-based terminal)

CMUX_SOCKET is set but often empty — do not use it as the sole signal. Use the OR matrix above.

wmux Browser Commands Reference

When $WMUX is set, use these instead of Playwright MCP.

Invocation form: the rest of this document uses the bare wmux browser … form, which is what runs when wmux is on PATH (the common case). If wmux is not on PATH in the current environment, substitute node "$WMUX_CLI" for wmux in every command below — $WMUX_CLI points to the same entry point. The two forms are interchangeable; pick whichever resolves on the current shell and use it consistently.

wmux browser open           # navigate (= playwright navigate)
wmux browser snapshot            # get accessibility tree with @eN refs
wmux browser click @eN           # click element
wmux browser type @eN      # type into element
wmux browser fill @eN     # set input value
wmux browser get-text            # get page text
wmux browser screenshot          # capture screenshot
wmux browser eval            # run JavaScript
wmux browser back                # go back
wmux browser forward             # go forward
wmux browser reload              # reload page

Workflow: browser open → browser snapshot → read tree → browser click/type @eN → browser snapshot again.

Refs (@e1, @e2...) expire after page changes — always re-snapshot.

Do & Don't — wmux vs Playwright Mapping

Key difference: wmux browser is visible to the user in real-time on the right panel. Playwright opens an invisible window the user cannot see.

---

Quick Reference

After Step 0 backend detection, route to the topic:

Step execution order: Step 0 (this file — detect backend + user-visibility rule) → read the target topic .md → follow its procedure. The topic .md files hold the actual procedures; this file is the shared backend-detection + index.