haltija 1.3.1 → 1.3.3

package/apps/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haltija-desktop",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "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.1";
+  var VERSION = "1.3.3";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;
@@ -1761,6 +1761,7 @@
     displayStream = null;
     displayVideo = null;
     isActive = true;
+    visibilityHandler = null;
     homeLeft = 0;
     homeBottom = 16;
     headless = false;
@@ -1952,6 +1953,16 @@
       }
       this.interceptConsole();
       this.interceptDialogs();
+      if (typeof document !== "undefined") {
+        this.visibilityHandler = () => {
+          if (document.visibilityState === "hidden") {
+            this.deactivate();
+          } else {
+            this.activate();
+          }
+        };
+        document.addEventListener("visibilitychange", this.visibilityHandler);
+      }
       this.connect();
     }
     disconnectedCallback() {
@@ -1962,6 +1973,10 @@
       this.clearEventWatchers();
       this.stopMutationWatch();
       this.stopScreenCapture();
+      if (this.visibilityHandler && typeof document !== "undefined") {
+        document.removeEventListener("visibilitychange", this.visibilityHandler);
+        this.visibilityHandler = null;
+      }
     }
     attributeChangedCallback(name, _old, value) {
       if (name === "server") {
@@ -5100,6 +5115,7 @@ ${elementSummary}${moreText}`;
           this.state = "connected";
           this.show();
           const windowType = window.opener ? "popup" : window.parent !== window ? "iframe" : "tab";
+          this.isActive = typeof document === "undefined" || document.visibilityState !== "hidden";
           this.send("system", "connected", {
             windowId: this.windowId,
             browserId: this.browserId,

package/bin/cli-subcommand.mjs

@@ -584,7 +584,7 @@ async function launchElectronApp() {
   return false
 }
 
-async function ensureBrowserConnected(port) {
+async function ensureBrowserConnected(port, { explicitTarget = false } = {}) {
   let status
   try {
     const resp = await fetch(`http://localhost:${port}/status`, {
@@ -600,6 +600,19 @@ async function ensureBrowserConnected(port) {
   // produce two app instances side by side — skip the launch.
   if (status?.desktopApp) return true
 
+  // Private / project-owned server (explicitly targeted via --port / --name /
+  // HALTIJA_PORT). Launching the standalone Haltija.app here is wrong — it runs
+  // its own server on 8700 and would never connect to this port — so guide the
+  // user to attach a browser to *this* server instead of spawning Electron.
+  if (explicitTarget) {
+    process.stderr.write(
+      `\x1b[2mNo browser connected to the haltija server on port ${port}. ` +
+      `Open your app/page with the widget injected (script tag or bookmarklet), ` +
+      `or run \`hj --no-launch\` to skip this check.\x1b[0m\n`
+    )
+    return false
+  }
+
   // Respect "user explicitly quit" — don't auto-relaunch on every agent
   // call. Cleared when the user starts Haltija manually.
   try {
@@ -748,6 +761,7 @@ export async function runSubcommand(subcommand, subArgs, port = '8700', options
   const baseUrl = `http://localhost:${port}`
   const jsonOutput = subArgs.includes('--json')
   const noLaunch = options.noLaunch || false
+  const explicitTarget = options.explicitTarget || false
   // Remove --json and extract --window before processing
   let filteredArgs = subArgs.filter(a => a !== '--json')
   let targetWindowId = undefined
@@ -791,7 +805,7 @@ export async function runSubcommand(subcommand, subArgs, port = '8700', options
 
   // Auto-launch browser if no windows connected (skip for info commands and --no-launch)
   if (!noLaunch && !INFO_COMMANDS.has(subcommand)) {
-    await ensureBrowserConnected(port)
+    await ensureBrowserConnected(port, { explicitTarget })
   }
 
   // Special handling for 'send' command - route to appropriate endpoint

package/bin/hj.mjs

@@ -196,6 +196,15 @@ if (noLaunchIdx !== -1) {
   args.splice(noLaunchIdx, 1)
 }
 
+// Did the shell explicitly target a private instance (--port / --name /
+// HALTIJA_PORT / HALTIJA_NAME / DEV_CHANNEL_PORT)? If so, this is a
+// project-owned server with a bring-your-own browser — auto-launching the
+// standalone Haltija.app is never right (it runs its own server on 8700 and
+// can't connect to this port), so we suppress the Electron launch and print
+// an actionable hint instead. Only the bare, unconfigured 8700 default keeps
+// the zero-config desktop auto-launch.
+const explicitTarget = portSource !== '8700 (default)'
+
 // --- Space-to-hyphen sub-command resolution ---
 // "hj test run foo.json" → "hj test-run foo.json"
 // "hj events watch" → "hj events-watch"
@@ -247,7 +256,7 @@ if (!isSubcommand(subcommand)) {
 
   // Auto-execute if there's exactly one fuzzy match
   if (suggestion) {
-    runSubcommand(suggestion, subArgs, port, { noLaunch })
+    runSubcommand(suggestion, subArgs, port, { noLaunch, explicitTarget })
   } else {
     console.error(`Unknown command: '${subcommand}'`)
     console.error(`\nExamples: hj tree, hj navigate <url>, hj click @42`)
@@ -255,7 +264,7 @@ if (!isSubcommand(subcommand)) {
     process.exit(1)
   }
 } else {
-  runSubcommand(subcommand, subArgs, port, { noLaunch })
+  runSubcommand(subcommand, subArgs, port, { noLaunch, explicitTarget })
 }
 
 function filterHelp(topic) {

package/dist/api-schema.d.ts

@@ -63,6 +63,8 @@ export declare const tree: EndpointDef<{
     pierceFrames?: boolean | undefined;
     compact?: boolean | undefined;
     ancestors?: boolean | undefined;
+    includeBox?: boolean | undefined;
+    mode?: string | undefined;
     window?: string | undefined;
 }>;
 export declare const query: EndpointDef<{
@@ -354,6 +356,8 @@ export declare const endpoints: {
         pierceFrames?: boolean | undefined;
         compact?: boolean | undefined;
         ancestors?: boolean | undefined;
+        includeBox?: boolean | undefined;
+        mode?: string | undefined;
         window?: string | undefined;
     }>;
     readonly query: EndpointDef<{
@@ -645,6 +649,8 @@ export declare const ALL_ENDPOINTS: (EndpointDef<{
     pierceFrames?: boolean | undefined;
     compact?: boolean | undefined;
     ancestors?: boolean | undefined;
+    includeBox?: boolean | undefined;
+    mode?: string | undefined;
     window?: string | undefined;
 }> | EndpointDef<{
     selector?: string | undefined;

package/dist/component.d.ts

@@ -20,7 +20,7 @@
  * - Option+Tab toggles visibility (but active state always shows briefly)
  * - Localhost only by default
  */
-export declare const VERSION = "1.3.1";
+export declare const VERSION = "1.3.3";
 export declare class DevChannel extends HTMLElement {
     static get tagName(): string;
     static elementCreator(): () => DevChannel;
@@ -50,6 +50,7 @@ export declare class DevChannel extends HTMLElement {
     private displayStream;
     private displayVideo;
     private isActive;
+    private visibilityHandler;
     private homeLeft;
     private homeBottom;
     private headless;

package/dist/component.esm.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var VERSION = "1.3.1";
+var VERSION = "1.3.3";
 
 // src/text-selector.ts
 var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;
@@ -1714,6 +1714,7 @@ class DevChannel extends HTMLElement {
   displayStream = null;
   displayVideo = null;
   isActive = true;
+  visibilityHandler = null;
   homeLeft = 0;
   homeBottom = 16;
   headless = false;
@@ -1905,6 +1906,16 @@ class DevChannel extends HTMLElement {
     }
     this.interceptConsole();
     this.interceptDialogs();
+    if (typeof document !== "undefined") {
+      this.visibilityHandler = () => {
+        if (document.visibilityState === "hidden") {
+          this.deactivate();
+        } else {
+          this.activate();
+        }
+      };
+      document.addEventListener("visibilitychange", this.visibilityHandler);
+    }
     this.connect();
   }
   disconnectedCallback() {
@@ -1915,6 +1926,10 @@ class DevChannel extends HTMLElement {
     this.clearEventWatchers();
     this.stopMutationWatch();
     this.stopScreenCapture();
+    if (this.visibilityHandler && typeof document !== "undefined") {
+      document.removeEventListener("visibilitychange", this.visibilityHandler);
+      this.visibilityHandler = null;
+    }
   }
   attributeChangedCallback(name, _old, value) {
     if (name === "server") {
@@ -5053,6 +5068,7 @@ ${elementSummary}${moreText}`;
         this.state = "connected";
         this.show();
         const windowType = window.opener ? "popup" : window.parent !== window ? "iframe" : "tab";
+        this.isActive = typeof document === "undefined" || document.visibilityState !== "hidden";
         this.send("system", "connected", {
           windowId: this.windowId,
           browserId: this.browserId,

package/dist/component.js

@@ -46,7 +46,7 @@
   });
 
   // src/version.ts
-  var VERSION = "1.3.1";
+  var VERSION = "1.3.3";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;
@@ -1761,6 +1761,7 @@
     displayStream = null;
     displayVideo = null;
     isActive = true;
+    visibilityHandler = null;
     homeLeft = 0;
     homeBottom = 16;
     headless = false;
@@ -1952,6 +1953,16 @@
       }
       this.interceptConsole();
       this.interceptDialogs();
+      if (typeof document !== "undefined") {
+        this.visibilityHandler = () => {
+          if (document.visibilityState === "hidden") {
+            this.deactivate();
+          } else {
+            this.activate();
+          }
+        };
+        document.addEventListener("visibilitychange", this.visibilityHandler);
+      }
       this.connect();
     }
     disconnectedCallback() {
@@ -1962,6 +1973,10 @@
       this.clearEventWatchers();
       this.stopMutationWatch();
       this.stopScreenCapture();
+      if (this.visibilityHandler && typeof document !== "undefined") {
+        document.removeEventListener("visibilitychange", this.visibilityHandler);
+        this.visibilityHandler = null;
+      }
     }
     attributeChangedCallback(name, _old, value) {
       if (name === "server") {
@@ -5100,6 +5115,7 @@ ${elementSummary}${moreText}`;
           this.state = "connected";
           this.show();
           const windowType = window.opener ? "popup" : window.parent !== window ? "iframe" : "tab";
+          this.isActive = typeof document === "undefined" || document.visibilityState !== "hidden";
           this.send("system", "connected", {
             windowId: this.windowId,
             browserId: this.browserId,

package/dist/hj.js

@@ -1345,7 +1345,7 @@ async function launchElectronApp() {
   }
   return false;
 }
-async function ensureBrowserConnected(port) {
+async function ensureBrowserConnected(port, { explicitTarget = false } = {}) {
   let status;
   try {
     const resp = await fetch(`http://localhost:${port}/status`, {
@@ -1359,6 +1359,11 @@ async function ensureBrowserConnected(port) {
   }
   if (status?.desktopApp)
     return true;
+  if (explicitTarget) {
+    process.stderr.write(`\x1B[2mNo browser connected to the haltija server on port ${port}. Open your app/page with the widget injected (script tag or bookmarklet), or run \`hj --no-launch\` to skip this check.\x1B[0m
+`);
+    return false;
+  }
   try {
     const quitMarker = join(homedir(), ".haltija", "last-quit");
     if (existsSync(quitMarker)) {
@@ -1483,6 +1488,7 @@ async function runSubcommand(subcommand, subArgs, port = "8700", options = {}) {
   const baseUrl = `http://localhost:${port}`;
   const jsonOutput = subArgs.includes("--json");
   const noLaunch = options.noLaunch || false;
+  const explicitTarget = options.explicitTarget || false;
   let filteredArgs = subArgs.filter((a) => a !== "--json");
   let targetWindowId = undefined;
   const windowIdx = filteredArgs.indexOf("--window");
@@ -1516,7 +1522,7 @@ async function runSubcommand(subcommand, subArgs, port = "8700", options = {}) {
     }
   }
   if (!noLaunch && !INFO_COMMANDS.has(subcommand)) {
-    await ensureBrowserConnected(port);
+    await ensureBrowserConnected(port, { explicitTarget });
   }
   if (subcommand === "send") {
     const firstArg = filteredArgs[0]?.toLocaleLowerCase();
@@ -2018,6 +2024,7 @@ if (noLaunchIdx !== -1) {
   noLaunch = true;
   args.splice(noLaunchIdx, 1);
 }
+var explicitTarget = portSource !== "8700 (default)";
 if (args.length >= 2 && isSubcommand(`${args[0]}-${args[1]}`)) {
   args.splice(0, 2, `${args[0]}-${args[1]}`);
 }
@@ -2052,7 +2059,7 @@ if (!isSubcommand(subcommand)) {
     process.exit(0);
   }
   if (suggestion) {
-    runSubcommand(suggestion, subArgs, port, { noLaunch });
+    runSubcommand(suggestion, subArgs, port, { noLaunch, explicitTarget });
   } else {
     console.error(`Unknown command: '${subcommand}'`);
     console.error(`
@@ -2061,7 +2068,7 @@ Examples: hj tree, hj navigate <url>, hj click @42`);
     process.exit(1);
   }
 } else {
-  runSubcommand(subcommand, subArgs, port, { noLaunch });
+  runSubcommand(subcommand, subArgs, port, { noLaunch, explicitTarget });
 }
 function filterHelp(topic) {
   const bold2 = (s) => `\x1B[1m${s}\x1B[0m`;

package/dist/index.js

@@ -674,7 +674,7 @@ var injectorCode = `
 `;
 
 // src/version.ts
-var VERSION = "1.3.1";
+var VERSION = "1.3.3";
 
 // src/embedded-assets.ts
 var APP_MD = `# Haltija App
@@ -1086,6 +1086,8 @@ Use ancestors:true to see parent elements when inspecting deep elements.
 | \`pierceFrames\` | boolean,null | Pierce same-origin iframes (default true) |
 | \`compact\` | boolean,null | Minimal output (default false) |
 | \`ancestors\` | boolean,null | Include ancestor path from root (default false) |
+| \`includeBox\` | boolean,null | Include each node's bounding box { x, y, w, h, visible } (default false) |
+| \`mode\` | string,null | 'actionable' returns a page action summary (url, title, headings, buttons, links, inputs, selects) instead of the DOM tree |
 | \`window\` | string,null | Target window ID |
 
 **Examples:**
@@ -3019,7 +3021,7 @@ var COMPONENT_JS = `(() => {
   });
 
   // src/version.ts
-  var VERSION = "1.3.1";
+  var VERSION = "1.3.3";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\\(/;
@@ -4734,6 +4736,7 @@ var COMPONENT_JS = `(() => {
     displayStream = null;
     displayVideo = null;
     isActive = true;
+    visibilityHandler = null;
     homeLeft = 0;
     homeBottom = 16;
     headless = false;
@@ -4925,6 +4928,16 @@ var COMPONENT_JS = `(() => {
       }
       this.interceptConsole();
       this.interceptDialogs();
+      if (typeof document !== "undefined") {
+        this.visibilityHandler = () => {
+          if (document.visibilityState === "hidden") {
+            this.deactivate();
+          } else {
+            this.activate();
+          }
+        };
+        document.addEventListener("visibilitychange", this.visibilityHandler);
+      }
       this.connect();
     }
     disconnectedCallback() {
@@ -4935,6 +4948,10 @@ var COMPONENT_JS = `(() => {
       this.clearEventWatchers();
       this.stopMutationWatch();
       this.stopScreenCapture();
+      if (this.visibilityHandler && typeof document !== "undefined") {
+        document.removeEventListener("visibilitychange", this.visibilityHandler);
+        this.visibilityHandler = null;
+      }
     }
     attributeChangedCallback(name, _old, value) {
       if (name === "server") {
@@ -8073,6 +8090,7 @@ var COMPONENT_JS = `(() => {
           this.state = "connected";
           this.show();
           const windowType = window.opener ? "popup" : window.parent !== window ? "iframe" : "tab";
+          this.isActive = typeof document === "undefined" || document.visibilityState !== "hidden";
           this.send("system", "connected", {
             windowId: this.windowId,
             browserId: this.browserId,
@@ -11373,6 +11391,8 @@ Use ancestors:true to see parent elements when inspecting deep elements.`,
     pierceFrames: L.boolean.describe("Pierce same-origin iframes (default true)").optional,
     compact: L.boolean.describe("Minimal output (default false)").optional,
     ancestors: L.boolean.describe("Include ancestor path from root (default false)").optional,
+    includeBox: L.boolean.describe("Include each node's bounding box { x, y, w, h, visible } (default false)").optional,
+    mode: L.string.describe("'actionable' returns a page action summary (url, title, headings, buttons, links, inputs, selects) instead of the DOM tree").optional,
     window: L.string.describe("Target window ID").optional
   }),
   examples: [
@@ -14063,7 +14083,10 @@ registerHandler(tree, async (body, ctx) => {
     pierceShadow: body.pierceShadow,
     pierceFrames: body.pierceFrames,
     visibleOnly: body.visibleOnly,
-    ancestors: body.ancestors
+    interactiveOnly: body.interactiveOnly,
+    ancestors: body.ancestors,
+    includeBox: body.includeBox,
+    mode: body.mode
   }, 5000, windowId);
   return Response.json(response, { headers: ctx.headers });
 });
@@ -18525,7 +18548,8 @@ var serverConfig = {
                 label: existingWindow?.label,
                 windowType: windowType || "tab"
               });
-              if (!focusedWindowId || focusedWindowId === windowId) {
+              const isVisibleTab = (windowType || "tab") === "tab" && active !== false;
+              if (!focusedWindowId || focusedWindowId === windowId || isVisibleTab) {
                 focusedWindowId = windowId;
               }
               console.log(`${LOG_PREFIX} Window connected: ${windowId} (${url})`);
@@ -18569,6 +18593,9 @@ var serverConfig = {
             if (win) {
               win.active = active;
               win.lastSeen = Date.now();
+              if (active && win.windowType === "tab") {
+                focusedWindowId = windowId;
+              }
             }
           }
         } catch {}

package/dist/server.js

@@ -674,7 +674,7 @@ var injectorCode = `
 `;
 
 // src/version.ts
-var VERSION = "1.3.1";
+var VERSION = "1.3.3";
 
 // src/embedded-assets.ts
 var APP_MD = `# Haltija App
@@ -1086,6 +1086,8 @@ Use ancestors:true to see parent elements when inspecting deep elements.
 | \`pierceFrames\` | boolean,null | Pierce same-origin iframes (default true) |
 | \`compact\` | boolean,null | Minimal output (default false) |
 | \`ancestors\` | boolean,null | Include ancestor path from root (default false) |
+| \`includeBox\` | boolean,null | Include each node's bounding box { x, y, w, h, visible } (default false) |
+| \`mode\` | string,null | 'actionable' returns a page action summary (url, title, headings, buttons, links, inputs, selects) instead of the DOM tree |
 | \`window\` | string,null | Target window ID |
 
 **Examples:**
@@ -3019,7 +3021,7 @@ var COMPONENT_JS = `(() => {
   });
 
   // src/version.ts
-  var VERSION = "1.3.1";
+  var VERSION = "1.3.3";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\\(/;
@@ -4734,6 +4736,7 @@ var COMPONENT_JS = `(() => {
     displayStream = null;
     displayVideo = null;
     isActive = true;
+    visibilityHandler = null;
     homeLeft = 0;
     homeBottom = 16;
     headless = false;
@@ -4925,6 +4928,16 @@ var COMPONENT_JS = `(() => {
       }
       this.interceptConsole();
       this.interceptDialogs();
+      if (typeof document !== "undefined") {
+        this.visibilityHandler = () => {
+          if (document.visibilityState === "hidden") {
+            this.deactivate();
+          } else {
+            this.activate();
+          }
+        };
+        document.addEventListener("visibilitychange", this.visibilityHandler);
+      }
       this.connect();
     }
     disconnectedCallback() {
@@ -4935,6 +4948,10 @@ var COMPONENT_JS = `(() => {
       this.clearEventWatchers();
       this.stopMutationWatch();
       this.stopScreenCapture();
+      if (this.visibilityHandler && typeof document !== "undefined") {
+        document.removeEventListener("visibilitychange", this.visibilityHandler);
+        this.visibilityHandler = null;
+      }
     }
     attributeChangedCallback(name, _old, value) {
       if (name === "server") {
@@ -8073,6 +8090,7 @@ var COMPONENT_JS = `(() => {
           this.state = "connected";
           this.show();
           const windowType = window.opener ? "popup" : window.parent !== window ? "iframe" : "tab";
+          this.isActive = typeof document === "undefined" || document.visibilityState !== "hidden";
           this.send("system", "connected", {
             windowId: this.windowId,
             browserId: this.browserId,
@@ -11373,6 +11391,8 @@ Use ancestors:true to see parent elements when inspecting deep elements.`,
     pierceFrames: L.boolean.describe("Pierce same-origin iframes (default true)").optional,
     compact: L.boolean.describe("Minimal output (default false)").optional,
     ancestors: L.boolean.describe("Include ancestor path from root (default false)").optional,
+    includeBox: L.boolean.describe("Include each node's bounding box { x, y, w, h, visible } (default false)").optional,
+    mode: L.string.describe("'actionable' returns a page action summary (url, title, headings, buttons, links, inputs, selects) instead of the DOM tree").optional,
     window: L.string.describe("Target window ID").optional
   }),
   examples: [
@@ -14063,7 +14083,10 @@ registerHandler(tree, async (body, ctx) => {
     pierceShadow: body.pierceShadow,
     pierceFrames: body.pierceFrames,
     visibleOnly: body.visibleOnly,
-    ancestors: body.ancestors
+    interactiveOnly: body.interactiveOnly,
+    ancestors: body.ancestors,
+    includeBox: body.includeBox,
+    mode: body.mode
   }, 5000, windowId);
   return Response.json(response, { headers: ctx.headers });
 });
@@ -18525,7 +18548,8 @@ var serverConfig = {
                 label: existingWindow?.label,
                 windowType: windowType || "tab"
               });
-              if (!focusedWindowId || focusedWindowId === windowId) {
+              const isVisibleTab = (windowType || "tab") === "tab" && active !== false;
+              if (!focusedWindowId || focusedWindowId === windowId || isVisibleTab) {
                 focusedWindowId = windowId;
               }
               console.log(`${LOG_PREFIX} Window connected: ${windowId} (${url})`);
@@ -18569,6 +18593,9 @@ var serverConfig = {
             if (win) {
               win.active = active;
               win.lastSeen = Date.now();
+              if (active && win.windowType === "tab") {
+                focusedWindowId = windowId;
+              }
             }
           }
         } catch {}

package/dist/version.d.ts

@@ -8,4 +8,4 @@
  * ⚠️  AUTO-GENERATED FROM package.json - DO NOT EDIT THIS FILE
  * ⚠️  To change the version, update package.json and run: bun run build
  */
-export declare const VERSION = "1.3.1";
+export declare const VERSION = "1.3.3";

package/docs/README.md

@@ -34,7 +34,7 @@
 ## Planning
 
 - **[Executive Summary](EXECUTIVE-SUMMARY.md)** - What Haltija is, who it's for
-- **[Roadmap to 10/10](ROADMAP-TO-10.md)** - Where we're going
+- **[Roadmap](ROADMAP.md)** - Where we're going
 - **[Development Roadmap](../ROADMAP.md)** - Completed and planned phases
 - **[TODO](../TODO.md)** - Outstanding issues and ideas
 

package/docs/agent-prompt.md

@@ -81,7 +81,7 @@ To fill this form:
   hj tree -d 5           Deeper tree
   hj tree form           Subtree rooted at selector
   hj console             Recent console logs/errors
-  hj screenshot          Capture page as image
+  hj screenshot          Capture page as image (--format webp for smaller)
   hj location            Current URL and title
   hj events              Recent semantic events
 
@@ -113,6 +113,10 @@ To fill this form:
   hj windows              List connected tabs
   hj click 5 --window abc  Target specific tab
 
+### Server
+  hj status               Is the server up? which tab is focused?
+  hj where                Which server this shell targets (add --json)
+
 ## Tips
 
 - Start with `hj tree` — look for [interactive] to find actionable elements

package/docs/recipes.md

@@ -128,8 +128,8 @@ curl localhost:8700/events
 # Highlight what might be wrong
 curl -X POST localhost:8700/highlight -d '{"selector":".error-message","label":"This error"}'
 
-# Screenshot for the ticket
-curl -X POST localhost:8700/screenshot -d '{"maxWidth":1200}'
+# Screenshot for the ticket (webp keeps it small)
+curl -X POST localhost:8700/screenshot -d '{"maxWidth":1200,"format":"webp"}'
 ```
 
 **Or just tell the agent**: "Customer says Settings page is broken. Check it out."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haltija",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "description": "Browser control for AI agents - query DOM, click, type, run JS, watch mutations",
   "type": "module",
   "main": "dist/index.js",