From 2966f19b96e3be754bf7425671191ab775b41035 Mon Sep 17 00:00:00 2001
From: zhanglinghao <zhangczssx@gmail.com>
Date: Wed, 7 Oct 2026 00:50:49 +0800
Subject: [PATCH 1/4] bin/vh textcheck: canvas text covered by the picture, too
 faint, or out of the frame

npx hyperframes check measures DOM text only; text a script draws into a canvas is
pixels to it. A canvas film's own script found reads with too little contrast that
frame review had missed. This turns that method into a command any canvas film can
run with one line in the composition: window.__vh = { draw(t), texts? }.

- tools/textcheck: hooks fillText/strokeText before the page's scripts, draws each
  read's frame with and without it plus the read alone as a mask: share shown,
  contrast with the picture and with its edge, out of frame, under a DOM caption.
  Canvas text outside the registry and captions over a bright picture warn.
  No npm dependency: CDP over --remote-debugging-pipe, a static server on 127.0.0.1.
- bin/vh textcheck finds the browser: CHROME_PATH, HyperFrames' headless shell,
  then Chrome or Chromium.
- engines/README (the contract), playbook/02 layer 2, CHANGELOG, CLAUDE.md command
  list and AGENTS.md; tools/ci.sh runs it on a fixture with one read per case.
---
 AGENTS.md                          |   2 +-
 CHANGELOG.md                       |   9 +
 CLAUDE.md                          |   2 +-
 bin/vh                             |  21 +-
 engines/README.md                  |  18 ++
 playbook/02-verification.md        |   1 +
 tools/ci.sh                        |  37 +++-
 tools/textcheck/browser.mjs        |  76 +++++++
 tools/textcheck/fixture/index.html |  63 ++++++
 tools/textcheck/page.js            | 327 +++++++++++++++++++++++++++++
 tools/textcheck/textcheck.mjs      | 270 ++++++++++++++++++++++++
 11 files changed, 821 insertions(+), 5 deletions(-)
 create mode 100644 tools/textcheck/browser.mjs
 create mode 100644 tools/textcheck/fixture/index.html
 create mode 100644 tools/textcheck/page.js
 create mode 100644 tools/textcheck/textcheck.mjs

diff --git a/AGENTS.md b/AGENTS.md
index df4c0e2..e3a7ed3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -108,7 +108,7 @@ OpenVideoHarness/
 ├── CLAUDE.md / AGENTS.md     入口（本文件；AGENTS.md 由 bin/vh sync-agents 生成，内容相同）
 ├── README.md / README.zh-CN.md  给人看的说明；CONTRIBUTING.md 是改本仓库时的规则；install.sh 一键安装
 ├── LOCAL.md                  本机环境（不入库；模板是 LOCAL.example.md）
-├── bin/vh                    命令行：doctor · setup · types · effort · new · style · recipes · hf-init · install-skill · sync-agents · tts · voices · captions · beats · music · sfx · mix · mux · qa · readcheck · storyboard · rhythm · cover-preview · sheet · check · gif · review · desk
+├── bin/vh                    命令行：doctor · setup · types · effort · new · style · recipes · hf-init · install-skill · sync-agents · tts · voices · captions · beats · music · sfx · mix · mux · qa · readcheck · textcheck · storyboard · rhythm · cover-preview · sheet · check · gif · review · desk
 ├── tools/                    bin/vh 背后的脚本；audio/README.md 是声音命令的参数手册，desk/README.md 是审阅台的读取约定；ci.sh 是仓库自检
 ├── skills/open-video-harness/  轻量 skill：在任何目录把做视频的请求引到本仓库
 ├── video-types/              9 类视频（09 实验中）：工作流、审美、禁止项、Prompt 增量块、自查重点、案例
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4f6059b..bb79c71 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+**`bin/vh textcheck`: canvas text covered by the picture, too faint, or out of the frame**
+- Why: `npx hyperframes check` measures DOM text only; text a script draws into a `<canvas>` is pixels to it. A 457 s canvas film's own script measured its 106 reads this way and found 3 with too little contrast that frame review had missed. This makes that check a command any canvas film can run.
+- A composition opts in with one line, `window.__vh = { draw: (t) => …, texts }` (`texts` optional). Before its scripts run, the check hooks the canvas's `fillText` and `strokeText`, so the film's own text functions stay as they are: kinetic type drawn one character at a time, a line drawn in parts, and a "·" or an arrow drawn as a shape still match the read.
+- For each registered read (`--texts`, else `window.__vh.texts`, else the `out/texts.json` readcheck reads), at 3 times across its window: the frame as drawn, the frame without that read and the read alone as a mask give the share of its glyphs that show (under 70%: covered), and its contrast with the picture under it and with what is right around it, so an outline, a shadow or a plate counts (both under 3:1: too faint). Outside or cut by the frame and under a DOM caption also fail; so does a frame function that throws. Exit 1 on any of those, 2 when it could not check.
+- Warnings only: canvas text outside the registry (scanned every second, each line judged once where it is most opaque), reads missing from some samples or never drawn as canvas text, DOM captions (`data-read="subtitle"`) over a bright picture (the share of the pixels under their lines within 3:1 of the caption's colour), and a frame that is not the same when drawn twice. Crops and every number go to `out/check/textcheck/`.
+- No npm dependency: Node drives a headless Chrome over the DevTools protocol through a pipe, and serves the project folder on 127.0.0.1. The browser: `CHROME_PATH`, HyperFrames' chrome-headless-shell, then Chrome or Chromium. Pixels are copied into the check's own canvas before reading, because after a few `getImageData` calls Chrome moves a canvas off the GPU and the film then draws every later frame on the CPU, many times slower.
+- On a copy of the 457 s film with the line added (107 reads, about 30 s on an M3 Max): one read drawn above the frame at its sample time, one read that is an image, ten reads missing from their first sample, two dim notes outside the registry under 3:1, one line outside the frame and one cut by its edge, two captions over a bright picture.
+- engines/README (HyperFrames, 画面文字检查): the contract and what it cannot see (text in images, WebGL or an offscreen canvas); playbook/02 layer 2: the method and the command; tools/ci.sh runs it on a fixture with one read per case, skipped where no Chrome is found.
+
 **Lessons from four films go into the docs**
 - Why: the maintainer asked that the general lessons kept in the agent's memory notes and in project LESSONS.md files move into the docs, leaving out what is personal to one channel. They come from 《发送之后》, a news film (FZ1073), the 3-minute tech-history film and the review rounds of 2026-10-04/05.
 - playbook/09 §10 (new): how narration, title cards and labels read as written by a person. Let the fact carry the heaviest beat; vary sentence length; the sentence shapes models reach for (parallelism, triplets, "不是……而是……"); spoken words; explanations go into labels; one common way to end (from this case to this kind of case, back to the person) in plain words; a caption-only script goes out with the gate ② storyboard (or stops on its own when the human owns `script`). A default, overridden by a concept that wants another voice; any film with narration or cards reads it. `templates/SCRIPT.md` points there from both of its comments; the concept card's 首尾 line goes down to the last line or last picture (a 3-minute film changed its ending three times at gate ③).
diff --git a/CLAUDE.md b/CLAUDE.md
index 12b8731..8283e62 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -105,7 +105,7 @@ OpenVideoHarness/
 ├── CLAUDE.md / AGENTS.md     入口（本文件；AGENTS.md 由 bin/vh sync-agents 生成，内容相同）
 ├── README.md / README.zh-CN.md  给人看的说明；CONTRIBUTING.md 是改本仓库时的规则；install.sh 一键安装
 ├── LOCAL.md                  本机环境（不入库；模板是 LOCAL.example.md）
-├── bin/vh                    命令行：doctor · setup · types · effort · new · style · recipes · hf-init · install-skill · sync-agents · tts · voices · captions · beats · music · sfx · mix · mux · qa · readcheck · storyboard · rhythm · cover-preview · sheet · check · gif · review · desk
+├── bin/vh                    命令行：doctor · setup · types · effort · new · style · recipes · hf-init · install-skill · sync-agents · tts · voices · captions · beats · music · sfx · mix · mux · qa · readcheck · textcheck · storyboard · rhythm · cover-preview · sheet · check · gif · review · desk
 ├── tools/                    bin/vh 背后的脚本；audio/README.md 是声音命令的参数手册，desk/README.md 是审阅台的读取约定；ci.sh 是仓库自检
 ├── skills/open-video-harness/  轻量 skill：在任何目录把做视频的请求引到本仓库
 ├── video-types/              9 类视频（09 实验中）：工作流、审美、禁止项、Prompt 增量块、自查重点、案例
diff --git a/bin/vh b/bin/vh
index 1d6e044..f20a5cd 100755
--- a/bin/vh
+++ b/bin/vh
@@ -57,6 +57,10 @@
 #                               FAIL under one brisk read (CJK/7 + other/20 + 0.8 s, at least 1.5 s; exit 1), WARN under the target of the BRIEF's
 #                               Pace (exit 0); subtitles within reading speed. data-read="subtitle"|"label" and data-pace="…" mark clips
 #                               readcheck --budget <s>: how many characters fit in a span · readcheck <index.html|project> --export [--out f]: the composition's timed text
+#   textcheck <project|index.html> [--texts f.json] [--min-visible 0.7] [--min-contrast 3] [--samples 3] [--scan-step 1] [--caption-step 0.5] [--out dir] [--soft-gl]
+#                               text drawn into a canvas, which npx hyperframes check cannot see: a read covered by the picture (under 70% of it
+#                               shows), under 3:1, outside or cut by the frame, or under a DOM caption (exit 1); canvas text outside the registry
+#                               and captions over a bright picture warn. The composition opts in with window.__vh = { draw(t), texts? } (engines/README.md)
 #   sheet <video> [cols] [fps] [out]  contact sheet (default: <project>/out/check/<name>-sheet-<HHMMSS>.png)
 #   check <video> [--allow t,t…] [--against <ref.mp4>]  ffprobe + the BRIEF's spec (size, rate, length; exit 1 on a mismatch) +
 #                               black/freeze/silence detection + isolated-frame scan (one-frame capture glitches; exit 1 on any not declared
@@ -439,6 +443,21 @@ for l in rules.splitlines():
 }
 
 cmd_readcheck() { python3 "$ROOT/tools/readcheck.py" "$@"; }
+hf_shell() { # the chrome-headless-shell binary itself (hf_chrome prints its version folder)
+  local p; p=$(hf_chrome) || return 1
+  [ -f "$p" ] && [ -x "$p" ] && { echo "$p"; return 0; }
+  p=$(find "$p" -maxdepth 3 -type f \( -name chrome-headless-shell -o -name chrome-headless-shell.exe \) 2>/dev/null | head -1)
+  [ -n "$p" ] && echo "$p"
+}
+cmd_textcheck() { # canvas text covered or too faint (tools/textcheck/textcheck.mjs). The browser: CHROME_PATH, HyperFrames'
+  # chrome-headless-shell (what renders the film), then Chrome or Chromium; no npm package needed
+  [ $# -gt 0 ] || { cmd_usage textcheck; exit 1; }
+  local b=${CHROME_PATH:-}
+  if [ -z "$b" ] || [ ! -x "$b" ]; then
+    b=$(hf_shell) || b=$(chrome_path) || { echo "$c_no bin/vh textcheck needs a headless Chrome: npx hyperframes browser ensure (in a HyperFrames project), install Chrome or Chromium, or set CHROME_PATH" >&2; exit 2; }
+  fi
+  exec node "$ROOT/tools/textcheck/textcheck.mjs" --browser "$b" "$@"
+}
 cmd_storyboard() { [ $# -gt 0 ] || { echo "usage: bin/vh storyboard <project> [--video v.mp4 | --snapshot] [--unsure S02,S04] [--per 6]   (-h: the shots.json schema)"; exit 1; }
   uv run -q --no-project --with pillow python "$ROOT/tools/storyboard.py" "$@"; }
 cmd_rhythm() { [ $# -gt 0 ] || { echo "usage: bin/vh rhythm <project> [--segment NAME | --from s --to s] [--max s] [--out file.png]"; exit 1; }
@@ -758,7 +777,7 @@ case "${1:-help}" in
   recipes) shift; python3 "$ROOT/tools/recipes.py" "$@" ;;
   review) shift; cmd_review "$@" ;;
   desk) shift; cmd_desk "$@" ;;
-  new) shift; cmd_new "$@" ;; style) shift; cmd_style "$@" ;; readcheck) shift; cmd_readcheck "$@" ;;
+  new) shift; cmd_new "$@" ;; style) shift; cmd_style "$@" ;; readcheck) shift; cmd_readcheck "$@" ;; textcheck) shift; cmd_textcheck "$@" ;;
   storyboard) shift; cmd_storyboard "$@" ;; rhythm) shift; cmd_rhythm "$@" ;; cover-preview) shift; cmd_cover_preview "$@" ;; effort) shift; cmd_effort "$@" ;; sync-agents) cmd_sync_agents ;; hf-init) shift; cmd_hf_init "$@" ;; sheet) shift; cmd_sheet "$@" ;; check) shift; cmd_check "$@" ;; gif) shift; cmd_gif "$@" ;;
   help|-h|--help) cmd_help ;;
   *) { echo "unknown command: $1"; echo; cmd_help; } >&2; exit 1 ;;
diff --git a/engines/README.md b/engines/README.md
index 03d11fb..73e3a9b 100644
--- a/engines/README.md
+++ b/engines/README.md
@@ -100,6 +100,24 @@ HYPERFRAMES_RENDER_DETACHED=1 nohup caffeinate -i npx hyperframes render --quali
 
 - **写一段，查一段**：`npx hyperframes lint` 到 0 error 再往下；`snapshot --at <秒> --describe false` 看几个关键时刻的单帧；`render --quality draft --fps 30 --output out/draft.mp4` 出草稿，字体和接缝以渲出来的 mp4 为准；最后 `--quality delivery` 出成片。完整写法见上面那一块命令。
 
+### 画面文字检查（canvas 片子）
+
+`npx hyperframes check` 只量 DOM 文字，脚本画进 `<canvas>` 的字在它眼里只是像素。canvas 片子用 `bin/vh textcheck <项目>` 查：哪条字被后画的东西盖住、和画面对比不够、出了画面或被边缘裁掉、被 DOM 字幕压住。合成的内联脚本里加一行就能用：
+
+```js
+window.__vh = {
+  draw: (t) => drawFrame(t),   // 必填：画出第 t 秒，连同它自己管的 DOM（比如字幕），和渲染出的那一帧一样；可以返回 Promise
+  texts: TEXTS,                // 可选：reads 登记表，格式同 readcheck 的 texts.json：[{text, start, end, read?}]
+};
+```
+
+- **画字的函数不用改。** 检查在合成的脚本运行之前挂上 canvas 的 `fillText` / `strokeText`，记下每条字画在哪、用什么字体，能单独去掉一条字重画这一帧。所以字要用 2D canvas 的 `fillText` / `strokeText` 画：做成图片的、画进 WebGL 的、画在离屏 canvas 里再贴上来的字，它看不到，登记了会报"没画成 canvas 字"。逐字出现的动画字、拆成几次画的一行字、中间的"·"和箭头画成图形的，都按字母对得上。
+- **登记表**：命令行给了 `--texts <文件>` 就用它，否则用 `window.__vh.texts`，再没有就读 `out/texts.json`（readcheck 读的同一份）。每条在它的时间窗里取 3 个时刻（开始后 0.4 s 到结束前 0.3 s），所以 start 要是字完整显示的那一刻，这也是 readcheck 的约定；登记早了会报"有的时刻没画全"。没有登记表也能跑，只做下面那遍扫描。
+- **没登记的字**每秒扫一遍全片，每行字在它最完整的那一刻量一次，有问题只警告：观众该读的，就登记进去。
+- `draw(t)` 要是 t 的纯函数（硬规则 1）：同一个 t 会画好几遍，两遍画面不一样会报出来，那一刻的数字不可信。
+- **浏览器**：`CHROME_PATH`，否则用 HyperFrames 渲染用的 chrome-headless-shell（缓存为空时先 `npx hyperframes browser ensure`），再否则用系统的 Chrome 或 Chromium，不用装 npm 包。合成从项目目录起一个只在本机 127.0.0.1 的服务来打开，尺寸按根元素的 `data-width` × `data-height`，设备像素比 1；先等 `window.__hf.buildReady`、`window.__vh.ready`（可选）和字体加载完。
+- **结果**：有登记的 read 被盖住（露出不到 70%）、低于 3:1、出画或被裁、压在字幕下，或画帧函数抛错，退出码 1；没登记的字、字幕底下的画面太亮只警告；没法检查（没有 `window.__vh.draw`、页面没加载起来、找不到浏览器）是 2，不算通过。每处问题存一张裁图到 `out/check/textcheck/`，全部数字在同一目录的 `textcheck.json`；阈值都能调，见 `bin/vh textcheck -h`。一支 457 s、107 条登记文字的片子在 M3 Max 上约 30 s 跑完。
+
 ### 注意事项和已知问题（0.8.82 实测）
 
 - **`snapshot` 一律带 `--describe false`。** 环境里有 `GEMINI_API_KEY`（或 `GOOGLE_API_KEY`）时，`snapshot` 默认把每一帧发给 Gemini 做画面描述，结果写进 `snapshots/descriptions.md`：画面离开本机，还要按 Gemini 计费。本仓库的 `bin/vh tts … --align gemini` 也要这个 key，所以 key 多半是设了的。`--describe false` 和 `--describe=false` 都能关掉；没设 key 时它只打一行 "skipping"。`check` 不受影响。
diff --git a/playbook/02-verification.md b/playbook/02-verification.md
index ee77df2..c855e9d 100644
--- a/playbook/02-verification.md
+++ b/playbook/02-verification.md
@@ -12,6 +12,7 @@
 1. **能不能跑**：lint、编译、dry-run。Manim 的报错按 ScopeRefine 的顺序修：先改出错行前后 ±1 行，不行就改整个代码块，再不行就重写整个场景。
 2. **不看图的结构检查**（确定性检验：从中间抽几帧单独渲染，和整片里的同一帧比对，要逐像素相同，或者 PSNR ≥ 45 dB；比的是无损 PNG 帧，不是编码后的 mp4，原因见下文"确定性"；`ffmpeg -i a.png -i b.png -lavfi psnr -f null -`）：
    - 渲染器自带的检查，例如 HyperFrames `check` 会查 DOM 包围盒、文字溢出和对比度；
+   - canvas 里画的字，`check` 看不到：canvas 片子跑 `bin/vh textcheck <项目>`，合成里要有一行 `window.__vh`（`engines/README.md`"画面文字检查"）。它把同一帧画两遍，一遍照常、一遍单独去掉这条字，再把这条字单独画一遍当掩膜：字自己的像素里，两遍不同的（或者正是字自己颜色的）占多少，就是露出来多少，不到七成算被盖住；字和底下画面的对比、和紧挨着它一圈（描边、阴影、底板都算）的对比，两个都低于 3:1 算看不清；出画、被边缘裁掉、压在 DOM 字幕下也算。没登记的 canvas 字和字幕底下的画面亮度另外扫一遍，只警告。一支 457 s 的片子这样扫了全部 106 条画面文字，找出 3 条对比度不够的，翻帧时都没看出来；
    - 打印所有对象的包围盒，检查有没有重叠（SGA 的做法）；
    - 用像素统计找空白帧和卡住的帧：逐帧 YAVG 找突降，逐帧和第 0 帧比 PSNR，见下文"静默失败"；
    - 黑场、冻结、静音检测（命令见下文），孤立帧扫描（`bin/vh check` 一并做，见下文"静默失败"）；
diff --git a/tools/ci.sh b/tools/ci.sh
index f397d10..6df26a5 100755
--- a/tools/ci.sh
+++ b/tools/ci.sh
@@ -752,12 +752,45 @@ PY
   rm -rf "$t"
 }
 
+# bin/vh textcheck on its fixture (tools/textcheck/fixture/index.html: one read per case), with whatever headless Chrome
+# the machine has (GitHub's runners come with Chrome); skipped without one
+textcheck_checks() {
+  local t a rc
+  t=$(mktemp -d "${TMPDIR:-/tmp}/vh-ci.XXXXXX")
+  a=$(vh textcheck tools/textcheck/fixture --out "$t/out" 2>&1); rc=$?
+  case "$rc:$a" in 2:*"needs a headless Chrome"*) skip "textcheck" "no Chrome, Chromium or chrome-headless-shell"; rm -rf "$t"; return ;; esac
+  if [ $rc = 1 ] && python3 - "$t/out/textcheck.json" <<'PY'
+import json, sys
+d = json.load(open(sys.argv[1], encoding="utf-8"))
+got = {r["text"]: (r["status"], sorted(f for f in ((r.get("worst") or {}).get("flags") or []) if f != "unstable")) for r in d["reads"]}
+want = {"CLEAR": ("ok", []), "COVERED": ("fail", ["covered"]), "FAINT": ("fail", ["contrast"]), "OUTLINED": ("ok", []), "KINETIC": ("ok", []),
+        "TWO · PARTS": ("ok", []), "GONE": ("fail", ["outside"]), "HIDDEN": ("fail", ["caption"]), "LATE": ("ok", []), "NOWHERE": ("not drawn", [])}
+bad = [f"{k}: got {got.get(k)}, want {v}" for k, v in want.items() if got.get(k) != v]
+late = [r for r in d["reads"] if r["text"] == "LATE"]
+if not late or late[0].get("missingAt") != [0.4]: bad.append(f"LATE: missing at {late[0].get('missingAt') if late else None}, want [0.4]")
+flagged = [e["text"] for e in d["extra"] if e["flagged"]]
+if flagged != ["ghost"]: bad.append(f"outside the registry: flagged {flagged}, want ['ghost']")
+bright = [c["text"] for c in d["captions"] if c["worst"]["close"] > 0.12]
+if bright != ["a caption over a bright band"]: bad.append(f"captions over a bright picture: {bright}")
+print("\n".join(bad))
+sys.exit(1 if bad else 0)
+PY
+  then ok "textcheck: covered, faint, out-of-frame and captioned-over reads fail (exit 1); outlined, kinetic and split reads pass; a late read, a faint line outside the registry and a caption over a bright band warn"
+  else bad "textcheck on its fixture (exit $rc): $(printf '%s' "$a" | head -c 800)"; fi
+  # without the contract: nothing can be drawn on demand, so exit 2 and say what to add
+  sed 's/window.__vh = { draw, texts: TEXTS };//' tools/textcheck/fixture/index.html > "$t/index.html"
+  a=$(vh textcheck "$t" --out "$t/out2" 2>&1); rc=$?
+  case "$rc:$a" in 2:*"window.__vh = { draw"*) ok "textcheck without window.__vh.draw exits 2 and names the line to add" ;;
+    *) bad "textcheck without the contract: exit $rc: $(printf '%s' "$a" | head -c 300)" ;; esac
+  rm -rf "$t"
+}
+
 case "${1:-all}" in
-  --smoke) smoke_checks; decision_checks; desk_checks ;;
+  --smoke) smoke_checks; decision_checks; desk_checks; textcheck_checks ;;
   --committed)   # exactly what a push would send: HEAD in a clean temporary checkout, uncommitted changes left out
     w="$(mktemp -d "${TMPDIR:-/tmp}/vh-ci.XXXXXX")/head"; git worktree add -q --detach "$w" HEAD || exit 2
     (cd "$w" && tools/ci.sh); rc=$?; git worktree remove --force "$w"; rmdir "$(dirname "$w")"; exit $rc ;;
-  all) static_checks; doc_checks; smoke_checks; decision_checks; desk_checks ;;
+  all) static_checks; doc_checks; smoke_checks; decision_checks; desk_checks; textcheck_checks ;;
   *) echo "usage: tools/ci.sh [--smoke | --committed]"; exit 2 ;;
 esac
 [ $fails = 0 ] && ok "all checks passed" || printf '\033[31m%s check(s) failed\033[0m\n' "$fails"
diff --git a/tools/textcheck/browser.mjs b/tools/textcheck/browser.mjs
new file mode 100644
index 0000000..dca7fa0
--- /dev/null
+++ b/tools/textcheck/browser.mjs
@@ -0,0 +1,76 @@
+// A headless Chrome driven over the DevTools protocol through a pipe (--remote-debugging-pipe), and a static file server
+// for the composition. No npm dependencies: Node's child_process and http are enough for what textcheck needs, so it runs
+// in any project and in CI without puppeteer.
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+
+// launch(exe, flags) → { send(method, params, sessionId), once(event, sessionId), close(), version }
+export async function launch(exe, flags = []) {
+  const profile = fs.mkdtempSync(path.join(os.tmpdir(), "vh-textcheck-"));
+  const args = ["--headless", "--remote-debugging-pipe", "--no-first-run", "--no-default-browser-check", `--user-data-dir=${profile}`,
+    "--hide-scrollbars", "--mute-audio", "--force-color-profile=srgb", ...flags, "about:blank"];
+  const proc = spawn(exe, args, { stdio: ["ignore", "ignore", "pipe", "pipe", "pipe"] });
+  let stderr = "";
+  proc.stderr.on("data", (d) => { stderr = (stderr + d).slice(-4000); });
+  const exited = new Promise((res) => { proc.on("exit", res); proc.on("error", (e) => { stderr += String(e); res(); }); });
+  const out = proc.stdio[3], inp = proc.stdio[4];
+  const pending = new Map(), waiters = [], listeners = [];
+  let buf = Buffer.alloc(0), id = 0;
+  inp.on("data", (d) => {
+    buf = Buffer.concat([buf, d]);
+    for (let i; (i = buf.indexOf(0)) >= 0;) {
+      const m = JSON.parse(buf.subarray(0, i).toString("utf8"));
+      buf = buf.subarray(i + 1);
+      if (m.id !== undefined && pending.has(m.id)) {
+        const p = pending.get(m.id); pending.delete(m.id);
+        if (m.error) p.reject(new Error(`${p.method}: ${m.error.message}${m.error.data ? " (" + m.error.data + ")" : ""}`)); else p.resolve(m.result);
+      } else if (m.method) {
+        for (const w of waiters.slice()) if (w.method === m.method && (!w.session || w.session === m.sessionId)) { waiters.splice(waiters.indexOf(w), 1); w.resolve(m.params); }
+        for (const l of listeners) if (l.method === m.method) l.fn(m.params);
+      }
+    }
+  });
+  const send = (method, params = {}, sessionId) => new Promise((resolve, reject) => {
+    const i = ++id; pending.set(i, { resolve, reject, method });
+    out.write(JSON.stringify({ id: i, method, params, ...(sessionId ? { sessionId } : {}) }) + "\0");
+  });
+  const once = (method, session) => new Promise((resolve) => waiters.push({ method, session, resolve }));
+  const on = (method, fn) => listeners.push({ method, fn });
+  const close = async () => {
+    try { await Promise.race([send("Browser.close"), new Promise((r) => setTimeout(r, 3000))]); } catch { /* already gone */ }
+    proc.kill(); await exited;
+    fs.rmSync(profile, { recursive: true, force: true });
+  };
+  let version;
+  try {
+    version = await Promise.race([send("Browser.getVersion"), exited.then(() => { throw new Error("the browser exited at start: " + stderr.trim().split("\n").slice(-3).join(" | ")); }),
+      new Promise((_, rej) => setTimeout(() => rej(new Error("the browser did not answer within 30 s")), 30000))]);
+  } catch (e) { proc.kill(); fs.rmSync(profile, { recursive: true, force: true }); throw e; }
+  return { send, once, on, close, version: version.product };
+}
+
+const TYPES = { ".html": "text/html; charset=utf-8", ".htm": "text/html; charset=utf-8", ".js": "text/javascript", ".mjs": "text/javascript", ".css": "text/css",
+  ".json": "application/json", ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp", ".avif": "image/avif",
+  ".svg": "image/svg+xml", ".woff2": "font/woff2", ".woff": "font/woff", ".ttf": "font/ttf", ".otf": "font/otf", ".wav": "audio/wav", ".mp3": "audio/mpeg",
+  ".m4a": "audio/mp4", ".mp4": "video/mp4", ".webm": "video/webm", ".mov": "video/quicktime", ".wasm": "application/wasm", ".glsl": "text/plain", ".txt": "text/plain" };
+
+// serve(dir) → { url, close() }: the folder on 127.0.0.1 (so module scripts, fetch and fonts work as they do in
+// HyperFrames' own preview, which file:// would block); no path out of it
+export async function serve(dir) {
+  const root = fs.realpathSync(dir);
+  const server = http.createServer((req, res) => {
+    let f;
+    try { f = path.join(root, decodeURIComponent(new URL(req.url, "http://x").pathname)); } catch { res.writeHead(400); return res.end(); }
+    // inside the folder by its path (a symlinked node_modules or assets folder is followed, as HyperFrames' preview does)
+    let ok = false;
+    try { ok = f.startsWith(root + path.sep) && fs.statSync(f).isFile(); } catch { /* missing */ }
+    if (!ok) { res.writeHead(404); return res.end(); }
+    res.writeHead(200, { "content-type": TYPES[path.extname(f).toLowerCase()] || "application/octet-stream", "cache-control": "no-store" });
+    fs.createReadStream(f).pipe(res);
+  });
+  await new Promise((res) => server.listen(0, "127.0.0.1", res));
+  return { url: `http://127.0.0.1:${server.address().port}/`, close: () => new Promise((res) => server.close(res)) };
+}
diff --git a/tools/textcheck/fixture/index.html b/tools/textcheck/fixture/index.html
new file mode 100644
index 0000000..0269f8b
--- /dev/null
+++ b/tools/textcheck/fixture/index.html
@@ -0,0 +1,63 @@
+<!doctype html>
+<!-- The test composition for bin/vh textcheck (tools/ci.sh). Each read below is a case; the comment says what the check
+     must say about it. Not a film: no GSAP, no HyperFrames, only the window.__vh contract. -->
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>textcheck fixture</title>
+    <style>
+      html, body { margin: 0; width: 640px; height: 360px; overflow: hidden; background: #000; }
+      #root { position: relative; width: 640px; height: 360px; }
+      #cv { position: absolute; left: 0; top: 0; width: 640px; height: 360px; }
+      #cap { position: absolute; left: 0; width: 640px; top: 318px; text-align: center; color: #fff; font: 700 22px sans-serif; white-space: nowrap; }
+    </style>
+  </head>
+  <body>
+    <div id="root" data-composition-id="main" data-start="0" data-duration="4" data-width="640" data-height="360">
+      <canvas id="cv" width="640" height="360"></canvas>
+      <div id="cap" data-read="subtitle"></div>
+    </div>
+    <script>
+      const X = document.getElementById("cv").getContext("2d");
+      const TEXTS = [
+        { text: "CLEAR", start: 0, end: 4 },                 // white on dark: passes
+        { text: "COVERED", start: 0, end: 4 },               // a panel drawn over it: covered
+        { text: "FAINT", start: 0, end: 4 },                 // grey on grey: contrast
+        { text: "OUTLINED", start: 0, end: 4 },              // white on white with a black outline: passes (the edge counts)
+        { text: "KINETIC", start: 0, end: 4 },               // one character a call: found, passes
+        { text: "TWO · PARTS", start: 0, end: 4 },           // the dot is a shape, the words two calls: found, passes
+        { text: "GONE", start: 0, end: 4 },                  // above the frame: outside
+        { text: "HIDDEN", start: 0, end: 4 },                // under the DOM caption: caption
+        { text: "LATE", start: 0, end: 4 },                  // only drawn after 2 s: missing from a sample
+        { text: "NOWHERE", start: 0, end: 4 },               // never drawn: not drawn
+      ];
+      function text(s, x, y, o = {}) {
+        X.save(); X.font = `700 ${o.size || 30}px sans-serif`; X.textAlign = o.align || "left"; X.textBaseline = "alphabetic";
+        if (o.stroke) { X.lineJoin = "round"; X.lineWidth = o.stroke; X.strokeStyle = "#000"; X.strokeText(s, x, y); }
+        X.fillStyle = o.color || "#fff"; X.fillText(s, x, y); X.restore();
+      }
+      function draw(t) {
+        X.setTransform(1, 0, 0, 1, 0, 0);
+        X.fillStyle = "#14181d"; X.fillRect(0, 0, 640, 360);
+        X.fillStyle = "#f2f2f2"; X.fillRect(320, 0, 320, 120);          // a bright panel, top right
+        X.fillStyle = "#444"; X.fillRect(0, 120, 320, 70);              // a grey panel, left
+        X.fillStyle = "#eeeeee"; X.fillRect(0, 300, 640, 60);           // a bright band under the caption
+        text("CLEAR", 20, 50);
+        text("COVERED", 20, 100);
+        X.fillStyle = "#2a6"; X.fillRect(14, 70, 150, 40);              // drawn after COVERED, over most of it
+        text("FAINT", 20, 165, { color: "#555" });
+        text("OUTLINED", 340, 70, { stroke: 8 });
+        let x = 340; for (const ch of "KINETIC") { text(ch, x, 165); x += X.measureText(ch).width + 22; }
+        text("TWO", 20, 245); X.fillStyle = "#fff"; X.beginPath(); X.arc(100, 235, 4, 0, 7); X.fill(); text("PARTS", 112, 245);
+        text("GONE", 400, -30);
+        text("HIDDEN", 250, 345, { size: 26, color: "#111" });
+        if (t >= 2) text("LATE", 400, 245);
+        text("ghost", 520, 290, { size: 22, color: "#26292d" });       // outside the registry, too dark: a warning
+        const cap = document.getElementById("cap");
+        cap.textContent = "a caption over a bright band";
+      }
+      window.__vh = { draw, texts: TEXTS };
+      draw(0);
+    </script>
+  </body>
+</html>
diff --git a/tools/textcheck/page.js b/tools/textcheck/page.js
new file mode 100644
index 0000000..c092594
--- /dev/null
+++ b/tools/textcheck/page.js
@@ -0,0 +1,327 @@
+// textcheck's side of the page: injected before the composition's own scripts (Page.addScriptToEvaluateOnNewDocument).
+// It records every fillText / strokeText on a canvas in the document (the string, the transform, the font state and the
+// alpha) and can skip chosen calls, so a frame can be drawn again without one read; it replays a read alone as a mask;
+// and it measures. The composition only provides window.__vh.draw(t) (engines/README.md, "画面文字检查").
+(() => {
+  if (window.__vhTC) return;
+  window.__timelines = window.__timelines || {};   // HyperFrames' runtime makes this; compositions register into it
+
+  const KEYS = ["font", "textAlign", "textBaseline", "direction", "letterSpacing", "wordSpacing", "fontKerning", "fontStretch", "fontVariantCaps", "textRendering"];
+  const SKEYS = ["lineWidth", "lineJoin", "miterLimit"];
+  const H = { rec: false, calls: [], skip: null, n: 0, t: null, errors: [] };
+  const alphaOf = (style) => {   // "rgba(r, g, b, a)" → a; gradients, patterns and opaque colours → 1
+    if (typeof style !== "string") return 1;
+    const m = style.match(/^rgba?\(([^)]*)\)$/);
+    if (!m) return 1;
+    const p = m[1].split(/[\s,/]+/).filter(Boolean);
+    return p.length >= 4 ? parseFloat(p[3]) / (p[3].endsWith("%") ? 100 : 1) : 1;
+  };
+  const P = CanvasRenderingContext2D.prototype;
+  const wrap = (orig, op) => function (s, x, y, maxWidth) {
+    const i = H.n++;
+    if (H.rec && this.canvas && this.canvas.isConnected) {
+      const st = {};
+      for (const k of KEYS) st[k] = this[k];
+      if (op === "stroke") for (const k of SKEYS) st[k] = this[k];
+      H.calls.push({ i, op, s: String(s), x: +x, y: +y, mw: arguments.length > 3 ? +maxWidth : undefined, m: this.getTransform(), st,
+        a: this.globalAlpha * alphaOf(op === "fill" ? this.fillStyle : this.strokeStyle), col: op === "fill" ? this.fillStyle : this.strokeStyle, cv: this.canvas });
+    }
+    if (H.skip && H.skip.has(i)) return;
+    return arguments.length > 3 ? orig.call(this, s, x, y, maxWidth) : orig.call(this, s, x, y);
+  };
+  P.fillText = wrap(P.fillText, "fill");
+  P.strokeText = wrap(P.strokeText, "stroke");
+  // a scene that throws inside the frame function, or catches and logs it, shows up as an error at that time
+  const logError = console.error;
+  console.error = function (...a) {
+    if (H.t !== null) H.errors.push({ t: H.t, msg: a.map((x) => (x && x.stack) || String(x)).join(" ") });
+    return logError.apply(this, a);
+  };
+  window.addEventListener("error", (e) => { if (H.t !== null) H.errors.push({ t: H.t, msg: String((e.error && e.error.stack) || e.message) }); });
+
+  // ---- helpers ----
+  const LIN = new Float32Array(256);
+  for (let i = 0; i < 256; i++) { const c = i / 255; LIN[i] = c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4); }
+  const lum = (d, p) => 0.2126 * LIN[d[p]] + 0.7152 * LIN[d[p + 1]] + 0.0722 * LIN[d[p + 2]];   // relative luminance (WCAG)
+  const ratio = (a, b) => (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+  const median = (a, n) => (n ? a.subarray(0, n).sort()[n >> 1] : NaN);
+  // a read matches calls by its letters: whitespace, punctuation and symbols are left out on both sides, because a film
+  // often draws a "·", an arrow or a fraction bar as a shape, or puts the parts of a line in separate calls
+  const strict = (s) => String(s).normalize("NFKC").replace(/[\s\p{P}\p{S}]/gu, "");
+  const loose = (s) => String(s).normalize("NFKC").replace(/\s/g, "");
+  const keyOf = (s) => strict(s) || loose(s);
+  const EMPTY = new Set();
+
+  async function draw(t, skip) {
+    H.n = 0; H.skip = skip || null; H.rec = !skip; H.t = t;
+    if (!skip) H.calls = [];
+    try { await window.__vh.draw(t); } catch (e) { H.errors.push({ t, msg: String((e && e.stack) || e) }); }
+    H.rec = false; H.skip = null; H.t = null;
+    return H.n;
+  }
+
+  // contiguous calls of one kind on one canvas whose letters spell the read; else one call that contains it
+  function runsFor(calls, text) {
+    const T0 = strict(text), f = T0 ? strict : loose, T = T0 || loose(text), out = [];
+    if (!T) return out;
+    const lists = ["fill", "stroke"].map((op) => calls.filter((c) => c.op === op).map((c) => [c, f(c.s)]).filter((x) => x[1]));
+    for (const L of lists) {
+      for (let a = 0; a < L.length; a++) {
+        let acc = "";
+        for (let b = a; b < L.length && L[b][0].cv === L[a][0].cv; b++) {
+          acc += L[b][1];
+          if (acc === T) { out.push(L.slice(a, b + 1).map((x) => x[0])); break; }
+          if (acc.length >= T.length || !T.startsWith(acc)) break;
+        }
+      }
+    }
+    if (!out.length && T.length >= 2) for (const L of lists) for (const [c, k] of L) if (k.includes(T)) out.push([c]);
+    return out;
+  }
+
+  // the glyph box of a call in canvas pixels (its transform applied), from the font's own metrics
+  const scratch = document.createElement("canvas").getContext("2d");
+  function boxOf(c) {
+    for (const k in c.st) try { scratch[k] = c.st[k]; } catch (e) { /* a state the browser rejects */ }
+    const m = scratch.measureText(c.s);
+    let l = -m.actualBoundingBoxLeft, r = m.actualBoundingBoxRight;
+    if (c.mw !== undefined && m.width > c.mw && m.width > 0) { l *= c.mw / m.width; r *= c.mw / m.width; }   // maxWidth squeezes the line
+    const pad = c.op === "stroke" ? (c.st.lineWidth || 1) / 2 : 0;
+    const pts = [[l - pad, -m.actualBoundingBoxAscent - pad], [r + pad, -m.actualBoundingBoxAscent - pad], [l - pad, m.actualBoundingBoxDescent + pad], [r + pad, m.actualBoundingBoxDescent + pad]]
+      .map(([dx, dy]) => c.m.transformPoint(new DOMPoint(c.x + dx, c.y + dy)));
+    const xs = pts.map((p) => p.x), ys = pts.map((p) => p.y);
+    return [Math.min(...xs), Math.min(...ys), Math.max(...xs), Math.max(...ys)];
+  }
+  const overlap = (a, b) => !(a[0] > b[2] || a[2] < b[0] || a[1] > b[3] || a[3] < b[1]);
+  const union = (a, b) => [Math.min(a[0], b[0]), Math.min(a[1], b[1]), Math.max(a[2], b[2]), Math.max(a[3], b[3])];
+
+  // runs drawn over each other (a glow pass and a crisp pass, the outline and the fill) are one copy of the read
+  function groupsOf(runs) {
+    const groups = [];
+    for (const r of runs) {
+      const box = r.map(boxOf).reduce(union);
+      const g = groups.find((g) => g.cv === r[0].cv && overlap(g.box, box));
+      if (g) { g.calls.push(...r); g.box = union(g.box, box); } else groups.push({ cv: r[0].cv, calls: [...r], box });
+    }
+    for (const g of groups) {
+      const fills = g.calls.filter((c) => c.op === "fill");
+      g.ink = fills.length ? fills : g.calls;
+      g.alpha = Math.min(...g.ink.map((c) => c.a));
+      g.skip = new Set(g.calls.map((c) => c.i));
+    }
+    return groups;
+  }
+
+  // pixels of a canvas, copied into a canvas of our own first: after a few getImageData calls Chrome moves a canvas off
+  // the GPU, and the film would then draw every later frame on the CPU, many times slower
+  let copy = null;
+  function pixels(cv, x, y, w, h) {
+    if (!copy) copy = document.createElement("canvas").getContext("2d", { willReadFrequently: true });
+    copy.canvas.width = w; copy.canvas.height = h;
+    copy.drawImage(cv, x, y, w, h, 0, 0, w, h);
+    return copy.getImageData(0, 0, w, h).data;
+  }
+  const rgba = (c) => {   // a CSS colour string as [r, g, b] (its alpha is in the call's own alpha), else null
+    if (typeof c !== "string") return null;
+    let m = c.match(/^#([0-9a-f]{6})$/i);
+    if (m) return [0, 2, 4].map((i) => parseInt(m[1].slice(i, i + 2), 16));
+    m = c.match(/^rgba?\(([^)]*)\)$/);
+    return m ? m[1].split(/[\s,/]+/).filter(Boolean).slice(0, 3).map(Number) : null;
+  };
+
+  let off = null;
+  function maskOf(ink, x, y, w, h) {   // the read alone, opaque white, in a w x h window at (x, y) of its canvas
+    if (!off) off = document.createElement("canvas");
+    off.width = w; off.height = h;
+    const g = off.getContext("2d", { willReadFrequently: true });
+    for (const c of ink) {
+      g.setTransform(new DOMMatrix().translate(-x, -y).multiply(c.m));
+      for (const k in c.st) try { g[k] = c.st[k]; } catch (e) { /* as above */ }
+      g.globalAlpha = 1; g.globalCompositeOperation = "source-over"; g.shadowBlur = 0; g.shadowColor = "transparent"; g.filter = "none";
+      g.fillStyle = g.strokeStyle = "#fff";
+      const args = c.mw === undefined ? [c.s, c.x, c.y] : [c.s, c.x, c.y, c.mw];
+      if (c.op === "fill") g.fillText(...args); else g.strokeText(...args);
+    }
+    return g.getImageData(0, 0, w, h).data;
+  }
+  function dilate(src, w, h, r) {
+    const tmp = new Uint8Array(w * h), out = new Uint8Array(w * h);
+    for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) {
+      let v = 0; for (let d = Math.max(0, x - r), e = Math.min(w - 1, x + r); d <= e && !v; d++) v = src[y * w + d];
+      tmp[y * w + x] = v;
+    }
+    for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) {
+      let v = 0; for (let d = Math.max(0, y - r), e = Math.min(h - 1, y + r); d <= e && !v; d++) v = tmp[d * w + x];
+      out[y * w + x] = v;
+    }
+    return out;
+  }
+  // share: the glyph pixels that show the read: they differ from the picture without it, or they are the read's own
+  // colour (white text on a white panel is not covered; its contrast says the rest). The others are covered.
+  // under: the glyphs' contrast with the picture under them; edge: with what is right around them (an outline, a
+  // shadow, a plate). col: the read's colour and alpha, when one solid colour
+  function measure(A, B, M, w, h, col) {
+    const N = w * h, core = new Uint8Array(N), ink = new Uint8Array(N);
+    for (let k = 0; k < N; k++) { const a = M[k * 4 + 3]; core[k] = a > 160; ink[k] = a > 8; }
+    const d4 = dilate(core, w, h, 4), d1 = dilate(core, w, h, 1);
+    const pc = new Float32Array(N), ga = new Float32Array(N), rg = new Float32Array(N);
+    let n = 0, vis = 0, nr = 0;
+    for (let k = 0; k < N; k++) {
+      const p = k * 4;
+      if (core[k]) {
+        if (Math.abs(A[p] - B[p]) + Math.abs(A[p + 1] - B[p + 1]) + Math.abs(A[p + 2] - B[p + 2]) > 36) vis++;
+        else if (col) { let d = 0; for (let c = 0; c < 3; c++) d += Math.abs(A[p + c] - (col[3] * col[c] + (1 - col[3]) * B[p + c])); if (d <= 36) vis++; }
+        const la = lum(A, p); pc[n] = ratio(la, lum(B, p)); ga[n] = la; n++;
+      } else if (d4[k] && !d1[k] && !ink[k]) rg[nr++] = lum(A, p);
+    }
+    if (n < 20) return null;
+    const under = median(pc, n), edge = nr >= 10 ? ratio(median(ga, n), median(rg, nr)) : under;
+    return { px: n, share: vis / n, under, edge, contrast: Math.max(under, edge) };
+  }
+
+  // DOM captions: elements marked data-read="subtitle" (readcheck's mark) that show now, with their line boxes
+  function shown(el) {
+    if (!el.textContent.trim() || !el.getClientRects().length) return false;
+    let o = 1;
+    for (let e = el; e && e.nodeType === 1; e = e.parentElement) { const cs = getComputedStyle(e); if (cs.display === "none") return false; o *= +cs.opacity; }
+    return getComputedStyle(el).visibility === "visible" && o >= 0.5;
+  }
+  function captions() {
+    const out = [];
+    for (const el of document.querySelectorAll('[data-read="subtitle"]')) {
+      if ((el.parentElement && el.parentElement.closest('[data-read="subtitle"]')) || !shown(el)) continue;
+      const r = document.createRange(); r.selectNodeContents(el);
+      const rects = [...r.getClientRects()].filter((q) => q.width > 1 && q.height > 1).map((q) => [q.left, q.top, q.right, q.bottom]);
+      if (rects.length) out.push({ el, text: el.textContent.replace(/\s+/g, " ").trim(), rects });
+    }
+    return out;
+  }
+  const toPage = (cv, b) => { const r = cv.getBoundingClientRect(), sx = r.width / cv.width, sy = r.height / cv.height; return [r.left + b[0] * sx, r.top + b[1] * sy, r.left + b[2] * sx, r.top + b[3] * sy]; };
+  const toCanvas = (cv, b) => { const r = cv.getBoundingClientRect(), sx = cv.width / r.width, sy = cv.height / r.height; return [(b[0] - r.left) * sx, (b[1] - r.top) * sy, (b[2] - r.left) * sx, (b[3] - r.top) * sy]; };
+  const colour = (s) => { const v = (String(s).match(/[\d.]+/g) || []).map(Number); return v.length >= 3 ? v.slice(0, 3).map((x) => (x <= 1 && /^color\(/.test(s) ? x * 255 : x)) : [255, 255, 255]; };
+
+  // one read at time t: every copy measured, the most legible one returned
+  async function sample(text, t, o, near) {
+    const nA = await draw(t);
+    let groups = groupsOf(runsFor(H.calls, text));
+    if (near) groups = groups.filter((g) => overlap(g.box, near));
+    groups = groups.slice(0, 12);
+    if (!groups.length) return { t, found: false };
+    const caps = captions();
+    for (const g of groups) {
+      const W = g.cv.width, Hh = g.cv.height, b = g.box;
+      g.flags = [];
+      if (b[2] < 0 || b[0] > W || b[3] < 0 || b[1] > Hh) { g.flags.push("outside"); continue; }
+      if (b[0] < -1 || b[1] < -1 || b[2] > W + 1 || b[3] > Hh + 1) g.flags.push("cut");
+      const x = Math.max(0, Math.floor(b[0]) - 8), y = Math.max(0, Math.floor(b[1]) - 8);
+      g.win = [x, y, Math.min(W, Math.ceil(b[2]) + 8) - x, Math.min(Hh, Math.ceil(b[3]) + 8) - y];
+      g.A = pixels(g.cv, ...g.win);
+      g.page = toPage(g.cv, b);
+      if (caps.some((c) => c.rects.some((r) => overlap(r, g.page)))) g.flags.push("caption");
+    }
+    for (const g of groups) if (g.win) { g.same = (await draw(t, g.skip)) === nA; g.B = pixels(g.cv, ...g.win); }
+    if (groups.some((g) => g.win)) {   // the frame drawn again must be the same frame (hard rule 1), or the numbers mean nothing
+      await draw(t, EMPTY);
+      for (const g of groups) if (g.win) {
+        const A2 = pixels(g.cv, ...g.win);
+        let diff = 0; for (let p = 0; p < A2.length; p += 4) if (Math.abs(A2[p] - g.A[p]) + Math.abs(A2[p + 1] - g.A[p + 1]) + Math.abs(A2[p + 2] - g.A[p + 2]) > 24) diff++;
+        if (!g.same || diff > (A2.length / 4) * 0.002) g.flags.push("unstable");
+      }
+    }
+    const res = groups.map((g) => {
+      const r = { t, found: true, copies: groups.length, alpha: g.alpha, flags: g.flags, box: g.page || toPage(g.cv, g.box) };
+      if (!g.win) return r;
+      const [x, y, w, h] = g.win, c0 = g.ink[0].col, rgb = g.ink.every((c) => c.col === c0) && rgba(c0);
+      const m = measure(g.A, g.B, maskOf(g.ink, x, y, w, h), w, h, rgb ? [...rgb, g.alpha] : null);
+      if (!m) { if (!g.flags.includes("cut")) g.flags.push("tiny"); return r; }
+      if (m.share < o.minVisible) g.flags.push("covered");
+      else if (m.contrast < o.minContrast) g.flags.push("contrast");   // a covered read's few visible pixels say nothing about contrast
+      return Object.assign(r, m);
+    });
+    const bad = (r) => r.flags.filter((f) => f !== "unstable" && f !== "tiny").length;
+    res.sort((a, b) => bad(a) - bad(b) || (b.contrast || 0) * (b.share || 0) - (a.contrast || 0) * (a.share || 0));
+    return res[0];
+  }
+
+  // canvas text drawn as lines: consecutive fills on one canvas in one font and scale, on one baseline, side by side
+  function linesOf(calls) {
+    const lines = [];
+    let cur = null;
+    for (const c of calls) {
+      if (c.op !== "fill" || !c.s.trim()) continue;
+      const b = boxOf(c), m = c.m, em = (parseFloat((c.st.font.match(/([\d.]+)px/) || [0, 16])[1]) || 16) * Math.hypot(m.a, m.b), base = m.transformPoint(new DOMPoint(c.x, c.y)).y;
+      const join = cur && cur.cv === c.cv && cur.font === c.st.font && Math.abs(cur.m.a - m.a) + Math.abs(cur.m.b - m.b) + Math.abs(cur.m.c - m.c) + Math.abs(cur.m.d - m.d) < 1e-3
+        && Math.abs(cur.base - base) < 0.2 * em && b[0] - cur.box[2] < 0.8 * em && b[0] - cur.box[2] > -0.5 * em;
+      if (join) { cur.text += c.s; cur.box = union(cur.box, b); cur.a = Math.min(cur.a, c.a); }
+      else lines.push(cur = { cv: c.cv, font: c.st.font, m, base, text: c.s, box: b, a: c.a });
+    }
+    return lines;
+  }
+
+  window.__vhTC = {
+    keyOf,
+    // what the page offers: the frame function, an in-page registry, the length
+    info() {
+      const v = window.__vh, root = document.querySelector("[data-composition-id]");
+      let texts = null;
+      if (v && v.texts) try { texts = JSON.parse(JSON.stringify(typeof v.texts === "function" ? v.texts() : v.texts)); } catch (e) { texts = { error: String(e) }; }
+      return { draw: !!(v && typeof v.draw === "function"), texts, duration: +((v && v.duration) || (root && root.dataset.duration) || 0),
+        canvases: document.querySelectorAll("canvas").length, subtitles: document.querySelectorAll('[data-read="subtitle"]').length };
+    },
+    async read(text, times, o, near) {
+      const out = [];
+      for (const t of times) out.push(await sample(text, t, o, near));
+      return out;
+    },
+    // a read not found as canvas text: is it DOM text showing at t?
+    async dom(text, t) {
+      await draw(t, EMPTY);
+      const T = keyOf(text), w = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+      for (let n; (n = w.nextNode());) {
+        const el = n.parentElement;
+        if (!el || /^(SCRIPT|STYLE|TEMPLATE)$/.test(el.tagName) || !keyOf(el.innerText || "").includes(T) || !shown(el)) continue;
+        const mark = el.closest("[data-read]");
+        return { dom: true, subtitle: !!(mark && mark.dataset.read === "subtitle") };
+      }
+      return { dom: false };
+    },
+    // every line of canvas text drawn at these times (for the texts outside the registry)
+    async lines(times) {
+      const seen = new Map();
+      for (const t of times) {
+        await draw(t);
+        for (const l of linesOf(H.calls)) {
+          const k = keyOf(l.text);
+          if (!k) continue;
+          if (!seen.has(k)) seen.set(k, { text: l.text.trim(), hits: [] });
+          seen.get(k).hits.push([t, l.a, l.box.map(Math.round)]);
+        }
+      }
+      return [...seen.values()];
+    },
+    // the picture under each DOM caption's lines: the share of its pixels within 3:1 of the caption's colour
+    async captions(times) {
+      const out = [];
+      for (const t of times) {
+        await draw(t, EMPTY);
+        for (const c of captions()) {
+          const col = colour(getComputedStyle(c.el).color), Lc = 0.2126 * LIN[Math.round(col[0])] + 0.7152 * LIN[Math.round(col[1])] + 0.0722 * LIN[Math.round(col[2])];
+          let n = 0, close = 0, box = null;
+          for (const r of c.rects) {
+            const cv = document.elementsFromPoint((r[0] + r[2]) / 2, (r[1] + r[3]) / 2).find((e) => e.tagName === "CANVAS");
+            if (!cv) continue;
+            const q = toCanvas(cv, r), x = Math.max(0, Math.floor(q[0])), y = Math.max(0, Math.floor(q[1])), w = Math.min(cv.width, Math.ceil(q[2])) - x, h = Math.min(cv.height, Math.ceil(q[3])) - y;
+            if (w <= 0 || h <= 0) continue;
+            const d = pixels(cv, x, y, w, h);
+            for (let p = 0; p < d.length; p += 8) { n++; if (ratio(lum(d, p), Lc) < 3) close++; }
+            box = box ? union(box, r) : r;
+          }
+          if (n) out.push({ t, text: c.text, close: close / n, box });
+        }
+      }
+      return out;
+    },
+    errors() { const e = H.errors; H.errors = []; return e; },
+    async show(t) { await draw(t, EMPTY); },
+  };
+})();
diff --git a/tools/textcheck/textcheck.mjs b/tools/textcheck/textcheck.mjs
new file mode 100644
index 0000000..b9080e0
--- /dev/null
+++ b/tools/textcheck/textcheck.mjs
@@ -0,0 +1,270 @@
+// textcheck: is the text drawn into a canvas covered by the picture, or too close to it in brightness to read?
+// `npx hyperframes check` measures DOM text only; text a script draws into a <canvas> is pixels to it.
+//
+// usage: node tools/textcheck/textcheck.mjs <project | composition.html> --browser <chrome> [--texts f.json]
+//          [--min-visible 0.7] [--min-contrast 3] [--samples 3] [--scan-step 1] [--caption-step 0.5] [--caption-close 0.12]
+//          [--out dir] [--soft-gl] [--timeout s]
+//        (bin/vh textcheck finds the browser: CHROME_PATH, HyperFrames' chrome-headless-shell, then Chrome or Chromium)
+//
+// The composition opts in with one line (engines/README.md, "画面文字检查"):
+//     window.__vh = { draw: (t) => drawFrame(t), texts: TEXTS };
+// draw(t) draws the frame at t seconds (and the DOM it controls, such as a caption), the same picture the render shows at
+// t; it may return a promise. texts (optional) is the registry of reads, the format of readcheck's texts.json:
+// [{text, start, end, read?}]. Without it the registry is --texts, else <project>/out/texts.json, else none.
+// The page is served from its folder on 127.0.0.1, at the composition's data-width x data-height, device scale 1; the
+// check waits for window.__hf.buildReady (HyperFrames' own convention), window.__vh.ready and the fonts.
+//
+// Nothing else in the film changes: before its scripts run, the check hooks the canvas's fillText and strokeText, so it
+// knows every text drawn, with its transform and font, and can draw a frame again without one of them. For each read:
+//   A  the frame at t; B  the same frame with only this read left out; M  the read alone (opaque white) as a mask.
+//   visible   the share of the read's own pixels where A differs from B: under --min-visible (0.7) something is drawn
+//             over it, or it is the colour of the picture under it
+//   contrast  the larger of: its contrast with the picture under it (the median over its pixels of A against B), and
+//             with what is right around it in A (2–4 px out: an outline, a shadow or a plate counts); under
+//             --min-contrast (3:1, WCAG's figure for large text) it is hard to read
+//   frame     drawn outside the canvas, or cut by its edge
+//   caption   its box meets the lines of a DOM caption showing at that moment
+// A read is matched to the calls that spell it, whitespace, punctuation and symbols left out (a film draws a "·" or an
+// arrow as a shape, and kinetic type one character at a time); a read drawn in several copies (a glow pass and a crisp
+// one, an outline and a fill) counts as one, and of copies in different places the most legible one counts.
+// Each read is sampled --samples (3) times across its window, from 0.4 s after its start to 0.3 s before its end;
+// samples where it is still fading (alpha under 0.95) are not judged when an opaque one exists.
+//
+// Also, never failing the run: canvas text outside the registry (every --scan-step seconds, each distinct line judged
+// once, at the middle of its longest opaque stretch; a line never seen at half opacity or more is left out); registered reads not drawn as canvas text at some or all of their
+// samples (an image, DOM text, or a window that is off); and DOM captions (data-read="subtitle", readcheck's mark) over
+// a bright picture: every --caption-step seconds, the share of the canvas pixels under the caption's own lines that are
+// within 3:1 of its colour, over --caption-close (0.12). CSS text-shadow and strokes usually carry such a caption: look.
+//
+// Writes <out>/textcheck.json (every number) and a crop per finding (<out>/<t>s-<kind>.png); out defaults to
+// <project>/out/check/textcheck. Exit: 0 no read failed (warnings allowed) · 1 a registered read is covered, under the
+// contrast, outside or cut by the frame, or under a caption, or the frame function threw · 2 could not check (no
+// window.__vh.draw, the page did not load, no browser): not a pass.
+import fs from "node:fs";
+import path from "node:path";
+import { launch, serve } from "./browser.mjs";
+
+process.stdout.on("error", (e) => { if (e.code !== "EPIPE") throw e; });   // a reader that stops early (| head) does not leave Chrome behind
+const HELP = fs.readFileSync(new URL(import.meta.url), "utf8").split("\nimport ")[0].replace(/^\/\/ ?/gm, "");
+const argv = process.argv.slice(2);
+if (!argv.length || argv.includes("-h") || argv.includes("--help")) { process.stdout.write(HELP); process.exit(argv.length ? 0 : 2); }
+const opt = { minVisible: 0.7, minContrast: 3, samples: 3, scanStep: 1, captionStep: 0.5, captionClose: 0.12, timeout: 900 };
+const NUM = { "--min-visible": "minVisible", "--min-contrast": "minContrast", "--samples": "samples", "--scan-step": "scanStep", "--caption-step": "captionStep", "--caption-close": "captionClose", "--timeout": "timeout" };
+let target = null, browserPath = null, textsFile = null, outDir = null, softGl = false;
+const die = (msg) => { console.error("textcheck: " + msg); process.exit(2); };   // before the browser starts
+class Stop extends Error {}
+const stop = (msg) => { throw new Stop(msg); };                                  // after: the finally below closes it
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i], [k, inline] = a.startsWith("--") && a.includes("=") ? [a.slice(0, a.indexOf("=")), a.slice(a.indexOf("=") + 1)] : [a, undefined];
+  const val = () => { const v = inline !== undefined ? inline : argv[++i]; if (v === undefined) die(`${k} needs a value`); return v; };
+  if (NUM[k]) { const v = Number(val()); if (!Number.isFinite(v) || v < 0) die(`${k}: not a number ≥ 0`); opt[NUM[k]] = v; }
+  else if (k === "--browser") browserPath = val();
+  else if (k === "--texts") textsFile = val();
+  else if (k === "--out") outDir = val();
+  else if (k === "--soft-gl") softGl = true;
+  else if (k.startsWith("-")) die(`unknown option ${k} (-h for the options)`);
+  else if (target) die(`one project or composition, got ${target} and ${a}`);
+  else target = a;
+}
+if (!target) die("which project or composition? (-h for the usage)");
+if (!browserPath) die("no browser: pass --browser <chrome>, or run it as bin/vh textcheck");
+if (opt.samples < 1) opt.samples = 1;
+
+let html = path.resolve(target);
+if (fs.existsSync(html) && fs.statSync(html).isDirectory()) html = path.join(html, "index.html");
+if (!fs.existsSync(html)) die(`no composition at ${html}`);
+const dir = path.dirname(html), project = dir;
+outDir = path.resolve(outDir || path.join(project, "out", "check", "textcheck"));
+const src = fs.readFileSync(html, "utf8"), rootTag = (src.match(/<[^>]*\bdata-composition-id\b[^>]*>/) || [""])[0];
+const attr = (n) => { const m = rootTag.match(new RegExp(`\\b${n}="([\\d.]+)"`)); return m ? +m[1] : 0; };
+const W = attr("data-width") || 1920, H = attr("data-height") || 1080;
+
+// the registry of reads: --texts, else the page's window.__vh.texts, else out/texts.json (the same file readcheck reads)
+function items(j) {
+  const list = Array.isArray(j) ? j : j && (j.texts || j.items || j.captions || j.cues);
+  if (!Array.isArray(list)) return null;
+  return list.map((x) => ({ text: Array.isArray(x.text) ? x.text.join("\n") : x.text, start: +(x.start ?? x.t0), end: +(x.end ?? x.t1), read: x.read || "onscreen" }))
+    .filter((x) => typeof x.text === "string" && x.text.trim() && Number.isFinite(x.start) && Number.isFinite(x.end));
+}
+const fmt = (t) => t.toFixed(2).padStart(7) + " s";
+const pct = (x) => Math.round(100 * x) + "%";
+const short = (s) => { const one = s.replace(/\s+/g, " ").trim(); return [...one].length > 40 ? [...one].slice(0, 39).join("") + "…" : one; };
+const sampleTimes = (a, b, n) => {
+  const d = b - a; if (!(d > 0)) return [];
+  const lo = a + Math.min(0.4, d / 4), hi = b - Math.min(0.3, d / 4);
+  if (n <= 1 || hi - lo < 0.2) return [+((lo + hi) / 2).toFixed(3)];
+  return Array.from({ length: n }, (_, i) => +(lo + ((hi - lo) * i) / (n - 1)).toFixed(3));
+};
+const steps = (step, dur) => { const out = []; if (step > 0) for (let t = step / 2; t < dur; t += step) out.push(+t.toFixed(3)); return out; };
+const FAIL = ["outside", "cut", "caption", "covered", "contrast"];
+const SAY = { outside: () => "outside the frame", cut: () => "cut by the frame edge", caption: () => "under a caption", covered: (r) => `${pct(r.share)} visible`,
+  contrast: (r) => `contrast ${r.under.toFixed(1)}:1 with the picture, ${r.edge.toFixed(1)}:1 with its edge` };
+const words = (r) => r.flags.filter((f) => FAIL.includes(f)).map((f) => SAY[f](r)).join(", ");
+
+const flags = softGl ? ["--use-angle=swiftshader", "--enable-unsafe-swiftshader", "--ignore-gpu-blocklist"]
+  : process.platform === "darwin" ? ["--use-angle=metal", "--ignore-gpu-blocklist"] : ["--ignore-gpu-blocklist"];
+if (process.platform === "linux") flags.push("--no-sandbox", "--disable-dev-shm-usage");
+
+let browser = null, server = null;
+const watchdog = setTimeout(async () => { console.error(`textcheck: stopped after ${opt.timeout} s (--timeout); a frame function that never returns?`); try { await browser?.close(); } catch { /* gone */ } process.exit(2); }, opt.timeout * 1000);
+watchdog.unref();
+try {
+  server = await serve(dir);
+  try { browser = await launch(browserPath, flags); } catch (e) { stop(`could not start ${browserPath}: ${e.message}`); }
+  const { targetId } = await browser.send("Target.createTarget", { url: "about:blank" });
+  const { sessionId: s } = await browser.send("Target.attachToTarget", { targetId, flatten: true });
+  const loadErrors = [];
+  browser.on("Runtime.exceptionThrown", (p) => loadErrors.push((p.exceptionDetails.exception && p.exceptionDetails.exception.description) || p.exceptionDetails.text));
+  await browser.send("Page.enable", {}, s);
+  await browser.send("Runtime.enable", {}, s);
+  await browser.send("Emulation.setDeviceMetricsOverride", { width: W, height: H, deviceScaleFactor: 1, mobile: false }, s);
+  await browser.send("Page.addScriptToEvaluateOnNewDocument", { source: fs.readFileSync(new URL("./page.js", import.meta.url), "utf8") }, s);
+  const ev = async (expression) => {
+    const r = await browser.send("Runtime.evaluate", { expression, awaitPromise: true, returnByValue: true }, s);
+    if (r.exceptionDetails) throw new Error((r.exceptionDetails.exception && r.exceptionDetails.exception.description) || r.exceptionDetails.text);
+    return r.result.value;
+  };
+  const call = (fn, ...args) => ev(`window.__vhTC.${fn}(${args.map((a) => JSON.stringify(a)).join(", ")})`);
+  const loaded = browser.once("Page.loadEventFired", s);
+  await browser.send("Page.navigate", { url: server.url + encodeURIComponent(path.basename(html)) }, s);
+  let loadTimer;
+  await Promise.race([loaded, new Promise((_, rej) => { loadTimer = setTimeout(() => rej(new Error("the page did not load within 60 s")), 60000); })]).catch((e) => stop(e.message)).finally(() => clearTimeout(loadTimer));
+  const ready = await ev(`(async () => {
+    const wait = (p) => Promise.race([p, new Promise((_, rej) => setTimeout(() => rej(new Error("not ready after 120 s")), 120000))]);
+    try { await wait(Promise.all(Object.values((window.__hf && window.__hf.buildReady) || {}))); if (window.__vh && window.__vh.ready) await wait(window.__vh.ready); await wait(document.fonts.ready); }
+    catch (e) { return String(e && e.message || e); }
+    return "";
+  })()`);
+  if (ready) stop(`${ready} (window.__hf.buildReady, window.__vh.ready or the fonts)`);
+  const T0 = Date.now(), phase = (name) => { if (process.env.TEXTCHECK_TIMING) console.error(`  [${((Date.now() - T0) / 1000).toFixed(1)} s] ${name}`); };
+  const info = await call("info");
+  if (!info.draw) {
+    stop(`${path.relative(process.cwd(), html) || html} has no window.__vh.draw(t), so nothing can be drawn on demand. Add one line to the composition's inline script:\n` +
+      `    window.__vh = { draw: (t) => drawFrame(t) };   // your function that draws frame t; texts: [...] optional\n` +
+      `(engines/README.md, "画面文字检查")` + (loadErrors.length ? `\npage errors while loading:\n  ${[...new Set(loadErrors)].slice(0, 5).join("\n  ")}` : ""));
+  }
+  let reg = null, regFrom = "";
+  if (textsFile) { try { reg = items(JSON.parse(fs.readFileSync(textsFile, "utf8"))); } catch (e) { stop(`--texts ${textsFile}: ${e.message}`); } if (!reg) stop(`--texts ${textsFile}: not a list of {text, start, end}`); regFrom = path.relative(process.cwd(), textsFile) || textsFile; }
+  else if (info.texts) { reg = items(info.texts); if (!reg) stop("window.__vh.texts is not a list of {text, start, end}"); regFrom = "window.__vh.texts"; }
+  else if (fs.existsSync(path.join(project, "out", "texts.json"))) { reg = items(JSON.parse(fs.readFileSync(path.join(project, "out", "texts.json"), "utf8"))) || []; regFrom = "out/texts.json"; }
+  reg = reg || [];
+  const dur = info.duration || Math.max(0, ...reg.map((x) => x.end));
+  if (!(dur > 0)) stop("no length: give the composition root a data-duration, or window.__vh a duration");
+  console.log(`textcheck: ${path.basename(html)} · ${W}x${H} · ${dur} s · ${browser.version}`);
+  console.log(`  reads: ${reg.length ? `${reg.length} from ${regFrom}, ${opt.samples} sample(s) each` : "no registry (window.__vh.texts, --texts or out/texts.json): only the scan below"}` +
+    ` · canvas text outside it: ${opt.scanStep > 0 ? `every ${opt.scanStep} s` : "off"} · captions: ${opt.captionStep > 0 ? `every ${opt.captionStep} s` : "off"}`);
+
+  // 1 the registered reads
+  const reads = [];
+  for (const x of reg) {
+    const times = sampleTimes(x.start, x.end, opt.samples);
+    if (!times.length) { reads.push({ ...x, status: "bad window" }); continue; }
+    const smp = await call("read", x.text, times, opt), found = smp.filter((r) => r.found);
+    const r = { ...x, samples: smp };
+    if (!found.length) {
+      const d = await call("dom", x.text, times[Math.floor(times.length / 2)]);
+      r.status = d.dom ? (d.subtitle ? "dom caption" : "dom") : "not drawn";
+    } else {
+      const opaque = found.filter((q) => q.alpha >= 0.95), judged = opaque.length ? opaque : found;
+      const fails = judged.filter((q) => q.flags.some((f) => FAIL.includes(f)));
+      const score = (q) => (q.contrast || 0) * (q.share || 0);
+      r.worst = fails.length ? fails.sort((a, b) => b.flags.length - a.flags.length || score(a) - score(b))[0] : judged.slice().sort((a, b) => score(a) - score(b))[0];
+      r.status = fails.length ? "fail" : "ok";
+      r.missingAt = smp.filter((q) => !q.found).map((q) => q.t);
+      r.faded = !opaque.length;
+      r.unstable = found.some((q) => q.flags.includes("unstable"));
+    }
+    reads.push(r);
+  }
+  phase("reads");
+  // 2 canvas text outside the registry
+  const regKeys = (await ev(`${JSON.stringify(reg.map((x) => x.text))}.map(window.__vhTC.keyOf)`)).filter(Boolean);
+  let fading = 0;
+  const extra = [], ts = steps(opt.scanStep, dur), lines = opt.scanStep > 0 ? await call("lines", ts) : [];
+  const lineKeys = await ev(`${JSON.stringify(lines.map((l) => l.text))}.map(window.__vhTC.keyOf)`);
+  for (const [i, l] of lines.entries()) {
+    const k = lineKeys[i];
+    if (regKeys.some((r) => r.includes(k) || k.includes(r))) continue;
+    // judge it once: the middle of its longest run of opaque samples, else its most opaque one
+    const hits = l.hits;
+    if (Math.max(...hits.map((h) => h[1])) < 0.5) { fading++; continue; }   // only ever seen fading in or out
+    let best = [], run = [];
+    for (const h of hits) { if (h[1] >= 0.95 && run.length && ts.indexOf(h[0]) === ts.indexOf(run[run.length - 1][0]) + 1) run.push(h); else run = h[1] >= 0.95 ? [h] : []; if (run.length > best.length) best = run.slice(); }
+    const h = best.length ? best[Math.floor(best.length / 2)] : hits.slice().sort((a, b) => b[1] - a[1])[0];
+    const [q] = await call("read", l.text, [h[0]], opt, h[2]);
+    extra.push({ text: l.text, seen: [hits[0][0], hits[hits.length - 1][0]], sample: q, flagged: !!(q.found && q.flags.some((f) => FAIL.includes(f))) });
+  }
+  phase("canvas text outside the registry");
+  // 3 DOM captions over a bright picture: each caption's worst sample
+  const capByText = new Map();
+  for (const c of opt.captionStep > 0 && info.subtitles ? await call("captions", steps(opt.captionStep, dur)) : []) {
+    const k = capByText.get(c.text);
+    if (!k) capByText.set(c.text, { text: c.text, samples: 1, worst: c }); else { k.samples++; if (c.close > k.worst.close) k.worst = c; }
+  }
+  const caps = [...capByText.values()], capBad = caps.filter((c) => c.worst.close > opt.captionClose);
+  phase("captions");
+  const errors = await call("errors");
+
+  // report
+  const failed = reads.filter((r) => r.status === "fail"), ok = reads.filter((r) => r.status === "ok");
+  const notDrawn = reads.filter((r) => r.status === "not drawn"), part = reads.filter((r) => r.status === "ok" || r.status === "fail").filter((r) => r.missingAt.length);
+  const dom = reads.filter((r) => r.status.startsWith("dom")), badWin = reads.filter((r) => r.status === "bad window");
+  const unstable = reads.filter((r) => r.unstable), extraBad = extra.filter((e) => e.flagged);
+  fs.mkdirSync(outDir, { recursive: true });
+  for (const f of fs.readdirSync(outDir)) if (/^[\d.]+s-[a-z-]+(-\d+)?\.png$/.test(f)) fs.rmSync(path.join(outDir, f));
+  const crops = new Map();
+  const crop = async (t, box, kind) => {
+    if (!box || crops.size >= 60) return "";
+    const m = 40, x = Math.max(0, Math.floor(box[0]) - m), y = Math.max(0, Math.floor(box[1]) - m);
+    const w = Math.min(W, Math.ceil(box[2]) + m) - x, h = Math.min(H, Math.ceil(box[3]) + m) - y;
+    if (w <= 0 || h <= 0) return "";
+    await call("show", t);
+    let name = `${t.toFixed(2)}s-${kind}.png`;
+    for (let i = 2; crops.has(name); i++) name = `${t.toFixed(2)}s-${kind}-${i}.png`;
+    const shot = await browser.send("Page.captureScreenshot", { format: "png", clip: { x, y, width: w, height: h, scale: 1 } }, s);
+    fs.writeFileSync(path.join(outDir, name), Buffer.from(shot.data, "base64")); crops.set(name, true);
+    return name;
+  };
+  const G = "\x1b[32m✓\x1b[0m", R = "\x1b[31m✗\x1b[0m", Y = "\x1b[33m!\x1b[0m";
+  if (reg.length) {
+    if (ok.length) console.log(`${G} ${ok.length} read(s) in the frame, at least ${pct(opt.minVisible)} visible and ${opt.minContrast}:1`);
+    if (failed.length) console.log(`${R} ${failed.length} read(s) covered, under ${opt.minContrast}:1, outside or cut by the frame, or under a caption:`);
+    for (const r of failed) { const w = r.worst; w.crop = await crop(w.t, w.box, w.flags.find((f) => FAIL.includes(f))); console.log(`   ${fmt(w.t)}  ${words(w)}  ${short(r.text)}`); }
+    if (notDrawn.length) console.log(`${Y} ${notDrawn.length} read(s) not drawn as canvas text at any sample (an image? a window that is off?): ${notDrawn.map((r) => short(r.text)).join(" · ")}`);
+    if (part.length) console.log(`${Y} ${part.length} read(s) missing from some samples inside their window (on screen for less than registered?):`);
+    for (const r of part.slice(0, 12)) console.log(`   not at ${r.missingAt.map((t) => t.toFixed(2)).join(", ")} s (window ${r.start}–${r.end} s)  ${short(r.text)}`);
+    if (part.length > 12) console.log(`   … ${part.length - 12} more in textcheck.json`);
+    if (dom.length) console.log(`  ${dom.length} read(s) are DOM text, not canvas: npx hyperframes check measures those${dom.some((r) => r.status === "dom caption") ? "; captions are in the caption scan below" : ""}`);
+    if (badWin.length) console.log(`${Y} ${badWin.length} read(s) with end ≤ start, not checked: ${badWin.map((r) => short(r.text)).join(" · ")}`);
+    if (reads.some((r) => r.faded)) console.log(`${Y} ${reads.filter((r) => r.faded).length} read(s) never fully opaque at their samples (judged anyway): ${reads.filter((r) => r.faded).map((r) => short(r.text)).join(" · ")}`);
+  }
+  if (opt.scanStep > 0) {
+    if (extraBad.length) console.log(`${Y} ${extraBad.length} of ${extra.length} canvas text line(s) outside the registry are covered, under ${opt.minContrast}:1 or out of the frame (if a viewer should read one, register it):`);
+    else console.log(`${G} ${extra.length} canvas text line(s) outside the registry: none covered, under ${opt.minContrast}:1 or out of the frame`);
+    for (const e of extraBad.sort((a, b) => (a.sample.contrast || 0) - (b.sample.contrast || 0)).slice(0, 15)) { const q = e.sample; q.crop = await crop(q.t, q.box, "extra"); console.log(`   ${fmt(q.t)}  ${words(q)}  ${short(e.text)}`); }
+    if (extraBad.length > 15) console.log(`   … ${extraBad.length - 15} more in textcheck.json`);
+    if (fading) console.log(`  ${fading} more line(s) only seen under half opacity, fading in or out: not judged`);
+  }
+  if (info.subtitles && opt.captionStep > 0) {
+    if (capBad.length) console.log(`${Y} ${capBad.length} of ${caps.length} caption(s) over a bright picture (over ${pct(opt.captionClose)} of the pixels under their lines within 3:1 of the caption's colour; a text-shadow may carry it, look):`);
+    else console.log(`${G} ${caps.length} caption(s): the picture under their lines stays apart from their colour`);
+    for (const c of capBad.sort((a, b) => b.worst.close - a.worst.close).slice(0, 15)) { c.worst.crop = await crop(c.worst.t, c.worst.box, "caption"); console.log(`   ${fmt(c.worst.t)}  ${pct(c.worst.close)} within 3:1  ${short(c.text)}`); }
+    if (capBad.length > 15) console.log(`   … ${capBad.length - 15} more in textcheck.json`);
+  }
+  if (unstable.length) console.log(`${Y} ${unstable.length} read(s) at a time where the frame drawn twice is not the same (hard rule 1); their numbers are unreliable: ${unstable.map((r) => short(r.text)).join(" · ")}`);
+  const errs = [...new Map(errors.map((e) => [e.msg.split("\n")[0], e])).values()];
+  if (errs.length) { console.log(`${R} the frame function threw or logged an error at ${errs.length} point(s):`); for (const e of errs.slice(0, 8)) console.log(`   ${fmt(e.t)}  ${e.msg.split("\n")[0]}`); }
+  if (!reg.length && !extra.length) console.log(`${Y} no canvas text found at all: is the text drawn some other way (DOM, WebGL, images)?`);
+  fs.writeFileSync(path.join(outDir, "textcheck.json"), JSON.stringify({ composition: html, size: [W, H], duration: dur, registry: regFrom || null, options: opt, reads, extra, captions: caps, errors }, null, 1));
+  const rel = (p) => { const r = path.relative(process.cwd(), p); return r && !r.startsWith("..") ? r : p; };
+  console.log(`  ${crops.size ? `crops: ${rel(outDir)}/*.png · ` : ""}every number: ${rel(path.join(outDir, "textcheck.json"))}`);
+  if (!reg.length && !extra.length) process.exitCode = 2;
+  else process.exitCode = failed.length || errs.length ? 1 : 0;
+} catch (e) {
+  console.error("textcheck: " + ((e && e.message) || e) + (e instanceof Stop ? "" : "\n" + (e && e.stack || "")));
+  process.exitCode = 2;
+} finally {
+  clearTimeout(watchdog);
+  if (browser) await browser.close();
+  if (server) await server.close();
+}

From f26564757946aca42bfbf13b03d688b56a5ba206 Mon Sep 17 00:00:00 2001
From: zhanglinghao <zhangczssx@gmail.com>
Date: Wed, 7 Oct 2026 01:09:22 +0800
Subject: [PATCH 2/4] textcheck: fixes from the review

- browser.mjs: a dead or missing browser fails every pending call at once (it hung
  until the 15-minute watchdog), pipe errors are handled (a bad --browser path
  crashed with EPIPE and exit 1), and no timer keeps node alive (every run waited
  out the 30 s start timeout).
- page.js: a maxWidth forwarded as undefined is no maxWidth (it was recorded as NaN,
  the mask came out empty and a covered read passed); the picture is every canvas,
  video and image over the page background, so text on a transparent layer is
  measured against what is behind it, captions too; a glow pass under a crisp one
  no longer makes the read look always faded.
- textcheck.mjs: a read drawn but never measurable is "unmeasured", not ok; a run
  that measured no canvas text exits 2; the browser-gone message without a stack.
- bin/vh usage lists --caption-close and --timeout; docs say what the picture is
  and when it exits 2. The 457 s film now runs in about 13 s.
---
 CHANGELOG.md                  |  4 +--
 bin/vh                        |  2 +-
 engines/README.md             |  4 +--
 tools/textcheck/browser.mjs   | 36 ++++++++++++++++----
 tools/textcheck/page.js       | 64 +++++++++++++++++++++++++----------
 tools/textcheck/textcheck.mjs | 20 +++++++----
 6 files changed, 95 insertions(+), 35 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bb79c71..912f906 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,10 +5,10 @@
 **`bin/vh textcheck`: canvas text covered by the picture, too faint, or out of the frame**
 - Why: `npx hyperframes check` measures DOM text only; text a script draws into a `<canvas>` is pixels to it. A 457 s canvas film's own script measured its 106 reads this way and found 3 with too little contrast that frame review had missed. This makes that check a command any canvas film can run.
 - A composition opts in with one line, `window.__vh = { draw: (t) => …, texts }` (`texts` optional). Before its scripts run, the check hooks the canvas's `fillText` and `strokeText`, so the film's own text functions stay as they are: kinetic type drawn one character at a time, a line drawn in parts, and a "·" or an arrow drawn as a shape still match the read.
-- For each registered read (`--texts`, else `window.__vh.texts`, else the `out/texts.json` readcheck reads), at 3 times across its window: the frame as drawn, the frame without that read and the read alone as a mask give the share of its glyphs that show (under 70%: covered), and its contrast with the picture under it and with what is right around it, so an outline, a shadow or a plate counts (both under 3:1: too faint). Outside or cut by the frame and under a DOM caption also fail; so does a frame function that throws. Exit 1 on any of those, 2 when it could not check.
+- For each registered read (`--texts`, else `window.__vh.texts`, else the `out/texts.json` readcheck reads), at 3 times across its window: the frame as drawn, the frame without that read and the read alone as a mask give the share of its glyphs that show (under 70%: covered), and its contrast with the picture under it and with what is right around it, so an outline, a shadow or a plate counts (both under 3:1: too faint). Outside or cut by the frame and under a DOM caption also fail; so does a frame function that throws. Exit 1 on any of those, 2 when 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, each line judged once where it is most opaque), reads missing from some samples or never drawn as canvas text, DOM captions (`data-read="subtitle"`) over a bright picture (the share of the pixels under their lines within 3:1 of the caption's colour), and a frame that is not the same when drawn twice. Crops and every number go to `out/check/textcheck/`.
 - No npm dependency: Node drives a headless Chrome over the DevTools protocol through a pipe, and serves the project folder on 127.0.0.1. The browser: `CHROME_PATH`, HyperFrames' chrome-headless-shell, then Chrome or Chromium. Pixels are copied into the check's own canvas before reading, because after a few `getImageData` calls Chrome moves a canvas off the GPU and the film then draws every later frame on the CPU, many times slower.
-- On a copy of the 457 s film with the line added (107 reads, about 30 s on an M3 Max): one read drawn above the frame at its sample time, one read that is an image, ten reads missing from their first sample, two dim notes outside the registry under 3:1, one line outside the frame and one cut by its edge, two captions over a bright picture.
+- On a copy of the 457 s film with the line added (107 reads, about 13 s on an M3 Max): one read drawn above the frame at its sample time, one read that is an image, ten reads missing from their first sample, two dim notes outside the registry under 3:1, one line outside the frame and one cut by its edge, two captions over a bright picture.
 - engines/README (HyperFrames, 画面文字检查): the contract and what it cannot see (text in images, WebGL or an offscreen canvas); playbook/02 layer 2: the method and the command; tools/ci.sh runs it on a fixture with one read per case, skipped where no Chrome is found.
 
 **Lessons from four films go into the docs**
diff --git a/bin/vh b/bin/vh
index f20a5cd..f9241ed 100755
--- a/bin/vh
+++ b/bin/vh
@@ -57,7 +57,7 @@
 #                               FAIL under one brisk read (CJK/7 + other/20 + 0.8 s, at least 1.5 s; exit 1), WARN under the target of the BRIEF's
 #                               Pace (exit 0); subtitles within reading speed. data-read="subtitle"|"label" and data-pace="…" mark clips
 #                               readcheck --budget <s>: how many characters fit in a span · readcheck <index.html|project> --export [--out f]: the composition's timed text
-#   textcheck <project|index.html> [--texts f.json] [--min-visible 0.7] [--min-contrast 3] [--samples 3] [--scan-step 1] [--caption-step 0.5] [--out dir] [--soft-gl]
+#   textcheck <project|index.html> [--texts f.json] [--min-visible 0.7] [--min-contrast 3] [--samples 3] [--scan-step 1] [--caption-step 0.5] [--caption-close 0.12] [--out dir] [--soft-gl] [--timeout 900]
 #                               text drawn into a canvas, which npx hyperframes check cannot see: a read covered by the picture (under 70% of it
 #                               shows), under 3:1, outside or cut by the frame, or under a DOM caption (exit 1); canvas text outside the registry
 #                               and captions over a bright picture warn. The composition opts in with window.__vh = { draw(t), texts? } (engines/README.md)
diff --git a/engines/README.md b/engines/README.md
index 73e3a9b..b4775eb 100644
--- a/engines/README.md
+++ b/engines/README.md
@@ -111,12 +111,12 @@ window.__vh = {
 };
 ```
 
-- **画字的函数不用改。** 检查在合成的脚本运行之前挂上 canvas 的 `fillText` / `strokeText`，记下每条字画在哪、用什么字体，能单独去掉一条字重画这一帧。所以字要用 2D canvas 的 `fillText` / `strokeText` 画：做成图片的、画进 WebGL 的、画在离屏 canvas 里再贴上来的字，它看不到，登记了会报"没画成 canvas 字"。逐字出现的动画字、拆成几次画的一行字、中间的"·"和箭头画成图形的，都按字母对得上。
+- **画字的函数不用改。** 检查在合成的脚本运行之前挂上 canvas 的 `fillText` / `strokeText`，记下每条字画在哪、用什么字体，能单独去掉一条字重画这一帧。所以字要用 2D canvas 的 `fillText` / `strokeText` 画：做成图片的、画进 WebGL 的、画在离屏 canvas 里再贴上来的字，它看不到，登记了会报"没画成 canvas 字"。字底下的"画面"是页面上所有 canvas、video、img 按层叠顺序合成的结果，字画在透明的一层上也按它后面那层量；CSS 背景、SVG 这类 DOM 不算在内。逐字出现的动画字、拆成几次画的一行字、中间的"·"和箭头画成图形的，都按字母对得上。
 - **登记表**：命令行给了 `--texts <文件>` 就用它，否则用 `window.__vh.texts`，再没有就读 `out/texts.json`（readcheck 读的同一份）。每条在它的时间窗里取 3 个时刻（开始后 0.4 s 到结束前 0.3 s），所以 start 要是字完整显示的那一刻，这也是 readcheck 的约定；登记早了会报"有的时刻没画全"。没有登记表也能跑，只做下面那遍扫描。
 - **没登记的字**每秒扫一遍全片，每行字在它最完整的那一刻量一次，有问题只警告：观众该读的，就登记进去。
 - `draw(t)` 要是 t 的纯函数（硬规则 1）：同一个 t 会画好几遍，两遍画面不一样会报出来，那一刻的数字不可信。
 - **浏览器**：`CHROME_PATH`，否则用 HyperFrames 渲染用的 chrome-headless-shell（缓存为空时先 `npx hyperframes browser ensure`），再否则用系统的 Chrome 或 Chromium，不用装 npm 包。合成从项目目录起一个只在本机 127.0.0.1 的服务来打开，尺寸按根元素的 `data-width` × `data-height`，设备像素比 1；先等 `window.__hf.buildReady`、`window.__vh.ready`（可选）和字体加载完。
-- **结果**：有登记的 read 被盖住（露出不到 70%）、低于 3:1、出画或被裁、压在字幕下，或画帧函数抛错，退出码 1；没登记的字、字幕底下的画面太亮只警告；没法检查（没有 `window.__vh.draw`、页面没加载起来、找不到浏览器）是 2，不算通过。每处问题存一张裁图到 `out/check/textcheck/`，全部数字在同一目录的 `textcheck.json`；阈值都能调，见 `bin/vh textcheck -h`。一支 457 s、107 条登记文字的片子在 M3 Max 上约 30 s 跑完。
+- **结果**：有登记的 read 被盖住（露出不到 70%）、低于 3:1、出画或被裁、压在字幕下，或画帧函数抛错，退出码 1；没登记的字、字幕底下的画面太亮只警告；没法检查（没有 `window.__vh.draw`、页面没加载起来、找不到浏览器、一条 canvas 字都没量到）是 2，不算通过。每处问题存一张裁图到 `out/check/textcheck/`，全部数字在同一目录的 `textcheck.json`；阈值都能调，见 `bin/vh textcheck -h`。一支 457 s、107 条登记文字的片子在 M3 Max 上约 13 s 跑完。
 
 ### 注意事项和已知问题（0.8.82 实测）
 
diff --git a/tools/textcheck/browser.mjs b/tools/textcheck/browser.mjs
index dca7fa0..e399c30 100644
--- a/tools/textcheck/browser.mjs
+++ b/tools/textcheck/browser.mjs
@@ -7,6 +7,8 @@ import http from "node:http";
 import os from "node:os";
 import path from "node:path";
 
+export class BrowserGone extends Error {}
+
 // launch(exe, flags) → { send(method, params, sessionId), once(event, sessionId), close(), version }
 export async function launch(exe, flags = []) {
   const profile = fs.mkdtempSync(path.join(os.tmpdir(), "vh-textcheck-"));
@@ -15,10 +17,24 @@ export async function launch(exe, flags = []) {
   const proc = spawn(exe, args, { stdio: ["ignore", "ignore", "pipe", "pipe", "pipe"] });
   let stderr = "";
   proc.stderr.on("data", (d) => { stderr = (stderr + d).slice(-4000); });
-  const exited = new Promise((res) => { proc.on("exit", res); proc.on("error", (e) => { stderr += String(e); res(); }); });
   const out = proc.stdio[3], inp = proc.stdio[4];
   const pending = new Map(), waiters = [], listeners = [];
-  let buf = Buffer.alloc(0), id = 0;
+  let buf = Buffer.alloc(0), id = 0, dead = null, started = false;
+  // a browser that exits or crashes fails every call still waiting, so nothing hangs until the watchdog
+  const gone = (why) => {
+    if (dead) return;
+    // its last log lines say why it would not start; once running, they are mostly noise
+    dead = new BrowserGone(`the browser is gone (${why})${!started && stderr.trim() ? ": " + stderr.trim().split("\n").slice(-3).join(" | ") : ""}`);
+    for (const p of pending.values()) p.reject(dead);
+    pending.clear();
+    for (const w of waiters.splice(0)) w.reject(dead);
+  };
+  const exited = new Promise((res) => {
+    proc.on("exit", (code, sig) => { gone(sig || `exit ${code}`); res(); });
+    proc.on("error", (e) => { stderr += String(e); gone(e.code || "error"); res(); });
+  });
+  out.on("error", (e) => gone(e.code || "pipe error"));
+  inp.on("error", (e) => gone(e.code || "pipe error"));
   inp.on("data", (d) => {
     buf = Buffer.concat([buf, d]);
     for (let i; (i = buf.indexOf(0)) >= 0;) {
@@ -34,21 +50,27 @@ export async function launch(exe, flags = []) {
     }
   });
   const send = (method, params = {}, sessionId) => new Promise((resolve, reject) => {
+    if (dead) return reject(dead);
     const i = ++id; pending.set(i, { resolve, reject, method });
     out.write(JSON.stringify({ id: i, method, params, ...(sessionId ? { sessionId } : {}) }) + "\0");
   });
-  const once = (method, session) => new Promise((resolve) => waiters.push({ method, session, resolve }));
+  const once = (method, session) => new Promise((resolve, reject) => (dead ? reject(dead) : waiters.push({ method, session, resolve, reject })));
   const on = (method, fn) => listeners.push({ method, fn });
+  // a race against a timer that is always cleared, so a pending timer never keeps node alive
+  const within = (p, ms, onTimeout) => {
+    let timer;
+    return Promise.race([p, new Promise((res, rej) => { timer = setTimeout(() => (onTimeout ? rej(onTimeout()) : res()), ms); })]).finally(() => clearTimeout(timer));
+  };
   const close = async () => {
-    try { await Promise.race([send("Browser.close"), new Promise((r) => setTimeout(r, 3000))]); } catch { /* already gone */ }
+    if (!dead) try { await within(send("Browser.close"), 3000); } catch { /* already gone */ }
     proc.kill(); await exited;
     fs.rmSync(profile, { recursive: true, force: true });
   };
   let version;
   try {
-    version = await Promise.race([send("Browser.getVersion"), exited.then(() => { throw new Error("the browser exited at start: " + stderr.trim().split("\n").slice(-3).join(" | ")); }),
-      new Promise((_, rej) => setTimeout(() => rej(new Error("the browser did not answer within 30 s")), 30000))]);
-  } catch (e) { proc.kill(); fs.rmSync(profile, { recursive: true, force: true }); throw e; }
+    version = await within(send("Browser.getVersion"), 30000, () => new Error("the browser did not answer within 30 s"));
+    started = true;
+  } catch (e) { proc.kill(); await within(exited, 3000); fs.rmSync(profile, { recursive: true, force: true }); throw e; }
   return { send, once, on, close, version: version.product };
 }
 
diff --git a/tools/textcheck/page.js b/tools/textcheck/page.js
index c092594..5ac45ae 100644
--- a/tools/textcheck/page.js
+++ b/tools/textcheck/page.js
@@ -23,7 +23,7 @@
       const st = {};
       for (const k of KEYS) st[k] = this[k];
       if (op === "stroke") for (const k of SKEYS) st[k] = this[k];
-      H.calls.push({ i, op, s: String(s), x: +x, y: +y, mw: arguments.length > 3 ? +maxWidth : undefined, m: this.getTransform(), st,
+      H.calls.push({ i, op, s: String(s), x: +x, y: +y, mw: maxWidth === undefined ? undefined : +maxWidth, m: this.getTransform(), st,
         a: this.globalAlpha * alphaOf(op === "fill" ? this.fillStyle : this.strokeStyle), col: op === "fill" ? this.fillStyle : this.strokeStyle, cv: this.canvas });
     }
     if (H.skip && H.skip.has(i)) return;
@@ -85,7 +85,7 @@
     for (const k in c.st) try { scratch[k] = c.st[k]; } catch (e) { /* a state the browser rejects */ }
     const m = scratch.measureText(c.s);
     let l = -m.actualBoundingBoxLeft, r = m.actualBoundingBoxRight;
-    if (c.mw !== undefined && m.width > c.mw && m.width > 0) { l *= c.mw / m.width; r *= c.mw / m.width; }   // maxWidth squeezes the line
+    if (Number.isFinite(c.mw) && m.width > c.mw && m.width > 0) { l *= c.mw / m.width; r *= c.mw / m.width; }   // maxWidth squeezes the line
     const pad = c.op === "stroke" ? (c.st.lineWidth || 1) / 2 : 0;
     const pts = [[l - pad, -m.actualBoundingBoxAscent - pad], [r + pad, -m.actualBoundingBoxAscent - pad], [l - pad, m.actualBoundingBoxDescent + pad], [r + pad, m.actualBoundingBoxDescent + pad]]
       .map(([dx, dy]) => c.m.transformPoint(new DOMPoint(c.x + dx, c.y + dy)));
@@ -101,26 +101,59 @@
     for (const r of runs) {
       const box = r.map(boxOf).reduce(union);
       const g = groups.find((g) => g.cv === r[0].cv && overlap(g.box, box));
-      if (g) { g.calls.push(...r); g.box = union(g.box, box); } else groups.push({ cv: r[0].cv, calls: [...r], box });
+      if (g) { g.calls.push(...r); g.runs.push(r); g.box = union(g.box, box); } else groups.push({ cv: r[0].cv, calls: [...r], runs: [r], box });
     }
     for (const g of groups) {
-      const fills = g.calls.filter((c) => c.op === "fill");
+      const fills = g.calls.filter((c) => c.op === "fill"), op = fills.length ? "fill" : "stroke";
       g.ink = fills.length ? fills : g.calls;
-      g.alpha = Math.min(...g.ink.map((c) => c.a));
+      // a glow pass under a crisp one is one read: as opaque as its most opaque pass (each pass as opaque as its faintest
+      // character, so kinetic type still counts as fading until every character is in)
+      g.alpha = Math.max(...g.runs.filter((r) => r[0].op === op).map((r) => Math.min(...r.map((c) => c.a))));
       g.skip = new Set(g.calls.map((c) => c.i));
     }
     return groups;
   }
 
-  // pixels of a canvas, copied into a canvas of our own first: after a few getImageData calls Chrome moves a canvas off
-  // the GPU, and the film would then draw every later frame on the CPU, many times slower
+  // The picture in a page rectangle, w x h: the page background, then every canvas, video and image over it in paint
+  // order (z-index, then document order), at its opacity. So text on a transparent layer is measured against what is
+  // behind it (a WebGL canvas, a video), and a layer above it counts as covering it. Other DOM (CSS backgrounds, SVG,
+  // text) is not in it. Drawn into a canvas of our own: after a few getImageData calls Chrome moves a canvas off the GPU,
+  // and the film would then draw every later frame on the CPU, many times slower.
   let copy = null;
-  function pixels(cv, x, y, w, h) {
+  const sizeOf = (el) => (el.tagName === "CANVAS" ? [el.width, el.height] : el.tagName === "VIDEO" ? [el.videoWidth, el.videoHeight] : [el.naturalWidth, el.naturalHeight]);
+  function layers(P) {
+    const out = [];
+    for (const el of document.querySelectorAll("canvas, video, img")) {
+      const [iw, ih] = sizeOf(el), r = el.getBoundingClientRect();
+      if (!iw || !ih || r.width <= 0 || r.height <= 0 || !overlap([r.left, r.top, r.right, r.bottom], P)) continue;
+      let o = 1, hidden = getComputedStyle(el).visibility !== "visible";
+      for (let e = el; e && e.nodeType === 1 && !hidden; e = e.parentElement) { const cs = getComputedStyle(e); if (cs.display === "none") hidden = true; o *= +cs.opacity; }
+      if (!hidden && o > 0.002) out.push({ el, r, iw, ih, o, z: parseInt(getComputedStyle(el).zIndex, 10) || 0 });
+    }
+    return out.map((l, i) => [l, i]).sort((a, b) => a[0].z - b[0].z || a[1] - b[1]).map((x) => x[0]);
+  }
+  function background() {
+    for (const el of [document.querySelector("[data-composition-id]"), document.body, document.documentElement]) {
+      if (!el) continue;
+      const c = getComputedStyle(el).backgroundColor, v = (c.match(/[\d.]+/g) || []).map(Number);
+      if (v.length >= 3 && !(v.length >= 4 && v[3] === 0)) return c;
+    }
+    return "#fff";   // the browser's own page colour
+  }
+  function compose(P, w, h, L = layers(P)) {
     if (!copy) copy = document.createElement("canvas").getContext("2d", { willReadFrequently: true });
     copy.canvas.width = w; copy.canvas.height = h;
-    copy.drawImage(cv, x, y, w, h, 0, 0, w, h);
+    copy.fillStyle = background(); copy.fillRect(0, 0, w, h);
+    const pw = P[2] - P[0], ph = P[3] - P[1];
+    for (const l of L) {
+      const sx = l.iw / l.r.width, sy = l.ih / l.r.height;
+      copy.globalAlpha = Math.min(1, l.o);
+      copy.drawImage(l.el, (P[0] - l.r.left) * sx, (P[1] - l.r.top) * sy, pw * sx, ph * sy, 0, 0, w, h);
+    }
+    copy.globalAlpha = 1;
     return copy.getImageData(0, 0, w, h).data;
   }
+  const pixels = (cv, x, y, w, h) => compose(toPage(cv, [x, y, x + w, y + h]), w, h);
   const rgba = (c) => {   // a CSS colour string as [r, g, b] (its alpha is in the call's own alpha), else null
     if (typeof c !== "string") return null;
     let m = c.match(/^#([0-9a-f]{6})$/i);
@@ -139,7 +172,7 @@
       for (const k in c.st) try { g[k] = c.st[k]; } catch (e) { /* as above */ }
       g.globalAlpha = 1; g.globalCompositeOperation = "source-over"; g.shadowBlur = 0; g.shadowColor = "transparent"; g.filter = "none";
       g.fillStyle = g.strokeStyle = "#fff";
-      const args = c.mw === undefined ? [c.s, c.x, c.y] : [c.s, c.x, c.y, c.mw];
+      const args = Number.isFinite(c.mw) ? [c.s, c.x, c.y, c.mw] : [c.s, c.x, c.y];
       if (c.op === "fill") g.fillText(...args); else g.strokeText(...args);
     }
     return g.getImageData(0, 0, w, h).data;
@@ -197,7 +230,6 @@
     return out;
   }
   const toPage = (cv, b) => { const r = cv.getBoundingClientRect(), sx = r.width / cv.width, sy = r.height / cv.height; return [r.left + b[0] * sx, r.top + b[1] * sy, r.left + b[2] * sx, r.top + b[3] * sy]; };
-  const toCanvas = (cv, b) => { const r = cv.getBoundingClientRect(), sx = cv.width / r.width, sy = cv.height / r.height; return [(b[0] - r.left) * sx, (b[1] - r.top) * sy, (b[2] - r.left) * sx, (b[3] - r.top) * sy]; };
   const colour = (s) => { const v = (String(s).match(/[\d.]+/g) || []).map(Number); return v.length >= 3 ? v.slice(0, 3).map((x) => (x <= 1 && /^color\(/.test(s) ? x * 255 : x)) : [255, 255, 255]; };
 
   // one read at time t: every copy measured, the most legible one returned
@@ -299,7 +331,7 @@
       }
       return [...seen.values()];
     },
-    // the picture under each DOM caption's lines: the share of its pixels within 3:1 of the caption's colour
+    // the picture under each DOM caption's lines (canvases, videos and images): the share of it within 3:1 of the caption's colour
     async captions(times) {
       const out = [];
       for (const t of times) {
@@ -308,11 +340,9 @@
           const col = colour(getComputedStyle(c.el).color), Lc = 0.2126 * LIN[Math.round(col[0])] + 0.7152 * LIN[Math.round(col[1])] + 0.0722 * LIN[Math.round(col[2])];
           let n = 0, close = 0, box = null;
           for (const r of c.rects) {
-            const cv = document.elementsFromPoint((r[0] + r[2]) / 2, (r[1] + r[3]) / 2).find((e) => e.tagName === "CANVAS");
-            if (!cv) continue;
-            const q = toCanvas(cv, r), x = Math.max(0, Math.floor(q[0])), y = Math.max(0, Math.floor(q[1])), w = Math.min(cv.width, Math.ceil(q[2])) - x, h = Math.min(cv.height, Math.ceil(q[3])) - y;
-            if (w <= 0 || h <= 0) continue;
-            const d = pixels(cv, x, y, w, h);
+            const L = layers(r), w = Math.round(r[2] - r[0]), h = Math.round(r[3] - r[1]);
+            if (!L.length || w <= 0 || h <= 0) continue;   // no canvas, video or image under it: a DOM picture, not measured here
+            const d = compose(r, w, h, L);
             for (let p = 0; p < d.length; p += 8) { n++; if (ratio(lum(d, p), Lc) < 3) close++; }
             box = box ? union(box, r) : r;
           }
diff --git a/tools/textcheck/textcheck.mjs b/tools/textcheck/textcheck.mjs
index b9080e0..2adab11 100644
--- a/tools/textcheck/textcheck.mjs
+++ b/tools/textcheck/textcheck.mjs
@@ -30,6 +30,9 @@
 // Each read is sampled --samples (3) times across its window, from 0.4 s after its start to 0.3 s before its end;
 // samples where it is still fading (alpha under 0.95) are not judged when an opaque one exists.
 //
+// The picture is what the viewer sees there: every canvas, video and image of the page over its background, so text on
+// a transparent layer is measured against the layer behind it; other DOM (CSS backgrounds, SVG) is not part of it.
+//
 // Also, never failing the run: canvas text outside the registry (every --scan-step seconds, each distinct line judged
 // once, at the middle of its longest opaque stretch; a line never seen at half opacity or more is left out); registered reads not drawn as canvas text at some or all of their
 // samples (an image, DOM text, or a window that is off); and DOM captions (data-read="subtitle", readcheck's mark) over
@@ -39,10 +42,10 @@
 // Writes <out>/textcheck.json (every number) and a crop per finding (<out>/<t>s-<kind>.png); out defaults to
 // <project>/out/check/textcheck. Exit: 0 no read failed (warnings allowed) · 1 a registered read is covered, under the
 // contrast, outside or cut by the frame, or under a caption, or the frame function threw · 2 could not check (no
-// window.__vh.draw, the page did not load, no browser): not a pass.
+// window.__vh.draw, the page did not load, no browser, or no canvas text measured at all): not a pass.
 import fs from "node:fs";
 import path from "node:path";
-import { launch, serve } from "./browser.mjs";
+import { BrowserGone, launch, serve } from "./browser.mjs";
 
 process.stdout.on("error", (e) => { if (e.code !== "EPIPE") throw e; });   // a reader that stops early (| head) does not leave Chrome behind
 const HELP = fs.readFileSync(new URL(import.meta.url), "utf8").split("\nimport ")[0].replace(/^\/\/ ?/gm, "");
@@ -169,7 +172,8 @@ try {
       const fails = judged.filter((q) => q.flags.some((f) => FAIL.includes(f)));
       const score = (q) => (q.contrast || 0) * (q.share || 0);
       r.worst = fails.length ? fails.sort((a, b) => b.flags.length - a.flags.length || score(a) - score(b))[0] : judged.slice().sort((a, b) => score(a) - score(b))[0];
-      r.status = fails.length ? "fail" : "ok";
+      // drawn, but nothing judged could be measured (a glyph too small or squeezed to nothing): not a pass
+      r.status = fails.length ? "fail" : judged.some((q) => q.share !== undefined) ? "ok" : "unmeasured";
       r.missingAt = smp.filter((q) => !q.found).map((q) => q.t);
       r.faded = !opaque.length;
       r.unstable = found.some((q) => q.flags.includes("unstable"));
@@ -208,6 +212,7 @@ try {
   // report
   const failed = reads.filter((r) => r.status === "fail"), ok = reads.filter((r) => r.status === "ok");
   const notDrawn = reads.filter((r) => r.status === "not drawn"), part = reads.filter((r) => r.status === "ok" || r.status === "fail").filter((r) => r.missingAt.length);
+  const unmeasured = reads.filter((r) => r.status === "unmeasured");
   const dom = reads.filter((r) => r.status.startsWith("dom")), badWin = reads.filter((r) => r.status === "bad window");
   const unstable = reads.filter((r) => r.unstable), extraBad = extra.filter((e) => e.flagged);
   fs.mkdirSync(outDir, { recursive: true });
@@ -230,6 +235,7 @@ try {
     if (ok.length) console.log(`${G} ${ok.length} read(s) in the frame, at least ${pct(opt.minVisible)} visible and ${opt.minContrast}:1`);
     if (failed.length) console.log(`${R} ${failed.length} read(s) covered, under ${opt.minContrast}:1, outside or cut by the frame, or under a caption:`);
     for (const r of failed) { const w = r.worst; w.crop = await crop(w.t, w.box, w.flags.find((f) => FAIL.includes(f))); console.log(`   ${fmt(w.t)}  ${words(w)}  ${short(r.text)}`); }
+    if (unmeasured.length) console.log(`${Y} ${unmeasured.length} read(s) drawn, but too small to measure at every sample: ${unmeasured.map((r) => short(r.text)).join(" · ")}`);
     if (notDrawn.length) console.log(`${Y} ${notDrawn.length} read(s) not drawn as canvas text at any sample (an image? a window that is off?): ${notDrawn.map((r) => short(r.text)).join(" · ")}`);
     if (part.length) console.log(`${Y} ${part.length} read(s) missing from some samples inside their window (on screen for less than registered?):`);
     for (const r of part.slice(0, 12)) console.log(`   not at ${r.missingAt.map((t) => t.toFixed(2)).join(", ")} s (window ${r.start}–${r.end} s)  ${short(r.text)}`);
@@ -254,14 +260,16 @@ try {
   if (unstable.length) console.log(`${Y} ${unstable.length} read(s) at a time where the frame drawn twice is not the same (hard rule 1); their numbers are unreliable: ${unstable.map((r) => short(r.text)).join(" · ")}`);
   const errs = [...new Map(errors.map((e) => [e.msg.split("\n")[0], e])).values()];
   if (errs.length) { console.log(`${R} the frame function threw or logged an error at ${errs.length} point(s):`); for (const e of errs.slice(0, 8)) console.log(`   ${fmt(e.t)}  ${e.msg.split("\n")[0]}`); }
-  if (!reg.length && !extra.length) console.log(`${Y} no canvas text found at all: is the text drawn some other way (DOM, WebGL, images)?`);
+  // nothing measured is not a pass: no registered read was found and measured as canvas text, and no other line was seen
+  const nothing = !extra.length && !reads.some((r) => r.status === "ok" || r.status === "fail");
+  if (nothing) console.log(`${R} nothing measured: no canvas text found${reg.length ? " for any registered read" : ""}. Is the text drawn some other way (DOM, WebGL, images, an offscreen canvas)?`);
   fs.writeFileSync(path.join(outDir, "textcheck.json"), JSON.stringify({ composition: html, size: [W, H], duration: dur, registry: regFrom || null, options: opt, reads, extra, captions: caps, errors }, null, 1));
   const rel = (p) => { const r = path.relative(process.cwd(), p); return r && !r.startsWith("..") ? r : p; };
   console.log(`  ${crops.size ? `crops: ${rel(outDir)}/*.png · ` : ""}every number: ${rel(path.join(outDir, "textcheck.json"))}`);
-  if (!reg.length && !extra.length) process.exitCode = 2;
+  if (nothing) process.exitCode = 2;
   else process.exitCode = failed.length || errs.length ? 1 : 0;
 } catch (e) {
-  console.error("textcheck: " + ((e && e.message) || e) + (e instanceof Stop ? "" : "\n" + (e && e.stack || "")));
+  console.error("textcheck: " + ((e && e.message) || e) + (e instanceof Stop || e instanceof BrowserGone ? "" : "\n" + (e && e.stack || "")));
   process.exitCode = 2;
 } finally {
   clearTimeout(watchdog);

From cc0b2540c50d56980ca32cb125a2438d09044a39 Mon Sep 17 00:00:00 2001
From: zhanglinghao <zhangczssx@gmail.com>
Date: Wed, 7 Oct 2026 01:11:40 +0800
Subject: [PATCH 3/4] textcheck: a stray promise rejection exits 2, not 1

On Linux CI the run without window.__vh exited 1 instead of 2: a promise left by the
start-up race rejected when the browser closed, and Node exits 1 on an unhandled
rejection, which here means a read failed. That promise is gone since the review
fixes; the page-load waiter now has a handler, and any other stray rejection is
reported as a failure to check (2).
---
 tools/textcheck/textcheck.mjs | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/tools/textcheck/textcheck.mjs b/tools/textcheck/textcheck.mjs
index 2adab11..f33953f 100644
--- a/tools/textcheck/textcheck.mjs
+++ b/tools/textcheck/textcheck.mjs
@@ -48,6 +48,8 @@ import path from "node:path";
 import { BrowserGone, launch, serve } from "./browser.mjs";
 
 process.stdout.on("error", (e) => { if (e.code !== "EPIPE") throw e; });   // a reader that stops early (| head) does not leave Chrome behind
+// Node exits 1 on an unhandled rejection, which here means "a read failed"; a stray one is a failure to check (2)
+process.on("unhandledRejection", (e) => { console.error("textcheck: " + ((e && e.message) || e)); process.exitCode = 2; });
 const HELP = fs.readFileSync(new URL(import.meta.url), "utf8").split("\nimport ")[0].replace(/^\/\/ ?/gm, "");
 const argv = process.argv.slice(2);
 if (!argv.length || argv.includes("-h") || argv.includes("--help")) { process.stdout.write(HELP); process.exit(argv.length ? 0 : 2); }
@@ -129,6 +131,7 @@ try {
   };
   const call = (fn, ...args) => ev(`window.__vhTC.${fn}(${args.map((a) => JSON.stringify(a)).join(", ")})`);
   const loaded = browser.once("Page.loadEventFired", s);
+  loaded.catch(() => { /* a browser that dies first fails it; the race below reports that */ });
   await browser.send("Page.navigate", { url: server.url + encodeURIComponent(path.basename(html)) }, s);
   let loadTimer;
   await Promise.race([loaded, new Promise((_, rej) => { loadTimer = setTimeout(() => rej(new Error("the page did not load within 60 s")), 60000); })]).catch((e) => stop(e.message)).finally(() => clearTimeout(loadTimer));

From 5e19a5365c41b0e50f5112e35b37bc91fa94c60f Mon Sep 17 00:00:00 2001
From: zhanglinghao <zhangczssx@gmail.com>
Date: Wed, 7 Oct 2026 01:36:59 +0800
Subject: [PATCH 4/4] textcheck: cleaning up never changes the exit code

Linux CI still saw exit 1 for the run without window.__vh, after the right message.
The only code after the verdict is the clean-up: closing the browser and removing its
temporary profile, which Chrome's helper processes may still be writing to just after
it exits (rmSync then throws, and an error out of the module's finally exits 1). The
profile removal now retries and swallows its error, closing is wrapped, and tools/ci.sh
prints the end of the output on a failure (it printed the start, which hid the cause).
---
 tools/ci.sh                   | 4 ++--
 tools/textcheck/browser.mjs   | 7 +++++--
 tools/textcheck/textcheck.mjs | 5 +++--
 3 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/tools/ci.sh b/tools/ci.sh
index 6df26a5..90bce39 100755
--- a/tools/ci.sh
+++ b/tools/ci.sh
@@ -776,12 +776,12 @@ print("\n".join(bad))
 sys.exit(1 if bad else 0)
 PY
   then ok "textcheck: covered, faint, out-of-frame and captioned-over reads fail (exit 1); outlined, kinetic and split reads pass; a late read, a faint line outside the registry and a caption over a bright band warn"
-  else bad "textcheck on its fixture (exit $rc): $(printf '%s' "$a" | head -c 800)"; fi
+  else bad "textcheck on its fixture (exit $rc): $(printf '%s' "$a" | tail -c 1200)"; fi
   # without the contract: nothing can be drawn on demand, so exit 2 and say what to add
   sed 's/window.__vh = { draw, texts: TEXTS };//' tools/textcheck/fixture/index.html > "$t/index.html"
   a=$(vh textcheck "$t" --out "$t/out2" 2>&1); rc=$?
   case "$rc:$a" in 2:*"window.__vh = { draw"*) ok "textcheck without window.__vh.draw exits 2 and names the line to add" ;;
-    *) bad "textcheck without the contract: exit $rc: $(printf '%s' "$a" | head -c 300)" ;; esac
+    *) bad "textcheck without the contract: exit $rc: $(printf '%s' "$a" | tail -c 800)" ;; esac
   rm -rf "$t"
 }
 
diff --git a/tools/textcheck/browser.mjs b/tools/textcheck/browser.mjs
index e399c30..36a7493 100644
--- a/tools/textcheck/browser.mjs
+++ b/tools/textcheck/browser.mjs
@@ -61,16 +61,19 @@ export async function launch(exe, flags = []) {
     let timer;
     return Promise.race([p, new Promise((res, rej) => { timer = setTimeout(() => (onTimeout ? rej(onTimeout()) : res()), ms); })]).finally(() => clearTimeout(timer));
   };
+  // the profile folder: Chrome's helper processes can still be writing to it just after the main one exits (Linux),
+  // so retry, and never let a leftover temp folder turn into an error
+  const removeProfile = () => { try { fs.rmSync(profile, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); } catch { /* left in the temp folder */ } };
   const close = async () => {
     if (!dead) try { await within(send("Browser.close"), 3000); } catch { /* already gone */ }
     proc.kill(); await exited;
-    fs.rmSync(profile, { recursive: true, force: true });
+    removeProfile();
   };
   let version;
   try {
     version = await within(send("Browser.getVersion"), 30000, () => new Error("the browser did not answer within 30 s"));
     started = true;
-  } catch (e) { proc.kill(); await within(exited, 3000); fs.rmSync(profile, { recursive: true, force: true }); throw e; }
+  } catch (e) { proc.kill(); await within(exited, 3000); removeProfile(); throw e; }
   return { send, once, on, close, version: version.product };
 }
 
diff --git a/tools/textcheck/textcheck.mjs b/tools/textcheck/textcheck.mjs
index f33953f..45485e8 100644
--- a/tools/textcheck/textcheck.mjs
+++ b/tools/textcheck/textcheck.mjs
@@ -275,7 +275,8 @@ try {
   console.error("textcheck: " + ((e && e.message) || e) + (e instanceof Stop || e instanceof BrowserGone ? "" : "\n" + (e && e.stack || "")));
   process.exitCode = 2;
 } finally {
+  // cleaning up never changes the verdict: the exit code is already set
   clearTimeout(watchdog);
-  if (browser) await browser.close();
-  if (server) await server.close();
+  try { if (browser) await browser.close(); } catch (e) { console.error("textcheck: closing the browser: " + ((e && e.message) || e)); }
+  try { if (server) await server.close(); } catch { /* the process is exiting anyway */ }
 }