with-canvas
Canvas 工作失败有两种方式：一种视觉代码美观但低效；另一种优化代码难以维护或缺乏可访问性。在编写绘制调用之前，应将每个任务视为一次渲染架构决策。仅加载当前阶段引用的参考文档，不要预加载所有参考。
阶段 1 - 分类 Canvas 任务
在选择 API 之前，确定主导工作负载：
- 拒绝 canvas： 当场景主要是文本、无障碍控件、文档布局、简单图标、CSS 动画、媒体播放或少量可缩放矢量形状时，优先使用 DOM/CSS/SVG/视频。
- 装饰性动画： 非交互式氛围、背景粒子、星星、鸟类、程序化循环。
- 数据渲染： 图表、地图、热力图、大量点云、频繁更新的测量数据。
- 生成艺术： 种子/随机绘制、创意草图、程序化系统、可导出图像。
- 交互工具： 指针/键盘输入、选择、拖放、可编辑对象、命中测试。
- 游戏/模拟： 固定更新循环、动态实体、碰撞/物理、分层场景。
- WebGL/引擎 canvas： Three.js/Babylon.js/其他拥有 GPU 资源的渲染器。
必须阅读： 如果工作负载是装饰性动画或生成艺术，请阅读 references/visual-quality.md —— 对于这两类任务，美观才是目标，仅靠性能和无障碍规范无法产出通用输出。对于数据渲染、工具、游戏或引擎 canvas，不要加载它。
退出条件：说明工作负载、选择 canvas 的理由、目标帧率、预期对象数量、交互模型，以及 canvas 是装饰性的还是语义上有意义的。
阶段 2 - 选择渲染模型
当场景主要是即时模式绘制、像素处理、精灵、简单动画或对包大小敏感时，使用原始 Canvas 2D。
当应用需要可编辑对象、选择、拖放、分层场景图、事件委托或序列化时，使用保留模式库。
对于草图、生成艺术、教学/原型设计或创意编程，且 setup/draw 的便利性比框架集成更重要时，使用 p5.js。
对于矢量编辑工作流：路径、线段、贝塞尔几何、命中测试、SVG 导入/导出、分层矢量文档，使用 Paper.js。
对于 canvas 上的应用 UI：React/Vue/Svelte 集成、可拖放形状、图层、缓存形状、事件监听控件，使用 Konva。
当 Pencil.js 的组件模型适用且其依赖项的新鲜度对项目可接受时，使用 Pencil.js 进行轻量级场景/组件抽象。
当主导成本是 3D/GPU 渲染、着色器、相机、材质或大量网格/精灵工作时，使用 Three.js/Babylon.js 或直接 WebGL。
必须阅读： 如果选择库或评估库的选择，请阅读 references/library-selection.md。除非任务进入那些阶段，否则不要加载性能或审查参考。
在安装 canvas 库或编写非平凡的库 API 代码之前，如果有 Context7，请用其验证当前文档；否则使用官方文档。对于 p5.js、Paper.js、Pencil.js、Konva、ZIM、Three.js 或 Babylon.js 的 API，不要依赖记忆。
退出条件：命名所选模型和被拒绝的备选方案，并各附一行理由。
阶段 3 - 设计循环和状态
将 canvas 代码分离为生命周期、状态更新、渲染、输入、大小调整和拆卸。对于框架组件，将命令式 canvas 引擎保持在一个挂载/初始化边界内。
对于可见动画，使用 requestAnimationFrame。当模拟速度需要在不同刷新率下保持稳定时，从 RAF 时间戳跟踪 delta。在拆卸时取消 RAF，在隐藏时暂停或减少工作，并尊重 prefers-reduced-motion。
选择以下重绘策略之一：
- 完全重绘：适用于简单/装饰性场景，且简单性优先时。
- 脏矩形：移动对象具有小范围的有界变化和稳定的背景。
- 分层 Canvas：静态/缓慢背景、动态实体、UI/交互覆盖层。
- 精灵/缓存 blit：重复的昂贵形状、文字、标记、缩放图像、粒子。
- Worker OffscreenCanvas：与输入/主线程竞争的重绘制或模拟。
必须阅读： 在优化动画、大型场景、粒子、图表、图像缩放、高 DPI 输出或 worker 渲染之前，请阅读 references/performance.md。除非添加/替换库，否则不要加载 library-selection。
退出条件：按顺序编写帧管线：输入采样 -> 更新 -> 清除/重绘策略 -> 绘制 -> 调度下一帧。
阶段 4 - 实现 Canvas 规范
根据后备存储（而非仅 CSS）设置 canvas 大小。为了获得清晰输出，分别设置 CSS 大小，将 canvas.width/height 设为 cssSize * devicePixelRatio，然后使用 ctx.setTransform(dpr, 0, 0, dpr, 0, 0) 标准化变换。对于性能密集场景，可有意降低 DPR。
使用与场景匹配的选项初始化上下文。对于不透明 canvas，使用 { alpha: false }。仅当频繁读取 getImageData 时才使用 willReadFrequently: true，因为它可能更改后备策略。
对于输入，通过 getBoundingClientRect() 和 canvas 缩放来转换指针坐标。不要相信 clientX/clientY 就是 canvas 坐标。
对于可访问性，装饰性 canvas 设置 aria-hidden="true" 且没有交互处理程序。有意义的 canvas 交互需要 DOM 控件、键盘路径、焦点管理、标签或等效的非 canvas 表示。
退出条件：大小调整、DPR、上下文选项、事件坐标映射、运动偏好和拆卸均已明确处理。
阶段 5 - 审查和验证
将 canvas 代码视为热循环加资源生命周期进行审查。不要仅停留在视觉正确性上。
必须阅读： 在审查现有 canvas 代码或最终确定新实现之前，请阅读 references/review-checklist.md。除非审查包含依赖项适用性，否则不要加载 library-selection。
使用至少一个适合任务的运行时信号进行验证：Chrome Performance 面板、FPS 计数器、内存快照、交互延迟、减少运动路径、隐藏标签页行为或低端/移动端节流。
示例
- 用户要求“制作粒子背景”：归类为装饰性动画，仅在粒子数或程序化绘制证明 canvas 合理时才拒绝 DOM/SVG，然后读取
references/visual-quality.md了解外观，读取references/performance.md了解循环。 - 用户要求“构建带选择的可拖放形状”：归类为交互工具，读取
references/library-selection.md，根据对象模型可能选择 Konva/Paper.js/原始 Canvas 2D。 - 用户要求“审查这个 canvas 循环”：对现有工作负载进行分类，读取
references/review-checklist.md，仅当出现卡顿、高对象数或热点路径时才读取references/performance.md。 - 用户要求“添加 p5 草图”：读取
references/library-selection.md，在编写 API 代码前验证当前 p5 文档，然后保持框架生命周期边界清晰。
绝对不要
-
绝对不要仅用 CSS 调整绘制 canvas 的大小 应该： 有意识地设置后备存储尺寸和 CSS 尺寸；在调整大小后应用一次 DPR 变换。 原因： CSS 缩放任意外观模糊，并隐藏后备存储不匹配，这在视网膜显示器上会更糟。
-
绝对不要启动 RAF 循环却没有拆卸路径 应该： 存储帧 ID，在卸载/释放时取消，并防止在可见性或媒体查询变化后重复启动。 原因： 孤儿循环持续绘制已分离的 canvas，造成内存/CPU 泄漏，快照常将其误归于浏览器内部。
-
绝对不要因为昂贵的静态内容在视觉上属于场景就每帧重绘它 应该： 将其缓存在离屏 canvas、图像位图、图层 canvas、Path2D 或库形状缓存中。 原因： canvas 是即时模式；未变化的视觉效果仍会消耗完整的绘制时间，除非明确缓存或分层。
-
绝对不要将 canvas 独有的交互作为唯一的无障碍控制方式 应该： 提供 DOM 控制/语义，或带有标签和焦点行为的键盘可操作保留对象模型。 原因： canvas 像素不会向辅助技术暴露角色、名称、状态或命中目标。
-
绝对不要仅仅因为性能差就将 canvas 工作迁移到 OffscreenCanvas 应该： 首先确定瓶颈是绘制调用、状态抖动、过度绘制、图像缩放、像素读取还是模拟；仅当主线程争用是问题时使用 worker。 原因： Worker 增加了传输、打包和 DOM 访问限制；它们不能修复糟糕的绘制架构。
-
绝对不要将保留模式库的性能规则视为可选 应该： 禁用惰性图层上的监听、缓存昂贵的形状、最小化图层数量、并通过库的生命周期销毁节点/阶段。 原因： 库添加了场景图和事件机制；忽略其开关可能比原始 canvas 更慢。