重构资源画本画布与转场状态

统一主画布与子画布的可见渲染层和 viewport 状态管理。

将子画布改为固定视口加无限平移 world，并保证首次 fit 的可读比例。

补充转场、滚轮、viewport 和资源画本回归测试，更新技术方案文档。

docs/technical/【技术方案】GameAgent资源自由画板与快速编辑-2026-08-20.md

@@ -1,5 +1,33 @@
 # Game Agent 资源自由画板与快速编辑
 
+## 2026-09-04 动画回归排查与重构收敛方案
+
+最近一组资源画本提交（`f339b383f`、`019b1761f`、`f883d4bf2`、`069248b29`、`820fbfd98`）把主画布、子画布、真实资源卡、分页画布和滚轮转发逐步叠加在同一个页面组件中，造成状态、坐标和副作用互相耦合。本阶段先完成低风险收敛：
+
+- 真实 `ResourceCard` 只保留一棵由 `ResourceBookScene` 管理的节点树；主画布缩略卡只负责入口展示，不再复制真实卡片或预览。
+- 修复主画布稳定 `main/idle` 状态误把标题和共享预览卡隐藏的问题；主画布与返回中的 overview 统一保持可见，只有进入子画布后才切换为活动栏目。
+- 转场 timer、`requestAnimationFrame` 和项目切换绑定同一个 token；新目标、切项目或卸载时统一失效旧回调，避免旧动画写入新栏目。
+- 从大纲或“下一页”进入时使用已测量的缩略卡布局作为过渡起点；子画布互切先同步逻辑目标栏目，再按既有 320ms/520ms 节奏完成返回与进入动画。
+- 主画布 viewport 与子画布 viewport 分离；普通滚轮直接复用分页画布 handler，Ctrl/Meta 滚轮只更新当前 viewport，不再向隐藏 DOM 重新派发 `WheelEvent`。
+- 转场阶段由 `ResourceBookScene` 统一承载当前 viewport：主画布缩放后的背景、标题、预览卡，以及进入/返回子画布时的目标缩放，都在同一条 `transform` 动画链路中完成，避免缩放后卡片和背景使用不同坐标系。
+- 依赖图尚未完成读取时不挂载真实资源卡；失败时允许使用明确的 fallback 快照，避免预览和布局在未确定的图上提前启动。
+
+重构按三个边界推进，不改变当前动画视觉参数：
+
+1. 已抽离 `resourceBookModel`、`resourceBookLayout`、`resourceBookViewport` 纯模块，以 reducer 管理 `main / child / entering / returning`，组件只订阅投影并渲染。
+2. 已抽离 `resourceBookController` 与 `resourceCanvasController`，由 tokenized transition controller 管理 timer/RAF，由分页 controller 管理滚轮阈值、方向、节流和重置；主画布、子画布和分页画布不再通过隐藏 DOM 转发推进状态。
+3. 已删除历史资源画本动画规则和重复 hover 选择器，并为快速切换、项目切换、origin 解析、viewport 隔离、唯一预览观察和滚轮状态补充回归测试。
+
+### 当前验证与未收敛项（2026-09-04）
+
+`npm --prefix apps/ai-game-creator-shell run typecheck`、`npm run check:encoding`、`git diff --check` 和相关 ESLint 检查已通过。`apps/ai-game-creator-shell/tests/appSurface.test.ts` 已恢复为 `384 passed / 0 failed`，资源画本模型与 controller 测试合计 `9 passed / 0 failed`；另补充主画布稳定态标题与共享预览卡回归场景。
+
+测试仍会输出既有的 React `act(...)` 提示，以及 jsdom 未实现 `HTMLMediaElement.prototype.pause` 的 stderr；这些是测试环境警告，不影响断言结果，也未新增生产兼容层。
+
+### 2026-09-05 子画布无限平移与初始可读比例
+
+子画布改为固定视口加可无限平移的 world 层：视口本身保持 `overflow: hidden`，平移和缩放只作用于 `.game-resource-book-scene-world`，不再让内容容器的边界限制拖动范围。首次 fit（包括隐藏分页画布提前完成的 fit）统一保证比例不低于 `1:1`，避免子画布展开后卡片缩成不可读的小块；用户后续主动缩放或平移的视口仍按每个分类独立保留。新增 viewport 回归测试覆盖初始可读比例和超出内容边界双向平移。
+
 ## 2026-09-04 资源画本 UI 阶段补充
 
 资源工作台当前产品方向调整为“主画布 + 子画布”的统一画本模型。主画布展示各子画布的缩略卡片，不直接展开真实资源内容；缩略卡片内部按资源类型显示有限层叠卡片，最多展示三层，更多资源以虚化卡片提示。进入子画布时使用共享元素转场：标题栏和资源卡片沿用同一组 DOM 元素，从缩略卡片的原始位置移动、展开到子画布中的目标位置，不允许先播放独立放大动画再硬切另一套内容；主画布预览和子画布展开态必须复用同一套卡片视觉与标题栏结构。进入子画布时在标题栏提供缩回主画布的缩放按钮；从一个子画布切换到另一个子画布时必须先完成缩回主画布，再进入目标子画布。