@bpmnkit/core 0.0.8

package/dist/bpmn/compact.js

@@ -0,0 +1,349 @@
+import { layoutProcess } from "../layout/index.js";
+// ── Compactify ───────────────────────────────────────────────────────────────
+function findAttr(ext, name, attr) {
+    return ext.find((e) => e.name === name)?.attributes[attr];
+}
+function compactifyElement(el) {
+    const ext = el.extensionElements;
+    const result = { id: el.id, type: el.type };
+    if (el.name)
+        result.name = el.name;
+    const jobType = findAttr(ext, "zeebe:taskDefinition", "type");
+    if (jobType)
+        result.jobType = jobType;
+    // Extract task headers (key→value map from zeebe:taskHeaders children)
+    const taskHeadersEl = ext.find((e) => e.name === "zeebe:taskHeaders");
+    if (taskHeadersEl && taskHeadersEl.children.length > 0) {
+        const headers = {};
+        for (const child of taskHeadersEl.children) {
+            const key = child.attributes.key;
+            const value = child.attributes.value;
+            if (key !== undefined && value !== undefined)
+                headers[key] = value;
+        }
+        if (Object.keys(headers).length > 0)
+            result.taskHeaders = headers;
+    }
+    const calledProcess = findAttr(ext, "zeebe:calledElement", "processId");
+    if (calledProcess)
+        result.calledProcess = calledProcess;
+    const formId = findAttr(ext, "zeebe:formDefinition", "formId");
+    if (formId)
+        result.formId = formId;
+    const decisionId = findAttr(ext, "zeebe:calledDecision", "decisionId");
+    if (decisionId) {
+        result.decisionId = decisionId;
+        const rv = findAttr(ext, "zeebe:calledDecision", "resultVariable");
+        if (rv)
+            result.resultVariable = rv;
+    }
+    else {
+        // For service tasks: extract the primary output variable from ioMapping
+        const ioMappingEl = ext.find((e) => e.name === "zeebe:ioMapping");
+        if (ioMappingEl) {
+            const outputs = ioMappingEl.children.filter((c) => c.name === "zeebe:output");
+            if (outputs.length === 1) {
+                const target = outputs[0]?.attributes.target;
+                if (target)
+                    result.resultVariable = target;
+            }
+        }
+    }
+    if ("eventDefinitions" in el && el.eventDefinitions.length > 0) {
+        result.eventType = el.eventDefinitions[0]?.type;
+    }
+    if (el.type === "boundaryEvent") {
+        result.attachedTo = el.attachedToRef;
+        if (el.cancelActivity === false)
+            result.interrupting = false;
+    }
+    return result;
+}
+/**
+ * Converts a {@link BpmnDefinitions} model into a token-efficient
+ * {@link CompactDiagram} representation suitable for AI contexts (LLM prompts,
+ * MCP tool calls, etc.). The compact format is typically 5–15× smaller than
+ * raw BPMN XML.
+ *
+ * Use {@link expand} to restore a compact diagram back to a full model with
+ * auto-generated layout.
+ *
+ * @example
+ * ```typescript
+ * import { Bpmn, compactify, expand } from "@bpmnkit/core"
+ *
+ * const defs    = Bpmn.parse(xml)
+ * const compact = compactify(defs)   // send to AI
+ * const restored = expand(compact)   // get back BpmnDefinitions
+ * const xml2    = Bpmn.export(restored)
+ * ```
+ */
+export function compactify(defs) {
+    return {
+        id: defs.id,
+        processes: defs.processes.map((process) => ({
+            id: process.id,
+            name: process.name,
+            elements: process.flowElements.map(compactifyElement),
+            flows: process.sequenceFlows.map((sf) => {
+                const f = { id: sf.id, from: sf.sourceRef, to: sf.targetRef };
+                if (sf.name)
+                    f.name = sf.name;
+                if (sf.conditionExpression)
+                    f.condition = sf.conditionExpression.text;
+                return f;
+            }),
+        })),
+    };
+}
+// ── Expand ───────────────────────────────────────────────────────────────────
+function makeEventDef(eventType) {
+    switch (eventType) {
+        case "timer":
+            return { type: "timer" };
+        case "error":
+            return { type: "error" };
+        case "message":
+            return { type: "message" };
+        case "signal":
+            return { type: "signal" };
+        case "escalation":
+            return { type: "escalation" };
+        case "cancel":
+            return { type: "cancel" };
+        case "terminate":
+            return { type: "terminate" };
+        case "conditional":
+            return { type: "conditional" };
+        case "link":
+            return { type: "link" };
+        case "compensate":
+            return { type: "compensate" };
+        default:
+            return undefined;
+    }
+}
+function makeExtensions(el) {
+    const ext = [];
+    if (el.jobType) {
+        ext.push({ name: "zeebe:taskDefinition", attributes: { type: el.jobType }, children: [] });
+    }
+    if (el.taskHeaders && Object.keys(el.taskHeaders).length > 0) {
+        ext.push({
+            name: "zeebe:taskHeaders",
+            attributes: {},
+            children: Object.entries(el.taskHeaders).map(([key, value]) => ({
+                name: "zeebe:header",
+                attributes: { key, value },
+                children: [],
+            })),
+        });
+    }
+    if (el.calledProcess) {
+        ext.push({
+            name: "zeebe:calledElement",
+            attributes: { processId: el.calledProcess },
+            children: [],
+        });
+    }
+    if (el.formId) {
+        ext.push({ name: "zeebe:formDefinition", attributes: { formId: el.formId }, children: [] });
+    }
+    if (el.decisionId) {
+        ext.push({
+            name: "zeebe:calledDecision",
+            attributes: {
+                decisionId: el.decisionId,
+                resultVariable: el.resultVariable ?? "result",
+            },
+            children: [],
+        });
+    }
+    else if (el.resultVariable && el.jobType) {
+        // Service task with a result variable: map the connector response to the variable
+        ext.push({
+            name: "zeebe:ioMapping",
+            attributes: {},
+            children: [
+                {
+                    name: "zeebe:output",
+                    attributes: { source: "= response", target: el.resultVariable },
+                    children: [],
+                },
+            ],
+        });
+    }
+    return ext;
+}
+function buildFlowElement(el, incoming, outgoing) {
+    const base = {
+        id: el.id,
+        name: el.name,
+        incoming,
+        outgoing,
+        extensionElements: makeExtensions(el),
+        unknownAttributes: {},
+    };
+    const eventDef = el.eventType ? makeEventDef(el.eventType) : undefined;
+    const eventDefs = eventDef ? [eventDef] : [];
+    const subContent = {
+        flowElements: [],
+        sequenceFlows: [],
+        textAnnotations: [],
+        associations: [],
+    };
+    switch (el.type) {
+        case "startEvent":
+            return { ...base, type: "startEvent", eventDefinitions: eventDefs };
+        case "endEvent":
+            return { ...base, type: "endEvent", eventDefinitions: eventDefs };
+        case "intermediateCatchEvent":
+            return { ...base, type: "intermediateCatchEvent", eventDefinitions: eventDefs };
+        case "intermediateThrowEvent":
+            return { ...base, type: "intermediateThrowEvent", eventDefinitions: eventDefs };
+        case "boundaryEvent":
+            return {
+                ...base,
+                type: "boundaryEvent",
+                attachedToRef: el.attachedTo ?? "",
+                cancelActivity: el.interrupting !== false,
+                eventDefinitions: eventDefs,
+            };
+        case "serviceTask":
+            return { ...base, type: "serviceTask" };
+        case "scriptTask":
+            return { ...base, type: "scriptTask" };
+        case "userTask":
+            return { ...base, type: "userTask" };
+        case "businessRuleTask":
+            return { ...base, type: "businessRuleTask" };
+        case "callActivity":
+            return { ...base, type: "callActivity" };
+        case "sendTask":
+            return { ...base, type: "sendTask" };
+        case "receiveTask":
+            return { ...base, type: "receiveTask" };
+        case "manualTask":
+            return { ...base, type: "manualTask" };
+        case "task":
+            return { ...base, type: "task" };
+        case "subProcess":
+            return { ...base, type: "subProcess", ...subContent };
+        case "adHocSubProcess":
+            return { ...base, type: "adHocSubProcess", ...subContent };
+        case "eventSubProcess":
+            return { ...base, type: "eventSubProcess", ...subContent };
+        case "transaction":
+            return { ...base, type: "transaction", ...subContent };
+        case "exclusiveGateway":
+            return { ...base, type: "exclusiveGateway" };
+        case "parallelGateway":
+            return { ...base, type: "parallelGateway" };
+        case "inclusiveGateway":
+            return { ...base, type: "inclusiveGateway" };
+        case "eventBasedGateway":
+            return { ...base, type: "eventBasedGateway" };
+        case "complexGateway":
+            return { ...base, type: "complexGateway" };
+    }
+}
+function buildDiagram(processId, process) {
+    const layout = layoutProcess(process);
+    const shapes = layout.nodes.map((n) => ({
+        id: `${n.id}_di`,
+        bpmnElement: n.id,
+        isExpanded: n.isExpanded,
+        bounds: n.bounds,
+        label: n.labelBounds ? { bounds: n.labelBounds } : undefined,
+        unknownAttributes: {},
+    }));
+    const edges = layout.edges.map((e) => ({
+        id: `${e.id}_di`,
+        bpmnElement: e.id,
+        waypoints: e.waypoints,
+        unknownAttributes: {},
+    }));
+    return {
+        id: `BPMNDiagram_${processId}`,
+        plane: {
+            id: `BPMNPlane_${processId}`,
+            bpmnElement: processId,
+            shapes,
+            edges,
+        },
+    };
+}
+function expandProcess(compact) {
+    const incoming = new Map();
+    const outgoing = new Map();
+    for (const f of compact.flows) {
+        const out = outgoing.get(f.from) ?? [];
+        out.push(f.id);
+        outgoing.set(f.from, out);
+        const inc = incoming.get(f.to) ?? [];
+        inc.push(f.id);
+        incoming.set(f.to, inc);
+    }
+    const flowElements = compact.elements.map((el) => buildFlowElement(el, incoming.get(el.id) ?? [], outgoing.get(el.id) ?? []));
+    const sequenceFlows = compact.flows.map((f) => ({
+        id: f.id,
+        name: f.name,
+        sourceRef: f.from,
+        targetRef: f.to,
+        conditionExpression: f.condition ? { text: f.condition, attributes: {} } : undefined,
+        extensionElements: [],
+        unknownAttributes: {},
+    }));
+    const process = {
+        id: compact.id,
+        name: compact.name,
+        isExecutable: true,
+        extensionElements: [],
+        flowElements,
+        sequenceFlows,
+        textAnnotations: [],
+        associations: [],
+        unknownAttributes: {},
+    };
+    return { process, diagram: buildDiagram(compact.id, process) };
+}
+/**
+ * Restores a {@link CompactDiagram} (produced by {@link compactify} or an AI
+ * model) back to a full {@link BpmnDefinitions} with auto-generated layout.
+ *
+ * @example
+ * ```typescript
+ * const compact = await askAI(prompt)   // AI returns CompactDiagram JSON
+ * const defs    = expand(compact)
+ * const xml     = Bpmn.export(defs)
+ * editor.loadXml(xml)
+ * ```
+ */
+export function expand(compact) {
+    const processes = [];
+    const diagrams = [];
+    for (const cp of compact.processes) {
+        const { process, diagram } = expandProcess(cp);
+        processes.push(process);
+        diagrams.push(diagram);
+    }
+    return {
+        id: compact.id,
+        targetNamespace: "http://bpmn.io/schema/bpmn",
+        namespaces: {
+            bpmn: "http://www.omg.org/spec/BPMN/20100524/MODEL",
+            bpmndi: "http://www.omg.org/spec/BPMN/20100524/DI",
+            dc: "http://www.omg.org/spec/DD/20100524/DC",
+            di: "http://www.omg.org/spec/DD/20100524/DI",
+            zeebe: "http://camunda.org/schema/zeebe/1.0",
+        },
+        unknownAttributes: {},
+        errors: [],
+        escalations: [],
+        messages: [],
+        collaborations: [],
+        processes,
+        diagrams,
+    };
+}
+//# sourceMappingURL=compact.js.map

package/dist/bpmn/di-color.d.ts

@@ -0,0 +1,9 @@
+export declare const BIOC_NS = "http://bpmn.io/schema/bpmn/biocolor/1.0";
+export declare const COLOR_NS = "http://www.omg.org/spec/BPMN/non-normative/color/1.0";
+export interface DiColor {
+    fill?: string;
+    stroke?: string;
+}
+export declare function readDiColor(attrs: Record<string, string>): DiColor;
+export declare function writeDiColor(attrs: Record<string, string>, color: DiColor): Record<string, string>;
+//# sourceMappingURL=di-color.d.ts.map

package/dist/bpmn/di-color.js

@@ -0,0 +1,32 @@
+export const BIOC_NS = "http://bpmn.io/schema/bpmn/biocolor/1.0";
+export const COLOR_NS = "http://www.omg.org/spec/BPMN/non-normative/color/1.0";
+export function readDiColor(attrs) {
+    return {
+        fill: attrs["bioc:fill"] ?? attrs["color:background-color"] ?? undefined,
+        stroke: attrs["bioc:stroke"] ?? attrs["color:border-color"] ?? undefined,
+    };
+}
+export function writeDiColor(attrs, color) {
+    // Build a new object, omitting existing color keys, then add new ones if set
+    const r = {};
+    const colorKeys = new Set([
+        "bioc:fill",
+        "color:background-color",
+        "bioc:stroke",
+        "color:border-color",
+    ]);
+    for (const [k, v] of Object.entries(attrs)) {
+        if (!colorKeys.has(k))
+            r[k] = v;
+    }
+    if (color.fill) {
+        r["bioc:fill"] = color.fill;
+        r["color:background-color"] = color.fill;
+    }
+    if (color.stroke) {
+        r["bioc:stroke"] = color.stroke;
+        r["color:border-color"] = color.stroke;
+    }
+    return r;
+}
+//# sourceMappingURL=di-color.js.map

package/dist/bpmn/index.d.ts

@@ -0,0 +1,105 @@
+import { ProcessBuilder } from "./bpmn-builder.js";
+import type { BpmnDefinitions } from "./bpmn-model.js";
+/** A minimal 3-element BPMN diagram useful for first-launch or "New Diagram" defaults. */
+export declare const SAMPLE_BPMN_XML = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<bpmn:definitions xmlns:bpmn=\"http://www.omg.org/spec/BPMN/20100524/MODEL\"\n  xmlns:bpmndi=\"http://www.omg.org/spec/BPMN/20100524/DI\"\n  xmlns:dc=\"http://www.omg.org/spec/DD/20100524/DC\"\n  xmlns:di=\"http://www.omg.org/spec/DD/20100524/DI\"\n  id=\"Definitions_1\" targetNamespace=\"http://bpmn.io/schema/bpmn\">\n  <bpmn:process id=\"proc\" isExecutable=\"true\">\n    <bpmn:startEvent id=\"start\" name=\"Start\">\n      <bpmn:outgoing>flow1</bpmn:outgoing>\n    </bpmn:startEvent>\n    <bpmn:serviceTask id=\"task1\" name=\"Process Order\">\n      <bpmn:incoming>flow1</bpmn:incoming>\n      <bpmn:outgoing>flow2</bpmn:outgoing>\n    </bpmn:serviceTask>\n    <bpmn:endEvent id=\"end\" name=\"End\">\n      <bpmn:incoming>flow2</bpmn:incoming>\n    </bpmn:endEvent>\n    <bpmn:sequenceFlow id=\"flow1\" sourceRef=\"start\" targetRef=\"task1\"/>\n    <bpmn:sequenceFlow id=\"flow2\" sourceRef=\"task1\" targetRef=\"end\"/>\n  </bpmn:process>\n  <bpmndi:BPMNDiagram id=\"diagram1\">\n    <bpmndi:BPMNPlane id=\"plane1\" bpmnElement=\"proc\">\n      <bpmndi:BPMNShape id=\"start_di\" bpmnElement=\"start\">\n        <dc:Bounds x=\"152\" y=\"202\" width=\"36\" height=\"36\"/>\n      </bpmndi:BPMNShape>\n      <bpmndi:BPMNShape id=\"task1_di\" bpmnElement=\"task1\">\n        <dc:Bounds x=\"260\" y=\"180\" width=\"100\" height=\"80\"/>\n      </bpmndi:BPMNShape>\n      <bpmndi:BPMNShape id=\"end_di\" bpmnElement=\"end\">\n        <dc:Bounds x=\"432\" y=\"202\" width=\"36\" height=\"36\"/>\n      </bpmndi:BPMNShape>\n      <bpmndi:BPMNEdge id=\"flow1_di\" bpmnElement=\"flow1\">\n        <di:waypoint x=\"188\" y=\"220\"/>\n        <di:waypoint x=\"260\" y=\"220\"/>\n      </bpmndi:BPMNEdge>\n      <bpmndi:BPMNEdge id=\"flow2_di\" bpmnElement=\"flow2\">\n        <di:waypoint x=\"360\" y=\"220\"/>\n        <di:waypoint x=\"432\" y=\"220\"/>\n      </bpmndi:BPMNEdge>\n    </bpmndi:BPMNPlane>\n  </bpmndi:BPMNDiagram>\n</bpmn:definitions>";
+/**
+ * Entry point for all BPMN operations — parsing, building, exporting, and
+ * creating empty diagrams.
+ *
+ * @example
+ * ```typescript
+ * import { Bpmn } from "@bpmnkit/core"
+ *
+ * // Parse existing XML
+ * const defs = Bpmn.parse(xml)
+ *
+ * // Build a new process
+ * const defs2 = Bpmn.createProcess("order")
+ *   .startEvent("start")
+ *   .serviceTask("task", { name: "Process", taskType: "process" })
+ *   .endEvent("end")
+ *   .withAutoLayout()
+ *   .build()
+ *
+ * const xml2 = Bpmn.export(defs2)
+ * ```
+ */
+export declare const Bpmn: {
+    /**
+     * Create a new BPMN process using the fluent builder API.
+     *
+     * @param processId - Unique identifier for the process (used as the XML `id` attribute).
+     *
+     * @example
+     * ```typescript
+     * const defs = Bpmn.createProcess("order-process")
+     *   .startEvent("start", { name: "Order received" })
+     *   .serviceTask("validate", { name: "Validate", taskType: "validate-order" })
+     *   .endEvent("end")
+     *   .withAutoLayout()
+     *   .build()
+     * ```
+     */
+    readonly createProcess: (processId: string) => ProcessBuilder;
+    /**
+     * Parse a BPMN 2.0 XML string into a typed {@link BpmnDefinitions} model.
+     *
+     * @param xml - BPMN 2.0 XML string (must contain a `<bpmn:definitions>` root).
+     * @returns Typed definitions object.
+     * @throws {ParseError} If the XML is malformed or a required attribute is missing.
+     *
+     * @example
+     * ```typescript
+     * import { Bpmn, ParseError } from "@bpmnkit/core"
+     *
+     * try {
+     *   const defs = Bpmn.parse(xmlString)
+     *   console.log(defs.processes[0].id)
+     * } catch (err) {
+     *   if (err instanceof ParseError) console.error(err.message)
+     * }
+     * ```
+     */
+    readonly parse: (xml: string) => BpmnDefinitions;
+    /**
+     * Serialise a {@link BpmnDefinitions} model back to BPMN 2.0 XML.
+     *
+     * @param definitions - The typed BPMN model to export.
+     * @returns A BPMN 2.0 XML string.
+     *
+     * @example
+     * ```typescript
+     * const xml = Bpmn.export(defs)
+     * fs.writeFileSync("diagram.bpmn", xml, "utf-8")
+     * ```
+     */
+    readonly export: (definitions: BpmnDefinitions) => string;
+    /**
+     * Returns a minimal valid BPMN XML string containing one process with a
+     * single start event. Useful for "New Diagram" / empty-canvas actions.
+     *
+     * @param processId - Process id (defaults to a random string).
+     * @param processName - Human-readable process name (defaults to `"New Process"`).
+     *
+     * @example
+     * ```typescript
+     * const xml = Bpmn.makeEmpty("order-process", "Order Process")
+     * editor.loadXml(xml)
+     * ```
+     */
+    readonly makeEmpty: (processId?: string, processName?: string) => string;
+    /** A minimal 3-element sample diagram. Re-exported for convenience. */
+    readonly SAMPLE_XML: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<bpmn:definitions xmlns:bpmn=\"http://www.omg.org/spec/BPMN/20100524/MODEL\"\n  xmlns:bpmndi=\"http://www.omg.org/spec/BPMN/20100524/DI\"\n  xmlns:dc=\"http://www.omg.org/spec/DD/20100524/DC\"\n  xmlns:di=\"http://www.omg.org/spec/DD/20100524/DI\"\n  id=\"Definitions_1\" targetNamespace=\"http://bpmn.io/schema/bpmn\">\n  <bpmn:process id=\"proc\" isExecutable=\"true\">\n    <bpmn:startEvent id=\"start\" name=\"Start\">\n      <bpmn:outgoing>flow1</bpmn:outgoing>\n    </bpmn:startEvent>\n    <bpmn:serviceTask id=\"task1\" name=\"Process Order\">\n      <bpmn:incoming>flow1</bpmn:incoming>\n      <bpmn:outgoing>flow2</bpmn:outgoing>\n    </bpmn:serviceTask>\n    <bpmn:endEvent id=\"end\" name=\"End\">\n      <bpmn:incoming>flow2</bpmn:incoming>\n    </bpmn:endEvent>\n    <bpmn:sequenceFlow id=\"flow1\" sourceRef=\"start\" targetRef=\"task1\"/>\n    <bpmn:sequenceFlow id=\"flow2\" sourceRef=\"task1\" targetRef=\"end\"/>\n  </bpmn:process>\n  <bpmndi:BPMNDiagram id=\"diagram1\">\n    <bpmndi:BPMNPlane id=\"plane1\" bpmnElement=\"proc\">\n      <bpmndi:BPMNShape id=\"start_di\" bpmnElement=\"start\">\n        <dc:Bounds x=\"152\" y=\"202\" width=\"36\" height=\"36\"/>\n      </bpmndi:BPMNShape>\n      <bpmndi:BPMNShape id=\"task1_di\" bpmnElement=\"task1\">\n        <dc:Bounds x=\"260\" y=\"180\" width=\"100\" height=\"80\"/>\n      </bpmndi:BPMNShape>\n      <bpmndi:BPMNShape id=\"end_di\" bpmnElement=\"end\">\n        <dc:Bounds x=\"432\" y=\"202\" width=\"36\" height=\"36\"/>\n      </bpmndi:BPMNShape>\n      <bpmndi:BPMNEdge id=\"flow1_di\" bpmnElement=\"flow1\">\n        <di:waypoint x=\"188\" y=\"220\"/>\n        <di:waypoint x=\"260\" y=\"220\"/>\n      </bpmndi:BPMNEdge>\n      <bpmndi:BPMNEdge id=\"flow2_di\" bpmnElement=\"flow2\">\n        <di:waypoint x=\"360\" y=\"220\"/>\n        <di:waypoint x=\"432\" y=\"220\"/>\n      </bpmndi:BPMNEdge>\n    </bpmndi:BPMNPlane>\n  </bpmndi:BPMNDiagram>\n</bpmn:definitions>";
+    /**
+     * Apply auto-layout to a BPMN XML string.
+     *
+     * Parses the XML, runs the Sugiyama layered layout algorithm on every process,
+     * replaces all BPMNDi positions with the computed layout, and returns the
+     * updated XML.  Works for plain processes and collaborations with pools/lanes.
+     *
+     * @param xml - BPMN 2.0 XML string
+     * @returns BPMN 2.0 XML string with updated diagram interchange
+     */
+    readonly autoLayout: (xml: string) => string;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/bpmn/index.js

@@ -0,0 +1,176 @@
+import { applyAutoLayout } from "./auto-layout.js";
+import { ProcessBuilder } from "./bpmn-builder.js";
+import { parseBpmn } from "./bpmn-parser.js";
+import { serializeBpmn } from "./bpmn-serializer.js";
+/** A minimal 3-element BPMN diagram useful for first-launch or "New Diagram" defaults. */
+export const SAMPLE_BPMN_XML = `<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
+  xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI"
+  xmlns:dc="http://www.omg.org/spec/DD/20100524/DC"
+  xmlns:di="http://www.omg.org/spec/DD/20100524/DI"
+  id="Definitions_1" targetNamespace="http://bpmn.io/schema/bpmn">
+  <bpmn:process id="proc" isExecutable="true">
+    <bpmn:startEvent id="start" name="Start">
+      <bpmn:outgoing>flow1</bpmn:outgoing>
+    </bpmn:startEvent>
+    <bpmn:serviceTask id="task1" name="Process Order">
+      <bpmn:incoming>flow1</bpmn:incoming>
+      <bpmn:outgoing>flow2</bpmn:outgoing>
+    </bpmn:serviceTask>
+    <bpmn:endEvent id="end" name="End">
+      <bpmn:incoming>flow2</bpmn:incoming>
+    </bpmn:endEvent>
+    <bpmn:sequenceFlow id="flow1" sourceRef="start" targetRef="task1"/>
+    <bpmn:sequenceFlow id="flow2" sourceRef="task1" targetRef="end"/>
+  </bpmn:process>
+  <bpmndi:BPMNDiagram id="diagram1">
+    <bpmndi:BPMNPlane id="plane1" bpmnElement="proc">
+      <bpmndi:BPMNShape id="start_di" bpmnElement="start">
+        <dc:Bounds x="152" y="202" width="36" height="36"/>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="task1_di" bpmnElement="task1">
+        <dc:Bounds x="260" y="180" width="100" height="80"/>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="end_di" bpmnElement="end">
+        <dc:Bounds x="432" y="202" width="36" height="36"/>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNEdge id="flow1_di" bpmnElement="flow1">
+        <di:waypoint x="188" y="220"/>
+        <di:waypoint x="260" y="220"/>
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="flow2_di" bpmnElement="flow2">
+        <di:waypoint x="360" y="220"/>
+        <di:waypoint x="432" y="220"/>
+      </bpmndi:BPMNEdge>
+    </bpmndi:BPMNPlane>
+  </bpmndi:BPMNDiagram>
+</bpmn:definitions>`;
+/**
+ * Entry point for all BPMN operations — parsing, building, exporting, and
+ * creating empty diagrams.
+ *
+ * @example
+ * ```typescript
+ * import { Bpmn } from "@bpmnkit/core"
+ *
+ * // Parse existing XML
+ * const defs = Bpmn.parse(xml)
+ *
+ * // Build a new process
+ * const defs2 = Bpmn.createProcess("order")
+ *   .startEvent("start")
+ *   .serviceTask("task", { name: "Process", taskType: "process" })
+ *   .endEvent("end")
+ *   .withAutoLayout()
+ *   .build()
+ *
+ * const xml2 = Bpmn.export(defs2)
+ * ```
+ */
+export const Bpmn = {
+    /**
+     * Create a new BPMN process using the fluent builder API.
+     *
+     * @param processId - Unique identifier for the process (used as the XML `id` attribute).
+     *
+     * @example
+     * ```typescript
+     * const defs = Bpmn.createProcess("order-process")
+     *   .startEvent("start", { name: "Order received" })
+     *   .serviceTask("validate", { name: "Validate", taskType: "validate-order" })
+     *   .endEvent("end")
+     *   .withAutoLayout()
+     *   .build()
+     * ```
+     */
+    createProcess(processId) {
+        return new ProcessBuilder(processId);
+    },
+    /**
+     * Parse a BPMN 2.0 XML string into a typed {@link BpmnDefinitions} model.
+     *
+     * @param xml - BPMN 2.0 XML string (must contain a `<bpmn:definitions>` root).
+     * @returns Typed definitions object.
+     * @throws {ParseError} If the XML is malformed or a required attribute is missing.
+     *
+     * @example
+     * ```typescript
+     * import { Bpmn, ParseError } from "@bpmnkit/core"
+     *
+     * try {
+     *   const defs = Bpmn.parse(xmlString)
+     *   console.log(defs.processes[0].id)
+     * } catch (err) {
+     *   if (err instanceof ParseError) console.error(err.message)
+     * }
+     * ```
+     */
+    parse(xml) {
+        return parseBpmn(xml);
+    },
+    /**
+     * Serialise a {@link BpmnDefinitions} model back to BPMN 2.0 XML.
+     *
+     * @param definitions - The typed BPMN model to export.
+     * @returns A BPMN 2.0 XML string.
+     *
+     * @example
+     * ```typescript
+     * const xml = Bpmn.export(defs)
+     * fs.writeFileSync("diagram.bpmn", xml, "utf-8")
+     * ```
+     */
+    export(definitions) {
+        return serializeBpmn(definitions);
+    },
+    /**
+     * Returns a minimal valid BPMN XML string containing one process with a
+     * single start event. Useful for "New Diagram" / empty-canvas actions.
+     *
+     * @param processId - Process id (defaults to a random string).
+     * @param processName - Human-readable process name (defaults to `"New Process"`).
+     *
+     * @example
+     * ```typescript
+     * const xml = Bpmn.makeEmpty("order-process", "Order Process")
+     * editor.loadXml(xml)
+     * ```
+     */
+    makeEmpty(processId = `Process_${Math.random().toString(36).slice(2, 9)}`, processName = "New Process") {
+        const startId = `StartEvent_${processId}`;
+        return `<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
+  xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI"
+  xmlns:dc="http://www.omg.org/spec/DD/20100524/DC"
+  id="Definitions_${processId}" targetNamespace="http://bpmn.io/schema/bpmn">
+  <bpmn:process id="${processId}" name="${processName}" isExecutable="true">
+    <bpmn:startEvent id="${startId}"/>
+  </bpmn:process>
+  <bpmndi:BPMNDiagram id="BPMNDiagram_${processId}">
+    <bpmndi:BPMNPlane id="BPMNPlane_${processId}" bpmnElement="${processId}">
+      <bpmndi:BPMNShape id="${startId}_di" bpmnElement="${startId}">
+        <dc:Bounds x="152" y="82" width="36" height="36"/>
+      </bpmndi:BPMNShape>
+    </bpmndi:BPMNPlane>
+  </bpmndi:BPMNDiagram>
+</bpmn:definitions>`;
+    },
+    /** A minimal 3-element sample diagram. Re-exported for convenience. */
+    SAMPLE_XML: SAMPLE_BPMN_XML,
+    /**
+     * Apply auto-layout to a BPMN XML string.
+     *
+     * Parses the XML, runs the Sugiyama layered layout algorithm on every process,
+     * replaces all BPMNDi positions with the computed layout, and returns the
+     * updated XML.  Works for plain processes and collaborations with pools/lanes.
+     *
+     * @param xml - BPMN 2.0 XML string
+     * @returns BPMN 2.0 XML string with updated diagram interchange
+     */
+    autoLayout(xml) {
+        const defs = parseBpmn(xml);
+        const laid = applyAutoLayout(defs);
+        return serializeBpmn(laid);
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/bpmn/optimize/feel.d.ts

@@ -0,0 +1,4 @@
+import type { BpmnProcess } from "../bpmn-model.js";
+import type { OptimizationFinding, ResolvedOptions } from "./types.js";
+export declare function analyzeFeel(p: BpmnProcess, opts: ResolvedOptions): OptimizationFinding[];
+//# sourceMappingURL=feel.d.ts.map