From c4cad629c945cd716d373e6dba4accc5093b7de0 Mon Sep 17 00:00:00 2001
From: Tom Boullay <tom@famille-boullay.fr>
Date: Wed, 3 Jun 2026 00:42:05 +0200
Subject: [PATCH] feat(handtracking): redesign SVG hand as primary
 visualization

Rewrite the live hand visualizer as a light-blue silhouette with a
crisp dark-blue outline, suitable as the primary hand UI (replacing
the buggy 3D glove for the default flow):

- Palm polygon (landmarks 0,1,5,9,13,17) and five finger tubes merged
  via an SVG feMorphology filter, so the outline is a single
  continuous ring with no internal seams.
- Q curves bow out to two synthetic wrist corners (perpendicular to
  the palm centerline) for a rounded heel of palm.
- Straight L edges between MCPs along the top - the filter dilation
  rounds the corners visually, no creux.
- Each finger path starts half a stroke inside the palm so the round
  base cap is hidden under the palm fill.
- Whole silhouette shrunk to 65% of the tracked hand size around the
  centroid, with 0.8 group opacity, and a faint MediaPipe skeleton
  overlay (lines + dots) on top.

Update the static fallback silhouettes (HandTrackingFallback) to a
matching curved-path look in a 100x120 viewBox.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/components/ui/HandTrackingFallback.tsx   |  77 +++++--
 src/components/ui/HandTrackingVisualizer.tsx | 217 +++++++++++++++----
 src/index.css                                |   8 +-
 3 files changed, 235 insertions(+), 67 deletions(-)

diff --git a/src/components/ui/HandTrackingFallback.tsx b/src/components/ui/HandTrackingFallback.tsx
index b5d2d53..e874992 100644
--- a/src/components/ui/HandTrackingFallback.tsx
+++ b/src/components/ui/HandTrackingFallback.tsx
@@ -4,29 +4,70 @@ import {
   type HandTrackingGloveHandedness,
 } from "@/hooks/handTracking/useHandTrackingGloveStatus";
 
-// Simple schematic silhouettes used as a last-resort fallback when the
-// rigged glove model has failed to load. Both icons share the same
-// 48x48 viewBox and the same stroke/fill rules from the .css.
+// Hand silhouettes used as a last-resort fallback when the rigged glove
+// model has failed to load. Both icons share a 100x120 viewBox so finger
+// lengths and the thumb angle stay anatomically readable.
 
 const OpenHandShape = (): React.JSX.Element => (
-  <>
-    <ellipse cx="9" cy="30" rx="3" ry="6" transform="rotate(-25 9 30)" />
-    <rect x="14" y="8" width="4" height="22" rx="2" />
-    <rect x="20" y="4" width="4" height="26" rx="2" />
-    <rect x="26" y="6" width="4" height="24" rx="2" />
-    <rect x="32" y="10" width="4" height="20" rx="2" />
-    <rect x="10" y="26" width="28" height="18" rx="6" />
-  </>
+  <path
+    d="M 28 116
+       Q 22 100 22 80
+       Q 22 65 28 58
+       Q 22 52 14 46
+       Q 6 40 8 28
+       Q 12 18 22 20
+       Q 30 24 30 36
+       Q 32 46 36 50
+       Q 36 38 36 28
+       Q 36 18 42 18
+       Q 48 18 48 28
+       Q 48 40 50 50
+       Q 50 32 50 14
+       Q 50 6 56 6
+       Q 62 6 62 14
+       Q 62 32 62 50
+       Q 64 38 64 20
+       Q 64 12 70 12
+       Q 76 12 76 20
+       Q 76 38 78 50
+       Q 78 40 78 32
+       Q 78 24 84 24
+       Q 90 24 90 32
+       Q 90 44 92 56
+       Q 96 80 92 100
+       Q 86 116 82 116
+       Z"
+  />
 );
 
 const FistShape = (): React.JSX.Element => (
   <>
-    <ellipse cx="8" cy="26" rx="3" ry="5" />
-    <rect x="10" y="14" width="28" height="30" rx="10" />
-    <circle cx="15" cy="14" r="3" />
-    <circle cx="21" cy="13" r="3" />
-    <circle cx="27" cy="13" r="3" />
-    <circle cx="33" cy="14" r="3" />
+    <path
+      d="M 18 70
+         Q 14 50 24 38
+         Q 28 30 36 34
+         Q 40 26 48 30
+         Q 54 22 60 28
+         Q 68 24 74 32
+         Q 84 32 88 46
+         Q 92 64 88 82
+         Q 82 104 64 112
+         Q 42 116 26 108
+         Q 14 96 18 70
+         Z"
+    />
+    <path
+      d="M 18 70
+         Q 6 66 8 80
+         Q 8 94 18 96
+         Q 28 94 26 84
+         Q 22 76 18 70
+         Z"
+    />
+    <path d="M 32 38 Q 30 50 34 60" fill="none" strokeLinecap="round" />
+    <path d="M 46 32 Q 44 46 48 58" fill="none" strokeLinecap="round" />
+    <path d="M 60 32 Q 58 46 62 58" fill="none" strokeLinecap="round" />
+    <path d="M 74 36 Q 72 50 76 60" fill="none" strokeLinecap="round" />
   </>
 );
 
@@ -66,7 +107,7 @@ export function HandTrackingFallback(): React.JSX.Element | null {
           <svg
             key={`${handedness}-${index}`}
             className="hand-tracking-fallback__icon"
-            viewBox="0 0 48 48"
+            viewBox="0 0 100 120"
             style={{
               left: `${leftPercent}%`,
               top: `${topPercent}%`,
diff --git a/src/components/ui/HandTrackingVisualizer.tsx b/src/components/ui/HandTrackingVisualizer.tsx
index 283a870..e393862 100644
--- a/src/components/ui/HandTrackingVisualizer.tsx
+++ b/src/components/ui/HandTrackingVisualizer.tsx
@@ -1,8 +1,16 @@
 import { useHandTrackingSnapshot } from "@/hooks/handTracking/useHandTrackingSnapshot";
-import { useHandTrackingGloveStatus } from "@/hooks/handTracking/useHandTrackingGloveStatus";
 import { useDebugStore } from "@/hooks/debug/useDebugStore";
 
-const HAND_CONNECTIONS: Array<[number, number]> = [
+// MediaPipe indexes the 21 hand landmarks predictably:
+// 0 wrist, 1-4 thumb (base→tip), 5-8 index, 9-12 middle, 13-16 ring, 17-20 pinky.
+const FINGER_LANDMARKS: Array<readonly number[]> = [
+  [1, 2, 3, 4],
+  [5, 6, 7, 8],
+  [9, 10, 11, 12],
+  [13, 14, 15, 16],
+  [17, 18, 19, 20],
+];
+const SKELETON_BONES: Array<[number, number]> = [
   [0, 1],
   [1, 2],
   [2, 3],
@@ -26,70 +34,187 @@ const HAND_CONNECTIONS: Array<[number, number]> = [
   [0, 17],
 ];
 
-const LANDMARK_FILL = "#67e8f9"; // cyan-300, opaque interior
-const LANDMARK_STROKE = "#0c4a6e"; // sky-900, dark blue outline
-const LANDMARK_STROKE_FIST = "#1e3a8a"; // blue-900, thicker accent when fist
-const CONNECTION_STROKE = "#ffffff"; // white bones
-const INDEX_TIP_LANDMARK = 8;
+const HAND_FILL = "#bfdbfe"; // blue-200, light interior
+const HAND_OUTLINE_COLOR = "#1e3a8a"; // blue-900, crisp dark outline
+const HAND_OUTLINE_RADIUS = 2; // px
+// Shrink the rendered hand around its centroid. Grab/physics keep using raw
+// landmarks elsewhere, so the silhouette is just visually smaller.
+const RENDER_SCALE = 0.65;
+const FINGER_THICKNESS_FACTOR = 0.08; // fraction of (scaled) hand length
+const WRIST_HALF_WIDTH = 0.28;
+const SKELETON_STROKE = "rgba(30, 58, 138, 0.22)";
+const SKELETON_DOT_FILL = "rgba(30, 58, 138, 0.35)";
+const FILTER_ID = "hand-tracking-outline";
 
 export function HandTrackingVisualizer(): React.JSX.Element | null {
   const { hands, status } = useHandTrackingSnapshot();
-  const showHandTrackingSvg = useDebugStore((debug) =>
-    debug.getShowHandTrackingSvg(),
-  );
-  const gloves = useHandTrackingGloveStatus((state) => state.gloves);
-  const hasLoadedGlove = Object.values(gloves).some(
-    (gloveStatus) => gloveStatus === "loaded",
+  const showHandTrackingModel = useDebugStore((debug) =>
+    debug.getShowHandTrackingModel(),
   );
 
-  if (
-    status === "idle" ||
-    hands.length === 0 ||
-    (hasLoadedGlove && !showHandTrackingSvg)
-  ) {
+  if (status === "idle" || hands.length === 0 || showHandTrackingModel) {
     return null;
   }
 
+  const viewportWidth = window.innerWidth;
+  const viewportHeight = window.innerHeight;
+
   return (
     <svg className="hand-tracking-visualizer" aria-hidden="true">
+      <defs>
+        {/* Dilate the merged alpha of all child shapes by HAND_OUTLINE_RADIUS
+            and subtract the original to get a 1-ring outline. Lets the palm
+            polygon and the five finger tubes share a single crisp outline
+            with no internal seams where they overlap. */}
+        <filter id={FILTER_ID} x="-10%" y="-10%" width="120%" height="120%">
+          <feMorphology
+            operator="dilate"
+            radius={HAND_OUTLINE_RADIUS}
+            in="SourceAlpha"
+            result="dilated"
+          />
+          <feComposite
+            operator="out"
+            in="dilated"
+            in2="SourceAlpha"
+            result="ringAlpha"
+          />
+          <feFlood floodColor={HAND_OUTLINE_COLOR} result="ringColor" />
+          <feComposite
+            operator="in"
+            in="ringColor"
+            in2="ringAlpha"
+            result="coloredRing"
+          />
+          <feMerge>
+            <feMergeNode in="SourceGraphic" />
+            <feMergeNode in="coloredRing" />
+          </feMerge>
+        </filter>
+      </defs>
+
       {hands.map((hand, handIndex) => {
         const landmarks = hand.landmarks;
-        if (landmarks.length === 0) return null;
+        if (landmarks.length < 21) return null;
 
-        const landmarkStroke = hand.isFist
-          ? LANDMARK_STROKE_FIST
-          : LANDMARK_STROKE;
+        // Centroid of all 21 landmarks in pixel space (mirrored x).
+        let cx = 0;
+        let cy = 0;
+        for (const lm of landmarks) {
+          cx += (1 - lm.x) * viewportWidth;
+          cy += lm.y * viewportHeight;
+        }
+        cx /= landmarks.length;
+        cy /= landmarks.length;
+
+        // Render coordinates: shrink each landmark toward the centroid.
+        const px = (i: number): number => {
+          const lm = landmarks[i];
+          return lm
+            ? cx + ((1 - lm.x) * viewportWidth - cx) * RENDER_SCALE
+            : cx;
+        };
+        const py = (i: number): number => {
+          const lm = landmarks[i];
+          return lm ? cy + (lm.y * viewportHeight - cy) * RENDER_SCALE : cy;
+        };
+
+        const handLengthPx = Math.hypot(px(12) - px(0), py(12) - py(0));
+        const fingerThickness = Math.max(
+          6,
+          handLengthPx * FINGER_THICKNESS_FACTOR,
+        );
+        const halfFingerThickness = fingerThickness / 2;
+        const dotRadius = Math.max(1.2, fingerThickness * 0.1);
+
+        // Perpendicular to the palm centerline (wrist → middle MCP), used to
+        // place two synthetic wrist corners on either side of landmark 0.
+        const cdx = px(9) - px(0);
+        const cdy = py(9) - py(0);
+        const clen = Math.hypot(cdx, cdy) || 1;
+        const perpX = -cdy / clen;
+        const perpY = cdx / clen;
+        const thumbSide =
+          (px(1) - px(0)) * perpX + (py(1) - py(0)) * perpY >= 0 ? 1 : -1;
+        const wristHalfWidth = handLengthPx * WRIST_HALF_WIDTH;
+        const wristThumbX = px(0) + perpX * wristHalfWidth * thumbSide;
+        const wristThumbY = py(0) + perpY * wristHalfWidth * thumbSide;
+        const wristPinkyX = px(0) - perpX * wristHalfWidth * thumbSide;
+        const wristPinkyY = py(0) - perpY * wristHalfWidth * thumbSide;
+
+        // Palm outline: straight L between adjacent MCPs along the top (no
+        // inter-finger dip — the morphology dilation rounds the MCP corners),
+        // rounded heel via two Q curves bowing out to the synthetic wrist
+        // corners.
+        const palmD = [
+          `M ${px(1)} ${py(1)}`,
+          `L ${px(5)} ${py(5)}`,
+          `L ${px(9)} ${py(9)}`,
+          `L ${px(13)} ${py(13)}`,
+          `L ${px(17)} ${py(17)}`,
+          `Q ${wristPinkyX} ${wristPinkyY}, ${px(0)} ${py(0)}`,
+          `Q ${wristThumbX} ${wristThumbY}, ${px(1)} ${py(1)}`,
+          "Z",
+        ].join(" ");
+
+        // Each finger path starts halfFingerThickness inside the palm (toward
+        // the next joint), so the rounded base cap sits hidden inside the palm
+        // fill instead of bulging below the MCP.
+        const fingerPathD = (joints: readonly number[]): string => {
+          const baseIdx = joints[0];
+          const nextIdx = joints[1];
+          if (baseIdx === undefined || nextIdx === undefined) return "";
+          const baseX = px(baseIdx);
+          const baseY = py(baseIdx);
+          const nextX = px(nextIdx);
+          const nextY = py(nextIdx);
+          const dx = nextX - baseX;
+          const dy = nextY - baseY;
+          const dlen = Math.hypot(dx, dy) || 1;
+          const sx = baseX + (dx / dlen) * halfFingerThickness;
+          const sy = baseY + (dy / dlen) * halfFingerThickness;
+          return joints
+            .map((idx, k) =>
+              k === 0 ? `M ${sx} ${sy}` : `L ${px(idx)} ${py(idx)}`,
+            )
+            .join(" ");
+        };
 
         return (
           <g key={`${hand.handedness}-${handIndex}`}>
-            {HAND_CONNECTIONS.map(([from, to]) => {
-              const fromPoint = landmarks[from];
-              const toPoint = landmarks[to];
-              if (!fromPoint || !toPoint) return null;
-
-              return (
-                <line
-                  key={`${from}-${to}`}
-                  x1={`${(1 - fromPoint.x) * 100}%`}
-                  y1={`${fromPoint.y * 100}%`}
-                  x2={`${(1 - toPoint.x) * 100}%`}
-                  y2={`${toPoint.y * 100}%`}
-                  stroke={CONNECTION_STROKE}
-                  strokeWidth="2.5"
+            <g filter={`url(#${FILTER_ID})`}>
+              <path d={palmD} fill={HAND_FILL} />
+              {FINGER_LANDMARKS.map((joints, fingerIndex) => (
+                <path
+                  key={fingerIndex}
+                  d={fingerPathD(joints)}
+                  fill="none"
+                  stroke={HAND_FILL}
+                  strokeWidth={fingerThickness}
                   strokeLinecap="round"
+                  strokeLinejoin="round"
                 />
-              );
-            })}
+              ))}
+            </g>
 
-            {landmarks.map((landmark, landmarkIndex) => (
+            {SKELETON_BONES.map(([from, to]) => (
+              <line
+                key={`bone-${from}-${to}`}
+                x1={px(from)}
+                y1={py(from)}
+                x2={px(to)}
+                y2={py(to)}
+                stroke={SKELETON_STROKE}
+                strokeWidth="1"
+              />
+            ))}
+            {landmarks.map((_, landmarkIndex) => (
               <circle
-                key={landmarkIndex}
-                cx={`${(1 - landmark.x) * 100}%`}
-                cy={`${landmark.y * 100}%`}
-                r={landmarkIndex === INDEX_TIP_LANDMARK ? 6 : 4}
-                fill={LANDMARK_FILL}
-                stroke={landmarkStroke}
-                strokeWidth={hand.isFist ? 2.5 : 2}
+                key={`dot-${landmarkIndex}`}
+                cx={px(landmarkIndex)}
+                cy={py(landmarkIndex)}
+                r={dotRadius}
+                fill={SKELETON_DOT_FILL}
               />
             ))}
           </g>
diff --git a/src/index.css b/src/index.css
index 5a347ec..b797892 100644
--- a/src/index.css
+++ b/src/index.css
@@ -1799,7 +1799,8 @@ canvas {
   width: 100vw;
   height: 100vh;
   pointer-events: none;
-  filter: drop-shadow(0 0 8px rgba(56, 189, 248, 0.55));
+  opacity: 0.8;
+  filter: drop-shadow(0 0 4px rgba(96, 165, 250, 0.3));
 }
 
 .hand-tracking-fallback {
@@ -1813,12 +1814,13 @@ canvas {
 
 .hand-tracking-fallback__icon {
   position: absolute;
-  width: 96px;
+  width: 80px;
   height: 96px;
   fill: #67e8f9;
   stroke: #0c4a6e;
-  stroke-width: 2;
+  stroke-width: 3;
   stroke-linejoin: round;
+  stroke-linecap: round;
   filter: drop-shadow(0 0 8px rgba(56, 189, 248, 0.55));
 }