Covers in other ratios, without their title, with a camera and a title of their own: frames --covers --ratios and --no-title, s.cover, titles in several colours

[ZLHad]

What and why · 改了什么、为什么

几支长片各写了一份封面脚本，做的是同一套机械活：出不带字的底图（临时改 COVERS 去掉标题，或者拷一份项目把界面画成空的）、只给封面换机位（在 cover() 里设全局变量）、双色标题（覆盖 coverTitle）、从 16:9 的帧裁出 9:16、3:4、4:3 再另排标题。这一版把这些做成工具；裁哪里、怎么取景、用什么字，仍由项目定。

• bin/vh frames <项目> --covers --no-title：不画标题的封面，out/covers/<id>-clean.png。页面合约的 cover(id, o) 接受 { title: false }，并返回 { title: false } 表示照办了；不返回的页面（旧的引擎拷贝）不出图，报出原因，不会给出一张带字的"底图"。
• --ratios 9:16,3:4,4:3（任意 w:h）：每张封面每个比例一张 out/covers/<id>-9x16.png，短边 1080 × --dpr。做的是裁切，每行输出都写明：封面画面里正好这个比例、整数像素的最大一块（1920 × 1080 的片子里 9:16 是 603 × 1072），围着项目给的 ratios[r].focus，给了 ratios[r].cam 就用它代替封面的机位；页面按裁切需要的像素比来画（9:16 约 1.8 × --dpr），画面不放大。标题是项目的 ratios[r].title（坐标按这个比例的像素，9:16 是 1080 × 1920），没写就把封面标题居中缩放挪过来当起点。ready 按各比例查标题宽不宽得下，bin/vh fonts check 也画一遍；最后打出 bin/vh cover-preview 那一行。
• canvas-film：画封面时镜头 draw(t, s) 的 s.cover 是封面 id（片子本身的帧里是 null），镜头可以给封面换取景。封面标题的 color 可以每行一个，一行可以写成一串 run（["…", { text, color }]），先描边后填字；family、weight 可选，默认仍是 "Film Heavy" 900。旧写法画出来和以前一样。
• 文档：canvas-film README 的"封面"（新增"其他比例"一节和旧拷贝的迁移说明）、CONTRACT 的 covers 一行、playbook/10 封面一节一句指路、bin/vh 帮助、CHANGELOG。

English summary. frames --covers --no-title draws clean backgrounds; the contract's cover(id, o) must confirm { title: false } or the host refuses. --ratios makes each cover in other aspect ratios as an honest crop (whole px, exact ratio, around a project-given focus, optional per-ratio camera) captured from a page drawn at the pixel ratio the crop needs, with a title the project lays out in that ratio's own px (or a fitted default as a starting point). s.cover exposes the cover id to shots only while a cover is drawn. Cover titles gain per-line colours, coloured runs within a line, and a configurable family/weight. Film frames are unchanged.

How it was verified · 怎么验证的

• tools/ci.sh --committed（VH_BASH=/bin/bash、LC_ALL=C，shellcheck、pyflakes 按 CONTRIBUTING 的办法真的跑了）通过；跳过 1 项（本机没装 HyperFrames 运行时）。新增 6 项回归（后两项见下面的 Review fixes），前 4 项在 canvas-film 模板上：
  • --no-title：和带标题的封面相比，标题暗带以上的行是同一幅画面（PSNR ≥ 40 dB；本机是 inf），标题所在的行不同（< 30 dB；本机约 6 dB）。两次分开打开页面不一定逐字节相同（GitHub 的 macOS 机器上就不同），所以比 PSNR；ffmpeg 失败或读不出数值时这一项算失败，没装 ffmpeg 时跳过；
  • --ratios 9:16,3:4,4:3：输出正好 1080 × 1920、1080 × 1440、1440 × 1080，输出写明是裁切；9-16 这种写法在开浏览器前就退出 2；
  • 把 window.film.cover 改回旧的 cover(id) { cover(id); }：--no-title 退出 1、报出原因、不写文件；
  • 一个镜头在 s.cover === "A" 时画一块品红：封面（带字和不带字）左上角是品红；片子在 4.9 s 和封面自己的时刻的帧和模板逐字节相同、没有品红。
• 和 origin/main 的模板对比：片子 9 个时刻（0、2.5、4.9、7、10.111、12.8、16、20、23 s）的帧、16:9 的封面 A 都逐字节相同。
• 手动跑过：--ratios 16:9,9:16,3:4,4:3（--dpr 1）和 --ratios 9:16,3:4,1:1,2.35:1 --dpr 2（2160 × 3840、2160 × 2880、2160 × 2160、5076 × 2160），尺寸都准；看过联系表：9:16 用模板自己写的双色两行标题，3:4、4:3 用默认排法；ready 对坏的比例名、超出画框的比例机位、写错的 focus、排不下的比例标题各报一条；bin/vh fonts check 在模板上通过。

Review fixes · 按 Codex 的评审改的（01b2c77，另合了 main 的 #108）

1. [P2] 默认比例标题被字号下限撑出画面：以前先按宽度缩小字号，txt() 又把它抬回 FILM.minText（下限 80 时，20 个字的标题在 9:16 算出 48 px，实际画 80 px、1600 px 宽，两头裁掉，退出 0）。现在按实际画出的字号排；还放不下的行按 wrap() 的断法折成几行，颜色跟着字走；折了还放不下（一个词就比画面宽，或者行数多到高度装不下），声明过的比例在 ready 报错，--ratios 临时要的比例在画的时候报错，都写明是哪张封面、哪个比例，让项目写 ratios[r].title。cover() 的返回多了 lines，输出写"re-set for it on 2 lines"；ready 的超宽提示写实际画出的字号。CI：下限 80 时这个标题在 9:16 和 3:4 都折成两行、退出 0；一个放不下的长词让 ready 报 cover L (3:4) … give it ratios["3:4"].title。
2. [P2] 画图的像素比按 HTML 估的尺寸定：页面合约允许 window.film.width/height 覆盖 HTML 的尺寸，以前 4:3 会在 1× 下画、把 1080 × 810 的裁切放大到 1440 × 1080。现在页面打开后按它真实的尺寸重算，不一样就用对的像素比重开一次（canvas 在页面启动时按 devicePixelRatio 定大小，所以要重开，不能只改视口）；裁切仍被放大时，输出那一行会写出来。CI：一个只在 window.film 里写 1080 × 1920 的页面，4:3 在 1.333× 下画，出 1440 × 1080，没有"scaled up"。
3. CI 的 psnr()：ffmpeg 失败或读不出数值时返回空值，这一项判失败（以前返回 0.0，被"标题暗带 < 30"当成通过）。

两条新 CI 在改之前的代码上都会失败（已经确认过）。改完以后模板 9 个时刻的帧和 16:9 封面 A 仍和 main 逐字节相同。

Review focus · 请重点看

1. 形状：放在 frames --covers 下面（--no-title、--ratios），没有另开 bin/vh covers，所以 CLAUDE.md 的命令表不用改。
2. 截图的尺寸：Chrome 的 clip 按整数 CSS px 截（实测 607.5 px 宽在 1.778 倍下出 1079 px），所以引擎给的裁切是整数像素、正好这个比例，宿主用 clip.scale 缩到目标尺寸，出来不对就反向再截一次，还不对就报错。9:16 因此比理论上的 607.5 × 1080 少 8 px 高（603 × 1072）。
3. 比例封面的标题在裁切框里按比例像素画，阴影的模糊跟着缩放（画标题时临时把 PRX 乘上缩放）；一次跑里同时要 16:9 和别的比例时，16:9 也在较高的像素比下画、再缩回去，所以和单独 --covers 出的那张不是逐字节相同（画面一样）。
4. 默认排法（居中、整体缩到宽度的 88 %、最后一行基线在 80 % 高度）只是起点，文档这么写了；要不要干脆不给默认、没写 ratios[r].title 就不出标题，可以讨论。

Checklist · 自查

• tools/ci.sh --committed passes · 通过
• User-visible change noted in CHANGELOG.md → Unreleased · 已记进 CHANGELOG
• CLAUDE.md unchanged (no new command) · 没改 CLAUDE.md，不用 sync-agents