slides-grab 1.0.0 → 1.1.3

package/README.md

@@ -9,7 +9,7 @@ Simple things like text, size, or bold can still be edited manually, just like i
 
 <p align="center">
 The whole slides are HTML & CSS, the programming langauge (which is not) that outperformed by AI agents.<br>
-So the slides are beautiful, easily editable by AI agents, and can be converted to pdf and pptx.
+So the slides are beautiful, easily editable by AI agents, and can be converted to PDF or to experimental / unstable PPTX formats.
 </p>
 
 <p align="center">
@@ -56,31 +56,66 @@ There are many AI tools that generate slide HTML. Almost none let you **visually
 - **Plan** — Agent creates a structured slide outline from your topic/files
 - **Design** — Agent generates each slide as a self-contained HTML file
 - **Edit** — Browser-based editor with bbox selection, direct text editing, and agent-powered rewrites
-- **Export** — One command to PPTX or PDF
+- **Export** — One command to PDF, plus experimental / unstable PPTX or Figma-export flows
 
 ## CLI Commands
 
 All 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`.
+
 ```bash
 slides-grab edit              # Launch visual slide editor
 slides-grab build-viewer      # Build single-file viewer.html
 slides-grab validate          # Validate slide HTML (Playwright-based)
-slides-grab convert           # Export to PPTX
-slides-grab pdf               # Export to PDF
+slides-grab convert           # Export to experimental / unstable PPTX
+slides-grab convert --resolution 2160p  # Higher-resolution raster PPTX export
+slides-grab figma             # Export an experimental / unstable Figma Slides importable PPTX
+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 list-templates    # Show available slide templates
 slides-grab list-themes       # Show available color themes
 ```
 
+## Image Contract
+
+Slides should store local image files in `<slides-dir>/assets/` and reference them as `./assets/<file>` from each `slide-XX.html`.
+
+- Preferred: `<img src="./assets/example.png" alt="...">`
+- Allowed: `data:` URLs for fully self-contained slides
+- Allowed with warnings: remote `https://` images
+- Unsupported: absolute filesystem paths such as `/Users/...` or `C:\\...`
+
+Run `slides-grab validate --slides-dir <path>` before export to catch missing local assets and discouraged path forms.
+
+`slides-grab pdf` now defaults to `--mode capture`, which rasterizes each rendered slide into the PDF for better visual fidelity. Use `--mode print` when searchable/selectable browser text matters more than pixel-perfect parity.
+
+`slides-grab pdf` and `slides-grab convert` now default to `2160p` / `4k` raster output for sharper exports. You can still override with `--resolution <preset>` using `720p`, `1080p`, `1440p`, `2160p`, or `4k` when you want smaller or faster artifacts.
+
 ### Multi-Deck Workflow
 
+Prerequisite: create or generate a deck in `decks/my-deck/` first.
+
 ```bash
 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 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.
+
+### Figma Workflow
+
+```bash
+slides-grab figma --slides-dir decks/my-deck --output decks/my-deck-figma.pptx
+```
+
+This command reuses the HTML to PPTX pipeline and emits a `.pptx` deck intended for manual import into Figma Slides via `Import`. It does not upload to Figma directly. The Figma export path is **experimental / unstable** and should be treated as best-effort only.
+
 ## Installation Guides
 
 - [Claude Code setup](docs/prompts/setup-claude.md)
@@ -117,4 +152,3 @@ docs/             Installation & usage guides
 ## Acknowledgment
 
 This project is built based on the [ppt_team_agent](https://github.com/uxjoseph/ppt_team_agent) by Builder Josh. Huge thanks to him!
-

package/bin/ppt-agent.js

@@ -5,10 +5,25 @@ import { readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
+import {
+  getFigmaImportCaveats,
+  getFigmaManualImportInstructions,
+} from '../src/figma.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = resolve(__dirname, '..');
 const packageJson = JSON.parse(readFileSync(resolve(packageRoot, 'package.json'), 'utf-8'));
+const figmaHelpText = [
+  '',
+  'Creates an experimental / unstable PowerPoint file tuned for Figma Slides manual import.',
+  'Treat both PPTX and Figma export as best-effort only.',
+  '',
+  'Manual import:',
+  `  ${getFigmaManualImportInstructions()}`,
+  '',
+  'Figma import caveats:',
+  ...getFigmaImportCaveats().map((caveat) => `  - ${caveat}`),
+].join('\n');
 
 /**
  * Run a Node.js script from the package, with CWD set to the user's directory.
@@ -49,6 +64,10 @@ async function runCommand(relativePath, args = []) {
   }
 }
 
+function collectRepeatedOption(value, previous = []) {
+  return [...previous, value];
+}
+
 const program = new Command();
 
 program
@@ -69,23 +88,33 @@ program
 
 program
   .command('validate')
+  .alias('lint')
   .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('--slide <file>', 'Validate only the named slide file (repeatable)', collectRepeatedOption, [])
   .action(async (options = {}) => {
-    const args = ['--slides-dir', options.slidesDir];
+    const args = ['--slides-dir', options.slidesDir, '--format', options.format];
+    for (const slide of options.slide || []) {
+      args.push('--slide', String(slide));
+    }
     await runCommand('scripts/validate-slides.js', args);
   });
 
 program
   .command('convert')
-  .description('Convert slide HTML files to PPTX')
+  .description('Convert slide HTML files to experimental / unstable PPTX')
   .option('--slides-dir <path>', 'Slide directory', 'slides')
   .option('--output <path>', 'Output PPTX file')
+  .option('--resolution <preset>', 'Raster size preset: 720p, 1080p, 1440p, 2160p, or 4k (default: 2160p)')
   .action(async (options = {}) => {
     const args = ['--slides-dir', options.slidesDir];
     if (options.output) {
       args.push('--output', String(options.output));
     }
+    if (options.resolution) {
+      args.push('--resolution', String(options.resolution));
+    }
     await runCommand('convert.cjs', args);
   });
 
@@ -94,14 +123,37 @@ program
   .description('Convert slide HTML files to PDF')
   .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('--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];
     if (options.output) {
       args.push('--output', String(options.output));
     }
+    if (options.mode) {
+      args.push('--mode', String(options.mode));
+    }
+    if (options.resolution) {
+      args.push('--resolution', String(options.resolution));
+    }
     await runCommand('scripts/html2pdf.js', args);
   });
 
+program
+  .command('figma')
+  .description('Export an experimental / unstable Figma Slides importable PPTX')
+  .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)')
+  .addHelpText('after', figmaHelpText)
+  .action(async (options = {}) => {
+    const args = ['--slides-dir', options.slidesDir];
+    if (options.output) {
+      args.push('--output', String(options.output));
+    }
+    await runCommand('scripts/figma-export.js', args);
+  });
+
 program
   .command('edit')
   .description('Start interactive slide editor with Codex image-based edit flow')

package/convert.cjs

@@ -3,13 +3,52 @@ const { chromium } = require('playwright');
 const path = require('path');
 const fs = require('fs');
 const sharp = require('sharp');
+const {
+  getResolutionChoices,
+  getResolutionSize,
+  normalizeResolutionPreset,
+} = require('./src/export-resolution.cjs');
 
 // Inline a simplified version that uses Playwright Chromium (not Chrome)
-const PT_PER_PX = 0.75;
-const PX_PER_IN = 96;
-const EMU_PER_IN = 914400;
 const DEFAULT_SLIDES_DIR = 'slides';
 const DEFAULT_OUTPUT = 'output.pptx';
+const DEFAULT_RESOLUTION = '2160p';
+const DEFAULT_CAPTURE_VIEWPORT = { width: 960, height: 540 };
+const DEFAULT_CAPTURE_DEVICE_SCALE_FACTOR = 2;
+const TARGET_RASTER_DPI = 150;
+const TARGET_SLIDE_SIZE_IN = { width: 13.33, height: 7.5 };
+
+function normalizeDimension(value, fallback) {
+  if (!Number.isFinite(value) || value <= 0) {
+    return fallback;
+  }
+  return Math.max(1, Math.round(value));
+}
+
+function buildPageOptions(resolution = '') {
+  const targetResolution = getResolutionSize(resolution);
+  return {
+    viewport: {
+      width: DEFAULT_CAPTURE_VIEWPORT.width,
+      height: DEFAULT_CAPTURE_VIEWPORT.height,
+    },
+    deviceScaleFactor: targetResolution
+      ? targetResolution.height / DEFAULT_CAPTURE_VIEWPORT.height
+      : DEFAULT_CAPTURE_DEVICE_SCALE_FACTOR,
+  };
+}
+
+function getTargetRasterSize(resolution = '') {
+  const targetResolution = getResolutionSize(resolution);
+  if (targetResolution) {
+    return targetResolution;
+  }
+
+  return {
+    width: Math.round(TARGET_SLIDE_SIZE_IN.width * TARGET_RASTER_DPI),
+    height: Math.round(TARGET_SLIDE_SIZE_IN.height * TARGET_RASTER_DPI),
+  };
+}
 
 function printUsage() {
   process.stdout.write(
@@ -19,6 +58,7 @@ function printUsage() {
       'Options:',
       `  --slides-dir <path>  Slide directory (default: ${DEFAULT_SLIDES_DIR})`,
       `  --output <path>      Output pptx path (default: ${DEFAULT_OUTPUT})`,
+      `  --resolution <preset> Raster size preset: ${getResolutionChoices().join('|')}|4k (default: ${DEFAULT_RESOLUTION})`,
       '  -h, --help           Show this help message',
     ].join('\n'),
   );
@@ -37,6 +77,7 @@ function parseArgs(args) {
   const options = {
     slidesDir: DEFAULT_SLIDES_DIR,
     output: DEFAULT_OUTPUT,
+    resolution: DEFAULT_RESOLUTION,
     help: false,
   };
 
@@ -69,6 +110,17 @@ function parseArgs(args) {
       continue;
     }
 
+    if (arg === '--resolution') {
+      options.resolution = normalizeResolutionPreset(readOptionValue(args, i, '--resolution'));
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--resolution=')) {
+      options.resolution = normalizeResolutionPreset(arg.slice('--resolution='.length));
+      continue;
+    }
+
     throw new Error(`Unknown option: ${arg}`);
   }
 
@@ -82,13 +134,14 @@ function parseArgs(args) {
 
   options.slidesDir = options.slidesDir.trim();
   options.output = options.output.trim();
+  options.resolution = normalizeResolutionPreset(options.resolution);
   return options;
 }
 
-async function convertSlide(htmlFile, pres, browser) {
+async function convertSlide(htmlFile, pres, browser, options = {}) {
   const filePath = path.isAbsolute(htmlFile) ? htmlFile : path.join(process.cwd(), htmlFile);
 
-  const page = await browser.newPage();
+  const page = await browser.newPage(buildPageOptions(options.resolution));
   await page.goto(`file://${filePath}`);
 
   const bodyDimensions = await page.evaluate(() => {
@@ -101,8 +154,8 @@ async function convertSlide(htmlFile, pres, browser) {
   });
 
   await page.setViewportSize({
-    width: Math.round(bodyDimensions.width),
-    height: Math.round(bodyDimensions.height)
+    width: normalizeDimension(bodyDimensions.width, DEFAULT_CAPTURE_VIEWPORT.width),
+    height: normalizeDimension(bodyDimensions.height, DEFAULT_CAPTURE_VIEWPORT.height)
   });
 
   // Take screenshot and add as full-slide image
@@ -110,11 +163,10 @@ async function convertSlide(htmlFile, pres, browser) {
   await page.close();
 
   // Resize to exact slide dimensions (13.33" x 7.5" at 150 DPI)
-  const targetWidth = Math.round(13.33 * 150);
-  const targetHeight = Math.round(7.5 * 150);
+  const targetSize = getTargetRasterSize(options.resolution);
 
   const resized = await sharp(screenshot)
-    .resize(targetWidth, targetHeight, { fit: 'fill' })
+    .resize(targetSize.width, targetSize.height, { fit: 'fill' })
     .png()
     .toBuffer();
 
@@ -144,6 +196,8 @@ async function main() {
   pres.layout = 'LAYOUT_WIDE'; // 16:9
 
   const slidesDir = path.resolve(process.cwd(), options.slidesDir);
+  const { ensureSlidesPassValidation } = await import('./scripts/validate-slides.js');
+  await ensureSlidesPassValidation(slidesDir, { exportLabel: 'PPTX export' });
   const files = fs.readdirSync(slidesDir)
     .filter(f => f.endsWith('.html'))
     .sort();
@@ -158,7 +212,7 @@ async function main() {
     const filePath = path.join(slidesDir, file);
     console.log(`  Processing: ${file}`);
     try {
-      const tmpPath = await convertSlide(filePath, pres, browser);
+      const tmpPath = await convertSlide(filePath, pres, browser, { resolution: options.resolution });
       tmpFiles.push(tmpPath);
       console.log(`    ✓ ${file} done`);
     } catch (err) {
@@ -178,7 +232,15 @@ async function main() {
   }
 }
 
-main().catch(err => {
-  console.error('Fatal error:', err);
-  process.exit(1);
-});
+if (require.main === module) {
+  main().catch(err => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  buildPageOptions,
+  getTargetRasterSize,
+  parseArgs,
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "slides-grab",
-  "version": "1.0.0",
-  "description": "Agent-first presentation framework — plan, design, and visually edit HTML slides with Claude Code or Codex, then export to PPTX/PDF",
+  "version": "1.1.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",
   "repository": {
@@ -30,13 +30,30 @@
   "bin": {
     "slides-grab": "./bin/ppt-agent.js"
   },
+  "files": [
+    "bin/",
+    "convert.cjs",
+    "scripts/build-viewer.js",
+    "scripts/editor-server.js",
+    "scripts/figma-export.js",
+    "scripts/html2pdf.js",
+    "scripts/html2pptx.js",
+    "scripts/install-codex-skills.js",
+    "scripts/validate-slides.js",
+    "skills/",
+    "src/",
+    "templates/",
+    "themes/",
+    "LICENSE",
+    "README.md"
+  ],
   "scripts": {
-    "html2pptx": "node .claude/skills/pptx-skill/scripts/html2pptx.js",
+    "html2pptx": "node scripts/html2pptx.js",
     "build-viewer": "node scripts/build-viewer.js",
     "validate": "node scripts/validate-slides.js",
     "convert": "node convert.cjs",
     "codex:install-skills": "node scripts/install-codex-skills.js --force",
-    "test": "node --test tests/editor/editor-codex-edit.test.js tests/pdf/html2pdf.test.js",
+    "test": "node --test tests/editor/editor-codex-edit.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/validation/validate-slides.test.js",
     "test:e2e": "node --test tests/editor/editor-ui.e2e.test.js tests/editor/editor-concurrency.e2e.test.js"
   },
   "dependencies": {