wissive 0.1.0 → 0.1.3

package/README.md

@@ -1,193 +1,194 @@
-# Wissive
-
-**Micro-librería de JavaScript de emojis "vivos" — reactivos a hover, click y proximidad del mouse.**
-
----
-
-## Instalación rápida
-
-### Vía npm
-```bash
-npm install wissive
-```
-```js
-import { createEmoji } from 'wissive';
-
-createEmoji('mochi', { target: document.querySelector('#slot') });
-```
-
-### Vía CDN (sin instalar nada)
-```html
-<script src="https://cdn.jsdelivr.net/npm/wissive/dist/wissive.umd.js"></script>
-<div id="slot"></div>
-<script>
-  Wissive.createEmoji('mochi', { target: document.querySelector('#slot') });
-</script>
-```
-
-> El paquete todavía no está publicado en npm (ver `requerimientos.md`, Fase 6) — estos son los
-> comandos que funcionarán una vez publicado.
-
----
-
-## 1. ¿Qué es Wissive?
-
-Wissive es una librería de JavaScript vanilla (sin dependencias obligatorias, sin framework)
-que renderiza emojis tipo *blob* con personalidad propia. Cada emoji reacciona en tiempo real
-a la interacción del usuario — no es una imagen estática ni un GIF: es un motor que dibuja el
-rostro por código (SVG) y lo anima con física de resorte (spring physics), eligiendo
-expresiones de forma semi-aleatoria dentro de un set curado para cada estado de interacción.
-
-No es un set de iconos. Es un **motor de expresión** con un catálogo de personajes ya
-diseñados, pensado para que cualquier desarrollador lo instale y tenga, en dos líneas de
-código, un emoji que "está vivo" en su interfaz.
-
----
-
-## 2. Objetivo del proyecto
-
-- Dar a cualquier sitio web una forma rápida de añadir personalidad y feedback emocional a
-  través de una carita animada, sin tener que diseñar ni animar nada desde cero.
-- Que la librería sea **liviana, sin dependencias obligatorias**, y utilizable tanto con
-  bundlers modernos como directamente desde un `<script>` en HTML plano.
-- Que **no dependa de ningún framework** para funcionar, pero que se pueda envolver fácilmente
-  en React, Vue o Astro sin fricción.
-- Que cada emoji se sienta "vivo" gracias a variedad real: no una sola expresión por estado,
-  sino un pool de expresiones que se sortea, evitando la sensación de repetición.
-
----
-
-## 3. Funcionalidad principal
-
-### 3.1 Catálogo de emojis
-14 personajes base con diseño propio (ver `desing.md`), cada uno con 24 expresiones
-distribuidas en 4 estados de interacción. Catálogo visual y demo en vivo de los 14, con
-snippet copiable por emoji (clic en el nombre): correr `pnpm run app` y abrir
-[`app/index.html`](app/index.html).
-
-### 3.2 Estados de interacción
-| Estado | Disparador | Descripción |
-|---|---|---|
-| `idle` | Sin interacción | Estado de reposo del emoji, respiración lenta. |
-| `near` | El cursor se acerca sin tocar el emoji (radio configurable) | El emoji "nota" que algo se acerca. |
-| `hover` | `mouseenter` / `mouseleave` | El cursor está directamente sobre el emoji. |
-| `click` | `mousedown` / `mouseup` (o `touchstart` en móvil) | Reacción a la interacción directa. |
-
-Cada estado tiene un **pool de variantes** de expresión; al dispararse el estado se sortea una
-variante evitando repetir la anterior inmediatamente, dando sensación de variedad.
-
-### 3.3 Motor de animación
-- Interpolación de parámetros (apertura de ojos, curvatura de boca, posición de cejas, etc.)
-  mediante un sistema de **resorte amortiguado (spring physics)**, no `transition` lineal de
-  CSS. Esto da movimiento orgánico entre expresiones.
-- Un único `requestAnimationFrame` central compartido entre todas las instancias activas en
-  una misma página (no un loop por emoji).
-
-### 3.4 Sonido (opcional)
-Integración opcional con [Cuelume](https://cuelume-site.pages.dev/) (librería de sonidos de
-interacción sintetizados con Web Audio, sin archivos de audio). Se detecta en tiempo de
-ejecución; si no está instalada, la librería sigue funcionando en silencio sin romperse.
-
-### 3.5 Accesibilidad
-- `role="img"` + `aria-label` describiendo la emoción actual.
-- Soporte de teclado (`tabindex`, `Enter`/`Espacio` equivalen a click).
-- Respeta `prefers-reduced-motion` del sistema operativo.
-- Fallback definido para touch (sin hover/near reales en móvil).
-
----
-
-## 4. Cómo estará construido
-
-### 4.1 Lenguaje y estructura
-- Código fuente en **TypeScript**, compilado a JS. Da autocompletado y tipos (`.d.ts`) a quien
-  la instale, sin obligar a nadie a usar TS.
-- Sin dependencias de runtime obligatorias. Cuelume es *peer dependency* opcional.
-
-### 4.2 Arquitectura interna (capas)
-```
-Diseño (paths/parametros SVG por expresión, por emoji)
-   ↓
-Catálogo (LIB: nombre, color, forma base, pools de expresión por estado)
-   ↓
-Motor de resorte (interpola parámetros numéricos en cada frame)
-   ↓
-Selector de estado (idle/near/hover/click + sorteo del pool)
-   ↓
-Renderer SVG (dibuja el emoji a partir de los parámetros actuales)
-   ↓
-Capa de eventos (mouseenter/leave, mousedown/up, mousemove global para "near")
-```
-
-### 4.3 API pública (borrador)
-```js
-import { createEmoji } from 'wissive';
-
-const emoji = createEmoji('mochi', {
-  target: document.querySelector('#slot'),
-  size: 120,
-  sound: true,       // requiere cuelume instalado
-  interactive: true, // false = solo decorativo, sin eventos
-});
-
-emoji.setEmotion('feliz');  // control programático
-emoji.destroy();            // limpieza (RAF + listeners)
-```
-
-### 4.4 Formatos de build
-- **ESM** — uso estándar con bundlers (Vite, Webpack, Rollup, Astro, etc.).
-- **UMD/IIFE** — uso directo con `<script>`, sin instalar nada, vía CDN (jsDelivr/unpkg).
-- **CJS** — compatibilidad con proyectos Node/legacy.
-
-### 4.5 Integración con frameworks
-Wissive no depende de ningún framework. Hay wrappers oficiales para React, Vue y Astro —
-`react`/`vue`/`astro` son *peer dependencies* opcionales, igual que Cuelume:
-
-```jsx
-// React — import { Wissive } from 'wissive/react'
-<Wissive name="mochi" size="lg" sound />
-```
-
-```vue
-<!-- Vue — import { Wissive } from 'wissive/vue' -->
-<script setup>
-import { Wissive } from 'wissive/vue';
-</script>
-<template>
-  <Wissive name="mochi" :options="{ size: 'lg', sound: true }" />
-</template>
-```
-
-```astro
----
-// Astro — import Wissive from 'wissive/astro' (export default: así compila
-// Astro el template de un .astro, no hay export nombrado posible)
-import Wissive from 'wissive/astro';
----
-<Wissive name="mochi" size="lg" sound />
-```
-
-El de Astro no resuelve un problema de timing — su `<script>` ya corre client-side sin
-ceremonia — resuelve repetición: usar el emoji en varias páginas sin copiar el `<script>` cada
-vez. Los de React/Vue sí empaquetan el patrón manual de siempre (`useEffect`/`onMounted` que
-llaman a `createEmoji()` en el montaje y `.destroy()` en el desmontaje), porque ahí sí hace
-falta esperar a que el DOM real exista. Fuente: [`src/react.tsx`](src/react.tsx),
-[`src/vue.ts`](src/vue.ts), [`src/astro/Wissive.astro`](src/astro/Wissive.astro).
-
-El patrón manual (sin depender de ningún wrapper) está documentado en
-[`examples/`](examples/) para los tres.
-
-### 4.6 Distribución
-- Publicación en npm bajo un solo paquete (`wissive`), con *exports* separados por formato.
-- Documentación y demo interactivo publicados como sitio estático (similar en espíritu al de
-  Cuelume: mostrar la librería funcionando en vivo en la propia página de docs).
-
----
-
-## 5. Alcance fuera de la v1
-
-Estas ideas quedan documentadas pero no forman parte del primer release (ver fases en
-`requerimientos.md`):
-- Secuencias encadenadas de expresiones (`.playSequence()`).
-- Seguimiento de cursor con la mirada (ojos que se mueven, no solo cambian).
-- Temas de color personalizados por el usuario de la librería.
-- Emojis adicionales más allá de los 14 iniciales.
+# Wissive
+
+**Micro-librería de JavaScript/TypeScript de emojis vivos reactivos con física de resorte real — añade micro vida a tu web.**
+
+[![npm version](https://img.shields.io/npm/v/wissive.svg?color=6366f1)](https://www.npmjs.com/package/wissive)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/wissive?color=10b981)](https://bundlephobia.com/package/wissive)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Sitio web y Documentación en vivo:** [https://wissive-docs.vercel.app/](https://wissive-docs.vercel.app/)  
+**Paquete en NPM:** [https://www.npmjs.com/package/wissive](https://www.npmjs.com/package/wissive)  
+**Repositorio en GitHub:** [https://github.com/EJCP3/wissive](https://github.com/EJCP3/wissive)
+
+---
+
+## Instalación rápida
+
+### Vía Gestor de Paquetes
+```bash
+# pnpm
+pnpm add wissive
+
+# npm
+npm install wissive
+
+# yarn
+yarn add wissive
+```
+
+```javascript
+import { createEmoji } from 'wissive';
+
+const emoji = createEmoji('mochi', {
+  target: document.querySelector('#slot'),
+  size: 120,
+});
+```
+
+### Vía CDN (sin instalación)
+```html
+<script src="https://cdn.jsdelivr.net/npm/wissive/dist/wissive.umd.js"></script>
+<div id="slot"></div>
+
+<script>
+  Wissive.create('mochi', {
+    target: document.querySelector('#slot'),
+    size: 120,
+  });
+</script>
+```
+
+---
+
+## ¿Qué es Wissive?
+
+Wissive es una librería de JavaScript/TypeScript vanilla (**sin frameworks ni dependencias de runtime obligatorias**) que renderiza personajes vectoriales reactivos en tiempo real. 
+
+No es una imagen estática ni un GIF: es un **motor de expresión** que dibuja el rostro por código (SVG) y lo interpola con **física de resorte amortiguada (*spring physics*)**, logrando un movimiento orgánico que reacciona de verdad al cursor, al teclado, al arrastre (*drag & drop*) y al tacto.
+
+---
+
+## Características Principales
+
+- **Catálogo de 14 personajes vivos**: Mochi, Zumi, Suri, Nima, Cota, Dozy, Lumo, Fidge, Brix, Wilt, Knot, Snug, Pip y Void.
+- **Crea tu propio emoji personalizado**: Mezcla más de 20 siluetas vectoriales, rasgos faciales, colores, sonidos y partículas con `createCustomEmoji()`.
+- **Física de resorte real**: Movimiento elástico y fluido sin transiciones CSS lineales rígidas.
+- **Seguimiento del cursor (*Gaze Tracking*)**: Los ojos siguen la posición del ratón en tiempo real.
+- **Arrastre con inercia (*Drag & Drop*)**: Arrastra los emojis por la pantalla con física y rebote.
+- **Secuencias de animación**: Encadena estados con `.playSequence()` en modos `once`, `loop` o `ping-pong`.
+- **Sonido sintetizado con Web Audio**: Integración opcional con [Cuelume](https://cuelume-site.pages.dev/).
+- **Emisor de partículas**: Ráfagas de destellos, estrellas y corazones con `.triggerParticles()`.
+- **Temas de color dinámicos**: Cambia la paleta en caliente (`auto`, `neon`, `pastel`, `gold`).
+- **Accesibilidad total**: `role="img"`, `aria-label` dinámico, soporte de teclado y respeto estricto a `prefers-reduced-motion`.
+- **Multi-Framework**: Wrappers oficiales y tipados para **React**, **Vue** y **Astro**.
+
+---
+
+## Crea tu Propio Emoji
+
+Puedes diseñar emojis completamente personalizados mezclando siluetas, ojos, bocas, colores y animaciones:
+
+```javascript
+import { createCustomEmoji, createEmoji } from 'wissive';
+
+// 1. Construir y registrar el emoji personalizado
+createCustomEmoji('mi-personaje', {
+  baseColor: '#FFD23F',
+  silhouette: 'circle', // 'circle', 'heart', 'starburst-puff', 'capsule', 'pear-blob', etc.
+  eyesFrom: 'mochi',
+  mouthFrom: 'suri',
+  motionFrom: 'zumi',
+  particlesFrom: 'mochi',
+  soundFrom: 'mochi',
+  stateBank: ['happy', 'excited', 'celebrate', 'playful'],
+});
+
+// 2. Instanciarlo en tu contenedor
+const miEmoji = createEmoji('mi-personaje', {
+  target: document.querySelector('#mi-slot'),
+  size: 100,
+  gazeTracking: true,
+  draggable: true,
+});
+```
+
+---
+
+## Integración con Frameworks
+
+Wissive incluye soporte nativo y componentes para los principales frameworks:
+
+### React
+```tsx
+import { Wissive } from 'wissive/react';
+
+export function MiComponente() {
+  return (
+    <Wissive
+      name="mochi"
+      size={120}
+      options={{
+        sound: true,
+        gazeTracking: true,
+        draggable: true,
+      }}
+    />
+  );
+}
+```
+
+### Vue
+```vue
+<script setup>
+import { Wissive } from 'wissive/vue';
+</script>
+
+<template>
+  <Wissive name="zumi" size="lg" :options="{ sound: true, draggable: true }" />
+</template>
+```
+
+### Astro
+```astro
+---
+import Wissive from 'wissive/astro';
+---
+
+<Wissive name="mochi" size={120} sound={true} />
+```
+
+---
+
+## API Reference
+
+### `createEmoji(name, options)`
+
+#### Opciones principales (`WissiveOptions`):
+| Opción | Tipo | Default | Descripción |
+|---|---|---|---|
+| `target` | `HTMLElement` | *(requerido)* | Elemento contenedor donde se monta el emoji. |
+| `size` | `WissiveSize` | `'base'` (120px) | Tamaño en px o preset (`'xs'`, `'sm'`, `'base'`, `'lg'`, `'xl'`, `'2xl'`). |
+| `interactive` | `boolean` | `true` | Habilita eventos de ratón, proximidad y hover. |
+| `draggable` | `boolean` | `true` | Permite arrastrar el emoji con inercia y física. |
+| `gazeTracking` | `boolean` | `false` | Los ojos siguen el cursor activamente. |
+| `sound` | `boolean` | `true` | Reproduce efectos de sonido si Cuelume está presente. |
+| `autonomousStates` | `boolean` | `true` | Deambula de forma autónoma entre emociones al estar en reposo. |
+| `theme` | `ThemeOption` | `'auto'` | Tema de color (`'auto'`, `'neon'`, `'pastel'`, `'gold'`). |
+| `reducedMotion` | `'auto' \| boolean` | `'auto'` | Respeta accesibilidad de movimiento reducido del sistema. |
+
+#### Métodos de la Instancia (`WissiveInstance`):
+```javascript
+const emoji = createEmoji('mochi', { target });
+
+emoji.setEmotion('excited');       // Cambia la emoción activa
+emoji.bounce();                   // Provoca un salto elástico
+emoji.spin(1);                    // Giro de 360°
+emoji.setGaze({ x: 0.5, y: -0.2 }); // Ajusta la dirección de la mirada
+emoji.setGazeTracking(true);      // Activa/desactiva seguimiento de cursor
+emoji.setTheme('neon');           // Cambia el tema de color en vivo
+emoji.triggerParticles(8);        // Emite una ráfaga de partículas
+emoji.playSequence([              // Reproduce una secuencia de estados
+  { state: 'thinking', duration: 800 },
+  { state: 'happy', duration: 1000 },
+], { mode: 'loop' });
+emoji.destroy();                  // Limpieza determinística de memoria y listeners
+```
+
+---
+
+## Enlaces y Recursos
+
+- **Documentación Interactiva:** [https://wissive-docs.vercel.app/](https://wissive-docs.vercel.app/)
+- **Código Fuente en GitHub:** [https://github.com/EJCP3/wissive](https://github.com/EJCP3/wissive)
+- **Reportar problemas:** [https://github.com/EJCP3/wissive/issues](https://github.com/EJCP3/wissive/issues)
+- **Licencia:** MIT © 2026

package/dist/index.d.ts

@@ -12,6 +12,8 @@ export declare const ALL_STATES: InteractionState[];
  */
 export declare const ALL_WANDERABLE_STATES: InteractionState[];
 
+export declare const ANGLES: number[];
+
 declare class AnimationLoop {
     private callbacks;
     private handle;
@@ -52,6 +54,11 @@ export declare const AUTONOMOUS_STATES: InteractionState[];
  */
 export declare function blendColors(colorA: string, colorB: string, factor: number): string;
 
+/**
+ * Interpola linealmente entre dos conjuntos de 64 radios
+ */
+export declare function blendProfiles(a: number[], b: number[], t: number): number[];
+
 /**
  * Construye una definición de emoji personalizado: base neutra (Cota),
  * silueta a elección (circle por default), con ojos/boca/animación tomados
@@ -69,8 +76,17 @@ export declare function checkContrast(bgColor: string, fgColor: string, minRatio
     passes: boolean;
 };
 
+export declare const clamp: (v: number, lo?: number, hi?: number) => number;
+
+/**
+ * Convierte polilínea cerrada de 64 puntos en curva Bézier cúbica Catmull-Rom cerrada continua
+ */
+export declare function closedCatmullRomPath(pts: Point[], tension?: number): string;
+
 export declare type CoreInteractionState = 'idle' | 'near' | 'hover' | 'click';
 
+export declare const COS: number[];
+
 /**
  * Construye (o reconstruye) un emoji personalizado, lo persiste en localStorage
  * y lo registra en LIB para poder usarlo directamente con createEmoji(name, ...).
@@ -95,6 +111,8 @@ export declare function createSequencePlayer(hooks: {
     applyStep: (params: Partial<FaceParameters>) => void;
 }): SequencePlayer;
 
+export declare function createStateManager(initialState?: InteractionState): StateManager;
+
 export declare type CueSoundType = 'chime' | 'sparkle' | 'droplet' | 'bloom' | 'whisper' | 'tick' | 'press' | 'release' | 'toggle' | 'success' | 'error' | 'page' | 'loading' | 'ready' | 'pulse' | 'scan' | 'arrival';
 
 export declare interface CustomEmojiOptions {
@@ -329,6 +347,8 @@ export declare interface FaceParameters {
      * 24: cat-cup-smirk]
      */
     mouthType: number;
+    /** Eyebrows visible toggle (0: hidden, 1: visible) */
+    showBrows: number;
     /** Eyebrow Y offset */
     browY: number;
     /** Eyebrow tilt angle in degrees (+ is angry \ /, - is sad / \) */
@@ -361,6 +381,11 @@ export declare interface FaceParameters {
 
 export declare type FrameCallback = (dt: number) => void;
 
+/**
+ * Genera el SVG `<path d="..." />` suave a partir de cualquier perfil de 64 radios
+ */
+export declare function generateSilhouettePath(radii: number[], cx?: number, cy?: number, radius?: number): string;
+
 /**
  * Calcula el ratio de contraste entre dos colores (e.g. 3:1, 4.5:1).
  */
@@ -380,11 +405,21 @@ export declare function getLuminance(color: string): number;
 
 export declare function getSilhouettePath(silhouette: SilhouetteType): string;
 
+/**
+ * Devuelve el perfil radial de 64 muestras para una silueta dada
+ */
+export declare function getSilhouetteProfile(type: SilhouetteType): number[];
+
 /**
  * Obtiene el tema sugerido para un estado dado, con fallback a la paleta predeterminada del emoji.
  */
 export declare function getThemeForState(_state: InteractionState, defaultBaseColor: string): EmojiTheme;
 
+/**
+ * Envolvente convexa de dos círculos (utilizado para cápsulas, gotas y peras)
+ */
+export declare function hullOfCircles(x1: number, y1: number, r1: number, x2: number, y2: number, r2v: number, steps?: number): Point[];
+
 export declare const IDLE_MOTIONS: Record<MotionType, IdleMotionFn>;
 
 /**
@@ -422,6 +457,8 @@ export declare function isReducedMotionPreferred(): boolean;
  */
 export declare function isTouchDevice(): boolean;
 
+export declare const lerp: (a: number, b: number, t: number) => number;
+
 export declare const LIB: Record<string, EmojiDefinition>;
 
 export declare type LifecycleState = 'sleeping' | 'waking' | 'idle' | 'listening' | 'thinking' | 'searching' | 'working';
@@ -451,11 +488,17 @@ export declare type MotionType = 'bouncy' | 'flutter' | 'serene' | 'float' | 'ca
 
 export declare interface MultiSpring<T extends Record<string, number>> {
     getValues: () => T;
+    setConfig: (config: Partial<SpringConfig> | TransitionProfile) => void;
     setTargets: (targets: Partial<T>) => void;
     setValues: (values: Partial<T>) => void;
     update: (dt: number) => boolean;
 }
 
+/**
+ * Normaliza los radios para que el radio máximo o medio sea consistente
+ */
+export declare function normalizeRadii(radii: number[], targetMax?: number): number[];
+
 export declare class ParticleEmitter {
     private particles;
     private canvas;
@@ -482,13 +525,29 @@ export declare const PERSONALITY_DRIVEN_STATES: InteractionState[];
 /** Elige uno al azar de `pool`, evitando repetir `previous` cuando hay más de una opción */
 export declare function pickWithoutRepeat<T>(pool: T[], previous: T | null): T;
 
+export declare interface Point {
+    x: number;
+    y: number;
+}
+
 export declare type ProductCycleState = 'spawning' | 'humming' | 'loading' | 'dictating' | 'writing' | 'sending' | 'receiving' | 'uploading' | 'notifying' | 'alerting' | 'dragging' | 'bouncing' | 'powering-down';
 
+export declare const PROFILE_SAMPLES = 64;
+
+/**
+ * Perfil radial a partir de polígono 2D por raycasting desde el centro
+ */
+export declare function profileFromPolygon(poly: Point[], cx?: number, cy?: number): number[];
+
+/** Round number to 2 decimals to keep SVG path string light & fast */
+export declare const r2: (v: number) => number;
+
 export declare type ReactionState = 'excited' | 'surprised' | 'suspicious' | 'angry' | 'drowsy' | 'happy' | 'curious' | 'confused' | 'bored' | 'proud' | 'shy' | 'sad' | 'laughing' | 'scared' | 'playful' | 'celebrate';
 
 export declare interface RenderOptions {
     flipX?: boolean;
     emphasis?: boolean;
+    radii?: number[];
 }
 
 export declare function renderSvgElement(silhouette: SilhouetteType, baseColor: string, params: FaceParameters, size: number, renderOptions?: RenderOptions): string;
@@ -539,8 +598,15 @@ export declare function setGlobalVolume(volume: number): void;
 
 export declare const sharedLoop: AnimationLoop;
 
+/**
+ * Perfiles radiales precalculados (64 muestras cada uno)
+ */
+export declare const SILHOUETTE_PROFILES: Record<SilhouetteType, number[]>;
+
 export declare type SilhouetteType = 'circle' | 'capsule' | 'rounded-squircle' | 'pear-blob' | 'egg-oval' | 'starburst-puff' | 'pill-vertical' | 'heart' | 'round-blob' | 'ghost-blob' | 'oval' | 'elongated-oval' | 'teardrop-blob' | 'flame-blob' | 'droopy-blob' | 'bear-blob' | 'spiky-blob' | 'cloud-blob' | 'wide-oval' | 'soft-round' | 'octopus-blob' | 'wave-blob';
 
+export declare const SIN: number[];
+
 export declare const SIZE_PRESETS: Record<WissivePresetSize, number>;
 
 export declare class SoundEngine {
@@ -559,6 +625,8 @@ export declare class SoundEngine {
 
 export declare const soundEngine: SoundEngine;
 
+export declare const SPRING_PRESETS: Record<TransitionProfile, SpringConfig>;
+
 export declare interface SpringConfig {
     stiffness: number;
     damping: number;
@@ -567,6 +635,7 @@ export declare interface SpringConfig {
 
 export declare interface SpringInstance {
     state: SpringState;
+    setConfig: (config: Partial<SpringConfig>) => void;
     setTarget: (target: number) => void;
     setCurrent: (value: number) => void;
     update: (dt: number) => boolean;
@@ -602,6 +671,7 @@ export declare interface StateGroup {
 export declare class StateManager {
     private currentState;
     private lastIndices;
+    constructor(initialState?: InteractionState);
     getState(): InteractionState;
     setState(newState: InteractionState): boolean;
     resolvePool(expressions: Record<string, FaceParameters[]>, state?: InteractionState): FaceParameters[];
@@ -613,14 +683,28 @@ export declare class StateManager {
  */
 export declare function subscribeToReducedMotion(onChange: (reduced: boolean) => void): () => void;
 
+/**
+ * Superellipse formula: |x/sx|^n + |y/sy|^n = 1
+ */
+export declare function superellipseProfile(n: number, sx?: number, sy?: number): number[];
+
 /**
  * Detecta si el dispositivo actual soporta hover real (puntero fino como mouse o trackpad).
  * Devuelve false en dispositivos táctiles primarios (smartphones, tablets sin mouse).
  */
 export declare function supportsHover(): boolean;
 
+export declare const TAU: number;
+
 export declare type ThemeOption = 'auto' | EmojiTheme;
 
+/**
+ * Convierte un perfil de 64 radios en 64 puntos 2D en coordenadas de SVG (cx, cy, radio base)
+ */
+export declare function toPoints(radii: number[], cx?: number, cy?: number, baseRadius?: number, scaleX?: number, scaleY?: number): Point[];
+
+export declare type TransitionProfile = 'smooth' | 'bouncy' | 'snappy' | 'gentle' | 'instant';
+
 declare const Wissive: {
     create: typeof createEmoji;
     createGroup: typeof createEmojiGroup;
@@ -662,6 +746,8 @@ export declare interface WissiveInstance {
     setReducedMotion: (setting: 'auto' | boolean) => void;
     setTheme: (theme: ThemeOption) => void;
     setSize: (size: WissiveSize) => void;
+    setSilhouette: (silhouette: SilhouetteType, duration?: number) => void;
+    setSpringConfig: (config: Partial<SpringConfig> | TransitionProfile) => void;
     triggerParticles: (count?: number) => void;
     playSequence: (steps: SequenceStep[], options?: SequenceOptions) => void;
     stopSequence: () => void;