动态效果建模

本项目是一个本地优先的 Chrome 动态效果分析器：用户在网页上框选任意矩形区域、手动演示交互并自行决定何时结束；本地 Node.js 分析器生成 WebM 回放、选区视觉分析图、运动强度曲线、中文解读与技术取证。不需要 API key，也不会把录制内容发送到外部服务。

环境要求

• Node.js 20.19 或更高版本。
• pnpm 9 或更高版本（仓库当前 packageManager 声明为 pnpm 11）。
• Chrome 116 或更高版本。扩展的 Manifest 已声明 minimum_chrome_version: 116。

安装与构建

在本目录执行：

pnpm install
pnpm test
pnpm build:analyzer
pnpm build:extension

扩展构建完成后，Chrome 的“加载已解压的扩展程序”目录为：

apps/extension/dist

启动本地分析器

pnpm dev:analyzer

默认监听 http://127.0.0.1:8787，打开该地址可查看本地报告页。也可以用 PORT=8787 pnpm dev:analyzer 显式指定端口。

扩展与本地分析器统一使用 http://127.0.0.1:8787/api/runs。按现有代码进行扩展联调时，直接运行上一段的 pnpm dev:analyzer，并在 http://127.0.0.1:8787 查看报告页。

演示流程

1. 构建扩展，并在 chrome://extensions 开启开发者模式，选择“加载已解压的扩展程序”，目录指向 apps/extension/dist。

2. 用 HTTP 静态服务器提供演示页（不要直接以 file: 打开）：

   python3 -m http.server 5173 --directory demo

   然后打开 http://127.0.0.1:5173/transition-demo.html。

3. 启动分析器：运行 pnpm dev:analyzer，使用唯一的本地端点 http://127.0.0.1:8787。

4. 每次目标页面的分析前，在扩展 Popup 点击“准备深度调试并重载”。页面会重载一次；这是为了在页面脚本运行前安装只读观测器。重载完成后重新打开 Popup，看到“深度调试已就绪”才可开始。

5. 点击“开始深度示范”。回到页面后拖拽框选要分析的区域，按“确认选区”。

6. 右上角会出现“正在录制”浮窗。操作网页；需要结束时由你点击“结束并分析”。浮窗可拖动，其自身区域会在分析中标记为扩展 UI。

7. 报告页会自动轮询正在处理的任务；完成后检查视频、四张选区分析图、阶段时间线、运动强度曲线、中文解读、“深度调试快照”，以及“事实 / 推断 / 未知”三栏技术取证。

深度调试快照可直接读出浏览器公开的 CSS/WAAPI 动画时长、延迟、缓动和关键帧属性；当网站把 GSAP 暴露到 window.gsap 时也会记录公开 timeline。Three.js 的精确相机和语义化场景层级只有在你自己的站点显式提供 window.__MOTION_FORENSICS__.getCamera() / getScene() 调试桥时才会输出；未读到时报告会明确标为未知。

演示动效时间轴（以点击时刻附近的动画窗口为参照）如下：

• 0–900ms：旧场景整体存在。
• 900–1500ms：旧场景下沉。
• 1500–1900ms：空台座阶段。
• 1900–3000ms：新场景上升。

数据产物

每个任务保存在 data/runs/<run-id>/，包括：

capture.webm       原始 WebM 回放
manifest.json      页面、选区、点击时间标记、Canvas/运行时证据和分析窗口元数据
frames/            解码帧（本地运行时生成）
artifacts/         胶片条、洋葱皮、狭缝扫描、差分热力图等
report.json        状态、阶段、运动强度和中文解读

运行数据默认被 .gitignore 排除；仅保留 data/runs/.gitkeep 作为目录占位。

支持范围

支持普通 http:// 和 https:// 网页；只有用户明确点击 Popup 的“准备深度调试并重载”、随后“开始深度示范”、确认选区、并点击浮窗“结束并分析”后，才会生成本地报告。深度模式使用 Chrome DevTools Protocol 的页面预注入能力，但不会读取 Cookie、表单、请求体或账户数据。

不支持或会被拒绝的页面包括 Chrome 内置页（chrome://）、Chrome Web Store/受保护页面、file: 页面及非 HTTP(S) 地址。工具也不会自动探索页面、还原 Three.js/GSAP/CSS 源码参数，或输出真实对象级坐标、相机参数和不透明度曲线。

隐私边界

• 原始视频、截图、点击元数据和报告默认只写入本机 data/runs/。
• 项目不需要 API key，不调用外部 AI 服务，不上传网页内容。
• 只有用户主动点击“准备深度调试并重载”后，扩展才会附加当前标签页的调试会话；只有之后点击“开始深度示范”才请求标签页捕获权限。
• 为避免意外长期录制，确认选区后超过两分钟仍未手动结束时，扩展会自动停止。
• 报告是像素/帧差层面的分析；技术部分严格区分“事实”（可读到的 DOM / Canvas / 运行时证据）、“推断”（由多项指纹得出的低至高置信判断）和“未知”。不会声称读取了目标网站的原始源码。
• 当前“重新发送”只缓存 Service Worker 生命周期内的最近一次 WebM；Worker 被回收后需要重新示范。

已知限制

• WebM 解码依赖本地 ffmpeg-static；单个录制有明确的 64 MiB 上限，超限返回 HTTP 413。
• 分析窗口以第一条网页交互时间标记为参照，默认保留前 600ms；视频实际以你的手动结束时刻为止。
• 真实 tabCapture、MediaRecorder、用户手势和 Chrome 受保护页面行为必须在真实 Chrome 中手工验证。
• 某些站点把 GSAP 或 Three.js 实例封装在 ESM 私有作用域中；此时扩展不会猜造贝塞尔、相机或模型数据，而会在“深度调试快照”的限制栏明确说明。精确复刻需配合 source map、断点或你自己的调试桥。
• 报告抽样和视频压缩可能影响阶段边界；“像素级”结论不等同于对象轨迹。

排障

• 报告页打不开：确认分析器正在运行，并访问实际监听端口；查看终端是否打印 Analyzer listening at ...。
• 扩展显示分析器未启动/发送失败：确认 pnpm dev:analyzer 正在监听 127.0.0.1:8787；启动后可点击“重试”。
• Popup 按钮被禁用：切换到普通 HTTP(S) 网页，不能在 chrome://、商店页或 file: 页面录制。
• 提示先准备深度调试：点击“准备深度调试并重载”，等目标页加载完成后关闭再重新打开 Popup；若 DevTools 已附加同一标签，先关闭 DevTools 后重试。
• 没有新任务：确认已完成框选、在录制期间至少操作过一次网页、并点击了浮窗“结束并分析”；再检查 data/runs/ 与 GET /api/runs。
• 报告处理失败：保留对应 run 目录中的 capture.webm 和 report.json，检查 ffmpeg/终端错误后重试；不要把网页录制上传到外部服务。

真实 Chrome 手工验收是否完成，请以 tests/e2e/manual-checklist.md 和 Task 7 报告为准；本文不将构建或单元测试写成 Chrome 实测结果。