figmatk 0.3.7 → 0.3.9

package/.claude-plugin/marketplace.json

@@ -13,7 +13,7 @@
     {
       "name": "figmatk",
       "description": "Swiss Army Knife for Figma Files (.deck)",
-      "version": "0.3.3",
+      "version": "0.3.9",
       "author": {
         "name": "FigmaTK Contributors"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "figmatk",
-  "version": "0.3.3",
+  "version": "0.3.9",
   "description": "Create and edit Figma Slides .deck files programmatically — no Figma API required",
   "author": {
     "name": "FigmaTK Contributors"

package/lib/rasterizer/svg-builder.mjs

@@ -4,10 +4,6 @@
  * Architecture: dispatcher pattern — each Figma node type maps to a render
  * function. Unknown types emit a magenta placeholder rect so renders never
  * crash. Add handlers incrementally as coverage grows.
- *
- * TODO: Symbol instance resolution (INSTANCE → SYMBOL + apply overrides).
- * Until that is implemented, INSTANCE nodes render as placeholders.
- * For slides that use direct nodes (not template instances), this works fully.
  */
 
 import { readFileSync } from 'fs';
@@ -504,6 +500,100 @@ function renderLine(deck, node) {
   return `<line x1="${x1}" y1="${y1}" x2="${x2}" y2="${y2}" stroke="${stroke}" stroke-width="${sw}"/>`;
 }
 
+/**
+ * VECTOR — decode fillGeometry/strokeGeometry commandsBlob binary to SVG paths.
+ *
+ * Blob format: [cmdByte][float32LE params...]
+ *   0x01 = moveTo (x, y)
+ *   0x02 = lineTo (x, y)
+ *   0x04 = cubicTo (c1x, c1y, c2x, c2y, x, y)
+ *   0x00 = close
+ *
+ * Coordinates are in node-size space. The full affine transform matrix is used
+ * to position, scale, and rotate the vector in the slide.
+ */
+function renderVector(deck, node) {
+  const t = node.transform ?? {};
+  const m00 = t.m00 ?? 1, m01 = t.m01 ?? 0, m02 = t.m02 ?? 0;
+  const m10 = t.m10 ?? 0, m11 = t.m11 ?? 1, m12 = t.m12 ?? 0;
+  const blobs = deck.message?.blobs;
+  const parts = [];
+
+  // Fill paths
+  const fillColor = resolveFill(getFillPaints(node));
+  if (fillColor && node.fillGeometry?.length && blobs) {
+    for (const geo of node.fillGeometry) {
+      const d = decodeCmdBlob(blobs, geo.commandsBlob);
+      if (!d) continue;
+      const rule = geo.windingRule === 'EVENODD' ? ' fill-rule="evenodd"' : '';
+      parts.push(`<path d="${d}" fill="${fillColor}"${rule}/>`);
+    }
+  }
+
+  // Stroke paths
+  const strokeColor = resolveFill(node.strokePaints);
+  const sw = node.strokeWeight ?? 0;
+  if (strokeColor && sw > 0 && node.strokeGeometry?.length && blobs) {
+    for (const geo of node.strokeGeometry) {
+      const d = decodeCmdBlob(blobs, geo.commandsBlob);
+      if (!d) continue;
+      // strokeGeometry encodes the stroke outline as a fill shape
+      const rule = geo.windingRule === 'EVENODD' ? ' fill-rule="evenodd"' : '';
+      parts.push(`<path d="${d}" fill="${strokeColor}"${rule}/>`);
+    }
+  }
+
+  if (!parts.length) return renderPlaceholder(deck, node);
+  return `<g transform="matrix(${m00},${m10},${m01},${m11},${m02},${m12})">\n${parts.join('\n')}\n</g>`;
+}
+
+/** Decode a commandsBlob index into an SVG path d-string. */
+function decodeCmdBlob(blobs, blobIdx) {
+  if (blobIdx == null || !blobs?.[blobIdx]) return null;
+  const raw = blobs[blobIdx].bytes ?? blobs[blobIdx];
+  if (!raw) return null;
+
+  // Convert indexed object to Buffer if needed
+  let buf;
+  if (Buffer.isBuffer(raw) || raw instanceof Uint8Array) {
+    buf = Buffer.from(raw);
+  } else {
+    const len = Object.keys(raw).length;
+    buf = Buffer.alloc(len);
+    for (let i = 0; i < len; i++) buf[i] = raw[i];
+  }
+
+  const cmds = [];
+  let off = 0;
+  while (off < buf.length) {
+    const cmd = buf[off++];
+    if (cmd === 0x01) { // moveTo
+      const x = buf.readFloatLE(off); off += 4;
+      const y = buf.readFloatLE(off); off += 4;
+      cmds.push(`M${f(x)},${f(y)}`);
+    } else if (cmd === 0x02) { // lineTo
+      const x = buf.readFloatLE(off); off += 4;
+      const y = buf.readFloatLE(off); off += 4;
+      cmds.push(`L${f(x)},${f(y)}`);
+    } else if (cmd === 0x04) { // cubicTo
+      const c1x = buf.readFloatLE(off); off += 4;
+      const c1y = buf.readFloatLE(off); off += 4;
+      const c2x = buf.readFloatLE(off); off += 4;
+      const c2y = buf.readFloatLE(off); off += 4;
+      const x = buf.readFloatLE(off); off += 4;
+      const y = buf.readFloatLE(off); off += 4;
+      cmds.push(`C${f(c1x)},${f(c1y)} ${f(c2x)},${f(c2y)} ${f(x)},${f(y)}`);
+    } else if (cmd === 0x00) { // close
+      cmds.push('Z');
+    } else {
+      break; // unknown command — stop
+    }
+  }
+  return cmds.length ? cmds.join('') : null;
+}
+
+function f(v) { return +v.toFixed(2); }
+
 function renderPlaceholder(deck, node) {
   const { x, y } = pos(node);
   const { w, h } = size(node);
@@ -511,6 +601,67 @@ function renderPlaceholder(deck, node) {
   return `<rect x="${x}" y="${y}" width="${w || 40}" height="${h || 40}" fill="none" stroke="#ff00ff" stroke-width="2" stroke-dasharray="6" opacity="0.5"/><!-- ${type} -->`;
 }
 
+/**
+ * INSTANCE → SYMBOL resolution.
+ *
+ * Figma templates use INSTANCE nodes that reference a SYMBOL definition.
+ * The SYMBOL's children (TEXT, shapes, frames, etc.) define the visual content.
+ * The INSTANCE may carry symbolOverrides that modify specific child properties
+ * (text content, fills, etc.).
+ *
+ * Strategy:
+ * - Resolve the SYMBOL via symbolData.symbolID
+ * - Render the SYMBOL's children tree (they live in the normal node hierarchy)
+ * - Apply symbolOverrides: text and fill overrides are temporarily applied
+ *   to the target nodes, rendered, then restored.
+ */
+function renderInstance(deck, node) {
+  const { x, y } = pos(node);
+  const symbolId = node.symbolData?.symbolID;
+  if (!symbolId) return renderPlaceholder(deck, node);
+
+  const symNid = `${symbolId.sessionID}:${symbolId.localID}`;
+  const symbol = deck.getNode(symNid);
+  if (!symbol) return renderPlaceholder(deck, node);
+
+  // Temporarily apply symbolOverrides so rendered content reflects overrides.
+  // Only single-level guidPath overrides are handled (covers the common case).
+  const overrides = node.symbolData?.symbolOverrides ?? [];
+  const restores = [];
+
+  for (const ov of overrides) {
+    const guids = ov.guidPath?.guids;
+    if (!guids?.length || guids.length !== 1) continue;
+    const targetId = `${guids[0].sessionID}:${guids[0].localID}`;
+    const target = deck.getNode(targetId);
+    if (!target) continue;
+
+    // Text override — replace characters but keep derived glyph layout.
+    // The glyph positions come from the original text, so this is approximate
+    // when character count differs, but visually far better than a placeholder.
+    if (ov.textData?.characters != null && target.textData) {
+      const origChars = target.textData.characters;
+      restores.push(() => { target.textData.characters = origChars; });
+      target.textData.characters = ov.textData.characters;
+    }
+
+    // Fill override (image swaps, color changes)
+    if (ov.fillPaints) {
+      const origFill = target.fillPaints;
+      restores.push(() => { target.fillPaints = origFill; });
+      target.fillPaints = ov.fillPaints;
+    }
+  }
+
+  const inner = childrenSvg(deck, symbol);
+
+  // Restore mutations
+  for (const fn of restores) fn();
+
+  if (!inner) return '';
+  return `<g transform="translate(${x},${y})">\n${inner}\n</g>`;
+}
+
 // ── Dispatcher ────────────────────────────────────────────────────────────────
 
 const RENDERERS = {
@@ -523,13 +674,11 @@ const RENDERERS = {
   GROUP:             renderGroup,
   SECTION:           renderGroup,
   BOOLEAN_OPERATION: renderGroup,
-  // Stubs — add full implementations over time:
-  VECTOR:            renderPlaceholder,
+  VECTOR:            renderVector,
   LINE:              renderLine,
   STAR:              renderPlaceholder,
   POLYGON:           renderPlaceholder,
-  // TODO: INSTANCE → resolve symbol + apply overrides, then recurse
-  INSTANCE:          renderPlaceholder,
+  INSTANCE:          renderInstance,
 };
 
 function renderNode(deck, node) {

package/lib/template-deck.mjs

@@ -298,13 +298,41 @@ function describeLayout(deck, layout, row) {
   };
 }
 
+/**
+ * Walk the node tree like deck.walkTree, but follow INSTANCE → SYMBOL links.
+ * When an INSTANCE node is encountered, its referenced SYMBOL's children are
+ * also walked so that slots inside published template components are discovered.
+ */
+function walkTreeThroughInstances(deck, rootId, visitor, depth = 0, visited = new Set()) {
+  if (!rootId || visited.has(rootId)) return;
+  visited.add(rootId);
+
+  const node = deck.getNode(rootId);
+  if (!node || node.phase === 'REMOVED') return;
+  visitor(node, depth);
+
+  // Follow INSTANCE → SYMBOL: walk the SYMBOL's children
+  if (node.type === 'INSTANCE' && node.symbolData?.symbolID) {
+    const sid = node.symbolData.symbolID;
+    const symNid = `${sid.sessionID}:${sid.localID}`;
+    for (const child of deck.getChildren(symNid)) {
+      walkTreeThroughInstances(deck, nid(child), visitor, depth + 1, visited);
+    }
+  }
+
+  // Walk direct children
+  for (const child of deck.getChildren(rootId)) {
+    walkTreeThroughInstances(deck, nid(child), visitor, depth + 1, visited);
+  }
+}
+
 function discoverSlots(deck, rootId) {
   const explicitTextSlots = [];
   const explicitImageSlots = [];
   const fallbackTextSlots = [];
   const fallbackImageSlots = [];
 
-  deck.walkTree(rootId, node => {
+  walkTreeThroughInstances(deck, rootId, node => {
     const textSlotName = parsePrefixedName(node.name, TEXT_SLOT_PREFIX);
     if (textSlotName) {
       const slot = describeTextSlot(node, textSlotName, 'explicit');

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": "0.2",
   "name": "figmatk",
-  "version": "0.3.3",
+  "version": "0.3.9",
   "description": "Create and edit Figma Slides .deck files programmatically - no Figma API required",
   "author": {
     "name": "FigmaTK Contributors"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figmatk",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "Figma Toolkit — Swiss-army knife CLI for Figma .deck and .fig files",
   "type": "module",
   "bin": {

package/skills/figma-slides-creator/SKILL.md

@@ -6,7 +6,7 @@ description: >
   clone or remove slides, or produce a .deck file for Figma Slides.
   Powered by FigmaTK under the hood.
 metadata:
-  version: "0.3.7"
+  version: "0.3.9"
 ---
 
 # FigmaTK Skill

package/skills/figma-template-builder/SKILL.md

@@ -6,7 +6,7 @@ description: >
   template from an existing deck, define reusable layouts, mark editable
   text/image slots, or prepare a draft template for later instantiation.
 metadata:
-  version: "0.3.7"
+  version: "0.3.9"
 ---
 
 # Figma Template Builder