C3 资源画本转场改为真实元素 FLIP

- resourceBookController 重写为真实元素 FLIP：begin 在提交前记录 First，play 测 Last 后给同一节点加反向 transform，sync 按布局签名做可中断重基
- 转场进行中重基用剩余时长（下限 80ms），空闲布局变化用完整 420ms，预览图尺寸晚到的二次布局变化不再瞬移
- 宿主节点几何基准改存 world 局部坐标，平移和缩放不会让上一次的干净矩形过期
- 不可见节点钉在 First 淡出、挂载节点淡入；搜索/排序导致的卸载保留一帧淡出；返回总览时源栏目未回到摞上的卡片按子画布布局淡出
- 新增 buildResourceBookScenePlan 渲染计划，渲染、转场签名与淡出集合共用同一份数据
- 删除 ResourceBookTransitionLayer 与克隆快照逻辑，清理 styles.css 的转场层和 data-book-motion 隐藏规则
- 重写 resourceBookController.test.ts，补 resourceBookLayout/resourceBookModel 用例与 appSurface 同节点断言
- 同步技术方案转场段与 pitfalls 经验条目

docs/project-memory/shared-memory/pitfalls.md

@@ -38,8 +38,10 @@
 
 - 无限画布的指针交互必须绑定未变换、铺满可视区域的视口，平移和缩放只作用于内部 world；若连交互容器一起移动或缩小，内容移走后的空白处会失去拖动入口。内容层不裁剪，裁剪仅由固定视口承担；主画布滚轮使用非 passive 监听，避免浏览器默认滚动或缩放。
 
-- `resourceBookController` 使用独立 FLIP 快照层和 Web Animations 完成信号；逻辑栏目立即提交，不用定时器猜 CSS 动画终点。再次导航从当前快照位置开始，旧完成回调由 token 失效。
-- 屏幕 DOMRect 与逻辑布局坐标不能混用。主画布缩略入口测量先逆 viewport；快照复制必须保留祖先缩放对内部图片、文字的影响，单纯把克隆外框改成屏幕宽高会产生内部留白。
+- `resourceBookController` 对真实元素做 FLIP：`begin` 在状态提交前记录 First，提交后 `play` 测 Last 并给同一个节点加反向 transform 过渡回 identity，`sync` 在每次布局提交后比较布局签名做可中断重基。逻辑栏目立即提交，不用定时器猜 CSS 动画终点；再次导航从当前像素开始，旧完成回调由 token 失效。
+- 屏幕 DOMRect 与逻辑布局坐标不能混用。主画布缩略入口测量先逆 viewport；FLIP 的 translate 写在 world 局部坐标系，屏幕位移必须除以 world 缩放，宿主节点原点不在卡片左上角时（卡片包装节点是 0x0）还要按原点偏移换算。
+- 克隆快照 + 动画结束交接给真实节点这条路线有两个结构性缺陷，反复补丁也治不了：一是交接要求两个不同 DOM 对象的终态像素级一致；二是快照层在 world 之外、真实卡片在 world 之内，克隆坐标是屏幕空间、真实节点是 world 局部空间，交接时必然要重映射一次坐标。共享元素转场只在"同一批 DOM 节点、同一父节点"成立时才用真实元素 FLIP，不要引入克隆层。
+- 卡片尺寸依赖异步到达的预览图尺寸，布局会在转场动画之后（甚至动画结束之后）再变一次。所有布局变化必须走同一套"同一节点反向 transform"，并在动画运行中以"此刻像素"为起点重基（转场中取剩余时长，下限 80ms；空闲布局变化取完整时长），否则晚到的那次布局变化仍是瞬移。
 - 点击和滚轮共用导航入口，但滚轮提交不得重置已有的冷却和队列；监听器使用最新导航回调引用，避免视觉 phase 更新重装监听器并清空待处理手势。
 - jsdom 不执行真实转场；定向模型测试之外，仍需浏览器核验中断连续性、图片/文字尺寸、viewport 保留和窄屏布局。完整契约见资源自由画板技术方案。
 

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

@@ -3,26 +3,27 @@
 ## 2026-09-05 资源画本独立转场
 
 - `resourceBookModel` 立即提交目标 `main / child + category`，`entering / returning-main` 只表示尚未收尾的视觉过程，不承载待提交的栏目。缩略入口、大纲、下一页与资源定位共用分类导航入口；栏目互切直接到达目标，不经过总览。滚轮不切换栏目。
-- 真实 `ResourceCard` 仍由唯一的 `ResourceBookScene` 挂载，保持预览请求、播放器和交互的单一所有者。转场前 `resourceBookController.begin` 捕获当前可见标题与资源卡的屏幕矩形和表现；目标 DOM 提交后的 layout effect 调用 `play`。
-- `ResourceBookTransitionLayer` 是 manager 内未变换的独立层。快照仅复制表现，不挂载 React 业务组件，移除重复 ID、业务 data 属性及可访问控件身份，整层 `inert / aria-hidden / pointer-events:none`。播放中的视频优先捕获当前帧；跨源禁止读取时保留已有 poster，不启动第二个播放器。
-- FLIP 只动画快照的 transform/opacity，统一时长 420ms，所有 `Animation.finished` 完成后删除快照并恢复目标真实节点；动画创建失败、零尺寸或不支持 Web Animations 时直接完成。`prefers-reduced-motion` 不创建动画，不等待定时器。
-- 再次导航先读取当前动画快照的实际位置，再取消旧动画并重新建立目标；token 隔离旧 promise，过期完成和取消均不能提交新状态。窗口尺寸变化、排序或异步布局更新时直接收尾到当前目标，避免使用过期几何。
+- 转场对**真实元素**做 FLIP，不使用克隆快照层。总览与子画布之间同一张卡是同一个 DOM 节点（同一 React key、同一父节点，只有布局函数在 `resourceBookOverviewCardLayout` 与 `resourceBookChildCardLayout` 之间切换），标题栏同理。`resourceBookController.begin` 在状态提交前按 key 记录 First 屏幕矩形与当前不透明度；提交后的 layout effect 调 `play` 测 Last，给同一个节点加反向 transform 再过渡回 identity。动画结束没有"克隆 → 真实节点"的交接，因此不存在交接瞬间的跳变；遮挡关系由真实 DOM 的 z-index/DOM 顺序决定，与静止态一致。
+- 反向 transform 写在宿主节点自身坐标系：`transform-origin: 0 0`，缩放比取 `First.size / Last.size`，位移按宿主原点偏移换算后除以 `.game-resource-book-scene-world` 的缩放。标题栏激活时内联的"抵消 world"transform 作为 base 与反向 transform 组合，结束帧回到该 base。
+- `begin` 之后的所有布局提交都调 `sync`：比较每个节点的布局签名，变化时取消旧动画、重新测量，以**当前视觉矩形**（含运行中的 transform）为起点重基到新的干净终点。转场进行中用剩余时长（`startTime + 420 - now`，下限 80ms），空闲布局变化用完整 420ms。卡片预览尺寸是异步到达的，因此"动画期间甚至动画结束之后"的二次布局变化同样是动画而不是瞬移。窗口/容器尺寸变化与拖拽中的卡片不做布局动画。
+- 目标不可见的节点（内联 `opacity` 为 0）钉在 First 位置淡出，没有 First 的挂载节点淡入；搜索/排序导致的卸载保留一帧后用同一套淡出撤下，进入栏目期间其他栏目保留挂载淡出，返回总览时源栏目未回到摞上的卡片按子画布布局淡出。转场时长统一 420ms；动画创建失败、零尺寸、容器尺寸变化或 `prefers-reduced-motion` 时不创建动画，也不等待定时器。
+- 再次导航先读取当前像素位置，再取消旧动画并重新建立目标；token 隔离旧 promise，过期完成和取消均不能提交新状态。
 - 缩放、适应内容和空白拖动先结束视觉转场再执行用户输入；转场中的资源卡 pointer-down 不启动持久化拖拽。普通滚轮只平移当前视图，Ctrl/Meta 滚轮以指针为锚点缩放，均不切换栏目。
 - viewport 只属于用户交互状态，按主画布以及 `sortMode/category` 隔离保存。转场不插值也不持久化 viewport；测量主画布缩略入口时先逆变换回布局坐标，避免缩放后的 DOMRect 被二次缩放。只有真实非零测量才能标记首次 fit 完成。
 
-验收使用 `resourceBookController.test.ts`、`resourceBookModel.test.ts`、`resourceBookViewport.test.ts` 和 `appSurface.test.ts`；页面 `.suite.ts` 由 `appSurface.test.ts` 注册，不能作为独立 Vitest 文件运行。真实浏览器需覆盖总览/栏目往返、连续改选、滚轮平移、缩放、尺寸变化、减少动画偏好，以及快照图片和字体的正确比例。jsdom 不模拟真实插值，不能代替浏览器验收。
+验收使用 `resourceBookController.test.ts`、`resourceBookLayout.test.ts`、`resourceBookModel.test.ts`、`resourceBookViewport.test.ts` 和 `appSurface.test.ts`；页面 `.suite.ts` 由 `appSurface.test.ts` 注册，不能作为独立 Vitest 文件运行。真实浏览器需覆盖总览/栏目往返、连续改选、滚轮平移、缩放、尺寸变化、减少动画偏好，以及真实元素的图片和字体比例。jsdom 不实现 Web Animations，只覆盖几何计算、状态机与调用契约，不能代替浏览器验收。
 
 ### 2026-09-05 子画布无限平移与初始可读比例
 
 子画布改为固定视口加可无限平移的 world 层：视口本身保持 `overflow: hidden`，平移和缩放只作用于 `.game-resource-book-scene-world`，不再让内容容器的边界限制拖动范围。首次 fit（包括隐藏分页画布提前完成的 fit）统一保证比例不低于 `1:1`，避免子画布展开后卡片缩成不可读的小块；用户后续主动缩放或平移的视口仍按每个分类独立保留。新增 viewport 回归测试覆盖初始可读比例和超出内容边界双向平移。
 
-返回主画布时立即提交主画布布局，由独立快照层完成缩回；world/main viewport 不播放附加动画。
+返回主画布时立即提交主画布布局，由真实元素 FLIP 完成缩回；world/main viewport 不播放附加动画。
 
 总览和栏目视图同样使用固定铺满 manager 的交互视口，只有内部 world 层承担平移和缩放，内容层不裁剪缩略入口。空白拖动允许双向越过全部内容边界；移走内容后仍可在原视口继续拖动。普通滚轮/触控板平移，Shift 滚轮横向平移，Ctrl/Meta 滚轮以指针为锚点缩放；wheel 监听阻止浏览器滚动或页面缩放，但不切换栏目。总览/栏目往返保留总览原有位置和比例，只有主动适应内容才复位。
 
 ## 2026-09-04 资源画本 UI 阶段补充
 
-资源工作台采用“主画布 + 子画布”的统一画本模型。主画布展示各子画布的缩略入口，内部按资源类型显示有限层叠卡片，最多三层，更多资源以虚化卡片提示。主画布预览和子画布展开态复用同一套卡片视觉与标题栏结构，共享元素快照从当前屏幕位置过渡到目标位置。子画布标题栏提供缩回主画布的按钮；子画布互切直接到达目标，不强制经过主画布。
+资源工作台采用“主画布 + 子画布”的统一画本模型。主画布展示各子画布的缩略入口，内部按资源类型显示有限层叠卡片，最多三层，更多资源以虚化卡片提示。主画布预览和子画布展开态复用同一套卡片视觉与标题栏结构，同一批 DOM 节点从当前屏幕位置过渡到目标位置。子画布标题栏提供缩回主画布的按钮；子画布互切直接到达目标，不强制经过主画布。
 
 本阶段先实现前端 UI、导航状态和转场表现，资源真实跨画布移动、主画布正式资源登记、上传/生成任务、版本绑定以及 UI 编辑器导入与 UI 包工作流继续沿用现有权威链路，待 UI 编辑器完善后再接入。临时画本视图状态不得替代 manifest、草稿或其它后端业务真相。
 
@@ -174,6 +175,7 @@
 
 ```powershell
 npm run ai-game-creator-shell:typecheck
+node node_modules/vitest/vitest.mjs run apps/ai-game-creator-shell/tests/resourceBookController.test.ts apps/ai-game-creator-shell/tests/resourceBookLayout.test.ts apps/ai-game-creator-shell/tests/resourceBookModel.test.ts apps/ai-game-creator-shell/tests/resourceBookViewport.test.ts
 node node_modules/vitest/vitest.mjs run apps/ai-game-creator-shell/tests/assetCanvasSurface.test.tsx apps/ai-game-creator-shell/tests/projectResourceLiveIntegration.test.tsx apps/ai-game-creator-shell/tests/resourceCanvasLayoutModel.test.ts apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts apps/ai-game-creator-shell/tests/useProjectResourceCardPreviews.test.ts apps/ai-game-creator-shell/tests/resourceCanvasLayoutContract.test.ts
 node node_modules/vitest/vitest.mjs run apps/ai-game-creator-shell/tests/appSurface.test.ts
 cargo fmt --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml -- --check