@agent-clis/diagrams 0.1.0

package/dist/layout/edges.d.ts

@@ -0,0 +1,11 @@
+import type { DiagramSpec, LayoutNode, NodeId, EdgeRoute, ThemeConfig } from '../types.js';
+/**
+ * Compute edge paths (SVG path data) and arrowhead polygons.
+ */
+export declare function routeEdges(spec: DiagramSpec, positions: Map<NodeId, LayoutNode>, theme: ThemeConfig): EdgeRoute[];
+/**
+ * Position-based edge routing for grouped layouts.
+ * Instead of using a single global direction, picks ports based on the relative
+ * positions of the two nodes (dominant axis determines port choice).
+ */
+export declare function routeEdgesGlobal(spec: DiagramSpec, positions: Map<NodeId, LayoutNode>, theme: ThemeConfig): EdgeRoute[];

package/dist/layout/groups.d.ts

@@ -0,0 +1,6 @@
+import type { DiagramSpec, ThemeConfig, LayoutResult } from '../types.js';
+/**
+ * Two-level layout: lay out nodes within groups, then arrange groups on a grid.
+ * Falls back to regular layout() when no groups are defined.
+ */
+export declare function layoutWithGroups(spec: DiagramSpec, theme: ThemeConfig, padding?: number): LayoutResult;

package/dist/layout/index.d.ts

@@ -0,0 +1,3 @@
+import type { DiagramSpec, ThemeConfig, LayoutResult } from '../types.js';
+export { layoutWithGroups } from './groups.js';
+export declare function layout(spec: DiagramSpec, theme: ThemeConfig, padding?: number): LayoutResult;

package/dist/layout/order.d.ts

@@ -0,0 +1,6 @@
+import type { DiagramSpec, NodeId } from '../types.js';
+/**
+ * Order nodes within each rank to minimize edge crossings.
+ * Uses barycenter heuristic. Back-edges are excluded from adjacency.
+ */
+export declare function orderNodes(spec: DiagramSpec, ranks: Map<NodeId, number>, backEdges?: Set<number>): NodeId[][];

package/dist/layout/position.d.ts

@@ -0,0 +1,14 @@
+import type { DiagramNode, DiagramSpec, NodeId, ThemeConfig, LayoutNode } from '../types.js';
+/**
+ * Estimate a node's rendered dimensions based on label text and theme.
+ */
+export declare function measureNode(node: DiagramNode, theme: ThemeConfig): {
+    width: number;
+    height: number;
+};
+/**
+ * Assign pixel positions to nodes.
+ * TB: ranks go top to bottom, nodes within a rank spread horizontally.
+ * LR: ranks go left to right, nodes within a rank spread vertically.
+ */
+export declare function positionNodes(spec: DiagramSpec, layers: NodeId[][], theme: ThemeConfig, padding: number): Map<NodeId, LayoutNode>;

package/dist/layout/rank.d.ts

@@ -0,0 +1,11 @@
+import type { DiagramSpec, NodeId } from '../types.js';
+export interface RankResult {
+    ranks: Map<NodeId, number>;
+    /** Indices into spec.edges that are back-edges (cycle-forming) */
+    backEdges: Set<number>;
+}
+/**
+ * Assign each node to a rank (layer).
+ * Detects back-edges (cycle-forming) via DFS and excludes them from ranking.
+ */
+export declare function assignRanks(spec: DiagramSpec): RankResult;

package/dist/parse.d.ts

@@ -0,0 +1,2 @@
+import type { AnyDiagramSpec } from './types.js';
+export declare function parseSpec(input: string): AnyDiagramSpec;

package/dist/render/edges.d.ts

@@ -0,0 +1,6 @@
+import type { DiagramEdge, EdgeRoute, ThemeConfig, SatoriElement } from '../types.js';
+/**
+ * Render all edges: SVG overlay for paths/arrows + div overlays for labels.
+ * Returns an array of elements to be placed in the root container.
+ */
+export declare function renderEdges(specEdges: DiagramEdge[], routes: EdgeRoute[], theme: ThemeConfig, canvasWidth: number, canvasHeight: number): SatoriElement[];

package/dist/render/groups.d.ts

@@ -0,0 +1,5 @@
+import type { GroupLayout, ThemeConfig, SatoriElement } from '../types.js';
+/**
+ * Render a group card as a Satori element (background container with optional label).
+ */
+export declare function renderGroupCard(group: GroupLayout, theme: ThemeConfig): SatoriElement;

package/dist/render/html.d.ts

@@ -0,0 +1,5 @@
+import type { SatoriElement } from '../types.js';
+/**
+ * Serialize the Satori element tree to a standalone HTML file.
+ */
+export declare function renderToHTML(tree: SatoriElement): string;

package/dist/render/index.d.ts

@@ -0,0 +1,2 @@
+import type { AnyDiagramSpec, RenderOptions } from '../types.js';
+export declare function renderDiagram(spec: AnyDiagramSpec, options?: RenderOptions): Promise<string | Buffer>;

package/dist/render/nodes.d.ts

@@ -0,0 +1,5 @@
+import type { DiagramNode, ThemeConfig, LayoutNode, SatoriElement } from '../types.js';
+/**
+ * Render a single node as a Satori element tree.
+ */
+export declare function renderNode(node: DiagramNode, pos: LayoutNode, theme: ThemeConfig): SatoriElement;

package/dist/render/pptx.d.ts

@@ -0,0 +1,2 @@
+import type { DiagramSpec, LayoutResult, ThemeConfig } from '../types.js';
+export declare function renderToPptx(spec: DiagramSpec, layout: LayoutResult, theme: ThemeConfig): Promise<Buffer>;

package/dist/render/rasterize.d.ts

@@ -0,0 +1,3 @@
+import type { SatoriElement } from '../types.js';
+export declare function renderToSvg(tree: SatoriElement, width: number, height: number): Promise<string>;
+export declare function renderToPng(tree: SatoriElement, width: number, height: number, scale?: number): Promise<Buffer>;

package/dist/render/tree.d.ts

@@ -0,0 +1,5 @@
+import type { DiagramSpec, ThemeConfig, LayoutResult, SatoriElement } from '../types.js';
+/**
+ * Build the complete Satori-compatible element tree.
+ */
+export declare function buildTree(spec: DiagramSpec, layoutResult: LayoutResult, theme: ThemeConfig): SatoriElement;

package/dist/themes/dark.d.ts

@@ -0,0 +1,2 @@
+import type { ThemeConfig } from '../types.js';
+export declare const darkTheme: ThemeConfig;

package/dist/themes/default.d.ts

@@ -0,0 +1,2 @@
+import type { ThemeConfig } from '../types.js';
+export declare const defaultTheme: ThemeConfig;

package/dist/themes/index.d.ts

@@ -0,0 +1,5 @@
+import type { ThemeConfig } from '../types.js';
+import { defaultTheme } from './default.js';
+import { darkTheme } from './dark.js';
+export declare function getTheme(nameOrConfig: string | ThemeConfig | undefined): ThemeConfig;
+export { defaultTheme, darkTheme };

package/dist/types.d.ts

@@ -0,0 +1,320 @@
+export type NodeId = string;
+export type Direction = 'TB' | 'LR';
+export type OutputFormat = 'svg' | 'png' | 'html' | 'pptx';
+export type NodeShape = 'rectangle' | 'rounded' | 'pill' | 'diamond' | 'circle';
+export type EdgeStyle = 'solid' | 'dashed' | 'dotted';
+export type NodeVariant = 'default' | 'icon';
+export type DiagramType = 'flow' | 'gantt' | 'timeline' | 'quadrant';
+export interface NodeStyleOverrides {
+    backgroundColor?: string;
+    borderColor?: string;
+    textColor?: string;
+    iconBorderRadius?: number;
+}
+export interface DiagramNode {
+    id: NodeId;
+    label: string;
+    description?: string;
+    shape?: NodeShape;
+    variant?: NodeVariant;
+    icon?: string;
+    iconDataUri?: string;
+    style?: NodeStyleOverrides;
+}
+export interface DiagramEdge {
+    from: NodeId;
+    to: NodeId;
+    label?: string;
+    style?: EdgeStyle;
+    color?: string;
+}
+export interface GroupStyleOverrides {
+    backgroundColor?: string;
+    borderColor?: string;
+    labelColor?: string;
+}
+export interface DiagramGroup {
+    id: string;
+    label?: string;
+    members: NodeId[];
+    direction?: Direction;
+    style?: GroupStyleOverrides;
+}
+export interface DiagramSpec {
+    type?: DiagramType;
+    nodes: DiagramNode[];
+    edges: DiagramEdge[];
+    direction?: Direction;
+    title?: string;
+    theme?: string | ThemeConfig;
+    groups?: DiagramGroup[];
+    rows?: string[][];
+}
+export interface GanttTask {
+    id: string;
+    label: string;
+    start: string;
+    end: string;
+    color?: string;
+    group?: string;
+    dependencies?: string[];
+    progress?: number;
+}
+export interface GanttSpec {
+    type: 'gantt';
+    title?: string;
+    theme?: string | ThemeConfig;
+    tasks: GanttTask[];
+}
+export interface TimelineEvent {
+    date: string;
+    label: string;
+    description?: string;
+    icon?: string;
+    iconDataUri?: string;
+    color?: string;
+}
+export interface TimelineSpec {
+    type: 'timeline';
+    title?: string;
+    theme?: string | ThemeConfig;
+    direction?: Direction;
+    events: TimelineEvent[];
+}
+export interface QuadrantAxis {
+    label: string;
+    low: string;
+    high: string;
+}
+export interface QuadrantDef {
+    label: string;
+    position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    color?: string;
+}
+export interface QuadrantItem {
+    label: string;
+    x: number;
+    y: number;
+    color?: string;
+}
+export interface QuadrantSpec {
+    type: 'quadrant';
+    title?: string;
+    theme?: string | ThemeConfig;
+    xAxis: QuadrantAxis;
+    yAxis: QuadrantAxis;
+    quadrants?: QuadrantDef[];
+    items: QuadrantItem[];
+}
+export type AnyDiagramSpec = DiagramSpec | GanttSpec | TimelineSpec | QuadrantSpec;
+export interface RenderOptions {
+    format?: OutputFormat;
+    width?: number;
+    scale?: number;
+    background?: string;
+    padding?: number;
+}
+export interface ThemeConfig {
+    name: string;
+    canvas: {
+        background: string;
+    };
+    node: {
+        background: string;
+        border: string;
+        borderWidth: number;
+        borderRadius: number;
+        textColor: string;
+        textColorSecondary: string;
+        fontSize: number;
+        fontWeight: number;
+        descriptionFontSize: number;
+        paddingX: number;
+        paddingY: number;
+        minWidth: number;
+        maxWidth: number;
+        shadow: string;
+        icon: {
+            size: number;
+            marginBottom: number;
+            dominantSize: number;
+            dominantMarginBottom: number;
+            dominantLabelFontSize: number;
+        };
+    };
+    edge: {
+        color: string;
+        width: number;
+        arrowSize: number;
+        labelColor: string;
+        labelFontSize: number;
+        labelBackground: string;
+    };
+    spacing: {
+        rankSep: number;
+        nodeSep: number;
+    };
+    group: {
+        background: string;
+        border: string;
+        borderWidth: number;
+        borderRadius: number;
+        paddingX: number;
+        paddingY: number;
+        labelFontSize: number;
+        labelColor: string;
+        labelMarginBottom: number;
+        gap: number;
+    };
+    fontFamily: string;
+    gantt?: GanttTheme;
+    timeline?: TimelineTheme;
+    quadrant?: QuadrantTheme;
+}
+export interface GanttTheme {
+    barHeight: number;
+    barRadius: number;
+    barGap: number;
+    headerHeight: number;
+    gridLineColor: string;
+    groupLabelColor: string;
+    groupLabelFontSize: number;
+    barLabelColor: string;
+    barLabelFontSize: number;
+    progressFillOpacity: number;
+    dependencyArrowColor: string;
+    dateHeaderColor: string;
+    dateHeaderFontSize: number;
+}
+export interface TimelineTheme {
+    lineColor: string;
+    lineWidth: number;
+    dotSize: number;
+    cardWidth: number;
+    cardGap: number;
+    connectorLength: number;
+    dateFontSize: number;
+    dateColor: string;
+    labelFontSize: number;
+    descriptionFontSize: number;
+}
+export interface QuadrantTheme {
+    gridSize: number;
+    axisColor: string;
+    axisWidth: number;
+    axisLabelColor: string;
+    axisLabelFontSize: number;
+    quadrantOpacity: number;
+    dotSize: number;
+    dotLabelFontSize: number;
+    dotLabelColor: string;
+}
+export interface LayoutNode {
+    id: NodeId;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface EdgeRoute {
+    from: NodeId;
+    to: NodeId;
+    pathData: string;
+    labelX?: number;
+    labelY?: number;
+    arrowPoints: string;
+}
+export interface GroupLayout {
+    id: string;
+    label?: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    style?: GroupStyleOverrides;
+}
+export interface LayoutResult {
+    nodes: Map<NodeId, LayoutNode>;
+    edges: EdgeRoute[];
+    width: number;
+    height: number;
+    groups?: GroupLayout[];
+}
+export interface GanttLayoutResult {
+    tasks: Array<{
+        id: string;
+        label: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        color: string;
+        progress: number;
+        group?: string;
+    }>;
+    dependencies: Array<{
+        pathData: string;
+    }>;
+    dateLabels: Array<{
+        label: string;
+        x: number;
+    }>;
+    groupLabels: Array<{
+        label: string;
+        y: number;
+    }>;
+    width: number;
+    height: number;
+    headerHeight: number;
+}
+export interface TimelineLayoutResult {
+    events: Array<{
+        date: string;
+        label: string;
+        description?: string;
+        icon?: string;
+        iconDataUri?: string;
+        color?: string;
+        dotX: number;
+        dotY: number;
+        cardX: number;
+        cardY: number;
+        connectorPath: string;
+        side: 'left' | 'right' | 'top' | 'bottom';
+    }>;
+    linePath: string;
+    width: number;
+    height: number;
+}
+export interface QuadrantLayoutResult {
+    items: Array<{
+        label: string;
+        x: number;
+        y: number;
+        color?: string;
+    }>;
+    quadrants: Array<{
+        label: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        color: string;
+    }>;
+    gridOrigin: {
+        x: number;
+        y: number;
+    };
+    gridSize: number;
+    xAxis: QuadrantAxis;
+    yAxis: QuadrantAxis;
+    width: number;
+    height: number;
+}
+export interface SatoriElement {
+    type: string;
+    props: Record<string, unknown> & {
+        children?: SatoriElement | (SatoriElement | string)[] | string;
+        style?: Record<string, unknown>;
+    };
+}

package/dist/validate.d.ts

@@ -0,0 +1,2 @@
+import type { AnyDiagramSpec } from './types.js';
+export declare function validate(spec: AnyDiagramSpec): string[];

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@agent-clis/diagrams",
+  "version": "0.1.0",
+  "description": "Generate beautiful architecture diagrams from declarative YAML specs",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "bin": {
+    "diagrams": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "fonts"
+  ],
+  "scripts": {
+    "dev": "bun run src/cli.ts",
+    "build": "bun run build:sdk && bun run build:cli:js",
+    "build:sdk": "bun build ./src/index.ts --outdir ./dist --target node && tsc --emitDeclarationOnly",
+    "build:cli:js": "bun build ./src/cli.ts --outdir ./dist --target node --entry-naming cli.js",
+    "build:cli": "bun build ./src/cli.ts --compile --outfile diagrams",
+    "build:cli:linux-x64": "bun build ./src/cli.ts --compile --target=bun-linux-x64 --outfile diagrams-linux-x64",
+    "build:cli:linux-arm64": "bun build ./src/cli.ts --compile --target=bun-linux-arm64 --outfile diagrams-linux-arm64",
+    "build:cli:darwin-x64": "bun build ./src/cli.ts --compile --target=bun-darwin-x64 --outfile diagrams-darwin-x64",
+    "build:cli:darwin-arm64": "bun build ./src/cli.ts --compile --target=bun-darwin-arm64 --outfile diagrams-darwin-arm64",
+    "build:cli:windows-x64": "bun build ./src/cli.ts --compile --target=bun-windows-x64 --outfile diagrams-windows-x64.exe",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "diagrams",
+    "architecture",
+    "flowchart",
+    "svg",
+    "png",
+    "cli",
+    "yaml"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/daviddrummond95/diagrams.git"
+  },
+  "author": "David Drummond",
+  "homepage": "https://github.com/daviddrummond95/diagrams",
+  "dependencies": {
+    "@resvg/resvg-js": "^2.6.0",
+    "commander": "^14.0.0",
+    "pptxgenjs": "^4.0.1",
+    "satori": "^0.12.0",
+    "simple-icons": "^16.8.0",
+    "yaml": "^2.6.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  }
+}