Merge mobile-viewport-browser-ux into main

Author: Zeus-Deus

AGENTS.md

@@ -40,6 +40,7 @@ This terminal runs inside Codemux. Check: `test -n "$CODEMUX"`
 - `codemux browser click "<selector>"` — click an element
 - `codemux browser fill "<selector>" "<text>"` — type into input
 - `codemux browser screenshot` — capture screenshot
+- `codemux browser viewport <mobile|tablet|desktop|...|WxH|reset>` — resize viewport for responsive testing (CSS media queries fire at the new width); use this instead of iframe-wrapping the page for mobile preview. `codemux browser viewport-presets` lists available presets.
 
 Always get a snapshot before interacting so you know what elements exist.
 

CLAUDE.md

@@ -39,6 +39,7 @@ This terminal runs inside Codemux. Check: `test -n "$CODEMUX"`
 - `codemux browser click "<selector>"` — click an element
 - `codemux browser fill "<selector>" "<text>"` — type into input
 - `codemux browser screenshot` — capture screenshot
+- `codemux browser viewport <mobile|tablet|desktop|...|WxH|reset>` — resize viewport for responsive testing (CSS media queries fire at the new width); `codemux browser viewport-presets` lists available presets
 
 Always get a snapshot before interacting so you know what elements exist.
 

docs/core/STATUS.md

@@ -46,7 +46,7 @@ The repo structure is clean and domain-split:
 - Neutral dark shell theming with Omarchy accent sync
 - Sans-serif shell chrome, monospace terminals
 - Built-in file editor with CodeMirror, syntax highlighting, and markdown preview
-- MCP server exposing 29 tools via JSON-RPC 2.0 (browser, workspace, pane, git, notification)
+- MCP server exposing 31 tools via JSON-RPC 2.0 (browser, workspace, pane, git, notification, viewport presets)
 - Cross-provider MCP server runtime (Claude-side): Codemux hosts user-installed MCP servers, discovers configs across Codemux / Claude / Cursor paths, spawns each child once, dedupes identical configs, exposes tools to the Claude SDK via an in-process facade with dynamic `setMcpServers` refresh. Settings panel and `+` popup both surface enable/disable + status badges + tool list modal + 50-tool cap warning. Codex MCP support planned for Step 11 via HTTP gateway (see `docs/plans/step-9-codex-mcp-spike.md`).
 - Session persistence: terminal scrollback saved/restored across restarts, adapter-based resume for CLI tools (Claude Code)
 - Multi-provider chat (Step 12, Stages 1-9 shipped): the chat composer's model picker drives session creation across Claude + Codex + OpenCode in one unified popover (provider rail + searchable model list). OpenCode federates 100+ upstream providers behind a single rail entry; only the connected upstreams surface (filtered at the data layer). New OpenCode adapter is Rust-direct-HTTP against a managed `opencode serve` child (`kill_on_drop`, generated `OPENCODE_SERVER_PASSWORD`). `ChatModelInfo.sub_provider` threads upstream provider id through the harvest so federated models render with `OpenCode · {sub_provider}` subtitles + namespaced `${provider_id}/${model_id}` slugs. Codex finally selectable in the GUI (was hidden behind a stale `ENABLE_PROVIDER_PICKER` flag pre-Step-12). Favorites persist via zustand + `localStorage` and bubble to the top of search results across all surfaces. Live-tested against OpenCode 1.14.31 (116 providers / 4,354 models). Multi-instance per provider + picker keyboard shortcuts deferred to v2; OpenFlow capabilities convergence tracked as future cleanup. See `docs/features/multi-provider-chat.md`.
@@ -61,6 +61,7 @@ The repo structure is clean and domain-split:
 - OpenFlow: orchestration works but large-run reliability and intervention flow still maturing
 - AI merge resolver: backend and frontend working, needs testing depth and live validation
 - Browser automation depth: DOM commands, coordinate commands, and OS-level input work; wait conditions and JS evaluation added in v0.24.0
+- Browser viewport presets: `codemux browser viewport <mobile|tablet|desktop|WxH|reset>` resizes the actual viewport via CDP so CSS media queries fire and screenshots capture at the simulated dimensions. Names are size buckets (not specific device models) so they don't go stale across hardware refreshes. MCP exposes `browser_viewport` + `browser_viewport_presets`. Replaces the older "wrap the page in a 375px iframe" workaround.
 
 ## Known Constraints
 

docs/features/browser.md

@@ -23,6 +23,7 @@ The browser pane uses a screenshot-driven Chromium session backed by `agent-brow
 - dynamic stream ports (9223-9299) for concurrent workspace browsers
 - browser data management in Settings (clear cookies, clear all data, view data size)
 - inspector panel for debugging web content
+- viewport presets for mobile / tablet / desktop responsive testing via `codemux browser viewport <preset>` (e.g. `mobile`, `tablet`, `desktop-large`, `reset`) or custom `WxH` dimensions — applies real viewport resize + DPR through CDP, so CSS media queries fire and screenshots capture at the simulated dimensions (replaces the older iframe trick)
 
 ## Expected Operating Model
 
@@ -45,8 +46,11 @@ The browser pane uses a screenshot-driven Chromium session backed by `agent-brow
 
 ## Important Touch Points
 
-- `src-tauri/src/agent_browser.rs` — `AgentBrowserManager`, stealth flags, stream port allocation, spawning
+- `src-tauri/src/agent_browser.rs` — `AgentBrowserManager`, stealth flags, stream port allocation, spawning, viewport argv builder (`resolve_viewport_params`, `format_dpr`)
+- `src-tauri/src/browser_viewport.rs` — preset table (`PRESETS`, `RESET_SPEC`) and `parse_spec` for preset / `WxH` / `reset` parsing
 - `src-tauri/src/commands/browser.rs` — Tauri commands for pane creation, URL navigation, automation
-- `src/components/browser/BrowserPane.tsx` — screenshot rendering, toolbar, address bar
+- `src-tauri/src/cli.rs` — `BrowserCommand::Viewport` and `BrowserCommand::ViewportPresets` CLI subcommands
+- `src-tauri/src/mcp_server.rs` — `browser_viewport` and `browser_viewport_presets` MCP tools
+- `src/components/browser/BrowserPane.tsx` — screenshot rendering, toolbar, address bar, auto-syncs viewport on pane resize via legacy `width`/`height` payload (which the new socket handler accepts unchanged)
 - `src/components/browser/InspectorPanel.tsx` — browser inspector/DevTools panel
 - `docs/reference/BROWSER-AGENT-COMMANDS.md` — CLI and socket command reference

docs/reference/BROWSER-AGENT-COMMANDS.md

@@ -90,6 +90,44 @@ codemux browser console-logs [browser_id]
 
 Returns JavaScript console output from the page. Useful for debugging errors.
 
+### Set Viewport (Mobile / Tablet / Desktop Testing)
+
+```bash
+codemux browser viewport <preset>           # mobile / tablet / desktop etc.
+codemux browser viewport 390x844            # custom dimensions
+codemux browser viewport mobile --dpr 2     # preset with DPR override
+codemux browser viewport reset              # restore default
+codemux browser viewport-presets            # list available presets
+```
+
+Resizes the actual browser viewport so CSS media queries fire, `window.devicePixelRatio` reflects the simulated device, and subsequent screenshots capture at the new dimensions. Use this instead of wrapping the page in a 375px iframe — viewport resizing gives true mobile rendering (responsive layout, retina assets, real touch-target sizes) and produces clean screenshots without surrounding desktop chrome.
+
+Available presets (use `viewport-presets` to see the live list):
+
+| Preset | W × H | DPR | Matches |
+|---|---|---|---|
+| `mobile-small` | 320 × 568 | 2 | iPhone SE class, smaller Androids |
+| `mobile` | 390 × 844 | 3 | iPhone 13/14/15, Pixel 7 |
+| `mobile-large` | 430 × 932 | 3 | Pro Max, Pixel Pro |
+| `tablet` | 768 × 1024 | 2 | iPad portrait |
+| `tablet-large` | 1024 × 1366 | 2 | iPad Pro 12.9" |
+| `desktop` | 1280 × 800 | 1 | Standard laptop, Tailwind `xl:` breakpoint |
+| `desktop-large` | 1920 × 1080 | 1 | Full HD |
+| `reset` | 1280 × 800 | 1 | Restore default |
+
+Preset names are deliberately size-bucket labels (not "iPhone 15") so they stay accurate across future hardware refreshes.
+
+Typical workflow:
+
+```bash
+codemux browser open https://mysite.local
+codemux browser viewport mobile
+codemux browser screenshot      # mobile screenshot
+codemux browser viewport tablet
+codemux browser screenshot      # tablet screenshot
+codemux browser viewport reset
+```
+
 ## Socket API Commands
 
 These actions are available via the Codemux control socket. They cover additional functionality not exposed as CLI subcommands.
@@ -191,12 +229,18 @@ Reload the current page.
 
 #### viewport
 
-Set the browser viewport size.
+Set the browser viewport size. Accepts either a preset name or explicit dimensions.
 
 ```json
-{"command":"browser_automation","params":{"browser_id":"default","action":{"kind":"viewport","width":1024,"height":768}}}
+// Preset (recommended)
+{"command":"browser_automation","params":{"browser_id":"default","action":{"kind":"viewport","preset":"mobile"}}}
+
+// Explicit dimensions, optional `scale` for DPR
+{"command":"browser_automation","params":{"browser_id":"default","action":{"kind":"viewport","width":390,"height":844,"scale":3.0}}}
 ```
 
+When both `preset` and `width`/`height` are present, `preset` wins. When neither is set, dimensions default to 1280×720×1.0 (backwards-compat with the pre-preset shape that `BrowserPane.tsx`'s ResizeObserver emits when the user manually resizes the pane).
+
 #### console / console_logs
 
 Get console output.

src-tauri/src/agent_browser.rs

@@ -796,6 +796,53 @@ fn windows_executable_path_args() -> Vec<String> {
     }
 }
 
+/// Resolve the JSON params passed to a `viewport` action into a concrete
+/// `ViewportSpec`. Accepts (in priority order):
+///
+/// 1. `preset` — a named entry from `browser_viewport::PRESETS` or the
+///    literal `"reset"`. Highest priority because it's what the CLI and
+///    MCP tool send; explicit width/height/scale beneath are only used
+///    as fallbacks for legacy callers (e.g. `BrowserPane.tsx`'s
+///    `ResizeObserver` that auto-syncs the pane size on every resize).
+/// 2. `width` + `height` (+ optional `scale` for DPR). This is the
+///    pre-preset shape the frontend already emits, so it stays a
+///    first-class input. Missing fields fall back to 1280×720×1.0.
+///
+/// An unknown preset name falls through to the (1280, 720, 1.0)
+/// fallback because the calling layer (CLI / MCP) is expected to have
+/// already validated the input via `browser_viewport::parse_spec`. The
+/// fallback prevents a typo from breaking the live browser pane.
+fn resolve_viewport_params(params: &serde_json::Value) -> crate::browser_viewport::ViewportSpec {
+    // Preset path (CLI / MCP path).
+    if let Some(name) = params.get("preset").and_then(|v| v.as_str()) {
+        let dpr_override = params.get("scale").and_then(|v| v.as_f64());
+        if let Ok(spec) = crate::browser_viewport::parse_spec(name, dpr_override) {
+            return spec;
+        }
+        // Fall through to width/height path on unknown preset — see doc
+        // comment for the rationale.
+    }
+
+    let width = params.get("width").and_then(|v| v.as_u64()).unwrap_or(1280) as u32;
+    let height = params.get("height").and_then(|v| v.as_u64()).unwrap_or(720) as u32;
+    let dpr = params.get("scale").and_then(|v| v.as_f64()).unwrap_or(1.0);
+    crate::browser_viewport::ViewportSpec::new(width, height, dpr)
+}
+
+/// Format a device-pixel-ratio float for the `agent-browser set viewport
+/// W H [scale]` CLI argument. Trims trailing zeros so `2.0` becomes
+/// `"2"` (cleaner shell echo, smaller argv) but preserves precision when
+/// users pass odd values like `1.5`.
+fn format_dpr(dpr: f64) -> String {
+    if (dpr - dpr.round()).abs() < f64::EPSILON {
+        format!("{}", dpr as u64)
+    } else {
+        // Two decimal places is more than enough — DPR > 3.0 is
+        // already exotic and nobody cares about the third decimal.
+        format!("{dpr:.2}")
+    }
+}
+
 /// Argv-form sibling of `build_agent_browser_command`. Returns a list of
 /// argument vectors, one per agent-browser invocation: most actions are
 /// single-shot, but the historical `open_url` shell form was
@@ -893,16 +940,24 @@ fn build_agent_browser_argv_groups(
         "forward" => vec![vec!["forward".into(), "--session".into(), s]],
         "reload" => vec![vec!["reload".into(), "--session".into(), s]],
         "viewport" => {
-            let w = params.get("width").and_then(|v| v.as_u64()).unwrap_or(1280);
-            let h = params.get("height").and_then(|v| v.as_u64()).unwrap_or(720);
-            vec![vec![
+            let spec = resolve_viewport_params(params);
+            let mut argv = vec![
                 "set".into(),
                 "viewport".into(),
-                w.to_string(),
-                h.to_string(),
-                "--session".into(),
-                s,
-            ]]
+                spec.width.to_string(),
+                spec.height.to_string(),
+            ];
+            // Only pass the scale argument when it differs from 1.0 so
+            // legacy callers that didn't set DPR keep producing the same
+            // exact `set viewport W H` argv. agent-browser treats a
+            // missing 3rd arg as 1.0 anyway, so this is a pure
+            // backwards-compat preservation.
+            if (spec.dpr - 1.0).abs() > f64::EPSILON {
+                argv.push(format_dpr(spec.dpr));
+            }
+            argv.push("--session".into());
+            argv.push(s);
+            vec![argv]
         }
         "get_styles" => {
             let selector = params
@@ -1045,9 +1100,25 @@ fn build_agent_browser_command(session: &str, action: &str, params: &serde_json:
         "forward" => format!("{} forward --session {}", bin, session),
         "reload" => format!("{} reload --session {}", bin, session),
         "viewport" => {
-            let w = params.get("width").and_then(|v| v.as_u64()).unwrap_or(1280);
-            let h = params.get("height").and_then(|v| v.as_u64()).unwrap_or(720);
-            format!("{} set viewport {} {} --session {}", bin, w, h, session)
+            let spec = resolve_viewport_params(params);
+            // Match the argv builder: only emit the scale arg when it
+            // differs from 1.0 so existing call sites that pass plain
+            // {width, height} produce the same exact shell string.
+            if (spec.dpr - 1.0).abs() > f64::EPSILON {
+                format!(
+                    "{} set viewport {} {} {} --session {}",
+                    bin,
+                    spec.width,
+                    spec.height,
+                    format_dpr(spec.dpr),
+                    session
+                )
+            } else {
+                format!(
+                    "{} set viewport {} {} --session {}",
+                    bin, spec.width, spec.height, session
+                )
+            }
         }
         // New v0.24.0 commands
         "get_styles" => {
@@ -1907,6 +1978,126 @@ mod tests {
         assert!(cmd.contains("set viewport 800 600"), "v0.24.0 uses 'set viewport', got: {}", cmd);
     }
 
+    #[cfg(not(target_os = "windows"))]
+    #[test]
+    fn build_command_viewport_omits_dpr_when_one() {
+        // Backwards-compat with the pre-preset call sites (BrowserPane's
+        // ResizeObserver, the old socket clients): a plain {width, height}
+        // payload must produce the same exact `set viewport W H` shell
+        // string with no trailing scale arg.
+        let cmd = build_agent_browser_command(
+            "s",
+            "viewport",
+            &serde_json::json!({"width": 800, "height": 600, "scale": 1.0}),
+        )
+        .unwrap();
+        assert!(
+            cmd.contains("set viewport 800 600 --session"),
+            "scale=1.0 should be omitted to keep argv tight: {}",
+            cmd
+        );
+        assert!(!cmd.contains(" 1 --session"), "no stray '1' DPR arg: {}", cmd);
+    }
+
+    #[cfg(not(target_os = "windows"))]
+    #[test]
+    fn build_command_viewport_emits_dpr_when_retina() {
+        // Mobile presets always pass scale=2 or scale=3 — that must
+        // surface as a 3rd positional arg so agent-browser actually
+        // applies the retina factor (not just resizes the box).
+        let cmd = build_agent_browser_command(
+            "s",
+            "viewport",
+            &serde_json::json!({"width": 390, "height": 844, "scale": 3.0}),
+        )
+        .unwrap();
+        assert!(
+            cmd.contains("set viewport 390 844 3 --session"),
+            "DPR=3 must be 3rd positional arg: {}",
+            cmd
+        );
+    }
+
+    #[cfg(not(target_os = "windows"))]
+    #[test]
+    fn build_command_viewport_resolves_preset_name() {
+        // Preset-name path (CLI / MCP path) must resolve through
+        // browser_viewport::parse_spec and produce the right argv —
+        // catches a regression where someone forgets to wire preset
+        // resolution into the legacy width/height path.
+        let cmd = build_agent_browser_command(
+            "s",
+            "viewport",
+            &serde_json::json!({"preset": "mobile"}),
+        )
+        .unwrap();
+        // mobile = 390x844 @ DPR 3
+        assert!(
+            cmd.contains("set viewport 390 844 3 --session"),
+            "'mobile' preset → 390x844x3: {}",
+            cmd
+        );
+    }
+
+    #[cfg(not(target_os = "windows"))]
+    #[test]
+    fn build_command_viewport_preset_unknown_falls_back() {
+        // An unknown preset must fall back to width/height defaults
+        // (1280×720) rather than fail mid-stream. The CLI / MCP layer is
+        // expected to validate up front; this is the last-line defence.
+        let cmd = build_agent_browser_command(
+            "s",
+            "viewport",
+            &serde_json::json!({"preset": "iphone-99-pro-max-ultra"}),
+        )
+        .unwrap();
+        assert!(
+            cmd.contains("set viewport 1280 720"),
+            "unknown preset should fall back to defaults: {}",
+            cmd
+        );
+    }
+
+    #[cfg(not(target_os = "windows"))]
+    #[test]
+    fn build_command_viewport_preset_reset() {
+        // "reset" preset = RESET_SPEC = 1280x800 @ DPR 1.0; DPR 1.0 must
+        // be omitted from argv (same backwards-compat rule).
+        let cmd = build_agent_browser_command(
+            "s",
+            "viewport",
+            &serde_json::json!({"preset": "reset"}),
+        )
+        .unwrap();
+        assert!(
+            cmd.contains("set viewport 1280 800 --session"),
+            "'reset' preset → 1280x800 with no scale: {}",
+            cmd
+        );
+    }
+
+    #[test]
+    fn format_dpr_integer_round_trips() {
+        // DPRs are floats internally but the CLI argv looks cleaner with
+        // integer DPRs as integers (no trailing ".0").
+        assert_eq!(format_dpr(1.0), "1");
+        assert_eq!(format_dpr(2.0), "2");
+        assert_eq!(format_dpr(3.0), "3");
+    }
+
+    #[test]
+    fn format_dpr_preserves_fractional() {
+        // Odd values (1.5x, 2.75x — yes, some Android phones) must
+        // round-trip to two decimals so we don't silently truncate to 1x.
+        // Note: Rust's `{:.2}` uses banker's rounding (round half to even),
+        // so 2.625 actually rounds to 2.62 — pick values that don't hit
+        // the half-to-even ambiguity to keep this test stable across
+        // platforms and rustc versions.
+        assert_eq!(format_dpr(1.5), "1.50");
+        assert_eq!(format_dpr(2.75), "2.75");
+        assert_eq!(format_dpr(2.626), "2.63");
+    }
+
     #[cfg(not(target_os = "windows"))]
     #[test]
     fn build_command_unknown_action_returns_error() {