@bpmn-nova/studio 0.3.3-preview → 0.3.5-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.3-preview`。请使用 `@preview` 安装，并在生产接入前验证目标 BPMN XML 与引擎扩展。
+> 当前版本为 `0.3.5-preview`。请使用 `@preview` 安装，并在生产接入前验证目标 BPMN XML 与引擎扩展。
 
 ![BPMN Nova 流程设计器](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-designer.jpg)
 
@@ -47,14 +47,22 @@ const model = createEmptyProcess('flowable')
 model.id = 'Process_PurchaseApproval'
 model.name = '采购申请审批流程'
 
+const config = {
+  modeling: {
+    allowedNodeTypes: ['startEvent', 'userTask', 'exclusiveGateway', 'endEvent'],
+    allowedEdgeTypes: ['sequenceFlow'],
+  },
+  ui: { controlSize: 'medium' },
+}
+
 const studio = createStudioController({
   model,
-  allowedNodeTypes: ['startEvent', 'userTask', 'exclusiveGateway', 'endEvent'],
-  allowedEdgeTypes: ['sequenceFlow'],
+  config,
 })
 const shell = createStudioShell({
   container: document.querySelector('#studio'),
   studio,
+  config,
   mode: 'design',
   allowedModes: ['design'],
   theme: 'auto',
@@ -77,15 +85,17 @@ studio.destroy()
 const shell = createStudioShell({
   container: novaHost,
   studio,
+  config: {
+    ui: { controlSize: 'medium', regions: { right: 'hidden' } },
+  },
   mode: 'design',
   allowedModes: ['design'],
-  regions: { right: 'hidden' },
   slots: {
     headerStart({ container, actions, getState, subscribe }) {
       // 在 Nova Header 左侧挂载宿主的返回入口、业务图标、流程名称和类型。
       // 完整替换 Header 时改用 slots.header，并继续调用 actions。
     },
-    headerActions({ container, actions, getMode, subscribeMode }) {
+    headerActions({ container, actions, getMode, subscribeMode, ui }) {
       // 替换默认“校验 / 导入 / 导出”，在这里挂载宿主的“校验 / 保存 / 发布”。
       // 校验按钮调用 actions.validate()；保存和发布继续调用宿主服务。
     },
@@ -101,7 +111,7 @@ const issues = shell.actions.validate()
 const xml = shell.actions.exportXml('flowable')
 ```
 
-`regions` 支持 `header`、`left`、`right`、`footer` 的 `default | hidden` 状态；隐藏区域不占布局轨道。`setRegions()` 原地更新默认 Shell，不重建 Controller 或 Canvas。`layout()` 是完整布局替换，不能与 `regions` 同时使用。
+`regions` 支持 `header`、`left`、`right`、`footer` 的 `default | hidden` 状态；隐藏区域不占布局轨道，也不保留折叠按钮。Design 默认显示左右，Viewer 仅右侧，Instance 默认隐藏两侧；显式 `regions.right: 'default'` 可在 Instance 开启右侧。`setRegions()` 原地更新默认 Shell，不重建 Controller 或 Canvas。`layout()` 是完整布局替换，不能与 `regions` 同时使用。
 
 `headerActions` 只替换 Header 最右侧动作组，`headerStart` 可与其同时使用，完整 `header` 的优先级更高。未提供 `headerActions` 时仍显示默认“校验 / 导入 / 导出”。顶部不再重复显示最佳视图；底部缩放区和 `fitView()` Interface 保持不变。
 
@@ -128,6 +138,62 @@ async function publishProcess(actions) {
 
 `shell.actions` 只封装撤销、重做、布局、视图、校验和 BPMN/SVG 导入导出。宿主的保存草稿、发布、权限、文件选择和服务端事务不属于 Nova Actions。
 
+## 侧栏内容与平滑折叠
+
+`slots.right` 只替换内容，Nova 保留宽度管理和分隔线中点折叠按钮；不要同时将 `regions.right` 设置为 `hidden`，否则自定义内容也隐藏。`config.ui.rightPanel.layout` 默认 `flex`，宿主安排固定头尾和 `flex: 1; min-height: 0; overflow: auto` 内容区；改为 `scroll` 时由 Nova 滚动整个内容。
+
+```js
+const shell = createStudioShell({
+  container,
+  studio,
+  config: { ui: {
+    leftPanel: { collapsible: true, defaultCollapsed: false },
+    rightPanel: { collapsible: true, defaultCollapsed: false, layout: 'scroll' },
+  } },
+  slots: {
+    right({ container, shell }) {
+      const text = document.createElement('p')
+      container.append(text)
+      const render = ({ selectedElement }) => { text.textContent = selectedElement?.id ?? '未选择元素' }
+      render(shell.getPanelSelection())
+      const off = shell.subscribePanelSelection(render)
+      return () => { off(); text.remove() }
+    },
+  },
+})
+const offSidebar = shell.subscribeSidebarChange(({ side, collapsed, source }) => console.log(side, collapsed, source))
+shell.setSidebarCollapsed('left', true)
+console.log(shell.getSidebarState().left)
+// 卸载时 offSidebar(); shell.destroy(); studio.destroy()
+```
+
+默认左右可独立折叠；200ms 动画尊重减少动态效果，不卸载内容、不丢失表单和滚动状态、不自动 Fit。Shell 容器 ≤720px 时首次默认收起并保留按钮，展开挤压画布，宽窄屏分别记忆状态。`defaultCollapsed` 只用于初始化；隐藏不同于收起。`panelSelection` 包含 `{ selection, selectedElement, trace }`，Design 从 Controller 派生，Viewer/Instance 从实际点击派生而不回写设计选择。
+
+完整配置、事件契约、窄屏与 Flex 样式见仓库 [CUSTOMIZATION.md](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/CUSTOMIZATION.md#侧栏布局与平滑折叠)，或包内 `llms-full.txt` 同名章节。上述新增能力自 `0.3.5-preview` 提供。
+
+## Config 与 Header 控件尺寸
+
+`config` 统一承载静态配置：`modeling` 是 Controller 初始化约束，`ui` 是 Shell 区域和尺寸，`viewer` 是只读/实例展示选项，`export` 是 SVG 导出默认值。`config.ui.controlSize` 默认 `medium`，支持 `small`（28px）、`medium`（32px）、`large`（40px）和 `24px`–`48px` 的 CSS 像素字符串。
+
+```js
+shell.setConfig({
+  ui: {
+    controlSize: '36px',
+    regions: { right: 'hidden' },
+    sidebarWidth: { left: 232, right: 344 },
+  },
+  viewer: { responsive: true },
+  export: { padding: 36 },
+})
+
+console.log(shell.getConfig())
+console.log(shell.ui.controlSize, shell.ui.controlHeight) // 36px, 36px
+```
+
+尺寸只作用于 Header；Footer、Canvas 浮动工具、Palette 和 Properties 不随之缩放。Header Slot 可读取只读 `ui`，并继承 `--nova-control-height`、`--nova-header-height`、`--nova-control-font-size`、`--nova-control-padding-inline`、`--nova-control-icon-size` 和 `--nova-control-radius`。Element Plus `default`、Ant Design `middle` 都对应 Nova `medium`。
+
+旧顶层配置仍兼容但已 Deprecated；同一字段同时出现时旧顶层显式值优先。`setConfig()` 原地应用 UI、Viewer 和 Export，不重建 Canvas；`config.modeling` 只在创建 Controller 时生效，运行中继续通过 `setPropertiesProfile()` 修改 Profile，节点/连线白名单保持不变量。
+
 ## Mode 与节点副标题投影
 
 `design`、`viewer`、`instance` 分别表示流程设计、流程展示和审批轨迹。Shell 是唯一 Mode 状态源：
@@ -188,6 +254,8 @@ viewer.destroy()
 
 ## 审批轨迹
 
+完整 XML、Snapshot、宿主转换器及 Core 生命周期示例见[审批轨迹接入指南](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/RUNTIME-INTEGRATION.md)，正文也包含在包内 `llms-full.txt`。Studio 现有 Runtime 类型出口保持不变；Vue/React 自 `0.3.5-preview` 提供的新增类型出口和旧版兼容写法在指南中单独说明。
+
 Viewer 接收引擎中立的 Runtime Snapshot。三种投影使用相同数据：
 
 | 投影 | 配置 | 适用场景 |
@@ -337,6 +405,7 @@ import { activitiProfile } from '@bpmn-nova/studio/activiti'
 - [项目首页](https://github.com/daxiangme/bpmn-nova)
 - [快速开始](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/GETTING-STARTED.md)
 - [公开 Interface](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/API.md)
+- [审批轨迹接入指南](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/RUNTIME-INTEGRATION.md)
 - [自定义指南](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/CUSTOMIZATION.md)
 
 ## 能力边界

package/dist/config.js

@@ -0,0 +1,285 @@
+const CONTROL_SIZE_PRESETS = Object.freeze({
+  small: 28,
+  medium: 32,
+  large: 40,
+});
+
+const STUDIO_SHELL_REGIONS = Object.freeze(['header', 'left', 'right', 'footer']);
+const STUDIO_PROJECTIONS = Object.freeze(['auto', 'standard', 'approval', 'compact']);
+
+export const DEFAULT_STUDIO_SHELL_REGIONS = Object.freeze({
+  header: 'default',
+  left: 'default',
+  right: 'default',
+  footer: 'default',
+});
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function assertObject(value, path) {
+  if (!isObject(value)) throw new TypeError(`${path} must be an object.`);
+  return value;
+}
+
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key);
+}
+
+function copyValue(value) {
+  if (Array.isArray(value)) return value.map(copyValue);
+  if (!isObject(value)) return value;
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, copyValue(item)]));
+}
+
+function freezeValue(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  Object.values(value).forEach(freezeValue);
+  return Object.freeze(value);
+}
+
+function immutableCopy(value) {
+  return freezeValue(copyValue(value));
+}
+
+function optionalObject(value, path) {
+  if (value === undefined) return undefined;
+  return immutableCopy(assertObject(value, path));
+}
+
+function optionalTypeList(value, path) {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === 'string' || typeof value?.[Symbol.iterator] !== 'function') {
+    throw new TypeError(`${path} must be a readonly array or iterable.`);
+  }
+  const entries = [...value];
+  if (entries.some((item) => typeof item !== 'string')) throw new TypeError(`${path} must contain only strings.`);
+  return Object.freeze(entries);
+}
+
+function normalizePropertiesProfile(value) {
+  if (value === undefined) return 'business';
+  if (value !== 'business' && value !== 'developer') {
+    throw new TypeError('config.modeling.propertiesProfile must be "business" or "developer".');
+  }
+  return value;
+}
+
+function normalizeSidebarWidth(value, fallback, path) {
+  if (value === undefined) return fallback;
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+    throw new TypeError(`${path} must be a finite non-negative number.`);
+  }
+  return value;
+}
+
+function normalizeSidebarConfig(value, side) {
+  const path = `config.ui.${side}Panel`;
+  const input = value === undefined ? {} : assertObject(value, path);
+  for (const key of ['collapsible', 'defaultCollapsed']) {
+    if (input[key] !== undefined && typeof input[key] !== 'boolean') {
+      throw new TypeError(`${path}.${key} must be a boolean.`);
+    }
+  }
+  const result = { collapsible: input.collapsible ?? true, defaultCollapsed: input.defaultCollapsed ?? false };
+  if (side === 'right') {
+    const layout = input.layout === undefined ? 'flex' : input.layout;
+    if (!['flex', 'scroll'].includes(layout)) throw new TypeError(`${path}.layout must be flex or scroll.`);
+    result.layout = layout;
+  }
+  return Object.freeze(result);
+}
+
+export function normalizeStudioControlSize(value) {
+  if (value === undefined) return 'medium';
+  if (typeof value !== 'string') {
+    throw new TypeError('config.ui.controlSize must be small, medium, large, or a 24px–48px CSS pixel value.');
+  }
+  if (hasOwn(CONTROL_SIZE_PRESETS, value)) return value;
+  if (!/^(?:\d+(?:\.\d+)?|\.\d+)px$/.test(value)) {
+    throw new TypeError('config.ui.controlSize must be small, medium, large, or a 24px–48px CSS pixel value.');
+  }
+  const pixels = Number(value.slice(0, -2));
+  if (!Number.isFinite(pixels) || pixels < 24 || pixels > 48) {
+    throw new RangeError('config.ui.controlSize must be between 24px and 48px.');
+  }
+  return `${pixels}px`;
+}
+
+export function resolveStudioControlMetrics(controlSize) {
+  const normalized = normalizeStudioControlSize(controlSize);
+  const height = CONTROL_SIZE_PRESETS[normalized] || Number(normalized.slice(0, -2));
+  const clamp = (value, minimum, maximum) => Math.min(maximum, Math.max(minimum, value));
+  const pixels = (value) => `${Number(value.toFixed(2))}px`;
+  return Object.freeze({
+    controlSize: normalized,
+    controlHeight: pixels(height),
+    headerHeight: pixels(height + 26),
+    modeHeight: pixels(height + 4),
+    modeButtonHeight: pixels(height - 4),
+    projectionButtonHeight: pixels(height - 6),
+    iconButtonSize: pixels(height - 1),
+    splitCaretWidth: pixels(height - 5),
+    fontSize: pixels(clamp(height * 0.25 + 4, 11, 14)),
+    paddingInline: pixels(clamp((height - 12) / 2, 8, 14)),
+    modePaddingInline: pixels(clamp(height / 2 - 4, 10, 14)),
+    iconSize: pixels(clamp(height / 2 - 2, 12, 18)),
+    radius: pixels(clamp(height / 4 - 1, 6, 9)),
+  });
+}
+
+export function normalizeStudioRegions(regions, current = DEFAULT_STUDIO_SHELL_REGIONS) {
+  if (regions === undefined || regions === null) return { ...current };
+  assertObject(regions, 'config.ui.regions');
+  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 };
+}
+
+function normalizeProjectionOptions(value) {
+  if (value === undefined || value === null) return undefined;
+  if (!Array.isArray(value)) throw new TypeError('config.viewer.projectionOptions must be a readonly array.');
+  const seen = new Set();
+  const options = value.map((item, index) => {
+    assertObject(item, `config.viewer.projectionOptions[${index}]`);
+    if (!STUDIO_PROJECTIONS.includes(item.value)) {
+      throw new TypeError(`config.viewer.projectionOptions[${index}].value must be auto, standard, approval, or compact.`);
+    }
+    if (seen.has(item.value)) throw new TypeError(`config.viewer.projectionOptions contains duplicate value "${item.value}".`);
+    if (typeof item.label !== 'string' || !item.label.trim()) {
+      throw new TypeError(`config.viewer.projectionOptions[${index}].label must be a non-empty string.`);
+    }
+    seen.add(item.value);
+    return Object.freeze({ value: item.value, label: item.label });
+  });
+  return Object.freeze(options);
+}
+
+function normalizeStudioConfigInput(config) {
+  if (config === undefined) return {};
+  return assertObject(config, 'config');
+}
+
+function assignPath(target, section, key, value) {
+  if (!target[section]) target[section] = {};
+  target[section][key] = value;
+}
+
+function applyKnownConfig(target, source) {
+  if (!source) return;
+  const config = normalizeStudioConfigInput(source);
+  for (const section of ['modeling', 'ui', 'viewer']) {
+    if (config[section] !== undefined) target[section] = { ...(target[section] || {}), ...assertObject(config[section], `config.${section}`) };
+  }
+  if (hasOwn(config, 'export')) target.export = config.export;
+}
+
+function applyLegacyConfig(target, legacy) {
+  if (!legacy) return;
+  for (const [key, path] of Object.entries({
+    propertiesProfile: ['modeling', 'propertiesProfile'],
+    allowedNodeTypes: ['modeling', 'allowedNodeTypes'],
+    allowedEdgeTypes: ['modeling', 'allowedEdgeTypes'],
+    regions: ['ui', 'regions'],
+    leftWidth: ['ui', 'leftWidth'],
+    rightWidth: ['ui', 'rightWidth'],
+    responsive: ['viewer', 'responsive'],
+    projectionOptions: ['viewer', 'projectionOptions'],
+    timeline: ['viewer', 'timeline'],
+    runtimeDetails: ['viewer', 'runtimeDetails'],
+    runtimeTraceOptions: ['viewer', 'runtimeTraceOptions'],
+  })) {
+    if (hasOwn(legacy, key) && legacy[key] !== undefined) assignPath(target, path[0], path[1], legacy[key]);
+  }
+  if (hasOwn(legacy, 'svgExport') && legacy.svgExport !== undefined) target.export = legacy.svgExport;
+}
+
+export function normalizeStudioConfig(config, { fallback = null, legacy = null } = {}) {
+  const merged = {};
+  applyKnownConfig(merged, fallback);
+  applyKnownConfig(merged, config);
+  applyLegacyConfig(merged, legacy);
+
+  const modelingInput = merged.modeling === undefined ? {} : assertObject(merged.modeling, 'config.modeling');
+  const uiInput = merged.ui === undefined ? {} : assertObject(merged.ui, 'config.ui');
+  const viewerInput = merged.viewer === undefined ? {} : assertObject(merged.viewer, 'config.viewer');
+  const sidebarInput = uiInput.sidebarWidth === undefined
+    ? {}
+    : assertObject(uiInput.sidebarWidth, 'config.ui.sidebarWidth');
+  const leftWidth = hasOwn(uiInput, 'leftWidth') ? uiInput.leftWidth : sidebarInput.left;
+  const rightWidth = hasOwn(uiInput, 'rightWidth') ? uiInput.rightWidth : sidebarInput.right;
+  const controlSize = normalizeStudioControlSize(uiInput.controlSize);
+  const allowedNodeTypes = optionalTypeList(modelingInput.allowedNodeTypes, 'config.modeling.allowedNodeTypes');
+  const allowedEdgeTypes = optionalTypeList(modelingInput.allowedEdgeTypes, 'config.modeling.allowedEdgeTypes');
+  const responsive = viewerInput.responsive === undefined ? false : viewerInput.responsive;
+  if (typeof responsive !== 'boolean') throw new TypeError('config.viewer.responsive must be a boolean.');
+
+  const modeling = {
+    propertiesProfile: normalizePropertiesProfile(modelingInput.propertiesProfile),
+    ...(allowedNodeTypes ? { allowedNodeTypes } : {}),
+    ...(allowedEdgeTypes ? { allowedEdgeTypes } : {}),
+  };
+  const ui = {
+    controlSize,
+    // Keep omitted regions omitted: an explicit right='default' opts into the
+    // Instance sidebar, whereas the mode default must survive get/setConfig.
+    regions: Object.freeze(normalizeStudioRegions(uiInput.regions, {})),
+    leftPanel: normalizeSidebarConfig(uiInput.leftPanel, 'left'),
+    rightPanel: normalizeSidebarConfig(uiInput.rightPanel, 'right'),
+    sidebarWidth: Object.freeze({
+      left: normalizeSidebarWidth(leftWidth, 244, 'config.ui.sidebarWidth.left'),
+      right: normalizeSidebarWidth(rightWidth, 360, 'config.ui.sidebarWidth.right'),
+    }),
+  };
+  const projectionOptions = normalizeProjectionOptions(viewerInput.projectionOptions);
+  const timeline = optionalObject(viewerInput.timeline, 'config.viewer.timeline');
+  const runtimeDetails = optionalObject(viewerInput.runtimeDetails, 'config.viewer.runtimeDetails');
+  const runtimeTraceOptions = optionalObject(viewerInput.runtimeTraceOptions, 'config.viewer.runtimeTraceOptions');
+  const viewer = {
+    responsive,
+    ...(projectionOptions ? { projectionOptions } : {}),
+    ...(timeline ? { timeline } : {}),
+    ...(runtimeDetails ? { runtimeDetails } : {}),
+    ...(runtimeTraceOptions ? { runtimeTraceOptions } : {}),
+  };
+  const exportOptions = merged.export === undefined || merged.export === null
+    ? undefined
+    : optionalObject(merged.export, 'config.export');
+
+  return Object.freeze({
+    modeling: Object.freeze(modeling),
+    ui: Object.freeze(ui),
+    viewer: Object.freeze(viewer),
+    ...(exportOptions ? { export: exportOptions } : {}),
+  });
+}
+
+export function createStudioUiContext(getMetrics) {
+  return Object.freeze({
+    get controlSize() { return getMetrics().controlSize; },
+    get controlHeight() { return getMetrics().controlHeight; },
+  });
+}
+
+export function applyStudioControlMetrics(root, metrics) {
+  const properties = {
+    '--nova-control-height': metrics.controlHeight,
+    '--nova-header-height': metrics.headerHeight,
+    '--nova-control-font-size': metrics.fontSize,
+    '--nova-control-padding-inline': metrics.paddingInline,
+    '--nova-mode-control-padding-inline': metrics.modePaddingInline,
+    '--nova-control-icon-size': metrics.iconSize,
+    '--nova-control-radius': metrics.radius,
+    '--nova-mode-control-height': metrics.modeHeight,
+    '--nova-mode-button-height': metrics.modeButtonHeight,
+    '--nova-projection-button-height': metrics.projectionButtonHeight,
+    '--nova-icon-button-size': metrics.iconButtonSize,
+    '--nova-split-caret-width': metrics.splitCaretWidth,
+  };
+  for (const [name, value] of Object.entries(properties)) root.style.setProperty(name, value);
+}

package/dist/controller.js

@@ -36,6 +36,7 @@ import {
   selectedLayoutNodes,
   selectionBounds,
 } from './selection-layout.js';
+import { normalizeStudioConfig } from './config.js';
 
 const SEQUENCE_FLOW_KINDS = new Set(['event', 'boundary', 'task', 'container', 'gateway']);
 
@@ -86,17 +87,31 @@ function normalizeAllowedEdgeTypes(allowedEdgeTypes) {
 }
 
 export class BpmnStudioController {
-  constructor({ model, historyLimit = 80, extensions = [], propertiesProfile = 'business', allowedNodeTypes = null, allowedEdgeTypes = null } = {}) {
+  constructor(options = {}) {
+    const {
+      model,
+      historyLimit = 80,
+      extensions = [],
+      propertiesProfile,
+      allowedNodeTypes,
+      allowedEdgeTypes,
+      config,
+    } = options;
     if (!model) throw new Error('BpmnStudioController requires a model.');
-    this._allowedNodeTypes = normalizeAllowedNodeTypes(allowedNodeTypes);
-    this._allowedEdgeTypes = normalizeAllowedEdgeTypes(allowedEdgeTypes);
+    const legacy = {};
+    if (Object.prototype.hasOwnProperty.call(options, 'propertiesProfile')) legacy.propertiesProfile = propertiesProfile;
+    if (Object.prototype.hasOwnProperty.call(options, 'allowedNodeTypes')) legacy.allowedNodeTypes = allowedNodeTypes;
+    if (Object.prototype.hasOwnProperty.call(options, 'allowedEdgeTypes')) legacy.allowedEdgeTypes = allowedEdgeTypes;
+    const normalizedConfig = normalizeStudioConfig(config, { legacy });
+    this._allowedNodeTypes = normalizeAllowedNodeTypes(normalizedConfig.modeling.allowedNodeTypes);
+    this._allowedEdgeTypes = normalizeAllowedEdgeTypes(normalizedConfig.modeling.allowedEdgeTypes);
     this._assertAllowedModel(model);
     this._model = model;
     this.history = new HistoryStack(historyLimit);
     this.selection = { kind: 'process', id: model.id };
     this.activeScopeId = model.id;
     this.connectingSource = null;
-    this.propertiesProfile = propertiesProfile;
+    this.propertiesProfile = normalizedConfig.modeling.propertiesProfile;
     this._listeners = new Set();
     this._extensions = new Map();
     applyContainmentOperation(this._model, { type: 'reconcile' });

package/dist/index.d.ts

@@ -178,7 +178,7 @@ export class BpmnViewer {
   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
+  setDisplayOptions(options: { timeline?: ViewerTimelineOptions; runtimeDetails?: RuntimeDetailsOptions; runtimeTraceOptions?: RuntimeTraceProjectionOptions; runtimeAssetResolver?: import('./modules/viewer/index.js').RuntimeAssetResolver | null; replace?: boolean }): void
   setProjection(projection: ViewerProjection): void
   setTheme(theme: NovaThemeInput): NovaThemeState
   setThemeMode(mode: NovaThemeMode): NovaThemeState
@@ -231,12 +231,64 @@ export interface StudioExtension {
   id: string
   setup(context: { studio: BpmnStudioController }): void | (() => void)
 }
+export type StudioControlSize = 'small' | 'medium' | 'large' | `${number}px`
+export interface StudioModelingConfig {
+  propertiesProfile?: 'business' | 'developer'
+  allowedNodeTypes?: readonly NodeType[]
+  allowedEdgeTypes?: readonly EdgeType[]
+}
+export interface StudioSidebarConfig {
+  /** Defaults to true. Disabling collapse keeps an available sidebar expanded. */
+  collapsible?: boolean
+  /** Initial wide-container state only; later config updates do not reset user choices. */
+  defaultCollapsed?: boolean
+}
+export interface StudioRightPanelConfig extends StudioSidebarConfig {
+  /** Defaults to flex. In scroll mode Nova scrolls the entire supplied content. */
+  layout?: 'flex' | 'scroll'
+}
+export interface StudioUiConfig {
+  controlSize?: StudioControlSize
+  regions?: StudioShellRegions
+  leftPanel?: StudioSidebarConfig
+  rightPanel?: StudioRightPanelConfig
+  sidebarWidth?: {
+    left?: number
+    right?: number
+  }
+}
+export interface StudioViewerConfig {
+  responsive?: boolean
+  projectionOptions?: readonly { value: ViewerProjection; label: string }[]
+  timeline?: ViewerTimelineOptions
+  runtimeDetails?: RuntimeDetailsOptions
+  runtimeTraceOptions?: RuntimeTraceProjectionOptions
+}
+export type StudioSvgExportOptions = SvgExportOptions & {
+  label?: string
+  nodeRenderers?: Record<string, SvgNodeRenderer>
+  runtimeTimelineRenderer?: RuntimeTimelineSvgRenderer
+}
+export interface BpmnStudioConfig {
+  modeling?: StudioModelingConfig
+  ui?: StudioUiConfig
+  viewer?: StudioViewerConfig
+  export?: StudioSvgExportOptions
+}
+export interface StudioUiContext {
+  readonly controlSize: StudioControlSize
+  readonly controlHeight: `${number}px`
+}
 export interface StudioControllerOptions {
   model: ProcessModel
   historyLimit?: number
   extensions?: StudioExtension[]
+  config?: BpmnStudioConfig
+  /** @deprecated Use config.modeling.propertiesProfile. */
   propertiesProfile?: 'business' | 'developer'
+  /** @deprecated Use config.modeling.allowedNodeTypes. */
   allowedNodeTypes?: Iterable<NodeType> | null
+  /** @deprecated Use config.modeling.allowedEdgeTypes. */
   allowedEdgeTypes?: Iterable<EdgeType> | null
 }
 export interface StudioCommands {
@@ -466,6 +518,25 @@ export interface StudioShellActions {
   }): SvgExportPreviewController | null
 }
 export type StudioMode = 'design' | 'viewer' | 'instance'
+export type StudioSidebarSide = 'left' | 'right'
+export type StudioSidebarState = Readonly<Record<StudioSidebarSide, {
+  readonly collapsed: boolean
+  readonly hidden: boolean
+  readonly collapsible: boolean
+}>>
+export type StudioSidebarChangeSource = 'button' | 'api' | 'responsive' | 'config'
+export interface StudioSidebarChangeEvent {
+  readonly side: StudioSidebarSide
+  readonly collapsed: boolean
+  readonly previousCollapsed: boolean
+  readonly mode: StudioMode
+  readonly source: StudioSidebarChangeSource
+}
+export interface StudioPanelSelection {
+  readonly selection: ElementSelection | null
+  readonly selectedElement: StudioState['selectedElement']
+  readonly trace: RuntimeTraceClickEvent | null
+}
 export type StudioModeChangeSource = 'toolbar' | 'api' | 'allowed-modes'
 export interface StudioModeChangeEvent {
   readonly mode: StudioMode
@@ -486,12 +557,18 @@ export interface StudioShellSlotContext {
   shell: BpmnStudioShell
   canvas: BpmnCanvas
   actions: StudioShellActions
+  readonly ui: StudioUiContext
   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
+  getSidebarState(): StudioSidebarState
+  setSidebarCollapsed(side: StudioSidebarSide, collapsed: boolean): boolean
+  subscribeSidebarChange(listener: (event: StudioSidebarChangeEvent) => void): () => void
+  getPanelSelection(): StudioPanelSelection
+  subscribePanelSelection(listener: (selection: StudioPanelSelection) => void): () => void
 }
 export type StudioShellDomSlot =
   | HTMLElement
@@ -526,6 +603,7 @@ export interface StudioShellRegionState {
 export interface StudioShellOptions {
   container: HTMLElement
   studio: BpmnStudioController
+  config?: BpmnStudioConfig
   iconRegistry?: IconRegistry
   paletteRegistry?: PaletteRegistry
   propertiesRegistry?: PropertiesRegistry
@@ -534,33 +612,54 @@ export interface StudioShellOptions {
   rendererOptions?: DiagramRendererOptions & {
     runtimeTraceOptions?: RuntimeTraceProjectionOptions
     timeline?: ViewerTimelineOptions
+    runtimeDetails?: RuntimeDetailsOptions
   }
   nodeSubtitleResolver?: NodeSubtitleResolver
   slots?: StudioShellSlots
+  /** @deprecated Use config.ui.regions. */
   regions?: StudioShellRegions
   layout?: (context: Record<string, unknown>) => void | (() => void)
   runtime?: ProcessInstanceSnapshot | null
   mode?: StudioMode
   allowedModes?: readonly StudioMode[]
   projection?: ViewerProjection
+  /** @deprecated Use config.viewer.responsive. */
   responsive?: boolean
+  /** @deprecated Use config.viewer.projectionOptions. */
   projectionOptions?: Array<{ value: ViewerProjection; label: string }>
+  /** @deprecated Use config.ui.sidebarWidth.left. */
   leftWidth?: number
+  /** @deprecated Use config.ui.sidebarWidth.right. */
   rightWidth?: number
+  /** @deprecated Use config.viewer.timeline. */
+  timeline?: ViewerTimelineOptions
+  /** @deprecated Use config.viewer.runtimeDetails. */
+  runtimeDetails?: RuntimeDetailsOptions
+  /** @deprecated Use config.viewer.runtimeTraceOptions. */
+  runtimeTraceOptions?: RuntimeTraceProjectionOptions
   theme?: NovaThemeInput
   runtimeAppearance?: RuntimeAppearanceOptions
-  svgExport?: SvgExportOptions & { label?: string; nodeRenderers?: Record<string, SvgNodeRenderer>; runtimeTimelineRenderer?: RuntimeTimelineSvgRenderer }
+  /** @deprecated Use config.export. */
+  svgExport?: StudioSvgExportOptions
   onThemeChange?: (state: NovaThemeState) => void
 }
 export class BpmnStudioShell {
   constructor(options: StudioShellOptions)
   readonly actions: StudioShellActions
+  readonly ui: StudioUiContext
   canvas?: BpmnCanvas
   viewer?: BpmnViewer
   getMode(): StudioMode
   getAllowedModes(): readonly StudioMode[]
   subscribeMode(listener: (event: StudioModeChangeEvent) => void): () => void
   subscribeValidation(listener: (event: StudioValidationEvent) => void): () => void
+  getSidebarState(): StudioSidebarState
+  setSidebarCollapsed(side: StudioSidebarSide, collapsed: boolean): boolean
+  subscribeSidebarChange(listener: (event: StudioSidebarChangeEvent) => void): () => void
+  getPanelSelection(): StudioPanelSelection
+  subscribePanelSelection(listener: (selection: StudioPanelSelection) => void): () => void
+  getConfig(): Readonly<BpmnStudioConfig>
+  setConfig(config?: BpmnStudioConfig): Readonly<BpmnStudioConfig>
   setAllowedModes(modes: readonly StudioMode[]): readonly StudioMode[]
   getRegions(): Readonly<StudioShellRegionState>
   setRegions(regions: StudioShellRegions): Readonly<StudioShellRegionState>