@bpmn-nova/studio 0.3.0-preview

package/dist/controller.js

@@ -0,0 +1,677 @@
+import {
+  applyContainmentOperation,
+  CONTAINMENT_LIMITS,
+  HistoryStack,
+  LAYOUT_DENSITIES,
+  NODE_DEFINITIONS,
+  autoLayout,
+  beautify,
+  clearConnectedWaypoints,
+  cloneModel,
+  createEdge,
+  createNode,
+  elementScopeId,
+  getEdge,
+  getDescendantScopeIds,
+  getNode,
+  getParentScopeId,
+  getScopeGraph,
+  getScopeIntegrityIssues,
+  getScopePath,
+  hasScopeChildren,
+  isEmbeddedSubProcess,
+  resolveContainment,
+  resolveSwimlaneLabelPlacement,
+  scopeExists,
+  validateParallelGateway,
+} from '@bpmn-nova/core';
+import { exportBpmn, importBpmn } from '@bpmn-nova/bpmn-model';
+import {
+  applySelectionArrangement,
+  mergeSelectionRefs,
+  nodesInSelectionRect,
+  selectedDiagramNodes,
+  selectedGroupableNodes,
+  selectedLayoutNodes,
+  selectionBounds,
+} from './selection-layout.js';
+
+const SEQUENCE_FLOW_KINDS = new Set(['event', 'boundary', 'task', 'container', 'gateway']);
+
+export function canCreateSequenceFlow(model, sourceId, targetId) {
+  if (!model || !sourceId || !targetId || sourceId === targetId) return false;
+  const source = getNode(model, sourceId);
+  const target = getNode(model, targetId);
+  if (!source || !target) return false;
+  if (elementScopeId(model, source) !== elementScopeId(model, target)) return false;
+  const sourceDef = NODE_DEFINITIONS[source.type] || NODE_DEFINITIONS.generic;
+  const targetDef = NODE_DEFINITIONS[target.type] || NODE_DEFINITIONS.generic;
+  if (!SEQUENCE_FLOW_KINDS.has(sourceDef.kind) || !SEQUENCE_FLOW_KINDS.has(targetDef.kind)) return false;
+  if (sourceDef.eventStage === 'end' || targetDef.eventStage === 'start' || targetDef.kind === 'boundary') return false;
+  return !model.edges.some((edge) => (edge.type || 'sequenceFlow') === 'sequenceFlow' && edge.source === sourceId && edge.target === targetId);
+}
+
+function mergeNodePreset(preset = {}) {
+  return {
+    ...preset,
+    properties: preset.properties ? cloneModel(preset.properties) : undefined,
+  };
+}
+
+export class BpmnStudioController {
+  constructor({ model, historyLimit = 80, extensions = [], propertiesProfile = 'business' } = {}) {
+    if (!model) throw new Error('BpmnStudioController requires a model.');
+    this._model = model;
+    this.history = new HistoryStack(historyLimit);
+    this.selection = { kind: 'process', id: model.id };
+    this.activeScopeId = model.id;
+    this.connectingSource = null;
+    this.propertiesProfile = propertiesProfile;
+    this._listeners = new Set();
+    this._extensions = new Map();
+    applyContainmentOperation(this._model, { type: 'reconcile' });
+    this.commands = Object.freeze({
+      createNode: (input) => this.createNode(input),
+      createTemplate: (template, point) => this.createTemplate(template, point),
+      connect: (source, target, overrides) => this.connect(source, target, overrides),
+      updateProcess: (patch) => this.updateProcess(patch),
+      updateNode: (id, patch) => this.updateNode(id, patch),
+      updateEdge: (id, patch) => this.updateEdge(id, patch),
+      updateEdges: (patches) => this.updateEdges(patches),
+      remove: (selection = this.selection) => this.remove(selection),
+      changeElementId: (kind, oldId, nextId) => this.changeElementId(kind, oldId, nextId),
+      changeNodeType: (id, type) => this.changeNodeType(id, type),
+      quickAdd: (sourceId, type, preset) => this.quickAdd(sourceId, type, preset),
+      autoLayout: (direction) => this.autoLayout(direction),
+      beautify: (options) => this.beautify(options),
+      rerouteEdges: (options) => this.rerouteEdges(options),
+      resetEdgeRoute: (id) => this.resetEdgeRoute(id),
+      setEngine: (engine) => this.setEngine(engine),
+      setPropertiesProfile: (profile) => this.setPropertiesProfile(profile),
+      select: (selection) => this.select(selection),
+      selectInRect: (rect, options) => this.selectInRect(rect, options),
+      getSelectionBounds: () => this.getSelectionBounds(),
+      arrangeSelection: (operation) => this.arrangeSelection(operation),
+      groupSelection: () => this.groupSelection(),
+      ungroup: (id) => this.ungroup(id),
+      attachLane: (laneId, participantId, index) => this.attachLane(laneId, participantId, index),
+      detachLane: (laneId, point) => this.detachLane(laneId, point),
+      enterScope: (id) => this.enterScope(id),
+      leaveScope: () => this.leaveScope(),
+      navigateToScope: (id) => this.navigateToScope(id),
+      getActiveGraph: () => this.getActiveGraph(),
+      undo: () => this.undo(),
+      redo: () => this.redo(),
+    });
+    for (const extension of extensions) this.registerExtension(extension);
+  }
+
+  get model() { return this._model; }
+
+  getState() {
+    return {
+      model: cloneModel(this._model),
+      selection: this.selection ? cloneModel(this.selection) : null,
+      selectedElement: cloneModel(this.getSelectedElement()),
+      connectingSource: this.connectingSource,
+      canUndo: this.history.canUndo,
+      canRedo: this.history.canRedo,
+      engine: this._model.engine,
+      propertiesProfile: this.propertiesProfile,
+      activeScopeId: this.activeScopeId,
+      scopePath: getScopePath(this._model, this.activeScopeId),
+    };
+  }
+
+  subscribe(listener) {
+    if (typeof listener !== 'function') return () => {};
+    this._listeners.add(listener);
+    return () => this._listeners.delete(listener);
+  }
+
+  _emit(type, detail = {}) {
+    const event = { type, ...detail, state: this.getState() };
+    for (const listener of this._listeners) listener(event);
+  }
+
+  _commit(reason, mutator) {
+    this.history.capture(this._model);
+    const result = mutator();
+    this._emit('modelChanged', { reason });
+    this._emit('historyChanged', { reason });
+    return result;
+  }
+
+  setModel(model, { resetHistory = true } = {}) {
+    const previousScopeId = this.activeScopeId;
+    this._model = model;
+    applyContainmentOperation(this._model, { type: 'reconcile' });
+    if (resetHistory) this.history = new HistoryStack(this.history.limit);
+    this.connectingSource = null;
+    this.activeScopeId = model.id;
+    if (previousScopeId !== this.activeScopeId) this._emit('scopeChanged', { activeScopeId: this.activeScopeId, scopePath: getScopePath(model, this.activeScopeId) });
+    this.select({ kind: 'process', id: model.id });
+    this._emit('modelChanged', { reason: 'set-model' });
+  }
+
+  select(selection) {
+    if (selection?.kind === 'process') selection = { kind: 'process', id: this._model.id };
+    if (selection?.kind === 'node' && !getNode(this._model, selection.id)) return false;
+    if (selection?.kind === 'edge' && !getEdge(this._model, selection.id)) return false;
+    this.selection = selection ? cloneModel(selection) : null;
+    this._emit('selectionChanged', { selection: this.selection, element: this.getSelectedElement() });
+    return true;
+  }
+
+  getSelectedElement() {
+    if (!this.selection) return null;
+    if (this.selection.kind === 'process') return this._model;
+    if (this.selection.kind === 'node') return getNode(this._model, this.selection.id);
+    if (this.selection.kind === 'edge') return getEdge(this._model, this.selection.id);
+    if (this.selection.kind === 'multi') return this.selection.items.map((ref) => ref.kind === 'node' ? getNode(this._model, ref.id) : getEdge(this._model, ref.id)).filter(Boolean);
+    return null;
+  }
+
+  selectInRect(rect, { mode = 'replace' } = {}) {
+    mode = ['replace', 'add', 'toggle'].includes(mode) ? mode : 'replace';
+    const hits = nodesInSelectionRect(this._model, this.activeScopeId, rect);
+    const current = selectedDiagramNodes(this._model, this.selection, this.activeScopeId);
+    const refs = mergeSelectionRefs(current, hits, mode);
+    let selection;
+    if (!refs.length) selection = this.activeScopeId === this._model.id
+      ? { kind: 'process', id: this._model.id }
+      : { kind: 'node', id: this.activeScopeId };
+    else if (refs.length === 1) selection = refs[0];
+    else selection = { kind: 'multi', items: refs };
+    this.select(selection);
+    return cloneModel(this.selection);
+  }
+
+  getSelectionBounds() {
+    return selectionBounds(selectedDiagramNodes(this._model, this.selection, this.activeScopeId));
+  }
+
+  groupSelection() {
+    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;
+    const bounds = selectionBounds(groupable);
+    if (!bounds) return null;
+    const padding = CONTAINMENT_LIMITS.groupPadding;
+    let group;
+    this._commit('group-selection', () => {
+      group = createNode('group', bounds.x - padding, bounds.y - padding, {
+        scopeId: this.activeScopeId,
+        width: Math.max(CONTAINMENT_LIMITS.groupMinWidth, bounds.width + padding * 2),
+        height: Math.max(CONTAINMENT_LIMITS.groupMinHeight, bounds.height + padding * 2),
+        properties: { categoryValue: '分组' },
+      });
+      const firstIndex = Math.min(...groupable.map((node) => this._model.nodes.indexOf(node)));
+      this._model.nodes.splice(Math.max(0, firstIndex), 0, group);
+    });
+    this.select({ kind: 'node', id: group.id });
+    return group;
+  }
+
+  ungroup(id) {
+    const targetId = id || (this.selection?.kind === 'node' ? this.selection.id : '');
+    const group = getNode(this._model, targetId);
+    if (!group || NODE_DEFINITIONS[group.type]?.kind !== 'group') return false;
+    this._commit('ungroup', () => {
+      this._model.nodes = this._model.nodes.filter((node) => node.id !== targetId);
+      this._model.edges = this._model.edges.filter((edge) => edge.source !== targetId && edge.target !== targetId);
+    });
+    this.select(this.activeScopeId === this._model.id
+      ? { kind: 'process', id: this._model.id }
+      : { kind: 'node', id: this.activeScopeId });
+    return true;
+  }
+
+  attachLane(laneId, participantId, index) {
+    const lane = getNode(this._model, laneId);
+    const participant = getNode(this._model, participantId);
+    if (NODE_DEFINITIONS[lane?.type]?.kind !== 'lane'
+      || NODE_DEFINITIONS[participant?.type]?.kind !== 'participant'
+      || participant.properties?.processRef !== this._model.id) return false;
+    return this._commit('attach-lane', () => applyContainmentOperation(this._model, {
+      type: 'attach-lane', laneId, participantId, index,
+    }).changed);
+  }
+
+  detachLane(laneId, point = {}) {
+    const lane = getNode(this._model, laneId);
+    if (NODE_DEFINITIONS[lane?.type]?.kind !== 'lane' || !lane.containerId) return false;
+    return this._commit('detach-lane', () => applyContainmentOperation(this._model, {
+      type: 'detach-lane', laneId, x: point.x, y: point.y,
+    }).changed);
+  }
+
+  arrangeSelection(operation) {
+    const valid = operation?.type === 'align'
+      ? ['left', 'centerX', 'right', 'top', 'centerY', 'bottom'].includes(operation.alignment)
+      : operation?.type === 'distribute'
+        ? ['horizontal', 'vertical'].includes(operation.axis)
+        : ['layout', 'reroute'].includes(operation?.type);
+    if (!valid) return false;
+    const nodes = selectedLayoutNodes(this._model, this.selection, this.activeScopeId);
+    if (nodes.length < (operation?.type === 'reroute' ? 1 : 2)) return false;
+    if (operation?.type === 'distribute' && nodes.length < 3) return false;
+    return this._commit(`selection-${operation?.type || 'arrange'}`, () => (
+      applySelectionArrangement(this._model, this.selection, this.activeScopeId, operation)
+    ));
+  }
+
+  getActiveGraph() { return getScopeGraph(this._model, this.activeScopeId); }
+
+  _nearestAvailableScope(model, previousPath) {
+    for (let index = previousPath.length - 1; index >= 0; index -= 1) {
+      if (scopeExists(model, previousPath[index].id)) return previousPath[index].id;
+    }
+    return model.id;
+  }
+
+  _setActiveScope(scopeId, nextSelection = null) {
+    if (!scopeExists(this._model, scopeId) || scopeId === this.activeScopeId) return false;
+    this.cancelConnect();
+    this.activeScopeId = scopeId;
+    const selection = nextSelection || (scopeId === this._model.id ? { kind: 'process', id: this._model.id } : { kind: 'node', id: scopeId });
+    this.selection = selection;
+    this._emit('scopeChanged', { activeScopeId: scopeId, scopePath: getScopePath(this._model, scopeId) });
+    this._emit('selectionChanged', { selection, element: this.getSelectedElement() });
+    return true;
+  }
+
+  enterScope(subProcessId) {
+    const node = getNode(this._model, subProcessId);
+    if (!node || !isEmbeddedSubProcess(node) || elementScopeId(this._model, node) !== this.activeScopeId) return false;
+    return this._setActiveScope(node.id);
+  }
+
+  leaveScope() {
+    const exitedScopeId = this.activeScopeId;
+    const parentScopeId = getParentScopeId(this._model, this.activeScopeId);
+    return parentScopeId ? this._setActiveScope(parentScopeId, { kind: 'node', id: exitedScopeId }) : false;
+  }
+
+  navigateToScope(scopeId) {
+    const currentPath = getScopePath(this._model, this.activeScopeId);
+    const targetIndex = currentPath.findIndex((item) => item.id === scopeId);
+    const exited = targetIndex >= 0 && targetIndex < currentPath.length - 1 ? currentPath[targetIndex + 1] : null;
+    return this._setActiveScope(scopeId, exited ? { kind: 'node', id: exited.id } : null);
+  }
+
+  createNode({ nodeType, point, preset = {} } = {}) {
+    const def = NODE_DEFINITIONS[nodeType];
+    if (!def) throw new Error(`Unknown BPMN node type: ${nodeType}`);
+    const position = point || { x: 100, y: 100 };
+    let node;
+    this._commit('create-node', () => {
+      const mergedPreset = mergeNodePreset(preset);
+      if (nodeType === 'participant') {
+        mergedPreset.properties = { ...(mergedPreset.properties || {}), processRef: mergedPreset.properties?.processRef || this._model.id };
+      }
+      node = createNode(nodeType, position.x, position.y, { ...mergedPreset, scopeId: this.activeScopeId });
+      this._model.nodes.push(node);
+      if (nodeType === 'lane') {
+        const participant = resolveContainment(this._model).getParticipantAt({
+          x: node.x + node.width / 2,
+          y: node.y + node.height / 2,
+        });
+        if (participant) applyContainmentOperation(this._model, { type: 'attach-lane', laneId: node.id, participantId: participant.id });
+      }
+    });
+    this.select({ kind: 'node', id: node.id });
+    return node;
+  }
+
+  createTemplate(template = {}, point = { x: 100, y: 100 }) {
+    const nodeSpecs = template.nodes || [];
+    if (!nodeSpecs.length) throw new Error('A template must contain at least one node.');
+    const keys = new Set();
+    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}`);
+      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.');
+    const result = { nodes: [], edges: [] };
+    const byKey = new Map();
+    this._commit('create-template', () => {
+      for (const spec of nodeSpecs) {
+        const offset = spec.offset || { x: 0, y: 0 };
+        const node = createNode(spec.nodeType, Math.round(point.x + (offset.x || 0)), Math.round(point.y + (offset.y || 0)), { ...mergeNodePreset(spec.preset), scopeId: this.activeScopeId });
+        byKey.set(spec.key, node);
+        result.nodes.push(node);
+        this._model.nodes.push(node);
+      }
+      for (const spec of template.edges || []) {
+        const edge = createEdge(byKey.get(spec.source).id, byKey.get(spec.target).id, { ...(spec.preset || {}), scopeId: this.activeScopeId });
+        result.edges.push(edge);
+        this._model.edges.push(edge);
+      }
+    });
+    this.select({ kind: 'multi', items: result.nodes.map((node) => ({ kind: 'node', id: node.id })) });
+    return result;
+  }
+
+  connect(source, target, overrides = {}) {
+    if (!canCreateSequenceFlow(this._model, source, target)) return null;
+    let edge;
+    this._commit('connect', () => {
+      edge = createEdge(source, target, { ...overrides, scopeId: elementScopeId(this._model, getNode(this._model, source)) });
+      this._model.edges.push(edge);
+    });
+    this.select({ kind: 'edge', id: edge.id });
+    return edge;
+  }
+
+  startConnect(sourceId) {
+    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;
+    this.connectingSource = this.connectingSource === sourceId ? null : sourceId;
+    if (this.connectingSource) this.select({ kind: 'node', id: sourceId });
+    this._emit('connectingChanged', { sourceId: this.connectingSource });
+    return true;
+  }
+
+  cancelConnect() {
+    if (!this.connectingSource) return;
+    this.connectingSource = null;
+    this._emit('connectingChanged', { sourceId: null });
+  }
+
+  beginGesture() { return cloneModel(this._model); }
+
+  commitGesture(snapshot, reason = 'gesture') {
+    if (!snapshot) return false;
+    this.history.undoStack.push(snapshot);
+    if (this.history.undoStack.length > this.history.limit) this.history.undoStack.shift();
+    this.history.redoStack.length = 0;
+    this._emit('modelChanged', { reason });
+    this._emit('historyChanged', { reason });
+    return true;
+  }
+
+  updateProcess(patch = {}) {
+    this._commit('update-process', () => {
+      if (patch.properties) this._model.properties = { ...(this._model.properties || {}), ...patch.properties };
+      if (patch.settings) this._model.settings = { ...(this._model.settings || {}), ...patch.settings };
+      if (patch.resources) this._model.resources = { ...(this._model.resources || {}), ...patch.resources };
+      const rest = { ...patch };
+      delete rest.properties; delete rest.settings; delete rest.resources;
+      Object.assign(this._model, rest);
+    });
+  }
+
+  updateNode(id, patch = {}) {
+    const node = getNode(this._model, id);
+    if (!node) return false;
+    const previousLabelPlacement = resolveSwimlaneLabelPlacement(this._model, node);
+    this._commit('update-node', () => {
+      if (patch.properties) node.properties = { ...node.properties, ...patch.properties };
+      const rest = { ...patch }; delete rest.properties;
+      Object.assign(node, rest);
+      clearConnectedWaypoints(this._model, id);
+      const nextLabelPlacement = resolveSwimlaneLabelPlacement(this._model, node);
+      if (previousLabelPlacement !== nextLabelPlacement) {
+        const result = applyContainmentOperation(this._model, {
+          type: 'update-label-placement',
+          nodeId: id,
+          previousPlacement: previousLabelPlacement,
+        });
+        if (result.changed) for (const edge of this._model.edges) edge.waypoints = null;
+      } else {
+        applyContainmentOperation(this._model, { type: 'reconcile' });
+      }
+    });
+    return true;
+  }
+
+  updateEdge(id, patch = {}) {
+    const edge = getEdge(this._model, id);
+    if (!edge) return false;
+    this._commit('update-edge', () => {
+      if (patch.properties) edge.properties = { ...(edge.properties || {}), ...patch.properties };
+      const rest = { ...patch }; delete rest.properties;
+      Object.assign(edge, rest);
+    });
+    return true;
+  }
+
+  updateEdges(patches = []) {
+    const valid = patches.filter((item) => item?.id && getEdge(this._model, item.id));
+    if (!valid.length) return false;
+    this._commit('update-edges', () => {
+      for (const { id, patch = {} } of valid) {
+        const edge = getEdge(this._model, id);
+        if (patch.properties) edge.properties = { ...(edge.properties || {}), ...patch.properties };
+        const rest = { ...patch }; delete rest.properties;
+        Object.assign(edge, rest);
+      }
+    });
+    return true;
+  }
+
+  changeElementId(kind, oldId, nextId) {
+    const value = String(nextId || '').trim();
+    if (!value || value === oldId) return false;
+    if (!['process', 'node', 'edge'].includes(kind)) return false;
+    if (kind === 'process' && this._model.id !== oldId) return false;
+    if (kind === 'node' && !getNode(this._model, oldId)) return false;
+    if (kind === 'edge' && !getEdge(this._model, oldId)) return false;
+    const conflict = this._model.id === value || this._model.nodes.some((node) => node.id === value) || this._model.edges.some((edge) => edge.id === value);
+    if (conflict) return false;
+    this._commit('change-element-id', () => {
+      if (kind === 'process') {
+        this._model.id = value;
+        for (const node of this._model.nodes) if (!node.scopeId || node.scopeId === oldId) node.scopeId = value;
+        for (const edge of this._model.edges) if (!edge.scopeId || edge.scopeId === oldId) edge.scopeId = value;
+        if (this.activeScopeId === oldId) this.activeScopeId = value;
+        for (const node of this._model.nodes) if (node.type === 'participant' && node.properties?.processRef === oldId) node.properties.processRef = value;
+      } else if (kind === 'node') {
+        const node = getNode(this._model, oldId);
+        if (!node) return;
+        node.id = value;
+        for (const item of this._model.nodes) if (item.scopeId === oldId) item.scopeId = value;
+        for (const item of this._model.edges) if (item.scopeId === oldId) item.scopeId = value;
+        if (this.activeScopeId === oldId) this.activeScopeId = value;
+        for (const edge of this._model.edges) {
+          if (edge.source === oldId) edge.source = value;
+          if (edge.target === oldId) edge.target = value;
+        }
+        for (const item of this._model.nodes) {
+          if (item.containerId === oldId) item.containerId = value;
+          if (item.properties?.attachedToRef === oldId) item.properties.attachedToRef = value;
+          if (Array.isArray(item.properties?.flowNodeRefs)) item.properties.flowNodeRefs = item.properties.flowNodeRefs.map((ref) => ref === oldId ? value : ref);
+        }
+      } else if (kind === 'edge') {
+        const edge = getEdge(this._model, oldId);
+        if (!edge) return;
+        edge.id = value;
+        for (const node of this._model.nodes) if (node.defaultFlowId === oldId) node.defaultFlowId = value;
+      }
+    });
+    if (kind !== 'edge') this._emit('scopeChanged', { activeScopeId: this.activeScopeId, scopePath: getScopePath(this._model, this.activeScopeId) });
+    this.select({ kind, id: value });
+    return true;
+  }
+
+  changeNodeType(id, type) {
+    const node = getNode(this._model, id);
+    const def = NODE_DEFINITIONS[type];
+    if (!node || !def || 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 });
+      Object.assign(node, { type, bpmnType: def.bpmnType, width: def.width, height: def.height, originalLocalName: def.localName });
+      node.isExpanded = isEmbeddedSubProcess(type) ? false : undefined;
+      node.properties = { ...next.properties, ...node.properties };
+      clearConnectedWaypoints(this._model, id);
+      applyContainmentOperation(this._model, { type: 'reconcile' });
+    });
+    return true;
+  }
+
+  quickAdd(sourceId, type = 'userTask', preset = {}) {
+    const source = getNode(this._model, sourceId);
+    const def = NODE_DEFINITIONS[type];
+    if (!source || elementScopeId(this._model, source) !== this.activeScopeId || !def) 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;
+    const x = direction === 'vertical'
+      ? source.x + source.width / 2 - def.width / 2
+      : source.x + source.width + spacing.rankGap;
+    const y = direction === 'vertical'
+      ? source.y + source.height + spacing.rankGap
+      : source.y + source.height / 2 - def.height / 2 + (outgoingCount ? outgoingCount * (def.height + spacing.nodeGap) : 0);
+    let node;
+    this._commit('quick-add', () => {
+      node = createNode(type, Math.round(x), Math.round(y), { ...mergeNodePreset(preset), scopeId: elementScopeId(this._model, source) });
+      this._model.nodes.push(node);
+      this._model.edges.push(createEdge(sourceId, node.id, { name: NODE_DEFINITIONS[source.type]?.kind === 'gateway' ? `分支 ${outgoingCount + 1}` : '', scopeId: elementScopeId(this._model, source) }));
+    });
+    this.select({ kind: 'node', id: node.id });
+    return node;
+  }
+
+  remove(selection = this.selection) {
+    if (!selection || selection.kind === 'process') return false;
+    const refs = selection.kind === 'multi' ? selection.items : [selection];
+    const previousScopeId = this.activeScopeId;
+    const requestedNodeIds = refs.filter((ref) => ref.kind === 'node').map((ref) => ref.id);
+    let fallbackScopeId = this.activeScopeId;
+    for (const id of requestedNodeIds) {
+      if (id === fallbackScopeId || getDescendantScopeIds(this._model, id).has(fallbackScopeId)) fallbackScopeId = elementScopeId(this._model, getNode(this._model, id));
+    }
+    this._commit('remove', () => {
+      const nodeIds = new Set(requestedNodeIds);
+      const removedScopes = new Set();
+      for (const id of requestedNodeIds) {
+        const node = getNode(this._model, id);
+        if (!isEmbeddedSubProcess(node)) continue;
+        const descendantScopes = getDescendantScopeIds(this._model, id);
+        for (const scopeId of descendantScopes) removedScopes.add(scopeId);
+        for (const candidate of this._model.nodes) if (descendantScopes.has(elementScopeId(this._model, candidate))) nodeIds.add(candidate.id);
+      }
+      const edgeIds = new Set(refs.filter((ref) => ref.kind === 'edge').map((ref) => ref.id));
+      for (const nodeId of nodeIds) applyContainmentOperation(this._model, { type: 'prepare-remove', nodeId });
+      this._model.nodes = this._model.nodes.filter((node) => !nodeIds.has(node.id));
+      this._model.edges = this._model.edges.filter((edge) => !edgeIds.has(edge.id) && !removedScopes.has(elementScopeId(this._model, edge)) && !nodeIds.has(edge.source) && !nodeIds.has(edge.target));
+      applyContainmentOperation(this._model, { type: 'reconcile' });
+    });
+    if (!scopeExists(this._model, this.activeScopeId)) this.activeScopeId = scopeExists(this._model, fallbackScopeId) ? fallbackScopeId : this._model.id;
+    this.select(this.activeScopeId === this._model.id ? { kind: 'process', id: this._model.id } : { kind: 'node', id: this.activeScopeId });
+    if (previousScopeId !== this.activeScopeId) this._emit('scopeChanged', { activeScopeId: this.activeScopeId, scopePath: getScopePath(this._model, this.activeScopeId) });
+    return true;
+  }
+
+  autoLayout(direction = this._model.settings?.direction || 'horizontal') { this._commit('auto-layout', () => autoLayout(this.getActiveGraph(), { direction })); }
+  beautify(options = {}) {
+    this._commit('beautify', () => {
+      const graph = this.getActiveGraph();
+      beautify(graph, options);
+      this._model.settings = graph.settings;
+    });
+  }
+  rerouteEdges(options = {}) {
+    this._commit('reroute-edges', () => {
+      const edgeStyle = options.edgeStyle || this._model.settings?.edgeStyle || 'rounded';
+      const cornerRadius = options.cornerRadius ?? this._model.settings?.cornerRadius ?? 16;
+      this._model.settings = { ...(this._model.settings || {}), edgeStyle, cornerRadius };
+      for (const edge of this.getActiveGraph().edges) Object.assign(edge, { waypoints: null, routeStyle: edgeStyle, cornerRadius });
+    });
+  }
+  resetEdgeRoute(id) { return this.updateEdge(id, { waypoints: null }); }
+
+  setEngine(engine) {
+    if (!['flowable', 'activiti'].includes(engine) || engine === this._model.engine) return false;
+    this._commit('set-engine', () => { this._model.engine = engine; });
+    return true;
+  }
+  setPropertiesProfile(profile) {
+    if (!['business', 'developer'].includes(profile) || profile === this.propertiesProfile) return false;
+    this.propertiesProfile = profile;
+    this._emit('propertiesProfileChanged', { profile });
+    return true;
+  }
+  exportXml(engine) { return exportBpmn(this._model, engine); }
+  importXml(xml, engine) { const model = importBpmn(xml, engine); this.setModel(model); return model; }
+
+  validate() {
+    const issues = [];
+    const starts = this._model.nodes.filter((node) => NODE_DEFINITIONS[node.type]?.eventStage === 'start');
+    const ends = this._model.nodes.filter((node) => NODE_DEFINITIONS[node.type]?.eventStage === 'end');
+    if (!starts.length) issues.push({ level: 'error', message: '流程至少需要一个开始事件。' });
+    if (!ends.length) issues.push({ level: 'warning', message: '建议至少配置一个结束事件。' });
+    const scopeIssues = getScopeIntegrityIssues(this._model);
+    const invalidScopeEdges = new Set(scopeIssues.filter((issue) => issue.kind === 'edge').map((issue) => issue.id));
+    for (const issue of scopeIssues.filter((item) => item.kind === 'node')) {
+      issues.push({ level: 'error', elementId: issue.id, message: '节点引用了不存在或无效的子流程作用域。' });
+    }
+    for (const edge of this._model.edges) {
+      if (!getNode(this._model, edge.source) || !getNode(this._model, edge.target)) issues.push({ level: 'error', elementId: edge.id, message: '连线引用了不存在的节点。' });
+      else if (invalidScopeEdges.has(edge.id)) issues.push({ level: 'error', elementId: edge.id, message: '连线不能跨越流程或子流程作用域。' });
+      if ((edge.type || 'sequenceFlow') === 'sequenceFlow' && edge.source === edge.target) issues.push({ level: 'error', elementId: edge.id, message: '顺序流不能连接到自身。' });
+    }
+    for (const node of this._model.nodes) {
+      const definition = NODE_DEFINITIONS[node.type] || NODE_DEFINITIONS.generic;
+      if (node.type === 'serviceTask' && !node.properties?.implementation) issues.push({ level: 'warning', elementId: node.id, message: `${node.name}: 服务任务尚未配置实现。` });
+      if (node.type === 'userTask' && !node.properties?.assignee && !node.properties?.candidateUsers && !node.properties?.candidateGroups) issues.push({ level: 'warning', elementId: node.id, message: `${node.name}: 用户任务尚未配置处理人。` });
+      if (definition.kind === 'boundary' && !node.properties?.attachedToRef) issues.push({ level: 'warning', elementId: node.id, message: `${node.name}: 边界事件尚未选择附着活动。` });
+      for (const message of validateParallelGateway(this._model, node)) issues.push({ level: 'warning', elementId: node.id, message: `${node.name}: ${message}` });
+    }
+    return issues;
+  }
+
+  undo() {
+    const previousScopeId = this.activeScopeId;
+    const previousPath = getScopePath(this._model, previousScopeId);
+    const model = this.history.undo(this._model);
+    if (!model) return false;
+    this._model = model;
+    applyContainmentOperation(this._model, { type: 'reconcile' });
+    this.activeScopeId = this._nearestAvailableScope(model, previousPath);
+    this.selection = this.activeScopeId === model.id ? { kind: 'process', id: model.id } : { kind: 'node', id: this.activeScopeId };
+    if (previousScopeId !== this.activeScopeId) this._emit('scopeChanged', { activeScopeId: this.activeScopeId, scopePath: getScopePath(model, this.activeScopeId) });
+    this._emit('modelChanged', { reason: 'undo' });
+    this._emit('selectionChanged', { selection: this.selection, element: this.getSelectedElement() });
+    this._emit('historyChanged', { reason: 'undo' });
+    return true;
+  }
+
+  redo() {
+    const previousScopeId = this.activeScopeId;
+    const previousPath = getScopePath(this._model, previousScopeId);
+    const model = this.history.redo(this._model);
+    if (!model) return false;
+    this._model = model;
+    applyContainmentOperation(this._model, { type: 'reconcile' });
+    this.activeScopeId = this._nearestAvailableScope(model, previousPath);
+    this.selection = this.activeScopeId === model.id ? { kind: 'process', id: model.id } : { kind: 'node', id: this.activeScopeId };
+    if (previousScopeId !== this.activeScopeId) this._emit('scopeChanged', { activeScopeId: this.activeScopeId, scopePath: getScopePath(model, this.activeScopeId) });
+    this._emit('modelChanged', { reason: 'redo' });
+    this._emit('selectionChanged', { selection: this.selection, element: this.getSelectedElement() });
+    this._emit('historyChanged', { reason: 'redo' });
+    return true;
+  }
+
+  registerExtension(extension) {
+    if (!extension?.id || typeof extension.setup !== 'function') throw new Error('Studio extension requires id and setup().');
+    if (this._extensions.has(extension.id)) throw new Error(`Studio extension already registered: ${extension.id}`);
+    const cleanup = extension.setup({ studio: this }) || (() => {});
+    this._extensions.set(extension.id, cleanup);
+    return () => { this._extensions.get(extension.id)?.(); this._extensions.delete(extension.id); };
+  }
+
+  destroy() {
+    for (const cleanup of this._extensions.values()) cleanup?.();
+    this._extensions.clear();
+    this._listeners.clear();
+  }
+}
+
+export function createStudioController(options) {
+  return new BpmnStudioController(options);
+}