claude-presentation-master 8.1.0 → 8.2.0

package/dist/index.d.mts

@@ -127,6 +127,26 @@ interface QAResults {
     passed: boolean;
     /** List of issues found */
     issues: QAIssue[];
+    /** Per-slide scores from visual QA */
+    slideScores?: SlideScore[];
+    /** Overall QA score */
+    score?: number;
+    /** QA status */
+    status?: string;
+}
+interface SlideScore {
+    /** Slide index */
+    index: number;
+    /** Slide type */
+    type: string;
+    /** Score 0-100 */
+    score: number;
+    /** Expert verdict */
+    expertVerdict?: string;
+    /** Critical issues found */
+    criticalIssues?: string[];
+    /** All issues */
+    issues?: QAIssue[];
 }
 interface VisualQAResults {
     /** Whitespace percentage (target: 35%+ keynote, 25%+ business) */
@@ -391,19 +411,28 @@ interface SparklineStructure {
 }
 declare class ValidationError extends Error {
     errors: string[];
+    readonly suggestions: string[];
     constructor(errors: string[], message?: string);
+    private static getSuggestions;
 }
 declare class QAFailureError extends Error {
     score: number;
     threshold: number;
     qaResults: QAResults;
+    readonly topIssues: string[];
     constructor(score: number, threshold: number, qaResults: QAResults, message?: string);
     getIssues(): string[];
+    private static getTopIssues;
 }
 declare class TemplateNotFoundError extends Error {
     templatePath: string;
     constructor(templatePath: string, message?: string);
 }
+declare class KnowledgeBaseError extends Error {
+    field: string;
+    context: string;
+    constructor(field: string, context: string, message?: string);
+}
 /**
  * Content pattern detected from a section
  * Used to match content to appropriate slide types
@@ -2173,4 +2202,4 @@ declare const _default: {
     VERSION: string;
 };
 
-export { type AccessibilityResults, type ChartData, type ChartDataset, ChartJsProvider, type ChartProvider, type ChartRequest, type ChartResult, type ChartType, type ColorPalette, CompositeChartProvider, CompositeImageProvider, type ContentAnalysis$1 as ContentAnalysis, ContentAnalyzer, type ContentPattern, ContentPatternClassifier, type ContentQAResults, type ContentSection$1 as ContentSection, type ContrastIssue, type ExpertQAResults, type ExpertValidation, type FontSizeIssue, type GlanceTestResult, type ImageData, type ImageProvider, type ImageRequest, type ImageResult, KnowledgeGateway, type LegacySlide, LocalImageProvider, MermaidProvider, type MetricData, type OneIdeaResult, type OutputFormat, PlaceholderImageProvider, PowerPointGenerator, type PresentationConfig, PresentationEngine, type PresentationMetadata, type PresentationMode$1 as PresentationMode, type PresentationQualityScore, type PresentationResult, type PresentationType, QAEngine, QAFailureError, type QAIssue, type QAResults, QuickChartProvider, RevealJsGenerator, type SCQAStructure, ScoreCalculator, type ScoringWeights, type SevenDimensionQAResult, type SignalNoiseResult, type Slide, type SlideContentScore, type SlideData, SlideFactory, SlideGenerator, type SlideTemplate, type SlideType, type SlideValidationResult, type SlideVisualScore, type SparklineStructure, type StoryStructure, TemplateEngine, TemplateNotFoundError, type ThemeName, type TypographyRules, UnsplashImageProvider, VERSION, ValidationError, type ValidationRules, type VisualQAResults, VisualQualityEvaluator, createDefaultChartProvider, createDefaultImageProvider, createSlideFactory, _default as default, evaluatePresentation, generate, getKnowledgeGateway, initSlideGenerator, validate };
+export { type AccessibilityResults, type ChartData, type ChartDataset, ChartJsProvider, type ChartProvider, type ChartRequest, type ChartResult, type ChartType, type ColorPalette, CompositeChartProvider, CompositeImageProvider, type ContentAnalysis$1 as ContentAnalysis, ContentAnalyzer, type ContentPattern, ContentPatternClassifier, type ContentQAResults, type ContentSection$1 as ContentSection, type ContrastIssue, type ExpertQAResults, type ExpertValidation, type FontSizeIssue, type GlanceTestResult, type ImageData, type ImageProvider, type ImageRequest, type ImageResult, KnowledgeBaseError, KnowledgeGateway, type LegacySlide, LocalImageProvider, MermaidProvider, type MetricData, type OneIdeaResult, type OutputFormat, PlaceholderImageProvider, PowerPointGenerator, type PresentationConfig, PresentationEngine, type PresentationMetadata, type PresentationMode$1 as PresentationMode, type PresentationQualityScore, type PresentationResult, type PresentationType, QAEngine, QAFailureError, type QAIssue, type QAResults, QuickChartProvider, RevealJsGenerator, type SCQAStructure, ScoreCalculator, type ScoringWeights, type SevenDimensionQAResult, type SignalNoiseResult, type Slide, type SlideContentScore, type SlideData, SlideFactory, SlideGenerator, type SlideScore, type SlideTemplate, type SlideType, type SlideValidationResult, type SlideVisualScore, type SparklineStructure, type StoryStructure, TemplateEngine, TemplateNotFoundError, type ThemeName, type TypographyRules, UnsplashImageProvider, VERSION, ValidationError, type ValidationRules, type VisualQAResults, VisualQualityEvaluator, createDefaultChartProvider, createDefaultImageProvider, createSlideFactory, _default as default, evaluatePresentation, generate, getKnowledgeGateway, initSlideGenerator, validate };

package/dist/index.d.ts

@@ -127,6 +127,26 @@ interface QAResults {
     passed: boolean;
     /** List of issues found */
     issues: QAIssue[];
+    /** Per-slide scores from visual QA */
+    slideScores?: SlideScore[];
+    /** Overall QA score */
+    score?: number;
+    /** QA status */
+    status?: string;
+}
+interface SlideScore {
+    /** Slide index */
+    index: number;
+    /** Slide type */
+    type: string;
+    /** Score 0-100 */
+    score: number;
+    /** Expert verdict */
+    expertVerdict?: string;
+    /** Critical issues found */
+    criticalIssues?: string[];
+    /** All issues */
+    issues?: QAIssue[];
 }
 interface VisualQAResults {
     /** Whitespace percentage (target: 35%+ keynote, 25%+ business) */
@@ -391,19 +411,28 @@ interface SparklineStructure {
 }
 declare class ValidationError extends Error {
     errors: string[];
+    readonly suggestions: string[];
     constructor(errors: string[], message?: string);
+    private static getSuggestions;
 }
 declare class QAFailureError extends Error {
     score: number;
     threshold: number;
     qaResults: QAResults;
+    readonly topIssues: string[];
     constructor(score: number, threshold: number, qaResults: QAResults, message?: string);
     getIssues(): string[];
+    private static getTopIssues;
 }
 declare class TemplateNotFoundError extends Error {
     templatePath: string;
     constructor(templatePath: string, message?: string);
 }
+declare class KnowledgeBaseError extends Error {
+    field: string;
+    context: string;
+    constructor(field: string, context: string, message?: string);
+}
 /**
  * Content pattern detected from a section
  * Used to match content to appropriate slide types
@@ -2173,4 +2202,4 @@ declare const _default: {
     VERSION: string;
 };
 
-export { type AccessibilityResults, type ChartData, type ChartDataset, ChartJsProvider, type ChartProvider, type ChartRequest, type ChartResult, type ChartType, type ColorPalette, CompositeChartProvider, CompositeImageProvider, type ContentAnalysis$1 as ContentAnalysis, ContentAnalyzer, type ContentPattern, ContentPatternClassifier, type ContentQAResults, type ContentSection$1 as ContentSection, type ContrastIssue, type ExpertQAResults, type ExpertValidation, type FontSizeIssue, type GlanceTestResult, type ImageData, type ImageProvider, type ImageRequest, type ImageResult, KnowledgeGateway, type LegacySlide, LocalImageProvider, MermaidProvider, type MetricData, type OneIdeaResult, type OutputFormat, PlaceholderImageProvider, PowerPointGenerator, type PresentationConfig, PresentationEngine, type PresentationMetadata, type PresentationMode$1 as PresentationMode, type PresentationQualityScore, type PresentationResult, type PresentationType, QAEngine, QAFailureError, type QAIssue, type QAResults, QuickChartProvider, RevealJsGenerator, type SCQAStructure, ScoreCalculator, type ScoringWeights, type SevenDimensionQAResult, type SignalNoiseResult, type Slide, type SlideContentScore, type SlideData, SlideFactory, SlideGenerator, type SlideTemplate, type SlideType, type SlideValidationResult, type SlideVisualScore, type SparklineStructure, type StoryStructure, TemplateEngine, TemplateNotFoundError, type ThemeName, type TypographyRules, UnsplashImageProvider, VERSION, ValidationError, type ValidationRules, type VisualQAResults, VisualQualityEvaluator, createDefaultChartProvider, createDefaultImageProvider, createSlideFactory, _default as default, evaluatePresentation, generate, getKnowledgeGateway, initSlideGenerator, validate };
+export { type AccessibilityResults, type ChartData, type ChartDataset, ChartJsProvider, type ChartProvider, type ChartRequest, type ChartResult, type ChartType, type ColorPalette, CompositeChartProvider, CompositeImageProvider, type ContentAnalysis$1 as ContentAnalysis, ContentAnalyzer, type ContentPattern, ContentPatternClassifier, type ContentQAResults, type ContentSection$1 as ContentSection, type ContrastIssue, type ExpertQAResults, type ExpertValidation, type FontSizeIssue, type GlanceTestResult, type ImageData, type ImageProvider, type ImageRequest, type ImageResult, KnowledgeBaseError, KnowledgeGateway, type LegacySlide, LocalImageProvider, MermaidProvider, type MetricData, type OneIdeaResult, type OutputFormat, PlaceholderImageProvider, PowerPointGenerator, type PresentationConfig, PresentationEngine, type PresentationMetadata, type PresentationMode$1 as PresentationMode, type PresentationQualityScore, type PresentationResult, type PresentationType, QAEngine, QAFailureError, type QAIssue, type QAResults, QuickChartProvider, RevealJsGenerator, type SCQAStructure, ScoreCalculator, type ScoringWeights, type SevenDimensionQAResult, type SignalNoiseResult, type Slide, type SlideContentScore, type SlideData, SlideFactory, SlideGenerator, type SlideScore, type SlideTemplate, type SlideType, type SlideValidationResult, type SlideVisualScore, type SparklineStructure, type StoryStructure, TemplateEngine, TemplateNotFoundError, type ThemeName, type TypographyRules, UnsplashImageProvider, VERSION, ValidationError, type ValidationRules, type VisualQAResults, VisualQualityEvaluator, createDefaultChartProvider, createDefaultImageProvider, createSlideFactory, _default as default, evaluatePresentation, generate, getKnowledgeGateway, initSlideGenerator, validate };

package/dist/index.js

@@ -35,6 +35,7 @@ __export(index_exports, {
   CompositeImageProvider: () => CompositeImageProvider,
   ContentAnalyzer: () => ContentAnalyzer,
   ContentPatternClassifier: () => ContentPatternClassifier,
+  KnowledgeBaseError: () => KnowledgeBaseError,
   KnowledgeGateway: () => KnowledgeGateway,
   LocalImageProvider: () => LocalImageProvider,
   MermaidProvider: () => MermaidProvider,
@@ -67,32 +68,100 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/types/index.ts
-var ValidationError = class extends Error {
+var ValidationError = class _ValidationError extends Error {
   constructor(errors, message = "Validation failed") {
-    super(message);
+    const errorList = errors.map((e) => `  \u2022 ${e}`).join("\n");
+    const suggestions = _ValidationError.getSuggestions(errors);
+    const suggestionList = suggestions.length > 0 ? "\n\nHow to fix:\n" + suggestions.map((s) => `  \u2192 ${s}`).join("\n") : "";
+    super(`${message}
+
+Issues found:
+${errorList}${suggestionList}`);
     this.errors = errors;
     this.name = "ValidationError";
+    this.suggestions = suggestions;
+  }
+  suggestions;
+  static getSuggestions(errors) {
+    const suggestions = [];
+    for (const error of errors) {
+      if (error.includes("Content is required")) {
+        suggestions.push("Provide markdown content with at least one ## section header");
+      }
+      if (error.includes("Mode must be")) {
+        suggestions.push('Use mode: "keynote" for TED-style or mode: "business" for corporate');
+      }
+      if (error.includes("Title is required")) {
+        suggestions.push('Add a title: "Your Presentation Title" to your config');
+      }
+      if (error.includes("output format")) {
+        suggestions.push('Specify format: ["html"] or format: ["html", "pdf"]');
+      }
+    }
+    return [...new Set(suggestions)];
   }
 };
-var QAFailureError = class extends Error {
-  constructor(score, threshold, qaResults, message = `QA score ${score} below threshold ${threshold}`) {
-    super(message);
+var QAFailureError = class _QAFailureError extends Error {
+  constructor(score, threshold, qaResults, message) {
+    const topIssues = _QAFailureError.getTopIssues(qaResults);
+    const issueList = topIssues.map((i) => `  \u2022 ${i}`).join("\n");
+    const helpText = `
+
+Score: ${score}/100 (threshold: ${threshold})
+
+Top issues to fix:
+${issueList}
+
+How to improve:
+  \u2192 Ensure each slide has meaningful content (not just a title)
+  \u2192 Keep text concise - aim for <40 words per slide
+  \u2192 Use timeline/process slides for step-by-step content
+  \u2192 Add visuals for data-heavy slides`;
+    super(message || `QA score ${score} below threshold ${threshold}${helpText}`);
     this.score = score;
     this.threshold = threshold;
     this.qaResults = qaResults;
     this.name = "QAFailureError";
+    this.topIssues = topIssues;
   }
+  topIssues;
   getIssues() {
     return this.qaResults.issues.map((issue) => issue.message);
   }
+  static getTopIssues(qaResults) {
+    const issues = [];
+    if (qaResults.slideScores) {
+      for (const slide of qaResults.slideScores) {
+        if (slide.criticalIssues) {
+          issues.push(...slide.criticalIssues);
+        }
+      }
+    }
+    if (qaResults.issues) {
+      issues.push(...qaResults.issues.map((i) => i.message));
+    }
+    return [...new Set(issues)].slice(0, 5);
+  }
 };
 var TemplateNotFoundError = class extends Error {
-  constructor(templatePath, message = `Template not found: ${templatePath}`) {
-    super(message);
+  constructor(templatePath, message) {
+    super(message || `Template not found: ${templatePath}
+
+Available templates: title, content, timeline, process, metrics, quote, cta, thank-you`);
     this.templatePath = templatePath;
     this.name = "TemplateNotFoundError";
   }
 };
+var KnowledgeBaseError = class extends Error {
+  constructor(field, context, message) {
+    super(message || `Knowledge base configuration error: Missing "${field}" in ${context}
+
+Check assets/presentation-knowledge.yaml for the correct structure.`);
+    this.field = field;
+    this.context = context;
+    this.name = "KnowledgeBaseError";
+  }
+};
 
 // src/core/PresentationEngine.ts
 var fs2 = __toESM(require("fs"));
@@ -102,7 +171,6 @@ var os = __toESM(require("os"));
 // src/kb/KnowledgeGateway.ts
 var import_fs = require("fs");
 var import_path = require("path");
-var import_url = require("url");
 var yaml = __toESM(require("yaml"));
 
 // src/utils/Logger.ts
@@ -173,11 +241,7 @@ var logger = new Logger({
 });
 
 // src/kb/KnowledgeGateway.ts
-var import_meta = {};
 function getModuleDir() {
-  if (typeof import_meta !== "undefined" && import_meta.url) {
-    return (0, import_path.dirname)((0, import_url.fileURLToPath)(import_meta.url));
-  }
   if (typeof __dirname !== "undefined") {
     return __dirname;
   }
@@ -2867,25 +2931,43 @@ var SlideFactory = class {
   createComparisonSlide(index, section) {
     const comparison = this.classifier.extractComparison(section);
     const labels = this.config.defaults.comparison;
+    const title = this.createTitle(section.header, section);
+    const normalizedTitle = title.toLowerCase().replace(/[^a-z0-9]/g, "");
     const leftFallback = labels.optionLabels[0] ?? "Option A";
     const rightFallback = labels.optionLabels[1] ?? "Option B";
-    const leftColumn = comparison?.left || section.bullets[0] || leftFallback;
-    const rightColumn = comparison?.right || section.bullets[1] || rightFallback;
+    let leftColumn = comparison?.left || section.bullets[0] || "";
+    let rightColumn = comparison?.right || section.bullets[1] || "";
+    const normalizedLeft = leftColumn.toLowerCase().replace(/[^a-z0-9]/g, "");
+    const normalizedRight = rightColumn.toLowerCase().replace(/[^a-z0-9]/g, "");
+    const leftIsDuplicate = normalizedLeft === normalizedTitle || normalizedTitle.includes(normalizedLeft);
+    const rightIsDuplicate = normalizedRight === normalizedTitle || normalizedTitle.includes(normalizedRight);
+    if (leftIsDuplicate || rightIsDuplicate || !leftColumn && !rightColumn) {
+      if (section.bullets.length >= 2) {
+        logger.warn(`Comparison slide "${title}" has duplicate content, using bullet points instead`);
+        return this.createBulletSlide(index, section);
+      }
+      if (leftIsDuplicate && rightIsDuplicate) {
+        logger.warn(`Skipping comparison slide "${title}" - content duplicates title`);
+        return null;
+      }
+      if (leftIsDuplicate) leftColumn = leftFallback;
+      if (rightIsDuplicate) rightColumn = rightFallback;
+    }
     return {
       index,
       type: "comparison",
       data: {
-        title: this.createTitle(section.header, section),
+        title,
         columns: [
           {
             title: labels.leftLabel,
             // FROM KB - not hardcoded 'Before'
-            content: this.truncateText(leftColumn, this.config.rules.wordsPerSlide.max)
+            content: this.truncateText(leftColumn || leftFallback, this.config.rules.wordsPerSlide.max)
           },
           {
             title: labels.rightLabel,
             // FROM KB - not hardcoded 'After'
-            content: this.truncateText(rightColumn, this.config.rules.wordsPerSlide.max)
+            content: this.truncateText(rightColumn || rightFallback, this.config.rules.wordsPerSlide.max)
           }
         ]
       },
@@ -3156,10 +3238,21 @@ var SlideFactory = class {
    * Used for section headers with strong conclusions.
    */
   createTitleImpactSlide(index, section) {
+    const title = this.cleanText(section.header);
     const supportingText = section.content || section.bullets.slice(0, 2).join(". ");
     const truncatedSupport = this.truncateText(supportingText, this.config.defaults.context.maxWords);
+    const normalizedTitle = title.toLowerCase().replace(/[^a-z0-9]/g, "");
+    const normalizedBody = truncatedSupport.toLowerCase().replace(/[^a-z0-9]/g, "");
+    const bodyIsDuplicate = normalizedBody === normalizedTitle || normalizedTitle.includes(normalizedBody) || normalizedBody.includes(normalizedTitle) || truncatedSupport.length < 10;
+    if (bodyIsDuplicate) {
+      if (section.bullets.length >= 2 && this.config.mode === "business") {
+        return this.createBulletSlide(index, section);
+      }
+      logger.warn(`Skipping title-impact slide "${title}" - no distinct body content`);
+      return null;
+    }
     const data = {
-      title: this.cleanText(section.header)
+      title
     };
     if (truncatedSupport) {
       data.body = truncatedSupport;
@@ -7675,13 +7768,63 @@ var PowerPointGenerator = class {
 
 // src/generators/PDFGenerator.ts
 var import_puppeteer = __toESM(require("puppeteer"));
+var cachedBrowser = null;
+var browserIdleTimeout = null;
+var BROWSER_IDLE_MS = 3e4;
 var PDFGenerator = class {
   defaultOptions = {
     orientation: "landscape",
     printBackground: true,
     format: "Slide",
-    scale: 1
+    scale: 1,
+    reuseBrowser: true
   };
+  /**
+   * Get or create a browser instance
+   */
+  async getBrowser(reuse) {
+    if (browserIdleTimeout) {
+      clearTimeout(browserIdleTimeout);
+      browserIdleTimeout = null;
+    }
+    if (reuse && cachedBrowser && cachedBrowser.connected) {
+      logger.progress("Using cached browser instance");
+      return cachedBrowser;
+    }
+    if (cachedBrowser && !cachedBrowser.connected) {
+      cachedBrowser = null;
+    }
+    logger.progress("Launching new browser instance...");
+    const browser = await import_puppeteer.default.launch({
+      headless: true,
+      args: [
+        "--no-sandbox",
+        "--disable-setuid-sandbox",
+        "--disable-dev-shm-usage",
+        "--disable-gpu"
+      ]
+    });
+    if (reuse) {
+      cachedBrowser = browser;
+    }
+    return browser;
+  }
+  /**
+   * Schedule browser cleanup after idle period
+   */
+  scheduleBrowserCleanup() {
+    if (browserIdleTimeout) {
+      clearTimeout(browserIdleTimeout);
+    }
+    browserIdleTimeout = setTimeout(async () => {
+      if (cachedBrowser) {
+        logger.progress("Closing idle browser instance");
+        await cachedBrowser.close().catch(() => {
+        });
+        cachedBrowser = null;
+      }
+    }, BROWSER_IDLE_MS);
+  }
   /**
    * Generate PDF from HTML presentation
    * @param html - The HTML content of the presentation
@@ -7690,18 +7833,14 @@ var PDFGenerator = class {
    */
   async generate(html, options = {}) {
     const opts = { ...this.defaultOptions, ...options };
+    const reuseBrowser = opts.reuseBrowser ?? true;
     logger.progress("\u{1F4C4} Generating PDF...");
-    let browser;
+    let browser = null;
+    let shouldCloseBrowser = !reuseBrowser;
+    let page = null;
     try {
-      browser = await import_puppeteer.default.launch({
-        headless: true,
-        args: [
-          "--no-sandbox",
-          "--disable-setuid-sandbox",
-          "--disable-dev-shm-usage"
-        ]
-      });
-      const page = await browser.newPage();
+      browser = await this.getBrowser(reuseBrowser);
+      page = await browser.newPage();
       const printHtml = this.preparePrintHtml(html);
       await page.setViewport({
         width: 1920,
@@ -7737,13 +7876,38 @@ var PDFGenerator = class {
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       logger.error(`PDF generation failed: ${errorMessage}`);
+      shouldCloseBrowser = true;
       throw new Error(`PDF generation failed: ${errorMessage}`);
     } finally {
-      if (browser) {
-        await browser.close();
+      if (page) {
+        await page.close().catch(() => {
+        });
+      }
+      if (shouldCloseBrowser && browser) {
+        await browser.close().catch(() => {
+        });
+        if (browser === cachedBrowser) {
+          cachedBrowser = null;
+        }
+      } else if (reuseBrowser) {
+        this.scheduleBrowserCleanup();
       }
     }
   }
+  /**
+   * Manually close the cached browser (call before process exit)
+   */
+  static async closeBrowser() {
+    if (browserIdleTimeout) {
+      clearTimeout(browserIdleTimeout);
+      browserIdleTimeout = null;
+    }
+    if (cachedBrowser) {
+      await cachedBrowser.close().catch(() => {
+      });
+      cachedBrowser = null;
+    }
+  }
   /**
    * Prepare HTML for print/PDF output
    * Modifies the HTML to work better as a printed document
@@ -7757,12 +7921,24 @@ var PDFGenerator = class {
           margin: 0;
         }
 
+        /* Font rendering optimization for print */
+        * {
+          -webkit-font-smoothing: antialiased;
+          -moz-osx-font-smoothing: grayscale;
+          text-rendering: optimizeLegibility;
+          font-feature-settings: "liga" 1, "kern" 1;
+        }
+
         @media print {
           html, body {
             margin: 0;
             padding: 0;
             width: 1920px;
             height: 1080px;
+            /* Print color optimization */
+            color-adjust: exact;
+            -webkit-print-color-adjust: exact;
+            print-color-adjust: exact;
           }
 
           .reveal .slides {
@@ -7779,7 +7955,8 @@ var PDFGenerator = class {
             width: 1920px !important;
             height: 1080px !important;
             margin: 0 !important;
-            padding: 60px !important;
+            /* Professional safe margins: 80px (4.2%) */
+            padding: 80px !important;
             box-sizing: border-box;
             position: relative !important;
             top: auto !important;
@@ -7803,7 +7980,7 @@ var PDFGenerator = class {
           }
 
           /* Disable animations for print */
-          * {
+          *, *::before, *::after {
             animation: none !important;
             transition: none !important;
           }
@@ -7819,6 +7996,30 @@ var PDFGenerator = class {
           .reveal .navigate-down {
             display: none !important;
           }
+
+          /* Typography refinements for print */
+          h1, h2, h3, h4 {
+            orphans: 3;
+            widows: 3;
+            page-break-after: avoid;
+          }
+
+          p, li {
+            orphans: 2;
+            widows: 2;
+          }
+
+          /* Ensure links are readable in print */
+          a {
+            text-decoration: none;
+          }
+
+          /* Prevent image overflow */
+          img {
+            max-width: 100%;
+            height: auto;
+            page-break-inside: avoid;
+          }
         }
 
         /* Force print mode in Puppeteer */
@@ -7826,6 +8027,11 @@ var PDFGenerator = class {
           page-break-after: always;
           page-break-inside: avoid;
         }
+
+        /* High contrast mode for business presentations */
+        .reveal section {
+          color-scheme: light;
+        }
       </style>
     `;
     if (html.includes("</head>")) {
@@ -8419,6 +8625,7 @@ var index_default = {
   CompositeImageProvider,
   ContentAnalyzer,
   ContentPatternClassifier,
+  KnowledgeBaseError,
   KnowledgeGateway,
   LocalImageProvider,
   MermaidProvider,

package/dist/index.mjs

@@ -1,30 +1,98 @@
 // src/types/index.ts
-var ValidationError = class extends Error {
+var ValidationError = class _ValidationError extends Error {
   constructor(errors, message = "Validation failed") {
-    super(message);
+    const errorList = errors.map((e) => `  \u2022 ${e}`).join("\n");
+    const suggestions = _ValidationError.getSuggestions(errors);
+    const suggestionList = suggestions.length > 0 ? "\n\nHow to fix:\n" + suggestions.map((s) => `  \u2192 ${s}`).join("\n") : "";
+    super(`${message}
+
+Issues found:
+${errorList}${suggestionList}`);
     this.errors = errors;
     this.name = "ValidationError";
+    this.suggestions = suggestions;
+  }
+  suggestions;
+  static getSuggestions(errors) {
+    const suggestions = [];
+    for (const error of errors) {
+      if (error.includes("Content is required")) {
+        suggestions.push("Provide markdown content with at least one ## section header");
+      }
+      if (error.includes("Mode must be")) {
+        suggestions.push('Use mode: "keynote" for TED-style or mode: "business" for corporate');
+      }
+      if (error.includes("Title is required")) {
+        suggestions.push('Add a title: "Your Presentation Title" to your config');
+      }
+      if (error.includes("output format")) {
+        suggestions.push('Specify format: ["html"] or format: ["html", "pdf"]');
+      }
+    }
+    return [...new Set(suggestions)];
   }
 };
-var QAFailureError = class extends Error {
-  constructor(score, threshold, qaResults, message = `QA score ${score} below threshold ${threshold}`) {
-    super(message);
+var QAFailureError = class _QAFailureError extends Error {
+  constructor(score, threshold, qaResults, message) {
+    const topIssues = _QAFailureError.getTopIssues(qaResults);
+    const issueList = topIssues.map((i) => `  \u2022 ${i}`).join("\n");
+    const helpText = `
+
+Score: ${score}/100 (threshold: ${threshold})
+
+Top issues to fix:
+${issueList}
+
+How to improve:
+  \u2192 Ensure each slide has meaningful content (not just a title)
+  \u2192 Keep text concise - aim for <40 words per slide
+  \u2192 Use timeline/process slides for step-by-step content
+  \u2192 Add visuals for data-heavy slides`;
+    super(message || `QA score ${score} below threshold ${threshold}${helpText}`);
     this.score = score;
     this.threshold = threshold;
     this.qaResults = qaResults;
     this.name = "QAFailureError";
+    this.topIssues = topIssues;
   }
+  topIssues;
   getIssues() {
     return this.qaResults.issues.map((issue) => issue.message);
   }
+  static getTopIssues(qaResults) {
+    const issues = [];
+    if (qaResults.slideScores) {
+      for (const slide of qaResults.slideScores) {
+        if (slide.criticalIssues) {
+          issues.push(...slide.criticalIssues);
+        }
+      }
+    }
+    if (qaResults.issues) {
+      issues.push(...qaResults.issues.map((i) => i.message));
+    }
+    return [...new Set(issues)].slice(0, 5);
+  }
 };
 var TemplateNotFoundError = class extends Error {
-  constructor(templatePath, message = `Template not found: ${templatePath}`) {
-    super(message);
+  constructor(templatePath, message) {
+    super(message || `Template not found: ${templatePath}
+
+Available templates: title, content, timeline, process, metrics, quote, cta, thank-you`);
     this.templatePath = templatePath;
     this.name = "TemplateNotFoundError";
   }
 };
+var KnowledgeBaseError = class extends Error {
+  constructor(field, context, message) {
+    super(message || `Knowledge base configuration error: Missing "${field}" in ${context}
+
+Check assets/presentation-knowledge.yaml for the correct structure.`);
+    this.field = field;
+    this.context = context;
+    this.name = "KnowledgeBaseError";
+  }
+};
 
 // src/core/PresentationEngine.ts
 import * as fs2 from "fs";
@@ -33,8 +101,7 @@ import * as os from "os";
 
 // src/kb/KnowledgeGateway.ts
 import { readFileSync } from "fs";
-import { join, dirname } from "path";
-import { fileURLToPath } from "url";
+import { join } from "path";
 import * as yaml from "yaml";
 
 // src/utils/Logger.ts
@@ -106,9 +173,6 @@ var logger = new Logger({
 
 // src/kb/KnowledgeGateway.ts
 function getModuleDir() {
-  if (typeof import.meta !== "undefined" && import.meta.url) {
-    return dirname(fileURLToPath(import.meta.url));
-  }
   if (typeof __dirname !== "undefined") {
     return __dirname;
   }
@@ -2798,25 +2862,43 @@ var SlideFactory = class {
   createComparisonSlide(index, section) {
     const comparison = this.classifier.extractComparison(section);
     const labels = this.config.defaults.comparison;
+    const title = this.createTitle(section.header, section);
+    const normalizedTitle = title.toLowerCase().replace(/[^a-z0-9]/g, "");
     const leftFallback = labels.optionLabels[0] ?? "Option A";
     const rightFallback = labels.optionLabels[1] ?? "Option B";
-    const leftColumn = comparison?.left || section.bullets[0] || leftFallback;
-    const rightColumn = comparison?.right || section.bullets[1] || rightFallback;
+    let leftColumn = comparison?.left || section.bullets[0] || "";
+    let rightColumn = comparison?.right || section.bullets[1] || "";
+    const normalizedLeft = leftColumn.toLowerCase().replace(/[^a-z0-9]/g, "");
+    const normalizedRight = rightColumn.toLowerCase().replace(/[^a-z0-9]/g, "");
+    const leftIsDuplicate = normalizedLeft === normalizedTitle || normalizedTitle.includes(normalizedLeft);
+    const rightIsDuplicate = normalizedRight === normalizedTitle || normalizedTitle.includes(normalizedRight);
+    if (leftIsDuplicate || rightIsDuplicate || !leftColumn && !rightColumn) {
+      if (section.bullets.length >= 2) {
+        logger.warn(`Comparison slide "${title}" has duplicate content, using bullet points instead`);
+        return this.createBulletSlide(index, section);
+      }
+      if (leftIsDuplicate && rightIsDuplicate) {
+        logger.warn(`Skipping comparison slide "${title}" - content duplicates title`);
+        return null;
+      }
+      if (leftIsDuplicate) leftColumn = leftFallback;
+      if (rightIsDuplicate) rightColumn = rightFallback;
+    }
     return {
       index,
       type: "comparison",
       data: {
-        title: this.createTitle(section.header, section),
+        title,
         columns: [
           {
             title: labels.leftLabel,
             // FROM KB - not hardcoded 'Before'
-            content: this.truncateText(leftColumn, this.config.rules.wordsPerSlide.max)
+            content: this.truncateText(leftColumn || leftFallback, this.config.rules.wordsPerSlide.max)
           },
           {
             title: labels.rightLabel,
             // FROM KB - not hardcoded 'After'
-            content: this.truncateText(rightColumn, this.config.rules.wordsPerSlide.max)
+            content: this.truncateText(rightColumn || rightFallback, this.config.rules.wordsPerSlide.max)
           }
         ]
       },
@@ -3087,10 +3169,21 @@ var SlideFactory = class {
    * Used for section headers with strong conclusions.
    */
   createTitleImpactSlide(index, section) {
+    const title = this.cleanText(section.header);
     const supportingText = section.content || section.bullets.slice(0, 2).join(". ");
     const truncatedSupport = this.truncateText(supportingText, this.config.defaults.context.maxWords);
+    const normalizedTitle = title.toLowerCase().replace(/[^a-z0-9]/g, "");
+    const normalizedBody = truncatedSupport.toLowerCase().replace(/[^a-z0-9]/g, "");
+    const bodyIsDuplicate = normalizedBody === normalizedTitle || normalizedTitle.includes(normalizedBody) || normalizedBody.includes(normalizedTitle) || truncatedSupport.length < 10;
+    if (bodyIsDuplicate) {
+      if (section.bullets.length >= 2 && this.config.mode === "business") {
+        return this.createBulletSlide(index, section);
+      }
+      logger.warn(`Skipping title-impact slide "${title}" - no distinct body content`);
+      return null;
+    }
     const data = {
-      title: this.cleanText(section.header)
+      title
     };
     if (truncatedSupport) {
       data.body = truncatedSupport;
@@ -7606,13 +7699,63 @@ var PowerPointGenerator = class {
 
 // src/generators/PDFGenerator.ts
 import puppeteer from "puppeteer";
+var cachedBrowser = null;
+var browserIdleTimeout = null;
+var BROWSER_IDLE_MS = 3e4;
 var PDFGenerator = class {
   defaultOptions = {
     orientation: "landscape",
     printBackground: true,
     format: "Slide",
-    scale: 1
+    scale: 1,
+    reuseBrowser: true
   };
+  /**
+   * Get or create a browser instance
+   */
+  async getBrowser(reuse) {
+    if (browserIdleTimeout) {
+      clearTimeout(browserIdleTimeout);
+      browserIdleTimeout = null;
+    }
+    if (reuse && cachedBrowser && cachedBrowser.connected) {
+      logger.progress("Using cached browser instance");
+      return cachedBrowser;
+    }
+    if (cachedBrowser && !cachedBrowser.connected) {
+      cachedBrowser = null;
+    }
+    logger.progress("Launching new browser instance...");
+    const browser = await puppeteer.launch({
+      headless: true,
+      args: [
+        "--no-sandbox",
+        "--disable-setuid-sandbox",
+        "--disable-dev-shm-usage",
+        "--disable-gpu"
+      ]
+    });
+    if (reuse) {
+      cachedBrowser = browser;
+    }
+    return browser;
+  }
+  /**
+   * Schedule browser cleanup after idle period
+   */
+  scheduleBrowserCleanup() {
+    if (browserIdleTimeout) {
+      clearTimeout(browserIdleTimeout);
+    }
+    browserIdleTimeout = setTimeout(async () => {
+      if (cachedBrowser) {
+        logger.progress("Closing idle browser instance");
+        await cachedBrowser.close().catch(() => {
+        });
+        cachedBrowser = null;
+      }
+    }, BROWSER_IDLE_MS);
+  }
   /**
    * Generate PDF from HTML presentation
    * @param html - The HTML content of the presentation
@@ -7621,18 +7764,14 @@ var PDFGenerator = class {
    */
   async generate(html, options = {}) {
     const opts = { ...this.defaultOptions, ...options };
+    const reuseBrowser = opts.reuseBrowser ?? true;
     logger.progress("\u{1F4C4} Generating PDF...");
-    let browser;
+    let browser = null;
+    let shouldCloseBrowser = !reuseBrowser;
+    let page = null;
     try {
-      browser = await puppeteer.launch({
-        headless: true,
-        args: [
-          "--no-sandbox",
-          "--disable-setuid-sandbox",
-          "--disable-dev-shm-usage"
-        ]
-      });
-      const page = await browser.newPage();
+      browser = await this.getBrowser(reuseBrowser);
+      page = await browser.newPage();
       const printHtml = this.preparePrintHtml(html);
       await page.setViewport({
         width: 1920,
@@ -7668,13 +7807,38 @@ var PDFGenerator = class {
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       logger.error(`PDF generation failed: ${errorMessage}`);
+      shouldCloseBrowser = true;
       throw new Error(`PDF generation failed: ${errorMessage}`);
     } finally {
-      if (browser) {
-        await browser.close();
+      if (page) {
+        await page.close().catch(() => {
+        });
+      }
+      if (shouldCloseBrowser && browser) {
+        await browser.close().catch(() => {
+        });
+        if (browser === cachedBrowser) {
+          cachedBrowser = null;
+        }
+      } else if (reuseBrowser) {
+        this.scheduleBrowserCleanup();
       }
     }
   }
+  /**
+   * Manually close the cached browser (call before process exit)
+   */
+  static async closeBrowser() {
+    if (browserIdleTimeout) {
+      clearTimeout(browserIdleTimeout);
+      browserIdleTimeout = null;
+    }
+    if (cachedBrowser) {
+      await cachedBrowser.close().catch(() => {
+      });
+      cachedBrowser = null;
+    }
+  }
   /**
    * Prepare HTML for print/PDF output
    * Modifies the HTML to work better as a printed document
@@ -7688,12 +7852,24 @@ var PDFGenerator = class {
           margin: 0;
         }
 
+        /* Font rendering optimization for print */
+        * {
+          -webkit-font-smoothing: antialiased;
+          -moz-osx-font-smoothing: grayscale;
+          text-rendering: optimizeLegibility;
+          font-feature-settings: "liga" 1, "kern" 1;
+        }
+
         @media print {
           html, body {
             margin: 0;
             padding: 0;
             width: 1920px;
             height: 1080px;
+            /* Print color optimization */
+            color-adjust: exact;
+            -webkit-print-color-adjust: exact;
+            print-color-adjust: exact;
           }
 
           .reveal .slides {
@@ -7710,7 +7886,8 @@ var PDFGenerator = class {
             width: 1920px !important;
             height: 1080px !important;
             margin: 0 !important;
-            padding: 60px !important;
+            /* Professional safe margins: 80px (4.2%) */
+            padding: 80px !important;
             box-sizing: border-box;
             position: relative !important;
             top: auto !important;
@@ -7734,7 +7911,7 @@ var PDFGenerator = class {
           }
 
           /* Disable animations for print */
-          * {
+          *, *::before, *::after {
             animation: none !important;
             transition: none !important;
           }
@@ -7750,6 +7927,30 @@ var PDFGenerator = class {
           .reveal .navigate-down {
             display: none !important;
           }
+
+          /* Typography refinements for print */
+          h1, h2, h3, h4 {
+            orphans: 3;
+            widows: 3;
+            page-break-after: avoid;
+          }
+
+          p, li {
+            orphans: 2;
+            widows: 2;
+          }
+
+          /* Ensure links are readable in print */
+          a {
+            text-decoration: none;
+          }
+
+          /* Prevent image overflow */
+          img {
+            max-width: 100%;
+            height: auto;
+            page-break-inside: avoid;
+          }
         }
 
         /* Force print mode in Puppeteer */
@@ -7757,6 +7958,11 @@ var PDFGenerator = class {
           page-break-after: always;
           page-break-inside: avoid;
         }
+
+        /* High contrast mode for business presentations */
+        .reveal section {
+          color-scheme: light;
+        }
       </style>
     `;
     if (html.includes("</head>")) {
@@ -8349,6 +8555,7 @@ export {
   CompositeImageProvider,
   ContentAnalyzer,
   ContentPatternClassifier,
+  KnowledgeBaseError,
   KnowledgeGateway,
   LocalImageProvider,
   MermaidProvider,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-presentation-master",
-  "version": "8.1.0",
+  "version": "8.2.0",
   "description": "Generate world-class presentations using expert methodologies from Duarte, Reynolds, Gallo, and Anderson. Enforces rigorous quality standards through real visual validation.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",