From d0497ec42c65474cbb7cb70d5b2fe2f75786335c Mon Sep 17 00:00:00 2001
From: Tom Boullay <tom@famille-boullay.fr>
Date: Mon, 25 May 2026 01:19:14 +0200
Subject: [PATCH] fix(debug): defer hand tracking startup

---
 src/components/ui/SceneLoadingOverlay.tsx     | 18 ++++++++++
 src/index.css                                 | 10 ++++++
 .../gameplay/HandTrackingProvider.tsx         | 35 ++++++++++++-------
 src/utils/debug/Debug.ts                      |  3 +-
 4 files changed, 53 insertions(+), 13 deletions(-)

diff --git a/src/components/ui/SceneLoadingOverlay.tsx b/src/components/ui/SceneLoadingOverlay.tsx
index d5c66c9..9037d52 100644
--- a/src/components/ui/SceneLoadingOverlay.tsx
+++ b/src/components/ui/SceneLoadingOverlay.tsx
@@ -9,6 +9,7 @@ export function SceneLoadingOverlay({
 }: SceneLoadingOverlayProps): React.JSX.Element | null {
   const isReady = state.status === "ready";
   const progress = Math.round(Math.max(0, Math.min(1, state.progress)) * 100);
+  const helperText = getLoadingHelperText(state.progress);
 
   return (
     <div
@@ -17,6 +18,7 @@ export function SceneLoadingOverlay({
     >
       <div className="scene-loading-overlay__content">
         <strong>{state.currentStep}</strong>
+        <p>{helperText}</p>
         <div className="scene-loading-overlay__track">
           <span style={{ width: `${progress}%` }} />
           <em>{progress}%</em>
@@ -25,3 +27,19 @@ export function SceneLoadingOverlay({
     </div>
   );
 }
+
+function getLoadingHelperText(progress: number): string {
+  if (progress >= 0.95) {
+    return "Finalisation de la scène et de la première frame.";
+  }
+
+  if (progress >= 0.7) {
+    return "Préparation des collisions et du gameplay.";
+  }
+
+  if (progress >= 0.25) {
+    return "Chargement progressif de la map autour du joueur.";
+  }
+
+  return "Récupération des données et modèles nécessaires.";
+}
diff --git a/src/index.css b/src/index.css
index cd732fe..9a55a73 100644
--- a/src/index.css
+++ b/src/index.css
@@ -466,6 +466,16 @@ canvas {
   text-transform: uppercase;
 }
 
+.scene-loading-overlay p {
+  max-width: 290px;
+  margin: -8px 0 0;
+  color: #64748b;
+  font-size: 12px;
+  font-weight: 500;
+  line-height: 1.45;
+  text-align: center;
+}
+
 .scene-loading-overlay__track {
   position: relative;
   overflow: hidden;
diff --git a/src/providers/gameplay/HandTrackingProvider.tsx b/src/providers/gameplay/HandTrackingProvider.tsx
index 87b72c6..a5993f9 100644
--- a/src/providers/gameplay/HandTrackingProvider.tsx
+++ b/src/providers/gameplay/HandTrackingProvider.tsx
@@ -24,9 +24,6 @@ export function HandTrackingProvider({
   children: ReactNode;
 }): React.JSX.Element {
   const sceneMode = useSceneMode();
-  const handTrackingSource = useDebugStore((debug) =>
-    debug.getHandTrackingSource(),
-  );
   const repairNeedsHands = useGameStore((state) => {
     switch (state.mainState) {
       case "bike":
@@ -44,20 +41,34 @@ export function HandTrackingProvider({
   const enabled =
     repairNeedsHands ||
     (sceneMode === "physics" && (nearby || holding || handHolding));
+
+  if (!enabled) {
+    return (
+      <HandTrackingContext value={HAND_TRACKING_IDLE_SNAPSHOT}>
+        {children}
+      </HandTrackingContext>
+    );
+  }
+
+  return <ActiveHandTrackingProvider>{children}</ActiveHandTrackingProvider>;
+}
+
+function ActiveHandTrackingProvider({
+  children,
+}: {
+  children: ReactNode;
+}): React.JSX.Element {
+  const handTrackingSource = useDebugStore((debug) =>
+    debug.getHandTrackingSource(),
+  );
   const backendSnapshot = useRemoteHandTracking({
-    enabled: enabled && handTrackingSource === "backend",
+    enabled: handTrackingSource === "backend",
   });
   const browserSnapshot = useBrowserHandTracking({
-    enabled: enabled && handTrackingSource === "browser",
+    enabled: handTrackingSource === "browser",
   });
   const snapshot =
     handTrackingSource === "browser" ? browserSnapshot : backendSnapshot;
 
-  return (
-    <HandTrackingContext
-      value={enabled ? snapshot : HAND_TRACKING_IDLE_SNAPSHOT}
-    >
-      {children}
-    </HandTrackingContext>
-  );
+  return <HandTrackingContext value={snapshot}>{children}</HandTrackingContext>;
 }
diff --git a/src/utils/debug/Debug.ts b/src/utils/debug/Debug.ts
index 3c29920..f9498a7 100644
--- a/src/utils/debug/Debug.ts
+++ b/src/utils/debug/Debug.ts
@@ -103,7 +103,6 @@ export class Debug {
 
     if (this.gui) {
       this.gui.open();
-      this.createOrderedFolders();
 
       this.gui
         .add(this.controls, "cameraMode", { Player: "player", Debug: "debug" })
@@ -137,6 +136,8 @@ export class Debug {
           this.emit();
         });
 
+      this.createOrderedFolders();
+
       const handTrackingFolder = this.createFolder("Hand Tracking");
 
       handTrackingFolder