slides-grab 1.2.6 → 1.3.1

package/runtimes/claude-code/agents/design-critic-agent.md

@@ -0,0 +1,23 @@
+---
+name: design-critic-agent
+description: Run the slides-grab design gate before export.
+tools: Read, Grep, Glob, Bash, Task
+---
+
+Use the canonical gate in `skills/slides-grab-design/references/design-gate.md`.
+
+Required workflow:
+
+1. Run `slides-grab validate --slides-dir <slides-dir>`.
+2. Render evidence with `slides-grab png --slides-dir <slides-dir> --output-dir <slides-dir>/.slides-grab/gate-preview`.
+3. Produce two read-only review reports:
+   - Pass A: System Contract / Constraint Integrity.
+   - Pass B: Audience Impact / Expressive Readability.
+   Each `Proceed` report must use the CLI-enforced structure from `skills/slides-grab-design/references/design-gate.md`: role title, `VERDICT: PASS`, confidence, rendered PNG evidence filenames, current `slide-*.html: <sha256>` fingerprints, `Unresolved Critical: 0`, `Blocking findings: None`, findings table, and all required checks marked `PASS`.
+4. If both passes conclude Proceed, record the gate with:
+
+```bash
+slides-grab design-gate --slides-dir <slides-dir> --verdict proceed --pass-a-report <pass-a.md> --pass-b-report <pass-b.md>
+```
+
+If either pass finds blocking issues, or if `slides-grab design-gate` rejects the reports, fix the slides/reports and repeat from validation and fresh rendered evidence. Do not run `slides-grab pdf`, `slides-grab convert`, or `slides-grab figma` until the CLI gate records `proceed`.

package/runtimes/codex/agents/slides-grab-design-critic.md

@@ -0,0 +1,22 @@
+---
+name: slides-grab-design-critic
+description: Run the slides-grab design gate before export.
+---
+
+Use the canonical gate in `skills/slides-grab-design/references/design-gate.md`.
+
+Required workflow:
+
+1. Run `slides-grab validate --slides-dir <slides-dir>`.
+2. Render evidence with `slides-grab png --slides-dir <slides-dir> --output-dir <slides-dir>/.slides-grab/gate-preview`.
+3. Produce two read-only review reports:
+   - Pass A: System Contract / Constraint Integrity.
+   - Pass B: Audience Impact / Expressive Readability.
+   Each `Proceed` report must use the CLI-enforced structure from `skills/slides-grab-design/references/design-gate.md`: role title, `VERDICT: PASS`, confidence, rendered PNG evidence filenames, current `slide-*.html: <sha256>` fingerprints, `Unresolved Critical: 0`, `Blocking findings: None`, findings table, and all required checks marked `PASS`.
+4. If both passes conclude Proceed, record the gate with:
+
+```bash
+slides-grab design-gate --slides-dir <slides-dir> --verdict proceed --pass-a-report <pass-a.md> --pass-b-report <pass-b.md>
+```
+
+If either pass finds blocking issues, or if `slides-grab design-gate` rejects the reports, fix the slides/reports and repeat from validation and fresh rendered evidence. Do not run `slides-grab pdf`, `slides-grab convert`, or `slides-grab figma` until the CLI gate records `proceed`.

package/scripts/design-gate.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { ensureSlidesPassValidation } from './validate-slides.js';
+import { assertProceedReportsComplete } from '../src/design-gate-report.js';
+import {
+  buildDesignGatePaths,
+  buildDesignGateReport,
+  collectFileFingerprints,
+  collectSlideFingerprints,
+  createDesignGateState,
+  findGateSlideFiles,
+  normalizeGateVerdict,
+  writeDesignGateState,
+} from '../src/design-gate-state.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(__dirname, '..');
+const DEFAULT_SLIDES_DIR = 'slides';
+const DEFAULT_SLIDE_MODE = 'presentation';
+const DEFAULT_RESOLUTION = '2160p';
+
+function printUsage() {
+  process.stdout.write(
+    [
+      'Usage: slides-grab design-gate [options]',
+      '',
+      'Options:',
+      `  --slides-dir <path>       Slide directory (default: ${DEFAULT_SLIDES_DIR})`,
+      `  --slide-mode <mode>       Slide mode: presentation|card-news (default: ${DEFAULT_SLIDE_MODE})`,
+      `  --resolution <preset>     PNG evidence resolution preset (default: ${DEFAULT_RESOLUTION})`,
+      '  --verdict <verdict>       Gate verdict: proceed|revise|rethink',
+      '  --pass-a-report <path>    Pass A review report file',
+      '  --pass-b-report <path>    Pass B review report file',
+      '  --output-dir <path>       PNG evidence directory (default: <slides-dir>/.slides-grab/gate-preview)',
+      '  -h, --help                Show this help message',
+    ].join('\n'),
+  );
+  process.stdout.write('\n');
+}
+
+function parseArgs(args) {
+  const options = {
+    slidesDir: DEFAULT_SLIDES_DIR,
+    slideMode: DEFAULT_SLIDE_MODE,
+    resolution: DEFAULT_RESOLUTION,
+    verdict: '',
+    passAReport: '',
+    passBReport: '',
+    outputDir: '',
+    help: false,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+      continue;
+    }
+
+    if (ARGUMENT_READERS.has(arg)) {
+      options[ARGUMENT_READERS.get(arg)] = readOptionValue(args, index, arg);
+      index += 1;
+      continue;
+    }
+
+    const equalSignIndex = arg.indexOf('=');
+    if (equalSignIndex > -1) {
+      const name = arg.slice(0, equalSignIndex);
+      const value = arg.slice(equalSignIndex + 1);
+      if (ARGUMENT_READERS.has(name)) {
+        options[ARGUMENT_READERS.get(name)] = value;
+        continue;
+      }
+    }
+
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  if (options.help) return options;
+
+  options.slidesDir = requireNonEmpty(options.slidesDir, '--slides-dir');
+  options.slideMode = requireNonEmpty(options.slideMode, '--slide-mode');
+  options.resolution = requireNonEmpty(options.resolution, '--resolution');
+  options.verdict = normalizeGateVerdict(requireNonEmpty(options.verdict, '--verdict'));
+  options.passAReport = requireNonEmpty(options.passAReport, '--pass-a-report');
+  options.passBReport = requireNonEmpty(options.passBReport, '--pass-b-report');
+  if (options.outputDir) options.outputDir = options.outputDir.trim();
+  return options;
+}
+
+const ARGUMENT_READERS = new Map([
+  ['--slides-dir', 'slidesDir'],
+  ['--slide-mode', 'slideMode'],
+  ['--resolution', 'resolution'],
+  ['--verdict', 'verdict'],
+  ['--pass-a-report', 'passAReport'],
+  ['--pass-b-report', 'passBReport'],
+  ['--output-dir', 'outputDir'],
+]);
+
+function readOptionValue(args, index, optionName) {
+  const value = args[index + 1];
+  if (!value || value.startsWith('-')) {
+    throw new Error(`Missing value for ${optionName}.`);
+  }
+  return value;
+}
+
+function requireNonEmpty(value, optionName) {
+  const trimmed = String(value || '').trim();
+  if (!trimmed) throw new Error(`${optionName} must be a non-empty string.`);
+  return trimmed;
+}
+
+async function renderGateEvidence(options, outputDir) {
+  await mkdir(outputDir, { recursive: true });
+  const scriptPath = resolve(packageRoot, 'scripts/html2png.js');
+  const args = [
+    scriptPath,
+    '--slides-dir',
+    options.slidesDir,
+    '--output-dir',
+    outputDir,
+    '--slide-mode',
+    options.slideMode,
+    '--resolution',
+    options.resolution,
+  ];
+
+  await new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(process.execPath, args, {
+      cwd: process.cwd(),
+      stdio: 'inherit',
+      env: { ...process.env, PPT_AGENT_PACKAGE_ROOT: packageRoot },
+    });
+    child.on('error', rejectPromise);
+    child.on('close', (code, signal) => {
+      if (signal) {
+        rejectPromise(new Error(`PNG evidence render terminated by signal ${signal}.`));
+        return;
+      }
+      if (code !== 0) {
+        rejectPromise(new Error(`PNG evidence render failed with exit code ${code}.`));
+        return;
+      }
+      resolvePromise();
+    });
+  });
+}
+
+async function readEvidenceReport(filePath, label) {
+  const resolvedPath = resolve(process.cwd(), filePath);
+  if (!existsSync(resolvedPath)) {
+    throw new Error(`${label} report not found: ${resolvedPath}`);
+  }
+  const report = (await readFile(resolvedPath, 'utf-8')).trim();
+  if (!report) {
+    throw new Error(`${label} report is empty: ${resolvedPath}`);
+  }
+  return { resolvedPath, report };
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const options = parseArgs(argv);
+  if (options.help) {
+    printUsage();
+    return;
+  }
+
+  const paths = buildDesignGatePaths(options.slidesDir);
+  const previewDir = options.outputDir ? resolve(process.cwd(), options.outputDir) : paths.previewDir;
+  await ensureSlidesPassValidation(paths.slidesDir, {
+    exportLabel: 'design gate',
+    slideMode: options.slideMode,
+    shouldBlockIssue: () => true,
+  });
+  await renderGateEvidence(options, previewDir);
+
+  const passA = await readEvidenceReport(options.passAReport, 'Pass A');
+  const passB = await readEvidenceReport(options.passBReport, 'Pass B');
+  let gateValidation = { status: options.verdict === 'proceed' ? 'passed' : 'not-run' };
+  const slideFiles = await findGateSlideFiles(paths.slidesDir);
+  const slideFingerprints = await collectSlideFingerprints(paths.slidesDir);
+  const evidenceFiles = slideFiles.map((fileName) => fileName.replace(/\.html$/i, '.png'));
+  const previewRelativeDir = relative(paths.slidesDir, previewDir);
+  const previewFingerprintFiles = evidenceFiles.map((fileName) => join(previewRelativeDir, fileName));
+  const passReportFingerprintFiles = [
+    relative(paths.slidesDir, passA.resolvedPath),
+    relative(paths.slidesDir, passB.resolvedPath),
+  ];
+
+  if (options.verdict === 'proceed') {
+    gateValidation = assertProceedReportsComplete({
+      passAReport: passA.report,
+      passBReport: passB.report,
+      evidenceFiles,
+      slideFingerprints,
+    });
+  }
+  const state = await createDesignGateState({
+    slidesDir: paths.slidesDir,
+    slideMode: options.slideMode,
+    resolution: options.resolution,
+    verdict: options.verdict,
+    previewDir,
+    reportPath: paths.reportPath,
+    passA: { reportPath: passA.resolvedPath, summary: firstLine(passA.report), ...gateValidation.passA },
+    passB: { reportPath: passB.resolvedPath, summary: firstLine(passB.report), ...gateValidation.passB },
+    gateValidation,
+    passReportFingerprints: await collectFileFingerprints(paths.slidesDir, passReportFingerprintFiles),
+    previewFingerprints: await collectFileFingerprints(paths.slidesDir, previewFingerprintFiles),
+  });
+  const report = buildDesignGateReport(state, passA.report, passB.report);
+  await writeDesignGateState(paths.slidesDir, state, report);
+
+  process.stdout.write(`Design gate recorded: ${state.verdict}\n`);
+  process.stdout.write(`Evidence PNGs: ${previewDir}\n`);
+  process.stdout.write(`Gate report: ${paths.reportPath}\n`);
+  process.stdout.write(`Gate state: ${paths.statePath}\n`);
+
+  if (state.verdict !== 'proceed') {
+    process.exitCode = 1;
+  }
+}
+
+function firstLine(value) {
+  return value.split(/\r?\n/).find((line) => line.trim())?.trim() || '';
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+  });
+}

package/scripts/editor-server.js

@@ -816,6 +816,7 @@ async function startServer(opts) {
         userPrompt: prompt,
         slideMode: opts.mode,
         selections: normalizedSelections,
+        designBaseDir: slidesDirectory,
       });
 
       const usesClaude = isClaudeModel(selectedModel);

package/scripts/html2png.js

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+
+import { mkdir, readdir } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { chromium } from 'playwright';
+
+import { ensureSlidesPassValidation } from './validate-slides.js';
+
+const require = createRequire(import.meta.url);
+const {
+  getResolutionChoices,
+  getResolutionSize,
+  normalizeResolutionPreset,
+} = require('../src/export-resolution.cjs');
+const {
+  DEFAULT_SLIDE_MODE,
+  getSlideModeChoices,
+  getSlideModeConfig,
+  normalizeSlideMode,
+} = require('../src/slide-mode.cjs');
+
+const DEFAULT_SLIDES_DIR = 'slides';
+const DEFAULT_RESOLUTION = '2160p';
+const DEFAULT_CAPTURE_DEVICE_SCALE_FACTOR = 2;
+const SLIDE_FILE_PATTERN = /^slide-.*\.html$/i;
+const RENDER_SETTLE_MS = 120;
+
+function printUsage() {
+  process.stdout.write(
+    [
+      'Usage: node scripts/html2png.js [options]',
+      '',
+      'Options:',
+      `  --slides-dir <path>   Slide directory (default: ${DEFAULT_SLIDES_DIR})`,
+      '  --output-dir <path>   Output directory for PNG files (default: <slides-dir>/out-png)',
+      `  --slide-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',
+      '',
+      'Examples:',
+      '  node scripts/html2png.js --slides-dir slides',
+      '  node scripts/html2png.js --slides-dir cards --slide-mode card-news',
+      '  node scripts/html2png.js --slides-dir slides --resolution 1440p',
+    ].join('\n'),
+  );
+  process.stdout.write('\n');
+}
+
+function readOptionValue(args, index, optionName) {
+  const next = args[index + 1];
+  if (!next || next.startsWith('-')) {
+    throw new Error(`Missing value for ${optionName}.`);
+  }
+  return next;
+}
+
+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 parseCliArgs(args) {
+  const options = {
+    slidesDir: DEFAULT_SLIDES_DIR,
+    outputDir: '',
+    slideMode: DEFAULT_SLIDE_MODE,
+    resolution: DEFAULT_RESOLUTION,
+    help: false,
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+      continue;
+    }
+
+    if (arg === '--slides-dir') {
+      options.slidesDir = readOptionValue(args, i, '--slides-dir');
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--slides-dir=')) {
+      options.slidesDir = arg.slice('--slides-dir='.length);
+      continue;
+    }
+
+    if (arg === '--output-dir') {
+      options.outputDir = readOptionValue(args, i, '--output-dir');
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--output-dir=')) {
+      options.outputDir = arg.slice('--output-dir='.length);
+      continue;
+    }
+
+    if (arg === '--slide-mode') {
+      options.slideMode = normalizeSlideMode(
+        readOptionValue(args, i, '--slide-mode'),
+        { optionName: '--slide-mode' },
+      );
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--slide-mode=')) {
+      options.slideMode = normalizeSlideMode(
+        arg.slice('--slide-mode='.length),
+        { optionName: '--slide-mode' },
+      );
+      continue;
+    }
+
+    if (arg === '--resolution') {
+      options.resolution = normalizeResolutionPreset(
+        readOptionValue(args, i, '--resolution'),
+        { allowEmpty: false },
+      );
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--resolution=')) {
+      options.resolution = normalizeResolutionPreset(
+        arg.slice('--resolution='.length),
+        { allowEmpty: false },
+      );
+      continue;
+    }
+
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  return options;
+}
+
+function computeDeviceScaleFactor(resolution, slideMode) {
+  const { framePx } = getSlideModeConfig(slideMode);
+  const target = getResolutionSize(resolution, slideMode);
+  if (!target) return DEFAULT_CAPTURE_DEVICE_SCALE_FACTOR;
+  return target.height / framePx.height;
+}
+
+async function discoverSlideFiles(slidesDir) {
+  const entries = await readdir(slidesDir);
+  return entries
+    .filter((name) => SLIDE_FILE_PATTERN.test(name))
+    .sort(sortSlideFiles);
+}
+
+async function renderSlideToPng(page, slidesDir, slideFile, outputPath) {
+  const url = pathToFileURL(join(slidesDir, slideFile)).href;
+  await page.goto(url, { waitUntil: 'load' });
+  await page.evaluate(async () => {
+    if (document.fonts?.ready) {
+      await document.fonts.ready;
+    }
+  });
+  await page.waitForTimeout(RENDER_SETTLE_MS);
+  await page.screenshot({ path: outputPath, fullPage: false });
+}
+
+async function main() {
+  let options;
+  try {
+    options = parseCliArgs(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    printUsage();
+    process.exit(2);
+  }
+
+  if (options.help) {
+    printUsage();
+    return;
+  }
+
+  const slidesDir = resolve(process.cwd(), options.slidesDir);
+  const outputDir = resolve(
+    process.cwd(),
+    options.outputDir || join(options.slidesDir, 'out-png'),
+  );
+
+  await ensureSlidesPassValidation(slidesDir, {
+    exportLabel: 'PNG export',
+    slideMode: options.slideMode,
+  });
+
+  const slideFiles = await discoverSlideFiles(slidesDir);
+  if (slideFiles.length === 0) {
+    process.stderr.write(`No slide-*.html files found in ${slidesDir}\n`);
+    process.exit(1);
+  }
+
+  await mkdir(outputDir, { recursive: true });
+
+  const { framePx } = getSlideModeConfig(options.slideMode);
+  const deviceScaleFactor = computeDeviceScaleFactor(
+    options.resolution,
+    options.slideMode,
+  );
+  const outputSize = getResolutionSize(options.resolution, options.slideMode) || {
+    width: framePx.width * deviceScaleFactor,
+    height: framePx.height * deviceScaleFactor,
+  };
+
+  process.stdout.write(
+    `Rendering ${slideFiles.length} slide(s) at ${outputSize.width}x${outputSize.height} (${options.slideMode})\n`,
+  );
+
+  const browser = await chromium.launch({ headless: true });
+  try {
+    const context = await browser.newContext({
+      viewport: { width: framePx.width, height: framePx.height },
+      deviceScaleFactor,
+    });
+    const page = await context.newPage();
+
+    for (const slideFile of slideFiles) {
+      const outputName = slideFile.replace(/\.html$/i, '.png');
+      const outputPath = join(outputDir, outputName);
+      await renderSlideToPng(page, slidesDir, slideFile, outputPath);
+      process.stdout.write(`  ${outputName}\n`);
+    }
+
+    await context.close();
+  } finally {
+    await browser.close();
+  }
+
+  process.stdout.write(`PNG export complete: ${outputDir}\n`);
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error?.stack || error?.message || error}\n`);
+  process.exit(1);
+});