openfig-cli 0.3.35 → 0.3.38

package/README.md

@@ -4,86 +4,68 @@
 
 Open tools for Figma files.
 
-Parse, inspect, and render `.deck` and `.fig` files without the Figma application — including PNG export.
+Parse, inspect, render, and modify `.deck` and `.fig` files without the Figma application.
 
-OpenFig is an open-source implementation of the Figma file format that allows developers to inspect, parse, and render Figma files without using the Figma application or API. The primary use case is Figma Slides (`.deck`), with `.fig` design file support also available.
+## Install
 
-## Figma File Formats
+```bash
+npm install -g openfig-cli
+```
 
-Each Figma product has its own native file format. Active development — status may change:
+Node 18+. No build step. Pure ESM.
+
+## File Format Support
 
-| Product | Extension | Status |
-|---------|-----------|--------|
-| Figma Slides | `.deck` | ✅ |
-| Figma Design | `.fig` | ✅ read + PNG render |
-| Figma Jam (whiteboard) | `.jam` | ❌ not yet |
-| Figma Buzz | `.buzz` | ❌ not yet |
-| Figma Sites | `.site` | ❌ not yet |
-| Figma Make | `.make` | ❌ not yet |
+| Product | Extension | Read | Render | Modify |
+|---------|-----------|------|--------|--------|
+| Figma Slides | `.deck` | ✅ | ✅ PNG / PDF | ✅ |
+| Figma Design | `.fig` | ✅ | ✅ PNG / PDF | — |
 
 ## Render Quality
 
-OpenFig achieves **≥99% SSIM** (Structural Similarity Index) against Figma reference exports across all test cases. Render fidelity is verified with visual regression tests against real Figma-exported PNGs.
+**≥99% SSIM** against Figma reference exports across all test cases:
 
 | Test suite | Visual results |
 |------------|----------------|
 | `.deck` slides | [render-report-deck.html](https://rcoenen.github.io/OpenFig/test/rasterizer/reports/openfig-render-report-deck.html) |
 | `.fig` design frames | [render-report-fig.html](https://rcoenen.github.io/OpenFig/test/rasterizer/reports/openfig-render-report-fig.html) |
 
-## Why native `.deck`?
-
-Figma Slides lets you download presentations as `.deck` files and re-upload them. This is the **native** round-trip format. Exporting to `.pptx` is lossy — vectors get rasterized, fonts fall back to system defaults, layout breaks. By staying in `.deck`, you preserve everything exactly as Figma renders it.
-
-OpenFig makes this round-trip programmable. Download a `.deck`, modify it, re-upload. Everything stays native.
-
-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
-
-- **AI agent for presentations** — let an LLM rewrite copy, insert images, and produce a ready-to-upload `.deck`
-- **Batch-produce branded decks** — start from a template, feed in data per client/project, get pixel-perfect slides out
-- **Inspect and audit** — understand the internal structure of any `.deck` file
-- **Automate** text and image placement across dozens of slides in seconds
-
-## Install
+## CLI
 
 ```bash
-npm install -g openfig-cli
+# Read & inspect (works on .deck and .fig)
+openfig inspect deck.deck              # node hierarchy tree
+openfig list-text deck.deck            # all text and image content per slide
+openfig list-overrides deck.deck       # editable override keys per symbol
+
+# Render (works on .deck and .fig)
+openfig export deck.deck               # export slides/frames as PNG
+openfig pdf deck.deck                  # export as multi-page PDF
+
+# 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>
+openfig clone-slide deck.deck -o out.deck --template <id|name> --name <name> [--set key=value ...]
+openfig remove-slide deck.deck -o out.deck --slide <id>
+openfig roundtrip in.deck out.deck     # decode + re-encode validation
 ```
 
-Node 18+. No build step. Pure ESM.
-
-## File Format Support
-
-All CLI commands work on both `.deck` (Figma Slides) and `.fig` (Figma Design) files. Pass either format wherever a file path is expected.
+> Full CLI reference: [docs/cli.md](docs/cli.md)
 
-## Quick Start
+## Why native `.deck`?
 
-```bash
-openfig inspect my-presentation.deck        # node hierarchy
-openfig list-text my-presentation.deck      # all text + images per slide
-openfig list-overrides my-presentation.deck # editable fields per symbol
-```
+Figma Slides lets you download and re-upload `.deck` files losslessly. Exporting to `.pptx` is lossy — vectors rasterize, fonts fall back, layout breaks. OpenFig makes this native round-trip programmable: download, modify, re-upload.
 
-> Full CLI reference: [docs/cli.md](docs/cli.md)
+Plug in Claude Cowork or any coding agent and you have an AI that can read and edit Figma presentations end-to-end — without opening the Figma UI.
 
-## Claude Cowork / MCP Integration
+## Agentic / MCP Integration
 
 > Install guide, MCP workflows, and template states: [docs/agentic/claude-cowork.md](docs/agentic/claude-cowork.md)
 
-## Programmatic API
-
-```javascript
-import { Deck } from 'openfig';
-
-const deck = await Deck.open('template.deck');
-const slide = deck.slides[0];
-slide.addText('Hello world', { style: 'Title' });
-await deck.save('output.deck');
-```
+## Docs
 
-| Docs | |
-|------|---|
+| | |
+|---|---|
 | MCP / Claude workflows | [docs/mcp.md](docs/mcp.md) |
 | High-level API | [docs/api-spec.md](docs/api-spec.md) |
 | Low-level FigDeck API | [docs/library.md](docs/library.md) |

package/lib/rasterizer/svg-builder.mjs

@@ -21,6 +21,7 @@
 
 import { readFileSync } from 'fs';
 import { join } from 'path';
+import { extractRenderableGradientFill, resolveGradientGeometry } from 'openfig-core';
 import { hashToHex } from '../core/image-helpers.mjs';
 import { nid } from '../core/node-helpers.mjs';
 
@@ -56,49 +57,34 @@ function resolveFill(fillPaints) {
  *  w, h = element dimensions in pixels (needed for userSpaceOnUse coordinates).
  *  Returns { defs: string, fill: string } where fill is 'url(#grad-N)'. */
 function resolveGradientSvg(paint, w, h) {
+  const gradient = extractRenderableGradientFill([paint]);
+  if (!gradient) return null;
+  const geometry = resolveGradientGeometry(gradient, w, h);
+  if (!geometry) return null;
+
   const id = `grad-${++_svgIdSeq}`;
-  const stops = (paint.stops ?? []).map(s => {
+  const stops = gradient.stops.map(s => {
     const color = cssColor(s.color ?? {});
     return `<stop offset="${s.position}" stop-color="${color}"/>`;
   }).join('');
-  const opacityAttr = (paint.opacity ?? 1) !== 1 ? ` opacity="${paint.opacity}"` : '';
-
-  // Figma's paint.transform maps from NODE space to GRADIENT space.
-  // We need the inverse: gradient space → node normalized space → pixels.
-  const t = paint.transform ?? {};
-  const ga = t.m00 ?? 1, gc = t.m01 ?? 0, ge = t.m02 ?? 0;
-  const gb = t.m10 ?? 0, gd = t.m11 ?? 1, gf = t.m12 ?? 0;
-  const det = ga * gd - gb * gc;
-  // Inverse affine: paint.transform maps node→gradient; we need gradient→node
-  const ia = gd / det, ic = -gc / det, ie = (gc * gf - gd * ge) / det;
-  const ib = -gb / det, iid = ga / det, iif = (gb * ge - ga * gf) / det;
-  const tx = (gx, gy) => (ia * gx + ic * gy + ie) * w;
-  const ty = (gx, gy) => (ib * gx + iid * gy + iif) * h;
+  const opacityAttr = gradient.opacity !== 1 ? ` opacity="${gradient.opacity}"` : '';
   const f = v => +v.toFixed(2);
 
-  if (paint.type === 'GRADIENT_LINEAR') {
-    // Linear gradient line: (0, 0.5) → (1, 0.5) in gradient space
-    return {
-      defs: `<linearGradient id="${id}" x1="${f(tx(0,0.5))}" y1="${f(ty(0,0.5))}" x2="${f(tx(1,0.5))}" y2="${f(ty(1,0.5))}" gradientUnits="userSpaceOnUse">${stops}</linearGradient>`,
-      fill: `url(#${id})`,
-      opacityAttr,
-    };
-  }
-  if (paint.type === 'GRADIENT_RADIAL') {
-    // Radial gradient: center (0.5, 0.5), radius mapped through transform
-    const cx = f(tx(0.5, 0.5)), cy = f(ty(0.5, 0.5));
-    // Radius along the gradient's x-axis: distance from center to (1, 0.5)
-    const rx = f(Math.hypot(tx(1, 0.5) - tx(0.5, 0.5), ty(1, 0.5) - ty(0.5, 0.5)));
-    const ry = f(Math.hypot(tx(0.5, 1) - tx(0.5, 0.5), ty(0.5, 1) - ty(0.5, 0.5)));
-    // Rotation angle from the transform
-    const angle = f(Math.atan2(ty(1, 0.5) - ty(0.5, 0.5), tx(1, 0.5) - tx(0.5, 0.5)) * 180 / Math.PI);
+  if (geometry.type === 'linear') {
     return {
-      defs: `<radialGradient id="${id}" cx="${cx}" cy="${cy}" rx="${rx}" ry="${ry}" gradientUnits="userSpaceOnUse" gradientTransform="rotate(${angle},${cx},${cy})">${stops}</radialGradient>`,
+      defs: `<linearGradient id="${id}" x1="${f(geometry.start.x)}" y1="${f(geometry.start.y)}" x2="${f(geometry.end.x)}" y2="${f(geometry.end.y)}" gradientUnits="userSpaceOnUse">${stops}</linearGradient>`,
       fill: `url(#${id})`,
       opacityAttr,
     };
   }
-  return null;
+  const cx = f(geometry.center.x), cy = f(geometry.center.y);
+  const rx = f(geometry.radiusX), ry = f(geometry.radiusY);
+  const angle = f(geometry.angle * 180 / Math.PI);
+  return {
+    defs: `<radialGradient id="${id}" cx="${cx}" cy="${cy}" rx="${rx}" ry="${ry}" gradientUnits="userSpaceOnUse" gradientTransform="rotate(${angle},${cx},${cy})">${stops}</radialGradient>`,
+    fill: `url(#${id})`,
+    opacityAttr,
+  };
 }
 
 function appendDefs(defs, extra) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openfig-cli",
-  "version": "0.3.35",
+  "version": "0.3.38",
   "description": "OpenFig — Open-source tools for Figma file parsing and rendering",
   "type": "module",
   "bin": {
@@ -45,7 +45,7 @@
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@resvg/resvg-wasm": "^2.6.2",
     "kiwi-schema": "^0.5.0",
-    "openfig-core": "^0.3.3",
+    "openfig-core": "^0.3.5",
     "pako": "^2.1.0",
     "pdf-lib": "^1.17.1",
     "sharp": "^0.34.5",