haltija 1.3.0-beta.9 → 1.3.1

package/README.md

@@ -61,18 +61,44 @@ Full API: `hj docs` — or `hj api` for complete reference
 
 ---
 
-## Why Not Playwright / Puppeteer?
+## Haltija vs. Playwright
 
-| | Haltija | Playwright MCP |
-|---|---------|----------------|
-| **Browser** | Your real browser | Separate headless instance |
-| **State** | Already logged in, cookies, extensions | Clean slate every time |
-| **Setup** | `bunx haltija` | Install Playwright, configure MCP |
-| **Protocol** | Simple REST/curl | Complex CDP |
-| **Feedback** | "Button hidden by modal" | `TimeoutError: element not found` |
-| **Visibility** | Watch it happen live | Background process |
+Playwright is a mature, cross-browser automation framework with deep tooling (trace viewer, codegen, test runner, fixtures) and an official MCP that hands agents a structured accessibility snapshot. Reach for it when you want cross-browser coverage or a full test framework. Haltija aims at something narrower: letting an agent drive **a browser you're already running**, over plain HTTP — or spawn its own when you'd rather it did.
 
-Haltija connects to the browser you're already using. The one with the bug, the active session, and the weird cookie state. No reproduction script required.
+| | Haltija | Playwright (+ MCP) |
+|---|---|---|
+| Browser | Attach to your real, already-open browser — *or* spawn its own | Usually its own managed context; can connect to an existing browser over CDP |
+| Cross-browser | ⚠️ Chromium only | ✅ Chromium, Firefox, WebKit |
+| Session / auth | Uses your live logged-in session as-is | Fresh context by default; reusable via `storageState` / persistent context |
+| How an agent drives it | Plain HTTP/REST — curl, any language, no client library | Playwright client library, or the MCP tools |
+| Page model | DOM tree with stable ref IDs + `eval` | Accessibility-tree snapshot with ref IDs (MCP), or the full API in code |
+| Interaction | Per-character, framework-triggering synthetic events you can steer live over HTTP | Trusted CDP-level input |
+| Feedback when a step can't proceed | **Fails fast** — reports what's blocking it (missing / hidden / covered) right away | **Auto-waits to a timeout** (tens of seconds) — smooths over races, but a genuinely broken step burns the full timeout before failing |
+| Test generation | record→replay → JSON tests | codegen → Playwright code |
+| Debugging | Live widget, console capture, semantic events, click diff | Trace viewer — time-travel step snapshots |
+| Embed in your app | ✅ Ship the widget inside your own product | Not designed for that |
+
+**The short version:** they're complementary, and this project uses both — Playwright for cross-browser smoke checks, Haltija for the fast end-to-end pass. Reach for Haltija when you want to point an agent at the browser (and logged-in session) you already have, or embed agent-control into your own app — over nothing more than HTTP.
+
+---
+
+## Haltija vs. Claude in Chrome
+
+Both let an agent drive a browser — they're built for different jobs. Because Haltija can either **spawn its own isolated browser** *or* **attach to your real one** (via a script tag / bookmarklet on a port you choose), it covers the axes a live-session-only tool can't.
+
+| Axis | Haltija | Claude in Chrome |
+|---|---|---|
+| Setup / auth | ✅ `bunx haltija` — zero auth, self-spawns | ⚠️ Extension + claude.ai login + per-site permissions |
+| How the agent invokes it | ✅ Plain `hj` CLI / REST — always available in a shell | ⚠️ MCP tools; must be loaded + extension connected |
+| Project integration | ✅ *Is* your test harness — JSON tests (`hj test-suite`), record→replay, CI | ❌ None |
+| Determinism / cost | ✅ DOM + `eval` with stable ref IDs — cheap text, scriptable, headless-CI-able | ⚠️ Has structured reads (page text, find-by-text) *and* vision/coordinate actions; the vision path is token-heavy and coordinate clicks less deterministic |
+| Isolation | ✅ Own instance on its own port — never touches your browsing | ❌ Drives tabs in your live session |
+| Real-browser fidelity (WebGL/3D, pixels) | ✅ Attach to a real GPU Chrome or the desktop app *(headless GPU is the one weak spot)* | ✅ Full real Chrome GPU |
+| Authenticated / external sites | ✅ Inject into your logged-in browser on a chosen port *(one-time setup step)* | ✅ Native — already your logged-in profile |
+| Flakiness / contention | ✅ A private port per project = dedicated instance *(a shared instance can still flake under contention)* | ⚠️ Depends on live browser + extension state |
+| Screenshots | ✅ Native (desktop) or WebRTC `getDisplayMedia` (browser) | ✅ Vision-native |
+
+**The short version:** reach for Claude in Chrome to glance at the tab you're already looking at; reach for Haltija when you want a browser your agent *controls* — reproducibly, cheaply, in CI, and as the regression harness your project already has.
 
 ---
 
@@ -246,18 +272,25 @@ The server rejects every REST/WebSocket request without a matching `X-Haltija-To
 ## Installation
 
 ```bash
-bunx haltija               # Desktop app (recommended)
-bunx haltija --server      # Server only (your browser, CI, remote)
+bunx haltija               # Bundled browser + embedded server (easiest start)
+bunx haltija --server      # Server only — your browser, per-project dev/debug
 npm install -g haltija     # Install globally
 
 # Server options
 haltija --https            # HTTPS mode
 haltija --port 3000        # Custom port
+haltija --name <proj>      # Register a per-project instance (hj --name <proj>)
 haltija --token <secret>   # Require X-Haltija-Token on every request
-haltija --headless         # For CI pipelines
+haltija --headless         # For CI pipelines (no desktop app needed)
 haltija --setup-mcp        # Configure Claude Desktop
 ```
 
+**Which mode?** For day-to-day dev/debugging, run a per-project server
+(`haltija --server --name <proj>`) and drive it with the `hj` CLI or your coding
+agent — that's the paved path. For CI, `haltija --headless` runs a deterministic
+headless Chromium with no desktop app required. A downloadable notarized desktop
+app also exists but isn't required for either.
+
 ---
 
 ## Security

package/apps/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haltija-desktop",
-  "version": "1.3.0-beta.9",
+  "version": "1.3.1",
   "private": true,
   "description": "Haltija Desktop - God Mode Browser for AI Agents",
   "homepage": "https://github.com/tonioloewald/haltija",

package/apps/desktop/resources/component.js

@@ -46,7 +46,7 @@
   });
 
   // src/version.ts
-  var VERSION = "1.3.0-beta.9";
+  var VERSION = "1.3.1";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;
@@ -98,6 +98,47 @@
     return lower.includes(parsed.searchText);
   }
 
+  // src/key-codes.ts
+  function keyToCode(key) {
+    const specialKeys = {
+      Enter: "Enter",
+      Escape: "Escape",
+      Tab: "Tab",
+      Backspace: "Backspace",
+      Delete: "Delete",
+      ArrowUp: "ArrowUp",
+      ArrowDown: "ArrowDown",
+      ArrowLeft: "ArrowLeft",
+      ArrowRight: "ArrowRight",
+      Home: "Home",
+      End: "End",
+      PageUp: "PageUp",
+      PageDown: "PageDown",
+      " ": "Space",
+      Space: "Space",
+      ".": "Period",
+      ",": "Comma",
+      "/": "Slash",
+      ";": "Semicolon",
+      "'": "Quote",
+      "[": "BracketLeft",
+      "]": "BracketRight",
+      "\\": "Backslash",
+      "-": "Minus",
+      "=": "Equal",
+      "`": "Backquote"
+    };
+    if (specialKeys[key])
+      return specialKeys[key];
+    if (/^F\d{1,2}$/.test(key))
+      return key;
+    if (/^[a-zA-Z]$/.test(key))
+      return `Key${key.toUpperCase()}`;
+    if (/^[0-9]$/.test(key))
+      return `Digit${key}`;
+    return key;
+  }
+
   // src/component.ts
   var VERSION2 = VERSION;
   var PRODUCT_NAME = "Haltija";
@@ -1435,7 +1476,7 @@
       if (htmlEl.disabled) {
         flags.disabled = true;
       }
-      if (htmlEl.readOnly) {
+      if ("readOnly" in htmlEl && htmlEl.readOnly) {
         flags.readOnly = true;
       }
       if (!htmlEl.validity.valid) {
@@ -1717,6 +1758,8 @@
     isElectron = false;
     browserId = uid();
     killed = false;
+    displayStream = null;
+    displayVideo = null;
     isActive = true;
     homeLeft = 0;
     homeBottom = 16;
@@ -1918,6 +1961,7 @@
       this.restoreDialogs();
       this.clearEventWatchers();
       this.stopMutationWatch();
+      this.stopScreenCapture();
     }
     attributeChangedCallback(name, _old, value) {
       if (name === "server") {
@@ -2085,6 +2129,10 @@
           color: white;
           animation: pulse 1s infinite;
         }
+        .btn[data-action="screen"].sharing {
+          background: #3b82f6;
+          color: white;
+        }
         .btn[data-action="logs"] {
           font-size: 10px;
           font-weight: 500;
@@ -2485,6 +2533,7 @@
           <div class="controls">
             <button class="btn" data-action="select" title="Click or drag to select elements" aria-label="Select elements">\uD83D\uDC46</button>
             <button class="btn" data-action="record" title="Record test (click to start/stop)" aria-label="Record test">REC</button>
+            <button class="btn" data-action="screen" title="Share screen so the agent can take screenshots (browser only; not needed in Haltija desktop app)" aria-label="Share screen for screenshots">\uD83D\uDDA5</button>
             <button class="btn" data-action="logs" title="Show event log panel" aria-label="Toggle event log">LOG</button>
             <button class="btn info-btn" data-action="stats" title="Copy stats to clipboard" aria-label="Copy stats">i</button>
             <button class="btn" data-action="minimize" title="Minimize widget (⌥Tab)" aria-label="Minimize">─</button>
@@ -2566,6 +2615,8 @@
             this.toggleRecording();
           if (action2 === "select")
             this.startSelection();
+          if (action2 === "screen")
+            this.toggleScreenCapture();
           if (action2 === "stats")
             this.copyStatsToClipboard();
           if (action2 === "close-modal")
@@ -3016,7 +3067,7 @@
             if (options.addAssertions && inputValue) {
               steps.push({
                 action: "assert",
-                assertion: { type: "value", selector, expected: inputValue },
+                assertion: { type: "value", selector, value: inputValue },
                 description: `Verify ${inputLabel} is "${inputValue}"`
               });
             }
@@ -3845,6 +3896,55 @@ ${elementSummary}${moreText}`;
         this.hide();
       }
     }
+    async toggleScreenCapture() {
+      if (this.displayStream) {
+        this.stopScreenCapture();
+        return;
+      }
+      if (typeof navigator === "undefined" || !navigator.mediaDevices?.getDisplayMedia) {
+        console.warn(`${LOG_PREFIX} Screen capture not supported in this browser.`);
+        return;
+      }
+      try {
+        const stream = await navigator.mediaDevices.getDisplayMedia({
+          video: { frameRate: { ideal: 5 } },
+          audio: false
+        });
+        this.displayStream = stream;
+        const video = document.createElement("video");
+        video.srcObject = stream;
+        video.muted = true;
+        video.playsInline = true;
+        await video.play().catch(() => {});
+        this.displayVideo = video;
+        stream.getVideoTracks()[0]?.addEventListener("ended", () => {
+          this.stopScreenCapture();
+        });
+        const btn = this.shadowRoot?.querySelector('.btn[data-action="screen"]');
+        btn?.classList.add("sharing");
+      } catch (err) {
+        console.log(`${LOG_PREFIX} Screen capture not started: ${err.message}`);
+      }
+    }
+    stopScreenCapture() {
+      if (this.displayStream) {
+        for (const track of this.displayStream.getTracks()) {
+          try {
+            track.stop();
+          } catch {}
+        }
+        this.displayStream = null;
+      }
+      if (this.displayVideo) {
+        try {
+          this.displayVideo.pause();
+        } catch {}
+        this.displayVideo.srcObject = null;
+        this.displayVideo = null;
+      }
+      const btn = this.shadowRoot?.querySelector('.btn[data-action="screen"]');
+      btn?.classList.remove("sharing");
+    }
     toggleMinimize() {
       if (this.headless)
         return;
@@ -5336,7 +5436,8 @@ ${elementSummary}${moreText}`;
           scroll: 0,
           mutation: 0,
           console: 0,
-          focus: 0
+          focus: 0,
+          recording: 0
         };
         this.statsStartTime = Date.now();
         this.startSemanticEvents();
@@ -5781,7 +5882,37 @@ ${elementSummary}${moreText}`;
               return;
             }
           }
-          this.respond(msg2.id, false, null, "Screenshots require the Haltija Desktop app. Run: npx haltija@latest -f");
+          if (this.displayVideo && this.displayStream) {
+            try {
+              const video = this.displayVideo;
+              const w = video.videoWidth;
+              const h = video.videoHeight;
+              if (!w || !h) {
+                this.respond(msg2.id, false, null, "Screen capture stream has no frame data yet — try again in a moment.");
+                return;
+              }
+              const canvas = document.createElement("canvas");
+              canvas.width = w;
+              canvas.height = h;
+              const ctx = canvas.getContext("2d");
+              ctx.drawImage(video, 0, 0, w, h);
+              const dataUrl = canvas.toDataURL("image/png");
+              const converted = await convertFormat(dataUrl);
+              this.respond(msg2.id, true, {
+                image: converted.image,
+                viewport,
+                format,
+                width: converted.width,
+                height: converted.height,
+                source: "getDisplayMedia"
+              });
+              return;
+            } catch (err) {
+              this.respond(msg2.id, false, null, `Screen capture frame failed: ${err.message}`);
+              return;
+            }
+          }
+          this.respond(msg2.id, false, null, "No screenshot capture available. Either run the Haltija Desktop app (npx haltija@latest -f) or click the \uD83D\uDDA5 button in the Haltija widget to share your screen.");
         } catch (err) {
           this.respond(msg2.id, false, null, err.message);
         }
@@ -6193,31 +6324,6 @@ ${elementSummary}${moreText}`;
         el.value = value;
       }
     }
-    getKeyCode(char) {
-      const upper = char.toUpperCase();
-      if (upper >= "A" && upper <= "Z")
-        return `Key${upper}`;
-      if (char >= "0" && char <= "9")
-        return `Digit${char}`;
-      const specialKeys = {
-        " ": "Space",
-        ".": "Period",
-        ",": "Comma",
-        "/": "Slash",
-        ";": "Semicolon",
-        "'": "Quote",
-        "[": "BracketLeft",
-        "]": "BracketRight",
-        "\\": "Backslash",
-        "-": "Minus",
-        "=": "Equal",
-        "`": "Backquote",
-        Enter: "Enter",
-        Tab: "Tab",
-        Backspace: "Backspace"
-      };
-      return specialKeys[char] || `Key${upper}`;
-    }
     getAdjacentKeys() {
       return {
         a: ["s", "q", "w", "z"],
@@ -6464,32 +6570,7 @@ ${elementSummary}${moreText}`;
       }
     }
     getKeyCode(key) {
-      const specialKeys = {
-        Enter: "Enter",
-        Escape: "Escape",
-        Tab: "Tab",
-        Backspace: "Backspace",
-        Delete: "Delete",
-        ArrowUp: "ArrowUp",
-        ArrowDown: "ArrowDown",
-        ArrowLeft: "ArrowLeft",
-        ArrowRight: "ArrowRight",
-        Home: "Home",
-        End: "End",
-        PageUp: "PageUp",
-        PageDown: "PageDown",
-        " ": "Space",
-        Space: "Space"
-      };
-      if (specialKeys[key])
-        return specialKeys[key];
-      if (/^F\d{1,2}$/.test(key))
-        return key;
-      if (/^[a-zA-Z]$/.test(key))
-        return `Key${key.toUpperCase()}`;
-      if (/^[0-9]$/.test(key))
-        return `Digit${key}`;
-      return key;
+      return keyToCode(key);
     }
     getElementLabel(el) {
       const text = el.textContent?.trim().slice(0, 30);

package/bin/cli-subcommand.mjs

@@ -97,6 +97,7 @@ export const ARG_MAPS = {
   highlight: (args) => ({ ...parseTargetArgs(args.slice(0, 1)), label: args[1] }),
   unhighlight: () => ({}),
   find: (args) => ({ text: args.join(' ') }),
+  form: (args) => parseFormArgs(args),
   wait: (args) => parseWaitArgs(args),
   call: (args) => ({ ...parseTargetArgs(args.slice(0, 1)), method: args[1], args: args.slice(2).map(tryParseJSON) }),
   fetch: (args) => ({ url: args[0], prompt: args.slice(1).join(' ') || undefined }),
@@ -106,6 +107,14 @@ export const ARG_MAPS = {
     for (let i = 0; i < args.length; i++) {
       const a = args[i]
       if (a === '--data-url') { body.file = false; continue }
+      if (a === '--format') { body.format = args[++i]; continue }
+      if (a === '--quality') {
+        // Accept both 0–1 (canvas-native) and 0–100 (documented) — normalize
+        // anything > 1 down to the 0–1 the widget's toDataURL expects.
+        const q = num(args[++i])
+        if (q != null && !Number.isNaN(q)) body.quality = q > 1 ? q / 100 : q
+        continue
+      }
       if (a === '--scale') { body.scale = num(args[++i]); continue }
       if (a === '--maxWidth' || a === '--max-width') { body.maxWidth = num(args[++i]); continue }
       if (a === '--maxHeight' || a === '--max-height') { body.maxHeight = num(args[++i]); continue }
@@ -135,7 +144,6 @@ export const ARG_MAPS = {
   'events-watch': (args) => ({ preset: args[0] || 'interactive' }),
   'mutations-watch': (args) => ({ preset: args[0] || 'smart' }),
   'network-watch': (args) => ({ preset: args[0] || 'standard' }),
-  form: (args) => parseTargetArgs(args),
   // send <agent> <message> or send selection/recording
   // --no-submit flag prevents auto-submit (paste only)
   'test-run': (args) => {
@@ -270,6 +278,20 @@ export function parseClickArgs(args) {
   return Object.keys(body).length ? body : {}
 }
 
+/** Parse form args: optional form selector + --include-disabled/--include-hidden */
+export function parseFormArgs(args) {
+  const body = {}
+  const positional = []
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '--include-disabled') { body.includeDisabled = true; continue }
+    if (a === '--include-hidden') { body.includeHidden = true; continue }
+    if (!a.startsWith('-')) { positional.push(a); continue }
+  }
+  if (positional.length) body.selector = positional[0]
+  return Object.keys(body).length ? body : undefined
+}
+
 /** Parse inspect args: selector/ref + CSS flags */
 export function parseInspectArgs(args) {
   const body = {}
@@ -621,10 +643,107 @@ async function ensureBrowserConnected(port) {
 // Commands that don't need a browser window to be connected
 const INFO_COMMANDS = new Set(['status', 'windows', 'version', 'help'])
 
+// Commands whose payload lives in DevResponse.data and should be printed
+// unwrapped: strings verbatim, objects/arrays as pretty JSON, no envelope.
+// Trailing command hint is suppressed for these so agents can pipe stdout
+// directly. Pass --json to get the full DevResponse envelope instead.
+const UNWRAP_DATA_SUBCOMMANDS = new Set([
+  'eval',        // JS expression result (any type)
+  'call',        // method-call result on an element
+  'fetch',       // fetched URL response (body + headers + status)
+  'location',    // current URL + title
+  'query',       // matched element info (single or array)
+  'inspect',     // single-element details
+  'inspectAll',  // array of element details
+  'find',        // elements located by text
+  'console',     // console buffer entries
+  'form',        // form field values
+])
+
 // ============================================
 // Main subcommand execution
 // ============================================
 
+// Flags each flag-oriented subcommand recognizes. Used to (a) accept
+// `--flag=value` as well as `--flag value`, and (b) warn — not fail — when an
+// agent passes a flag the command will otherwise silently ignore. Commands that
+// take free-form text (type, eval, find, snapshot, send…) are intentionally
+// ABSENT: a leading-dash token there is content, not a flag, so we leave them
+// untouched.
+const GLOBAL_FLAGS = ['--json', '--window', '--port', '--name', '--token', '--no-launch', '--help']
+export const KNOWN_FLAGS = {
+  tree: ['--depth', '-d', '--selector', '-s', '--compact', '-c', '--interactive', '-i', '--visible', '-v', '--text', '--no-text', '--shadow', '--frames', '--no-frames'],
+  click: ['--diff', '--delay'],
+  form: ['--include-disabled', '--include-hidden'],
+  inspect: ['--full-styles', '--styles', '--matched-rules', '--rules', '--ancestors'],
+  inspectAll: ['--full-styles', '--styles', '--matched-rules', '--rules', '--ancestors'],
+  key: ['--ctrl', '-c', '--shift', '-s', '--alt', '-a', '--meta', '-m'],
+  screenshot: ['--data-url', '--format', '--quality', '--scale', '--maxWidth', '--max-width', '--maxHeight', '--max-height', '--delay', '--no-chyron'],
+  'video-start': ['--maxDuration', '--max-duration'],
+  refresh: ['--soft'],
+  'test-run': ['--vars', '--seed', '--timeoutMs', '--allow-failures', '--allow-failures-streak', '--step-delay'],
+  'test-validate': ['--vars', '--seed', '--timeoutMs', '--allow-failures', '--allow-failures-streak', '--step-delay'],
+  'test-suite': ['--vars', '--seed', '--timeoutMs', '--allow-failures', '--allow-failures-streak', '--step-delay'],
+}
+
+/** Split `--flag=value` into `--flag`, `value` (first `=` only). Long flags only. */
+export function normalizeEqualsFlags(args) {
+  const out = []
+  for (const a of args) {
+    if (a.startsWith('--') && a.includes('=')) {
+      const eq = a.indexOf('=')
+      out.push(a.slice(0, eq), a.slice(eq + 1))
+    } else {
+      out.push(a)
+    }
+  }
+  return out
+}
+
+/** Levenshtein distance, for "did you mean" suggestions. */
+function editDistance(a, b) {
+  const m = a.length, n = b.length
+  const d = Array.from({ length: m + 1 }, (_, i) => [i, ...Array(n).fill(0)])
+  for (let j = 0; j <= n; j++) d[0][j] = j
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost)
+    }
+  }
+  return d[m][n]
+}
+
+/** Closest known flag within a small edit distance, or null. */
+function closestFlag(input, candidates) {
+  let best = null, bestD = Infinity
+  for (const c of candidates) {
+    const dist = editDistance(input, c)
+    if (dist < bestD) { bestD = dist; best = c }
+  }
+  return bestD <= 3 ? best : null
+}
+
+/**
+ * Warn (to stderr, non-fatal) about dashed tokens a flag-oriented command
+ * doesn't recognize, so a typo like `--frmat` or an unsupported flag stops
+ * silently doing nothing. No-op for free-text commands (not in KNOWN_FLAGS).
+ */
+export function warnUnknownFlags(subcommand, args) {
+  const known = KNOWN_FLAGS[subcommand]
+  if (!known) return
+  const allowed = new Set([...known, ...GLOBAL_FLAGS])
+  const dim = (s) => `\x1b[2m${s}\x1b[0m`
+  for (const a of args) {
+    if (!a.startsWith('-')) continue      // positional or a flag's value
+    if (/^-\d/.test(a)) continue          // negative number, not a flag
+    if (allowed.has(a)) continue
+    const suggestion = closestFlag(a, known)
+    const hint = suggestion ? ` (did you mean ${suggestion}?)` : ''
+    process.stderr.write(dim(`[hj] warning: unknown flag "${a}" ignored${hint}`) + '\n')
+  }
+}
+
 export async function runSubcommand(subcommand, subArgs, port = '8700', options = {}) {
   const baseUrl = `http://localhost:${port}`
   const jsonOutput = subArgs.includes('--json')
@@ -638,6 +757,13 @@ export async function runSubcommand(subcommand, subArgs, port = '8700', options
     filteredArgs = [...filteredArgs.slice(0, windowIdx), ...filteredArgs.slice(windowIdx + 2)]
   }
 
+  // For flag-oriented commands, accept `--flag=value` and surface unknown flags
+  // instead of silently dropping them. Free-text commands are left untouched.
+  if (KNOWN_FLAGS[subcommand]) {
+    filteredArgs = normalizeEqualsFlags(filteredArgs)
+    warnUnknownFlags(subcommand, filteredArgs)
+  }
+
   // Check if server is running, auto-start if not
   if (!(await isServerRunning(port))) {
     // Respect "user manually quit Haltija" before we try to spawn anything.
@@ -765,6 +891,25 @@ async function doRequest(url, method, body, context = {}) {
         console.log(bold(json.data.path))
         const meta = [json.data.duration ? `${json.data.duration.toFixed(1)}s` : null, json.data.size ? `${(json.data.size / 1024).toFixed(0)}KB` : null, json.data.format].filter(Boolean).join(', ')
         if (meta) console.log(dim(meta))
+      } else if (!jsonOutput && UNWRAP_DATA_SUBCOMMANDS.has(subcommand)) {
+        // Print the inner DevResponse.data unwrapped so agents (and humans) can
+        // read it directly. Strings go to stdout as-is — no JSON escaping of
+        // newlines, quotes, etc. Objects/arrays still pretty-print as JSON.
+        // Failures go to stderr with a non-zero exit. Pass --json to get the
+        // full DevResponse envelope instead.
+        if (json.success === false) {
+          console.error(`${subcommand} failed: ${json.error || 'unknown error'}`)
+          process.exit(1)
+        }
+        const result = json.data
+        if (result === null || result === undefined) {
+          // nothing to print
+        } else if (typeof result === 'string') {
+          process.stdout.write(result)
+          if (!result.endsWith('\n')) process.stdout.write('\n')
+        } else {
+          console.log(JSON.stringify(result, null, 2))
+        }
       } else {
         console.log(JSON.stringify(json, null, 2))
       }
@@ -773,8 +918,10 @@ async function doRequest(url, method, body, context = {}) {
       console.log(text)
     }
 
-    // Show hint for this command (if available and successful)
-    if (resp.ok && !jsonOutput) {
+    // Show hint for this command (if available and successful).
+    // Skip for commands whose stdout is meant to be piped/consumed verbatim
+    // — agents shouldn't have to strip a trailing hint line.
+    if (resp.ok && !jsonOutput && !UNWRAP_DATA_SUBCOMMANDS.has(subcommand)) {
       const hint = COMMAND_HINTS[subcommand]
       if (hint) {
         const dim = (s) => `\x1b[2m${s}\x1b[0m`
@@ -798,7 +945,7 @@ async function doRequest(url, method, body, context = {}) {
 
 /** Known valid subcommands */
 export const KNOWN_COMMANDS = new Set([
-  'tree', 'query', 'inspect', 'inspectAll', 'styles', 'find',
+  'tree', 'query', 'inspect', 'inspectAll', 'styles', 'find', 'form',
   'click', 'type', 'key', 'drag', 'scroll', 'call',
   'navigate', 'refresh', 'location',
   'events', 'events-watch', 'events-unwatch', 'console',
@@ -812,7 +959,7 @@ export const KNOWN_COMMANDS = new Set([
   'recording', 'recording-start', 'recording-stop', 'recording-generate', 'recordings',
   'test-run', 'test-validate', 'test-suite',
   'send', 'send-message', 'send-selection', 'send-recording',
-  'status', 'version', 'docs', 'api', 'stats'
+  'status', 'version', 'docs', 'api', 'stats', 'where'
 ])
 
 /** Common typos/aliases mapped to correct commands */

package/bin/hints.json

@@ -12,7 +12,7 @@
   "events": "events-watch first | see: recording, console, mutations-watch",
   "eval": "\"code\" (returns result) | see: console, snapshot",
   "call": "@ref or \"selector\" <method>, --args [...]  | see: eval, inspect",
-  "screenshot": "[selector], --scale 0.5, --maxWidth 800 | see: highlight, snapshot",
+  "screenshot": "[selector], --format webp, --scale 0.5, --maxWidth 800 | see: highlight, snapshot",
   "windows": "--json | see: tabs-open, tabs-close, tabs-focus, status",
   "tabs-open": "[url] | see: tabs-focus, tabs-close, windows",
   "tabs-close": "<window-id> | see: windows, tabs-focus, tabs-open",