@bpmnkit/ascii 0.0.8

package/README.md

@@ -0,0 +1,93 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/bpmn-sdk/monorepo/main/doc/logos/logo-2-gateway.svg" width="72" height="72" alt="BPMN Kit logo">
+  <h1>@bpmnkit/ascii</h1>
+  <p>Render BPMN diagrams as Unicode box-drawing ASCII art — perfect for terminals and docs</p>
+
+  [![npm](https://img.shields.io/npm/v/@bpmnkit/ascii?style=flat-square&color=6244d7)](https://www.npmjs.com/package/@bpmnkit/ascii)
+  [![license](https://img.shields.io/npm/l/@bpmnkit/ascii?style=flat-square)](https://github.com/bpmnkit/monorepo/blob/main/LICENSE)
+  [![typescript](https://img.shields.io/badge/TypeScript-strict-6244d7?style=flat-square&logo=typescript&logoColor=white)](https://github.com/bpmnkit/monorepo)
+
+  [Documentation](https://bpmn-sdk-docs.pages.dev) · [GitHub](https://github.com/bpmnkit/monorepo) · [Changelog](https://github.com/bpmnkit/monorepo/blob/main/packages/ascii/CHANGELOG.md)
+</div>
+
+---
+
+## Overview
+
+`@bpmnkit/ascii` converts BPMN 2.0 diagrams into Unicode box-drawing text art. It uses the same Sugiyama layout engine as the visual renderer, so the spatial flow of the diagram is preserved.
+
+Useful for: CLI output, plain-text documentation, terminal UIs, test snapshots, and LLM prompts where visual BPMN isn't available.
+
+## Features
+
+- **Unicode box-drawing** — `┌─┐`, `│`, `└─┘`, `→` for clean terminal output
+- **Automatic layout** — uses `@bpmnkit/core`'s layout engine
+- **All element types** — tasks, events, gateways, sub-processes
+- **Configurable output** — optional title, element type labels
+- **Zero additional dependencies** — only requires `@bpmnkit/core` (already bundled)
+
+## Installation
+
+```sh
+npm install @bpmnkit/ascii
+```
+
+## Quick Start
+
+```typescript
+import { renderBpmnAscii } from "@bpmnkit/ascii"
+import { readFileSync } from "node:fs"
+
+const xml = readFileSync("my-process.bpmn", "utf8")
+const art = renderBpmnAscii(xml, { title: true, showTypes: true })
+console.log(art)
+```
+
+### Example output
+
+```
+Order Flow
+══════════════════════════════════════════════
+  ╭──────────╮     ╭───────────────╮     ╭╮
+  │  Order   │────▶│ Validate Order│────▶││
+  │ Received │     │ (ServiceTask) │     │◇│
+  ╰──────────╯     ╰───────────────╯     ╰╯
+                                          │
+                         ╭───────────────╯│╰───────────────╮
+                         ▼                                  ▼
+                   ╭───────────╮                    ╭──────────────╮
+                   │  Fulfill  │                    │    Reject    │
+                   │   Order   │                    │    Order     │
+                   ╰───────────╯                    ╰──────────────╯
+```
+
+## API Reference
+
+```typescript
+function renderBpmnAscii(xml: string, options?: RenderOptions): string
+
+interface RenderOptions {
+  title?: boolean     // Show process name as header. Default: false
+  showTypes?: boolean // Include element type in boxes. Default: false
+}
+```
+
+---
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@bpmnkit/core`](https://www.npmjs.com/package/@bpmnkit/core) | BPMN/DMN/Form parser, builder, layout engine |
+| [`@bpmnkit/canvas`](https://www.npmjs.com/package/@bpmnkit/canvas) | Zero-dependency SVG BPMN viewer |
+| [`@bpmnkit/editor`](https://www.npmjs.com/package/@bpmnkit/editor) | Full-featured interactive BPMN editor |
+| [`@bpmnkit/engine`](https://www.npmjs.com/package/@bpmnkit/engine) | Lightweight BPMN process execution engine |
+| [`@bpmnkit/feel`](https://www.npmjs.com/package/@bpmnkit/feel) | FEEL expression language parser & evaluator |
+| [`@bpmnkit/plugins`](https://www.npmjs.com/package/@bpmnkit/plugins) | 22 composable canvas plugins |
+| [`@bpmnkit/api`](https://www.npmjs.com/package/@bpmnkit/api) | Camunda 8 REST API TypeScript client |
+| [`@bpmnkit/profiles`](https://www.npmjs.com/package/@bpmnkit/profiles) | Shared auth, profile storage, and client factories for CLI & proxy |
+| [`@bpmnkit/operate`](https://www.npmjs.com/package/@bpmnkit/operate) | Monitoring & operations frontend for Camunda clusters |
+
+## License
+
+[MIT](https://github.com/bpmnkit/monorepo/blob/main/LICENSE) © bpmn-sdk

package/dist/dmn.d.ts

@@ -0,0 +1,9 @@
+import type { RenderOptions } from "./types.js";
+/**
+ * Render a DMN XML string as ASCII art.
+ *
+ * Each decision with a decision table is rendered as a labeled table with
+ * box-drawing characters. Multiple decisions are separated by a blank line.
+ */
+export declare function renderDmnAscii(xml: string, options?: RenderOptions): string;
+//# sourceMappingURL=dmn.d.ts.map

package/dist/dmn.js

@@ -0,0 +1,130 @@
+import { Dmn } from "@bpmnkit/core";
+// ── Box-drawing characters ───────────────────────────────────────────────────
+const H = "═";
+const V = "║";
+const TL = "╔";
+const TR = "╗";
+const BL = "╚";
+const BR = "╝";
+const TM = "╦";
+const BM = "╩";
+const LM = "╠";
+const RM = "╣";
+const MM = "╬";
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function pad(s, w) {
+    return s.length >= w ? s.slice(0, w) : s + " ".repeat(w - s.length);
+}
+function repeat(ch, n) {
+    return n <= 0 ? "" : ch.repeat(n);
+}
+// ── Decision table renderer ──────────────────────────────────────────────────
+function renderTable(name, table) {
+    const { hitPolicy, aggregation, inputs, outputs, rules } = table;
+    // Column widths: pad each column to at least the header label width
+    const numW = Math.max(1, String(rules.length).length);
+    const inputWidths = inputs.map((inp, i) => {
+        const headerW = (inp.label ?? inp.inputExpression.text ?? `In${i}`).length;
+        const entryW = rules.reduce((m, r) => {
+            const t = r.inputEntries[i]?.text ?? "";
+            return Math.max(m, t.length);
+        }, 0);
+        return Math.max(headerW, entryW, 4);
+    });
+    const outputWidths = outputs.map((out, i) => {
+        const headerW = (out.label ?? out.name ?? `Out${i}`).length;
+        const entryW = rules.reduce((m, r) => {
+            const t = r.outputEntries[i]?.text ?? "";
+            return Math.max(m, t.length);
+        }, 0);
+        return Math.max(headerW, entryW, 4);
+    });
+    // Hit policy label for the # column header cell
+    const policy = hitPolicy ?? "UNIQUE";
+    const policyLabel = aggregation ? `${policy}(${aggregation[0]})` : policy;
+    const numHeader = pad(policyLabel, numW);
+    // Build column separators
+    const numBar = repeat(H, numW + 2);
+    const inputBars = inputWidths.map((w) => repeat(H, w + 2));
+    const outputBars = outputWidths.map((w) => repeat(H, w + 2));
+    const allBars = [numBar, ...inputBars, ...outputBars];
+    function topRow() {
+        return TL + allBars.join(TM) + TR;
+    }
+    function midRow() {
+        return LM + allBars.join(MM) + RM;
+    }
+    function botRow() {
+        return BL + allBars.join(BM) + BR;
+    }
+    function cell(s, w) {
+        return ` ${pad(s, w)} `;
+    }
+    const lines = [];
+    // Header above the table
+    const tableTitle = name ? `${name}` : "Decision";
+    const hitLine = ` [${policy}${aggregation ? `/${aggregation}` : ""}]`;
+    lines.push(tableTitle + hitLine);
+    lines.push("─".repeat(tableTitle.length + hitLine.length));
+    lines.push("");
+    // Top border
+    lines.push(topRow());
+    // Column headers
+    const headerCells = [
+        cell(numHeader, numW),
+        ...inputs.map((inp, i) => cell(inp.label ?? inp.inputExpression.text ?? `In${i}`, inputWidths[i] ?? 0)),
+        ...outputs.map((out, i) => cell(out.label ?? out.name ?? `Out${i}`, outputWidths[i] ?? 0)),
+    ];
+    lines.push(V + headerCells.join(V) + V);
+    // Separator
+    lines.push(midRow());
+    // Rules
+    if (rules.length === 0) {
+        const emptyW = allBars.reduce((s, b) => s + b.length, 0) + allBars.length - 1;
+        lines.push(`${V} ${pad("(no rules)", emptyW)} ${V}`);
+    }
+    else {
+        for (let r = 0; r < rules.length; r++) {
+            const rule = rules[r];
+            if (!rule)
+                continue;
+            const ruleCells = [
+                cell(String(r + 1), numW),
+                ...inputs.map((_, i) => cell(rule.inputEntries[i]?.text ?? "", inputWidths[i] ?? 0)),
+                ...outputs.map((_, i) => cell(rule.outputEntries[i]?.text ?? "", outputWidths[i] ?? 0)),
+            ];
+            lines.push(V + ruleCells.join(V) + V);
+        }
+    }
+    // Bottom border
+    lines.push(botRow());
+    return lines.join("\n");
+}
+// ── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Render a DMN XML string as ASCII art.
+ *
+ * Each decision with a decision table is rendered as a labeled table with
+ * box-drawing characters. Multiple decisions are separated by a blank line.
+ */
+export function renderDmnAscii(xml, options) {
+    const defs = Dmn.parse(xml);
+    const decisions = defs.decisions.filter((d) => d.decisionTable);
+    if (decisions.length === 0)
+        return "(no decision tables)";
+    const blocks = decisions.map((d) => renderTable(d.name, d.decisionTable));
+    const body = blocks.join("\n\n");
+    const title = resolveTitle(options, defs.name);
+    if (!title)
+        return body;
+    const line = "─".repeat(title.length);
+    return `${title}\n${line}\n\n${body}`;
+}
+function resolveTitle(options, definitionsName) {
+    if (options?.title === false)
+        return undefined;
+    if (typeof options?.title === "string")
+        return options.title;
+    return definitionsName ?? undefined;
+}
+//# sourceMappingURL=dmn.js.map

package/dist/edges.d.ts

@@ -0,0 +1,16 @@
+import type { AsciiGrid } from "./grid.js";
+/**
+ * Draw an orthogonal sequence-flow edge from a source exit point to a target
+ * entry point, with an optional short label floated above the edge mid-point.
+ *
+ * `srcCol` — first column after the source element's right border.
+ * `dstCol` — column of the target element's left border (arrow lands at dstCol-1).
+ *
+ * Routing strategy:
+ *   • Same row  → direct horizontal  ──────►
+ *   • Going down → right + turn-down + right  ──┐ / └──►
+ *   • Going up   → right + turn-up   + right  ──┘ / ┌──►
+ *   • Backward   → route above the diagram via row 0
+ */
+export declare function drawEdge(grid: AsciiGrid, srcCol: number, srcRow: number, dstCol: number, dstRow: number, label?: string): void;
+//# sourceMappingURL=edges.d.ts.map

package/dist/edges.js

@@ -0,0 +1,91 @@
+import { truncate } from "./util.js";
+/**
+ * Draw an orthogonal sequence-flow edge from a source exit point to a target
+ * entry point, with an optional short label floated above the edge mid-point.
+ *
+ * `srcCol` — first column after the source element's right border.
+ * `dstCol` — column of the target element's left border (arrow lands at dstCol-1).
+ *
+ * Routing strategy:
+ *   • Same row  → direct horizontal  ──────►
+ *   • Going down → right + turn-down + right  ──┐ / └──►
+ *   • Going up   → right + turn-up   + right  ──┘ / ┌──►
+ *   • Backward   → route above the diagram via row 0
+ */
+export function drawEdge(grid, srcCol, srcRow, dstCol, dstRow, label) {
+    if (dstCol <= srcCol) {
+        drawBackwardEdge(grid, srcCol, srcRow, dstCol, dstRow);
+        return;
+    }
+    if (srcRow === dstRow) {
+        drawHorizontal(grid, srcCol, dstCol, srcRow, label);
+        return;
+    }
+    // L-shaped route: bend immediately after the source exit so that multiple
+    // outgoing edges from the same element diverge right at the exit point,
+    // producing clean ├ junctions rather than a shared horizontal segment.
+    const midCol = srcCol + 1;
+    const goingDown = dstRow > srcRow;
+    // Horizontal leg: srcCol → midCol-1
+    drawHorizontalSegment(grid, srcCol, midCol - 1, srcRow);
+    // Turn at (midCol, srcRow)
+    grid.setLine(midCol, srcRow, goingDown ? "┐" : "┘");
+    // Vertical leg
+    const rowLo = Math.min(srcRow, dstRow);
+    const rowHi = Math.max(srcRow, dstRow);
+    for (let r = rowLo + 1; r < rowHi; r++) {
+        grid.setLine(midCol, r, "│");
+    }
+    // Turn at (midCol, dstRow)
+    grid.setLine(midCol, dstRow, goingDown ? "└" : "┌");
+    // Horizontal leg: midCol+1 → dstCol-2, then arrow
+    drawHorizontalSegment(grid, midCol + 1, dstCol - 2, dstRow);
+    grid.set(dstCol - 1, dstRow, "►");
+    // Label: float above the first horizontal segment's midpoint
+    if (label) {
+        const labelCol = Math.floor((srcCol + midCol) / 2) - Math.floor(label.length / 2);
+        grid.write(labelCol, srcRow - 1, truncate(label, midCol - srcCol));
+    }
+}
+/** Draw a straight horizontal edge from srcCol to dstCol on the given row. */
+function drawHorizontal(grid, srcCol, dstCol, row, label) {
+    drawHorizontalSegment(grid, srcCol, dstCol - 2, row);
+    grid.set(dstCol - 1, row, "►");
+    if (label) {
+        const mid = Math.floor((srcCol + dstCol) / 2) - Math.floor(label.length / 2);
+        grid.write(mid, row - 1, truncate(label, dstCol - srcCol));
+    }
+}
+/** Fill `─` characters from col `a` to col `b` inclusive on the given row.
+ *  Uses setLine so characters merge correctly at junctions (e.g. ─+┐→┬, ─+│→┼). */
+function drawHorizontalSegment(grid, a, b, row) {
+    for (let c = a; c <= b; c++) {
+        grid.setLine(c, row, "─");
+    }
+}
+/**
+ * Backward (loop) edge: routes above the diagram (row 0) so it doesn't
+ * collide with forward-direction elements.
+ *
+ * Route: go up from src to row 0, go left to dstCol, go down to dst.
+ */
+function drawBackwardEdge(grid, srcCol, srcRow, dstCol, dstRow) {
+    const routeRow = 0;
+    // Vertical up from srcRow to routeRow
+    for (let r = routeRow + 1; r < srcRow; r++) {
+        grid.setLine(srcCol, r, "│");
+    }
+    grid.setLine(srcCol, srcRow, "┘");
+    grid.setLine(srcCol, routeRow, "┐");
+    // Horizontal along routeRow from dstCol+1 to srcCol-1
+    for (let c = dstCol + 1; c < srcCol; c++) {
+        grid.setLine(c, routeRow, "─");
+    }
+    grid.setLine(dstCol, routeRow, "┌");
+    // Vertical down from routeRow to dstRow
+    for (let r = routeRow + 1; r < dstRow; r++) {
+        grid.setLine(dstCol, r, "│");
+    }
+    grid.set(dstCol - 1, dstRow, "►");
+}
+//# sourceMappingURL=edges.js.map

package/dist/form.d.ts

@@ -0,0 +1,9 @@
+import type { RenderOptions } from "./types.js";
+/**
+ * Render a Camunda Form JSON string as ASCII art.
+ *
+ * Each form component is drawn in document order as a text mock-up,
+ * showing labels, input placeholders, options, and buttons.
+ */
+export declare function renderFormAscii(json: string, options?: RenderOptions): string;
+//# sourceMappingURL=form.d.ts.map

package/dist/form.js

@@ -0,0 +1,209 @@
+import { Form } from "@bpmnkit/core";
+// ── Width ────────────────────────────────────────────────────────────────────
+const WIDTH = 48; // inner content width (chars)
+function hline(ch = "─") {
+    return ch.repeat(WIDTH);
+}
+function required(req) {
+    return req ? " *" : "";
+}
+// ── Component renderers ───────────────────────────────────────────────────────
+function renderComponent(c, depth = 0) {
+    const indent = "  ".repeat(depth);
+    const lines = [];
+    const k = c;
+    switch (k.type) {
+        case "text": {
+            // Render each line of the text content, prefixed with indent
+            for (const line of k.text.split("\n")) {
+                lines.push(indent + line);
+            }
+            break;
+        }
+        case "textfield":
+        case "textarea": {
+            const lbl = k.label + required(k.validate?.required);
+            const inputBox = k.type === "textarea"
+                ? "┌──────────────────────┐\n│                      │\n│                      │\n└──────────────────────┘"
+                : "[ ______________________ ]";
+            lines.push(indent + lbl);
+            for (const l of inputBox.split("\n"))
+                lines.push(indent + l);
+            break;
+        }
+        case "number": {
+            const lbl = k.label + required(k.validate?.required);
+            lines.push(indent + lbl);
+            lines.push(`${indent}[ 0 ▲▼ ]`);
+            break;
+        }
+        case "datetime": {
+            const lbl = k.dateLabel ?? k.timeLabel ?? "Date/Time";
+            lines.push(indent + lbl + required(k.validate?.required));
+            lines.push(`${indent}[ YYYY-MM-DD ]  [ HH:MM ]`);
+            break;
+        }
+        case "select": {
+            const lbl = k.label + required(k.validate?.required);
+            lines.push(indent + lbl);
+            lines.push(`${indent}[ ▼ Select...            ]`);
+            break;
+        }
+        case "taglist": {
+            const lbl = k.label + required(k.validate?.required);
+            lines.push(indent + lbl);
+            lines.push(`${indent}[ × Tag1  × Tag2  +Add  ]`);
+            break;
+        }
+        case "radio": {
+            const lbl = k.label + required(k.validate?.required);
+            lines.push(indent + lbl);
+            if (k.values) {
+                for (const opt of k.values) {
+                    lines.push(`${indent}  ○ ${opt.label}`);
+                }
+            }
+            else {
+                lines.push(`${indent}  ○ (dynamic options)`);
+            }
+            break;
+        }
+        case "checkbox": {
+            const req = k.validate?.required;
+            lines.push(`${indent}☐  ${k.label}${required(req)}`);
+            break;
+        }
+        case "checklist": {
+            const lbl = k.label + required(k.validate?.required);
+            lines.push(indent + lbl);
+            if (k.values) {
+                for (const opt of k.values) {
+                    lines.push(`${indent}  ☐  ${opt.label}`);
+                }
+            }
+            else {
+                lines.push(`${indent}  ☐  (dynamic options)`);
+            }
+            break;
+        }
+        case "button": {
+            const label = k.label;
+            const inner = `  ${label}  `;
+            lines.push(`${indent}[${inner}]`);
+            break;
+        }
+        case "separator": {
+            lines.push(indent + hline());
+            break;
+        }
+        case "spacer": {
+            lines.push("");
+            break;
+        }
+        case "group": {
+            const top = `┌─ ${k.label} ${"─".repeat(Math.max(0, WIDTH - k.label.length - 4))}┐`;
+            lines.push(indent + top);
+            for (const child of k.components) {
+                for (const l of renderComponent(child, depth + 1)) {
+                    lines.push(l);
+                }
+            }
+            lines.push(`${indent}└${"─".repeat(WIDTH - 1)}┘`);
+            break;
+        }
+        case "dynamiclist": {
+            const label = k.label ?? "List";
+            const top = `┌─ ${label} ${"─".repeat(Math.max(0, WIDTH - label.length - 4))}┐`;
+            lines.push(indent + top);
+            for (const child of k.components) {
+                for (const l of renderComponent(child, depth + 1)) {
+                    lines.push(l);
+                }
+            }
+            lines.push(`${indent}└${"─".repeat(WIDTH - 1)}┘`);
+            lines.push(`${indent}  [+ Add item]`);
+            break;
+        }
+        case "table": {
+            const cols = k.columns ?? [];
+            if (cols.length === 0) {
+                lines.push(`${indent}[ Table: ${k.label ?? "(no label)"} ]`);
+            }
+            else {
+                const colW = Math.max(8, Math.floor((WIDTH - cols.length - 1) / cols.length));
+                const bar = cols.map(() => "─".repeat(colW));
+                lines.push(indent + (k.label ? k.label : "Table"));
+                lines.push(`${indent}┌${bar.join("┬")}┐`);
+                lines.push(`${indent}│${cols.map((col) => col.label.slice(0, colW).padEnd(colW)).join("│")}│`);
+                lines.push(`${indent}├${bar.join("┼")}┤`);
+                lines.push(`${indent}│${bar.map(() => " ".repeat(colW)).join("│")}│`);
+                lines.push(`${indent}└${bar.join("┴")}┘`);
+            }
+            break;
+        }
+        case "image": {
+            lines.push(`${indent}[ 🖼  ${k.alt ?? "Image"} ]`);
+            break;
+        }
+        case "iframe": {
+            lines.push(`${indent}[ iframe: ${k.url ?? "(url)"} ]`);
+            break;
+        }
+        case "html": {
+            lines.push(`${indent}[ HTML content ]`);
+            break;
+        }
+        case "expression": {
+            lines.push(`${indent}[ expr: ${k.expression ?? ""} ]`);
+            break;
+        }
+        case "filepicker": {
+            const lbl = k.label ?? "File";
+            lines.push(indent + lbl + required(undefined));
+            lines.push(`${indent}[ 📎 Choose file... ]`);
+            break;
+        }
+        case "documentPreview": {
+            lines.push(`${indent}[ 📄 ${k.label ?? "Document"} ]`);
+            break;
+        }
+        default: {
+            lines.push(`${indent}[ ${c.type} ]`);
+            break;
+        }
+    }
+    return lines;
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Render a Camunda Form JSON string as ASCII art.
+ *
+ * Each form component is drawn in document order as a text mock-up,
+ * showing labels, input placeholders, options, and buttons.
+ */
+export function renderFormAscii(json, options) {
+    const form = Form.parse(json);
+    const lines = [];
+    for (const comp of form.components) {
+        const compLines = renderComponent(comp);
+        lines.push(...compLines);
+        lines.push(""); // blank line between top-level components
+    }
+    // Remove trailing blank line
+    while (lines.length > 0 && lines[lines.length - 1] === "")
+        lines.pop();
+    const body = lines.join("\n");
+    const title = resolveTitle(options, form.id);
+    if (!title)
+        return body;
+    const line = "─".repeat(title.length);
+    return `${title}\n${line}\n\n${body}`;
+}
+function resolveTitle(options, formId) {
+    if (options?.title === false)
+        return undefined;
+    if (typeof options?.title === "string")
+        return options.title;
+    return formId ?? undefined;
+}
+//# sourceMappingURL=form.js.map

package/dist/grid.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Mutable 2-D character canvas that serialises to a multiline string.
+ *
+ * Coordinates are (col, row) = (x, y), zero-based from the top-left.
+ * Out-of-bounds writes are silently ignored.
+ */
+export declare class AsciiGrid {
+    private readonly cells;
+    readonly cols: number;
+    readonly rows: number;
+    constructor(cols: number, rows: number);
+    /** Overwrite a single cell. Out-of-bounds writes are silently ignored. */
+    set(col: number, row: number, ch: string): void;
+    get(col: number, row: number): string;
+    /**
+     * Write text left-to-right starting at (col, row).
+     * Characters that fall outside the grid are ignored.
+     */
+    write(col: number, row: number, text: string): void;
+    /**
+     * Set a cell, combining with any existing box-drawing char at that position.
+     * Used for edge junctions (e.g. two edges crossing at the same column).
+     */
+    setLine(col: number, row: number, ch: string): void;
+    /** Serialise to a newline-separated string. Trailing spaces on each row are stripped. */
+    toString(): string;
+}
+/**
+ * Merge two box-drawing characters at a junction point by taking the union of
+ * their connection directions. Returns `next` when no merge applies.
+ */
+export declare function mergeBoxChars(existing: string, next: string): string;
+//# sourceMappingURL=grid.d.ts.map

package/dist/grid.js

@@ -0,0 +1,89 @@
+/**
+ * Mutable 2-D character canvas that serialises to a multiline string.
+ *
+ * Coordinates are (col, row) = (x, y), zero-based from the top-left.
+ * Out-of-bounds writes are silently ignored.
+ */
+export class AsciiGrid {
+    cells;
+    cols;
+    rows;
+    constructor(cols, rows) {
+        this.cols = cols;
+        this.rows = rows;
+        this.cells = Array.from({ length: rows }, () => Array(cols).fill(" "));
+    }
+    /** Overwrite a single cell. Out-of-bounds writes are silently ignored. */
+    set(col, row, ch) {
+        if (col < 0 || col >= this.cols || row < 0 || row >= this.rows)
+            return;
+        const r = this.cells[row];
+        if (r !== undefined)
+            r[col] = ch[0] ?? " ";
+    }
+    get(col, row) {
+        if (col < 0 || col >= this.cols || row < 0 || row >= this.rows)
+            return " ";
+        return this.cells[row]?.[col] ?? " ";
+    }
+    /**
+     * Write text left-to-right starting at (col, row).
+     * Characters that fall outside the grid are ignored.
+     */
+    write(col, row, text) {
+        for (let i = 0; i < text.length; i++) {
+            this.set(col + i, row, text[i] ?? " ");
+        }
+    }
+    /**
+     * Set a cell, combining with any existing box-drawing char at that position.
+     * Used for edge junctions (e.g. two edges crossing at the same column).
+     */
+    setLine(col, row, ch) {
+        const existing = this.get(col, row);
+        this.set(col, row, mergeBoxChars(existing, ch));
+    }
+    /** Serialise to a newline-separated string. Trailing spaces on each row are stripped. */
+    toString() {
+        return this.cells.map((row) => row.join("").trimEnd()).join("\n");
+    }
+}
+// Directions each box-drawing char has connections in (L=left R=right U=up D=down)
+const CHAR_DIRS = {
+    "─": "LR",
+    "│": "UD",
+    "┌": "RD",
+    "┐": "LD",
+    "└": "RU",
+    "┘": "LU",
+    "├": "RUD",
+    "┤": "LUD",
+    "┬": "LRD",
+    "┴": "LRU",
+    "┼": "LRUD",
+};
+// Reverse map: sorted direction string → box-drawing char
+const DIRS_CHAR = {};
+for (const [ch, dirs] of Object.entries(CHAR_DIRS)) {
+    DIRS_CHAR[[...dirs].sort().join("")] = ch;
+}
+/**
+ * Merge two box-drawing characters at a junction point by taking the union of
+ * their connection directions. Returns `next` when no merge applies.
+ */
+export function mergeBoxChars(existing, next) {
+    if (existing === " " || existing === next)
+        return next;
+    // Arrows always win
+    if (next === "►" || next === "▼")
+        return next;
+    if (existing === "►" || existing === "▼")
+        return existing;
+    const eDirs = CHAR_DIRS[existing];
+    const nDirs = CHAR_DIRS[next];
+    if (!eDirs || !nDirs)
+        return next;
+    const union = [...new Set([...eDirs, ...nDirs])].sort().join("");
+    return DIRS_CHAR[union] ?? next;
+}
+//# sourceMappingURL=grid.js.map

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { renderBpmnAscii } from "./render.js";
+export { renderDmnAscii } from "./dmn.js";
+export { renderFormAscii } from "./form.js";
+export type { RenderOptions } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,4 @@
+export { renderBpmnAscii } from "./render.js";
+export { renderDmnAscii } from "./dmn.js";
+export { renderFormAscii } from "./form.js";
+//# sourceMappingURL=index.js.map

package/dist/render.d.ts

@@ -0,0 +1,10 @@
+import type { RenderOptions } from "./types.js";
+/**
+ * Render a BPMN XML string as a Unicode box-drawing ASCII diagram.
+ *
+ * Uses the same Sugiyama layout engine as the canvas renderer to position
+ * elements, then maps each element to a fixed-size ASCII box and routes
+ * sequence flows as orthogonal lines.
+ */
+export declare function renderBpmnAscii(xml: string, options?: RenderOptions): string;
+//# sourceMappingURL=render.d.ts.map

package/dist/render.js

@@ -0,0 +1,62 @@
+import { Bpmn, layoutFlowNodes } from "@bpmnkit/core";
+import { drawEdge } from "./edges.js";
+import { AsciiGrid } from "./grid.js";
+import { CELL_H, CELL_W, drawElement, entryCol, exitCol, midRow } from "./shapes.js";
+/**
+ * Render a BPMN XML string as a Unicode box-drawing ASCII diagram.
+ *
+ * Uses the same Sugiyama layout engine as the canvas renderer to position
+ * elements, then maps each element to a fixed-size ASCII box and routes
+ * sequence flows as orthogonal lines.
+ */
+export function renderBpmnAscii(xml, options) {
+    const defs = Bpmn.parse(xml);
+    const process = defs.processes[0];
+    if (!process)
+        return "(empty)";
+    // Use layoutFlowNodes directly to skip the overlap assertion — the ASCII renderer
+    // uses layer/position indices (not pixel coords) so pixel-level overlaps are harmless.
+    const layout = layoutFlowNodes(process.flowElements, process.sequenceFlows);
+    const { nodes, edges } = layout;
+    if (nodes.length === 0)
+        return "(empty)";
+    // Compute grid dimensions from the layout's layer/position extents
+    const maxLayer = Math.max(...nodes.map((n) => n.layer));
+    const maxPos = Math.max(...nodes.map((n) => n.position));
+    // +2 padding on each axis, +1 because layers/positions are 0-indexed
+    const gridCols = (maxLayer + 1) * CELL_W + 4;
+    const gridRows = (maxPos + 1) * CELL_H + 4;
+    const grid = new AsciiGrid(gridCols, gridRows);
+    // Build an id → node map for O(1) edge-endpoint look-up
+    const nodeById = new Map();
+    for (const node of nodes)
+        nodeById.set(node.id, node);
+    // Draw edges first so that shapes render on top of any edge overlap
+    for (const edge of edges) {
+        const src = nodeById.get(edge.sourceRef);
+        const dst = nodeById.get(edge.targetRef);
+        if (!src || !dst)
+            continue;
+        drawEdge(grid, exitCol(src.type, src.layer), midRow(src.position), entryCol(dst.type, dst.layer), midRow(dst.position));
+    }
+    // Draw element boxes on top
+    for (const node of nodes) {
+        drawElement(grid, node.type, node.layer, node.position, node.label);
+    }
+    const diagram = grid.toString();
+    // Optional title header
+    const title = resolveTitle(options, process.name);
+    if (!title)
+        return diagram;
+    const line = "─".repeat(title.length);
+    return `${title}\n${line}\n\n${diagram}`;
+}
+/** Pick the title string to show above the diagram (or undefined to suppress). */
+function resolveTitle(options, processName) {
+    if (options?.title === false)
+        return undefined;
+    if (typeof options?.title === "string")
+        return options.title;
+    return processName ?? undefined;
+}
+//# sourceMappingURL=render.js.map

package/dist/shapes.d.ts

@@ -0,0 +1,37 @@
+import type { AsciiGrid } from "./grid.js";
+/** Total character width of a task box (including the two │ borders). */
+export declare const TASK_W = 24;
+/** Total character width of an event compact box (including borders). */
+export declare const ELEM_W = 11;
+/**
+ * Total character width of a gateway box (including the two border chars).
+ * Narrower than event boxes; corners use / and \ to suggest a rotated square.
+ *
+ * /───────\
+ * │ × Lbl │
+ * \───────/
+ */
+export declare const GATEWAY_W = 9;
+/** Character width of one logical grid cell (one Sugiyama layer). */
+export declare const CELL_W = 28;
+/** Character height of one logical grid cell (one Sugiyama position). */
+export declare const CELL_H = 8;
+/** Top-left column of an element within its cell. */
+export declare function elemCol(type: string, layer: number): number;
+/** Top-left row of a task or event element within its cell (3 rows tall). */
+export declare function elemRow(position: number): number;
+/**
+ * Column of the right exit connection point (first column AFTER the element's
+ * right border — where an outgoing edge begins).
+ */
+export declare function exitCol(type: string, layer: number): number;
+/**
+ * Column of the left entry connection point (the column OF the element's left
+ * border — where an incoming edge arrow lands just before it).
+ */
+export declare function entryCol(type: string, layer: number): number;
+/** Row of the horizontal mid-point (used as the connection row for edges). */
+export declare function midRow(position: number): number;
+/** Draw any BPMN element onto the grid at its logical (layer, position). */
+export declare function drawElement(grid: AsciiGrid, type: string, layer: number, position: number, label: string | undefined): void;
+//# sourceMappingURL=shapes.d.ts.map

package/dist/shapes.js

@@ -0,0 +1,222 @@
+import { truncate } from "./util.js";
+// ── Layout constants ────────────────────────────────────────────────────────
+/** Total character width of a task box (including the two │ borders). */
+export const TASK_W = 24;
+/** Total character width of an event compact box (including borders). */
+export const ELEM_W = 11;
+/**
+ * Total character width of a gateway box (including the two border chars).
+ * Narrower than event boxes; corners use / and \ to suggest a rotated square.
+ *
+ * /───────\
+ * │ × Lbl │
+ * \───────/
+ */
+export const GATEWAY_W = 9;
+/** Character width of one logical grid cell (one Sugiyama layer). */
+export const CELL_W = 28;
+/** Character height of one logical grid cell (one Sugiyama position). */
+export const CELL_H = 8;
+// Derived inner widths (space available for content inside the borders)
+const TASK_INNER = TASK_W - 2; // 22
+const ELEM_INNER = ELEM_W - 2; // 9
+// ── Element classification ──────────────────────────────────────────────────
+function isTaskLike(type) {
+    return (type === "task" ||
+        type === "serviceTask" ||
+        type === "userTask" ||
+        type === "scriptTask" ||
+        type === "sendTask" ||
+        type === "receiveTask" ||
+        type === "businessRuleTask" ||
+        type === "manualTask" ||
+        type === "callActivity" ||
+        type === "subProcess" ||
+        type === "adHocSubProcess" ||
+        type === "eventSubProcess" ||
+        type === "transaction");
+}
+function isGateway(type) {
+    return (type === "exclusiveGateway" ||
+        type === "parallelGateway" ||
+        type === "inclusiveGateway" ||
+        type === "eventBasedGateway" ||
+        type === "complexGateway");
+}
+// ── Label / marker helpers ──────────────────────────────────────────────────
+/** Short type tag prepended to task content, e.g. "[svc] ". */
+function taskTag(type) {
+    switch (type) {
+        case "serviceTask":
+            return "[svc] ";
+        case "userTask":
+            return "[usr] ";
+        case "scriptTask":
+            return "[scr] ";
+        case "sendTask":
+            return "[snd] ";
+        case "receiveTask":
+            return "[rcv] ";
+        case "businessRuleTask":
+            return "[dmn] ";
+        case "manualTask":
+            return "[man] ";
+        case "callActivity":
+            return "[cal] ";
+        case "subProcess":
+        case "adHocSubProcess":
+        case "eventSubProcess":
+            return "[sub] ";
+        case "transaction":
+            return "[txn] ";
+        default:
+            return "";
+    }
+}
+/** Single Unicode marker shown inside an event or gateway shape. */
+function elementMarker(type) {
+    switch (type) {
+        case "startEvent":
+            return "○";
+        case "endEvent":
+            return "●";
+        case "intermediateCatchEvent":
+            return "◎";
+        case "intermediateThrowEvent":
+            return "◉";
+        case "boundaryEvent":
+            return "◈";
+        case "exclusiveGateway":
+            return "×";
+        case "parallelGateway":
+            return "+";
+        case "inclusiveGateway":
+            return "◇";
+        case "eventBasedGateway":
+            return "?";
+        case "complexGateway":
+            return "✱";
+        default:
+            return "·";
+    }
+}
+// ── Position helpers ────────────────────────────────────────────────────────
+/** Width of the element drawn for this type. */
+function elemW(type) {
+    if (isTaskLike(type))
+        return TASK_W;
+    if (isGateway(type))
+        return GATEWAY_W;
+    return ELEM_W;
+}
+/** Top-left column of an element within its cell. */
+export function elemCol(type, layer) {
+    return layer * CELL_W + Math.floor((CELL_W - elemW(type)) / 2);
+}
+/** Top-left row of a task or event element within its cell (3 rows tall). */
+export function elemRow(position) {
+    // Centre the 3-row element vertically within the cell
+    return position * CELL_H + Math.floor((CELL_H - 3) / 2);
+}
+/**
+ * Column of the right exit connection point (first column AFTER the element's
+ * right border — where an outgoing edge begins).
+ */
+export function exitCol(type, layer) {
+    return elemCol(type, layer) + elemW(type);
+}
+/**
+ * Column of the left entry connection point (the column OF the element's left
+ * border — where an incoming edge arrow lands just before it).
+ */
+export function entryCol(type, layer) {
+    return elemCol(type, layer);
+}
+/** Row of the horizontal mid-point (used as the connection row for edges). */
+export function midRow(position) {
+    return elemRow(position) + 1; // middle of the 3-row element
+}
+// ── Drawing ─────────────────────────────────────────────────────────────────
+/** Draw any BPMN element onto the grid at its logical (layer, position). */
+export function drawElement(grid, type, layer, position, label) {
+    const col = elemCol(type, layer);
+    const name = label ?? "";
+    if (isTaskLike(type)) {
+        drawTaskBox(grid, col, elemRow(position), name, type);
+    }
+    else if (isGateway(type)) {
+        drawGatewayBox(grid, col, elemRow(position), name, elementMarker(type));
+    }
+    else {
+        drawCompactBox(grid, col, elemRow(position), name, elementMarker(type));
+    }
+}
+/**
+ * Rectangular task box — 3 rows tall, TASK_W wide.
+ *
+ * ┌──────────────────────┐
+ * │ [tag] Label…         │
+ * └──────────────────────┘
+ */
+function drawTaskBox(grid, col, row, label, type) {
+    const inner = TASK_INNER;
+    // Top border
+    grid.set(col, row, "┌");
+    grid.write(col + 1, row, "─".repeat(inner));
+    grid.set(col + inner + 1, row, "┐");
+    // Middle row
+    grid.set(col, row + 1, "│");
+    const tag = taskTag(type);
+    const content = truncate(tag + label, inner - 1); // -1 for leading space
+    grid.write(col + 1, row + 1, ` ${content}`);
+    grid.set(col + inner + 1, row + 1, "│");
+    // Bottom border
+    grid.set(col, row + 2, "└");
+    grid.write(col + 1, row + 2, "─".repeat(inner));
+    grid.set(col + inner + 1, row + 2, "┘");
+}
+/**
+ * Compact rounded box for events — 3 rows tall, ELEM_W wide.
+ *
+ * ╭─────────╮
+ * │ ○ Label │
+ * ╰─────────╯
+ */
+function drawCompactBox(grid, col, row, label, marker) {
+    const inner = ELEM_INNER;
+    // Top border (rounded)
+    grid.set(col, row, "╭");
+    grid.write(col + 1, row, "─".repeat(inner));
+    grid.set(col + inner + 1, row, "╮");
+    // Middle row: marker + label
+    grid.set(col, row + 1, "│");
+    const content = truncate(`${marker} ${label}`, inner - 1); // -1 for leading space
+    grid.write(col + 1, row + 1, ` ${content}`);
+    grid.set(col + inner + 1, row + 1, "│");
+    // Bottom border (rounded)
+    grid.set(col, row + 2, "╰");
+    grid.write(col + 1, row + 2, "─".repeat(inner));
+    grid.set(col + inner + 1, row + 2, "╯");
+}
+/**
+ * Gateway box — 3 rows tall, GATEWAY_W wide. Diagonal / \ corners suggest a
+ * rotated square. Marker + label shown inside.
+ *
+ * /─────────\
+ * │ × Label │
+ * \─────────/
+ */
+function drawGatewayBox(grid, col, row, label, marker) {
+    const inner = GATEWAY_W - 2;
+    grid.set(col, row, "/");
+    grid.write(col + 1, row, "─".repeat(inner));
+    grid.set(col + inner + 1, row, "\\");
+    grid.set(col, row + 1, "│");
+    const content = truncate(`${marker} ${label}`, inner - 1); // -1 for leading space
+    grid.write(col + 1, row + 1, ` ${content}`);
+    grid.set(col + inner + 1, row + 1, "│");
+    grid.set(col, row + 2, "\\");
+    grid.write(col + 1, row + 2, "─".repeat(inner));
+    grid.set(col + inner + 1, row + 2, "/");
+}
+//# sourceMappingURL=shapes.js.map

package/dist/types.d.ts

@@ -0,0 +1,10 @@
+/** Options for renderBpmnAscii(). */
+export interface RenderOptions {
+    /**
+     * Process name shown as a header above the diagram.
+     * Pass `false` to suppress the header entirely.
+     * Defaults to the process name from the BPMN XML.
+     */
+    title?: string | false;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/util.d.ts

@@ -0,0 +1,5 @@
+/** Truncate `text` to at most `maxLen` characters, appending "…" when shortened. */
+export declare function truncate(text: string, maxLen: number): string;
+/** Pad `text` with trailing spaces so the result is exactly `width` characters wide. */
+export declare function padEnd(text: string, width: number): string;
+//# sourceMappingURL=util.d.ts.map

package/dist/util.js

@@ -0,0 +1,17 @@
+/** Truncate `text` to at most `maxLen` characters, appending "…" when shortened. */
+export function truncate(text, maxLen) {
+    if (maxLen <= 0)
+        return "";
+    if (text.length <= maxLen)
+        return text;
+    if (maxLen === 1)
+        return "…";
+    return `${text.slice(0, maxLen - 1)}…`;
+}
+/** Pad `text` with trailing spaces so the result is exactly `width` characters wide. */
+export function padEnd(text, width) {
+    if (text.length >= width)
+        return text.slice(0, width);
+    return text + " ".repeat(width - text.length);
+}
+//# sourceMappingURL=util.js.map

package/package.json

@@ -0,0 +1,30 @@
+{
+	"name": "@bpmnkit/ascii",
+	"version": "0.0.8",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"files": ["dist/**/*.js", "dist/**/*.d.ts"],
+	"scripts": {
+		"build": "tsc",
+		"typecheck": "tsc --noEmit",
+		"check": "biome check .",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@bpmnkit/core": "workspace:*"
+	},
+	"description": "Render BPMN diagrams as Unicode box-drawing ASCII art — perfect for terminals and docs",
+	"keywords": ["bpmn", "ascii", "terminal", "diagram", "typescript"],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/bpmnkit/monorepo"
+	}
+}