make-slide 2.1.0 → 2.2.0

package/.claude/skills/make-slide/SKILL.md

@@ -74,11 +74,13 @@ Follow these steps in order:
   - 30-min talk → 30–40 slides
 - Identify the target audience and tone (technical, business, casual, academic)
 - Detect the user's language from the conversation — generate content in that language
-- Detect or ask about the desired output format:
-  - **HTML** (default) — Interactive single-file presentation with navigation, animations, and speaker notes
-  - **PPTX** — PowerPoint file for traditional presentation software (Office, Google Slides, Keynote)
-  - If the user mentions "PowerPoint", "pptx", "PPT", ".pptx", "Google Slides", or "Keynote" → use PPTX mode
-  - If unclear, default to HTML and mention PPTX is also available
+- Ask the user about the desired output format (always ask, do not skip):
+  > **Which output format would you like?**
+  > - **HTML** — Interactive single-file presentation you can open in a browser (navigation, animations, speaker notes built-in)
+  > - **PPTX** — PowerPoint file for Office, Google Slides, or Keynote
+  
+  - If the user already mentioned "PowerPoint", "pptx", "PPT", ".pptx", "Google Slides", or "Keynote" in their request → skip the question and use PPTX mode
+  - Otherwise, always ask explicitly before proceeding
 
 ### Step 2: Choose a Theme
 Present the user with the theme gallery link for browsing:
@@ -109,12 +111,16 @@ Ask the user which image approach they prefer:
 
 - **Option A** → Use CSS placeholders matching the theme (emoji, SVG icons, CSS shapes)
 - **Option B** → Mark image positions in the outline, ask user for URLs, use `<img src>` with `loading="lazy"` and descriptive `alt` text
-- **Option C** → For each slide that would benefit from an image:
-  1. Determine a relevant search query based on the slide content
-  2. Search for images using web search (prefer Unsplash, Pexels, or other royalty-free sources)
-  3. Select the most relevant, high-quality result
-  4. Insert as `<img src="URL" alt="description" loading="lazy">`
-  5. Note: Inform the user that auto-searched images are from the web and they should verify licensing for commercial use
+- **Option C** → Automatically search and place images, but be selective:
+  1. NOT every slide needs an image. Only add images to slides where a visual genuinely enhances understanding (e.g., concept slides, example slides, section dividers). Skip images for quote slides, code slides, data/chart slides, comparison slides, and agenda slides.
+  2. Aim for roughly 30-40% of slides having images — not all of them.
+  3. Determine a relevant English search keyword based on the slide content.
+  4. Use Unsplash direct photo URLs: `https://images.unsplash.com/photo-{PHOTO_ID}?w=800&h=600&fit=crop`
+     - To find valid photo IDs, search the web for `site:unsplash.com {keyword}` and extract the photo ID from the URL.
+     - NEVER guess or fabricate Unsplash photo IDs — every URL must come from an actual search result.
+  5. After collecting image URLs, verify each one actually returns an image (HTTP 200) before inserting. Replace any 404 URLs with CSS placeholders.
+  6. Insert as `<img src="URL" alt="description" loading="lazy">`
+  7. Inform the user that images are from Unsplash (Unsplash License, free for commercial use).
 
 ### Step 4: Generate Outline
 Create a slide-by-slide outline with:
@@ -156,6 +162,8 @@ Add speaker notes as `data-notes` attributes on each slide's `<div>`:
 - Expand on the slide text — don't just repeat it
 - Include transitions between slides (e.g., "Now let's move on to...")
 
+**Speaker Notes Panel must be a separate popup window** using `window.open()`. Do NOT render notes inline at the bottom of the slide — this breaks the slide layout. The `S` key should toggle a popup window that shows the current slide's notes and auto-updates on slide change. See `references/html-spec.md` for the implementation pattern.
+
 ### Step 8: Generate Script (Mode A and B only)
 For Mode A and B, also generate a separate `script.md` file containing:
 - Full speaking script organized by slide
@@ -168,13 +176,8 @@ For Mode C, the user already has a script — skip this step.
 ### Step 9: Save and Deliver
 - Save the presentation as `index.html` (or user-specified filename)
 - Save the script as `script.md` (if generated)
-- Offer to start a local server for preview:
-  ```bash
-  # Python
-  python -m http.server 8000
-  # Node.js
-  npx serve .
-  ```
+- Tell the user they can open `index.html` directly in their browser to view the presentation — no server needed
+- The file is fully self-contained (all CSS/JS inlined), so it works by simply double-clicking the file or dragging it into a browser
 
 ---
 
@@ -186,13 +189,42 @@ When the user selects PPTX output, follow this modified workflow:
 Follow the standard HTML generation workflow (Steps 1-7) but with these constraints from the PPTX spec. Read `references/pptx-spec.md` for the complete PPTX conversion rules before generating HTML.
 
 ### PPTX Step 2: Convert HTML to PPTX
-Use the html2pptx conversion pipeline:
-1. Install dependencies if not present: `npm install pptxgenjs sharp puppeteer`
-2. For each HTML slide, render and convert to PPTX using PptxGenJS
-3. Combine all slides into a single `.pptx` file
+Use the screenshot-based conversion pipeline with Puppeteer + PptxGenJS:
+1. Install dependencies if not present: `npm install pptxgenjs puppeteer`
+2. Write a conversion script that:
+   - Opens the HTML file in a headless browser with viewport 1280×720 (16:9)
+   - For EACH slide:
+     a. Navigate to that slide (set it as active, remove active class from others)
+     b. **Wait for ALL animations to complete** — add a delay of at least 1000ms after activating the slide, or better: disable all CSS animations/transitions before capturing by injecting `* { animation: none !important; transition: none !important; }`
+     c. **Hide all other slides completely** — ensure only the current slide is visible (opacity:1, display:flex) and all others are hidden (opacity:0, display:none). This prevents ghost/residue from previous slides.
+     d. Take a full-page screenshot of the viewport at **2x resolution** (deviceScaleFactor: 2) for crisp text
+   - Insert each screenshot into PPTX as a **full-slide image** covering the entire slide area (x:0, y:0, w:'100%', h:'100%')
+   - Do NOT add margins or padding around the image — it should fill the entire slide
+3. Save as `.pptx`
+
+**Critical: Preventing ghost slides and small content**
+```javascript
+// Before each screenshot, inject this CSS to disable animations
+await page.addStyleTag({ content: '*, *::before, *::after { animation: none !important; transition: none !important; animation-delay: 0s !important; }' });
+
+// Hide all slides, then show only current
+await page.evaluate((idx) => {
+  document.querySelectorAll('.slide').forEach((s, i) => {
+    s.style.display = i === idx ? 'flex' : 'none';
+    s.style.opacity = i === idx ? '1' : '0';
+    s.classList.toggle('active', i === idx);
+  });
+}, slideIndex);
+
+// Wait for layout to settle
+await new Promise(r => setTimeout(r, 500));
+
+// Screenshot at 2x for crisp text
+await page.screenshot({ path: outputPath, type: 'png' });
+```
 
 ### PPTX Step 3: Validate and Deliver
-- Open the PPTX to verify content and formatting
+- Verify the PPTX opens correctly and content fills each slide without excess margins
 - Save as `presentation.pptx` (or user-specified filename)
 - Offer to also generate the HTML version for preview
 

package/.claude/skills/make-slide/references/pptx-spec.md

@@ -80,17 +80,64 @@ Workflow:
    - `<img>` → `add_picture()`
 4. Save as .pptx
 
-### Method 3: Screenshot-based (Simplest but lowest quality)
+### Method 3: Screenshot-based (Recommended for visual fidelity)
 ```bash
 npm install puppeteer pptxgenjs
 ```
 
+This is the recommended method when using make-slide themes, because it preserves the exact visual design including custom fonts, gradients, and complex layouts.
+
 Workflow:
 1. Generate full HTML presentation (standard mode, no PPTX constraints needed)
 2. Use Puppeteer to screenshot each slide as high-resolution PNG
 3. Insert each screenshot as a full-slide image in PPTX
-4. Add text overlays for searchability (optional)
-- Note: This produces image-based slides (no editable text) but preserves exact visual design
+4. Note: This produces image-based slides (no editable text) but preserves exact visual design
+
+**Critical implementation details to prevent common issues:**
+
+**Problem: Ghost/residue from previous slides appearing in screenshots**
+```javascript
+// BEFORE capturing, disable ALL animations and transitions
+await page.addStyleTag({ 
+  content: '*, *::before, *::after { animation: none !important; transition: none !important; animation-delay: 0s !important; opacity: 1 !important; }' 
+});
+
+// For each slide, hide ALL others completely
+await page.evaluate((idx) => {
+  document.querySelectorAll('.slide').forEach((s, i) => {
+    if (i === idx) {
+      s.style.display = 'flex';
+      s.style.opacity = '1';
+      s.style.visibility = 'visible';
+      s.classList.add('active');
+    } else {
+      s.style.display = 'none';
+      s.style.opacity = '0';
+      s.style.visibility = 'hidden';
+      s.classList.remove('active');
+    }
+  });
+}, slideIndex);
+
+// Wait for layout to fully settle
+await new Promise(r => setTimeout(r, 500));
+```
+
+**Problem: Content appears too small with large margins in PPTX**
+```javascript
+// Set viewport to exact 16:9 dimensions
+await page.setViewport({ width: 1280, height: 720, deviceScaleFactor: 2 });
+
+// Screenshot the full viewport
+const screenshot = await page.screenshot({ type: 'png' });
+
+// Insert as FULL-SLIDE image — no margins
+slide.addImage({
+  data: `image/png;base64,${screenshot.toString('base64')}`,
+  x: 0, y: 0, w: '100%', h: '100%'
+});
+```
+Do NOT use percentage-based sizing with margins. The image must cover x:0, y:0 to w:100%, h:100%.
 
 ## Design Principles for PPTX
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "make-slide",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "AI presentation skill — generate single-file HTML slides with 10 themes",
   "bin": {
     "make-slide": "./bin/cli.js"