slides-grab 1.2.1 → 1.2.3

package/src/pptx-raster-export.cjs

@@ -9,14 +9,19 @@ const {
   getResolutionSize,
   normalizeResolutionPreset,
 } = require('./export-resolution.cjs');
+const {
+  DEFAULT_SLIDE_MODE,
+  getSlideModeChoices,
+  getSlideModeConfig,
+  normalizeSlideMode,
+} = require('./slide-mode.cjs');
 
 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 };
+const SLIDE_FILE_PATTERN = /^slide-.*\.html$/i;
 
 function normalizeDimension(value, fallback) {
   if (!Number.isFinite(value) || value <= 0) {
@@ -25,31 +30,63 @@ function normalizeDimension(value, fallback) {
   return Math.max(1, Math.round(value));
 }
 
-function buildPageOptions(resolution = '') {
-  const targetResolution = getResolutionSize(resolution);
+function buildPageOptions(resolution = '', slideMode = DEFAULT_SLIDE_MODE) {
+  const { framePx } = getSlideModeConfig(slideMode);
+  const targetResolution = getResolutionSize(resolution, slideMode);
   return {
     viewport: {
-      width: DEFAULT_CAPTURE_VIEWPORT.width,
-      height: DEFAULT_CAPTURE_VIEWPORT.height,
+      width: framePx.width,
+      height: framePx.height,
     },
     deviceScaleFactor: targetResolution
-      ? targetResolution.height / DEFAULT_CAPTURE_VIEWPORT.height
+      ? targetResolution.height / framePx.height
       : DEFAULT_CAPTURE_DEVICE_SCALE_FACTOR,
   };
 }
 
-function getTargetRasterSize(resolution = '') {
-  const targetResolution = getResolutionSize(resolution);
+function getTargetRasterSize(resolution = '', slideMode = DEFAULT_SLIDE_MODE) {
+  const targetResolution = getResolutionSize(resolution, slideMode);
   if (targetResolution) {
     return targetResolution;
   }
 
+  const { pptxSizeIn } = getSlideModeConfig(slideMode);
   return {
-    width: Math.round(TARGET_SLIDE_SIZE_IN.width * TARGET_RASTER_DPI),
-    height: Math.round(TARGET_SLIDE_SIZE_IN.height * TARGET_RASTER_DPI),
+    width: Math.round(pptxSizeIn.width * TARGET_RASTER_DPI),
+    height: Math.round(pptxSizeIn.height * TARGET_RASTER_DPI),
   };
 }
 
+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);
+}
+
+function getHtmlSlides(slidesDir) {
+  if (!fs.existsSync(slidesDir)) {
+    throw new Error(`Slides directory not found: ${slidesDir}`);
+  }
+
+  const files = fs.readdirSync(slidesDir)
+    .filter((fileName) => SLIDE_FILE_PATTERN.test(fileName))
+    .sort(sortSlideFiles);
+
+  if (files.length === 0) {
+    throw new Error(`No slide-*.html files found in ${slidesDir}`);
+  }
+
+  return files;
+}
+
 function printUsage() {
   process.stdout.write(
     [
@@ -58,6 +95,7 @@ function printUsage() {
       'Options:',
       `  --slides-dir <path>  Slide directory (default: ${DEFAULT_SLIDES_DIR})`,
       `  --output <path>      Output pptx path (default: ${DEFAULT_OUTPUT})`,
+      `  --mode <mode>        Slide mode: ${getSlideModeChoices().join('|')} (default: ${DEFAULT_SLIDE_MODE})`,
       `  --resolution <preset> Raster size preset: ${getResolutionChoices().join('|')}|4k (default: ${DEFAULT_RESOLUTION})`,
       '  -h, --help           Show this help message',
     ].join('\n'),
@@ -77,6 +115,7 @@ function parseArgs(args) {
   const options = {
     slidesDir: DEFAULT_SLIDES_DIR,
     output: DEFAULT_OUTPUT,
+    mode: DEFAULT_SLIDE_MODE,
     resolution: DEFAULT_RESOLUTION,
     help: false,
   };
@@ -110,6 +149,17 @@ function parseArgs(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;
+    }
+
     if (arg === '--resolution') {
       options.resolution = normalizeResolutionPreset(readOptionValue(args, i, '--resolution'));
       i += 1;
@@ -134,14 +184,17 @@ function parseArgs(args) {
 
   options.slidesDir = options.slidesDir.trim();
   options.output = options.output.trim();
+  options.mode = normalizeSlideMode(options.mode);
   options.resolution = normalizeResolutionPreset(options.resolution);
   return options;
 }
 
 async function convertSlide(htmlFile, pres, browser, options = {}) {
   const filePath = path.isAbsolute(htmlFile) ? htmlFile : path.join(process.cwd(), htmlFile);
+  const slideMode = normalizeSlideMode(options.mode || DEFAULT_SLIDE_MODE);
+  const fallbackSize = getSlideModeConfig(slideMode).framePx;
 
-  const page = await browser.newPage(buildPageOptions(options.resolution));
+  const page = await browser.newPage(buildPageOptions(options.resolution, slideMode));
   await page.goto(`file://${filePath}`);
 
   const bodyDimensions = await page.evaluate(() => {
@@ -154,14 +207,14 @@ async function convertSlide(htmlFile, pres, browser, options = {}) {
   });
 
   await page.setViewportSize({
-    width: normalizeDimension(bodyDimensions.width, DEFAULT_CAPTURE_VIEWPORT.width),
-    height: normalizeDimension(bodyDimensions.height, DEFAULT_CAPTURE_VIEWPORT.height),
+    width: normalizeDimension(bodyDimensions.width, fallbackSize.width),
+    height: normalizeDimension(bodyDimensions.height, fallbackSize.height),
   });
 
   const screenshot = await page.screenshot({ type: 'png' });
   await page.close();
 
-  const targetSize = getTargetRasterSize(options.resolution);
+  const targetSize = getTargetRasterSize(options.resolution, slideMode);
 
   const resized = await sharp(screenshot)
     .resize(targetSize.width, targetSize.height, { fit: 'fill' })
@@ -191,14 +244,18 @@ async function main(argv = process.argv.slice(2)) {
   }
 
   const pres = new PptxGenJS();
-  pres.layout = 'LAYOUT_WIDE';
+  const { pptxSizeIn } = getSlideModeConfig(options.mode);
+  pres.defineLayout({
+    name: 'SLIDES_GRAB_DYNAMIC',
+    width: pptxSizeIn.width,
+    height: pptxSizeIn.height,
+  });
+  pres.layout = 'SLIDES_GRAB_DYNAMIC';
 
   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((fileName) => fileName.endsWith('.html'))
-    .sort();
+  await ensureSlidesPassValidation(slidesDir, { exportLabel: 'PPTX export', slideMode: options.mode });
+  const files = getHtmlSlides(slidesDir);
 
   console.log(`Converting ${files.length} slides...`);
 
@@ -209,7 +266,7 @@ async function main(argv = process.argv.slice(2)) {
     const filePath = path.join(slidesDir, file);
     console.log(`  Processing: ${file}`);
     try {
-      const tmpPath = await convertSlide(filePath, pres, browser, { resolution: options.resolution });
+      const tmpPath = await convertSlide(filePath, pres, browser, { mode: options.mode, resolution: options.resolution });
       tmpFiles.push(tmpPath);
       console.log(`    ✓ ${file} done`);
     } catch (error) {
@@ -232,6 +289,7 @@ async function main(argv = process.argv.slice(2)) {
 
 module.exports = {
   buildPageOptions,
+  getHtmlSlides,
   getTargetRasterSize,
   main,
   parseArgs,

package/src/resolve.js

@@ -5,8 +5,8 @@
  *   1. Local (user's CWD) — per-project overrides
  *   2. Package root — built-in defaults
  *
- * slides directory, slide-outline.md, style-config.md → always local (CWD)
- * templates/, themes/ → local first, package fallback
+ * slides directory, slide-outline.md → always local (CWD)
+ * templates/ → local first, package fallback
  * scripts/ → always package
  */
 
@@ -60,27 +60,6 @@ export function resolveTemplate(name) {
   return null;
 }
 
-/**
- * Resolve a theme file. Local first, then package fallback.
- * @param {string} name — theme name without extension (e.g. "modern-dark")
- * @returns {{ path: string, source: 'local' | 'package' } | null}
- */
-export function resolveTheme(name) {
-  const fileName = name.endsWith('.css') ? name : `${name}.css`;
-
-  const localPath = join(getCwd(), 'themes', fileName);
-  if (existsSync(localPath)) {
-    return { path: localPath, source: 'local' };
-  }
-
-  const packagePath = join(PACKAGE_ROOT, 'themes', fileName);
-  if (existsSync(packagePath)) {
-    return { path: packagePath, source: 'package' };
-  }
-
-  return null;
-}
-
 /**
  * List all available templates (local + package, deduplicated).
  * @returns {Array<{ name: string, source: 'local' | 'package' }>}
@@ -122,34 +101,6 @@ export function listTemplates() {
   return Array.from(seen.values()).sort((a, b) => a.name.localeCompare(b.name));
 }
 
-/**
- * List all available themes (local + package, deduplicated).
- * @returns {Array<{ name: string, source: 'local' | 'package' }>}
- */
-export function listThemes() {
-  const seen = new Map();
-
-  const localDir = join(getCwd(), 'themes');
-  if (existsSync(localDir)) {
-    for (const f of readdirSync(localDir)) {
-      if (f.endsWith('.css')) {
-        seen.set(f, { name: f.replace('.css', ''), source: 'local' });
-      }
-    }
-  }
-
-  const pkgDir = join(PACKAGE_ROOT, 'themes');
-  if (existsSync(pkgDir)) {
-    for (const f of readdirSync(pkgDir)) {
-      if (f.endsWith('.css') && !seen.has(f)) {
-        seen.set(f, { name: f.replace('.css', ''), source: 'package' });
-      }
-    }
-  }
-
-  return Array.from(seen.values()).sort((a, b) => a.name.localeCompare(b.name));
-}
-
 /**
  * Resolve a script path. Always from package.
  * @param {string} relativePath — e.g. "scripts/validate-slides.js"

package/src/slide-mode.cjs

@@ -0,0 +1,72 @@
+const DEFAULT_SLIDE_MODE = 'presentation';
+const PT_TO_PX = 96 / 72;
+
+const SLIDE_MODES = Object.freeze({
+  presentation: Object.freeze({
+    name: 'presentation',
+    framePt: Object.freeze({ width: 720, height: 405 }),
+    framePx: Object.freeze({ width: 720 * PT_TO_PX, height: 405 * PT_TO_PX }),
+    screenshotPx: Object.freeze({ width: 1600, height: 900 }),
+    pptxSizeIn: Object.freeze({ width: 13.33, height: 7.5 }),
+    figmaSizeIn: Object.freeze({ width: 10, height: 5.625 }),
+    sizeLabel: '720pt x 405pt',
+    coordinateSpaceLabel: '960x540',
+    aspectRatioLabel: '16:9',
+  }),
+  'card-news': Object.freeze({
+    name: 'card-news',
+    framePt: Object.freeze({ width: 720, height: 720 }),
+    framePx: Object.freeze({ width: 720 * PT_TO_PX, height: 720 * PT_TO_PX }),
+    screenshotPx: Object.freeze({ width: 1600, height: 1600 }),
+    pptxSizeIn: Object.freeze({ width: 10, height: 10 }),
+    figmaSizeIn: Object.freeze({ width: 10, height: 10 }),
+    sizeLabel: '720pt x 720pt',
+    coordinateSpaceLabel: '960x960',
+    aspectRatioLabel: '1:1',
+  }),
+});
+
+function getSlideModeChoices() {
+  return Object.keys(SLIDE_MODES);
+}
+
+function normalizeSlideMode(value, options = {}) {
+  const {
+    allowEmpty = false,
+    optionName = '--mode',
+  } = options;
+
+  if (typeof value !== 'string') {
+    if (allowEmpty) {
+      return '';
+    }
+    throw new Error(`${optionName} must be one of: ${getSlideModeChoices().join(', ')}`);
+  }
+
+  const normalized = value.trim().toLowerCase();
+  if (normalized === '') {
+    if (allowEmpty) {
+      return '';
+    }
+    throw new Error(`${optionName} must be one of: ${getSlideModeChoices().join(', ')}`);
+  }
+
+  if (!SLIDE_MODES[normalized]) {
+    throw new Error(`Unknown ${optionName} value: ${value}. Expected one of: ${getSlideModeChoices().join(', ')}`);
+  }
+
+  return normalized;
+}
+
+function getSlideModeConfig(value = DEFAULT_SLIDE_MODE) {
+  return SLIDE_MODES[normalizeSlideMode(value, { optionName: '--mode' })];
+}
+
+module.exports = {
+  DEFAULT_SLIDE_MODE,
+  PT_TO_PX,
+  SLIDE_MODES,
+  getSlideModeChoices,
+  getSlideModeConfig,
+  normalizeSlideMode,
+};

package/src/validation/cli.js

@@ -1,3 +1,12 @@
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const {
+  DEFAULT_SLIDE_MODE,
+  getSlideModeChoices,
+  normalizeSlideMode,
+} = require('../slide-mode.cjs');
+
 export const DEFAULT_SLIDES_DIR = 'slides';
 export const DEFAULT_VALIDATE_FORMAT = 'concise';
 export const VALIDATE_FORMATS = ['concise', 'json', 'json-full'];
@@ -14,6 +23,7 @@ export function parseValidateCliArgs(args) {
   const options = {
     slidesDir: DEFAULT_SLIDES_DIR,
     format: DEFAULT_VALIDATE_FORMAT,
+    mode: DEFAULT_SLIDE_MODE,
     help: false,
     slides: [],
   };
@@ -48,6 +58,17 @@ export function parseValidateCliArgs(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;
+    }
+
     if (arg === '--slide') {
       options.slides.push(readOptionValue(args, i, '--slide'));
       i += 1;
@@ -72,6 +93,7 @@ export function parseValidateCliArgs(args) {
 
   options.slidesDir = options.slidesDir.trim();
   options.format = options.format.trim();
+  options.mode = normalizeSlideMode(options.mode);
 
   if (!VALIDATE_FORMATS.includes(options.format)) {
     throw new Error(`Unknown --format value: ${options.format}. Expected one of: ${VALIDATE_FORMATS.join(', ')}`);
@@ -91,6 +113,7 @@ export function getValidateUsage() {
     'Options:',
     `  --slides-dir <path>  Slide directory (default: ${DEFAULT_SLIDES_DIR})`,
     `  --format <format>   Output format: ${VALIDATE_FORMATS.join(', ')} (default: ${DEFAULT_VALIDATE_FORMAT})`,
+    `  --mode <mode>       Slide mode: ${getSlideModeChoices().join(', ')} (default: ${DEFAULT_SLIDE_MODE})`,
     '  --slide <file>      Validate only the named slide file (repeatable)',
     '  -h, --help           Show this help message',
   ].join('\n');

package/src/validation/core.js

@@ -1,4 +1,5 @@
 import { access, readdir } from 'node:fs/promises';
+import { createRequire } from 'node:module';
 import { basename, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { chromium } from 'playwright';
@@ -9,12 +10,14 @@ import {
   resolveSlideSourcePath,
 } from '../image-contract.js';
 
-export const FRAME_PT = { width: 720, height: 405 };
-export const PT_TO_PX = 96 / 72;
-export const FRAME_PX = {
-  width: FRAME_PT.width * PT_TO_PX,
-  height: FRAME_PT.height * PT_TO_PX,
-};
+const require = createRequire(import.meta.url);
+const {
+  DEFAULT_SLIDE_MODE,
+  getSlideModeConfig,
+} = require('../slide-mode.cjs');
+
+export const FRAME_PT = getSlideModeConfig(DEFAULT_SLIDE_MODE).framePt;
+export const FRAME_PX = getSlideModeConfig(DEFAULT_SLIDE_MODE).framePx;
 export const SLIDE_FILE_PATTERN = /^slide-.*\.html$/i;
 export const TEXT_SELECTOR = 'p,h1,h2,h3,h4,h5,h6,li';
 export const TOLERANCE_PX = 0.5;
@@ -58,28 +61,30 @@ export function summarizeSlides(slides) {
   return summary;
 }
 
-export function createValidationResult(slides) {
+export function createValidationResult(slides, slideMode = DEFAULT_SLIDE_MODE) {
+  const { framePt, framePx } = getSlideModeConfig(slideMode);
   return {
     generatedAt: new Date().toISOString(),
     frame: {
-      widthPt: FRAME_PT.width,
-      heightPt: FRAME_PT.height,
-      widthPx: FRAME_PX.width,
-      heightPx: FRAME_PX.height,
+      widthPt: framePt.width,
+      heightPt: framePt.height,
+      widthPx: framePx.width,
+      heightPx: framePx.height,
     },
     slides,
     summary: summarizeSlides(slides),
   };
 }
 
-export function createValidationFailure(error) {
+export function createValidationFailure(error, slideMode = DEFAULT_SLIDE_MODE) {
+  const { framePt, framePx } = getSlideModeConfig(slideMode);
   return {
     generatedAt: new Date().toISOString(),
     frame: {
-      widthPt: FRAME_PT.width,
-      heightPt: FRAME_PT.height,
-      widthPx: FRAME_PX.width,
-      heightPx: FRAME_PX.height,
+      widthPt: framePt.width,
+      heightPt: framePt.height,
+      widthPx: framePx.width,
+      heightPx: framePx.height,
     },
     slides: [],
     summary: {
@@ -347,9 +352,10 @@ export function selectSlideFiles(slideFiles, selectedSlides = [], slidesDir = ''
   return slideFiles.filter((slide) => available.has(slide) && requested.includes(slide));
 }
 
-export async function inspectSlide(page, fileName, slidesDir) {
+export async function inspectSlide(page, fileName, slidesDir, slideMode = DEFAULT_SLIDE_MODE) {
   const slidePath = join(slidesDir, fileName);
   const slideUrl = pathToFileURL(slidePath).href;
+  const { framePx, sizeLabel } = getSlideModeConfig(slideMode);
 
   await page.goto(slideUrl, { waitUntil: 'load' });
   await page.evaluate(async () => {
@@ -359,7 +365,7 @@ export async function inspectSlide(page, fileName, slidesDir) {
   });
 
   const inspection = await page.evaluate(
-    ({ framePx, textSelector, tolerancePx }) => {
+    ({ framePx, sizeLabel, textSelector, tolerancePx }) => {
       const skipTags = new Set(['SCRIPT', 'STYLE', 'META', 'LINK', 'HEAD', 'TITLE', 'NOSCRIPT']);
       const critical = [];
       const warning = [];
@@ -552,7 +558,7 @@ export async function inspectSlide(page, fileName, slidesDir) {
         if (outsideFrame) {
           critical.push({
             code: 'overflow-outside-frame',
-            message: 'Element exceeds the 720pt x 405pt slide frame.',
+            message: `Element exceeds the ${sizeLabel} slide frame.`,
             element: elementPath(element),
             bbox: normalizeRect(rect),
             frame: normalizeRect(frameRect),
@@ -663,7 +669,8 @@ export async function inspectSlide(page, fileName, slidesDir) {
       };
     },
     {
-      framePx: FRAME_PX,
+      framePx,
+      sizeLabel,
       textSelector: TEXT_SELECTOR,
       tolerancePx: TOLERANCE_PX,
     },
@@ -696,12 +703,12 @@ export async function inspectSlide(page, fileName, slidesDir) {
   };
 }
 
-export async function scanSlides(page, slidesDir, slideFiles) {
+export async function scanSlides(page, slidesDir, slideFiles, slideMode = DEFAULT_SLIDE_MODE) {
   const slides = [];
 
   for (const slideFile of slideFiles) {
     try {
-      const result = await inspectSlide(page, slideFile, slidesDir);
+      const result = await inspectSlide(page, slideFile, slidesDir, slideMode);
       slides.push(result);
     } catch (error) {
       slides.push({
@@ -740,7 +747,10 @@ export function formatValidationFailureForExport(result, exportLabel = 'Export')
   }
 
   const suffix = findings.length > 0 ? `\n${findings.join('\n')}` : '';
-  return `${exportLabel} blocked by slide validation. Run \`slides-grab validate --slides-dir <path>\` for full diagnostics.${suffix}`;
+  const modeHint = result.slideMode && result.slideMode !== DEFAULT_SLIDE_MODE
+    ? ` --mode ${result.slideMode}`
+    : '';
+  return `${exportLabel} blocked by slide validation. Run \`slides-grab validate --slides-dir <path>${modeHint}\` for full diagnostics.${suffix}`;
 }
 
 const EXPORT_BLOCKING_IMAGE_CONTRACT_CODES = new Set([
@@ -799,6 +809,7 @@ export async function ensureSlidesPassValidation(
   slidesDir,
   {
     exportLabel = 'Export',
+    slideMode = DEFAULT_SLIDE_MODE,
     shouldBlockIssue = isBlockingImageContractIssue,
   } = {},
 ) {
@@ -812,8 +823,11 @@ export async function ensureSlidesPassValidation(
   const page = await context.newPage();
 
   try {
-    const slides = await scanSlides(page, slidesDir, slideFiles);
-    const result = createValidationResult(slides);
+    const slides = await scanSlides(page, slidesDir, slideFiles, slideMode);
+    const result = {
+      ...createValidationResult(slides, slideMode),
+      slideMode,
+    };
     const blockingResult = filterExportBlockingSlides(result, shouldBlockIssue);
     if (blockingResult.summary.failedSlides > 0) {
       throw new Error(formatValidationFailureForExport(blockingResult, exportLabel));

package/templates/design-styles/README.md

@@ -0,0 +1,19 @@
+# Design Style Collections
+
+slides-grab bundles 35 design styles: 30 derived from [corazzon/pptx-design-styles](https://github.com/corazzon/pptx-design-styles) (MIT) plus 5 slides-grab originals.
+
+These styles are reference directions for slide generation, not drop-in HTML slide templates. Agents may also design fully custom visuals beyond the bundled collection.
+
+## Recommended workflow
+
+1. `slides-grab list-styles`
+2. `slides-grab preview-styles` to open the visual gallery in browser
+3. Tell the agent which style to use, or ask for something custom
+
+The preview/select flow is intentionally simple: it keeps design approval inside the CLI and a local HTML preview page instead of adding a separate app.
+
+## Citation
+
+- Upstream collection: `corazzon/pptx-design-styles`
+- URL: <https://github.com/corazzon/pptx-design-styles>
+- Reference used in this repo: `references/styles.md`