Psyche Signals 🧠 v3.5

Tu interfaz ahora tiene instinto.

Psyche Signals es una biblioteca de computación afectiva ultra-ligera que convierte el caos del cursor y los gestos táctiles en inteligencia emocional. Analiza la física del movimiento (velocidad, entropía, jerk) para predecir intenciones, detectar frustración y adaptar la UX en tiempo real.

---

⚡ Características Principales

• 🕵️ Shadow Tracking (Nuevo en v3.5): Atraviesa el Shadow DOM para identificar elementos reales dentro de Web Components, ignorando wrappers decorativos (div, span).
• 🧠 Micro-AI Adaptativa: Aprende el comportamiento base de cada usuario (calibración Z-Score) para detectar anomalías personalizadas en lugar de usar umbrales fijos.
• 📱 Touch & Rage Taps: Detecta "golpes de frustración" en móviles y presión táctil (si el hardware lo soporta).
• 🛡️ Privacy-First: Modo de anonimización local que cumple con GDPR/CCPA (redacta textos e IDs, oculta coordenadas exactas).
• 🔮 Micro-Intenciones: Predicción vectorial de Exit Intent (abandono) y Hesitation (duda/confusión).

---

📦 Instalación

NPM / Yarn / PNPM

npm install psyche-signals
# o
pnpm add psyche-signals

CDN (Navegador)

<script src="https://unpkg.com/psyche-signals/dist/psyche.umd.js"></script>

---

🚀 Uso Rápido

Inicializa el motor y empieza a escuchar la "mente" del usuario.

import { Psyche } from 'psyche-signals';

// 1. Configuración
const engine = new Psyche({
  useAI: true,
  debug: true,
  significantSelectors: ['.buy-btn', '#signup', '[role="button"]']
});

// 2. Escuchar cambios de estado emocional
engine.on('stateChange', (state) => {
  console.log(`Estado del usuario: ${state}`);
  
  if (state === 'FRUSTRADO') {
    openHelpChat(); // El usuario está golpeando o moviendo el mouse con ira
  }
  
  if (state === 'INDECISO') {
    showTooltip(); // El usuario duda sobre un elemento
  }
});

// 3. Escuchar micro-intenciones específicas
engine.on('intention', (intent) => {
  if (intent === 'EXIT_INTENT') {
    showDiscountModal(); // El usuario va a cerrar la pestaña
  }
});

---

⚙️ Configuración

Opción	Tipo	Default	Descripción
interval	number	100	Frecuencia de análisis en milisegundos.
historySize	number	20	Cantidad de puntos de rastreo a mantener en memoria.
useAI	boolean	true	Activa la calibración estadística automática por usuario.
privacyMode	boolean	false	Si es true, redacta textos, IDs y coordenadas (GDPR safe).
significantSelectors	string[]	['button', 'a']	Selectores CSS críticos para tu negocio. Ayuda al motor a filtrar ruido.
learningSamples	number	30	Cuantos ciclos (ticks) necesita la AI para calibrarse.
scrollElement	HTMLElement	window	Elemento donde escuchar eventos de scroll.

---

📡 API de Eventos

.on('metrics', callback)

Se dispara en cada ciclo de análisis (tick). Devuelve el objeto de telemetría completo.

engine.on('metrics', (data) => {
  console.log(data.velocity);      // px/ms
  console.log(data.entropy);       // 0-1 (Nivel de caos)
  console.log(data.currentElement);// Elemento bajo el cursor (Smart parsing)
});

.on('stateChange', callback)

Se dispara solo cuando el usuario cambia de perfil cognitivo.

Estado	Significado	Disparador Típico
CALMADO	Lectura o inactividad.	Baja velocidad, scroll constante.
EXPLORANDO	Navegación estándar.	Velocidad media, entropía baja.
URGENTE	Objetivo claro.	Alta velocidad, trayectoria recta.
INDECISO	Confusión o búsqueda.	Alta entropía (movimiento errático).
FRUSTRADO	Ira o error de UI.	Rage Taps, High Jerk (sacudidas).

.on('intention', callback)

Detecta acciones futuras inmediatas.

• EXIT_INTENT: El usuario mueve el mouse rápido hacia la barra del navegador.
• HESITATION: El usuario mantiene el foco en un elemento interactivo mucho tiempo sin hacer clic.

---

🛡️ Estructura de Datos (TypeScript)

El motor devuelve objetos tipados para facilitar la integración:

interface PsycheElement {
  tag: string;           // 'button', 'input', etc.
  id?: string;           // Redactado si privacyMode = true
  className?: string;    // Primera clase encontrada
  interactive: boolean;  // ¿Es clicable?
  isInShadow: boolean;   // ¿Está dentro de un Web Component?
  isSignificant: boolean;// ¿Coincide con tus selectores de negocio?
}

---

🤝 Contribución

¡Los PRs son bienvenidos! Este proyecto busca democratizar la computación afectiva en la web.

1. Fork el repositorio.
2. Crea una rama (git checkout -b feature/AmazingFeature).
3. Commit tus cambios (git commit -m 'Add some AmazingFeature').
4. Push a la rama (git push origin feature/AmazingFeature).
5. Abre un Pull Request.

---

📄 Licencia

Distribuido bajo la licencia MIT. Ver LICENSE para más información.

Creado por Walter Sandoval - GitHub