docs: add DX-first runtime and asset redesign spec

Made-with: Cursor

docs/superpowers/specs/2026-04-26-pixi-dx-runtime-assets-redesign-design.md

@@ -0,0 +1,299 @@
+# Pixi 框架重构设计（DX 优先，性能其次）
+
+## 背景与目标
+
+本设计用于指导 `pixi-demo` 的新一轮框架重构。重构范围聚焦两部分：
+
+- 核心运行时（`Game + Scene + 生命周期 + 插件机制`）
+- 资源系统（`AssetManager + manifest + 预加载/引用追踪/调试信息`）
+
+约束和原则：
+
+- 目标平台：Web H5 优先
+- 兼容策略：彻底升级（允许批量改场景代码，换取更干净的架构）
+- 优先级：开发者体验第一，性能第二
+- 允许任意重构
+- 需要内置一组服务开发流程的 UI 能力
+
+## 设计原则
+
+1. 可观测优先：所有关键行为都能在开发态被看见和解释。
+2. 状态可证明：场景与资源都由明确状态机驱动，不依赖隐式约定。
+3. 边界清晰：运行时、场景、资源、开发工具分层解耦，减少跨层直接访问。
+4. 失败可恢复：切换和加载过程默认考虑失败与回滚，不把异常当特例。
+5. 渐进性能：先构建可测量基础，再做高收益优化，避免盲目微调。
+
+## 总体架构
+
+### 1) `kernel`（运行时内核）
+
+职责：
+
+- 管理 `AppRuntime`（renderer/ticker/stage）
+- 编排生命周期与切换事务
+- 提供插件总线与统一错误边界
+
+非职责：
+
+- 不承载业务场景逻辑
+- 不直接持有业务资源映射
+
+### 2) `scene`（场景域）
+
+职责：
+
+- 场景注册（`SceneRegistry`）
+- 场景切换（`SceneTransition`）
+- 场景上下文（`SceneContext`）
+
+场景统一生命周期：
+
+- `created -> setup -> assetsLoading -> entering -> ready -> leaving -> disposed`
+
+### 3) `assets`（资源域）
+
+职责：
+
+- 资源依赖图（`AssetGraph`）
+- 场景资源会话（`AssetSession`）
+- 引用追踪与释放策略
+- 预加载与复用策略
+
+### 4) `devtools`（开发体验层）
+
+职责：
+
+- 开发态 overlay
+- 运行时事件时间线
+- 场景/资源检视器
+- 命令面板（Command Palette）
+
+约束：
+
+- 仅通过事件与快照读取状态，不直接修改业务状态
+
+### 5) `ui-core`（内置 UI 基础层）
+
+第一阶段只服务开发工具界面，不直接扩展为完整业务 UI 框架。提供最小组件集：
+
+- `UiPanel`
+- `UiText`
+- `UiButton`
+- `UiList`
+
+## 模块边界约束
+
+- 场景层不得直接调用 Pixi `Assets` 全局对象，只能通过 `SceneContext.assets`。
+- 资源层不得感知具体场景类实现，只识别 `ownerId/sessionId`。
+- 运行时内核不直接 import 业务场景文件，场景通过注册机制注入。
+- devtools 读取运行时快照和事件流，避免写入造成调试副作用。
+
+## 生命周期与数据流设计
+
+## 场景状态机定义
+
+### `setup`
+
+- 创建静态显示对象结构
+- 绑定事件与命令
+- 禁止异步资源请求
+
+### `assetsLoading`
+
+- 通过 `AssetSession` 申请 bundle 及依赖
+- 记录 owner/session 关系
+
+### `entering`
+
+- 资源就绪后的首帧布局
+- 进入动画和交互解锁前处理
+
+### `ready`
+
+- 场景可交互的稳定状态
+
+### `leaving`
+
+- 停止输入和 ticker 订阅
+- 准备切换和资源释放
+
+### `disposed`
+
+- 场景彻底释放，不再允许引用
+- 需要复用时重新实例化
+
+## 场景切换事务（Transition Transaction）
+
+切换流程固定为：
+
+1. `beginTransition(from, to)`
+2. `freezeInput(from)`
+3. `prepare(to)`（`setup + assetsLoading`）
+4. `commit()`（舞台替换 + `entering`）
+5. `finalize(from)`（`leave + dispose/unmount`）
+6. `emitTransitionReport()`
+
+失败处理：
+
+- 任一阶段失败触发 `rollback()`
+- 回退到 `from.ready`
+- 记录失败阶段与异常信息
+- 通过 dev overlay 展示失败链路
+
+## 资源会话模型（AssetSession）
+
+每次场景进入创建 `AssetSession(sceneId, transitionId)`，示例：
+
+- `session.require("bundle.home")`
+
+内部行为：
+
+- 解析 `AssetGraph` 依赖关系（如 `home -> common-ui -> common-audio`）
+- 记录引用链：`asset <- bundle <- session <- scene`
+- 在 `commit` 成功后再释放旧场景 session
+
+释放策略：
+
+- 支持短延迟释放窗口（例如 2s），降低快速来回切场造成的重复加载抖动
+
+## 可观测事件流
+
+内核输出统一事件流：
+
+- `scene:state-changed`
+- `transition:started|committed|rolledback|finished`
+- `asset:request|loaded|reused|released|orphan-detected`
+- `runtime:error`
+
+该事件流同时服务日志、overlay、定位与回归验证。
+
+## 开发体验能力（MVP）
+
+## Debug Overlay（开发态默认启用）
+
+至少展示：
+
+- 当前场景与状态
+- 切换耗时
+- 最近运行时事件（最近 20 条）
+- FPS 和 ticker 开销
+- bundle 引用树（owner/session）
+- 最近错误与 phase
+
+支持快捷键开关（例如 `~`）。
+
+## Scene Inspector（最小版）
+
+展示场景树（scene id/state/mounted）并支持开发命令：
+
+- `reload current scene`
+- `simulate transition failure`
+- `force release assets(session)`
+
+## Asset Inspector（最小版）
+
+展示：
+
+- `bundle -> assets -> owners`
+- orphan 资源
+- 高频重复加载 bundle
+- 长驻 bundle 总量
+
+## Runtime Command Palette
+
+支持开发命令调用，例如：
+
+- `scene.goto(welcome)`
+- `asset.preload(bundle.xxx)`
+- `dev.toggleOverlay()`
+
+## 性能策略（第一阶段）
+
+在不牺牲 DX 的前提下做低侵入优化：
+
+- overlay 刷新节流（例如 200ms）
+- 通过可观测数据驱动资源预热，而非猜测
+- 切场资源释放使用短延迟窗口平衡内存与流畅度
+
+## 测试与验收标准
+
+## Definition of Done
+
+### 运行时稳定性
+
+- 场景切换 100 次无卡死、无黑屏、无未捕获异常
+- 切换失败可回滚到上一场景 `ready`
+
+### 资源可追踪性
+
+- 每个已加载 bundle 都可查看 owner/session
+- 切场后无长期 orphan 残留（延迟释放窗口内短暂存在可接受）
+
+### 开发体验
+
+- overlay 可一键开关且不阻断交互
+- 至少 8 条 runtime 命令可执行
+- 报错可定位到生命周期 phase
+
+### 可维护性
+
+- 生命周期、切换事务、资源图关键路径具备单测
+- 新场景模板可在 5 分钟内创建并跑通
+
+## 测试策略
+
+### 单元测试
+
+- `SceneStateMachine` 状态迁移合法性
+- `TransitionTransaction` 的 commit/rollback 分支
+- `AssetSession` 引用计数与释放顺序
+
+### 集成测试
+
+- 场景 A->B->A 快速切换与资源抖动
+- bundle 加载失败与恢复
+
+### 手工验证（开发态）
+
+- overlay 信息正确性
+- command palette 链路可用性
+- 长时间运行资源引用稳定性
+
+## 实施里程碑
+
+### M1：运行时内核重构（约 1 周）
+
+- 新 lifecycle 与 transition transaction
+- 插件总线
+- 基础 overlay（状态与耗时）
+
+### M2：资源系统重构（约 1 周）
+
+- `AssetGraph + AssetSession`
+- `Asset Inspector`
+- 预热与延迟释放
+
+### M3：DX 强化（约 1 周）
+
+- command palette
+- 场景模板与错误提示优化
+- 验收测试补齐
+
+## 风险与应对
+
+- 风险：彻底升级导致迁移期间业务场景不可用。
+  - 应对：按里程碑提供最小迁移适配层，仅用于过渡，M3 后清理。
+- 风险：devtools 与运行时耦合过深。
+  - 应对：强制事件总线和只读快照接口，禁止直接写内核状态。
+- 风险：资源引用关系复杂导致误释放。
+  - 应对：`owner/session` 双维追踪 + release 日志审计 + 回归用例。
+
+## 非目标（当前阶段不做）
+
+- 完整业务 UI 组件库建设
+- 多端宿主统一适配层（小程序/小游戏）
+- 高级渲染性能专项（需在可观测基础稳定后进行）
+
+## 结论
+
+本方案以“内核先重构、资源系统同步升级、开发工具前置落地”为主线，保证在重构初期即提升开发者体感，并通过可观测与状态机约束降低后续维护成本。第一阶段以可看见、可定位、可恢复为核心交付，性能优化作为可量化的后续迭代项推进。