haltija 1.5.2 → 1.5.4

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # 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.

package/apps/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haltija-desktop",
-  "version": "1.5.2",
+  "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.2";
+  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
@@ -106,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)
@@ -729,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.2'
+export const HJ_VERSION = '1.5.4'

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.2";
+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.2";
+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.2";
+  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.2
+// 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.2";
+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.2";
+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:**
 
@@ -3024,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
 
@@ -3101,7 +3116,7 @@ var COMPONENT_JS = `(() => {
   });
 
   // src/version.ts
-  var VERSION = "1.5.2";
+  var VERSION = "1.5.4";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\\(/;
@@ -8692,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) {
@@ -12818,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
@@ -14247,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) => {

package/dist/server.js

@@ -674,7 +674,7 @@ var injectorCode = `
 `;
 
 // src/version.ts
-var VERSION = "1.5.2";
+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:**
 
@@ -3024,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
 
@@ -3101,7 +3116,7 @@ var COMPONENT_JS = `(() => {
   });
 
   // src/version.ts
-  var VERSION = "1.5.2";
+  var VERSION = "1.5.4";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\\(/;
@@ -8692,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) {
@@ -12818,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
@@ -14247,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) => {

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

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.2",
+  "version": "1.5.4",
   "description": "Browser control for AI agents - query DOM, click, type, run JS, watch mutations",
   "type": "module",
   "main": "dist/index.js",