refig - render images from .fig or cached figma rest-api response

.gitignore

@@ -205,4 +205,10 @@ node-compile-cache/
 /target
 
 # Test artifacts
-**/__tests__/artifacts/
+**/__tests__/artifacts/
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class

.tools/README.md

@@ -6,9 +6,10 @@ This directory contains miscellaneous, trivial scripts that are useful for inter
 
 ## Available Tools
 
-| Tool           | Description                                   | Usage                |
-| -------------- | --------------------------------------------- | -------------------- |
-| `pbdump.swift` | Dump macOS clipboard contents (all UTI types) | `swift pbdump.swift` |
+| Tool               | Description                                                 | Usage                                                                |
+| ------------------ | ----------------------------------------------------------- | -------------------------------------------------------------------- |
+| `pbdump.swift`     | Dump macOS clipboard contents (all UTI types)               | `swift pbdump.swift`                                                 |
+| `figma_archive.py` | Archive a Figma file via REST API (document.json + images/) | `python .tools/figma_archive.py --filekey <key> --archive-dir <dir>` |
 
 ## Contributing
 

.tools/figma_archive.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+# https://gist.github.com/softmarshmallow/27ad65dfa5babc2c67b41740f1f05791
+"""
+Archive a Figma file via REST API: document.json (with geometry) and images/*.
+
+Stdlib only. Usage:
+
+  python .tools/figma_archive.py --filekey <key> --archive-dir <dir> [--x-figma-token <token>]
+  # or set FIGMA_TOKEN in the environment
+
+Output layout:
+  <archive-dir>/document.json   — GET /v1/files/:key?geometry=paths
+  <archive-dir>/images/<ref>.<ext>  — from GET /v1/files/:key/images, then download each URL
+"""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+FIGMA_BASE = "https://api.figma.com"
+ENV_TOKEN = "FIGMA_TOKEN"
+
+# Content-Type -> file extension for image fills
+MIME_EXT = {
+    "image/png": "png",
+    "image/jpeg": "jpeg",
+    "image/jpg": "jpg",
+    "image/webp": "webp",
+    "image/gif": "gif",
+}
+
+
+def get_token(flag_value: str | None) -> str:
+    token = flag_value or os.environ.get(ENV_TOKEN)
+    if not token or not token.strip():
+        print(f"error: provide --x-figma-token or set {ENV_TOKEN}", file=sys.stderr)
+        sys.exit(1)
+    return token.strip()
+
+
+def api_get(url: str, token: str) -> bytes:
+    req = Request(url, method="GET", headers={"X-Figma-Token": token})
+    try:
+        with urlopen(req, timeout=60) as resp:
+            return resp.read()
+    except HTTPError as e:
+        print(f"error: HTTP {e.code} {e.reason}: {url}", file=sys.stderr)
+        if e.fp:
+            body = e.fp.read().decode("utf-8", errors="replace")[:500]
+            print(body, file=sys.stderr)
+        sys.exit(1)
+    except URLError as e:
+        print(f"error: request failed: {e.reason}", file=sys.stderr)
+        sys.exit(1)
+
+
+def fetch_document(file_key: str, token: str) -> dict:
+    url = f"{FIGMA_BASE}/v1/files/{file_key}?geometry=paths"
+    raw = api_get(url, token)
+    return json.loads(raw.decode("utf-8"))
+
+
+def fetch_image_fills(file_key: str, token: str) -> dict[str, str]:
+    url = f"{FIGMA_BASE}/v1/files/{file_key}/images"
+    raw = api_get(url, token)
+    data = json.loads(raw.decode("utf-8"))
+    meta = data.get("meta") or {}
+    images = meta.get("images") or {}
+    return {k: v for k, v in images.items() if v}
+
+
+def download_image(url: str) -> tuple[bytes, str]:
+    # Image URLs from the Images API are pre-signed; no token needed.
+    req = Request(url, method="GET")
+    with urlopen(req, timeout=120) as resp:
+        data = resp.read()
+        content_type = (
+            (resp.headers.get("Content-Type") or "").split(";")[0].strip().lower()
+        )
+        ext = MIME_EXT.get(content_type) or "png"
+        return data, ext
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Archive a Figma file (document.json + images/) via REST API."
+    )
+    parser.add_argument(
+        "--x-figma-token",
+        metavar="TOKEN",
+        default=None,
+        help=f"Figma personal access token (or set {ENV_TOKEN})",
+    )
+    parser.add_argument("--filekey", required=True, help="Figma file key")
+    parser.add_argument(
+        "--archive-dir",
+        required=True,
+        type=Path,
+        help="Output directory (document.json and images/ will be written here)",
+    )
+    args = parser.parse_args()
+
+    token = get_token(args.x_figma_token)
+    archive_dir = args.archive_dir.resolve()
+    file_key = args.filekey.strip()
+
+    archive_dir.mkdir(parents=True, exist_ok=True)
+    images_dir = archive_dir / "images"
+    images_dir.mkdir(exist_ok=True)
+
+    print("Fetching document (geometry=paths)...", flush=True)
+    doc = fetch_document(file_key, token)
+    document_path = archive_dir / "document.json"
+    with open(document_path, "w", encoding="utf-8") as f:
+        json.dump(doc, f, indent=2, ensure_ascii=False)
+    doc_size = document_path.stat().st_size
+    print(f"Wrote document.json ({doc_size:,} bytes)", flush=True)
+
+    print("Fetching image fills list...", flush=True)
+    ref_to_url = fetch_image_fills(file_key, token)
+    n_images = len(ref_to_url)
+    if not ref_to_url:
+        print("No image fills.", flush=True)
+        return
+
+    print(f"Downloading {n_images} image(s)...", flush=True)
+    total_bytes = 0
+    ok = 0
+    for i, (ref, url) in enumerate(ref_to_url.items(), 1):
+        # Ref can contain characters unsafe for filenames; sanitize to alphanumeric + underscore
+        safe_ref = "".join(c if c.isalnum() or c in "._-" else "_" for c in ref)
+        if not safe_ref:
+            safe_ref = f"ref_{i}"
+        try:
+            data, ext = download_image(url)
+            out_path = images_dir / f"{safe_ref}.{ext}"
+            out_path.write_bytes(data)
+            size_k = len(data) / 1024
+            total_bytes += len(data)
+            ok += 1
+            print(f"  [{i}/{n_images}] {safe_ref}.{ext} ({size_k:.1f} KB)", flush=True)
+        except Exception as e:
+            print(f"  [{i}/{n_images}] {safe_ref} — failed: {e}", file=sys.stderr)
+
+    total_mb = total_bytes / (1024 * 1024)
+    print(
+        f"Done. document.json ({doc_size:,} B) + {ok}/{n_images} images ({total_mb:.2f} MB) in {archive_dir}.",
+        flush=True,
+    )
+
+
+if __name__ == "__main__":
+    main()

apps/blog/blog/refig/post.md

@@ -0,0 +1,82 @@
+---
+title: Introducing refig — a headless Figma renderer for real-world pipelines
+description: Export Figma designs to PNG/SVG/PDF without a browser. Deterministic, CI-friendly rendering from .fig or REST JSON—built for tooling, previews, and automation.
+slug: refig
+authors: universe
+date: 2026-02-17
+tags: [figma, rendering, ci, wasm, skia, tooling]
+hide_table_of_contents: false
+---
+
+Figma exports are easy—until exporting becomes **infrastructure**.
+
+Teams start with “click Export” and end up needing **thumbnails**, **asset pipelines**, **visual diffs**, and **repeatable builds**. That’s where the usual options start to hurt:
+
+- A headless browser is slow and flaky in CI.
+- The Figma Images API is great, but it’s still **a network dependency** (tokens, rate limits, availability).
+- Signed image URLs expire, which makes “render later” workflows fragile.
+- Offline or air‑gapped environments simply can’t rely on API calls.
+
+**refig** is built for that gap.
+
+<!-- truncate -->
+
+## What is refig?
+
+**`@grida/refig`** (“render figma”) is a **headless Figma renderer**. It turns a Figma document + node id into **PNG, JPEG, WebP, PDF, or SVG**—without opening Figma and without driving a browser UI.
+
+It works with:
+
+- **`.fig` files** (offline, reproducible)
+- **Figma REST API file JSON** (`GET /v1/files/:key`) when you already have your own ingestion layer
+
+You can use it as a **CLI** (`refig`) or as a **library** in Node.js and the browser.
+
+- Technical reference and usage: [`@grida/refig` on npm](https://www.npmjs.com/package/@grida/refig)
+
+## The idea: deterministic rendering you can build on
+
+When rendering is deterministic and programmable, a bunch of workflows become straightforward:
+
+- **Preview services**: generate thumbnails for files, pages, frames, components.
+- **Asset pipelines**: treat “Export presets” as build artifacts (commit, cache, publish).
+- **Visual regression tests**: render the same node on every PR and diff outputs.
+- **Offline archives**: store `.fig` snapshots and reproduce outputs later—no tokens, no network.
+- **In-app previews**: render inside your product (browser entrypoint) to show design snapshots.
+
+In other words: refig is less about “export an image” and more about making Figma rendering a reliable building block.
+
+## What refig intentionally doesn’t do
+
+refig is opinionated about scope so it stays composable:
+
+- **No auth / fetching**: you bring your own token storage, HTTP client, and caching.
+- **No design-to-code**: this is rendering (pixels / SVG / PDF), not HTML/CSS/Flutter generation.
+- **No editor**: read + render only.
+
+## A tiny taste (CLI)
+
+If you just want to feel what it’s like:
+
+```sh
+# Render a node from a .fig export
+npx @grida/refig ./design.fig --node "1:23" --out ./out.png
+
+# Or render from REST API JSON you fetched elsewhere
+npx @grida/refig ./document.json --node "1:23" --out ./out.svg
+```
+
+From there, most teams graduate quickly to: “render N nodes”, “render on every commit”, or “render on demand”.
+
+## Where this is headed
+
+We’re treating refig as a foundation for “design → build” automation:
+
+- render outputs that are **repeatable**
+- workflows that can run **in CI**
+- tooling that can work **offline**
+
+If that sounds like your problem, start with the docs (high-level) and the npm page (full API/CLI reference), then wire it into the pipeline you already have:
+
+- [`@grida/refig` docs](https://grida.co/docs/packages/@grida/refig)
+- [`@grida/refig` on npm](https://www.npmjs.com/package/@grida/refig)

crates/grida-canvas-wasm/lib/__test__/environment-node-api-spec-validation.test.ts

@@ -61,6 +61,7 @@ const EXPECTED_FUNCTIONS = [
 
   // images
   { name: "_add_image", paramCount: 3 },
+  { name: "_add_image_with_rid", paramCount: 5 },
   { name: "_get_image_bytes", paramCount: 3 },
   { name: "_get_image_size", paramCount: 3 },
 

crates/grida-canvas-wasm/lib/__test__/environment-node-raster-export.test.ts

@@ -70,4 +70,94 @@ describe("raster export (node)", () => {
     expectPng(data);
     writePng("gradient-rect", data);
   }, 30_000);
+
+  it("registers fixture image with addImageWithId and renders with custom RID", async () => {
+    const imagePath = resolve(process.cwd(), "../../fixtures/images/stripes.png");
+    const imageBytes = new Uint8Array(readFileSync(imagePath));
+
+    const doc = {
+      version: "0.90.0-beta+20260108",
+      document: {
+        nodes: {
+          "image-rect": {
+            id: "image-rect",
+            name: "image-rect",
+            locked: false,
+            active: true,
+            layout_positioning: "absolute",
+            layout_inset_top: 24,
+            layout_inset_left: 24,
+            opacity: 1,
+            z_index: 0,
+            rotation: 0,
+            layout_target_width: 208,
+            layout_target_height: 208,
+            type: "rectangle",
+            corner_radius: 16,
+            effects: [],
+            stroke_width: 0,
+            stroke_cap: "butt",
+            fill_paints: [
+              {
+                type: "image",
+                active: true,
+                src: "res://images/test-fixture-stripes",
+                fit: "cover",
+                opacity: 1,
+                blend_mode: "normal",
+                filters: {
+                  exposure: 0,
+                  contrast: 0,
+                  saturation: 0,
+                  temperature: 0,
+                  tint: 0,
+                  highlights: 0,
+                  shadows: 0,
+                },
+              },
+            ],
+          },
+          main: {
+            type: "scene",
+            id: "main",
+            name: "main",
+            active: true,
+            locked: false,
+            constraints: { children: "multiple" },
+            guides: [],
+            edges: [],
+            background_color: { r: 0.96, g: 0.96, b: 0.96, a: 1 },
+          },
+        },
+        links: { main: ["image-rect"] },
+        scenes_ref: ["main"],
+        bitmaps: {},
+        images: {},
+        properties: {},
+      },
+    };
+
+    const canvas = await createCanvas({
+      backend: "raster",
+      width: 256,
+      height: 256,
+      useEmbeddedFonts: true,
+    });
+
+    const result = canvas.addImageWithId(imageBytes, "res://images/test-fixture-stripes");
+    expect(result).not.toBe(false);
+    expect((result as { width: number; height: number }).width).toBeGreaterThan(0);
+    expect((result as { width: number; height: number }).height).toBeGreaterThan(0);
+
+    canvas.loadScene(JSON.stringify(doc));
+
+    const { data } = canvas.exportNodeAs("image-rect", {
+      format: "PNG",
+      constraints: { type: "none", value: 1 },
+    });
+
+    expectPng(data);
+    writePng("add-image-with-id-stripes", data);
+    canvas.dispose();
+  }, 30_000);
 });