claude-presentation-master 4.2.0 → 4.3.0

package/dist/index.d.mts

@@ -538,7 +538,10 @@ declare function initContentAnalyzer(): Promise<ContentAnalyzer>;
  * - Respect for KB word limits and rules
  * - SCQA/Sparkline narrative structure when detected
  *
- * ALL decisions come from the Knowledge Base. NO hardcoded fallbacks.
+ * DESIGN PHILOSOPHY:
+ * - All type-specific rules (word limits, allowed slide types) come from KB
+ * - Defensive fallbacks exist for edge cases (e.g., bullet limit defaults to 5)
+ * - Slide structure decisions (agenda, section dividers) are algorithmic
  */
 
 declare class SlideGenerator {
@@ -935,6 +938,150 @@ declare class RendererV2 {
  */
 declare function createRendererV2(presentationType?: PresentationType, kb?: KnowledgeGateway): RendererV2;
 
+/**
+ * VisualQAEngine - REAL Visual Quality Assurance
+ *
+ * This is NOT a rule checker. This SEES the actual rendered presentation.
+ *
+ * How it works:
+ * 1. Playwright renders the HTML presentation
+ * 2. Screenshots each slide at 1920x1080
+ * 3. Analyzes screenshots with:
+ *    - Pixel-based whitespace calculation
+ *    - Color contrast checking (WCAG)
+ *    - Text density measurement
+ *    - Visual balance assessment
+ * 4. Vision API for qualitative "would you present this?" check
+ * 5. Scores against KB criteria
+ * 6. Provides specific visual feedback
+ * 7. Loops until 95+ or max iterations
+ *
+ * This is the REAL QA that evaluates what the audience SEES.
+ */
+
+interface VisualSlideAnalysis {
+    slideIndex: number;
+    title: string;
+    screenshot: Buffer;
+    whitespacePercentage: number;
+    textDensity: number;
+    colorContrast: number;
+    visualBalance: number;
+    glanceTestPassed: boolean;
+    hierarchyClear: boolean;
+    professionalLook: boolean;
+    score: number;
+    issues: VisualIssue[];
+    passed: boolean;
+}
+interface VisualIssue {
+    severity: 'critical' | 'major' | 'minor';
+    category: 'whitespace' | 'contrast' | 'density' | 'balance' | 'hierarchy' | 'professional';
+    issue: string;
+    measurement?: number;
+    threshold?: number;
+    fix: string;
+}
+interface VisualDeckAnalysis {
+    slides: VisualSlideAnalysis[];
+    overallScore: number;
+    passed: boolean;
+    consistency: number;
+    deckIssues: string[];
+    summary: string;
+}
+interface RemediationFeedback {
+    slideIndex: number;
+    currentScore: number;
+    targetScore: number;
+    specificFixes: string[];
+    visualProblems: string[];
+}
+interface QALoopResult {
+    finalScore: number;
+    passed: boolean;
+    iterations: number;
+    initialScore: number;
+    improvements: string[];
+    finalAnalysis: VisualDeckAnalysis;
+}
+declare class VisualQAEngine {
+    private kb;
+    private browser;
+    private initialized;
+    private minWhitespace;
+    private minContrast;
+    private maxWordsPerSlide;
+    private targetScore;
+    constructor();
+    /**
+     * Initialize Playwright browser.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Load quality thresholds from Knowledge Base.
+     */
+    private loadKBThresholds;
+    /**
+     * Capture screenshots of all slides in a presentation.
+     */
+    captureSlides(html: string): Promise<Buffer[]>;
+    /**
+     * Analyze a single slide screenshot.
+     */
+    analyzeSlide(screenshot: Buffer, slideIndex: number, slideTitle: string, presentationType: PresentationType): Promise<VisualSlideAnalysis>;
+    /**
+     * Analyze entire deck visually.
+     */
+    analyzeDeck(html: string, slides: SlideV2[], presentationType: PresentationType): Promise<VisualDeckAnalysis>;
+    /**
+     * Generate remediation feedback for failing slides.
+     */
+    generateRemediationFeedback(analysis: VisualDeckAnalysis): RemediationFeedback[];
+    /**
+     * Run the full QA loop until passing or max iterations.
+     */
+    runQALoop(generateFn: () => Promise<{
+        html: string;
+        slides: SlideV2[];
+    }>, remediateFn: (feedback: RemediationFeedback[]) => Promise<void>, presentationType: PresentationType, maxIterations?: number): Promise<QALoopResult>;
+    /**
+     * Close browser and cleanup.
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Measure whitespace percentage from screenshot.
+     * Uses actual pixel analysis.
+     */
+    private measureWhitespace;
+    /**
+     * Measure color contrast ratio.
+     */
+    private measureContrast;
+    /**
+     * Measure text density (approximation based on non-background pixels).
+     */
+    private measureTextDensity;
+    /**
+     * Measure visual balance (how evenly distributed is the content).
+     * Uses a 3x3 grid to properly detect centered layouts (common in keynotes).
+     */
+    private measureBalance;
+    /**
+     * Check if there's clear visual hierarchy.
+     */
+    private checkHierarchy;
+    private getTypeThresholds;
+    private detectBackgroundColor;
+    private detectTextColor;
+    private isSimilarColor;
+    private relativeLuminance;
+    private calculateConsistency;
+    private variance;
+}
+declare function getVisualQAEngine(): VisualQAEngine;
+declare function initVisualQAEngine(): Promise<VisualQAEngine>;
+
 /**
  * PresentationEngineV2 - Knowledge-Driven Excellence
  *
@@ -946,9 +1093,14 @@ declare function createRendererV2(presentationType?: PresentationType, kb?: Know
  * 5. Review ruthlessly (must score 95/100+)
  * 6. Output ONLY if quality passes
  *
- * CRITICAL: The Knowledge Base drives EVERYTHING.
- * The KnowledgeGateway reads from presentation-knowledge.yaml at runtime.
- * NO hardcoded fallbacks - if KB is missing data, we fail loudly.
+ * DESIGN PHILOSOPHY:
+ * - The Knowledge Base (YAML) is the single source of truth for all design decisions
+ * - Uses KnowledgeGateway.queryRequired() for critical paths (throws on missing data)
+ * - Defensive fallbacks exist only for:
+ *   1. Optional fields that may not exist in older KB versions
+ *   2. Type coercion safety (undefined → default string)
+ *   3. Map lookups that might fail for new palette names
+ * - Critical errors (missing presentation types, validation rules) will throw
  */
 
 interface DesignSpecs {
@@ -1011,6 +1163,14 @@ interface EngineOptions {
     verbose?: boolean;
     /** Maximum remediation attempts per slide */
     maxRemediationAttempts?: number;
+    /** Run visual QA analysis using Playwright screenshots (default: false) */
+    runVisualQA?: boolean;
+    /**
+     * Use V1's richer slide generation pipeline (default: true)
+     * V1 creates agenda, section dividers, SCQA structure, metrics, STAR moments, call-to-action
+     * V2 is minimalist - just sections parsed from markdown
+     */
+    useRichPipeline?: boolean;
 }
 interface EngineResult {
     slides: SlideV2[];
@@ -1020,6 +1180,8 @@ interface EngineResult {
     designSpecs: DesignSpecs;
     review: DeckReview;
     warnings: string[];
+    /** Visual QA analysis (only present if runVisualQA option is true) */
+    visualQA?: VisualDeckAnalysis;
 }
 declare class PresentationEngineV2 {
     private options;
@@ -1802,7 +1964,11 @@ declare function runCodeQualityCheck(srcDir: string): Promise<boolean>;
  * 5. DeckQualityReviewer -> Holistic deck review (must pass 95)
  * 6. Renderer -> Premium HTML/PPTX output
  *
- * ALL decisions come from the Knowledge Base. NO hardcoded fallbacks.
+ * DESIGN PHILOSOPHY:
+ * - The Knowledge Base (YAML) is the source of truth for all design decisions
+ * - Critical paths use queryRequired() which throws on missing data
+ * - Defensive fallbacks exist for optional fields and type safety
+ * - Both V1 (generate) and V2 (generatePresentation) APIs use the same KB
  */
 
 declare const VERSION = "4.2.0";
@@ -1874,4 +2040,4 @@ interface GenerateResult {
  */
 declare function generate(options: GenerateOptions): Promise<GenerateResult>;
 
-export { CodeQualityValidator, type ValidationResult as CodeValidationResult, type ContentAnalysis, ContentAnalyzer, DeckQualityReviewer, type DeckScore, type GenerateOptions, type GenerateResult, type HardcodedViolation, type ImageGenerationRequest, type ImageGenerationResult, KnowledgeGateway, type MetricData, type NanoBananaConfig, NanoBananaProvider, type OutputFormat, PresentationEngineV2, type PresentationMetadata, type PresentationMode, type PresentationResult, type PresentationType, type QualitativeDeckReview, type QualitativeSlideReview, type RemediationResult, Remediator, Renderer, RendererV2, type Slide, type SlideContent as SlideContentV2, SlideGenerator, SlideGeneratorV2, SlideQualityReviewer, type SlideScore, type SlideType as SlideTypeV2, type SlideV2, type TableData, VERSION, type Violation, VisualDesignSystem, createNanoBananaProvider, createPresentationEngineV2, createRendererV2, createSlideGeneratorV2, generate, generatePresentation, getContentAnalyzer, getDeckQualityReviewer, getKB, getNanoBananaPrompt, getRemediator, getRenderer, getSlideGenerator, getSlideQualityReviewer, getVisualDesignSystem, initContentAnalyzer, initDeckQualityReviewer, initKB, initRemediator, initRenderer, initSlideGenerator, initSlideQualityReviewer, initVisualDesignSystem, runCodeQualityCheck, validateCodeQuality };
+export { CodeQualityValidator, type ValidationResult as CodeValidationResult, type ContentAnalysis, ContentAnalyzer, DeckQualityReviewer, type DeckScore, type GenerateOptions, type GenerateResult, type HardcodedViolation, type ImageGenerationRequest, type ImageGenerationResult, KnowledgeGateway, type MetricData, type NanoBananaConfig, NanoBananaProvider, type OutputFormat, PresentationEngineV2, type PresentationMetadata, type PresentationMode, type PresentationResult, type PresentationType, type QALoopResult, type QualitativeDeckReview, type QualitativeSlideReview, type RemediationFeedback, type RemediationResult, Remediator, Renderer, RendererV2, type Slide, type SlideContent as SlideContentV2, SlideGenerator, SlideGeneratorV2, SlideQualityReviewer, type SlideScore, type SlideType as SlideTypeV2, type SlideV2, type TableData, VERSION, type Violation, type VisualDeckAnalysis, VisualDesignSystem, VisualQAEngine, type VisualSlideAnalysis, createNanoBananaProvider, createPresentationEngineV2, createRendererV2, createSlideGeneratorV2, generate, generatePresentation, getContentAnalyzer, getDeckQualityReviewer, getKB, getNanoBananaPrompt, getRemediator, getRenderer, getSlideGenerator, getSlideQualityReviewer, getVisualDesignSystem, getVisualQAEngine, initContentAnalyzer, initDeckQualityReviewer, initKB, initRemediator, initRenderer, initSlideGenerator, initSlideQualityReviewer, initVisualDesignSystem, initVisualQAEngine, runCodeQualityCheck, validateCodeQuality };

package/dist/index.d.ts

@@ -538,7 +538,10 @@ declare function initContentAnalyzer(): Promise<ContentAnalyzer>;
  * - Respect for KB word limits and rules
  * - SCQA/Sparkline narrative structure when detected
  *
- * ALL decisions come from the Knowledge Base. NO hardcoded fallbacks.
+ * DESIGN PHILOSOPHY:
+ * - All type-specific rules (word limits, allowed slide types) come from KB
+ * - Defensive fallbacks exist for edge cases (e.g., bullet limit defaults to 5)
+ * - Slide structure decisions (agenda, section dividers) are algorithmic
  */
 
 declare class SlideGenerator {
@@ -935,6 +938,150 @@ declare class RendererV2 {
  */
 declare function createRendererV2(presentationType?: PresentationType, kb?: KnowledgeGateway): RendererV2;
 
+/**
+ * VisualQAEngine - REAL Visual Quality Assurance
+ *
+ * This is NOT a rule checker. This SEES the actual rendered presentation.
+ *
+ * How it works:
+ * 1. Playwright renders the HTML presentation
+ * 2. Screenshots each slide at 1920x1080
+ * 3. Analyzes screenshots with:
+ *    - Pixel-based whitespace calculation
+ *    - Color contrast checking (WCAG)
+ *    - Text density measurement
+ *    - Visual balance assessment
+ * 4. Vision API for qualitative "would you present this?" check
+ * 5. Scores against KB criteria
+ * 6. Provides specific visual feedback
+ * 7. Loops until 95+ or max iterations
+ *
+ * This is the REAL QA that evaluates what the audience SEES.
+ */
+
+interface VisualSlideAnalysis {
+    slideIndex: number;
+    title: string;
+    screenshot: Buffer;
+    whitespacePercentage: number;
+    textDensity: number;
+    colorContrast: number;
+    visualBalance: number;
+    glanceTestPassed: boolean;
+    hierarchyClear: boolean;
+    professionalLook: boolean;
+    score: number;
+    issues: VisualIssue[];
+    passed: boolean;
+}
+interface VisualIssue {
+    severity: 'critical' | 'major' | 'minor';
+    category: 'whitespace' | 'contrast' | 'density' | 'balance' | 'hierarchy' | 'professional';
+    issue: string;
+    measurement?: number;
+    threshold?: number;
+    fix: string;
+}
+interface VisualDeckAnalysis {
+    slides: VisualSlideAnalysis[];
+    overallScore: number;
+    passed: boolean;
+    consistency: number;
+    deckIssues: string[];
+    summary: string;
+}
+interface RemediationFeedback {
+    slideIndex: number;
+    currentScore: number;
+    targetScore: number;
+    specificFixes: string[];
+    visualProblems: string[];
+}
+interface QALoopResult {
+    finalScore: number;
+    passed: boolean;
+    iterations: number;
+    initialScore: number;
+    improvements: string[];
+    finalAnalysis: VisualDeckAnalysis;
+}
+declare class VisualQAEngine {
+    private kb;
+    private browser;
+    private initialized;
+    private minWhitespace;
+    private minContrast;
+    private maxWordsPerSlide;
+    private targetScore;
+    constructor();
+    /**
+     * Initialize Playwright browser.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Load quality thresholds from Knowledge Base.
+     */
+    private loadKBThresholds;
+    /**
+     * Capture screenshots of all slides in a presentation.
+     */
+    captureSlides(html: string): Promise<Buffer[]>;
+    /**
+     * Analyze a single slide screenshot.
+     */
+    analyzeSlide(screenshot: Buffer, slideIndex: number, slideTitle: string, presentationType: PresentationType): Promise<VisualSlideAnalysis>;
+    /**
+     * Analyze entire deck visually.
+     */
+    analyzeDeck(html: string, slides: SlideV2[], presentationType: PresentationType): Promise<VisualDeckAnalysis>;
+    /**
+     * Generate remediation feedback for failing slides.
+     */
+    generateRemediationFeedback(analysis: VisualDeckAnalysis): RemediationFeedback[];
+    /**
+     * Run the full QA loop until passing or max iterations.
+     */
+    runQALoop(generateFn: () => Promise<{
+        html: string;
+        slides: SlideV2[];
+    }>, remediateFn: (feedback: RemediationFeedback[]) => Promise<void>, presentationType: PresentationType, maxIterations?: number): Promise<QALoopResult>;
+    /**
+     * Close browser and cleanup.
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Measure whitespace percentage from screenshot.
+     * Uses actual pixel analysis.
+     */
+    private measureWhitespace;
+    /**
+     * Measure color contrast ratio.
+     */
+    private measureContrast;
+    /**
+     * Measure text density (approximation based on non-background pixels).
+     */
+    private measureTextDensity;
+    /**
+     * Measure visual balance (how evenly distributed is the content).
+     * Uses a 3x3 grid to properly detect centered layouts (common in keynotes).
+     */
+    private measureBalance;
+    /**
+     * Check if there's clear visual hierarchy.
+     */
+    private checkHierarchy;
+    private getTypeThresholds;
+    private detectBackgroundColor;
+    private detectTextColor;
+    private isSimilarColor;
+    private relativeLuminance;
+    private calculateConsistency;
+    private variance;
+}
+declare function getVisualQAEngine(): VisualQAEngine;
+declare function initVisualQAEngine(): Promise<VisualQAEngine>;
+
 /**
  * PresentationEngineV2 - Knowledge-Driven Excellence
  *
@@ -946,9 +1093,14 @@ declare function createRendererV2(presentationType?: PresentationType, kb?: Know
  * 5. Review ruthlessly (must score 95/100+)
  * 6. Output ONLY if quality passes
  *
- * CRITICAL: The Knowledge Base drives EVERYTHING.
- * The KnowledgeGateway reads from presentation-knowledge.yaml at runtime.
- * NO hardcoded fallbacks - if KB is missing data, we fail loudly.
+ * DESIGN PHILOSOPHY:
+ * - The Knowledge Base (YAML) is the single source of truth for all design decisions
+ * - Uses KnowledgeGateway.queryRequired() for critical paths (throws on missing data)
+ * - Defensive fallbacks exist only for:
+ *   1. Optional fields that may not exist in older KB versions
+ *   2. Type coercion safety (undefined → default string)
+ *   3. Map lookups that might fail for new palette names
+ * - Critical errors (missing presentation types, validation rules) will throw
  */
 
 interface DesignSpecs {
@@ -1011,6 +1163,14 @@ interface EngineOptions {
     verbose?: boolean;
     /** Maximum remediation attempts per slide */
     maxRemediationAttempts?: number;
+    /** Run visual QA analysis using Playwright screenshots (default: false) */
+    runVisualQA?: boolean;
+    /**
+     * Use V1's richer slide generation pipeline (default: true)
+     * V1 creates agenda, section dividers, SCQA structure, metrics, STAR moments, call-to-action
+     * V2 is minimalist - just sections parsed from markdown
+     */
+    useRichPipeline?: boolean;
 }
 interface EngineResult {
     slides: SlideV2[];
@@ -1020,6 +1180,8 @@ interface EngineResult {
     designSpecs: DesignSpecs;
     review: DeckReview;
     warnings: string[];
+    /** Visual QA analysis (only present if runVisualQA option is true) */
+    visualQA?: VisualDeckAnalysis;
 }
 declare class PresentationEngineV2 {
     private options;
@@ -1802,7 +1964,11 @@ declare function runCodeQualityCheck(srcDir: string): Promise<boolean>;
  * 5. DeckQualityReviewer -> Holistic deck review (must pass 95)
  * 6. Renderer -> Premium HTML/PPTX output
  *
- * ALL decisions come from the Knowledge Base. NO hardcoded fallbacks.
+ * DESIGN PHILOSOPHY:
+ * - The Knowledge Base (YAML) is the source of truth for all design decisions
+ * - Critical paths use queryRequired() which throws on missing data
+ * - Defensive fallbacks exist for optional fields and type safety
+ * - Both V1 (generate) and V2 (generatePresentation) APIs use the same KB
  */
 
 declare const VERSION = "4.2.0";
@@ -1874,4 +2040,4 @@ interface GenerateResult {
  */
 declare function generate(options: GenerateOptions): Promise<GenerateResult>;
 
-export { CodeQualityValidator, type ValidationResult as CodeValidationResult, type ContentAnalysis, ContentAnalyzer, DeckQualityReviewer, type DeckScore, type GenerateOptions, type GenerateResult, type HardcodedViolation, type ImageGenerationRequest, type ImageGenerationResult, KnowledgeGateway, type MetricData, type NanoBananaConfig, NanoBananaProvider, type OutputFormat, PresentationEngineV2, type PresentationMetadata, type PresentationMode, type PresentationResult, type PresentationType, type QualitativeDeckReview, type QualitativeSlideReview, type RemediationResult, Remediator, Renderer, RendererV2, type Slide, type SlideContent as SlideContentV2, SlideGenerator, SlideGeneratorV2, SlideQualityReviewer, type SlideScore, type SlideType as SlideTypeV2, type SlideV2, type TableData, VERSION, type Violation, VisualDesignSystem, createNanoBananaProvider, createPresentationEngineV2, createRendererV2, createSlideGeneratorV2, generate, generatePresentation, getContentAnalyzer, getDeckQualityReviewer, getKB, getNanoBananaPrompt, getRemediator, getRenderer, getSlideGenerator, getSlideQualityReviewer, getVisualDesignSystem, initContentAnalyzer, initDeckQualityReviewer, initKB, initRemediator, initRenderer, initSlideGenerator, initSlideQualityReviewer, initVisualDesignSystem, runCodeQualityCheck, validateCodeQuality };
+export { CodeQualityValidator, type ValidationResult as CodeValidationResult, type ContentAnalysis, ContentAnalyzer, DeckQualityReviewer, type DeckScore, type GenerateOptions, type GenerateResult, type HardcodedViolation, type ImageGenerationRequest, type ImageGenerationResult, KnowledgeGateway, type MetricData, type NanoBananaConfig, NanoBananaProvider, type OutputFormat, PresentationEngineV2, type PresentationMetadata, type PresentationMode, type PresentationResult, type PresentationType, type QALoopResult, type QualitativeDeckReview, type QualitativeSlideReview, type RemediationFeedback, type RemediationResult, Remediator, Renderer, RendererV2, type Slide, type SlideContent as SlideContentV2, SlideGenerator, SlideGeneratorV2, SlideQualityReviewer, type SlideScore, type SlideType as SlideTypeV2, type SlideV2, type TableData, VERSION, type Violation, type VisualDeckAnalysis, VisualDesignSystem, VisualQAEngine, type VisualSlideAnalysis, createNanoBananaProvider, createPresentationEngineV2, createRendererV2, createSlideGeneratorV2, generate, generatePresentation, getContentAnalyzer, getDeckQualityReviewer, getKB, getNanoBananaPrompt, getRemediator, getRenderer, getSlideGenerator, getSlideQualityReviewer, getVisualDesignSystem, getVisualQAEngine, initContentAnalyzer, initDeckQualityReviewer, initKB, initRemediator, initRenderer, initSlideGenerator, initSlideQualityReviewer, initVisualDesignSystem, initVisualQAEngine, runCodeQualityCheck, validateCodeQuality };