figmatk 0.3.1 → 0.3.7

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/README.md

@@ -21,7 +21,7 @@ Figma Slides lets you download presentations as `.deck` files and re-upload them
 
 FigmaTK makes this round-trip programmable. Download a `.deck`, modify it, re-upload. Everything stays native.
 
-Plug in [Claude Code](https://claude.ai/code) or any coding agent and you have an AI that can read and edit Figma presentations end-to-end — without ever opening the Figma UI.
+Plug in Claude Cowork or any coding agent and you have an AI that can read and edit Figma presentations end-to-end — without ever opening the Figma UI.
 
 ## Use Cases
 
@@ -48,26 +48,48 @@ figmatk list-overrides my-presentation.deck # editable fields per symbol
 
 → Full CLI reference: [docs/cli.md](docs/cli.md)
 
-## Claude Code / MCP Integration
+## Claude Cowork / MCP Integration
 
-FigmaTK ships as a **Cowork plugin** with an MCP server — Claude can manipulate `.deck` files directly as tool calls.
+FigmaTK supports two Claude Cowork install paths:
+
+- GitHub-backed personal plugin install, which preserves Claude Cowork's repo update-check behavior
+- Local `.mcpb` bundle install, which matches Anthropic's current desktop-extension packaging model
+
+### Option 1 — Install from GitHub in Claude Cowork
+
+If you want Claude Cowork to keep checking the repo for updates, install `figmatk` from GitHub/personal plugins inside Claude Cowork.
+
+That path uses the checked-in [plugin.json](/Users/rob/Dev/figmatk/.claude-plugin/plugin.json) and [marketplace.json](/Users/rob/Dev/figmatk/.claude-plugin/marketplace.json) metadata.
+
+### Option 2 — Install the local MCPB bundle
+
+Build the extension bundle:
 
 ```bash
-claude plugin marketplace add rcoenen/figmatk
-claude plugin install figmatk
+npm install
+npm run pack
 ```
 
-Or add manually in Claude Desktop → Settings → Developer → Edit Config:
+This creates `dist/figmatk.mcpb`. Install that bundle from Claude Desktop/Cowork's Extensions UI.
 
-```json
-{
-  "mcpServers": {
-    "figmatk": { "command": "figmatk-mcp" }
-  }
-}
-```
+Install in Claude Cowork:
+
+1. Open Claude Cowork or Claude Desktop.
+2. Go to `Settings`.
+3. Open `Extensions`.
+4. Choose the local install/add option.
+5. Select `dist/figmatk.mcpb`.
+
+Use this path when you want a local extension artifact. Unlike the GitHub-backed personal plugin path, local `.mcpb` installs do not poll the repo for updates automatically.
 
-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`.
+The MCP server covers four high-level workflows:
+
+- create a new deck from scratch
+- author a reusable Slides template
+- instantiate a new deck from a template
+- inspect or edit an existing deck
+
+→ MCP tool reference: [docs/mcp.md](docs/mcp.md)
 
 ## Template Workflows
 
@@ -76,14 +98,9 @@ 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>`
+Reusable template authoring is built around explicit layout and slot naming, then a publish-like wrapping step before later instantiation.
 
-`figmatk_list_template_layouts` understands those conventions and only falls back to heuristic image placeholders when a layout has not been explicitly annotated yet.
+→ Template workflow guide: [docs/template-workflows.md](docs/template-workflows.md)
 
 ## Programmatic API
 
@@ -98,6 +115,7 @@ await deck.save('output.deck');
 
 | Docs | |
 |------|---|
+| MCP / Claude workflows | [docs/mcp.md](docs/mcp.md) |
 | 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) |

package/cli.mjs

@@ -24,6 +24,7 @@ const COMMANDS = {
   'clone-slide':    './commands/clone-slide.mjs',
   'remove-slide':   './commands/remove-slide.mjs',
   'roundtrip':      './commands/roundtrip.mjs',
+  'render':         './commands/render.mjs',
 };
 
 const command = process.argv[2];
@@ -39,6 +40,7 @@ if (!command || command === '--help' || command === '-h') {
   console.log('  clone-slide    Duplicate a template slide with new content');
   console.log('  remove-slide   Mark slides as REMOVED');
   console.log('  roundtrip      Decode and re-encode (pipeline validation)');
+  console.log('  render         Rasterize slides to PNG');
   console.log('\nUsage: figmatk <command> [args...]');
   process.exit(0);
 }

package/commands/render.mjs

@@ -0,0 +1,56 @@
+/**
+ * render — Rasterize slides in a .deck file to PNG.
+ *
+ * Usage:
+ *   figmatk render <file.deck> -o <output-dir> [options]
+ *
+ * Options:
+ *   -o <dir>        Output directory (default: ./render-out)
+ *   --slide <n>     Render only slide N (1-based). Omit to render all.
+ *   --scale <n>     Zoom factor: 1 = 1920×1080, 0.5 = 960×540 (default: 1)
+ *   --width <px>    Output width in pixels (height scales proportionally)
+ *   --fonts <dir>   Extra font directory to load (can repeat)
+ */
+
+import { mkdirSync, writeFileSync } from 'fs';
+import { join, resolve } from 'path';
+import { FigDeck } from '../lib/fig-deck.mjs';
+import { renderDeck, registerFontDir } from '../lib/rasterizer/deck-rasterizer.mjs';
+import { resolveFonts } from '../lib/rasterizer/font-resolver.mjs';
+
+export async function run(args, flags) {
+  const file = args[0];
+  if (!file) {
+    console.error('Usage: render <file.deck> -o <output-dir> [--slide N] [--scale 0.5] [--width 400] [--fonts <dir>]');
+    process.exit(1);
+  }
+
+  const outDir = resolve(flags.o ?? flags.output ?? './render-out');
+
+  // Build render options
+  const renderOpts = {};
+  if (flags.width) renderOpts.width = parseInt(flags.width);
+  else if (flags.scale) renderOpts.scale = parseFloat(flags.scale);
+
+  // Load extra font directories
+  const fontDirs = [].concat(flags.fonts ?? []);
+  for (const d of fontDirs) registerFontDir(resolve(d));
+
+  const deck = await FigDeck.fromDeckFile(file);
+  await resolveFonts(deck, { quiet: false });
+  mkdirSync(outDir, { recursive: true });
+
+  // Filter to single slide if requested
+  const slideFilter = flags.slide ? parseInt(flags.slide) : null;
+  const slides = await renderDeck(deck, renderOpts);
+
+  for (const { index, slideId, png } of slides) {
+    if (slideFilter && index + 1 !== slideFilter) continue;
+    const outFile = join(outDir, `slide-${String(index + 1).padStart(3, '0')}.png`);
+    writeFileSync(outFile, png);
+    console.log(`  slide ${index + 1}  →  ${outFile}`);
+  }
+
+  const count = slideFilter ? 1 : slides.length;
+  console.log(`\nRendered ${count} slide(s) to ${outDir}`);
+}

package/lib/rasterizer/deck-rasterizer.mjs

@@ -0,0 +1,228 @@
+/**
+ * deck-rasterizer.mjs — Render FigDeck slides to PNG via WASM (resvg).
+ *
+ * WASM is initialized once per process. Fonts are loaded at init time and
+ * can be hot-plugged via registerFont() before or after initialization.
+ *
+ * Usage:
+ *   import { renderDeck, registerFont } from './deck-rasterizer.mjs';
+ *   await registerFont('/path/to/CustomFont.ttf');
+ *   const pngs = await renderDeck(deck);  // Map<slideIndex, Uint8Array>
+ */
+
+import { readFileSync, readdirSync, statSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { initWasm, Resvg } from '@resvg/resvg-wasm';
+import { slideToSvg } from './svg-builder.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const WASM_PATH = join(__dirname, '../../node_modules/@resvg/resvg-wasm/index_bg.wasm');
+
+// ── Font registry ─────────────────────────────────────────────────────────────
+
+/**
+ * Try to load a font file from a path — returns Buffer or null (never throws).
+ * Tries the given path variants in order, returning the first that exists.
+ */
+function tryFont(...paths) {
+  for (const p of paths) {
+    try { return readFileSync(p); } catch { /* not found */ }
+  }
+  return null;
+}
+
+/**
+ * Load all available weights of a font from @fontsource, trying WOFF2 then TTF.
+ * Silently skips missing files/packages.
+ * @param {string} pkg  e.g. '@fontsource/darker-grotesque'
+ * @param {string} slug e.g. 'darker-grotesque'
+ * @param {number[]} weights e.g. [400, 500, 600, 700]
+ */
+function tryFontsourceFamily(pkg, slug, weights = [400, 500, 600, 700]) {
+  const base = join(__dirname, `../../node_modules/${pkg}/files`);
+  const bufs = [];
+  for (const w of weights) {
+    const buf = tryFont(
+      `${base}/${slug}-latin-${w}-normal.woff2`,
+      `${base}/${slug}-latin-${w}-normal.woff`,
+      `${base}/${slug}-latin-${w}-normal.ttf`,
+      `${base}/${slug}-all-${w}-normal.woff2`,
+    );
+    if (buf) bufs.push(buf);
+  }
+  return bufs;
+}
+
+// ── Inter font loading with version warning ────────────────────────────────────
+//
+// Figma bundles Inter v3.015 (variable font, wght+slnt axes) inside its app.
+// @fontsource/inter ships v4.x — italic glyph shapes (e.g. "a") differ visibly.
+//
+// Run  node lib/rasterizer/extract-figma-fonts.mjs  once to generate the v3
+// static WOFF2 files in lib/rasterizer/fonts/inter-v3-*.woff2.
+//
+// KNOWN_FIGMA_INTER_VERSION is the nameID 5 string from Figma's bundled font.
+const KNOWN_FIGMA_INTER_VERSION = 'Version 3.015;git-7f5c04026';
+
+function loadInterFonts() {
+  const v3Meta = join(__dirname, 'fonts/inter-v3-meta.json');
+  const v3Instances = ['400-normal', '500-normal', '600-normal', '700-normal', '400-italic', '700-italic'];
+  const bufs = v3Instances.map(s => tryFont(join(__dirname, `fonts/inter-v3-${s}.woff2`))).filter(Boolean);
+
+  if (bufs.length === v3Instances.length) {
+    // All v3 static fonts present — check version matches expectation
+    try {
+      const meta = JSON.parse(readFileSync(v3Meta, 'utf8'));
+      if (meta.version !== KNOWN_FIGMA_INTER_VERSION) {
+        process.stderr.write(
+          `[figmatk] Inter version warning: fonts/inter-v3-*.woff2 reports "${meta.version}", ` +
+          `expected "${KNOWN_FIGMA_INTER_VERSION}". Renders may differ.\n`
+        );
+      }
+    } catch { /* meta missing — skip version check */ }
+    return bufs;
+  }
+
+  // Fallback: @fontsource/inter (v4.x)
+  process.stderr.write(
+    `[figmatk] Inter version warning: Figma uses Inter "${KNOWN_FIGMA_INTER_VERSION}" but ` +
+    `local v3 fonts not found. Falling back to @fontsource/inter (v4.x) — ` +
+    `italic glyphs (e.g. "a") may differ. ` +
+    `Run: node lib/rasterizer/extract-figma-fonts.mjs\n`
+  );
+  return [
+    ...tryFontsourceFamily('@fontsource/inter', 'inter', [400, 500, 600, 700]),
+    ...['400', '700'].flatMap(w => {
+      const buf = tryFont(join(__dirname, `../../node_modules/@fontsource/inter/files/inter-latin-${w}-italic.woff2`));
+      return buf ? [buf] : [];
+    }),
+  ];
+}
+
+const fontBuffers = [
+  ...loadInterFonts(),
+  // Darker Grotesque — patched WOFF2 with family name "Darker Grotesque" so resvg can match it
+  ...['400', '500', '600', '700'].flatMap(w => {
+    const buf = tryFont(join(__dirname, `fonts/darker-grotesque-patched-${w}-normal.woff2`));
+    return buf ? [buf] : [];
+  }),
+  // Irish Grover — internal name already matches, load directly from @fontsource
+  ...tryFontsourceFamily('@fontsource/irish-grover', 'irish-grover', [400]),
+];
+
+/**
+ * Register an additional font for rendering.
+ * Can be called at any time — takes effect on the next render call.
+ * @param {string|Buffer|Uint8Array} source  File path or raw buffer.
+ */
+export function registerFont(source) {
+  const buf = typeof source === 'string'
+    ? readFileSync(source)
+    : Buffer.isBuffer(source) ? source : Buffer.from(source);
+  fontBuffers.push(buf);
+}
+
+/**
+ * Register all fonts in a directory (recursively scans .ttf/.otf/.woff/.woff2).
+ * Call this before rendering if slides use custom fonts.
+ * @param {string} dir  Directory path to scan.
+ */
+export function registerFontDir(dir) {
+  const scan = (d) => {
+    for (const entry of readdirSync(d)) {
+      const full = join(d, entry);
+      if (statSync(full).isDirectory()) { scan(full); continue; }
+      if (/\.(ttf|otf|woff2?)$/i.test(entry)) registerFont(full);
+    }
+  };
+  scan(dir);
+}
+
+// ── WASM init (lazy, once) ────────────────────────────────────────────────────
+
+let wasmReady = false;
+let wasmInitPromise = null;
+
+async function ensureWasm() {
+  if (wasmReady) return;
+  if (!wasmInitPromise) {
+    wasmInitPromise = initWasm(readFileSync(WASM_PATH)).then(() => {
+      wasmReady = true;
+    });
+  }
+  await wasmInitPromise;
+}
+
+// ── Core render ───────────────────────────────────────────────────────────────
+
+const SLIDE_W = 1920;
+const SLIDE_H = 1080;
+
+const DEFAULT_OPTS = {
+  scale: 1,          // 1 = 1920×1080, 0.5 = 960×540 — capped at 1
+  background: '#ffffff',
+};
+
+/**
+ * Resolve scale from opts. Accepts:
+ *   scale (float)   — direct multiplier, capped at 1
+ *   width (px)      — fit to width, preserving aspect ratio
+ *   height (px)     — fit to height, preserving aspect ratio
+ * Never upscales beyond native 1920×1080.
+ */
+function resolveScale(opts) {
+  if (opts.width)  return opts.width  / SLIDE_W;
+  if (opts.height) return opts.height / SLIDE_H;
+  return opts.scale ?? 1;
+}
+
+/**
+ * Render a single SVG string to PNG.
+ * @param {string} svg
+ * @param {object} opts
+ * @returns {Promise<Uint8Array>} PNG bytes
+ */
+export async function svgToPng(svg, opts = {}) {
+  await ensureWasm();
+  const { background } = { ...DEFAULT_OPTS, ...opts };
+  const scale = resolveScale(opts);
+
+  const resvg = new Resvg(svg, {
+    background,
+    fitTo: scale !== 1 ? { mode: 'zoom', value: scale } : { mode: 'original' },
+    font: {
+      fontBuffers: fontBuffers.map(b => new Uint8Array(b)),
+      loadSystemFonts: false,
+      sansSerifFamily: 'Inter',
+      defaultFontFamily: 'Inter',
+    },
+  });
+
+  const rendered = resvg.render();
+  const png = rendered.asPng();
+  rendered.free();
+  resvg.free();
+  return png;
+}
+
+/**
+ * Render all active slides in a deck to PNG.
+ * @param {import('../fig-deck.mjs').FigDeck} deck
+ * @param {object} opts
+ * @param {number} [opts.scale=1]  Zoom factor (e.g. 0.5 for thumbnails)
+ * @returns {Promise<Array<{index: number, slideId: string, png: Uint8Array}>>}
+ */
+export async function renderDeck(deck, opts = {}) {
+  const slides = deck.getActiveSlides();
+  const results = [];
+  for (let i = 0; i < slides.length; i++) {
+    const slide = slides[i];
+    const svg = slideToSvg(deck, slide);
+    const png = await svgToPng(svg, opts);
+    results.push({ index: i, slideId: slide.guid
+      ? `${slide.guid.sessionID}:${slide.guid.localID}`
+      : String(i), png });
+  }
+  return results;
+}

package/lib/rasterizer/download-font.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * font-helper — Install fonts from @fontsource and register with the rasterizer.
+ *
+ * resvg-wasm accepts WOFF2 directly — no conversion needed.
+ *
+ * Usage:
+ *   node lib/rasterizer/download-font.mjs "Darker Grotesque" 500 600
+ *   node lib/rasterizer/download-font.mjs "Inter" 400 700
+ *
+ * What it does:
+ *   1. npm install @fontsource/<family> (if not already installed)
+ *   2. Prints the registerFont() calls to add to deck-rasterizer.mjs
+ */
+
+import { existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT      = join(__dirname, '../..');
+
+const [,, familyArg, ...weightArgs] = process.argv;
+if (!familyArg) {
+  console.error('Usage: node download-font.mjs "Family Name" [weight...]\n');
+  console.error('  node download-font.mjs "Darker Grotesque" 500 600');
+  process.exit(1);
+}
+
+const weights   = weightArgs.length ? weightArgs.map(Number) : [400];
+const family    = familyArg.trim();
+const pkgSlug   = family.toLowerCase().replace(/\s+/g, '-');
+const pkgName   = `@fontsource/${pkgSlug}`;
+const pkgDir    = join(ROOT, 'node_modules', pkgName, 'files');
+
+if (!existsSync(pkgDir)) {
+  console.log(`Installing ${pkgName}…`);
+  execSync(`npm install ${pkgName} --save-dev`, { cwd: ROOT, stdio: 'inherit' });
+}
+
+if (!existsSync(pkgDir)) {
+  console.error(`${pkgName} not found after install.`);
+  process.exit(1);
+}
+
+console.log(`\n✓ ${pkgName} ready. Add to deck-rasterizer.mjs fontBuffers:\n`);
+for (const w of weights) {
+  const file = `${pkgSlug}-latin-${w}-normal.woff2`;
+  const full = join(pkgDir, file);
+  if (existsSync(full)) {
+    const rel = full.replace(ROOT + '/', '');
+    console.log(`  readFileSync(join(ROOT, '${rel}')),  // ${family} ${w}`);
+  } else {
+    console.warn(`  ⚠ not found: ${file}`);
+  }
+}