aether-diagram

AI-native diagram DSL, JSON AST, deterministic + pluggable layout (core / elk), semantic diagnostics, interop helpers, SVG + terminal output, Remark plugin, and CLI for Markdown workflows.

Preview (renders on GitHub; same image works on npm via absolute URL):

• Try from any folder: npx aether-diagram@latest validate --help
• Full monorepo + gallery: github.com/raztronaut/aether

DSL quick reference

diagram <id>
title Optional title
theme default | dark | minimal

node <id> <kind> <label>
edge <from> -> <to> [: label]

import ./other.aether [as prefix]
rank <id> <id> ...
align horizontal|vertical <id> <id> ...
pin <id> <x> <y>

Kinds: service, queue, db, agent, ui, boundary, box.

JSON schema

Canonical AST: schema/aether-diagram.schema.json.

API

import { parseDsl, layoutDiagramWithEngine, renderSvg, attachPanZoom } from "aether-diagram";

const ast = parseDsl(source);
const layout = await layoutDiagramWithEngine(ast, { engine: "elk" });
const svg = renderSvg(ast, layout);

CLI

pnpm exec aether-diagram validate diagram.aether
pnpm exec aether-diagram validate diagram.aether --json --fail-on-warning
pnpm exec aether-diagram format diagram.aether
pnpm exec aether-diagram svg diagram.aether --engine elk -o out.svg
pnpm exec aether-diagram text diagram.aether --width 80
pnpm exec aether-diagram tui-model diagram.aether
pnpm exec aether-diagram render-md "docs/**/*.md" --out-dir diagrams --embed
pnpm exec aether-diagram diff before.aether after.aether
pnpm exec aether-diagram fix diagram.aether
pnpm exec aether-diagram explain diagram.aether

Remark / MDX

See docs/mdx-integration.md.

import { remarkAetherDiagram } from "aether-diagram/remark";

License

MIT (same as the parent workspace unless noted otherwise).