figmatk 0.3.0 → 0.3.1

package/mcp-server.mjs

@@ -7,9 +7,15 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { FigDeck } from './lib/fig-deck.mjs';
 import { Deck } from './lib/api.mjs';
-import { listTemplateLayouts, createFromTemplate } from './lib/template-deck.mjs';
-import { nid, ov, nestedOv, removeNode, parseId, positionChar } from './lib/node-helpers.mjs';
-import { imageOv, hexToHash, hashToHex } from './lib/image-helpers.mjs';
+import {
+  annotateTemplateLayout,
+  createDraftTemplate,
+  createFromTemplate,
+  listTemplateLayouts,
+  publishTemplateDraft,
+} from './lib/template-deck.mjs';
+import { nid, ov, removeNode } from './lib/node-helpers.mjs';
+import { imageOv, hashToHex } from './lib/image-helpers.mjs';
 import { deepClone } from './lib/deep-clone.mjs';
 
 const server = new McpServer({
@@ -46,7 +52,7 @@ server.tool(
 // ── list-text ───────────────────────────────────────────────────────────
 server.tool(
   'figmatk_list_text',
-  'List all text and image content per slide in a .deck file',
+  'List visible text and image content per slide in a .deck file, including direct slide nodes and instance overrides.',
   { path: z.string().describe('Path to .deck or .fig file') },
   async ({ path }) => {
     const deck = await FigDeck.fromDeckFile(path);
@@ -56,18 +62,41 @@ server.tool(
       if (slide.phase === 'REMOVED') continue;
       const id = nid(slide);
       lines.push(`\n── Slide ${id} "${slide.name || ''}" ──`);
+
+      const directLines = [];
+      deck.walkTree(id, (node, depth) => {
+        if (depth === 0 || node.phase === 'REMOVED') return;
+        if (node.type === 'TEXT' && node.textData?.characters) {
+          directLines.push(`  [text-node] ${nid(node)} "${node.name || ''}": ${node.textData.characters.substring(0, 120)}`);
+        }
+        if (node.type === 'SHAPE_WITH_TEXT' && node.nodeGenerationData?.overrides) {
+          for (const override of node.nodeGenerationData.overrides) {
+            if (override.textData?.characters) {
+              directLines.push(`  [shape-text] ${nid(node)} "${node.name || ''}": ${override.textData.characters.substring(0, 120)}`);
+              break;
+            }
+          }
+        }
+        const imageFill = node.fillPaints?.find(p => p.type === 'IMAGE' && p.image?.hash);
+        if (imageFill) {
+          directLines.push(`  [image-node] ${nid(node)} "${node.name || ''}": ${hashToHex(imageFill.image.hash)}`);
+        }
+      });
+
+      lines.push(...directLines);
+
       const inst = deck.getSlideInstance(id);
       if (!inst?.symbolData?.symbolOverrides) continue;
       for (const ov of inst.symbolData.symbolOverrides) {
         const key = ov.guidPath?.guids?.[0];
         const keyStr = key ? `${key.sessionID}:${key.localID}` : '?';
         if (ov.textData?.characters) {
-          lines.push(`  [text] ${keyStr}: ${ov.textData.characters.substring(0, 120)}`);
+          lines.push(`  [text-override] ${keyStr}: ${ov.textData.characters.substring(0, 120)}`);
         }
         if (ov.fillPaints?.length) {
           for (const p of ov.fillPaints) {
             if (p.image?.hash) {
-              lines.push(`  [image] ${keyStr}: ${hashToHex(p.image.hash)}`);
+              lines.push(`  [image-override] ${keyStr}: ${hashToHex(p.image.hash)}`);
             }
           }
         }
@@ -93,13 +122,13 @@ server.tool(
       function walkChildren(nodeId, depth) {
         const node = deck.getNode(nodeId);
         if (!node || node.phase === 'REMOVED') return;
-        const cid = nid(node);
+        const key = node.overrideKey ? `${node.overrideKey.sessionID}:${node.overrideKey.localID}` : null;
         const type = node.type || '?';
         const name = node.name || '';
-        if (type === 'TEXT' || (node.fillPaints?.some(p => p.type === 'IMAGE'))) {
-          lines.push(`  ${'  '.repeat(depth)}${type} ${cid} "${name}"`);
+        if (key && (type === 'TEXT' || node.fillPaints?.some(p => p.type === 'IMAGE'))) {
+          lines.push(`  ${'  '.repeat(depth)}${type} ${key} "${name}"`);
         }
-        const kids = deck.childrenMap.get(cid) || [];
+        const kids = deck.childrenMap.get(nid(node)) || [];
         for (const kid of kids) walkChildren(nid(kid), depth + 1);
       }
       for (const child of children) walkChildren(nid(child), 0);
@@ -127,7 +156,18 @@ server.tool(
 
     for (const [key, text] of Object.entries(overrides)) {
       const [s, l] = key.split(':').map(Number);
-      inst.symbolData.symbolOverrides.push(ov({ sessionID: s, localID: l }, text));
+      const nextOverride = ov({ sessionID: s, localID: l }, text);
+      const existingIdx = inst.symbolData.symbolOverrides.findIndex(entry =>
+        entry.guidPath?.guids?.length >= 1 &&
+        entry.guidPath.guids[0].sessionID === s &&
+        entry.guidPath.guids[0].localID === l &&
+        entry.textData
+      );
+      if (existingIdx >= 0) {
+        inst.symbolData.symbolOverrides.splice(existingIdx, 1, nextOverride);
+      } else {
+        inst.symbolData.symbolOverrides.push(nextOverride);
+      }
     }
 
     const bytes = await deck.saveDeck(output);
@@ -158,9 +198,18 @@ server.tool(
     if (!inst.symbolData.symbolOverrides) inst.symbolData.symbolOverrides = [];
 
     const [s, l] = targetKey.split(':').map(Number);
-    inst.symbolData.symbolOverrides.push(
-      imageOv({ sessionID: s, localID: l }, imageHash, thumbHash, width, height)
+    const nextOverride = imageOv({ sessionID: s, localID: l }, imageHash, thumbHash, width, height);
+    const existingIdx = inst.symbolData.symbolOverrides.findIndex(entry =>
+      entry.guidPath?.guids?.length >= 1 &&
+      entry.guidPath.guids[0].sessionID === s &&
+      entry.guidPath.guids[0].localID === l &&
+      entry.fillPaints
     );
+    if (existingIdx >= 0) {
+      inst.symbolData.symbolOverrides.splice(existingIdx, 1, nextOverride);
+    } else {
+      inst.symbolData.symbolOverrides.push(nextOverride);
+    }
 
     const opts = imagesDir ? { imagesDir } : {};
     const bytes = await deck.saveDeck(output, opts);
@@ -338,17 +387,70 @@ server.tool(
 );
 
 // ── figmatk_list_template_layouts ────────────────────────────────────────
+server.tool(
+  'figmatk_create_template_draft',
+  'Create a new draft template deck. Draft templates are normal slide decks; later annotate slots and publish-wrap them into module-backed layouts.',
+  {
+    output: z.string().describe('Output path for the draft template .deck file'),
+    title: z.string().describe('Template deck title'),
+    layouts: z.array(z.string()).optional().describe('Optional ordered list of layout names to create, e.g. ["cover", "agenda", "section"]'),
+  },
+  async ({ output, title, layouts }) => {
+    const bytes = await createDraftTemplate(output, { title, layouts });
+    return { content: [{ type: 'text', text: `Created draft template ${output} (${bytes} bytes). Use figmatk_annotate_template_layout to mark layout and slot names.` }] };
+  }
+);
+
+server.tool(
+  'figmatk_annotate_template_layout',
+  'Add explicit layout and slot metadata to a draft or published template. Use figmatk_inspect or figmatk_list_template_layouts first to get slide and node IDs.',
+  {
+    path: z.string().describe('Path to the source .deck file'),
+    output: z.string().describe('Output path for the updated .deck file'),
+    slideId: z.string().describe('Slide node ID to annotate'),
+    layoutName: z.string().optional().describe('Logical layout name without the layout: prefix, e.g. "cover"'),
+    textSlots: z.record(z.string()).optional().describe('Map of nodeId -> text slot name, e.g. {"1:120": "title"}'),
+    imageSlots: z.record(z.string()).optional().describe('Map of nodeId -> image slot name, e.g. {"1:144": "hero_image"}'),
+    fixedImages: z.record(z.string()).optional().describe('Map of nodeId -> fixed image label for decorative/sample content'),
+  },
+  async ({ path, output, slideId, layoutName, textSlots, imageSlots, fixedImages }) => {
+    const bytes = await annotateTemplateLayout(path, output, { slideId, layoutName, textSlots, imageSlots, fixedImages });
+    return { content: [{ type: 'text', text: `Annotated slide ${slideId}. Saved ${output} (${bytes} bytes).` }] };
+  }
+);
+
+server.tool(
+  'figmatk_publish_template_draft',
+  'Wrap draft template slides in publish-like MODULE nodes while preserving the slide subtree and internal canvas assets.',
+  {
+    path: z.string().describe('Path to the draft template .deck file'),
+    output: z.string().describe('Output path for the wrapped .deck file'),
+    slideIds: z.array(z.string()).optional().describe('Optional list of draft slide IDs to wrap. Defaults to every draft layout on the main canvas.'),
+  },
+  async ({ path, output, slideIds }) => {
+    const bytes = await publishTemplateDraft(path, output, { slideIds });
+    return { content: [{ type: 'text', text: `Publish-wrapped draft template to ${output} (${bytes} bytes).` }] };
+  }
+);
+
 server.tool(
   'figmatk_list_template_layouts',
-  'Inspect a Figma .deck template and return available slide layouts with their text field names. Call this first before figmatk_create_from_template.',
+  'Inspect a template or draft template .deck file and return available layouts with explicit text/image slot metadata. Call this before figmatk_create_from_template or figmatk_annotate_template_layout.',
   {
     template: z.string().describe('Path to the .deck template file'),
   },
   async ({ template }) => {
     const layouts = await listTemplateLayouts(template);
     const lines = layouts.map(l => {
-      const fields = l.textFields.map(f => `    - "${f.name}" (${f.nodeId}): "${f.preview}"`).join('\n');
-      return `Slide "${l.name}" [${l.slideId}]\n${fields || '    (no text fields)'}`;
+      const textSlots = l.textFields.map(f => `    - ${f.name} (${f.nodeId}, ${f.source}): "${f.preview}"`).join('\n');
+      const imageSlots = l.imagePlaceholders.map(f => `    - ${f.name} (${f.nodeId}, ${f.source}, ${f.width}x${f.height})${f.hasCurrentImage ? ' [image]' : ''}`).join('\n');
+      return [
+        `Layout "${l.name}" [${l.slideId}]`,
+        `  state: ${l.state}${l.moduleId ? `, module ${l.moduleId}` : ''}, row ${l.rowId}`,
+        `  explicit slots: ${l.hasExplicitSlotMetadata ? 'yes' : 'no'}`,
+        textSlots ? `  text slots:\n${textSlots}` : '  text slots: (none)',
+        imageSlots ? `  image slots:\n${imageSlots}` : '  image slots: (none)',
+      ].join('\n');
     });
     return { content: [{ type: 'text', text: lines.join('\n\n') }] };
   }
@@ -357,13 +459,14 @@ server.tool(
 // ── figmatk_create_from_template ─────────────────────────────────────────
 server.tool(
   'figmatk_create_from_template',
-  'Create a new Figma Slides deck by cherry-picking layouts from a template .deck file and populating them with content. Preserves all template colors, fonts, and styling.',
+  'Create a new Figma Slides deck by cherry-picking layouts from a draft, published, or publish-like template .deck file and populating explicit text/image slots. Preserves colors, fonts, internal assets, and special nodes.',
   {
     template: z.string().describe('Path to the source .deck template file'),
     output:   z.string().describe('Output path for the new .deck file (use /tmp/)'),
     slides: z.array(z.object({
       slideId: z.string().describe('Slide ID from figmatk_list_template_layouts (e.g. "1:74")'),
-      text:    z.record(z.string()).optional().describe('Map of text field name → value (e.g. { "Title": "My Company", "Body 1": "..." })'),
+      text:    z.record(z.string()).optional().describe('Map of text slot/name/nodeId -> value (e.g. { "title": "My Company" })'),
+      images:  z.record(z.string()).optional().describe('Map of image slot/name/nodeId -> absolute image path (e.g. { "hero_image": "/tmp/photo.jpg" })'),
     })).describe('Ordered list of slides to include, each referencing a template layout'),
   },
   async ({ template, output, slides }) => {

package/package.json

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

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

@@ -1,16 +1,30 @@
 ---
 name: figma-slides-creator
 description: >
-  Create, edit, and inspect Figma Slides .deck files. Use when the user asks to
-  create a presentation, build a slide deck, edit slides, update text or images,
-  clone or remove slides, or produce a .deck file for Figma Slides.
+  Create, populate, edit, and inspect Figma Slides .deck files. Use when the
+  user wants a finished presentation deck, wants to fill an existing template
+  with content, or wants to edit a non-template deck's text, images, or slide
+  order. Do not use this skill to author reusable templates themselves.
   Powered by FigmaTK under the hood.
 metadata:
-  version: "0.3.0"
+  version: "0.3.1"
 ---
 
 # Figma Slides Creator
 
+Use this skill for the default workflow: take an existing template and build a new presentation from it. For authoring reusable templates themselves, use `skills/figma-template-builder/SKILL.md`.
+
+## Skill Boundary
+
+Use this skill when the outcome is a finished deck for immediate use.
+
+Switch to `skills/figma-template-builder/SKILL.md` when the user wants to:
+
+- build a reusable template
+- define layouts or placeholders
+- rename slots for future sessions
+- derive a new template system from references or examples
+
 ## ⚠️ Never open .deck files directly
 
 `.deck` files are binary ZIP archives. **Never open, read, or display a `.deck` file** — it will show garbage bytes in the panel. To inspect or modify a `.deck` file, always use the CLI commands or Node.js API shown below.
@@ -25,6 +39,7 @@ To let the user view the result: tell them to **open the file in Figma Desktop**
 |------|----------|
 | Create from scratch | **Path A** — `figmatk_create_deck` MCP tool |
 | Create from a `.deck` template | **Path B** — `figmatk_list_template_layouts` + `figmatk_create_from_template` |
+| Author a reusable template | Use `skills/figma-template-builder/SKILL.md` |
 | Edit text or images in an existing deck | `figmatk_update_text`, `figmatk_insert_image` |
 | Clone, remove, or restructure slides | `figmatk_clone_slide`, `figmatk_remove_slide` |
 | Inspect structure or read content | `figmatk_inspect`, `figmatk_list_text` |
@@ -35,6 +50,14 @@ To let the user view the result: tell them to **open the file in Figma Desktop**
 
 **All files go in `/tmp/`** — scripts, output decks, images, everything. Never write to the Desktop, Documents, Downloads, or any user directory. Never create intermediate notes or reference markdown files. Just build and save the deck.
 
+## Default Workflow
+
+1. Inspect the template or deck.
+2. Pick the minimum set of layouts or edits needed.
+3. Populate text slots first, then image slots.
+4. Save to a new `/tmp/` output path.
+5. Sanity-check the result with `figmatk_list_text` or by opening it in Figma Desktop.
+
 ---
 
 ## Path B — Create from a Template (preferred when user provides a .deck file)
@@ -49,13 +72,16 @@ figmatk_list_template_layouts("/path/to/template.deck")
 
 Returns a catalog of all available slide layouts. Each entry includes:
 - `slideId` — the ID to reference this layout
-- Text fields — editable TEXT nodes with their names and current content
-- Image placeholders — FRAME nodes with IMAGE fill (these need a real image)
+- Layout state — `draft` or `published`
+- Text slots — explicit `slot:text:*` fields when present, otherwise fallback text candidates
+- Image slots — explicit `slot:image:*` fields when present, otherwise fallback image candidates
+- Node IDs — usable for direct targeting when the template has not been fully annotated yet
 
 **Read the catalog carefully before picking layouts:**
-- Match each slide's purpose to your content (the existing text in the template is a strong hint — e.g. "Use this slide to introduce the big problem" → use for your problem statement)
-- Slides with image placeholders need an appropriate image — the surrounding text should describe what's shown in that image
-- Slides with `SHAPE_WITH_TEXT` pill labels (MONTH XX YEAR, TAGLINE, CONFIDENTIAL) cannot be changed programmatically — tell the user to update those in Figma
+- Prefer layouts with explicit slot metadata when available
+- Match each slide's purpose to your content; the existing copy is often the best hint
+- Use slot names first, then node IDs, then raw node names when populating content
+- If a layout exposes no explicit image slots, treat heuristic image candidates as weaker signals and avoid overwriting decorative sample imagery unless the user clearly wants that
 
 ### Step 2 — Create the deck
 
@@ -64,14 +90,14 @@ figmatk_create_from_template({
   template: "/path/to/template.deck",
   output: "/tmp/my-deck.deck",
   slides: [
-    { slideId: "1:74",  text: { "Title": "My Company" } },
-    { slideId: "1:112", text: { "Header 1": "The problem.", "Body 1": "Description here." } },
-    { slideId: "1:643", text: { "Thank you": "Thank you!" } }
+    { slideId: "1:74",  text: { "title": "My Company" } },
+    { slideId: "1:112", text: { "header": "The problem.", "body": "Description here." }, images: { "hero_image": "/tmp/problem-photo.jpg" } },
+    { slideId: "1:643", text: { "title": "Thank you!" } }
   ]
 })
 ```
 
-Only pass text fields that exist in the layout's catalog — extra fields are silently ignored.
+Only pass slots or node IDs that exist in the layout's catalog. Extra keys are silently ignored.
 
 ---
 
@@ -250,6 +276,14 @@ Use this when the user provides a `.deck` file to modify.
 | `figmatk_remove_slide` | Mark slides as REMOVED (never deleted) |
 | `figmatk_roundtrip` | Decode + re-encode for pipeline validation |
 
+## Final Checks
+
+Before finishing, prefer at least one of these:
+
+- `figmatk_list_text` on the output deck
+- `figmatk_roundtrip` if the deck went through multiple edits
+- a manual open check in Figma Desktop when the user is validating upload/render behavior
+
 ---
 
 ## Design Philosophy

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

@@ -0,0 +1,148 @@
+---
+name: figma-template-builder
+description: >
+  Author reusable Figma Slides templates as .deck files. Use when the user
+  wants to build a template from reference images or examples, derive a new
+  template from an existing deck, define reusable layouts, mark editable
+  text/image slots, or prepare a draft template for later instantiation.
+metadata:
+  version: "0.1.0"
+---
+
+# Figma Template Builder
+
+Use this skill when the goal is to build or refine the template itself. For the common workflow of taking an existing template and producing a new presentation, use `skills/figma-slides-creator/SKILL.md`.
+
+## Skill Boundary
+
+Use this skill when the deliverable is a reusable template, not a one-off deck.
+
+Stay here when the user wants to:
+
+- translate reference images or screenshots into template layouts
+- create a new layout family
+- define placeholder semantics for later sessions
+- turn an ordinary deck into a reusable template
+
+Hand off to `skills/figma-slides-creator/SKILL.md` once the template exists and the task becomes simple content population.
+
+## Core Model
+
+Template work happens in two states:
+
+- Draft template: `SLIDE_ROW -> SLIDE -> ...`
+- Published or publish-like template: `SLIDE_ROW -> MODULE -> SLIDE -> ...`
+
+Draft templates are easier to author. Publish-like wrapping is the final step before later instantiation.
+
+## Design-First Workflow
+
+When the user provides reference images, screenshots, or example decks:
+
+1. Read the references first and infer the layout family before touching the `.deck`.
+2. Decide which parts are reusable structure versus one-off sample content.
+3. Create only the smallest set of layouts that captures the system.
+4. Use semantic slot names so later sessions can populate them without re-reading the design intent.
+
+Do not mirror every visual variation as its own layout unless the content structure changes materially.
+
+## Naming Conventions
+
+Always use explicit metadata when authoring reusable layouts:
+
+- Layouts: `layout:<name>`
+- Text slots: `slot:text:<name>`
+- Image slots: `slot:image:<name>`
+- Decorative fixed imagery: `fixed:image:<name>`
+
+These conventions are how later sessions discover what is editable.
+
+Prefer semantic names over visual or auto-generated names.
+
+Good:
+
+- `title`
+- `subtitle`
+- `hero_image`
+- `device_screen_primary`
+- `quote_author`
+
+Bad:
+
+- `text1`
+- `frame183`
+- `image-left`
+- `rectangle2`
+
+## Recommended Flow
+
+### 1. Create or inspect a draft template
+
+- New draft from scratch: `figmatk_create_template_draft`
+- Existing deck/template: `figmatk_list_template_layouts`
+- Structural inspection: `figmatk_inspect`
+
+### 2. Annotate reusable layouts
+
+Use `figmatk_annotate_template_layout` to:
+
+- rename a slide as a layout
+- mark text nodes as editable text slots
+- mark image-bearing nodes as editable image slots
+- mark decorative imagery as fixed
+
+The tool accepts node ID maps, so inspect first if you need the raw node IDs.
+
+While annotating:
+
+- rename the slide itself to the stable layout name
+- mark only true placeholders as `slot:*`
+- mark decorative or sample imagery as `fixed:image:*`
+- prefer stable semantic names over spatial names like `left_box`
+
+### 3. Publish-wrap when the template is ready
+
+Use `figmatk_publish_template_draft` to add publish-like `MODULE` wrappers while preserving the slide subtree and internal assets.
+
+### 4. Verify the result
+
+- `figmatk_list_template_layouts`
+- `figmatk_list_text`
+- `figmatk_roundtrip` if you want a conservative encode/decode check
+- open the wrapped template in Figma Desktop when validating real upload behavior
+
+## Practical Rules
+
+- Prefer explicit slot names over heuristic placeholders.
+- Do not assume every image fill is editable content.
+- Preserve `Internal Only Canvas` assets.
+- Preserve special nodes such as device mockups and interactive slide elements; do not try to recreate them from scratch unless necessary.
+
+## Template Authoring Heuristics
+
+- Start with 4-8 reusable layouts, not an exhaustive library.
+- Reuse one layout when only copy length changes; create a new layout when hierarchy or media structure changes.
+- Separate content slots from chrome. For device mockups, the screen is usually the slot and the hardware frame is usually fixed.
+- If a layout has explicit slot metadata, do not rely on heuristic image placeholders for that layout.
+- After publish-wrapping, re-run `figmatk_list_template_layouts` and confirm the layout names and slot names survived unchanged.
+
+## Example
+
+```json
+{
+  "path": "/tmp/draft-template.deck",
+  "output": "/tmp/draft-template-annotated.deck",
+  "slideId": "1:42",
+  "layoutName": "cover",
+  "textSlots": {
+    "1:120": "title",
+    "1:121": "subtitle"
+  },
+  "imageSlots": {
+    "1:144": "hero_image"
+  },
+  "fixedImages": {
+    "1:199": "background_texture"
+  }
+}
+```