haltija 1.6.0 → 1.11.0

package/CHANGELOG.md

@@ -1,5 +1,171 @@
 # Changelog
 
+## 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),
+[#11](https://github.com/tonioloewald/haltija/issues/11)).
+
+haltija already *detects* the situations that wreck a test lane — the wrong project's browser, a
+hidden tab returning stale results, a server with nothing to drive. It only ever **warned on
+stderr**, so scripts consumed plausible-but-wrong results and failed much later, pointing at the
+caller's own code.
+
+### New: `ready` — "server is up" is not "server is drivable"
+
+`/status` and `/windows` now return **`ready`**: true when at least one top-level tab is connected.
+A server running with *zero* windows answers `/status` 200, so an adopter's reuse probe skipped
+starting its own browser and then had nothing to navigate. Gate a lane on `ready`, not on the 200.
+
+### New: `hj doctor`
+
+One-command preflight that **exits non-zero**: server reachable → a tab is connected → the target
+isn't ambiguous → tabs aren't all hidden → versions aligned. `--json` for machine-readable output.
+Use it as the wait-loop condition in CI.
+
+### New: `hj --strict` / `HALTIJA_STRICT=1`
+
+Turns the advisory warnings into **non-zero exits**, and refuses to print a suspect result to
+stdout at all — a script must not consume a value that may be wrong. A warning is the right default
+for a human at a prompt and the wrong one for a lane.
+
+### Fixed
+
+- **Warning de-duplication silently defeated strict mode.** The server withheld a repeated warning
+  entirely, so the first command in a lane failed and every later one within the cooldown passed.
+  The server now always reports the condition and marks repeats (`warningRepeated`); de-dup is a
+  presentation concern, so `hj` stays quiet on a repeat while `--strict` fails on any warning.
+
 ## 1.6.0
 
 Consolidating release: rolls up everything from 1.5.2–1.5.7 (the last npm-published version was

package/apps/desktop/package.json

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