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

package/dist/shell.js

@@ -1,7 +1,6 @@
 import { createDefaultIconRegistry, hydrateIcons } from './modules/icons/index.js';
 import { createDefaultPaletteRegistry, PalettePanel } from './modules/palette/index.js';
 import { createDefaultPropertiesRegistry, PropertiesPanel } from './modules/properties/index.js';
-import { demoRuntime } from './modules/runtime/index.js';
 import { BpmnViewer } from './modules/viewer/index.js';
 import { ThemeController } from './modules/theme/index.js';
 import { openSvgExportPreview } from './modules/export-svg/index.js';
@@ -29,6 +28,43 @@ function mountSlot(slot, container, context) {
   return null;
 }
 
+const STUDIO_MODES = ['design', 'viewer', 'instance'];
+const STUDIO_MODE_OPTIONS = Object.freeze([
+  Object.freeze({ value: 'design', label: '流程设计', iconId: 'ui.design' }),
+  Object.freeze({ value: 'viewer', label: '流程展示', iconId: 'ui.preview' }),
+  Object.freeze({ value: 'instance', label: '审批轨迹', iconId: 'ui.trace' }),
+]);
+const STUDIO_SHELL_REGIONS = ['header', 'left', 'right', 'footer'];
+const DEFAULT_STUDIO_SHELL_REGIONS = Object.freeze({
+  header: 'default',
+  left: 'default',
+  right: 'default',
+  footer: 'default',
+});
+
+function normalizeAllowedModes(allowedModes, { allowDefault = true } = {}) {
+  if (allowDefault && (allowedModes === undefined || allowedModes === null)) return [...STUDIO_MODES];
+  if (!Array.isArray(allowedModes)) throw new Error('allowedModes must be an array of Studio modes.');
+  if (!allowedModes.length || allowedModes.some((mode) => !STUDIO_MODES.includes(mode)) || new Set(allowedModes).size !== allowedModes.length) {
+    throw new Error('allowedModes must contain one or more unique design, viewer, or instance modes.');
+  }
+  return [...allowedModes];
+}
+
+function normalizeRegions(regions, current = DEFAULT_STUDIO_SHELL_REGIONS) {
+  if (regions === undefined || regions === null) return { ...current };
+  if (!regions || typeof regions !== 'object' || Array.isArray(regions)) {
+    throw new Error('regions must be an object containing header, left, right, or footer modes.');
+  }
+  for (const name of Object.keys(regions)) {
+    if (!STUDIO_SHELL_REGIONS.includes(name)) throw new Error(`Unknown Studio Shell region: ${name}.`);
+    if (!['default', 'hidden'].includes(regions[name])) {
+      throw new Error(`Studio Shell region "${name}" must be "default" or "hidden".`);
+    }
+  }
+  return { ...current, ...regions };
+}
+
 export class BpmnStudioShell {
   constructor({
     container,
@@ -39,10 +75,13 @@ export class BpmnStudioShell {
     templateRegistry = createTemplateRegistry(),
     contextMenuRegistry = createDefaultContextMenuRegistry(),
     rendererOptions = {},
+    nodeSubtitleResolver = rendererOptions.nodeSubtitleResolver,
     slots = {},
     layout = null,
-    runtime = demoRuntime(),
+    regions = null,
+    runtime = null,
     mode = 'design',
+    allowedModes = null,
     projection = undefined,
     responsive = false,
     projectionOptions = null,
@@ -54,8 +93,13 @@ export class BpmnStudioShell {
     onThemeChange = null,
   } = {}) {
     if (!container || !studio) throw new Error('BpmnStudioShell requires container and studio.');
+    if (typeof layout === 'function' && regions !== null && regions !== undefined) {
+      throw new Error('BpmnStudioShell options "layout" and "regions" cannot be used together.');
+    }
+    const resolvedAllowedModes = normalizeAllowedModes(allowedModes);
+    const resolvedMode = resolvedAllowedModes.includes(mode) ? mode : resolvedAllowedModes[0];
     const instanceProjection = projection || (responsive ? 'auto' : 'approval');
-    const activeProjection = mode === 'instance' ? instanceProjection : 'standard';
+    const activeProjection = resolvedMode === 'instance' ? instanceProjection : 'standard';
     Object.assign(this, {
       container,
       studio,
@@ -63,27 +107,68 @@ export class BpmnStudioShell {
       paletteRegistry,
       templateRegistry,
       contextMenuRegistry,
-      rendererOptions,
+      rendererOptions: { ...rendererOptions, nodeSubtitleResolver },
       slots,
       runtime,
-      mode,
+      mode: resolvedMode,
+      allowedModes: resolvedAllowedModes,
       projection: activeProjection,
       _instanceProjection: instanceProjection,
       responsive,
       projectionOptions,
       runtimeAppearance,
       svgExport: svgExport || rendererOptions.svgExport || null,
+      _usesCustomLayout: typeof layout === 'function',
+      _regions: normalizeRegions(regions),
     });
     this.propertiesRegistry = propertiesRegistry || createDefaultPropertiesRegistry({ studio });
     this.interactions = createInteractionController({ studio, templates: templateRegistry });
     this._cleanups = [];
     this._instances = [];
+    this._modeListeners = new Set();
+    this._validationListeners = new Set();
+    this._modeViewports = new Map();
+    this._destroyed = false;
     this._svgExportPreview = null;
+    this.actions = Object.freeze({
+      undo: () => this.studio.undo(),
+      redo: () => this.studio.redo(),
+      beautify: (options) => {
+        this.studio.commands.beautify(options);
+        requestAnimationFrame(() => this._fitActive());
+      },
+      rerouteEdges: (options) => {
+        this.studio.commands.rerouteEdges(options);
+        requestAnimationFrame(() => this._fitActive());
+      },
+      fitView: () => this.fitView(),
+      validate: () => this._runValidation('toolbar'),
+      importXml: (xml, engine) => this.studio.importXml(xml, engine),
+      exportXml: (engine) => this.studio.exportXml(engine),
+      exportSvg: (options) => this.exportSvg(options),
+      openSvgExportPreview: (options) => this.openSvgExportPreview(options),
+    });
     this.container.classList.add('nova-studio-shell');
     this.themeController = new ThemeController({ root: this.container, theme, onChange: onThemeChange });
     this.container.style.setProperty('--nova-left-width', `${leftWidth}px`);
     this.container.style.setProperty('--nova-right-width', `${rightWidth}px`);
-    const context = { studio, iconRegistry, paletteRegistry, propertiesRegistry: this.propertiesRegistry, templateRegistry, contextMenuRegistry, interactions: this.interactions };
+    const context = {
+      studio,
+      shell: this,
+      actions: this.actions,
+      getState: () => this.studio.getState(),
+      subscribe: (listener) => this.studio.subscribe(listener),
+      getMode: () => this.getMode(),
+      getAllowedModes: () => this.getAllowedModes(),
+      subscribeMode: (listener) => this.subscribeMode(listener),
+      subscribeValidation: (listener) => this.subscribeValidation(listener),
+      iconRegistry,
+      paletteRegistry,
+      propertiesRegistry: this.propertiesRegistry,
+      templateRegistry,
+      contextMenuRegistry,
+      interactions: this.interactions,
+    };
     const mount = {
       canvas: (host, options = {}) => this._mountCanvas(host, options),
       palette: (host, options = {}) => this._mountPalette(host, options),
@@ -104,20 +189,8 @@ export class BpmnStudioShell {
     brandCopy.append(node('strong', '', 'BPMN Nova'), node('span', '', this.studio.model.name));
     brand.append(brandMark, brandCopy);
     const modeSwitch = node('nav', 'nova-studio-mode-switch');
+    modeSwitch.setAttribute('aria-label', 'Studio 模式');
     const modeButtons = new Map();
-    for (const item of [
-      { value: 'design', label: '流程设计', iconId: 'ui.design' },
-      { value: 'viewer', label: '流程展示', iconId: 'ui.preview' },
-      { value: 'instance', label: '审批轨迹', iconId: 'ui.trace' },
-    ]) {
-      const button = node('button');
-      button.type = 'button';
-      button.setAttribute('data-mode', item.value);
-      button.append(iconNode(item.iconId, 'nova-icon nova-icon-xs'), node('span', '', item.label));
-      button.addEventListener('click', () => this._setMode(item.value));
-      modeButtons.set(item.value, button);
-      modeSwitch.appendChild(button);
-    }
     const projectionSwitch = node('nav', 'nova-studio-projection-switch is-hidden');
     projectionSwitch.setAttribute('aria-label', '审批轨迹视图');
     const projectionButtons = new Map();
@@ -136,16 +209,16 @@ export class BpmnStudioShell {
     const centerControls = node('div', 'nova-studio-center-controls');
     centerControls.append(modeSwitch, projectionSwitch);
     const tools = node('div', 'nova-studio-tools');
-    const tool = (label, title, action, className = '', iconId = null) => {
+    const tool = (label, title, action, className = '', iconId = null, target = tools) => {
       const button = node('button', `nova-studio-tool ${className}`.trim()); button.type = 'button'; button.title = title;
       if (iconId) button.appendChild(iconNode(iconId));
       if (label) button.appendChild(node('span', '', label));
-      button.addEventListener('click', action); tools.appendChild(button); return button;
+      button.addEventListener('click', action); target.appendChild(button); return button;
     };
 
     const divider = () => tools.appendChild(node('span', 'nova-studio-tool-divider'));
-    const undo = tool('', '撤销 Ctrl/⌘+Z', () => this.studio.undo(), 'is-icon', 'ui.undo');
-    const redo = tool('', '重做 Ctrl/⌘+Y', () => this.studio.redo(), 'is-icon', 'ui.redo');
+    const undo = tool('', '撤销 Ctrl/⌘+Z', () => this.actions.undo(), 'is-icon', 'ui.undo');
+    const redo = tool('', '重做 Ctrl/⌘+Y', () => this.actions.redo(), 'is-icon', 'ui.redo');
     divider();
     const beautifySplit = node('div', 'nova-studio-beautify-split');
     const beautifyButton = node('button', 'nova-studio-tool nova-studio-beautify is-magic');
@@ -200,56 +273,62 @@ export class BpmnStudioShell {
     });
     beautifySplit.append(beautifyButton, beautifyCaret, beautifyMenu);
     tools.appendChild(beautifySplit);
-    const fit = tool('最佳视图', '适应画布内容', () => this._fitActive(), '', 'ui.fitView');
-
-    const importInput = node('input', 'nova-studio-import-input');
-    importInput.type = 'file';
-    importInput.accept = '.bpmn,.xml,.bpmn20.xml,text/xml,application/xml';
-    importInput.hidden = true;
-    const validateButton = tool('校验', '校验流程结构', () => this._showValidationStatus(), 'nova-studio-validate');
-    const importButton = tool('导入', '导入 BPMN XML', () => importInput.click(), 'nova-studio-import');
-    const exportMenu = node('div', 'nova-studio-export-menu');
-    const exportButton = node('button', 'nova-studio-tool nova-studio-export is-primary');
-    exportButton.type = 'button';
-    exportButton.title = '导出当前内容';
-    exportButton.append(node('span', '', '导出'), iconNode('ui.chevron', 'nova-icon nova-icon-xs'));
-    const exportPopover = node('div', 'nova-studio-export-popover is-hidden');
-    const exportSvgButton = node('button', 'nova-studio-export-option');
-    exportSvgButton.type = 'button';
-    exportSvgButton.append(iconNode('ui.preview'), node('strong', '', '导出 SVG'), node('small', '', '预览确认后下载'));
-    exportSvgButton.addEventListener('click', () => {
-      exportPopover.classList.add('is-hidden');
-      exportButton.focus({ preventScroll: true });
-      this.openSvgExportPreview();
-    });
-    const exportBpmnButton = node('button', 'nova-studio-export-option');
-    exportBpmnButton.type = 'button';
-    exportBpmnButton.append(iconNode('ui.design'), node('strong', '', '导出 BPMN'), node('small', '', '下载流程 XML'));
-    exportBpmnButton.addEventListener('click', () => {
-      exportPopover.classList.add('is-hidden');
-      this._exportBpmn();
-    });
-    exportPopover.append(exportSvgButton, exportBpmnButton);
-    exportButton.addEventListener('click', (event) => {
-      event.stopPropagation();
-      exportPopover.classList.toggle('is-hidden');
-    });
-    exportMenu.append(exportButton, exportPopover);
-    tools.appendChild(exportMenu);
-    importInput.addEventListener('change', async () => {
-      const file = importInput.files?.[0];
-      if (!file) return;
-      try {
-        this.studio.importXml(await file.text(), this.studio.model.engine);
-        this._setStatus('已导入 BPMN 文件', 'ok');
-        requestAnimationFrame(() => this._fitActive());
-      } catch (error) {
-        this._setStatus(`导入失败：${error.message}`, 'error');
-      } finally {
-        importInput.value = '';
-      }
-    });
-    tools.appendChild(importInput);
+    const headerActions = node('div', 'nova-studio-header-actions');
+    let validateButton = null;
+    let importButton = null;
+    let exportMenu = null;
+    let exportPopover = null;
+    let exportBpmnButton = null;
+    if (!this.slots.headerActions) {
+      const importInput = node('input', 'nova-studio-import-input');
+      importInput.type = 'file';
+      importInput.accept = '.bpmn,.xml,.bpmn20.xml,text/xml,application/xml';
+      importInput.hidden = true;
+      validateButton = tool('校验', '校验流程结构', () => this.actions.validate(), 'nova-studio-validate', null, headerActions);
+      importButton = tool('导入', '导入 BPMN XML', () => importInput.click(), 'nova-studio-import', null, headerActions);
+      exportMenu = node('div', 'nova-studio-export-menu');
+      const exportButton = node('button', 'nova-studio-tool nova-studio-export is-primary');
+      exportButton.type = 'button';
+      exportButton.title = '导出当前内容';
+      exportButton.append(node('span', '', '导出'), iconNode('ui.chevron', 'nova-icon nova-icon-xs'));
+      exportPopover = node('div', 'nova-studio-export-popover is-hidden');
+      const exportSvgButton = node('button', 'nova-studio-export-option');
+      exportSvgButton.type = 'button';
+      exportSvgButton.append(iconNode('ui.preview'), node('strong', '', '导出 SVG'), node('small', '', '预览确认后下载'));
+      exportSvgButton.addEventListener('click', () => {
+        exportPopover.classList.add('is-hidden');
+        exportButton.focus({ preventScroll: true });
+        this.actions.openSvgExportPreview();
+      });
+      exportBpmnButton = node('button', 'nova-studio-export-option');
+      exportBpmnButton.type = 'button';
+      exportBpmnButton.append(iconNode('ui.design'), node('strong', '', '导出 BPMN'), node('small', '', '下载流程 XML'));
+      exportBpmnButton.addEventListener('click', () => {
+        exportPopover.classList.add('is-hidden');
+        this._exportBpmn();
+      });
+      exportPopover.append(exportSvgButton, exportBpmnButton);
+      exportButton.addEventListener('click', (event) => {
+        event.stopPropagation();
+        exportPopover.classList.toggle('is-hidden');
+      });
+      exportMenu.append(exportButton, exportPopover);
+      headerActions.append(exportMenu, importInput);
+      importInput.addEventListener('change', async () => {
+        const file = importInput.files?.[0];
+        if (!file) return;
+        try {
+          this.actions.importXml(await file.text(), this.studio.model.engine);
+          this._setStatus('已导入 BPMN 文件', 'ok');
+          requestAnimationFrame(() => this._fitActive());
+        } catch (error) {
+          this._setStatus(`导入失败：${error.message}`, 'error');
+        } finally {
+          importInput.value = '';
+        }
+      });
+    }
+    tools.appendChild(headerActions);
     header.append(brand, centerControls, tools);
 
     const body = node('div', 'nova-studio-body');
@@ -295,18 +374,24 @@ export class BpmnStudioShell {
     this.container.append(header, body);
     hydrateIcons(this.container, this.iconRegistry);
     Object.assign(this, {
+      _header: header,
+      _headerStart: brand,
+      _headerActions: headerActions,
       _body: body,
       _left: left,
       _right: right,
+      _canvasColumn: canvasColumn,
+      _footer: statusbar,
       _canvasHost: canvasHost,
       _floatingHead: floatingHead,
       _scopeBack: scopeBack,
       _scopeNav: scopeNav,
       _modeButtons: modeButtons,
+      _modeSwitch: modeSwitch,
       _projectionSwitch: projectionSwitch,
       _projectionButtons: projectionButtons,
       _viewportTools: viewportTools,
-      _designControls: [undo, redo, beautifySplit, validateButton, importButton],
+      _designControls: [undo, redo, beautifySplit, validateButton, importButton].filter(Boolean),
       _exportMenu: exportMenu,
       _exportPopover: exportPopover,
       _exportBpmnButton: exportBpmnButton,
@@ -314,6 +399,7 @@ export class BpmnStudioShell {
       _defaultMount: mount,
       _usesDefaultProperties: !this.slots.right,
     });
+    this._rebuildModeButtons();
     this.canvas = mount.canvas(canvasHost, {
       rendererOptions: {
         ...this.rendererOptions,
@@ -328,8 +414,21 @@ export class BpmnStudioShell {
     else this.palette = mount.palette(left, { canvas: this.canvas });
     if (this.slots.right) this._recordCleanup(mountSlot(this.slots.right, right, { ...context, canvas: this.canvas }));
     else this.properties = mount.properties(right, { canvas: this.canvas });
-    if (this.slots.header) { header.innerHTML = ''; this._recordCleanup(mountSlot(this.slots.header, header, { ...context, canvas: this.canvas })); }
+    const mountHeaderActions = () => {
+      if (this.slots.headerActions) {
+        this._recordCleanup(mountSlot(this.slots.headerActions, headerActions, { ...context, canvas: this.canvas }));
+      }
+    };
+    if (this.slots.header) {
+      header.innerHTML = '';
+      this._recordCleanup(mountSlot(this.slots.header, header, { ...context, canvas: this.canvas }));
+    } else if (this.slots.headerStart) {
+      brand.innerHTML = '';
+      this._recordCleanup(mountSlot(this.slots.headerStart, brand, { ...context, canvas: this.canvas }));
+      mountHeaderActions();
+    } else mountHeaderActions();
     if (this.slots.footer) { statusbar.innerHTML = ''; this._recordCleanup(mountSlot(this.slots.footer, statusbar, { ...context, canvas: this.canvas })); }
+    hydrateIcons(this.container, this.iconRegistry);
     this._offState = this.studio.subscribe((event) => {
       if (event.type === 'historyChanged' || event.type === 'modelChanged') {
         undo.disabled = !this.studio.history.canUndo;
@@ -353,13 +452,12 @@ export class BpmnStudioShell {
     this._setStatus(`${initialGraph.nodes.length} 节点 · ${initialGraph.edges.length} 连线`, 'ok');
     const closeBeautify = (event) => {
       if (!beautifySplit.contains(event.target)) beautifyMenu.classList.add('is-hidden');
-      if (!exportMenu.contains(event.target)) exportPopover.classList.add('is-hidden');
+      if (exportMenu && !exportMenu.contains(event.target)) exportPopover.classList.add('is-hidden');
     };
     document.addEventListener('click', closeBeautify);
     this._cleanups.push(() => document.removeEventListener('click', closeBeautify));
     this._syncDensityButtons();
-    this._setMode(this.mode, { force: true });
-    requestAnimationFrame(() => fit.click());
+    this._setMode(this.mode, { force: true, emit: false });
   }
 
   _renderScopePath() {
@@ -399,14 +497,13 @@ export class BpmnStudioShell {
 
   _runBeautify(action = null) {
     const settings = this.studio.model.settings || {};
-    if (action === 'routing') this.studio.commands.rerouteEdges({ edgeStyle: 'rounded' });
-    else if (action === 'smooth') this.studio.commands.rerouteEdges({ edgeStyle: 'smooth' });
-    else this.studio.commands.beautify({
+    if (action === 'routing') this.actions.rerouteEdges({ edgeStyle: 'rounded' });
+    else if (action === 'smooth') this.actions.rerouteEdges({ edgeStyle: 'smooth' });
+    else this.actions.beautify({
       direction: action || settings.direction || 'horizontal',
       density: settings.layoutDensity || 'balanced',
       edgeStyle: settings.edgeStyle || 'rounded',
     });
-    requestAnimationFrame(() => this._fitActive());
   }
 
   _syncDensityButtons() {
@@ -415,93 +512,225 @@ export class BpmnStudioShell {
     this.container.querySelectorAll('[data-density]').forEach((button) => button.classList.toggle('is-active', button.dataset.density === value));
   }
 
-  _setMode(mode, { force = false } = {}) {
-    if (!['design', 'viewer', 'instance'].includes(mode)) return;
-    if (!force && this.mode === mode) return;
-    this.mode = mode;
-    this.projection = mode === 'instance' ? this._instanceProjection : 'standard';
-    this._modeButtons?.forEach((button, value) => button.classList.toggle('is-active', value === mode));
-    const readonly = mode !== 'design';
+  _rebuildModeButtons() {
+    if (!this._modeSwitch) return;
+    this._modeSwitch.replaceChildren();
+    this._modeButtons = new Map();
+    for (const item of STUDIO_MODE_OPTIONS.filter(({ value }) => this.allowedModes.includes(value))) {
+      const button = node('button');
+      const active = item.value === this.mode;
+      button.type = 'button';
+      button.setAttribute('data-mode', item.value);
+      button.setAttribute('aria-label', `切换到${item.label}`);
+      button.setAttribute('aria-pressed', String(active));
+      button.classList.toggle('is-active', active);
+      button.append(iconNode(item.iconId, 'nova-icon nova-icon-xs'), node('span', '', item.label));
+      button.addEventListener('click', () => this.setMode(item.value, 'toolbar'));
+      this._modeButtons.set(item.value, button);
+      this._modeSwitch.appendChild(button);
+    }
+    hydrateIcons(this._modeSwitch, this.iconRegistry);
+  }
+
+  _syncModeChrome() {
+    this._modeButtons?.forEach((button, value) => {
+      const active = value === this.mode;
+      button.classList.toggle('is-active', active);
+      button.setAttribute('aria-pressed', String(active));
+    });
+    const readonly = this.mode !== 'design';
     this._body?.classList.toggle('is-readonly', readonly);
+    this._applyRegions({ fit: false });
     this._floatingHead?.classList.toggle('is-hidden', readonly);
     this._designControls?.forEach((control) => control.classList.toggle('is-hidden-by-mode', readonly));
-    this._projectionSwitch?.classList.toggle('is-hidden', mode !== 'instance');
-    this._exportBpmnButton?.classList.toggle('is-hidden', mode !== 'design');
+    this._projectionSwitch?.classList.toggle('is-hidden', this.mode !== 'instance');
+    this._exportBpmnButton?.classList.toggle('is-hidden', this.mode !== 'design');
     this._syncProjectionButtons();
-    this._body?.classList.remove('is-timeline');
-
-    if (!this._canvasHost) return;
-    if (readonly) {
-      this.canvas?.destroy?.();
-      this.canvas = null;
-      this.viewer?.destroy?.();
-      this._canvasHost.innerHTML = '';
-      if (this._usesDefaultProperties) this.properties?.destroy?.();
-      this.viewer = new BpmnViewer({
-        container: this._canvasHost,
-        themeController: this.themeController,
-        runtimeAppearance: this.runtimeAppearance,
-        model: this.studio.model,
-        iconRegistry: this.iconRegistry,
-        nodeRenderers: this.rendererOptions.nodeRenderers,
-        nodeRenderer: this.rendererOptions.nodeRenderer,
-        runtime: mode === 'instance' ? this.runtime : null,
-        projection: this.projection,
-        responsive: this.responsive,
-        runtimeTraceOptions: this.rendererOptions.runtimeTraceOptions,
-        timeline: this.rendererOptions.timeline,
-        runtimeDetails: this.rendererOptions.runtimeDetails,
-        runtimePresenter: this.rendererOptions.runtimePresenter,
-        runtimeTraceProjector: this.rendererOptions.runtimeTraceProjector,
-        runtimeAssetResolver: this.rendererOptions.runtimeAssetResolver,
-        svgExport: this.svgExport,
-        runtimeTimelineRenderer: this.slots.runtimeTimeline
-          ? (timeline) => mountSlot(this.slots.runtimeTimeline, timeline.container, { ...timeline, studio: this.studio, shell: this })
-          : this.rendererOptions.runtimeTimelineRenderer,
-        onRuntimeTraceItemClick: this.rendererOptions.onRuntimeTraceItemClick,
-        runtimeDetailsRenderer: this.slots.runtimeDetails
-          ? (details) => mountSlot(this.slots.runtimeDetails, details.container, { ...details, studio: this.studio, shell: this })
-          : this.rendererOptions.runtimeDetailsRenderer,
-        onRuntimeDetailsOpen: this.rendererOptions.onRuntimeDetailsOpen,
-        runtimeTransitionDetailsRenderer: this.slots.runtimeTransitionDetails
-          ? (details) => mountSlot(this.slots.runtimeTransitionDetails, details.container, { ...details, studio: this.studio, shell: this })
-          : this.rendererOptions.runtimeTransitionDetailsRenderer,
-        onRuntimeTransitionDetailsOpen: this.rendererOptions.onRuntimeTransitionDetailsOpen,
-        onTraceClick: (payload) => {
-          const kind = payload.targetType === 'visit' ? 'node' : payload.targetType === 'transition' ? 'node' : payload.targetType;
-          this._renderReadonlyDetails({ kind, element: payload.element, presentation: payload.presentation, transition: payload.transition });
-          this.rendererOptions.onTraceClick?.(payload);
-        },
-        onProjectionChange: ({ active }) => {
-          const timeline = active === 'compact';
-          this._body?.classList.toggle('is-timeline', timeline);
-          this._viewportTools?.classList.toggle('is-hidden', timeline);
-          const status = timeline ? '审批轨迹 · 移动时间线' : active === 'standard' ? '审批轨迹 · 完整 BPMN' : '审批轨迹 · 实际路径';
-          this._setStatus(status, 'ok');
-        },
-        onViewportChange: (viewport) => this._handleViewport(viewport),
-        onElementClick: (selection) => {
-          if (!selection) this._renderReadonlyDetails(null);
-          this.rendererOptions.onElementClick?.(selection);
-        },
-      });
-      this._renderReadonlyDetails(null);
-      this._setStatus(mode === 'instance' ? '审批轨迹 · 运行实例' : '流程展示 · 只读预览', 'ok');
-    } else if (!this.canvas) {
-      this.viewer?.destroy?.();
-      this.viewer = null;
-      this._canvasHost.innerHTML = '';
-      this.canvas = this._defaultMount.canvas(this._canvasHost, {
-        rendererOptions: {
-          ...this.rendererOptions,
-          onViewportChange: (viewport) => this._handleViewport(viewport),
-        },
-      });
-      if (this.palette) this.palette.canvas = this.canvas;
-      if (this._usesDefaultProperties) this.properties = this._defaultMount.properties(this._right, { canvas: this.canvas });
-      this._setStatus(`${this.studio.model.nodes.length} 节点 · ${this.studio.model.edges.length} 连线`, 'ok');
+    this._syncProjectionChrome();
+  }
+
+  _syncProjectionChrome() {
+    const timeline = this.mode === 'instance' && this.viewer?.activeProjection === 'compact';
+    this._body?.classList.toggle('is-timeline', timeline);
+    this._viewportTools?.classList.toggle('is-hidden', timeline);
+    if (this.mode === 'design') {
+      const graph = this.studio.getActiveGraph();
+      this._setStatus(`${graph.nodes.length} 节点 · ${graph.edges.length} 连线`, 'ok');
+    } else if (this.mode === 'viewer') this._setStatus('流程展示 · 只读预览', 'ok');
+    else {
+      const active = this.viewer?.activeProjection || this.projection;
+      const status = active === 'compact' ? '审批轨迹 · 移动时间线' : active === 'standard' ? '审批轨迹 · 完整 BPMN' : '审批轨迹 · 实际路径';
+      this._setStatus(status, 'ok');
+    }
+  }
+
+  _captureModeViewport(mode = this.mode) {
+    if (this.viewer?.activeProjection === 'compact') return;
+    const renderer = this.canvas?.renderer || this.viewer?.renderer;
+    const viewport = renderer?.getViewportState?.();
+    if (viewport) this._modeViewports.set(mode, viewport);
+  }
+
+  _restoreModeViewport(mode) {
+    const viewport = this._modeViewports.get(mode);
+    const renderer = this.canvas?.renderer || this.viewer?.renderer;
+    if (viewport && renderer?.setViewportState) {
+      renderer.setViewportState(viewport);
+      return;
+    }
+    requestAnimationFrame(() => {
+      if (this._destroyed || this.mode !== mode) return;
+      this._fitActive();
+    });
+  }
+
+  _createViewer(container, mode) {
+    let viewer = null;
+    viewer = new BpmnViewer({
+      container,
+      themeController: this.themeController,
+      runtimeAppearance: this.runtimeAppearance,
+      model: this.studio.model,
+      mode,
+      iconRegistry: this.iconRegistry,
+      nodeRenderers: this.rendererOptions.nodeRenderers,
+      nodeRenderer: this.rendererOptions.nodeRenderer,
+      nodeSubtitleResolver: this.rendererOptions.nodeSubtitleResolver,
+      runtime: mode === 'instance' ? this.runtime : null,
+      projection: mode === 'instance' ? this._instanceProjection : 'standard',
+      responsive: this.responsive,
+      runtimeTraceOptions: this.rendererOptions.runtimeTraceOptions,
+      timeline: this.rendererOptions.timeline,
+      runtimeDetails: this.rendererOptions.runtimeDetails,
+      runtimePresenter: this.rendererOptions.runtimePresenter,
+      runtimeTraceProjector: this.rendererOptions.runtimeTraceProjector,
+      runtimeAssetResolver: this.rendererOptions.runtimeAssetResolver,
+      svgExport: this.svgExport,
+      runtimeTimelineRenderer: this.slots.runtimeTimeline
+        ? (timeline) => mountSlot(this.slots.runtimeTimeline, timeline.container, { ...timeline, studio: this.studio, shell: this })
+        : this.rendererOptions.runtimeTimelineRenderer,
+      onRuntimeTraceItemClick: this.rendererOptions.onRuntimeTraceItemClick,
+      runtimeDetailsRenderer: this.slots.runtimeDetails
+        ? (details) => mountSlot(this.slots.runtimeDetails, details.container, { ...details, studio: this.studio, shell: this })
+        : this.rendererOptions.runtimeDetailsRenderer,
+      onRuntimeDetailsOpen: this.rendererOptions.onRuntimeDetailsOpen,
+      runtimeTransitionDetailsRenderer: this.slots.runtimeTransitionDetails
+        ? (details) => mountSlot(this.slots.runtimeTransitionDetails, details.container, { ...details, studio: this.studio, shell: this })
+        : this.rendererOptions.runtimeTransitionDetailsRenderer,
+      onRuntimeTransitionDetailsOpen: this.rendererOptions.onRuntimeTransitionDetailsOpen,
+      onTraceClick: (payload) => {
+        const kind = payload.targetType === 'visit' ? 'node' : payload.targetType === 'transition' ? 'node' : payload.targetType;
+        this._renderReadonlyDetails({ kind, element: payload.element, presentation: payload.presentation, transition: payload.transition });
+        this.rendererOptions.onTraceClick?.(payload);
+      },
+      onProjectionChange: () => {
+        if (this.viewer === viewer) this._syncProjectionChrome();
+      },
+      onViewportChange: (viewport) => {
+        if (this.viewer === viewer) this._handleViewport(viewport);
+      },
+      onElementClick: (selection) => {
+        if (!selection) this._renderReadonlyDetails(null);
+        this.rendererOptions.onElementClick?.(selection);
+      },
+    });
+    return viewer;
+  }
+
+  _emitModeChange(previousMode, source) {
+    const event = Object.freeze({
+      mode: this.mode,
+      previousMode,
+      source,
+      allowedModes: this.getAllowedModes(),
+    });
+    for (const listener of [...this._modeListeners]) {
+      try {
+        listener(event);
+      } catch (error) {
+        console.error('BpmnStudioShell mode listener failed.', error);
+      }
+    }
+  }
+
+  _setMode(mode, { force = false, emit = true, source = 'api', allowedModes = this.allowedModes } = {}) {
+    if (this._destroyed || !allowedModes.includes(mode)) return false;
+    const previousMode = this.mode;
+    if (!force && previousMode === mode) return false;
+
+    const reusable = (mode === 'design' && this.canvas) || (mode !== 'design' && this.viewer);
+    if (force && previousMode === mode && reusable) {
+      this.allowedModes = allowedModes;
+      this.projection = mode === 'instance' ? this._instanceProjection : 'standard';
+      this._rebuildModeButtons();
+      this._syncModeChrome();
+      this._restoreModeViewport(mode);
+      return true;
+    }
+
+    if (!this._canvasHost) {
+      this.allowedModes = allowedModes;
+      this.mode = mode;
+      this.projection = mode === 'instance' ? this._instanceProjection : 'standard';
+      this._rebuildModeButtons();
+      this._syncModeChrome();
+      if (emit && previousMode !== mode) this._emitModeChange(previousMode, source);
+      return true;
     }
-    requestAnimationFrame(() => this._fitActive());
+
+    if (!force || previousMode !== mode) this._captureModeViewport(previousMode);
+    const previousHost = this._canvasHost;
+    const nextHost = node('main', 'nova-studio-canvas');
+    nextHost.hidden = true;
+    previousHost.parentNode?.insertBefore(nextHost, previousHost.nextSibling);
+    let nextCanvas = null;
+    let nextViewer = null;
+    try {
+      if (mode === 'design') {
+        nextCanvas = this._createCanvas(nextHost, {
+          rendererOptions: {
+            ...this.rendererOptions,
+            onViewportChange: (viewport) => {
+              if (this.canvas === nextCanvas) this._handleViewport(viewport);
+            },
+          },
+        });
+      } else nextViewer = this._createViewer(nextHost, mode);
+    } catch (error) {
+      nextCanvas?.destroy?.();
+      nextViewer?.destroy?.();
+      nextHost.remove();
+      this._syncModeChrome();
+      console.error(`BpmnStudioShell failed to mount mode "${mode}".`, error);
+      return false;
+    }
+
+    const previousCanvas = this.canvas;
+    const previousViewer = this.viewer;
+    nextHost.hidden = false;
+    previousHost.replaceWith(nextHost);
+    this._canvasHost = nextHost;
+    this.canvas = nextCanvas;
+    this.viewer = nextViewer;
+    this.allowedModes = allowedModes;
+    this.mode = mode;
+    this.projection = mode === 'instance' ? this._instanceProjection : 'standard';
+    if (nextCanvas) this._instances.push(nextCanvas);
+    this._releaseInstance(previousCanvas);
+    previousViewer?.destroy?.();
+
+    if (this.palette) this.palette.canvas = this.canvas;
+    if (this._usesDefaultProperties) {
+      this._releaseInstance(this.properties);
+      this.properties = null;
+      if (this.canvas) this.properties = this._mountProperties(this._right, { canvas: this.canvas });
+      else this._renderReadonlyDetails(null);
+    }
+    this._rebuildModeButtons();
+    this._syncModeChrome();
+    this._restoreModeViewport(mode);
+    if (emit && previousMode !== mode) this._emitModeChange(previousMode, source);
+    return true;
   }
 
   _handleViewport(viewport) {
@@ -552,7 +781,34 @@ export class BpmnStudioShell {
     if (this.canvas) this.canvas.fitView(72);
     else this.viewer?.fitView?.();
   }
-  setMode(mode) { this._setMode(mode); }
+  getMode() { return this.mode; }
+  getAllowedModes() { return Object.freeze([...this.allowedModes]); }
+  subscribeMode(listener) {
+    if (typeof listener !== 'function') throw new TypeError('subscribeMode() requires a listener function.');
+    if (this._destroyed) return () => {};
+    this._modeListeners.add(listener);
+    return () => this._modeListeners.delete(listener);
+  }
+  subscribeValidation(listener) {
+    if (typeof listener !== 'function') throw new TypeError('subscribeValidation() requires a listener function.');
+    if (this._destroyed) return () => {};
+    this._validationListeners.add(listener);
+    return () => this._validationListeners.delete(listener);
+  }
+  setMode(mode, source = 'api') { return this._setMode(mode, { source }); }
+  setAllowedModes(modes) {
+    const next = normalizeAllowedModes(modes, { allowDefault: false });
+    if (this._destroyed) return this.getAllowedModes();
+    if (next.length === this.allowedModes.length && next.every((mode, index) => mode === this.allowedModes[index])) {
+      return this.getAllowedModes();
+    }
+    if (next.includes(this.mode)) {
+      this.allowedModes = next;
+      this._rebuildModeButtons();
+      this._syncModeChrome();
+    } else this._setMode(next[0], { source: 'allowed-modes', allowedModes: next });
+    return this.getAllowedModes();
+  }
   setRuntime(runtime) {
     this.runtime = runtime;
     if (this.mode === 'instance') this.viewer?.setRuntime(runtime);
@@ -563,6 +819,34 @@ export class BpmnStudioShell {
     this._syncProjectionButtons();
     if (this.mode === 'instance') this.viewer?.setProjection?.(projection);
   }
+  getRegions() { return Object.freeze({ ...this._regions }); }
+  setRegions(regions) {
+    if (this._usesCustomLayout) {
+      throw new Error('BpmnStudioShell setRegions() is unavailable when a custom layout is active.');
+    }
+    const next = normalizeRegions(regions, this._regions);
+    const changed = STUDIO_SHELL_REGIONS.some((name) => next[name] !== this._regions[name]);
+    this._regions = next;
+    if (changed) this._applyRegions();
+    return this.getRegions();
+  }
+  _applyRegions({ fit = true } = {}) {
+    if (this._usesCustomLayout || !this._body) return;
+    const readonly = this.mode !== 'design';
+    const headerHidden = this._regions.header === 'hidden';
+    const leftHidden = readonly || this._regions.left === 'hidden';
+    const rightHidden = this._regions.right === 'hidden';
+    const footerHidden = this._regions.footer === 'hidden';
+    this.container.classList.toggle('is-header-hidden', headerHidden);
+    this._body.classList.toggle('is-left-hidden', leftHidden);
+    this._body.classList.toggle('is-right-hidden', rightHidden);
+    this._canvasColumn?.classList.toggle('is-footer-hidden', footerHidden);
+    if (this._header) this._header.hidden = headerHidden;
+    if (this._left) this._left.hidden = leftHidden;
+    if (this._right) this._right.hidden = rightHidden;
+    if (this._footer) this._footer.hidden = footerHidden;
+    if (fit) requestAnimationFrame(() => this._fitActive());
+  }
   setTheme(theme) { return this.themeController.setTheme(theme); }
   setThemeMode(mode) { return this.themeController.setMode(mode); }
   getThemeState() { return this.themeController.getState(); }
@@ -571,6 +855,8 @@ export class BpmnStudioShell {
     this.runtimeAppearance = runtimeAppearance || null;
     this.viewer?.setRuntimeAppearance?.(this.runtimeAppearance);
   }
+  refreshPresentation() { (this.canvas || this.viewer)?.refreshPresentation?.(); }
+  validate() { return this._runValidation('api'); }
 
   _syncProjectionButtons() {
     this._projectionButtons?.forEach((button, value) => {
@@ -617,18 +903,38 @@ export class BpmnStudioShell {
     this._statusDot.className = `is-${tone}`;
   }
 
-  _showValidationStatus() {
+  _runValidation(source) {
     const issues = this.studio.validate();
+    const errorCount = issues.filter((issue) => issue.level === 'error').length;
+    const warningCount = issues.filter((issue) => issue.level === 'warning').length;
     if (!issues.length) this._setStatus('校验通过：流程结构正常', 'ok');
     else {
-      const errors = issues.filter((issue) => issue.level === 'error').length;
-      this._setStatus(`校验完成：${errors ? `${errors} 个错误 · ` : ''}${issues.length} 个提示`, errors ? 'error' : 'warning');
+      const summary = [
+        errorCount ? `${errorCount} 个错误` : null,
+        warningCount ? `${warningCount} 个警告` : null,
+      ].filter(Boolean).join(' · ');
+      this._setStatus(`校验完成：${summary}`, errorCount ? 'error' : 'warning');
+    }
+    const eventIssues = Object.freeze(issues.map((issue) => Object.freeze({ ...issue })));
+    const event = Object.freeze({
+      source,
+      valid: errorCount === 0,
+      errorCount,
+      warningCount,
+      issues: eventIssues,
+    });
+    for (const listener of [...this._validationListeners]) {
+      try {
+        listener(event);
+      } catch (error) {
+        console.error('BpmnStudioShell validation listener failed.', error);
+      }
     }
     return issues;
   }
 
   _exportBpmn() {
-    const blob = new Blob([this.studio.exportXml()], { type: 'application/xml;charset=utf-8' });
+    const blob = new Blob([this.actions.exportXml()], { type: 'application/xml;charset=utf-8' });
     const url = URL.createObjectURL(blob);
     const anchor = node('a');
     anchor.href = url;
@@ -641,8 +947,8 @@ export class BpmnStudioShell {
   }
 
   _recordCleanup(cleanup) { if (typeof cleanup === 'function') this._cleanups.push(cleanup); }
-  _mountCanvas(container, options = {}) {
-    const instance = new BpmnCanvas({
+  _createCanvas(container, options = {}) {
+    return new BpmnCanvas({
       container,
       studio: this.studio,
       interactions: this.interactions,
@@ -657,6 +963,9 @@ export class BpmnStudioShell {
       },
       themeController: this.themeController,
     });
+  }
+  _mountCanvas(container, options = {}) {
+    const instance = this._createCanvas(container, options);
     this._instances.push(instance); return instance;
   }
   _mountPalette(container, options = {}) {
@@ -667,11 +976,25 @@ export class BpmnStudioShell {
     const instance = new PropertiesPanel({ container, studio: this.studio, registry: this.propertiesRegistry, iconRegistry: this.iconRegistry, themeController: this.themeController, ...options });
     instance.render(); this._instances.push(instance); return instance;
   }
+  _releaseInstance(instance) {
+    if (!instance) return;
+    const index = this._instances.indexOf(instance);
+    if (index >= 0) this._instances.splice(index, 1);
+    instance.destroy?.();
+  }
   destroy() {
+    if (this._destroyed) return;
+    this._destroyed = true;
+    this._modeListeners.clear();
+    this._validationListeners.clear();
     this._svgExportPreview?.close?.({ immediate: true });
     this._svgExportPreview = null;
     this._cleanups.splice(0).reverse().forEach((cleanup) => cleanup?.());
+    this.viewer?.destroy?.();
+    this.viewer = null;
     this._instances.splice(0).reverse().forEach((instance) => instance.destroy?.());
+    this.canvas = null;
+    this.properties = null;
     this.container.innerHTML = '';
     this.container.classList.remove('nova-studio-shell');
     this.themeController.destroy();