lumina-slides 9.0.2 → 9.0.4

package/src/core/Lumina.ts

@@ -433,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);
     }
 
     /**

package/src/core/elementResolver.ts

@@ -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).
@@ -99,6 +100,11 @@ 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);
 }
 
@@ -107,22 +113,38 @@ export type PathGenerator = (slide: Readonly<BaseSlideData>) => ElementPath[];
 
 /** Map of slide.type → path generator. Extend to support new layouts. */
 const PATH_GENERATORS: Record<string, PathGenerator> = {
-  statement: () => [['tag'], ['title'], ['subtitle']],
+  statement: (s) => {
+    const paths: ElementPath[] = [['title']];
+    if (getValueAt(s, ['tag'])) paths.unshift(['tag']);
+    if (getValueAt(s, ['subtitle'])) paths.push(['subtitle']);
+    return paths;
+  },
   features: (s) => {
     const arr = getValueAt(s, ['features']);
     const list = Array.isArray(arr) ? arr : [];
-    return [['header'], ...list.map((_: unknown, i: number) => ['features', i] as ElementPath)];
+    const paths: ElementPath[] = [['header'], ['title']];
+    if (getValueAt(s, ['description'])) paths.push(['description']);
+    return [...paths, ...list.map((_: unknown, i: number) => ['features', i] as ElementPath)];
+  },
+  half: (s) => {
+    const paths: ElementPath[] = [['media'], ['title'], ['paragraphs']];
+    if (getValueAt(s, ['tag'])) paths.splice(1, 0, ['tag']); // after media, before title
+    if (getValueAt(s, ['cta'])) paths.push(['cta']);
+    return paths;
   },
-  half: () => [['media'], ['tag'], ['title'], ['paragraphs'], ['cta']],
   timeline: (s) => {
     const arr = getValueAt(s, ['timeline']);
     const list = Array.isArray(arr) ? arr : [];
-    return [['title'], ['subtitle'], ...list.map((_: unknown, i: number) => ['timeline', i] as ElementPath)];
+    const paths: ElementPath[] = [['title']];
+    if (getValueAt(s, ['subtitle'])) paths.push(['subtitle']);
+    return [...paths, ...list.map((_: unknown, i: number) => ['timeline', i] as ElementPath)];
   },
   steps: (s) => {
     const arr = getValueAt(s, ['steps']);
     const list = Array.isArray(arr) ? arr : [];
-    return [['header'], ...list.map((_: unknown, i: number) => ['steps', i] as ElementPath)];
+    const paths: ElementPath[] = [['header'], ['title']];
+    if (getValueAt(s, ['subtitle'])) paths.push(['subtitle']);
+    return [...paths, ...list.map((_: unknown, i: number) => ['steps', i] as ElementPath)];
   },
   flex: (s) => {
     const paths: ElementPath[] = [];
@@ -137,7 +159,13 @@ const PATH_GENERATORS: Record<string, PathGenerator> = {
     });
     return paths;
   },
-  chart: () => [['title'], ['subtitle'], ['chart']],
+  chart: (s) => {
+    const paths: ElementPath[] = [];
+    if (getValueAt(s, ['title'])) paths.push(['title']);
+    if (getValueAt(s, ['subtitle'])) paths.push(['subtitle']);
+    paths.push(['chart']);
+    return paths;
+  },
   diagram: (s) => {
     const p: ElementPath[] = [];
     const nodes = getValueAt(s, ['nodes']);
@@ -147,7 +175,11 @@ const PATH_GENERATORS: Record<string, PathGenerator> = {
     return p;
   },
   custom: () => [],
-  video: () => [['video'], ['title']],
+  video: (s) => {
+    const paths: ElementPath[] = [['video']];
+    if (getValueAt(s, ['title'])) paths.push(['title']);
+    return paths;
+  },
   free: (s) => {
     const arr = getValueAt(s, ['elements']);
     const list = Array.isArray(arr) ? arr : [];

package/src/core/types.ts

@@ -448,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.
@@ -462,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

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`: