haltija 1.11.0 → 1.11.2

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # Changelog
 
+## 1.11.2
+
+Patch. Four field reports from tosijs-3d and tosijs-ui, all confirmed.
+
+### Fixed: `--canvas` couldn't reach a canvas in a shadow root ([#15](https://github.com/tonioloewald/haltija/issues/15))
+
+Which is where every component-based renderer puts it — so the exact-pixels escape hatch failed on
+exactly the pages where pixels are the only thing worth looking at. Canvas resolution now pierces
+shadow DOM and accepts every shape someone would reasonably write:
+
+```bash
+hj screenshot --canvas "tosi-b3d canvas"       # descendant, crossing the boundary
+hj screenshot --canvas "tosi-b3d >>> canvas"   # explicit piercing form
+hj screenshot --canvas "canvas"                # found inside shadow roots too
+hj screenshot --canvas                         # no selector: the largest canvas on the page
+```
+
+A genuine miss now lists the canvases that *do* exist, with working selectors. The **schematic**
+embeds shadow-root canvases as well — previously it silently showed none on these pages.
+
+### Fixed: advisory hints were printed to stdout ([#14](https://github.com/tonioloewald/haltija/issues/14))
+
+A dim hint line was appended to **stdout** after JSON output, so `JSON.parse(await $\`hj windows\`)`
+threw — and an adopter's readiness probe fell into an open catch and silently did nothing. All
+advisory text is on stderr now; stdout is the data channel.
+
+Two related fixes from the same report:
+
+- **`hj <cmd> --help` now describes that command** instead of falling through to global help, which
+  read exactly like "unknown command" (a reporter concluded `doctor` and `map` didn't exist in their
+  build). haltija's own error messages recommend this form, so the remedy we printed was broken.
+- **The standalone `hj` bundle now carries its hints.** They were read from a sibling `hints.json`,
+  which doesn't exist next to `~/.local/bin/hj` — so two distributions reporting the same version
+  produced different output. Hints are compiled in, like the version and semver helpers.
+
+### Fixed: contrast false positives on text-less ancestors ([#13](https://github.com/tonioloewald/haltija/issues/13))
+
+A container propagates `color`/`background` but has no font size, so `large` is *unknowable* —
+defaulting it to false held it to 4.5:1 and manufactured failures for text that passes as large on
+the child that actually renders it. About half the findings on a typical page. Only elements with
+their own direct text are graded now.
+
+## 1.11.1
+
+Patch, per the rule that a minor bump waits for a cleared backlog and a nine-lens review.
+
+### Fixed: contrast audit noise
+
+Two sources of false findings, fixed before anyone acts on a long list of them:
+
+- **Containers with no text of their own were flagged.** A `<div>`/`<form>` inherits a colour but
+  displays nothing, so a "failure" there is noise. Only elements that actually render text, a label
+  or a value get a verdict now.
+- **Text over a `background-image`** (gradient, photo) was judged against whatever background-*color*
+  sat beneath it — which can be wrong in either direction. Those are now reported as
+  `colors.uncertain` rather than asserted as pass or fail.
+
+An audit people learn to skim is worth nothing, so the bar is: only claim what can be justified.
+
+### Per-tab routing, by declaration ([#1](https://github.com/tonioloewald/haltija/issues/1), [#2](https://github.com/tonioloewald/haltija/issues/2))
+
+cwd routing gets a command to the right *server*; which **tab** answers then fell back to focus, so
+two projects on a shared server could drive each other's pages. Ranking tabs by "this origin looks
+like your project" was rejected twice — there's no reliable origin→directory map, and a
+usually-right guess reintroduces the silent misroute cwd routing exists to prevent.
+
+So the project declares it. A `.haltija.json` at the project root:
+
+```json
+{ "origins": ["https://localhost:8030", "http://localhost:3000"] }
+```
+
+…and `hj`, run anywhere inside that project, pins commands to a connected tab on one of those
+origins regardless of focus. **Entirely opt-in** (no file = unchanged behaviour) and it never
+guesses: if you declared origins and no connected tab matches, `hj` says so loudly instead of
+quietly driving another project's page — and refuses outright under `--strict`. `HALTIJA_ORIGINS`
+overrides for one-off shells and CI.
+
+### `hj screenshot --schematic`
+
+Ask for the schematic even when real capture *is* available — it's cheaper, deterministic, and
+carries the contrast audit. Canvases are still embedded as real pixels.
+
 ## 1.11.0
 
 ### Errors now tell you what to do

package/apps/desktop/package.json

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

package/apps/desktop/resources/component.js

@@ -46,7 +46,7 @@
   });
 
   // src/version.ts
-  var VERSION = "1.11.0";
+  var VERSION = "1.11.2";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;
@@ -1294,9 +1294,90 @@
       ...buildDomAffordances(opts.maxNodes)
     };
   }
+  function findCanvasesDeep(root = document) {
+    const found = [];
+    const visit = (node) => {
+      for (const el of Array.from(node.querySelectorAll("*"))) {
+        if (el.tagName === "CANVAS")
+          found.push(el);
+        const sr = el.shadowRoot;
+        if (sr)
+          visit(sr);
+      }
+    };
+    visit(root);
+    return found;
+  }
+  function resolveCanvasDeep(selector) {
+    const all = findCanvasesDeep();
+    if (!selector || !String(selector).trim()) {
+      if (!all.length)
+        return { canvas: null };
+      const largest = all.slice().sort((a, b) => b.width * b.height - a.width * a.height)[0];
+      return {
+        canvas: largest,
+        note: all.length > 1 ? `page has ${all.length} canvases; captured the largest (${largest.width}×${largest.height}). Pass a selector to choose another.` : undefined
+      };
+    }
+    const sel = String(selector).trim();
+    if (sel.includes(">>>")) {
+      const parts = sel.split(">>>").map((p) => p.trim()).filter(Boolean);
+      let scope = document;
+      let el = null;
+      for (const part of parts) {
+        if (!scope)
+          return { canvas: null };
+        el = scope.querySelector(part);
+        if (!el)
+          return { canvas: null };
+        scope = el.shadowRoot || el;
+      }
+      return { canvas: el && el.tagName === "CANVAS" ? el : scope?.querySelector?.("canvas") || null };
+    }
+    const light = resolveSelector(sel);
+    if (light && light.tagName === "CANVAS")
+      return { canvas: light };
+    if (light) {
+      const inHost = light.shadowRoot?.querySelector("canvas");
+      if (inHost)
+        return { canvas: inHost };
+    }
+    const tokens = sel.split(/\s+/).filter(Boolean);
+    if (tokens.length > 1) {
+      const descend = (scope, i) => {
+        if (i >= tokens.length)
+          return null;
+        const rest = tokens.slice(i).join(" ");
+        const direct = scope.querySelector(rest);
+        if (direct && direct.tagName === "CANVAS")
+          return direct;
+        for (const cand of Array.from(scope.querySelectorAll(tokens[i]))) {
+          const sr = cand.shadowRoot;
+          if (!sr)
+            continue;
+          const hit = descend(sr, i + 1);
+          if (hit)
+            return hit;
+        }
+        return null;
+      };
+      const crossed = descend(document, 0);
+      if (crossed)
+        return { canvas: crossed };
+    }
+    for (const el of Array.from(document.querySelectorAll("*"))) {
+      const sr = el.shadowRoot;
+      if (!sr)
+        continue;
+      const hit = sr.querySelector(sel);
+      if (hit && hit.tagName === "CANVAS")
+        return { canvas: hit };
+    }
+    return { canvas: null };
+  }
   function collectCanvasThumbnails(maxEdge = 320) {
     const out = [];
-    for (const el of Array.from(document.querySelectorAll("canvas"))) {
+    for (const el of findCanvasesDeep()) {
       const c = el;
       if (!c.width || !c.height)
         continue;
@@ -1472,8 +1553,12 @@
     let node = el;
     let acc = { r: 255, g: 255, b: 255 };
     const stack = [];
+    let imaged = false;
     while (node) {
-      const c = parseCssColor(getComputedStyle(node).backgroundColor);
+      const cs = getComputedStyle(node);
+      if (cs.backgroundImage && cs.backgroundImage !== "none")
+        imaged = true;
+      const c = parseCssColor(cs.backgroundColor);
       if (c && c.a > 0) {
         stack.push(c);
         if (c.a === 1)
@@ -1483,7 +1568,7 @@
     }
     for (let i = stack.length - 1;i >= 0; i--)
       acc = over(stack[i], acc);
-    return acc;
+    return { ...acc, imaged };
   }
   var relLuminance = (c) => {
     const ch = (v) => {
@@ -1516,7 +1601,8 @@
       border,
       contrast: Math.round(ratio * 10) / 10,
       passes: ratio >= (large ? 3 : 4.5),
-      large
+      large,
+      ...bg.imaged ? { uncertain: true } : {}
     };
   }
   function elementNotFoundMessage(target) {
@@ -1560,8 +1646,11 @@
       try {
         const c = probeColors(el);
         node.colors = c;
-        if (!c.passes)
+        const hasOwnText = Array.from(el.childNodes).some((n) => n.nodeType === 3 && (n.textContent || "").trim().length > 0);
+        const hasReadableText = hasOwnText || !!(node.label || node.value);
+        if (!c.passes && hasReadableText && !c.uncertain) {
           node.contrastFail = `${c.contrast}:1 (needs ${c.large ? 3 : 4.5}:1)`;
+        }
       } catch {}
       return node;
     };
@@ -6261,10 +6350,34 @@ ${elementSummary}${moreText}`;
               targetSelector = element.id ? `#${element.id}` : element.getAttribute("data-testid") ? `[data-testid="${element.getAttribute("data-testid")}"]` : undefined;
             }
           }
-          if (payload2?.canvas) {
-            const el = resolveSelector(payload2.canvas);
+          if (payload2?.schematic) {
+            const map = buildAffordanceMap({});
+            const canvases = collectCanvasThumbnails();
+            const { svg, width, height } = renderMapSchematic(map, canvases, "SCHEMATIC — requested (not a screenshot)");
+            const image = await rasterizeSchematic(svg, width, height, payload2?.scale || 2);
+            this.respond(msg2.id, true, {
+              image,
+              viewport,
+              format: "png",
+              width,
+              height,
+              source: "schematic",
+              requested: true,
+              canvasesRendered: canvases.filter((c) => c.image).length,
+              map
+            });
+            return;
+          }
+          if (payload2?.canvas !== undefined) {
+            const resolved = resolveCanvasDeep(payload2.canvas);
+            const el = resolved.canvas;
             if (!el) {
-              this.respond(msg2.id, false, null, `Canvas not found: ${payload2.canvas}`);
+              const all = findCanvasesDeep();
+              const inventory = all.length ? `Found ${all.length} canvas element(s): ` + all.map((c) => {
+                const host = c.getRootNode()?.host;
+                return `${host ? host.tagName.toLowerCase() + " >>> " : ""}canvas${c.id ? "#" + c.id : ""} (${c.width}×${c.height})`;
+              }).join(", ") + `. Try one of those, or omit the selector to capture the largest.` : `No <canvas> exists on this page (shadow roots included). \`hj map\` shows what is here.`;
+              this.respond(msg2.id, false, null, `Canvas not found: ${payload2.canvas || "(largest)"}. ${inventory}`);
               return;
             }
             if (typeof el.toDataURL !== "function") {
@@ -6323,9 +6436,11 @@ ${elementSummary}${moreText}`;
                 height: targetH,
                 source: "canvas",
                 canvas: {
-                  selector: payload2.canvas,
+                  selector: payload2.canvas || "(largest)",
                   intrinsic: { width: el.width, height: el.height },
-                  displayed: { width: el.clientWidth, height: el.clientHeight }
+                  displayed: { width: el.clientWidth, height: el.clientHeight },
+                  inShadowRoot: el.getRootNode()?.host ? el.getRootNode().host.tagName.toLowerCase() : undefined,
+                  ...resolved.note ? { note: resolved.note } : {}
                 },
                 ...warning ? { warning } : {}
               });

package/bin/cli-subcommand.mjs

@@ -31,10 +31,12 @@ import { differsBeyondPatch } from './semver.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
-// Command hints - generated from api-schema.ts during build
-// Use readFileSync instead of JSON import to avoid Node.js ExperimentalWarning
-const hintsPath = join(__dirname, 'hints.json')
-export const COMMAND_HINTS = existsSync(hintsPath) ? JSON.parse(readFileSync(hintsPath, 'utf-8')) : {}
+// Command hints — generated from api-schema.ts during build and IMPORTED, not read from disk.
+// Reading a sibling hints.json works for the npm package but not for dist/hj.js installed as a lone
+// file in ~/.local/bin, so the standalone CLI silently had no hints while claiming the same version
+// (issue #14). An import is inlined by the bundler, so both distributions behave identically.
+export { COMMAND_HINTS } from './hints.mjs'
+import { COMMAND_HINTS as COMMAND_HINTS_LOCAL } from './hints.mjs'
 
 let warnedAboutSkew = false
 
@@ -155,9 +157,17 @@ export const ARG_MAPS = {
       if (a === '--no-chyron') { body.chyron = false; continue }
       // Read a <canvas>'s own pixels (WebGL/2D) instead of capturing the screen: exact pixels, no
       // screen-share grant, works off-screen. The route for 3D scenes / render-to-texture UI.
-      if (a === '--canvas') { body.canvas = args[++i]; continue }
+      if (a === '--canvas') {
+        // Bare `--canvas` (no selector) captures the largest canvas on the page — which is
+        // unambiguous when there's one interesting canvas, the common case.
+        const next = args[i + 1]
+        body.canvas = next && !next.startsWith('-') ? args[++i] : ''
+        continue
+      }
       // Hard-fail instead of returning a labelled schematic when pixels aren't capturable.
       if (a === '--no-fallback') { body.fallback = false; continue }
+      // Prefer the schematic outright: cheaper, deterministic, and it carries the contrast audit.
+      if (a === '--schematic') { body.schematic = true; continue }
       if (!a.startsWith('-')) { positional.push(a) }
     }
     return { ...body, ...parseTargetArgs(positional) }
@@ -742,7 +752,7 @@ export const KNOWN_FLAGS = {
   inspect: ['--full-styles', '--styles', '--matched-rules', '--rules', '--ancestors'],
   inspectAll: ['--full-styles', '--styles', '--matched-rules', '--rules', '--ancestors'],
   key: ['--ctrl', '-c', '--shift', '-s', '--alt', '-a', '--meta', '-m'],
-  screenshot: ['--data-url', '--format', '--quality', '--scale', '--maxWidth', '--max-width', '--maxHeight', '--max-height', '--delay', '--no-chyron', '--canvas', '--no-fallback'],
+  screenshot: ['--data-url', '--format', '--quality', '--scale', '--maxWidth', '--max-width', '--maxHeight', '--max-height', '--delay', '--no-chyron', '--canvas', '--no-fallback', '--schematic'],
   'video-start': ['--maxDuration', '--max-duration'],
   refresh: ['--soft'],
   'test-run': ['--vars', '--seed', '--timeoutMs', '--allow-failures', '--allow-failures-streak', '--step-delay'],
@@ -995,7 +1005,7 @@ async function doRequest(url, method, body, context = {}) {
         const dim = (s) => `\x1b[2m${s}\x1b[0m`
         console.log(bold(json.data.path))
         const meta = [json.data.width && json.data.height ? `${json.data.width}×${json.data.height}` : null, json.data.format, json.data.source].filter(Boolean).join(', ')
-        if (meta) console.log(dim(meta))
+        if (meta) console.error(dim(meta))
       } else if (!jsonOutput && (subcommand === 'network' || subcommand === 'network-watch') && (json.entries || json.data?.entries || json.summary || json.data?.summary)) {
         console.log(formatNetwork(json))
       } else if (!jsonOutput && subcommand === 'network-stats') {
@@ -1005,7 +1015,7 @@ async function doRequest(url, method, body, context = {}) {
         const dim = (s) => `\x1b[2m${s}\x1b[0m`
         console.log(bold(json.data.path))
         const meta = [json.data.duration ? `${json.data.duration.toFixed(1)}s` : null, json.data.size ? `${(json.data.size / 1024).toFixed(0)}KB` : null, json.data.format].filter(Boolean).join(', ')
-        if (meta) console.log(dim(meta))
+        if (meta) console.error(dim(meta))
       } else if (!jsonOutput && UNWRAP_DATA_SUBCOMMANDS.has(subcommand)) {
         // Print the inner DevResponse.data unwrapped so agents (and humans) can
         // read it directly. Strings go to stdout as-is — no JSON escaping of
@@ -1048,10 +1058,13 @@ async function doRequest(url, method, body, context = {}) {
     // Skip for commands whose stdout is meant to be piped/consumed verbatim
     // — agents shouldn't have to strip a trailing hint line.
     if (resp.ok && !jsonOutput && !UNWRAP_DATA_SUBCOMMANDS.has(subcommand)) {
-      const hint = COMMAND_HINTS[subcommand]
+      const hint = COMMAND_HINTS_LOCAL[subcommand]
       if (hint) {
         const dim = (s) => `\x1b[2m${s}\x1b[0m`
-        console.log(dim(`\nhj ${subcommand} : ${hint}`))
+        // stderr, NOT stdout. A hint appended to stdout turns parseable JSON into garbage —
+        // an adopter's `JSON.parse(await $`hj windows`)` threw, their catch fell open, and the
+        // readiness probe silently did nothing (issue #14). Advisory text belongs on stderr.
+        console.error(dim(`hj ${subcommand} : ${hint}`))
       }
     }
 

package/bin/hints.mjs

@@ -0,0 +1,27 @@
+/** ⚠️  AUTO-GENERATED FROM src/api-schema.ts — DO NOT EDIT. Run: bun run build */
+export const COMMAND_HINTS = {
+  "tree": "-d 3 (shallow), -i (interactive only), --visible, --compact | see: inspect, query, click",
+  "query": "@ref or \"selector\", --all | see: tree, inspect",
+  "inspect": "@ref or \"selector\", --styles, --rules, --ancestors | see: tree, query",
+  "click": "@ref or \"selector\", :text(Button), --diff | see: tree, wait, type",
+  "type": "@ref, --clear, --humanlike false (fast) | see: click, key",
+  "key": "<key> --ctrl --shift --alt --meta, --repeat 3 | see: type, click",
+  "drag": "@ref or \"selector\" <deltaX> <deltaY>, --duration 500 | see: click, scroll",
+  "highlight": "@ref or \"selector\", --label \"text\", --color #f00, --duration 3000 | see: unhighlight, screenshot",
+  "scroll": "@ref or \"selector\" or <deltaY>, --duration 500 | see: click, wait",
+  "wait": "\"selector\", --text \"content\", --timeout 5000 | see: click, navigate",
+  "events": "events-watch first | see: recording, console, mutations-watch",
+  "eval": "\"code\" (returns result) | see: console, snapshot",
+  "call": "@ref or \"selector\" <method>, --args [...]  | see: eval, inspect",
+  "screenshot": "[selector], --format webp, --scale 0.5, --maxWidth 800 | see: highlight, snapshot",
+  "windows": "--json | see: tabs-open, tabs-close, tabs-focus, status",
+  "map": "--json | see: tree, query, inspect",
+  "tabs-open": "[url] | see: tabs-focus, tabs-close, windows",
+  "tabs-close": "<window-id> | see: windows, tabs-focus, tabs-open",
+  "tabs-focus": "<window-id> | see: windows, tabs-close, tabs-open",
+  "recording": "start, stop, list, replay <id|index> | see: test-run, events",
+  "video-start": "--maxDuration 120 | see: video-stop, video-status, screenshot",
+  "video-stop": "| see: video-start, video-status",
+  "video-status": "| see: video-start, video-stop",
+  "status": "--json | see: windows, stats, console"
+}

package/bin/hj.mjs

@@ -12,6 +12,7 @@
 
 import { runSubcommand, isSubcommand, getSuggestion, listSubcommands, COMMAND_HINTS } from './cli-subcommand.mjs'
 import { extractWindowTarget } from './arg-utils.mjs'
+import { findProjectOrigins, routeByDeclaredOrigin } from './project-origins.mjs'
 import { HJ_VERSION } from './version.mjs'
 import { differsBeyondPatch } from './semver.mjs'
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
@@ -350,6 +351,15 @@ function resolveByCwd(cwd, instances) {
   return candidates[0]
 }
 
+// `hj <cmd> --help` shows help for THAT command. It used to fall into the global help below, which
+// reads exactly like "unknown command" — a reporter reasonably concluded `doctor` and `map` didn't
+// exist in their build (issue #14). Worse, haltija's own error messages tell you to run
+// `hj <cmd> --help`, so the remedy we print was broken: a printed remedy is a testable claim.
+if ((args.includes('--help') || args.includes('-h')) && args[0] && !args[0].startsWith('-')) {
+  filterHelp(args[0])
+  process.exit(0)
+}
+
 if (!args.length || args.includes('--help') || args.includes('-h')) {
   const bold = (s) => `\x1b[1m${s}\x1b[0m`
   const dim = (s) => `\x1b[2m${s}\x1b[0m`
@@ -609,6 +619,50 @@ if (subcommand === 'shutdown' || subcommand === 'quit') {
   }
 }
 
+// Declared-origin routing (issues #1/#2). cwd routing found the right SERVER; if this project has
+// declared which origins are its pages, pin the command to the matching TAB instead of letting focus
+// decide. Purely opt-in — no `.haltija.json` (or HALTIJA_ORIGINS) means nothing changes.
+//
+// Skipped when the caller already pinned a window (they own the choice), and for the diagnostic
+// commands, which must describe the world rather than act on one tab.
+const DIAGNOSTIC = new Set(['where', 'servers', 'ls', 'doctor', 'shutdown', 'quit', 'status', 'windows', 'version'])
+if (!windowTarget && !DIAGNOSTIC.has(subcommand) && isSubcommand(subcommand)) {
+  const declared = findProjectOrigins(process.cwd(), process.env)
+  if (declared && declared.origins.length) {
+    try {
+      const token = process.env.HALTIJA_TOKEN
+      const resp = await fetch(`http://localhost:${port}/windows`, {
+        headers: token ? { 'X-Haltija-Token': token } : {},
+        signal: AbortSignal.timeout(2500),
+      })
+      if (resp.ok) {
+        const { windows: tabs = [], focused } = await resp.json()
+        const routed = routeByDeclaredOrigin(declared.origins, tabs, focused)
+        if (routed.kind === 'matched') {
+          subArgs = [...subArgs, '--window', routed.windowId]
+        } else if (routed.kind === 'no-match' && tabs.length) {
+          // NEVER fall through silently: this project said which pages are its own, and none is
+          // connected. Driving whatever happens to be focused is the exact bug the declaration was
+          // added to prevent.
+          const saw = routed.sawOrigins.length ? routed.sawOrigins.join(', ') : '(none with a readable origin)'
+          const msg =
+            `declared origins ${declared.origins.join(', ')} (from ${declared.source}) match no connected tab. ` +
+            `Connected: ${saw}.`
+          if (STRICT) {
+            console.error(`hj: ERROR (strict) — ${msg}`)
+            console.error(`hj: open one of your declared origins, fix .haltija.json, or pass --window <id> to choose explicitly.`)
+            process.exit(1)
+          }
+          console.error(`hj: warning — ${msg}`)
+          console.error(`hj: proceeding against the FOCUSED tab, which may be another project's page. Pass --window <id> to be sure.`)
+        }
+      }
+    } catch {
+      // Routing is an enhancement; never let a probe failure block the command.
+    }
+  }
+}
+
 if (!isSubcommand(subcommand)) {
   const suggestion = getSuggestion(subcommand)
   if (suggestion === '--help') {

package/bin/project-origins.mjs

@@ -0,0 +1,77 @@
+/** ⚠️  AUTO-GENERATED FROM src/project-origins.ts — DO NOT EDIT. Run: bun run build */
+// src/project-origins.ts
+import { existsSync, readFileSync } from "fs";
+import { dirname, join, parse as parsePath } from "path";
+function normalizeOrigin(value) {
+  const v = String(value || "").trim();
+  if (!v)
+    return null;
+  const parse = (candidate) => {
+    try {
+      const origin = new URL(candidate).origin;
+      return origin && origin !== "null" ? origin : null;
+    } catch {
+      return null;
+    }
+  };
+  return parse(v) ?? parse(`http://${v}`);
+}
+function findProjectOrigins(cwd, env = process.env) {
+  const fromEnv = env.HALTIJA_ORIGINS;
+  if (fromEnv && fromEnv.trim()) {
+    const origins = fromEnv.split(",").map(normalizeOrigin).filter((o) => !!o);
+    if (origins.length)
+      return { origins, source: "HALTIJA_ORIGINS env" };
+  }
+  let dir = cwd;
+  const { root } = parsePath(cwd);
+  for (let depth = 0;depth < 64; depth++) {
+    const file = join(dir, ".haltija.json");
+    if (existsSync(file)) {
+      try {
+        const parsed = JSON.parse(readFileSync(file, "utf-8"));
+        const raw = Array.isArray(parsed?.origins) ? parsed.origins : [];
+        const origins = raw.map(normalizeOrigin).filter((o) => !!o);
+        return { origins, source: file };
+      } catch {
+        return { origins: [], source: `${file} (unreadable or invalid JSON)` };
+      }
+    }
+    if (dir === root)
+      break;
+    const parent = dirname(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return null;
+}
+function routeByDeclaredOrigin(declared, tabs, focusedWindowId) {
+  if (!declared.length)
+    return { kind: "no-declaration" };
+  const wanted = new Set(declared);
+  const topLevel = tabs.filter((t) => (t.windowType || "tab") === "tab");
+  const matches = topLevel.filter((t) => {
+    const o = normalizeOrigin(t.url || "");
+    return o !== null && wanted.has(o);
+  });
+  if (!matches.length) {
+    const sawOrigins = [...new Set(topLevel.map((t) => normalizeOrigin(t.url || "")).filter((o) => !!o))];
+    return { kind: "no-match", declared, sawOrigins };
+  }
+  const visible = matches.filter((t) => t.active !== false);
+  const pool = visible.length ? visible : matches;
+  const focused = pool.find((t) => t.id === focusedWindowId);
+  const chosen = focused || pool[0];
+  return {
+    kind: "matched",
+    windowId: chosen.id,
+    origin: normalizeOrigin(chosen.url || ""),
+    candidates: matches.length
+  };
+}
+export {
+  routeByDeclaredOrigin,
+  normalizeOrigin,
+  findProjectOrigins
+};

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.11.0'
+export const HJ_VERSION = '1.11.2'

package/dist/api-schema.d.ts

@@ -244,6 +244,7 @@ export declare const screenshot: EndpointDef<{
     maxHeight?: number | undefined;
     chyron?: boolean | undefined;
     file?: boolean | undefined;
+    schematic?: boolean | undefined;
     fallback?: boolean | undefined;
 }>;
 export declare const select: EndpointDef<{
@@ -546,6 +547,7 @@ export declare const endpoints: {
         maxHeight?: number | undefined;
         chyron?: boolean | undefined;
         file?: boolean | undefined;
+        schematic?: boolean | undefined;
         fallback?: boolean | undefined;
     }>;
     readonly select: EndpointDef<{
@@ -816,6 +818,7 @@ export declare const ALL_ENDPOINTS: (EndpointDef<{
     maxHeight?: number | undefined;
     chyron?: boolean | undefined;
     file?: boolean | undefined;
+    schematic?: boolean | undefined;
     fallback?: boolean | undefined;
 }> | EndpointDef<{
     window?: string | undefined;

package/dist/component.d.ts

@@ -20,7 +20,7 @@
  * - Option+Tab toggles visibility (but active state always shows briefly)
  * - Localhost only by default
  */
-export declare const VERSION = "1.11.0";
+export declare const VERSION = "1.11.2";
 export declare class DevChannel extends HTMLElement {
     static get tagName(): string;
     static elementCreator(): () => DevChannel;