Browser Video 是一个录制网页演示与验证视频的技能，建立在 playwright-cli 的 screencast 能力之上。它假定 playwright-cli 已在 PATH 中，并接续其 references/video-recording.md 中关于 screencast 与 overlay API 的说明，重点在于如何录出“正确”的一条视频。
用途 该技能面向需要录制网页操作演示或验证视频的场景。其核心立场是：一次运行成功（返回 done、退出码 0）只能说明脚本执行了，不能说明视频内容正确——例如点击偏离目标 200 像素、画面中没有指针等问题都可能在“绿跑”下发生。因此它把抽帧核验作为交付前的必备步骤。
主要能力与规则
- 每个浏览器会话只录一条视频：叠加层会泄漏，持续时间已过的 overlay 可能跨 page.goto、跨 screencast.stop() 残留，并出现在之后两次录制中。技能要求每个片段使用全新的命名会话，录完即关闭；page.screencast.hideOverlays() 可在 stop() 前清理泄漏的叠加层，但只有新会话才是确定性的。示例命令：playwright-cli -s=take1 open https://example.com/、playwright-cli -s=take1 video-show-actions、playwright-cli -s=take1 run-code --filename hero.js、playwright-cli -s=take1 close。
- 让操作可见：screencast 不记录光标，page.mouse.move() 移动的是不可见对象。在脚本运行前对会话执行 video-show-actions，录制中会出现动画指针和标注每步操作名称的 callout；--cursor pointer 为默认，--cursor none 关闭指针但保留 callout。它能标注 run-code 触发的操作，可取代手写的光标叠加层。
- 两阶段工作流：先用 CLI 命令（goto/snapshot/click/fill）探索真实流程、不录制，以了解定位器与应用锚点；再用 run-code 脚本录制正式片段，一次成片，节奏可控，可从 assets/hero-template.js 复制并适配（包含坐标映射、滑动辅助与章节标记）。
- 缩放 iframe 中的坐标：boundingBox() 不校正 CSS transform 对 iframe 的缩放，在 “Fit 55%” 等情况下会导致点击偏移。技能给出通过 iframe 盒子和元素在 iframe 内的 getBoundingClientRect 计算真实缩放比例、再映射坐标的方法；在非缩放 iframe 外 boundingBox() 正常，无需此处理。
验证方式 交付前抽取视频帧查看，这是唯一能发现上述问题的步骤。可用 scripts/video.sh probe 查看时长、尺寸、编码；用 sheet 把 6 帧拼成一张 PNG；用 --around 与 --window 猎取短时叠加层。查看拼图时需检查四点：指针可见且靠近点击位置、目标被命中且应用有响应、没有上一片段残留的叠加层、交付尺寸下文字可读。短标注可能恰好落在等距帧之间，需用窄窗口确认其渲染。默认交付 .mp4（H.264、yuv420p、faststart），因为 .webm 在部分播放器无法打开。
适用场景与录制建议 适用于网页操作演示视频和验证视频的录制。若流程会改变状态（如发评论），应在录制前准备可重建的一次性 fixture（新账号、看板、文档或种子数据），避免一次录制就消耗掉真实目标；只读流程不涉及此问题。面向真人观看的视频还建议：用 pressSequentially(text, { delay: 55 }) 模拟打字节奏、mouse.move 分 28 步后停顿约 500ms 再点击、用 showChapter 做章节分割、结尾用 showOverlay 高亮结果约 3 秒，时长控制在 20–40 秒。
边界 该技能不涉及 playwright-cli 本身的 screencast/overlay/chapter API 细节，不负责从已有视频合成静帧（video-thumbnails），不做终端录制（terminal-control、terminal-fabricate），也不判断证据是否支持某项主张（prove-it）——它只负责证据如何被捕获。修改脚本后应运行 tests/video.bats 验证 CLI 约定。
限制 使用前提是 playwright-cli 在 PATH 中。初次在缩放 iframe 之外的环境需要额外坐标映射代码。叠加层泄漏需要通过新会话规避。最终视频是否被判定正确，依赖人工查看抽帧拼图，而非自动化通过信号。