figmatk 0.3.7 → 0.3.8

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.8",
       "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';
@@ -511,6 +507,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 +580,11 @@ const RENDERERS = {
   GROUP:             renderGroup,
   SECTION:           renderGroup,
   BOOLEAN_OPERATION: renderGroup,
-  // Stubs — add full implementations over time:
   VECTOR:            renderPlaceholder,
   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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figmatk",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "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.8"
 ---
 
 # 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.8"
 ---
 
 # Figma Template Builder