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

package/README.md

@@ -4,7 +4,7 @@ BPMN Nova 的 React 18+ Adapter，提供 Studio、Designer、Viewer、审批轨
 
 > **English summary:** React 18+ components and refs for BPMN Nova process design, viewing, approval traces, properties, themes, and SVG export.
 
-> 当前版本为 `0.3.1-preview`。React 与 React DOM 由宿主工程提供，本包不会替应用选择或升级框架版本。
+> 当前版本为 `0.3.3-preview`。React 与 React DOM 由宿主工程提供，本包不会替应用选择或升级框架版本。
 
 ![BPMN Nova React 流程工作台](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-designer.jpg)
 
@@ -20,6 +20,8 @@ import '@bpmn-nova/react/styles.css'
 
 只安装本包；`@bpmn-nova/studio` 会作为内部依赖自动解析。容器必须有明确高度。
 
+使用代码生成助手或 IDE Agent 接入时，从随包的 `llms.txt` 开始；需要完整接口和定制资料时再读取 `llms-full.txt`。两份文件都包含在 npm tarball 中，不依赖源码仓库可见性。
+
 ## 流程设计
 
 ```jsx
@@ -27,16 +29,17 @@ import { useRef } from 'react'
 import { BpmnStudio } from '@bpmn-nova/react'
 import '@bpmn-nova/react/styles.css'
 
-export function WorkflowEditor({ xml }) {
+export function WorkflowEditor({ initialXml }) {
   const studioRef = useRef(null)
 
   return (
     <div style={{ height: 720 }}>
       <BpmnStudio
         ref={studioRef}
-        xml={xml}
+        xml={initialXml}
         engine="flowable"
         mode="design"
+        allowedModes={['design']}
         theme="auto"
         onChange={(model, reason, nextXml) => {
           console.log(reason, nextXml)
@@ -47,7 +50,91 @@ export function WorkflowEditor({ xml }) {
 }
 ```
 
-Ref 提供 `exportXml()`、`fitView()`、`setTheme()`、`exportSvg()` 和 `openSvgExportPreview()`。
+Ref 提供 `actions`、`validate()`、`exportXml()`、`fitView()`、`setTheme()`、`exportSvg()` 和 `openSvgExportPreview()`。
+
+`xml`/`model` 是外部替换输入，`onChange` 的 XML 是草稿输出。宿主回写完全相同的导出 XML 不会重新导入或清空撤销历史；切换服务器 revision 或流程时传入不同 XML 会替换模型。Activiti 宿主应显式使用 `engine="activiti"`。
+
+## 组合宿主头部与业务属性面板
+
+默认 `BpmnStudio` 是完整工作台。通过 `regions={{ right: 'hidden' }}` 隐藏 Nova Properties 后，Canvas 会获得该轨道的全部宽度；宿主属性面板应作为外部兄弟区域渲染。
+
+```jsx
+<BpmnStudio
+  ref={studioRef}
+  xml={xml}
+  engine="activiti"
+  mode="design"
+  allowedModes={['design']}
+  allowedNodeTypes={supportedNodeTypes}
+  allowedEdgeTypes={['sequenceFlow']}
+  regions={{ right: 'hidden' }}
+  theme="auto"
+  headerStart={({ state, actions }) => (
+    <HostProcessIdentity onBack={back} />
+  )}
+  headerActions={({ actions, mode }) => (
+    <HostWorkflowActions
+      disabled={mode !== 'design'}
+      onValidate={() => actions.validate()}
+      onSave={() => saveDraft(actions.exportXml())}
+      onPublish={() => publishProcess(actions)}
+    />
+  )}
+  onChange={handleChange}
+  onValidation={(event) => handleValidation(event)}
+  onSelectionChange={(selection, element) => {
+    setSelectedElement(selection ? element : null)
+  }}
+/>
+```
+
+`headerStart` 只替换 Nova Brand；`headerActions` 只替换默认“校验 / 导入 / 导出”动作组，适合组合“校验 / 保存 / 发布”；`header` 可完整替换 Header。它们都通过 React Portal 在当前组件树内渲染，保留 Context 和生命周期。默认 Header 的最佳视图只保留在底部缩放区。
+
+`actions.validate()` 以 `toolbar` 来源先更新 Nova 默认状态栏，再调用 `onValidation` 并返回 issues；Ref `validate()` 使用 `api` 来源。事件的 `valid` 仅由 error 决定，warning 会保留在 `issues` 中但不默认阻止发布。保存与发布仍由宿主负责。
+
+```js
+async function publishProcess(actions) {
+  const issues = actions.validate()
+  if (issues.some((issue) => issue.level === 'error')) return
+  await publishXml(actions.exportXml())
+}
+```
+
+宿主属性面板以 `onSelectionChange` 为选择状态来源；它覆盖节点、连线、多选、清空与键盘选择。`onElementClick` 只是点击观察事件，不能代替选择状态。宿主通过稳定 BPMN Element ID 关联业务配置，并自行负责保存、发布、权限与服务端事务。
+
+## Mode 双向同步与副标题刷新
+
+```jsx
+import { useCallback, useRef, useState } from 'react'
+
+const [mode, setMode] = useState('design')
+const summaries = useRef(new Map())
+const resolveSubtitle = useCallback(
+  ({ node }) => summaries.current.has(node.id)
+    ? summaries.current.get(node.id)
+    : undefined,
+  [],
+)
+
+<BpmnStudio
+  ref={studioRef}
+  xml={xml}
+  mode={mode}
+  allowedModes={['design', 'viewer']}
+  onModeChange={(event) => setMode(event.mode)}
+  nodeSubtitleResolver={resolveSubtitle}
+  headerStart={({ mode: actualMode }) => (
+    <HostHeader mode={actualMode} />
+  )}
+/>
+
+function updateArchiveSummary() {
+  summaries.current.set('ServiceTask_Archive', '归档到采购系统')
+  studioRef.current?.refreshPresentation()
+}
+```
+
+Ref 的 `mode` Getter 与 `setMode()` 始终反映 Shell 实际状态。Resolver 返回 `undefined` 保留默认值、`null` 移除副标题行、字符串替换显示；函数引用变化会自动刷新，稳定闭包内部数据变化需显式调用 `refreshPresentation()`。Resolver 只影响 Design/Viewer 标准卡片和 SVG，不覆盖 Instance Runtime Presentation，也不修改 XML、History、Selection 或 Viewport。
 
 ## 只读展示与审批轨迹
 
@@ -161,6 +248,10 @@ studioRef.current?.openSvgExportPreview({
 - `createReactRuntimeDetailsComponent`
 - `createReactRuntimeTransitionDetailsComponent`
 - `createReactRuntimeTimelineComponent`
+- `createStudioController`、`createEmptyProcess`、`importBpmn`、`exportBpmn`
+- Palette、Properties、Context Menu、Icon 和 Template Registry 的公开创建函数
+
+完整工作台可通过 `allowedNodeTypes` 与 `allowedEdgeTypes` 限制宿主支持的图元类型，通过 `allowedModes` 限制可切换的工作台模式。图元限制同时作用于 XML 导入、Palette、连接、快捷新增、模板和节点类型转换。
 
 ## 常见问题
 
@@ -172,11 +263,11 @@ studioRef.current?.openSvgExportPreview({
 
 ## 文档与 AI
 
+- npm 包内 `llms.txt`：可执行安装入口
+- npm 包内 `llms-full.txt`：完整 AI 上下文
 - [完整项目能力](https://github.com/daxiangme/bpmn-nova)
 - [React/Vue 组件说明](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/COMPONENTS.md)
 - [公开 Interface](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/API.md)
-- [AI 接入入口](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/llms.txt)
-- [AI 完整上下文](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/llms-full.txt)
 
 ## License
 

package/dist/index.d.ts

@@ -2,12 +2,19 @@ import type {
   ComponentType,
   CSSProperties,
   ForwardRefExoticComponent,
+  ReactNode,
   RefAttributes,
 } from 'react'
-import type { BpmnEdge, BpmnNode, ElementSelection, EngineId, LayoutOptions, ProcessModel } from '@bpmn-nova/studio'
+import type { BpmnEdge, BpmnNode, EdgeType, ElementSelection, EngineId, LayoutOptions, NodeType, ProcessModel } from '@bpmn-nova/studio'
 import type { BpmnDesigner as DesignerInstance } from '@bpmn-nova/studio/designer'
 import type { IconRegistry } from '@bpmn-nova/studio'
-import type { PaletteItem, PaletteProvider, PaletteRegistry, PaletteSection } from '@bpmn-nova/studio'
+import type {
+  PaletteItemRenderer,
+  PalettePanel as PalettePanelInstance,
+  PaletteProvider,
+  PaletteRegistry,
+  PaletteSectionRenderer,
+} from '@bpmn-nova/studio'
 import type {
   PropertiesContext,
   PropertiesProvider,
@@ -22,8 +29,15 @@ import type {
   BpmnStudioShell,
   ContextMenuRegistry,
   InteractionController,
+  NodeSubtitleResolver,
   StudioCommands,
+  StudioShellActions,
+  StudioMode,
+  StudioModeChangeEvent,
+  StudioValidationEvent,
+  StudioValidationIssue,
   StudioShellOptions,
+  StudioShellRegions,
   StudioShellSlots,
   StudioState,
   TemplateRegistry,
@@ -39,6 +53,33 @@ import type {
   ViewerProjection,
 } from '@bpmn-nova/studio/viewer'
 
+export {
+  createContextMenuRegistry,
+  createDefaultContextMenuRegistry,
+  createDefaultIconRegistry,
+  createDefaultPaletteRegistry,
+  createDefaultPropertiesRegistry,
+  createEmptyProcess,
+  createPaletteRegistry,
+  createPropertiesRegistry,
+  createStudioController,
+  createTemplateRegistry,
+  exportBpmn,
+  importBpmn,
+  propertyEntry,
+  propertyGroup,
+  registerActivitiProperties,
+  registerBpmnProperties,
+  registerFlowableProperties,
+} from '@bpmn-nova/studio'
+export type {
+  NodeSubtitleResolver,
+  NodeSubtitleResolverContext,
+  StudioValidationEvent,
+  StudioValidationIssue,
+  StudioValidationSource,
+} from '@bpmn-nova/studio'
+
 export interface BpmnNovaVisualProps {
   theme?: NovaThemeInput
   runtimeAppearance?: RuntimeAppearanceOptions
@@ -54,6 +95,8 @@ export interface BpmnModelProps {
 export interface UseBpmnStudioOptions extends BpmnModelProps {
   studio?: BpmnStudioController
   propertiesProfile?: 'business' | 'developer'
+  allowedNodeTypes?: NodeType[]
+  allowedEdgeTypes?: EdgeType[]
 }
 export interface UseBpmnStudioResult { studio: BpmnStudioController; state: StudioState; commands: StudioCommands }
 export function useBpmnStudio(options?: UseBpmnStudioOptions): UseBpmnStudioResult
@@ -65,11 +108,13 @@ export interface BpmnCanvasProps extends BpmnNovaVisualProps {
   iconRegistry?: IconRegistry
   nodeRenderers?: Record<string, Function>
   nodeRenderer?: Function
+  nodeSubtitleResolver?: NodeSubtitleResolver
   svgExport?: ViewerOptions['svgExport']
 }
 export interface BpmnCanvasHandle {
   readonly instance: CanvasInstance | null
   fitView(padding?: number, options?: Record<string, unknown>): void
+  refreshPresentation(): void
   clientToWorld(x: number, y: number): { x: number; y: number } | undefined
   setTheme(theme: NovaThemeInput): NovaThemeState | undefined
   exportSvg(options?: SvgExportOptions): Promise<SvgExportArtifact> | undefined
@@ -85,11 +130,11 @@ export interface BpmnPalettePanelProps extends BpmnNovaVisualProps {
   providers?: PaletteProvider[]
   canvas?: CanvasInstance | null
   iconRegistry?: IconRegistry
-  renderItem?: (context: { item: PaletteItem; panel: unknown }) => HTMLElement | null
-  renderSection?: (context: { section: PaletteSection; panel: unknown }) => HTMLElement | null
+  renderItem?: PaletteItemRenderer
+  renderSection?: PaletteSectionRenderer
 }
 export interface BpmnPalettePanelHandle {
-  readonly panel: unknown
+  readonly panel: PalettePanelInstance | null
   render(): void
   setTheme(theme: NovaThemeInput): NovaThemeState | undefined
 }
@@ -98,6 +143,8 @@ export const BpmnPalettePanel: ForwardRefExoticComponent<BpmnPalettePanelProps &
 export interface BpmnStudioProps extends BpmnNovaVisualProps, BpmnModelProps {
   studio?: BpmnStudioController
   propertiesProfile?: 'business' | 'developer'
+  allowedNodeTypes?: NodeType[]
+  allowedEdgeTypes?: EdgeType[]
   iconRegistry?: IconRegistry
   paletteRegistry?: PaletteRegistry
   propertiesRegistry?: PropertiesRegistry
@@ -105,10 +152,16 @@ export interface BpmnStudioProps extends BpmnNovaVisualProps, BpmnModelProps {
   contextMenuRegistry?: ContextMenuRegistry
   nodeRenderers?: Record<string, Function>
   nodeRenderer?: Function
+  nodeSubtitleResolver?: NodeSubtitleResolver
   slots?: StudioShellSlots
   layout?: StudioShellOptions['layout']
+  regions?: StudioShellRegions
+  headerStart?: BpmnStudioRenderSlot
+  headerActions?: BpmnStudioRenderSlot
+  header?: BpmnStudioRenderSlot
   runtime?: ProcessInstanceSnapshot | null
-  mode?: 'design' | 'viewer' | 'instance'
+  mode?: StudioMode
+  allowedModes?: readonly StudioMode[]
   projection?: ViewerProjection
   responsive?: boolean
   projectionOptions?: Array<{ value: ViewerProjection; label: string }>
@@ -132,10 +185,28 @@ export interface BpmnStudioProps extends BpmnNovaVisualProps, BpmnModelProps {
   onChange?: (model: ProcessModel, reason: string, xml: string) => void
   onSelectionChange?: (selection: ElementSelection | null, element: StudioState['selectedElement']) => void
   onScopeChange?: (activeScopeId: string, scopePath: StudioState['scopePath'], state: StudioState) => void
+  onModeChange?: (event: StudioModeChangeEvent) => void
+  onValidation?: (event: StudioValidationEvent) => void
+}
+export interface BpmnStudioRenderContext {
+  readonly studio: BpmnStudioController
+  readonly shell: BpmnStudioShell
+  readonly actions: StudioShellActions
+  readonly state: Readonly<StudioState>
+  readonly mode: StudioMode
 }
+export type BpmnStudioRenderSlot = ReactNode | ((context: BpmnStudioRenderContext) => ReactNode)
 export interface BpmnStudioHandle {
   readonly studio: BpmnStudioController
   readonly shell: BpmnStudioShell | null
+  readonly actions: StudioShellActions | null
+  readonly mode: StudioMode | undefined
+  getMode(): StudioMode | undefined
+  getAllowedModes(): readonly StudioMode[]
+  setMode(mode: StudioMode): boolean
+  setAllowedModes(modes: readonly StudioMode[]): readonly StudioMode[]
+  refreshPresentation(): void
+  validate(): StudioValidationIssue[]
   exportXml(engine?: EngineId): string
   fitView(): void
   setTheme(theme: NovaThemeInput): NovaThemeState | undefined
@@ -167,6 +238,7 @@ export interface BpmnViewerProps extends BpmnNovaVisualProps, BpmnModelProps, Om
 export interface BpmnViewerHandle {
   readonly instance: ViewerInstance | null
   fitView(): void
+  refreshPresentation(): void
   setProjection(projection: ViewerProjection): void
   setRuntime(runtime: ProcessInstanceSnapshot | null): void
   setDisplayOptions(options: Parameters<ViewerInstance['setDisplayOptions']>[0]): void

package/dist/index.js

@@ -1,4 +1,5 @@
 import React, { forwardRef, useEffect, useImperativeHandle, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
 import { BpmnDesigner as CoreDesigner } from '@bpmn-nova/studio/designer';
 import { BpmnViewer as CoreViewer } from '@bpmn-nova/studio/viewer';
 import { importBpmn, exportBpmn } from '@bpmn-nova/studio';
@@ -6,6 +7,26 @@ import { createEmptyProcess } from '@bpmn-nova/studio';
 import { BpmnCanvas as CoreCanvas, BpmnStudioShell as CoreStudioShell, createInteractionController, createStudioController, createTemplateRegistry } from '@bpmn-nova/studio';
 import { createDefaultPaletteRegistry, PalettePanel as CorePalettePanel } from '@bpmn-nova/studio';
 
+export {
+  createContextMenuRegistry,
+  createDefaultContextMenuRegistry,
+  createDefaultIconRegistry,
+  createDefaultPaletteRegistry,
+  createDefaultPropertiesRegistry,
+  createEmptyProcess,
+  createPaletteRegistry,
+  createPropertiesRegistry,
+  createStudioController,
+  createTemplateRegistry,
+  exportBpmn,
+  importBpmn,
+  propertyEntry,
+  propertyGroup,
+  registerActivitiProperties,
+  registerBpmnProperties,
+  registerFlowableProperties,
+} from '@bpmn-nova/studio';
+
 export function createReactRuntimeDetailsComponent(Component) {
   return ({ container, ...context }) => {
     const root = createRoot(container);
@@ -30,7 +51,7 @@ function resolveModel({ model, xml, engine = 'flowable' }) {
 
 export function useBpmnStudio(options = {}) {
   const ownedRef = useRef(null);
-  if (!options.studio && !ownedRef.current) ownedRef.current = createStudioController({ model: resolveModel(options), propertiesProfile: options.propertiesProfile });
+  if (!options.studio && !ownedRef.current) ownedRef.current = createStudioController({ model: resolveModel(options), propertiesProfile: options.propertiesProfile, allowedNodeTypes: options.allowedNodeTypes, allowedEdgeTypes: options.allowedEdgeTypes });
   const studio = options.studio || ownedRef.current;
   const [state, setState] = useState(() => studio.getState());
   useEffect(() => studio.subscribe((event) => setState(event.state)), [studio]);
@@ -41,9 +62,13 @@ export function useBpmnStudio(options = {}) {
 export const BpmnCanvas = forwardRef(function BpmnCanvas(props, ref) {
   const hostRef = useRef(null);
   const instanceRef = useRef(null);
+  const subtitleResolverRef = useRef(props.nodeSubtitleResolver);
+  subtitleResolverRef.current = props.nodeSubtitleResolver;
+  const stableSubtitleResolverRef = useRef((context) => subtitleResolverRef.current?.(context));
   useImperativeHandle(ref, () => ({
     get instance() { return instanceRef.current; },
     fitView(padding, options) { instanceRef.current?.fitView(padding, options); },
+    refreshPresentation() { instanceRef.current?.refreshPresentation(); },
     clientToWorld(x, y) { return instanceRef.current?.clientToWorld(x, y); },
     setTheme(theme) { return instanceRef.current?.setTheme(theme); },
     exportSvg(options) { return instanceRef.current?.exportSvg(options); },
@@ -52,12 +77,13 @@ export const BpmnCanvas = forwardRef(function BpmnCanvas(props, ref) {
   useEffect(() => {
     if (!hostRef.current || !props.studio) return undefined;
     const interactions = props.interactions || createInteractionController({ studio: props.studio, templates: props.templates || createTemplateRegistry() });
-    const instance = new CoreCanvas({ container: hostRef.current, studio: props.studio, interactions, theme: props.theme, onThemeChange: props.onThemeChange, rendererOptions: { iconRegistry: props.iconRegistry, nodeRenderers: props.nodeRenderers, nodeRenderer: props.nodeRenderer, svgExport: props.svgExport } });
+    const instance = new CoreCanvas({ container: hostRef.current, studio: props.studio, interactions, theme: props.theme, onThemeChange: props.onThemeChange, nodeSubtitleResolver: stableSubtitleResolverRef.current, rendererOptions: { iconRegistry: props.iconRegistry, nodeRenderers: props.nodeRenderers, nodeRenderer: props.nodeRenderer, svgExport: props.svgExport } });
     instanceRef.current = instance;
     requestAnimationFrame(() => instance.fitView());
     return () => { instance.destroy(); instanceRef.current = null; };
   }, [props.studio]);
   useEffect(() => { if (props.theme !== undefined) instanceRef.current?.setTheme(props.theme); }, [props.theme]);
+  useEffect(() => { instanceRef.current?.refreshPresentation(); }, [props.nodeSubtitleResolver]);
   return React.createElement('div', { ref: hostRef, className: props.className, style: { width: '100%', height: '100%', minHeight: 320, ...props.style } });
 });
 
@@ -72,7 +98,7 @@ export const BpmnPalettePanel = forwardRef(function BpmnPalettePanel(props, ref)
     const panel = new CorePalettePanel({ container: hostRef.current, registry, studio: props.studio, interactions, canvas: props.canvas, iconRegistry: props.iconRegistry, renderItem: props.renderItem, renderSection: props.renderSection, theme: props.theme, onThemeChange: props.onThemeChange });
     panelRef.current = panel;
     return () => { panel.destroy(); panelRef.current = null; };
-  }, [props.studio, props.registry, props.interactions, props.canvas]);
+  }, [props.studio, props.registry, props.interactions, props.templates, props.canvas, props.providers, props.iconRegistry, props.renderItem, props.renderSection, props.onThemeChange]);
   useEffect(() => { if (props.theme !== undefined) panelRef.current?.setTheme(props.theme); }, [props.theme]);
   return React.createElement('div', { ref: hostRef, className: props.className, style: { width: '100%', height: '100%', overflow: 'auto', ...props.style } });
 });
@@ -81,21 +107,53 @@ export const BpmnStudio = forwardRef(function BpmnStudio(props, ref) {
   const hostRef = useRef(null);
   const ownedStudioRef = useRef(null);
   const shellRef = useRef(null);
+  const mountedModelSyncRef = useRef(false);
+  const [headerPortal, setHeaderPortal] = useState(null);
+  const [headerStartPortal, setHeaderStartPortal] = useState(null);
+  const [headerActionsPortal, setHeaderActionsPortal] = useState(null);
   const callbacksRef = useRef({});
   callbacksRef.current = props;
-  if (!props.studio && !ownedStudioRef.current) ownedStudioRef.current = createStudioController({ model: resolveModel(props), propertiesProfile: props.propertiesProfile });
+  if (!props.studio && !ownedStudioRef.current) ownedStudioRef.current = createStudioController({ model: resolveModel(props), propertiesProfile: props.propertiesProfile, allowedNodeTypes: props.allowedNodeTypes, allowedEdgeTypes: props.allowedEdgeTypes });
   const studio = props.studio || ownedStudioRef.current;
+  const [studioState, setStudioState] = useState(() => studio.getState());
+  const [actualMode, setActualMode] = useState(() => props.mode || props.allowedModes?.[0] || 'design');
+  const subtitleResolverRef = useRef(props.nodeSubtitleResolver);
+  subtitleResolverRef.current = props.nodeSubtitleResolver;
+  const stableSubtitleResolverRef = useRef((context) => subtitleResolverRef.current?.(context));
   useImperativeHandle(ref, () => ({
     studio,
     get shell() { return shellRef.current; },
+    get actions() { return shellRef.current?.actions || null; },
+    get mode() { return shellRef.current?.getMode(); },
+    getMode: () => shellRef.current?.getMode(),
+    getAllowedModes: () => shellRef.current?.getAllowedModes() || [],
+    setMode: (mode) => shellRef.current?.setMode(mode) || false,
+    setAllowedModes: (modes) => shellRef.current?.setAllowedModes(modes) || [],
+    refreshPresentation: () => shellRef.current?.refreshPresentation(),
+    validate: () => shellRef.current?.validate() || [],
     exportXml: (engine) => studio.exportXml(engine),
     exportSvg: (options) => shellRef.current?.exportSvg(options),
     openSvgExportPreview: (options) => shellRef.current?.openSvgExportPreview(options),
-    fitView: () => shellRef.current?.canvas?.fitView(),
+    fitView: () => shellRef.current?.fitView(),
     setTheme: (theme) => shellRef.current?.setTheme(theme),
   }), [studio]);
+  const hasNativeHeader = props.header !== undefined && props.header !== null;
+  const hasNativeHeaderStart = props.headerStart !== undefined && props.headerStart !== null;
+  const hasNativeHeaderActions = props.headerActions !== undefined && props.headerActions !== null;
   useEffect(() => {
     if (!hostRef.current) return undefined;
+    setStudioState(studio.getState());
+    const createPortalSlot = (setPortal) => (context) => {
+      const portal = { target: context.container, context };
+      setPortal(portal);
+      return () => setPortal((current) => current?.target === context.container ? null : current);
+    };
+    const shellSlots = { ...(props.slots || {}) };
+    if (hasNativeHeader) shellSlots.header = createPortalSlot(setHeaderPortal);
+    else if (!shellSlots.header) {
+      if (hasNativeHeaderStart) shellSlots.headerStart = createPortalSlot(setHeaderStartPortal);
+      if (hasNativeHeaderActions) shellSlots.headerActions = createPortalSlot(setHeaderActionsPortal);
+    }
     const shell = new CoreStudioShell({
       container: hostRef.current,
       studio,
@@ -103,9 +161,11 @@ export const BpmnStudio = forwardRef(function BpmnStudio(props, ref) {
       paletteRegistry: props.paletteRegistry,
       propertiesRegistry: props.propertiesRegistry,
       templateRegistry: props.templateRegistry,
+      contextMenuRegistry: props.contextMenuRegistry,
       rendererOptions: {
         nodeRenderers: props.nodeRenderers,
         nodeRenderer: props.nodeRenderer,
+        nodeSubtitleResolver: stableSubtitleResolverRef.current,
         runtimePresenter: props.runtimePresenter,
         runtimeTraceProjector: props.runtimeTraceProjector,
         runtimeAssetResolver: props.runtimeAssetResolver,
@@ -121,10 +181,12 @@ export const BpmnStudio = forwardRef(function BpmnStudio(props, ref) {
         onElementClick: (payload) => callbacksRef.current.onElementClick?.(payload),
         onTraceClick: (payload) => callbacksRef.current.onTraceClick?.(payload),
       },
-      slots: props.slots || {},
+      slots: shellSlots,
       layout: props.layout,
+      regions: props.regions,
       runtime: props.runtime,
       mode: props.mode,
+      allowedModes: props.allowedModes,
       projection: props.projection,
       responsive: props.responsive,
       projectionOptions: props.projectionOptions,
@@ -136,19 +198,46 @@ export const BpmnStudio = forwardRef(function BpmnStudio(props, ref) {
       onThemeChange: (state) => callbacksRef.current.onThemeChange?.(state),
     });
     shellRef.current = shell;
+    setActualMode(shell.getMode());
+    const offMode = shell.subscribeMode((event) => {
+      setActualMode(event.mode);
+      callbacksRef.current.onModeChange?.(event);
+    });
+    const offValidation = shell.subscribeValidation((event) => callbacksRef.current.onValidation?.(event));
     const off = studio.subscribe((event) => {
+      setStudioState(event.state);
       if (event.type === 'modelChanged') callbacksRef.current.onChange?.(studio.model, event.reason, studio.exportXml());
       if (event.type === 'selectionChanged') callbacksRef.current.onSelectionChange?.(studio.selection, studio.getSelectedElement());
       if (event.type === 'scopeChanged') callbacksRef.current.onScopeChange?.(event.activeScopeId, event.scopePath, studio.getState());
     });
-    return () => { off(); shell.destroy(); shellRef.current = null; if (!props.studio) { ownedStudioRef.current?.destroy(); ownedStudioRef.current = null; } };
-  }, [studio]);
-  useEffect(() => { if (props.model && props.model !== studio.model) studio.setModel(props.model); else if (props.xml) studio.importXml(props.xml, props.engine); }, [props.model, props.xml]);
+    return () => { offMode(); offValidation(); off(); shell.destroy(); shellRef.current = null; };
+  }, [studio, hasNativeHeader, hasNativeHeaderStart, hasNativeHeaderActions]);
+  useEffect(() => () => {
+    if (!props.studio && ownedStudioRef.current === studio) {
+      studio.destroy();
+      ownedStudioRef.current = null;
+    }
+  }, [studio, Boolean(props.studio)]);
+  useEffect(() => {
+    if (!mountedModelSyncRef.current) {
+      mountedModelSyncRef.current = true;
+      if (!props.studio) return;
+    }
+    if (props.model && props.model !== studio.model) studio.setModel(props.model);
+    else if (props.xml && props.xml !== studio.exportXml(props.engine)) studio.importXml(props.xml, props.engine);
+  }, [studio, props.model, props.xml, props.engine]);
   useEffect(() => { if (props.runtime !== undefined) shellRef.current?.setRuntime(props.runtime); }, [props.runtime]);
-  useEffect(() => { if (props.mode) shellRef.current?.setMode(props.mode); }, [props.mode]);
+  useEffect(() => {
+    const shell = shellRef.current;
+    if (!shell) return;
+    if (props.allowedModes !== undefined) shell.setAllowedModes(props.allowedModes);
+    if (props.mode) shell.setMode(props.mode);
+  }, [props.allowedModes, props.mode]);
   useEffect(() => { if (props.projection) shellRef.current?.setProjection(props.projection); }, [props.projection]);
+  useEffect(() => { if (props.regions !== undefined) shellRef.current?.setRegions(props.regions); }, [props.regions]);
   useEffect(() => { if (props.theme !== undefined) shellRef.current?.setTheme(props.theme); }, [props.theme]);
   useEffect(() => { if (props.runtimeAppearance !== undefined) shellRef.current?.setRuntimeAppearance(props.runtimeAppearance); }, [props.runtimeAppearance]);
+  useEffect(() => { shellRef.current?.refreshPresentation(); }, [props.nodeSubtitleResolver]);
   useEffect(() => {
     const shell = shellRef.current;
     if (!shell) return;
@@ -157,7 +246,23 @@ export const BpmnStudio = forwardRef(function BpmnStudio(props, ref) {
     shell.rendererOptions.runtimeTraceOptions = props.runtimeTraceOptions;
     shell.viewer?.setDisplayOptions({ timeline: props.timeline, runtimeDetails: props.runtimeDetails, runtimeTraceOptions: props.runtimeTraceOptions });
   }, [props.timeline, props.runtimeDetails, props.runtimeTraceOptions]);
-  return React.createElement('div', { ref: hostRef, className: props.className, style: { width: '100%', height: '100%', minHeight: 520, ...props.style } });
+  const renderSlot = (slot, portal, key) => {
+    if (slot === undefined || slot === null || !portal) return null;
+    const context = {
+      studio: portal.context.studio,
+      shell: portal.context.shell,
+      actions: portal.context.actions,
+      state: studioState,
+      mode: actualMode,
+    };
+    return createPortal(typeof slot === 'function' ? slot(context) : slot, portal.target, key);
+  };
+  return React.createElement(React.Fragment, null,
+    React.createElement('div', { ref: hostRef, className: props.className, style: { width: '100%', height: '100%', minHeight: 520, ...props.style } }),
+    renderSlot(props.header, headerPortal, 'bpmn-nova-header'),
+    renderSlot(props.headerStart, headerStartPortal, 'bpmn-nova-header-start'),
+    renderSlot(props.headerActions, headerActionsPortal, 'bpmn-nova-header-actions'),
+  );
 });
 
 export const BpmnDesigner = forwardRef(function BpmnDesigner(props, ref) {
@@ -221,6 +326,9 @@ export const BpmnViewer = forwardRef(function BpmnViewer(props, ref) {
   const hostRef = useRef(null);
   const instanceRef = useRef(null);
   const callbacksRef = useRef({});
+  const subtitleResolverRef = useRef(props.nodeSubtitleResolver);
+  subtitleResolverRef.current = props.nodeSubtitleResolver;
+  const stableSubtitleResolverRef = useRef((context) => subtitleResolverRef.current?.(context));
   callbacksRef.current = {
     onTraceClick: props.onTraceClick,
     onElementClick: props.onElementClick,
@@ -234,6 +342,7 @@ export const BpmnViewer = forwardRef(function BpmnViewer(props, ref) {
   useImperativeHandle(ref, () => ({
     get instance() { return instanceRef.current; },
     fitView() { instanceRef.current?.fitView(); },
+    refreshPresentation() { instanceRef.current?.refreshPresentation(); },
     setProjection(value) { instanceRef.current?.setProjection(value); },
     setRuntime(value) { instanceRef.current?.setRuntime(value); },
     setDisplayOptions(value) { instanceRef.current?.setDisplayOptions(value); },
@@ -256,6 +365,7 @@ export const BpmnViewer = forwardRef(function BpmnViewer(props, ref) {
       iconRegistry: props.iconRegistry,
       nodeRenderers: props.nodeRenderers,
       nodeRenderer: props.nodeRenderer,
+      nodeSubtitleResolver: stableSubtitleResolverRef.current,
       runtimePresenter: props.runtimePresenter,
       runtimeTraceProjector: props.runtimeTraceProjector,
       runtimeAssetResolver: props.runtimeAssetResolver,
@@ -285,6 +395,7 @@ export const BpmnViewer = forwardRef(function BpmnViewer(props, ref) {
   useEffect(() => { if (instanceRef.current && props.projection) instanceRef.current.setProjection(props.projection); }, [props.projection]);
   useEffect(() => { if (props.theme !== undefined) instanceRef.current?.setTheme(props.theme); }, [props.theme]);
   useEffect(() => { if (props.runtimeAppearance !== undefined) instanceRef.current?.setRuntimeAppearance(props.runtimeAppearance); }, [props.runtimeAppearance]);
+  useEffect(() => { instanceRef.current?.refreshPresentation(); }, [props.nodeSubtitleResolver]);
   useEffect(() => { instanceRef.current?.setDisplayOptions({ timeline: props.timeline, runtimeDetails: props.runtimeDetails, runtimeTraceOptions: props.runtimeTraceOptions, runtimeAssetResolver: props.runtimeAssetResolver }); }, [props.timeline, props.runtimeDetails, props.runtimeTraceOptions, props.runtimeAssetResolver]);
   useEffect(() => {
     if (!instanceRef.current) return;

package/dist/styles.css

@@ -511,8 +511,8 @@
 .mb-node-event,
 .mb-node-boundary { display: grid; place-items: center; z-index: 7; }
 .mb-event-shape {
-  width: 46px;
-  height: 46px;
+  width: var(--mb-event-shape-size, 46px);
+  height: var(--mb-event-shape-size, 46px);
   box-sizing: border-box;
   display: grid;
   place-items: center;
@@ -523,7 +523,7 @@
   box-shadow: var(--nova-shadow-sm);
   position: relative;
 }
-.mb-node-boundary .mb-event-shape { width: 40px; height: 40px; border-width: 2px; }
+.mb-node-boundary .mb-event-shape { width: var(--mb-event-shape-size, 40px); height: var(--mb-event-shape-size, 40px); border-width: 2px; }
 .mb-event-shape[data-stage="intermediate"],
 .mb-node-boundary .mb-event-shape { box-shadow: inset 0 0 0 3px var(--nova-color-surface), inset 0 0 0 4.5px var(--nova-color-text-muted, #8796a9), var(--nova-shadow-sm); }
 .mb-event-shape[data-stage="end"] { border-width: 4px; border-color: var(--nova-color-text-secondary); }
@@ -1141,6 +1141,8 @@ textarea.property-control { resize: vertical; }
 
 /* @bpmn-nova/internal/studio */
 .nova-studio-shell { --nova-left-width: 244px; --nova-right-width: 360px; --nova-font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei UI", "Microsoft YaHei", Arial, sans-serif; --nova-font-size-xs: 10px; --nova-font-size-sm: 12px; --nova-font-size-md: 14px; --nova-font-size-lg: 16px; --nova-font-weight-regular: 400; --nova-font-weight-medium: 500; --nova-font-weight-semibold: 600; --nova-font-weight-bold: 700; position: relative; isolation: isolate; width: 100%; height: 100%; min-height: 520px; overflow: hidden; display: grid; grid-template-rows: 58px minmax(0, 1fr); color: var(--nova-color-text, #263148); background: var(--nova-color-canvas, #f6f7fb); font-family: var(--nova-font-family); }
+.nova-studio-shell.is-header-hidden { grid-template-rows: minmax(0, 1fr); }
+.nova-studio-header[hidden], .nova-studio-left[hidden], .nova-studio-right[hidden], .nova-studio-statusbar[hidden] { display: none !important; }
 .nova-studio-header { min-width: 0; border-bottom: 1px solid var(--nova-color-divider, #e4e8f0); background: var(--nova-color-surface, #fff); display: grid; grid-template-columns: minmax(180px, auto) auto minmax(0, 1fr); align-items: center; gap: 18px; padding: 0 12px 0 14px; }
 .nova-studio-brand { min-width: 0; display: flex; align-items: center; gap: 10px; }
 .nova-studio-brand-mark { flex: none; width: 30px; height: 30px; border-radius: 9px; display: grid; place-items: center; color: var(--nova-color-text-inverse, #fff); background: linear-gradient(145deg, var(--nova-color-primary, #5362da), var(--nova-color-primary-hover)); font-size: var(--nova-font-size-md); font-weight: var(--nova-font-weight-bold); box-shadow: var(--nova-shadow-sm); }
@@ -1157,6 +1159,7 @@ textarea.property-control { resize: vertical; }
 .nova-studio-projection-switch button:hover { color: var(--nova-tone-primary-foreground, #4d59ca); background: var(--nova-color-primary-soft, #f4f5ff); }.nova-studio-projection-switch button.is-active { color: var(--nova-tone-primary-foreground, #4654c8); background: var(--nova-color-primary-soft, #eef0ff); font-weight: var(--nova-font-weight-semibold); }
 .nova-studio-tools { min-width: 0; overflow: visible; display: flex; align-items: center; justify-content: flex-end; gap: 5px; }
 .nova-studio-tools::-webkit-scrollbar { display: none; }
+.nova-studio-header-actions { min-width: 0; display: flex; align-items: center; justify-content: flex-end; gap: 5px; }
 .nova-studio-tool-divider { flex: none; width: 1px; height: 20px; margin: 0 2px; background: var(--nova-color-divider, #e4e8f0); }
 .nova-studio-tool { flex: none; min-height: 32px; border: 1px solid var(--nova-color-border, #e2e6ef); border-radius: 7px; padding: 0 10px; display: inline-flex; align-items: center; justify-content: center; gap: 5px; color: var(--nova-color-text-secondary, #4c586d); background: var(--nova-color-surface, #fff); font-size: var(--nova-font-size-sm); line-height: 18px; white-space: nowrap; cursor: pointer; }
 .nova-studio-tool:focus { outline: none; }.nova-studio-tool:focus-visible { outline: 2px solid var(--nova-color-focus-ring, #aeb7ff); outline-offset: 1px; }
@@ -1194,7 +1197,11 @@ textarea.property-control { resize: vertical; }
 .nova-studio-beautify-action-icon > .nova-icon-svg { width: 14px; height: 14px; }
 .nova-studio-beautify-action strong { font-size: var(--nova-font-size-sm); font-weight: var(--nova-font-weight-semibold); line-height: 18px; }.nova-studio-beautify-action small { color: #778195; color: var(--nova-color-text-muted, #778195); font-size: var(--nova-font-size-xs); line-height: 14px; }
 .nova-studio-body { min-width: 0; min-height: 0; display: grid; grid-template-columns: var(--nova-left-width) minmax(320px, 1fr) var(--nova-right-width); }
+.nova-studio-body.is-left-hidden { grid-template-columns: minmax(320px, 1fr) var(--nova-right-width); }
+.nova-studio-body.is-right-hidden { grid-template-columns: var(--nova-left-width) minmax(320px, 1fr); }
+.nova-studio-body.is-left-hidden.is-right-hidden { grid-template-columns: minmax(320px, 1fr); }
 .nova-studio-body.is-readonly { grid-template-columns: minmax(320px, 1fr) var(--nova-right-width); }
+.nova-studio-body.is-readonly.is-right-hidden { grid-template-columns: minmax(320px, 1fr); }
 .nova-studio-body.is-readonly .nova-studio-left { display: none; }
 .nova-studio-left, .nova-studio-right, .nova-studio-canvas-column, .nova-studio-canvas { min-width: 0; min-height: 0; overflow: hidden; }
 .nova-studio-left { border-right: 1px solid var(--nova-color-divider, #e4e8f0); background: var(--nova-color-surface, #fff); overflow-x: hidden; overflow-y: auto; overscroll-behavior: contain; }
@@ -1206,6 +1213,7 @@ textarea.property-control { resize: vertical; }
 .nova-studio-left::-webkit-scrollbar-thumb:hover, .nova-studio-right::-webkit-scrollbar-thumb:hover { background: #c1c9d5; background: var(--nova-color-text-muted); }
 .nova-studio-left::-webkit-scrollbar-button, .nova-studio-right::-webkit-scrollbar-button { display: none; width: 0; height: 0; }
 .nova-studio-canvas-column { display: grid; grid-template-rows: minmax(0, 1fr) 35px; background: var(--nova-color-canvas, #f7f8fc); }
+.nova-studio-canvas-column.is-footer-hidden { grid-template-rows: minmax(0, 1fr); }
 .nova-studio-canvas-stage { position: relative; min-width: 0; min-height: 0; overflow: hidden; }
 .nova-studio-canvas { position: relative; }
 .nova-studio-canvas-stage > .nova-studio-canvas { width: 100%; height: 100%; }
@@ -1422,6 +1430,7 @@ textarea.property-control { resize: vertical; }
 }
 @media (max-width: 720px) {
   .nova-studio-shell { grid-template-rows: 54px minmax(0,1fr); }
+  .nova-studio-shell.is-header-hidden { grid-template-rows: minmax(0, 1fr); }
   .nova-studio-header { grid-template-columns: auto minmax(0,1fr); padding-left: 9px; }
   .nova-studio-brand-copy { display: none; }
   .nova-studio-body { grid-template-columns: 1fr; }