refactor: tighten project structure and strengthen tooling

src/utils/debug/Debug.ts

@@ -0,0 +1,78 @@
+import GUI from "lil-gui";
+import type { CameraMode } from "@/types/debug";
+
+export class Debug {
+  private static instance: Debug | null = null;
+
+  public readonly active: boolean;
+  private readonly gui: GUI | null;
+  private readonly folders = new Map<string, GUI>();
+  private readonly listeners = new Set<() => void>();
+  private readonly controls: { cameraMode: CameraMode } = {
+    cameraMode: "player",
+  };
+
+  static getInstance(): Debug {
+    if (!Debug.instance) {
+      Debug.instance = new Debug();
+    }
+
+    return Debug.instance;
+  }
+
+  private constructor() {
+    this.active = new URLSearchParams(window.location.search).has("debug");
+    this.gui = this.active ? new GUI({ title: "La-Fabrik Debug" }) : null;
+
+    if (this.gui) {
+      const folder = this.createFolder("Debug");
+
+      if (!folder) {
+        return;
+      }
+
+      folder
+        .add(this.controls, "cameraMode", { Player: "player", Debug: "debug" })
+        .name("Camera Mode")
+        .onChange((value: CameraMode) => {
+          this.controls.cameraMode = value;
+          this.emit();
+        });
+    }
+  }
+
+  createFolder(name: string): GUI;
+  createFolder(name: string): GUI | null;
+  createFolder(name: string): GUI | null {
+    if (!this.gui) {
+      return null;
+    }
+
+    const existingFolder = this.folders.get(name);
+
+    if (existingFolder) {
+      return existingFolder;
+    }
+
+    const folder = this.gui.addFolder(name);
+    this.folders.set(name, folder);
+
+    return folder;
+  }
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  getCameraMode(): CameraMode {
+    return this.controls.cameraMode;
+  }
+
+  private emit(): void {
+    this.listeners.forEach((listener) => listener());
+  }
+}

src/utils/debug/DebugPerf.tsx

@@ -0,0 +1,18 @@
+import { Suspense, lazy } from "react";
+import { Debug } from "@/utils/debug/Debug";
+
+const Perf = lazy(() => import("r3f-perf").then((m) => ({ default: m.Perf })));
+
+export function DebugPerf(): React.JSX.Element | null {
+  const debug = Debug.getInstance();
+
+  if (!debug.active) {
+    return null;
+  }
+
+  return (
+    <Suspense fallback={null}>
+      <Perf position="bottom-right" />
+    </Suspense>
+  );
+}

src/utils/debug/scene/DebugCameraControls.tsx

@@ -0,0 +1,13 @@
+import { OrbitControls } from "@react-three/drei";
+
+export function DebugCameraControls(): React.JSX.Element {
+  return (
+    <OrbitControls
+      enableDamping
+      dampingFactor={0.05}
+      minDistance={100}
+      maxDistance={1000}
+      target={[0, 1.75, 0]}
+    />
+  );
+}

src/utils/debug/scene/DebugHelpers.tsx

@@ -0,0 +1,19 @@
+import { Debug } from "@/utils/debug/Debug";
+
+export function DebugHelpers(): React.JSX.Element | null {
+  const debug = Debug.getInstance();
+
+  if (!debug.active) {
+    return null;
+  }
+
+  return (
+    <>
+      <gridHelper
+        args={[180, 36, "#1d4ed8", "#1e293b"]}
+        position={[0, 0.01, 0]}
+      />
+      <axesHelper args={[10]} />
+    </>
+  );
+}