lumina-slides 9.0.2 → 9.0.3

package/src/components/site/SiteDocs.vue

@@ -1,8 +1,8 @@
 <template>
     <div class="min-h-screen pt-32 px-6 md:px-12 max-w-8xl mx-auto flex flex-col md:flex-row gap-16">
         <!-- Sidebar Navigation -->
-        <aside class="w-full md:w-64 flex-shrink-0 hidden md:block">
-            <div class="sticky top-32 space-y-10">
+        <aside class="w-full md:w-64 flex-shrink-0 block sticky top-32 self-start max-h-[calc(100vh-10rem)] overflow-y-auto">
+            <div class="space-y-10 py-1">
                 <div v-for="(group, i) in navigation" :key="i">
                     <!-- Group Title -->
                     <h3 class="text-xs font-bold uppercase tracking-widest text-white/30 mb-4 pl-3">
@@ -12,14 +12,14 @@
                     <!-- Links -->
                     <ul class="space-y-1 relative border-l border-white/5">
                         <li v-for="item in group.items" :key="item.id">
-                            <button @click="activeSection = item.id; scrollToTop()" :class="[
+                            <a v-if="group.title === 'Layouts'" :href="'#' + item.id" @click.prevent="goToLayout(item.id)" :class="[
+                                'block group w-full text-left px-4 py-2 text-sm transition-all duration-300 border-l-2 -ml-[1px]',
+                                activeSection === item.id ? 'border-blue-500 text-white font-medium bg-blue-500/5' : 'border-transparent text-white/50 hover:text-white hover:border-white/20'
+                            ]">{{ item.label }}</a>
+                            <button v-else @click="activeSection = item.id; scrollToTop()" :class="[
                                 'group w-full text-left px-4 py-2 text-sm transition-all duration-300 border-l-2 -ml-[1px]',
-                                activeSection === item.id
-                                    ? 'border-blue-500 text-white font-medium bg-blue-500/5'
-                                    : 'border-transparent text-white/50 hover:text-white hover:border-white/20'
-                            ]">
-                                {{ item.label }}
-                            </button>
+                                activeSection === item.id ? 'border-blue-500 text-white font-medium bg-blue-500/5' : 'border-transparent text-white/50 hover:text-white hover:border-white/20'
+                            ]">{{ item.label }}</button>
                         </li>
                     </ul>
                 </div>
@@ -28,11 +28,10 @@
 
         <!-- Main Content Area -->
         <main class="flex-1 w-full min-w-0 pb-32">
-            <Transition name="fade" mode="out-in">
-                <div :key="activeSection" class="doc-content max-w-6xl">
+            <div class="doc-content max-w-6xl">
 
                     <!-- MEDIA & VIDEO -->
-                    <div v-if="activeSection === 'media'">
+                    <div v-if="activeSection === 'media'" id="media">
                         <h1>Media & Video</h1>
                         <p class="lead">Lumina supports video backgrounds on any slide, and video elements in Half and Flex layouts.</p>
 
@@ -61,7 +60,7 @@
                     </div>
 
                     <!-- INTRODUCTION -->
-                    <div v-else-if="activeSection === 'intro'">
+                    <div v-else-if="activeSection === 'intro'" id="intro">
                         <h1>Introduction</h1>
                         <p class="lead text-2xl text-white font-light">
                             Lumina is a high-performance, Universal Presentation Engine.
@@ -102,7 +101,7 @@
                     </div>
 
                     <!-- INSTALLATION -->
-                    <div v-else-if="activeSection === 'install'">
+                    <div v-else-if="activeSection === 'install'" id="install">
                         <h1>Installation</h1>
                         <p>Lumina is available as a Universal NPM package. It works in any JavaScript environment
                             (Vanilla, React, Vue, Svelte, etc.). Vue and GSAP are bundled; Chart.js is an optional peer only if you use <code>type: "chart"</code> slides.</p>
@@ -137,7 +136,7 @@
                     </div>
 
                     <!-- SETUP -->
-                    <div v-else-if="activeSection === 'setup'">
+                    <div v-else-if="activeSection === 'setup'" id="setup">
                         <h1>Quick Start</h1>
                         <p>Import the stylesheet and initialize the engine in your main entry file.
                         </p>
@@ -158,7 +157,7 @@ engine.load(myDeckData);</code></pre>
                     </div>
 
                     <!-- DECK STRUCTURE -->
-                    <div v-else-if="activeSection === 'deck'">
+                    <div v-else-if="activeSection === 'deck'" id="deck">
                         <h1>Deck Structure</h1>
                         <p>A deck is a JSON object with <code>meta</code> and <code>slides</code>. Both are required.</p>
 
@@ -205,7 +204,7 @@ engine.load(myDeckData);</code></pre>
                     </div>
 
                     <!-- SLIDE LAYOUTS -->
-                    <div v-else-if="activeSection === 'slides'">
+                    <div v-else-if="activeSection === 'slides'" id="slides">
                         <h1>Slide Layouts</h1>
                         <p>Lumina includes responsive layouts for common scenarios. Each layout has a reference section with a full property table.</p>
 
@@ -335,7 +334,7 @@ engine.load(myDeckData);</code></pre>
 
 
                     <!-- SIZING / EMBEDDING -->
-                    <div v-else-if="activeSection === 'sizing'">
+                    <div v-else-if="activeSection === 'sizing'" id="sizing">
                         <h1>Embedding & Sizing</h1>
                         <p>By default, Lumina slides take up the full viewport height (<code>100vh</code>) to create an
                             immersive experience.</p>
@@ -364,7 +363,7 @@ engine.load(myDeckData);</code></pre>
                     </div>
 
                     <!-- CONFIGURATION -->
-                    <div v-else-if="activeSection === 'config'">
+                    <div v-else-if="activeSection === 'config'" id="config">
                         <h1>Configuration</h1>
                         <p>Pass options to <code>new Lumina(selector, options)</code>. All properties are optional.</p>
 
@@ -408,7 +407,7 @@ engine.load(myDeckData);</code></pre>
                     </div>
 
                     <!-- EVENTS -->
-                    <div v-else-if="activeSection === 'events'">
+                    <div v-else-if="activeSection === 'events'" id="events">
                         <h1>Events & API</h1>
                         <p>Subscribe with <code>engine.on(event, handler)</code>; unsubscribe with <code>engine.off(event, handler)</code> using the same function reference.</p>
 
@@ -443,7 +442,7 @@ engine.<span class="text-yellow-400">on</span>('navigate', ({ direction, toIndex
                     </div>
 
                     <!-- ELEMENT CONTROL -->
-                    <div v-else-if="activeSection === 'element-control'">
+                    <div v-else-if="activeSection === 'element-control'" id="element-control">
                         <h1>Element Control (Reveal on Demand)</h1>
                         <p class="lead">Start with elements hidden and reveal them in sequence: ideal for blank slides that
                             fill in as you speak, or for effects driven by <code>engine.element(id)</code>.</p>
@@ -570,7 +569,7 @@ engine.load(deck);</code></pre>
                     </div>
 
                     <!-- ANIMATIONS: revealInSequence, presets, stagger -->
-                    <div v-else-if="activeSection === 'animations'">
+                    <div v-else-if="activeSection === 'animations'" id="animations">
                         <h1>Animations</h1>
                         <p class="lead">Control entrances with <code>revealInSequence</code>, built-in presets, and stagger modes. Use with <code>meta.initialElementState</code> or <code>elementControl.defaultVisible: false</code> to start hidden.</p>
 
@@ -602,7 +601,7 @@ engine.load(deck);</code></pre>
                     </div>
 
                     <!-- TIMELINE (Remotion-style keyframes) -->
-                    <div v-else-if="activeSection === 'timeline-keyframes'">
+                    <div v-else-if="activeSection === 'timeline-keyframes'" id="timeline-keyframes">
                         <h1>Timeline (Remotion-style keyframes)</h1>
                         <p class="lead">Drive element state from a progress 0–1 with <code>slide.timelineTracks</code>. Use <code>engine.seekTo(progress)</code> to scrub or <code>engine.playTimeline(duration)</code> to play. Works with any layout; the <code>free</code> layout is for absolutely positioned storytelling.</p>
 
@@ -638,7 +637,7 @@ engine.load(deck);</code></pre>
                     </div>
 
                     <!-- THEMING -->
-                    <div v-else-if="activeSection === 'theming'">
+                    <div v-else-if="activeSection === 'theming'" id="theming">
                         <h1>Theming</h1>
                         <p class="lead">Customize colors, fonts, and visual style with built-in presets or create your
                             own theme.</p>
@@ -1403,7 +1402,7 @@ engine.load(myDeck);</code></pre>
                     </div>
 
                     <!-- SPEAKER NOTES -->
-                    <div v-else-if="activeSection === 'speaker-notes'">
+                    <div v-else-if="activeSection === 'speaker-notes'" id="speaker-notes">
                         <h1>Speaker Notes</h1>
                         <p class="lead">Open a separate presenter view with notes, timer, and bidirectional navigation
                             controls.</p>
@@ -1487,7 +1486,7 @@ engine.<span class="text-yellow-400">closeSpeakerNotes</span>();</code></pre>
 
 
                     <!-- AGENTS: INTRO -->
-                    <div v-else-if="activeSection === 'agents-intro'">
+                    <div v-else-if="activeSection === 'agents-intro'" id="agents-intro">
                         <h1>The Agent Protocol</h1>
                         <p class="lead">Lumina is the first presentation engine designed for <strong>Agentic
                                 AI</strong>.</p>
@@ -1533,7 +1532,7 @@ engine.<span class="text-yellow-400">closeSpeakerNotes</span>();</code></pre>
                     </div>
 
                     <!-- AGENTS: TOKENS -->
-                    <div v-else-if="activeSection === 'agents-tokens'">
+                    <div v-else-if="activeSection === 'agents-tokens'" id="agents-tokens">
                         <h1>Token Optimization</h1>
                         <p class="lead">Reduce output size with short property aliases. Less characters = faster
                             rendering and lower costs.</p>
@@ -1641,7 +1640,7 @@ engine.<span class="text-yellow-400">closeSpeakerNotes</span>();</code></pre>
                     </div>
 
                     <!-- AGENTS: STREAMING -->
-                    <div v-else-if="activeSection === 'agents-streaming'">
+                    <div v-else-if="activeSection === 'agents-streaming'" id="agents-streaming">
                         <h1>Streaming & Realtime</h1>
                         <p>Lumina enables a <strong>"Type & See"</strong> experience. Using our partial parser, you can
                             feed raw LLM streams directly into the engine.</p>
@@ -1689,12 +1688,11 @@ engine.<span class="text-yellow-400">closeSpeakerNotes</span>();</code></pre>
                     </div>
 
                     <!-- AGENTS: LAYOUT GALLERY -->
-                    <div v-else-if="activeSection === 'agents-layouts'">
+                    <div v-else-if="activeSection === 'agents-layouts'" id="agents-layouts">
                         <h1>Layout Gallery</h1>
                         <p>Lumina provides 5 core layouts optimized for different types of information. Click <strong><i
                                     class="fa-solid fa-play text-blue-400"></i> Visualize</strong> to load them into the
-                            <a @click.prevent="activeSection = 'agents-streaming'; scroll('streaming-demo-container')"
-                                href="#" class="text-blue-400 hover:underline">Streaming Demo</a>.
+                            <a href="#streaming-demo-container" @click.prevent="goToStreamingDemo" class="text-blue-400 hover:underline">Streaming Demo</a>.
                         </p>
 
                         <div class="space-y-12 mt-12">
@@ -1750,7 +1748,7 @@ engine.<span class="text-yellow-400">closeSpeakerNotes</span>();</code></pre>
                         </div>
                     </div>
 
-                    <div v-else-if="activeSection === 'agents-auto'">
+                    <div v-else-if="activeSection === 'agents-auto'" id="agents-auto">
                         <h1>Auto-Layouts</h1>
                         <p>Sometimes the Agent doesn't know which layout is best. Just use <code>type: 'auto'</code>.
                         </p>
@@ -1828,7 +1826,7 @@ engine.<span class="text-yellow-400">closeSpeakerNotes</span>();</code></pre>
                     </div>
 
                     <!-- AGENTS: STATE -->
-                    <div v-else-if="activeSection === 'agents-state'">
+                    <div v-else-if="activeSection === 'agents-state'" id="agents-state">
                         <h1>State & Feedback Loop</h1>
                         <p>Use <code>engine.exportState()</code> to get the current state for your LLM or agent. It returns a frozen object with <code>status</code>, <code>currentSlide</code> (<code>{ index, id, type, title }</code>), <code>narrative</code> (e.g. "User is on slide 3. Session: clicked 'Learn More' → next."), <code>engagementLevel</code> ("High" or "Low"), and <code>history</code> (recorded actions). Add this to your prompt for context-aware replies.</p>
                         <pre><code><span class="text-blue-400">const</span> state = engine.exportState();
@@ -1836,7 +1834,7 @@ engine.<span class="text-yellow-400">closeSpeakerNotes</span>();</code></pre>
                     </div>
 
                     <!-- TEMPLATE TAGS & engine.data -->
-                    <div v-else-if="activeSection === 'template-tags'">
+                    <div v-else-if="activeSection === 'template-tags'" id="template-tags">
                         <h1>Template Tags & Key-Value Store</h1>
                         <p class="lead">Use <code>engine.data</code> as a key-value store and <code v-pre>{{key}}</code> placeholders in slide strings. Values resolve at render time and update reactively when <code>engine.data</code> changes.</p>
 
@@ -1879,8 +1877,10 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
                         </p>
                     </div>
 
+                    <!-- LAYOUTS (single page with anchors) -->
+                    <div v-else-if="LAYOUT_IDS.includes(activeSection)" class="space-y-24">
                     <!-- REF: STATEMENT -->
-                    <div v-else-if="activeSection === 'ref-statement'">
+                    <section id="ref-statement">
                         <h1>Statement Slide</h1>
                         <p class="lead">High-impact titles, opening covers, or emphatic quotes. Punchy and minimal. Supports <code>sizing</code>, <code>background</code>, <code>notes</code>, <code>class</code>, <code>timelineTracks</code>, <code>reveal</code>, <code>ids</code>, <code>meta</code> (SlideBase).</p>
 
@@ -1910,10 +1910,10 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
                             <h2 class="text-xl font-bold text-white mb-4">Example</h2>
                             <LivePreview :initial-code="EXAMPLES.statement" />
                         </div>
-                    </div>
+                    </section>
 
                     <!-- REF: HALF -->
-                    <div v-else-if="activeSection === 'ref-half'">
+                    <section id="ref-half">
                         <h1>Half / Split Slide</h1>
                         <p class="lead">Image or video on one side, text on the other. Product showcases, "about me", explainers. <strong>Provide <code>image</code> or <code>video</code> (one required).</strong> Plus SlideBase (sizing, background, notes, class, timelineTracks, reveal, ids, meta).</p>
 
@@ -1944,10 +1944,10 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
                             <h2 class="text-xl font-bold text-white mb-4">Example</h2>
                             <LivePreview :initial-code="EXAMPLES.half" />
                         </div>
-                    </div>
+                    </section>
 
                     <!-- REF: FEATURES -->
-                    <div v-else-if="activeSection === 'ref-features'">
+                    <section id="ref-features">
                         <h1>Features Slide</h1>
                         <p class="lead">Grid of cards for benefits, stats, or services. Responsive: 1 column on mobile, auto-fit on desktop. SlideBase (sizing, background, notes, class, timelineTracks, reveal, ids, meta) applies.</p>
 
@@ -1989,10 +1989,10 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
                             <h2 class="text-xl font-bold text-white mb-4">Example</h2>
                             <LivePreview :initial-code="EXAMPLES.features" />
                         </div>
-                    </div>
+                    </section>
 
                     <!-- REF: TIMELINE -->
-                    <div v-else-if="activeSection === 'ref-timeline'">
+                    <section id="ref-timeline">
                         <h1>Timeline Slide</h1>
                         <p class="lead">Vertical chronological list for events, roadmaps, or history. Alternating left/right on desktop. <em>Not</em> the same as <code>slide.timelineTracks</code> (keyframe animation). SlideBase applies.</p>
 
@@ -2035,10 +2035,10 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
                             <h2 class="text-xl font-bold text-white mb-4">Example</h2>
                             <LivePreview :initial-code="EXAMPLES.timeline" />
                         </div>
-                    </div>
+                    </section>
 
                     <!-- REF: STEPS -->
-                    <div v-else-if="activeSection === 'ref-steps'">
+                    <section id="ref-steps">
                         <h1>Steps Slide</h1>
                         <p class="lead">Numbered steps for tutorials, how-to guides, or process flows. Responsive grid. SlideBase applies.</p>
 
@@ -2081,10 +2081,10 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
                             <h2 class="text-xl font-bold text-white mb-4">Example</h2>
                             <LivePreview :initial-code="EXAMPLES.steps" />
                         </div>
-                    </div>
+                    </section>
 
                     <!-- REF: FLEX -->
-                    <div v-else-if="activeSection === 'ref-flex'">
+                    <section id="ref-flex">
                         <h1>Flex Layout</h1>
                         <p class="lead">Flow-based layout with semantic sizing (quarter, half, full, etc.). No coordinates—ideal for LLMs. SlideBase applies. Top-level and content children can have <code>size?: FlexSize</code>.</p>
 
@@ -2147,10 +2147,10 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
                             <h2 class="text-xl font-bold text-white mb-4">Example</h2>
                             <LivePreview :initial-code="EXAMPLES.flex" />
                         </div>
-                    </div>
+                    </section>
 
                     <!-- REF: CHART -->
-                    <div v-else-if="activeSection === 'ref-chart'">
+                    <section id="ref-chart">
                         <h1>Chart Slide</h1>
                         <p class="lead">Data visualization with Chart.js. Types: <code>bar</code>, <code>line</code>, <code>pie</code>, <code>doughnut</code>. Requires <code>chart.js</code> as an optional peer. SlideBase applies.</p>
 
@@ -2439,10 +2439,10 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
                                     charts automatically</li>
                             </ul>
                         </div>
-                    </div>
+                    </section>
 
                     <!-- REF: VIDEO -->
-                    <div v-else-if="activeSection === 'ref-video'">
+                    <section id="ref-video">
                         <h1>Video Slide</h1>
                         <p class="lead">Full-screen video. <code>video</code> (VideoProperties) is required. Optional <code>title</code> overlay at bottom-left (on hover). SlideBase applies.</p>
 
@@ -2508,10 +2508,10 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
                         </div>
 
                         <p class="text-white/60 text-sm">Element control ids: <code>s{N}-video</code>, <code>s{N}-title</code>.</p>
-                    </div>
+                    </section>
 
                     <!-- REF: CUSTOM HTML -->
-                    <div v-else-if="activeSection === 'ref-custom'">
+                    <section id="ref-custom">
                         <h1>Custom HTML Slide</h1>
                         <p class="lead">Raw <code>html</code> and optional <code>css</code>. For iframes, D3, or brand-specific layouts. SlideBase applies. Sanitized: <code>&lt;script&gt;</code> and <code>on*</code> handlers removed.</p>
 
@@ -2585,10 +2585,10 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
                                     creative freedom</li>
                             </ul>
                         </div>
-                    </div>
+                    </section>
 
                     <!-- REF: DIAGRAM -->
-                    <div v-else-if="activeSection === 'ref-diagram'">
+                    <section id="ref-diagram">
                         <h1>Diagram Slide</h1>
                         <p class="lead">Node-based diagram (Vue Flow). <code>nodes</code> and <code>edges</code> required. In Studio: drag-and-drop, connect, resize. SlideBase applies.</p>
 
@@ -2610,10 +2610,10 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
                             </div>
                             <p class="text-white/50 text-sm mt-2">Element control: <code>s{N}-nodes-{i}</code>, <code>s{N}-edges-{i}</code>. Studio: palette, drag, connect, resize.</p>
                         </div>
-                    </div>
+                    </section>
 
                     <!-- REF: FREE -->
-                    <div v-else-if="activeSection === 'ref-free'">
+                    <section id="ref-free">
                         <h1>Free / Composition Slide</h1>
                         <p class="lead">Absolutely positioned elements for Remotion-style storytelling. Three types: <code>text</code>, <code>image</code>, <code>box</code>. Position and animation are driven by <code>slide.timelineTracks</code> (x, y as translate). SlideBase applies.</p>
 
@@ -2675,10 +2675,10 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
   }
 }</code></pre>
                         </div>
-                    </div>
+                    </section>
 
                     <!-- REF: AUTO -->
-                    <div v-else-if="activeSection === 'ref-auto'">
+                    <section id="ref-auto">
                         <h1>Auto Strategy</h1>
                         <p class="lead">Picks a layout from the data shape. Use <code>type: "auto"</code>; the engine resolves to one of: Chart, Timeline, Steps, Features, Half, Statement. All SlideBase and layout-specific props are passed through to the chosen layout. Best for LLMs and rapid prototyping.</p>
 
@@ -2742,22 +2742,50 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
   ]
 }' />
                         </div>
+                    </section>
+
                     </div>
 
                 </div>
-            </Transition>
         </main>
     </div>
 </template>
 
 <script setup lang="ts">
-import { ref, watch, onUnmounted, nextTick } from 'vue';
+import { ref, watch, onUnmounted, onMounted, nextTick } from 'vue';
 import { Lumina } from '../../core/Lumina';
 import { parsePartialJson } from '../../utils/streaming';
 import LivePreview from './LivePreview.vue';
 
 const activeSection = ref('intro');
 
+const LAYOUT_IDS = ['ref-statement', 'ref-half', 'ref-features', 'ref-timeline', 'ref-steps', 'ref-flex', 'ref-chart', 'ref-video', 'ref-diagram', 'ref-free', 'ref-custom', 'ref-auto'];
+
+function scrollToTop() {
+    window.scrollTo({ top: 0, behavior: 'smooth' });
+}
+
+function goToLayout(id: string) {
+    activeSection.value = id;
+    nextTick(() => {
+        document.getElementById(id)?.scrollIntoView({ behavior: 'smooth', block: 'start' });
+        if (typeof location !== 'undefined') location.hash = id;
+    });
+}
+
+function goToStreamingDemo() {
+    activeSection.value = 'agents-streaming';
+    nextTick(() => document.getElementById('streaming-demo-container')?.scrollIntoView({ behavior: 'smooth', block: 'start' }));
+}
+
+onMounted(() => {
+    if (typeof window === 'undefined') return;
+    const h = window.location.hash.slice(1) || '';
+    if (!h) return;
+    activeSection.value = h;
+    nextTick(() => document.getElementById(h)?.scrollIntoView({ behavior: 'smooth', block: 'start' }));
+});
+
 // --- DEMO LOGIC ---
 const demoInput = ref('');
 const demoStarted = ref(false);
@@ -2847,7 +2875,7 @@ async function runDemo() {
 
 function loadIntoDemo(json: string) {
     activeSection.value = 'agents-streaming';
-    window.scrollTo({ top: 0, behavior: 'smooth' });
+    nextTick(() => document.getElementById('streaming-demo-container')?.scrollIntoView({ behavior: 'smooth', block: 'start' }));
     demoInput.value = '';
     demoStarted.value = true;
 
@@ -3057,6 +3085,7 @@ const navigation = [
         title: 'AI & LLM Integration',
         items: [
             { id: 'agents-streaming', label: 'Streaming & Realtime' },
+            { id: 'agents-layouts', label: 'Layout Gallery' },
             { id: 'agents-intro', label: 'Agent Protocol' },
             { id: 'agents-tokens', label: 'Token Optimization' }
         ]
@@ -3077,21 +3106,13 @@ const navigation = [
 ];
 
 
-function scroll(id: string) {
-    nextTick(() => {
-        const el = document.getElementById(id);
-        if (el) {
-            el.scrollIntoView({ behavior: 'smooth', block: 'center' });
-        }
-    });
-}
-
-function scrollToTop() {
-    window.scrollTo({ top: 0, behavior: 'smooth' });
-}
 </script>
 
 <style scoped>
+.doc-content [id] {
+    scroll-margin-top: 8.5rem;
+}
+
 .doc-content h1 {
     @apply text-4xl md:text-5xl font-black tracking-tight text-white mb-8 leading-tight font-heading;
 }

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);
 }
 

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