From 52c6f4282f49d96c3b9ac03fd3612dbbdd706d63 Mon Sep 17 00:00:00 2001 From: kdletters Date: Mon, 8 Jun 2026 17:49:28 +0800 Subject: [PATCH] =?UTF-8?q?=E7=AD=89=E5=BE=85=E6=8E=A8=E8=8D=90=E9=A1=B5?= =?UTF-8?q?=E8=BF=90=E8=A1=8C=E6=80=81=E5=85=A8=E9=83=A8=E8=B5=84=E6=BA=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 推荐页 ready 持续观察运行态图片、背景、音视频和资源 pending 标记 资源换签与玩法图集解析中通过隐藏标记阻止遮罩提前消失 补齐拼图、跳一跳、抓大鹅和敲木鱼运行态资源等待接入 补充推荐页资源等待回归测试和团队文档 --- .hermes/shared-memory/pitfalls.md | 8 + ...玩法创作】平台入口与玩法链路-2026-05-15.md | 2 +- src/components/ResolvedAssetImage.tsx | 46 ++- .../common/RuntimeResourcePendingMarker.tsx | 29 ++ .../jump-hop-runtime/JumpHopRuntimeShell.tsx | 92 +++-- .../match3d-runtime/Match3DRuntimeShell.tsx | 119 +++++- .../PuzzleRuntimeShell.test.tsx | 43 ++ .../puzzle-runtime/PuzzleRuntimeShell.tsx | 51 ++- .../RpgEntryHomeView.recharge.test.tsx | 133 +++++- src/components/rpg-entry/RpgEntryHomeView.tsx | 382 ++++++++++++++++-- .../WoodenFishRuntimeShell.tsx | 11 +- src/hooks/useResolvedAssetReadUrl.ts | 11 +- 12 files changed, 802 insertions(+), 125 deletions(-) create mode 100644 src/components/common/RuntimeResourcePendingMarker.tsx diff --git a/.hermes/shared-memory/pitfalls.md b/.hermes/shared-memory/pitfalls.md index 2f0629bb..16df7cf5 100644 --- a/.hermes/shared-memory/pitfalls.md +++ b/.hermes/shared-memory/pitfalls.md @@ -2083,6 +2083,14 @@ - 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "puzzle draft generation auto starts trial and runtime back opens draft result"`。 - 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 +## 推荐页 ready 不能只等主图或首次 DOM 图片 + +- 现象：移动端推荐页卡面遮罩在作品主图加载后就渐隐，但游戏内 UI 图集、背景、道具图或换签中的 generated 图片还没有准备好，用户会看到运行态半成品或资源闪入。 +- 原因：推荐页 ready probe 如果只扫描首次挂载时已有的 ``，就会漏掉 React effect、`/api/assets/read-url` 换签、spritesheet 解析或后续 state 更新才新增的资源。 +- 处理：推荐页 runtime 遮罩必须持续观察运行态 DOM 内新增图片、内联 `background-image` 和 `data-runtime-resource-pending` 隐藏标记；各玩法对换签中、解析中的资源源头要暴露 pending 标记，失败后释放标记并交给玩法兜底，避免遮罩永久卡住。 +- 验证：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "mobile recommend cover waits for async runtime resources beyond the main image|mobile recommend cover waits until runtime images are ready"`。 +- 关联：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/components/common/RuntimeResourcePendingMarker.tsx`、`src/components/ResolvedAssetImage.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 + ## 拼图文字直创的 compile 回包不等于生成完成 - 现象：只输入文字点击生成拼图时，页面刚进入生成页就弹出“生成任务已完成，可以继续查看草稿。”，随后又提示“请先选择一张正式拼图图片。”，结果页关卡里也没有图。 diff --git a/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md b/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md index 8d697380..e3fce420 100644 --- a/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md +++ b/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md @@ -177,7 +177,7 @@ RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列 跳一跳作品架删除入口必须走 `/api/creation/jump-hop/works/{profile_id}`，并通过 SpacetimeDB 同步删除 work profile、源 session、运行态 run 与事件，再刷新作品架和公开广场；不得只做前端本地隐藏。 -推荐页匿名游玩不再限定为跳一跳。移动端一级 `推荐` Tab 是内嵌运行态刷卡流，会自动选择推荐作品并启动对应玩法；桌面端首页不启动这套移动推荐运行态，而是渲染桌面发现壳，展示 `今日游戏`、`推荐`、`作品分类` 等桌面内容。推荐页候选顺序由前端轻量推荐算法 `platformRecommendation.ts` 统一生成：先按公开作品 key 去重，再使用公开读模型已有的精选来源、近 7 日游玩、点赞、改造、总游玩、发布时间新鲜度、封面和标签完整度做确定性评分，最后优先交错不同玩法类型；只要还有其它玩法候选，就不要连续推荐同一玩法，只有候选池已没有其它玩法时才允许同玩法相邻。该算法不得新增前端业务真相或绕过公开作品 read model。断点事实统一走 `platformEntryResponsive.ts` 的 `usePlatformDesktopLayout()`，平台壳和首页视图必须共用同一个判断，避免桌面发现页与移动推荐页同时挂载、重复触发请求或启动运行态。移动端推荐页拿到推荐作品列表后必须预加载每个作品的卡片封面、主封面和玩法兜底封面；启动或切换作品时先展示当前带玩法标签和标题的作品卡面遮罩，嵌入 runtime 在卡面下层加载，不得再从卡面闪切到另一层单独纯封面图。作品切换提交后，当前 runtime 遮罩接手已在屏幕上的卡面时必须瞬时贴合，不允许再执行“卡面到同一卡面”的淡入或重绘过渡；推荐页 runtime 必须通过统一 `ready` 门控等待对应运行态 run / profile、lazy runtime 组件和 runtime DOM 内图片资源都准备好，`ready` 返回 `true` 后才由外层放开游戏画面并只让卡面遮罩渐隐。遮罩层级必须高于并隔离下层 runtime，防止运行态 HUD、canvas 或高 `z-index` 子层穿透到封面上；ready 前不展示“加载中”文案，但封面内必须保留无文案加载动效或进度条，避免用户误以为卡片损坏，也不得把未准备好的运行态直接暴露给用户。切换推荐作品时，如果上一条作品的启动请求、退出收口或目标玩法 busy 状态尚未结束，应继续显示当前作品卡面遮罩并等待下一轮自动启动；只有目标作品启动明确失败时，才显示“作品暂时无法进入，请稍后再试。”这类失败态。推荐页内拼图通关后的“下一关”属于推荐页统一切卡入口，不能复用拼图 runtime 的跨作品 handoff，也不能直接把当前 run 改写到另一个作品；`activeRecommendEntryKey` 只能由推荐页统一选择下一作品后更新。推荐页嵌入运行态启动时按真实身份分流：已登录用户或本地已有 access token 时继续使用账号 Bearer，但请求选项必须是 local auth impact，避免单卡 401 清空整站登录态；只有确认为匿名访客时才申请短期 Runtime Guest Token，并只把它作为局部请求头传给运行态客户端，不写入全局登录态、不触发 refresh，也不把匿名流量伪装成普通用户。当前覆盖矩阵为：跳一跳、视觉小说、抓大鹅 Match3D、方洞挑战、拼图、敲木鱼、大鱼吃小鱼、汪汪声浪。每个模板的启动请求、推荐页内后续运行态动作以及需要上报的 play/finish/leaderboard/next-level 类请求，都必须继续按该身份分流；公开读取入口仍可匿名读取，创作、个人作品、删除、发布、Remix 等账号/所有权动作仍保持普通用户鉴权。 +推荐页匿名游玩不再限定为跳一跳。移动端一级 `推荐` Tab 是内嵌运行态刷卡流，会自动选择推荐作品并启动对应玩法；桌面端首页不启动这套移动推荐运行态，而是渲染桌面发现壳，展示 `今日游戏`、`推荐`、`作品分类` 等桌面内容。推荐页候选顺序由前端轻量推荐算法 `platformRecommendation.ts` 统一生成：先按公开作品 key 去重，再使用公开读模型已有的精选来源、近 7 日游玩、点赞、改造、总游玩、发布时间新鲜度、封面和标签完整度做确定性评分，最后优先交错不同玩法类型；只要还有其它玩法候选，就不要连续推荐同一玩法，只有候选池已没有其它玩法时才允许同玩法相邻。该算法不得新增前端业务真相或绕过公开作品 read model。断点事实统一走 `platformEntryResponsive.ts` 的 `usePlatformDesktopLayout()`，平台壳和首页视图必须共用同一个判断，避免桌面发现页与移动推荐页同时挂载、重复触发请求或启动运行态。移动端推荐页拿到推荐作品列表后必须预加载每个作品的卡片封面、主封面和玩法兜底封面；启动或切换作品时先展示当前带玩法标签和标题的作品卡面遮罩，嵌入 runtime 在卡面下层加载，不得再从卡面闪切到另一层单独纯封面图。作品切换提交后，当前 runtime 遮罩接手已在屏幕上的卡面时必须瞬时贴合，不允许再执行“卡面到同一卡面”的淡入或重绘过渡；推荐页 runtime 必须通过统一 `ready` 门控等待对应运行态 run / profile、lazy runtime 组件和 runtime DOM 内图片资源都准备好，且必须持续观察后续新增图片、内联 `background-image` 和换签中的资源标记，不能只在首次挂载时扫描主图或封面；`ready` 返回 `true` 后才由外层放开游戏画面并只让卡面遮罩渐隐。遮罩层级必须高于并隔离下层 runtime，防止运行态 HUD、canvas 或高 `z-index` 子层穿透到封面上；ready 前不展示“加载中”文案，但封面内必须保留无文案加载动效或进度条，避免用户误以为卡片损坏，也不得把未准备好的运行态直接暴露给用户。切换推荐作品时，如果上一条作品的启动请求、退出收口或目标玩法 busy 状态尚未结束，应继续显示当前作品卡面遮罩并等待下一轮自动启动；只有目标作品启动明确失败时，才显示“作品暂时无法进入，请稍后再试。”这类失败态。推荐页内拼图通关后的“下一关”属于推荐页统一切卡入口，不能复用拼图 runtime 的跨作品 handoff，也不能直接把当前 run 改写到另一个作品；`activeRecommendEntryKey` 只能由推荐页统一选择下一作品后更新。推荐页嵌入运行态启动时按真实身份分流：已登录用户或本地已有 access token 时继续使用账号 Bearer，但请求选项必须是 local auth impact，避免单卡 401 清空整站登录态；只有确认为匿名访客时才申请短期 Runtime Guest Token，并只把它作为局部请求头传给运行态客户端，不写入全局登录态、不触发 refresh，也不把匿名流量伪装成普通用户。当前覆盖矩阵为：跳一跳、视觉小说、抓大鹅 Match3D、方洞挑战、拼图、敲木鱼、大鱼吃小鱼、汪汪声浪。每个模板的启动请求、推荐页内后续运行态动作以及需要上报的 play/finish/leaderboard/next-level 类请求，都必须继续按该身份分流；公开读取入口仍可匿名读取，创作、个人作品、删除、发布、Remix 等账号/所有权动作仍保持普通用户鉴权。 ## 敲木鱼 diff --git a/src/components/ResolvedAssetImage.tsx b/src/components/ResolvedAssetImage.tsx index 3bccab70..5f662f7b 100644 --- a/src/components/ResolvedAssetImage.tsx +++ b/src/components/ResolvedAssetImage.tsx @@ -1,6 +1,7 @@ import React, { type ImgHTMLAttributes, useEffect, useState } from 'react'; import { useResolvedAssetReadUrl } from '../hooks/useResolvedAssetReadUrl'; +import { RuntimeResourcePendingMarker } from './common/RuntimeResourcePendingMarker'; type ResolvedAssetImageProps = Omit< ImgHTMLAttributes, @@ -19,39 +20,50 @@ export function ResolvedAssetImage({ onError, ...rest }: ResolvedAssetImageProps) { - const { resolvedUrl } = useResolvedAssetReadUrl(src, { + const { resolvedUrl, isResolving, shouldResolve } = useResolvedAssetReadUrl(src, { refreshKey, }); + const normalizedSource = src?.trim() ?? ''; const normalizedFallbackSrc = fallbackSrc?.trim() ?? ''; const [useFallbackSrc, setUseFallbackSrc] = useState(false); const finalSrc = useFallbackSrc && normalizedFallbackSrc ? normalizedFallbackSrc : resolvedUrl || normalizedFallbackSrc; + const pendingMarker = ( + + ); useEffect(() => { setUseFallbackSrc(false); }, [normalizedFallbackSrc, resolvedUrl]); if (!finalSrc) { - return null; + return pendingMarker; } return ( - {alt} { - if ( - normalizedFallbackSrc && - !useFallbackSrc && - finalSrc !== normalizedFallbackSrc - ) { - setUseFallbackSrc(true); - } - onError?.(event); - }} - /> + <> + {pendingMarker} + {alt} { + if ( + normalizedFallbackSrc && + !useFallbackSrc && + finalSrc !== normalizedFallbackSrc + ) { + setUseFallbackSrc(true); + } + onError?.(event); + }} + /> + ); } diff --git a/src/components/common/RuntimeResourcePendingMarker.tsx b/src/components/common/RuntimeResourcePendingMarker.tsx new file mode 100644 index 00000000..d32b2b54 --- /dev/null +++ b/src/components/common/RuntimeResourcePendingMarker.tsx @@ -0,0 +1,29 @@ +type RuntimeResourcePendingMarkerProps = { + source?: string | null; + isPending?: boolean; + kind?: string; +}; + +export const RUNTIME_RESOURCE_PENDING_SELECTOR = + '[data-runtime-resource-pending="true"]'; + +export function RuntimeResourcePendingMarker({ + source, + isPending = true, + kind, +}: RuntimeResourcePendingMarkerProps) { + const normalizedSource = source?.trim() ?? ''; + if (!isPending || !normalizedSource) { + return null; + } + + return ( +