yumiamd 0.1.5 → 0.1.6

package/README.md

@@ -1,7 +1,7 @@
 # YumiaMD (`yumiamd`)
 
 > **A Markdown-based presentation language & compiler designed for humans and AI.**  
-> Author decks in clean Markdown and compile directly to **100% native, editable PowerPoint (.pptx)** presentations, vector PDFs, and interactive HTML5 slides.
+> Author slide decks in clean Markdown and compile directly to **100% native, editable PowerPoint (.pptx)** presentations, 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,13 +10,13 @@
 
 ## ⚡ Quick Start (Zero Install)
 
-You can run YumiaMD immediately without installing anything:
+You can run YumiaMD immediately without installing anything via `npx`:
 
 ```bash
 # Initialize a starter presentation
 npx yumiamd init my-deck
 
-# Compile presentation to an editable PowerPoint (.pptx)
+# Compile presentation directly to an editable PowerPoint (.pptx)
 npx yumiamd build presentation.yumia.md --out presentation.pptx
 ```
 
@@ -44,7 +44,7 @@ pnpm add yumiamd
 
 ---
 
-## 🚀 CLI Commands
+## 🚀 CLI Commands & AI Tooling
 
 Once installed globally or locally, the `yumia` / `yumiamd` commands are available in your terminal:
 
@@ -52,16 +52,19 @@ Once installed globally or locally, the `yumia` / `yumiamd` commands are availab
 # Initialize a new presentation template
 yumia init my-presentation
 
-# Validate markdown syntax and AST structure
-yumia validate presentation.yumia.md
+# Validate markdown syntax and AST structure (supports --json for CI & AI agents)
+yumia validate presentation.yumia.md --json
 
 # Lint presentation for vertical overflow and layout issues
-yumia lint presentation.yumia.md
+yumia lint presentation.yumia.md --json
 
 # Inspect parsed AST and computed layout bounding boxes
 yumia inspect presentation.yumia.md --layout
 
-# Compile to PowerPoint (.pptx)
+# Export machine-readable JSON schema for LLMs & AI prompt generation
+yumia schema
+
+# Compile to native editable PowerPoint (.pptx)
 yumia build presentation.yumia.md --out dist/presentation.pptx
 ```
 
@@ -71,8 +74,9 @@ yumia build presentation.yumia.md --out dist/presentation.pptx
 
 ```markdown
 ---
-title: System Architecture & Workflow
+title: System Architecture & Capabilities
 theme: default
+aspectRatio: '16:9'
 author: Biagio Scaglia
 ---
 
@@ -109,37 +113,57 @@ Opening slide introducing the core architectural vision.
   :::
 
 :::
+
+---
+
+# Feature Comparison
+
+| Feature                  | YumiaMD                          | Legacy HTML Deck Tools               |
+| :----------------------- | :------------------------------- | :----------------------------------- |
+| **Output Type**          | Native OpenXML Shapes & Text     | Flat rasterized images / screenshots |
+| **Full Editability**     | ✅ 100% Editable in PowerPoint   | ❌ Read-only image slides            |
+| **Deterministic Layout** | ✅ Pixel-exact bounding boxes    | ❌ Browser rendering variance        |
+| **AI / Agent Tooling**   | ✅ Machine-readable schema & CLI | ❌ Complex DOM scraping              |
 ```
 
 ---
 
 ## 💻 JavaScript / TypeScript API
 
-You can also use `yumiamd` programmatically inside your Node.js or TypeScript backend / tools:
+You can also use `yumiamd` programmatically inside your Node.js or TypeScript backend, CLI tools, and AI pipelines:
 
 ```typescript
-import { compile, parse, layoutEngine } from 'yumiamd';
+import { compile, parse, YumiaCompiler } from 'yumiamd';
 import fs from 'node:fs';
 
 const markdown = fs.readFileSync('presentation.yumia.md', 'utf-8');
 
-// 1. Compile directly to PPTX buffer / file
+// 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' });
 
 if (errors.length === 0) {
   fs.writeFileSync('output.pptx', buffer);
   console.log('✅ Presentation generated successfully!');
 }
+
+// 3. Export JSON schema for LLM generation
+const schema = compiler.getSchema();
 ```
 
 ---
 
 ## ✨ Key Features
 
-- 🎯 **Native Object Principle**: Slides compiled to PowerPoint are **NOT** rasterized screenshot images. Headings, bullet points, cards, and speaker notes are generated as **100% native vector PowerPoint shapes & textboxes** that you can click, re-format, and edit in Microsoft PowerPoint or Google Slides.
-- 📐 **Deterministic Layout Engine**: Semantic multi-column grids, flex cards, and auto-spacing.
+- 🎯 **Native Object Principle**: Slides compiled to PowerPoint are **NOT** rasterized screenshot images. Headings, bullet points, cards, tables, 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 Tables & Multicolumn**: Full support for Markdown tables and semantic responsive multi-column layouts with customizable ratio splits (`ratios="50:50"` or `"30:70"`).
+- 📐 **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.
+- 🤖 **AI-Friendly Format**: Clean Markdown syntax designed for LLM prompts and agentic workflows, complete with `yumia schema` and `--json` CLI diagnostics.
 
 ---
 

package/dist/bin.js

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

package/dist/{chunk-MKQASLAK.js → chunk-FHM6V4JH.js}

@@ -103,26 +103,75 @@ function createLayoutDirective(mode, attributes) {
 
 // ../parser/dist/parser.js
 var DefaultYumiaParser = class {
-  parse(source, _options) {
-    const normalized = source.replace(/\r\n/g, "\n");
-    const { metadata, content } = this.extractFrontmatter(normalized);
-    const slideChunks = this.splitSlides(content);
-    const slides = slideChunks.map((chunk) => this.parseSlide(chunk)).filter((slide) => slide.elements.length > 0 || slide.notes !== void 0);
-    return createPresentation(metadata, slides);
+  diagnostics = [];
+  parse(source, options) {
+    this.diagnostics = [];
+    if (!source || typeof source !== "string") {
+      return createPresentation({}, []);
+    }
+    const normalized = source.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    const { metadata, content, lineOffset } = this.extractFrontmatter(normalized);
+    const slideChunks = this.splitSlides(content, lineOffset);
+    const slides = [];
+    for (const chunk of slideChunks) {
+      const slide = this.parseSlide(chunk.content, chunk.startLine);
+      if (slide.elements.length > 0 || slide.notes !== void 0 || slide.background !== void 0) {
+        slides.push(slide);
+      }
+    }
+    const presentation = createPresentation(metadata, slides);
+    if (this.diagnostics.length > 0) {
+      presentation.diagnostics = [...this.diagnostics];
+    }
+    if (options?.strict && this.diagnostics.some((d) => d.severity === "error")) {
+      const firstError = this.diagnostics.find((d) => d.severity === "error");
+      throw new Error(`[Strict Parse Error] ${firstError?.message || "Syntax error"}`);
+    }
+    return presentation;
   }
   extractFrontmatter(source) {
     const trimmed = source.trimStart();
     if (!trimmed.startsWith("---")) {
-      return { metadata: {}, content: source };
+      return { metadata: {}, content: source, lineOffset: 1 };
     }
-    const endIndex = trimmed.indexOf("\n---", 3);
-    if (endIndex === -1) {
-      return { metadata: {}, content: source };
+    const firstLineEnd = trimmed.indexOf("\n");
+    if (firstLineEnd === -1) {
+      return { metadata: {}, content: source, lineOffset: 1 };
     }
-    const frontmatterBlock = trimmed.slice(3, endIndex).trim();
-    const afterFrontmatter = trimmed.slice(endIndex + 4);
-    const metadata = this.parseYamlMetadata(frontmatterBlock);
-    return { metadata, content: afterFrontmatter };
+    const headerLine = trimmed.slice(0, firstLineEnd).trim();
+    if (headerLine !== "---") {
+      return { metadata: {}, content: source, lineOffset: 1 };
+    }
+    const afterHeader = trimmed.slice(firstLineEnd + 1);
+    const lines = afterHeader.split("\n");
+    let closingIndex = -1;
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i]?.trim() === "---") {
+        closingIndex = i;
+        break;
+      }
+    }
+    if (closingIndex === -1) {
+      this.diagnostics.push({
+        code: "UNCLOSED_FRONTMATTER",
+        message: 'Frontmatter block was opened with "---" but never closed.',
+        severity: "warning",
+        loc: {
+          start: { line: 1, column: 1 },
+          end: { line: 1, column: 4 }
+        }
+      });
+      return { metadata: {}, content: source, lineOffset: 1 };
+    }
+    const frontmatterLines = lines.slice(0, closingIndex);
+    const bodyLines = lines.slice(closingIndex + 1);
+    const metadata = this.parseYamlMetadata(frontmatterLines.join("\n"));
+    const lineOffset = closingIndex + 2;
+    return {
+      metadata,
+      content: bodyLines.join("\n"),
+      lineOffset
+    };
   }
   parseYamlMetadata(block) {
     const metadata = {};
@@ -134,8 +183,8 @@ var DefaultYumiaParser = class {
       const colonIndex = trimmed.indexOf(":");
       if (colonIndex > 0) {
         const key = trimmed.slice(0, colonIndex).trim();
-        const value = trimmed.slice(colonIndex + 1).trim();
-        const unquoted = value.replace(/^['"](.*)['"]$/, "$1");
+        const rawVal = trimmed.slice(colonIndex + 1).trim();
+        const unquoted = rawVal.replace(/^['"](.*)['"]$/, "$1");
         metadata[key] = unquoted;
       }
     }
@@ -154,52 +203,79 @@ var DefaultYumiaParser = class {
       result.aspectRatio = metadata["aspectRatio"];
     return result;
   }
-  splitSlides(content) {
+  splitSlides(content, startLineOffset) {
     const lines = content.split("\n");
     const slides = [];
     let currentSlideLines = [];
-    for (const line of lines) {
+    let currentStartLine = startLineOffset;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i] ?? "";
       if (line.trim() === "---") {
-        slides.push(currentSlideLines.join("\n"));
+        slides.push({
+          content: currentSlideLines.join("\n"),
+          startLine: currentStartLine
+        });
         currentSlideLines = [];
+        currentStartLine = startLineOffset + i + 1;
       } else {
         currentSlideLines.push(line);
       }
     }
     if (currentSlideLines.length > 0) {
-      slides.push(currentSlideLines.join("\n"));
+      slides.push({
+        content: currentSlideLines.join("\n"),
+        startLine: currentStartLine
+      });
     }
     return slides;
   }
-  parseSlide(slideContent) {
+  parseSlide(slideContent, startLine) {
     const lines = slideContent.split("\n");
-    const { elements, notes, layout } = this.parseLines(lines);
+    const { elements, notes, layout } = this.parseLines(lines, startLine);
     const slideOptions = {};
     if (notes)
       slideOptions.notes = notes;
     if (layout)
       slideOptions.layout = layout;
+    slideOptions.loc = {
+      start: { line: startLine, column: 1 },
+      end: {
+        line: startLine + lines.length - 1,
+        column: (lines[lines.length - 1]?.length || 0) + 1
+      }
+    };
     return createSlide(elements, slideOptions);
   }
-  parseLines(lines) {
+  parseLines(lines, baseLine) {
     const elements = [];
     let notes;
     let layout;
     let i = 0;
     let currentParagraph = [];
+    let paragraphStartLine = baseLine;
     let currentList = null;
     const flushParagraph = () => {
       if (currentParagraph.length > 0) {
         const text = currentParagraph.join(" ").trim();
         if (text) {
-          elements.push(createParagraph(text));
+          const el = createParagraph(text);
+          el.loc = {
+            start: { line: paragraphStartLine, column: 1 },
+            end: { line: paragraphStartLine + currentParagraph.length - 1, column: 1 }
+          };
+          elements.push(el);
         }
         currentParagraph = [];
       }
     };
     const flushList = () => {
       if (currentList && currentList.items.length > 0) {
-        elements.push(createList(currentList.items, currentList.ordered));
+        const el = createList(currentList.items, currentList.ordered);
+        el.loc = {
+          start: { line: currentList.startLine, column: 1 },
+          end: { line: currentList.startLine + currentList.items.length - 1, column: 1 }
+        };
+        elements.push(el);
         currentList = null;
       }
     };
@@ -210,6 +286,7 @@ var DefaultYumiaParser = class {
     while (i < lines.length) {
       const rawLine = lines[i] ?? "";
       const line = rawLine.trim();
+      const currentLineNum = baseLine + i;
       if (!line) {
         flushAll();
         i++;
@@ -219,24 +296,53 @@ var DefaultYumiaParser = class {
         flushAll();
         const language = line.slice(3).trim() || void 0;
         const codeLines = [];
+        const codeStartLine = currentLineNum;
         i++;
-        while (i < lines.length && !lines[i]?.trim().startsWith("```")) {
+        let closed = false;
+        while (i < lines.length) {
+          const checkLine = lines[i]?.trim() ?? "";
+          if (checkLine.startsWith("```")) {
+            closed = true;
+            i++;
+            break;
+          }
           codeLines.push(lines[i] ?? "");
           i++;
         }
-        i++;
-        elements.push(createCode(codeLines.join("\n"), language));
+        if (!closed) {
+          this.diagnostics.push({
+            code: "UNCLOSED_CODE_BLOCK",
+            message: `Unclosed code block opened at line ${codeStartLine}`,
+            severity: "warning",
+            loc: {
+              start: { line: codeStartLine, column: 1 },
+              end: { line: baseLine + i - 1, column: 1 }
+            }
+          });
+        }
+        const el = createCode(codeLines.join("\n"), language);
+        el.loc = {
+          start: { line: codeStartLine, column: 1 },
+          end: { line: baseLine + i - 1, column: 1 }
+        };
+        elements.push(el);
         continue;
       }
       if (line.startsWith(":::")) {
         flushAll();
         const directiveHeader = line.slice(3).trim();
+        const directiveStartLine = currentLineNum;
         if (directiveHeader.startsWith("layout")) {
           const layoutMatch = directiveHeader.match(/^layout\s*(.*)$/);
           const rawArg = layoutMatch && layoutMatch[1] ? layoutMatch[1].trim() : "default";
           const mode = rawArg.replace(/^['"](.*)['"]$/, "$1");
           layout = mode;
-          elements.push(createLayoutDirective(mode));
+          const el = createLayoutDirective(mode);
+          el.loc = {
+            start: { line: currentLineNum, column: 1 },
+            end: { line: currentLineNum, column: rawLine.length + 1 }
+          };
+          elements.push(el);
           i++;
           continue;
         }
@@ -245,6 +351,7 @@ var DefaultYumiaParser = class {
         const blockLines = [];
         i++;
         let nestedCount = 1;
+        let closed = false;
         while (i < lines.length) {
           const innerLine = lines[i]?.trim() ?? "";
           if (innerLine.startsWith(":::") && innerLine.length > 3) {
@@ -252,6 +359,7 @@ var DefaultYumiaParser = class {
           } else if (innerLine === ":::") {
             nestedCount--;
             if (nestedCount === 0) {
+              closed = true;
               i++;
               break;
             }
@@ -259,36 +367,99 @@ var DefaultYumiaParser = class {
           blockLines.push(lines[i] ?? "");
           i++;
         }
+        if (!closed) {
+          this.diagnostics.push({
+            code: "UNCLOSED_DIRECTIVE",
+            message: `Directive ':::${directiveName}' at line ${directiveStartLine} was never closed with ':::'`,
+            severity: "warning",
+            loc: {
+              start: { line: directiveStartLine, column: 1 },
+              end: { line: baseLine + i - 1, column: 1 }
+            }
+          });
+        }
+        const blockBaseLine = directiveStartLine + 1;
         if (directiveName === "notes") {
           notes = blockLines.map((l) => l.trim()).filter(Boolean).join("\n");
         } else if (directiveName === "card") {
           const title = directiveArg.replace(/^['"](.*)['"]$/, "$1") || void 0;
-          const { elements: cardElements } = this.parseLines(blockLines);
-          elements.push(createCard(cardElements, title));
+          const { elements: cardElements } = this.parseLines(blockLines, blockBaseLine);
+          const el = createCard(cardElements, title);
+          el.loc = {
+            start: { line: directiveStartLine, column: 1 },
+            end: { line: baseLine + i - 1, column: 1 }
+          };
+          elements.push(el);
         } else if (directiveName === "columns") {
           const ratios = directiveArg ? directiveArg.replace(/^ratios=['"]?(.*?)['"]?$/, "$1") : void 0;
-          const columns = this.parseColumnsBlock(blockLines);
-          elements.push(createColumns(columns, ratios));
+          const columns = this.parseColumnsBlock(blockLines, blockBaseLine);
+          const el = createColumns(columns, ratios);
+          el.loc = {
+            start: { line: directiveStartLine, column: 1 },
+            end: { line: baseLine + i - 1, column: 1 }
+          };
+          elements.push(el);
         } else if (directiveName === "quote") {
           const author = directiveArg.replace(/^['"](.*)['"]$/, "$1") || void 0;
           const quoteText = blockLines.map((l) => l.trim()).join(" ").trim();
-          elements.push(createQuote(quoteText, author));
+          const el = createQuote(quoteText, author);
+          el.loc = {
+            start: { line: directiveStartLine, column: 1 },
+            end: { line: baseLine + i - 1, column: 1 }
+          };
+          elements.push(el);
         }
         continue;
       }
+      if (line.startsWith("|") && line.endsWith("|")) {
+        const nextLine = lines[i + 1]?.trim() ?? "";
+        if (nextLine.startsWith("|") && nextLine.includes("---")) {
+          flushAll();
+          const tableStartLine = currentLineNum;
+          const headerCells = line.slice(1, -1).split("|").map((c) => c.trim());
+          const rows = [];
+          i += 2;
+          while (i < lines.length) {
+            const rowLine = lines[i]?.trim() ?? "";
+            if (!rowLine.startsWith("|") || !rowLine.endsWith("|")) {
+              break;
+            }
+            const rowCells = rowLine.slice(1, -1).split("|").map((c) => c.trim());
+            rows.push(rowCells);
+            i++;
+          }
+          const tableEl = createTable(rows, headerCells);
+          tableEl.loc = {
+            start: { line: tableStartLine, column: 1 },
+            end: { line: baseLine + i - 1, column: 1 }
+          };
+          elements.push(tableEl);
+          continue;
+        }
+      }
       const headingMatch = line.match(/^(#{1,6})\s+(.*)$/);
       if (headingMatch && headingMatch[1] && headingMatch[2]) {
         flushAll();
         const level = headingMatch[1].length;
         const text = headingMatch[2].trim();
-        elements.push(createHeading(text, level));
+        const el = createHeading(text, level);
+        el.loc = {
+          start: { line: currentLineNum, column: 1 },
+          end: { line: currentLineNum, column: rawLine.length + 1 }
+        };
+        elements.push(el);
         i++;
         continue;
       }
       if (line.startsWith(">")) {
         flushAll();
         const quoteText = line.replace(/^>\s*/, "").trim();
-        elements.push(createQuote(quoteText));
+        const el = createQuote(quoteText);
+        el.loc = {
+          start: { line: currentLineNum, column: 1 },
+          end: { line: currentLineNum, column: rawLine.length + 1 }
+        };
+        elements.push(el);
         i++;
         continue;
       }
@@ -298,7 +469,12 @@ var DefaultYumiaParser = class {
         const alt = imageMatch[1] || void 0;
         const src = imageMatch[2].trim();
         const caption = imageMatch[3] || void 0;
-        elements.push(createImage(src, alt, caption));
+        const el = createImage(src, alt, caption);
+        el.loc = {
+          start: { line: currentLineNum, column: 1 },
+          end: { line: currentLineNum, column: rawLine.length + 1 }
+        };
+        elements.push(el);
         i++;
         continue;
       }
@@ -307,7 +483,7 @@ var DefaultYumiaParser = class {
         flushParagraph();
         if (!currentList || currentList.ordered) {
           flushList();
-          currentList = { ordered: false, items: [] };
+          currentList = { ordered: false, items: [], startLine: currentLineNum };
         }
         currentList.items.push(unorderMatch[1].trim());
         i++;
@@ -318,13 +494,16 @@ var DefaultYumiaParser = class {
         flushParagraph();
         if (!currentList || !currentList.ordered) {
           flushList();
-          currentList = { ordered: true, items: [] };
+          currentList = { ordered: true, items: [], startLine: currentLineNum };
         }
         currentList.items.push(orderMatch[1].trim());
         i++;
         continue;
       }
       flushList();
+      if (currentParagraph.length === 0) {
+        paragraphStartLine = currentLineNum;
+      }
       currentParagraph.push(line);
       i++;
     }
@@ -335,24 +514,41 @@ var DefaultYumiaParser = class {
       ...layout ? { layout } : {}
     };
   }
-  parseColumnsBlock(lines) {
+  parseColumnsBlock(lines, baseLine) {
     const columns = [];
     let i = 0;
     while (i < lines.length) {
       const line = lines[i]?.trim() ?? "";
+      const currentLineNum = baseLine + i;
       if (line.startsWith(":::column")) {
         const arg = line.slice(9).trim();
         const widthMatch = arg.match(/width=['"]?(.*?)['"]?$/);
         const width = widthMatch && widthMatch[1] ? widthMatch[1] : void 0;
         const colLines = [];
+        const colStartLine = currentLineNum;
         i++;
-        while (i < lines.length && lines[i]?.trim() !== ":::") {
+        let nestedCount = 1;
+        while (i < lines.length) {
+          const innerLine = lines[i]?.trim() ?? "";
+          if (innerLine.startsWith(":::") && innerLine.length > 3) {
+            nestedCount++;
+          } else if (innerLine === ":::") {
+            nestedCount--;
+            if (nestedCount === 0) {
+              i++;
+              break;
+            }
+          }
           colLines.push(lines[i] ?? "");
           i++;
         }
-        i++;
-        const { elements } = this.parseLines(colLines);
-        columns.push(createColumn(elements, width));
+        const { elements } = this.parseLines(colLines, colStartLine + 1);
+        const col = createColumn(elements, width);
+        col.loc = {
+          start: { line: colStartLine, column: 1 },
+          end: { line: baseLine + i - 1, column: 1 }
+        };
+        columns.push(col);
       } else {
         i++;
       }
@@ -370,12 +566,17 @@ var DEFAULT_VIEWPORT = {
   width: 1920,
   height: 1080
 };
+var VIEWPORT_PRESETS = {
+  "16:9": { width: 1920, height: 1080 },
+  "4:3": { width: 1440, height: 1080 },
+  "16:10": { width: 1920, height: 1200 }
+};
 var DefaultLayoutEngine = class {
   computeSlide(slide, viewport = DEFAULT_VIEWPORT, options = {}) {
     const padding = options.padding ?? 64;
     const gap = options.gap ?? 24;
-    const availableWidth = viewport.width - padding * 2;
-    const availableHeight = viewport.height - padding * 2;
+    const availableWidth = Math.max(100, viewport.width - padding * 2);
+    const availableHeight = Math.max(100, viewport.height - padding * 2);
     if (slide.elements.length === 0) {
       return {
         ...slide.id ? { slideId: slide.id } : {},
@@ -396,10 +597,11 @@ var DefaultLayoutEngine = class {
       overflowAmount
     };
   }
-  computePresentation(presentation, viewport = DEFAULT_VIEWPORT, options = {}) {
+  computePresentation(presentation, viewport, options = {}) {
+    const effectiveViewport = viewport || presentation.metadata.aspectRatio && VIEWPORT_PRESETS[presentation.metadata.aspectRatio] || DEFAULT_VIEWPORT;
     return {
-      viewport,
-      slides: presentation.slides.map((slide) => this.computeSlide(slide, viewport, options))
+      viewport: effectiveViewport,
+      slides: presentation.slides.map((slide) => this.computeSlide(slide, effectiveViewport, options))
     };
   }
   layoutElementList(elements, startX, startY, availableWidth, gap) {
@@ -435,6 +637,14 @@ var DefaultLayoutEngine = class {
         const height = this.estimateQuoteHeight(element, width);
         return { element, bounds: { x, y, width, height } };
       }
+      case "table": {
+        const height = this.estimateTableHeight(element);
+        return { element, bounds: { x, y, width, height } };
+      }
+      case "image": {
+        const height = this.estimateImageHeight(element);
+        return { element, bounds: { x, y, width, height } };
+      }
       case "card": {
         return this.layoutCard(element, x, y, width, gap);
       }
@@ -449,7 +659,7 @@ var DefaultLayoutEngine = class {
   }
   layoutCard(element, x, y, width, gap) {
     const cardPadding = 28;
-    const innerWidth = width - cardPadding * 2;
+    const innerWidth = Math.max(10, width - cardPadding * 2);
     const titleHeight = element.title ? 56 : 0;
     const innerStartY = y + cardPadding + titleHeight;
     const { nodes: children, totalHeight: innerHeight } = this.layoutElementList(element.elements, x + cardPadding, innerStartY, innerWidth, gap / 1.5);
@@ -468,7 +678,7 @@ var DefaultLayoutEngine = class {
     }
     const ratios = this.parseRatios(element.ratios, columnCount);
     const totalGap = gap * (columnCount - 1);
-    const usableWidth = width - totalGap;
+    const usableWidth = Math.max(10, width - totalGap);
     let currentX = x;
     const columnNodes = [];
     let maxColumnHeight = 0;
@@ -531,6 +741,17 @@ var DefaultLayoutEngine = class {
     const lines = Math.ceil(quote.text.length / charsPerLine) || 1;
     return lines * 32 + 24;
   }
+  estimateTableHeight(table) {
+    const headerHeight = table.headers && table.headers.length > 0 ? 50 : 0;
+    const rowsHeight = (table.rows ? table.rows.length : 0) * 42;
+    return Math.max(60, headerHeight + rowsHeight + 16);
+  }
+  estimateImageHeight(image) {
+    if (typeof image.height === "number") {
+      return image.height;
+    }
+    return 320;
+  }
 };
 
 // ../theme/dist/default-theme.js
@@ -632,6 +853,18 @@ var YumiaCompiler = class {
   parse(source, options) {
     return this.parser.parse(source, options);
   }
+  validate(source) {
+    const presentation = this.parse(source);
+    const diagnostics = presentation.diagnostics || [];
+    const errors = diagnostics.filter((d) => d.severity === "error");
+    const warnings = diagnostics.filter((d) => d.severity === "warning");
+    return {
+      valid: errors.length === 0,
+      slideCount: presentation.slides.length,
+      errors,
+      warnings
+    };
+  }
   layout(presentation, viewport) {
     return this.layoutEngine.computePresentation(presentation, viewport ?? this.viewport);
   }
@@ -649,10 +882,68 @@ var YumiaCompiler = class {
     const presentation = this.parse(source, options?.parserOptions);
     return this.render(presentation, renderer, options?.renderContext);
   }
+  getSchema() {
+    return {
+      $schema: "http://json-schema.org/draft-07/schema#",
+      title: "YumiaMDPresentation",
+      type: "object",
+      description: "YumiaMD semantic presentation structure and directive definitions",
+      properties: {
+        frontmatter: {
+          type: "object",
+          properties: {
+            title: { type: "string" },
+            subtitle: { type: "string" },
+            author: { type: "string" },
+            date: { type: "string" },
+            theme: { type: "string" },
+            aspectRatio: { enum: ["16:9", "4:3", "16:10"] }
+          }
+        },
+        directives: {
+          type: "object",
+          properties: {
+            columns: {
+              syntax: ':::columns [ratios="50:50"]\\n:::column\\n...\\n:::\\n:::',
+              description: "Multi-column grid layout"
+            },
+            card: {
+              syntax: ":::card [Title]\\n...\\n:::",
+              description: "Visual container card with theme border and background"
+            },
+            notes: {
+              syntax: ":::notes\\nSpeaker notes text\\n:::",
+              description: "Speaker notes attached to slide metadata"
+            },
+            quote: {
+              syntax: ":::quote [Author]\\nQuote text\\n:::",
+              description: "Highlighted quotation with accent bar"
+            },
+            layout: {
+              syntax: ":::layout [mode]",
+              description: "Slide layout mode directive"
+            }
+          }
+        }
+      }
+    };
+  }
 };
 
 // ../renderer-pptx/dist/renderer.js
 import pptxgen from "pptxgenjs";
+var CSS_NAMED_COLORS = {
+  white: "ffffff",
+  black: "000000",
+  red: "ef4444",
+  blue: "3b82f6",
+  green: "22c55e",
+  yellow: "eab308",
+  gray: "64748b",
+  grey: "64748b",
+  slate: "0f172a",
+  transparent: "ffffff"
+};
 var PptxRenderer = class {
   name = "PptxRenderer";
   targetFormat = "pptx";
@@ -668,16 +959,18 @@ var PptxRenderer = class {
     const author = presentation.metadata.author || "YumiaMD";
     pptx.title = title;
     pptx.author = author;
-    const slideWidthInches = 13.333;
+    const is43 = presentation.metadata.aspectRatio === "4:3";
+    const slideWidthInches = is43 ? 10 : 13.333;
     const slideHeightInches = 7.5;
-    pptx.defineLayout({ name: "YUMIA_16_9", width: slideWidthInches, height: slideHeightInches });
-    pptx.layout = "YUMIA_16_9";
-    const pixelViewport = { width: 1920, height: 1080 };
+    const layoutName = is43 ? "YUMIA_4_3" : "YUMIA_16_9";
+    pptx.defineLayout({ name: layoutName, width: slideWidthInches, height: slideHeightInches });
+    pptx.layout = layoutName;
+    const pixelViewport = is43 ? { width: 1440, height: 1080 } : { width: 1920, height: 1080 };
     const scaleX = slideWidthInches / pixelViewport.width;
     const scaleY = slideHeightInches / pixelViewport.height;
     for (const slide of presentation.slides) {
       const pptxSlide = pptx.addSlide();
-      const bgColor = this.cleanHexColor(theme.colors.background);
+      const bgColor = this.cleanHexColor(slide.background?.value || theme.colors.background);
       pptxSlide.background = { color: bgColor };
       const slideLayout = this.layoutEngine.computeSlide(slide, pixelViewport);
       for (const node of slideLayout.nodes) {
@@ -693,7 +986,7 @@ var PptxRenderer = class {
       format: "pptx",
       data: uint8Array,
       slideCount: presentation.slides.length,
-      fileName: `${title.toLowerCase().replace(/\s+/g, "-")}.pptx`
+      fileName: `${title.toLowerCase().replace(/[^a-z0-9]+/g, "-")}.pptx`
     };
   }
   renderNode(pptxSlide, pptx, node, scaleX, scaleY, theme) {
@@ -715,6 +1008,12 @@ var PptxRenderer = class {
       case "quote":
         this.renderQuote(pptxSlide, pptx, element, rect, theme);
         break;
+      case "table":
+        this.renderTable(pptxSlide, element, rect, theme);
+        break;
+      case "image":
+        this.renderImage(pptxSlide, element, rect);
+        break;
       case "card":
         this.renderCard(pptxSlide, pptx, node, scaleX, scaleY, theme);
         break;
@@ -781,6 +1080,75 @@ var PptxRenderer = class {
       margin: 0
     });
   }
+  renderTable(pptxSlide, table, rect, theme) {
+    const tableRows = [];
+    const headerBg = this.cleanHexColor(theme.colors.primary);
+    const borderColor = this.cleanHexColor(theme.colors.border || "#cbd5e1");
+    if (table.headers && table.headers.length > 0) {
+      tableRows.push(table.headers.map((h) => ({
+        text: h,
+        options: {
+          bold: true,
+          color: "ffffff",
+          fill: { color: headerBg },
+          fontSize: 14,
+          align: "center"
+        }
+      })));
+    }
+    if (table.rows) {
+      table.rows.forEach((row, rowIndex) => {
+        const rowBg = rowIndex % 2 === 1 ? "f8fafc" : "ffffff";
+        tableRows.push(row.map((cell) => ({
+          text: cell,
+          options: {
+            color: this.cleanHexColor(theme.colors.text),
+            fill: { color: rowBg },
+            fontSize: 13
+          }
+        })));
+      });
+    }
+    if (tableRows.length > 0) {
+      pptxSlide.addTable(tableRows, {
+        x: rect.x,
+        y: rect.y,
+        w: rect.w,
+        border: { type: "solid", pt: 1, color: borderColor },
+        margin: [4, 8, 4, 8]
+      });
+    }
+  }
+  renderImage(pptxSlide, image, rect) {
+    try {
+      pptxSlide.addImage({
+        path: image.src,
+        x: rect.x,
+        y: rect.y,
+        w: rect.w,
+        h: rect.h
+      });
+    } catch {
+      pptxSlide.addShape("rect", {
+        x: rect.x,
+        y: rect.y,
+        w: rect.w,
+        h: rect.h,
+        fill: { color: "e2e8f0" },
+        line: { color: "94a3b8", width: 1 }
+      });
+      pptxSlide.addText(`[Image: ${image.alt || image.src}]`, {
+        x: rect.x,
+        y: rect.y,
+        w: rect.w,
+        h: rect.h,
+        fontSize: 12,
+        color: "64748b",
+        align: "center",
+        valign: "middle"
+      });
+    }
+  }
   renderCard(pptxSlide, pptx, node, scaleX, scaleY, theme) {
     const card = node.element;
     const rect = this.toInches(node.bounds, scaleX, scaleY);
@@ -892,15 +1260,29 @@ var PptxRenderer = class {
         return 18;
     }
   }
-  cleanHexColor(hex) {
-    return hex.replace("#", "").trim();
+  cleanHexColor(raw) {
+    if (!raw)
+      return "000000";
+    const trimmed = raw.trim().toLowerCase();
+    if (CSS_NAMED_COLORS[trimmed]) {
+      return CSS_NAMED_COLORS[trimmed];
+    }
+    const hexMatch = trimmed.match(/^#?([0-9a-f]{3}|[0-9a-f]{6})$/i);
+    if (hexMatch && hexMatch[1]) {
+      const hex = hexMatch[1];
+      if (hex.length === 3) {
+        return hex[0] + hex[0] + hex[1] + hex[1] + hex[2] + hex[2];
+      }
+      return hex;
+    }
+    return "000000";
   }
 };
 
 // src/cli.ts
 import { mkdirSync, readFileSync, writeFileSync } from "fs";
 import { basename, dirname, extname, join, resolve } from "path";
-var VERSION = "0.1.5";
+var VERSION = "0.1.6";
 function printHelp() {
   return `
 YumiaMD \u2014 Markdown-based presentation compiler (v${VERSION})
@@ -913,11 +1295,13 @@ Commands:
   validate <file>    Validate a .yumia.md presentation syntax and 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
   build <file>       Compile a presentation to editable PowerPoint (.pptx)
 
 Options:
   --out, -o <file>   Specify output file path (default: dist/<name>.pptx)
   --format, -f <fmt> Target output format: pptx (default)
+  --json             Output results formatted as JSON for CI/CD and AI tools
   --layout           Show computed geometric bounding boxes in 'inspect'
   -h, --help         Show this help message
   -v, --version      Show CLI version
@@ -931,8 +1315,17 @@ async function runCli(argv) {
   if (args.includes("-v") || args.includes("--version")) {
     return { exitCode: 0, output: `yumia v${VERSION}` };
   }
-  const command = args[0];
-  const target = args[1];
+  const isJson = args.includes("--json");
+  const nonFlagArgs = args.filter((a) => !a.startsWith("-"));
+  const command = nonFlagArgs[0];
+  const target = nonFlagArgs[1];
+  if (command === "schema") {
+    const compiler = new YumiaCompiler();
+    return {
+      exitCode: 0,
+      output: JSON.stringify(compiler.getSchema(), null, 2)
+    };
+  }
   if (command === "init") {
     const projectName = target || "yumia-deck";
     const projectDir = join(process.cwd(), projectName);
@@ -943,38 +1336,56 @@ async function runCli(argv) {
       const sampleContent = `---
 title: ${projectName}
 theme: default
+aspectRatio: "16:9"
 ---
 
 # ${projectName}
-Presentation authoring with YumiaMD.
+Presentation authoring designed for humans and AI.
 
 :::notes
-Opening slide introducing the project.
+Opening slide introducing the presentation deck.
 :::
 
 ---
 
-# Architecture
+# Architecture & Modularity
 
 :::columns ratios="50:50"
 
 :::column
-:::card Philosophy
-- Plain Markdown source
-- Semantic directives
+:::card Core Pipeline
+- Semantic AST model
+- Markdown + Directive parser
+- 100% Deterministic layout
 :::
 :::
 
 :::column
-:::card Output
-- Native editable PPTX
-- Clean vector PDF
+:::card Native Output
+- Fully editable PowerPoint objects
+- Vector PDF documents
+- Interactive HTML decks
 :::
 :::
 
 :::
 `.trim();
       writeFileSync(join(projectDir, "presentation.yumia.md"), sampleContent, "utf-8");
+      if (isJson) {
+        return {
+          exitCode: 0,
+          output: JSON.stringify(
+            {
+              success: true,
+              project: projectName,
+              path: projectDir,
+              entry: join(projectDir, "presentation.yumia.md")
+            },
+            null,
+            2
+          )
+        };
+      }
       return {
         exitCode: 0,
         output: `\u2713 Created presentation project '${projectName}' at ./${projectName}
@@ -982,33 +1393,62 @@ Opening slide introducing the project.
   Then compile with: yumia build ./${projectName}/presentation.yumia.md`
       };
     } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (isJson) {
+        return { exitCode: 1, output: JSON.stringify({ success: false, error: msg }, null, 2) };
+      }
       return {
         exitCode: 1,
-        output: `\u2717 Initialization failed: ${err instanceof Error ? err.message : String(err)}`
+        output: `\u2717 Initialization failed: ${msg}`
       };
     }
   }
   if (command === "validate") {
     if (!target) {
-      return { exitCode: 1, output: "Error: Please specify a file to validate." };
+      const msg = "Error: Please specify a file to validate.";
+      return { exitCode: 1, output: isJson ? JSON.stringify({ error: msg }) : msg };
     }
     try {
       const source = readFileSync(target, "utf-8");
-      const presentation = parseYumia(source);
-      return {
-        exitCode: 0,
-        output: `\u2713 Presentation '${target}' is valid. Detected ${presentation.slides.length} slide(s).`
-      };
+      const compiler = new YumiaCompiler();
+      const validation = compiler.validate(source);
+      if (isJson) {
+        return {
+          exitCode: validation.valid ? 0 : 1,
+          output: JSON.stringify(validation, null, 2)
+        };
+      }
+      if (validation.valid) {
+        const warnInfo = validation.warnings.length > 0 ? ` (${validation.warnings.length} warning(s))` : "";
+        return {
+          exitCode: 0,
+          output: `\u2713 Presentation '${target}' is valid. Detected ${validation.slideCount} slide(s)${warnInfo}.`
+        };
+      } else {
+        const errorLines = validation.errors.map(
+          (e) => `  - [Line ${e.loc?.start.line || "?"}] ${e.message}`
+        );
+        return {
+          exitCode: 1,
+          output: `\u2717 Validation failed with ${validation.errors.length} error(s):
+${errorLines.join("\n")}`
+        };
+      }
     } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (isJson) {
+        return { exitCode: 1, output: JSON.stringify({ valid: false, error: msg }) };
+      }
       return {
         exitCode: 1,
-        output: `\u2717 Validation failed: ${err instanceof Error ? err.message : String(err)}`
+        output: `\u2717 Validation failed: ${msg}`
       };
     }
   }
   if (command === "lint") {
     if (!target) {
-      return { exitCode: 1, output: "Error: Please specify a file to lint." };
+      const msg = "Error: Please specify a file to lint.";
+      return { exitCode: 1, output: isJson ? JSON.stringify({ error: msg }) : msg };
     }
     try {
       const source = readFileSync(target, "utf-8");
@@ -1019,40 +1459,67 @@ Opening slide introducing the project.
       layout.slides.forEach((slideResult, index) => {
         const slideNum = index + 1;
         if (slideResult.overflow) {
-          issues.push(
-            `\u26A0 Slide ${slideNum}: Content exceeds slide height by ~${Math.round(slideResult.overflowAmount || 0)}px`
-          );
+          issues.push({
+            slide: slideNum,
+            type: "overflow",
+            message: `Content exceeds slide height by ~${Math.round(slideResult.overflowAmount || 0)}px`
+          });
         }
         const slide = presentation.slides[index];
         if (slide.elements.length === 0) {
-          issues.push(`\u26A0 Slide ${slideNum}: Slide has no content elements.`);
+          issues.push({
+            slide: slideNum,
+            type: "empty",
+            message: "Slide has no content elements."
+          });
         }
       });
+      if (isJson) {
+        return {
+          exitCode: 0,
+          output: JSON.stringify(
+            {
+              target,
+              passed: issues.length === 0,
+              slideCount: presentation.slides.length,
+              issues
+            },
+            null,
+            2
+          )
+        };
+      }
       if (issues.length === 0) {
         return {
           exitCode: 0,
           output: `\u2713 Yumia Lint: All ${presentation.slides.length} slide(s) passed with 0 issues.`
         };
       } else {
+        const formatted = issues.map((i) => `\u26A0 Slide ${i.slide}: ${i.message}`).join("\n");
         return {
           exitCode: 0,
           output: `Yumia Lint Report for '${target}':
 
-${issues.join("\n")}
+${formatted}
 
 Found ${issues.length} warning(s).`
         };
       }
     } 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 Linting failed: ${err instanceof Error ? err.message : String(err)}`
+        output: `\u2717 Linting failed: ${msg}`
       };
     }
   }
   if (command === "inspect") {
     if (!target) {
-      return { exitCode: 1, output: "Error: Please specify a file to inspect." };
+      const msg = "Error: Please specify a file to inspect.";
+      return { exitCode: 1, output: isJson ? JSON.stringify({ error: msg }) : msg };
     }
     try {
       const source = readFileSync(target, "utf-8");
@@ -1070,15 +1537,20 @@ Found ${issues.length} warning(s).`
         output: JSON.stringify(presentation, null, 2)
       };
     } 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 Inspection failed: ${err instanceof Error ? err.message : String(err)}`
+        output: `\u2717 Inspection failed: ${msg}`
       };
     }
   }
   if (command === "build") {
     if (!target) {
-      return { exitCode: 1, output: "Error: Please specify a presentation file to build." };
+      const msg = "Error: Please specify a presentation file to build.";
+      return { exitCode: 1, output: isJson ? JSON.stringify({ error: msg }) : msg };
     }
     try {
       const resolvedInput = resolve(process.cwd(), target);
@@ -1097,14 +1569,34 @@ Found ${issues.length} warning(s).`
       const result = await compiler.compile(source, renderer);
       const buffer = result.data instanceof Uint8Array ? Buffer.from(result.data) : Buffer.from(new Uint8Array(result.data));
       writeFileSync(outputPath, buffer);
+      if (isJson) {
+        return {
+          exitCode: 0,
+          output: JSON.stringify(
+            {
+              success: true,
+              source: target,
+              output: outputPath,
+              slideCount: result.slideCount,
+              format: result.format
+            },
+            null,
+            2
+          )
+        };
+      }
       return {
         exitCode: 0,
         output: `\u2713 Successfully compiled '${target}' \u2794 '${outputPath}' (${result.slideCount} native editable slides)`
       };
     } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (isJson) {
+        return { exitCode: 1, output: JSON.stringify({ success: false, error: msg }) };
+      }
       return {
         exitCode: 1,
-        output: `\u2717 Build failed: ${err instanceof Error ? err.message : String(err)}`
+        output: `\u2717 Build failed: ${msg}`
       };
     }
   }
@@ -1132,6 +1624,7 @@ export {
   DefaultYumiaParser,
   parseYumia,
   DEFAULT_VIEWPORT,
+  VIEWPORT_PRESETS,
   DefaultLayoutEngine,
   defaultTheme,
   createTheme,

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export * from '@yumiamd/layout';
 export * from '@yumiamd/renderer';
 export * from '@yumiamd/renderer-pptx';
 
-declare const VERSION = "0.1.5";
+declare const VERSION = "0.1.6";
 declare function printHelp(): string;
 declare function runCli(argv: string[]): Promise<{
     exitCode: number;

package/dist/index.js

@@ -4,6 +4,7 @@ import {
   DefaultYumiaParser,
   PptxRenderer,
   VERSION,
+  VIEWPORT_PRESETS,
   YumiaCompiler,
   createCard,
   createCode,
@@ -24,13 +25,14 @@ import {
   parseYumia,
   printHelp,
   runCli
-} from "./chunk-MKQASLAK.js";
+} from "./chunk-FHM6V4JH.js";
 export {
   DEFAULT_VIEWPORT,
   DefaultLayoutEngine,
   DefaultYumiaParser,
   PptxRenderer,
   VERSION,
+  VIEWPORT_PRESETS,
   YumiaCompiler,
   createCard,
   createCode,

package/package.json

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