From 96df12cd1536daca6979ab2a603b30eb2d734f70 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=AB=98=E7=89=A9?= <253518756@qq.com>
Date: Fri, 8 May 2026 22:07:08 +0800
Subject: [PATCH] 1

---
 ..._DISCOVER_DRAFT_TAB_REDESIGN_2026-05-05.md |  3 ++
 ...ADER_AND_CLEAR_EFFECT_DESIGN_2026-04-27.md |  6 ++++
 .../PuzzleRuntimeShell.test.tsx               | 28 +++++++++++++++++++
 .../puzzle-runtime/PuzzleRuntimeShell.tsx     |  9 ++++--
 4 files changed, 43 insertions(+), 3 deletions(-)

diff --git a/docs/design/PLATFORM_MOBILE_RECOMMEND_DISCOVER_DRAFT_TAB_REDESIGN_2026-05-05.md b/docs/design/PLATFORM_MOBILE_RECOMMEND_DISCOVER_DRAFT_TAB_REDESIGN_2026-05-05.md
index bc63c74e..61da363f 100644
--- a/docs/design/PLATFORM_MOBILE_RECOMMEND_DISCOVER_DRAFT_TAB_REDESIGN_2026-05-05.md
+++ b/docs/design/PLATFORM_MOBILE_RECOMMEND_DISCOVER_DRAFT_TAB_REDESIGN_2026-05-05.md
@@ -37,6 +37,7 @@
 - 用户停留在推荐页时，底部当前 Tab 从“推荐”切换为“下一个”，图标使用向下的倒三角 / 双下箭头语义，点击后切换下一个推荐作品。
 - 推荐页不再展示额外的底部作品切换块；当前作品的完整操作继续收敛在详情页和作品自身运行态中。
 - 推荐页嵌入运行只调整平台外壳容器、主题注入和玩法壳层配色，不改写作品数据、关卡设定、道具设定或图片资产。
+- 推荐页嵌入拼图玩法时隐藏拼图左上返回按钮，并在设置弹层中隐藏退出入口；作品切换前对当前拼图 run 执行既有“保存并退出”收口，正式 run 的交互状态以已写回后端的快照为准。
 - 点赞、改造、复制作品号等完整操作继续收敛在详情页，详情入口由作品自身运行态或其它广场列表承接，推荐页作品信息区只负责展示和上下滑切换。
 - 无数据、加载中、启动失败和暂不支持内嵌运行的作品沿用短状态文案。
 
@@ -87,6 +88,8 @@
 8. 推荐页不出现额外底部作品卡或横滑切换块，运行视口、加载态和错误态跟随当前明暗主题。
 9. 拼图玩法背景、HUD、按钮、弹窗、排行榜和相似作品卡跟随平台主题色；暗色主题仍保留深色游戏感，亮色主题不得出现大面积固定黑底。
 10. 推荐页作品信息区点击无效，上滑切下一个、下滑切上一个；点击底部“下一个”也切下一个作品。
+11. 仅推荐页嵌入拼图态隐藏返回与设置内退出入口；详情页、新手引导和普通拼图运行态继续保留原有退出能力。
+12. 推荐页切换作品前，如果当前作品是拼图，必须先执行当前拼图 run 的退出收口，再启动下一作品。
 
 ## 8. 2026-05-07 未登录三栏补充
 
diff --git a/docs/design/PUZZLE_RUNTIME_HEADER_AND_CLEAR_EFFECT_DESIGN_2026-04-27.md b/docs/design/PUZZLE_RUNTIME_HEADER_AND_CLEAR_EFFECT_DESIGN_2026-04-27.md
index 53b34e35..ef2fb54e 100644
--- a/docs/design/PUZZLE_RUNTIME_HEADER_AND_CLEAR_EFFECT_DESIGN_2026-04-27.md
+++ b/docs/design/PUZZLE_RUNTIME_HEADER_AND_CLEAR_EFFECT_DESIGN_2026-04-27.md
@@ -51,6 +51,12 @@
 3. `platform-theme--dark` 下可保留深色棋盘氛围，但按钮、选中态、倒计时、弹窗边框和推荐页加载态仍要从主题 token 取色，避免局部色板漂移。
 4. 推荐页内嵌拼图时，父级必须保持 `platform-theme` 类可传递到 `PuzzleRuntimeShell`，不能让 runtime 脱离平台主题变量。
 
+### 1.4 2026-05-08 推荐页嵌入态退出控制
+
+1. 推荐页嵌入拼图时需要单独隐藏左上返回按钮和设置面板里的退出入口，避免把推荐流里的作品切换与普通退出混在一起。
+2. 推荐页切换到下一作品前，平台外壳会先沿用现有“保存并退出”语义收口当前拼图 run，再进入新作品。
+3. 该隐藏规则只作用于推荐页嵌入态，不影响详情页、新手引导或普通拼图入口。
+
 ### 2. 拼图块显示规则
 
 运行时单块右下角编号全部移除。
diff --git a/src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx b/src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx
index fa2a546f..8635e822 100644
--- a/src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx
+++ b/src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx
@@ -446,6 +446,34 @@ test('右上角设置按钮打开拼图设置并支持音量调节', () => {
   expect(authValue.setMusicVolume).toHaveBeenCalledWith(0.77);
 });
 
+test('推荐页嵌入拼图时隐藏返回和设置里的退出入口', () => {
+  renderPuzzleRuntime(
+    <PuzzleRuntimeShell
+      run={clearedRun}
+      embedded
+      hideExitControls
+      onBack={vi.fn()}
+      onRemodelWork={vi.fn()}
+      onSwapPieces={vi.fn()}
+      onDragPiece={vi.fn()}
+      onAdvanceNextLevel={vi.fn()}
+    />,
+  );
+
+  const backButton = screen.getByRole('button', { name: '返回上一页' });
+  expect((backButton as HTMLButtonElement).disabled).toBe(true);
+  expect(backButton.className).toContain('invisible');
+
+  fireEvent.click(screen.getByRole('button', { name: '打开拼图设置' }));
+
+  const dialog = screen.getByRole('dialog', { name: '拼图设置' });
+  expect(within(dialog).getByRole('button', { name: '继续拼图' })).toBeTruthy();
+  expect(
+    within(dialog).queryByRole('button', { name: '返回上一页' }),
+  ).toBeNull();
+  expect(within(dialog).queryByText('保存并退出')).toBeNull();
+});
+
 test('拼图棋盘使用贴近移动端边缘的正方形舞台承载切块', () => {
   const { container } = renderPuzzleRuntime(
     <PuzzleRuntimeShell
diff --git a/src/components/puzzle-runtime/PuzzleRuntimeShell.tsx b/src/components/puzzle-runtime/PuzzleRuntimeShell.tsx
index 74c2f038..00534b00 100644
--- a/src/components/puzzle-runtime/PuzzleRuntimeShell.tsx
+++ b/src/components/puzzle-runtime/PuzzleRuntimeShell.tsx
@@ -962,6 +962,7 @@ export function PuzzleRuntimeShell({
     canAdvanceDefaultNextLevel || hasSimilarWorkChoices;
   const levelLabel = `第 ${currentLevel.levelIndex} 关`;
   const exitPromptProfileId = currentLevel.profileId.trim();
+  const shouldHideBackButton = hideBackButton || hideExitControls;
   const leaderboardEntries =
     (currentLevel.leaderboardEntries ?? []).length > 0
       ? currentLevel.leaderboardEntries
@@ -1105,9 +1106,11 @@ export function PuzzleRuntimeShell({
               type="button"
               onClick={handleBackRequest}
               aria-label="返回上一页"
-              disabled={hideBackButton}
+              disabled={shouldHideBackButton}
               className={`puzzle-runtime-icon-button h-10 w-10 items-center justify-center rounded-full sm:h-11 sm:w-11 ${
-                hideBackButton ? 'invisible pointer-events-none' : 'inline-flex'
+                shouldHideBackButton
+                  ? 'invisible pointer-events-none'
+                  : 'inline-flex'
               }`}
             >
               <ArrowLeft className="h-4 w-4" />
@@ -1739,7 +1742,7 @@ export function PuzzleRuntimeShell({
                       onBack();
                     }}
                     className={`puzzle-runtime-primary-button rounded-full px-4 py-2 text-sm font-bold transition hover:brightness-105 ${
-                      hideBackButton ? 'hidden' : ''
+                      shouldHideBackButton ? 'hidden' : ''
                     }`}
                   >
                     返回上一页