Skip to content

feat(emulate): add mobile device emulation via CDP Emulation domain - #60

Merged
BB-fat merged 2 commits into
mainfrom
feat/mobile-emulation
Aug 5, 2026
Merged

feat(emulate): add mobile device emulation via CDP Emulation domain#60
BB-fat merged 2 commits into
mainfrom
feat/mobile-emulation

Conversation

@BB-fat

@BB-fat BB-fat commented Aug 5, 2026

Copy link
Copy Markdown
Collaborator

Motivation

Agents driving real user browsers had no way to debug mobile page behaviour: the codebase made no use of the CDP Emulation domain at all — no viewport metrics override, no UA spoofing, no touch emulation. (Window sizing from #52 only resizes the real window; pages still see a desktop environment.)

What changes

New bsk emulate command + tool.emulate end-to-end:

bsk emulate --session <id> --device iphone-14        # built-in preset
bsk emulate --session <id> --width 390 --height 844 --dpr 3 --mobile --ua "Mozilla/5.0 (iPhone…)"
bsk emulate --session <id> --device pixel-7 --touch  # manual flags layer on top of presets
bsk emulate --session <id> --off                     # clear every override
  • Viewport via Emulation.setDeviceMetricsOverride (width/height/deviceScaleFactor/mobile) — changes what the page sees (innerWidth, media queries, meta-viewport handling), unlike window resizing.
  • User-Agent via Emulation.setUserAgentOverride, with optional accept-language and UA client-hints metadata (protocol-level).
  • Touch via Emulation.setTouchEmulationEnabled + maxTouchPoints, so ontouchstart / pointer media queries behave like a touch device.
  • Seven CLI-side presets: iphone-14, iphone-14-pro-max, iphone-se, pixel-7, galaxy-s23, ipad-mini, galaxy-tab-s8. Manual flags work standalone or override individual preset fields.
  • Overrides are per-tab (CDP per-target) and not inherited by new tabs; the result JSON carries a note so agents know to re-apply.

Explicitly out of scope (possible v2): real touch event streams (Input.dispatchTouchEvent), network throttling, geolocation.

Implementation

  • bsk-protocol: tool.emulate method (classified BrowserMutation), EmulateParams/EmulateOverrides/EmulateResult types + regenerated JSON schemas.
  • CLI: new emulate subcommand (presets, validation, JSON/human output), daemon forwards ToolEmulate to the extension.
  • Extension: ChromiumCdp Emulation wrappers, new tools/emulate.ts handler (off clears; otherwise viewport → UA → touch applied in order), dispatcher registration, transport types mirrored.
  • Docs: both SKILL.md copies gain a concise "Device emulation" section (presets, --off, per-tab scope).

Tests

  • New: 6 protocol serde tests, 15 CLI param-building unit tests, 4 cli_parse integration tests, 22 extension vitest cases for the handler.
  • cargo fmt --all --check, clippy -p bsk-protocol -p bsk --all-targets -D warnings: clean.
  • cargo test -p bsk-protocol: 113 passed. cargo test -p bsk --lib: 207 passed; sync_continues_on_partial_error fails identically on clean main in this environment (pre-existing, env-dependent).
  • Extension: pnpm lint, tsc --noEmit, wxt build, vom:test all clean; vitest +22 new tests green (41 pre-existing React.act failures in tsx files also fail identically on clean main).

BB-fat added 2 commits August 5, 2026 05:38
Add `bsk emulate` so agents can debug mobile page behaviour by
emulating a device environment on a session tab:

- Viewport metrics (Emulation.setDeviceMetricsOverride), User-Agent
  (Emulation.setUserAgentOverride, optional accept-language and UA
  client-hints metadata), and touch (Emulation.setTouchEmulationEnabled
  with maxTouchPoints).
- Seven CLI-side device presets (iphone-14, iphone-14-pro-max,
  iphone-se, pixel-7, galaxy-s23, ipad-mini, galaxy-tab-s8) via
  --device; manual flags (--width/--height/--dpr/--mobile/--ua/
  --accept-language/--touch/--max-touch-points) work standalone or
  override individual preset fields.
- `bsk emulate --off` clears every override (clearDeviceMetricsOverride
  + touch disabled + empty UA override) and restores the real
  environment.
- Overrides are per-tab (CDP per-target) and not inherited by new tabs;
  the result JSON carries a note reminding agents to re-apply.

Wire: new tool.emulate method end-to-end (bsk-protocol types + JSON
schemas + Method::ToolEmulate classified BrowserMutation, daemon
forwarding, CLI subcommand, extension tool handler + ChromiumCdp
Emulation wrappers, dispatcher registration), docs in both SKILL.md
copies, and unit tests on every layer.
- extension: remember the applied emulation state per tab and merge each new request onto it field by field before applying, so a later --width/--height no longer resets an earlier preset's dpr/mobile; --off clears the stored state along with the CDP overrides
- extension: cdp_failed errors now note that already-applied overrides were not rolled back and can be reset with --off
- cli: validate width/height pairing and metric requirements on the merged preset+flags result, so --device iphone-14 --width 500 keeps the preset height
- cli: add --no-mobile/--no-touch (conflicting with --mobile/--touch) to turn preset mobile/touch fields back off
- docs: describe the merge behaviour, --no-mobile/--no-touch and --off state clearing in both SKILL.md copies
@BB-fat
BB-fat merged commit 0f264c5 into main Aug 5, 2026
4 checks passed
@BB-fat
BB-fat deleted the feat/mobile-emulation branch August 5, 2026 10:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant