@bpmn-nova/studio 0.3.4-preview → 0.3.6-preview

package/dist/shell.js

@@ -5,6 +5,15 @@ import { BpmnViewer } from './modules/viewer/index.js';
 import { ThemeController } from './modules/theme/index.js';
 import { openSvgExportPreview } from './modules/export-svg/index.js';
 import { BpmnCanvas } from './canvas.js';
+import { StudioSidebars } from './sidebars.js';
+import { createPanelSelection, samePanelSelection } from './panel-selection.js';
+import {
+  applyStudioControlMetrics,
+  createStudioUiContext,
+  normalizeStudioConfig,
+  normalizeStudioRegions,
+  resolveStudioControlMetrics,
+} from './config.js';
 import { createDefaultContextMenuRegistry } from './context-menu.js';
 import { createInteractionController, createTemplateRegistry } from './interactions.js';
 
@@ -24,10 +33,25 @@ function iconNode(id, className = 'nova-icon nova-icon-sm') {
 function mountSlot(slot, container, context) {
   if (!slot) return null;
   if (slot instanceof HTMLElement) { container.appendChild(slot); return null; }
-  if (typeof slot === 'function') return slot({ container, ...context });
+  if (typeof slot === 'function') return slot(Object.defineProperties({ container }, Object.getOwnPropertyDescriptors(context)));
   return null;
 }
 
+function sameConfigValue(left, right) {
+  if (Object.is(left, right)) return true;
+  if (!left || !right || typeof left !== 'object' || typeof right !== 'object') return false;
+  if (Array.isArray(left) || Array.isArray(right)) {
+    return Array.isArray(left)
+      && Array.isArray(right)
+      && left.length === right.length
+      && left.every((value, index) => sameConfigValue(value, right[index]));
+  }
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+  return leftKeys.length === rightKeys.length
+    && leftKeys.every((key) => Object.prototype.hasOwnProperty.call(right, key) && sameConfigValue(left[key], right[key]));
+}
+
 const STUDIO_MODES = ['design', 'viewer', 'instance'];
 const STUDIO_MODE_OPTIONS = Object.freeze([
   Object.freeze({ value: 'design', label: '流程设计', iconId: 'ui.design' }),
@@ -35,12 +59,6 @@ const STUDIO_MODE_OPTIONS = Object.freeze([
   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];
@@ -51,54 +69,62 @@ function normalizeAllowedModes(allowedModes, { allowDefault = true } = {}) {
   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,
-    studio,
-    iconRegistry = createDefaultIconRegistry(),
-    paletteRegistry = createDefaultPaletteRegistry(),
-    propertiesRegistry = null,
-    templateRegistry = createTemplateRegistry(),
-    contextMenuRegistry = createDefaultContextMenuRegistry(),
-    rendererOptions = {},
-    nodeSubtitleResolver = rendererOptions.nodeSubtitleResolver,
-    slots = {},
-    layout = null,
-    regions = null,
-    runtime = null,
-    mode = 'design',
-    allowedModes = null,
-    projection = undefined,
-    responsive = false,
-    projectionOptions = null,
-    leftWidth = 244,
-    rightWidth = 360,
-    theme = null,
-    runtimeAppearance = null,
-    svgExport = null,
-    onThemeChange = null,
-  } = {}) {
+  constructor(options = {}) {
+    const {
+      container,
+      studio,
+      config,
+      iconRegistry = createDefaultIconRegistry(),
+      paletteRegistry = createDefaultPaletteRegistry(),
+      propertiesRegistry = null,
+      templateRegistry = createTemplateRegistry(),
+      contextMenuRegistry = createDefaultContextMenuRegistry(),
+      rendererOptions = {},
+      nodeSubtitleResolver = rendererOptions.nodeSubtitleResolver,
+      slots = {},
+      layout = null,
+      regions = null,
+      runtime = null,
+      mode = 'design',
+      allowedModes = null,
+      projection = undefined,
+      responsive = false,
+      projectionOptions = null,
+      leftWidth = 244,
+      rightWidth = 360,
+      timeline,
+      runtimeDetails,
+      runtimeTraceOptions,
+      theme = null,
+      runtimeAppearance = null,
+      svgExport = null,
+      onThemeChange = null,
+    } = options;
     if (!container || !studio) throw new Error('BpmnStudioShell requires container and studio.');
-    if (typeof layout === 'function' && regions !== null && regions !== undefined) {
+    const configuredRegions = regions !== null && regions !== undefined
+      || config?.ui?.regions !== null && config?.ui?.regions !== undefined;
+    if (typeof layout === 'function' && configuredRegions) {
       throw new Error('BpmnStudioShell options "layout" and "regions" cannot be used together.');
     }
+    const fallbackConfig = {
+      viewer: {
+        timeline: rendererOptions.timeline,
+        runtimeDetails: rendererOptions.runtimeDetails,
+        runtimeTraceOptions: rendererOptions.runtimeTraceOptions,
+      },
+      export: rendererOptions.svgExport,
+    };
+    const legacyConfig = {};
+    for (const name of ['regions', 'leftWidth', 'rightWidth', 'responsive', 'projectionOptions', 'timeline', 'runtimeDetails', 'runtimeTraceOptions', 'svgExport']) {
+      if (Object.prototype.hasOwnProperty.call(options, name)) legacyConfig[name] = options[name];
+    }
+    const normalizedConfig = normalizeStudioConfig(config, { fallback: fallbackConfig, legacy: legacyConfig });
+    const resolvedUi = normalizedConfig.ui;
+    const resolvedViewer = normalizedConfig.viewer;
     const resolvedAllowedModes = normalizeAllowedModes(allowedModes);
     const resolvedMode = resolvedAllowedModes.includes(mode) ? mode : resolvedAllowedModes[0];
-    const instanceProjection = projection || (responsive ? 'auto' : 'approval');
+    const instanceProjection = projection || (resolvedViewer.responsive ? 'auto' : 'approval');
     const activeProjection = resolvedMode === 'instance' ? instanceProjection : 'standard';
     Object.assign(this, {
       container,
@@ -107,26 +133,40 @@ export class BpmnStudioShell {
       paletteRegistry,
       templateRegistry,
       contextMenuRegistry,
-      rendererOptions: { ...rendererOptions, nodeSubtitleResolver },
+      rendererOptions: {
+        ...rendererOptions,
+        nodeSubtitleResolver,
+        timeline: resolvedViewer.timeline,
+        runtimeDetails: resolvedViewer.runtimeDetails,
+        runtimeTraceOptions: resolvedViewer.runtimeTraceOptions,
+      },
       slots,
       runtime,
       mode: resolvedMode,
       allowedModes: resolvedAllowedModes,
       projection: activeProjection,
       _instanceProjection: instanceProjection,
-      responsive,
-      projectionOptions,
+      _projectionExplicit: projection !== undefined,
+      responsive: resolvedViewer.responsive,
+      projectionOptions: resolvedViewer.projectionOptions || null,
       runtimeAppearance,
-      svgExport: svgExport || rendererOptions.svgExport || null,
+      svgExport: normalizedConfig.export || null,
       _usesCustomLayout: typeof layout === 'function',
-      _regions: normalizeRegions(regions),
+      _regions: normalizeStudioRegions(resolvedUi.regions),
+      _config: normalizedConfig,
+      _configFallback: fallbackConfig,
+      _legacyConfig: legacyConfig,
+      _controlMetrics: resolveStudioControlMetrics(resolvedUi.controlSize),
     });
+    this.ui = createStudioUiContext(() => this._controlMetrics);
     this.propertiesRegistry = propertiesRegistry || createDefaultPropertiesRegistry({ studio });
     this.interactions = createInteractionController({ studio, templates: templateRegistry });
     this._cleanups = [];
     this._instances = [];
     this._modeListeners = new Set();
     this._validationListeners = new Set();
+    this._panelSelectionListeners = new Set();
+    this._panelSelection = Object.freeze({ selection: null, selectedElement: null, trace: null });
     this._modeViewports = new Map();
     this._destroyed = false;
     this._svgExportPreview = null;
@@ -150,18 +190,25 @@ export class BpmnStudioShell {
     });
     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`);
+    applyStudioControlMetrics(this.container, this._controlMetrics);
+    this.container.style.setProperty('--nova-left-width', `${resolvedUi.sidebarWidth.left}px`);
+    this.container.style.setProperty('--nova-right-width', `${resolvedUi.sidebarWidth.right}px`);
     const context = {
       studio,
       shell: this,
       actions: this.actions,
+      ui: this.ui,
       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),
+      getSidebarState: () => this.getSidebarState(),
+      setSidebarCollapsed: (side, collapsed) => this.setSidebarCollapsed(side, collapsed),
+      subscribeSidebarChange: (listener) => this.subscribeSidebarChange(listener),
+      getPanelSelection: () => this.getPanelSelection(),
+      subscribePanelSelection: (listener) => this.subscribePanelSelection(listener),
       iconRegistry,
       paletteRegistry,
       propertiesRegistry: this.propertiesRegistry,
@@ -178,6 +225,12 @@ export class BpmnStudioShell {
       const cleanup = layout({ container, ...context, mount });
       if (typeof cleanup === 'function') this._cleanups.push(cleanup);
     } else this._buildDefault(context, mount);
+    if (!this._usesCustomLayout) {
+      this._updatePanelSelection();
+      this._recordCleanup(this.studio.subscribe((event) => {
+        if (['selectionChanged', 'modelChanged', 'scopeChanged'].includes(event.type)) this._updatePanelSelection();
+      }));
+    }
   }
 
   _buildDefault(context, mount) {
@@ -194,18 +247,6 @@ export class BpmnStudioShell {
     const projectionSwitch = node('nav', 'nova-studio-projection-switch is-hidden');
     projectionSwitch.setAttribute('aria-label', '审批轨迹视图');
     const projectionButtons = new Map();
-    const projectionOptions = this.projectionOptions || [
-      { value: this.responsive ? 'auto' : 'approval', label: '实际路径' },
-      { value: 'standard', label: '完整 BPMN' },
-    ];
-    for (const item of projectionOptions) {
-      const button = node('button', '', item.label);
-      button.type = 'button';
-      button.dataset.projection = item.value;
-      button.addEventListener('click', () => this.setProjection(item.value));
-      projectionButtons.set(item.value, button);
-      projectionSwitch.appendChild(button);
-    }
     const centerControls = node('div', 'nova-studio-center-controls');
     centerControls.append(modeSwitch, projectionSwitch);
     const tools = node('div', 'nova-studio-tools');
@@ -370,6 +411,10 @@ export class BpmnStudioShell {
     statusbar.append(statusLeft, viewportTools);
     canvasColumn.append(canvasStage, statusbar);
     const right = node('aside', 'nova-studio-right');
+    const leftContent = node('div', 'nova-studio-sidebar-content nova-studio-left-content');
+    const rightContent = node('div', 'nova-studio-sidebar-content nova-studio-right-content');
+    left.appendChild(leftContent);
+    right.appendChild(rightContent);
     body.append(left, canvasColumn, right);
     this.container.append(header, body);
     hydrateIcons(this.container, this.iconRegistry);
@@ -380,6 +425,8 @@ export class BpmnStudioShell {
       _body: body,
       _left: left,
       _right: right,
+      _leftContent: leftContent,
+      _rightContent: rightContent,
       _canvasColumn: canvasColumn,
       _footer: statusbar,
       _canvasHost: canvasHost,
@@ -399,7 +446,9 @@ export class BpmnStudioShell {
       _defaultMount: mount,
       _usesDefaultProperties: !this.slots.right,
     });
+    this._sidebars = new StudioSidebars(this, { body, left, right, leftContent, rightContent });
     this._rebuildModeButtons();
+    this._rebuildProjectionButtons();
     this.canvas = mount.canvas(canvasHost, {
       rendererOptions: {
         ...this.rendererOptions,
@@ -410,10 +459,9 @@ export class BpmnStudioShell {
       },
     });
     this._renderScopePath();
-    if (this.slots.left) this._recordCleanup(mountSlot(this.slots.left, left, { ...context, canvas: this.canvas }));
-    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.left) this._recordCleanup(mountSlot(this.slots.left, leftContent, { ...context, canvas: this.canvas }));
+    else this.palette = mount.palette(leftContent, { canvas: this.canvas });
+    this._setRightSlot(this.slots.right);
     const mountHeaderActions = () => {
       if (this.slots.headerActions) {
         this._recordCleanup(mountSlot(this.slots.headerActions, headerActions, { ...context, canvas: this.canvas }));
@@ -532,6 +580,26 @@ export class BpmnStudioShell {
     hydrateIcons(this._modeSwitch, this.iconRegistry);
   }
 
+  _rebuildProjectionButtons() {
+    if (!this._projectionSwitch) return;
+    this._projectionSwitch.replaceChildren();
+    this._projectionButtons = new Map();
+    const options = this.projectionOptions || [
+      { value: this.responsive ? 'auto' : 'approval', label: '实际路径' },
+      { value: 'standard', label: '完整 BPMN' },
+    ];
+    for (const item of options) {
+      const button = node('button', '', item.label);
+      button.type = 'button';
+      button.dataset.projection = item.value;
+      button.addEventListener('click', () => this.setProjection(item.value));
+      this._projectionButtons.set(item.value, button);
+      this._projectionSwitch.appendChild(button);
+    }
+    hydrateIcons(this._projectionSwitch, this.iconRegistry);
+    this._syncProjectionButtons();
+  }
+
   _syncModeChrome() {
     this._modeButtons?.forEach((button, value) => {
       const active = value === this.mode;
@@ -619,10 +687,11 @@ export class BpmnStudioShell {
         : 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);
       },
+      _onPanelSelection: (trace) => {
+        if (viewer && this.viewer === viewer) this._updatePanelSelection(trace);
+      },
       onProjectionChange: () => {
         if (this.viewer === viewer) this._syncProjectionChrome();
       },
@@ -630,7 +699,6 @@ export class BpmnStudioShell {
         if (this.viewer === viewer) this._handleViewport(viewport);
       },
       onElementClick: (selection) => {
-        if (!selection) this._renderReadonlyDetails(null);
         this.rendererOptions.onElementClick?.(selection);
       },
     });
@@ -717,17 +785,19 @@ export class BpmnStudioShell {
     this.projection = mode === 'instance' ? this._instanceProjection : 'standard';
     if (nextCanvas) this._instances.push(nextCanvas);
     this._releaseInstance(previousCanvas);
+    if (this._sidebars?.motionViewer === previousViewer) this._sidebars.finishMotion({ resume: false });
     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 });
+      if (this.canvas) this.properties = this._mountProperties(this._rightContent, { canvas: this.canvas });
       else this._renderReadonlyDetails(null);
     }
     this._rebuildModeButtons();
     this._syncModeChrome();
+    this._updatePanelSelection(null);
     this._restoreModeViewport(mode);
     if (emit && previousMode !== mode) this._emitModeChange(previousMode, source);
     return true;
@@ -738,11 +808,56 @@ export class BpmnStudioShell {
     this.rendererOptions.onViewportChange?.(viewport);
   }
 
+  // Adapter-only seam: replace right content without remounting the workbench.
+  _setRightSlot(slot) {
+    if (this._destroyed || !this._rightContent) return;
+    const next = slot || null;
+    if (this._rightSlot === next) return;
+    this._rightSlotCleanup?.();
+    this._rightSlotCleanup = null;
+    this._releaseInstance(this.properties);
+    this.properties = null;
+    this._rightContent.replaceChildren();
+    this._rightSlot = next;
+    this._usesDefaultProperties = !next;
+    if (next) {
+      const shell = this;
+      const context = { ...this._defaultContext, get canvas() { return shell.canvas; } };
+      this._rightSlotCleanup = mountSlot(next, this._rightContent, context);
+    } else if (this.canvas) this.properties = this._mountProperties(this._rightContent, { canvas: this.canvas });
+    else this._renderReadonlyDetails(this._readonlyPanelDetails());
+  }
+
+  getPanelSelection() { return this._panelSelection; }
+  subscribePanelSelection(listener) {
+    if (typeof listener !== 'function') throw new TypeError('subscribePanelSelection() requires a listener function.');
+    if (this._destroyed) return () => {};
+    this._panelSelectionListeners.add(listener);
+    return () => this._panelSelectionListeners.delete(listener);
+  }
+  _readonlyPanelDetails() {
+    const { selection, selectedElement, trace } = this._panelSelection;
+    return selectedElement ? { kind: selection?.kind, element: selectedElement, presentation: trace?.presentation, transition: trace?.transition } : null;
+  }
+  _updatePanelSelection(trace = this._panelSelection.trace) {
+    if (this._destroyed) return;
+    const next = createPanelSelection(this.studio, this.mode === 'design' ? null : this.viewer, trace);
+    if (samePanelSelection(next, this._panelSelection)) {
+      if (this.mode !== 'design' && !next.selectedElement) this._renderReadonlyDetails(null);
+      return;
+    }
+    this._panelSelection = next;
+    if (this.mode !== 'design') this._renderReadonlyDetails(this._readonlyPanelDetails());
+    for (const listener of [...this._panelSelectionListeners]) {
+      try { listener(next); } catch (error) { console.error('BpmnStudioShell panel selection listener failed.', error); }
+    }
+  }
+
   _renderReadonlyDetails(selection) {
-    if (!this._usesDefaultProperties || !this._right) return;
+    if (!this._usesDefaultProperties || !this._rightContent) return;
     const model = this.studio.model;
     const element = selection?.element;
-    this._right.innerHTML = '';
+    this._rightContent.innerHTML = '';
     const panel = node('div', 'nova-studio-readonly-panel');
     const header = node('header', 'nova-studio-readonly-header');
     header.append(node('strong', '', element?.name || (selection?.kind === 'edge' ? '流程连线' : model.name)), node('span', '', element?.id || model.id));
@@ -769,7 +884,7 @@ export class BpmnStudioShell {
       body.appendChild(row);
     }
     panel.appendChild(body);
-    this._right.appendChild(panel);
+    this._rightContent.appendChild(panel);
   }
 
   _zoomActive(factor) { (this.canvas || this.viewer)?.zoomBy?.(factor); }
@@ -781,6 +896,91 @@ export class BpmnStudioShell {
     if (this.canvas) this.canvas.fitView(72);
     else this.viewer?.fitView?.();
   }
+  getConfig() {
+    const state = this.studio.getState();
+    const modeling = Object.freeze({
+      propertiesProfile: state.propertiesProfile,
+      ...(state.allowedNodeTypes ? { allowedNodeTypes: Object.freeze([...state.allowedNodeTypes]) } : {}),
+      ...(state.allowedEdgeTypes ? { allowedEdgeTypes: Object.freeze([...state.allowedEdgeTypes]) } : {}),
+    });
+    return Object.freeze({
+      modeling,
+      ui: this._config.ui,
+      viewer: this._config.viewer,
+      ...(this._config.export ? { export: this._config.export } : {}),
+    });
+  }
+  setConfig(config) {
+    if (this._destroyed) return this.getConfig();
+    const next = normalizeStudioConfig(config, {
+      fallback: this._configFallback,
+      legacy: this._legacyConfig,
+    });
+    const hasRegions = config?.ui
+      && Object.prototype.hasOwnProperty.call(config.ui, 'regions')
+      && config.ui.regions !== undefined
+      && config.ui.regions !== null;
+    if (this._usesCustomLayout && hasRegions) {
+      throw new Error('BpmnStudioShell config.ui.regions is unavailable when a custom layout is active.');
+    }
+
+    const previous = this._config;
+    const previousSidebars = this._sidebars?.getState();
+    const nextMetrics = resolveStudioControlMetrics(next.ui.controlSize);
+    const regionsChanged = !sameConfigValue(previous.ui.regions, next.ui.regions);
+    const projectionOptionsChanged = !sameConfigValue(previous.viewer.projectionOptions, next.viewer.projectionOptions);
+    const responsiveChanged = previous.viewer.responsive !== next.viewer.responsive;
+    const displayChanged = ['timeline', 'runtimeDetails', 'runtimeTraceOptions']
+      .some((name) => !sameConfigValue(previous.viewer[name], next.viewer[name]));
+    const exportChanged = !sameConfigValue(previous.export, next.export);
+    const nextDefaultProjection = next.viewer.responsive ? 'auto' : 'approval';
+    const projectionChanged = responsiveChanged
+      && !this._projectionExplicit
+      && this._instanceProjection !== nextDefaultProjection;
+    const viewport = this.viewer?.activeProjection === 'compact'
+      ? null
+      : (this.canvas?.renderer || this.viewer?.renderer)?.getViewportState?.();
+
+    this._config = next;
+    this._controlMetrics = nextMetrics;
+    applyStudioControlMetrics(this.container, nextMetrics);
+    this.container.style.setProperty('--nova-left-width', `${next.ui.sidebarWidth.left}px`);
+    this.container.style.setProperty('--nova-right-width', `${next.ui.sidebarWidth.right}px`);
+    this._regions = normalizeStudioRegions(next.ui.regions);
+    this.responsive = next.viewer.responsive;
+    this.projectionOptions = next.viewer.projectionOptions || null;
+    this.rendererOptions.timeline = next.viewer.timeline;
+    this.rendererOptions.runtimeDetails = next.viewer.runtimeDetails;
+    this.rendererOptions.runtimeTraceOptions = next.viewer.runtimeTraceOptions;
+    this.svgExport = next.export || null;
+    this.rendererOptions.svgExport = this.svgExport;
+    if (projectionChanged) {
+      this._instanceProjection = nextDefaultProjection;
+      if (this.mode === 'instance') this.projection = nextDefaultProjection;
+    }
+
+    if (regionsChanged) this._applyRegions({ fit: false, sidebars: false });
+    if (previousSidebars) this._sidebars.updateConfig(previousSidebars);
+    if (projectionOptionsChanged || responsiveChanged) this._rebuildProjectionButtons();
+    if (this.canvas?.renderer && exportChanged) this.canvas.renderer.svgExportOptions = this.svgExport || {};
+    if (this.viewer) {
+      this.viewer.responsive = this.responsive;
+      this.viewer.options.responsive = this.responsive;
+      if (exportChanged) this.viewer.svgExportOptions = this.svgExport || {};
+      if (projectionChanged && this.mode === 'instance') this.viewer.projection = this._instanceProjection;
+      if (displayChanged) {
+        this.viewer.setDisplayOptions({
+          timeline: next.viewer.timeline,
+          runtimeDetails: next.viewer.runtimeDetails,
+          runtimeTraceOptions: next.viewer.runtimeTraceOptions,
+          replace: true,
+        });
+      } else if (projectionChanged && this.mode === 'instance') this.viewer.refresh();
+    }
+    if (viewport) (this.canvas?.renderer || this.viewer?.renderer)?.setViewportState?.(viewport);
+    this._syncProjectionButtons();
+    return this.getConfig();
+  }
   getMode() { return this.mode; }
   getAllowedModes() { return Object.freeze([...this.allowedModes]); }
   subscribeMode(listener) {
@@ -814,37 +1014,61 @@ export class BpmnStudioShell {
     if (this.mode === 'instance') this.viewer?.setRuntime(runtime);
   }
   setProjection(projection) {
+    this._projectionExplicit = true;
     this._instanceProjection = projection;
     if (this.mode === 'instance') this.projection = projection;
     this._syncProjectionButtons();
     if (this.mode === 'instance') this.viewer?.setProjection?.(projection);
   }
-  getRegions() { return Object.freeze({ ...this._regions }); }
+  getRegions() { return Object.freeze({ ...this._regions, left: this._isSidebarHidden('left') ? 'hidden' : 'default', right: this._isSidebarHidden('right') ? 'hidden' : 'default' }); }
   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 next = normalizeStudioRegions(regions, this._regions);
     const changed = STUDIO_SHELL_REGIONS.some((name) => next[name] !== this._regions[name]);
     this._regions = next;
-    if (changed) this._applyRegions();
+    if (this._config) {
+      this._config = Object.freeze({
+        ...this._config,
+        ui: Object.freeze({ ...this._config.ui, regions: Object.freeze(normalizeStudioRegions(regions, this._config.ui.regions)) }),
+      });
+    }
+    if (changed || regions?.right === 'default') this._applyRegions({ fit: false });
     return this.getRegions();
   }
-  _applyRegions({ fit = true } = {}) {
+  _isSidebarHidden(side) {
+    if (this._regions[side] === 'hidden') return true;
+    if (side === 'left') return this.mode !== 'design';
+    return this.mode === 'instance' && this._config?.ui.regions.right !== 'default';
+  }
+  getSidebarState() {
+    if (this._sidebars) return this._sidebars.getState();
+    return Object.freeze(Object.fromEntries(['left', 'right'].map((side) => [side, Object.freeze({ collapsed: false, hidden: true, collapsible: false })])));
+  }
+  setSidebarCollapsed(side, collapsed) { return this._sidebars?.setCollapsed(side, collapsed) || false; }
+  subscribeSidebarChange(listener) {
+    if (typeof listener !== 'function') throw new TypeError('subscribeSidebarChange() requires a listener function.');
+    return this._sidebars?.subscribe(listener) || (() => {});
+  }
+  _applyRegions({ fit = true, sidebars = 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 leftHidden = this._isSidebarHidden('left');
+    const rightHidden = this._isSidebarHidden('right');
     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._sidebars) {
+      if (this._left) this._left.hidden = leftHidden;
+      if (this._right) this._right.hidden = rightHidden;
+    }
     if (this._footer) this._footer.hidden = footerHidden;
+    if (sidebars) this._sidebars?.apply({ animate: false });
     if (fit) requestAnimationFrame(() => this._fitActive());
   }
   setTheme(theme) { return this.themeController.setTheme(theme); }
@@ -987,6 +1211,10 @@ export class BpmnStudioShell {
     this._destroyed = true;
     this._modeListeners.clear();
     this._validationListeners.clear();
+    this._panelSelectionListeners.clear();
+    this._sidebars?.destroy();
+    this._rightSlotCleanup?.();
+    this._rightSlotCleanup = null;
     this._svgExportPreview?.close?.({ immediate: true });
     this._svgExportPreview = null;
     this._cleanups.splice(0).reverse().forEach((cleanup) => cleanup?.());