@stella-studio/ck 1.0.0

package/.claude/skills/threejs/references/08-interaction.md

@@ -0,0 +1,267 @@
+# Interaction & Picking
+
+Handle user input and object interaction.
+
+## Mouse/Touch Raycasting
+
+Detect which object user clicked:
+
+```javascript
+const raycaster = new THREE.Raycaster();
+const mouse = new THREE.Vector2();
+const clickableObjects = []; // array of meshes
+
+function onPointerMove(event) {
+  // Normalize mouse coordinates (-1 to +1)
+  mouse.x = (event.clientX / window.innerWidth) * 2 - 1;
+  mouse.y = -(event.clientY / window.innerHeight) * 2 + 1;
+
+  // Update raycaster
+  raycaster.setFromCamera(mouse, camera);
+
+  // Find intersections
+  const intersects = raycaster.intersectObjects(clickableObjects);
+
+  if (intersects.length > 0) {
+    // Hover effect
+    intersects[0].object.material.emissive.setHex(0xff0000);
+  }
+}
+
+function onClick(event) {
+  mouse.x = (event.clientX / window.innerWidth) * 2 - 1;
+  mouse.y = -(event.clientY / window.innerHeight) * 2 + 1;
+
+  raycaster.setFromCamera(mouse, camera);
+  const intersects = raycaster.intersectObjects(clickableObjects);
+
+  if (intersects.length > 0) {
+    const object = intersects[0].object;
+    console.log('Clicked:', object.name);
+    console.log('Point:', intersects[0].point);
+  }
+}
+
+renderer.domElement.addEventListener('pointermove', onPointerMove);
+renderer.domElement.addEventListener('click', onClick);
+```
+
+## DragControls (Addon)
+
+Drag objects with mouse:
+
+```javascript
+import { DragControls } from 'three/addons/controls/DragControls.js';
+
+const controls = new DragControls(objectsArray, camera, renderer.domElement);
+
+// Events
+controls.addEventListener('dragstart', (event) => {
+  orbitControls.enabled = false; // disable camera controls during drag
+  event.object.material.emissive.set(0xaaaaaa);
+});
+
+controls.addEventListener('drag', (event) => {
+  console.log(event.object.position);
+});
+
+controls.addEventListener('dragend', (event) => {
+  orbitControls.enabled = true;
+  event.object.material.emissive.set(0x000000);
+});
+```
+
+## TransformControls (Addon)
+
+Interactive 3D gizmo for translate/rotate/scale:
+
+```javascript
+import { TransformControls } from 'three/addons/controls/TransformControls.js';
+
+const transformControls = new TransformControls(camera, renderer.domElement);
+scene.add(transformControls);
+
+// Attach to object
+transformControls.attach(mesh);
+
+// Switch modes
+transformControls.setMode('translate'); // or 'rotate', 'scale'
+
+// Switch space
+transformControls.setSpace('world'); // or 'local'
+
+// Events
+transformControls.addEventListener('change', () => {
+  renderer.render(scene, camera);
+});
+
+transformControls.addEventListener('dragging-changed', (event) => {
+  orbitControls.enabled = !event.value; // disable orbit during transform
+});
+
+// Keyboard shortcuts
+window.addEventListener('keydown', (event) => {
+  switch (event.key) {
+    case 'g': transformControls.setMode('translate'); break;
+    case 'r': transformControls.setMode('rotate'); break;
+    case 's': transformControls.setMode('scale'); break;
+    case 'x': transformControls.showX = !transformControls.showX; break;
+    case 'Escape': transformControls.detach(); break;
+  }
+});
+```
+
+## Selection Box (Addon)
+
+Box selection for multiple objects:
+
+```javascript
+import { SelectionBox } from 'three/addons/interactive/SelectionBox.js';
+import { SelectionHelper } from 'three/addons/interactive/SelectionHelper.js';
+
+const selectionBox = new SelectionBox(camera, scene);
+const helper = new SelectionHelper(renderer, 'selectBox');
+
+let isSelecting = false;
+
+renderer.domElement.addEventListener('pointerdown', (event) => {
+  isSelecting = true;
+  selectionBox.startPoint.set(
+    (event.clientX / window.innerWidth) * 2 - 1,
+    -(event.clientY / window.innerHeight) * 2 + 1,
+    0.5
+  );
+});
+
+renderer.domElement.addEventListener('pointermove', (event) => {
+  if (isSelecting) {
+    selectionBox.endPoint.set(
+      (event.clientX / window.innerWidth) * 2 - 1,
+      -(event.clientY / window.innerHeight) * 2 + 1,
+      0.5
+    );
+    const allSelected = selectionBox.select();
+    console.log('Selected:', allSelected.length);
+  }
+});
+
+renderer.domElement.addEventListener('pointerup', () => {
+  isSelecting = false;
+});
+```
+
+## Keyboard Input
+
+Handle keyboard controls:
+
+```javascript
+const keysPressed = {};
+
+window.addEventListener('keydown', (event) => {
+  keysPressed[event.key] = true;
+});
+
+window.addEventListener('keyup', (event) => {
+  keysPressed[event.key] = false;
+});
+
+// In animation loop
+function animate() {
+  const speed = 0.1;
+
+  if (keysPressed['w']) object.position.z -= speed;
+  if (keysPressed['s']) object.position.z += speed;
+  if (keysPressed['a']) object.position.x -= speed;
+  if (keysPressed['d']) object.position.x += speed;
+
+  renderer.render(scene, camera);
+  requestAnimationFrame(animate);
+}
+```
+
+## Pointer Lock (First Person)
+
+Lock pointer for FPS controls:
+
+```javascript
+import { PointerLockControls } from 'three/addons/controls/PointerLockControls.js';
+
+const controls = new PointerLockControls(camera, renderer.domElement);
+
+// Lock on click
+renderer.domElement.addEventListener('click', () => {
+  controls.lock();
+});
+
+controls.addEventListener('lock', () => {
+  console.log('Pointer locked');
+});
+
+controls.addEventListener('unlock', () => {
+  console.log('Pointer unlocked');
+});
+
+// Movement
+const velocity = new THREE.Vector3();
+const direction = new THREE.Vector3();
+
+function animate() {
+  if (controls.isLocked) {
+    // Apply movement
+    controls.moveForward(velocity.z);
+    controls.moveRight(velocity.x);
+  }
+  renderer.render(scene, camera);
+  requestAnimationFrame(animate);
+}
+```
+
+## Object Highlighting
+
+Visual feedback on hover/selection:
+
+```javascript
+let hoveredObject = null;
+const originalEmissive = new THREE.Color();
+
+function onPointerMove(event) {
+  mouse.x = (event.clientX / window.innerWidth) * 2 - 1;
+  mouse.y = -(event.clientY / window.innerHeight) * 2 + 1;
+
+  raycaster.setFromCamera(mouse, camera);
+  const intersects = raycaster.intersectObjects(scene.children, true);
+
+  // Reset previous
+  if (hoveredObject) {
+    hoveredObject.material.emissive.copy(originalEmissive);
+    hoveredObject = null;
+  }
+
+  // Highlight new
+  if (intersects.length > 0) {
+    hoveredObject = intersects[0].object;
+    originalEmissive.copy(hoveredObject.material.emissive);
+    hoveredObject.material.emissive.setHex(0x555555);
+  }
+
+  renderer.domElement.style.cursor = hoveredObject ? 'pointer' : 'default';
+}
+```
+
+## Tooltips & UI Overlays
+
+Show HTML tooltip at 3D position:
+
+```javascript
+function updateTooltip(object3D, text) {
+  const vector = object3D.position.clone();
+  vector.project(camera);
+
+  const x = (vector.x * 0.5 + 0.5) * window.innerWidth;
+  const y = (-vector.y * 0.5 + 0.5) * window.innerHeight;
+
+  tooltip.style.left = x + 'px';
+  tooltip.style.top = y + 'px';
+  tooltip.textContent = text;
+}
+```

package/.claude/skills/threejs/references/09-postprocessing.md

@@ -0,0 +1,240 @@
+# Post-Processing
+
+Apply visual effects after rendering.
+
+## EffectComposer Setup
+
+Post-processing pipeline (addon):
+
+```javascript
+import { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js';
+import { RenderPass } from 'three/addons/postprocessing/RenderPass.js';
+import { OutputPass } from 'three/addons/postprocessing/OutputPass.js';
+
+// Create composer
+const composer = new EffectComposer(renderer);
+
+// Add render pass (required first pass)
+const renderPass = new RenderPass(scene, camera);
+composer.addPass(renderPass);
+
+// Add effect passes
+// ... (see below)
+
+// Add output pass (required last pass)
+const outputPass = new OutputPass();
+composer.addPass(outputPass);
+
+// Render with composer instead of renderer
+function animate() {
+  requestAnimationFrame(animate);
+  composer.render();
+}
+
+// Handle resize
+window.addEventListener('resize', () => {
+  composer.setSize(window.innerWidth, window.innerHeight);
+});
+```
+
+## Bloom Effect
+
+Glow effect for bright areas:
+
+```javascript
+import { UnrealBloomPass } from 'three/addons/postprocessing/UnrealBloomPass.js';
+
+const bloomPass = new UnrealBloomPass(
+  new THREE.Vector2(window.innerWidth, window.innerHeight),
+  1.5,  // strength
+  0.4,  // radius
+  0.85  // threshold (brightness trigger)
+);
+composer.addPass(bloomPass);
+
+// Adjust parameters
+bloomPass.strength = 2.0;
+bloomPass.radius = 1.0;
+bloomPass.threshold = 0.5;
+```
+
+## SSAO (Screen Space Ambient Occlusion)
+
+Realistic shadowing in crevices:
+
+```javascript
+import { SSAOPass } from 'three/addons/postprocessing/SSAOPass.js';
+
+const ssaoPass = new SSAOPass(scene, camera, width, height);
+ssaoPass.kernelRadius = 16;
+ssaoPass.minDistance = 0.005;
+ssaoPass.maxDistance = 0.1;
+composer.addPass(ssaoPass);
+```
+
+## SSR (Screen Space Reflections)
+
+Real-time reflections:
+
+```javascript
+import { SSRPass } from 'three/addons/postprocessing/SSRPass.js';
+
+const ssrPass = new SSRPass({
+  renderer,
+  scene,
+  camera,
+  width: window.innerWidth,
+  height: window.innerHeight
+});
+
+ssrPass.opacity = 0.5;
+ssrPass.maxDistance = 0.1;
+composer.addPass(ssrPass);
+```
+
+## Depth of Field (Bokeh)
+
+Blur based on depth:
+
+```javascript
+import { BokehPass } from 'three/addons/postprocessing/BokehPass.js';
+
+const bokehPass = new BokehPass(scene, camera, {
+  focus: 10.0,      // focal distance
+  aperture: 0.025,  // blur amount
+  maxblur: 0.01     // max blur size
+});
+composer.addPass(bokehPass);
+```
+
+## FXAA (Anti-Aliasing)
+
+Smooth jagged edges:
+
+```javascript
+import { ShaderPass } from 'three/addons/postprocessing/ShaderPass.js';
+import { FXAAShader } from 'three/addons/shaders/FXAAShader.js';
+
+const fxaaPass = new ShaderPass(FXAAShader);
+fxaaPass.material.uniforms['resolution'].value.x = 1 / window.innerWidth;
+fxaaPass.material.uniforms['resolution'].value.y = 1 / window.innerHeight;
+composer.addPass(fxaaPass);
+```
+
+## Outline Pass
+
+Highlight selected objects:
+
+```javascript
+import { OutlinePass } from 'three/addons/postprocessing/OutlinePass.js';
+
+const outlinePass = new OutlinePass(
+  new THREE.Vector2(window.innerWidth, window.innerHeight),
+  scene,
+  camera
+);
+
+outlinePass.edgeStrength = 3;
+outlinePass.edgeGlow = 0.5;
+outlinePass.edgeThickness = 1;
+outlinePass.visibleEdgeColor.set('#ffffff');
+outlinePass.hiddenEdgeColor.set('#190a05');
+
+// Set objects to outline
+outlinePass.selectedObjects = [mesh1, mesh2];
+
+composer.addPass(outlinePass);
+```
+
+## Film/Grain Effect
+
+Add film grain and scanlines:
+
+```javascript
+import { FilmPass } from 'three/addons/postprocessing/FilmPass.js';
+
+const filmPass = new FilmPass(
+  0.35,  // noise intensity
+  0.5,   // scanline intensity
+  648,   // scanline count
+  false  // grayscale
+);
+composer.addPass(filmPass);
+```
+
+## Glitch Effect
+
+Digital glitch distortion:
+
+```javascript
+import { GlitchPass } from 'three/addons/postprocessing/GlitchPass.js';
+
+const glitchPass = new GlitchPass();
+composer.addPass(glitchPass);
+```
+
+## Custom Shader Pass
+
+Create custom effects:
+
+```javascript
+import { ShaderPass } from 'three/addons/postprocessing/ShaderPass.js';
+
+const customShader = {
+  uniforms: {
+    tDiffuse: { value: null },
+    amount: { value: 1.0 }
+  },
+  vertexShader: `
+    varying vec2 vUv;
+    void main() {
+      vUv = uv;
+      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+    }
+  `,
+  fragmentShader: `
+    uniform sampler2D tDiffuse;
+    uniform float amount;
+    varying vec2 vUv;
+
+    void main() {
+      vec4 color = texture2D(tDiffuse, vUv);
+      // Apply custom effect
+      color.r *= amount;
+      gl_FragColor = color;
+    }
+  `
+};
+
+const customPass = new ShaderPass(customShader);
+customPass.material.uniforms.amount.value = 1.5;
+composer.addPass(customPass);
+```
+
+## Common Pass Patterns
+
+```javascript
+// Combine multiple effects
+composer.addPass(renderPass);
+composer.addPass(ssaoPass);
+composer.addPass(bloomPass);
+composer.addPass(fxaaPass);
+composer.addPass(outputPass);
+
+// Selective rendering
+bloomPass.renderToScreen = false; // render to texture, not screen
+
+// Clear pass
+import { ClearPass } from 'three/addons/postprocessing/ClearPass.js';
+const clearPass = new ClearPass();
+composer.addPass(clearPass);
+```
+
+## Performance Tips
+
+- Post-processing is GPU-intensive
+- Use lower resolution for expensive effects (SSAO, SSR)
+- Limit number of passes (3-5 for good performance)
+- Disable passes when not needed
+- Use FXAA instead of MSAA (cheaper)
+- Test on target devices