Merge branch 'master' into codex/frontend-error-dialogs

# Conflicts:
#	.hermes/shared-memory/decision-log.md
#	server-rs/crates/api-server/src/generated_asset_sheets.rs

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

@@ -40,6 +40,22 @@
 - 验证方式：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx` 应断言任务卡显示 `1 / 1`、领取后显示已完成，且新用户账号也没有 `次级入口` / `填邀请码` 常驻按钮；`npm run typecheck`、`npm run check:encoding` 通过。
 - 关联文档：`docs/【项目基线】当前产品与工程约束-2026-05-15.md`。
 
+## 2026-05-25 抓大鹅发现页官方 demo 使用静态资源与本地运行态
+
+- 背景：本轮抓大鹅资源管线已经生成完整 `level-scene`、背景、UI spritesheet、物品 spritesheet 和切片资源，需要放入发现页作为可试玩验证入口，但不应把一次性本地资源包装成后端正式作品。
+- 决策：发现页官方抓大鹅 demo 固定 profileId 为 `match3d-demo-20260525`、公开作品号为 `M3-20260525`，资源读取 `public/match3d-demo/undersea-candy-market/` 下的静态文件。公开卡片、作品号搜索和详情页沿用平台公开作品详情链路；启动运行态时用 `createLocalMatch3DRuntimeAdapter`，不调用正式 Match3D runtime 后端、不新增 SpacetimeDB schema、不写正式作品统计。
+- 影响范围：`src/data/match3dDemoGalleryCard.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、发现页公开卡片、作品号搜索、Match3D 本地 runtime adapter、玩法链路文档。
+- 验证方式：搜索 `M3-20260525` 能打开“海底糖果集市”并启动本地抓大鹅运行态；正式 Match3D 公开作品仍走 server runtime adapter。
+- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-05-25 抓大鹅运行态 HUD 收敛为拼图同款低遮挡样式
+
+- 背景：抓大鹅游玩阶段 UI 需要继续对齐拼图运行态的观感，同时移除右上角设置入口、灰白半透底板和显眼锅壳，让棋盘区域更专注。
+- 决策：抓大鹅运行态只保留左上透明返回按钮，右上不再显示设置入口；顶部关卡名和倒计时直接复用拼图同款的铭牌 + 下挂计时牌结构、同色板、同造型和 `media/logo.png` 产品 logo；底部备选栏和道具图标保持交互边界但不再显示灰白半透底；中央容器图层可以视觉隐藏，但棋盘命中边界和既有交互逻辑保留。
+- 影响范围：`src/components/match3d-runtime/Match3DRuntimeShell.tsx`、`src/components/match3d-runtime/Match3DRuntimeShell.test.tsx`、`src/index.css`、抓大鹅玩法链路文档。
+- 验证方式：运行态页面不再渲染“打开抓大鹅设置”，顶部仍显示关卡名和倒计时，底部槽位和道具按钮 class 中不含旧白底视觉；相关测试通过后保持该口径。
+- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## 2026-05-25 平台首页推荐按桌面与移动断点分流
 
 - 背景：平台首页的推荐页在桌面与移动端之间原先共用同一套推荐运行态逻辑，容易让桌面和移动两套内容同时启动，也让首页的推荐卡与桌面发现壳互相抢状态。
@@ -56,6 +72,22 @@
 - 验证方式：玩法接入 PRD 和实现验收必须列出作品架链路；若一个玩法具备发布或试玩能力，但缺少 `/api/creation/<play>/works`、前端 client `listWorks`、`CustomWorldCreationHub` props、`creationWorkShelf` adapter 或草稿 / 已发布作品架测试，则接入不算完成。
 - 关联文档：`AGENTS.md`、`.codex/skills/genarrative-play-type-integration/SKILL.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
+## 2026-05-26 统一公开作品主读模型收口
+
+- 背景：各玩法原有 `*_gallery_card_view` / `*_gallery_view` / `custom_world_gallery_entry` 已经足够承载各自 source 投影，但公开列表 / 详情在 `api-server` 侧分散拼装会继续放大重复逻辑和契约漂移。
+- 决策：新增跨玩法统一公开主读模型 `public_work_gallery_entry` 与 `public_work_detail_entry`。各玩法旧公开 view 不删除，退为 source / 兼容路径；`api-server` 公开列表与详情主路径统一读 public view cache，再映射回现有 HTTP DTO。前端首期仍不直接订阅 SpacetimeDB，只走 BFF HTTP。
+- 影响范围：`server-rs/crates/spacetime-module`、`server-rs/crates/spacetime-client`、`server-rs/crates/api-server`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【后端架构】统一公开作品ReadModel设计-2026-05-26.md`。
+- 验证方式：`SELECT * FROM public_work_gallery_entry` 与 `SELECT * FROM public_work_detail_entry` 可作为 `api-server` 长期订阅目标；`/api/public-works` 与 `/api/public-works/{publicWorkCode}` 走统一 cache；旧 `/api/runtime/<play>/gallery` 响应 shape 保持兼容。
+- 关联文档：`docs/technical/【后端架构】统一公开作品ReadModel设计-2026-05-26.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## 2026-05-26 推荐页拼图下一关 pending 时保留当前运行态
+
+- 背景：推荐页嵌入拼图在点击“下一关”时，`advancePuzzleNextLevel` 的服务端请求会短暂处于 pending。旧逻辑把推荐卡的 `isStartingRecommendEntry` 和拼图局部 busy 混在一起，导致外层直接切回“加载中...”，把当前 `PuzzleRuntimeShell` 一起卸载，视觉上像是切关闪回。
+- 决策：推荐页嵌入拼图切关 pending 期间必须保留当前运行态与棋盘，只让拼图壳内部 busy 表现承接同步；`isStartingRecommendEntry` 只表示推荐作品尚未真正启动出来，不再把已有嵌入拼图 run 的局部 busy 一并当成整卡加载态。若下一关落到相似作品，前端还必须把新作品写回推荐缓存并同步 `activeRecommendEntryKey`，避免运行态进入新作品但推荐卡元信息、分享 / 点赞 / 改造和后续“下一个”仍锚定旧作品。
+- 影响范围：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、推荐页拼图切关测试与平台链路文档。
+- 验证方式：点击推荐页拼图“下一关”后，在 `advancePuzzleNextLevel` 未返回前，页面仍应保留 `puzzle-board`，且不出现 `加载中...` 占位；返回相似作品后，当前推荐卡的 `作品信息` 应显示新作品标题。
+- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## 2026-05-24 创作 Tab banner 轮播只展示主题赛
 
 - 背景：创作 Tab banner 曾经把后端入口配置里的默认活动横幅和两个主题赛一起轮播，导致首屏出现 58000 奖池活动卡，和当前只强调拼图 / 抓大鹅主题赛的产品口径不一致。
@@ -1000,3 +1032,11 @@
 - 影响范围：`WoodenFishWorkspace`、`WoodenFishResultView`、`PlatformEntryFlowShellImpl`、敲木鱼 PRD 和平台入口链路文档。
 - 验证方式：工作台首屏不再出现标题 / 简介 / 标签输入；结果页修改后点试玩或发布会先写回当前作品信息。
 - 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-05-26 前端不外露图片模型名
+
+- 背景：拼图与相关结果页、生成进度和错误提示里直接显示 `gpt-image-2`、`gemini-3.1-flash-image-preview`、`image-2` 等名称，会把内部模型路由暴露给普通用户。
+- 决策：前端展示层统一改用产品化名称，如“标准模式”“创意模式”，以及“素材”“图片生成模式”等中性文案；内部 `imageModel`、`generationProvider` 和后端契约值保留不变，只改 UI 文案与错误提示。
+- 影响范围：拼图图片模型选择器、拼图结果页关卡重生成面板、拼图生成进度文案、宝贝识物结果页占位提示和相关错误提示。
+- 验证方式：前端可见文本中不再出现 `gpt-image-2` / `gemini-3.1-flash-image-preview` / `image-2 资源`；相关交互测试改为断言产品化模式名，但提交 payload 仍保持原有模型 ID。
+- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

.hermes/shared-memory/pitfalls.md

@@ -55,6 +55,14 @@
 - 验证：`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`。
 
+## 草稿作品架打开结果页返回必须回草稿 Tab
+
+- 现象：从草稿 Tab 作品架点击已有草稿进入结果页后，点结果页返回会跳回创作 Tab 模板入口，用户需要重新切回草稿页才能继续找原草稿。
+- 原因：平台壳层只按结果页类型硬编码返回创作入口，没有记录本次创作流是从草稿作品架打开；如果来源标记没有在新建入口时重置，还可能污染下一条创作链路。
+- 处理：从作品架打开任一玩法草稿时标记返回目标为 `draft-shelf`；从创作 Tab 新建、打开模板或退出非草稿来源工作区时重置为 `create`；结果页返回和工作区退出统一消费这个返回目标，并在消费后复位。
+- 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "puzzle draft result back button returns to draft hub when opened from shelf|agent draft result back button returns to draft hub without syncing result profile"`。
+- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## 拼图生成页轮询不要绑展示 phase 或不稳定 setter
 
 - 现象：拼图创作进入生成中页后，`/api/runtime/puzzle/agent/sessions/{sessionId}` 会在 0.3 到 0.5 秒内被反复 GET，看起来像轮询风暴，而不是 3 秒一次的正常刷新。
@@ -1560,6 +1568,14 @@
 - 验证：`curl.exe -i http://127.0.0.1:8082/api/creation-entry/config` 返回 `200` 且包含 `baby-object-match`；前端草稿页作品架重新渲染。
 - 关联：`server-rs/crates/api-server/src/state.rs`、`server-rs/crates/api-server/src/creation_entry_config.rs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
+## 抓大鹅物品 spritesheet 偏移先查 alpha 连通域切片是否启用
+
+- 现象：抓大鹅物品图集里大多数素材显示不全、被裁碎、位置整体偏移，甚至切出来像拼贴块。
+- 原因：旧链路只按 `10x10` 固定格线裁切，遇到模型输出的透明图集稍有偏移、跨格或留白不均时就会把主体切坏。现在后端优先按透明 alpha 连通域识别真实素材矩形，再按原图从上到下、从左到右排序；只有识别数量不足时才回退旧网格切法。
+- 处理：优先检查 `generated_asset_sheets.rs` 的 alpha 连通域切片是否生效，再查 `item_assets.rs` 是否还在透传旧的固定格线语义。不要只改前端显示比例。
+- 验证：定向测试 `cargo test -p api-server generated_asset_sheet_two_items_per_row --manifest-path server-rs/Cargo.toml -- --nocapture` 应通过，且错位透明样本应按连通域切出完整视图。
+- 关联：`server-rs/crates/api-server/src/generated_asset_sheets.rs`、`server-rs/crates/api-server/src/match3d/item_assets.rs`。
+
 ## 个人中心不再保留直达“存档”按钮入口
 
 - 现象：2026-05-25 起，移动端“我的”页顶部改为品牌行 + 扫码 / 设置按钮，设置区和次级入口不再提供独立的 `存档` 按钮；用户仍可在“玩过”弹窗里查看可继续存档。