openfig-cli 0.3.20 → 0.3.22

package/README.md

@@ -53,6 +53,10 @@ npm install -g openfig-cli
 
 Node 18+. No build step. Pure ESM.
 
+## File Format Support
+
+All CLI commands work on both `.deck` (Figma Slides) and `.fig` (Figma Design) files. Pass either format wherever a file path is expected.
+
 ## Quick Start
 
 ```bash

package/bin/cli.mjs

@@ -2,7 +2,7 @@
 /**
  * OpenFig — Open-source tools for Figma file parsing and rendering.
  *
- * Usage: openfig <command> [args...]
+ * Usage: openfig <command> <file.deck | file.fig> [args...]
  *
  * Commands:
  *   inspect        Show document structure (node hierarchy tree)
@@ -38,7 +38,7 @@ let command, rawArgs;
 
 if (!arg2 || arg2 === '--help' || arg2 === '-h') {
   console.log(`OpenFig — Open-source tools for Figma file parsing and rendering\n`);
-  console.log('Usage: openfig <command> [args...]\n');
+  console.log('Usage: openfig <command> <file.deck | file.fig> [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');

package/lib/core/fig-deck.mjs

@@ -325,6 +325,56 @@ export class FigDeck {
       }
     }
 
+    // --- Color contrast validation ---
+    // WCAG relative luminance
+    function luminance(r, g, b) {
+      const [rs, gs, bs] = [r, g, b].map(c =>
+        c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4)
+      );
+      return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
+    }
+
+    function contrastRatio(l1, l2) {
+      const lighter = Math.max(l1, l2);
+      const darker = Math.min(l1, l2);
+      return (lighter + 0.05) / (darker + 0.05);
+    }
+
+    function extractColor(paints) {
+      if (!paints || paints.length === 0) return null;
+      const paint = paints[0];
+      if (paint.color) return paint.color;
+      return null;
+    }
+
+    for (const slide of this.getActiveSlides()) {
+      const slideId = nid(slide);
+      // Get background color: from fillPaints or default white
+      const bgPaints = slide.fillPaints;
+      const bgColor = extractColor(bgPaints) || { r: 1, g: 1, b: 1 };
+      const bgLum = luminance(bgColor.r, bgColor.g, bgColor.b);
+
+      // Walk all descendants looking for TEXT nodes
+      this.walkTree(slideId, (node) => {
+        if (node.type !== 'TEXT') return;
+        const textPaints = node.fillPaints;
+        const textColor = extractColor(textPaints);
+        if (!textColor) return;
+
+        const textLum = luminance(textColor.r, textColor.g, textColor.b);
+        const ratio = contrastRatio(bgLum, textLum);
+
+        if (ratio < 2) {
+          const nodeId = nid(node);
+          let msg = `TEXT ${nodeId} "${node.name || ''}": contrast ratio ${ratio.toFixed(2)}:1 against slide background is below 2:1`;
+          if (node.colorVar) {
+            msg += ` (uses colorVar "${node.colorVar}" — may resolve differently in Figma)`;
+          }
+          warnings.push(msg);
+        }
+      });
+    }
+
     for (const w of warnings) console.warn(`⚠️  ${w}`);
     return warnings;
   }

package/lib/rasterizer/svg-builder.mjs

@@ -1102,6 +1102,22 @@ function renderInstance(deck, node) {
   const symbol = deck.getNode(symNid);
   if (!symbol) return renderPlaceholder(deck, node);
 
+  // Figma-parity: reject instances of symbols with invalid variant specs.
+  // Figma Desktop silently shows blank slides for these. We match that behavior
+  // deliberately so our preview catches invalid decks instead of hiding them.
+  // Root cause: older tooling created SYMBOL variants with names (e.g.
+  // "Size=Wide") that don't exist in the component set's variantPropSpecs.
+  if (symbol.componentKey && symbol.variantPropSpecs) {
+    const specValues = new Set(symbol.variantPropSpecs.map(s => s.value));
+    const nameValues = (symbol.name || '').split(', ').map(p => p.split('=')[1]).filter(Boolean);
+    const invalid = nameValues.some(v => !specValues.has(v));
+    if (invalid) {
+      const nid = `${node.guid.sessionID}:${node.guid.localID}`;
+      console.warn(`⚠️  Skipping INSTANCE ${nid}: symbol ${symNid} "${symbol.name}" has invalid variant specs — Figma would show blank`);
+      return renderPlaceholder(deck, node);
+    }
+  }
+
   // Temporarily apply symbolOverrides so rendered content reflects overrides.
   // Override guidPaths may reference library-original IDs (e.g. 100:656) rather
   // than local node IDs (e.g. 1:1131). Nodes expose their library ID via the

package/lib/slides/api.mjs

@@ -169,6 +169,11 @@ export class Deck {
     // Auto-remove the original template blank slide on first addBlankSlide() call
     if (this._templateSlide) {
       this._templateSlide.phase = 'REMOVED';
+      // Also remove children (e.g. FRAME nodes) of the template slide
+      const templateChildren = fd.getChildren(nid(this._templateSlide));
+      for (const child of templateChildren) {
+        child.phase = 'REMOVED';
+      }
       this._templateSlide = null;
       fd.rebuildMaps();
     }
@@ -204,7 +209,6 @@ export class Deck {
     if (!templateSlide) throw new Error('No slides to clone structure from');
 
     const templateInst = fd.getSlideInstance(nid(templateSlide));
-    if (!templateInst) throw new Error('Template slide has no instance');
 
     const slideRowId = templateSlide.parentIndex?.guid
       ? `${templateSlide.parentIndex.guid.sessionID}:${templateSlide.parentIndex.guid.localID}`
@@ -242,20 +246,42 @@ export class Deck {
       newSlide.transform.m02 = activeCount * 2160;
     }
 
-    // Clone INSTANCE node, pointing at the given symbol
-    const newInst = deepClone(templateInst);
-    newInst.guid = { sessionID: 1, localID: instLocalId };
-    newInst.name = newSlide.name;
-    newInst.phase = 'CREATED';
-    newInst.parentIndex = { guid: { sessionID: 1, localID: slideLocalId }, position: '!' };
-    newInst.symbolData = {
-      symbolID: deepClone(symbol._node.guid),
-      symbolOverrides: [],
-      uniformScaleFactor: 1,
-    };
-    delete newInst.derivedSymbolData;
-    delete newInst.derivedSymbolDataLayoutVersion;
-    delete newInst.editInfo;
+    // Build the INSTANCE node — clone from existing INSTANCE or construct from
+    // scratch when the template SLIDE has a FRAME child instead (e.g. blank-template.deck).
+    let newInst;
+    if (templateInst) {
+      newInst = deepClone(templateInst);
+      newInst.guid = { sessionID: 1, localID: instLocalId };
+      newInst.name = newSlide.name;
+      newInst.phase = 'CREATED';
+      newInst.parentIndex = { guid: { sessionID: 1, localID: slideLocalId }, position: '!' };
+      newInst.symbolData = {
+        symbolID: deepClone(symbol._node.guid),
+        symbolOverrides: [],
+        uniformScaleFactor: 1,
+      };
+      delete newInst.derivedSymbolData;
+      delete newInst.derivedSymbolDataLayoutVersion;
+      delete newInst.editInfo;
+    } else {
+      // No INSTANCE to clone (FRAME-based template) — build a bare INSTANCE node
+      newInst = {
+        guid: { sessionID: 1, localID: instLocalId },
+        phase: 'CREATED',
+        parentIndex: { guid: { sessionID: 1, localID: slideLocalId }, position: '!' },
+        type: 'INSTANCE',
+        name: newSlide.name,
+        visible: true,
+        opacity: 1,
+        size: deepClone(templateSlide.size ?? { x: 1920, y: 1080 }),
+        transform: { m00: 1, m01: 0, m02: 0, m10: 0, m11: 1, m12: 0 },
+        symbolData: {
+          symbolID: deepClone(symbol._node.guid),
+          symbolOverrides: [],
+          uniformScaleFactor: 1,
+        },
+      };
+    }
 
     fd.message.nodeChanges.push(newSlide);
     fd.message.nodeChanges.push(newInst);

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": "0.2",
   "name": "openfig",
-  "version": "0.3.20",
+  "version": "0.3.22",
   "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.20",
+  "version": "0.3.22",
   "description": "OpenFig — Open-source tools for Figma file parsing and rendering",
   "type": "module",
   "bin": {