lumina-slides 8.9.4 → 9.0.0

package/src/core/animationConfig.ts

@@ -0,0 +1,251 @@
+/**
+ * Animation config — centralized defaults and resolution for all animation timings, delays, and eases.
+ *
+ * @description
+ * Single source of truth for animation constants used by useTransition, Lumina.revealInSequence,
+ * elementController, LuminaDeck onLeave, and LuminaElement. Every timing and ease can be overridden via
+ * `options.animation`, `deck.meta.effects`, or `slide.meta.effects`. Precedence: slide overrides deck
+ * over options over ANIMATION_DEFAULTS.
+ *
+ * Legacy keys in meta.effects are mapped: `animationDuration`→durationIn, `animationDurationOut`→durationOut,
+ * `animationStagger`→stagger, `animationEase`→ease, `animationsEnabled`→enabled, `animationType`→type,
+ * `entranceReveal` (unchanged).
+ *
+ * @example
+ * // Resolve config for a slide (e.g. in a custom component or tooling)
+ * import { resolveTransitionConfig, ANIMATION_DEFAULTS } from 'lumina-slides';
+ * const cfg = resolveTransitionConfig(store, slide);
+ * console.log(cfg.durationIn, cfg.revealDelayMs, cfg.elementDuration);
+ *
+ * @example
+ * // Override via options when creating the engine
+ * new Lumina("#app", { animation: { durationIn: 1.2, revealDelayMs: 500, elementDuration: 0.6 } });
+ *
+ * @example
+ * // Override via deck or slide meta (in JSON)
+ * { "meta": { "effects": { "animationDuration": 1, "revealDelayMs": 400 } }, "slides": [...] }
+ *
+ * @module animationConfig
+ * @see Lumina
+ * @see LuminaAnimationOptions
+ * @see IMPLEMENTATION.md Animation options section
+ */
+
+import type { LuminaStore } from './store';
+import type { BaseSlideData } from './types';
+
+// ---------------------------------------------------------------------------
+// DEFAULTS — Single source of truth for all animation constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Default values for every animation setting. All keys are guaranteed to exist.
+ * Override via `options.animation`, `deck.meta.effects`, or `slide.meta.effects`; see resolveTransitionConfig.
+ *
+ * @constant
+ * @type {Readonly<Record<string, string|number|boolean>>}
+ * @see resolveTransitionConfig
+ * @see LuminaAnimationOptions
+ */
+export const ANIMATION_DEFAULTS = {
+    // --- Global ---
+    enabled: true,
+    type: 'fade' as const,
+    durationIn: 0.8,
+    durationOut: 0.5,
+    stagger: 0.1,
+    ease: 'power3.out',
+    entranceReveal: false,
+
+    // --- useTransition: entrance (by element type) ---
+    /** Multiplier for image reveal duration (durationIn * this). */
+    imageDurationMultiplier: 1.5,
+    imageEase: 'expo.out',
+    /** Stagger between character spans in split text. */
+    characterStagger: 0.015,
+    characterDurationFactor: 0.8,
+    characterEase: 'back.out(2)',
+    /** Stagger between .reveal-child elements. */
+    childRevealStagger: 0.05,
+    childRevealDurationFactor: 0.6,
+    childRevealStart: 0.2,
+    childRevealEase: 'power2.out',
+    /** Duration for standard (non-elastic) when durationIn not set. */
+    durationInStandard: 0.7,
+    /** Duration for elastic-up type. */
+    durationInElastic: 1.2,
+    easeElastic: 'elastic.out(1, 0.5)',
+    easeSpring: 'back.out(1.5)',
+
+    // --- useTransition: exit ---
+    easeOut: 'power2.in',
+    exitCharStagger: 0.005,
+    exitStaggerFactor: 0.5,
+    exitImageDurationFactor: 1.2,
+    exitChildDurationFactor: 0.8,
+
+    // --- Lumina.revealInSequence ---
+    revealDelayMs: 400,
+    revealDuration: 0.45,
+    revealEase: 'power2.out',
+
+    // --- elementController.animate ---
+    elementDuration: 0.5,
+    elementEase: 'power2.out',
+
+    // --- LuminaDeck onLeave (uses durationOut, easeOut) ---
+    // (no extra keys; durationOut, easeOut above)
+
+    // --- LuminaElement opacity transition (CSS fallback) ---
+    elementOpacityTransition: '0.35s ease-out',
+} as const;
+
+/**
+ * Fully resolved animation config. Every field is defined (no undefined). Produced by resolveTransitionConfig.
+ * Used internally by useTransition, Lumina.revealInSequence, elementController, LuminaDeck onLeave.
+ *
+ * @typedef {Object} ResolvedTransitionConfig
+ * @property {boolean} enabled - Global animations on/off.
+ * @property {string} type - 'fade'|'slide'|'zoom'|'cascade'|'blur'|'elastic-up'|'spring'|etc.
+ * @property {number} durationIn - Entry animation duration (s). Default 0.8.
+ * @property {number} durationOut - Exit animation duration (s). Default 0.5.
+ * @property {number} stagger - Delay between staggered elements (s). Default 0.1.
+ * @property {string} ease - GSAP ease (e.g. 'power3.out').
+ * @property {boolean} entranceReveal - If true, run GSAP reveal on .reveal-* when entering.
+ * @property {number} imageDurationMultiplier - Image duration = durationIn * this. Default 1.5.
+ * @property {string} imageEase - Image reveal ease. Default 'expo.out'.
+ * @property {number} characterStagger - Stagger between split-text chars (s). Default 0.015.
+ * @property {number} characterDurationFactor - Character duration factor. Default 0.8.
+ * @property {string} characterEase - Character ease. Default 'back.out(2)'.
+ * @property {number} childRevealStagger - Stagger between .reveal-child (s). Default 0.05.
+ * @property {number} childRevealDurationFactor - Child duration factor. Default 0.6.
+ * @property {number} childRevealStart - Timeline start for child reveal. Default 0.2.
+ * @property {string} childRevealEase - Child reveal ease. Default 'power2.out'.
+ * @property {number} durationInStandard - Fallback when type is not elastic. Default 0.7.
+ * @property {number} durationInElastic - Duration for elastic-up. Default 1.2.
+ * @property {string} easeElastic - Ease for elastic-up. Default 'elastic.out(1, 0.5)'.
+ * @property {string} easeSpring - Ease for spring. Default 'back.out(1.5)'.
+ * @property {string} easeOut - Exit/leave ease. Default 'power2.in'.
+ * @property {number} exitCharStagger - Char stagger on exit. Default 0.005.
+ * @property {number} exitStaggerFactor - Exit element stagger = stagger * this. Default 0.5.
+ * @property {number} exitImageDurationFactor - Exit image duration factor. Default 1.2.
+ * @property {number} exitChildDurationFactor - Exit child duration factor. Default 0.8.
+ * @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} 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'.
+ */
+export type ResolvedTransitionConfig = {
+    enabled: boolean;
+    type: string;
+    durationIn: number;
+    durationOut: number;
+    stagger: number;
+    ease: string;
+    entranceReveal: boolean;
+    imageDurationMultiplier: number;
+    imageEase: string;
+    characterStagger: number;
+    characterDurationFactor: number;
+    characterEase: string;
+    childRevealStagger: number;
+    childRevealDurationFactor: number;
+    childRevealStart: number;
+    childRevealEase: string;
+    durationInStandard: number;
+    durationInElastic: number;
+    easeElastic: string;
+    easeSpring: string;
+    easeOut: string;
+    exitCharStagger: number;
+    exitStaggerFactor: number;
+    exitImageDurationFactor: number;
+    exitChildDurationFactor: number;
+    revealDelayMs: number;
+    revealDuration: number;
+    revealEase: string;
+    elementDuration: number;
+    elementEase: string;
+    elementOpacityTransition: string;
+};
+
+const LEGACY_MAP: Record<string, keyof ResolvedTransitionConfig> = {
+    animationsEnabled: 'enabled',
+    animationType: 'type',
+    animationDuration: 'durationIn',
+    animationDurationOut: 'durationOut',
+    animationStagger: 'stagger',
+    animationEase: 'ease',
+    entranceReveal: 'entranceReveal',
+};
+
+function mapLegacy(src: Record<string, unknown> | null | undefined): Partial<ResolvedTransitionConfig> {
+    if (!src || typeof src !== 'object') return {};
+    const out: Partial<ResolvedTransitionConfig> = {};
+    for (const [k, v] of Object.entries(src)) {
+        if (v === undefined) continue;
+        const canon = LEGACY_MAP[k] ?? (k as keyof ResolvedTransitionConfig);
+        if (Object.prototype.hasOwnProperty.call(ANIMATION_DEFAULTS, canon)) {
+            (out as Record<string, unknown>)[canon] = v;
+        }
+    }
+    return out;
+}
+
+function pickCanonical(src: Record<string, unknown> | null | undefined): Partial<ResolvedTransitionConfig> {
+    if (!src || typeof src !== 'object') return {};
+    const out: Partial<ResolvedTransitionConfig> = {};
+    const keys = Object.keys(ANIMATION_DEFAULTS) as (keyof ResolvedTransitionConfig)[];
+    for (const k of keys) {
+        if (Object.prototype.hasOwnProperty.call(src, k) && (src as Record<string, unknown>)[k] !== undefined) {
+            (out as Record<string, unknown>)[k] = (src as Record<string, unknown>)[k];
+        }
+    }
+    return out;
+}
+
+/**
+ * Resolves the full animation config by merging, in order (later overrides earlier):
+ * 1. ANIMATION_DEFAULTS
+ * 2. options.animation (with legacy key mapping)
+ * 3. deck.meta.effects (with legacy key mapping)
+ * 4. slide.meta.effects (with legacy key mapping)
+ *
+ * Use when you need a single config object for transitions, revealInSequence, element().animate(),
+ * or deck leave. When `store` or `slideData` is null/undefined, only the layers you have are merged.
+ *
+ * @param store - Lumina store (state.options, state.deck). Can be null if building config without engine.
+ * @param slideData - Optional slide for slide-level overrides (slide.meta.effects). Omit for deck-level only.
+ * @returns Resolved config with every key defined (no undefined). Safe to pass to GSAP or timing logic.
+ *
+ * @example
+ * const cfg = resolveTransitionConfig(store, currentSlide);
+ * gsap.to(el, { duration: cfg.durationIn, ease: cfg.ease });
+ *
+ * @example
+ * // Without slide (deck + options only)
+ * const cfg = resolveTransitionConfig(store, undefined);
+ *
+ * @see ANIMATION_DEFAULTS
+ * @see ResolvedTransitionConfig
+ * @see LuminaAnimationOptions
+ */
+export function resolveTransitionConfig(store: LuminaStore | null | undefined, slideData?: BaseSlideData | null): ResolvedTransitionConfig {
+    const base = { ...ANIMATION_DEFAULTS } as unknown as Record<string, unknown>;
+
+    const opt = (store?.state?.options?.animation || {}) as Record<string, unknown>;
+    const deckEff = (store?.state?.deck?.meta?.effects || {}) as Record<string, unknown>;
+    const slideEff = (slideData?.meta?.effects || {}) as Record<string, unknown>;
+
+    const apply = (raw: Record<string, unknown>) => {
+        Object.assign(base, mapLegacy(raw), pickCanonical(raw));
+    };
+
+    apply(opt);
+    apply(deckEff);
+    apply(slideEff);
+
+    return base as unknown as ResolvedTransitionConfig;
+}

package/src/core/compression.ts

@@ -0,0 +1,34 @@
+
+/**
+ * Feature: Token Optimization (Compression)
+ * A dictionary of common values mapped to short codes.
+ * This can be provided to the LLM to reduce output size.
+ */
+
+export const COMPRESSION_DICT = {
+    // Icons
+    'i:s': 'star',
+    'i:u': 'users',
+    'i:c': 'check',
+    'i:a': 'arrow-right',
+
+    // Colors (Tailwind standard approximation)
+    'c:p': '#6366f1', // Primary (Indigo)
+    'c:s': '#10b981', // Success (Emerald)
+    'c:d': '#ef4444', // Danger (Red)
+
+    // Variants
+    'v:g': 'gradient',
+    'v:o': 'outlined',
+    'v:s': 'soft',
+};
+
+/**
+ * Expands a compressed value if it exists in the dictionary.
+ */
+export function expandValue(val: string): string {
+    if (val in COMPRESSION_DICT) {
+        return (COMPRESSION_DICT as any)[val];
+    }
+    return val;
+}

package/src/core/elementController.ts

@@ -0,0 +1,170 @@
+/**
+ * Element controller factory. Creates the fluent API returned by `engine.element(id)` and
+ * `engine.element(slideIndex, path)`. Use the public API; this module is for implementation.
+ *
+ * @module elementController
+ * @see Lumina.element
+ * @see ElementController
+ * @see AnimateOptions
+ */
+import gsap from 'gsap';
+import type { LuminaStore } from './store';
+import { resolveTransitionConfig } from './animationConfig';
+import { resolveAnimationFromInput } from '../animation';
+import type { AnimateOptions, ElementController as IElementController, ElementState, TimelineKeyframes, TimelineKeyframeState } from './types';
+
+/**
+ * Minimal engine interface for resolving a DOM node by element id. Implemented by {@link Lumina}.
+ */
+export interface LuminaEngineLike {
+  getElementById(id: string): HTMLElement | null;
+}
+
+/**
+ * Creates an {@link ElementController} for the given element id. Used internally by
+ * `engine.element(id)` and `engine.element(slideIndex, path)`. Prefer the public API.
+ *
+ * @param store - Lumina store (setElementState, state.elementState).
+ * @param engine - Engine with getElementById (for animate).
+ * @param id - Resolved element id (from resolveId or user).
+ * @returns Fluent controller for show/hide/opacity/transform/css/class/animate.
+ * @internal
+ */
+export function createElementController(
+  store: LuminaStore,
+  engine: LuminaEngineLike,
+  id: string
+): IElementController {
+  function set(patch: Partial<ElementState>) {
+    store.setElementState(id, patch);
+  }
+
+  function getClass(): string {
+    return (store.state.elementState[id]?.class as string) || '';
+  }
+
+  const ctrl: IElementController = {
+    show() {
+      set({ visible: true, opacity: 1 });
+      const dom = engine.getElementById(id);
+      const reveal = dom?.closest('.reveal-zoom, .reveal-up, .reveal-card, .reveal-left, .reveal-right');
+      if (reveal) gsap.set(reveal, { opacity: 1 });
+      return ctrl;
+    },
+    hide() {
+      set({ visible: false });
+      return ctrl;
+    },
+    toggle(force?: boolean) {
+      const cur = store.state.elementState[id]?.visible !== false;
+      set({ visible: force !== undefined ? force : !cur });
+      return ctrl;
+    },
+    opacity(value: number) {
+      set({ opacity: value });
+      return ctrl;
+    },
+    transform(value: string) {
+      set({ transform: value });
+      return ctrl;
+    },
+    css(style: Record<string, string | number>) {
+      set({ style });
+      return ctrl;
+    },
+    addClass(className: string) {
+      const cur = getClass();
+      const next = (cur + ' ' + className).trim();
+      set({ class: next });
+      return ctrl;
+    },
+    removeClass(className: string) {
+      const cur = getClass();
+      const next = cur
+        .split(/\s+/)
+        .filter((c) => c && c !== className)
+        .join(' ');
+      set({ class: next });
+      return ctrl;
+    },
+    animate(options: AnimateOptions) {
+      runAnimate(options);
+      return ctrl;
+    },
+    animateAsync(options: AnimateOptions): Promise<void> {
+      return new Promise((resolve) => {
+        runAnimate(options, () => {
+          options.onComplete?.();
+          resolve();
+        });
+      });
+    },
+    animateToProgress(progress: number, keyframes: TimelineKeyframes) {
+      const keys = Object.keys(keyframes)
+        .map((k) => parseFloat(k))
+        .filter((n) => !Number.isNaN(n))
+        .sort((a, b) => a - b);
+      if (keys.length === 0) return ctrl;
+      const k0 = keys[0];
+      const k1 = keys[keys.length - 1];
+      let state: TimelineKeyframeState;
+      if (progress <= k0) {
+        state = keyframes[String(k0)] ?? {};
+      } else if (progress >= k1) {
+        state = keyframes[String(k1)] ?? {};
+      } else {
+        let i = 0;
+        while (i + 1 < keys.length && keys[i + 1] <= progress) i++;
+        const a = keys[i];
+        const b = keys[i + 1];
+        const va = keyframes[String(a)] ?? {};
+        const vb = keyframes[String(b)] ?? {};
+        const t = (progress - a) / (b - a);
+        state = {};
+        for (const prop of ['opacity', 'x', 'y', 'scale', 'rotate'] as const) {
+          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 vb.visible === 'boolean') state.visible = vb.visible;
+        else if (typeof va.visible === 'boolean') state.visible = va.visible;
+      }
+      const opacity = state.opacity !== undefined ? state.opacity : 1;
+      const parts: string[] = [];
+      if (state.x !== undefined || state.y !== undefined) {
+        parts.push(`translate(${state.x ?? 0}px, ${state.y ?? 0}px)`);
+      }
+      if (state.scale !== undefined) {
+        parts.push(`scale(${state.scale})`);
+      }
+      if (state.rotate !== undefined) {
+        parts.push(`rotate(${state.rotate}deg)`);
+      }
+      const transform = parts.length ? parts.join(' ') : '';
+      const visible = state.visible !== undefined ? state.visible : opacity > 0;
+      set({ opacity, transform, visible });
+      return ctrl;
+    }
+  };
+
+  function runAnimate(opts: AnimateOptions, onCompleteOverride?: () => void) {
+    const el = engine.getElementById(id);
+    if (!el) return;
+    const cfg = resolveTransitionConfig(store, undefined);
+    const { from, to, ease, duration } = resolveAnimationFromInput(opts, {
+      duration: cfg.elementDuration,
+      ease: cfg.elementEase,
+    });
+    const cb = onCompleteOverride ?? opts.onComplete;
+    const toVars = { ...to, duration, ease, overwrite: true, onComplete: cb } as gsap.TweenVars;
+    if (from && Object.keys(from).length) {
+      gsap.fromTo(el, from as gsap.TweenVars, toVars);
+    } else {
+      gsap.to(el, toVars);
+    }
+  }
+
+  return ctrl;
+}

package/src/core/elementId.ts

@@ -0,0 +1,27 @@
+/**
+ * Builds a stable, unique element id from slide index and a logical path. Used as fallback
+ * when the slide or child object does not define an explicit `id`. The format is
+ * `s{slideIndex}-{path0}-{path1}-...` (e.g. "s0-tag", "s1-features-2", "s2-elements-0-elements-1").
+ *
+ * Prefer resolveId when you have slide data (it respects explicit ids and slide.ids). Use
+ * elemId when constructing an id without the full slide (e.g. for initialElementState keys
+ * when you know the path convention).
+ *
+ * @param slideIndex - Zero-based slide index. If undefined, 0 is used.
+ * @param path - Rest args: property names and indices (e.g. 'tag'; 'features', 2; 'elements', 0, 'elements', 1).
+ * @returns Id string. Safe for data-lumina-id, engine.element(id), and meta.initialElementState.
+ *
+ * @example
+ * elemId(0, 'tag')                  // "s0-tag"
+ * elemId(1, 'features', 2)          // "s1-features-2"
+ * elemId(2, 'elements', 0, 'elements', 1)  // "s2-elements-0-elements-1"
+ *
+ * @see resolveId
+ * @see getElementIds
+ * @see DeckMeta.initialElementState
+ */
+export function elemId(slideIndex: number | undefined, ...path: (string | number)[]): string {
+  const s = slideIndex ?? 0;
+  if (path.length === 0) return `s${s}`;
+  return `s${s}-${path.map(String).join('-')}`;
+}

package/src/core/elementResolver.ts

@@ -0,0 +1,207 @@
+/**
+ * ELEMENT RESOLVER
+ *
+ * Central, schema-aware logic to:
+ * - Resolve a logical path (e.g. ["elements", 0, "elements", 1]) to a stable element id.
+ * - Enumerate all element paths for a slide (for engine.elements(slideIndex) and path-based element()).
+ *
+ * Supports: explicit `id` on objects, `ids` on the slide for named fields, and fallback to
+ * elemId(slideIndex, ...path). Works for all built-in layouts; extend PATH_GENERATORS for new types.
+ *
+ * @see resolveId
+ * @see getElementPaths
+ * @see getElementIds
+ * @see Lumina.element
+ * @see Lumina.elements
+ */
+
+import { getByPath } from '../utils/deep';
+import { elemId } from './elementId';
+import type { BaseSlideData } from './types';
+
+/**
+ * Logical path into slide data: property names and array indices. Used by resolveId and
+ * engine.element(slideIndex, path). String form: "tag", "features.0", "elements.0.elements.1".
+ */
+export type ElementPath = (string | number)[];
+
+/**
+ * Converts an ElementPath to a dot-notation key for getByPath (e.g. ["features", 0] → "features.0").
+ */
+export function pathToKey(path: ElementPath): string {
+  return path.join('.');
+}
+
+/**
+ * Reads the value at `path` in the slide object. Uses dot-notation traversal; indices are
+ * stringified (e.g. "features.0").
+ *
+ * @param slide - Slide data (BaseSlideData). Can be any object for generic traversal.
+ * @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 {
+  if (!slide || !path.length) return undefined;
+  return getByPath(slide, pathToKey(path));
+}
+
+/**
+ * Parses a path from string or array. Use for engine.element(slideIndex, path) when
+ * path is a string like "features.0" or "elements.0.elements.1".
+ *
+ * Rules: split by "."; numeric segments become numbers, rest stay strings.
+ *
+ * @param input - String ("features.0") or already-parsed ElementPath.
+ * @returns Normalized ElementPath. Empty array if input is not string or array.
+ *
+ * @example
+ * parsePath("tag")           // ['tag']
+ * parsePath("features.0")    // ['features', 0]
+ * parsePath("elements.0.elements.1")  // ['elements', 0, 'elements', 1]
+ */
+export function parsePath(input: string | ElementPath): ElementPath {
+  if (Array.isArray(input)) return input;
+  if (typeof input !== 'string') return [];
+  return input.split('.').map((p) => (/^\d+$/.test(p) ? parseInt(p, 10) : p));
+}
+
+/**
+ * Resolves the stable element id for a (slide, slideIndex, path). This id is used in
+ * data-lumina-id, engine.element(id), and meta.initialElementState. Resolution order:
+ * 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").
+ *
+ * @param slide - The slide data.
+ * @param slideIndex - Zero-based slide index (for elemId fallback).
+ * @param path - Logical path (from getElementPaths or parsePath).
+ * @returns Element id string. Use in engine.element(id) or meta.initialElementState.
+ *
+ * @see getElementPaths
+ * @see getElementIds
+ * @see elemId
+ */
+export function resolveId(
+  slide: BaseSlideData,
+  slideIndex: number,
+  path: ElementPath
+): string {
+  const slideAny = slide as { id?: string; ids?: Record<string, string> };
+  if (path.length === 0 || (path.length === 1 && path[0] === 'slide')) {
+    return slideAny?.id || elemId(slideIndex, 'slide');
+  }
+  const obj = getValueAt(slide, path);
+  if (obj != null && typeof obj === 'object' && typeof (obj as { id?: string }).id === 'string') {
+    return (obj as { id: string }).id;
+  }
+  const key = pathToKey(path);
+  if (key && slideAny?.ids?.[key]) {
+    return slideAny.ids[key];
+  }
+  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[];
+
+/** Map of slide.type → path generator. Extend to support new layouts. */
+const PATH_GENERATORS: Record<string, PathGenerator> = {
+  statement: () => [['tag'], ['title'], ['subtitle']],
+  features: (s) => {
+    const arr = getValueAt(s, ['features']);
+    const list = Array.isArray(arr) ? arr : [];
+    return [['header'], ...list.map((_: unknown, i: number) => ['features', i] as ElementPath)];
+  },
+  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)];
+  },
+  steps: (s) => {
+    const arr = getValueAt(s, ['steps']);
+    const list = Array.isArray(arr) ? arr : [];
+    return [['header'], ...list.map((_: unknown, i: number) => ['steps', i] as ElementPath)];
+  },
+  flex: (s) => {
+    const paths: ElementPath[] = [];
+    const els = getValueAt(s, ['elements']);
+    const list = Array.isArray(els) ? els : [];
+    list.forEach((e: unknown, i: number) => {
+      paths.push(['elements', i]);
+      const ob = e && typeof e === 'object' ? (e as { type?: string; elements?: unknown[] }) : null;
+      if (ob?.type === 'content' && Array.isArray(ob.elements)) {
+        ob.elements.forEach((_: unknown, j: number) => paths.push(['elements', i, 'elements', j]));
+      }
+    });
+    return paths;
+  },
+  chart: () => [['title'], ['subtitle'], ['chart']],
+  diagram: (s) => {
+    const p: ElementPath[] = [];
+    const nodes = getValueAt(s, ['nodes']);
+    const edges = getValueAt(s, ['edges']);
+    (Array.isArray(nodes) ? nodes : []).forEach((_: unknown, i: number) => p.push(['nodes', i]));
+    (Array.isArray(edges) ? edges : []).forEach((_: unknown, i: number) => p.push(['edges', i]));
+    return p;
+  },
+  custom: () => [],
+  video: () => [['video'], ['title']],
+  free: (s) => {
+    const arr = getValueAt(s, ['elements']);
+    const list = Array.isArray(arr) ? arr : [];
+    return list.map((_: unknown, i: number) => ['elements', i] as ElementPath);
+  },
+};
+
+/**
+ * Registers or overrides the path generator for a slide type. Use to support custom layouts
+ * or to change how elements are enumerated for engine.elements(slideIndex) and path-based
+ * engine.element(slideIndex, path).
+ *
+ * @param type - Slide type (e.g. 'statement', 'features', or a custom type like 'diagram-v2').
+ * @param fn - Generator that returns ElementPath[] for a slide of that type.
+ *
+ * @example
+ * import { registerElementPaths, getElementPaths } from 'lumina-slides';
+ * registerElementPaths('my-layout', (slide) => [['title'], ['blocks', 0], ['blocks', 1]]);
+ */
+export function registerElementPaths(type: string, fn: PathGenerator): void {
+  PATH_GENERATORS[type] = fn;
+}
+
+/**
+ * Returns all logical element paths for a slide. Used by {@link getElementIds} and thus
+ * engine.elements(slideIndex). Always includes the slide root ['slide']; the rest come from
+ * PATH_GENERATORS for the slide's type. Add new layout types by extending PATH_GENERATORS.
+ *
+ * @param slide - The slide data (must have `type`).
+ * @returns Array of paths, e.g. [['slide'], ['tag'], ['title'], ['subtitle']] for statement.
+ *
+ * @see getElementIds
+ * @see resolveId
+ * @see Lumina.elements
+ */
+export function getElementPaths(slide: BaseSlideData): ElementPath[] {
+  const t = (slide?.type as string) || 'unknown';
+  const gen = PATH_GENERATORS[t] || (() => []);
+  return [['slide'], ...gen(slide)];
+}
+
+/**
+ * Returns all element ids for a slide. Used by engine.elements(slideIndex) and useful to
+ * know which ids can be passed to engine.element(id) or to meta.initialElementState.
+ *
+ * @param slide - The slide data.
+ * @param slideIndex - Zero-based slide index (for resolveId).
+ * @returns Array of id strings, e.g. ["s0-slide","s0-tag","s0-title","s0-subtitle"].
+ *
+ * @see getElementPaths
+ * @see resolveId
+ * @see Lumina.elements
+ * @see DeckMeta.initialElementState
+ */
+export function getElementIds(slide: BaseSlideData, slideIndex: number): string[] {
+  return getElementPaths(slide).map((p) => resolveId(slide, slideIndex, p));
+}