add zustand game state

docs/technical/zustand.md

@@ -0,0 +1,133 @@
+# Zustand Game State
+
+This document explains how Zustand is used in the current project.
+
+## Why Zustand Exists Here
+
+The project needs one shared source of truth for the player's progression through the experience.
+
+The current progression is split into main states:
+
+| Main state | Role                            |
+| ---------- | ------------------------------- |
+| `intro`    | Onboarding and opening sequence |
+| `bike`     | E-bike repair sequence          |
+| `pylone`   | Power grid sequence             |
+| `ferme`    | Vertical farm sequence          |
+| `outro`    | Ending sequence                 |
+
+Each main state can also own smaller sub state, such as the current mission step, dialogue audio, or completion flags.
+
+Zustand is useful because React and React Three Fiber components can subscribe only to the state slice they need. When that slice changes, only the subscribed components re-render.
+
+## Store Location
+
+The game progression store lives here:
+
+```txt
+src/managers/stores/useGameStore.ts
+```
+
+The store is placed under `src/managers/stores/` because it belongs to the gameplay orchestration layer, not to a specific visual component.
+
+## Current Shape
+
+The store exposes:
+
+- `mainState`: the active game phase
+- `intro`: intro-specific state
+- `bike`: e-bike mission state
+- `pylone`: power grid mission state
+- `ferme`: farm mission state
+- `outro`: ending state
+- actions for direct updates and progression updates
+
+The mission steps currently use this sequence:
+
+```ts
+"locked" | "waiting" | "inspect" | "scanning" | "repairing" | "done";
+```
+
+## Reading State In Components
+
+Use selectors to read only what the component needs.
+
+```tsx
+import { useGameStore } from "@/managers/stores/useGameStore";
+
+export function Example(): React.JSX.Element {
+  const mainState = useGameStore((state) => state.mainState);
+
+  return <p>Current state: {mainState}</p>;
+}
+```
+
+This is better than reading the whole store, because the component re-renders only when `mainState` changes.
+
+## Updating State
+
+Prefer explicit actions from the store.
+
+```ts
+const advanceGameState = useGameStore((state) => state.advanceGameState);
+
+advanceGameState();
+```
+
+For development and debug tooling, direct setters also exist:
+
+```ts
+const setMainState = useGameStore((state) => state.setMainState);
+
+setMainState("bike");
+```
+
+Direct setters are useful for debug panels, but production gameplay should prefer business actions such as `advanceGameState`, `completeBike`, or `completePylone`.
+
+## World Integration
+
+`src/world/GameStageContent.tsx` subscribes to `mainState` and mounts stage-specific content.
+
+That means the scene can progressively move toward this pattern:
+
+```tsx
+switch (mainState) {
+  case "intro":
+    return <IntroContent />;
+  case "bike":
+    return <BikeContent />;
+  case "pylone":
+    return <PyloneContent />;
+  case "ferme":
+    return <FarmContent />;
+  case "outro":
+    return <OutroContent />;
+}
+```
+
+In React Three Fiber, mounting and unmounting JSX controls what appears in the Three.js scene. When a state-specific component disappears from JSX, React removes it from the scene.
+
+## UI Integration
+
+`src/components/ui/GameUI.tsx` groups the HTML overlays used by the playable route.
+
+Current overlays:
+
+- `GameStateHUD`: debug-only progression panel shown with `?debug`
+- `Crosshair`: player aiming helper
+- `InteractPrompt`: interaction prompt
+
+`src/pages/page.tsx` should stay thin and mount only the canvas and `GameUI`.
+
+## Regression Rules
+
+- Do not store per-frame values in Zustand.
+- Use `useRef` for high-frequency mutable values such as player velocity, temporary vectors, or animation-loop data.
+- Use selectors instead of reading the whole store in components.
+- Keep gameplay transitions inside store actions when possible.
+- Keep debug-only controls behind `?debug`.
+- Add new state only when a real runtime feature needs it.
+
+## Next Steps
+
+The next natural step is to replace the temporary stage anchors in `GameStageContent` with real stage components, for example `IntroContent`, `BikeContent`, `PyloneContent`, `FermeContent`, and `OutroContent`.