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

package/README.md

@@ -4,7 +4,7 @@ BPMN Nova 的 Vanilla JavaScript / TypeScript 完整入口，提供流程设计
 
 > **English summary:** The complete framework-neutral BPMN Nova package for process design, viewing, approval traces, themes, properties, and pure SVG export.
 
-> 当前版本为 `0.3.2-preview`。请使用 `@preview` 安装，并在生产接入前验证目标 BPMN XML 与引擎扩展。
+> 当前版本为 `0.3.3-preview`。请使用 `@preview` 安装，并在生产接入前验证目标 BPMN XML 与引擎扩展。
 
 ![BPMN Nova 流程设计器](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-designer.jpg)
 
@@ -85,6 +85,10 @@ const shell = createStudioShell({
       // 在 Nova Header 左侧挂载宿主的返回入口、业务图标、流程名称和类型。
       // 完整替换 Header 时改用 slots.header，并继续调用 actions。
     },
+    headerActions({ container, actions, getMode, subscribeMode }) {
+      // 替换默认“校验 / 导入 / 导出”，在这里挂载宿主的“校验 / 保存 / 发布”。
+      // 校验按钮调用 actions.validate()；保存和发布继续调用宿主服务。
+    },
   },
   theme: 'auto',
 })
@@ -99,8 +103,67 @@ const xml = shell.actions.exportXml('flowable')
 
 `regions` 支持 `header`、`left`、`right`、`footer` 的 `default | hidden` 状态；隐藏区域不占布局轨道。`setRegions()` 原地更新默认 Shell，不重建 Controller 或 Canvas。`layout()` 是完整布局替换，不能与 `regions` 同时使用。
 
+`headerActions` 只替换 Header 最右侧动作组，`headerStart` 可与其同时使用，完整 `header` 的优先级更高。未提供 `headerActions` 时仍显示默认“校验 / 导入 / 导出”。顶部不再重复显示最佳视图；底部缩放区和 `fitView()` Interface 保持不变。
+
+`shell.actions.validate()` 作为 Header 动作，以 `toolbar` 来源先更新 Nova 默认状态栏、再发送 Validation Event，最后返回 issues；程序化调用 `shell.validate()` 使用 `api` 来源。`valid` 表示没有 error，warning 不默认阻止发布：
+
+```js
+const offValidation = shell.subscribeValidation((event) => {
+  console.log(event.source, event.valid, event.errorCount, event.warningCount, event.issues)
+})
+
+shell.validate()
+offValidation()
+```
+
+宿主发布按钮可以复用 Toolbar 来源的完整流程；仅 error 默认阻止发布：
+
+```js
+async function publishProcess(actions) {
+  const issues = actions.validate()
+  if (issues.some((issue) => issue.level === 'error')) return
+  await publishXml(actions.exportXml())
+}
+```
+
 `shell.actions` 只封装撤销、重做、布局、视图、校验和 BPMN/SVG 导入导出。宿主的保存草稿、发布、权限、文件选择和服务端事务不属于 Nova Actions。
 
+## Mode 与节点副标题投影
+
+`design`、`viewer`、`instance` 分别表示流程设计、流程展示和审批轨迹。Shell 是唯一 Mode 状态源：
+
+```js
+const unsubscribe = shell.subscribeMode((event) => {
+  console.log(event.mode, event.previousMode, event.source, event.allowedModes)
+})
+
+shell.getMode()
+shell.setMode('viewer')
+shell.setAllowedModes(['design', 'viewer'])
+```
+
+`setMode()` 仅在实际成功切换时返回 `true`。`setAllowedModes()` 拒绝空数组、重复值和未知值；若移除当前 Mode，会回退到新数组首项并发送一次 `allowed-modes` 事件。切换只改变 Shell 展示，不进入 Model、History 或 Studio State。
+
+标准任务与容器卡片支持定义态副标题 Resolver：
+
+```js
+const summaries = new Map()
+const shell = createStudioShell({
+  container,
+  studio,
+  nodeSubtitleResolver({ node, mode, surface, defaultSubtitle }) {
+    return summaries.has(node.id) ? summaries.get(node.id) : undefined
+  },
+})
+
+summaries.set('ServiceTask_Archive', '归档到采购系统')
+shell.refreshPresentation()
+summaries.set('ServiceTask_Archive', null)
+shell.refreshPresentation()
+```
+
+`undefined` 保留默认副标题，`null` 移除副标题行，字符串（包括空字符串）作为覆盖值。Resolver 同步应用于 Design、Viewer 与标准 SVG 降级视觉；完整自定义 Renderer 优先，Instance 始终使用 Runtime Presentation。`refreshPresentation()` 不写 XML、不创建历史、不改变选择、Scope 或视口。
+
 ## 只读 Viewer
 
 ```js

package/dist/canvas.js

@@ -35,7 +35,7 @@ function toolbarIcon(id) {
 }
 
 export class BpmnCanvas {
-  constructor({ container, studio, rendererOptions = {}, interactions = null, selectionToolbar = null, contextMenu = null, contextMenuRegistry = createDefaultContextMenuRegistry(), pointerMode = 'select', themeController = null, theme = null, onThemeChange = null } = {}) {
+  constructor({ container, studio, rendererOptions = {}, nodeSubtitleResolver = rendererOptions.nodeSubtitleResolver, interactions = null, selectionToolbar = null, contextMenu = null, contextMenuRegistry = createDefaultContextMenuRegistry(), pointerMode = 'select', themeController = null, theme = null, onThemeChange = null } = {}) {
     if (!container) throw new Error('BpmnCanvas requires a container.');
     if (!studio) throw new Error('BpmnCanvas requires a studio controller.');
     this.container = container;
@@ -51,6 +51,7 @@ export class BpmnCanvas {
     const onViewportChange = rendererOptions.onViewportChange;
     this.renderer = new DiagramRenderer(container, {
       ...rendererOptions,
+      nodeSubtitleResolver,
       themeController,
       theme,
       onThemeChange,
@@ -905,6 +906,7 @@ export class BpmnCanvas {
   startConnect(nodeId) { this.renderer.closeTransientOverlays?.(); return this.studio.startConnect(nodeId); }
   editEdgeName(edgeId) { return this.renderer.editEdgeName?.(edgeId) || false; }
   fitView(padding, options) { this.renderer.fitView(padding, { minZoom: 0.7, ...(options || {}) }); }
+  refreshPresentation() { this.renderer.refreshPresentation(); }
   exportSvg(options) { return this.renderer.exportSvg(options); }
   openSvgExportPreview(options) { return this.renderer.openSvgExportPreview(options); }
   fitSelection(padding = 72) {

package/dist/index.d.ts

@@ -26,6 +26,7 @@ import type {
 import type { IconRegistry } from './modules/icons/index.js'
 import type { PaletteRegistry } from './modules/palette/index.js'
 import type { PropertiesRegistry } from './modules/properties/index.js'
+import type { NodeSubtitleResolver } from './modules/node-presentation/index.js'
 import type { DiagramNodeRenderer, DiagramRendererOptions } from './modules/renderer-svg/index.js'
 import type { RuntimeTimelineSvgRenderer, SvgExportArtifact, SvgExportOptions, SvgExportPreviewController, SvgNodeRenderer } from './modules/export-svg/index.js'
 import type {
@@ -38,6 +39,8 @@ import type {
   RuntimeTransitionDetailsRenderer,
 } from './modules/viewer/index.js'
 
+export type { NodeSubtitleResolver, NodeSubtitleResolverContext } from './modules/node-presentation/index.js'
+
 // Aggregate compatibility surface. Studio re-exports the package-level types,
 // and keeps these frequently consumed declarations visible at its own entry.
 export interface ScopedElement { scopeId?: string }
@@ -141,6 +144,7 @@ export interface ViewerOptions {
   iconRegistry?: IconRegistry
   nodeRenderers?: Record<string, Function>
   nodeRenderer?: Function
+  nodeSubtitleResolver?: NodeSubtitleResolver
   projection?: ViewerProjection
   responsive?: boolean
   timeline?: ViewerTimelineOptions
@@ -173,6 +177,7 @@ export class BpmnViewer {
   traceProjection: RuntimeTraceProjection | null
   setModel(model: ProcessModel): void
   setRuntime(runtime: ProcessInstanceSnapshot | null): void
+  refreshPresentation(): void
   setDisplayOptions(options: { timeline?: ViewerTimelineOptions; runtimeDetails?: RuntimeDetailsOptions; runtimeTraceOptions?: RuntimeTraceProjectionOptions; runtimeAssetResolver?: import('./modules/viewer/index.js').RuntimeAssetResolver | null }): void
   setProjection(projection: ViewerProjection): void
   setTheme(theme: NovaThemeInput): NovaThemeState
@@ -414,6 +419,7 @@ export interface BpmnCanvasOptions {
   container: HTMLElement
   studio: BpmnStudioController
   rendererOptions?: DiagramRendererOptions
+  nodeSubtitleResolver?: NodeSubtitleResolver
   interactions?: InteractionController | null
   selectionToolbar?: HTMLElement | SelectionToolbarSlot | null
   contextMenu?: HTMLElement | ContextMenuSlot | null
@@ -427,6 +433,7 @@ export class BpmnCanvas {
   clientToWorld(clientX: number, clientY: number): Point
   getViewportCenterWorld(): Point
   fitView(padding?: number, options?: Record<string, unknown>): void
+  refreshPresentation(): void
   fitSelection(padding?: number): boolean
   setPointerMode(mode: 'select' | 'marquee' | 'pan'): boolean
   getPointerMode(): 'select' | 'marquee' | 'pan'
@@ -458,6 +465,22 @@ export interface StudioShellActions {
     onDownload?: (artifact: SvgExportArtifact) => void
   }): SvgExportPreviewController | null
 }
+export type StudioMode = 'design' | 'viewer' | 'instance'
+export type StudioModeChangeSource = 'toolbar' | 'api' | 'allowed-modes'
+export interface StudioModeChangeEvent {
+  readonly mode: StudioMode
+  readonly previousMode: StudioMode
+  readonly source: StudioModeChangeSource
+  readonly allowedModes: readonly StudioMode[]
+}
+export type StudioValidationSource = 'toolbar' | 'api'
+export interface StudioValidationEvent {
+  readonly source: StudioValidationSource
+  readonly valid: boolean
+  readonly errorCount: number
+  readonly warningCount: number
+  readonly issues: readonly StudioValidationIssue[]
+}
 export interface StudioShellSlotContext {
   studio: BpmnStudioController
   shell: BpmnStudioShell
@@ -465,6 +488,10 @@ export interface StudioShellSlotContext {
   actions: StudioShellActions
   getState(): StudioState
   subscribe(listener: (event: StudioEvent) => void): () => void
+  getMode(): StudioMode
+  getAllowedModes(): readonly StudioMode[]
+  subscribeMode(listener: (event: StudioModeChangeEvent) => void): () => void
+  subscribeValidation(listener: (event: StudioValidationEvent) => void): () => void
 }
 export type StudioShellDomSlot =
   | HTMLElement
@@ -473,6 +500,7 @@ export interface StudioShellSlots {
   left?: StudioShellDomSlot
   right?: StudioShellDomSlot
   headerStart?: StudioShellDomSlot
+  headerActions?: StudioShellDomSlot
   header?: StudioShellDomSlot
   footer?: StudioShellDomSlot
   contextMenu?: ContextMenuSlot
@@ -507,12 +535,13 @@ export interface StudioShellOptions {
     runtimeTraceOptions?: RuntimeTraceProjectionOptions
     timeline?: ViewerTimelineOptions
   }
+  nodeSubtitleResolver?: NodeSubtitleResolver
   slots?: StudioShellSlots
   regions?: StudioShellRegions
   layout?: (context: Record<string, unknown>) => void | (() => void)
   runtime?: ProcessInstanceSnapshot | null
-  mode?: 'design' | 'viewer' | 'instance'
-  allowedModes?: Array<'design' | 'viewer' | 'instance'>
+  mode?: StudioMode
+  allowedModes?: readonly StudioMode[]
   projection?: ViewerProjection
   responsive?: boolean
   projectionOptions?: Array<{ value: ViewerProjection; label: string }>
@@ -528,9 +557,14 @@ export class BpmnStudioShell {
   readonly actions: StudioShellActions
   canvas?: BpmnCanvas
   viewer?: BpmnViewer
+  getMode(): StudioMode
+  getAllowedModes(): readonly StudioMode[]
+  subscribeMode(listener: (event: StudioModeChangeEvent) => void): () => void
+  subscribeValidation(listener: (event: StudioValidationEvent) => void): () => void
+  setAllowedModes(modes: readonly StudioMode[]): readonly StudioMode[]
   getRegions(): Readonly<StudioShellRegionState>
   setRegions(regions: StudioShellRegions): Readonly<StudioShellRegionState>
-  setMode(mode: 'design' | 'viewer' | 'instance'): void
+  setMode(mode: StudioMode): boolean
   setRuntime(runtime: ProcessInstanceSnapshot | null): void
   setProjection(projection: ViewerProjection): void
   setTheme(theme: NovaThemeInput): NovaThemeState
@@ -538,6 +572,8 @@ export class BpmnStudioShell {
   getThemeState(): NovaThemeState
   subscribeTheme(listener: (state: NovaThemeState) => void): () => void
   setRuntimeAppearance(options: RuntimeAppearanceOptions | null): void
+  refreshPresentation(): void
+  validate(): StudioValidationIssue[]
   fitView(): void
   zoomBy(factor: number): void
   exportSvg(options?: SvgExportOptions): Promise<SvgExportArtifact>

package/dist/modules/export-svg/index.d.ts

@@ -2,6 +2,7 @@ import type { BpmnNode, ProcessModel } from '../core/index.js'
 import type { IconRegistry, NodeVisualResolution } from '../icons/index.js'
 import type { NodeRuntimePresentation, ProcessInstanceSnapshot, RuntimeApprovalActionPresentation, RuntimePresentation, RuntimeAssetRef } from '../runtime/index.js'
 import type { NovaResolvedTheme, NovaThemeSnapshot, RuntimeAppearanceOptions, RuntimeAppearanceResolver, ThemeController } from '../theme/index.js'
+import type { NodeSubtitleResolver } from '../node-presentation/index.js'
 
 export type SvgExportTheme = 'current' | NovaResolvedTheme
 export interface SvgExportOptions {
@@ -65,6 +66,7 @@ export interface DiagramSvgExportContext {
   nodeRenderers?: Record<string, SvgNodeRenderer>
   htmlNodeRenderers?: Record<string, Function>
   htmlNodeRenderer?: Function
+  nodeSubtitleResolver?: NodeSubtitleResolver
   mode?: 'design' | 'viewer' | 'instance'
   label?: string
 }

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

@@ -1,5 +1,6 @@
 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 { createRuntimePresentation } from '../runtime/index.js';
 import { createRuntimeAppearance } from '../theme/index.js';
 
@@ -304,7 +305,7 @@ 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, theme, iconRegistry }) {
+function renderDefaultNode({ document, group, node, definition, 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));
@@ -360,7 +361,10 @@ function renderDefaultNode({ document, group, node, definition, visual, presenta
   const iconY = y + (height - iconSize) / 2;
   const copyX = iconX + iconSize + 12;
   const title = node.name || definition.label;
-  const subtitle = presentation?.actionSummary || presentation?.summary || (node.properties?.assignee || node.properties?.candidateGroups || node.properties?.candidateUsers || '');
+  const subtitle = definitionSubtitle === undefined
+    ? presentation?.actionSummary || presentation?.summary || (node.properties?.assignee || node.properties?.candidateGroups || node.properties?.candidateUsers || '')
+    : definitionSubtitle;
+  const hasSubtitleRow = subtitle !== null;
   const hasStatus = Boolean(presentation?.status && presentation.status !== 'idle');
   const label = hasStatus ? String(presentation.statusLabel || presentation.status) : '';
   const statusTypography = { fontSize: 10.5, fontWeight: 650, fontFamily: theme.fontFamily };
@@ -371,18 +375,24 @@ function renderDefaultNode({ document, group, node, definition, visual, presenta
   const titleTypography = { fontSize: 14, fontWeight: 650, fontFamily: theme.fontFamily };
   const subtitleTypography = { fontSize: 11.5, fontWeight: 400, fontFamily: theme.fontFamily };
   const fittedTitle = fitText(document, title, titleMaxWidth, titleTypography);
-  const fittedSubtitle = fitText(document, subtitle, subtitleMaxWidth, subtitleTypography);
-  const tooltip = [title, subtitle].filter(Boolean).join('\n');
+  const fittedSubtitle = hasSubtitleRow ? fitText(document, subtitle, subtitleMaxWidth, subtitleTypography) : '';
+  const tooltip = subtitle === null || subtitle === '' ? title : `${title}\n${subtitle}`;
+  group.setAttribute('role', 'group');
+  group.setAttribute('aria-label', tooltip);
   if (tooltip && (fittedTitle !== title || fittedSubtitle !== String(subtitle || ''))) group.appendChild(svgElement(document, 'title', {}, tooltip));
 
   const clipId = safeSvgId(node.id);
-  const titleClip = appendClipPath(document, group, `nova-node-${clipId}-title-clip`, { x: copyX, y: y + 9, width: titleMaxWidth, height: 23 });
-  const subtitleClip = appendClipPath(document, group, `nova-node-${clipId}-subtitle-clip`, { x: copyX, y: y + 33, width: subtitleMaxWidth, height: 21 });
+  const titleY = hasSubtitleRow ? y + 27 : y + height / 2 + 5;
+  const titleClipY = hasSubtitleRow ? y + 9 : y + (height - 23) / 2;
+  const titleClip = appendClipPath(document, group, `nova-node-${clipId}-title-clip`, { x: copyX, y: titleClipY, width: titleMaxWidth, height: 23 });
+  const subtitleClip = hasSubtitleRow
+    ? appendClipPath(document, group, `nova-node-${clipId}-subtitle-clip`, { x: copyX, y: y + 33, width: subtitleMaxWidth, height: 21 })
+    : null;
   group.appendChild(svgElement(document, 'rect', { x, y, width, height, rx: 12, fill: colors.surface, stroke: hasStatus ? statusTone.border : colors.border, 'stroke-width': presentation?.status === 'active' ? 2 : 1.2, filter: 'url(#nova-export-shadow)' }));
   group.appendChild(svgElement(document, 'rect', { x, y: y + 12, width: 3, height: Math.max(12, height - 24), rx: 1.5, fill: typeTone.strong }));
   group.appendChild(svgElement(document, 'rect', { x: iconX, y: iconY, width: iconSize, height: iconSize, rx: 9, fill: typeTone.background }));
   appendIcon(document, group, icon, { x: iconX + 8, y: iconY + 8, width: iconSize - 16, height: iconSize - 16 }, typeTone.foreground);
-  if (fittedTitle) group.appendChild(svgElement(document, 'text', { x: copyX, y: y + 27, fill: colors.text, 'font-size': titleTypography.fontSize, 'font-weight': titleTypography.fontWeight, 'font-family': titleTypography.fontFamily, 'clip-path': titleClip }, fittedTitle));
+  if (fittedTitle) group.appendChild(svgElement(document, 'text', { x: copyX, y: titleY, fill: colors.text, 'font-size': titleTypography.fontSize, 'font-weight': titleTypography.fontWeight, 'font-family': titleTypography.fontFamily, 'clip-path': titleClip }, fittedTitle));
   if (fittedSubtitle) group.appendChild(svgElement(document, 'text', { x: copyX, y: y + 49, fill: colors.textSecondary, 'font-size': subtitleTypography.fontSize, 'font-family': subtitleTypography.fontFamily, 'clip-path': subtitleClip }, fittedSubtitle));
   if (hasStatus) {
     const fittedLabel = fitText(document, label, labelWidth - 16, statusTypography);
@@ -479,6 +489,8 @@ export async function exportDiagramSvg(context = {}, options = {}) {
   }
 
   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) {
@@ -500,7 +512,19 @@ export async function exportDiagramSvg(context = {}, options = {}) {
     } 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) renderDefaultNode({ document, group, node, definition, visual, presentation: nodePresentation, theme, iconRegistry });
+    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);

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

@@ -0,0 +1,25 @@
+import type { BpmnNode, NodeDefinition, ProcessModel } from '../core/index.js'
+
+export interface NodeSubtitleResolverContext {
+  readonly node: BpmnNode
+  readonly definition: NodeDefinition
+  readonly model: ProcessModel
+  readonly mode: 'design' | 'viewer'
+  readonly surface: 'canvas' | 'svg-export'
+  readonly defaultSubtitle: string
+}
+
+export type NodeSubtitleResolver = (
+  context: Readonly<NodeSubtitleResolverContext>,
+) => string | null | undefined
+
+export function resolveDefaultNodeSubtitle(node: BpmnNode): string
+export function supportsNodeSubtitle(definition: NodeDefinition): boolean
+export function resolveNodeSubtitle(context: {
+  node: BpmnNode
+  definition: NodeDefinition
+  model: ProcessModel
+  mode: 'design' | 'viewer'
+  surface: 'canvas' | 'svg-export'
+  resolver?: NodeSubtitleResolver | null
+}): string | null

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

@@ -0,0 +1,51 @@
+function resolverError(node, reason) {
+  const nodeId = node?.id || '<unknown>';
+  const detail = reason instanceof Error ? reason.message : String(reason);
+  const error = new Error(`Node subtitle resolver failed for node "${nodeId}": ${detail}`);
+  if (reason instanceof Error) error.cause = reason;
+  return error;
+}
+
+export function resolveDefaultNodeSubtitle(node) {
+  const properties = node?.properties || {};
+  if (node?.type === 'userTask') return properties.assignee || properties.candidateGroups || properties.candidateUsers || '待配置审批人';
+  if (['serviceTask', 'sendTask', 'businessRuleTask'].includes(node?.type)) return properties.implementation || '待配置执行实现';
+  if (node?.type === 'scriptTask') return properties.scriptFormat || 'Script';
+  if (node?.type === 'callActivity') return properties.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:', '') || '';
+}
+
+export function supportsNodeSubtitle(definition) {
+  return definition?.kind === 'task' || definition?.kind === 'container';
+}
+
+export function resolveNodeSubtitle({ node, definition, model, mode, surface, resolver }) {
+  const defaultSubtitle = resolveDefaultNodeSubtitle(node);
+  if (typeof resolver !== 'function') return defaultSubtitle;
+
+  let result;
+  try {
+    result = resolver(Object.freeze({
+      node,
+      definition,
+      model,
+      mode,
+      surface,
+      defaultSubtitle,
+    }));
+  } catch (error) {
+    throw resolverError(node, error);
+  }
+
+  if (result === undefined) return defaultSubtitle;
+  if (result === null || typeof result === 'string') return result;
+  if (result && typeof result.then === 'function') {
+    throw resolverError(node, 'Promise results are not supported; return a string, null, or undefined.');
+  }
+  throw resolverError(node, `invalid result type "${typeof result}"; return a string, null, or undefined.`);
+}

package/dist/modules/renderer-svg/index.d.ts

@@ -3,6 +3,7 @@ import type { IconRegistry, NodeVisualResolution } from '../icons/index.js'
 import type { NodeRuntimePresentation, ProcessInstanceSnapshot, RuntimePresentation } from '../runtime/index.js'
 import type { NovaThemeInput, NovaThemeMode, NovaThemeState, RuntimeAppearanceResolver, ThemeController } from '../theme/index.js'
 import type { SvgExportArtifact, SvgExportOptions, SvgExportPreviewController, SvgNodeRenderer } from '../export-svg/index.js'
+import type { NodeSubtitleResolver } from '../node-presentation/index.js'
 
 export interface SceneBounds {
   left: number
@@ -73,6 +74,7 @@ export interface DiagramRendererOptions {
   iconRegistry?: IconRegistry
   nodeRenderers?: Record<string, DiagramNodeRenderer>
   nodeRenderer?: DiagramNodeRenderer
+  nodeSubtitleResolver?: NodeSubtitleResolver
   runtimePresenter?: (context: { model: ProcessModel; runtime: ProcessInstanceSnapshot | null; appearance: RuntimeAppearanceResolver | null }) => RuntimePresentation
   runtimeAppearance?: RuntimeAppearanceResolver | null
   svgExport?: SvgExportOptions & { label?: string; nodeRenderers?: Record<string, SvgNodeRenderer> }
@@ -98,6 +100,7 @@ export class DiagramRenderer {
   setModel(model: ProcessModel): void
   setMode(mode: 'design' | 'viewer' | 'instance'): void
   setRuntime(runtime: ProcessInstanceSnapshot | null): void
+  refreshPresentation(): void
   setSelection(selection: ElementSelection | null): void
   setConnectingSource(nodeId: string | null): void
   setSpacePressed(active: boolean): void

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

@@ -1,6 +1,7 @@
 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 { resolveNodeSubtitle, supportsNodeSubtitle } from '../node-presentation/index.js';
 import { ThemeController, applyRuntimeTone } from '../theme/index.js';
 import { exportDiagramSvg, openSvgExportPreview } from '../export-svg/index.js';
 
@@ -16,6 +17,15 @@ function quantizeZoom(value, step = 0.05) {
   return Math.round(Math.round(clamped / step) * step * 1000) / 1000;
 }
 
+function eventShapeDiameter(node, definition) {
+  const maximum = definition.kind === 'boundary' ? 40 : 46;
+  const width = Number(node?.width);
+  const height = Number(node?.height);
+  const availableWidth = Number.isFinite(width) ? Math.max(0, width) : maximum;
+  const availableHeight = Number.isFinite(height) ? Math.max(0, height) : maximum;
+  return Math.min(maximum, availableWidth, availableHeight);
+}
+
 function estimateLabelTextWidth(value) {
   let width = 0;
   for (const ch of Array.from(String(value ?? ''))) {
@@ -262,18 +272,8 @@ function routePathData(points, routeStyle = 'rounded', cornerRadius = 14) {
   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 nodeAccessibleLabel(title, subtitle) {
+  return subtitle === null || subtitle === '' ? title : `${title}\n${subtitle}`;
 }
 
 function runtimeStatusIconId(presentation) {
@@ -599,6 +599,23 @@ export class DiagramRenderer {
   setModel(model) { this.model = model; this.render(); }
   setMode(mode) { this.mode = mode; this.render(); }
   setRuntime(runtime) { this.runtime = runtime; this.render(); }
+  refreshPresentation() {
+    if (this.mode === 'instance') return;
+    const subtitles = this._resolveDefinitionSubtitles();
+    const nodeElements = new Map(
+      [...this.nodeLayer.querySelectorAll('[data-node-id]')]
+        .map((nodeEl) => [nodeEl.dataset.nodeId, nodeEl]),
+    );
+    const updates = [];
+    for (const node of this.model.nodes) {
+      if (!subtitles.has(node.id)) continue;
+      const nodeEl = nodeElements.get(node.id);
+      if (!nodeEl || nodeEl.dataset.nodePresentation !== 'standard') continue;
+      const definition = NODE_DEFINITIONS[node.type] || NODE_DEFINITIONS.generic;
+      updates.push({ nodeEl, node, definition, subtitle: subtitles.get(node.id) });
+    }
+    updates.forEach((update) => this._applyDefinitionPresentation(update));
+  }
   setSelection(selection) {
     this.selection = selection;
     if (selection?.kind !== 'node' || selection.id !== this.quickMenuNodeId) this.quickMenuNodeId = null;
@@ -645,6 +662,7 @@ export class DiagramRenderer {
       nodeRenderers: options.nodeRenderers || this.svgExportOptions.nodeRenderers,
       htmlNodeRenderers: this.options.nodeRenderers,
       htmlNodeRenderer: this.options.nodeRenderer,
+      nodeSubtitleResolver: this.options.nodeSubtitleResolver,
       mode: this.mode,
       label: options.label || this.svgExportOptions.label,
     }, { ...this.svgExportOptions, ...options });
@@ -748,16 +766,38 @@ export class DiagramRenderer {
     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 });
+    const subtitles = this._resolveDefinitionSubtitles();
     this._syncSceneBounds();
     this._renderEdges();
     this._renderRuntimeTransitions();
     this._renderGuides();
-    this._renderNodes();
+    this._renderNodes(subtitles);
     this._applyTransform();
     this.container.dataset.mode = this.mode;
     if (this.emptyState) this.emptyState.hidden = this.model.nodes.length > 0 || !this.options.showEmptyState;
   }
 
+  _resolveDefinitionSubtitles() {
+    const subtitles = new Map();
+    if (this.mode === 'instance') return subtitles;
+    const mode = this.mode === 'viewer' ? 'viewer' : 'design';
+    for (const node of this.model.nodes) {
+      const definition = NODE_DEFINITIONS[node.type] || NODE_DEFINITIONS.generic;
+      if (!supportsNodeSubtitle(definition)) continue;
+      const renderers = this.options.nodeRenderers || {};
+      if (typeof (renderers[node.type] || renderers[definition.kind] || this.options.nodeRenderer) === 'function') continue;
+      subtitles.set(node.id, resolveNodeSubtitle({
+        node,
+        definition,
+        model: this.model,
+        mode,
+        surface: 'canvas',
+        resolver: this.options.nodeSubtitleResolver,
+      }));
+    }
+    return subtitles;
+  }
+
   _renderGuides() {
     this.guideSvg.replaceChildren();
     if (this.model.settings?.alignmentGuides === false) return;
@@ -977,7 +1017,7 @@ export class DiagramRenderer {
     requestAnimationFrame(() => { input.focus(); input.select(); });
   }
 
-  _renderNodes() {
+  _renderNodes(subtitles = new Map()) {
     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 };
@@ -1018,7 +1058,7 @@ export class DiagramRenderer {
       nodeEl.tabIndex = 0;
 
       const visual = this._resolveNodeVisual(node);
-      this._renderNodeShape(nodeEl, node, def, runtimeState, visual);
+      this._renderNodeShape(nodeEl, node, def, runtimeState, visual, subtitles.get(node.id));
       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');
@@ -1048,9 +1088,10 @@ export class DiagramRenderer {
     if (this.mode === 'design' && this.quickMenuNodeId) this._renderQuickMenu();
   }
 
-  _renderNodeShape(nodeEl, node, def, runtimeState, visual) {
+  _renderNodeShape(nodeEl, node, def, runtimeState, visual, subtitle) {
     if (def.kind === 'event' || def.kind === 'boundary') {
       const shape = el('div', 'mb-event-shape');
+      shape.style.setProperty('--mb-event-shape-size', `${eventShapeDiameter(node, def)}px`);
       shape.dataset.stage = def.eventStage || 'intermediate';
       shape.dataset.role = def.eventRole || '';
       if (def.kind === 'boundary' && node.properties?.cancelActivity === false) shape.classList.add('is-noninterrupting');
@@ -1136,6 +1177,7 @@ export class DiagramRenderer {
       nodeEl.appendChild(customHost);
       return;
     }
+    nodeEl.dataset.nodePresentation = 'standard';
     const header = el('div', 'mb-node-header');
     const icon = visual.iconId ? el('span', 'mb-node-icon') : null;
     const iconNode = visual.iconId
@@ -1185,14 +1227,33 @@ export class DiagramRenderer {
         titleWrap.appendChild(action);
       }
     } else {
-      titleWrap.appendChild(el('div', 'mb-node-title', node.name || def.label));
-      titleWrap.appendChild(el('div', 'mb-node-subtitle', displaySubtitle(node)));
+      const title = node.name || def.label;
+      titleWrap.appendChild(el('div', 'mb-node-title', title));
+      if (subtitle !== null) titleWrap.appendChild(el('div', 'mb-node-subtitle', subtitle));
+      const label = nodeAccessibleLabel(title, subtitle);
+      nodeEl.title = label;
+      nodeEl.setAttribute('aria-label', label);
     }
     if (icon) header.append(icon);
     header.append(titleWrap);
     nodeEl.appendChild(header);
   }
 
+  _applyDefinitionPresentation({ nodeEl, node, definition, subtitle }) {
+    const title = node.name || definition.label;
+    const titleWrap = nodeEl.querySelector('.mb-node-title-wrap');
+    const titleEl = titleWrap?.querySelector('.mb-node-title');
+    if (!titleWrap || !titleEl) return;
+    titleEl.textContent = title;
+    const currentSubtitle = titleWrap.querySelector('.mb-node-subtitle');
+    if (subtitle === null) currentSubtitle?.remove();
+    else if (currentSubtitle) currentSubtitle.textContent = subtitle;
+    else titleWrap.appendChild(el('div', 'mb-node-subtitle', subtitle));
+    const label = nodeAccessibleLabel(title, subtitle);
+    nodeEl.title = label;
+    nodeEl.setAttribute('aria-label', label);
+  }
+
   _resolveNodeVisual(node, surface = this.mode === 'instance' ? 'viewer' : 'canvas') {
     const visualModel = this.options.getVisualModel?.() || this.options.visualModel || this.model;
     return resolveNodeVisual(node, { surface, model: visualModel });