English · 中文

Matra Canvas X

A workflow viewer SDK that renders workflow JSON as an interactive node graph. Supports n8n native and Agent graph formats, ships with brand SVG icons for 50+ n8n services, and exposes a GoJS-style edge template binding for runtime styling.

Quick start

<script src="dist/matra-canvas-x.min.js"></script>
<div id="viewer" style="width:100%;height:600px"></div>
<script>
  const viewer = new MatraCanvasX.MatraCanvasX('#viewer', { editable: true });
  viewer.loadJSON(workflowJSON);
  viewer.fitView();
</script>

ESM:

import { MatraCanvasX } from 'matra-canvas-x';
const viewer = new MatraCanvasX('#viewer', { editable: true });
viewer.loadJSON(json);

Supported formats

n8n format — nodes array + connections object

{ "name": "My Flow", "nodes": [...], "connections": {...} }

Agent graph format — nodes object + edges array

{ "nodes": { "id1": { "type": "start", "x": 100, "y": 200 } },
  "edges": [{ "from": "id1", "to": "id2" }] }

Format is auto-detected on import. getWorkflowJSON() exports in the original format by default; pass 'n8n' or 'agent' to force.

Features

• Nodes — multiple shapes (rect/diamond/circle), drag, status badges, custom type registration, brand SVG icons (Simple Icons + Lucide) for 50+ n8n services including Google suite, Slack, GitHub, OpenAI, etc.
• Edges — 4 bend types (bezier/step/straight/taxi/smart), smart obstacle avoidance, port-snap drag-to-connect, click-to-select, delete, reconnect, custom labels at midpoint.
• Edge styling — per-edge stroke / strokeWidth / dashArray / animation either inline in JSON via style: {…} or at runtime via setEdgeTemplate(({edge}) => style) — same data-binding pattern as GoJS.
• Animation — flow / pulse / dots, canvas-wide or per-edge.
• Endpoints — arrow / dot / diamond / tee, applied to the incoming side.
• Canvas — pan/zoom, fit-view, dotted/grid/lines/cross backgrounds (fixed or content-following), minimap.
• Editing — undo/redo, marquee multi-select, context menu, in-place rename, source-JSON editor.
• Themes — light / dark / blue presets, plus arbitrary custom palettes.
• Sticky notes — markdown subset with strict URL allow-listing (XSS-safe) + YouTube embed via @[youtube](VIDEO_ID).
• AI sub-attachments — ai_tool / ai_languageModel / ai_memory / etc. connection types always route vertically below the agent node, matching n8n's native visual.

Common API

const viewer = new MatraCanvasX('#viewer', {
  editable: false,
  theme: MatraCanvasX.DARK_THEME,
  connectionAnimation: 'flow',
  connectionEndpoint: 'arrow',
  onNodeClick: (name, node) => console.log(name),
});

viewer.loadJSON(json);
viewer.fitView();
viewer.getWorkflowJSON();           // export in source format
viewer.getWorkflowJSON('n8n');      // export in specific format
viewer.getSourceFormat();            // 'n8n' | 'agent'

// GoJS-style edge styling: read edge.data, return EdgeStyle.
viewer.setEdgeTemplate(({ edge }) => {
  switch (edge.data?.branch) {
    case 'success': return { stroke: '#10b981', strokeWidth: 3 };
    case 'error':   return { stroke: '#ef4444', dashArray: '6 4' };
    case 'warning': return { stroke: '#f59e0b' };
  }
  return null;  // fall through to theme default
});

viewer.setConnectionAnimation('pulse');
viewer.setConnectionEndpoint('dot');
viewer.setBackgroundFollowsContent(true);
viewer.registerNodeType('custom', { color: '#f59e0b', icon: '⚡', label: 'Custom', svgIcon: 'si/slack' });
viewer.setNodeStatus('node1', 'completed');

Build

npm install
npm run build
# outputs: dist/matra-canvas-x.min.js (UMD) + dist/matra-canvas-x.esm.js (ESM)
npm test   # 50 unit + DOM tests

About 21 KB gzipped.

License

MIT. See THIRD_PARTY_NOTICES.md for the icon-pack licenses (Simple Icons CC0-1.0, Lucide ISC).

English · 中文

Matra Canvas X（中文）

工作流视图 SDK，将工作流 JSON 渲染为可交互的节点图。原生支持 n8n 与 Agent 图两种格式，内置 50+ n8n 服务品牌 SVG 图标，提供 GoJS 风格的边模板绑定用于运行时样式派发。

快速开始

<script src="dist/matra-canvas-x.min.js"></script>
<div id="viewer" style="width:100%;height:600px"></div>
<script>
  const viewer = new MatraCanvasX.MatraCanvasX('#viewer', { editable: true });
  viewer.loadJSON(workflowJSON);
  viewer.fitView();
</script>

ESM：

import { MatraCanvasX } from 'matra-canvas-x';
const viewer = new MatraCanvasX('#viewer', { editable: true });
viewer.loadJSON(json);

支持的格式

n8n 格式 — nodes 数组 + connections 对象

{ "name": "My Flow", "nodes": [...], "connections": {...} }

Agent 图格式 — nodes 对象 + edges 数组

{ "nodes": { "id1": { "type": "start", "x": 100, "y": 200 } },
  "edges": [{ "from": "id1", "to": "id2" }] }

导入时自动识别格式。getWorkflowJSON() 默认按原格式导出，传 'n8n' / 'agent' 强制目标格式。

主要功能

• 节点 — 多形状（rect/diamond/circle）、拖拽移动、状态角标、自定义类型注册；内置 50+ n8n 服务的品牌 SVG 图标（Simple Icons + Lucide），涵盖 Google 全家桶、Slack、GitHub、OpenAI 等。
• 连线 — 4 种弯曲类型（bezier/step/straight/taxi/smart）、智能避障、端口磁性吸附拖出新线、点选 / 删除 / 重连、中点自定义文本。
• 边自定义样式 — 每条边的 stroke / strokeWidth / dashArray / animation 既可写在 JSON 的 style: {…} 里，也可运行时通过 setEdgeTemplate(({edge}) => style) 函数派发 —— 跟 GoJS 的 data-binding 同范式。
• 动画 — flow / pulse / dots 三种，画布级或单边级。
• 端点 — arrow / dot / diamond / tee，作用在入边一侧。
• 画布 — 平移缩放、FitView、4 种背景纹理（固定 / 跟随内容）、Minimap。
• 编辑 — 撤销 / 重做、框选多节点、右键菜单、原位重命名、源码 JSON 编辑器。
• 主题 — 亮色 / 暗色 / 蓝色 + 任意自定义调色板。
• 便签 — 安全的 Markdown 子集（URL scheme 白名单防 XSS）+ @[youtube](VIDEO_ID) 内嵌 YouTube 视频。
• AI 子挂载 — ai_tool / ai_languageModel / ai_memory 等连接类型强制走垂直扇入，匹配 n8n 原生的"工具在 Agent 下方"视觉。

常用 API

const viewer = new MatraCanvasX('#viewer', {
  editable: false,
  theme: MatraCanvasX.DARK_THEME,
  connectionAnimation: 'flow',
  connectionEndpoint: 'arrow',
  onNodeClick: (name, node) => console.log(name),
});

viewer.loadJSON(json);
viewer.fitView();
viewer.getWorkflowJSON();           // 按原格式导出
viewer.getWorkflowJSON('n8n');      // 强制目标格式
viewer.getSourceFormat();            // 'n8n' | 'agent'

// GoJS 风格的边样式模板：读 edge.data，返回 EdgeStyle。
viewer.setEdgeTemplate(({ edge }) => {
  switch (edge.data?.branch) {
    case 'success': return { stroke: '#10b981', strokeWidth: 3 };
    case 'error':   return { stroke: '#ef4444', dashArray: '6 4' };
    case 'warning': return { stroke: '#f59e0b' };
  }
  return null;  // 回落到主题默认
});

viewer.setConnectionAnimation('pulse');
viewer.setConnectionEndpoint('dot');
viewer.setBackgroundFollowsContent(true);
viewer.registerNodeType('custom', { color: '#f59e0b', icon: '⚡', label: 'Custom', svgIcon: 'si/slack' });
viewer.setNodeStatus('node1', 'completed');

构建

npm install
npm run build
# 输出：dist/matra-canvas-x.min.js (UMD) + dist/matra-canvas-x.esm.js (ESM)
npm test   # 50 个单元 + DOM 测试

gzip 后约 21 KB。

协议

MIT。图标来源协议见 THIRD_PARTY_NOTICES.md（Simple Icons CC0-1.0、Lucide ISC）。