Debug UI

Gotchas

• The browser is a machine-global singleton — isolate per task or agents stomp each other. Every agent-browser call with no session lands in one shared "default" session: one browser process, one global viewport. When two task agents QA at the same time they collide — agent B's open silently replaces agent A's page, so A's next screenshot captures B's UI. The fix is step 1: export AGENT_BROWSER_SESSION="dev3-${DEV3_TASK_ID%%-*}" gives each task its own isolated session/profile (verify with agent-browser session / session list), and agent-browser close then closes only your session. The Bash tool reinitializes the shell per call, so an export does not carry across separate invocations — the line derives from the always-present $DEV3_TASK_ID, so just repeat it at the top of each block, or pass --session "dev3-${DEV3_TASK_ID%%-*}" on every command. (If you ever must share one browser machine-wide instead, serialize QA across agents so only one drives at a time.)

• The dev-server is a build snapshot — no watch/HMR. Your code only appears after a (re)start. After changing code, dev3 dev-server restart, re-wait for the port, then agent-browser reload — a bare reload re-serves the old bundle. Don't keep a stale server around; never hand-run vite build.

• Is the running build actually yours? An already-running app/remote is often production or another worktree — it won't have your changes. (Re)start THIS task's dev-server and confirm with dev3 --version (commit hash should match git log -1) + that your change actually renders. Don't assume.

• Tell the user before you start the app any way at all (visible side effect), and stop it after (step 4) unless they want it kept.

• dev3 says app not running? Stop and tell the user. Every route in this skill needs the CLI, so there is nothing to fall back to. Never launch the app yourself — a bare bun run dev (with or without --qa, in your shell or in a dev3 pane run) opens a native window on the user's screen that no dev-server owns, so nothing can status or stop it for you.

• No DEV3_PORT0? (portCount 0, or an older worktree where it was never allocated) — run your own fixed-port server instead: dev3 remote --no-detach --no-tunnel --static-code $CODE --port 47823 → :47823/?token=$CODE.

• Every screenshot in streamer mode — no exceptions by default. The app shows the developer's REAL identity (account emails, orgs, home-dir paths, tunnel URLs, QR codes), and a QA screenshot easily ends up in a PR/issue/recording. &streamer=on in the URL forces the privacy masking on for the whole session (it persists in this session's localStorage; &streamer=off forces it back off). The masking is CSS blur on .streamer-private elements — see src/mainview/streamer-mode.tsx and decision 161. Only capture unmasked when the task is explicitly about those values (e.g. testing the accounts UI itself), and say so when presenting the image.

• App renders but nothing clicks? That's the mobile gate, not the tooling. The app decides mobile from the physical screen.width (< 1024 → mobile; src/mainview/hooks/useMobile.tsx, deliberately not innerWidth), and a mobile device held in landscape gets MobilePortraitGate: a "rotate your device" overlay plus inert on the whole app — screenshots still work, clicks do nothing. agent-browser 0.6.0 emulated screen.* together with the viewport, so set viewport 1440 900 before open was enough. 0.34.0 does not — screen stays at the headless display's 800×600 no matter the viewport (--window-size in --args does not move it either), so every desktop QA run lands in the gate. Override it with an init script instead, registered before the first navigation:

  printf 'for (const k of ["width","availWidth"]) Object.defineProperty(screen, k, { get: () => 1600, configurable: true });\nfor (const k of ["height","availHeight"]) Object.defineProperty(screen, k, { get: () => 1000, configurable: true });\n' > /tmp/screen-desktop.js
  agent-browser close                      # a running session keeps its old init scripts
  agent-browser set viewport 1600 1000
  agent-browser open "http://localhost:$PORT/?token=$CODE&streamer=on" --init-script /tmp/screen-desktop.js

  With that, screen.width reports 1600 and the gate stays off. You otherwise only hit the gate by asking for a phone-sized landscape viewport — that is the app working as designed. Measured across the common sizes: 2560×1440, 1920×1080, 1600×900, 1440×900, 1366×768, 1280×720, 1024×768, 768×1024 and phone portrait 390×844 all render and click fine (screen.width always equals the requested width); only landscape 844×390 shows the gate, goes inert, and reports zero interactive elements in snapshot -i — that count is the fastest tell. Diagnose in one call: agent-browser eval "JSON.stringify({sw:screen.width,gate:!!document.querySelector('[data-testid=\"mobile-portrait-gate\"]'),inert:!!document.querySelector('[inert]')})". If a future browser tool pins screen.* to the real headless display and desktop QA goes inert, that's the moment to add an escape hatch to the app — not before (see the headless-QA decision).

• No native dialogs in browser mode. If a confirm/file-picker flow silently no-ops, that's an app bug, not a tooling problem — report it.

• Show images to the user AFTER you stop this dev-server, not while it runs. dev3 show-image (and dev3 attention / dev3 notify) route to the app instance that owns the task — and this QA dev-server is itself a full dev3 instance. While it's up, those UI-attention calls can land in it (the browser only you see) instead of the user's main app, so the user never sees the image. Screenshots persist on disk, so the correct order is capture → dev3 dev-server stop (confirm State: stopped) → dev3 show-image.