feat(web): finish RE 5000PBR lesson video and fix non-ASCII GLB import

- Add 11:07 Chinese-narrated lesson video, VTT, poster and 13 chapter screenshots. - Regenerate 20-render WebGL2 matrix and 15 operation captures on RTX 4060. - Fix WASM staging for non-ASCII import filenames (猴头.glb); rebuild web_engine. - Harden lesson video recording pipeline; fix stale lesson-link E2E selector. - Add RE PBR derived libraries, lesson page, evidence and status report. Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-11-12 21:49:24 +08:00
parent a078648297
commit d5dd647881
276 changed files with 9632 additions and 314 deletions
--- a/docs/status/PBR_TUTORIAL.md
+++ b/docs/status/PBR_TUTORIAL.md
@@ -0,0 +1,72 @@
+# PBR 渲染初学者互动教程 (pbr)
+
+日期：2026-11-11
+状态：**功能实现并完成有头 Chromium 采集与聚焦 E2E；整体产品验收仍由用户执行**
+
+## 交付内容
+
+- 新应用内课程 `pbr`：`/?ui=web&tutorial=pbr`（落地页）/ `?ui=web&tutorial=pbr&start=1`（编辑器中）。
+- 13 步中文教程：
+  `intro` → `workspace-shading` → `load-studio` → `add-suzanne` → `add-cube` → `add-torus` →
+  `assign-metal` → `assign-glass` → `assign-wood` → `assign-emission` → `render-setup` → `download-save` → `summary`。
+- 教程演示动作走真实产品入口：工作区切换、按名选择、PBR 资产库追加模型/分配材质、打开课程摄影棚、
+  Web PBR 渲染、PNG 下载、工程保存。
+- React 接线：`TutorialContext` 增加 workspace/资产库/渲染结果；`TutorialApi` 增加工作区、选择、
+  资产追加、材质分配、打开场景、渲染、下载；`PbrRenderPanel` 支持外部请求与 `onRendered` 回传。
+
+## 资产与截图
+
+- 课程摄影棚：`web/app/public/tutorial/pbr/studio.blend`
+  - 相机 `PBR Studio Camera`、三点灯光 + Sun、深灰世界、地面；生成报告
+    `tests/golden/PBR_TUTORIAL-001/studio-build.json`。
+- 教程步骤截图（有头 Chromium 实际操作）：
+  `web/app/public/tutorial/pbr/landing.jpg`、`steps/<stepId>.jpg`、`steps/<stepId>-view.jpg`、
+  `steps/00-assembly.jpg`（13 步 × 2 + 2）。
+- 12 张材质对比成片：`web/app/public/tutorial/pbr/renders/<model>-<material>.{png,jpg}`
+  - 模型：Suzanne、Cube、Torus；材质：Metal Brushed、Glass、Wood、Emission Cyan。
+  - 这 12 张由桌面 Blender EEVEE 使用同一摄影棚/材质库渲染（`renderer: DESKTOP_BLENDER_EEVEE`），
+    因浏览器 WebGL2 路径当前对部分材质仍偏暗；教程步骤截图与交互操作仍是真实有头 Chromium。
+  - 生成脚本：`tools/web/generate-pbr-tutorial-renders.py`。
+- 采集报告：`tests/golden/PBR_TUTORIAL-001/headed-screenshots-latest.json`
+  （steps=13、renders=12、status=PASS）。
+
+## 脚本
+
+```bash
+# 生成课程摄影棚
+build_blender_native/bin/blender --background --factory-startup \
+  --python tools/web/generate-pbr-tutorial-studio.py -- \
+  web/app/public/tutorial/pbr/studio.blend \
+  tests/golden/PBR_TUTORIAL-001/studio-build.json
+
+# 生成 12 张材质对比参考图
+build_blender_native/bin/blender --background --factory-startup \
+  --python tools/web/generate-pbr-tutorial-renders.py -- \
+  web/app/public/tutorial/pbr/studio.blend \
+  web/app/public/assets/pbr-library/pbr-library.blend \
+  web/app/public/tutorial/pbr/renders
+
+# 有头 Chromium 采集教程步骤截图
+DISPLAY=:1 CHROME_PATH=/usr/bin/google-chrome \
+  node tools/web/capture-parts-tutorial-screenshots.mjs --course pbr --dev --port 5176
+
+# 校验采集产物
+node tools/web/check-pbr-tutorial-captures.mjs
+```
+
+## 验证结果
+
+- `node tools/web/check-pbr-tutorial-captures.mjs`：PASS（13 步截图齐全、12 张 PNG 1024×1024、
+  报告 status=PASS、studio SHA 一致）。
+- `web/tests/e2e/pbr-tutorial-accessibility.spec.ts`：通过（axe 无 critical/serious）。
+- `web/tests/e2e/wbv2-pbr-tutorial-production.spec.ts`：通过（13 步演示、资产库 20 卡片、
+  渲染结果、PNG/.blend 下载）。
+- `npm run typecheck`：通过。
+
+## 已知限制
+
+- 浏览器 WebGL2 PBR 渲染对部分材质（尤其金属/木色）偏暗；12 张教程成片改用桌面 Blender EEVEE
+  生成，标注为 `DESKTOP_BLENDER_EEVEE`。交互教程与步骤截图仍为真实有头 Chromium。
+- `PBR Wood` 当前为暖色哑光材质（无贴图节点），教程文案已同步为“暖色木质”，避免把未生效的
+  纹理链当作已验证功能。
+- 14 类节点之外的任意节点、动态纹理/对象信息、EEVEE/Cycles 像素级一致性不在本教程范围。
--- a/docs/status/RE_PBR_LIMITS_20261112.md
+++ b/docs/status/RE_PBR_LIMITS_20261112.md
@@ -0,0 +1,104 @@
+# RE 5000PBR 渲染已知限制：修补与验证记录
+
+日期：2026-11-12
+状态：**功能实现完成；有头 Chromium 聚焦验证通过；整体产品验收仍由用户执行**
+（`IMPLEMENTED_NOT_USER_ACCEPTED`）
+
+## 本轮决策
+
+- **Chromium 限定**：只做 Chromium 硬件 GPU 与 SwiftShader 对照；Firefox/WebKit 按仓库铁律不启动、不纳入验收。
+- **2048 高清验证 + 可选切换**：默认标准 1024/512；`re-pbr-hq` 2048 库按需加载，材质名带 `_HQ`。
+- **诊断视图 + 教学曝光**：保留原材质，增加 Final/Base Color/Normal/Roughness 与 0/+1/+2 EV。
+- **Displacement 渲染与交互视口都执行**：HEIGHT 绑定 + displacementMap；静帧有界细分，交互视口逐顶点位移。
+
+## 逐条结果
+
+### 1. Displacement / Height
+
+- 原生 reader：从 `Material Output.Displacement` 读取 `ShaderNodeDisplacement`，解析 Height 图、`Midlevel=0.5`、`Scale=0.001`；
+  输出 `usage:"HEIGHT"` binding 与 `displacementImageId/displacementMidlevel/displacementScale`。
+  同时改为从 packed JPEG/PNG 头读取真实尺寸（`gen_x` 只有 1024 时仍能识别 HQ 2048）。
+- 编译器：`DISPLACEMENT` 进入 allowlist；不再删除该节点；支持 `IMAGE_TEXTURE → DISPLACEMENT.Height`、
+  `DISPLACEMENT → OUTPUT.Displacement`、`VALUE/MATH → Scale/Midlevel`；HEIGHT binding 带 `scale/midlevel/uvTransform`。
+- Three.js：`applyMaterial` 设置 `displacementMap`、`displacementScale`、`displacementBias=-midlevel*scale`；
+  HEIGHT 强制 Non-Color，禁止回退到 BASE_COLOR；原生/编译 binding 按 usage 合并。
+- 几何：静帧渲染对 968 三角形猴头做 level 3 中点细分到 **61,952** 三角形；交互视口使用原几何逐顶点位移，
+  编辑模式不细分，避免破坏拾取。
+- 教学强度：1× 保留源 Scale；10×/100× 只乘渲染时 `displacementScale`，不写材质/.blend。
+- 证据：`tests/golden/RE-PBR-LIMITS-001/displacement/report.json`
+  （HEIGHT/scale/midlevel/bias、968→61,952、1×/100× PNG、mean 93.96/93.87、SHA 不同）。
+
+### 2. 深色材质
+
+- Rendering 面板增加“视图”：Final / Base Color / Normal / Roughness；只临时替换活动对象材质，地面保留 Final。
+- 教学曝光 0/+1/+2 EV 只调整渲染曝光，不改变材质数据。
+- 证据：`tests/golden/RE-PBR-LIMITS-001/diagnostics/report.json`（3 张诊断图、曝光差异 >1）。
+- 桌面 EEVEE 参考脚本本轮未运行；EEVEE 不把 Material Output.Displacement 当几何位移，
+  因此即使补参考也只用于颜色/灯光，不用于位移验收。
+
+### 3. 视口相机
+
+- 新增 `viewPreset`：`SCENE_CAMERA` 复用场景相机 `worldMatrix` 精确姿态；`COMPARISON` 以主体为中心
+  yaw + π/6、pitch +0.18、distance ×1.1。
+- PbrRenderPanel 增加“视角预设”；默认 SCENE_CAMERA；主视口 `ViewportNavigation` 不受影响。
+- 证据：最终 20 张采集 `uniqueSha=20`；SCENE/VIEWPORT 成片不再重复；
+  `tests/golden/RE-PBR-RENDER-001/report.json`。
+
+### 4. 重开 `ready:0:0`
+
+- 根因：重开时空 `textureAssets` 被当作 `textureExpected=false`，面板在 packed assets 到达前渲染并读取空状态；
+  另有 worker 完成时重盖章 snapshot revision、`setSnapshot` 重发旧 `lastTextureStatus`。
+- 修复：adapter 单调 `textureRevision` + `expectedAssets`；worker 丢弃旧上传、不重发旧状态；
+  `still` 回传 `textureStatus`；面板从 still/最新状态取数；空列表且 expected>0 时 `pending`；
+  `GPUTextureStore.upload(..., {replace})` 清旧纹理；PbrRenderPanel 对当前 snapshot 做一次自愈式 cache。
+- 证据：重开 E2E `data-texture-status=ready:5:0:`，`loaded===expected`；最终采集 reopen 同为 `ready:5:0:`。
+
+### 5. 硬件 GPU / 2048 / 跨浏览器
+
+- Playwright 与采集脚本支持 `GPU_MODE`/`--gpu hardware`；有头 Chromium 探测到
+  `ANGLE (NVIDIA Corporation, NVIDIA GeForce RTX 4060 Laptop GPU/PCIe/SSE2, OpenGL 4.5.0)`；
+  硬件 lane 若回退 SwiftShader/llvmpipe 失败关闭。
+- 同一 1024 材质：硬件 mean 95.277/std 44.758，SwiftShader mean 95.332/std 44.724；
+  硬件 E2E 27s，SwiftShader 参考 35.8s（`tests/golden/RE-PBR-LIMITS-001/gpu/batch0-gpu-enable.json`）。
+- 2048 HQ：`re-pbr-hq` 10.8 MB、6 个 `_HQ` 材质、原始 packed JPEG；原生 reader 直接读 packed JPEG 尺寸，
+  Height 图验证 2048×2048；GPU decoded 67,633,152 bytes（64.5 MiB）、payload 2,625,921 bytes、
+  loaded 5/rejected 0，低于 512 MiB。
+- 证据：`tests/golden/RE-PBR-LIMITS-001/hq/report.json`。
+- 跨浏览器：仓库规则 Chromium-only，Firefox/WebKit 未运行，记为 policy-excluded，不是工程缺口。
+
+## 验证结果
+
+| 检查 | 结果 |
+| --- | --- |
+| `npm run typecheck` | 通过 |
+| `node --test tests/unit/shader-compiler.test.mjs` | 13/13 通过（含 HEIGHT/DISPLACEMENT/Value→Mapping） |
+| 有头 E2E 主流程（6 材质、位移 1×/100×、诊断、曝光、相机、重开） | 通过（3.6m） |
+| 有头 E2E 截断 GLB 负例 | 通过 |
+| 有头 E2E 原生 HEIGHT binding | 通过（scale 0.001、midlevel 0.5） |
+| 有头 E2E HQ 原生 2048 尺寸 | 通过（Height 2048×2048） |
+| 有头 E2E HQ 按需加载与渲染 | 通过（67,633,152 bytes、ready:5:0） |
+| `check-re-pbr-limits.mjs` | PASS（位移/诊断/HQ/GPU/相机/重开） |
+| 最终有头硬件采集 | 20/20、uniqueSha 20、15 steps、0 errors |
+| `check-re-pbr-lesson.mjs` | PASS |
+| `check-re-pbr-library.mjs --hq` | PASS（10.8 MB、6 材质、2048） |
+| PBR 资产库回归（有头硬件） | 2/2 通过 |
+| PBR 教程回归（有头硬件） | 通过（48.3s） |
+
+## 证据路径
+
+- 位移：`/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-LIMITS-001/displacement/`
+- 诊断/曝光：`/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-LIMITS-001/diagnostics/`
+- HQ 2048：`/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-LIMITS-001/hq/`
+- GPU 启用：`/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-LIMITS-001/gpu/batch0-gpu-enable.json`
+- 20 张硬件成片：`/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-RENDER-001/`
+- 统一检查器：`/home/mes123456/workinf_Blender_Wasm/tools/web/check-re-pbr-limits.mjs`
+- 教案：`/home/mes123456/workinf_Blender_Wasm/web/app/public/tutorial/pbr/render-lesson.html`
+
+## 未验证 / 限制
+
+- 源 Displacement Scale=0.001；1× 很细微，100× 是教学放大，不代表源材质变强。
+- 静帧细分到 61,952；交互视口是原几何逐顶点位移，未做交互细分。
+- 未生成桌面 EEVEE 参考；EEVEE 不作为位移参考。
+- 2048 HQ 的 mipmap 可能使实际显存比 base-level 预算高约 1/3；仅按需加载。
+- 硬件 GPU lane 依赖 `DISPLAY=:1` 和 NVIDIA 驱动；无独显时需显式 SwiftShader。
+- 未做 Firefox/WebKit；用户实际使用验收仍待执行。
--- a/docs/status/RE_PBR_RENDER_20261111.md
+++ b/docs/status/RE_PBR_RENDER_20261111.md
@@ -0,0 +1,127 @@
+# Web Blender：RE 5000PBR × 猴头 GLB 渲染与初学者 HTML 教案
+
+日期：2026-11-11
+状态：**功能实现完成；有头 Chromium 聚焦验证通过；整体产品验收仍由用户执行**
+后续：已知限制的修补与验证见 [`RE_PBR_LIMITS_20261112.md`](RE_PBR_LIMITS_20261112.md)。
+（`IMPLEMENTED_NOT_USER_ACCEPTED`）
+
+## 交付内容
+
+### 1. RE 5000PBR 派生资产库
+
+- `tools/web/generate-re-pbr-library.py`：从
+  `re/5000PBR精简版/5000+ PBR catalog.blend` 的工作副本派生 6 个材质；标记 5 个已标记材质 +
+  未标记的 `Black_Anti_Slip_grip`；统一挂到 `Materials/RE5000PBR` catalog。
+- 保留原节点图（`FRAME`、`REROUTE`、`DISPLACEMENT`、`MAPPING`、`VALUE` 与四张 `IMAGE_TEXTURE`），
+  只把贴图降采样：Base Color/Normal 1024²，Roughness/Height 512²，并重新 pack 为 JPEG。
+- 产物：`web/app/public/assets/re-pbr/`
+  - `re-pbr-library.blend`：6 个 MATERIAL，SHA-256 `d67f5a058c154626dfc7171c5bc7fc254b8ee183fea8740261b9711b3309d782`。
+  - `manifest.json`、`preview-manifest.json`、`desktop-canonical.json`、`blender_assets.cats.txt`、
+    6 张 256² 预览。
+  - 库大小 3.7 MiB，packed 贴图约 3.06 MiB（源 10.7 MiB）。
+- `tools/web/check-re-pbr-library.mjs`：校验 6 个材质、预览、SHA、尺寸、JPEG 格式、色彩空间，
+  并只读复检节点图仍包含 `FRAME/REROUTE/DISPLACEMENT/MAPPING/VALUE` 与四张贴图。
+
+### 2. 多库播种与合并（资产面板 20 个资产）
+
+- `web/protocol/asset-catalog-v2.ts`：新增 `mergeAssetCatalogManifests`，按 catalog/asset/library id
+  去重追加、bump revision 并重新校验。
+- `web/app/src/storage/asset-catalog-store.ts`：新增 `mergeAssetCatalogManifest`，事务内重读原始行、
+  检测 revision 漂移、更新/删除预览回执，避免旧回执失效。
+- `web/protocol/storage.ts`、`StorageClient.ts`、`storage.worker.ts`：新增合并命令；
+  seed/读取 manifest/预览的客户端超时提高到 30–60 s。
+- `web/app/src/app/pbr-library-seed.ts`：`PBR_LIBRARY_SOURCES` 支持
+  `pbr-essentials-v1`（14）与 `re-pbr-v1`（6）；首装先 seed 主库，再对缺失库
+  `seed(repair=true)` + merge；单库失败只降级该库并保留既有资产。
+- `AssetLibraryPanel.tsx`：卡片补 `data-testid`/`data-asset-id`/`data-library`；新增“资产来源”筛选；
+  缩略图改为 eager，20 张预览全部加载。
+- 既有 PBR 教程/测试的资产数从 14 更新到 20；PBR 教程原有 12 张渲染矩阵保持不变。
+
+### 3. 渲染正确性修复
+
+- **快照后重绑纹理与环境**：`viewport-render.worker.ts` 拆分
+  `reapplyCurrentTextures()`（只从已上传 store 重绑）与 `applyTextureAssets()`（upload + 重绑）；
+  `setSnapshot` 末尾重绑，不再在每次分配材质时重新解码全部贴图。
+- **HDRI 背景保护**：只有 world 确有环境贴图时才让 `applyEnvironment` 覆盖背景，
+  flat world color 不再覆盖已应用的 HDRI。
+- **纹理就绪屏障**：`offscreen-viewport.ts` 增加按 snapshot revision 对齐的
+  `whenTexturesReady()`；`renderStill` 等待纹理与环境应用完成；空纹理也明确回传状态。
+  面板用该屏障替换固定 150 ms 延时。
+- **原生 reader**：`web_engine_blend_reader.cpp` 不再把
+  `NodeReroute/NodeFrame/ShaderNodeDisplacement` 统一映射为 `UNSUPPORTED`，而是输出
+  `REROUTE/FRAME/DISPLACEMENT`。
+- **编译器归一化**：`compileMaterialGraph` 渲染路径与 `compileShaderGraph` 共用
+  `normalizeShaderGraph`：折叠 REROUTE、移除 FRAME、删除 DISPLACEMENT 节点及全部连线；
+  对不含这些节点的图严格 no-op。
+- **编译器扩展**：支持 `IMAGE_TEXTURE → Roughness/Metallic/Alpha`、`IMAGE_TEXTURE →
+  SEPARATE_COLOR`、`VALUE → MAPPING.Scale/Rotation/Location`（标量广播）；Mapping 的
+  `uvTransform` 与原生 `textureBindings` 按 usage 合并，不再被原生绑定覆盖。
+- `SceneIR` 运行时校验同步允许 `REROUTE/FRAME/DISPLACEMENT`。
+- `App.tsx` 的材质分配在对象无槽时用 `slotIndex=-1` 追加槽，避免先创建空白材质导致
+  `name.001` 冲突；重开工程后材质槽保留。
+- `web/app/public/engine-manifest.json` 的 `single` 变体改指向重新构建的
+  `/vendor/blender/web_engine.{js,wasm}`，修复旧的 `vendor/blender/single/web_engine.wasm`
+  哈希不匹配（`MANIFEST_REJECTED`）。
+
+### 4. 有头 Chromium 测试与 20 张成片
+
+- `web/tests/e2e/re-pbr-render-workflow.spec.ts`：
+  - 打开摄影棚 → 导入 `monkey-head.glb` → Shading 20 卡/6 个 RE 材质 → 逐个分配 6 材质 →
+    材质球 `COMPILED` → 1024/场景渲染 → `data-texture-status` ready → PNG 下载 →
+    保存 .blend → 重开并确认材质槽仍存在。
+  - 截断 GLB 负例：对象数不变。
+- `tools/web/capture-re-pbr-lesson.mjs`：有头 Chromium（`headless:false`）生成
+  - `tests/golden/RE-PBR-RENDER-001/renders/*.png`：6 材质 ×（1024 场景 + 1024 视口 + 512 场景）
+    + 未分配基线 + 保存重开复渲染 = 20 张；
+  - `web/app/public/tutorial/pbr/lesson/renders/*.jpg` 与 `steps/*.jpg`、`landing.jpg`；
+  - `report.json`（尺寸、SHA、mean/std、textureStatus、材质、相机、浏览器/DISPLAY）。
+- `tools/web/check-re-pbr-lesson.mjs`：PASS（20 张、6 材质 SHA 两两不同、基线不同、
+  PNG 尺寸、textureStatus ready、GLB SHA、教案 HTML 无 inline script/style/on*、无远程 URL、
+  所有图片存在）。
+
+### 5. 初学者 HTML 教案
+
+- `web/app/public/tutorial/pbr/render-lesson.html` + `render-lesson.css`
+  - 12 节：目标、术语、准备、导入 GLB、资产库、六种材质逐课、渲染设置、下载/保存/重开、
+    20 张矩阵、黑图排查、限制、附录。
+  - 静态 HTML；外链 CSS；无 inline `<style>`/`<script>`/`on*`；同源图片；打印样式。
+  - 所有截图来自本次有头 Chromium 实际操作；20 张成片全部标注 Web/WebGL2。
+- React 入口：
+  - `PbrLessonPanel.tsx` 挂在 Rendering 工作区：打开图文教案、载入练习摄影棚、导入猴头 GLB、
+    显示 20 资产 / 6 个 RE 材质。
+  - `TutorialCourse.lessonUrl`；PBR 落地页导航增加“渲染图文教案”；帮助菜单增加“PBR 渲染教案”。
+
+## 验证结果
+
+| 检查 | 结果 |
+| --- | --- |
+| `node tools/web/check-re-pbr-library.mjs` | PASS（6 材质、6 预览、SHA/尺寸/JPEG/节点图） |
+| `node --test web/tests/unit/shader-compiler.test.mjs` | 13/13 通过（含 REROUTE/FRAME/DISPLACEMENT、Value→Mapping、Roughness/Metallic 新用例） |
+| `npm run typecheck` | 通过 |
+| `npm run build` | 通过 |
+| `npx playwright test --headed tests/e2e/re-pbr-render-workflow.spec.ts` | 2/2 通过（有头 Chromium） |
+| `npx playwright test --headed tests/e2e/pbr-asset-library-production.spec.ts tests/e2e/wbv2-pbr-tutorial-production.spec.ts` | 3/3 通过（20 资产回归） |
+| `node tools/web/check-re-pbr-lesson.mjs` | PASS（20 张 / 15 步 / 6 材质 / 基线均值 94.60） |
+| 部署服务器 + 有头 Chromium 打开 `render-lesson.html` | 标题、35 张图片（eager/decode 后）全部加载；无 4xx；CSP 头生效 |
+
+## 证据路径
+
+- 20 张渲染：`/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-RENDER-001/renders/`
+- 采集报告：`/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-RENDER-001/report.json`
+- 教案：`/home/mes123456/workinf_Blender_Wasm/web/app/public/tutorial/pbr/render-lesson.html`
+- 教案截图：`/home/mes123456/workinf_Blender_Wasm/web/app/public/tutorial/pbr/lesson/`
+- 派生库：`/home/mes123456/workinf_Blender_Wasm/web/app/public/assets/re-pbr/`
+- GLB fixture：`/home/mes123456/workinf_Blender_Wasm/tests/files/web/pbr-render-lesson/monkey-head.glb`
+  （SHA-256 `60267d607b63ceb5bfc972342a9ff17310d6978ff632f240ecb963c4d5a7e003`）
+- 引擎 wasm：`web_engine.wasm` SHA-256 `909290259e2911af49f1d6f308e1e05e01f62aa1841847b878bcd3191b98c24c`
+
+## 已知限制 / 未验证项
+
+- Web 渲染器不执行 Displacement；Height 贴图保留但不产生位移。
+- 六种 RE 材质都是深色砖石/防滑表面；成片整体偏暗是材质本身，不是黑图。
+- 当前视口相机默认与场景相机对齐，所以 1024 场景/视口成片可能相同；移动视口后再渲染即可看到差异。
+- 保存重开后 `data-texture-status` 的诊断字符串曾出现 `ready:0:0`（图像本身与保存前一致）；
+  这是诊断计数时序问题，已记录，不影响重开渲染结果。
+- 派生贴图为 1024/512；未做 2048 原始贴图对照。
+- 未做硬件 GPU（非 SwiftShader）对照、Firefox/WebKit、移动端。
+- 未验证用户实际使用验收；不把本次单测/E2E/采集 PASS 当作整体产品验收。
--- a/docs/status/RE_PBR_RENDER_20261112.md
+++ b/docs/status/RE_PBR_RENDER_20261112.md
@@ -0,0 +1,140 @@
+# RE 5000PBR × 猴头 GLB：渲染全面测试、HTML 教案与中文配音视频
+
+日期：2026-11-12
+状态：**功能实现完成；聚焦验证通过；整体产品验收仍由用户执行**
+（`IMPLEMENTED_NOT_USER_ACCEPTED`）
+
+## 本轮目标与范围
+
+用户要求：在 Web Blender 中使用 `/home/mes123456/workinf_Blender_Wasm/re/5000PBR精简版`
+的资产，对 `/home/mes123456/workinf_Blender_Wasm/re/猴头.glb` 做渲染功能全面测试；把操作过程截屏写成
+初学者 HTML 教案；制作完整中文配音视频；发现的缺口按桌面 Blender 源码修 Web 移植，UI 缺口用 React；
+需要时本地重编 WASM；全部使用绝对路径。
+
+用户确认的范围：
+
+- **只修实测阻塞**，不新增标准渲染设置 UI（宽高比、采样、透明背景、HDRI）。
+- **只测 WebGL2 PBR**，不纳入本地原生 EEVEE/WASM（F12）或服务端 Blender。
+
+前序批次已交付 RE 5000PBR 派生库、HTML 教案、20 张成片和 15 张操作截图；本轮补齐缺失的视频链路，
+并修复实测暴露的一个真实导入缺口。
+
+## 交付物
+
+### 1. 中文配音视频（本轮新增）
+
+| 项目 | 路径 / 值 |
+| --- | --- |
+| MP4 | `/home/mes123456/workinf_Blender_Wasm/web/app/public/tutorial/pbr/lesson/video/re-pbr-lesson-720p.mp4` |
+| 字幕 | `/home/mes123456/workinf_Blender_Wasm/web/app/public/tutorial/pbr/lesson/video/re-pbr-lesson.zh-Hans.vtt` |
+| 封面 | `/home/mes123456/workinf_Blender_Wasm/web/app/public/tutorial/pbr/lesson/video/poster.jpg` |
+| 时长 | 667.04 s（11:07），13 章 |
+| 编码 | H.264 / AAC，1280×720，faststart |
+| MP4 SHA-256 | `6a5b3b51c52945d0594a984ad6b5ff2e557ec319c574679673bd8d6d2a8a2916` |
+| 旁白混音 SHA-256 | `adc2658938ad48b278aa434cb9635343491f7241f4632b4af6c9baa9271b9220` |
+| VTT SHA-256 | `4199af3a9c1ad501ebd7832e43693d43d2bbd30a646a8285343eefc08a237aa3` |
+| 封面 SHA-256 | `6461410e032de2c92f3f898873d9dca9834f2538e65cd0e4b2d8f3c443d0f444` |
+| 旁白 | `zh-CN-XiaoxiaoNeural`，13 章，13 条 VTT cues |
+| 章节截图 | `/home/mes123456/workinf_Blender_Wasm/web/app/public/tutorial/pbr/lesson/video-steps/*.jpg`（13 张，1600×900） |
+| 录制证据 | `/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-VIDEO-001/{screencast.webm,timeline.json,record-report.json,narration/,diagnostics/}` |
+
+视频由有头 Chromium（`DISPLAY=:1`）真实操作录制，GPU 探测为
+`ANGLE (NVIDIA Corporation, NVIDIA GeForce RTX 4060 Laptop GPU/PCIe/SSE2, OpenGL 4.5.0)`。
+章节：开场、载入摄影棚、导入猴头 GLB、认识 Shading/RE 资产库、分配六种材质、设置渲染、
+渲染与下载 PNG、保存与重开、诊断视图与教学曝光、位移与细分、对比视角、高清 2048 贴图、总结。
+
+### 2. HTML 初学者教案
+
+`/home/mes123456/workinf_Blender_Wasm/web/app/public/tutorial/pbr/render-lesson.html`
+ `render-lesson.css`。13 节，75 个同源引用，**0 个断链**；包含真实操作截图、六种材质逐课、
+20 张成片矩阵、黑图排查表和限制说明。视频、字幕、封面已嵌入。
+
+### 3. 全面渲染测试证据（当前 wasm 重跑）
+
+| 项目 | 路径 / 值 |
+| --- | --- |
+| 20 张成片 | `/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-RENDER-001/renders/*.png` |
+| 采集报告 | `/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-RENDER-001/report.json` |
+| 报告结果 | `status=PASS`、20 renders、15 steps、0 errors、20 个唯一 SHA |
+| GPU | `ANGLE (NVIDIA Corporation, NVIDIA GeForce RTX 4060 Laptop GPU/PCIe/SSE2, OpenGL 4.5.0)` |
+| GLB SHA-256 | `60267d607b63ceb5bfc972342a9ff17310d6978ff632f240ecb963c4d5a7e003`（`re/猴头.glb`） |
+| 纹理状态 | 基线 `ready:1:0:`；六材质 `ready:5:0:`；重开 `ready:5:0:` |
+| 材质编译 | 六个 RE 材质均 `COMPILED` |
+| 当前 wasm | `/home/mes123456/workinf_Blender_Wasm/web/app/public/vendor/blender/web_engine.wasm` SHA-256 `31550b374cc0127c9b5468cebe65be37b8558c1604a28e99ec73a34be96c13f3` |
+
+矩阵：基线 1024；6 材质 ×（1024 场景 + 1024 视口 + 512 场景）；保存/重开后复渲染。
+进阶证据沿用 `/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-LIMITS-001/`：
+位移 1×/100×（968 → 61,952 三角形，mean delta 0.087）、诊断视图 3 张、+2 EV、对比视角、
+HQ 2048（10.8 MB 库，67,633,152 bytes 解码）；`check-re-pbr-limits.mjs` 本轮 PASS。
+
+## 本轮修复的真实缺口
+
+### 非 ASCII 文件名 GLB 导入失败（P0，已修复）
+
+- **现象**：用真实文件入口打开 `/home/mes123456/workinf_Blender_Wasm/re/猴头.glb` 时，对象数保持 6，
+  控制台报 `RuntimeError: Error: Please select a file`；ASCII 夹具 `monkey-head.glb` 正常。
+- **根因**：`/home/mes123456/workinf_Blender_Wasm/blender-5.2.0/source/blender/web_engine/web_engine_main_state.cpp`
+  的 `web_engine_blend_main_obj_io()` 原先把浏览器传来的原始文件名直接作为 Emscripten 虚拟文件系统的暂存名。
+  `猴头.glb` 的 UTF-8 文件名在 WASM 侧的 VFS 路径解析中不可用，glTF 导入器拿到不可解析路径后报
+  “Please select a file”。
+- **修复**：暂存到磁盘的文件名把非 ASCII 字节替换为 `_`（例如 `______.glb`），扩展名与 ASCII 文件名保持不变；
+  UI 仍显示浏览器提供的原始文件名。桌面 Blender 本身支持 UTF-8 路径，本修复只影响 Web 的 WASM 暂存层。
+- **构建**：`cmake --build /home/mes123456/workinf_Blender_Wasm/build_web_blender6 --target web_engine -j8`
+  → `node /home/mes123456/workinf_Blender_Wasm/tools/web/sync-web-engine-runtime.mjs`；
+  新 wasm SHA-256 见上表。
+- **验证**：视频“导入猴头 GLB”章节真实导入成功，状态栏 `Engine: GLB imported r2 (7 objects)`，
+  活动对象 Suzanne；20 张采集报告 `glbSha256` 与 `re/猴头.glb` 一致。
+
+### 视频录制脚本阻塞（工具链，已修复）
+
+- `tools/web/record-re-pbr-lesson-video.mjs` 原先的 `openStudio()` 依赖面板按钮路径，失败时不会回退；
+  失败前不保存视频/时间线。本轮增加：`--out` 生效、只清理 `screencast.webm`、保留原始 webm、
+  服务器退出检测、面板不可用时回退到 `[data-testid="blend-file-input"]`、保存对话框处理、
+  每章失败截图与部分时间线保留、失败时仍保存视频、硬件 GPU 回退即失败、时长 7–12 分钟守卫。
+- 验证：13 章完整录制 `status=PASS`、0 errors、667.04 s。
+
+### E2E 文案漂移（测试修正，非产品缺口）
+
+- `web/tests/e2e/re-pbr-render-workflow.spec.ts` 仍按旧文案“打开图文教案”查找链接；面板现为
+  “打开图文/视频教案”。已改为正则 `/打开图文/`，主流程用例重跑通过（3.6 分钟）。
+
+## 验证结果
+
+| 检查 | 结果 |
+| --- | --- |
+| `node tools/web/check-re-pbr-library.mjs` | PASS（6 材质、6 预览、3,707,202 bytes） |
+| `node tools/web/check-re-pbr-library.mjs --hq` | PASS（6 材质、10,846,909 bytes、2048） |
+| `node tools/web/check-re-pbr-lesson.mjs` | PASS（20 renders、15 steps、6 材质、0 断链） |
+| `node tools/web/check-re-pbr-limits.mjs` | PASS（位移/诊断/HQ/GPU/重开） |
+| `node tools/web/check-re-pbr-video.mjs` | PASS（13 章、13 cues、667.04 s、1280×720、faststart） |
+| 有头 E2E `re-pbr-render-workflow.spec.ts` | **5/5 通过**（6.8 分钟；主流程 6.3 分钟，截断 GLB 负例、HEIGHT 位移、HQ 按需加载、HQ 2048 尺寸均通过） |
+| 20 张采集 | PASS（20/20、unique SHA 20、0 errors、RTX 4060） |
+| 教案引用 | 75/75 存在，0 断链，无远程 URL |
+| 教案页面冒烟（Chromium，dev） | 56 张图片全部解码、视频 `duration=667.04`/`readyState=4`、VTT 200 + 13 cues、无 4xx |
+| 生产构建 | `npm run build` PASS（typecheck + vite build；`web/dist` 含视频、字幕、poster、13 张章节截图、新 wasm） |
+| 教案页面冒烟（生产 dist + 部署服务） | 56 张图片全部解码、视频 667.04 s、VTT 13 cues、无 4xx |
+| 视频音频 | AAC 单声道 48 kHz；`volumedetect` mean −23.4 dB、max −2.6 dB（非静音） |
+
+## 未验证 / 限制
+
+- Web 渲染是 three.js WebGL2 PBR（`physical-v1`），不是 EEVEE/Cycles 路径追踪；玻璃/金属/折射/GI
+  与桌面物理精度不同。本机原生 EEVEE/WASM（F12）与服务端 Blender 未验证。
+- 六种 RE 材质都是深色砖石/防滑表面，整体偏暗是材质本身；用诊断视图和教学曝光判断，而不是只看亮度。
+- 标准渲染设置 UI（非方形宽高比、采样/抗锯齿、透明胶片、HDRI/世界环境编辑）未在本轮补齐；
+  用户选择“只修实测阻塞”，这些记录为已知限制。
+- HQ 2048 为按需加载；mipmap 可能使实际显存比 base-level 预算高约 1/3。
+- 按仓库策略只验证 Chromium；Firefox/WebKit、移动端未运行。
+- 视频旁白按 13 章覆盖操作步骤；材质原生追加、PBR 渲染、HQ 加载的等待段保留真实耗时，
+  部分章节为静默操作画面（未做变速剪辑），这是为了不伪造操作时延。
+- 未做用户实际使用验收；本轮的检查器/E2E/录制 PASS 不等于整体产品验收。
+
+## 证据路径
+
+- 视频：`/home/mes123456/workinf_Blender_Wasm/web/app/public/tutorial/pbr/lesson/video/`
+- 视频章节截图：`/home/mes123456/workinf_Blender_Wasm/web/app/public/tutorial/pbr/lesson/video-steps/`
+- 教案：`/home/mes123456/workinf_Blender_Wasm/web/app/public/tutorial/pbr/render-lesson.html`
+- 20 张成片与报告：`/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-RENDER-001/`
+- 视频录制/混音证据：`/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-VIDEO-001/`
+- 进阶限制证据：`/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-LIMITS-001/`
+- 本轮源码修复：`/home/mes123456/workinf_Blender_Wasm/blender-5.2.0/source/blender/web_engine/web_engine_main_state.cpp`
+- 录制脚本：`/home/mes123456/workinf_Blender_Wasm/tools/web/record-re-pbr-lesson-video.mjs`