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

package/dist/modules/renderer-svg/index.js

@@ -0,0 +1,1460 @@
+import { NODE_DEFINITIONS, PALETTE_GROUPS, PARALLEL_GATEWAY_PRESETS, edgeWaypoints, resolveGatewayRole, resolveSwimlaneLabelPlacement, roundedPath, routeRuntimeTransition, smoothPath } from '../core/index.js';
+import { createRuntimePresentation } from '../runtime/index.js';
+import { createDefaultIconRegistry, createIconElement, resolveNodeVisual } from '../icons/index.js';
+import { ThemeController, applyRuntimeTone } from '../theme/index.js';
+import { exportDiagramSvg, openSvgExportPreview } from '../export-svg/index.js';
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+const XHTML_NS = 'http://www.w3.org/1999/xhtml';
+
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+
+function quantizeZoom(value, step = 0.05) {
+  const clamped = clamp(value, 0.25, 2.25);
+  return Math.round(Math.round(clamped / step) * step * 1000) / 1000;
+}
+
+function estimateLabelTextWidth(value) {
+  let width = 0;
+  for (const ch of Array.from(String(value ?? ''))) {
+    const code = ch.codePointAt(0);
+    if (/\s/.test(ch)) width += 3.8;
+    else if ((code >= 0x2e80 && code <= 0x9fff) || (code >= 0xf900 && code <= 0xfaff)) width += 11.6;
+    else if (/[A-Z]/.test(ch)) width += 7.2;
+    else if (/[a-z]/.test(ch)) width += 6.2;
+    else if (/[0-9]/.test(ch)) width += 6.4;
+    else if (/[.,:;]/.test(ch)) width += 4.2;
+    else width += 7.4;
+  }
+  return width;
+}
+
+const EDGE_LABEL_TOKENS = Object.freeze({
+  paddingX: 10,
+  paddingY: 5,
+  maxWidth: 144,
+  lineHeight: 16,
+  radius: 7,
+});
+
+const SCENE_MARGIN = 1200;
+const MIN_SCENE_SIZE = 1;
+
+/**
+ * Computes a render envelope for SVG content without constraining the logical canvas.
+ * Node coordinates may be negative or arbitrarily large; the renderer only sizes its
+ * SVG layers around currently visible/content coordinates so there is no fixed 5200×3200
+ * world boundary.
+ */
+export function computeSceneBounds(model, viewportBounds = null, margin = SCENE_MARGIN) {
+  const xs = [0];
+  const ys = [0];
+  const nodes = model?.nodes || [];
+  const edges = model?.edges || [];
+
+  for (const node of nodes) {
+    xs.push(node.x, node.x + node.width);
+    ys.push(node.y, node.y + node.height);
+  }
+  for (const edge of edges) {
+    for (const point of edgeWaypoints(model, edge)) {
+      xs.push(point.x);
+      ys.push(point.y);
+    }
+  }
+  if (viewportBounds) {
+    xs.push(viewportBounds.left, viewportBounds.right);
+    ys.push(viewportBounds.top, viewportBounds.bottom);
+  }
+
+  const left = Math.floor(Math.min(...xs) - margin);
+  const top = Math.floor(Math.min(...ys) - margin);
+  const right = Math.ceil(Math.max(...xs) + margin);
+  const bottom = Math.ceil(Math.max(...ys) + margin);
+  return {
+    left,
+    top,
+    right,
+    bottom,
+    width: Math.max(MIN_SCENE_SIZE, right - left),
+    height: Math.max(MIN_SCENE_SIZE, bottom - top),
+  };
+}
+
+function wrapLabelText(value, maxTextWidth) {
+  const paragraphs = String(value ?? '').split(/\r?\n/);
+  const lines = [];
+  for (const paragraph of paragraphs) {
+    if (!paragraph) {
+      lines.push('');
+      continue;
+    }
+    let current = '';
+    let currentWidth = 0;
+    for (const ch of Array.from(paragraph)) {
+      const chWidth = estimateLabelTextWidth(ch);
+      if (current && currentWidth + chWidth > maxTextWidth) {
+        lines.push(current.trimEnd());
+        current = ch.trimStart();
+        currentWidth = estimateLabelTextWidth(current);
+      } else {
+        current += ch;
+        currentWidth += chWidth;
+      }
+    }
+    if (current || !lines.length) lines.push(current.trimEnd());
+  }
+  return lines.length ? lines : [''];
+}
+
+export function edgeLabelMetrics(value, options = {}) {
+  const tokens = { ...EDGE_LABEL_TOKENS, ...(options || {}) };
+  const maxTextWidth = Math.max(24, tokens.maxWidth - tokens.paddingX * 2);
+  const lines = wrapLabelText(value, maxTextWidth);
+  const textWidth = Math.min(maxTextWidth, Math.max(...lines.map(estimateLabelTextWidth), 0));
+  return {
+    width: Math.ceil(textWidth + tokens.paddingX * 2),
+    height: Math.ceil(lines.length * tokens.lineHeight + tokens.paddingY * 2),
+    paddingX: tokens.paddingX,
+    paddingY: tokens.paddingY,
+    maxWidth: tokens.maxWidth,
+    lineHeight: tokens.lineHeight,
+    radius: tokens.radius,
+    lines,
+  };
+}
+
+function normalizeRect(rect) {
+  if (!rect) return null;
+  const left = rect.left ?? rect.x ?? 0;
+  const top = rect.top ?? rect.y ?? 0;
+  const right = rect.right ?? left + (rect.width ?? 0);
+  const bottom = rect.bottom ?? top + (rect.height ?? 0);
+  return { left, right, top, bottom };
+}
+
+function labelBounds(point, metrics) {
+  const left = point.x - metrics.width / 2;
+  const top = point.y - metrics.height / 2;
+  return {
+    x: left,
+    y: top,
+    width: metrics.width,
+    height: metrics.height,
+    left,
+    right: left + metrics.width,
+    top,
+    bottom: top + metrics.height,
+  };
+}
+
+function rectsOverlap(a, b, padding = 0) {
+  const obstacle = normalizeRect(b);
+  if (!obstacle) return false;
+  return a.left < obstacle.right + padding
+    && a.right > obstacle.left - padding
+    && a.top < obstacle.bottom + padding
+    && a.bottom > obstacle.top - padding;
+}
+
+/**
+ * Places an edge label without consuming the Sequence Flow arrow corridor.
+ * Short connector segments move the label perpendicular to the path and away
+ * from node/label obstacles instead of painting over the terminal marker.
+ */
+export function edgeLabelPlacement(points, metrics, options = {}) {
+  if (!points?.length) {
+    const point = { x: 0, y: 0 };
+    return { ...point, bounds: labelBounds(point, metrics), strategy: 'fallback', segmentIndex: -1 };
+  }
+  if (points.length === 1) {
+    const point = { ...points[0] };
+    return { ...point, bounds: labelBounds(point, metrics), strategy: 'fallback', segmentIndex: 0 };
+  }
+
+  const startClearance = options.startClearance ?? 8;
+  const endClearance = options.endClearance ?? 16;
+  const innerClearance = options.innerClearance ?? 6;
+  const obstaclePadding = options.obstaclePadding ?? 6;
+  const labelGap = options.labelGap ?? 8;
+  const offsetStep = options.offsetStep ?? 20;
+  const maxOffset = options.maxOffset ?? 168;
+  const obstacles = options.obstacles || [];
+  const segments = [];
+
+  for (let index = 0; index < points.length - 1; index += 1) {
+    const a = points[index];
+    const b = points[index + 1];
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    const length = Math.hypot(dx, dy);
+    if (length < 0.01) continue;
+    const ux = dx / length;
+    const uy = dy / length;
+    segments.push({ index, a, b, length, ux, uy, nx: -uy, ny: ux });
+  }
+  segments.sort((a, b) => b.length - a.length || a.index - b.index);
+
+  const isClear = (bounds) => !obstacles.some((obstacle) => rectsOverlap(bounds, obstacle, obstaclePadding));
+  for (const segment of segments) {
+    const before = segment.index === 0 ? startClearance : innerClearance;
+    const after = segment.index === points.length - 2 ? endClearance : innerClearance;
+    const axisSize = Math.abs(segment.ux) * metrics.width + Math.abs(segment.uy) * metrics.height;
+    const minCenter = before + axisSize / 2;
+    const maxCenter = segment.length - after - axisSize / 2;
+    if (minCenter > maxCenter) continue;
+    const distance = clamp(segment.length / 2, minCenter, maxCenter);
+    const point = { x: segment.a.x + segment.ux * distance, y: segment.a.y + segment.uy * distance };
+    const bounds = labelBounds(point, metrics);
+    if (isClear(bounds)) return { ...point, bounds, strategy: 'inline', segmentIndex: segment.index };
+  }
+
+  for (const segment of segments) {
+    const midpoint = { x: (segment.a.x + segment.b.x) / 2, y: (segment.a.y + segment.b.y) / 2 };
+    const perpendicularSize = Math.abs(segment.nx) * metrics.width + Math.abs(segment.ny) * metrics.height;
+    const initialOffset = perpendicularSize / 2 + labelGap;
+    for (let offset = initialOffset; offset <= maxOffset; offset += offsetStep) {
+      for (const side of [-1, 1]) {
+        const point = { x: midpoint.x + segment.nx * offset * side, y: midpoint.y + segment.ny * offset * side };
+        const bounds = labelBounds(point, metrics);
+        if (isClear(bounds)) return { ...point, bounds, strategy: 'offset', segmentIndex: segment.index };
+      }
+    }
+  }
+
+  const point = edgeLabelPoint(points);
+  return { ...point, bounds: labelBounds(point, metrics), strategy: 'fallback', segmentIndex: -1 };
+}
+
+function el(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+function uiIconElement(registry, id, className = 'nova-icon nova-icon-sm') {
+  const host = el('span', className);
+  host.dataset.icon = id;
+  const iconNode = createIconElement(registry.resolve(id, null), { className: 'nova-icon-svg' });
+  if (iconNode) host.appendChild(iconNode);
+  return host;
+}
+
+function svgEl(tag, attrs = {}) {
+  const node = document.createElementNS(SVG_NS, tag);
+  for (const [key, value] of Object.entries(attrs)) {
+    if (value !== undefined && value !== null) node.setAttribute(key, String(value));
+  }
+  return node;
+}
+
+function linearPath(points) {
+  if (!points.length) return '';
+  return points.map((p, i) => `${i === 0 ? 'M' : 'L'} ${p.x} ${p.y}`).join(' ');
+}
+
+function routePathData(points, routeStyle = 'rounded', cornerRadius = 14) {
+  if (routeStyle === 'straight') return linearPath(points);
+  if (routeStyle === 'smooth') return smoothPath(points, Math.max(24, cornerRadius * 1.7));
+  return roundedPath(points, cornerRadius);
+}
+
+function displaySubtitle(node) {
+  const p = node.properties || {};
+  if (node.type === 'userTask') return p.assignee || p.candidateGroups || p.candidateUsers || '待配置审批人';
+  if (['serviceTask', 'sendTask', 'businessRuleTask'].includes(node.type)) return p.implementation || '待配置执行实现';
+  if (node.type === 'scriptTask') return p.scriptFormat || 'Script';
+  if (node.type === 'callActivity') return p.calledElement || '待配置调用流程';
+  if (node.type === 'receiveTask') return '等待消息或外部触发';
+  if (node.type === 'manualTask') return '人工线下处理';
+  if (node.type === 'subProcess') return '可折叠子流程';
+  if (node.type === 'eventSubProcess') return '事件触发子流程';
+  if (node.type === 'transaction') return '事务边界';
+  return node.bpmnType?.replace('bpmn:', '') || '';
+}
+
+function runtimeStatusIconId(presentation) {
+  if (presentation?.status === 'rejected') return 'ui.statusRejected';
+  if (presentation?.status === 'completed') return 'ui.statusCompleted';
+  if (presentation?.status === 'active') return 'ui.statusActive';
+  if (presentation?.status === 'failed') return 'ui.statusFailed';
+  if (['skipped', 'cancelled'].includes(presentation?.status)) return 'ui.statusSkipped';
+  return 'ui.statusIdle';
+}
+
+function edgeLabelPoint(points) {
+  if (!points.length) return { x: 0, y: 0 };
+  if (points.length === 1) return points[0];
+  let best = null;
+  for (let i = 0; i < points.length - 1; i += 1) {
+    const a = points[i];
+    const b = points[i + 1];
+    const len = Math.hypot(b.x - a.x, b.y - a.y);
+    if (!best || len > best.len) best = { len, a, b };
+  }
+  return { x: (best.a.x + best.b.x) / 2, y: (best.a.y + best.b.y) / 2 };
+}
+
+function addActivityMarkers(nodeEl, visual, registry) {
+  if (!visual.activityMarkerIds.length) return;
+  const wrap = el('div', 'mb-activity-markers');
+  wrap.setAttribute('aria-hidden', 'true');
+  visual.activityMarkerIds.forEach((markerId) => {
+    const marker = el('span', 'mb-activity-marker');
+    const iconNode = createIconElement(registry.resolve(markerId, null), { className: 'mb-activity-marker-icon' });
+    if (iconNode) marker.appendChild(iconNode);
+    wrap.appendChild(marker);
+  });
+  nodeEl.appendChild(wrap);
+}
+
+export class DiagramRenderer {
+  constructor(container, options = {}) {
+    if (!container) throw new Error('DiagramRenderer requires a container element.');
+    this.container = container;
+    this.options = options;
+    this.themeController = options.themeController || new ThemeController({ root: container, theme: options.theme, onChange: options.onThemeChange });
+    this._ownsThemeController = !options.themeController;
+    this.iconRegistry = options.iconRegistry || createDefaultIconRegistry();
+    this._nodeContentCleanups = [];
+    this.model = options.model || { nodes: [], edges: [] };
+    this.mode = options.mode || 'design';
+    this.runtime = options.runtime || null;
+    this.runtimePresentation = null;
+    this.selection = null;
+    this.interactionMode = options.interactionMode || 'select';
+    this.connectingSource = null;
+    this.quickMenuNodeId = null;
+    this.zoom = 1;
+    this.pan = { x: 0, y: 0 };
+    this._isPanning = false;
+    this._panStart = null;
+    this._isMarquee = false;
+    this._spacePressed = false;
+    this.alignmentGuides = [];
+    this.svgExportOptions = options.svgExport || {};
+    this._svgExportPreview = null;
+    this._buildDom();
+    this.render();
+  }
+
+  _buildDom() {
+    this.container.innerHTML = '';
+    this.container.classList.add('mb-diagram-host');
+
+    this.viewport = el('div', 'mb-diagram-viewport');
+    this.viewport.dataset.interactionMode = this.interactionMode;
+    this.marquee = el('div', 'mb-selection-marquee');
+    this.marquee.hidden = true;
+    this.world = el('div', 'mb-diagram-world');
+    this.edgeSvg = svgEl('svg', { class: 'mb-edge-layer' });
+    this.runtimeTransitionSvg = svgEl('svg', { class: 'mb-runtime-transition-layer' });
+    this.guideSvg = svgEl('svg', { class: 'mb-guide-layer' });
+    this.nodeLayer = el('div', 'mb-node-layer');
+    this.edgeLabelSvg = svgEl('svg', { class: 'mb-edge-label-layer' });
+
+    const defs = svgEl('defs');
+    const markers = [
+      ['arrow', 'var(--mb-edge)'],
+      ['arrow-completed', 'var(--mb-success)'],
+      ['arrow-active', 'var(--mb-primary)'],
+      ['arrow-failed', 'var(--mb-danger)'],
+    ];
+    for (const [id] of markers) {
+      const marker = svgEl('marker', { id, viewBox: '0 0 10 10', refX: '8.5', refY: '5', markerWidth: '7', markerHeight: '7', orient: 'auto-start-reverse', markerUnits: 'strokeWidth' });
+      marker.appendChild(svgEl('path', { d: 'M 0 0 L 10 5 L 0 10 z', fill: 'context-stroke' }));
+      defs.appendChild(marker);
+    }
+    this.edgeSvg.appendChild(defs);
+
+    const runtimeDefs = svgEl('defs');
+    for (const id of ['runtime-arrow-forward', 'runtime-arrow-reject', 'runtime-arrow-return', 'runtime-arrow-skip']) {
+      const marker = svgEl('marker', { id, viewBox: '0 0 10 10', refX: '8.5', refY: '5', markerWidth: '7', markerHeight: '7', orient: 'auto-start-reverse', markerUnits: 'strokeWidth' });
+      marker.appendChild(svgEl('path', { d: 'M 0 0 L 10 5 L 0 10 z', fill: 'context-stroke' }));
+      runtimeDefs.appendChild(marker);
+    }
+    this.runtimeTransitionSvg.appendChild(runtimeDefs);
+
+    this.world.append(this.edgeSvg, this.runtimeTransitionSvg, this.guideSvg, this.nodeLayer, this.edgeLabelSvg);
+    this.viewport.append(this.world, this.marquee);
+    this.emptyState = el('div', 'mb-scope-empty');
+    this.emptyState.hidden = true;
+    this.emptyState.append(el('strong', '', '空子流程'), el('span', '', '拖入节点或添加开始事件'));
+    this.container.append(this.viewport, this.emptyState);
+
+    this.viewport.addEventListener('wheel', (event) => {
+      event.preventDefault();
+      if (event.ctrlKey || event.metaKey) {
+        const rect = this.viewport.getBoundingClientRect();
+        const sx = event.clientX - rect.left;
+        const sy = event.clientY - rect.top;
+        const before = this.screenToWorld(event.clientX, event.clientY);
+        const factor = event.deltaY < 0 ? 1.1 : 0.9;
+        this.zoom = quantizeZoom(this.zoom * factor);
+        this.pan.x = sx - before.x * this.zoom;
+        this.pan.y = sy - before.y * this.zoom;
+        this._applyTransform();
+        this.options.onViewportChange?.({ zoom: this.zoom, pan: { ...this.pan } });
+      } else {
+        this.pan.x -= event.deltaX;
+        this.pan.y -= event.deltaY;
+        this._applyTransform();
+        this.options.onViewportChange?.({ zoom: this.zoom, pan: { ...this.pan } });
+      }
+    }, { passive: false });
+
+    this.viewport.addEventListener('pointerdown', (event) => {
+      const target = event.target;
+      if (target.closest?.('button,input,textarea,select,.mb-quick-menu,.mb-edge-bend,.mb-edge-label-editor')) return;
+      const elementTarget = target.closest?.('.mb-node') || target.closest?.('.mb-edge-hit') || target.closest?.('.mb-edge-label-group');
+      if (elementTarget && this.interactionMode !== 'pan') return;
+      if (event.button !== 0 && event.button !== 1) return;
+      this.quickMenuNodeId = null;
+      const canvasLeftPan = event.button === 0 && (this.mode !== 'design' || this.interactionMode === 'select');
+      const panGesture = event.button === 1 || (event.button === 0 && (this._spacePressed || this.interactionMode === 'pan')) || canvasLeftPan;
+      const marqueeGesture = event.button === 0 && this.interactionMode === 'marquee' && !panGesture;
+      // Single-select and read-only modes treat a plain left press on empty
+      // canvas as a pan candidate so a click can still select the process or
+      // clear Viewer selection. Dragging starts after the 5px intent threshold.
+      this._isPanning = panGesture && !canvasLeftPan;
+      this._isMarquee = false;
+      this._panStart = {
+        clientX: event.clientX,
+        clientY: event.clientY,
+        x: this.pan.x,
+        y: this.pan.y,
+        pointerId: event.pointerId,
+        button: event.button,
+        kind: canvasLeftPan ? 'pan-candidate' : panGesture ? 'pan' : marqueeGesture ? 'marquee' : 'click',
+        mode: event.ctrlKey || event.metaKey ? 'toggle' : event.shiftKey ? 'add' : 'replace',
+        moved: false,
+      };
+      if (this._isPanning) {
+        this.viewport.setPointerCapture?.(event.pointerId);
+        this.viewport.classList.add('is-panning');
+      }
+    });
+
+    this.viewport.addEventListener('pointermove', (event) => {
+      if (!this._panStart) return;
+      const dx = event.clientX - this._panStart.clientX;
+      const dy = event.clientY - this._panStart.clientY;
+      if (this._panStart.kind === 'click') {
+        if (Math.hypot(dx, dy) >= 5) this._panStart.moved = true;
+        return;
+      }
+      if (this._panStart.kind === 'pan-candidate') {
+        if (Math.hypot(dx, dy) < 5) return;
+        this._panStart.kind = 'pan';
+      }
+      if (this._panStart.kind === 'marquee') {
+        if (!this._isMarquee && Math.hypot(dx, dy) < 5) return;
+        if (!this._isMarquee) {
+          this._isMarquee = true;
+          this.viewport.setPointerCapture?.(event.pointerId);
+          this.viewport.classList.add('is-selecting');
+          this.marquee.hidden = false;
+        }
+        const rect = this.viewport.getBoundingClientRect();
+        const left = Math.min(this._panStart.clientX, event.clientX) - rect.left;
+        const top = Math.min(this._panStart.clientY, event.clientY) - rect.top;
+        this.marquee.style.left = `${left}px`;
+        this.marquee.style.top = `${top}px`;
+        this.marquee.style.width = `${Math.abs(dx)}px`;
+        this.marquee.style.height = `${Math.abs(dy)}px`;
+        return;
+      }
+      if (!this._isPanning) {
+        this._isPanning = true;
+        this.viewport.setPointerCapture?.(event.pointerId);
+        this.viewport.classList.add('is-panning');
+      }
+      this.pan.x = this._panStart.x + dx;
+      this.pan.y = this._panStart.y + dy;
+      this._applyTransform();
+      this.options.onViewportChange?.({ zoom: this.zoom, pan: { ...this.pan } });
+    });
+
+    const finishPan = (event) => {
+      if (!this._panStart) return;
+      const start = this._panStart;
+      const wasPanning = this._isPanning;
+      const wasMarquee = this._isMarquee;
+      const wasLeftButton = start.button === 0;
+      const pointerId = start.pointerId;
+      this._isPanning = false;
+      this._isMarquee = false;
+      this._panStart = null;
+      if (this.viewport.hasPointerCapture?.(pointerId)) this.viewport.releasePointerCapture?.(pointerId);
+      this.viewport.classList.remove('is-panning');
+      this.viewport.classList.remove('is-selecting');
+      this.marquee.hidden = true;
+      if (event.type === 'pointercancel') return;
+      if (wasMarquee) {
+        const from = this.screenToWorld(start.clientX, start.clientY);
+        const to = this.screenToWorld(event.clientX, event.clientY);
+        this.options.onMarqueeSelect?.({ x: from.x, y: from.y, width: to.x - from.x, height: to.y - from.y }, { mode: start.mode, event });
+      } else if (!wasPanning && wasLeftButton && !start.moved) this.options.onCanvasClick?.(event);
+    };
+
+    this.viewport.addEventListener('pointerup', finishPan);
+    this.viewport.addEventListener('pointercancel', finishPan);
+  }
+
+  _applyTransform() {
+    // Keep the compositor translation aligned to physical pixels. Fractional
+    // pan values plus a transformed HTML layer are a common source of soft
+    // text and 1px borders, especially after fit-to-view.
+    const dpr = typeof window === 'undefined' ? 1 : (window.devicePixelRatio || 1);
+    this.pan.x = Math.round(this.pan.x * dpr) / dpr;
+    this.pan.y = Math.round(this.pan.y * dpr) / dpr;
+    this.world.style.transform = `translate(${this.pan.x}px, ${this.pan.y}px) scale(${this.zoom})`;
+    this.viewport.classList.toggle('is-low-detail', this.zoom < 0.7);
+    this.viewport.classList.toggle('is-overview', this.zoom < 0.6);
+
+    // The grid belongs to world coordinates as well. Moving/scaling its pattern
+    // with the viewport makes the canvas feel genuinely unbounded instead of
+    // exposing a stationary background behind a finite diagram surface.
+    const showGrid = this.model.settings?.showGrid !== false;
+    this.viewport.classList.toggle('is-grid-hidden', !showGrid);
+    const baseGrid = this.model.settings?.gridSize || 16;
+    const scaledGrid = Math.max(4, baseGrid * this.zoom);
+    const mod = (value, size) => ((value % size) + size) % size;
+    this.viewport.style.backgroundSize = `${scaledGrid}px ${scaledGrid}px`;
+    this.viewport.style.backgroundPosition = `${mod(this.pan.x, scaledGrid)}px ${mod(this.pan.y, scaledGrid)}px`;
+  }
+
+  setSpacePressed(active) {
+    this._spacePressed = Boolean(active);
+    this.viewport.classList.toggle('is-pan-ready', this._spacePressed);
+  }
+
+  setInteractionMode(mode) {
+    if (!['select', 'marquee', 'pan'].includes(mode)) return false;
+    this.interactionMode = mode;
+    this.viewport.dataset.interactionMode = mode;
+    this.render();
+    return true;
+  }
+
+  _visibleWorldBounds() {
+    const rect = this.viewport.getBoundingClientRect();
+    return {
+      left: -this.pan.x / this.zoom,
+      top: -this.pan.y / this.zoom,
+      right: (rect.width - this.pan.x) / this.zoom,
+      bottom: (rect.height - this.pan.y) / this.zoom,
+    };
+  }
+
+  _syncSceneBounds() {
+    this.sceneBounds = computeSceneBounds(this.model, this._visibleWorldBounds());
+    const bounds = this.sceneBounds;
+    for (const layer of [this.edgeSvg, this.runtimeTransitionSvg, this.guideSvg, this.edgeLabelSvg]) {
+      layer.style.left = `${bounds.left}px`;
+      layer.style.top = `${bounds.top}px`;
+      layer.style.width = `${bounds.width}px`;
+      layer.style.height = `${bounds.height}px`;
+      layer.setAttribute('width', String(bounds.width));
+      layer.setAttribute('height', String(bounds.height));
+      layer.setAttribute('viewBox', `${bounds.left} ${bounds.top} ${bounds.width} ${bounds.height}`);
+    }
+  }
+
+  screenToWorld(clientX, clientY) {
+    const rect = this.viewport.getBoundingClientRect();
+    return {
+      x: (clientX - rect.left - this.pan.x) / this.zoom,
+      y: (clientY - rect.top - this.pan.y) / this.zoom,
+    };
+  }
+
+  openQuickMenu(nodeId) {
+    if (this.mode !== 'design' || !this.model.nodes.some((node) => node.id === nodeId)) return false;
+    this.quickMenuNodeId = nodeId;
+    this.render();
+    return true;
+  }
+
+  editEdgeName(edgeId) {
+    if (this.mode !== 'design') return false;
+    const edge = this.model.edges.find((candidate) => candidate.id === edgeId);
+    if (!edge) return false;
+    this._beginEdgeLabelEdit(edge, edgeLabelPoint(edgeWaypoints(this.model, edge)));
+    return true;
+  }
+
+  closeTransientOverlays() {
+    const hadQuickMenu = Boolean(this.quickMenuNodeId || this.nodeLayer?.querySelector?.('.mb-quick-menu'));
+    this.quickMenuNodeId = null;
+    this.nodeLayer?.querySelectorAll?.('.mb-quick-menu').forEach((node) => node.remove());
+    this.edgeLabelSvg?.querySelectorAll?.('.mb-edge-label-editor').forEach((node) => node.remove());
+    return hadQuickMenu;
+  }
+
+  setAlignmentGuides(guides = []) { this.alignmentGuides = guides; }
+  setModel(model) { this.model = model; this.render(); }
+  setMode(mode) { this.mode = mode; this.render(); }
+  setRuntime(runtime) { this.runtime = runtime; this.render(); }
+  setSelection(selection) {
+    this.selection = selection;
+    if (selection?.kind !== 'node' || selection.id !== this.quickMenuNodeId) this.quickMenuNodeId = null;
+    this.render();
+  }
+  setConnectingSource(nodeId) {
+    this.connectingSource = nodeId;
+    this.container.classList.toggle('is-connecting', Boolean(nodeId));
+    this.render();
+  }
+  getViewportState() { return { zoom: this.zoom, pan: { ...this.pan } }; }
+  setViewportState(state) {
+    if (!state) return false;
+    this.zoom = quantizeZoom(state.zoom || 1);
+    this.pan = { x: Number(state.pan?.x || 0), y: Number(state.pan?.y || 0) };
+    this._applyTransform();
+    this.options.onViewportChange?.({ zoom: this.zoom, pan: { ...this.pan } });
+    return true;
+  }
+  destroy() {
+    this._svgExportPreview?.close?.({ immediate: true });
+    this._svgExportPreview = null;
+    this._nodeContentCleanups.splice(0).forEach((cleanup) => cleanup?.());
+    this.container.innerHTML = '';
+    this.container.classList.remove('mb-diagram-host', 'is-connecting');
+    if (this._ownsThemeController) this.themeController.destroy();
+  }
+
+  setTheme(theme) { return this.themeController.setTheme(theme); }
+  setThemeMode(mode) { return this.themeController.setMode(mode); }
+  getThemeState() { return this.themeController.getState(); }
+
+  exportSvg(options = {}) {
+    return exportDiagramSvg({
+      document: this.container.ownerDocument,
+      root: this.container,
+      model: this.model,
+      visualModel: this.options.getVisualModel?.() || this.options.visualModel || this.model,
+      runtime: this.runtime,
+      runtimePresentation: this.runtimePresentation,
+      runtimeAppearance: this.options.runtimeAppearance,
+      themeController: this.themeController,
+      iconRegistry: this.iconRegistry,
+      nodeRenderers: options.nodeRenderers || this.svgExportOptions.nodeRenderers,
+      htmlNodeRenderers: this.options.nodeRenderers,
+      htmlNodeRenderer: this.options.nodeRenderer,
+      mode: this.mode,
+      label: options.label || this.svgExportOptions.label,
+    }, { ...this.svgExportOptions, ...options });
+  }
+
+  openSvgExportPreview(options = {}) {
+    if (this._svgExportPreview && !this._svgExportPreview.closed) {
+      this._svgExportPreview.focus();
+      return this._svgExportPreview;
+    }
+    this._svgExportPreview = openSvgExportPreview({
+      container: this.container,
+      title: options.previewTitle || '导出 SVG',
+      initialTheme: options.theme || 'current',
+      createArtifact: (previewOptions) => this.exportSvg({ ...options, ...previewOptions }),
+      onClose: () => { this._svgExportPreview = null; },
+      onDownload: options.onDownload,
+    });
+    return this._svgExportPreview;
+  }
+
+  zoomBy(delta) {
+    const rect = this.viewport.getBoundingClientRect();
+    const cx = rect.left + rect.width / 2;
+    const cy = rect.top + rect.height / 2;
+    const before = this.screenToWorld(cx, cy);
+    this.zoom = quantizeZoom(this.zoom * delta);
+    this.pan.x = rect.width / 2 - before.x * this.zoom;
+    this.pan.y = rect.height / 2 - before.y * this.zoom;
+    this._applyTransform();
+    this.options.onViewportChange?.({ zoom: this.zoom, pan: { ...this.pan } });
+  }
+
+  fitView(padding = 90, options = {}) {
+    if (!this.model.nodes.length) {
+      this.zoom = 1;
+      this.pan = { x: 0, y: 0 };
+      this._applyTransform();
+      this.options.onViewportChange?.({ zoom: this.zoom, pan: { ...this.pan } });
+      return;
+    }
+    const visible = this.model.nodes.filter((n) => !['group'].includes(n.type));
+    const minX = Math.min(...visible.map((n) => n.x));
+    const minY = Math.min(...visible.map((n) => n.y));
+    const maxX = Math.max(...visible.map((n) => n.x + n.width));
+    const maxY = Math.max(...visible.map((n) => n.y + n.height));
+    const boundsW = maxX - minX || 1;
+    const boundsH = maxY - minY || 1;
+    const rect = this.viewport.getBoundingClientRect();
+    const maxZoom = options.maxZoom ?? 1.15;
+    const minZoom = options.minZoom ?? 0.25;
+    const rawZoom = Math.min((rect.width - padding * 2) / boundsW, (rect.height - padding * 2) / boundsH, maxZoom);
+    let nextZoom = clamp(rawZoom, minZoom, maxZoom);
+    if (options.snapZoom !== false) nextZoom = quantizeZoom(nextZoom, options.zoomStep ?? 0.05);
+    this.zoom = clamp(nextZoom, minZoom, maxZoom);
+
+    const renderedW = boundsW * this.zoom;
+    const renderedH = boundsH * this.zoom;
+    const contentTooWide = renderedW > rect.width - padding * 2;
+    const contentTooTall = renderedH > rect.height - padding * 2;
+    this.pan.x = options.alignX === 'start' && contentTooWide
+      ? padding - minX * this.zoom
+      : (rect.width - renderedW) / 2 - minX * this.zoom;
+    this.pan.y = options.alignY === 'start' && contentTooTall
+      ? padding - minY * this.zoom
+      : (rect.height - renderedH) / 2 - minY * this.zoom;
+    this._applyTransform();
+    this.options.onViewportChange?.({ zoom: this.zoom, pan: { ...this.pan } });
+  }
+
+  fitReadable(padding = 72) {
+    // Designer should not automatically shrink a wide process to 40–60%.
+    // At that scale transformed HTML text becomes physically tiny and looks
+    // blurred. Keep a readable floor and let the user pan horizontally.
+    this.fitView(padding, { minZoom: 0.85, maxZoom: 1, alignX: 'start', snapZoom: true });
+  }
+
+  actualSize(padding = 72) {
+    if (!this.model.nodes.length) return;
+    const visible = this.model.nodes.filter((n) => !['group'].includes(n.type));
+    const minX = Math.min(...visible.map((n) => n.x));
+    const minY = Math.min(...visible.map((n) => n.y));
+    const maxX = Math.max(...visible.map((n) => n.x + n.width));
+    const maxY = Math.max(...visible.map((n) => n.y + n.height));
+    const boundsW = maxX - minX || 1;
+    const boundsH = maxY - minY || 1;
+    const rect = this.viewport.getBoundingClientRect();
+    this.zoom = 1;
+    this.pan.x = boundsW > rect.width - padding * 2
+      ? padding - minX
+      : (rect.width - boundsW) / 2 - minX;
+    this.pan.y = boundsH > rect.height - padding * 2
+      ? padding - minY
+      : (rect.height - boundsH) / 2 - minY;
+    this._applyTransform();
+    this.options.onViewportChange?.({ zoom: this.zoom, pan: { ...this.pan } });
+  }
+
+  render() {
+    const presenter = this.options.runtimePresenter || ((context) => createRuntimePresentation(context));
+    this.runtimePresentation = this.runtime
+      ? presenter({ model: this.model, runtime: this.runtime, appearance: this.options.runtimeAppearance })
+      : createRuntimePresentation({ model: this.model, runtime: null, appearance: this.options.runtimeAppearance });
+    this._syncSceneBounds();
+    this._renderEdges();
+    this._renderRuntimeTransitions();
+    this._renderGuides();
+    this._renderNodes();
+    this._applyTransform();
+    this.container.dataset.mode = this.mode;
+    if (this.emptyState) this.emptyState.hidden = this.model.nodes.length > 0 || !this.options.showEmptyState;
+  }
+
+  _renderGuides() {
+    this.guideSvg.replaceChildren();
+    if (this.model.settings?.alignmentGuides === false) return;
+    const bounds = this.sceneBounds || computeSceneBounds(this.model);
+    for (const guide of this.alignmentGuides || []) {
+      const attrs = guide.orientation === 'vertical'
+        ? { x1: guide.position, y1: bounds.top, x2: guide.position, y2: bounds.bottom }
+        : { x1: bounds.left, y1: guide.position, x2: bounds.right, y2: guide.position };
+      this.guideSvg.appendChild(svgEl('line', { ...attrs, class: `mb-alignment-guide kind-${guide.kind || 'center'}` }));
+    }
+  }
+
+  _renderRuntimeTransitions() {
+    const defs = this.runtimeTransitionSvg.querySelector('defs');
+    this.runtimeTransitionSvg.replaceChildren(defs);
+    if (this.mode !== 'instance') return;
+    const transitions = this.runtimePresentation.getTransitions()
+      .filter((item) => ['reject', 'return'].includes(item.type) && item.visible)
+      .sort((a, b) => String(a.occurredAt || '').localeCompare(String(b.occurredAt || '')) || String(a.id).localeCompare(String(b.id)));
+    const occupiedRuntimeRoutes = [];
+    const labelObstacles = (this._edgeLabelObstacles || []).map((bounds) => ({
+      x: bounds.x,
+      y: bounds.y,
+      width: bounds.width,
+      height: bounds.height,
+    }));
+    transitions.forEach((transition) => {
+      const metrics = edgeLabelMetrics(transition.label, { maxWidth: 176 });
+      const route = routeRuntimeTransition(this.model, transition, {
+        occupiedRoutes: occupiedRuntimeRoutes,
+        obstacles: labelObstacles,
+        labelSize: { width: metrics.width, height: metrics.height },
+      });
+      if (!route) return;
+      const points = route.points;
+      occupiedRuntimeRoutes.push(points);
+      labelObstacles.push({
+        x: route.labelPoint.x - metrics.width / 2,
+        y: route.labelPoint.y - metrics.height / 2,
+        width: metrics.width,
+        height: metrics.height,
+      });
+      const group = svgEl('g', {
+        class: `mb-runtime-transition type-${transition.type} ${transition.latest ? 'is-latest' : 'is-history'}`,
+        'data-transition-id': transition.id,
+        role: 'button',
+        tabindex: '0',
+        'aria-label': `${transition.label}${transition.operator ? `，操作人：${transition.operator}` : ''}`,
+      });
+      applyRuntimeTone(group, this.options.runtimeAppearance?.resolveTransition(transition).tone);
+      const corner = this.model.settings?.cornerRadius ?? 14;
+      const routeStyle = this.model.settings?.edgeStyle || 'rounded';
+      const pathData = routePathData(points, routeStyle, corner);
+      group.appendChild(svgEl('path', {
+        d: pathData,
+        class: 'mb-runtime-transition-hit',
+        fill: 'none',
+      }));
+      group.appendChild(svgEl('path', {
+        d: pathData,
+        class: 'mb-runtime-transition-path',
+        fill: 'none',
+        'marker-end': `url(#runtime-arrow-${transition.type})`,
+      }));
+      const labelX = route.labelPoint.x;
+      const labelY = route.labelPoint.y;
+      const label = svgEl('g', { class: 'mb-runtime-transition-label', transform: `translate(${labelX - metrics.width / 2} ${labelY - metrics.height / 2})` });
+      label.append(
+        svgEl('rect', { x: 0, y: 0, width: metrics.width, height: metrics.height, rx: metrics.radius, ry: metrics.radius }),
+        svgEl('text', { x: metrics.width / 2, y: metrics.paddingY + metrics.lineHeight * 0.74, 'text-anchor': 'middle' }),
+      );
+      label.querySelector('text').textContent = transition.label;
+      group.appendChild(label);
+      group.addEventListener('click', (event) => {
+        event.stopPropagation();
+        this.options.onRuntimeTransitionClick?.(transition, event);
+      });
+      group.addEventListener('keydown', (event) => {
+        if (!['Enter', ' '].includes(event.key)) return;
+        event.preventDefault();
+        event.stopPropagation();
+        this.options.onRuntimeTransitionClick?.(transition, event);
+      });
+      this.runtimeTransitionSvg.appendChild(group);
+    });
+  }
+
+  _renderEdges() {
+    const defs = this.edgeSvg.querySelector('defs');
+    this.edgeSvg.replaceChildren(defs);
+    this.edgeLabelSvg.replaceChildren();
+    const nodeObstacles = this.model.nodes.map((node) => ({
+      x: node.x,
+      y: node.y,
+      width: node.width,
+      height: node.height,
+    }));
+    const labelObstacles = [];
+
+    for (const edge of this.model.edges) {
+      const points = edgeWaypoints(this.model, edge);
+      if (points.length < 2) continue;
+      const corner = edge.cornerRadius ?? this.model.settings?.cornerRadius ?? 14;
+      const routeStyle = edge.routeStyle || this.model.settings?.edgeStyle || 'rounded';
+      const pathData = routePathData(points, routeStyle, corner);
+
+      const edgeStatus = this.runtimePresentation.getEdge(edge.id).status;
+      const selected = this.selection?.kind === 'edge' && this.selection.id === edge.id;
+      const classes = [
+        'mb-edge-group', `status-${edgeStatus}`, selected ? 'is-selected' : '', `type-${edge.type || 'sequenceFlow'}`,
+      ].filter(Boolean).join(' ');
+      const group = svgEl('g', { class: classes, 'data-edge-id': edge.id });
+      if (this.mode === 'instance') applyRuntimeTone(group, this.options.runtimeAppearance?.resolveStatus(edgeStatus));
+      const pathAttrs = {
+        d: pathData,
+        class: 'mb-edge-path',
+        fill: 'none',
+      };
+      if ((edge.type || 'sequenceFlow') === 'sequenceFlow') pathAttrs['marker-end'] = `url(#arrow${edgeStatus === 'idle' ? '' : `-${edgeStatus}`})`;
+      const path = svgEl('path', pathAttrs);
+      const hit = svgEl('path', { d: pathData, class: 'mb-edge-hit', fill: 'none' });
+      let labelPosition = edgeLabelPoint(points);
+      hit.addEventListener('click', (event) => {
+        event.stopPropagation();
+        this.options.onEdgeClick?.(edge, event);
+      });
+      hit.addEventListener('dblclick', (event) => {
+        event.stopPropagation();
+        this._beginEdgeLabelEdit(edge, labelPosition);
+      });
+      group.append(path, hit);
+
+      const sourceNode = this.model.nodes.find((node) => node.id === edge.source);
+      const shouldShowPlaceholder = selected && sourceNode && NODE_DEFINITIONS[sourceNode.type]?.kind === 'gateway';
+      if (edge.name || shouldShowPlaceholder) {
+        const textValue = edge.name || '设置分支名称';
+        const metrics = edgeLabelMetrics(textValue);
+        const pos = edgeLabelPlacement(points, metrics, {
+          obstacles: [...nodeObstacles, ...labelObstacles],
+          endClearance: (edge.type || 'sequenceFlow') === 'sequenceFlow' ? 16 : 6,
+        });
+        labelPosition = pos;
+        const { width, height, radius, paddingY, lineHeight, lines } = metrics;
+        const labelClasses = [
+          'mb-edge-label-group',
+          edge.name ? '' : 'is-placeholder',
+          selected ? 'is-selected' : '',
+        ].filter(Boolean).join(' ');
+        const label = svgEl('g', { class: labelClasses, 'data-edge-id': edge.id, transform: `translate(${pos.x - width / 2} ${pos.y - height / 2})` });
+        label.appendChild(svgEl('rect', { x: 0, y: 0, width, height, rx: radius, ry: radius, class: 'mb-edge-label-bg' }));
+        const text = svgEl('text', { 'text-anchor': 'middle', class: 'mb-edge-label' });
+        lines.forEach((line, index) => {
+          const tspan = svgEl('tspan', {
+            x: width / 2,
+            y: paddingY + lineHeight * (index + 0.74),
+            class: 'mb-edge-label-line',
+          });
+          tspan.textContent = line || ' ';
+          text.appendChild(tspan);
+        });
+        label.appendChild(text);
+        label.addEventListener('click', (event) => {
+          event.stopPropagation();
+          this.options.onEdgeClick?.(edge, event);
+        });
+        label.addEventListener('dblclick', (event) => {
+          event.stopPropagation();
+          this._beginEdgeLabelEdit(edge, pos);
+        });
+        this.edgeLabelSvg.appendChild(label);
+        labelObstacles.push(pos.bounds);
+      }
+
+      this.edgeSvg.appendChild(group);
+
+      if (selected && this.mode === 'design') {
+        const handlePoints = edge.waypoints?.length ? edge.waypoints : points;
+        for (let index = 1; index < handlePoints.length - 1; index += 1) {
+          const point = handlePoints[index];
+          const handle = svgEl('circle', { cx: point.x, cy: point.y, r: 5.5, class: 'mb-edge-bend', 'data-index': index });
+          handle.addEventListener('pointerdown', (event) => {
+            event.stopPropagation();
+            event.preventDefault();
+            this.options.onEdgeBendPointerDown?.(edge, index, handlePoints.map((p) => ({ ...p })), event);
+          });
+          this.edgeSvg.appendChild(handle);
+        }
+      }
+    }
+    this._edgeLabelObstacles = labelObstacles;
+  }
+
+  _beginEdgeLabelEdit(edge, pos) {
+    if (this.mode !== 'design') return;
+    this.edgeLabelSvg.querySelectorAll('.mb-edge-label-editor').forEach((node) => node.remove());
+    const foreign = svgEl('foreignObject', { x: pos.x - 84, y: pos.y - 18, width: 168, height: 36, class: 'mb-edge-label-editor' });
+    const wrap = document.createElementNS(XHTML_NS, 'div');
+    wrap.className = 'mb-edge-label-editor-wrap';
+    const input = document.createElementNS(XHTML_NS, 'input');
+    input.className = 'mb-edge-label-input';
+    input.value = edge.name || '';
+    input.placeholder = '输入分支名称';
+    wrap.appendChild(input);
+    foreign.appendChild(wrap);
+    this.edgeLabelSvg.appendChild(foreign);
+    const commit = () => {
+      if (!foreign.isConnected) return;
+      const value = input.value.trim();
+      foreign.remove();
+      this.options.onEdgeNameChange?.(edge, value);
+    };
+    input.addEventListener('keydown', (event) => {
+      if (event.key === 'Enter') { event.preventDefault(); commit(); }
+      if (event.key === 'Escape') { event.preventDefault(); foreign.remove(); }
+    });
+    input.addEventListener('blur', commit, { once: true });
+    requestAnimationFrame(() => { input.focus(); input.select(); });
+  }
+
+  _renderNodes() {
+    this._nodeContentCleanups.splice(0).forEach((cleanup) => cleanup?.());
+    this.nodeLayer.innerHTML = '';
+    const zOrder = { participant: 0, lane: 1, group: 2, container: 3, data: 4, dataStore: 4, annotation: 4, task: 5, gateway: 6, event: 7, boundary: 8 };
+    const nodes = [...this.model.nodes].sort((a, b) => (zOrder[NODE_DEFINITIONS[a.type]?.kind] ?? 5) - (zOrder[NODE_DEFINITIONS[b.type]?.kind] ?? 5));
+
+    for (const node of nodes) {
+      const def = NODE_DEFINITIONS[node.type] || NODE_DEFINITIONS.generic;
+      const runtimeState = this.runtimePresentation.getNode(node.id);
+      const selected = (this.selection?.kind === 'node' && this.selection.id === node.id)
+        || (this.selection?.kind === 'multi' && this.selection.items?.some((item) => item.kind === 'node' && item.id === node.id));
+      const connectingSourceNode = this.connectingSource
+        ? this.model.nodes.find((candidate) => candidate.id === this.connectingSource)
+        : null;
+      const isConnectingSource = this.connectingSource === node.id;
+      const isConnectTarget = Boolean(
+        connectingSourceNode
+        && !isConnectingSource
+        && this.options.canConnect?.(connectingSourceNode, node)
+      );
+      const swimlaneLabelPlacement = ['participant', 'lane'].includes(def.kind)
+        ? resolveSwimlaneLabelPlacement(this.model, node)
+        : '';
+      const classes = [
+        'mb-node', `mb-node-${def.kind}`, `mb-node-type-${node.type}`, `status-${runtimeState.pathStatus || runtimeState.status}`,
+        swimlaneLabelPlacement ? `mb-swimlane-label-${swimlaneLabelPlacement}` : '',
+        selected ? 'is-selected' : '',
+        isConnectingSource ? 'is-connecting-source' : '',
+        isConnectTarget ? 'is-connect-target' : '',
+      ].filter(Boolean).join(' ');
+
+      const nodeEl = el('div', classes);
+      nodeEl.dataset.nodeId = node.id;
+      if (this.mode === 'instance') applyRuntimeTone(nodeEl, this.options.runtimeAppearance?.resolveStatus(runtimeState.status));
+      nodeEl.style.left = `${node.x}px`;
+      nodeEl.style.top = `${node.y}px`;
+      nodeEl.style.width = `${node.width}px`;
+      nodeEl.style.height = `${node.height}px`;
+      nodeEl.tabIndex = 0;
+
+      const visual = this._resolveNodeVisual(node);
+      this._renderNodeShape(nodeEl, node, def, runtimeState, visual);
+      if (['task', 'container'].includes(def.kind)) addActivityMarkers(nodeEl, visual, this.iconRegistry);
+
+      if (this.mode === 'design') this._renderDesignControls(nodeEl, node, def, selected && this.selection?.kind !== 'multi' && this.interactionMode !== 'pan');
+
+      nodeEl.addEventListener('click', (event) => {
+        event.stopPropagation();
+        this.options.onNodeClick?.(node, event);
+      });
+      nodeEl.addEventListener('pointerdown', (event) => {
+        if (event.target.closest?.('button,input,.mb-quick-menu')) return;
+        // In connect-existing mode a target click must never accidentally start
+        // dragging the target. This also makes left/right/up/down targets behave
+        // identically instead of depending on the target's visible port.
+        if (this.connectingSource && node.id !== this.connectingSource) {
+          event.preventDefault();
+          return;
+        }
+        this.options.onNodePointerDown?.(node, event);
+      });
+      nodeEl.addEventListener('dblclick', (event) => {
+        event.stopPropagation();
+        this.options.onNodeDoubleClick?.(node, event);
+      });
+      this.nodeLayer.appendChild(nodeEl);
+    }
+
+    if (this.mode === 'design' && this.quickMenuNodeId) this._renderQuickMenu();
+  }
+
+  _renderNodeShape(nodeEl, node, def, runtimeState, visual) {
+    if (def.kind === 'event' || def.kind === 'boundary') {
+      const shape = el('div', 'mb-event-shape');
+      shape.dataset.stage = def.eventStage || 'intermediate';
+      shape.dataset.role = def.eventRole || '';
+      if (def.kind === 'boundary' && node.properties?.cancelActivity === false) shape.classList.add('is-noninterrupting');
+      const glyph = el('span', 'mb-event-glyph');
+      if (!this._renderCustomNodeContent(glyph, node, def, runtimeState, visual)) {
+        const iconNode = visual.iconId
+          ? createIconElement(this.iconRegistry.resolve(visual.iconId, null), { className: 'mb-node-svg-icon', title: def.label })
+          : null;
+        if (iconNode) glyph.appendChild(iconNode);
+      }
+      shape.appendChild(glyph);
+      nodeEl.appendChild(shape);
+      nodeEl.appendChild(el('div', 'mb-node-floating-label', node.name));
+      return;
+    }
+
+    if (def.kind === 'gateway') {
+      const shape = el('div', 'mb-gateway-shape');
+      const symbol = el('span', 'mb-gateway-symbol');
+      if (!this._renderCustomNodeContent(symbol, node, def, runtimeState, visual)) {
+        const iconNode = visual.iconId
+          ? createIconElement(this.iconRegistry.resolve(visual.iconId, null), { className: 'mb-node-svg-icon', title: def.label })
+          : null;
+        if (iconNode) symbol.appendChild(iconNode);
+      }
+      shape.appendChild(symbol);
+      nodeEl.appendChild(shape);
+      if (this.mode === 'design' && node.type === 'parallelGateway') {
+        const role = resolveGatewayRole(this.model, node);
+        if (!role.topologyComplete) {
+          const marker = role.effective === 'Diverging' ? '分' : role.effective === 'Converging' ? '汇' : '?';
+          const badge = el('span', `mb-gateway-role-badge is-${role.status}`, marker);
+          badge.dataset.gatewayRole = role.effective;
+          badge.setAttribute('aria-hidden', 'true');
+          const statusLabel = { incomplete: '结构未完成', conflict: '结构冲突', ambiguous: '角色待判断', valid: '结构正常' }[role.status];
+          badge.title = `${role.effective === 'Diverging' ? '并行分支' : role.effective === 'Converging' ? '并行汇聚' : '角色待判断'} · ${statusLabel}`;
+          nodeEl.appendChild(badge);
+        }
+      }
+      nodeEl.appendChild(el('div', 'mb-node-floating-label', node.name));
+      return;
+    }
+
+    if (def.kind === 'data') {
+      const page = el('div', 'mb-data-object-shape');
+      page.appendChild(el('span', 'mb-data-object-lines', '≡'));
+      nodeEl.appendChild(page);
+      nodeEl.appendChild(el('div', 'mb-node-floating-label', node.name));
+      return;
+    }
+
+    if (def.kind === 'dataStore') {
+      const store = el('div', 'mb-data-store-shape');
+      store.appendChild(el('span', '', '≡'));
+      nodeEl.appendChild(store);
+      nodeEl.appendChild(el('div', 'mb-node-floating-label', node.name));
+      return;
+    }
+
+    if (def.kind === 'annotation') {
+      const annotation = el('div', 'mb-annotation-shape');
+      annotation.appendChild(el('div', 'mb-annotation-text', node.properties?.text || node.name || '说明'));
+      nodeEl.appendChild(annotation);
+      return;
+    }
+
+    if (def.kind === 'group') {
+      nodeEl.appendChild(el('div', 'mb-container-caption', node.properties?.categoryValue || node.name || '分组'));
+      return;
+    }
+
+    if (def.kind === 'participant' || def.kind === 'lane') {
+      const rail = el('div', 'mb-swimlane-rail');
+      rail.appendChild(el('div', 'mb-swimlane-title', node.name || def.label));
+      nodeEl.appendChild(rail);
+      return;
+    }
+
+    const accent = el('div', 'mb-node-accent');
+    nodeEl.appendChild(accent);
+    const customHost = el('div', 'mb-node-custom-content');
+    if (this._renderCustomNodeContent(customHost, node, def, runtimeState, visual)) {
+      nodeEl.appendChild(customHost);
+      return;
+    }
+    const header = el('div', 'mb-node-header');
+    const icon = visual.iconId ? el('span', 'mb-node-icon') : null;
+    const iconNode = visual.iconId
+      ? createIconElement(this.iconRegistry.resolve(visual.iconId, null), { className: 'mb-node-svg-icon', title: def.label })
+      : null;
+    if (iconNode) icon.appendChild(iconNode);
+    const titleWrap = el('div', `mb-node-title-wrap${this.mode === 'instance' ? ' mb-node-runtime-copy' : ''}`);
+    if (this.mode === 'instance') {
+      const requestDetails = (event) => {
+        event.stopPropagation();
+        this.options.onRuntimeDetailsRequest?.({ node, presentation: runtimeState, anchor: event.currentTarget, event });
+      };
+      titleWrap.appendChild(el('div', 'mb-node-title', node.name || def.label));
+      const status = runtimeState.hasDetails ? el('button', `mb-runtime-status-icon status-${runtimeState.status}`) : el('span', `mb-runtime-status-icon status-${runtimeState.status}`);
+      status.appendChild(uiIconElement(this.iconRegistry, runtimeStatusIconId(runtimeState), 'nova-icon nova-icon-sm'));
+      status.title = runtimeState.statusLabel;
+      status.dataset.runtimeStatus = runtimeState.status;
+      applyRuntimeTone(status, this.options.runtimeAppearance?.resolveStatus(runtimeState.status));
+      if (status instanceof HTMLButtonElement) {
+        status.type = 'button';
+        status.setAttribute('aria-label', `查看${node.name || def.label}审批详情，当前状态：${runtimeState.statusLabel}`);
+        status.addEventListener('click', requestDetails);
+      } else {
+        status.setAttribute('aria-label', runtimeState.statusLabel);
+      }
+      nodeEl.appendChild(status);
+      if (runtimeState.summary) {
+        const summary = runtimeState.hasDetails ? el('button', 'mb-node-subtitle mb-runtime-summary', runtimeState.summary) : el('div', 'mb-node-subtitle mb-runtime-summary', runtimeState.summary);
+        summary.title = runtimeState.fullSummary || runtimeState.summary;
+        summary.setAttribute('aria-label', runtimeState.fullSummary || runtimeState.summary);
+        if (summary instanceof HTMLButtonElement) {
+          summary.type = 'button';
+          summary.addEventListener('click', requestDetails);
+        }
+        titleWrap.appendChild(summary);
+      }
+      if (runtimeState.actionSummary) {
+        const action = runtimeState.hasDetails
+          ? el('button', 'mb-runtime-action-summary', runtimeState.actionSummary)
+          : el('div', 'mb-runtime-action-summary', runtimeState.actionSummary);
+        action.title = runtimeState.actionSummary;
+        action.setAttribute('aria-label', runtimeState.actionSummary);
+        if (action instanceof HTMLButtonElement) {
+          action.type = 'button';
+          action.addEventListener('click', requestDetails);
+        }
+        titleWrap.appendChild(action);
+      }
+    } else {
+      titleWrap.appendChild(el('div', 'mb-node-title', node.name || def.label));
+      titleWrap.appendChild(el('div', 'mb-node-subtitle', displaySubtitle(node)));
+    }
+    if (icon) header.append(icon);
+    header.append(titleWrap);
+    nodeEl.appendChild(header);
+  }
+
+  _resolveNodeVisual(node, surface = this.mode === 'instance' ? 'viewer' : 'canvas') {
+    const visualModel = this.options.getVisualModel?.() || this.options.visualModel || this.model;
+    return resolveNodeVisual(node, { surface, model: visualModel });
+  }
+
+  _renderCustomNodeContent(container, node, definition, runtimeState, visual = this._resolveNodeVisual(node)) {
+    const renderers = this.options.nodeRenderers || {};
+    const renderer = renderers[node.type] || renderers[definition.kind] || this.options.nodeRenderer;
+    if (typeof renderer !== 'function') return false;
+    const cleanup = renderer({
+      container,
+      node,
+      definition,
+      runtimeState,
+      runtimePresentation: runtimeState,
+      visual,
+      semanticIconId: visual.iconId,
+      mode: this.mode,
+      model: this.model,
+      themeState: this.themeController.getState(),
+      runtimeAppearance: this.options.runtimeAppearance || null,
+      select: () => this.options.onNodeClick?.(node),
+      openRuntimeDetails: (anchor = container) => this.options.onRuntimeDetailsRequest?.({ node, presentation: runtimeState, anchor }),
+      renderSemanticIcon: (target = container, options = {}) => {
+        if (!visual.iconId || !target?.appendChild) return null;
+        const iconNode = createIconElement(this.iconRegistry.resolve(visual.iconId, null), {
+          className: options.className || 'mb-node-svg-icon',
+          title: options.title ?? definition.label,
+        });
+        if (iconNode) target.appendChild(iconNode);
+        return iconNode;
+      },
+    });
+    if (typeof cleanup === 'function') this._nodeContentCleanups.push(cleanup);
+    return true;
+  }
+
+  _renderDesignControls(nodeEl, node, def, selected) {
+    const flowKinds = new Set(['event', 'boundary', 'task', 'container', 'gateway']);
+    const canIncoming = flowKinds.has(def.kind) && def.kind !== 'boundary' && !['start'].includes(def.eventStage);
+    const canOutgoing = flowKinds.has(def.kind) && !['end'].includes(def.eventStage);
+    const sourceNode = this.connectingSource
+      ? this.model.nodes.find((candidate) => candidate.id === this.connectingSource)
+      : null;
+    const isConnectSource = this.connectingSource === node.id;
+    const isConnectTarget = Boolean(
+      sourceNode
+      && !isConnectSource
+      && canIncoming
+      && this.options.canConnect?.(sourceNode, node)
+    );
+
+    const appendPort = (side, { target = false, onClick } = {}) => {
+      const port = el('button', `mb-port mb-port-${side}${target ? ' mb-port-target' : ''}`);
+      port.type = 'button';
+      port.title = target ? '连接到此节点' : (side === 'right' ? '创建连接' : '输入连接点');
+      port.tabIndex = -1;
+      port.addEventListener('pointerdown', (event) => {
+        event.stopPropagation();
+        if (target) event.preventDefault();
+      });
+      if (onClick) {
+        port.addEventListener('click', (event) => {
+          event.preventDefault();
+          event.stopPropagation();
+          onClick(event);
+        });
+      }
+      nodeEl.appendChild(port);
+      return port;
+    };
+
+    if (this.connectingSource && !isConnectSource) {
+      // While choosing an existing target, expose four equivalent target handles.
+      // The user does not need to reason about source/target sides; the router will
+      // pick the correct anchor after the target is selected.
+      if (isConnectTarget) {
+        const complete = (event) => this.options.onNodeClick?.(node, event);
+        appendPort('left', { target: true, onClick: complete });
+        appendPort('right', { target: true, onClick: complete });
+        appendPort('top', { target: true, onClick: complete });
+        appendPort('bottom', { target: true, onClick: complete });
+      }
+      return;
+    }
+
+    if (canIncoming) appendPort('left');
+    if (canOutgoing) {
+      appendPort('right', { onClick: (event) => this.options.onStartConnect?.(node, event) });
+    }
+
+    if (def.kind === 'lane' && node.containerId) {
+      const siblings = this.model.nodes
+        .filter((candidate) => candidate.type === 'lane' && candidate.containerId === node.containerId)
+        .sort((a, b) => a.y - b.y || a.id.localeCompare(b.id));
+      if (siblings.at(-1)?.id !== node.id) {
+        const divider = el('span', 'mb-lane-divider');
+        divider.title = '调整相邻泳道高度';
+        divider.addEventListener('pointerdown', (event) => {
+          event.preventDefault();
+          event.stopPropagation();
+          this.options.onLaneDividerPointerDown?.(node, event);
+        });
+        nodeEl.appendChild(divider);
+      }
+    }
+    if (!selected) return;
+    const resizeKinds = new Set(['group', 'participant', 'lane']);
+    if (resizeKinds.has(def.kind) && !(def.kind === 'lane' && node.containerId)) {
+      for (const handle of ['nw', 'n', 'ne', 'e', 'se', 's', 'sw', 'w']) {
+        const resize = el('span', `mb-resize-handle mb-resize-${handle}`);
+        resize.dataset.resizeHandle = handle;
+        resize.setAttribute('aria-hidden', 'true');
+        resize.addEventListener('pointerdown', (event) => {
+          event.preventDefault();
+          event.stopPropagation();
+          this.options.onNodeResizePointerDown?.(node, handle, event);
+        });
+        nodeEl.appendChild(resize);
+      }
+    }
+    const actions = el('div', 'mb-node-actions');
+    if (def.kind === 'container' && this.options.onEnterSubProcess) {
+      const enter = el('button', 'mb-action-btn mb-action-enter');
+      enter.type = 'button';
+      enter.title = '进入子流程';
+      enter.setAttribute('aria-label', '进入子流程');
+      enter.appendChild(uiIconElement(this.iconRegistry, 'ui.enterScope'));
+      enter.addEventListener('pointerdown', (event) => event.stopPropagation());
+      enter.addEventListener('click', (event) => {
+        event.stopPropagation();
+        this.options.onEnterSubProcess?.(node, event);
+      });
+      actions.appendChild(enter);
+    }
+    if (canOutgoing) {
+      const quick = el('button', 'mb-action-btn mb-action-primary');
+      quick.type = 'button';
+      quick.title = '快捷添加下一节点';
+      quick.setAttribute('aria-label', '快捷添加下一节点');
+      quick.appendChild(uiIconElement(this.iconRegistry, 'ui.add'));
+      quick.addEventListener('pointerdown', (event) => event.stopPropagation());
+      quick.addEventListener('click', (event) => {
+        event.stopPropagation();
+        this.quickMenuNodeId = this.quickMenuNodeId === node.id ? null : node.id;
+        this.render();
+      });
+      actions.appendChild(quick);
+
+      const connect = el('button', `mb-action-btn mb-action-connect${isConnectSource ? ' is-active' : ''}`);
+      connect.type = 'button';
+      connect.title = isConnectSource ? '取消连接模式（Esc）' : '连接到已有节点';
+      connect.setAttribute('aria-label', connect.title);
+      connect.appendChild(uiIconElement(this.iconRegistry, 'ui.connect'));
+      connect.setAttribute('aria-pressed', isConnectSource ? 'true' : 'false');
+      connect.addEventListener('pointerdown', (event) => event.stopPropagation());
+      connect.addEventListener('click', (event) => {
+        event.stopPropagation();
+        this.options.onStartConnect?.(node, event);
+      });
+      actions.appendChild(connect);
+    }
+    const isGroup = def.kind === 'group';
+    const remove = el('button', 'mb-action-btn mb-action-danger');
+    remove.type = 'button';
+    remove.title = isGroup ? '取消分组' : '删除节点';
+    remove.setAttribute('aria-label', remove.title);
+    remove.appendChild(uiIconElement(this.iconRegistry, 'ui.delete'));
+    remove.addEventListener('pointerdown', (event) => event.stopPropagation());
+    remove.addEventListener('click', (event) => {
+      event.stopPropagation();
+      if (isGroup) this.options.onUngroup?.(node, event);
+      else this.options.onDeleteNode?.(node, event);
+    });
+    actions.appendChild(remove);
+    nodeEl.appendChild(actions);
+
+    if (isConnectSource) {
+      const hint = el('div', 'mb-connect-mode-hint', '选择目标节点 · Esc 取消');
+      nodeEl.appendChild(hint);
+    }
+  }
+
+  _renderQuickMenu() {
+    const source = this.model.nodes.find((node) => node.id === this.quickMenuNodeId);
+    if (!source) return;
+    const menu = el('div', 'mb-quick-menu');
+    menu.style.left = `${source.x + source.width + 58}px`;
+    menu.style.top = `${source.y + source.height / 2 - 206}px`;
+    menu.addEventListener('pointerdown', (event) => event.stopPropagation());
+    menu.addEventListener('click', (event) => event.stopPropagation());
+
+    const head = el('div', 'mb-quick-menu-head');
+    const headText = el('div');
+    headText.appendChild(el('div', 'mb-quick-menu-title', '添加下一节点'));
+    headText.appendChild(el('div', 'mb-quick-menu-subtitle', '自动连线并智能摆放'));
+    const close = el('button', 'mb-quick-menu-close');
+    close.type = 'button';
+    close.title = '关闭';
+    close.setAttribute('aria-label', '关闭');
+    close.appendChild(uiIconElement(this.iconRegistry, 'ui.close'));
+    close.addEventListener('click', () => { this.quickMenuNodeId = null; this.render(); });
+    head.append(headText, close);
+    menu.appendChild(head);
+
+    const search = el('input', 'mb-quick-menu-search');
+    search.placeholder = '搜索 BPMN 节点…';
+    menu.appendChild(search);
+
+    const body = el('div', 'mb-quick-menu-body');
+    const groups = [
+      PALETTE_GROUPS.find((group) => group.id === 'favorites'),
+      PALETTE_GROUPS.find((group) => group.id === 'tasks'),
+      PALETTE_GROUPS.find((group) => group.id === 'gateways'),
+      PALETTE_GROUPS.find((group) => group.id === 'intermediateEvents'),
+      PALETTE_GROUPS.find((group) => group.id === 'endEvents'),
+      PALETTE_GROUPS.find((group) => group.id === 'activities'),
+    ].filter(Boolean);
+
+    for (const group of groups) {
+      const section = el('div', 'mb-quick-menu-section');
+      section.dataset.group = group.id;
+      section.appendChild(el('div', 'mb-quick-menu-section-title', group.label));
+      const grid = el('div', 'mb-quick-menu-grid');
+      const quickItems = group.types.flatMap((type) => type === 'parallelGateway'
+        ? [PARALLEL_GATEWAY_PRESETS.diverging, PARALLEL_GATEWAY_PRESETS.converging]
+        : [{ id: type, label: NODE_DEFINITIONS[type]?.label, iconId: resolveNodeVisual(type, { surface: 'palette' }).iconId, nodeType: type, preset: undefined }]);
+      for (const quickItem of quickItems) {
+        const type = quickItem.nodeType;
+        if (type === 'startEvent') continue;
+        const def = NODE_DEFINITIONS[type];
+        if (!def || this.options.canCreateNodeType?.(type) === false) continue;
+        const item = el('button', 'mb-quick-menu-item');
+        item.dataset.search = `${quickItem.id} ${type} ${quickItem.label}`.toLowerCase();
+        const miniIcon = el('span', `mb-mini-type mb-mini-kind-${def.kind}`);
+        const miniSvg = createIconElement(this.iconRegistry.resolve(quickItem.iconId || resolveNodeVisual(type, { surface: 'palette' }).iconId, null), { className: 'mb-node-svg-icon', title: quickItem.label });
+        if (miniSvg) miniIcon.appendChild(miniSvg);
+        item.appendChild(miniIcon);
+        item.appendChild(el('span', 'mb-quick-menu-item-text', quickItem.label));
+        item.addEventListener('click', () => {
+          this.quickMenuNodeId = null;
+          this.options.onQuickAdd?.(source, type, quickItem.preset);
+        });
+        grid.appendChild(item);
+      }
+      section.appendChild(grid);
+      body.appendChild(section);
+    }
+    menu.appendChild(body);
+
+    search.addEventListener('input', () => {
+      const q = search.value.trim().toLowerCase();
+      body.querySelectorAll('.mb-quick-menu-item').forEach((item) => {
+        item.classList.toggle('is-hidden', q && !item.dataset.search.includes(q));
+      });
+      body.querySelectorAll('.mb-quick-menu-section').forEach((section) => {
+        const visible = [...section.querySelectorAll('.mb-quick-menu-item')].some((item) => !item.classList.contains('is-hidden'));
+        section.classList.toggle('is-hidden', !visible);
+      });
+    });
+
+    this.nodeLayer.appendChild(menu);
+    requestAnimationFrame(() => search.focus());
+  }
+}