# 矩阵光门与窗口恢复播放

本次开发记录：2026-10-13。以下把实现、离线验证与待实机验证的项目分开记录；不覆盖 DESIGN.md 中早期版本的历史实测结论。

## 视觉与时序

默认保留无标题、无提示的绿色数字雨。宿主就绪且收到进入交互后，在窗口中央出现高约窗口 70%、初始宽约 2 px 的细长矩形。前约 135 ms 点亮边框，随后左右对称展开，同时增加高度，最终超出窗口边界。总转场约 750 ms。

门框为浅绿细线、局部绿光和两列代码字符。门内直接露出已挂载的 Harness 界面，门外数字雨继续流动。使用原有 Canvas2D 雨场与 CSS clip-path 裁出透明矩形；没有视频、3D 引擎、全屏模糊或额外网络素材。没有修改或缩放宿主界面。

交互模式仍有默认 900 ms 的最短展示时间，鼠标移动还保留 350 ms 防误触与累计 14 px 的意图阈值。3 秒自动模式在达到展示时间且宿主就绪后开启光门。转场期间遮罩继续接管鼠标，进入按键在捕获阶段被消费，避免底层输入框误输入或提交。

`prefers-reduced-motion` 下跳过光门，使用原有淡出；未就绪的提前交互、宿主错误及就绪看门狗也保留原有逃生路径。光门额外设置 1000 ms 清理后备计时器；结束时销毁雨场、动画帧、临时 DOM 和输入监听，恢复标题栏颜色。

## 设置与生命周期

| 设置 | 值 | 默认 |
| --- | --- | --- |
| playback | startup / every-open | startup |
| transition | portal / fade | portal |

持久化仍使用插件自己的 `/codefall/api` 与 `$DSH_HOME/codefall.json`，旧配置缺少新字段时使用默认值。界面保存后将完整响应同步到文档会话，不再依赖桌面壳启动时缓存的配置。雨场参数由既有实时配置路径更新，下一次播放使用最新参数。

`Codefall.install()` 建立一份文档级会话；一次动画退出后只留下一个轻量的可见性监听，不留下动画帧或轮询。客户端 `shell.overlay` 首挂载通知会话已就绪。仅在 `dsh-app:` 桌面文档中，检测到隐藏后恢复可见、应用已就绪且选择 every-open 时才创建新动画。没有使用 focus 事件；Web 标签切换不会触发桌面重播。

隐藏中的旧动画被清理，恢复时重新建立雨场与输入防误触计时。重复可见事件不会堆叠遮罩。插件卸载同时销毁会话监听与当前动画；渲染器创建失败时遮罩尚未插入文档，避免恢复窗口时留下无法操作的空遮罩。

“仅应用启动时”对应应用文档初始化时播放：留在后台恢复不播放，完全退出重启或页面重新加载会播放。它不是安装后只播放一次，也不是按自然日记忆第一次启动。

## 已验证与依据

- 宿主与客户端离线测试覆盖配置读写、默认迁移、光门几何、最短展示时间、按键拦截、弱动画、错误中断、清理后备计时器，以及桌面隐藏恢复、重复事件、即时切换设置、Web 不重播和卸载清理。
- 原有 Canvas2D 像素烟雾测试保持通过：首帧、预播雨场、明暗切换、画质与参数更新、销毁行为。
- 浏览器预览检查：中央窄矩形内能看到宿主占位界面，两边仍有绿色数字雨；展开后完整移除遮罩。该预览不是实际 Harness 窗口。
- 已缓存的官方桌面源码使用 `window.hide()` 处理关闭到后台，窗口地址为 `dsh-app://app/`。Electron 的 [Page Visibility 行为说明](https://www.electronjs.org/docs/latest/api/browser-window#page-visibility) 表明 Windows/Linux 的 hide/minimize 会产生隐藏状态；macOS 还会把完全遮挡作为隐藏状态。

## 实机验收

1. 加载本地修改的插件版本，完整退出并重启 Harness，确认设置出现“播放时机”和“退出转场”。仅安装公开 npm 旧版本不会包含本次代码。
2. 默认设置下，交互后看光门从中央向两侧展开，进入现有界面；按 Enter 进入时不应发送输入框里已有的消息。
3. 选择“每次打开窗口”，关闭到后台后从托盘恢复、最小化后恢复，应各播放一次；普通 Alt+Tab 返回不应重播。
4. 动画过程中隐藏再恢复，确认只有一个新动画且没有残留门框或失效点击区。
5. 切回“仅应用启动时”，上述窗口恢复不播放；完全退出再启动仍播放。切回“淡出”，退出应恢复原有效果。
6. 系统减少动态效果与宿主加载失败时，确认快速退出且界面可操作。

本次未修改用户 Harness profile，也未发布 npm 包或 GitHub Release。Windows 的真实托盘恢复与其他平台行为仍待上述实机验收。