@thanh01.pmt/presentation-kit 0.2.10 → 0.2.12

package/dist/ai/index.js

@@ -1,4 +1,4 @@
-import { SLIDE_LAYOUT_PRESETS, getSlideLayoutPresetsByCategory, getSlideLayoutPresetById, serializeLayoutToComment, updateSlideLayoutInMarkdown, splitMarkdownSlides } from '../chunk-V6X7D44H.js';
+import { SLIDE_LAYOUT_PRESETS, getSlideLayoutPresetsByCategory, getSlideLayoutPresetById, serializeLayoutToComment, updateSlideLayoutInMarkdown, splitMarkdownSlides, HTML_SLIDE_PRESETS, HTML_THEMES, compileHtmlDeck } from '../chunk-3VGV5KYZ.js';
 import { z } from 'zod';
 
 var listSlidePresetsSchema = z.object({
@@ -410,8 +410,504 @@ When a precise coordinate layout is specified, include the clean YAML block at t
       pos: [670, 150, 530, 510]
 -->
 \`\`\`
+
+---
+
+## 7. STEP REVEAL & PROGRESSIVE DISCLOSURE
+When presenting lists, comparisons, or multi-phase concepts, support sequential reveals:
+- Annotate lists or elements with \`<!-- v-click -->\` or apply class \`.step-reveal\` / \`[data-step]\`.
+- Clicking or pressing forward arrow reveals items sequentially before transitioning to the next slide.
+- Keep list items concise (< 15 words) to maintain visual rhythm during progressive steps.
 `;
+var validateSlideDeckSchema = z.object({
+  format: z.enum(["auto", "html", "markdown"]).default("auto").describe('Deck format to validate: "html", "markdown", or "auto"'),
+  markdown: z.string().optional().describe("Raw Markdown / Marp slide presentation content"),
+  htmlDeck: z.object({
+    title: z.string().optional(),
+    subtitle: z.string().optional(),
+    theme: z.string().optional(),
+    slides: z.array(z.object({
+      layoutId: z.string(),
+      slots: z.record(z.any()),
+      notes: z.string().optional()
+    })).optional()
+  }).optional().describe("Structured HTML deck data matching HtmlDeckData"),
+  strict: z.boolean().default(false).describe("If true, warnings cause valid to be false")
+});
+function countWords(str) {
+  if (!str) return 0;
+  return str.trim().split(/\s+/).filter(Boolean).length;
+}
+function validateHtmlSlideDeck(deck, strict = false) {
+  const issues = [];
+  const suggestions = [];
+  const slides = deck.slides || [];
+  const slideCount = slides.length;
+  if (slideCount === 0) {
+    return {
+      success: false,
+      valid: false,
+      score: 0,
+      format: "html",
+      slideCount: 0,
+      notesCoveragePercent: 0,
+      issues: [{
+        slideIndex: 0,
+        severity: "error",
+        rule: "EMPTY_DECK",
+        message: "Presentation deck contains no slides."
+      }],
+      suggestions: ["Add at least one slide (e.g. hero-cover) to the deck."]
+    };
+  }
+  let notesCount = 0;
+  let hasCover = false;
+  let hasQuiz = false;
+  let hasSummary = false;
+  slides.forEach((slide, idx) => {
+    const slideNumber = idx + 1;
+    const layoutId = slide.layoutId;
+    const preset = HTML_SLIDE_PRESETS[layoutId];
+    if (!preset) {
+      issues.push({
+        slideIndex: slideNumber,
+        severity: "error",
+        rule: "INVALID_LAYOUT_PRESET",
+        message: `Unknown layoutId "${slide.layoutId}". Available presets: ${Object.keys(HTML_SLIDE_PRESETS).join(", ")}`
+      });
+      return;
+    }
+    if (preset.category === "cover" && idx === 0) hasCover = true;
+    if (preset.id === "checkpoint-quiz") hasQuiz = true;
+    if (preset.id === "summary-takeaways") hasSummary = true;
+    for (const slotDef of preset.slots) {
+      if (slotDef.required) {
+        const val = slide.slots?.[slotDef.name];
+        if (val === void 0 || val === null || typeof val === "string" && val.trim() === "") {
+          issues.push({
+            slideIndex: slideNumber,
+            severity: "error",
+            rule: "MISSING_REQUIRED_SLOT",
+            message: `Slide ${slideNumber} (${layoutId}) is missing required slot "${slotDef.name}" (${slotDef.label}).`
+          });
+        }
+      }
+    }
+    const slots = slide.slots || {};
+    for (const [key, val] of Object.entries(slots)) {
+      if (typeof val === "string") {
+        const words = countWords(val);
+        if (key !== "code" && words > 50) {
+          issues.push({
+            slideIndex: slideNumber,
+            severity: "warning",
+            rule: "ZERO_SCROLL_WORD_BUDGET",
+            message: `Slot "${key}" on slide ${slideNumber} has ${words} words. Recommended max is 35-40 words to prevent vertical scrolling.`
+          });
+        }
+      } else if (Array.isArray(val)) {
+        if (val.length > 5) {
+          issues.push({
+            slideIndex: slideNumber,
+            severity: "warning",
+            rule: "EXCESSIVE_LIST_ITEMS",
+            message: `List slot "${key}" on slide ${slideNumber} has ${val.length} items. Keep to 3-4 items for optimal readability.`
+          });
+        }
+        val.forEach((item, itemIdx) => {
+          if (typeof item === "string") {
+            const w = countWords(item);
+            if (w > 20) {
+              issues.push({
+                slideIndex: slideNumber,
+                severity: "warning",
+                rule: "BULLET_WORD_BUDGET",
+                message: `Bullet #${itemIdx + 1} in "${key}" on slide ${slideNumber} is ${w} words. Keep bullet points concise (< 15 words).`
+              });
+            }
+          }
+        });
+      }
+    }
+    if (slide.notes && slide.notes.trim().length > 0) {
+      notesCount++;
+      const notes = slide.notes.trim();
+      const hasQuestion = notes.includes("?") || /cold-?call|question/i.test(notes);
+      const hasTip = /scaffold|tip|analogy|hint/i.test(notes);
+      if (!hasQuestion || !hasTip) {
+        issues.push({
+          slideIndex: slideNumber,
+          severity: "warning",
+          rule: "INCOMPLETE_PRESENTER_NOTES",
+          message: `Presenter notes for slide ${slideNumber} should follow the 3-part contract: Talk Track, Cold-Call Question, and Scaffolding Tip.`
+        });
+      }
+    } else {
+      issues.push({
+        slideIndex: slideNumber,
+        severity: "error",
+        rule: "MISSING_PRESENTER_NOTES",
+        message: `Slide ${slideNumber} is missing presenter notes. 100% presenter notes coverage is required.`
+      });
+    }
+  });
+  if (slideCount >= 3 && !hasCover) {
+    issues.push({
+      slideIndex: 1,
+      severity: "warning",
+      rule: "MISSING_HERO_COVER",
+      message: 'Slide 1 should ideally use the "hero-cover" layout preset to introduce the topic and objectives.'
+    });
+  }
+  if (slideCount >= 6 && !hasQuiz) {
+    issues.push({
+      slideIndex: Math.floor(slideCount / 2),
+      severity: "warning",
+      rule: "MISSING_FORMATIVE_CHECKPOINT",
+      message: `Deck has ${slideCount} slides but lacks a "checkpoint-quiz" for mid-lesson active recall.`
+    });
+  }
+  if (slideCount >= 4 && !hasSummary) {
+    issues.push({
+      slideIndex: slideCount,
+      severity: "warning",
+      rule: "MISSING_SUMMARY_SLIDE",
+      message: 'Deck lacks a "summary-takeaways" wrap-up slide at the conclusion of the presentation.'
+    });
+  }
+  const notesCoveragePercent = Math.round(notesCount / slideCount * 100);
+  const errorCount = issues.filter((i) => i.severity === "error").length;
+  const warningCount = issues.filter((i) => i.severity === "warning").length;
+  let score = 100 - errorCount * 15 - warningCount * 4;
+  score = Math.max(0, Math.min(100, score));
+  const valid = strict ? issues.length === 0 : errorCount === 0;
+  if (errorCount > 0) {
+    suggestions.push(`Resolve ${errorCount} blocking error(s) before presenting or publishing.`);
+  }
+  if (notesCoveragePercent < 100) {
+    suggestions.push(`Increase presenter notes coverage from ${notesCoveragePercent}% to 100%.`);
+  }
+  if (!hasQuiz && slideCount >= 6) {
+    suggestions.push("Add an interactive checkpoint quiz around the midpoint of the lesson.");
+  }
+  return {
+    success: true,
+    valid,
+    score,
+    format: "html",
+    slideCount,
+    notesCoveragePercent,
+    issues,
+    suggestions
+  };
+}
+function validateMarkdownSlideDeck(markdown, strict = false) {
+  const issues = [];
+  const suggestions = [];
+  if (!markdown || markdown.trim().length === 0) {
+    return {
+      success: false,
+      valid: false,
+      score: 0,
+      format: "markdown",
+      slideCount: 0,
+      notesCoveragePercent: 0,
+      issues: [{
+        slideIndex: 0,
+        severity: "error",
+        rule: "EMPTY_MARKDOWN",
+        message: "Markdown slide presentation is empty."
+      }],
+      suggestions: ['Provide Markdown slide content delimited by "---".']
+    };
+  }
+  const rawSlides = markdown.split(/\n---\n/);
+  const slideCount = rawSlides.length;
+  let notesCount = 0;
+  rawSlides.forEach((slideContent, idx) => {
+    const slideNumber = idx + 1;
+    const trimmed = slideContent.trim();
+    const notesMatch = trimmed.match(/<!--\s*(?:Presenter Notes:?[\s\S]*?|[\s\S]*?notes[\s\S]*?)-->/i);
+    if (notesMatch) {
+      notesCount++;
+      const noteBody = notesMatch[0];
+      const hasQuestion = noteBody.includes("?") || /cold-?call|question/i.test(noteBody);
+      const hasTip = /scaffold|tip|analogy|hint/i.test(noteBody);
+      if (!hasQuestion || !hasTip) {
+        issues.push({
+          slideIndex: slideNumber,
+          severity: "warning",
+          rule: "INCOMPLETE_PRESENTER_NOTES",
+          message: `Presenter notes on slide ${slideNumber} should include Talk Track, a Cold-Call Question, and a Scaffolding Tip.`
+        });
+      }
+    } else {
+      issues.push({
+        slideIndex: slideNumber,
+        severity: "error",
+        rule: "MISSING_PRESENTER_NOTES",
+        message: `Slide ${slideNumber} is missing presenter notes comments (<!-- Presenter Notes: ... -->).`
+      });
+    }
+    const codeBlockTokens = trimmed.match(/```/g);
+    if (codeBlockTokens && codeBlockTokens.length % 2 !== 0) {
+      issues.push({
+        slideIndex: slideNumber,
+        severity: "error",
+        rule: "UNCLOSED_CODE_BLOCK",
+        message: `Slide ${slideNumber} contains unclosed code fence backticks (\`\`\`).`
+      });
+    }
+    const cleanBody = trimmed.replace(/<!--[\s\S]*?-->/g, "").replace(/```[\s\S]*?```/g, "");
+    const words = countWords(cleanBody);
+    if (words > 100) {
+      issues.push({
+        slideIndex: slideNumber,
+        severity: "warning",
+        rule: "ZERO_SCROLL_WORD_BUDGET",
+        message: `Slide ${slideNumber} body has ${words} words. Keep within 40-70 words per slide to prevent vertical scroll.`
+      });
+    }
+  });
+  const notesCoveragePercent = Math.round(notesCount / slideCount * 100);
+  const errorCount = issues.filter((i) => i.severity === "error").length;
+  const warningCount = issues.filter((i) => i.severity === "warning").length;
+  let score = 100 - errorCount * 15 - warningCount * 4;
+  score = Math.max(0, Math.min(100, score));
+  const valid = strict ? issues.length === 0 : errorCount === 0;
+  return {
+    success: true,
+    valid,
+    score,
+    format: "markdown",
+    slideCount,
+    notesCoveragePercent,
+    issues,
+    suggestions
+  };
+}
+function executeValidateSlideDeck(input) {
+  const format = input.format || "auto";
+  if (format === "html" || format === "auto" && input.htmlDeck && input.htmlDeck.slides) {
+    return validateHtmlSlideDeck(input.htmlDeck || { slides: [] }, input.strict);
+  }
+  if (format === "markdown" || format === "auto" && input.markdown) {
+    return validateMarkdownSlideDeck(input.markdown || "", input.strict);
+  }
+  return {
+    success: false,
+    valid: false,
+    score: 0,
+    format: "html",
+    slideCount: 0,
+    notesCoveragePercent: 0,
+    issues: [{
+      slideIndex: 0,
+      severity: "error",
+      rule: "INVALID_INPUT",
+      message: "Neither htmlDeck nor markdown was supplied for slide deck validation."
+    }],
+    suggestions: ['Provide either "htmlDeck" object or "markdown" string in the validation parameters.']
+  };
+}
+var handleValidateSlideDeck = executeValidateSlideDeck;
+var listHtmlSlidePresetsSchema = z.object({
+  category: z.enum(["all", "cover", "content", "split", "grid", "timeline", "callout", "assessment"]).optional().describe("Optional category filter for HTML layout presets")
+});
+var htmlSlideSlotDataSchema = z.object({
+  layoutId: z.enum([
+    "hero-cover",
+    "split-concept-code",
+    "two-columns-compare",
+    "three-cards-grid",
+    "timeline-steps",
+    "metric-callout",
+    "checkpoint-quiz",
+    "summary-takeaways"
+  ]).describe("Layout preset ID"),
+  slots: z.record(z.any()).describe("Key-value slot dictionary matching the chosen layout requirements"),
+  notes: z.string().optional().describe("Presenter speech track or teaching guide for this slide")
+});
+var generateHtmlDeckSchema = z.object({
+  title: z.string().describe("Title of the presentation / lesson deck"),
+  subtitle: z.string().optional().describe("Subtitle or target audience / grade"),
+  theme: z.enum(["blue-professional", "editorial-forest", "cobalt-grid", "studio", "monochrome"]).default("blue-professional").describe("Visual theme palette"),
+  slides: z.array(htmlSlideSlotDataSchema).min(1).describe("List of slides with designated layouts and slot contents")
+});
+var createHtmlSlideSchema = z.object({
+  layoutId: z.enum([
+    "hero-cover",
+    "split-concept-code",
+    "two-columns-compare",
+    "three-cards-grid",
+    "timeline-steps",
+    "metric-callout",
+    "checkpoint-quiz",
+    "summary-takeaways"
+  ]).describe("Layout preset ID"),
+  slots: z.record(z.any()).describe("Key-value content slots"),
+  notes: z.string().optional().describe("Speaker talk track or question prompts")
+});
+
+// src/ai/html/prompt.ts
+var SLIDE_HTML_PROMPT_CONTRACT = `
+# \u{1F3A8} HTML SLIDE ENGINE \u2014 AGENT GENERATION CONTRACT
+
+You are an expert Presentation Designer and Curriculum Architect producing professional, high-impact slide decks.
+Instead of generating free-form HTML or brittle Markdown hacks, you MUST fill structured content into pre-tested **Layout Presets**.
+
+## Available Layout Presets & Required Slots:
+
+1. **hero-cover** (Cover / Title Slide)
+   - \`tag\` (string): e.g. "Unit 01 \xB7 Lesson 02"
+   - \`title\` (string): Main bold headline
+   - \`subtitle\` (string): Subtitle or 1-sentence learning objective
+   - \`author\` (string): Instructor / Organization
+   - \`date\` (string): Course term or date
+
+2. **split-concept-code** (Theory + Code Snippet)
+   - \`tag\` (string): Section topic tag
+   - \`title\` (string): Topic heading
+   - \`points\` (string[]): 3 to 4 concise bullet takeaways
+   - \`code\` (string): Executable source code
+   - \`language\` (string): Language name (e.g. "python", "typescript", "swift")
+   - \`codeNote\` (string, optional): One-line hint or execution output
+
+3. **two-columns-compare** (Comparison / Pros vs Cons)
+   - \`tag\` (string): Topic tag
+   - \`title\` (string): Headline
+   - \`col1Title\` (string): e.g. "Synchronous I/O"
+   - \`col1Items\` (string[]): 3 to 4 points
+   - \`col2Title\` (string): e.g. "Asynchronous I/O"
+   - \`col2Items\` (string[]): 3 to 4 points
+
+4. **three-cards-grid** (3 Core Pillars / Architecture)
+   - \`tag\` (string): e.g. "Core Principles"
+   - \`title\` (string): Overview headline
+   - \`cards\` (array of objects): Exactly 3 cards:
+     - \`badge\`: e.g. "01", "LAYER 1"
+     - \`title\`: Card headline
+     - \`desc\`: 1-2 sentence description
+     - \`footer\` (optional): Key takeaway
+
+5. **timeline-steps** (Algorithm / Execution Pipeline)
+   - \`tag\` (string): e.g. "Workflow"
+   - \`title\` (string): Headline
+   - \`steps\` (array of objects): 3 to 5 steps:
+     - \`stepNum\` (number/string): 1, 2, 3...
+     - \`title\`: Step name
+     - \`desc\`: What happens at this step
+
+6. **metric-callout** (Key Theorem / Benchmark Statistic)
+   - \`tag\` (string): e.g. "Time Complexity"
+   - \`metric\` (string): Big stat (e.g. "O(log N)", "99.99%", "10x")
+   - \`metricLabel\` (string): e.g. "Lookup Efficiency"
+   - \`title\` (string): Main takeaway
+   - \`desc\` (string): Contextual explanation
+
+7. **checkpoint-quiz** (Interactive Checkpoint)
+   - \`tag\` (string): e.g. "Quick Knowledge Check"
+   - \`question\` (string): Clear question prompt
+   - \`options\` (array of objects): 2 to 4 options:
+     - \`label\`: "A", "B", "C", "D"
+     - \`text\`: Option text
+   - \`explanation\` (string): Explanatory rationale
+
+8. **summary-takeaways** (Wrap-Up / Next Steps)
+   - \`tag\` (string): e.g. "Recap"
+   - \`title\` (string): Wrap-up headline
+   - \`takeaways\` (string[]): 3 to 4 memorable bullet points
+   - \`nextStep\` (string): Teaser for the next lesson or project
+
+## Aesthetic & Quality Invariants ("Anti-AI-Slop"):
+- **Brevity is King (Zero-Scroll Invariant):** Each slide is calibrated for a 1920\xD71080 canvas. Maximum **35\u201340 words** per card or column; maximum **15 words** per bullet item. Never write dense multi-sentence paragraphs that cause vertical scrolling.
+- **Pedagogical Pacing:** Start with \`hero-cover\`, alternate between \`split-concept-code\`, \`two-columns-compare\` and \`three-cards-grid\`, insert a \`checkpoint-quiz\` midway, and finish with \`summary-takeaways\`.
+- **Theme Selection:**
+  - \`blue-professional\`: General academic, clean engineering, trustworthy.
+  - \`cobalt-grid\`: Advanced tech, algorithms, robotics, cybersecurity.
+  - \`editorial-forest\`: Thoughtful design, literature, ethics, science.
+  - \`studio\`: Minimalist product design, modern software.
+  - \`monochrome\`: Pure high-contrast dark mode.
+
+## \u{1FA84} Step Reveal & Progressive Disclosure:
+- The presentation shell supports sequential step reveal via mouse click or Space/Arrow keys.
+- Bullet lists (\`points\`, \`col1Items\`, \`col2Items\`), cards in \`three-cards-grid\`, and steps in \`timeline-steps\` reveal progressively one by one before navigating to the next slide.
+- In custom HTML slots, you can attach \`class="step-reveal"\`, \`data-step\`, \`data-reveal\`, or \`data-auto-reveal="true"\` on parent containers to enable click-by-click stepped appearance.
+
+## \u{1F399}\uFE0F Mandatory 3-Part Presenter Notes Contract:
+Every single slide MUST include the \`notes\` property structured with these 3 explicit components:
+1. **Talk Track:** 2-3 sentences of exact conversational speaking script for the teacher/presenter.
+2. **Cold-Call Check Question:** 1 diagnostic question to check understanding with a named student or attendee.
+3. **Scaffolding Tip:** 1 intuitive analogy or troubleshooting hint in case learners struggle with the concept.
+
+Example Notes:
+\`\`\`markdown
+Talk Track: Here we contrast synchronous blocking I/O with asynchronous event-driven handling. Notice how threads remain idle while waiting for network responses.
+Cold-Call: "Jordan, looking at the left column, what happens to thread pool throughput when network latency quadruples?"
+Scaffolding Tip: Compare it to ordering coffee at a counter (async buzzer) versus waiting at the register until the cup is brewed (sync blocking).
+\`\`\`
+`;
+
+// src/ai/html/tools.ts
+function handleListHtmlSlidePresets(input) {
+  const category = input.category || "all";
+  const presets = Object.values(HTML_SLIDE_PRESETS).filter((p) => category === "all" || p.category === category).map((p) => ({
+    id: p.id,
+    name: p.name,
+    category: p.category,
+    description: p.description,
+    slots: p.slots.map((s) => ({
+      name: s.name,
+      label: s.label,
+      type: s.type,
+      required: Boolean(s.required),
+      description: s.description
+    }))
+  }));
+  return {
+    success: true,
+    presets,
+    availableThemes: Object.keys(HTML_THEMES)
+  };
+}
+function handleGenerateHtmlDeck(input) {
+  try {
+    const result = compileHtmlDeck(input);
+    return {
+      success: true,
+      title: result.title,
+      slideCount: result.slideCount,
+      theme: result.theme.id,
+      html: result.html
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: err.message || "Failed to compile HTML slide deck"
+    };
+  }
+}
+function handleCreateHtmlSlide(input) {
+  const preset = HTML_SLIDE_PRESETS[input.layoutId];
+  if (!preset) {
+    return {
+      success: false,
+      error: `Unknown layout preset: ${input.layoutId}`
+    };
+  }
+  return {
+    success: true,
+    slide: {
+      layoutId: input.layoutId,
+      slots: input.slots,
+      notes: input.notes
+    }
+  };
+}
+var executeListHtmlSlidePresets = handleListHtmlSlidePresets;
+var executeGenerateHtmlDeck = handleGenerateHtmlDeck;
+var executeCreateHtmlSlide = handleCreateHtmlSlide;
 
-export { SLIDE_DESIGN_PROMPT_CONTRACT, applySlideLayoutSchema, createSlideFromPresetSchema, executeApplySlideLayout, executeCreateSlideFromPreset, executeGenerateDeckOutline, executeListSlidePresets, executeUpdatePresenterNotes, generateDeckOutlineSchema, listSlidePresetsSchema, updatePresenterNotesSchema };
+export { SLIDE_DESIGN_PROMPT_CONTRACT, SLIDE_HTML_PROMPT_CONTRACT, applySlideLayoutSchema, createHtmlSlideSchema, createSlideFromPresetSchema, executeApplySlideLayout, executeCreateHtmlSlide, executeCreateSlideFromPreset, executeGenerateDeckOutline, executeGenerateHtmlDeck, executeListHtmlSlidePresets, executeListSlidePresets, executeUpdatePresenterNotes, executeValidateSlideDeck, generateDeckOutlineSchema, generateHtmlDeckSchema, handleCreateHtmlSlide, handleGenerateHtmlDeck, handleListHtmlSlidePresets, handleValidateSlideDeck, htmlSlideSlotDataSchema, listHtmlSlidePresetsSchema, listSlidePresetsSchema, updatePresenterNotesSchema, validateHtmlSlideDeck, validateMarkdownSlideDeck, validateSlideDeckSchema };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map