openfig-cli 0.3.21 → 0.3.23

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

@@ -14,11 +14,12 @@ import { decompress } from 'fzstd';
 import { inflateRaw, deflateRaw } from 'pako';
 import { ZstdCodec } from 'zstd-codec';
 import yazl from 'yazl';
-import { readFileSync, createWriteStream, existsSync, mkdtempSync, readdirSync } from 'fs';
+import { readFileSync, createWriteStream, existsSync, mkdtempSync, readdirSync, copyFileSync, mkdirSync } from 'fs';
 import { execSync } from 'child_process';
 import { join, resolve } from 'path';
 import { tmpdir } from 'os';
 import { nid } from './node-helpers.mjs';
+import { deepClone } from './deep-clone.mjs';
 
 export class FigDeck {
   constructor() {
@@ -231,6 +232,206 @@ export class FigDeck {
     }
   }
 
+  /**
+   * Import SYMBOL nodes (and their full subtrees) from another FigDeck into this one.
+   *
+   * Handles:
+   * - Deep cloning with full GUID remapping
+   * - parentIndex.guid rebinding
+   * - symbolData.symbolID remapping for nested INSTANCE nodes
+   * - overrideKey remapping
+   * - Image/blob file copying between decks
+   * - Deduplication by componentKey
+   *
+   * @param {FigDeck} sourceDeck - The FigDeck to copy symbols from
+   * @param {string[]} symbolIds - Array of symbol node IDs in "s:l" format (e.g., ['1:500', '1:600'])
+   * @returns {Map<string, string>} Map of old ID → new ID for every remapped node
+   */
+  importSymbols(sourceDeck, symbolIds) {
+    if (!sourceDeck || !symbolIds?.length) return new Map();
+
+    // Build componentKey index for dedup in the target deck
+    const existingByKey = new Map();
+    for (const sym of this.getSymbols()) {
+      if (sym.phase === 'REMOVED' || !sym.componentKey) continue;
+      existingByKey.set(sym.componentKey, nid(sym));
+    }
+
+    // Find the Internal Only Canvas to parent imported symbols under
+    const internalCanvas = this.message.nodeChanges.find(
+      n => n.type === 'CANVAS' && n.name === 'Internal Only Canvas' && n.phase !== 'REMOVED'
+    );
+    if (!internalCanvas) {
+      throw new Error('No "Internal Only Canvas" found in target deck');
+    }
+    const canvasId = nid(internalCanvas);
+
+    let nextId = this.maxLocalID() + 1;
+    const sessionId = 1;
+    const globalIdMap = new Map(); // old "s:l" → new "s:l" across all imported symbols
+
+    for (const symId of symbolIds) {
+      const sourceSymbol = sourceDeck.getNode(symId);
+      if (!sourceSymbol || sourceSymbol.type !== 'SYMBOL') {
+        throw new Error(`SYMBOL not found in source deck: ${symId}`);
+      }
+
+      // Dedup: if target already has a symbol with the same componentKey, skip
+      if (sourceSymbol.componentKey && existingByKey.has(sourceSymbol.componentKey)) {
+        globalIdMap.set(symId, existingByKey.get(sourceSymbol.componentKey));
+        continue;
+      }
+
+      // Collect the full subtree (DFS)
+      const subtreeNodes = [];
+      sourceDeck.walkTree(symId, node => {
+        if (node.phase !== 'REMOVED') subtreeNodes.push(node);
+      });
+
+      // Build ID remap table for this subtree
+      const idMap = new Map(); // old "s:l" → new guid { sessionID, localID }
+      for (const node of subtreeNodes) {
+        idMap.set(nid(node), { sessionID: sessionId, localID: nextId++ });
+      }
+
+      // Clone and remap each node
+      const clonedNodes = subtreeNodes.map(node => {
+        const clone = deepClone(node);
+        const oldId = nid(node);
+        const newGuid = idMap.get(oldId);
+        if (newGuid) clone.guid = newGuid;
+
+        // Root symbol → parent under Internal Only Canvas
+        if (oldId === symId) {
+          clone.parentIndex = {
+            guid: deepClone(internalCanvas.guid),
+            position: String.fromCharCode(0x21 + this.getChildren(canvasId).length),
+          };
+        } else if (clone.parentIndex?.guid) {
+          // Remap parent reference
+          const parentOldId = `${clone.parentIndex.guid.sessionID}:${clone.parentIndex.guid.localID}`;
+          const remappedParent = idMap.get(parentOldId);
+          if (remappedParent) {
+            clone.parentIndex = { ...clone.parentIndex, guid: deepClone(remappedParent) };
+          }
+        }
+
+        // Remap symbolData.symbolID on INSTANCE nodes
+        if (clone.type === 'INSTANCE' && clone.symbolData?.symbolID) {
+          const sid = clone.symbolData.symbolID;
+          const symRef = `${sid.sessionID}:${sid.localID}`;
+          const remappedSym = idMap.get(symRef);
+          if (remappedSym) {
+            clone.symbolData.symbolID = deepClone(remappedSym);
+          } else if (globalIdMap.has(symRef)) {
+            // Reference to a previously imported symbol
+            const newRef = globalIdMap.get(symRef);
+            const [s, l] = newRef.split(':').map(Number);
+            clone.symbolData.symbolID = { sessionID: s, localID: l };
+          }
+        }
+
+        // Remap overrideKey
+        if (clone.overrideKey) {
+          const okOld = `${clone.overrideKey.sessionID}:${clone.overrideKey.localID}`;
+          const remappedOk = idMap.get(okOld);
+          if (remappedOk) {
+            clone.overrideKey = deepClone(remappedOk);
+          }
+        }
+
+        // Remap symbolOverrides guid paths
+        if (clone.symbolOverrides) {
+          for (const ov of clone.symbolOverrides) {
+            if (ov.guidPath?.guids) {
+              ov.guidPath.guids = ov.guidPath.guids.map(g => {
+                const gOld = `${g.sessionID}:${g.localID}`;
+                const remapped = idMap.get(gOld);
+                return remapped ? deepClone(remapped) : g;
+              });
+            }
+          }
+        }
+
+        // Remap derivedSymbolData references
+        if (clone.derivedSymbolData) {
+          for (const dsd of clone.derivedSymbolData) {
+            if (dsd.symbolID) {
+              const dsdOld = `${dsd.symbolID.sessionID}:${dsd.symbolID.localID}`;
+              const remappedDsd = idMap.get(dsdOld);
+              if (remappedDsd) {
+                dsd.symbolID = deepClone(remappedDsd);
+              }
+            }
+          }
+        }
+
+        clone.phase = 'CREATED';
+        delete clone.slideThumbnailHash;
+        delete clone.editInfo;
+        delete clone.prototypeInteractions;
+
+        return clone;
+      });
+
+      // Copy referenced images from source deck
+      if (sourceDeck.imagesDir) {
+        if (!this.imagesDir) {
+          // Create a temp images dir for the target deck
+          const tmp = this._tempDir || mkdtempSync(join(tmpdir(), 'openfig_'));
+          if (!this._tempDir) this._tempDir = tmp;
+          this.imagesDir = join(tmp, 'images');
+          mkdirSync(this.imagesDir, { recursive: true });
+        }
+
+        for (const clone of clonedNodes) {
+          // Copy IMAGE fills
+          if (clone.fillPaints) {
+            for (const paint of clone.fillPaints) {
+              if (paint.type === 'IMAGE' && paint.image?.name) {
+                this._copyImageAsset(sourceDeck.imagesDir, paint.image.name);
+              }
+              if (paint.imageThumbnail?.name) {
+                this._copyImageAsset(sourceDeck.imagesDir, paint.imageThumbnail.name);
+              }
+            }
+          }
+        }
+      }
+
+      // Add cloned nodes to target deck
+      this.message.nodeChanges.push(...clonedNodes);
+
+      // Record mappings
+      for (const [oldId, newGuid] of idMap.entries()) {
+        globalIdMap.set(oldId, `${newGuid.sessionID}:${newGuid.localID}`);
+      }
+
+      // Register componentKey for dedup of subsequent symbols in the same call
+      if (sourceSymbol.componentKey) {
+        const newSymId = `${idMap.get(symId).sessionID}:${idMap.get(symId).localID}`;
+        existingByKey.set(sourceSymbol.componentKey, newSymId);
+      }
+    }
+
+    this.rebuildMaps();
+    return globalIdMap;
+  }
+
+  /**
+   * Copy an image asset file from a source images directory to this deck's images directory.
+   * @param {string} srcImagesDir - Source images directory
+   * @param {string} fileName - Image file name (hash)
+   */
+  _copyImageAsset(srcImagesDir, fileName) {
+    if (!fileName || !this.imagesDir) return;
+    const srcPath = join(srcImagesDir, fileName);
+    const destPath = join(this.imagesDir, fileName);
+    if (existsSync(srcPath) && !existsSync(destPath)) {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+
   /**
    * Encode message to canvas.fig binary.
    * Returns a Promise<Uint8Array> because zstd-codec uses callbacks.
@@ -325,6 +526,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/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.21",
+  "version": "0.3.23",
   "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.21",
+  "version": "0.3.23",
   "description": "OpenFig — Open-source tools for Figma file parsing and rendering",
   "type": "module",
   "bin": {