openfig-cli 0.3.18 → 0.3.20

package/bin/cli.mjs

@@ -30,6 +30,7 @@ const COMMANDS = {
   'remove-slide':   './commands/remove-slide.mjs',
   'roundtrip':      './commands/roundtrip.mjs',
   'export':         './commands/export.mjs',
+  'pdf':            './commands/pdf.mjs',
 };
 
 const arg2 = process.argv[2];
@@ -40,6 +41,7 @@ if (!arg2 || arg2 === '--help' || arg2 === '-h') {
   console.log('Usage: openfig <command> [args...]\n');
   console.log('Commands:');
   console.log('  export         Export slides as images (PNG/JPG/WEBP)');
+  console.log('  pdf            Export slides as a multi-page PDF');
   console.log('  inspect        Show document structure (node hierarchy tree)');
   console.log('  list-text      List all text content in the deck');
   console.log('  list-overrides List editable override keys per symbol');

package/bin/commands/pdf.mjs

@@ -0,0 +1,66 @@
+/**
+ * pdf — Export slides from a .deck file to a multi-page PDF.
+ *
+ * Usage:
+ *   openfig pdf <file.deck> [options]
+ *
+ * Options:
+ *   -o <file.pdf>   Output PDF path (default: <deckname>.pdf)
+ *   --slide <n>     Export only slide N (1-based). Omit to export all.
+ *   --scale <n>     Zoom factor: 1 = 1920×1080, 0.5 = 960×540 (default: 1)
+ *   --width <px>    Output width in pixels (height scales proportionally)
+ *   --fonts <dir>   Extra font directory to load (can repeat)
+ */
+
+import { writeFileSync } from 'fs';
+import { parse, resolve } from 'path';
+import { PDFDocument } from 'pdf-lib';
+import { FigDeck } from '../../lib/core/fig-deck.mjs';
+import { renderDeck, registerFontDir } from '../../lib/rasterizer/deck-rasterizer.mjs';
+import { resolveFonts } from '../../lib/rasterizer/font-resolver.mjs';
+
+export async function run(args, flags) {
+  const file = args[0];
+  if (!file) {
+    console.error('Usage: openfig pdf <file.deck> [options]\n');
+    console.error('Options:');
+    console.error('  -o <file.pdf>   Output PDF path (default: <deckname>.pdf)');
+    console.error('  --slide <n>     Export only slide N (1-based)');
+    console.error('  --scale <n>     Zoom factor: 1 = 1920×1080 (default: 1)');
+    console.error('  --width <px>    Output width in pixels');
+    console.error('  --fonts <dir>   Extra font directory to load');
+    process.exit(1);
+  }
+
+  const defaultOut = parse(file).name + '.pdf';
+  const outPath = resolve(flags.o ?? flags.output ?? defaultOut);
+
+  const renderOpts = {};
+  if (flags.width) renderOpts.width = parseInt(flags.width);
+  else if (flags.scale) renderOpts.scale = parseFloat(flags.scale);
+
+  const fontDirs = [].concat(flags.fonts ?? []);
+  for (const d of fontDirs) registerFontDir(resolve(d));
+
+  const deck = await FigDeck.fromDeckFile(file);
+  await resolveFonts(deck, { quiet: false });
+
+  const slideFilter = flags.slide ? parseInt(flags.slide) : null;
+  const slides = await renderDeck(deck, renderOpts);
+
+  const doc = await PDFDocument.create();
+
+  let count = 0;
+  for (const { index, png } of slides) {
+    if (slideFilter && index + 1 !== slideFilter) continue;
+    const image = await doc.embedPng(png);
+    const page = doc.addPage([image.width, image.height]);
+    page.drawImage(image, { x: 0, y: 0, width: image.width, height: image.height });
+    count++;
+    console.log(`  slide ${index + 1}  →  page ${count}`);
+  }
+
+  const pdfBytes = await doc.save();
+  writeFileSync(outPath, pdfBytes);
+  console.log(`\nExported ${count} slide(s) to ${outPath} (${pdfBytes.length} bytes)`);
+}

package/lib/core/fig-deck.mjs

@@ -278,12 +278,64 @@ export class FigDeck {
     });
   }
 
+  /**
+   * Validate deck integrity before saving. Warns about issues that would
+   * cause Figma to fail silently (blank slides, missing symbols, etc.).
+   */
+  validate() {
+    const warnings = [];
+    const symbols = this.getSymbols().filter(s => s.phase !== 'REMOVED');
+
+    // Check for variant name / variantPropSpecs mismatch
+    const byKey = new Map();
+    for (const sym of symbols) {
+      if (!sym.componentKey) continue;
+      if (!byKey.has(sym.componentKey)) byKey.set(sym.componentKey, []);
+      byKey.get(sym.componentKey).push(sym);
+    }
+    for (const [key, variants] of byKey) {
+      if (variants.length < 2) continue;
+      const specValues = new Set();
+      for (const sym of variants) {
+        if (sym.variantPropSpecs) {
+          for (const spec of sym.variantPropSpecs) specValues.add(spec.value);
+        }
+      }
+      for (const sym of variants) {
+        const parts = (sym.name || '').split(', ').map(p => p.split('=')[1]).filter(Boolean);
+        for (const val of parts) {
+          if (!specValues.has(val)) {
+            const id = `${sym.guid.sessionID}:${sym.guid.localID}`;
+            warnings.push(`SYMBOL ${id} "${sym.name}": variant value "${val}" not in variantPropSpecs — Figma will show blank slides`);
+          }
+        }
+      }
+    }
+
+    // Check for instances referencing missing symbols
+    for (const node of this.message.nodeChanges) {
+      if (node.type !== 'INSTANCE' || node.phase === 'REMOVED') continue;
+      const sid = node.symbolData?.symbolID;
+      if (!sid) continue;
+      const symId = `${sid.sessionID}:${sid.localID}`;
+      const sym = this.getNode(symId);
+      if (!sym || sym.type !== 'SYMBOL') {
+        const nid = `${node.guid.sessionID}:${node.guid.localID}`;
+        warnings.push(`INSTANCE ${nid} "${node.name}": references missing SYMBOL ${symId}`);
+      }
+    }
+
+    for (const w of warnings) console.warn(`⚠️  ${w}`);
+    return warnings;
+  }
+
   /**
    * Save as a .deck (ZIP archive).
    * @param {string} outPath - Output file path
    * @param {object} opts - { imagesDir, thumbnail, meta }
    */
   async saveDeck(outPath, opts = {}) {
+    this.validate();
     const figBuf = await this.encodeFig();
     const absOut = resolve(outPath);
 

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": "0.2",
   "name": "openfig",
-  "version": "0.3.18",
+  "version": "0.3.20",
   "description": "Open-source tools for Figma file parsing and rendering",
   "author": {
     "name": "OpenFig Contributors"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openfig-cli",
-  "version": "0.3.18",
+  "version": "0.3.20",
   "description": "OpenFig — Open-source tools for Figma file parsing and rendering",
   "type": "module",
   "bin": {
@@ -49,6 +49,7 @@
     "fzstd": "^0.1.1",
     "kiwi-schema": "^0.5.0",
     "pako": "^2.1.0",
+    "pdf-lib": "^1.17.1",
     "sharp": "^0.34.5",
     "ssim.js": "^3.5.0",
     "yazl": "^3.3.1",