@grida/refig 0.0.2 → 0.0.4

package/README.md

@@ -6,6 +6,8 @@ Render Figma documents to **PNG, JPEG, WebP, PDF, and SVG** in **Node.js (no bro
 
 Use a `.fig` export (offline) or a Figma REST API file JSON response (`GET /v1/files/:key`), pick a node ID, and get pixels.
 
+Refig aims to render designs as faithfully as possible to the original. See [Known limitations](#known-limitations) for current exceptions.
+
 ## Features (checklist)
 
 - [x] Render from **`.fig` files** (offline / no API calls)
@@ -14,6 +16,7 @@ Use a `.fig` export (offline) or a Figma REST API file JSON response (`GET /v1/f
 - [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] **Bring-your-own-font** — supply custom font files for designs that use non-default typefaces
 - [x] Batch export with **`--export-all`** (renders nodes with Figma export presets)
 - [x] WASM + Skia-backed renderer via `@grida/canvas-wasm`
 
@@ -105,6 +108,57 @@ const { data } = await renderer.render("<node-id>", { format: "png" });
 renderer.dispose();
 ```
 
+### Render with custom fonts
+
+Unlike images, fonts do not have a Figma API. Use **`listFontFamilies()`** to see which font families are used in your file (or a scoped node), then load those fonts and pass them to the renderer:
+
+```ts
+import { readFileSync, writeFileSync } from "node:fs";
+import { FigmaDocument, FigmaRenderer } from "@grida/refig";
+
+const doc = FigmaDocument.fromFile("path/to/file.fig");
+
+// 1. Discover font families used (omit rootNodeId for full document)
+const fontFamilies = doc.listFontFamilies("<node-id>"); // e.g. ["Inter", "Caveat", "Roboto"]
+
+// 2. Load your custom fonts (local FS, CDN, asset service, etc.)
+// Skip Figma defaults (Inter, Noto Sans KR/JP/SC, etc.) — the renderer loads those.
+const fonts: Record<string, Uint8Array> = {};
+for (const family of fontFamilies) {
+  if (
+    family === "Inter" ||
+    family.startsWith("Noto Sans") ||
+    family === "Noto Color Emoji"
+  )
+    continue;
+  fonts[family] = new Uint8Array(readFileSync(`./fonts/${family}.ttf`)); // adjust path to your font file structure
+}
+
+// 3. Render
+const renderer = new FigmaRenderer(doc, { fonts });
+const { data } = await renderer.render("<node-id>", { format: "png" });
+writeFileSync("out.png", data);
+renderer.dispose();
+```
+
+**CLI:** Use `--fonts <dir>` to pass a directory of TTF/OTF files (scanned recursively). Fonts are inferred from the name table; multiple files per family are grouped automatically. Use `--skip-default-fonts` to avoid loading Figma defaults (useful to verify custom font rendering):
+
+```sh
+refig ./figma-response.json --fonts ./my-fonts --node "1:23" --out out.png
+refig ./doc.json --fonts ./my-fonts --node "1:23" --out out.png --skip-default-fonts
+```
+
+With a project directory, place fonts in `fonts/` next to `document.json` (and optionally `images/`); refig auto-discovers them:
+
+```sh
+refig ./my-figma-export --node "1:23" --format png
+# Expects my-figma-export/document.json and, if present, my-figma-export/fonts/
+```
+
+Load **all** font files that match each family (variable or static) so the renderer can pick the right one for each text style, just like the original design. For multiple files per family (e.g. Regular, Bold, Italic), pass an array: `fonts: { "MyFamily": [regularBytes, boldBytes, italicBytes] }`.
+
+If the design uses **locally-installed fonts** (fonts the designer had on their machine), loading those from your OS may require extra scripts or tooling to locate and extract the font files. We do not provide such tooling.
+
 ## Quick start (Browser)
 
 ```ts
@@ -143,14 +197,21 @@ new FigmaDocument(json: Record<string, unknown>)
 // From a file path (Node only — @grida/refig)
 FigmaDocument.fromFile("path/to/file.fig")   // .fig binary
 FigmaDocument.fromFile("path/to/doc.json")   // REST API JSON
+
+// Font families used in the document (for bring-your-own-font)
+document.listFontFamilies(rootNodeId?: string): string[]
+// — rootNodeId: optional; scope to that node's subtree, or omit for full document
+// — returns unique family names; load all font files that match each family (VF or static)
 ```
 
 ### `FigmaRenderer`
 
 ```ts
 const renderer = new FigmaRenderer(document: FigmaDocument, options?: {
-  useEmbeddedFonts?: boolean;  // default: true
+  useEmbeddedFonts?: boolean;       // default: true
+  loadFigmaDefaultFonts?: boolean;  // default: true — Inter, Noto Sans KR/JP/SC, etc.
   images?: Record<string, Uint8Array>;  // image ref → bytes; used for REST API IMAGE fills
+  fonts?: Record<string, Uint8Array | Uint8Array[]>;  // font family → bytes (TTF/OTF); one or more files per family
 });
 
 const result = await renderer.render(nodeId: string, {
@@ -194,8 +255,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
@@ -205,50 +267,61 @@ pnpm dlx @grida/refig <input> --node <node-id> --out <path>
 - A **file**: path to a `.fig` file or a JSON file (Figma REST API response).
 - A **directory**: path to a folder that contains:
   - **`document.json`** — the REST API response (required),
-  - **`images/`** — directory of image assets (optional; used for REST API IMAGE fills).
+  - **`images/`** — directory of image assets (optional; used for REST API IMAGE fills),
+  - **`fonts/`** — directory of font files TTF/OTF (optional; scanned recursively).
 
-Using a directory avoids passing the document and images separately.
+Using a directory avoids passing the document, images, and fonts 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
+
+# Custom fonts (when design uses non-default typefaces)
+refig ./figma-response.json --fonts ./my-fonts --node "1:23" --out out.png
+refig ./doc.json --fonts ./fonts --node "1:23" --out out.png --skip-default-fonts
 
 # 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 +348,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 +364,19 @@ 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/`, `fonts/`)                                                                              |
+| `--images <dir>`       | no       |                                 | Directory of image assets for REST document (ignored if `<input>` is a dir with `images/`)                                                                                           |
+| `--fonts <dir>`        | no       |                                 | Directory of font files (TTF/OTF) for custom fonts (ignored if `<input>` is a dir with `fonts/`)                                                                                     |
+| `--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)                                                                                                                                               |
+| `--skip-default-fonts` | no       |                                 | Do not load Figma default fonts (Inter, Noto Sans, etc.); use only custom fonts from `--fonts` or `fonts/`                                                                           |
 
 ## Architecture
 
@@ -332,13 +407,19 @@ 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`
-- **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`  
-  (expects `my-figma-export/document.json` and, if present, `my-figma-export/images/`.)
+  `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/`** and **`fonts/`**. No need to pass `--images` or `--fonts` separately:  
+  `refig ./my-figma-export --node "1:23" --format png`  
+  (expects `my-figma-export/document.json` and, if present, `my-figma-export/images/` and `my-figma-export/fonts/`.)
 
 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.
 
+## Known limitations
+
+- **Rich text** — Text with mixed styles (e.g. bold and italic in the same paragraph) is not yet supported.
+- **Image transformation** — Complex image transforms from Figma designs are not yet properly aligned. Known issue; will fix.
+- **Emoji** — Rendered with Noto Color Emoji instead of Figma's platform emoji (Apple Color Emoji / Segoe UI Emoji). Output differs by design.
+
 ## Not planned
 
 - **Figma API fetching / auth** — bring your own tokens and HTTP client
@@ -364,7 +445,9 @@ Yes. Import from `@grida/refig/browser`. The core renderer uses `@grida/canvas-w
 
 ### What about fonts?
 
-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.
+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 fonts** (e.g. Caveat, Roboto, brand typefaces) use the bring-your-own-font flow: call **`document.listFontFamilies(rootNodeId?)`** to see which families are used, load those fonts yourself, then pass **`fonts: Record<string, Uint8Array>`** to `FigmaRenderer`. See [Render with custom fonts](#render-with-custom-fonts).
 
 ## Contributing
 
@@ -372,7 +455,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.d.mts

@@ -1,4 +1,5 @@
 import { ExportSetting } from '@figma/rest-api-spec';
+import { iofigma } from '@grida/io-figma';
 
 /**
  * @grida/refig — shared core (no node:fs, no DOM)
@@ -28,6 +29,14 @@ interface RefigRendererOptions {
      * Ref must match document references (e.g. 40-char hex for .fig, Figma image fill hash for REST).
      */
     images?: Record<string, Uint8Array>;
+    /**
+     * Custom fonts keyed by family name. Use the family name returned by
+     * `listFontFamilies()` (e.g. from Figma's `style.font_family`). Pass one or
+     * more font files per family; the canvas resolves the correct face per
+     * text style. Skip Figma defaults (Inter, Noto Sans KR/JP/SC, etc.) —
+     * those are loaded by `loadFigmaDefaultFonts`.
+     */
+    fonts?: Record<string, Uint8Array | Uint8Array[]>;
 }
 interface RefigRenderOptions {
     format: RefigRenderFormat;
@@ -44,21 +53,61 @@ interface RefigRenderResult {
     height: number;
 }
 type FigmaJsonDocument = Record<string, unknown>;
+type FigFileDocument = ReturnType<typeof iofigma.kiwi.parseFile>;
 declare class FigmaDocument {
     readonly sourceType: "fig-file" | "rest-api-json";
     /**
-     * For "fig-file" this is the raw bytes of the .fig file.
+     * For "fig-file" this is the raw bytes (Uint8Array) or a pre-parsed FigFileDocument
+     * (e.g. from parseFileFromStream for large ZIP files).
      * For "rest-api-json" this is the parsed REST API document JSON.
      */
-    readonly payload: Uint8Array | FigmaJsonDocument;
+    readonly payload: Uint8Array | FigmaJsonDocument | FigFileDocument;
+    /** Cached parsed FigFile (.fig only). */
+    private _figFile?;
+    /**
+     * Cache of ResolvedScene per rootNodeId. REST with images is not cached.
+     * Bounded to avoid unbounded memory growth in --export-all flows.
+     */
+    private _sceneCache;
+    /** Max cached scenes; evicts LRU when exceeded. */
+    private static readonly _MAX_SCENE_CACHE;
     /**
-     * @param input Raw `.fig` bytes (Uint8Array) or a parsed Figma REST API
-     *              document JSON object.
+     * @param input Raw `.fig` bytes (Uint8Array), a pre-parsed FigFileDocument
+     *              (e.g. from parseFileFromStream for large files), or REST JSON.
      *
      * For file-path convenience in Node, use `FigmaDocument.fromFile()` from
      * the `@grida/refig` entrypoint.
      */
-    constructor(input: Uint8Array | FigmaJsonDocument);
+    constructor(input: Uint8Array | FigmaJsonDocument | FigFileDocument);
+    /**
+     * Resolve document to Grida IR (scene JSON + images to register).
+     * On-demand, cached when deterministic (no images for REST).
+     * Cache is bounded (LRU eviction) to avoid OOM in --export-all flows.
+     * @internal
+     */
+    _resolve(rootNodeId?: string, images?: Record<string, Uint8Array>): ResolvedScene;
+    private _sceneCacheGet;
+    private _sceneCacheSet;
+    /** @internal */
+    private _restToScene;
+    /** @internal */
+    private _figToScene;
+    /**
+     * Returns the list of font family names used in this document.
+     *
+     * The result is family names only — no weights, PostScript names, or other metadata.
+     * That is intentional: in practice, you can load all TTF/OTF files for each family
+     * (variable or static) and pass them to the renderer; it will resolve the correct face
+     * per text style. We prioritize simple usage and accurate font selection over
+     * performance or resource-optimized patterns.
+     *
+     * When rootNodeId is omitted, traverses all pages so fonts from every page are included.
+     *
+     * @param rootNodeId — Optional. When provided, scope to that node's subtree. Omit for the full document (all pages).
+     * @returns Unique font family names (e.g. `["Inter", "Caveat", "Roboto"]`).
+     */
+    listFontFamilies(rootNodeId?: string): string[];
+    private _collectFontFamiliesFromSceneJson;
 }
 declare function resolveMimeType(format: RefigRenderFormat): string;
 type RestNode = Record<string, unknown> & {
@@ -81,6 +130,15 @@ declare function collectExportsFromDocument(json: FigmaJsonDocument): ExportItem
  * Constraint SCALE → scale; WIDTH/HEIGHT → width/height from constraint value and node aspect ratio.
  */
 declare function exportSettingToRenderOptions(node: RestNode, setting: ExportSetting): RefigRenderOptions;
+/**
+ * Resolved scene: Grida IR ready for canvas load.
+ * @internal
+ */
+interface ResolvedScene {
+    sceneJson: string;
+    images: Record<string, Uint8Array>;
+    imageRefsUsed?: string[];
+}
 declare class FigmaRenderer {
     readonly document: FigmaDocument;
     readonly options: RefigRendererOptions;

package/dist/browser.mjs

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