haltija 1.6.1 → 1.11.2

package/CHANGELOG.md

@@ -1,5 +1,219 @@
 # 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
+
+Following the tjs lesson that an error's job is the next action, not the diagnosis:
+
+- **"Element not found"** branches on what you passed. A stale **ref** explains that refs are only
+  valid while the element is in the DOM and to re-run `hj tree` (or target by text, which survives
+  re-renders); a **selector** gets the recovery order — `hj map`/`hj tree` to see what's there, the
+  hidden-elements rule, prefer `:text()`/`[data-testid]` over structural selectors, and `hj wait` if
+  the page is still loading.
+- **Unknown-action errors list the valid actions** instead of only rejecting yours.
+- **"No active recording" / "No selection available" / "url is required"** now say how to reach a
+  valid state.
+- **Schema-validation failures** carry a `hint` with the CLI form and a runnable example body — and
+  `hj` now prints `hint` on errors, which it previously discarded, so the teachable half reached
+  nobody.
+
+### Fixed: six endpoints were missing from every generated doc
+
+All three doc generators iterated a hardcoded category list and silently dropped anything not in it,
+so every `/network/*` and `/dialog/*` endpoint appeared in **no** generated documentation. They now
+append unlisted categories, so a new category can't vanish.
+
+### New: a docs-coverage gate
+
+`docs-drift` catches generated files going stale against the schema; it can't catch a feature
+shipping that the prose never mentions — which is how `hj map`, `--canvas` and `hj shutdown` all
+shipped undiscoverable. A test now asserts every public endpoint reaches the reference and
+`llms.txt`, every agent-facing command is named in `SKILL.md`, and headline capabilities are
+explained rather than merely listed — failing with exactly what to add.
+
+## 1.10.0
+
+### New: a screenshot you can't take now degrades to a labelled schematic
+
+In a plain browser with no desktop app and no screen-share grant, `hj screenshot` used to just fail.
+It now returns a **schematic** of the page instead — and because canvases need **no permission**, any
+`<canvas>` is embedded as **real pixels** inside it. For a 3D app or a chart that's the actual visual
+content, so the substitute is genuinely useful rather than a consolation prize.
+
+Labelled three ways, because a schematic quietly standing in for a screenshot would be exactly the
+plausible-but-wrong result this tool exists to prevent: `source: "schematic"`, a `warning` naming
+both routes to real pixels, and a red banner burned across the image. `--no-fallback` restores the
+hard error, and `--strict` turns the warning into a non-zero exit.
+
+### New: the schematic surfaces contrast problems
+
+The schematic is drawn in the **page's own colours** — element background as fill, border as stroke,
+text colour for the caption — so a control the user can barely read is a box you can barely read.
+Poor contrast shows itself instead of hiding in a JSON blob. It's machine-checkable too: DOM-tier
+nodes carry `colors: {fg, bg, contrast, passes}` and a `contrastFail` string when they miss WCAG AA.
+(The verdict is drawn in legible red on purpose — a warning about unreadable text mustn't itself be
+unreadable.)
+
+### Fixed: the widget was served without a charset
+
+`Content-Type: application/javascript` carried no `; charset=utf-8`, so browsers parsed
+`component.js` as Latin-1 and **every non-ASCII string literal in the widget was corrupted at parse
+time** — em-dashes, `×`, `·`, and the `⟷`/`⟵` binding-arrow legend. The bytes on disk were always
+valid UTF-8; the browser was mis-decoding them. Fixed on all five JS responses.
+
+## 1.9.0
+
+### New: `hj map --image` — the map as a rasterized schematic
+
+Renders the affordance map as a PNG: one labeled box per control, nested by structure, each showing
+its handle (`@ref` or `#index`) so the picture doubles as an **index** — glance at it, pick a
+target, act on that one record.
+
+It has to be a **bitmap** to be worth anything: an image of text costs a vision encoder far fewer
+tokens than the same text tokenized, but that applies to rendered pixels, not to SVG markup (which
+is just text tokens, and worse than the JSON it would replace). Rasterized in the browser, so there
+is no new dependency.
+
+**The win is density-dependent, and the response says so rather than assuming.** An image costs
+~1000–1600 vision tokens regardless of content, so a small page is cheaper as JSON; the image pays
+off once the map is large. `cost.approxJsonTokens` reports the JSON size for that page so the choice
+is measurable. The schematic is also deterministic, which makes a diff between two runs a regression
+a human can see.
+
+## 1.8.0
+
+### New: `hj map` — what can I interact with, and what is it wired to?
+
+An affordance map of the page. Usually a better first move than `hj tree` or a screenshot when
+you're deciding what to *do*: structural, deterministic (no fonts/theme/viewport/animation timing),
+and dense — a small page is a few hundred bytes (~100 tokens) against ~1–1.5k vision tokens for a
+screenshot.
+
+Two tiers, and the response always says which one produced it:
+
+- **`source: "tosi-agent"`** — when the page exposes an agent surface (`globalThis.tosiAgent`, a
+  tosijs app calling `enableAgentInterface()`), the map is the app's **own wiring records**, passed
+  through unchanged. Those carry what the DOM cannot: which state path each control is bound to and
+  in which **direction** (`⟷` two-way/user-writable, `⟵` display-only, absent = static), the handler
+  path each event calls, and the callable actions. Act through the paths rather than synthesizing
+  input — `hj eval "tosiAgent.write('app.filter','milk')"` — and note that writing a `⟵`
+  display-only path via the DOM won't stick, which is exactly the "I typed into it and nothing
+  happened" trap.
+- **`source: "dom"`** — any other page: structural, visible-only, each node carrying a `ref` for
+  `hj click <ref>`. Labelled an approximation with **no** binding provenance, so it can't be
+  mistaken for real wiring.
+
+Credit to the tosijs agent for the idea (#12).
+
+## 1.7.0
+
+### New: capture a `<canvas>` directly — `hj screenshot --canvas <selector>`
+
+Reads the canvas's own pixels (`toDataURL`) instead of capturing the screen. For a WebGL scene
+(Babylon/three.js) or a UI rendered into a texture that means **exact pixels at native resolution,
+no screen-share grant, no desktop app required** — and it works even when the canvas is scrolled
+out of view or the tab isn't frontmost. Takes the same `--scale`/`--format`/`--max-width`/file
+options as any screenshot.
+
+It also handles the trap that makes naive canvas capture untrustworthy: a WebGL context clears its
+drawing buffer after compositing unless created with `{ preserveDrawingBuffer: true }`, so
+`toDataURL` can hand back a **blank image with no error**. Haltija samples the result and returns a
+`warning` explaining the likely cause instead of a silent empty picture — and deliberately doesn't
+cry wolf: a canvas with real content warns not at all, and a uniform *opaque* colour (which may be a
+perfectly legitimate solid background) gets a softer note than a fully transparent one. A canvas
+tainted by cross-origin textures returns a clear CORS error rather than crashing.
+
+### New: adopter-context test lane
+
+The suite now includes tests that reproduce the *dirty machine* adopters actually have — a server
+already running with zero windows, two projects in different directories each expecting their own,
+and ambiguous targeting from an unrelated directory. Every field bug this project has shipped lived
+in that gap, invisible to a suite that starts from nothing.
+
 ## 1.6.1
 
 Makes haltija's detection reachable by automation ([#8](https://github.com/tonioloewald/haltija/issues/8),

package/apps/desktop/package.json

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