blur

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: blur

Component WebGL thuần — canvas full-screen, chuyển giữa các ảnh bằng "zoom blur" (radial blur hội tụ về tâm), scroll/click/phím mũi tên để điều hướng, tâm blur bám theo chuột.

纯 WebGL 组件——全屏 canvas，使用“zoom blur”（向中心汇聚的 radial blur）在图片间切换；通过 scroll/click/方向键导航，blur 中心跟随鼠标。

WHAT

内容概览（WHAT）

Purpose và context

目的与上下文

Purpose: gắn vào trang một canvas WebGL full-screen chuyển giữa các ảnh bằng hiệu ứng zoom-blur (ảnh ra mờ dần hội tụ về tâm, ảnh vào rõ dần), điều hướng bằng scroll/click/phím, tâm blur bám chuột.
Trigger (when to use):
- Hero section hoặc slideshow ảnh cần hiệu ứng chuyển CAO CẤP hơn crossfade thường (zoom-blur transition).
- User nói "hiệu ứng blur ảnh", "webgl blur", "gallery kiểu zoom blur".
Non-goals: KHÔNG dùng cho blur/frosted-glass TĨNH của UI card/panel (đó là
```
backdrop-filter: blur()
```
CSS thường, hoặc
```
docs-site-macos
```
liquid-glass) — đây là hiệu ứng CHUYỂN ĐỘNG giữa các ảnh, tốn GPU hơn hẳn. Không đổi theme (việc của
```
dark-mode-maker
```
).

**目的：**在页面中挂载一个全屏 WebGL canvas，通过 zoom-blur 效果切换图片（旧图逐渐模糊并向中心汇聚，新图逐渐清晰），支持 scroll/click/按键导航，blur 中心跟随鼠标。
触发条件（何时使用）：
- Hero section 或图片 slideshow 需要比普通 crossfade 更高级的切换效果（zoom-blur transition）。
- 用户说“图片 blur 效果”“webgl blur”“zoom blur 风格的 gallery”。
**非目标：**不用于 UI card/panel 的静态 blur/frosted-glass（那通常使用
```
backdrop-filter: blur()
```
CSS，或
```
docs-site-macos
```
liquid-glass）——这是图片之间的动态切换效果，GPU 开销明显更高。不切换 theme（这是
```
dark-mode-maker
```
的职责）。

Mental model

心智模型

mảng images → mỗi ảnh = PlaneBufferGeometry + shader ZoomBlurImage → progress/targetProgress lerp → uStrength 2 layer đan chéo → frame render; input (wheel/click/phím) đổi targetProgress; chuột đổi uCenter

images 数组 → 每张图片 = PlaneBufferGeometry + ZoomBlurImage shader → progress/targetProgress lerp → 两层交错的 uStrength → 逐帧渲染；输入（wheel/click/按键）改变 targetProgress；鼠标改变 uCenter

。

Input và output contract

输入与输出约定

	Field	Required?	Ý nghĩa
In	danh sách ảnh	có	thay mảng `images` trong `assets/blur.js`
In	tốc độ / easing	không	chỉnh `duration` /easing, mặc định giữ như asset
In	trang chứa có `gsap` global	có	`initScene()` gọi `gsap.fromTo(...)` mà không import
Out	`blur.html` + `blur.css` + `blur.js` đã adapt	có	canvas full-screen chạy được trong trang đích
Out	bằng chứng verify	có	ảnh chụp trước/sau khi cuộn + console sạch (qua `playwright-verify` )

	字段	是否必需	含义
In	图片列表	是	替换 `assets/blur.js` 中的 `images` 数组
In	速度/easing	否	调整 `duration` /easing，默认保持 asset 原样
In	宿主页面含全局 `gsap`	是	`initScene()` 会调用 `gsap.fromTo(...)` ，但文件自身不 import
Out	已适配的 `blur.html` + `blur.css` + `blur.js`	是	可在目标页面运行的全屏 canvas
Out	验证证据	是	scroll 前后截图 + console 无报错（通过 `playwright-verify` ）

Rules và capabilities

规则与能力

RULE-01 (MUST): Đây là hiệu ứng NẶNG GPU (shader chạy mỗi frame trên toàn viewport) — không dùng cho nhiều instance cùng lúc trên 1 trang, và test trên máy yếu/mobile trước khi chốt (WebGL context có giới hạn số lượng đồng thời của trình duyệt).
RULE-02 (MUST): Verify bằng
```
playwright-verify
```
— chụp trước/sau khi cuộn, đọc console (context WebGL lỗi thường im lặng ở canvas, không throw JS error thấy ngay).
RULE-03 (MUST): Đọc mục "Nợ kỹ thuật đã biết" TRƯỚC khi dùng production — vendor hoá import CDN
```
useThree
```
trước khi giao khách hàng/sản phẩm thật.
Capabilities: đọc asset của skill; ghi file HTML/CSS/JS vào dự án đích; chạy trình duyệt headless để chụp + đọc console.

RULE-01 (MUST)：这是 GPU 开销很高的效果（shader 每帧在整个 viewport 上运行）——不要在同一页面同时使用多个 instance，并应在最终确定前于低性能设备/mobile 上测试（浏览器对 WebGL context 可同时创建的数量有限）。
RULE-02 (MUST)：使用
```
playwright-verify
```
验证——截取 scroll 前后画面并读取 console（WebGL context 的错误通常会在 canvas 中静默发生，不会立即抛出可见的 JS error）。
RULE-03 (MUST)：在用于 production 前先阅读“已知技术债务”部分——交付给客户/真实产品前，需将 CDN
```
useThree
```
vendor 化。
能力：读取 skill 的 asset；将 HTML/CSS/JS 文件写入目标项目；运行 headless 浏览器进行截图并读取 console。

Failure boundaries

失败边界

Trang chứa thiếu
```
<script>
```
gsap →
```
gsap.fromTo(...)
```
ném lỗi ngay khi ảnh load xong → blocked tới khi thêm script.
CDN CodePen/unpkg không tải được → canvas trắng → failed; hướng sửa là vendor hoá (mục Nợ kỹ thuật).
Canvas không render nhưng không có JS error → coi là failed cho tới khi console/ảnh chụp chứng minh ngược lại (lỗi WebGL im lặng).
Yêu cầu là blur tĩnh cho card/panel → ngoài phạm vi, chuyển
```
backdrop-filter
```
/
```
docs-site-macos
```
.

宿主页面缺少
```
<script>
```
gsap →
```
gsap.fromTo(...)
```
会在图片加载完成后立即报错 → blocked，直到添加 script。
CodePen/unpkg CDN 无法加载 → canvas 变白 → failed；修复方式是 vendor 化（见“技术债务”部分）。
Canvas 未渲染但没有 JS error → 在 console/截图证明其正常之前，均视为 failed（WebGL 错误会静默发生）。
用户要求为 card/panel 添加静态 blur → 超出范围，应改用
```
backdrop-filter
```
/
```
docs-site-macos
```
。

HOW

工作方式（HOW）

Main workflow

主工作流

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	yêu cầu user	Xác nhận đây là chuyển ảnh động, không phải blur tĩnh UI	đi tiếp / chuyển skill khác	blur tĩnh → dừng, gợi ý `backdrop-filter`
W02	deterministic	`assets/blur.*`	Đọc `assets/blur.html` + `assets/blur.css` + `assets/blur.js`	nội dung asset	—
W03	effect	asset, ảnh của user	ADAPT: đổi mảng `images` , chỉnh `duration` /easing; đảm bảo trang có `gsap` global	file trong dự án đích	—
W04	judgment	đích dùng (prototype/production)	Rà mục Nợ kỹ thuật; production → B01	quyết định vendor hoá	—
W05	deterministic	trang đã gắn	Verify bằng `playwright-verify` : chụp trước/sau cuộn, đọc console	ảnh + log console	lỗi/canvas trắng → sửa rồi lặp W05

步骤	类型	输入	操作	输出/退出条件	失败/下一步
W01	判断	用户需求	确认这是动态图片切换，而非静态 UI blur	继续 / 切换到其他 skill	静态 blur → 停止，建议使用 `backdrop-filter`
W02	确定性	`assets/blur.*`	读取 `assets/blur.html` + `assets/blur.css` + `assets/blur.js`	asset 内容	—
W03	效果	asset、用户图片	ADAPT：替换 `images` 数组，调整 `duration` /easing；确保页面具有全局 `gsap`	目标项目中的文件	—
W04	判断	目标使用场景（prototype/production）	检查技术债务；production → B01	决定是否 vendor 化	—
W05	确定性	已挂载的页面	使用 `playwright-verify` 验证：截取 scroll 前后画面并读取 console	截图 + console 日志	报错/canvas 变白 → 修复后重新执行 W05

Branches

分支

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	conditional_required	dùng cho khách hàng/sản phẩm thật	vendor hoá pen `useThree` thành file `.js` trong `assets/` , xoá import CDN (tự viết lại nếu license pen không rõ); có bundler thì cài `three` qua npm	prototype → skip	W05
B02	recovery	console báo `gsap is not defined`	thêm `<script src="gsap...">` vào trang chứa	—	W05

ID	类型	条件	行为	跳过/失败	汇合点
B01	conditional_required	用于客户/真实产品	将 pen 中的 `useThree` vendor 化为 `assets/` 下独立的 `.js` 文件，移除 CDN import（若原 pen 的 license 不明确，则自行重写）；若项目有 bundler，则通过 npm 安装 `three`	prototype → 跳过	W05
B02	recovery	console 报错 `gsap is not defined`	在宿主页面添加 `<script src="gsap...">`	—	W05

Validation và stopping

验证与停止条件

Xong khi ảnh chụp trước/sau cuộn khác nhau (chuyển ảnh xảy ra) và console không có lỗi WebGL/JS. Không lặp W05 vô hạn: sau 2 vòng vẫn lỗi → báo user kèm log console.

完成条件：scroll 前后截图不同（说明图片切换已发生），且 console 中没有 WebGL/JS 错误。不要无限重复 W05：若两轮后仍然报错，则向用户报告并附上 console log。

Examples

示例

Positive: "làm hero slideshow 4 ảnh kiểu zoom blur" → thay
```
images
```
bằng 4 URL, trang đã có gsap → playwright chụp trước/sau cuộn thấy ảnh 1→ảnh 2, console sạch → giao.
Boundary/failure: trang đích không nạp gsap → console
```
gsap is not defined
```
ngay khi ảnh load → B02 thêm script, verify lại; user muốn "card mờ kiểu kính" → W01 dừng, gợi ý
```
backdrop-filter: blur()
```
.

正向示例：“制作一个包含 4 张图片、采用 zoom blur 效果的 hero slideshow” → 将
```
images
```
替换为 4 个 URL；页面已有 gsap → Playwright 截取 scroll 前后画面，可见图片 1→图片 2，且 console 无报错 → 交付。
**边界/失败：**目标页面未加载 gsap → 图片加载后 console 立即出现
```
gsap is not defined
```
→ B02 添加 script 后重新验证；用户想要“玻璃般模糊的 card” → W01 停止，并建议使用
```
backdrop-filter: blur()
```
。

Reference — Assets

参考——Assets

assets/blur.html

assets/blur.css

assets/blur.js

— đọc rồi ADAPT (đổi mảng

images

, chỉnh tốc độ

duration

/easing).

assets/blur.html

assets/blur.css

assets/blur.js

— 读取后进行 ADAPT（替换

images

数组，调整速度

duration

/easing）。

Reference — ⚠️ Nợ kỹ thuật đã biết — đọc TRƯỚC khi dùng production

参考——⚠️ 已知技术债务——在用于 production 前阅读

assets/blur.js

dòng 12 import helper

useThree

từ một CodePen pen của người khác (

codepen.io/soju22/pen/...js

) — đây là phụ thuộc CDN vào tài nguyên không do ta sở hữu, có thể đổi/gỡ bất cứ lúc nào không báo trước. Snippet gốc là demo tham khảo, chưa hardened cho production.

ponytail: global external dependency chưa vendor hoá, nâng cấp khi cần production thật — trước khi dùng cho khách hàng/sản phẩm thật: (1) đọc nội dung pen đó, vendor hoá thành file
```
.js
```
riêng trong
```
assets/
```
, xoá import CDN; (2) tự viết lại
```
useThree
```
(Three.js scene/camera/renderer boilerplate) nếu không rõ license của pen gốc.
```
import ... from 'https://unpkg.com/three@0.120.0/...'
```
(dòng 1-10) cũng là CDN runtime — chấp nhận được cho prototype, nhưng dự án có bundler nên cài
```
three
```
qua npm rồi import local, tránh phụ thuộc mạng lúc chạy.
```
gsap
```
dùng trong
```
initScene()
```
nhưng KHÔNG được import trong file — giả định biến global đã có sẵn (script
```
<script src="gsap...">
```
ở trang chứa nó). Thiếu
```
<script>
```
đó thì
```
gsap.fromTo(...)
```
ném lỗi ngay khi ảnh load xong.

assets/blur.js

第 12 行从一个他人的 CodePen pen（

codepen.io/soju22/pen/...js

）导入 helper

useThree

——这是对非自有资源的 CDN 依赖，可能随时被更改或下架，且不会提前通知。原始 snippet 是参考 demo，尚未针对 production 完成 hardening。

ponytail：全局外部依赖尚未 vendor 化，在真正用于 production 时需要升级——在用于客户/真实产品前：(1) 阅读该 pen 的内容，将其 vendor 化为
```
assets/
```
中独立的
```
.js
```
文件，并移除 CDN import；(2) 如果原 pen 的 license 不明确，则自行重写
```
useThree
```
（Three.js scene/camera/renderer boilerplate）。
```
import ... from 'https://unpkg.com/three@0.120.0/...'
```
（第 1–10 行）同样是 CDN runtime 依赖——prototype 可以接受，但若项目有 bundler，应通过 npm 安装
```
three
```
并从本地 import，从而避免运行时依赖网络。
```
gsap
```
在
```
initScene()
```
中使用，但文件中并未 import；实现假定全局变量已经存在（宿主页面通过
```
<script src="gsap...">
```
加载）。缺少该
```
<script>
```
时，
```
gsap.fromTo(...)
```
会在图片加载完成后立即报错。

Reference — Cơ chế

参考——实现机制

Mỗi ảnh là một
```
PlaneBufferGeometry
```
phủ shader tuỳ biến (
```
ZoomBlurImage
```
) — fragment shader lấy mẫu ảnh dọc theo vector hướng-về-tâm, trọng số Bezier, tạo hiệu ứng mờ hội tụ khi
```
uStrength
```
khác 0.
Chuyển ảnh:
```
progress
```
/
```
targetProgress
```
lerp dần (
```
updateProgress
```
),
```
uStrength
```
của 2 layer ảnh đan chéo (ảnh ra mờ dần, ảnh vào rõ dần).
Input: cuộn chuột (
```
wheel
```
) đổi
```
targetProgress
```
theo bước 1/20; click nửa trên/dưới màn hình = lùi/tiến; phím mũi tên tương tự.
Tâm blur (
```
uCenter
```
) lerp theo vị trí chuột mỗi frame → hiệu ứng "mắt dõi theo con trỏ".

每张图片都是一个
```
PlaneBufferGeometry
```
，覆盖自定义 shader（
```
ZoomBlurImage
```
）——fragment shader 沿“指向中心”的 vector 对图片采样，并应用 Bezier 权重；当
```
uStrength
```
不为 0 时，形成向中心汇聚的模糊效果。
图片切换：
```
progress
```
/
```
targetProgress
```
通过
```
updateProgress
```
逐步 lerp，两层图片的
```
uStrength
```
交错变化（旧图逐渐模糊，新图逐渐清晰）。
输入：鼠标滚轮（
```
wheel
```
）每次将
```
targetProgress
```
改变 1/20；点击屏幕上半区/下半区分别后退/前进；方向键同理。
Blur 中心（
```
uCenter
```
）每帧根据鼠标位置 lerp → 形成“视线追随指针”的效果。

Origin

来源

Nén từ
```
llmwiki/patterns/blur/
```
(snippet tham khảo chưa gắn skill nào, chưa từng track git) thành skill thật theo yêu cầu user 2026-09-17 — cùng đợt với
```
timeline
```
.

压缩自

llmwiki/patterns/blur/

（参考 snippet，尚未关联任何 skill，也从未纳入 git 跟踪），根据用户 2026-09-17 的需求整理成正式 skill——与

timeline

在同一批次完成。