arkaos 5.5.0 → 5.7.0

package/departments/dev/skills/threejs/references/r3f.md

@@ -0,0 +1,249 @@
+> Derived from genjutsu's `threejs-r3f` skill (MIT — `genjutsu.LICENSE`
+> in this directory). The React Three Fiber layer of `dev/threejs`.
+
+# Three.js & React Three Fiber
+
+> 3D on the web. Three.js is the engine, R3F is the React renderer.
+> Concise rules here. Deep-dive in `references/`.
+
+---
+
+## When to Use What
+
+| Need | Tool | Why |
+|---|---|---|
+| Full 3D scene (models, lights, physics) | R3F + drei | Declarative, React-friendly, ecosystem |
+| Vanilla 3D (no React) | Three.js direct | Lighter, no React overhead |
+| Simple 3D transforms on UI | CSS `transform3d` | GPU-composited, no WebGL context |
+| 2D particles / generative | Canvas 2D | Simpler API, less GPU overhead |
+| Shader-only visuals (no scene graph) | Raw WebGL / ShaderMaterial | Maximum control, minimal abstraction |
+
+---
+
+## Scene Setup Patterns
+
+```tsx
+import { Canvas } from '@react-three/fiber'
+import { Environment, OrbitControls } from '@react-three/drei'
+import { Suspense } from 'react'
+
+<Canvas camera={{ position: [0, 2, 5], fov: 45 }} dpr={[1, 2]} gl={{ antialias: true }}>
+  <Suspense fallback={null}>
+    <Environment preset="studio" />
+    <OrbitControls makeDefault />
+    <Scene />
+  </Suspense>
+</Canvas>
+```
+
+**Rules:**
+- Always wrap scene content in `<Suspense>` -- loaders (GLTF, textures, HDRI) need it
+- Set `dpr={[1, 2]}` to clamp pixel ratio (Retina without melting GPUs)
+- Keep the Canvas parent component minimal -- re-renders propagate into the scene
+
+---
+
+## R3F Hooks
+
+| Hook | Purpose | Gotcha |
+|---|---|---|
+| `useFrame((state, delta) => {})` | Per-frame logic (animation, physics) | Never setState inside |
+| `useThree()` | Access gl, scene, camera, size, viewport, pointer | Destructure only what you need |
+| `useLoader(TextureLoader, url)` | Load any Three.js resource | Wrap parent in Suspense |
+| `useGraph(scene)` | Extract nodes/materials from loaded scene | Useful after useGLTF |
+
+### useFrame Tips
+
+```tsx
+useFrame((state, delta) => {
+  // Use delta for framerate-independent animation
+  meshRef.current.rotation.y += delta * 0.5
+  // Access clock for time-based effects
+  material.uniforms.uTime.value = state.clock.elapsedTime
+})
+```
+
+---
+
+## Drei Essentials
+
+| Component | Use Case |
+|---|---|
+| `Environment` | HDRI lighting (presets: studio, sunset, city, forest, dawn) |
+| `Float` | Idle floating animation (speed, rotationIntensity, floatIntensity) |
+| `Text3D` | Extruded 3D text (needs JSON font from Facetype.js) |
+| `useGLTF` | Load .glb/.gltf models (returns { nodes, materials, scene }) |
+| `useGLTF.preload(url)` | Preload model before component mounts |
+| `MeshTransmissionMaterial` | Glass/crystal/liquid refraction effects |
+| `PresentationControls` | Drag-to-rotate for product showcases |
+| `Center` | Auto-center any group of meshes |
+| `Detailed` | LOD -- swap geometry by camera distance |
+| `useTexture` | Load textures with Suspense support |
+| `Instances` | Declarative instancing for repeated meshes |
+
+---
+
+## Postprocessing
+
+```tsx
+import { EffectComposer, Bloom, ChromaticAberration } from '@react-three/postprocessing'
+import { BlendFunction } from 'postprocessing'
+
+<EffectComposer>
+  <Bloom
+    luminanceThreshold={1}
+    luminanceSmoothing={0.4}
+    intensity={0.6}
+  />
+  <ChromaticAberration
+    blendFunction={BlendFunction.NORMAL}
+    offset={[0.002, 0.002]}
+  />
+</EffectComposer>
+```
+
+**Rules:**
+- Bloom is selective by default -- lift material color/emissive above 1.0 to make it glow
+- `luminanceThreshold={1}` = nothing glows unless explicitly emissive
+- Order matters inside EffectComposer
+- Effects are merged into a single pass (performant by design)
+
+---
+
+## Performance Patterns
+
+| Pattern | When |
+|---|---|
+| `<Instances>` / `InstancedMesh` | 100+ identical meshes (particles, trees, crowds) |
+| `<Detailed distances={[0, 50, 100]}>` | LOD: swap hi/lo models by distance |
+| `dispose={null}` on `<primitive>` | Prevent auto-dispose when reusing shared geometry |
+| `useGLTF` + Draco | Compress .glb models (70-90% size reduction) |
+| `useKTX2` (drei) | Compressed GPU textures (1/4 VRAM) — `useTexture` is TextureLoader-only and cannot decode .ktx2 |
+| `frameloop="demand"` on Canvas | Only render when something changes (static scenes) |
+| `invalidate()` from useThree | Trigger a render in demand mode |
+| `<Canvas eventSource={ref}>` | Delegate pointer events to an ancestor element (overlay UIs); rendering stays on the main thread |
+
+**Target metrics:** < 100 draw calls, < 1M triangles, 60fps on mid-range GPU.
+Use `stats-gl` or `r3f-perf` to monitor.
+
+---
+
+## Do Not
+
+### 1. Never setState in useFrame
+
+Causes full React re-render 60x/second. Mutate refs directly.
+
+```tsx
+// BAD
+useFrame(() => {
+  setRotation(prev => prev + 0.01) // React re-render every frame
+})
+
+// GOOD
+useFrame((_, delta) => {
+  meshRef.current.rotation.y += delta * 0.5 // Direct mutation, zero re-renders
+})
+```
+
+### 2. Never allocate in the render loop
+
+`new Vector3()` per frame = GC spikes = stutter.
+
+```tsx
+// BAD
+useFrame((state) => {
+  const target = new THREE.Vector3(0, Math.sin(state.clock.elapsedTime), 0)
+  meshRef.current.position.copy(target)
+})
+
+// GOOD
+const _target = useMemo(() => new THREE.Vector3(), [])
+useFrame((state) => {
+  _target.set(0, Math.sin(state.clock.elapsedTime), 0)
+  meshRef.current.position.copy(_target)
+})
+```
+
+### 3. Never forget dispose (memory leak)
+
+Three.js textures, geometries, and materials live on the GPU. Unmounting a React component does NOT free them.
+
+```tsx
+// BAD -- texture stays in VRAM after unmount
+const texture = useLoader(TextureLoader, '/big-texture.jpg')
+
+// GOOD -- R3F auto-disposes objects mounted as JSX primitives.
+// useLoader results are CACHED globally: disposing the texture directly
+// poisons the cache and the next consumer renders a disposed resource.
+// Evict from the cache instead, then dispose:
+useEffect(() => {
+  return () => {
+    useLoader.clear(TextureLoader, '/big-texture.jpg')
+    texture.dispose()
+  }
+}, [texture])
+
+// Resources YOU constructed (not via useLoader) are yours to dispose:
+useEffect(() => () => { geometry.dispose(); material.dispose() }, [])
+```
+
+### 4. Never re-render the Canvas parent
+
+Parent state changes re-render the Canvas subtree — the Canvas does not
+remount, but every child re-renders, props reconcile against the scene
+graph, and R3F work you meant to keep out of React's render path runs
+again. Keep fast-changing state out of the Canvas parent (zustand or
+refs).
+
+```tsx
+// BAD
+function App() {
+  const [uiState, setUiState] = useState(false) // fast-changing state here re-renders the whole Canvas subtree
+  return (
+    <>
+      <button onClick={() => setUiState(!uiState)}>Toggle</button>
+      <Canvas><Scene config={uiState} /></Canvas>
+    </>
+  )
+}
+
+// GOOD -- isolate Canvas in its own component
+function App() {
+  return (
+    <>
+      <UI />
+      <SceneCanvas />
+    </>
+  )
+}
+```
+
+### 5. Never load assets without Suspense
+
+Loaders (useGLTF, useTexture, useLoader) throw promises. Without Suspense, you get crashes.
+
+```tsx
+// BAD
+<Canvas>
+  <Model /> {/* useGLTF inside -- will throw */}
+</Canvas>
+
+// GOOD
+<Canvas>
+  <Suspense fallback={<Loader />}>
+    <Model />
+  </Suspense>
+</Canvas>
+```
+
+---
+
+## Quick Reference: Loading Sub-resources
+
+| Need | Load |
+|---|---|
+| Scene boilerplate, lighting rigs, controls | `scene-setup.md` (this directory) |
+| Custom shaders, GLSL patterns, uniforms | `shaders.md` (this directory) |
+| Animation principles, easing, timing | the brand guidelines' Motion System (§06), reached via `departments/brand/references/uiux-knowledge-and-tools.md` |
+| Scroll-scrubbed pre-rendered worlds (no live engine) | `departments/dev/skills/scroll-world/SKILL.md` |

package/departments/dev/skills/threejs/references/scene-setup.md

@@ -0,0 +1,404 @@
+# Scene Setup Reference
+
+> Complete R3F boilerplate patterns with TypeScript.
+> Copy-paste ready. Adapt to your project.
+
+---
+
+## Minimal Canvas Setup
+
+```tsx
+import { Canvas } from '@react-three/fiber'
+import { Suspense } from 'react'
+
+function App() {
+  return (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <Canvas
+        camera={{ position: [0, 2, 5], fov: 45, near: 0.1, far: 100 }}
+        dpr={[1, 2]}
+        gl={{ antialias: true, alpha: false, powerPreference: 'high-performance' }}
+      >
+        <Suspense fallback={null}>
+          <Scene />
+        </Suspense>
+      </Canvas>
+    </div>
+  )
+}
+```
+
+**Props breakdown:**
+- `dpr={[1, 2]}` -- clamp device pixel ratio (retina without burning GPUs)
+- `alpha: false` -- opaque background = faster compositing
+- `powerPreference: 'high-performance'` -- request discrete GPU on laptops
+- `frameloop="demand"` -- add for static scenes (render only on invalidate)
+
+---
+
+## Lighting Rigs
+
+### Studio (product shots, clean shadows)
+
+```tsx
+function StudioLighting() {
+  return (
+    <>
+      <ambientLight intensity={0.4} />
+      <directionalLight
+        position={[5, 8, 3]}
+        intensity={1.2}
+        castShadow
+        shadow-mapSize-width={2048}
+        shadow-mapSize-height={2048}
+        shadow-camera-near={0.5}
+        shadow-camera-far={50}
+        shadow-camera-left={-10}
+        shadow-camera-right={10}
+        shadow-camera-top={10}
+        shadow-camera-bottom={-10}
+      />
+      <directionalLight position={[-3, 4, -5]} intensity={0.3} />
+    </>
+  )
+}
+```
+
+### Studio with HDRI (easiest, best quality)
+
+```tsx
+import { Environment } from '@react-three/drei'
+
+function StudioHDRI() {
+  return (
+    <>
+      <Environment preset="studio" background={false} />
+      {/* Optional fill light to reduce contrast */}
+      <ambientLight intensity={0.2} />
+    </>
+  )
+}
+```
+
+**Environment presets:** `apartment`, `city`, `dawn`, `forest`, `lobby`, `night`, `park`, `studio`, `sunset`, `warehouse`
+
+### Outdoor (natural, directional sun)
+
+```tsx
+function OutdoorLighting() {
+  return (
+    <>
+      <Environment preset="sunset" background />
+      <directionalLight
+        position={[10, 15, 5]}
+        intensity={2}
+        castShadow
+        shadow-mapSize={2048}
+        color="#ffeedd"
+      />
+      <hemisphereLight args={['#87CEEB', '#362907', 0.3]} />
+    </>
+  )
+}
+```
+
+### Dramatic (high contrast, noir)
+
+```tsx
+function DramaticLighting() {
+  return (
+    <>
+      <color attach="background" args={['#000000']} />
+      <fog attach="fog" args={['#000000', 5, 20]} />
+      <spotLight
+        position={[3, 8, 2]}
+        angle={0.3}
+        penumbra={0.8}
+        intensity={3}
+        castShadow
+        color="#ff6644"
+      />
+      <pointLight position={[-5, 2, -3]} intensity={0.5} color="#4466ff" />
+      {/* No ambient -- pure darkness outside lights */}
+    </>
+  )
+}
+```
+
+---
+
+## Camera Configurations
+
+### Perspective (default, most scenes)
+
+```tsx
+<Canvas camera={{ position: [0, 2, 5], fov: 45 }}>
+```
+
+- **fov 35-45:** Natural, cinematic feel
+- **fov 60-75:** Wider, more immersive
+- **fov 20-30:** Telephoto, compressed depth
+
+### Orthographic (isometric, UI, 2D-in-3D)
+
+```tsx
+<Canvas orthographic camera={{ position: [0, 5, 10], zoom: 50 }}>
+```
+
+### Animated Camera (smooth transitions)
+
+```tsx
+import { useFrame, useThree } from '@react-three/fiber'
+import { useMemo } from 'react'
+import * as THREE from 'three'
+
+function CameraRig({ target }: { target: [number, number, number] }) {
+  const _target = useMemo(() => new THREE.Vector3(), [])
+  const _position = useMemo(() => new THREE.Vector3(), [])
+
+  useFrame((state, delta) => {
+    // Smooth lerp to target
+    _target.set(...target)
+    state.camera.position.lerp(_position.set(target[0], target[1] + 2, target[2] + 5), delta * 2)
+    state.camera.lookAt(_target)
+  })
+
+  return null
+}
+```
+
+---
+
+## Controls
+
+### OrbitControls (inspect / product viewer)
+
+```tsx
+import { OrbitControls } from '@react-three/drei'
+
+<OrbitControls
+  makeDefault
+  enableDamping
+  dampingFactor={0.05}
+  minDistance={2}
+  maxDistance={20}
+  minPolarAngle={0}
+  maxPolarAngle={Math.PI / 2}    // prevent going below ground
+  autoRotate={false}
+  autoRotateSpeed={0.5}
+/>
+```
+
+### PresentationControls (drag-to-rotate, bounded)
+
+```tsx
+import { PresentationControls } from '@react-three/drei'
+
+<PresentationControls
+  global                         // listen on entire canvas
+  snap                           // snap back to rest
+  speed={1.5}
+  zoom={0.8}
+  rotation={[0, -Math.PI / 4, 0]}  // initial angle
+  polar={[-Math.PI / 4, Math.PI / 4]}
+  azimuth={[-Math.PI / 4, Math.PI / 4]}
+>
+  <Model />
+</PresentationControls>
+```
+
+### MapControls (top-down, pan-based)
+
+```tsx
+import { MapControls } from '@react-three/drei'
+
+<MapControls
+  makeDefault
+  enableRotate={false}
+  minDistance={5}
+  maxDistance={50}
+/>
+```
+
+### Pointer-based camera (follow cursor)
+
+```tsx
+function PointerCamera() {
+  useFrame((state) => {
+    const { x, y } = state.pointer // normalized -1 to 1
+    state.camera.position.x = THREE.MathUtils.lerp(state.camera.position.x, x * 2, 0.05)
+    state.camera.position.y = THREE.MathUtils.lerp(state.camera.position.y, y * 1.5 + 1, 0.05)
+    state.camera.lookAt(0, 0, 0)
+  })
+  return null
+}
+```
+
+---
+
+## Loading Models
+
+### useGLTF (standard)
+
+```tsx
+import * as THREE from 'three'
+import { useGLTF } from '@react-three/drei'
+import type { ComponentProps } from 'react'
+import type { GLTF } from 'three-stdlib'
+
+type ModelGLTF = GLTF & {
+  nodes: {
+    Body: THREE.Mesh
+    Eyes: THREE.Mesh
+  }
+  materials: {
+    skin: THREE.MeshStandardMaterial
+    eyes: THREE.MeshStandardMaterial
+  }
+}
+
+// React 19 typings removed the global JSX namespace; use the element's
+// component props. The double cast is deliberate: GLTF's nodes/materials
+// are loosely typed upstream, so the assertion must go through unknown.
+function Model(props: ComponentProps<'group'>) {
+  const { nodes, materials } = useGLTF('/model.glb') as unknown as ModelGLTF
+
+  return (
+    <group {...props} dispose={null}>
+      <mesh geometry={nodes.Body.geometry} material={materials.skin} />
+      <mesh geometry={nodes.Eyes.geometry} material={materials.eyes} />
+    </group>
+  )
+}
+
+useGLTF.preload('/model.glb')
+```
+
+**Tip:** Use [gltf.pmnd.rs](https://gltf.pmnd.rs/) to auto-generate typed R3F components from .glb files.
+
+### useGLTF with Draco compression
+
+```tsx
+import { useGLTF } from '@react-three/drei'
+
+// Draco decoder loaded from CDN automatically
+const { nodes } = useGLTF('/model-draco.glb', true) // second arg enables Draco
+
+useGLTF.preload('/model-draco.glb', true)
+```
+
+### useTexture
+
+```tsx
+import { useTexture } from '@react-three/drei'
+
+function TexturedMesh() {
+  const [colorMap, normalMap, roughnessMap] = useTexture([
+    '/textures/color.jpg',
+    '/textures/normal.jpg',
+    '/textures/roughness.jpg',
+  ])
+
+  return (
+    <mesh>
+      <sphereGeometry args={[1, 64, 64]} />
+      <meshStandardMaterial
+        map={colorMap}
+        normalMap={normalMap}
+        roughnessMap={roughnessMap}
+      />
+    </mesh>
+  )
+}
+
+useTexture.preload(['/textures/color.jpg', '/textures/normal.jpg', '/textures/roughness.jpg'])
+```
+
+---
+
+## Responsive Canvas
+
+### Fill parent container
+
+```tsx
+// Parent must have explicit dimensions
+<div style={{ width: '100%', height: '100vh' }}>
+  <Canvas>
+    <Scene />
+  </Canvas>
+</div>
+```
+
+### Respond to viewport size inside scene
+
+```tsx
+function ResponsiveObject() {
+  const { viewport } = useThree()
+  // viewport.width/height = world units visible at z=0
+
+  return (
+    <mesh scale={viewport.width > 6 ? 1 : 0.6}>
+      <boxGeometry />
+      <meshStandardMaterial />
+    </mesh>
+  )
+}
+```
+
+### Adaptive performance
+
+```tsx
+import { useState } from 'react'
+import { Canvas } from '@react-three/fiber'
+import { PerformanceMonitor } from '@react-three/drei'
+
+function App() {
+  const [dpr, setDpr] = useState(1.5)
+  return (
+    <Canvas dpr={dpr}>
+      <PerformanceMonitor
+        onIncline={() => setDpr(2)}
+        onDecline={() => setDpr(1)}
+      >
+        <Scene />
+      </PerformanceMonitor>
+    </Canvas>
+  )
+}
+```
+
+---
+
+## Shadows Setup
+
+```tsx
+<Canvas shadows>
+  <directionalLight castShadow shadow-mapSize={2048} />
+  <mesh castShadow>
+    <boxGeometry />
+    <meshStandardMaterial />
+  </mesh>
+  <mesh receiveShadow rotation-x={-Math.PI / 2} position-y={-1}>
+    <planeGeometry args={[20, 20]} />
+    <shadowMaterial opacity={0.3} />
+  </mesh>
+</Canvas>
+```
+
+- `shadows` on Canvas enables the shadow system
+- `castShadow` on lights and meshes that cast
+- `receiveShadow` on meshes that receive
+- `<shadowMaterial>` for transparent ground shadows (product shots)
+- `<ContactShadows>` from drei for soft baked-look shadows without shadow maps
+
+```tsx
+import { ContactShadows } from '@react-three/drei'
+
+<ContactShadows
+  position={[0, -1, 0]}
+  opacity={0.4}
+  scale={10}
+  blur={2}
+  far={4}
+/>
+```