Merge remote-tracking branch 'origin/master' into dev-jenken

# Conflicts: # .hermes/shared-memory/pitfalls.md # server-rs/crates/api-server/src/modules/jump_hop.rs # src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx # src/services/jump-hop/jumpHopClient.test.ts
2026-06-05 23:59:40 +08:00
parent fb3eede781 7e6ed91149
commit 2db3a6e185
67 changed files with 8713 additions and 2537 deletions
@@ -525,6 +525,7 @@ test('creation start card maps backend jump-hop draft to template card', () => {
          profileId: 'jump-hop-profile-1',
          ownerUserId: 'user-1',
          sourceSessionId: 'jump-hop-session-1',
+          themeText: '跳一跳生成草稿',
          workTitle: '跳一跳生成草稿',
          workDescription: '后端仍在生成跳一跳玩法。',
          themeTags: ['跳一跳'],
@@ -1,144 +1,205 @@
 /* @vitest-environment jsdom */

 import { render, screen } from '@testing-library/react';
-import userEvent from '@testing-library/user-event';
-import { expect, test, vi } from 'vitest';
+import { beforeEach, expect, test, vi } from 'vitest';

-import type { JumpHopDraftResponse } from '../../../packages/shared/src/contracts/jumpHop';
+import type { JumpHopWorkProfileResponse } from '../../../packages/shared/src/contracts/jumpHop';
+import { useJumpHopLeaderboard } from '../../services/jump-hop/useJumpHopLeaderboard';
 import { JumpHopResultView } from './JumpHopResultView';

-const draft: JumpHopDraftResponse = {
-  templateId: 'jump-hop',
-  templateName: '跳一跳',
-  profileId: 'profile-1',
-  workTitle: '云端跳台',
-  workDescription: '一路跳到星星。',
-  themeTags: ['云朵', '星空'],
-  difficulty: 'standard',
-  stylePreset: 'paper-toy',
-  characterPrompt: '纸片小兔',
-  tilePrompt: '柔软云朵平台',
-  endMoodPrompt: '星光门',
-  characterAsset: {
-    assetId: 'character-1',
-    imageSrc: 'data:image/png;base64,character',
-    imageObjectKey: 'jump-hop/character.png',
-    assetObjectId: 'asset-character',
-    generationProvider: 'vector-engine-gpt-image-2',
-    prompt: '角色图',
-    width: 1024,
-    height: 1024,
-  },
-  tileAtlasAsset: {
-    assetId: 'tiles-1',
-    imageSrc: 'data:image/png;base64,tiles',
-    imageObjectKey: 'jump-hop/tiles.png',
-    assetObjectId: 'asset-tiles',
-    generationProvider: 'vector-engine-gpt-image-2',
-    prompt: '地块图',
-    width: 1024,
-    height: 1024,
-  },
-  tileAssets: [
-    {
-      tileType: 'start',
-      imageSrc: 'data:image/png;base64,tile-start',
-      imageObjectKey: 'jump-hop/tile-start.png',
-      assetObjectId: 'asset-tile-start',
-      sourceAtlasCell: 'A1',
-      visualWidth: 128,
-      visualHeight: 96,
-      topSurfaceRadius: 24,
-      landingRadius: 28,
-    },
-    {
-      tileType: 'finish',
-      imageSrc: 'data:image/png;base64,tile-finish',
-      imageObjectKey: 'jump-hop/tile-finish.png',
-      assetObjectId: 'asset-tile-finish',
-      sourceAtlasCell: 'A2',
-      visualWidth: 128,
-      visualHeight: 96,
-      topSurfaceRadius: 24,
-      landingRadius: 28,
-    },
-  ],
-  path: {
-    seed: 'jump-hop-seed',
-    difficulty: 'standard',
-    platforms: [
-      {
-        platformId: 'platform-1',
-        tileType: 'start',
-        x: 0,
-        y: 0,
-        width: 48,
-        height: 36,
-        landingRadius: 22,
-        perfectRadius: 12,
-        scoreValue: 1,
-      },
-      {
-        platformId: 'platform-2',
-        tileType: 'finish',
-        x: 16,
-        y: 18,
-        width: 60,
-        height: 42,
-        landingRadius: 22,
-        perfectRadius: 12,
-        scoreValue: 2,
-      },
-    ],
-    finishIndex: 1,
-    cameraPreset: 'default',
-    scoring: {
-      chargeToDistanceRatio: 1.2,
-      maxChargeMs: 1800,
-      hitBonus: 20,
-      perfectBonus: 50,
-    },
-  },
-  coverComposite: 'data:image/png;base64,cover',
-  generationStatus: 'ready',
-};
+vi.mock('../../services/jump-hop/useJumpHopLeaderboard', () => ({
+  useJumpHopLeaderboard: vi.fn(),
+}));

-test('jump hop result view exposes test run and publish actions', async () => {
-  const user = userEvent.setup();
-  const onBack = vi.fn();
-  const onEdit = vi.fn();
-  const onStartTestRun = vi.fn();
-  const onPublish = vi.fn();
-  const onRegenerateCharacter = vi.fn();
-  const onRegenerateTiles = vi.fn();
+beforeEach(() => {
+  vi.clearAllMocks();
+  vi.mocked(useJumpHopLeaderboard).mockReturnValue({
+    leaderboard: null,
+    isLoading: false,
+    error: null,
+    refresh: vi.fn(),
+  });
+});
+
+test('跳一跳结果页展示排行榜列表', () => {
+  vi.mocked(useJumpHopLeaderboard).mockReturnValue({
+    leaderboard: {
+      profileId: 'jump-hop-profile-test',
+      items: [
+        {
+          rank: 1,
+          playerId: 'player-1',
+          successfulJumpCount: 12,
+          durationMs: 40123,
+          updatedAt: '2026-05-27T00:00:00Z',
+        },
+        {
+          rank: 2,
+          playerId: 'player-2',
+          successfulJumpCount: 10,
+          durationMs: 38210,
+          updatedAt: '2026-05-26T00:00:00Z',
+        },
+      ],
+      viewerBest: null,
+    },
+    isLoading: false,
+    error: null,
+    refresh: vi.fn(),
+  });

  render(
    <JumpHopResultView
-      profile={draft}
-      onBack={onBack}
-      onEdit={onEdit}
-      onStartTestRun={onStartTestRun}
-      onPublish={onPublish}
-      onRegenerateCharacter={onRegenerateCharacter}
-      onRegenerateTiles={onRegenerateTiles}
+      profile={buildProfile({ publicationStatus: 'published' })}
+      onBack={() => {}}
+      onEdit={() => {}}
+      onStartTestRun={() => {}}
+      onPublish={() => {}}
+      onRegenerateTiles={() => {}}
    />,
  );

-  expect(screen.getByText('云端跳台')).toBeTruthy();
-  expect(screen.getByRole('button', { name: '试玩' })).toBeTruthy();
-  expect(screen.getByRole('button', { name: '发布' })).toBeTruthy();
-
-  await user.click(screen.getByRole('button', { name: '试玩' }));
-  await user.click(screen.getByRole('button', { name: '发布' }));
-  await user.click(screen.getByRole('button', { name: '返回' }));
-  await user.click(screen.getByRole('button', { name: '返回编辑' }));
-  await user.click(screen.getByRole('button', { name: '角色' }));
-  await user.click(screen.getByRole('button', { name: '地块' }));
-
-  expect(onStartTestRun).toHaveBeenCalledTimes(1);
-  expect(onPublish).toHaveBeenCalledTimes(1);
-  expect(onBack).toHaveBeenCalledTimes(1);
-  expect(onEdit).toHaveBeenCalledTimes(1);
-  expect(onRegenerateCharacter).toHaveBeenCalledTimes(1);
-  expect(onRegenerateTiles).toHaveBeenCalledTimes(1);
+  expect(screen.getByText('排行榜')).toBeTruthy();
+  expect(screen.getByText('player-1')).toBeTruthy();
+  expect(screen.getByText('12 跳')).toBeTruthy();
+  expect(screen.getByText('00:40')).toBeTruthy();
+  expect(screen.getByText('player-2')).toBeTruthy();
 });
+
+test('跳一跳结果页默认角色预览使用陶泥儿透明 logo', () => {
+  render(
+    <JumpHopResultView
+      profile={buildProfile()}
+      onBack={() => {}}
+      onEdit={() => {}}
+      onStartTestRun={() => {}}
+      onPublish={() => {}}
+      onRegenerateTiles={() => {}}
+    />,
+  );
+
+  expect(screen.getByTestId('jump-hop-result-character-logo').getAttribute('src')).toBe(
+    '/branding/jump-hop-taonier-character.png',
+  );
+});
+
+test('跳一跳草稿结果页不请求公开排行榜', () => {
+  render(
+    <JumpHopResultView
+      profile={buildProfile({ publicationStatus: 'draft' })}
+      onBack={() => {}}
+      onEdit={() => {}}
+      onStartTestRun={() => {}}
+      onPublish={() => {}}
+      onRegenerateTiles={() => {}}
+    />,
+  );
+
+  expect(useJumpHopLeaderboard).not.toHaveBeenCalled();
+  expect(screen.queryByText('排行榜')).toBeNull();
+});
+
+function buildProfile(
+  options: {
+    publicationStatus?: JumpHopWorkProfileResponse['summary']['publicationStatus'];
+  } = {},
+): JumpHopWorkProfileResponse {
+  return {
+    summary: {
+      runtimeKind: 'jump-hop',
+      workId: 'jump-hop-profile-test',
+      profileId: 'jump-hop-profile-test',
+      ownerUserId: 'user-test',
+      sourceSessionId: 'jump-hop-session-test',
+      themeText: '测试',
+      workTitle: '测试',
+      workDescription: '测试',
+      themeTags: ['测试'],
+      difficulty: 'standard',
+      stylePreset: 'minimal-blocks',
+      coverImageSrc: null,
+      publicationStatus: options.publicationStatus ?? 'draft',
+      playCount: 0,
+      updatedAt: '2026-05-27T00:00:00Z',
+      publishedAt: null,
+      publishReady: true,
+      generationStatus: 'ready',
+    },
+    draft: {
+      templateId: 'jump-hop',
+      templateName: '跳一跳',
+      profileId: 'jump-hop-profile-test',
+      themeText: '测试',
+      workTitle: '测试',
+      workDescription: '测试',
+      themeTags: ['测试'],
+      difficulty: 'standard',
+      stylePreset: 'minimal-blocks',
+      defaultCharacter: {
+        characterId: 'jump-hop-default-runner',
+        displayName: '默认角色',
+        modelKind: 'builtin-three',
+        bodyColor: '#f59e0b',
+        accentColor: '#2563eb',
+      },
+      characterPrompt: '默认角色',
+      tilePrompt: '地块',
+      endMoodPrompt: null,
+      characterAsset: {
+        assetId: 'builtin',
+        imageSrc: 'builtin://jump-hop/default-character',
+        imageObjectKey: '',
+        assetObjectId: 'builtin',
+        generationProvider: 'builtin-three',
+        prompt: '默认角色',
+        width: 0,
+        height: 0,
+      },
+      tileAtlasAsset: {
+        assetId: 'builtin',
+        imageSrc: 'builtin://jump-hop/default-character',
+        imageObjectKey: '',
+        assetObjectId: 'builtin',
+        generationProvider: 'builtin-three',
+        prompt: '默认角色',
+        width: 0,
+        height: 0,
+      },
+      tileAssets: [],
+      path: null,
+      coverComposite: null,
+      backButtonAsset: null,
+      generationStatus: 'ready',
+    },
+    path: null as never,
+    defaultCharacter: {
+      characterId: 'jump-hop-default-runner',
+      displayName: '默认角色',
+      modelKind: 'builtin-three',
+      bodyColor: '#f59e0b',
+      accentColor: '#2563eb',
+    },
+    characterAsset: {
+      assetId: 'builtin',
+      imageSrc: 'builtin://jump-hop/default-character',
+      imageObjectKey: '',
+      assetObjectId: 'builtin',
+      generationProvider: 'builtin-three',
+      prompt: '默认角色',
+      width: 0,
+      height: 0,
+    },
+    tileAtlasAsset: {
+      assetId: 'builtin',
+      imageSrc: 'builtin://jump-hop/default-character',
+      imageObjectKey: '',
+      assetObjectId: 'builtin',
+      generationProvider: 'builtin-three',
+      prompt: '默认角色',
+      width: 0,
+      height: 0,
+    },
+    tileAssets: [],
+    backButtonAsset: null,
+  };
+}
@@ -0,0 +1,32 @@
+import { describe, expect, test } from 'vitest';
+
+import {
+  resolveMiniGameGenerationProgressTickState,
+} from './PlatformEntryFlowShellImpl';
+import { createMiniGameDraftGenerationState } from '../../services/miniGameDraftGenerationProgress';
+
+describe('resolveMiniGameGenerationProgressTickState', () => {
+  test('returns jump hop and wooden fish generation states for progress ticking', () => {
+    const jumpHopState = createMiniGameDraftGenerationState('jump-hop');
+    const woodenFishState = createMiniGameDraftGenerationState('wooden-fish');
+
+    expect(
+      resolveMiniGameGenerationProgressTickState('jump-hop-generating', {
+        'jump-hop': jumpHopState,
+      }),
+    ).toBe(jumpHopState);
+    expect(
+      resolveMiniGameGenerationProgressTickState('wooden-fish-generating', {
+        'wooden-fish': woodenFishState,
+      }),
+    ).toBe(woodenFishState);
+  });
+
+  test('returns null when the stage does not need generation ticking', () => {
+    expect(
+      resolveMiniGameGenerationProgressTickState('platform', {
+        'jump-hop': createMiniGameDraftGenerationState('jump-hop'),
+      }),
+    ).toBeNull();
+  });
+});
@@ -38,7 +38,10 @@ import type {
  BabyObjectMatchDraft,
  CreateBabyObjectMatchDraftRequest,
 } from '../../../packages/shared/src/contracts/edutainmentBabyObject';
-import type { JumpHopWorkSummaryResponse } from '../../../packages/shared/src/contracts/jumpHop';
+import type {
+  JumpHopJumpRequest,
+  JumpHopWorkSummaryResponse,
+} from '../../../packages/shared/src/contracts/jumpHop';
 import type {
  CreateMatch3DSessionRequest,
  ExecuteMatch3DActionRequest,
@@ -109,6 +112,7 @@ import type {
  VisualNovelWorkDetail,
  VisualNovelWorkSummary,
 } from '../../../packages/shared/src/contracts/visualNovel';
+import type { WoodenFishWorkSummaryResponse } from '../../../packages/shared/src/contracts/woodenFish';
 import { buildCustomWorldPlayableCharacters } from '../../data/characterPresets';
 import {
  buildPublicWorkStagePath,
@@ -189,6 +193,7 @@ import {
  jumpHopClient,
  type JumpHopGalleryCardResponse,
  type JumpHopRunResponse,
+  type JumpHopRuntimeRequestOptions,
  type JumpHopSessionResponse,
  type JumpHopSessionSnapshotResponse,
  JumpHopWorkProfileResponse,
@@ -352,7 +357,6 @@ import {
  type WoodenFishWorkProfileResponse,
  type WoodenFishWorkspaceCreateRequest,
 } from '../../services/wooden-fish/woodenFishClient';
-import type { WoodenFishWorkSummaryResponse } from '../../../packages/shared/src/contracts/woodenFish';
 import type { CustomWorldProfile } from '../../types';
 import { useAuthUi } from '../auth/AuthUiContext';
 import { PublishShareModal } from '../common/PublishShareModal';
@@ -441,11 +445,11 @@ import {
  PlatformErrorDialog,
  type PlatformErrorDialogPayload,
 } from './PlatformErrorDialog';
+import { PlatformFeedbackView } from './PlatformFeedbackView';
 import {
  PlatformTaskCompletionDialog,
  type PlatformTaskCompletionDialogPayload,
 } from './PlatformTaskCompletionDialog';
-import { PlatformFeedbackView } from './PlatformFeedbackView';
 import { PlatformWorkDetailView } from './PlatformWorkDetailView';
 import { usePlatformCreationAgentFlowController } from './usePlatformCreationAgentFlowController';
 import { usePlatformEntryBootstrap } from './usePlatformEntryBootstrap';
@@ -492,6 +496,30 @@ type PuzzleBackgroundCompileTask = {
  error: string | null;
 };

+type MiniGameGenerationProgressTickStateMap = Partial<
+  Record<MiniGameDraftGenerationKind, MiniGameDraftGenerationState | null>
+>;
+
+export function resolveMiniGameGenerationProgressTickState(
+  selectionStage: SelectionStage,
+  states: MiniGameGenerationProgressTickStateMap,
+) {
+  const stageKindMap: Partial<
+    Record<SelectionStage, MiniGameDraftGenerationKind>
+  > = {
+    'puzzle-generating': 'puzzle',
+    'big-fish-generating': 'big-fish',
+    'square-hole-generating': 'square-hole',
+    'match3d-generating': 'match3d',
+    'baby-object-match-generating': 'baby-object-match',
+    'jump-hop-generating': 'jump-hop',
+    'wooden-fish-generating': 'wooden-fish',
+  };
+  const kind = stageKindMap[selectionStage];
+
+  return kind ? (states[kind] ?? null) : null;
+}
+
 type PuzzleDetailReturnTarget = {
  tab: PlatformHomeTab;
 };
@@ -595,11 +623,11 @@ const AGENT_RESULT_STRUCTURAL_BLOCKER_CODES = new Set([
  'publish_missing_main_chapter',
  'publish_missing_first_act',
 ]);
-const RECOMMEND_RUNTIME_BACKGROUND_AUTH_OPTIONS =
+const RECOMMEND_RUNTIME_BACKGROUND_AUTH_OPTIONS: JumpHopRuntimeRequestOptions =
  BACKGROUND_AUTH_REQUEST_OPTIONS;
-const RECOMMEND_PUZZLE_BACKGROUND_AUTH_OPTIONS =
+const RECOMMEND_PUZZLE_BACKGROUND_AUTH_OPTIONS: JumpHopRuntimeRequestOptions =
  RECOMMEND_RUNTIME_BACKGROUND_AUTH_OPTIONS;
-async function buildRecommendRuntimeGuestOptions() {
+async function buildRecommendRuntimeGuestOptions(): Promise<JumpHopRuntimeRequestOptions> {
  const { token } = await ensureRuntimeGuestToken();
  return {
    ...RECOMMEND_RUNTIME_BACKGROUND_AUTH_OPTIONS,
@@ -614,9 +642,9 @@ function shouldUseRecommendRuntimeGuestAuth(
 async function buildRecommendRuntimeAuthOptions(
  authUi: { user?: { id?: string } | null } | null | undefined,
  embedded?: boolean,
-) {
+): Promise<JumpHopRuntimeRequestOptions> {
  if (!embedded) {
-    return {};
+    return RECOMMEND_RUNTIME_BACKGROUND_AUTH_OPTIONS;
  }

  if (shouldUseRecommendRuntimeGuestAuth(authUi)) {
@@ -1967,6 +1995,7 @@ function buildJumpHopPendingSession(
      templateId: 'jump-hop',
      templateName: '跳一跳',
      profileId: item.profileId,
+      themeText: item.themeText || item.workTitle,
      workTitle: item.workTitle,
      workDescription: item.workDescription,
      themeTags: item.themeTags,
@@ -2773,6 +2802,7 @@ function buildPendingJumpHopWorks(
        profileId: `jump-hop-profile-${sessionId}`,
        ownerUserId: '',
        sourceSessionId: sessionId,
+        themeText: '跳一跳',
        workTitle: '跳一跳草稿',
        workDescription:
          state.status === 'failed'
@@ -3596,6 +3626,8 @@ export function PlatformEntryFlowShellImpl({
  const [jumpHopRun, setJumpHopRun] = useState<
    JumpHopRunResponse['run'] | null
  >(null);
+  const [jumpHopRuntimeRequestOptions, setJumpHopRuntimeRequestOptions] =
+    useState<JumpHopRuntimeRequestOptions | null>(null);
  const [jumpHopWork, setJumpHopWork] =
    useState<JumpHopWorkProfileResponse | null>(null);
  const [jumpHopGalleryEntries, setJumpHopGalleryEntries] = useState<
@@ -5375,22 +5407,18 @@ export function PlatformEntryFlowShellImpl({
  ]);

  useEffect(() => {
-    const activeGenerationState =
-      selectionStage === 'puzzle-generating'
-        ? puzzleGenerationState
-        : selectionStage === 'match3d-generating'
-          ? match3dGenerationState
-          : selectionStage === 'big-fish-generating'
-            ? bigFishGenerationState
-            : selectionStage === 'square-hole-generating'
-              ? squareHoleGenerationState
-              : selectionStage === 'jump-hop-generating'
-                ? jumpHopGenerationState
-                : selectionStage === 'wooden-fish-generating'
-                  ? woodenFishGenerationState
-                  : selectionStage === 'baby-object-match-generating'
-                    ? babyObjectMatchGenerationState
-                    : null;
+    const activeGenerationState = resolveMiniGameGenerationProgressTickState(
+      selectionStage,
+      {
+        puzzle: puzzleGenerationState,
+        'big-fish': bigFishGenerationState,
+        'square-hole': squareHoleGenerationState,
+        match3d: match3dGenerationState,
+        'baby-object-match': babyObjectMatchGenerationState,
+        'jump-hop': jumpHopGenerationState,
+        'wooden-fish': woodenFishGenerationState,
+      },
+    );
    const shouldTickProgress =
      selectionStage === 'visual-novel-generating'
        ? visualNovelGenerationStartedAtMs != null &&
@@ -7384,6 +7412,7 @@ export function PlatformEntryFlowShellImpl({
    setJumpHopSession(null);
    setJumpHopWork(null);
    setJumpHopRun(null);
+    setJumpHopRuntimeRequestOptions(null);
    setJumpHopGenerationState(null);
    enterCreateTab();
    setShowCreationTypeModal(false);
@@ -8516,6 +8545,7 @@ export function PlatformEntryFlowShellImpl({
    setJumpHopRuntimeReturnStage('jump-hop-result');
    setJumpHopGenerationState(null);
    setJumpHopSession(null);
+    setJumpHopRuntimeRequestOptions(null);
    setJumpHopError(null);
    returnToCreationFlowSource();
  }, [returnToCreationFlowSource]);
@@ -9545,6 +9575,7 @@ export function PlatformEntryFlowShellImpl({
      );
      setJumpHopWork(null);
      setJumpHopRun(null);
+      setJumpHopRuntimeRequestOptions(null);
      setJumpHopGenerationState(generationState);
      setIsJumpHopBusy(true);
      setSelectionStage('jump-hop-generating');
@@ -9559,6 +9590,8 @@ export function PlatformEntryFlowShellImpl({
          created.session.sessionId,
          {
            actionType: 'compile-draft',
+            themeText:
+              payload?.themeText ?? created.session.draft?.themeText,
            workTitle: payload?.workTitle ?? created.session.draft?.workTitle,
            workDescription:
              payload?.workDescription ??
@@ -9673,7 +9706,7 @@ export function PlatformEntryFlowShellImpl({
  }, [compileJumpHopSession, jumpHopSession, setSelectionStage]);

  const regenerateJumpHopAsset = useCallback(
-    async (actionType: 'regenerate-character' | 'regenerate-tiles') => {
+    async (actionType: 'regenerate-tiles') => {
      if (!jumpHopSession?.sessionId) {
        setSelectionStage('jump-hop-workspace');
        return;
@@ -9689,6 +9722,9 @@ export function PlatformEntryFlowShellImpl({
          jumpHopSession.sessionId,
          {
            actionType,
+            profileId:
+              jumpHopWork?.summary.profileId ?? jumpHopSession.draft?.profileId,
+            themeText: jumpHopSession.draft?.themeText,
            workTitle: jumpHopSession.draft?.workTitle,
            workDescription: jumpHopSession.draft?.workDescription,
            themeTags: jumpHopSession.draft?.themeTags,
@@ -9714,9 +9750,7 @@ export function PlatformEntryFlowShellImpl({
      } catch (error) {
        const errorMessage = resolveRpgCreationErrorMessage(
          error,
-          actionType === 'regenerate-character'
-            ? '重新生成跳一跳角色失败。'
-            : '重新生成跳一跳地块失败。',
+          '重新生成跳一跳地块失败。',
        );
        setJumpHopError(errorMessage);
        setJumpHopGenerationState(
@@ -9792,7 +9826,9 @@ export function PlatformEntryFlowShellImpl({
    setJumpHopError(null);
    setJumpHopRuntimeReturnStage('jump-hop-result');
    try {
-      const response = await jumpHopClient.startRun(profileId);
+      const response = await jumpHopClient.startRun(profileId, {
+        runtimeMode: 'draft',
+      });
      setJumpHopRun(response.run);
      setSelectionStage('jump-hop-runtime');
    } catch (error) {
@@ -9823,13 +9859,30 @@ export function PlatformEntryFlowShellImpl({
      setJumpHopError(null);
      setJumpHopRuntimeReturnStage(options.returnStage ?? 'work-detail');
      try {
-        const runtimeGuestOptions = await buildRecommendRuntimeAuthOptions(
-          authUi,
-          options.embedded,
+        const runtimeGuestOptions =
+          options.embedded || shouldUseRecommendRuntimeGuestAuth(authUi)
+            ? await buildRecommendRuntimeAuthOptions(authUi, true)
+            : RECOMMEND_RUNTIME_BACKGROUND_AUTH_OPTIONS;
+        setJumpHopRuntimeRequestOptions(
+          runtimeGuestOptions.runtimeGuestToken?.trim()
+            ? {
+                runtimeGuestToken: runtimeGuestOptions.runtimeGuestToken,
+                authImpact: runtimeGuestOptions.authImpact,
+                skipAuth: runtimeGuestOptions.skipAuth,
+                skipRefresh: runtimeGuestOptions.skipRefresh,
+                notifyAuthStateChange:
+                  runtimeGuestOptions.notifyAuthStateChange,
+                clearAuthOnUnauthorized:
+                  runtimeGuestOptions.clearAuthOnUnauthorized,
+              }
+            : null,
        );
        const [detail, runResponse] = await Promise.all([
          jumpHopClient.getWorkDetail(normalizedProfileId).catch(() => null),
-          jumpHopClient.startRun(normalizedProfileId, runtimeGuestOptions),
+          jumpHopClient.startRun(normalizedProfileId, {
+            ...runtimeGuestOptions,
+            runtimeMode: 'published',
+          }),
        ]);
        if (detail?.item) {
          setJumpHopWork(detail.item);
@@ -9867,7 +9920,10 @@ export function PlatformEntryFlowShellImpl({
    setIsJumpHopBusy(true);
    setJumpHopError(null);
    try {
-      const response = await jumpHopClient.restartRun(runId);
+      const response = await jumpHopClient.restartRun(
+        runId,
+        jumpHopRuntimeRequestOptions ?? undefined,
+      );
      setJumpHopRun(response.run);
    } catch (error) {
      setJumpHopError(
@@ -9876,16 +9932,29 @@ export function PlatformEntryFlowShellImpl({
    } finally {
      setIsJumpHopBusy(false);
    }
-  }, [jumpHopRun?.runId, startJumpHopTestRunFromProfile]);
+  }, [
+    jumpHopRun?.runId,
+    jumpHopRuntimeRequestOptions,
+    startJumpHopTestRunFromProfile,
+  ]);

  const submitJumpHopJumpAction = useCallback(
-    async (payload: { chargeMs: number }) => {
+    async (
+      payload: Pick<
+        JumpHopJumpRequest,
+        'dragDistance' | 'dragVectorX' | 'dragVectorY'
+      >,
+    ) => {
      const runId = jumpHopRun?.runId;
      if (!runId) {
        return;
      }
      try {
-        const response = await jumpHopClient.submitJump(runId, payload);
+        const response = await jumpHopClient.submitJump(
+          runId,
+          payload,
+          jumpHopRuntimeRequestOptions ?? undefined,
+        );
        setJumpHopRun(response.run);
      } catch (error) {
        setJumpHopError(
@@ -9893,7 +9962,7 @@ export function PlatformEntryFlowShellImpl({
        );
      }
    },
-    [jumpHopRun?.runId],
+    [jumpHopRun?.runId, jumpHopRuntimeRequestOptions],
  );

  const compileWoodenFishSession = useCallback(
@@ -14426,6 +14495,14 @@ export function PlatformEntryFlowShellImpl({
      return;
    }

+    if (isJumpHopGalleryEntry(selectedPublicWorkDetail)) {
+      setPublicWorkDetailError(null);
+      void startJumpHopRunFromProfile(selectedPublicWorkDetail.profileId, {
+        returnStage: 'work-detail',
+      });
+      return;
+    }
+
    runProtectedAction(() => {
      if (isBigFishGalleryEntry(selectedPublicWorkDetail)) {
        const work = mapPublicWorkDetailToBigFishWork(selectedPublicWorkDetail);
@@ -14460,14 +14537,6 @@ export function PlatformEntryFlowShellImpl({
        return;
      }

-      if (isJumpHopGalleryEntry(selectedPublicWorkDetail)) {
-        setPublicWorkDetailError(null);
-        void startJumpHopRunFromProfile(selectedPublicWorkDetail.profileId, {
-          returnStage: 'work-detail',
-        });
-        return;
-      }
-
      if (isWoodenFishGalleryEntry(selectedPublicWorkDetail)) {
        setPublicWorkDetailError(null);
        void startWoodenFishRunFromProfile(selectedPublicWorkDetail.profileId, {
@@ -14970,37 +15039,15 @@ export function PlatformEntryFlowShellImpl({
          run={jumpHopRun}
          isBusy={isJumpHopBusy}
          error={jumpHopError}
+          runtimeRequestOptions={jumpHopRuntimeRequestOptions ?? undefined}
          onBack={() => {
            setActiveRecommendRuntimeKind(null);
          }}
          onRestart={() => {
-            if (!jumpHopRun?.runId || isJumpHopBusy) {
-              return;
-            }
-
-            setIsJumpHopBusy(true);
-            setJumpHopError(null);
-            void jumpHopClient
-              .restartRun(jumpHopRun.runId)
-              .then((response) => {
-                setJumpHopRun(response.run);
-              })
-              .catch((error) => {
-                setJumpHopError(
-                  resolveRpgCreationErrorMessage(error, '重新开始跳一跳失败。'),
-                );
-              })
-              .finally(() => {
-                setIsJumpHopBusy(false);
-              });
+            void restartJumpHopRuntimeRun();
          }}
          onJump={async (payload) => {
-            const runId = jumpHopRun?.runId;
-            if (!runId) {
-              throw new Error('跳一跳运行态缺少 runId。');
-            }
-            const response = await jumpHopClient.submitJump(runId, payload);
-            setJumpHopRun(response.run);
+            await submitJumpHopJumpAction(payload);
          }}
        />
      );
@@ -16969,6 +17016,7 @@ export function PlatformEntryFlowShellImpl({
                )}
                progress={buildMiniGameDraftGenerationProgress(
                  bigFishGenerationState,
+                  miniGameGenerationProgressNowMs,
                )}
                isGenerating={isBigFishBusy}
                error={bigFishError}
@@ -17577,6 +17625,7 @@ export function PlatformEntryFlowShellImpl({
                )}
                progress={buildMiniGameDraftGenerationProgress(
                  squareHoleGenerationState,
+                  miniGameGenerationProgressNowMs,
                )}
                isGenerating={isSquareHoleBusy}
                error={squareHoleError}
@@ -17789,6 +17838,7 @@ export function PlatformEntryFlowShellImpl({
                )}
                progress={buildMiniGameDraftGenerationProgress(
                  jumpHopGenerationState,
+                  miniGameGenerationProgressNowMs,
                )}
                isGenerating={isJumpHopBusy}
                error={jumpHopError}
@@ -17830,9 +17880,6 @@ export function PlatformEntryFlowShellImpl({
                      }}
                      onStartTestRun={startJumpHopTestRunFromProfile}
                      onPublish={publishJumpHopDraft}
-                      onRegenerateCharacter={() => {
-                        void regenerateJumpHopAsset('regenerate-character');
-                      }}
                      onRegenerateTiles={() => {
                        void regenerateJumpHopAsset('regenerate-tiles');
                      }}
@@ -17868,6 +17915,7 @@ export function PlatformEntryFlowShellImpl({
                profile={jumpHopWork}
                isBusy={isJumpHopBusy}
                error={jumpHopError}
+                runtimeRequestOptions={jumpHopRuntimeRequestOptions ?? undefined}
                onBack={() => {
                  setSelectionStage(jumpHopRuntimeReturnStage);
                }}
@@ -17929,6 +17977,7 @@ export function PlatformEntryFlowShellImpl({
                )}
                progress={buildMiniGameDraftGenerationProgress(
                  woodenFishGenerationState,
+                  miniGameGenerationProgressNowMs,
                )}
                isGenerating={isWoodenFishBusy}
                error={woodenFishError}
@@ -14,14 +14,15 @@ import type {
  CustomWorldWorkSummary,
 } from '../../../packages/shared/src/contracts/customWorldAgent';
 import type {
-  BabyObjectMatchDraft,
-  CreateBabyObjectMatchDraftRequest,
-} from '../../../packages/shared/src/contracts/edutainmentBabyObject';
-import type {
+  JumpHopRuntimeRunSnapshotResponse,
  JumpHopWorkDetailResponse,
  JumpHopWorkProfileResponse,
  JumpHopWorkSummaryResponse,
 } from '../../../packages/shared/src/contracts/jumpHop';
+import type {
+  BabyObjectMatchDraft,
+  CreateBabyObjectMatchDraftRequest,
+} from '../../../packages/shared/src/contracts/edutainmentBabyObject';
 import type { Match3DAgentSessionSnapshot } from '../../../packages/shared/src/contracts/match3dAgent';
 import type { Match3DRunSnapshot } from '../../../packages/shared/src/contracts/match3dRuntime';
 import type { Match3DWorkSummary } from '../../../packages/shared/src/contracts/match3dWorks';
@@ -70,6 +71,7 @@ import {
  submitBigFishInput,
 } from '../../services/big-fish-runtime';
 import { listBigFishWorks } from '../../services/big-fish-works';
+import { jumpHopClient } from '../../services/jump-hop/jumpHopClient';
 import {
  type CreationEntryConfig,
  fetchCreationEntryConfig,
@@ -89,7 +91,6 @@ import {
  regenerateBabyObjectMatchDraftAssets,
  saveBabyObjectMatchDraft,
 } from '../../services/edutainment-baby-object';
-import { jumpHopClient } from '../../services/jump-hop/jumpHopClient';
 import { match3dCreationClient } from '../../services/match3d-creation';
 import { createServerMatch3DRuntimeAdapter } from '../../services/match3d-runtime';
 import {
@@ -610,6 +611,24 @@ vi.mock('../../services/puzzle-runtime', () => ({
  usePuzzleRuntimeProp: vi.fn(),
 }));

+vi.mock('../../services/jump-hop/jumpHopClient', () => ({
+  jumpHopClient: {
+    createSession: vi.fn(),
+    deleteWork: vi.fn(),
+    executeAction: vi.fn(),
+    getGalleryDetail: vi.fn(),
+    getLeaderboard: vi.fn(),
+    getSession: vi.fn(),
+    getWorkDetail: vi.fn(),
+    listGallery: vi.fn(),
+    listWorks: vi.fn(),
+    publishWork: vi.fn(),
+    restartRun: vi.fn(),
+    startRun: vi.fn(),
+    submitJump: vi.fn(),
+  },
+}));
+
 vi.mock('../../services/rpg-entry/rpgEntryLibraryClient', () => ({
  ...rpgEntryLibraryServiceMocks,
 }));
@@ -657,23 +676,6 @@ vi.mock('../../services/edutainment-baby-object', () => ({
  saveBabyObjectMatchDraft: vi.fn(),
 }));

-vi.mock('../../services/jump-hop/jumpHopClient', () => ({
-  jumpHopClient: {
-    createSession: vi.fn(),
-    deleteWork: vi.fn(),
-    executeAction: vi.fn(),
-    getGalleryDetail: vi.fn(),
-    getSession: vi.fn(),
-    getWorkDetail: vi.fn(),
-    listGallery: vi.fn(),
-    listWorks: vi.fn(),
-    publishWork: vi.fn(),
-    restartRun: vi.fn(),
-    startRun: vi.fn(),
-    submitJump: vi.fn(),
-  },
-}));
-
 vi.mock('../../services/wooden-fish/woodenFishClient', () => ({
  woodenFishClient: {
    checkpointRun: vi.fn(),
@@ -684,9 +686,14 @@ vi.mock('../../services/wooden-fish/woodenFishClient', () => ({
    getGalleryDetail: vi.fn(),
    getSession: vi.fn(),
    getWorkDetail: vi.fn(),
-    listGallery: vi.fn(),
-    listWorks: vi.fn(),
+    listGallery: vi.fn(async () => ({
+      hasMore: false,
+      items: [],
+      nextCursor: null,
+    })),
+    listWorks: vi.fn(async () => ({ items: [] })),
    publishWork: vi.fn(),
+    restartRun: vi.fn(),
    startRun: vi.fn(),
  },
 }));
@@ -804,23 +811,6 @@ vi.mock('../../services/visual-novel-works', () => ({
  updateVisualNovelWork: vi.fn(),
 }));

-vi.mock('../../services/wooden-fish/woodenFishClient', () => ({
-  woodenFishClient: {
-    checkpointRun: vi.fn(),
-    createSession: vi.fn(),
-    deleteWork: vi.fn(),
-    executeAction: vi.fn(),
-    finishRun: vi.fn(),
-    getGalleryDetail: vi.fn(),
-    getSession: vi.fn(),
-    getWorkDetail: vi.fn(),
-    listGallery: vi.fn(),
-    listWorks: vi.fn(),
-    publishWork: vi.fn(),
-    startRun: vi.fn(),
-  },
-}));
-
 vi.mock('../../services/visual-novel-creation', () => ({
  compileVisualNovelWorkProfile: vi.fn(),
  createVisualNovelSession: vi.fn(),
@@ -1636,6 +1626,7 @@ function buildMockJumpHopWork(
    templateId: 'jump-hop',
    templateName: '跳一跳',
    profileId,
+    themeText: '云朵跳台',
    workTitle: '云端跳台',
    workDescription: '一路跳到星星。',
    themeTags: ['云朵', '星空'],
@@ -1649,6 +1640,7 @@ function buildMockJumpHopWork(
    tileAssets,
    path,
    coverComposite: 'data:image/png;base64,cover',
+    backButtonAsset: null,
    generationStatus: 'ready' as const,
  };

@@ -1659,6 +1651,7 @@ function buildMockJumpHopWork(
      profileId,
      ownerUserId: 'user-1',
      sourceSessionId: 'jump-hop-session-1',
+      themeText: draft.themeText,
      workTitle: draft.workTitle,
      workDescription: draft.workDescription,
      themeTags: draft.themeTags,
@@ -1678,6 +1671,7 @@ function buildMockJumpHopWork(
    characterAsset,
    tileAtlasAsset,
    tileAssets,
+    backButtonAsset: null,
  };
 }

@@ -5354,7 +5348,7 @@ test('match3d result trial passes generated models into first runtime mount', as
  await waitFor(() => {
    expect(match3dServerRuntimeAdapterMock.startRun).toHaveBeenCalledWith(
      'match3d-profile-draft-1',
-      {},
+      ISOLATED_RUNTIME_AUTH_OPTIONS,
    );
  });
  expect(
@@ -5447,7 +5441,7 @@ test('match3d result trial passes generated 2D image views into first runtime mo
  await waitFor(() => {
    expect(match3dServerRuntimeAdapterMock.startRun).toHaveBeenCalledWith(
      'match3d-profile-draft-2d-1',
-      {},
+      ISOLATED_RUNTIME_AUTH_OPTIONS,
    );
  });
  expect(
@@ -6471,10 +6465,10 @@ test('opening a compiled draft with a missing agent session falls back to draft
  await waitFor(() => {
    expect(fallbackDraftPanel.getAttribute('aria-hidden')).toBe('false');
    expect(
-      within(fallbackDraftPanel).getByText(
+      screen.getAllByText(
        '这份共创草稿已失效，已为你返回草稿列表，请重新开始创作。',
-      ),
-    ).toBeTruthy();
+      ).length,
+    ).toBeGreaterThan(0);
  });

  expect(window.location.search).toBe('');
@@ -6590,6 +6584,213 @@ test('logged out public detail gates puzzle start and remix before real actions'
  expect(remixPuzzleGalleryWork).not.toHaveBeenCalled();
 });

+test('logged out public jump-hop detail starts runtime without requireAuth', async () => {
+  const user = userEvent.setup();
+  const requireAuth = vi.fn();
+  const publishedJumpHopWork: JumpHopWorkProfileResponse = {
+    summary: {
+      runtimeKind: 'jump-hop',
+      workId: 'jump-hop-work-public-1',
+      profileId: 'jump-hop-profile-public-12345678',
+      ownerUserId: 'user-2',
+      sourceSessionId: 'jump-hop-session-public-1',
+      themeText: '云上方块',
+      workTitle: '云上方块跳一跳',
+      workDescription: '在云层地块之间连续弹跳。',
+      themeTags: ['云层', '跳跃'],
+      difficulty: 'standard',
+      stylePreset: 'paper-toy',
+      coverImageSrc: null,
+      publicationStatus: 'published',
+      playCount: 3,
+      updatedAt: '2026-05-29T10:00:00.000Z',
+      publishedAt: '2026-05-29T10:00:00.000Z',
+      publishReady: true,
+      generationStatus: 'ready',
+    },
+    draft: {
+      templateId: 'jump-hop',
+      templateName: '跳一跳',
+      profileId: 'jump-hop-profile-public-12345678',
+      themeText: '云上方块',
+      workTitle: '云上方块跳一跳',
+      workDescription: '在云层地块之间连续弹跳。',
+      themeTags: ['云层', '跳跃'],
+      difficulty: 'standard',
+      stylePreset: 'paper-toy',
+      defaultCharacter: {
+        characterId: 'builtin-default',
+        displayName: '默认角色',
+        modelKind: 'builtin-three',
+        bodyColor: '#df7f40',
+        accentColor: '#2563eb',
+      },
+      characterPrompt: '',
+      tilePrompt: '云上方块',
+      endMoodPrompt: null,
+      characterAsset: null,
+      tileAtlasAsset: null,
+      tileAssets: [],
+      path: null,
+      coverComposite: null,
+      generationStatus: 'ready',
+    },
+    path: {
+      seed: 'jump-hop-public-seed',
+      difficulty: 'standard',
+      platforms: [
+        {
+          platformId: 'platform-0',
+          tileType: 'start',
+          x: 0,
+          y: 0,
+          width: 1,
+          height: 1,
+          landingRadius: 0.7,
+          perfectRadius: 0.25,
+          scoreValue: 1,
+        },
+        {
+          platformId: 'platform-1',
+          tileType: 'normal',
+          x: 1,
+          y: 1,
+          width: 1,
+          height: 1,
+          landingRadius: 0.7,
+          perfectRadius: 0.25,
+          scoreValue: 1,
+        },
+        {
+          platformId: 'platform-2',
+          tileType: 'normal',
+          x: -1,
+          y: 2,
+          width: 1,
+          height: 1,
+          landingRadius: 0.7,
+          perfectRadius: 0.25,
+          scoreValue: 1,
+        },
+      ],
+      finishIndex: 2,
+      cameraPreset: 'portrait-top-down',
+      scoring: {
+        chargeToDistanceRatio: 1,
+        maxChargeMs: 1800,
+        hitBonus: 0,
+        perfectBonus: 0,
+      },
+    },
+    defaultCharacter: {
+      characterId: 'builtin-default',
+      displayName: '默认角色',
+      modelKind: 'builtin-three',
+      bodyColor: '#df7f40',
+      accentColor: '#2563eb',
+    },
+    characterAsset: {
+      assetId: 'builtin-character',
+      imageSrc: '',
+      imageObjectKey: '',
+      assetObjectId: '',
+      generationProvider: 'builtin',
+      prompt: '',
+      width: 1,
+      height: 1,
+    },
+    tileAtlasAsset: {
+      assetId: 'tile-atlas-1',
+      imageSrc: '/generated-jump-hop-assets/public/atlas.png',
+      imageObjectKey: 'generated-jump-hop-assets/public/atlas.png',
+      assetObjectId: 'asset-tile-atlas-1',
+      generationProvider: 'gpt-image-2',
+      prompt: '云上方块',
+      width: 1024,
+      height: 1024,
+    },
+    tileAssets: [],
+  };
+  const publishedJumpHopRun: JumpHopRuntimeRunSnapshotResponse = {
+    runId: 'jump-hop-run-public-1',
+    profileId: publishedJumpHopWork.summary.profileId,
+    ownerUserId: '',
+    status: 'playing',
+    currentPlatformIndex: 0,
+    successfulJumpCount: 0,
+    durationMs: 0,
+    score: 0,
+    combo: 0,
+    path: publishedJumpHopWork.path,
+    lastJump: null,
+    startedAtMs: 1_779_999_000_000,
+    finishedAtMs: null,
+  };
+
+  window.history.replaceState(null, '', '/works/detail?work=JH-12345678');
+  vi.mocked(jumpHopClient.listGallery).mockResolvedValue({
+    items: [
+      {
+        publicWorkCode: 'JH-12345678',
+        workId: publishedJumpHopWork.summary.workId,
+        profileId: publishedJumpHopWork.summary.profileId,
+        ownerUserId: publishedJumpHopWork.summary.ownerUserId,
+        authorDisplayName: '跳跃作者',
+        themeText: publishedJumpHopWork.summary.themeText,
+        workTitle: publishedJumpHopWork.summary.workTitle,
+        workDescription: publishedJumpHopWork.summary.workDescription,
+        coverImageSrc: null,
+        themeTags: publishedJumpHopWork.summary.themeTags,
+        difficulty: publishedJumpHopWork.summary.difficulty,
+        stylePreset: publishedJumpHopWork.summary.stylePreset,
+        publicationStatus: publishedJumpHopWork.summary.publicationStatus,
+        playCount: publishedJumpHopWork.summary.playCount,
+        updatedAt: publishedJumpHopWork.summary.updatedAt,
+        publishedAt: publishedJumpHopWork.summary.publishedAt,
+        generationStatus: publishedJumpHopWork.summary.generationStatus,
+      },
+    ],
+    hasMore: false,
+    nextCursor: null,
+  });
+  vi.mocked(jumpHopClient.getWorkDetail).mockResolvedValue({
+    item: publishedJumpHopWork,
+  });
+  vi.mocked(jumpHopClient.startRun).mockResolvedValue({
+    run: publishedJumpHopRun,
+  });
+  vi.mocked(jumpHopClient.getLeaderboard).mockResolvedValue({
+    profileId: publishedJumpHopWork.summary.profileId,
+    items: [],
+    viewerBest: null,
+  });
+
+  render(
+    <TestWrapper
+      authValue={createAuthValue({
+        user: null,
+        canAccessProtectedData: false,
+        openLoginModal: () => {},
+        requireAuth,
+      })}
+    />,
+  );
+
+  expect(await screen.findByText('详情')).toBeTruthy();
+  await user.click(screen.getByRole('button', { name: '启动' }));
+
+  await waitFor(() => {
+    expect(jumpHopClient.startRun).toHaveBeenCalledWith(
+      publishedJumpHopWork.summary.profileId,
+      expect.objectContaining({
+        runtimeGuestToken: 'runtime-guest-token',
+        runtimeMode: 'published',
+      }),
+    );
+  });
+  expect(requireAuth).not.toHaveBeenCalled();
+});
+
 test('owned public puzzle detail edits original draft instead of remixing', async () => {
  const user = userEvent.setup();
  const ownedPuzzleWork = {
@@ -8050,6 +8251,7 @@ test('direct jump hop result route restores work detail by profile id', async ()
      profileId: 'jump-hop-profile-restore-1',
      ownerUserId: 'user-1',
      sourceSessionId: null,
+      themeText: '恢复后的云端跳台',
      workTitle: '恢复后的云端跳台',
      workDescription: '从 profileId 回读完整跳一跳结果。',
      themeTags: ['云朵'],
@@ -9222,7 +9424,7 @@ test('public code search opens a published Match3D work by M3 code and starts ru
  await waitFor(() => {
    expect(match3dServerRuntimeAdapterMock.startRun).toHaveBeenCalledWith(
      'match3d-profile-public-1',
-      {},
+      LOGGED_IN_RECOMMEND_RUNTIME_AUTH_OPTIONS,
    );
  });
  expect(
@@ -9294,7 +9496,7 @@ test('published Match3D runtime receives persisted generated models', async () =
  await waitFor(() => {
    expect(match3dServerRuntimeAdapterMock.startRun).toHaveBeenCalledWith(
      'match3d-profile-model-1',
-      {},
+      LOGGED_IN_RECOMMEND_RUNTIME_AUTH_OPTIONS,
    );
  });
  expect(
@@ -111,53 +111,11 @@ const FALLBACK_UNIFIED_CREATION_SPECS: Record<
    resultStage: 'jump-hop-result',
    fields: [
      {
-        id: 'workTitle',
+        id: 'themeText',
        kind: 'text',
-        label: '作品标题',
+        label: '主题',
        required: true,
      },
-      {
-        id: 'workDescription',
-        kind: 'text',
-        label: '作品简介',
-        required: true,
-      },
-      {
-        id: 'themeTags',
-        kind: 'text',
-        label: '主题标签',
-        required: true,
-      },
-      {
-        id: 'difficulty',
-        kind: 'select',
-        label: '难度',
-        required: true,
-      },
-      {
-        id: 'stylePreset',
-        kind: 'select',
-        label: '风格',
-        required: true,
-      },
-      {
-        id: 'characterPrompt',
-        kind: 'text',
-        label: '角色提示词',
-        required: true,
-      },
-      {
-        id: 'tilePrompt',
-        kind: 'text',
-        label: '地块提示词',
-        required: true,
-      },
-      {
-        id: 'endMoodPrompt',
-        kind: 'text',
-        label: '终点氛围',
-        required: false,
-      },
    ],
  },
  'wooden-fish': {
@@ -33,7 +33,7 @@ function createSessionResponse(): JumpHopSessionResponse {
  };
 }

-test('jump hop workspace submits structured payload after required fields are filled', async () => {
+test('jump hop workspace submits theme payload after required field is filled', async () => {
  const user = userEvent.setup();
  const onSubmitted = vi.fn();
  const sessionResponse = createSessionResponse();
@@ -46,14 +46,11 @@ test('jump hop workspace submits structured payload after required fields are fi
  const submitButton = screen.getByRole('button', { name: '生成' });
  expect(submitButton).toHaveProperty('disabled', true);

-  await user.type(screen.getByLabelText('作品标题'), '云朵跳台');
-  await user.type(screen.getByLabelText('作品简介'), '在云端一路跳到星星。');
-  await user.type(screen.getByLabelText('主题标签'), '云朵 星星');
-  await user.selectOptions(screen.getByLabelText('难度'), 'standard');
-  await user.selectOptions(screen.getByLabelText('风格'), 'paper-toy');
-  await user.type(screen.getByLabelText('角色提示词'), '一只纸片小兔');
-  await user.type(screen.getByLabelText('地块提示词'), '柔软云朵平台');
-  await user.type(screen.getByLabelText('终点氛围'), '星光门');
+  expect(screen.getByLabelText('主题')).toBeTruthy();
+  expect(screen.queryByLabelText('作品标题')).toBeNull();
+  expect(screen.queryByLabelText('角色提示词')).toBeNull();
+
+  await user.type(screen.getByLabelText('主题'), '云朵跳台');

  expect(submitButton).toHaveProperty('disabled', false);
  await user.click(submitButton);
@@ -61,21 +58,22 @@ test('jump hop workspace submits structured payload after required fields are fi
  await waitFor(() => {
    expect(mockCreateSession).toHaveBeenCalledWith({
      templateId: 'jump-hop',
-      workTitle: '云朵跳台',
-      workDescription: '在云端一路跳到星星。',
-      themeTags: ['云朵', '星星'],
+      themeText: '云朵跳台',
+      workTitle: '云朵跳台跳一跳',
+      workDescription: '云朵跳台主题的俯视角跳跃作品',
+      themeTags: ['云朵跳台', '跳一跳', '休闲'],
      difficulty: 'standard',
-      stylePreset: 'paper-toy',
-      characterPrompt: '一只纸片小兔',
-      tilePrompt: '柔软云朵平台',
-      endMoodPrompt: '星光门',
+      stylePreset: 'minimal-blocks',
+      characterPrompt: '内置默认 3D 角色',
+      tilePrompt: '云朵跳台主题的正面30度视角主题物体图集，物体本身作为跳跃落点',
+      endMoodPrompt: null,
    });
  });
  expect(onSubmitted).toHaveBeenCalledWith(
    sessionResponse,
    expect.objectContaining({
      templateId: 'jump-hop',
-      workTitle: '云朵跳台',
+      themeText: '云朵跳台',
    }),
  );
 });
@@ -2,9 +2,7 @@ import { ArrowLeft, Loader2, Send } from 'lucide-react';
 import { useMemo, useState } from 'react';

 import type {
-  JumpHopDifficulty,
  JumpHopSessionResponse,
-  JumpHopStylePreset,
  JumpHopWorkspaceCreateRequest,
 } from '../../../../packages/shared/src/contracts/jumpHop';
 import { jumpHopClient } from '../../../services/jump-hop/jumpHopClient';
@@ -22,27 +20,31 @@ type JumpHopCreationWorkspaceProps = {
 };

 type JumpHopWorkspaceFormState = {
-  workTitle: string;
-  workDescription: string;
-  themeTags: string;
-  difficulty: JumpHopDifficulty;
-  stylePreset: JumpHopStylePreset;
-  characterPrompt: string;
-  tilePrompt: string;
-  endMoodPrompt: string;
+  themeText: string;
 };

 const DEFAULT_FORM_STATE: JumpHopWorkspaceFormState = {
-  workTitle: '',
-  workDescription: '',
-  themeTags: '',
-  difficulty: 'easy',
-  stylePreset: 'minimal-blocks',
-  characterPrompt: '',
-  tilePrompt: '',
-  endMoodPrompt: '',
+  themeText: '',
 };

+function buildJumpHopWorkspacePayload(
+  formState: JumpHopWorkspaceFormState,
+): JumpHopWorkspaceCreateRequest {
+  const themeText = formState.themeText.trim();
+  return {
+    templateId: 'jump-hop',
+    themeText,
+    workTitle: `${themeText}跳一跳`,
+    workDescription: `${themeText}主题的俯视角跳跃作品`,
+    themeTags: [themeText, '跳一跳', '休闲'],
+    difficulty: 'standard',
+    stylePreset: 'minimal-blocks',
+    characterPrompt: '内置默认 3D 角色',
+    tilePrompt: `${themeText}主题的正面30度视角主题物体图集，物体本身作为跳跃落点`,
+    endMoodPrompt: null,
+  };
+}
+
 export function JumpHopCreationWorkspace({
  isBusy = false,
  error = null,
@@ -56,14 +58,7 @@ export function JumpHopCreationWorkspace({
  const [isSubmitting, setIsSubmitting] = useState(false);

  const canSubmit = useMemo(
-    () =>
-      Boolean(
-        formState.workTitle.trim() &&
-          formState.workDescription.trim() &&
-          formState.themeTags.trim() &&
-          formState.characterPrompt.trim() &&
-          formState.tilePrompt.trim(),
-      ),
+    () => Boolean(formState.themeText.trim()),
    [formState],
  );

@@ -77,20 +72,7 @@ export function JumpHopCreationWorkspace({
    setLocalError(null);

    try {
-      const payload: JumpHopWorkspaceCreateRequest = {
-        templateId: 'jump-hop',
-        workTitle: formState.workTitle.trim(),
-        workDescription: formState.workDescription.trim(),
-        themeTags: formState.themeTags
-          .split(/[，,、\s]+/)
-          .map((item) => item.trim())
-          .filter(Boolean),
-        difficulty: formState.difficulty,
-        stylePreset: formState.stylePreset,
-        characterPrompt: formState.characterPrompt.trim(),
-        tilePrompt: formState.tilePrompt.trim(),
-        endMoodPrompt: formState.endMoodPrompt.trim() || null,
-      };
+      const payload = buildJumpHopWorkspacePayload(formState);
      const response = await jumpHopClient.createSession(payload);
      onSubmitted(response, payload);
    } catch (caughtError) {
@@ -124,143 +106,22 @@ export function JumpHopCreationWorkspace({
        </div>
      ) : null}

-      <div className="grid gap-3 sm:grid-cols-2">
+      <div className="grid gap-3">
        <label className="block sm:col-span-2">
          <span className="text-xs font-bold tracking-[0.18em] text-[var(--platform-text-soft)]">
-            作品标题
+            主题
          </span>
          <input
-            value={formState.workTitle}
+            value={formState.themeText}
            onChange={(event) =>
              setFormState((current) => ({
                ...current,
-                workTitle: event.target.value,
+                themeText: event.target.value,
              }))
            }
            className="mt-2 w-full rounded-[1rem] border border-[var(--platform-subpanel-border)] bg-white/90 px-3 py-3 text-sm font-semibold text-[var(--platform-text-strong)] outline-none"
          />
        </label>
-        <label className="block sm:col-span-2">
-          <span className="text-xs font-bold tracking-[0.18em] text-[var(--platform-text-soft)]">
-            作品简介
-          </span>
-          <textarea
-            value={formState.workDescription}
-            onChange={(event) =>
-              setFormState((current) => ({
-                ...current,
-                workDescription: event.target.value,
-              }))
-            }
-            rows={3}
-            className="mt-2 w-full resize-none rounded-[1rem] border border-[var(--platform-subpanel-border)] bg-white/90 px-3 py-3 text-sm leading-6 text-[var(--platform-text-strong)] outline-none"
-          />
-        </label>
-        <label className="block sm:col-span-2">
-          <span className="text-xs font-bold tracking-[0.18em] text-[var(--platform-text-soft)]">
-            主题标签
-          </span>
-          <input
-            value={formState.themeTags}
-            onChange={(event) =>
-              setFormState((current) => ({
-                ...current,
-                themeTags: event.target.value,
-              }))
-            }
-            className="mt-2 w-full rounded-[1rem] border border-[var(--platform-subpanel-border)] bg-white/90 px-3 py-3 text-sm font-semibold text-[var(--platform-text-strong)] outline-none"
-          />
-        </label>
-        <label className="block">
-          <span className="text-xs font-bold tracking-[0.18em] text-[var(--platform-text-soft)]">
-            难度
-          </span>
-          <select
-            value={formState.difficulty}
-            onChange={(event) =>
-              setFormState((current) => ({
-                ...current,
-                difficulty: event.target.value as JumpHopDifficulty,
-              }))
-            }
-            className="mt-2 w-full rounded-[1rem] border border-[var(--platform-subpanel-border)] bg-white/90 px-3 py-3 text-sm font-semibold text-[var(--platform-text-strong)] outline-none"
-          >
-            <option value="easy">easy</option>
-            <option value="standard">standard</option>
-            <option value="advanced">advanced</option>
-            <option value="challenge">challenge</option>
-          </select>
-        </label>
-        <label className="block">
-          <span className="text-xs font-bold tracking-[0.18em] text-[var(--platform-text-soft)]">
-            风格
-          </span>
-          <select
-            value={formState.stylePreset}
-            onChange={(event) =>
-              setFormState((current) => ({
-                ...current,
-                stylePreset: event.target.value as JumpHopStylePreset,
-              }))
-            }
-            className="mt-2 w-full rounded-[1rem] border border-[var(--platform-subpanel-border)] bg-white/90 px-3 py-3 text-sm font-semibold text-[var(--platform-text-strong)] outline-none"
-          >
-            <option value="minimal-blocks">minimal-blocks</option>
-            <option value="paper-toy">paper-toy</option>
-            <option value="neon-glass">neon-glass</option>
-            <option value="forest-stone">forest-stone</option>
-            <option value="future-metal">future-metal</option>
-            <option value="custom">custom</option>
-          </select>
-        </label>
-        <label className="block sm:col-span-2">
-          <span className="text-xs font-bold tracking-[0.18em] text-[var(--platform-text-soft)]">
-            角色提示词
-          </span>
-          <textarea
-            value={formState.characterPrompt}
-            onChange={(event) =>
-              setFormState((current) => ({
-                ...current,
-                characterPrompt: event.target.value,
-              }))
-            }
-            rows={3}
-            className="mt-2 w-full resize-none rounded-[1rem] border border-[var(--platform-subpanel-border)] bg-white/90 px-3 py-3 text-sm leading-6 text-[var(--platform-text-strong)] outline-none"
-          />
-        </label>
-        <label className="block sm:col-span-2">
-          <span className="text-xs font-bold tracking-[0.18em] text-[var(--platform-text-soft)]">
-            地块提示词
-          </span>
-          <textarea
-            value={formState.tilePrompt}
-            onChange={(event) =>
-              setFormState((current) => ({
-                ...current,
-                tilePrompt: event.target.value,
-              }))
-            }
-            rows={3}
-            className="mt-2 w-full resize-none rounded-[1rem] border border-[var(--platform-subpanel-border)] bg-white/90 px-3 py-3 text-sm leading-6 text-[var(--platform-text-strong)] outline-none"
-          />
-        </label>
-        <label className="block sm:col-span-2">
-          <span className="text-xs font-bold tracking-[0.18em] text-[var(--platform-text-soft)]">
-            终点氛围
-          </span>
-          <textarea
-            value={formState.endMoodPrompt}
-            onChange={(event) =>
-              setFormState((current) => ({
-                ...current,
-                endMoodPrompt: event.target.value,
-              }))
-            }
-            rows={2}
-            className="mt-2 w-full resize-none rounded-[1rem] border border-[var(--platform-subpanel-border)] bg-white/90 px-3 py-3 text-sm leading-6 text-[var(--platform-text-strong)] outline-none"
-          />
-        </label>
      </div>

      {localError || error ? (
@@ -39,3 +39,104 @@ test('jump hop delete work uses creation works endpoint', async () => {
    '删除跳一跳作品失败',
  );
 });
+
+test('jump hop creation keeps image2 generation requests alive long enough', async () => {
+  await import('./jumpHopClient');
+
+  expect(createCreationAgentClientMock).toHaveBeenCalledWith(
+    expect.objectContaining({
+      createSessionTimeoutMs: 20 * 60 * 1000,
+      executeActionTimeoutMs: 20 * 60 * 1000,
+    }),
+  );
+});
+
+test('jump hop work detail preserves flattened back button asset', async () => {
+  const backButtonAsset = {
+    assetId: 'back-button-1',
+    imageSrc: '/generated-jump-hop-assets/back-button-1.png',
+    imageObjectKey: 'jump-hop/back-button-1.png',
+    assetObjectId: 'asset-object-back-button-1',
+    generationProvider: 'image2',
+    prompt: '主题返回按钮',
+    width: 1024,
+    height: 1024,
+  };
+  const characterAsset = {
+    assetId: 'character-1',
+    imageSrc: 'builtin://jump-hop/default-character',
+    imageObjectKey: '',
+    assetObjectId: 'character-object-1',
+    generationProvider: 'builtin-three',
+    prompt: '内置默认角色',
+    width: 0,
+    height: 0,
+  };
+  const draft = {
+    templateId: 'jump-hop',
+    templateName: '跳一跳',
+    profileId: 'profile-1',
+    themeText: '森林茶馆',
+    workTitle: '森林茶馆跳一跳',
+    workDescription: '森林茶馆主题',
+    themeTags: ['森林茶馆', '跳一跳'],
+    difficulty: 'standard',
+    stylePreset: 'minimal-blocks',
+    defaultCharacter: null,
+    characterPrompt: '内置默认角色',
+    tilePrompt: '森林茶馆主题地块',
+    endMoodPrompt: null,
+    characterAsset,
+    tileAtlasAsset: characterAsset,
+    tileAssets: [],
+    path: {
+      seed: 'profile-1',
+      difficulty: 'standard',
+      platforms: [],
+      scoring: {
+        perfectRadiusRatio: 0.24,
+        hitRadiusRatio: 0.52,
+        maxChargeMs: 1200,
+        minChargeMs: 80,
+        maxJumpDistance: 5,
+      },
+    },
+    coverComposite: null,
+    backButtonAsset: null,
+    generationStatus: 'ready',
+  };
+  requestJsonMock.mockResolvedValue({
+    item: {
+      runtimeKind: 'jump-hop',
+      workId: 'work-1',
+      profileId: 'profile-1',
+      ownerUserId: 'owner-1',
+      sourceSessionId: 'session-1',
+      themeText: '森林茶馆',
+      workTitle: '森林茶馆跳一跳',
+      workDescription: '森林茶馆主题',
+      themeTags: ['森林茶馆', '跳一跳'],
+      difficulty: 'standard',
+      stylePreset: 'minimal-blocks',
+      coverImageSrc: null,
+      publicationStatus: 'published',
+      playCount: 0,
+      updatedAt: '2026-06-05T00:00:00Z',
+      publishedAt: '2026-06-05T00:00:00Z',
+      publishReady: true,
+      generationStatus: 'ready',
+      draft,
+      path: draft.path,
+      defaultCharacter: null,
+      characterAsset,
+      tileAtlasAsset: characterAsset,
+      tileAssets: [],
+      backButtonAsset,
+    },
+  });
+
+  const { jumpHopClient } = await import('./jumpHopClient');
+  const response = await jumpHopClient.getWorkDetail('profile-1');
+
+  expect(response.item.backButtonAsset).toEqual(backButtonAsset);
+});
@@ -5,6 +5,7 @@ import type {
  JumpHopGalleryCardResponse,
  JumpHopGalleryDetailResponse,
  JumpHopGalleryResponse,
+  JumpHopLeaderboardResponse,
  JumpHopRunResponse,
  JumpHopRuntimeRunSnapshotResponse,
  JumpHopSessionResponse,
@@ -12,8 +13,8 @@ import type {
  JumpHopWorkDetailResponse,
  JumpHopWorkMutationResponse,
  JumpHopWorkProfileResponse,
-  JumpHopWorksResponse,
  JumpHopWorkspaceCreateRequest,
+  JumpHopWorksResponse,
  JumpHopWorkSummaryResponse,
 } from '../../../packages/shared/src/contracts/jumpHop';
 import {
@@ -30,12 +31,23 @@ import {
 const JUMP_HOP_API_BASE = '/api/creation/jump-hop/sessions';
 const JUMP_HOP_WORKS_API_BASE = '/api/creation/jump-hop/works';
 const JUMP_HOP_RUNTIME_API_BASE = '/api/runtime/jump-hop';
+// 中文注释：跳一跳创作会等待背景图、25 格图集、切片和 OSS 写入，不能沿用共创会话默认 15 秒超时。
+const JUMP_HOP_GENERATION_TIMEOUT_MS = 20 * 60 * 1000;
 const JUMP_HOP_RUNTIME_READ_RETRY: ApiRetryOptions = {
  maxRetries: 1,
  baseDelayMs: 120,
  maxDelayMs: 360,
 };
-type JumpHopRuntimeRequestOptions = RuntimeGuestRequestOptions;
+export type JumpHopRuntimeRequestOptions = RuntimeGuestRequestOptions;
+type JumpHopRuntimeMode = 'draft' | 'published';
+type JumpHopStartRunOptions = JumpHopRuntimeRequestOptions & {
+  runtimeMode?: JumpHopRuntimeMode;
+};
+type JumpHopJumpPayload = {
+  dragDistance: number;
+  dragVectorX?: number;
+  dragVectorY?: number;
+};

 export type {
  JumpHopActionRequest,
@@ -44,6 +56,7 @@ export type {
  JumpHopGalleryCardResponse,
  JumpHopGalleryDetailResponse,
  JumpHopGalleryResponse,
+  JumpHopLeaderboardResponse,
  JumpHopRunResponse,
  JumpHopRuntimeRunSnapshotResponse,
  JumpHopSessionResponse,
@@ -51,16 +64,10 @@ export type {
  JumpHopWorkDetailResponse,
  JumpHopWorkMutationResponse,
  JumpHopWorkProfileResponse,
-  JumpHopWorksResponse,
  JumpHopWorkspaceCreateRequest,
+  JumpHopWorksResponse,
 };
-export type CreateJumpHopSessionRequest = {
-  themeText: string;
-  characterDescription: string;
-  tileStyle: string;
-  difficulty: string;
-  rhythmPreference: string;
-};
+export type CreateJumpHopSessionRequest = JumpHopWorkspaceCreateRequest;
 export type ExecuteJumpHopActionRequest = JumpHopActionRequest;
 export type JumpHopSessionSnapshot = JumpHopSessionSnapshotResponse;

@@ -82,6 +89,8 @@ const jumpHopCreationClient = createCreationAgentClient<
    streamIncomplete: '跳一跳共创消息流式结果不完整',
    executeAction: '执行跳一跳共创操作失败',
  },
+  createSessionTimeoutMs: JUMP_HOP_GENERATION_TIMEOUT_MS,
+  executeActionTimeoutMs: JUMP_HOP_GENERATION_TIMEOUT_MS,
 });

 type FlattenedJumpHopWorkProfileResponse = Omit<
@@ -104,6 +113,7 @@ function normalizeJumpHopWorkProfile(
    profileId: flattened.profileId,
    ownerUserId: flattened.ownerUserId,
    sourceSessionId: flattened.sourceSessionId ?? null,
+    themeText: flattened.themeText || flattened.workTitle,
    workTitle: flattened.workTitle,
    workDescription: flattened.workDescription,
    themeTags: flattened.themeTags,
@@ -122,9 +132,12 @@ function normalizeJumpHopWorkProfile(
    summary,
    draft: flattened.draft,
    path: flattened.path,
+    defaultCharacter: flattened.defaultCharacter ?? flattened.draft?.defaultCharacter,
    characterAsset: flattened.characterAsset,
    tileAtlasAsset: flattened.tileAtlasAsset,
    tileAssets: flattened.tileAssets,
+    backButtonAsset:
+      flattened.backButtonAsset ?? flattened.draft?.backButtonAsset ?? null,
  };
 }

@@ -240,9 +253,10 @@ export async function deleteJumpHopWork(profileId: string) {

 export async function startJumpHopRuntimeRun(
  profileId: string,
-  options: JumpHopRuntimeRequestOptions = {},
+  options: JumpHopStartRunOptions = {},
 ) {
  const requestOptions = buildRuntimeGuestAuthOptions(options);
+  const runtimeMode = options.runtimeMode ?? 'published';
  return requestJson<JumpHopRunResponse>(
    `${JUMP_HOP_RUNTIME_API_BASE}/runs`,
    {
@@ -251,7 +265,7 @@ export async function startJumpHopRuntimeRun(
        'content-type': 'application/json',
        ...buildRuntimeGuestHeaders(options),
      },
-      body: JSON.stringify({ profileId }),
+      body: JSON.stringify({ profileId, runtimeMode }),
    },
    '启动跳一跳运行态失败',
    {
@@ -262,12 +276,14 @@ export async function startJumpHopRuntimeRun(

 export async function submitJumpHopJump(
  runId: string,
-  payload: { chargeMs: number },
+  payload: JumpHopJumpPayload,
  options: JumpHopRuntimeRequestOptions = {},
 ) {
  const requestOptions = buildRuntimeGuestAuthOptions(options);
  const requestPayload = {
-    chargeMs: payload.chargeMs,
+    dragDistance: payload.dragDistance,
+    dragVectorX: payload.dragVectorX,
+    dragVectorY: payload.dragVectorY,
    clientEventId: `jump-${runId}-${Date.now()}`,
  };

@@ -286,6 +302,22 @@ export async function submitJumpHopJump(
  );
 }

+export async function getJumpHopLeaderboard(
+  profileId: string,
+  options: JumpHopRuntimeRequestOptions = {},
+) {
+  const requestOptions = buildRuntimeGuestAuthOptions(options);
+  return requestJson<JumpHopLeaderboardResponse>(
+    `${JUMP_HOP_RUNTIME_API_BASE}/works/${encodeURIComponent(profileId)}/leaderboard`,
+    {
+      method: 'GET',
+      headers: buildRuntimeGuestHeaders(options),
+    },
+    '读取跳一跳排行榜失败',
+    requestOptions,
+  );
+}
+
 export async function restartJumpHopRuntimeRun(
  runId: string,
  options: JumpHopRuntimeRequestOptions = {},
@@ -318,6 +350,7 @@ export const jumpHopClient = {
  listGallery: listJumpHopGallery,
  listWorks: listJumpHopWorks,
  publishWork: publishJumpHopWork,
+  getLeaderboard: getJumpHopLeaderboard,
  restartRun: restartJumpHopRuntimeRun,
  startRun: startJumpHopRuntimeRun,
  submitJump: submitJumpHopJump,
@@ -0,0 +1,498 @@
+import { expect, test } from 'vitest';
+
+import type {
+  JumpHopPath,
+  JumpHopTileAsset,
+} from '../../../packages/shared/src/contracts/jumpHop';
+import {
+  buildJumpHopVisiblePlatforms,
+  getJumpHopBackendDragVector,
+  getJumpHopCharacterVisualPosition,
+  getJumpHopJumpFeedbackLabel,
+  getJumpHopLandingAssistVisualPosition,
+  getJumpHopPlatformVisualSize,
+  getJumpHopStatusLabel,
+  resolveJumpHopCharacterCanvasPosition,
+  selectJumpHopTileAsset,
+} from './jumpHopRuntimeModel';
+
+test('跳一跳地块池按平台编号从 25 个素材中抽取而不是按类型压扁', () => {
+  const tileAssets = Array.from({ length: 25 }, (_, index) => ({
+    tileType: 'normal',
+    tileId: `tile-${String(index + 1).padStart(2, '0')}`,
+    imageSrc: `asset-${index + 1}`,
+    imageObjectKey: `key-${index + 1}`,
+    assetObjectId: `object-${index + 1}`,
+    sourceAtlasCell: `row-1-col-${index + 1}`,
+    atlasRow: 1,
+    atlasCol: index + 1,
+    visualWidth: 256,
+    visualHeight: 192,
+    topSurfaceRadius: 42,
+    landingRadius: 34,
+  })) satisfies JumpHopTileAsset[];
+
+  const first = selectJumpHopTileAsset(tileAssets, '森林茶馆', 1, 'platform-1');
+  const second = selectJumpHopTileAsset(tileAssets, '森林茶馆', 2, 'platform-2');
+
+  expect(first?.imageSrc).not.toBe(second?.imageSrc);
+  expect(first?.imageSrc).toMatch(/^asset-/);
+  expect(second?.imageSrc).toMatch(/^asset-/);
+});
+
+test('跳一跳可见平台窗口固定为 3 个并携带选中的地块素材', () => {
+  const path: JumpHopPath = {
+    seed: 'forest-tea',
+    difficulty: 'standard',
+    finishIndex: 999,
+    cameraPreset: 'portrait-isometric-9x16',
+    scoring: {
+      chargeToDistanceRatio: 0.004,
+      maxChargeMs: 900,
+      hitBonus: 20,
+      perfectBonus: 60,
+    },
+    platforms: [
+      platform(0, 0, 'start'),
+      platform(1.2, 1.8, 'normal'),
+      platform(-0.3, 3.5, 'target'),
+      platform(0.8, 5.1, 'normal'),
+    ],
+  };
+  const tileAssets = Array.from({ length: 25 }, (_, index) => ({
+    tileType: 'normal',
+    tileId: `tile-${String(index + 1).padStart(2, '0')}`,
+    imageSrc: `asset-${index + 1}`,
+    imageObjectKey: `key-${index + 1}`,
+    assetObjectId: `object-${index + 1}`,
+    sourceAtlasCell: `row-1-col-${index + 1}`,
+    visualWidth: 256,
+    visualHeight: 192,
+    topSurfaceRadius: 42,
+    landingRadius: 34,
+  })) satisfies JumpHopTileAsset[];
+
+  const visible = buildJumpHopVisiblePlatforms(path, 1, tileAssets);
+
+  expect(visible).toHaveLength(3);
+  expect(visible[0]?.asset?.imageSrc).toMatch(/^asset-/);
+  expect(visible[1]?.asset?.imageSrc).toMatch(/^asset-/);
+  expect(visible[2]?.asset?.imageSrc).toMatch(/^asset-/);
+});
+
+test('跳一跳三块可见地块按下方中部上方展开且角色落在当前地块上', () => {
+  const path: JumpHopPath = {
+    seed: 'forest-tea',
+    difficulty: 'standard',
+    finishIndex: 999,
+    cameraPreset: 'portrait-isometric-9x16',
+    scoring: {
+      chargeToDistanceRatio: 0.004,
+      maxChargeMs: 900,
+      hitBonus: 20,
+      perfectBonus: 60,
+    },
+    platforms: [
+      platform(0, 0, 'start'),
+      platform(0.8, 1.2, 'normal'),
+      platform(-0.2, 2.4, 'target'),
+    ],
+  };
+
+  const visible = buildJumpHopVisiblePlatforms(path, 0, []);
+  const character = getJumpHopCharacterVisualPosition(
+    {
+      runId: 'run-1',
+      profileId: 'profile-1',
+      ownerUserId: 'user-1',
+      status: 'playing',
+      currentPlatformIndex: 0,
+      successfulJumpCount: 0,
+      durationMs: 0,
+      score: 0,
+      combo: 0,
+      path,
+      lastJump: null,
+      startedAtMs: 1000,
+      finishedAtMs: null,
+    },
+    visible,
+  );
+
+  expect(visible[0]?.screenY).toBeGreaterThanOrEqual(68);
+  expect(visible[0]?.screenY).toBeLessThanOrEqual(80);
+  expect(visible[1]?.screenY).toBeGreaterThanOrEqual(40);
+  expect(visible[1]?.screenY).toBeLessThan(visible[0]?.screenY ?? 0);
+  expect(visible[2]?.screenY).toBeLessThan(visible[1]?.screenY ?? 0);
+  expect(visible[2]?.screenY).toBeLessThanOrEqual(26);
+  expect(Math.abs((visible[1]?.screenX ?? 0) - (visible[0]?.screenX ?? 0))).toBeGreaterThan(5);
+  expect(Math.abs((visible[2]?.screenX ?? 0) - (visible[1]?.screenX ?? 0))).toBeGreaterThan(5);
+  expect(character?.screenX).toBeCloseTo(visible[0]?.screenX ?? 0, 1);
+  expect(character?.screenY).toBeCloseTo((visible[0]?.screenY ?? 0) - 3, 1);
+});
+
+test('跳一跳可见地块按深度保留不同视觉尺寸', () => {
+  const path: JumpHopPath = {
+    seed: 'forest-tea',
+    difficulty: 'standard',
+    finishIndex: 999,
+    cameraPreset: 'portrait-isometric-9x16',
+    scoring: {
+      chargeToDistanceRatio: 0.004,
+      maxChargeMs: 900,
+      hitBonus: 20,
+      perfectBonus: 60,
+    },
+    platforms: [
+      platform(0, 0, 'start'),
+      platform(0.8, 1.2, 'normal'),
+      platform(-0.2, 2.4, 'target'),
+    ],
+  };
+
+  const visible = buildJumpHopVisiblePlatforms(path, 0, []);
+  const currentSize = getJumpHopPlatformVisualSize(
+    visible[0]!.platform,
+    visible[0]!.scale,
+  );
+  const targetSize = getJumpHopPlatformVisualSize(
+    visible[1]!.platform,
+    visible[1]!.scale,
+  );
+  const previewSize = getJumpHopPlatformVisualSize(
+    visible[2]!.platform,
+    visible[2]!.scale,
+  );
+
+  expect(currentSize.width).toBeGreaterThan(targetSize.width);
+  expect(targetSize.width).toBeGreaterThan(previewSize.width);
+  expect(currentSize.height).toBeGreaterThan(targetSize.height);
+  expect(targetSize.height).toBeGreaterThan(previewSize.height);
+});
+
+test('跳一跳三维角色画布坐标与屏幕坐标同向映射到下方起始地块', () => {
+  const path: JumpHopPath = {
+    seed: 'forest-tea',
+    difficulty: 'standard',
+    finishIndex: 999,
+    cameraPreset: 'portrait-isometric-9x16',
+    scoring: {
+      chargeToDistanceRatio: 0.004,
+      maxChargeMs: 900,
+      hitBonus: 20,
+      perfectBonus: 60,
+    },
+    platforms: [
+      platform(0, 0, 'start'),
+      platform(0.8, 1.2, 'normal'),
+      platform(-0.2, 2.4, 'target'),
+    ],
+  };
+
+  const visible = buildJumpHopVisiblePlatforms(path, 0, []);
+  const character = getJumpHopCharacterVisualPosition(
+    {
+      runId: 'run-1',
+      profileId: 'profile-1',
+      ownerUserId: 'user-1',
+      status: 'playing',
+      currentPlatformIndex: 0,
+      successfulJumpCount: 0,
+      durationMs: 0,
+      score: 0,
+      combo: 0,
+      path,
+      lastJump: null,
+      startedAtMs: 1000,
+      finishedAtMs: null,
+    },
+    visible,
+  );
+
+  const canvasPosition = resolveJumpHopCharacterCanvasPosition(character, {
+    width: 320,
+    height: 568,
+  });
+
+  expect(canvasPosition?.x).toBeGreaterThan(140);
+  expect(canvasPosition?.x).toBeLessThan(180);
+  expect(canvasPosition?.y).toBeGreaterThan(380);
+  expect(canvasPosition?.y).toBeLessThan(450);
+});
+
+test('跳一跳运行态当前地块视觉尺寸按原调参结果放大一倍', () => {
+  const size = getJumpHopPlatformVisualSize(platform(0, 0, 'start'), 1.08);
+
+  expect(size.width).toBeCloseTo(125.28, 2);
+  expect(size.height).toBeCloseTo(103.68, 2);
+});
+
+test('跳一跳落点辅助标识按后端落点规则随拖拽方向和距离投影', () => {
+  const path: JumpHopPath = {
+    seed: 'forest-tea',
+    difficulty: 'standard',
+    finishIndex: 999,
+    cameraPreset: 'portrait-isometric-9x16',
+    scoring: {
+      chargeToDistanceRatio: 0.004,
+      maxChargeMs: 900,
+      hitBonus: 20,
+      perfectBonus: 60,
+    },
+    platforms: [
+      platform(0, 0, 'start'),
+      platform(0.8, 1.2, 'normal'),
+      platform(-0.2, 2.4, 'target'),
+    ],
+  };
+  const run = {
+    runId: 'run-1',
+    profileId: 'profile-1',
+    ownerUserId: 'user-1',
+    status: 'playing',
+    currentPlatformIndex: 0,
+    successfulJumpCount: 0,
+    durationMs: 0,
+    score: 0,
+    combo: 0,
+    path,
+    lastJump: null,
+    startedAtMs: 1000,
+    finishedAtMs: null,
+  } as const;
+  const visible = buildJumpHopVisiblePlatforms(path, 0, []);
+  const character = getJumpHopCharacterVisualPosition(run, visible);
+  const current = visible[0]!;
+  const target = visible[1]!;
+  const stageSize = { width: 320, height: 568 };
+  const currentCanvasPosition = {
+    x: (current.screenX / 100) * stageSize.width,
+    y: (current.screenY / 100) * stageSize.height,
+  };
+  const targetCanvasPosition = {
+    x: (target.screenX / 100) * stageSize.width,
+    y: (target.screenY / 100) * stageSize.height,
+  };
+  const targetWorldDistance = Math.hypot(
+    target.platform.x - current.platform.x,
+    target.platform.y - current.platform.y,
+  );
+  const fullDragDistance =
+    targetWorldDistance / path.scoring.chargeToDistanceRatio;
+  const dragVectorX = -(targetCanvasPosition.x - currentCanvasPosition.x);
+  const dragVectorY = -(targetCanvasPosition.y - currentCanvasPosition.y);
+
+  const fullAssist = getJumpHopLandingAssistVisualPosition(
+    run,
+    visible,
+    character,
+    stageSize,
+    fullDragDistance,
+    dragVectorX,
+    dragVectorY,
+  );
+  const halfAssist = getJumpHopLandingAssistVisualPosition(
+    run,
+    visible,
+    character,
+    stageSize,
+    fullDragDistance / 2,
+    dragVectorX,
+    dragVectorY,
+  );
+
+  expect(fullAssist?.screenX).toBeCloseTo(target.screenX, 1);
+  expect(fullAssist?.screenY).toBeCloseTo(target.screenY, 1);
+  expect(halfAssist?.screenX).toBeCloseTo(
+    current.screenX + (target.screenX - current.screenX) / 2,
+    1,
+  );
+  expect(halfAssist?.screenY).toBeCloseTo(
+    current.screenY + (target.screenY - current.screenY) / 2,
+    1,
+  );
+});
+
+test('跳一跳落点辅助标识使用屏幕坐标向后拖拽并投向上方目标地块', () => {
+  const path: JumpHopPath = {
+    seed: 'forest-tea',
+    difficulty: 'standard',
+    finishIndex: 999,
+    cameraPreset: 'portrait-isometric-9x16',
+    scoring: {
+      chargeToDistanceRatio: 0.004,
+      maxChargeMs: 900,
+      hitBonus: 20,
+      perfectBonus: 60,
+    },
+    platforms: [
+      platform(0, 0, 'start'),
+      platform(0.8, 1.2, 'normal'),
+      platform(-0.2, 2.4, 'target'),
+    ],
+  };
+  const run = {
+    runId: 'run-1',
+    profileId: 'profile-1',
+    ownerUserId: 'user-1',
+    status: 'playing',
+    currentPlatformIndex: 0,
+    successfulJumpCount: 0,
+    durationMs: 0,
+    score: 0,
+    combo: 0,
+    path,
+    lastJump: null,
+    startedAtMs: 1000,
+    finishedAtMs: null,
+  } as const;
+  const visible = buildJumpHopVisiblePlatforms(path, 0, []);
+  const character = getJumpHopCharacterVisualPosition(run, visible);
+  const current = visible[0]!;
+  const target = visible[1]!;
+  const stageSize = { width: 320, height: 568 };
+  const currentCanvasPosition = {
+    x: (current.screenX / 100) * stageSize.width,
+    y: (current.screenY / 100) * stageSize.height,
+  };
+  const targetCanvasPosition = {
+    x: (target.screenX / 100) * stageSize.width,
+    y: (target.screenY / 100) * stageSize.height,
+  };
+  const dragVectorX = -(targetCanvasPosition.x - currentCanvasPosition.x);
+  const dragVectorY = currentCanvasPosition.y - targetCanvasPosition.y;
+  const targetWorldDistance = Math.hypot(
+    target.platform.x - current.platform.x,
+    target.platform.y - current.platform.y,
+  );
+  const fullDragDistance =
+    targetWorldDistance / path.scoring.chargeToDistanceRatio;
+
+  const assist = getJumpHopLandingAssistVisualPosition(
+    run,
+    visible,
+    character,
+    stageSize,
+    fullDragDistance,
+    dragVectorX,
+    dragVectorY,
+  );
+
+  expect(dragVectorY).toBeGreaterThan(0);
+  expect(assist?.screenX).toBeCloseTo(target.screenX, 1);
+  expect(assist?.screenY).toBeCloseTo(target.screenY, 1);
+});
+
+test('跳一跳后端落点向量会把屏幕拖拽换算为世界尺度一致的反向弹射', () => {
+  const path: JumpHopPath = {
+    seed: 'forest-tea',
+    difficulty: 'standard',
+    finishIndex: 999,
+    cameraPreset: 'portrait-isometric-9x16',
+    scoring: {
+      chargeToDistanceRatio: 0.004,
+      maxChargeMs: 900,
+      hitBonus: 20,
+      perfectBonus: 60,
+    },
+    platforms: [
+      platform(0, 0, 'start'),
+      platform(0.8, 1.2, 'normal'),
+      platform(-0.2, 2.4, 'target'),
+    ],
+  };
+  const run = {
+    runId: 'run-1',
+    profileId: 'profile-1',
+    ownerUserId: 'user-1',
+    status: 'playing',
+    currentPlatformIndex: 0,
+    successfulJumpCount: 0,
+    durationMs: 0,
+    score: 0,
+    combo: 0,
+    path,
+    lastJump: null,
+    startedAtMs: 1000,
+    finishedAtMs: null,
+  } as const;
+  const visible = buildJumpHopVisiblePlatforms(path, 0, []);
+  const current = visible[0]!;
+  const target = visible[1]!;
+  const stageSize = { width: 320, height: 568 };
+  const currentCanvasPosition = {
+    x: (current.screenX / 100) * stageSize.width,
+    y: (current.screenY / 100) * stageSize.height,
+  };
+  const targetCanvasPosition = {
+    x: (target.screenX / 100) * stageSize.width,
+    y: (target.screenY / 100) * stageSize.height,
+  };
+  const dragVectorX = -(targetCanvasPosition.x - currentCanvasPosition.x);
+  const dragVectorY = currentCanvasPosition.y - targetCanvasPosition.y;
+  const backendVector = getJumpHopBackendDragVector(
+    run,
+    visible,
+    stageSize,
+    dragVectorX,
+    dragVectorY,
+  );
+
+  expect(backendVector.dragVectorX).toBeLessThan(0);
+  expect(backendVector.dragVectorY).toBeGreaterThan(0);
+  expect(Math.abs(backendVector.dragVectorY)).toBeLessThan(Math.abs(dragVectorY));
+});
+
+test('跳一跳运行态公开反馈不再展示旧 perfect 和通关语义', () => {
+  expect(getJumpHopStatusLabel('cleared')).toBe('结束');
+  expect(
+    getJumpHopJumpFeedbackLabel({
+      runId: 'run-1',
+      profileId: 'profile-1',
+      ownerUserId: 'user-1',
+      status: 'playing',
+      currentPlatformIndex: 1,
+      successfulJumpCount: 1,
+      durationMs: 0,
+      score: 1,
+      combo: 0,
+      path: {
+        seed: 'forest-tea',
+        difficulty: 'standard',
+        finishIndex: 999,
+        cameraPreset: 'portrait-isometric-9x16',
+        scoring: {
+          chargeToDistanceRatio: 0.004,
+          maxChargeMs: 900,
+          hitBonus: 20,
+          perfectBonus: 60,
+        },
+        platforms: [platform(0, 0, 'start'), platform(1.2, 1.8, 'normal')],
+      },
+      lastJump: {
+        chargeMs: 300,
+        jumpDistance: 1.2,
+        targetPlatformIndex: 1,
+        landedX: 1.2,
+        landedY: 1.8,
+        result: 'perfect',
+      },
+      startedAtMs: 1000,
+      finishedAtMs: null,
+    }),
+  ).toBe('落地');
+});
+
+function platform(x: number, y: number, tileType: 'start' | 'normal' | 'target') {
+  return {
+    platformId: `platform-${x}-${y}`,
+    tileType,
+    x,
+    y,
+    width: 1,
+    height: 1,
+    landingRadius: 0.5,
+    perfectRadius: 0.2,
+    scoreValue: 1,
+  };
+}
@@ -0,0 +1,479 @@
+import type {
+  JumpHopPath,
+  JumpHopPlatform,
+  JumpHopRunStatus,
+  JumpHopRuntimeRunSnapshotResponse,
+  JumpHopTileAsset,
+  JumpHopTileType,
+} from '../../../packages/shared/src/contracts/jumpHop';
+
+export type JumpHopVisiblePlatform = {
+  platform: JumpHopPlatform;
+  index: number;
+  screenX: number;
+  screenY: number;
+  sceneX: number;
+  sceneY: number;
+  sceneZ: number;
+  scale: number;
+  asset: JumpHopTileAsset | null;
+};
+
+export type JumpHopCharacterVisualPosition = {
+  screenX: number;
+  screenY: number;
+  sceneX: number;
+  sceneY: number;
+  sceneZ: number;
+  isMiss: boolean;
+};
+
+export type JumpHopCanvasSize = {
+  width: number;
+  height: number;
+};
+
+export type JumpHopPlatformVisualSize = {
+  width: number;
+  height: number;
+};
+
+export type JumpHopLandingAssistVisualPosition = {
+  screenX: number;
+  screenY: number;
+  targetPlatformIndex: number;
+};
+
+export type JumpHopBackendDragVector = {
+  dragVectorX: number;
+  dragVectorY: number;
+};
+
+const VISIBLE_PLATFORM_COUNT = 3;
+const JUMP_HOP_STAGE_WORLD_SCALE = 4.2;
+const JUMP_HOP_STAGE_FORWARD_SCALE = 3;
+const JUMP_HOP_VISIBLE_PLATFORM_SCREEN_Y = [78, 50, 22] as const;
+const JUMP_HOP_PLATFORM_VISUAL_SIZE_MULTIPLIER = 2;
+const JUMP_HOP_SCREEN_X_WORLD_PERCENT = 16 * 0.96;
+
+const tileToneByType: Record<JumpHopTileType, string> = {
+  accent: '#e0f2fe',
+  bonus: '#fef3c7',
+  finish: '#dcfce7',
+  normal: '#f8fafc',
+  start: '#e0f2fe',
+  target: '#fee2e2',
+};
+
+function clamp(value: number, min: number, max: number) {
+  return Math.min(max, Math.max(min, value));
+}
+
+function hashJumpHopString(value: string) {
+  let hash = 0x811c9dc5;
+  for (const character of value) {
+    hash ^= character.codePointAt(0) ?? 0;
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return hash >>> 0;
+}
+
+export function selectJumpHopTileAsset(
+  tileAssets: JumpHopTileAsset[] | null | undefined,
+  seedText: string | null | undefined,
+  platformIndex: number,
+  platformId: string,
+) {
+  const pool = (tileAssets ?? []).filter(Boolean);
+  if (pool.length === 0) {
+    return null;
+  }
+
+  const normalizedSeed = seedText?.trim() || 'jump-hop';
+  const signature = `${normalizedSeed}:${platformIndex}:${platformId}`;
+  const selectedIndex = hashJumpHopString(signature) % pool.length;
+  return pool[selectedIndex] ?? null;
+}
+
+export function buildJumpHopVisiblePlatforms(
+  path: JumpHopPath | null | undefined,
+  currentPlatformIndex: number,
+  tileAssets: JumpHopTileAsset[] | null | undefined,
+) {
+  const platforms = path?.platforms ?? [];
+  const current = platforms[currentPlatformIndex] ?? platforms[0];
+  if (!current) {
+    return [];
+  }
+
+  const start = Math.max(0, currentPlatformIndex);
+  const end = Math.min(platforms.length, currentPlatformIndex + VISIBLE_PLATFORM_COUNT);
+  const visible = platforms.slice(start, end);
+  const worldScale = 0.96;
+
+  return visible.map((platform, offset): JumpHopVisiblePlatform => {
+    const index = start + offset;
+    const dx = platform.x - current.x;
+    const dy = platform.y - current.y;
+    const depth = index - currentPlatformIndex;
+    const asset = selectJumpHopTileAsset(
+      tileAssets,
+      path?.seed ?? null,
+      index,
+      platform.platformId,
+    );
+    const screenY =
+      depth <= 0
+        ? JUMP_HOP_VISIBLE_PLATFORM_SCREEN_Y[0]
+        : depth === 1
+          ? JUMP_HOP_VISIBLE_PLATFORM_SCREEN_Y[1]
+          : JUMP_HOP_VISIBLE_PLATFORM_SCREEN_Y[2];
+    const screenX = clamp(50 + dx * 16 * worldScale, 14, 86);
+
+    return {
+      platform,
+      index,
+      screenX,
+      screenY,
+      sceneX: dx * JUMP_HOP_STAGE_WORLD_SCALE,
+      sceneY: 0,
+      sceneZ: dy * JUMP_HOP_STAGE_FORWARD_SCALE,
+      scale: clamp(1.08 - Math.max(0, depth) * 0.12, 0.8, 1.1),
+      asset,
+    };
+  });
+}
+
+export function getJumpHopPlatformVisualSize(
+  platform: JumpHopPlatform,
+  scale: number,
+): JumpHopPlatformVisualSize {
+  return {
+    width:
+      clamp(platform.width * 0.96, 58, 118) *
+      scale *
+      JUMP_HOP_PLATFORM_VISUAL_SIZE_MULTIPLIER,
+    height:
+      clamp(platform.height * 0.78, 48, 92) *
+      scale *
+      JUMP_HOP_PLATFORM_VISUAL_SIZE_MULTIPLIER,
+  };
+}
+
+function getJumpHopCurrentTargetPlatforms(
+  run: JumpHopRuntimeRunSnapshotResponse | null,
+  platforms: JumpHopVisiblePlatform[],
+) {
+  if (!run) {
+    return null;
+  }
+
+  const currentIndex = run.currentPlatformIndex;
+  const currentPlatform =
+    platforms.find((item) => item.index === currentIndex) ??
+    platforms[0] ??
+    null;
+  const targetPlatform =
+    platforms.find((item) => item.index === currentIndex + 1) ??
+    platforms[1] ??
+    null;
+
+  if (!currentPlatform || !targetPlatform) {
+    return null;
+  }
+
+  return {
+    currentPlatform,
+    targetPlatform,
+  };
+}
+
+function getJumpHopCanvasPosition(
+  platform: JumpHopVisiblePlatform,
+  stageSize: JumpHopCanvasSize,
+) {
+  return {
+    x: (platform.screenX / 100) * stageSize.width,
+    y: (platform.screenY / 100) * stageSize.height,
+  };
+}
+
+function getJumpHopScreenWorldScales(
+  currentPlatform: JumpHopVisiblePlatform,
+  targetPlatform: JumpHopVisiblePlatform,
+  stageSize: JumpHopCanvasSize,
+) {
+  const currentCanvasPosition = getJumpHopCanvasPosition(
+    currentPlatform,
+    stageSize,
+  );
+  const targetCanvasPosition = getJumpHopCanvasPosition(
+    targetPlatform,
+    stageSize,
+  );
+  const targetWorldDeltaX =
+    targetPlatform.platform.x - currentPlatform.platform.x;
+  const targetWorldDeltaY =
+    targetPlatform.platform.y - currentPlatform.platform.y;
+  const targetScreenDeltaX = targetCanvasPosition.x - currentCanvasPosition.x;
+  const targetScreenDeltaY = targetCanvasPosition.y - currentCanvasPosition.y;
+  const targetWorldDistance = Math.hypot(targetWorldDeltaX, targetWorldDeltaY);
+  const targetScreenDistance = Math.hypot(
+    targetScreenDeltaX,
+    targetScreenDeltaY,
+  );
+  const fallbackPixelsPerWorldUnit =
+    targetWorldDistance > 0.0001 && targetScreenDistance > 0.0001
+      ? targetScreenDistance / targetWorldDistance
+      : stageSize.height * 0.18;
+  const xPixelsPerWorldUnit =
+    Math.abs(targetWorldDeltaX) > 0.0001 &&
+    Math.abs(targetScreenDeltaX) > 0.0001
+      ? Math.abs(targetScreenDeltaX / targetWorldDeltaX)
+      : Math.max(stageSize.width * (JUMP_HOP_SCREEN_X_WORLD_PERCENT / 100), 1);
+  const yPixelsPerWorldUnit =
+    Math.abs(targetWorldDeltaY) > 0.0001 &&
+    Math.abs(targetScreenDeltaY) > 0.0001
+      ? Math.abs(targetScreenDeltaY / targetWorldDeltaY)
+      : fallbackPixelsPerWorldUnit;
+  const signedXScreenPerWorld =
+    Math.abs(targetWorldDeltaX) > 0.0001 &&
+    Math.abs(targetScreenDeltaX) > 0.0001
+      ? targetScreenDeltaX / targetWorldDeltaX
+      : xPixelsPerWorldUnit;
+  const signedYScreenPerWorld =
+    Math.abs(targetWorldDeltaY) > 0.0001 &&
+    Math.abs(targetScreenDeltaY) > 0.0001
+      ? targetScreenDeltaY / targetWorldDeltaY
+      : -yPixelsPerWorldUnit;
+
+  return {
+    currentCanvasPosition,
+    targetPlatform,
+    xPixelsPerWorldUnit,
+    yPixelsPerWorldUnit: Math.max(yPixelsPerWorldUnit, 1),
+    signedXScreenPerWorld,
+    signedYScreenPerWorld,
+  };
+}
+
+export function getJumpHopBackendDragVector(
+  run: JumpHopRuntimeRunSnapshotResponse | null,
+  platforms: JumpHopVisiblePlatform[],
+  stageSize: JumpHopCanvasSize,
+  dragVectorX: number,
+  dragVectorY: number,
+): JumpHopBackendDragVector {
+  const pair = getJumpHopCurrentTargetPlatforms(run, platforms);
+  if (!pair || stageSize.width <= 0 || stageSize.height <= 0) {
+    return {
+      dragVectorX,
+      dragVectorY,
+    };
+  }
+
+  const scales = getJumpHopScreenWorldScales(
+    pair.currentPlatform,
+    pair.targetPlatform,
+    stageSize,
+  );
+
+  return {
+    dragVectorX: dragVectorX / scales.xPixelsPerWorldUnit,
+    dragVectorY: dragVectorY / scales.yPixelsPerWorldUnit,
+  };
+}
+
+export function getJumpHopLandingAssistVisualPosition(
+  run: JumpHopRuntimeRunSnapshotResponse | null,
+  platforms: JumpHopVisiblePlatform[],
+  characterPosition: JumpHopCharacterVisualPosition | null,
+  stageSize: JumpHopCanvasSize,
+  dragDistance: number,
+  dragVectorX: number | null,
+  dragVectorY: number | null,
+) {
+  if (
+    !run ||
+    run.status !== 'playing' ||
+    !characterPosition ||
+    stageSize.width <= 0 ||
+    stageSize.height <= 0 ||
+    dragDistance <= 0
+  ) {
+    return null;
+  }
+
+  const pair = getJumpHopCurrentTargetPlatforms(run, platforms);
+  if (!pair) {
+    return null;
+  }
+  const { currentPlatform, targetPlatform } = pair;
+
+  const dragX = dragVectorX ?? 0;
+  const dragY = dragVectorY ?? 0;
+  const dragLength = Math.hypot(dragX, dragY);
+  if (dragLength < 0.0001) {
+    return null;
+  }
+
+  const scales = getJumpHopScreenWorldScales(
+    currentPlatform,
+    targetPlatform,
+    stageSize,
+  );
+  const backendDragVector = getJumpHopBackendDragVector(
+    run,
+    platforms,
+    stageSize,
+    dragX,
+    dragY,
+  );
+  const jumpWorldX = -backendDragVector.dragVectorX;
+  const jumpWorldY = backendDragVector.dragVectorY;
+  const jumpWorldLength = Math.hypot(jumpWorldX, jumpWorldY);
+  if (jumpWorldLength < 0.0001) {
+    return null;
+  }
+
+  const maxDragDistance =
+    run.path.scoring.maxChargeMs > 0 ? run.path.scoring.maxChargeMs : 180;
+  const chargeToDistanceRatio =
+    run.path.scoring.chargeToDistanceRatio > 0
+      ? run.path.scoring.chargeToDistanceRatio
+      : 0.008;
+  const projectedWorldDistance =
+    clamp(dragDistance, 0, maxDragDistance) * chargeToDistanceRatio;
+  const landedWorldDeltaX =
+    (jumpWorldX / jumpWorldLength) * projectedWorldDistance;
+  const landedWorldDeltaY =
+    (jumpWorldY / jumpWorldLength) * projectedWorldDistance;
+  const landedPixelX =
+    scales.currentCanvasPosition.x +
+    landedWorldDeltaX * scales.signedXScreenPerWorld;
+  const landedPixelY =
+    scales.currentCanvasPosition.y +
+    landedWorldDeltaY * scales.signedYScreenPerWorld;
+
+  return {
+    screenX: clamp((landedPixelX / stageSize.width) * 100, 6, 94),
+    screenY: clamp((landedPixelY / stageSize.height) * 100, 10, 92),
+    targetPlatformIndex: targetPlatform.index,
+  };
+}
+
+export function resolveJumpHopCharacterCanvasPosition(
+  characterPosition: JumpHopCharacterVisualPosition | null,
+  size: JumpHopCanvasSize,
+) {
+  if (!characterPosition) {
+    return null;
+  }
+
+  return {
+    x: (characterPosition.screenX / 100) * size.width,
+    y: (characterPosition.screenY / 100) * size.height,
+  };
+}
+
+export function getJumpHopCharacterVisualPosition(
+  run: JumpHopRuntimeRunSnapshotResponse | null,
+  platforms: JumpHopVisiblePlatform[],
+) {
+  if (!run) {
+    return null;
+  }
+
+  const landedPlatform = platforms.find(
+    (item) => item.index === run.currentPlatformIndex,
+  );
+  if (landedPlatform) {
+    return {
+      screenX: landedPlatform.screenX,
+      screenY: landedPlatform.screenY - 3,
+      sceneX: landedPlatform.sceneX,
+      sceneY: landedPlatform.sceneY + 0.84,
+      sceneZ: landedPlatform.sceneZ,
+      isMiss: false,
+    };
+  }
+
+  const lastJump = run.lastJump;
+  if (lastJump && run.status === 'failed') {
+    const targetPlatform = platforms.find(
+      (item) => item.index === lastJump.targetPlatformIndex,
+    );
+    if (targetPlatform) {
+      return {
+        screenX: targetPlatform.screenX + 8,
+        screenY: targetPlatform.screenY - 2,
+        sceneX: targetPlatform.sceneX + 0.7,
+        sceneY: targetPlatform.sceneY + 0.48,
+        sceneZ: targetPlatform.sceneZ - 0.4,
+        isMiss: true,
+      };
+    }
+  }
+
+  return null;
+}
+
+export function getJumpHopRunDurationMs(
+  run: JumpHopRuntimeRunSnapshotResponse | null,
+  nowMs: number,
+) {
+  if (!run) {
+    return 0;
+  }
+
+  if (run.status === 'playing' && run.startedAtMs > 0) {
+    return Math.max(0, nowMs - run.startedAtMs);
+  }
+
+  return run.durationMs;
+}
+
+export function formatJumpHopDurationLabel(durationMs: number) {
+  const safeDuration = Math.max(0, Math.floor(durationMs));
+  const totalSeconds = Math.floor(safeDuration / 1000);
+  const minutes = Math.floor(totalSeconds / 60)
+    .toString()
+    .padStart(2, '0');
+  const seconds = (totalSeconds % 60).toString().padStart(2, '0');
+  return `${minutes}:${seconds}`;
+}
+
+export function getJumpHopStatusLabel(
+  status: JumpHopRunStatus | undefined,
+) {
+  if (status === 'cleared') {
+    return '结束';
+  }
+  if (status === 'failed') {
+    return '失败';
+  }
+  return '进行中';
+}
+
+export function getJumpHopJumpFeedbackLabel(
+  run: JumpHopRuntimeRunSnapshotResponse | null,
+) {
+  const result = run?.lastJump?.result;
+  if (result === 'perfect') {
+    return '落地';
+  }
+  if (result === 'finish') {
+    return '落地';
+  }
+  if (result === 'hit') {
+    return '落地';
+  }
+  if (result === 'miss') {
+    return '落空';
+  }
+  return null;
+}
+
+export function getJumpHopTileTone(tileType: JumpHopTileType) {
+  return tileToneByType[tileType];
+}
@@ -0,0 +1,86 @@
+/* @vitest-environment jsdom */
+
+import { renderHook, waitFor } from '@testing-library/react';
+import { beforeEach, expect, test, vi } from 'vitest';
+
+import {
+  getStoredAccessToken,
+  setStoredAccessToken,
+} from '../apiClient';
+import { ensureRuntimeGuestToken } from '../authService';
+import {
+  jumpHopClient,
+  type JumpHopLeaderboardResponse,
+} from './jumpHopClient';
+import { useJumpHopLeaderboard } from './useJumpHopLeaderboard';
+
+vi.mock('../authService', () => ({
+  ensureRuntimeGuestToken: vi.fn(),
+}));
+
+vi.mock('./jumpHopClient', () => ({
+  jumpHopClient: {
+    getLeaderboard: vi.fn(),
+  },
+}));
+
+const leaderboardResponse: JumpHopLeaderboardResponse = {
+  profileId: 'jump-hop-profile-test',
+  items: [
+    {
+      rank: 1,
+      playerId: 'player-1',
+      successfulJumpCount: 10,
+      durationMs: 3210,
+      updatedAt: '2026-05-27T00:00:00Z',
+    },
+  ],
+  viewerBest: null,
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  setStoredAccessToken('', { emit: false });
+  vi.mocked(ensureRuntimeGuestToken).mockResolvedValue({
+    token: 'runtime-guest-token',
+    expiresAt: '2099-01-01T00:10:00Z',
+    subject: 'guest-runtime-test',
+    scope: 'public-play',
+  });
+  vi.mocked(jumpHopClient.getLeaderboard).mockResolvedValue(
+    leaderboardResponse,
+  );
+});
+
+test('跳一跳排行榜在已有登录态时使用本地账号请求，不再额外申请 guest token', async () => {
+  setStoredAccessToken('stored-access-token', { emit: false });
+
+  const { result } = renderHook(() =>
+    useJumpHopLeaderboard('jump-hop-profile-test'),
+  );
+
+  await waitFor(() => expect(result.current.isLoading).toBe(false));
+  expect(getStoredAccessToken()).toBe('stored-access-token');
+  expect(ensureRuntimeGuestToken).not.toHaveBeenCalled();
+  expect(jumpHopClient.getLeaderboard).toHaveBeenCalledWith(
+    'jump-hop-profile-test',
+    expect.objectContaining({
+      authImpact: 'local',
+      skipRefresh: true,
+    }),
+  );
+  expect(result.current.leaderboard).toEqual(leaderboardResponse);
+});
+test('跳一跳排行榜在匿名模式下会申请 guest token', async () => {
+  const { result } = renderHook(() =>
+    useJumpHopLeaderboard('jump-hop-profile-test'),
+  );
+
+  await waitFor(() => expect(result.current.isLoading).toBe(false));
+  expect(ensureRuntimeGuestToken).toHaveBeenCalledTimes(1);
+  expect(jumpHopClient.getLeaderboard).toHaveBeenCalledWith(
+    'jump-hop-profile-test',
+    { runtimeGuestToken: 'runtime-guest-token' },
+  );
+  expect(result.current.leaderboard).toEqual(leaderboardResponse);
+});
@@ -0,0 +1,85 @@
+import { useEffect, useMemo, useState } from 'react';
+
+import {
+  BACKGROUND_AUTH_REQUEST_OPTIONS,
+  getStoredAccessToken,
+} from '../apiClient';
+import { ensureRuntimeGuestToken } from '../authService';
+import {
+  jumpHopClient,
+  type JumpHopLeaderboardResponse,
+  type JumpHopRuntimeRequestOptions,
+} from './jumpHopClient';
+
+type JumpHopLeaderboardState = {
+  leaderboard: JumpHopLeaderboardResponse | null;
+  isLoading: boolean;
+  error: string | null;
+  refresh: () => Promise<void>;
+};
+
+export function useJumpHopLeaderboard(
+  profileId: string | null | undefined,
+  runtimeRequestOptions?: JumpHopRuntimeRequestOptions,
+): JumpHopLeaderboardState {
+  const normalizedProfileId = profileId?.trim() ?? '';
+  const [leaderboard, setLeaderboard] =
+    useState<JumpHopLeaderboardResponse | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const refresh = useMemo(
+    () => async () => {
+      if (!normalizedProfileId) {
+        setLeaderboard(null);
+        setError(null);
+        setIsLoading(false);
+        return;
+      }
+
+      setIsLoading(true);
+      setError(null);
+      try {
+        if (runtimeRequestOptions) {
+          const response = await jumpHopClient.getLeaderboard(
+            normalizedProfileId,
+            runtimeRequestOptions,
+          );
+          setLeaderboard(response);
+          return;
+        }
+
+        if (getStoredAccessToken()) {
+          const response = await jumpHopClient.getLeaderboard(
+            normalizedProfileId,
+            BACKGROUND_AUTH_REQUEST_OPTIONS,
+          );
+          setLeaderboard(response);
+          return;
+        }
+
+        const runtimeGuest = await ensureRuntimeGuestToken();
+        const response = await jumpHopClient.getLeaderboard(
+          normalizedProfileId,
+          { runtimeGuestToken: runtimeGuest.token },
+        );
+        setLeaderboard(response);
+      } catch (caughtError) {
+        setError(
+          caughtError instanceof Error
+            ? caughtError.message
+            : '读取排行榜失败。',
+        );
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [normalizedProfileId, runtimeRequestOptions],
+  );
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  return { leaderboard, isLoading, error, refresh };
+}
@@ -489,7 +489,7 @@ describe('miniGameDraftGenerationProgress', () => {
    ]);
  });

-  test('jump hop draft generation exposes character and tile atlas pipeline', () => {
+  test('jump hop draft generation exposes theme and tile atlas pipeline', () => {
    const state = createMiniGameDraftGenerationState('jump-hop');

    const progress = buildMiniGameDraftGenerationProgress(
@@ -499,23 +499,20 @@ describe('miniGameDraftGenerationProgress', () => {

    expect(progress?.steps.map((step) => step.id)).toEqual([
      'jump-hop-draft',
-      'jump-hop-character',
      'jump-hop-tile-atlas',
      'jump-hop-slice-tiles',
      'jump-hop-write-draft',
    ]);
-    expect(progress?.phaseId).toBe('jump-hop-character');
-    expect(progress?.phaseLabel).toBe('生成角色形象');
+    expect(progress?.phaseId).toBe('jump-hop-tile-atlas');
+    expect(progress?.phaseLabel).toBe('生成 5x5 地块图集');
    expect(progress?.estimatedRemainingMs).toBe(265_000);
  });

-  test('jump hop generation anchors expose theme, character and tile style', () => {
+  test('jump hop generation anchors expose theme and tile atlas', () => {
    const entries = buildJumpHopGenerationAnchorEntries(null, {
      themeText: '云端糖果塔',
-      characterDescription: '披着星星披风的小旅人',
-      tileStyle: '纸模玩具',
-      difficulty: '标准',
-      rhythmPreference: '轻快',
+      templateId: 'jump-hop',
+      tilePrompt: '云端糖果塔主题的正面30度视角主题物体图集，物体本身作为跳跃落点',
    });

    expect(entries).toEqual([
@@ -524,15 +521,10 @@ describe('miniGameDraftGenerationProgress', () => {
        label: '主题',
        value: '云端糖果塔',
      },
-      {
-        id: 'jump-hop-character',
-        label: '角色',
-        value: '披着星星披风的小旅人',
-      },
      {
        id: 'jump-hop-tile-style',
-        label: '地块',
-        value: '纸模玩具',
+        label: '地块图集',
+        value: '云端糖果塔主题的正面30度视角主题物体图集，物体本身作为跳跃落点',
      },
    ]);
  });
@@ -63,7 +63,6 @@ export type MiniGameDraftGenerationPhase =
  | 'baby-object-images'
  | 'baby-object-ready'
  | 'jump-hop-draft'
-  | 'jump-hop-character'
  | 'jump-hop-tile-atlas'
  | 'jump-hop-slice-tiles'
  | 'jump-hop-write-draft'
@@ -394,32 +393,26 @@ const JUMP_HOP_STEPS = [
  {
    id: 'jump-hop-draft',
    label: '整理玩法草稿',
-    detail: '建立主题、难度和路径基础数据。',
-    weight: 10,
-  },
-  {
-    id: 'jump-hop-character',
-    label: '生成角色形象',
-    detail: '生成可进入运行态的俯视角角色图。',
-    weight: 34,
+    detail: '保存主题并派生作品信息和默认角色配置。',
+    weight: 12,
  },
  {
    id: 'jump-hop-tile-atlas',
-    label: '生成地块图集',
-    detail: '生成起点、普通、目标和终点地块图集。',
-    weight: 34,
+    label: '生成 5x5 地块图集',
+    detail: '调用 image2 生成 25 个主题地块素材。',
+    weight: 54,
  },
  {
    id: 'jump-hop-slice-tiles',
-    label: '切分地块素材',
-    detail: '切分透明地块 PNG 并校验落点半径。',
-    weight: 14,
+    label: '切分 25 个地块',
+    detail: '按 5 行 5 列切分透明地块 PNG。',
+    weight: 24,
  },
  {
    id: 'jump-hop-write-draft',
    label: '写入正式草稿',
-    detail: '保存角色、地块、路径和封面合成结果。',
-    weight: 8,
+    detail: '保存地块池、无限路径缓冲和运行态配置。',
+    weight: 10,
  },
 ] as const satisfies ReadonlyArray<MiniGameStepDefinition>;

@@ -659,7 +652,7 @@ function resolveJumpHopPhaseByElapsedMs(
    return 'jump-hop-tile-atlas';
  }
  if (elapsedMs >= 12_000) {
-    return 'jump-hop-character';
+    return 'jump-hop-tile-atlas';
  }
  return 'jump-hop-draft';
 }
@@ -1099,21 +1092,12 @@ export function buildJumpHopGenerationAnchorEntries(
        draft?.workTitle?.trim() ||
        '',
    },
-    {
-      key: 'jump-hop-character',
-      label: '角色',
-      value:
-        formPayload?.characterDescription?.trim() ||
-        config?.characterDescription?.trim() ||
-        draft?.characterPrompt?.trim() ||
-        '',
-    },
    {
      key: 'jump-hop-tile-style',
-      label: '地块',
+      label: '地块图集',
      value:
-        formPayload?.tileStyle?.trim() ||
-        config?.tileStyle?.trim() ||
+        formPayload?.tilePrompt?.trim() ||
+        config?.tilePrompt?.trim() ||
        draft?.stylePreset?.trim() ||
        '',
    },