@bpmn-nova/studio 0.3.0-preview → 0.3.2-preview

package/README.md

@@ -1,26 +1,41 @@
 # @bpmn-nova/studio
 
-BPMN Nova 的推荐聚合入口，组合流程设计器、只读 Viewer、审批轨迹、Palette、Properties 和主题。
+BPMN Nova 的 Vanilla JavaScript / TypeScript 完整入口，提供流程设计、只读展示、审批轨迹、主题、属性面板和纯 SVG 导出。
 
-> **English summary:** The recommended aggregate package for BPMN Nova Designer, Viewer, runtime visualization, Palette and Properties.
+> **English summary:** The complete framework-neutral BPMN Nova package for process design, viewing, approval traces, themes, properties, and pure SVG export.
 
-> 当前版本为 `0.3.0-preview`。API 与 BPMN round-trip 能力仍在稳定中，请固定 Preview 版本或使用 `preview` dist-tag。
+> 当前版本为 `0.3.2-preview`。请使用 `@preview` 安装，并在生产接入前验证目标 BPMN XML 与引擎扩展。
+
+![BPMN Nova 流程设计器](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-designer.jpg)
+
+## 什么时候使用
+
+- Vanilla JavaScript 或 TypeScript 项目安装本包。
+- React 18+ 项目安装 `@bpmn-nova/react`。
+- Vue 3.3+ 项目安装 `@bpmn-nova/vue`。
+- 一个项目只需要选择一个公开包，不需要安装 Core、Viewer、Runtime、Theme 等内部 Module。
 
 ## 安装
 
 ```bash
-npm install @bpmn-nova/studio
+npm install @bpmn-nova/studio@preview
 ```
 
 ```js
 import '@bpmn-nova/studio/styles.css'
 ```
 
-JavaScript 不会隐式注入 CSS；只导入当前视觉包的样式入口。
+BPMN Nova 不会在 JavaScript 中隐式注入 CSS。视觉容器必须有明确高度。
+
+使用代码生成助手或 IDE Agent 接入时，从随包的 `llms.txt` 开始；需要完整接口和定制资料时再读取 `llms-full.txt`。两份文件都包含在 npm tarball 中，不依赖源码仓库可见性。
 
-## 最小用法
+## 流程设计
 
-```jsx
+```html
+<div id="studio" style="height: 720px"></div>
+```
+
+```js
 import {
   createEmptyProcess,
   createStudioController,
@@ -29,31 +44,241 @@ import {
 import '@bpmn-nova/studio/styles.css'
 
 const model = createEmptyProcess('flowable')
-const studio = createStudioController({ model })
-const shell = createStudioShell({ container, studio, theme: 'auto' })
+model.id = 'Process_PurchaseApproval'
+model.name = '采购申请审批流程'
+
+const studio = createStudioController({
+  model,
+  allowedNodeTypes: ['startEvent', 'userTask', 'exclusiveGateway', 'endEvent'],
+  allowedEdgeTypes: ['sequenceFlow'],
+})
+const shell = createStudioShell({
+  container: document.querySelector('#studio'),
+  studio,
+  mode: 'design',
+  allowedModes: ['design'],
+  theme: 'auto',
+})
 
 const xml = studio.exportXml()
+
+// 页面卸载时释放实例。
 shell.destroy()
 studio.destroy()
 ```
 
-## 主要接口
+`allowedNodeTypes` 与 `allowedEdgeTypes` 同时约束 XML 导入、Palette、连接、快捷新增、模板和节点类型转换；不传时开放 Nova 当前支持的全部图元。`allowedModes` 控制默认工作台显示和允许切换的模式。不传 Runtime 时实例模式保持空运行事实，不会注入演示审批数据。
+
+## 嵌入宿主工作台
+
+默认 `BpmnStudioShell` 仍是包含 Header、Palette、Canvas、Properties 和 Statusbar 的完整工作台。宿主要复用自己的业务属性面板时，应显式隐藏 Nova 右侧区域，并把业务面板作为 Nova 根节点的外部兄弟区域：
+
+```js
+const shell = createStudioShell({
+  container: novaHost,
+  studio,
+  mode: 'design',
+  allowedModes: ['design'],
+  regions: { right: 'hidden' },
+  slots: {
+    headerStart({ container, actions, getState, subscribe }) {
+      // 在 Nova Header 左侧挂载宿主的返回入口、业务图标、流程名称和类型。
+      // 完整替换 Header 时改用 slots.header，并继续调用 actions。
+    },
+  },
+  theme: 'auto',
+})
+
+shell.setRegions({ right: 'default' })
+shell.actions.undo()
+shell.actions.redo()
+shell.actions.fitView()
+const issues = shell.actions.validate()
+const xml = shell.actions.exportXml('flowable')
+```
 
-- `createStudioController / BpmnStudioController`
-- `createStudioShell / BpmnStudioShell`
-- `BpmnCanvas 与 InteractionController`
-- `ContextMenu、Template、Palette、Properties Registries`
-- `Studio 聚合导出的 Core、XML、Runtime、Theme、Designer 与 Viewer API`
+`regions` 支持 `header`、`left`、`right`、`footer` 的 `default | hidden` 状态；隐藏区域不占布局轨道。`setRegions()` 原地更新默认 Shell，不重建 Controller 或 Canvas。`layout()` 是完整布局替换，不能与 `regions` 同时使用。
 
-参数、默认值、事件和实例方法以随包发布的 TypeScript 声明为准。
+`shell.actions` 只封装撤销、重做、布局、视图、校验和 BPMN/SVG 导入导出。宿主的保存草稿、发布、权限、文件选择和服务端事务不属于 Nova Actions。
+
+## 只读 Viewer
+
+```js
+import { importBpmn } from '@bpmn-nova/studio'
+import { BpmnViewer } from '@bpmn-nova/studio/viewer'
+import '@bpmn-nova/studio/styles.css'
+
+const viewer = new BpmnViewer({
+  container: document.querySelector('#viewer'),
+  model: importBpmn(xml, 'flowable'),
+  projection: 'standard',
+  theme: 'auto',
+})
+
+viewer.fitView()
+viewer.destroy()
+```
+
+也可以从 `@bpmn-nova/studio` 根入口导入所有公开 Interface；子路径用于明确表达接入场景。
+
+![BPMN Nova 只读流程展示](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-viewer.jpg)
+
+## 审批轨迹
+
+Viewer 接收引擎中立的 Runtime Snapshot。三种投影使用相同数据：
+
+| 投影 | 配置 | 适用场景 |
+| --- | --- | --- |
+| 实际路径 | `projection: 'approval'` | 只展示实际发生的有效路径 |
+| 移动时间线 | `projection: 'compact'` | 按访问轮次展示动作、图片和附件 |
+| 完整 BPMN | `projection: 'standard'` + `runtime` | 完整结构叠加运行状态 |
+
+```js
+const runtime = {
+  processInstanceId: 'purchase-20260824',
+  status: 'running',
+  activities: [{
+    id: 'activity-manager-1',
+    elementId: 'UserTask_Manager',
+    visitId: 'visit-manager-1',
+    status: 'completed',
+    assignee: '李经理',
+    endTime: '2026-08-24T10:12:00+08:00',
+  }],
+  actions: [{
+    id: 'action-manager-approve',
+    type: 'approve',
+    elementId: 'UserTask_Manager',
+    visitId: 'visit-manager-1',
+    activityId: 'activity-manager-1',
+    actor: { id: 'manager-li', name: '李经理' },
+    occurredAt: '2026-08-24T10:12:00+08:00',
+    content: {
+      plainText: '资料完整，同意提交总经理审批。',
+      blocks: [
+        { type: 'paragraph', text: '资料完整，同意提交总经理审批。' },
+        { type: 'image', assetId: 'quotation-preview' },
+        { type: 'file', assetId: 'purchase-checklist' },
+      ],
+      assets: [
+        {
+          id: 'quotation-preview',
+          name: '现场报价单.png',
+          mediaType: 'image/png',
+          width: 1280,
+          height: 720,
+        },
+        {
+          id: 'purchase-checklist',
+          name: '采购核验清单.txt',
+          mediaType: 'text/plain',
+          size: 248,
+        },
+      ],
+    },
+  }],
+  visitedEdges: [],
+}
 
-## 文档
+const runtimeAssetResolver = async (asset, { purpose, signal }) => {
+  const response = await fetch(
+    `/api/runtime-assets/${encodeURIComponent(asset.id)}?purpose=${purpose}`,
+    { signal },
+  )
+  if (!response.ok) return null
+  return response.url
+}
 
+viewer.setRuntime(runtime)
+viewer.setProjection('compact')
+viewer.setDisplayOptions({ runtimeAssetResolver })
+```
+
+Snapshot 只保存资源引用，不保存 URL、Base64、Blob 或 HTML。上传、权限签发和资源存储由宿主业务系统负责。
+
+| 实际路径 | 移动时间线 |
+| --- | --- |
+| ![审批实际路径](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-approval-effective-path.jpg) | ![移动审批时间线](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-approval-mobile-timeline.jpg) |
+
+![完整 BPMN 审批轨迹](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-approval-full-bpmn.jpg)
+
+## 主题与运行态配色
+
+```js
+shell.setTheme({
+  mode: 'auto',
+  dark: {
+    colors: {
+      canvas: '#0b1018',
+      surface: '#18202b',
+    },
+  },
+})
+
+shell.setRuntimeAppearance({
+  statuses: { completed: 'success', active: 'primary' },
+  actions: {
+    approve: { label: '通过', tone: 'success' },
+    reject: { label: '驳回', tone: 'danger' },
+  },
+})
+```
+
+主题限定在实例根节点；`auto` 会跟随并监听浏览器系统主题变化，不修改宿主页面的 `<html>`。
+
+![BPMN Nova 深色运行态](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-dark-runtime.jpg)
+
+## SVG 导出
+
+```js
+// 打开确认预览，用户确认后下载。
+shell.openSvgExportPreview({
+  theme: 'current',
+  transparentBackground: false,
+  filename: '采购申请审批流程.svg',
+})
+
+// 或只创建 Artifact，不触发下载。
+const artifact = await shell.exportSvg({ theme: 'dark' })
+console.log(artifact.svg, artifact.warnings)
+```
+
+导出完整业务内容，不受当前缩放、平移或滚动影响。图片会通过 Resolver 嵌入 SVG，普通附件只展示摘要。
+
+![SVG 导出确认预览](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-svg-export-preview.jpg)
+
+## 支持的子路径
+
+```js
+import { BpmnDesigner } from '@bpmn-nova/studio/designer'
+import { BpmnViewer } from '@bpmn-nova/studio/viewer'
+import { createRuntimePresentation } from '@bpmn-nova/studio/runtime'
+import { createThemeController } from '@bpmn-nova/studio/theme'
+import { exportDiagramSvg } from '@bpmn-nova/studio/export-svg'
+import { flowableProfile } from '@bpmn-nova/studio/flowable'
+import { activitiProfile } from '@bpmn-nova/studio/activiti'
+```
+
+## 常见问题
+
+- **界面为空或高度为 0：** 为 Studio/Viewer 的父容器设置明确高度。
+- **界面没有样式：** 导入一次 `@bpmn-nova/studio/styles.css`。
+- **附件不可用：** 提供 `runtimeAssetResolver`，并为不同 purpose 返回当前有效地址。
+- **SSR 报错：** 在浏览器挂载阶段创建实例，服务端只准备 XML 和 Runtime 数据。
+- **重复安装：** 不直接安装任何未列出的 `@bpmn-nova/*` 内部 Module。
+
+## 文档与 AI
+
+- npm 包内 `llms.txt`：可执行安装入口
+- npm 包内 `llms-full.txt`：完整 AI 上下文
+- [项目首页](https://github.com/daxiangme/bpmn-nova)
 - [快速开始](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/GETTING-STARTED.md)
-- [组件参数](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/COMPONENTS.md)
-- [API](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/API.md)
+- [公开 Interface](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/API.md)
 - [自定义指南](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/CUSTOMIZATION.md)
-- [Properties Panel](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/PROPERTIES-PANEL.md)
+
+## 能力边界
+
+BPMN Nova 负责建模、展示、审批轨迹、主题和 SVG 导出；不负责流程引擎执行、审批提交、附件上传存储、权限签发或 PNG/PDF 导出。当前 Preview 不声明 BPMN Schema 100% 覆盖。
 
 ## License
 

package/dist/canvas.js

@@ -8,9 +8,9 @@ import {
   NODE_DEFINITIONS,
   resolveContainment,
   snapNodePosition,
-} from '@bpmn-nova/core';
-import { DiagramRenderer } from '@bpmn-nova/renderer';
-import { hydrateIcons } from '@bpmn-nova/icons';
+} from './modules/core/index.js';
+import { DiagramRenderer } from './modules/renderer-svg/index.js';
+import { hydrateIcons } from './modules/icons/index.js';
 import { canCreateSequenceFlow } from './controller.js';
 import { createDefaultContextMenuRegistry } from './context-menu.js';
 import { CREATE_INTENT_MIME } from './interactions.js';
@@ -80,6 +80,7 @@ export class BpmnCanvas {
       },
       onStartConnect: (node) => studio.startConnect(node.id),
       canConnect: (source, target) => canCreateSequenceFlow(studio.model, source.id, target.id),
+      canCreateNodeType: (nodeType) => studio.allowsNodeType(nodeType),
       onQuickAdd: (source, type, preset) => studio.commands.quickAdd(source.id, type, preset),
       onDeleteNode: (node) => studio.commands.remove({ kind: 'node', id: node.id }),
       onUngroup: (node) => studio.commands.ungroup(node.id),
@@ -521,7 +522,7 @@ export class BpmnCanvas {
       { id: 'distribute-vertical', iconId: 'ui.distributeVertical', title: '垂直等距', action: () => actions.distribute('vertical'), disabled: nodes.length < 3 },
     ];
     this._selectionToolbar.append(
-      button('group', 'ui.layoutSelection', '创建分组', actions.group, { label: '创建分组', disabled: !groupableNodes.length || groupableNodes.length !== diagramNodes.length }),
+      button('group', 'ui.layoutSelection', '创建分组', actions.group, { label: '创建分组', disabled: this.studio.allowsNodeType?.('group') === false || !groupableNodes.length || groupableNodes.length !== diagramNodes.length }),
       separator(),
       menu('align', 'ui.alignCenterHorizontal', '对齐选区', alignmentItems, nodes.length < 2),
       menu('distribute', 'ui.distributeHorizontal', '等距分布', distributeItems, nodes.length < 3),
@@ -904,6 +905,8 @@ export class BpmnCanvas {
   startConnect(nodeId) { this.renderer.closeTransientOverlays?.(); return this.studio.startConnect(nodeId); }
   editEdgeName(edgeId) { return this.renderer.editEdgeName?.(edgeId) || false; }
   fitView(padding, options) { this.renderer.fitView(padding, { minZoom: 0.7, ...(options || {}) }); }
+  exportSvg(options) { return this.renderer.exportSvg(options); }
+  openSvgExportPreview(options) { return this.renderer.openSvgExportPreview(options); }
   fitSelection(padding = 72) {
     const bounds = this.studio.getSelectionBounds();
     if (!bounds) return false;

package/dist/context-menu.js

@@ -3,7 +3,7 @@ import {
   getEdge,
   getNode,
   isEmbeddedSubProcess,
-} from '@bpmn-nova/core';
+} from './modules/core/index.js';
 import { selectedDiagramNodes, selectedGroupableNodes, selectedLayoutNodes } from './selection-layout.js';
 
 function insert(actions, action) {
@@ -104,7 +104,7 @@ function multiActions(context) {
     execute: ({ studio }) => studio.arrangeSelection({ type: 'align', alignment }),
   }));
   actions.push(
-    action({ id: 'selection.group', label: '创建分组', iconId: 'ui.layoutSelection', group: 'layout', disabled: !groupableNodes.length || groupableNodes.length !== diagramNodes.length, execute: ({ studio }) => studio.commands.groupSelection() }),
+    action({ id: 'selection.group', label: '创建分组', iconId: 'ui.layoutSelection', group: 'layout', disabled: context.studio.allowsNodeType?.('group') === false || !groupableNodes.length || groupableNodes.length !== diagramNodes.length, execute: ({ studio }) => studio.commands.groupSelection() }),
     action({ id: 'selection.distribute.horizontal', label: '水平等距', iconId: 'ui.distributeHorizontal', group: 'distribute', disabled: nodes.length < 3, execute: ({ studio }) => studio.arrangeSelection({ type: 'distribute', axis: 'horizontal' }) }),
     action({ id: 'selection.distribute.vertical', label: '垂直等距', iconId: 'ui.distributeVertical', group: 'distribute', disabled: nodes.length < 3, execute: ({ studio }) => studio.arrangeSelection({ type: 'distribute', axis: 'vertical' }) }),
     action({ id: 'selection.layout', label: '美化选区', iconId: 'ui.layoutSelection', group: 'layout', disabled: nodes.length < 2, execute: ({ studio }) => studio.arrangeSelection({ type: 'layout' }) }),

package/dist/controller.js

@@ -1,6 +1,7 @@
 import {
   applyContainmentOperation,
   CONTAINMENT_LIMITS,
+  EDGE_DEFINITIONS,
   HistoryStack,
   LAYOUT_DENSITIES,
   NODE_DEFINITIONS,
@@ -24,8 +25,8 @@ import {
   resolveSwimlaneLabelPlacement,
   scopeExists,
   validateParallelGateway,
-} from '@bpmn-nova/core';
-import { exportBpmn, importBpmn } from '@bpmn-nova/bpmn-model';
+} from './modules/core/index.js';
+import { exportBpmn, importBpmn } from './modules/bpmn-model/index.js';
 import {
   applySelectionArrangement,
   mergeSelectionRefs,
@@ -58,9 +59,38 @@ function mergeNodePreset(preset = {}) {
   };
 }
 
+function normalizeAllowedNodeTypes(allowedNodeTypes) {
+  if (allowedNodeTypes === undefined || allowedNodeTypes === null) return null;
+  if (typeof allowedNodeTypes === 'string' || typeof allowedNodeTypes[Symbol.iterator] !== 'function') {
+    throw new Error('allowedNodeTypes must be an iterable of BPMN node types.');
+  }
+  const normalized = new Set(allowedNodeTypes);
+  for (const nodeType of normalized) {
+    if (!NODE_DEFINITIONS[nodeType] || nodeType === 'generic') {
+      throw new Error(`Unknown allowed BPMN node type: ${nodeType}`);
+    }
+  }
+  return normalized;
+}
+
+function normalizeAllowedEdgeTypes(allowedEdgeTypes) {
+  if (allowedEdgeTypes === undefined || allowedEdgeTypes === null) return null;
+  if (typeof allowedEdgeTypes === 'string' || typeof allowedEdgeTypes[Symbol.iterator] !== 'function') {
+    throw new Error('allowedEdgeTypes must be an iterable of BPMN edge types.');
+  }
+  const normalized = new Set(allowedEdgeTypes);
+  for (const edgeType of normalized) {
+    if (!EDGE_DEFINITIONS[edgeType]) throw new Error(`Unknown allowed BPMN edge type: ${edgeType}`);
+  }
+  return normalized;
+}
+
 export class BpmnStudioController {
-  constructor({ model, historyLimit = 80, extensions = [], propertiesProfile = 'business' } = {}) {
+  constructor({ model, historyLimit = 80, extensions = [], propertiesProfile = 'business', allowedNodeTypes = null, allowedEdgeTypes = null } = {}) {
     if (!model) throw new Error('BpmnStudioController requires a model.');
+    this._allowedNodeTypes = normalizeAllowedNodeTypes(allowedNodeTypes);
+    this._allowedEdgeTypes = normalizeAllowedEdgeTypes(allowedEdgeTypes);
+    this._assertAllowedModel(model);
     this._model = model;
     this.history = new HistoryStack(historyLimit);
     this.selection = { kind: 'process', id: model.id };
@@ -108,6 +138,32 @@ export class BpmnStudioController {
 
   get model() { return this._model; }
 
+  allowsNodeType(nodeType) {
+    return Boolean(NODE_DEFINITIONS[nodeType])
+      && nodeType !== 'generic'
+      && (!this._allowedNodeTypes || this._allowedNodeTypes.has(nodeType));
+  }
+
+  allowsEdgeType(edgeType) {
+    return Boolean(EDGE_DEFINITIONS[edgeType])
+      && (!this._allowedEdgeTypes || this._allowedEdgeTypes.has(edgeType));
+  }
+
+  _assertAllowedModel(model) {
+    if (this._allowedNodeTypes) {
+      const unsupportedNode = model?.nodes?.find((node) => !this._allowedNodeTypes.has(node.type));
+      if (unsupportedNode) {
+        throw new Error(`BPMN node type is not allowed: ${unsupportedNode.type} (${unsupportedNode.id})`);
+      }
+    }
+    if (this._allowedEdgeTypes) {
+      const unsupportedEdge = model?.edges?.find((edge) => !this._allowedEdgeTypes.has(edge.type || 'sequenceFlow'));
+      if (unsupportedEdge) {
+        throw new Error(`BPMN edge type is not allowed: ${unsupportedEdge.type || 'sequenceFlow'} (${unsupportedEdge.id})`);
+      }
+    }
+  }
+
   getState() {
     return {
       model: cloneModel(this._model),
@@ -118,6 +174,8 @@ export class BpmnStudioController {
       canRedo: this.history.canRedo,
       engine: this._model.engine,
       propertiesProfile: this.propertiesProfile,
+      allowedNodeTypes: this._allowedNodeTypes ? [...this._allowedNodeTypes] : null,
+      allowedEdgeTypes: this._allowedEdgeTypes ? [...this._allowedEdgeTypes] : null,
       activeScopeId: this.activeScopeId,
       scopePath: getScopePath(this._model, this.activeScopeId),
     };
@@ -143,6 +201,7 @@ export class BpmnStudioController {
   }
 
   setModel(model, { resetHistory = true } = {}) {
+    this._assertAllowedModel(model);
     const previousScopeId = this.activeScopeId;
     this._model = model;
     applyContainmentOperation(this._model, { type: 'reconcile' });
@@ -192,6 +251,7 @@ export class BpmnStudioController {
   }
 
   groupSelection() {
+    if (!this.allowsNodeType('group')) return null;
     const selected = selectedDiagramNodes(this._model, this.selection, this.activeScopeId);
     const groupable = selectedGroupableNodes(this._model, this.selection, this.activeScopeId);
     if (!groupable.length || groupable.length !== selected.length) return null;
@@ -303,6 +363,7 @@ export class BpmnStudioController {
   createNode({ nodeType, point, preset = {} } = {}) {
     const def = NODE_DEFINITIONS[nodeType];
     if (!def) throw new Error(`Unknown BPMN node type: ${nodeType}`);
+    if (!this.allowsNodeType(nodeType)) throw new Error(`BPMN node type is not allowed: ${nodeType}`);
     const position = point || { x: 100, y: 100 };
     let node;
     this._commit('create-node', () => {
@@ -331,9 +392,15 @@ export class BpmnStudioController {
     for (const spec of nodeSpecs) {
       if (!spec.key || keys.has(spec.key)) throw new Error('Template node keys must be unique.');
       if (!NODE_DEFINITIONS[spec.nodeType]) throw new Error(`Unknown BPMN node type: ${spec.nodeType}`);
+      if (!this.allowsNodeType(spec.nodeType)) throw new Error(`BPMN node type is not allowed: ${spec.nodeType}`);
       keys.add(spec.key);
     }
-    for (const edge of template.edges || []) if (!keys.has(edge.source) || !keys.has(edge.target)) throw new Error('Template edge references an unknown node key.');
+    for (const edge of template.edges || []) {
+      if (!keys.has(edge.source) || !keys.has(edge.target)) throw new Error('Template edge references an unknown node key.');
+      const edgeType = edge.preset?.type || 'sequenceFlow';
+      if (!EDGE_DEFINITIONS[edgeType]) throw new Error(`Unknown BPMN edge type: ${edgeType}`);
+      if (!this.allowsEdgeType(edgeType)) throw new Error(`BPMN edge type is not allowed: ${edgeType}`);
+    }
     const result = { nodes: [], edges: [] };
     const byKey = new Map();
     this._commit('create-template', () => {
@@ -355,6 +422,9 @@ export class BpmnStudioController {
   }
 
   connect(source, target, overrides = {}) {
+    const edgeType = overrides.type || 'sequenceFlow';
+    if (!EDGE_DEFINITIONS[edgeType]) throw new Error(`Unknown BPMN edge type: ${edgeType}`);
+    if (!this.allowsEdgeType(edgeType)) throw new Error(`BPMN edge type is not allowed: ${edgeType}`);
     if (!canCreateSequenceFlow(this._model, source, target)) return null;
     let edge;
     this._commit('connect', () => {
@@ -366,6 +436,7 @@ export class BpmnStudioController {
   }
 
   startConnect(sourceId) {
+    if (!this.allowsEdgeType('sequenceFlow')) return false;
     const source = getNode(this._model, sourceId);
     const definition = source && (NODE_DEFINITIONS[source.type] || NODE_DEFINITIONS.generic);
     if (!source || elementScopeId(this._model, source) !== this.activeScopeId || !SEQUENCE_FLOW_KINDS.has(definition.kind) || definition.eventStage === 'end') return false;
@@ -407,6 +478,9 @@ export class BpmnStudioController {
   updateNode(id, patch = {}) {
     const node = getNode(this._model, id);
     if (!node) return false;
+    if (patch.type !== undefined && patch.type !== node.type) {
+      throw new Error('Node type changes must use changeNodeType().');
+    }
     const previousLabelPlacement = resolveSwimlaneLabelPlacement(this._model, node);
     this._commit('update-node', () => {
       if (patch.properties) node.properties = { ...node.properties, ...patch.properties };
@@ -431,6 +505,9 @@ export class BpmnStudioController {
   updateEdge(id, patch = {}) {
     const edge = getEdge(this._model, id);
     if (!edge) return false;
+    if (patch.type !== undefined && patch.type !== (edge.type || 'sequenceFlow')) {
+      throw new Error('Edge type cannot be changed through updateEdge().');
+    }
     this._commit('update-edge', () => {
       if (patch.properties) edge.properties = { ...(edge.properties || {}), ...patch.properties };
       const rest = { ...patch }; delete rest.properties;
@@ -500,7 +577,7 @@ export class BpmnStudioController {
   changeNodeType(id, type) {
     const node = getNode(this._model, id);
     const def = NODE_DEFINITIONS[type];
-    if (!node || !def || node.type === type) return false;
+    if (!node || !def || !this.allowsNodeType(type) || node.type === type) return false;
     if (isEmbeddedSubProcess(node) && !isEmbeddedSubProcess(type) && hasScopeChildren(this._model, id)) return false;
     this._commit('change-node-type', () => {
       const next = createNode(type, node.x, node.y, { id: node.id, name: node.name });
@@ -514,9 +591,10 @@ export class BpmnStudioController {
   }
 
   quickAdd(sourceId, type = 'userTask', preset = {}) {
+    if (!this.allowsEdgeType('sequenceFlow')) return null;
     const source = getNode(this._model, sourceId);
     const def = NODE_DEFINITIONS[type];
-    if (!source || elementScopeId(this._model, source) !== this.activeScopeId || !def) return null;
+    if (!source || elementScopeId(this._model, source) !== this.activeScopeId || !def || !this.allowsNodeType(type)) return null;
     const direction = this._model.settings?.direction || 'horizontal';
     const spacing = LAYOUT_DENSITIES[this._model.settings?.layoutDensity || 'balanced'] || LAYOUT_DENSITIES.balanced;
     const outgoingCount = this._model.edges.filter((edge) => edge.source === sourceId).length;