haltija 1.13.0-beta.2 → 1.13.0-beta.3

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 1.13.0-beta.3 (2026-10-08)
+
+### Added
+
+- **`hj doctor` prints an `observability:` line whenever a tab is connected** (#821, GitHub #50). It
+  says whether the tab that commands go to is visible and painting and, for widgets 1.12.6 or
+  newer, how long ago it last drew a frame. When
+  it isn't, the line says what that invalidates: geometry, screenshots and anything rAF-driven. A
+  backgrounded tab still answers, just wrongly, so this matters even when nothing fails. Also in
+  `--json` as `observability`.
+
+- **`hj map` reads tosijs's shipped agent-surface contract** (#787, GitHub #16). It reads
+  `describe().version`, `exposure` and `writable` instead of inferring them, and was verified
+  against real tosijs 1.10.6.
+  - A read-only surface (a manifest without `write: true`) is reported as read-only. The map used
+    to tell agents to call `write()`, which the surface refuses.
+  - The callable actions are listed.
+  - An empty `'closed'` surface, the tosijs default, comes with a hint on how the app's author
+    enables it.
+  - A surface version haltija doesn't read produces a warning.
+  - The tier is no longer marked experimental, in the skill or in the `/map` API description.
+
+- **`playwrightBridge(page)`** in `haltija/test`: runs `testInBrowser` probes in Firefox and WebKit
+  through a Playwright page you launch (virta #3088). Tested in all three engines. New
+  `docs/TEST-IN-BROWSER.md` covers it, the bridge contract, and which engine each route reaches.
+
+### Fixed
+
+- **A bridge that wraps its `eval` reply is now named as the problem** (virta #2415).
+  `BrowserBridge.eval` was typed `Promise<any>` with no stated contract, and a bridge returning
+  `{ success: true, value }` made every `read()` fail with a bare "probe threw" although the probe
+  had run. The return shape is now typed and documented, and the error says the bridge returned no
+  `{ ok }` envelope and lists the keys it did return.
+
+  - Type change: `BrowserBridge.eval` now resolves to `unknown` rather than `any`. Bridges you
+    wrote still compile. Code that calls `.eval()` on a `BrowserBridge`-typed value and reads a
+    property off the result needs a cast.
+
+- **`haltija --server` no longer leaves its server running when the launcher is stopped.** The
+  server is a child process, and nothing passed a signal on, so a process manager (or a closed
+  terminal) that stopped the launcher left the server alive and holding its ports. SIGTERM, SIGINT
+  and SIGHUP now stop both.
+
+- **The docs no longer say `--headless` gives Firefox/WebKit coverage.** It launches Chromium and
+  has no engine flag. `--help`, the CI guide, the skill and `/llms.txt` all said to pick it for
+  multi-engine coverage.
+
+- **`hj doctor` checks visibility on the tab commands actually go to**, not across all tabs. A
+  hidden target used to pass with a note as long as some other tab was visible, while every
+  command went to the hidden one. For a project with declared origins that is the tab its
+  commands are pinned to, whichever tab has focus.
+
+- **Freeing a busy HTTPS port is now deliberate.** It used to probe the HTTPS port with plain HTTP,
+  which always failed, so the holder was refused as "a server we could not identify". That was the
+  right outcome only by accident, and the message misled (#1079).
+  - The HTTPS port is freed only when it was itself explicitly requested (`--https-port` /
+    `DEV_CHANNEL_HTTPS_PORT`). Being strict about the HTTP port says nothing about the HTTPS one,
+    and stopping a server's HTTPS listener stops its whole process, HTTP included.
+  - The holder is identified over TLS and asked to stop, under the same rules as the HTTP port.
+
 ## 1.13.0-beta.2 (2026-09-29)
 
 ### Changed

package/apps/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haltija-desktop",
-  "version": "1.13.0-beta.2",
+  "version": "1.13.0-beta.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.13.0-beta.2";
+  var VERSION = "1.13.0-beta.3";
 
   // src/ws-url.ts
   function httpBaseFromWsUrl(wsUrl2, fallback = "http://localhost:8700") {
@@ -1374,16 +1374,26 @@
         const description = agent.describe();
         const wiring = description?.wiring;
         const shapeWarning = wiring === undefined ? `${globalName}.describe() returned no 'wiring' — this haltija understands the agent ` + `surface as { wiring: [{ tag, id, label, on }] }. The map below is passed through ` + `unchanged and may be missing structure; the schematic will be empty. Check the ` + `tosijs version, or use hj map with the DOM fallback (a page without tosiAgent).` : !Array.isArray(wiring) ? `${globalName}.describe().wiring is ${typeof wiring}, expected an array — passing it ` + `through unchanged, but the schematic cannot render it.` : undefined;
+        const d = description;
+        const surfaceVersion = d?.version ?? agent.version;
+        const surfaceMajor = surfaceVersion && typeof surfaceVersion === "object" && typeof surfaceVersion.surface === "string" ? surfaceVersion.surface.split(".")[0] : null;
+        const versionWarning = surfaceMajor !== null && surfaceMajor !== "1" ? `${globalName} reports agent surface ${surfaceVersion.surface}; this haltija reads surface ` + `1.x, so fields may be missing or misread. Update haltija.` : undefined;
+        const warning = [shapeWarning, versionWarning].filter(Boolean).join(" ") || undefined;
+        const closedHint = d?.exposure === "closed" && Array.isArray(wiring) && wiring.length === 0 ? `The app exposes no wiring: exposure is 'closed', the tosijs default. Its author enables ` + `it with expose: { roots } (add write: true to allow write()). Until then, find controls ` + `with hj tree and drive them with hj click / hj type.` : undefined;
+        const actions = Array.isArray(d?.actions) ? d.actions : undefined;
+        const writeAdvice = d?.writable === false ? `This surface is READ-ONLY (describe().writable is false): ${globalName}.write() will be ` + `refused, so act through actions or realistic input instead.` : d?.writable === true ? `${globalName}.write(path, value) for a ⟷ two-way binding.` : `${globalName}.write(path, value) for a ⟷ two-way binding (writability not reported ` + `by this surface; it may refuse).`;
+        const callAdvice = actions && actions.length === 0 ? `It exposes no actions.` : `${globalName}.call(actionPath) for an action${actions ? ` (one of: ${actions.slice(0, 8).join(", ")}${actions.length > 8 ? ", …" : ""})` : ""}.`;
         return {
           url: location.href,
           title: document.title,
           source: "tosi-agent",
           global: globalName,
-          agentSurfaceVersion: agent.version ?? description?.version,
-          ...shapeWarning ? { warning: shapeWarning } : {},
+          agentSurfaceVersion: surfaceVersion,
+          ...warning ? { warning } : {},
+          ...closedHint ? { hint: closedHint } : {},
           ...description,
           act: {
-            note: `Act through the paths, not synthesized input: ${globalName}.write(path, value) for a ` + `⟷ two-way binding, ${globalName}.call(actionPath) for an action. ` + `Run them with: hj eval "${globalName}.write('some.path', 'value')"`,
+            note: `Act through the paths, not synthesized input. ${writeAdvice} ${callAdvice}` + (actions && actions.length === 0 ? "" : ` Run one with: hj eval "${globalName}.call('some.action')"`),
             legend: {
               "⟷": "two-way binding — user-writable; writing the path updates the UI and app state",
               "⟵": "bound to DOM — display only; it reflects the path, writing the DOM will not stick",

package/bin/hj.mjs

@@ -79,7 +79,7 @@ function describeOrigins(windows) {
     return { line: yellow(msg), problem: msg }
   }
   const list = declared.origins.join(', ')
-  const routing = routeByDeclaredOrigin(declared.origins, windows || [], null)
+  const routing = routeByDeclaredOrigin(declared.origins, windows || [], (windows || []).find((w) => w.focused)?.id ?? null)
   if (routing.kind === 'matched') {
     return { line: `${list} ${dim(`(${declared.source}) → window ${routing.windowId}`)}`, problem: null }
   }
@@ -331,6 +331,11 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
   // this command exists to remove.
   const unchecked = []
   let status = null
+  // First-class answer to "can I believe what this tab tells me?" (#821, GitHub #50). Everything
+  // else doctor checks is about reaching a tab; this is about whether its answers are trustworthy.
+  // A hidden or non-compositing tab still answers — geometry, screenshots and anything rAF-driven
+  // just come back wrong — so it is printed on every run, not only when something fails.
+  let observability = null
 
   try {
     const resp = await fetch(`http://localhost:${port}/status`, {
@@ -365,6 +370,22 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
     // Reads `active` via the shared predicate: /status and /windows disagreed on polarity, and
     // keying on one endpoint's field name is what made this diverge from the origin router.
     const hidden = tabs.filter((w) => !isVisible(w))
+    // The tab commands go to, resolved the way a command resolves it. Judging visibility over ALL
+    // tabs passed a lane whose target was hidden as long as some OTHER tab was visible — every
+    // command still went to the hidden one.
+    //
+    // A project with declared origins has its commands PINNED to the matching tab, wherever focus
+    // is. The first version of this looked only at focus, so for exactly the projects that
+    // declared their tabs it described another project's tab: a false pass when ours was hidden
+    // behind their visible one, a false failure the other way round (1.13.0-beta.3 review).
+    const focusedTab = tabs.find((w) => w.focused) ?? null
+    const declaredOrigins = findProjectOrigins(process.cwd(), process.env)
+    const routed = declaredOrigins?.origins.length
+      ? routeByDeclaredOrigin(declaredOrigins.origins, tabs, focusedTab?.id ?? null)
+      : null
+    const pinned = routed?.kind === 'matched' ? tabs.find((w) => w.id === routed.windowId) ?? null : null
+    const target = pinned ?? focusedTab ?? tabs.find((w) => isVisible(w)) ?? tabs[0] ?? null
+    const targetLabel = target ? `${target.title && target.title !== '(untitled)' ? `"${target.title}" ` : ''}${target.url || target.id}` : ''
     // A tab that reported NEITHER field hasn't told us anything; `isVisible` had to assume. Say so
     // rather than counting the assumption as a passed check.
     const silent = tabs.filter((w) => !visibilityKnown(w))
@@ -378,14 +399,16 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
           `Upgrade the server to make this checkable.`,
       )
     }
-    if (ready && hidden.length === tabs.length) {
+    if (ready && target && !isVisible(target)) {
       problems.push(
-        `every connected tab reports HIDDEN — results from a backgrounded tab can be ` +
-          `plausible-but-wrong (rAF/timers throttled). Bring one to the front.`,
+        `the tab commands go to (${targetLabel}) reports HIDDEN — it still answers, but geometry, ` +
+          `screenshots and anything rAF-driven WILL be wrong (timers and rendering are throttled). ` +
+          `Bring it to the front, or target a visible tab with --window <id>.`,
       )
     } else if (hidden.length) {
       notes.push(`${hidden.length} of ${tabs.length} tab(s) are hidden; commands targeting them may return stale results`)
     }
+    if (ready && target) observability = { target: target.id, label: targetLabel, visible: isVisible(target), painting: null, paintAgeMs: null }
     if (status.serverVersion && differsBeyondPatch(HJ_VERSION, status.serverVersion)) {
       notes.push(`hj ${HJ_VERSION} is driving server ${status.serverVersion} (version skew)`)
     }
@@ -413,7 +436,8 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
         // socket that never answers `/eval` (a widget mid-teardown, or a test harness holding an
         // open WebSocket) made `hj doctor` block for the server's full browser timeout.
         const cancel = AbortSignal.timeout(3000)
-        const r = await fetch(`http://localhost:${port}/eval`, {
+        // Asked of the TARGET tab. Untargeted, it measured whichever tab had focus.
+        const r = await fetch(`http://localhost:${port}/eval${target ? `?window=${encodeURIComponent(target.id)}` : ''}`, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json', ...(token ? { 'X-Haltija-Token': token } : {}) },
           body: JSON.stringify({ code: probe }),
@@ -435,6 +459,10 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
       } catch {
         // Fall through to the unchecked branch — never a pass.
       }
+      if (observability && raf !== null) {
+        observability.painting = !!raf.fired
+        observability.paintAgeMs = raf.measured ? raf.ms : null
+      }
       if (raf === null) {
         unchecked.push(
           `could not run the requestAnimationFrame probe — whether this tab actually paints is ` +
@@ -484,6 +512,7 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
       ready: status ? (typeof status.ready === 'boolean' ? status.ready : (status.windows?.length ?? 0) > 0) : false,
       tabs: status?.windows?.length ?? 0,
       problems, notes,
+      observability,
       origins: (() => {
         const d = findProjectOrigins(process.cwd(), process.env)
         return d ? { declared: d.origins, source: d.source } : null
@@ -501,6 +530,7 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
     console.log(`${bold('server:')} haltija ${status.serverVersion || '?'}${status.desktopApp ? dim(' (desktop app)') : ''}, ${tabCount} tab${tabCount === 1 ? '' : 's'}`)
   }
   if (status) console.log(`${bold('origins:')} ${describeOrigins(status.windows || []).line}`)
+  if (observability) console.log(`${bold('observability:')} ${describeObservability(observability)}`)
   for (const n of notes) console.log(`${yellow('!')} ${n}`)
   // `?` — its own glyph, because the whole point is that this is neither a pass nor a failure.
   for (const u of unchecked) console.log(`${dim('?')} ${u}`)
@@ -517,6 +547,20 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
   return ok
 }
 
+/**
+ * The `observability:` line: whether the tab commands go to will tell the truth (#821). Says what a
+ * bad state invalidates rather than only naming the state — the recorded failures were agents who
+ * knew a tab was "hidden" and still trusted its geometry.
+ */
+function describeObservability(o) {
+  const where = dim(`(${o.label})`)
+  if (!o.visible) return `${red('✗ hidden')} — geometry, screenshots and rAF-driven rendering will be wrong ${where}`
+  if (o.painting === false) return `${red('✗ not painting')} — visible but not compositing; missing elements prove nothing ${where}`
+  if (o.painting === null) return `${dim('? visible, painting unknown')} ${where}`
+  const age = o.paintAgeMs === null ? '' : dim(` (last frame ${(o.paintAgeMs / 1000).toFixed(1)}s ago)`)
+  return `${green('✓ visible and painting')}${age} ${where}`
+}
+
 /**
  * Resolve a named haltija instance to its port by reading
  * ~/.haltija/servers/<name>.json. Returns null if the file is missing,

package/bin/tosijs-dev.mjs

@@ -54,7 +54,9 @@ Options:
   --snapshots-dir <path>  Save snapshots to disk (for CI artifacts)
   --docs-dir <path>       Directory with custom docs (*.md files)
   --port <n>      Set HTTP port (default: 8700)
-  --https-port <n> Set HTTPS port (default: 8701 for the server on 8700, else ephemeral)
+  --https-port <n> Set HTTPS port (default: 8701 for the server on 8700, else ephemeral).
+                  Like --port, naming a port CLAIMS it: a haltija server already holding
+                  it is asked to stop, which ends its HTTP side too. Pick a free port.
   --token <value> Require X-Haltija-Token header on REST and ?token= on WebSocket
                   (default: off; sets HALTIJA_TOKEN)
   --name <foo>    Register this server as <foo> in ~/.haltija/servers/ so
@@ -119,7 +121,7 @@ Choosing a CI engine ${dim('(both need one external browser, but a DIFFERENT one
   ${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\".")}
+    ${dim("Chromium only. For Firefox/WebKit, launch Playwright yourself: docs/TEST-IN-BROWSER.md.")}
 
 Examples:
   haltija                          # Desktop app (or server fallback)
@@ -878,7 +880,7 @@ const startHeadlessBrowser = async (port) => {
       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.')
+      console.error('[tosijs-dev]   (--headless is Chromium only. For Firefox/WebKit see docs/TEST-IN-BROWSER.md.)')
     } else {
       console.error('[tosijs-dev] Failed to start headless browser:', err.message)
     }
@@ -886,6 +888,25 @@ const startHeadlessBrowser = async (port) => {
   }
 }
 
+/**
+ * The server is a CHILD of this launcher, and it must not outlive it.
+ *
+ * It used to: nothing forwarded a signal on the --server path, so `kill <launcher>` (a process
+ * manager, a test's afterAll, a closed terminal tab) left the server running with ppid 1, still
+ * holding its ports. A shared server has no idle timeout, so it stayed for good. Found when the
+ * HTTPS tests moved to this launcher (#1080) and each run of the suite left two servers behind.
+ *
+ * The 'exit' hook covers every path that ends in process.exit(), including the headless ones.
+ * A signal with no handler ends the process WITHOUT firing 'exit', so the non-headless path
+ * installs handlers; headless already has its own, which close the browser first.
+ */
+const superviseServer = (child) => {
+  process.on('exit', () => { try { child.kill('SIGTERM') } catch {} })
+  if (!headlessMode) {
+    for (const sig of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.on(sig, () => process.exit(0))
+  }
+}
+
 // Try bun first, fall back to node
 const tryBun = () => {
   const bun = spawn('bun', ['run', serverPath], {
@@ -901,6 +922,7 @@ const tryBun = () => {
   bun.on('exit', code => {
     process.exit(code || 0)
   })
+  superviseServer(bun)
   
   // Start headless browser after server is ready
   if (headlessMode) {
@@ -940,6 +962,7 @@ const tryNode = () => {
   node.on('exit', code => {
     process.exit(code || 0)
   })
+  superviseServer(node)
   
   // Start headless browser after server is ready
   if (headlessMode) {

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.13.0-beta.2'
+export const HJ_VERSION = '1.13.0-beta.3'

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.13.0-beta.2";
+export declare const VERSION = "1.13.0-beta.3";
 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.13.0-beta.2";
+var VERSION = "1.13.0-beta.3";
 
 // src/ws-url.ts
 function httpBaseFromWsUrl(wsUrl2, fallback = "http://localhost:8700") {
@@ -1327,16 +1327,26 @@ function buildAffordanceMap(opts = {}) {
       const description = agent.describe();
       const wiring = description?.wiring;
       const shapeWarning = wiring === undefined ? `${globalName}.describe() returned no 'wiring' — this haltija understands the agent ` + `surface as { wiring: [{ tag, id, label, on }] }. The map below is passed through ` + `unchanged and may be missing structure; the schematic will be empty. Check the ` + `tosijs version, or use hj map with the DOM fallback (a page without tosiAgent).` : !Array.isArray(wiring) ? `${globalName}.describe().wiring is ${typeof wiring}, expected an array — passing it ` + `through unchanged, but the schematic cannot render it.` : undefined;
+      const d = description;
+      const surfaceVersion = d?.version ?? agent.version;
+      const surfaceMajor = surfaceVersion && typeof surfaceVersion === "object" && typeof surfaceVersion.surface === "string" ? surfaceVersion.surface.split(".")[0] : null;
+      const versionWarning = surfaceMajor !== null && surfaceMajor !== "1" ? `${globalName} reports agent surface ${surfaceVersion.surface}; this haltija reads surface ` + `1.x, so fields may be missing or misread. Update haltija.` : undefined;
+      const warning = [shapeWarning, versionWarning].filter(Boolean).join(" ") || undefined;
+      const closedHint = d?.exposure === "closed" && Array.isArray(wiring) && wiring.length === 0 ? `The app exposes no wiring: exposure is 'closed', the tosijs default. Its author enables ` + `it with expose: { roots } (add write: true to allow write()). Until then, find controls ` + `with hj tree and drive them with hj click / hj type.` : undefined;
+      const actions = Array.isArray(d?.actions) ? d.actions : undefined;
+      const writeAdvice = d?.writable === false ? `This surface is READ-ONLY (describe().writable is false): ${globalName}.write() will be ` + `refused, so act through actions or realistic input instead.` : d?.writable === true ? `${globalName}.write(path, value) for a ⟷ two-way binding.` : `${globalName}.write(path, value) for a ⟷ two-way binding (writability not reported ` + `by this surface; it may refuse).`;
+      const callAdvice = actions && actions.length === 0 ? `It exposes no actions.` : `${globalName}.call(actionPath) for an action${actions ? ` (one of: ${actions.slice(0, 8).join(", ")}${actions.length > 8 ? ", …" : ""})` : ""}.`;
       return {
         url: location.href,
         title: document.title,
         source: "tosi-agent",
         global: globalName,
-        agentSurfaceVersion: agent.version ?? description?.version,
-        ...shapeWarning ? { warning: shapeWarning } : {},
+        agentSurfaceVersion: surfaceVersion,
+        ...warning ? { warning } : {},
+        ...closedHint ? { hint: closedHint } : {},
         ...description,
         act: {
-          note: `Act through the paths, not synthesized input: ${globalName}.write(path, value) for a ` + `⟷ two-way binding, ${globalName}.call(actionPath) for an action. ` + `Run them with: hj eval "${globalName}.write('some.path', 'value')"`,
+          note: `Act through the paths, not synthesized input. ${writeAdvice} ${callAdvice}` + (actions && actions.length === 0 ? "" : ` Run one with: hj eval "${globalName}.call('some.action')"`),
           legend: {
             "⟷": "two-way binding — user-writable; writing the path updates the UI and app state",
             "⟵": "bound to DOM — display only; it reflects the path, writing the DOM will not stick",

package/dist/component.js

@@ -46,7 +46,7 @@
   });
 
   // src/version.ts
-  var VERSION = "1.13.0-beta.2";
+  var VERSION = "1.13.0-beta.3";
 
   // src/ws-url.ts
   function httpBaseFromWsUrl(wsUrl2, fallback = "http://localhost:8700") {
@@ -1374,16 +1374,26 @@
         const description = agent.describe();
         const wiring = description?.wiring;
         const shapeWarning = wiring === undefined ? `${globalName}.describe() returned no 'wiring' — this haltija understands the agent ` + `surface as { wiring: [{ tag, id, label, on }] }. The map below is passed through ` + `unchanged and may be missing structure; the schematic will be empty. Check the ` + `tosijs version, or use hj map with the DOM fallback (a page without tosiAgent).` : !Array.isArray(wiring) ? `${globalName}.describe().wiring is ${typeof wiring}, expected an array — passing it ` + `through unchanged, but the schematic cannot render it.` : undefined;
+        const d = description;
+        const surfaceVersion = d?.version ?? agent.version;
+        const surfaceMajor = surfaceVersion && typeof surfaceVersion === "object" && typeof surfaceVersion.surface === "string" ? surfaceVersion.surface.split(".")[0] : null;
+        const versionWarning = surfaceMajor !== null && surfaceMajor !== "1" ? `${globalName} reports agent surface ${surfaceVersion.surface}; this haltija reads surface ` + `1.x, so fields may be missing or misread. Update haltija.` : undefined;
+        const warning = [shapeWarning, versionWarning].filter(Boolean).join(" ") || undefined;
+        const closedHint = d?.exposure === "closed" && Array.isArray(wiring) && wiring.length === 0 ? `The app exposes no wiring: exposure is 'closed', the tosijs default. Its author enables ` + `it with expose: { roots } (add write: true to allow write()). Until then, find controls ` + `with hj tree and drive them with hj click / hj type.` : undefined;
+        const actions = Array.isArray(d?.actions) ? d.actions : undefined;
+        const writeAdvice = d?.writable === false ? `This surface is READ-ONLY (describe().writable is false): ${globalName}.write() will be ` + `refused, so act through actions or realistic input instead.` : d?.writable === true ? `${globalName}.write(path, value) for a ⟷ two-way binding.` : `${globalName}.write(path, value) for a ⟷ two-way binding (writability not reported ` + `by this surface; it may refuse).`;
+        const callAdvice = actions && actions.length === 0 ? `It exposes no actions.` : `${globalName}.call(actionPath) for an action${actions ? ` (one of: ${actions.slice(0, 8).join(", ")}${actions.length > 8 ? ", …" : ""})` : ""}.`;
         return {
           url: location.href,
           title: document.title,
           source: "tosi-agent",
           global: globalName,
-          agentSurfaceVersion: agent.version ?? description?.version,
-          ...shapeWarning ? { warning: shapeWarning } : {},
+          agentSurfaceVersion: surfaceVersion,
+          ...warning ? { warning } : {},
+          ...closedHint ? { hint: closedHint } : {},
           ...description,
           act: {
-            note: `Act through the paths, not synthesized input: ${globalName}.write(path, value) for a ` + `⟷ two-way binding, ${globalName}.call(actionPath) for an action. ` + `Run them with: hj eval "${globalName}.write('some.path', 'value')"`,
+            note: `Act through the paths, not synthesized input. ${writeAdvice} ${callAdvice}` + (actions && actions.length === 0 ? "" : ` Run one with: hj eval "${globalName}.call('some.action')"`),
             legend: {
               "⟷": "two-way binding — user-writable; writing the path updates the UI and app state",
               "⟵": "bound to DOM — display only; it reflects the path, writing the DOM will not stick",

package/dist/hj.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-// haltija-cli:do-not-edit v1.13.0-beta.2
+// haltija-cli:do-not-edit v1.13.0-beta.3
 var __esm = (fn, res, err) => () => {
   if (fn)
     try {
@@ -785,7 +785,7 @@ function substituteGeneratedVars(text, seed) {
 }
 
 // bin/version.mjs
-var HJ_VERSION = "1.13.0-beta.2";
+var HJ_VERSION = "1.13.0-beta.3";
 
 // bin/semver.mjs
 function parseVersion(v) {
@@ -2608,7 +2608,7 @@ function describeOrigins(windows) {
     return { line: yellow2(msg), problem: msg };
   }
   const list = declared.origins.join(", ");
-  const routing = routeByDeclaredOrigin(declared.origins, windows || [], null);
+  const routing = routeByDeclaredOrigin(declared.origins, windows || [], (windows || []).find((w) => w.focused)?.id ?? null);
   if (routing.kind === "matched") {
     return { line: `${list} ${dim3(`(${declared.source}) → window ${routing.windowId}`)}`, problem: null };
   }
@@ -2771,6 +2771,7 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
   const notes = [];
   const unchecked = [];
   let status = null;
+  let observability = null;
   try {
     const resp = await fetch(`http://localhost:${port}/status`, {
       headers: token ? { "X-Haltija-Token": token } : {},
@@ -2791,15 +2792,23 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
       problems.push(`the server on port ${port} is up but has NO connected browser tab — nothing to drive. ` + `Open a tab in the desktop app, or inject the widget into a page. ` + `("server is up" is not "server is drivable" — that's what this check exists for.)`);
     }
     const hidden = tabs.filter((w) => !isVisible2(w));
+    const focusedTab = tabs.find((w) => w.focused) ?? null;
+    const declaredOrigins = findProjectOrigins(process.cwd(), process.env);
+    const routed = declaredOrigins?.origins.length ? routeByDeclaredOrigin(declaredOrigins.origins, tabs, focusedTab?.id ?? null) : null;
+    const pinned = routed?.kind === "matched" ? tabs.find((w) => w.id === routed.windowId) ?? null : null;
+    const target = pinned ?? focusedTab ?? tabs.find((w) => isVisible2(w)) ?? tabs[0] ?? null;
+    const targetLabel = target ? `${target.title && target.title !== "(untitled)" ? `"${target.title}" ` : ""}${target.url || target.id}` : "";
     const silent = tabs.filter((w) => !visibilityKnown(w));
     if (ready && silent.length) {
       unchecked.push(`${silent.length} of ${tabs.length} tab(s) did not report visibility${status.serverVersion ? ` (server ${status.serverVersion} is too old to send it)` : ""} — this check ASSUMED they are on screen and cannot confirm it. ` + `A backgrounded tab returns plausible-but-wrong results (rAF/timers throttled), so if ` + `something looks stale, that assumption is the first thing to doubt. ` + `Upgrade the server to make this checkable.`);
     }
-    if (ready && hidden.length === tabs.length) {
-      problems.push(`every connected tab reports HIDDEN — results from a backgrounded tab can be ` + `plausible-but-wrong (rAF/timers throttled). Bring one to the front.`);
+    if (ready && target && !isVisible2(target)) {
+      problems.push(`the tab commands go to (${targetLabel}) reports HIDDEN — it still answers, but geometry, ` + `screenshots and anything rAF-driven WILL be wrong (timers and rendering are throttled). ` + `Bring it to the front, or target a visible tab with --window <id>.`);
     } else if (hidden.length) {
       notes.push(`${hidden.length} of ${tabs.length} tab(s) are hidden; commands targeting them may return stale results`);
     }
+    if (ready && target)
+      observability = { target: target.id, label: targetLabel, visible: isVisible2(target), painting: null, paintAgeMs: null };
     if (status.serverVersion && differsBeyondPatch(HJ_VERSION, status.serverVersion)) {
       notes.push(`hj ${HJ_VERSION} is driving server ${status.serverVersion} (version skew)`);
     }
@@ -2808,7 +2817,7 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
       let raf = null;
       try {
         const cancel = AbortSignal.timeout(3000);
-        const r = await fetch(`http://localhost:${port}/eval`, {
+        const r = await fetch(`http://localhost:${port}/eval${target ? `?window=${encodeURIComponent(target.id)}` : ""}`, {
           method: "POST",
           headers: { "Content-Type": "application/json", ...token ? { "X-Haltija-Token": token } : {} },
           body: JSON.stringify({ code: probe }),
@@ -2823,6 +2832,10 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
           }
         }
       } catch {}
+      if (observability && raf !== null) {
+        observability.painting = !!raf.fired;
+        observability.paintAgeMs = raf.measured ? raf.ms : null;
+      }
       if (raf === null) {
         unchecked.push(`could not run the requestAnimationFrame probe — whether this tab actually paints is ` + `UNKNOWN. If elements seem missing, suspect a non-compositing tab before the page.`);
       } else if (!raf.fired) {
@@ -2849,6 +2862,7 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
       tabs: status?.windows?.length ?? 0,
       problems,
       notes,
+      observability,
       origins: (() => {
         const d = findProjectOrigins(process.cwd(), process.env);
         return d ? { declared: d.origins, source: d.source } : null;
@@ -2864,6 +2878,8 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
   }
   if (status)
     console.log(`${bold2("origins:")} ${describeOrigins(status.windows || []).line}`);
+  if (observability)
+    console.log(`${bold2("observability:")} ${describeObservability(observability)}`);
   for (const n of notes)
     console.log(`${yellow2("!")} ${n}`);
   for (const u of unchecked)
@@ -2875,6 +2891,17 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
   }
   return ok;
 }
+function describeObservability(o) {
+  const where = dim3(`(${o.label})`);
+  if (!o.visible)
+    return `${red2("✗ hidden")} — geometry, screenshots and rAF-driven rendering will be wrong ${where}`;
+  if (o.painting === false)
+    return `${red2("✗ not painting")} — visible but not compositing; missing elements prove nothing ${where}`;
+  if (o.painting === null)
+    return `${dim3("? visible, painting unknown")} ${where}`;
+  const age = o.paintAgeMs === null ? "" : dim3(` (last frame ${(o.paintAgeMs / 1000).toFixed(1)}s ago)`);
+  return `${green2("✓ visible and painting")}${age} ${where}`;
+}
 function lookupNamedInstance(name) {
   const path = join3(REGISTRY_DIR, `${name}.json`);
   if (!existsSync3(path))

package/dist/index.js

@@ -647,7 +647,7 @@ var injectorCode = `
 `;
 
 // src/version.ts
-var VERSION = "1.13.0-beta.2";
+var VERSION = "1.13.0-beta.3";
 
 // src/embedded-assets.ts
 var APP_MD = `# Haltija App
@@ -1369,10 +1369,11 @@ Works with standard forms and most framework components (React, Vue, etc).
 
 Returns a map of the page's affordances. Two tiers, and the difference matters:
 
-**Native (\`source: "tosi-agent"\`) \u2014 EXPERIMENTAL.** haltija detects this tier by duck-typing one
-method and consumes a shape tosijs has not committed to (no version/capability marker yet \u2014 see
-tosijs#23). When the shape isn't what haltija expects it returns a \`warning\` and \`agentSurfaceVersion\`
-rather than passing a blank map off as a success, but treat the tier as best-effort. When the page
+**Native (\`source: "tosi-agent"\`).** haltija reads the contract tosijs ships: the surface's
+\`version\`, \`exposure\` and \`writable\`. A read-only surface is reported as read-only, an empty
+\`'closed'\` surface comes with a hint for the app's author, and a surface version haltija does not
+read produces a \`warning\` and \`agentSurfaceVersion\` rather than a blank map passed off as a
+success. When the page
 exposes an agent surface at
 \`globalThis.tosiAgent\` (a tosijs app calling \`enableAgentInterface()\`), the map is the app's OWN
 wiring records. That carries what the DOM cannot: which state path each control is bound to and in
@@ -3492,9 +3493,9 @@ Two first-party ways to run (plus embedding, below):
     (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
+    package (\`npm i playwright && npx playwright install chromium\`). It is Chromium only,
+    with no engine flag; for Firefox/WebKit launch Playwright yourself (see
+    docs/TEST-IN-BROWSER.md). \`--private\` is an *isolation* modifier (ephemeral port), and
     pairs with either engine: \`--private --app\` (Electron) or \`--private --headless\`
     (Playwright). See the CI guide below.
 
@@ -3623,7 +3624,7 @@ var COMPONENT_JS = `(() => {
   });
 
   // src/version.ts
-  var VERSION = "1.13.0-beta.2";
+  var VERSION = "1.13.0-beta.3";
 
   // src/ws-url.ts
   function httpBaseFromWsUrl(wsUrl2, fallback = "http://localhost:8700") {
@@ -4951,16 +4952,26 @@ var COMPONENT_JS = `(() => {
         const description = agent.describe();
         const wiring = description?.wiring;
         const shapeWarning = wiring === undefined ? \`\${globalName}.describe() returned no 'wiring' \u2014 this haltija understands the agent \` + \`surface as { wiring: [{ tag, id, label, on }] }. The map below is passed through \` + \`unchanged and may be missing structure; the schematic will be empty. Check the \` + \`tosijs version, or use hj map with the DOM fallback (a page without tosiAgent).\` : !Array.isArray(wiring) ? \`\${globalName}.describe().wiring is \${typeof wiring}, expected an array \u2014 passing it \` + \`through unchanged, but the schematic cannot render it.\` : undefined;
+        const d = description;
+        const surfaceVersion = d?.version ?? agent.version;
+        const surfaceMajor = surfaceVersion && typeof surfaceVersion === "object" && typeof surfaceVersion.surface === "string" ? surfaceVersion.surface.split(".")[0] : null;
+        const versionWarning = surfaceMajor !== null && surfaceMajor !== "1" ? \`\${globalName} reports agent surface \${surfaceVersion.surface}; this haltija reads surface \` + \`1.x, so fields may be missing or misread. Update haltija.\` : undefined;
+        const warning = [shapeWarning, versionWarning].filter(Boolean).join(" ") || undefined;
+        const closedHint = d?.exposure === "closed" && Array.isArray(wiring) && wiring.length === 0 ? \`The app exposes no wiring: exposure is 'closed', the tosijs default. Its author enables \` + \`it with expose: { roots } (add write: true to allow write()). Until then, find controls \` + \`with hj tree and drive them with hj click / hj type.\` : undefined;
+        const actions = Array.isArray(d?.actions) ? d.actions : undefined;
+        const writeAdvice = d?.writable === false ? \`This surface is READ-ONLY (describe().writable is false): \${globalName}.write() will be \` + \`refused, so act through actions or realistic input instead.\` : d?.writable === true ? \`\${globalName}.write(path, value) for a \u27F7 two-way binding.\` : \`\${globalName}.write(path, value) for a \u27F7 two-way binding (writability not reported \` + \`by this surface; it may refuse).\`;
+        const callAdvice = actions && actions.length === 0 ? \`It exposes no actions.\` : \`\${globalName}.call(actionPath) for an action\${actions ? \` (one of: \${actions.slice(0, 8).join(", ")}\${actions.length > 8 ? ", \u2026" : ""})\` : ""}.\`;
         return {
           url: location.href,
           title: document.title,
           source: "tosi-agent",
           global: globalName,
-          agentSurfaceVersion: agent.version ?? description?.version,
-          ...shapeWarning ? { warning: shapeWarning } : {},
+          agentSurfaceVersion: surfaceVersion,
+          ...warning ? { warning } : {},
+          ...closedHint ? { hint: closedHint } : {},
           ...description,
           act: {
-            note: \`Act through the paths, not synthesized input: \${globalName}.write(path, value) for a \` + \`\u27F7 two-way binding, \${globalName}.call(actionPath) for an action. \` + \`Run them with: hj eval "\${globalName}.write('some.path', 'value')"\`,
+            note: \`Act through the paths, not synthesized input. \${writeAdvice} \${callAdvice}\` + (actions && actions.length === 0 ? "" : \` Run one with: hj eval "\${globalName}.call('some.action')"\`),
             legend: {
               "\u27F7": "two-way binding \u2014 user-writable; writing the path updates the UI and app state",
               "\u27F5": "bound to DOM \u2014 display only; it reflects the path, writing the DOM will not stick",
@@ -15068,10 +15079,11 @@ var map = endpoint({
   summary: "Affordance map \u2014 what can be interacted with, and what it is wired to",
   description: `Returns a map of the page's affordances. Two tiers, and the difference matters:
 
-**Native (\`source: "tosi-agent"\`) \u2014 EXPERIMENTAL.** haltija detects this tier by duck-typing one
-method and consumes a shape tosijs has not committed to (no version/capability marker yet \u2014 see
-tosijs#23). When the shape isn't what haltija expects it returns a \`warning\` and \`agentSurfaceVersion\`
-rather than passing a blank map off as a success, but treat the tier as best-effort. When the page
+**Native (\`source: "tosi-agent"\`).** haltija reads the contract tosijs ships: the surface's
+\`version\`, \`exposure\` and \`writable\`. A read-only surface is reported as read-only, an empty
+\`'closed'\` surface comes with a hint for the app's author, and a surface version haltija does not
+read produces a \`warning\` and \`agentSurfaceVersion\` rather than a blank map passed off as a
+success. When the page
 exposes an agent surface at
 \`globalThis.tosiAgent\` (a tosijs app calling \`enableAgentInterface()\`), the map is the app's OWN
 wiring records. That carries what the DOM cannot: which state path each control is bound to and in
@@ -22567,12 +22579,12 @@ var serverConfig = {
     }
   }
 };
-async function freePort(port) {
+async function freePort(port, scheme = "http") {
   if (process.env.HALTIJA_NO_RETIRE === "1")
     return false;
   if (listenerPidsOnPort(port).length === 0)
     return false;
-  const probe = await probePort(port);
+  const probe = await probePort(port, scheme);
   if (planFreePort(probe) === "decline") {
     recordMachineAction({
       kind: "declined",
@@ -22580,7 +22592,7 @@ async function freePort(port) {
     });
     return false;
   }
-  if (await requestShutdown(port)) {
+  if (await requestShutdown(port, 3000, scheme)) {
     recordMachineAction({
       kind: "server-stopped",
       detail: `stopped the haltija server on :${port} because this server was explicitly asked to bind that port`
@@ -22609,21 +22621,23 @@ async function freePort(port) {
     Bun.sleepSync(100);
   return killed;
 }
-async function requestShutdown(port, timeoutMs = 3000) {
+async function requestShutdown(port, timeoutMs = 3000, scheme = "http") {
   const authHeaders = REQUIRED_TOKEN ? { "X-Haltija-Token": REQUIRED_TOKEN } : {};
   try {
-    await fetch(`http://localhost:${port}/shutdown`, {
+    await fetch(`${scheme}://localhost:${port}/shutdown`, {
       method: "POST",
       headers: authHeaders,
-      signal: AbortSignal.timeout(1500)
+      signal: AbortSignal.timeout(1500),
+      ...selfSigned(scheme)
     });
   } catch {}
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
     try {
-      await fetch(`http://localhost:${port}/status`, {
+      await fetch(`${scheme}://localhost:${port}/status`, {
         headers: authHeaders,
-        signal: AbortSignal.timeout(500)
+        signal: AbortSignal.timeout(500),
+        ...selfSigned(scheme)
       });
     } catch {
       return true;
@@ -22632,11 +22646,15 @@ async function requestShutdown(port, timeoutMs = 3000) {
   }
   return false;
 }
-async function probePort(port) {
+function selfSigned(scheme) {
+  return scheme === "https" ? { tls: { rejectUnauthorized: false } } : {};
+}
+async function probePort(port, scheme = "http") {
   const unknown = { port, version: null, desktopApp: null, pid: null };
   try {
-    const resp = await fetch(`http://localhost:${port}/status`, {
+    const resp = await fetch(`${scheme}://localhost:${port}/status`, {
       signal: AbortSignal.timeout(1000),
+      ...selfSigned(scheme),
       headers: REQUIRED_TOKEN ? { "X-Haltija-Token": REQUIRED_TOKEN } : {}
     });
     if (!resp.ok)
@@ -22759,7 +22777,7 @@ if (USE_HTTPS) {
       httpsServer = bindHttps();
   } catch (err) {
     if (certFailure(err)) {} else if (err && typeof err === "object" && "code" in err && err.code === "EADDRINUSE") {
-      if (PORT_IS_STRICT && await freePort(wantedHttpsPort)) {
+      if (HTTPS_PORT_EXPLICIT !== null && await freePort(wantedHttpsPort, "https")) {
         httpsServer = bindHttps();
       } else {
         for (let attempt = 0;attempt < 5 && !httpsServer; attempt++) {
@@ -23054,7 +23072,7 @@ function httpsLoaderHint() {
               blocks http://localhost from https, so they need the HTTPS transport.`;
   }
   return `              On https pages load https://localhost:${HTTPS_PORT}/component.js?autoInject=true&serverUrl=wss://localhost:${HTTPS_PORT}/ws/browser
-              (this server's HTTPS port is ephemeral; pass --https-port for a stable one).`;
+              (this server's HTTPS port is ephemeral; pass --https-port <a free port> for a stable one).`;
 }
 console.log(`
   To connect: Visit the server URL and drag the bookmarklet to your toolbar.

package/dist/server.js

@@ -647,7 +647,7 @@ var injectorCode = `
 `;
 
 // src/version.ts
-var VERSION = "1.13.0-beta.2";
+var VERSION = "1.13.0-beta.3";
 
 // src/embedded-assets.ts
 var APP_MD = `# Haltija App
@@ -1369,10 +1369,11 @@ Works with standard forms and most framework components (React, Vue, etc).
 
 Returns a map of the page's affordances. Two tiers, and the difference matters:
 
-**Native (\`source: "tosi-agent"\`) \u2014 EXPERIMENTAL.** haltija detects this tier by duck-typing one
-method and consumes a shape tosijs has not committed to (no version/capability marker yet \u2014 see
-tosijs#23). When the shape isn't what haltija expects it returns a \`warning\` and \`agentSurfaceVersion\`
-rather than passing a blank map off as a success, but treat the tier as best-effort. When the page
+**Native (\`source: "tosi-agent"\`).** haltija reads the contract tosijs ships: the surface's
+\`version\`, \`exposure\` and \`writable\`. A read-only surface is reported as read-only, an empty
+\`'closed'\` surface comes with a hint for the app's author, and a surface version haltija does not
+read produces a \`warning\` and \`agentSurfaceVersion\` rather than a blank map passed off as a
+success. When the page
 exposes an agent surface at
 \`globalThis.tosiAgent\` (a tosijs app calling \`enableAgentInterface()\`), the map is the app's OWN
 wiring records. That carries what the DOM cannot: which state path each control is bound to and in
@@ -3492,9 +3493,9 @@ Two first-party ways to run (plus embedding, below):
     (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
+    package (\`npm i playwright && npx playwright install chromium\`). It is Chromium only,
+    with no engine flag; for Firefox/WebKit launch Playwright yourself (see
+    docs/TEST-IN-BROWSER.md). \`--private\` is an *isolation* modifier (ephemeral port), and
     pairs with either engine: \`--private --app\` (Electron) or \`--private --headless\`
     (Playwright). See the CI guide below.
 
@@ -3623,7 +3624,7 @@ var COMPONENT_JS = `(() => {
   });
 
   // src/version.ts
-  var VERSION = "1.13.0-beta.2";
+  var VERSION = "1.13.0-beta.3";
 
   // src/ws-url.ts
   function httpBaseFromWsUrl(wsUrl2, fallback = "http://localhost:8700") {
@@ -4951,16 +4952,26 @@ var COMPONENT_JS = `(() => {
         const description = agent.describe();
         const wiring = description?.wiring;
         const shapeWarning = wiring === undefined ? \`\${globalName}.describe() returned no 'wiring' \u2014 this haltija understands the agent \` + \`surface as { wiring: [{ tag, id, label, on }] }. The map below is passed through \` + \`unchanged and may be missing structure; the schematic will be empty. Check the \` + \`tosijs version, or use hj map with the DOM fallback (a page without tosiAgent).\` : !Array.isArray(wiring) ? \`\${globalName}.describe().wiring is \${typeof wiring}, expected an array \u2014 passing it \` + \`through unchanged, but the schematic cannot render it.\` : undefined;
+        const d = description;
+        const surfaceVersion = d?.version ?? agent.version;
+        const surfaceMajor = surfaceVersion && typeof surfaceVersion === "object" && typeof surfaceVersion.surface === "string" ? surfaceVersion.surface.split(".")[0] : null;
+        const versionWarning = surfaceMajor !== null && surfaceMajor !== "1" ? \`\${globalName} reports agent surface \${surfaceVersion.surface}; this haltija reads surface \` + \`1.x, so fields may be missing or misread. Update haltija.\` : undefined;
+        const warning = [shapeWarning, versionWarning].filter(Boolean).join(" ") || undefined;
+        const closedHint = d?.exposure === "closed" && Array.isArray(wiring) && wiring.length === 0 ? \`The app exposes no wiring: exposure is 'closed', the tosijs default. Its author enables \` + \`it with expose: { roots } (add write: true to allow write()). Until then, find controls \` + \`with hj tree and drive them with hj click / hj type.\` : undefined;
+        const actions = Array.isArray(d?.actions) ? d.actions : undefined;
+        const writeAdvice = d?.writable === false ? \`This surface is READ-ONLY (describe().writable is false): \${globalName}.write() will be \` + \`refused, so act through actions or realistic input instead.\` : d?.writable === true ? \`\${globalName}.write(path, value) for a \u27F7 two-way binding.\` : \`\${globalName}.write(path, value) for a \u27F7 two-way binding (writability not reported \` + \`by this surface; it may refuse).\`;
+        const callAdvice = actions && actions.length === 0 ? \`It exposes no actions.\` : \`\${globalName}.call(actionPath) for an action\${actions ? \` (one of: \${actions.slice(0, 8).join(", ")}\${actions.length > 8 ? ", \u2026" : ""})\` : ""}.\`;
         return {
           url: location.href,
           title: document.title,
           source: "tosi-agent",
           global: globalName,
-          agentSurfaceVersion: agent.version ?? description?.version,
-          ...shapeWarning ? { warning: shapeWarning } : {},
+          agentSurfaceVersion: surfaceVersion,
+          ...warning ? { warning } : {},
+          ...closedHint ? { hint: closedHint } : {},
           ...description,
           act: {
-            note: \`Act through the paths, not synthesized input: \${globalName}.write(path, value) for a \` + \`\u27F7 two-way binding, \${globalName}.call(actionPath) for an action. \` + \`Run them with: hj eval "\${globalName}.write('some.path', 'value')"\`,
+            note: \`Act through the paths, not synthesized input. \${writeAdvice} \${callAdvice}\` + (actions && actions.length === 0 ? "" : \` Run one with: hj eval "\${globalName}.call('some.action')"\`),
             legend: {
               "\u27F7": "two-way binding \u2014 user-writable; writing the path updates the UI and app state",
               "\u27F5": "bound to DOM \u2014 display only; it reflects the path, writing the DOM will not stick",
@@ -15068,10 +15079,11 @@ var map = endpoint({
   summary: "Affordance map \u2014 what can be interacted with, and what it is wired to",
   description: `Returns a map of the page's affordances. Two tiers, and the difference matters:
 
-**Native (\`source: "tosi-agent"\`) \u2014 EXPERIMENTAL.** haltija detects this tier by duck-typing one
-method and consumes a shape tosijs has not committed to (no version/capability marker yet \u2014 see
-tosijs#23). When the shape isn't what haltija expects it returns a \`warning\` and \`agentSurfaceVersion\`
-rather than passing a blank map off as a success, but treat the tier as best-effort. When the page
+**Native (\`source: "tosi-agent"\`).** haltija reads the contract tosijs ships: the surface's
+\`version\`, \`exposure\` and \`writable\`. A read-only surface is reported as read-only, an empty
+\`'closed'\` surface comes with a hint for the app's author, and a surface version haltija does not
+read produces a \`warning\` and \`agentSurfaceVersion\` rather than a blank map passed off as a
+success. When the page
 exposes an agent surface at
 \`globalThis.tosiAgent\` (a tosijs app calling \`enableAgentInterface()\`), the map is the app's OWN
 wiring records. That carries what the DOM cannot: which state path each control is bound to and in
@@ -22567,12 +22579,12 @@ var serverConfig = {
     }
   }
 };
-async function freePort(port) {
+async function freePort(port, scheme = "http") {
   if (process.env.HALTIJA_NO_RETIRE === "1")
     return false;
   if (listenerPidsOnPort(port).length === 0)
     return false;
-  const probe = await probePort(port);
+  const probe = await probePort(port, scheme);
   if (planFreePort(probe) === "decline") {
     recordMachineAction({
       kind: "declined",
@@ -22580,7 +22592,7 @@ async function freePort(port) {
     });
     return false;
   }
-  if (await requestShutdown(port)) {
+  if (await requestShutdown(port, 3000, scheme)) {
     recordMachineAction({
       kind: "server-stopped",
       detail: `stopped the haltija server on :${port} because this server was explicitly asked to bind that port`
@@ -22609,21 +22621,23 @@ async function freePort(port) {
     Bun.sleepSync(100);
   return killed;
 }
-async function requestShutdown(port, timeoutMs = 3000) {
+async function requestShutdown(port, timeoutMs = 3000, scheme = "http") {
   const authHeaders = REQUIRED_TOKEN ? { "X-Haltija-Token": REQUIRED_TOKEN } : {};
   try {
-    await fetch(`http://localhost:${port}/shutdown`, {
+    await fetch(`${scheme}://localhost:${port}/shutdown`, {
       method: "POST",
       headers: authHeaders,
-      signal: AbortSignal.timeout(1500)
+      signal: AbortSignal.timeout(1500),
+      ...selfSigned(scheme)
     });
   } catch {}
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
     try {
-      await fetch(`http://localhost:${port}/status`, {
+      await fetch(`${scheme}://localhost:${port}/status`, {
         headers: authHeaders,
-        signal: AbortSignal.timeout(500)
+        signal: AbortSignal.timeout(500),
+        ...selfSigned(scheme)
       });
     } catch {
       return true;
@@ -22632,11 +22646,15 @@ async function requestShutdown(port, timeoutMs = 3000) {
   }
   return false;
 }
-async function probePort(port) {
+function selfSigned(scheme) {
+  return scheme === "https" ? { tls: { rejectUnauthorized: false } } : {};
+}
+async function probePort(port, scheme = "http") {
   const unknown = { port, version: null, desktopApp: null, pid: null };
   try {
-    const resp = await fetch(`http://localhost:${port}/status`, {
+    const resp = await fetch(`${scheme}://localhost:${port}/status`, {
       signal: AbortSignal.timeout(1000),
+      ...selfSigned(scheme),
       headers: REQUIRED_TOKEN ? { "X-Haltija-Token": REQUIRED_TOKEN } : {}
     });
     if (!resp.ok)
@@ -22759,7 +22777,7 @@ if (USE_HTTPS) {
       httpsServer = bindHttps();
   } catch (err) {
     if (certFailure(err)) {} else if (err && typeof err === "object" && "code" in err && err.code === "EADDRINUSE") {
-      if (PORT_IS_STRICT && await freePort(wantedHttpsPort)) {
+      if (HTTPS_PORT_EXPLICIT !== null && await freePort(wantedHttpsPort, "https")) {
         httpsServer = bindHttps();
       } else {
         for (let attempt = 0;attempt < 5 && !httpsServer; attempt++) {
@@ -23054,7 +23072,7 @@ function httpsLoaderHint() {
               blocks http://localhost from https, so they need the HTTPS transport.`;
   }
   return `              On https pages load https://localhost:${HTTPS_PORT}/component.js?autoInject=true&serverUrl=wss://localhost:${HTTPS_PORT}/ws/browser
-              (this server's HTTPS port is ephemeral; pass --https-port for a stable one).`;
+              (this server's HTTPS port is ephemeral; pass --https-port <a free port> for a stable one).`;
 }
 console.log(`
   To connect: Visit the server URL and drag the bookmarklet to your toolbar.

package/dist/test-in-browser.d.ts

@@ -53,13 +53,70 @@
  * how it earned this. So the point is scrolled into view first and the coordinate re-based, rather
  * than making every caller remember.
  */
-/** How this talks to a browser. Structural, so any haltija client satisfies it. */
+/**
+ * What `bridge.eval` may resolve to. Getting this wrong was the first outside adopter's first
+ * debugging cycle (tosijs-editor, virta #2415): the type was `Promise<any>`, the natural guess is a
+ * REST-style wrapper, and a wrapper made every probe fail while the probe itself ran perfectly.
+ *
+ * - the VALUE the code evaluated to (a returned Promise already resolved) — the normal case;
+ * - or `{ data: value }`, which is what haltija's own `/eval` answers;
+ * - or `{ success: false, error? }` when the code threw in the page.
+ *
+ * Nothing else. In particular NOT `{ success: true, value }` or `{ result }`.
+ */
+export type BridgeEvalResult = unknown | {
+    data: unknown;
+} | {
+    success: false;
+    error?: string;
+};
+/** What `click` / `type` / `press` may resolve to: anything, or `{ success: false }` to fail. */
+export type BridgeActionResult = unknown | {
+    success: false;
+    error?: string;
+};
+/**
+ * How this talks to a browser: four methods. Structural, so any haltija client satisfies it, and so
+ * does anything else that can run a string of JavaScript in a page — see `playwrightBridge` for
+ * Firefox and WebKit.
+ *
+ * A method may also reject; the rejection reaches the test unchanged.
+ */
 export interface BrowserBridge {
-    eval(code: string): Promise<any>;
-    click(selector: string, options?: any): Promise<any>;
-    type(selector: string, text: string): Promise<any>;
-    press(key: string, modifiers?: any): Promise<any>;
+    /** Run `code` (an expression, possibly an async IIFE) in the page. See `BridgeEvalResult`. */
+    eval(code: string): Promise<BridgeEvalResult>;
+    click(selector: string, options?: any): Promise<BridgeActionResult>;
+    type(selector: string, text: string): Promise<BridgeActionResult>;
+    press(key: string, modifiers?: any): Promise<BridgeActionResult>;
 }
+/** The part of a Playwright `Page` that `playwrightBridge` uses. Structural: no import needed. */
+export interface PlaywrightPageLike {
+    evaluate(expression: string): Promise<unknown>;
+    locator(selector: string): {
+        click(): Promise<unknown>;
+        pressSequentially(text: string): Promise<unknown>;
+    };
+    keyboard: {
+        press(key: string): Promise<unknown>;
+    };
+}
+/**
+ * A bridge over a Playwright page, for the engines haltija does not launch itself (virta #3088).
+ *
+ * `haltija --headless` is Chromium only, and for some questions Chromium is the engine that proves
+ * nothing: tosijs-editor needed WebKit's text shaping, where a Chromium run is all zeros by
+ * construction. They wrote this adapter by hand; three more adopters were about to.
+ *
+ *     const browser = await webkit.launch()
+ *     const page = createBrowserPage(playwrightBridge(await browser.newPage()))
+ *
+ * No haltija server or widget is involved on this path, and that has consequences worth knowing:
+ * `click` and `type` are Playwright's (real input, Playwright's actionability rules), not haltija's
+ * synthetic sequences, and selectors are Playwright's, so haltija's `:text()` extensions do not
+ * apply (Playwright has its own `:text()`). `read`, `clickAt` and `dragFrom` behave the same on
+ * every bridge, because they are plain JavaScript evaluated in the page.
+ */
+export declare function playwrightBridge(page: PlaywrightPageLike): BrowserBridge;
 /**
  * Serialize an expression for the page.
  *

package/dist/test.d.ts

@@ -196,4 +196,4 @@ export declare const hj: HaltijaTestClient;
 /** Create a test client for a custom server URL */
 export declare function createTestClient(serverUrl: string): HaltijaTestClient;
 export type { DevChannelTest, TestRunResult, SuiteRunResult };
-export { createBrowserPage, serializeProbe, BrowserProbeError, assertBrowserTierRan, markBrowserTestRan, browserTestsRan, resetBrowserTestCount, type BrowserPage, type BrowserBridge, } from './test-in-browser';
+export { createBrowserPage, playwrightBridge, serializeProbe, BrowserProbeError, assertBrowserTierRan, markBrowserTestRan, browserTestsRan, resetBrowserTestCount, type BrowserPage, type BrowserBridge, type BridgeEvalResult, type BridgeActionResult, type PlaywrightPageLike, } from './test-in-browser';

package/dist/test.js

@@ -594,6 +594,14 @@ function inferSuggestion(step, pageContext) {
 }
 
 // src/test-in-browser.ts
+function playwrightBridge(page) {
+  return {
+    eval: (code) => page.evaluate(code),
+    click: (selector) => page.locator(selector).click(),
+    type: (selector, text) => page.locator(selector).pressSequentially(text),
+    press: (key) => page.keyboard.press(key)
+  };
+}
 function serializeProbe(fn, args = []) {
   return `(${fn.toString()})(...${JSON.stringify(args)})`;
 }
@@ -651,8 +659,11 @@ function createBrowserPage(bridge) {
       if (!out || typeof out !== "object") {
         throw new BrowserProbeError("probe returned no result \u2014 is a browser connected?", probe);
       }
+      if (!("ok" in out)) {
+        throw new BrowserProbeError(`bridge.eval returned an object without the probe's { ok } envelope (keys: ${Object.keys(out).join(", ") || "none"}). ` + "It must return the VALUE the code evaluated to, optionally as { data: value }, not a wrapper of its own.", probe);
+      }
       if (!out.ok)
-        throw new BrowserProbeError(out.error || "probe threw", probe);
+        throw new BrowserProbeError(out.error || "probe threw, with no message", probe);
       return out.value;
     },
     async click(selector) {
@@ -1015,6 +1026,7 @@ export {
   createTestClient,
   hj,
   markBrowserTestRan,
+  playwrightBridge,
   resetBrowserTestCount,
   resolveTestServerUrl,
   serializeProbe,

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.13.0-beta.2";
+export declare const VERSION = "1.13.0-beta.3";

package/docs/CI-INTEGRATION.md

@@ -104,11 +104,11 @@ picking by the words "for CI" alone leads people to the wrong one:
 | --- | --- | --- | --- |
 | 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`) |
+| A lighter single-engine run | `--headless` | **Playwright** Chromium (Chromium only) | 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
+is **Electron vs. Playwright**, not "deps vs. no deps". Both are Chromium: `--headless` does
+not give you Firefox or WebKit (see Option 3). 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).
@@ -133,7 +133,7 @@ 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 (multi-engine)
+### Option 3: Playwright headless (Chromium)
 
 ```bash
 npm install playwright && npx playwright install chromium   # required — not bundled
@@ -142,9 +142,13 @@ bunx haltija@latest --headless &
 
 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`).
+points you back to `--ci`). Choose this when you want a lighter run than Electron. For a plain
+Chromium lane with no extra install, prefer Option 1 (`--ci`).
+
+**`--headless` is Chromium only; it has no engine flag.** Earlier versions of this page said to pick
+it for Firefox/WebKit coverage, which it has never provided. For those engines, launch Playwright
+yourself: host-side tests reach the page through `playwrightBridge`
+([TEST-IN-BROWSER.md](TEST-IN-BROWSER.md)), and no haltija server is involved.
 
 ### Option 4: Server-only mode (lighter weight)
 

package/docs/TEST-IN-BROWSER.md

@@ -0,0 +1,142 @@
+# Browser tests with the host's `expect` (`testInBrowser`)
+
+Tests whose **assertions run on the host** (an ordinary `bun:test` or vitest file, with its real
+`expect`) and whose **probes run in a real browser**. A probe is the small function you pass to
+`read()`: it is the only thing sent to the page, and everything else in the test is an ordinary
+closure. The package is ESM only.
+
+The API is `createBrowserPage(bridge)`, where a *bridge* is whatever can run JavaScript in a page:
+a haltija client, or a Playwright page.
+
+## Before the first example runs
+
+`npm i -D haltija`. A haltija client needs three things: a haltija server, a browser connected to it
+(a page with haltija's widget in it), and that browser on the page under test.
+
+```bash
+npm i -D playwright && npx playwright install chromium
+bunx haltija --private --headless     # prints HALTIJA_PRIVATE_READY {"port": …}
+HALTIJA_PORT=<that port> bun test
+```
+
+**Always name your server** (`HALTIJA_PORT`, `HALTIJA_URL`, or `createTestClient(url)`). With none
+of them, `hj` targets the machine's shared `localhost:8700`. There, `click`, `type`, `press` and
+`navigate` refuse to run, but `read`, `clickAt` and `dragFrom` do run, against whatever tab is
+focused, which may be someone else's.
+
+```ts
+import { test, expect, beforeAll, afterAll } from 'bun:test'
+import { hj, createBrowserPage, markBrowserTestRan, assertBrowserTierRan } from 'haltija/test'
+
+const page = createBrowserPage(hj) // hj reads HALTIJA_PORT; or createTestClient('http://localhost:9123')
+
+beforeAll(() => hj.navigate('http://localhost:3000/slider'))
+
+test('the handle drags', async () => {
+  markBrowserTestRan()
+  // The app's own drag handle, 40px to the right. Start 5px inside its corner.
+  const box = await page.read(() => document.querySelector('#handle')!.getBoundingClientRect().toJSON())
+  await page.dragFrom(box.x + 5, box.y + 5, 40, 0)
+  expect(await page.read(() => document.querySelector('#readout')!.textContent)).toBe('40')
+})
+
+afterAll(() => assertBrowserTierRan())
+```
+
+`markBrowserTestRan()` counts a test, and `assertBrowserTierRan(minimum = 1)` throws if fewer than
+`minimum` were counted. A suite that silently ran nothing has no failures, so without this it
+passes.
+
+`read(fn, args)` re-parses `fn` in the page, so it cannot see the test's variables. `args` is an
+array spread into `fn`'s parameters: `page.read((a, b) => a + b, [2, 3])`. Return JSON-serializable
+values. (Using `document` in a test file needs the `dom` lib in your tsconfig.)
+
+`page` has `read`, `click`, `type`, `press`, and the coordinate actions `clickAt(x, y)` and
+`dragFrom(x, y, dx, dy, steps?)` for UI with no selectable element. Coordinates are
+viewport-relative, as `getBoundingClientRect()` reports them; a point below the fold is scrolled
+into view first. The coordinate actions dispatch synthetic pointer and mouse events, on every
+bridge. They drive handlers your code attached; they do not move a native control such as
+`<input type=range>`.
+
+## When it fails
+
+| Cause | What you get |
+| --- | --- |
+| the probe threw in the page | `BrowserProbeError` (exported) with the page's message; `.probe` holds the source that was sent |
+| `clickAt` / `dragFrom` hit nothing | `BrowserProbeError`: "nothing at (x, y) even after scrolling it into view", or "(x, y) is outside the document" |
+| no server | the `fetch` connection error |
+| server up, no browser connected | an `Error` carrying the server's message |
+| no tests counted | `assertBrowserTierRan` throws |
+
+## Which engine?
+
+| Bridge | Engines | What `click` / `type` are |
+| --- | --- | --- |
+| a haltija client (`hj`, `createTestClient(url)`) | whatever browser has the widget: the desktop app, `haltija --headless` (**Chromium only**), or any tab you injected it into | haltija's realistic synthetic sequences; haltija selectors, including `:text()` |
+| `playwrightBridge(page)` | Chromium, Firefox, **WebKit** | Playwright's real input and Playwright's selectors |
+
+`press` differs more than the others. Through a haltija client it is a single synthetic `keydown`
+dispatched at `body`: no `keyup`, and not aimed at the focused element. Through Playwright it is a
+real key press.
+
+`read`, `clickAt` and `dragFrom` run the same JavaScript in the page on both. Return values can
+differ at the edges: a haltija client returns JSON, while Playwright's own serialization also
+carries `undefined`, `NaN` and `Date`.
+
+### Firefox and WebKit: `playwrightBridge`
+
+`haltija --headless` launches Chromium and has no engine flag. For another engine, launch it with
+Playwright yourself and hand the page to the bridge. No haltija server is involved.
+
+```bash
+npm i -D playwright && npx playwright install webkit
+```
+
+```ts
+import { test, expect, afterAll } from 'bun:test' // an ordinary test file; @playwright/test is not needed
+import { webkit } from 'playwright'
+import { createBrowserPage, playwrightBridge } from 'haltija/test'
+
+const browser = await webkit.launch()
+const pw = await browser.newPage()
+await pw.goto('http://localhost:3000')
+const page = createBrowserPage(playwrightBridge(pw))
+
+test('the heading renders', async () => {
+  expect(await page.read(() => document.querySelector('h1')!.getBoundingClientRect().width)).toBeGreaterThan(0)
+})
+
+afterAll(() => browser.close())
+```
+
+`clickAt` and `dragFrom` are still synthetic events here. For real mouse input, use `pw.mouse`
+directly; the Playwright page is yours.
+
+## Writing your own bridge
+
+A bridge is four methods:
+
+```ts
+interface BrowserBridge {
+  eval(code: string): Promise<BridgeEvalResult>
+  click(selector: string): Promise<BridgeActionResult>
+  type(selector: string, text: string): Promise<BridgeActionResult>
+  press(key: string): Promise<BridgeActionResult>
+}
+```
+
+**`eval` must resolve to the value the code evaluated to** (with a returned Promise already
+resolved). Two other shapes are accepted: `{ data: value }`, and `{ success: false, error }` when
+the code threw. Do not invent a wrapper such as `{ success: true, value }`: the probe will have run
+correctly and every `read()` will fail, with an error saying the bridge returned no `{ ok }`
+envelope.
+
+`click`, `type` and `press` may resolve to anything; `{ success: false, error }` fails the step. Any
+method may reject instead.
+
+## One measuring trap
+
+Measure rendered boxes only (`getBoundingClientRect().width > 0`). Collapsed whitespace and custom
+elements that have not upgraded report a zero rect, and a zero rect compared with an earlier
+non-zero one reads as a large layout shift. tosijs-editor measured a 1058px shift this way, in two
+engines, that did not exist.

package/llms.txt

@@ -61,9 +61,9 @@ Two first-party ways to run (plus embedding, below):
     (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
+    package (`npm i playwright && npx playwright install chromium`). It is Chromium only,
+    with no engine flag; for Firefox/WebKit launch Playwright yourself (see
+    docs/TEST-IN-BROWSER.md). `--private` is an *isolation* modifier (ephemeral port), and
     pairs with either engine: `--private --app` (Electron) or `--private --headless`
     (Playwright). See the CI guide below.
 

package/package.json

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