openfig-cli 0.3.42 → 0.4.0

package/README.md

@@ -33,6 +33,9 @@ openfig list-overrides deck.deck       # editable override keys per symbol
 openfig export deck.deck               # export slides/frames as PNG
 openfig pdf deck.deck                  # export as multi-page PDF
 
+# Create (.deck only)
+openfig create-deck -o new.deck [--title "Name"] [--layout cover --layout content ...]
+
 # Modify (.deck only)
 openfig update-text deck.deck -o out.deck --slide <id> --set "key=value"
 openfig insert-image deck.deck -o out.deck --slide <id> --key <nodeId> --image <path>
@@ -61,7 +64,7 @@ Plug in Claude Cowork or any coding agent and you have an AI that can read and e
 | High-level API | [docs/api-spec.md](docs/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/) ([canonical source](https://github.com/OpenFig-org/openfig-core/tree/main/docs)) |
+| File format internals | [openfig-core/docs](https://github.com/OpenFig-org/openfig-core/tree/main/docs) |
 
 ## License
 

package/bin/cli.mjs

@@ -5,6 +5,7 @@
  * Usage: openfig <command> <file.deck | file.fig> [args...]
  *
  * Commands:
+ *   create-deck    Create a new .deck file from scratch
  *   inspect        Show document structure (node hierarchy tree)
  *   list-text      List all text content in the deck
  *   list-overrides List all editable override keys per symbol
@@ -21,6 +22,8 @@
  */
 
 const COMMANDS = {
+  'create-deck':    './commands/create-deck.mjs',
+  'convert-html':   './commands/convert-html.mjs',
   'inspect':        './commands/inspect.mjs',
   'list-text':      './commands/list-text.mjs',
   'list-overrides': './commands/list-overrides.mjs',
@@ -40,6 +43,8 @@ if (!arg2 || arg2 === '--help' || arg2 === '-h') {
   console.log(`OpenFig — Open-source tools for Figma file parsing and rendering\n`);
   console.log('Usage: openfig <command> <file.deck | file.fig> [args...]\n');
   console.log('Commands:');
+  console.log('  create-deck    Create a new .deck file from scratch');
+  console.log('  convert-html   Convert a Claude Design standalone HTML export into a .deck');
   console.log('  export         Export slides as images (PNG/JPG/WEBP)');
   console.log('  pdf            Export slides as a multi-page PDF');
   console.log('  inspect        Show document structure (node hierarchy tree)');

package/bin/commands/convert-html.mjs

@@ -0,0 +1,44 @@
+/**
+ * convert-html — Convert a Claude Design standalone HTML export into a .deck file.
+ *
+ * Usage: openfig convert-html <input.html> -o <out.deck> [--title "Name"] [--dry-run]
+ */
+import { statSync } from 'fs';
+import { resolve } from 'path';
+import { convertStandaloneHtml } from '../../lib/slides/html-converter.mjs';
+
+export async function run(args, flags) {
+  const inPath = args[0];
+  const outPath = flags.o || flags.out || flags.output;
+  const dryRun = !!(flags['dry-run'] || flags.dryRun);
+  if (!inPath || (!dryRun && (!outPath || outPath === true))) {
+    console.error('Usage: convert-html <input.html> -o <out.deck> [--title "Name"] [--dry-run]');
+    console.error('  <input.html>  (required)  Claude Design standalone HTML export');
+    console.error('  -o / --out    (required unless --dry-run)  output .deck path');
+    console.error('  --title       (optional)  presentation name (default: inferred from <title>)');
+    console.error('  --dry-run     (optional)  extract geometry only, skip .deck emission');
+    process.exit(1);
+  }
+
+  const title = typeof flags.title === 'string' ? flags.title : undefined;
+  const opts = {};
+  if (title) opts.title = title;
+  if (dryRun) opts.dryRun = true;
+
+  // In dry-run mode there's no .deck output path; pick a scratch-only target
+  // next to the input so the extractor's scratch directory lives somewhere
+  // predictable for inspection.
+  const effectiveOut = outPath && outPath !== true
+    ? outPath
+    : inPath.replace(/\.html?$/i, '') + '.dryrun.deck';
+  const result = await convertStandaloneHtml(inPath, effectiveOut, opts);
+
+  if (dryRun) {
+    console.log(`Dry run: extracted ${result.manifest.slides.length} slide(s); manifest at ${result.scratchDir}/manifest.json`);
+    return;
+  }
+
+  const absolute = resolve(outPath);
+  const bytes = statSync(absolute).size;
+  console.log(`Saved: ${outPath} (${bytes} bytes)`);
+}

package/bin/commands/create-deck.mjs

@@ -0,0 +1,34 @@
+/**
+ * create-deck — Create a new .deck file from scratch.
+ *
+ * Usage: node cli.mjs create-deck -o <out.deck> [--title "Name"] [--layout cover --layout content ...]
+ */
+import { statSync } from 'fs';
+import { resolve } from 'path';
+import { createDraftTemplate } from '../../lib/slides/template-deck.mjs';
+
+export async function run(args, flags) {
+  const outPath = flags.o || flags.out || flags.output;
+  if (!outPath || outPath === true) {
+    console.error('Usage: create-deck -o <out.deck> [--title "Name"] [--layout <name> ...]');
+    console.error('  -o / --out   (required)  output .deck path');
+    console.error('  --title      (optional)  presentation name (default: "Untitled")');
+    console.error('  --layout     (optional, repeatable) layout name(s) for blank slides (default: cover)');
+    process.exit(1);
+  }
+
+  const title = typeof flags.title === 'string' ? flags.title : undefined;
+  const layouts = Array.isArray(flags.layout)
+    ? flags.layout
+    : (flags.layout ? [flags.layout] : undefined);
+
+  await createDraftTemplate(outPath, {
+    ...(title !== undefined ? { title } : {}),
+    ...(layouts ? { layouts } : {}),
+  });
+
+  const absolute = resolve(outPath);
+  const bytes = statSync(absolute).size;
+  const slideCount = layouts ? layouts.length : 1;
+  console.log(`Saved: ${outPath} (${bytes} bytes, ${slideCount} slide${slideCount === 1 ? '' : 's'})`);
+}

package/lib/core/fig-deck.mjs

@@ -10,6 +10,7 @@
  * - Chunk 2+ = optional additional data (pass through as-is)
  */
 import { parseFigBinary } from 'openfig-core';
+import { createEmptyDeckDoc, createPlaceholderThumbnail } from '../slides/empty-deck.mjs';
 import { encodeBinarySchema } from 'kiwi-schema';
 import { deflateRaw } from 'pako';
 import { ZstdCodec } from 'zstd-codec';
@@ -77,6 +78,44 @@ export class FigDeck {
     return deck;
   }
 
+  /**
+   * Create an empty .deck in memory — no seed file, no bundled theme content.
+   * The returned FigDeck has a minimum-viable Slides hierarchy:
+   *   DOCUMENT → CANVAS "Page 1" → SLIDE_GRID "Presentation" → SLIDE_ROW → SLIDE
+   * Plus the auxiliary CANVAS "Internal Only Canvas".
+   */
+  static createEmpty(opts = {}) {
+    const deck = new FigDeck();
+    const doc = createEmptyDeckDoc(opts);
+    // .deck files use the "fig-deck" prelude; createEmptyFigDoc returns
+    // "fig-kiwi" (the .fig Design-file magic). Override for Slides.
+    deck.header = { ...doc.header, prelude: 'fig-deck' };
+    deck.schema = doc.schema;
+    deck.compiledSchema = doc.compiledSchema;
+    deck.message = {
+      ...doc.message,
+      sessionID: doc.message.sessionID ?? 0,
+      ackID: doc.message.ackID ?? 0,
+      blobs: doc.message.blobs ?? [],
+    };
+    deck.rawFiles = doc.rawChunks ?? [];
+    deck.nodeMap = doc.nodeMap;
+    deck.childrenMap = doc.childrenMap;
+    const name = opts.name ?? 'Untitled';
+    deck.deckMeta = {
+      client_meta: {
+        background_color: { r: 0.11764705926179886, g: 0.11764705926179886, b: 0.11764705926179886, a: 1 },
+        thumbnail_size: { width: 400, height: 260 },
+        render_coordinates: { x: 0, y: 0, width: 2400, height: 1560 },
+      },
+      file_name: name,
+      developer_related_links: [],
+      exported_at: new Date().toISOString(),
+    };
+    deck.deckThumbnail = createPlaceholderThumbnail();
+    return deck;
+  }
+
   /**
    * Load from a raw .fig file.
    */

package/lib/rasterizer/svg-builder.mjs

@@ -247,6 +247,59 @@ function resolveLineHeight(lh, fontSize) {
   }
 }
 
+// ── Text width approximation (Inter-like proportional metrics) ──────────────
+//
+// Used only when wrapping text in the fallback layout path (no derivedTextData,
+// e.g. programmatically-generated text). Values are expressed as a fraction of
+// fontSize and tuned for Inter Regular — close enough for word-wrap decisions.
+const _NARROW   = new Set('iIlt.,:;!|\'`"()[]{}/\\'.split(''));
+const _WIDE     = new Set('ABCDEFGHJKLNOPQRSTUVXYZmw'.split(''));
+const _XWIDE    = new Set('MW@%'.split(''));
+function approxCharWidth(ch, fontSize) {
+  if (ch === ' ') return fontSize * 0.28;
+  if (_NARROW.has(ch))  return fontSize * 0.28;
+  if (_XWIDE.has(ch))   return fontSize * 0.85;
+  if (_WIDE.has(ch))    return fontSize * 0.66;
+  return fontSize * 0.52; // default for lowercase + digits + punctuation
+}
+
+function approxTextWidth(str, fontSize, letterSpacingPx = 0) {
+  let w = 0;
+  for (let i = 0; i < str.length; i++) w += approxCharWidth(str[i], fontSize);
+  if (str.length > 1) w += letterSpacingPx * (str.length - 1);
+  return w;
+}
+
+/**
+ * Word-wrap a single line into multiple lines that each fit within maxWidth.
+ * Breaks on ASCII spaces only. If a single "word" overflows maxWidth it is
+ * placed on its own line (no mid-word break).
+ * @param {string} line
+ * @param {number} fontSize
+ * @param {number} maxWidth
+ * @param {number} letterSpacingPx
+ * @returns {string[]}
+ */
+function wrapLineByWidth(line, fontSize, maxWidth, letterSpacingPx = 0) {
+  if (!line) return [line];
+  if (!(maxWidth > 0)) return [line];
+  if (approxTextWidth(line, fontSize, letterSpacingPx) <= maxWidth) return [line];
+  const words = line.split(' ');
+  const out = [];
+  let cur = '';
+  for (const word of words) {
+    const candidate = cur ? cur + ' ' + word : word;
+    if (approxTextWidth(candidate, fontSize, letterSpacingPx) <= maxWidth || !cur) {
+      cur = candidate;
+    } else {
+      out.push(cur);
+      cur = word;
+    }
+  }
+  if (cur) out.push(cur);
+  return out;
+}
+
 function esc(s) {
   return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
@@ -285,14 +338,19 @@ function isStaleLayout(chars, baselines, glyphs) {
  * Auto-scales font size down when new text is longer than the original.
  * Returns { tspans, fontSize } so the caller can use the adjusted size.
  */
-function fallbackTextTspans(dispChars, fontSize, node) {
+function fallbackTextTspans(dispChars, fontSize, node, letterSpacingPx = 0) {
   const baselines = node.derivedTextData?.baselines;
-  const lines = dispChars.split('\n');
+  const rawLines = dispChars.split('\n');
   // Drop trailing empty line from trailing newline
-  if (lines.length > 1 && !lines[lines.length - 1]) lines.pop();
-
-  // Use original baseline metrics for spacing (style property, still valid)
-  let lineHeightPx = baselines?.[0]?.lineHeight ?? fontSize * 1.2;
+  if (rawLines.length > 1 && !rawLines[rawLines.length - 1]) rawLines.pop();
+
+  // Use original baseline metrics for spacing (style property, still valid).
+  // When baselines are absent (programmatically-generated text), honour the
+  // node's own lineHeight (RAW/PERCENT/PIXELS) rather than falling back to
+  // a hard-coded 1.2× multiplier, so hand-authored lineHeight values render
+  // correctly. Ultimate default 1.25× per spec.
+  const lhFromNode = node.lineHeight ? resolveLineHeight(node.lineHeight, fontSize) : null;
+  let lineHeightPx = baselines?.[0]?.lineHeight ?? lhFromNode ?? fontSize * 1.25;
   let lineAscent   = baselines?.[0]?.lineAscent ?? fontSize * 0.8;
 
   // Auto-fit: scale font size down when new text is longer than original.
@@ -303,7 +361,7 @@ function fallbackTextTspans(dispChars, fontSize, node) {
   if (baselines?.length) {
     const maxOrigCharsPerLine = Math.max(...baselines.map(b =>
       Math.max(0, (b.endCharacter ?? 0) - (b.firstCharacter ?? 0))));
-    const maxNewCharsPerLine = Math.max(...lines.map(l => l.length));
+    const maxNewCharsPerLine = Math.max(...rawLines.map(l => l.length));
 
     // Scale down if widest new line has more chars than widest original line
     if (maxNewCharsPerLine > maxOrigCharsPerLine && maxOrigCharsPerLine > 0) {
@@ -311,8 +369,8 @@ function fallbackTextTspans(dispChars, fontSize, node) {
     }
 
     // Also scale down if more lines than original (would overflow vertically)
-    if (lines.length > baselines.length && nodeH > 0) {
-      scale = Math.min(scale, baselines.length / lines.length);
+    if (rawLines.length > baselines.length && nodeH > 0) {
+      scale = Math.min(scale, baselines.length / rawLines.length);
     }
 
     scale = Math.max(scale, 0.15); // don't shrink below 15%
@@ -321,6 +379,7 @@ function fallbackTextTspans(dispChars, fontSize, node) {
   const adjFontSize    = fontSize * scale;
   const adjLineHeight  = lineHeightPx * scale;
   const adjLineAscent  = lineAscent * scale;
+  const adjLetterSpacingPx = letterSpacingPx * scale;
 
   // Horizontal alignment → text-anchor + x position
   const align  = node.textAlignHorizontal ?? 'LEFT';
@@ -336,35 +395,67 @@ function fallbackTextTspans(dispChars, fontSize, node) {
     startY = baselines[0].position.y * scale;
   } else {
     startX = anchorX;
-    const totalH = lines.length * adjLineHeight;
-    const nodeH  = node.size?.y ?? totalH;
     const vAlign = node.textAlignVertical ?? 'TOP';
-    startY = vAlign === 'CENTER' ? (nodeH - totalH) / 2 + adjLineAscent
-           : vAlign === 'BOTTOM' ? nodeH - totalH + adjLineAscent
-           : adjLineAscent;
+    // Placeholder; recomputed below once we know the wrapped line count.
+    startY = adjLineAscent;
+    // Mark that we need to recompute after word-wrap based on final line count
+    // (kept here for readability — actual recompute below).
+    if (vAlign !== 'TOP') startY = null;
   }
 
-  // List marker support: read lineType from textData.lines
+  // Word-wrap each hard-newline-delimited line to fit within the node's width.
+  // Only wrap when the node has an explicit size.x and ≥1 hard line overflows.
+  // Preserves alignment via the outer text-anchor/startX logic.
+  const lineType0 = null;
   const linesMeta = node.textData?.lines ?? [];
+  // Interpret each rawLine and wrap — track (text, metaIndex) for each output line
+  const wrapped = []; // array of { text, metaIndex }
+  for (let i = 0; i < rawLines.length; i++) {
+    const rawLine = rawLines[i];
+    // Reserve horizontal space consumed by list marker + indent on this meta line
+    const meta = linesMeta[i];
+    const indent = (meta?.indentationLevel ?? 0) * adjFontSize * 0.8;
+    const effectiveMaxW = Math.max(0, nodeW - indent);
+    const pieces = wrapLineByWidth(rawLine, adjFontSize, effectiveMaxW, adjLetterSpacingPx);
+    for (const piece of pieces) wrapped.push({ text: piece, metaIndex: i });
+  }
+
+  // Recompute startY for non-TOP vertical alignment now that we know final line count
+  if (startY === null) {
+    const totalH = wrapped.length * adjLineHeight;
+    const nodeHH = node.size?.y ?? totalH;
+    const vAlign = node.textAlignVertical ?? 'TOP';
+    startY = vAlign === 'CENTER' ? (nodeHH - totalH) / 2 + adjLineAscent
+           : vAlign === 'BOTTOM' ? nodeHH - totalH + adjLineAscent
+           : adjLineAscent;
+  }
+
+  // List marker support: read lineType from textData.lines. Only apply marker
+  // to the first visual line of a wrapped paragraph.
   let orderedCounter = 0;
+  let lastMetaIdx = -1;
 
-  const tspans = lines.map((line, i) => {
+  const tspans = wrapped.map(({ text, metaIndex }, i) => {
     const y = startY + i * adjLineHeight;
-    const meta = linesMeta[i];
+    const meta = linesMeta[metaIndex];
     const lineType = meta?.lineType;
     const indent = (meta?.indentationLevel ?? 0) * adjFontSize * 0.8;
     let prefix = '';
-    if (lineType === 'UNORDERED_LIST') {
-      prefix = '\u2022 ';  // bullet •
-      orderedCounter = 0;
-    } else if (lineType === 'ORDERED_LIST') {
-      orderedCounter++;
-      prefix = `${orderedCounter}. `;
-    } else {
-      orderedCounter = 0;
+    const isFirstVisualOfMeta = metaIndex !== lastMetaIdx;
+    if (isFirstVisualOfMeta) {
+      if (lineType === 'UNORDERED_LIST') {
+        prefix = '\u2022 ';  // bullet •
+        orderedCounter = 0;
+      } else if (lineType === 'ORDERED_LIST') {
+        orderedCounter++;
+        prefix = `${orderedCounter}. `;
+      } else {
+        orderedCounter = 0;
+      }
+      lastMetaIdx = metaIndex;
     }
     const x = startX + indent;
-    return `<tspan x="${x.toFixed(2)}" y="${y.toFixed(2)}" text-anchor="${anchor}">${esc(prefix + line) || ' '}</tspan>`;
+    return `<tspan x="${x.toFixed(2)}" y="${y.toFixed(2)}" text-anchor="${anchor}">${esc(prefix + text) || ' '}</tspan>`;
   }).join('');
 
   return { tspans, fontSize: adjFontSize };
@@ -464,7 +555,7 @@ function renderText(deck, node) {
     // Fallback: derivedTextData is stale (text was edited outside Figma).
     // Emit line-level tspans and let resvg handle per-glyph layout.
     const origFontSize = fontSize;
-    const fb = fallbackTextTspans(dispChars, fontSize, node);
+    const fb = fallbackTextTspans(dispChars, fontSize, node, letterSpacingPx);
     tspans = fb.tspans;
     fontSize = fb.fontSize;                              // auto-fit may have scaled down
     if (origFontSize > 0) letterSpacingPx *= fontSize / origFontSize;
@@ -851,11 +942,27 @@ function renderVector(deck, node) {
   const strokeColor = resolveFill(node.strokePaints);
   const sw = node.strokeWeight ?? 0;
   const strokeAlign = node.strokeAlign ?? 'CENTER';
+  const dashAttr = Array.isArray(node.dashPattern) && node.dashPattern.length
+    ? ` stroke-dasharray="${node.dashPattern.join(' ')}"`
+    : '';
+  const lineCap = node.strokeCap === 'ROUND'
+    ? 'round'
+    : node.strokeCap === 'SQUARE'
+    ? 'square'
+    : 'butt';
+  const lineJoin = node.strokeJoin === 'ROUND'
+    ? 'round'
+    : node.strokeJoin === 'BEVEL'
+    ? 'bevel'
+    : 'miter';
 
   if (strokeAlign === 'OUTSIDE' && strokeColor && sw > 0 && fillEntries.length) {
     // Stroke layer underneath (2× width, centered = sw outside + sw inside)
     for (const { d, rule } of fillEntries) {
-      parts.push(`<path d="${d}" fill="none" stroke="${strokeColor}" stroke-width="${sw * 2}" stroke-linejoin="miter"${rule}/>`);
+      parts.push(
+        `<path d="${d}" fill="none" stroke="${strokeColor}" stroke-width="${sw * 2}" ` +
+        `stroke-linecap="${lineCap}" stroke-linejoin="${lineJoin}"${dashAttr}${rule}/>`
+      );
     }
     // Fill layer on top — covers inner half of stroke
     for (const { d, color, rule } of fillEntries) {
@@ -886,8 +993,15 @@ function renderVector(deck, node) {
   if (!parts.length && node.vectorData?.vectorNetworkBlob != null && blobs) {
     const vnbD = decodeVnb(blobs, node.vectorData.vectorNetworkBlob, node.vectorData.normalizedSize, node.size);
     if (vnbD) {
-      const color = fillColor ?? resolveFill(node.strokePaints) ?? '#000000';
-      parts.push(`<path d="${vnbD}" fill="${color}" fill-rule="evenodd"/>`);
+      if (!fillColor && strokeColor && sw > 0) {
+        parts.push(
+          `<path d="${vnbD}" fill="none" stroke="${strokeColor}" stroke-width="${sw}" ` +
+          `stroke-linecap="${lineCap}" stroke-linejoin="${lineJoin}"${dashAttr}/>`
+        );
+      } else {
+        const color = fillColor ?? strokeColor ?? '#000000';
+        parts.push(`<path d="${vnbD}" fill="${color}" fill-rule="evenodd"/>`);
+      }
     }
   }
 
@@ -1030,6 +1144,17 @@ function decodeVnb(blobs, blobIdx, normalizedSize, nodeSize) {
     segs.push({ sv, tsx, tsy, ev, tex, tey, type });
   }
 
+  const segToPathCmd = (seg, start, end) => {
+    if (seg.type === 0) {
+      return `L${f(end.x)},${f(end.y)}`;
+    }
+    const c1x = start.x + seg.tsx;
+    const c1y = start.y + seg.tsy;
+    const c2x = end.x + seg.tex;
+    const c2y = end.y + seg.tey;
+    return `C${f(c1x)},${f(c1y)} ${f(c2x)},${f(c2y)} ${f(end.x)},${f(end.y)}`;
+  };
+
   // Parse regions → build SVG paths
   const cmds = [];
   for (let r = 0; r < numRegions; r++) {
@@ -1049,23 +1174,38 @@ function decodeVnb(blobs, blobIdx, normalizedSize, nodeSize) {
 
         if (s === 0) cmds.push(`M${f(start.x)},${f(start.y)}`);
 
-        if (seg.type === 0) {
-          // Line
-          cmds.push(`L${f(end.x)},${f(end.y)}`);
-        } else {
-          // Cubic bezier — tangents are relative to their vertex
-          const c1x = start.x + seg.tsx;
-          const c1y = start.y + seg.tsy;
-          const c2x = end.x + seg.tex;
-          const c2y = end.y + seg.tey;
-          cmds.push(`C${f(c1x)},${f(c1y)} ${f(c2x)},${f(c2y)} ${f(end.x)},${f(end.y)}`);
-        }
+        cmds.push(segToPathCmd(seg, start, end));
       }
       cmds.push('Z');
     }
     off += 4; // windingRule
   }
 
+  // Stroke-only vectors authored with addPath() intentionally omit regions.
+  // Recover their centerline by walking the stored segments in order so they
+  // render as strokes instead of falling through to the magenta placeholder.
+  if (!cmds.length && segs.length) {
+    let currentEnd = null;
+    let subpathStart = null;
+    for (const seg of segs) {
+      const start = verts[seg.sv];
+      const end = verts[seg.ev];
+      if (!start || !end) continue;
+      if (currentEnd == null || seg.sv !== currentEnd) {
+        cmds.push(`M${f(start.x)},${f(start.y)}`);
+        subpathStart = seg.sv;
+      }
+      cmds.push(segToPathCmd(seg, start, end));
+      if (subpathStart != null && seg.ev === subpathStart) {
+        cmds.push('Z');
+        currentEnd = null;
+        subpathStart = null;
+      } else {
+        currentEnd = seg.ev;
+      }
+    }
+  }
+
   return cmds.length ? cmds.join('') : null;
 }