Add frontend debug mode gate

src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx

@@ -1,7 +1,7 @@
 /* @vitest-environment jsdom */
 
 import { act, fireEvent, render, screen, within } from '@testing-library/react';
-import { expect, test, vi } from 'vitest';
+import { beforeEach, expect, test, vi } from 'vitest';
 
 import type { PuzzleRunSnapshot } from '../../../packages/shared/src/contracts/puzzleRuntimeSession';
 import { AuthUiContext } from '../auth/AuthUiContext';
@@ -31,6 +31,15 @@ const mocapMock = vi.hoisted(() => ({
   y: 0.58,
 }));
 
+const debugModeMock = vi.hoisted(() => ({
+  enabled: true,
+}));
+
+vi.mock('../../config/debugMode', () => ({
+  IS_DEBUG_MODE: debugModeMock.enabled,
+  isDebugMode: () => debugModeMock.enabled,
+}));
+
 vi.mock('../../services/useMocapInput', () => ({
   useMocapInput: () => ({
     status: 'connected',
@@ -44,6 +53,13 @@ vi.mock('../../services/useMocapInput', () => ({
   }),
 }));
 
+beforeEach(() => {
+  debugModeMock.enabled = true;
+  mocapMock.state = 'grab';
+  mocapMock.x = 0.42;
+  mocapMock.y = 0.58;
+});
+
 function createAuthValue() {
   return {
     user: null,
@@ -157,7 +173,7 @@ const clearedRun: PuzzleRunSnapshot = {
   },
 };
 
-test('拼图界面显示 mocap 连接状态和最近动作调试信息', () => {
+test('调试模式下拼图界面折叠展示 mocap 连接状态，展开后显示最近动作调试信息', () => {
   renderPuzzleRuntime(
     <PuzzleRuntimeShell
       run={{
@@ -176,12 +192,42 @@ test('拼图界面显示 mocap 连接状态和最近动作调试信息', () => {
 
   const debugPanel = screen.getByTestId('puzzle-mocap-debug');
   expect(within(debugPanel).getByText('mocap: connected')).toBeTruthy();
+  const toggleButton = within(debugPanel).getByRole('button', {
+    name: 'mocap: connected',
+  });
+  expect(toggleButton.getAttribute('aria-expanded')).toBe('false');
+  expect(within(debugPanel).queryByText('动作: grab')).toBeNull();
+
+  fireEvent.click(toggleButton);
+
+  expect(toggleButton.getAttribute('aria-expanded')).toBe('true');
   expect(within(debugPanel).getByText('动作: grab')).toBeTruthy();
   expect(within(debugPanel).getByText('手势: grab @ 0.42, 0.58')).toBeTruthy();
   expect(within(debugPanel).getByText('解析: 无')).toBeTruthy();
   expect(within(debugPanel).getByText(/原始:/)).toBeTruthy();
 });
 
+test('非调试模式下拼图界面不渲染 mocap 调试面板', () => {
+  debugModeMock.enabled = false;
+  renderPuzzleRuntime(
+    <PuzzleRuntimeShell
+      run={{
+        ...clearedRun,
+        currentLevel: {
+          ...clearedRun.currentLevel!,
+          status: 'playing',
+        },
+      }}
+      onBack={vi.fn()}
+      onSwapPieces={vi.fn()}
+      onDragPiece={vi.fn()}
+      onAdvanceNextLevel={vi.fn()}
+    />,
+  );
+
+  expect(screen.queryByTestId('puzzle-mocap-debug')).toBeNull();
+});
+
 test('拼图界面在 mocap open_palm 时显示体感光标', () => {
   mocapMock.state = 'open_palm';
   mocapMock.x = 0.42;