cursor-reveal-hero

Cursor Reveal Hero

使用此技能创建或修复柔和的光标轨迹显现效果：基础图像始终可见，显现图像则仅在逐渐淡出的遮罩范围内显示。

核心公式：

final = baseImage + revealImage * softCursorTrailMask

模式

• build：在现有应用或原生模板中从头创建此效果。
• repair：诊断图像加载、遮罩合成、指针处理、滑块、淡出、调整大小或缓存行为异常的问题。
• tune：调整半径、羽化、淡出、强度、不透明度和动量，以达到预期效果。
• validate：运行浏览器／画布检查并查看屏幕截图。

工作流

1. 如果用户不确定两层图像是否匹配，请先使用 $image-layer-alignment-validator。
2. 确定项目所用技术栈。优先沿用现有框架和资源管线。
3. 对于原生实现，请复制 assets/vanilla-template/ 并替换图像路径。
4. 让页面专注于实际的显现区域。除非用户要求，否则不要添加营销文案、主视觉文本或无关内容。
5. 按照 references/canvas-compositing.md 实现画布架构。
6. 添加用于调整参数的直接控件：半径、羽化、淡出、强度、不透明度和动量。
7. 在开发构建中视需要公开 window.revealSettings 和清除遮罩的函数。
8. 当有可用的浏览器目标时，针对本地 URL 运行 scripts/smoke-check-reveal.mjs。
9. 报告具体修改的文件、当前参数值和验证结果。

实现规则

• 使用一个可见画布，并使用离屏画布绘制遮罩层和显现层。
• 按设备像素比进行渲染，同时保持 CSS 尺寸稳定。
• 使用指针事件，并处理鼠标、触摸和触控笔输入。
• 使用柔和的径向渐变，而不是边缘生硬的悬停圆圈。
• 使用 destination-out 淡化旧的遮罩内容。
• 使用 destination-in 将遮罩应用于显现层。
• 每帧都先绘制基础层，再绘制经过遮罩处理的显现层。
• 控件值发生变化时，清除累积的遮罩，避免旧轨迹干扰参数调整。
• 静态文件被缓存时，更新缓存破坏查询字符串或强制刷新。

常见修复目标

• 滑块移动，但设置没有变化：绑定 input 和 change 事件，更新 textContent，并在设置更新后清除遮罩。
• 显现效果像边缘生硬的放大镜：增大羽化和半径，并让淡出更平滑；如果显现层过于突出，则降低不透明度。
• 轨迹始终不消失：提高淡出速度，或确认遮罩画布上应用了 destination-out。
• 显现图像始终可见：检查 globalCompositeOperation、遮罩重置和显现画布清除顺序。
• 画布模糊：修复 DPR 缩放和调整大小处理。
• 调整大小后效果异常：重建所有画布的底层存储并重新绘制。

安全与隐私

• 除非用户明确要求外部生成、托管或分析，否则请将图像资源保留在本地。
• 调整效果时不要覆盖原始基础图像或显现图像资源。
• 除非项目已使用这些依赖且用户希望采用，否则不要为此效果添加分析、远程跟踪或第三方运行时依赖。
• 验证浏览器时，优先使用本地 URL 和文件 URL。除非用户明确指定目标，否则不要自动化访问经过身份验证的页面或私有生产页面。

验证与评估

• 有可用 URL 时，使用 scripts/smoke-check-reveal.mjs。
• 自动检查后查看屏幕截图或实时页面；冒烟测试通过并不能证明视觉效果良好。
• 如果修改了控件，请手动验证滑块行为。
• 调整视口大小以及更改缓存破坏参数后，都要重新测试。

资源

• 在实现或修复核心渲染循环前，请阅读 references/canvas-compositing.md。
• 在调整操作手感或排查控制问题时，请阅读 references/tuning-and-failure-modes.md。
• 在进行最终视觉检查前，请阅读 references/browser-validation.md。
• 复制 assets/vanilla-template/，用作独立的 HTML/CSS/JS 起始模板。
• 本地 URL 可用时，运行 scripts/smoke-check-reveal.mjs 获取浏览器证据。