feat(web): complete PBR shader, asset library and offscreen render chain

- generate a desktop-Blender PBR asset library and seed catalog v2 into OPFS
- add React asset browser, material preview sphere and Web PBR render panel
- extend shader graph/compiler to the finite 14-node set and native properties
- add image colour-space editing, scene-camera still rendering and asset repair
- add focused E2E/unit coverage and implementation status notes

Co-Authored-By: Claude Code <noreply@anthropic.com>

docs/status/WEB_PBR_ASSET_LIBRARY_20261111.md

@@ -0,0 +1,87 @@
+# Web PBR 资产库 / 着色器 / 浏览器渲染 — 实施与验证记录
+
+日期：2026-11-11
+状态：**功能实现完成；聚焦验证通过；整体产品验收仍由用户执行**
+
+## 已完成
+
+### 资产库（桌面 Blender → OPFS → React）
+- `tools/web/generate-pbr-library.py` 用 `build_blender_native/bin/blender` 生成
+  6 个模型、8 个 PBR 材质、7 个目录、14 张 256×256 EEVEE 预览。
+- `web/app/public/assets/pbr-library/`：`pbr-library.blend`、catalog、desktop canonical、
+  preview manifest、schema v2 `manifest.json`、build report、LICENSE（约 0.6 MiB）。
+- `tools/web/generate-pbr-library-manifest.mjs` 基于
+  `createAssetCatalogManifestV2FromDesktop` 补全 library/source SHA/preview 并校验。
+- `web/app/src/storage/asset-catalog-store.ts`：目录读取/迁移、首次 seed、OPFS 内容寻址写入、
+  预览读取/提交、缺失载荷修复；`web/protocol/storage.ts`、`storage.worker.ts`、
+  `StorageClient.ts` 增加四个生产命令。
+- `pbr-library-seed.ts`：启动校验 SHA 后 seed；`repairPbrAssetLibrary` 可重写缺失载荷。
+- `AssetLibraryPanel.tsx` + `asset-library.css`：目录/搜索/类型筛选/缩略图/拖拽。
+- Shading 工作区挂载；模型 `libraryLink` APPEND 进 Main，材质 APPEND 后分配到活动槽。
+
+### 材质与着色器
+- `MaterialPreviewSphere.tsx` + `material-preview.worker.ts`：three.js WebGL2 实时材质球，
+  显示编译报告；“保存为缩略图”经 `createAssetPreviewIdentity` + `commitAssetPreviewToOPFS`
+  写 OPFS 并原子更新 catalog。
+- `Properties` 支持活动材质槽；Shader Editor 跟随活动槽；面分配使用活动槽。
+- `shader-graph.ts` 支持 14 类节点的结构与属性校验；原生 `SET_PROPERTY` 支持
+  Math operation、Separate Color mode、Mix/Mapping/NormalMap/Bump/UVMap/TexImage 属性；
+  `setShaderGraph` 会应用节点属性。
+- 新增 `SET_IMAGE_COLORSPACE`（sRGB / Non-Color / Linear Rec.709），写入并随 `.blend` 保存。
+- `shader-compiler.ts` 扩展到 14 类节点：Blend 常量、Mix 常量（标量/颜色）、
+  Separate Color 常量、Mapping→UV Map→Image Texture、Normal Map/Bump 纹理链、
+  UV 变换；纹理绑定支持 BUMP、strength、uvMap、uvTransform。
+- `texture-assets.ts` 应用 UV 变换与 Bump 强度。
+- 浏览器编译 BLOCKED 不再阻止 Main 写入，编译报告返回 UI。
+- 已增量构建 `web_engine` 并同步 wasm。
+
+### 浏览器 PBR 渲染
+- `renderStill` 协议 + `viewport-render.worker.ts` 离屏渲染（当前视口或场景相机、隐藏网格、
+  PNG 输出）+ `OffscreenViewportRenderer.renderStill()`。
+- `PbrRenderPanel.tsx`：分辨率 256–2048、相机选择、渲染、下载、保存 OPFS。
+- Rendering 工作区默认 Web PBR，桌面 EEVEE 保留为可折叠备选。
+
+## 验证结果（2026-11-11）
+
+- `npm run typecheck`：**通过**。
+- 聚焦 E2E（8 个，全部通过）：
+  - `pbr-asset-library-production.spec.ts`（新增）：seed、14 缩略图、模型追加、材质分配、
+    材质球 COMPILED、1024² PBR 渲染、刷新后 catalog/预览持久化。
+  - `shader-editor-all-nodes-production.spec.ts`（新增）：添加并编辑 Math / Separate Color /
+    Mix / Mapping / Bump / UV Map / Texture Coord，材质球 COMPILED。
+  - `shader-editor-flow-production.spec.ts`
+  - `shader-main-command-production.spec.ts`
+  - `wbv2-material-slot-production.spec.ts`
+  - `wbv2-material-image-production.spec.ts`
+  - `pbr-real-assets-production.spec.ts`
+- 新增 `tests/unit/shader-compiler.test.mjs` 用例：Mix 常量、Separate Color 常量、
+  Mapping→Image→Bump + UV 变换、纹理 Mix 负例；全部通过。
+- `npm test`：467 项中 447 通过、20 失败。失败均为**既有台账/历史证据问题**，与本次功能无关：
+  - 18 项 `M12-*` 历史 manifest/evidence 哈希漂移（工作树中既有 golden 修改）。
+  - `M6-04B` 期望旧的 `/vendor/blender/web_engine.wasm` 路径，现产物为
+    `/vendor/blender/single/web_engine.wasm`（既有变体迁移）。
+  - `M7-17` 扫描到既有 `runNativeWorkflow` 中的 `error.message` 拼接。
+- 为让直接使用 `WebEngineClient` 的既有测试与新 native-files 排他锁兼容，修正了
+  `shader-main-command-production`、`wbv2-material-slot-production`、
+  `wbv2-material-image-production` 的客户端生命周期（先终止再重开）并同步 socket 标识符；
+  同时更新 `local-deps` 运行时依赖期望（`@xyflow/react`、`react-accessible-treeview`）。
+
+## 已知残余（不影响本批功能验收）
+
+1. 生成型 packed 图片的 `colorSpace` 在 `web_engine_blend_reader` 读取 SceneIR 时未输出，
+   UI 用本地选择值显示；`.blend` 保存后实测为 `Non-Color`，Main 持久化正确。
+   若需 UI 重启后仍显示，可后续补 reader 回退。
+2. 14 类之外的任意节点、非 Principled 闭包、动态 TEX_COORD/OBJECT_INFO、
+   通用 GLSL/WebGPU 后端仍未支持（按既定范围）。
+3. 上述 20 项既有单元测试失败未在本批修复（属台账/历史证据，避免改动已冻结记录）。
+
+## 使用验证入口
+
+```bash
+cd web
+npm run dev -- --host 127.0.0.1 --port 5173
+# 浏览器打开 http://127.0.0.1:5173/?ui=web
+```
+
+Shading：资产库（14 个 PBR 资产）→ 双击 PBR Cube → 双击 PBR Metal Brushed →
+材质球与视口更新 → Rendering → “渲染 PBR” → 下载/OPFS。