haltija 1.5.1 → 1.5.4

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 1.5.4
+
+The `hj tabs open` client-less-tab trap now explains itself ([#5](https://github.com/tonioloewald/haltija/issues/5)).
+
+Outside the desktop app, `hj tabs open <url>` has no tab API, so it falls back to `window.open()` —
+and that new tab has **no haltija widget** unless its page injects one. So the server never hears
+from it, it doesn't appear in `hj tabs`, and commands can't reach it (they go to the focused widget
+tab). It presents as "the tab opened fine but every command goes somewhere else" — indistinguishable
+from a routing bug.
+
+- The fallback response now carries a `reason`, promoted to a top-level `warning` that `hj` prints
+  on stderr — at the one moment the client-less tab is created.
+- The `/tabs/open` schema and `SKILL.md` now state plainly that only widget-injected tabs are
+  controllable and appear in `hj tabs`, so a non-responding tab is the first thing to check.
+
+## 1.5.3
+
+Discoverability fix for the two CI browser engines ([#6](https://github.com/tonioloewald/haltija/issues/6)).
+
+Both `--headless` and `--ci` said "for CI" with no hint that they drive **different** engines:
+`--headless` is Playwright Chromium (and needs the `playwright` package), while `--ci` / `--app` /
+`--private --app` drive Electron and need no Playwright. An agent picked `--headless`, hit
+"Playwright not installed", and wrongly concluded haltija's CI mode is just a Playwright wrapper.
+
+- `hj --help` now names the engine per mode and adds a "Choosing a CI engine" block; `--private` is
+  clarified as an *isolation* modifier that pairs with either engine (not "pair with `--headless`").
+- The "Playwright not installed" error points at the Electron path (`--ci` / `--private --app`) as
+  the no-Playwright alternative.
+- `llms.txt`, `docs/CI-INTEGRATION.md`, and `SKILL.md` get an honest "which engine?" framing:
+  it's Electron vs Playwright (neither is bundled), and the real reason to choose Playwright is
+  multi-engine coverage (Firefox/WebKit), not the words "for CI".
+
+## 1.5.2
+
+Two follow-ups from the 1.5.0 review, both about the multi-tab experience on a shared server.
+
+### Fixed
+
+- **`hj tabs focus <id>` no longer times out** ([#4](https://github.com/tonioloewald/haltija/issues/4)).
+  It was dispatching a `focus` command to the browser, routed to the *focused* tab rather than the
+  target, so nobody answered — and even routed correctly, a backgrounded tab can't raise itself.
+  Focus is now a **server-side** routing change: it validates the tab and points untargeted commands
+  at it, returning instantly (unknown tab → a clean error, never a timeout). It does not physically
+  raise the tab; to pin a single command use `--window <id>`. "Focus follows the visible tab" still
+  applies when you physically switch tabs — that's genuine intent that should win over a stale pin.
+
+### Changed
+
+- **The hidden-tab / focus-ambiguity warnings are de-duplicated within a short (15s) cooldown**, so
+  a burst of commands from one agent doesn't repeat the same block every time. A *changed* condition
+  (different tab, newly-hidden tab, a new origin on the server) always re-warns; the cooldown
+  re-arms rather than suppressing forever. Set `HALTIJA_NO_TAB_WARN=1` to silence them entirely.
+
 ## 1.5.1
 
 Low-risk follow-ups from the 1.5.0 pre-release review — the two new "instrument must not lie"

package/apps/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haltija-desktop",
-  "version": "1.5.1",
+  "version": "1.5.4",
   "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.5.1";
+  var VERSION = "1.5.4";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;
@@ -5637,7 +5637,11 @@ ${elementSummary}${moreText}`;
           });
         } else {
           window.open(payload2.url, "_blank");
-          this.respond(msg2.id, true, { opened: true, fallback: true });
+          this.respond(msg2.id, true, {
+            opened: true,
+            fallback: true,
+            reason: "Opened a plain browser tab via window.open() (this is not the Haltija desktop app). " + "That tab has NO Haltija widget unless its page injects one, so it will NOT appear in " + "`hj tabs` and hj commands cannot reach it — untargeted commands go to the focused " + "widget tab instead. To control the new tab: inject the widget on that page (e.g. " + "HALTIJA_DEV=1 / haltijaDev:true in that project), or use the Haltija desktop app, " + "which auto-injects into every tab."
+          });
         }
       } else if (action2 === "close") {
         if (haltija?.closeTab) {

package/bin/tosijs-dev.mjs

@@ -37,12 +37,12 @@ ${bold('haltija')} - Browser control for AI agents
 Usage:
   haltija [options]
 
-Modes:
+Modes: ${dim('(the browser ENGINE differs — see "Choosing a CI engine" below)')}
   ${dim('(default)')}       Launch desktop app if electron available, otherwise server
-  --app           Explicitly launch desktop app (Electron)
-  --server        Server only (for CI, headless, or bookmarklet usage)
-  --headless      Start with headless Chromium browser (for CI)
-  --ci            CI mode: Electron app + wait for ready + sandbox disabled
+  --app           Explicitly launch desktop app (Electron — Chromium)
+  --server        Server only; bring your own browser (inject the widget). For bookmarklets/CI-lite
+  --headless      Headless Chromium via ${bold('Playwright')} (needs the 'playwright' package) — for CI
+  --ci            CI mode: ${bold('Electron')} app + wait-ready + sandbox off. No Playwright. Recommended for CI
 
 Options:
   --http          HTTP only on port 8700 (default protocol)
@@ -62,7 +62,9 @@ Options:
   --private       Isolated automation instance: own server on an EPHEMERAL port (never
                   8700), own browser, torn down with the run. Never sees/adopts/navigates
                   the shared interactive browser. Reports its address on stdout
-                  (HALTIJA_PRIVATE_READY {json}) and to --port-file. Pair with --headless.
+                  (HALTIJA_PRIVATE_READY {json}) and to --port-file. This is an ISOLATION
+                  modifier, not an engine: pair with --app (Electron, no Playwright) or
+                  --headless (Playwright Chromium).
   --port-file <p> Write the (private) server's bound address as JSON to <p> when ready.
   --setup-mcp     Configure Claude Desktop MCP integration
   --setup-mcp-check  Check MCP configuration status
@@ -88,6 +90,7 @@ Environment Variables:
   HALTIJA_NO_RETIRE        Set to 1: do not stop pre-1.4.0 haltija servers
   HALTIJA_NO_INSTALL       Set to 1: do not install hj into ~/.local/bin
   HALTIJA_NO_SKEW_WARN     Set to 1: silence hj's version-skew warning
+  HALTIJA_NO_TAB_WARN      Set to 1: silence hidden-tab / focus-ambiguity result warnings
   HALTIJA_REGISTRY_DIR     Instance registry location (default: ~/.haltija/servers)
   DEV_CHANNEL_PORT         Legacy alias for HALTIJA_PORT
   DEV_CHANNEL_HTTPS_PORT   HTTPS port (default: 8701)
@@ -105,13 +108,23 @@ Subcommands:
 
   Use 'hj' as a short alias: hj tree, hj click @42, etc.
 
+Choosing a CI engine ${dim('(both need one external browser, but a DIFFERENT one):')}
+  ${bold('Electron')} (Chromium, same engine the desktop app uses) — no Playwright:
+    haltija --ci                   # recommended: Electron + wait-ready + sandbox off
+    haltija --private --app        # + isolation (own ephemeral port, adopts nothing)
+    ${dim('Electron is fetched via npx if not already installed.')}
+  ${bold('Playwright')} Chromium — needs the 'playwright' package:
+    npm i playwright && npx playwright install chromium
+    haltija --headless             # single-engine; or --private --headless for isolation
+    ${dim("Pick this for MULTI-ENGINE coverage (Firefox/WebKit) — not just because it says \"CI\".")}
+
 Examples:
   haltija                          # Desktop app (or server fallback)
   haltija --app                    # Desktop app explicitly
-  haltija --server                 # Server only
+  haltija --server                 # Server only (bring your own browser)
   haltija --server --https         # HTTPS server only
-  haltija --headless               # Headless browser for CI
-  haltija --ci                     # CI mode (headless + wait + sandbox disabled)
+  haltija --ci                     # CI: Electron (no Playwright) + wait + sandbox off
+  haltija --headless               # CI: Playwright Chromium (needs playwright)
   haltija --setup-mcp              # Configure Claude Desktop integration
 `)
   process.exit(0)
@@ -728,8 +741,12 @@ const startHeadlessBrowser = async (port) => {
     
   } catch (err) {
     if (err.code === 'ERR_MODULE_NOT_FOUND') {
-      console.error('[tosijs-dev] Playwright not installed. Run: npm install playwright')
-      console.error('[tosijs-dev] Then: npx playwright install chromium')
+      console.error('[tosijs-dev] --headless uses Playwright Chromium, which is not installed.')
+      console.error('[tosijs-dev]   To use Playwright: npm install playwright && npx playwright install chromium')
+      console.error('[tosijs-dev]   Or skip Playwright entirely and use the ELECTRON engine instead:')
+      console.error('[tosijs-dev]     haltija --ci                 (Electron, waits for ready, sandbox off)')
+      console.error('[tosijs-dev]     haltija --private --app      (Electron + isolated ephemeral instance)')
+      console.error('[tosijs-dev]   Reach for --headless (Playwright) when you need Firefox/WebKit coverage.')
     } else {
       console.error('[tosijs-dev] Failed to start headless browser:', err.message)
     }

package/bin/version.mjs

@@ -3,4 +3,4 @@
  * ⚠️  To change the version, update package.json and run: bun run build
  */
 
-export const HJ_VERSION = '1.5.1'
+export const HJ_VERSION = '1.5.4'

package/dist/api-handlers.d.ts

@@ -52,6 +52,18 @@ export interface HandlerContext {
     headers: Record<string, string>;
     url: URL;
     getWindowInfo: (windowId?: string) => WindowInfo | undefined;
+    /**
+     * Set the server-side focused window — the tab that receives untargeted commands. This is pure
+     * server state, NOT a browser roundtrip: it validates the tab exists and returns immediately, so
+     * it can never time out the way dispatching a command *to* the (possibly hidden) tab does (#4).
+     */
+    focusWindow: (windowId: string) => {
+        ok: boolean;
+        error?: string;
+        active?: boolean;
+        windowType?: string;
+        title?: string;
+    };
     startRecordingSession: (windowId: string, url: string, name?: string) => void;
     stopRecordingSession: (windowId: string) => RecordingSessionInfo | undefined;
     getRecordingSession: (windowId: string) => RecordingSessionInfo | 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.5.1";
+export declare const VERSION = "1.5.4";
 export declare class DevChannel extends HTMLElement {
     static get tagName(): string;
     static elementCreator(): () => DevChannel;

package/dist/component.esm.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var VERSION = "1.5.1";
+var VERSION = "1.5.4";
 
 // src/text-selector.ts
 var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;
@@ -5590,7 +5590,11 @@ ${elementSummary}${moreText}`;
         });
       } else {
         window.open(payload2.url, "_blank");
-        this.respond(msg2.id, true, { opened: true, fallback: true });
+        this.respond(msg2.id, true, {
+          opened: true,
+          fallback: true,
+          reason: "Opened a plain browser tab via window.open() (this is not the Haltija desktop app). " + "That tab has NO Haltija widget unless its page injects one, so it will NOT appear in " + "`hj tabs` and hj commands cannot reach it — untargeted commands go to the focused " + "widget tab instead. To control the new tab: inject the widget on that page (e.g. " + "HALTIJA_DEV=1 / haltijaDev:true in that project), or use the Haltija desktop app, " + "which auto-injects into every tab."
+        });
       }
     } else if (action2 === "close") {
       if (haltija?.closeTab) {

package/dist/component.js

@@ -46,7 +46,7 @@
   });
 
   // src/version.ts
-  var VERSION = "1.5.1";
+  var VERSION = "1.5.4";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;
@@ -5637,7 +5637,11 @@ ${elementSummary}${moreText}`;
           });
         } else {
           window.open(payload2.url, "_blank");
-          this.respond(msg2.id, true, { opened: true, fallback: true });
+          this.respond(msg2.id, true, {
+            opened: true,
+            fallback: true,
+            reason: "Opened a plain browser tab via window.open() (this is not the Haltija desktop app). " + "That tab has NO Haltija widget unless its page injects one, so it will NOT appear in " + "`hj tabs` and hj commands cannot reach it — untargeted commands go to the focused " + "widget tab instead. To control the new tab: inject the widget on that page (e.g. " + "HALTIJA_DEV=1 / haltijaDev:true in that project), or use the Haltija desktop app, " + "which auto-injects into every tab."
+          });
         }
       } else if (action2 === "close") {
         if (haltija?.closeTab) {

package/dist/hj.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-// haltija-cli:do-not-edit v1.5.1
+// haltija-cli:do-not-edit v1.5.4
 import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
@@ -756,7 +756,7 @@ function substituteGeneratedVars(text, seed) {
 }
 
 // bin/version.mjs
-var HJ_VERSION = "1.5.1";
+var HJ_VERSION = "1.5.4";
 
 // bin/semver.mjs
 function parseVersion(v) {

package/dist/index.js

@@ -674,7 +674,7 @@ var injectorCode = `
 `;
 
 // src/version.ts
-var VERSION = "1.5.1";
+var VERSION = "1.5.4";
 
 // src/embedded-assets.ts
 var APP_MD = `# Haltija App
@@ -2176,9 +2176,15 @@ Use window IDs in other endpoints (e.g., /click, /tree) to target specific tabs.
 
 **Open a new tab**
 
-Desktop app only. Opens a new tab with optional URL.
+Opens a new tab with optional URL. If url is omitted, opens a blank tab.
 
-If url is omitted, opens a blank tab. The new tab gets the widget auto-injected.
+**In the Haltija desktop app** the new tab gets the widget auto-injected, so it's immediately
+controllable. **Anywhere else** (widget injected into a normal browser via bookmarklet/dev-server)
+there is no tab API, so this falls back to \`window.open()\` \u2014 the new tab is a plain browser tab
+with NO widget unless its own page injects one. In that case the response has \`fallback: true\`
+plus a \`reason\`, and a top-level \`warning\`: the tab will NOT appear in \`hj tabs\` and hj commands
+cannot reach it (they go to the focused widget tab). To control it, inject the widget on that page
+(e.g. HALTIJA_DEV / haltijaDev) or use the desktop app.
 
 **Parameters:**
 
@@ -2224,11 +2230,15 @@ Get window IDs from /windows endpoint.
 
 ### \`POST /tabs/focus\`
 
-**Focus a tab**
+**Focus a tab (route untargeted commands to it)**
 
-Desktop app only. Brings the specified tab to front.
-
-Useful when working with multiple tabs to ensure the right one is visible.
+Make the given tab the target of untargeted commands. This is a server-side
+routing change, NOT a browser action: it does not physically raise the tab (a backgrounded browser
+tab cannot be raised remotely), and because it never dispatches to the tab it can't time out \u2014 even
+if the tab is hidden. After this, commands without a \`window\`/\`--window\` go to this tab until you
+focus another or physically switch tabs in the browser. To pin a single command instead, use
+\`--window <id>\`. If the tab is hidden the response includes a warning (a backgrounded tab's results
+can be stale). Returns \`{ success, focused, active, title }\`.
 
 **Parameters:**
 
@@ -2238,7 +2248,7 @@ Useful when working with multiple tabs to ensure the right one is visible.
 
 **Examples:**
 
-- **focus**: Bring tab to front
+- **focus**: Route untargeted commands to this tab
   \`\`\`json
   {"window":"window-abc123"}
   \`\`\`
@@ -2802,7 +2812,7 @@ hj --help              # All commands
 - \`hj windows\` - List connected windows
 - \`hj tabs-open [url]\` - Open a new tab
 - \`hj tabs-close [window]\` - Close a tab
-- \`hj tabs-focus [window]\` - Focus a tab
+- \`hj tabs-focus [window]\` - Focus a tab (route untargeted commands to it)
 
 ### Record & Replay
 
@@ -3020,8 +3030,17 @@ Two first-party ways to run (plus embedding, below):
   \`hj tree\` inside a project reaches that project's server with no flags. Falling
   back to the shared default port 8700 warns on stderr. Use \`hj where\` to see which
   port a shell targets and WHY; override with \`--port\` or \`--name\`.
-- **CI:** \`haltija --headless\` (or \`--ci\`) runs a headless Chromium with the widget
-  auto-injected \u2014 deterministic, no desktop app required. See the CI guide below.
+- **CI:** two engines, and the choice matters \u2014 both need one external browser, but
+  a *different* one:
+  - \`haltija --ci\` (or \`--private --app\` for an isolated instance) drives **Electron**
+    (Chromium \u2014 the same engine the Haltija desktop app uses). Electron is fetched via
+    \`npx\` if not already present; **no \`playwright\` needed.** This is the default CI path.
+  - \`haltija --headless\` drives **Playwright Chromium**, which requires the \`playwright\`
+    package (\`npm i playwright && npx playwright install chromium\`). Reach for it when you
+    want multi-engine coverage (Firefox/WebKit) or a lighter single-engine run \u2014 not just
+    because it says "for CI". \`--private\` is an *isolation* modifier (ephemeral port), and
+    pairs with either engine: \`--private --app\` (Electron) or \`--private --headless\`
+    (Playwright). See the CI guide below.
 
 ## Embed in your app
 
@@ -3097,7 +3116,7 @@ var COMPONENT_JS = `(() => {
   });
 
   // src/version.ts
-  var VERSION = "1.5.1";
+  var VERSION = "1.5.4";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\\(/;
@@ -8688,7 +8707,11 @@ var COMPONENT_JS = `(() => {
           });
         } else {
           window.open(payload2.url, "_blank");
-          this.respond(msg2.id, true, { opened: true, fallback: true });
+          this.respond(msg2.id, true, {
+            opened: true,
+            fallback: true,
+            reason: "Opened a plain browser tab via window.open() (this is not the Haltija desktop app). " + "That tab has NO Haltija widget unless its page injects one, so it will NOT appear in " + "\`hj tabs\` and hj commands cannot reach it \u2014 untargeted commands go to the focused " + "widget tab instead. To control the new tab: inject the widget on that page (e.g. " + "HALTIJA_DEV=1 / haltijaDev:true in that project), or use the Haltija desktop app, " + "which auto-injects into every tab."
+          });
         }
       } else if (action2 === "close") {
         if (haltija?.closeTab) {
@@ -12814,9 +12837,15 @@ var tabsOpen = endpoint({
   path: "/tabs/open",
   method: "POST",
   summary: "Open a new tab",
-  description: `Desktop app only. Opens a new tab with optional URL.
-
-If url is omitted, opens a blank tab. The new tab gets the widget auto-injected.`,
+  description: `Opens a new tab with optional URL. If url is omitted, opens a blank tab.
+
+**In the Haltija desktop app** the new tab gets the widget auto-injected, so it's immediately
+controllable. **Anywhere else** (widget injected into a normal browser via bookmarklet/dev-server)
+there is no tab API, so this falls back to \`window.open()\` \u2014 the new tab is a plain browser tab
+with NO widget unless its own page injects one. In that case the response has \`fallback: true\`
+plus a \`reason\`, and a top-level \`warning\`: the tab will NOT appear in \`hj tabs\` and hj commands
+cannot reach it (they go to the focused widget tab). To control it, inject the widget on that page
+(e.g. HALTIJA_DEV / haltijaDev) or use the desktop app.`,
   category: "windows",
   input: L.object({
     url: L.string.describe("URL to open").optional
@@ -12857,10 +12886,14 @@ Get window IDs from /windows endpoint.`,
 var tabsFocus = endpoint({
   path: "/tabs/focus",
   method: "POST",
-  summary: "Focus a tab",
-  description: `Desktop app only. Brings the specified tab to front.
-
-Useful when working with multiple tabs to ensure the right one is visible.`,
+  summary: "Focus a tab (route untargeted commands to it)",
+  description: `Make the given tab the target of untargeted commands. This is a server-side
+routing change, NOT a browser action: it does not physically raise the tab (a backgrounded browser
+tab cannot be raised remotely), and because it never dispatches to the tab it can't time out \u2014 even
+if the tab is hidden. After this, commands without a \`window\`/\`--window\` go to this tab until you
+focus another or physically switch tabs in the browser. To pin a single command instead, use
+\`--window <id>\`. If the tab is hidden the response includes a warning (a backgrounded tab's results
+can be stale). Returns \`{ success, focused, active, title }\`.`,
   category: "windows",
   input: L.object({
     window: L.string.describe("Window ID to focus")
@@ -12869,7 +12902,7 @@ Useful when working with multiple tabs to ensure the right one is visible.`,
     {
       name: "focus",
       input: { window: "window-abc123" },
-      description: "Bring tab to front"
+      description: "Route untargeted commands to this tab"
     }
   ],
   hints: "<window-id> | see: windows, tabs-close, tabs-open"
@@ -14239,6 +14272,9 @@ registerHandler(screenshot, async (body, ctx) => {
 });
 registerHandler(tabsOpen, async (body, ctx) => {
   const response = await ctx.requestFromBrowser("tabs", "open", { url: body.url });
+  if (response?.data?.fallback && response.data.reason && !response.warning) {
+    response.warning = response.data.reason;
+  }
   return Response.json(response, { headers: ctx.headers });
 });
 registerHandler(tabsClose, async (body, ctx) => {
@@ -14252,10 +14288,19 @@ registerHandler(tabsClose, async (body, ctx) => {
 registerHandler(tabsFocus, async (body, ctx) => {
   const windowId = body.window || ctx.targetWindowId;
   if (!windowId) {
-    return Response.json({ success: false, error: "window id is required" }, { status: 400, headers: ctx.headers });
+    return Response.json({ success: false, error: "window id is required (run `hj tabs` to list connected tabs)" }, { status: 400, headers: ctx.headers });
   }
-  const response = await ctx.requestFromBrowser("tabs", "focus", { windowId });
-  return Response.json(response, { headers: ctx.headers });
+  const r = ctx.focusWindow(windowId);
+  if (!r.ok) {
+    return Response.json({ success: false, error: r.error }, { status: 404, headers: ctx.headers });
+  }
+  const result = { success: true, focused: windowId, active: r.active !== false };
+  if (r.title)
+    result.title = r.title;
+  if (r.active === false) {
+    result.warning = "Untargeted commands now route to this tab, but it reports HIDDEN \u2014 browsers freeze " + "requestAnimationFrame and throttle timers in a backgrounded tab, so results can be stale " + '("not mounted yet", not "broken"). Bring it to the front in your browser to wake it.';
+  }
+  return Response.json(result, { headers: ctx.headers });
 });
 registerHandler(mutationsWatch, async (body, ctx) => {
   const response = await ctx.requestFromBrowser("mutations", "watch", {
@@ -15275,6 +15320,22 @@ function ambiguousFocusWarning(opts) {
 ${pins}${more}`;
 }
 
+// src/warning-dedupe.ts
+function shouldEmitWarning(warning, cache, now, cooldownMs) {
+  const last = cache.get(warning);
+  if (last !== undefined && now - last < cooldownMs) {
+    return false;
+  }
+  cache.set(warning, now);
+  if (cache.size > 64) {
+    for (const [key2, ts] of cache) {
+      if (now - ts >= cooldownMs)
+        cache.delete(key2);
+    }
+  }
+  return true;
+}
+
 // src/server.ts
 init_terminal();
 
@@ -16129,6 +16190,9 @@ function getComponentJs() {
 }
 var browsers = new Map;
 var windows2 = new Map;
+var recentTabWarnings = new Map;
+var TAB_WARN_COOLDOWN_MS = 15000;
+var TAB_WARN_DISABLED = process.env.HALTIJA_NO_TAB_WARN === "1";
 var agents = new Set;
 var focusedWindowId = null;
 var isDesktopApp = process.env.HALTIJA_DESKTOP === "1";
@@ -16443,6 +16507,8 @@ async function requestFromBrowser(channel, action, payload, timeoutMs = 5000, wi
   return new Promise((resolve) => {
     let sentTo = null;
     const attachWarning = (res) => {
+      if (TAB_WARN_DISABLED)
+        return res;
       const hidden = hiddenTabWarning(sentTo);
       const ambiguous = ambiguousFocusWarning({
         windows: Array.from(windows2.values()),
@@ -16452,7 +16518,12 @@ async function requestFromBrowser(channel, action, payload, timeoutMs = 5000, wi
       const warning = [hidden, ambiguous].filter(Boolean).join(`
 
 `);
-      return warning ? { ...res, warning } : res;
+      if (!warning)
+        return res;
+      if (!shouldEmitWarning(warning, recentTabWarnings, Date.now(), TAB_WARN_COOLDOWN_MS)) {
+        return res;
+      }
+      return { ...res, warning };
     };
     const timeout = setTimeout(() => {
       pendingResponses.delete(id);
@@ -16623,6 +16694,15 @@ var createHandlerContext = (req, url) => {
     headers,
     url,
     getWindowInfo,
+    focusWindow: (windowId) => {
+      const win = windows2.get(windowId);
+      if (!win) {
+        return { ok: false, error: `Tab ${windowId} not found (run \`hj tabs\` to list connected tabs)` };
+      }
+      focusedWindowId = windowId;
+      updateHjStatus();
+      return { ok: true, active: win.active, windowType: win.windowType, title: win.title };
+    },
     startRecordingSession,
     stopRecordingSession,
     getRecordingSession,
@@ -18300,12 +18380,10 @@ Type 'help <topic>' for details.`);
             break;
           }
           case "tabs-focus": {
-            const resp = await requestFromBrowser("tabs", "focus", { windowId: step.window }, stepTimeout);
-            if (!resp.success) {
+            if (!step.window || !windows2.has(step.window)) {
               stepPassed = false;
-              error = resp.error || "Failed to focus tab";
-            }
-            if (step.window && windows2.has(step.window)) {
+              error = `Tab ${step.window ?? "(none)"} not found`;
+            } else {
               focusedWindowId = step.window;
             }
             break;

package/dist/server.js

@@ -674,7 +674,7 @@ var injectorCode = `
 `;
 
 // src/version.ts
-var VERSION = "1.5.1";
+var VERSION = "1.5.4";
 
 // src/embedded-assets.ts
 var APP_MD = `# Haltija App
@@ -2176,9 +2176,15 @@ Use window IDs in other endpoints (e.g., /click, /tree) to target specific tabs.
 
 **Open a new tab**
 
-Desktop app only. Opens a new tab with optional URL.
+Opens a new tab with optional URL. If url is omitted, opens a blank tab.
 
-If url is omitted, opens a blank tab. The new tab gets the widget auto-injected.
+**In the Haltija desktop app** the new tab gets the widget auto-injected, so it's immediately
+controllable. **Anywhere else** (widget injected into a normal browser via bookmarklet/dev-server)
+there is no tab API, so this falls back to \`window.open()\` \u2014 the new tab is a plain browser tab
+with NO widget unless its own page injects one. In that case the response has \`fallback: true\`
+plus a \`reason\`, and a top-level \`warning\`: the tab will NOT appear in \`hj tabs\` and hj commands
+cannot reach it (they go to the focused widget tab). To control it, inject the widget on that page
+(e.g. HALTIJA_DEV / haltijaDev) or use the desktop app.
 
 **Parameters:**
 
@@ -2224,11 +2230,15 @@ Get window IDs from /windows endpoint.
 
 ### \`POST /tabs/focus\`
 
-**Focus a tab**
+**Focus a tab (route untargeted commands to it)**
 
-Desktop app only. Brings the specified tab to front.
-
-Useful when working with multiple tabs to ensure the right one is visible.
+Make the given tab the target of untargeted commands. This is a server-side
+routing change, NOT a browser action: it does not physically raise the tab (a backgrounded browser
+tab cannot be raised remotely), and because it never dispatches to the tab it can't time out \u2014 even
+if the tab is hidden. After this, commands without a \`window\`/\`--window\` go to this tab until you
+focus another or physically switch tabs in the browser. To pin a single command instead, use
+\`--window <id>\`. If the tab is hidden the response includes a warning (a backgrounded tab's results
+can be stale). Returns \`{ success, focused, active, title }\`.
 
 **Parameters:**
 
@@ -2238,7 +2248,7 @@ Useful when working with multiple tabs to ensure the right one is visible.
 
 **Examples:**
 
-- **focus**: Bring tab to front
+- **focus**: Route untargeted commands to this tab
   \`\`\`json
   {"window":"window-abc123"}
   \`\`\`
@@ -2802,7 +2812,7 @@ hj --help              # All commands
 - \`hj windows\` - List connected windows
 - \`hj tabs-open [url]\` - Open a new tab
 - \`hj tabs-close [window]\` - Close a tab
-- \`hj tabs-focus [window]\` - Focus a tab
+- \`hj tabs-focus [window]\` - Focus a tab (route untargeted commands to it)
 
 ### Record & Replay
 
@@ -3020,8 +3030,17 @@ Two first-party ways to run (plus embedding, below):
   \`hj tree\` inside a project reaches that project's server with no flags. Falling
   back to the shared default port 8700 warns on stderr. Use \`hj where\` to see which
   port a shell targets and WHY; override with \`--port\` or \`--name\`.
-- **CI:** \`haltija --headless\` (or \`--ci\`) runs a headless Chromium with the widget
-  auto-injected \u2014 deterministic, no desktop app required. See the CI guide below.
+- **CI:** two engines, and the choice matters \u2014 both need one external browser, but
+  a *different* one:
+  - \`haltija --ci\` (or \`--private --app\` for an isolated instance) drives **Electron**
+    (Chromium \u2014 the same engine the Haltija desktop app uses). Electron is fetched via
+    \`npx\` if not already present; **no \`playwright\` needed.** This is the default CI path.
+  - \`haltija --headless\` drives **Playwright Chromium**, which requires the \`playwright\`
+    package (\`npm i playwright && npx playwright install chromium\`). Reach for it when you
+    want multi-engine coverage (Firefox/WebKit) or a lighter single-engine run \u2014 not just
+    because it says "for CI". \`--private\` is an *isolation* modifier (ephemeral port), and
+    pairs with either engine: \`--private --app\` (Electron) or \`--private --headless\`
+    (Playwright). See the CI guide below.
 
 ## Embed in your app
 
@@ -3097,7 +3116,7 @@ var COMPONENT_JS = `(() => {
   });
 
   // src/version.ts
-  var VERSION = "1.5.1";
+  var VERSION = "1.5.4";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\\(/;
@@ -8688,7 +8707,11 @@ var COMPONENT_JS = `(() => {
           });
         } else {
           window.open(payload2.url, "_blank");
-          this.respond(msg2.id, true, { opened: true, fallback: true });
+          this.respond(msg2.id, true, {
+            opened: true,
+            fallback: true,
+            reason: "Opened a plain browser tab via window.open() (this is not the Haltija desktop app). " + "That tab has NO Haltija widget unless its page injects one, so it will NOT appear in " + "\`hj tabs\` and hj commands cannot reach it \u2014 untargeted commands go to the focused " + "widget tab instead. To control the new tab: inject the widget on that page (e.g. " + "HALTIJA_DEV=1 / haltijaDev:true in that project), or use the Haltija desktop app, " + "which auto-injects into every tab."
+          });
         }
       } else if (action2 === "close") {
         if (haltija?.closeTab) {
@@ -12814,9 +12837,15 @@ var tabsOpen = endpoint({
   path: "/tabs/open",
   method: "POST",
   summary: "Open a new tab",
-  description: `Desktop app only. Opens a new tab with optional URL.
-
-If url is omitted, opens a blank tab. The new tab gets the widget auto-injected.`,
+  description: `Opens a new tab with optional URL. If url is omitted, opens a blank tab.
+
+**In the Haltija desktop app** the new tab gets the widget auto-injected, so it's immediately
+controllable. **Anywhere else** (widget injected into a normal browser via bookmarklet/dev-server)
+there is no tab API, so this falls back to \`window.open()\` \u2014 the new tab is a plain browser tab
+with NO widget unless its own page injects one. In that case the response has \`fallback: true\`
+plus a \`reason\`, and a top-level \`warning\`: the tab will NOT appear in \`hj tabs\` and hj commands
+cannot reach it (they go to the focused widget tab). To control it, inject the widget on that page
+(e.g. HALTIJA_DEV / haltijaDev) or use the desktop app.`,
   category: "windows",
   input: L.object({
     url: L.string.describe("URL to open").optional
@@ -12857,10 +12886,14 @@ Get window IDs from /windows endpoint.`,
 var tabsFocus = endpoint({
   path: "/tabs/focus",
   method: "POST",
-  summary: "Focus a tab",
-  description: `Desktop app only. Brings the specified tab to front.
-
-Useful when working with multiple tabs to ensure the right one is visible.`,
+  summary: "Focus a tab (route untargeted commands to it)",
+  description: `Make the given tab the target of untargeted commands. This is a server-side
+routing change, NOT a browser action: it does not physically raise the tab (a backgrounded browser
+tab cannot be raised remotely), and because it never dispatches to the tab it can't time out \u2014 even
+if the tab is hidden. After this, commands without a \`window\`/\`--window\` go to this tab until you
+focus another or physically switch tabs in the browser. To pin a single command instead, use
+\`--window <id>\`. If the tab is hidden the response includes a warning (a backgrounded tab's results
+can be stale). Returns \`{ success, focused, active, title }\`.`,
   category: "windows",
   input: L.object({
     window: L.string.describe("Window ID to focus")
@@ -12869,7 +12902,7 @@ Useful when working with multiple tabs to ensure the right one is visible.`,
     {
       name: "focus",
       input: { window: "window-abc123" },
-      description: "Bring tab to front"
+      description: "Route untargeted commands to this tab"
     }
   ],
   hints: "<window-id> | see: windows, tabs-close, tabs-open"
@@ -14239,6 +14272,9 @@ registerHandler(screenshot, async (body, ctx) => {
 });
 registerHandler(tabsOpen, async (body, ctx) => {
   const response = await ctx.requestFromBrowser("tabs", "open", { url: body.url });
+  if (response?.data?.fallback && response.data.reason && !response.warning) {
+    response.warning = response.data.reason;
+  }
   return Response.json(response, { headers: ctx.headers });
 });
 registerHandler(tabsClose, async (body, ctx) => {
@@ -14252,10 +14288,19 @@ registerHandler(tabsClose, async (body, ctx) => {
 registerHandler(tabsFocus, async (body, ctx) => {
   const windowId = body.window || ctx.targetWindowId;
   if (!windowId) {
-    return Response.json({ success: false, error: "window id is required" }, { status: 400, headers: ctx.headers });
+    return Response.json({ success: false, error: "window id is required (run `hj tabs` to list connected tabs)" }, { status: 400, headers: ctx.headers });
   }
-  const response = await ctx.requestFromBrowser("tabs", "focus", { windowId });
-  return Response.json(response, { headers: ctx.headers });
+  const r = ctx.focusWindow(windowId);
+  if (!r.ok) {
+    return Response.json({ success: false, error: r.error }, { status: 404, headers: ctx.headers });
+  }
+  const result = { success: true, focused: windowId, active: r.active !== false };
+  if (r.title)
+    result.title = r.title;
+  if (r.active === false) {
+    result.warning = "Untargeted commands now route to this tab, but it reports HIDDEN \u2014 browsers freeze " + "requestAnimationFrame and throttle timers in a backgrounded tab, so results can be stale " + '("not mounted yet", not "broken"). Bring it to the front in your browser to wake it.';
+  }
+  return Response.json(result, { headers: ctx.headers });
 });
 registerHandler(mutationsWatch, async (body, ctx) => {
   const response = await ctx.requestFromBrowser("mutations", "watch", {
@@ -15275,6 +15320,22 @@ function ambiguousFocusWarning(opts) {
 ${pins}${more}`;
 }
 
+// src/warning-dedupe.ts
+function shouldEmitWarning(warning, cache, now, cooldownMs) {
+  const last = cache.get(warning);
+  if (last !== undefined && now - last < cooldownMs) {
+    return false;
+  }
+  cache.set(warning, now);
+  if (cache.size > 64) {
+    for (const [key2, ts] of cache) {
+      if (now - ts >= cooldownMs)
+        cache.delete(key2);
+    }
+  }
+  return true;
+}
+
 // src/server.ts
 init_terminal();
 
@@ -16129,6 +16190,9 @@ function getComponentJs() {
 }
 var browsers = new Map;
 var windows2 = new Map;
+var recentTabWarnings = new Map;
+var TAB_WARN_COOLDOWN_MS = 15000;
+var TAB_WARN_DISABLED = process.env.HALTIJA_NO_TAB_WARN === "1";
 var agents = new Set;
 var focusedWindowId = null;
 var isDesktopApp = process.env.HALTIJA_DESKTOP === "1";
@@ -16443,6 +16507,8 @@ async function requestFromBrowser(channel, action, payload, timeoutMs = 5000, wi
   return new Promise((resolve) => {
     let sentTo = null;
     const attachWarning = (res) => {
+      if (TAB_WARN_DISABLED)
+        return res;
       const hidden = hiddenTabWarning(sentTo);
       const ambiguous = ambiguousFocusWarning({
         windows: Array.from(windows2.values()),
@@ -16452,7 +16518,12 @@ async function requestFromBrowser(channel, action, payload, timeoutMs = 5000, wi
       const warning = [hidden, ambiguous].filter(Boolean).join(`
 
 `);
-      return warning ? { ...res, warning } : res;
+      if (!warning)
+        return res;
+      if (!shouldEmitWarning(warning, recentTabWarnings, Date.now(), TAB_WARN_COOLDOWN_MS)) {
+        return res;
+      }
+      return { ...res, warning };
     };
     const timeout = setTimeout(() => {
       pendingResponses.delete(id);
@@ -16623,6 +16694,15 @@ var createHandlerContext = (req, url) => {
     headers,
     url,
     getWindowInfo,
+    focusWindow: (windowId) => {
+      const win = windows2.get(windowId);
+      if (!win) {
+        return { ok: false, error: `Tab ${windowId} not found (run \`hj tabs\` to list connected tabs)` };
+      }
+      focusedWindowId = windowId;
+      updateHjStatus();
+      return { ok: true, active: win.active, windowType: win.windowType, title: win.title };
+    },
     startRecordingSession,
     stopRecordingSession,
     getRecordingSession,
@@ -18300,12 +18380,10 @@ Type 'help <topic>' for details.`);
             break;
           }
           case "tabs-focus": {
-            const resp = await requestFromBrowser("tabs", "focus", { windowId: step.window }, stepTimeout);
-            if (!resp.success) {
+            if (!step.window || !windows2.has(step.window)) {
               stepPassed = false;
-              error = resp.error || "Failed to focus tab";
-            }
-            if (step.window && windows2.has(step.window)) {
+              error = `Tab ${step.window ?? "(none)"} not found`;
+            } else {
               focusedWindowId = step.window;
             }
             break;

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.5.1";
+export declare const VERSION = "1.5.4";

package/dist/warning-dedupe.d.ts

@@ -0,0 +1,19 @@
+/**
+ * De-duplicate the tab warnings (hidden-tab #3, focus-ambiguity #2) so a burst of untargeted
+ * commands from one agent doesn't repeat the same multi-line block on every single one. That
+ * repetition is the alarm-fatigue the repo's own skew-warning rationale warns about: a caveat that
+ * fires on every command trains agents to ignore it, including the time it matters.
+ *
+ * **Why a short cooldown and not "once, forever":** the server has many clients and can't tell them
+ * apart, so a permanent global suppression would hide the warning from a *second* agent that never
+ * saw it — the exact "plausible-but-wrong answer with no caveat" failure these warnings exist to
+ * prevent. A short cooldown collapses the one-agent burst (the real fatigue source) while keeping
+ * the window in which another client could miss it tiny; the condition persists, so their next
+ * command past the cooldown re-warns.
+ *
+ * **Why key on the whole warning string:** the text already encodes the full condition — which tab
+ * answered, whether it's hidden, the exact set of other origins. So a *changed* situation (a
+ * different tab, a newly-hidden tab, a new origin on the server) produces different text and is
+ * never suppressed. Identical text means identical situation.
+ */
+export declare function shouldEmitWarning(warning: string, cache: Map<string, number>, now: number, cooldownMs: number): boolean;

package/docs/CI-INTEGRATION.md

@@ -95,6 +95,24 @@ run: |
 
 ## Launch Options
 
+### Which engine? (read this first)
+
+Haltija can drive one of two browser engines in CI, and they need **different** external browsers —
+picking by the words "for CI" alone leads people to the wrong one:
+
+| You want | Use | Engine | External dependency |
+| --- | --- | --- | --- |
+| The default CI path | `--ci` | **Electron** (Chromium) | Electron (auto-fetched via `npx`) — **no Playwright** |
+| Isolated CI instance, own ephemeral port | `--private --app` | **Electron** (Chromium) | Electron (as above) |
+| Multi-engine coverage (Firefox/WebKit) or a lighter single-engine run | `--headless` | **Playwright** Chromium | the `playwright` package (`npm i playwright && npx playwright install`) |
+
+Neither engine is bundled in the npm package, so *something* is downloaded either way — the choice
+is **Electron vs. Playwright**, not "deps vs. no deps". The one genuine reason to reach for
+`--headless`/Playwright is engines Electron can't give you (Firefox, WebKit). For a straight
+Chromium CI lane, `--ci` (Electron) needs no separate `playwright` install. `--private` is an
+*isolation* modifier — it pairs with either engine (`--private --app` = Electron, `--private
+--headless` = Playwright).
+
 ### Option 1: CI mode (recommended)
 
 ```bash
@@ -115,13 +133,18 @@ xvfb-run --auto-servernum bunx haltija@latest --app &
 
 Same as `--ci` but doesn't wait for ready state. You'll need to poll `/status` yourself.
 
-### Option 3: Playwright headless (lighter weight)
+### Option 3: Playwright headless (multi-engine)
 
 ```bash
+npm install playwright && npx playwright install chromium   # required — not bundled
 bunx haltija@latest --headless &
 ```
 
-Uses Playwright's Chromium instead of Electron. Lighter weight but slightly different browser engine.
+Uses **Playwright's** Chromium instead of Electron, so it needs the `playwright` package installed
+(the command above; without it, `--headless` exits with a "Playwright not installed" error that
+points you back to `--ci`). Choose this when you want a lighter single-engine run or, the real
+reason, **multi-engine coverage** — Playwright can also drive Firefox and WebKit, which Electron
+cannot. For a plain Chromium lane with no extra install, prefer Option 1 (`--ci`).
 
 ### Option 4: Server-only mode (lighter weight)
 

package/llms.txt

@@ -40,8 +40,17 @@ Two first-party ways to run (plus embedding, below):
   `hj tree` inside a project reaches that project's server with no flags. Falling
   back to the shared default port 8700 warns on stderr. Use `hj where` to see which
   port a shell targets and WHY; override with `--port` or `--name`.
-- **CI:** `haltija --headless` (or `--ci`) runs a headless Chromium with the widget
-  auto-injected — deterministic, no desktop app required. See the CI guide below.
+- **CI:** two engines, and the choice matters — both need one external browser, but
+  a *different* one:
+  - `haltija --ci` (or `--private --app` for an isolated instance) drives **Electron**
+    (Chromium — the same engine the Haltija desktop app uses). Electron is fetched via
+    `npx` if not already present; **no `playwright` needed.** This is the default CI path.
+  - `haltija --headless` drives **Playwright Chromium**, which requires the `playwright`
+    package (`npm i playwright && npx playwright install chromium`). Reach for it when you
+    want multi-engine coverage (Firefox/WebKit) or a lighter single-engine run — not just
+    because it says "for CI". `--private` is an *isolation* modifier (ephemeral port), and
+    pairs with either engine: `--private --app` (Electron) or `--private --headless`
+    (Playwright). See the CI guide below.
 
 ## Embed in your app
 

package/package.json

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