补记 Node 26 下 vitest jsdom 用例的 localStorage 坑

- pitfalls 记录：Node 26 的实验性 globalThis.localStorage 会顶掉 jsdom 的 Storage，导致只声明 jsdom 的用例读到 undefined
- 给出跑法：NODE_OPTIONS=--localstorage-file=… 后 clientApi 与 chatPromptPolish 共 26 项转绿
- 里程碑证据更新为全量结果：125 files / 1676 passed / 17 skipped，tsc exit 0

docs/project-memory/plans/【里程碑】DirectProject聊天真相源收敛-2026-09-16.md

@@ -63,7 +63,7 @@ AGC 项目开发对话的显示与恢复只依赖两项输入：**项目对话
 
 ## 证据要求
 
-- 自动化（已跑）：`cargo test direct_thread`（25 条）、`cargo test direct_project_history`（20 条）、`cargo test export_bindings`（生成绑定与工作区无差异）、`npx vitest run apps/ai-game-creator-shell/tests/appSurface.test.ts`（468 passed / 17 skipped）、`directThreadChat.test.ts` + `directTurnPresentation.test.ts` 单测、TypeScript 类型检查、ESLint 与 `prettier`。
+- 自动化（已跑）：`cargo test direct_thread`（25 条）、`cargo test direct_project_history`（20 条）、`cargo test export_bindings`（生成绑定与工作区无差异）、`NODE_OPTIONS=--localstorage-file=… npx vitest run apps/ai-game-creator-shell/tests`（125 files / 1676 passed / 17 skipped）、`npx tsc -p apps/ai-game-creator-shell/tsconfig.json --noEmit`（exit 0）、ESLint 与 `prettier`。
 - 运行时（待补）：真实 app-server 会话下的新回合、杀进程重开、页面重进、分页与终止。
 - 边界：订阅过期、回执竞态、不可显示切片、无 `turn.completed` 的残回合、工具输出超长截断与脱敏。
-- 已知环境缺口：本容器内 `rehype-highlight` 未安装且远端拉包被策略禁用，`ChatMarkdownMessage` / `AgentMessageContent` 与 `chatPromptPolish` / `clientApi` 的环境型失败与本里程碑改动无关。
+- 环境注意：`rehype-highlight` 已装齐后 `ChatMarkdownMessage` / `AgentMessageContent` 转绿；Node 26 下 vitest 的 jsdom 用例需要 `--localstorage-file` 才能拿到 `window.localStorage`（`clientApi.test.ts` / `chatPromptPolish.test.tsx`），已记入 `docs/project-memory/shared-memory/pitfalls.md`。

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

@@ -5616,3 +5616,10 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - fixture 子进程统一清除 `GIT_*` 环境，并用一次性外层 linked worktree 验证引用、索引、配置不变；原有工程检查规则保持完整，不能用逐项关闭规则修复 fixture 污染。
 - Vitest 的 `toHaveBeenCalledWith` 匹配任意一次调用，失败输出会列出其它命令；应先定位相同命令的真实参数差异，不能由其它调用的序号推断时序故障。
 - 存在后台轮询的 IPC mock 不应要求目标命令占据全局最后一次调用。验证刷新时先记录调用边界，再筛选该边界之后的目标命令，严格核对其最后一次参数，避免后台查询影响断言，也避免旧调用掩盖刷新未执行。
+
+## 2026-09-16 Node 26 下 vitest 的 jsdom 用例拿不到 window.localStorage
+
+- **现象**：只声明 `@vitest-environment jsdom` 的用例里 `window.localStorage` 是 `undefined`（典型报错 `Cannot read properties of undefined (reading 'clear')`）；而 `appSurface.test.ts` 里同样访问 `window.localStorage` 却一切正常。
+- **原因（已核对，不是推断）**：Node 26 在 `globalThis` 上定义了实验性 `localStorage` 访问器，不传 `--localstorage-file` 时它返回 `undefined`。vitest 0.34 的 jsdom 环境把 jsdom window 的描述符复制到全局时，不会覆盖 `globalThis` 上已存在的键，于是 jsdom 真正的 `Storage` 被 Node 的 `undefined` 顶掉。`appSurface` 之所以不受影响，是因为 `apps/ai-game-creator-shell/tests/appSurface/harness.ts` 自己用 `Object.defineProperty(window, 'localStorage', …)` 挂了内存实现。
+- **处理**：跑这类用例时给 Node 加 `--localstorage-file`，例如 `NODE_OPTIONS="--localstorage-file=/tmp/vitest-node-localstorage" npx vitest run <files>`；`apps/ai-game-creator-shell/tests/clientApi.test.ts` 与 `chatPromptPolish.test.tsx` 加这个开关后 26 项全绿。不要改业务代码或往测试里塞假 storage 来绕过。
+- **关联**：`vitest.config.ts`（`environment: 'node'` + 用例内 docblock 切 jsdom）、`apps/ai-game-creator-shell/tests/appSurface/harness.ts` 的内存 localStorage 垫片。