lumina-slides 9.0.4 → 9.0.6

package/src/core/Lumina.ts

@@ -1,6 +1,7 @@
-import { createApp, App as VueApp, watch } from 'vue';
+import { createApp, App as VueApp, watch, ref, type Ref } from 'vue';
 import LuminaDeck from '../components/LuminaDeck.vue';
 import LuminaStudio from '../components/studio/LuminaStudio.vue';
+import StudioEmbedRoot from '../components/studio/StudioEmbedRoot.vue';
 import LuminaSpeakerNotes from '../components/LuminaSpeakerNotes.vue';
 import LayoutStatement from '../components/layouts/LayoutStatement.vue';
 import LayoutHalf from '../components/layouts/LayoutHalf.vue';
@@ -18,7 +19,7 @@ import LuminaElement from '../components/base/LuminaElement.vue';
 import { createStore, StoreKey, LuminaStore } from './store';
 import { resolveTransitionConfig } from './animationConfig';
 import { computeStagger, resolveAnimationFromInput } from '../animation';
-import { createElementController } from './elementController';
+import { createElementController, createNoopElementController } from './elementController';
 import { parsePath, resolveId, getElementIds } from './elementResolver';
 import { elemId } from './elementId';
 import type { ElementPath } from './elementResolver';
@@ -34,8 +35,8 @@ import '../style/main.css';
  * @description
  * Mount a slide deck into a DOM element, load/patch deck data, subscribe to events (slideChange, action),
  * and export state for LLM context. Vanilla JS: use `engine.load(deck)`, `engine.element(id)`, `engine.on(...)`.
- * For reveal-on-demand: set `meta.initialElementState` and `meta.elementControl.defaultVisible: false`;
- * register `ready` and `slideChange` before `load`; then `engine.element(id).show()` or `revealInSequence`.
+ * Elements start hidden by default and cascade-reveal on slide enter. Set `elementControl.defaultVisible: true`
+ * to show all, or `slide.reveal: false` for manual control. Use `engine.element(id).show()` or `revealInSequence`.
  * `engine.element(id).animate()` and `getElementById` require the element's slide to be mounted (no-op/null otherwise).
  *
  * @example
@@ -44,9 +45,7 @@ import '../style/main.css';
  * import "lumina-slides/style.css";
  *
  * const engine = new Lumina("#app", { theme: "ocean", loop: true });
- * engine.on("ready", () => engine.revealInSequence(0));
- * engine.on("slideChange", (e) => engine.revealInSequence(e.index));
- * engine.load({ meta: { title: "Demo", elementControl: { defaultVisible: false } }, slides: [
+ * engine.load({ meta: { title: "Demo" }, slides: [
  *   { type: "statement", title: "Hello", subtitle: "World" }
  * ]});
  * engine.on("action", (p) => console.log("clicked", p));
@@ -59,9 +58,16 @@ import '../style/main.css';
  * @see IMPLEMENTATION.md
  * @see AGENTS.md
  */
+const DEFAULT_EMBED_DECK: Deck = {
+    meta: { title: 'Untitled' },
+    slides: [{ type: 'statement', title: 'New Slide', subtitle: '' }]
+};
+
 export class Lumina {
     private app: VueApp;
-    private store: LuminaStore;
+    private store: LuminaStore | null = null;
+    /** When studioEmbed is true, deck is driven by this ref; store is not used. */
+    private _embedDeckRef: Ref<Deck | null> | null = null;
 
     /** Key-value store: `engine.data.get/set/has/delete/clear/keys`. Persists across deck loads. */
     public readonly data: LuminaDataStore;
@@ -86,88 +92,93 @@ export class Lumina {
         // Generate unique channel ID for this instance
         this.speakerChannelId = `lumina-speaker-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 
-        // Create isolated store for this instance
-        this.store = createStore(options);
-
-        const dataApi: LuminaDataStore = {
-            get: (k) => this.store.getUserData(k),
-            set: (k, v) => { this.store.setUserData(k, v); return dataApi; },
-            has: (k) => this.store.hasUserData(k),
-            delete: (k) => this.store.deleteUserData(k),
-            clear: () => this.store.clearUserData(),
-            keys: () => Object.keys(this.store.state.userData)
-        };
-        this.data = dataApi;
-
-        // Apply initial theme
-        if (options.theme) {
-            ThemeManager.inject(options.theme);
-        }
-
-        // Initialize Vue App
-        this.app = options.studio ? createApp(LuminaStudio) : createApp(LuminaDeck);
-
-        // Dependency Injection
-        this.app.provide(StoreKey, this.store);
-        this.app.provide('LuminaEngine', this);
-
-        // Watch for state changes and emit public events
-        watch(() => this.store.state.currentIndex, (newIndex, oldIndex) => {
-            this.store.resetElementStateForSlide(newIndex);
-            const deck = this.store.state.deck;
-            const currentSlide = deck?.slides?.[newIndex];
-            if (currentSlide) {
-                bus.emit('slideChange', {
-                    index: newIndex,
-                    previousIndex: oldIndex ?? 0,
-                    slide: currentSlide
-                });
-                const rev = deck?.meta?.reveal ?? currentSlide?.reveal;
-                if (rev && typeof rev === 'object') {
-                    this.revealInSequence(newIndex, this.getRevealOptionsFromDeck(deck!, newIndex));
+        const isStudioEmbed = !!options.studioEmbed;
+
+        if (isStudioEmbed) {
+            this._embedDeckRef = ref<Deck | null>(
+                options.initialDeck && Array.isArray(options.initialDeck.slides)
+                    ? options.initialDeck
+                    : DEFAULT_EMBED_DECK
+            );
+            this.data = {
+                get: () => '',
+                set: () => this.data!,
+                has: () => false,
+                delete: () => false,
+                clear: () => {},
+                keys: () => []
+            } as LuminaDataStore;
+
+            if (options.theme) ThemeManager.inject(options.theme);
+
+            this.app = createApp(StudioEmbedRoot, { deckRef: this._embedDeckRef });
+        } else {
+            this.store = createStore(options);
+            const dataApi: LuminaDataStore = {
+                get: (k) => this.store!.getUserData(k),
+                set: (k, v) => { this.store!.setUserData(k, v); return dataApi; },
+                has: (k) => this.store!.hasUserData(k),
+                delete: (k) => this.store!.deleteUserData(k),
+                clear: () => this.store!.clearUserData(),
+                keys: () => Object.keys(this.store!.state.userData)
+            };
+            this.data = dataApi;
+
+            if (options.theme) ThemeManager.inject(options.theme);
+
+            this.app = options.studio ? createApp(LuminaStudio) : createApp(LuminaDeck);
+            this.app.provide(StoreKey, this.store);
+            this.app.provide('LuminaEngine', this);
+
+            watch(() => this.store!.state.currentIndex, (newIndex, oldIndex) => {
+                this.store!.resetElementStateForSlide(newIndex);
+                const deck = this.store!.state.deck;
+                const currentSlide = deck?.slides?.[newIndex];
+                if (currentSlide) {
+                    bus.emit('slideChange', {
+                        index: newIndex,
+                        previousIndex: oldIndex ?? 0,
+                        slide: currentSlide
+                    });
+                    // Reveal runs from Deck onEnter when the slide has mounted (elements in DOM).
                 }
-            }
-        });
+            });
 
-        // Watch for metadata changes (Theme, Orb, etc.)
-        watch(() => this.store.state.deck?.meta, (newMeta) => {
-            if (newMeta) {
-                // 1. Construct Theme Overrides from Meta
-                // - meta.themeConfig: full ThemeConfig object (e.g. from theme-custom-example.json)
-                // - meta.colors, meta.typography, etc.: direct overrides from Studio (take precedence)
-                const fromThemeConfig = newMeta.themeConfig || {};
-                const direct: Partial<ThemeConfig> = {
-                    colors: newMeta.colors,
-                    typography: newMeta.typography,
-                    spacing: newMeta.spacing,
-                    borderRadius: newMeta.borderRadius,
-                    effects: newMeta.effects,
-                    components: newMeta.components
-                };
-                const base = (fromThemeConfig && typeof fromThemeConfig === 'object' && !Array.isArray(fromThemeConfig) ? fromThemeConfig : {});
-                const overrides = deepMerge<ThemeConfig>(base as ThemeConfig, direct);
-
-                // Resolve theme: deck.theme (top-level, e.g. from theme-ocean.json) takes precedence over
-                // meta.theme, then constructor options. Ensures examples and loaded decks keep their theme.
-                const deck = this.store.state.deck;
-                const themeOrName = deck?.theme ?? newMeta.theme ?? this.store.state.options?.theme ?? 'default';
-
-                // 2. Dynamic Theme Application
-                // This ensures that any change in Studio (which updates deck.meta) is immediately reflected
-                // via CSS variables injected by ThemeManager.
-                ThemeManager.inject(themeOrName, overrides);
-
-                // 3. Fallback/Direct variable handling if needed (e.g. for specific legacy props)
-                if (newMeta.orbColor) {
-                    // Update the primary color variable as a fallback or if specifically mapped
-                    document.documentElement.style.setProperty('--lumina-colors-primary', newMeta.orbColor);
+            watch(() => this.store!.state.deck?.meta, (newMeta) => {
+                if (newMeta) {
+                    const fromThemeConfig = newMeta.themeConfig || {};
+                    const direct: Partial<ThemeConfig> = {
+                        colors: newMeta.colors,
+                        typography: newMeta.typography,
+                        spacing: newMeta.spacing,
+                        borderRadius: newMeta.borderRadius,
+                        effects: newMeta.effects,
+                        components: newMeta.components
+                    };
+                    const base = (fromThemeConfig && typeof fromThemeConfig === 'object' && !Array.isArray(fromThemeConfig) ? fromThemeConfig : {});
+                    const overrides = deepMerge<ThemeConfig>(base as ThemeConfig, direct);
+                    const deck = this.store!.state.deck;
+                    const themeOrName = deck?.theme ?? newMeta.theme ?? this.store!.state.options?.theme ?? 'default';
+                    ThemeManager.inject(themeOrName, overrides);
+                    if (newMeta.orbColor) {
+                        document.documentElement.style.setProperty('--lumina-colors-primary', newMeta.orbColor);
+                    }
+                    bus.emit('themeChange', { theme: typeof themeOrName === 'string' ? themeOrName : 'custom' });
                 }
+            }, { deep: true });
+
+            bus.on('action', (payload) => {
+                if (payload.type === 'slide-update' && typeof payload.slideIndex === 'number') {
+                    const { slideIndex, patch } = payload;
+                    if (patch && typeof patch === 'object') {
+                        if ('nodes' in patch) this.store!.updateNode(`slides.${slideIndex}.nodes`, patch.nodes);
+                        if ('edges' in patch) this.store!.updateNode(`slides.${slideIndex}.edges`, patch.edges);
+                    }
+                }
+                this.store!.recordAction(payload);
+            });
+        }
 
-                bus.emit('themeChange', { theme: typeof themeOrName === 'string' ? themeOrName : 'custom' });
-            }
-        }, { deep: true });
-
-        // Register Core Components
         this.app.component('layout-statement', LayoutStatement);
         this.app.component('layout-half', LayoutHalf);
         this.app.component('layout-features', LayoutFeatures);
@@ -182,26 +193,9 @@ export class Lumina {
         this.app.component('layout-free', LayoutFree);
         this.app.component('LuminaElement', LuminaElement);
 
-        // Internal Event Listeners
-        bus.on('action', (payload) => {
-            // Feature: Real-time Slide Updates (e.g. from Diagram Layout)
-            if (payload.type === 'slide-update' && typeof payload.slideIndex === 'number') {
-                const { slideIndex, patch } = payload;
-                if (patch && typeof patch === 'object') {
-                    if ('nodes' in patch) {
-                        this.store.updateNode(`slides.${slideIndex}.nodes`, patch.nodes);
-                    }
-                    if ('edges' in patch) {
-                        this.store.updateNode(`slides.${slideIndex}.edges`, patch.edges);
-                    }
-                }
-            }
-            this.store.recordAction(payload);
-        });
-
         this.app.mount(this.selector);
 
-        this.syncSpeakerNotes();
+        if (!isStudioEmbed) this.syncSpeakerNotes();
     }
 
     /**
@@ -219,13 +213,14 @@ export class Lumina {
             return;
         }
         try {
-            this.store.loadDeck(deckData);
-            bus.emit('ready', deckData);
-            const rev = deckData.meta?.reveal ?? deckData.slides?.[0]?.reveal;
-            if (rev && typeof rev === 'object') {
-                this.revealInSequence(0, this.getRevealOptionsFromDeck(deckData, 0));
+            if (this._embedDeckRef) {
+                this._embedDeckRef.value = deckData;
+            } else if (this.store) {
+                this.store.loadDeck(deckData);
+                // Reveal runs from Deck onEnter when the first slide has mounted.
+                this.syncSpeakerNotes();
             }
-            this.syncSpeakerNotes();
+            bus.emit('ready', deckData);
         } catch (e) {
             bus.emit('error', e instanceof Error ? e : new Error(String(e)));
         }
@@ -241,6 +236,7 @@ export class Lumina {
      * engine.patch({ meta: { title: "Updated Title" } });
      */
     public patch(diff: Partial<Deck>) {
+        if (!this.store) return;
         this.store.patchDeck(diff);
         bus.emit('patch', { diff: diff ?? {} });
         this.syncSpeakerNotes();
@@ -256,6 +252,7 @@ export class Lumina {
      * // "User is on slide 3 (features). Session: clicked 'Learn More' -> navigated next."
      */
     public exportState() {
+        if (!this.store) return Object.freeze({ status: 'active' as const, currentSlide: null, narrative: '', engagementLevel: 'Low Engagement', history: [] });
         const { currentIndex, deck, actionHistory } = this.store.state;
         const slide = deck?.slides[currentIndex];
         const context = actionHistory.map(a => `User ${a.type}ed on ${a.label || a.value}`).join(' -> ');
@@ -323,9 +320,9 @@ export class Lumina {
         bus.clear();
     }
 
-    /** Zero-based index of the currently visible slide. */
+    /** Zero-based index of the currently visible slide. In studioEmbed mode returns 0. */
     public get currentSlideIndex() {
-        return this.store.state.currentIndex;
+        return this.store ? this.store.state.currentIndex : 0;
     }
 
     /**
@@ -333,6 +330,7 @@ export class Lumina {
      * @param index - Zero-based slide index. Clamped to [0, slides.length - 1].
      */
     public goTo(index: number) {
+        if (!this.store) return;
         const from = this.store.state.currentIndex;
         this.store.goto(index);
         if (this.store.state.currentIndex !== from) {
@@ -343,6 +341,7 @@ export class Lumina {
 
     /** Advances to the next slide (or first if loop and at end). */
     public next() {
+        if (!this.store) return;
         const from = this.store.state.currentIndex;
         this.store.next();
         if (this.store.state.currentIndex !== from) {
@@ -353,6 +352,7 @@ export class Lumina {
 
     /** Goes to the previous slide (or last if loop and at start). */
     public prev() {
+        if (!this.store) return;
         const from = this.store.state.currentIndex;
         this.store.prev();
         if (this.store.state.currentIndex !== from) {
@@ -424,6 +424,7 @@ export class Lumina {
     public element(id: string): ElementController;
     public element(slideIndex: number, path: string | ElementPath): ElementController;
     public element(idOrSlide: string | number, path?: string | ElementPath): ElementController {
+        if (!this.store) return createNoopElementController(this, typeof idOrSlide === 'string' ? idOrSlide : '');
         if (typeof idOrSlide === 'number') {
             const slide = this.store.state.deck?.slides[idOrSlide];
             const p = parsePath(path!);
@@ -448,7 +449,7 @@ export class Lumina {
      * @see elements
      */
     public elementInCurrent(path: string | ElementPath): ElementController {
-        const i = this.store.state.currentIndex ?? 0;
+        const i = this.store ? this.store.state.currentIndex ?? 0 : 0;
         return this.element(i, path);
     }
 
@@ -473,6 +474,7 @@ export class Lumina {
      * @see DeckMeta.initialElementState
      */
     public elements(slideIndex?: number): string[] {
+        if (!this.store) return [];
         const i = slideIndex ?? this.store.state.currentIndex ?? 0;
         const slide = this.store.state.deck?.slides[i];
         if (!slide) return [];
@@ -577,6 +579,62 @@ export class Lumina {
         return { ...a, ...b };
     }
 
+    /**
+     * Options for the default cascade when no meta.reveal or slide.reveal is configured.
+     * Uses defaultCascadeDelayMs and defaultCascadeDuration from config; excludes the slide root.
+     */
+    private getDefaultCascadeOptions(index: number): RevealInSequenceOptions {
+        if (!this.store) return {};
+        const deck = this.store.state.deck;
+        const slide = deck?.slides?.[index] as BaseSlideData | undefined;
+        const cfg = resolveTransitionConfig(this.store, slide ?? undefined);
+        const slideRootId = slide ? resolveId(slide, index, ['slide']) : undefined;
+        return {
+            delayMs: cfg.defaultCascadeDelayMs,
+            duration: cfg.defaultCascadeDuration,
+            ...(slideRootId ? { exclude: [slideRootId] as readonly string[] } : {}),
+        };
+    }
+
+    /**
+     * Runs reveal for a slide if configured (default cascade, meta.reveal, or slide.reveal).
+     * Call when the slide has mounted (e.g. from Deck's onEnter) so elements exist in the DOM.
+     * Returns the reveal promise or undefined if no reveal runs.
+     */
+    public runRevealForSlideIfNeeded(slideIndex?: number): Promise<void> | undefined {
+        if (!this.store) return undefined;
+        const i = slideIndex ?? this.currentSlideIndex;
+        const opts = this.getRevealDecision(i);
+        if (opts === null) return undefined;
+        return this.revealInSequence(i, opts);
+    }
+
+    /**
+     * Decides whether and how to run reveal for a slide. Returns options to pass to revealInSequence,
+     * or null if no reveal should run.
+     */
+    private getRevealDecision(index: number): RevealInSequenceOptions | null {
+        const deck = this.store?.state.deck;
+        const slide = deck?.slides?.[index];
+        if (!slide) return null;
+
+        const rev = deck?.meta?.reveal ?? (slide as { reveal?: unknown }).reveal;
+
+        // Explicit opt-out: no reveal
+        if (rev === false) return null;
+
+        // Timeline-driven: no cascade
+        if ((slide as { timelineTracks?: unknown }).timelineTracks != null) return null;
+
+        // Explicit reveal config: use it
+        if (rev && typeof rev === 'object') {
+            return this.getRevealOptionsFromDeck(deck!, index);
+        }
+
+        // Default: fast cascade
+        return this.getDefaultCascadeOptions(index);
+    }
+
     /**
      * Reveals slide elements one by one with optional stagger and animation. Optionally
      * hides all first (hideFirst: true). Resolves when the sequence has been scheduled
@@ -591,6 +649,7 @@ export class Lumina {
      * await engine.revealInSequence(0, { only: ['s0-tag', 's0-title'], hideFirst: true });
      */
     public revealInSequence(slideIndex?: number, options?: RevealInSequenceOptions): Promise<void> {
+        if (!this.store) return Promise.resolve();
         const i = slideIndex ?? this.currentSlideIndex;
         let ids = this.elements(i);
         const opts = options ?? {};
@@ -677,6 +736,7 @@ export class Lumina {
      * slider.oninput = () => engine.seekTo(parseFloat(slider.value));
      */
     public seekTo(progress: number, slideIndex?: number): this {
+        if (!this.store) return this;
         const i = slideIndex ?? this.currentSlideIndex;
         const slide = this.store.state.deck?.slides[i];
         const timeline = slide?.timelineTracks;
@@ -703,6 +763,7 @@ export class Lumina {
      * // cancel() to stop
      */
     public playTimeline(durationSeconds = 5, slideIndex?: number): [Promise<void>, () => void] {
+        if (!this.store) return [Promise.resolve(), () => {}];
         const i = slideIndex ?? this.currentSlideIndex;
         const slide = this.store.state.deck?.slides[i];
         if (!slide?.timelineTracks || typeof slide.timelineTracks !== 'object') {

package/src/core/animationConfig.ts

@@ -89,6 +89,12 @@ export const ANIMATION_DEFAULTS = {
     revealDuration: 0.45,
     revealEase: 'power2.out',
 
+    // --- Default cascade (when no meta.reveal or slide.reveal) ---
+    /** Delay in ms between elements for implicit default cascade. Default 120. */
+    defaultCascadeDelayMs: 120,
+    /** Per-element duration (s) for implicit default cascade. Default 0.3. */
+    defaultCascadeDuration: 0.3,
+
     // --- elementController.animate ---
     elementDuration: 0.5,
     elementEase: 'power2.out',
@@ -133,6 +139,8 @@ export const ANIMATION_DEFAULTS = {
  * @property {number} revealDelayMs - revealInSequence delay between elements (ms). Default 400.
  * @property {number} revealDuration - revealInSequence per-element duration (s). Default 0.45.
  * @property {string} revealEase - revealInSequence ease. Default 'power2.out'.
+ * @property {number} defaultCascadeDelayMs - Default cascade delay between elements (ms). Default 120.
+ * @property {number} defaultCascadeDuration - Default cascade per-element duration (s). Default 0.3.
  * @property {number} elementDuration - element().animate() default duration (s). Default 0.5.
  * @property {string} elementEase - element().animate() default ease. Default 'power2.out'.
  * @property {string} elementOpacityTransition - CSS value for LuminaElement opacity. Default '0.35s ease-out'.
@@ -166,6 +174,8 @@ export type ResolvedTransitionConfig = {
     revealDelayMs: number;
     revealDuration: number;
     revealEase: string;
+    defaultCascadeDelayMs: number;
+    defaultCascadeDuration: number;
     elementDuration: number;
     elementEase: string;
     elementOpacityTransition: string;

package/src/core/elementController.ts

@@ -174,3 +174,21 @@ export function createElementController(
 
   return ctrl;
 }
+
+/** No-op controller when engine has no store (e.g. studioEmbed mode). */
+export function createNoopElementController(_engine: LuminaEngineLike, _id: string): IElementController {
+  const ctrl: IElementController = {
+    show: () => ctrl,
+    hide: () => ctrl,
+    toggle: () => ctrl,
+    opacity: () => ctrl,
+    transform: () => ctrl,
+    css: () => ctrl,
+    addClass: () => ctrl,
+    removeClass: () => ctrl,
+    animate: () => ctrl,
+    animateAsync: () => Promise.resolve(),
+    animateToProgress: () => ctrl
+  };
+  return ctrl;
+}

package/src/core/elementResolver.ts

@@ -122,7 +122,8 @@ const PATH_GENERATORS: Record<string, PathGenerator> = {
   features: (s) => {
     const arr = getValueAt(s, ['features']);
     const list = Array.isArray(arr) ? arr : [];
-    const paths: ElementPath[] = [['header'], ['title']];
+    // Omit header (parent of title/description) to avoid animating container + children = jump
+    const paths: ElementPath[] = [['title']];
     if (getValueAt(s, ['description'])) paths.push(['description']);
     return [...paths, ...list.map((_: unknown, i: number) => ['features', i] as ElementPath)];
   },
@@ -142,7 +143,8 @@ const PATH_GENERATORS: Record<string, PathGenerator> = {
   steps: (s) => {
     const arr = getValueAt(s, ['steps']);
     const list = Array.isArray(arr) ? arr : [];
-    const paths: ElementPath[] = [['header'], ['title']];
+    // Omit header (parent of title/subtitle) to avoid animating container + children = jump
+    const paths: ElementPath[] = [['title']];
     if (getValueAt(s, ['subtitle'])) paths.push(['subtitle']);
     return [...paths, ...list.map((_: unknown, i: number) => ['steps', i] as ElementPath)];
   },