Dashboard/Scout/wiki/decisions/2026-05-22-browser-workbench-session-modes.md
Scout

wiki/decisions/2026-05-22-browser-workbench-session-modes.md

ADR: Browser Workbench And Session Modes

Date: 2026-05-22
Status: Accepted

Context

Scout's app UI was failing the product workflow because the browser/evidence surface was a small placeholder, live runs looked frozen, navigation hid active runs, and hard-site cases such as Estée Lauder were not represented truthfully. The user expectation is closer to a live workbench: open a target, see what Scout is doing, preserve evidence, and make blocked pages understandable.

Decision

Scout will treat browser evidence as a primary app workspace and expose three explicit session concepts: crawler, scout-browser, and user-browser.

Rationale

  • A normal web page cannot literally embed a full native browser process, but Scout can run Playwright and stream/capture browser evidence into the app.
  • Crawl4AI remains the default acquisition path, but it cannot be the only fallback for JavaScript-heavy or hard-site workflows.
  • A Scout-controlled browser can capture screenshot, DOM, text, links, console errors, and network failures without relying on arbitrary third-party iframe embedding.
  • A user's own browser session can see pages that Scout's isolated crawler/browser cannot. That requires a separate, explicit consent boundary through Chrome CDP or a browser extension.
  • Hard-site blocked pages must be treated as evidence, not as silent failure or fake success.

Alternatives Considered

Option Why rejected
Keep tiny evidence placeholder It hides the main workflow and makes Scout look like a mockup instead of an app.
Embed third-party pages in an iframe Many sites block framing; it also does not solve extraction or provenance.
Make Scout Browser the default for everything Higher cost, more brittle, and not needed for simple pages; Crawl4AI remains better as the default crawler.
Pretend User Browser mode works now This would be misleading and unsafe because it needs explicit CDP or extension setup.

Consequences

  • Product runs now support scout-browser as a real Playwright-backed capture mode.
  • Browser evidence artifacts are written under the selected output directory: screenshot, DOM, text, and links.
  • If Scout Browser captures an access-denied or blocked page, the run becomes a failed/blocked run with explicit blocked evidence.
  • The app now needs a future browser-control API before Back, Forward, Refresh, Capture, Extract, and Save Evidence can become enabled controls.
  • User Browser mode remains a planned secure bridge, not an active data-capture path.

Verification

  • python3 -m pytest tests/e2e/test_app_ui_exhaustive.py -q -> 14 passed.
  • SCOUT_LIVE_TESTS=1 python3 -m pytest tests/live/test_app_live_targets.py -q -> 39 passed.
  • python3 -m pytest tests/unit/ -q -> 196 passed.
  • python3 -m pytest tests/ -q -> 216 passed, 41 skipped.
  • python3 -m pyright scout/ -> 0 errors.
  • ruff check scout/ tests/ && ruff format --check scout/ tests/ -> passed.