feat: add mocap puzzle debug and drag support

src/components/puzzle-runtime/PuzzleRuntimeShell.tsx

@@ -23,6 +23,7 @@ import type {
   SwapPuzzlePiecesRequest,
 } from '../../../packages/shared/src/contracts/puzzleRuntimeSession';
 import { useResolvedAssetReadUrl } from '../../hooks/useResolvedAssetReadUrl';
+import { useMocapInput } from '../../services/useMocapInput';
 import { CHROME_ICONS, getNineSliceStyle, UI_CHROME } from '../../uiAssets';
 import { useAuthUi } from '../auth/AuthUiContext';
 import { PixelIcon } from '../PixelIcon';
@@ -283,6 +284,12 @@ type PuzzleHintDemoState = {
   offsetYPercent: number;
 };
 
+type PuzzleMocapCursorState = {
+  x: number;
+  y: number;
+  state: string;
+};
+
 function triggerPuzzlePiecePressHapticFeedback() {
   if (typeof navigator === 'undefined') {
     return;
@@ -367,6 +374,10 @@ export function PuzzleRuntimeShell({
     pieceId: string;
     groupId: string | null;
   } | null>(null);
+  const [mocapCursor, setMocapCursor] = useState<PuzzleMocapCursorState | null>(
+    null,
+  );
+  const mocapDragRef = useRef<{pieceId: string} | null>(null);
   const [dismissedClearKey, setDismissedClearKey] = useState<string | null>(
     null,
   );
@@ -397,6 +408,18 @@ export function PuzzleRuntimeShell({
   const { resolvedUrl: resolvedCoverImage } = useResolvedAssetReadUrl(
     currentLevel?.coverImageSrc ?? null,
   );
+  const mocapInput = useMocapInput({enabled: runtimeStatus === 'playing'});
+  const mocapActionsLabel =
+    mocapInput.latestCommand?.actions.length
+      ? mocapInput.latestCommand.actions.join(', ')
+      : '无';
+  const mocapHandLabel = mocapInput.latestCommand?.primaryHand
+    ? `${mocapInput.latestCommand.primaryHand.state} @ ${mocapInput.latestCommand.primaryHand.x.toFixed(2)}, ${mocapInput.latestCommand.primaryHand.y.toFixed(2)}`
+    : '无';
+  const mocapParseWarningLabel = mocapInput.latestCommand?.parseWarnings?.length
+    ? mocapInput.latestCommand.parseWarnings.join('；')
+    : '无';
+  const mocapRawPacketLabel = mocapInput.rawPacketPreview?.text ?? '未收到';
 
   useEffect(() => {
     currentLevelRef.current = currentLevel;
@@ -850,6 +873,49 @@ export function PuzzleRuntimeShell({
     return { row, col };
   };
 
+  const resolveMocapTargetCell = (x: number, y: number) => ({
+    row: Math.min(board.rows - 1, Math.max(0, Math.floor(y * board.rows))),
+    col: Math.min(board.cols - 1, Math.max(0, Math.floor(x * board.cols))),
+  });
+
+  const handleMocapInputCommand = () => {
+    const hand = mocapInput.latestCommand?.primaryHand;
+    if (runtimeStatus !== 'playing' || isInteractionLocked || !hand) {
+      mocapDragRef.current = null;
+      setMocapCursor(null);
+      return;
+    }
+
+    setMocapCursor({x: hand.x, y: hand.y, state: hand.state});
+    if (hand.state === 'grab') {
+      if (mocapDragRef.current) {
+        return;
+      }
+      const sourceCell = resolveMocapTargetCell(hand.x, hand.y);
+      const sourcePiece = pieceByCell.get(`${sourceCell.row}:${sourceCell.col}`) ?? null;
+      if (!sourcePiece || sourcePiece.mergedGroupId) {
+        return;
+      }
+      mocapDragRef.current = {pieceId: sourcePiece.pieceId};
+      setSelectedPieceId(sourcePiece.pieceId);
+      triggerPuzzlePiecePressHapticFeedback();
+      return;
+    }
+
+    const draggingPiece = mocapDragRef.current;
+    if (!draggingPiece) {
+      return;
+    }
+    const targetCell = resolveMocapTargetCell(hand.x, hand.y);
+    mocapDragRef.current = null;
+    setSelectedPieceId(null);
+    onDragPiece({
+      pieceId: draggingPiece.pieceId,
+      targetRow: targetCell.row,
+      targetCol: targetCell.col,
+    });
+  };
+
   const handlePiecePointerUp = (
     pieceId: string,
     event: React.PointerEvent<HTMLDivElement>,
@@ -973,7 +1039,6 @@ export function PuzzleRuntimeShell({
     isClearResultReady;
   const isInteractionLocked =
     isBusy || runtimeStatus !== 'playing' || Boolean(propDialog);
-
   const handleBackRequest = () => {
     if (hideExitControls) {
       return;
@@ -1085,6 +1150,10 @@ export function PuzzleRuntimeShell({
     }
   };
 
+  useEffect(() => {
+    handleMocapInputCommand();
+  }, [mocapInput.latestCommand?.primaryHand]);
+
   return (
     <div
       className={`puzzle-runtime-shell ${embedded ? 'relative h-full min-h-0 w-full' : 'fixed inset-0 z-[100]'} flex justify-center`}
@@ -1445,6 +1514,21 @@ export function PuzzleRuntimeShell({
                 />
               </div>
             ) : null}
+            {mocapCursor ? (
+              <div
+                data-testid="puzzle-mocap-cursor"
+                className={`pointer-events-none absolute z-[70] flex h-8 w-8 -translate-x-1/2 -translate-y-1/2 items-center justify-center rounded-full border-2 ${
+                  mocapCursor.state === 'grab'
+                    ? 'border-amber-200 bg-amber-400/90 text-amber-950'
+                    : 'border-cyan-200 bg-cyan-300/90 text-cyan-950'
+                } shadow-[0_10px_24px_rgba(15,23,42,0.25)]`}
+                style={{left: `${mocapCursor.x * 100}%`, top: `${mocapCursor.y * 100}%`}}
+              >
+                <span className="text-[10px] font-black leading-none">
+                  {mocapCursor.state === 'grab' ? '抓' : '手'}
+                </span>
+              </div>
+            ) : null}
             {mergeFlash ? (
               <div
                 key={mergeFlash.key}
@@ -1472,6 +1556,19 @@ export function PuzzleRuntimeShell({
               已选择
             </div>
           ) : null}
+          <div
+            data-testid="puzzle-mocap-debug"
+            className="w-[min(92vw,34rem)] rounded-[0.9rem] border border-white/20 bg-slate-950/70 px-3 py-2 font-mono text-[10px] leading-4 text-white shadow-[0_12px_32px_rgba(15,23,42,0.25)] backdrop-blur"
+          >
+            <div>mocap: {mocapInput.status}</div>
+            <div>动作: {mocapActionsLabel}</div>
+            <div>手势: {mocapHandLabel}</div>
+            <div>解析: {mocapParseWarningLabel}</div>
+            <div className="max-h-20 overflow-auto break-all text-white/75">
+              原始: {mocapRawPacketLabel}
+            </div>
+            {mocapInput.error ? <div>错误: {mocapInput.error}</div> : null}
+          </div>
           {canShowNextAction ? (
             <button
               type="button"