Add headless Node GIF rendering

Author: MesTTo

README.md

@@ -23,6 +23,7 @@ npm install @metta-ts/node        # CLI + file import! + a parallel matcher
 npm install @metta-ts/browser     # web entry + in-memory virtual file system
 npm install @metta-ts/py          # optional Python interop: pythonia or Pyodide
 npm install @metta-ts/prolog      # optional Prolog interop: SWI native or SWI-WASM
+npm install @metta-ts/grapher     # visual editor + browser or Node reduction GIFs
 ```
 
 For the command-line runner, install `@metta-ts/node` globally (or use `npx`):

examples/grapher-gif.ts

@@ -0,0 +1,25 @@
+// SPDX-FileCopyrightText: 2026 MesTTo
+//
+// SPDX-License-Identifier: MIT
+
+// Generate a reduction GIF in plain Node.js. Run with:
+//   pnpm --filter @metta-ts/examples grapher-gif
+
+import { writeFile } from "node:fs/promises";
+import { renderReductionGif } from "@metta-ts/grapher/node";
+
+const source = `
+(= (fact $n)
+   (if (> $n 0)
+       (* $n (fact (- $n 1)))
+       1))
+(fact 5)
+`;
+
+const gif = await renderReductionGif(source, {
+  view: "blocks",
+  width: 720,
+});
+
+await writeFile("factorial-reduction.gif", gif);
+console.log(`Wrote factorial-reduction.gif (${gif.byteLength} bytes)`);

examples/package.json

@@ -25,6 +25,7 @@
     "transactions": "tsx transactions.ts",
     "scaling": "tsx scaling.ts",
     "parallel-matcher": "tsx parallel-matcher.ts",
+    "grapher-gif": "tsx grapher-gif.ts",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
@@ -43,6 +44,8 @@
   },
   "devDependencies": {
     "esbuild": "0.27.7",
+    "gifenc": "1.0.3",
+    "sharp": "^0.35.3",
     "tsx": "^4.19.2",
     "typescript": "^5.0.0"
   }

packages/grapher/README.md

@@ -1,8 +1,9 @@
 # @metta-ts/grapher
 
-A browser editor for MeTTa programs. It renders the same atoms as a connected
-node graph or nested blocks, evaluates them with `@metta-ts/hyperon`, and
-exposes the model and rendering pieces for custom hosts.
+A visual editor and reduction renderer for MeTTa programs. It renders the same
+atoms as a connected node graph or nested blocks, evaluates them with
+`@metta-ts/hyperon`, and can export the reduction from a browser or plain
+Node.js.
 
 ## Install
 
@@ -51,12 +52,13 @@ view uses Canvas 2D text measurement, and animated transitions use
 `requestAnimationFrame`. Styles are embedded in the generated SVG, so there is
 no stylesheet to import.
 
-The parser, graph model, serialization, and evaluation helpers also run
-headlessly. Node consumers require Node 20 or newer. `@metta-ts/hyperon` is
-installed as a package dependency.
+The parser, graph model, serialization, evaluation helpers, SVG-frame builders,
+and Node GIF renderer also run headlessly. Node consumers require Node 20 or
+newer. The GIF renderer uses Sharp 0.35 and requires Node 20.9 or newer.
+`@metta-ts/hyperon` is installed as a package dependency.
 
-GIF export is optional. Install `gifenc` and pass its module to `gif()` or
-`exportReductionGif()`:
+Browser GIF export is optional. Install `gifenc` and pass its module to `gif()`
+or `exportReductionGif()`:
 
 ```bash
 npm install gifenc
@@ -69,6 +71,40 @@ const blob = await grapher("#metta-graph")
   .gif(await import("gifenc"));
 ```
 
+## Generate a GIF in Node.js
+
+Install the two optional rendering packages:
+
+```bash
+npm install @metta-ts/grapher sharp gifenc
+```
+
+Then call the Node entry point. It does not create a DOM or open a browser.
+
+```ts
+import { writeFile } from "node:fs/promises";
+import { renderReductionGif } from "@metta-ts/grapher/node";
+
+const gif = await renderReductionGif("(+ 10 (* 25 2))", {
+  view: "blocks",
+  width: 720,
+});
+
+await writeFile("reduction.gif", gif);
+```
+
+`renderReductionGif()` accepts MeTTa source, one `Atom`, or an array of atoms.
+For source and arrays, it loads every atom into the selected engine and traces
+the last atom whose head is not `=` or `:`. Pass `{ metta }` to reuse an
+existing `MeTTa` space. `view` accepts `"blocks"`, `"graph"`, or
+`"side-by-side"`.
+
+The Node renderer uses the same `reduceTrace()`, `blockReductionSvgs()`,
+`graphReductionSvgs()`, and `sideBySideReductionSvgs()` pipeline as the browser.
+Only SVG rasterization changes by host. The function returns GIF bytes as a
+`Uint8Array`; writing, uploading, or returning those bytes is the caller's
+choice.
+
 ## Exports
 
 The code entry point is `@metta-ts/grapher`. Its main public surfaces are:
@@ -86,8 +122,12 @@ The code entry point is `@metta-ts/grapher`. Its main public surfaces are:
   `&grapher` directives.
 - `reductionGif`, `graphReductionGif`, and `sideBySideReductionGif` for
   caller-supplied GIF encoding.
+- `blockReductionSvgs`, `graphReductionSvgs`, `sideBySideReductionSvgs`, and
+  `encodeSvgAnimation` for host-independent frame generation and encoding.
+- `renderReductionGif` from `@metta-ts/grapher/node` for direct Node GIF bytes.
 
-The package also exports `@metta-ts/grapher/package.json`. See the
+The package also exports `@metta-ts/grapher/node` and
+`@metta-ts/grapher/package.json`. See the
 [full API reference](https://mestto.github.io/MeTTa-TS/reference/grapher).
 
 ## License

packages/grapher/package.json

@@ -3,13 +3,14 @@
   "version": "1.1.4",
   "author": "MesTTo",
   "license": "MIT",
-  "description": "MeTTaGrapher: a pure-SVG visual node-graph editor for MeTTa. Build a program as connected nodes, evaluate any subtree on the engine, and see the result. A node graph is a MeTTa atom.",
+  "description": "MeTTa visual editor and reduction renderer for browser and Node.js, with node-graph and nested-block views.",
   "keywords": [
     "metta",
     "hyperon",
     "visual",
     "editor",
     "graph",
+    "gif",
     "svg",
     "typescript"
   ],
@@ -22,6 +23,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -32,11 +37,27 @@
   },
   "sideEffects": false,
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean --platform browser"
+    "build": "tsup src/index.ts --format esm --dts --clean --platform browser && tsup src/node.ts --format esm --dts --platform node"
   },
   "dependencies": {
     "@metta-ts/hyperon": "workspace:*"
   },
+  "devDependencies": {
+    "gifenc": "1.0.3",
+    "sharp": "^0.35.3"
+  },
+  "peerDependencies": {
+    "gifenc": "^1.0.3",
+    "sharp": "^0.35.3"
+  },
+  "peerDependenciesMeta": {
+    "gifenc": {
+      "optional": true
+    },
+    "sharp": {
+      "optional": true
+    }
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/MesTTo/MeTTa-TS.git",

packages/grapher/scripts/gen-graph-gif.mjs

@@ -2,46 +2,27 @@
 //
 //   node scripts/gen-graph-gif.mjs <program.metta> "<query>" <out.gif> [width]
 //
-// The frame math (@metta-ts/grapher's graphReductionSvgs) is pure and runs in Node; the SVG frames are
-// rasterized and assembled into a GIF by ImageMagick (`convert`). The reduction endpoint matches Run, so
-// this is the same picture the in-browser editor plays.
+// Uses the package's Node adapter, so the reduction and animation are the same ones the browser editor plays.
 
-import { readFileSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
-import { execFileSync } from "node:child_process";
-import { MeTTa } from "@metta-ts/hyperon";
-import { parseProgram, reduceTrace, graphReductionSvgs } from "../dist/index.js";
+import { readFileSync, writeFileSync } from "node:fs";
+import { renderReductionGif } from "../dist/node.js";
 
 const [, , programPath, query, outGif, widthArg] = process.argv;
 if (!programPath || !query || !outGif) {
   console.error('usage: node gen-graph-gif.mjs <program.metta> "<query>" <out.gif> [width]');
   process.exit(1);
 }
 
-const metta = new MeTTa();
-for (const atom of parseProgram(readFileSync(programPath, "utf8"))) metta.space().addAtom(atom);
-const states = reduceTrace(parseProgram(query)[0], metta);
-
-// Smoothness is tunable via env: more frames per step + a shorter per-frame delay reads smoother.
-const { frames, width, height } = graphReductionSvgs(states, {
-  width: widthArg ? Number(widthArg) : 1100,
+const source = `${readFileSync(programPath, "utf8")}\n${query}`;
+const width = widthArg ? Number(widthArg) : 1100;
+const bytes = await renderReductionGif(source, {
+  view: "graph",
+  width,
   framesPerStep: Number(process.env.FPS ?? 8),
   holdMs: Number(process.env.HOLD ?? 460),
   stepMs: Number(process.env.STEP ?? 33),
   maxFrames: Number(process.env.MAXFRAMES ?? 320),
+  maxSteps: Number(process.env.MAXSTEPS ?? 300),
 });
-console.log(`states=${states.length} frames=${frames.length} size=${width}x${height}`);
-
-// Write each frame's SVG, then let ImageMagick rasterize and assemble them in one call, applying each
-// frame's delay (GIF delays are centiseconds, so milliseconds / 10).
-const dir = "/tmp/mg-frames";
-rmSync(dir, { recursive: true, force: true });
-mkdirSync(dir, { recursive: true });
-const assemble = ["-loop", "0"];
-frames.forEach((f, i) => {
-  const path = `${dir}/f${String(i).padStart(4, "0")}.svg`;
-  writeFileSync(path, f.svg);
-  assemble.push("-delay", String(Math.max(2, Math.round(f.delay / 10))), path);
-});
-assemble.push("-layers", "optimize", outGif);
-execFileSync("convert", assemble);
-console.log("wrote", outGif);
+writeFileSync(outGif, bytes);
+console.log(`wrote ${outGif} (${bytes.byteLength} bytes, width ${width})`);

packages/grapher/src/block/gif.ts

@@ -2,14 +2,13 @@
 //
 // SPDX-License-Identifier: MIT
 
-// Export a reduction as an animated GIF. Each frame of the block animation is rendered to an SVG string,
-// rasterized on an offscreen canvas, and encoded by a caller-provided GIF encoder. The encoder is passed
-// in rather than imported, so this package stays dependency-free: only a consumer that wants GIF export
-// installs one (gifenc) and hands it over. The frames are the same morph the live view plays, over a fixed
-// view box (the union of every state's bounds) so the animation does not jump or rescale.
+// Export a reduction as SVG animation frames or a browser GIF. The browser path rasterizes each SVG on an
+// offscreen canvas and uses a caller-provided GIF encoder. The frames use a fixed view box over every
+// state, so the animation does not jump or rescale.
 
 import type { Atom } from "@metta-ts/hyperon";
 import { DEFAULT_TRACE_MS } from "../anim";
+import { encodeBrowserSvgAnimation, type SvgAnimation } from "../svg-gif";
 import type { BlockSettings } from "./settings";
 import { placeProgram, type BlockBox } from "./layout";
 import { boxesToPrims, interpolate, ease, type Prim } from "./animate";
@@ -129,14 +128,12 @@ export function frameSvg(
   return parts.join("");
 }
 
-/** Encode a sequence of reduction states into an animated GIF, morphing between them. Each state is a
- *  frontier (one or more terms), so a nondeterministic step shows every branch. */
-export async function reductionGif(
+/** Build the nested-block SVG frames for a reduction with explicit block settings. */
+export function blockReductionSvgsWithSettings(
   states: readonly Atom[][],
   s: BlockSettings,
-  lib: GifEncoderLib,
   opts: GifOptions = {},
-): Promise<Blob> {
+): SvgAnimation {
   if (states.length === 0) throw new Error("no reduction states to export");
   const width = opts.width ?? 720;
   const holdMs = opts.holdMs ?? 260;
@@ -146,38 +143,30 @@ export async function reductionGif(
   let vb = boundsOf(placeProgram(states[0]!, s), s);
   for (const frontier of states) vb = union(vb, boundsOf(placeProgram(frontier, s), s));
   const height = Math.max(1, Math.round((width * vb.h) / vb.w));
-
-  const canvas = document.createElement("canvas");
-  canvas.width = width;
-  canvas.height = height;
-  const ctx = canvas.getContext("2d");
-  if (ctx === null) throw new Error("no 2d canvas context for GIF export");
-
-  const gif = lib.GIFEncoder();
-  const addFrame = async (prims: readonly Prim[], delay: number): Promise<void> => {
-    const svg = frameSvg(prims, vb, width, height, s.canvas);
-    const img = new Image();
-    img.src = "data:image/svg+xml;charset=utf-8," + encodeURIComponent(svg);
-    await img.decode();
-    ctx.fillStyle = s.canvas;
-    ctx.fillRect(0, 0, width, height);
-    ctx.drawImage(img, 0, 0, width, height);
-    const { data } = ctx.getImageData(0, 0, width, height);
-    const palette = lib.quantize(data, 256);
-    const index = lib.applyPalette(data, palette);
-    gif.writeFrame(index, width, height, { palette, delay });
-  };
-
+  const background = opts.background ?? s.canvas;
+  const frames: SvgAnimation["frames"] = [];
   const n = states.length;
   const perStep = framesPerStepFor(opts, n - 1);
-
-  await addFrame(framePrims[0]!, holdMs);
+  frames.push({ svg: frameSvg(framePrims[0]!, vb, width, height, background), delay: holdMs });
   for (let i = 1; i < n; i++) {
     for (let k = 1; k <= perStep; k++) {
       const prims = interpolate(framePrims[i - 1]!, framePrims[i]!, ease(k / perStep));
-      await addFrame(prims, k === perStep ? holdMs : stepMs);
+      frames.push({
+        svg: frameSvg(prims, vb, width, height, background),
+        delay: k === perStep ? holdMs : stepMs,
+      });
     }
   }
-  gif.finish();
-  return new Blob([gif.bytes() as BlobPart], { type: "image/gif" });
+  return { frames, width, height, background };
+}
+
+/** Encode a sequence of reduction states into an animated GIF, morphing between them. Each state is a
+ *  frontier (one or more terms), so a nondeterministic step shows every branch. */
+export async function reductionGif(
+  states: readonly Atom[][],
+  s: BlockSettings,
+  lib: GifEncoderLib,
+  opts: GifOptions = {},
+): Promise<Blob> {
+  return encodeBrowserSvgAnimation(blockReductionSvgsWithSettings(states, s, opts), lib, 256);
 }

packages/grapher/src/gifenc.d.ts

@@ -0,0 +1,14 @@
+// SPDX-FileCopyrightText: 2026 MesTTo
+//
+// SPDX-License-Identifier: MIT
+
+declare module "gifenc" {
+  type Encoder = import("./block/gif").GifEncoderLib;
+
+  export const GIFEncoder: Encoder["GIFEncoder"];
+  export const quantize: Encoder["quantize"];
+  export const applyPalette: Encoder["applyPalette"];
+
+  const gifenc: Encoder;
+  export default gifenc;
+}

packages/grapher/src/index.ts

@@ -57,11 +57,18 @@ export {
 export { reductionGif, type GifEncoderLib, type GifOptions } from "./block/gif";
 export {
   sideBySideReductionGif,
+  sideBySideReductionSvgs,
   graphReductionGif,
   graphReductionSvgs,
   blockReductionSvgs,
   type GraphFrame,
 } from "./sidebyside-gif";
+export {
+  encodeSvgAnimation,
+  type SvgAnimation,
+  type SvgFrame,
+  type SvgRasterizer,
+} from "./svg-gif";
 export {
   roundedRectPath,
   roundedBackingPath,