@decido/tutor-engine — Cinematic Tutor Engine

Motor de visualización interactivo y declarativo controlado por JSON para la reproducción de tutoriales cinemáticos animados. Diseñado para orquestar animaciones, movimientos de cursor, subtítulos y narración sincronizada (TTS) en aplicaciones de Decido OS.

Características Clave

• Tutor Cinematic Document (TCD): Schema JSON completo para declarar escenas, capas (texto, SVG, código, LaTeX), animaciones y narración de forma estructurada.
• Cursor Virtual Interactivo: Cursor que apunta, subraya, encierra y guía visualmente la atención del usuario en sincronización con la narración.
• Narración y Subtítulos en Tiempo Real: Soporte nativo para Web Speech API con eventos de sincronización palabra por palabra y panel de subtítulos.
• Orquestación de Animaciones (GSAP): Soporte integrado para animaciones GSAP (typewriter, morphing SVG, dibujo lineal progresivo) con fallback automático de CSS.
• Arquitectura Basada en Patrones: Diseñado bajo patrones como Mediator, Iterator, Observer, Strategy, Command y Composite para máxima extensibilidad y bajo acoplamiento.
• Integración React + Zustand: Estado reactivo global sincronizado con hooks de fácil consumo.

Arquitectura de 7 Subsistemas

El motor divide las responsabilidades en 7 áreas independientes:

1. Parser & Validator (TCDParser): Valida y parsea el JSON entrante contra el schema de TCD y compila la línea de tiempo.
2. Director (SceneDirector): El mediador principal. Coordina la comunicación de eventos y el ciclo de vida de las escenas.
3. Timeline (TimelineController): El reloj de reproducción (rAF ticks) que controla play, pause, seek y velocidad.
4. Renderer (SlideRenderer): Maneja el árbol composite de capas (capas de texto, SVG, imágenes, HTML, LaTeX).
5. Cursor (VirtualCursor): Controla la visibilidad y coordenadas del cursor, mapeando selectores DOM a pixeles reales.
6. Narration (NarrationEngine): Sintetiza la voz mediante TTS y emite subtítulos.
7. Animation (AnimationOrchestrator): Orquesta las colas de comandos de animación (GSAP/CSS).

Instalación e Integración

1. Dependencias

Asegúrate de tener instalados React y GSAP en tu proyecto principal:

"dependencies": {
  "@decido/tutor-engine": "workspace:*",
  "gsap": "^3.12.0",
  "react": "^19.0.0",
  "zustand": "^5.0.3"
}

2. Uso Básico

import React from 'react';
import { CinematicPlayer, useTutorEngine } from '@decido/tutor-engine';
import docOctagon from '@decido/tutor-engine/examples/matematicas-octagon.tcd.json';

export const TutorView: React.FC = () => {
  const engine = useTutorEngine(docOctagon, {
    autoPlay: true,
    showControls: true,
    showSubtitles: true,
  });

  return (
    <div className="w-full h-[500px] rounded-2xl overflow-hidden border border-white/10 bg-slate-950">
      <CinematicPlayer engine={engine} theme="dark-glass" />
    </div>
  );
};

Licencia

Propiedad exclusiva de Decido OS. Todos los derechos reservados.