haltija 1.12.0 → 1.12.1

package/CHANGELOG.md

@@ -1,5 +1,96 @@
 # Changelog
 
+## 1.12.1
+
+A patch of fixes reported by an agent driving a real React + web-components admin app against
+1.12.0 — the kind of surface no fixture reproduces. Four of the five below are cases where haltija
+answered confidently and wrongly, which is the same thread 1.12.0 was pulling on.
+
+**Still open: [#26](https://github.com/tonioloewald/haltija/issues/26)** — tabs reportedly
+disconnect permanently on webpack-dev-server (CRA) origins in 1.12.0, and rc.5 is unaffected. It is
+**not fixed here**, because I could not reproduce it: a real webpack-dev-server (v5 client, `hot` +
+`liveReload`) survived on both 1.12.0 and the rc.5 widget, the opposite of the reporter's A/B. The
+re-injection fix below may cover it and may not. If you drive a CRA dev server, test before you rely
+on this release, and please add to that issue.
+
+
+### Text selectors pick the element you could actually click — [#27](https://github.com/tonioloewald/haltija/issues/27)
+
+Two ways the same selector chose the wrong element, both found driving a real admin app:
+
+- **A hidden duplicate that came first won.** `click` took the first match in DOM order and left the
+  visibility gate to complain afterwards, so a `display:none` copy made `hj click ':text(Save
+  Changes)'` fail with "zero-size bounding rect" while the visible copy sat right there — and
+  `hj find`, which filters before choosing, returned the right one. One selector, two answers.
+- **An off-canvas element was clicked silently.** The `position:absolute; left:-9999px` skip-link
+  idiom has a perfectly normal box (measured: 99x35 at x=-9999), so every size and style check
+  passed it. `click` actuated an element no human can see and reported **success** — a script then
+  asserts against a state it never produced. This is the worse of the two: it fails confidently.
+
+Resolution now filters *before* choosing, and `find` and `click` share one predicate so they cannot
+disagree. An off-canvas element that is the ONLY match fails loudly (`positioned off-canvas`) rather
+than being clicked invisibly.
+
+Off-canvas is measured in **page** coordinates, so content merely **below the fold** is unaffected —
+visible still means *rendered*, not *on screen*. That is also why `elementFromPoint` isn't used
+here despite catching this case: it rejects everything scrolled out of view, which would fail
+legitimate content in a small headless viewport.
+
+### `hj doctor` probes requestAnimationFrame — [#28](https://github.com/tonioloewald/haltija/issues/28)
+
+**A tab can report `visibilityState: "visible"` and still not be compositing.** Occluded windows,
+offscreen windows and a sleeping display all do it. Nothing rAF-driven then renders — React's
+scheduler, tosijs `queueRender`, animations, virtual scrollers — while geometry probes keep
+returning real numbers, so the absence of an element stops being evidence of anything.
+
+That doesn't merely hide information, it manufactures a plausible wrong answer. The reporter found
+four routes "not mounting" on hard navigation, had a coherent mechanism (the router gates its first
+mount on rAF), reproduced it four times, and nearly filed it as an application bug. Opening a second
+tab fixed all four.
+
+`hj doctor` now measures it directly and fails with `requestAnimationFrame DID NOT FIRE within 2s`.
+If the probe itself can't run, that is reported as **unchecked** — never as a pass — and the probe
+is bounded at 3s so a pre-flight can't hang on a socket that never answers.
+
+### `hj tabs` — the array is `windows`, and a `tabs` alias now exists ([#29](https://github.com/tonioloewald/haltija/issues/29))
+
+`d['tabs']` KeyError'd because the payload key is `windows` — accurate, since the list holds popups
+and iframes too, but the command is `hj tabs`, so the obvious guess failed and it looked like the
+caller's bug. `tabs` is now sent as an alias of the same array. The hint no longer mixes the two
+vocabularies in one sentence ("Multiple **tabs** connected. Use `?window=<id>`"), which is where the
+wrong idea came from.
+
+Popups being indistinguishable from user-opened tabs, the other half of that report, is fixed by the
+popup work below: they carry `windowType: "popup"` and never take focus.
+
+### Popups are popups again (desktop app) — [#25](https://github.com/tonioloewald/haltija/issues/25)
+
+A page calling `window.open(url, name, 'width=...')` now gets a genuine popup: `window.open()`
+returns a real `WindowProxy`, the child has `window.opener`, and `opener.postMessage(...)` reaches
+the parent.
+
+Previously the desktop app decided by **guessing from the URL** — allow if it contained `oauth`,
+`signin`, `login`, `accounts.google.com` or `/__/auth/`; deny everything else and re-open it as a
+tab, which severs the opener in both directions. `window.open()` returned `null` and the child had
+no `opener`. That is the shape of every OAuth popup flow: the SDK keeps the returned window to poll
+`.closed` and to `.close()`, and the callback page delivers its credential via `opener.postMessage`.
+With neither, a user can complete a sign-in in a window that cannot report back and the app just
+waits — arguably worse than a clean block.
+
+The heuristic failed both ways: an innocent `/login-help` page became a popup, while the common SDK
+pattern of opening `about:blank` and *then* navigating matched nothing and was denied — the very
+case the list existed to catch. The decision now keys on Electron's `disposition`, which is what the
+page actually asked for, so there is nothing to guess.
+
+Two things come free, because the window model already handled popups correctly: the popup registers
+as `windowType: "popup"` (tellable from a user-opened tab) and it **does not steal focus**, so
+untargeted commands keep going to the tab you were driving.
+
+Ordinary `<a target="_blank">` links still open as tabs in the app's tab strip — that behaviour is
+deliberate and unchanged. **Known residual:** a featureless `window.open(url, '_blank')` is
+indistinguishable from a `target="_blank"` link at this layer (both report `foreground-tab`), so it
+still becomes a tab and still returns `null`.
+
 ## 1.12.0 — trustworthy by default
 
 **Trustworthy by default.** A minor, gated on the nine-lens pre-release review: every finding it

package/apps/desktop/main.js

@@ -690,28 +690,47 @@ function setupWebContentsInjection(wc) {
 
   console.log('[Haltija Desktop] Monitoring webContents:', wc.id, wc.getType())
 
-  // Intercept window.open() calls - redirect to tabs instead of new windows
-  // Exception: allow auth popups which need to close and callback
-  wc.setWindowOpenHandler(({ url, frameName, features }) => {
-    console.log('[Haltija Desktop] Intercepted window.open:', url)
-
-    // Allow OAuth/auth popups - they need popup behavior to work
-    const isAuthPopup =
-      url.includes('accounts.google.com') ||
-      url.includes('/__/auth/') ||
-      url.includes('/emulator/auth') ||
-      url.includes('firebaseapp.com/__/auth') ||
-      url.includes('oauth') ||
-      url.includes('signin') ||
-      url.includes('login') ||
-      frameName === 'firebaseAuth'
-
-    if (isAuthPopup) {
-      console.log('[Haltija Desktop] Allowing auth popup:', url)
+  // Intercept window.open(): a genuine POPUP stays a popup; an ordinary new-window link becomes a
+  // tab in our own tab strip.
+  //
+  // This used to decide by GUESSING FROM THE URL — allow if it contained `oauth`, `signin`,
+  // `login`, `accounts.google.com`, `/__/auth/`. Everything else was denied and re-opened as a tab,
+  // which severs the opener relationship in both directions: `window.open()` returns **null** and
+  // the child has no `window.opener`. That is the shape of every OAuth popup flow (issue #25):
+  // an SDK keeps the returned WindowProxy to poll `.closed` and to `.close()`, and the callback
+  // page delivers its credential via `opener.postMessage(...)`. With neither, the user can complete
+  // a sign-in in a window that cannot report back — worse than a clean block, because the app just
+  // waits.
+  //
+  // The heuristic failed in both directions: an innocent `/login-help` page became a popup, while
+  // the common SDK pattern of opening `about:blank` and *then* navigating matched nothing and was
+  // denied — the case the list was written to catch.
+  //
+  // `disposition` is what the page actually asked for, so there is nothing to guess (verified
+  // against Electron):
+  //   window.open(url, name, 'width=420,height=320')  -> 'new-window'     features: "width=..."
+  //   window.open(url, '_blank')                      -> 'foreground-tab' features: ""
+  //   <a target="_blank">                             -> 'foreground-tab' features: ""
+  //
+  // Allowing a real popup also fixes two things for free, because the window model already handles
+  // popups correctly: it registers as `windowType: "popup"` (so scripts can tell it from a
+  // user-opened tab) and it does NOT steal focus, since only real tabs become the untargeted
+  // command target.
+  //
+  // KNOWN RESIDUAL: a featureless `window.open(url, '_blank')` is indistinguishable from a
+  // `target="_blank"` link at this layer — both report 'foreground-tab' — so it still becomes a tab
+  // and still returns null. Preserving the tab UX for ordinary links is worth that; if an SDK turns
+  // up that opens featureless popups and needs the opener, this is the line to revisit.
+  wc.setWindowOpenHandler((details) => {
+    const { url, disposition } = details
+    console.log('[Haltija Desktop] Intercepted window.open:', url, `(disposition: ${disposition})`)
+
+    if (disposition === 'new-window') {
+      console.log('[Haltija Desktop] Genuine popup — preserving the opener relationship:', url)
       return { action: 'allow' }
     }
 
-    // Regular links: open as new tab instead of window
+    // Ordinary new-window link: open as a tab instead.
     if (mainWindow && mainWindow.webContents) {
       mainWindow.webContents.send('open-url-in-tab', url)
     }

package/apps/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haltija-desktop",
-  "version": "1.12.0",
+  "version": "1.12.1",
   "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.12.0";
+  var VERSION = "1.12.1";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;
@@ -624,6 +624,19 @@
     const candidates = queryAllDeep(parsed.baseSelector).filter((el) => !NON_RENDERED_TEXT.has(el.tagName) && elementTextMatches(el, parsed));
     return candidates.filter((el) => !candidates.some((other) => other !== el && containsDeep(el, other)));
   }
+  function isOffCanvas(el) {
+    const r = el.getBoundingClientRect();
+    return r.right + window.scrollX <= 0 || r.bottom + window.scrollY <= 0;
+  }
+  function isActionable(el) {
+    const cs = getComputedStyle(el);
+    if (cs.display === "none" || cs.visibility === "hidden" || cs.opacity === "0")
+      return false;
+    const r = el.getBoundingClientRect();
+    if (r.width <= 0 || r.height <= 0)
+      return false;
+    return !isOffCanvas(el);
+  }
   function resolveSelector(selector) {
     if (!TEXT_PSEUDO_RE.test(selector)) {
       return document.querySelector(selector) || queryAllDeep(selector)[0] || null;
@@ -631,7 +644,8 @@
     const parsed = parseTextSelector(selector);
     if (!parsed)
       return document.querySelector(selector);
-    return textMatchesInDocument(parsed)[0] || null;
+    const matches = textMatchesInDocument(parsed);
+    return matches.find(isActionable) || matches[0] || null;
   }
   function resolveSelectorAll(selector) {
     if (!TEXT_PSEUDO_RE.test(selector)) {
@@ -5027,6 +5041,9 @@ ${elementSummary}${moreText}`;
       }
       this.render();
     }
+    get isDefunct() {
+      return this.killed;
+    }
     kill() {
       this.killed = true;
       hideHighlight();
@@ -7555,6 +7572,9 @@ ${elementSummary}${moreText}`;
       };
     }
     getHiddenReason(el) {
+      if (isOffCanvas(el)) {
+        return "positioned off-canvas (e.g. left:-9999px) — rendered but not reachable by a user";
+      }
       const rect = el.getBoundingClientRect();
       if (rect.width === 0 && rect.height === 0) {
         return "zero-size bounding rect (element not rendered or in hidden container)";
@@ -8711,6 +8731,7 @@ ${elementSummary}${moreText}`;
     currentTagName = TAG_NAME;
     window.__haltija_resolveSelector = resolveSelector;
     window.__haltija_resolveSelectorAll = resolveSelectorAll;
+    window.__haltija_isActionable = isActionable;
     window.__haltija_refRegistry = refRegistry;
   }
   registerDevChannel();
@@ -8723,6 +8744,9 @@ ${elementSummary}${moreText}`;
       if (existingVersion !== VERSION2) {
         console.log(`${LOG_PREFIX} Version mismatch (${existingVersion} -> ${VERSION2}), replacing`);
         existing.remove();
+      } else if (existing.isDefunct) {
+        console.log(`${LOG_PREFIX} Existing widget is defunct (killed), replacing`);
+        existing.remove();
       } else {
         return existing;
       }

package/bin/hj.mjs

@@ -357,6 +357,58 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
     if (status.serverVersion && differsBeyondPatch(HJ_VERSION, status.serverVersion)) {
       notes.push(`hj ${HJ_VERSION} is driving server ${status.serverVersion} (version skew)`)
     }
+
+    // Does this tab actually PAINT? `visibilityState` answers "is this tab selected", not "is this
+    // tab being composited", and the two diverge for occluded windows, offscreen windows and a
+    // sleeping display. A starved tab renders nothing while reporting `visible`, geometry probes
+    // still return real numbers, and the absence of an element stops being evidence of anything.
+    //
+    // That is worse than a missing feature: it invites a plausible code-level explanation. An agent
+    // driving a React app found four routes "not mounting" on hard navigation, had a coherent
+    // mechanism (the router gates its first mount on rAF), reproduced it four times, and nearly
+    // filed it as an application bug. Opening a second tab fixed all four (#28). This check is here
+    // to convert that silent, confidently-wrong outcome into a visible one.
+    if (ready && tabs.length) {
+      const probe =
+        `new Promise(r => { const s = Date.now();` +
+        ` const t = setTimeout(() => r({ fired: false, ms: Date.now() - s }), 2000);` +
+        ` requestAnimationFrame(() => { clearTimeout(t); r({ fired: true, ms: Date.now() - s }) }) })`
+      let raf = null
+      try {
+        // BOUND IT. The probe resolves in ~2s at the latest when a browser is there to answer, so a
+        // longer wait means nothing is coming — and doctor is a pre-flight: a lane runs it to find
+        // out quickly, not to sit through another component's timeout. Without this, a connected
+        // 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`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', ...(token ? { 'X-Haltija-Token': token } : {}) },
+          body: JSON.stringify({ code: probe }),
+          signal: cancel,
+        })
+        if (r.ok) {
+          const j = await r.json()
+          if (j && j.success && j.data && typeof j.data.fired === 'boolean') raf = j.data
+        }
+      } catch {
+        // Fall through to the unchecked branch — never a pass.
+      }
+      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) {
+        problems.push(
+          `requestAnimationFrame DID NOT FIRE within 2s — this tab is not compositing, even though ` +
+            `it reports visibilityState "visible". Anything rAF-driven (React's scheduler, tosijs ` +
+            `queueRender, animations, virtual scrollers) will never render, so a missing element ` +
+            `is NOT evidence of an application bug. Bring a window to the front, or wake the ` +
+            `display, and re-run.`,
+        )
+      }
+    }
     // Declared origins decide WHICH tab answers. A broken declaration silently disables the
     // routing it configures, and doctor is where a CI lane finds out.
     const origins = describeOrigins(tabs)

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.12.0'
+export const HJ_VERSION = '1.12.1'

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.12.0";
+export declare const VERSION = "1.12.1";
 export declare class DevChannel extends HTMLElement {
     static get tagName(): string;
     static elementCreator(): () => DevChannel;
@@ -195,6 +195,14 @@ export declare class DevChannel extends HTMLElement {
     private stopScreenCapture;
     private toggleMinimize;
     private togglePause;
+    /**
+     * Can this widget never talk to the server again?
+     *
+     * `killed` is set when the element is removed from the DOM or `kill()` runs, and it permanently
+     * stops the 3-second reconnect loop. An ordinary disconnected socket is NOT defunct — that retries
+     * forever and heals itself, so callers must not treat it as dead.
+     */
+    get isDefunct(): boolean;
     private kill;
     private testRecordingHandler;
     private toggleTestRecording;

package/dist/component.esm.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var VERSION = "1.12.0";
+var VERSION = "1.12.1";
 
 // src/text-selector.ts
 var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;
@@ -577,6 +577,19 @@ function textMatchesInDocument(parsed) {
   const candidates = queryAllDeep(parsed.baseSelector).filter((el) => !NON_RENDERED_TEXT.has(el.tagName) && elementTextMatches(el, parsed));
   return candidates.filter((el) => !candidates.some((other) => other !== el && containsDeep(el, other)));
 }
+function isOffCanvas(el) {
+  const r = el.getBoundingClientRect();
+  return r.right + window.scrollX <= 0 || r.bottom + window.scrollY <= 0;
+}
+function isActionable(el) {
+  const cs = getComputedStyle(el);
+  if (cs.display === "none" || cs.visibility === "hidden" || cs.opacity === "0")
+    return false;
+  const r = el.getBoundingClientRect();
+  if (r.width <= 0 || r.height <= 0)
+    return false;
+  return !isOffCanvas(el);
+}
 function resolveSelector(selector) {
   if (!TEXT_PSEUDO_RE.test(selector)) {
     return document.querySelector(selector) || queryAllDeep(selector)[0] || null;
@@ -584,7 +597,8 @@ function resolveSelector(selector) {
   const parsed = parseTextSelector(selector);
   if (!parsed)
     return document.querySelector(selector);
-  return textMatchesInDocument(parsed)[0] || null;
+  const matches = textMatchesInDocument(parsed);
+  return matches.find(isActionable) || matches[0] || null;
 }
 function resolveSelectorAll(selector) {
   if (!TEXT_PSEUDO_RE.test(selector)) {
@@ -4980,6 +4994,9 @@ ${elementSummary}${moreText}`;
     }
     this.render();
   }
+  get isDefunct() {
+    return this.killed;
+  }
   kill() {
     this.killed = true;
     hideHighlight();
@@ -7508,6 +7525,9 @@ ${elementSummary}${moreText}`;
     };
   }
   getHiddenReason(el) {
+    if (isOffCanvas(el)) {
+      return "positioned off-canvas (e.g. left:-9999px) — rendered but not reachable by a user";
+    }
     const rect = el.getBoundingClientRect();
     if (rect.width === 0 && rect.height === 0) {
       return "zero-size bounding rect (element not rendered or in hidden container)";
@@ -8664,6 +8684,7 @@ function registerDevChannel() {
   currentTagName = TAG_NAME;
   window.__haltija_resolveSelector = resolveSelector;
   window.__haltija_resolveSelectorAll = resolveSelectorAll;
+  window.__haltija_isActionable = isActionable;
   window.__haltija_refRegistry = refRegistry;
 }
 registerDevChannel();
@@ -8676,6 +8697,9 @@ function inject(serverUrl2 = "wss://localhost:8700/ws/browser", options) {
     if (existingVersion !== VERSION2) {
       console.log(`${LOG_PREFIX} Version mismatch (${existingVersion} -> ${VERSION2}), replacing`);
       existing.remove();
+    } else if (existing.isDefunct) {
+      console.log(`${LOG_PREFIX} Existing widget is defunct (killed), replacing`);
+      existing.remove();
     } else {
       return existing;
     }

package/dist/component.js

@@ -46,7 +46,7 @@
   });
 
   // src/version.ts
-  var VERSION = "1.12.0";
+  var VERSION = "1.12.1";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;
@@ -624,6 +624,19 @@
     const candidates = queryAllDeep(parsed.baseSelector).filter((el) => !NON_RENDERED_TEXT.has(el.tagName) && elementTextMatches(el, parsed));
     return candidates.filter((el) => !candidates.some((other) => other !== el && containsDeep(el, other)));
   }
+  function isOffCanvas(el) {
+    const r = el.getBoundingClientRect();
+    return r.right + window.scrollX <= 0 || r.bottom + window.scrollY <= 0;
+  }
+  function isActionable(el) {
+    const cs = getComputedStyle(el);
+    if (cs.display === "none" || cs.visibility === "hidden" || cs.opacity === "0")
+      return false;
+    const r = el.getBoundingClientRect();
+    if (r.width <= 0 || r.height <= 0)
+      return false;
+    return !isOffCanvas(el);
+  }
   function resolveSelector(selector) {
     if (!TEXT_PSEUDO_RE.test(selector)) {
       return document.querySelector(selector) || queryAllDeep(selector)[0] || null;
@@ -631,7 +644,8 @@
     const parsed = parseTextSelector(selector);
     if (!parsed)
       return document.querySelector(selector);
-    return textMatchesInDocument(parsed)[0] || null;
+    const matches = textMatchesInDocument(parsed);
+    return matches.find(isActionable) || matches[0] || null;
   }
   function resolveSelectorAll(selector) {
     if (!TEXT_PSEUDO_RE.test(selector)) {
@@ -5027,6 +5041,9 @@ ${elementSummary}${moreText}`;
       }
       this.render();
     }
+    get isDefunct() {
+      return this.killed;
+    }
     kill() {
       this.killed = true;
       hideHighlight();
@@ -7555,6 +7572,9 @@ ${elementSummary}${moreText}`;
       };
     }
     getHiddenReason(el) {
+      if (isOffCanvas(el)) {
+        return "positioned off-canvas (e.g. left:-9999px) — rendered but not reachable by a user";
+      }
       const rect = el.getBoundingClientRect();
       if (rect.width === 0 && rect.height === 0) {
         return "zero-size bounding rect (element not rendered or in hidden container)";
@@ -8711,6 +8731,7 @@ ${elementSummary}${moreText}`;
     currentTagName = TAG_NAME;
     window.__haltija_resolveSelector = resolveSelector;
     window.__haltija_resolveSelectorAll = resolveSelectorAll;
+    window.__haltija_isActionable = isActionable;
     window.__haltija_refRegistry = refRegistry;
   }
   registerDevChannel();
@@ -8723,6 +8744,9 @@ ${elementSummary}${moreText}`;
       if (existingVersion !== VERSION2) {
         console.log(`${LOG_PREFIX} Version mismatch (${existingVersion} -> ${VERSION2}), replacing`);
         existing.remove();
+      } else if (existing.isDefunct) {
+        console.log(`${LOG_PREFIX} Existing widget is defunct (killed), replacing`);
+        existing.remove();
       } else {
         return existing;
       }

package/dist/hj.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-// haltija-cli:do-not-edit v1.12.0
+// haltija-cli:do-not-edit v1.12.1
 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.12.0";
+var HJ_VERSION = "1.12.1";
 
 // bin/semver.mjs
 function parseVersion(v) {
@@ -2676,6 +2676,29 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
     if (status.serverVersion && differsBeyondPatch(HJ_VERSION, status.serverVersion)) {
       notes.push(`hj ${HJ_VERSION} is driving server ${status.serverVersion} (version skew)`);
     }
+    if (ready && tabs.length) {
+      const probe = `new Promise(r => { const s = Date.now();` + ` const t = setTimeout(() => r({ fired: false, ms: Date.now() - s }), 2000);` + ` requestAnimationFrame(() => { clearTimeout(t); r({ fired: true, ms: Date.now() - s }) }) })`;
+      let raf = null;
+      try {
+        const cancel = AbortSignal.timeout(3000);
+        const r = await fetch(`http://localhost:${port}/eval`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json", ...token ? { "X-Haltija-Token": token } : {} },
+          body: JSON.stringify({ code: probe }),
+          signal: cancel
+        });
+        if (r.ok) {
+          const j = await r.json();
+          if (j && j.success && j.data && typeof j.data.fired === "boolean")
+            raf = j.data;
+        }
+      } catch {}
+      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) {
+        problems.push(`requestAnimationFrame DID NOT FIRE within 2s — this tab is not compositing, even though ` + `it reports visibilityState "visible". Anything rAF-driven (React's scheduler, tosijs ` + `queueRender, animations, virtual scrollers) will never render, so a missing element ` + `is NOT evidence of an application bug. Bring a window to the front, or wake the ` + `display, and re-run.`);
+      }
+    }
     const origins = describeOrigins(tabs);
     if (origins.problem)
       problems.push(origins.problem);

package/dist/index.js

@@ -674,7 +674,7 @@ var injectorCode = `
 `;
 
 // src/version.ts
-var VERSION = "1.12.0";
+var VERSION = "1.12.1";
 
 // src/embedded-assets.ts
 var APP_MD = `# Haltija App
@@ -2251,7 +2251,15 @@ Deprecated: Use POST /select {"action":"clear"} instead.
 
 Returns all connected browser windows/tabs with IDs, URLs, and titles.
 
-Response: { windows: [{ id, url, title, focused, active, hidden, windowType }], count, ready, hint }
+Response: { windows: [{ id, url, title, focused, active, hidden, windowType }], tabs, count, ready, hint }
+
+The array is **\`windows\`**, not \`tabs\` \u2014 it includes popups (\`windowType: "popup"\`) and
+iframes (\`"iframe"\`), not only tabs. Because the CLI command is \`hj tabs\`, \`d['tabs']\` is the
+natural first guess and used to KeyError, so **\`tabs\` is also sent as an alias** of the same
+array. Prefer \`windows\`; \`tabs\` exists so the obvious guess works.
+
+Only real tabs can be the target of an UNTARGETED command \u2014 a popup or iframe never becomes
+\`focused\`, so a page opening a popup cannot silently re-route your commands.
 
 \`active\` and \`hidden\` are exact inverses, and BOTH are sent on purpose: /status historically
 emitted only \`hidden\` and /windows only \`active\`, so code moving between the two silently
@@ -3441,7 +3449,7 @@ var COMPONENT_JS = `(() => {
   });
 
   // src/version.ts
-  var VERSION = "1.12.0";
+  var VERSION = "1.12.1";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\\(/;
@@ -4019,6 +4027,19 @@ var COMPONENT_JS = `(() => {
     const candidates = queryAllDeep(parsed.baseSelector).filter((el) => !NON_RENDERED_TEXT.has(el.tagName) && elementTextMatches(el, parsed));
     return candidates.filter((el) => !candidates.some((other) => other !== el && containsDeep(el, other)));
   }
+  function isOffCanvas(el) {
+    const r = el.getBoundingClientRect();
+    return r.right + window.scrollX <= 0 || r.bottom + window.scrollY <= 0;
+  }
+  function isActionable(el) {
+    const cs = getComputedStyle(el);
+    if (cs.display === "none" || cs.visibility === "hidden" || cs.opacity === "0")
+      return false;
+    const r = el.getBoundingClientRect();
+    if (r.width <= 0 || r.height <= 0)
+      return false;
+    return !isOffCanvas(el);
+  }
   function resolveSelector(selector) {
     if (!TEXT_PSEUDO_RE.test(selector)) {
       return document.querySelector(selector) || queryAllDeep(selector)[0] || null;
@@ -4026,7 +4047,8 @@ var COMPONENT_JS = `(() => {
     const parsed = parseTextSelector(selector);
     if (!parsed)
       return document.querySelector(selector);
-    return textMatchesInDocument(parsed)[0] || null;
+    const matches = textMatchesInDocument(parsed);
+    return matches.find(isActionable) || matches[0] || null;
   }
   function resolveSelectorAll(selector) {
     if (!TEXT_PSEUDO_RE.test(selector)) {
@@ -8422,6 +8444,9 @@ var COMPONENT_JS = `(() => {
       }
       this.render();
     }
+    get isDefunct() {
+      return this.killed;
+    }
     kill() {
       this.killed = true;
       hideHighlight();
@@ -10950,6 +10975,9 @@ var COMPONENT_JS = `(() => {
       };
     }
     getHiddenReason(el) {
+      if (isOffCanvas(el)) {
+        return "positioned off-canvas (e.g. left:-9999px) \u2014 rendered but not reachable by a user";
+      }
       const rect = el.getBoundingClientRect();
       if (rect.width === 0 && rect.height === 0) {
         return "zero-size bounding rect (element not rendered or in hidden container)";
@@ -12106,6 +12134,7 @@ var COMPONENT_JS = `(() => {
     currentTagName = TAG_NAME;
     window.__haltija_resolveSelector = resolveSelector;
     window.__haltija_resolveSelectorAll = resolveSelectorAll;
+    window.__haltija_isActionable = isActionable;
     window.__haltija_refRegistry = refRegistry;
   }
   registerDevChannel();
@@ -12118,6 +12147,9 @@ var COMPONENT_JS = `(() => {
       if (existingVersion !== VERSION2) {
         console.log(\`\${LOG_PREFIX} Version mismatch (\${existingVersion} -> \${VERSION2}), replacing\`);
         existing.remove();
+      } else if (existing.isDefunct) {
+        console.log(\`\${LOG_PREFIX} Existing widget is defunct (killed), replacing\`);
+        existing.remove();
       } else {
         return existing;
       }
@@ -14547,7 +14579,15 @@ var windows = endpoint({
   summary: "List connected windows",
   description: `Returns all connected browser windows/tabs with IDs, URLs, and titles.
 
-Response: { windows: [{ id, url, title, focused, active, hidden, windowType }], count, ready, hint }
+Response: { windows: [{ id, url, title, focused, active, hidden, windowType }], tabs, count, ready, hint }
+
+The array is **\`windows\`**, not \`tabs\` \u2014 it includes popups (\`windowType: "popup"\`) and
+iframes (\`"iframe"\`), not only tabs. Because the CLI command is \`hj tabs\`, \`d['tabs']\` is the
+natural first guess and used to KeyError, so **\`tabs\` is also sent as an alias** of the same
+array. Prefer \`windows\`; \`tabs\` exists so the obvious guess works.
+
+Only real tabs can be the target of an UNTARGETED command \u2014 a popup or iframe never becomes
+\`focused\`, so a page opening a popup cannot silently re-route your commands.
 
 \`active\` and \`hidden\` are exact inverses, and BOTH are sent on purpose: /status historically
 emitted only \`hidden\` and /windows only \`active\`, so code moving between the two silently
@@ -16578,12 +16618,17 @@ registerHandler(find, async (body, ctx) => {
     // "Rendered", matching assert visible/hidden \u2014 NOT \`offsetParent === null\`, which is null for
     // \`html\`, \`body\` and EVERY \`position: fixed\` element. Fixed shells, modals and sticky chrome
     // are perfectly visible and were all being skipped.
-    const isVisible = (el) => {
+    //
+    // Prefers the WIDGET'S OWN predicate so \`find\` and \`click\` cannot disagree about which element
+    // a text selector means \u2014 they did, and it also let \`find\` return an element parked off-canvas
+    // at \`left:-9999px\` (#27). The inline copy below is only a fallback for a widget too old to
+    // export it; keeping two rules in permanent use is what caused #24 in the first place.
+    const isVisible = window.__haltija_isActionable || ((el) => {
       const cs = getComputedStyle(el);
       if (cs.display === 'none' || cs.visibility === 'hidden' || cs.opacity === '0') return false;
       const r = el.getBoundingClientRect();
       return r.width > 0 && r.height > 0;
-    };
+    });
 
     const textOf = (el) => (el.textContent || '').trim();
     const hits = elements.filter((el) => {
@@ -21014,9 +21059,10 @@ ${messageText}`;
       label: w.label
     }));
     const ready = isDrivable(windowList);
-    const hint = windowList.length > 1 ? "Multiple tabs connected. Use ?window=<id> to target specific tab (e.g., /tree?window=abc123)" : windowList.length === 1 ? "One tab connected. Commands automatically target it." : "No tabs connected. Inject the widget into a browser tab.";
+    const hint = windowList.length > 1 ? "Multiple windows connected. Use ?window=<id> to target a specific one (e.g., /tree?window=abc123). The array is `windows` \u2014 it includes popups and iframes, not only tabs." : windowList.length === 1 ? "One window connected. Commands automatically target it." : "No windows connected. Inject the widget into a browser tab.";
     return Response.json({
       windows: windowList,
+      tabs: windowList,
       focused: focusedWindowId,
       count: windowList.length,
       ready,

package/dist/server.js

@@ -674,7 +674,7 @@ var injectorCode = `
 `;
 
 // src/version.ts
-var VERSION = "1.12.0";
+var VERSION = "1.12.1";
 
 // src/embedded-assets.ts
 var APP_MD = `# Haltija App
@@ -2251,7 +2251,15 @@ Deprecated: Use POST /select {"action":"clear"} instead.
 
 Returns all connected browser windows/tabs with IDs, URLs, and titles.
 
-Response: { windows: [{ id, url, title, focused, active, hidden, windowType }], count, ready, hint }
+Response: { windows: [{ id, url, title, focused, active, hidden, windowType }], tabs, count, ready, hint }
+
+The array is **\`windows\`**, not \`tabs\` \u2014 it includes popups (\`windowType: "popup"\`) and
+iframes (\`"iframe"\`), not only tabs. Because the CLI command is \`hj tabs\`, \`d['tabs']\` is the
+natural first guess and used to KeyError, so **\`tabs\` is also sent as an alias** of the same
+array. Prefer \`windows\`; \`tabs\` exists so the obvious guess works.
+
+Only real tabs can be the target of an UNTARGETED command \u2014 a popup or iframe never becomes
+\`focused\`, so a page opening a popup cannot silently re-route your commands.
 
 \`active\` and \`hidden\` are exact inverses, and BOTH are sent on purpose: /status historically
 emitted only \`hidden\` and /windows only \`active\`, so code moving between the two silently
@@ -3441,7 +3449,7 @@ var COMPONENT_JS = `(() => {
   });
 
   // src/version.ts
-  var VERSION = "1.12.0";
+  var VERSION = "1.12.1";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\\(/;
@@ -4019,6 +4027,19 @@ var COMPONENT_JS = `(() => {
     const candidates = queryAllDeep(parsed.baseSelector).filter((el) => !NON_RENDERED_TEXT.has(el.tagName) && elementTextMatches(el, parsed));
     return candidates.filter((el) => !candidates.some((other) => other !== el && containsDeep(el, other)));
   }
+  function isOffCanvas(el) {
+    const r = el.getBoundingClientRect();
+    return r.right + window.scrollX <= 0 || r.bottom + window.scrollY <= 0;
+  }
+  function isActionable(el) {
+    const cs = getComputedStyle(el);
+    if (cs.display === "none" || cs.visibility === "hidden" || cs.opacity === "0")
+      return false;
+    const r = el.getBoundingClientRect();
+    if (r.width <= 0 || r.height <= 0)
+      return false;
+    return !isOffCanvas(el);
+  }
   function resolveSelector(selector) {
     if (!TEXT_PSEUDO_RE.test(selector)) {
       return document.querySelector(selector) || queryAllDeep(selector)[0] || null;
@@ -4026,7 +4047,8 @@ var COMPONENT_JS = `(() => {
     const parsed = parseTextSelector(selector);
     if (!parsed)
       return document.querySelector(selector);
-    return textMatchesInDocument(parsed)[0] || null;
+    const matches = textMatchesInDocument(parsed);
+    return matches.find(isActionable) || matches[0] || null;
   }
   function resolveSelectorAll(selector) {
     if (!TEXT_PSEUDO_RE.test(selector)) {
@@ -8422,6 +8444,9 @@ var COMPONENT_JS = `(() => {
       }
       this.render();
     }
+    get isDefunct() {
+      return this.killed;
+    }
     kill() {
       this.killed = true;
       hideHighlight();
@@ -10950,6 +10975,9 @@ var COMPONENT_JS = `(() => {
       };
     }
     getHiddenReason(el) {
+      if (isOffCanvas(el)) {
+        return "positioned off-canvas (e.g. left:-9999px) \u2014 rendered but not reachable by a user";
+      }
       const rect = el.getBoundingClientRect();
       if (rect.width === 0 && rect.height === 0) {
         return "zero-size bounding rect (element not rendered or in hidden container)";
@@ -12106,6 +12134,7 @@ var COMPONENT_JS = `(() => {
     currentTagName = TAG_NAME;
     window.__haltija_resolveSelector = resolveSelector;
     window.__haltija_resolveSelectorAll = resolveSelectorAll;
+    window.__haltija_isActionable = isActionable;
     window.__haltija_refRegistry = refRegistry;
   }
   registerDevChannel();
@@ -12118,6 +12147,9 @@ var COMPONENT_JS = `(() => {
       if (existingVersion !== VERSION2) {
         console.log(\`\${LOG_PREFIX} Version mismatch (\${existingVersion} -> \${VERSION2}), replacing\`);
         existing.remove();
+      } else if (existing.isDefunct) {
+        console.log(\`\${LOG_PREFIX} Existing widget is defunct (killed), replacing\`);
+        existing.remove();
       } else {
         return existing;
       }
@@ -14547,7 +14579,15 @@ var windows = endpoint({
   summary: "List connected windows",
   description: `Returns all connected browser windows/tabs with IDs, URLs, and titles.
 
-Response: { windows: [{ id, url, title, focused, active, hidden, windowType }], count, ready, hint }
+Response: { windows: [{ id, url, title, focused, active, hidden, windowType }], tabs, count, ready, hint }
+
+The array is **\`windows\`**, not \`tabs\` \u2014 it includes popups (\`windowType: "popup"\`) and
+iframes (\`"iframe"\`), not only tabs. Because the CLI command is \`hj tabs\`, \`d['tabs']\` is the
+natural first guess and used to KeyError, so **\`tabs\` is also sent as an alias** of the same
+array. Prefer \`windows\`; \`tabs\` exists so the obvious guess works.
+
+Only real tabs can be the target of an UNTARGETED command \u2014 a popup or iframe never becomes
+\`focused\`, so a page opening a popup cannot silently re-route your commands.
 
 \`active\` and \`hidden\` are exact inverses, and BOTH are sent on purpose: /status historically
 emitted only \`hidden\` and /windows only \`active\`, so code moving between the two silently
@@ -16578,12 +16618,17 @@ registerHandler(find, async (body, ctx) => {
     // "Rendered", matching assert visible/hidden \u2014 NOT \`offsetParent === null\`, which is null for
     // \`html\`, \`body\` and EVERY \`position: fixed\` element. Fixed shells, modals and sticky chrome
     // are perfectly visible and were all being skipped.
-    const isVisible = (el) => {
+    //
+    // Prefers the WIDGET'S OWN predicate so \`find\` and \`click\` cannot disagree about which element
+    // a text selector means \u2014 they did, and it also let \`find\` return an element parked off-canvas
+    // at \`left:-9999px\` (#27). The inline copy below is only a fallback for a widget too old to
+    // export it; keeping two rules in permanent use is what caused #24 in the first place.
+    const isVisible = window.__haltija_isActionable || ((el) => {
       const cs = getComputedStyle(el);
       if (cs.display === 'none' || cs.visibility === 'hidden' || cs.opacity === '0') return false;
       const r = el.getBoundingClientRect();
       return r.width > 0 && r.height > 0;
-    };
+    });
 
     const textOf = (el) => (el.textContent || '').trim();
     const hits = elements.filter((el) => {
@@ -21014,9 +21059,10 @@ ${messageText}`;
       label: w.label
     }));
     const ready = isDrivable(windowList);
-    const hint = windowList.length > 1 ? "Multiple tabs connected. Use ?window=<id> to target specific tab (e.g., /tree?window=abc123)" : windowList.length === 1 ? "One tab connected. Commands automatically target it." : "No tabs connected. Inject the widget into a browser tab.";
+    const hint = windowList.length > 1 ? "Multiple windows connected. Use ?window=<id> to target a specific one (e.g., /tree?window=abc123). The array is `windows` \u2014 it includes popups and iframes, not only tabs." : windowList.length === 1 ? "One window connected. Commands automatically target it." : "No windows connected. Inject the widget into a browser tab.";
     return Response.json({
       windows: windowList,
+      tabs: windowList,
       focused: focusedWindowId,
       count: windowList.length,
       ready,

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

package/package.json

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