Match3D & Puzzle: runtime UI, assets, drag fix

Backend: stop treating background music as a required draft asset and remove auto-submit/plan for background music; load persisted generated UI/assets into Match3D agent session responses (added helpers to resolve profile id and fetch existing generated assets). Frontend: make Match3D result preview reuse runtime UI styles, unify runtime settings entry, update PuzzleRuntime to apply immediate pointermove transforms (disable drag transition), use SVG clipPath for merged piece rounding, ensure PuzzleRuntimeShell supplies platform theme classes, and adjust related tests. Docs & logs: update decision log, pitfalls and product docs to reflect these changes.

.hermes/shared-memory/decision-log.md

@@ -16,6 +16,54 @@
 
 ---
 
+## 2026-05-15 抓大鹅结果页 UI 预览复用运行态布局
+
+- 背景：抓大鹅结果页 `素材配置 > UI` 的预览弹层曾手写简化 HUD 和容器布局，和真实运行态顶部关卡卡片、右上设置入口、容器图定位及槽位样式出现漂移。
+- 决策：结果页 UI 预览只组合 `match3dRuntimeUiStyles` 中的运行态 HUD、棋盘、容器图和槽位样式常量；运行态尺寸或视觉层级调整时，同步由这些常量影响预览，不再在结果页单独维护另一套预览 UI。
+- 影响范围：`src/components/match3d-result/Match3DResultView.tsx`、`src/components/match3d-runtime/Match3DRuntimeShell.tsx`、`src/components/match3d-runtime/match3dRuntimeUiStyles.ts`、抓大鹅结果页测试和玩法链路文档。
+- 验证方式：执行 `npm run test -- src/components/match3d-result/Match3DResultView.test.tsx`、`npm run test -- src/components/match3d-runtime/Match3DRuntimeShell.test.tsx`，确认预览顶部 HUD、设置入口、容器图定位和槽位样式与运行态一致。
+- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-05-15 拼图拖拽视觉即时跟手且拼块裁切圆角
+
+- 背景：拼图运行态在触控拖拽时不能有追手延迟，同时拼图片需要真实圆角裁切，合并后的 L 形 / 凹形块不能靠单格圆角拼接。
+- 决策：`PuzzleRuntimeShell` 拖拽视觉在 `pointermove` 期间直接写入当前可见拼块 DOM 的 `translate3d(...)`，拖拽阶段禁用 transform transition，不依赖后端回包、React 重渲染或 `requestAnimationFrame` 队列。拖动过程中不展示拼块选中态或底部“已选择”提示，选中状态只保留给点击交换语义。单块通过 `buildRoundedGridCellClipPath()` 裁切独立圆角；合并块视觉层必须用 SVG 原生 `clipPath` 裁切整体外轮廓，不只依赖 HTML `clip-path:url(#...)`，外凸角和内凹角分开计算半径，内凹角半径更大以避免移动端看起来仍是直角。
+- 影响范围：拼图运行态拖拽手感、`puzzleRuntimeShape` 圆角路径、拼图运行态测试和玩法链路文档。
+- 验证方式：执行 `npm run test -- src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx`、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-05-15 拼图运行态点击弹层不使用像素素材框
+
+- 背景：拼图运行态主界面已经切到平台主色主题，但提示和设置弹层仍复用像素九宫格素材框，和当前拼图视觉不一致。
+- 决策：拼图运行态的提示、设置等点击弹层跟随 `puzzle-runtime-*` 主色主题，使用普通圆角主题面板和 CSS 变量分层，不再套 `pixel-nine-slice` / `pixel-modal-shell` 或 `UI_CHROME.modalPanel`。
+- 影响范围：`PuzzleRuntimeShell` 的道具确认弹窗、设置弹窗、拼图运行态样式和玩法链路文档。
+- 验证方式：执行 `npm run test -- src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx`，确认提示和设置 dialog 不包含像素框类名。
+- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-05-15 拼图运行态壳层必须自带平台主题类
+
+- 背景：`/puzzle` 直达页和运行态提前返回分支不一定挂在外层平台壳里，若壳层只依赖父级主题类，就会出现修改已经生效但页面看起来还是旧样式的错觉。
+- 决策：`PuzzleRuntimeShell` 自身在正常运行态和等待态都补齐 `platform-ui-shell platform-theme platform-theme--light|dark`，让直达页和平台内嵌页共享同一套主题变量。
+- 影响范围：`PuzzleRuntimeShell` 根容器、路由直达页、拼图运行态测试和玩法链路文档。
+- 验证方式：执行 `npm run test -- src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx` 与 `npm run typecheck`，确认壳层 className 包含平台主题类。
+- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-05-15 抓大鹅草稿自动编排不再要求背景音乐
+
+- 背景：抓大鹅音频入口关闭后，草稿生成仍可能在后端自动编排中调用 Suno，导致“提交 Suno 背景音乐任务失败”阻断草稿生成。
+- 决策：`match3d_compile_draft` 的完成条件只包含 2D 五视角物品图片、UI 背景和容器图；点击音效只在 `generateClickSound=true` 的历史配置下作为可选补齐。背景音乐字段仅作为历史兼容传递，不再由草稿自动生成或补齐。
+- 影响范围：`api-server` Match3D 草稿资产编排、抓大鹅音频关闭口径、玩法链路文档。
+- 验证方式：执行 `cargo test -p api-server match3d_generated_assets_require_only_images_when_click_sound_is_closed --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`。
+- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-05-15 抓大鹅运行态右上角统一为设置入口
+
+- 背景：抓大鹅运行态右上角原先直接暴露重新开始按钮，和拼图的设置入口口径不一致，也不利于把设置、重开和后续扩展动作收口到统一面板。
+- 决策：`Match3DRuntimeShell` 右上角改为设置按钮，点击后打开独立设置面板；重新开始动作仅放在设置面板内，结算弹层继续保留再来一局。拼图右上角设置图标同步改为非像素风 `lucide-react` `Settings` 图标。
+- 影响范围：`src/components/puzzle-runtime/PuzzleRuntimeShell.tsx`、`src/components/match3d-runtime/Match3DRuntimeShell.tsx`、对应测试和玩法链路文档。
+- 验证方式：执行 `npm run test -- src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx src/components/match3d-runtime/Match3DRuntimeShell.test.tsx`，确认拼图设置按钮不再渲染像素图片、抓大鹅右上角打开设置面板且面板内可重新开始。
+- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## 2026-05-15 汪汪声浪和宝贝识物入口设为敬请期待
 
 - 背景：当前需要暂时关闭汪汪声浪和宝贝识物两个模板的创建链路，但仍保留创作 Tab 中的模板占位。

.hermes/shared-memory/pitfalls.md

@@ -70,6 +70,22 @@
 - 验证：`npm run test -- src\services\match3dGeneratedModelCache.test.ts src\components\match3d-result\Match3DResultView.test.tsx src\components\match3d-runtime\Match3DRuntimeShell.test.tsx`；平台推荐流定向跑 `RpgEntryFlowShell.agent.interaction.test.tsx` 中的 Match3D runtime assets 用例；`npm run typecheck`。
 - 关联：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【项目基线】当前产品与工程约束-2026-05-15.md`。
 
+## 抓大鹅草稿关闭背景音乐后仍触发 Suno 先查后端自动编排
+
+- 现象：用户已关闭抓大鹅草稿里的 `生成音效` 或隐藏结果页音频入口，但点击生成仍报 `提交 Suno 背景音乐任务失败`。
+- 原因：入口开关只影响前端可见控件或点击音效，后端 `match3d_compile_draft` 之前还会把 `backgroundMusic` 当作自动完成条件，继续调用 `generate_background_music_asset_for_creation()`，从而直接发 `/suno/submit/music`。
+- 处理：抓大鹅草稿自动编排只保留 2D 物品图片、UI 背景和容器图；背景音乐字段只作为历史兼容数据，不再作为草稿完成条件，也不再由自动编排提交 Suno。
+- 验证：`cargo test -p api-server match3d_generated_assets_require_only_images_when_click_sound_is_closed --manifest-path server-rs/Cargo.toml` 通过，`cargo check -p api-server --manifest-path server-rs/Cargo.toml` 无新的编译问题。
+- 关联：`server-rs/crates/api-server/src/match3d.rs`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`.hermes/shared-memory/decision-log.md`。
+
+## 抓大鹅 UI 预览和实际游戏不一致先查运行态样式复用
+
+- 现象：结果页 `素材配置 > UI` 打开的预览弹层和真实抓大鹅运行态不一致，例如顶部只显示倒计时、右上还是转圈占位、中心容器尺寸或定位和局内不同。
+- 原因：预览层手写了简化 HUD、棋盘尺寸和容器图样式，没有消费 `Match3DRuntimeShell` 运行态使用的共享样式常量。
+- 处理：把运行态 HUD、棋盘、容器图和槽位的 Tailwind 类抽到 `match3dRuntimeUiStyles.ts`，结果页预览只复用这些常量；运行态之后改顶部设置入口、关卡卡片、容器图宽度或棋盘兜底样式时，不要在结果页再写一套。
+- 验证：`npm run test -- src/components/match3d-result/Match3DResultView.test.tsx src/components/match3d-runtime/Match3DRuntimeShell.test.tsx`。
+- 关联：`src/components/match3d-result/Match3DResultView.tsx`、`src/components/match3d-runtime/match3dRuntimeUiStyles.ts`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## 中文乱码与编码风险
 
 - 现象：中文文案、注释、剧情或文档显示为乱码，或被改写成英文。
@@ -469,6 +485,14 @@
 - 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "home recommendation surfaces start failure"`。
 - 关联：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【项目基线】当前产品与工程约束-2026-05-15.md`。
 
+## 推荐页拼图改造返回后又卡在进入中
+
+- 现象：推荐页进入拼图作品后点击改造，返回推荐页时卡在“正在进入拼图关卡”或空白加载态，像是作品还在启动。
+- 原因：改造或其他页面流程会清掉当前 `puzzleRun`，但推荐页自动启动逻辑曾只检查 `activeRecommendEntryKey` 是否仍在推荐列表中；旧 key 还在、玩法 run 已丢失时，会继续渲染失效的 `PuzzleRuntimeShell` 占位。
+- 处理：从推荐页拼图进入改造结果页时，先收口推荐嵌入态；推荐页自动启动逻辑还必须校验当前推荐作品对应的 runtime 数据是否存在，例如拼图要有 `puzzleRun`，抓大鹅要有 `match3dRun`。key 还在但 runtime 不完整时，优先重新启动当前作品，不要误判为已激活。
+- 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "home recommendation starts embedded puzzle|home recommendation surfaces start failure|first puzzle runtime back click can open remix result page"`。
+- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/puzzle-runtime/PuzzleRuntimeShell.tsx`。
+
 ## 推荐页未登录入口误打开公开详情
 
 - 现象：新用户默认在发现页，但点击推荐页或推荐封面后，如果复用公开作品详情入口，可能绕过推荐页“登录后游玩”的产品门禁。
@@ -696,6 +720,13 @@
 - 验证：执行 `npm run test -- src/components/match3d-runtime/Match3DRuntimeShell.test.tsx` 和 `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "Match3D runtime"`；浏览器 Network 中背景和容器 generated path 应先请求 `/api/assets/read-url` 换签，局内出现 `match3d-background-image` 和 `match3d-container-image` 对应图片。
 - 关联：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【项目基线】当前产品与工程约束-2026-05-15.md`。
 
+## 抓大鹅 UI 背景和容器只在物品挂载字段时也要提升
+
+- 现象：草稿恢复、结果页素材配置、UI 预览或试玩时仍显示默认背景 / 默认容器，但 work profile 的首个 `generatedItemAssets[].backgroundAsset` 里已经有生成的背景和容器图。
+- 原因：UI 背景和容器资产没有独立表字段，后端持久化常落在 `generatedItemAssets[].backgroundAsset`；如果 session 映射、结果页 profile、推荐运行态详情补读后不提升到顶层 `generatedBackgroundAsset` 和 `backgroundImageSrc`，后续组件会误判“没有生成 UI 资产”。
+- 处理：Agent session 返回前要用持久化 work profile 资产回填 draft；前端进入结果页、构建草稿 profile、推荐 / 公开作品启动运行态前，都要把 `generatedItemAssets[].backgroundAsset` 提升为顶层背景字段。容器图在运行态和 UI 预览复用同一套居中 `object-contain` 样式，移动端宽度接近屏宽，只有缺失或加载失败时才使用透明参考图兜底。
+- 验证：`cargo test -p api-server match3d_agent_session_response_hydrates_persisted_ui_assets --manifest-path server-rs/Cargo.toml`、`npm run test -- src/components/match3d-result/Match3DResultView.test.tsx src/components/match3d-runtime/Match3DRuntimeShell.test.tsx`。
+
 ## 抓大鹅重启时不要清空 generated 图片签名缓存
 
 - 现象：抓大鹅进入局内时背景或生成物品首帧缺失；点击右上角重启后，局内短暂显示默认积木，过一段时间才换回实际生成素材。
@@ -788,10 +819,18 @@
 
 - 现象：抓大鹅生成的物品视角图裁剪后仍带白边，或者整块纯绿色绿幕背景没有被透明化，运行态看到绿色方块。
 - 原因：素材 sheet 可能是“每格内部绿幕、整张图外圈近白底”，内部绿幕不一定连通到 sheet 外边缘；旧 flood fill 只从外边缘找背景会漏掉这种绿幕块。白底抗锯齿如果不纳入抠像和边缘去污染，也会随裁剪输出成一圈白边。即使顺序已是先整张 sheet 去绿再裁剪，较厚的半透明或混色软绿边仍可能低于高置信绿幕阈值，被当作前景带进独立 PNG。
-- 处理：`api-server` 的 `slice_match3d_material_sheet` 必须先在整张 sheet 上做透明背景后处理：外边缘连通绿幕/近白底清 alpha，非连通但高置信纯绿块也清 alpha，沿整张 sheet 透明背景继续吃掉软绿边，边缘近白和绿幕抗锯齿做透明或去污染；同时保护不够纯的绿色主体像素。不要改成先裁剪单格再去绿。
+- 处理：`api-server` 的 `slice_match3d_material_sheet` 必须先在整张 sheet 上做透明背景后处理：外边缘连通绿幕/近白底清 alpha，非连通但高置信纯绿块也清 alpha，沿整张 sheet 透明背景继续吃掉软绿边；每个视角单图还要以扩大的 PNG 边界带为种子，把连通的浅绿 / 近白抗锯齿边直接改为透明，再按剩余可见主体收紧裁边，同时保护不够纯的绿色主体像素。不要改成先裁剪单格再去绿。
 - 验证：`cargo test -p api-server match3d_material_sheet_slicing --manifest-path server-rs\Cargo.toml` 覆盖非连通绿幕、白边、贴边主体保留和固定 5x5 切图。
 - 关联：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
+## 抓大鹅背景 UI 图出现透明区域先查背景不透明后处理
+
+- 现象：抓大鹅生成的 `9:16` 局内背景 UI 图边缘、角落或局部出现透明 alpha，运行态可能露出底色或透明棋盘底。
+- 原因：背景图和中心容器图是两张资产；容器图需要透明 alpha，但背景图是整屏底图。如果只靠提示词约束，生图服务仍可能返回带透明通道的 PNG。
+- 处理：`generate_match3d_background_image` 上传背景前必须调用 `make_match3d_background_image_opaque()`，把所有半透明 / 全透明像素合成到不透明底色；不要把这条逻辑套到容器图，容器图仍由 `make_match3d_container_image_transparent()` 保持透明。
+- 验证：`cargo test -p api-server match3d_background_image_postprocess_removes_transparent_pixels --manifest-path server-rs\Cargo.toml`，并确认背景提示词包含“全画幅不透明”和“透明 alpha”禁用约束。
+- 关联：`server-rs/crates/api-server/src/match3d.rs`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## 抓大鹅物品详情大方格只做单张大图查看
 
 - 现象：结果页 `素材配置 > 物品` 打开详情后，上方大方格仍显示横向五图带、焦点内框或小缩略图边框，物品本体看起来偏小且像带着素材自带边框。
@@ -856,6 +895,22 @@
 - 验证：运行 `npm run test -- src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx -t "拖拽合并大块时底层单格不显示选中色块"`，并确认合并块拖拽时底层 `[data-piece-id]` 仍为 `puzzle-runtime-piece--merged`。
 - 关联：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【项目基线】当前产品与工程约束-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
+## 拼图拖拽延迟和圆角异常先查即时 DOM 视觉层
+
+- 现象：拼图块拖动时有明显追手延迟，或合并块的 L 形 / 凹形内角圆角和外凸角表现一致、出现方角。
+- 原因：拖拽视觉如果依赖 `requestAnimationFrame` 排队、React 重渲染或 transform transition，会在触控设备上产生一帧以上延迟；合并块如果只靠单格 `border-radius`，无法正确处理整体外轮廓和内凹角。
+- 处理：`PuzzleRuntimeShell` 的 `pointermove` 期间直接给当前单块或合并组 DOM 写入 `translate3d(...)`，拖拽阶段禁用 transform transition，并隐藏拼块选中态和底部“已选择”提示；单块使用 `buildRoundedGridCellClipPath()` 独立裁切，合并块视觉层使用 SVG 原生 `clipPath` 裁切整体轮廓，不只依赖 HTML `clip-path:url(#...)`，外凸角和内凹角半径分开计算，内凹角半径更大。
+- 验证：执行 `npm run test -- src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx`，重点覆盖拖拽 move 后 DOM transform 立即变化且不调用 rAF、拖动中不显示已选择状态、基础单块有圆角裁切、合并块内凹角路径使用更大半径且视觉层为 SVG 裁切。
+- 关联：`src/components/puzzle-runtime/PuzzleRuntimeShell.tsx`、`src/components/puzzle-runtime/puzzleRuntimeShape.ts`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 拼图设置面板当前用时为 0 先查结算字段误用
+
+- 现象：拼图运行态还在游玩时，设置面板里的“当前用时”一直显示 `0:00.00`，但顶部倒计时正常变化。
+- 原因：`currentLevel.elapsedMs` 是通关后的结算字段，进行中关卡按契约通常为 `null`；设置面板若直接格式化该字段，就会被归一化为 0。
+- 处理：设置面板的当前用时按 `startedAtMs`、`pausedAccumulatedMs`、UI 暂停起点、`freezeAccumulatedMs` 和当前冻结区间实时派生，和剩余时间使用同一套暂停 / 冻结扣除口径。
+- 验证：运行 `npm run test -- src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx -t "拼图设置面板展示进行中关卡的实时当前用时"`。
+- 关联：`src/components/puzzle-runtime/PuzzleRuntimeShell.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## 拼图历史图片列表不要把账号归属当图片名
 
 - 现象：拼图创作页或结果页打开“选择历史图片”后，历史列表显示 `账号 user-1` 之类归属文案而不是图片名；`1713686400.000000Z` 这类时间显示为未知；选中后预览或生成参考图可能被怀疑不可用。