需要写 GLSL fragment shader…

适用于在浏览器/Three.js 中编写 GLSL 片段着色器，实现全屏动画渐变、噪声、SDF、域扭曲、图像过渡、故障和后处理，并交付可单文件打开与截图验证的 HTML。

适用场景

解决思路

1. 写 fragment shader 时，每个像素计算一个颜色：先用 `vec2 uv = gl_FragCoord.xy / u_resolution.xy;` 得到 0..1 坐标，再用 `vec2 p = uv * 2.0 - 1.0;` 转为以中心为原点的 -1..1 坐标，然后 `p.x *= u_resolution.x / u_resolution.y;` 做宽高比校正。
2. 用 IQ cosine palette 最快做出好看的动画渐变：`vec3 col = 0.5 + 0.5 * cos(u_time + p.xyx + vec3(0.0, 2.0, 4.0));`，或通用形式 `a + b*cos(2π*(c*t + d))`，其中 a、b、c、d 是 vec3 可调参数。
3. 把 `smoothstep` 和 `mix` 作为主力：`smoothstep(e0, e1, x)` 生成平滑 0→1，`mix(a, b, t)` 线性混合；用一像素宽度做边缘抗锯齿：`float px = fwidth(d); float mask = smoothstep(px, -px, d);`。
4. 不需要纹理时实现 hash + value noise：`float hash(vec2 p){ return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453); }`；`noise` 中用 `vec2 i = floor(p), f = fract(p); vec2 u = f * f * (3.0 - 2.0 * f);` 平滑插值，再对四个角 hash 做双线性 `mix`。
5. 需要有机纹理时实现 fbm：初始化 `float v = 0.0, a = 0.5;`，循环 5 次 `v += a * noise(p); p *= 2.0; a *= 0.5;`，返回 v；完整 value/simplex noise 与 fbm 变体在 `references/glsl-cookbook.md`。
6. 用 SDF 画分辨率无关的清晰形状：距离内部为负、外部为正；`sdCircle` 用 `length(p) - r`；`sdBox` 用 `vec2 d = abs(p) - b; return length(max(d,0.0)) + min(max(d.x,d.y),0.0);`；渲染时用 `float m = smoothstep(fwidth(d), -fwidth(d), d);`。
7. 做流体/大理石纹理时用 domain warping：`vec2 q = vec2(fbm(p), fbm(p + vec2(5.2, 1.3))); float n = fbm(p + 4.0 * q + u_time * 0.1);`。
8. 实现图像过渡时采样两张纹理，并逐像素按进度 uniform `u_progress`（0→1）混合。
9. Dissolve / noise wipe：`float n = noise(uv * 20.0); float edge = smoothstep(u_progress - 0.05, u_progress, n); gl_FragColor = mix(texture2D(tex0, uv), texture2D(tex1, uv), 1.0 - edge);`。
10. Displacement 过渡：`float disp = texture2D(dispTex, uv).r; vec2 d0 = uv + vec2(disp * u_progress * 0.3, 0.0); vec2 d1 = uv - vec2(disp * (1.0 - u_progress) * 0.3, 0.0); gl_FragColor = mix(texture2D(tex0, d0), texture2D(tex1, d1), u_progress);`。
11. Glitch 过渡：`float row = floor(uv.y * 20.0); float shift = (hash(vec2(row, floor(u_time * 12.0))) - 0.5) * 0.1 * u_glitch; vec2 g = uv + vec2(shift, 0.0);`，然后分别采样 RGB 并偏移色差：`c.r = texture2D(tex, g + vec2(0.005, 0.0)).r; c.g = texture2D(tex, g).g; c.b = texture2D(tex, g - vec2(0.005, 0.0)).b;`。
12. Three.js 中先声明 uniforms：`u_time: { value: 0 }`、`u_resolution: { value: new THREE.Vector2(innerWidth, innerHeight) }`、`u_mouse: { value: new THREE.Vector2(0, 0) }`。
13. 创建 `THREE.ShaderMaterial`：传入 uniforms、vertexShader（全屏 pass 可写 `void main(){ gl_Position = vec4(position, 1.0); }`）和 fragmentShader（GLSL 字符串）。
14. 全屏三角形/四边形：用 `new THREE.PlaneGeometry(2, 2)`、`new THREE.Mesh(geometry, material)` 加入 `scene`，用 `new THREE.Camera()`（无需投影）渲染；创建 `WebGLRenderer`，`renderer.setSize(innerWidth, innerHeight)`，`renderer.setPixelRatio(Math.min(devicePixelRatio, 2))`，把 `renderer.domElement` 添加到 body。
15. 动画循环：用 `THREE.Clock`，在 `renderer.setAnimationLoop` 中把 `uniforms.u_time.value = clock.getElapsedTime()` 后 `renderer.render(scene, camera)`；监听 resize，更新 `renderer.setSize` 和 `uniforms.u_resolution.value.set(innerWidth, innerHeight)`。
16. 全屏 pass 配普通 camera 时，vertex shader 直接输出 `position`，跳过投影；若 shader 应用到真实几何体，则从 vertex shader 传 `varying vec2 vUv;`：`vUv = uv; gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);`。
17. 移动端/性能：不需要 highp 时声明 `precision mediump float;`；大坐标、深 fbm 等效果需要 `highp`。
18. 限制像素比：`renderer.setPixelRatio(Math.min(devicePixelRatio, 2))`；重 shader 先渲染到低分辨率 target 再放大。
19. GLSL ES 中循环必须有常量边界，不能动态循环次数；fbm octave 保持 ≤ 5–6。
20. 热路径避免 `if`/分支，优先 `mix`/`step`/`smoothstep`；尽量减少 `texture2D` 调用，避免 dependent texture reads。
21. WebGL2/GLSL ES 3.00 可用 `texelFetch`、整数运算、`textureLod`；声明 `#version 300 es` 并使用 `in`/`out`/`fragColor`。
22. 交付自包含 shader（渐变/噪声背景、过渡、生成循环）时，产出一个可直接在浏览器打开的 HTML 文件：Three.js 通过 importmap 从 CDN 引入，一个全屏 quad，一个 render loop，无构建步骤；不要在一个文件能完成时引入 bundler。
23. 如果环境有打包 helper，用 `scripts/seek-shot.sh anim.html 0 1.5 3` 冻结 `?t=N` harness 并逐个时刻截图；用 `scripts/contact-sheet.sh sheet.png frame-*.png` 拼成 contact sheet 一眼审查；细节见 `scripts/README.md`。
24. 输出契约：一个 `.html`，importmap 把 `three` 固定到 CDN；GLSL 字符串、`ShaderMaterial`、全屏 quad、render loop 都放在同一个内联 `<script type="module">` 中。
25. 把 shader 写成 uniforms 的纯函数——一切由 `u_time` 驱动（过渡再加 `u_progress`）；所有动画都经过一个可冻结的 uniform。
26. shader 内的随机性来自确定性的 `hash(uv)`，不需要逐帧播种；不要喂 wall-clock，唯一时间源用 `u_time`。
27. 实现 seek/freeze harness：`?t=N` 时把 `u_time`（以及可选 `u_progress`）设为 N，渲染一帧并停止循环，得到确定性静帧；代码模式：解析 `new URLSearchParams(location.search).get("t")`，`frame(time)` 中设 `uniforms.u_time.value = time`、`uniforms.u_progress && (uniforms.u_progress.value = Math.min(time, 1))` 后 render；若 `t !== null` 则 `frame(parseFloat(t)); window.__ready = true;`，否则用 `setAnimationLoop` 和 clock。
28. 验证循环：render → freeze → screenshot → check；在两个 t 时刻打开 start、mid、end（`?t=0`、`?t=<mid>`、`?t=<end>`；过渡用 `u_progress` 0 / 0.5 / 1），分别截图，检查 fidelity（符合 brief）和 artifacts：黑/空 canvas 通常是 shader 编译或解析错误（读 console 的 GLSL log），banding、NaN 爆白（`pow`/`log` 负数导致白/垃圾像素）、过渡缺纹理（CDN/asset 404）。
29. WebGL 需要 GPU context；Playwright/Chromium 可 headless 提供 (swiftshader)。
30. 截图命令：`npx playwright screenshot --wait-for-timeout=600 "file://$PWD/shader.html?t=2.0" frame-mid.png`。
31. 完成前检查 1：canvas 正常渲染——不是黑/空，无 shader 编译或 console 错误，无 CDN 404。
32. 完成前检查 2：`?t=N` 冻结出可复现帧——同 N 同像素；`u_time` 是唯一时钟。
33. 完成前检查 3：已截 start / mid / end（或 progress 0/0.5/1）——符合 brief，无 banding/NaN/黑屏。
34. 完成前检查 4：若嵌入 SPA，必须释放且无泄漏——`material.dispose()`、`geometry.dispose()`、`renderer.dispose()`，停止循环。
35. 完成前检查 5：尊重 `prefers-reduced-motion`——装饰性动画冻结 `u_time` 或放慢。
36. 速查映射：动画渐变 → cosine palette `a + b*cos(...)`。
37. 速查映射：有机纹理 → `fbm(uv * scale + time)`。
38. 速查映射：清晰形状 → SDF + `smoothstep(fwidth(d), -fwidth(d), d)`。
39. 速查映射：流体/大理石 → domain warp：noise into noise。
40. 速查映射：揭示过渡 → threshold noise vs `u_progress`。
41. 速查映射：故障 → row hash shift + RGB channel offset。
42. 速查映射：抗锯齿边缘 → `fwidth(d)` 获取屏幕空间宽度。
43. 需要完整实现时查阅 `references/glsl-cookbook.md`：完整 value/simplex noise + fbm、IQ cosine-palette 配方、完整 SDF 形状库（布尔运算和圆角）、domain warping、三种图像过渡完整 shader、Three.js uniform/texture 接线、GLSL ES 3.00 迁移、移动端精度坑。

适用边界 · 注意事项

• 普通的 DOM/CSS/SVG 动效或不需要逐像素并行处理时，不要写 fragment shader，成本不划算。
• 目标环境无法提供 WebGL/GPU 上下文（禁用硬件加速、旧浏览器/无 headless GPU）时，不要依赖 fragment shader 作为唯一渲染路径。
• 单个 shader 能用一个 HTML 文件交付时，不要为它引入打包器或复杂构建链。