@kilospark/webact 2.5.1 → 2.6.0

package/SKILL.md

@@ -9,12 +9,12 @@ Control Chrome directly via the Chrome DevTools Protocol. No Playwright, no MCP
 
 ## How to Run Commands
 
-All commands use `webact.js` from this skill's base directory. The base directory is provided when the skill loads - use it as the path prefix.
+All commands use the `webact` CLI. First, check if `webact` is on PATH by running `which webact`. If found, use `webact` directly. If not, fall back to `node <base-dir>/webact.js` where `<base-dir>` is this skill's base directory.
 
 ### Session Setup (once)
 
 ```bash
-node <base-dir>/webact.js launch
+webact launch
 ```
 
 This launches Chrome (or connects to an existing instance) and creates a session. All subsequent commands auto-discover the session - no session ID needed.
@@ -24,11 +24,11 @@ This launches Chrome (or connects to an existing instance) and creates a session
 Use direct CLI commands. Each is a single bash call:
 
 ```bash
-node <base-dir>/webact.js navigate https://example.com
-node <base-dir>/webact.js click button.submit
-node <base-dir>/webact.js keyboard "hello world"
-node <base-dir>/webact.js press Enter
-node <base-dir>/webact.js dom
+webact navigate https://example.com
+webact click button.submit
+webact keyboard "hello world"
+webact press Enter
+webact dom
 ```
 
 **Auto-brief:** State-changing commands (navigate, click, hover, press Enter/Tab, scroll, select, waitfor) auto-print a compact page summary showing URL, title, inputs, buttons, links, and total element counts. You usually don't need a separate `dom` call. Use `dom` only when you need the full page structure, `axtree -i` for a quick list of all interactive elements, or `axtree` for the full semantic tree.
@@ -37,47 +37,48 @@ node <base-dir>/webact.js dom
 
 | Command | Example |
 |---------|---------|
-| `navigate <url>` | `node webact.js navigate https://example.com` |
-| `back` | `node webact.js back` |
-| `forward` | `node webact.js forward` |
-| `reload` | `node webact.js reload` |
-| `dom [selector] [--full]` | `node webact.js dom` or `node webact.js dom .results` |
-| `axtree [selector] [-i]` | `node webact.js axtree` or `node webact.js axtree -i` |
-| `observe` | `node webact.js observe` |
-| `screenshot` | `node webact.js screenshot` |
-| `pdf [path]` | `node webact.js pdf` or `node webact.js pdf /tmp/page.pdf` |
-| `click <selector>` | `node webact.js click button.submit` |
-| `doubleclick <selector>` | `node webact.js doubleclick td.cell` |
-| `rightclick <selector>` | `node webact.js rightclick .context-target` |
-| `hover <selector>` | `node webact.js hover .menu-trigger` |
-| `focus <selector>` | `node webact.js focus input[name=q]` |
-| `clear <selector>` | `node webact.js clear input[name=q]` |
-| `type <selector> <text>` | `node webact.js type input[name=q] search query` |
-| `keyboard <text>` | `node webact.js keyboard hello world` |
-| `select <selector> <value>` | `node webact.js select select#country US` |
-| `upload <selector> <file>` | `node webact.js upload input[type=file] /tmp/photo.png` |
-| `drag <from> <to>` | `node webact.js drag .card .dropzone` |
-| `dialog <accept\|dismiss> [text]` | `node webact.js dialog accept` |
-| `waitfor <selector> [ms]` | `node webact.js waitfor .dropdown 5000` |
-| `waitfornav [ms]` | `node webact.js waitfornav` |
-| `press <key\|combo>` | `node webact.js press Enter` or `node webact.js press Ctrl+A` |
-| `scroll <target> [px]` | `node webact.js scroll down 500` or `node webact.js scroll top` |
-| `eval <js>` | `node webact.js eval document.title` |
-| `cookies [get\|set\|clear\|delete]` | `node webact.js cookies` or `node webact.js cookies set name val` |
-| `console [show\|errors\|listen]` | `node webact.js console` or `node webact.js console errors` |
-| `block <pattern>` | `node webact.js block images css` or `node webact.js block off` |
-| `viewport <w> <h>` | `node webact.js viewport mobile` or `node webact.js viewport 1024 768` |
-| `frames` | `node webact.js frames` |
-| `frame <id\|selector>` | `node webact.js frame main` or `node webact.js frame iframe#embed` |
-| `download [path\|list]` | `node webact.js download path /tmp/dl` or `node webact.js download list` |
-| `tabs` | `node webact.js tabs` |
-| `tab <id>` | `node webact.js tab ABC123` |
-| `newtab [url]` | `node webact.js newtab https://example.com` |
-| `close` | `node webact.js close` |
-| `activate` | `node webact.js activate` |
-| `minimize` | `node webact.js minimize` |
-
-**`type` vs `keyboard`:** Use `type` to focus a specific input and fill it. Use `keyboard` to type at the current caret position - essential for rich text editors (Slack, Google Docs, Notion) where `type`'s focus call resets the cursor.
+| `navigate <url>` | `webact navigate https://example.com` |
+| `back` | `webact back` |
+| `forward` | `webact forward` |
+| `reload` | `webact reload` |
+| `dom [selector] [--full]` | `webact dom` or `webact dom .results` |
+| `axtree [selector] [-i]` | `webact axtree` or `webact axtree -i` |
+| `observe` | `webact observe` |
+| `screenshot` | `webact screenshot` |
+| `pdf [path]` | `webact pdf` or `webact pdf /tmp/page.pdf` |
+| `click <selector>` | `webact click button.submit` |
+| `doubleclick <selector>` | `webact doubleclick td.cell` |
+| `rightclick <selector>` | `webact rightclick .context-target` |
+| `hover <selector>` | `webact hover .menu-trigger` |
+| `focus <selector>` | `webact focus input[name=q]` |
+| `clear <selector>` | `webact clear input[name=q]` |
+| `type <selector> <text>` | `webact type input[name=q] search query` |
+| `keyboard <text>` | `webact keyboard hello world` |
+| `paste <text>` | `webact paste Hello world` |
+| `select <selector> <value>` | `webact select select#country US` |
+| `upload <selector> <file>` | `webact upload input[type=file] /tmp/photo.png` |
+| `drag <from> <to>` | `webact drag .card .dropzone` |
+| `dialog <accept\|dismiss> [text]` | `webact dialog accept` |
+| `waitfor <selector> [ms]` | `webact waitfor .dropdown 5000` |
+| `waitfornav [ms]` | `webact waitfornav` |
+| `press <key\|combo>` | `webact press Enter` or `webact press Ctrl+A` |
+| `scroll <target> [px]` | `webact scroll down 500` or `webact scroll top` |
+| `eval <js>` | `webact eval document.title` |
+| `cookies [get\|set\|clear\|delete]` | `webact cookies` or `webact cookies set name val` |
+| `console [show\|errors\|listen]` | `webact console` or `webact console errors` |
+| `block <pattern>` | `webact block images css` or `webact block off` |
+| `viewport <w> <h>` | `webact viewport mobile` or `webact viewport 1024 768` |
+| `frames` | `webact frames` |
+| `frame <id\|selector>` | `webact frame main` or `webact frame iframe#embed` |
+| `download [path\|list]` | `webact download path /tmp/dl` or `webact download list` |
+| `tabs` | `webact tabs` |
+| `tab <id>` | `webact tab ABC123` |
+| `newtab [url]` | `webact newtab https://example.com` |
+| `close` | `webact close` |
+| `activate` | `webact activate` |
+| `minimize` | `webact minimize` |
+
+**`type` vs `keyboard` vs `paste`:** Use `type` to focus a specific input and fill it. Use `keyboard` to type at the current caret position - essential for rich text editors (Slack, Google Docs, Notion) where `type`'s focus call resets the cursor. Use `paste` to insert text via a ClipboardEvent - works with apps that intercept paste (Google Docs, Notion) and is faster than `keyboard` for large text.
 
 **`click` behavior:** Waits up to 5s for the element, scrolls it into view, then clicks. No manual waits needed for dynamic elements.
 
@@ -93,7 +94,9 @@ node <base-dir>/webact.js dom
 
 **`press` combos:** Supports modifier keys: `Ctrl+A` (select all), `Ctrl+C` (copy), `Meta+V` (paste on Mac), `Shift+Enter`, etc. Modifiers: Ctrl, Alt, Shift, Meta/Cmd.
 
-**`scroll` targets:** `up`/`down` (default 400px, or specify pixels), `top`/`bottom`, or a CSS selector to scroll an element into view.
+**Mac keyboard note:** On macOS, app shortcuts documented as `Ctrl+Alt+<key>` (e.g., Google Docs heading shortcuts `Ctrl+Alt+1` through `Ctrl+Alt+6`) must be sent as `Meta+Alt+<key>` through CDP. Mac's Ctrl key is not the Command key these apps expect. Example: `press Meta+Alt+2` for Heading 2 in Google Docs.
+
+**`scroll` targets:** `up`/`down` (default 400px, or specify pixels), `top`/`bottom`, or a CSS selector to scroll an element into view. **Element-scoped:** `scroll <selector> <up|down|top|bottom> [px]` scrolls within a container element instead of the page — essential for apps with custom scroll containers (Google Docs, Slack).
 
 **`block` patterns:** Block resource types (`images`, `css`, `fonts`, `media`, `scripts`) or URL substrings. Speeds up page loads. Use `block off` to disable.
 
@@ -119,7 +122,7 @@ When given a goal, follow this loop:
 
 1. **PLAN** - Break the goal into steps. Chain predictable sequences (click → type → press Enter) into a single command array.
 
-2. **ACT** - Write command JSON (or array), run `node <base-dir>/webact.js run <sessionId>`. Actions auto-print a page brief.
+2. **ACT** - Write command JSON (or array), run `webact run <sessionId>`. Actions auto-print a page brief.
 
 3. **DECIDE** - Read the brief. Expected state? Continue. Login wall / CAPTCHA? Tell user. Need more detail? Use `dom`. Goal complete? Report.
 
@@ -149,7 +152,7 @@ When given a goal, follow this loop:
 
 ```bash
 # Launch Chrome and get a session ID
-node <base-dir>/webact.js launch
+webact launch
 # Output: Session: a1b2c3d4
 #         Command file: /tmp/webact-command-a1b2c3d4.json  (path varies by OS)
 ```
@@ -180,30 +183,51 @@ Read the DOM output and identify elements by:
 
 If a CSS selector doesn't work, use `eval` to find elements by text content:
 ```bash
-node webact.js eval "[...document.querySelectorAll('a')].find(a => a.textContent.includes('Sign in'))?.getAttribute('href')"
+webact eval "[...document.querySelectorAll('a')].find(a => a.textContent.includes('Sign in'))?.getAttribute('href')"
 ```
 
 ## Common Patterns
 
-All examples assume you've already run `node webact.js launch`.
+All examples assume you've already run `webact launch`.
 
 **Navigate and read** (navigate auto-prints brief - no separate dom needed):
 ```bash
-node webact.js navigate https://news.ycombinator.com
+webact navigate https://news.ycombinator.com
 ```
 
 **Fill a form:**
 ```bash
-node webact.js click input[name=q]
-node webact.js type input[name=q] search query
-node webact.js press Enter
+webact click input[name=q]
+webact type input[name=q] search query
+webact press Enter
 ```
 
 **Rich text editors and @mentions:**
 ```bash
-node webact.js click .ql-editor
-node webact.js keyboard Hello @alice
-node webact.js waitfor [data-qa='tab_complete_ui_item'] 5000
-node webact.js click [data-qa='tab_complete_ui_item']
-node webact.js keyboard " check this out"
+webact click .ql-editor
+webact keyboard Hello @alice
+webact waitfor [data-qa='tab_complete_ui_item'] 5000
+webact click [data-qa='tab_complete_ui_item']
+webact keyboard " check this out"
 ```
+
+## Complex Web Apps
+
+Some apps have non-standard DOMs that require specific approaches.
+
+**Google Docs:**
+- Use `keyboard` (not `type`) — Google Docs has a custom editor, not standard inputs
+- Use `paste` for inserting blocks of text — faster and more reliable than `keyboard` for multi-line content
+- Heading shortcuts: `press Meta+Alt+1` through `press Meta+Alt+6` (NOT `Ctrl+Alt` — see Mac keyboard note above)
+- Scrolling: Use `scroll .kix-appview-editor down 500` — page-level scroll doesn't reach the document content
+
+**Slack:**
+- Message composition: Click the message input, then use `keyboard` to type
+- Message extraction: Use `eval` to query Slack's virtual DOM — standard CSS selectors are unreliable due to virtual scrolling
+- Example: `eval [...document.querySelectorAll('[data-qa="virtual-list-item"]')].map(el => el.textContent).join('\n')`
+
+**General rich editors (Notion, Quill, ProseMirror, etc.):**
+- Prefer `paste` over `keyboard` for multi-line text — many editors handle paste events specially
+- Use `keyboard` for short inline text and @mentions
+- Use `eval` when you need to extract content from editors with virtual rendering
+- If `paste` doesn't work for a specific app, fall back to `eval` with a custom ClipboardEvent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kilospark/webact",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "CLI for browser automation via Chrome DevTools Protocol",
   "main": "webact.js",
   "bin": {

package/webact.js

@@ -4624,6 +4624,38 @@ async function cmdKeyboard(text) {
     console.log(`OK keyboard "${text.substring(0, 50)}${text.length > 50 ? "..." : ""}"`);
   });
 }
+async function cmdPaste(text) {
+  if (!text) {
+    console.error("Usage: webact.js paste <text>");
+    process.exit(1);
+  }
+  await withCDP(async (cdp) => {
+    const result = await cdp.send("Runtime.evaluate", {
+      expression: `
+        (function() {
+          const el = document.activeElement;
+          if (!el) return { error: 'No active element to paste into' };
+          const dt = new DataTransfer();
+          dt.setData('text/plain', ${JSON.stringify(text)});
+          const evt = new ClipboardEvent('paste', {
+            clipboardData: dt,
+            bubbles: true,
+            cancelable: true,
+          });
+          el.dispatchEvent(evt);
+          return { ok: true };
+        })()
+      `,
+      returnByValue: true
+    });
+    const val = result.result.value;
+    if (val && val.error) {
+      console.error(val.error);
+      process.exit(1);
+    }
+    console.log(`OK pasted "${text.substring(0, 50)}${text.length > 50 ? "..." : ""}"`);
+  });
+}
 async function cmdWaitFor(selector, timeoutMs) {
   if (!selector) {
     console.error("Usage: webact.js waitfor <selector> [timeout_ms]");
@@ -4775,33 +4807,64 @@ async function cmdPress(key) {
     }
   });
 }
-async function cmdScroll(target, amount) {
-  if (!target) {
-    console.error("Usage: webact.js scroll <up|down|top|bottom|selector> [pixels]");
+async function cmdScroll(args) {
+  if (!args.length) {
+    console.error("Usage: webact.js scroll <up|down|top|bottom|selector> [pixels]\n       webact.js scroll <selector> <up|down|top|bottom> [pixels]");
     process.exit(1);
   }
-  const lower = target.toLowerCase();
+  const directions = ["up", "down", "top", "bottom"];
+  const first = args[0];
+  const lower = first.toLowerCase();
+  const secondIsDirection = args[1] && directions.includes(args[1].toLowerCase());
+  const firstIsDirection = directions.includes(lower);
   await withCDP(async (cdp) => {
-    if (lower === "top") {
-      await cdp.send("Runtime.evaluate", { expression: "window.scrollTo(0, 0)" });
-    } else if (lower === "bottom") {
-      await cdp.send("Runtime.evaluate", { expression: "window.scrollTo(0, document.body.scrollHeight)" });
-    } else if (lower === "up" || lower === "down") {
-      const pixels = parseInt(amount, 10) || 400;
-      const deltaY = lower === "up" ? -pixels : pixels;
-      await cdp.send("Input.dispatchMouseEvent", {
-        type: "mouseWheel",
-        x: 200,
-        y: 200,
-        deltaX: 0,
-        deltaY
+    if (firstIsDirection) {
+      if (lower === "top") {
+        await cdp.send("Runtime.evaluate", { expression: "window.scrollTo(0, 0)" });
+      } else if (lower === "bottom") {
+        await cdp.send("Runtime.evaluate", { expression: "window.scrollTo(0, document.body.scrollHeight)" });
+      } else {
+        const pixels = parseInt(args[1], 10) || 400;
+        const deltaY = lower === "up" ? -pixels : pixels;
+        await cdp.send("Input.dispatchMouseEvent", {
+          type: "mouseWheel",
+          x: 200,
+          y: 200,
+          deltaX: 0,
+          deltaY
+        });
+      }
+    } else if (secondIsDirection) {
+      const selector = first;
+      const dir = args[1].toLowerCase();
+      const pixels = parseInt(args[2], 10) || 400;
+      const result = await cdp.send("Runtime.evaluate", {
+        expression: `
+          (function() {
+            const el = document.querySelector(${JSON.stringify(selector)});
+            if (!el) return { error: 'Element not found' };
+            const dir = ${JSON.stringify(dir)};
+            const pixels = ${pixels};
+            if (dir === 'top') el.scrollTop = 0;
+            else if (dir === 'bottom') el.scrollTop = el.scrollHeight;
+            else el.scrollBy(0, dir === 'up' ? -pixels : pixels);
+            return { tag: el.tagName.toLowerCase(), dir };
+          })()
+        `,
+        returnByValue: true
       });
+      const val = result.result.value;
+      if (val && val.error) {
+        console.error(val.error);
+        process.exit(1);
+      }
+      console.log(`Scrolled ${val.dir} within ${val.tag} ${selector}`);
     } else {
       const result = await cdp.send("Runtime.evaluate", {
         expression: `
           (function() {
-            const el = document.querySelector(${JSON.stringify(target)});
-            if (!el) return { error: 'Element not found: ${target}' };
+            const el = document.querySelector(${JSON.stringify(first)});
+            if (!el) return { error: 'Element not found: ' + ${JSON.stringify(first)} };
             el.scrollIntoView({ block: 'center', behavior: 'smooth' });
             return { tag: el.tagName.toLowerCase() };
           })()
@@ -4809,11 +4872,11 @@ async function cmdScroll(target, amount) {
         returnByValue: true
       });
       const val = result.result.value;
-      if (val.error) {
+      if (val && val.error) {
         console.error(val.error);
         process.exit(1);
       }
-      console.log(`Scrolled to ${val.tag} ${target}`);
+      console.log(`Scrolled to ${val.tag} ${first}`);
     }
     await new Promise((r) => setTimeout(r, 100));
     console.log(await getPageBrief(cdp));
@@ -5694,6 +5757,9 @@ async function dispatch(command, args) {
     case "keyboard":
       await cmdKeyboard(args.join(" "));
       break;
+    case "paste":
+      await cmdPaste(args.join(" "));
+      break;
     case "select":
       await cmdSelect(resolveSelector(args[0]), ...args.slice(1));
       break;
@@ -5716,7 +5782,7 @@ async function dispatch(command, args) {
       await cmdPress(args[0]);
       break;
     case "scroll":
-      await cmdScroll(args[0], args[1]);
+      await cmdScroll(args);
       break;
     case "eval":
       await cmdEval(args.join(" "));
@@ -5817,6 +5883,7 @@ Commands:
   clear <selector>    Clear an input field or contenteditable
   type <sel> <text>   Type text into element (focuses selector first)
   keyboard <text>     Type text at current caret position (no selector)
+  paste <text>        Paste text via ClipboardEvent (for rich editors)
   select <sel> <val>  Select option(s) from a <select> by value or label
   upload <sel> <file> Upload file(s) to a file input
   drag <from> <to>    Drag from one element to another
@@ -5825,6 +5892,7 @@ Commands:
   waitfornav [ms]     Wait for page navigation to complete (default 10000ms)
   press <key>         Press a key or combo (Enter, Ctrl+A, Meta+C, etc.)
   scroll <target> [px] Scroll: up, down, top, bottom, or CSS selector [pixels]
+  scroll <sel> <dir> [px] Scroll within element: up, down, top, bottom [pixels]
   eval <js>           Evaluate JavaScript
   cookies [get|set|clear|delete]  Manage browser cookies
   console [show|errors|listen]    View console output or JS errors