lumina-slides 9.0.2 → 9.0.4

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>
@@ -455,30 +454,52 @@ engine.<span class="text-yellow-400">on</span>('navigate', ({ direction, toIndex
                         <ol class="list-decimal list-inside mb-6 space-y-1 text-white/70">
                             <li><strong>Slide root</strong> (path <code>[]</code> or <code>['slide']</code>): <code>slide.id</code> if present, otherwise <code>s{N}-slide</code>.</li>
                             <li><strong>Object with <code>id</code></strong>: if the value at that path is an object with <code>id: string</code> (e.g. <code>features[0].id</code>, a diagram node), that <code>id</code> is used.</li>
-                            <li><strong><code>slide.ids</code></strong>: if the path has a single segment (e.g. <code>tag</code>) and <code>slide.ids.tag</code> exists, that value is used.</li>
-                            <li><strong>Fallback</strong>: <code>elemId(slideIndex, ...path)</code> → format <code>s{N}-{path0}-{path1}-...</code> (e.g. <code>s0-tag</code>, <code>s1-features-2</code>, <code>s2-elements-0-elements-1</code>).</li>
+                            <li><strong><code>slide.ids[key]</code></strong>: e.g. <code>slide.ids["tag"]</code>, <code>slide.ids["features.0"]</code>. Overrides the fallback when the object has no <code>id</code>.</li>
+                            <li><strong>Fallback</strong>: if <code>slide.id</code> is set → <code>{slide.id}-{path}</code> (e.g. <code>intro-tag</code>, <code>intro-title</code>); these IDs stay stable when you insert, remove or reorder slides. Otherwise → <code>s{N}-{path}</code> (e.g. <code>s0-tag</code>, <code>s1-features-0</code>).</li>
                         </ol>
 
-                        <p><strong>Ids by slide type</strong> (when there is no <code>id</code> or <code>slide.ids</code>):</p>
+                        <p><strong>Stable IDs with <code>slide.id</code></strong>: set <code>id: "intro"</code> on a slide so the fallback becomes <code>intro-tag</code>, <code>intro-title</code>, etc. Recommended when using <code>meta.initialElementState</code> or reorderable decks.</p>
+
+                        <h3>Element IDs per layout</h3>
+                        <p>Each row is one controllable element. <strong>Path</strong> is used in <code>engine.element(slideIndex, "tag")</code> or <code>engine.elementInCurrent("title")</code>. <strong>Fallback ID</strong> when no <code>slide.id</code>, <code>slide.ids</code> or <code>object.id</code>; with <code>slide.id: "x"</code> it becomes <code>x-tag</code>, <code>x-title</code>, etc. <strong>When</strong> = always, or only when that field exists in the slide JSON.</p>
                         <div class="overflow-x-auto mb-6">
                             <table class="w-full text-sm border border-white/10 rounded-lg">
-                                <thead><tr class="border-b border-white/10"><th class="text-left py-2 px-3 text-white/90">Type</th><th class="text-left py-2 px-3 text-white/90">Paths (path → id fallback)</th></tr></thead>
+                                <thead><tr class="border-b border-white/10"><th class="text-left py-2 px-3 text-white/90">Layout</th><th class="text-left py-2 px-3 text-white/90">Path</th><th class="text-left py-2 px-3 text-white/90">Fallback ID</th><th class="text-left py-2 px-3 text-white/90">When</th></tr></thead>
                                 <tbody class="text-white/70">
-                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">statement</td><td class="py-2 px-3"><code>tag</code>→s{N}-tag, <code>title</code>→s{N}-title, <code>subtitle</code>→s{N}-subtitle</td></tr>
-                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">features</td><td class="py-2 px-3"><code>header</code>→s{N}-header, <code>features.i</code>→s{N}-features-{i}</td></tr>
-                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">half</td><td class="py-2 px-3"><code>media</code>, <code>tag</code>, <code>title</code>, <code>paragraphs</code>, <code>cta</code> → s{N}-media, s{N}-tag, etc.</td></tr>
-                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">timeline</td><td class="py-2 px-3"><code>title</code>, <code>subtitle</code>, <code>timeline.i</code> → s{N}-title, s{N}-subtitle, s{N}-timeline-{i}</td></tr>
-                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">steps</td><td class="py-2 px-3"><code>header</code>, <code>steps.i</code> → s{N}-header, s{N}-steps-{i}</td></tr>
-                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">flex</td><td class="py-2 px-3"><code>elements.i</code> → s{N}-elements-{i}; nested <code>elements.i.elements.j</code> → s{N}-elements-{i}-elements-{j}</td></tr>
-                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">chart</td><td class="py-2 px-3"><code>title</code>, <code>subtitle</code>, <code>chart</code> → s{N}-title, s{N}-subtitle, s{N}-chart</td></tr>
-                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">video</td><td class="py-2 px-3"><code>video</code>, <code>title</code> → s{N}-video, s{N}-title</td></tr>
-                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">diagram</td><td class="py-2 px-3"><code>nodes.i</code>, <code>edges.i</code>; if the node has <code>id</code>, it is used</td></tr>
-                                    <tr><td class="py-2 px-3 font-mono">free</td><td class="py-2 px-3"><code>elements.i</code> → s{N}-elements-0, s{N}-elements-1, …</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">statement</td><td class="py-2 px-3"><code>tag</code></td><td class="py-2 px-3"><code>s{N}-tag</code></td><td class="py-2 px-3">only when <code>tag</code> is set</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">statement</td><td class="py-2 px-3"><code>title</code></td><td class="py-2 px-3"><code>s{N}-title</code></td><td class="py-2 px-3">always</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">statement</td><td class="py-2 px-3"><code>subtitle</code></td><td class="py-2 px-3"><code>s{N}-subtitle</code></td><td class="py-2 px-3">only when <code>subtitle</code> is set</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">features</td><td class="py-2 px-3"><code>header</code></td><td class="py-2 px-3"><code>s{N}-header</code></td><td class="py-2 px-3">always (wrapper for title + description)</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">features</td><td class="py-2 px-3"><code>title</code></td><td class="py-2 px-3"><code>s{N}-title</code></td><td class="py-2 px-3">always</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">features</td><td class="py-2 px-3"><code>description</code></td><td class="py-2 px-3"><code>s{N}-description</code></td><td class="py-2 px-3">only when <code>description</code> is set</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">features</td><td class="py-2 px-3"><code>features.0</code>, <code>features.1</code>, …</td><td class="py-2 px-3"><code>s{N}-features-{i}</code> or <code>features[i].id</code></td><td class="py-2 px-3">one per feature</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">half</td><td class="py-2 px-3"><code>media</code></td><td class="py-2 px-3"><code>s{N}-media</code></td><td class="py-2 px-3">always</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">half</td><td class="py-2 px-3"><code>tag</code></td><td class="py-2 px-3"><code>s{N}-tag</code></td><td class="py-2 px-3">only when <code>tag</code> is set</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">half</td><td class="py-2 px-3"><code>title</code></td><td class="py-2 px-3"><code>s{N}-title</code></td><td class="py-2 px-3">always</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">half</td><td class="py-2 px-3"><code>paragraphs</code></td><td class="py-2 px-3"><code>s{N}-paragraphs</code></td><td class="py-2 px-3">always</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">half</td><td class="py-2 px-3"><code>cta</code></td><td class="py-2 px-3"><code>s{N}-cta</code></td><td class="py-2 px-3">only when <code>cta</code> is set</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">timeline</td><td class="py-2 px-3"><code>title</code></td><td class="py-2 px-3"><code>s{N}-title</code></td><td class="py-2 px-3">always</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">timeline</td><td class="py-2 px-3"><code>subtitle</code></td><td class="py-2 px-3"><code>s{N}-subtitle</code></td><td class="py-2 px-3">only when <code>subtitle</code> is set</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">timeline</td><td class="py-2 px-3"><code>timeline.0</code>, <code>timeline.1</code>, …</td><td class="py-2 px-3"><code>s{N}-timeline-{i}</code> or <code>timeline[i].id</code></td><td class="py-2 px-3">one per item</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">steps</td><td class="py-2 px-3"><code>header</code></td><td class="py-2 px-3"><code>s{N}-header</code></td><td class="py-2 px-3">always (wrapper for title + subtitle)</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">steps</td><td class="py-2 px-3"><code>title</code></td><td class="py-2 px-3"><code>s{N}-title</code></td><td class="py-2 px-3">always</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">steps</td><td class="py-2 px-3"><code>subtitle</code></td><td class="py-2 px-3"><code>s{N}-subtitle</code></td><td class="py-2 px-3">only when <code>subtitle</code> is set</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">steps</td><td class="py-2 px-3"><code>steps.0</code>, <code>steps.1</code>, …</td><td class="py-2 px-3"><code>s{N}-steps-{i}</code> or <code>steps[i].id</code></td><td class="py-2 px-3">one per step</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">flex</td><td class="py-2 px-3"><code>elements.0</code>, <code>elements.1</code>, …</td><td class="py-2 px-3"><code>s{N}-elements-{i}</code> or <code>elements[i].id</code></td><td class="py-2 px-3">one per element</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">flex</td><td class="py-2 px-3"><code>elements.i.elements.j</code></td><td class="py-2 px-3"><code>s{N}-elements-{i}-elements-{j}</code></td><td class="py-2 px-3">content children only</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">chart</td><td class="py-2 px-3"><code>title</code></td><td class="py-2 px-3"><code>s{N}-title</code></td><td class="py-2 px-3">only when <code>title</code> is set</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">chart</td><td class="py-2 px-3"><code>subtitle</code></td><td class="py-2 px-3"><code>s{N}-subtitle</code></td><td class="py-2 px-3">only when <code>subtitle</code> is set</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">chart</td><td class="py-2 px-3"><code>chart</code></td><td class="py-2 px-3"><code>s{N}-chart</code></td><td class="py-2 px-3">always (may be absent in DOM if Chart.js fails)</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">video</td><td class="py-2 px-3"><code>video</code></td><td class="py-2 px-3"><code>s{N}-video</code></td><td class="py-2 px-3">always</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">video</td><td class="py-2 px-3"><code>title</code></td><td class="py-2 px-3"><code>s{N}-title</code></td><td class="py-2 px-3">only when <code>title</code> is set</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">diagram</td><td class="py-2 px-3"><code>nodes.0</code>, <code>nodes.1</code>, …</td><td class="py-2 px-3"><code>nodes[i].id</code> or <code>s{N}-nodes-{i}</code></td><td class="py-2 px-3">set <code>nodes[i].id</code> in JSON for control</td></tr>
+                                    <tr class="border-b border-white/5"><td class="py-2 px-3 font-mono">diagram</td><td class="py-2 px-3"><code>edges.0</code>, <code>edges.1</code>, …</td><td class="py-2 px-3"><code>edges[i].id</code> or <code>s{N}-edges-{i}</code></td><td class="py-2 px-3">set <code>edges[i].id</code> in JSON for control</td></tr>
+                                    <tr><td class="py-2 px-3 font-mono">free</td><td class="py-2 px-3"><code>elements.0</code>, <code>elements.1</code>, …</td><td class="py-2 px-3"><code>s{N}-elements-{i}</code></td><td class="py-2 px-3">one per element</td></tr>
                                 </tbody>
                             </table>
                         </div>
 
-                        <p>To see a slide's ids at runtime: <code>engine.elements(slideIndex)</code>. To use by path: <code>engine.element(slideIndex, "tag")</code> or <code>engine.element(slideIndex, "features.0")</code>; the id is resolved with the same rules.</p>
+                        <p><strong>Discover and target</strong>: <code>engine.elements()</code> or <code>engine.elements(slideIndex)</code> lists all ids for a slide (omit <code>slideIndex</code> for the current slide). <code>engine.element(id)</code>, <code>engine.element(slideIndex, "tag")</code>, or <code>engine.elementInCurrent("title")</code> for the current slide by path. Override any path via <code>slide.ids</code> (e.g. <code>ids: { "title": "hero-title" }</code>) or <code>object.id</code> on items (e.g. <code>features[0].id: "hero"</code>).</p>
 
                         <h2>Option 1: meta.initialElementState</h2>
                         <p>Define in the deck which elements start hidden. Ids follow the pattern
@@ -570,7 +591,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 +623,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 +659,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 +1424,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 +1508,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 +1554,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 +1662,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 +1710,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 +1770,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 +1848,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 +1856,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 +1899,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>
 
@@ -1903,17 +1925,17 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
                                     </tbody>
                                 </table>
                             </div>
-                            <p class="text-white/50 text-sm mt-2">Element ids: <code>s{N}-tag</code>, <code>s{N}-title</code>, <code>s{N}-subtitle</code>. Override via <code>ids</code>.</p>
+                            <p class="text-white/50 text-sm mt-2">Element ids: <code>tag</code> (if set)→<code>s{N}-tag</code>, <code>title</code>→<code>s{N}-title</code>, <code>subtitle</code> (if set)→<code>s{N}-subtitle</code>. With <code>slide.id</code>: <code>{id}-tag</code>, etc. Override via <code>slide.ids</code>. <a href="#element-control" class="text-blue-400 hover:underline">Element Control</a> has the full table.</p>
                         </div>
 
                         <div class="my-8">
                             <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>
 
@@ -1937,17 +1959,17 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
                                     </tbody>
                                 </table>
                             </div>
-                            <p class="text-white/50 text-sm mt-2">Element ids: <code>s{N}-media</code>, <code>s{N}-tag</code>, <code>s{N}-title</code>, <code>s{N}-paragraphs</code>, <code>s{N}-cta</code>.</p>
+                            <p class="text-white/50 text-sm mt-2">Element ids: <code>media</code>, <code>tag</code> (if set), <code>title</code>, <code>paragraphs</code>, <code>cta</code> (if set) → <code>s{N}-media</code>, <code>s{N}-tag</code>, etc. <a href="#element-control" class="text-blue-400 hover:underline">Element Control</a> has the full table.</p>
                         </div>
 
                         <div class="my-8">
                             <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>
 
@@ -1982,17 +2004,17 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
                                     </tbody>
                                 </table>
                             </div>
-                            <p class="text-white/50 text-sm mt-2">Element ids: <code>s{N}-header</code>, <code>s{N}-features-0</code>, <code>s{N}-features-1</code>, …</p>
+                            <p class="text-white/50 text-sm mt-2">Element ids: <code>header</code>, <code>title</code>, <code>description</code> (if set), <code>features.0</code>, <code>features.1</code>, … → <code>s{N}-header</code>, <code>s{N}-title</code>, <code>s{N}-features-0</code>, etc. <a href="#element-control" class="text-blue-400 hover:underline">Element Control</a> has the full table.</p>
                         </div>
 
                         <div class="my-8">
                             <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>
 
@@ -2028,17 +2050,17 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
                                     </tbody>
                                 </table>
                             </div>
-                            <p class="text-white/50 text-sm mt-2">Element ids: <code>s{N}-title</code>, <code>s{N}-subtitle</code>, <code>s{N}-timeline-0</code>, …</p>
+                            <p class="text-white/50 text-sm mt-2">Element ids: <code>title</code>, <code>subtitle</code> (if set), <code>timeline.0</code>, <code>timeline.1</code>, … → <code>s{N}-title</code>, <code>s{N}-subtitle</code>, <code>s{N}-timeline-{i}</code>. <a href="#element-control" class="text-blue-400 hover:underline">Element Control</a> has the full table.</p>
                         </div>
 
                         <div class="my-8">
                             <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>
 
@@ -2074,17 +2096,17 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
                                     </tbody>
                                 </table>
                             </div>
-                            <p class="text-white/50 text-sm mt-2">Element ids: <code>s{N}-header</code>, <code>s{N}-steps-0</code>, <code>s{N}-steps-1</code>, …</p>
+                            <p class="text-white/50 text-sm mt-2">Element ids: <code>header</code>, <code>title</code>, <code>subtitle</code> (if set), <code>steps.0</code>, <code>steps.1</code>, … → <code>s{N}-header</code>, <code>s{N}-title</code>, <code>s{N}-steps-{i}</code>. <a href="#element-control" class="text-blue-400 hover:underline">Element Control</a> has the full table.</p>
                         </div>
 
                         <div class="my-8">
                             <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>
 
@@ -2135,7 +2157,7 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
                                     </tbody>
                                 </table>
                             </div>
-                            <p class="text-white/50 text-sm mt-2">SpacingToken: <code>none | xs | sm | md | lg | xl | 2xl</code>. Element ids: <code>s{N}-elements-{i}</code>, <code>s{N}-elements-{i}-elements-{j}</code> for content children.</p>
+                            <p class="text-white/50 text-sm mt-2">SpacingToken: <code>none | xs | sm | md | lg | xl | 2xl</code>. Element ids: <code>elements.0</code>, <code>elements.1</code>, …, <code>elements.i.elements.j</code> (content) → <code>s{N}-elements-{i}</code>, <code>s{N}-elements-{i}-elements-{j}</code>. <a href="#element-control" class="text-blue-400 hover:underline">Element Control</a> has the full table.</p>
                         </div>
 
                         <div class="my-8">
@@ -2147,10 +2169,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>
 
@@ -2195,6 +2217,7 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
                                     </tbody>
                                 </table>
                             </div>
+                            <p class="text-white/50 text-sm mt-2">Element ids: <code>title</code> (if set), <code>subtitle</code> (if set), <code>chart</code> → <code>s{N}-title</code>, <code>s{N}-subtitle</code>, <code>s{N}-chart</code>. <a href="#element-control" class="text-blue-400 hover:underline">Element Control</a> has the full table.</p>
                         </div>
 
                         <div class="my-8">
@@ -2439,10 +2462,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>
 
@@ -2507,11 +2530,11 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
                             <LivePreview :initial-code="EXAMPLES.video_slide" />
                         </div>
 
-                        <p class="text-white/60 text-sm">Element control ids: <code>s{N}-video</code>, <code>s{N}-title</code>.</p>
-                    </div>
+                        <p class="text-white/50 text-sm mt-2">Element ids: <code>video</code>, <code>title</code> (if set) → <code>s{N}-video</code>, <code>s{N}-title</code>. <a href="#element-control" class="text-blue-400 hover:underline">Element Control</a> has the full table.</p>
+                    </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 +2608,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>
 
@@ -2608,12 +2631,12 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
                                     </tbody>
                                 </table>
                             </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>
+                            <p class="text-white/50 text-sm mt-2">Element ids: <code>nodes.0</code>, <code>nodes.1</code>, … and <code>edges.0</code>, … Use <code>nodes[i].id</code> and <code>edges[i].id</code> in JSON so <code>engine.elements()</code> aligns with the DOM. Fallback: <code>s{N}-nodes-{i}</code>, <code>s{N}-edges-{i}</code>. <a href="#element-control" class="text-blue-400 hover:underline">Element Control</a> has the full table. 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>
 
@@ -2651,6 +2674,7 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
                                     </tbody>
                                 </table>
                             </div>
+                            <p class="text-white/50 text-sm mt-2">Element ids: <code>elements.0</code>, <code>elements.1</code>, … → <code>s{N}-elements-{i}</code>. Override with <code>elements[i].id</code>. <a href="#element-control" class="text-blue-400 hover:underline">Element Control</a> has the full table.</p>
 
                             <h3 class="text-lg font-bold text-white mt-8 mb-4">Positioning and animation (timelineTracks)</h3>
                             <p>Elements are placed at <code>left: 0; top: 0</code> by default. To move or animate them, set <code>slide.timelineTracks</code> on the slide (SlideBase). Keys are element ids: <code>s{N}-elements-0</code>, <code>s{N}-elements-1</code>, or the element’s <code>id</code>. Value: keyframes from progress string to state:</p>
@@ -2675,10 +2699,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 +2766,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 +2899,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 +3109,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 +3130,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;
 }