wizz-method 1.3.2 → 1.4.1

package/src/skills-lib/animate/references/framer-motion.md

@@ -0,0 +1,356 @@
+# Framer Motion Reference
+
+Framer Motion is the recommended animation library for React/Next.js applications.
+
+## Installation
+
+```bash
+npm install framer-motion
+# or
+pnpm add framer-motion
+```
+
+## Basic Usage
+
+### Motion Components
+
+```tsx
+import { motion } from "framer-motion"
+
+// Any HTML element can become animated
+<motion.div
+  initial={{ opacity: 0, y: 20 }}
+  animate={{ opacity: 1, y: 0 }}
+  transition={{ duration: 0.3, ease: "easeOut" }}
+>
+  Content
+</motion.div>
+```
+
+### Common Props
+
+| Prop | Description |
+|------|-------------|
+| `initial` | Starting state (or `false` to disable) |
+| `animate` | Target state |
+| `exit` | Exit state (requires AnimatePresence) |
+| `transition` | Animation configuration |
+| `whileHover` | State while hovered |
+| `whileTap` | State while pressed |
+| `whileFocus` | State while focused |
+| `whileInView` | State while in viewport |
+
+## AnimatePresence
+
+Required for exit animations. Wraps elements that may be removed from DOM.
+
+```tsx
+import { motion, AnimatePresence } from "framer-motion"
+
+function Modal({ isOpen, onClose, children }) {
+  return (
+    <AnimatePresence>
+      {isOpen && (
+        <motion.div
+          initial={{ opacity: 0 }}
+          animate={{ opacity: 1 }}
+          exit={{ opacity: 0 }}
+          transition={{ duration: 0.2 }}
+        >
+          {children}
+        </motion.div>
+      )}
+    </AnimatePresence>
+  )
+}
+```
+
+### AnimatePresence Props
+
+```tsx
+<AnimatePresence
+  mode="wait"      // 'sync' | 'wait' | 'popLayout'
+  initial={false}  // Disable initial animation on mount
+  onExitComplete={() => {}}  // Callback when all exits complete
+>
+```
+
+- `mode="sync"` (default): Enter and exit happen simultaneously
+- `mode="wait"`: Wait for exit to complete before enter
+- `mode="popLayout"`: Remove exiting elements from layout flow
+
+## Variants
+
+Variants define animation states that can be orchestrated across parent/children.
+
+```tsx
+const containerVariants = {
+  hidden: { opacity: 0 },
+  visible: {
+    opacity: 1,
+    transition: {
+      staggerChildren: 0.1,  // Delay between each child
+      delayChildren: 0.2,    // Initial delay before children start
+    }
+  }
+}
+
+const itemVariants = {
+  hidden: { opacity: 0, y: 20 },
+  visible: { opacity: 1, y: 0 }
+}
+
+function List({ items }) {
+  return (
+    <motion.ul
+      variants={containerVariants}
+      initial="hidden"
+      animate="visible"
+    >
+      {items.map(item => (
+        <motion.li key={item.id} variants={itemVariants}>
+          {item.name}
+        </motion.li>
+      ))}
+    </motion.ul>
+  )
+}
+```
+
+## Layout Animations
+
+Animate layout changes automatically with the `layout` prop.
+
+```tsx
+// Element animates when its position/size changes
+<motion.div layout>
+  {isExpanded ? "Expanded content here" : "Collapsed"}
+</motion.div>
+
+// Layout types
+<motion.div layout>  // Animate position and size
+<motion.div layout="position">  // Only animate position
+<motion.div layout="size">  // Only animate size
+```
+
+### Shared Layout Animations (layoutId)
+
+Elements with the same `layoutId` animate between each other.
+
+```tsx
+function Tabs({ tabs, activeTab, setActiveTab }) {
+  return (
+    <div className="flex gap-2">
+      {tabs.map(tab => (
+        <button
+          key={tab}
+          onClick={() => setActiveTab(tab)}
+          className="relative px-4 py-2"
+        >
+          {tab}
+          {activeTab === tab && (
+            <motion.div
+              layoutId="tab-indicator"
+              className="absolute inset-0 bg-blue-500 rounded -z-10"
+              transition={{ type: "spring", stiffness: 400, damping: 30 }}
+            />
+          )}
+        </button>
+      ))}
+    </div>
+  )
+}
+```
+
+### LayoutGroup
+
+Group layout animations to prevent conflicts between independent animations.
+
+```tsx
+import { LayoutGroup } from "framer-motion"
+
+<LayoutGroup>
+  <Tabs />  {/* These layout animations */}
+</LayoutGroup>
+<LayoutGroup>
+  <OtherTabs />  {/* Won't conflict with these */}
+</LayoutGroup>
+```
+
+## Gestures
+
+### Drag
+
+```tsx
+<motion.div
+  drag              // Enable both axes
+  drag="x"          // Horizontal only
+  drag="y"          // Vertical only
+  dragConstraints={{ left: 0, right: 300, top: 0, bottom: 200 }}
+  dragElastic={0.2}     // Elasticity outside constraints (0-1)
+  dragMomentum={true}   // Continue after release
+  dragTransition={{ bounceStiffness: 600, bounceDamping: 20 }}
+  onDragStart={(event, info) => {}}
+  onDrag={(event, info) => {}}
+  onDragEnd={(event, info) => {}}
+>
+  Drag me
+</motion.div>
+```
+
+### Drag Info Object
+
+```tsx
+onDrag={(event, info) => {
+  info.point    // { x, y } current position
+  info.delta    // { x, y } change since last frame
+  info.offset   // { x, y } offset from drag start
+  info.velocity // { x, y } current velocity
+}}
+```
+
+## Motion Values & Hooks
+
+### useMotionValue
+
+Create a value that updates without re-rendering.
+
+```tsx
+import { motion, useMotionValue, useTransform } from "framer-motion"
+
+function Component() {
+  const x = useMotionValue(0)
+
+  // Transform x position to opacity
+  const opacity = useTransform(x, [-100, 0, 100], [0, 1, 0])
+
+  // Transform x to rotation
+  const rotate = useTransform(x, [-100, 100], [-10, 10])
+
+  return (
+    <motion.div
+      drag="x"
+      style={{ x, opacity, rotate }}
+    />
+  )
+}
+```
+
+### useSpring
+
+Create a spring-animated motion value.
+
+```tsx
+import { useSpring, useMotionValue } from "framer-motion"
+
+function Component() {
+  const x = useMotionValue(0)
+  const springX = useSpring(x, { stiffness: 300, damping: 30 })
+
+  return (
+    <motion.div
+      onMouseMove={(e) => x.set(e.clientX)}
+      style={{ x: springX }}
+    />
+  )
+}
+```
+
+### useScroll
+
+Track scroll progress.
+
+```tsx
+import { useScroll, useTransform, motion } from "framer-motion"
+
+function ProgressBar() {
+  const { scrollYProgress } = useScroll()
+
+  return (
+    <motion.div
+      className="fixed top-0 left-0 right-0 h-1 bg-blue-500 origin-left"
+      style={{ scaleX: scrollYProgress }}
+    />
+  )
+}
+
+// Scroll within a container
+const { scrollYProgress } = useScroll({
+  target: containerRef,
+  offset: ["start end", "end start"]  // When to start/end tracking
+})
+```
+
+### useInView
+
+Detect when element enters viewport.
+
+```tsx
+import { useInView } from "framer-motion"
+
+function Component() {
+  const ref = useRef(null)
+  const isInView = useInView(ref, {
+    once: true,      // Only trigger once
+    margin: "-100px" // Trigger 100px before entering
+  })
+
+  return (
+    <motion.div
+      ref={ref}
+      initial={{ opacity: 0, y: 50 }}
+      animate={isInView ? { opacity: 1, y: 0 } : {}}
+    />
+  )
+}
+```
+
+## Transition Options
+
+```tsx
+const transition = {
+  // Timing
+  duration: 0.3,
+  delay: 0.1,
+
+  // Easing
+  ease: "easeOut",  // or array: [0.23, 1, 0.32, 1]
+
+  // Spring physics
+  type: "spring",
+  stiffness: 400,
+  damping: 30,
+  mass: 1,
+
+  // Or duration-based spring
+  type: "spring",
+  duration: 0.3,
+  bounce: 0.2,
+
+  // Per-property transitions
+  opacity: { duration: 0.2 },
+  x: { type: "spring", stiffness: 300 },
+
+  // Repeat
+  repeat: Infinity,
+  repeatType: "reverse",  // "loop" | "reverse" | "mirror"
+  repeatDelay: 0.5,
+}
+```
+
+## Multi-Step Animations (Keyframes)
+
+```tsx
+<motion.div
+  animate={{
+    x: [0, 100, 0],           // Move right then back
+    opacity: [0, 1, 1, 0],    // Fade in, stay, fade out
+    scale: [1, 1.2, 1],       // Grow then shrink
+  }}
+  transition={{
+    duration: 2,
+    times: [0, 0.5, 1],       // When each keyframe occurs (0-1)
+    ease: "easeInOut",
+  }}
+/>
+```

package/src/skills-lib/animate/references/performance-accessibility.md

@@ -0,0 +1,185 @@
+# Performance & Accessibility Reference
+
+## Performance
+
+### Target: 60 FPS
+
+Animations should run at 60 frames per second (16.67ms per frame) for smooth motion.
+
+### GPU-Accelerated Properties
+
+Only these properties are hardware-accelerated and won't cause layout recalculation:
+
+| Property | Notes |
+|----------|-------|
+| `transform` | translate, scale, rotate |
+| `opacity` | Fade effects |
+
+### Properties to Avoid Animating
+
+These trigger layout recalculation and are expensive:
+
+- `width`, `height`
+- `top`, `left`, `right`, `bottom`
+- `margin`, `padding`
+- `border-width`
+- `font-size`
+
+**Instead**: Use `transform: scale()` instead of width/height, `transform: translate()` instead of top/left.
+
+### will-change
+
+Hints to the browser that an element will animate:
+
+```css
+.will-animate {
+  will-change: transform, opacity;
+}
+```
+
+**Caution**: Use sparingly. Apply only to elements that actually animate, and remove after animation completes if possible. Overuse can hurt performance.
+
+### Hardware Acceleration Hack
+
+Force GPU layer creation (use sparingly):
+
+```css
+.force-gpu {
+  transform: translateZ(0);
+  /* or */
+  backface-visibility: hidden;
+}
+```
+
+### Monitoring Performance
+
+1. **Chrome DevTools**: Performance tab → Record during animation
+2. **Rendering tab**: Enable "FPS meter" and "Paint flashing"
+3. **Layers panel**: Check layer composition
+
+### Common Performance Issues
+
+| Issue | Solution |
+|-------|----------|
+| Janky scrolling | Use `transform` instead of `top/left` |
+| Slow animations | Reduce number of animated elements |
+| Memory spikes | Avoid creating new objects during animation |
+| Layout thrashing | Batch DOM reads/writes |
+
+## Accessibility
+
+### prefers-reduced-motion
+
+Users can indicate they prefer reduced motion in their system settings. Always respect this preference.
+
+#### CSS Implementation
+
+```css
+/* Full animation by default */
+.element {
+  transition: transform 300ms ease-out;
+}
+
+/* Reduced or no motion for users who prefer it */
+@media (prefers-reduced-motion: reduce) {
+  .element {
+    transition: none;
+    /* or minimal transition */
+    transition: opacity 200ms ease-out;
+  }
+}
+```
+
+#### React/Framer Motion Implementation
+
+```tsx
+import { useReducedMotion } from "framer-motion"
+
+function AnimatedComponent() {
+  const shouldReduceMotion = useReducedMotion()
+
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: shouldReduceMotion ? 0 : 20 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={{ duration: shouldReduceMotion ? 0 : 0.3 }}
+    />
+  )
+}
+```
+
+#### Global Configuration with MotionConfig
+
+```tsx
+import { MotionConfig, useReducedMotion } from "framer-motion"
+
+function App() {
+  const shouldReduceMotion = useReducedMotion()
+
+  return (
+    <MotionConfig reducedMotion={shouldReduceMotion ? "always" : "never"}>
+      {/* All motion components inside respect this setting */}
+      <YourApp />
+    </MotionConfig>
+  )
+}
+```
+
+### MotionConfig Options
+
+| Value | Effect |
+|-------|--------|
+| `"never"` | Normal animations (default) |
+| `"always"` | Skip all animations |
+| `"user"` | Respect system `prefers-reduced-motion` setting |
+
+### Accessible Animation Guidelines
+
+1. **Provide alternatives**: Ensure content is accessible without animation
+2. **Avoid flashing**: No content flashing more than 3 times per second
+3. **Don't block interaction**: Animations shouldn't prevent users from interacting
+4. **Keep it brief**: Long animations can be frustrating
+5. **Purposeful motion**: Only animate when it adds value
+6. **Pause controls**: For continuous animations, provide pause/stop
+
+### Focus Management with Animations
+
+```tsx
+// Ensure focus moves appropriately with animated elements
+function Modal({ isOpen }) {
+  const modalRef = useRef(null)
+
+  useEffect(() => {
+    if (isOpen) {
+      // Wait for enter animation before focusing
+      const timer = setTimeout(() => {
+        modalRef.current?.focus()
+      }, 300)
+      return () => clearTimeout(timer)
+    }
+  }, [isOpen])
+
+  return (
+    <AnimatePresence>
+      {isOpen && (
+        <motion.div
+          ref={modalRef}
+          tabIndex={-1}
+          initial={{ opacity: 0 }}
+          animate={{ opacity: 1 }}
+          exit={{ opacity: 0 }}
+        >
+          Modal content
+        </motion.div>
+      )}
+    </AnimatePresence>
+  )
+}
+```
+
+### Testing Reduced Motion
+
+1. **macOS**: System Preferences → Accessibility → Display → Reduce motion
+2. **Windows**: Settings → Ease of Access → Display → Show animations
+3. **iOS**: Settings → Accessibility → Motion → Reduce Motion
+4. **Chrome DevTools**: Rendering tab → Emulate CSS media feature `prefers-reduced-motion`

package/src/skills-lib/auth-and-secrets/SKILL.md

@@ -2,6 +2,7 @@
 name: auth-and-secrets
 description: >
   Segurança de autenticação e gestão de secrets. Usar quando: implementar auth, lidar com JWT/OAuth/SSO,
+  token no header vs URL, revogação de token no logout, enumeração de usuário/mensagem genérica,
   guardar API keys ou credenciais, configurar Clerk/Supabase auth, revisar onde secrets estão armazenados,
   rotação de credenciais, checar se .env está seguro.
 ---
@@ -12,16 +13,25 @@ description: >
 
 ### Senhas
 - Hash com bcrypt (custo >= 12), Argon2id ou scrypt. Nunca MD5/SHA1 para senhas
-- Minimum 8 caracteres, sem restrição de caracteres especiais
+- Mínimo de 8 caracteres, sem restrição de caracteres especiais
 - Implemente bloqueio após N tentativas (lockout ou CAPTCHA)
-- Oferece 2FA: TOTP (Google Authenticator) é o padrão mínimo
+- Ofereça 2FA: TOTP (Google Authenticator) é o padrão mínimo
 
 ### JWT
-- Assine sempre com RS256 (assimétrico) em produção, nunca HS256 com secret fraco
+- Na verificação, aceite só o algoritmo esperado: rejeite `alg: none` e não deixe o token escolher o algoritmo (ataque de confusão de algoritmo)
+- Prefira RS256 (assimétrico) quando mais de um serviço verifica o token. HS256 só com secret forte: 32+ bytes aleatórios, nunca uma palavra
 - exp curto para access token (15 min a 1h)
 - Refresh token com rotação: ao usar, invalide o anterior e emita novo
 - Nunca coloque dados sensíveis no payload (é base64, não criptografia)
-- Blacklist de tokens invalidados: Redis com TTL igual ao exp do token
+- **Token no header `Authorization: Bearer`, NUNCA na URL/query string** (a URL vaza em logs de servidor, histórico do browser, header `Referer` e analytics)
+- **Logout de verdade revoga o token**: coloque na blacklist (Redis, TTL = exp do token) e invalide o refresh token. Sem isso o access token continua válido depois do logout até expirar sozinho
+
+### Enumeração de usuário
+Evita que um atacante descubra quais e-mails existem na base (login, signup, reset de senha).
+- Resposta idêntica para e-mail existente e inexistente: "Se o e-mail existir, enviamos um link"
+- No login use mensagem genérica ("credenciais inválidas"), nunca "e-mail não cadastrado" vs "senha incorreta"
+- Responda em **tempo constante**: rode o hash da senha mesmo quando o usuário não existe (senão o tempo de resposta denuncia quem existe)
+- Reforce com rate limit por IP **e** por conta (ver web-security) para barrar varredura de e-mails
 
 ### OAuth / SSO
 - Use biblioteca estabelecida, não implemente o flow manualmente
@@ -30,9 +40,10 @@ description: >
 
 ### Stack Supabase + Clerk
 - Auth gerenciada pelo Clerk: nunca reimplementar flows de auth manualmente
-- Clerk webhook (`svix`) verificado por assinatura antes de processar — não confiar no body sem verificar
+- Toda rota protegida, Server Action e route handler chama `auth()` do Clerk no servidor. Nunca confiar em estado de sessão vindo do cliente
+- Clerk webhook (`svix`) verificado por assinatura antes de processar: não confiar no body sem verificar
 - Supabase RLS: toda tabela de domínio deve ter RLS ativo; queries devem filtrar por `workspace_id`/`user_id`
-- `SUPABASE_SERVICE_ROLE_KEY` só usada em server-side (API routes, never client), nunca exposta no frontend
+- `SUPABASE_SERVICE_ROLE_KEY` bypassa RLS: só em server-side (API routes, jobs), nunca exposta no frontend
 - `NEXT_PUBLIC_*` = seguro expor no cliente; tudo sem `NEXT_PUBLIC_` = server-only
 
 ## Secrets e credenciais
@@ -46,19 +57,36 @@ description: >
 ### Onde guardar secrets
 - Produção: variáveis de ambiente da plataforma (Vercel: `vercel env add`)
 - CI/CD: variáveis de ambiente criptografadas da plataforma (GitHub Actions Secrets, etc.)
-- Dev local: arquivo `.env.local` nunca commitado — verificar com `git check-ignore -v .env.local`
+- Dev local: arquivo `.env.local` nunca commitado. Verificar com `git check-ignore -v .env.local`
+
+### API keys emitidas pelo próprio app
+Se o app gera API keys para os usuários:
+- Guarde só o hash (SHA-256) da key no banco, nunca a key em texto plano
+- Mostre a key completa uma única vez, na criação
+- Use prefixo identificável (ex: `wz_live_`) para facilitar detecção em scan de repositório
+- Permita revogar e listar keys por usuário
 
 ### Cripto de credenciais de usuário (AES-256-GCM)
 Se o app armazena credenciais de terceiros do usuário (ex: SMTP, WhatsApp API):
 ```ts
-// src/lib/crypto.ts — ler chave do env, nunca hardcodar
-const key = process.env.CREDENTIAL_ENCRYPTION_KEY
+// src/lib/crypto.ts: chave vem do env, nunca hardcodada
+import { createCipheriv, randomBytes } from "crypto"
+
+const key = process.env.CREDENTIAL_ENCRYPTION_KEY // base64, 32 bytes
 if (!key) throw new Error("CREDENTIAL_ENCRYPTION_KEY não configurada")
-// AES-256-GCM: chave base64 de 32 bytes
+
+export function encrypt(plain: string) {
+  const iv = randomBytes(12) // IV aleatório por registro, nunca reutilizar
+  const cipher = createCipheriv("aes-256-gcm", Buffer.from(key, "base64"), iv)
+  const enc = Buffer.concat([cipher.update(plain, "utf8"), cipher.final()])
+  return { iv: iv.toString("base64"), data: enc.toString("base64"), tag: cipher.getAuthTag().toString("base64") }
+}
+// no decrypt: setAuthTag antes de final(), senão a integridade não é verificada
 ```
 
 ### Rotação de credenciais
 - Rotacione secrets de terceiros a cada 90 dias ou após qualquer saída de membro do time
+- Secret commitado por acidente: considere comprometido e rotacione na hora. Reescrever o histórico do git não basta
 - API keys de produção: uma por serviço/ambiente, nunca compartilhadas
 - Database passwords: use IAM auth quando disponível no cloud provider