lumina-slides 8.9.4 → 9.0.0

package/src/views/StudioView.vue

@@ -0,0 +1,61 @@
+<template>
+    <div class="flex flex-col w-full h-screen bg-black text-white font-sans overflow-hidden">
+        <StudioToolbar />
+        <div class="flex flex-1 overflow-hidden relative">
+            <StudioSidebar />
+            <EditorCanvas />
+            <div class="w-72 bg-[#111] border-l border-[#333] flex flex-col">
+                <StudioInspector />
+            </div>
+
+            <!-- Floating Slide Navigator -->
+            <SlideNavigator />
+        </div>
+    </div>
+</template>
+
+<script setup lang="ts">
+import { onMounted, provide } from 'vue';
+import { useRoute } from 'vue-router';
+import { createStore, StoreKey } from '../core/store';
+import { createEditor, EditorKey } from '../composables/useEditor';
+import { getDeck, initFirebase } from '../utils/firebase';
+
+import StudioToolbar from '../components/studio/StudioToolbar.vue';
+import StudioSidebar from '../components/studio/StudioSidebar.vue';
+import StudioInspector from '../components/studio/StudioInspector.vue';
+import EditorCanvas from '../components/studio/EditorCanvas.vue';
+import SlideNavigator from '../components/studio/SlideNavigator.vue';
+
+// Initialize isolated Store & provide it
+const store = createStore({ studio: true });
+provide(StoreKey, store);
+
+// Initialize Editor State & Provide it
+const editor = createEditor(store);
+provide(EditorKey, editor);
+
+const route = useRoute();
+
+onMounted(async () => {
+    try {
+        initFirebase();
+    } catch (e) { }
+
+    const deckId = route.params.id as string;
+
+    if (deckId) {
+        try {
+            const deckData = await getDeck(deckId);
+            if (deckData) {
+                // Initialize editor with loaded deck via proper store method
+                store.loadDeck(deckData);
+            }
+        } catch (e) {
+            console.error("Failed to load deck for studio:", e);
+        }
+    } else {
+        // Handle new/empty deck case if needed, or initialized by Dashboard creation
+    }
+});
+</script>

package/src/vite-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="vite/client" />
+declare module '*.vue' {
+    import type { DefineComponent } from 'vue'
+    const component: DefineComponent<{}, {}, any>
+    export default component
+}

package/IMPLEMENTATION.md

@@ -1,418 +0,0 @@
-# Implementing lumina-slides
-
-Guide for integrating the `lumina-slides` library into your application. For developers and **code agents** (Cursor, Copilot, etc.) that write the code that consumes the library.
-
-**Vanilla JavaScript library:** use `import { Lumina } from "lumina-slides"`, `new Lumina(selector)`, and `engine.load(deck)`. The host app can be vanilla JS, React, or any framework; **Vue is not required**. All control (render, element control, animations, events) is done via the engine API and the deck JSON. The API is designed for vanilla JS.
-
----
-
-## 1. Installation
-
-```bash
-npm install lumina-slides
-# Optional, only if you use "chart" slides:
-npm install lumina-slides chart.js
-```
-
----
-
-## 2. Main imports
-
-```ts
-import { Lumina, parsePartialJson, generateSystemPrompt, getLuminaJsonSchema } from "lumina-slides";
-import "lumina-slides/style.css";
-```
-
-Other useful exports: `createDebouncedLoader`, `isSlideReady`, `generateThemePrompt`, types `Deck`, `LuminaOptions`, `LuminaEventMap`, etc.
-
----
-
-## 3. Create the engine and load a deck
-
-```ts
-const engine = new Lumina("#app", {
-  theme: "ocean",   // presets: default, ocean, midnight, forest, cyber, latte, sunset, monochrome
-  loop: true,
-  navigation: true,
-  touch: true,
-});
-
-engine.load({
-  meta: { title: "My presentation" },
-  slides: [
-    { type: "statement", title: "Title", subtitle: "Subtitle" },
-    { type: "features", title: "Features", features: [
-      { title: "A", desc: "Desc A", icon: "star" },
-      { title: "B", desc: "Desc B", icon: "zap" },
-    ]},
-  ],
-});
-```
-
----
-
-## 4. Update the deck (patch)
-
-For incremental updates without reloading:
-
-```ts
-engine.patch({ meta: { title: "New title" } });
-// slides are replaced entirely if provided:
-// engine.patch({ slides: [...newSlides] });
-```
-
----
-
-## 5. Events
-
-```ts
-engine.on("ready", (deck) => { /* deck loaded */ });
-engine.on("slideChange", ({ index, previousIndex, slide }) => { /* slide changed */ });
-engine.on("action", (p) => {
-  // p: { type, label?, value? } — e.g. button clicks
-});
-engine.on("error", (err) => { /* internal error */ });
-```
-
-To unsubscribe: `engine.off("slideChange", handler)` with the same function reference.
-
----
-
-## 6. Programmatic navigation
-
-```ts
-engine.next();
-engine.prev();
-engine.goTo(3);
-const i = engine.currentSlideIndex;
-```
-
----
-
-## 7. State for the agent / LLM
-
-```ts
-const state = engine.exportState();
-// { status, currentSlide: { index, id, type, title }, narrative, engagementLevel, history }
-// Use in LLM context: "User is on slide X, did Y".
-```
-
----
-
-## 8. Streaming from an LLM
-
-When the model streams JSON in chunks:
-
-```ts
-import { Lumina, parsePartialJson } from "lumina-slides";
-
-const engine = new Lumina("#app", { theme: "midnight" });
-let buffer = "";
-
-function onStream(chunk) {
-  buffer += chunk;
-  const json = parsePartialJson(buffer);
-  if (json) engine.load(json);
-}
-```
-
-Or with debounce to reduce flicker:
-
-```ts
-import { createDebouncedLoader } from "lumina-slides";
-
-const onChunk = createDebouncedLoader((deck) => engine.load(deck), 80);
-// In the stream loop: onChunk(buffer);
-```
-
----
-
-## 9. Generate the system prompt for an LLM that creates slides
-
-If an LLM will generate the deck JSON:
-
-```ts
-const systemPrompt = generateSystemPrompt({
-  mode: "fast",           // 'reasoning' for CoT before JSON
-  includeSchema: true,
-  includeTheming: true,
-});
-// Use systemPrompt as the system message in OpenAI, Anthropic, etc.
-```
-
-Theming only: `generateThemePrompt()`.
-
----
-
-## 10. JSON Schema
-
-To validate or pass to the LLM:
-
-```ts
-const schema = getLuminaJsonSchema();
-```
-
----
-
-## 11. Destroy the instance
-
-When unmounting or leaving the view:
-
-```ts
-engine.destroy();
-```
-
----
-
-## Deck structure
-
-```ts
-interface Deck {
-  meta: {
-    title: string;
-    author?: string;
-    theme?: string;
-    themeConfig?: ThemeConfig;
-    elementControl?: { defaultVisible?: boolean };  // false = all hidden by default
-    initialElementState?: { [id: string]: { visible?: boolean; opacity?: number; transform?: string; class?: string; style?: Record<string, string | number> } };
-    [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.
-  >;
-}
-```
-
-Detailed types in the package: `Deck`, `SlideStatement`, `SlideFeatures`, `LuminaOptions`, `LuminaEventMap`, etc.
-
----
-
-## Element IDs and `data-lumina-id` (vanilla JS / JSON API)
-
-The library assigns a `data-lumina-id` attribute to each controllable element when **rendering the deck from JSON**. You use only `engine.load(deck)` and the engine API; no framework or component code is required.
-
-**ID resolution order:** (1) `slide.id` for the root; (2) if the object at that path has `id: string`, it is used; (3) `slide.ids[path]` if present; (4) fallback `s{N}-{path}` (e.g. `s0-tag`, `s1-features-2`).
-
-**Discovering IDs from vanilla JS:** `engine.elements(slideIndex)` returns the array of ids for that slide. To predict ids without mounting: `getElementIds(slide, slideIndex)` or `resolveId(slide, slideIndex, path)` / `elemId(slideIndex, ...path)` (exported for advanced use).
-
-**Paths per slide type** (default id is `s{N}-{path}`):
-
-| Type     | Paths (e.g. `s0-tag`, `s1-features-0`) |
-|----------|----------------------------------------|
-| statement| `tag`, `title`, `subtitle`             |
-| features | `header`, `features.0`, `features.1`…  |
-| half     | `media`, `tag`, `title`, `paragraphs`, `cta` |
-| timeline | `title`, `subtitle`, `timeline.0`…     |
-| steps    | `header`, `steps.0`, `steps.1`…        |
-| flex     | `elements.0`, `elements.0.elements.0`… |
-| chart    | `title`, `subtitle`, `chart`           |
-| video    | `video`, `title`                       |
-| diagram  | `nodes.0`, `nodes.1`…, `edges.0`…      |
-| custom   | (none by default)                      |
-
-**Control from JSON:**
-
-- `meta.initialElementState`: `{ [id]: { visible?: false, opacity?, transform?, class?, style? } }` — initial state when the deck loads.
-- `meta.elementControl`: `{ defaultVisible?: boolean }` — if `false`, all elements start hidden; override per id with `initialElementState`.
-
-**APIs (vanilla JS):** `engine.element(id)`, `engine.element(slideIndex, path)`, `engine.getElementById(id)`, `engine.elements(slideIndex)`.
-
----
-
-## Element control and animations (vanilla JS)
-
-Use `engine.element(id)` or `engine.element(slideIndex, path)` to get an **ElementController**:
-
-- **Visibility:** `.show()`, `.hide()`, `.toggle(force?)`
-- **Style:** `.opacity(n)`, `.transform(s)`, `.css({ ... })`, `.addClass(name)`, `.removeClass(name)`
-- **Animations:** `.animate({ from?, to, duration?, ease?, onComplete? })`, `.animateAsync(...)`
-
-`engine.getElementById(id)` returns the DOM node with `data-lumina-id`, or `null` if the slide is not mounted. Animations (GSAP) are no-op when the node is null.
-
-**Avoiding null / no visible effect:** The element must be in the DOM when you call `.show()` or `.animate()`. Pattern in **vanilla JS**:
-
-1. **Register `ready` and `slideChange` before `engine.load(deck)`** so callbacks run when the deck/slide is mounted.
-
-2. **In `ready`:** use `setTimeout` (e.g. `(i + 1) * 700` ms per element) before each `engine.element(id).show()` for the first slide.
-
-3. **In `slideChange`:** when `index` is the slide with controlled elements, repeat the same `setTimeout` + `.show()` for that slide’s ids.
-
-4. **Order:** `new Lumina(...)` → `engine.on('ready', ...)` → `engine.on('slideChange', ...)` → `engine.load(deck)`.
-
-**Example (vanilla JS) — simple reveal with delay:**
-
-```js
-const engine = new Lumina("#app", { theme: "midnight" });
-
-engine.on("ready", (deck) => {
-  const ids = engine.elements(0);
-  ids.forEach((id, i) => {
-    setTimeout(() => engine.element(id).show(), (i + 1) * 500);
-  });
-});
-
-engine.on("slideChange", ({ index }) => {
-  const ids = engine.elements(index);
-  ids.forEach((id, i) => {
-    setTimeout(() => engine.element(id).show(), (i + 1) * 500);
-  });
-});
-
-engine.load({
-  meta: {
-    title: "Reveal",
-    elementControl: { defaultVisible: false },
-    initialElementState: { "s0-tag": { visible: false }, "s0-title": { visible: false }, "s0-subtitle": { visible: false } },
-  },
-  slides: [{ type: "statement", title: "Hello", subtitle: "World", tag: "Intro" }],
-});
-```
-
----
-
-## Delay-controlled animations (vanilla JS, no Vue)
-
-Staggered reveals and per-element animations are driven from vanilla JS using `setTimeout`, `engine.element(id).show()`, and `engine.element(id).animate()`. Register `ready` and `slideChange` **before** `engine.load(deck)`.
-
-**Helper to reveal a slide’s elements with delay and optional animation:**
-
-```js
-/**
- * Reveal all elements of a slide with staggered delay. Pure JavaScript, no Vue.
- * @param {import('lumina-slides').Lumina} engine
- * @param {number} slideIndex
- * @param {Object} [opts]
- * @param {number} [opts.delayMs=500] - Delay between each element (ms).
- * @param {boolean} [opts.animate=true] - If true, animate from { opacity: 0, y: 20 } to { opacity: 1, y: 0 }.
- * @param {number} [opts.animDuration=0.5] - Animation duration in seconds.
- */
-function revealSlideWithDelay(engine, slideIndex, opts = {}) {
-  const { delayMs = 500, animate = true, animDuration = 0.5 } = opts;
-  const ids = engine.elements(slideIndex);
-  if (!ids || !ids.length) return;
-
-  ids.forEach((id, i) => {
-    const t = (i + 1) * delayMs;
-    setTimeout(() => {
-      const el = engine.element(id);
-      el.show();
-      if (animate) {
-        el.animate({
-          from: { opacity: 0, y: 20 },
-          to: { opacity: 1, y: 0 },
-          duration: animDuration,
-          ease: "power2.out",
-        });
-      }
-    }, t);
-  });
-}
-```
-
-**Full HTML + vanilla JS example (delay-controlled animations):**
-
-```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8" />
-  <title>Lumina – delay-controlled animations (vanilla JS)</title>
-  <link rel="stylesheet" href="node_modules/lumina-slides/dist/style.css" />
-</head>
-<body>
-  <div id="app" style="width:100vw;height:100vh;"></div>
-  <script type="module">
-    import { Lumina } from "lumina-slides";
-
-    const engine = new Lumina("#app", { theme: "midnight" });
-
-    function revealSlideWithDelay(engine, slideIndex, opts = {}) {
-      const { delayMs = 500, animate = true, animDuration = 0.5 } = opts;
-      const ids = engine.elements(slideIndex);
-      if (!ids || !ids.length) return;
-      ids.forEach((id, i) => {
-        setTimeout(() => {
-          engine.element(id).show();
-          if (animate) {
-            engine.element(id).animate({
-              from: { opacity: 0, y: 20 },
-              to: { opacity: 1, y: 0 },
-              duration: animDuration,
-              ease: "power2.out",
-            });
-          }
-        }, (i + 1) * delayMs);
-      });
-    }
-
-    // Must register before load so callbacks run when DOM is ready
-    engine.on("ready", () => revealSlideWithDelay(engine, 0, { delayMs: 600, animDuration: 0.5 }));
-    engine.on("slideChange", ({ index }) => revealSlideWithDelay(engine, index, { delayMs: 600, animDuration: 0.5 }));
-
-    engine.load({
-      meta: {
-        title: "Staggered reveal",
-        elementControl: { defaultVisible: false },
-        initialElementState: {
-          "s0-tag": { visible: false },
-          "s0-title": { visible: false },
-          "s0-subtitle": { visible: false },
-          "s1-header": { visible: false },
-          "s1-features-0": { visible: false },
-          "s1-features-1": { visible: false },
-        },
-      },
-      slides: [
-        { type: "statement", title: "Welcome", subtitle: "Each line appears with a delay", tag: "Intro" },
-        { type: "features", title: "Highlights", features: [
-          { title: "First", desc: "Revealed after 600ms", icon: "star" },
-          { title: "Second", desc: "Revealed after 1200ms", icon: "zap" },
-        ]},
-      ],
-    });
-  </script>
-</body>
-</html>
-```
-
-**Animation-only (no show/hide), with custom stagger:**
-
-```js
-engine.on("ready", () => {
-  const ids = engine.elements(0);
-  ids.forEach((id, i) => {
-    setTimeout(() => {
-      engine.element(id).animate({
-        from: { opacity: 0, scale: 0.95 },
-        to: { opacity: 1, scale: 1 },
-        duration: 0.6,
-        ease: "back.out(1.2)",
-      });
-    }, i * 400);
-  });
-});
-```
-
----
-
-## Animation options (engine and deck)
-
-- **Engine options:** `options.animation: { enabled?: boolean, type?: 'fade'|'cascade'|'zoom', durationIn?, durationOut? }` when creating `new Lumina(selector, options)`.
-- **Slide transitions** are applied by the engine; you listen to `slideChange` for timing.
-- **Per-element animations** are done with `engine.element(id).animate({ from: { opacity: 0, y: 20 }, to: { opacity: 1, y: 0 }, duration: 0.5 })` from vanilla JS.
-
----
-
-## Where to go next
-
-- **API and types:** JSDoc in the code and generated `.d.ts`.
-- **Guide for agents that generate slides:** [AGENTS.md](./AGENTS.md).
-- **Docs and playground:** [lumina-slides](https://pailletjuanpablo.github.io/lumina-slides/).