yumiamd 0.1.23 → 0.1.24

package/README.md

@@ -1,7 +1,7 @@
 # YumiaMD (`yumiamd`)
 
-> **A Markdown-based presentation language & compiler designed for humans and AI.**  
-> Author slide decks in clean Markdown and compile directly to **100% native, editable PowerPoint (.pptx)** presentations, vector PDFs, and interactive HTML5 slides.
+> **The Design Compiler for Presentations & Visual Documents.**  
+> Author decks with high-level design intent and compile directly to **100% native, editable PowerPoint (.pptx)** presentations, crisp vector PDFs, and interactive HTML5 slides.
 
 [![npm version](https://img.shields.io/npm/v/yumiamd.svg?color=blue)](https://www.npmjs.com/package/yumiamd)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/biagio-scaglia/Yumia-MD/blob/main/LICENSE)
@@ -10,15 +10,18 @@
 
 ## ⚡ Quick Start (Zero Install)
 
-You can run YumiaMD immediately without installing anything via `npx`:
+You can run Yumia immediately without installing anything via `npx`:
 
 ```bash
-# Initialize a starter presentation
-npx yumiamd init my-deck
+# Initialize a starter presentation with custom theme
+npx yumiamd init my-deck --theme corporate
 
-# Launch instant dev server with live-reload
+# Launch instant dev server with live-reload and Visual Inspector
 npx yumiamd dev presentation.yumia.md --open
 
+# Run automated design audit & visual quality score
+npx yumiamd check presentation.yumia.md --optimize
+
 # Compile presentation directly to an editable PowerPoint (.pptx)
 npx yumiamd build presentation.yumia.md --out presentation.pptx
 ```
@@ -47,7 +50,7 @@ pnpm add yumiamd
 
 ---
 
-## 🚀 CLI Commands & AI Tooling
+## 🚀 CLI Commands & Design Tooling
 
 Once installed globally or locally, the `yumia` / `yumiamd` commands are available in your terminal:
 
@@ -55,9 +58,12 @@ Once installed globally or locally, the `yumia` / `yumiamd` commands are availab
 # Initialize a new presentation template (supports --theme and custom color overrides)
 yumia init my-presentation --theme cyberpunk --primary "#FF2E88"
 
-# Start instant live-reload dev server with HTML preview (zero config!)
+# Start instant live-reload dev server with HTML preview & Visual Inspector (zero config!)
 yumia dev presentation.yumia.md --open
 
+# Run design audit, check WCAG contrast, density & compute Visual Quality Score (0-100)
+yumia check presentation.yumia.md --optimize
+
 # Compile to native editable PowerPoint (.pptx)
 yumia build presentation.yumia.md --out dist/presentation.pptx
 
@@ -93,115 +99,77 @@ yumia schema
 ```markdown
 ---
 title: System Architecture & Capabilities
-theme: default
+theme: corporate
 aspectRatio: '16:9'
-author: Biagio Scaglia
+author: Engineering Team
 ---
 
-# High-Performance Presentation Engine
-
-Deterministic compilation from Markdown directly to native PowerPoint slides.
-
-:::badge text="v0.1.15" variant="primary" :::
-:::badge text="Multi-Target" variant="success" :::
+<!-- Slide 1: Hero Cover -->
 
-:::notes
-Opening slide introducing the core architectural vision.
+:::hero title="Next-Generation Cloud Architecture" subtitle="High-throughput distributed compute platform" badge="v2.4 Enterprise" align="center"
 :::
 
 ---
 
-# Architecture & Capabilities
+<!-- Slide 2: Primitives & Visual Intent -->
 
-:::columns ratios="50:50"
-
-:::column
-:::card Core Engine
-
-- 100% Deterministic placement
-- Zero runtime dependencies
-- TypeScript-first architecture
-  :::
-  :::
-
-:::column
-:::card Native PowerPoint Export
-
-- Headings, cards, shapes & notes
-- Fully editable OpenXML objects
-- Compatible with PowerPoint & Google Slides
-  :::
-  :::
+# Core Infrastructure Breakdown
 
+:::callout variant="info" title="Zero Downtime Rollout"
+All worker nodes are upgraded progressively with active health probing.
 :::
 
----
-
-# Native Charts & Data Visuals
-
-:::chart type="bar" title="Execution Speed" labels="Parser, Layout, PDF, PPTX" data="1200, 850, 430, 680"
+:::grid columns=3 gap=20
+:::card "Edge Routing" variant="primary"
 
----
-
-# Roadmap Timeline
+- Global Anycast DNS
+- Sub-5ms SSL Termination
+  :::
 
-:::timeline layout="horizontal"
+:::card "Stateful Compute" variant="success"
 
-- [Phase 1] AST & Compiler Core
-- [Phase 2] Multi-Format Renderers
-- [Phase 3] Rich Directives & Charts
-- [Phase 4] Cloud Deployments
+- Autonomous Actor Runtime
+- Distributed Raft Consensus
   :::
 
-:::step
+:::card "Vector Store" variant="accent"
 
-- 🚀 Seamless deployment via `yumia deploy`
+- Multi-index HNSW Search
+- 10M query/sec throughput
+  :::
   :::
-```
 
 ---
 
-## 💻 JavaScript / TypeScript API
-
-You can also use `yumiamd` programmatically inside your Node.js or TypeScript backend, CLI tools, and AI pipelines:
+<!-- Slide 3: Key Performance Metrics -->
 
-```typescript
-import { compile, parse, YumiaCompiler } from 'yumiamd';
-import fs from 'node:fs';
+# Operational Performance
 
-const markdown = fs.readFileSync('presentation.yumia.md', 'utf-8');
+:::grid columns=3 gap=20
+:::metric value="99.999%" label="Service SLA" change="+0.009%" variant="success" trend="up"
+:::
+:::metric value="1.2ms" label="p99 Latency" change="-35%" variant="primary" trend="down"
+:::
+:::metric value="14.2M" label="Active Invocations" change="+120%" variant="accent" trend="up"
+:::
+:::
 
-// 1. Validate syntax and collect diagnostics
-const compiler = new YumiaCompiler();
-const validation = compiler.validate(markdown);
-console.log(`Valid: ${validation.valid}, Slides: ${validation.slideCount}`);
+---
 
-// 2. Compile directly to PPTX buffer
-const { buffer, errors } = await compile(markdown, { format: 'pptx' });
+<!-- Slide 4: Data Visualization -->
 
-if (errors.length === 0) {
-  fs.writeFileSync('output.pptx', buffer);
-  console.log('✅ Presentation generated successfully!');
-}
+# Global Throughput & Adoption
 
-// 3. Export JSON schema for LLM generation
-const schema = compiler.getSchema();
+:::chart type="bar" title="Monthly API Invocations (Millions)" labels="Jan,Feb,Mar,Apr,May,Jun" data="4.2,6.8,9.1,11.5,13.2,14.2"
+:::
 ```
 
 ---
 
-## ✨ Key Features
-
-- 🎯 **Native Object Principle**: Slides compiled to PowerPoint are **NOT** rasterized screenshot images. Headings, bullet points, cards, tables, charts, badges, and speaker notes are generated as **100% native vector PowerPoint shapes, tables & textboxes** that you can click, re-format, and edit in Microsoft PowerPoint or Google Slides.
-- 📊 **Native Charts & Diagrams**: Full support for `:::chart` (bar, line, pie, doughnut) and `:::mermaid` diagrams across HTML, PDF, and PowerPoint.
-- ⏳ **Timelines, Compare & Steps**: Rich layout directives including `:::timeline`, `:::compare`, and click-to-reveal `:::step` animations.
-- 🚀 **One-Command Cloud Deploy**: Instantly deploy decks to GitHub Pages, Vercel, or static web servers with `yumia deploy`.
-- 📐 **Deterministic Layout Engine**: Exact coordinate calculations for stack, columns, cards, and automatic overflow detection.
-- 🎨 **Semantic Design Tokens**: Built-in themes with typography scales, color palettes, and contrast-safe themes.
-- 🤖 **AI-Friendly Format**: Clean Markdown syntax designed for LLM prompts and agentic workflows, complete with `yumia schema` and `--json` CLI diagnostics.
-
----
+## 🔍 Visual Inspector & Speaker View
 
-## 📄 License
+When previewing in HTML5 (`yumia dev` or `--format html`):
 
-MIT © [Biagio Scaglia](https://github.com/biagio-scaglia)
+- **Visual Inspector**: Press `I` or `Alt+Click` on any element to view computed design tokens, variants, bounding boxes, and source lines.
+- **Dual-Window Speaker View**: Press `S` to open an synchronized second screen with speaker notes, elapsed timer, and next-slide preview.
+- **Overview Mode**: Press `O` or `Esc` to view slide grid thumbnails.

package/dist/bin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runCli
-} from "./chunk-GKERS3TA.js";
+} from "./chunk-FKFINZOL.js";
 
 // src/bin.ts
 var result = await runCli(process.argv);

package/dist/{chunk-GKERS3TA.js → chunk-FKFINZOL.js}

@@ -215,6 +215,24 @@ function createSlot(name, elements) {
     ...elements ? { elements } : {}
   };
 }
+function createHero(title, subtitle, elements, options) {
+  return {
+    type: "hero",
+    title,
+    ...subtitle ? { subtitle } : {},
+    ...elements ? { elements } : {},
+    ...options || {}
+  };
+}
+function createCallout(text, severity = "info", title, icon) {
+  return {
+    type: "callout",
+    text,
+    severity,
+    ...title ? { title } : {},
+    ...icon ? { icon } : {}
+  };
+}
 
 // ../parser/dist/parser.js
 function parseHighlightLines(highlightStr) {
@@ -678,6 +696,36 @@ var DefaultYumiaParser = class {
         const blockBaseLine = directiveStartLine + 1;
         if (directiveName === "notes") {
           notes = blockLines.map((l) => l.trim()).filter(Boolean).join("\n");
+        } else if (directiveName === "hero") {
+          const subMatch = directiveArg.match(/subtitle=['"](.*?)['"]/);
+          const tagMatch = directiveArg.match(/tagline=['"](.*?)['"]/);
+          const alignMatch = directiveArg.match(/align=['"](.*?)['"]/);
+          const emphMatch = directiveArg.match(/emphasis=['"](.*?)['"]/);
+          const densMatch = directiveArg.match(/density=['"](.*?)['"]/);
+          const title = directiveArg.replace(/(?:subtitle|tagline|align|emphasis|density)=['"].*?['"]/g, "").trim().replace(/^['"](.*)['"]$/, "$1") || "Hero";
+          const { elements: heroElements } = this.parseLines(blockLines, blockBaseLine);
+          const el = createHero(title, subMatch ? subMatch[1] : void 0, heroElements.length > 0 ? heroElements : void 0, {
+            tagline: tagMatch ? tagMatch[1] : void 0,
+            align: alignMatch ? alignMatch[1] : void 0,
+            emphasis: emphMatch ? emphMatch[1] : void 0,
+            density: densMatch ? densMatch[1] : void 0
+          });
+          el.loc = {
+            start: { line: directiveStartLine, column: 1 },
+            end: { line: baseLine + i - 1, column: 1 }
+          };
+          elements.push(el);
+        } else if (directiveName === "callout") {
+          const titleMatch = directiveArg.match(/title=['"](.*?)['"]/);
+          const sevMatch = directiveArg.match(/(?:severity|variant)=['"](.*?)['"]/);
+          const iconMatch = directiveArg.match(/icon=['"](.*?)['"]/);
+          const calloutText = blockLines.length > 0 ? blockLines.map((l) => l.trim()).join(" ").trim() : directiveArg.replace(/(?:title|severity|variant|icon)=['"].*?['"]/g, "").trim().replace(/^['"](.*)['"]$/, "$1") || "Note";
+          const el = createCallout(calloutText, sevMatch ? sevMatch[1] : "info", titleMatch ? titleMatch[1] : void 0, iconMatch ? iconMatch[1] : void 0);
+          el.loc = {
+            start: { line: directiveStartLine, column: 1 },
+            end: { line: baseLine + i - 1, column: 1 }
+          };
+          elements.push(el);
         } else if (directiveName === "card") {
           let cardTitle;
           let cardVariant;
@@ -1332,13 +1380,70 @@ var NativeYumiaParser = class {
     const tok = tokens[idx];
     const baseIndent = tok.indent;
     switch (tok.command) {
+      case "hero": {
+        const titleMatch = tok.args.match(/^(?:title=)?["']([^"']+)["']/);
+        const subMatch = tok.args.match(/\bsubtitle=["']([^"']+)["']/);
+        const tagMatch = tok.args.match(/\btagline=["']([^"']+)["']/);
+        const alignMatch = tok.args.match(/\balign=["']?([^"'\s]+)["']?/);
+        const emphMatch = tok.args.match(/\bemphasis=["']?([^"'\s]+)["']?/);
+        const densMatch = tok.args.match(/\bdensity=["']?([^"'\s]+)["']?/);
+        const title = titleMatch ? titleMatch[1] : this.stripQuotes(tok.args) || "Hero";
+        const children = [];
+        let nextIdx = idx + 1;
+        while (nextIdx < tokens.length && tokens[nextIdx].indent > baseIndent) {
+          const childRes = this.parseElement(tokens, nextIdx);
+          if (childRes) {
+            children.push(childRes.element);
+            nextIdx = childRes.nextIdx;
+          } else {
+            nextIdx++;
+          }
+        }
+        const heroEl = createHero(title, subMatch ? subMatch[1] : void 0, children.length > 0 ? children : void 0, {
+          tagline: tagMatch ? tagMatch[1] : void 0,
+          align: alignMatch ? alignMatch[1] : void 0,
+          emphasis: emphMatch ? emphMatch[1] : void 0,
+          density: densMatch ? densMatch[1] : void 0
+        });
+        heroEl.loc = {
+          start: { line: tok.lineNum, column: 1 },
+          end: { line: tok.lineNum, column: tok.text.length }
+        };
+        return { element: heroEl, nextIdx };
+      }
+      case "callout": {
+        const titleMatch = tok.args.match(/title=["']([^"']+)["']/);
+        const sevMatch = tok.args.match(/\b(?:severity|variant)=["']?([^"'\s]+)["']?/);
+        const iconMatch = tok.args.match(/\bicon=["']?([^"'\s]+)["']?/);
+        let text = this.stripQuotes(tok.args.replace(/title=["'][^"']+["']/, "").replace(/(?:severity|variant|icon)=["']?[^"'\s]+["']?/g, ""));
+        let nextIdx = idx + 1;
+        if (!text) {
+          const cLines = [];
+          while (nextIdx < tokens.length && tokens[nextIdx].indent > baseIndent) {
+            cLines.push(tokens[nextIdx].text);
+            nextIdx++;
+          }
+          text = cLines.join(" ");
+        }
+        const calloutEl = createCallout(text || "Note", sevMatch ? sevMatch[1] : "info", titleMatch ? titleMatch[1] : void 0, iconMatch ? iconMatch[1] : void 0);
+        calloutEl.loc = {
+          start: { line: tok.lineNum, column: 1 },
+          end: { line: tok.lineNum, column: tok.text.length }
+        };
+        return { element: calloutEl, nextIdx };
+      }
       case "heading":
       case "h1":
       case "h2":
       case "h3": {
         const level = tok.command === "h1" ? 1 : tok.command === "h2" ? 2 : tok.command === "h3" ? 3 : 1;
         const text = this.stripQuotes(tok.args);
-        return { element: createHeading(text, level), nextIdx: idx + 1 };
+        const el = createHeading(text, level);
+        el.loc = {
+          start: { line: tok.lineNum, column: 1 },
+          end: { line: tok.lineNum, column: tok.text.length }
+        };
+        return { element: el, nextIdx: idx + 1 };
       }
       case "paragraph":
       case "text":
@@ -3304,13 +3409,147 @@ var YumiaLinter = class {
     const errors = issues.filter((i) => i.severity === "error");
     const warnings = issues.filter((i) => i.severity === "warning");
     const infos = issues.filter((i) => i.severity === "info");
+    const score = Math.max(0, Math.min(100, 100 - errors.length * 20 - warnings.length * 5 - infos.length * 1));
+    const suggestions = [];
+    if (warnings.some((w) => w.code === "YUM001")) {
+      suggestions.push("Reduce text length or split overflowing slides using slide breaks.");
+    }
+    if (warnings.some((w) => w.code === "YUM004")) {
+      suggestions.push("High density detected: consider converting dense bullet lists into cards or a multi-column layout.");
+    }
+    if (warnings.some((w) => w.code === "YUM007")) {
+      suggestions.push('Add alt="description" to all images for full accessibility.');
+    }
+    if (warnings.some((w) => w.code === "YUM010")) {
+      suggestions.push("Increase color contrast between text and background to meet WCAG AA (4.5:1).");
+    }
+    if (suggestions.length === 0 && score === 100) {
+      suggestions.push("Design layout and visual hierarchy are optimal.");
+    }
     return {
       passed: options.strict ? errors.length === 0 && warnings.length === 0 : errors.length === 0,
       totalSlides: presentation.slides.length,
       issueCount: issues.length,
+      score,
       errors,
       warnings,
-      infos
+      infos,
+      suggestions
+    };
+  }
+  explain(presentation, options = {}) {
+    const lintReport = this.lint(presentation, options);
+    const themeMeta = presentation.metadata.theme;
+    const themeName = typeof themeMeta === "string" ? themeMeta : themeMeta && typeof themeMeta === "object" && "name" in themeMeta ? themeMeta.name || "custom" : "default";
+    const aspectRatio = presentation.metadata.aspectRatio || "16:9";
+    const composition = {
+      heroSlides: 0,
+      metricSlides: 0,
+      comparisonSlides: 0,
+      chartSlides: 0,
+      timelineSlides: 0,
+      cardSlides: 0,
+      contentSlides: 0
+    };
+    const slideTypes = [];
+    const wordCounts = [];
+    presentation.slides.forEach((slide) => {
+      let type = "content";
+      let hasHero = false;
+      let hasMetric = false;
+      let hasCompare = false;
+      let hasChart = false;
+      let hasTimeline = false;
+      let hasCard = false;
+      const inspectEls = (els) => {
+        for (const el of els) {
+          if (el.type === "hero" || el.purpose === "hero" || el.semanticRole === "hero") {
+            hasHero = true;
+          }
+          if (el.type === "metric")
+            hasMetric = true;
+          if (el.type === "compare")
+            hasCompare = true;
+          if (el.type === "chart")
+            hasChart = true;
+          if (el.type === "timeline")
+            hasTimeline = true;
+          if (el.type === "card" || el.type === "grid" || el.type === "columns")
+            hasCard = true;
+          if (el.type === "card" && el.elements) {
+            inspectEls(el.elements);
+          }
+          if (el.type === "columns") {
+            for (const col of el.columns) {
+              inspectEls(col.elements);
+            }
+          }
+        }
+      };
+      inspectEls(slide.elements);
+      if (hasHero) {
+        type = "hero";
+        composition.heroSlides++;
+      } else if (hasMetric) {
+        type = "metric";
+        composition.metricSlides++;
+      } else if (hasCompare) {
+        type = "comparison";
+        composition.comparisonSlides++;
+      } else if (hasChart) {
+        type = "chart";
+        composition.chartSlides++;
+      } else if (hasTimeline) {
+        type = "timeline";
+        composition.timelineSlides++;
+      } else if (hasCard) {
+        type = "card";
+        composition.cardSlides++;
+      } else {
+        composition.contentSlides++;
+      }
+      slideTypes.push(type);
+      const { wordCount } = this.calculateSlideDensity(slide.elements);
+      wordCounts.push(wordCount);
+    });
+    const diagnostics = [];
+    const avgWords = wordCounts.length > 0 ? wordCounts.reduce((a, b) => a + b, 0) / wordCounts.length : 0;
+    wordCounts.forEach((wc, i) => {
+      if (avgWords > 20 && wc > avgWords * 1.35) {
+        const pct = Math.round((wc - avgWords) / avgWords * 100);
+        diagnostics.push({
+          type: "density",
+          message: `Slide ${i + 1} contains ${pct}% more text than the presentation average.`
+        });
+      }
+    });
+    for (let i = 0; i <= slideTypes.length - 3; i++) {
+      const t1 = slideTypes[i];
+      const t2 = slideTypes[i + 1];
+      const t3 = slideTypes[i + 2];
+      if (t1 && t1 === t2 && t2 === t3 && t1 !== "hero") {
+        diagnostics.push({
+          type: "repetition",
+          message: `Slides ${i + 1}\u2013${i + 3} use identical '${t1}' composition. \u2192 Consider introducing a visual break (e.g. metric, quote, or split compare).`
+        });
+        i += 2;
+      }
+    }
+    const visualHierarchyScore = Math.min(100, Math.max(60, Math.round(100 - lintReport.warnings.filter((w) => w.code === "YUM003" || w.code === "YUM006").length * 10)));
+    return {
+      slidesCount: presentation.slides.length,
+      theme: themeName,
+      aspectRatio,
+      composition,
+      design: {
+        typographyScale: "\u2713 Scaled (Modular 1.25)",
+        contrast: lintReport.warnings.some((w) => w.code === "YUM010") ? "AA Warning" : "AAA / WCAG 2.1",
+        safeArea: "\u2713 Compliant (90px margin buffer)",
+        densityScore: lintReport.score,
+        visualHierarchyScore
+      },
+      diagnostics,
+      suggestions: lintReport.suggestions
     };
   }
   getLuminance(hex) {
@@ -3510,6 +3749,13 @@ var YumiaCompiler = class {
       ...options
     });
   }
+  explain(sourceOrPresentation, options) {
+    const presentation = typeof sourceOrPresentation === "string" ? this.parse(sourceOrPresentation) : sourceOrPresentation;
+    return this.linter.explain(presentation, {
+      ...this.viewport ? { viewport: this.viewport } : {},
+      ...options
+    });
+  }
   layout(presentation, viewport) {
     return this.layoutEngine.computePresentation(presentation, viewport ?? this.viewport);
   }
@@ -3932,6 +4178,12 @@ var PptxRenderer = class {
       case "table":
         this.renderTable(pptxSlide, element, rect, theme);
         break;
+      case "hero":
+        this.renderHero(pptxSlide, pptx, node, scaleX, scaleY, theme, presentation);
+        break;
+      case "callout":
+        this.renderCallout(pptxSlide, pptx, element, rect, theme);
+        break;
       case "image":
         this.renderImage(pptxSlide, element, rect);
         break;
@@ -4398,6 +4650,95 @@ var PptxRenderer = class {
       valign: "middle"
     });
   }
+  renderCallout(pptxSlide, pptx, callout, rect, theme) {
+    const sevColor = this.cleanHexColor(callout.severity === "warning" ? theme.colors.warning || "#f59e0b" : callout.severity === "danger" ? theme.colors.danger || "#ef4444" : callout.severity === "success" ? theme.colors.success || "#10b981" : theme.colors.info || theme.colors.primary);
+    pptxSlide.addShape(pptx.ShapeType.roundRect, {
+      x: rect.x,
+      y: rect.y,
+      w: rect.w,
+      h: rect.h,
+      fill: { color: this.cleanHexColor(theme.colors.surface) },
+      line: { color: sevColor, width: 2 },
+      rectRadius: 0.08
+    });
+    const titleH = callout.title ? 0.35 : 0;
+    if (callout.title) {
+      pptxSlide.addText(callout.title, {
+        x: rect.x + 0.15,
+        y: rect.y + 0.08,
+        w: rect.w - 0.3,
+        h: 0.3,
+        fontSize: 13,
+        bold: true,
+        color: sevColor,
+        fontFace: cleanFontFace(theme.typography.headingFont)
+      });
+    }
+    pptxSlide.addText(callout.text, {
+      x: rect.x + 0.15,
+      y: rect.y + titleH + 0.08,
+      w: rect.w - 0.3,
+      h: rect.h - titleH - 0.16,
+      fontSize: 12,
+      color: this.cleanHexColor(theme.colors.text),
+      fontFace: cleanFontFace(theme.typography.bodyFont),
+      valign: "top"
+    });
+  }
+  renderHero(pptxSlide, pptx, node, scaleX, scaleY, theme, presentation) {
+    const hero = node.element;
+    const rect = {
+      x: node.bounds.x * scaleX,
+      y: node.bounds.y * scaleY,
+      w: node.bounds.width * scaleX,
+      h: node.bounds.height * scaleY
+    };
+    let curY = rect.y;
+    if (hero.tagline) {
+      pptxSlide.addText(hero.tagline.toUpperCase(), {
+        x: rect.x,
+        y: curY,
+        w: rect.w,
+        h: 0.35,
+        fontSize: 11,
+        bold: true,
+        color: this.cleanHexColor(theme.colors.primary),
+        fontFace: cleanFontFace(theme.typography.headingFont),
+        align: hero.align || "center"
+      });
+      curY += 0.4;
+    }
+    pptxSlide.addText(hero.title, {
+      x: rect.x,
+      y: curY,
+      w: rect.w,
+      h: 0.9,
+      fontSize: 32,
+      bold: true,
+      color: this.cleanHexColor(theme.colors.text),
+      fontFace: cleanFontFace(theme.typography.headingFont),
+      align: hero.align || "center"
+    });
+    curY += 0.95;
+    if (hero.subtitle) {
+      pptxSlide.addText(hero.subtitle, {
+        x: rect.x,
+        y: curY,
+        w: rect.w,
+        h: 0.6,
+        fontSize: 16,
+        color: this.cleanHexColor(theme.colors.muted || theme.colors.text),
+        fontFace: cleanFontFace(theme.typography.bodyFont),
+        align: hero.align || "center"
+      });
+      curY += 0.65;
+    }
+    if (node.children) {
+      for (const childNode of node.children) {
+        this.renderNode(pptxSlide, pptx, childNode, scaleX, scaleY, theme, presentation);
+      }
+    }
+  }
   renderChart(pptxSlide, pptx, chart, rect, theme) {
     const series = chart.series || [];
     const labels = chart.labels || [];
@@ -6089,15 +6430,35 @@ var HtmlRenderer = class {
       height: 160% !important;
     }
 
-    .speaker-notes-box {
-      flex: 1;
-      background: #11111a;
-      border-radius: 8px;
-      padding: 16px;
-      font-size: 16px;
-      line-height: 1.7;
-      color: #e2e8f0;
-      overflow-y: auto;
+    /* Visual Inspector Overlay */
+    body.yumia-inspect-active * {
+      cursor: crosshair !important;
+    }
+    .yumia-inspect-highlight {
+      outline: 2px dashed var(--yumia-accent) !important;
+      outline-offset: 3px !important;
+      box-shadow: 0 0 15px var(--yumia-accent) !important;
+    }
+    .yumia-inspector-popup {
+      position: fixed;
+      bottom: 60px;
+      right: 20px;
+      z-index: 9999;
+      background: rgba(10, 15, 30, 0.95);
+      backdrop-filter: blur(16px);
+      border: 1.5px solid var(--yumia-primary);
+      border-radius: 10px;
+      padding: 12px 18px;
+      color: #fff;
+      font-size: 13px;
+      font-family: var(--yumia-font-code);
+      box-shadow: 0 10px 30px rgba(0, 0, 0, 0.7), 0 0 15px rgba(0, 240, 255, 0.25);
+      display: none;
+      max-width: 380px;
+      line-height: 1.5;
+    }
+    .yumia-inspector-popup.open {
+      display: block;
     }
   </style>
 </head>
@@ -6113,10 +6474,12 @@ var HtmlRenderer = class {
       <button class="yumia-btn" id="btn-next" title="Next Slide (\u2192)">\u25B6</button>
       <button class="yumia-btn" id="btn-overview" title="Slide Overview (ESC / O)">\u25A6</button>
       <button class="yumia-btn" id="btn-speaker" title="Speaker View (S)">\u{1F3A4}</button>
+      <button class="yumia-btn" id="btn-inspect" title="Visual Inspector (I / Alt+Click)">\u{1F50D}</button>
       <button class="yumia-btn" id="btn-print" title="Stampa / Salva PDF (Ctrl+P)">\u{1F5A8}\uFE0F</button>
       <button class="yumia-btn" id="btn-notes" title="Toggle Notes (N)">\u{1F4DD}</button>
       <button class="yumia-btn" id="btn-fs" title="Fullscreen (F)">\u26F6</button>
     </div>
+    <div id="inspector-popup" class="yumia-inspector-popup"></div>
 
     <div id="notes-drawer" class="yumia-notes-drawer">
       <div class="yumia-notes-header">
@@ -6423,6 +6786,14 @@ var HtmlRenderer = class {
         prev: function() { goToSlide(currentIdx - 1); },
         toggleNotes: function() { notesDrawer?.classList.toggle('open'); },
         toggleOverview: function() { toggleOverview(); },
+        toggleInspect: function() {
+          const isActive = document.body.classList.toggle('yumia-inspect-active');
+          const popup = document.getElementById('inspector-popup');
+          if (!isActive && popup) {
+            popup.classList.remove('open');
+            document.querySelectorAll('.yumia-inspect-highlight').forEach((el) => el.classList.remove('yumia-inspect-highlight'));
+          }
+        },
         openSpeaker: openSpeakerWindow,
         print: function() { window.print(); },
         toggleFs: function() {
@@ -6437,6 +6808,7 @@ var HtmlRenderer = class {
       document.getElementById('btn-next')?.addEventListener('click', window.deckController.next);
       document.getElementById('btn-prev')?.addEventListener('click', window.deckController.prev);
       document.getElementById('btn-notes')?.addEventListener('click', window.deckController.toggleNotes);
+      document.getElementById('btn-inspect')?.addEventListener('click', window.deckController.toggleInspect);
       document.getElementById('btn-close-notes')?.addEventListener('click', () => {
         notesDrawer?.classList.remove('open');
       });
@@ -6446,6 +6818,30 @@ var HtmlRenderer = class {
       document.getElementById('btn-print')?.addEventListener('click', window.deckController.print);
       document.getElementById('btn-fs')?.addEventListener('click', window.deckController.toggleFs);
 
+      // Interactive Element Inspector Hover & Click
+      document.addEventListener('mouseover', function(e) {
+        if (!document.body.classList.contains('yumia-inspect-active')) return;
+        const target = e.target.closest('[data-yumia-role], .yumia-card, .yumia-metric, .yumia-hero, .yumia-callout, .yumia-grid, .yumia-stack, h1, h2, h3, p, img, pre');
+        if (!target || target.closest('#deck-controls') || target.closest('#inspector-popup')) return;
+
+        document.querySelectorAll('.yumia-inspect-highlight').forEach((el) => el.classList.remove('yumia-inspect-highlight'));
+        target.classList.add('yumia-inspect-highlight');
+
+        const popup = document.getElementById('inspector-popup');
+        if (popup) {
+          const role = target.getAttribute('data-yumia-role') || target.tagName.toLowerCase();
+          const variant = target.getAttribute('data-variant') || target.getAttribute('data-severity') || 'default';
+          const loc = target.getAttribute('data-yumia-loc') || 'slide ' + (currentIdx + 1);
+          popup.innerHTML = \`
+            <div style="color:var(--yumia-primary); font-weight:800; font-size:14px; margin-bottom:4px;">\u{1F50D} \${role.toUpperCase()}</div>
+            <div><strong>Variant:</strong> <span style="color:var(--yumia-accent);">\${variant}</span></div>
+            <div><strong>Location:</strong> \${loc}</div>
+            <div style="margin-top:6px; font-size:11px; color:var(--yumia-muted);">Press 'I' to exit inspector</div>
+          \`;
+          popup.classList.add('open');
+        }
+      });
+
       window.addEventListener('keydown', function(e) {
         if (overviewModal && overviewModal.classList.contains('open')) {
           if (e.key === 'Escape' || e.key.toLowerCase() === 'o') {
@@ -6480,6 +6876,8 @@ var HtmlRenderer = class {
           window.deckController.print();
         } else if (e.key.toLowerCase() === 'n') {
           window.deckController.toggleNotes();
+        } else if (e.key.toLowerCase() === 'i') {
+          window.deckController.toggleInspect();
         } else if (e.key === 'Escape' || e.key.toLowerCase() === 'o') {
           window.deckController.toggleOverview();
         }
@@ -6528,6 +6926,32 @@ var HtmlRenderer = class {
   }
   renderElement(element, theme, presentation) {
     switch (element.type) {
+      case "hero": {
+        const hero = element;
+        const align = hero.align || "center";
+        const tagHtml = hero.tagline ? `<div class="yumia-hero-tagline" style="display:inline-flex; align-items:center; padding:4px 14px; border-radius:999px; background:rgba(255,255,255,0.08); border:1px solid var(--yumia-primary); color:var(--yumia-primary); font-size:0.85rem; font-weight:700; margin-bottom:1rem; letter-spacing:0.06em; text-transform:uppercase;">${this.formatInline(hero.tagline)}</div>` : "";
+        const titleHtml = `<h1 class="yumia-hero-title" style="font-size:clamp(2.4rem, 4.5vw, 4rem); font-weight:800; line-height:1.1; color:var(--yumia-text); margin-bottom:0.8rem;">${this.formatInline(hero.title)}</h1>`;
+        const subHtml = hero.subtitle ? `<p class="yumia-hero-subtitle" style="font-size:clamp(1.1rem, 1.8vw, 1.5rem); color:var(--yumia-muted); max-width:800px; margin-bottom:1.5rem; line-height:1.5;">${this.formatInline(hero.subtitle)}</p>` : "";
+        const innerHtml = hero.elements ? hero.elements.map((child) => this.renderElement(child, theme, presentation)).join("\n") : "";
+        return `
+        <div class="yumia-hero" data-align="${align}" data-yumia-role="hero" style="display:flex; flex-direction:column; align-items:${align === "center" ? "center" : align === "right" ? "flex-end" : "flex-start"}; text-align:${align}; justify-content:center; flex:1; width:100%; margin:auto 0;">
+          ${tagHtml}
+          ${titleHtml}
+          ${subHtml}
+          ${innerHtml ? `<div style="width:100%; margin-top:1rem;">${innerHtml}</div>` : ""}
+        </div>`;
+      }
+      case "callout": {
+        const c = element;
+        const sev = c.severity || "info";
+        const colorVar = sev === "warning" ? "var(--yumia-warning)" : sev === "danger" ? "var(--yumia-danger)" : sev === "success" ? "var(--yumia-success)" : "var(--yumia-info)";
+        const titleHtml = c.title ? `<div style="font-weight:700; font-size:1.05rem; color:${colorVar}; margin-bottom:4px;">${this.formatInline(c.title)}</div>` : "";
+        return `
+        <div class="yumia-callout" data-severity="${sev}" data-yumia-role="callout" style="background:var(--yumia-surface); border-left:4px solid ${colorVar}; border-radius:var(--yumia-radius-card); padding:1rem 1.4rem; margin:0.8rem 0; width:100%;">
+          ${titleHtml}
+          <div style="font-size:0.95rem; color:var(--yumia-text); line-height:1.5;">${this.formatInline(c.text)}</div>
+        </div>`;
+      }
       case "heading": {
         const h = element;
         const tag = `h${Math.min(4, Math.max(1, h.level))}`;
@@ -7005,6 +7429,48 @@ var PdfRenderer = class {
   }
   renderElement(doc, element, x, y, width, theme, presentation) {
     switch (element.type) {
+      case "hero": {
+        const hero = element;
+        let curY = y;
+        if (hero.tagline) {
+          doc.font("Helvetica-Bold").fontSize(11).fillColor(theme.colors.primary);
+          doc.text(this.stripFormatting(hero.tagline).toUpperCase(), x, curY, { width });
+          curY += 20;
+        }
+        doc.font("Helvetica-Bold").fontSize(34).fillColor(theme.colors.text);
+        doc.text(this.stripFormatting(hero.title), x, curY, { width, lineGap: 6 });
+        curY += doc.heightOfString(this.stripFormatting(hero.title), { width }) + 8;
+        if (hero.subtitle) {
+          doc.font("Helvetica").fontSize(16).fillColor(theme.colors.muted || "#888888");
+          doc.text(this.stripFormatting(hero.subtitle), x, curY, { width, lineGap: 4 });
+          curY += doc.heightOfString(this.stripFormatting(hero.subtitle), { width }) + 12;
+        }
+        if (hero.elements) {
+          for (const child of hero.elements) {
+            curY = this.renderElement(doc, child, x, curY, width, theme, presentation) + 10;
+          }
+        }
+        return curY;
+      }
+      case "callout": {
+        const c = element;
+        const sevColor = c.severity === "warning" ? theme.colors.warning || "#f59e0b" : c.severity === "danger" ? theme.colors.danger || "#ef4444" : c.severity === "success" ? theme.colors.success || "#10b981" : theme.colors.info || theme.colors.primary;
+        doc.font("Helvetica").fontSize(12);
+        const textH = doc.heightOfString(this.stripFormatting(c.text), { width: width - 30 });
+        const titleH = c.title ? 20 : 0;
+        const totalH = textH + titleH + 16;
+        doc.roundedRect(x, y, width, totalH, 6).fill(theme.colors.surface || "#151522");
+        doc.rect(x, y, 4, totalH).fill(sevColor);
+        let curY = y + 8;
+        if (c.title) {
+          doc.font("Helvetica-Bold").fontSize(12).fillColor(sevColor);
+          doc.text(this.stripFormatting(c.title), x + 16, curY, { width: width - 26 });
+          curY += 18;
+        }
+        doc.font("Helvetica").fontSize(12).fillColor(theme.colors.text);
+        doc.text(this.stripFormatting(c.text), x + 16, curY, { width: width - 26 });
+        return y + totalH + 8;
+      }
       case "heading": {
         const h = element;
         const fontSize = h.level === 1 ? 28 : h.level === 2 ? 22 : 18;
@@ -7575,7 +8041,7 @@ function startDevServer(filePath, options = {}) {
 // src/cli.ts
 import { mkdirSync, readFileSync as readFileSync2, watch as fsWatch, writeFileSync } from "fs";
 import { basename, dirname, extname, join, resolve as resolve2 } from "path";
-var VERSION = "0.1.23";
+var VERSION = "0.1.24";
 function printHelp() {
   return `
 YumiaMD \u2014 Markdown-based presentation compiler (v${VERSION})
@@ -7584,10 +8050,12 @@ Usage:
   yumia <command> [options] [file]
 
 Commands:
-  init [name]        Scaffold a new YumiaMD presentation project
-  dev <file>         Start live-reload dev server with instant HTML preview
+  init [name]        Scaffold a new Yumia presentation project
+  dev <file>         Start live-reload dev server with instant HTML preview & Inspector
+  check <file>       Run design audit, contrast & density checks (--optimize)
+  explain <file>     Explain document composition, design metrics, and visual rhythm
   watch <file>       Watch presentation file and recompile automatically on save
-  validate <file>    Validate a .yumia.md presentation syntax and structure
+  validate <file>    Validate a presentation syntax and AST structure
   lint <file>        Analyze presentation for layout overflows and accessibility
   inspect <file>     Inspect the AST and geometric layout tree
   schema             Output machine-readable JSON schema for AI agents
@@ -7835,11 +8303,12 @@ ${errorLines.join("\n")}`
       };
     }
   }
-  if (command === "lint") {
+  if (command === "lint" || command === "check") {
     if (!target) {
-      const msg = "Error: Please specify a file to lint.";
+      const msg = "Error: Please specify a file to check or lint.";
       return { exitCode: 1, output: isJson ? JSON.stringify({ error: msg }) : msg };
     }
+    const isOptimize = args.includes("--optimize");
     try {
       const source = readFileSync2(target, "utf-8");
       const compiler = new YumiaCompiler();
@@ -7850,6 +8319,7 @@ ${errorLines.join("\n")}`
           output: JSON.stringify(
             {
               target,
+              optimize: isOptimize,
               ...report
             },
             null,
@@ -7857,10 +8327,15 @@ ${errorLines.join("\n")}`
           )
         };
       }
+      const scoreStr = `Visual Quality Score: ${report.score}/100`;
+      const suggestionLines = report.suggestions && report.suggestions.length > 0 ? `
+Design Suggestions:
+${report.suggestions.map((s) => `  \u2192 ${s}`).join("\n")}` : "";
       if (report.issueCount === 0) {
         return {
           exitCode: 0,
-          output: `\u2713 Yumia Lint: All ${report.totalSlides} slide(s) passed with 0 issues.`
+          output: `\u2713 Yumia Lint / Design Audit: All ${report.totalSlides} slide(s) passed with 0 issues.
+${scoreStr}${suggestionLines}`
         };
       } else {
         const issueLines = [];
@@ -7877,11 +8352,12 @@ ${errorLines.join("\n")}`
         const exitCode = report.passed ? 0 : 1;
         return {
           exitCode,
-          output: `Yumia Lint Report for '${target}':
+          output: `Yumia Design Audit Report for '${target}':
 
 ${issueLines.join("\n")}
 
-${summary}${isStrict && report.warnings.length > 0 ? " (failed due to --strict)" : ""}`
+${summary}
+${scoreStr}${suggestionLines}${isStrict && report.warnings.length > 0 ? "\n(failed due to --strict)" : ""}`
         };
       }
     } catch (err) {
@@ -7891,7 +8367,76 @@ ${summary}${isStrict && report.warnings.length > 0 ? " (failed due to --strict)"
       }
       return {
         exitCode: 1,
-        output: `\u2717 Linting failed: ${msg}`
+        output: `\u2717 Design audit failed: ${msg}`
+      };
+    }
+  }
+  if (command === "explain") {
+    if (!target) {
+      const msg = "Error: Please specify a file to explain.";
+      return { exitCode: 1, output: isJson ? JSON.stringify({ error: msg }) : msg };
+    }
+    try {
+      const source = readFileSync2(target, "utf-8");
+      const compiler = new YumiaCompiler();
+      const exp = compiler.explain(source, { strict: isStrict });
+      if (isJson) {
+        return {
+          exitCode: 0,
+          output: JSON.stringify({ target, ...exp }, null, 2)
+        };
+      }
+      const compLines = [
+        `  Hero slides:       ${exp.composition.heroSlides}`,
+        `  Metric slides:     ${exp.composition.metricSlides}`,
+        `  Comparison slides: ${exp.composition.comparisonSlides}`,
+        `  Chart slides:      ${exp.composition.chartSlides}`,
+        `  Timeline slides:   ${exp.composition.timelineSlides}`,
+        `  Card / Grid:       ${exp.composition.cardSlides}`,
+        `  Content slides:    ${exp.composition.contentSlides}`
+      ];
+      const designLines = [
+        `  Typography scale:  ${exp.design.typographyScale}`,
+        `  Contrast:          ${exp.design.contrast}`,
+        `  Safe area:         ${exp.design.safeArea}`,
+        `  Density score:     ${exp.design.densityScore}/100`,
+        `  Visual hierarchy:  ${exp.design.visualHierarchyScore}/100`
+      ];
+      const diagLines = exp.diagnostics.length > 0 ? exp.diagnostics.map((d) => `  \u26A0 ${d.message}`).join("\n") : "  \u2713 No rhythm or density imbalances detected.";
+      const sugLines = exp.suggestions.length > 0 ? exp.suggestions.map((s) => `  \u2192 ${s}`).join("\n") : "  \u2713 Layout and structure are balanced.";
+      const out = [
+        `Yumia Design Explanation for '${target}'`,
+        `================================================`,
+        `Document Analysis`,
+        `  Slides:            ${exp.slidesCount}`,
+        `  Theme:             ${exp.theme}`,
+        `  Aspect Ratio:      ${exp.aspectRatio}`,
+        ``,
+        `Composition Distribution`,
+        ...compLines,
+        ``,
+        `Design Intelligence`,
+        ...designLines,
+        ``,
+        `Diagnostics & Rhythm`,
+        diagLines,
+        ``,
+        `Design Suggestions`,
+        sugLines,
+        `================================================`
+      ].join("\n");
+      return {
+        exitCode: 0,
+        output: out
+      };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (isJson) {
+        return { exitCode: 1, output: JSON.stringify({ error: msg }) };
+      }
+      return {
+        exitCode: 1,
+        output: `\u2717 Explain failed: ${msg}`
       };
     }
   }
@@ -8123,6 +8668,8 @@ export {
   createStack,
   createComponent,
   createSlot,
+  createHero,
+  createCallout,
   NativeYumiaParser,
   parseNativeYumia,
   parseHighlightLines,

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export * from '@yumiamd/renderer-pptx';
 export * from '@yumiamd/renderer-html';
 export * from '@yumiamd/renderer-pdf';
 
-declare const VERSION = "0.1.23";
+declare const VERSION = "0.1.24";
 declare function printHelp(): string;
 declare function runCli(argv: string[]): Promise<{
     exitCode: number;

package/dist/index.js

@@ -16,6 +16,7 @@ import {
   cleanFontFace,
   corporateTheme,
   createBadge,
+  createCallout,
   createCard,
   createChart,
   createCode,
@@ -26,6 +27,7 @@ import {
   createGrid,
   createGroup,
   createHeading,
+  createHero,
   createIcon,
   createImage,
   createLayoutDirective,
@@ -66,7 +68,7 @@ import {
   terminalTheme,
   tokyoNightTheme,
   validate
-} from "./chunk-GKERS3TA.js";
+} from "./chunk-FKFINZOL.js";
 export {
   DEFAULT_VIEWPORT,
   DefaultLayoutEngine,
@@ -85,6 +87,7 @@ export {
   cleanFontFace,
   corporateTheme,
   createBadge,
+  createCallout,
   createCard,
   createChart,
   createCode,
@@ -95,6 +98,7 @@ export {
   createGrid,
   createGroup,
   createHeading,
+  createHero,
   createIcon,
   createImage,
   createLayoutDirective,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yumiamd",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "description": "Command line interface and compiler for YumiaMD presentations",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,15 +21,15 @@
   },
   "devDependencies": {
     "tsup": "^8.5.1",
-    "@yumiamd/ast": "0.1.23",
-    "@yumiamd/core": "0.1.23",
-    "@yumiamd/parser": "0.1.23",
-    "@yumiamd/layout": "0.1.23",
-    "@yumiamd/renderer": "0.1.23",
-    "@yumiamd/renderer-html": "0.1.23",
-    "@yumiamd/renderer-pdf": "0.1.23",
-    "@yumiamd/renderer-pptx": "0.1.23",
-    "@yumiamd/theme": "0.1.23"
+    "@yumiamd/ast": "0.1.24",
+    "@yumiamd/core": "0.1.24",
+    "@yumiamd/renderer-html": "0.1.24",
+    "@yumiamd/renderer": "0.1.24",
+    "@yumiamd/parser": "0.1.24",
+    "@yumiamd/renderer-pptx": "0.1.24",
+    "@yumiamd/layout": "0.1.24",
+    "@yumiamd/renderer-pdf": "0.1.24",
+    "@yumiamd/theme": "0.1.24"
   },
   "keywords": [
     "yumia",