examfig

Render educational diagrams from structured semantic specifications to deterministic SVG.

Install

pnpm add examfig

API

import {
  renderDiagram,
  validateDiagram,
  type DiagramSpec,
} from "examfig";
import { getDiagramJsonSchema } from "examfig/schema";

const spec: DiagramSpec = {
  type: "data-plot",
  plotType: "boxplot",
  accessibleDescription: "Boxplot of salaries.",
  xAxis: { domain: [25, 83], ticks: [30, 50, 70] },
  series: [
    {
      label: "A",
      values: {
        minimum: 38,
        firstQuartile: 47,
        median: 51,
        thirdQuartile: 56,
        maximum: 62,
      },
    },
  ],
};

const result = validateDiagram(spec);
if (!result.success) {
  console.error(result.errors);
} else {
  const svg = renderDiagram(result.spec, { theme: "monochrome" });
}

v2 package boundaries

examfig is the compatibility facade. New applications can depend on the narrower packages directly:

import { createMathText, validateSvg } from "@examfig/core";
import { polarGraphRenderer } from "@examfig/charts";
import { circuitRenderer } from "@examfig/science";

The facade registers all chart and science renderers automatically. Direct package consumers can register only the renderers they need.

Migration from the v0.1 prototype

The prototype accepted { type: "free-body", width?, height? } and ignored semantic fields. The current API requires a full DiagramSpec, including accessibleDescription, and returns the same SVG string contract. Validation is fail-closed.

For the complete v2 migration, including math-text, PNG/PDF adapter seams, and the fixture gallery, see the repository's docs/migration-v2.md.

Browser and server

renderDiagram is synchronous, DOM-free, and safe for Node/Bun SSR.

Development

From the monorepo root:

pnpm dev
pnpm test
pnpm build

License

MIT — see LICENSE.