Editable-Design 用 Coding Agent 生成可编辑海报交付物：真实文本、独立图层，外加一个随海报附带的鼠标编辑器editor.html。而每一次“拖一下、像素级对齐”的顺滑体验背后，编辑器运行时都踩过一批真实陷阱——固化阶段版面乱跳、双击文本编辑失灵、中文输入被中途踢出、自动验收误报……本文整理自官方陷阱清单 editor-pitfalls.md，按三个阶段讲清 16 个最典型的陷阱与修复方案，开发时遇到偏差不为 0 或功能异常，可直接对照排查。

🧱 先看懂：海报图层编辑器能做什么

Editable-Design 的默认交付物中，editor.html由固定画布的index.html一键接入生成：可以拖拽图层、八手柄缩放宽高、双击编辑文字、切换字号与字体族，还能把海报扫描、炸开成「拆解视图」逐层检视。运行时就是 layer-editor.js 与 layer-editor.css 两个文件，官方定位很明确：它是微调工具，不是设计工具。

陷阱清单同样按三个阶段组织：固化阶段（把稿子固化成可独立编辑的绝对定位布局）、交互阶段（鼠标键盘操作）、测试与环境阶段（headless Chrome 自动验收）。以下共 16 条。

🔩 固化阶段陷阱：版面乱跳的 7 大原因

固化的目标是「零偏差验收」——原稿与固化稿叠放完全重合。绝大多数乱跳问题都出在下面这几条：

1. 边量边改，元素逐个上跳（T1）

测量完前一个图层就写入坐标，会改变版面，导致后续要量的元素位置已变。修复：严格两趟——先全量测量并缓存，再统一写入。

2. 图层抽走，容器塌陷（T2）

抽离图层后容器高度塌陷，容器内未被抽走的元素（如分隔线）跟着整体跑位；用bottom定位的容器危害最大。修复：测量阶段一并记录所有「含图层的祖先容器」，抽离前把width/height钉死。

3. margin 残留造成二次偏移（T3）

文档流元素原本靠margin-top排版，转 absolute 后 margin 仍然生效，元素在新坐标基础上又偏移一次。修复：写入时统一margin: 0。

4. 一刀清空 transform，旋转装饰被抹平（T4）

统一清空transform能解决translateX(-50%)的重复偏移，却会抹掉邮戳、回形针、手写贴纸等设计旋转。修复：分别保存未变换布局尺寸、computedtransform矩阵与transform-origin，提升后重施矩阵，再用可见包围盒差值反算left/top。

5. 元素宽度塌缩（T7）

文档流元素的宽度由父容器给定，转 absolute 后塌成fit-content，文字重新换行。修复：把测得的width原样写入。

6. 字体未加载完就测量（T8）

量到的是 fallback 字体的坐标，落盘后整个版面偏移。修复：固化前await document.fonts.ready。

7. 图片没加载完就测量，坏图卡死编辑器（T9）

未加载图片高度为 0；但加载失败也必须放行，否则一张坏图卡死整个编辑器。修复：等待所有img的load与error。

🖱️ 交互阶段陷阱：双击编辑与中文输入为什么失灵

海报变成「画布 + 浮动 UI」后，浏览器事件模型带来 6 个经典坑：

8. pointerdown 里 preventDefault 会杀死 dblclick（T12）

按 Pointer Events 规范，在pointerdown阻止默认行为会连带抑制后续click/dblclick。表现为双击进入文本编辑完全无效。修复：不在pointerdown阻止默认行为；防止拖拽误选文字，改为「移动超过阈值后再设user-select: none」。

9. 指针捕获让双击命中了错误的图层（T13）

setPointerCapture会把后续click/dblclick的target重定向到捕获元素，双击图层内部小文本槽时e.target变成整个图层，找不到文本槽。若图层自身恰好就是文本槽则「碰巧能用」，极具误导性。修复：① 指针捕获推迟到确认拖拽之后；②dblclick不信任e.target，改用document.elementFromPoint()重新命中。

10. 画布缩放后拖拽不跟手（T14）

画布整体scale后，屏幕位移与画布位移不相等，不换算则拖拽明显滞后。修复：dx = (e.clientX - startX) / scale。

11. Esc 和 Enter 被中文输入法劫持（T16）

组字期间 Esc 是「取消候选词」、Enter 是「上屏」，不区分则用户打字打到一半就被踢出编辑态。修复：按键处理第一行即if (e.isComposing || e.keyCode === 229) return;。

12. 整层可编辑，多字号拼排一退格就崩（T17）

文本编辑粒度若取整个图层，像价格由.cup/.num/.yuan三个不同字号字色的 span 拼成的结构，整块contenteditable时一个退格即崩。修复：编辑单元下沉到「文本槽」——图层内部只承载文字的叶子节点；图文混排节点整体算一个槽；SVG 子树排除。

13. 粘贴把 HTML 污染进海报（T18）

从外部粘贴带格式内容会把脏 HTML 带进海报。修复：contenteditable="plaintext-only"，只粘贴纯文本。

🧪 测试验收陷阱：3 个最容易的误报

headless Chrome 自动验收有一套「看起来像 bug、其实不是」的问题：

14. Puppeteer 的 clickCount: 2 不会产生 dblclick（T20）

它只设置参数、不真的按两次，detail恒为 1，浏览器不合成双击——会误判成功能 bug。修复：手动发两轮 down/up，第二轮传clickCount: 2，此时detail=2、dblclick正常派发。

15. 用户已打开的 Chrome 干扰 headless 启动（T21）

报错Timed out waiting for the WS endpoint URL，通常是连到了用户已开着的实例。修复：每次使用全新的临时--user-data-dir（顺带保证 localStorage 干净，草稿不干扰固化）。

16. 只比较坐标，把「零偏差」判成假阳性（T31）

只比较getBoundingClientRect()，会把「坐标没变、但底色/伪元素/图片/层级已丢」的稿件误判为零偏差。修复：验收双轨制——几何比较负责定位，原稿与固化稿的像素比较负责视觉真值。

🚑 偏差不为 0 时：三步诊断流程

当 bake.mjs 报出偏差，按可能性排序依次检查：

1. 契约未满足——先跑 check-contract.mjs，十有八九是vw/vh/%之类视口单位或字体没等到；
2. 未覆盖的布局——float、position: sticky、伪元素撑开高度、writing-mode、CSScolumns、subgrid，上面的 T1–T11 不覆盖这些；
3. 图层间重叠依赖——一个图层的位置由另一个图层的内容高度决定。

定位技巧：看bake.mjs逐图层列出的原始与固化后坐标，关注哪些图层偏了、偏移量是否相同。同一容器内的图层偏移量一致，通常是 T2 容器塌陷；单个图层偏移恰好等于某个 margin 值，是 T3；旋转饰物的包围盒与角度不一致，是 T4。

✅ 收尾：照清单查，不要重写外壳

以上 16 条陷阱全部已在编辑器外壳内处理完毕。官方的建议（见 editor-runtime.md）只有两句话：遇到偏差不为 0 或功能异常，先查陷阱清单，不要重写外壳；也不要为某一张海报单独给编辑器打补丁。

新海报照 SKILL.md 的流程接入即可：wire-editor.mjs生成editor.html，再跑 verify.mjs 一次浏览器运行完成「几何 + 像素」零偏差验收。真正理解这 16 个陷阱的价值在于：下次需要改动运行时逻辑时，你能立刻意识到自己是在和哪条浏览器规范行为博弈——排障速度会完全不一样。