sinapse-ai 1.0.0

package/squad-animations/tasks/build-sdf-visualization.md

@@ -0,0 +1,176 @@
+---
+task: build-sdf-visualization
+responsavel: "@shader-artist"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+
+Entrada:
+  - campo: sdf_spec
+    tipo: object
+    origem: "animation_brief"
+    obrigatorio: true
+
+Saida:
+  - campo: sdf_shader
+    tipo: code
+    destino: "threejs-architect"
+
+Checklist:
+  - "[ ] Implementar SDFs primitivos necessarios"
+  - "[ ] Aplicar operacoes booleanas (union, subtraction, intersection)"
+  - "[ ] Implementar ray marching loop"
+  - "[ ] Calcular normais e iluminacao"
+  - "[ ] Adicionar smooth blending entre formas"
+  - "[ ] Animar morfologia com time"
+---
+
+# Task: Build SDF Visualization
+
+## Metadata
+- **Agent:** shader-artist (Fragment)
+- **Squad:** squad-animations
+- **Complexity:** HIGH
+
+## Objetivo
+Criar visualizacoes usando Signed Distance Functions — formas 3D procedurais renderizadas via ray marching, sem geometria mesh. Permite formas organicas, smooth morphing e operacoes booleanas impossveis com mesh tradicional.
+
+## Pre-Conditions
+- Formas desejadas definidas (esferas, boxes, toruses, combinacoes)
+- Estilo visual (realista, stylized, wireframe, glow)
+- Animation type (morph, rotate, pulse)
+- Performance target (ray marching e GPU-intensive)
+
+## Passos
+
+### 1. Implementar SDF Primitivos
+```glsl
+float sdSphere(vec3 p, float r) {
+  return length(p) - r;
+}
+float sdBox(vec3 p, vec3 b) {
+  vec3 q = abs(p) - b;
+  return length(max(q, 0.0)) + min(max(q.x, max(q.y, q.z)), 0.0);
+}
+float sdTorus(vec3 p, vec2 t) {
+  vec2 q = vec2(length(p.xz) - t.x, p.y);
+  return length(q) - t.y;
+}
+```
+
+### 2. Implementar Operacoes Booleanas
+```glsl
+float opUnion(float d1, float d2) { return min(d1, d2); }
+float opSubtraction(float d1, float d2) { return max(-d1, d2); }
+float opIntersection(float d1, float d2) { return max(d1, d2); }
+// Smooth union - organic blending
+float opSmoothUnion(float d1, float d2, float k) {
+  float h = clamp(0.5 + 0.5 * (d2 - d1) / k, 0.0, 1.0);
+  return mix(d2, d1, h) - k * h * (1.0 - h);
+}
+```
+
+### 3. Implementar Scene SDF
+```glsl
+float sceneSDF(vec3 p) {
+  float sphere = sdSphere(p - vec3(0.0, 0.0, 0.0), 0.5);
+  float box = sdBox(p - vec3(1.0, 0.0, 0.0), vec3(0.3));
+  return opSmoothUnion(sphere, box, 0.3);
+}
+```
+
+### 4. Implementar Ray Marching
+```glsl
+float rayMarch(vec3 ro, vec3 rd) {
+  float t = 0.0;
+  for (int i = 0; i < 100; i++) {
+    vec3 p = ro + rd * t;
+    float d = sceneSDF(p);
+    if (d < 0.001) break;
+    if (t > 20.0) break;
+    t += d;
+  }
+  return t;
+}
+```
+
+### 5. Calcular Normais
+```glsl
+vec3 calcNormal(vec3 p) {
+  vec2 e = vec2(0.001, 0.0);
+  return normalize(vec3(
+    sceneSDF(p + e.xyy) - sceneSDF(p - e.xyy),
+    sceneSDF(p + e.yxy) - sceneSDF(p - e.yxy),
+    sceneSDF(p + e.yyx) - sceneSDF(p - e.yyx)
+  ));
+}
+```
+
+### 6. Implementar Iluminacao
+```glsl
+vec3 lighting(vec3 p, vec3 normal, vec3 rd) {
+  vec3 lightDir = normalize(vec3(1.0, 1.0, -1.0));
+  float diff = max(dot(normal, lightDir), 0.0);
+  float spec = pow(max(dot(reflect(-lightDir, normal), -rd), 0.0), 32.0);
+  vec3 ambient = vec3(0.1);
+  return ambient + diff * vec3(0.8) + spec * vec3(0.3);
+}
+```
+
+### 7. Animar com Time
+```glsl
+float sceneSDF(vec3 p) {
+  // Morph between shapes
+  float t = sin(uTime * 0.5) * 0.5 + 0.5;
+  float sphere = sdSphere(p, 0.5);
+  float box = sdBox(p, vec3(0.4));
+  return mix(sphere, box, t);
+}
+```
+
+### 8. Configurar Camera
+```glsl
+void main() {
+  vec2 uv = (gl_FragCoord.xy - 0.5 * uResolution) / uResolution.y;
+  vec3 ro = vec3(0.0, 0.0, 3.0); // Camera position
+  vec3 rd = normalize(vec3(uv, -1.0)); // Ray direction
+  float t = rayMarch(ro, rd);
+  // Render
+}
+```
+
+### 9. Adicionar Post Effects (AO, Glow)
+```glsl
+// Simple AO
+float ao = 0.0;
+for (int i = 0; i < 5; i++) {
+  float h = 0.01 + 0.12 * float(i);
+  ao += (h - sceneSDF(p + normal * h));
+}
+ao = clamp(1.0 - ao, 0.0, 1.0);
+```
+
+### 10. Otimizar Ray Marching
+- Max steps: 64-100 (mais = mais lento)
+- Early exit distance: 20.0 (ajustar por cena)
+- Hit threshold: 0.001 (0.01 para mobile)
+- Render em resolucao menor e upscale se necessario
+- Mobile: reduzir max steps para 48
+
+## Output
+- Fragment shader completo com ray marching
+- SDF scene com primitivos e operacoes
+- Iluminacao e normais calculados
+- Animacao temporal (morph, rotation)
+- Camera setup e controls
+- Performance notes para mobile
+
+## Quality Criteria
+- [ ] Ray marching converge sem artifacts
+- [ ] Normais corretas (iluminacao realista)
+- [ ] Smooth union sem descontinuidades
+- [ ] Morph animation fluida
+- [ ] 30fps minimo em GPU integrada
+- [ ] Sem banding em gradients de iluminacao
+- [ ] Camera responsiva ao resize
+- [ ] Max steps otimizado por complexidade da cena

package/squad-animations/tasks/build-shadow-system.md

@@ -0,0 +1,155 @@
+---
+task: build-shadow-system
+responsavel: "@threejs-architect"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+
+Entrada:
+  - campo: lighting_setup
+    tipo: code
+    origem: "design-lighting-setup"
+    obrigatorio: true
+
+Saida:
+  - campo: shadow_system
+    tipo: code
+    destino: "animation-performance-engineer"
+
+Checklist:
+  - "[ ] Configurar shadow map type (PCFSoft, VSM)"
+  - "[ ] Ajustar shadow camera frustum"
+  - "[ ] Definir shadow map resolution"
+  - "[ ] Configurar shadow bias para evitar acne"
+  - "[ ] Implementar contact shadows se necessario"
+---
+
+# Task: Build Shadow System
+
+## Metadata
+- **Agent:** threejs-architect (Vertex)
+- **Squad:** squad-animations
+- **Complexity:** MEDIUM
+
+## Objetivo
+Configurar sistema de sombras Three.js — shadow maps, bias, camera frustum e contact shadows. Sombras adicionam grounding e profundidade mas sao o maior custo de performance em cenas 3D web.
+
+## Pre-Conditions
+- Lighting setup funcional
+- Tipo de sombra desejado (hard, soft, contact)
+- Performance budget (shadows custam caro)
+- Objetos que devem cast/receive shadows identificados
+
+## Passos
+
+### 1. Habilitar Shadows no Renderer
+```javascript
+renderer.shadowMap.enabled = true;
+renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+// Opcoes: BasicShadowMap | PCFShadowMap | PCFSoftShadowMap | VSMShadowMap
+```
+
+### 2. Selecionar Shadow Map Type
+| Type | Qualidade | Performance | Nota |
+|------|----------|-------------|------|
+| BasicShadowMap | Baixa (pixelada) | Rapido | Dev only |
+| PCFShadowMap | Media | Medio | Acceptable |
+| PCFSoftShadowMap | Alta (soft edges) | Medio-Alto | Recomendado |
+| VSMShadowMap | Alta (very soft) | Alto | Bleed artifacts |
+
+### 3. Configurar Shadow na Light
+```javascript
+const light = new THREE.DirectionalLight(0xffffff, 1.5);
+light.castShadow = true;
+light.shadow.mapSize.set(2048, 2048); // Resolution
+light.shadow.camera.near = 0.5;
+light.shadow.camera.far = 20;
+light.shadow.camera.left = -5;
+light.shadow.camera.right = 5;
+light.shadow.camera.top = 5;
+light.shadow.camera.bottom = -5;
+```
+
+### 4. Ajustar Shadow Bias
+```javascript
+// Shadow acne: aumentar bias (positivo)
+// Peter panning: diminuir bias
+light.shadow.bias = -0.001;
+light.shadow.normalBias = 0.02;
+// Regra: comecar com -0.001 e ajustar visualmente
+```
+
+### 5. Marcar Objetos para Shadows
+```javascript
+scene.traverse((child) => {
+  if (child.isMesh) {
+    child.castShadow = true;
+    child.receiveShadow = true;
+  }
+});
+// Desabilitar em objetos que nao precisam (performance)
+background.castShadow = false;
+smallDetail.castShadow = false;
+```
+
+### 6. Implementar Contact Shadows
+```javascript
+// Plane com blur que recebe sombra suave de contato
+import { ContactShadows } from '@react-three/drei'; // R3F
+// Ou custom: render cena de cima em render target, blur, projetar
+const shadowPlane = new THREE.Mesh(
+  new THREE.PlaneGeometry(10, 10),
+  new THREE.MeshBasicMaterial({
+    map: shadowTexture,
+    transparent: true,
+    opacity: 0.4,
+  })
+);
+```
+
+### 7. Shadow Map Resolution por Device
+| Device | Resolution | Nota |
+|--------|-----------|------|
+| Desktop high-end | 2048x2048 | Melhor qualidade |
+| Desktop mid | 1024x1024 | Bom tradeoff |
+| Mobile | 512x512 | Performance |
+| Mobile low-end | Desabilitar | Sem shadows |
+
+### 8. Ajustar Shadow Camera Frustum
+```javascript
+// Frustum deve ser o menor possivel que engloba a cena
+// Maior frustum = menos resolucao por pixel
+if (DEV) {
+  const helper = new THREE.CameraHelper(light.shadow.camera);
+  scene.add(helper);
+}
+```
+
+### 9. Otimizar Performance
+- Apenas 1-2 lights com castShadow = true
+- Objetos pequenos: castShadow = false
+- Shadow map resolution: menor possivel com qualidade aceitavel
+- Cascaded shadow maps para cenas grandes (CSM)
+
+### 10. Animated Shadows
+- Shadows seguem objetos automaticamente
+- Se light se move, shadow camera frustum deve cobrir nova area
+- Atualizar `light.shadow.camera.updateProjectionMatrix()` se mudar frustum
+
+## Output
+- Shadow system configurado (type, resolution, bias)
+- Objetos marcados para cast/receive
+- Shadow camera frustum otimizado
+- Contact shadows se solicitado
+- Device-specific resolution settings
+- Dev helpers para debug
+
+## Quality Criteria
+- [ ] Sem shadow acne (bias correto)
+- [ ] Sem peter panning (bias nao excessivo)
+- [ ] Sombras suaves (PCFSoft ou VSM)
+- [ ] Frustum ajustado (sem desperdicio de resolucao)
+- [ ] Max 2 shadow-casting lights
+- [ ] Resolution adequada por device
+- [ ] Ground plane recebe shadows
+- [ ] Performance: shadows nao causam drop abaixo de 30fps

package/squad-animations/tasks/build-text-animation.md

@@ -0,0 +1,180 @@
+---
+task: build-text-animation
+responsavel: "@css-motion-artist"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+
+Entrada:
+  - campo: text_spec
+    tipo: object
+    origem: "animation_brief"
+    obrigatorio: true
+
+Saida:
+  - campo: text_animation
+    tipo: code
+    destino: "review-animation-quality"
+
+Checklist:
+  - "[ ] Selecionar tipo (split chars, split words, split lines, typewriter, scramble)"
+  - "[ ] Implementar splitting com SplitType ou manual"
+  - "[ ] Configurar stagger timing"
+  - "[ ] Definir easing por caractere/palavra"
+  - "[ ] Garantir acessibilidade (aria-label no container)"
+  - "[ ] Limpar DOM apos animacao se necessario"
+---
+
+# Task: Build Text Animation
+
+## Metadata
+- **Agent:** css-motion-artist (Flux)
+- **Squad:** squad-animations
+- **Complexity:** MEDIUM
+
+## Objetivo
+Criar animacoes de texto — split characters, word reveals, line-by-line entrances, typewriter effects e text scramble. Manter legibilidade e acessibilidade como prioridade maxima.
+
+## Pre-Conditions
+- Texto final definido (nao animar texto placeholder)
+- Font carregada antes da animacao iniciar (FOUT prevention)
+- Acessibilidade: texto completo disponivel para screen readers
+- Trigger definido (page load, scroll, click)
+
+## Passos
+
+### 1. Classificar Tipo de Text Animation
+| Tipo | Complexidade | Melhor Para |
+|------|-------------|-------------|
+| Fade-in words | Baixa | Subtitulos, paragrafos |
+| Split characters | Media | Headlines, hero text |
+| Line reveal | Media | Paragrafos, quotes |
+| Typewriter | Baixa | Terminal, code, chat |
+| Scramble/decode | Alta | Tech, cyber, reveal |
+| Clip reveal | Media | Headlines com impacto |
+
+### 2. Implementar Split Characters
+```javascript
+// SplitType approach
+import SplitType from 'split-type';
+const text = new SplitType('.headline', { types: 'chars' });
+// Cada char recebe classe .char e CSS variable --char-index
+```
+```css
+.headline .char {
+  opacity: 0;
+  transform: translateY(20px);
+  animation: char-in 400ms ease-out both;
+  animation-delay: calc(var(--char-index) * 30ms);
+}
+@keyframes char-in {
+  to { opacity: 1; transform: translateY(0); }
+}
+```
+
+### 3. Implementar Line Reveal (Clip)
+```css
+.line-reveal {
+  clip-path: inset(0 100% 0 0);
+  animation: reveal-line 600ms cubic-bezier(0.77, 0, 0.18, 1) both;
+}
+@keyframes reveal-line {
+  to { clip-path: inset(0 0% 0 0); }
+}
+```
+
+### 4. Implementar Typewriter
+```css
+.typewriter {
+  width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  border-right: 2px solid currentColor;
+  animation:
+    typing 2s steps(30) forwards,
+    blink 0.5s step-end infinite;
+}
+@keyframes typing { to { width: 100%; } }
+@keyframes blink { 50% { border-color: transparent; } }
+```
+
+### 5. Implementar Word Stagger
+```css
+.word {
+  display: inline-block;
+  opacity: 0;
+  transform: translateY(8px);
+  animation: word-in 300ms ease-out both;
+  animation-delay: calc(var(--word-index) * 60ms);
+}
+@keyframes word-in {
+  to { opacity: 1; transform: translateY(0); }
+}
+```
+
+### 6. Configurar Stagger Timing
+| Elementos | Stagger | Total Maximo |
+|-----------|---------|-------------|
+| 1-10 chars | 30-50ms | 500ms |
+| 10-30 chars | 20-30ms | 800ms |
+| 30+ chars | 15-20ms | 1000ms |
+| Words | 50-80ms | 800ms |
+| Lines | 100-150ms | 600ms |
+
+### 7. Garantir Acessibilidade
+```html
+<!-- Screen reader ve texto completo -->
+<h1 class="headline" aria-label="Welcome to our platform">
+  <span class="char" aria-hidden="true">W</span>
+  <span class="char" aria-hidden="true">e</span>
+  <!-- ... -->
+</h1>
+```
+
+### 8. Prevenir FOUT (Flash of Unstyled Text)
+```css
+.headline {
+  font-display: block;
+  visibility: hidden;
+}
+.fonts-loaded .headline {
+  visibility: visible;
+}
+```
+
+### 9. Cleanup DOM apos Animacao
+```javascript
+// Reverter split apos animacao
+text.revert(); // SplitType cleanup
+```
+
+### 10. Reduced Motion
+```css
+@media (prefers-reduced-motion: reduce) {
+  .headline .char, .word, .line-reveal, .typewriter {
+    animation: none;
+    opacity: 1;
+    transform: none;
+    clip-path: none;
+    width: auto;
+  }
+}
+```
+
+## Output
+- Codigo CSS/JS para text animation escolhida
+- SplitType integration se necessario
+- Acessibilidade: aria-label, aria-hidden
+- Reduced motion fallback
+- FOUT prevention strategy
+- Demo HTML com texto animado
+
+## Quality Criteria
+- [ ] Texto legivel durante TODA a animacao
+- [ ] Screen readers leem texto completo (aria-label)
+- [ ] Font carregada antes da animacao iniciar
+- [ ] Stagger total nao excede 1 segundo
+- [ ] prefers-reduced-motion mostra texto instantaneo
+- [ ] DOM limpo apos animacao (revert split)
+- [ ] 60fps durante split animation
+- [ ] Cross-browser (SplitType polyfill se necessario)

package/squad-animations/tasks/choreograph-stagger-sequence.md

@@ -0,0 +1,177 @@
+---
+task: choreograph-stagger-sequence
+responsavel: "@motion-choreographer"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+
+Entrada:
+  - campo: elements
+    tipo: array
+    origem: "animation_brief"
+    obrigatorio: true
+  - campo: feeling
+    tipo: string
+    origem: "animation_brief"
+    obrigatorio: true
+
+Saida:
+  - campo: stagger_spec
+    tipo: object
+    destino: "css-motion-artist ou threejs-architect"
+
+Checklist:
+  - "[ ] Definir stagger delay entre elementos"
+  - "[ ] Selecionar pattern (linear, ease-in, random, from-center)"
+  - "[ ] Configurar overlap entre animacoes"
+  - "[ ] Testar ritmo visual"
+  - "[ ] Ajustar para quantidade de elementos"
+---
+
+# Task: Choreograph Stagger Sequence
+
+## Metadata
+- **Agent:** motion-choreographer (Tempo)
+- **Squad:** squad-animations
+- **Complexity:** MEDIUM
+
+## Objetivo
+Coreografar sequencias stagger — definir como multiplos elementos animam em cascata com timing, pattern e ritmo que criam harmonia visual. Stagger bem feito transforma lista de items em experiencia orquestrada.
+
+## Pre-Conditions
+- Elementos a serem staggered identificados
+- Numero de elementos conhecido
+- Feeling desejado (elegante, energetico, dramatico)
+- Layout dos elementos (lista, grid, radial)
+
+## Stagger Patterns
+- **Cascata:** delay fixo (50-100ms), elegante
+- **Wave:** delay variavel, organico
+- **From center:** expande do centro, impactante
+- **Random:** delay aleatorio, energetico
+
+## Passos
+
+### 1. Selecionar Pattern por Feeling
+| Feeling | Pattern | Delay | Total Max |
+|---------|---------|-------|-----------|
+| Elegante/premium | Cascata linear | 60-80ms | 800ms |
+| Energetico/dinamico | Accelerating | 40-80ms | 600ms |
+| Organico/natural | Wave (sine) | variavel | 1000ms |
+| Impactante/hero | From center | dist-based | 600ms |
+| Playful | Random | 30-100ms | 800ms |
+
+### 2. Calcular Delay Otimo
+```
+Regra: stagger_delay = min(100ms, 800ms / num_elements)
+Exemplo: 12 cards = 800/12 = ~66ms stagger
+Exemplo: 4 cards = 800/4 = 200ms (cap em 100ms)
+```
+
+### 3. Implementar GSAP Stagger
+```javascript
+gsap.from('.card', {
+  opacity: 0,
+  y: 30,
+  duration: 0.4,
+  stagger: {
+    each: 0.08,       // 80ms entre cada
+    from: 'start',    // ou 'center', 'end', 'random', index
+    ease: 'power2.out', // Easing do stagger timing itself
+  }
+});
+```
+
+### 4. Implementar Grid Stagger (2D)
+```javascript
+gsap.from('.grid-item', {
+  opacity: 0,
+  scale: 0.8,
+  duration: 0.5,
+  stagger: {
+    grid: [rows, cols],
+    from: 'center',
+    amount: 0.8, // Total stagger duration
+  }
+});
+```
+
+### 5. CSS Variable Stagger
+```css
+.stagger-item {
+  animation: entrance 400ms ease-out both;
+  animation-delay: calc(var(--i) * 80ms);
+}
+```
+```html
+<div class="stagger-item" style="--i: 0">A</div>
+<div class="stagger-item" style="--i: 1">B</div>
+<div class="stagger-item" style="--i: 2">C</div>
+```
+
+### 6. Overlap entre Animacoes
+```
+Sem overlap:   A----| B----| C----|
+50% overlap:   A----|
+                 B----|
+                   C----|
+Full overlap:  A----|
+               B----|
+               C----|
+```
+- 50% overlap: natural, flowing
+- 0% overlap: sequential, deliberate
+- 70%+ overlap: energetic, fast
+
+### 7. Ajustar para Quantidade
+| Num Elements | Stagger | Per Element Duration |
+|-------------|---------|---------------------|
+| 2-4 | 80-100ms | 400ms |
+| 5-8 | 60-80ms | 350ms |
+| 9-16 | 40-60ms | 300ms |
+| 17+ | 30-40ms | 250ms |
+
+### 8. Wave/Sine Pattern
+```javascript
+gsap.from('.item', {
+  opacity: 0,
+  y: 30,
+  stagger: {
+    each: 0.05,
+    from: 'start',
+    ease: 'sine.inOut', // Wave-like timing
+  }
+});
+```
+
+### 9. Reduced Motion
+```javascript
+if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+  gsap.set('.stagger-item', { opacity: 1, y: 0, scale: 1 });
+}
+```
+
+### 10. Validar Ritmo Visual
+- Assistir animacao em tempo real 3x
+- Se parece "mecanico", adicionar easing ao stagger
+- Se parece "caótico", usar pattern linear em vez de random
+- Se parece "lento", reduzir delay e duration
+- Total sequence nao deve exceder 1 segundo
+
+## Output
+- Stagger spec com pattern, delay e duration
+- GSAP/CSS implementation
+- Grid stagger se layout 2D
+- Overlap configuration
+- Quantity-adaptive delays
+- Reduced motion variant
+
+## Quality Criteria
+- [ ] Total stagger sequence < 1 segundo
+- [ ] Delay proporcional ao numero de elementos
+- [ ] Pattern adequado ao feeling (cascata/wave/center)
+- [ ] Overlap configurado (nao 100% sequential)
+- [ ] Grid stagger para layouts 2D
+- [ ] prefers-reduced-motion: items visiveis instantaneo
+- [ ] Ritmo visual harmonioso (sem "mecanico")
+- [ ] 60fps durante toda sequencia