sinapse-ai 1.0.0

package/squad-animations/tasks/implement-lod-system.md

@@ -0,0 +1,185 @@
+---
+task: implement-lod-system
+responsavel: "@threejs-architect"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+
+Entrada:
+  - campo: scene_setup
+    tipo: code
+    origem: "setup-threejs-scene"
+    obrigatorio: true
+  - campo: models
+    tipo: array
+    origem: "load-3d-models"
+    obrigatorio: true
+
+Saida:
+  - campo: lod_system
+    tipo: code
+    destino: "animation-performance-engineer"
+
+Checklist:
+  - "[ ] Criar LOD groups para modelos pesados"
+  - "[ ] Definir distancias de transicao"
+  - "[ ] Implementar instancing para objetos repetidos"
+  - "[ ] Configurar frustum culling"
+  - "[ ] Testar transicoes suaves entre niveis"
+---
+
+# Task: Implement LOD System
+
+## Metadata
+- **Agent:** threejs-architect (Vertex)
+- **Squad:** squad-animations
+- **Complexity:** HIGH
+
+## Objetivo
+Implementar Level of Detail (LOD) — diferentes niveis de qualidade geometrica baseados na distancia da camera. Essencial para cenas com muitos objetos ou modelos complexos.
+
+## Pre-Conditions
+- Modelos carregados com diferentes resolutions disponiveis
+- Cena com objetos em diferentes distancias
+- Performance issue identificada ou prevenida
+- Camera system configurado
+
+## Passos
+
+### 1. Criar LOD Group
+```javascript
+const lod = new THREE.LOD();
+// High detail (perto)
+lod.addLevel(highDetailMesh, 0);
+// Medium detail
+lod.addLevel(mediumDetailMesh, 10);
+// Low detail (longe)
+lod.addLevel(lowDetailMesh, 25);
+// Invisible (muito longe)
+lod.addLevel(new THREE.Object3D(), 50);
+scene.add(lod);
+```
+
+### 2. Definir Distancias por Tipo de Objeto
+| Objeto | LOD0 (high) | LOD1 (medium) | LOD2 (low) | Cull |
+|--------|-------------|---------------|------------|------|
+| Hero object | 0 | 15 | 30 | 60 |
+| Secondary | 0 | 8 | 20 | 40 |
+| Background | 0 | 5 | 12 | 25 |
+| Vegetation | 0 | 6 | 15 | 30 |
+
+### 3. Gerar LOD Meshes
+```javascript
+// Simplificar geometria programaticamente
+import { SimplifyModifier } from 'three/addons/modifiers/SimplifyModifier';
+
+const modifier = new SimplifyModifier();
+const lod1Geometry = modifier.modify(
+  originalGeometry,
+  Math.floor(originalGeometry.attributes.position.count * 0.5) // 50%
+);
+const lod2Geometry = modifier.modify(
+  originalGeometry,
+  Math.floor(originalGeometry.attributes.position.count * 0.25) // 25%
+);
+```
+
+### 4. Implementar InstancedMesh
+```javascript
+// Para objetos repetidos (arvores, rochas, particulas)
+const instancedMesh = new THREE.InstancedMesh(geometry, material, count);
+const matrix = new THREE.Matrix4();
+for (let i = 0; i < count; i++) {
+  matrix.setPosition(positions[i]);
+  matrix.scale(scales[i]);
+  instancedMesh.setMatrixAt(i, matrix);
+}
+instancedMesh.instanceMatrix.needsUpdate = true;
+```
+
+### 5. Frustum Culling
+```javascript
+// Habilitado por default em Object3D
+mesh.frustumCulled = true; // Default
+// Para objetos com vertex displacement (shader), pode precisar:
+mesh.geometry.computeBoundingSphere();
+// Ou expandir bounding sphere manualmente:
+mesh.geometry.boundingSphere.radius *= 1.5;
+```
+
+### 6. LOD Update no Render Loop
+```javascript
+function animate() {
+  // LOD auto-updates baseado na camera
+  scene.traverse((child) => {
+    if (child.isLOD) {
+      child.update(camera);
+    }
+  });
+  renderer.render(scene, camera);
+}
+```
+
+### 7. Material LOD
+```javascript
+// Simplificar materiais em LODs distantes
+const lod0Mat = new THREE.MeshStandardMaterial({
+  map: texture, normalMap: normalMap, roughnessMap: roughMap
+});
+const lod1Mat = new THREE.MeshStandardMaterial({
+  map: texture // Sem normal/roughness maps
+});
+const lod2Mat = new THREE.MeshBasicMaterial({
+  map: texture // Sem lighting
+});
+```
+
+### 8. Merge Distant Objects
+```javascript
+import { mergeGeometries } from 'three/addons/utils/BufferGeometryUtils';
+// Merge geometrias de objetos distantes em um unico mesh
+const merged = mergeGeometries(distantGeometries);
+const mergedMesh = new THREE.Mesh(merged, sharedMaterial);
+```
+
+### 9. Adaptive LOD (Device-Based)
+```javascript
+function getDeviceLODBias() {
+  const isMobile = /Android|iPhone/i.test(navigator.userAgent);
+  const isLowEnd = navigator.hardwareConcurrency <= 4;
+  if (isMobile || isLowEnd) return 0.5; // Use lower LOD sooner
+  return 1.0;
+}
+const bias = getDeviceLODBias();
+lod.addLevel(highMesh, 0 * bias);
+lod.addLevel(medMesh, 10 * bias);
+```
+
+### 10. Monitorar LOD Performance
+```javascript
+function logLODStats() {
+  const info = renderer.info;
+  console.log(`Triangles: ${info.render.triangles}`);
+  console.log(`Draw calls: ${info.render.calls}`);
+  console.log(`Textures: ${info.memory.textures}`);
+  console.log(`Geometries: ${info.memory.geometries}`);
+}
+```
+
+## Output
+- LOD groups configurados com distancias
+- InstancedMesh para objetos repetidos
+- Material LOD (simplificado por distancia)
+- Frustum culling otimizado
+- Device-adaptive LOD bias
+- Performance monitoring
+
+## Quality Criteria
+- [ ] LOD transitions nao visiveis (distancia correta)
+- [ ] InstancedMesh para 10+ objetos iguais
+- [ ] Frustum culling ativo em todos meshes
+- [ ] Triangle count reduzido em 50%+ com LOD
+- [ ] Draw calls reduzidos com merge/instancing
+- [ ] Mobile: LOD mais agressivo
+- [ ] Bounding spheres corretas (shader displacement)
+- [ ] 60fps alcancado com LOD system ativo

package/squad-animations/tasks/implement-page-transition.md

@@ -0,0 +1,193 @@
+---
+task: implement-page-transition
+responsavel: "@scroll-narrative-engineer"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+
+Entrada:
+  - campo: transition_spec
+    tipo: object
+    origem: "animation_brief"
+    obrigatorio: true
+
+Saida:
+  - campo: page_transition
+    tipo: code
+    destino: "review-animation-quality"
+
+Checklist:
+  - "[ ] Selecionar lib (Barba.js, Swup, View Transitions API)"
+  - "[ ] Implementar animacao de saida (leave)"
+  - "[ ] Implementar animacao de entrada (enter)"
+  - "[ ] Configurar shared elements se necessario"
+  - "[ ] Garantir cleanup de ScrollTrigger entre paginas"
+  - "[ ] Testar navegacao back/forward"
+---
+
+# Task: Implement Page Transition
+
+## Metadata
+- **Agent:** scroll-narrative-engineer (Parallax)
+- **Squad:** squad-animations
+- **Complexity:** HIGH
+
+## Objetivo
+Implementar transicoes entre paginas — animacoes de saida e entrada que criam continuidade durante navegacao. Usar View Transitions API, Barba.js ou Swup dependendo do stack.
+
+## Pre-Conditions
+- Framework/stack definido (MPA, SPA, Next.js)
+- Tipo de transicao desejado (fade, slide, morph, overlay)
+- Shared elements identificados (se houver)
+- ScrollTrigger cleanup strategy
+
+## Passos
+
+### 1. Selecionar Approach
+| Stack | Approach | Lib |
+|-------|----------|-----|
+| MPA (multi-page) | View Transitions API | Nativo |
+| MPA + fallback | Barba.js | barba.js |
+| SPA (React) | Framer Motion AnimatePresence | framer-motion |
+| SPA (Next.js) | App Router + View Transitions | Nativo |
+| SPA (generic) | Swup | swup |
+
+### 2. View Transitions API (Modern)
+```javascript
+// Interceptar navegacao
+document.addEventListener('click', (e) => {
+  const link = e.target.closest('a[href]');
+  if (!link || link.origin !== location.origin) return;
+  e.preventDefault();
+  if (!document.startViewTransition) {
+    location.href = link.href;
+    return;
+  }
+  document.startViewTransition(async () => {
+    const response = await fetch(link.href);
+    const html = await response.text();
+    document.documentElement.innerHTML = html;
+  });
+});
+```
+
+### 3. CSS para View Transitions
+```css
+::view-transition-old(root) {
+  animation: fade-out 200ms ease-in;
+}
+::view-transition-new(root) {
+  animation: fade-in 300ms ease-out;
+}
+@keyframes fade-out { to { opacity: 0; } }
+@keyframes fade-in { from { opacity: 0; } }
+```
+
+### 4. Shared Element Transitions
+```css
+/* Page A */
+.product-card { view-transition-name: product-hero; }
+/* Page B */
+.product-detail-image { view-transition-name: product-hero; }
+/* Transition */
+::view-transition-group(product-hero) {
+  animation-duration: 400ms;
+}
+```
+
+### 5. Barba.js Setup
+```javascript
+import barba from '@barba/core';
+import gsap from 'gsap';
+
+barba.init({
+  transitions: [{
+    leave(data) {
+      return gsap.to(data.current.container, {
+        opacity: 0, y: -20, duration: 0.3,
+      });
+    },
+    enter(data) {
+      return gsap.from(data.next.container, {
+        opacity: 0, y: 20, duration: 0.4,
+      });
+    },
+  }],
+});
+```
+
+### 6. ScrollTrigger Cleanup entre Paginas
+```javascript
+barba.hooks.beforeLeave(() => {
+  ScrollTrigger.getAll().forEach(st => st.kill());
+  lenis?.destroy();
+});
+barba.hooks.afterEnter(() => {
+  ScrollTrigger.refresh();
+  // Re-initialize scroll animations for new page
+  initScrollAnimations();
+});
+```
+
+### 7. Overlay Transition Pattern
+```javascript
+// Overlay que cobre, troca conteudo, revela
+barba.init({
+  transitions: [{
+    async leave() {
+      await gsap.to('.transition-overlay', {
+        scaleY: 1, transformOrigin: 'bottom', duration: 0.4,
+      });
+    },
+    async enter() {
+      await gsap.to('.transition-overlay', {
+        scaleY: 0, transformOrigin: 'top', duration: 0.4, delay: 0.1,
+      });
+    },
+  }],
+});
+```
+
+### 8. Loading State During Transition
+```javascript
+barba.hooks.before(() => {
+  document.body.classList.add('is-transitioning');
+});
+barba.hooks.after(() => {
+  document.body.classList.remove('is-transitioning');
+});
+```
+
+### 9. Back/Forward Navigation
+- View Transitions API: handled automatically by browser
+- Barba.js: `barba.history` tracks navigation
+- Testar: transicao deve funcionar em ambas direcoes
+- Scroll position: restaurar ao voltar
+
+### 10. Reduced Motion
+```css
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-old(root),
+  ::view-transition-new(root) {
+    animation: none;
+  }
+}
+```
+
+## Output
+- Page transition implementation (View Transitions/Barba/Swup)
+- Leave e enter animations
+- Shared element transitions se aplicavel
+- ScrollTrigger cleanup hooks
+- Overlay transition se solicitado
+- Reduced motion fallback
+
+## Quality Criteria
+- [ ] Transicao suave sem flash de conteudo
+- [ ] ScrollTrigger cleanup entre paginas
+- [ ] Back/forward navigation funciona
+- [ ] Shared elements morph corretamente
+- [ ] Loading state se transicao demora
+- [ ] prefers-reduced-motion: instant swap
+- [ ] Scroll position restaurada em back
+- [ ] 60fps durante transicao

package/squad-animations/tasks/implement-physics-simulation.md

@@ -0,0 +1,262 @@
+---
+task: implement-physics-simulation
+responsavel: "@generative-particle-engineer"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+
+Entrada:
+  - campo: physics_spec
+    tipo: object
+    origem: "animation_brief"
+    obrigatorio: true
+
+Saida:
+  - campo: physics_simulation
+    tipo: code
+    destino: "animation-performance-engineer"
+
+Checklist:
+  - "[ ] Selecionar engine (custom, cannon-es, rapier)"
+  - "[ ] Implementar forces e constraints"
+  - "[ ] Configurar collision detection"
+  - "[ ] Sincronizar com render loop"
+  - "[ ] Otimizar timestep fixo"
+---
+
+# Task: Implement Physics Simulation
+
+## Metadata
+- **Agent:** generative-particle-engineer (Cloud)
+- **Squad:** squad-animations
+- **Complexity:** HIGH
+
+## Objetivo
+Implementar simulacao de fisica para animacoes — gravity, collision, constraints, soft body, cloth ou fluids. Selecionar engine correta (custom lightweight vs full physics library), sincronizar com render loop e otimizar timestep.
+
+## Pre-Conditions
+- Tipo de simulacao definido (rigid body, soft body, cloth, fluid, ragdoll)
+- Three.js scene configurada (se 3D)
+- Complexidade estimada (poucos objetos vs centenas)
+- Target devices definidos (afeta engine choice)
+
+## Passos
+
+### 1. Selecionar Engine
+| Engine | Tipo | Bundle Size | Melhor Para |
+|--------|------|-------------|-------------|
+| Custom (Verlet) | Lightweight | 0 KB | Pontos, springs, cloth simples |
+| cannon-es | Rigid body | ~150 KB | Boxes, spheres, compound shapes |
+| Rapier (WASM) | Full physics | ~250 KB | Performance critica, complex sim |
+| Oimo.js | Rigid body | ~100 KB | Simples, leve |
+| Matter.js | 2D physics | ~80 KB | 2D scenes, DOM elements |
+| Custom SPH | Fluid | 0 KB | Fluid sim (advanced) |
+
+### 2. Implementar Verlet Integration (Custom)
+```javascript
+class VerletParticle {
+  constructor(x, y, z) {
+    this.position = new THREE.Vector3(x, y, z);
+    this.previous = this.position.clone();
+    this.acceleration = new THREE.Vector3();
+    this.mass = 1;
+    this.pinned = false;
+  }
+  update(dt) {
+    if (this.pinned) return;
+    const velocity = this.position.clone().sub(this.previous);
+    this.previous.copy(this.position);
+    this.position.add(velocity);
+    this.position.add(this.acceleration.multiplyScalar(dt * dt));
+    this.acceleration.set(0, 0, 0);
+  }
+  applyForce(force) {
+    this.acceleration.add(force.clone().divideScalar(this.mass));
+  }
+}
+```
+
+### 3. Implementar Constraints
+```javascript
+class DistanceConstraint {
+  constructor(p1, p2, restLength, stiffness = 1) {
+    this.p1 = p1;
+    this.p2 = p2;
+    this.restLength = restLength ?? p1.position.distanceTo(p2.position);
+    this.stiffness = stiffness;
+  }
+  solve() {
+    const diff = this.p2.position.clone().sub(this.p1.position);
+    const dist = diff.length();
+    const correction = diff.multiplyScalar((dist - this.restLength) / dist * 0.5 * this.stiffness);
+    if (!this.p1.pinned) this.p1.position.add(correction);
+    if (!this.p2.pinned) this.p2.position.sub(correction);
+  }
+}
+// Solve constraints multiple iterations for stability
+for (let i = 0; i < solverIterations; i++) {
+  constraints.forEach(c => c.solve());
+}
+```
+
+### 4. Configurar Cannon-es (Rigid Body)
+```javascript
+import * as CANNON from 'cannon-es';
+
+const world = new CANNON.World({ gravity: new CANNON.Vec3(0, -9.82, 0) });
+world.broadphase = new CANNON.SAPBroadphase(world);
+world.solver.iterations = 10;
+
+// Create body
+const body = new CANNON.Body({
+  mass: 1,
+  shape: new CANNON.Sphere(0.5),
+  position: new CANNON.Vec3(0, 10, 0),
+  material: new CANNON.Material({ friction: 0.3, restitution: 0.5 }),
+});
+world.addBody(body);
+
+// Ground plane
+const ground = new CANNON.Body({
+  mass: 0, // Static
+  shape: new CANNON.Plane(),
+});
+ground.quaternion.setFromEuler(-Math.PI / 2, 0, 0);
+world.addBody(ground);
+```
+
+### 5. Sincronizar Physics com Three.js
+```javascript
+// Fixed timestep physics loop
+const fixedDt = 1 / 60;
+let accumulator = 0;
+
+function animate(time) {
+  const dt = clock.getDelta();
+  accumulator += dt;
+
+  while (accumulator >= fixedDt) {
+    world.step(fixedDt);
+    accumulator -= fixedDt;
+  }
+
+  // Interpolate for smooth rendering
+  const alpha = accumulator / fixedDt;
+  bodies.forEach((body, i) => {
+    meshes[i].position.lerpVectors(body.previousPosition, body.position, alpha);
+    meshes[i].quaternion.slerpQuaternions(body.previousQuaternion, body.quaternion, alpha);
+  });
+
+  renderer.render(scene, camera);
+  requestAnimationFrame(animate);
+}
+```
+
+### 6. Implementar Cloth Simulation
+```javascript
+// Grid of Verlet particles with distance constraints
+function createCloth(widthSegments, heightSegments, spacing) {
+  const particles = [];
+  const constraints = [];
+
+  for (let y = 0; y <= heightSegments; y++) {
+    for (let x = 0; x <= widthSegments; x++) {
+      const p = new VerletParticle(x * spacing, -y * spacing, 0);
+      if (y === 0) p.pinned = true; // Pin top row
+      particles.push(p);
+    }
+  }
+
+  // Structural constraints (horizontal + vertical)
+  // Shear constraints (diagonal)
+  // Bend constraints (skip one) for stiffness
+  // ... connect neighbors
+
+  return { particles, constraints };
+}
+```
+
+### 7. Collision Detection
+| Tipo | Algoritmo | Performance |
+|------|-----------|-------------|
+| Sphere-sphere | Distance check | O(1) per pair |
+| AABB | Overlap test | O(1) per pair |
+| Broadphase | Spatial hash / SAP | O(n log n) |
+| Narrowphase | GJK / EPA | O(faces) |
+| Point-plane | Dot product | O(1) |
+| Ray-mesh | BVH traversal | O(log n) |
+
+```javascript
+// Simple sphere collision
+function resolveSphereCollision(p1, p2, r1, r2) {
+  const diff = p1.position.clone().sub(p2.position);
+  const dist = diff.length();
+  const minDist = r1 + r2;
+  if (dist < minDist) {
+    const correction = diff.normalize().multiplyScalar((minDist - dist) * 0.5);
+    p1.position.add(correction);
+    p2.position.sub(correction);
+  }
+}
+```
+
+### 8. Forces e Interacao
+| Force | Implementacao | Uso |
+|-------|--------------|-----|
+| Gravity | `vel.y -= 9.82 * dt` | Universal |
+| Wind | `force = windDir * strength * noise(time)` | Cloth, particulas |
+| Mouse attract | `force = (mouse - pos).normalize() * strength / dist` | Interactive |
+| Spring | `force = -k * (dist - rest) * dir` | Soft body, connections |
+| Damping | `vel *= (1 - damping * dt)` | Estabilizacao |
+| Buoyancy | `force.y = volume * density * g` | Flutuacao |
+
+### 9. Debug Visualization
+```javascript
+// Wireframe helpers for physics shapes
+function debugPhysics(world, scene) {
+  const debugMaterial = new THREE.LineBasicMaterial({ color: 0x00ff00 });
+  world.bodies.forEach(body => {
+    body.shapes.forEach(shape => {
+      const helper = createShapeHelper(shape, debugMaterial);
+      helper.position.copy(body.position);
+      helper.quaternion.copy(body.quaternion);
+      scene.add(helper);
+    });
+  });
+}
+```
+
+### 10. Cleanup e Reduced Motion
+```javascript
+function dispose() {
+  world.bodies.forEach(b => world.removeBody(b));
+  constraints.forEach(c => world.removeConstraint(c));
+  cancelAnimationFrame(animId);
+}
+
+// Reduced motion: show final resting state, skip simulation
+if (prefersReducedMotion) {
+  // Place objects at rest positions
+  // Skip animation loop
+}
+```
+
+## Output
+- Physics simulation funcional com engine selecionada
+- Forces configuradas (gravity, wind, attraction, springs)
+- Constraints implementados (distance, hinge, lock)
+- Collision detection funcional
+- Sincronizacao smooth com render loop (interpolation)
+- Fixed timestep loop estavel
+- Debug visualization helpers
+- Cleanup/dispose functions
+
+## Quality Criteria
+- [ ] Engine correta para complexidade da simulacao
+- [ ] Fixed timestep (deterministic, frame-rate independent)
+- [ ] Interpolacao entre physics steps (smooth rendering)
+- [ ] Constraints estaveis (sem jitter, sem explosao)
+- [ ] Collision detection funcional
+- [ ] 60fps no target device
+- [ ] Memoria limpa no dispose
+- [ ] Reduced motion: estado estatico final