fix: restore puzzle runtime url state

.hermes/shared-memory/pitfalls.md

@@ -23,6 +23,30 @@
 - 验证：点拼图 / 抓大鹅 / 汪汪声浪卡片后，应看到各自既有工作台内容，例如测试中的 `拼图工作区：missing-session`、`抓大鹅工作区：missing-session` 或 `汪汪声浪配置表单`，并且不再出现“X 创作入口”空白页。
 - 关联：`src/components/platform-entry/platformEntryTypes.ts`、`src/routing/appPageRoutes.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`。
 
+## 创作流程刷新恢复必须写私有 query
+
+- 现象：创作生成页或结果页刷新后回到空白工作区、平台首页，或者从作品详情返回时错误复用了别的玩法草稿。
+- 原因：部分创作流程只把 `sessionId` / `profileId` / `draftId` / `workId` 放在前端内存里，没有写进 URL；也曾把写 URL 放在 stage 切换前，`writeCreationUrlState` 因为还停在非创作路径而直接跳过。若跨玩法或公开详情继续保留私有 query，还会污染 `/works/detail?work=...`。
+- 处理：创作页只使用私有 query `sessionId`、`profileId`、`draftId`、`workId` 做刷新恢复，不复用公开 `work` 参数；`pushAppHistoryPath` 只在同一创作流内保留这些 query，离开创作流或切到另一个玩法必须清掉；手动 draft 打开、生成完成和保存回调要在路由已经切到 `/creation/<play>` 后再调用 `writeCreationUrlState`。
+- 验证：`npm run test -- src/services/creationUrlState.test.ts src/routing/appPageRoutes.test.ts src/components/platform-entry/usePlatformCreationAgentFlowController.test.tsx`；手测生成页 / 结果页刷新仍恢复同一草稿，打开公开作品详情 URL 不带私有恢复参数。
+- 关联：`src/services/creationUrlState.ts`、`src/routing/appPageRoutes.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 拼图生成页轮询不要绑展示 phase 或不稳定 setter
+
+- 现象：拼图创作进入生成中页后，`/api/runtime/puzzle/agent/sessions/{sessionId}` 会在 0.3 到 0.5 秒内被反复 GET，看起来像轮询风暴，而不是 3 秒一次的正常刷新。
+- 原因：轮询 `useEffect` 同时依赖了拼图展示 phase 和会随父组件渲染变化的 `setSession` 函数，导致 `puzzleGenerationState` 的进度合并或页面重渲染就会重挂 effect；effect 里又会立即先请求一次 session，于是请求被放大成密集循环。
+- 处理：拼图轮询只绑定 `selectionStage`、`activePuzzleGenerationSessionId` 和“是否仍在生成中”这个布尔条件；`setSession` 通过 ref 保持稳定，不让父组件重新渲染改变轮询器身份。进度 phase 变化只更新展示，不重建轮询。
+- 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "persisted generating puzzle draft"`，并确认恢复生成中草稿后 `getPuzzleAgentSession` 不会因为进度刷新继续连发。
+- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/platform-entry/usePlatformCreationAgentFlowController.ts`、`src/components/platform-entry/usePlatformCreationAgentFlowController.test.tsx`。
+
+## 拼图试玩恢复 query 必须先切到运行态路径再写
+
+- 现象：拼图试玩或正式运行态打开后，刷新会停在“正在进入拼图关卡”，或地址栏只有 `runtimeProfileId`，缺少草稿 `runtimeSessionId`。
+- 原因：`writePuzzleRuntimeUrlState` 只会在当前路径已经是 `/runtime/puzzle` 时写入；如果先触发阶段切换再写 query，或者草稿作品摘要缺少 `sourceSessionId`，就会把恢复参数写丢。`App.tsx` 的 stage 同步也会改 pathname，所以顺序不对时容易只留下部分 query。
+- 处理：进入拼图 runtime 时先 `pushAppHistoryPath('/runtime/puzzle')`，再 `setSelectionStage('puzzle-runtime')`，最后写 `runtimeProfileId`、`runtimeSessionId`、`runtimeLevelId`、`work`、`mode`；草稿 runtime URL state 允许从 `profileId` 反推 `puzzle-session-*`，作为 `sourceSessionId` 的兜底。
+- 验证：`npm test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t \"puzzle draft generation auto starts trial and runtime back opens draft result\"`，确认 `window.location.pathname === '/runtime/puzzle'` 且 `window.location.search` 同时包含 `runtimeProfileId` 和 `runtimeSessionId`。
+- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/services/puzzleRuntimeUrlState.ts`、`src/routing/appPageRoutes.ts`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## 草稿页未读点不要继续用红色 literal
 
 - 现象：草稿页底部 Tab 和作品架的未读点视觉上仍像红点，或 glow 仍带红色阴影，和平台暖棕体系不一致。