@thanh01.pmt/presentation-kit 0.2.11 → 0.2.13

package/dist/ai/index.js

@@ -410,7 +410,326 @@ 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).`
+              });
+            }
+          }
+        });
+      }
+    }
+    const rawNotes = Array.isArray(slide.notes) ? slide.notes.join("\n") : typeof slide.notes === "string" ? slide.notes : "";
+    if (rawNotes && rawNotes.trim().length > 0) {
+      notesCount++;
+      const notes = rawNotes.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 { slides: rawSlides } = splitMarkdownSlides(markdown);
+  const activeSlides = rawSlides.filter((s) => s.trim().length > 0);
+  const slideCount = activeSlides.length;
+  if (slideCount === 0) {
+    return {
+      success: false,
+      valid: false,
+      score: 0,
+      format: "markdown",
+      slideCount: 0,
+      notesCoveragePercent: 0,
+      issues: [{
+        slideIndex: 0,
+        severity: "error",
+        rule: "EMPTY_MARKDOWN",
+        message: "No slide content detected after stripping frontmatter."
+      }],
+      suggestions: ['Add slide content separated by "---".']
+    };
+  }
+  let notesCount = 0;
+  activeSlides.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")
 });
@@ -519,8 +838,8 @@ Instead of generating free-form HTML or brittle Markdown hacks, you MUST fill st
    - \`takeaways\` (string[]): 3 to 4 memorable bullet points
    - \`nextStep\` (string): Teaser for the next lesson or project
 
-## Aesthetic Rules ("Anti-AI-Slop"):
-- **Brevity is King:** Each slide fits a 1920\xD71080 canvas. Keep sentences punchy. Never write dense paragraphs that overflow.
+## 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.
@@ -528,6 +847,24 @@ Instead of generating free-form HTML or brittle Markdown hacks, you MUST fill st
   - \`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
@@ -586,7 +923,10 @@ function handleCreateHtmlSlide(input) {
     }
   };
 }
+var executeListHtmlSlidePresets = handleListHtmlSlidePresets;
+var executeGenerateHtmlDeck = handleGenerateHtmlDeck;
+var executeCreateHtmlSlide = handleCreateHtmlSlide;
 
-export { SLIDE_DESIGN_PROMPT_CONTRACT, SLIDE_HTML_PROMPT_CONTRACT, applySlideLayoutSchema, createHtmlSlideSchema, createSlideFromPresetSchema, executeApplySlideLayout, executeCreateSlideFromPreset, executeGenerateDeckOutline, executeListSlidePresets, executeUpdatePresenterNotes, generateDeckOutlineSchema, generateHtmlDeckSchema, handleCreateHtmlSlide, handleGenerateHtmlDeck, handleListHtmlSlidePresets, htmlSlideSlotDataSchema, listHtmlSlidePresetsSchema, 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