lazyslides 0.3.1 → 0.4.0

package/index.js

@@ -112,6 +112,14 @@ export default function lazyslides(eleventyConfig, options = {}) {
         d2Cache.set(source, `<div class="d2-error">${safeMsg}</div>`);
       }
     }
+
+    // Terminate the D2 worker thread so the Node process can exit cleanly.
+    // The D2 class spawns a Worker for WASM but never exposes a cleanup method.
+    if (d2Instance?.worker) {
+      await d2Instance.worker.terminate();
+      d2Instance = null;
+      d2Available = null;
+    }
   });
 
   // ---------------------------------------------------------------

package/lib/export-pdf.js

@@ -229,7 +229,6 @@ export async function run(opts = {}) {
   // Summary
   console.log("\u2501".repeat(30));
   console.log(`Exported: ${success}  Failed: ${failure}`);
-  if (failure > 0) {
-    process.exit(1);
-  }
+  // Force exit to ensure all child processes (server, npx wrappers) are cleaned up.
+  process.exit(failure > 0 ? 1 : 0);
 }

package/lib/init.js

@@ -126,17 +126,13 @@ export async function run(opts) {
   );
   console.log("  Created CLAUDE.md");
 
-  // 9. .claude/ directory (commands + settings)
+  // 9. .claude/ directory (skills + settings)
   const claudeDir = path.join(targetDir, ".claude");
-  const commandsDir = path.join(claudeDir, "commands");
-  fs.mkdirSync(commandsDir, { recursive: true });
-  const scaffoldCommandsDir = path.join(scaffoldDir, "claude-commands");
-  for (const file of fs.readdirSync(scaffoldCommandsDir)) {
-    fs.copyFileSync(
-      path.join(scaffoldCommandsDir, file),
-      path.join(commandsDir, file)
-    );
-  }
+  fs.mkdirSync(claudeDir, { recursive: true });
+  copyDir(
+    path.join(scaffoldDir, "claude-skills"),
+    path.join(claudeDir, "skills")
+  );
   fs.copyFileSync(
     path.join(scaffoldDir, "claude-settings.json"),
     path.join(claudeDir, "settings.json")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lazyslides",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Slide decks with native agentic AI integration",
   "license": "MIT",
   "author": "Chris Tietz",
@@ -61,7 +61,8 @@
     "@tailwindcss/cli": "4.1.18",
     "concurrently": "^9.0.0",
     "tailwindcss": "4.1.18",
-    "vitest": "^4.1.2"
+    "vite": "^7.3.2",
+    "vitest": "^4.1.5"
   },
   "scripts": {
     "dev": "node cli.js validate && concurrently \"pnpm:watch:*\"",

package/scaffold/{claude-commands/add-slide.md → claude-skills/add-slide/SKILL.md}

@@ -1,3 +1,18 @@
+---
+name: add-slide
+description: >
+  Guides adding a new slide to an existing LazySlides presentation —
+  picks template, gathers content, inserts at the right position, and validates.
+when_to_use: >
+  Use when the user wants to add, insert, or append a slide to an existing presentation.
+allowed-tools:
+  - Read
+  - Edit
+  - Bash
+user-invocable: true
+effort: medium
+---
+
 # Add Slide
 
 You are helping the user add a new slide to an existing presentation.

package/scaffold/{claude-commands/add-template.md → claude-skills/add-template/SKILL.md}

@@ -1,3 +1,20 @@
+---
+name: add-template
+description: >
+  Guides creating a custom Nunjucks slide template for a LazySlides project,
+  including the .njk file structure and any required CSS.
+when_to_use: >
+  Use when the user wants to create a new slide template that doesn't exist
+  in the built-in set of 19 templates.
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+user-invocable: true
+effort: high
+---
+
 # Add Template
 
 You are helping the user create a custom slide template for their LazySlides project.

package/scaffold/{claude-commands/add-theme.md → claude-skills/add-theme/SKILL.md}

@@ -1,3 +1,18 @@
+---
+name: add-theme
+description: >
+  Guides creating a custom CSS theme for a LazySlides project, including
+  color palette, typography, footer branding, and theater background.
+when_to_use: >
+  Use when the user wants to create or apply a custom visual theme to their presentation.
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+user-invocable: true
+effort: medium
+---
+
 # Add Theme
 
 You are helping the user create a custom CSS theme for their LazySlides project.

package/scaffold/{claude-commands/create-outline.md → claude-skills/create-outline/SKILL.md}

@@ -1,3 +1,19 @@
+---
+name: create-outline
+description: >
+  Helps build a structured presentation outline before generating YAML —
+  covers audience, purpose, section structure, and per-slide content sketches.
+when_to_use: >
+  Use when the user wants to plan a presentation before writing slides,
+  or when starting a new deck without an existing outline.
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+user-invocable: true
+effort: medium
+---
+
 # Create Outline
 
 You are helping the user create a structured outline before generating presentation YAML.

package/scaffold/{claude-commands/new-presentation.md → claude-skills/new-presentation/SKILL.md}

@@ -1,3 +1,19 @@
+---
+name: new-presentation
+description: >
+  Full guided workflow for creating a LazySlides presentation from scratch —
+  gathers requirements, builds an outline, maps templates, and generates index.md.
+when_to_use: >
+  Use when the user wants to create a new presentation or start a new deck from scratch.
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+user-invocable: true
+effort: high
+---
+
 # Create New Presentation
 
 You are helping the user create a new presentation in this Eleventy + Reveal.js presentation system.

package/scaffold/claude-skills/pdf-export/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: pdf-export
+description: >
+  How to export a LazySlides presentation to PDF.
+  Covers the command, pipeline, known hang causes, how to verify the pipeline
+  with the test fixture, and debugging steps when export fails.
+when_to_use: >
+  Use whenever the user asks to "export", "make", "generate", or "create"
+  a PDF of a presentation, or when PDF export fails or hangs.
+allowed-tools:
+  - Bash
+  - Read
+effort: medium
+---
+
+# LazySlides PDF Export
+
+## Command
+
+From the project root:
+
+```bash
+pnpm run pdf <presentation-name>   # single presentation
+pnpm run pdf                       # all presentations (skips _-prefixed dirs)
+```
+
+Output lands in `_pdfs/<presentation-name>.pdf`.
+
+## Pipeline (what the script actually does)
+
+1. `pnpm run build` — validate, build CSS, run eleventy. Builds **all** presentations.
+2. Spawn `npx eleventy --serve --port 4100` as a child.
+3. Poll `http://127.0.0.1:4100/` until the server responds (60s timeout).
+4. For each target presentation: `npx decktape reveal --size 1920x1080 --pause 1000 --load-pause 2000 http://127.0.0.1:4100/presentations/<name>/?pdf _pdfs/<name>.pdf`.
+5. Kill the server, print summary.
+
+## Known gotcha: eleventy doesn't always exit cleanly
+
+After writing files, the eleventy build process sometimes stays alive with 0% CPU — a lingering async handle (d2 WASM worker, chokidar, etc.) keeps the event loop open.
+
+**The hardened script handles this** via an idle-timeout: if the build child emits no stdout for 15s, we force-kill and proceed. You'll see:
+
+```
+Build child idle for 15s — assuming done and force-exiting.
+```
+
+That line is expected and harmless. The `_site/` has already been written.
+
+## Verifying the pipeline is healthy
+
+There's a one-slide smoke-test presentation at `presentations/_test-pdf/`. To confirm the export pipeline works in isolation:
+
+```bash
+pnpm run pdf _test-pdf
+```
+
+If that produces `_pdfs/_test-pdf.pdf`, the pipeline is fine. Any subsequent failure on a real deck is deck-specific — check that deck's content, images, or diagrams.
+
+## Debugging a failure
+
+1. **Nothing visible happens**: decktape's stdout is inherited — you should see `Printing slide 1/N…` live. If you don't, the build or server-start phase stalled.
+2. **Process leftovers**: `ps aux | grep -E "lazyslides|eleventy|decktape" | grep -v grep` — kill anything stale before retrying.
+3. **Port 4100 in use**: `lsof -nP -iTCP:4100`. Kill the holder.
+4. **Do NOT run `pnpm run dev` first** — `pdf` spawns its own server on port 4100 (vs 8080 for dev), but leftover dev-server processes can confuse things.
+5. **Decktape fails with a clear exit code** — the script surfaces it. Common causes: slide HTML didn't render, an image URL is unreachable, or a d2 diagram failed.

package/scaffold/claude-skills/presentation-design/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: presentation-design
+description: >
+  Apply when creating, refining, or reviewing LazySlides presentations.
+  Guides visual hierarchy, template selection, content density, motion
+  strategy, and theme usage for distinctive, professional slide decks.
+when_to_use: >
+  Activate for any request involving slide creation, deck improvement, template
+  selection, visual design decisions, or content structure in a LazySlides project.
+user-invocable: false
+allowed-tools:
+  - Read
+effort: low
+---
+
+# Presentation Design Skill
+
+## 1. Design Thinking Process
+
+Before generating YAML, choose an aesthetic direction based on the audience and content:
+
+| Direction | Best For | Theme Combo | Transition |
+|-----------|----------|-------------|------------|
+| Minimal/Clean | Data-heavy, technical | `default` or `corporate` | `fade` |
+| Bold/Dramatic | Keynotes, product launches | `midnight` or `theme: black` | `zoom` for reveals, `slide` elsewhere |
+| Warm/Inviting | Training, culture, onboarding | `sunset` or `forest` | `slide` |
+| Corporate/Professional | Board decks, strategy | `corporate` | `fade` |
+| Editorial/Magazine | Thought leadership, creative | `default` | `convex` |
+
+## 2. Visual Hierarchy
+
+Structure every deck with this arc:
+
+1. **Title slide** (template: `title`) — establish brand and topic
+2. **Agenda** (template: `agenda`) — orient the audience (optional for <8 slides)
+3. **Section dividers** (template: `section`) — breathing room between topics
+4. **Evidence slides** — mix of `content`, `metrics`, `comparison`, `split`
+5. **Summary/Close** — `center` with a key takeaway, or `title` reprise
+
+Rules:
+- One idea per slide
+- Title slides should have 2-6 word headlines
+- Section dividers every 4-7 slides in long decks (>12 slides)
+- End with impact: a bold statement, a call to action, or a key metric
+
+## 3. Template Selection Strategy
+
+**Never use 3+ of the same template in a row.** Alternate between text-heavy and visual templates:
+
+| Purpose | Template Options |
+|---------|-----------------|
+| Argument building | `content` with `fragment: fade-up` |
+| Visual evidence | `split`, `split-wide`, `center` (with image) |
+| Data points | `metrics`, `table`, `comparison` |
+| Narrative flow | `timeline`, `funnel` |
+| Impact statement | `quote`, `hero`, `center` (text only) |
+| Code demonstration | `code` |
+| Side-by-side comparison | `columns`, `comparison` |
+
+**Emotional arc**: Open with impact (hero/title) -> build with evidence (content/metrics/comparison) -> close with aspiration (quote/center/hero)
+
+## 4. Content Density Rules
+
+| Element | Guideline |
+|---------|-----------|
+| Headlines | 2-6 words, action-oriented |
+| Bullet text | Max 12 words per bullet |
+| Bullets per slide | 3-5 items |
+| Metrics | 3 for visual balance (2 or 4 acceptable) |
+| Code blocks | Max 10 visible lines |
+| Quote text | Max 2 sentences |
+| Nested lists | Max 2 levels deep |
+
+If a slide exceeds these limits, split it into two slides.
+
+## 5. Motion & Animation Strategy
+
+### Use fragments for:
+- Argument building: reveal bullets one-by-one (`fragment: fade-up`)
+- Metric reveals: show numbers progressively (`fragment: fade-in`)
+- Comparison reveals: expose rows one at a time (`fragment: fade-up`)
+- Progressive disclosure in training content
+
+### Do NOT use fragments for:
+- Every slide (causes pacing fatigue)
+- Simple lists with <3 items
+- Decorative purposes
+- Section dividers or title slides
+
+### Use auto-animate for:
+- Before/after comparisons (matching `data_id` on items)
+- Progressive detail — start simple, add complexity
+- Code evolution — show how code changes step by step
+
+### Per-slide transitions:
+- `transition: zoom` — only for dramatic reveals (use sparingly, max 2 per deck)
+- `transition: fade` — smooth narrative flow, section transitions
+- `transition: none` — rapid-fire comparison between similar slides
+- Default `slide` transition works well for most slides
+
+## 6. Theme & Color Usage
+
+### Metric colors tell a story:
+- `mint` — positive outcomes, growth, success
+- `coral` — negative outcomes, problems, risks
+- `amber` — warnings, caveats, things to watch
+- `icy` — neutral data, context, baseline
+
+### Hero slides:
+- `color` should match the theme's mood (dark for midnight, warm for sunset)
+- Use `background_image` for photographic hero slides
+- Use `background_gradient` for abstract/geometric backgrounds
+
+### Comparison highlights:
+- `highlight: right` (default) — right column is the recommendation
+- `highlight: left` — left column is preferred
+- `highlight: none` — neutral comparison
+
+### Background enhancements:
+- `background_color` on section dividers for visual separation
+- `background_gradient` for mood transitions between sections
+- `background_image` sparingly — max 2-3 per deck
+
+## 7. Anti-Patterns to Flag
+
+When reviewing presentations, flag these issues:
+
+- **Wall of text**: Any slide with >100 words of body content
+- **Template monotony**: 3+ consecutive slides with the same template
+- **Missing section dividers**: Decks >8 slides without any `section` templates
+- **Generic titles**: "Overview", "Details", "Summary" — titles should be specific
+- **Orphaned sections**: A `section` divider followed by only 1 content slide
+- **Fragment overuse**: More than 50% of slides using fragments
+- **Metric overload**: More than 4 metrics on a single slide
+- **Missing speaker notes**: Important slides without `notes:` field
+- **Image-heavy without alt text**: `image` fields without `image_alt`

package/scaffold/{claude-commands/refine-slides.md → claude-skills/refine-slides/SKILL.md}

@@ -1,3 +1,18 @@
+---
+name: refine-slides
+description: >
+  Reviews and improves an existing LazySlides presentation — checks structure,
+  template variety, content density, design anti-patterns, and applies approved changes.
+when_to_use: >
+  Use when the user wants to improve, polish, review, or fix an existing presentation.
+allowed-tools:
+  - Read
+  - Edit
+  - Bash
+user-invocable: true
+effort: medium
+---
+
 # Refine Slides
 
 You are helping the user improve an existing presentation.
@@ -16,10 +31,18 @@ You are helping the user improve an existing presentation.
 
 Analyze and report:
 - **Slide count** — is it appropriate for the estimated duration?
-- **Template diversity** — are templates varied or repetitive? (e.g., 10 `content` slides in a row)
+- **Template diversity** — are templates varied or repetitive? (e.g., 3+ `content` slides in a row)
 - **Visual rhythm** — is there a good mix of text-heavy and visual slides?
 - **Section structure** — are `section` dividers used to organize the flow?
 - **Notes coverage** — which slides are missing speaker notes?
+- **Design quality** — check against the presentation-design skill anti-patterns:
+  - Wall of text (>100 words on a slide)
+  - Template monotony (3+ consecutive same template)
+  - Missing section dividers in decks >8 slides
+  - Generic titles ("Overview", "Details")
+  - Fragment overuse (>50% of slides)
+  - Missing alt text on images
+- **Animation strategy** — suggest where `fragment`, `auto_animate`, or per-slide `transition` would improve the narrative
 
 ## Step 3: Content Review
 

package/scaffold/{claude-commands/research-topic.md → claude-skills/research-topic/SKILL.md}

@@ -1,3 +1,20 @@
+---
+name: research-topic
+description: >
+  Researches a topic to gather statistics, quotes, comparisons, and case studies
+  for a data-driven LazySlides presentation, then saves findings as research.md.
+when_to_use: >
+  Use when the user wants to gather data, statistics, or supporting evidence
+  for a presentation topic.
+allowed-tools:
+  - WebSearch
+  - WebFetch
+  - Read
+  - Write
+user-invocable: true
+effort: high
+---
+
 # Research Topic
 
 You are helping the user research a topic to build a data-driven presentation.

package/scaffold/{claude-commands/validate.md → claude-skills/validate/SKILL.md}

@@ -1,3 +1,18 @@
+---
+name: validate
+description: >
+  Runs LazySlides YAML validation, interprets errors and warnings,
+  proposes fixes, and applies approved corrections.
+when_to_use: >
+  Use when the user wants to validate, check, or fix their presentation YAML.
+allowed-tools:
+  - Bash
+  - Read
+  - Edit
+user-invocable: true
+effort: low
+---
+
 # Validate Presentations
 
 You are helping the user validate their presentation YAML and fix any issues.