WP32：防休眠、唤醒恢复与清理

状态：已完成（2026-10-18）。阶段：M3。主责：Runtime / 运维。 上层工作项：R06（恢复/运行环境）；详见模块计划。本包是该工作项的实施拆分，不是另一份配置契约。

前置与输入

前置完成：WP31。 字段与行为以统一契约为准；所有依赖编号见执行清单。

修改范围与交付

• 修改范围：本地构建产物放映下的屏幕防休眠（Screen Wake Lock）与权限拒绝回退、系统休眠/唤醒和前后台切换后的状态校验、本地静态服务中断及浏览器重载/崩溃后的显式恢复，以及退出后的 wake lock、媒体、计时器和监听器释放。
• 交付物：目标设备上的防休眠与恢复操作指引、可验证状态和清理证据。
• 提交边界：不默认申请设备权限，不承诺所有设备防休眠可用；不新增远端入口、票据或代理恢复逻辑，网络与构建访问票据故障由后续独立代理服务负责。

完成标准

• [x] 实现及评审覆盖上述修改范围，未超出提交边界。
• [x] 行为验收：权限拒绝可普通放映；休眠/唤醒和前后台切换不连跳、不重复推进；本地服务中断或浏览器重载后不无限重试或自动连跳，按明确步骤重新进入且起点行为与配置一致；退出释放锁、媒体、计时器和监听。
• [x] 验证范围：桌面浏览器与本地静态服务的休眠/唤醒、前后台、服务中断和浏览器重载恢复；记录设备、权限状态和未覆盖项。
• [x] 关联验收：M3 专项：设备与恢复；见联调与验收计划。
• [x] 记录代码版本、实际测试命令/结果、未运行项及原因，产物保存到任务专属临时目录。
• [x] 回填本卡状态与证据；阶段能力是否开放由对应阶段出口包决定，单包完成不等于整阶段交付。

建议提交标题：WP32：防休眠、唤醒恢复与清理。通常按一个可评审 PR 实施；若实际改动仍过大，先按输入/输出再拆子包，保留父编号和依赖。

测试环境与命令选择遵循 dev-start-test，不因执行本卡重复启动服务或重置开发数据。

实施记录（2026-10-18）

• 防休眠：新增 useScreenWakeLock，只在自动放映的准备/播放阶段持有 Screen Wake Lock；暂停、失败、结束、停止、卸载与控制器销毁立即释放。系统回收 sentinel 后在可见且仍播放时补申请；同一轮自动翻页不重复申请。不可用、NotAllowedError 或 SecurityError 收敛为 unsupported/denied，普通放映继续，权限拒绝后不在自动翻页中反复请求。控制条以 data-wake-lock 暴露可验证状态，不新增设备权限默认申请。
• 中断恢复：页面 freeze、持久化 pageshow 和 visibilitychange 隐藏均先暂停并释放屏幕锁；重新可见不自动继续，必须显式点击。控制器新增计时迟到守卫（回调晚于截止时间 3s 以上）先暂停，避免系统休眠或长冻结后醒来连跳；旧 generation 回调仍被丢弃。
• 服务与重载恢复：媒体元素处于 error 或 NETWORK_NO_SOURCE 时，重试播放前先 load() 重新选源，本地静态服务恢复后可继续；错误态不自动翻页、不无限重试。浏览器重载从 URL 指定路由重新进入并按项目 auto_start 启动。
• 本地放映操作指引：按 WP31 的固定产物与静态服务命令启动并打开入口；系统休眠/窗口隐藏/页面冻结后回到放映窗口，点击控制条继续（不会自动补跳）；本地服务中断时先恢复静态服务，再点击重试；浏览器关闭或崩溃后重新打开同一 URL，按项目 auto_start 自动开始或点击开始；结束放映后确认控制条为暂停且屏幕锁释放。权限被拒或设备不支持防休眠时按普通放映操作，不阻断翻页。
• 自动化：pnpm --dir runtime test 为 142 files/1105 passed/3 skipped；pnpm --dir runtime check、pnpm --dir runtime build 与改动文件 ESLint 通过。定向媒体/放映测试 63 passed，覆盖屏幕锁申请/暂停/隐藏/卸载释放、sentinel 回收补申请、拒绝回退、freeze/pageshow 暂停、计时迟到暂停与失败媒体 load() 重试。
• 真实浏览器（Windows 10.0.26300 x64，Playwright 1.60.0，有头 Chromium 1280×720，本地静态服务 127.0.0.1:7416，构建任务 13）：A1 入场持有屏幕锁；A2 媒体页视频实际播放；A3 暂停释放锁；A4 继续重新持有；A5 隐藏暂停、6s 内不翻页且锁释放；A6 重新可见保持暂停；A7 显式继续；A8 注入 freeze 后暂停、8s 内不翻页，A8b 持久化 pageshow 保持暂停；A9 继续；A10 关闭缓存并停止本地服务后媒体请求 net::ERR_CONNECTION_REFUSED，进入错误态且 2s 内不跳页；A11 重启服务后点击重试恢复媒体播放；A12 浏览器重载从 #/intro 自动开始；A13 暂停后锁为 idle、媒体全部暂停，播放调度计时句柄清除（活动计时器 3→2，剩余为运行时/界面定时器），document/window 监听计数保持 14；A15 在权限拒绝上下文（NotAllowedError）中仍从开场自动推进到 /content 第 2/4 页。控制台仅有 A10 预期的连接拒绝错误。
• 代码版本：提交 20e7f0e（WP32）。证据：.tmp/wp32/browser/evidence.json 与截图；WP31 无头浏览器亦记录 wakeLock=denied 时计时放映正常。
• 未运行：真实操作系统睡眠/唤醒（CDP setWebLifecycleState('frozen') 不触发页面 freeze，改用事件级模拟加计时迟到单测，不能等同真实睡眠）；Firefox/WebKit、移动端行内播放、真实远端无人值守与构建访问票据/代理不在本包范围。证据账号、工作空间、项目、构建产物对象与 .tmp 凭证已清理（.tmp/wp31/cleanup.json，DB 剩余 0）。