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

package/README.md

@@ -4,7 +4,7 @@ BPMN Nova 的 Vanilla JavaScript / TypeScript 完整入口，提供流程设计
 
 > **English summary:** The complete framework-neutral BPMN Nova package for process design, viewing, approval traces, themes, properties, and pure SVG export.
 
-> 当前版本为 `0.3.1-preview`。请使用 `@preview` 安装，并在生产接入前验证目标 BPMN XML 与引擎扩展。
+> 当前版本为 `0.3.3-preview`。请使用 `@preview` 安装，并在生产接入前验证目标 BPMN XML 与引擎扩展。
 
 ![BPMN Nova 流程设计器](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-designer.jpg)
 
@@ -27,6 +27,8 @@ import '@bpmn-nova/studio/styles.css'
 
 BPMN Nova 不会在 JavaScript 中隐式注入 CSS。视觉容器必须有明确高度。
 
+使用代码生成助手或 IDE Agent 接入时，从随包的 `llms.txt` 开始；需要完整接口和定制资料时再读取 `llms-full.txt`。两份文件都包含在 npm tarball 中，不依赖源码仓库可见性。
+
 ## 流程设计
 
 ```html
@@ -45,10 +47,16 @@ const model = createEmptyProcess('flowable')
 model.id = 'Process_PurchaseApproval'
 model.name = '采购申请审批流程'
 
-const studio = createStudioController({ model })
+const studio = createStudioController({
+  model,
+  allowedNodeTypes: ['startEvent', 'userTask', 'exclusiveGateway', 'endEvent'],
+  allowedEdgeTypes: ['sequenceFlow'],
+})
 const shell = createStudioShell({
   container: document.querySelector('#studio'),
   studio,
+  mode: 'design',
+  allowedModes: ['design'],
   theme: 'auto',
 })
 
@@ -59,6 +67,103 @@ 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
@@ -227,12 +332,12 @@ import { activitiProfile } from '@bpmn-nova/studio/activiti'
 
 ## 文档与 AI
 
+- 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)
-- [AI 接入入口](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/llms.txt)
-- [AI 完整上下文](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/llms-full.txt)
 
 ## 能力边界
 

package/dist/canvas.js

@@ -35,7 +35,7 @@ function toolbarIcon(id) {
 }
 
 export class BpmnCanvas {
-  constructor({ container, studio, rendererOptions = {}, interactions = null, selectionToolbar = null, contextMenu = null, contextMenuRegistry = createDefaultContextMenuRegistry(), pointerMode = 'select', themeController = null, theme = null, onThemeChange = null } = {}) {
+  constructor({ container, studio, rendererOptions = {}, nodeSubtitleResolver = rendererOptions.nodeSubtitleResolver, interactions = null, selectionToolbar = null, contextMenu = null, contextMenuRegistry = createDefaultContextMenuRegistry(), pointerMode = 'select', themeController = null, theme = null, onThemeChange = null } = {}) {
     if (!container) throw new Error('BpmnCanvas requires a container.');
     if (!studio) throw new Error('BpmnCanvas requires a studio controller.');
     this.container = container;
@@ -51,6 +51,7 @@ export class BpmnCanvas {
     const onViewportChange = rendererOptions.onViewportChange;
     this.renderer = new DiagramRenderer(container, {
       ...rendererOptions,
+      nodeSubtitleResolver,
       themeController,
       theme,
       onThemeChange,
@@ -80,6 +81,7 @@ export class BpmnCanvas {
       },
       onStartConnect: (node) => studio.startConnect(node.id),
       canConnect: (source, target) => canCreateSequenceFlow(studio.model, source.id, target.id),
+      canCreateNodeType: (nodeType) => studio.allowsNodeType(nodeType),
       onQuickAdd: (source, type, preset) => studio.commands.quickAdd(source.id, type, preset),
       onDeleteNode: (node) => studio.commands.remove({ kind: 'node', id: node.id }),
       onUngroup: (node) => studio.commands.ungroup(node.id),
@@ -521,7 +523,7 @@ export class BpmnCanvas {
       { id: 'distribute-vertical', iconId: 'ui.distributeVertical', title: '垂直等距', action: () => actions.distribute('vertical'), disabled: nodes.length < 3 },
     ];
     this._selectionToolbar.append(
-      button('group', 'ui.layoutSelection', '创建分组', actions.group, { label: '创建分组', disabled: !groupableNodes.length || groupableNodes.length !== diagramNodes.length }),
+      button('group', 'ui.layoutSelection', '创建分组', actions.group, { label: '创建分组', disabled: this.studio.allowsNodeType?.('group') === false || !groupableNodes.length || groupableNodes.length !== diagramNodes.length }),
       separator(),
       menu('align', 'ui.alignCenterHorizontal', '对齐选区', alignmentItems, nodes.length < 2),
       menu('distribute', 'ui.distributeHorizontal', '等距分布', distributeItems, nodes.length < 3),
@@ -904,6 +906,7 @@ export class BpmnCanvas {
   startConnect(nodeId) { this.renderer.closeTransientOverlays?.(); return this.studio.startConnect(nodeId); }
   editEdgeName(edgeId) { return this.renderer.editEdgeName?.(edgeId) || false; }
   fitView(padding, options) { this.renderer.fitView(padding, { minZoom: 0.7, ...(options || {}) }); }
+  refreshPresentation() { this.renderer.refreshPresentation(); }
   exportSvg(options) { return this.renderer.exportSvg(options); }
   openSvgExportPreview(options) { return this.renderer.openSvgExportPreview(options); }
   fitSelection(padding = 72) {

package/dist/context-menu.js

@@ -104,7 +104,7 @@ function multiActions(context) {
     execute: ({ studio }) => studio.arrangeSelection({ type: 'align', alignment }),
   }));
   actions.push(
-    action({ id: 'selection.group', label: '创建分组', iconId: 'ui.layoutSelection', group: 'layout', disabled: !groupableNodes.length || groupableNodes.length !== diagramNodes.length, execute: ({ studio }) => studio.commands.groupSelection() }),
+    action({ id: 'selection.group', label: '创建分组', iconId: 'ui.layoutSelection', group: 'layout', disabled: context.studio.allowsNodeType?.('group') === false || !groupableNodes.length || groupableNodes.length !== diagramNodes.length, execute: ({ studio }) => studio.commands.groupSelection() }),
     action({ id: 'selection.distribute.horizontal', label: '水平等距', iconId: 'ui.distributeHorizontal', group: 'distribute', disabled: nodes.length < 3, execute: ({ studio }) => studio.arrangeSelection({ type: 'distribute', axis: 'horizontal' }) }),
     action({ id: 'selection.distribute.vertical', label: '垂直等距', iconId: 'ui.distributeVertical', group: 'distribute', disabled: nodes.length < 3, execute: ({ studio }) => studio.arrangeSelection({ type: 'distribute', axis: 'vertical' }) }),
     action({ id: 'selection.layout', label: '美化选区', iconId: 'ui.layoutSelection', group: 'layout', disabled: nodes.length < 2, execute: ({ studio }) => studio.arrangeSelection({ type: 'layout' }) }),

package/dist/controller.js

@@ -1,6 +1,7 @@
 import {
   applyContainmentOperation,
   CONTAINMENT_LIMITS,
+  EDGE_DEFINITIONS,
   HistoryStack,
   LAYOUT_DENSITIES,
   NODE_DEFINITIONS,
@@ -58,9 +59,38 @@ function mergeNodePreset(preset = {}) {
   };
 }
 
+function normalizeAllowedNodeTypes(allowedNodeTypes) {
+  if (allowedNodeTypes === undefined || allowedNodeTypes === null) return null;
+  if (typeof allowedNodeTypes === 'string' || typeof allowedNodeTypes[Symbol.iterator] !== 'function') {
+    throw new Error('allowedNodeTypes must be an iterable of BPMN node types.');
+  }
+  const normalized = new Set(allowedNodeTypes);
+  for (const nodeType of normalized) {
+    if (!NODE_DEFINITIONS[nodeType] || nodeType === 'generic') {
+      throw new Error(`Unknown allowed BPMN node type: ${nodeType}`);
+    }
+  }
+  return normalized;
+}
+
+function normalizeAllowedEdgeTypes(allowedEdgeTypes) {
+  if (allowedEdgeTypes === undefined || allowedEdgeTypes === null) return null;
+  if (typeof allowedEdgeTypes === 'string' || typeof allowedEdgeTypes[Symbol.iterator] !== 'function') {
+    throw new Error('allowedEdgeTypes must be an iterable of BPMN edge types.');
+  }
+  const normalized = new Set(allowedEdgeTypes);
+  for (const edgeType of normalized) {
+    if (!EDGE_DEFINITIONS[edgeType]) throw new Error(`Unknown allowed BPMN edge type: ${edgeType}`);
+  }
+  return normalized;
+}
+
 export class BpmnStudioController {
-  constructor({ model, historyLimit = 80, extensions = [], propertiesProfile = 'business' } = {}) {
+  constructor({ model, historyLimit = 80, extensions = [], propertiesProfile = 'business', allowedNodeTypes = null, allowedEdgeTypes = null } = {}) {
     if (!model) throw new Error('BpmnStudioController requires a model.');
+    this._allowedNodeTypes = normalizeAllowedNodeTypes(allowedNodeTypes);
+    this._allowedEdgeTypes = normalizeAllowedEdgeTypes(allowedEdgeTypes);
+    this._assertAllowedModel(model);
     this._model = model;
     this.history = new HistoryStack(historyLimit);
     this.selection = { kind: 'process', id: model.id };
@@ -108,6 +138,32 @@ export class BpmnStudioController {
 
   get model() { return this._model; }
 
+  allowsNodeType(nodeType) {
+    return Boolean(NODE_DEFINITIONS[nodeType])
+      && nodeType !== 'generic'
+      && (!this._allowedNodeTypes || this._allowedNodeTypes.has(nodeType));
+  }
+
+  allowsEdgeType(edgeType) {
+    return Boolean(EDGE_DEFINITIONS[edgeType])
+      && (!this._allowedEdgeTypes || this._allowedEdgeTypes.has(edgeType));
+  }
+
+  _assertAllowedModel(model) {
+    if (this._allowedNodeTypes) {
+      const unsupportedNode = model?.nodes?.find((node) => !this._allowedNodeTypes.has(node.type));
+      if (unsupportedNode) {
+        throw new Error(`BPMN node type is not allowed: ${unsupportedNode.type} (${unsupportedNode.id})`);
+      }
+    }
+    if (this._allowedEdgeTypes) {
+      const unsupportedEdge = model?.edges?.find((edge) => !this._allowedEdgeTypes.has(edge.type || 'sequenceFlow'));
+      if (unsupportedEdge) {
+        throw new Error(`BPMN edge type is not allowed: ${unsupportedEdge.type || 'sequenceFlow'} (${unsupportedEdge.id})`);
+      }
+    }
+  }
+
   getState() {
     return {
       model: cloneModel(this._model),
@@ -118,6 +174,8 @@ export class BpmnStudioController {
       canRedo: this.history.canRedo,
       engine: this._model.engine,
       propertiesProfile: this.propertiesProfile,
+      allowedNodeTypes: this._allowedNodeTypes ? [...this._allowedNodeTypes] : null,
+      allowedEdgeTypes: this._allowedEdgeTypes ? [...this._allowedEdgeTypes] : null,
       activeScopeId: this.activeScopeId,
       scopePath: getScopePath(this._model, this.activeScopeId),
     };
@@ -143,6 +201,7 @@ export class BpmnStudioController {
   }
 
   setModel(model, { resetHistory = true } = {}) {
+    this._assertAllowedModel(model);
     const previousScopeId = this.activeScopeId;
     this._model = model;
     applyContainmentOperation(this._model, { type: 'reconcile' });
@@ -192,6 +251,7 @@ export class BpmnStudioController {
   }
 
   groupSelection() {
+    if (!this.allowsNodeType('group')) return null;
     const selected = selectedDiagramNodes(this._model, this.selection, this.activeScopeId);
     const groupable = selectedGroupableNodes(this._model, this.selection, this.activeScopeId);
     if (!groupable.length || groupable.length !== selected.length) return null;
@@ -303,6 +363,7 @@ export class BpmnStudioController {
   createNode({ nodeType, point, preset = {} } = {}) {
     const def = NODE_DEFINITIONS[nodeType];
     if (!def) throw new Error(`Unknown BPMN node type: ${nodeType}`);
+    if (!this.allowsNodeType(nodeType)) throw new Error(`BPMN node type is not allowed: ${nodeType}`);
     const position = point || { x: 100, y: 100 };
     let node;
     this._commit('create-node', () => {
@@ -331,9 +392,15 @@ export class BpmnStudioController {
     for (const spec of nodeSpecs) {
       if (!spec.key || keys.has(spec.key)) throw new Error('Template node keys must be unique.');
       if (!NODE_DEFINITIONS[spec.nodeType]) throw new Error(`Unknown BPMN node type: ${spec.nodeType}`);
+      if (!this.allowsNodeType(spec.nodeType)) throw new Error(`BPMN node type is not allowed: ${spec.nodeType}`);
       keys.add(spec.key);
     }
-    for (const edge of template.edges || []) if (!keys.has(edge.source) || !keys.has(edge.target)) throw new Error('Template edge references an unknown node key.');
+    for (const edge of template.edges || []) {
+      if (!keys.has(edge.source) || !keys.has(edge.target)) throw new Error('Template edge references an unknown node key.');
+      const edgeType = edge.preset?.type || 'sequenceFlow';
+      if (!EDGE_DEFINITIONS[edgeType]) throw new Error(`Unknown BPMN edge type: ${edgeType}`);
+      if (!this.allowsEdgeType(edgeType)) throw new Error(`BPMN edge type is not allowed: ${edgeType}`);
+    }
     const result = { nodes: [], edges: [] };
     const byKey = new Map();
     this._commit('create-template', () => {
@@ -355,6 +422,9 @@ export class BpmnStudioController {
   }
 
   connect(source, target, overrides = {}) {
+    const edgeType = overrides.type || 'sequenceFlow';
+    if (!EDGE_DEFINITIONS[edgeType]) throw new Error(`Unknown BPMN edge type: ${edgeType}`);
+    if (!this.allowsEdgeType(edgeType)) throw new Error(`BPMN edge type is not allowed: ${edgeType}`);
     if (!canCreateSequenceFlow(this._model, source, target)) return null;
     let edge;
     this._commit('connect', () => {
@@ -366,6 +436,7 @@ export class BpmnStudioController {
   }
 
   startConnect(sourceId) {
+    if (!this.allowsEdgeType('sequenceFlow')) return false;
     const source = getNode(this._model, sourceId);
     const definition = source && (NODE_DEFINITIONS[source.type] || NODE_DEFINITIONS.generic);
     if (!source || elementScopeId(this._model, source) !== this.activeScopeId || !SEQUENCE_FLOW_KINDS.has(definition.kind) || definition.eventStage === 'end') return false;
@@ -407,6 +478,9 @@ export class BpmnStudioController {
   updateNode(id, patch = {}) {
     const node = getNode(this._model, id);
     if (!node) return false;
+    if (patch.type !== undefined && patch.type !== node.type) {
+      throw new Error('Node type changes must use changeNodeType().');
+    }
     const previousLabelPlacement = resolveSwimlaneLabelPlacement(this._model, node);
     this._commit('update-node', () => {
       if (patch.properties) node.properties = { ...node.properties, ...patch.properties };
@@ -431,6 +505,9 @@ export class BpmnStudioController {
   updateEdge(id, patch = {}) {
     const edge = getEdge(this._model, id);
     if (!edge) return false;
+    if (patch.type !== undefined && patch.type !== (edge.type || 'sequenceFlow')) {
+      throw new Error('Edge type cannot be changed through updateEdge().');
+    }
     this._commit('update-edge', () => {
       if (patch.properties) edge.properties = { ...(edge.properties || {}), ...patch.properties };
       const rest = { ...patch }; delete rest.properties;
@@ -500,7 +577,7 @@ export class BpmnStudioController {
   changeNodeType(id, type) {
     const node = getNode(this._model, id);
     const def = NODE_DEFINITIONS[type];
-    if (!node || !def || node.type === type) return false;
+    if (!node || !def || !this.allowsNodeType(type) || node.type === type) return false;
     if (isEmbeddedSubProcess(node) && !isEmbeddedSubProcess(type) && hasScopeChildren(this._model, id)) return false;
     this._commit('change-node-type', () => {
       const next = createNode(type, node.x, node.y, { id: node.id, name: node.name });
@@ -514,9 +591,10 @@ export class BpmnStudioController {
   }
 
   quickAdd(sourceId, type = 'userTask', preset = {}) {
+    if (!this.allowsEdgeType('sequenceFlow')) return null;
     const source = getNode(this._model, sourceId);
     const def = NODE_DEFINITIONS[type];
-    if (!source || elementScopeId(this._model, source) !== this.activeScopeId || !def) return null;
+    if (!source || elementScopeId(this._model, source) !== this.activeScopeId || !def || !this.allowsNodeType(type)) return null;
     const direction = this._model.settings?.direction || 'horizontal';
     const spacing = LAYOUT_DENSITIES[this._model.settings?.layoutDensity || 'balanced'] || LAYOUT_DENSITIES.balanced;
     const outgoingCount = this._model.edges.filter((edge) => edge.source === sourceId).length;

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export * from './modules/palette/index.js'
 import type {
   BpmnEdge,
   BpmnNode,
+  EdgeType,
   ElementSelection,
   EngineId,
   LayoutOptions,
@@ -25,6 +26,7 @@ import type {
 import type { IconRegistry } from './modules/icons/index.js'
 import type { PaletteRegistry } from './modules/palette/index.js'
 import type { PropertiesRegistry } from './modules/properties/index.js'
+import type { NodeSubtitleResolver } from './modules/node-presentation/index.js'
 import type { DiagramNodeRenderer, DiagramRendererOptions } from './modules/renderer-svg/index.js'
 import type { RuntimeTimelineSvgRenderer, SvgExportArtifact, SvgExportOptions, SvgExportPreviewController, SvgNodeRenderer } from './modules/export-svg/index.js'
 import type {
@@ -37,6 +39,8 @@ import type {
   RuntimeTransitionDetailsRenderer,
 } from './modules/viewer/index.js'
 
+export type { NodeSubtitleResolver, NodeSubtitleResolverContext } from './modules/node-presentation/index.js'
+
 // Aggregate compatibility surface. Studio re-exports the package-level types,
 // and keeps these frequently consumed declarations visible at its own entry.
 export interface ScopedElement { scopeId?: string }
@@ -140,6 +144,7 @@ export interface ViewerOptions {
   iconRegistry?: IconRegistry
   nodeRenderers?: Record<string, Function>
   nodeRenderer?: Function
+  nodeSubtitleResolver?: NodeSubtitleResolver
   projection?: ViewerProjection
   responsive?: boolean
   timeline?: ViewerTimelineOptions
@@ -172,6 +177,7 @@ export class BpmnViewer {
   traceProjection: RuntimeTraceProjection | null
   setModel(model: ProcessModel): void
   setRuntime(runtime: ProcessInstanceSnapshot | null): void
+  refreshPresentation(): void
   setDisplayOptions(options: { timeline?: ViewerTimelineOptions; runtimeDetails?: RuntimeDetailsOptions; runtimeTraceOptions?: RuntimeTraceProjectionOptions; runtimeAssetResolver?: import('./modules/viewer/index.js').RuntimeAssetResolver | null }): void
   setProjection(projection: ViewerProjection): void
   setTheme(theme: NovaThemeInput): NovaThemeState
@@ -201,9 +207,16 @@ export interface StudioState {
   canRedo: boolean
   engine: EngineId
   propertiesProfile: 'business' | 'developer'
+  allowedNodeTypes: NodeType[] | null
+  allowedEdgeTypes: EdgeType[] | null
   activeScopeId: string
   scopePath: Array<{ id: string; name: string; kind: 'process' | 'subProcess' }>
 }
+export interface StudioValidationIssue {
+  level: 'error' | 'warning'
+  elementId?: string
+  message: string
+}
 export interface NodePreset extends Partial<Omit<BpmnNode, 'properties'>> { properties?: Record<string, unknown> }
 export interface TemplateDefinition {
   nodes: Array<{ key: string; nodeType: NodeType; offset?: Point; preset?: NodePreset }>
@@ -223,6 +236,8 @@ export interface StudioControllerOptions {
   historyLimit?: number
   extensions?: StudioExtension[]
   propertiesProfile?: 'business' | 'developer'
+  allowedNodeTypes?: Iterable<NodeType> | null
+  allowedEdgeTypes?: Iterable<EdgeType> | null
 }
 export interface StudioCommands {
   createNode(input: { nodeType: NodeType; point?: Point; preset?: NodePreset }): BpmnNode
@@ -289,6 +304,8 @@ export class BpmnStudioController {
   navigateToScope(scopeId: string): boolean
   setModel(model: ProcessModel, options?: { resetHistory?: boolean }): void
   setPropertiesProfile(profile: 'business' | 'developer'): void
+  allowsNodeType(nodeType: NodeType): boolean
+  allowsEdgeType(edgeType: EdgeType): boolean
   startConnect(sourceId: string): boolean
   cancelConnect(): void
   createNode(input: Parameters<StudioCommands['createNode']>[0]): BpmnNode
@@ -311,6 +328,7 @@ export class BpmnStudioController {
   redo(): boolean
   exportXml(engine?: EngineId): string
   importXml(xml: string, engine?: EngineId): ProcessModel
+  validate(): StudioValidationIssue[]
   registerExtension(extension: StudioExtension): () => void
   destroy(): void
 }
@@ -401,6 +419,7 @@ export interface BpmnCanvasOptions {
   container: HTMLElement
   studio: BpmnStudioController
   rendererOptions?: DiagramRendererOptions
+  nodeSubtitleResolver?: NodeSubtitleResolver
   interactions?: InteractionController | null
   selectionToolbar?: HTMLElement | SelectionToolbarSlot | null
   contextMenu?: HTMLElement | ContextMenuSlot | null
@@ -414,6 +433,7 @@ export class BpmnCanvas {
   clientToWorld(clientX: number, clientY: number): Point
   getViewportCenterWorld(): Point
   fitView(padding?: number, options?: Record<string, unknown>): void
+  refreshPresentation(): void
   fitSelection(padding?: number): boolean
   setPointerMode(mode: 'select' | 'marquee' | 'pan'): boolean
   getPointerMode(): 'select' | 'marquee' | 'pan'
@@ -430,10 +450,59 @@ export class BpmnCanvas {
 }
 export function createBpmnCanvas(options: BpmnCanvasOptions): BpmnCanvas
 
+export interface StudioShellActions {
+  undo(): boolean
+  redo(): boolean
+  beautify(options?: LayoutOptions): void
+  rerouteEdges(options?: LayoutOptions): void
+  fitView(): void
+  validate(): StudioValidationIssue[]
+  importXml(xml: string, engine?: EngineId): ProcessModel
+  exportXml(engine?: EngineId): string
+  exportSvg(options?: SvgExportOptions): Promise<SvgExportArtifact>
+  openSvgExportPreview(options?: SvgExportOptions & {
+    previewTitle?: string
+    onDownload?: (artifact: SvgExportArtifact) => void
+  }): SvgExportPreviewController | null
+}
+export type StudioMode = 'design' | 'viewer' | 'instance'
+export type StudioModeChangeSource = 'toolbar' | 'api' | 'allowed-modes'
+export interface StudioModeChangeEvent {
+  readonly mode: StudioMode
+  readonly previousMode: StudioMode
+  readonly source: StudioModeChangeSource
+  readonly allowedModes: readonly StudioMode[]
+}
+export type StudioValidationSource = 'toolbar' | 'api'
+export interface StudioValidationEvent {
+  readonly source: StudioValidationSource
+  readonly valid: boolean
+  readonly errorCount: number
+  readonly warningCount: number
+  readonly issues: readonly StudioValidationIssue[]
+}
+export interface StudioShellSlotContext {
+  studio: BpmnStudioController
+  shell: BpmnStudioShell
+  canvas: BpmnCanvas
+  actions: StudioShellActions
+  getState(): StudioState
+  subscribe(listener: (event: StudioEvent) => void): () => void
+  getMode(): StudioMode
+  getAllowedModes(): readonly StudioMode[]
+  subscribeMode(listener: (event: StudioModeChangeEvent) => void): () => void
+  subscribeValidation(listener: (event: StudioValidationEvent) => void): () => void
+}
+export type StudioShellDomSlot =
+  | HTMLElement
+  | ((context: StudioShellSlotContext & { container: HTMLElement }) => void | (() => void))
 export interface StudioShellSlots {
-  left?: HTMLElement | ((context: Record<string, unknown>) => void | (() => void))
-  right?: HTMLElement | ((context: Record<string, unknown>) => void | (() => void))
-  header?: HTMLElement | ((context: Record<string, unknown>) => void | (() => void))
+  left?: StudioShellDomSlot
+  right?: StudioShellDomSlot
+  headerStart?: StudioShellDomSlot
+  headerActions?: StudioShellDomSlot
+  header?: StudioShellDomSlot
+  footer?: StudioShellDomSlot
   contextMenu?: ContextMenuSlot
   selectionToolbar?: SelectionToolbarSlot
   runtimeDetails?: RuntimeDetailsRenderer
@@ -441,6 +510,19 @@ export interface StudioShellSlots {
   runtimeTimeline?: RuntimeTimelineRenderer
   [name: string]: HTMLElement | Function | undefined
 }
+export type StudioShellRegionMode = 'default' | 'hidden'
+export interface StudioShellRegions {
+  header?: StudioShellRegionMode
+  left?: StudioShellRegionMode
+  right?: StudioShellRegionMode
+  footer?: StudioShellRegionMode
+}
+export interface StudioShellRegionState {
+  header: StudioShellRegionMode
+  left: StudioShellRegionMode
+  right: StudioShellRegionMode
+  footer: StudioShellRegionMode
+}
 export interface StudioShellOptions {
   container: HTMLElement
   studio: BpmnStudioController
@@ -453,10 +535,13 @@ export interface StudioShellOptions {
     runtimeTraceOptions?: RuntimeTraceProjectionOptions
     timeline?: ViewerTimelineOptions
   }
+  nodeSubtitleResolver?: NodeSubtitleResolver
   slots?: StudioShellSlots
+  regions?: StudioShellRegions
   layout?: (context: Record<string, unknown>) => void | (() => void)
   runtime?: ProcessInstanceSnapshot | null
-  mode?: 'design' | 'viewer' | 'instance'
+  mode?: StudioMode
+  allowedModes?: readonly StudioMode[]
   projection?: ViewerProjection
   responsive?: boolean
   projectionOptions?: Array<{ value: ViewerProjection; label: string }>
@@ -469,9 +554,17 @@ export interface StudioShellOptions {
 }
 export class BpmnStudioShell {
   constructor(options: StudioShellOptions)
+  readonly actions: StudioShellActions
   canvas?: BpmnCanvas
   viewer?: BpmnViewer
-  setMode(mode: 'design' | 'viewer' | 'instance'): void
+  getMode(): StudioMode
+  getAllowedModes(): readonly StudioMode[]
+  subscribeMode(listener: (event: StudioModeChangeEvent) => void): () => void
+  subscribeValidation(listener: (event: StudioValidationEvent) => void): () => void
+  setAllowedModes(modes: readonly StudioMode[]): readonly StudioMode[]
+  getRegions(): Readonly<StudioShellRegionState>
+  setRegions(regions: StudioShellRegions): Readonly<StudioShellRegionState>
+  setMode(mode: StudioMode): boolean
   setRuntime(runtime: ProcessInstanceSnapshot | null): void
   setProjection(projection: ViewerProjection): void
   setTheme(theme: NovaThemeInput): NovaThemeState
@@ -479,6 +572,8 @@ export class BpmnStudioShell {
   getThemeState(): NovaThemeState
   subscribeTheme(listener: (state: NovaThemeState) => void): () => void
   setRuntimeAppearance(options: RuntimeAppearanceOptions | null): void
+  refreshPresentation(): void
+  validate(): StudioValidationIssue[]
   fitView(): void
   zoomBy(factor: number): void
   exportSvg(options?: SvgExportOptions): Promise<SvgExportArtifact>

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

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