lumina-slides 9.0.3 → 9.0.5

package/src/components/site/SiteDocs.vue

@@ -310,7 +310,7 @@ engine.load(myDeckData);</code></pre>
                                         5</div>
                                     <div>
                                         <h2 class="text-2xl font-bold text-white mb-1">Flex</h2>
-                                        <p class="text-sm text-white/50">Flow-based layout with size tokens (<code>half</code>, <code>third</code>, …). Elements: <code>title</code>, <code>text</code>, <code>bullets</code>, <code>image</code>, <code>video</code>, <code>button</code>, <code>content</code>, <code>timeline</code>, <code>stepper</code>, <code>spacer</code>. See <em>Flex</em> in Layouts.</p>
+                                        <p class="text-sm text-white/50">Flow-based layout with size tokens (<code>half</code>, <code>third</code>, …). Elements: <code>title</code>, <code>text</code>, <code>bullets</code>, <code>image</code>, <code>html</code>, <code>video</code>, <code>button</code>, <code>content</code> (supports nesting), <code>timeline</code>, <code>stepper</code>, <code>spacer</code>. See <em>Flex</em> in Layouts.</p>
                                     </div>
                                 </div>
                                 <div class="prose prose-invert max-w-none prose-pre:bg-black/50 prose-pre:border-none">
@@ -454,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
@@ -1903,7 +1925,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>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">
@@ -1937,7 +1959,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>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">
@@ -1982,7 +2004,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>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">
@@ -2028,7 +2050,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>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">
@@ -2074,7 +2096,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>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">
@@ -2121,8 +2143,9 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
                                         <tr><th class="p-3 border-b border-white/10">type</th><th class="p-3 border-b border-white/10">Properties</th><th class="p-3 border-b border-white/10">Description</th></tr>
                                     </thead>
                                     <tbody class="divide-y divide-white/5">
-                                        <tr><td class="p-3 font-mono text-cyan-400">content</td><td class="p-3 font-mono text-xs">elements, valign?, halign?, gap?, padding?, size?</td><td class="p-3">Groups children vertically. Children: title, text, bullets, ordered, button, timeline, stepper, spacer (no image/video/nested content).</td></tr>
-                                        <tr><td class="p-3 font-mono text-cyan-400">image</td><td class="p-3 font-mono text-xs">src, alt?, fill?, fit?, rounded?, href?, target?, class?, size?, id?</td><td class="p-3">Media. fill: edge-to-edge. fit: cover|contain. href+target: link. Rounded: none|sm|md|lg|xl|full.</td></tr>
+                                        <tr><td class="p-3 font-mono text-cyan-400">content</td><td class="p-3 font-mono text-xs">elements, direction?, valign?, halign?, gap?, padding?, size?, class?, style?, id?</td><td class="p-3">Groups children with alignment. <code>direction</code>: horizontal|vertical (default: vertical). Supports nested content, html, image, and all child elements. <code>class</code> and <code>style</code> for custom styling.</td></tr>
+                                        <tr><td class="p-3 font-mono text-cyan-400">image</td><td class="p-3 font-mono text-xs">src, alt?, fill?, fit?, position?, rounded?, href?, target?, class?, style?, size?, id?</td><td class="p-3">Media. <code>fill</code>: edge-to-edge. <code>fit</code>: cover|contain|fill|none|scale-down. <code>position</code>: object-position (e.g., "top center"). <code>href</code>+<code>target</code>: link. <code>rounded</code>: none|sm|md|lg|xl|full. <code>style</code>: custom CSS.</td></tr>
+                                        <tr><td class="p-3 font-mono text-cyan-400">html</td><td class="p-3 font-mono text-xs">html, class?, style?, size?, id?</td><td class="p-3">Raw HTML content. Renders any HTML string. Supports <code>class</code> and <code>style</code> for customization. Automatically styled to match Lumina theme.</td></tr>
                                         <tr><td class="p-3 font-mono text-cyan-400">video</td><td class="p-3 font-mono text-xs">src, poster?, autoplay?, loop?, muted?, controls?, fill?, fit?, rounded?, class?, size?, id?</td><td class="p-3">Video element. Same fill/fit/rounded as image.</td></tr>
                                         <tr><td class="p-3 font-mono text-cyan-400">title</td><td class="p-3 font-mono text-xs">text, size? (lg|xl|2xl|3xl), align?, id?</td><td class="p-3">Heading. align: left|center|right. Top-level only: optional FlexSize <code>size</code>.</td></tr>
                                         <tr><td class="p-3 font-mono text-cyan-400">text</td><td class="p-3 font-mono text-xs">text, align?, muted?, size?, id?</td><td class="p-3">Paragraph. muted: subtle style.</td></tr>
@@ -2135,12 +2158,53 @@ 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">
+                            <h2 class="text-xl font-bold text-white mb-4">Content container (direction, valign, halign, gap, padding)</h2>
+                            <p><strong>Direction:</strong> <code>horizontal</code> | <code>vertical</code> (default: <code>vertical</code>). Controls layout direction of child elements.</p>
+                            <p><strong>Defaults:</strong> direction <code>vertical</code>, valign <code>center</code>, halign <code>left</code>, gap <code>md</code>, padding <code>lg</code>.</p>
+                            <p class="mt-2"><strong>Nested content:</strong> Content containers can be nested inside other content containers for complex layouts. Supports unlimited nesting levels.</p>
+                        </div>
+
+                        <div class="my-8">
+                            <h2 class="text-xl font-bold text-white mb-4">HTML Element</h2>
+                            <p>The <code>html</code> element allows you to insert raw HTML content into your flex layout. This is useful for custom formatting, embedded content, or any HTML that isn't covered by other element types.</p>
+                            <div class="mt-4 p-4 bg-white/5 rounded-lg border border-white/10">
+                                <p class="text-sm text-white/70 mb-2"><strong>Example:</strong></p>
+                                <pre class="text-xs"><code>{{
+`{
+  "type": "html",
+  "html": "<p>Insert <strong>any HTML</strong> here.</p><ul><li>List item</li></ul>",
+  "class": "custom-class",
+  "style": { "maxWidth": "600px" }
+}`}}</code></pre>
+                            </div>
+                            <p class="text-sm text-white/50 mt-2">The HTML is automatically styled to match Lumina's theme. Common HTML elements (h1-h6, p, a, ul, ol, li) are styled with Lumina CSS variables.</p>
                         </div>
 
                         <div class="my-8">
-                            <h2 class="text-xl font-bold text-white mb-4">Content container (valign, halign, gap, padding)</h2>
-                            <p>Defaults: valign <code>center</code>, halign <code>left</code>, gap <code>md</code>, padding <code>lg</code>.</p>
+                            <h2 class="text-xl font-bold text-white mb-4">Enhanced Image Element</h2>
+                            <p>The <code>image</code> element now supports advanced positioning and styling options:</p>
+                            <ul class="list-disc list-inside text-white/70 space-y-1 mt-2">
+                                <li><code>fit</code>: <code>cover</code> | <code>contain</code> | <code>fill</code> | <code>none</code> | <code>scale-down</code> - Controls how the image fits its container</li>
+                                <li><code>position</code>: string (e.g., <code>"top center"</code>, <code>"left bottom"</code>) - Controls object-position CSS property</li>
+                                <li><code>style</code>: object - Custom CSS styles as key-value pairs</li>
+                                <li><code>class</code>: string - Custom CSS class names</li>
+                            </ul>
+                            <div class="mt-4 p-4 bg-white/5 rounded-lg border border-white/10">
+                                <p class="text-sm text-white/70 mb-2"><strong>Example:</strong></p>
+                                <pre class="text-xs"><code>{{
+`{
+  "type": "image",
+  "src": "photo.jpg",
+  "fit": "contain",
+  "position": "top center",
+  "rounded": "lg",
+  "style": { "border": "2px solid var(--lumina-color-primary)" }
+}`}}</code></pre>
+                            </div>
                         </div>
 
                         <div class="my-8">
@@ -2195,6 +2259,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">
@@ -2507,7 +2572,7 @@ 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>
+                        <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 -->
@@ -2608,7 +2673,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 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>
                     </section>
 
@@ -2651,6 +2716,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>
@@ -2753,10 +2819,13 @@ engine.data.set(<span class="text-green-400">"user"</span>, <span class="text-gr
 
 <script setup lang="ts">
 import { ref, watch, onUnmounted, onMounted, nextTick } from 'vue';
+import TurndownService from 'turndown';
 import { Lumina } from '../../core/Lumina';
 import { parsePartialJson } from '../../utils/streaming';
 import LivePreview from './LivePreview.vue';
 
+const turndownService = new TurndownService({ headingStyle: 'atx', codeBlockStyle: 'fenced' });
+
 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'];
@@ -2778,12 +2847,74 @@ function goToStreamingDemo() {
     nextTick(() => document.getElementById('streaming-demo-container')?.scrollIntoView({ behavior: 'smooth', block: 'start' }));
 }
 
+function getHeadingLevel(el: Element): number {
+    const m = /^H([1-6])$/.exec(el.tagName || '');
+    return m ? parseInt(m[1], 10) : 7;
+}
+
+async function copySectionAsMarkdown(heading: HTMLElement | null, button?: HTMLElement) {
+    if (!heading || !heading.closest('.doc-content')) return;
+    const level = getHeadingLevel(heading);
+    const container = document.createElement('div');
+    const headingClone = heading.cloneNode(true) as HTMLElement;
+    headingClone.querySelector('.doc-copy-btn')?.remove();
+    container.appendChild(headingClone);
+    let el: Element | null = heading.nextElementSibling;
+    while (el) {
+        if (/^H[1-6]$/i.test(el.tagName) && getHeadingLevel(el) <= level) break;
+        container.appendChild(el.cloneNode(true));
+        el = el.nextElementSibling;
+    }
+    try {
+        const md = turndownService.turndown(container);
+        await navigator.clipboard.writeText(md);
+        if (button) {
+            const orig = button.innerHTML;
+            button.innerHTML = CHECK_ICON_SVG;
+            button.classList.add('doc-copy-btn-done');
+            button.setAttribute('aria-label', 'Copiado');
+            setTimeout(() => {
+                button.innerHTML = orig;
+                button.classList.remove('doc-copy-btn-done');
+                button.setAttribute('aria-label', 'Copiar sección en Markdown');
+            }, 2000);
+        }
+    } catch (_) { /* clipboard or turndown error */ }
+}
+
+const COPY_ICON_SVG = '<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 256 256" fill="currentColor" aria-hidden="true"><path d="M216 32H88a8 8 0 0 0-8 8v40H40a8 8 0 0 0-8 8v128a8 8 0 0 0 8 8h128a8 8 0 0 0 8-8v-40h40a8 8 0 0 0 8-8V40a8 8 0 0 0-8-8Zm-56 176H48V96h112Zm48-48h-32V88a8 8 0 0 0-8-8H96V48h112Z"/></svg>';
+const CHECK_ICON_SVG = '<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 256 256" fill="currentColor" aria-hidden="true"><path d="M229.66 77.66l-128 128a8 8 0 0 1-11.32 0l-56-56a8 8 0 0 1 11.32-11.32L96 188.69 218.34 66.34a8 8 0 0 1 11.32 11.32Z"/></svg>';
+
+function injectCopyButtons() {
+    const root = document.querySelector('.doc-content');
+    if (!root) return;
+    root.querySelectorAll('h1, h2, h3').forEach((h) => {
+        if ((h as HTMLElement).querySelector('.doc-copy-btn')) return;
+        const btn = document.createElement('button');
+        btn.type = 'button';
+        btn.className = 'doc-copy-btn';
+        btn.title = 'Copiar sección en Markdown';
+        btn.setAttribute('aria-label', 'Copiar sección en Markdown');
+        btn.innerHTML = COPY_ICON_SVG;
+        btn.addEventListener('click', (e) => {
+            e.stopPropagation();
+            copySectionAsMarkdown((e.currentTarget as HTMLElement).parentElement, e.currentTarget as HTMLElement);
+        });
+        (h as HTMLElement).appendChild(btn);
+    });
+}
+
+watch(activeSection, () => nextTick(injectCopyButtons));
+
 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' }));
+    if (h) {
+        activeSection.value = h;
+        nextTick(() => document.getElementById(h)?.scrollIntoView({ behavior: 'smooth', block: 'start' }));
+    }
+    nextTick(injectCopyButtons);
+    setTimeout(injectCopyButtons, 150);
 });
 
 // --- DEMO LOGIC ---
@@ -2950,13 +3081,31 @@ const EXAMPLES = {
   "type": "flex",
   "sizing": "container",
   "direction": "horizontal",
+  "gap": "lg",
   "elements": [
-    { "type": "image", "src": "./brains.png", "size": "half", "fill": true },
-    { "type": "content", "size": "half", "valign": "center", "padding": "xl", "gap": "md", "elements": [
-      { "type": "title", "text": "Visual Story", "size": "2xl" },
-      { "type": "bullets", "items": ["Image fills height", "Content centered", "No coordinates"] },
-      { "type": "button", "label": "Learn More", "variant": "primary" }
-    ]}
+    { 
+      "type": "image", 
+      "src": "./brains.png", 
+      "size": "half", 
+      "fill": true,
+      "fit": "cover",
+      "position": "center"
+    },
+    { 
+      "type": "content", 
+      "size": "half", 
+      "direction": "vertical",
+      "valign": "center", 
+      "padding": "xl", 
+      "gap": "md", 
+      "elements": [
+        { "type": "title", "text": "Visual Story", "size": "2xl" },
+        { "type": "text", "text": "Enhanced flex layout with new features" },
+        { "type": "html", "html": "<p>Insert <strong>custom HTML</strong> here</p>" },
+        { "type": "bullets", "items": ["Nested content support", "HTML elements", "Enhanced images"] },
+        { "type": "button", "label": "Learn More", "variant": "primary" }
+      ]
+    }
   ]
 }` ,
     video: `{
@@ -3114,15 +3263,22 @@ const navigation = [
 }
 
 .doc-content h1 {
-    @apply text-4xl md:text-5xl font-black tracking-tight text-white mb-8 leading-tight font-heading;
+    @apply text-4xl md:text-5xl font-black tracking-tight text-white mb-8 leading-tight font-heading flex flex-wrap items-center gap-2;
 }
 
 .doc-content h2 {
-    @apply text-2xl md:text-3xl font-bold text-white mt-16 mb-6 tracking-tight font-heading;
+    @apply text-2xl md:text-3xl font-bold text-white mt-16 mb-6 tracking-tight font-heading flex flex-wrap items-center gap-2;
 }
 
 .doc-content h3 {
-    @apply text-[20px] font-extrabold text-white mb-[15px] mt-8 font-heading;
+    @apply text-[20px] font-extrabold text-white mb-[15px] mt-8 font-heading flex flex-wrap items-center gap-2;
+}
+
+.doc-content :deep(.doc-copy-btn) {
+    @apply inline-flex items-center justify-center w-8 h-8 rounded-lg text-white/40 hover:text-white/90 hover:bg-white/10 transition-colors flex-shrink-0;
+}
+.doc-content :deep(.doc-copy-btn-done) {
+    @apply text-green-400;
 }
 
 .doc-content p {

package/src/composables/useFlexLayout.ts

@@ -63,14 +63,20 @@ export const getFlexContainerStyle = (element: FlexElementContent): CSSPropertie
     const halign = element.halign || 'left';
     const gap = element.gap || 'md';
     const padding = element.padding || 'lg';
+    const direction = element.direction || 'vertical';
 
     return {
         display: 'flex',
-        flexDirection: 'column', // Content containers are always column based for children
-        justifyContent: valignMap[valign] as CSSProperties['justifyContent'],
-        alignItems: halignMap[halign] as CSSProperties['alignItems'],
+        flexDirection: direction === 'horizontal' ? 'row' : 'column',
+        justifyContent: direction === 'horizontal' 
+            ? halignMap[halign] as CSSProperties['justifyContent']
+            : valignMap[valign] as CSSProperties['justifyContent'],
+        alignItems: direction === 'horizontal'
+            ? valignMap[valign] as CSSProperties['alignItems']
+            : halignMap[halign] as CSSProperties['alignItems'],
         gap: spacingVarMap[gap],
         padding: spacingVarMap[padding],
+        ...(element.style || {}),
     };
 };
 

package/src/core/elementResolver.ts

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

package/src/core/schema.ts

@@ -179,8 +179,20 @@ const FlexElementImageSchema = z.object({
     src: fuzzyString.describe("Image URL."),
     alt: fuzzyString.optional().describe("Alt text for accessibility."),
     fill: z.boolean().optional().describe("Fill container edge-to-edge. Default: true."),
-    fit: z.enum(['cover', 'contain']).optional().describe("Object-fit when fill. Default: 'cover'."),
+    fit: z.enum(['cover', 'contain', 'fill', 'none', 'scale-down']).optional().describe("Object-fit mode. Default: 'cover' when fill is true."),
+    position: fuzzyString.optional().describe("Object-position for image placement. Default: 'center'."),
     rounded: z.enum(['none', 'sm', 'md', 'lg', 'xl', 'full']).optional().describe("Border radius."),
+    href: fuzzyString.optional().describe("Link URL when image is clicked."),
+    target: z.enum(['_blank', '_self']).optional().describe("Link target. Default: '_blank'."),
+    class: fuzzyString.optional().describe("Custom CSS class."),
+    style: z.record(z.string()).optional().describe("Custom CSS style object."),
+});
+
+const FlexElementHtmlSchema = z.object({
+    type: z.literal('html').describe("Raw HTML content element."),
+    html: fuzzyString.describe("Raw HTML string to render."),
+    class: fuzzyString.optional().describe("Custom CSS class."),
+    style: z.record(z.string()).optional().describe("Custom CSS style object."),
 });
 
 const FlexElementButtonSchema = z.object({
@@ -208,8 +220,27 @@ const FlexElementSpacerSchema = z.object({
     size: SpacingTokenSchema.optional().describe("Size of the space. Default: 'md'."),
 });
 
-// Child elements (inside content container)
-const FlexChildElementSchema = z.discriminatedUnion('type', [
+// Child elements (inside content container) - supports nested content, html, and image
+// We need to use lazy evaluation for recursive content support
+let FlexChildElementSchema: z.ZodType<any>;
+let FlexElementContentSchema: z.ZodType<any>;
+
+// Define content schema with lazy reference to child elements (for recursion)
+FlexElementContentSchema = z.lazy(() => z.object({
+    type: z.literal('content').describe("Groups child elements with alignment control. Supports nested content."),
+    elements: fuzzyArray(FlexChildElementSchema).describe("Child elements. Can include nested content containers."),
+    direction: z.enum(['horizontal', 'vertical']).optional().describe("Layout direction. Default: 'vertical'."),
+    valign: VAlignSchema.optional().describe("Vertical alignment. Default: 'center'."),
+    halign: HAlignSchema.optional().describe("Horizontal alignment. Default: 'left'."),
+    gap: SpacingTokenSchema.optional().describe("Gap between children. Default: 'md'."),
+    padding: SpacingTokenSchema.optional().describe("Internal padding. Default: 'lg'."),
+    size: FlexSizeSchema.optional().describe("Size in parent flex container."),
+    class: fuzzyString.optional().describe("Custom CSS class."),
+    style: z.record(z.string()).optional().describe("Custom CSS style object."),
+}));
+
+// Define child element schema with reference to content (for nesting)
+FlexChildElementSchema = z.discriminatedUnion('type', [
     FlexElementTitleSchema,
     FlexElementTextSchema,
     FlexElementBulletsSchema,
@@ -218,23 +249,17 @@ const FlexChildElementSchema = z.discriminatedUnion('type', [
     FlexElementTimelineSchema,
     FlexElementStepperSchema,
     FlexElementSpacerSchema,
+    FlexElementHtmlSchema,
+    FlexElementImageSchema,
+    FlexElementContentSchema,
 ]);
 
-// Content container schema
-const FlexElementContentSchema = z.object({
-    type: z.literal('content').describe("Groups child elements vertically with alignment control."),
-    elements: fuzzyArray(FlexChildElementSchema).describe("Child elements."),
-    valign: VAlignSchema.optional().describe("Vertical alignment. Default: 'center'."),
-    halign: HAlignSchema.optional().describe("Horizontal alignment. Default: 'left'."),
-    gap: SpacingTokenSchema.optional().describe("Gap between children. Default: 'md'."),
-    padding: SpacingTokenSchema.optional().describe("Internal padding. Default: 'lg'."),
-    size: FlexSizeSchema.optional().describe("Size in parent flex container."),
-});
-
 // Top-level flex element (with size property)
+// Note: FlexElementContentSchema already includes size in its definition, so we don't need to extend it
 const FlexElementSchema = z.discriminatedUnion('type', [
     FlexElementImageSchema.extend({ size: FlexSizeSchema.optional() }),
-    FlexElementContentSchema,
+    FlexElementContentSchema, // Already includes size, no need to extend
+    FlexElementHtmlSchema.extend({ size: FlexSizeSchema.optional() }),
     FlexElementTitleSchema.extend({ size: FlexSizeSchema.optional() }),
     FlexElementTextSchema.extend({ size: FlexSizeSchema.optional() }),
     FlexElementBulletsSchema.extend({ size: FlexSizeSchema.optional() }),