browser-pilot-cli 0.1.4 → 0.1.6

package/README.md

@@ -96,8 +96,10 @@ The daemon maintains a single CDP WebSocket connection. A pulsing blue glow arou
 |---------|---------|-------------|
 | `bp open <url>` | snapshot | Navigate to URL |
 | `bp snapshot` | snapshot | Get interactive elements |
-| `bp click <ref>` | snapshot | Click element by ref number |
+| `bp click <ref>` | snapshot | Click element by ref number (`--double`, `--right`) |
+| `bp click 0 --xy x,y` | snapshot | Click at viewport coordinates (canvas, maps) |
 | `bp type <ref> <text>` | snapshot | Type into element (`--clear`, `--submit`) |
+| `bp keyboard <text>` | snapshot | Type via keyboard events (`--click`, `--clear`) |
 | `bp press <key>` | snapshot | Press key (Enter, Escape, Control+a, Meta+c) |
 | `bp eval [js]` | value | Run JavaScript (escape hatch for anything) |
 
@@ -211,6 +213,15 @@ bp upload ~/Downloads/photo.jpg    # auto-finds file input, triggers upload
 bp type 3 "new content" --clear     # replace content in a rich text editor
 ```
 
+For canvas-based editors (Google Docs, Google Sheets, Figma), use `bp keyboard` which sends real keyboard events:
+
+```bash
+bp keyboard "Hello Docs!" --click ".kix-appview-editor"   # Google Docs
+bp press Meta+b                                            # toggle bold
+bp keyboard "bold text"
+bp click 0 --xy 400,300                                    # click canvas area
+```
+
 Shadow DOM elements are traversed automatically — no special commands needed. Elements inside open shadow roots (even deeply nested) appear in snapshots and can be clicked/typed normally.
 
 For `<select>` dropdowns (shown as `combobox`), use `bp eval`:

package/dist/cli.js

@@ -4,6 +4,7 @@
 import { Command } from "commander";
 import { writeFileSync as writeFileSync3, readFileSync as readFileSync5, existsSync as existsSync6 } from "fs";
 import { resolve as resolvePath } from "path";
+import { createRequire } from "module";
 
 // src/session.ts
 import { spawn } from "child_process";
@@ -542,13 +543,16 @@ async function resolveTarget(transport, sessionId, target, targetId) {
 }
 
 // src/cli.ts
+var require2 = createRequire(import.meta.url);
+var PKG_VERSION = require2("../package.json").version;
 var program = new Command();
-program.name("bp").description("Control your browser from the command line").version("0.1.0").option("--human", "force human-readable output (default when TTY)").addHelpText("after", `
+program.name("bp").description("Control your browser from the command line").version(PKG_VERSION).option("--human", "force human-readable output (default when TTY)").addHelpText("after", `
 Workflow:
   bp connect                          # one-time setup (click Allow in Chrome)
   bp open <url>                       # navigate \u2014 returns snapshot with [ref] numbers
   bp click <ref>                      # interact \u2014 returns updated snapshot
-  bp click 0 --xy 400,300            # click at coordinates (canvas/maps)
+  bp click --xy 400,300              # click at coordinates (canvas/maps)
+  bp locate ".selector"              # get element coordinates for click --xy
   bp type <ref> <text>                # input text \u2014 returns updated snapshot
   bp keyboard <text>                  # type via keyboard events (Google Docs etc.)
   bp press <key>                      # press key \u2014 returns updated snapshot
@@ -659,7 +663,30 @@ var KEY_DEFS = {
   home: { key: "Home", code: "Home", keyCode: 36 },
   end: { key: "End", code: "End", keyCode: 35 },
   pageup: { key: "PageUp", code: "PageUp", keyCode: 33 },
-  pagedown: { key: "PageDown", code: "PageDown", keyCode: 34 }
+  pagedown: { key: "PageDown", code: "PageDown", keyCode: 34 },
+  // Digits
+  "0": { key: "0", code: "Digit0", keyCode: 48 },
+  "1": { key: "1", code: "Digit1", keyCode: 49 },
+  "2": { key: "2", code: "Digit2", keyCode: 50 },
+  "3": { key: "3", code: "Digit3", keyCode: 51 },
+  "4": { key: "4", code: "Digit4", keyCode: 52 },
+  "5": { key: "5", code: "Digit5", keyCode: 53 },
+  "6": { key: "6", code: "Digit6", keyCode: 54 },
+  "7": { key: "7", code: "Digit7", keyCode: 55 },
+  "8": { key: "8", code: "Digit8", keyCode: 56 },
+  "9": { key: "9", code: "Digit9", keyCode: 57 },
+  // Punctuation
+  "-": { key: "-", code: "Minus", keyCode: 189 },
+  "=": { key: "=", code: "Equal", keyCode: 187 },
+  "[": { key: "[", code: "BracketLeft", keyCode: 219 },
+  "]": { key: "]", code: "BracketRight", keyCode: 221 },
+  "\\": { key: "\\", code: "Backslash", keyCode: 220 },
+  ";": { key: ";", code: "Semicolon", keyCode: 186 },
+  "'": { key: "'", code: "Quote", keyCode: 222 },
+  ",": { key: ",", code: "Comma", keyCode: 188 },
+  ".": { key: ".", code: "Period", keyCode: 190 },
+  "/": { key: "/", code: "Slash", keyCode: 191 },
+  "`": { key: "`", code: "Backquote", keyCode: 192 }
 };
 var MOD_DEFS = {
   control: { key: "Control", code: "ControlLeft", keyCode: 17, mask: 2 },
@@ -753,14 +780,15 @@ program.command("snapshot").description("Get interactive elements on the page").
     emitSnapshot(await takeSnapshot(transport, sessionId, state.activeTargetId, limit));
   });
 }));
-program.command("click <ref>").description("Click element by ref number and return page snapshot").option("--xy <coords>", "click at x,y coordinates instead of ref (e.g. --xy 400,300)").option("--double", "double-click").option("--right", "right-click (context menu)").option("-l, --limit <n>", "max elements in snapshot", "50").addHelpText("after", `
-Ref is a number from the snapshot output, or use --xy for coordinate clicks.
-
+program.command("click [ref]").description("Click element by ref number or at x,y coordinates").option("--xy <coords>", "click at x,y viewport coordinates (e.g. --xy 400,300)").option("--double", "double-click").option("--right", "right-click (context menu)").option("-l, --limit <n>", "max elements in snapshot", "50").addHelpText("after", `
 Examples:
-  bp click 3                       # click element [3]
-  bp click 0 --xy 400,300          # click at coordinates (ref ignored)
-  bp click 0 --xy 400,300 --double # double-click at coordinates
-  bp click 0 --xy 400,300 --right  # right-click at coordinates`).action(action(async (ref, opts) => {
+  bp click 3                  # click element [3] from snapshot
+  bp click --xy 400,300       # click at viewport coordinates
+  bp click --xy 400,300 --double   # double-click at coordinates
+  bp click --xy 400,300 --right    # right-click (context menu)
+  bp click 3 --right          # right-click element [3]`).action(action(async (ref, opts) => {
+  if (opts.double && opts.right) throw new Error("--double and --right are mutually exclusive");
+  if (!ref && !opts.xy) throw new Error("Provide a ref number or --xy coordinates");
   const limit = parseLimit(opts.limit);
   await withPilot(async ({ transport, sessionId, state }) => {
     if (opts.xy) {
@@ -805,6 +833,28 @@ Examples:
     emitSnapshot(await snap(transport, sessionId, state.activeTargetId, limit));
   });
 }));
+program.command("locate <selector>").description("Get element coordinates by CSS selector (for use with click --xy)").addHelpText("after", `
+Returns center coordinates and bounding box of an element.
+Use with click --xy for canvas apps, charts, or elements not in snapshot.
+
+Examples:
+  bp locate ".kix-appview-editor"    # Google Docs editor area
+  bp locate "canvas"                 # canvas element
+  bp locate "#map"                   # map container`).action(action(async (selector) => {
+  await withPilot(async ({ transport, sessionId }) => {
+    const { result } = await transport.send("Runtime.evaluate", {
+      expression: `JSON.stringify((function(){var el=document.querySelector(${JSON.stringify(selector)});if(!el)return null;el.scrollIntoView({block:'center',inline:'center'});var r=el.getBoundingClientRect();return{x:Math.round(r.x+r.width/2),y:Math.round(r.y+r.height/2),top:Math.round(r.top),left:Math.round(r.left),width:Math.round(r.width),height:Math.round(r.height)}})())`,
+      returnByValue: true
+    }, sessionId);
+    const coords = result.value ? JSON.parse(result.value) : null;
+    if (!coords) throw new Error(`Element not found: ${selector}`);
+    if (useJson()) {
+      console.log(JSON.stringify({ ok: true, ...coords }));
+    } else {
+      console.log(`center: ${coords.x},${coords.y}  size: ${coords.width}x${coords.height}  (top:${coords.top} left:${coords.left})`);
+    }
+  });
+}));
 program.command("type <ref> <text>").description("Type text into element and return page snapshot").option("-c, --clear", "clear field before typing").option("-s, --submit", "press Enter after typing").option("-l, --limit <n>", "max elements in snapshot", "50").addHelpText("after", '\nExamples:\n  bp type 2 "hello world"\n  bp type 5 "query" --submit\n  bp type 3 "new value" --clear').action(action(async (ref, text, opts) => {
   const limit = parseLimit(opts.limit);
   await withPilot(async ({ transport, sessionId, state }) => {
@@ -848,6 +898,13 @@ program.command("type <ref> <text>").description("Type text into element and ret
     emitSnapshot(await snap(transport, sessionId, state.activeTargetId, limit));
   });
 }));
+function charToCode(char) {
+  const kd = KEY_DEFS[char];
+  if (kd) return kd;
+  if (/^[a-zA-Z]$/.test(char)) return { key: char, code: `Key${char.toUpperCase()}`, keyCode: char.toUpperCase().charCodeAt(0) };
+  if (char === " ") return { key: " ", code: "Space", keyCode: 32 };
+  return { key: char, code: "", keyCode: char.charCodeAt(0) };
+}
 async function typeViaKeyboard(t, sid, text) {
   for (const char of text) {
     if (char === "\n") {
@@ -855,10 +912,9 @@ async function typeViaKeyboard(t, sid, text) {
     } else if (char === "	") {
       await dispatchKey(t, sid, "Tab");
     } else if (char.charCodeAt(0) >= 32 && char.charCodeAt(0) <= 126) {
-      const code = char === " " ? "Space" : `Key${char.toUpperCase()}`;
-      const keyCode = char.toUpperCase().charCodeAt(0);
-      await t.send("Input.dispatchKeyEvent", { type: "keyDown", key: char, code, windowsVirtualKeyCode: keyCode, text: char }, sid);
-      await t.send("Input.dispatchKeyEvent", { type: "keyUp", key: char, code, windowsVirtualKeyCode: keyCode }, sid);
+      const { key, code, keyCode } = charToCode(char);
+      await t.send("Input.dispatchKeyEvent", { type: "keyDown", key, code, windowsVirtualKeyCode: keyCode, text: char }, sid);
+      await t.send("Input.dispatchKeyEvent", { type: "keyUp", key, code, windowsVirtualKeyCode: keyCode }, sid);
     } else {
       await t.send("Input.insertText", { text: char }, sid);
     }
@@ -890,19 +946,22 @@ Examples:
       await new Promise((r) => setTimeout(r, 300));
     }
     if (opts.clear) {
-      await dispatchKey(transport, sessionId, "Meta+a");
+      const selectAllMod = process.platform === "darwin" ? "Meta" : "Control";
+      await dispatchKey(transport, sessionId, `${selectAllMod}+a`);
       await dispatchKey(transport, sessionId, "Delete");
     }
     if (opts.delay) {
       const delay = parseInt(opts.delay, 10);
+      if (isNaN(delay) || delay < 0) throw new Error("--delay must be a non-negative number");
       for (const char of text) {
         if (char === "\n") {
           await dispatchKey(transport, sessionId, "Enter");
+        } else if (char === "	") {
+          await dispatchKey(transport, sessionId, "Tab");
         } else if (char.charCodeAt(0) >= 32 && char.charCodeAt(0) <= 126) {
-          const code = char === " " ? "Space" : `Key${char.toUpperCase()}`;
-          const keyCode = char.toUpperCase().charCodeAt(0);
-          await transport.send("Input.dispatchKeyEvent", { type: "keyDown", key: char, code, windowsVirtualKeyCode: keyCode, text: char }, sessionId);
-          await transport.send("Input.dispatchKeyEvent", { type: "keyUp", key: char, code, windowsVirtualKeyCode: keyCode }, sessionId);
+          const { key, code, keyCode } = charToCode(char);
+          await transport.send("Input.dispatchKeyEvent", { type: "keyDown", key, code, windowsVirtualKeyCode: keyCode, text: char }, sessionId);
+          await transport.send("Input.dispatchKeyEvent", { type: "keyUp", key, code, windowsVirtualKeyCode: keyCode }, sessionId);
         } else {
           await transport.send("Input.insertText", { text: char }, sessionId);
         }
@@ -912,7 +971,12 @@ Examples:
       await typeViaKeyboard(transport, sessionId, text);
     }
     if (opts.submit) await dispatchKey(transport, sessionId, "Enter");
-    emitSnapshot(await snap(transport, sessionId, state.activeTargetId, limit));
+    const snapResult = await snap(transport, sessionId, state.activeTargetId, limit);
+    if (useJson()) {
+      console.log(JSON.stringify({ ok: true, typed: text, ...snapResult.data }));
+    } else {
+      console.log(snapResult.text);
+    }
   });
 }));
 program.command("press <key>").description("Press key combo (e.g. Enter, Escape, Control+a) and return snapshot").option("-l, --limit <n>", "max elements in snapshot", "50").addHelpText("after", "\nKeys: Enter, Escape, Tab, Space, Backspace, Delete,\n      ArrowUp, ArrowDown, ArrowLeft, ArrowRight,\n      Home, End, PageUp, PageDown\nModifiers: Control (Ctrl), Shift, Alt, Meta (Cmd)\n\nExamples:\n  bp press Enter\n  bp press Escape\n  bp press Control+a\n  bp press Meta+c").action(action(async (key, opts) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-pilot-cli",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "CLI tool to control your browser via Chrome DevTools Protocol",
   "type": "module",
   "bin": {