figmatk 0.2.6 → 0.3.1

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/README.md

@@ -67,7 +67,23 @@ Or add manually in Claude Desktop → Settings → Developer → Edit Config:
 }
 ```
 
-Available MCP tools: `figmatk_create_deck`, `figmatk_inspect`, `figmatk_list_text`, `figmatk_list_overrides`, `figmatk_update_text`, `figmatk_insert_image`, `figmatk_clone_slide`, `figmatk_remove_slide`, `figmatk_roundtrip`.
+Available MCP tools: `figmatk_create_deck`, `figmatk_create_template_draft`, `figmatk_annotate_template_layout`, `figmatk_publish_template_draft`, `figmatk_list_template_layouts`, `figmatk_create_from_template`, `figmatk_inspect`, `figmatk_list_text`, `figmatk_list_overrides`, `figmatk_update_text`, `figmatk_insert_image`, `figmatk_clone_slide`, `figmatk_remove_slide`, `figmatk_roundtrip`.
+
+## Template Workflows
+
+FigmaTK supports two related template states:
+
+- Draft templates: `SLIDE_ROW -> SLIDE -> ...`
+- Published templates: `SLIDE_ROW -> MODULE -> SLIDE -> ...`
+
+Use explicit naming conventions when authoring reusable templates:
+
+- Layouts: `layout:<name>`
+- Text slots: `slot:text:<name>`
+- Image slots: `slot:image:<name>`
+- Decorative fixed imagery: `fixed:image:<name>`
+
+`figmatk_list_template_layouts` understands those conventions and only falls back to heuristic image placeholders when a layout has not been explicitly annotated yet.
 
 ## Programmatic API
 
@@ -84,6 +100,7 @@ await deck.save('output.deck');
 |------|---|
 | High-level API | [docs/figmatk-api-spec.md](docs/figmatk-api-spec.md) |
 | Low-level FigDeck API | [docs/library.md](docs/library.md) |
+| Template workflows | [docs/template-workflows.md](docs/template-workflows.md) |
 | File format internals | [docs/format/](docs/format/) |
 
 ## License

package/lib/fig-deck.mjs

@@ -14,9 +14,10 @@ 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 { readFileSync, createWriteStream, existsSync, mkdtempSync } from 'fs';
 import { execSync } from 'child_process';
 import { join, resolve } from 'path';
+import { tmpdir } from 'os';
 import { nid } from './node-helpers.mjs';
 
 export class FigDeck {
@@ -42,9 +43,8 @@ export class 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' });
+    const tmp = mkdtempSync(join(tmpdir(), 'figmatk_'));
+    execSync(`unzip -o "${absPath}" -d "${tmp}"`, { stdio: 'pipe' });
     deck._tempDir = tmp;
 
     // Read canvas.fig

package/lib/template-deck.mjs

@@ -0,0 +1,643 @@
+/**
+ * template-deck — Inspect, author, wrap, and instantiate Figma Slides templates.
+ *
+ * Template workflows now cover two structural states:
+ * - Draft templates:      SLIDE_ROW -> SLIDE -> ...
+ * - Published templates:  SLIDE_ROW -> MODULE -> SLIDE -> ...
+ */
+import { createHash } from 'crypto';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync } from 'fs';
+import { join, resolve } from 'path';
+import { Deck } from './api.mjs';
+import { deepClone } from './deep-clone.mjs';
+import { FigDeck } from './fig-deck.mjs';
+import { hexToHash } from './image-helpers.mjs';
+import { getImageDimensions, generateThumbnail } from './image-utils.mjs';
+import { nid, positionChar } from './node-helpers.mjs';
+
+export const LAYOUT_PREFIX = 'layout:';
+export const TEXT_SLOT_PREFIX = 'slot:text:';
+export const IMAGE_SLOT_PREFIX = 'slot:image:';
+export const FIXED_IMAGE_PREFIX = 'fixed:image:';
+
+const INTERNAL_CANVAS_NAME = 'Internal Only Canvas';
+const MODULE_VERSION = '1:37';
+const DEFAULT_ROW_GAP = 2160;
+
+/**
+ * Inspect a template deck and return available layouts plus explicit slot metadata.
+ */
+export async function listTemplateLayouts(templatePath, opts = {}) {
+  const deck = await FigDeck.fromDeckFile(templatePath);
+  return describeTemplateLayouts(deck, opts);
+}
+
+/**
+ * Create a new draft template deck from scratch.
+ */
+export async function createDraftTemplate(outputPath, opts = {}) {
+  const title = opts.title ?? 'Untitled';
+  const layoutNames = Array.isArray(opts.layouts) && opts.layouts.length
+    ? opts.layouts
+    : ['cover'];
+
+  const deck = await Deck.create({ name: title });
+  for (const name of layoutNames) {
+    deck.addBlankSlide({ name: normalizeLayoutName(name) });
+  }
+
+  await deck.save(outputPath);
+  return statSync(resolve(outputPath)).size;
+}
+
+/**
+ * Add or update explicit layout/slot metadata on an existing draft or published template.
+ */
+export async function annotateTemplateLayout(path, outputPath, opts = {}) {
+  const deck = await FigDeck.fromDeckFile(path);
+  const slide = deck.getNode(opts.slideId);
+  if (!slide || slide.type !== 'SLIDE') {
+    throw new Error(`Slide not found: ${opts.slideId}`);
+  }
+
+  const module = getParentModule(deck, slide);
+  if (opts.layoutName) {
+    const layoutName = normalizeLayoutName(opts.layoutName);
+    slide.name = layoutName;
+    if (module) module.name = layoutName;
+  }
+
+  renameNodes(deck, opts.textSlots, TEXT_SLOT_PREFIX);
+  renameNodes(deck, opts.imageSlots, IMAGE_SLOT_PREFIX);
+  renameNodes(deck, opts.fixedImages, FIXED_IMAGE_PREFIX);
+
+  return deck.saveDeck(outputPath);
+}
+
+/**
+ * Convert draft slides into publish-like module-backed layouts.
+ */
+export async function publishTemplateDraft(path, outputPath, opts = {}) {
+  const deck = await FigDeck.fromDeckFile(path);
+  const targetIds = new Set(opts.slideIds ?? []);
+  const layouts = describeTemplateLayouts(deck);
+  const draftLayouts = layouts.filter(layout => layout.state === 'draft');
+  const targets = targetIds.size
+    ? draftLayouts.filter(layout => targetIds.has(layout.slideId))
+    : draftLayouts;
+
+  if (!targets.length) {
+    throw new Error('No draft template slides found to wrap');
+  }
+
+  let nextId = deck.maxLocalID() + 1;
+  for (const layout of targets) {
+    const slide = deck.getNode(layout.slideId);
+    if (!slide) continue;
+
+    const row = deck.getNode(layout.rowId);
+    if (!row) {
+      throw new Error(`Slide row not found for ${layout.slideId}`);
+    }
+
+    const moduleGuid = { sessionID: slide.guid.sessionID, localID: nextId++ };
+    const module = createModuleWrapper(slide, moduleGuid);
+    module.parentIndex = deepClone(slide.parentIndex);
+
+    slide.parentIndex = { guid: deepClone(moduleGuid), position: '!' };
+
+    deck.message.nodeChanges.push(module);
+  }
+
+  deck.rebuildMaps();
+  return deck.saveDeck(outputPath);
+}
+
+/**
+ * Create a new deck from a template by cherry-picking and populating layouts.
+ *
+ * @param {string} templatePath
+ * @param {string} outputPath
+ * @param {Array<{slideId: string, text?: Record<string, string>, images?: Record<string, string>}>} slideDefs
+ */
+export async function createFromTemplate(templatePath, outputPath, slideDefs) {
+  const deck = await FigDeck.fromDeckFile(templatePath);
+  const layouts = describeTemplateLayouts(deck);
+  const layoutBySlideId = new Map(layouts.map(layout => [layout.slideId, layout]));
+  const mainRows = getMainSlideRows(deck);
+  const targetRow = mainRows[0];
+
+  if (!targetRow) {
+    throw new Error('No main-canvas SLIDE_ROW found in template');
+  }
+
+  let nextId = deck.maxLocalID() + 1;
+  const sessionId = 200;
+
+  for (let defIdx = 0; defIdx < slideDefs.length; defIdx++) {
+    const def = slideDefs[defIdx];
+    const sourceLayout = layoutBySlideId.get(def.slideId);
+    if (!sourceLayout) throw new Error(`Layout not found: ${def.slideId}`);
+
+    const rootId = sourceLayout.moduleId ?? sourceLayout.slideId;
+    const subtreeNodes = [];
+    deck.walkTree(rootId, node => {
+      if (node.phase !== 'REMOVED') subtreeNodes.push(node);
+    });
+
+    const idMap = new Map();
+    for (const node of subtreeNodes) {
+      idMap.set(nid(node), { sessionID: sessionId, localID: nextId++ });
+    }
+
+    const reverseIdMap = new Map();
+    for (const [oldId, guid] of idMap.entries()) {
+      reverseIdMap.set(`${guid.sessionID}:${guid.localID}`, oldId);
+    }
+
+    const clonedNodes = subtreeNodes.map(node => {
+      const clone = deepClone(node);
+      const oldId = nid(node);
+      const newGuid = idMap.get(oldId);
+      if (newGuid) clone.guid = newGuid;
+
+      if (oldId === rootId) {
+        clone.parentIndex = {
+          guid: deepClone(targetRow.guid),
+          position: positionChar(defIdx),
+        };
+        if (clone.transform) {
+          clone.transform.m02 = defIdx * DEFAULT_ROW_GAP;
+        }
+      } else if (clone.parentIndex?.guid) {
+        const parentId = `${clone.parentIndex.guid.sessionID}:${clone.parentIndex.guid.localID}`;
+        const remappedParent = idMap.get(parentId);
+        if (remappedParent) {
+          clone.parentIndex = { ...clone.parentIndex, guid: remappedParent };
+        }
+      }
+
+      clone.phase = 'CREATED';
+      delete clone.slideThumbnailHash;
+      delete clone.editInfo;
+      delete clone.prototypeInteractions;
+
+      return clone;
+    });
+
+    for (const clone of clonedNodes) {
+      const originalId = reverseIdMap.get(nid(clone));
+      const textValue = pickMappedValue(def.text, candidateTextKeys(sourceLayout, clone, originalId));
+      if (textValue !== undefined) {
+        applyTextValue(clone, textValue);
+      }
+
+      const imagePath = pickMappedValue(def.images, candidateImageKeys(sourceLayout, clone, originalId));
+      if (imagePath !== undefined) {
+        await applyImageValue(deck, clone, imagePath);
+      }
+    }
+
+    deck.message.nodeChanges.push(...clonedNodes);
+  }
+
+  deck.rebuildMaps();
+
+  const pruneIds = new Set();
+  for (const layout of layouts) {
+    collectSubtree(deck, layout.moduleId ?? layout.slideId, pruneIds);
+  }
+
+  const targetRowId = nid(targetRow);
+  const extraRowIds = new Set(mainRows.slice(1).map(row => nid(row)));
+
+  deck.message.nodeChanges = deck.message.nodeChanges.filter(node => {
+    const id = nid(node);
+    if (!id) return true;
+    if (pruneIds.has(id)) return false;
+    if (id !== targetRowId && extraRowIds.has(id)) return false;
+    return true;
+  });
+
+  deck.rebuildMaps();
+  return deck.saveDeck(outputPath);
+}
+
+function describeTemplateLayouts(deck, opts = {}) {
+  const includeInternal = Boolean(opts.includeInternal);
+  const rows = includeInternal
+    ? deck.message.nodeChanges.filter(node => node.type === 'SLIDE_ROW' && node.phase !== 'REMOVED')
+    : getMainSlideRows(deck);
+
+  const layouts = [];
+  for (const row of rows) {
+    for (const layout of getRowLayouts(deck, row)) {
+      layouts.push(describeLayout(deck, layout, row));
+    }
+  }
+  return layouts;
+}
+
+function getMainSlideRows(deck) {
+  return deck.message.nodeChanges.filter(node => {
+    if (node.type !== 'SLIDE_ROW' || node.phase === 'REMOVED') return false;
+    const canvas = getAncestorCanvas(deck, node);
+    return !isInternalCanvas(canvas);
+  });
+}
+
+function getRowLayouts(deck, row) {
+  const layouts = [];
+  for (const child of deck.getChildren(nid(row))) {
+    if (child.phase === 'REMOVED') continue;
+    if (child.type === 'MODULE') {
+      for (const maybeSlide of deck.getChildren(nid(child))) {
+        if (maybeSlide.phase === 'REMOVED' || maybeSlide.type !== 'SLIDE') continue;
+        layouts.push({ slide: maybeSlide, module: child });
+      }
+      continue;
+    }
+    if (child.type === 'SLIDE') {
+      layouts.push({ slide: child, module: null });
+    }
+  }
+  return layouts;
+}
+
+function describeLayout(deck, layout, row) {
+  const rootId = layout.module ? nid(layout.module) : nid(layout.slide);
+  const slotDiscovery = discoverSlots(deck, rootId);
+  const nameSource = layout.module?.name || layout.slide.name || layout.slide.name || 'Untitled';
+  const canonicalName = stripLayoutPrefix(nameSource);
+
+  return {
+    slideId: nid(layout.slide),
+    moduleId: layout.module ? nid(layout.module) : null,
+    rowId: nid(row),
+    rowName: row.name || 'Slide row',
+    name: canonicalName,
+    rawName: nameSource,
+    state: layout.module ? 'published' : 'draft',
+    hasExplicitSlotMetadata: slotDiscovery.hasExplicitSlotMetadata,
+    slots: [...slotDiscovery.textSlots, ...slotDiscovery.imageSlots],
+    textFields: slotDiscovery.textSlots.map(slot => ({
+      nodeId: slot.nodeId,
+      name: slot.name,
+      preview: slot.preview,
+      source: slot.source,
+    })),
+    imagePlaceholders: slotDiscovery.imageSlots.map(slot => ({
+      nodeId: slot.nodeId,
+      name: slot.name,
+      type: slot.nodeType,
+      width: slot.width,
+      height: slot.height,
+      hasCurrentImage: slot.hasCurrentImage,
+      source: slot.source,
+    })),
+  };
+}
+
+function discoverSlots(deck, rootId) {
+  const explicitTextSlots = [];
+  const explicitImageSlots = [];
+  const fallbackTextSlots = [];
+  const fallbackImageSlots = [];
+
+  deck.walkTree(rootId, node => {
+    const textSlotName = parsePrefixedName(node.name, TEXT_SLOT_PREFIX);
+    if (textSlotName) {
+      const slot = describeTextSlot(node, textSlotName, 'explicit');
+      if (slot) explicitTextSlots.push(slot);
+      return;
+    }
+
+    const imageSlotName = parsePrefixedName(node.name, IMAGE_SLOT_PREFIX);
+    if (imageSlotName) {
+      const slot = describeImageSlot(node, imageSlotName, 'explicit');
+      if (slot) explicitImageSlots.push(slot);
+      return;
+    }
+
+    if (parsePrefixedName(node.name, FIXED_IMAGE_PREFIX)) {
+      return;
+    }
+
+    const fallbackText = describeFallbackTextSlot(node);
+    if (fallbackText) fallbackTextSlots.push(fallbackText);
+
+    const fallbackImage = describeFallbackImageSlot(deck, node);
+    if (fallbackImage) fallbackImageSlots.push(fallbackImage);
+  });
+
+  const hasExplicitSlotMetadata = explicitTextSlots.length > 0 || explicitImageSlots.length > 0;
+
+  return {
+    hasExplicitSlotMetadata,
+    textSlots: explicitTextSlots.length ? explicitTextSlots : fallbackTextSlots,
+    imageSlots: hasExplicitSlotMetadata ? explicitImageSlots : fallbackImageSlots,
+  };
+}
+
+function describeFallbackTextSlot(node) {
+  if (node.type === 'TEXT' && node.name) {
+    return describeTextSlot(node, node.name, 'heuristic');
+  }
+
+  if (node.type === 'SHAPE_WITH_TEXT' && node.nodeGenerationData?.overrides?.length) {
+    return {
+      type: 'text',
+      nodeId: nid(node),
+      name: `#${nid(node)}`,
+      preview: firstShapeText(node),
+      source: 'heuristic',
+      nodeType: node.type,
+    };
+  }
+
+  return null;
+}
+
+function describeTextSlot(node, name, source) {
+  if (node.type === 'TEXT') {
+    return {
+      type: 'text',
+      nodeId: nid(node),
+      name,
+      preview: (node.textData?.characters ?? '').slice(0, 80),
+      source,
+      nodeType: node.type,
+    };
+  }
+
+  if (node.type === 'SHAPE_WITH_TEXT') {
+    return {
+      type: 'text',
+      nodeId: nid(node),
+      name,
+      preview: firstShapeText(node),
+      source,
+      nodeType: node.type,
+    };
+  }
+
+  return null;
+}
+
+function describeFallbackImageSlot(deck, node) {
+  if (node.name && parsePrefixedName(node.name, FIXED_IMAGE_PREFIX)) return null;
+  const hasImageFill = node.fillPaints?.some(fill => fill.type === 'IMAGE');
+  const isLargeEmptyFrame = (node.type === 'FRAME' || node.type === 'ROUNDED_RECTANGLE')
+    && (node.size?.x ?? 0) > 100
+    && (node.size?.y ?? 0) > 100
+    && deck.getChildren(nid(node)).filter(child => child.phase !== 'REMOVED').length === 0;
+
+  if (!hasImageFill && !isLargeEmptyFrame) return null;
+
+  return describeImageSlot(node, `#${nid(node)}`, 'heuristic');
+}
+
+function describeImageSlot(node, name, source) {
+  const hasImageFill = node.fillPaints?.some(fill => fill.type === 'IMAGE') ?? false;
+  return {
+    type: 'image',
+    nodeId: nid(node),
+    name,
+    source,
+    nodeType: node.type,
+    width: Math.round(node.size?.x ?? 0),
+    height: Math.round(node.size?.y ?? 0),
+    hasCurrentImage: hasImageFill,
+  };
+}
+
+function candidateTextKeys(layout, node, originalId) {
+  const keys = [];
+  const field = layout.textFields.find(entry => entry.nodeId === originalId);
+  if (field?.name) keys.push(field.name);
+  if (originalId) {
+    keys.push(originalId);
+    keys.push(`#${originalId}`);
+  }
+  if (node.name) keys.push(node.name);
+  return dedupe(keys);
+}
+
+function candidateImageKeys(layout, node, originalId) {
+  const keys = [];
+  const field = layout.imagePlaceholders.find(entry => entry.nodeId === originalId);
+  if (field?.name) keys.push(field.name);
+  if (originalId) {
+    keys.push(originalId);
+    keys.push(`#${originalId}`);
+  }
+  if (node.name) keys.push(node.name);
+  return dedupe(keys);
+}
+
+function pickMappedValue(map, keys) {
+  if (!map) return undefined;
+  for (const key of keys) {
+    if (key in map) return map[key];
+  }
+  return undefined;
+}
+
+function applyTextValue(node, text) {
+  const chars = text === '' || text == null ? ' ' : text;
+
+  if (node.type === 'TEXT') {
+    if (!node.textData) node.textData = {};
+    node.textData.characters = chars;
+    node.textData.lines = chars.split('\n').map(() => ({
+      lineType: 'PLAIN',
+      styleId: 0,
+      indentationLevel: 0,
+      sourceDirectionality: 'AUTO',
+      listStartOffset: 0,
+      isFirstLineOfList: false,
+    }));
+    delete node.derivedTextData;
+    return;
+  }
+
+  if (node.type === 'SHAPE_WITH_TEXT' && node.nodeGenerationData?.overrides) {
+    for (const override of node.nodeGenerationData.overrides) {
+      if (!override.textData) continue;
+      override.textData.characters = chars;
+      override.textData.lines = chars.split('\n').map(() => ({
+        lineType: 'PLAIN',
+        styleId: 0,
+        indentationLevel: 0,
+        sourceDirectionality: 'AUTO',
+        listStartOffset: 0,
+        isFirstLineOfList: false,
+      }));
+    }
+    delete node.derivedImmutableFrameData;
+  }
+}
+
+async function applyImageValue(deck, node, imagePath) {
+  const absPath = resolve(imagePath);
+  const imgBuf = readFileSync(absPath);
+  const imgHash = sha1Hex(imgBuf);
+  const { width, height } = await getImageDimensions(imgBuf);
+
+  const tmpThumb = `/tmp/figmatk_thumb_${Date.now()}_${Math.random().toString(36).slice(2)}.png`;
+  await generateThumbnail(imgBuf, tmpThumb);
+  const thumbHash = sha1Hex(readFileSync(tmpThumb));
+
+  copyToImagesDir(deck, imgHash, absPath);
+  copyToImagesDir(deck, thumbHash, tmpThumb);
+
+  const fill = {
+    type: 'IMAGE',
+    opacity: 1,
+    visible: true,
+    blendMode: 'NORMAL',
+    transform: { m00: 1, m01: 0, m02: 0, m10: 0, m11: 1, m12: 0 },
+    image: { hash: hexToHash(imgHash), name: imgHash },
+    imageThumbnail: { hash: hexToHash(thumbHash), name: thumbHash },
+    animationFrame: 0,
+    imageScaleMode: existingImageScaleMode(node) ?? 'FILL',
+    imageShouldColorManage: false,
+    rotation: 0,
+    scale: 0.5,
+    originalImageWidth: width,
+    originalImageHeight: height,
+    thumbHash: new Uint8Array(0),
+    altText: '',
+  };
+
+  if (node.fillPaints?.length) {
+    const idx = node.fillPaints.findIndex(paint => paint.type === 'IMAGE');
+    if (idx >= 0) {
+      node.fillPaints.splice(idx, 1, fill);
+    } else {
+      node.fillPaints = [fill];
+    }
+  } else {
+    node.fillPaints = [fill];
+  }
+
+  delete node.derivedImmutableFrameData;
+}
+
+function collectSubtree(deck, rootId, seen) {
+  if (!rootId || seen.has(rootId)) return;
+  seen.add(rootId);
+  for (const child of deck.getChildren(rootId)) {
+    collectSubtree(deck, nid(child), seen);
+  }
+}
+
+function renameNodes(deck, map, prefix) {
+  if (!map) return;
+  for (const [nodeId, name] of Object.entries(map)) {
+    const node = deck.getNode(nodeId);
+    if (!node) throw new Error(`Node not found: ${nodeId}`);
+    node.name = `${prefix}${stripPrefix(name)}`;
+  }
+}
+
+function createModuleWrapper(slide, moduleGuid) {
+  return {
+    guid: deepClone(moduleGuid),
+    phase: 'CREATED',
+    type: 'MODULE',
+    name: slide.name ?? 'layout',
+    isPublishable: true,
+    version: MODULE_VERSION,
+    userFacingVersion: MODULE_VERSION,
+    visible: true,
+    opacity: 1,
+    size: deepClone(slide.size ?? { x: 1920, y: 1080 }),
+    transform: { m00: 1, m01: 0, m02: slide.transform?.m02 ?? 0, m10: 0, m11: 1, m12: slide.transform?.m12 ?? 0 },
+    strokeWeight: 1,
+    strokeAlign: 'INSIDE',
+    strokeJoin: 'MITER',
+    fillPaints: deepClone(slide.fillPaints ?? [{
+      type: 'SOLID',
+      color: { r: 1, g: 1, b: 1, a: 1 },
+      opacity: 1,
+      visible: true,
+      blendMode: 'NORMAL',
+    }]),
+    fillGeometry: [{
+      windingRule: 'NONZERO',
+      commandsBlob: 13,
+      styleID: 0,
+    }],
+    frameMaskDisabled: false,
+  };
+}
+
+function getParentModule(deck, slide) {
+  if (!slide?.parentIndex?.guid) return null;
+  const parent = deck.getNode(guidId(slide.parentIndex.guid));
+  return parent?.type === 'MODULE' ? parent : null;
+}
+
+function getAncestorCanvas(deck, node) {
+  let current = node;
+  while (current?.parentIndex?.guid) {
+    const parent = deck.getNode(guidId(current.parentIndex.guid));
+    if (!parent) return null;
+    if (parent.type === 'CANVAS') return parent;
+    current = parent;
+  }
+  return null;
+}
+
+function isInternalCanvas(canvas) {
+  return canvas?.name === INTERNAL_CANVAS_NAME;
+}
+
+function parsePrefixedName(value, prefix) {
+  if (!value || !value.startsWith(prefix)) return null;
+  return stripPrefix(value.slice(prefix.length));
+}
+
+function normalizeLayoutName(value) {
+  const stripped = stripLayoutPrefix(value || 'layout');
+  return `${LAYOUT_PREFIX}${stripped}`;
+}
+
+function stripLayoutPrefix(value) {
+  return parsePrefixedName(value, LAYOUT_PREFIX) ?? stripPrefix(value);
+}
+
+function stripPrefix(value) {
+  return String(value ?? '').trim().replace(/^(layout:|slot:text:|slot:image:|fixed:image:)/, '');
+}
+
+function firstShapeText(node) {
+  const text = node.nodeGenerationData?.overrides?.find(override => override.textData?.characters)?.textData?.characters ?? '';
+  return text.trim().slice(0, 80);
+}
+
+function existingImageScaleMode(node) {
+  return node.fillPaints?.find(fill => fill.type === 'IMAGE')?.imageScaleMode;
+}
+
+function dedupe(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+function guidId(guid) {
+  return guid ? `${guid.sessionID}:${guid.localID}` : null;
+}
+
+function sha1Hex(buf) {
+  return createHash('sha1').update(buf).digest('hex');
+}
+
+function copyToImagesDir(deck, hash, srcPath) {
+  if (!deck.imagesDir) {
+    deck.imagesDir = `/tmp/figmatk_images_${Date.now()}`;
+    mkdirSync(deck.imagesDir, { recursive: true });
+  }
+  const dest = join(deck.imagesDir, hash);
+  if (!existsSync(dest)) copyFileSync(srcPath, dest);
+}

package/mcp-server.mjs

@@ -7,8 +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 { 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({
@@ -45,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);
@@ -55,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)}`);
             }
           }
         }
@@ -92,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);
@@ -126,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);
@@ -157,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);
@@ -336,6 +386,95 @@ 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 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 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') }] };
+  }
+);
+
+// ── figmatk_create_from_template ─────────────────────────────────────────
+server.tool(
+  'figmatk_create_from_template',
+  '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 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 }) => {
+    const bytes = await createFromTemplate(template, output, slides);
+    return { content: [{ type: 'text', text: `Created ${output} — ${slides.length} slides (${bytes} bytes). Open in Figma Desktop.` }] };
+  }
+);
+
 // ── Start server ────────────────────────────────────────────────────────
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figmatk",
-  "version": "0.2.6",
+  "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.2.6"
+  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.
@@ -23,7 +37,9 @@ To let the user view the result: tell them to **open the file in Figma Desktop**
 
 | Task | Approach |
 |------|----------|
-| Create a new deck from scratch | **`figmatk_create_deck` MCP tool** — no npm install needed |
+| 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` |
@@ -34,9 +50,58 @@ 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)
+
+Use this path when the user provides a `.deck` template file. The output deck inherits all fonts, colors, spacing, and visual design from the template verbatim.
+
+### Step 1 — Inspect the template
+
+```
+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
+- 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:**
+- 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
+
+```
+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": "The problem.", "body": "Description here." }, images: { "hero_image": "/tmp/problem-photo.jpg" } },
+    { slideId: "1:643", text: { "title": "Thank you!" } }
+  ]
+})
+```
+
+Only pass slots or node IDs that exist in the layout's catalog. Extra keys are silently ignored.
+
 ---
 
-## Path A — Create from Scratch (MCP tool — preferred)
+## Path A — Create from Scratch (MCP tool — no template)
 
 **Always use this path.** No npm install, no scripts, no workspace setup.
 
@@ -211,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
@@ -289,7 +362,7 @@ Every slide needs at least **one visual element** — shape, image, SVG, or tabl
 - Centre body text
 - Use accent lines under slide titles (hallmark of AI-generated slides)
 - Text-only slides
-- Low-contrast text against background
+- Low-contrast text against background — **match image tone to slide palette**: dark/moody images on light-background slides make text unreadable; pick a bright image or switch to a dark-background layout
 - Skip the closing slide — it makes the deck feel unfinished
 - Put long paragraphs in body/caption fields — text overflows the container
 

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"
+  }
+}
+```