@bpmn-nova/studio 0.3.3-preview → 0.3.5-preview

package/dist/modules/export-svg/render.js

@@ -1,6 +1,7 @@
 import { NODE_DEFINITIONS, edgeWaypoints, roundedPath, routeRuntimeTransition, smoothPath } from '../core/index.js';
 import { createDefaultIconRegistry, resolveNodeVisual } from '../icons/index.js';
 import { resolveNodeSubtitle, supportsNodeSubtitle } from '../node-presentation/index.js';
+import { resolveNodeGeometry, resolvePresentationWaypoints } from '../node-geometry/index.js';
 import { createRuntimePresentation } from '../runtime/index.js';
 import { createRuntimeAppearance } from '../theme/index.js';
 
@@ -294,9 +295,11 @@ function addDefinitions(document, svg, theme) {
     if (/^[a-z][a-z0-9-]{0,47}$/.test(name)) markers.set(name, tone(theme, name).strong);
   }
   for (const [id, color] of markers) {
-    const marker = svgElement(document, 'marker', { id: `nova-arrow-${id}`, viewBox: '0 0 10 10', refX: 8.5, refY: 5, markerWidth: 7, markerHeight: 7, orient: 'auto-start-reverse', markerUnits: 'strokeWidth' });
-    marker.appendChild(svgElement(document, 'path', { d: 'M 0 0 L 10 5 L 0 10 z', fill: color }));
-    defs.appendChild(marker);
+    for (const docked of [false, true]) {
+      const marker = svgElement(document, 'marker', { id: `nova-arrow-${id}${docked ? '-docked' : ''}`, viewBox: '0 0 10 10', refX: docked ? 10 : 8.5, refY: 5, markerWidth: 7, markerHeight: 7, orient: 'auto-start-reverse', markerUnits: 'strokeWidth' });
+      marker.appendChild(svgElement(document, 'path', { d: 'M 0 0 L 10 5 L 0 10 z', fill: color }));
+      defs.appendChild(marker);
+    }
   }
   svg.appendChild(defs);
 }
@@ -305,7 +308,29 @@ function nodeToneName(node) {
   return ({ userTask: 'user-task', serviceTask: 'service-task', scriptTask: 'script-task', businessRuleTask: 'rule-task', sendTask: 'message-task', receiveTask: 'message-task', manualTask: 'manual-task' })[node.type] || 'primary';
 }
 
-function renderDefaultNode({ document, group, node, definition, visual, presentation, subtitle: definitionSubtitle, theme, iconRegistry }) {
+function renderGeometryShape(document, group, geometry, fill, stroke) {
+  const { outline, center, scale } = geometry;
+  const { width, height, radiusX, radiusY, rotation, strokeWidth } = outline;
+  const inset = strokeWidth / 2;
+  const shape = svgElement(document, 'g', { 'data-node-shape': geometry.kind, transform: `translate(${center.x} ${center.y}) rotate(${rotation * 180 / Math.PI}) scale(${scale})` });
+  // Paint the border inward, as CSS does. A centred SVG stroke around an inset ellipse
+  // is not the same outer curve (notably for data stores), so use two nested fills.
+  shape.appendChild(svgElement(document, 'rect', { x: -width / 2, y: -height / 2, width, height, rx: radiusX, ry: radiusY, fill: stroke, filter: geometry.kind === 'gateway' ? 'url(#nova-export-shadow)' : null }));
+  shape.appendChild(svgElement(document, 'rect', { x: -width / 2 + strokeWidth, y: -height / 2 + strokeWidth, width: width - 2 * strokeWidth, height: height - 2 * strokeWidth, rx: Math.max(0, radiusX - strokeWidth), ry: Math.max(0, radiusY - strokeWidth), fill }));
+  if (geometry.kind === 'data') {
+    const right = width / 2 - inset;
+    const top = -height / 2 + inset;
+    shape.appendChild(svgElement(document, 'path', { d: `M ${right - 15} ${top} L ${right} ${top + 15}`, fill: 'none', stroke, 'stroke-width': strokeWidth }));
+  } else if (geometry.kind === 'dataStore') {
+    for (const offset of [9, 19]) {
+      const top = -height / 2 + strokeWidth + offset;
+      shape.appendChild(svgElement(document, 'path', { d: `M ${-width / 2 + inset} ${top + 4.5} A ${width / 2 - inset} 4.5 0 0 1 ${width / 2 - inset} ${top + 4.5}`, fill: 'none', stroke, 'stroke-width': 1.5 }));
+    }
+  }
+  group.appendChild(shape);
+}
+
+function renderDefaultNode({ document, group, node, definition, geometry, visual, presentation, subtitle: definitionSubtitle, theme, iconRegistry }) {
   const colors = theme.colors;
   const statusTone = tone(theme, presentation?.status === 'rejected' ? 'danger' : presentation?.status === 'active' ? 'primary' : presentation?.status === 'completed' ? 'success' : 'neutral');
   const typeTone = tone(theme, nodeToneName(node));
@@ -319,11 +344,12 @@ function renderDefaultNode({ document, group, node, definition, visual, presenta
     appendTextLines(document, group, wrapText(node.name || definition.label, 150, 12), { x: x + width / 2, y: y + height + 20, lineHeight: 15, attributes: { 'text-anchor': 'middle', fill: colors.textSecondary, 'font-size': 12, 'font-family': theme.fontFamily } });
     return;
   }
-  if (definition.kind === 'gateway') {
-    const points = `${x + width / 2},${y + 2} ${x + width - 2},${y + height / 2} ${x + width / 2},${y + height - 2} ${x + 2},${y + height / 2}`;
-    group.appendChild(svgElement(document, 'polygon', { points, fill: colors.surface, stroke: presentation?.status && presentation.status !== 'idle' ? statusTone.strong : colors.borderStrong, 'stroke-width': 2, filter: 'url(#nova-export-shadow)' }));
-    appendIcon(document, group, icon, { x: x + width * 0.28, y: y + height * 0.28, width: width * 0.44, height: height * 0.44 }, colors.textSecondary);
-    appendTextLines(document, group, wrapText(node.name || definition.label, 160, 12), { x: x + width / 2, y: y + height + 20, lineHeight: 15, attributes: { 'text-anchor': 'middle', fill: colors.textSecondary, 'font-size': 12, 'font-family': theme.fontFamily } });
+  if (['gateway', 'data', 'dataStore'].includes(definition.kind)) {
+    if (!geometry) return;
+    const stroke = definition.kind === 'gateway' && presentation?.status && presentation.status !== 'idle' ? statusTone.strong : colors.borderStrong;
+    renderGeometryShape(document, group, geometry, colors.surface, stroke);
+    appendIcon(document, group, icon, geometry.iconBounds, colors.textSecondary);
+    appendTextLines(document, group, wrapText(node.name || definition.label, definition.kind === 'gateway' ? 160 : 150, 12), { x: geometry.label.x, y: geometry.label.y + 12, lineHeight: geometry.label.lineHeight, attributes: { 'text-anchor': 'middle', fill: colors.textSecondary, 'font-size': 12, 'font-family': theme.fontFamily } });
     return;
   }
   if (definition.kind === 'participant' || definition.kind === 'lane') {
@@ -344,17 +370,6 @@ function renderDefaultNode({ document, group, node, definition, visual, presenta
     appendTextLines(document, group, wrapText(node.properties?.text || node.name || '说明', width - 24, 12), { x: x + 16, y: y + 20, lineHeight: 17, attributes: { fill: colors.textSecondary, 'font-size': 12, 'font-family': theme.fontFamily } });
     return;
   }
-  if (definition.kind === 'data' || definition.kind === 'dataStore') {
-    if (definition.kind === 'data') group.appendChild(svgElement(document, 'path', { d: `M ${x + 8} ${y + 2} H ${x + width - 18} L ${x + width - 2} ${y + 18} V ${y + height - 2} H ${x + 8} Z`, fill: colors.surface, stroke: colors.borderStrong, 'stroke-width': 1.5 }));
-    else {
-      group.appendChild(svgElement(document, 'rect', { x: x + 4, y: y + 10, width: width - 8, height: height - 20, fill: colors.surface, stroke: colors.borderStrong, 'stroke-width': 1.5 }));
-      group.appendChild(svgElement(document, 'ellipse', { cx: x + width / 2, cy: y + 10, rx: width / 2 - 4, ry: 9, fill: colors.surface, stroke: colors.borderStrong, 'stroke-width': 1.5 }));
-      group.appendChild(svgElement(document, 'ellipse', { cx: x + width / 2, cy: y + height - 10, rx: width / 2 - 4, ry: 9, fill: 'none', stroke: colors.borderStrong, 'stroke-width': 1.5 }));
-    }
-    appendIcon(document, group, icon, { x: x + width * 0.33, y: y + height * 0.31, width: width * 0.34, height: height * 0.34 }, colors.textSecondary);
-    appendTextLines(document, group, wrapText(node.name || definition.label, 150, 12), { x: x + width / 2, y: y + height + 20, lineHeight: 15, attributes: { 'text-anchor': 'middle', fill: colors.textSecondary, 'font-size': 12, 'font-family': theme.fontFamily } });
-    return;
-  }
 
   const iconSize = Math.min(36, height - 24);
   const iconX = x + 14;
@@ -401,6 +416,45 @@ function renderDefaultNode({ document, group, node, definition, visual, presenta
   }
 }
 
+function prepareNodes({ document, context, options, model, presentation, theme, iconRegistry, warnings }) {
+  const nodeLayer = svgElement(document, 'g', { 'data-layer': 'nodes' });
+  const geometries = new Map();
+  const runtimeMode = context.mode === 'instance' || Boolean(context.runtime);
+  const definitionMode = context.mode === 'viewer' ? 'viewer' : 'design';
+  const order = { participant: 0, lane: 1, group: 2, container: 3, data: 4, dataStore: 4, annotation: 4, task: 5, gateway: 6, event: 7, boundary: 8 };
+  const nodes = [...(model.nodes || [])].sort((a, b) => (order[NODE_DEFINITIONS[a.type]?.kind] ?? 5) - (order[NODE_DEFINITIONS[b.type]?.kind] ?? 5));
+  for (const node of nodes) {
+    options.signal?.throwIfAborted?.();
+    const definition = NODE_DEFINITIONS[node.type] || NODE_DEFINITIONS.generic;
+    const nodePresentation = presentation.getNode?.(node.id) || null;
+    const visual = resolveNodeVisual(node, { surface: context.mode === 'instance' ? 'viewer' : 'canvas', model: context.visualModel || model });
+    const group = svgElement(document, 'g', { 'data-node-id': node.id });
+    const customRenderer = context.nodeRenderers?.[node.type] || context.nodeRenderers?.[definition.kind];
+    let rendered = false;
+    if (typeof customRenderer === 'function') {
+      try {
+        rendered = customRenderer({ container: group, node, definition, runtimePresentation: nodePresentation, visual, model, themeSnapshot: theme, iconRegistry }) !== false;
+        if (!rendered) group.replaceChildren();
+      } catch (error) {
+        group.replaceChildren();
+        warnings.push({ code: 'custom-node-renderer-failed', message: `节点“${node.name || node.id}”的 SVG Renderer 执行失败，已使用标准视觉。`, elementId: node.id });
+      }
+    } else if (context.htmlNodeRenderers?.[node.type] || context.htmlNodeRenderers?.[definition.kind] || context.htmlNodeRenderer) {
+      warnings.push({ code: 'custom-node-renderer-fallback', message: `节点“${node.name || node.id}”没有 SVG Renderer，已使用标准视觉。`, elementId: node.id });
+    }
+    if (!rendered) {
+      const geometry = resolveNodeGeometry(node, definition);
+      geometries.set(node.id, geometry);
+      const subtitle = !runtimeMode && supportsNodeSubtitle(definition)
+        ? resolveNodeSubtitle({ node, definition, model, mode: definitionMode, surface: 'svg-export', resolver: context.nodeSubtitleResolver })
+        : undefined;
+      renderDefaultNode({ document, group, node, definition, geometry, visual, presentation: nodePresentation, subtitle, theme, iconRegistry });
+    }
+    nodeLayer.appendChild(group);
+  }
+  return { nodeLayer, geometries };
+}
+
 export async function exportDiagramSvg(context = {}, options = {}) {
   options.signal?.throwIfAborted?.();
   const document = resolvedDocument(context);
@@ -435,18 +489,22 @@ export async function exportDiagramSvg(context = {}, options = {}) {
   const svg = createRoot(document, { minX, minY, width, height, title, theme, transparentBackground: options.transparentBackground === true });
   addDefinitions(document, svg, theme);
 
+  // Resolve custom renderers once before docking edges, without changing the final layer order.
+  const { nodeLayer, geometries } = prepareNodes({ document, context, options, model, presentation, theme, iconRegistry, warnings });
+
   const edgeLayer = svgElement(document, 'g', { 'data-layer': 'edges' });
   for (const edge of model.edges || []) {
     const points = edgeWaypoints(model, edge);
+    const display = resolvePresentationWaypoints(points, geometries.get(edge.source), geometries.get(edge.target));
     const edgeState = presentation.getEdge?.(edge.id) || { status: 'idle' };
     const completed = edgeState.status === 'completed';
     const stroke = completed ? tone(theme, 'success').strong : theme.colors.edge;
     const type = edge.type || 'sequenceFlow';
     const path = svgElement(document, 'path', {
-      d: routePath(points, edge.routeStyle || model.settings?.edgeStyle || 'rounded', edge.cornerRadius ?? model.settings?.cornerRadius ?? 14),
+      d: routePath(display.points, edge.routeStyle || model.settings?.edgeStyle || 'rounded', edge.cornerRadius ?? model.settings?.cornerRadius ?? 14),
       fill: 'none', stroke, 'stroke-width': completed ? 2.3 : 1.8, 'stroke-linecap': 'round', 'stroke-linejoin': 'round',
       'stroke-dasharray': type === 'messageFlow' ? '8 7' : type === 'association' ? '2 6' : null,
-      'marker-end': type === 'association' ? null : `url(#nova-arrow-${completed ? 'success' : 'edge'})`,
+      'marker-end': type === 'association' ? null : `url(#nova-arrow-${completed ? 'success' : 'edge'}${display.targetDocked ? '-docked' : ''})`,
     });
     edgeLayer.appendChild(path);
     if (edge.name) {
@@ -471,10 +529,11 @@ export async function exportDiagramSvg(context = {}, options = {}) {
       const route = routeRuntimeTransition(model, transition, { occupiedRoutes: occupied });
       if (!route) continue;
       occupied.push(route.points);
+      const display = resolvePresentationWaypoints(route.points, geometries.get(transition.sourceElementId), geometries.get(transition.targetElementId));
       const toneName = appearance.resolveTransition?.(transition)?.tone || (transition.type === 'reject' ? 'danger' : 'warning');
       const transitionTone = tone(theme, toneName);
       const markerTone = Object.hasOwn(theme.tones || {}, toneName) && /^[a-z][a-z0-9-]{0,47}$/.test(toneName) ? toneName : 'neutral';
-      transitionLayer.appendChild(svgElement(document, 'path', { d: routePath(route.points, model.settings?.edgeStyle || 'rounded', model.settings?.cornerRadius || 14), fill: 'none', stroke: transitionTone.strong, 'stroke-width': 2.2, 'stroke-dasharray': '8 6', 'stroke-linecap': 'round', 'stroke-linejoin': 'round', 'marker-end': `url(#nova-arrow-${markerTone})`, opacity: transition.latest ? 1 : 0.42 }));
+      transitionLayer.appendChild(svgElement(document, 'path', { d: routePath(display.points, model.settings?.edgeStyle || 'rounded', model.settings?.cornerRadius || 14), fill: 'none', stroke: transitionTone.strong, 'stroke-width': 2.2, 'stroke-dasharray': '8 6', 'stroke-linecap': 'round', 'stroke-linejoin': 'round', 'marker-end': `url(#nova-arrow-${markerTone}${display.targetDocked ? '-docked' : ''})`, opacity: transition.latest ? 1 : 0.42 }));
       const label = transition.label || (transition.type === 'reject' ? '驳回' : '退回');
       const labelTypography = { fontSize: 11, fontWeight: 650, fontFamily: theme.fontFamily };
       const labelWidth = Math.max(68, Math.min(210, Math.ceil(measureText(document, label, labelTypography) + 20)));
@@ -488,45 +547,6 @@ export async function exportDiagramSvg(context = {}, options = {}) {
     svg.appendChild(transitionLayer);
   }
 
-  const nodeLayer = svgElement(document, 'g', { 'data-layer': 'nodes' });
-  const runtimeMode = context.mode === 'instance' || Boolean(context.runtime);
-  const definitionMode = context.mode === 'viewer' ? 'viewer' : 'design';
-  const order = { participant: 0, lane: 1, group: 2, container: 3, data: 4, dataStore: 4, annotation: 4, task: 5, gateway: 6, event: 7, boundary: 8 };
-  const nodes = [...(model.nodes || [])].sort((a, b) => (order[NODE_DEFINITIONS[a.type]?.kind] ?? 5) - (order[NODE_DEFINITIONS[b.type]?.kind] ?? 5));
-  for (const node of nodes) {
-    options.signal?.throwIfAborted?.();
-    const definition = NODE_DEFINITIONS[node.type] || NODE_DEFINITIONS.generic;
-    const nodePresentation = presentation.getNode?.(node.id) || null;
-    const visual = resolveNodeVisual(node, { surface: context.mode === 'instance' ? 'viewer' : 'canvas', model: context.visualModel || model });
-    const group = svgElement(document, 'g', { 'data-node-id': node.id });
-    const customRenderer = context.nodeRenderers?.[node.type] || context.nodeRenderers?.[definition.kind];
-    let rendered = false;
-    if (typeof customRenderer === 'function') {
-      try {
-        rendered = customRenderer({ container: group, node, definition, runtimePresentation: nodePresentation, visual, model, themeSnapshot: theme, iconRegistry }) !== false;
-        if (!rendered) group.replaceChildren();
-      } catch (error) {
-        group.replaceChildren();
-        warnings.push({ code: 'custom-node-renderer-failed', message: `节点“${node.name || node.id}”的 SVG Renderer 执行失败，已使用标准视觉。`, elementId: node.id });
-      }
-    } else if (context.htmlNodeRenderers?.[node.type] || context.htmlNodeRenderers?.[definition.kind] || context.htmlNodeRenderer) {
-      warnings.push({ code: 'custom-node-renderer-fallback', message: `节点“${node.name || node.id}”没有 SVG Renderer，已使用标准视觉。`, elementId: node.id });
-    }
-    if (!rendered) {
-      const subtitle = !runtimeMode && supportsNodeSubtitle(definition)
-        ? resolveNodeSubtitle({
-          node,
-          definition,
-          model,
-          mode: definitionMode,
-          surface: 'svg-export',
-          resolver: context.nodeSubtitleResolver,
-        })
-        : undefined;
-      renderDefaultNode({ document, group, node, definition, visual, presentation: nodePresentation, subtitle, theme, iconRegistry });
-    }
-    nodeLayer.appendChild(group);
-  }
   svg.appendChild(nodeLayer);
   const filename = sanitizeSvgFilename(options.filename || `${model.name || model.id || 'process'}-${context.label || (context.mode === 'instance' ? '审批轨迹' : context.mode === 'viewer' ? '流程展示' : '流程设计')}`);
   return serializeArtifact(document, svg, { filename, width, height, viewBox: { x: minX, y: minY, width, height }, warnings });

package/dist/modules/node-geometry/index.d.ts

@@ -0,0 +1,19 @@
+import type { BpmnNode, NodeDefinition, Point } from '../core/index.js'
+
+export interface NodeGeometry {
+  kind: 'gateway' | 'data' | 'dataStore'
+  scale: number
+  center: Point
+  outline: Readonly<{ width: number; height: number; radiusX: number; radiusY: number; rotation: number; strokeWidth: number; iconSize: number }>
+  bounds: { x: number; y: number; width: number; height: number }
+  iconBounds: { x: number; y: number; width: number; height: number }
+  label: Point & { lineHeight: number }
+  ports: Record<'left' | 'right' | 'top' | 'bottom', Point | null>
+}
+
+export function resolveNodeGeometry(node: BpmnNode, definition: NodeDefinition): NodeGeometry | null
+export function resolvePresentationWaypoints(points: readonly Point[], sourceGeometry?: NodeGeometry | null, targetGeometry?: NodeGeometry | null): {
+  points: Point[]
+  sourceDocked: boolean
+  targetDocked: boolean
+}

package/dist/modules/node-geometry/index.js

@@ -0,0 +1,147 @@
+const EPSILON = 1e-9;
+const BASE_SHAPES = Object.freeze({
+  gateway: Object.freeze({ width: 49, height: 49, radiusX: 7, radiusY: 7, rotation: Math.PI / 4, strokeWidth: 1.8, iconSize: 24 }),
+  data: Object.freeze({ width: 50, height: 62, radiusX: 4, radiusY: 4, rotation: 0, strokeWidth: 1.7, iconSize: 18 }),
+  dataStore: Object.freeze({ width: 56, height: 50, radiusX: 28, radiusY: 7, rotation: 0, strokeWidth: 1.7, iconSize: 16 }),
+});
+
+function finitePoint(point) {
+  return Number.isFinite(point?.x) && Number.isFinite(point?.y);
+}
+
+function toLocal(geometry, point) {
+  const x = (point.x - geometry.center.x) / geometry.scale;
+  const y = (point.y - geometry.center.y) / geometry.scale;
+  const { rotation } = geometry.outline;
+  return { x: x * Math.cos(rotation) + y * Math.sin(rotation), y: -x * Math.sin(rotation) + y * Math.cos(rotation) };
+}
+
+function contains(outline, point) {
+  const x = Math.abs(point.x);
+  const y = Math.abs(point.y);
+  const halfWidth = outline.width / 2;
+  const halfHeight = outline.height / 2;
+  if (x > halfWidth + EPSILON || y > halfHeight + EPSILON) return false;
+  const dx = Math.max(0, x - halfWidth + outline.radiusX) / outline.radiusX;
+  const dy = Math.max(0, y - halfHeight + outline.radiusY) / outline.radiusY;
+  return dx * dx + dy * dy <= 1 + EPSILON;
+}
+
+/** Intersect an incoming ray with the outer painted rounded rectangle, in base coordinates. */
+function outlineIntersection(outline, from, toward) {
+  if (contains(outline, from)) return null;
+  const dx = toward.x - from.x;
+  const dy = toward.y - from.y;
+  if (Math.hypot(dx, dy) <= EPSILON) return null;
+  const { width, height, radiusX: rx, radiusY: ry } = outline;
+  const hw = width / 2;
+  const hh = height / 2;
+  const candidates = [];
+  const accept = (t, valid) => { if (Number.isFinite(t) && t >= 0 && valid) candidates.push(t); };
+  for (const sign of [-1, 1]) {
+    if (Math.abs(dx) > EPSILON) {
+      const t = (sign * hw - from.x) / dx;
+      accept(t, Math.abs(from.y + t * dy) <= hh - ry + EPSILON);
+    }
+    if (Math.abs(dy) > EPSILON) {
+      const t = (sign * hh - from.y) / dy;
+      accept(t, Math.abs(from.x + t * dx) <= hw - rx + EPSILON);
+    }
+  }
+  for (const sx of [-1, 1]) {
+    for (const sy of [-1, 1]) {
+      const cx = sx * (hw - rx);
+      const cy = sy * (hh - ry);
+      const x = (from.x - cx) / rx;
+      const y = (from.y - cy) / ry;
+      const vx = dx / rx;
+      const vy = dy / ry;
+      const a = vx * vx + vy * vy;
+      const b = 2 * (x * vx + y * vy);
+      const c = x * x + y * y - 1;
+      const discriminant = b * b - 4 * a * c;
+      if (discriminant < -EPSILON || a === 0) continue;
+      const root = Math.sqrt(Math.max(0, discriminant));
+      for (const t of [(-b - root) / (2 * a), (-b + root) / (2 * a)]) {
+        accept(t, (from.x + t * dx - cx) * sx >= -EPSILON && (from.y + t * dy - cy) * sy >= -EPSILON);
+      }
+    }
+  }
+  return candidates.length ? Math.min(...candidates) : null;
+}
+
+/** Display-only intersection. A missing intersection must never invent a new route. */
+function dockPoint(geometry, from, toward) {
+  if (!geometry || !finitePoint(from) || !finitePoint(toward)) return null;
+  const localFrom = toLocal(geometry, from);
+  const localToward = toLocal(geometry, toward);
+  if (!finitePoint(localFrom) || !finitePoint(localToward)) return null;
+  const t = outlineIntersection(geometry.outline, localFrom, localToward);
+  if (t === null) return null;
+  const point = { x: from.x + (toward.x - from.x) * t, y: from.y + (toward.y - from.y) * t };
+  return finitePoint(point) ? point : null;
+}
+
+/**
+ * Standard gateway/data geometry shared by DOM and pure SVG. Model Bounds remain authoritative;
+ * scaling only affects presentation, including borders and decorations. Unsupported/invalid input
+ * deliberately has no geometry rather than silently rewriting a BPMN element's dimensions.
+ */
+export function resolveNodeGeometry(node, definition) {
+  const base = BASE_SHAPES[definition?.kind];
+  if (!base || !finitePoint(node) || !Number.isFinite(node.width) || !Number.isFinite(node.height) || node.width <= 0 || node.height <= 0) return null;
+  const extentWidth = base.rotation ? base.width * Math.SQRT2 : base.width;
+  const extentHeight = base.rotation ? base.height * Math.SQRT2 : base.height;
+  const scale = Math.min(1, node.width / extentWidth, node.height / extentHeight);
+  const center = { x: node.x + node.width / 2, y: node.y + node.height / 2 };
+  const label = { x: center.x, y: node.y + node.height + 6, lineHeight: 16 };
+  if (!finitePoint(center) || !finitePoint(label) || !Number.isFinite(scale) || scale <= 0) return null;
+  const iconSize = (node.type === 'complexGateway' ? 20 : base.iconSize) * scale;
+  const geometry = {
+    kind: definition.kind,
+    scale,
+    center,
+    outline: base,
+    bounds: { x: center.x - extentWidth * scale / 2, y: center.y - extentHeight * scale / 2, width: extentWidth * scale, height: extentHeight * scale },
+    iconBounds: { x: center.x - iconSize / 2, y: center.y - iconSize / 2, width: iconSize, height: iconSize },
+    label,
+    ports: {},
+  };
+  for (const [side, dx, dy] of [['left', -1, 0], ['right', 1, 0], ['top', 0, -1], ['bottom', 0, 1]]) {
+    const distance = Math.max(extentWidth, extentHeight) * scale;
+    geometry.ports[side] = dockPoint(geometry, { x: center.x + dx * distance, y: center.y + dy * distance }, center);
+  }
+  return geometry;
+}
+
+function endpointProjection(points, geometry, target) {
+  const start = target ? points.length - 1 : 0;
+  const step = target ? -1 : 1;
+  let next = start + step;
+  while (next >= 0 && next < points.length && Math.hypot(points[next].x - points[start].x, points[next].y - points[start].y) <= EPSILON) next += step;
+  if (next < 0 || next >= points.length) return null;
+  const point = dockPoint(geometry, points[next], points[start]);
+  return point ? { point, start, next, step } : null;
+}
+
+/** Clone routes; keep bends, collinearity and travel direction, including repeated endpoint entries. */
+export function resolvePresentationWaypoints(points, sourceGeometry = null, targetGeometry = null) {
+  const copy = points.map((point) => ({ ...point }));
+  const unchanged = () => ({ points: points.map((point) => ({ ...point })), sourceDocked: false, targetDocked: false });
+  if (points.length < 2 || !points.every(finitePoint)) return unchanged();
+  const source = endpointProjection(points, sourceGeometry, false);
+  const target = endpointProjection(points, targetGeometry, true);
+  for (const projection of [source, target]) {
+    if (!projection) continue;
+    for (let index = projection.start; index !== projection.next; index += projection.step) copy[index] = { ...projection.point };
+  }
+  // Closely spaced/overlapping nodes must not reverse the first or last segment after docking.
+  for (const projection of [source, target]) {
+    if (!projection) continue;
+    const { start, next } = projection;
+    const before = { x: points[next].x - points[start].x, y: points[next].y - points[start].y };
+    const after = { x: copy[next].x - copy[start].x, y: copy[next].y - copy[start].y };
+    if (before.x * after.x + before.y * after.y <= EPSILON) return unchanged();
+  }
+  return { points: copy, sourceDocked: Boolean(source), targetDocked: Boolean(target) };
+}

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

@@ -2,6 +2,7 @@ import { NODE_DEFINITIONS, PALETTE_GROUPS, PARALLEL_GATEWAY_PRESETS, edgeWaypoin
 import { createRuntimePresentation } from '../runtime/index.js';
 import { createDefaultIconRegistry, createIconElement, resolveNodeVisual } from '../icons/index.js';
 import { resolveNodeSubtitle, supportsNodeSubtitle } from '../node-presentation/index.js';
+import { resolveNodeGeometry, resolvePresentationWaypoints } from '../node-geometry/index.js';
 import { ThemeController, applyRuntimeTone } from '../theme/index.js';
 import { exportDiagramSvg, openSvgExportPreview } from '../export-svg/index.js';
 
@@ -276,6 +277,26 @@ function nodeAccessibleLabel(title, subtitle) {
   return subtitle === null || subtitle === '' ? title : `${title}\n${subtitle}`;
 }
 
+function applyNodeGeometry(shape, geometry) {
+  shape.classList.add('mb-node-scaled-shape');
+  shape.style.width = `${geometry.outline.width}px`;
+  shape.style.height = `${geometry.outline.height}px`;
+  shape.style.setProperty('--mb-node-shape-scale', String(geometry.scale));
+  shape.style.setProperty('--mb-node-shape-rotation', `${geometry.outline.rotation}rad`);
+  // CSS may quantize a 1.7px border to 1.5px; keep the document fold inside the outer outline.
+  if (geometry.kind === 'data') shape.style.clipPath = `inset(0 round ${geometry.outline.radiusX}px)`;
+}
+
+function geometryLabel(node, geometry) {
+  const label = el('div', 'mb-node-floating-label', node.name);
+  if (geometry) {
+    label.style.left = `${geometry.label.x - node.x}px`;
+    label.style.top = `${geometry.label.y - node.y}px`;
+    label.style.lineHeight = `${geometry.label.lineHeight}px`;
+  }
+  return label;
+}
+
 function runtimeStatusIconId(presentation) {
   if (presentation?.status === 'rejected') return 'ui.statusRejected';
   if (presentation?.status === 'completed') return 'ui.statusCompleted';
@@ -364,17 +385,21 @@ export class DiagramRenderer {
       ['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);
+      for (const docked of [false, true]) {
+        const marker = svgEl('marker', { id: `${id}${docked ? '-docked' : ''}`, viewBox: '0 0 10 10', refX: docked ? '10' : '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);
+      for (const docked of [false, true]) {
+        const marker = svgEl('marker', { id: `${id}${docked ? '-docked' : ''}`, viewBox: '0 0 10 10', refX: docked ? '10' : '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);
 
@@ -767,6 +792,7 @@ export class DiagramRenderer {
       ? presenter({ model: this.model, runtime: this.runtime, appearance: this.options.runtimeAppearance })
       : createRuntimePresentation({ model: this.model, runtime: null, appearance: this.options.runtimeAppearance });
     const subtitles = this._resolveDefinitionSubtitles();
+    this._nodeGeometries = new Map(this.model.nodes.map((node) => [node.id, resolveNodeGeometry(node, NODE_DEFINITIONS[node.type])]));
     this._syncSceneBounds();
     this._renderEdges();
     this._renderRuntimeTransitions();
@@ -832,8 +858,9 @@ export class DiagramRenderer {
         labelSize: { width: metrics.width, height: metrics.height },
       });
       if (!route) return;
-      const points = route.points;
-      occupiedRuntimeRoutes.push(points);
+      const display = resolvePresentationWaypoints(route.points, this._nodeGeometries.get(transition.sourceElementId), this._nodeGeometries.get(transition.targetElementId));
+      const points = display.points;
+      occupiedRuntimeRoutes.push(route.points);
       labelObstacles.push({
         x: route.labelPoint.x - metrics.width / 2,
         y: route.labelPoint.y - metrics.height / 2,
@@ -860,7 +887,7 @@ export class DiagramRenderer {
         d: pathData,
         class: 'mb-runtime-transition-path',
         fill: 'none',
-        'marker-end': `url(#runtime-arrow-${transition.type})`,
+        'marker-end': `url(#runtime-arrow-${transition.type}${display.targetDocked ? '-docked' : ''})`,
       }));
       const labelX = route.labelPoint.x;
       const labelY = route.labelPoint.y;
@@ -900,9 +927,10 @@ export class DiagramRenderer {
     for (const edge of this.model.edges) {
       const points = edgeWaypoints(this.model, edge);
       if (points.length < 2) continue;
+      const display = resolvePresentationWaypoints(points, this._nodeGeometries.get(edge.source), this._nodeGeometries.get(edge.target));
       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 pathData = routePathData(display.points, routeStyle, corner);
 
       const edgeStatus = this.runtimePresentation.getEdge(edge.id).status;
       const selected = this.selection?.kind === 'edge' && this.selection.id === edge.id;
@@ -916,7 +944,7 @@ export class DiagramRenderer {
         class: 'mb-edge-path',
         fill: 'none',
       };
-      if ((edge.type || 'sequenceFlow') === 'sequenceFlow') pathAttrs['marker-end'] = `url(#arrow${edgeStatus === 'idle' ? '' : `-${edgeStatus}`})`;
+      if ((edge.type || 'sequenceFlow') === 'sequenceFlow') pathAttrs['marker-end'] = `url(#arrow${edgeStatus === 'idle' ? '' : `-${edgeStatus}`}${display.targetDocked ? '-docked' : ''})`;
       const path = svgEl('path', pathAttrs);
       const hit = svgEl('path', { d: pathData, class: 'mb-edge-hit', fill: 'none' });
       let labelPosition = edgeLabelPoint(points);
@@ -1109,7 +1137,13 @@ export class DiagramRenderer {
     }
 
     if (def.kind === 'gateway') {
+      const geometry = this._nodeGeometries.get(node.id);
+      if (!geometry) {
+        nodeEl.appendChild(geometryLabel(node, geometry));
+        return;
+      }
       const shape = el('div', 'mb-gateway-shape');
+      applyNodeGeometry(shape, geometry);
       const symbol = el('span', 'mb-gateway-symbol');
       if (!this._renderCustomNodeContent(symbol, node, def, runtimeState, visual)) {
         const iconNode = visual.iconId
@@ -1131,23 +1165,19 @@ export class DiagramRenderer {
           nodeEl.appendChild(badge);
         }
       }
-      nodeEl.appendChild(el('div', 'mb-node-floating-label', node.name));
+      nodeEl.appendChild(geometryLabel(node, geometry));
       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));
+    if (def.kind === 'data' || def.kind === 'dataStore') {
+      const geometry = this._nodeGeometries.get(node.id);
+      if (geometry) {
+        const shape = el('div', def.kind === 'data' ? 'mb-data-object-shape' : 'mb-data-store-shape');
+        applyNodeGeometry(shape, geometry);
+        shape.appendChild(el('span', def.kind === 'data' ? 'mb-data-object-lines' : '', '≡'));
+        nodeEl.appendChild(shape);
+      }
+      nodeEl.appendChild(geometryLabel(node, geometry));
       return;
     }
 
@@ -1308,6 +1338,14 @@ export class DiagramRenderer {
 
     const appendPort = (side, { target = false, onClick } = {}) => {
       const port = el('button', `mb-port mb-port-${side}${target ? ' mb-port-target' : ''}`);
+      const anchor = this._nodeGeometries.get(node.id)?.ports[side];
+      if (anchor) {
+        port.classList.add('mb-port-geometry');
+        port.style.left = `${anchor.x - node.x}px`;
+        port.style.top = `${anchor.y - node.y}px`;
+        port.style.right = 'auto';
+        port.style.bottom = 'auto';
+      }
       port.type = 'button';
       port.title = target ? '连接到此节点' : (side === 'right' ? '创建连接' : '输入连接点');
       port.tabIndex = -1;

package/dist/modules/viewer/index.d.ts

@@ -248,7 +248,7 @@ export class BpmnViewer {
   setModel(model: ProcessModel): void
   setRuntime(runtime: ProcessInstanceSnapshot | null): void
   refreshPresentation(): void
-  setDisplayOptions(options: { timeline?: ViewerTimelineOptions; runtimeDetails?: RuntimeDetailsOptions; runtimeTraceOptions?: RuntimeTraceProjectionOptions; runtimeAssetResolver?: RuntimeAssetResolver | null }): void
+  setDisplayOptions(options: { timeline?: ViewerTimelineOptions; runtimeDetails?: RuntimeDetailsOptions; runtimeTraceOptions?: RuntimeTraceProjectionOptions; runtimeAssetResolver?: RuntimeAssetResolver | null; replace?: boolean }): void
   setProjection(projection: ViewerProjection): void
   setTheme(theme: NovaThemeInput): NovaThemeState
   setThemeMode(mode: NovaThemeMode): NovaThemeState