@lark-apaas/coding-steering 0.1.2 → 0.1.4

package/steering/vite-react/skills/react-three-fiber/references/fundamentals.md

@@ -0,0 +1,877 @@
+# React Three Fiber Fundamentals
+
+## Quick Start
+
+```tsx
+import { Canvas } from '@react-three/fiber'
+import { useRef } from 'react'
+import { useFrame } from '@react-three/fiber'
+
+function RotatingBox() {
+  const meshRef = useRef()
+
+  useFrame((state, delta) => {
+    meshRef.current.rotation.x += delta
+    meshRef.current.rotation.y += delta * 0.5
+  })
+
+  return (
+    <mesh ref={meshRef}>
+      <boxGeometry args={[1, 1, 1]} />
+      <meshStandardMaterial color="hotpink" />
+    </mesh>
+  )
+}
+
+export default function App() {
+  return (
+    <Canvas camera={{ position: [0, 0, 5], fov: 75 }}>
+      <ambientLight intensity={0.5} />
+      <directionalLight position={[5, 5, 5]} />
+      <RotatingBox />
+    </Canvas>
+  )
+}
+```
+
+## Canvas Component
+
+The root component that creates the WebGL context, scene, camera, and renderer.
+
+```tsx
+import { Canvas } from '@react-three/fiber'
+
+function App() {
+  return (
+    <Canvas
+      // Camera configuration
+      camera={{
+        position: [0, 5, 10],
+        fov: 75,
+        near: 0.1,
+        far: 1000,
+      }}
+      // Or use orthographic
+      orthographic
+      camera={{ zoom: 50, position: [0, 0, 100] }}
+
+      // Renderer settings
+      gl={{
+        antialias: true,
+        alpha: true,
+        powerPreference: 'high-performance',
+        preserveDrawingBuffer: true,  // For screenshots
+      }}
+      dpr={[1, 2]}  // Pixel ratio min/max
+
+      // Shadows
+      shadows  // or shadows="soft" | "basic" | "percentage"
+
+      // Color management
+      flat  // Disable automatic sRGB color management
+
+      // Frame loop control
+      frameloop="demand"  // 'always' | 'demand' | 'never'
+
+      // Event handling
+      eventSource={document.getElementById('root')}
+      eventPrefix="client"  // 'offset' | 'client' | 'page' | 'layer' | 'screen'
+
+      // Callbacks
+      onCreated={(state) => {
+        console.log('Canvas ready:', state.gl, state.scene, state.camera)
+      }}
+      onPointerMissed={() => console.log('Clicked background')}
+
+      // Styling
+      style={{ width: '100%', height: '100vh' }}
+    >
+      <Scene />
+    </Canvas>
+  )
+}
+```
+
+### Canvas Defaults
+
+R3F sets sensible defaults:
+
+- Renderer: antialias, alpha, outputColorSpace = SRGBColorSpace
+- Camera: PerspectiveCamera at [0, 0, 5]
+- Scene: Automatic resize handling
+- Events: Pointer events enabled
+
+## useFrame Hook
+
+Subscribe to the render loop. Called every frame (typically 60fps).
+
+```tsx
+import { useFrame } from '@react-three/fiber'
+import { useRef } from 'react'
+
+function AnimatedMesh() {
+  const meshRef = useRef()
+
+  useFrame((state, delta, xrFrame) => {
+    // state: Full R3F state (see useThree)
+    // delta: Time since last frame in seconds
+    // xrFrame: XR frame if in VR/AR mode
+
+    // Animate rotation
+    meshRef.current.rotation.y += delta
+
+    // Access clock
+    const elapsed = state.clock.elapsedTime
+    meshRef.current.position.y = Math.sin(elapsed) * 2
+
+    // Access pointer position (-1 to 1)
+    const { x, y } = state.pointer
+    meshRef.current.rotation.x = y * 0.5
+    meshRef.current.rotation.z = x * 0.5
+  })
+
+  return (
+    <mesh ref={meshRef}>
+      <boxGeometry />
+      <meshStandardMaterial color="orange" />
+    </mesh>
+  )
+}
+```
+
+### useFrame with Priority
+
+Control render order with priority (higher = later).
+
+```tsx
+// Default priority is 0
+useFrame((state, delta) => {
+  // Runs first
+}, -1)
+
+useFrame((state, delta) => {
+  // Runs after priority -1
+}, 0)
+
+// Manual rendering with positive priority
+useFrame((state, delta) => {
+  // Take over rendering
+  state.gl.render(state.scene, state.camera)
+}, 1)
+```
+
+### Conditional useFrame
+
+```tsx
+function ConditionalAnimation({ active }) {
+  useFrame((state, delta) => {
+    if (!active) return  // Skip when inactive
+    meshRef.current.rotation.y += delta
+  })
+}
+```
+
+## useThree Hook
+
+Access the R3F state store.
+
+```tsx
+import { useThree } from '@react-three/fiber'
+
+function CameraInfo() {
+  // Get full state (triggers re-render on any change)
+  const state = useThree()
+
+  // Selective subscription (recommended)
+  const camera = useThree((state) => state.camera)
+  const gl = useThree((state) => state.gl)
+  const scene = useThree((state) => state.scene)
+  const size = useThree((state) => state.size)
+
+  // Available state properties:
+  // gl: WebGLRenderer
+  // scene: Scene
+  // camera: Camera
+  // raycaster: Raycaster
+  // pointer: Vector2 (normalized -1 to 1)
+  // mouse: Vector2 (deprecated, use pointer)
+  // clock: Clock
+  // size: { width, height, top, left }
+  // viewport: { width, height, factor, distance, aspect }
+  // performance: { current, min, max, debounce, regress }
+  // events: Event handlers
+  // set: State setter
+  // get: State getter
+  // invalidate: Trigger re-render (for frameloop="demand")
+  // advance: Advance one frame (for frameloop="never")
+
+  return null
+}
+```
+
+### Common useThree Patterns
+
+```tsx
+// Responsive to viewport
+function ResponsiveObject() {
+  const viewport = useThree((state) => state.viewport)
+  return (
+    <mesh scale={[viewport.width / 4, viewport.height / 4, 1]}>
+      <planeGeometry />
+      <meshBasicMaterial color="blue" />
+    </mesh>
+  )
+}
+
+// Manual render trigger
+function TriggerRender() {
+  const invalidate = useThree((state) => state.invalidate)
+
+  const handleClick = () => {
+    // Trigger render when using frameloop="demand"
+    invalidate()
+  }
+}
+
+// Update camera
+function CameraController() {
+  const camera = useThree((state) => state.camera)
+  const set = useThree((state) => state.set)
+
+  useEffect(() => {
+    camera.position.set(10, 10, 10)
+    camera.lookAt(0, 0, 0)
+  }, [camera])
+}
+```
+
+## JSX Elements
+
+All Three.js objects are available as JSX elements (camelCase).
+
+### Meshes
+
+```tsx
+// Basic mesh structure
+<mesh
+  position={[0, 0, 0]}       // x, y, z
+  rotation={[0, Math.PI, 0]} // Euler angles in radians
+  scale={[1, 2, 1]}          // x, y, z or single number
+  visible={true}
+  castShadow
+  receiveShadow
+>
+  <boxGeometry args={[1, 1, 1]} />
+  <meshStandardMaterial color="red" />
+</mesh>
+
+// With ref
+const meshRef = useRef()
+<mesh ref={meshRef} />
+// meshRef.current is the THREE.Mesh
+```
+
+### Geometry args
+
+Constructor arguments via `args` prop:
+
+```tsx
+// BoxGeometry(width, height, depth, widthSegments, heightSegments, depthSegments)
+<boxGeometry args={[1, 1, 1, 1, 1, 1]} />
+
+// SphereGeometry(radius, widthSegments, heightSegments)
+<sphereGeometry args={[1, 32, 32]} />
+
+// PlaneGeometry(width, height, widthSegments, heightSegments)
+<planeGeometry args={[10, 10]} />
+
+// CylinderGeometry(radiusTop, radiusBottom, height, radialSegments)
+<cylinderGeometry args={[1, 1, 2, 32]} />
+```
+
+### Groups
+
+```tsx
+<group position={[5, 0, 0]} rotation={[0, Math.PI / 4, 0]}>
+  <mesh position={[-1, 0, 0]}>
+    <boxGeometry />
+    <meshStandardMaterial color="red" />
+  </mesh>
+  <mesh position={[1, 0, 0]}>
+    <boxGeometry />
+    <meshStandardMaterial color="blue" />
+  </mesh>
+</group>
+```
+
+### Nested Properties
+
+Use dashes for nested properties:
+
+```tsx
+<mesh
+  position-x={5}
+  rotation-y={Math.PI}
+  scale-z={2}
+>
+  <meshStandardMaterial
+    color="red"
+    metalness={0.8}
+    roughness={0.2}
+  />
+</mesh>
+
+// Shadow camera properties
+<directionalLight
+  castShadow
+  shadow-mapSize={[2048, 2048]}
+  shadow-camera-left={-10}
+  shadow-camera-right={10}
+  shadow-camera-top={10}
+  shadow-camera-bottom={-10}
+/>
+```
+
+### attach Prop
+
+Control how children attach to parents:
+
+```tsx
+<mesh>
+  <boxGeometry />
+  {/* Default: attaches as 'material' */}
+  <meshStandardMaterial />
+</mesh>
+
+{/* Explicit attach */}
+<mesh>
+  <boxGeometry attach="geometry" />
+  <meshStandardMaterial attach="material" />
+</mesh>
+
+{/* Array attachment */}
+<mesh>
+  <boxGeometry />
+  <meshStandardMaterial attach="material-0" color="red" />
+  <meshStandardMaterial attach="material-1" color="blue" />
+</mesh>
+
+{/* Custom attachment with function */}
+<someObject>
+  <texture
+    attach={(parent, self) => {
+      parent.map = self
+      return () => { parent.map = null }  // Cleanup
+    }}
+  />
+</someObject>
+```
+
+## Event Handling
+
+R3F provides React-style events on 3D objects.
+
+```tsx
+function InteractiveBox() {
+  const [hovered, setHovered] = useState(false)
+  const [clicked, setClicked] = useState(false)
+
+  return (
+    <mesh
+      onClick={(e) => {
+        e.stopPropagation()  // Prevent bubbling
+        setClicked(!clicked)
+
+        // Event properties:
+        console.log(e.object)      // THREE.Mesh
+        console.log(e.point)       // Vector3 - intersection point
+        console.log(e.distance)    // Distance from camera
+        console.log(e.face)        // Intersected face
+        console.log(e.faceIndex)   // Face index
+        console.log(e.uv)          // UV coordinates
+        console.log(e.normal)      // Face normal
+        console.log(e.pointer)     // Normalized pointer coords
+        console.log(e.ray)         // Raycaster ray
+        console.log(e.camera)      // Camera
+        console.log(e.delta)       // Distance moved (drag events)
+      }}
+      onContextMenu={(e) => console.log('Right click')}
+      onDoubleClick={(e) => console.log('Double click')}
+      onPointerOver={(e) => {
+        e.stopPropagation()
+        setHovered(true)
+        document.body.style.cursor = 'pointer'
+      }}
+      onPointerOut={(e) => {
+        setHovered(false)
+        document.body.style.cursor = 'default'
+      }}
+      onPointerDown={(e) => console.log('Pointer down')}
+      onPointerUp={(e) => console.log('Pointer up')}
+      onPointerMove={(e) => console.log('Moving over mesh')}
+      onWheel={(e) => console.log('Wheel:', e.deltaY)}
+      scale={hovered ? 1.2 : 1}
+    >
+      <boxGeometry />
+      <meshStandardMaterial color={clicked ? 'hotpink' : 'orange'} />
+    </mesh>
+  )
+}
+```
+
+### Event Propagation
+
+Events bubble up through the scene graph:
+
+```tsx
+<group onClick={(e) => console.log('Group clicked')}>
+  <mesh onClick={(e) => {
+    e.stopPropagation()  // Stop bubbling to group
+    console.log('Mesh clicked')
+  }}>
+    <boxGeometry />
+    <meshStandardMaterial />
+  </mesh>
+</group>
+```
+
+## primitive Element
+
+Use existing Three.js objects directly:
+
+```tsx
+import * as THREE from 'three'
+
+// Existing object
+const geometry = new THREE.BoxGeometry()
+const material = new THREE.MeshStandardMaterial({ color: 'red' })
+const mesh = new THREE.Mesh(geometry, material)
+
+function Scene() {
+  return <primitive object={mesh} position={[0, 1, 0]} />
+}
+
+// Common with loaded models
+function Model({ gltf }) {
+  return <primitive object={gltf.scene} />
+}
+```
+
+## extend Function
+
+Register custom Three.js classes for JSX use:
+
+```tsx
+import { extend } from '@react-three/fiber'
+import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls'
+
+// Extend once (usually at module level)
+extend({ OrbitControls })
+
+// Now use as JSX
+function Scene() {
+  const { camera, gl } = useThree()
+  return <orbitControls args={[camera, gl.domElement]} />
+}
+
+// TypeScript declaration
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      orbitControls: ReactThreeFiber.Object3DNode<OrbitControls, typeof OrbitControls>
+    }
+  }
+}
+```
+
+## Refs and Imperative Access
+
+```tsx
+import { useRef, useEffect } from 'react'
+import { useFrame } from '@react-three/fiber'
+import * as THREE from 'three'
+
+function MeshWithRef() {
+  const meshRef = useRef<THREE.Mesh>(null)
+  const materialRef = useRef<THREE.MeshStandardMaterial>(null)
+
+  useEffect(() => {
+    if (meshRef.current) {
+      // Direct Three.js access
+      meshRef.current.geometry.computeBoundingBox()
+      console.log(meshRef.current.geometry.boundingBox)
+    }
+  }, [])
+
+  useFrame(() => {
+    if (materialRef.current) {
+      materialRef.current.color.setHSL(Math.random(), 1, 0.5)
+    }
+  })
+
+  return (
+    <mesh ref={meshRef}>
+      <boxGeometry />
+      <meshStandardMaterial ref={materialRef} />
+    </mesh>
+  )
+}
+```
+
+## Performance Patterns
+
+### Avoiding Re-renders
+
+```tsx
+// BAD: Creates new object every render
+<mesh position={[x, y, z]} />
+
+// GOOD: Mutate existing position
+const meshRef = useRef()
+useFrame(() => {
+  meshRef.current.position.x = x
+})
+<mesh ref={meshRef} />
+
+// GOOD: Use useMemo for static values
+const position = useMemo(() => [x, y, z], [x, y, z])
+<mesh position={position} />
+```
+
+### Component Isolation
+
+```tsx
+// Isolate animated components to prevent parent re-renders
+function Scene() {
+  return (
+    <>
+      <StaticEnvironment />
+      <AnimatedObject />  {/* Only this re-renders on animation */}
+    </>
+  )
+}
+
+function AnimatedObject() {
+  const ref = useRef()
+  useFrame((_, delta) => {
+    ref.current.rotation.y += delta
+  })
+  return <mesh ref={ref}><boxGeometry /></mesh>
+}
+```
+
+### Dispose
+
+R3F auto-disposes geometries, materials, and textures. Override with:
+
+```tsx
+<mesh dispose={null}>  {/* Prevent auto-dispose */}
+  <boxGeometry />
+  <meshStandardMaterial />
+</mesh>
+```
+
+## Common Patterns
+
+### Fullscreen Canvas
+
+```tsx
+// styles.css
+html, body, #root {
+  margin: 0;
+  padding: 0;
+  width: 100%;
+  height: 100%;
+}
+
+// App.tsx
+<Canvas style={{ width: '100%', height: '100%' }}>
+```
+
+### Responsive Canvas
+
+```tsx
+function ResponsiveScene() {
+  const { viewport } = useThree()
+
+  return (
+    <mesh scale={Math.min(viewport.width, viewport.height) / 5}>
+      <boxGeometry />
+      <meshStandardMaterial />
+    </mesh>
+  )
+}
+```
+
+### Forwarding Refs
+
+```tsx
+import { forwardRef } from 'react'
+
+const CustomMesh = forwardRef((props, ref) => {
+  return (
+    <mesh ref={ref} {...props}>
+      <boxGeometry />
+      <meshStandardMaterial color="orange" />
+    </mesh>
+  )
+})
+
+// Usage
+const meshRef = useRef()
+<CustomMesh ref={meshRef} position={[0, 1, 0]} />
+```
+
+## Debugging with Leva
+
+Leva provides a GUI for tweaking parameters in real-time during development.
+
+### Installation
+
+```bash
+npm install leva
+```
+
+### Basic Controls
+
+```tsx
+import { useControls } from 'leva'
+
+function DebugMesh() {
+  const { position, color, scale, visible } = useControls({
+    position: { value: [0, 0, 0], step: 0.1 },
+    color: '#ff0000',
+    scale: { value: 1, min: 0.1, max: 5, step: 0.1 },
+    visible: true,
+  })
+
+  return (
+    <mesh position={position} scale={scale} visible={visible}>
+      <boxGeometry />
+      <meshStandardMaterial color={color} />
+    </mesh>
+  )
+}
+```
+
+### Organized Folders
+
+```tsx
+import { useControls, folder } from 'leva'
+
+function DebugScene() {
+  const { lightIntensity, lightColor, shadowMapSize } = useControls({
+    Lighting: folder({
+      lightIntensity: { value: 1, min: 0, max: 5 },
+      lightColor: '#ffffff',
+      shadowMapSize: { value: 1024, options: [512, 1024, 2048, 4096] },
+    }),
+    Camera: folder({
+      fov: { value: 75, min: 30, max: 120 },
+      near: { value: 0.1, min: 0.01, max: 1 },
+    }),
+  })
+
+  return (
+    <directionalLight
+      intensity={lightIntensity}
+      color={lightColor}
+      shadow-mapSize={[shadowMapSize, shadowMapSize]}
+    />
+  )
+}
+```
+
+### Button Actions
+
+```tsx
+import { useControls, button } from 'leva'
+
+function DebugActions() {
+  const meshRef = useRef()
+
+  useControls({
+    'Reset Position': button(() => {
+      meshRef.current.position.set(0, 0, 0)
+    }),
+    'Random Color': button(() => {
+      meshRef.current.material.color.setHex(Math.random() * 0xffffff)
+    }),
+    'Log State': button(() => {
+      console.log(meshRef.current.position)
+    }),
+  })
+
+  return <mesh ref={meshRef}>...</mesh>
+}
+```
+
+### Hide in Production
+
+```tsx
+import { Leva } from 'leva'
+
+function App() {
+  return (
+    <>
+      {/* Hide Leva panel in production */}
+      <Leva hidden={process.env.NODE_ENV === 'production'} />
+
+      <Canvas>
+        <Scene />
+      </Canvas>
+    </>
+  )
+}
+```
+
+### Monitor Values (Read-Only)
+
+```tsx
+import { useControls, monitor } from 'leva'
+import { useFrame } from '@react-three/fiber'
+
+function PerformanceMonitor() {
+  const [fps, setFps] = useState(0)
+
+  useControls({
+    FPS: monitor(() => fps, { graph: true, interval: 100 }),
+  })
+
+  useFrame((state) => {
+    // Update FPS display
+    setFps(Math.round(1 / state.clock.getDelta()))
+  })
+
+  return null
+}
+```
+
+### Integration with useFrame
+
+```tsx
+function AnimatedDebugMesh() {
+  const meshRef = useRef()
+
+  const { speed, amplitude, enabled } = useControls('Animation', {
+    enabled: true,
+    speed: { value: 1, min: 0, max: 5 },
+    amplitude: { value: 1, min: 0, max: 3 },
+  })
+
+  useFrame(({ clock }) => {
+    if (!enabled) return
+    meshRef.current.position.y = Math.sin(clock.elapsedTime * speed) * amplitude
+  })
+
+  return (
+    <mesh ref={meshRef}>
+      <sphereGeometry />
+      <meshStandardMaterial color="cyan" />
+    </mesh>
+  )
+}
+```
+
+## 妙搭沙箱适配铁律 (React 19 + 严格模式)
+
+妙搭沙箱跑 React 19 + React Compiler 严格 lint。下列写法 commit 时会报错，且**运行时部分组件会被 React 跳过编译/重复挂载抛错 → Canvas 内部黑屏**。失败 case `app_4k7v39352vh9q` 12 次循环改 lint 没修对就是踩了这些坑。
+
+### 1. `Math.random()` / `Date.now()` 严禁 render 期间直接调用
+
+```tsx
+// ❌ render 期间生成位置, React 19 报 "impure function during render"
+{enemies.map((_, i) => <group position={[Math.random() * 10, 0, 0]}>...</group>)}
+
+// ✅ useMemo 一次性算好, deps=[]
+const enemyPositions = useMemo(
+  () => Array.from({ length: 8 }, () => [Math.random() * 10, 0, Math.random() * 10]),
+  []
+)
+{enemyPositions.map((pos, i) => <group key={i} position={pos}>...</group>)}
+```
+
+### 2. 动画 / 位置更新优先用 drei 高阶组件, 严禁 render 里读写 ref.current
+
+```tsx
+// ❌ render 期间访问 ref.current — React 19 报 "Cannot access refs during render"
+<mesh rotation={[ref.current?.rotation.y + 0.01 || 0, 0, 0]} />
+
+// ❌ 自己写 useFrame 逐帧推位置 — 容易踩坑且代码冗长
+function Earth() {
+  const ref = useRef<THREE.Mesh>(null)
+  useFrame(() => { if (ref.current) ref.current.rotation.y += 0.005 })
+  return <mesh ref={ref}>...</mesh>
+}
+
+// ✅ 优先用 drei 高阶组件让库帮你驱动动画
+<OrbitControls autoRotate autoRotateSpeed={0.4} />  // 整个场景自动旋转
+<Float speed={1.5} rotationIntensity={1} floatIntensity={2}>  // 自动悬浮
+  <mesh>...</mesh>
+</Float>
+
+// ✅ 必须自己写 useFrame 时, ref 操作放 useFrame 内, 不进 render JSX
+function Earth() {
+  const ref = useRef<THREE.Mesh>(null)
+  useFrame(() => { if (ref.current) ref.current.rotation.y += 0.005 })
+  return <mesh ref={ref}><sphereGeometry /><meshStandardMaterial /></mesh>
+}
+```
+
+### 3. useEffect 里 setState 加 if 条件 / 用 setter 函数, 防级联渲染
+
+```tsx
+// ❌ React 19 报 "Calling setState synchronously within an effect can trigger cascading renders"
+useEffect(() => { setHealth(100) }, [gameState])
+
+// ✅ 加条件或 setter 函数
+useEffect(() => {
+  if (gameState === 'playing') {
+    setHealth((h) => (h > 0 ? h : 100))
+  }
+}, [gameState])
+```
+
+### 4. Canvas 外必须包 ErrorBoundary, Suspense 不吞 error
+
+`<Canvas>` 内部 mesh / geometry / material 抛 runtime error 时, **Suspense fallback 只吞 Promise (异步加载), 不吞 Error**. 没 ErrorBoundary → 整个 Canvas 黑屏, 控制台报错被吞, 用户看到只剩 HUD.
+
+```tsx
+// ❌ 只有 Suspense, Canvas 内部错误 → 整片黑
+<Canvas>
+  <Suspense fallback={null}>
+    <Scene />
+  </Suspense>
+</Canvas>
+
+// ✅ ErrorBoundary 包 Canvas, fallback 显示降级 UI 而不是黑屏
+import { ErrorBoundary } from 'react-error-boundary'
+
+<ErrorBoundary fallback={<div className="p-8 text-center">3D 场景加载失败, 请刷新重试</div>}>
+  <Canvas camera={{ position: [0, 0, 5] }}>
+    <Suspense fallback={null}>
+      <Scene />
+    </Suspense>
+  </Canvas>
+</ErrorBoundary>
+```
+
+### 5. 黑屏必查清单 (调试 3D 场景空白时按顺序排查)
+
+| 项 | 要求 |
+|----|------|
+| Canvas 父容器有显式高度 | `h-screen` / `h-[800px]`, **不要** `h-full` 链断 |
+| 至少 1 个 `<ambientLight intensity≥0.3>` | 没灯 = 全黑 |
+| `<directionalLight position={[5,5,5]} intensity≥0.5>` | 主光源 |
+| Camera position 跟 mesh 有距离 (5-20 单位) | `<Canvas camera={{ position: [0, 0, 5] }}>` |
+| 至少 1 个 mesh 在 `[0, 0, 0]` 附近 | 调试时放在原点确认 |
+| 浏览器 Console 看有无红字 Error | 看 R3F 抛了什么(没 ErrorBoundary 时只有 Console 看得到) |
+
+## See Also
+
+- `r3f-geometry` - Geometry creation
+- `r3f-materials` - Material configuration
+- `r3f-lighting` - Lights and shadows
+- `r3f-interaction` - Controls and user input
+- `r3f-animation` - 动画(useFrame / drei autoRotate / Float)
+- `r3f-loaders` - GLTF 加载 + Suspense 模式