pelican-engine 0.0.0-stage → 0.3.1

package/docs/DECISIONS.md

@@ -0,0 +1,107 @@
+# 需求决策记录
+
+日期：2026-11-04。状态：M0–M2 已发布，M3 开发中；本次范围变更新增 npm 开发分发、WebGL2 后端回退和面向 1.0 的性能策略。
+
+本文件记录用户已经确认的产品要求。后续技术设计可以调整实现方法，不能自行删除目标、降低能力或将建议升级为使用限制。原对话中的纠正以本文件最终表述为准。
+
+## 产品定位
+
+`Pelican Engine`（鹈鹕游戏引擎）是面向 100% 外部 AI 开发的开源、代码优先、高质量游戏引擎，原名 threecat。人提出需求、约束和反馈；技术执行由外部 AI 完成。引擎研发者与游戏作者可以是不同用户。游戏运行时没有大模型或 AI 智能体。
+
+选择路线 C：编译型 TypeScript SDK。引擎以 Three.js 的 WebGPU 能力为图形基础，完整封装底层；公开受控材质、后处理和 GPU 计算接口。游戏项目遵循公开接口开发，生态规范不等于防篡改。
+
+## 已确认决策
+
+| ID | 确认结果 | 对实现和验收的影响 |
+| --- | --- | --- |
+| D01 | 只面向桌面浏览器游戏 | 不建设原生安装包或移动端首发适配；玩家端不设置拦截白名单，见 D16 |
+| D02 | 单机、关卡制第三人称动作冒险为首个完整样板，尽量覆盖更多系统 | 完整玩法闭环、专项能力场景和压力场景三层验证；不限制引擎题材 |
+| D03 | 主流独立显卡电脑为性能基线 | M0 记录实际硬件；不以旗舰卡代替基线，不承诺集显性能；不是玩家门槛 |
+| D04 | 原生 1920×1080、60 FPS、高画质档为核心性能目标 | 基准不靠动态分辨率或超分达标；画质独立验收；光追/PT 各模式按明确负载测量，不虚构全模式统一性能保证 |
+| D05 | 首发游戏开发语言为 TypeScript，声明式定义加受控逻辑系统 | 不另造通用文本语言；声明、玩法代码和 GPU 图分别定义编译规则，不自动把任意 TS 变成 GPU 程序 |
+| D06 | 引擎与游戏开发、测试、维护均由外部 AI 完成，人只提需求与反馈 | 不以人工点击编辑器、编码、修图或排错作为必要流程；独立 AI 使用验收 |
+| D07 | AI 只用于开发流程，不发展游戏运行时模型调用 | 不规划运行时大模型/智能体模块；NPC 决策是普通程序逻辑 |
+| D08 | 允许开发者自由使用外部服务、已有资产和程序化生成 | 服务选择、调用和生产流程属于开发者；引擎处理离线资产，不管理生成服务平台 |
+| D09 | 首发完整单机，多人联机后续独立阶段 | 不以网络同步为首发依赖；基础状态与实体契约需清晰，不承诺加网络即变多人 |
+| D10 | 游戏开发只用公开 API，不修改或绕过引擎 | 通过完整扩展接口、文档和常规检查统一生态；不是安全沙箱、防篡改、封禁或许可限制 |
+| D11 | 开放受控材质、后处理、GPU 计算 | 使用引擎自有强类型 API；不暴露 Three.js/TSL、GPUDevice，不直接提交任意 WGSL/GLSL |
+| D12 | 产品统一更名 Pelican Engine（鹈鹕游戏引擎），GitHub 保留当前所有者、仅仓库改名 pelican-engine，npm 单包 pelican-engine、bin pelican | 正式仓库为 danchar12138/pelican-engine，不创建或迁移组织；单包内含 SDK/runtime/renderer/编译器/CLI；游戏只 import "pelican-engine"；npm i -D pelican-engine 后 npx pelican dev 即可上手；仓库/ZIP/npm 共用同一公开 API、CLI、AI 文档及能力，无需引擎源码或平台账号 |
+| D13 | Git、ZIP、本地目录均可使用；游戏可在引擎内或其他目录 | 不依赖 `.git`、硬编码路径或目录名；外部目录项目明确引用引擎路径；ZIP 可以由 AI 解压 |
+| D14 | 允许首次自动联网准备环境和锁定依赖 | 不依赖人工管理员操作；缓存和资产齐备后日常开发、测试、构建可离线 |
+| D15 | 研发和游戏开发环境仅 Windows | 初始化、工具和自动化围绕 Windows 验证，不承担 macOS/Linux 开发流程 |
+| D16 | Pelican Engine 玩家端不限定系统、浏览器或版本；优先 WebGPU，允许 Three.js 内置 WebGL2 回退 | 使用 WebGPURenderer 的 getFallback → WebGLBackend，不手动强制 WebGPUBackend，不因缺少 navigator.gpu 直接失败；不主动降画质，compute/path/hybrid/降噪不可用时给明确错误码及可用模式，状态和诊断显示实际后端；npm 与仓库运行行为一致 |
+| D17 | 3D 为核心，同时正式覆盖 2D、2.5D 和完整游戏 UI | 提供一致的场景、资源、输入、生命周期和测试基础；不要求 AI 从原语重造完整系统 |
+| D18 | 不配置生成服务也能制作完整可玩游戏；质量上限不能被基础素材限制 | 提供基础资产和程序化接口；高质量成果可来自高质量外部资产、服务或自行生成，均不限制 |
+| D19 | 大型连续场景和无缝流送纳入首发 | 分块、异步加载卸载、预取、引用、状态恢复、驻留和精度管理均需验证 |
+| D20 | 可复现运行与调试是基础能力 | 可控时间、随机源、输入录放、快照、诊断和自动验证；相同受控环境可复现，跨环境用容差，不强求逐位一致 |
+| D21 | 终端命令、文件和结构化结果是标准入口 | 不要求特定 AI 平台或 MCP；支持运行态查询、控制、截图和长任务管理；适配器仅可选 |
+| D22 | 高质量光栅、真实光追混合渲染和全路径追踪全部正式支持 | 能力与性能分别验收；屏幕空间近似不能冒充真实场景光追；不得用帧率目标取消高质量组件 |
+| D23 | 全路径追踪支持动态可交互玩法 | 移动相机、运动物件、动画角色和动态几何进入验收；静态累积或拍照演示不够 |
+| D24 | 布料、绳索、软体和流体首发支持可交互模拟 | 包括力、约束、碰撞、查询、渲染同步和相应跨系统验证，不只是视觉效果 |
+| D25 | 动画同时覆盖实时玩法和电影化过场 | 骨骼、混合、分层、状态机、根运动、IK、重定向、Morph、预制口型和代码时间轴等 |
+| D26 | 提供通用机制、玩法模块和可修改参考实现 | 属性、事件、状态等核心机制；背包、装备、技能、战斗、任务、对话、制作、交易等可组合，不固定规则 |
+| D27 | 程序化世界和运行时环境修改纳入首发 | 生成、建造拆除、物件破坏、地形修改，并同步渲染、光追、物理、导航、流送、存档 |
+| D28 | NPC 与导航覆盖地面、飞行、水中和动态环境 | 感知、行为树/状态机/效用决策、避障、群体、动态规划及可解释诊断 |
+| D29 | 完整应用级游戏 UI 纳入首发 | 布局、虚拟列表、主题、输入法、文本、本地化、焦点、手柄、世界 UI、可访问性和自动测试 |
+| D30 | 完整游戏音频体系纳入首发 | 空间、遮挡混响、总线、并发、互动音乐、事件联动、流式播放、过场同步与可测试性 |
+| D31 | 完整能力按需编译、加载 | 模块/资产/变体依赖分析、分包、动态引用声明、构建解释；不无条件启动全部高级模块 |
+| D32 | 增量编译与安全热更新是基础能力 | 追踪依赖、明确状态保留策略、兼容则更新、不兼容则明确重载；冷启动测试仍必需 |
+| D33 | 自有代码 MIT，第三方和用户内容分别管理 | 维护许可和来源记录；开发规范不追加修改源码禁令 |
+| D34 | 项目锁定引擎版本，显式迁移、验证与恢复 | ZIP 也能识别版本；API、内容、存档、回放分别管理兼容性；无法自动迁移则输出具体任务 |
+| D35 | 可重复验收证据是完成条件 | 接口、示例、边界、跨系统、资源生命周期、干净复测和无上下文 AI 验收；占位不算完成 |
+| D36 | 首个研发里程碑是四条高风险原型 | 编译链路、动态渲染、交互模拟、外部 AI 闭环；先有证据，再锁定架构与底层依赖 |
+| D37 | 按里程碑和质量门禁推进，默认无必须付费依赖 | 不编造日期；额外费用说明用途/成本/替代后由用户决定；不约束未来开发者工具选择 |
+| D38 | 构建输出 `dist/`，发布到 Web 服务器运行 | 独立静态产物、路径/资源地址/分包配置，无引擎在线服务依赖；不是要求 file:// 打开 |
+| D39 | 允许主线 AI 统筹、多研发 AI 分工并行 | 明确写入范围、接口与任务依赖，主线集成验收；单 AI 也能顺序完成，不建设必需协作平台 |
+| D40 | 每个里程碑验收后，在同一交付节点提交、推送、标记版本并发布 Release；提交消息采用行业标准结构与中文描述 | 使用 Conventional Commits，例如 feat(m0): 完成首个里程碑风险原型与自动验收；不提前零散推送，远程失败按实际状态恢复，不强推或覆盖发布 |
+| D41 | 正式支持 npm 安装后在任意空目录开发、构建和部署，无需引擎仓库或源码 | 仓库、ZIP、目录和 npm 共用一套 API、工具协议、AI 入口、能力索引和诊断；依赖安装后可离线开发、构建与运行；不破坏既有工作流 |
+| D42 | npm 包为可校验版本的编译分发物 | 不含源码映射、证据、示例、游戏资产；附 MIT 与第三方许可声明；引擎/API/项目版本不匹配给稳定错误码及修复建议；误用内部依赖有确定诊断 |
+| D43 | npm 发布纳入同一已验收里程碑的提交、标签、Release 节点，由 CI 自动执行 | 不单独提前发布；以干净 Windows 空目录、无引擎仓库的安装到静态部署及真实 GPU 出画面验收；发布凭据和包名条件按实际状态报告 |
+| D44 | WebGL2 回退不主动降低画质，也不伪装功能 | 不自动降低采样、分辨率、灯光、材质或后处理；path/hybrid/降噪等 compute 依赖在 WebGL2 下明确拒绝并提示可用模式，保持原状态，不崩溃、不静默转光栅 |
+| D45 | 后端身份可观测，WebGPU 与回退测试分开 | 状态栏及诊断显示 WebGPU 或 WebGL2；主里程碑仍需真实 WebGPU 硬件证据；WebGL2 单列出画面、模式切换、错误码、资源生命周期及上下文丢失浏览器实测 |
+| D46 | 尽快完成 1.0，性能目标为测量与优化方向而非僵硬发布门槛 | 保留 D03/D04 基线及诚实性能数据；不靠降画质掩盖成本，不因固定 FPS 数字阻断可用能力交付；正确性、真实渲染、资源安全和不虚报能力仍需验收 |
+| D47 | 更名是已定产品变更，不再讨论命名；不打断 M3，先改名、再完成单包分发 | 活跃代码、导入、命令、清单、项目元数据、文档、测试与自动化统一 Pelican 命名，不保留第二套公开 SDK；历史标签/发布/验收证据保留原始内容及哈希并明确历史属性；GitHub 只改仓库名，注册表与远端权限按实际情况报告，不假造迁移或发布完成 |
+| D48 | npm 发布使用用户授权的 Automation Token，后续 CI 同样使用该方式 | 令牌仅作为 GitHub Actions NPM_TOKEN secret 等受保护凭据使用，不写源码/文档/日志；不改变同一已验收里程碑的发布时点 |
+| D49 | 全流程验证按风险和收益选择，减少低收益高耗时步骤，提高迭代速度 | 开发增量优先类型检查、受影响契约和一条真实端到端；不逐次全量重跑性能/质量矩阵、重复安装/打包或冻结未稳定源码；GPU 任务串行，完整验收集中在稳定冻结及里程碑发布前；保留真实证据与失败记录，不以跳过必需验收冒称完成 |
+| D50 | 用户于 2026-11-06 要求立即停止一切验证，以编译不报错作为推进条件，极速完成 1.0 | 本决策覆盖 D35、D43、D45、D46、D49 中要求继续执行测试、硬件或验收矩阵的操作：不得启动测试、浏览器、GPU、性能、分发 smoke、额外校验或其他验证；仅允许编译/构建及其必要步骤。CI 亦不得自动运行这些验证。此前真实结果保留原样；编译成功只说明编译成功，不可伪造或暗示运行、性能、画质、硬件和质量已验证。已知未完成能力及风险如实标记，不用空实现或视觉近似冒充完整能力；用户恢复验证授权前不得自行恢复。里程碑编译通过后的提交、标签、Release、npm 同节点发布要求不变，但发布说明必须明确未验证。 |
+| D51 | 用户于 2026-11-06 要求发布 M3 后收敛所有分支和工作树，今后只使用单线串行开发 | 仅在主工作树和 `main` 顺序研发，不新建并行工作树或开发分支；历史独有成果、未提交文件、忽略证据和提交须安全保留，不得跟随 junction 删除。历史候选未合入的部分只作为本机归档，后续逐项审查和串行集成，不能声称已完成。D50 验证禁令继续有效。 |
+| D52 | 用户要求 npm 包由自动化提交 staged 发布，再由本人以 2FA 手动审核 | npm CI 使用受保护的 `NPM_TOKEN` 提交 staged 包；预发布版本使用 `next` 标签。Staging 成功不等于版本已公开发布，批准须由用户手动完成 2FA。令牌不得写入源码或日志。D50 禁止测试及其他验证的约束仍然有效。 |
+| D53 | 用户要求每次推送主线自动以无预发布后缀的正式版本发布到 npm `latest`，使用 OIDC，不再人工审批 | 覆盖 D48、D52 的 token/staged/next 方案。GitHub Actions 使用 npm 可信发布，不传长期发布令牌；每次运行生成唯一正式版本，更新 `latest`。发布失败、队列延迟和不可覆盖版本须如实记录。正式版本命名不表示行为、硬件或完整里程碑已验证，D50 仍有效。 |
+| D54 | 用户要求推送主线即尝试发布 npm，GitHub Release 仅标记里程碑；仓库和 npm 使用相同的简洁版本，移除 `next` | 覆盖 D53 的运行 ID 自动版本方案。版本由仓库显式维护，CI 不自动改号；每次推送使用该版本以 OIDC 发布到 `latest`，版本重复则失败并等待后续版本，不覆盖既有包。移除 `next` 别名但保留历史版本；已有长版本不可重用或抹除。D50 仍有效。 |
+
+## 本次变更实施顺序
+
+不打断 M3：先将活跃项目统一更名 Pelican Engine，再完成 pelican-engine 单包的最小端到端链路与明确能力边界的 WebGL2 光栅回退，随后补齐渠道一致性、独立 AI 使用、离线与生命周期矩阵。仓库开发与 npm 开发不得形成两套接口或不同的 AI 能力等级。旧里程碑证据保留原始语义；本次名称、分发和回退决策优先于历史 threecat/@threecat/sdk/WebGPU-only 描述。
+
+## 已纠正的误解
+
+1. “AI 友好”不是降低功能复杂度，而是降低不必要的使用歧义并增强观察、验证与修复能力。
+2. “完整封装”不等于只提供预设。组件、系统、材质、后处理、GPU 计算、程序化内容都必须可表达新需求。
+3. “不绕过引擎”是生态规范，不建设代码防篡改或违规产物封禁机制。
+4. 开源引擎的研发修改，与游戏开发任务通过公开 SDK 开发，是两个职责，不冲突。
+5. 游戏开发者可以自由获取和放置引擎；“仓库即产品”不要求游戏必须在仓库内。
+6. Windows 是开发环境范围，不是玩家端拦截规则；固定机器是测试基准，不是准入条件。
+7. 高质量光追/PT 是明确能力要求，不可用“光栅也可以很好看”替代。
+8. 全首发范围很大，阶段性原型或局部可用版本不得冒称完整首发完成。
+9. 资产生成服务是外部开发选择，引擎无需建立服务任务、账号、计费或模型管理平台。
+10. 任何“游戏 AI”简称均弃用：只使用“引擎研发 AI”“游戏开发 AI”“NPC 行为系统”。
+
+## 需要技术验证而非继续访谈的事项
+
+以下未确定为事实，进入 M0 与后续架构决策记录。能够通过试验解决的，不再要求用户替代研发者选底层算法。
+
+| 问题 | 需要取得的证据 | 决策位置 |
+| --- | --- | --- |
+| Three.js 版本与 WebGPU/WebGL2 内置回退适配 | 初始化失败行为、后端身份、功能能力边界、扩展接口、升级维护成本 | M0 历史报告与 M3 新增回退实测 |
+| 编译与打包底座 | TS 类型/源映射、声明提取、增量、外部目录和 ZIP 入口 | M0 编译报告 |
+| ECS 内核自研或封装 | 查询吞吐、结构变化、句柄、快照和调度契约 | M0/M1 ADR |
+| GPU 光追/PT 算法与依赖 | 动态 BVH、形变更新、采样降噪、材质一致性、性能/内存 | M0 动态渲染报告 |
+| 多物理求解器和耦合 | 代表性双向交互、步长、稳定性、同步/读回成本 | M0 交互模拟报告 |
+| UI 渲染与文字实现 | IME、文本选择、字体、多语言、世界 UI、画面捕获 | M1/M2 专项原型 |
+| 具体基准硬件与负载 | 真实 CPU/GPU/驱动/浏览器清单、测量工具、三模式独立负载 | M0 基准清单 |
+| 快照和回放的大状态成本 | GPU 状态捕获/恢复、异步音频/资源事件、存档一致性 | M0/M1 状态报告 |
+| 无缝世界与可变环境一致性 | 修改提交、资源依赖、导航更新和光追重建的端到端时序 | M4/M5 集成报告 |
+
+## 变更规则
+
+实现方法、依赖版本和内部模块可以根据证据调整，记录原因与影响即可。删除正式首发能力、改变游戏开发边界或新增必要费用，需要回到用户需求决策，不能以“技术优化”名义自行处理。

package/docs/M3-USAGE.md

@@ -0,0 +1,192 @@
+# M3 开发候选使用指引
+
+当前 `0.3.0-m3.0` **尚未正式验收或发布**。稳定 M2 为 `v0.2.0-m2.0`，不能用当前源码更新历史 M2 验收指纹。本文说明已有开发候选的实际操作，不宣称完整高级渲染完成。
+
+## 模型材质槽
+
+模型可用 `materialSlots: { Paint: replacement }` 按加载后的材质名称精确替换该名称的全部材质槽，其余槽保留原材质；与整体 `material` 覆盖互斥。同名槽会一起替换，不能区分同名或无名槽。未知名称返回 `TC_MODEL_MATERIAL_SLOT_MISSING`，诊断包含部分可用的已加载材质名；名称或数量过多时会截断。未知目标材质也会明确报错，替换材质的生命周期仍由引擎管理。仓库示例 `examples/material-slots` 展示此接口；它不代表所有 glTF 扩展均受支持。
+
+模型实际包含 `KHR_animation_pointer` 动画通道时当前明确拒绝并报告 `TC_MODEL_EXTENSION_UNSUPPORTED`；不要将其材质动画当作已经播放。只声明可选扩展而没有使用该通道的模型不因此被拒绝。普通 glTF 平移、旋转、缩放与 morph 动画仍按现有接口使用。
+
+## 不透射介质折射率
+
+`defineMaterial({ id, ior, transmission: 0, ... })` 可为不透射的物理材质指定有限正数折射率，默认值为 1.5。介质法线入射反射率由 `((ior - 1) / (ior + 1))²` 决定；光栅、hybrid 和 path 共享该输入，路径采样与 PDF 也使用对应反射率。金属部分仍使用 baseColor 的 F0。`attenuationColor` 和 `attenuationDistance` 仍要求正的 transmission，不能用不透射 IOR 伪装体积吸收。
+
+仓库中的 `examples/opaque-ior` 以三个黑色平面展示差异；`npm run probe:opaque-ior` 是需要独占 GPU 的小型三模式开发验证。该例不代表完整物理材质扩展或正式 M3 验收；npm 渠道使用同一公开接口，当前源码增量的新包安装验收仍待稳定候选。
+
+不透射物理材质还可设置 `specularIntensity`（0 到 1，默认 1）和 `specularColor`（sRGB `#rgb`、`#rrggbb` 或颜色名称，默认白色）。这两个因子参与介质高光、掠射和 path/hybrid 采样；金属部分仍由 baseColor 决定。非默认高光与正 `transmission` 的组合目前返回 `TC_MATERIAL_SPECULAR_TRANSMISSION`，不会悄悄使用默认值。
+
+自包含 GLB 可使用 `KHR_materials_specular`／`KHR_materials_ior` 的常数材质因子；不透射材质还支持 specular 强度纹理 alpha 与 sRGB 颜色纹理 RGB，资产仅接受 TEXCOORD_0，`optimize` 保留并复核因子、图像和采样配置。高光颜色 PNG 支持 1/2/4-bit 灰度和调色板 Adam7、无色彩元数据的 16-bit，以及 gAMA 45455/100000、标准 sRGB cHRM、sRGB intent 0、cICP [1,13,0,1]；其他 16-bit 色彩块值和 ICC 仍明确拒绝。正透射结合高光纹理及其他未实现扩展仍不支持。示例 `examples/specular-material`、`examples/specular-textures` 和 `examples/specular-textures-16` 对照导入材质；探针需串行独占 GPU。完整 M3 和全新系统或公开注册表验收尚未完成。
+
+## 计算到渲染的缓冲绑定
+
+`defineGame({ computeBuffers: [...] })` 可在首帧前建立受管理缓冲。材质以 `buffers: [{ name, type, buffer?, count? }]` 声明槽，顶点图和片元 `graph`/`graphs` 的 `readBuffer` 引用槽名；初始 `buffer` 必须引用已声明的逻辑 ID。游戏通过 `ctx.render.buffers.bind(materialId, slot, handle)` 改绑，`unbind` 解除引用，`state(materialId)` 查询已绑定的逻辑名称/类型/数量，不能取得底层对象。活跃未绑定槽、类型/数量不符和失效句柄明确报错。
+
+计算任务先产生候选 GPU 输出，完成着色器/越界/非有限值及 CPU 结果校验后才发布新 revision。渲染器对已提交原生缓冲做 GPU→GPU 复制到自己持有的稳定 Three storage 属性，不把 CPU 镜像重新上传当作 GPU 绑定。首次值、显式 CPU 写和恢复检查点可以上传；`inspect` 中 `computeGpu` 区分上传、候选、提交和版本，`bufferBindings` 区分 GPU 复制与渲染属性资源。当前不是零复制，也不是完全无读回：CPU 镜像仍用于任务校验、快照、动态 bounds/BVH 和查询。
+
+被渲染槽引用的缓冲不能 release，先解除所有引用。检查点只保存逻辑绑定；跨插件预检确保 compute 快照包含匹配的 ID/类型/count，失败不改变旧世界。恢复后原缓冲句柄失效，游戏应按名称 resolve；物理 GPU 资源重新建立。WebGL2 上活跃 storage 槽返回 `TC_RENDER_BUFFER_CAPABILITY`，不会上传 CPU 镜像伪装 WebGPU 功能。
+
+后处理以 `definePostProcess({ id, buffers: [...], graph })` 声明相同的类型化槽，通过 `ctx.render.effects.buffers.bind(passId, slot, handle)`、`unbind`、`state` 管理。材质 ID 与 pass ID 是独立命名空间，可以同名。两类槽联合保护逻辑源缓冲，取消其中一个引用不会移除另一类引用的 pin。快照同时预检两类绑定与 compute peer，失败不部分恢复。
+
+片元和后处理允许从 `uv` 等逐像素输入计算动态索引，使用 `floor` 得到整数。负数、非整数、非有限或超过元素数的渲染读取明确返回该类型的零值，不取相邻元素；bool 为 false。compute 越界仍使任务失败，顶点域仍由 CPU 几何镜像执行索引检查，不能把渲染 gather 的零边界语义套到计算任务。
+
+path/hybrid 将常驻 GPU 数据复制进原生材料表的附加 vec4 区域；CPU 表只写材质、参数和零占位。`rendering.surface.materialGraphs.bufferSlots` 记录原生槽的复制、字节、版本和零 CPU 结果上传；资源版本变化使积分/时域失效，未变化帧跳过复制。渲染复制不等于零复制，计算仍逐任务读回验证镜像。
+
+顶点反馈例子为 `examples/compute-render`。片元/后处理例子为 `examples/fragment-buffers`，两者都只使用公开 SDK；源码渠道可运行 `npm run dev -- --project examples/fragment-buffers`。npm 渠道使用同样的声明和 `render.effects.buffers` 接口，无需引擎源码。独占 GPU 的小型复测入口为 `npm run probe:fragment-buffers`。计算纹理及直接渲染槽见下文；完整高级矩阵仍待完成，不宣称全部 CAP-17 已验收。
+
+## 受控顶点图
+
+`defineMaterial({ vertex: { position?, normal? } })` 接受 vec3 输出图。输入可用 `positionLocal`、`normalLocal`、`vertexIndex`、`instanceIndex`、uv/uv1、固定时间、参数及声明纹理的 base-LOD 采样；材质域、计算域和后处理域不能冒用这些输入。至少定义一个通道。
+
+这里的 local 明确指内置 morph、骨骼和实例变换之后、对象世界矩阵之前。position 返回绝对位置，不是位移增量；normal 输入已归一化，输出零向量时保留它。GPU 光栅节点和 f32 CPU 镜像读取同一原始输入快照。未提供法线图时不会自动推导变形微分，也不会自动修正切线或所有法线贴图组合。
+
+使用 `model: { asset, material }` 可显式整模替换导入材质，把顶点图用于带骨骼/morph 的模型；不传 material 保留原资产材质。覆盖材质由游戏内容所有者持有，模型实例与模板不会销毁借用材质。当前是整模替换，不是按源材质槽合并。
+
+引擎从同一变形几何维护对象包围体和渲染射线查询，剔除保持开启，路径/混合 BVH 会更新或 refit。Transform 和显式物理 collider 不被 shader 改写；本功能不等于自动 Rapier 形变或 M4 耦合。
+
+最小例子：`npm run dev -- --project examples/vertex`。数据纹理和小型带骨骼/morph GLB 是可离线重建的 MIT 夹具；`node --import tsx tools/prepare-vertex-assets.ts` 可重新生成。高收益实测入口为 `npm run probe:vertex`，内部 MRT 遮挡回归为 `npm run probe:postprocess:occlusion`；两者都应独占 GPU，不是完整 M3 验收。
+
+## 受控 HDR 后处理
+
+通过 `definePostProcess({ id, graph, enabled? })` 声明 vec4 输出图，并在 `defineGame({ postProcesses: [...] })` 中显式排序。系统使用 `ctx.render.effects.configure/state/setParameter/resetHistory`，无需也不能导入 Three.js、GPU 对象或着色器源码。
+
+图支持 `uv`、`screenSize`、`texelSize`、固定时间和已有类型化参数/算术。`sampleFrame` 的 channel 可为 `scene.color`（未曝光/未色调映射的线性 HDR）、`scene.normal`（世界空间着色法线 RGB，命中 alpha=1）或 `scene.depth`（R 为相机到首表面的世界单位距离，未命中 0），也可为更早 pass 的 ID。`sampleHistory` 读取已声明 pass 的上一个成功提交呈现帧；不允许当前帧的前向依赖。
+
+pass 输出为全尺寸 rgba16float，捕获保持场景原 MSAA，最终曝光/色调映射和颜色转换只执行一次。无启用效果时仍走原直出链路。后端缺少所需 HDR/MSAA/MRT 能力则明确报 `TC_POSTPROCESS_CAPABILITY`，不会自动降尺寸、采样或精度。颜色、法线和距离不是透明多层 G-buffer；半精度范围、复杂透明与逐像素算术溢出的完整诊断矩阵尚未验收。
+
+效果开关及参数参与 CPU 检查点；反馈纹理不序列化，恢复/内容/模式/设备变化明确重置历史。开关变化会防御性重置所有历史；关闭的 pass 不再推进历史，当前帧输出为上游直通。参数改变默认保留历史，需要时显式 `resetHistory(id?)`。反馈按呈现帧推进，不是游戏物理时间或存档状态。
+
+最小三段例子在 `examples/postprocess`：`npm run dev -- --project examples/postprocess`。小规模独占 GPU 验证为 `npm run probe:postprocess`，覆盖三模式像素、通道、反馈/恢复、4× MSAA、方向标记及一条 WebGL2 路径；它不是完整 M3、画质或性能验收。
+
+## 受管理计算
+
+声明 `defineCompute({ id, count, outputType, buffers, graph })`，其中 `buffers` 为具名只读绑定及其 GraphType。计算图用 `input/index`、`readBuffer`、参数和既有算术节点表达计算，不接收原始 shader 或 GPU 对象。系统通过 `ctx.compute` 创建/查询/读写/释放缓冲，派发任务并查询或取消任务；类型、维度、绑定、越界和非有限输出均有明确诊断。
+
+引擎在每个固定 tick 后等待 GPU 任务结算；`readBuffer` 返回上次完整成功结果的 CPU 镜像，失败或取消不覆盖输出。输出可同时作为输入，读取的是派发前快照。枚举 `tasks()` 并释放终态任务，避免无限保留历史；恢复后按缓冲名称 `resolve()`，不复用旧句柄。快照/回放/设备重建已接入，WebGL2 不执行计算。
+
+仓库最小反馈游戏：`npm run dev -- --project examples/compute`。受影响功能复测使用 `npm run probe:compute:numeric`，完成后再串行执行 `npm run probe:compute`；前者为小规模真实 GPU 数值与释放检查，后者为游戏反馈、输入、快照/回放、恢复和一条 WebGL2 能力分支。不要并行争用同一 GPU，也不需要为每次局部修改运行整个 M3 矩阵。
+
+显式依赖使用 `bindings: { name: { task: predecessor } }`：读取该任务的确切成功输出，即使同一源缓冲已经被后续任务覆盖。`after: [predecessor]` 只约束执行顺序，普通缓冲句柄绑定仍读取派发时快照；参数与 time 也在派发时固定。只能引用同一运行时已有的未释放任务，不支持前向/跨 owner 引用。
+
+失败或取消的前置任务使消费者以 `TC_COMPUTE_DEPENDENCY_*` 失败，不运行其 GPU 计算、不发布输出；独立任务继续执行。仍被未完成消费者引用的任务不能释放（`TC_COMPUTE_TASK_IN_USE`）。未释放成功任务会保留其 CPU/GPU 结果版本，及时 `releaseTask` 才能回收历史。已排队的任务结果绑定保护源缓冲；已释放的源资源不能通过旧任务复活。
+
+任务不序列化进快照。游戏不要把临时任务句柄作为持久状态：恢复或设备重建后重新派发链路；源缓冲按名称 resolve。公开示例 `examples/compute-dependencies` 演示分支、覆盖、纯顺序依赖及失败隔离；小型串行硬件验证为 `npm run probe:compute-dependencies`。
+
+当前任务仍顺序执行且每节点读回 CPU 镜像，不是一次批量 GPU-only DAG。GPU 常驻顶点/片元/后处理的缓冲和纹理绑定、顶点图、HDR 后处理及计算纹理核心已接入；完整高级矩阵仍待完成。现有链路不等于 CAP-17 或完整 M3 已验收。
+
+## 计算纹理
+
+使用 `defineGame({ computeTextures: [{ id, width, height, data? }] })` 或 `ctx.compute.createTexture(...)` 创建受管理二维纹理。格式固定为线性 `rgba32float`，data 为行优先 Vec4 数组；宽高必须是正整数，总 texel 数最多 2^24，实际 GPU 限制另行校验。纹理与缓冲共用唯一 ID 空间，但句柄不同，不能混用两类 API。
+
+`resolveTexture(id)` 按名称获取句柄，`describeTexture` 返回尺寸/格式/revision，`readTexture` 返回上次完整成功结果的分离 CPU 镜像。`writeTexture(handle, texels)` 写整图，第三参数 `{x,y,width,height}` 可写矩形；全部数据和范围先通过检查，再一次更新 revision。`releaseTexture` 拒绝仍有未结束消费者的源。
+
+计算内声明 `textures: [{ name, filter?, wrapU?, wrapV? }]`，图中 `sampleTexture` 引用该槽名。filter 为 nearest/linear（默认 linear），寻址为 clamp/repeat/mirror（默认 clamp）。dispatch 通过 `textures: { name: textureHandle }` 捕获派发时输入，或 `{ name: { task: predecessor } }` 读取该任务的确切纹理版本；`after` 仍只提供顺序。纹理不能传给普通缓冲 bindings。
+
+dispatch.output 可为纹理句柄，此时 outputType 必须为 vec4，count 必须等于 width×height。计算输入 `pixelCoord` 是输出整数坐标，`outputSize` 是输出宽高，`uv` 是 texel 中心归一化坐标；缓冲输出视为 count×1，index 保持线性索引。非有限采样 UV 使整个任务以 `TC_COMPUTE_TEXTURE_COORD` 失败，有限域外 UV 按声明寻址。
+
+同一 GPU compute shader 写真实 storage texture 和验证用 packed buffer，校验后成对提交；失败/取消不发布其中一半。后续采样重用确切 GPU 版本，不上传 CPU 计算结果。初始化、显式 CPU 写、恢复后的检查点可以上传；`computeGpu.textureUploads/liveTextures/textureResidentHits/storageTextureDispatches` 可观察实际纹理资源与使用。任务仍读回 buffer 验证，不能宣称 GPU-only。
+
+纹理句柄不跨恢复保存，恢复后按名称 resolveTexture，重新派发临时任务链。示例 `examples/compute-textures` 只导入公开 SDK；源码渠道运行 `npm run dev -- --project examples/compute-textures`，小型硬件复测 `npm run probe:compute-textures`。npm 渠道使用同样的类型/接口与随包本文档。
+
+## 动态纹理渲染与资产
+
+材质和后处理各自声明 `textures: [{ name, texture?, width?, height?, filter?, wrapU?, wrapV? }]`；`texture` 是初始的受管理纹理 ID，不是资产对象。图中 `sampleTexture` 的 texture 使用该槽名。槽名不能与静态纹理资产 ID 相同；静态资产采样仍走原来的接口。运行时通过 `ctx.render.textures.bind(materialId, slot, handle)` 或 `ctx.render.effects.textures.bind(passId, slot, handle)` 改绑，两个服务都提供 `unbind` 和 `state`。尺寸约束可省略；已经绑定的尺寸变化须重新 bind。
+
+槽可用于材质片元、顶点位置／法线和后处理。顶点 CPU 镜像使用相同过滤与寻址维护变形 bounds/BVH 和射线查询，不改变物理 collider。渲染采样非有限 UV 明确返回透明零值；计算采样非有限 UV 仍导致 `TC_COMPUTE_TEXTURE_COORD`。材质／后处理与缓冲／纹理四组引用联合 pin；纹理被引用时 `releaseTexture` 保持现有 `TC_COMPUTE_BUFFER_IN_USE` 错误码。
+
+`computeTextures: [{ id, asset }]` 或 `ctx.compute.createTexture({ id, asset })` 可以从声明并加载的普通纹理资产建立独立计算纹理。支持可读的 RGBA8 或 float32 像素；按资产声明的 sRGB／linear 色空间转换为线性数据并保持上传行顺序。计算纹理之后独立更新，快照保存像素而非依赖重新读取资产。资产不可读、未声明或格式不支持时返回 `TC_COMPUTE_TEXTURE_ASSET`。
+
+Three 路径将常驻纹理以 GPU→GPU 复制到自身资源；path/hybrid 将同版本的 GPU packed mirror 复制到已有材料表。两条路径不会把 CPU 计算结果上传作为渲染更新，但也不是零复制。`rendering.textureBindings` 和 `rendering.surface.materialGraphs.textureSlots` 可查看复制计数；活跃槽在 WebGL2 返回 `TC_RENDER_TEXTURE_CAPABILITY`。示例 `examples/render-textures` 和 `npm run probe:render-textures` 覆盖资产导入与小型三模式链路；npm 使用相同 SDK 和文档，实际新版本安装验收留至里程碑冻结。
+
+## 场景与公开设置
+
+```powershell
+npm run dev
+```
+
+默认加载 `examples/m3` 的真实 Fox/WaterBottle 画廊。`1/2/3` 切换 raster/hybrid/path；Space 切换刚体运动，N 切换空间降噪，D/I 切换直接/间接光照。游戏只导入 `pelican-engine`。
+
+```ts
+export default defineGame({
+  id: "render-example",
+  scene,
+  render: {
+    mode: "path",
+    samplesPerFrame: 1,
+    maxBounces: 6,
+    denoise: true,
+    denoiseIterations: 3,
+    exposure: 1,
+    directLighting: true,
+    indirectLighting: true,
+    debug: "beauty",
+  },
+  systems,
+});
+// 在同步玩法系统中：
+ctx.render.configure({ mode: "hybrid", denoise: true });
+const settings = ctx.render.state();
+```
+
+设置是可序列化状态，参加 Host 快照和恢复；未知字段、非法数值或模式明确失败，不公开 GPU 对象。调试视图支持 beauty/albedo/normal/depth/samples。材质新增 emissive/emissiveIntensity/opacity/alphaTest/side，使用相同编译诊断与引擎封装。opacity 的随机覆盖不是折射。
+
+## 物理透射开发链路
+
+```ts
+const glass = defineMaterial({
+  id: "glass",
+  color: "#ffffff",
+  roughness: 0.15,
+  metalness: 0,
+  transmission: 1,
+  ior: 1.5,
+  attenuationColor: "#80c0e0",
+  attenuationDistance: 2,
+});
+```
+
+`transmission` 是介电透射与不透明 BSDF 的混合比例；它不修改 opacity。IOR 必须为正，透射要求 metalness 为 0；正衰减距离按世界单位计算 Beer 吸收，颜色先转为线性值，距离为 0 关闭吸收。SDK 不暴露底层材质对象。
+
+path/hybrid 将正透射对象的闭合几何边界编入介质目录，支持平滑/粗糙折射、反射、嵌套介质和相机内部初始状态。每个对象或实例必须是单个闭合、连续、非自交壳体；相交/接触体积、开口和部分不透明边界有明确诊断。目录不是通用自交证明；复杂重叠介质、空腔、多壳体、光谱色散尚未实现。完整规则见 `packages/renderer/MEDIUM.md`。
+
+```powershell
+npm run dev -- --project examples/refraction
+```
+
+该项目仅使用公开 SDK，包含吸收平板、内外相机、嵌套边界、折射/粗糙度、尺度/平移和介质内点光源对照。线性图像、边界错误计数与解析 Beer 断言由独立开发探针检查；不能把可见玻璃球当成完整 M3 画质验收。光栅使用物理材质实现，但其屏幕空间透射/厚度与路径体积的一致性仍需补验。
+
+## 已有链路
+
+- 光栅模式使用 WebGPURenderer，WebGPU 初始化不可用时走 Three.js 内置 WebGL2 回退，不主动降画质。`game.render.capabilities()` / `ctx.render.capabilities()` 返回当前后端及可用模式；WebGL2 下切 path/hybrid 返回 `TC_RENDER_MODE_UNAVAILABLE`，降噪/计算返回 `TC_RENDER_COMPUTE_UNAVAILABLE`，原设置保持不变。两后端都不可用返回 `TC_RENDER_BACKEND_UNAVAILABLE`。状态栏同步显示 WebGPU/WebGL2。
+- path 使用当前表面/BVH 的实际光线命中，UV、法线、PBR 纹理和多材质组进入 WGSL。
+- hybrid 光栅化首命中，再使用同一材质/灯光进行真实阴影与二次光线求值，不透明叠加独立图片。
+- 支持点/方向光、环境辐射、发光几何及 MIS；studio PMREM 捕获实际 HDR，不用均值或假背景替代。
+- 内容变更、相机、灯光、材质和设置变化使路径累积失效。开启 denoise 后独立主命中通道输出上一帧 UV/预期深度，先做时域历史验证/邻域裁剪，再做空间滤波；静态连续累积不重复计入历史。完整时域画质矩阵仍未验收。
+- 设备丢失会暂停并尝试重建设备/管线/环境，保留 CPU 游戏状态；失败保持故障诊断。自动化就绪不依赖点击、焦点或按回车。
+
+当前 capture/cache、CPU SAH/refit 与 GPU 线程化遍历是不同阶段。它们不等于 GPU refit、BLAS/TLAS 或专用硬件 RT。原生 1080p 的当前高反弹负载仍慢，性能优化和完整质量矩阵未完成。
+
+`examples/temporal` 是只用公开 SDK 的运动/遮挡/动画/资源恢复测试场景。
+`denoiseIterations` 仅控制空间迭代次数；`denoise=false` 关闭时域与空间链路。
+内部开发读回不是游戏接口。时域历史的权重不是严格独立的光线样本数，
+不能据此把低 spp 动态帧宣称为高 spp 物理参考。详见 `packages/renderer/TEMPORAL.md`。
+
+## 开发复验
+
+### 刚体角运动（M4 并行增量）
+
+`ctx.physics.angularVelocity(entity)` 查询世界坐标弧度／秒；`setAngularVelocity(entity, vec3)` 设置动态刚体角速度，`torqueImpulse(entity, vec3)` 施加世界空间力矩冲量，`impulseAtPoint(entity, impulse, worldPoint)` 在指定世界坐标施加冲量，同时影响平动和转动。后三者只支持动态刚体；固定、运动学或角色体返回 `TC_PHYSICS_BODY_TYPE`。写操作参与物理历史、快照和回放，旧快照仍兼容。
+
+示例 `examples/angular-physics` 只使用公开 SDK；源码渠道运行 `npm run dev -- --project examples/angular-physics`，独占 GPU 的小型验证为 `npm run probe:angular-physics`。当前 M4 非正式完成，首次正常物理步前移除刚体存在已复现的底层生命周期缺陷，见 `docs/tasks/M4-ANGULAR-PHYSICS.md`；完整模拟交互仍需后续验收。npm 渠道使用相同 SDK，更新包安装验收留待稳定节点。
+
+```powershell
+npm run typecheck
+npm run probe:m3
+npm run build
+```
+
+`probe:m3` 必须在真实硬件 WebGPU 环境运行，生成带源码指纹的开发记录和图像。失败不覆盖成成功；`formalMilestoneAccepted` 明确为 false。全量测试的硬件 opt-in 见 `docs/tasks/M3.md`；未启用时的跳过不算通过 GPU 验证。
+
+构建仍为 `dist/`，可在普通静态服务器子路径部署；默认生产不暴露开发控制 hook。`tools/m3-static-probe.ts` 使用真实按键测试模式切换和冷启动。直接浏览器自动化是外部测试职责，游戏源码不得调用内部开发 hook。
+
+当前公开图语言仍是有限子集。后处理、多通道、变形和计算接口的完整表达矩阵、完整物理材质图像矩阵、时域重建、原生性能及独立 AI 使用门禁未完成前，不发布 M3。已确认的 M1–M8 总范围保持不变。

package/docs/PELICAN-MIGRATION.md

@@ -0,0 +1,38 @@
+# Pelican Engine 命名与迁移
+
+本次名称由用户确定：**Pelican Engine（鹈鹕游戏引擎）**。引擎仍处于 M3 开发，不因更名重启里程碑，也不把已有开发探针提升为正式验收。
+
+| 对象 | 唯一正式名称 |
+| --- | --- |
+| 产品 | Pelican Engine（鹈鹕游戏引擎） |
+| GitHub 所有者 / 仓库 | `danchar12138/pelican-engine`（所有者保持不变） |
+| npm 单包 | `pelican-engine` |
+| 命令 / bin | `pelican` |
+| 游戏侧公开导入 | `pelican-engine` |
+| 源码目录启动脚本 | `pelican.ps1` |
+| 项目清单 | `pelican.project.json` |
+| 本地缓存 / 开发控制路由 | `.pelican/` / `/__pelican/` |
+| 部署版本清单 | `pelican-build.json` |
+
+SDK、runtime、renderer、编译器和 CLI 位于同一个 npm 包中。内部模块不成为额外公开导入入口；游戏不导入 renderer、Three.js、TSL 或 GPU 对象。仓库开发通过路径解析到同一 SDK，npm 通过导出解析到生成的 JavaScript 与声明，接口与开发能力相同。
+
+目标最短使用流程为：
+
+```powershell
+npm i -D pelican-engine
+npx pelican dev
+```
+
+首次 `dev` 在没有游戏文件的新目录创建最小可运行项目；已有项目必须保留原文件，错误给明确诊断，不能覆盖游戏。安装依赖后日常开发、构建和运行不依赖网络；自动化截图需要提前准备浏览器。
+
+## 历史与迁移边界
+
+M0–M2 的原名称、标签、提交、Release 附件与 `evidence/` 是历史事实，内容及哈希原样保留。历史证据中的旧名称、旧协议、旧命令只适用于对应历史标签，不是当前 SDK 的别名。原始 MIT 版权声明继续保留，新开发声明 Pelican Engine。
+
+既有稳定错误码 `TC_*`、`TCENV_*`、`TCREL_*` 是诊断协议标识，不是旧 SDK 的入口或品牌别名，本次不为改名破坏它们。旧缓存目录仅在忽略/归档排除规则中保留，以免把历史缓存当作当前源码或发布物；当前生成的项目、协议格式、控制路由和产物统一使用 Pelican 名称。磁盘上已有工作目录名称不影响包身份，无需强制移动用户目录。
+
+从旧工作树的游戏迁移时，在游戏副本中将公开导入统一为 `pelican-engine`，清单改名为 `pelican.project.json` 并锁定当前精确引擎版本，使用当前 CLI 重新检查和构建。重新生成 `.pelican/` 与 `dist/`，不复用旧编译缓存。旧存档/回放/快照的品牌格式标识不自动当作当前格式；无明确迁移器时保留原文件并提示不兼容，不静默改写历史数据。原里程碑复测继续从原标签进行。
+
+## 远端实际状态
+
+用户后续明确 GitHub 只改仓库名，不改组织。远端现已改名为 `danchar12138/pelican-engine`，本地 origin 同步更新，公开仓库、历史标签与 Release 保留。npm 身份已通过授权 Automation Token 验证，令牌仅配置为该仓库 Actions 的 `NPM_TOKEN` secret，未写源码或证据。npm `pelican-engine` 查询仍返回 404；本轮只完成更名和开发分发验证，不在里程碑验收前提前推送、创建标签或发布包。

package/docs/RENDER-BACKENDS.md

@@ -0,0 +1,50 @@
+# 渲染后端与能力诊断
+
+适用：M3 开发工作树及由同一版本生成的 npm 包。历史 M0–M2 标签保留当时 WebGPU-only 行为；本文件不改写旧验收。
+
+## 同一公开接口
+
+游戏仍只使用 `pelican-engine`。仓库、ZIP、外部目录和 npm 渠道共用相同声明、编译器和运行时。查询 `game.render.capabilities()` 或系统中的 `ctx.render.capabilities()`：
+
+```typescript
+const capabilities = ctx.render.capabilities();
+// backend: "webgpu" | "webgl2" | "uninitialized"
+// compute: boolean
+// availableModes: readonly ("raster" | "hybrid" | "path")[]
+```
+
+返回值是分离的普通数据；没有 Three.js、GPUDevice 或 WebGL 上下文。未绑定浏览器渲染器的纯 CPU 运行时报告 `uninitialized`，不能据此声明已经初始化 GPU。
+
+## 选择与画质
+
+引擎创建 Three.js `WebGPURenderer`，由其 `getFallback → WebGLBackend` 处理 WebGPU 初始化不可用。没有 API、找不到适配器和适配器请求拒绝均可进入内置回退；引擎不自行构造 WebGPUBackend，也不根据缺少 `navigator.gpu` 提前拒绝。
+
+引擎不改变作者指定的分辨率、采样、灯光、材质或后处理来适应回退。不同后端可能存在数值、驱动或扩展能力差异；支持边界必须明确记录，不能把近似图像当作相同功能。WebGL2 可用模式为 `raster`；依赖 compute 的 `path`、`hybrid`、降噪和受控计算不能使用。初始内容要求不支持模式时明确失败，不自动重写内容。
+
+状态栏显示当前 WebGPU/WebGL2。开发态 `inspect` 同时提供实际后端名称、适配器（适用时）和 `capabilities`；WebGL2 不伪造 WebGPU 适配器信息。
+
+## 错误与修复
+
+| 错误码 | 含义 | 修复 |
+| --- | --- | --- |
+| `TC_RENDER_MODE_UNAVAILABLE` | 当前后端不支持请求的模式 | 按错误中的 available modes 选择模式，或启用实际可用的 WebGPU 后重新加载 |
+| `TC_RENDER_COMPUTE_UNAVAILABLE` | 降噪或计算需要 WebGPU compute | 不请求该功能，或启用 WebGPU 后重新加载；不能替换成光栅并仍声称光追 |
+| `TC_RENDER_BACKEND_UNAVAILABLE` | WebGPU 及内置 WebGL2 回退均无法初始化 | 检查图形加速、驱动、浏览器设置与安全上下文，修复后重载 |
+| `TC_RENDER_CONTEXT_LOST` | WebGL2 上下文丢失，等待浏览器恢复 | 游戏暂停；浏览器恢复上下文后引擎重建资源并保留受控 CPU 状态；未恢复时不报告 ready |
+| `TC_GPU_RECOVERY_FAILED` | 设备或上下文重建失败 | 保留诊断，修复缺失能力后重载；不宣称旧 GPU 资源仍可用 |
+
+配置和检查点恢复先校验能力再提交；被拒绝的配置不改变当前模式或设置。运行态开发控制命令返回结构化 `failed` 与稳定错误码，不因正常的不支持请求把游戏置为崩溃状态。
+
+## 实测入口
+
+在 Windows、已安装依赖与 Playwright Chromium、真实硬件加速环境中：
+
+```powershell
+npm run probe:backends
+# 仅运行独立 WebGL2 回退矩阵：
+npm run probe:backends -- --webgl-only
+```
+
+输出 `.pelican/backend-probes/<run>/report.json` 与截图，包括源码指纹、实际 ANGLE/GPU 身份、画面像素检查、三类初始化失败、不可用模式/降噪/计算错误码、两次上下文恢复、重复内容重载，以及两后端都不可用的诊断。默认还复测真实 WebGPU 三模式设备重建。
+
+这是开发专项，不是完整 M3 acceptance。主里程碑只接受真实 WebGPU 硬件证据；WebGL2 单列记录，不用它或软件渲染器代替主门禁。性能保留诚实观测，不以固定帧率阈值阻断 1.0，也不放松功能正确性和资源生命周期验证。