slides-grab 1.2.1 → 1.2.3

package/README.md

@@ -70,9 +70,9 @@ There are many AI tools that generate slide HTML. Almost none let you **visually
 
 ## CLI Commands
 
-All commands support `--slides-dir <path>` (default: `slides`).
+Workflow commands support `--slides-dir <path>` (default: `slides`).
 
-On a fresh clone, only `--help`, `list-templates`, and `list-themes` work without a deck. `edit`, `build-viewer`, `validate`, `convert`, and `pdf` require an existing slides workspace containing `slide-*.html`.
+On a fresh clone, the discovery commands (`--help`, `list-templates`, `list-styles`, and `preview-styles`) work without a deck. `edit`, `build-viewer`, `validate`, `convert`, and `pdf` require an existing slides workspace containing `slide-*.html`.
 
 ```bash
 slides-grab edit              # Launch visual slide editor
@@ -84,13 +84,27 @@ slides-grab figma             # Export an experimental / unstable Figma Slides i
 slides-grab pdf               # Export PDF in capture mode (default)
 slides-grab pdf --resolution 2160p  # Higher-resolution image-backed PDF export
 slides-grab pdf --mode print  # Export searchable/selectable text PDF
+slides-grab png               # Render one PNG per slide (default 2160p)
+slides-grab png --slide-mode card-news  # Render square 1:1 PNGs for Instagram
 slides-grab image --prompt "..."    # Generate a local slide image with Nano Banana Pro
 slides-grab fetch-video --url <youtube-url> --slides-dir decks/my-deck  # Download a local video asset with yt-dlp
 slides-grab tldraw           # Render a .tldr diagram into a slide-sized local SVG asset
 slides-grab list-templates    # Show available slide templates
-slides-grab list-themes       # Show available color themes
+slides-grab list-styles       # Show 35 bundled design styles (browse, preview, select)
+slides-grab preview-styles                        # Open the 35-style visual gallery in browser
 ```
 
+## Design Style Collections
+
+slides-grab bundles 35 design styles: 30 derived from [corazzon/pptx-design-styles](https://github.com/corazzon/pptx-design-styles) plus 5 slides-grab originals. Agents can also create fully custom designs beyond the bundled collection.
+
+```bash
+slides-grab list-styles                           # Browse the catalog
+slides-grab preview-styles  # Local HTML preview
+```
+
+Tell the agent which style to use (or ask for something custom) — no config files needed.
+
 ## Asset Contract
 
 Slides should store local image and video files in `<slides-dir>/assets/` and reference them as `./assets/<file>` from each `slide-XX.html`.
@@ -141,12 +155,26 @@ slides-grab edit       --slides-dir decks/my-deck
 slides-grab validate   --slides-dir decks/my-deck
 slides-grab pdf        --slides-dir decks/my-deck --output decks/my-deck.pdf
 slides-grab pdf        --slides-dir decks/my-deck --mode print --output decks/my-deck-searchable.pdf
+slides-grab png        --slides-dir decks/my-deck --output-dir decks/my-deck/out-png
 slides-grab convert    --slides-dir decks/my-deck --output decks/my-deck.pptx
 slides-grab figma      --slides-dir decks/my-deck --output decks/my-deck-figma.pptx
 ```
 
 > **Warning:** `slides-grab convert` and `slides-grab figma` are currently **experimental / unstable**. Expect best-effort output, layout shifts, and manual cleanup in PowerPoint or Figma.
 
+### Card News (Square 1:1) Workflow
+
+Instagram-style card news uses a 720pt × 720pt frame end-to-end. Pass `--mode card-news` (or `--slide-mode card-news` for `pdf`/`png`) at every stage and prefer `slides-grab png` as the primary export so each card becomes an Instagram-ready PNG.
+
+```bash
+slides-grab edit     --slides-dir decks/my-cards --mode card-news
+slides-grab validate --slides-dir decks/my-cards --mode card-news
+slides-grab png      --slides-dir decks/my-cards --slide-mode card-news --resolution 2160p
+# Optional extras (PPTX / Figma remain experimental / unstable)
+slides-grab pdf      --slides-dir decks/my-cards --slide-mode card-news --output decks/my-cards.pdf
+slides-grab convert  --slides-dir decks/my-cards --mode card-news --output decks/my-cards.pptx
+```
+
 ### Tldraw Diagram Assets
 
 Use `slides-grab tldraw` when you want a newly authored `tldraw` diagram to fit an exact slide region and remain export-friendly as a local SVG asset. The command supports current-format `.tldr` files and store-snapshot JSON; legacy pre-records `.tldr` files must be reopened and resaved in a current `tldraw` build first:
@@ -204,7 +232,7 @@ bin/              CLI entry point
 src/editor/       Visual editor (HTML + JS client modules)
 scripts/          Build, validate, convert, editor server
 templates/        Slide HTML templates (cover, content, chart, ...)
-themes/           Color themes (modern-dark, executive, sage, ...)
+src/              Design styles data, style config, path resolution
 skills/           Shared Vercel-installable agent skills + references
 docs/             Installation & usage guides
 ```

package/bin/ppt-agent.js

@@ -27,7 +27,7 @@ const figmaHelpText = [
 
 /**
  * Run a Node.js script from the package, with CWD set to the user's directory.
- * Scripts resolve slide paths via --slides-dir and templates/themes via src/resolve.js.
+ * Scripts resolve slide paths via --slides-dir and templates via src/resolve.js.
  */
 function runNodeScript(relativePath, args = []) {
   return new Promise((resolvePromise, rejectPromise) => {
@@ -68,6 +68,12 @@ function collectRepeatedOption(value, previous = []) {
   return [...previous, value];
 }
 
+function reportCliError(error) {
+  console.error(`[slides-grab] ${error.message}`);
+  process.exitCode = 1;
+}
+
+
 const program = new Command();
 
 program
@@ -81,8 +87,9 @@ program
   .command('build-viewer')
   .description('Build viewer.html from slide HTML files')
   .option('--slides-dir <path>', 'Slide directory', 'slides')
+  .option('--mode <mode>', 'Slide mode: presentation or card-news', 'presentation')
   .action(async (options = {}) => {
-    const args = ['--slides-dir', options.slidesDir];
+    const args = ['--slides-dir', options.slidesDir, '--mode', options.mode];
     await runCommand('scripts/build-viewer.js', args);
   });
 
@@ -92,9 +99,10 @@ program
   .description('Run structured validation on slide HTML files (Playwright-based)')
   .option('--slides-dir <path>', 'Slide directory', 'slides')
   .option('--format <format>', 'Output format: concise, json, json-full', 'concise')
+  .option('--mode <mode>', 'Slide mode: presentation or card-news', 'presentation')
   .option('--slide <file>', 'Validate only the named slide file (repeatable)', collectRepeatedOption, [])
   .action(async (options = {}) => {
-    const args = ['--slides-dir', options.slidesDir, '--format', options.format];
+    const args = ['--slides-dir', options.slidesDir, '--format', options.format, '--mode', options.mode];
     for (const slide of options.slide || []) {
       args.push('--slide', String(slide));
     }
@@ -106,9 +114,10 @@ program
   .description('Convert slide HTML files to experimental / unstable PPTX')
   .option('--slides-dir <path>', 'Slide directory', 'slides')
   .option('--output <path>', 'Output PPTX file')
+  .option('--mode <mode>', 'Slide mode: presentation or card-news', 'presentation')
   .option('--resolution <preset>', 'Raster size preset: 720p, 1080p, 1440p, 2160p, or 4k (default: 2160p)')
   .action(async (options = {}) => {
-    const args = ['--slides-dir', options.slidesDir];
+    const args = ['--slides-dir', options.slidesDir, '--mode', options.mode];
     if (options.output) {
       args.push('--output', String(options.output));
     }
@@ -124,6 +133,7 @@ program
   .option('--slides-dir <path>', 'Slide directory', 'slides')
   .option('--output <path>', 'Output PDF file')
   .option('--mode <mode>', 'PDF export mode: capture for visual fidelity, print for searchable text', 'capture')
+  .option('--slide-mode <mode>', 'Slide mode: presentation or card-news', 'presentation')
   .option('--resolution <preset>', 'Capture raster size preset: 720p, 1080p, 1440p, 2160p, or 4k (default: 2160p in capture mode)')
   .action(async (options = {}) => {
     const args = ['--slides-dir', options.slidesDir];
@@ -133,12 +143,36 @@ program
     if (options.mode) {
       args.push('--mode', String(options.mode));
     }
+    if (options.slideMode) {
+      args.push('--slide-mode', String(options.slideMode));
+    }
     if (options.resolution) {
       args.push('--resolution', String(options.resolution));
     }
     await runCommand('scripts/html2pdf.js', args);
   });
 
+program
+  .command('png')
+  .description('Render slide HTML files to one PNG per slide')
+  .option('--slides-dir <path>', 'Slide directory', 'slides')
+  .option('--output-dir <path>', 'Output directory for PNG files (default: <slides-dir>/out-png)')
+  .option('--slide-mode <mode>', 'Slide mode: presentation or card-news', 'presentation')
+  .option('--resolution <preset>', 'Raster size preset: 720p, 1080p, 1440p, 2160p, or 4k', '2160p')
+  .action(async (options = {}) => {
+    const args = ['--slides-dir', options.slidesDir];
+    if (options.outputDir) {
+      args.push('--output-dir', String(options.outputDir));
+    }
+    if (options.slideMode) {
+      args.push('--slide-mode', String(options.slideMode));
+    }
+    if (options.resolution) {
+      args.push('--resolution', String(options.resolution));
+    }
+    await runCommand('scripts/html2png.js', args);
+  });
+
 program
   .command('fetch-video')
   .description('Download a video into <slides-dir>/assets via yt-dlp and print the ./assets reference')
@@ -159,9 +193,10 @@ program
   .helpOption('-h, --help', 'Show this help message')
   .option('--slides-dir <path>', 'Slide directory', 'slides')
   .option('--output <path>', 'Output PPTX file (default: <slides-dir>-figma.pptx)')
+  .option('--mode <mode>', 'Slide mode: presentation or card-news', 'presentation')
   .addHelpText('after', figmaHelpText)
   .action(async (options = {}) => {
-    const args = ['--slides-dir', options.slidesDir];
+    const args = ['--slides-dir', options.slidesDir, '--mode', options.mode];
     if (options.output) {
       args.push('--output', String(options.output));
     }
@@ -216,15 +251,16 @@ program
   .description('Start interactive slide editor with Codex image-based edit flow')
   .option('--port <number>', 'Server port')
   .option('--slides-dir <path>', 'Slide directory', 'slides')
+  .option('--mode <mode>', 'Slide mode: presentation or card-news', 'presentation')
   .action(async (options = {}) => {
-    const args = ['--slides-dir', options.slidesDir];
+    const args = ['--slides-dir', options.slidesDir, '--mode', options.mode];
     if (options.port) {
       args.push('--port', String(options.port));
     }
     await runCommand('scripts/editor-server.js', args);
   });
 
-// --- Template/theme discovery commands ---
+// --- Template/style discovery commands ---
 
 program
   .command('list-templates')
@@ -245,21 +281,42 @@ program
   });
 
 program
-  .command('list-themes')
-  .description('List all available color themes (local overrides + package built-ins)')
+  .command('list-styles')
+  .description('List bundled design styles agents and users can reference during slide generation')
   .action(async () => {
-    const { listThemes } = await import('../src/resolve.js');
-    const themes = listThemes();
-    if (themes.length === 0) {
-      console.log('No themes found.');
-      return;
+    try {
+      const { listDesignStyles } = await import('../src/design-styles.js');
+      const styles = listDesignStyles();
+
+      if (styles.length === 0) {
+        console.log('No bundled design styles found.');
+        return;
+      }
+
+      console.log('Available design styles:\n');
+      for (const style of styles) {
+        console.log(`  ${style.id.padEnd(22)} ${style.title}`);
+        console.log(`    ${style.mood} · ${style.bestFor}`);
+      }
+
+      console.log(`\nTotal: ${styles.length} styles`);
+      console.log('Preview: slides-grab preview-styles [--style <id>]');
+    } catch (error) {
+      reportCliError(error);
     }
-    console.log('Available themes:\n');
-    for (const t of themes) {
-      const tag = t.source === 'local' ? '(local)' : '(built-in)';
-      console.log(`  ${t.name.padEnd(20)} ${tag}`);
+  });
+
+program
+  .command('preview-styles')
+  .description('Print the path to the bundled 35-style visual preview gallery')
+  .action(async () => {
+    try {
+      const { getPreviewHtmlPath } = await import('../src/design-styles.js');
+      const previewPath = getPreviewHtmlPath();
+      console.log(previewPath);
+    } catch (error) {
+      reportCliError(error);
     }
-    console.log(`\nTotal: ${themes.length} themes`);
   });
 
 program
@@ -280,22 +337,5 @@ program
     console.log(content);
   });
 
-program
-  .command('show-theme')
-  .description('Print the contents of a theme file')
-  .argument('<name>', 'Theme name (e.g. "modern-dark", "executive")')
-  .action(async (name) => {
-    const { resolveTheme } = await import('../src/resolve.js');
-    const result = resolveTheme(name);
-    if (!result) {
-      console.error(`Theme "${name}" not found.`);
-      process.exitCode = 1;
-      return;
-    }
-    const content = readFileSync(result.path, 'utf-8');
-    console.log(`/* Theme: ${name} (${result.source}) */`);
-    console.log(`/* Path: ${result.path} */\n`);
-    console.log(content);
-  });
 
 await program.parseAsync(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slides-grab",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Agent-first presentation framework — plan, design, and visually edit HTML slides with Claude Code or Codex, then export to PDF or experimental/unstable PPTX/Figma formats",
   "license": "MIT",
   "author": "vkehfdl1",
@@ -45,7 +45,6 @@
     "skills/",
     "src/",
     "templates/",
-    "themes/",
     "LICENSE",
     "README.md"
   ],
@@ -54,18 +53,18 @@
     "build-viewer": "node scripts/build-viewer.js",
     "validate": "node scripts/validate-slides.js",
     "convert": "node convert.cjs",
-    "test": "node --test --test-concurrency=1 tests/editor/editor-codex-edit.test.js tests/nano-banana/nano-banana.test.js tests/pdf/html2pdf.test.js tests/pdf/html2pdf.e2e.test.js tests/figma/figma-export.test.js tests/image-contract/image-contract.test.js tests/tldraw/render-tldraw.test.js tests/validation/validate-slides.test.js tests/skills/installable-skills.test.js tests/video/download-video.test.js",
+    "test": "node --test --test-concurrency=1 tests/design/design-styles.test.js tests/editor/editor-codex-edit.test.js tests/editor/editor-server.test.js tests/nano-banana/nano-banana.test.js tests/pdf/html2pdf.test.js tests/pdf/html2pdf.e2e.test.js tests/figma/figma-export.test.js tests/image-contract/image-contract.test.js tests/tldraw/render-tldraw.test.js tests/validation/validate-slides.test.js tests/viewer/build-viewer.test.js tests/skills/installable-skills.test.js tests/video/download-video.test.js",
     "test:e2e": "node --test tests/editor/editor-ui.e2e.test.js tests/editor/editor-concurrency.e2e.test.js"
   },
   "dependencies": {
     "commander": "^12.1.0",
     "express": "^5.2.1",
+    "lucide-react": "^1.7.0",
     "pdf-lib": "^1.17.1",
     "playwright": "^1.40.0",
     "pptxgenjs": "^3.12.0",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
-    "react-icons": "^5.0.0",
     "sharp": "^0.33.0",
     "tldraw": "^4.4.1"
   },

package/scripts/build-viewer.js

@@ -9,11 +9,20 @@
  */
 
 import { readFileSync, writeFileSync, readdirSync } from 'fs';
-import { fileURLToPath } from 'url';
+import { createRequire } from 'node:module';
 import { join, resolve } from 'path';
+import { fileURLToPath } from 'url';
 
 import { buildSlideRuntimeHtml } from '../src/image-contract.js';
 
+const require = createRequire(import.meta.url);
+const {
+  DEFAULT_SLIDE_MODE,
+  getSlideModeChoices,
+  getSlideModeConfig,
+  normalizeSlideMode,
+} = require('../src/slide-mode.cjs');
+
 const DEFAULT_SLIDES_DIR = 'slides';
 
 function printUsage() {
@@ -23,6 +32,7 @@ function printUsage() {
       '',
       'Options:',
       `  --slides-dir <path>  Slide directory (default: ${DEFAULT_SLIDES_DIR})`,
+      `  --mode <mode>       Slide mode: ${getSlideModeChoices().join(', ')} (default: ${DEFAULT_SLIDE_MODE})`,
       '  -h, --help           Show this help message',
     ].join('\n'),
   );
@@ -40,6 +50,7 @@ function readOptionValue(args, index, optionName) {
 export function parseCliArgs(args) {
   const options = {
     slidesDir: DEFAULT_SLIDES_DIR,
+    mode: DEFAULT_SLIDE_MODE,
     help: false,
   };
 
@@ -62,6 +73,17 @@ export function parseCliArgs(args) {
       continue;
     }
 
+    if (arg === '--mode') {
+      options.mode = normalizeSlideMode(readOptionValue(args, i, '--mode'));
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--mode=')) {
+      options.mode = normalizeSlideMode(arg.slice('--mode='.length));
+      continue;
+    }
+
     throw new Error(`Unknown option: ${arg}`);
   }
 
@@ -70,17 +92,28 @@ export function parseCliArgs(args) {
   }
 
   options.slidesDir = options.slidesDir.trim();
+  options.mode = normalizeSlideMode(options.mode);
   return options;
 }
 
+function toSlideOrder(fileName) {
+  const match = fileName.match(/\d+/);
+  return match ? Number.parseInt(match[0], 10) : Number.POSITIVE_INFINITY;
+}
+
+function sortSlideFiles(a, b) {
+  const orderA = toSlideOrder(a);
+  const orderB = toSlideOrder(b);
+  if (orderA !== orderB) {
+    return orderA - orderB;
+  }
+  return a.localeCompare(b);
+}
+
 export function findSlideFiles(slidesDir) {
   return readdirSync(slidesDir)
-    .filter((file) => /^slide-\d+\.html$/i.test(file))
-    .sort((a, b) => {
-      const numA = parseInt(a.match(/\d+/)[0], 10);
-      const numB = parseInt(b.match(/\d+/)[0], 10);
-      return numA - numB || a.localeCompare(b);
-    });
+    .filter((file) => /^slide-.*\.html$/i.test(file))
+    .sort(sortSlideFiles);
 }
 
 /**
@@ -106,7 +139,9 @@ export function loadSlides(slidesDir) {
   });
 }
 
-export function buildViewerHtml(slides) {
+export function buildViewerHtml(slides, { slideMode = DEFAULT_SLIDE_MODE } = {}) {
+  const { framePt } = getSlideModeConfig(slideMode);
+
   return `<!DOCTYPE html>
 <html lang="ko">
 <head>
@@ -131,7 +166,6 @@ export function buildViewerHtml(slides) {
       flex-direction: column;
     }
 
-    /* Navigation bar */
     .nav-bar {
       height: 48px;
       background: #1a1a1a;
@@ -182,7 +216,6 @@ export function buildViewerHtml(slides) {
       padding: 6px 10px !important;
     }
 
-    /* Slide viewport */
     .slide-viewport {
       flex: 1;
       display: flex;
@@ -193,18 +226,17 @@ export function buildViewerHtml(slides) {
     }
 
     .slide-scaler {
-      width: 720pt;
-      height: 405pt;
+      width: ${framePt.width}pt;
+      height: ${framePt.height}pt;
       position: relative;
       transform-origin: center center;
     }
 
-    /* Slide frames (iframes) */
     .slide-frame {
       position: absolute;
       inset: 0;
-      width: 720pt;
-      height: 405pt;
+      width: ${framePt.width}pt;
+      height: ${framePt.height}pt;
       border: none;
       overflow: hidden;
       opacity: 0;
@@ -220,7 +252,6 @@ export function buildViewerHtml(slides) {
 </head>
 <body>
   <div class="viewer-container">
-    <!-- Navigation -->
     <div class="nav-bar">
       <button id="btn-prev" title="Previous (\\u2190)">Prev</button>
       <span class="slide-counter" id="counter">1 / ${slides.length}</span>
@@ -228,7 +259,6 @@ export function buildViewerHtml(slides) {
       <button class="btn-fullscreen" id="btn-fs" title="Fullscreen (F)">&#x26F6;</button>
     </div>
 
-    <!-- Slide viewport -->
     <div class="slide-viewport" id="viewport">
       <div class="slide-scaler" id="scaler">
 ${slides.map((s, i) => `        <iframe class="slide-frame${i === 0 ? ' active' : ''}" data-slide="${i + 1}" srcdoc="${escapeForSrcdoc(s.html)}" sandbox="allow-same-origin"></iframe>`).join('\n')}
@@ -265,7 +295,6 @@ ${slides.map((s, i) => `        <iframe class="slide-frame${i === 0 ? ' active'
     btnNext.addEventListener('click', next);
     btnPrev.disabled = true;
 
-    // Keyboard navigation
     document.addEventListener('keydown', (e) => {
       if (e.key === 'ArrowRight' || e.key === ' ') { e.preventDefault(); next(); }
       else if (e.key === 'ArrowLeft') { e.preventDefault(); prev(); }
@@ -277,7 +306,6 @@ ${slides.map((s, i) => `        <iframe class="slide-frame${i === 0 ? ' active'
       }
     });
 
-    // Fullscreen
     function toggleFullscreen() {
       if (!document.fullscreenElement) {
         document.documentElement.requestFullscreen().catch(() => {});
@@ -287,7 +315,6 @@ ${slides.map((s, i) => `        <iframe class="slide-frame${i === 0 ? ' active'
     }
     document.getElementById('btn-fs').addEventListener('click', toggleFullscreen);
 
-    // Auto-scale to fit viewport (95% fit)
     function rescale() {
       const vw = viewport.clientWidth;
       const vh = viewport.clientHeight;
@@ -332,7 +359,7 @@ export function main(args = process.argv.slice(2)) {
   }
 
   console.log(`Found ${slides.length} slides`);
-  writeFileSync(output, buildViewerHtml(slides), 'utf-8');
+  writeFileSync(output, buildViewerHtml(slides, { slideMode: options.mode }), 'utf-8');
   console.log(`Built viewer: ${output}`);
   return { slidesDir, output, slides };
 }