byte271/mirrorframe

# Mirrorframe **本项目被封装为一个 Claude Skill** — AI agent 应从 [`SKILL.md`](SKILL.md)（工作流指令 + 断言式触发器描述）以及 [`references/`](references/) 中更深入的文档开始阅读。本 README 是面向人类读者的概述。 捕获实时页面，提炼出 **Design Genome**，还原其 **交互状态机**，将其重构为 React 应用，并通过视觉 diff 按 **节点和交互状态** 对结果进行验证 — 完全基于当今已有的技术（Playwright, WAAPI, MutationObserver, esbuild, pixelmatch）构建。全确定性的，循环中没有 LLM 参与：所有输出均可审查且可复现。 ## 快速开始（纯净克隆） 需要 Node.js ≥ 18。不假设任何其他机器状态。 ``` git clone && cd mirrorframe npm install # also installs the Playwright Chromium binary (postinstall) npm run verify # full pipeline on all 4 fixtures + results table (exit 1 on any failure) # 单一 fixture / 你的自有页面 node scripts/mirrorframe.js run --dir ./fixtures/tabs --out ./mf-out/tabs node scripts/mirrorframe.js run --url https://your-site.example --out ./mf-out/yours # options: --width 1280 --height 800（capture viewport） ``` 在 `/recon-app/index.html` 打开重构结果 — 这是一个自包含的 React 应用 （`app.jsx`, `styles.css`, `bundle.js`）。 ## v0.1 支持的处理范围（已实现，由 `npm run verify` 验证） - 静态页面：flexbox 布局，类型 / 颜色 / 间距 / 圆角 / 阴影 token 聚类 - CSS `@keyframes` 动画（通过 WAAPI `getAnimations()`），CSS 过渡，`:hover` 状态（从同源 stylesheets 中原样恢复） - **滚动显示**：IntersectionObserver 的 `hidden → visible` 类状态机通过 MutationObserver 滚动探针检测；触发器和可见类名均*从页面中恢复*，绝非假设 - **点击驱动的状态机**（广义行为图谱）：交互探针会对候选交互元素模拟点击，对比 class 及 computed-style 状态差异，测试可逆性，并对结果进行分类 — 没有任何内容是按组件硬编码的： - `toggle`（切换） — 第二次点击反转第一次（手风琴 / 展开折叠） - `exclusive`（互斥） — 一个 class 在同级组之间移动（tabs / 分段控件） - `pair`（配对） — 一个触发器添加 class，另一个移除（modal 打开 / 关闭），包括仅在打开状态*内部*可触达的触发器（modal 的关闭按钮） - **逐节点验证**：每个被追踪的节点都有各自的相似度得分和状态（`pass` / `style-verified` / `corrected` / `failed` / `animated-unstable` / `hidden-at-capture`）。折叠 / 全页面聚合格式会报告在逐节点表格**旁边**，绝不会将其替代。 - **残余自动修正**：会从重构结果中重新读取失败节点的 computed styles，与捕获数据进行对比，使用逐节点的 override 规则进行修补，并精确重新验证一次（成功则为 `corrected`，否则为附带原因的 `failed`）。 - **行为验证**：每个还原的交互状态都会在重构结果中使用*真实点击*进行重放，并与原始页面在该状态下的真实截图进行像素级差异对比。 ## 验证结果（全部 4 个测试用例，纯净运行） 图例：P 通过 · SV 样式验证通过（像素残留，所有被追踪的 computed styles 匹配 — 微小节点上的子像素字体抗锯齿） · C 已修正 · F 失败 · A 动画不稳定（无限动画，依赖相位的像素） · H 捕获时隐藏（通过状态重放验证）。 | 测试用例 | 模式 | 逐节点 | 状态 | 折叠 | 全页面 | |---|---|---|---|---|---| | northlight | 滚动显示 + 关键帧 + 悬停 | 25P / 1A | — | 99.99% | 99.81% | | accordion | toggle | 11P / 3SV / 2H | 6/6 pass | 99.99% | 99.99% | | tabs | exclusive | 12P / 8H | 2/2 pass | 100.00% | 100.00% | | modal | pair | 5P / 5H | 2/2 pass | 100.00% | 100.00% | 运行 `npm run verify` 进行复现（由于字体光栅化，精确的相似度数值在不同平台上可能在小数点最后几位有所波动；但状态不应改变）。 ## 已知局限性（谨慎设定的范围 — 参见 references/limitations.md 和 references/roadmap.md） - 不支持 Canvas / WebGL / WebGPU / shader / 后处理重构 - 不支持物理、惯性或弹簧恢复 - 行为图谱仅涵盖由点击和滚动驱动的 **类切换** 状态机 — 不支持拖拽、JS驱动的悬停、键盘交互、内联样式变异，或 DOM 插入/移除状态机 - 单一输出目标：React + 原生 CSS - 不支持图像、背景图像、网络字体文件、grid 布局、伪元素、响应式断点或跨域 stylesheets - 自动修正仅修补 computed-style 偏差；由未追踪属性导致的布局偏差会被报告为 `failed`，而不会被静默吸收 - 仅基于包含的四个测试用例（自主编写，无外部资源）进行了验证 — 明确声明不涵盖“任何网站” ## 产物（`--out` 目录） | 文件 | 含义 | |---|---| | `capture.json` | 证据包：节点树、computed styles、动画、过渡、hover 规则、显示变异、交互探针 | | `genome.json` | Design Genome：token、运动 DNA、交互 DNA（行为）、带标注的结构 | | `recon-app/` | 生成的 React 应用 (jsx + css + bundle + html) | | `original-*.png` / `state-*.png` | 真值截图（初始状态 + 每个交互状态） | | `recon-*.png` / `diff-*.png` | 重构截图 + pixelmatch 残留映射图 | | `convergence.json` | 逐节点表格、修正日志、状态重放结果、聚合数据 | | `summary.json` | 单屏定量摘要 | ## 项目结构 ``` SKILL.md skill entrypoint: trigger description + agent workflow scripts/mirrorframe.js CLI: capture → genome → reconstruct → converge scripts/verify-all.js release verification: all fixtures + results table scripts/lib/props.js shared tracked-property list + color normalization scripts/lib/capture.js capture substrate: DOM/style walk, motion + interaction probes scripts/lib/genome.js genome compiler: tokens, reveal recovery, behavior classification scripts/lib/reconstruct.js deterministic React + CSS codegen (state machines re-wired) scripts/lib/converge.js per-node + aggregate diff, auto-correction, state replay references/behavior-patterns.md recovered-pattern catalog (reveal/toggle/exclusive/pair) references/limitations.md hard scope limits + expected non-pass statuses references/roadmap.md v0.2–v0.4 planning, feasible-now vs research-level fixtures/ 4 self-authored test pages (northlight, accordion, tabs, modal) ``` ## 许可授权 MIT（参见 `LICENSE`） — 选择它是为了最大限度的宽松，并在将该 pipeline 嵌入其他工具时实现零摩擦。兼容性审计： - **测试用例/资源**：所有四个测试用例均专为本仓库编写；仅使用系统字体堆栈；无外部图像、字体、图标或第三方代码片段。无需替换任何内容。 - **运行时依赖**：playwright (Apache-2.0), esbuild (MIT), pixelmatch (ISC), pngjs (MIT), react / react-dom (MIT)。均为宽松许可；与 MIT 无冲突。 ## 诚挚的工程说明 - 恢复的是约束，而非像素：固定的 `width`/`height` 永远不会被固化（无论是在基础规则、行为状态规则，还是修正补丁中） — 允许粗体文本撑宽 tab。 - 恢复的是状态机，而非帧：状态类（`open`、`active`、`shown`、`visible` — 均为观察到的，而非假设的）被排除在样式规则标识之外，并且关闭/打开的样式会作为明确的还原状态规则输出。 - 本 README 中的每一项声明都对应于 `npm run verify` 中的一个检查项；任何失败或无法观察到的内容都会在 `convergence.json` 中按节点报告，而不是被平均值掩盖。

标签：MITM代理, Playwright, React, Syscalls, UI组件提取, 云资产清单, 像素验证, 特征检测, 自定义脚本, 逆向工程