@grida/refig 0.0.0 → 0.0.1

package/README.md

@@ -1,10 +1,28 @@
 # `@grida/refig`
 
-> **re**nder **fig**ma — headless Figma renderer in the spirit of [`resvg`](https://github.com/nicolo-ribaudo/resvg-js)
+> **re**nder **fig**ma — headless Figma renderer (Node.js + browser) in the spirit of [`resvg-js`](https://github.com/nicolo-ribaudo/resvg-js)
 
-Render Figma documents to **PNG, JPEG, WebP, PDF, and SVG** without Figma Desktop and without a browser.
+Render Figma documents to **PNG, JPEG, WebP, PDF, and SVG** in **Node.js (no browser required)** or directly in the **browser**.
 
-Pass a `.fig` file or a Figma REST API JSON response, pick a node, get pixels.
+Use a `.fig` export (offline) or a Figma REST API file JSON response (`GET /v1/files/:key`), pick a node ID, and get pixels.
+
+## Features (checklist)
+
+- [x] Render from **`.fig` files** (offline / no API calls)
+- [x] Render from **Figma REST API JSON** (bring your own auth + HTTP client)
+- [x] Output formats: **PNG, JPEG, WebP, PDF, SVG**
+- [x] **CLI** (`refig`) and **library API** (`FigmaDocument`, `FigmaRenderer`)
+- [x] **Node.js** + **browser** entrypoints (`@grida/refig`, `@grida/refig/browser`)
+- [x] IMAGE fills supported via **embedded `.fig` images** or a **local `images/` directory** for REST JSON
+- [x] Batch export with **`--export-all`** (renders nodes with Figma export presets)
+- [x] WASM + Skia-backed renderer via `@grida/canvas-wasm`
+
+## Use cases
+
+- Export assets in CI (deterministic, no network calls required)
+- Generate thumbnails / previews from `.fig` or REST JSON
+- Offline / air-gapped rendering from `.fig` exports
+- In-browser previews with `@grida/refig/browser`
 
 ## Install
 
@@ -26,7 +44,7 @@ Both entrypoints export the same core API (`FigmaDocument`, `FigmaRenderer`, typ
 ### Render from a `.fig` file
 
 ```ts
-import { readFileSync, writeFileSync } from "node:fs";
+import { writeFileSync } from "node:fs";
 import { FigmaDocument, FigmaRenderer } from "@grida/refig";
 
 const doc = FigmaDocument.fromFile("path/to/file.fig");
@@ -92,6 +110,7 @@ renderer.dispose();
 ```ts
 import { FigmaDocument, FigmaRenderer } from "@grida/refig/browser";
 
+// `file` is a File from <input type="file">, drag-and-drop, etc.
 // Uint8Array from a File input, fetch(), or drag-and-drop
 const figBytes: Uint8Array = await file
   .arrayBuffer()
@@ -172,6 +191,13 @@ interface RefigRenderResult {
 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>
+```
+
 ### Usage
 
 **`<input>`** can be:
@@ -220,10 +246,41 @@ refig ./design.fig --export-all --out ./exports
 # Scale 2x, custom dimensions
 refig ./design.fig --node "1:23" --out ./out.png --width 512 --height 512 --scale 2
 
-# No-install (CI one-liner)
+# 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
 ```
 
+### Quick test via `figma_archive.py` (REST API → `document.json` + `images/`)
+
+If you want an end-to-end test from a real Figma file using the REST API, you can generate a local “project directory” that refig can consume directly.
+
+1. Archive a Figma file (stdlib-only Python script):
+
+- Script: [`figma_archive.py` (gist)](https://gist.github.com/softmarshmallow/27ad65dfa5babc2c67b41740f1f05791)
+- (For repo contributors, it’s also in this monorepo at `.tools/figma_archive.py`.)
+- Save the script locally as `figma_archive.py`, then run:
+
+```sh
+# File key is the "<key>" part of `https://www.figma.com/file/<key>/...`
+python3 figma_archive.py --x-figma-token "<token>" --filekey "<key>" --archive-dir ./my-figma-export
+```
+
+This writes:
+
+- `./my-figma-export/document.json` (with `geometry=paths`)
+- `./my-figma-export/images/<ref>.<ext>` (image fills downloaded from `/v1/files/:key/images`)
+
+2. Render using the directory as `<input>`:
+
+```sh
+# Single node
+refig ./my-figma-export --node "1:23" --out ./out.png
+
+# Or export everything with Figma export presets
+refig ./my-figma-export --export-all --out ./exports
+```
+
 ### Export all (`--export-all`)
 
 With **`--export-all`**, refig walks the document and renders every node that has [Figma export settings](https://www.figma.com/developers/api#exportsetting-type) — one file per (node, setting), using that setting’s format, suffix, and constraint. Both **REST API JSON** (e.g. `GET /v1/files/:key`) and **`.fig` files** are supported when the file includes export settings.
@@ -282,15 +339,6 @@ REST JSON ───┘
 
 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.
 
-## Features
-
-- **Multiple output formats** — `png`, `jpeg`, `webp`, `pdf`, `svg`
-- **`.fig` file input** — render from exported `.fig` without API calls
-- **REST API JSON input** — render from document JSON you already have
-- **CI-friendly** — headless, deterministic, no browser required
-- **Browser-compatible** — `@grida/refig/browser` works in any modern browser
-- **WASM-powered** — Skia-backed rendering for pixel-accurate output
-
 ## Not planned
 
 - **Figma API fetching / auth** — bring your own tokens and HTTP client
@@ -316,7 +364,7 @@ Yes. Import from `@grida/refig/browser`. The core renderer uses `@grida/canvas-w
 
 ### What about fonts?
 
-The WASM runtime ships with embedded fallback fonts. Custom font loading (Google Fonts, local directories) is planned but not yet available.
+The WASM runtime ships with embedded fallback fonts (Geist / Geist Mono). **`loadFigmaDefaultFonts`** is enabled by default: the renderer loads the Figma default font set (Inter, Noto Sans KR/JP/SC, and optionally Noto Sans TC/HK and Noto Color Emoji) from CDN and registers them as fallbacks before the first render, so mixed-script and CJK text avoid tofu. Set **`loadFigmaDefaultFonts: false`** to disable (e.g. to avoid network or use only embedded fonts). Custom or other Google Fonts are **not** loaded by the renderer; the user is responsible for fetching font bytes and registering them with the canvas if needed.
 
 ## Contributing
 

package/dist/browser.d.mts

@@ -14,6 +14,14 @@ interface RefigRendererOptions {
      * @default true
      */
     useEmbeddedFonts?: boolean;
+    /**
+     * When true (default), the renderer ensures Figma default fonts (Inter, Noto Sans KR/JP/SC, etc.)
+     * are loaded from CDN and registered with the canvas before any scene is loaded.
+     * Reduces tofu for mixed-script and CJK text. Set to false to skip (e.g. to avoid network or use only embedded fonts).
+     * Custom fonts remain the user's responsibility.
+     * @default true
+     */
+    loadFigmaDefaultFonts?: boolean;
     /**
      * Map of Figma image ref (hash) to image bytes.
      * Used for REST API and .fig input so IMAGE fills render correctly.

package/dist/browser.mjs

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

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

@@ -13393,6 +13393,61 @@ var iofigma;
         ...map2.blendModeMap,
         PASS_THROUGH: "pass-through"
       };
+      function normalizeRestVectorNetworkToIR(rest) {
+        if (!Array.isArray(rest.vertices) || !Array.isArray(rest.segments) || !Array.isArray(rest.regions)) {
+          return null;
+        }
+        const vertexCount = rest.vertices.length;
+        const segmentCount = rest.segments.length;
+        for (const seg of rest.segments) {
+          if (typeof seg.start !== "number" || typeof seg.end !== "number" || seg.start < 0 || seg.start >= vertexCount || seg.end < 0 || seg.end >= vertexCount || !seg.startTangent || !seg.endTangent) {
+            return null;
+          }
+        }
+        for (const region of rest.regions) {
+          if (!Array.isArray(region.loops)) return null;
+          for (const loop of region.loops) {
+            if (!Array.isArray(loop)) return null;
+            for (const segIdx of loop) {
+              if (typeof segIdx !== "number" || segIdx < 0 || segIdx >= segmentCount) {
+                return null;
+              }
+            }
+          }
+        }
+        const vertices = rest.vertices.map(
+          (v) => ({
+            x: v.position?.x ?? 0,
+            y: v.position?.y ?? 0,
+            styleID: 0
+          })
+        );
+        const segments = rest.segments.map(
+          (seg) => ({
+            styleID: 0,
+            start: {
+              vertex: seg.start,
+              dx: seg.startTangent.x,
+              dy: seg.startTangent.y
+            },
+            end: {
+              vertex: seg.end,
+              dx: seg.endTangent.x,
+              dy: seg.endTangent.y
+            }
+          })
+        );
+        const regions = rest.regions.map(
+          (region) => {
+            const wr = region.windingRule?.toUpperCase?.();
+            const windingRule = wr === "EVENODD" || wr === "ODD" ? "ODD" : "NONZERO";
+            const loops = region.loops.map((loop) => ({ segments: loop }));
+            return { styleID: 0, windingRule, loops };
+          }
+        );
+        return { vertices, segments, regions };
+      }
+      map2.normalizeRestVectorNetworkToIR = normalizeRestVectorNetworkToIR;
     })(map = restful2.map || (restful2.map = {}));
     let factory;
     ((factory2) => {
@@ -13699,6 +13754,7 @@ var iofigma;
           try {
             const vectorNetwork = index_default2.fromSVGPathData(pathData);
             const bbox = index_default2.getBBox(vectorNetwork);
+            const strokeAsFill = options.strokeAsFill === true;
             return {
               id: childId,
               ...base_node_trait({
@@ -13716,12 +13772,25 @@ var iofigma;
                 ],
                 size: { x: bbox.width, y: bbox.height }
               }),
-              ...options.useFill ? fills_trait(parentNode.fills, context, imageRefsUsed) : {},
-              ...options.useStroke ? stroke_trait(parentNode, context, imageRefsUsed) : stroke_trait(
-                { strokes: [], strokeWeight: 0 },
-                context,
-                imageRefsUsed
-              ),
+              ...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: "vector",
               vector_network: vectorNetwork,
@@ -13770,7 +13839,7 @@ var iofigma;
               node2,
               childId,
               name,
-              { useFill: false, useStroke: true }
+              { useFill: false, useStroke: false, strokeAsFill: true }
             );
             if (childNode) {
               nodes[childId] = childNode;
@@ -14013,6 +14082,37 @@ var iofigma;
           case "REGULAR_POLYGON":
           case "STAR":
           case "VECTOR": {
+            const useRestVectorNetwork = context.disable_volatile_apis !== true && "vectorNetwork" in node && node.vectorNetwork != null;
+            if (useRestVectorNetwork) {
+              try {
+                const ir = restful2.map.normalizeRestVectorNetworkToIR(
+                  node.vectorNetwork
+                );
+                if (ir) {
+                  const gridaVectorNetwork = {
+                    vertices: ir.vertices.map((v) => [v.x, v.y]),
+                    segments: ir.segments.map((seg) => ({
+                      a: seg.start.vertex,
+                      b: seg.end.vertex,
+                      ta: [seg.start.dx, seg.start.dy],
+                      tb: [seg.end.dx, seg.end.dy]
+                    }))
+                  };
+                  return {
+                    id: gridaId,
+                    ...base_node_trait(node),
+                    ...positioning_trait(node),
+                    ...fills_trait(node.fills, context, imageRefsUsed),
+                    ...stroke_trait(node, context, imageRefsUsed),
+                    ...corner_radius_trait(node),
+                    ...effects_trait(node.effects),
+                    type: "vector",
+                    vector_network: gridaVectorNetwork
+                  };
+                }
+              } catch {
+              }
+            }
             return {
               id: gridaId,
               ...base_node_trait(node),
@@ -14363,7 +14463,11 @@ var iofigma;
           const f = fmt(s.imageType);
           if (!f) return null;
           const c = s.constraint;
-          return { format: f, suffix: s.suffix ?? "", constraint: { type: cstr(c?.type), value: c?.value ?? 1 } };
+          return {
+            format: f,
+            suffix: s.suffix ?? "",
+            constraint: { type: cstr(c?.type), value: c?.value ?? 1 }
+          };
         }).filter((x) => x !== null);
         return exportSettings.length ? { exportSettings } : {};
       }
@@ -15607,6 +15711,60 @@ var grida;
 })(grida || (grida = {}));
 var cloneWithUndefinedValues = (obj) => Object.fromEntries(Object.keys(obj).map((key) => [key, void 0]));
 
+// figma-default-fonts.ts
+var FIGMA_DEFAULT_FONT_ENTRIES = [
+  {
+    family: "Inter",
+    url: "https://fonts.gstatic.com/s/inter/v19/UcCo3FwrK3iLTfvlaQc78lA2.ttf"
+  },
+  {
+    family: "Noto Sans KR",
+    url: "https://fonts.gstatic.com/s/notosanskr/v37/PbykFmXiEBPT4ITbgNA5Cgm21nTs4JMMuA.ttf"
+  },
+  {
+    family: "Noto Sans JP",
+    url: "https://fonts.gstatic.com/s/notosansjp/v54/-F62fjtqLzI2JPCgQBnw7HFoxgIO2lZ9hg.ttf"
+  },
+  {
+    family: "Noto Sans SC",
+    url: "https://fonts.gstatic.com/s/notosanssc/v38/k3kXo84MPvpLmixcA63oeALhKYiJ-Q7m8w.ttf"
+  },
+  {
+    family: "Noto Sans TC",
+    url: "https://fonts.gstatic.com/s/notosanstc/v37/-nF7OG829Oofr2wohFbTp9iFPysLA_ZJ1g.ttf"
+  },
+  {
+    family: "Noto Sans HK",
+    url: "https://fonts.gstatic.com/s/notosanshk/v33/nKKQ-GM_FYFRJvXzVXaAPe9hNHB3Eu7mOQ.ttf"
+  },
+  {
+    family: "Noto Color Emoji",
+    url: "https://fonts.gstatic.com/s/notocoloremoji/v35/Yq6P-KqIXTD0t4D9z1ESnKM3-HpFab5s79iz64w.ttf"
+  }
+];
+var FIGMA_DEFAULT_FALLBACK_ORDER = [
+  "Inter",
+  "Noto Sans KR",
+  "Noto Sans JP",
+  "Noto Sans SC",
+  "Noto Sans TC",
+  "Noto Sans HK",
+  "Noto Color Emoji"
+];
+async function ensureFigmaDefaultFonts(canvas) {
+  for (const entry of FIGMA_DEFAULT_FONT_ENTRIES) {
+    const res = await fetch(entry.url);
+    if (!res.ok) {
+      throw new Error(
+        `Figma default font fetch failed: ${entry.family} ${res.status} ${res.statusText}`
+      );
+    }
+    const buffer = await res.arrayBuffer();
+    canvas.addFont(entry.family, new Uint8Array(buffer));
+  }
+  canvas.setFallbackFonts(FIGMA_DEFAULT_FALLBACK_ORDER);
+}
+
 // lib.ts
 var FigmaDocument = class {
   /**
@@ -15960,6 +16118,11 @@ var FigmaRenderer = class {
       height,
       useEmbeddedFonts: this.options.useEmbeddedFonts ?? true
     });
+    if (this.options.loadFigmaDefaultFonts !== false) {
+      await ensureFigmaDefaultFonts(
+        this._canvas
+      );
+    }
     return this._canvas;
   }
   loadScene(canvas, nodeId) {

package/dist/cli.mjs

@@ -6,7 +6,7 @@ import {
   exportSettingToRenderOptions,
   figFileToRestLikeDocument,
   iofigma
-} from "./chunk-DAHUXARL.mjs";
+} from "./chunk-PK5L35ID.mjs";
 
 // cli.ts
 import {
@@ -80,7 +80,7 @@ function exportAllOutputBasename(nodeId, suffix, format) {
   const name = safeSuffix ? `${safeId}_${safeSuffix}` : safeId;
   return `${name}.${ext}`;
 }
-async function runExportAll(documentPath, outDir, imagesDir) {
+async function runExportAll(documentPath, outDir, imagesDir, skipDefaultFonts) {
   const isFig = documentPath.toLowerCase().endsWith(".fig");
   let document;
   let items;
@@ -109,6 +109,9 @@ async function runExportAll(documentPath, outDir, imagesDir) {
       rendererOptions = { images: readImagesFromDir(imagesDir) };
     }
   }
+  if (skipDefaultFonts || process.env.REFIG_SKIP_DEFAULT_FONTS === "1") {
+    rendererOptions = { ...rendererOptions, loadFigmaDefaultFonts: false };
+  }
   if (items.length === 0) {
     process.stdout.write("No nodes with export settings found.\n");
     return;
@@ -144,6 +147,9 @@ async function runSingleNode(documentPath, nodeId, outPath, opts) {
   const isJson = documentPath.toLowerCase().endsWith(".json");
   const document = isJson ? new FigmaDocument(JSON.parse(readFileSync(documentPath, "utf8"))) : new FigmaDocument(new Uint8Array(readFileSync(documentPath)));
   const rendererOptions = isJson && opts.imagesDir ? { images: readImagesFromDir(opts.imagesDir) } : {};
+  if (opts.skipDefaultFonts || process.env.REFIG_SKIP_DEFAULT_FONTS === "1") {
+    rendererOptions.loadFigmaDefaultFonts = false;
+  }
   const renderer = new FigmaRenderer(document, rendererOptions);
   try {
     const result = await renderer.render(nodeId, {
@@ -183,7 +189,10 @@ async function main() {
   ).option(
     "--format <fmt>",
     "png | jpeg | webp | pdf | svg (single-node only; default: from --out extension)"
-  ).option("--width <px>", "Viewport width (single-node only)", "1024").option("--height <px>", "Viewport height (single-node only)", "1024").option("--scale <n>", "Raster scale factor (single-node only)", "1").action(
+  ).option("--width <px>", "Viewport width (single-node only)", "1024").option("--height <px>", "Viewport height (single-node only)", "1024").option("--scale <n>", "Raster scale factor (single-node only)", "1").option(
+    "--skip-default-fonts",
+    "Do not load Figma default fonts (same as REFIG_SKIP_DEFAULT_FONTS=1)"
+  ).action(
     async (input, options) => {
       const outPath = String(options.out ?? "").trim();
       const exportAll = options.exportAll === true;
@@ -211,7 +220,12 @@ async function main() {
         } else {
           mkdirSync(outDir, { recursive: true });
         }
-        await runExportAll(documentPath, outDir, imagesDir);
+        await runExportAll(
+          documentPath,
+          outDir,
+          imagesDir,
+          options.skipDefaultFonts === true
+        );
         return;
       }
       if (!nodeId) {
@@ -225,7 +239,8 @@ async function main() {
         width,
         height,
         scale,
-        imagesDir
+        imagesDir,
+        skipDefaultFonts: options.skipDefaultFonts === true
       });
     }
   );

package/dist/index.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grida/refig",
-  "version": "0.0.0",
+  "version": "0.0.1",
   "private": false,
   "description": "Headless Figma renderer — render .fig and REST API JSON to PNG/JPEG/WebP/PDF/SVG",
   "keywords": [
@@ -21,7 +21,7 @@
     "wasm",
     "webp"
   ],
-  "homepage": "https://github.com/gridaco/grida/tree/main/packages/grida-canvas-sdk-render-figma",
+  "homepage": "https://grida.co/docs/packages/@grida/refig",
   "bugs": "https://github.com/gridaco/grida/issues",
   "license": "MIT",
   "author": "softmarshmallow",
@@ -55,11 +55,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@grida/canvas-wasm": "0.90.0-canary.6",
+    "@grida/canvas-wasm": "0.90.0-canary.7",
     "commander": "^12.1.0"
   },
   "devDependencies": {
-    "@figma/rest-api-spec": "0.35.0",
+    "@figma/rest-api-spec": "0.36.0",
     "fflate": "^0.8.2",
     "tsup": "^8.5.0"
   },