replicas-cli 0.2.321 → 0.2.322

package/dist/index.mjs

@@ -7985,7 +7985,7 @@ The CLI is the canonical surface. Chat transcripts that show \`DISPLAY=:99 xdoto
 \`\`\`bash
 # DO
 replicas computer key Return
-replicas computer screenshot /tmp/state.png
+replicas computer observe /tmp/state.png
 
 # DON'T
 DISPLAY=:99 xdotool key Return
@@ -8003,9 +8003,9 @@ replicas computer info
 # 2) Launch a browser on the workspace display.
 replicas computer launch chrome https://news.ycombinator.com
 
-# 3) Take a screenshot so you can see what's there.
-replicas computer screenshot /tmp/state.png
-# (Read the PNG yourself before deciding where to click.)
+# 3) Observe the settled screen and browser tab state before clicking.
+replicas computer observe /tmp/state.png
+replicas computer browser --snapshot
 
 # 4) Drive the UI.
 replicas computer click 521 700                    # click coordinates from the screenshot
@@ -8028,14 +8028,37 @@ If invoked very early in the workspace lifecycle, \`info\` will poll briefly whi
 ### \`replicas computer status\`
 Prints which desktop services are running and the active preview URL (if any). Useful for debugging when a tool call seems to be doing nothing.
 
-### \`replicas computer screenshot <path>\`
-Captures the current desktop to a PNG at the given path. Read the file (e.g. with your Read tool) to see what's on screen - coordinates from the screenshot drive subsequent \`click\` / \`move\` / \`drag\` calls.
+### \`replicas computer screenshot <path> [--raw] [--grid [px]]\`
+Captures the current desktop to a PNG at the given path.
+
+Use \`--raw\` for a 1:1 desktop capture with no branding, padding, or rounded corners. Use \`--grid\` for the same 1:1 capture plus a coordinate grid; the optional value sets grid spacing in pixels and defaults to 100. Use the default branded screenshot only when you plan to share the image with \`replicas media upload\`.
+
+### \`replicas computer observe <path> [--raw] [--grid [px]] [--timeout MS] [--stable-ms MS] [--poll-ms MS]\`
+Waits briefly for the screen to stop changing, saves a 1:1 screenshot, and prints JSON with screen dimensions, whether the screen stabilized, frame/change counts, mouse location, active window title, and visible window titles.
+
+Use this instead of hand-written \`sleep && screenshot\` loops after clicks, navigation, typing, or page loads. By default it saves a 100px coordinate-grid screenshot and waits up to 3s for 600ms of visual stability. Pass \`--raw\` if you need an unannotated 1:1 screenshot.
+
+### \`replicas computer browser\`
+Prints JSON for Chrome tabs launched through Replicas, including page titles and URLs. Pass \`--snapshot\` to include visible page text and interactive controls with DOM viewport bounding boxes.
+
+Use this alongside \`observe\` when testing web apps so you do not infer navigation, page state, or click targets from pixels alone. Snapshot coordinates are DOM viewport coordinates, not desktop click coordinates.
+
+### \`replicas computer browser-click <text> [--exact] [--index N]\`
+Clicks the first visible Chrome control whose text, label, placeholder, or href matches \`<text>\`. Use this for web buttons and links found via \`browser --snapshot\`; it is faster and less error-prone than converting DOM coordinates to desktop pixels.
+
+### \`replicas computer browser-fill <field> <value> [--exact] [--index N]\`
+Fills the first visible Chrome field whose label, placeholder, name, or text matches \`<field>\`, then dispatches input/change events. Use this for web forms instead of clicking a field and typing through the desktop.
+
+### \`replicas computer browser-wait <text> [--mode any|text|title|url|control] [--exact] [--timeout MS]\`
+Waits until the active Chrome page matches text in the title, URL, body text, or visible controls. Use this after \`browser-click\` / \`browser-fill\` when you need web app state to settle without screenshot polling.
+
+For \`browser-click\`, \`browser-fill\`, and \`browser-wait\`, pass \`--id <id>\`, \`--title <text>\`, \`--url <text>\`, or \`--page <n>\` when multiple Chrome tabs are open. Run \`replicas computer browser\` first to list tabs. Prefer \`--id\` when a click may change the page title or URL.
 
 ### \`replicas computer click <x> <y> [--button N] [--double] [--modifiers ctrl+shift]\`
-Move to (x, y) and click. Default is left-click (button 1); pass \`--button 3\` for right-click. \`--modifiers\` holds keys during the click (e.g. ctrl-click a link to open in a new tab).
+Move to (x, y) and click. Coordinates can be absolute pixels or percentages such as \`50%\` \`50%\`. Default is left-click (button 1); pass \`--button 3\` for right-click. \`--modifiers\` holds keys during the click (e.g. ctrl-click a link to open in a new tab).
 
 ### \`replicas computer move <x> <y>\`
-Move the mouse without clicking. Useful for hovering tooltips.
+Move the mouse without clicking. Coordinates can be absolute pixels or percentages. Useful for hovering tooltips.
 
 ### \`replicas computer type <text> [--delay MS]\`
 Type a literal string into the focused field. Default per-character delay is 12ms (~80 wpm) - feels human and avoids breaking apps that debounce input. Bump \`--delay 30\` for stricter apps.
@@ -8046,10 +8069,10 @@ For key combos (not literal text), use \`key\`. \`type "ctrl+l"\` will literally
 Press a single key or combo. Examples: \`Return\`, \`Escape\`, \`Tab\`, \`ctrl+l\`, \`ctrl+shift+t\`, \`alt+Left\`, \`Page_Down\`, \`Home\`. Syntax matches \`xdotool key\`.
 
 ### \`replicas computer scroll <up|down|left|right> [--amount N] [--x X --y Y]\`
-Scroll the wheel. Pass \`--x\` / \`--y\` to hover before scrolling (otherwise scrolls wherever the cursor currently is). Default amount is 3 wheel ticks.
+Scroll the wheel. Pass \`--x\` / \`--y\` to hover before scrolling (otherwise scrolls wherever the cursor currently is). Hover coordinates can be absolute pixels or percentages. Default amount is 3 wheel ticks.
 
 ### \`replicas computer drag <fromX> <fromY> <toX> <toY>\`
-Press left mouse at (fromX, fromY), drag to (toX, toY), release. For things like dragging a file onto an upload zone.
+Press left mouse at (fromX, fromY), drag to (toX, toY), release. Coordinates can be absolute pixels or percentages. For things like dragging a file onto an upload zone.
 
 ### \`replicas computer launch <app> [args...]\`
 Spawns an app on the workspace display. Built-in aliases:
@@ -8072,31 +8095,37 @@ SIGINTs ffmpeg, waits for it to finalize the MP4, prints the output path. Upload
 
 ## Patterns
 
-### Action / screenshot loop
-You are blind between tool calls. After any action that changes the screen, take a screenshot before deciding the next coordinate:
+### Action / observe loop
+You are blind between tool calls. After any action that changes the screen, observe before deciding the next coordinate:
 
 \`\`\`bash
 replicas computer click 521 700
-sleep 2  # let the page settle
-replicas computer screenshot /tmp/after-click.png
-# read /tmp/after-click.png, decide next click
+replicas computer observe /tmp/after-click.png
+# read /tmp/after-click.png and the JSON output, decide next click
 \`\`\`
 
-\`sleep\` is a regular shell sleep - there's no \`replicas computer wait\` command, but you can mix shell sleeps freely.
+The JSON \`stable\`, \`frames\`, and \`changes\` fields tell you whether something changed while you were waiting. If \`stable\` is false, observe again or increase \`--timeout\` before acting on coordinates.
 
 ### Typing into an address bar
 \`\`\`bash
 replicas computer launch chrome
-sleep 2
-replicas computer key ctrl+l                    # focus address bar
+replicas computer observe /tmp/browser-open.png
+replicas computer key ctrl+l
 replicas computer type "https://example.com"
 replicas computer key Return
-sleep 3                                          # wait for page load
-replicas computer screenshot /tmp/loaded.png
+replicas computer observe /tmp/loaded.png
+replicas computer browser --snapshot
+replicas computer browser-fill "Search" "replicas"
+replicas computer browser-click "More information" --title "Example"
+replicas computer browser-wait "Example Domain" --mode title --title "Example"
 \`\`\`
 
 ### Coordinates from screenshots
-The display is 1920\xD71080 by default. Screenshot pixels map 1:1 to click coordinates - if your Read tool shows a button at pixel (520, 700), click \`replicas computer click 520 700\`. **No translation needed.** Modern image-reading models often imagine the screenshot is at a different resolution; trust the \`xdpyinfo\` value (\`replicas computer status\` shows the real size).
+The display is 1920\xD71080 by default. For click planning, use \`observe\`, \`screenshot --raw\`, or \`screenshot --grid\`; those pixels map 1:1 to click coordinates. If the grid/raw screenshot shows a button at pixel (520, 700), click \`replicas computer click 520 700\`. The default screenshot is branded for sharing and has padding around the desktop, so do not use it for coordinates.
+
+Use percentages for broad, layout-relative targets when exact pixels are unnecessary: \`replicas computer click 50% 50%\` clicks the center of the screen, and \`replicas computer move 95% 5%\` moves near the top-right.
+
+Modern image-reading models often imagine the screenshot is at a different resolution. Trust the dimensions printed by \`observe\`, \`replicas computer screenshot ... --raw\` / \`--grid\`, and the \`xdpyinfo\` value shown by \`replicas computer status\`.
 
 ### Letting the user watch
 The Desktop tab is already live in the dashboard - the user can open it any time. If you're communicating with the user somewhere else (Slack, PR comment, etc.), grab the URL with \`replicas computer info\` and share it inline so they can watch you work.
@@ -8115,7 +8144,7 @@ Then embed the printed \`![\u2026](\u2026)\` line in your chat reply. See \`MEDI
 
 - **"Desktop services script missing"**: workspace image is older than this skill. Tell the user - nothing you can do from the CLI side.
 - **\`xdotool ... failed: Can't open display\`**: Xvfb didn't come up. \`replicas computer status\` will show which service is dead. Re-running any CLI command auto-attempts to start it.
-- **Browser doesn't appear after \`launch chrome\`**: give it 1-2s, then screenshot. Chrome cold-start on the virtual display takes ~500ms but bigger pages take longer.
+- **Browser doesn't appear after \`launch chrome\`**: run \`replicas computer observe /tmp/state.png\`. Chrome cold-start on the virtual display takes ~500ms but bigger pages take longer.
 - **Live preview shows static / black screen**: the browser may have crashed. \`replicas computer status\` should show no Chrome process - re-launch.
 - **\`replicas computer info\` errors with "not registered"**: engine couldn't register the preview at startup (transient monolith error, or warming mode). Re-running the engine usually fixes it. Until it's registered, the Desktop tab will show a placeholder.
 
@@ -9507,7 +9536,7 @@ var HOOK_EXEC_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
 var REPLICAS_CONFIG_FILENAMES = ["replicas.json", "replicas.yaml", "replicas.yml"];
 
 // ../shared/src/cli-version.ts
-var CLI_VERSION = "0.2.321";
+var CLI_VERSION = "0.2.322";
 
 // ../shared/src/engine/environment.ts
 var DESKTOP_NOVNC_PORT = 6080;
@@ -14374,7 +14403,8 @@ async function mediaListCommand(options) {
 
 // src/commands/computer.ts
 import { spawn as spawn3, spawnSync } from "child_process";
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, rmSync, writeFileSync } from "fs";
+import { createHash as createHash2 } from "crypto";
+import { closeSync, copyFileSync, existsSync, mkdirSync, openSync, readFileSync, readSync, rmSync, writeFileSync } from "fs";
 import { dirname, isAbsolute, resolve } from "path";
 import chalk20 from "chalk";
 var STATE_DIR = process.env.REPLICAS_DESKTOP_STATE_DIR || "/tmp/replicas-computer";
@@ -14384,6 +14414,15 @@ var SERVICES_SCRIPT = "/usr/local/bin/replicas-start-desktop-services";
 var CHROME_WRAPPER = "/usr/local/bin/replicas-chrome";
 var INFO_WAIT_TIMEOUT_MS = 1e4;
 var INFO_WAIT_INTERVAL_MS = 500;
+var CHROME_DEBUG_PORT = (() => {
+  const value = process.env.REPLICAS_DESKTOP_CHROME_DEBUG_PORT;
+  if (!value) return 9222;
+  const port = parseInt(value, 10);
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    fail(`REPLICAS_DESKTOP_CHROME_DEBUG_PORT must be a valid TCP port, got ${JSON.stringify(value)}`);
+  }
+  return port;
+})();
 function fail(msg) {
   throw new Error(msg);
 }
@@ -14409,14 +14448,41 @@ function runDisplayCmd(bin, args) {
   }
   return r.stdout?.toString() ?? "";
 }
+function tryDisplayCmd(bin, args) {
+  ensureServicesRunning();
+  const r = spawnSync(bin, args, { env: withDisplay(), stdio: "pipe" });
+  if (r.status !== 0) return null;
+  const out = r.stdout?.toString().trim();
+  return out || null;
+}
 function parseCoord(value, label) {
+  if (!/^-?\d+$/.test(value)) fail(`${label} must be an integer (got "${value}")`);
   const n = Number.parseInt(value, 10);
   if (!Number.isFinite(n)) fail(`${label} must be an integer (got "${value}")`);
   return n;
 }
+function getDisplayDimensions() {
+  const out = runDisplayCmd("xdpyinfo", []);
+  const match = out.match(/dimensions:\s+(\d+)x(\d+)\s+pixels/);
+  if (!match) fail("could not read display dimensions from xdpyinfo");
+  return { width: Number.parseInt(match[1], 10), height: Number.parseInt(match[2], 10) };
+}
+function parseScreenCoord(value, label, size) {
+  if (value.endsWith("%")) {
+    const rawPct = value.slice(0, -1);
+    if (!/^(?:\d+(?:\.\d+)?|\.\d+)$/.test(rawPct)) fail(`${label} percent must be a number between 0% and 100% (got "${value}")`);
+    const pct = Number.parseFloat(rawPct);
+    if (!Number.isFinite(pct) || pct < 0 || pct > 100) fail(`${label} percent must be between 0% and 100% (got "${value}")`);
+    return Math.round(pct / 100 * (size - 1));
+  }
+  const n = parseCoord(value, label);
+  if (n < 0 || n >= size) fail(`${label} must be between 0 and ${size - 1} pixels, or 0%-100% (got "${value}")`);
+  return n;
+}
 function resolvePath(p) {
   return isAbsolute(p) ? p : resolve(process.cwd(), p);
 }
+var sleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
 async function lookupDesktopViewerUrl() {
   try {
     const list = await listAgentPreviews();
@@ -14493,7 +14559,59 @@ var SHADOW_OFFSET_Y_FRACTION = 0.013;
 var SHADOW_ALPHA = 0.6;
 var SCREENSHOT_MASK_TEMPLATE = `<svg width="__W__" height="__H__" xmlns="http://www.w3.org/2000/svg"><rect width="__W__" height="__H__" rx="__R__" ry="__R__" fill="white"/></svg>`;
 var SHADOW_MASK_TEMPLATE = `<svg width="__SW__" height="__SH__" xmlns="http://www.w3.org/2000/svg"><rect x="__M__" y="__M__" width="__W__" height="__H__" rx="__R__" ry="__R__" fill="white"/></svg>`;
-async function computerScreenshotCommand(path6) {
+function parseGridSize(value) {
+  if (value === void 0 || value === false) return null;
+  const size = value === true ? 100 : parseCoord(value, "--grid");
+  if (size < 25 || size > 500) fail("--grid must be between 25 and 500 pixels");
+  return size;
+}
+function buildGridSvg(width, height, size) {
+  const lines = [];
+  const labels = [];
+  for (let x = 0; x <= width; x += size) {
+    const strokeWidth = x % (size * 5) === 0 ? 2 : 1;
+    lines.push(`<line x1="${x}" y1="0" x2="${x}" y2="${height}" stroke="#00e5ff" stroke-opacity="0.42" stroke-width="${strokeWidth}"/>`);
+    if (x > 0 && x < width) labels.push(`<text x="${x + 4}" y="18">${x}</text>`);
+  }
+  for (let y = 0; y <= height; y += size) {
+    const strokeWidth = y % (size * 5) === 0 ? 2 : 1;
+    lines.push(`<line x1="0" y1="${y}" x2="${width}" y2="${y}" stroke="#00e5ff" stroke-opacity="0.42" stroke-width="${strokeWidth}"/>`);
+    if (y > 0 && y < height) labels.push(`<text x="4" y="${y - 4}">${y}</text>`);
+  }
+  return `<svg width="${width}" height="${height}" xmlns="http://www.w3.org/2000/svg">
+<style>text{font:16px monospace;fill:white;paint-order:stroke;stroke:black;stroke-width:4px;stroke-linejoin:round}</style>
+${lines.join("\n")}
+${labels.join("\n")}
+</svg>`;
+}
+function overlayGrid(rawPath, target, width, height, gridSize, gridPath) {
+  writeFileSync(gridPath, buildGridSvg(width, height, gridSize));
+  const r = spawnSync(
+    "ffmpeg",
+    [
+      "-y",
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      "-i",
+      rawPath,
+      "-i",
+      gridPath,
+      "-filter_complex",
+      "[0:v][1:v]overlay=0:0:format=auto",
+      "-frames:v",
+      "1",
+      "-update",
+      "1",
+      target
+    ],
+    { stdio: "pipe" }
+  );
+  if (r.status !== 0) {
+    fail(`ffmpeg grid overlay failed: ${r.stderr?.toString().trim() || `exit ${r.status}`}`);
+  }
+}
+async function computerScreenshotCommand(path6, options = {}) {
   const target = resolvePath(path6);
   mkdirSync(dirname(target), { recursive: true });
   const stamp = `${process.pid}-${Date.now()}`;
@@ -14501,9 +14619,21 @@ async function computerScreenshotCommand(path6) {
   const svgPath = `/tmp/replicas-screenshot-${stamp}.brand.svg`;
   const maskPath = `/tmp/replicas-screenshot-${stamp}.mask.svg`;
   const shadowPath = `/tmp/replicas-screenshot-${stamp}.shadow.svg`;
+  const gridPath = `/tmp/replicas-screenshot-${stamp}.grid.svg`;
   try {
     runDisplayCmd("scrot", ["-o", rawPath]);
     const { width, height } = readPngDimensions(rawPath);
+    const gridSize = parseGridSize(options.grid);
+    if (options.raw && gridSize === null) {
+      copyFileSync(rawPath, target);
+      console.log(`${target} (${width}x${height}, raw 1:1 desktop pixels)`);
+      return;
+    }
+    if (gridSize !== null) {
+      overlayGrid(rawPath, target, width, height, gridSize, gridPath);
+      console.log(`${target} (${width}x${height}, raw 1:1 desktop pixels, ${gridSize}px grid)`);
+      return;
+    }
     const padX = Math.round(width * BRAND_PAD_FRACTION);
     const padY = Math.round(height * BRAND_PAD_FRACTION);
     const canvasW = width + padX * 2;
@@ -14557,12 +14687,542 @@ async function computerScreenshotCommand(path6) {
     rmSync(svgPath, { force: true });
     rmSync(maskPath, { force: true });
     rmSync(shadowPath, { force: true });
+    rmSync(gridPath, { force: true });
   }
   console.log(target);
 }
+function hashFile(path6) {
+  return createHash2("sha256").update(readFileSync(path6)).digest("hex");
+}
+async function captureStableRawScreenshot(target, options) {
+  const start = Date.now();
+  const framePath = `${target}.frame.png`;
+  let lastHash = null;
+  let lastChangeAt = start;
+  let frames = 0;
+  let changes = 0;
+  let width = 0;
+  let height = 0;
+  try {
+    while (Date.now() - start <= options.timeoutMs) {
+      runDisplayCmd("scrot", ["-o", framePath]);
+      frames++;
+      const dimensions = readPngDimensions(framePath);
+      width = dimensions.width;
+      height = dimensions.height;
+      const hash = hashFile(framePath);
+      const now = Date.now();
+      if (lastHash === null) {
+        lastChangeAt = now;
+      } else if (hash !== lastHash) {
+        changes++;
+        lastChangeAt = now;
+      }
+      lastHash = hash;
+      copyFileSync(framePath, target);
+      if (frames > 1 && now - lastChangeAt >= options.stableMs) {
+        return { width, height, stable: true, elapsedMs: now - start, frames, changes };
+      }
+      await sleep(options.pollMs);
+    }
+    return { width, height, stable: false, elapsedMs: Date.now() - start, frames, changes };
+  } finally {
+    rmSync(framePath, { force: true });
+  }
+}
+function getMouseLocation() {
+  const out = tryDisplayCmd("xdotool", ["getmouselocation", "--shell"]);
+  if (!out) return null;
+  const values = Object.fromEntries(
+    out.split("\n").map((line) => {
+      const [key, value] = line.split("=");
+      return [key.toLowerCase(), Number.parseInt(value, 10)];
+    })
+  );
+  if (!Number.isFinite(values.x) || !Number.isFinite(values.y)) return null;
+  return {
+    x: values.x,
+    y: values.y,
+    screen: Number.isFinite(values.screen) ? values.screen : 0,
+    window: Number.isFinite(values.window) ? values.window : 0
+  };
+}
+function getActiveWindowTitle() {
+  return tryDisplayCmd("xdotool", ["getactivewindow", "getwindowname"]);
+}
+function getVisibleWindowTitles() {
+  const out = tryDisplayCmd("xdotool", ["search", "--onlyvisible", "--name", ".", "getwindowname", "%@"]);
+  return out ? out.split("\n").filter(Boolean).slice(0, 20) : [];
+}
+async function computerObserveCommand(path6, options = {}) {
+  const target = resolvePath(path6);
+  mkdirSync(dirname(target), { recursive: true });
+  const timeoutMs = options.timeout ? parseCoord(options.timeout, "--timeout") : 3e3;
+  const stableMs = options.stableMs ? parseCoord(options.stableMs, "--stable-ms") : 600;
+  const pollMs = options.pollMs ? parseCoord(options.pollMs, "--poll-ms") : 200;
+  if (timeoutMs < 0) fail("--timeout must be >= 0");
+  if (stableMs < 0) fail("--stable-ms must be >= 0");
+  if (pollMs < 50 || pollMs > 2e3) fail("--poll-ms must be between 50 and 2000");
+  const stamp = `${process.pid}-${Date.now()}`;
+  const rawPath = `/tmp/replicas-observe-${stamp}.raw.png`;
+  const gridPath = `/tmp/replicas-observe-${stamp}.grid.svg`;
+  try {
+    const capture = await captureStableRawScreenshot(rawPath, { timeoutMs, stableMs, pollMs });
+    const gridSize = options.raw ? null : parseGridSize(options.grid ?? true);
+    if (gridSize === null) {
+      copyFileSync(rawPath, target);
+    } else {
+      overlayGrid(rawPath, target, capture.width, capture.height, gridSize, gridPath);
+    }
+    console.log(JSON.stringify({
+      screenshot: target,
+      width: capture.width,
+      height: capture.height,
+      stable: capture.stable,
+      elapsedMs: capture.elapsedMs,
+      frames: capture.frames,
+      changes: capture.changes,
+      mouse: getMouseLocation(),
+      activeWindow: getActiveWindowTitle(),
+      visibleWindows: getVisibleWindowTitles(),
+      mode: gridSize === null ? "raw" : "grid",
+      gridSize
+    }, null, 2));
+  } finally {
+    rmSync(rawPath, { force: true });
+    rmSync(gridPath, { force: true });
+  }
+}
+async function fetchChromeJson(path6) {
+  let res;
+  try {
+    res = await fetch(`http://127.0.0.1:${CHROME_DEBUG_PORT}${path6}`);
+  } catch {
+    fail(
+      `Chrome DevTools is not available on localhost:${CHROME_DEBUG_PORT}. Launch Chrome with \`replicas computer launch chrome <url>\` and try again.`
+    );
+  }
+  if (!res.ok) fail(`Chrome DevTools returned HTTP ${res.status}`);
+  try {
+    return await res.json();
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    fail(`Chrome DevTools returned invalid JSON from ${path6}: ${reason}`);
+  }
+}
+async function getChromePages() {
+  const targets = await fetchChromeJson("/json/list");
+  if (!Array.isArray(targets)) fail("Chrome DevTools returned an unexpected target list");
+  return targets.filter((target) => typeof target === "object" && target !== null).filter((target) => target.type === "page");
+}
+async function selectChromePage(options = {}) {
+  const pages = await getChromePages();
+  let matches = pages;
+  if (options.id) {
+    matches = matches.filter((page2) => page2.id === options.id);
+  }
+  if (options.title) {
+    const needle = options.title.toLowerCase();
+    matches = matches.filter((page2) => (page2.title ?? "").toLowerCase().includes(needle));
+  }
+  if (options.url) {
+    const needle = options.url.toLowerCase();
+    matches = matches.filter((page2) => (page2.url ?? "").toLowerCase().includes(needle));
+  }
+  const index = options.page ? parseCoord(options.page, "--page") : 0;
+  if (index < 0) fail("--page must be >= 0");
+  const page = matches[index];
+  const webSocketDebuggerUrl = page?.webSocketDebuggerUrl;
+  if (!webSocketDebuggerUrl) {
+    fail(
+      `No matching debuggable Chrome page found (${matches.length} match${matches.length === 1 ? "" : "es"}, index ${index}). Use \`replicas computer browser\` to list pages.`
+    );
+  }
+  return { ...page, webSocketDebuggerUrl };
+}
+function buildBrowserSnapshotExpression(textLimit, elementLimit) {
+  return `(() => {
+    const clip = (value, limit) => String(value || '').replace(/\\s+/g, ' ').trim().slice(0, limit);
+    const escape = (value) => globalThis.CSS && CSS.escape ? CSS.escape(value) : String(value).replace(/["\\\\]/g, '\\\\$&');
+    const visible = (el) => {
+      const rect = el.getBoundingClientRect();
+      const style = getComputedStyle(el);
+      return rect.width > 0 && rect.height > 0 && style.visibility !== 'hidden' && style.display !== 'none';
+    };
+    const labels = (el) => {
+      const values = [];
+      const id = el.getAttribute('id');
+      if (id) values.push(...Array.from(document.querySelectorAll('label[for="' + escape(id) + '"]')).map((label) => label.innerText));
+      const wrappingLabel = el.closest('label');
+      if (wrappingLabel) values.push(wrappingLabel.innerText);
+      values.push(el.innerText, el.value, el.getAttribute('aria-label'), el.getAttribute('title'), el.getAttribute('placeholder'), el.href, el.id, el.name, el.tagName);
+      return values.map((value) => clip(value, 160)).filter(Boolean);
+    };
+    const name = (el) => labels(el)[0] || clip(el.tagName, 160);
+    const selector = 'a,button,input,textarea,select,[role="button"],[role="link"],[role="textbox"],[contenteditable="true"]';
+    const controls = Array.from(document.querySelectorAll(selector))
+      .filter(visible)
+      .slice(0, ${elementLimit})
+      .map((el) => {
+        const rect = el.getBoundingClientRect();
+        return {
+          tag: el.tagName.toLowerCase(),
+          role: el.getAttribute('role') || null,
+          type: el.getAttribute('type') || null,
+          text: name(el),
+          href: el.href || null,
+          disabled: !!el.disabled || el.getAttribute('aria-disabled') === 'true',
+          rect: {
+            x: Math.round(rect.x),
+            y: Math.round(rect.y),
+            width: Math.round(rect.width),
+            height: Math.round(rect.height),
+            centerX: Math.round(rect.x + rect.width / 2),
+            centerY: Math.round(rect.y + rect.height / 2),
+          },
+        };
+      });
+    return {
+      title: document.title,
+      url: location.href,
+      text: clip(document.body ? document.body.innerText : '', ${textLimit}),
+      controls,
+    };
+  })()`;
+}
+async function evaluateChromeTarget(webSocketDebuggerUrl, expression) {
+  return await new Promise((resolve2, reject) => {
+    const ws = new WebSocket(webSocketDebuggerUrl);
+    let settled = false;
+    const finish = (callback) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      ws.close();
+      callback();
+    };
+    const timeout = setTimeout(() => {
+      finish(() => reject(new Error("Chrome DevTools evaluation timed out")));
+    }, 5e3);
+    ws.addEventListener("open", () => {
+      ws.send(JSON.stringify({
+        id: 1,
+        method: "Runtime.evaluate",
+        params: {
+          expression,
+          awaitPromise: true,
+          returnByValue: true
+        }
+      }));
+    });
+    ws.addEventListener("message", (event) => {
+      const data = typeof event.data === "string" ? event.data : Buffer.from(event.data).toString("utf8");
+      let parsed;
+      try {
+        parsed = JSON.parse(data);
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        finish(() => reject(new Error(`Chrome DevTools returned invalid WebSocket JSON: ${reason}`)));
+        return;
+      }
+      if (typeof parsed !== "object" || parsed === null) {
+        finish(() => reject(new Error("Chrome DevTools returned an invalid WebSocket message")));
+        return;
+      }
+      const message = parsed;
+      if (message.id !== 1) return;
+      if (message.error) {
+        finish(() => reject(new Error(message.error?.message || "Chrome DevTools evaluation failed")));
+        return;
+      }
+      if (message.result?.exceptionDetails) {
+        finish(() => reject(new Error(message.result.exceptionDetails.text || "Chrome DevTools evaluation threw")));
+        return;
+      }
+      finish(() => resolve2(message.result?.result?.value ?? null));
+    });
+    ws.addEventListener("error", () => {
+      finish(() => reject(new Error("Chrome DevTools WebSocket failed")));
+    });
+  });
+}
+async function computerBrowserCommand(options = {}) {
+  const textLimit = options.limit ? parseCoord(options.limit, "--limit") : 4e3;
+  const elementLimit = options.elementLimit ? parseCoord(options.elementLimit, "--element-limit") : 80;
+  if (textLimit < 0 || textLimit > 5e4) fail("--limit must be between 0 and 50000");
+  if (elementLimit < 0 || elementLimit > 500) fail("--element-limit must be between 0 and 500");
+  const expression = buildBrowserSnapshotExpression(textLimit, elementLimit);
+  const pages = (await getChromePages()).map((target) => ({
+    target,
+    page: {
+      id: target.id ?? null,
+      title: target.title ?? "",
+      url: target.url ?? "",
+      attached: !!target.attached
+    }
+  }));
+  const pageResults = [];
+  for (const { target, page } of pages) {
+    if (options.snapshot && target.webSocketDebuggerUrl) {
+      try {
+        pageResults.push({ ...page, snapshot: await evaluateChromeTarget(target.webSocketDebuggerUrl, expression) });
+      } catch (error) {
+        pageResults.push({ ...page, snapshotError: error instanceof Error ? error.message : "snapshot failed" });
+      }
+    } else {
+      pageResults.push(page);
+    }
+  }
+  console.log(JSON.stringify({
+    port: CHROME_DEBUG_PORT,
+    pageCount: pageResults.length,
+    pages: pageResults
+  }, null, 2));
+}
+function buildBrowserClickExpression(query, options) {
+  return `(() => {
+    const query = ${JSON.stringify(query)};
+    const exact = ${JSON.stringify(options.exact)};
+    const index = ${options.index};
+    const normalize = (value) => String(value || '').replace(/\\s+/g, ' ').trim();
+    const visible = (el) => {
+      const rect = el.getBoundingClientRect();
+      const style = getComputedStyle(el);
+      return rect.width > 0 && rect.height > 0 && style.visibility !== 'hidden' && style.display !== 'none';
+    };
+    const label = (el) => normalize(el.innerText || el.value || el.getAttribute('aria-label') || el.getAttribute('title') || el.getAttribute('placeholder') || el.href || el.id || el.name || el.tagName);
+    const matches = (text) => {
+      const haystack = text.toLowerCase();
+      const needle = query.toLowerCase();
+      return exact ? haystack === needle : haystack.includes(needle);
+    };
+    const selector = 'a,button,input,textarea,select,[role="button"],[role="link"],[role="textbox"],[contenteditable="true"]';
+    const candidates = Array.from(document.querySelectorAll(selector))
+      .filter(visible)
+      .map((el) => ({ el, text: label(el) }))
+      .filter((candidate) => candidate.text && matches(candidate.text));
+    const candidate = candidates[index];
+    if (!candidate) {
+      return {
+        clicked: false,
+        query,
+        matchCount: candidates.length,
+        reason: candidates.length ? 'index out of range' : 'no visible matching control',
+      };
+    }
+    const { el, text } = candidate;
+    el.scrollIntoView({ block: 'center', inline: 'center' });
+    const rect = el.getBoundingClientRect();
+    if (typeof el.focus === 'function') el.focus();
+    el.click();
+    return {
+      clicked: true,
+      query,
+      matchCount: candidates.length,
+      index,
+      tag: el.tagName.toLowerCase(),
+      role: el.getAttribute('role') || null,
+      type: el.getAttribute('type') || null,
+      text,
+      href: el.href || null,
+      rect: {
+        x: Math.round(rect.x),
+        y: Math.round(rect.y),
+        width: Math.round(rect.width),
+        height: Math.round(rect.height),
+        centerX: Math.round(rect.x + rect.width / 2),
+        centerY: Math.round(rect.y + rect.height / 2),
+      },
+    };
+  })()`;
+}
+async function computerBrowserClickCommand(query, options = {}) {
+  const page = await selectChromePage(options);
+  const index = options.index ? parseCoord(options.index, "--index") : 0;
+  if (index < 0) fail("--index must be >= 0");
+  const result = await evaluateChromeTarget(
+    page.webSocketDebuggerUrl,
+    buildBrowserClickExpression(query, { exact: !!options.exact, index })
+  );
+  console.log(JSON.stringify({
+    title: page.title ?? "",
+    url: page.url ?? "",
+    result
+  }, null, 2));
+}
+function buildBrowserFillExpression(query, value, options) {
+  return `(() => {
+    const query = ${JSON.stringify(query)};
+    const value = ${JSON.stringify(value)};
+    const exact = ${JSON.stringify(options.exact)};
+    const index = ${options.index};
+    const normalize = (text) => String(text || '').replace(/\\s+/g, ' ').trim();
+    const escape = (text) => globalThis.CSS && CSS.escape ? CSS.escape(text) : String(text).replace(/["\\\\]/g, '\\\\$&');
+    const visible = (el) => {
+      const rect = el.getBoundingClientRect();
+      const style = getComputedStyle(el);
+      return rect.width > 0 && rect.height > 0 && style.visibility !== 'hidden' && style.display !== 'none';
+    };
+    const matches = (text) => {
+      const haystack = text.toLowerCase();
+      const needle = query.toLowerCase();
+      return exact ? haystack === needle : haystack.includes(needle);
+    };
+    const labelParts = (el) => {
+      const id = el.getAttribute('id');
+      const labels = [];
+      if (id) labels.push(...Array.from(document.querySelectorAll('label[for="' + escape(id) + '"]')).map((label) => label.innerText));
+      const wrappingLabel = el.closest('label');
+      if (wrappingLabel) labels.push(wrappingLabel.innerText);
+      labels.push(
+        el.getAttribute('aria-label'),
+        el.getAttribute('title'),
+        el.getAttribute('placeholder'),
+        el.getAttribute('name'),
+        el.getAttribute('id'),
+        el.value,
+        el.innerText,
+      );
+      return labels.map(normalize).filter(Boolean);
+    };
+    const labelText = (el) => labelParts(el).join(' ');
+    const fieldMatches = (el) => {
+      const parts = labelParts(el);
+      return exact ? parts.some(matches) : matches(parts.join(' '));
+    };
+    const selector = 'input:not([type="button"]):not([type="submit"]):not([type="reset"]):not([type="checkbox"]):not([type="radio"]),textarea,select,[role="textbox"],[contenteditable="true"]';
+    const candidates = Array.from(document.querySelectorAll(selector))
+      .filter(visible)
+      .map((el) => ({ el, text: labelText(el) }))
+      .filter((candidate) => candidate.text && fieldMatches(candidate.el));
+    const candidate = candidates[index];
+    if (!candidate) {
+      return {
+        filled: false,
+        query,
+        matchCount: candidates.length,
+        reason: candidates.length ? 'index out of range' : 'no visible matching field',
+      };
+    }
+    const { el, text } = candidate;
+    el.scrollIntoView({ block: 'center', inline: 'center' });
+    if (typeof el.focus === 'function') el.focus();
+    if (el.tagName.toLowerCase() === 'select') {
+      const option = Array.from(el.options).find((item) => item.value === value || normalize(item.text) === value);
+      if (option) el.value = option.value;
+      else el.value = value;
+    } else if (el.isContentEditable) {
+      el.textContent = value;
+    } else {
+      el.value = value;
+    }
+    el.dispatchEvent(new InputEvent('input', { bubbles: true, inputType: 'insertText', data: value }));
+    el.dispatchEvent(new Event('change', { bubbles: true }));
+    const rect = el.getBoundingClientRect();
+    return {
+      filled: true,
+      query,
+      matchCount: candidates.length,
+      index,
+      tag: el.tagName.toLowerCase(),
+      role: el.getAttribute('role') || null,
+      type: el.getAttribute('type') || null,
+      text,
+      value: el.isContentEditable ? el.textContent : el.value,
+      rect: {
+        x: Math.round(rect.x),
+        y: Math.round(rect.y),
+        width: Math.round(rect.width),
+        height: Math.round(rect.height),
+        centerX: Math.round(rect.x + rect.width / 2),
+        centerY: Math.round(rect.y + rect.height / 2),
+      },
+    };
+  })()`;
+}
+async function computerBrowserFillCommand(query, value, options = {}) {
+  const page = await selectChromePage(options);
+  const index = options.index ? parseCoord(options.index, "--index") : 0;
+  if (index < 0) fail("--index must be >= 0");
+  const result = await evaluateChromeTarget(
+    page.webSocketDebuggerUrl,
+    buildBrowserFillExpression(query, value, { exact: !!options.exact, index })
+  );
+  console.log(JSON.stringify({
+    title: page.title ?? "",
+    url: page.url ?? "",
+    result
+  }, null, 2));
+}
+function buildBrowserWaitExpression(query, options) {
+  return `(() => {
+    const query = ${JSON.stringify(query)};
+    const mode = ${JSON.stringify(options.mode)};
+    const exact = ${JSON.stringify(options.exact)};
+    const normalize = (text) => String(text || '').replace(/\\s+/g, ' ').trim();
+    const visible = (el) => {
+      const rect = el.getBoundingClientRect();
+      const style = getComputedStyle(el);
+      return rect.width > 0 && rect.height > 0 && style.visibility !== 'hidden' && style.display !== 'none';
+    };
+    const matches = (text) => {
+      const haystack = normalize(text).toLowerCase();
+      const needle = query.toLowerCase();
+      return exact ? haystack === needle : haystack.includes(needle);
+    };
+    const controlText = (el) => normalize(el.innerText || el.value || el.getAttribute('aria-label') || el.getAttribute('title') || el.getAttribute('placeholder') || el.href || el.id || el.name || el.tagName);
+    const controls = () => Array.from(document.querySelectorAll('a,button,input,textarea,select,[role="button"],[role="link"],[role="textbox"],[contenteditable="true"]'))
+      .filter(visible)
+      .map(controlText)
+      .filter(Boolean);
+    const values = {
+      title: [document.title],
+      url: [location.href],
+      text: [document.body ? document.body.innerText : ''],
+      control: controls(),
+      any: [document.title, location.href, document.body ? document.body.innerText : '', ...controls()],
+    }[mode];
+    if (!values) return { matched: false, query, mode, reason: 'invalid mode' };
+    const match = values.find(matches) || null;
+    return {
+      matched: !!match,
+      query,
+      mode,
+      exact,
+      match: match ? normalize(match).slice(0, 500) : null,
+      title: document.title,
+      url: location.href,
+    };
+  })()`;
+}
+async function computerBrowserWaitCommand(query, options = {}) {
+  const mode = options.mode ?? "any";
+  if (!["any", "text", "title", "url", "control"].includes(mode)) fail("--mode must be one of any|text|title|url|control");
+  const timeoutMs = options.timeout ? parseCoord(options.timeout, "--timeout") : 1e4;
+  const pollMs = options.pollMs ? parseCoord(options.pollMs, "--poll-ms") : 250;
+  if (timeoutMs < 0) fail("--timeout must be >= 0");
+  if (pollMs < 50 || pollMs > 2e3) fail("--poll-ms must be between 50 and 2000");
+  const page = await selectChromePage(options);
+  const start = Date.now();
+  const expression = buildBrowserWaitExpression(query, { mode, exact: !!options.exact });
+  let attempts = 0;
+  let lastResult = null;
+  while (Date.now() - start <= timeoutMs) {
+    attempts++;
+    lastResult = await evaluateChromeTarget(page.webSocketDebuggerUrl, expression);
+    if (typeof lastResult === "object" && lastResult !== null && "matched" in lastResult && lastResult.matched) {
+      console.log(JSON.stringify({ ok: true, elapsedMs: Date.now() - start, attempts, result: lastResult }, null, 2));
+      return;
+    }
+    await sleep(pollMs);
+  }
+  console.log(JSON.stringify({ ok: false, elapsedMs: Date.now() - start, attempts, result: lastResult }, null, 2));
+  process.exitCode = 1;
+}
 async function computerClickCommand(xStr, yStr, options) {
-  const x = parseCoord(xStr, "x");
-  const y = parseCoord(yStr, "y");
+  const dimensions = getDisplayDimensions();
+  const x = parseScreenCoord(xStr, "x", dimensions.width);
+  const y = parseScreenCoord(yStr, "y", dimensions.height);
   const button = options.button ?? "1";
   const args = ["mousemove", "--sync", String(x), String(y)];
   if (options.modifiers) {
@@ -14584,8 +15244,9 @@ async function computerClickCommand(xStr, yStr, options) {
   console.log(`clicked ${button === "1" ? "left" : button === "2" ? "middle" : button === "3" ? "right" : `button ${button}`} at (${x},${y})${options.double ? " x2" : ""}`);
 }
 async function computerMoveCommand(xStr, yStr) {
-  const x = parseCoord(xStr, "x");
-  const y = parseCoord(yStr, "y");
+  const dimensions = getDisplayDimensions();
+  const x = parseScreenCoord(xStr, "x", dimensions.width);
+  const y = parseScreenCoord(yStr, "y", dimensions.height);
   runDisplayCmd("xdotool", ["mousemove", "--sync", String(x), String(y)]);
   console.log(`moved to (${x},${y})`);
 }
@@ -14606,17 +15267,24 @@ async function computerScrollCommand(direction, options) {
   const amount = options.amount ? parseCoord(options.amount, "--amount") : 3;
   const args = [];
   if (options.x && options.y) {
-    args.push("mousemove", "--sync", options.x, options.y);
+    const dimensions = getDisplayDimensions();
+    args.push(
+      "mousemove",
+      "--sync",
+      String(parseScreenCoord(options.x, "--x", dimensions.width)),
+      String(parseScreenCoord(options.y, "--y", dimensions.height))
+    );
   }
   args.push("click", "--repeat", String(amount), "--delay", "30", button);
   runDisplayCmd("xdotool", args);
   console.log(`scrolled ${dir} x${amount}`);
 }
 async function computerDragCommand(fx, fy, tx, ty) {
-  const fromX = parseCoord(fx, "fromX");
-  const fromY = parseCoord(fy, "fromY");
-  const toX = parseCoord(tx, "toX");
-  const toY = parseCoord(ty, "toY");
+  const dimensions = getDisplayDimensions();
+  const fromX = parseScreenCoord(fx, "fromX", dimensions.width);
+  const fromY = parseScreenCoord(fy, "fromY", dimensions.height);
+  const toX = parseScreenCoord(tx, "toX", dimensions.width);
+  const toY = parseScreenCoord(ty, "toY", dimensions.height);
   runDisplayCmd("xdotool", [
     "mousemove",
     "--sync",
@@ -19043,13 +19711,18 @@ if (isAgentMode()) {
   };
   computer.command("info").description("Print the live noVNC viewer URL for the workspace desktop. The preview is registered automatically at engine startup, so this just looks it up \u2014 share the URL with the user to let them watch the desktop.").action(wrap(() => computerInfoCommand()));
   computer.command("status").description("Show which desktop services are running and the active preview URL").action(wrap(() => computerStatusCommand()));
-  computer.command("screenshot <path>").description("Capture the current desktop to a PNG file. Use the path with `replicas media upload` to share it.").action(wrap((path6) => computerScreenshotCommand(path6)));
-  computer.command("click <x> <y>").description("Move to (x, y) and click. Coordinates are in pixels on the workspace display.").option("-b, --button <n>", "Mouse button (1=left, 2=middle, 3=right). Default 1.").option("--double", "Double-click instead of single-click").option("--modifiers <mods>", "Hold modifier keys during the click, e.g. ctrl or ctrl+shift").action(wrap((x, y, options) => computerClickCommand(x, y, options)));
-  computer.command("move <x> <y>").description("Move the mouse to (x, y) without clicking").action(wrap((x, y) => computerMoveCommand(x, y)));
+  computer.command("screenshot <path>").description("Capture the current desktop to a PNG file. Use --raw or --grid for agent click planning; omit both for a branded shareable image.").option("--raw", "Save a 1:1 desktop capture with no branding, padding, or rounded corners").option("--grid [px]", "Overlay a coordinate grid on a 1:1 desktop capture. Default 100px.").action(wrap((path6, options) => computerScreenshotCommand(path6, options)));
+  computer.command("observe <path>").description("Wait briefly for the desktop to settle, save a 1:1 screenshot, and print JSON screen context for agents.").option("--raw", "Save a 1:1 desktop capture with no coordinate grid").option("--grid [px]", "Overlay a coordinate grid on the 1:1 desktop capture. Default 100px.").option("--timeout <ms>", "Maximum time to wait for visual stability. Default 3000.").option("--stable-ms <ms>", "Required unchanged time before the screen is considered stable. Default 600.").option("--poll-ms <ms>", "Screenshot polling interval while waiting. Default 200.").action(wrap((path6, options) => computerObserveCommand(path6, options)));
+  computer.command("browser").description("Print JSON for Chrome tabs launched through Replicas, including page titles and URLs.").option("--snapshot", "Include visible page text and interactive controls with bounding boxes").option("--limit <chars>", "Maximum body text characters per page snapshot. Default 4000.").option("--element-limit <n>", "Maximum controls per page snapshot. Default 80.").action(wrap((options) => computerBrowserCommand(options)));
+  computer.command("browser-click <text>").description("Click the first visible Chrome control whose text, label, placeholder, or href matches <text>.").option("--exact", "Require an exact text match instead of substring matching").option("--index <n>", "When multiple controls match, click the nth match. Default 0.").option("--id <id>", "Only target the Chrome page with this target id").option("--page <n>", "When multiple pages match, target the nth page. Default 0.").option("--title <text>", "Only target pages whose title contains text").option("--url <text>", "Only target pages whose URL contains text").action(wrap((text, options) => computerBrowserClickCommand(text, options)));
+  computer.command("browser-fill <field> <value>").description("Fill the first visible Chrome field whose label, placeholder, name, or text matches <field>.").option("--exact", "Require an exact field match instead of substring matching").option("--index <n>", "When multiple fields match, fill the nth match. Default 0.").option("--id <id>", "Only target the Chrome page with this target id").option("--page <n>", "When multiple pages match, target the nth page. Default 0.").option("--title <text>", "Only target pages whose title contains text").option("--url <text>", "Only target pages whose URL contains text").action(wrap((field, value, options) => computerBrowserFillCommand(field, value, options)));
+  computer.command("browser-wait <text>").description("Wait until Chrome page title, URL, body text, or controls match <text>.").option("--mode <mode>", "Where to match: any, text, title, url, or control. Default any.").option("--exact", "Require an exact match instead of substring matching").option("--timeout <ms>", "Maximum time to wait. Default 10000.").option("--poll-ms <ms>", "Polling interval. Default 250.").option("--id <id>", "Only target the Chrome page with this target id").option("--page <n>", "When multiple pages match, target the nth page. Default 0.").option("--title <text>", "Only target pages whose title contains text").option("--url <text>", "Only target pages whose URL contains text").action(wrap((text, options) => computerBrowserWaitCommand(text, options)));
+  computer.command("click <x> <y>").description("Move to (x, y) and click. Coordinates are pixels or percentages like 50% 50%.").option("-b, --button <n>", "Mouse button (1=left, 2=middle, 3=right). Default 1.").option("--double", "Double-click instead of single-click").option("--modifiers <mods>", "Hold modifier keys during the click, e.g. ctrl or ctrl+shift").action(wrap((x, y, options) => computerClickCommand(x, y, options)));
+  computer.command("move <x> <y>").description("Move the mouse to (x, y) without clicking. Coordinates are pixels or percentages like 50% 50%.").action(wrap((x, y) => computerMoveCommand(x, y)));
   computer.command("type <text>").description("Type a literal string into the focused field. Use `key` for key combos like ctrl+l.").option("--delay <ms>", "Per-character delay in ms (default 12 \u2248 80 wpm)").action(wrap((text, options) => computerTypeCommand(text, options)));
   computer.command("key <combo>").description("Press a key combo, e.g. Return, Escape, ctrl+l, ctrl+shift+t. Same syntax as xdotool key.").action(wrap((combo) => computerKeyCommand(combo)));
-  computer.command("scroll <direction>").description("Scroll up | down | left | right. Optionally provide --x / --y to hover before scrolling.").option("--amount <n>", "Wheel ticks (default 3)").option("--x <x>", "Hover x before scrolling").option("--y <y>", "Hover y before scrolling").action(wrap((direction, options) => computerScrollCommand(direction, options)));
-  computer.command("drag <fromX> <fromY> <toX> <toY>").description("Press the left mouse button at (fromX, fromY), drag to (toX, toY), release.").action(wrap((fx, fy, tx, ty) => computerDragCommand(fx, fy, tx, ty)));
+  computer.command("scroll <direction>").description("Scroll up | down | left | right. Optionally provide --x / --y to hover before scrolling.").option("--amount <n>", "Wheel ticks (default 3)").option("--x <x>", "Hover x before scrolling. Pixels or percentage.").option("--y <y>", "Hover y before scrolling. Pixels or percentage.").action(wrap((direction, options) => computerScrollCommand(direction, options)));
+  computer.command("drag <fromX> <fromY> <toX> <toY>").description("Press the left mouse button at (fromX, fromY), drag to (toX, toY), release. Coordinates are pixels or percentages.").action(wrap((fx, fy, tx, ty) => computerDragCommand(fx, fy, tx, ty)));
   computer.command("launch <app> [args...]").description("Launch an app on the workspace display. Aliases: chrome, chromium, firefox, terminal.").action(wrap((app, args) => computerLaunchCommand(app, args)));
   const record = computer.command("record").description("Screen-record the workspace display to an MP4 (60fps libx264).");
   record.command("start <path>").description("Start recording to <path>. Output is fragmented MP4 (safe if the workspace dies mid-record).").option("--fps <n>", "Frame rate (default 60)").action(wrap((path6, options) => computerRecordStartCommand(path6, options)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replicas-cli",
-  "version": "0.2.321",
+  "version": "0.2.322",
   "description": "CLI for managing Replicas workspaces - SSH into cloud dev environments with automatic port forwarding",
   "main": "dist/index.mjs",
   "bin": {