blur

技能：blur

纯 WebGL 组件 — 全屏 canvas，通过“缩放模糊”（径向模糊向中心汇聚）切换图片；可通过滚动、点击或方向键导航，模糊中心跟随鼠标。

WHAT

目的与上下文

• 目的： 在页面中添加全屏 WebGL canvas，通过缩放模糊效果切换图片（当前图片逐渐模糊并向中心汇聚，新图片逐渐变清晰），并支持滚动、点击和按键导航；模糊中心跟随鼠标。
• 触发条件（何时使用）：
  • Hero 区域或图片幻灯片需要比普通交叉淡化更高级的切换效果（缩放模糊过渡）。
  • 用户提到“图片模糊效果”“WebGL 模糊”或“缩放模糊风格的图库”。
• 非目标： 不要用于 UI 卡片／面板的静态模糊／磨砂玻璃效果（这类效果应使用普通 CSS backdrop-filter: blur()，或 docs-site-macos liquid-glass）——此技能用于图片之间的动态过渡，GPU 开销高得多。不要更改主题（这是 dark-mode-maker 的职责）。

心智模型

图片数组 → 每张图片 = PlaneBufferGeometry + shader ZoomBlurImage → progress/targetProgress lerp → uStrength 两层交错 → 逐帧渲染；输入（滚轮／点击／按键）改变 targetProgress；鼠标改变 uCenter。

输入与输出约定

	字段	必需？	含义
输入	图片列表	是	替换 assets/blur.js 中的 images 数组
输入	速度／缓动	否	调整 duration／easing；默认保留 asset 中的设置
输入	所在页面有全局 gsap	是	initScene() 调用 gsap.fromTo(...) 时不会导入该库
输出	已适配的 blur.html + blur.css + blur.js	是	全屏 canvas 可在目标页面运行
输出	验证证据	是	滚动前后的截图 + 无报错的控制台（通过 playwright-verify）

规则与能力

• RULE-01（MUST）：这是 GPU 开销很大的效果（shader 每帧都会在整个视口上运行）——不要在同一页面上同时使用多个实例；最终确认前要在低端设备／移动设备上测试（浏览器对同时存在的 WebGL context 数量有限制）。
• RULE-02（MUST）：使用 playwright-verify 进行验证——截取滚动前后的画面，并读取控制台（WebGL context 错误通常不会在 canvas 中明显呈现，也不会立即抛出可见的 JS error）。
• RULE-03（MUST）：用于生产环境前，先阅读“已知技术债务”部分——交付给客户或用于真实产品前，需将 CDN 的 useThree import vendoring 到项目中。
• 能力：读取技能 asset；在目标项目中写入 HTML／CSS／JS 文件；运行无头浏览器进行截图并读取控制台。

失败边界

• 所在页面缺少 <script> gsap → 图片加载完毕后 gsap.fromTo(...) 立即报错 → 受阻，直到添加该 script。
• CodePen／unpkg CDN 无法加载 → canvas 空白 → 失败；修复方法是 vendoring（见“技术债务”部分）。
• canvas 未渲染但没有 JS error → 在控制台／截图证明情况并非如此之前，一律视为失败（WebGL 错误可能不会显示）。
• 需求是卡片／面板的静态模糊 → 超出范围，改用 backdrop-filter／docs-site-macos。

HOW

主要工作流

步骤	类型	输入	操作	输出／退出条件	失败／后续
W01	判断	用户需求	确认这是动态图片切换，而不是 UI 静态模糊	继续／切换其他技能	静态模糊 → 停止，建议使用 backdrop-filter
W02	确定性	assets/blur.*	阅读 assets/blur.html + assets/blur.css + assets/blur.js	asset 内容	—
W03	效果	asset、用户的图片	适配：更改 images 数组，调整 duration／easing；确保页面有全局 gsap	目标项目中的文件	—
W04	判断	使用目标（原型／生产环境）	检查技术债务部分；用于生产环境时 → B01	vendoring 决策	—
W05	确定性	已集成的页面	使用 playwright-verify 验证：截取滚动前后的画面，读取控制台	截图 + 控制台日志	出错／canvas 空白 → 修复后重复 W05

分支

ID	类型	守卫条件	行为	跳过 / 失败	汇合点
B01	conditional_required	用于真实客户/产品	将 useThree pen 供应商化为 assets/ 中的 .js 文件，删除 CDN import（如果 pen 的 license 不明确，则自行重写）；如果有 bundler，则通过 npm 安装 three	原型 → 跳过	W05
B02	recovery	控制台提示 gsap is not defined	在承载页面中添加 <script src="gsap...">	—	W05

验证和停止条件

当滚动前后的截图不同（图片发生切换），且控制台没有 WebGL/JS 错误时，即视为完成。不要无限重复 W05：如果 2 轮后仍有错误 → 附上控制台日志告知 user。

示例

• 正向：“做一个 4 张图片的缩放模糊风格 hero 幻灯片” → 将 images 替换为 4 个 URL，页面已有 gsap → playwright 截取滚动前后的截图，看到图片从 1→2 切换，控制台无错误 → 交付。
• **边界/失败：**目标页面未加载 gsap → 图片加载时控制台立即报错 gsap is not defined → B02 添加 script，再次验证；user 想要“玻璃质感的模糊卡片” → W01 停止，建议使用 backdrop-filter: blur()。

参考 — 资源

assets/blur.html + assets/blur.css + assets/blur.js — 阅读后再适配（更改 images 数组，调整 duration/easing 速度）。

参考 — ⚠️ 已知技术债务 — 用于生产环境前请先阅读

assets/blur.js 第 12 行从他人的 CodePen pen（codepen.io/soju22/pen/...js）导入 helper useThree — 这是依赖我们不拥有的资源的 CDN，可能随时更改或移除，且不会提前通知。原始 snippet 是供参考的演示，尚未针对生产环境进行强化。

• ponytail：尚未供应商化的全局外部依赖，需要用于真实生产环境时再升级 — 用于真实客户/产品之前：(1) 阅读该 pen 的内容，将其供应商化为 assets/ 中独立的 .js 文件，并删除 CDN import；(2) 如果不清楚原始 pen 的 license，则自行重写 useThree（Three.js 场景/相机/渲染器样板代码）。
• import ... from 'https://unpkg.com/[email protected]/...'（第 1-10 行）也是运行时 CDN — 原型阶段可以接受，但项目有 bundler 时，应通过 npm 安装 three 并从本地 import，避免运行时依赖网络。
• initScene() 中使用了 gsap，但文件中并未 import — 假定该全局变量已存在（承载页面中有 <script src="gsap...">）。如果缺少该 <script>，图片加载完成后 gsap.fromTo(...) 会立即报错。

参考 — 机制

• 每张图片都是一个覆盖自定义 shader（ZoomBlurImage）的 PlaneBufferGeometry — fragment shader 沿着指向中心的向量对图片进行采样，并使用 Bezier 权重；当 uStrength 不为 0 时，会产生向中心汇聚的模糊效果。
• 图片切换：progress/targetProgress 逐渐进行 lerp（updateProgress），两层图片的 uStrength 交叉变化（退出的图片逐渐模糊，进入的图片逐渐清晰）。
• 输入：鼠标滚动（wheel）按 1/20 的步进更改 targetProgress；点击屏幕上半部分/下半部分 = 后退/前进；方向键效果相同。
• 模糊中心（uCenter）每帧根据鼠标位置进行 lerp → 产生“目光跟随光标”的效果。

来源

• 根据 user 2026-09-17 的要求，将 llmwiki/patterns/blur/ 中的内容压缩成真正的 skill（参考 snippet 尚未关联任何 skill，也从未纳入 git track）——与 timeline 同一批。