等待推荐页运行态全部资源

推荐页 ready 持续观察运行态图片、背景、音视频和资源 pending 标记资源换签与玩法图集解析中通过隐藏标记阻止遮罩提前消失补齐拼图、跳一跳、抓大鹅和敲木鱼运行态资源等待接入补充推荐页资源等待回归测试和团队文档
2026-06-08 17:49:28 +08:00
parent ccb5023197
commit 52c6f4282f
12 changed files with 802 additions and 125 deletions
--- 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 如果只扫描首次挂载时已有的 `<img>`，就会漏掉 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 回包不等于生成完成

 - 现象：只输入文字点击生成拼图时，页面刚进入生成页就弹出“生成任务已完成，可以继续查看草稿。”，随后又提示“请先选择一张正式拼图图片。”，结果页关卡里也没有图。
--- 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 等账号/所有权动作仍保持普通用户鉴权。

 ## 敲木鱼

--- 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<HTMLImageElement>,
@@ -19,25 +20,35 @@ 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 = (
+    <RuntimeResourcePendingMarker
+      source={normalizedSource}
+      kind="image"
+      isPending={shouldResolve && isResolving}
+    />
+  );

  useEffect(() => {
    setUseFallbackSrc(false);
  }, [normalizedFallbackSrc, resolvedUrl]);

  if (!finalSrc) {
-    return null;
+    return pendingMarker;
  }

  return (
+    <>
+      {pendingMarker}
      <img
        {...rest}
        src={finalSrc}
@@ -53,5 +64,6 @@ export function ResolvedAssetImage({
          onError?.(event);
        }}
      />
+    </>
  );
 }
--- a/src/components/common/RuntimeResourcePendingMarker.tsx
+++ 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 (
+    <span
+      hidden
+      aria-hidden="true"
+      data-runtime-resource-pending="true"
+      data-runtime-resource-src={normalizedSource}
+      data-runtime-resource-kind={kind}
+    />
+  );
+}
--- a/src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx
+++ b/src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx
@@ -30,12 +30,13 @@ import {
  getJumpHopRunDurationMs,
  getJumpHopStatusLabel,
  getJumpHopTileTone,
-  selectJumpHopTileAsset,
  type JumpHopCharacterVisualPosition,
  type JumpHopVisiblePlatform,
  resolveJumpHopCharacterCanvasPosition,
+  selectJumpHopTileAsset,
 } from '../../services/jump-hop/jumpHopRuntimeModel';
 import { useJumpHopLeaderboard } from '../../services/jump-hop/useJumpHopLeaderboard';
+import { RuntimeResourcePendingMarker } from '../common/RuntimeResourcePendingMarker';

 type JumpHopRuntimeJumpPayload = {
  dragDistance: number;
@@ -218,9 +219,12 @@ function JumpHopTileImage({
  platform: JumpHopVisiblePlatform['platform'];
 }) {
  const assetRefreshKey = getJumpHopTileAssetRefreshKey(asset);
-  const { resolvedUrl } = useResolvedAssetReadUrl(asset?.imageSrc, {
+  const { resolvedUrl, isResolving } = useResolvedAssetReadUrl(
+    asset?.imageSrc,
+    {
      refreshKey: assetRefreshKey,
-  });
+    },
+  );
  const [isLoaded, setIsLoaded] = useState(false);
  const [hasError, setHasError] = useState(false);

@@ -234,6 +238,11 @@ function JumpHopTileImage({

  return (
    <div className="jump-hop-runtime__tile-image-stack">
+      <RuntimeResourcePendingMarker
+        source={asset?.imageSrc}
+        kind="image"
+        isPending={isResolving}
+      />
      {shouldShowFallback ? <IsometricFallbackTile platform={platform} /> : null}
      {shouldShowImage ? (
        <img
@@ -258,15 +267,27 @@ function JumpHopTileImage({

 function JumpHopTilePreloadImage({ asset }: { asset: JumpHopTileAsset }) {
  const assetRefreshKey = getJumpHopTileAssetRefreshKey(asset);
-  const { resolvedUrl } = useResolvedAssetReadUrl(asset.imageSrc, {
+  const { resolvedUrl, isResolving } = useResolvedAssetReadUrl(asset.imageSrc, {
    refreshKey: assetRefreshKey,
  });

  if (!resolvedUrl) {
-    return null;
+    return (
+      <RuntimeResourcePendingMarker
+        source={asset.imageSrc}
+        kind="image"
+        isPending={isResolving}
+      />
+    );
  }

  return (
+    <>
+      <RuntimeResourcePendingMarker
+        source={asset.imageSrc}
+        kind="image"
+        isPending={isResolving}
+      />
      <img
        src={resolvedUrl}
        alt=""
@@ -275,6 +296,7 @@ function JumpHopTilePreloadImage({ asset }: { asset: JumpHopTileAsset }) {
        data-testid="jump-hop-tile-preload-image"
        className="jump-hop-runtime__tile-preload-image"
      />
+    </>
  );
 }

@@ -619,26 +641,26 @@ export function JumpHopRuntimeShell({
    profile?.draft.coverComposite,
    profile?.summary.coverImageSrc,
  ].find(isJumpHopGeneratedBackgroundSource);
-  const { resolvedUrl: stageBackgroundUrl } = useResolvedAssetReadUrl(
-    stageBackgroundSource,
-    {
+  const {
+    resolvedUrl: stageBackgroundUrl,
+    isResolving: isStageBackgroundResolving,
+  } = useResolvedAssetReadUrl(stageBackgroundSource, {
    refreshKey: stageBackgroundSource,
-    },
-  );
+  });
  const backButtonAssetSource =
    profile?.backButtonAsset?.imageSrc?.trim() ||
    profile?.draft.backButtonAsset?.imageSrc?.trim() ||
    null;
-  const { resolvedUrl: backButtonAssetUrl } = useResolvedAssetReadUrl(
-    backButtonAssetSource,
-    {
+  const {
+    resolvedUrl: backButtonAssetUrl,
+    isResolving: isBackButtonAssetResolving,
+  } = useResolvedAssetReadUrl(backButtonAssetSource, {
    refreshKey:
      profile?.backButtonAsset?.assetObjectId ||
      profile?.draft.backButtonAsset?.assetObjectId ||
      backButtonAssetSource ||
      undefined,
-    },
-  );
+  });

  useEffect(() => {
    activeRunRef.current = activeRun;
@@ -1313,6 +1335,16 @@ export function JumpHopRuntimeShell({

  return (
    <div className="platform-remap-surface jump-hop-runtime relative h-full min-h-dvh w-full overflow-hidden bg-[#fffdf9] text-slate-950">
+      <RuntimeResourcePendingMarker
+        source={stageBackgroundSource}
+        kind="image"
+        isPending={isStageBackgroundResolving}
+      />
+      <RuntimeResourcePendingMarker
+        source={backButtonAssetSource}
+        kind="image"
+        isPending={isBackButtonAssetResolving}
+      />
      <section
        ref={stageRef}
        data-testid="jump-hop-stage"
--- a/src/components/match3d-runtime/Match3DRuntimeShell.tsx
+++ b/src/components/match3d-runtime/Match3DRuntimeShell.tsx
@@ -32,6 +32,11 @@ import {
  readAssetBytes,
  resolveAssetReadUrl,
 } from '../../services/assetReadUrlService';
+import {
+  buildMatch3DTrayInsertionPlan,
+  resolveMatch3DTrayItemIdToSlotIndexMap,
+  syncMatch3DItemTraySlotIndexes,
+} from '../../services/match3d-runtime/match3dTrayLayout';
 import {
  getMatch3DGeneratedImageViewSources,
  normalizeMatch3DGeneratedItemAssetsForRuntime,
@@ -41,11 +46,6 @@ import {
  loadMatch3DSpritesheetAssetRegions,
  type Match3DDecodedSpritesheetRegion,
 } from '../../services/match3dSpritesheetParser';
-import {
-  buildMatch3DTrayInsertionPlan,
-  resolveMatch3DTrayItemIdToSlotIndexMap,
-  syncMatch3DItemTraySlotIndexes,
-} from '../../services/match3d-runtime/match3dTrayLayout';
 import {
  DEFAULT_RUNTIME_LEVEL_AUDIO_CONFIG,
  playRuntimeClickSound,
@@ -55,6 +55,7 @@ import {
  resolveRuntimeCountdownSecondBucket,
 } from '../../services/runtimeAudioFeedback';
 import { useAuthUi } from '../auth/AuthUiContext';
+import { RuntimeResourcePendingMarker } from '../common/RuntimeResourcePendingMarker';
 import {
  findMatch3DHitItem,
  type Match3DAlphaHitMask,
@@ -398,12 +399,6 @@ function indexMatch3DUiSpritesheetRegions(
  return new Map(regions.map((region) => [region.label, region]));
 }

-function resolveMatch3DImageReadUrlCacheKey(
-  imageSourcesByType: ReadonlyMap<string, readonly string[]>,
-) {
-  return resolveMatch3DImageReadUrlSources(imageSourcesByType).join('|');
-}
-
 function resolveMatch3DImageReadUrlSources(
  imageSourcesByType: ReadonlyMap<string, readonly string[]>,
 ) {
@@ -1047,6 +1042,10 @@ export function Match3DRuntimeShell({
  const [itemSpritesheetViewGroups, setItemSpritesheetViewGroups] = useState<
    Match3DItemSpritesheetViewGroup[]
  >([]);
+  const [isUiSpritesheetResolving, setIsUiSpritesheetResolving] =
+    useState(false);
+  const [isItemSpritesheetResolving, setIsItemSpritesheetResolving] =
+    useState(false);
  const uiSpritesheetRegionByLabel = useMemo(
    () => indexMatch3DUiSpritesheetRegions(uiSpritesheetRegions),
    [uiSpritesheetRegions],
@@ -1077,11 +1076,13 @@ export function Match3DRuntimeShell({
      setUiSpritesheetRegions((current) =>
        current.length > 0 ? [] : current,
      );
+      setIsUiSpritesheetResolving(false);
      return undefined;
    }

    let cancelled = false;
    const controller = new AbortController();
+    setIsUiSpritesheetResolving(true);
    void loadMatch3DSpritesheetAssetRegions({
      source: uiSpritesheetSource,
      labels: MATCH3D_UI_SPRITESHEET_LABELS,
@@ -1093,11 +1094,13 @@ export function Match3DRuntimeShell({
      .then((regions) => {
        if (!cancelled) {
          setUiSpritesheetRegions(regions);
+          setIsUiSpritesheetResolving(false);
        }
      })
      .catch(() => {
        if (!cancelled) {
          setUiSpritesheetRegions([]);
+          setIsUiSpritesheetResolving(false);
        }
      });

@@ -1112,11 +1115,13 @@ export function Match3DRuntimeShell({
      setItemSpritesheetViewGroups((current) =>
        current.length > 0 ? [] : current,
      );
+      setIsItemSpritesheetResolving(false);
      return undefined;
    }

    let cancelled = false;
    const controller = new AbortController();
+    setIsItemSpritesheetResolving(true);
    void loadMatch3DSpritesheetAssetRegions({
      source: itemSpritesheetSource,
      maxRegions: 100,
@@ -1132,11 +1137,13 @@ export function Match3DRuntimeShell({
              runtimeGeneratedItemAssets.map((asset) => asset.itemName),
            ),
          );
+          setIsItemSpritesheetResolving(false);
        }
      })
      .catch(() => {
        if (!cancelled) {
          setItemSpritesheetViewGroups([]);
+          setIsItemSpritesheetResolving(false);
        }
      });

@@ -1315,13 +1322,17 @@ export function Match3DRuntimeShell({
      ),
    [itemSpritesheetViewGroups, runtimeGeneratedItemAssets, run],
  );
+  const imageReadUrlSources = useMemo(
+    () => resolveMatch3DImageReadUrlSources(imageSourcesByType),
+    [imageSourcesByType],
+  );
  const itemSizeByType = useMemo(
    () => buildMatch3DItemSizeByType(run, runtimeGeneratedItemAssets),
    [runtimeGeneratedItemAssets, run],
  );
  const imageReadUrlCacheKey = useMemo(
-    () => resolveMatch3DImageReadUrlCacheKey(imageSourcesByType),
-    [imageSourcesByType],
+    () => imageReadUrlSources.join('|'),
+    [imageReadUrlSources],
  );
  const [resolvedImageSources, setResolvedImageSources] = useState<
    Map<string, string>
@@ -1329,6 +1340,8 @@ export function Match3DRuntimeShell({
  const [failedImageSources, setFailedImageSources] = useState<Set<string>>(
    () => new Set(),
  );
+  const [isImageSourcesResolving, setIsImageSourcesResolving] =
+    useState(false);
  const resolvedImageSourceEntriesByType = useMemo(
    () =>
      buildResolvedMatch3DImageSourceEntriesByType(
@@ -1354,6 +1367,12 @@ export function Match3DRuntimeShell({
    useState('');
  const [resolvedContainerImageSrc, setResolvedContainerImageSrc] =
    useState('');
+  const [isBackgroundMusicResolving, setIsBackgroundMusicResolving] =
+    useState(false);
+  const [isBackgroundImageResolving, setIsBackgroundImageResolving] =
+    useState(false);
+  const [isContainerImageResolving, setIsContainerImageResolving] =
+    useState(false);
  const clickSoundByTypeId = useMemo(() => {
    if (!run) {
      return new Map<string, string>();
@@ -1397,16 +1416,19 @@ export function Match3DRuntimeShell({
    const source = backgroundMusicSrc?.trim() ?? '';
    if (!source) {
      setResolvedBackgroundMusicSrc('');
+      setIsBackgroundMusicResolving(false);
      return undefined;
    }
    if (!isGeneratedLegacyPath(source)) {
      setResolvedBackgroundMusicSrc(source);
+      setIsBackgroundMusicResolving(false);
      return undefined;
    }

    let cancelled = false;
    const controller = new AbortController();
    setResolvedBackgroundMusicSrc('');
+    setIsBackgroundMusicResolving(true);
    void resolveAssetReadUrl(source, {
      signal: controller.signal,
      expireSeconds: 300,
@@ -1420,6 +1442,11 @@ export function Match3DRuntimeShell({
        if (!cancelled) {
          setResolvedBackgroundMusicSrc('');
        }
+      })
+      .finally(() => {
+        if (!cancelled) {
+          setIsBackgroundMusicResolving(false);
+        }
      });

    return () => {
@@ -1439,15 +1466,19 @@ export function Match3DRuntimeShell({
  useEffect(() => {
    if (!backgroundAssetSrc) {
      setResolvedBackgroundImageSrc('');
+      setIsBackgroundImageResolving(false);
      return undefined;
    }
    if (!isGeneratedLegacyPath(backgroundAssetSrc)) {
      setResolvedBackgroundImageSrc(backgroundAssetSrc);
+      setIsBackgroundImageResolving(false);
      return undefined;
    }

    let cancelled = false;
    const controller = new AbortController();
+    setResolvedBackgroundImageSrc('');
+    setIsBackgroundImageResolving(true);
    void resolveAssetReadUrl(backgroundAssetSrc, {
      signal: controller.signal,
      expireSeconds: 300,
@@ -1461,6 +1492,11 @@ export function Match3DRuntimeShell({
        if (!cancelled) {
          setResolvedBackgroundImageSrc('');
        }
+      })
+      .finally(() => {
+        if (!cancelled) {
+          setIsBackgroundImageResolving(false);
+        }
      });

    return () => {
@@ -1475,8 +1511,10 @@ export function Match3DRuntimeShell({
    setResolvedContainerImageSrc('');
    if (!isGeneratedLegacyPath(containerAssetSrc)) {
      setResolvedContainerImageSrc(containerAssetSrc);
+      setIsContainerImageResolving(false);
      return undefined;
    }
+    setIsContainerImageResolving(true);
    void resolveAssetReadUrl(containerAssetSrc, {
      signal: controller.signal,
      expireSeconds: 300,
@@ -1494,6 +1532,11 @@ export function Match3DRuntimeShell({
              : MATCH3D_CONTAINER_REFERENCE_SRC,
          );
        }
+      })
+      .finally(() => {
+        if (!cancelled) {
+          setIsContainerImageResolving(false);
+        }
      });

    return () => {
@@ -1503,7 +1546,7 @@ export function Match3DRuntimeShell({
  }, [containerAssetSrc]);

  useEffect(() => {
-    const rawSources = resolveMatch3DImageReadUrlSources(imageSourcesByType);
+    const rawSources = imageReadUrlSources;
    if (rawSources.length <= 0) {
      setResolvedImageSources((current) =>
        current.size > 0 ? new Map() : current,
@@ -1511,6 +1554,7 @@ export function Match3DRuntimeShell({
      setFailedImageSources((current) =>
        current.size > 0 ? new Set() : current,
      );
+      setIsImageSourcesResolving(false);
      return undefined;
    }

@@ -1519,6 +1563,7 @@ export function Match3DRuntimeShell({
      setFailedImageSources((current) =>
        current.size > 0 ? new Set() : current,
      );
+      setIsImageSourcesResolving(false);
      return undefined;
    }

@@ -1535,6 +1580,7 @@ export function Match3DRuntimeShell({
      return retained;
    });
    setFailedImageSources(new Set());
+    setIsImageSourcesResolving(true);
    void Promise.all(
      rawSources.map(async (source) => {
        if (nextSources.has(source)) {
@@ -1565,13 +1611,18 @@ export function Match3DRuntimeShell({
        if (!cancelled) {
          setFailedImageSources(new Set(rawSources));
        }
+      })
+      .finally(() => {
+        if (!cancelled) {
+          setIsImageSourcesResolving(false);
+        }
      });

    return () => {
      cancelled = true;
      controller.abort();
    };
-  }, [imageReadUrlCacheKey, imageSourcesByType]);
+  }, [imageReadUrlCacheKey, imageReadUrlSources]);

  useEffect(() => {
    const rawSources = alphaHitMaskCacheKey
@@ -1925,6 +1976,44 @@ export function Match3DRuntimeShell({
    <main
      className={`relative flex ${embedded ? 'h-full min-h-0' : 'min-h-dvh'} w-full justify-center overflow-hidden bg-[#16221f] text-white`}
    >
+      <RuntimeResourcePendingMarker
+        source={backgroundMusicSrc}
+        kind="audio"
+        isPending={isBackgroundMusicResolving}
+      />
+      <RuntimeResourcePendingMarker
+        source={backgroundAssetSrc}
+        kind="image"
+        isPending={isBackgroundImageResolving}
+      />
+      <RuntimeResourcePendingMarker
+        source={containerAssetSrc}
+        kind="image"
+        isPending={isContainerImageResolving}
+      />
+      <RuntimeResourcePendingMarker
+        source={uiSpritesheetSource}
+        kind="image"
+        isPending={isUiSpritesheetResolving}
+      />
+      <RuntimeResourcePendingMarker
+        source={itemSpritesheetSource}
+        kind="image"
+        isPending={isItemSpritesheetResolving}
+      />
+      {imageReadUrlSources.map((source) => (
+        <RuntimeResourcePendingMarker
+          key={`match3d-runtime-resource:${source}`}
+          source={source}
+          kind="image"
+          isPending={
+            isImageSourcesResolving &&
+            isGeneratedLegacyPath(source) &&
+            !resolvedImageSources.has(source) &&
+            !failedImageSources.has(source)
+          }
+        />
+      ))}
      <div className="absolute inset-0 bg-[radial-gradient(circle_at_50%_12%,rgba(255,255,255,0.22),transparent_26%),linear-gradient(180deg,#b8e28d_0%,#377569_52%,#14201f_100%)]" />
      {resolvedBackgroundImageSrc ? (
        <img
--- a/src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx
+++ b/src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx
@@ -11,6 +11,7 @@ import {
 import { expect, test, vi } from 'vitest';

 import type { PuzzleRunSnapshot } from '../../../packages/shared/src/contracts/puzzleRuntimeSession';
+import { loadPuzzleUiSpritesheetLayout } from '../../services/puzzle-runtime/puzzleUiSpritesheetParser';
 import { AuthUiContext } from '../auth/AuthUiContext';
 import {
  buildMergedGroupOutlinePath,
@@ -938,6 +939,48 @@ test('运行态用 UI spritesheet 原图检测矩形裁切返回设置下一关
  expect(screen.getByRole('button', { name: '冻结' }).textContent).toBe('');
 });

+test('运行态 UI spritesheet 解析失败后释放推荐页资源等待标记', async () => {
+  vi.mocked(loadPuzzleUiSpritesheetLayout).mockRejectedValueOnce(
+    new Error('spritesheet parse failed'),
+  );
+  const runWithSpritesheet: PuzzleRunSnapshot = {
+    ...clearedRun,
+    currentLevel: {
+      ...clearedRun.currentLevel!,
+      status: 'playing',
+      coverImageSrc: '/generated-puzzle-assets/session/cover.png',
+      uiSpritesheetImageSrc:
+        '/generated-puzzle-assets/session/ui-spritesheet/sheet.png',
+      remainingMs: 120_000,
+      timeLimitMs: 300_000,
+    },
+  };
+
+  const { container } = renderPuzzleRuntime(
+    <PuzzleRuntimeShell
+      run={runWithSpritesheet}
+      onBack={vi.fn()}
+      onSwapPieces={vi.fn()}
+      onDragPiece={vi.fn()}
+      onAdvanceNextLevel={vi.fn()}
+    />,
+  );
+
+  await waitFor(() => {
+    expect(loadPuzzleUiSpritesheetLayout).toHaveBeenCalledWith(
+      '/generated-puzzle-assets/session/ui-spritesheet/sheet.png',
+      expect.objectContaining({ signal: expect.any(AbortSignal) }),
+    );
+  });
+  await waitFor(() => {
+    expect(
+      container.querySelector(
+        '[data-runtime-resource-pending="true"][data-runtime-resource-src="/generated-puzzle-assets/session/ui-spritesheet/sheet.png"]',
+      ),
+    ).toBeNull();
+  });
+});
+
 test('运行态在只有 UI 背景 objectKey 时仍渲染生成背景', () => {
  const runWithUiBackground: PuzzleRunSnapshot = {
    ...clearedRun,
--- a/src/components/puzzle-runtime/PuzzleRuntimeShell.tsx
+++ b/src/components/puzzle-runtime/PuzzleRuntimeShell.tsx
@@ -55,6 +55,7 @@ import {
  resolveRuntimeCountdownSecondBucket,
 } from '../../services/runtimeAudioFeedback';
 import { useAuthUi } from '../auth/AuthUiContext';
+import { RuntimeResourcePendingMarker } from '../common/RuntimeResourcePendingMarker';
 import { ResolvedAssetImage } from '../ResolvedAssetImage';
 import {
  buildMergedGroupOutlinePath,
@@ -475,6 +476,8 @@ export function PuzzleRuntimeShell({
  } | null>(null);
  const [uiSpritesheetLayout, setUiSpritesheetLayout] =
    useState<PuzzleUiSpritesheetLayout | null>(null);
+  const [isUiSpritesheetLayoutResolving, setIsUiSpritesheetLayoutResolving] =
+    useState(false);
  const runtimeDragInputControllerRef = useRef(
    createRuntimeDragInputController<string>(),
  );
@@ -526,22 +529,28 @@ export function PuzzleRuntimeShell({
    currentLevel?.backgroundMusic?.audioSrc?.trim() || null;
  const levelAudioConfig = DEFAULT_RUNTIME_LEVEL_AUDIO_CONFIG;
  const onMusicVolumeChange = authUi?.setMusicVolume ?? (() => {});
-  const { resolvedUrl: resolvedBackgroundMusicSrc } =
-    useResolvedAssetReadUrl(backgroundMusicSrc);
-  const { resolvedUrl: resolvedCoverImage } = useResolvedAssetReadUrl(
+  const {
+    resolvedUrl: resolvedBackgroundMusicSrc,
+    isResolving: isBackgroundMusicResolving,
+  } = useResolvedAssetReadUrl(backgroundMusicSrc);
+  const { resolvedUrl: resolvedCoverImage, isResolving: isCoverImageResolving } =
+    useResolvedAssetReadUrl(
    currentLevel?.coverImageSrc ?? null,
  );
-  const { resolvedUrl: resolvedUiBackgroundImage } = useResolvedAssetReadUrl(
-    resolvePuzzleUiBackgroundSource(currentLevel) ?? null,
-  );
+  const rawUiBackgroundImage = resolvePuzzleUiBackgroundSource(currentLevel);
+  const {
+    resolvedUrl: resolvedUiBackgroundImage,
+    isResolving: isUiBackgroundResolving,
+  } = useResolvedAssetReadUrl(rawUiBackgroundImage ?? null);
  const rawUiSpritesheetImage =
    currentLevel?.uiSpritesheetImageSrc?.trim() ||
    (currentLevel?.uiSpritesheetImageObjectKey?.trim()
      ? `/${currentLevel.uiSpritesheetImageObjectKey.trim().replace(/^\/+/u, '')}`
      : null);
-  const { resolvedUrl: resolvedUiSpritesheetImage } = useResolvedAssetReadUrl(
-    rawUiSpritesheetImage,
-  );
+  const {
+    resolvedUrl: resolvedUiSpritesheetImage,
+    isResolving: isUiSpritesheetResolving,
+  } = useResolvedAssetReadUrl(rawUiSpritesheetImage);
  const hasUiSpritesheet = Boolean(resolvedUiSpritesheetImage);
  const tryPlayBackgroundMusic = useCallback(() => {
    const audio = backgroundAudioRef.current;
@@ -558,23 +567,27 @@ export function PuzzleRuntimeShell({
  useEffect(() => {
    if (!rawUiSpritesheetImage) {
      setUiSpritesheetLayout(null);
+      setIsUiSpritesheetLayoutResolving(false);
      return;
    }

    const controller = new AbortController();
    setUiSpritesheetLayout(null);
+    setIsUiSpritesheetLayoutResolving(true);
    void loadPuzzleUiSpritesheetLayout(rawUiSpritesheetImage, {
      signal: controller.signal,
    })
      .then((layout) => {
        if (!controller.signal.aborted) {
          setUiSpritesheetLayout(layout);
+          setIsUiSpritesheetLayoutResolving(false);
        }
      })
      .catch(() => {
        if (!controller.signal.aborted) {
          // 中文注释：私有图读取或 canvas 解析失败时回退旧固定六宫格，避免运行态按钮空白。
          setUiSpritesheetLayout(null);
+          setIsUiSpritesheetLayoutResolving(false);
        }
      });

@@ -1523,6 +1536,26 @@ export function PuzzleRuntimeShell({
    <div
      className={`platform-ui-shell platform-theme ${platformThemeClass} puzzle-runtime-shell ${embedded ? 'relative h-full min-h-0 w-full' : 'fixed inset-0 z-[100]'} flex justify-center`}
    >
+      <RuntimeResourcePendingMarker
+        source={backgroundMusicSrc}
+        kind="audio"
+        isPending={isBackgroundMusicResolving}
+      />
+      <RuntimeResourcePendingMarker
+        source={currentLevel.coverImageSrc}
+        kind="image"
+        isPending={isCoverImageResolving}
+      />
+      <RuntimeResourcePendingMarker
+        source={rawUiBackgroundImage}
+        kind="image"
+        isPending={isUiBackgroundResolving}
+      />
+      <RuntimeResourcePendingMarker
+        source={rawUiSpritesheetImage}
+        kind="image"
+        isPending={isUiSpritesheetResolving || isUiSpritesheetLayoutResolving}
+      />
      {resolvedBackgroundMusicSrc ? (
        <audio
          ref={backgroundAudioRef}
--- a/src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx
+++ b/src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx
@@ -9,7 +9,7 @@ import {
  within,
 } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import { afterEach, expect, test, vi } from 'vitest';

 import type {
@@ -4095,6 +4095,11 @@ test('mobile recommend runtime cover does not swap to a late signed cover', asyn
 test('mobile recommend cover waits until runtime images are ready', async () => {
  vi.useFakeTimers();
  const animationCallbacks: FrameRequestCallback[] = [];
+  const flushAnimationFrames = () => {
+    act(() => {
+      animationCallbacks.splice(0).forEach((callback) => callback(16));
+    });
+  };
  Object.defineProperty(window, 'requestAnimationFrame', {
    configurable: true,
    writable: true,
@@ -4137,6 +4142,102 @@ test('mobile recommend cover waits until runtime images are ready', async () =>
  await act(async () => {
    vi.advanceTimersByTime(520);
  });
+  flushAnimationFrames();
+  flushAnimationFrames();
+  await act(async () => undefined);
+
+  expect(
+    document.querySelector('.platform-recommend-runtime-cover')?.className,
+  ).toContain('platform-recommend-runtime-cover--hidden');
+});
+
+test('mobile recommend cover waits for async runtime resources beyond the main image', async () => {
+  vi.useFakeTimers();
+  const animationCallbacks: FrameRequestCallback[] = [];
+  const flushAnimationFrames = () => {
+    act(() => {
+      animationCallbacks.splice(0).forEach((callback) => callback(16));
+    });
+  };
+  Object.defineProperty(window, 'requestAnimationFrame', {
+    configurable: true,
+    writable: true,
+    value: vi.fn((callback: FrameRequestCallback) => {
+      animationCallbacks.push(callback);
+      return animationCallbacks.length;
+    }),
+  });
+  Object.defineProperty(window, 'cancelAnimationFrame', {
+    configurable: true,
+    writable: true,
+    value: vi.fn(),
+  });
+
+  function AsyncRuntimeAssets() {
+    const [showExtraResource, setShowExtraResource] = useState(false);
+    useEffect(() => {
+      const timeoutId = window.setTimeout(() => {
+        setShowExtraResource(true);
+      }, 100);
+
+      return () => window.clearTimeout(timeoutId);
+    }, []);
+
+    return (
+      <div>
+        <img src="/runtime-main.png" alt="runtime main" />
+        {showExtraResource ? (
+          <img src="/runtime-extra.png" alt="runtime extra" />
+        ) : (
+          <span
+            hidden
+            data-runtime-resource-pending="true"
+            data-runtime-resource-src="/runtime-extra.png"
+          />
+        )}
+      </div>
+    );
+  }
+
+  renderLoggedOutHomeView(vi.fn(), {
+    latestEntries: [puzzlePublicEntry],
+    activeRecommendEntryKey: 'puzzle:user-2:puzzle-profile-public-1',
+    isRecommendRuntimeReady: true,
+    recommendRuntimeContent: <AsyncRuntimeAssets />,
+  });
+
+  fireEvent.load(screen.getByAltText('runtime main'));
+  flushAnimationFrames();
+
+  await act(async () => {
+    vi.advanceTimersByTime(100);
+  });
+  await act(async () => undefined);
+  flushAnimationFrames();
+  flushAnimationFrames();
+  expect(screen.getByAltText('runtime extra')).toBeTruthy();
+  await act(async () => {
+    vi.advanceTimersByTime(80);
+  });
+  flushAnimationFrames();
+
+  await act(async () => {
+    vi.advanceTimersByTime(520);
+  });
+  flushAnimationFrames();
+
+  expect(
+    document.querySelector('.platform-recommend-runtime-cover')?.className,
+  ).not.toContain('platform-recommend-runtime-cover--hidden');
+
+  fireEvent.load(screen.getByAltText('runtime extra'));
+  flushAnimationFrames();
+  await act(async () => {
+    vi.advanceTimersByTime(80);
+  });
+  flushAnimationFrames();
+  flushAnimationFrames();
+  await act(async () => undefined);

  expect(
    document.querySelector('.platform-recommend-runtime-cover')?.className,
@@ -4144,7 +4245,24 @@ test('mobile recommend cover waits until runtime images are ready', async () =>
 });

 test('mobile recommend keeps runtime visual stable when active entry changes', async () => {
+  vi.useFakeTimers();
  const animationCallbacks: FrameRequestCallback[] = [];
+  const flushAnimationFrames = () => {
+    act(() => {
+      animationCallbacks.splice(0).forEach((callback) => callback(16));
+    });
+  };
+  const settleRecommendRuntimeReady = async () => {
+    await act(async () => {
+      vi.advanceTimersByTime(80);
+    });
+    flushAnimationFrames();
+    flushAnimationFrames();
+    await act(async () => {
+      vi.advanceTimersByTime(520);
+    });
+    await act(async () => undefined);
+  };
  Object.defineProperty(window, 'requestAnimationFrame', {
    configurable: true,
    writable: true,
@@ -4183,14 +4301,10 @@ test('mobile recommend keeps runtime visual stable when active entry changes', a
    isRecommendRuntimeReady: true,
  });

-  act(() => {
-    animationCallbacks.splice(0).forEach((callback) => callback(16));
-  });
-  await waitFor(() => {
+  await settleRecommendRuntimeReady();
  expect(
    document.querySelector('.platform-recommend-runtime-cover')?.className,
  ).toContain('platform-recommend-runtime-cover--hidden');
-  });

  rerender(
    <AuthUiContext.Provider
@@ -4243,6 +4357,7 @@ test('mobile recommend keeps runtime visual stable when active entry changes', a
      />
    </AuthUiContext.Provider>,
  );
+  await act(async () => undefined);

  const rail = document.querySelector(
    '.platform-recommend-swipe-rail',
--- a/src/components/rpg-entry/RpgEntryHomeView.tsx
+++ b/src/components/rpg-entry/RpgEntryHomeView.tsx
@@ -121,6 +121,7 @@ import {
  LEGAL_DOCUMENTS,
  type LegalDocumentId,
 } from '../common/legalDocuments';
+import { RUNTIME_RESOURCE_PENDING_SELECTOR } from '../common/RuntimeResourcePendingMarker';
 import {
  buildCenteredSquareImageCropRect,
  clampSquareImageCropRect,
@@ -267,6 +268,8 @@ const RECOMMEND_ENTRY_SWIPE_THRESHOLD_PX = 36;
 const RECOMMEND_ENTRY_COMMIT_ANIMATION_MS = 180;
 const RECOMMEND_ENTRY_DRAG_LIMIT_PX = 160;
 const RECOMMEND_RUNTIME_COVER_MIN_VISIBLE_MS = 520;
+const RECOMMEND_RUNTIME_RESOURCE_IDLE_MS = 80;
+const RECOMMEND_RUNTIME_READY_FRAME_COUNT = 2;

 type RecommendResolvedCoverUrlMap = ReadonlyMap<string, string>;

@@ -438,19 +441,67 @@ function useResolvedRecommendCoverImages(
  return resolvedCoverUrls;
 }

-function scheduleRecommendRuntimeReady(
-  signal: AbortSignal,
-  onReady: (value: boolean) => void,
-) {
+function scheduleRecommendRuntimeReady(signal: AbortSignal, onReady: () => void) {
  if (signal.aborted) {
    return null;
  }

-  return window.requestAnimationFrame(() => {
-    if (!signal.aborted) {
-      onReady(true);
+  let animationFrameId: number | null = null;
+  let remainingFrameCount = RECOMMEND_RUNTIME_READY_FRAME_COUNT;
+  const tick = () => {
+    animationFrameId = null;
+    if (signal.aborted) {
+      return;
+    }
+
+    remainingFrameCount -= 1;
+    if (remainingFrameCount <= 0) {
+      onReady();
+      return;
+    }
+
+    animationFrameId = window.requestAnimationFrame(tick);
+  };
+
+  animationFrameId = window.requestAnimationFrame(tick);
+  return () => {
+    if (animationFrameId !== null) {
+      window.cancelAnimationFrame(animationFrameId);
+    }
+  };
+}
+
+function getRecommendRuntimeImageSource(image: HTMLImageElement) {
+  return (
+    image.currentSrc ||
+    image.getAttribute('src') ||
+    image.getAttribute('srcset') ||
+    ''
+  ).trim();
+}
+
+function getRecommendRuntimeMediaSource(media: HTMLMediaElement) {
+  return (media.currentSrc || media.getAttribute('src') || '').trim();
+}
+
+function collectRecommendRuntimeBackgroundUrls(root: HTMLElement) {
+  const urls = new Set<string>();
+  root.querySelectorAll<HTMLElement>('[style]').forEach((element) => {
+    const backgroundImage = element.style.backgroundImage;
+    if (!backgroundImage || backgroundImage === 'none') {
+      return;
+    }
+
+    const pattern = /url\((?:"([^"]*)"|'([^']*)'|([^)]*))\)/giu;
+    let match: RegExpExecArray | null;
+    while ((match = pattern.exec(backgroundImage))) {
+      const url = (match[1] ?? match[2] ?? match[3] ?? '').trim();
+      if (url) {
+        urls.add(url);
+      }
    }
  });
+  return urls;
 }

 function readyRecommendRuntime(
@@ -461,63 +512,312 @@ function readyRecommendRuntime(
    return Promise.resolve(false);
  }

-  const pendingImages = Array.from(root.querySelectorAll('img')).filter(
-    (image) => !image.complete,
-  );
+  const runtimeRoot = root;

  return new Promise((resolve) => {
-    let animationFrameId: number | null = null;
+    let scanFrameId: number | null = null;
+    let readyIdleTimeoutId: number | null = null;
+    let pendingRecheckTimeoutId: number | null = null;
+    let readyFrameCleanup: (() => void) | null = null;
    let settled = false;
    const cleanupCallbacks: Array<() => void> = [];
+    const pendingImageListeners = new Map<
+      HTMLImageElement,
+      { src: string; cleanup: () => void }
+    >();
+    const pendingMediaListeners = new Map<
+      HTMLMediaElement,
+      { src: string; cleanup: () => void }
+    >();
+    const settledImageSources = new WeakMap<HTMLImageElement, string>();
+    const settledMediaSources = new WeakMap<HTMLMediaElement, string>();
+    const loadedBackgroundUrls = new Set<string>();
+    const pendingBackgroundPreloads = new Map<string, () => void>();
+
+    const cancelReadySchedule = () => {
+      if (readyIdleTimeoutId !== null) {
+        window.clearTimeout(readyIdleTimeoutId);
+        readyIdleTimeoutId = null;
+      }
+      if (readyFrameCleanup) {
+        readyFrameCleanup();
+        readyFrameCleanup = null;
+      }
+    };
+    const cancelPendingRecheck = () => {
+      if (pendingRecheckTimeoutId !== null) {
+        window.clearTimeout(pendingRecheckTimeoutId);
+        pendingRecheckTimeoutId = null;
+      }
+    };
    const finish = (value: boolean) => {
      if (settled) {
        return;
      }
      settled = true;
+      cancelReadySchedule();
+      cancelPendingRecheck();
      cleanupCallbacks.splice(0).forEach((cleanup) => cleanup());
-      if (animationFrameId !== null) {
-        window.cancelAnimationFrame(animationFrameId);
+      if (scanFrameId !== null) {
+        window.cancelAnimationFrame(scanFrameId);
      }
      resolve(value);
    };
    const abort = () => finish(false);
    signal.addEventListener('abort', abort, { once: true });
    cleanupCallbacks.push(() => signal.removeEventListener('abort', abort));
+    cleanupCallbacks.push(() => {
+      pendingImageListeners.forEach(({ cleanup }) => cleanup());
+      pendingImageListeners.clear();
+      pendingMediaListeners.forEach(({ cleanup }) => cleanup());
+      pendingMediaListeners.clear();
+      pendingBackgroundPreloads.forEach((cleanup) => cleanup());
+      pendingBackgroundPreloads.clear();
+    });

-    if (pendingImages.length === 0) {
-      animationFrameId = scheduleRecommendRuntimeReady(signal, finish);
-      if (animationFrameId === null) {
+    const scheduleScan = () => {
+      if (settled) {
+        return;
+      }
+      cancelReadySchedule();
+      cancelPendingRecheck();
+      if (scanFrameId !== null) {
+        return;
+      }
+      scanFrameId = window.requestAnimationFrame(() => {
+        scanFrameId = null;
+        scanResources();
+      });
+    };
+
+    const scheduleReady = () => {
+      cancelReadySchedule();
+      readyIdleTimeoutId = window.setTimeout(() => {
+        readyIdleTimeoutId = null;
+        readyFrameCleanup = scheduleRecommendRuntimeReady(signal, () =>
+          finish(true),
+        );
+        if (readyFrameCleanup === null) {
          finish(false);
        }
+      }, RECOMMEND_RUNTIME_RESOURCE_IDLE_MS);
+    };
+
+    const preloadBackgroundUrl = (url: string) => {
+      if (loadedBackgroundUrls.has(url) || pendingBackgroundPreloads.has(url)) {
+        return;
+      }
+      if (typeof Image === 'undefined') {
+        loadedBackgroundUrls.add(url);
        return;
      }

-    let remaining = pendingImages.length;
-    const markImageReady = () => {
-      remaining -= 1;
-      if (remaining > 0) {
-        return;
-      }
-      animationFrameId = scheduleRecommendRuntimeReady(signal, finish);
-      if (animationFrameId === null) {
-        finish(false);
+      const image = new Image();
+      const cleanup = () => {
+        image.onload = null;
+        image.onerror = null;
+      };
+      const markReady = () => {
+        cleanup();
+        pendingBackgroundPreloads.delete(url);
+        loadedBackgroundUrls.add(url);
+        scheduleScan();
+      };
+      image.decoding = 'async';
+      image.onload = markReady;
+      image.onerror = markReady;
+      pendingBackgroundPreloads.set(url, cleanup);
+      image.src = url;
+      if (image.complete) {
+        markReady();
      }
    };

-    pendingImages.forEach((image) => {
+    function scanResources() {
+      if (signal.aborted) {
+        finish(false);
+        return;
+      }
+
+      const currentImages = new Set(
+        Array.from(runtimeRoot.querySelectorAll<HTMLImageElement>('img')),
+      );
+      const currentMedia = new Set(
+        Array.from(
+          runtimeRoot.querySelectorAll<HTMLMediaElement>('audio,video'),
+        ),
+      );
+      pendingImageListeners.forEach((entry, image) => {
+        const currentSrc = getRecommendRuntimeImageSource(image);
+        if (!currentImages.has(image) || currentSrc !== entry.src || !currentSrc) {
+          entry.cleanup();
+          pendingImageListeners.delete(image);
+        }
+      });
+      pendingMediaListeners.forEach((entry, media) => {
+        const currentSrc = getRecommendRuntimeMediaSource(media);
+        if (!currentMedia.has(media) || currentSrc !== entry.src || !currentSrc) {
+          entry.cleanup();
+          pendingMediaListeners.delete(media);
+        }
+      });
+
+      currentImages.forEach((image) => {
+        const imageSrc = getRecommendRuntimeImageSource(image);
+        const settledImageSrc = settledImageSources.get(image);
+        if (settledImageSrc && settledImageSrc !== imageSrc) {
+          settledImageSources.delete(image);
+        }
+        if (!imageSrc || image.complete) {
+          if (imageSrc && image.complete) {
+            settledImageSources.set(image, imageSrc);
+          }
+          return;
+        }
+        if (settledImageSources.get(image) === imageSrc) {
+          return;
+        }
+
+        const existingEntry = pendingImageListeners.get(image);
+        if (existingEntry?.src === imageSrc) {
+          return;
+        }
+        existingEntry?.cleanup();
+        const markImageReady = () => {
+          const activeEntry = pendingImageListeners.get(image);
+          if (activeEntry?.src !== imageSrc) {
+            return;
+          }
+          settledImageSources.set(image, imageSrc);
+          activeEntry.cleanup();
+          pendingImageListeners.delete(image);
+          scheduleScan();
+        };
        const cleanupImageListeners = () => {
          image.removeEventListener('load', markImageReady);
          image.removeEventListener('error', markImageReady);
        };
        image.addEventListener('load', markImageReady, { once: true });
        image.addEventListener('error', markImageReady, { once: true });
-      cleanupCallbacks.push(cleanupImageListeners);
+        pendingImageListeners.set(image, {
+          src: imageSrc,
+          cleanup: cleanupImageListeners,
+        });

        if (image.complete) {
-        cleanupImageListeners();
          markImageReady();
        }
      });
+
+      currentMedia.forEach((media) => {
+        const mediaSrc = getRecommendRuntimeMediaSource(media);
+        const settledMediaSrc = settledMediaSources.get(media);
+        const mediaReadyThreshold =
+          typeof HTMLMediaElement !== 'undefined'
+            ? HTMLMediaElement.HAVE_CURRENT_DATA
+            : 2;
+        if (settledMediaSrc && settledMediaSrc !== mediaSrc) {
+          settledMediaSources.delete(media);
+        }
+        if (
+          !mediaSrc ||
+          media.readyState >= mediaReadyThreshold ||
+          media.error
+        ) {
+          if (mediaSrc && media.readyState >= mediaReadyThreshold) {
+            settledMediaSources.set(media, mediaSrc);
+          }
+          return;
+        }
+        if (settledMediaSources.get(media) === mediaSrc) {
+          return;
+        }
+
+        const existingEntry = pendingMediaListeners.get(media);
+        if (existingEntry?.src === mediaSrc) {
+          return;
+        }
+        existingEntry?.cleanup();
+        const markMediaReady = () => {
+          const activeEntry = pendingMediaListeners.get(media);
+          if (activeEntry?.src !== mediaSrc) {
+            return;
+          }
+          settledMediaSources.set(media, mediaSrc);
+          activeEntry.cleanup();
+          pendingMediaListeners.delete(media);
+          scheduleScan();
+        };
+        const cleanupMediaListeners = () => {
+          media.removeEventListener('loadeddata', markMediaReady);
+          media.removeEventListener('canplaythrough', markMediaReady);
+          media.removeEventListener('error', markMediaReady);
+        };
+        media.addEventListener('loadeddata', markMediaReady, { once: true });
+        media.addEventListener('canplaythrough', markMediaReady, {
+          once: true,
+        });
+        media.addEventListener('error', markMediaReady, { once: true });
+        pendingMediaListeners.set(media, {
+          src: mediaSrc,
+          cleanup: cleanupMediaListeners,
+        });
+
+        if (media.readyState >= mediaReadyThreshold || media.error) {
+          markMediaReady();
+        }
+      });
+
+      const currentBackgroundUrls =
+        collectRecommendRuntimeBackgroundUrls(runtimeRoot);
+      pendingBackgroundPreloads.forEach((cleanup, url) => {
+        if (!currentBackgroundUrls.has(url)) {
+          cleanup();
+          pendingBackgroundPreloads.delete(url);
+        }
+      });
+      currentBackgroundUrls.forEach((url) => preloadBackgroundUrl(url));
+
+      const hasPendingResourceMarker = Boolean(
+        runtimeRoot.querySelector(RUNTIME_RESOURCE_PENDING_SELECTOR),
+      );
+      if (
+        hasPendingResourceMarker ||
+        pendingImageListeners.size > 0 ||
+        pendingMediaListeners.size > 0 ||
+        pendingBackgroundPreloads.size > 0
+      ) {
+        cancelReadySchedule();
+        if (pendingRecheckTimeoutId === null) {
+          pendingRecheckTimeoutId = window.setTimeout(() => {
+            pendingRecheckTimeoutId = null;
+            scheduleScan();
+          }, RECOMMEND_RUNTIME_RESOURCE_IDLE_MS);
+        }
+        return;
+      }
+
+      cancelPendingRecheck();
+      scheduleReady();
+    }
+
+    if (typeof MutationObserver !== 'undefined') {
+      const observer = new MutationObserver(scheduleScan);
+      observer.observe(runtimeRoot, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        attributeFilter: [
+          'src',
+          'srcset',
+          'style',
+          'data-runtime-resource-pending',
+        ],
+      });
+      cleanupCallbacks.push(() => observer.disconnect());
+    }
+
+    scanResources();
  });
 }
 const WECHAT_JS_SDK_URL = 'https://res.wx.qq.com/open/js/jweixin-1.6.0.js';
--- a/src/components/wooden-fish-runtime/WoodenFishRuntimeShell.tsx
+++ b/src/components/wooden-fish-runtime/WoodenFishRuntimeShell.tsx
@@ -8,17 +8,18 @@ import {
  useState,
 } from 'react';

+import woodenFishRuntimeLogo from '../../../media/logo.png';
 import type {
  WoodenFishRuntimeRunSnapshotResponse,
  WoodenFishWordCounter,
  WoodenFishWorkProfileResponse,
 } from '../../../packages/shared/src/contracts/woodenFish';
-import woodenFishRuntimeLogo from '../../../media/logo.png';
 import { useResolvedAssetReadUrl } from '../../hooks/useResolvedAssetReadUrl';
 import {
  WOODEN_FISH_DEFAULT_HIT_OBJECT_SRC,
  WOODEN_FISH_DEFAULT_HIT_SOUND_ASSET,
 } from '../../services/wooden-fish/woodenFishDefaults';
+import { RuntimeResourcePendingMarker } from '../common/RuntimeResourcePendingMarker';
 import { ResolvedAssetImage } from '../ResolvedAssetImage';
 import {
  applyWoodenFishTap,
@@ -114,7 +115,8 @@ export function WoodenFishRuntimeShell({
    profile?.hitSoundAsset?.audioSrc ??
    profile?.draft.hitSoundAsset?.audioSrc ??
    WOODEN_FISH_DEFAULT_HIT_SOUND_ASSET.audioSrc;
-  const { resolvedUrl: resolvedAudioUrl } = useResolvedAssetReadUrl(hitSoundSrc);
+  const { resolvedUrl: resolvedAudioUrl, isResolving: isHitSoundResolving } =
+    useResolvedAssetReadUrl(hitSoundSrc);

  useEffect(() => {
    currentSnapshotRef.current = { totalTapCount, wordCounters };
@@ -254,6 +256,11 @@ export function WoodenFishRuntimeShell({
      className="wooden-fish-runtime relative flex h-full min-h-0 w-full flex-col overflow-hidden bg-[#f7f4ec] text-slate-950"
      onPointerDown={registerTap}
    >
+      <RuntimeResourcePendingMarker
+        source={hitSoundSrc}
+        kind="audio"
+        isPending={isHitSoundResolving}
+      />
      <div className="pointer-events-none absolute inset-0 bg-[radial-gradient(circle_at_50%_18%,rgba(255,255,255,0.92),transparent_26%),linear-gradient(180deg,#fff8e8_0%,#eef7ed_55%,#e5f2f7_100%)]" />
      {backgroundSrc ? (
        <ResolvedAssetImage
--- a/src/hooks/useResolvedAssetReadUrl.ts
+++ b/src/hooks/useResolvedAssetReadUrl.ts
@@ -22,21 +22,25 @@ export function useResolvedAssetReadUrl(
  const [resolvedUrl, setResolvedUrl] = useState(
    shouldResolve ? '' : normalizedSource,
  );
+  const [isResolving, setIsResolving] = useState(shouldResolve);

  useEffect(() => {
    if (!normalizedSource) {
      setResolvedUrl('');
+      setIsResolving(false);
      return;
    }

    if (!shouldResolve) {
      setResolvedUrl(normalizedSource);
+      setIsResolving(false);
      return;
    }

    let cancelled = false;
    // 生成资源通常是 OSS 私有对象；签名 URL 未就绪前不能把裸 generated 路径交给 img 触发无鉴权 GET。
    setResolvedUrl('');
+    setIsResolving(true);

    void resolveAssetReadUrl(normalizedSource, {
      expireSeconds: options.expireSeconds,
@@ -52,6 +56,11 @@ export function useResolvedAssetReadUrl(
          // 签名失败时保持空 src，避免继续请求无签名的私有对象兼容路径。
          setResolvedUrl('');
        }
+      })
+      .finally(() => {
+        if (!cancelled) {
+          setIsResolving(false);
+        }
      });

    return () => {
@@ -66,7 +75,7 @@ export function useResolvedAssetReadUrl(

  return {
    resolvedUrl,
-    isResolving: shouldResolve && !resolvedUrl,
+    isResolving,
    shouldResolve,
  };
 }