openfig-cli 0.3.41 → 0.4.0

package/lib/slides/api.mjs

@@ -18,6 +18,7 @@ import { imageOv, hexToHash } from '../core/image-helpers.mjs';
 import { deepClone } from '../core/deep-clone.mjs';
 import { readFileSync, writeFileSync, copyFileSync, existsSync, mkdirSync } from 'fs';
 import { createHash } from 'crypto';
+import { tmpdir } from 'os';
 import { join, resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 
@@ -53,12 +54,11 @@ export class Deck {
    * @returns {Promise<Deck>}
    */
   static async create(opts = {}) {
-    const templatePath = join(__dirname, 'blank-template.deck');
-    const fd = await FigDeck.fromDeckFile(templatePath);
-    fd.deckMeta = { file_name: opts.name ?? 'Untitled', version: '1' };
+    const fd = FigDeck.createEmpty({ name: opts.name ?? 'Untitled' });
     const deck = new Deck(fd, null);
-    // Remember the template's blank slide so addBlankSlide() can auto-remove it
-    deck._templateSlide = fd.getActiveSlides().length ? fd.getSlide(1) : null;
+    // The zero-seed document ships with exactly one blank SLIDE; remember it
+    // so the first addBlankSlide()/addSlide() call can clear the placeholder.
+    deck._templateSlide = fd.getActiveSlides()[0] ?? null;
     return deck;
   }
 
@@ -122,7 +122,8 @@ export class Deck {
   addBlankSlide(opts = {}) {
     const fd = this._fd;
 
-    // Clone structure from the first slide
+    // Clone structure from the first slide (before placeholder deletion —
+    // we still need it as the structural template).
     const templateSlide = fd.getActiveSlides()[0];
     if (!templateSlide) throw new Error('No slides to clone structure from');
 
@@ -130,6 +131,24 @@ export class Deck {
       ? `${templateSlide.parentIndex.guid.sessionID}:${templateSlide.parentIndex.guid.localID}`
       : null;
 
+    // Clear the zero-seed placeholder on the first real slide insertion.
+    // Must happen BEFORE activeCount is read, or the placeholder inflates
+    // the count and the first real slide ends up in slot 2.
+    // The placeholder is fully removed rather than flagged `phase: REMOVED`
+    // so the saved document contains no stale-node entries.
+    if (this._templateSlide) {
+      const toDrop = new Set();
+      toDrop.add(nid(this._templateSlide));
+      for (const child of fd.getChildren(nid(this._templateSlide))) {
+        toDrop.add(nid(child));
+      }
+      fd.message.nodeChanges = fd.message.nodeChanges.filter(
+        (n) => !toDrop.has(`${n.guid.sessionID}:${n.guid.localID}`),
+      );
+      this._templateSlide = null;
+      fd.rebuildMaps();
+    }
+
     const localID = fd.maxLocalID() + 1;
     const activeCount = fd.getActiveSlides().length;
 
@@ -166,18 +185,6 @@ export class Deck {
     fd.message.nodeChanges.push(newSlide);
     fd.rebuildMaps();
 
-    // Auto-remove the original template blank slide on first addBlankSlide() call
-    if (this._templateSlide) {
-      this._templateSlide.phase = 'REMOVED';
-      // Also remove children (e.g. FRAME nodes) of the template slide
-      const templateChildren = fd.getChildren(nid(this._templateSlide));
-      for (const child of templateChildren) {
-        child.phase = 'REMOVED';
-      }
-      this._templateSlide = null;
-      fd.rebuildMaps();
-    }
-
     const slide = new Slide(fd, newSlide);
 
     if (opts.background) {
@@ -210,6 +217,21 @@ export class Deck {
 
     const templateInst = fd.getSlideInstance(nid(templateSlide));
 
+    // Auto-remove zero-seed placeholder on first add. Must happen before
+    // activeCount is read (see addBlankSlide for rationale).
+    if (this._templateSlide) {
+      const toDrop = new Set();
+      toDrop.add(nid(this._templateSlide));
+      for (const child of fd.getChildren(nid(this._templateSlide))) {
+        toDrop.add(nid(child));
+      }
+      fd.message.nodeChanges = fd.message.nodeChanges.filter(
+        (n) => !toDrop.has(`${n.guid.sessionID}:${n.guid.localID}`),
+      );
+      this._templateSlide = null;
+      fd.rebuildMaps();
+    }
+
     const slideRowId = templateSlide.parentIndex?.guid
       ? `${templateSlide.parentIndex.guid.sessionID}:${templateSlide.parentIndex.guid.localID}`
       : null;
@@ -246,8 +268,8 @@ export class Deck {
       newSlide.transform.m02 = activeCount * 2160;
     }
 
-    // Build the INSTANCE node — clone from existing INSTANCE or construct from
-    // scratch when the template SLIDE has a FRAME child instead (e.g. blank-template.deck).
+    // Build the INSTANCE node — clone from an existing INSTANCE if the deck
+    // already has one, otherwise construct a bare INSTANCE from scratch.
     let newInst;
     if (templateInst) {
       newInst = deepClone(templateInst);
@@ -342,6 +364,30 @@ export class Slide {
   get guid() { return nid(this._node); }
   get index() { return this._fd.getActiveSlides().indexOf(this._node); }
 
+  // --- Speaker notes --------------------------------------------------------
+
+  /**
+   * Set the speaker notes for this slide.
+   *
+   * Figma stores speaker notes as a Lexical editor state JSON string on the
+   * SLIDE node's `slideSpeakerNotes` field, NOT plain text. Writing a raw
+   * plain-text string here produces a .deck file that Figma refuses to import
+   * ("Something went wrong..."), because the importer unconditionally parses
+   * the field as Lexical JSON. We wrap the caller's plain text into a minimal
+   * Lexical tree (one paragraph per `\n`-delimited line).
+   */
+  setSpeakerNotes(text) {
+    this._node.slideSpeakerNotes = _plainToLexical(text ?? '');
+    return this;
+  }
+
+  /**
+   * Get the speaker notes for this slide as plain text (Lexical → plain).
+   */
+  getSpeakerNotes() {
+    return _lexicalToPlain(this._node.slideSpeakerNotes ?? '');
+  }
+
   // --- Shape access ----------------------------------------------------------
 
   /**
@@ -502,12 +548,12 @@ export class Slide {
 
     const { width, height } = await getImageDimensions(imgBuf);
 
-    const tmpThumb = `/tmp/openfig_thumb_${Date.now()}.png`;
+    const tmpThumb = join(tmpdir(), `openfig_thumb_${Date.now()}.png`);
     await generateThumbnail(imgBuf, tmpThumb);
     const thumbHash = sha1Hex(readFileSync(tmpThumb));
 
     copyToImagesDir(this._fd, imgHash, imgPath ?? (() => {
-      const tmp = `/tmp/openfig_img_${Date.now()}`;
+      const tmp = join(tmpdir(), `openfig_img_${Date.now()}`);
       writeFileSync(tmp, imgBuf);
       return tmp;
     })());
@@ -597,6 +643,12 @@ export class Slide {
     const fd = this._fd;
     const localID = fd.maxLocalID() + 1;
     const fill = parseColor(fd, opts.fill ?? 'White');
+    const strokeColor = opts.stroke ? parseColor(fd, opts.stroke) : null;
+    const strokePaints = strokeColor ? [{
+      type: 'SOLID',
+      color: { r: strokeColor.r, g: strokeColor.g, b: strokeColor.b, a: strokeColor.a ?? 1 },
+      opacity: 1, visible: true, blendMode: 'NORMAL',
+    }] : [];
 
     const node = {
       guid: { sessionID: 1, localID },
@@ -611,9 +663,11 @@ export class Slide {
       opacity: opts.opacity ?? 1,
       size: { x: width, y: height },
       transform: { m00: 1, m01: 0, m02: x, m10: 0, m11: 1, m12: y },
-      strokeWeight: 1,
-      strokeAlign: 'INSIDE',
+      strokeWeight: opts.strokeWeight ?? (strokeColor ? 1 : 0),
+      strokeAlign: opts.strokeAlign ?? 'INSIDE',
       strokeJoin: 'MITER',
+      strokePaints,
+      ...(opts.dashPattern ? { dashPattern: opts.dashPattern } : {}),
       ...(opts.cornerRadius ? {
         cornerRadius: opts.cornerRadius,
         rectangleTopLeftCornerRadius: opts.cornerRadius,
@@ -670,7 +724,7 @@ export class Slide {
     const { width: origW, height: origH } = await getImageDimensions(imgBuf);
 
     // Generate thumbnail
-    const tmpThumb = `/tmp/openfig_thumb_${Date.now()}.png`;
+    const tmpThumb = join(tmpdir(), `openfig_thumb_${Date.now()}.png`);
     await generateThumbnail(imgBuf, tmpThumb);
     const thumbHash = sha1Hex(readFileSync(tmpThumb));
 
@@ -678,7 +732,7 @@ export class Slide {
     if (imgPath) {
       copyToImagesDir(fd, imgHash, imgPath);
     } else {
-      const tmpImg = `/tmp/openfig_img_${Date.now()}`;
+      const tmpImg = join(tmpdir(), `openfig_img_${Date.now()}`);
       writeFileSync(tmpImg, imgBuf);
       copyToImagesDir(fd, imgHash, tmpImg);
     }
@@ -810,11 +864,18 @@ export class Slide {
       styleIdForText = { guid: deepClone(styleDef.guid) };
     } else {
       // Detached or no style — explicit fields
-      fontName = {
-        family: opts.font ?? 'Inter',
-        style: opts.fontStyle ?? 'Regular',
-        postscript: '',
-      };
+      const family = opts.font ?? 'Inter';
+      const style = opts.fontStyle ?? 'Regular';
+      // Figma's font resolver appears to match on (family, postscript) together.
+      // Empty postscript triggers substitution to a fallback even when the
+      // requested family is available (e.g. via Figma's Google Fonts
+      // integration). Synthesize a conventional PostScript name — this matches
+      // what Figma-authored files emit for standard Google Fonts (Inter-Bold,
+      // EBGaramond-Regular, etc.). Callers can pass `opts.postscript`
+      // explicitly to override.
+      const psName = opts.postscript
+        ?? family.replace(/\s+/g, '') + '-' + style.replace(/\s+/g, '');
+      fontName = { family, style, postscript: psName };
       fontSize = opts.fontSize ?? 36;
       lineHeight = { value: 1.4, units: 'RAW' };
       letterSpacing = { value: 0, units: 'PERCENT' };
@@ -827,12 +888,34 @@ export class Slide {
       fontSize = opts.fontSize;
     }
 
+    // Optional letterSpacing override: number (pixels) or raw { value, units }
+    if (opts.letterSpacing !== undefined) {
+      if (typeof opts.letterSpacing === 'number') {
+        letterSpacing = { value: opts.letterSpacing, units: 'PIXELS' };
+      } else {
+        letterSpacing = opts.letterSpacing;
+      }
+    }
+
+    // Optional lineHeight override: number → MULTIPLE (if <10) or PIXELS; or raw { value, units }
+    if (opts.lineHeight !== undefined) {
+      if (typeof opts.lineHeight === 'number') {
+        if (opts.lineHeight < 10) {
+          lineHeight = { value: opts.lineHeight, units: 'RAW' };
+        } else {
+          lineHeight = { value: opts.lineHeight, units: 'PIXELS' };
+        }
+      } else {
+        lineHeight = opts.lineHeight;
+      }
+    }
+
     const chars = (fullText === '' || fullText == null) ? ' ' : fullText;
     const textData = { characters: chars };
 
     // Build per-run formatting overrides
-    if (isRuns && textOrRuns.some(r => r.bold || r.italic || r.underline || r.strikethrough || r.hyperlink)) {
-      const overrides = buildRunOverrides(textOrRuns, fontName, styleIdForText);
+    if (isRuns && textOrRuns.some(r => r.bold || r.italic || r.underline || r.strikethrough || r.hyperlink || r.color)) {
+      const overrides = buildRunOverrides(textOrRuns, fontName, styleIdForText, fd);
       textData.styleOverrideTable = overrides.styleOverrideTable;
       textData.characterStyleIDs = overrides.characterStyleIDs;
     }
@@ -855,9 +938,8 @@ export class Slide {
       type: 'TEXT',
       name: opts.name ?? 'Text',
       visible: true,
-      opacity: 1,
+      opacity: opts.opacity ?? 1,
       size: { x: opts.width ?? 1200, y: opts.height ?? 50 },
-      textAutoResize: opts.height ? 'NONE' : 'HEIGHT',
       transform: {
         m00: 1, m01: 0, m02: opts.x ?? 128,
         m10: 0, m11: 1, m12: opts.y ?? 128,
@@ -868,9 +950,21 @@ export class Slide {
       lineHeight,
       letterSpacing,
       textTracking,
-      textAutoResize: 'HEIGHT',
+      textAutoResize:
+        opts.autoresize === 'WIDTH_AND_HEIGHT'
+          ? 'WIDTH_AND_HEIGHT'
+          : opts.autoresize === 'HEIGHT'
+          ? 'HEIGHT'
+          : opts.autoresize === 'NONE'
+          ? 'NONE'
+          : opts.height
+          ? 'NONE'
+          : 'HEIGHT',
       textAlignHorizontal: opts.align ?? 'LEFT',
-      textAlignVertical: 'TOP',
+      textAlignVertical:
+        opts.verticalAlign === 'CENTER' || opts.verticalAlign === 'BOTTOM'
+          ? opts.verticalAlign
+          : 'TOP',
       styleIdForText,
       fillPaints: [{
         type: 'SOLID',
@@ -951,6 +1045,12 @@ export class Slide {
       color: { r: 0, g: 0, b: 0, a: 1 },
       opacity: 1, visible: true, blendMode: 'NORMAL',
     };
+    const strokeColor = opts.stroke ? parseColor(fd, opts.stroke) : null;
+    const strokePaint = strokeColor ? {
+      type: 'SOLID',
+      color: { r: strokeColor.r, g: strokeColor.g, b: strokeColor.b, a: strokeColor.a ?? 1 },
+      opacity: 1, visible: true, blendMode: 'NORMAL',
+    } : null;
 
     const node = {
       guid: { sessionID: 1, localID },
@@ -970,7 +1070,7 @@ export class Slide {
       shapeTruncates: false,
       autoRename: true,
       frameMaskDisabled: true,
-      nodeGenerationData: buildShapeNodeGenData(fillPaint, textFill),
+      nodeGenerationData: buildShapeNodeGenData(fillPaint, textFill, strokePaint, opts.strokeWeight ?? 1),
     };
 
     fd.message.nodeChanges.push(node);
@@ -994,7 +1094,7 @@ export class Slide {
   addLine(x1, y1, x2, y2, opts = {}) {
     const fd = this._fd;
     const localID = fd.maxLocalID() + 1;
-    const color = parseColor(fd, opts.color ?? 'black');
+    const color = parseColor(fd, opts.stroke ?? opts.color ?? 'black');
 
     const dx = x2 - x1;
     const dy = y2 - y1;
@@ -1012,12 +1112,14 @@ export class Slide {
       type: 'LINE',
       name: opts.name ?? 'Line',
       visible: true,
-      opacity: 1,
+      opacity: opts.opacity ?? 1,
       size: { x: length, y: 0 },
       transform: { m00: cos, m01: -sin, m02: x1, m10: sin, m11: cos, m12: y1 },
-      strokeWeight: opts.weight ?? 2,
+      strokeWeight: opts.strokeWeight ?? opts.weight ?? 2,
       strokeAlign: 'CENTER',
       strokeJoin: 'MITER',
+      strokeCap: opts.strokeCap ?? 'NONE',
+      ...(opts.dashPattern ? { dashPattern: opts.dashPattern } : {}),
       strokePaints: [{
         type: 'SOLID',
         color: { r: color.r, g: color.g, b: color.b, a: color.a ?? 1 },
@@ -1275,6 +1377,128 @@ export class Slide {
     return frameNode;
   }
 
+  /**
+   * Add a stroked SVG path (supports M/L/C/Q/Z open paths).
+   * Unlike addSVG (closed-region fills), addPath draws a stroked line/curve.
+   *
+   * @param {string} d - SVG path data (e.g. 'M 100 100 Q 200 50 300 100')
+   * @param {object} [opts]
+   * @param {number} [opts.x=0]         - X offset on slide
+   * @param {number} [opts.y=0]         - Y offset on slide
+   * @param {object|string} [opts.stroke='black'] - Stroke color
+   * @param {number} [opts.strokeWeight=2]
+   * @param {string} [opts.strokeCap='NONE'] - 'NONE' | 'ROUND' | 'SQUARE' | 'LINE_ARROW' | 'TRIANGLE_ARROW'
+   * @param {string} [opts.strokeJoin='MITER']
+   * @param {number[]} [opts.dashPattern]
+   * @param {object|string} [opts.fill] - Optional fill color for closed regions
+   * @param {number} [opts.opacity=1]
+   * @param {string} [opts.name='Path']
+   * @returns {object} the raw VECTOR node
+   */
+  addPath(d, opts = {}) {
+    const fd = this._fd;
+    const localID = fd.maxLocalID() + 1;
+
+    const cmds = _parseSVGPath(d);
+    if (!cmds.length) throw new Error('addPath: path data produced no commands');
+
+    // Compute bounding box from vertices
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+    for (const c of cmds) {
+      const pts = [];
+      if (c.type === 'M' || c.type === 'L') pts.push([c.x, c.y]);
+      else if (c.type === 'C') pts.push([c.c1x, c.c1y], [c.c2x, c.c2y], [c.x, c.y]);
+      for (const [px, py] of pts) {
+        if (px < minX) minX = px; if (py < minY) minY = py;
+        if (px > maxX) maxX = px; if (py > maxY) maxY = py;
+      }
+    }
+    if (!isFinite(minX)) { minX = 0; minY = 0; maxX = 0; maxY = 0; }
+    const width = Math.max(1, maxX - minX);
+    const height = Math.max(1, maxY - minY);
+
+    // Shift all commands to origin (0,0)
+    const shifted = cmds.map(c => {
+      if (c.type === 'M' || c.type === 'L') return { ...c, x: c.x - minX, y: c.y - minY };
+      if (c.type === 'C') return {
+        ...c,
+        c1x: c.c1x - minX, c1y: c.c1y - minY,
+        c2x: c.c2x - minX, c2y: c.c2y - minY,
+        x: c.x - minX, y: c.y - minY,
+      };
+      return c;
+    });
+
+    // commandsBlob (scaled 1:1) and vectorNetworkBlob
+    fd.message.blobs.push({ bytes: _encodeCommandsBlob(shifted, 1, 1) });
+    const cmdsBlobIdx = fd.message.blobs.length - 1;
+    fd.message.blobs.push({ bytes: _buildVectorNetworkBlob([shifted], { emitRegions: !!opts.fill }) });
+    const vnbIdx = fd.message.blobs.length - 1;
+
+    const strokeColor = parseColor(fd, opts.stroke ?? 'black');
+    const strokePaints = [{
+      type: 'SOLID',
+      color: { r: strokeColor.r, g: strokeColor.g, b: strokeColor.b, a: strokeColor.a ?? 1 },
+      opacity: 1,
+      visible: true,
+      blendMode: 'NORMAL',
+    }];
+
+    const fillPaints = [];
+    if (opts.fill) {
+      const fc = parseColor(fd, opts.fill);
+      fillPaints.push({
+        type: 'SOLID',
+        color: { r: fc.r, g: fc.g, b: fc.b, a: fc.a ?? 1 },
+        opacity: 1,
+        visible: true,
+        blendMode: 'NORMAL',
+      });
+    }
+
+    const node = {
+      guid: { sessionID: 1, localID },
+      phase: 'CREATED',
+      parentIndex: {
+        guid: this._node.guid,
+        position: positionChar(fd.getChildren(nid(this._node)).length),
+      },
+      type: 'VECTOR',
+      name: opts.name ?? 'Path',
+      visible: true,
+      opacity: opts.opacity ?? 1,
+      size: { x: width, y: height },
+      transform: {
+        m00: 1, m01: 0, m02: (opts.x ?? 0) + minX,
+        m10: 0, m11: 1, m12: (opts.y ?? 0) + minY,
+      },
+      strokeWeight: opts.strokeWeight ?? 2,
+      strokeAlign: opts.strokeAlign ?? 'CENTER',
+      strokeJoin: opts.strokeJoin ?? 'MITER',
+      strokeCap: opts.strokeCap ?? 'NONE',
+      strokePaints,
+      fillPaints,
+      fillGeometry: opts.fill ? [{ windingRule: 'NONZERO', commandsBlob: cmdsBlobIdx, styleID: 0 }] : [],
+      // strokeGeometry must be a *pre-expanded outline ribbon* (Figma fills
+      // it with the stroke color — it's not rendered as an SVG stroke). We
+      // only have the centerline here, so leave it empty and let Figma
+      // derive the stroke from vectorNetworkBlob + strokePaints + strokeWeight.
+      // Supplying the centerline as strokeGeometry makes Figma's server
+      // rasterizer fill the open curve, producing a "lens" shape in previews.
+      strokeGeometry: [],
+      ...(opts.dashPattern ? { dashPattern: opts.dashPattern } : {}),
+      vectorData: {
+        vectorNetworkBlob: vnbIdx,
+        normalizedSize: { x: width, y: height },
+        styleOverrideTable: [],
+      },
+    };
+
+    fd.message.nodeChanges.push(node);
+    fd.rebuildMaps();
+    return node;
+  }
+
   /**
    * Add a FRAME (auto-layout container) to this slide.
    * Useful for grouping text nodes with automatic spacing.
@@ -1567,14 +1791,14 @@ export class Shape {
     const imgHash = sha1Hex(imgBuf);
     const { width: origW, height: origH } = await getImageDimensions(imgBuf);
 
-    const tmpThumb = `/tmp/openfig_thumb_${Date.now()}.png`;
+    const tmpThumb = join(tmpdir(), `openfig_thumb_${Date.now()}.png`);
     await generateThumbnail(imgBuf, tmpThumb);
     const thumbHash = sha1Hex(readFileSync(tmpThumb));
 
     if (imgPath) {
       copyToImagesDir(this._fd, imgHash, imgPath);
     } else {
-      const tmpImg = `/tmp/openfig_img_${Date.now()}`;
+      const tmpImg = join(tmpdir(), `openfig_img_${Date.now()}`);
       writeFileSync(tmpImg, imgBuf);
       copyToImagesDir(this._fd, imgHash, tmpImg);
     }
@@ -1623,6 +1847,10 @@ class FrameProxy {
     return Slide.prototype.addText.call(this, text, { ...opts, x: 0, y: 0 });
   }
 
+  addFrame(x, y, width, height, opts = {}) {
+    return Slide.prototype.addFrame.call(this, x, y, width, height, opts);
+  }
+
   addRectangle(x, y, width, height, opts = {}) {
     return Slide.prototype.addRectangle.call(this, x, y, width, height, opts);
   }
@@ -1630,6 +1858,30 @@ class FrameProxy {
   async addImage(pathOrBuf, opts = {}) {
     return Slide.prototype.addImage.call(this, pathOrBuf, opts);
   }
+
+  addEllipse(x, y, width, height, opts = {}) {
+    return Slide.prototype.addEllipse.call(this, x, y, width, height, opts);
+  }
+
+  addPath(d, opts = {}) {
+    return Slide.prototype.addPath.call(this, d, opts);
+  }
+
+  addLine(x1, y1, x2, y2, opts = {}) {
+    return Slide.prototype.addLine.call(this, x1, y1, x2, y2, opts);
+  }
+
+  addSVG(svg, opts = {}) {
+    return Slide.prototype.addSVG.call(this, svg, opts);
+  }
+
+  // addEllipse / addDiamond / addTriangle / addStar all route through
+  // Slide.prototype._addShapeWithText, which expects `this._addShapeWithText`
+  // to resolve on the receiver. Expose it here so FrameProxy behaves like a
+  // Slide target for those shape handlers.
+  _addShapeWithText(shapeType, x, y, width, height, opts = {}) {
+    return Slide.prototype._addShapeWithText.call(this, shapeType, x, y, width, height, opts);
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -1665,7 +1917,12 @@ function resolveTextStyle(fd, styleName) {
   );
   if (preview) return preview;
 
-  throw new Error(`Unknown text style: "${styleName}". Available: Title, Header 1, Header 2, Header 3, Body 1, Body 2, Body 3, Note`);
+  const available = nodes
+    .filter(n => n.type === 'TEXT' && (n.isPublishable === true || (n.locked === true && n.visible === false)))
+    .map(n => n.name)
+    .filter(Boolean);
+  const avail = available.length ? available.join(', ') : '(no named styles in deck — pass explicit font/fontSize instead)';
+  throw new Error(`Unknown text style: "${styleName}". Available: ${avail}`);
 }
 
 // Designer-friendly color aliases → hex
@@ -1694,6 +1951,58 @@ function _hexToRgb(hex) {
   return { r: parseInt(h.slice(0,2),16)/255, g: parseInt(h.slice(2,4),16)/255, b: parseInt(h.slice(4,6),16)/255 };
 }
 
+// Speaker-notes Lexical <-> plain-text helpers. See setSpeakerNotes for the
+// Figma-import failure mode this works around.
+function _plainToLexical(plain) {
+  // Match Figma's native speaker-notes format byte-for-byte: paragraphs with
+  // text content get direction "ltr" and textFormat 0; truly empty paragraphs
+  // (blank-line separators, or a fully-empty notes document) get direction null
+  // and textFormat null to match the blank-deck template.
+  const lines = String(plain).split('\n');
+  const children = lines.map(line => {
+    const hasText = line !== '';
+    return {
+      children: hasText ? [{
+        detail: 0, format: 0, mode: 'normal', style: '',
+        text: line, type: 'text', version: 1,
+      }] : [],
+      direction: hasText ? 'ltr' : null,
+      format: '',
+      indent: 0,
+      type: 'paragraph',
+      version: 1,
+      textFormat: hasText ? 0 : null,
+      textStyle: '',
+    };
+  });
+  const hasAnyText = lines.some(l => l !== '');
+  return JSON.stringify({
+    root: {
+      children: children.length ? children : [{
+        children: [], direction: null, format: '', textFormat: null,
+        indent: 0, type: 'paragraph', version: 1, textStyle: '',
+      }],
+      direction: hasAnyText ? 'ltr' : null,
+      format: '',
+      indent: 0,
+      type: 'root',
+      version: 1,
+    },
+  });
+}
+
+function _lexicalToPlain(stored) {
+  if (!stored) return '';
+  // Tolerate plain-text round-trips from before the Lexical wrapping existed.
+  if (typeof stored !== 'string' || !stored.startsWith('{')) return String(stored);
+  let doc;
+  try { doc = JSON.parse(stored); } catch { return stored; }
+  const paragraphs = doc?.root?.children ?? [];
+  return paragraphs.map(p =>
+    (p?.children ?? []).map(c => c?.text ?? '').join('')
+  ).join('\n');
+}
+
 /**
  * Resolve any color value to { r, g, b } (0-1) plus optional colorVar for Figma variables.
  * Accepts:
@@ -1706,6 +2015,15 @@ function parseColor(fd, color) {
   if (!color && color !== 0) return { r: 0, g: 0, b: 0 };
   if (typeof color === 'object') return { r: color.r, g: color.g, b: color.b };
   if (typeof color === 'string') {
+    // CSS rgb()/rgba() — common in SVG `fill` attributes.
+    const rgbMatch = color.match(/^rgba?\(\s*([0-9.]+)[,\s]+([0-9.]+)[,\s]+([0-9.]+)(?:[,\s/]+[0-9.]+%?)?\s*\)$/i);
+    if (rgbMatch) {
+      return {
+        r: Math.max(0, Math.min(1, parseFloat(rgbMatch[1]) / 255)),
+        g: Math.max(0, Math.min(1, parseFloat(rgbMatch[2]) / 255)),
+        b: Math.max(0, Math.min(1, parseFloat(rgbMatch[3]) / 255)),
+      };
+    }
     // Hex string
     if (/^#?[0-9a-fA-F]{6}$/.test(color)) return _hexToRgb(color);
     // Figma theme variable first (exact match, preserves colorVar binding for slides)
@@ -1749,14 +2067,14 @@ function resolveColorVariable(fd, colorName) {
  * Build styleOverrideTable + characterStyleIDs from an array of text runs.
  * Each unique formatting combination gets its own styleID.
  */
-function buildRunOverrides(runs, baseFontName, styleIdForText) {
+function buildRunOverrides(runs, baseFontName, styleIdForText, fd) {
   const styleOverrideTable = [];
   const characterStyleIDs = [];
   const styleMap = new Map(); // formatKey → styleID
   let nextStyleID = 1;
 
   for (const run of runs) {
-    const hasFormat = run.bold || run.italic || run.underline || run.strikethrough || run.hyperlink;
+    const hasFormat = run.bold || run.italic || run.underline || run.strikethrough || run.hyperlink || run.color;
 
     if (!hasFormat) {
       // Plain text — styleID 0 (base style)
@@ -1765,7 +2083,8 @@ function buildRunOverrides(runs, baseFontName, styleIdForText) {
     }
 
     // Build a key for this unique formatting combination
-    const key = `${run.bold ? 'b' : ''}${run.italic ? 'i' : ''}${run.underline ? 'u' : ''}${run.strikethrough ? 's' : ''}${run.hyperlink ? 'h:' + run.hyperlink : ''}`;
+    const colorKey = run.color ? 'c:' + (typeof run.color === 'string' ? run.color : JSON.stringify(run.color)) : '';
+    const key = `${run.bold ? 'b' : ''}${run.italic ? 'i' : ''}${run.underline ? 'u' : ''}${run.strikethrough ? 's' : ''}${run.hyperlink ? 'h:' + run.hyperlink : ''}${colorKey}`;
 
     if (!styleMap.has(key)) {
       const styleID = nextStyleID++;
@@ -1809,6 +2128,18 @@ function buildRunOverrides(runs, baseFontName, styleIdForText) {
         entry.textDecoration = 'STRIKETHROUGH';
       }
 
+      // Per-run color
+      if (run.color && fd) {
+        const c = parseColor(fd, run.color);
+        entry.fillPaints = [{
+          type: 'SOLID',
+          color: { r: c.r, g: c.g, b: c.b, a: c.a ?? 1 },
+          opacity: 1,
+          visible: true,
+          blendMode: 'NORMAL',
+        }];
+      }
+
       styleOverrideTable.push(entry);
     }
 
@@ -1918,7 +2249,7 @@ function buildLines(characters, runs, listType) {
  * Build the nodeGenerationData required for SHAPE_WITH_TEXT nodes.
  * Two override entries: [0] = shape background, [1] = inner text.
  */
-function buildShapeNodeGenData(shapeFillPaint, textFillPaint) {
+function buildShapeNodeGenData(shapeFillPaint, textFillPaint, shapeStrokePaint = null, shapeStrokeWeight = 1) {
   const DETACHED = { guid: { sessionID: 4294967295, localID: 4294967295 } };
   const baseOverride = {
     styleIdForFill: DETACHED,
@@ -1962,6 +2293,10 @@ function buildShapeNodeGenData(shapeFillPaint, textFillPaint) {
         ...baseOverride,
         guidPath: { guids: [{ sessionID: 40000000, localID: 0 }] },
         fillPaints: [shapeFillPaint],
+        ...(shapeStrokePaint ? {
+          strokePaints: [shapeStrokePaint],
+          strokeWeight: shapeStrokeWeight,
+        } : {}),
       },
       {
         ...baseOverride,
@@ -1979,15 +2314,24 @@ function buildShapeNodeGenData(shapeFillPaint, textFillPaint) {
 
 function _parseSVGPath(d) {
   const tokens = [];
-  const re = /([MmLlCcSsHhVvZz])|([+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?)/g;
+  const re = /([MmLlCcSsHhVvQqTtZz])|([+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?)/g;
   let m;
   while ((m = re.exec(d)) !== null) {
     if (m[1]) tokens.push(m[1]);
     else tokens.push(parseFloat(m[2]));
   }
   const cmds = [];
-  let i = 0, cx = 0, cy = 0, startX = 0, startY = 0, prevC2x = 0, prevC2y = 0, cmd = '';
+  let i = 0, cx = 0, cy = 0, startX = 0, startY = 0, prevC2x = 0, prevC2y = 0, prevQx = 0, prevQy = 0, cmd = '';
   const num = () => tokens[i++];
+  // Q(c, end) → C using: c1 = start + 2/3(c - start), c2 = end + 2/3(c - end)
+  const qToC = (sx, sy, qx, qy, ex, ey) => ({
+    type: 'C',
+    c1x: sx + (2 / 3) * (qx - sx),
+    c1y: sy + (2 / 3) * (qy - sy),
+    c2x: ex + (2 / 3) * (qx - ex),
+    c2y: ey + (2 / 3) * (qy - ey),
+    x: ex, y: ey,
+  });
   while (i < tokens.length) {
     if (typeof tokens[i] === 'string') cmd = tokens[i++];
     switch (cmd) {
@@ -2003,6 +2347,10 @@ function _parseSVGPath(d) {
       case 'c': { const c1x=cx+num(),c1y=cy+num(),c2x=cx+num(),c2y=cy+num(); cx+=num(); cy+=num(); prevC2x=c2x; prevC2y=c2y; cmds.push({type:'C',c1x,c1y,c2x,c2y,x:cx,y:cy}); break; }
       case 'S': { const c1x=2*cx-prevC2x,c1y=2*cy-prevC2y,c2x=num(),c2y=num(); cx=num(); cy=num(); prevC2x=c2x; prevC2y=c2y; cmds.push({type:'C',c1x,c1y,c2x,c2y,x:cx,y:cy}); break; }
       case 's': { const c1x=2*cx-prevC2x,c1y=2*cy-prevC2y,c2x=cx+num(),c2y=cy+num(); cx+=num(); cy+=num(); prevC2x=c2x; prevC2y=c2y; cmds.push({type:'C',c1x,c1y,c2x,c2y,x:cx,y:cy}); break; }
+      case 'Q': { const sx=cx,sy=cy,qx=num(),qy=num(); cx=num(); cy=num(); prevQx=qx; prevQy=qy; cmds.push(qToC(sx,sy,qx,qy,cx,cy)); break; }
+      case 'q': { const sx=cx,sy=cy,qx=cx+num(),qy=cy+num(); cx+=num(); cy+=num(); prevQx=qx; prevQy=qy; cmds.push(qToC(sx,sy,qx,qy,cx,cy)); break; }
+      case 'T': { const sx=cx,sy=cy,qx=2*cx-prevQx,qy=2*cy-prevQy; cx=num(); cy=num(); prevQx=qx; prevQy=qy; cmds.push(qToC(sx,sy,qx,qy,cx,cy)); break; }
+      case 't': { const sx=cx,sy=cy,qx=2*cx-prevQx,qy=2*cy-prevQy; cx+=num(); cy+=num(); prevQx=qx; prevQy=qy; cmds.push(qToC(sx,sy,qx,qy,cx,cy)); break; }
       case 'Z': case 'z': cmds.push({ type: 'Z' }); cx = startX; cy = startY; break;
       default: i++; break;
     }
@@ -2029,17 +2377,33 @@ function _encodeCommandsBlob(cmds, sx, sy) {
   return new Uint8Array(buf.buffer, 0, off);
 }
 
-function _buildVectorNetworkBlob(allPathCmds) {
+function _buildVectorNetworkBlob(allPathCmds, { emitRegions = true } = {}) {
+  // Regions in a vector network define closed fillable loops. addSVG needs
+  // them (filled glyphs/shapes). addPath emits open stroked curves — if we
+  // emit a region for those, Figma renders a filled area between endpoints
+  // even when fillPaints is empty, producing "lens" shapes instead of strokes.
   const vertices = [];
   const segments = [];
   const regions = [];
 
   for (const pathCmds of allPathCmds) {
-    const regionSegs = [];
+    // One region can contain multiple independent loops (SVG `M ... Z M ... Z`
+    // draws e.g. the two O-shapes in a pair of letters). Track loops as
+    // separate segment-index arrays so the region header can emit the correct
+    // numLoops and each loop's segment list. Writing a single flat list with
+    // numLoops=1 makes Figma connect the end of one subpath to the start of
+    // the next as if they were a single chain — visible as a diagonal bar
+    // running through multi-letter wordmark paths.
+    const loops = [];
+    let currentLoop = [];
     let firstVtx = -1, prevVtx = -1, prevX = 0, prevY = 0;
 
     for (const c of pathCmds) {
       if (c.type === 'M') {
+        if (currentLoop.length > 0) {
+          loops.push(currentLoop);
+          currentLoop = [];
+        }
         const vi = vertices.length;
         vertices.push({ x: c.x, y: c.y });
         firstVtx = vi; prevVtx = vi; prevX = c.x; prevY = c.y;
@@ -2047,7 +2411,7 @@ function _buildVectorNetworkBlob(allPathCmds) {
         const vi = vertices.length;
         vertices.push({ x: c.x, y: c.y });
         if (prevVtx >= 0) {
-          regionSegs.push(segments.length);
+          currentLoop.push(segments.length);
           segments.push({ s: prevVtx, tsx: 0, tsy: 0, e: vi, tex: 0, tey: 0, t: 0 });
         }
         prevVtx = vi; prevX = c.x; prevY = c.y;
@@ -2055,24 +2419,30 @@ function _buildVectorNetworkBlob(allPathCmds) {
         const vi = vertices.length;
         vertices.push({ x: c.x, y: c.y });
         if (prevVtx >= 0) {
-          regionSegs.push(segments.length);
+          currentLoop.push(segments.length);
           segments.push({ s: prevVtx, tsx: c.c1x - prevX, tsy: c.c1y - prevY, e: vi, tex: c.c2x - c.x, tey: c.c2y - c.y, t: 4 });
         }
         prevVtx = vi; prevX = c.x; prevY = c.y;
       } else if (c.type === 'Z') {
         if (prevVtx >= 0 && prevVtx !== firstVtx) {
-          regionSegs.push(segments.length);
+          currentLoop.push(segments.length);
           segments.push({ s: prevVtx, tsx: 0, tsy: 0, e: firstVtx, tex: 0, tey: 0, t: 0 });
         }
         prevVtx = firstVtx; prevX = vertices[firstVtx].x; prevY = vertices[firstVtx].y;
       }
     }
-    regions.push(regionSegs);
+    if (currentLoop.length > 0) loops.push(currentLoop);
+    if (emitRegions) regions.push(loops);
   }
 
   // Calculate size: header(16) + vertices(12 each) + segments(28 each) + regions(variable)
+  // Region layout: numLoops(u32) + [segCount(u32) + segIndices(u32*n)]*numLoops + windingRule(u32)
   let regSize = 0;
-  for (const r of regions) regSize += 4 + 4 + r.length * 4 + 4; // numLoops + segCount + indices + windingRule
+  for (const loops of regions) {
+    regSize += 4; // numLoops
+    for (const loop of loops) regSize += 4 + loop.length * 4; // segCount + indices
+    regSize += 4; // windingRule
+  }
   const totalSize = 16 + vertices.length * 12 + segments.length * 28 + regSize;
   const buf = Buffer.alloc(totalSize);
   let off = 0;
@@ -2101,11 +2471,13 @@ function _buildVectorNetworkBlob(allPathCmds) {
     buf.writeUInt32LE(s.t, off); off += 4;
   }
 
-  // Regions: numLoops(u32) segCount(u32) segIndices(u32*n) windingRule(u32)
-  for (const r of regions) {
-    buf.writeUInt32LE(1, off); off += 4; // numLoops = 1
-    buf.writeUInt32LE(r.length, off); off += 4;
-    for (const si of r) { buf.writeUInt32LE(si, off); off += 4; }
+  // Regions: numLoops(u32) + [segCount(u32) + segIndices(u32*n)]*numLoops + windingRule(u32)
+  for (const loops of regions) {
+    buf.writeUInt32LE(loops.length, off); off += 4;
+    for (const loop of loops) {
+      buf.writeUInt32LE(loop.length, off); off += 4;
+      for (const si of loop) { buf.writeUInt32LE(si, off); off += 4; }
+    }
     buf.writeUInt32LE(1, off); off += 4; // windingRule = NONZERO
   }
 
@@ -2118,7 +2490,7 @@ function sha1Hex(buf) {
 
 function copyToImagesDir(fd, hash, srcPath) {
   if (!fd.imagesDir) {
-    fd.imagesDir = `/tmp/openfig_images_${Date.now()}`;
+    fd.imagesDir = join(tmpdir(), `openfig_images_${Date.now()}`);
     mkdirSync(fd.imagesDir, { recursive: true });
   }
   const dest = join(fd.imagesDir, hash);