@bpmn-nova/react 0.3.4-preview → 0.3.5-preview

package/llms-full.txt

@@ -75,6 +75,8 @@ Use `engine="flowable"` or `engine="activiti"` explicitly from the host workflow
 
 Studio modes are presentation state: `design` means editable process design, `viewer` means read-only process viewing, and `instance` means approval trace. Observe the actual Shell state through `subscribeMode()` or framework mode events; never store it in the BPMN model.
 
+Node geometry is also presentation, not DI normalization. Loading server XML via the component parses its BPMN DI Bounds; XML export already writes model dimensions. The `0.3.5-preview` gateway/data fix scales standard shells to fit those bounds and docks display endpoints without rewriting model geometry or waypoints. Do not resize stored nodes, recreate them, or patch internal CSS to compensate. See [Node DI and visual geometry](docs/API.md#节点-di-与视觉尺寸) and the customization section in the co-located `llms-full.txt`; `node-geometry` is internal, not another installable package.
+
 ## 4. Mount a minimal integration
 
 Every branch must import its own public `styles.css` exactly once and provide a height through the complete parent layout chain.
@@ -90,6 +92,10 @@ import '@bpmn-nova/vue/styles.css'
 const props = defineProps({ initialXml: String })
 const emit = defineEmits(['change'])
 const studioRef = ref(null)
+const config = {
+  modeling: { allowedEdgeTypes: ['sequenceFlow'] },
+  ui: { controlSize: 'medium' },
+}
 
 function handleChange(model, reason, xml) {
   emit('change', xml)
@@ -102,8 +108,8 @@ function handleChange(model, reason, xml) {
       ref="studioRef"
       :xml="props.initialXml"
       engine="flowable"
+      :config="config"
       mode="design"
-      :allowed-edge-types="['sequenceFlow']"
       :allowed-modes="['design', 'viewer']"
       theme="auto"
       @change="handleChange"
@@ -119,6 +125,11 @@ import { useRef } from 'react'
 import { BpmnStudio } from '@bpmn-nova/react'
 import '@bpmn-nova/react/styles.css'
 
+const STUDIO_CONFIG = {
+  modeling: { allowedEdgeTypes: ['sequenceFlow'] },
+  ui: { controlSize: 'medium' },
+}
+
 export function WorkflowEditor({ initialXml, saveDraft }) {
   const studioRef = useRef(null)
   return (
@@ -127,8 +138,8 @@ export function WorkflowEditor({ initialXml, saveDraft }) {
         ref={studioRef}
         xml={initialXml}
         engine="flowable"
+        config={STUDIO_CONFIG}
         mode="design"
-        allowedEdgeTypes={['sequenceFlow']}
         allowedModes={['design', 'viewer']}
         theme="auto"
         onChange={(model, reason, xml) => saveDraft(xml)}
@@ -148,13 +159,19 @@ import {
 } from '@bpmn-nova/studio'
 import '@bpmn-nova/studio/styles.css'
 
+const config = {
+  modeling: { allowedEdgeTypes: ['sequenceFlow'] },
+  ui: { controlSize: 'medium' },
+}
+
 const studio = createStudioController({
   model: createEmptyProcess('flowable'),
-  allowedEdgeTypes: ['sequenceFlow'],
+  config,
 })
 const shell = createStudioShell({
   container: document.querySelector('#workflow-studio'),
   studio,
+  config,
   mode: 'design',
   allowedModes: ['design', 'viewer'],
   theme: 'auto',
@@ -177,18 +194,16 @@ This step is complete when the workbench is visible, the initial XML is rendered
 
 ### 4.1 Embed the complete Studio in an existing business workbench
 
-`BpmnStudio` is a complete Header + Palette + Canvas + Properties + Statusbar workbench by default. Preserve that default unless the host already owns a region. To keep the Nova Palette and editing tools, replace only the Header start area and explicitly hide Nova Properties:
+`BpmnStudio` is a complete Header + Palette + Canvas + Properties + Statusbar workbench by default. Preserve that default unless the host already owns a region. Define a stable `studioConfig` object in host code. To keep the Nova Palette and editing tools, replace only the Header start area and explicitly hide Nova Properties:
 
 ```vue
 <BpmnStudio
   ref="studioRef"
   :xml="xml"
   engine="activiti"
+  :config="studioConfig"
   mode="design"
   :allowed-modes="['design']"
-  :allowed-node-types="supportedNodeTypes"
-  :allowed-edge-types="['sequenceFlow']"
-  :regions="{ right: 'hidden' }"
   theme="auto"
   @change="handleChange"
   @selection-change="handleSelectionChange"
@@ -196,23 +211,43 @@ This step is complete when the workbench is visible, the initial XML is rendered
   <template #header-start="{ state, actions }">
     <!-- Host back action, business icon, process name, and type -->
   </template>
-  <template #header-actions="{ actions, mode }">
+  <template #header-actions="{ actions, mode, ui }">
     <!-- Host Validate / Save / Publish actions. Validation calls actions.validate(). -->
   </template>
 </BpmnStudio>
 ```
 
-- Vue uses native `#header-start` / `#header-actions` / `#header` slots. React uses `headerStart` / `headerActions` / `header` render props. Core uses matching DOM Slots.
+- Vue uses native `#header-start` / `#header-actions` / `#header` / `#right` slots. React uses `headerStart` / `headerActions` / `header` / `right` render props. Core uses matching DOM Slots. Native Right support starts in `0.3.5-preview`; inspect the installed declarations before using it.
 - Vue supports `v-model:mode` and `mode-change`; React supports `mode` and `onModeChange`. Framework Header contexts expose the actual reactive `mode`. Core Slots use `getMode()` / `subscribeMode()`.
 - Header Start replaces only the Nova Brand. Header Actions replaces only the default Validate / Import / Export group, so a host can compose Validate / Save / Publish without rebuilding the editing tools. A complete Header replacement calls the public Actions Interface.
 - `actions.validate()` updates Nova's default status summary before emitting a read-only validation result with `source: 'toolbar'`; `shell.validate()` and framework Handle/Expose methods use `source: 'api'`. Vue receives `validation`, React receives `onValidation`, and Core uses `subscribeValidation()`. `valid` means there are no errors; warnings do not block publishing by default.
 - The default Header does not duplicate Fit; use the footer control or `fitView()`.
-- `regions` can hide `header`, `left`, `right`, or `footer` without leaving an empty layout track. Prop changes update the existing Shell; do not rebuild the Canvas.
-- Put a host-owned properties panel beside the Nova root. Use `selection-change` / `onSelectionChange` as its source of truth because it covers nodes, edges, multi-selection, clearing, and keyboard selection. Do not substitute `element-click` / `onElementClick`.
+- `config.ui.regions` can hide `header`, `left`, `right`, or `footer` without leaving an empty layout track. Config changes update the existing Shell; do not rebuild the Canvas.
+- A host panel can replace right content inside Nova, or live beside the Nova root after explicitly hiding the whole region. For an external design panel use `selection-change` / `onSelectionChange`, covering nodes, edges, multi-selection, clearing, and keyboard selection. Do not substitute `element-click` / `onElementClick`. Use the new `panelSelection` context for selection across read-only modes.
 - Join host business configuration by stable BPMN element ID. Saving, publishing, authorization, upload, and server transactions remain host responsibilities.
 - `theme="auto"` explicitly follows the system theme. The compatibility default remains `light`.
 - Vue and React both export standalone `BpmnPalettePanel` for a fully custom layout. Pass the same external Studio Controller to Canvas, Palette, and Properties.
 
+Group static Studio options under `config`: modeling constraints in `config.modeling`, Header layout in `config.ui`, Viewer display defaults in `config.viewer`, and SVG defaults in `config.export`. Keep model/XML, mode/allowedModes/runtime/projection/theme, resolvers, renderers, registries, callbacks, and Slots at the top level. Deprecated top-level configuration aliases remain compatible and explicitly win when the same item is supplied in both places.
+
+`config.ui.controlSize` defaults to `medium` (32px). `small`, `medium`, and `large` map to 28px, 32px, and 40px; Element Plus `default` and Ant Design `middle` both map to Nova `medium`. A host-specific value must be a strict `24px`–`48px` string such as `36px`; numbers, other units, CSS expressions, and out-of-range values are invalid. Header contexts expose read-only `ui.controlSize` and `ui.controlHeight`, while custom actions inherit `--nova-control-height`, `--nova-header-height`, `--nova-control-font-size`, `--nova-control-padding-inline`, `--nova-control-icon-size`, and `--nova-control-radius`. These sizes never change footer zoom, canvas floating controls, Palette, or Properties.
+
+Core Shell and framework handles expose `getConfig()` and `setConfig()`. The setter validates first and updates UI, Viewer, and Export in place without changing Model, XML, History, Selection, Mode, or Viewport. Modeling allowlists are Controller creation invariants; use the existing `setPropertiesProfile()` only for a runtime Profile change.
+
+### 4.2 Sidebar layout and collapse (0.3.5-preview)
+
+Read `SOURCE: docs/CUSTOMIZATION.md`, section `侧栏布局与平滑折叠`, in the co-located `llms-full.txt` before integrating the sidebar interfaces introduced in `0.3.5-preview`. They are not available in the older `0.3.4-preview` package. The host must still provide a computable container height.
+
+- Configure `config.ui.leftPanel/rightPanel.collapsible` (default `true`) and `defaultCollapsed` (wide-layout initialization only, default `false`). `config.ui.rightPanel.layout` defaults to `flex`: Nova supplies a bounded column, the host arranges fixed regions and a `flex: 1; min-height: 0; overflow: auto` body. Use `scroll` for Nova-owned scrolling of the entire content; avoid nested scroll containers unless intentional.
+- Core `slots.right`, Vue `#right`, and React `right` replace only content. Native slots preserve the host application tree and win over same-name Core DOM slots. Do not create another framework root or patch Nova classes. Header/Right contexts share `state`, `mode`, `ui`, and `panelSelection`, plus `studio`, `shell`, and `actions`.
+- Design shows both panels by default; Viewer only the right; Instance hides both. An omitted right region uses mode defaults; explicit `regions.right: 'default'` opts into Instance, while `'hidden'` removes the panel and its toggle. A slot never overrides hidden. Preserve this distinction when reading/updating Config.
+- Collapsed retains an edge toggle; hidden does not. Sidebars animate independently for 200ms and respect reduced motion. The first entry into a Shell container at or below 720px starts collapsible panels collapsed, with separate wide/narrow state memory. Expansion pushes the canvas, never opens a drawer. Content/form/scroll state survives; no automatic Fit occurs. Automatic Viewer projection responds once to the final size.
+- Use `getSidebarState()`, `setSidebarCollapsed(side, collapsed)`, and `subscribeSidebarChange()`. The setter returns `true` only for actual changes; unavailable/redundant requests return `false`. Vue emits `sidebar-change`; React uses `onSidebarChange`. The read-only event contains `side`, `collapsed`, `previousCollapsed`, `mode`, and `source: button | api | responsive | config`.
+- `panelSelection` contains `selection`, `selectedElement`, and `trace`. Core reads/subscribes with `getPanelSelection()` / `subscribePanelSelection()`. Design follows Controller selection; read-only clicks do not rewrite design selection. Do not substitute `state.selection` for the current approval-trace context. Hiding the sidebar does not disable trace clicks, details, or assets.
+- These policies belong to the default Shell, not a complete custom `layout()` or standalone Designer/Viewer. Sidebar UI state must never enter BPMN XML, Model, or History.
+
+### 4.3 Definition-time subtitle presentation
+
 For a host-owned definition-time subtitle, pass `nodeSubtitleResolver` to Studio, Canvas, or Viewer. Return `undefined` for Nova's default subtitle, `null` to remove the row, or a string (including an empty string) as the override. After data inside a stable closure or Map changes, call `refreshPresentation()` on the component handle or Shell. This refresh must not be implemented by mutating a node, re-importing XML, or remounting the component. The resolver applies only to standard Design/Viewer task and container cards and standard SVG fallback; a complete custom renderer wins, and Instance runtime summaries are never overridden.
 
 ## 5. Keep model ownership deterministic
@@ -227,12 +262,16 @@ This step is complete when edit, undo, redo, save, reload, and intentional exter
 
 ## 6. Add host constraints before business use
 
-Production workflow applications usually support a subset of BPMN. Configure `allowedNodeTypes` and `allowedEdgeTypes` on the Studio Controller or framework `BpmnStudio`; these reject unsupported imported models and block node/edge creation outside the host contract. The node allowlist filters Palette entries, but one allowed node type may still have multiple Palette presets. Configure matching Palette and Properties registries when the host needs custom labels or business fields.
+Production workflow applications usually support a subset of BPMN. Configure `config.modeling.allowedNodeTypes` and `config.modeling.allowedEdgeTypes` on the Studio Controller or framework `BpmnStudio`; these reject unsupported imported models and block node/edge creation outside the host contract. The node allowlist filters Palette entries, but one allowed node type may still have multiple Palette presets. Configure matching Palette and Properties registries when the host needs custom labels or business fields.
 
 Use `allowedModes` to expose only host-authorized workbench modes. Runtime changes use `setAllowedModes()` rather than rebuilding the Studio; invalid, empty, or duplicate lists are errors. Pass real Runtime data for instance mode; absence of Runtime data means no approval trace rather than demo business data.
 
 Runtime snapshots store asset references only. The host supplies `runtimeAssetResolver`. BPMN Nova does not execute workflow engines, submit approvals, upload/store attachments, issue permissions, or export PNG/PDF.
 
+For approval-trace integration, read the complete `SOURCE: docs/RUNTIME-INTEGRATION.md` section in the co-located `llms-full.txt` before mapping backend records. It covers instance-bound XML, stable work-item/visit identities, Flowable/Activiti mapping limits, complete approval scenarios, request cancellation, and assets. Runtime data stays top-level; only Studio display configuration belongs in `config.viewer`. Finish this branch only after the guide's relevant integration checks pass; report missing history instead of inventing facts.
+
+Named Runtime type re-exports from the Vue/React facade start in `0.3.5-preview`. Check the installed declarations before using them; the guide gives a Props-based type fallback for older releases. Keep the one-direct-package rule rather than adding Studio for these types.
+
 Read `llms-full.txt` before implementing custom Shell regions, Header composition, Actions, Palette, Properties, Context Menu, Renderer, Runtime, theme, or SVG export behavior. Use only public exports from the one selected package or supported Studio subpaths. `llms-full.txt` is generated by the Nova repository and must not be edited by hand.
 
 ## 7. Verify the integration
@@ -246,16 +285,24 @@ Run the target application's existing non-destructive quality commands, includin
 5. Intentional external XML replacement loads once and resets history once.
 6. Disallowed node types are unavailable and rejected by import/creation commands; disallowed modes are not rendered and `setMode()` returns `false` without changing state.
 7. Theme changes update the existing instance.
-8. Unmount/remount leaves no duplicate listeners, overlays, or framework instances.
-9. Browser Console has no errors.
-10. If a subtitle resolver is used, verify override, `undefined`, `null`, SVG parity, and that `refreshPresentation()` preserves XML, history, selection, scope, zoom, pan, theme, and mode. Verify Instance summaries are unchanged.
+8. Default `medium`, presets, and a custom value such as `36px` resize only Header controls; invalid `config.ui.controlSize` leaves the previous DOM and configuration intact.
+9. Unmount/remount leaves no duplicate listeners, overlays, or framework instances.
+10. Browser Console has no errors.
+11. If a subtitle resolver is used, verify override, `undefined`, `null`, SVG parity, and that `refreshPresentation()` preserves XML, history, selection, scope, zoom, pan, theme, and mode. Verify Instance summaries are unchanged.
+12. If sidebars are used, verify independent collapse, narrow containers, reduced motion, keyboard focus, host form/scroll preservation, Flex/Scroll behavior, native slot updates, Instance defaults, and selection/event consistency. Keep XML, history, and viewport invariant during ordinary collapse; record automatic projection changes separately.
 
 The installation is complete only when the package is present, the production build succeeds, and the relevant browser checks pass. Report any unverified branch explicitly.
 
+## Maintainer release policy
+
+Before changing Nova package versions, publishing, or recovering a partial release, read the complete `SOURCE: docs/NPM-PACKAGES.md` section in the co-located `llms-full.txt` (or that file in the source repository). It defines mandatory lockstep versions and full releases of all three public packages, including unchanged packages, plus Registry completion checks. This is a maintainer rule, not an instruction for host applications to install all three packages or authorization to publish without a user request.
+
 ## Reference
 
 - `README.md`: human-facing product overview and quick start.
 - `llms-full.txt`: complete generated AI context containing setup, component, Interface, customization, publishing, and architecture documentation.
+- `docs/RUNTIME-INTEGRATION.md`: authoritative approval-trace guide in the source repository; the full content also ships inside every public package's `llms-full.txt`.
+- `docs/NPM-PACKAGES.md`: authoritative global version and full-release policy, including partial-release recovery.
 
 
 <!-- SOURCE: README.md -->
@@ -269,7 +316,7 @@ The installation is complete only when the package is present, the production bu
 BPMN Nova 提供可嵌入的流程设计器、只读 Viewer、运行态审批轨迹、实例级主题、纯 SVG 导出，以及 React / Vue 适配。项目使用独立的 DOM / SVG 渲染实现，不依赖 `bpmn-js`，并为 Flowable 与 Activiti 提供 XML Profile 和属性扩展。
 
 > [!IMPORTANT]
-> 当前版本为 `0.3.4-preview`。它适合 SDK 评估、产品集成验证和企业审批原型；公开 Interface、BPMN XML round-trip 与引擎兼容能力仍在持续稳定中，建议使用 `@preview` 安装并在生产接入前完成目标流程验证。
+> 当前版本为 `0.3.5-preview`。它适合 SDK 评估、产品集成验证和企业审批原型；公开 Interface、BPMN XML round-trip 与引擎兼容能力仍在持续稳定中，建议使用 `@preview` 安装并在生产接入前完成目标流程验证。
 
 AI 或代码生成工具接入必须从 [`llms.txt`](llms.txt) 的完整安装流程开始；需要全部接口与定制上下文时再读取 [`llms-full.txt`](llms-full.txt)。这两份文件也会随三个公开 npm 包发布。
 
@@ -397,16 +444,24 @@ const model = createEmptyProcess('flowable')
 model.id = 'Process_PurchaseApproval'
 model.name = '采购申请审批流程'
 
+const config = {
+  modeling: {
+    propertiesProfile: 'business',
+    allowedNodeTypes: ['startEvent', 'userTask', 'exclusiveGateway', 'endEvent'],
+    allowedEdgeTypes: ['sequenceFlow'],
+  },
+  ui: { controlSize: 'medium' },
+}
+
 const studio = createStudioController({
   model,
-  propertiesProfile: 'business',
-  allowedNodeTypes: ['startEvent', 'userTask', 'exclusiveGateway', 'endEvent'],
-  allowedEdgeTypes: ['sequenceFlow'],
+  config,
 })
 
 const shell = createStudioShell({
   container: document.querySelector('#bpmn-studio'),
   studio,
+  config,
   mode: 'design',
   allowedModes: ['design'],
   theme: 'auto',
@@ -430,6 +485,8 @@ const studio = createStudioController({ model })
 
 ### Viewer 与 Runtime
 
+真实后端接入请从[审批轨迹接入指南](docs/RUNTIME-INTEGRATION.md)开始：包含匹配的 XML、Flowable/Activiti 映射、完整 Snapshot、会签与驳回重入、刷新和附件。Vue/React 的具名 Runtime 类型出口自 `0.3.5-preview` 提供；指南也提供旧版的兼容类型写法。
+
 ```js
 import { BpmnViewer } from '@bpmn-nova/studio/viewer'
 import '@bpmn-nova/studio/styles.css'
@@ -457,15 +514,22 @@ npm install @bpmn-nova/react@preview
 import { BpmnStudio } from '@bpmn-nova/react'
 import '@bpmn-nova/react/styles.css'
 
+const studioConfig = {
+  modeling: {
+    propertiesProfile: 'business',
+    allowedNodeTypes: ['startEvent', 'userTask', 'exclusiveGateway', 'endEvent'],
+    allowedEdgeTypes: ['sequenceFlow'],
+  },
+  ui: { controlSize: 'medium' },
+}
+
 export function WorkflowEditor({ initialXml }) {
   return (
     <div style={{ height: 720 }}>
       <BpmnStudio
         xml={initialXml}
         engine="flowable"
-        propertiesProfile="business"
-        allowedNodeTypes={['startEvent', 'userTask', 'exclusiveGateway', 'endEvent']}
-        allowedEdgeTypes={['sequenceFlow']}
+        config={studioConfig}
         mode="design"
         allowedModes={['design']}
         theme="auto"
@@ -492,6 +556,14 @@ import { BpmnStudio } from '@bpmn-nova/vue'
 import '@bpmn-nova/vue/styles.css'
 
 const props = defineProps({ initialXml: String })
+const studioConfig = {
+  modeling: {
+    propertiesProfile: 'business',
+    allowedNodeTypes: ['startEvent', 'userTask', 'exclusiveGateway', 'endEvent'],
+    allowedEdgeTypes: ['sequenceFlow'],
+  },
+  ui: { controlSize: 'medium' },
+}
 
 function onChange(model, reason, nextXml) {
   console.log(reason, nextXml)
@@ -503,9 +575,7 @@ function onChange(model, reason, nextXml) {
     <BpmnStudio
       :xml="props.initialXml"
       engine="flowable"
-      properties-profile="business"
-      :allowed-node-types="['startEvent', 'userTask', 'exclusiveGateway', 'endEvent']"
-      :allowed-edge-types="['sequenceFlow']"
+      :config="studioConfig"
       mode="design"
       :allowed-modes="['design']"
       theme="auto"
@@ -528,9 +598,10 @@ Vue Expose 提供与 Vanilla 实例对应的 Actions、校验、XML、视图、
   engine="activiti"
   mode="design"
   :allowed-modes="['design']"
-  :allowed-node-types="supportedNodeTypes"
-  :allowed-edge-types="['sequenceFlow']"
-  :regions="{ right: 'hidden' }"
+  :config="{
+    modeling: { allowedNodeTypes: supportedNodeTypes, allowedEdgeTypes: ['sequenceFlow'] },
+    ui: { controlSize: 'medium', regions: { right: 'hidden' } },
+  }"
   theme="auto"
   @change="handleChange"
   @selection-change="handleSelectionChange"
@@ -539,7 +610,7 @@ Vue Expose 提供与 Vanilla 实例对应的 Actions、校验、XML、视图、
   <template #header-start="{ state, actions }">
     <!-- 返回、业务图标、流程名称和类型 -->
   </template>
-  <template #header-actions="{ actions, mode }">
+  <template #header-actions="{ actions, mode, ui }">
     <button type="button" :disabled="mode !== 'design'" @click="actions.validate()">校验</button>
     <button type="button" :disabled="mode !== 'design'" @click="saveDraft(actions.exportXml())">保存</button>
     <button type="button" :disabled="mode !== 'design'" @click="publishProcess(actions)">发布</button>
@@ -547,10 +618,26 @@ Vue Expose 提供与 Vanilla 实例对应的 Actions、校验、XML、视图、
 </BpmnStudio>
 ```
 
-`header-start` 只替换 Nova Brand；`header-actions` 只替换默认的“校验 / 导入 / 导出”动作组，适合宿主组合“校验 / 保存 / 发布”；`header` 可替换整个 Header。`regions` 隐藏区域后不会保留 Grid 空白，也不会重建 Canvas。React 提供等价的 `headerStart` / `headerActions` / `header` Render Prop，Core 提供同名 DOM Slots。默认 Header 的最佳视图只保留在底部缩放区。
+`header-start` 只替换 Nova Brand；`header-actions` 只替换默认的“校验 / 导入 / 导出”动作组，适合宿主组合“校验 / 保存 / 发布”；`header` 可替换整个 Header。`config.ui.regions` 隐藏区域后不会保留 Grid 空白，也不会重建 Canvas。React 提供等价的 `headerStart` / `headerActions` / `header` Render Prop，Core 提供同名 DOM Slots。默认 Header 的最佳视图只保留在底部缩放区。
 
 `actions.validate()` 会先更新 Nova 默认状态栏，再发送 `validation` 事件并返回 issues；公开 `validate()` 使用相同流程。`valid` 只在存在 error 时为 `false`，warning 会展示和上报但不默认阻止发布。
 
+静态建模、Shell UI、Viewer 展示和 SVG 导出选项统一收敛在 `config`。顶部控件由 `config.ui.controlSize` 控制，默认 `medium`，可选 `small`、`medium`、`large` 或 `24px`–`48px`；该值只改变 Header，不改变底部缩放区、画布浮动工具、Palette 或 Properties。Header Slot 的 `ui.controlHeight` 可直接用于对齐宿主控件：Element Plus 的 `default`、Ant Design 的 `middle` 对应 Nova `medium`。自定义像素值时也可读取 `--nova-control-height` 等公开 CSS Variables。
+
+```js
+shell.setConfig({
+  ui: {
+    controlSize: '36px',
+    regions: { right: 'hidden' },
+    sidebarWidth: { left: 232, right: 344 },
+  },
+})
+
+console.log(shell.getConfig(), shell.ui.controlHeight) // 36px
+```
+
+旧的 `propertiesProfile`、`allowedNodeTypes`、`regions`、`responsive`、`timeline`、`svgExport` 等顶层字段继续兼容，但已标记为 Deprecated；同一项同时出现时，显式旧字段优先。`config.modeling` 只在 Controller 创建时建立约束，运行中节点和连线白名单不会被 `setConfig()` 改写。
+
 发布事务由宿主实现，并可以直接复用同一个 Header Action 完成“校验后发布”：
 
 ```js
@@ -561,7 +648,24 @@ async function publishProcess(actions) {
 }
 ```
 
-宿主右侧属性面板应位于 Nova 外部，并以 `selection-change` / `onSelectionChange` 为状态来源、以稳定 BPMN Element ID 关联业务配置。`element-click` 不能替代选择事件。Nova 不拥有宿主的保存、发布、权限或服务端事务。
+宿主右侧属性面板可以通过右侧 Slot 复用 Nova 布局，也可以在显式隐藏 Nova 右侧后放在外部。外部设计面板以 `selection-change` / `onSelectionChange` 为状态来源，以稳定 BPMN Element ID 关联业务配置；`element-click` 不能替代选择事件。Nova 不拥有宿主的保存、发布、权限或服务端事务。
+
+### 侧栏扩展、滚动与平滑折叠
+
+Core `slots.right`、Vue `#right`、React `right` 可以替换右侧内容，Nova 继续管理宽度、高度和左右分隔线中点的折叠按钮。右侧默认 `flex`，适合固定标题/底部、中间内容滚动；设置 `scroll` 则由 Nova 滚动整个内容。
+
+```js
+const config = {
+  ui: {
+    leftPanel: { collapsible: true, defaultCollapsed: false },
+    rightPanel: { collapsible: true, defaultCollapsed: false, layout: 'flex' },
+  },
+}
+```
+
+左右独立收起，200ms 平滑过渡并尊重减少动态效果；收起保留展开按钮，不卸载内容、不丢失表单/滚动状态、不自动 Fit。Shell 容器 ≤720px 时首次默认收起，展开继续挤压画布，宽窄屏分别记忆状态。**隐藏不同于收起**：`regions.right: 'hidden'` 移除整个区域及按钮；Instance 默认隐藏右侧，显式 `'default'` 可开启。
+
+Shell 与框架 Handle/Expose 提供 `getSidebarState()`、`setSidebarCollapsed()`、`subscribeSidebarChange()`；Vue `sidebar-change`、React `onSidebarChange` 接收同一事件。Header/Right Context 的 `panelSelection` 支持设计与只读轨迹选择，Core 使用 `getPanelSelection()` / `subscribePanelSelection()`。完整 Core/Vue/React 用法、Flex CSS 和兼容说明见[侧栏指南](docs/CUSTOMIZATION.md#侧栏布局与平滑折叠)。本节新接口自 `0.3.5-preview` 提供。
 
 `theme="auto"` 是显式启用系统主题适配；为了兼容已有接入，未传 Theme 时仍默认为 `light`。Vue 包同时提供独立的 `BpmnPalettePanel`，用于完全自定义布局。
 
@@ -760,6 +864,7 @@ shell.openSvgExportPreview()
 
 ## 浏览器接入注意事项
 
+- 节点默认尺寸不等于导入尺寸：组件加载服务端 XML 也会解析 BPMN DI Bounds；保存/导出会写入模型宽高。自 `0.3.5-preview` 提供的网关与数据图元兼容修复只让内部图形按实际容器缩小居中，并校正显示连线，不扩大 DI、不改 waypoint。宿主无需配置节点尺寸、删除重建节点或覆盖内部 CSS，详见 [DI 与视觉尺寸](docs/API.md#节点-di-与视觉尺寸)。
 - 为 Canvas、Studio 和 Viewer 容器设置明确高度；隐藏容器恢复显示后可调用 `fitView()`。
 - CSS 必须由宿主显式导入；Studio、React、Vue 各自提供一个自包含样式入口。
 - 使用 ESM 与现代浏览器；Node.js 18+ 用于构建和包消费工具链。
@@ -772,6 +877,7 @@ shell.openSvgExportPreview()
 - [快速开始](docs/GETTING-STARTED.md)：Studio、Designer、Viewer、React、Vue 与 XML。
 - [组件参数](docs/COMPONENTS.md)：Options、Props、事件、Ref / Expose 和实例方法。
 - [API](docs/API.md)：模型、命令、XML、Runtime Snapshot、主题与导出类型。
+- [审批轨迹接入指南](docs/RUNTIME-INTEGRATION.md)：宿主数据转换、组件接入、审批轮次、回退与资源解析。
 - [自定义指南](docs/CUSTOMIZATION.md)：主题、Palette、图标、Renderer、Slot 和运行态扩展。
 - [Properties Panel](docs/PROPERTIES-PANEL.md)：Provider、Group、Entry、Data Provider 和自定义字段。
 - [NPM Packages](docs/NPM-PACKAGES.md)：三个公开包、Studio 子路径、构建验证与 Registry 清理说明。
@@ -893,16 +999,24 @@ const model = createEmptyProcess('flowable')
 model.id = 'Process_Approval'
 model.name = '审批流程'
 
+const config = {
+  modeling: {
+    propertiesProfile: 'business',
+    allowedNodeTypes: ['startEvent', 'userTask', 'exclusiveGateway', 'endEvent'],
+    allowedEdgeTypes: ['sequenceFlow'],
+  },
+  ui: { controlSize: 'medium' },
+}
+
 const studio = createStudioController({
   model,
-  propertiesProfile: 'business',
-  allowedNodeTypes: ['startEvent', 'userTask', 'exclusiveGateway', 'endEvent'],
-  allowedEdgeTypes: ['sequenceFlow'],
+  config,
 })
 
 const shell = createStudioShell({
   container: document.querySelector('#studio'),
   studio,
+  config,
   mode: 'design',
   allowedModes: ['design', 'viewer'],
   theme: 'auto',
@@ -974,6 +1088,11 @@ import { useRef, useState } from 'react'
 import { BpmnStudio } from '@bpmn-nova/react'
 import '@bpmn-nova/react/styles.css'
 
+const STUDIO_CONFIG = {
+  modeling: { propertiesProfile: 'business' },
+  ui: { controlSize: 'medium' },
+}
+
 export function WorkflowEditor({ initialXml }) {
   const studioRef = useRef(null)
   const [mode, setMode] = useState('design')
@@ -984,10 +1103,10 @@ export function WorkflowEditor({ initialXml }) {
         ref={studioRef}
         xml={initialXml}
         engine="flowable"
+        config={STUDIO_CONFIG}
         mode={mode}
         allowedModes={['design', 'viewer']}
         theme="auto"
-        propertiesProfile="business"
         onChange={(model, reason, nextXml) => saveDraft(nextXml)}
         onModeChange={(event) => setMode(event.mode)}
       />
@@ -1015,6 +1134,10 @@ import '@bpmn-nova/vue/styles.css'
 const props = defineProps({ initialXml: String })
 const studioRef = ref(null)
 const mode = ref('design')
+const config = {
+  modeling: { propertiesProfile: 'business' },
+  ui: { controlSize: 'medium' },
+}
 const onChange = (model, reason, nextXml) => saveDraft(nextXml)
 </script>
 
@@ -1024,10 +1147,10 @@ const onChange = (model, reason, nextXml) => saveDraft(nextXml)
       ref="studioRef"
       :xml="props.initialXml"
       engine="flowable"
+      :config="config"
       v-model:mode="mode"
       :allowed-modes="['design', 'viewer']"
       theme="auto"
-      properties-profile="business"
       @change="onChange"
       @mode-change="event => console.log(event.source)"
     />
@@ -1039,28 +1162,48 @@ const onChange = (model, reason, nextXml) => saveDraft(nextXml)
 
 ### 4.1 宿主工作台组合规则
 
-默认 `BpmnStudio` 是完整工作台。只有宿主明确拥有自己的区域时才配置 `regions`；例如 DX 复用自己的业务属性面板时使用 `regions: { right: 'hidden' }`，并把该面板放在 Nova 外部。隐藏区域不保留 Grid 轨道。
+默认 `BpmnStudio` 是完整工作台。静态建模、布局、Viewer 和导出选项统一放入 `config`；数据、状态、事件和 Slots 保持顶层。宿主内容可通过右侧 Slot 复用 Nova 布局；只有需要把整个面板放到 Nova 外部时，才使用 `config: { ui: { regions: { right: 'hidden' } } }`。隐藏区域不保留 Grid 轨道或展开按钮，不能用右侧 Slot 覆盖。
 
-Vue 使用原生 `#header-start` / `#header-actions` / `#header`，React 使用 `headerStart` / `headerActions` / `header` Render Prop。Header Start 只替换 Brand，Header Actions 只替换默认“校验 / 导入 / 导出”动作组，完整 Header 通过公开 `StudioShellActions` 重建所需编辑操作。不要创建第二个 Vue App 或 React Root 挂载 Header。
+Vue 使用原生 `#header-start` / `#header-actions` / `#header` / `#right`，React 使用 `headerStart` / `headerActions` / `header` / `right` Render Prop。Header Start 只替换 Brand，Header Actions 只替换默认“校验 / 导入 / 导出”动作组，完整 Header 通过公开 `StudioShellActions` 重建所需编辑操作；Right 仅替换侧栏内容。不要创建第二个 Vue App 或 React Root 挂载这些内容。同名原生 Slot 优先于 Core DOM Slot。
 
 宿主通常在 Header Actions 中组合“校验 / 保存 / 发布”。校验按钮调用 `actions.validate()`：Nova 先更新默认状态栏，再通过 Vue `validation`、React `onValidation` 或 Core `subscribeValidation()` 发送只读结果。程序化 `validate()` 的来源为 `api`，Header Action 的来源为 `toolbar`；`valid` 仅在存在 error 时为 `false`。保存、发布、权限和服务端事务始终留在宿主。顶部不再重复渲染最佳视图，底部缩放区及 `fitView()` Interface 继续可用。
 
-Header Slot/Render Context 的 `mode` 是当前实际模式。宿主用它显隐保存、发布按钮或外部属性面板；不要从 Nova Header DOM 读取选中按钮。运行时改变 `allowedModes` 会原地更新默认模式按钮，移除当前模式时只回退一次。
+Header Slot/Render Context 的 `mode` 是当前实际模式，`ui` 是只读的实际控件尺寸。宿主用它显隐保存、发布按钮、映射自己的组件库尺寸或外部属性面板；不要从 Nova Header DOM 读取选中按钮。运行时改变 `allowedModes` 会原地更新默认模式按钮，移除当前模式时只回退一次。
+
+`config.ui.controlSize` 默认为 Nova `medium`（32px），对应 Element Plus `default` 和 Ant Design `middle`；`small`、`large` 分别对应两者的同名尺寸。宿主也可传 `24px`–`48px` 的严格 CSS 像素字符串，例如 `36px`。自定义 Header 控件可以继承 `--nova-control-height`、`--nova-header-height`、`--nova-control-font-size`、`--nova-control-padding-inline`、`--nova-control-icon-size` 和 `--nova-control-radius`。该尺寸边界只覆盖 Header，不影响底部缩放区、画布浮动工具、Palette 或 Properties。
+
+`getConfig()` 返回实际归一化配置，`setConfig()` 在完整校验成功后原地更新 UI、Viewer 与 Export，并保持 Model、XML、History、Selection、Mode 和 Viewport。`config.modeling.allowedNodeTypes` 与 `allowedEdgeTypes` 只在 Controller 创建时建立不变量；运行时 Profile 仍通过 `setPropertiesProfile()` 修改。旧顶层配置仅作为 Deprecated 兼容别名；同一项新旧并存时，旧顶层显式值优先。
 
 外部业务属性面板必须以 `selection-change` / `onSelectionChange` 为状态来源，以稳定 BPMN Element ID 关联业务配置。该事件覆盖节点、连线、多选、清空和键盘选择；`element-click` / `onElementClick` 只是点击观察事件。保存草稿、发布、权限和服务端事务属于宿主，不要写入 Nova Actions。
 
 显式 `theme="auto"` 才表示跟随系统主题；默认 Theme 为兼容性的 `light`。Vue 与 React 都公开独立 `BpmnPalettePanel`，完整自定义布局时必须让 Canvas、Palette 和 Properties 复用同一个外部 Controller。
 
-### 4.1 模型所有权
+### 4.2 侧栏布局与折叠门禁
+
+新增侧栏接口自 `0.3.5-preview` 提供，先核对目标安装包的版本与声明。完整 Core/Vue/React 示例见[侧栏指南](CUSTOMIZATION.md#侧栏布局与平滑折叠)，不要以内部 CSS 覆盖实现本能力。
+
+- `config.ui.leftPanel/rightPanel` 收拢 `collapsible`（默认 `true`）、`defaultCollapsed`（宽屏初始化默认 `false`）；右侧另有 `layout: 'flex' | 'scroll'`，默认 `flex`。不要添加零散顶层布局 Props。
+- Flex 由宿主安排固定头尾和弹性滚动区，Nova 仅提供有界纵向 Flex 容器；Scroll 由 Nova 滚动整个内容。宿主高度链必须可计算，不能只给无高度基准的根节点设置 `height: 100%`。
+- Design 默认显示左右，Viewer 仅右侧，Instance 默认两侧隐藏。右侧显式 `'default'` 可在 Instance 开启，`'hidden'` 移除内容和按钮；Slot 不改变显隐优先级。`getConfig()` 保留未配置意图，不应把读取结果中的默认值再转成显式开启。
+- Shell 容器 ≤720px 首次收起可折叠面板，保留按钮；宽窄屏分别记忆状态。两侧独立展开且挤压画布，非抽屉。200ms 动画尊重减少动态效果，不卸载 Slot、不自动 Fit；Viewer 自动投影仅在动画结束后按最终宽度处理。
+- 使用 `getSidebarState()` / `setSidebarCollapsed()` / `subscribeSidebarChange()`；Vue `sidebar-change`、React `onSidebarChange` 与 Core 事件一致。折叠是 Shell UI 状态，不写入 BPMN 模型或历史。
+- Header/Right Context 共用响应式 `mode`、`state`、`ui`、`panelSelection`。Core 使用 `getPanelSelection()` / `subscribePanelSelection()`；Viewer/Instance 的实际选择不回写 Controller 设计选择，也不能用设计 `state.selection` 代替。
+- 验证折叠按钮、键盘、减少动态效果、表单/滚动状态保留、跨模式选择更新和无重复订阅；完整自定义 `layout()` 与独立 Designer/Viewer 不接管默认侧栏。
+
+### 4.3 模型所有权
 
 框架组件的 `xml`/`model` 是外部替换输入，`change`/`onChange` 的 XML 是草稿输出。宿主可以保存该输出；如果响应式状态回写的是完全相同的导出 XML，Adapter 会忽略这次回声并保留 Undo/Redo 历史。只有加载另一流程或服务器 revision 时才传入不同 XML，此时模型和历史会替换一次。
 
 React/Vue 包重新导出创建外部 Controller、Palette、Properties、Context Menu、Icon 和 Template Registry 所需的公开函数，因此高级接入仍只需要直接安装对应 Adapter 包。
 
-生产工作流通常只支持 BPMN 子集。通过 Controller 或 `BpmnStudio` 的 `allowedNodeTypes` 与 `allowedEdgeTypes` 声明节点、连线白名单；该限制会校验初始/外部模型，并约束创建、快捷新增、模板和节点类型转换。Palette 会服从节点白名单，但同一节点类型可以有多个 Preset。通过 `allowedModes` 限制工作台可切换模式。实例模式没有 Runtime 时保持空运行事实，不会自动加载演示数据。
+生产工作流通常只支持 BPMN 子集。通过 Controller 或 `BpmnStudio` 的 `config.modeling.allowedNodeTypes` 与 `allowedEdgeTypes` 声明节点、连线白名单；该限制会校验初始/外部模型，并约束创建、快捷新增、模板和节点类型转换。Palette 会服从节点白名单，但同一节点类型可以有多个 Preset。通过顶层 `allowedModes` 限制工作台可切换模式。实例模式没有 Runtime 时保持空运行事实，不会自动加载演示数据。
 
 ## 5. Runtime Snapshot 与审批动作
 
+接入真实审批数据、会签、回退或附件前，先完整阅读[审批轨迹接入指南](RUNTIME-INTEGRATION.md)。使用 npm 包内上下文时读取 `llms-full.txt` 中 `SOURCE: docs/RUNTIME-INTEGRATION.md` 对应全文。按指南完成身份映射、快照转换、过期请求处理与场景验收；引擎字段缺失时向宿主报告缺口，不生成虚假的审批事实。
+
+Vue/React 的 14 个具名 Runtime 类型出口自 `0.3.5-preview` 提供；旧安装版本使用指南中的 Props 推导，不增加 Studio 直依赖。`runtime` 保持顶层，Studio 展示配置进入 `config.viewer`，独立 Viewer 继续使用顶层展示 Options。
+
 Runtime Snapshot 描述已经发生的运行事实，不负责发起审批或执行流程引擎。新动作必须关联 `elementId` 与 `visitId`；`activityId` 用于精确关联工作项。
 
 ```js
@@ -1190,6 +1333,8 @@ const artifact = await viewer.exportSvg({
 console.log(artifact.svg, artifact.width, artifact.height, artifact.warnings)
 ```
 
+完整 Studio 的默认导出选项放在 `config.export`；单次调用传入的选项仍用于本次导出。
+
 导出内容不受当前缩放、平移或滚动影响。移动时间线会展开全部历史动作。审批图片通过 `purpose: 'export'` 解析并嵌入 Data URL；普通附件只输出名称、MIME 和大小。第一版不导出 PNG/PDF。
 
 ## 9. 清理与生命周期
@@ -1240,11 +1385,843 @@ BPMN Nova 负责 BPMN 建模、XML 导入导出、只读展示、运行态审批
 - [项目架构](ARCHITECTURE.md)
 
 
+<!-- SOURCE: docs/RUNTIME-INTEGRATION.md -->
+
+# 审批轨迹接入指南
+
+本文面向把真实审批记录接入 Nova 的前后端开发者。按“准备定义与实例 → 转换数据 → 挂载组件 → 更新与交互 → 验收”阅读；会签、驳回和附件规则集中在对应章节。
+
+> 版本边界：Vue/React 根入口的 Runtime 类型重导出自 `0.3.5-preview` 提供。下列具名类型示例面向该版本及后续兼容版本；已安装旧版没有这些出口时，使用第 2.4 节的 Props 类型推导，不增加 Studio 直依赖。Studio 原有 Runtime 出口保持不变。
+
+## 1. 准备定义与最小实例
+
+### 1.1 职责与读取顺序
+
+| 输入或职责 | 所有者 | 约束 |
+| --- | --- | --- |
+| BPMN XML | 宿主定义服务 | 读取实例绑定的定义版本，保留原始节点、连线和 DI |
+| 引擎当前状态、活动和任务历史 | 宿主引擎适配层 | 按实例查询、关联、去重，区分活动 ID 与工作项 ID |
+| 审批操作、回退目标、附件引用 | 宿主业务日志 | 保存真实业务事实，不从任务结束时间猜测审批决定 |
+| `runtime` | 宿主转换层 | 组装引擎中立的 `ProcessInstanceSnapshot` |
+| 图形、时间线、默认详情 | Nova | 读取 XML 与 Snapshot，派生展示，不执行审批业务 |
+
+推荐由后端聚合一致的数据快照，前端只接收定义和 Snapshot。现有宿主也可以在前端执行纯转换，但引擎鉴权、查询、分页、历史保留和审批事务仍由宿主负责。`engine="flowable"` / `engine="activiti"` 选择 XML 与属性 Profile，不会自动查询引擎。
+
+先按 `processInstanceId` 确认其 `processDefinitionId`，再获取该定义的 XML。实例迁移后的定义绑定也由后端明确提供。不要用流程 Key 对应的最新 XML，也不要在前端按名称重新生成节点 ID。
+
+### 1.2 可复制的最小数据
+
+下面保存为宿主的 `approval-data.ts`。整个指南沿用“开始 → 提交申请 → 审核 → 结束”的节点 ID。XML 是 `isExecutable="false"` 的可视化教学定义，不是包含会签表达式、回退命令和权限规则的引擎部署模板；真实接入始终使用实例自己的 XML。
+
+共享 TypeScript 文件以下以 Vue 为例。React 项目把共享文件的类型导入改为 `@bpmn-nova/react`，Core 项目改为 `@bpmn-nova/studio`；每个宿主只直接依赖所选包。示例文件名是宿主代码组织建议，不是 npm 子路径。
+
+```ts title="approval-data.ts"
+import type { ProcessInstanceSnapshot } from '@bpmn-nova/vue'
+
+export const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
+  xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI"
+  xmlns:dc="http://www.omg.org/spec/DD/20100524/DC"
+  xmlns:di="http://www.omg.org/spec/DD/20100524/DI"
+  id="Definitions_Approval" targetNamespace="https://example.org/approval">
+  <bpmn:process id="Process_Approval" name="申请审批" isExecutable="false">
+    <bpmn:startEvent id="StartEvent_1" name="开始" />
+    <bpmn:userTask id="Task_Submit" name="提交申请" />
+    <bpmn:userTask id="Task_Review" name="审核" />
+    <bpmn:endEvent id="EndEvent_1" name="结束" />
+    <bpmn:sequenceFlow id="Flow_Start_Submit" sourceRef="StartEvent_1" targetRef="Task_Submit" />
+    <bpmn:sequenceFlow id="Flow_Submit_Review" sourceRef="Task_Submit" targetRef="Task_Review" />
+    <bpmn:sequenceFlow id="Flow_Review_End" sourceRef="Task_Review" targetRef="EndEvent_1" />
+  </bpmn:process>
+  <bpmndi:BPMNDiagram id="Diagram_Approval">
+    <bpmndi:BPMNPlane id="Plane_Approval" bpmnElement="Process_Approval">
+      <bpmndi:BPMNShape id="Shape_Start" bpmnElement="StartEvent_1">
+        <dc:Bounds x="80" y="122" width="36" height="36" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="Shape_Submit" bpmnElement="Task_Submit">
+        <dc:Bounds x="180" y="100" width="160" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="Shape_Review" bpmnElement="Task_Review">
+        <dc:Bounds x="420" y="100" width="160" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="Shape_End" bpmnElement="EndEvent_1">
+        <dc:Bounds x="650" y="122" width="36" height="36" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNEdge id="Edge_Start_Submit" bpmnElement="Flow_Start_Submit">
+        <di:waypoint x="116" y="140" /><di:waypoint x="180" y="140" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="Edge_Submit_Review" bpmnElement="Flow_Submit_Review">
+        <di:waypoint x="340" y="140" /><di:waypoint x="420" y="140" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="Edge_Review_End" bpmnElement="Flow_Review_End">
+        <di:waypoint x="580" y="140" /><di:waypoint x="650" y="140" />
+      </bpmndi:BPMNEdge>
+    </bpmndi:BPMNPlane>
+  </bpmndi:BPMNDiagram>
+</bpmn:definitions>`
+
+export const runtime: ProcessInstanceSnapshot = {
+  processInstanceId: 'PI-1001',
+  status: 'running',
+  activities: [
+    { id: 'activity:h-start', elementId: 'StartEvent_1', visitId: 'visit-start-1', status: 'completed', startTime: '2026-09-05T09:00:00+08:00', endTime: '2026-09-05T09:00:00+08:00' },
+    { id: 'task:t-submit-1', elementId: 'Task_Submit', visitId: 'visit-submit-1', status: 'completed', startTime: '2026-09-05T09:00:01+08:00', endTime: '2026-09-05T09:05:00+08:00', participant: { id: 'u-applicant', name: '申请人' } },
+    { id: 'task:t-review-1', elementId: 'Task_Review', visitId: 'visit-review-1', status: 'active', startTime: '2026-09-05T09:05:01+08:00', participant: { id: 'u-li', name: '李经理' } },
+  ],
+  visitedEdges: ['Flow_Start_Submit', 'Flow_Submit_Review'],
+}
+```
+
+最小 Snapshot 不要求 `actions`，所以这里只能展示工作项状态和处理人，不能据此声称“已经同意”。第 4 节再补充真实操作。
+
+最小 Vue 组件保存为 `ApprovalPreview.vue`，仅在浏览器挂载；Nuxt 等 SSR 宿主使用自己的客户端边界：
+
+```vue title="ApprovalPreview.vue"
+<script setup lang="ts">
+import { BpmnViewer } from '@bpmn-nova/vue'
+import '@bpmn-nova/vue/styles.css'
+import { xml, runtime } from './approval-data'
+</script>
+
+<template>
+  <div style="height: 640px; min-height: 320px">
+    <BpmnViewer :xml="xml" :runtime="runtime" engine="flowable" projection="approval" />
+  </div>
+</template>
+```
+
+完成条件：审核节点显示处理中和李经理；切换 `standard` 能看到全部四个节点；没有请求业务后端的隐式行为。父级隐藏或高度为零时应先恢复布局，再调用公开 `fitView()`。
+
+## 2. 数据契约与身份关联
+
+### 2.1 Snapshot 与记录
+
+| 字段 | 类型与必填性 | 语义 |
+| --- | --- | --- |
+| `processInstanceId` | 必填 `string` | 一个真实实例的稳定 ID |
+| `status` | 必填 `running / completed / suspended / terminated` | 实例状态；未发起不是上述状态之一 |
+| `activities` | 必填 `ActivityInstance[]` | 已发生的活动执行或工作项，包含当前记录与历史 |
+| `visitedEdges` | 必填 `string[]`，可为空 | 已确认曾经过的 BPMN 连线 ID 汇总，不表示当前全部有效 |
+| `actions` | 可选 `RuntimeApprovalAction[]` | 不可变的业务操作事实 |
+| `transitions` | 可选 `RuntimeTransition[]` | 运行时跳转，独立于 BPMN Sequence Flow |
+| `edgeVisits` | 可选 `RuntimeEdgeVisit[]` | 每次经过连线的独立记录，支持重复经过及失效历史 |
+
+| 记录 | 必填字段 | 常用可选字段 |
+| --- | --- | --- |
+| `ActivityInstance` | `id`、`elementId`、`status` | `visitId`、起止时间、`participant`、会签元数据 |
+| `RuntimeApprovalAction` | `id`、`type`、`elementId`、`visitId`、`occurredAt` | `activityId`、`actor`、`targets`、`targetElementId`、`content` |
+| `RuntimeTransition` | `id`、`type`、`sourceElementId` | 来源工作项、目标节点、时间、`actionId`、状态和失效范围 |
+| `RuntimeEdgeVisit` | `id`、`edgeId` | `visitId`、`occurredAt`、`status: effective / superseded` |
+
+新接入应完整提供 `visitId` 和带时区的 ISO 时间。虽有兼容回退，缺失时间或关联 ID 不能保证多轮审批顺序正确。时间使用 `2026-09-05T09:05:00+08:00` 或 UTC `Z`，不要依赖浏览器解析无时区文本。
+
+活动状态只接受 `active / completed / failed / cancelled / skipped`；`idle` 是没有工作项时的派生状态，`rejected` 是展示状态，两者都不是 `ActivityInstance.status` 的合法值。实例挂起不等于所有工作项取消，或签剩余任务被取消也不等于流程终止。
+
+### 2.2 四类 ID
+
+| ID | 示例 | 关联规则 |
+| --- | --- | --- |
+| BPMN 元素 | `Task_Review` | 来自实例 XML；`elementId` 与 Transition 端点引用它 |
+| 工作项 | `task:t-review-1` | 一次执行；Action `activityId`、Transition `sourceActivityId` 引用它 |
+| 节点到达 | `visit-review-1` | 同一节点本次到达；会签工作项共享，重入创建新 ID |
+| 操作 / 跳转 / 连线经过 | `op-approve-1` / `move-1` / `ev-1` | 每条事实稳定且唯一，不能在轮询时重新随机生成 |
+
+`visitId` 建议在实例内唯一，并始终与同一个 BPMN 节点关联。`executionId`、task ID、时间戳或数组序号都不能普遍替代会签访问 ID；宿主必须保存或可靠关联每次到达及多实例作用域。没有可信关联时，应报告数据缺口，而不是合并同节点的全部历史。
+
+会签使用 `approvalMode: 'all'`，或签使用 `'any'`，单人使用 `'single'`。多人参与不会自动变成会签。`multiInstanceMode` 区分 `parallel / sequential`，`totalInstances` 是本轮总人数，`requiredInstances` 是业务完成门槛。Nova 展示这些事实，不在达到门槛时替引擎结束或取消任务；或签完成后应传入其余工作项的真实终态。
+
+### 2.3 操作、回退与历史
+
+`actions` 支持 `submit / approve / reject / return / add-sign / transfer / delegate / withdraw / comment / skip` 及宿主自定义类型。转办可以只有操作记录，不需要制造一条 BPMN 边。`actor` 是实际操作者，不一定是任务最终的 `assignee`。
+
+驳回路径由 `transitions` 表达，`actionId` 关联同一次业务操作，`sourceActivityId` 精确关联工作项。仅增加 `type: 'reject'` 的 Action 不会自动画出回退路径。结束的驳回工作项仍可为 `completed`；配套 reject Transition 会派生“已驳回”展示。
+
+当前 `invalidatedActivityIds` 名称保留兼容，但其值是 **BPMN 节点 ID**，例如 `['Task_Review']`，不是 `['task:t-review-1']`。`invalidatedEdgeIds` 同样是 BPMN 连线 ID。两者应共同明确给出；任一数组存在就属于显式范围，不再自动补推另一项。缺少范围时仅对唯一、同作用域的已访问路径做兼容推断，不能覆盖所有并行、跨作用域和回环情况。
+
+失效只影响当前路径展示，不删除历史，也不修改 XML。再次经过的边应新增带更晚时间的 `edgeVisits`，旧记录继续保留；宿主确认目标本轮处理完成后把回退 Transition 更新为 `resolved`，可同时提供 `resolvedAt` / `resolvedByActivityId`。操作日志本身不随状态更新而被改写。
+
+旧 `ActivityInstance.comment/outcome` 和 `RuntimeTransition.comment` 会生成兼容动作。新接入优先显式 `actions`：填入 `activityId` 可抑制同工作项的兼容动作，填入 Transition `actionId` 可避免同次跳转再次生成动作。`normalizeRuntime()` 只是兼容归一化，不是业务事实校验器。
+
+### 2.4 公共类型与已发布版本兼容
+
+自 `0.3.5-preview` 起，Vue/React 根入口显式重导出以下类型，均为 `export type`，没有同名 JavaScript 值：
+
+- `ProcessInstanceSnapshot`、`ActivityInstance`、`ActivityStatus`、`RuntimeParticipant`。
+- `RuntimeApprovalAction`、`RuntimeApprovalActionType`、`RuntimeApprovalContent`、`RuntimeApprovalContentBlock`、`RuntimeAssetRef`。
+- `RuntimeTransition`、`RuntimeEdgeVisit`。
+- `RuntimeTraceClickEvent`、`RuntimeAssetResolver`、`RuntimeAssetPurpose`。
+
+已安装包尚未提供这些具名出口时，可从现有 Props 推导，不增加依赖：
+
+```ts title="runtime-compat.ts"
+import type { BpmnStudioProps } from '@bpmn-nova/vue'
+
+export type ProcessInstanceSnapshot = NonNullable<BpmnStudioProps['runtime']>
+export type ActivityInstance = ProcessInstanceSnapshot['activities'][number]
+export type RuntimeApprovalAction = NonNullable<ProcessInstanceSnapshot['actions']>[number]
+export type RuntimeTransition = NonNullable<ProcessInstanceSnapshot['transitions']>[number]
+export type RuntimeEdgeVisit = NonNullable<ProcessInstanceSnapshot['edgeVisits']>[number]
+```
+
+React 使用相同写法并改为 React 包。其他结构可继续按属性推导；不要从源码相对路径或传递依赖导入。下文 Studio `config` 示例要求包含 Config 功能的构建；旧构建沿用同义的顶层 Viewer 配置，不影响 Snapshot 格式。
+
+## 3. Flowable / Activiti 映射参考
+
+### 3.1 官方资料与边界
+
+资料核对日期：2026-09-05。字段表依据 [Flowable HistoricActivityInstance（页面标识 8.0.0）](https://www.flowable.com/open-source/docs/all-javadocs/org/flowable/engine/history/HistoricActivityInstance.html) 与 [Activiti 6.0.0 HistoricActivityInstance](https://www.activiti.org/javadocs/6.latest/org/activiti/engine/history/HistoricActivityInstance.html)。Flowable 链接是滚动文档；宿主使用其他版本时应对照实际依赖的 API，本文不声明 Activiti 7/Cloud 或所有引擎版本已经联调通过。
+
+| 引擎活动字段 | 宿主映射 |
+| --- | --- |
+| `getProcessInstanceId()` / `getProcessDefinitionId()` | 校验实例归属及绑定的定义版本 |
+| `getActivityId()` | Nova `elementId`，来自 BPMN 定义 |
+| `getId()` | 历史活动实例 ID；非人工工作项可据此建立稳定记录 ID |
+| `getTaskId()` | 关联人工任务；用同一 task ID 合并任务与活动两种视角 |
+| `getExecutionId()` | 执行关联线索，不默认当作 `visitId` |
+| `getStartTime()` / `getEndTime()` | 转换为带时区的开始和结束时间 |
+| `getAssignee()` | 处理人标识；显示名称另向宿主人员服务解析 |
+| `getDeleteReason()` | 状态判断的输入之一，不通用等价于“驳回” |
+
+Flowable 历史记录包含进行中与已结束实例，因此实时任务和历史查询结果应关联去重，而不是直接拼接。历史级别影响可获得的记录：`none` 没有可用历史；`activity` 保留活动级信息；`audit` / `full` 提供更丰富记录。历史清理也可能移除旧记录。接入前应记录宿主实际配置和保留策略，而不是只检查接口返回成功。[Flowable History](https://www.flowable.com/open-source/docs/bpmn/ch10-History)、[Activiti 6 History](https://www.activiti.org/userguide/6.latest/#history)
+
+上述字段并不构成完整业务审计契约。`approve/reject`、回退目标、会签访问身份、完成门槛及可靠的连线经过记录必须结合宿主已有日志或引擎扩展。数据采集不足时，在宿主页面说明“轨迹不完整”；即使历史级别为 `full`，也不要把自定义审批业务含义视为自动可得。
+
+### 3.2 宿主 DTO 与纯转换
+
+以下 `runtime-adapter.ts` 是可复制的**宿主参考代码**，不是 Nova 导出，也不是某个引擎的 REST Schema。接口边界先完成鉴权、分页、原始 JSON 校验、人员名称解析及一致性读取，再交给此函数。`revision` 是宿主为同一工作项提供的单调版本，不能用数组位置生成。
+
+人工任务统一使用 `{ kind: 'task', id: taskId }`，活动历史中的人工任务也使用相同键；非任务活动使用 `{ kind: 'activity', id: historicActivityId }`。不要同时把同一人工任务映射成一个 task 记录和一个 activity 记录。若历史暂时没有对应 task ID，应先完成关联或报告缺失，不能换一个新 ID 填入。
+
+```ts title="runtime-adapter.ts"
+import type {
+  ActivityInstance, ProcessInstanceSnapshot, RuntimeApprovalAction,
+  RuntimeEdgeVisit, RuntimeTransition,
+} from '@bpmn-nova/vue'
+
+export interface WorkItemKey { kind: 'task' | 'activity'; id: string }
+export interface HostActivity {
+  key: WorkItemKey
+  revision: number
+  nodeId: string
+  visitId: string
+  state: ActivityInstance['status']
+  startedAt: string
+  endedAt?: string
+  participant?: ActivityInstance['participant']
+  approval?: Pick<ActivityInstance,
+    'approvalMode' | 'multiInstanceId' | 'multiInstanceMode' |
+    'totalInstances' | 'requiredInstances'>
+}
+export interface HostOperation extends Omit<RuntimeApprovalAction, 'activityId'> {
+  workItem: WorkItemKey
+}
+export interface HostMovement extends Omit<RuntimeTransition,
+  'sourceActivityId' | 'invalidatedActivityIds' | 'actionId'> {
+  sourceWorkItem: WorkItemKey
+  actionId: string
+  invalidatedElementIds: string[]
+}
+export interface HostTraceSource {
+  processInstanceId: string
+  status: ProcessInstanceSnapshot['status']
+  historicalActivities: HostActivity[]
+  currentActivities: HostActivity[]
+  operations: HostOperation[]
+  movements: HostMovement[]
+  visitedEdgeIds: string[]
+  edgeVisits: RuntimeEdgeVisit[]
+  coverage: { activities: 'complete' | 'partial'; actions: 'complete' | 'partial'; edges: 'complete' | 'partial' }
+}
+export interface ModelIds {
+  nodes: ReadonlySet<string>
+  edges: ReadonlySet<string>
+}
+
+export function workItemId(key: WorkItemKey): string {
+  if (!key.id.trim()) throw new Error('缺少工作项来源 ID')
+  return `${key.kind}:${key.id}`
+}
+
+export function toNovaRuntime(source: HostTraceSource, ids: ModelIds): ProcessInstanceSnapshot {
+  const requireId = (set: ReadonlySet<string>, id: string, field: string) => {
+    if (!set.has(id)) throw new Error(`${field} 无法关联: ${id}`)
+  }
+  const requireTime = (time: string) => {
+    if (!/T.*(?:Z|[+-]\d{2}:\d{2})$/.test(time) || !Number.isFinite(Date.parse(time))) {
+      throw new Error(`需要带时区的 ISO 时间: ${time}`)
+    }
+  }
+  if (!source.processInstanceId.trim()) throw new Error('缺少 processInstanceId')
+  const records = new Map<string, { revision: number; activity: ActivityInstance }>()
+  for (const row of [...source.historicalActivities, ...source.currentActivities]) {
+    requireId(ids.nodes, row.nodeId, 'nodeId')
+    if (!row.visitId.trim()) throw new Error(`缺少 visitId: ${row.nodeId}`)
+    if (!Number.isSafeInteger(row.revision) || row.revision < 0) throw new Error('无效工作项 revision')
+    requireTime(row.startedAt)
+    if (row.endedAt) {
+      requireTime(row.endedAt)
+      if (Date.parse(row.endedAt) < Date.parse(row.startedAt)) throw new Error('工作项结束早于开始')
+    }
+    const activity: ActivityInstance = {
+      id: workItemId(row.key), elementId: row.nodeId, visitId: row.visitId,
+      status: row.state, startTime: row.startedAt, endTime: row.endedAt,
+      participant: row.participant ? {
+        id: row.participant.id, name: row.participant.name, avatarUrl: row.participant.avatarUrl,
+      } : undefined,
+      approvalMode: row.approval?.approvalMode, multiInstanceId: row.approval?.multiInstanceId,
+      multiInstanceMode: row.approval?.multiInstanceMode,
+      totalInstances: row.approval?.totalInstances, requiredInstances: row.approval?.requiredInstances,
+    }
+    const previous = records.get(activity.id)
+    if (previous && (previous.activity.elementId !== activity.elementId || previous.activity.visitId !== activity.visitId)) {
+      throw new Error(`工作项身份冲突: ${activity.id}`)
+    }
+    if (previous && previous.revision === row.revision && JSON.stringify(previous.activity) !== JSON.stringify(activity)) {
+      throw new Error(`相同 revision 的记录冲突: ${activity.id}`)
+    }
+    if (!previous || row.revision > previous.revision) records.set(activity.id, { revision: row.revision, activity })
+  }
+  const activities = [...records.values()].map(({ activity }) => activity)
+    .sort((a, b) => Date.parse(a.startTime!) - Date.parse(b.startTime!) || a.id.localeCompare(b.id))
+  const visits = new Map<string, string>()
+  for (const activity of activities) {
+    const nodeId = visits.get(activity.visitId!)
+    if (nodeId && nodeId !== activity.elementId) throw new Error(`visitId 跨节点复用: ${activity.visitId}`)
+    visits.set(activity.visitId!, activity.elementId)
+  }
+  const actionIds = new Set<string>()
+  const actions: RuntimeApprovalAction[] = source.operations.map(({ workItem, ...operation }) => {
+    if (!operation.id.trim() || actionIds.has(operation.id)) throw new Error(`操作 ID 缺失或重复: ${operation.id}`)
+    actionIds.add(operation.id)
+    requireTime(operation.occurredAt)
+    const record = records.get(workItemId(workItem))?.activity
+    if (!record || record.elementId !== operation.elementId || record.visitId !== operation.visitId) {
+      throw new Error(`操作与工作项不匹配: ${operation.id}`)
+    }
+    if (operation.targetElementId) requireId(ids.nodes, operation.targetElementId, 'targetElementId')
+    return { ...structuredClone(operation), activityId: record.id }
+  }).sort((a, b) => Date.parse(a.occurredAt) - Date.parse(b.occurredAt) || a.id.localeCompare(b.id))
+  const movementIds = new Set<string>()
+  const transitions: RuntimeTransition[] = source.movements.map(({ sourceWorkItem, invalidatedElementIds, ...movement }) => {
+    if (!movement.id.trim() || movementIds.has(movement.id)) throw new Error(`跳转 ID 缺失或重复: ${movement.id}`)
+    movementIds.add(movement.id)
+    const record = records.get(workItemId(sourceWorkItem))?.activity
+    const action = actions.find((item) => item.id === movement.actionId)
+    if (!record || record.elementId !== movement.sourceElementId || !action || action.activityId !== record.id
+      || action.type !== movement.type || action.targetElementId !== movement.targetElementId) {
+      throw new Error(`跳转与操作不匹配: ${movement.id}`)
+    }
+    if (movement.occurredAt) requireTime(movement.occurredAt)
+    if (movement.resolvedAt) requireTime(movement.resolvedAt)
+    if (movement.resolvedByActivityId && !records.has(movement.resolvedByActivityId)) throw new Error('跳转完成工作项不存在')
+    invalidatedElementIds.forEach((id) => requireId(ids.nodes, id, 'invalidatedElementIds'))
+    ;(movement.invalidatedEdgeIds ?? []).forEach((id) => requireId(ids.edges, id, 'invalidatedEdgeIds'))
+    return { ...structuredClone(movement), sourceActivityId: record.id, invalidatedActivityIds: [...invalidatedElementIds] }
+  })
+  const edgeVisitIds = new Set<string>()
+  for (const visit of source.edgeVisits) {
+    if (!visit.id.trim() || edgeVisitIds.has(visit.id)) throw new Error(`连线经过 ID 缺失或重复: ${visit.id}`)
+    edgeVisitIds.add(visit.id)
+    requireId(ids.edges, visit.edgeId, 'edgeId')
+    if (visit.occurredAt) requireTime(visit.occurredAt)
+  }
+  const visitedEdges = [...new Set([...source.visitedEdgeIds, ...source.edgeVisits.map((visit) => visit.edgeId)])]
+  visitedEdges.forEach((id) => requireId(ids.edges, id, 'visitedEdges'))
+  return {
+    processInstanceId: source.processInstanceId, status: source.status, activities,
+    actions, transitions, visitedEdges, edgeVisits: structuredClone(source.edgeVisits),
+  }
+}
+```
+
+此函数只去重同一工作项的不同读取视角，不合并不同工作项或不同访问轮次。相同版本冲突直接报错；不会用旧活动记录覆盖较新任务记录。它是已校验 DTO 的教学转换层，不是通用 JSON Schema 校验器，也不替宿主推断审批状态、轮次或跳转范围。
+
+参考 DTO 针对本文的工作项审批场景，要求每个操作都关联已采集工作项。公共 Action 接口的 `activityId` 实际可选；宿主存在只有节点与访问身份的操作时，应保留真实 `elementId / visitId` 并按该接口扩展转换层，而不是伪造工作项来满足本例。
+
+`coverage` 是宿主页面的完整性提示，不属于 Nova Snapshot。示例中的 `ModelIds` 从同版本解析模型生成：节点集合取 `model.nodes[].id`，连线集合取 `model.edges[].id`。身份不匹配时应保留上次成功显示的数据并提示错误，而不是改 XML ID 来迁就日志。
+
+## 4. 同一流程的完整业务场景
+
+以下 `runtime-scenarios.ts` 与第 3 节转换器一起使用，没有省略的输入数组。公共事实只定义一次，各场景对象独立组装，`scenarioSnapshots` 保存每份输入对应的完整 Snapshot；`JSON.stringify(scenarioSnapshots.reject.runtime, null, 2)` 可查看驳回场景的完整输出。
+
+这些是教学数据，不是 Playground 的真实接口响应。“单人完成”“或签完成”是不同实例分支；“驳回 → 重新提交”则是同一实例的后续快照。会签/或签示例只说明相同可视节点如何接收不同工作项，实际引擎模型及宿主审批策略必须与事实一致。
+
+```ts title="runtime-scenarios.ts"
+import type { RuntimeEdgeVisit } from '@bpmn-nova/vue'
+import { toNovaRuntime } from './runtime-adapter'
+import type { HostActivity, HostOperation, HostTraceSource, ModelIds } from './runtime-adapter'
+
+// 教学 XML 的身份集合。真实接入从实例对应的解析模型生成。
+const ids: ModelIds = {
+  nodes: new Set(['StartEvent_1', 'Task_Submit', 'Task_Review', 'EndEvent_1']),
+  edges: new Set(['Flow_Start_Submit', 'Flow_Submit_Review', 'Flow_Review_End']),
+}
+const applicant = { id: 'u-applicant', name: '申请人' }
+const manager = { id: 'u-li', name: '李经理' }
+const start: HostActivity = {
+  key: { kind: 'activity', id: 'h-start' }, revision: 1,
+  nodeId: 'StartEvent_1', visitId: 'visit-start-1', state: 'completed',
+  startedAt: '2026-09-05T09:00:00+08:00', endedAt: '2026-09-05T09:00:00+08:00',
+}
+const submit: HostActivity = {
+  key: { kind: 'task', id: 't-submit-1' }, revision: 2,
+  nodeId: 'Task_Submit', visitId: 'visit-submit-1', state: 'completed', participant: applicant,
+  startedAt: '2026-09-05T09:00:01+08:00', endedAt: '2026-09-05T09:05:00+08:00',
+}
+const review: HostActivity = {
+  key: { kind: 'task', id: 't-review-1' }, revision: 2,
+  nodeId: 'Task_Review', visitId: 'visit-review-1', state: 'active', participant: manager,
+  startedAt: '2026-09-05T09:05:01+08:00', approval: { approvalMode: 'single' },
+}
+const submitAction: HostOperation = {
+  id: 'op-submit-1', type: 'submit', workItem: submit.key,
+  elementId: submit.nodeId, visitId: submit.visitId, actor: applicant,
+  occurredAt: '2026-09-05T09:05:00+08:00', content: { plainText: '提交申请。' },
+}
+const beforeReview: RuntimeEdgeVisit[] = [
+  { id: 'ev-1', edgeId: 'Flow_Start_Submit', occurredAt: '2026-09-05T09:00:01+08:00', status: 'effective' },
+  { id: 'ev-2', edgeId: 'Flow_Submit_Review', occurredAt: '2026-09-05T09:05:01+08:00', status: 'effective' },
+]
+
+export const singleInput: HostTraceSource = {
+  processInstanceId: 'PI-1001', status: 'running',
+  historicalActivities: [start, submit, { ...review, revision: 1, participant: undefined }],
+  currentActivities: [review], operations: [submitAction], movements: [],
+  visitedEdgeIds: ['Flow_Start_Submit', 'Flow_Submit_Review'], edgeVisits: beforeReview,
+  coverage: { activities: 'complete', actions: 'complete', edges: 'complete' },
+}
+export const waitingInput: HostTraceSource = {
+  ...singleInput, processInstanceId: 'PI-WAITING',
+  currentActivities: [{ ...review, revision: 3, participant: undefined }],
+}
+
+const reviewed: HostActivity = {
+  ...review, revision: 3, state: 'completed', endedAt: '2026-09-05T09:10:00+08:00',
+}
+const approveAction: HostOperation = {
+  id: 'op-approve-1', type: 'approve', workItem: review.key,
+  elementId: review.nodeId, visitId: review.visitId, actor: manager,
+  occurredAt: '2026-09-05T09:10:00+08:00', content: { plainText: '同意。' },
+}
+const end: HostActivity = {
+  key: { kind: 'activity', id: 'h-end' }, revision: 1,
+  nodeId: 'EndEvent_1', visitId: 'visit-end-1', state: 'completed',
+  startedAt: '2026-09-05T09:10:01+08:00', endedAt: '2026-09-05T09:10:01+08:00',
+}
+const toEnd: RuntimeEdgeVisit = {
+  id: 'ev-end-1', edgeId: 'Flow_Review_End', occurredAt: '2026-09-05T09:10:01+08:00', status: 'effective',
+}
+export const completedInput: HostTraceSource = {
+  ...singleInput, processInstanceId: 'PI-COMPLETED', status: 'completed',
+  historicalActivities: [start, submit, reviewed, end], currentActivities: [],
+  operations: [submitAction, approveAction], edgeVisits: [...beforeReview, toEnd],
+}
+
+const allApproval: NonNullable<HostActivity['approval']> = {
+  approvalMode: 'all', multiInstanceMode: 'parallel', multiInstanceId: 'mi-review-1',
+  totalInstances: 3, requiredInstances: 3,
+}
+const reviewerTwo: HostActivity = {
+  ...review, key: { kind: 'task', id: 't-review-2' }, participant: { id: 'u-wang', name: '王经理' }, approval: allApproval,
+}
+const reviewerThree: HostActivity = {
+  ...review, key: { kind: 'task', id: 't-review-3' }, participant: { id: 'u-zhao', name: '赵经理' }, approval: allApproval,
+}
+export const countersignInput: HostTraceSource = {
+  ...singleInput, processInstanceId: 'PI-ALL',
+  historicalActivities: [start, submit, { ...reviewed, approval: allApproval }],
+  currentActivities: [reviewerTwo, reviewerThree], operations: [submitAction, approveAction],
+}
+const anyApproval: NonNullable<HostActivity['approval']> = { ...allApproval, approvalMode: 'any', requiredInstances: 1 }
+export const anySignInput: HostTraceSource = {
+  ...singleInput, processInstanceId: 'PI-ANY', status: 'completed',
+  historicalActivities: [
+    start, submit, { ...reviewed, approval: anyApproval },
+    { ...reviewerTwo, revision: 3, state: 'cancelled', endedAt: '2026-09-05T09:10:00+08:00', approval: anyApproval },
+    { ...reviewerThree, revision: 3, state: 'cancelled', endedAt: '2026-09-05T09:10:00+08:00', approval: anyApproval },
+    end,
+  ],
+  currentActivities: [], operations: [submitAction, approveAction], edgeVisits: [...beforeReview, toEnd],
+}
+
+const submitAgain: HostActivity = {
+  ...submit, key: { kind: 'task', id: 't-submit-2' }, revision: 1,
+  visitId: 'visit-submit-2', state: 'active', startedAt: '2026-09-05T09:10:01+08:00', endedAt: undefined,
+}
+const rejectAction: HostOperation = {
+  id: 'op-reject-1', type: 'reject', workItem: review.key,
+  elementId: review.nodeId, visitId: review.visitId, actor: manager,
+  targetElementId: 'Task_Submit', occurredAt: '2026-09-05T09:10:00+08:00',
+  content: { plainText: '请补充材料后重新提交。' },
+}
+export const rejectInput: HostTraceSource = {
+  ...singleInput,
+  historicalActivities: [start, submit, reviewed], currentActivities: [submitAgain],
+  operations: [submitAction, rejectAction],
+  movements: [{
+    id: 'move-reject-1', type: 'reject', actionId: rejectAction.id, sourceWorkItem: review.key,
+    sourceElementId: 'Task_Review', targetElementId: 'Task_Submit', operator: manager.name,
+    occurredAt: '2026-09-05T09:10:00+08:00', state: 'active',
+    invalidatedElementIds: ['Task_Review'], invalidatedEdgeIds: ['Flow_Submit_Review'],
+  }],
+  edgeVisits: beforeReview.map((visit) => visit.id === 'ev-2' ? { ...visit, status: 'superseded' } : visit),
+}
+const resubmitted: HostActivity = {
+  ...submitAgain, revision: 2, state: 'completed', endedAt: '2026-09-05T09:15:00+08:00',
+}
+const reviewAgain: HostActivity = {
+  ...review, key: { kind: 'task', id: 't-review-round-2' }, revision: 1,
+  visitId: 'visit-review-2', startedAt: '2026-09-05T09:15:01+08:00',
+}
+export const reentryInput: HostTraceSource = {
+  ...rejectInput,
+  historicalActivities: [start, submit, reviewed, resubmitted], currentActivities: [reviewAgain],
+  operations: [submitAction, rejectAction, {
+    ...submitAction, id: 'op-submit-2', workItem: submitAgain.key, visitId: submitAgain.visitId,
+    occurredAt: '2026-09-05T09:15:00+08:00', content: { plainText: '已补充材料，重新提交。' },
+  }],
+  movements: rejectInput.movements.map((movement) => ({
+    ...movement, state: 'resolved', resolvedAt: '2026-09-05T09:15:00+08:00', resolvedByActivityId: 'task:t-submit-2',
+  })),
+  edgeVisits: [...rejectInput.edgeVisits, {
+    id: 'ev-3', edgeId: 'Flow_Submit_Review', occurredAt: '2026-09-05T09:15:01+08:00', status: 'effective',
+  }],
+}
+
+export const scenarioSnapshots = {
+  single: { input: singleInput, runtime: toNovaRuntime(singleInput, ids) },
+  waiting: { input: waitingInput, runtime: toNovaRuntime(waitingInput, ids) },
+  completed: { input: completedInput, runtime: toNovaRuntime(completedInput, ids) },
+  countersign: { input: countersignInput, runtime: toNovaRuntime(countersignInput, ids) },
+  anySign: { input: anySignInput, runtime: toNovaRuntime(anySignInput, ids) },
+  reject: { input: rejectInput, runtime: toNovaRuntime(rejectInput, ids) },
+  reentry: { input: reentryInput, runtime: toNovaRuntime(reentryInput, ids) },
+}
+```
+
+| 输入 → 完整输出 | 预期标准 Presentation 与默认展示 |
+| --- | --- |
+| `singleInput` → `scenarioSnapshots.single.runtime` | 3 条活动，而非 4 条；审核只有一个工作项，显示“处理中”、李经理 |
+| `waitingInput` → `scenarioSnapshots.waiting.runtime` | 审核 active，无处理人；本示例无候选配置，显示“待分配审批人” |
+| `completedInput` → `scenarioSnapshots.completed.runtime` | 流程 completed，审核已完成且有“通过”动作；结束边已经过 |
+| `countersignInput` → `scenarioSnapshots.countersign.runtime` | 审核同一 visit 中 3 个工作项，1 completed、2 active，显示“会签 1/3” |
+| `anySignInput` → `scenarioSnapshots.anySign.runtime` | 1 completed、2 cancelled，显示“或签 1/3”，门槛为 1，流程已完成；不为被取消工作项制造通过动作 |
+| `rejectInput` → `scenarioSnapshots.reject.runtime` | 提交节点第 2 次到达并 active，显示“重新审批”；审核保留驳回事实，旧审核路径失效，回退关系可见 |
+| `reentryInput` → `scenarioSnapshots.reentry.runtime` | 审核第 2 次到达显示处理中；旧驳回仍在历史内但已 resolved，回退线隐藏，新的 `ev-3` 恢复有效线路 |
+
+`approval` 和 `compact` 会重排、聚合或过滤图元，展示不保证与 `standard` 的位置相同。普通开始/结束事件默认在完整 BPMN 可见，在实际路径/时间线默认隐藏。需要显示时设置 `runtimeTraceOptions.showStartMilestone / showEndMilestone`。
+
+默认投影可能追加唯一可预测的后续人工节点；预测不是已发生事实，也不应写回 `activities` 或审批日志。需要严格只读历史时配置 `runtimeTraceOptions.includePredicted: false`；Studio 中放在 `config.viewer.runtimeTraceOptions`。
+
+## 5. 加载、更新和交互
+
+### 5.1 宿主加载契约
+
+**自 `0.3.5-preview` 起的侧栏行为**：Studio `instance` 默认隐藏左右区域，右侧没有展开按钮，也不占宽度。下方示例仍显式写 `regions: { left: 'hidden', right: 'hidden' }`，可兼容旧版；如果要显示宿主业务详情，改为 `config.ui.regions.right: 'default'` 并使用 Vue `#right`、React `right` 或 Core `slots.right`。右侧 Slot 不会自动覆盖 `hidden`。
+
+框架 Header/Right Context 的 `panelSelection` 和 Core `getPanelSelection()` / `subscribePanelSelection()` 提供当前选择、元素及轨迹上下文；Instance 点击不改变设计选择。面板可用默认 Flex 固定头尾/中间滚动，也可设为 Scroll 整体滚动。隐藏或收起右侧不关闭 `trace-click`、内置详情或附件交互，详见[侧栏指南](CUSTOMIZATION.md#侧栏布局与平滑折叠)。独立 `BpmnViewer` 不拥有 Shell 侧栏，不传入 `config.ui`。
+
+下面的 `trace-contract.ts` 只定义宿主函数的返回约定，不创建 Nova HTTP 端点。宿主实现 `loadTrace` 时应完成读取、原始 JSON 校验、`toNovaRuntime()` 转换及完整性说明；返回的 XML 和 Runtime 必须属于同一实例的定义版本。历史不可用时由宿主报告错误或明确的 partial 状态，不能把查询失败转成“没有经过任何节点”。
+
+```ts title="trace-contract.ts"
+import type { ProcessInstanceSnapshot } from '@bpmn-nova/vue'
+import type { HostTraceSource } from './runtime-adapter'
+
+export interface TraceDocument {
+  processDefinitionId: string
+  xml: string
+  runtime: ProcessInstanceSnapshot
+  coverage: HostTraceSource['coverage']
+}
+export type LoadTrace = (instanceId: string, signal: AbortSignal) => Promise<TraceDocument>
+
+export function checkTraceDocument(next: TraceDocument, instanceId: string, previous: TraceDocument | null): void {
+  if (next.runtime.processInstanceId !== instanceId) throw new Error('审批轨迹响应的实例 ID 不匹配')
+  if (!next.processDefinitionId || !next.xml.trim()) throw new Error('审批轨迹缺少定义版本或 XML')
+  if (previous?.processDefinitionId === next.processDefinitionId && previous.xml !== next.xml) {
+    throw new Error('同一定义版本返回了不同 XML，请检查定义服务')
+  }
+}
+```
+
+下面的刷新都是替换 Snapshot 对象，不是往原数组里 `push()`。Vue watcher 和 React effect 依赖 Prop 引用；闭包数据的定义态 `refreshPresentation()` 不能替代 Runtime 数据更新。
+
+### 5.2 Vue：Studio 实例模式，防止旧请求覆盖
+
+`ApprovalTrace.vue` 接收宿主的 `instanceId` 和 `loadTrace`，通过 `refresh()` 暴露主动刷新入口。首次加载显示占位，同实例刷新保留当前组件；切换实例先移除旧实例内容，避免旧数据冒充新实例。宿主函数变化时保持同样的取消语义。
+
+```vue title="ApprovalTrace.vue"
+<script setup lang="ts">
+import { ref, shallowRef, watch } from 'vue'
+import { BpmnStudio } from '@bpmn-nova/vue'
+import type { BpmnStudioConfig, RuntimeTraceClickEvent } from '@bpmn-nova/vue'
+import '@bpmn-nova/vue/styles.css'
+import { checkTraceDocument } from './trace-contract'
+import type { LoadTrace, TraceDocument } from './trace-contract'
+
+const props = defineProps<{ instanceId: string | null; loadTrace: LoadTrace }>()
+const emit = defineEmits<{ 'trace-click': [event: RuntimeTraceClickEvent] }>()
+const document = shallowRef<TraceDocument | null>(null)
+const loading = ref(false)
+const error = ref('')
+const refreshKey = ref(0)
+const config: BpmnStudioConfig = {
+  ui: { regions: { left: 'hidden', right: 'hidden' } },
+  viewer: { runtimeDetails: { autoOpen: false }, runtimeTraceOptions: { includePredicted: false } },
+}
+
+watch(() => [props.instanceId, props.loadTrace, refreshKey.value] as const, async ([id, load], _previous, onCleanup) => {
+  const controller = new AbortController()
+  onCleanup(() => controller.abort())
+  if (document.value?.runtime.processInstanceId !== id) document.value = null
+  error.value = ''
+  loading.value = Boolean(id)
+  if (!id) return
+  try {
+    const next = await load(id, controller.signal)
+    if (controller.signal.aborted) return
+    checkTraceDocument(next, id, document.value)
+    document.value = next
+  } catch (cause) {
+    if (!controller.signal.aborted) error.value = cause instanceof Error ? cause.message : '轨迹加载失败'
+  } finally {
+    if (!controller.signal.aborted) loading.value = false
+  }
+}, { immediate: true })
+
+defineExpose({ refresh: () => { refreshKey.value += 1 } })
+</script>
+
+<template>
+  <section>
+    <p v-if="!instanceId">流程尚未发起</p>
+    <p v-else-if="loading" role="status">{{ document ? '正在刷新轨迹…' : '正在加载轨迹…' }}</p>
+    <p v-if="error" role="alert">{{ error }}</p>
+    <p v-if="document && Object.values(document.coverage).includes('partial')">轨迹记录不完整，请结合业务审计查看。</p>
+    <div v-if="document" style="height: 640px; min-height: 320px">
+      <BpmnStudio :xml="document.xml" :runtime="document.runtime" :config="config"
+        engine="flowable" mode="instance" :allowed-modes="['instance']" projection="approval"
+        @trace-click="emit('trace-click', $event)" />
+    </div>
+  </section>
+</template>
+```
+
+这里禁用了内置详情自动打开，宿主监听 `trace-click` 自行展示。需要 Nova 默认详情时设 `config.viewer.runtimeDetails.autoOpen: true`，宿主事件只做观察。卸载时 Vue 自动清理 watcher 并取消当前请求，适配组件负责销毁自己创建的实例。
+
+### 5.3 React：独立 Viewer 与 Studio 选择
+
+`ApprovalTrace.tsx` 使用相同的宿主加载契约。`loadTrace` 应由宿主以稳定函数引用传入；`refreshKey` 变化代表一次新刷新，不应作为组件 React `key` 使用。
+
+```tsx title="ApprovalTrace.tsx"
+import { useEffect, useRef, useState } from 'react'
+import { BpmnStudio, BpmnViewer } from '@bpmn-nova/react'
+import type { BpmnStudioConfig, RuntimeTraceClickEvent } from '@bpmn-nova/react'
+import '@bpmn-nova/react/styles.css'
+import { checkTraceDocument } from './trace-contract'
+import type { LoadTrace, TraceDocument } from './trace-contract'
+
+const studioConfig: BpmnStudioConfig = {
+  ui: { regions: { left: 'hidden', right: 'hidden' } },
+  viewer: { runtimeDetails: { autoOpen: false }, runtimeTraceOptions: { includePredicted: false } },
+}
+const details = { autoOpen: false }
+const traceOptions = { includePredicted: false }
+
+export function ApprovalTrace({ instanceId, loadTrace, refreshKey = 0, useStudio = false, onTraceClick }: {
+  instanceId: string | null
+  loadTrace: LoadTrace
+  refreshKey?: number
+  useStudio?: boolean
+  onTraceClick?: (event: RuntimeTraceClickEvent) => void
+}) {
+  const [document, setDocument] = useState<TraceDocument | null>(null)
+  const lastAccepted = useRef<TraceDocument | null>(null)
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState('')
+  useEffect(() => {
+    const controller = new AbortController()
+    if (lastAccepted.current?.runtime.processInstanceId !== instanceId) lastAccepted.current = null
+    setError('')
+    setLoading(Boolean(instanceId))
+    if (!instanceId) { setDocument(null); return () => controller.abort() }
+    void (async () => {
+      try {
+        const next = await loadTrace(instanceId, controller.signal)
+        if (controller.signal.aborted) return
+        checkTraceDocument(next, instanceId, lastAccepted.current)
+        lastAccepted.current = next
+        setDocument(next)
+      } catch (cause) {
+        if (!controller.signal.aborted) setError(cause instanceof Error ? cause.message : '轨迹加载失败')
+      } finally {
+        if (!controller.signal.aborted) setLoading(false)
+      }
+    })()
+    return () => controller.abort()
+  }, [instanceId, loadTrace, refreshKey])
+  // render 时即按实例身份过滤，避免新请求的 effect 执行前短暂显示旧实例。
+  const visible = document?.runtime.processInstanceId === instanceId ? document : null
+  return <section>
+    {!instanceId && <p>流程尚未发起</p>}
+    {loading && <p role="status">{visible ? '正在刷新轨迹…' : '正在加载轨迹…'}</p>}
+    {error && <p role="alert">{error}</p>}
+    {visible && Object.values(visible.coverage).includes('partial') && <p>轨迹记录不完整，请结合业务审计查看。</p>}
+    {visible && <div style={{ height: 640, minHeight: 320 }}>
+      {useStudio
+        ? <BpmnStudio xml={visible.xml} runtime={visible.runtime} config={studioConfig}
+            engine="flowable" mode="instance" allowedModes={['instance']} projection="approval" onTraceClick={onTraceClick} />
+        : <BpmnViewer xml={visible.xml} runtime={visible.runtime} engine="flowable" projection="approval"
+            runtimeDetails={details} runtimeTraceOptions={traceOptions} onTraceClick={onTraceClick} />}
+    </div>}
+  </section>
+}
+```
+
+`useStudio` 是本例宿主布局选择，不是 Nova Prop；运行中切换它会切换组件种类。普通刷新保持它不变，使用新 Runtime 对象更新既有组件。Vue 独立 Viewer 使用相同顶层 `runtime-details` / `runtime-trace-options` 配置；只有完整 Studio 使用 `config.viewer`。
+
+### 5.4 Core：显式生命周期与更新
+
+`core-trace.ts` 的两个工厂分别提供独立 Viewer 和完整 Studio。只在浏览器中调用，传入有高度的容器；调用方从宿主加载函数得到成功且未过期的 `TraceDocument` 后，再调用 `update()`。同实例、同定义的刷新只设置 Runtime；换实例或定义时才替换模型。
+
+```ts title="core-trace.ts"
+import { BpmnViewer, createStudioController, createStudioShell, importBpmn } from '@bpmn-nova/studio'
+import type { RuntimeTraceClickEvent } from '@bpmn-nova/studio'
+import '@bpmn-nova/studio/styles.css'
+import { checkTraceDocument } from './trace-contract'
+import type { TraceDocument } from './trace-contract'
+
+export function mountViewer(container: HTMLElement, initial: TraceDocument, onTraceClick: (event: RuntimeTraceClickEvent) => void) {
+  let current = initial
+  const viewer = new BpmnViewer({
+    container, model: importBpmn(initial.xml, 'flowable'), runtime: initial.runtime,
+    projection: 'approval', runtimeDetails: { autoOpen: false },
+    runtimeTraceOptions: { includePredicted: false }, onTraceClick,
+  })
+  return {
+    update(next: TraceDocument) {
+      checkTraceDocument(next, next.runtime.processInstanceId, current)
+      if (next.runtime.processInstanceId !== current.runtime.processInstanceId || next.processDefinitionId !== current.processDefinitionId) {
+        viewer.setModel(importBpmn(next.xml, 'flowable'))
+      }
+      viewer.setRuntime(next.runtime)
+      current = next
+    },
+    destroy: () => viewer.destroy(),
+  }
+}
+
+export function mountStudio(container: HTMLElement, initial: TraceDocument, onTraceClick: (event: RuntimeTraceClickEvent) => void) {
+  let current = initial
+  const studio = createStudioController({ model: importBpmn(initial.xml, 'flowable') })
+  const shell = createStudioShell({
+    container, studio, runtime: initial.runtime, mode: 'instance', allowedModes: ['instance'], projection: 'approval',
+    config: {
+      ui: { regions: { left: 'hidden', right: 'hidden' } },
+      viewer: { runtimeDetails: { autoOpen: false }, runtimeTraceOptions: { includePredicted: false } },
+    },
+    rendererOptions: { onTraceClick },
+  })
+  return {
+    update(next: TraceDocument) {
+      checkTraceDocument(next, next.runtime.processInstanceId, current)
+      if (next.runtime.processInstanceId !== current.runtime.processInstanceId || next.processDefinitionId !== current.processDefinitionId) {
+        studio.setModel(importBpmn(next.xml, 'flowable'))
+      }
+      shell.setRuntime(next.runtime)
+      current = next
+    },
+    destroy() { shell.destroy(); studio.destroy() },
+  }
+}
+```
+
+Core 的调用方仍须保存当前请求的实例 ID，并使用 `AbortController` 和过期响应检查，不能直接把任意请求结果传给 `update()`。切换实例和定义是有意的模型替换，不属于“同实例刷新不重导 XML”的保证。不要在每次刷新后自动 Fit，否则会覆盖用户正在阅读的位置。
+
+### 5.5 点击数据与内置详情
+
+`RuntimeTraceClickEvent.targetType` 区分 `node / edge / visit / transition`，并提供可选的原始 `elementId`、`visitId`、`traceItem`、`transition`、`presentation`，以及 `activityInstances`、`actions`、`runtime` 和实际 `projection`。
+
+所有分支应先判断 `targetType` 和可选字段，不能把每次点击都当成人工任务。在审批投影中使用事件的原始元素/访问关联，不从重排后的 DOM 属性反推业务任务 ID。事件是展示交互，不代表已经执行通过、驳回或保存；执行这些操作仍需要宿主校验权限并调用自己的业务 API。
+
+## 6. 意见、图片与附件
+
+以下 `approval-assets.ts` 为一次真实已记录的操作补充内容，并提供可注入 Viewer/Studio 的 Resolver 工厂。资源名称、MIME、大小来自宿主元数据；审批快照不存短期地址，用户头像也不要填入凭证或短期签名。
+
+```ts title="approval-assets.ts"
+import type { RuntimeApprovalContent, RuntimeAssetPurpose, RuntimeAssetResolver } from '@bpmn-nova/vue'
+import { completedInput } from './runtime-scenarios'
+import type { HostTraceSource } from './runtime-adapter'
+
+export const content: RuntimeApprovalContent = {
+  plainText: '同意，核验材料见附件。',
+  blocks: [
+    { type: 'paragraph', text: '同意，核验材料见附件。' },
+    { type: 'image', assetId: 'asset-photo', alt: '材料照片' },
+    { type: 'file', assetId: 'asset-checklist' },
+  ],
+  assets: [
+    { id: 'asset-photo', name: '材料照片.png', mediaType: 'image/png', width: 1200, height: 800 },
+    { id: 'asset-checklist', name: '核验清单.pdf', mediaType: 'application/pdf', size: 4096 },
+  ],
+}
+export const withAssetsInput: HostTraceSource = {
+  ...completedInput,
+  operations: completedInput.operations.map((operation) => operation.id === 'op-approve-1' ? { ...operation, content } : operation),
+}
+
+type ResolveAssetUrl = (input: {
+  assetId: string; actionId: string; purpose: RuntimeAssetPurpose; signal: AbortSignal
+}) => Promise<string | null>
+
+export function createAssetResolver(resolveAssetUrl: ResolveAssetUrl): RuntimeAssetResolver {
+  return (asset, { action, purpose, signal }) => resolveAssetUrl({
+    assetId: asset.id, actionId: action.id, purpose, signal,
+  })
+}
+```
+
+将 `withAssetsInput` 交给同一个 `toNovaRuntime()`，输出保留一个通过动作，内容包含一张图片和一个文件；不能为“补全附件展示”再新增一个重复审批操作。`resolveAssetUrl` 是宿主函数，按当前用户、实例/操作、资源及用途进行授权后返回资源地址，不返回业务 JSON 接口本身的地址。
+
+`purpose` 为 `thumbnail / preview / download / export`。宿主应把 `signal` 传递到实际网络请求并及时取消；返回相对或绝对 HTTP(S) 地址、宿主管理生命周期的 Blob URL，或者无权限/不存在时返回 `null`。资源不可用时 Nova 局部降级，不应让整条审批轨迹失败。需特别检查跨域图片、实际响应 MIME 与下载权限。
+
+原生内容块解释 `paragraph / image / file`，不执行 HTML 或 Markdown。默认图片预览和附件下载由 Viewer 处理；SVG 导出会按 `export` 用途获取图片并嵌入 Artifact，普通文件只保留元数据，不把临时地址写回 Snapshot。上传、存储、删除、审计和签名生命周期属于宿主业务。
+
+## 7. 接入验收与排错
+
+| 现象 | 优先检查与处理 |
+| --- | --- |
+| 画布空白 | 样式入口、浏览器生命周期、容器与父级实际高度；先区分布局问题与数据加载失败 |
+| 无实例 ID | 宿主展示“尚未发起”，等待真实实例；不创建虚假的 running Snapshot |
+| 请求中或请求失败 | 首次加载显示占位；同实例刷新失败保留上次成功数据并提示错误 |
+| 历史为空 | 检查历史级别、保留策略、分页及权限；与真正尚未到达的节点区分 |
+| 处理人或状态消失 | 检查定义版本、原始节点 ID、人员名称，以及实时/历史记录是否重复或相互覆盖 |
+| 会签人数不对 | 检查同轮 visitId、独立工作项 ID、显式 approvalMode、人数与门槛；同一工作项不能在两个来源各计一次 |
+| 驳回没有线路 | 检查 Transition、actionId、来源/目标、时间和失效范围；Action 本身不是线路 |
+| 重新审批仍显示旧状态 | 新到达是否获得新 visitId 与工作项 ID；新 edgeVisit 是否有更晚时间；回退是否正确 resolved |
+| 历史操作重复 | 检查显式 Action 的 activityId 和 Transition actionId，避免旧 comment/outcome 再次生成兼容动作 |
+| 出现未处理的后续节点 | 检查是否预测节点；严格历史视图设置 includePredicted: false |
+| 修改数组后没有刷新 | 替换 runtime 对象引用；Core 调用 setRuntime，不依赖定义态 refreshPresentation |
+| 意见附件不可用 | 核对 assetId、Resolver、用途授权、取消信号、跨域与真实资源响应 |
+
+完成接入应逐项确认：
+
+1. 安装入口与框架一致，公共类型及生产构建通过；`0.3.5-preview` 之前缺少具名 Runtime 类型出口的版本使用兼容推导。
+2. 真实 XML 的节点/连线 ID 与记录关联一致，刷新前后定义 XML 不变。
+3. 单人、等待、会签、或签、驳回及重入均符合宿主业务记录；结束任务没有被自动解释为通过。
+4. 同实例刷新不重建组件或重复导入 XML；切换实例取消旧请求，响应身份不匹配时拒绝覆盖。
+5. `standard / approval / compact` 使用相同事实；预测与真实记录可区分，历史失效记录仍可追溯。
+6. 内置详情与宿主详情按 autoOpen 策略工作，无重复事件订阅；Light/Dark 和窄屏下内容可读。
+7. 附件授权失败仅局部降级，卸载后请求与实例得到清理。
+
+这些是宿主集成验收项，不代表仅复制本文就已完成真实引擎联调。示例不替宿主创建业务接口、部署流程或运行审批事务。完整参数见[组件参数](COMPONENTS.md)、[公开 API](API.md)与[自定义指南](CUSTOMIZATION.md)；安装入口见 [AI 接入指南](AI-INTEGRATION.md)。
+
+
 <!-- SOURCE: docs/GETTING-STARTED.md -->
 
 # BPMN Nova 快速开始
 
-本文面向通过 NPM 集成 BPMN Nova 的应用开发者。版本 `0.3.4-preview` 要求现代浏览器；Node.js 18+ 用于构建、SSR 和开发工具。
+本文面向通过 NPM 集成 BPMN Nova 的应用开发者。版本 `0.3.5-preview` 要求现代浏览器；Node.js 18+ 用于构建、SSR 和开发工具。
 
 ## 1. 按语言与框架选择入口
 
@@ -1316,16 +2293,24 @@ const model = createEmptyProcess('flowable')
 model.id = 'Process_LeaveApproval'
 model.name = '请假审批'
 
+const config = {
+  modeling: {
+    propertiesProfile: 'business',
+    allowedNodeTypes: ['startEvent', 'userTask', 'exclusiveGateway', 'endEvent'],
+    allowedEdgeTypes: ['sequenceFlow'],
+  },
+  ui: { controlSize: 'medium' },
+}
+
 const studio = createStudioController({
   model,
-  propertiesProfile: 'business',
-  allowedNodeTypes: ['startEvent', 'userTask', 'exclusiveGateway', 'endEvent'],
-  allowedEdgeTypes: ['sequenceFlow'],
+  config,
 })
 
 const shell = createStudioShell({
   container: document.querySelector('#studio'),
   studio,
+  config,
   mode: 'design',
   allowedModes: ['design', 'viewer'],
   theme: 'auto',
@@ -1348,6 +2333,8 @@ function dispose() {
 
 Controller 持有模型、命令、选择、历史与作用域；Shell 只负责组合 Canvas、Palette、Properties 和 Viewer。销毁 Shell 不会自动销毁外部传入的 Controller。
 
+`config` 用一个结构化入口承载静态选项：`modeling` 传给 Controller，`ui`、`viewer` 和 `export` 传给 Shell。旧顶层字段仍兼容但已 Deprecated；同一项同时配置时，显式旧值优先。
+
 宿主可观察实际 Mode，并在运行时调整白名单：
 
 ```js
@@ -1431,6 +2418,8 @@ Designer 子路径适合已有自定义工具栏和属性面板的宿主。需
 
 ## 6. Studio Viewer 子路径与审批轨迹
 
+接入真实审批后端时先阅读[审批轨迹接入指南](RUNTIME-INTEGRATION.md)，按实例定义版本准备 XML，再转换工作项、操作及路径事实。指南提供完整可编译示例，以及新增 Runtime 类型出口在 `0.3.5-preview` 之前版本的兼容写法；设置 `engine` 不会自动查询引擎。
+
 ```js
 import { BpmnViewer } from '@bpmn-nova/studio/viewer'
 import '@bpmn-nova/studio/styles.css'
@@ -1496,8 +2485,11 @@ export function WorkflowEditor({ initialXml }) {
         engine="flowable"
         mode={mode}
         allowedModes={['design', 'viewer']}
+        config={{
+          modeling: { propertiesProfile: 'business' },
+          ui: { controlSize: 'medium' },
+        }}
         nodeSubtitleResolver={subtitleResolver}
-        propertiesProfile="business"
         theme="auto"
         onChange={(model, reason, nextXml) => saveDraft(nextXml)}
         onSelectionChange={(selection, element) => console.log(element)}
@@ -1545,7 +2537,10 @@ const onChange = (model, reason, nextXml) => saveDraft(nextXml)
       engine="flowable"
       v-model:mode="mode"
       :allowed-modes="['design', 'viewer']"
-      properties-profile="business"
+      :config="{
+        modeling: { propertiesProfile: 'business' },
+        ui: { controlSize: 'medium' },
+      }"
       theme="auto"
       @change="onChange"
       @mode-change="event => console.log(event.source)"
@@ -1568,11 +2563,12 @@ Vue 事件使用 kebab-case：`change`、`selection-change`、`scope-change`、`
   ref="studioRef"
   :xml="xml"
   engine="activiti"
-  mode="design"
-  :allowed-modes="['design']"
-  :allowed-node-types="supportedNodeTypes"
-  :allowed-edge-types="['sequenceFlow']"
-  :regions="{ right: 'hidden' }"
+      mode="design"
+      :allowed-modes="['design']"
+      :config="{
+        modeling: { allowedNodeTypes: supportedNodeTypes, allowedEdgeTypes: ['sequenceFlow'] },
+        ui: { controlSize: 'medium', regions: { right: 'hidden' } },
+      }"
   theme="auto"
   @change="handleChange"
   @selection-change="handleSelectionChange"
@@ -1581,7 +2577,7 @@ Vue 事件使用 kebab-case：`change`、`selection-change`、`scope-change`、`
   <template #header-start="{ state, actions }">
     <!-- 返回、业务图标、流程名称、类型 -->
   </template>
-  <template #header-actions="{ actions, mode }">
+    <template #header-actions="{ actions, mode, ui }">
     <button type="button" :disabled="mode !== 'design'" @click="actions.validate()">校验</button>
     <button type="button" :disabled="mode !== 'design'" @click="saveDraft(actions.exportXml())">保存</button>
     <button type="button" :disabled="mode !== 'design'" @click="publishProcess(actions)">发布</button>
@@ -1591,6 +2587,28 @@ Vue 事件使用 kebab-case：`change`、`selection-change`、`scope-change`、`
 
 Vue 的 `#header-start` 只替换 Brand，`#header-actions` 只替换默认“校验 / 导入 / 导出”动作组，`#header` 替换完整 Header；React 使用等价的 `headerStart` / `headerActions` / `header` Render Prop。顶部最佳视图已去重，底部入口与 `fitView()` 保留。`actions.validate()` 先展示 Nova 内部结果，再发送 `validation` / `onValidation`，最后返回 issues。`regions` 属性变化会原地更新区域，不重建 Canvas。
 
+### 8.2 对齐宿主 UI 组件库
+
+Header 控件通过 `config.ui.controlSize` 统一设置。默认值是 `medium`；`small / medium / large` 的普通按钮高度分别为 28 / 32 / 40px，也可传入 `24px`–`48px` 的 CSS 像素字符串：
+
+```vue
+<BpmnStudio
+  ref="studioRef"
+  :config="{ ui: { controlSize: '36px' } }"
+>
+  <template #header-actions="{ actions, ui }">
+    <HostWorkflowActions
+      :actions="actions"
+      :button-height="ui.controlHeight"
+    />
+  </template>
+</BpmnStudio>
+```
+
+Element Plus 的 `small / default / large` 可映射到 Nova `small / medium / large`；Ant Design 的 `small / middle / large` 使用相同映射。自定义动作位于 Nova Header DOM 内，可继承 `--nova-control-height`、`--nova-header-height`、`--nova-control-font-size`、`--nova-control-padding-inline`、`--nova-control-icon-size` 和 `--nova-control-radius`。
+
+该尺寸不会影响 Footer 缩放区、Canvas 浮动工具、Palette 或 Properties。运行时可通过 `shell.setConfig()` 或框架响应式 `config` 原地更新；`shell.getConfig()` 返回当前归一化配置。`config.modeling` 只在 Controller 创建时生效，运行中只允许现有 `setPropertiesProfile()` 调整 Profile，节点/连线白名单不会改变。
+
 ```js
 async function publishProcess(actions) {
   const issues = actions.validate()
@@ -1599,10 +2617,25 @@ async function publishProcess(actions) {
 }
 ```
 
-把宿主属性面板放在 Nova 外部，以 `selection-change` / `onSelectionChange` 作为状态来源，并用稳定 BPMN Element ID 关联业务配置。该事件覆盖节点、连线、多选、清空和键盘选择；`element-click` 不能替代选择状态。Nova 不负责保存、发布、权限或服务端事务。
+宿主拥有外部属性面板时，以 `selection-change` / `onSelectionChange` 作为设计选择状态来源，用稳定 BPMN Element ID 关联业务配置；`element-click` 不能替代选择状态。希望复用 Nova 侧栏时使用下述右侧 Slot。Nova 不负责保存、发布、权限或服务端事务。
 
 `theme="auto"` 需要显式配置才会跟随系统主题；未传 Theme 时仍默认为 `light`。完全自定义布局时，React 与 Vue 均可组合 `BpmnCanvas`、`BpmnPalettePanel` 和 `BpmnPropertiesPanel`，并传入同一个外部 Controller。
 
+### 8.3 右侧内容与侧栏展开收起
+
+Vue `#right`、React `right`、Core `slots.right` 替换右侧内容但保留 Nova 管理的宽度、高度和折叠按钮。不要配置 `regions.right: 'hidden'` 后再期待 Slot 显示；隐藏移除整个区域，收起才保留展开按钮。
+
+```js
+const config = { ui: {
+  leftPanel: { collapsible: true, defaultCollapsed: false },
+  rightPanel: { collapsible: true, defaultCollapsed: false, layout: 'flex' },
+} }
+```
+
+默认 Flex 让宿主安排固定头尾与 `flex: 1; min-height: 0; overflow: auto` 中间内容；改为 `scroll` 时由 Nova 滚动整块内容。父容器仍需完整高度链。默认折叠按钮位于左右分隔线中点，200ms 平滑过渡并尊重减少动态效果；不卸载内容、不自动 Fit。Shell 容器 ≤720px 时首次收起并保留按钮，展开继续挤压画布，宽窄屏分别记忆状态。
+
+Instance 默认隐藏右侧；显式 `regions.right: 'default'` 可开启，隐藏侧栏不影响轨迹点击/详情。通过 `panelSelection` 读取跨模式的当前元素，而非从只读页面猜测设计 `state.selection`。完整 Core/Vue/React 示例、状态方法和事件见[侧栏指南](CUSTOMIZATION.md#侧栏布局与平滑折叠)；这些新增能力自 `0.3.5-preview` 提供。
+
 ## 9. Group 与 Pool/Lane
 
 Group 是纯视觉 Artifact，不保存成员关系：
@@ -1660,7 +2693,7 @@ BPMN Nova 主题应挂在组件根容器。自定义 Renderer 不要修改 `docu
 
 # BPMN Nova 组件参数
 
-本手册记录 `0.3.4-preview` 的公开组件参数、回调和实例方法。所有视觉组件都需要具有实际尺寸的容器，并显式导入所属包的 `styles.css`。
+本手册记录 `0.3.5-preview` 的公开组件参数、回调和实例方法。所有视觉组件都需要具有实际尺寸的容器，并显式导入所属包的 `styles.css`。
 
 ## 按项目环境阅读
 
@@ -1681,6 +2714,7 @@ type EngineId = 'flowable' | 'activiti'
 type ViewerProjection = 'auto' | 'standard' | 'approval' | 'compact'
 type NovaThemeInput = 'light' | 'dark' | 'auto' | NovaThemeOptions
 type PropertiesProfile = 'business' | 'developer'
+type StudioControlSize = 'small' | 'medium' | 'large' | `${number}px`
 ```
 
 完整 `ProcessModel`、`BpmnNode`、`BpmnEdge` 与 Runtime Snapshot 类型见对应包的 `.d.ts` 和 [API](API.md)。
@@ -1693,10 +2727,11 @@ Controller 不创建 DOM，负责模型、命令、历史、选择与子流程
 | --- | --- | --- | --- |
 | `model` | `ProcessModel` | 必填 | 初始流程模型 |
 | `historyLimit` | `number` | `80` | Undo/Redo 快照上限 |
-| `propertiesProfile` | `'business' \| 'developer'` | `'business'` | 属性面板可见级别 |
+| `config` | `BpmnStudioConfig` | `{}` | 结构化静态配置；Controller 使用 `config.modeling` |
+| `propertiesProfile` | `'business' \| 'developer'` | `'business'` | Deprecated 兼容别名；优先于 `config.modeling.propertiesProfile` |
 | `extensions` | `StudioExtension[]` | `[]` | Controller 扩展，`setup()` 可返回清理函数 |
-| `allowedNodeTypes` | `Iterable<NodeType> \| null` | `null` | 完整模型节点白名单；同时约束导入与所有创建/转换命令 |
-| `allowedEdgeTypes` | `Iterable<EdgeType> \| null` | `null` | 完整模型连线白名单；同时约束导入、连接与模板命令 |
+| `allowedNodeTypes` | `Iterable<NodeType> \| null` | `null` | Deprecated 兼容别名；完整模型节点白名单 |
+| `allowedEdgeTypes` | `Iterable<EdgeType> \| null` | `null` | Deprecated 兼容别名；完整模型连线白名单 |
 
 常用方法：
 
@@ -1719,17 +2754,18 @@ Controller 不创建 DOM，负责模型、命令、历史、选择与子流程
 | --- | --- | --- | --- |
 | `container` | `HTMLElement` | 必填 | Studio 根容器 |
 | `studio` | `BpmnStudioController` | 必填 | 外部 Controller |
+| `config` | `BpmnStudioConfig` | `{}` | `ui/viewer/export` 静态配置；`modeling` 由 Controller 创建时消费 |
 | `mode` | `'design' \| 'viewer' \| 'instance'` | `'design'` | 当前展示模式 |
 | `allowedModes` | `('design' \| 'viewer' \| 'instance')[]` | 全部模式 | 默认工作台显示并允许切换的模式 |
 | `runtime` | `ProcessInstanceSnapshot \| null` | `null` | 实例模式数据；没有数据时保持空运行事实 |
 | `projection` | `ViewerProjection` | 实例模式默认 `approval` | 审批轨迹投影 |
-| `responsive` | `boolean` | `false` | 是否允许审批投影响应容器宽度 |
-| `projectionOptions` | `{ value, label }[]` | 默认两项 | Shell 轨迹切换选项 |
-| `leftWidth` | `number` | `244` | 左侧栏宽度，像素 |
-| `rightWidth` | `number` | `360` | 右侧栏宽度，像素 |
+| `responsive` | `boolean` | `false` | Deprecated；使用 `config.viewer.responsive` |
+| `projectionOptions` | `{ value, label }[]` | 默认两项 | Deprecated；使用 `config.viewer.projectionOptions` |
+| `leftWidth` | `number` | `244` | Deprecated；使用 `config.ui.sidebarWidth.left` |
+| `rightWidth` | `number` | `360` | Deprecated；使用 `config.ui.sidebarWidth.right` |
 | `theme` | `NovaThemeInput` | `light` | 组件实例主题 |
 | `runtimeAppearance` | `RuntimeAppearanceOptions` | 默认语义映射 | 状态、动作、转移的 Tone 映射 |
-| `svgExport` | `SvgExportOptions & Renderer Adapters` | `{}` | SVG 文件名、节点/时间线 SVG Renderer 等导出配置 |
+| `svgExport` | `SvgExportOptions & Renderer Adapters` | `{}` | Deprecated；使用 `config.export` |
 | `iconRegistry` | `IconRegistry` | 默认 Registry | 图标覆盖入口 |
 | `paletteRegistry` | `PaletteRegistry` | 默认 Registry | Palette Provider 入口 |
 | `propertiesRegistry` | `PropertiesRegistry` | 默认 Registry | Properties Provider 入口 |
@@ -1738,15 +2774,27 @@ Controller 不创建 DOM，负责模型、命令、历史、选择与子流程
 | `rendererOptions` | `DiagramRendererOptions` | `{}` | 节点与 Runtime Renderer 配置 |
 | `nodeSubtitleResolver` | `NodeSubtitleResolver` | 无 | 覆盖 Design/Viewer 标准节点副标题；不影响 Instance |
 | `slots` | `StudioShellSlots` | `{}` | 局部 UI 替换 |
-| `regions` | `StudioShellRegions` | 全部 `default` | 原地隐藏 Header、Palette、Properties 或 Statusbar；隐藏后不保留轨道 |
+| `regions` | `StudioShellRegions` | 按模式决定 | Deprecated；使用 `config.ui.regions`；Instance 默认隐藏右侧 |
 | `layout` | `Function` | 默认三栏布局 | 完整布局替换 |
 | `onThemeChange` | `(state) => void` | 无 | 主题模式解析变化回调 |
 
-实例方法包括 `getMode()`、`getAllowedModes()`、`setMode()`、`setAllowedModes()`、`subscribeMode()`、`validate()`、`subscribeValidation()`、`getRegions()`、`setRegions()`、`setRuntime()`、`setProjection()`、`refreshPresentation()`、`setTheme()`、`setRuntimeAppearance()`、`fitView()`、`zoomBy()`、`exportSvg()`、`openSvgExportPreview()` 和 `destroy()`。`setMode()` 仅在真实成功切换时返回 `true`；Mode Event 的 `source` 为 `toolbar | api | allowed-modes`。
+实例方法包括 `getConfig()`、`setConfig()`、`getMode()`、`getAllowedModes()`、`setMode()`、`setAllowedModes()`、`subscribeMode()`、`validate()`、`subscribeValidation()`、`getRegions()`、`setRegions()`、`setRuntime()`、`setProjection()`、`refreshPresentation()`、`setTheme()`、`setRuntimeAppearance()`、`fitView()`、`zoomBy()`、`exportSvg()`、`openSvgExportPreview()` 和 `destroy()`。`setMode()` 仅在真实成功切换时返回 `true`；Mode Event 的 `source` 为 `toolbar | api | allowed-modes`。
+
+`0.3.5-preview` 新增 `getSidebarState()`、`setSidebarCollapsed(side, collapsed)`、`subscribeSidebarChange()`、`getPanelSelection()`、`subscribePanelSelection()`。侧栏状态与选择快照的类型、返回值和事件见 [API](API.md#侧栏配置状态与选择)，完整框架示例见[侧栏指南](CUSTOMIZATION.md#侧栏布局与平滑折叠)。
+
+| `config.ui` 配置 | 默认值 | 含义 |
+| --- | --- | --- |
+| `leftPanel.collapsible` / `rightPanel.collapsible` | `true` | 显示分隔线中点折叠按钮；`false` 时可见面板保持展开 |
+| `leftPanel.defaultCollapsed` / `rightPanel.defaultCollapsed` | `false` | 宽屏初始化状态；不随 Config 更新重置 |
+| `rightPanel.layout` | `'flex'` | `'flex'` 由宿主安排内部滚动；`'scroll'` 由 Nova 滚动整块内容 |
+
+首次进入 ≤720px 的 Shell 容器时，可折叠面板默认收起且保留按钮，宽窄屏分别记忆状态。折叠动画为 200ms，支持减少动态效果，不卸载 Slot、不执行 Fit。Design 默认左右可见，Viewer 仅右侧可见，Instance 默认两侧隐藏；显式 `regions.right: 'default'` 可在 Instance 开启，`'hidden'` 隐藏整个区域和按钮，不能用右侧 Slot 覆盖。
+
+`BpmnStudioConfig` 分为四组：`modeling`（Profile 和节点/连线白名单）、`ui`（`controlSize`、Regions、侧栏宽度、折叠与内容布局）、`viewer`（响应式投影、投影选项、Timeline/Details/Trace）和 `export`。`setConfig()` 先完整校验，再原地更新 UI、Viewer 与 Export，不重建 Canvas。`controlSize` 默认 `medium`，接受 `small | medium | large | '24px'…'48px'`；`null`、裸数字、其他单位及范围外值会抛出包含 `config.ui.controlSize` 的错误。
 
 `shell.actions` 是默认 Header 与宿主自定义 Header 共用的稳定 Interface，提供 `undo()`、`redo()`、`beautify()`、`rerouteEdges()`、`fitView()`、`validate()`、`importXml()`、`exportXml()`、`exportSvg()` 和 `openSvgExportPreview()`。它不包含保存、发布、权限或文件上传等宿主业务动作。
 
-`slots.headerStart` 只替换 Nova Brand；`slots.headerActions` 只替换默认“校验 / 导入 / 导出”动作组；`slots.header` 完整替换 Header，且优先级更高。Slot Context 提供 `studio`、`shell`、`canvas`、`actions`、`getState()`、`subscribe()`、`getMode()`、`getAllowedModes()`、`subscribeMode()` 和 `subscribeValidation()`。默认 Header 的最佳视图只保留在底部缩放区。`regions.header = 'hidden'` 的优先级最高。`layout()` 与 `regions` 不能同时使用。
+`slots.headerStart` 只替换 Nova Brand；`slots.headerActions` 只替换默认“校验 / 导入 / 导出”动作组；`slots.header` 完整替换 Header，且优先级更高。Slot Context 提供 `studio`、`shell`、`canvas`、`actions`、只读 `ui`、`getState()`、`subscribe()`、`getMode()`、`getAllowedModes()`、`subscribeMode()` 和 `subscribeValidation()`。`ui.controlSize` 是语义值，`ui.controlHeight` 是归一化 px 高度。默认 Header 的最佳视图只保留在底部缩放区。`regions.header = 'hidden'` 的优先级最高。`layout()` 与 `regions` 不能同时使用。
 
 `actions.validate()` 先更新 Nova 默认状态栏，再发送一次来源为 `toolbar` 的 Validation Event 并返回 issues；实例 `validate()` 的来源为 `api`。事件 `valid` 只由 error 决定，warning 不默认阻止发布。
 
@@ -1773,6 +2821,8 @@ new BpmnDesigner(options)
 
 ## `BpmnViewer`
 
+审批轨迹的完整输入、Vue/React/Core 加载刷新和点击事件示例见[审批轨迹接入指南](RUNTIME-INTEGRATION.md)。`runtime` 是顶层实例数据；完整 Studio 的展示配置使用 `config.viewer`，独立 Viewer 保持下表的顶层 Options。指南同时说明自 `0.3.5-preview` 提供的 Adapter Runtime 类型出口与旧版兼容推导。
+
 | 参数 | 类型 | 必填/默认 | 说明 |
 | --- | --- | --- | --- |
 | `container` | `HTMLElement` | 必填 | Viewer 容器 |
@@ -1854,6 +2904,7 @@ new BpmnDesigner(options)
 | --- | --- |
 | `studio` | 外部 Controller；不传时根据 `model/xml/engine` 创建并托管 |
 | `model` / `xml` / `engine` | 初始及后续受控模型输入 |
+| `config` | `modeling/ui/viewer/export` 结构化静态配置；属性变化原地应用 Shell 配置 |
 | `propertiesProfile` | 创建内部 Controller 时的属性 Profile |
 | `allowedNodeTypes` | 创建内部 Controller 时使用的完整模型节点白名单 |
 | `allowedEdgeTypes` | 创建内部 Controller 时使用的完整模型连线白名单 |
@@ -1861,14 +2912,17 @@ new BpmnDesigner(options)
 | `mode` / `onModeChange` | 受控输入与实际 Mode 事件；Header Render Context 同步提供 `mode` |
 | `nodeSubtitleResolver` | Design/Viewer 标准节点副标题 Resolver |
 | `contextMenuRegistry` | 自定义右键动作 Registry |
-| `regions` | 默认 Shell 区域显隐；属性变化原地调用 `setRegions()` |
-| `headerStart` / `headerActions` / `header` | React Node 或 Render Prop；使用 Portal 保留宿主 Context |
+| `regions` | Deprecated 兼容别名；使用 `config.ui.regions` |
+| `headerStart` / `headerActions` / `header` / `right` | React Node 或 Render Prop；使用 Portal 保留宿主 Context；`right` 仅替换侧栏内容 |
 | `onValidation` | Nova 内部校验展示完成后的只读结果事件 |
+| `onSidebarChange` | 只读侧栏折叠事件，来源 `button \| api \| responsive \| config` |
 | `onChange(model, reason, xml)` | 模型变化 |
 | `onSelectionChange(selection, element)` | 选择变化 |
 | `onScopeChange(activeScopeId, scopePath, state)` | 子流程作用域变化 |
 
-Ref：`studio`、`shell`、`actions`、`mode`、`getMode()`、`setMode()`、`setAllowedModes()`、`validate()`、`refreshPresentation()`、`exportXml()`、`fitView()`、`setTheme()`。
+Ref：`studio`、`shell`、`actions`、`mode`、`getConfig()`、`setConfig()`、`getMode()`、`setMode()`、`setAllowedModes()`、`validate()`、`refreshPresentation()`、`exportXml()`、`fitView()`、`setTheme()`。Header Render Context 额外提供只读 `ui`。
+
+Studio Ref 同时提供五个侧栏/面板选择方法：`getSidebarState()`、`setSidebarCollapsed()`、`subscribeSidebarChange()`、`getPanelSelection()`、`subscribePanelSelection()`。Header/Right Render Context 共享响应式 `state`、`mode`、`ui`、`panelSelection`，以及 `studio`、`shell`、`actions`；只读选择使用 `panelSelection`，不将 `state.selection` 误当作轨迹当前选择。
 
 `xml`/`model` 是外部替换输入。回写与最近导出完全相同的 XML 不会重复导入或清空 Undo/Redo；不同 XML 会替换模型和历史。React/Vue 包均重新导出创建外部 Controller 与 Palette、Properties、Context Menu、Icon、Template Registry 所需的公开函数。
 
@@ -1888,11 +2942,13 @@ Props：`model`、`xml`、`engine`、`theme`、`onChange`、`onSelectionChange`
 
 Vue 组件与 React 使用同一底层接口，主要差异为：
 
-- Studio 提供原生 `#header-start`、`#header-actions` 和 `#header` Slot，通过 Teleport 保留宿主 provide/inject、响应式状态和生命周期。
+- Studio 提供原生 `#header-start`、`#header-actions`、`#header` 和 `#right` Slot，通过 Teleport 保留宿主 provide/inject、响应式状态和生命周期；同名原生 Slot 高于 Core DOM Slot。
 - `slotsConfig` 继续保留，作为高级 Core DOM Slot 入口；完整 Header 高于局部 Header Slots，原生局部 Slot 高于对应 Core Slot。
-- 事件为 `change`、`selection-change`、`scope-change`、`element-click`、`trace-click`、`update:mode`、`mode-change`、`validation`；支持 `v-model:mode`。
+- 事件为 `change`、`selection-change`、`scope-change`、`element-click`、`trace-click`、`update:mode`、`mode-change`、`validation`、`sidebar-change`；支持 `v-model:mode`。
 - `BpmnDesigner` 发出 `change`、`selection-change`。
 - Header Slot Context 的 `mode` 是响应式实际状态。Ref Expose 使用 `getStudio()`、`getShell()`、`getActions()`、`getMode()`、`setMode()`、`setAllowedModes()`、`validate()`、`refreshPresentation()` 或 `getInstance()`，不直接暴露可替换字段。
+- Studio Prop 与 `useBpmnStudio()` 支持 `config`；Expose 提供 `getConfig()` / `setConfig()`，Header Slot Context 提供响应式只读 `ui`。
+- Studio Expose 提供与 React 相同的五个侧栏/面板选择方法；Header/Right Slot Context 共享响应式 `panelSelection`。
 
 Vue 提供 `BpmnStudio`、`BpmnDesigner`、`BpmnViewer`、`BpmnCanvas`、`BpmnPalettePanel`、`BpmnPropertiesPanel` 和 `useBpmnStudio()`。独立 `BpmnPalettePanel` 复用外部 Studio；传入 Registry 时不会隐式注册 Providers，未传 Registry 时才用 Providers 创建默认 Registry。
 
@@ -1916,7 +2972,7 @@ Runtime Details、Timeline 和 Transition Details 组件通过对应 `createReac
 
 <!-- SOURCE: docs/API.md -->
 
-# BPMN Nova v0.3.4 Preview API
+# BPMN Nova v0.3.5 Preview API
 
 ## Framework Adapter 类型门面
 
@@ -1934,6 +2990,135 @@ import type {
 
 React 使用相同名称，并将入口替换为 `@bpmn-nova/react`。这些是 TypeScript-only export，不会增加 Adapter 的浏览器运行时代码。
 
+### Runtime 类型门面
+
+自 `0.3.5-preview` 起，Vue/React 根入口新增显式 `export type`：`ProcessInstanceSnapshot`、`ActivityInstance`、`ActivityStatus`、`RuntimeParticipant`、`RuntimeApprovalAction`、`RuntimeApprovalActionType`、`RuntimeApprovalContent`、`RuntimeApprovalContentBlock`、`RuntimeAssetRef`、`RuntimeTransition`、`RuntimeEdgeVisit`、`RuntimeTraceClickEvent`、`RuntimeAssetResolver`、`RuntimeAssetPurpose`。它们复用现有声明，不是新增 JavaScript API；Studio 原有出口保持不变。
+
+真实数据转换、ID 关联、完整场景与已发布版本的 Props 类型推导见[审批轨迹接入指南](RUNTIME-INTEGRATION.md)。
+
+## Studio Config Interface
+
+```ts
+type StudioControlSize = 'small' | 'medium' | 'large' | `${number}px`
+
+interface StudioSidebarConfig {
+  collapsible?: boolean
+  defaultCollapsed?: boolean
+}
+
+interface StudioRightPanelConfig extends StudioSidebarConfig {
+  layout?: 'flex' | 'scroll'
+}
+
+interface StudioUiConfig {
+  controlSize?: StudioControlSize
+  regions?: StudioShellRegions
+  sidebarWidth?: { left?: number; right?: number }
+  leftPanel?: StudioSidebarConfig
+  rightPanel?: StudioRightPanelConfig
+}
+
+interface BpmnStudioConfig {
+  modeling?: {
+    propertiesProfile?: 'business' | 'developer'
+    allowedNodeTypes?: readonly NodeType[]
+    allowedEdgeTypes?: readonly EdgeType[]
+  }
+  ui?: StudioUiConfig
+  viewer?: {
+    responsive?: boolean
+    projectionOptions?: readonly { value: ViewerProjection; label: string }[]
+    timeline?: ViewerTimelineOptions
+    runtimeDetails?: RuntimeDetailsOptions
+    runtimeTraceOptions?: RuntimeTraceProjectionOptions
+  }
+  export?: StudioSvgExportOptions
+}
+
+interface StudioUiContext {
+  readonly controlSize: StudioControlSize
+  readonly controlHeight: `${number}px`
+}
+```
+
+同一个 `config` 可同时传给 `createStudioController()` 和 `createStudioShell()`；React/Vue `BpmnStudio` 与 `useBpmnStudio()` 也接受它。`config.modeling` 在 Controller 创建时建立 Profile 与建模不变量；Shell 的 `setConfig()` 只原地更新 UI、Viewer 和 Export，不改节点/连线白名单、不重建 Canvas。
+
+```js
+const next = shell.setConfig({
+  ui: { controlSize: '36px', regions: { right: 'hidden' } },
+  viewer: { responsive: true },
+  export: { padding: 36 },
+})
+
+console.log(shell.getConfig(), shell.ui.controlHeight)
+```
+
+`controlSize` 默认 `medium`。预设普通按钮高度是 `small=28px`、`medium=32px`、`large=40px`；自定义值严格接受 24px–48px。非法配置在任何 DOM 写入前抛错，错误包含 `config.ui.controlSize`。尺寸只影响 Header。Core Slot、Vue Slot 和 React Render Context 都提供只读 `ui`；自定义 Header 还可以继承 `--nova-control-height`、`--nova-header-height`、`--nova-control-font-size`、`--nova-control-padding-inline`、`--nova-control-icon-size` 与 `--nova-control-radius`。
+
+旧顶层字段继续兼容并标记 Deprecated：
+
+| 旧字段 | Config 路径 |
+| --- | --- |
+| `propertiesProfile` / `allowedNodeTypes` / `allowedEdgeTypes` | `config.modeling.*` |
+| `regions` / `leftWidth` / `rightWidth` | `config.ui.regions` / `config.ui.sidebarWidth.*` |
+| `responsive` / `projectionOptions` / `timeline` / `runtimeDetails` / `runtimeTraceOptions` | `config.viewer.*` |
+| `svgExport` | `config.export` |
+
+同一项同时出现时，旧顶层显式值优先，以保证现有接入无行为变化。
+
+### 侧栏配置、状态与选择
+
+自 `0.3.5-preview` 起，新增侧栏类型和接口从 Studio/Vue/React 根声明入口提供，不要求增加其他直接依赖。`config.ui.leftPanel/rightPanel.collapsible` 默认 `true`；`defaultCollapsed` 只用于宽屏初始化，默认 `false`。`rightPanel.layout` 默认 `flex`，宿主控制内部滚动；`scroll` 由 Nova 负责整块内容滚动。完整示例见[侧栏布局与平滑折叠](CUSTOMIZATION.md#侧栏布局与平滑折叠)。
+
+```ts
+type StudioSidebarSide = 'left' | 'right'
+type StudioSidebarChangeSource = 'button' | 'api' | 'responsive' | 'config'
+
+interface StudioSidebarChangeEvent {
+  readonly side: StudioSidebarSide
+  readonly collapsed: boolean
+  readonly previousCollapsed: boolean
+  readonly mode: StudioMode
+  readonly source: StudioSidebarChangeSource
+}
+```
+
+| Shell 方法 | 契约 |
+| --- | --- |
+| `getSidebarState()` | 返回只读左右状态；每侧包含 `collapsed`、`hidden`、`collapsible` |
+| `setSidebarCollapsed(side, collapsed): boolean` | 仅实际切换返回 `true`；隐藏、禁用折叠、销毁或重复设置返回 `false` |
+| `subscribeSidebarChange(listener)` | 订阅只读状态变化；返回取消订阅函数，不按动画帧发送 |
+| `getPanelSelection()` | 返回 `{ selection, selectedElement, trace }`，只读空选择的三个字段均为 `null` |
+| `subscribePanelSelection(listener)` | 接收面板选择快照；返回取消订阅函数 |
+
+Design 的面板选择沿用 Controller 选择语义（包括默认流程选择），Viewer/Instance 来自实际节点/轨迹点击，不改变设计选择。Model/Runtime 更新后重新解析；模式切换成功后才更新。Core Slot 只挂载一次，通过订阅响应变化；Vue/React Header 与 Right Context 直接提供响应式 `panelSelection`。
+
+框架 Studio Expose/Handle 透传上述方法；侧栏事件分别为 Vue `sidebar-change`、React `onSidebarChange`。新 Vue `#right` 与 React `right` 优先于对应 Core DOM Slot，只替换右侧内容，不重建 Canvas。
+
+默认 Design 显示左右，Viewer 仅显示右侧，Instance 两侧隐藏。未配置 `regions.right` 时采用模式默认；显式 `'default'` 可在 Instance 开启右侧，`'hidden'` 隐藏内容及按钮。`getConfig()` 保留未配置与显式配置的区别，`setConfig(getConfig())` 不改变这一意图。隐藏与收起独立，Slot 不会自动开启隐藏的侧栏。
+
+Shell 容器宽度 ≤720px 为窄屏，首次进入时可折叠侧栏收起；宽/窄屏分别记忆状态。两侧可同时展开并挤压画布；收起和展开采用 200ms 过渡，尊重减少动态效果，不自动 Fit。`sidebarWidth` 为展开首选宽度，窄空间按比例约束以保留画布。折叠状态不写入 Model、XML、History 或持久化存储。自定义完整 `layout()` 和独立 Designer/Viewer 不使用这套默认侧栏。
+
+## 节点 DI 与视觉尺寸
+
+`createNode()` / Palette 使用类型定义的默认宽高；加载已有 XML（包括组件接收服务端返回的 `xml`）使用 BPMN DI Bounds。XML 导出已写入节点的 `x/y/width/height`，并沿用既有取整与 waypoint 序列化规则；小尺寸节点的外壳溢出不是“保存遗漏宽高”。
+
+以下标准外壳的适配自 `0.3.5-preview` 提供，不新增公共 Interface 或尺寸配置：
+
+| 标准图元 | 默认节点容器 | 内部图形基准 | 显示缩放比例 |
+| --- | --- | --- | --- |
+| 排他、并行、包容、事件、复杂网关 | 72×72 | 49×49，旋转 45° | `min(1, width / (49√2), height / (49√2))` |
+| 数据对象 | 72×88 | 50×62 | `min(1, width / 50, height / 62)` |
+| 数据存储 | 78×78 | 56×50 | `min(1, width / 56, height / 50)` |
+
+图形及其描边、圆角、折角和内部标记等比缩小、不放大，并相对节点容器居中。标签不随图形缩放，水平中心对齐容器，顶部位于容器底部下方 6px。并行网关的角色徽标保持独立。事件沿用已有尺寸约束修复；任务、子流程和泳道不在此次调整范围。
+
+DOM Canvas/Viewer/Instance 与纯 SVG Export 共享内部 `node-geometry` Module，以实际渲染 Projection Model 为输入。仅复制显示路径并将首末非零线段与标准外轮廓求交；中间折点、方向、连线标签基准及持久化 waypoint 不变。命中区域使用同一显示路径，折点编辑仍操作原始数据；已贴边目标的箭头尖端与参考点重合。已有连接手柄按可见轮廓定位，不改变连接规则。
+
+非有限或非正尺寸不产生标准外壳几何；无合法交点、退化路径或 SVG 自定义 Renderer 成功接管的节点不做标准端点校正。SVG Renderer 每个节点只调用一次；返回 `false` 或抛错时继续原有标准降级/警告规则。该 Module 不作为公共 npm 包或 API 导出。宿主无需扩大 DI、删除重建节点、覆盖内部 CSS 或为此迁移服务端 XML。
+
+这里的不变性针对重绘、展示刷新和 SVG 导出，不是对所有编辑操作的无损承诺：现有 Controller `updateNode()` 会清空该节点相邻连线的 waypoint（仅改名也会触发），随后沿用 Core 自动路由。本轮没有改变该编辑语义；也不承诺 XML 的字节级往返一致性。
+
 ## Designer
 
 ```js
@@ -2126,12 +3311,12 @@ interface StudioShellRegions {
 const shell = createStudioShell({
   container,
   studio,
-  regions: { right: 'hidden' },
+  config: { ui: { regions: { right: 'hidden' } } },
   slots: {
-    headerStart({ container, studio, shell, canvas, actions, getState, subscribe, getMode, getAllowedModes, subscribeMode, subscribeValidation }) {
+    headerStart({ container, studio, shell, canvas, actions, getState, subscribe, getMode, getAllowedModes, subscribeMode, subscribeValidation, ui }) {
       // 只替换 Brand；默认模式区和编辑工具继续保留。
     },
-    headerActions({ container, actions, getMode, subscribeMode }) {
+    headerActions({ container, actions, getMode, subscribeMode, ui }) {
       // 替换默认“校验 / 导入 / 导出”，挂载宿主“校验 / 保存 / 发布”。
       // 校验调用 actions.validate()；保存与发布调用宿主服务。
     },
@@ -2142,7 +3327,7 @@ shell.getRegions()
 shell.setRegions({ right: 'default' })
 ```
 
-`slots.headerActions` 只替换 Header 最右侧默认动作组，可与 `slots.headerStart` 同时使用；`slots.header` 完整替换 Header，并高于两个局部 Slot；`regions.header = 'hidden'` 的优先级最高。未提供 `headerActions` 时仍显示“校验 / 导入 / 导出”。顶部不再重复渲染最佳视图，底部缩放区与 `fitView()` Interface 保持不变。`layout()` 与 `regions` 互斥。
+`slots.headerActions` 只替换 Header 最右侧默认动作组，可与 `slots.headerStart` 同时使用；`slots.header` 完整替换 Header，并高于两个局部 Slot；`regions.header = 'hidden'` 的优先级最高。Slot Context 的 `ui` 与 Shell 实际 Config 同步。未提供 `headerActions` 时仍显示“校验 / 导入 / 导出”。顶部不再重复渲染最佳视图，底部缩放区与 `fitView()` Interface 保持不变。`layout()` 与 `regions` 互斥。
 
 ```ts
 interface StudioShellActions {
@@ -2163,6 +3348,8 @@ interface StudioShellActions {
 
 Vue `BpmnStudio` 提供 `#header-start` / `#header-actions` / `#header` 与 `getActions()`；React 提供 `headerStart` / `headerActions` / `header` Render Prop 与 Ref `actions`。Core Slot 可通过 `getMode()` / `subscribeMode()` / `subscribeValidation()` 观察 Shell，框架 Slot/Render Context 直接提供响应式实际 `mode`。框架插槽的 `state` 会随 Controller 事件更新，Undo/Redo 禁用状态可以直接绑定 `state.canUndo/canRedo`。
 
+右侧内容使用 Core `slots.right`、Vue `#right` 或 React `right`。所有 Header/Right Context 共用 `mode`、`state`、`ui`、`panelSelection` 及 Actions/Controller/Shell；右侧的布局和展开/收起由默认 Shell 管理，见上面的侧栏 Interface。
+
 ## Group 与 Pool / Lane
 
 `Group` 是不持有成员引用的 BPMN 视觉 Artifact；`Lane` 通过 `containerId` 表示画布上的 Participant containment，并继续使用标准 `flowNodeRefs` 表示 BPMN 成员。`containerId` 不会写入 XML，导入时会根据 Participant 的 `processRef` 与 BPMN DI Bounds 恢复。
@@ -2400,6 +3587,8 @@ Viewer 与审批轨迹模式可在空白画布上直接按住左键拖动视口
 
 ### Runtime presentation
 
+引擎映射和组件接入步骤集中在[审批轨迹接入指南](RUNTIME-INTEGRATION.md)。特别注意当前 `invalidatedActivityIds` 表示 BPMN 节点 ID，而 `sourceActivityId` 表示工作项实例 ID；两者不能互换。
+
 Runtime snapshots are engine-neutral. `visitId` separates repeated arrivals at the same BPMN element; records sharing a visit describe one approval round, while `multiInstanceId` and an explicit `approvalMode` describe multi-person approval. Multiple people are never assumed to be countersign unless the snapshot declares `approvalMode: 'all'`.
 
 ```js
@@ -2621,12 +3810,21 @@ Stage 0 将编辑器拆成无 UI 的 `BpmnStudioController`，以及可组合的
 ## 默认组合
 
 ```js
+const config = {
+  modeling: { propertiesProfile: 'business' },
+  ui: { controlSize: 'medium' },
+};
+
 const studio = createStudioController({
   model: createSampleProcess('flowable'),
-  propertiesProfile: 'business',
+  config,
 });
 
-const shell = createStudioShell({ container, studio });
+const shell = createStudioShell({
+  container,
+  studio,
+  config,
+});
 ```
 
 NPM 接入只需要加载 Studio 的自包含样式入口。它已经按 Theme、Icons、Renderer、Palette、Properties Renderer、Studio 的顺序打包，避免宿主重复引入内部 CSS。
@@ -2709,20 +3907,20 @@ properties.registerProvider(850, {
 
 ## 组合 Shell 区域与宿主界面
 
-默认 Shell 包含 Header、Palette、Canvas、Properties 和 Statusbar。仅需要移除某个默认区域时使用 `regions`，不需要重写布局：
+默认 Shell 包含 Header、Palette、Canvas、Properties 和 Statusbar。仅需要移除某个默认区域时使用 `config.ui.regions`，不需要重写布局：
 
 ```js
 const shell = createStudioShell({
   container,
   studio,
-  regions: { right: 'hidden' },
+  config: { ui: { regions: { right: 'hidden' } } },
 })
 
 // 原地切换，不重建 Controller、Canvas、历史或视口。
 shell.setRegions({ right: 'default' })
 ```
 
-`header`、`left`、`right`、`footer` 均接受 `default | hidden`。隐藏区域不占 Grid 轨道、不显示边框，也不保留可聚焦控件。Viewer/Instance 的只读布局仍会隐藏 Palette；区域配置只能进一步隐藏。
+`header`、`left`、`right`、`footer` 均接受 `default | hidden`。隐藏区域不占 Grid 轨道、不显示边框或折叠按钮，也不保留可聚焦控件。左侧只属于 Design；右侧在 Design/Viewer 默认显示，在 Instance 默认隐藏。显式设置 `regions.right: 'default'` 可在 Instance 开启右侧；仅提供右侧 Slot 不会覆盖隐藏规则。
 
 局部内容替换使用 `slots.left`、`slots.right`、`slots.headerStart`、`slots.headerActions`、`slots.header` 和 `slots.footer`。`headerStart` 只替换默认 Brand；`headerActions` 只替换最右侧默认“校验 / 导入 / 导出”动作组；`header` 替换完整 Header，优先级高于两个局部 Slot。回调收到 `studio`、`shell`、`actions`、`getState()`、`subscribe()`、注册表、交互控制器和 Canvas。
 
@@ -2734,8 +3932,9 @@ createStudioShell({
     headerStart({ container, actions, getState, subscribe }) {
       // 挂载返回入口、业务图标、流程名称和类型；返回卸载函数。
     },
-    headerActions({ container, actions, getMode, subscribeMode }) {
+    headerActions({ container, actions, getMode, subscribeMode, ui }) {
       // 挂载校验 / 保存 / 发布；校验调用 actions.validate()，其余调用宿主服务。
+      // ui.controlSize / ui.controlHeight 始终反映 Shell 的实际配置。
     },
     left({ container, studio, interactions, canvas }) {
       // 挂载任意 Vanilla / React / Vue UI，返回卸载函数。
@@ -2759,11 +3958,226 @@ async function publishProcess(actions) {
 }
 ```
 
-React 使用 `headerStart` / `headerActions` / `header` Render Prop 和 Portal；Vue 使用 `#header-start` / `#header-actions` / `#header` Named Slot 和 Teleport。两者都在宿主应用树内渲染，不创建独立 React Root 或 Vue App，因此 Context、provide/inject、响应式状态和生命周期继续有效。Vue 原有 `slotsConfig`、React 原有 `slots` 仍作为 Core DOM 接口保留。
+React 使用 `headerStart` / `headerActions` / `header` / `right` Render Prop 和 Portal；Vue 使用 `#header-start` / `#header-actions` / `#header` / `#right` Named Slot 和 Teleport。两者都在宿主应用树内渲染，不创建独立 React Root 或 Vue App，因此 Context、provide/inject、响应式状态和生命周期继续有效。Vue 原有 `slotsConfig`、React 原有 `slots` 仍作为 Core DOM 接口保留；同名框架原生 Slot 优先。右侧原生 Slot 与下述侧栏能力自 `0.3.5-preview` 提供。
+
+### 侧栏布局与平滑折叠
+
+Nova 管理侧栏宽度、折叠按钮和可用高度，宿主只填入内容。不要先配置 `right: 'hidden'` 再传右侧 Slot：隐藏的是整个区域；Slot 替换的只是内容。
+
+```js
+const config = {
+  ui: {
+    sidebarWidth: { left: 244, right: 360 },
+    leftPanel: { collapsible: true, defaultCollapsed: false },
+    rightPanel: { collapsible: true, defaultCollapsed: false, layout: 'flex' },
+    // regions: { right: 'default' }, // 仅在 Instance 也需要右侧时显式开启
+  },
+}
+```
+
+| 状态 | 侧栏占用宽度 | 分隔线中点按钮 |
+| --- | --- | --- |
+| 展开 | 是 | 收起按钮；`collapsible: false` 时不显示 |
+| 收起 | 否 | 展开按钮仍保留在对应边缘 |
+| 隐藏 | 否 | 不显示，Slot 也不可见 |
+
+- `collapsible` 默认 `true`；`defaultCollapsed` 只设置宽屏初始化状态，默认 `false`。后续更新 Config 不重置用户操作；运行时设为 `collapsible: false` 会展开面板并移除按钮。
+- 左右独立；宽屏与窄屏分别记忆当前 Shell 生命周期内的折叠状态，不存入模型或本地存储。窄屏以 **Shell 容器宽度 ≤720px** 判断，首次进入时可折叠侧栏默认收起，保留展开按钮。
+- 窄屏展开仍挤压画布，不使用抽屉、遮罩或焦点陷阱，允许两侧同时展开。空间不足按首选宽度比例缩小侧栏，为画布保留至少 `min(96px, 容器宽度)`；空间恢复后还原首选宽度。
+- 折叠宽度采用 `200ms cubic-bezier(0.2, 0, 0, 1)`，快速反向操作从当前位置继续；初始化无动画，系统启用减少动态效果时关闭动画。按钮支持键盘和 `aria-expanded`，收起内容不可聚焦。
+- 收起或隐藏不卸载 Slot、不丢失表单状态与滚动位置、不重建 Canvas，也不调用 Fit 或改变 Zoom/Pan。Viewer 自动投影的尺寸响应在动画结束后按最终宽度合并处理；跨投影阈值时沿用原投影切换行为。
+- 完整自定义 `layout()` 不接管上述默认侧栏布局；独立 Designer/Viewer 没有 Shell 侧栏配置。
+
+### Flex 或 Scroll：谁负责滚动
+
+右侧 `layout: 'flex'` 为默认值：Nova 提供满宽高纵向 Flex 内容容器，限制溢出并设置 `min-width/min-height: 0`。宿主自行安排固定标题、弹性滚动内容和固定底部；不会给每个子元素强加 `flex: 1`。内置面板使用固定标题、中间内容滚动。
+
+使用自己的类名即可，不覆盖 Nova 内部选择器：
+
+```css
+.host-panel {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-width: 0;
+  min-height: 0;
+  overflow: hidden;
+}
+.host-panel > header,
+.host-panel > footer { flex: 0 0 auto; padding: 12px; }
+.host-panel-content { flex: 1; min-height: 0; overflow: auto; padding: 12px; }
+```
+
+如果宿主希望只填入普通内容，设置 `layout: 'scroll'`。Nova 会让整个右侧内容纵向滚动，标题也随内容滚动；此时不要再给内容包一层固定高度或滚动容器。Studio 的宿主仍须提供可计算高度，如 `height: 720px`，或一条完整、可计算的父级 Flex 高度链；仅设置一个没有高度基准的 `height: 100%` 不够。
+
+### Vue：原生右侧 Slot
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { BpmnStudio } from '@bpmn-nova/vue'
+import '@bpmn-nova/vue/styles.css'
+
+const props = defineProps({ xml: String })
+const studioRef = ref(null)
+const note = ref('')
+const config = {
+  ui: {
+    leftPanel: { collapsible: true },
+    rightPanel: { layout: 'flex', collapsible: true },
+  },
+}
+function observeSidebar(event) { console.log(event.side, event.collapsed, event.source) }
+</script>
+
+<template>
+  <div style="height: 720px">
+    <BpmnStudio ref="studioRef" :xml="props.xml" :config="config" @sidebar-change="observeSidebar">
+      <template #right="{ panelSelection, mode }">
+        <section class="host-panel">
+          <header>业务详情 · {{ mode }}</header>
+          <div class="host-panel-content">
+            <p>{{ panelSelection.selectedElement?.id ?? '未选择元素' }}</p>
+            <label>宿主备注 <textarea v-model="note" /></label>
+          </div>
+          <footer><button type="button" @click="studioRef?.setSidebarCollapsed('right', true)">收起</button></footer>
+        </section>
+      </template>
+    </BpmnStudio>
+  </div>
+</template>
+```
+
+示例使用前面的 `.host-panel` 样式。`note` 是宿主业务状态，不会因收起而销毁，不会自动写入 BPMN。
+
+### React：原生右侧 Render Prop
+
+```jsx
+import { useRef, useState } from 'react'
+import { BpmnStudio } from '@bpmn-nova/react'
+import '@bpmn-nova/react/styles.css'
+
+const config = { ui: { rightPanel: { layout: 'flex', collapsible: true } } }
+
+export function WorkflowEditor({ xml }) {
+  const studioRef = useRef(null)
+  const [note, setNote] = useState('')
+  return (
+    <div style={{ height: 720 }}>
+      <BpmnStudio
+        ref={studioRef}
+        xml={xml}
+        config={config}
+        onSidebarChange={(event) => console.log(event.side, event.collapsed, event.source)}
+        right={({ panelSelection, mode }) => (
+          <section className="host-panel">
+            <header>业务详情 · {mode}</header>
+            <div className="host-panel-content">
+              <p>{panelSelection.selectedElement?.id ?? '未选择元素'}</p>
+              <label>宿主备注 <textarea value={note} onChange={(event) => setNote(event.target.value)} /></label>
+            </div>
+            <footer><button type="button" onClick={() => studioRef.current?.setSidebarCollapsed('right', true)}>收起</button></footer>
+          </section>
+        )}
+      />
+    </div>
+  )
+}
+```
+
+### Core：内容与选择订阅
+
+```js
+import { createStudioController, createStudioShell, importBpmn } from '@bpmn-nova/studio'
+import '@bpmn-nova/studio/styles.css'
+
+// container 已有可计算高度；xml 为宿主加载的流程定义。
+const studio = createStudioController({ model: importBpmn(xml, 'flowable') })
+const shell = createStudioShell({
+  container,
+  studio,
+  config: { ui: { rightPanel: { layout: 'scroll' } } },
+  slots: {
+    right({ container: content, shell }) {
+      const heading = document.createElement('h2')
+      const summary = document.createElement('p')
+      heading.textContent = '业务详情'
+      content.append(heading, summary)
+      const render = ({ selectedElement }) => {
+        summary.textContent = selectedElement?.id ?? '未选择元素'
+      }
+      render(shell.getPanelSelection())
+      const unsubscribe = shell.subscribePanelSelection(render)
+      return () => { unsubscribe(); heading.remove(); summary.remove() }
+    },
+  },
+})
+
+const offSidebar = shell.subscribeSidebarChange((event) => {
+  console.log(event.side, event.previousCollapsed, event.collapsed, event.source)
+})
+shell.setSidebarCollapsed('left', true)
+console.log(shell.getSidebarState().left)
+
+// 宿主卸载时执行：offSidebar(); shell.destroy(); studio.destroy()
+```
+
+### 折叠状态与面板选择契约
+
+`getSidebarState()` 返回左右两侧各自的 `collapsed`、`hidden`、`collapsible`。`setSidebarCollapsed(side, collapsed)` 仅在实际成功改变时返回 `true`；隐藏、禁用折叠、销毁或重复设置返回 `false`。`subscribeSidebarChange()` 返回取消订阅函数，事件为只读 `{ side, collapsed, previousCollapsed, mode, source }`；`source` 为 `button | api | responsive | config`，不会按动画帧重复发送。Vue Expose/React Handle 透传三个方法，组件事件分别为 `sidebar-change`/`onSidebarChange`。
+
+所有框架 Header/Right Context 共用响应式 `mode`、`state`、`ui`、`panelSelection`，以及 `studio`、`shell`、`actions`。`panelSelection` 为 `{ selection, selectedElement, trace }`：Design 从 Controller 选择派生；Viewer/Instance 从实际点击派生，包含适用的轨迹上下文，不回写设计选择。空白点击清空；Model/Runtime 更新后重新解析，避免展示旧实例事实。Core 通过 `getPanelSelection()` / `subscribePanelSelection()` 使用相同状态。
+
+`state.selection` 是设计选择，不应作为只读轨迹当前选择的替代。业务字段仍以稳定 BPMN ID 关联；需要审批动作、附件或跳转事实时读取 `trace` 或既有 `trace-click`，而不是根据属性面板可见性判断。隐藏右侧不关闭轨迹详情、点击事件或附件能力。
+
+### Header 控件尺寸与宿主 UI 库
+
+通过 `config.ui.controlSize` 统一调整顶部 Header 的 Mode、Projection、撤销/重做、美化、默认动作组和自定义 Header 容器。默认值是 `medium`；预设与常见宿主组件库的语义映射如下：
+
+| Nova | 普通控件高度 | Element Plus | Ant Design |
+| --- | ---: | --- | --- |
+| `small` | 28px | `small` | `small` |
+| `medium` | 32px | `default` | `middle` |
+| `large` | 40px | `large` | `large` |
+
+宿主设计系统不落在预设上时，可传严格的 `24px`–`48px` CSS 像素字符串：
+
+```js
+const config = {
+  ui: {
+    controlSize: '36px',
+    regions: { right: 'hidden' },
+    sidebarWidth: { left: 256, right: 384 },
+  },
+}
+
+const shell = createStudioShell({ container, studio, config })
+shell.setConfig({ ...shell.getConfig(), ui: { ...shell.getConfig().ui, controlSize: 'large' } })
+```
+
+`setConfig()` 先完整校验再更新现有 Shell，不重建 Canvas，也不改变 Model、XML、History、Selection、Mode 或 Viewport。传入 `null`、裸数字、`rem`、任意 CSS 表达式或范围外值会抛出包含 `config.ui.controlSize` 的错误。`config.modeling.allowedNodeTypes` 和 `allowedEdgeTypes` 是 Controller 初始化不变量；运行中只有 Profile 继续通过 `setPropertiesProfile()` 修改。
+
+自定义 Header Actions 可通过 Context 的只读 `ui.controlSize` / `ui.controlHeight` 映射宿主组件尺寸，并继承以下 CSS Variables：
+
+```css
+.host-studio-actions .host-button {
+  min-height: var(--nova-control-height);
+  padding-inline: var(--nova-control-padding-inline);
+  border-radius: var(--nova-control-radius);
+  font-size: var(--nova-control-font-size);
+}
+
+.host-studio-actions .host-button svg {
+  width: var(--nova-control-icon-size);
+  height: var(--nova-control-icon-size);
+}
+```
+
+还可读取 `--nova-header-height`。这些变量只控制 Header；底部缩放区、画布浮动工具、Palette 和 Properties 保持自己的尺寸。旧顶层 `propertiesProfile`、`allowedNodeTypes`、`allowedEdgeTypes`、`regions`、`leftWidth`、`rightWidth`、`responsive`、`projectionOptions`、`timeline`、`runtimeDetails`、`runtimeTraceOptions` 与 `svgExport` 仍作为 Deprecated 兼容别名；新旧同时出现时，旧顶层显式值优先。
 
 若整个三栏结构都要自定义，使用 `layout({ container, mount, ...services })`。`mount.canvas()`、`mount.palette()`、`mount.properties()` 可分别挂载官方实现，也可只使用 Controller 自行实现。`layout()` 与 `regions` 是互斥 Interface，同时传入会抛出配置错误。
 
-宿主复用自己的业务属性面板时，把它放在 Nova 根节点外部的兄弟区域，并订阅 Controller 的 `selectionChanged`（框架中为 `selection-change` / `onSelectionChange`）。该事件覆盖节点、连线、多选、清空和键盘选择；`element-click` 只观察点击，不能替代选择状态。业务配置应使用稳定 BPMN Element ID 关联，不写入 Nova UI 状态。
+宿主业务属性面板既可通过右侧 Slot 复用 Nova 布局，也可显式隐藏右侧并放在 Nova 根节点外部。外部设计面板订阅 Controller 的 `selectionChanged`（框架中为 `selection-change` / `onSelectionChange`）；该事件覆盖节点、连线、多选、清空和键盘选择，`element-click` 不能替代它。跨模式的面板使用上述 `panelSelection`。业务配置以稳定 BPMN Element ID 关联，不写入 Nova UI 状态。
 
 ## 自定义画布右键菜单
 
@@ -2808,6 +4222,12 @@ createStudioShell({
 
 `rendererOptions.nodeRenderers` 按节点类型或节点 kind 注册内部渲染器。外框、端口、选择、连接、拖动和删除仍由 Canvas 管理。
 
+### 标准外壳与导入尺寸
+
+Palette 默认节点尺寸与 XML 中的 DI Bounds 可以不同；服务端 XML 通过组件加载时同样会进入解析路径。导出已保存宽高，不应以扩大模型、重建节点或宿主 CSS 补丁修复显示。自 `0.3.5-preview` 起，五类网关、数据对象和数据存储按实际节点容器等比缩小、居中，并只在显示层将连线端点及已有连接手柄贴合可见外轮廓；模型、标签的逻辑路径基准与原始 waypoint 均不变。完整尺寸规则见 [API：节点 DI 与视觉尺寸](API.md#节点-di-与视觉尺寸)。
+
+DOM 节点内容 Renderer 仍处于 Nova 管理的标准外壳内，网关自定义内容随外壳一起缩放，角色徽标保持独立。SVG Renderer 则可接管完整节点：每个节点只调用一次，成功接管时不应用标准几何或端点校正；返回 `false` 或执行失败时沿用标准降级及既有警告规则。不要依赖内部 `node-geometry` 路径；不属于标准外轮廓的自定义图形需要由宿主自行保证其视觉与连接契约。
+
 ```js
 createStudioShell({
   container,
@@ -2954,6 +4374,8 @@ createStudioShell({
 
 ## 自定义审批轨迹详情
 
+先按[审批轨迹接入指南](RUNTIME-INTEGRATION.md)完成 Runtime 数据关联，再选择详情扩展点。该指南覆盖统一点击事件、内置详情 `autoOpen`、资源 Resolver、会签和回退历史；定义态副标题 Resolver 不用于改写这些运行事实。
+
 默认 Instance Viewer 会把运行记录归一化为 `RuntimePresentation`。自定义节点通过 `runtimePresentation` 读取状态和处理人摘要，通过 `openRuntimeDetails()` 复用默认详情弹层，不需要再次实现会签与多轮审批聚合。
 
 ```js
@@ -3050,7 +4472,7 @@ createStudioShell({
 
 # BPMN Nova NPM 包与发布
 
-版本：`0.3.4-preview`。BPMN Nova 只发布三个 `@bpmn-nova` 公共包，均使用 ESM、附带 TypeScript 声明、采用 Apache-2.0 License，并通过 `preview` dist-tag 发布。
+版本：`0.3.5-preview`。BPMN Nova 只发布三个 `@bpmn-nova` 公共包，均使用 ESM、附带 TypeScript 声明、采用 Apache-2.0 License，并通过 `preview` dist-tag 发布。
 
 ## 公共包
 
@@ -3066,6 +4488,8 @@ Core、Model、Renderer、Runtime、Theme、Properties、Node Presentation 和
 
 React/Vue 的声明入口显式重导出宿主常用的 Core 类型：`BpmnEdge`、`BpmnNode`、`EdgeType`、`ElementSelection`、`EngineId`、`LayoutOptions`、`NodeType` 和 `ProcessModel`。业务项目必须从自己选择的 Adapter 导入这些类型，不应仅为类型在 manifest 中增加 Studio 直依赖。
 
+`0.3.5-preview` 另补齐 14 个 Runtime 数据、点击事件及资源 Resolver 类型出口；只修改声明，不增加运行时代码或依赖。完整清单、旧版 Props 推导及宿主接入示例见[审批轨迹接入指南](RUNTIME-INTEGRATION.md)。这些新增出口不属于旧 `0.3.4-preview` 包。
+
 ## Studio 子路径
 
 Studio 根入口重新导出稳定的完整能力；以下子路径用于让导入意图更清晰：
@@ -3109,6 +4533,28 @@ node scripts/build-packages.mjs --package vue
 
 `--package` 不接受内部 Module 名称。三个公开包之外的目录没有发布 manifest、NPM README 或独立版本生命周期。
 
+## 全局统一版本与全量发布
+
+每次发布都是三个公共包的完整发布，不按源码是否改动选择包；未改动的 Adapter 也必须同步升版、构建、验证和发布。此规则不改变宿主只直接安装一个适配包的接入方式。
+
+同一轮目标版本 `V` 必须满足：
+
+```text
+根 package.json.version
+  = @bpmn-nova/studio.version
+  = @bpmn-nova/react.version
+  = @bpmn-nova/vue.version
+  = React 对 Studio 的精确依赖
+  = Vue 对 Studio 的精确依赖
+  = V
+```
+
+根包为私有包，只同步版本，不发布 npm；源码内部 Module 没有独立发布版本。`--package` 仅用于单包构建或打包过程，不能用来跳过本轮某个公共包的发布。
+
+发布前先查询三个包的 Registry 版本，选择统一且未被占用的目标版本，再一起更新上述版本和相关文档，执行 `npm run docs:ai` 生成 AI 文档。本地 `release:check-versions` 检查上述一致性，但不能替代发布后的远端检查。已发布版本不可覆盖；部分成功后的处理见本页“部分发布失败”。
+
+只有三个包的精确目标版本均可安装、Adapter 的 Studio 依赖精确一致、三个包的目标 dist-tag 均解析到 `V`，才算本轮发布完成。当前通道为 `preview`，保持 `latest` 不变；不将“最新版”解释为更新 `latest` 标签。
+
 ## 发布前验证
 
 ```bash
@@ -3140,7 +4586,7 @@ git diff --check
 
 ## 发布顺序
 
-先发布 Studio，确认 Registry 已可解析后，再发布 React 和 Vue：
+每轮必须发布三个包。先发布 Studio，确认 Registry 已可解析后，再发布 React 和 Vue：
 
 ```bash
 (cd packages/studio && npm publish --access public --tag preview)
@@ -3150,14 +4596,20 @@ git diff --check
 
 三个 manifest 都设置了 Preview 发布守卫。仍应显式使用 `--tag preview`，避免预览版本意外覆盖稳定版 `latest`。
 
-发布后核对：
+发布后从仓库根目录核对；下面所有版本输出都应等于根版本，两个依赖也应精确等于该值：
 
 ```bash
-npm view @bpmn-nova/studio@0.3.4-preview version
-npm view @bpmn-nova/react@0.3.4-preview version
-npm view @bpmn-nova/vue@0.3.4-preview version
+release_version=$(node -p "require('./package.json').version")
+npm view "@bpmn-nova/studio@$release_version" version
+npm view "@bpmn-nova/react@$release_version" version dependencies --json
+npm view "@bpmn-nova/vue@$release_version" version dependencies --json
+npm view @bpmn-nova/studio@preview version
+npm view @bpmn-nova/react@preview version
+npm view @bpmn-nova/vue@preview version
 ```
 
+同时比较发布前后三个包的 `dist-tags.latest`，并在临时消费工程中安装本轮产物验证入口和类型。尚未通过远端核对时，报告为“部分发布”或“待验证”，不能报告全部发布成功。
+
 ## Registry 清理说明
 
 Registry 清理是不可逆的外部操作，不由构建脚本自动执行。只有在三个 `0.3.4-preview` 新产物发布、安装和子路径验证均成功后，才能在获得单独明确授权的情况下执行：
@@ -3178,14 +4630,15 @@ Registry 清理是不可逆的外部操作，不由构建脚本自动执行。
 
 1. 使用 `npm view` 确认成功发布的包和版本。
 2. 修复身份、网络或顺序问题。
-3. 如果 Studio 正确而 Adapter 尚未发布，可以继续发布 React/Vue。
-4. 如果已发布 tarball 内容错误，停止本轮发布，修复后提升 Preview 版本并重新构建三个包。
+3. 已成功发布且内容正确的包无需重复发布；继续发布本轮尚未成功的包，直到三个包及其 `preview` 标签均对齐。这是失败恢复，不是按源码改动跳过包。
+4. 如果已发布 tarball 内容错误，停止本轮发布，修复后选择新的统一 Preview 版本，重新构建、验证并发布全部三个包，不能只提升一个包的版本。
 
 ## 文档
 
 - [快速开始](GETTING-STARTED.md)
 - [组件参数](COMPONENTS.md)
 - [公开 API](API.md)
+- [审批轨迹接入指南](RUNTIME-INTEGRATION.md)
 - [AI 接入指南](AI-INTEGRATION.md)
 - [AI 安装执行入口](../llms.txt)