@ai-matrx/diagrams

The AI Matrx diagram engine: Archify 3.2.0 (MIT) refactored into pure functions. A spec goes in; a validated, laid-out, self-contained diagram comes out, in Node or in the browser, with no Node built-ins, no filesystem and no network.

npm install @ai-matrx/diagrams

import { validate, layout, render } from "@ai-matrx/diagrams";

const spec = { meta: { title: "Checkout", subtitle: "Order to paid" }, /* ... */ };

const checked = validate("workflow", spec, { quality: "showcase" });
// { ok, diagnostics: [{ code, severity, message, subject, evidence, supportedFixes }], composition, checks }

const geometry = layout("workflow", spec); // { receipt }  (Archify's --layout-json contract)
const picture = render("workflow", spec, { theme: "dark" }); // { svg, html, receipt }

Ten types: architecture, workflow, sequence, dataflow, lifecycle, erd, class, tree, timeline, waterfall. Every function never throws on bad input: schema errors, layout refusals and unknown types come back as Diagnostics, each saying what is wrong, where, with the numbers, and which fixes are supported.

render().html is Archify's complete standalone explorer page (about 800 KB, fonts included) and is byte-identical to what the Archify CLI writes (the package's parity test proves it for all 25 bundled examples). render().svg is the diagram alone; it takes its colors from the CSS variables of the surrounding page.

Embedding in an app

render(type, spec, { theme, mode: "embed", legend? }) returns the picture for hosting inside your own UI: no header, theme toggle, export menu, toolbar, passport popup, node index or cards. svg is self-themed (theme tokens, classes and fonts inline, all scoped to svg.mxd) and always shows the WHOLE picture: never cropped, never a sideways scroll. bindEmbed fits it to its container in both axes (a content-height host gets the full width with a capped height) and adds zoom (Ctrl/Cmd+wheel or pinch, drag to pan, zoomIn/zoomOut/resetZoom on the handle, or controls: true for built-in buttons). data-mxd-min-width is the legibility floor as a measurement. html is a small document for an iframe srcdoc that fits its window and draws its own zoom buttons. Clicking or activating a node emits diagram:node (detail: {id, label, type}; a CustomEvent on the svg, plus a postMessage to the parent when framed), so your UI decides what to show. When you mount the svg string yourself, call bindEmbed(svgElement) once it is in the document.

Node state over the picture, never moving it: handle.setNodeState({status, current, tone}) (or the nodeState bind option) draws a status per node (idle|pending|running|done|warning|failed|skipped: outline, fill tint, corner glyph; running spins unless the reader prefers reduced motion), one "you are here" node (a dashed ring and aria-current="step", distinct from select), and a categorical tone per node (cyan|green|violet|amber|rose|orange|slate). Every color is one of the picture's own theme tokens. handle.legend() lists only what is drawn, with the color actually used (DIAGRAM_NODE_STATUSES, DIAGRAM_NODE_TONES name the sets).

Choosing a target width

DESKTOP_READER_DIAGRAM_WIDTH is the engine's desktop reader width, currently 930 CSS pixels. A targetWidth below it enables narrow-layout adaptation and, when needed, a wider fallback. At or above it the engine draws the spec as written. A host retrying an adapted diagram in a wide container can use DESKTOP_READER_DIAGRAM_WIDTH - 1 to retain narrow-layout adaptation.

import { DESKTOP_READER_DIAGRAM_WIDTH, render } from "@ai-matrx/diagrams";
const picture = render("workflow", spec, { targetWidth: DESKTOP_READER_DIAGRAM_WIDTH - 1 });

Measuring a render

@ai-matrx/diagrams/measure is one pure-DOM function that turns a rendered diagram into numbers (inspection.v1): text sizes, clipped and truncated text, overlaps, out-of-bounds elements, crossings, labels sitting on lines, and text contrast.

import { measure } from "@ai-matrx/diagrams/measure";
const inspection = measure(document.querySelector("svg")!);

For headless capture, inject the same function as text so a browser and a headless page return the same JSON:

import { MEASURE_SCRIPT, SETTLE_EXPRESSION, measureExpression } from "@ai-matrx/diagrams/measure";
await page.setContent(render("workflow", spec).html!);
await page.evaluate(SETTLE_EXPRESSION); // fonts + the viewer's layout
const inspection = await page.evaluate(measureExpression("svg"));

What is not here

No React (the chat and canvas renderers live in @ai-matrx/rich-content), no browser launching (the scraper does headless capture), no file output, no git or repository-evidence verification, and no network brand capture. Built-in brand ids resolve; a bare URL or digest-pinned brand is refused with a diagnostic. See NOTICE for what was taken from Archify, what changed, and which third-party marks were dropped for licence reasons.

There is a thin CLI (ai-matrx-diagrams render|validate|layout); it exists only for parity testing against the original Archify CLI.