bin/vh textcheck: canvas text covered by the picture, too faint, or out of the frame

[ZLHad]

npx hyperframes check measures DOM text only; text a script draws into a <canvas> is pixels to it. The icecube film's own tools/occlusion.mjs measured its reads by drawing each frame with and without text and found 3 with too little contrast that frame review had missed. That script was tied to the one film (its txt/kin functions, a global context, __drawAt, hard-coded caption band, offset and size, system Chrome through a transitive puppeteer-core). This makes the method a command any canvas film can run.

How a film opts in: one line in the composition's inline script.

window.__vh = { draw: (t) => drawFrame(t), texts: TEXTS };   // texts optional: readcheck's texts.json format

The film's own text functions stay as they are: before its scripts run, the check hooks fillText / strokeText, records every call (string, transform, font state, alpha, colour) and can skip chosen calls. A read matches the calls that spell it with whitespace, punctuation and symbols left out, so kinetic type drawn one character at a time, a line drawn in parts, and a "·" or an arrow drawn as a shape all match.

What it measures for each registered read (--texts, else window.__vh.texts, else out/texts.json), at 3 times across its window:

• A = the frame as drawn, B = the same frame with only this read skipped, M = the read alone as a mask;
• shown: the glyph pixels that differ from B or are the read's own colour; under 70% = covered;
• contrast: its contrast with the picture under it, and with a 2–4 px ring around it in A (so an outline, a shadow or a plate counts); both under 3:1 = too faint;
• outside or cut by the frame; under a DOM caption (data-read="subtitle", readcheck's mark); the frame function throwing.

Those exit 1; 2 means it could not check (no window.__vh.draw, no browser, or no canvas text measured at all). The picture is every canvas, video and image of the page over its background, so text on a transparent layer is measured against the layer behind it. Warnings only: canvas text outside the registry (scanned every second), reads missing from some samples or never drawn as canvas text, captions over a bright picture (the pixels under their lines within 3:1 of the caption's colour), a frame not the same when drawn twice. Crops and every number go to out/check/textcheck/. Thresholds are options.

No npm dependency: Node drives a headless Chrome over the DevTools protocol through --remote-debugging-pipe and serves the project folder on 127.0.0.1. bin/vh textcheck picks CHROME_PATH, else HyperFrames' chrome-headless-shell, else Chrome or Chromium. Pixels are copied into the check's own canvas before reading: repeated getImageData on the film's canvas made Chrome move it off the GPU, and every later frame drew on the CPU (the caption scan went from 1.2 s to 26 s after the read phase).

Docs: engines/README.md (HyperFrames, 画面文字检查): the contract and what it cannot see (text in images, WebGL or an offscreen canvas); playbook/02-verification.md layer 2; CHANGELOG; CLAUDE.md command list, AGENTS.md regenerated.

Checks

• tools/ci.sh --committed passes, also with VH_BASH=/bin/bash; shellcheck and pyflakes ran through the uv recipe. The new smoke test runs bin/vh textcheck on tools/textcheck/fixture/ (one read per case: clear, covered, faint, outlined over a bright panel, kinetic, split with a drawn dot, above the frame, under the caption, drawn late, never drawn; a faint unregistered line; a caption over a bright band) and checks each verdict in the JSON; also that a composition without window.__vh exits 2 and names the line to add. Skipped where no Chrome is found (GitHub's runners have one).
• Ran with chrome-headless-shell 150 and 152 (HyperFrames' own) and with Chrome 154; no Chrome process left behind, also when the output pipe closes early.
• A copy of the 457 s icecube film with the line added (the project itself untouched): 107 reads in about 13 s on an M3 Max. 105 pass; one (θ ≈ 41°) is drawn above the frame at its sample time; the AP quote is an image; ten reads are missing from their first sample (0.4 s after the registered start); outside the registry, two dim notes under 3:1 (（事件图为示意） 1.7:1, （银河带为示意） 2.2:1), one line outside the frame, one cut by its edge; two captions over a bright picture (13.25 s, 351.75 s; readable through their text-shadow, but close).

Independent review (one reviewer, findings confirmed with small test pages, all fixed in the second commit): every run waited out a 30 s start timer; a wrapper forwarding maxWidth as undefined emptied the mask, so a fully covered read passed; text on a transparent canvas was measured against black (now composited with what is behind it); a dead browser hung until the 15-minute watchdog and a bad browser path crashed with exit 1; a run that measured nothing exited 0; a glow pass made a read look always faded; the usage line left out two options. Re-checked: each of those cases now fails or exits 2 as it should; the fixture and the film give the same verdicts as before.

Merging with #67: #67 adds a paragraph to the same place in playbook/02-verification.md layer 2 (the method, "wired up in each project") and a CHANGELOG line saying it stays a method rather than a command. Whichever merges second resolves it: this bullet replaces #67's, and that CHANGELOG line goes.