@grida/refig 0.0.1 → 0.0.3

package/README.md

@@ -1,6 +1,6 @@
 # `@grida/refig`
 
-> **re**nder **fig**ma — headless Figma renderer (Node.js + browser) in the spirit of [`resvg-js`](https://github.com/nicolo-ribaudo/resvg-js)
+> **re**nder **fig**ma — headless Figma renderer (Node.js + browser) in the spirit of [`resvg`](https://github.com/linebender/resvg)
 
 Render Figma documents to **PNG, JPEG, WebP, PDF, and SVG** in **Node.js (no browser required)** or directly in the **browser**.
 
@@ -194,8 +194,9 @@ pnpm add -g @grida/refig
 Or run without installing:
 
 ```sh
-npx @grida/refig <input> --node <node-id> --out <path>
-pnpm dlx @grida/refig <input> --node <node-id> --out <path>
+# Instant usage (writes to OS temp dir; output path printed)
+npx @grida/refig <input> --node <node-id> --format png
+pnpm dlx @grida/refig <input> --export-all
 ```
 
 ### Usage
@@ -211,44 +212,50 @@ Using a directory avoids passing the document and images separately.
 
 ```sh
 # Single node (default)
-refig <input> --node <node-id> --out <path> [options]
+# - Without --out: writes to OS temp dir (requires --format)
+# - With --out: format inferred from file extension unless --format is provided
+refig <input> --node <node-id> --format <fmt> [options]
+refig <input> --node <node-id> --out <path> [--format <fmt>] [options]
 
 # With images directory (REST JSON only; IMAGE fills rendered from local files)
-refig <input> --images <dir> --node <node-id> --out <path>
+refig <input> --images <dir> --node <node-id> --format <fmt> [options]
+refig <input> --images <dir> --node <node-id> --out <path> [--format <fmt>] [options]
 
 # Directory input: document.json + images/ under one folder
-refig ./my-figma-export --node "1:23" --out ./out.png
+refig ./my-figma-export --node "1:23" --format png
 
 # Export all nodes that have exportSettings (REST JSON or .fig)
-refig <input> --export-all --out <output-dir>
+refig <input> --export-all [--out <output-dir>]
 ```
 
 ### Examples
 
 ```sh
-# Render a node from a .fig file
-refig ./design.fig --node "1:23" --out ./out.png
-
-# Render from REST API JSON
-refig ./figma-response.json --node "1:23" --out ./out.svg
+# Instant usage: omit --out to write to OS temp directory (output path printed)
+refig ./design.fig --node "1:23" --format png
+refig ./figma-response.json --node "1:23" --format svg
 
 # Directory with document.json (and optionally images/): one path instead of response + --images
-refig ./my-figma-export --node "1:23" --out ./out.png
+refig ./my-figma-export --node "1:23" --format png
 # (my-figma-export/document.json, my-figma-export/images/)
 
 # Explicit images directory (when not using a project directory)
-refig ./figma-response.json --images ./downloaded-images --node "1:23" --out ./out.png
+refig ./figma-response.json --images ./downloaded-images --node "1:23" --format png
 
 # Export all: render every node that has export settings (see below)
-refig ./figma-response.json --export-all --out ./exports
-refig ./design.fig --export-all --out ./exports
+refig ./figma-response.json --export-all
+refig ./design.fig --export-all
 
 # Scale 2x, custom dimensions
-refig ./design.fig --node "1:23" --out ./out.png --width 512 --height 512 --scale 2
+refig ./design.fig --node "1:23" --format png --width 512 --height 512 --scale 2
+
+# Deterministic output: provide --out (useful for CI or saving into a known path)
+refig ./design.fig --node "1:23" --out ./out.png
+refig ./figma-response.json --export-all --out ./exports
 
 # No-install (run without installing)
-npx @grida/refig ./design.fig --node "1:23" --out ./out.png
-pnpm dlx @grida/refig ./design.fig --node "1:23" --out ./out.png
+npx @grida/refig ./design.fig --node "1:23" --format png
+pnpm dlx @grida/refig ./design.fig --export-all
 ```
 
 ### Quick test via `figma_archive.py` (REST API → `document.json` + `images/`)
@@ -275,10 +282,10 @@ This writes:
 
 ```sh
 # Single node
-refig ./my-figma-export --node "1:23" --out ./out.png
+refig ./my-figma-export --node "1:23" --format png
 
 # Or export everything with Figma export presets
-refig ./my-figma-export --export-all --out ./exports
+refig ./my-figma-export --export-all
 ```
 
 ### Export all (`--export-all`)
@@ -291,17 +298,17 @@ With **`--export-all`**, refig walks the document and renders every node that ha
 
 ### Flags
 
-| Flag             | Required | Default                         | Description                                                                                   |
-| ---------------- | -------- | ------------------------------- | --------------------------------------------------------------------------------------------- |
-| `<input>`        | yes      |                                 | Path to `.fig`, JSON file, or directory containing `document.json` (and optionally `images/`) |
-| `--images <dir>` | no       |                                 | Directory of image assets for REST document (ignored if `<input>` is a dir with `images/`)    |
-| `--node <id>`    | yes\*    |                                 | Figma node ID to render (\*omit when using `--export-all`)                                    |
-| `--out <path>`   | yes      |                                 | Output file path (single node) or output directory (`--export-all`)                           |
-| `--export-all`   | no       |                                 | Export every node with exportSettings (REST JSON or .fig); `--out` is a directory             |
-| `--format <fmt>` | no       | inferred from `--out` extension | `png`, `jpeg`, `webp`, `pdf`, `svg` (single-node only)                                        |
-| `--width <px>`   | no       | `1024`                          | Viewport width (single-node only)                                                             |
-| `--height <px>`  | no       | `1024`                          | Viewport height (single-node only)                                                            |
-| `--scale <n>`    | no       | `1`                             | Raster scale factor (single-node only)                                                        |
+| Flag             | Required | Default                         | Description                                                                                                                                                                          |
+| ---------------- | -------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `<input>`        | yes      |                                 | Path to `.fig`, JSON file, or directory containing `document.json` (and optionally `images/`)                                                                                        |
+| `--images <dir>` | no       |                                 | Directory of image assets for REST document (ignored if `<input>` is a dir with `images/`)                                                                                           |
+| `--node <id>`    | yes\*    |                                 | Figma node ID to render (\*omit when using `--export-all`)                                                                                                                           |
+| `--out <path>`   | no       | OS temp dir when omitted        | Output file path (single node) or output directory (`--export-all`). When omitted, writes to the OS temp directory (valid with `--export-all` or with both `--format` and `--node`). |
+| `--export-all`   | no       |                                 | Export every node with exportSettings (REST JSON or .fig); `--out` is a directory                                                                                                    |
+| `--format <fmt>` | no       | inferred from `--out` extension | `png`, `jpeg`, `webp`, `pdf`, `svg` (single-node only; required when `--out` is omitted)                                                                                             |
+| `--width <px>`   | no       | `1024`                          | Viewport width (single-node only)                                                                                                                                                    |
+| `--height <px>`  | no       | `1024`                          | Viewport height (single-node only)                                                                                                                                                   |
+| `--scale <n>`    | no       | `1`                             | Raster scale factor (single-node only)                                                                                                                                               |
 
 ## Architecture
 
@@ -332,9 +339,9 @@ REST JSON ───┘
 **CLI** — You can pass images in two ways:
 
 - **`--images <dir>`** — Explicit images directory. Files are keyed by filename without extension (e.g. `a1b2c3d4.png` → ref `a1b2c3d4`). Use when the document is a separate file:  
-  `refig ./figma-response.json --images ./downloaded-images --node "1:23" --out ./out.png`
+  `refig ./figma-response.json --images ./downloaded-images --node "1:23" --format png`
 - **Directory input** — Pass a single directory that contains **`document.json`** (REST response) and optionally **`images/`**. No need to pass `--images` separately:  
-  `refig ./my-figma-export --node "1:23" --out ./out.png`  
+  `refig ./my-figma-export --node "1:23" --format png`  
   (expects `my-figma-export/document.json` and, if present, `my-figma-export/images/`.)
 
 For **`.fig`** input, images are embedded in the file; no extra images directory is needed. For **REST** input, use `--images` or a project directory with `images/` to render IMAGE fills correctly.
@@ -372,7 +379,7 @@ From the package root:
 
 1. Install dependencies and build: `pnpm install && pnpm build`
 2. Link the package so the `refig` CLI is available: `pnpm link --global`
-3. Run the `refig` command from anywhere to test (e.g. `refig ./fixture.json --node "1:1" --out ./out.png`)
+3. Run the `refig` command from anywhere to test (e.g. `refig ./fixture.json --node "1:1" --format png`)
 
 To unlink: `pnpm unlink --global`.
 

package/dist/browser.mjs

@@ -4,7 +4,7 @@ import {
   collectExportsFromDocument,
   exportSettingToRenderOptions,
   resolveMimeType
-} from "./chunk-PK5L35ID.mjs";
+} from "./chunk-YI7PIULZ.mjs";
 export {
   FigmaDocument,
   FigmaRenderer,

package/dist/{chunk-PK5L35ID.mjs → chunk-YI7PIULZ.mjs}

@@ -13749,11 +13749,19 @@ var iofigma;
         function hasGeometryTrait(node2) {
           return "fillGeometry" in node2 || "strokeGeometry" in node2;
         }
+        function getParentBounds(node2) {
+          const box = "absoluteBoundingBox" in node2 ? node2.absoluteBoundingBox : void 0;
+          const sz = "size" in node2 ? node2.size : void 0;
+          return {
+            width: box?.width ?? sz?.x ?? 0,
+            height: box?.height ?? sz?.y ?? 0
+          };
+        }
         function createVectorNodeFromPath(pathData, geometry, parentNode, childId, name, options) {
           if (!pathData) return null;
           try {
             const vectorNetwork = index_default2.fromSVGPathData(pathData);
-            const bbox = index_default2.getBBox(vectorNetwork);
+            const { width, height } = getParentBounds(parentNode);
             const strokeAsFill = options.strokeAsFill === true;
             return {
               id: childId,
@@ -13767,10 +13775,10 @@ var iofigma;
               }),
               ...positioning_trait({
                 relativeTransform: [
-                  [1, 0, bbox.x],
-                  [0, 1, bbox.y]
+                  [1, 0, 0],
+                  [0, 1, 0]
                 ],
-                size: { x: bbox.width, y: bbox.height }
+                size: { x: width, y: height }
               }),
               ...strokeAsFill ? {
                 ...fills_trait(
@@ -13794,8 +13802,8 @@ var iofigma;
               ..."effects" in parentNode && parentNode.effects ? effects_trait(parentNode.effects) : effects_trait(void 0),
               type: "vector",
               vector_network: vectorNetwork,
-              layout_target_width: bbox.width,
-              layout_target_height: bbox.height,
+              layout_target_width: width,
+              layout_target_height: height,
               fill_rule: map.windingRuleMap[geometry.windingRule] ?? "nonzero"
             };
           } catch (e) {
@@ -13806,13 +13814,73 @@ var iofigma;
             return null;
           }
         }
+        function createPathNodeFromPath(pathData, geometry, parentNode, childId, name, options) {
+          if (!pathData) return null;
+          try {
+            const { width, height } = getParentBounds(parentNode);
+            const strokeAsFill = options.strokeAsFill === true;
+            return {
+              id: childId,
+              ...base_node_trait({
+                name,
+                visible: "visible" in parentNode ? parentNode.visible : true,
+                locked: "locked" in parentNode ? parentNode.locked : false,
+                rotation: 0,
+                opacity: "opacity" in parentNode && parentNode.opacity !== void 0 ? parentNode.opacity : 1,
+                blendMode: "blendMode" in parentNode && parentNode.blendMode ? parentNode.blendMode : "NORMAL"
+              }),
+              ...positioning_trait({
+                relativeTransform: [
+                  [1, 0, 0],
+                  [0, 1, 0]
+                ],
+                size: { x: width, y: height }
+              }),
+              ...strokeAsFill ? {
+                ...fills_trait(
+                  parentNode.strokes ?? [],
+                  context,
+                  imageRefsUsed
+                ),
+                ...stroke_trait(
+                  { strokes: [], strokeWeight: 0 },
+                  context,
+                  imageRefsUsed
+                )
+              } : {
+                ...options.useFill ? fills_trait(parentNode.fills, context, imageRefsUsed) : {},
+                ...options.useStroke ? stroke_trait(parentNode, context, imageRefsUsed) : stroke_trait(
+                  { strokes: [], strokeWeight: 0 },
+                  context,
+                  imageRefsUsed
+                )
+              },
+              ..."effects" in parentNode && parentNode.effects ? effects_trait(parentNode.effects) : effects_trait(void 0),
+              type: "path",
+              data: pathData,
+              layout_target_width: width,
+              layout_target_height: height,
+              fill_rule: map.windingRuleMap[geometry.windingRule] ?? "nonzero"
+            };
+          } catch (e) {
+            console.warn(`Failed to create path node (${name}):`, e);
+            return null;
+          }
+        }
         function processFillGeometries(node2, parentGridaId, nodeTypeName) {
           if (!node2.fillGeometry?.length) return [];
           const childIds = [];
           node2.fillGeometry.forEach((geometry, idx) => {
             const childId = `${parentGridaId}_fill_${idx}`;
             const name = `${node2.name || nodeTypeName} Fill ${idx + 1}`;
-            const childNode = createVectorNodeFromPath(
+            const childNode = context.prefer_path_for_geometry ? createPathNodeFromPath(
+              geometry.path ?? "",
+              geometry,
+              node2,
+              childId,
+              name,
+              { useFill: true, useStroke: false }
+            ) : createVectorNodeFromPath(
               geometry.path ?? "",
               geometry,
               node2,
@@ -13833,7 +13901,14 @@ var iofigma;
           node2.strokeGeometry.forEach((geometry, idx) => {
             const childId = `${parentGridaId}_stroke_${idx}`;
             const name = `${node2.name || nodeTypeName} Stroke ${idx + 1}`;
-            const childNode = createVectorNodeFromPath(
+            const childNode = context.prefer_path_for_geometry ? createPathNodeFromPath(
+              geometry.path ?? "",
+              geometry,
+              node2,
+              childId,
+              name,
+              { useFill: false, useStroke: false, strokeAsFill: true }
+            ) : createVectorNodeFromPath(
               geometry.path ?? "",
               geometry,
               node2,
@@ -14082,7 +14157,7 @@ var iofigma;
           case "REGULAR_POLYGON":
           case "STAR":
           case "VECTOR": {
-            const useRestVectorNetwork = context.disable_volatile_apis !== true && "vectorNetwork" in node && node.vectorNetwork != null;
+            const useRestVectorNetwork = context.prefer_path_for_geometry !== true && context.disable_volatile_apis !== true && "vectorNetwork" in node && node.vectorNetwork != null;
             if (useRestVectorNetwork) {
               try {
                 const ir = restful2.map.normalizeRestVectorNetworkToIR(
@@ -15866,7 +15941,8 @@ function exportSettingToRenderOptions(node, setting) {
     JPG: "jpeg",
     PNG: "png",
     SVG: "svg",
-    PDF: "pdf"
+    PDF: "pdf",
+    WEBP: "webp"
   };
   const format = formatMap[setting.format] ?? "png";
   const constraint = setting.constraint;
@@ -15951,6 +16027,7 @@ function restJsonToSceneJson(json, rootNodeId, images) {
   const resolveImageSrc = images && (Object.keys(images).length > 0 ? (ref) => ref in images ? `res://images/${ref}` : null : void 0);
   const buildContext = (overrides) => ({
     gradient_id_generator: baseGradientGen,
+    prefer_path_for_geometry: true,
     ...resolveImageSrc && { resolve_image_src: resolveImageSrc },
     ...overrides
   });
@@ -16089,6 +16166,7 @@ function figBytesToSceneJson(figBytes, rootNodeId) {
     node_id_generator: () => `refig-${++counter}`,
     gradient_id_generator: () => `grad-${++counter}`,
     preserve_figma_ids: true,
+    prefer_path_for_geometry: true,
     ...resolveImageSrc && { resolve_image_src: resolveImageSrc }
   };
   const { document: packed } = iofigma.kiwi.convertPageToScene(page, context);

package/dist/cli.mjs

@@ -6,7 +6,7 @@ import {
   exportSettingToRenderOptions,
   figFileToRestLikeDocument,
   iofigma
-} from "./chunk-PK5L35ID.mjs";
+} from "./chunk-YI7PIULZ.mjs";
 
 // cli.ts
 import {
@@ -15,9 +15,11 @@ import {
   mkdirSync,
   writeFileSync,
   existsSync,
-  statSync
+  statSync,
+  mkdtempSync
 } from "fs";
 import path from "path";
+import { tmpdir } from "os";
 import { program } from "commander";
 var FORMAT_SET = /* @__PURE__ */ new Set(["png", "jpeg", "webp", "pdf", "svg"]);
 var DOCUMENT_JSON = "document.json";
@@ -31,6 +33,7 @@ var EXT_BY_FORMAT = {
   png: "png",
   jpeg: "jpeg",
   jpg: "jpeg",
+  webp: "webp",
   svg: "svg",
   pdf: "pdf"
 };
@@ -174,9 +177,9 @@ async function main() {
   ).argument(
     "<input>",
     "Path to .fig, JSON file (REST API response), or directory containing document.json (and optionally images/)"
-  ).requiredOption(
+  ).option(
     "--out <path>",
-    "Output file path (single node) or output directory (--export-all)"
+    "Output file path (single node) or output directory (--export-all); when omitted, uses OS temp directory (valid with --export-all or with both --format and --node)"
   ).option(
     "--images <dir>",
     "Directory of image files for REST API document (optional; not used if <input> is a dir with images/)"
@@ -198,9 +201,6 @@ async function main() {
       const exportAll = options.exportAll === true;
       const nodeId = String(options.node ?? "").trim();
       const explicitImagesDir = typeof options.images === "string" ? options.images : void 0;
-      if (!outPath) {
-        program.error("--out is required");
-      }
       const { documentPath, imagesDir, isRestJson } = resolveInput(
         input.trim(),
         explicitImagesDir
@@ -209,17 +209,20 @@ async function main() {
         if (nodeId) {
           program.error("--node must not be used with --export-all");
         }
-        const outDir = path.resolve(outPath);
-        if (existsSync(outDir)) {
-          const stat = statSync(outDir);
-          if (!stat.isDirectory()) {
-            program.error(
-              "--out must be a directory when using --export-all"
-            );
+        const outDir = outPath ? (() => {
+          const resolved = path.resolve(outPath);
+          if (existsSync(resolved)) {
+            const stat = statSync(resolved);
+            if (!stat.isDirectory()) {
+              program.error(
+                "--out must be a directory when using --export-all"
+              );
+            }
+          } else {
+            mkdirSync(resolved, { recursive: true });
           }
-        } else {
-          mkdirSync(outDir, { recursive: true });
-        }
+          return resolved;
+        })() : mkdtempSync(path.join(tmpdir(), "refig-export-"));
         await runExportAll(
           documentPath,
           outDir,
@@ -234,8 +237,28 @@ async function main() {
       const width = Number(options.width ?? 1024);
       const height = Number(options.height ?? 1024);
       const scale = Number(options.scale ?? 1);
-      await runSingleNode(documentPath, nodeId, path.resolve(outPath), {
-        format: typeof options.format === "string" ? options.format : void 0,
+      const formatOption = typeof options.format === "string" ? options.format : void 0;
+      let singleOutPath;
+      if (outPath) {
+        singleOutPath = path.resolve(outPath);
+      } else {
+        if (!formatOption) {
+          program.error(
+            "When --out is omitted, both --node and --format are required"
+          );
+        }
+        const format = formatOption.toLowerCase();
+        if (!FORMAT_SET.has(format)) {
+          program.error(`Unsupported --format "${format}"`);
+        }
+        const ext = EXT_BY_FORMAT[format] ?? "png";
+        singleOutPath = path.join(
+          tmpdir(),
+          `refig-${sanitizeForFilename(nodeId)}.${ext}`
+        );
+      }
+      await runSingleNode(documentPath, nodeId, singleOutPath, {
+        format: formatOption,
         width,
         height,
         scale,

package/dist/index.mjs

@@ -4,7 +4,7 @@ import {
   collectExportsFromDocument,
   exportSettingToRenderOptions,
   resolveMimeType
-} from "./chunk-PK5L35ID.mjs";
+} from "./chunk-YI7PIULZ.mjs";
 
 // index.ts
 import { readFileSync } from "fs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grida/refig",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "private": false,
   "description": "Headless Figma renderer — render .fig and REST API JSON to PNG/JPEG/WebP/PDF/SVG",
   "keywords": [
@@ -55,7 +55,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@grida/canvas-wasm": "0.90.0-canary.7",
+    "@grida/canvas-wasm": "0.90.0-canary.8",
     "commander": "^12.1.0"
   },
   "devDependencies": {