Updated lesson 10 - debugging and fixed a bug that caused invalid components to be generated in slideshows

Author: ofriw

scripts/audit-presentations.js

@@ -15,6 +15,25 @@ const MIN_ITEMS = 3;
 const MAX_ITEMS = 5;
 const MAX_WORDS = 5;
 
+// Single source of truth: RevealSlideshow.tsx
+const REVEAL_SLIDESHOW_PATH = join(
+  __dirname,
+  '../website/src/components/PresentationMode/RevealSlideshow.tsx'
+);
+
+function getValidVisualComponents() {
+  const content = readFileSync(REVEAL_SLIDESHOW_PATH, 'utf-8');
+  const match = content.match(/const VISUAL_COMPONENTS = \{([^}]+)\}/);
+  if (!match) {
+    throw new Error('Could not find VISUAL_COMPONENTS in RevealSlideshow.tsx');
+  }
+  return match[1]
+    .split(',')
+    .map(line => line.trim())
+    .filter(line => line && !line.startsWith('//'))
+    .map(line => line.split(':')[0].trim());
+}
+
 function auditPresentation(filePath) {
   const content = readFileSync(filePath, 'utf-8');
   const presentation = JSON.parse(content);
@@ -108,10 +127,24 @@ function auditPresentation(filePath) {
     }
   });
 
+  // Check visual component references
+  const validComponents = getValidVisualComponents();
+  const componentViolations = [];
+  const visualSlides = presentation.slides.filter(s => s.type === 'visual');
+  for (const slide of visualSlides) {
+    if (slide.component && !validComponents.includes(slide.component)) {
+      componentViolations.push({
+        slide: slide.title,
+        component: slide.component
+      });
+    }
+  }
+
   return {
     title: presentation.metadata?.title || 'Unknown',
     violations,
     wordCountViolations,
+    componentViolations,
     totalSlides: presentation.slides.length
   };
 }
@@ -136,11 +169,13 @@ function main() {
   console.log('Checking:');
   console.log('  • Content arrays (3-5 items rule)');
   console.log('  • Takeaway word counts (5 words max)');
-  console.log('  • Learning objectives word counts (5 words max)\n');
+  console.log('  • Learning objectives word counts (5 words max)');
+  console.log('  • Visual component references (must be registered)\n');
 
   const results = [];
   let totalViolations = 0;
   let totalWordCountViolations = 0;
+  let totalComponentViolations = 0;
 
   for (const file of files) {
     const filePath = join(presentationsDir, file);
@@ -150,8 +185,9 @@ function main() {
 
       const hasViolations = result.violations.length > 0;
       const hasWordViolations = result.wordCountViolations.length > 0;
+      const hasComponentViolations = result.componentViolations.length > 0;
 
-      if (hasViolations || hasWordViolations) {
+      if (hasViolations || hasWordViolations || hasComponentViolations) {
         console.log(`❌ ${file}`);
         console.log(`   Title: ${result.title}`);
 
@@ -183,6 +219,14 @@ function main() {
           });
         }
 
+        if (hasComponentViolations) {
+          totalComponentViolations += result.componentViolations.length;
+          console.log(`   Invalid visual components (${result.componentViolations.length}):`);
+          result.componentViolations.forEach(v => {
+            console.log(`   - Slide "${v.slide}": component "${v.component}" is not registered`);
+          });
+        }
+
         console.log('');
       }
     } catch (error) {
@@ -192,7 +236,9 @@ function main() {
 
   // Summary
   console.log('═══════════════════════════════════════════════════════════');
-  const violatingFiles = results.filter(r => r.violations.length > 0 || r.wordCountViolations.length > 0);
+  const violatingFiles = results.filter(r =>
+    r.violations.length > 0 || r.wordCountViolations.length > 0 || r.componentViolations.length > 0
+  );
 
   if (violatingFiles.length === 0) {
     console.log('✅ All presentations pass validation!');
@@ -202,15 +248,18 @@ function main() {
     console.log(`Files with violations: ${violatingFiles.length}`);
     console.log(`  • Content array violations: ${totalViolations}`);
     console.log(`  • Word count violations: ${totalWordCountViolations}`);
-    console.log(`  • Total: ${totalViolations + totalWordCountViolations}\n`);
+    console.log(`  • Invalid component violations: ${totalComponentViolations}`);
+    console.log(`  • Total: ${totalViolations + totalWordCountViolations + totalComponentViolations}\n`);
     console.log('Files needing regeneration:');
     violatingFiles.forEach(r => {
       const arrayViolations = r.violations.length;
       const wordViolations = r.wordCountViolations.length;
-      const total = arrayViolations + wordViolations;
+      const compViolations = r.componentViolations.length;
+      const total = arrayViolations + wordViolations + compViolations;
       const details = [];
       if (arrayViolations > 0) details.push(`${arrayViolations} array`);
       if (wordViolations > 0) details.push(`${wordViolations} word`);
+      if (compViolations > 0) details.push(`${compViolations} component`);
       console.log(`  - ${r.file} (${total} total: ${details.join(', ')})`);
     });
   }

scripts/generate-presentation.js

@@ -45,6 +45,33 @@ const DOCS_DIR = join(__dirname, "../website/docs");
 const OUTPUT_DIR = join(__dirname, "output/presentations");
 const STATIC_OUTPUT_DIR = join(__dirname, "../website/static/presentations");
 const MANIFEST_PATH = join(OUTPUT_DIR, "manifest.json");
+const REVEAL_SLIDESHOW_PATH = join(
+  __dirname,
+  "../website/src/components/PresentationMode/RevealSlideshow.tsx",
+);
+
+/**
+ * Extract valid visual component names from RevealSlideshow.tsx
+ * Single source of truth: the VISUAL_COMPONENTS object in the renderer
+ */
+function getValidVisualComponents() {
+  const content = readFileSync(REVEAL_SLIDESHOW_PATH, "utf-8");
+  const match = content.match(
+    /const VISUAL_COMPONENTS = \{([^}]+)\}/,
+  );
+  if (!match) {
+    throw new Error(
+      "Could not find VISUAL_COMPONENTS in RevealSlideshow.tsx",
+    );
+  }
+  // Extract component names (the keys of the object)
+  const componentNames = match[1]
+    .split(",")
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith("//"))
+    .map((line) => line.split(":")[0].trim());
+  return componentNames;
+}
 
 // Parse command-line arguments
 function parseArgs() {
@@ -114,7 +141,8 @@ PRESENTATION STRUCTURE REQUIREMENTS:
   - Discussion prompts or questions to ask students
   - Real-world examples to reference
 ✓ DO: Preserve important code examples as slide content
-✓ DO: Identify which visual components to use (CapabilityMatrix, UShapeAttentionCurve, WorkflowCircle, GroundingComparison, ContextWindowMeter, AbstractShapesVisualization, etc.)
+✓ DO: ONLY use these registered visual components: ${getValidVisualComponents().join(", ")}
+✗ DO NOT: Invent or reference visual components not in this list
 ✓ DO: Generate exactly 4 learning objectives (no more, no less)
 ✓ DO: Keep each learning objective to 5 words or fewer - THIS IS STRICTLY ENFORCED
   - Good: "Master active context engineering" (4 words) ✓
@@ -134,7 +162,7 @@ SLIDE TYPES:
 4. **Code Comparison Slide**: Side-by-side code examples (especially for prompt examples)
 5. **Code Execution Slide**: Step-by-step visualization of execution flows (agent loops, algorithms, workflows)
 6. **Comparison Slide**: Effective vs ineffective patterns (bullet points)
-7. **Visual Slide**: Custom component (CapabilityMatrix, etc.)
+7. **Visual Slide**: ONLY when source has [VISUAL_COMPONENT: X] marker - NEVER invent components
 8. **Key Takeaway Slide**: Summary of section or lesson
 
 HANDLING CODE BLOCKS:
@@ -354,6 +382,8 @@ Example:
 
 If you see [VISUAL_COMPONENT: X] anywhere in the content, it MUST become a visual slide.
 
+CRITICAL CONSTRAINT: NEVER create a "visual" slide type unless there is an explicit [VISUAL_COMPONENT: X] marker in the source content. Do NOT invent visual components. If no marker exists, use "concept", "comparison", or "codeExecution" slide types instead.
+
 CODE EXECUTION SLIDES:
 
 Use the "codeExecution" slide type to visualize step-by-step processes like:
@@ -660,7 +690,7 @@ Like regular comparison slides, codeComparison also supports the "neutral" flag:
     {
       "type": "visual",
       "title": "Visual Component",
-      "component": "CapabilityMatrix | UShapeAttentionCurve | WorkflowCircle | GroundingComparison | ContextWindowMeter | AbstractShapesVisualization",
+      "component": "${getValidVisualComponents().join(" | ")}",
       "caption": "Description of what the visual shows",
       "speakerNotes": { ... }
     },
@@ -974,6 +1004,35 @@ function validateComponents(content, presentation) {
   };
 }
 
+/**
+ * Validate that visual slides reference registered components
+ * Prevents AI from inventing non-existent component names
+ * @param {object} presentation - Generated presentation object
+ * @returns {object} Validation result with invalid component references
+ */
+function validateVisualComponentsExist(presentation) {
+  const validComponents = getValidVisualComponents();
+  const visualSlides = presentation.slides.filter((s) => s.type === "visual");
+  const issues = [];
+
+  for (const slide of visualSlides) {
+    if (slide.component && !validComponents.includes(slide.component)) {
+      issues.push({
+        slide: slide.title,
+        component: slide.component,
+        reason: `Component "${slide.component}" is not registered`,
+      });
+    }
+  }
+
+  return {
+    valid: issues.length === 0,
+    issues,
+    totalVisualSlides: visualSlides.length,
+    validComponents,
+  };
+}
+
 /**
  * Validate semantic correctness of comparison slides
  * Checks that better/effective options are on the RIGHT (green ✓)
@@ -1492,6 +1551,29 @@ async function generatePresentation(filePath, manifest, config) {
     // This allows us to write the presentation file even when validation fails
     const validationErrors = [];
 
+    // Validate visual components exist in registry
+    // CRITICAL: This prevents AI from inventing non-existent components
+    const componentRegistryValidation =
+      validateVisualComponentsExist(presentation);
+    if (!componentRegistryValidation.valid) {
+      console.log(
+        `  ❌ BUILD FAILURE: ${componentRegistryValidation.issues.length} invalid visual component(s):`,
+      );
+      componentRegistryValidation.issues.forEach((issue) => {
+        console.log(`      - Slide "${issue.slide}": ${issue.reason}`);
+      });
+      console.log(
+        `  ℹ️  Valid components: ${componentRegistryValidation.validComponents.join(", ")}`,
+      );
+      validationErrors.push(
+        "Visual component validation failed - slides reference non-existent components",
+      );
+    } else if (componentRegistryValidation.totalVisualSlides > 0) {
+      console.log(
+        `  ✅ All ${componentRegistryValidation.totalVisualSlides} visual slide(s) reference valid components`,
+      );
+    }
+
     // Validate content array lengths (3-5 items)
     // CRITICAL: This validation is intentionally strict and throws an error because
     // slides with too many bullets become unreadable and overflow the layout.