lumina-slides 8.8.1 → 8.9.0

package/IMPLEMENTATION.md

@@ -0,0 +1,192 @@
+# Implementing lumina-slides
+
+Guía para integrar la librería `lumina-slides` en tu aplicación. Pensada para desarrolladores y para **agentes de código** (Cursor, Copilot, etc.) que escriben el código que consume la librería.
+
+---
+
+## 1. Instalación
+
+```bash
+npm install lumina-slides
+# Opcional, solo si usas slides tipo "chart":
+npm install lumina-slides chart.js
+```
+
+---
+
+## 2. Imports principales
+
+```ts
+import { Lumina, parsePartialJson, generateSystemPrompt, getLuminaJsonSchema } from "lumina-slides";
+import "lumina-slides/style.css";
+```
+
+Otras exportaciones útiles: `createDebouncedLoader`, `isSlideReady`, `generateThemePrompt`, tipos `Deck`, `LuminaOptions`, `LuminaEventMap`, etc.
+
+---
+
+## 3. Crear el motor y cargar un deck
+
+```ts
+const engine = new Lumina("#app", {
+  theme: "ocean",   // preset: default, ocean, midnight, forest, cyber, latte, sunset, monochrome
+  loop: true,
+  navigation: true,
+  touch: true,
+});
+
+engine.load({
+  meta: { title: "Mi presentación" },
+  slides: [
+    { type: "statement", title: "Título", subtitle: "Subtítulo" },
+    { type: "features", title: "Features", features: [
+      { title: "A", desc: "Desc A", icon: "star" },
+      { title: "B", desc: "Desc B", icon: "zap" },
+    ]},
+  ],
+});
+```
+
+---
+
+## 4. Actualizar el deck (patch)
+
+Para cambios incrementales sin recargar todo:
+
+```ts
+engine.patch({ meta: { title: "Nuevo título" } });
+// slides se reemplaza por completo si lo pasas:
+// engine.patch({ slides: [...nuevosSlides] });
+```
+
+---
+
+## 5. Eventos
+
+```ts
+engine.on("ready", (deck) => { /* deck cargado */ });
+engine.on("slideChange", ({ index, previousIndex, slide }) => { /* cambió la diapositiva */ });
+engine.on("action", (p) => {
+  // p: { type, label?, value? } — p.ej. clicks en botones
+});
+engine.on("error", (err) => { /* error interno */ });
+```
+
+Para desuscribirse: `engine.off("slideChange", handler)` con la misma referencia de función.
+
+---
+
+## 6. Navegación programática
+
+```ts
+engine.next();
+engine.prev();
+engine.goTo(3);
+const i = engine.currentSlideIndex;
+```
+
+---
+
+## 7. Estado para el agente / LLM
+
+```ts
+const state = engine.exportState();
+// { status, currentSlide: { index, id, type, title }, narrative, engagementLevel, history }
+// Útil para incluir en el contexto de un LLM: "El usuario está en la diapositiva X, ha hecho Y".
+```
+
+---
+
+## 8. Streaming desde un LLM
+
+Cuando el modelo va devolviendo JSON por chunks:
+
+```ts
+import { Lumina, parsePartialJson } from "lumina-slides";
+
+const engine = new Lumina("#app", { theme: "midnight" });
+let buffer = "";
+
+async function onStream(chunk: string) {
+  buffer += chunk;
+  const json = parsePartialJson(buffer);
+  if (json) engine.load(json);
+}
+```
+
+O con debounce para evitar parpadeos:
+
+```ts
+import { createDebouncedLoader } from "lumina-slides";
+
+const onChunk = createDebouncedLoader((deck) => engine.load(deck), 80);
+// En el bucle de stream: onChunk(buffer);
+```
+
+---
+
+## 9. Generar el system prompt para un LLM que crea slides
+
+Si un LLM va a generar el JSON del deck:
+
+```ts
+const systemPrompt = generateSystemPrompt({
+  mode: "fast",           // 'reasoning' si quieres CoT antes del JSON
+  includeSchema: true,
+  includeTheming: true,
+});
+// Usar systemPrompt como mensaje de sistema en OpenAI, Anthropic, etc.
+```
+
+Solo temas: `generateThemePrompt()`.
+
+---
+
+## 10. Schema JSON
+
+Para validar o para dárselo al LLM:
+
+```ts
+const schema = getLuminaJsonSchema();
+```
+
+---
+
+## 11. Destruir la instancia
+
+Al desmontar el componente o salir de la vista:
+
+```ts
+engine.destroy();
+```
+
+---
+
+## Estructura de un `Deck`
+
+```ts
+interface Deck {
+  meta: { title: string; author?: string; theme?: string; themeConfig?: ThemeConfig; [k: string]: any };
+  slides: Array<
+    | { type: "statement"; title: string; subtitle?: string; tag?: string; notes?: string }
+    | { type: "features"; title: string; features: { title: string; desc: string; icon?: string }[]; description?: string; notes?: string }
+    | { type: "timeline"; title: string; timeline: { date: string; title: string; description: string }[]; subtitle?: string; notes?: string }
+    | { type: "steps"; title: string; steps: { step: string; title: string; description?: string }[]; notes?: string }
+    | { type: "half"; imageSide: "left"|"right"; image: string; title: string; paragraphs: string[]; tag?: string; cta?: string; notes?: string }
+    | { type: "flex"; direction?: "horizontal"|"vertical"; elements: FlexElement[]; gap?: SpacingToken; padding?: SpacingToken; notes?: string }
+    | { type: "chart"; chartType: "bar"|"line"|"pie"|"doughnut"; data: { labels: string[]; datasets: { label: string; values: number[]; color?: string }[] }; title?: string; subtitle?: string; notes?: string }
+    | { type: "custom"; html: string; css?: string; notes?: string }
+    // + diagram, video, etc.
+  >;
+}
+```
+
+Los tipos detallados están en el paquete: `Deck`, `SlideStatement`, `SlideFeatures`, `LuminaOptions`, `LuminaEventMap`, etc.
+
+---
+
+## Dónde seguir
+
+- **API y tipos**: los JSDoc en el código y los `.d.ts` generados.
+- **Guía para agentes que generan slides**: [AGENTS.md](./AGENTS.md).
+- **Docs y playground**: [lumina-slides](https://pailletjuanpablo.github.io/lumina-slides/).