figmatk 0.0.6

package/lib/deep-clone.mjs

@@ -0,0 +1,16 @@
+/**
+ * Uint8Array-safe deep clone.
+ * JSON.parse(JSON.stringify()) corrupts Uint8Array → plain objects.
+ */
+export function deepClone(obj) {
+  if (obj === null || typeof obj !== 'object') return obj;
+  if (obj instanceof Uint8Array) return obj.slice();
+  if (obj instanceof ArrayBuffer) return obj.slice(0);
+  if (obj instanceof Date) return new Date(obj);
+  if (Array.isArray(obj)) return obj.map(deepClone);
+  const out = {};
+  for (const key of Object.keys(obj)) {
+    out[key] = deepClone(obj[key]);
+  }
+  return out;
+}

package/lib/fig-deck.mjs

@@ -0,0 +1,307 @@
+/**
+ * FigDeck — Core class for reading, modifying, and writing Figma .deck/.fig files.
+ *
+ * FORMAT RULES (hard-won):
+ * - .deck = ZIP containing canvas.fig, thumbnail.png, meta.json, images/
+ * - canvas.fig = prelude ("fig-deck" or "fig-kiwi") + version (uint32 LE)
+ *   + length-prefixed chunks
+ * - Chunk 0 = kiwi schema (deflateRaw compressed)
+ * - Chunk 1 = message data (MUST be zstd compressed — Figma rejects deflateRaw)
+ * - Chunk 2+ = optional additional data (pass through as-is)
+ */
+import { decodeBinarySchema, compileSchema, encodeBinarySchema } from 'kiwi-schema';
+import { decompress } from 'fzstd';
+import { inflateRaw, deflateRaw } from 'pako';
+import { ZstdCodec } from 'zstd-codec';
+import archiver from 'archiver';
+import { readFileSync, createWriteStream, existsSync, mkdirSync, cpSync } from 'fs';
+import { execSync } from 'child_process';
+import { join, resolve } from 'path';
+import { nid } from './node-helpers.mjs';
+
+export class FigDeck {
+  constructor() {
+    this.header = null;       // { prelude, version }
+    this.schema = null;       // decoded kiwi binary schema
+    this.compiledSchema = null;
+    this.message = null;      // decoded message { nodeChanges, blobs, ... }
+    this.rawFiles = [];       // original compressed chunks (for passthrough)
+    this.nodeMap = new Map();  // "s:l" → node
+    this.childrenMap = new Map(); // "s:l" → [child nodes]
+    this.deckMeta = null;     // parsed meta.json (when loaded from .deck)
+    this.deckThumbnail = null; // raw thumbnail PNG bytes
+    this.imagesDir = null;    // path to extracted images directory
+    this._tempDir = null;     // temp dir for deck extraction
+  }
+
+  /**
+   * Load from a .deck file (ZIP archive).
+   */
+  static async fromDeckFile(deckPath) {
+    const deck = new FigDeck();
+    const absPath = resolve(deckPath);
+
+    // Extract to temp dir
+    const tmp = `/tmp/figmatk_${Date.now()}`;
+    execSync(`rm -rf ${tmp} && mkdir -p ${tmp}`);
+    execSync(`unzip -o "${absPath}" -d ${tmp}`, { stdio: 'pipe' });
+    deck._tempDir = tmp;
+
+    // Read canvas.fig
+    const figPath = join(tmp, 'canvas.fig');
+    if (!existsSync(figPath)) {
+      throw new Error('No canvas.fig found in deck archive');
+    }
+    deck._parseFig(readFileSync(figPath));
+
+    // Read meta.json
+    const metaPath = join(tmp, 'meta.json');
+    if (existsSync(metaPath)) {
+      deck.deckMeta = JSON.parse(readFileSync(metaPath, 'utf8'));
+    }
+
+    // Read thumbnail
+    const thumbPath = join(tmp, 'thumbnail.png');
+    if (existsSync(thumbPath)) {
+      deck.deckThumbnail = readFileSync(thumbPath);
+    }
+
+    // Record images dir
+    const imgDir = join(tmp, 'images');
+    if (existsSync(imgDir)) {
+      deck.imagesDir = imgDir;
+    }
+
+    return deck;
+  }
+
+  /**
+   * Load from a raw .fig file.
+   */
+  static fromFigFile(figPath) {
+    const deck = new FigDeck();
+    deck._parseFig(readFileSync(resolve(figPath)));
+    return deck;
+  }
+
+  /**
+   * Parse a canvas.fig buffer.
+   * Format: prelude (8 bytes ASCII) + version (uint32 LE) + N×(length uint32 LE + chunk bytes)
+   * Known preludes: "fig-kiwi", "fig-deck", "fig-jam."
+   */
+  _parseFig(buf) {
+    const data = new Uint8Array(buf.buffer ?? buf);
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+
+    // Read 8-byte prelude
+    const prelude = String.fromCharCode(...data.subarray(0, 8));
+    const version = view.getUint32(8, true);
+    this.header = { prelude, version };
+
+    // Read length-prefixed chunks
+    const files = [];
+    let off = 12;
+    while (off < data.byteLength) {
+      const len = view.getUint32(off, true);
+      off += 4;
+      files.push(data.subarray(off, off + len));
+      off += len;
+    }
+    this.rawFiles = files;
+
+    // Chunk 0: schema (always deflateRaw)
+    const schemaData = inflateRaw(files[0]);
+    this.schema = decodeBinarySchema(schemaData);
+    this.compiledSchema = compileSchema(this.schema);
+
+    // Chunk 1: message (zstd or deflateRaw — auto-detect)
+    let msgData;
+    if (files[1][0] === 0x28 && files[1][1] === 0xb5 &&
+        files[1][2] === 0x2f && files[1][3] === 0xfd) {
+      msgData = decompress(files[1]); // zstd
+    } else {
+      msgData = inflateRaw(files[1]); // deflateRaw fallback
+    }
+    this.message = this.compiledSchema.decodeMessage(msgData);
+
+    this.rebuildMaps();
+  }
+
+  /**
+   * Rebuild nodeMap and childrenMap from message.nodeChanges.
+   */
+  rebuildMaps() {
+    this.nodeMap.clear();
+    this.childrenMap.clear();
+
+    for (const node of this.message.nodeChanges) {
+      const id = nid(node);
+      if (id) this.nodeMap.set(id, node);
+    }
+
+    for (const node of this.message.nodeChanges) {
+      if (!node.parentIndex?.guid) continue;
+      const pid = `${node.parentIndex.guid.sessionID}:${node.parentIndex.guid.localID}`;
+      if (!this.childrenMap.has(pid)) this.childrenMap.set(pid, []);
+      this.childrenMap.get(pid).push(node);
+    }
+  }
+
+  /** Get node by string ID "s:l" */
+  getNode(id) {
+    return this.nodeMap.get(id);
+  }
+
+  /** Get children of a node by string ID */
+  getChildren(id) {
+    return this.childrenMap.get(id) || [];
+  }
+
+  /** Get all SLIDE nodes */
+  getSlides() {
+    return this.message.nodeChanges.filter(n => n.type === 'SLIDE');
+  }
+
+  /** Get only active (non-REMOVED) slides */
+  getActiveSlides() {
+    return this.getSlides().filter(n => n.phase !== 'REMOVED');
+  }
+
+  /** Get all INSTANCE nodes */
+  getInstances() {
+    return this.message.nodeChanges.filter(n => n.type === 'INSTANCE');
+  }
+
+  /** Get all SYMBOL nodes */
+  getSymbols() {
+    return this.message.nodeChanges.filter(n => n.type === 'SYMBOL');
+  }
+
+  /** Find the INSTANCE child of a SLIDE */
+  getSlideInstance(slideId) {
+    const children = this.getChildren(slideId);
+    return children.find(c => c.type === 'INSTANCE');
+  }
+
+  /** Highest localID in use (for generating new IDs) */
+  maxLocalID() {
+    let max = 0;
+    for (const node of this.message.nodeChanges) {
+      if (node.guid?.localID > max) max = node.guid.localID;
+    }
+    return max;
+  }
+
+  /**
+   * DFS walk from a root node.
+   * @param {string} rootId - "s:l" format
+   * @param {Function} visitor - (node, depth) => void
+   */
+  walkTree(rootId, visitor, depth = 0) {
+    const node = this.getNode(rootId);
+    if (!node) return;
+    visitor(node, depth);
+    for (const child of this.getChildren(rootId)) {
+      this.walkTree(nid(child), visitor, depth + 1);
+    }
+  }
+
+  /**
+   * Encode message to canvas.fig binary.
+   * Returns a Promise<Uint8Array> because zstd-codec uses callbacks.
+   */
+  encodeFig() {
+    return new Promise((resolve, reject) => {
+      ZstdCodec.run(zstd => {
+        try {
+          const z = new zstd.Simple();
+
+          const encodedMsg = this.compiledSchema.encodeMessage(this.message);
+          const compSchema = deflateRaw(encodeBinarySchema(this.schema));
+          const compMsg = z.compress(encodedMsg, 3);
+
+          const prelude = this.header.prelude;
+          const chunks = [compSchema, compMsg];
+          // Pass through any additional chunks (chunk 2+)
+          for (let i = 2; i < this.rawFiles.length; i++) {
+            chunks.push(this.rawFiles[i]);
+          }
+
+          const headerSize = prelude.length + 4;
+          const totalSize = chunks.reduce((sz, c) => sz + 4 + c.byteLength, headerSize);
+          const buf = new Uint8Array(totalSize);
+          const view = new DataView(buf.buffer);
+          const enc = new TextEncoder();
+
+          let off = 0;
+          off = enc.encodeInto(prelude, buf).written;
+          view.setUint32(off, this.header.version, true);
+          off += 4;
+
+          for (const chunk of chunks) {
+            view.setUint32(off, chunk.byteLength, true);
+            off += 4;
+            buf.set(chunk, off);
+            off += chunk.byteLength;
+          }
+
+          resolve(buf);
+        } catch (e) {
+          reject(e);
+        }
+      });
+    });
+  }
+
+  /**
+   * Save as a .deck (ZIP archive).
+   * @param {string} outPath - Output file path
+   * @param {object} opts - { imagesDir, thumbnail, meta }
+   */
+  async saveDeck(outPath, opts = {}) {
+    const figBuf = await this.encodeFig();
+    const absOut = resolve(outPath);
+
+    return new Promise((resolveP, reject) => {
+      const output = createWriteStream(absOut);
+      const archive = archiver('zip', { store: true });
+
+      archive.on('error', reject);
+      output.on('close', () => resolveP(archive.pointer()));
+
+      archive.pipe(output);
+
+      // canvas.fig
+      archive.append(Buffer.from(figBuf), { name: 'canvas.fig' });
+
+      // thumbnail.png
+      const thumb = opts.thumbnail || this.deckThumbnail;
+      if (thumb) {
+        archive.append(Buffer.from(thumb), { name: 'thumbnail.png' });
+      }
+
+      // meta.json
+      const meta = opts.meta || this.deckMeta;
+      if (meta) {
+        archive.append(JSON.stringify(meta), { name: 'meta.json' });
+      }
+
+      // images/
+      const imgDir = opts.imagesDir || this.imagesDir;
+      if (imgDir && existsSync(imgDir)) {
+        archive.directory(imgDir, 'images');
+      }
+
+      archive.finalize();
+    });
+  }
+
+  /**
+   * Save just the canvas.fig binary.
+   */
+  async saveFig(outPath) {
+    const buf = await this.encodeFig();
+    const { writeFileSync } = await import('fs');
+    writeFileSync(resolve(outPath), buf);
+  }
+}

package/lib/image-helpers.mjs

@@ -0,0 +1,56 @@
+/**
+ * Image override utilities for Figma .deck files.
+ *
+ * CRITICAL RULES:
+ * - styleIdForFill with sentinel GUID (all 0xFFFFFFFF) is REQUIRED
+ * - imageThumbnail with real thumbnail hash (~320px PNG) is REQUIRED
+ * - thumbHash must be new Uint8Array(0), NOT {}
+ */
+
+/** Convert 40-char hex SHA-1 string to Uint8Array(20). */
+export function hexToHash(hex) {
+  const arr = new Uint8Array(20);
+  for (let i = 0; i < 20; i++) {
+    arr[i] = parseInt(hex.substring(i * 2, i * 2 + 2), 16);
+  }
+  return arr;
+}
+
+/** Convert Uint8Array(20) hash back to 40-char hex string. */
+export function hashToHex(arr) {
+  return Array.from(arr).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Build a complete image fill override for symbolOverrides.
+ *
+ * @param {object} key - Override key { sessionID, localID }
+ * @param {string} hash - 40-char hex SHA-1 of the full image
+ * @param {string} thumbHash - 40-char hex SHA-1 of the thumbnail image
+ * @param {number} width - Original image width
+ * @param {number} height - Original image height
+ */
+export function imageOv(key, hash, thumbHash, width, height) {
+  return {
+    styleIdForFill: { guid: { sessionID: 4294967295, localID: 4294967295 } },
+    guidPath: { guids: [key] },
+    fillPaints: [{
+      type: 'IMAGE',
+      opacity: 1,
+      visible: true,
+      blendMode: 'NORMAL',
+      transform: { m00: 1, m01: 0, m02: 0, m10: 0, m11: 1, m12: 0 },
+      image: { hash: hexToHash(hash), name: hash },
+      imageThumbnail: { hash: hexToHash(thumbHash), name: hash },
+      animationFrame: 0,
+      imageScaleMode: 'FILL',
+      imageShouldColorManage: false,
+      rotation: 0,
+      scale: 0.5,
+      originalImageWidth: width,
+      originalImageHeight: height,
+      thumbHash: new Uint8Array(0),
+      altText: '',
+    }],
+  };
+}

package/lib/image-utils.mjs

@@ -0,0 +1,29 @@
+/**
+ * Cross-platform image utilities using sharp.
+ * Replaces macOS-only sips calls.
+ */
+import sharp from 'sharp';
+import { writeFileSync } from 'fs';
+
+/**
+ * Get pixel dimensions of an image.
+ * @param {string|Buffer} input - file path or buffer
+ * @returns {Promise<{width: number, height: number}>}
+ */
+export async function getImageDimensions(input) {
+  const meta = await sharp(input).metadata();
+  return { width: meta.width ?? 0, height: meta.height ?? 0 };
+}
+
+/**
+ * Generate a thumbnail (~320px wide) and write to a temp file.
+ * @param {string|Buffer} input - file path or buffer
+ * @param {string} outPath - destination file path
+ * @returns {Promise<void>}
+ */
+export async function generateThumbnail(input, outPath) {
+  await sharp(input)
+    .resize(320, null, { withoutEnlargement: true })
+    .png()
+    .toFile(outPath);
+}

package/lib/node-helpers.mjs

@@ -0,0 +1,49 @@
+/**
+ * Node ID formatting, tree walking, override builders.
+ */
+
+/** Format a node's guid as "sessionID:localID" */
+export function nid(node) {
+  if (!node?.guid) return null;
+  return `${node.guid.sessionID}:${node.guid.localID}`;
+}
+
+/** Parse "57:48" → { sessionID: 57, localID: 48 } */
+export function parseId(str) {
+  const [s, l] = str.split(':').map(Number);
+  return { sessionID: s, localID: l };
+}
+
+/** Shorthand for { sessionID, localID } */
+export function makeGuid(sessionID, localID) {
+  return { sessionID, localID };
+}
+
+/**
+ * Build a text override for symbolOverrides.
+ * Empty string is replaced with ' ' (space) — empty crashes Figma.
+ */
+export function ov(key, text) {
+  const chars = (text === '' || text == null) ? ' ' : text;
+  return { guidPath: { guids: [key] }, textData: { characters: chars } };
+}
+
+/**
+ * Build a nested text override (e.g., quote inside paraGrid).
+ * guidPath has 2 guids: [instanceKey, textKey].
+ */
+export function nestedOv(instKey, textKey, text) {
+  const chars = (text === '' || text == null) ? ' ' : text;
+  return { guidPath: { guids: [instKey, textKey] }, textData: { characters: chars } };
+}
+
+/** Mark a node as REMOVED (never delete from nodeChanges array). */
+export function removeNode(node) {
+  node.phase = 'REMOVED';
+  delete node.prototypeInteractions;
+}
+
+/** Position character for sibling ordering in parentIndex. */
+export function positionChar(index) {
+  return String.fromCharCode(0x21 + index); // '!' = 0, '"' = 1, etc.
+}