haltija 1.3.0 → 1.3.2

package/README.md

@@ -61,18 +61,24 @@ Full API: `hj docs` — or `hj api` for complete reference
 
 ---
 
-## Why Not Playwright / Puppeteer?
-
-| | Haltija | Playwright MCP |
-|---|---------|----------------|
-| **Browser** | Your real browser | Separate headless instance |
-| **State** | Already logged in, cookies, extensions | Clean slate every time |
-| **Setup** | `bunx haltija` | Install Playwright, configure MCP |
-| **Protocol** | Simple REST/curl | Complex CDP |
-| **Feedback** | "Button hidden by modal" | `TimeoutError: element not found` |
-| **Visibility** | Watch it happen live | Background process |
-
-Haltija connects to the browser you're already using. The one with the bug, the active session, and the weird cookie state. No reproduction script required.
+## Haltija vs. Playwright
+
+Playwright is a mature, cross-browser automation framework with deep tooling (trace viewer, codegen, test runner, fixtures) and an official MCP that hands agents a structured accessibility snapshot. Reach for it when you want cross-browser coverage or a full test framework. Haltija aims at something narrower: letting an agent drive **a browser you're already running**, over plain HTTP — or spawn its own when you'd rather it did.
+
+| | Haltija | Playwright (+ MCP) |
+|---|---|---|
+| Browser | Attach to your real, already-open browser — *or* spawn its own | Usually its own managed context; can connect to an existing browser over CDP |
+| Cross-browser | ⚠️ Chromium only | ✅ Chromium, Firefox, WebKit |
+| Session / auth | Uses your live logged-in session as-is | Fresh context by default; reusable via `storageState` / persistent context |
+| How an agent drives it | Plain HTTP/REST — curl, any language, no client library | Playwright client library, or the MCP tools |
+| Page model | DOM tree with stable ref IDs + `eval` | Accessibility-tree snapshot with ref IDs (MCP), or the full API in code |
+| Interaction | Per-character, framework-triggering synthetic events you can steer live over HTTP | Trusted CDP-level input |
+| Feedback when a step can't proceed | **Fails fast** — reports what's blocking it (missing / hidden / covered) right away | **Auto-waits to a timeout** (tens of seconds) — smooths over races, but a genuinely broken step burns the full timeout before failing |
+| Test generation | record→replay → JSON tests | codegen → Playwright code |
+| Debugging | Live widget, console capture, semantic events, click diff | Trace viewer — time-travel step snapshots |
+| Embed in your app | ✅ Ship the widget inside your own product | Not designed for that |
+
+**The short version:** they're complementary, and this project uses both — Playwright for cross-browser smoke checks, Haltija for the fast end-to-end pass. Reach for Haltija when you want to point an agent at the browser (and logged-in session) you already have, or embed agent-control into your own app — over nothing more than HTTP.
 
 ---
 

package/apps/desktop/package.json

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

package/apps/desktop/resources/component.js

@@ -46,7 +46,7 @@
   });
 
   // src/version.ts
-  var VERSION = "1.3.0";
+  var VERSION = "1.3.2";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;

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/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.0";
+export declare const VERSION = "1.3.2";
 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.3.0";
+var VERSION = "1.3.2";
 
 // src/text-selector.ts
 var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;

package/dist/component.js

@@ -46,7 +46,7 @@
   });
 
   // src/version.ts
-  var VERSION = "1.3.0";
+  var VERSION = "1.3.2";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;

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.0";
+var VERSION = "1.3.2";
 
 // src/embedded-assets.ts
 var APP_MD = `# Haltija App
@@ -3019,7 +3019,7 @@ var COMPONENT_JS = `(() => {
   });
 
   // src/version.ts
-  var VERSION = "1.3.0";
+  var VERSION = "1.3.2";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\\(/;

package/dist/server.js

@@ -674,7 +674,7 @@ var injectorCode = `
 `;
 
 // src/version.ts
-var VERSION = "1.3.0";
+var VERSION = "1.3.2";
 
 // src/embedded-assets.ts
 var APP_MD = `# Haltija App
@@ -3019,7 +3019,7 @@ var COMPONENT_JS = `(() => {
   });
 
   // src/version.ts
-  var VERSION = "1.3.0";
+  var VERSION = "1.3.2";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\\(/;

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

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