@bpmn-nova/react 0.3.4-preview → 0.3.6-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.6-preview`。React 与 React DOM 由宿主工程提供，本包不会替应用选择或升级框架版本。
 
 ![BPMN Nova React 流程工作台](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-designer.jpg)
 
@@ -14,35 +14,19 @@ BPMN Nova 的 React 18+ Adapter，提供 Studio、Designer、Viewer、审批轨
 npm install @bpmn-nova/react@preview
 ```
 
-```jsx
-import '@bpmn-nova/react/styles.css'
-```
+只安装本包；匹配版本的 `@bpmn-nova/studio` 会作为依赖自动解析。公共 TypeScript 类型直接从 `@bpmn-nova/react` 导入，不需要为类型额外添加 Studio 直依赖。
 
-只安装本包；`@bpmn-nova/studio` 会作为内部依赖自动解析。容器必须有明确高度。
+CSS 必须显式导入 `@bpmn-nova/react/styles.css`；视觉容器及其父级需要具有可计算高度。
 
-TypeScript 类型也从 React 入口导入，不要为了模型类型额外声明 Studio 直依赖：
-
-```ts
-import type {
-  BpmnNode,
-  EdgeType,
-  ElementSelection,
-  NodeType,
-  ProcessModel,
-} from '@bpmn-nova/react'
-```
-
-公共类型门面还包含 `BpmnEdge`、`EngineId` 和 `LayoutOptions`。
-
-使用代码生成助手或 IDE Agent 接入时，从随包的 `llms.txt` 开始；需要完整接口和定制资料时再读取 `llms-full.txt`。两份文件都包含在 npm tarball 中，不依赖源码仓库可见性。
-
-## 流程设计
+## 最小用法
 
 ```jsx
 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 +36,7 @@ export function WorkflowEditor({ initialXml }) {
         ref={studioRef}
         xml={initialXml}
         engine="flowable"
+        config={STUDIO_CONFIG}
         mode="design"
         allowedModes={['design']}
         theme="auto"
@@ -64,224 +49,17 @@ export function WorkflowEditor({ initialXml }) {
 }
 ```
 
-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。
-
-## 只读展示与审批轨迹
-
-```jsx
-import { BpmnViewer } from '@bpmn-nova/react'
-import '@bpmn-nova/react/styles.css'
-
-export function ApprovalTrace({ xml, runtime, resolveAsset }) {
-  return (
-    <div style={{ height: 720 }}>
-      <BpmnViewer
-        xml={xml}
-        engine="flowable"
-        runtime={runtime}
-        projection="compact"
-        responsive
-        theme="auto"
-        runtimeAssetResolver={resolveAsset}
-        onTraceClick={(event) => console.log(event)}
-      />
-    </div>
-  )
-}
-```
-
-- `approval`：实际发生的有效路径。
-- `compact`：移动时间线、审批动作、图片和附件。
-- `standard`：完整 BPMN 叠加运行状态。
-
-![BPMN Nova React 移动审批时间线](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-approval-mobile-timeline.jpg)
-
-## Runtime Action 与附件
-
-```js
-const runtime = {
-  processInstanceId: 'purchase-20260824',
-  status: 'running',
-  activities: [{
-    id: 'activity-manager-1',
-    elementId: 'UserTask_Manager',
-    visitId: 'visit-manager-1',
-    status: 'completed',
-    assignee: '李经理',
-  }],
-  actions: [{
-    id: 'approve-manager-1',
-    type: 'approve',
-    elementId: 'UserTask_Manager',
-    visitId: 'visit-manager-1',
-    occurredAt: '2026-08-24T10:12:00+08:00',
-    actor: { id: 'manager-li', name: '李经理' },
-    content: {
-      plainText: '资料完整，同意提交总经理审批。',
-      blocks: [{ type: 'file', assetId: 'purchase-checklist' }],
-      assets: [{
-        id: 'purchase-checklist',
-        name: '采购核验清单.txt',
-        mediaType: 'text/plain',
-        size: 248,
-      }],
-    },
-  }],
-  visitedEdges: [],
-}
-
-const resolveAsset = async (asset, { purpose, signal }) => {
-  const response = await fetch(
-    `/api/runtime-assets/${encodeURIComponent(asset.id)}?purpose=${purpose}`,
-    { signal },
-  )
-  return response.ok ? response.url : null
-}
-```
-
-Runtime Snapshot 只保存资源引用；上传、存储和权限签发由宿主负责。
-
-## 主题和 SVG 导出
-
-```jsx
-<BpmnStudio
-  ref={studioRef}
-  xml={xml}
-  theme={{
-    mode: 'auto',
-    dark: {
-      colors: {
-        canvas: '#0b1018',
-        surface: '#18202b',
-      },
-    },
-  }}
-/>
-```
-
-```js
-studioRef.current?.openSvgExportPreview({
-  theme: 'current',
-  filename: '采购申请审批流程.svg',
-})
-```
-
-主题属性变化会更新现有实例，不会重新挂载画布、清除选择或关闭详情。
-
-## Properties 与自定义 Renderer
-
-本包还导出：
-
-- `BpmnDesigner`、`BpmnCanvas`、`BpmnPalettePanel`、`BpmnPropertiesPanel`
-- `useBpmnStudio`
-- `createReactPropertyComponent`
-- `createReactRuntimeDetailsComponent`
-- `createReactRuntimeTransitionDetailsComponent`
-- `createReactRuntimeTimelineComponent`
-- `createStudioController`、`createEmptyProcess`、`importBpmn`、`exportBpmn`
-- Palette、Properties、Context Menu、Icon 和 Template Registry 的公开创建函数
-
-完整工作台可通过 `allowedNodeTypes` 与 `allowedEdgeTypes` 限制宿主支持的图元类型，通过 `allowedModes` 限制可切换的工作台模式。图元限制同时作用于 XML 导入、Palette、连接、快捷新增、模板和节点类型转换。
-
-## 常见问题
+`initialXml` 由宿主提供。组件负责实例生命周期；SSR 应用只在客户端挂载。`xml` / `model` 用于外部替换输入，事件中的 XML 是草稿输出。
 
-- **无高度：** 为外层容器设置明确高度。
-- **无样式：** 导入一次 `@bpmn-nova/react/styles.css`。
-- **Hooks/React 重复：** React 与 React DOM 应由宿主提供并保持单实例。
-- **SSR：** 将可视组件放到客户端挂载阶段。
-- **包选择：** React 项目只直接安装 `@bpmn-nova/react`。
+## 完整文档
 
-## 文档与 AI
+- [官网与文档](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/index.md)
+- [React 接入、宿主组合和完整示例](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/guide/react.md)
+- [组件参数与事件](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/components/index.md)、[公开 API](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/api/index.md)
+- [审批轨迹接入](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/guide/runtime.md)、[自定义扩展](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/customization/index.md)
+- [更新日志](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/changelog.md)
 
-- 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 接入从随包的 `llms.txt` 开始；`llms-full.txt` 提供完整离线上下文，两份文件都包含在 npm tarball 中。
 
 ## 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,58 @@ 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. Types since 0.3.5-preview; inspectRuntime / formatRuntimeInstant since 0.3.6-preview. */
+export type {
+  ActivityInstance,
+  ActivityStatus,
+  ActivityVisitState,
+  ProcessInstanceSnapshot,
+  RuntimeApprovalAction,
+  RuntimeApprovalActionType,
+  RuntimeApprovalContent,
+  RuntimeApprovalContentBlock,
+  RuntimeAssetRef,
+  RuntimeDiagnostic,
+  RuntimeEdgeVisit,
+  RuntimeInstant,
+  RuntimeParticipant,
+  RuntimeTransition,
+} from '@bpmn-nova/studio/runtime'
+export {
+  activityState,
+  createRuntimePresentation,
+  formatRuntimeInstant,
+  inspectRuntime,
+  normalizeRuntime,
+  parseRuntimeInstant,
+} from '@bpmn-nova/studio/runtime'
+export type {
+  RuntimeAssetPurpose,
+  RuntimeAssetResolver,
+  RuntimeTraceClickEvent,
+} from '@bpmn-nova/studio/viewer'
+
 export interface BpmnNovaVisualProps {
   theme?: NovaThemeInput
   runtimeAppearance?: RuntimeAppearanceOptions
@@ -104,8 +155,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 +207,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 +224,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 +266,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 +274,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 +283,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

@@ -7,6 +7,15 @@ 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 {
+  activityState,
+  createRuntimePresentation,
+  formatRuntimeInstant,
+  inspectRuntime,
+  normalizeRuntime,
+  parseRuntimeInstant,
+} from '@bpmn-nova/studio/runtime';
+
 export {
   createContextMenuRegistry,
   createDefaultContextMenuRegistry,
@@ -51,7 +60,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 +120,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 +142,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 +169,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 +184,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 +224,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 +234,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 +278,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 +291,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 +305,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 +315,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'),
   );
 });