openfig-cli 0.3.22 → 0.3.24

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,242 @@ 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);
+              }
+            }
+          }
+        }
+
+        // Remap blob indices (commandsBlob, vectorNetworkBlob, fillGeometry etc.)
+        // Blobs in source deck reference positions in sourceDeck.message.blobs.
+        // Copy each referenced blob to target and update the index.
+        const remapBlobIndex = (idx) => {
+          if (idx == null || idx < 0) return idx;
+          if (!sourceDeck.message.blobs || idx >= sourceDeck.message.blobs.length) return idx;
+          if (!this._blobRemap) this._blobRemap = new Map();
+          if (this._blobRemap.has(idx)) return this._blobRemap.get(idx);
+          const blob = sourceDeck.message.blobs[idx];
+          if (!this.message.blobs) this.message.blobs = [];
+          const newIdx = this.message.blobs.length;
+          this.message.blobs.push(deepClone(blob));
+          this._blobRemap.set(idx, newIdx);
+          return newIdx;
+        };
+
+        // fillGeometry[].commandsBlob
+        if (clone.fillGeometry) {
+          for (const fg of clone.fillGeometry) {
+            if (fg.commandsBlob != null) fg.commandsBlob = remapBlobIndex(fg.commandsBlob);
+          }
+        }
+        // strokeGeometry[].commandsBlob
+        if (clone.strokeGeometry) {
+          for (const sg of clone.strokeGeometry) {
+            if (sg.commandsBlob != null) sg.commandsBlob = remapBlobIndex(sg.commandsBlob);
+          }
+        }
+        // vectorNetworkBlob (VECTOR nodes)
+        if (clone.vectorNetworkBlob != null) {
+          clone.vectorNetworkBlob = remapBlobIndex(clone.vectorNetworkBlob);
+        }
+
+        clone.phase = 'CREATED';
+        delete clone.slideThumbnailHash;
+        delete clone.editInfo;
+        delete clone.prototypeInteractions;
+
+        return clone;
+      });
+
+      // Clear blob remap cache after processing this symbol's subtree
+      delete this._blobRemap;
+
+      // 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.
@@ -354,25 +591,36 @@ export class FigDeck {
       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)`;
+      // Walk all descendants looking for TEXT nodes — follow INSTANCE → SYMBOL
+      // links so we reach TEXT inside components (walkTree alone stops at INSTANCE).
+      const walkIntoSymbols = (rootId, visited = new Set()) => {
+        this.walkTree(rootId, (node) => {
+          if (node.type === 'TEXT') {
+            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);
+            }
           }
-          warnings.push(msg);
-        }
-      });
+          if (node.type === 'INSTANCE' && node.symbolData?.symbolID) {
+            const sid = node.symbolData.symbolID;
+            const symNid = `${sid.sessionID}:${sid.localID}`;
+            if (!visited.has(symNid)) {
+              visited.add(symNid);
+              walkIntoSymbols(symNid, visited);
+            }
+          }
+        });
+      };
+      walkIntoSymbols(slideId);
     }
 
     for (const w of warnings) console.warn(`⚠️  ${w}`);

package/manifest.json

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