@bpmn-nova/react 0.3.4-preview → 0.3.5-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.4-preview`。React 与 React DOM 由宿主工程提供，本包不会替应用选择或升级框架版本。
+> 当前版本为 `0.3.5-preview`。React 与 React DOM 由宿主工程提供，本包不会替应用选择或升级框架版本。
 
 ![BPMN Nova React 流程工作台](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-designer.jpg)
 
@@ -43,6 +43,8 @@ import { useRef } from 'react'
 import { BpmnStudio } from '@bpmn-nova/react'
 import '@bpmn-nova/react/styles.css'
 
+const STUDIO_CONFIG = { ui: { controlSize: 'medium' } }
+
 export function WorkflowEditor({ initialXml }) {
   const studioRef = useRef(null)
 
@@ -52,6 +54,7 @@ export function WorkflowEditor({ initialXml }) {
         ref={studioRef}
         xml={initialXml}
         engine="flowable"
+        config={STUDIO_CONFIG}
         mode="design"
         allowedModes={['design']}
         theme="auto"
@@ -70,7 +73,7 @@ Ref 提供 `actions`、`validate()`、`exportXml()`、`fitView()`、`setTheme()`
 
 ## 组合宿主头部与业务属性面板
 
-默认 `BpmnStudio` 是完整工作台。通过 `regions={{ right: 'hidden' }}` 隐藏 Nova Properties 后，Canvas 会获得该轨道的全部宽度；宿主属性面板应作为外部兄弟区域渲染。
+默认 `BpmnStudio` 是完整工作台。下面展示宿主拥有外部面板的接法：通过 `config.ui.regions.right = 'hidden'` 隐藏 Nova Properties，Canvas 获得该轨道的全部宽度。若希望复用 Nova 侧栏布局，使用下文的 `right` Render Prop，不必放到外部。
 
 ```jsx
 <BpmnStudio
@@ -79,14 +82,15 @@ Ref 提供 `actions`、`validate()`、`exportXml()`、`fitView()`、`setTheme()`
   engine="activiti"
   mode="design"
   allowedModes={['design']}
-  allowedNodeTypes={supportedNodeTypes}
-  allowedEdgeTypes={['sequenceFlow']}
-  regions={{ right: 'hidden' }}
+  config={{
+    modeling: { allowedNodeTypes: supportedNodeTypes, allowedEdgeTypes: ['sequenceFlow'] },
+    ui: { controlSize: 'medium', regions: { right: 'hidden' } },
+  }}
   theme="auto"
   headerStart={({ state, actions }) => (
     <HostProcessIdentity onBack={back} />
   )}
-  headerActions={({ actions, mode }) => (
+  headerActions={({ actions, mode, ui }) => (
     <HostWorkflowActions
       disabled={mode !== 'design'}
       onValidate={() => actions.validate()}
@@ -116,6 +120,52 @@ async function publishProcess(actions) {
 
 宿主属性面板以 `onSelectionChange` 为选择状态来源；它覆盖节点、连线、多选、清空与键盘选择。`onElementClick` 只是点击观察事件，不能代替选择状态。宿主通过稳定 BPMN Element ID 关联业务配置，并自行负责保存、发布、权限与服务端事务。
 
+`config` 收拢 `modeling/ui/viewer/export` 静态选项。顶部控件尺寸使用 `config.ui.controlSize`，默认 `medium`，支持 `small`、`medium`、`large` 和 `24px`–`48px`。Render Context 的只读 `ui.controlHeight` 可交给宿主按钮；Element Plus `default`、Ant Design `middle` 都映射到 Nova `medium`。自定义 px 时也可以在宿主 Header Actions CSS 中读取 `--nova-control-height` 等公开变量。
+
+```jsx
+<BpmnStudio
+  ref={studioRef}
+  config={{ ui: { controlSize: '36px' } }}
+  headerActions={({ actions, ui }) => (
+    <HostActions actions={actions} buttonHeight={ui.controlHeight} />
+  )}
+/>
+```
+
+Ref 同步提供 `getConfig()` / `setConfig()`；运行时更新 UI、Viewer 或 Export 不重建 Canvas。旧顶层配置继续兼容并标记 Deprecated，同项冲突时显式旧值优先。`config.modeling` 只在内部 Controller 创建时建立节点和连线约束。
+
+## 原生右侧内容与折叠
+
+`right` Render Prop 仅替换侧栏内容，保留 Nova 的布局与折叠按钮；它高于 Core `slots.right`，通过 Portal 保留宿主 Context。不要同时配置 `regions.right: 'hidden'`，否则自定义内容也隐藏。
+
+```jsx
+<BpmnStudio
+  ref={studioRef}
+  xml={xml}
+  config={{ ui: {
+    leftPanel: { collapsible: true, defaultCollapsed: false },
+    rightPanel: { collapsible: true, defaultCollapsed: false, layout: 'flex' },
+  } }}
+  onSidebarChange={(event) => console.log(event.side, event.collapsed, event.source)}
+  right={({ panelSelection, mode }) => (
+    <>
+      <header style={{ flex: 'none', padding: 12 }}>业务详情 · {mode}</header>
+      <div style={{ flex: 1, minHeight: 0, overflow: 'auto', padding: 12 }}>
+        {panelSelection.selectedElement?.id ?? '未选择元素'}
+        {/* 填入宿主表单 */}
+      </div>
+      <footer style={{ flex: 'none', padding: 12 }}>宿主固定操作区</footer>
+    </>
+  )}
+/>
+```
+
+默认 `flex` 由宿主安排内部滚动；`scroll` 由 Nova 滚动整个内容，宿主只填普通内容。父容器仍需可计算高度。收起不卸载内容、不丢失表单/滚动状态、不自动 Fit；左右按钮位于分隔线中点，支持键盘和尊重减少动态效果的 200ms 动画。Shell 容器 ≤720px 时首次默认收起，保留按钮，展开挤压画布而非抽屉，宽窄屏分别记忆状态。
+
+Ref 增加 `getSidebarState()`、`setSidebarCollapsed(side, collapsed)`、`subscribeSidebarChange()`、`getPanelSelection()`、`subscribePanelSelection()`；设置仅在实际切换时返回 `true`。Header/Right Render Context 共享响应式 `panelSelection`（`selection`、`selectedElement`、`trace`），只读轨迹选择不回写设计选择。
+
+Instance 默认隐藏右侧且没有展开按钮；需要时显式设置 `config.ui.regions.right: 'default'`。新增能力自 `0.3.5-preview` 提供。完整示例见[侧栏指南](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/CUSTOMIZATION.md#侧栏布局与平滑折叠)或包内 `llms-full.txt`。
+
 ## Mode 双向同步与副标题刷新
 
 ```jsx
@@ -152,6 +202,8 @@ Ref 的 `mode` Getter 与 `setMode()` 始终反映 Shell 实际状态。Resolver
 
 ## 只读展示与审批轨迹
 
+真实后端的数据格式与接入步骤见[审批轨迹接入指南](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/RUNTIME-INTEGRATION.md)，完整正文也包含在包内 `llms-full.txt`。React 根入口的 `ProcessInstanceSnapshot`、Activity/Action/Transition、`RuntimeTraceClickEvent` 与资源 Resolver 等 14 个 Runtime 类型出口自 `0.3.5-preview` 提供；旧版可按指南从 `BpmnStudioProps['runtime']` 推导，无需增加 Studio 直依赖。
+
 ```jsx
 import { BpmnViewer } from '@bpmn-nova/react'
 import '@bpmn-nova/react/styles.css'
@@ -282,6 +334,7 @@ studioRef.current?.openSvgExportPreview({
 - [完整项目能力](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)
+- [审批轨迹接入指南](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/RUNTIME-INTEGRATION.md)
 
 ## License
 

package/dist/index.d.ts

@@ -25,6 +25,7 @@ import type { ProcessInstanceSnapshot } from '@bpmn-nova/studio/runtime'
 import type { SvgExportArtifact, SvgExportOptions, SvgExportPreviewController } from '@bpmn-nova/studio/export-svg'
 import type {
   BpmnCanvas as CanvasInstance,
+  BpmnStudioConfig,
   BpmnStudioController,
   BpmnStudioShell,
   ContextMenuRegistry,
@@ -34,12 +35,17 @@ import type {
   StudioShellActions,
   StudioMode,
   StudioModeChangeEvent,
+  StudioPanelSelection,
+  StudioSidebarChangeEvent,
+  StudioSidebarSide,
+  StudioSidebarState,
   StudioValidationEvent,
   StudioValidationIssue,
   StudioShellOptions,
   StudioShellRegions,
   StudioShellSlots,
   StudioState,
+  StudioUiContext,
   TemplateRegistry,
 } from '@bpmn-nova/studio'
 import type { NovaThemeInput, NovaThemeState, RuntimeAppearanceOptions } from '@bpmn-nova/studio/theme'
@@ -83,13 +89,47 @@ export {
   registerFlowableProperties,
 } from '@bpmn-nova/studio'
 export type {
+  BpmnStudioConfig,
   NodeSubtitleResolver,
   NodeSubtitleResolverContext,
+  StudioControlSize,
+  StudioModelingConfig,
+  StudioPanelSelection,
+  StudioRightPanelConfig,
+  StudioSidebarChangeEvent,
+  StudioSidebarChangeSource,
+  StudioSidebarConfig,
+  StudioSidebarSide,
+  StudioSidebarState,
+  StudioSvgExportOptions,
+  StudioUiConfig,
+  StudioUiContext,
   StudioValidationEvent,
   StudioValidationIssue,
   StudioValidationSource,
+  StudioViewerConfig,
 } from '@bpmn-nova/studio'
 
+/** Runtime integration facade. Added in 0.3.5-preview; no runtime JavaScript exports. */
+export type {
+  ActivityInstance,
+  ActivityStatus,
+  ProcessInstanceSnapshot,
+  RuntimeApprovalAction,
+  RuntimeApprovalActionType,
+  RuntimeApprovalContent,
+  RuntimeApprovalContentBlock,
+  RuntimeAssetRef,
+  RuntimeEdgeVisit,
+  RuntimeParticipant,
+  RuntimeTransition,
+} from '@bpmn-nova/studio/runtime'
+export type {
+  RuntimeAssetPurpose,
+  RuntimeAssetResolver,
+  RuntimeTraceClickEvent,
+} from '@bpmn-nova/studio/viewer'
+
 export interface BpmnNovaVisualProps {
   theme?: NovaThemeInput
   runtimeAppearance?: RuntimeAppearanceOptions
@@ -104,8 +144,12 @@ export interface BpmnModelProps {
 }
 export interface UseBpmnStudioOptions extends BpmnModelProps {
   studio?: BpmnStudioController
+  config?: BpmnStudioConfig
+  /** @deprecated Use config.modeling.propertiesProfile. */
   propertiesProfile?: 'business' | 'developer'
+  /** @deprecated Use config.modeling.allowedNodeTypes. */
   allowedNodeTypes?: NodeType[]
+  /** @deprecated Use config.modeling.allowedEdgeTypes. */
   allowedEdgeTypes?: EdgeType[]
 }
 export interface UseBpmnStudioResult { studio: BpmnStudioController; state: StudioState; commands: StudioCommands }
@@ -152,8 +196,12 @@ export const BpmnPalettePanel: ForwardRefExoticComponent<BpmnPalettePanelProps &
 
 export interface BpmnStudioProps extends BpmnNovaVisualProps, BpmnModelProps {
   studio?: BpmnStudioController
+  config?: BpmnStudioConfig
+  /** @deprecated Use config.modeling.propertiesProfile. */
   propertiesProfile?: 'business' | 'developer'
+  /** @deprecated Use config.modeling.allowedNodeTypes. */
   allowedNodeTypes?: NodeType[]
+  /** @deprecated Use config.modeling.allowedEdgeTypes. */
   allowedEdgeTypes?: EdgeType[]
   iconRegistry?: IconRegistry
   paletteRegistry?: PaletteRegistry
@@ -165,25 +213,35 @@ export interface BpmnStudioProps extends BpmnNovaVisualProps, BpmnModelProps {
   nodeSubtitleResolver?: NodeSubtitleResolver
   slots?: StudioShellSlots
   layout?: StudioShellOptions['layout']
+  /** @deprecated Use config.ui.regions. */
   regions?: StudioShellRegions
   headerStart?: BpmnStudioRenderSlot
   headerActions?: BpmnStudioRenderSlot
   header?: BpmnStudioRenderSlot
+  right?: BpmnStudioRenderSlot
   runtime?: ProcessInstanceSnapshot | null
   mode?: StudioMode
   allowedModes?: readonly StudioMode[]
   projection?: ViewerProjection
+  /** @deprecated Use config.viewer.responsive. */
   responsive?: boolean
+  /** @deprecated Use config.viewer.projectionOptions. */
   projectionOptions?: Array<{ value: ViewerProjection; label: string }>
+  /** @deprecated Use config.ui.sidebarWidth.left. */
   leftWidth?: number
+  /** @deprecated Use config.ui.sidebarWidth.right. */
   rightWidth?: number
+  /** @deprecated Use config.viewer.timeline. */
   timeline?: ViewerOptions['timeline']
+  /** @deprecated Use config.viewer.runtimeDetails. */
   runtimeDetails?: ViewerOptions['runtimeDetails']
+  /** @deprecated Use config.viewer.runtimeTraceOptions. */
   runtimeTraceOptions?: ViewerOptions['runtimeTraceOptions']
   runtimePresenter?: ViewerOptions['runtimePresenter']
   runtimeTraceProjector?: ViewerOptions['runtimeTraceProjector']
   runtimeAssetResolver?: ViewerOptions['runtimeAssetResolver']
   runtimeTimelineRenderer?: RuntimeTimelineRenderer
+  /** @deprecated Use config.export. */
   svgExport?: ViewerOptions['svgExport']
   runtimeDetailsRenderer?: RuntimeDetailsRenderer | null
   runtimeTransitionDetailsRenderer?: RuntimeTransitionDetailsRenderer | null
@@ -197,6 +255,7 @@ export interface BpmnStudioProps extends BpmnNovaVisualProps, BpmnModelProps {
   onScopeChange?: (activeScopeId: string, scopePath: StudioState['scopePath'], state: StudioState) => void
   onModeChange?: (event: StudioModeChangeEvent) => void
   onValidation?: (event: StudioValidationEvent) => void
+  onSidebarChange?: (event: StudioSidebarChangeEvent) => void
 }
 export interface BpmnStudioRenderContext {
   readonly studio: BpmnStudioController
@@ -204,6 +263,8 @@ export interface BpmnStudioRenderContext {
   readonly actions: StudioShellActions
   readonly state: Readonly<StudioState>
   readonly mode: StudioMode
+  readonly ui: StudioUiContext
+  readonly panelSelection: StudioPanelSelection
 }
 export type BpmnStudioRenderSlot = ReactNode | ((context: BpmnStudioRenderContext) => ReactNode)
 export interface BpmnStudioHandle {
@@ -211,10 +272,17 @@ export interface BpmnStudioHandle {
   readonly shell: BpmnStudioShell | null
   readonly actions: StudioShellActions | null
   readonly mode: StudioMode | undefined
+  getConfig(): Readonly<BpmnStudioConfig> | undefined
+  setConfig(config?: BpmnStudioConfig): Readonly<BpmnStudioConfig> | undefined
   getMode(): StudioMode | undefined
   getAllowedModes(): readonly StudioMode[]
   setMode(mode: StudioMode): boolean
   setAllowedModes(modes: readonly StudioMode[]): readonly StudioMode[]
+  getSidebarState(): StudioSidebarState | undefined
+  setSidebarCollapsed(side: StudioSidebarSide, collapsed: boolean): boolean
+  subscribeSidebarChange(listener: (event: StudioSidebarChangeEvent) => void): () => void
+  getPanelSelection(): StudioPanelSelection | undefined
+  subscribePanelSelection(listener: (selection: StudioPanelSelection) => void): () => void
   refreshPresentation(): void
   validate(): StudioValidationIssue[]
   exportXml(engine?: EngineId): string

package/dist/index.js

@@ -51,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, allowedNodeTypes: options.allowedNodeTypes, allowedEdgeTypes: options.allowedEdgeTypes });
+  if (!options.studio && !ownedRef.current) ownedRef.current = createStudioController({ model: resolveModel(options), config: options.config, 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]);
@@ -111,12 +111,21 @@ export const BpmnStudio = forwardRef(function BpmnStudio(props, ref) {
   const [headerPortal, setHeaderPortal] = useState(null);
   const [headerStartPortal, setHeaderStartPortal] = useState(null);
   const [headerActionsPortal, setHeaderActionsPortal] = useState(null);
+  const [rightPortal, setRightPortal] = useState(null);
+  const nativeRightSlotRef = useRef(null);
+  if (!nativeRightSlotRef.current) nativeRightSlotRef.current = (context) => {
+    const portal = { target: context.container, context };
+    setRightPortal(portal);
+    return () => setRightPortal((current) => current === portal ? null : current);
+  };
   const callbacksRef = useRef({});
   callbacksRef.current = props;
-  if (!props.studio && !ownedStudioRef.current) ownedStudioRef.current = createStudioController({ model: resolveModel(props), propertiesProfile: props.propertiesProfile, allowedNodeTypes: props.allowedNodeTypes, allowedEdgeTypes: props.allowedEdgeTypes });
+  if (!props.studio && !ownedStudioRef.current) ownedStudioRef.current = createStudioController({ model: resolveModel(props), config: props.config, 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 [actualUi, setActualUi] = useState(() => Object.freeze({ controlSize: 'medium', controlHeight: '32px' }));
+  const [panelSelection, setPanelSelection] = useState(() => Object.freeze({ selection: studio.selection, selectedElement: studio.getSelectedElement(), trace: null }));
   const subtitleResolverRef = useRef(props.nodeSubtitleResolver);
   subtitleResolverRef.current = props.nodeSubtitleResolver;
   const stableSubtitleResolverRef = useRef((context) => subtitleResolverRef.current?.(context));
@@ -124,11 +133,22 @@ export const BpmnStudio = forwardRef(function BpmnStudio(props, ref) {
     studio,
     get shell() { return shellRef.current; },
     get actions() { return shellRef.current?.actions || null; },
+    getConfig: () => shellRef.current?.getConfig(),
+    setConfig: (config) => {
+      const result = shellRef.current?.setConfig(config);
+      if (shellRef.current) setActualUi(Object.freeze({ ...shellRef.current.ui }));
+      return result;
+    },
     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) || [],
+    getSidebarState: () => shellRef.current?.getSidebarState(),
+    setSidebarCollapsed: (side, collapsed) => shellRef.current?.setSidebarCollapsed(side, collapsed) || false,
+    subscribeSidebarChange: (listener) => shellRef.current?.subscribeSidebarChange(listener) || (() => {}),
+    getPanelSelection: () => shellRef.current?.getPanelSelection(),
+    subscribePanelSelection: (listener) => shellRef.current?.subscribePanelSelection(listener) || (() => {}),
     refreshPresentation: () => shellRef.current?.refreshPresentation(),
     validate: () => shellRef.current?.validate() || [],
     exportXml: (engine) => studio.exportXml(engine),
@@ -140,6 +160,7 @@ export const BpmnStudio = forwardRef(function BpmnStudio(props, ref) {
   const hasNativeHeader = props.header !== undefined && props.header !== null;
   const hasNativeHeaderStart = props.headerStart !== undefined && props.headerStart !== null;
   const hasNativeHeaderActions = props.headerActions !== undefined && props.headerActions !== null;
+  const hasNativeRight = props.right !== undefined && props.right !== null;
   useEffect(() => {
     if (!hostRef.current) return undefined;
     setStudioState(studio.getState());
@@ -154,9 +175,11 @@ export const BpmnStudio = forwardRef(function BpmnStudio(props, ref) {
       if (hasNativeHeaderStart) shellSlots.headerStart = createPortalSlot(setHeaderStartPortal);
       if (hasNativeHeaderActions) shellSlots.headerActions = createPortalSlot(setHeaderActionsPortal);
     }
+    if (hasNativeRight) shellSlots.right = nativeRightSlotRef.current;
     const shell = new CoreStudioShell({
       container: hostRef.current,
       studio,
+      config: props.config,
       iconRegistry: props.iconRegistry,
       paletteRegistry: props.paletteRegistry,
       propertiesRegistry: props.propertiesRegistry,
@@ -192,6 +215,9 @@ export const BpmnStudio = forwardRef(function BpmnStudio(props, ref) {
       projectionOptions: props.projectionOptions,
       leftWidth: props.leftWidth,
       rightWidth: props.rightWidth,
+      timeline: props.timeline,
+      runtimeDetails: props.runtimeDetails,
+      runtimeTraceOptions: props.runtimeTraceOptions,
       theme: props.theme,
       runtimeAppearance: props.runtimeAppearance,
       svgExport: props.svgExport,
@@ -199,19 +225,28 @@ export const BpmnStudio = forwardRef(function BpmnStudio(props, ref) {
     });
     shellRef.current = shell;
     setActualMode(shell.getMode());
+    setActualUi(Object.freeze({ ...shell.ui }));
     const offMode = shell.subscribeMode((event) => {
       setActualMode(event.mode);
       callbacksRef.current.onModeChange?.(event);
     });
     const offValidation = shell.subscribeValidation((event) => callbacksRef.current.onValidation?.(event));
+    setPanelSelection(shell.getPanelSelection());
+    const offPanelSelection = shell.subscribePanelSelection(setPanelSelection);
+    const offSidebar = shell.subscribeSidebarChange((event) => callbacksRef.current.onSidebarChange?.(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 () => { offMode(); offValidation(); off(); shell.destroy(); shellRef.current = null; };
+    return () => { offMode(); offValidation(); offPanelSelection(); offSidebar(); off(); shell.destroy(); shellRef.current = null; };
   }, [studio, hasNativeHeader, hasNativeHeaderStart, hasNativeHeaderActions]);
+  // The content render function may change each render; only slot ownership
+  // changes replace the right mount. Neither case reconstructs the Shell.
+  useEffect(() => {
+    shellRef.current?._setRightSlot(hasNativeRight ? nativeRightSlotRef.current : props.slots?.right);
+  }, [studio, hasNativeRight, props.slots?.right, hasNativeHeader, hasNativeHeaderStart, hasNativeHeaderActions]);
   useEffect(() => () => {
     if (!props.studio && ownedStudioRef.current === studio) {
       studio.destroy();
@@ -234,6 +269,12 @@ export const BpmnStudio = forwardRef(function BpmnStudio(props, ref) {
     if (props.mode) shell.setMode(props.mode);
   }, [props.allowedModes, props.mode]);
   useEffect(() => { if (props.projection) shellRef.current?.setProjection(props.projection); }, [props.projection]);
+  useEffect(() => {
+    const shell = shellRef.current;
+    if (!shell) return;
+    shell.setConfig(props.config);
+    setActualUi(Object.freeze({ ...shell.ui }));
+  }, [props.config]);
   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]);
@@ -241,6 +282,7 @@ export const BpmnStudio = forwardRef(function BpmnStudio(props, ref) {
   useEffect(() => {
     const shell = shellRef.current;
     if (!shell) return;
+    if (props.timeline === undefined && props.runtimeDetails === undefined && props.runtimeTraceOptions === undefined) return;
     shell.rendererOptions.timeline = props.timeline;
     shell.rendererOptions.runtimeDetails = props.runtimeDetails;
     shell.rendererOptions.runtimeTraceOptions = props.runtimeTraceOptions;
@@ -254,6 +296,8 @@ export const BpmnStudio = forwardRef(function BpmnStudio(props, ref) {
       actions: portal.context.actions,
       state: studioState,
       mode: actualMode,
+      ui: actualUi,
+      panelSelection,
     };
     return createPortal(typeof slot === 'function' ? slot(context) : slot, portal.target, key);
   };
@@ -262,6 +306,7 @@ export const BpmnStudio = forwardRef(function BpmnStudio(props, ref) {
     renderSlot(props.header, headerPortal, 'bpmn-nova-header'),
     renderSlot(props.headerStart, headerStartPortal, 'bpmn-nova-header-start'),
     renderSlot(props.headerActions, headerActionsPortal, 'bpmn-nova-header-actions'),
+    renderSlot(props.right, rightPortal, 'bpmn-nova-right'),
   );
 });
 

package/dist/styles.css

@@ -536,6 +536,14 @@
 
 /* Gateways */
 .mb-node-gateway { display: grid; place-items: center; z-index: 7; }
+.mb-node .mb-node-scaled-shape {
+  position: absolute;
+  left: 50%;
+  top: 50%;
+  box-sizing: border-box;
+  transform: translate(-50%, -50%) rotate(var(--mb-node-shape-rotation, 0rad)) scale(var(--mb-node-shape-scale, 1));
+  transform-origin: center;
+}
 .mb-gateway-shape {
   width: 49px;
   height: 49px;
@@ -699,6 +707,8 @@
 .mb-port-right:hover { transform: translateY(-50%) scale(1.2); }
 .mb-port-top:hover,
 .mb-port-bottom:hover { transform: translateX(-50%) scale(1.2); }
+.mb-port.mb-port-geometry { transform: translate(-50%, -50%); }
+.mb-port.mb-port-geometry:hover { transform: translate(-50%, -50%) scale(1.2); }
 .mb-node.is-connecting-source .mb-port-right { opacity: 1; border-color: var(--mb-primary); background: var(--mb-primary); box-shadow: 0 0 0 4px color-mix(in srgb, var(--nova-color-primary) 12%, transparent); }
 .mb-port-target {
   width: 12px;
@@ -1140,7 +1150,7 @@ textarea.property-control { resize: vertical; }
 .property-branch-target small { color: var(--nova-color-text-muted); font-size: var(--nova-font-size-xs, 10px); line-height: 14px; }.property-branch-target strong { overflow: hidden; color: var(--nova-color-text-secondary); font-size: var(--nova-font-size-sm, 12px); line-height: 18px; font-weight: var(--nova-font-weight-semibold, 600); text-overflow: ellipsis; white-space: nowrap; }.property-branch-target > span { color: var(--nova-color-primary); font-size: var(--nova-font-size-sm, 12px); }
 
 /* @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 { --nova-left-width: 244px; --nova-right-width: 360px; --nova-control-height: 32px; --nova-header-height: 58px; --nova-control-font-size: 12px; --nova-control-padding-inline: 10px; --nova-mode-control-padding-inline: 12px; --nova-control-icon-size: 14px; --nova-control-radius: 7px; --nova-mode-control-height: 36px; --nova-mode-button-height: 28px; --nova-projection-button-height: 26px; --nova-icon-button-size: 31px; --nova-split-caret-width: 27px; --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: var(--nova-header-height) 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; }
@@ -1150,20 +1160,22 @@ textarea.property-control { resize: vertical; }
 .nova-studio-brand-copy strong { color: var(--nova-tone-primary-foreground, #3443b8); font-size: var(--nova-font-size-md); line-height: 20px; font-weight: var(--nova-font-weight-bold); letter-spacing: -.01em; }
 .nova-studio-brand-copy span { max-width: 180px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--nova-color-text-muted, #7c8799); font-size: var(--nova-font-size-xs); line-height: 14px; }
 .nova-studio-center-controls { min-width: 0; justify-self: center; display: flex; align-items: center; gap: 8px; }
-.nova-studio-mode-switch { height: 36px; border: 1px solid var(--nova-color-divider, #e6e8ef); border-radius: 10px; padding: 3px; display: flex; align-items: center; gap: 2px; background: var(--nova-color-surface-muted, #f4f5f8); box-shadow: inset 0 1px 2px rgba(35,43,68,.03); }
-.nova-studio-mode-switch button { height: 28px; border: 0; border-radius: 7px; padding: 0 12px; display: flex; align-items: center; gap: 5px; color: var(--nova-color-text-muted, #8a93a4); background: transparent; font-size: var(--nova-font-size-sm); line-height: 18px; white-space: nowrap; cursor: pointer; }
+.nova-studio-mode-switch { height: var(--nova-mode-control-height); border: 1px solid var(--nova-color-divider, #e6e8ef); border-radius: calc(var(--nova-control-radius) + 3px); padding: 3px; display: flex; align-items: center; gap: 2px; background: var(--nova-color-surface-muted, #f4f5f8); box-shadow: inset 0 1px 2px rgba(35,43,68,.03); }
+.nova-studio-mode-switch button { height: var(--nova-mode-button-height); border: 0; border-radius: var(--nova-control-radius); padding: 0 var(--nova-mode-control-padding-inline); display: flex; align-items: center; gap: 5px; color: var(--nova-color-text-muted, #8a93a4); background: transparent; font-size: var(--nova-control-font-size); line-height: 18px; white-space: nowrap; cursor: pointer; }
 .nova-studio-mode-switch button.is-active { color: var(--nova-tone-primary-foreground, #4f5dd1); background: var(--nova-color-surface, #fff); font-weight: var(--nova-font-weight-semibold); box-shadow: var(--nova-shadow-sm); }
-.nova-studio-projection-switch { height: 32px; border: 1px solid var(--nova-color-border, #e2e6ef); border-radius: 8px; padding: 2px; display: flex; align-items: center; gap: 2px; background: var(--nova-color-surface, #fff); }
+.nova-studio-projection-switch { height: var(--nova-control-height); border: 1px solid var(--nova-color-border, #e2e6ef); border-radius: calc(var(--nova-control-radius) + 1px); padding: 2px; display: flex; align-items: center; gap: 2px; background: var(--nova-color-surface, #fff); }
 .nova-studio-projection-switch.is-hidden { display: none; }
-.nova-studio-projection-switch button { height: 26px; border: 0; border-radius: 6px; padding: 0 9px; color: var(--nova-color-text-muted, #7c8799); background: transparent; font-size: var(--nova-font-size-sm); line-height: 18px; white-space: nowrap; cursor: pointer; }
+.nova-studio-projection-switch button { height: var(--nova-projection-button-height); border: 0; border-radius: max(0px, calc(var(--nova-control-radius) - 1px)); padding: 0 max(0px, calc(var(--nova-control-padding-inline) - 1px)); color: var(--nova-color-text-muted, #7c8799); background: transparent; font-size: var(--nova-control-font-size); line-height: 18px; white-space: nowrap; cursor: pointer; }
 .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-header-actions { min-width: 0; min-height: var(--nova-control-height); display: flex; align-items: center; justify-content: flex-end; gap: 5px; }
+.nova-studio-header .nova-icon { width: var(--nova-control-icon-size); height: var(--nova-control-icon-size); }
+.nova-studio-header .nova-icon.nova-icon-xs { width: max(12px, calc(var(--nova-control-icon-size) - 2px)); height: max(12px, calc(var(--nova-control-icon-size) - 2px)); }
+.nova-studio-tool-divider { flex: none; width: 1px; height: calc(var(--nova-control-height) - 12px); margin: 0 2px; background: var(--nova-color-divider, #e4e8f0); }
+.nova-studio-tool { flex: none; height: var(--nova-control-height); min-height: var(--nova-control-height); border: 1px solid var(--nova-color-border, #e2e6ef); border-radius: var(--nova-control-radius); padding: 0 var(--nova-control-padding-inline); 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-control-font-size); 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; }
-.nova-studio-tool.is-icon { width: 31px; padding: 0; font-size: 14px; }
+.nova-studio-tool.is-icon { width: var(--nova-icon-button-size); padding: 0; font-size: calc(var(--nova-control-font-size) + 2px); }
 .nova-studio-tool:hover, .nova-studio-tool.is-active { border-color: var(--nova-tone-primary-border, #bec6ff); color: var(--nova-tone-primary-foreground, #3948c5); background: var(--nova-color-primary-soft, #f2f4ff); }
 .nova-studio-tool.is-magic { border-color: var(--nova-tone-primary-border, #d9ddff); color: var(--nova-tone-primary-foreground, #4654c8); background: var(--nova-color-primary-soft, #f4f5ff); font-weight: var(--nova-font-weight-semibold); }
 .nova-studio-tool.is-primary { border-color: var(--nova-color-primary); color: var(--nova-color-text-inverse, #fff); background: var(--nova-color-primary, #5361d6); }
@@ -1182,8 +1194,8 @@ textarea.property-control { resize: vertical; }
 .nova-studio-export-option.is-hidden { display: none; }
 .nova-studio-import-input { display: none; }
 .nova-studio-beautify-split { position: relative; flex: none; display: flex; }
-.nova-studio-beautify-split .nova-studio-beautify { border-radius: 7px 0 0 7px; }
-.nova-studio-beautify-split .nova-studio-beautify-caret { width: 27px; border-left: 0; border-radius: 0 7px 7px 0; padding: 0; }
+.nova-studio-beautify-split .nova-studio-beautify { border-radius: var(--nova-control-radius) 0 0 var(--nova-control-radius); }
+.nova-studio-beautify-split .nova-studio-beautify-caret { width: var(--nova-split-caret-width); border-left: 0; border-radius: 0 var(--nova-control-radius) var(--nova-control-radius) 0; padding: 0; }
 .nova-studio-beautify-menu { position: absolute; z-index: 30; top: calc(100% + 8px); right: 0; width: 224px; border: 1px solid var(--nova-color-border, #e5e7ee); border-radius: 12px; padding: 12px; color: var(--nova-color-text-secondary, #3d4659); background: var(--nova-color-surface, #fff); box-shadow: var(--nova-shadow-lg); }
 .nova-studio-beautify-menu.is-hidden, .nova-studio-canvas-floating-head.is-hidden, .is-hidden-by-mode { display: none !important; }
 .nova-studio-beautify-title { margin-bottom: 9px; font-size: 12px; font-weight: 700; line-height: 18px; }
@@ -1429,7 +1441,7 @@ textarea.property-control { resize: vertical; }
   .nova-studio-brand-copy span { display: none; }
 }
 @media (max-width: 720px) {
-  .nova-studio-shell { grid-template-rows: 54px minmax(0,1fr); }
+  .nova-studio-shell { grid-template-rows: var(--nova-header-height) 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; }
@@ -1442,3 +1454,51 @@ textarea.property-control { resize: vertical; }
   .nova-studio-body.is-timeline .nova-studio-statusbar { display: none; }
 }
 
+/* The managed Shell keeps three tracks, including zero-width collapsed tracks.
+   Legacy base layout above remains usable without the sidebar controller. */
+.nova-studio-shell .nova-studio-body.is-managed-sidebars {
+  position: relative;
+  grid-template-columns: var(--nova-sidebar-left-track, 0px) minmax(0, 1fr) var(--nova-sidebar-right-track, 0px);
+}
+.nova-studio-body.is-managed-sidebars.is-sidebar-animated {
+  transition: grid-template-columns 200ms cubic-bezier(0.2, 0, 0, 1);
+}
+.nova-studio-shell .is-managed-sidebars > .nova-studio-left, .nova-studio-shell .is-managed-sidebars > .nova-studio-right {
+  display: block; min-width: 0; min-height: 0; overflow: hidden; border: 0;
+}
+.is-managed-sidebars > .nova-studio-left { grid-column: 1; grid-row: 1; }
+.is-managed-sidebars > .nova-studio-canvas-column { grid-column: 2; grid-row: 1; }
+.is-managed-sidebars > .nova-studio-right { grid-column: 3; grid-row: 1; }
+.nova-studio-sidebar-content {
+  box-sizing: border-box; height: 100%; min-width: 0; min-height: 0;
+  scrollbar-width: thin; scrollbar-color: var(--nova-color-border-strong, #d9dee7) transparent;
+}
+.nova-studio-left-content { overflow-x: hidden; overflow-y: auto; overscroll-behavior: contain; border-right: 1px solid var(--nova-color-divider); }
+.nova-studio-right-content { border-left: 1px solid var(--nova-color-divider); }
+.nova-studio-right-content[data-layout="flex"] { display: flex; flex-direction: column; min-height: 0; overflow: hidden; }
+.nova-studio-right-content[data-layout="scroll"] { display: block; overflow-y: auto; overflow-x: hidden; overscroll-behavior: contain; }
+.nova-studio-right-content[data-layout="flex"].nova-properties > .properties-head { flex: none; position: relative; }
+.nova-studio-right-content[data-layout="flex"].nova-properties > .properties-body { flex: 1; min-height: 0; overflow: auto; overscroll-behavior: contain; }
+.nova-studio-right-content[data-layout="scroll"].nova-properties > .properties-head { position: relative; }
+.nova-studio-right-content[data-layout="flex"] > .nova-studio-readonly-panel { display: flex; flex-direction: column; flex: 1; min-height: 0; }
+.nova-studio-right-content[data-layout="flex"] .nova-studio-readonly-header { flex: none; }
+.nova-studio-right-content[data-layout="flex"] .nova-studio-readonly-body { flex: 1; min-height: 0; overflow: auto; align-content: start; overscroll-behavior: contain; }
+.nova-studio-sidebar-content::-webkit-scrollbar, .nova-studio-right-content .properties-body::-webkit-scrollbar, .nova-studio-readonly-body::-webkit-scrollbar { width: 4px; height: 4px; }
+.nova-studio-sidebar-content::-webkit-scrollbar-thumb, .nova-studio-right-content .properties-body::-webkit-scrollbar-thumb, .nova-studio-readonly-body::-webkit-scrollbar-thumb { border-radius: 999px; background: var(--nova-color-border-strong, #d9dee7); }
+.nova-studio-sidebar-toggle {
+  position: absolute; z-index: 8; top: 50%; transform: translateY(-50%);
+  box-sizing: border-box; width: 22px; height: 44px; padding: 0;
+  display: grid; place-items: center; border: 1px solid var(--nova-color-border);
+  border-radius: 7px; background: var(--nova-color-surface); color: var(--nova-color-text-muted);
+  box-shadow: var(--nova-shadow-sm); font: 22px/1 sans-serif; cursor: pointer;
+}
+.nova-studio-sidebar-toggle[hidden] { display: none; }
+.nova-studio-sidebar-toggle.is-left { left: max(0px, calc(var(--nova-sidebar-left-track, 0px) - 11px)); }
+.nova-studio-sidebar-toggle.is-right { right: max(0px, calc(var(--nova-sidebar-right-track, 0px) - 11px)); }
+.is-sidebar-animated > .nova-studio-sidebar-toggle { transition: left 200ms cubic-bezier(0.2, 0, 0, 1), right 200ms cubic-bezier(0.2, 0, 0, 1); }
+.nova-studio-sidebar-toggle:hover { color: var(--nova-color-primary); background: var(--nova-color-primary-soft); }
+.nova-studio-sidebar-toggle:focus-visible { outline: 2px solid var(--nova-color-focus-ring); outline-offset: 2px; }
+@media (prefers-reduced-motion: reduce) {
+  .nova-studio-body.is-managed-sidebars.is-sidebar-animated, .is-sidebar-animated > .nova-studio-sidebar-toggle { transition: none; }
+}
+