suzmii
2a157ea6f8
预览可见性门禁等 root 就绪再建 observer，并把登记表补挂齐
真机现场：同一屏里 `idle` 与 `loaded` 交错，12 张相交卡从未入队（`idle` 的语义就是「从未请求」，不是被淘汰回退）。根因在 observer 的**创建时机**：`useProjectResourceCardPreviews` 建 IntersectionObserver 时把 `intersectionRootRef.current ?? canvasRef.current` 直接当 root 传下去，而 root 是资源画本容器、由被观察卡片所在的子树持有。创建那一刻 root 还是 `null` 时，浏览器会**退回按视口判定**，于是被画本容器裁掉的卡片永远报「不可见」，可见性门禁再也不放行它们 —— 卡面只剩占位图标，且没有任何错误提示。
- `useProjectResourceCardPreviews`：root 为 `null` 时**不建 observer**，等 root 就绪后由卡片注册触发的 `rootEpoch` 重建。判据是「卡片一定渲染在画本容器内部」，所以**有卡片注册本身就等价于 root 已就绪**，不需要新增跨组件契约、也不必改 `index.tsx`。
- 新增 `attachObservedCards()`：observer 就绪或重建后，按登记表把**每一张已注册卡片**补挂一遍。此前只在新 observer 创建时补挂一次，注册与创建分属不同 effect 存在时序窗口，错过那次补挂的卡会停在登记表里却从未被观察。
- root 未变且 observer 已在时只补挂、不重建，避免每次渲染重建观察器。
- `observePreview` 在没有 `IntersectionObserver` 的环境（如单测）保持静默，不制造多余渲染。
测试（`tests/useProjectResourceCardPreviews.test.ts` 新增 3 条契约）：
- 「不在热预取窗口内的可见卡不得停在 idle」：注册 20 张、`eagerPreviewLimit: 12`，断言注册进 observer 的元素数等于注册数、回调报可见后全部落 `loaded`、且没有一张停留在未请求状态；
- 「等真正的 root 就绪后再观察并加载」：root 首次为 `null` 时**不得建 observer**（否则按视口判定），注册后必须以真正的 root 建出来并完成加载；
- 「建 observer 之前就注册的卡要被补挂」：断言 observer 就绪后登记表里的每一张都在观察集合内，且报可见后全部 `loaded`。
变异验证：把 root 守卫退回旧行为（允许 root 为 `null` 时照建 observer）后，「等真正的 root 就绪」这条立即失败（`expected [] to have a length of 0 but got 1`）；恢复后 19/19 通过。断言不是恒真假守卫。
边界说明：只改预览 hook 与它的测试，未动 `index.tsx` / `styles.css` / `resourceBookLayout.ts`（均在他人手上），未放宽任何既有断言、未取消可见性门禁（仍是按需加载）。
验证：`npm run test -- apps/ai-game-creator-shell/tests` 84 files passed / 1216 passed / 4 skipped / 0 failed；`src/components/image-editor` 1385 passed；typecheck exit 0；check:encoding 4379 文件；prettier 与 eslint 干净；`git diff --check` 干净。
2026-09-11 15:31:29 +08:00
..
2026-09-05 19:48:27 +08:00
2026-09-11 15:31:29 +08:00
2026-09-01 17:00:44 +08:00
2026-09-01 17:00:44 +08:00
2026-08-22 13:17:26 +08:00