@bovinphang/frontend-craft 2.5.0

package/skills/fec-accessibility-check/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: fec-accessibility-check
+description: Use when reviewing or improving frontend accessibility, semantic structure, keyboard support, focus management, ARIA labels, screen reader behavior, WCAG 2.2 issues, touch accessibility, or assistive-technology regressions; Chinese triggers include 无障碍, accessibility, a11y, WCAG, 屏幕阅读器.
+---
+
+# 无障碍实现规范（WCAG 2.2 AA）
+
+## Purpose
+
+确保前端 UI 对残障用户可访问，满足 WCAG 2.2 AA 的核心要求，并能被键盘、屏幕阅读器、触控和缩放用户稳定使用。
+
+## Procedure
+
+1. 检查语义结构：landmark、标题层级、表单 label、按钮/链接可访问名称、表格语义和图片 alt。
+2. 检查键盘路径：Tab 顺序、Enter/Space/Esc 行为、焦点可见、关闭后焦点恢复。
+3. 检查复杂组件：对话框、菜单、标签页、树、抽屉、表格和自定义控件的 ARIA 状态。
+4. 检查动态状态：loading、empty、error、toast 和异步更新需要被屏幕阅读器感知。
+5. 检查视觉与触控可读性：文本/背景对比、focus ring、缩放到 200%、减少动效偏好、触摸目标尺寸和移动端虚拟键盘行为。
+6. 用真实键盘路径复核关键流程，必要时补充屏幕阅读器或浏览器无障碍树观察；屏幕阅读器流程见 [references/screen-reader-testing.md](references/screen-reader-testing.md)。
+7. 复核 WCAG 2.2 新增高频风险：可见焦点不被遮挡、拖拽操作有替代路径、目标尺寸过小、帮助入口和认证流程不依赖记忆负担。
+8. 输出分级报告；报告格式见 [references/report-template.md](references/report-template.md)。
+
+## Detailed References
+
+撰写无障碍审查报告时，加载 [references/report-template.md](references/report-template.md)。需要验证屏幕阅读器公告、焦点读法和动态区域时，加载 [references/screen-reader-testing.md](references/screen-reader-testing.md)。
+
+## Constraints
+
+- 优先使用语义化 HTML，而不是 ARIA。
+- `role` 不应覆盖原生语义。
+- 交互元素必须可键盘访问。
+- 表单错误必须与字段关联。
+- 颜色对比度风险需要指出具体文本/背景组合。
+- 不用 ARIA 弥补可以用原生 HTML 解决的问题。
+- 不把浏览器自动可访问树当作最终结论；关键路径需要用键盘和至少一种辅助技术或等价检查验证。
+
+## Expected Output
+
+交互元素可键盘访问，语义和 ARIA 使用正确，焦点管理稳定；无障碍检查报告保存为 `reports/accessibility-review-YYYY-MM-DD-HHmmss.md`。

package/skills/fec-accessibility-check/references/report-template.md

@@ -0,0 +1,23 @@
+# 无障碍检查报告模板
+
+```markdown
+# 无障碍检查报告
+
+> 生成时间: YYYY-MM-DD HH:mm
+> 评审工具: frontend-craft
+> 标准: WCAG 2.2 AA
+
+## 必须修复 (N项)
+- **[文件:行号]** 问题描述 -> 建议修改
+
+## 建议改进 (N项)
+- **[文件:行号]** 问题描述 -> 建议修改
+
+## 已通过项
+- ...
+
+## 建议的代码修改
+- ...
+```
+
+检查完成后，将报告保存到 `reports/accessibility-review-YYYY-MM-DD-HHmmss.md`，并告知用户报告路径。

package/skills/fec-accessibility-check/references/screen-reader-testing.md

@@ -0,0 +1,33 @@
+# 屏幕阅读器测试
+
+## 何时测试
+
+以下场景需要使用屏幕阅读器或浏览器无障碍树进行检查：
+
+- 对话框、抽屉、菜单、标签页、组合框、树形控件和自定义控件。
+- 异步状态更新、toast 通知、校验错误和 loading 区域。
+- 表格、虚拟列表、图表、dashboard 和数据密集型控件。
+- 触摸探索、虚拟键盘或焦点顺序可能与桌面不同的移动端流程。
+
+## 最小流程
+
+1. 先只用键盘操作：Tab、Shift+Tab、Enter、Space、Esc，以及适用场景下的方向键。
+2. 在浏览器开发者工具中检查可访问名称、角色、状态和元素关系。
+3. 条件允许时至少跑一轮辅助技术验证：NVDA/Firefox、JAWS/Chrome、VoiceOver/Safari 或 TalkBack/Chrome。
+4. 验证路由变化、校验错误、加载完成和破坏性确认是否有正确公告。
+5. 记录具体用户影响、期望读法、实际读法和建议修复方式。
+
+## 动态内容
+
+- 非阻塞状态更新使用 `aria-live="polite"`。
+- 紧急错误可谨慎使用 `role="alert"`，不要滥用。
+- 只有当用户任务上下文发生变化时才移动焦点，例如打开弹窗或提交后跳转。
+- 关闭浮层后，将焦点恢复到触发控件。
+
+## 常见问题
+
+- 纯图标按钮没有可访问名称。
+- 对话框内容先于标题被朗读，或缺少模态边界。
+- 表单错误只在视觉上展示，没有用 `aria-describedby` 与字段关联。
+- Toast 消失太快，屏幕阅读器用户来不及理解。
+- 虚拟列表行丢失行位置、表格语义或键盘连续性。

package/skills/fec-api-integration/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: fec-api-integration
+description: Use when designing, implementing, or reviewing frontend-to-backend API integration, typed API clients, REST/tRPC/OpenAPI client choices, auth refresh, API error mapping, upload flows, SSE/WebSocket/polling choices, CORS-facing frontend behavior, or cross-boundary loading/error states. Do not use for backend-only service architecture or TanStack Query cache policy alone; Chinese triggers include API 集成, 前后端联调, typed API client, 接口错误处理, SSE, WebSocket.
+---
+
+# API 集成
+
+适用于前端与后端边界的类型、错误、鉴权、上传、实时通信和用户状态设计。需要具体代码模式时加载 [integration-patterns.md](references/integration-patterns.md)。
+
+## Purpose
+
+规范前端 API 集成边界，让请求、错误、鉴权和实时数据可维护。
+
+## Procedure
+
+1. 明确接口所有权
+   - 同团队 TypeScript 全栈可考虑 tRPC 或共享 schema。
+   - 多语言或多消费者 API 优先 OpenAPI/GraphQL codegen。
+   - 小型内部应用可用 typed fetch wrapper，但类型必须集中维护。
+   - 不在组件里散落 `fetch`、URL、header、错误解析和 token 逻辑。
+   - 公共接口需要明确版本、兼容窗口、废弃字段策略和调用方范围。
+
+2. 建立客户端边界
+   - 用一个 API client 处理 base URL、credentials、JSON 解析、超时、取消和统一错误。
+   - 环境变量只读取公开前缀，私密 token 不进入客户端 bundle。
+   - 组件只消费 domain 函数或 query/mutation hook，不直接拼接接口路径。
+   - 204、空响应、非 JSON 错误和网络断开要有明确行为。
+   - TypeScript contract 必须覆盖请求、响应、错误形状和分页/游标元数据。
+
+3. 映射用户可理解的错误
+   - 401：刷新失败后引导登录。
+   - 403：说明权限不足，不重复重试。
+   - 404：展示缺失状态或返回上级入口。
+   - 409：提示冲突和下一步操作。
+   - 422：映射字段级错误。
+   - 429/5xx/网络错误：允许退避重试或展示稍后再试。
+   - 未识别错误要落到统一 fallback，不把原始后端异常暴露给用户。
+   - 所有错误都应归一到用户可恢复动作：重试、重新登录、修改输入、返回上级、联系支持或稍后再试。
+   - 错误对象要保留面向日志的 trace id / request id，但 UI 不暴露内部堆栈、SQL、服务名或敏感字段。
+
+4. 管理接口演进
+   - 兼容新增字段；删除或改名字段必须走迁移期、适配层或双写/双读策略。
+   - 用 schema、类型生成物或 contract test 捕捉破坏性变更。
+   - 对前后端协作项记录状态码、错误码、幂等性、重试语义和时区/金额/枚举规则。
+
+5. 处理鉴权刷新
+   - Access token 生命周期短，refresh 优先放在 httpOnly cookie 或服务端会话。
+   - 401 后只允许单次刷新队列，避免多个请求同时刷新。
+   - 刷新失败要清理本地身份状态并跳转登录。
+   - 不把 bearer token 放在 URL、localStorage 或日志里。
+
+6. 选择上传与实时方案
+   - 小文件可用 multipart；大文件优先预签名直传或分片上传。
+   - 只需要服务端推送时用 SSE；双向协作、聊天或多人状态用 WebSocket。
+   - 简单状态刷新、低频任务进度可用 polling，并设置停止条件。
+   - 上传和实时连接都需要取消、重连、超时和错误 UI。
+
+7. 验证集成质量
+   - 检查 loading、empty、error、unauthorized、offline、retrying 状态。
+   - 用浏览器网络面板确认 base URL、credentials、CORS 和状态码行为。
+   - 用 mock 或测试服务覆盖 401、403、422、500、断网和取消请求。
+   - 确认客户端 bundle 不包含私密环境变量、服务端密钥或内部地址。
+   - 对关键 API client 行为补最小测试，证明超时、取消、错误映射和刷新队列可预期。
+   - 验证错误边界与请求层协作：渲染异常进 Error Boundary，请求失败进可恢复 UI，不互相吞掉。
+
+## Constraints
+
+- 不在页面组件中直接管理 token refresh、错误格式解析或重试策略。
+- 不对 4xx 业务错误做盲目自动重试。
+- 不把后端异常栈、内部错误码或原始 SQL/服务名暴露给用户。
+- 不用 localStorage 存储高价值 token；若遗留系统无法避免，必须联动安全审查。
+- 不用 WebSocket 替代简单轮询，也不用轮询实现高频双向协作。
+- 不让上传经过 API 服务器转发大文件，除非有明确合规或扫描需求。
+- 不在公共接口里直接暴露临时字段、数据库字段名或后端内部错误结构。
+
+## Expected Output
+
+输出应包含 API client 边界、接口类型来源、错误映射、鉴权刷新策略、上传/实时方案和验证结果。完成后组件不散落请求细节，用户状态完整，失败场景可恢复，客户端不会泄露服务端密钥。

package/skills/fec-api-integration/references/integration-patterns.md

@@ -0,0 +1,80 @@
+# API 集成实现模式
+
+## 类型化 Fetch 客户端
+
+```ts
+export class ApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly body: unknown,
+  ) {
+    super(`API 请求失败，状态码 ${status}`);
+  }
+}
+
+export async function requestJson<T>(
+  path: string,
+  init: RequestInit = {},
+): Promise<T> {
+  const response = await fetch(`${import.meta.env.VITE_API_URL}${path}`, {
+    ...init,
+    headers: {
+      Accept: "application/json",
+      "Content-Type": "application/json",
+      ...init.headers,
+    },
+    credentials: "include",
+  });
+
+  if (!response.ok) {
+    const body = await response.json().catch(() => null);
+    throw new ApiError(response.status, body);
+  }
+
+  if (response.status === 204) return undefined as T;
+  return response.json() as Promise<T>;
+}
+```
+
+## 用户端错误映射
+
+```ts
+export function getApiMessage(error: unknown): string {
+  if (!(error instanceof ApiError)) return "操作失败，请稍后重试。";
+
+  if (error.status === 401) return "请重新登录。";
+  if (error.status === 403) return "您没有权限执行此操作。";
+  if (error.status === 404) return "请求的资源已不存在。";
+  if (error.status === 409) return "此变更与最新数据冲突。";
+  if (error.status === 422) return "请检查标红字段。";
+  if (error.status === 429) return "请求过于频繁，请稍后再试。";
+
+  return "服务暂不可用，请稍后重试。";
+}
+```
+
+## 上传选型
+
+| 需求             | 推荐方案                      |
+| ---------------- | ----------------------------- |
+| 小头像或 CSV     | Multipart 请求                |
+| 大视频或归档文件 | 预签名直传                    |
+| 弱网环境大文件   | 分片断点续传                  |
+| 入库前合规扫描   | 经 API 中介上传（含大小限制） |
+
+## 实时通信选型
+
+| 需求                 | 推荐方案                  |
+| -------------------- | ------------------------- |
+| 任务进度或通知       | SSE（Server-Sent Events） |
+| 聊天、在线状态、协作 | WebSocket                 |
+| 数秒一次的状态轮询   | 定时轮询（Polling）       |
+| 服务端 AI Token 流   | SSE 或 fetch 流式响应     |
+
+## 审查清单
+
+- API 地址和凭证集中管理。
+- 客户端需处理 204、非 JSON 错误、取消和离线状态。
+- Token 刷新机制不能引发请求风暴。
+- 组件应消费 hooks/领域函数，而非直接调用原始 fetch。
+- 上传和实时流需暴露进度、取消、失败和重试状态。

package/skills/fec-browser-storage/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: fec-browser-storage
+description: Use when choosing, implementing, or reviewing browser storage such as localStorage, sessionStorage, IndexedDB, cookies, client persistence, offline data, secure storage, or cleanup strategy; Chinese triggers include 浏览器存储, 客户端持久化.
+---
+
+# 浏览器存储
+
+## Purpose
+
+根据数据大小、安全要求和生命周期选择合适的客户端存储方案。
+
+## Procedure
+
+1. 先判断数据敏感度、体积、生命周期、是否需要跨 Tab、是否需要随请求发送。
+2. 小量非敏感偏好用 localStorage；Tab 级临时数据用 sessionStorage；大量结构化数据或离线缓存用 IndexedDB；认证态优先 httpOnly cookie。
+3. 封装统一 key 前缀、JSON parse/stringify、异常处理、过期清理和 quota 兜底。
+4. 敏感数据按安全规则处理，不把明文 token、密码、信用卡信息放进可被 JS 读取的存储。
+5. 审查隐私模式、存储配额、清理策略和跨浏览器兼容性。
+
+## Detailed References
+
+涉及存储选型表、localStorage/sessionStorage 封装、IndexedDB 示例、Cookie 辅助方法和敏感数据规则时，加载 [references/storage-patterns.md](references/storage-patterns.md)。
+
+## Constraints
+
+- localStorage/sessionStorage 是同步 API，大数据读写会阻塞主线程。
+- 除 httpOnly cookie 外，客户端存储都可被 XSS 读取。
+- Cookie 每次请求自动携带，不适合大数据。
+- IndexedDB 配额和隐私模式行为有浏览器差异。
+- URL 中不要传 token 或敏感数据。
+
+## Expected Output
+
+产出统一的 storage/cookie/db 封装，key 有命名空间，数据有过期或清理策略，敏感数据只进入合适的安全边界。

package/skills/fec-browser-storage/references/storage-patterns.md

@@ -0,0 +1,65 @@
+# 浏览器存储模式
+
+## 选型表
+
+| 存储 | 容量 | API | 是否发送服务端 | 适用场景 | 安全性 |
+| --- | --- | --- | --- | --- | --- |
+| LocalStorage | ~5MB | 同步 | 否 | 用户偏好、非敏感持久数据 | XSS 可读取 |
+| SessionStorage | ~5MB | 同步 | 否 | Tab 级临时数据 | XSS 可读取 |
+| IndexedDB | 大 | 异步 | 否 | 大数据、文件、离线缓存 | XSS 可读取 |
+| Cookie | ~4KB | 同步 | 是 | 认证 Session/httpOnly token | httpOnly 可防 JS 读取 |
+
+## localStorage 封装
+
+```ts
+const STORAGE_PREFIX = "app:";
+
+export const storage = {
+  get<T>(key: string): T | null {
+    try {
+      const raw = localStorage.getItem(STORAGE_PREFIX + key);
+      return raw ? JSON.parse(raw) : null;
+    } catch {
+      return null;
+    }
+  },
+  set<T>(key: string, value: T): void {
+    localStorage.setItem(STORAGE_PREFIX + key, JSON.stringify(value));
+  },
+  remove(key: string): void {
+    localStorage.removeItem(STORAGE_PREFIX + key);
+  },
+  clear(): void {
+    Object.keys(localStorage)
+      .filter((key) => key.startsWith(STORAGE_PREFIX))
+      .forEach((key) => localStorage.removeItem(key));
+  },
+};
+```
+
+## IndexedDB
+
+```ts
+import { openDB } from "idb";
+
+export const db = openDB("app-offline-db", 1, {
+  upgrade(database) {
+    if (!database.objectStoreNames.contains("requests")) {
+      database.createObjectStore("requests", { keyPath: "id" });
+    }
+  },
+});
+```
+
+## Cookie
+
+- httpOnly 只能由服务端设置。
+- 认证 Cookie 使用 `Secure`、`SameSite=Lax/Strict`。
+- 需要跨站点嵌入时才考虑 `SameSite=None; Secure`。
+
+## 敏感数据规则
+
+- 认证 token、刷新 token、Session ID：优先 httpOnly cookie。
+- 用户偏好：localStorage。
+- 表单草稿：sessionStorage 或 IndexedDB，避免敏感字段。
+- 离线数据：IndexedDB，但不要缓存隐私或高价值敏感数据。

package/skills/fec-canvas-threejs/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: fec-canvas-threejs
+description: Use when building or reviewing Canvas 2D, Three.js/WebGL, React Three Fiber, GLSL shaders, ShaderToy-to-WebGL adaptation, 2D/3D visualization, game rendering, animation loops, GPU resource cleanup, or rendering performance. Do not use for standard DOM UI, charts already covered by a chart library, or non-graphical performance work; Chinese triggers include Canvas, Three.js, WebGL, GLSL, Shader, 3D, 数据可视化, 游戏.
+---
+
+# Canvas 与 Three.js
+
+## Purpose
+
+在浏览器中实现高性能 2D/3D 图形渲染。
+
+## Procedure
+
+1. 先选渲染层：标准 UI 用 DOM；简单 2D 图形/签名/粒子用 Canvas 2D；3D 模型、空间交互和复杂粒子用 Three.js/WebGL；React 项目中的声明式 3D 用 React Three Fiber。
+2. 为渲染容器定义稳定尺寸、DPI 适配和 resize 行为；Canvas 不会自动随 CSS 清晰缩放。
+3. 动画循环使用 `requestAnimationFrame`，不可见或无变化时暂停，卸载时取消。
+4. Three.js 必须释放 geometry/material/texture/renderer，并移除事件监听和 observer。
+5. Shader/WebGL 任务先识别是 SDF、ray marching、noise、particle、post-processing、multipass 还是调试问题，再决定是否需要原生 WebGL2、Three.js ShaderMaterial 或 R3F。
+6. WebGL2 适配时检查 GLSL 版本、入口函数、varying/in-out、texture API、uniform 使用和函数声明顺序，避免白屏只留控制台错误。
+7. 对不可访问的图形内容提供 `aria-label`、替代文本或 DOM 版摘要；交互式图形要有键盘兜底。
+
+## Core Patterns
+
+```ts
+const dpr = Math.min(window.devicePixelRatio || 1, 2);
+canvas.width = width * dpr;
+canvas.height = height * dpr;
+canvas.style.width = `${width}px`;
+canvas.style.height = `${height}px`;
+ctx.scale(dpr, dpr);
+```
+
+```ts
+let animationId = 0;
+function animate() {
+  animationId = requestAnimationFrame(animate);
+  renderer.render(scene, camera);
+}
+
+return () => {
+  cancelAnimationFrame(animationId);
+  geometry.dispose();
+  material.dispose();
+  renderer.dispose();
+};
+```
+
+## Detailed References
+
+涉及 Canvas 2D 绘图、动画循环、Three.js 场景搭建、React Three Fiber、InstancedMesh 和性能清理时，加载 [references/rendering-patterns.md](references/rendering-patterns.md)。
+
+涉及着色器路由、WebGL2 适配、GLSL 调试、多 pass 预算和视觉验证时，加载 [references/shader-webgl-patterns.md](references/shader-webgl-patterns.md)。
+
+## Constraints
+
+- Canvas/WebGL 内容对屏幕阅读器不可见，必须提供替代语义。
+- WebGL 消耗 GPU，低端设备需限制像素比、面数和纹理大小。
+- Three.js 资源不会自动释放，遗漏 `dispose()` 会造成 GPU 内存泄漏。
+- Canvas 响应式必须同步 CSS 尺寸、绘图尺寸和相机/viewport。
+- 复杂布局/路径规划可联用后台线程 workflow，但渲染本身仍在主线程/渲染线程协调。
+- Shader 主循环、采样层数和多 pass 数量必须有预算；低端设备上要降低 DPR、步数、粒子数或禁用重后处理。
+- 交付前必须确认 canvas 非空、尺寸正确、resize 后不拉伸、控制台无 shader compile/link 错误。
+
+## Expected Output
+
+2D/3D 场景清晰、响应式、可清理，关键设备上接近 60fps；用户能通过替代文本或键盘路径理解/操作核心内容。

package/skills/fec-canvas-threejs/references/rendering-patterns.md

@@ -0,0 +1,67 @@
+# Canvas、Three.js 与 R3F 模式
+
+## Canvas 2D
+
+```ts
+const canvas = document.getElementById("chart") as HTMLCanvasElement;
+const ctx = canvas.getContext("2d");
+if (!ctx) throw new Error("Canvas 2D is unavailable");
+
+ctx.fillStyle = "#3b82f6";
+ctx.fillRect(10, 10, 50, 50);
+ctx.beginPath();
+ctx.arc(100, 100, 30, 0, Math.PI * 2);
+ctx.fill();
+```
+
+## 动画循环
+
+```ts
+let animationId = 0;
+
+function animate() {
+  ctx.clearRect(0, 0, canvas.width, canvas.height);
+  updateParticles();
+  drawParticles(ctx);
+  animationId = requestAnimationFrame(animate);
+}
+
+animate();
+return () => cancelAnimationFrame(animationId);
+```
+
+## Three.js 基础场景
+
+```ts
+const scene = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(75, width / height, 0.1, 1000);
+const renderer = new THREE.WebGLRenderer({ antialias: true });
+renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+
+const geometry = new THREE.BoxGeometry(1, 1, 1);
+const material = new THREE.MeshStandardMaterial({ color: 0x00ff00 });
+const cube = new THREE.Mesh(geometry, material);
+scene.add(cube);
+```
+
+## React Three Fiber
+
+```tsx
+<Canvas camera={{ position: [0, 0, 5], fov: 75 }} role="img" aria-label="3D 产品预览">
+  <ambientLight intensity={0.5} />
+  <directionalLight position={[5, 5, 5]} />
+  <mesh>
+    <boxGeometry />
+    <meshStandardMaterial color="hotpink" />
+  </mesh>
+  <OrbitControls />
+</Canvas>
+```
+
+## 性能与清理
+
+- 纹理尽量压缩并限制尺寸，常规上限先按 2048px 评估。
+- 重复几何体用 `InstancedMesh`。
+- 不需要持续重绘时暂停 animation loop。
+- 卸载时释放 geometry、material、texture、renderer、controls。
+- ResizeObserver 更新相机 aspect 和 renderer size。

package/skills/fec-canvas-threejs/references/shader-webgl-patterns.md

@@ -0,0 +1,67 @@
+# Shader 与 WebGL 模式
+
+## 技术选型参考
+
+| 目标               | 推荐起点           | 注意事项                       |
+| ------------------ | ------------------ | ------------------------------ |
+| 数学几何 3D 形态   | SDF + 光线步进     | 步数上限、法线质量、软阴影开销 |
+| 有机运动效果       | 噪声 + 域扭曲      | 过度绘制、重复噪声调用         |
+| 粒子效果           | 实例化或着色器粒子 | 移动端粒子数量上限、混合开销   |
+| 泛光/故障/色彩调整 | 后处理通道         | 额外帧缓冲区显存               |
+| 持续模拟           | 乒乓帧缓冲区       | 纹理格式支持                   |
+| 白屏调试           | 编译/链接日志      | 函数顺序、被优化掉的 uniform   |
+
+## WebGL2 适配清单
+
+- 片元着色器以 `#version 300 es` 开头。
+- 添加 `precision highp float;` 和 `out vec4 fragColor;`。
+- 用 `in`/`out` 替代旧版 `varying`。
+- 用 `texture()` 替代 `texture2D()`。
+- 将 ShaderToy 风格的 `mainImage` 包装为标准 `main`。
+- 使用 `gl_FragCoord.xy` 获取片元坐标。
+- 辅助函数必须在被调用前声明。
+- 预计算常量，不要在宏定义中放函数调用。
+
+## 运行时骨架
+
+```ts
+const gl = canvas.getContext("webgl2");
+if (!gl) throw new Error("WebGL2 is unavailable");
+
+function compile(type: number, source: string) {
+  const shader = gl.createShader(type);
+  if (!shader) throw new Error("Cannot create shader");
+  gl.shaderSource(shader, source.trim());
+  gl.compileShader(shader);
+
+  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+    throw new Error(gl.getShaderInfoLog(shader) ?? "Shader compile failed");
+  }
+
+  return shader;
+}
+```
+
+## 性能预算
+
+- 光线步进步数：从 64 起步，仅在出现伪影且证明必要时再提升。
+- 体积采样：桌面端每条射线 16-24 次，移动端酌情降低。
+- FBM 倍频：从 4 开始；避免在光线循环内嵌套 FBM。
+- DPR：桌面端上限 2，移动端重度场景上限 1.5。
+- 纹理尺寸：使用压缩或缩放资源；不要假设 4K 纹理是安全的。
+
+## 调试视图
+
+- 法线：输出归一化后的法线，映射到 0-1 范围。
+- 步数：输出当前步数除以最大步数。
+- 距离/深度：以灰度输出命中距离。
+- UV：映射后输出 `vec3(uv, 0.0)`。
+- 材质 ID：将 ID 映射到少量固定调色板。
+
+## 视觉验证
+
+- 桌面端和移动端尺寸下 Canvas 不为空白。
+- 缩放时更新绘制缓冲区、视口、相机纵横比和 uniform。
+- 低功耗模式下仍能响应，或有静态降级方案。
+- 控制台无着色器编译/链接错误。
+- 卸载或场景隐藏时停止动画。