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

package/README.md

@@ -4,32 +4,21 @@ 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.4-preview`。请使用 `@preview` 安装，并在生产接入前验证目标 BPMN XML 与引擎扩展。
+> 当前版本为 `0.3.6-preview`。请使用 `@preview` 安装，并在生产接入前验证目标 BPMN XML 与引擎扩展。
 
 ![BPMN Nova 流程设计器](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-designer.jpg)
 
-## 什么时候使用
-
-- Vanilla JavaScript 或 TypeScript 项目安装本包。
-- React 18+ 项目安装 `@bpmn-nova/react`。
-- Vue 3.3+ 项目安装 `@bpmn-nova/vue`。
-- 一个项目只需要选择一个公开包，不需要安装 Core、Viewer、Runtime、Theme 等内部 Module。
-
 ## 安装
 
 ```bash
 npm install @bpmn-nova/studio@preview
 ```
 
-```js
-import '@bpmn-nova/studio/styles.css'
-```
-
-BPMN Nova 不会在 JavaScript 中隐式注入 CSS。视觉容器必须有明确高度。
+Vanilla JavaScript / TypeScript 项目选择本包；React 18+ 和 Vue 3.3+ 项目分别选择 `@bpmn-nova/react` 或 `@bpmn-nova/vue`。
 
-使用代码生成助手或 IDE Agent 接入时，从随包的 `llms.txt` 开始；需要完整接口和定制资料时再读取 `llms-full.txt`。两份文件都包含在 npm tarball 中，不依赖源码仓库可见性。
+CSS 必须显式导入 `@bpmn-nova/studio/styles.css`；视觉容器及其父级需要具有可计算高度。
 
-## 流程设计
+## 最小用法
 
 ```html
 <div id="studio" style="height: 720px"></div>
@@ -43,14 +32,8 @@ import {
 } from '@bpmn-nova/studio'
 import '@bpmn-nova/studio/styles.css'
 
-const model = createEmptyProcess('flowable')
-model.id = 'Process_PurchaseApproval'
-model.name = '采购申请审批流程'
-
 const studio = createStudioController({
-  model,
-  allowedNodeTypes: ['startEvent', 'userTask', 'exclusiveGateway', 'endEvent'],
-  allowedEdgeTypes: ['sequenceFlow'],
+  model: createEmptyProcess('flowable'),
 })
 const shell = createStudioShell({
   container: document.querySelector('#studio'),
@@ -60,288 +43,23 @@ const shell = createStudioShell({
   theme: 'auto',
 })
 
-const xml = studio.exportXml()
-
-// 页面卸载时释放实例。
-shell.destroy()
-studio.destroy()
-```
-
-`allowedNodeTypes` 与 `allowedEdgeTypes` 同时约束 XML 导入、Palette、连接、快捷新增、模板和节点类型转换；不传时开放 Nova 当前支持的全部图元。`allowedModes` 控制默认工作台显示和允许切换的模式。不传 Runtime 时实例模式保持空运行事实，不会注入演示审批数据。
-
-## 嵌入宿主工作台
-
-默认 `BpmnStudioShell` 仍是包含 Header、Palette、Canvas、Properties 和 Statusbar 的完整工作台。宿主要复用自己的业务属性面板时，应显式隐藏 Nova 右侧区域，并把业务面板作为 Nova 根节点的外部兄弟区域：
-
-```js
-const shell = createStudioShell({
-  container: novaHost,
-  studio,
-  mode: 'design',
-  allowedModes: ['design'],
-  regions: { right: 'hidden' },
-  slots: {
-    headerStart({ container, actions, getState, subscribe }) {
-      // 在 Nova Header 左侧挂载宿主的返回入口、业务图标、流程名称和类型。
-      // 完整替换 Header 时改用 slots.header，并继续调用 actions。
-    },
-    headerActions({ container, actions, getMode, subscribeMode }) {
-      // 替换默认“校验 / 导入 / 导出”，在这里挂载宿主的“校验 / 保存 / 发布”。
-      // 校验按钮调用 actions.validate()；保存和发布继续调用宿主服务。
-    },
-  },
-  theme: 'auto',
-})
-
-shell.setRegions({ right: 'default' })
-shell.actions.undo()
-shell.actions.redo()
-shell.actions.fitView()
-const issues = shell.actions.validate()
-const xml = shell.actions.exportXml('flowable')
-```
-
-`regions` 支持 `header`、`left`、`right`、`footer` 的 `default | hidden` 状态；隐藏区域不占布局轨道。`setRegions()` 原地更新默认 Shell，不重建 Controller 或 Canvas。`layout()` 是完整布局替换，不能与 `regions` 同时使用。
-
-`headerActions` 只替换 Header 最右侧动作组，`headerStart` 可与其同时使用，完整 `header` 的优先级更高。未提供 `headerActions` 时仍显示默认“校验 / 导入 / 导出”。顶部不再重复显示最佳视图；底部缩放区和 `fitView()` Interface 保持不变。
-
-`shell.actions.validate()` 作为 Header 动作，以 `toolbar` 来源先更新 Nova 默认状态栏、再发送 Validation Event，最后返回 issues；程序化调用 `shell.validate()` 使用 `api` 来源。`valid` 表示没有 error，warning 不默认阻止发布：
-
-```js
-const offValidation = shell.subscribeValidation((event) => {
-  console.log(event.source, event.valid, event.errorCount, event.warningCount, event.issues)
-})
-
-shell.validate()
-offValidation()
-```
-
-宿主发布按钮可以复用 Toolbar 来源的完整流程；仅 error 默认阻止发布：
-
-```js
-async function publishProcess(actions) {
-  const issues = actions.validate()
-  if (issues.some((issue) => issue.level === 'error')) return
-  await publishXml(actions.exportXml())
-}
-```
-
-`shell.actions` 只封装撤销、重做、布局、视图、校验和 BPMN/SVG 导入导出。宿主的保存草稿、发布、权限、文件选择和服务端事务不属于 Nova Actions。
-
-## Mode 与节点副标题投影
-
-`design`、`viewer`、`instance` 分别表示流程设计、流程展示和审批轨迹。Shell 是唯一 Mode 状态源：
-
-```js
-const unsubscribe = shell.subscribeMode((event) => {
-  console.log(event.mode, event.previousMode, event.source, event.allowedModes)
-})
-
-shell.getMode()
-shell.setMode('viewer')
-shell.setAllowedModes(['design', 'viewer'])
-```
-
-`setMode()` 仅在实际成功切换时返回 `true`。`setAllowedModes()` 拒绝空数组、重复值和未知值；若移除当前 Mode，会回退到新数组首项并发送一次 `allowed-modes` 事件。切换只改变 Shell 展示，不进入 Model、History 或 Studio State。
-
-标准任务与容器卡片支持定义态副标题 Resolver：
-
-```js
-const summaries = new Map()
-const shell = createStudioShell({
-  container,
-  studio,
-  nodeSubtitleResolver({ node, mode, surface, defaultSubtitle }) {
-    return summaries.has(node.id) ? summaries.get(node.id) : undefined
-  },
-})
-
-summaries.set('ServiceTask_Archive', '归档到采购系统')
-shell.refreshPresentation()
-summaries.set('ServiceTask_Archive', null)
-shell.refreshPresentation()
-```
-
-`undefined` 保留默认副标题，`null` 移除副标题行，字符串（包括空字符串）作为覆盖值。Resolver 同步应用于 Design、Viewer 与标准 SVG 降级视觉；完整自定义 Renderer 优先，Instance 始终使用 Runtime Presentation。`refreshPresentation()` 不写 XML、不创建历史、不改变选择、Scope 或视口。
-
-## 只读 Viewer
-
-```js
-import { importBpmn } from '@bpmn-nova/studio'
-import { BpmnViewer } from '@bpmn-nova/studio/viewer'
-import '@bpmn-nova/studio/styles.css'
-
-const viewer = new BpmnViewer({
-  container: document.querySelector('#viewer'),
-  model: importBpmn(xml, 'flowable'),
-  projection: 'standard',
-  theme: 'auto',
-})
-
-viewer.fitView()
-viewer.destroy()
-```
-
-也可以从 `@bpmn-nova/studio` 根入口导入所有公开 Interface；子路径用于明确表达接入场景。
-
-![BPMN Nova 只读流程展示](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-viewer.jpg)
-
-## 审批轨迹
-
-Viewer 接收引擎中立的 Runtime Snapshot。三种投影使用相同数据：
-
-| 投影 | 配置 | 适用场景 |
-| --- | --- | --- |
-| 实际路径 | `projection: 'approval'` | 只展示实际发生的有效路径 |
-| 移动时间线 | `projection: 'compact'` | 按访问轮次展示动作、图片和附件 |
-| 完整 BPMN | `projection: 'standard'` + `runtime` | 完整结构叠加运行状态 |
-
-```js
-const runtime = {
-  processInstanceId: 'purchase-20260824',
-  status: 'running',
-  activities: [{
-    id: 'activity-manager-1',
-    elementId: 'UserTask_Manager',
-    visitId: 'visit-manager-1',
-    status: 'completed',
-    assignee: '李经理',
-    endTime: '2026-08-24T10:12:00+08:00',
-  }],
-  actions: [{
-    id: 'action-manager-approve',
-    type: 'approve',
-    elementId: 'UserTask_Manager',
-    visitId: 'visit-manager-1',
-    activityId: 'activity-manager-1',
-    actor: { id: 'manager-li', name: '李经理' },
-    occurredAt: '2026-08-24T10:12:00+08:00',
-    content: {
-      plainText: '资料完整，同意提交总经理审批。',
-      blocks: [
-        { type: 'paragraph', text: '资料完整，同意提交总经理审批。' },
-        { type: 'image', assetId: 'quotation-preview' },
-        { type: 'file', assetId: 'purchase-checklist' },
-      ],
-      assets: [
-        {
-          id: 'quotation-preview',
-          name: '现场报价单.png',
-          mediaType: 'image/png',
-          width: 1280,
-          height: 720,
-        },
-        {
-          id: 'purchase-checklist',
-          name: '采购核验清单.txt',
-          mediaType: 'text/plain',
-          size: 248,
-        },
-      ],
-    },
-  }],
-  visitedEdges: [],
-}
-
-const runtimeAssetResolver = async (asset, { purpose, signal }) => {
-  const response = await fetch(
-    `/api/runtime-assets/${encodeURIComponent(asset.id)}?purpose=${purpose}`,
-    { signal },
-  )
-  if (!response.ok) return null
-  return response.url
+function dispose() {
+  shell.destroy()
+  studio.destroy()
 }
-
-viewer.setRuntime(runtime)
-viewer.setProjection('compact')
-viewer.setDisplayOptions({ runtimeAssetResolver })
 ```
 
-Snapshot 只保存资源引用，不保存 URL、Base64、Blob 或 HTML。上传、权限签发和资源存储由宿主业务系统负责。
-
-| 实际路径 | 移动时间线 |
-| --- | --- |
-| ![审批实际路径](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-approval-effective-path.jpg) | ![移动审批时间线](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-approval-mobile-timeline.jpg) |
-
-![完整 BPMN 审批轨迹](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-approval-full-bpmn.jpg)
-
-## 主题与运行态配色
-
-```js
-shell.setTheme({
-  mode: 'auto',
-  dark: {
-    colors: {
-      canvas: '#0b1018',
-      surface: '#18202b',
-    },
-  },
-})
-
-shell.setRuntimeAppearance({
-  statuses: { completed: 'success', active: 'primary' },
-  actions: {
-    approve: { label: '通过', tone: 'success' },
-    reject: { label: '驳回', tone: 'danger' },
-  },
-})
-```
-
-主题限定在实例根节点；`auto` 会跟随并监听浏览器系统主题变化，不修改宿主页面的 `<html>`。
-
-![BPMN Nova 深色运行态](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-dark-runtime.jpg)
-
-## SVG 导出
-
-```js
-// 打开确认预览，用户确认后下载。
-shell.openSvgExportPreview({
-  theme: 'current',
-  transparentBackground: false,
-  filename: '采购申请审批流程.svg',
-})
-
-// 或只创建 Artifact，不触发下载。
-const artifact = await shell.exportSvg({ theme: 'dark' })
-console.log(artifact.svg, artifact.warnings)
-```
-
-导出完整业务内容，不受当前缩放、平移或滚动影响。图片会通过 Resolver 嵌入 SVG，普通附件只展示摘要。
-
-![SVG 导出确认预览](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-svg-export-preview.jpg)
-
-## 支持的子路径
-
-```js
-import { BpmnDesigner } from '@bpmn-nova/studio/designer'
-import { BpmnViewer } from '@bpmn-nova/studio/viewer'
-import { createRuntimePresentation } from '@bpmn-nova/studio/runtime'
-import { createThemeController } from '@bpmn-nova/studio/theme'
-import { exportDiagramSvg } from '@bpmn-nova/studio/export-svg'
-import { flowableProfile } from '@bpmn-nova/studio/flowable'
-import { activitiProfile } from '@bpmn-nova/studio/activiti'
-```
-
-## 常见问题
-
-- **界面为空或高度为 0：** 为 Studio/Viewer 的父容器设置明确高度。
-- **界面没有样式：** 导入一次 `@bpmn-nova/studio/styles.css`。
-- **附件不可用：** 提供 `runtimeAssetResolver`，并为不同 purpose 返回当前有效地址。
-- **SSR 报错：** 在浏览器挂载阶段创建实例，服务端只准备 XML 和 Runtime 数据。
-- **重复安装：** 不直接安装任何未列出的 `@bpmn-nova/*` 内部 Module。
-
-## 文档与 AI
+在页面卸载时调用 `dispose()`；SSR 应用只在客户端创建视觉实例。
 
-- npm 包内 `llms.txt`：可执行安装入口
-- npm 包内 `llms-full.txt`：完整 AI 上下文
-- [项目首页](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/CUSTOMIZATION.md)
+## 完整文档
 
-## 能力边界
+- [官网与文档](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/index.md)
+- [Studio 接入、宿主组合和完整示例](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/guide/studio.md)
+- [组件参数与事件](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/components/index.md)、[公开 API](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/api/index.md)
+- [审批轨迹接入](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/guide/runtime.md)、[自定义扩展](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/customization/index.md)
+- [更新日志](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/changelog.md)
 
-BPMN Nova 负责建模、展示、审批轨迹、主题和 SVG 导出；不负责流程引擎执行、审批提交、附件上传存储、权限签发或 PNG/PDF 导出。当前 Preview 不声明 BPMN Schema 100% 覆盖。
+官网尚未部署，以上链接暂指向仓库文档。AI 接入从随包的 `llms.txt` 开始；`llms-full.txt` 提供完整离线上下文，两份文件都包含在 npm tarball 中。
 
 ## License
 

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' });