Merge branch 'develop' into feat/polish-mission-2

feat(site): sync naming typewriter to last subtitle cue
Replace the audio "ended"-based trigger with an SRT-driven one: the typewriter now starts (lastCue.endTime - typewriterDuration) seconds into the dialogue so the final letter lands at the moment the narrator finishes speaking. Char delay shortened from 110ms to 70ms for a snappier reveal. Fallbacks: audio "ended" when no SRT, 8s absolute timer otherwise.
2026-06-03 02:02:37 +02:00 · 2026-06-03 01:56:14 +02:00 · 2026-06-03 01:52:20 +02:00 · 2026-06-03 01:48:31 +02:00 · 2026-06-03 01:46:13 +02:00 · 2026-06-03 01:45:43 +02:00
34 changed files with 1152 additions and 192 deletions
@@ -20,9 +20,11 @@ Both sources funnel into the same `HandTrackingContext` so all consumers see one
 1. The active source captures or receives landmarks.
 2. The hook applies an EMA smoothing pass on the landmarks before publishing the snapshot.
 3. `HandTrackingProvider` exposes that snapshot through React context.
-4. `GrabbableObject` reads the snapshot each frame and uses the fist state plus raycasting to grab objects.
-5. `HandTrackingGlove` reads the same snapshot and places a rigged glove on each detected hand.
-6. `HandTrackingVisualizer` paints an SVG wireframe overlay on top of the canvas.
+4. `GrabbableObject` reads the snapshot each frame and uses `hand.isFist` plus raycasting to grab objects.
+5. `HandTrackingVisualizer` paints the SVG hand silhouette overlay on top of the canvas — the primary visualization.
+6. `HandTrackingGlove` (opt-in, see UI And Debug) places a rigged 3D glove on each detected hand when enabled via the debug toggle.
+
+All consumers — fist detection, grab raycasting, SVG silhouette, optional 3D glove — read the **same** landmarks from the snapshot. None of them depend on the others.

 ## Activation Rules

@@ -108,6 +110,17 @@ interface HandTrackingHand {

 `x` and `y` are normalized camera coordinates. `z` is a relative depth value from MediaPipe, not an absolute world-space distance.

+## Fist Detection
+
+`isFist` is computed in `src/lib/handTracking/browserHandTracking.ts` (`isFist()` function) from landmarks alone — no model, no glove. The check is:
+
+1. Palm center = mean of landmarks `[0, 5, 9, 13, 17]` (wrist + 4 MCPs).
+2. Palm size = distance from wrist (landmark 0) to middle MCP (landmark 9).
+3. For each of the four fingertip landmarks `[8, 12, 16, 20]`, check whether its distance to the palm center is less than `1.05 × palmSize`.
+4. `isFist === true` iff all four fingertips pass the check.
+
+The flag is attached to each hand on the snapshot at the publish step (`isFist: isFist(normalizedLandmarks)`) and read directly by `GrabbableObject.tsx` — the SVG visualizer and the 3D glove never participate in the gesture decision.
+
 ## Grab Targeting

 The hand grab logic lives in `src/components/three/interaction/GrabbableObject.tsx`.
@@ -142,18 +155,40 @@ This is less expressive than true depth-aware hand movement, but it is more stab
 The current debug UI includes:

 - `HandTrackingDebugPanel` inside `DebugOverlayLayout` for status, usage, loaded glove model, server state, hand count, and fist state
- `HandTrackingVisualizer` for the SVG landmark overlay
- `HandTrackingFallback` for the last-resort hand silhouette overlay
- `HandTrackingGlove` for the per-hand rigged glove models in the R3F scene
+- `HandTrackingVisualizer` for the SVG hand silhouette overlay (always on when tracking is active)
+- `HandTrackingFallback` for the last-resort hand silhouette overlay (legacy, see below)
+- `HandTrackingGlove` for the per-hand rigged glove models in the R3F scene, opt-in via the **Show Model** toggle
 - `r3f-perf` for render performance
 - `lil-gui` for scene, camera, lighting, interaction, and grab controls

-The SVG visualizer uses a "blueish hand" style: white connection lines between landmarks, cyan circles with a dark blue outline. The outline gets thicker when the hand is detected as a fist, so the user gets a visual confirmation of the grab gesture without having to look at the debug panel.
+### SVG Visualizer

-The fallback overlay (`HandTrackingFallback`) draws a simple open-hand or fist silhouette positioned on the detected wrist landmark. It only renders for a hand whose matching glove is in the `"error"` state in `useHandTrackingGloveStatus`. This guarantees the user always sees something on their hand even when the 3D glove model fails to load.
+`HandTrackingVisualizer` is the primary hand visualization. It draws a light-blue hand silhouette with a crisp dark-blue outline by:
+
+1. Filling a palm polygon (landmarks `[1, 5, 9, 13, 17]` plus two synthetic wrist corners) and five finger tubes (thick rounded `stroke` along each finger's joint chain).
+2. Wrapping the whole thing in an SVG `<filter>` that uses `feMorphology` to dilate the merged alpha by 2 px and subtract the original, producing a single continuous outline around the union — no internal seams where the palm and finger tubes overlap.
+3. Shrinking every landmark toward the hand centroid by `RENDER_SCALE = 0.65` so the silhouette stays compact and doesn't dominate the screen.
+4. Overlaying the 21 raw landmarks and 21 bones as faint translucent lines and dots, so the user can still see the MediaPipe data feeding the silhouette.
+
+The SVG only displays when MediaPipe is active and the debug **Show Model** toggle is off (default). When the toggle is on, the SVG hides and `HandTrackingGlove` takes over.
+
+### Show Model Toggle
+
+The `Hand Tracking` debug folder exposes a single visualization switch:
+
+- `showHandTrackingModel = false` (default): SVG visualizer renders, 3D glove is not mounted at all.
+- `showHandTrackingModel = true`: SVG visualizer hides, 3D glove gets mounted for the detected hand(s).
+
+The 3D glove is treated as opt-in legacy because it had bugs (WebGL context loss, finger rig artefacts) and its hit/grab role was never load-bearing — grab has always read landmarks directly.
+
+### Fallback Overlay (legacy)
+
+`HandTrackingFallback` draws a simple open-hand or fist silhouette positioned on the detected wrist landmark. It renders for any hand whose glove is in the `"error"` state in `useHandTrackingGloveStatus`. Now that the glove is opt-in and rarely mounted, the fallback effectively only fires in the rare case where the user enables `showHandTrackingModel` and the glove fails to load. It is kept on disk for that edge case but is not part of the default visual path.

 ## Glove Models

+The 3D glove is **opt-in** via the `Show Model` debug toggle (see UI And Debug). It is not mounted by default; the SVG visualizer is the primary hand UI. The information below applies only when the toggle is enabled.
+
 `HandTrackingGlove` loads `public/models/gant_l/model.gltf` for both hands. The right hand applies `scale.x = -1` at the group level to mirror the mesh, so the thumb ends up on the correct side. Both hands therefore share the same rig and the same material.

 The historical `public/models/gant_r/model.gltf` is kept as legacy but is not loaded by the frontend — its GLB embeds three skeletons (`Hand_l`, `Hand_l_pad`, `Hand_r`) plus a `galet` mesh, which made the finger rig unreliable.
@@ -172,6 +207,8 @@ They are intended for future swap-by-state usage but are **not yet rigged**. The
 - Production usage is currently limited to repair mission steps that explicitly need hands.
 - MediaPipe depth is relative and currently not used for stable object depth control.
 - The virtual hit zone is an approximation based on multiple raycasts, not a real 3D collider.
+- The 3D glove is opt-in only (see `Show Model` toggle). Default visual is the SVG silhouette.
+- `HandTrackingFallback` is legacy and effectively unused unless the glove toggle is enabled and the glove fails to load.
 - The right glove is a mirrored copy of `gant_l` rather than its own mesh; in the future a dedicated right-hand model would give a better visual.
 - The `_pad` glove variants are not rigged yet, so swap-by-state (normal ↔ pad) is not wired in.
 - Finger bone animation is an approximate landmark-to-bone mapping; it still needs calibration for per-model twist, offsets, and smoothing.
@@ -2,24 +2,18 @@
  "version": 1,
  "cinematics": [
    {
-      "id": "intro_overview",
+      "id": "outro_farm_drone",
      "timecode": 0,
-      "dialogueCues": [
-        {
-          "time": 0,
-          "dialogueId": "narrateur_bienvenueaaltera"
-        }
-      ],
      "cameraKeyframes": [
        {
          "time": 0,
-          "position": [8, 5, 12],
-          "target": [0, 2, 0]
+          "position": [-24, 5, 65],
+          "target": [-24, 2, 42]
        },
        {
-          "time": 4,
-          "position": [12, 4, -6],
-          "target": [10, 1.4, -8]
+          "time": 10,
+          "position": [-24, 90, 200],
+          "target": [-24, 0, 42]
        }
      ]
    }
@@ -39340,8 +39340,7 @@
                      "rotation": [0, 0.0027, 0.0819],
                      "scale": [1, 1, 1]
                    }
-                  ],
-                  "id": "repair:pylon"
+                  ]
                },
                {
                  "name": "pylone",
@@ -39373,7 +39372,8 @@
                      "rotation": [0, 0.0027, 0.0819],
                      "scale": [1, 1, 1]
                    }
-                  ]
+                  ],
+                  "id": "repair:pylon"
                },
                {
                  "name": "pylone",
@@ -163,7 +163,7 @@
      "id": "narrateur_histoireelectricienne",
      "voice": "narrateur",
      "audio": "/sounds/dialogue/narrateur_histoireelectricienne.mp3",
-      "subtitleCueIndex": 23
+      "subtitleCueIndices": [23, 25, 26, 27, 28]
    },
    {
      "id": "narrateur_demande_aide",
@@ -87,5 +87,21 @@ Welcome to your workshop!! So? Pretty impressive, right? Okay, quick tour of wha
 Here, this is a dashboard. You can imagine that if your fridge or oven breaks down, you won't be able to put it in the pipe haha! So here, it tells you when residents have a bulky item that broke down, or when there's a problem in the city. Uh oh... I've got an emergency, I'll have to leave you soon! So here, take your tools to repair most things: a mini 3D printer powered by electronic waste, Push-Parts gloves to disassemble objects, and a Relaunch pack!

 23
-00:00:00,000 --> 00:00:54,000
-The electrician helped you at the Power Plant? Aaaaah, that's what I love here: everyone helps each other, nobody judges anyone, it's like a real little family. You should know the electrician has quite a special story. She was born in the north of the continent, in the city of Kalska. She grew up happily with her mother Edith, her father Jordan, and her two little brothers, Malo and Justin. A few years ago, as you know, the northern countries were, quite unexpectedly, the first ones forced to migrate. So they began their journey, country by country, city by city, village by village. On a day of walking like so many others after several months, a climate storm caught them off guard. Having split up to find food in the village, her father and one of her two brothers sadly disappeared. It's tragic. But one day, they happened upon this place during their journey. We welcomed them with open arms, and they were slowly able to rebuild their lives among us. Today, they are an integral part of the community.
+00:00:00,000 --> 00:00:07,500
+The electrician helped you at the Power Plant? Aaaaah, that's what I love here: everyone helps each other, nobody judges anyone, it's like a real little family.
+
+25
+00:00:07,500 --> 00:00:19,100
+You should know the electrician has quite a special story. She was born in the north of the continent, in the city of Kalska. She grew up happily with her mother Edith, her father Jordan, and her two little brothers, Malo and Justin.
+
+26
+00:00:19,100 --> 00:00:30,600
+A few years ago, as you know, the northern countries were, quite unexpectedly, the first ones forced to migrate. So they began their journey, country by country, city by city, village by village.
+
+27
+00:00:30,600 --> 00:00:42,800
+On a day of walking like so many others after several months, a climate storm caught them off guard. Having split up to find food in the village, her father and one of her two brothers sadly disappeared. It's tragic.
+
+28
+00:00:42,800 --> 00:00:54,000
+But one day, they happened upon this place during their journey. We welcomed them with open arms, and they were slowly able to rebuild their lives among us. Today, they are an integral part of the community.
@@ -87,5 +87,21 @@ Bienvenue dans ton atelier !! Alors ? Ça claque hein ? Bon je te présente en r
 Ici, c'est un tableau de bord. T'imagines bien que si ton frigo ou ton four tombe en panne, tu ne vas pas pouvoir le mettre dans le tuyau haha ! Donc ici, ça te signale quand des résidents ont un objet volumineux tombé en panne, ou quand il y a un problème dans la ville. Oh oh... j'ai une urgence, il va bientôt falloir que je te laisse ! Donc tiens, tes outils pour pouvoir réparer la plupart des choses : une mini imprimante 3D à base de déchets électroniques, des gants Pousse Pièces pour désassembler les objets, ainsi qu'un pack de Relance !

 23
-00:00:00,000 --> 00:00:54,000
-L'électricienne t'a aidé à la Centrale ? Aaaaah c'est ça que j'adore ici, tout le monde s'entraide, personne se juge, une vraie petite famille. Sache que l'électricienne a une histoire assez particulière. Elle est née au nord du continent, dans la ville de Kalska. Elle a grandit heureuse, avec sa mère Edith, son père Jordan et ses deux petits frères Malo et Justin. Il y a quelques années de ça, comme tu le sais, c'est les pays du Nord, qui par grande surprise, ont été obligés de migrer en premier. Ils ont alors entamé leur périple, pays par pays, ville par ville, village par village. Un jour de marche comme les autres depuis plusieurs mois, une tempête climatique les a pris de court. S'étant séparés pour trouver des vivres dans le village, le père et un des deux frères sont malheureusement partis. C'est tragique. Mais un beau jour, ils sont tombés ici, par hasard dans leur périple. On les a accueillis les bras ouverts et ils ont pu se reconstruire doucement parmi nous et font partie intégrante de la communauté aujourd'hui.
+00:00:00,000 --> 00:00:07,500
+L'électricienne t'a aidé à la Centrale ? Aaaaah c'est ça que j'adore ici, tout le monde s'entraide, personne se juge, une vraie petite famille.
+
+25
+00:00:07,500 --> 00:00:19,100
+Sache que l'électricienne a une histoire assez particulière. Elle est née au nord du continent, dans la ville de Kalska. Elle a grandit heureuse, avec sa mère Edith, son père Jordan et ses deux petits frères Malo et Justin.
+
+26
+00:00:19,100 --> 00:00:30,600
+Il y a quelques années de ça, comme tu le sais, c'est les pays du Nord, qui par grande surprise, ont été obligés de migrer en premier. Ils ont alors entamé leur périple, pays par pays, ville par ville, village par village.
+
+27
+00:00:30,600 --> 00:00:42,800
+Un jour de marche comme les autres depuis plusieurs mois, une tempête climatique les a pris de court. S'étant séparés pour trouver des vivres dans le village, le père et un des deux frères sont malheureusement partis. C'est tragique.
+
+28
+00:00:42,800 --> 00:00:54,000
+Mais un beau jour, ils sont tombés ici, par hasard dans leur périple. On les a accueillis les bras ouverts et ils ont pu se reconstruire doucement parmi nous et font partie intégrante de la communauté aujourd'hui.
@@ -334,7 +334,7 @@ export function Ebike({

  const interactionLabel =
    mainState === "ebike"
-      ? "Lancer le repair game"
+      ? "Lancer le Repair Game"
      : movementMode === "walk"
        ? "Monter sur le bike"
        : "Descendre du bike";
@@ -344,13 +344,19 @@ export function Ebike({
  // pollute the view. The prompt comes back the moment the bike comes to
  // a stop. window.ebikeDriveInputActive is published every frame by
  // PlayerController based on whether a movement key is currently held.
+  // Also hide entirely while the breakdown sequence is active — the bike
+  // must read as inert and non-interactive while the panne dialogue plays
+  // and during the auto-dismount that follows.
  const [isEbikeDriving, setIsEbikeDriving] = useState(false);
+  const [isEbikeBreakdown, setIsEbikeBreakdown] = useState(false);
  useFrame(() => {
    const driving =
      movementMode === "ebike" && window.ebikeDriveInputActive === true;
    if (driving !== isEbikeDriving) setIsEbikeDriving(driving);
+    const breakdown = window.ebikeBreakdownActive === true;
+    if (breakdown !== isEbikeBreakdown) setIsEbikeBreakdown(breakdown);
  });
-  const showInteractPrompt = !isEbikeDriving;
+  const showInteractPrompt = !isEbikeDriving && !isEbikeBreakdown;

  const handleInteract = useCallback((): void => {
    if (window.ebikeBreakdownActive === true) return;
@@ -0,0 +1,165 @@
+import { useEffect, useRef } from "react";
+import { useGameStore } from "@/managers/stores/useGameStore";
+import { useSubtitleStore } from "@/managers/stores/useSubtitleStore";
+import { AudioManager } from "@/managers/AudioManager";
+
+const HISTOIRE_AUDIO_PATH = "/sounds/dialogue/narrateur_histoireelectricienne.mp3";
+const OUTRO_DELAY_MS = 5_000; // delay after audio ends before transitioning to outro
+
+/**
+ * Text blocks for the electricienne history narration (max 5 lines each).
+ * Displayed sequentially — timings are calculated dynamically from the actual
+ * audio duration so they are always correct regardless of the mp3 length.
+ */
+const HISTOIRE_BLOCKS = [
+  "L'électricienne t'a aidé à la Centrale ? Aaaaah c'est ça que j'adore ici, tout le monde s'entraide, personne se juge, une vraie petite famille.",
+  "Sache que l'électricienne a une histoire assez particulière. Elle est née au nord du continent, dans la ville de Kalska. Elle a grandit heureuse, avec sa mère Edith, son père Jordan et ses deux petits frères Malo et Justin.",
+  "Il y a quelques années de ça, comme tu le sais, c'est les pays du Nord, qui par grande surprise, ont été obligés de migrer en premier. Ils ont alors entamé leur périple, pays par pays, ville par ville, village par village.",
+  "Un jour de marche comme les autres depuis plusieurs mois, une tempête climatique les a pris de court. S'étant séparés pour trouver des vivres dans le village, le père et un des deux frères sont malheureusement partis. C'est tragique.",
+  "Mais un beau jour, ils sont tombés ici, par hasard dans leur périple. On les a accueillis les bras ouverts et ils ont pu se reconstruire doucement parmi nous et font partie intégrante de la communauté aujourd'hui.",
+] as const;
+
+const TOTAL_CHARS = HISTOIRE_BLOCKS.reduce((sum, b) => sum + b.length, 0);
+
+/** Compute start/end times for each block based on actual audio duration. */
+function buildBlockTimings(
+  duration: number,
+): Array<{ start: number; end: number }> {
+  let t = 0;
+  return HISTOIRE_BLOCKS.map((block) => {
+    const blockDuration = (block.length / TOTAL_CHARS) * duration;
+    const start = t;
+    t += blockDuration;
+    return { start, end: t };
+  });
+}
+
+/**
+ * Play the histoire audio and keep `useSubtitleStore` in sync with
+ * dynamically-computed block boundaries.
+ * Movement is intentionally NOT blocked so the player can explore while
+ * listening to the narration.
+ * `onAudioEnded` fires once when the audio element emits "ended".
+ */
+function useHistoireSubtitlePlayback(
+  enabled: boolean,
+  onAudioEnded?: () => void,
+): void {
+  // Keep callback in a ref so the effect doesn't need it as a dependency.
+  const onAudioEndedRef = useRef(onAudioEnded);
+  useEffect(() => {
+    onAudioEndedRef.current = onAudioEnded;
+  });
+
+  useEffect(() => {
+    if (!enabled) return undefined;
+
+    let isCancelled = false;
+
+    const audio = AudioManager.getInstance().playSound(HISTOIRE_AUDIO_PATH, 1, {
+      category: "dialogue",
+    });
+
+    if (!audio) return undefined;
+
+    const { setActiveSubtitle, clearActiveSubtitle } =
+      useSubtitleStore.getState();
+
+    /** Wire up block-level subtitle sync once we know the audio duration. */
+    function startSync(): void {
+      const duration = audio.duration;
+      if (!duration || isNaN(duration) || isCancelled) return;
+
+      const timings = buildBlockTimings(duration);
+
+      function onTimeUpdate(): void {
+        const t = audio.currentTime;
+        const idx = timings.findIndex(
+          ({ start, end }) => t >= start && t < end,
+        );
+        if (idx >= 0) {
+          setActiveSubtitle({
+            speaker: "Narrateur",
+            text: HISTOIRE_BLOCKS[idx],
+          });
+        }
+      }
+
+      function onEnded(): void {
+        clearActiveSubtitle();
+        onAudioEndedRef.current?.();
+      }
+
+      audio.addEventListener("timeupdate", onTimeUpdate);
+      audio.addEventListener("ended", onEnded, { once: true });
+    }
+
+    // If duration is already known (cached audio), start immediately.
+    if (audio.duration && !isNaN(audio.duration)) {
+      startSync();
+    } else {
+      audio.addEventListener("loadedmetadata", startSync, { once: true });
+    }
+
+    return () => {
+      isCancelled = true;
+      audio.pause();
+      useSubtitleStore.getState().clearActiveSubtitle();
+    };
+  }, [enabled]);
+}
+
+/**
+ * Handles the farm mission narrative intro:
+ *   locked → (auto) → electricienne_history → plays audio with block subtitles
+ *                   → 5 s after audio ends → completeMission("farm") → outro
+ */
+export function FarmNarrativeFlow(): null {
+  const mainState = useGameStore((state) => state.mainState);
+  const step = useGameStore((state) => state.farm.currentStep);
+  const setMissionStep = useGameStore((state) => state.setMissionStep);
+  const completeMission = useGameStore((state) => state.completeMission);
+
+  // locked is purely a gate — transition immediately to electricienne_history.
+  useEffect(() => {
+    if (mainState !== "farm" || step !== "locked") return;
+    setMissionStep("farm", "electricienne_history");
+  }, [mainState, step, setMissionStep]);
+
+  // Ensure movement is always allowed during the electricienne_history narration,
+  // regardless of what the previous step may have blocked.
+  const setCanMove = useGameStore((state) => state.setCanMove);
+  useEffect(() => {
+    if (mainState !== "farm" || step !== "electricienne_history") return;
+    setCanMove(true);
+  }, [mainState, step, setCanMove]);
+
+  // After the audio finishes, wait 5 s then transition to outro.
+  // The timeout ID is kept in a ref so we can cancel on unmount.
+  const outroTimeoutRef = useRef<ReturnType<typeof window.setTimeout> | null>(null);
+
+  useEffect(() => {
+    return () => {
+      if (outroTimeoutRef.current !== null) {
+        window.clearTimeout(outroTimeoutRef.current);
+      }
+    };
+  }, []);
+
+  const handleAudioEnded = (): void => {
+    if (outroTimeoutRef.current !== null) {
+      window.clearTimeout(outroTimeoutRef.current);
+    }
+    outroTimeoutRef.current = window.setTimeout(() => {
+      outroTimeoutRef.current = null;
+      completeMission("farm");
+    }, OUTRO_DELAY_MS);
+  };
+
+  useHistoireSubtitlePlayback(
+    mainState === "farm" && step === "electricienne_history",
+    handleAudioEnded,
+  );
+
+  return null;
+}
@@ -4,6 +4,8 @@ import { useGLTF } from "@react-three/drei";
 import * as THREE from "three";
 import { InteractableObject } from "@/components/three/interaction/InteractableObject";
 import { useGameStore } from "@/managers/stores/useGameStore";
+import { useRepairMissionAnchorStore } from "@/managers/stores/useRepairMissionAnchorStore";
+import { useTerrainSnappedPosition } from "@/hooks/three/useTerrainHeight";
 import { loadDialogueManifest } from "@/utils/dialogues/loadDialogueManifest";
 import { playDialogueById } from "@/utils/dialogues/playDialogue";
 import {
@@ -14,6 +16,7 @@ import {
  PYLON_UPRIGHT_ROTATION,
  PYLON_WORLD_POSITION,
 } from "@/data/gameplay/pylonConfig";
+import { isRepairGameStep } from "@/types/gameplay/repairMission";
 import { pylonStraighteningSignal } from "@/components/gameplay/pylon/pylonSignals";

 const PYLON_MODEL_PATH = "/models/pylone/model.glb";
@@ -22,6 +25,15 @@ export function PylonDownedPylon(): React.JSX.Element | null {
  const mainState = useGameStore((state) => state.mainState);
  const step = useGameStore((state) => state.pylon.currentStep);
  const setCanMove = useGameStore((state) => state.setCanMove);
+  // Use the repair:pylon anchor from the store so the downed pylon is always
+  // co-located with the instanced mesh it replaces. Falls back to the
+  // hard-coded constant while the map is loading or unavailable.
+  const pylonAnchor = useRepairMissionAnchorStore(
+    (state) => state.anchors.pylon,
+  );
+  // Snap to terrain so the downed/upright model sits flush on the ground,
+  // matching the Y adjustment that InstancedMapAsset applies to the same node.
+  const position = useTerrainSnappedPosition(pylonAnchor ?? PYLON_WORLD_POSITION);
  const [isStraightening, setIsStraightening] = useState(false);
  // Keeps the pylon upright after the animation completes while
  // PylonFarmerNPC plays the post-raise audio sequence.
@@ -30,19 +42,9 @@ export function PylonDownedPylon(): React.JSX.Element | null {
  const straightenStartRef = useRef<number | null>(null);
  const hasPlayedFirstAudioRef = useRef(false);

-  const showUpright =
-    isRaised ||
-    mainState !== "pylon" ||
-    step === "waiting" ||
-    step === "inspected" ||
-    step === "fragmented" ||
-    step === "scanning" ||
-    step === "repairing" ||
-    step === "reassembling" ||
-    step === "done" ||
-    step === "narrator-outro";
-
-  const isPylonInteractive = step === "arrived" || step === "npc-return";
+  // Hidden outside the pylon mission and once the pylon has been raised
+  // (repair-game steps take over from there).
+  const shouldRender = mainState === "pylon" && !isRepairGameStep(step);

  useEffect(() => {
    if (step === "arrived") {
@@ -61,9 +63,7 @@ export function PylonDownedPylon(): React.JSX.Element | null {
    if (!group) return;

    if (!isStraightening || straightenStartRef.current === null) {
-      group.rotation.set(
-        ...(showUpright ? PYLON_UPRIGHT_ROTATION : PYLON_DOWNED_ROTATION),
-      );
+      group.rotation.set(...(isRaised ? PYLON_UPRIGHT_ROTATION : PYLON_DOWNED_ROTATION));
      return;
    }

@@ -79,6 +79,8 @@ export function PylonDownedPylon(): React.JSX.Element | null {
    );
  });

+  const isPylonInteractive = step === "arrived" || step === "npc-return";
+
  const beginStraighten = (): void => {
    setIsStraightening(true);
    pylonStraighteningSignal.started = true;
@@ -99,10 +101,12 @@ export function PylonDownedPylon(): React.JSX.Element | null {
    }, PYLON_STRAIGHTEN_ANIMATION_DURATION_MS);
  };

+  if (!shouldRender) return null;
+
  return (
    <group
      ref={groupRef}
-      position={PYLON_WORLD_POSITION}
+      position={position}
      rotation={PYLON_DOWNED_ROTATION}
    >
      <primitive object={scene.clone(true)} />
@@ -112,7 +116,7 @@ export function PylonDownedPylon(): React.JSX.Element | null {
          label={
            step === "arrived" ? "Inspecter le pylône" : "Redresser le pylône"
          }
-          position={PYLON_WORLD_POSITION}
+          position={position}
          radius={PYLON_NARRATIVE_INTERACT_RADIUS}
          onPress={() => {
            if (step === "arrived") {
@@ -43,9 +43,32 @@ function faceToward(
  return Math.atan2(dx, dz);
 }

+/**
+ * Outer shell — only checks visibility conditions.
+ * Rendering is delegated to PylonFarmerNPCContent so that the heavy hooks
+ * (useFrame, useAnimations) are only active while the NPC is actually shown.
+ */
 export function PylonFarmerNPC(): React.JSX.Element | null {
  const mainState = useGameStore((state) => state.mainState);
  const step = useGameStore((state) => state.pylon.currentStep);
+
+  if (mainState !== "pylon") return null;
+  // Visible during narrative + at repair completion (hides during repair steps)
+  if (
+    step !== "arrived" &&
+    step !== "npc-return" &&
+    step !== "inspected" &&
+    step !== "done"
+  ) {
+    return null;
+  }
+
+  return <PylonFarmerNPCContent />;
+}
+
+// ─── Inner component — heavy hooks only run when NPC is mounted ──────────────
+function PylonFarmerNPCContent(): React.JSX.Element {
+  const step = useGameStore((state) => state.pylon.currentStep);
  const setMissionStep = useGameStore((state) => state.setMissionStep);
  const camera = useThree((state) => state.camera);

@@ -102,7 +125,6 @@ export function PylonFarmerNPC(): React.JSX.Element | null {
  const playPostRaiseAudioAndAdvance = useCallback(async () => {
    const manifest = await loadDialogueManifest();
    if (manifest) {
-      // "N'hésite pas, si tu as besoin d'autre chose !"
      const audio = await playDialogueById(
        manifest,
        PYLON_NARRATIVE_DIALOGUES.electricienneApresMontage,
@@ -134,6 +156,15 @@ export function PylonFarmerNPC(): React.JSX.Element | null {
      playAnim("walk");
    } else if (step === "inspected") {
      playAnim("idle");
+    } else if (step === "done") {
+      // NPC reappears at repair completion — position at the post-raise spot,
+      // facing the pylon, playing idle.
+      currentPosRef.current.set(...PYLON_FARMER_NPC_AFTER_POSITION_pylone_straight);
+      savedRotationYRef.current = faceToward(
+        currentPosRef.current,
+        PYLON_WORLD_POSITION,
+      );
+      playAnim("idle");
    }
  }, [step, playAnim]);

@@ -184,7 +215,7 @@ export function PylonFarmerNPC(): React.JSX.Element | null {
        );
      }
      group.position.copy(currentPosRef.current);
-    } else if (step === "inspected") {
+    } else if (step === "inspected" || step === "done") {
      group.position.set(...PYLON_FARMER_NPC_AFTER_POSITION_pylone_straight);
    } else if (isCompleted) {
      group.position.copy(currentPosRef.current);
@@ -211,10 +242,6 @@ export function PylonFarmerNPC(): React.JSX.Element | null {
  });
  /* eslint-enable react-hooks/immutability */

-  if (mainState !== "pylon") return null;
-  if (step !== "arrived" && step !== "npc-return" && step !== "inspected")
-    return null;
-
  return (
    <group ref={groupRef} position={PYLON_FARMER_NPC_POSITION}>
      <primitive object={model} />
@@ -225,6 +252,13 @@ export function PylonFarmerNPC(): React.JSX.Element | null {
          position={PYLON_FARMER_NPC_POSITION}
          radius={PYLON_NARRATIVE_INTERACT_RADIUS}
          onPress={() => {
+            // Turn to face the player the moment they engage the NPC
+            savedRotationYRef.current = faceToward(currentPosRef.current, [
+              camera.position.x,
+              camera.position.y,
+              camera.position.z,
+            ]);
+
            void (async () => {
              const manifest = await loadDialogueManifest();
              if (!manifest) {
@@ -19,9 +19,13 @@ export function PylonLightingEffect(): null {
  const mainState = useGameStore((state) => state.mainState);
  const step = useGameStore((state) => state.pylon.currentStep);

-  // True from "approaching" until narrator-outro (lighting resets before the outro audio)
+  // True from "approaching" until done — lighting starts reverting as soon as
+  // the repair is complete (powerup sfx plays at "done", outro dialogue at "narrator-outro").
  const isActive =
-    mainState === "pylon" && step !== "locked" && step !== "narrator-outro";
+    mainState === "pylon" &&
+    step !== "locked" &&
+    step !== "done" &&
+    step !== "narrator-outro";

  // Working THREE.Color instances — lerped every frame
  const ambientRef = useRef(new THREE.Color(LIGHTING_STATE.ambientColor));
@@ -1,3 +1,4 @@
+import { useEffect } from "react";
 import { useGameStore } from "@/managers/stores/useGameStore";
 import { useDialoguePlayback } from "@/hooks/gameplay/useDialoguePlayback";
 import { ZoneDetection } from "@/components/zone/ZoneDetection";
@@ -5,22 +6,122 @@ import { PylonFarmerNPC } from "@/components/gameplay/pylon/PylonFarmerNPC";
 import { PylonNarratorOutro } from "@/components/gameplay/pylon/PylonNarratorOutro";
 import { PYLON_APPROACH_ZONE, PYLON_ARRIVED_ZONE } from "@/data/gameplay/zones";
 import { PYLON_NARRATIVE_DIALOGUES } from "@/data/gameplay/pylonConfig";
+import { AudioManager } from "@/managers/AudioManager";
+import { loadDialogueManifest } from "@/utils/dialogues/loadDialogueManifest";
+import { playDialogueById } from "@/utils/dialogues/playDialogue";
+
+const PYLON_POWERDOWN_SFX = "/sounds/effect/generateur-powerdown.mp3";
+const PYLON_POWERUP_SFX = "/sounds/effect/generateur-powerup.mp3";

 export function PylonNarrativeFlow(): React.JSX.Element | null {
  const mainState = useGameStore((state) => state.mainState);
  const step = useGameStore((state) => state.pylon.currentStep);
  const setMissionStep = useGameStore((state) => state.setMissionStep);
+  const setCanMove = useGameStore((state) => state.setCanMove);

-  useDialoguePlayback({
-    enabled: mainState === "pylon" && step === "approaching",
-    dialogueId: PYLON_NARRATIVE_DIALOGUES.electricOutage,
-  });
+  // ── approaching : powerdown sfx → then electricOutage dialogue ────────────
+  useEffect(() => {
+    if (mainState !== "pylon" || step !== "approaching") return undefined;

+    let isCancelled = false;
+    setCanMove(false);
+
+    void (async () => {
+      // 1. Play the generator powerdown sound effect
+      const sfx = AudioManager.getInstance().playSound(
+        PYLON_POWERDOWN_SFX,
+        1,
+        { category: "sfx" },
+      );
+
+      // 2. Wait for it to finish (or skip if it can't load)
+      if (sfx) {
+        await new Promise<void>((resolve) => {
+          sfx.addEventListener("ended", () => resolve(), { once: true });
+          sfx.addEventListener("error", () => resolve(), { once: true });
+        });
+      }
+
+      if (isCancelled) return;
+
+      // 3. Play the narrative dialogue
+      const manifest = await loadDialogueManifest();
+      if (isCancelled || !manifest) {
+        setCanMove(true);
+        return;
+      }
+
+      const audio = await playDialogueById(
+        manifest,
+        PYLON_NARRATIVE_DIALOGUES.electricOutage,
+      );
+
+      if (isCancelled || !audio) {
+        setCanMove(true);
+        return;
+      }
+
+      audio.addEventListener(
+        "ended",
+        () => {
+          setCanMove(true);
+        },
+        { once: true },
+      );
+    })();
+
+    return () => {
+      isCancelled = true;
+      setCanMove(true);
+    };
+  }, [mainState, step, setCanMove]);
+
+  // ── arrived : searchCentral dialogue (unchanged) ──────────────────────────
  useDialoguePlayback({
    enabled: mainState === "pylon" && step === "arrived",
    dialogueId: PYLON_NARRATIVE_DIALOGUES.searchCentral,
  });

+  // ── inspected (demo skip) : jump straight to done after 5 s ─────────────
+  useEffect(() => {
+    if (mainState !== "pylon" || step !== "inspected") return undefined;
+
+    const timeoutId = window.setTimeout(() => {
+      setMissionStep("pylon", "done");
+    }, 5_000);
+
+    return () => {
+      window.clearTimeout(timeoutId);
+    };
+  }, [mainState, step, setMissionStep]);
+
+  // ── done : powerup sfx + lighting revert → auto-transition to narrator-outro
+  useEffect(() => {
+    if (mainState !== "pylon" || step !== "done") return undefined;
+
+    const sfx = AudioManager.getInstance().playSound(PYLON_POWERUP_SFX, 1, {
+      category: "sfx",
+    });
+
+    if (sfx) {
+      sfx.addEventListener(
+        "ended",
+        () => setMissionStep("pylon", "narrator-outro"),
+        { once: true },
+      );
+      sfx.addEventListener(
+        "error",
+        () => setMissionStep("pylon", "narrator-outro"),
+        { once: true },
+      );
+    } else {
+      // Fallback if the audio can't load
+      setMissionStep("pylon", "narrator-outro");
+    }
+
+    return undefined;
+  }, [mainState, step, setMissionStep]);
+
  // narrator-outro audio sequence + completeMission are handled in PylonNarratorOutro

  if (mainState !== "pylon") return null;
@@ -45,7 +146,12 @@ export function PylonNarrativeFlow(): React.JSX.Element | null {
    );
  }

-  if (step === "arrived" || step === "npc-return" || step === "inspected") {
+  if (
+    step === "arrived" ||
+    step === "npc-return" ||
+    step === "inspected" ||
+    step === "done"
+  ) {
    return <PylonFarmerNPC />;
  }

@@ -22,8 +22,6 @@ export function SiteCard({
    return "#b8b8b8";
  };

-  const borderColor = selected ? "#a8d5a2" : "rgba(255, 255, 255, 0.55)";
-
  const textColor = disabled ? "rgba(77, 77, 77, 0.72)" : "#4d4d4d";

  return (
@@ -41,7 +39,9 @@ export function SiteCard({
        height: isSituation
          ? "clamp(48px, 6vw, 60px)"
          : "clamp(140px, 18vw, 180px)",
-        border: `3px solid ${borderColor}`,
+        border: "3px solid rgba(255, 255, 255, 0.55)",
+        outline: selected ? "3px solid #a8d5a2" : "none",
+        outlineOffset: 0,
        background: getBackground(),
        cursor: disabled ? "not-allowed" : "pointer",
        display: "flex",
@@ -1,59 +1,133 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useEffect, useState } from "react";
 import { useGameStore } from "@/managers/stores/useGameStore";
 import { useSiteStore } from "@/managers/stores/useSiteStore";
+import { useSettingsStore } from "@/managers/stores/useSettingsStore";
 import { SiteButton } from "@/components/site/SiteButton";
 import { SITE_CONFIG } from "@/data/site/siteConfig";
 import { SITE_DIALOGUE_IDS } from "@/data/site/dialogueIds";
-import { loadDialogueManifest } from "@/utils/dialogues/loadDialogueManifest";
+import {
+  loadDialogueManifest,
+  loadDialogueSubtitleCues,
+} from "@/utils/dialogues/loadDialogueManifest";
 import {
  playDialogueById,
  stopCurrentDialogue,
 } from "@/utils/dialogues/playDialogue";

+const TYPEWRITER_CHAR_DELAY_MS = 70;
+// Fallback in case nothing else triggers the typewriter (audio failed to
+// load, no subtitles, "ended" never fires). Long enough not to fire
+// before the narration on a slow load.
+const AUDIO_END_FALLBACK_MS = 8000;
+
 /**
- * Screen 3: Name input
- * The displayed name is forced to SITE_CONFIG.presetPlayerName — the
- * field reveals one letter per keystroke until the preset name is complete.
+ * Screen 3: Name reveal
+ * The player's preset name is revealed letter-by-letter inside the input
+ * once the naming dialogue finishes playing. The confirm button stays
+ * locked until the reveal completes. No user typing — the input is
+ * read-only and just acts as a typewriter target.
 */
 export function SiteNamingScreen(): React.JSX.Element {
  const setStep = useSiteStore((state) => state.setStep);
  const setPlayerName = useGameStore((state) => state.setPlayerName);
-  const [charIndex, setCharIndex] = useState(0);
-  const inputRef = useRef<HTMLInputElement>(null);
+  const [revealedChars, setRevealedChars] = useState(0);
+  const [typewriterStarted, setTypewriterStarted] = useState(false);

  const presetPlayerName = SITE_CONFIG.presetPlayerName;
-  const displayValue = presetPlayerName.slice(0, charIndex);
-  const isComplete = charIndex >= presetPlayerName.length;
+  const displayValue = presetPlayerName.slice(0, revealedChars);
+  const isComplete = revealedChars >= presetPlayerName.length;

+  // Play the dialogue, then trigger the typewriter so it FINISHES at the
+  // same moment the narration ends. We compute that moment from the SRT
+  // cues: the last cue's endTime is where the narrator stops speaking,
+  // so we start typing `typewriterDuration` before that.
  useEffect(() => {
    let cancelled = false;
+    let audioElement: HTMLAudioElement | null = null;
+    let onTimeUpdate: (() => void) | null = null;
+    let fallbackTimer: ReturnType<typeof setTimeout> | null = null;
+
+    const start = (): void => {
+      if (cancelled) return;
+      setTypewriterStarted(true);
+    };
+
+    const typewriterDurationSec =
+      (TYPEWRITER_CHAR_DELAY_MS * presetPlayerName.length) / 1000;

    void (async () => {
      const manifest = await loadDialogueManifest();
-      if (cancelled || !manifest) return;
-      await playDialogueById(manifest, SITE_DIALOGUE_IDS.naming);
+      if (cancelled) return;
+      if (!manifest) {
+        start();
+        return;
+      }
+
+      // Resolve the dialogue + its SRT cues for the active subtitle language.
+      const dialogue = manifest.dialogues.find(
+        (item) => item.id === SITE_DIALOGUE_IDS.naming,
+      );
+      const language = useSettingsStore.getState().subtitleLanguage;
+      const subtitleData = dialogue
+        ? await loadDialogueSubtitleCues(manifest, dialogue, language)
+        : null;
+      if (cancelled) return;
+
+      audioElement = await playDialogueById(manifest, SITE_DIALOGUE_IDS.naming);
+      if (cancelled) return;
+      if (!audioElement) {
+        start();
+        return;
+      }
+
+      const lastCue = subtitleData?.cues[subtitleData.cues.length - 1];
+      if (lastCue) {
+        // Trigger so the typewriter ends at the narration's end.
+        const audio = audioElement;
+        const triggerAt = Math.max(0, lastCue.endTime - typewriterDurationSec);
+        onTimeUpdate = (): void => {
+          if (audio.currentTime >= triggerAt) {
+            audio.removeEventListener("timeupdate", onTimeUpdate!);
+            start();
+          }
+        };
+        audio.addEventListener("timeupdate", onTimeUpdate);
+      } else {
+        // No SRT data — fall back to the audio "ended" event.
+        audioElement.addEventListener("ended", start, { once: true });
+      }
+
+      fallbackTimer = setTimeout(start, AUDIO_END_FALLBACK_MS);
    })();

    return () => {
      cancelled = true;
+      if (fallbackTimer !== null) clearTimeout(fallbackTimer);
+      if (audioElement) {
+        if (onTimeUpdate) {
+          audioElement.removeEventListener("timeupdate", onTimeUpdate);
+        }
+        audioElement.removeEventListener("ended", start);
+      }
      stopCurrentDialogue();
    };
-  }, []);
+  }, [presetPlayerName.length]);

+  // Reveal the preset name one character at a time once the typewriter
+  // has been triggered.
  useEffect(() => {
-    inputRef.current?.focus();
-  }, []);
-
-  const handleNameChange = useCallback(
-    (event: React.ChangeEvent<HTMLInputElement>): void => {
-      const nextLength = Math.min(
-        event.target.value.length,
-        presetPlayerName.length,
-      );
-      setCharIndex(nextLength);
-    },
-    [presetPlayerName.length],
-  );
+    if (!typewriterStarted) return;
+    const interval = setInterval(() => {
+      setRevealedChars((current) => {
+        if (current >= presetPlayerName.length) {
+          clearInterval(interval);
+          return current;
+        }
+        return current + 1;
+      });
+    }, TYPEWRITER_CHAR_DELAY_MS);
+    return () => clearInterval(interval);
+  }, [typewriterStarted, presetPlayerName.length]);

  const handleConfirm = (): void => {
    if (isComplete) {
@@ -98,17 +172,16 @@ export function SiteNamingScreen(): React.JSX.Element {
            margin: 0,
          }}
        >
-          Quel est votre prénom ?
+          Je suis…
        </h2>

        <input
-          ref={inputRef}
          type="text"
          value={displayValue}
-          onChange={handleNameChange}
-          placeholder="Écrivez votre prénom ici"
+          readOnly
+          tabIndex={-1}
          aria-labelledby="player-name-label"
-          aria-describedby="player-name-hint"
+          aria-live="polite"
          autoComplete="off"
          style={{
            display: "flex",
@@ -122,30 +195,12 @@ export function SiteNamingScreen(): React.JSX.Element {
            background: "#D9D9D9",
            outline: "none",
            color: "#333",
-            caretColor: "#333",
            fontFamily: "Inter, system-ui, sans-serif",
            fontSize: "clamp(16px, 2.5vw, 20px)",
            textAlign: "left",
            boxSizing: "border-box",
          }}
        />
-        <span
-          id="player-name-hint"
-          style={{
-            position: "absolute",
-            width: 1,
-            height: 1,
-            padding: 0,
-            margin: -1,
-            overflow: "hidden",
-            clip: "rect(0, 0, 0, 0)",
-            whiteSpace: "nowrap",
-            border: 0,
-          }}
-        >
-          Votre personnage s&apos;appelle {presetPlayerName}. Tapez{" "}
-          {presetPlayerName.length} caractères pour révéler son nom.
-        </span>
      </div>

      <SiteButton
@@ -204,7 +204,7 @@ export function RepairGame({
            onComplete={() => setMissionStep(mission, "done")}
          />
        ) : null}
-        {step === "done" ? (
+        {step === "done" && mission !== "pylon" ? (
          <RepairCompletionStep
            config={config}
            onComplete={() => completeMission(mission)}
@@ -4,8 +4,11 @@ import { GameSettingsMenu } from "@/components/ui/GameSettingsMenu";
 import { HandTrackingFallback } from "@/components/ui/HandTrackingFallback";
 import { HandTrackingVisualizer } from "@/components/ui/HandTrackingVisualizer";
 import { InteractPrompt } from "@/components/ui/InteractPrompt";
+import { OutroVideoOverlay } from "@/components/ui/OutroVideoOverlay";
 import { Subtitles } from "@/components/ui/Subtitles";
 import { TalkieDialogueOverlay } from "@/components/ui/TalkieDialogueOverlay";
+import { HandTrackingTutorial } from "@/components/ui/tutorial/HandTrackingTutorial";
+import { MovementTutorial } from "@/components/ui/tutorial/MovementTutorial";

 export function GameUI(): React.JSX.Element {
  return (
@@ -15,9 +18,12 @@ export function GameUI(): React.JSX.Element {
      <InteractPrompt />
      <HandTrackingVisualizer />
      <HandTrackingFallback />
+      <MovementTutorial />
+      <HandTrackingTutorial />
      <Subtitles />
      <TalkieDialogueOverlay />
      <GameSettingsMenu />
+      <OutroVideoOverlay />
    </>
  );
 }
@@ -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}%`,
@@ -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>
@@ -0,0 +1,55 @@
+import { useEffect, useRef, useState } from "react";
+
+const OUTRO_VIDEO_SRC = "/cinematics/outro.mp4";
+
+/**
+ * Full-screen video overlay that plays once after the outro drone-shot
+ * cinematic ends. Triggered by the "outro-cinematic-complete" window event
+ * dispatched from GameCinematics.tsx.
+ */
+export function OutroVideoOverlay(): React.JSX.Element | null {
+  const [visible, setVisible] = useState(false);
+  const videoRef = useRef<HTMLVideoElement>(null);
+
+  useEffect(() => {
+    function handleCinematicComplete(): void {
+      setVisible(true);
+    }
+
+    window.addEventListener("outro-cinematic-complete", handleCinematicComplete);
+    return () => {
+      window.removeEventListener(
+        "outro-cinematic-complete",
+        handleCinematicComplete,
+      );
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!visible) return;
+    void videoRef.current?.play();
+  }, [visible]);
+
+  if (!visible) return null;
+
+  return (
+    <div
+      style={{
+        position: "fixed",
+        inset: 0,
+        zIndex: 10000,
+        background: "#000",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+      }}
+    >
+      <video
+        ref={videoRef}
+        src={OUTRO_VIDEO_SRC}
+        style={{ width: "100%", height: "100%", objectFit: "cover" }}
+        playsInline
+      />
+    </div>
+  );
+}
@@ -0,0 +1,59 @@
+import { useEffect, useState } from "react";
+import { Hand } from "lucide-react";
+import { useGameStore } from "@/managers/stores/useGameStore";
+import { useHandTrackingSnapshot } from "@/hooks/handTracking/useHandTrackingSnapshot";
+import type { MissionStep } from "@/types/gameplay/repairMission";
+import { TutorialOverlay } from "@/components/ui/tutorial/TutorialOverlay";
+
+// Repair steps where the hand-tracking tutorial is allowed to display. Covers
+// the no-hand-tracking phase (fragmented, scanning) and the first hand-driven
+// step (inspected) — beyond that the player has presumably learned.
+const HAND_TUTORIAL_STEPS: ReadonlySet<MissionStep> = new Set([
+  "fragmented",
+  "scanning",
+  "inspected",
+]);
+
+/**
+ * First-time hand-tracking tutorial. Visible during the early ebike repair
+ * steps until MediaPipe actually detects a hand on screen. Once dismissed it
+ * stays dismissed for the session.
+ */
+export function HandTrackingTutorial(): React.JSX.Element | null {
+  const mainState = useGameStore((state) => state.mainState);
+  const ebikeStep = useGameStore((state) => state.ebike.currentStep);
+  const { hands, status } = useHandTrackingSnapshot();
+  const [dismissed, setDismissed] = useState(false);
+
+  const isInShowWindow =
+    mainState === "ebike" && HAND_TUTORIAL_STEPS.has(ebikeStep);
+  const handsDetected = status !== "idle" && hands.length > 0;
+
+  useEffect(() => {
+    if (handsDetected && !dismissed) {
+      // Sync the persistent dismissal flag with an external signal (the
+      // hand-tracking snapshot). Same shape as the resync pattern used
+      // elsewhere in the repo (e.g. PylonDownedPylon).
+      // eslint-disable-next-line react-hooks/set-state-in-effect
+      setDismissed(true);
+    }
+  }, [handsDetected, dismissed]);
+
+  if (!isInShowWindow || dismissed) return null;
+
+  return (
+    <TutorialOverlay
+      icon={
+        <div className="tutorial-overlay__hands">
+          <Hand size={96} strokeWidth={1.5} />
+          <Hand
+            size={96}
+            strokeWidth={1.5}
+            style={{ transform: "scaleX(-1)" }}
+          />
+        </div>
+      }
+      text="Placez vos mains devant la caméra pour attraper les pièces. Sinon, utilisez la souris."
+    />
+  );
+}
@@ -0,0 +1,57 @@
+import { useEffect, useState } from "react";
+import { useGameStore } from "@/managers/stores/useGameStore";
+import type { GameStep } from "@/types/game";
+import { TutorialOverlay } from "@/components/ui/tutorial/TutorialOverlay";
+
+const MOVEMENT_KEYS = new Set(["z", "q", "s", "d"]);
+// Intro steps where the movement tutorial is allowed to display. From the
+// reveal fade through the free-walk window before the ebike mount.
+const MOVEMENT_TUTORIAL_STEPS: ReadonlySet<GameStep> = new Set([
+  "reveal",
+  "await-ebike-mount",
+]);
+
+function KeyCap({ label }: { label: string }): React.JSX.Element {
+  return <span className="tutorial-overlay__keycap">{label}</span>;
+}
+
+/**
+ * First-time movement tutorial. Visible during the intro reveal and the
+ * walk-around step before the ebike mount, until the player presses any
+ * of Z, Q, S, D. Once dismissed it stays dismissed for the session.
+ */
+export function MovementTutorial(): React.JSX.Element | null {
+  const introStep = useGameStore((state) => state.intro.currentStep);
+  const [dismissed, setDismissed] = useState(false);
+
+  const isInShowWindow = MOVEMENT_TUTORIAL_STEPS.has(introStep);
+
+  useEffect(() => {
+    if (dismissed) return;
+    function onKeyDown(event: KeyboardEvent): void {
+      if (MOVEMENT_KEYS.has(event.key.toLowerCase())) {
+        setDismissed(true);
+      }
+    }
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [dismissed]);
+
+  if (!isInShowWindow || dismissed) return null;
+
+  return (
+    <TutorialOverlay
+      icon={
+        <div className="tutorial-overlay__keyboard">
+          <span aria-hidden="true" />
+          <KeyCap label="Z" />
+          <span aria-hidden="true" />
+          <KeyCap label="Q" />
+          <KeyCap label="S" />
+          <KeyCap label="D" />
+        </div>
+      }
+      text="Utilisez le clavier et la souris pour vous déplacer."
+    />
+  );
+}
@@ -0,0 +1,23 @@
+interface TutorialOverlayProps {
+  icon: React.ReactNode;
+  text: string;
+}
+
+/**
+ * Full-screen instructional overlay shown during onboarding moments
+ * (movement intro, hand-tracking intro, ...). Pure presentation: parent
+ * decides when to mount it and when to unmount it.
+ */
+export function TutorialOverlay({
+  icon,
+  text,
+}: TutorialOverlayProps): React.JSX.Element {
+  return (
+    <div className="tutorial-overlay" aria-live="polite">
+      <div className="tutorial-overlay__panel">
+        <div className="tutorial-overlay__icon">{icon}</div>
+        <p className="tutorial-overlay__text">{text}</p>
+      </div>
+    </div>
+  );
+}
@@ -15,11 +15,11 @@ export const EBIKE_DROP_PLAYER_TRANSFORM: CameraTransform = {
  rotation: [0, 0, 0],
 };

-export const EBIKE_WORLD_POSITION: Vector3Tuple = [65, 0.8, 72];
+export const EBIKE_WORLD_POSITION: Vector3Tuple = [68, 0.8, 65];
 export const EBIKE_WORLD_ROTATION_Y = -2.5;
 export const EBIKE_WORLD_SCALE = 0.35;

-export const EBIKE_INTRO_BREAKDOWN_DISTANCE = 15;
+export const EBIKE_INTRO_BREAKDOWN_DISTANCE = 50;
 export const EBIKE_BREAKDOWN_DIALOGUE_DELAY_MS = 250;

 export const EBIKE_ACCELERATION_DURATION_MS = 2000;
@@ -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 {
@@ -1811,14 +1812,82 @@ canvas {
  pointer-events: none;
 }

+.tutorial-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 14;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: rgba(96, 165, 250, 0.55);
+  pointer-events: none;
+}
+
+.tutorial-overlay__panel {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 36px;
+  padding: 56px 72px;
+  max-width: 640px;
+  background: transparent;
+  border: 2px solid #1e3a8a;
+  border-radius: 24px;
+  color: #1e3a8a;
+}
+
+.tutorial-overlay__icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.tutorial-overlay__text {
+  font-family: var(--font-body);
+  font-size: 1.1rem;
+  font-weight: 500;
+  line-height: 1.45;
+  text-align: center;
+  margin: 0;
+}
+
+.tutorial-overlay__keyboard {
+  display: grid;
+  grid-template-columns: repeat(3, 64px);
+  gap: 8px;
+  font-family: var(--font-primary);
+}
+
+.tutorial-overlay__keycap {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 64px;
+  height: 64px;
+  background: #e0f2fe;
+  border: 2px solid #1e3a8a;
+  border-radius: 10px;
+  font-size: 1.6rem;
+  font-weight: 700;
+  color: #1e3a8a;
+}
+
+.tutorial-overlay__hands {
+  display: flex;
+  align-items: center;
+  gap: 32px;
+  color: #1e3a8a;
+}
+
 .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));
 }

@@ -161,7 +161,10 @@ function completePylonState(state: GameState): GameStateUpdate {
    },
    farm: {
      ...state.farm,
-      currentStep: "waiting",
+      // Farm starts at "locked" so FarmNarrativeFlow can auto-transition
+      // to "electricienne_history" and play the intro audio before the
+      // repair game begins.
+      currentStep: "locked",
    },
  };
 }
@@ -100,7 +100,8 @@ export type MissionStep =
  | "repairing"
  | "reassembling"
  | "done"
-  | "narrator-outro";
+  | "narrator-outro"
+  | "electricienne_history";

 export const PYLON_NARRATIVE_STEPS = [
  "approaching",
@@ -109,6 +110,12 @@ export const PYLON_NARRATIVE_STEPS = [
  "narrator-outro",
 ] as const;

+/** Farm-specific steps that bypass the repair-game flow. */
+export const FARM_NARRATIVE_STEPS = [
+  "locked",
+  "electricienne_history",
+] as const;
+
 export const REPAIR_GAME_STEPS = [
  "waiting",
  "inspected",
@@ -123,6 +130,10 @@ export function isPylonNarrativeStep(step: MissionStep): boolean {
  return (PYLON_NARRATIVE_STEPS as readonly MissionStep[]).includes(step);
 }

+export function isFarmNarrativeStep(step: MissionStep): boolean {
+  return (FARM_NARRATIVE_STEPS as readonly MissionStep[]).includes(step);
+}
+
 export function isRepairGameStep(step: MissionStep): boolean {
  return (REPAIR_GAME_STEPS as readonly MissionStep[]).includes(step);
 }
@@ -11,6 +11,8 @@ export interface MapNode {
 }

 export interface MapNodeInstanceTransform {
+  /** Node id from map.json — preserved so specific instances can be excluded at runtime. */
+  id?: string;
  position: Vector3Tuple;
  rotation: Vector3Tuple;
  scale: Vector3Tuple;
@@ -4,6 +4,7 @@ export function mapNodeToInstanceTransform(
  node: MapNode,
 ): MapNodeInstanceTransform {
  return {
+    id: node.id,
    position: node.position,
    rotation: node.rotation,
    scale: node.scale,
@@ -118,7 +118,15 @@ function playCinematic(
    onUpdate: () => camera.lookAt(target),
    onComplete: () => {
      timelineRef.current = null;
-      useGameStore.getState().setCinematicPlaying(false);
+      // During the outro the camera is intentionally left at its final
+      // position — don't release cinematic lock so the player camera system
+      // can't snap it back to the player's eye position.
+      const { mainState } = useGameStore.getState();
+      if (mainState === "outro") {
+        window.dispatchEvent(new CustomEvent("outro-cinematic-complete"));
+      } else {
+        useGameStore.getState().setCinematicPlaying(false);
+      }
    },
  });

@@ -1,14 +1,43 @@
 import { useEffect } from "react";
 import { AudioManager } from "@/managers/AudioManager";
+import { useGameStore } from "@/managers/stores/useGameStore";
+import type { MissionStep } from "@/types/gameplay/repairMission";

 const GAME_MUSIC_PATH = "/sounds/musique/musique-jeu.mp3";
-const GAME_MUSIC_VOLUME = 0.33;
+const REPAIR_MUSIC_PATH = "/sounds/musique/musique-reparation.mp3";
+const MUSIC_VOLUME = 0.33;
+
+// Steps during which the repair mini-game owns the experience.
+// Triggered when any mission (ebike / pylon / farm) is in this range.
+const REPAIR_MUSIC_STEPS: ReadonlySet<MissionStep> = new Set([
+  "inspected",
+  "fragmented",
+  "scanning",
+  "repairing",
+  "reassembling",
+  "done",
+]);

 export function GameMusic(): null {
+  const ebikeStep = useGameStore((state) => state.ebike.currentStep);
+  const pylonStep = useGameStore((state) => state.pylon.currentStep);
+  const farmStep = useGameStore((state) => state.farm.currentStep);
+
+  const inRepair =
+    REPAIR_MUSIC_STEPS.has(ebikeStep) ||
+    REPAIR_MUSIC_STEPS.has(pylonStep) ||
+    REPAIR_MUSIC_STEPS.has(farmStep);
+
  useEffect(() => {
    const audio = AudioManager.getInstance();
-    audio.playMusic(GAME_MUSIC_PATH, GAME_MUSIC_VOLUME);
+    audio.playMusic(
+      inRepair ? REPAIR_MUSIC_PATH : GAME_MUSIC_PATH,
+      MUSIC_VOLUME,
+    );
+  }, [inRepair]);

+  useEffect(() => {
+    const audio = AudioManager.getInstance();
    return () => {
      audio.stopMusic();
    };
@@ -2,6 +2,7 @@ import { Ebike } from "@/components/ebike/Ebike";
 import { InteractableObject } from "@/components/three/interaction/InteractableObject";
 import { RepairFocusBubble } from "@/components/three/gameplay/RepairFocusBubble";
 import { RepairGame } from "@/components/three/gameplay/RepairGame";
+import { FarmNarrativeFlow } from "@/components/gameplay/farm/FarmNarrativeFlow";
 import { PylonDownedPylon } from "@/components/gameplay/pylon/PylonDownedPylon";
 import { PylonLightingEffect } from "@/components/gameplay/pylon/PylonLightingEffect";
 import { PylonNarrativeFlow } from "@/components/gameplay/pylon/PylonNarrativeFlow";
@@ -19,7 +20,10 @@ import {
 import { useGameStore } from "@/managers/stores/useGameStore";
 import { useRepairFocusStore } from "@/managers/stores/useRepairFocusStore";
 import { useRepairMissionAnchorStore } from "@/managers/stores/useRepairMissionAnchorStore";
-import { isPylonNarrativeStep } from "@/types/gameplay/repairMission";
+import {
+  isFarmNarrativeStep,
+  isPylonNarrativeStep,
+} from "@/types/gameplay/repairMission";
 import type { RepairMissionTriggerConfig } from "@/types/gameplay/repairMission";
 import type { Vector3Tuple } from "@/types/three/three";
 import { getRepairMissionPosition } from "@/utils/gameplay/repairMissionPosition";
@@ -90,8 +94,12 @@ export function GameStageContent(): React.JSX.Element {
  const anchors = useRepairMissionAnchorStore((state) => state.anchors);
  const repairFocusActive = useRepairFocusStore((state) => state.active);

+  const farmStep = useGameStore((state) => state.farm.currentStep);
+
  const pylonInNarrative =
    mainState === "pylon" && isPylonNarrativeStep(pylonStep);
+  const farmInNarrative =
+    mainState === "farm" && isFarmNarrativeStep(farmStep);

  return (
    <>
@@ -106,10 +114,12 @@ export function GameStageContent(): React.JSX.Element {
        </>
      ) : null}
      {mainState === "pylon" ? <PylonNarrativeFlow /> : null}
+      {mainState === "farm" ? <FarmNarrativeFlow /> : null}
      {REPAIR_MISSION_POSITION_ENTRIES.map(({ mission }) => {
        const position = getRepairMissionPosition(mission, anchors);
        if (!position) return null;
        if (mission === "pylon" && pylonInNarrative) return null;
+        if (mission === "farm" && farmInNarrative) return null;
        return (
          <RepairGame key={mission} mission={mission} position={position} />
        );
@@ -271,7 +271,7 @@ export function TestMap({ onOctreeReady }: TestMapProps): React.JSX.Element {
        </mesh>
        */}
        {/* GPS Map screen plane */}
-        <group position={[0, 0, 0.06]}>
+        <group position={[0, -8, 0.06]}>
          <EbikeGPSMap
            width={4}
            height={4}
@@ -20,6 +20,7 @@ import {
  isMapModelVisible,
  useMapPerformanceStore,
 } from "@/managers/stores/useMapPerformanceStore";
+import { useGameStore } from "@/managers/stores/useGameStore";
 import { InstancedMapAsset } from "@/world/map-instancing/InstancedMapAsset";
 import {
  MAP_INSTANCING_ASSETS,
@@ -27,6 +28,8 @@ import {
  type MapInstancingAssetConfig,
  type MapInstancingAssetType,
 } from "@/data/world/mapInstancingConfig";
+import { REPAIR_MISSION_ANCHOR_IDS } from "@/data/gameplay/repairMissionAnchors";
+import { isRepairGameStep } from "@/types/gameplay/repairMission";
 import { useMapInstancingData } from "@/hooks/world/useMapInstancingData";
 import type { MapAssetInstance } from "@/types/map/mapScene";
 import type { GraphicsPreset } from "@/data/world/graphicsConfig";
@@ -146,6 +149,8 @@ export function MapInstancingSystem({
  const groups = useMapPerformanceStore((state) => state.groups);
  const models = useMapPerformanceStore((state) => state.models);
  const { data, isLoading } = useMapInstancingData();
+  const mainState = useGameStore((state) => state.mainState);
+  const pylonStep = useGameStore((state) => state.pylon.currentStep);
  const streamingEnabled =
    streaming &&
    CHUNK_CONFIG.enabled &&
@@ -153,6 +158,15 @@ export function MapInstancingSystem({
    sceneMode === "game" &&
    cameraMode === "player";

+  // During the pylon narrative phase (before the pylon is raised), hide the
+  // repair:pylon instanced mesh so the PylonDownedPylon component takes its place.
+  // Once the pylon is raised (repair-game steps), restore it so the normal model
+  // appears upright in the world while the repair mini-game runs.
+  const hidePylonAnchorId =
+    mainState === "pylon" && !isRepairGameStep(pylonStep)
+      ? REPAIR_MISSION_ANCHOR_IDS.pylon
+      : undefined;
+
  const chunks = useMemo(() => {
    if (!data) return [];

@@ -168,12 +182,18 @@ export function MapInstancingSystem({
        return [];
      }

-      const instances = data.get(type);
+      let instances = data.get(type);
      if (!instances || instances.length === 0) return [];

+      // Filter out the repair-mission pylon instance during the narrative phase
+      if (hidePylonAnchorId && config.mapName === "pylone") {
+        instances = instances.filter((inst) => inst.id !== hidePylonAnchorId);
+        if (instances.length === 0) return [];
+      }
+
      return createMapAssetChunks(type, config, instances);
    });
-  }, [data, groups, models, onlyMapName]);
+  }, [data, groups, models, onlyMapName, hidePylonAnchorId]);

  const visibleChunks = useVisibleWorldChunks(chunks, streamingEnabled, {
    loadRadius: graphicsPresetConfig.chunkLoadRadius,
@@ -363,7 +363,11 @@ export function PlayerController({
    }

    _wishDir.set(0, 0, 0);
-    if (!isEbikeBreakdown) {
+    // Block drive input only when still on the bike during breakdown.
+    // Once auto-dismounted (movementMode === "walk"), the player must
+    // remain free to walk around even though ebikeBreakdownActive is true.
+    const blockDriveInput = isEbikeMounted && isEbikeBreakdown;
+    if (!blockDriveInput) {
      if (keys.current.forward) _wishDir.add(_forward);
      if (keys.current.backward) _wishDir.sub(_forward);
      if (!isEbikeMounted) {
Author	SHA1	Message	Date
math-pixel	1325b7b2af	Merge branch 'develop' into feat/polish-mission-2 🔍 Lint / 🪄 Check lint (pull_request) Has been cancelled Details 🔍 Lint / 🎨 Check format (pull_request) Has been cancelled Details 🔍 Lint / 🔎 Typecheck (pull_request) Has been cancelled Details 📊 Quality / 🔒 Security Audit (pull_request) Has been cancelled Details 📊 Quality / 📋 Dependency Freshness (pull_request) Has been cancelled Details 📊 Quality / 📦 Bundle Size (pull_request) Has been cancelled Details 🔍 Lint / 🏗 Build (pull_request) Has been cancelled Details	2026-06-03 02:02:37 +02:00
Tom Boullay	c2f55e3a2f	feat(site): sync naming typewriter to last subtitle cue 🔍 Lint / 🪄 Check lint (push) Has been cancelled Details 🔍 Lint / 🎨 Check format (push) Has been cancelled Details 🔍 Lint / 🔎 Typecheck (push) Has been cancelled Details 📊 Quality / 🔒 Security Audit (push) Has been cancelled Details 📊 Quality / 📋 Dependency Freshness (push) Has been cancelled Details 📊 Quality / 📦 Bundle Size (push) Has been cancelled Details 🔍 Lint / 🏗 Build (push) Has been cancelled Details Replace the audio "ended"-based trigger with an SRT-driven one: the typewriter now starts (lastCue.endTime - typewriterDuration) seconds into the dialogue so the final letter lands at the moment the narrator finishes speaking. Char delay shortened from 110ms to 70ms for a snappier reveal. Fallbacks: audio "ended" when no SRT, 8s absolute timer otherwise.	2026-06-03 01:56:14 +02:00
math-pixel	63c2b294c1	Merge branch 'develop' into feat/polish-mission-2 🔍 Lint / 🪄 Check lint (pull_request) Has been cancelled Details 🔍 Lint / 🎨 Check format (pull_request) Has been cancelled Details 🔍 Lint / 🔎 Typecheck (pull_request) Has been cancelled Details 📊 Quality / 🔒 Security Audit (pull_request) Has been cancelled Details 📊 Quality / 📋 Dependency Freshness (pull_request) Has been cancelled Details 📊 Quality / 📦 Bundle Size (pull_request) Has been cancelled Details 🔍 Lint / 🏗 Build (pull_request) Has been cancelled Details	2026-06-03 01:52:20 +02:00
Tom Boullay	62d0dcf531	upatde; config ebike 🔍 Lint / 🪄 Check lint (push) Has been cancelled Details 🔍 Lint / 🎨 Check format (push) Has been cancelled Details 🔍 Lint / 🔎 Typecheck (push) Has been cancelled Details 📊 Quality / 🔒 Security Audit (push) Has been cancelled Details 📊 Quality / 📋 Dependency Freshness (push) Has been cancelled Details 📊 Quality / 📦 Bundle Size (push) Has been cancelled Details 🔍 Lint / 🏗 Build (push) Has been cancelled Details	2026-06-03 01:48:31 +02:00
Tom Boullay	c75c4e0be6	fix(site): keep white card border visible when selected Replace the border swap with an outer green outline so the white border stays in place. Selected = white border + green outline, unselected = white border only. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-06-03 01:46:13 +02:00
math-pixel	10b0d4fc16	outro anim + vid	2026-06-03 01:45:43 +02:00
Tom Boullay	5f113cbba4	feat(tutorial): add movement and hand-tracking onboarding overlays Mount two first-time tutorial overlays driven by the game state machine: - MovementTutorial: visible during the intro reveal and the free-walk step before the ebike mount, dismissed on the first Z/Q/S/D keydown. - HandTrackingTutorial: visible during the early ebike repair steps (fragmented, scanning, inspected), dismissed when MediaPipe detects any hand on screen. Both share a generic TutorialOverlay shell (transparent panel, dark blue border, lucide-react Hand / inline ZQSD keycap icons, centered text). The overlay sits at z-index 14, behind Subtitles (15) and the talkie overlay (16), so dialogue/subtitle UI stays in front. Dismissals stay persistent for the session: keyboard-triggered uses event-handler setState; hand-detection uses a guarded effect-driven setState (same pattern as PylonDownedPylon resync). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-06-03 01:43:25 +02:00
math-pixel	b1037d5107	split narrator srt	2026-06-03 01:01:48 +02:00
Tom Boullay	1cc3b0e47e	feat(audio): swap to repair music while a mission is in repair flow Switch background music to musique-reparation.mp3 whenever any mission (ebike / pylon / farm) is in the repair mini-game step range (inspected → done) and back to musique-jeu.mp3 once the mission leaves that range. Reuses AudioManager.playMusic which handles the swap cleanly when the path changes.	2026-06-03 01:00:29 +02:00
Tom Boullay	00b1ff9e93	fix(ebike): unlock walking during breakdown + hide interact prompt + 450m ride Three fixes for the ebike-breakdown substep: 1. PlayerController: the previous `if (!isEbikeBreakdown)` guard zeroed _wishDir for everyone during breakdown, including the player after they had been auto-dismounted to walk mode. Narrow the guard to `isEbikeMounted && isEbikeBreakdown` so the bike stops accepting drive input but the player on foot can move. 2. Ebike: track `window.ebikeBreakdownActive` in component state and hide the InteractableObject (and therefore the interact prompt UI) while the breakdown sequence is active. The bike must read as inert and non-interactive while the panne dialogue plays and during the auto-dismount that follows. 3. ebikeConfig: bump EBIKE_INTRO_BREAKDOWN_DISTANCE from 15 m to 450 m so the panne triggers after a real ride instead of a few meters from the parked spawn.	2026-06-03 00:46:30 +02:00
Tom Boullay	675a45f02b	Update ebikeConfig.ts	2026-06-03 00:44:00 +02:00
Tom Boullay	bbae199105	docs(handtracking): document SVG-primary path and isFist origin Reflect the current runtime in docs/technical/hand-tracking.md: - SVG visualizer is now the primary hand UI; the 3D glove is opt-in via the Show Model debug toggle. - Reorder the runtime flow to put HandTrackingVisualizer before HandTrackingGlove and make explicit that grab, fist detection, SVG and optional 3D glove are independent consumers of the same landmark snapshot. - New Fist Detection section showing how isFist() in browserHandTracking.ts derives the flag from landmarks alone (palm centroid + 4 fingertip distances), and confirming GrabbableObject reads that flag directly - no glove involvement. - Describe the SVG visualizer styling and the feMorphology outline trick. - Mark HandTrackingFallback and the gant_l/_pad assets as legacy in the limitations list. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-06-03 00:42:14 +02:00
Tom Boullay	c4cad629c9	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>	2026-06-03 00:42:05 +02:00
math-pixel	18fb5e39e9	edit electricienne + poto	2026-06-03 00:05:07 +02:00