@bysages/workflow 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 By Sages
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @bysages/workflow
+
+![npm version](https://img.shields.io/npm/v/@bysages/workflow)
+![npm downloads](https://img.shields.io/npm/dw/@bysages/workflow)
+![npm license](https://img.shields.io/npm/l/@bysages/workflow)
+
+> The workflow canvas for By Sages Elements — a headless graph protocol (store, change stream, versioned serialization) with an [AntV X6](https://x6.antv.antgroup.com) adapter on top, dressed entirely by the paper-and-ink styles from `@bysages/core`.
+
+## Features
+
+- 🧠 **Headless first** — the protocol layer (`types`, `store`, `serialize`) imports no X6: executors, persistence, and tests run in Node, and the canvas engine stays replaceable
+- 🖋 **Visuals live in core** — cards, handles, edges, and the minimap are `data-scope="workflow"` styles driven by tokens; light/dark, accent, contrast, and density tiers come free
+- 🧩 **Host-owned nodes** — `renderNode` hands every node card to your framework (Vue, React, or plain DOM); the canvas never mounts content of its own
+- 🎛 **Editor-grade defaults** — drag, connect with direction-aware handles, rubberband select, undo/redo, delete, minimap, fit view; the elkjs auto layout reads the edges' ports and sweeps the way the graph flows
+- ⛓ **Execution stays out of history** — state writes (`node:state`, `edge:state`) ride a separate change source and never enter the undo stack
+
+## Installation
+
+```bash
+# pnpm
+pnpm add @bysages/workflow
+
+# npm
+npm install @bysages/workflow
+
+# yarn
+yarn add @bysages/workflow
+
+# bun
+bun add @bysages/workflow
+```
+
+X6 is browser-only — import the canvas from client code only (a dynamic import in SSR apps).
+
+## Quick Start
+
+Describe the graph as data, mount a canvas, and hand each card to your framework:
+
+```ts
+import { createWorkflowCanvas, createWorkflowStore } from "@bysages/workflow";
+
+const store = createWorkflowStore({
+  nodes: [
+    {
+      id: "start",
+      type: "start",
+      position: { x: 60, y: 40 },
+      ports: [{ id: "out-1", dir: "out" }],
+      data: { label: "Start" },
+    },
+    // …
+  ],
+  edges: [],
+});
+
+const canvas = createWorkflowCanvas(host, store, {
+  // Your framework mounts the content of every node card.
+  renderNode: (card, node) => {
+    card.textContent = String(node.data.label ?? node.id);
+  },
+  minimap: { container: mapHost },
+});
+
+// Execution writes states back through the store — the canvas lights up.
+store.setNodeState("start", "running");
+
+// Persist the whole graph with a version envelope.
+const saved = serializeWorkflowGraph(store.getGraph());
+```
+
+Every write goes through the store and fans out as a change; the canvas applies host changes, and host listeners observe canvas changes — drag a node and your store subscription sees it, write a position and the canvas moves it.
+
+## License
+
+- [MIT](../../LICENSE) © [By Sages](https://www.bysages.com/)

package/dist/index.d.mts

@@ -0,0 +1,202 @@
+import { Graph } from "@antv/x6";
+//#region src/types.d.ts
+/** The engine-independent facts of a workflow graph. The canvas adapter
+ * reads them; the execution backend writes states back through the
+ * store. Nothing here knows about SVG, DOM, or any rendering engine.
+ *
+ * These shapes deliberately don't reuse X6's (NodeMetadata, TerminalData,
+ * PointLike, …): importing them would couple the protocol's type surface
+ * to the canvas engine, and executors — servers included — would then
+ * carry X6's types just to describe a graph. Duplication here is the
+ * boundary, not an oversight. */
+/** Runtime state of one node — the same `data-state` contract every
+ * component reads. The canvas only displays it; the executor writes it. */
+export type NodeState = "idle" | "running" | "success" | "error";
+export interface Position {
+  x: number;
+  y: number;
+}
+/** A logical port. `dir` fixes the geometry (in = top, out = bottom);
+ * `type` is reserved for typed-connection labels. */
+export interface WorkflowPort {
+  id: string;
+  dir: "in" | "out";
+  type?: string;
+}
+export type WorkflowNodeData = Record<string, unknown>;
+/** One node on the graph. `type` is the renderer's lookup key; `ports`
+ * is required — the adapter derives geometry and connection validation
+ * from it. `state` defaults to idle. */
+export interface WorkflowNode {
+  id: string;
+  type: string;
+  position: Position;
+  ports: WorkflowPort[];
+  state?: NodeState;
+  data: WorkflowNodeData;
+}
+export interface WorkflowEndpoint {
+  node: string;
+  port: string;
+}
+export interface WorkflowEdge {
+  id: string;
+  source: WorkflowEndpoint;
+  target: WorkflowEndpoint;
+  /** Runtime state — the same `data-state` contract the CSS reads on the
+   * edge line. The canvas only displays it; the executor writes it. */
+  state?: NodeState;
+}
+export interface WorkflowGraph {
+  nodes: readonly WorkflowNode[];
+  edges: readonly WorkflowEdge[];
+}
+//#endregion
+//#region src/store.d.ts
+/** A record of one graph change. It is both the listener payload and the
+ * command protocol: replaying changes is how an executor (or a future
+ * undo stack) drives the graph from the outside. */
+export type WorkflowChange = {
+  kind: "node:add";
+  node: WorkflowNode;
+} | {
+  kind: "node:remove";
+  id: string;
+} | {
+  kind: "node:move";
+  id: string;
+  position: Position;
+} | {
+  kind: "node:state";
+  id: string;
+  state: NodeState;
+} | {
+  kind: "node:data";
+  id: string;
+  patch: WorkflowNodeData;
+} | {
+  kind: "edge:connect";
+  edge: WorkflowEdge;
+} | {
+  kind: "edge:state";
+  id: string;
+  state: NodeState;
+} | {
+  kind: "edge:remove";
+  id: string;
+};
+/** Who set a change in motion: the canvas translating one of its own
+ * gestures, or anything else (the host, an executor, a future undo
+ * stack). Listeners read it to skip echoing a change back to where it
+ * came from — the same office Yjs' transaction origin serves. */
+export type WorkflowChangeSource = "canvas" | "host";
+export interface WorkflowStore {
+  getGraph(): WorkflowGraph;
+  getNode(id: string): Readonly<WorkflowNode> | undefined;
+  getEdge(id: string): Readonly<WorkflowEdge> | undefined;
+  addNode(node: WorkflowNode): void;
+  /** Removes a node and every edge attached to it, each removal its own
+   * change event. Unknown ids are a silent no-op — idempotence is what
+   * breaks the canvas event loops. */
+  removeNode(id: string): void;
+  moveNode(id: string, position: Position): void;
+  setNodeState(id: string, state: NodeState): void;
+  /** Shallow-merges into the node's data. */
+  setNodeData(id: string, patch: WorkflowNodeData): void;
+  /** Connects two ports and returns the edge; an already existing
+   * source→target pair (or id) returns that edge untouched. */
+  connect(edge: Omit<WorkflowEdge, "id"> & {
+    id?: string;
+  }): WorkflowEdge | undefined;
+  /** Marks an edge's execution state — the edge twin of setNodeState. */
+  setEdgeState(id: string, state: NodeState): void;
+  disconnect(id: string): void;
+  /** Runs fn, attributing every change it commits to `source`. The
+   * attribution covers this one synchronous call only: a listener the
+   * changes notify writes back as the host, never as `source` — which
+   * is what keeps a listener's own follow-up writes from being
+   * silently swallowed by the listener that skips echoes. */
+  asSource<T>(source: WorkflowChangeSource, fn: () => T): T;
+  subscribe(listener: (change: WorkflowChange, source: WorkflowChangeSource) => void): () => void;
+}
+/** The single writer of the graph. Every operation is idempotent (unknown
+ * ids are silent no-ops, redundant writes don't re-emit) so event loops
+ * between the canvas and the store die on their own. */
+export declare function createWorkflowStore(graph?: WorkflowGraph): WorkflowStore;
+//#endregion
+//#region src/serialize.d.ts
+/** The wire format's contract version. Bump it whenever the graph shape
+ * breaks what older readers expect, and teach deserialize to migrate. */
+export declare const WORKFLOW_GRAPH_VERSION = 1;
+/** The versioned envelope a graph travels in. */
+export interface SerializedWorkflowGraph {
+  version: typeof WORKFLOW_GRAPH_VERSION;
+  graph: WorkflowGraph;
+}
+export declare const serializeWorkflowGraph: (graph: WorkflowGraph) => SerializedWorkflowGraph;
+/** Reads a serialized graph back. An unrecognized version means the
+ * payload was written by an incompatible writer — refuse it loudly
+ * rather than render a half-understood graph. */
+export declare const deserializeWorkflowGraph: (serialized: {
+  version: number;
+  graph: WorkflowGraph;
+}) => WorkflowGraph;
+//#endregion
+//#region src/x6-canvas.d.ts
+/** How the layered engine should sweep the graph. Left out, the
+ * direction is read off the graph: edges drawn between side handles
+ * vote horizontal, edges between the top/bottom handles vote
+ * vertical. Top-to-bottom suits the node's first in/out pair — out
+ * handles on the bottom, in handles on top. */
+export interface WorkflowAutoLayoutOptions {
+  direction?: "TB" | "LR" | "BT" | "RL";
+  /** The gap between layers, in px. */
+  rankSep?: number;
+  /** The gap between siblings on one layer, in px. */
+  nodeSep?: number;
+}
+/** The framework mount point: the host mounts its components into the
+ * node's card and returns an unmount cleanup (optional). Content updates
+ * stay with the host — subscribe to the store in the closure. */
+export interface WorkflowCanvasOptions {
+  renderNode?: (host: HTMLElement, node: Readonly<WorkflowNode>) => void | (() => void);
+  /** Handed the live Graph once it exists — the escape hatch for plugin
+   * wiring this adapter doesn't cover. */
+  onReady?: (graph: Graph) => void;
+  /** Renders a live minimap into the given element. */
+  minimap?: {
+    container: HTMLElement;
+  };
+}
+/** Viewport options for fitView. X6's own fit options are accepted in
+ * full through the graph escape hatch; these cover the calls a toolbar
+ * actually makes. */
+export interface WorkflowFitViewOptions {
+  padding?: number;
+  maxScale?: number;
+  minScale?: number;
+}
+export interface WorkflowCanvas {
+  readonly store: WorkflowStore;
+  /** Read-only escape hatch; the lifecycle stays with the canvas. */
+  readonly graph: Graph;
+  /** Multiplies the current zoom — the relative step X6's own API
+   * doesn't offer, and what every zoom toolbar button is. */
+  zoomBy(factor: number): void;
+  /** Frames the whole graph. Defaults to what a toolbar wants: a
+   * breathing margin and no magnifying past 100%. */
+  fitView(options?: WorkflowFitViewOptions): void;
+  /** Sweeps the graph with the ELK layered algorithm and writes every
+   * node's new position back through the store. Async: the layout
+   * engine is heavy, so it's pulled in only when this runs. */
+  layout(options?: WorkflowAutoLayoutOptions): Promise<void>;
+  destroy(): void;
+}
+/** Mounts an X6 canvas onto `container` and keeps it in step with the
+ * graph protocol. The store is the single writer; canvas gestures are
+ * translated back into store calls, and store changes — from an executor
+ * or the host app — are replayed onto the canvas. Every store operation
+ * is idempotent, which is what lets those two event streams cross
+ * without loops. */
+export declare function createWorkflowCanvas(container: HTMLElement, source: WorkflowGraph | WorkflowStore, options?: WorkflowCanvasOptions): WorkflowCanvas;
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,561 @@
+import { Graph, History, Keyboard, MiniMap, Selection, Shape } from "@antv/x6";
+import { injectComponentStyle } from "@bysages/core";
+//#region src/store.ts
+/** The single writer of the graph. Every operation is idempotent (unknown
+* ids are silent no-ops, redundant writes don't re-emit) so event loops
+* between the canvas and the store die on their own. */
+function createWorkflowStore(graph) {
+	const copyNode = (node) => ({
+		...node,
+		position: { ...node.position },
+		ports: node.ports.map((port) => ({ ...port })),
+		data: { ...node.data }
+	});
+	const nodes = new Map(graph?.nodes.map((n) => [n.id, copyNode(n)]) ?? []);
+	const edges = new Map(graph?.edges.map((e) => [e.id, { ...e }]) ?? []);
+	const listeners = /* @__PURE__ */ new Set();
+	let edgeSeq = 0;
+	let changeSource = "host";
+	const nextEdgeId = () => {
+		let id;
+		do
+			id = `edge-${++edgeSeq}`;
+		while (edges.has(id));
+		return id;
+	};
+	const commit = (change) => {
+		const source = changeSource;
+		changeSource = "host";
+		try {
+			for (const listener of Array.from(listeners)) listener(change, source);
+		} finally {
+			changeSource = source;
+		}
+	};
+	const store = {
+		getGraph: () => ({
+			nodes: [...nodes.values()],
+			edges: [...edges.values()]
+		}),
+		getNode: (id) => nodes.get(id),
+		getEdge: (id) => edges.get(id),
+		addNode(node) {
+			if (nodes.has(node.id)) return;
+			nodes.set(node.id, copyNode(node));
+			commit({
+				kind: "node:add",
+				node: copyNode(node)
+			});
+		},
+		removeNode(id) {
+			if (!nodes.delete(id)) return;
+			for (const edge of Array.from(edges.values())) if (edge.source.node === id || edge.target.node === id) store.disconnect(edge.id);
+			commit({
+				kind: "node:remove",
+				id
+			});
+		},
+		moveNode(id, position) {
+			const node = nodes.get(id);
+			if (!node) return;
+			if (node.position.x === position.x && node.position.y === position.y) return;
+			node.position = { ...position };
+			commit({
+				kind: "node:move",
+				id,
+				position: { ...position }
+			});
+		},
+		setNodeState(id, state) {
+			const node = nodes.get(id);
+			if (!node || node.state === state) return;
+			node.state = state;
+			commit({
+				kind: "node:state",
+				id,
+				state
+			});
+		},
+		setNodeData(id, patch) {
+			const node = nodes.get(id);
+			if (!node) return;
+			node.data = {
+				...node.data,
+				...patch
+			};
+			commit({
+				kind: "node:data",
+				id,
+				patch: { ...patch }
+			});
+		},
+		connect(edge) {
+			const byId = edge.id != null ? edges.get(edge.id) : void 0;
+			if (byId) return byId;
+			const source = { ...edge.source };
+			const target = { ...edge.target };
+			for (const existing of edges.values()) if (existing.source.node === source.node && existing.source.port === source.port && existing.target.node === target.node && existing.target.port === target.port) return existing;
+			const record = {
+				id: edge.id ?? nextEdgeId(),
+				source,
+				target
+			};
+			if (edge.state) record.state = edge.state;
+			edges.set(record.id, record);
+			commit({
+				kind: "edge:connect",
+				edge: { ...record }
+			});
+			return record;
+		},
+		setEdgeState(id, state) {
+			const edge = edges.get(id);
+			if (!edge || edge.state === state) return;
+			edge.state = state;
+			commit({
+				kind: "edge:state",
+				id,
+				state
+			});
+		},
+		disconnect(id) {
+			if (!edges.delete(id)) return;
+			commit({
+				kind: "edge:remove",
+				id
+			});
+		},
+		asSource(source, fn) {
+			const outer = changeSource;
+			changeSource = source;
+			try {
+				return fn();
+			} finally {
+				changeSource = outer;
+			}
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		}
+	};
+	return store;
+}
+//#endregion
+//#region src/serialize.ts
+/** The wire format's contract version. Bump it whenever the graph shape
+* breaks what older readers expect, and teach deserialize to migrate. */
+const WORKFLOW_GRAPH_VERSION = 1;
+const serializeWorkflowGraph = (graph) => ({
+	version: 1,
+	graph
+});
+/** Reads a serialized graph back. An unrecognized version means the
+* payload was written by an incompatible writer — refuse it loudly
+* rather than render a half-understood graph. */
+const deserializeWorkflowGraph = (serialized) => {
+	if (serialized.version !== 1) throw new Error(`Unsupported workflow graph version ${serialized.version} (expected 1)`);
+	return serialized.graph;
+};
+//#endregion
+//#region src/x6-canvas.ts
+const NODE_WIDTH = 256;
+const NODE_HEIGHT = 88;
+const HANDLE = 12;
+const canvasContexts = /* @__PURE__ */ new WeakMap();
+const SHAPE_NAME = "workflow-html-node";
+Shape.HTML.register({
+	shape: SHAPE_NAME,
+	effect: [],
+	width: NODE_WIDTH,
+	height: NODE_HEIGHT,
+	html(cell) {
+		const model = cell.model;
+		const context = model ? canvasContexts.get(model.graph) : void 0;
+		if (!context) return document.createElement("div");
+		const node = context.store.getNode(cell.id);
+		if (!node) return document.createElement("div");
+		const host = document.createElement("div");
+		host.dataset.scope = "workflow";
+		host.dataset.part = "node";
+		const card = document.createElement("div");
+		card.className = "workflow-node-card";
+		card.dataset.state = node.state ?? "idle";
+		host.append(card);
+		const dispose = context.renderNode?.(card, node);
+		if (dispose) context.cleanups.set(cell.id, dispose);
+		cell.on("change:data", ({ current }) => {
+			const data = current ?? {};
+			card.dataset.state = data.workflowState ?? "idle";
+		});
+		return host;
+	}
+});
+/** One live canvas per container — re-creating over an existing canvas
+* (hot reload does this) tears the old one down first. */
+const live = /* @__PURE__ */ new WeakMap();
+/** Mounts an X6 canvas onto `container` and keeps it in step with the
+* graph protocol. The store is the single writer; canvas gestures are
+* translated back into store calls, and store changes — from an executor
+* or the host app — are replayed onto the canvas. Every store operation
+* is idempotent, which is what lets those two event streams cross
+* without loops. */
+function createWorkflowCanvas(container, source, options = {}) {
+	live.get(container)?.destroy();
+	injectComponentStyle("workflow");
+	const store = "getGraph" in source ? source : createWorkflowStore(source);
+	const cleanups = /* @__PURE__ */ new Map();
+	const sideGroup = (position, dir) => ({
+		position,
+		markup: [{
+			tagName: "rect",
+			selector: "handle"
+		}],
+		attrs: { handle: {
+			magnet: true,
+			x: -6,
+			y: -6,
+			width: HANDLE,
+			height: HANDLE,
+			"data-part": "handle",
+			"data-dir": dir
+		} }
+	});
+	const portGroups = {
+		in: sideGroup("top", "in"),
+		"in-alt": sideGroup("left", "in"),
+		out: sideGroup("bottom", "out"),
+		"out-alt": sideGroup("right", "out")
+	};
+	const edgeAttrs = { line: {
+		class: "workflow-edge-line",
+		targetMarker: {
+			name: "classic",
+			size: 6,
+			fill: "context-stroke"
+		}
+	} };
+	const toNodeConfig = (node) => ({
+		id: node.id,
+		shape: SHAPE_NAME,
+		x: node.position.x,
+		y: node.position.y,
+		data: {
+			...node.data,
+			workflowType: node.type,
+			workflowState: node.state ?? "idle"
+		},
+		ports: {
+			groups: portGroups,
+			items: (() => {
+				let ins = 0;
+				let outs = 0;
+				return node.ports.map((p) => ({
+					id: p.id,
+					group: p.dir === "in" ? ins++ % 2 === 0 ? "in" : "in-alt" : outs++ % 2 === 0 ? "out" : "out-alt"
+				}));
+			})()
+		}
+	});
+	const toEdgeConfig = (edge) => ({
+		id: edge.id,
+		source: {
+			cell: edge.source.node,
+			port: edge.source.port
+		},
+		target: {
+			cell: edge.target.node,
+			port: edge.target.port
+		},
+		attrs: { line: {
+			...edgeAttrs.line,
+			...edge.state ? { "data-state": edge.state } : {}
+		} }
+	});
+	const graph = new Graph({
+		container,
+		grid: false,
+		connecting: {
+			connector: "smooth",
+			allowBlank: false,
+			allowLoop: false,
+			allowNode: false,
+			allowMulti: "withPort",
+			validateConnection({ sourceCell, sourcePort, targetCell, targetPort }) {
+				if (!sourceCell || !targetCell || !sourcePort || !targetPort) return false;
+				const dirOf = (cellId, portId) => store.getNode(cellId)?.ports.find((p) => p.id === portId)?.dir;
+				return dirOf(sourceCell.id, sourcePort) === "out" && dirOf(targetCell.id, targetPort) === "in";
+			},
+			createEdge: () => graph.createEdge({ attrs: edgeAttrs })
+		},
+		mousewheel: {
+			enabled: true,
+			factor: 1.1,
+			minScale: .25,
+			maxScale: 4,
+			zoomAtMousePosition: true
+		},
+		panning: { enabled: true }
+	});
+	canvasContexts.set(graph, {
+		store,
+		cleanups,
+		renderNode: options.renderNode
+	});
+	container.dataset.scope = "workflow";
+	container.dataset.part = "canvas";
+	container.style.setProperty("--bs-workflow-handle", `${HANDLE}px`);
+	graph.use(new Selection({
+		enabled: true,
+		rubberband: true,
+		modifiers: ["shift"],
+		multiple: true
+	}));
+	graph.use(new History({
+		enabled: true,
+		beforeAddCommand: (event, args) => {
+			if (event !== "cell:change:*") return true;
+			const key = args.key;
+			return key !== "data" && key !== "attrs";
+		}
+	}));
+	const keyboard = new Keyboard({ enabled: true });
+	graph.use(keyboard);
+	keyboard.bindKey(["ctrl+z", "meta+z"], () => graph.undo());
+	keyboard.bindKey(["ctrl+shift+z", "meta+shift+z"], () => graph.redo());
+	keyboard.bindKey(["delete", "backspace"], () => {
+		graph.removeCells(graph.getSelectedCells());
+	});
+	if (options.minimap) {
+		options.minimap.container.dataset.scope = "workflow";
+		options.minimap.container.dataset.part = "minimap";
+		graph.use(new MiniMap({
+			container: options.minimap.container,
+			width: 200,
+			height: 140,
+			padding: 8
+		}));
+	}
+	options.onReady?.(graph);
+	const followHost = () => graph.resize(container.clientWidth, container.clientHeight);
+	followHost();
+	const hostResize = new ResizeObserver(followHost);
+	hostResize.observe(container);
+	for (const node of store.getGraph().nodes) graph.addNode(toNodeConfig(node));
+	for (const edge of store.getGraph().edges) graph.addEdge(toEdgeConfig(edge));
+	let replaying = false;
+	const guard = (fn) => {
+		if (replaying) return;
+		store.asSource("canvas", fn);
+	};
+	graph.on("node:moved", ({ node }) => guard(() => store.moveNode(node.id, node.getPosition())));
+	graph.on("node:change:position", ({ node, options }) => {
+		if (options?.ui) return;
+		guard(() => store.moveNode(node.id, node.getPosition()));
+	});
+	graph.on("node:removed", ({ node }) => {
+		cleanups.get(node.id)?.();
+		cleanups.delete(node.id);
+		guard(() => store.removeNode(node.id));
+	});
+	graph.on("node:added", ({ node }) => guard(() => {
+		const { workflowType, workflowState, ...rest } = node.getData() ?? {};
+		store.addNode({
+			id: node.id,
+			type: workflowType ?? "unknown",
+			position: node.getPosition(),
+			ports: node.getPorts().map((p) => ({
+				id: p.id ?? "",
+				dir: String(p.group ?? "").startsWith("out") ? "out" : "in"
+			})),
+			state: workflowState,
+			data: rest
+		});
+	}));
+	graph.on("edge:connected", ({ edge, isNew }) => {
+		if (!isNew) return;
+		guard(() => {
+			store.connect({
+				id: edge.id,
+				source: {
+					node: edge.getSourceCellId(),
+					port: edge.getSourcePortId() ?? ""
+				},
+				target: {
+					node: edge.getTargetCellId(),
+					port: edge.getTargetPortId() ?? ""
+				}
+			});
+		});
+	});
+	graph.on("edge:removed", ({ edge }) => guard(() => store.disconnect(edge.id)));
+	graph.on("edge:added", ({ edge }) => guard(() => {
+		const sourceNode = edge.getSourceCellId();
+		const targetNode = edge.getTargetCellId();
+		const sourcePort = edge.getSourcePortId();
+		const targetPort = edge.getTargetPortId();
+		if (!sourceNode || !targetNode || !sourcePort || !targetPort) return;
+		store.connect({
+			id: edge.id,
+			source: {
+				node: sourceNode,
+				port: sourcePort
+			},
+			target: {
+				node: targetNode,
+				port: targetPort
+			}
+		});
+	}));
+	const apply = (change) => {
+		replaying = true;
+		try {
+			switch (change.kind) {
+				case "node:add":
+					graph.addNode(toNodeConfig(change.node));
+					break;
+				case "node:remove":
+					graph.removeCell(change.id);
+					break;
+				case "node:move": {
+					const cell = graph.getCellById(change.id);
+					if (cell?.isNode()) cell.position(change.position.x, change.position.y);
+					break;
+				}
+				case "node:state":
+					graph.getCellById(change.id)?.setData({ workflowState: change.state });
+					break;
+				case "node:data":
+					graph.getCellById(change.id)?.setData({ ...change.patch });
+					break;
+				case "edge:connect":
+					graph.addEdge(toEdgeConfig(change.edge));
+					break;
+				case "edge:state":
+					graph.getCellById(change.id)?.attr("line/data-state", change.state);
+					break;
+				case "edge:remove": graph.removeCell(change.id);
+			}
+		} finally {
+			replaying = false;
+		}
+	};
+	const unsubscribe = store.subscribe((change, source) => {
+		if (source === "canvas") return;
+		apply(change);
+	});
+	let elkLoader;
+	let layoutRun = Promise.resolve();
+	const inferDirection = () => {
+		const sideOf = (nodeId, portId, dir) => {
+			const node = store.getNode(nodeId);
+			if (!node) return dir === "in" ? "top" : "bottom";
+			let ordinal = -1;
+			let found = -1;
+			for (const port of node.ports) {
+				if (port.dir !== dir) continue;
+				ordinal++;
+				if (port.id === portId) {
+					found = ordinal;
+					break;
+				}
+			}
+			if (found < 0) return dir === "in" ? "top" : "bottom";
+			const first = found % 2 === 0;
+			if (dir === "in") return first ? "top" : "left";
+			return first ? "bottom" : "right";
+		};
+		let horizontal = 0;
+		let vertical = 0;
+		for (const edge of store.getGraph().edges) {
+			const out = sideOf(edge.source.node, edge.source.port, "out");
+			const into = sideOf(edge.target.node, edge.target.port, "in");
+			if (out === "right" || into === "left") horizontal++;
+			else vertical++;
+		}
+		return horizontal > vertical ? "LR" : "TB";
+	};
+	const doLayout = async (options) => {
+		const direction = options?.direction ?? inferDirection();
+		const rankSep = options?.rankSep ?? 80;
+		const nodeSep = options?.nodeSep ?? 40;
+		elkLoader ??= import("elkjs").then(({ default: ELK }) => new ELK());
+		const elk = await elkLoader;
+		const { nodes, edges } = store.getGraph();
+		const result = await elk.layout({
+			id: "workflow",
+			layoutOptions: {
+				"elk.algorithm": "layered",
+				"elk.direction": {
+					TB: "DOWN",
+					LR: "RIGHT",
+					BT: "UP",
+					RL: "LEFT"
+				}[direction],
+				"elk.spacing.nodeNode": String(nodeSep),
+				"elk.layered.spacing.nodeNodeBetweenLayers": String(rankSep)
+			},
+			children: nodes.map((node) => ({
+				id: node.id,
+				width: NODE_WIDTH,
+				height: NODE_HEIGHT
+			})),
+			edges: edges.map((edge) => ({
+				id: edge.id,
+				sources: [edge.source.node],
+				targets: [edge.target.node]
+			}))
+		});
+		if (destroyed) return;
+		graph.startBatch("workflow-layout");
+		try {
+			for (const child of result.children ?? []) {
+				if (child.x == null || child.y == null) continue;
+				store.moveNode(child.id, {
+					x: child.x,
+					y: child.y
+				});
+			}
+		} finally {
+			graph.stopBatch("workflow-layout");
+		}
+	};
+	const layout = (options) => {
+		const run = layoutRun.catch(() => {}).then(() => doLayout(options));
+		layoutRun = run;
+		return run;
+	};
+	let destroyed = false;
+	const canvas = {
+		store,
+		graph,
+		zoomBy(factor) {
+			graph.zoomTo(graph.zoom() * factor);
+		},
+		fitView(options) {
+			graph.zoomToFit({
+				padding: 24,
+				maxScale: 1,
+				...options
+			});
+		},
+		layout,
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			live.delete(container);
+			replaying = true;
+			unsubscribe();
+			hostResize.disconnect();
+			graph.dispose();
+			for (const child of Array.from(container.children)) if (child.classList.value.startsWith("x6-")) child.remove();
+			canvasContexts.delete(graph);
+			for (const dispose of cleanups.values()) dispose();
+			cleanups.clear();
+		}
+	};
+	live.set(container, canvas);
+	return canvas;
+}
+//#endregion
+export { WORKFLOW_GRAPH_VERSION, createWorkflowCanvas, createWorkflowStore, deserializeWorkflowGraph, serializeWorkflowGraph };

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@bysages/workflow",
+  "version": "0.1.0",
+  "description": "AI-ready workflow graphs for By Sages Elements — a headless graph protocol dressed in the paper-and-ink system, rendered by a swappable canvas engine",
+  "keywords": [
+    "ai",
+    "design-system",
+    "design-tokens",
+    "diagram",
+    "flowchart",
+    "graph",
+    "theming",
+    "ui",
+    "workflow"
+  ],
+  "homepage": "https://github.com/bysages/elements#readme",
+  "bugs": {
+    "url": "https://github.com/bysages/elements/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "By Sages",
+    "email": "contact@bysages.com",
+    "url": "https://www.bysages.com/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bysages/elements"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "@antv/x6": "3.1.8",
+    "elkjs": "0.12.0",
+    "@bysages/core": "0.1.2"
+  },
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "vue": "3.5.42",
+    "@bysages/vue": "0.1.1",
+    "@bysages/react": "0.1.1"
+  },
+  "scripts": {
+    "dev": "basis build --stub",
+    "build": "vp pack",
+    "release": "basis publish"
+  }
+}