lumina-slides 9.0.1 → 9.0.3

package/src/components/site/SiteExamples.vue

@@ -36,6 +36,7 @@ const router = useRouter();
 const decks = [
     { id: 'deck', title: 'Feature Showcase', description: 'A comprehensive tour of all major features.', icon: '🚀' },
     { id: 'layout-element-control', title: 'Element Control', description: 'Reveal-on-demand: elements start hidden and appear automatically.', icon: '🎭' },
+    { id: 'layout-template-tags', title: 'Template Tags', description: '{{key}} placeholders in slide content, resolved from engine.data. Updates reactively.', icon: '🏷️' },
     { id: 'animation-presets', title: 'Animation: Presets', description: 'Built-in presets: fadeUp, scaleIn, spring. Use with animate() or revealInSequence.', icon: '✨' },
     { id: 'animation-stagger', title: 'Animation: Stagger', description: 'Stagger modes: center-out, wave, random. Control order and timing.', icon: '〰️' },
     { id: 'animation-timeline', title: 'Animation: Timeline', description: 'Remotion-style: scrub 0–1, keyframes per element, seekTo and playTimeline.', icon: '⏯️' },

package/src/core/Lumina.ts

@@ -25,7 +25,7 @@ import type { ElementPath } from './elementResolver';
 import { bus } from './events';
 import { ThemeManager, deepMerge } from './theme';
 import { SpeakerChannel } from './speaker-channel';
-import type { Deck, LuminaOptions, LuminaEventMap, LuminaDataStore, SpeakerSyncPayload, BaseSlideData, ElementController, RevealInSequenceOptions, TimelineTracks, ThemeConfig } from './types';
+import type { Deck, LuminaOptions, LuminaEventMap, LuminaDataStore, SpeakerSyncPayload, BaseSlideData, ElementController, RevealInSequenceOptions, ThemeConfig } from './types';
 import '../style/main.css';
 
 /**
@@ -114,13 +114,18 @@ export class Lumina {
         // Watch for state changes and emit public events
         watch(() => this.store.state.currentIndex, (newIndex, oldIndex) => {
             this.store.resetElementStateForSlide(newIndex);
-            const currentSlide = this.store.state.deck?.slides[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));
+                }
             }
         });
 
@@ -130,8 +135,8 @@ export class Lumina {
                 // 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 as { themeConfig?: object }).themeConfig || {};
-                const direct = {
+                const fromThemeConfig = newMeta.themeConfig || {};
+                const direct: Partial<ThemeConfig> = {
                     colors: newMeta.colors,
                     typography: newMeta.typography,
                     spacing: newMeta.spacing,
@@ -139,7 +144,8 @@ export class Lumina {
                     effects: newMeta.effects,
                     components: newMeta.components
                 };
-                const overrides = deepMerge(fromThemeConfig as Record<string, unknown>, direct as Record<string, unknown>) as ThemeConfig;
+                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.
@@ -208,13 +214,17 @@ export class Lumina {
      * engine.load({ meta: { title: "Q4 Review" }, slides: [ { type: "statement", title: "Intro" } ] });
      */
     public load(deckData: Deck) {
-        if (!deckData || !Array.isArray((deckData as any)?.slides)) {
+        if (!deckData || !Array.isArray(deckData.slides)) {
             bus.emit('error', new Error('Invalid deck: expected { meta?, slides: [] }'));
             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));
+            }
             this.syncSpeakerNotes();
         } catch (e) {
             bus.emit('error', e instanceof Error ? e : new Error(String(e)));
@@ -230,7 +240,7 @@ export class Lumina {
      * @example
      * engine.patch({ meta: { title: "Updated Title" } });
      */
-    public patch(diff: any) {
+    public patch(diff: Partial<Deck>) {
         this.store.patchDeck(diff);
         bus.emit('patch', { diff: diff ?? {} });
         this.syncSpeakerNotes();
@@ -257,7 +267,7 @@ export class Lumina {
                 index: currentIndex,
                 id: slide?.id || currentIndex,
                 type: slide?.type,
-                title: (slide && 'title' in slide ? (slide as any).title : null) || "(No Title)"
+                title: (typeof slide?.title === 'string' ? slide.title : null) || "(No Title)"
             },
             narrative: `User is currently on slide ${currentIndex + 1}. Session Flow: ${context || "Just started"}.`,
             engagementLevel: interest,
@@ -368,7 +378,8 @@ export class Lumina {
         if (!container) return null;
         const root = container.querySelector('[data-lumina-root]') || container;
         const escaped = id.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-        return (root.querySelector(`[data-lumina-id="${escaped}"]`) as HTMLElement) || null;
+        const el = root.querySelector(`[data-lumina-id="${escaped}"]`);
+        return el instanceof HTMLElement ? el : null;
     }
 
     /**
@@ -422,28 +433,50 @@ export class Lumina {
         return createElementController(this.store, this, idOrSlide);
     }
 
+    /**
+     * Returns the element at the given path on the current slide. Shorthand for
+     * engine.element(engine.currentSlideIndex, path). Use when you don't need the slide index.
+     *
+     * @param path - Logical path (e.g. "title", "features.0", ["elements", 0, "elements", 1]).
+     * @returns ElementController for that element.
+     *
+     * @example
+     * engine.elementInCurrent("title").show();
+     * engine.elementInCurrent("features.0").animate({ from: { opacity: 0 }, to: { opacity: 1 }, duration: 0.5 });
+     *
+     * @see element
+     * @see elements
+     */
+    public elementInCurrent(path: string | ElementPath): ElementController {
+        const i = this.store.state.currentIndex ?? 0;
+        return this.element(i, path);
+    }
+
     /**
      * Returns all element ids for a slide. Use to discover which ids exist (e.g. for
      * meta.initialElementState, or to iterate and control elements). Each id can be passed to
      * engine.element(id). Uses the same path→id logic as element(slideIndex, path); ids follow
-     * resolveId (explicit id, slide.ids, or elemId(slideIndex, ...path)).
+     * resolveId (explicit id, slide.ids, or slide.id / elemId(slideIndex, ...path) as fallback).
      *
-     * @param slideIndex - Zero-based slide index. If out of range or deck not loaded, returns [].
-     * @returns Array of id strings (e.g. ["s0-slide","s0-tag","s0-title","s0-subtitle"] for a statement slide).
+     * @param slideIndex - Zero-based slide index. Omit to use the current slide. If out of range or deck not loaded, returns [].
+     * @returns Array of id strings (e.g. ["s0-slide","s0-tag","s0-title","s0-subtitle"] or ["intro-slide","intro-tag",...] when slide.id is set).
      *
      * @example
-     * const ids = engine.elements(0);
-     * ids.forEach(id => { if (id.endsWith('-title')) engine.element(id).hide(); });
+     * engine.elements();        // current slide
+     * engine.elements(0);
+     * engine.elements().forEach(id => { if (id.endsWith('-title')) engine.element(id).hide(); });
      *
      * @see element
+     * @see elementInCurrent
      * @see getElementIds
      * @see resolveId
      * @see DeckMeta.initialElementState
      */
-    public elements(slideIndex: number): string[] {
-        const slide = this.store.state.deck?.slides[slideIndex];
+    public elements(slideIndex?: number): string[] {
+        const i = slideIndex ?? this.store.state.currentIndex ?? 0;
+        const slide = this.store.state.deck?.slides[i];
         if (!slide) return [];
-        return getElementIds(slide, slideIndex);
+        return getElementIds(slide, i);
     }
 
     /**
@@ -529,13 +562,28 @@ export class Lumina {
         return new Promise((resolve) => setTimeout(resolve, ms));
     }
 
+    /**
+     * Merges meta.reveal and slide.reveal into options for revealInSequence. slide overrides meta.
+     * Used when auto-running reveal from declarative slide.reveal or meta.reveal in the deck JSON.
+     */
+    private getRevealOptionsFromDeck(
+        deck: { meta?: { reveal?: RevealInSequenceOptions }; slides?: ReadonlyArray<{ reveal?: RevealInSequenceOptions }> },
+        index: number
+    ): RevealInSequenceOptions {
+        const meta = deck.meta;
+        const slide = deck.slides?.[index];
+        const a = (meta?.reveal && typeof meta.reveal === 'object') ? meta.reveal : {};
+        const b = (slide?.reveal && typeof slide.reveal === 'object') ? slide.reveal : {};
+        return { ...a, ...b };
+    }
+
     /**
      * Reveals slide elements one by one with optional stagger and animation. Optionally
      * hides all first (hideFirst: true). Resolves when the sequence has been scheduled
      * (does not wait for the last animation to finish).
      *
      * @param slideIndex - Zero-based slide index. Omit to use the current slide.
-     * @param options - Stagger delay, animation from/to, and filters (only, exclude).
+     * @param options - Stagger delay, animation from/to, and filters (only, exclude). Or from slide.reveal / meta.reveal when auto-run.
      * @returns Promise that resolves after the last element's scheduled reveal time.
      *
      * @example
@@ -554,6 +602,7 @@ export class Lumina {
         const delayMs = opts.delayMs ?? cfg.revealDelayMs;
         const animate = opts.animate !== false;
 
+        const motions = this.store.state.deck?.meta?.motions;
         const resolved = resolveAnimationFromInput(
             {
                 preset: opts.preset,
@@ -563,7 +612,8 @@ export class Lumina {
                 ease: opts.ease,
                 duration: opts.duration,
             },
-            { from: { opacity: 0, y: 16 }, to: { opacity: 1, y: 0 }, ease: cfg.revealEase, duration: cfg.revealDuration }
+            { from: { opacity: 0, y: 16 }, to: { opacity: 1, y: 0 }, ease: cfg.revealEase, duration: cfg.revealDuration },
+            motions
         );
 
         const steps = computeStagger({
@@ -628,7 +678,7 @@ export class Lumina {
      */
     public seekTo(progress: number, slideIndex?: number): this {
         const i = slideIndex ?? this.currentSlideIndex;
-        const slide = this.store.state.deck?.slides[i] as BaseSlideData & { timelineTracks?: TimelineTracks } | undefined;
+        const slide = this.store.state.deck?.slides[i];
         const timeline = slide?.timelineTracks;
         this._timelineProgress = Math.max(0, Math.min(1, progress));
         bus.emit('timelineSeek', { progress: this._timelineProgress, slideIndex: i });
@@ -654,7 +704,7 @@ export class Lumina {
      */
     public playTimeline(durationSeconds = 5, slideIndex?: number): [Promise<void>, () => void] {
         const i = slideIndex ?? this.currentSlideIndex;
-        const slide = this.store.state.deck?.slides[i] as BaseSlideData & { timelineTracks?: TimelineTracks } | undefined;
+        const slide = this.store.state.deck?.slides[i];
         if (!slide?.timelineTracks || typeof slide.timelineTracks !== 'object') {
             return [Promise.resolve(), () => {}];
         }
@@ -799,11 +849,8 @@ export class Lumina {
         const currentSlide = deck.slides[currentIndex];
         const nextSlide = deck.slides[currentIndex + 1];
 
-        const getSlideTitle = (slide: BaseSlideData | undefined): string | undefined => {
-            if (!slide) return undefined;
-            if ('title' in slide && typeof (slide as any).title === 'string') return (slide as any).title;
-            return undefined;
-        };
+        const getSlideTitle = (slide: BaseSlideData | undefined): string | undefined =>
+            (slide && typeof slide.title === 'string' ? slide.title : undefined);
 
         this.speakerChannel.send({
             action: 'state',

package/src/core/animationConfig.ts

@@ -232,7 +232,7 @@ function pickCanonical(src: Record<string, unknown> | null | undefined): Partial
  * @see ResolvedTransitionConfig
  * @see LuminaAnimationOptions
  */
-export function resolveTransitionConfig(store: LuminaStore | null | undefined, slideData?: BaseSlideData | null): ResolvedTransitionConfig {
+export function resolveTransitionConfig(store: LuminaStore | null | undefined, slideData?: Readonly<BaseSlideData> | null): ResolvedTransitionConfig {
     const base = { ...ANIMATION_DEFAULTS } as unknown as Record<string, unknown>;
 
     const opt = (store?.state?.options?.animation || {}) as Record<string, unknown>;

package/src/core/elementController.ts

@@ -40,7 +40,7 @@ export function createElementController(
   }
 
   function getClass(): string {
-    return (store.state.elementState[id]?.class as string) || '';
+    return store.state.elementState[id]?.class ?? '';
   }
 
   const ctrl: IElementController = {
@@ -121,12 +121,17 @@ export function createElementController(
         const vb = keyframes[String(b)] ?? {};
         const t = (progress - a) / (b - a);
         state = {};
-        for (const prop of ['opacity', 'x', 'y', 'scale', 'rotate'] as const) {
+        const numericKeys = ['opacity', 'x', 'y', 'scale', 'rotate'] as const;
+        for (const prop of numericKeys) {
           const pa = va[prop];
           const pb = vb[prop];
-          if (typeof pa === 'number' && typeof pb === 'number') (state as Record<string, number>)[prop] = pa + (pb - pa) * t;
-          else if (pb !== undefined) (state as Record<string, unknown>)[prop] = pb;
-          else if (pa !== undefined) (state as Record<string, unknown>)[prop] = pa;
+          if (typeof pa === 'number' && typeof pb === 'number') {
+            state[prop] = pa + (pb - pa) * t;
+          } else if (typeof pb === 'number') {
+            state[prop] = pb;
+          } else if (typeof pa === 'number') {
+            state[prop] = pa;
+          }
         }
         if (typeof vb.visible === 'boolean') state.visible = vb.visible;
         else if (typeof va.visible === 'boolean') state.visible = va.visible;
@@ -153,14 +158,15 @@ export function createElementController(
     const el = engine.getElementById(id);
     if (!el) return;
     const cfg = resolveTransitionConfig(store, undefined);
+    const motions = store.state.deck?.meta?.motions;
     const { from, to, ease, duration } = resolveAnimationFromInput(opts, {
       duration: cfg.elementDuration,
       ease: cfg.elementEase,
-    });
+    }, motions);
     const cb = onCompleteOverride ?? opts.onComplete;
-    const toVars = { ...to, duration, ease, overwrite: true, onComplete: cb } as gsap.TweenVars;
+    const toVars: gsap.TweenVars = { ...to, duration, ease, overwrite: true, onComplete: cb };
     if (from && Object.keys(from).length) {
-      gsap.fromTo(el, from as gsap.TweenVars, toVars);
+      gsap.fromTo(el, from, toVars);
     } else {
       gsap.to(el, toVars);
     }

package/src/core/elementResolver.ts

@@ -40,7 +40,7 @@ export function pathToKey(path: ElementPath): string {
  * @param path - Path segments (e.g. ['features', 0] or ['elements', 0, 'elements', 1]).
  * @returns The value at that path, or undefined if missing.
  */
-export function getValueAt(slide: BaseSlideData, path: ElementPath): unknown {
+export function getValueAt(slide: Readonly<BaseSlideData>, path: ElementPath): unknown {
   if (!slide || !path.length) return undefined;
   return getByPath(slide, pathToKey(path));
 }
@@ -71,7 +71,8 @@ export function parsePath(input: string | ElementPath): ElementPath {
  * 1. Path [] or ['slide'] → slide.id or elemId(slideIndex, 'slide').
  * 2. If the value at path is an object with string `id` → use it (e.g. feature.id, node.id).
  * 3. If slide.ids[pathToKey(path)] exists → use it (supports compound keys: 'tag', 'features.0', 'elements.0.elements.1').
- * 4. Otherwise → elemId(slideIndex, ...path) (e.g. "s0-tag", "s1-elements-0-elements-1").
+ * 4. Otherwise → if slide.id is set, "{slide.id}-{path}"; else elemId(slideIndex, ...path)
+ *    (e.g. "intro-tag" with slide.id "intro", or "s0-tag" when no slide.id).
  *
  * @param slide - The slide data.
  * @param slideIndex - Zero-based slide index (for elemId fallback).
@@ -83,7 +84,7 @@ export function parsePath(input: string | ElementPath): ElementPath {
  * @see elemId
  */
 export function resolveId(
-  slide: BaseSlideData,
+  slide: Readonly<BaseSlideData>,
   slideIndex: number,
   path: ElementPath
 ): string {
@@ -99,11 +100,16 @@ export function resolveId(
   if (key && slideAny?.ids?.[key]) {
     return slideAny.ids[key];
   }
+  // Fallback: use slide.id as namespace when present, so IDs stay stable when slides are
+  // inserted, removed or reordered. Otherwise s{N}-{path} (same as before).
+  if (slideAny?.id != null && slideAny.id !== '') {
+    return `${slideAny.id}-${path.map(String).join('-')}`;
+  }
   return elemId(slideIndex, ...path);
 }
 
 /** Function that returns all logical element paths for a given slide. One per layout type. */
-export type PathGenerator = (slide: BaseSlideData) => ElementPath[];
+export type PathGenerator = (slide: Readonly<BaseSlideData>) => ElementPath[];
 
 /** Map of slide.type → path generator. Extend to support new layouts. */
 const PATH_GENERATORS: Record<string, PathGenerator> = {
@@ -202,6 +208,6 @@ export function getElementPaths(slide: BaseSlideData): ElementPath[] {
  * @see Lumina.elements
  * @see DeckMeta.initialElementState
  */
-export function getElementIds(slide: BaseSlideData, slideIndex: number): string[] {
+export function getElementIds(slide: Readonly<BaseSlideData>, slideIndex: number): string[] {
   return getElementPaths(slide).map((p) => resolveId(slide, slideIndex, p));
 }

package/src/core/store.ts

@@ -267,7 +267,7 @@ export function createStore(initialOptions: LuminaOptions = {}) {
      * Feature: Diff Updates
      * Patches the current deck with partial data.
      */
-    function patchDeck(partial: any) {
+    function patchDeck(partial: Partial<Deck>) {
         if (!state.deck) return;
         const merged = deepMerge(state.deck, partial);
         state.deck = ensureDragKeys(merged);

package/src/core/types.ts

@@ -362,6 +362,17 @@ export interface AnimateOptions {
     onComplete?: () => void;
 }
 
+/**
+ * Motion definition for meta.motions. Defines from/to/ease (and optional duration) for
+ * use when reveal.motion or animate({ motion: id }) references it. Overrides built-in presets when same id.
+ */
+export interface MotionDef {
+    from?: Record<string, string | number>;
+    to?: Record<string, string | number>;
+    ease?: string;
+    duration?: number;
+}
+
 /**
  * Options for `Lumina.revealInSequence`. Controls staggered reveal of slide elements.
  *
@@ -401,9 +412,9 @@ export interface RevealInSequenceOptions {
     /** If true, hide all elements before starting the sequence. Default: true */
     hideFirst?: boolean;
     /** Only reveal these element ids (subset). Order follows slide elements. */
-    only?: string[];
+    only?: readonly string[];
     /** Exclude these element ids from the sequence. */
-    exclude?: string[];
+    exclude?: readonly string[];
 }
 
 /**
@@ -437,8 +448,8 @@ export type TimelineKeyframes = Record<string, TimelineKeyframeState>;
 export type TimelineTracks = Record<string, TimelineKeyframes>;
 
 /**
- * Fluent API to control one slide element in real time. Returned by `engine.element(id)`
- * and `engine.element(slideIndex, path)`. All methods return `this` for chaining.
+ * Fluent API to control one slide element in real time. Returned by `engine.element(id)`,
+ * `engine.element(slideIndex, path)`, and `engine.elementInCurrent(path)`. All methods return `this` for chaining.
  *
  * Use for: starting with an empty slide and revealing items in order, hiding highlights,
  * animating entrances on demand, or syncing with voice/agent.
@@ -451,6 +462,7 @@ export type TimelineTracks = Record<string, TimelineKeyframes>;
  * engine.element(0, 'subtitle').show();
  *
  * @see Lumina.element
+ * @see Lumina.elementInCurrent
  * @see Lumina.elements
  * @see ElementState
  * @see AnimateOptions
@@ -515,6 +527,10 @@ interface SlideBase {
     backgroundOpacity?: number;
     /** Optional custom CSS class for the slide content container. */
     class?: string;
+    /** Optional title used by exportState and speaker notes when the slide type has no required title. */
+    title?: string;
+    /** Declarative reveal options. When present, engine runs revealInSequence on ready (slide 0) and on slideChange. */
+    reveal?: RevealInSequenceOptions;
 }
 
 /**
@@ -852,6 +868,12 @@ export interface DeckMeta {
      * defaultVisible: false = start all elements hidden; override per-id via initialElementState.
      */
     elementControl?: { defaultVisible?: boolean };
+    /** Default reveal options for all slides. Overridden by slide.reveal. */
+    reveal?: RevealInSequenceOptions;
+    /** Motion definitions (id -> { from, to, ease?, duration? }). Used when reveal.motion or animate({ motion: id }). */
+    motions?: Record<string, MotionDef>;
+    /** Full or partial theme overrides (e.g. from theme-custom-example.json). */
+    themeConfig?: ThemeConfig | object;
     [key: string]: any;
 }
 
@@ -1408,7 +1430,7 @@ export interface LuminaOptions {
     selector?: string;
     /** Whether to loop back to the start after the last slide. */
     loop?: boolean;
-    /** Master switch for slide-by-slide navigation. When false, the on-screen prev/next buttons are disabled and keyboard/touch do nothing. When true, keyboard and touch can be toggled via `keyboard` and `touch`; the nav buttons are shown/hidden with `ui.showControls`. Default: true. */
+    /** Master switch for slide-by-slide navigation. When false, the on-screen prev/next arrow buttons are hidden and keyboard/touch do nothing. When true, keyboard and touch can be toggled via `keyboard` and `touch`; the nav buttons are shown/hidden with `ui.showControls`. Default: true. */
     navigation?: boolean;
     /** Enable or disable keyboard shortcuts for next/prev. Only has effect when `navigation` is true. Default: true. */
     keyboard?: boolean;
@@ -1467,7 +1489,7 @@ export type LuminaEventType =
 export interface SlideChangePayload {
     index: number;
     previousIndex: number;
-    slide: BaseSlideData;
+    slide: Readonly<BaseSlideData>;
 }
 
 /**

package/src/index.ts

@@ -10,7 +10,7 @@
  * **Deck:** `{ meta: { title, initialElementState?, elementControl?, effects? }, slides: [...] }`
  * Slide types: statement, features, half, timeline, steps, flex, chart, diagram, custom, video.
  *
- * **Element control:** `engine.element(id)` or `engine.element(slideIndex, path)` → ElementController:
+ * **Element control:** `engine.element(id)`, `engine.element(slideIndex, path)`, or `engine.elementInCurrent(path)` → ElementController:
  * `.show()`, `.hide()`, `.toggle()`, `.opacity(n)`, `.transform(s)`, `.animate({ preset?, from?, to?, duration?, ease? })`.
  * Presets: fadeUp, fadeIn, scaleIn, slideLeft, slideRight, zoomIn, blurIn, spring, drop, fadeOut. `to` optional when using preset.
  * Ids: `engine.elements(slideIndex)` or `s{N}-{path}` (e.g. s0-tag, s1-features-0). `meta.initialElementState`:
@@ -30,7 +30,7 @@
  *
  * **Events:** `engine.on("ready"|"slideChange"|"action"|"error"|"patch"|"destroy"|"navigate"|"themeChange"|"speakerNotesOpen"|"speakerNotesClose"|"timelineSeek"|"timelineComplete"|"revealStart"|"revealComplete"|"revealElement", handler)`. `engine.emitError(err)` to forward errors.
  * **State for LLM:** `engine.exportState()` → `{ currentSlide, narrative, history }`.
- * **Key-value store:** `engine.data.get(key)`, `engine.data.set(key, value)`, `engine.data.has(key)`, `engine.data.delete(key)`, `engine.data.clear()`, `engine.data.keys()`. Persists across deck loads.
+ * **Key-value store:** `engine.data.get(key)`, `engine.data.set(key, value)`, `engine.data.has(key)`, `engine.data.delete(key)`, `engine.data.clear()`, `engine.data.keys()`. Persists across deck loads. **Template tags:** any slide string supports `{{key}}` resolved from engine.data; updates reactively when data changes. Helpers: `interpolateString`, `interpolateObject`.
  *
  * **Streaming:** `parsePartialJson(buffer)` then `engine.load(json)`. Or `createDebouncedLoader(engine.load, ms)`.
  * **Prompts:** `generateSystemPrompt({ mode, includeSchema, includeTheming })`, `generateThemePrompt()`.
@@ -146,6 +146,9 @@ export {
   type PresetDef,
 } from './animation';
 
+// Template interpolation: {{tag}} in slide strings resolved from engine.data
+export { interpolateString, interpolateObject } from './utils/templateInterpolation';
+
 // Element control: resolution and discovery (for engine.element(id), engine.element(slideIndex, path), engine.elements(slideIndex))
 export { elemId } from './core/elementId';
 export {

package/src/utils/templateInterpolation.ts

@@ -0,0 +1,52 @@
+/**
+ * Template interpolation for Lumina slide content.
+ *
+ * Replaces `{{key}}` placeholders in strings with values from a key-value store
+ * (e.g. engine.data / store.userData). When the store changes, any component
+ * that uses the interpolated result will reactively update.
+ *
+ * @example
+ * interpolateString('Hello {{name}}', { name: 'World' })  // 'Hello World'
+ * interpolateObject({ title: '{{product}}', subtitle: 'v{{version}}' }, { product: 'Lumina', version: 1 })
+ * // { title: 'Lumina', subtitle: 'v1' }
+ */
+
+/** Matches {{key}} or {{ key }}. Key: alphanumeric, underscore. */
+const TAG_RE = /\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/g;
+
+/**
+ * Replaces all {{key}} placeholders in a string with values from `data`.
+ * Missing keys render as empty string. Non-string values are coerced with String().
+ *
+ * @param str - Raw string possibly containing `{{key}}` tags.
+ * @param data - Key-value map (e.g. engine.data / store.state.userData).
+ * @returns Interpolated string.
+ */
+export function interpolateString(str: string, data: Record<string, unknown>): string {
+    if (typeof str !== 'string') return str;
+    return str.replace(TAG_RE, (_, key: string) => {
+        const v = data[key];
+        return v == null ? '' : String(v);
+    });
+}
+
+/**
+ * Recursively interpolates all string values in an object/array with `{{key}}`
+ * placeholders. Other types (number, boolean, null, etc.) are returned unchanged.
+ * Does not mutate the input; returns a new structure.
+ *
+ * @param obj - Object, array, or primitive (strings are interpolated).
+ * @param data - Key-value map (e.g. engine.data / store.state.userData).
+ * @returns New structure with all strings interpolated.
+ */
+export function interpolateObject<T>(obj: T, data: Record<string, unknown>): T {
+    if (obj == null) return obj;
+    if (typeof obj === 'string') return interpolateString(obj, data) as T;
+    if (Array.isArray(obj)) return obj.map((item) => interpolateObject(item, data)) as T;
+    if (typeof obj === 'object' && obj.constructor === Object) {
+        return Object.fromEntries(
+            Object.entries(obj).map(([k, v]) => [k, interpolateObject(v, data)])
+        ) as T;
+    }
+    return obj;
+}