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

package/llms-full.txt

@@ -44,6 +44,20 @@ yarn add @bpmn-nova/vue@preview
 
 Replace `vue` with `react` or `studio` only when the selected framework branch requires it. Run one installation command, not all three.
 
+In TypeScript host code, import shared BPMN model types from that same selected public package. Vue and React explicitly re-export `BpmnEdge`, `BpmnNode`, `EdgeType`, `ElementSelection`, `EngineId`, `LayoutOptions`, `NodeType`, and `ProcessModel`; do not add a direct Studio dependency only to obtain these types:
+
+```ts
+import type {
+  BpmnNode,
+  EdgeType,
+  ElementSelection,
+  NodeType,
+  ProcessModel,
+} from '@bpmn-nova/vue'
+```
+
+Use `@bpmn-nova/react` instead in a React application.
+
 This step is complete when the application manifest contains exactly the selected direct BPMN Nova dependency and the package manager finishes without peer-dependency errors.
 
 ## 3. Select the visual Interface
@@ -59,6 +73,8 @@ Choose the smallest Interface that owns the required experience:
 
 Use `engine="flowable"` or `engine="activiti"` explicitly from the host workflow engine. Do not infer the engine from BPMN XML namespace declarations alone.
 
+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.
+
 ## 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.
@@ -88,7 +104,7 @@ function handleChange(model, reason, xml) {
       engine="flowable"
       mode="design"
       :allowed-edge-types="['sequenceFlow']"
-      :allowed-modes="['design']"
+      :allowed-modes="['design', 'viewer']"
       theme="auto"
       @change="handleChange"
     />
@@ -113,7 +129,7 @@ export function WorkflowEditor({ initialXml, saveDraft }) {
         engine="flowable"
         mode="design"
         allowedEdgeTypes={['sequenceFlow']}
-        allowedModes={['design']}
+        allowedModes={['design', 'viewer']}
         theme="auto"
         onChange={(model, reason, xml) => saveDraft(xml)}
       />
@@ -140,7 +156,7 @@ const shell = createStudioShell({
   container: document.querySelector('#workflow-studio'),
   studio,
   mode: 'design',
-  allowedModes: ['design'],
+  allowedModes: ['design', 'viewer'],
   theme: 'auto',
 })
 
@@ -180,17 +196,25 @@ 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 }">
+    <!-- Host Validate / Save / Publish actions. Validation calls actions.validate(). -->
+  </template>
 </BpmnStudio>
 ```
 
-- Vue uses native `#header-start` / `#header` slots. React uses `headerStart` / `header` render props. Core uses `slots.headerStart` / `slots.header`.
-- Header Start replaces only the Nova Brand. A complete Header replacement calls the public Actions Interface for undo, redo, layout, fit, validation, BPMN import/export, and SVG export.
+- Vue uses native `#header-start` / `#header-actions` / `#header` slots. React uses `headerStart` / `headerActions` / `header` render props. Core uses matching DOM Slots.
+- 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`.
 - 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.
 
+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
 
 - Treat `xml` and `model` as external replacement inputs. Use the emitted/exported XML as the draft output.
@@ -203,9 +227,9 @@ 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. 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 `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.
 
-Use `allowedModes` to expose only host-authorized workbench modes. Pass real Runtime data for instance mode; absence of Runtime data means no approval trace rather than demo business data.
+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.
 
@@ -220,10 +244,11 @@ Run the target application's existing non-destructive quality commands, includin
 3. Create, connect, edit, delete, Undo, and Redo work in design mode.
 4. Change output is persisted and reloads to the same process.
 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()` leaves the current mode unchanged.
+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.
 
 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.
 
@@ -244,7 +269,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.2-preview`。它适合 SDK 评估、产品集成验证和企业审批原型；公开 Interface、BPMN XML round-trip 与引擎兼容能力仍在持续稳定中，建议使用 `@preview` 安装并在生产接入前完成目标流程验证。
+> 当前版本为 `0.3.4-preview`。它适合 SDK 评估、产品集成验证和企业审批原型；公开 Interface、BPMN XML round-trip 与引擎兼容能力仍在持续稳定中，建议使用 `@preview` 安装并在生产接入前完成目标流程验证。
 
 AI 或代码生成工具接入必须从 [`llms.txt`](llms.txt) 的完整安装流程开始；需要全部接口与定制上下文时再读取 [`llms-full.txt`](llms-full.txt)。这两份文件也会随三个公开 npm 包发布。
 
@@ -336,6 +361,20 @@ JavaScript 入口不会自动注入 CSS。使用视觉组件时，请显式导
 
 设计、Viewer、Runtime、Theme、SVG Export、Flowable 和 Activiti 继续保持独立内部 Module，但统一由 Studio 根入口或受支持子路径暴露，不再单独发布。一个业务项目只直接安装上述三个包之一。
 
+TypeScript 宿主也从所选框架包导入公共模型类型，无需为类型再直接安装 Studio。例如 Vue 项目可以直接导入：
+
+```ts
+import type {
+  BpmnNode,
+  EdgeType,
+  ElementSelection,
+  NodeType,
+  ProcessModel,
+} from '@bpmn-nova/vue'
+```
+
+React 项目将入口替换为 `@bpmn-nova/react`。两个 Adapter 还显式重导出 `BpmnEdge`、`EngineId` 与 `LayoutOptions`。
+
 ## 快速开始
 
 视觉组件依赖容器尺寸，请先提供明确高度：
@@ -476,7 +515,7 @@ function onChange(model, reason, nextXml) {
 </template>
 ```
 
-Vue Expose 提供与 Vanilla 实例对应的 Actions、XML、视图、主题和 SVG 导出方法。
+Vue Expose 提供与 Vanilla 实例对应的 Actions、校验、XML、视图、主题和 SVG 导出方法。
 
 ### 嵌入现有业务设计工作台
 
@@ -495,19 +534,66 @@ Vue Expose 提供与 Vanilla 实例对应的 Actions、XML、视图、主题和
   theme="auto"
   @change="handleChange"
   @selection-change="handleSelectionChange"
+  @validation="handleValidation"
 >
   <template #header-start="{ state, actions }">
     <!-- 返回、业务图标、流程名称和类型 -->
   </template>
+  <template #header-actions="{ actions, mode }">
+    <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>
+  </template>
 </BpmnStudio>
 ```
 
-`header-start` 只替换 Nova Brand，`header` 可替换整个 Header；完整替换时通过 `actions` 调用编辑能力。`regions` 隐藏区域后不会保留 Grid 空白，也不会重建 Canvas。React 提供等价的 `headerStart` / `header` Render Prop，Core 提供 `slots.headerStart` / `slots.header`。
+`header-start` 只替换 Nova Brand；`header-actions` 只替换默认的“校验 / 导入 / 导出”动作组，适合宿主组合“校验 / 保存 / 发布”；`header` 可替换整个 Header。`regions` 隐藏区域后不会保留 Grid 空白，也不会重建 Canvas。React 提供等价的 `headerStart` / `headerActions` / `header` Render Prop，Core 提供同名 DOM Slots。默认 Header 的最佳视图只保留在底部缩放区。
+
+`actions.validate()` 会先更新 Nova 默认状态栏，再发送 `validation` 事件并返回 issues；公开 `validate()` 使用相同流程。`valid` 只在存在 error 时为 `false`，warning 会展示和上报但不默认阻止发布。
+
+发布事务由宿主实现，并可以直接复用同一个 Header Action 完成“校验后发布”：
+
+```js
+async function publishProcess(actions) {
+  const issues = actions.validate()
+  if (issues.some((issue) => issue.level === 'error')) return
+  await publishXml(actions.exportXml())
+}
+```
 
 宿主右侧属性面板应位于 Nova 外部，并以 `selection-change` / `onSelectionChange` 为状态来源、以稳定 BPMN Element ID 关联业务配置。`element-click` 不能替代选择事件。Nova 不拥有宿主的保存、发布、权限或服务端事务。
 
 `theme="auto"` 是显式启用系统主题适配；为了兼容已有接入，未传 Theme 时仍默认为 `light`。Vue 包同时提供独立的 `BpmnPalettePanel`，用于完全自定义布局。
 
+Shell 的 `design`、`viewer`、`instance` 分别表示流程设计、流程展示和审批轨迹。宿主可以观察并在运行时调整可用模式，而不会写入 BPMN Model 或 Undo/Redo History：
+
+```js
+const offMode = shell.subscribeMode(({ mode, previousMode, source }) => {
+  console.log(previousMode, mode, source)
+})
+
+shell.setMode('viewer') // 成功切换返回 true
+shell.setAllowedModes(['design', 'viewer'])
+```
+
+业务系统只需要覆盖标准节点卡片的定义态副标题时，可以提供轻量 Resolver。`undefined` 保留 Nova 默认值，`null` 隐藏副标题行，字符串替换显示值；外部 Map 等数据变化后显式调用 `refreshPresentation()`。该刷新不改 XML、历史、选择或视口，且不会覆盖 `instance` 的运行事实。
+
+```js
+const subtitles = new Map()
+const shell = createStudioShell({
+  container,
+  studio,
+  nodeSubtitleResolver: ({ node }) => subtitles.has(node.id)
+    ? subtitles.get(node.id)
+    : undefined,
+})
+
+subtitles.set('ServiceTask_Archive', '归档到采购系统')
+shell.refreshPresentation()
+```
+
+`allowedNodeTypes` 会过滤 Palette 和所有建模入口；一个节点类型仍可能由多个 Palette Preset 创建。副标题 Resolver 只是视觉投影，不能替代标准 BPMN Candidate 配置或 Runtime Snapshot。
+
 ## 审批动作、图文与附件
 
 Runtime Snapshot 使用动作描述提交、通过、驳回、加签、转办等事实。内容只保存安全文本和资源引用，不保存 URL、Base64、`Blob`、Markdown 或 HTML。
@@ -661,11 +747,13 @@ shell.openSvgExportPreview()
 | Properties | 注册 Provider、Group、Entry、Data Provider、校验和自定义组件 |
 | Icons | 覆盖内置图标或注册业务图标 |
 | Node Renderer | 自定义 Canvas / Viewer 节点内容和运行态摘要 |
+| Node Subtitle Resolver | 轻量覆盖 Design / Viewer 标准节点副标题并无历史刷新 |
 | Runtime Details Renderer | 自定义 Popover / Bottom Sheet 审批详情 |
 | Runtime Timeline Renderer | 自定义移动时间线条目、动作和资源布局 |
 | Runtime Transition Renderer | 自定义驳回、退回和异常线路 |
 | SVG Renderer | 为自定义节点或时间线提供纯 SVG 导出视觉 |
 | Context Menu / Slot | 扩展设计器操作、工具区和宿主内容 |
+| Studio Mode Interface | 观察并运行时控制设计、展示与审批轨迹模式 |
 | React / Vue Bridge | 通过 Props、Ref / Expose 与组合式接口接入上述能力 |
 
 完整接口和示例见[自定义指南](docs/CUSTOMIZATION.md)与[组件参数](docs/COMPONENTS.md)。
@@ -761,6 +849,14 @@ npm test
 
 已经安装三个公开包之一且与目标技术栈匹配时，沿用现有入口。React 和 Vue 同时存在但无法确定目标应用时先询问用户。`@bpmn-nova/core`、`designer`、`viewer`、`runtime`、`theme`、`export-svg`、`properties` 等历史入口不参与选择；这些能力已经收进 Studio，并通过根入口或受支持子路径提供。
 
+TypeScript 代码必须从已经选择的公开包导入共享类型。React/Vue Adapter 均显式重导出 `BpmnEdge`、`BpmnNode`、`EdgeType`、`ElementSelection`、`EngineId`、`LayoutOptions`、`NodeType` 和 `ProcessModel`；不要仅为了这些类型安装或声明 `@bpmn-nova/studio`：
+
+```ts
+import type { BpmnNode, ElementSelection, NodeType, EdgeType, ProcessModel } from '@bpmn-nova/vue'
+```
+
+React 应用把入口替换为 `@bpmn-nova/react`。
+
 所有示例都必须满足：
 
 - 导入对应公开包的 `styles.css`。
@@ -808,7 +904,7 @@ const shell = createStudioShell({
   container: document.querySelector('#studio'),
   studio,
   mode: 'design',
-  allowedModes: ['design'],
+  allowedModes: ['design', 'viewer'],
   theme: 'auto',
 })
 
@@ -827,6 +923,10 @@ export function disposeWorkflow() {
 
 Shell 负责界面组合，Controller 负责模型、命令、选择和历史。外部传入的 Controller 不会因 Shell 销毁而自动销毁。
 
+Mode 是 Shell 展示状态。`design`、`viewer`、`instance` 分别表示流程设计、流程展示和审批轨迹；使用 `getMode()` / `setMode()` / `setAllowedModes()` / `subscribeMode()` 与宿主状态同步，不要把 Mode 写进 BPMN Model 或 Studio State。
+
+定义态业务摘要使用同步 `nodeSubtitleResolver`，按稳定 `node.id` 查询宿主数据。返回 `undefined` 保留 Nova 默认副标题，`null` 删除该行，字符串覆盖显示。外部 Map 更新后调用 `refreshPresentation()`；不要调用 `updateNode()`、重新导入 XML 或重建组件来刷新纯视觉摘要。Instance 模式继续完全使用 Runtime Presentation。
+
 ### 2.2 独立 Designer 或 Viewer
 
 独立能力仍由 Studio 提供，不要安装旧包：
@@ -870,12 +970,13 @@ npm install @bpmn-nova/react@preview
 ```
 
 ```jsx
-import { useRef } from 'react'
+import { useRef, useState } from 'react'
 import { BpmnStudio } from '@bpmn-nova/react'
 import '@bpmn-nova/react/styles.css'
 
 export function WorkflowEditor({ initialXml }) {
   const studioRef = useRef(null)
+  const [mode, setMode] = useState('design')
 
   return (
     <div style={{ height: 720 }}>
@@ -883,18 +984,19 @@ export function WorkflowEditor({ initialXml }) {
         ref={studioRef}
         xml={initialXml}
         engine="flowable"
-        mode="design"
-        allowedModes={['design']}
+        mode={mode}
+        allowedModes={['design', 'viewer']}
         theme="auto"
         propertiesProfile="business"
         onChange={(model, reason, nextXml) => saveDraft(nextXml)}
+        onModeChange={(event) => setMode(event.mode)}
       />
     </div>
   )
 }
 ```
 
-需要只读或审批轨迹时使用 React 包导出的 `BpmnViewer`，传入 `model`、`runtime`、`projection`、`runtimeAssetResolver` 和 `runtimeAppearance`。Ref 可访问 `exportXml()`、`exportSvg()`、`openSvgExportPreview()`、`fitView()` 和 `setTheme()`；实际可用方法以类型声明为准。
+需要只读或审批轨迹时使用 React 包导出的 `BpmnViewer`，传入 `model`、`runtime`、`projection`、`runtimeAssetResolver` 和 `runtimeAppearance`。Ref 可访问实际 `mode`、`setMode()`、`refreshPresentation()`、`exportXml()`、`exportSvg()`、`openSvgExportPreview()`、`fitView()` 和 `setTheme()`；Header Render Context 同步提供 `mode`。实际可用方法以类型声明为准。
 
 不要在 React effect 中每次渲染都重新创建 Vanilla 实例。优先使用 Adapter 组件，让属性变化更新现有实例。
 
@@ -912,6 +1014,7 @@ import '@bpmn-nova/vue/styles.css'
 
 const props = defineProps({ initialXml: String })
 const studioRef = ref(null)
+const mode = ref('design')
 const onChange = (model, reason, nextXml) => saveDraft(nextXml)
 </script>
 
@@ -921,23 +1024,28 @@ const onChange = (model, reason, nextXml) => saveDraft(nextXml)
       ref="studioRef"
       :xml="props.initialXml"
       engine="flowable"
-      mode="design"
-      :allowed-modes="['design']"
+      v-model:mode="mode"
+      :allowed-modes="['design', 'viewer']"
       theme="auto"
       properties-profile="business"
       @change="onChange"
+      @mode-change="event => console.log(event.source)"
     />
   </div>
 </template>
 ```
 
-需要只读或审批轨迹时使用 Vue 包导出的 `BpmnViewer`。事件使用 kebab-case；Expose 提供的实例能力以包内类型声明为准。不要在 watcher 中重复挂载组件，主题、Runtime、Projection 和 Regions 应通过响应式属性更新。
+需要只读或审批轨迹时使用 Vue 包导出的 `BpmnViewer`。事件使用 kebab-case，`v-model:mode` 由 `update:mode` 驱动，`mode-change` 提供来源与前后值；Expose 包含 `getMode()`、`setMode()` 与 `refreshPresentation()`。不要在 watcher 中重复挂载组件，Mode、Theme、Runtime、Projection、Regions 和 Resolver 应通过响应式属性或轻量刷新更新。
 
 ### 4.1 宿主工作台组合规则
 
 默认 `BpmnStudio` 是完整工作台。只有宿主明确拥有自己的区域时才配置 `regions`；例如 DX 复用自己的业务属性面板时使用 `regions: { right: 'hidden' }`，并把该面板放在 Nova 外部。隐藏区域不保留 Grid 轨道。
 
-Vue 使用原生 `#header-start` / `#header`，React 使用 `headerStart` / `header` Render Prop。Header Start 只替换 Brand，完整 Header 通过公开 `StudioShellActions` 重建所需编辑操作。不要创建第二个 Vue App 或 React Root 挂载 Header。
+Vue 使用原生 `#header-start` / `#header-actions` / `#header`，React 使用 `headerStart` / `headerActions` / `header` Render Prop。Header Start 只替换 Brand，Header Actions 只替换默认“校验 / 导入 / 导出”动作组，完整 Header 通过公开 `StudioShellActions` 重建所需编辑操作。不要创建第二个 Vue App 或 React Root 挂载 Header。
+
+宿主通常在 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` 会原地更新默认模式按钮，移除当前模式时只回退一次。
 
 外部业务属性面板必须以 `selection-change` / `onSelectionChange` 为状态来源，以稳定 BPMN Element ID 关联业务配置。该事件覆盖节点、连线、多选、清空和键盘选择；`element-click` / `onElementClick` 只是点击观察事件。保存草稿、发布、权限和服务端事务属于宿主，不要写入 Nova Actions。
 
@@ -949,7 +1057,7 @@ Vue 使用原生 `#header-start` / `#header`，React 使用 `headerStart` / `hea
 
 React/Vue 包重新导出创建外部 Controller、Palette、Properties、Context Menu、Icon 和 Template Registry 所需的公开函数，因此高级接入仍只需要直接安装对应 Adapter 包。
 
-生产工作流通常只支持 BPMN 子集。通过 Controller 或 `BpmnStudio` 的 `allowedNodeTypes` 与 `allowedEdgeTypes` 声明节点、连线白名单；该限制会校验初始/外部模型，并约束创建、快捷新增、模板和节点类型转换。通过 `allowedModes` 限制工作台可切换模式。实例模式没有 Runtime 时保持空运行事实，不会自动加载演示数据。
+生产工作流通常只支持 BPMN 子集。通过 Controller 或 `BpmnStudio` 的 `allowedNodeTypes` 与 `allowedEdgeTypes` 声明节点、连线白名单；该限制会校验初始/外部模型，并约束创建、快捷新增、模板和节点类型转换。Palette 会服从节点白名单，但同一节点类型可以有多个 Preset。通过 `allowedModes` 限制工作台可切换模式。实例模式没有 Runtime 时保持空运行事实，不会自动加载演示数据。
 
 ## 5. Runtime Snapshot 与审批动作
 
@@ -1136,7 +1244,7 @@ BPMN Nova 负责 BPMN 建模、XML 导入导出、只读展示、运行态审批
 
 # BPMN Nova 快速开始
 
-本文面向通过 NPM 集成 BPMN Nova 的应用开发者。版本 `0.3.2-preview` 要求现代浏览器；Node.js 18+ 用于构建、SSR 和开发工具。
+本文面向通过 NPM 集成 BPMN Nova 的应用开发者。版本 `0.3.4-preview` 要求现代浏览器；Node.js 18+ 用于构建、SSR 和开发工具。
 
 ## 1. 按语言与框架选择入口
 
@@ -1152,6 +1260,20 @@ JavaScript 与 TypeScript 使用相同的包和导入方式。所有公开包都
 
 Core、Viewer、Runtime、Theme 等目录不再是可直接安装的 NPM 包。Vanilla 项目从 Studio 根入口或受支持子路径导入；React/Vue 项目使用对应 Adapter。
 
+React/Vue Adapter 同时是公共 TypeScript 类型门面。模型、选区与图元类型从所选 Adapter 直接导入，不需要额外安装 Studio：
+
+```ts
+import type {
+  BpmnNode,
+  EdgeType,
+  ElementSelection,
+  NodeType,
+  ProcessModel,
+} from '@bpmn-nova/vue'
+```
+
+React 项目使用 `@bpmn-nova/react`；两个入口还重导出 `BpmnEdge`、`EngineId` 和 `LayoutOptions`。
+
 每个视觉包都有自己的完整样式入口。JavaScript 不会隐式插入 CSS：
 
 ```js
@@ -1205,7 +1327,7 @@ const shell = createStudioShell({
   container: document.querySelector('#studio'),
   studio,
   mode: 'design',
-  allowedModes: ['design'],
+  allowedModes: ['design', 'viewer'],
   theme: 'auto',
 })
 
@@ -1226,6 +1348,38 @@ function dispose() {
 
 Controller 持有模型、命令、选择、历史与作用域；Shell 只负责组合 Canvas、Palette、Properties 和 Viewer。销毁 Shell 不会自动销毁外部传入的 Controller。
 
+宿主可观察实际 Mode，并在运行时调整白名单：
+
+```js
+const offMode = shell.subscribeMode(({ mode, source }) => {
+  externalProperties.hidden = mode !== 'design'
+  console.log(source)
+})
+
+shell.setMode('viewer')
+shell.setAllowedModes(['design', 'viewer'])
+```
+
+`design` 是流程设计，`viewer` 是流程展示，`instance` 是审批轨迹。Mode 只属于 Shell 展示状态，不会进入 BPMN Model 或撤销历史。
+
+业务数据需要显示在标准节点副标题时，传入同步 `nodeSubtitleResolver`；闭包中的 Map 更新后调用无历史刷新：
+
+```js
+const subtitles = new Map()
+const shell = createStudioShell({
+  container,
+  studio,
+  nodeSubtitleResolver: ({ node }) => subtitles.has(node.id)
+    ? subtitles.get(node.id)
+    : undefined,
+})
+
+subtitles.set('ServiceTask_Archive', '归档到采购系统')
+shell.refreshPresentation()
+```
+
+`undefined` 使用 Nova 默认值，`null` 删除该行。该 Resolver 只影响 Design/Viewer 与 SVG 标准视觉；Instance 仍由 Runtime Snapshot/Presentation 决定。`allowedNodeTypes` 会过滤 Palette，但同一节点类型可以继续提供多个业务 Preset。
+
 ## 4. XML 导入与导出
 
 ```js
@@ -1244,7 +1398,7 @@ const activitiXml = studio.exportXml('activiti')
 const issues = studio.model.nodes.length ? [] : ['流程没有节点']
 ```
 
-独立 `BpmnDesigner` 提供内置 `validate()`；Studio 当前通过属性规则和命令约束模型，宿主也可以添加自己的发布校验。
+独立 `BpmnDesigner` 提供纯校验 `validate()`。完整 Studio 则通过 `actions.validate()` 或 Shell/框架公开的 `validate()` 执行 Nova 校验、更新内部状态摘要、发送校验事件并返回 issues；宿主仍可在发布前追加自己的业务规则。
 
 `allowedNodeTypes` 与 `allowedEdgeTypes` 是完整模型约束：初始模型和后续导入包含白名单外节点或连线时会拒绝，Palette、连接、快捷新增、模板及节点类型转换也使用同一约束。只有确实支持全部 Nova 图元的宿主才省略它们。
 
@@ -1325,12 +1479,14 @@ npm install @bpmn-nova/react@preview
 ```
 
 ```jsx
-import { useRef } from 'react'
+import { useCallback, useRef, useState } from 'react'
 import { BpmnStudio } from '@bpmn-nova/react'
 import '@bpmn-nova/react/styles.css'
 
 export function WorkflowEditor({ initialXml }) {
   const ref = useRef(null)
+  const [mode, setMode] = useState('design')
+  const subtitleResolver = useCallback(({ node, defaultSubtitle }) => defaultSubtitle, [])
 
   return (
     <div style={{ height: 720 }}>
@@ -1338,12 +1494,14 @@ export function WorkflowEditor({ initialXml }) {
         ref={ref}
         xml={initialXml}
         engine="flowable"
-        mode="design"
-        allowedModes={['design']}
+        mode={mode}
+        allowedModes={['design', 'viewer']}
+        nodeSubtitleResolver={subtitleResolver}
         propertiesProfile="business"
         theme="auto"
         onChange={(model, reason, nextXml) => saveDraft(nextXml)}
         onSelectionChange={(selection, element) => console.log(element)}
+        onModeChange={(event) => setMode(event.mode)}
       />
     </div>
   )
@@ -1357,7 +1515,7 @@ const { studio, state, commands } = useBpmnStudio({ model })
 return <BpmnStudio studio={studio} />
 ```
 
-Ref 可访问 `studio`、`shell`、`actions`、`exportXml()`、`fitView()` 和 `setTheme()`。
+Ref 可访问 `studio`、`shell`、`actions`、实际 `mode`、`setMode()`、`validate()`、`refreshPresentation()`、`exportXml()`、`fitView()` 和 `setTheme()`。`onValidation` 在 Nova 内部状态展示完成后收到校验结果；Header Render Context 同样提供响应式实际 `mode`。
 
 ## 8. Vue 3.3+
 
@@ -1375,6 +1533,7 @@ import '@bpmn-nova/vue/styles.css'
 
 const props = defineProps({ initialXml: String })
 const studioRef = ref(null)
+const mode = ref('design')
 const onChange = (model, reason, nextXml) => saveDraft(nextXml)
 </script>
 
@@ -1384,17 +1543,19 @@ const onChange = (model, reason, nextXml) => saveDraft(nextXml)
       ref="studioRef"
       :xml="props.initialXml"
       engine="flowable"
-      mode="design"
-      :allowed-modes="['design']"
+      v-model:mode="mode"
+      :allowed-modes="['design', 'viewer']"
       properties-profile="business"
       theme="auto"
       @change="onChange"
+      @mode-change="event => console.log(event.source)"
+      @validation="event => console.log(event.valid, event.issues)"
     />
   </div>
 </template>
 ```
 
-Vue 事件使用 kebab-case：`change`、`selection-change`、`scope-change`、`element-click` 和 `trace-click`。Expose 提供 `getStudio()`、`getShell()`、`getActions()`、`exportXml()`、`fitView()` 与 `setTheme()`。
+Vue 事件使用 kebab-case：`change`、`selection-change`、`scope-change`、`element-click`、`trace-click`、`update:mode`、`mode-change` 和 `validation`。Expose 提供 `getStudio()`、`getShell()`、`getActions()`、`getMode()`、`setMode()`、`validate()`、`refreshPresentation()`、`exportXml()`、`fitView()` 与 `setTheme()`；Header Slot Context 的 `mode` 为响应式实际状态。
 
 框架组件把 `xml`/`model` 作为外部替换输入，把 `change`/`onChange` 的 XML 作为草稿输出。完全相同的导出 XML 回写会被忽略并保留 Undo/Redo；不同 XML 表示宿主有意加载另一流程或服务器 revision，会替换模型并重置历史。React/Vue 包也重新导出了外部 Controller 和各类 Registry 的创建函数，高级接入无需直接安装 Studio。
 
@@ -1415,14 +1576,28 @@ Vue 事件使用 kebab-case：`change`、`selection-change`、`scope-change`、`
   theme="auto"
   @change="handleChange"
   @selection-change="handleSelectionChange"
+  @validation="handleValidation"
 >
   <template #header-start="{ state, actions }">
     <!-- 返回、业务图标、流程名称、类型 -->
   </template>
+  <template #header-actions="{ actions, mode }">
+    <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>
+  </template>
 </BpmnStudio>
 ```
 
-Vue 的 `#header-start` 只替换 Brand，`#header` 替换完整 Header；React 使用等价的 `headerStart` / `header` Render Prop。完整 Header 中使用公开 Actions 执行编辑操作。`regions` 属性变化会原地更新区域，不重建 Canvas。
+Vue 的 `#header-start` 只替换 Brand，`#header-actions` 只替换默认“校验 / 导入 / 导出”动作组，`#header` 替换完整 Header；React 使用等价的 `headerStart` / `headerActions` / `header` Render Prop。顶部最佳视图已去重，底部入口与 `fitView()` 保留。`actions.validate()` 先展示 Nova 内部结果，再发送 `validation` / `onValidation`，最后返回 issues。`regions` 属性变化会原地更新区域，不重建 Canvas。
+
+```js
+async function publishProcess(actions) {
+  const issues = actions.validate()
+  if (issues.some((issue) => issue.level === 'error')) return
+  await publishXml(actions.exportXml())
+}
+```
 
 把宿主属性面板放在 Nova 外部，以 `selection-change` / `onSelectionChange` 作为状态来源，并用稳定 BPMN Element ID 关联业务配置。该事件覆盖节点、连线、多选、清空和键盘选择；`element-click` 不能替代选择状态。Nova 不负责保存、发布、权限或服务端事务。
 
@@ -1485,7 +1660,7 @@ BPMN Nova 主题应挂在组件根容器。自定义 Renderer 不要修改 `docu
 
 # BPMN Nova 组件参数
 
-本手册记录 `0.3.2-preview` 的公开组件参数、回调和实例方法。所有视觉组件都需要具有实际尺寸的容器，并显式导入所属包的 `styles.css`。
+本手册记录 `0.3.4-preview` 的公开组件参数、回调和实例方法。所有视觉组件都需要具有实际尺寸的容器，并显式导入所属包的 `styles.css`。
 
 ## 按项目环境阅读
 
@@ -1561,16 +1736,19 @@ Controller 不创建 DOM，负责模型、命令、历史、选择与子流程
 | `templateRegistry` | `TemplateRegistry` | 默认 Registry | 企业模板入口 |
 | `contextMenuRegistry` | `ContextMenuRegistry` | 默认 Registry | 右键动作入口 |
 | `rendererOptions` | `DiagramRendererOptions` | `{}` | 节点与 Runtime Renderer 配置 |
+| `nodeSubtitleResolver` | `NodeSubtitleResolver` | 无 | 覆盖 Design/Viewer 标准节点副标题；不影响 Instance |
 | `slots` | `StudioShellSlots` | `{}` | 局部 UI 替换 |
 | `regions` | `StudioShellRegions` | 全部 `default` | 原地隐藏 Header、Palette、Properties 或 Statusbar；隐藏后不保留轨道 |
 | `layout` | `Function` | 默认三栏布局 | 完整布局替换 |
 | `onThemeChange` | `(state) => void` | 无 | 主题模式解析变化回调 |
 
-实例方法包括 `getRegions()`、`setRegions()`、`setMode()`、`setRuntime()`、`setProjection()`、`setTheme()`、`setRuntimeAppearance()`、`fitView()`、`zoomBy()`、`exportSvg()`、`openSvgExportPreview()` 和 `destroy()`。
+实例方法包括 `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`。
 
 `shell.actions` 是默认 Header 与宿主自定义 Header 共用的稳定 Interface，提供 `undo()`、`redo()`、`beautify()`、`rerouteEdges()`、`fitView()`、`validate()`、`importXml()`、`exportXml()`、`exportSvg()` 和 `openSvgExportPreview()`。它不包含保存、发布、权限或文件上传等宿主业务动作。
 
-`slots.headerStart` 只替换 Nova Brand，保留默认模式区和工具区；`slots.header` 完整替换 Header，且优先级更高。Slot Context 提供 `studio`、`shell`、`canvas`、`actions`、`getState()` 和 `subscribe()`。`regions.header = 'hidden'` 的优先级最高。`layout()` 与 `regions` 不能同时使用。
+`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` 不能同时使用。
+
+`actions.validate()` 先更新 Nova 默认状态栏，再发送一次来源为 `toolbar` 的 Validation Event 并返回 issues；实例 `validate()` 的来源为 `api`。事件 `valid` 只由 error 决定，warning 不默认阻止发布。
 
 ## `BpmnDesigner`
 
@@ -1611,13 +1789,14 @@ new BpmnDesigner(options)
 | `runtimeDetailsRenderer` | `RuntimeDetailsRenderer \| null` | 默认 Renderer | 替换或关闭节点详情 |
 | `runtimeTransitionDetailsRenderer` | `RuntimeTransitionDetailsRenderer \| null` | 默认 Renderer | 替换或关闭异常转移详情 |
 | `nodeRenderers` | `Record<string, NodeRenderer>` | `{}` | 按节点类型替换内部内容 |
+| `nodeSubtitleResolver` | `NodeSubtitleResolver` | 无 | 定义态标准节点副标题视觉投影 |
 | `onTraceClick` | `(event) => void` | 无 | 统一节点、线路、Visit、Transition 点击 |
 | `onElementClick` | `(payload) => void` | 无 | 基础元素点击 |
 | `onProjectionChange` | `({ requested, active }) => void` | 无 | 实际投影变化 |
 | `theme` | `NovaThemeInput` | `light` | 实例主题 |
 | `runtimeAppearance` | `RuntimeAppearanceOptions` | 默认映射 | Runtime 语义外观 |
 
-实例方法：`setModel()`、`setRuntime()`、`setProjection()`、`setDisplayOptions()`、`setTheme()`、`setRuntimeAppearance()`、`fitView()`、`openRuntimeDetails()`、`openRuntimeTransitionDetails()`、`closeRuntimeDetails()` 和 `destroy()`。
+实例方法：`setModel()`、`setRuntime()`、`setProjection()`、`setDisplayOptions()`、`refreshPresentation()`、`setTheme()`、`setRuntimeAppearance()`、`fitView()`、`openRuntimeDetails()`、`openRuntimeTransitionDetails()`、`closeRuntimeDetails()` 和 `destroy()`。Compact Runtime Timeline 中 `refreshPresentation()` 安全 No-op。
 
 ## `BpmnCanvas`
 
@@ -1626,6 +1805,7 @@ new BpmnDesigner(options)
 | `container` | `HTMLElement` | 必填 | 画布容器 |
 | `studio` | `BpmnStudioController` | 必填 | Controller |
 | `rendererOptions` | `DiagramRendererOptions` | `{}` | Renderer 配置 |
+| `nodeSubtitleResolver` | `NodeSubtitleResolver` | 无 | 标准节点副标题 Resolver |
 | `interactions` | `InteractionController \| null` | `null` | Palette 拖放协议 |
 | `selectionToolbar` | `HTMLElement \| SelectionToolbarSlot \| null` | 默认工具栏 | 框选工具栏替换 |
 | `contextMenu` | `HTMLElement \| ContextMenuSlot \| null` | 默认菜单 | 右键菜单替换 |
@@ -1633,7 +1813,7 @@ new BpmnDesigner(options)
 | `pointerMode` | `'select' \| 'marquee' \| 'pan'` | `'select'` | 指针模式 |
 | `theme` | `NovaThemeInput` | `light` | 实例主题 |
 
-常用方法：`clientToWorld()`、`fitView()`、`fitSelection()`、`setPointerMode()`、`zoomBy()`、`actualSize()` 和 `destroy()`。
+常用方法：`clientToWorld()`、`fitView()`、`fitSelection()`、`setPointerMode()`、`zoomBy()`、`actualSize()`、`refreshPresentation()` 和 `destroy()`。
 
 ## `PalettePanel`
 
@@ -1678,14 +1858,17 @@ new BpmnDesigner(options)
 | `allowedNodeTypes` | 创建内部 Controller 时使用的完整模型节点白名单 |
 | `allowedEdgeTypes` | 创建内部 Controller 时使用的完整模型连线白名单 |
 | `allowedModes` | Shell 显示并允许切换的工作台模式 |
+| `mode` / `onModeChange` | 受控输入与实际 Mode 事件；Header Render Context 同步提供 `mode` |
+| `nodeSubtitleResolver` | Design/Viewer 标准节点副标题 Resolver |
 | `contextMenuRegistry` | 自定义右键动作 Registry |
 | `regions` | 默认 Shell 区域显隐；属性变化原地调用 `setRegions()` |
-| `headerStart` / `header` | React Node 或 Render Prop；使用 Portal 保留宿主 Context |
+| `headerStart` / `headerActions` / `header` | React Node 或 Render Prop；使用 Portal 保留宿主 Context |
+| `onValidation` | Nova 内部校验展示完成后的只读结果事件 |
 | `onChange(model, reason, xml)` | 模型变化 |
 | `onSelectionChange(selection, element)` | 选择变化 |
 | `onScopeChange(activeScopeId, scopePath, state)` | 子流程作用域变化 |
 
-Ref：`studio`、`shell`、`actions`、`exportXml()`、`fitView()`、`setTheme()`。
+Ref：`studio`、`shell`、`actions`、`mode`、`getMode()`、`setMode()`、`setAllowedModes()`、`validate()`、`refreshPresentation()`、`exportXml()`、`fitView()`、`setTheme()`。
 
 `xml`/`model` 是外部替换输入。回写与最近导出完全相同的 XML 不会重复导入或清空 Undo/Redo；不同 XML 会替换模型和历史。React/Vue 包均重新导出创建外部 Controller 与 Palette、Properties、Context Menu、Icon、Template Registry 所需的公开函数。
 
@@ -1695,7 +1878,7 @@ Props：`model`、`xml`、`engine`、`theme`、`onChange`、`onSelectionChange`
 
 ### `BpmnViewer`
 
-接受除 `container/model` 外的 `ViewerOptions`，并通过 `model` 或 `xml` 输入流程。Ref：`instance`、`fitView()`、`setProjection()`、`setRuntime()`、`setDisplayOptions()`、`setTheme()`。
+接受除 `container/model` 外的 `ViewerOptions`，并通过 `model` 或 `xml` 输入流程。Ref：`instance`、`fitView()`、`refreshPresentation()`、`setProjection()`、`setRuntime()`、`setDisplayOptions()`、`setTheme()`。
 
 ### `BpmnCanvas` / `BpmnPalettePanel` / `BpmnPropertiesPanel`
 
@@ -1705,11 +1888,11 @@ Props：`model`、`xml`、`engine`、`theme`、`onChange`、`onSelectionChange`
 
 Vue 组件与 React 使用同一底层接口，主要差异为：
 
-- Studio 提供原生 `#header-start` 和 `#header` Slot，通过 Teleport 保留宿主 provide/inject、响应式状态和生命周期。
-- `slotsConfig` 继续保留，作为高级 Core DOM Slot 入口；原生完整 Header、Core 完整 Header、原生 Header Start、Core Header Start 依次降级。
-- 事件为 `change`、`selection-change`、`scope-change`、`element-click`、`trace-click`。
+- Studio 提供原生 `#header-start`、`#header-actions` 和 `#header` Slot，通过 Teleport 保留宿主 provide/inject、响应式状态和生命周期。
+- `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`。
 - `BpmnDesigner` 发出 `change`、`selection-change`。
-- Ref Expose 使用 `getStudio()`、`getShell()`、`getActions()` 或 `getInstance()`，不直接暴露可替换字段。
+- Header Slot Context 的 `mode` 是响应式实际状态。Ref Expose 使用 `getStudio()`、`getShell()`、`getActions()`、`getMode()`、`setMode()`、`setAllowedModes()`、`validate()`、`refreshPresentation()` 或 `getInstance()`，不直接暴露可替换字段。
 
 Vue 提供 `BpmnStudio`、`BpmnDesigner`、`BpmnViewer`、`BpmnCanvas`、`BpmnPalettePanel`、`BpmnPropertiesPanel` 和 `useBpmnStudio()`。独立 `BpmnPalettePanel` 复用外部 Studio；传入 Registry 时不会隐式注册 Providers，未传 Registry 时才用 Providers 创建默认 Registry。
 
@@ -1733,7 +1916,23 @@ Runtime Details、Timeline 和 Transition Details 组件通过对应 `createReac
 
 <!-- SOURCE: docs/API.md -->
 
-# BPMN Nova v0.3.2 Preview API
+# BPMN Nova v0.3.4 Preview API
+
+## Framework Adapter 类型门面
+
+React/Vue 项目只直接依赖对应 Adapter。两个 Adapter 的根声明入口显式重导出 `BpmnEdge`、`BpmnNode`、`EdgeType`、`ElementSelection`、`EngineId`、`LayoutOptions`、`NodeType` 和 `ProcessModel`，宿主无需仅为这些公共类型增加 Studio 直依赖：
+
+```ts
+import type {
+  BpmnNode,
+  EdgeType,
+  ElementSelection,
+  NodeType,
+  ProcessModel,
+} from '@bpmn-nova/vue'
+```
+
+React 使用相同名称，并将入口替换为 `@bpmn-nova/react`。这些是 TypeScript-only export，不会增加 Adapter 的浏览器运行时代码。
 
 ## Designer
 
@@ -1845,6 +2044,69 @@ const shell = createStudioShell({
 
 React/Vue Adapter 的 `BpmnStudio` 接受同名 `allowedNodeTypes`、`allowedEdgeTypes` 和 `allowedModes`。框架 `xml`/`model` 是外部替换输入；回写与当前导出完全相同的 XML 不会重新导入或清空历史，不同 XML 会替换模型并重置历史。
 
+### Studio Mode Interface
+
+```ts
+type StudioMode = 'design' | 'viewer' | 'instance'
+type StudioModeChangeSource = 'toolbar' | 'api' | 'allowed-modes'
+
+interface StudioModeChangeEvent {
+  readonly mode: StudioMode
+  readonly previousMode: StudioMode
+  readonly source: StudioModeChangeSource
+  readonly allowedModes: readonly StudioMode[]
+}
+```
+
+```js
+shell.getMode()
+shell.getAllowedModes()
+shell.setMode('viewer')
+shell.setAllowedModes(['design', 'viewer'])
+const off = shell.subscribeMode((event) => console.log(event))
+```
+
+`setMode()` 只在完成一次真实切换时返回 `true`。同模式、不允许的模式或已销毁 Shell 返回 `false`，不重建也不发事件。`setAllowedModes()` 先完整校验非空、唯一且已知的 Mode；移除当前 Mode 时回退到新列表首项，只发送一次 `allowed-modes` 事件。事件在新视图挂载和 Shell UI 同步后发送，Mode 不进入 Controller State 或 History。
+
+### Studio Validation Interface
+
+```ts
+type StudioValidationSource = 'toolbar' | 'api'
+
+interface StudioValidationEvent {
+  readonly source: StudioValidationSource
+  readonly valid: boolean
+  readonly errorCount: number
+  readonly warningCount: number
+  readonly issues: readonly StudioValidationIssue[]
+}
+```
+
+`shell.actions.validate()` 用于默认或宿主 Header，来源为 `toolbar`；`shell.validate()` 用于程序调用，来源为 `api`。两者都会先运行纯 `studio.validate()`，同步更新 Nova 默认状态栏，再向 `subscribeValidation()` Listener 发送一次只读结果，最后返回兼容的 issues 数组。`valid` 等价于 `errorCount === 0`，warning 不默认阻止保存或发布。隐藏或替换默认 Footer 时事件与返回值不受影响，只是不再强制显示 Nova 状态摘要。
+
+Vue 将事件透传为 `validation` 并 Expose `validate()`；React 使用 `onValidation` 和 Ref `validate()`。Listener 异常不会阻断其他 Listener、内部状态展示或返回值。
+
+### Node Subtitle Resolver 与刷新
+
+```ts
+interface NodeSubtitleResolverContext {
+  readonly node: BpmnNode
+  readonly definition: NodeDefinition
+  readonly model: ProcessModel
+  readonly mode: 'design' | 'viewer'
+  readonly surface: 'canvas' | 'svg-export'
+  readonly defaultSubtitle: string
+}
+
+type NodeSubtitleResolver = (
+  context: Readonly<NodeSubtitleResolverContext>,
+) => string | null | undefined
+```
+
+`undefined` 保留默认值，`null` 删除副标题行，字符串替换视觉值；空字符串是显式字符串，不等同于隐藏。Resolver 必须同步，异常、Promise 或非法返回会抛出包含节点 ID 的错误。它只作用于 Design/Viewer 的标准任务和容器卡片；事件、网关、泳道等不会新增副标题槽，完整自定义 Renderer 优先，Instance 始终使用 Runtime Presentation。
+
+`DiagramRenderer`、`BpmnCanvas`、`BpmnViewer` 与 `BpmnStudioShell` 均提供 `refreshPresentation()`。该方法先计算全部目标节点，再原位更新 DOM；失败时保持上一版视觉，不调用 Model Mutation、History、完整 Viewer Refresh 或 `fitView()`。SVG Export 使用同一默认规则和 Resolver，标准降级路径失败时直接 Reject。
+
 ## Studio Shell 区域、Actions 与 Header Slot
 
 默认 Shell 是完整工作台。`regions` 只控制默认布局中的区域，`hidden` 不保留行列轨道：
@@ -1866,9 +2128,13 @@ const shell = createStudioShell({
   studio,
   regions: { right: 'hidden' },
   slots: {
-    headerStart({ container, studio, shell, canvas, actions, getState, subscribe }) {
+    headerStart({ container, studio, shell, canvas, actions, getState, subscribe, getMode, getAllowedModes, subscribeMode, subscribeValidation }) {
       // 只替换 Brand；默认模式区和编辑工具继续保留。
     },
+    headerActions({ container, actions, getMode, subscribeMode }) {
+      // 替换默认“校验 / 导入 / 导出”，挂载宿主“校验 / 保存 / 发布”。
+      // 校验调用 actions.validate()；保存与发布调用宿主服务。
+    },
   },
 })
 
@@ -1876,7 +2142,7 @@ shell.getRegions()
 shell.setRegions({ right: 'default' })
 ```
 
-`slots.header` 完整替换 Header，并高于 `slots.headerStart`；`regions.header = 'hidden'` 的优先级最高。`layout()` 与 `regions` 互斥。
+`slots.headerActions` 只替换 Header 最右侧默认动作组，可与 `slots.headerStart` 同时使用；`slots.header` 完整替换 Header，并高于两个局部 Slot；`regions.header = 'hidden'` 的优先级最高。未提供 `headerActions` 时仍显示“校验 / 导入 / 导出”。顶部不再重复渲染最佳视图，底部缩放区与 `fitView()` Interface 保持不变。`layout()` 与 `regions` 互斥。
 
 ```ts
 interface StudioShellActions {
@@ -1893,9 +2159,9 @@ interface StudioShellActions {
 }
 ```
 
-默认 Header 与宿主 Header 都调用 `shell.actions`。Actions 保留 Controller 的返回值与异常语义，但不处理文件选择、保存草稿、发布、权限或宿主 API。
+默认 Header 与宿主 Header 都调用 `shell.actions`。保存草稿、发布、权限和宿主服务不进入 Actions；宿主通过 `headerActions` 闭包调用自己的业务方法，并使用 `actions.exportXml()` 获取草稿。
 
-Vue `BpmnStudio` 提供 `#header-start` / `#header` 与 `getActions()`；React 提供 `headerStart` / `header` Render Prop 与 Ref `actions`。框架插槽的 `state` 会随 Controller 事件更新，Undo/Redo 禁用状态可以直接绑定 `state.canUndo/canRedo`。
+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`。
 
 ## Group 与 Pool / Lane
 
@@ -2458,7 +2724,7 @@ shell.setRegions({ right: 'default' })
 
 `header`、`left`、`right`、`footer` 均接受 `default | hidden`。隐藏区域不占 Grid 轨道、不显示边框，也不保留可聚焦控件。Viewer/Instance 的只读布局仍会隐藏 Palette；区域配置只能进一步隐藏。
 
-局部内容替换使用 `slots.left`、`slots.right`、`slots.headerStart`、`slots.header` 和 `slots.footer`。`headerStart` 只替换默认 Brand，保留模式区和工具区；`header` 替换完整 Header，优先级高于 `headerStart`。回调收到 `studio`、`shell`、`actions`、`getState()`、`subscribe()`、注册表、交互控制器和 Canvas。
+局部内容替换使用 `slots.left`、`slots.right`、`slots.headerStart`、`slots.headerActions`、`slots.header` 和 `slots.footer`。`headerStart` 只替换默认 Brand；`headerActions` 只替换最右侧默认“校验 / 导入 / 导出”动作组；`header` 替换完整 Header，优先级高于两个局部 Slot。回调收到 `studio`、`shell`、`actions`、`getState()`、`subscribe()`、注册表、交互控制器和 Canvas。
 
 ```js
 createStudioShell({
@@ -2468,6 +2734,9 @@ createStudioShell({
     headerStart({ container, actions, getState, subscribe }) {
       // 挂载返回入口、业务图标、流程名称和类型；返回卸载函数。
     },
+    headerActions({ container, actions, getMode, subscribeMode }) {
+      // 挂载校验 / 保存 / 发布；校验调用 actions.validate()，其余调用宿主服务。
+    },
     left({ container, studio, interactions, canvas }) {
       // 挂载任意 Vanilla / React / Vue UI，返回卸载函数。
     },
@@ -2478,9 +2747,19 @@ createStudioShell({
 });
 ```
 
-默认 Header 和完整自定义 Header 共用 `shell.actions`：撤销/重做、布局/布线、最佳视图、结构校验、BPMN XML 导入导出及 SVG 导出。Actions 不拥有宿主的保存草稿、发布、权限、文件选择或服务端事务。
+默认 Header 和宿主 Header Slots 共用 `shell.actions`：撤销/重做、布局/布线、最佳视图、结构校验、BPMN XML 导入导出及 SVG 导出。顶部不再重复显示最佳视图，底部缩放区和程序化 `fitView()` 继续可用。Actions 不拥有宿主的保存草稿、发布、权限、文件选择或服务端事务。
 
-React 使用 `headerStart` / `header` Render Prop 和 Portal；Vue 使用 `#header-start` / `#header` Named Slot 和 Teleport。两者都在宿主应用树内渲染，不创建独立 React Root 或 Vue App，因此 Context、provide/inject、响应式状态和生命周期继续有效。Vue 原有 `slotsConfig`、React 原有 `slots` 仍作为 Core DOM 接口保留。
+`actions.validate()` 会先更新 Nova 默认状态栏，再发送 `toolbar` 来源的 Validation Event，并返回 issues。程序化 `shell.validate()` 使用 `api` 来源；两者都可由 `shell.subscribeValidation()` 观察。`valid` 表示不存在 error，warning 仍会显示并随事件返回。
+
+```js
+async function publishProcess(actions) {
+  const issues = actions.validate()
+  if (issues.some((issue) => issue.level === 'error')) return
+  await publishXml(actions.exportXml())
+}
+```
+
+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 接口保留。
 
 若整个三栏结构都要自定义，使用 `layout({ container, mount, ...services })`。`mount.canvas()`、`mount.palette()`、`mount.properties()` 可分别挂载官方实现，也可只使用 Controller 自行实现。`layout()` 与 `regions` 是互斥 Interface，同时传入会抛出配置错误。
 
@@ -2570,6 +2849,32 @@ const canvasRef = ref(null)
 
 创建外部 Controller 的一方负责在页面卸载时销毁它；Canvas 和 Palette Adapter 不销毁外部 Controller。
 
+### 只覆盖标准节点副标题
+
+不需要复制整个节点 Renderer 时，优先使用 `nodeSubtitleResolver`。它复用 Nova 的默认标题、图标、端口、Tooltip、ARIA 与 SVG 布局，只替换标准任务和容器卡片的定义态副标题：
+
+```js
+const summaries = new Map()
+const shell = createStudioShell({
+  container,
+  studio,
+  nodeSubtitleResolver({ node, definition, model, mode, surface, defaultSubtitle }) {
+    if (!summaries.has(node.id)) return undefined
+    return summaries.get(node.id)
+  },
+})
+
+summaries.set('ServiceTask_Archive', '1 条归档规则')
+shell.refreshPresentation()
+
+summaries.set('ServiceTask_Archive', null) // 删除副标题行
+shell.refreshPresentation()
+```
+
+返回 `undefined` 恢复权威默认值，返回 `null` 隐藏，字符串（包括 `''`）是显式覆盖。Resolver 必须同步且只读；异常、Promise 或非法值会带节点 ID 失败。刷新会先解析全部节点再更新，因此不会留下局部视觉，也不会改变 XML、Undo/Redo、Selection、Scope、Zoom/Pan 或 Mode。
+
+优先级为“成功的完整自定义 Renderer > Subtitle Resolver > Nova 默认副标题”。HTML Renderer 没有 SVG 适配而回退到标准导出视觉时，SVG 会应用 Resolver；Instance 不调用 Resolver，等待、会签、驳回和重新进入摘要继续来自 Runtime Presentation。业务候选人摘要不能写入标准 `candidateUsers/candidateGroups` 来冒充执行配置。
+
 HTML 节点内容不会被复制到导出的 SVG。需要保持品牌视觉时，应为同一节点类型提供纯 SVG 适配；Renderer 接收 `SVGGElement`、具体主题快照与 Icon Registry，只能创建 SVG Primitive，不能使用 `foreignObject`：
 
 ```js
@@ -2745,7 +3050,7 @@ createStudioShell({
 
 # BPMN Nova NPM 包与发布
 
-版本：`0.3.2-preview`。BPMN Nova 只发布三个 `@bpmn-nova` 公共包，均使用 ESM、附带 TypeScript 声明、采用 Apache-2.0 License，并通过 `preview` dist-tag 发布。
+版本：`0.3.4-preview`。BPMN Nova 只发布三个 `@bpmn-nova` 公共包，均使用 ESM、附带 TypeScript 声明、采用 Apache-2.0 License，并通过 `preview` dist-tag 发布。
 
 ## 公共包
 
@@ -2757,7 +3062,9 @@ createStudioShell({
 | React 18+ | `npm install @bpmn-nova/react@preview` | React 组件、Hook 与 Ref；依赖 Studio |
 | Vue 3.3+ | `npm install @bpmn-nova/vue@preview` | Vue 组件、Composable 与 Expose；依赖 Studio |
 
-Core、Model、Renderer、Runtime、Theme、Properties 和引擎 Profile 是源码内部 Module，不再是可独立安装或独立发布的产品。React/Vue 各自只依赖完全相同版本的 `@bpmn-nova/studio`，并通过 peer dependency 使用宿主框架。
+Core、Model、Renderer、Runtime、Theme、Properties、Node Presentation 和引擎 Profile 是源码内部 Module，不再是可独立安装或独立发布的产品。`NodeSubtitleResolver` 类型从 Studio 根入口公开，但 `node-presentation` 没有 npm 子路径或独立版本。React/Vue 各自只依赖完全相同版本的 `@bpmn-nova/studio`，并通过 peer dependency 使用宿主框架。
+
+React/Vue 的声明入口显式重导出宿主常用的 Core 类型：`BpmnEdge`、`BpmnNode`、`EdgeType`、`ElementSelection`、`EngineId`、`LayoutOptions`、`NodeType` 和 `ProcessModel`。业务项目必须从自己选择的 Adapter 导入这些类型，不应仅为类型在 manifest 中增加 Studio 直依赖。
 
 ## Studio 子路径
 
@@ -2780,7 +3087,7 @@ JavaScript 不会隐式插入 CSS。Studio 项目导入 `@bpmn-nova/studio/style
 
 源码目录保留当前 Module 边界和相对引用，以便 Playground 无需安装 workspace 包即可运行。发布构建执行以下操作：
 
-1. 将 Core、Model、Renderer、Runtime、Properties、Theme、引擎 Profile 和 SVG Export 复制到 `packages/studio/dist/modules`。
+1. 将 Core、Model、Renderer、Runtime、Properties、Node Presentation、Theme、引擎 Profile 和 SVG Export 复制到 `packages/studio/dist/modules`。
 2. 将 Studio 中跨 Module 的源码引用改写为 `dist` 内部相对路径。
 3. 生成 Studio 根入口和受支持子路径所需的 JavaScript 与声明文件。
 4. 将 React/Vue 产物的运行时和类型导入统一改写到 `@bpmn-nova/studio`。
@@ -2828,6 +3135,7 @@ git diff --check
 - Studio、React、Vue 样式子路径存在。
 - 三个包都能直接读取 `llms.txt` 和 `llms-full.txt`，不需要访问源码仓库。
 - TypeScript 能解析 Options、Runtime、Theme、Ref/Expose 等声明。
+- TypeScript 能从三个公开入口解析 Mode Event、`NodeSubtitleResolver` 与 `refreshPresentation()`，无需导入内部 Module。
 - React/Vue Adapter 可以复用 Studio，不会安装历史内部包。
 
 ## 发布顺序
@@ -2845,14 +3153,14 @@ git diff --check
 发布后核对：
 
 ```bash
-npm view @bpmn-nova/studio@0.3.2-preview version
-npm view @bpmn-nova/react@0.3.2-preview version
-npm view @bpmn-nova/vue@0.3.2-preview version
+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
 ```
 
 ## Registry 清理说明
 
-Registry 清理是不可逆的外部操作，不由构建脚本自动执行。只有在三个 `0.3.2-preview` 新产物发布、安装和子路径验证均成功后，才能在获得单独明确授权的情况下执行：
+Registry 清理是不可逆的外部操作，不由构建脚本自动执行。只有在三个 `0.3.4-preview` 新产物发布、安装和子路径验证均成功后，才能在获得单独明确授权的情况下执行：
 
 1. 删除 Studio、React、Vue 的旧 `0.3.0-preview` 版本。
 2. 按反向依赖顺序删除旧的内部包：Designer/Viewer/Properties 聚合层，Renderer/Provider/Model 层，最后 Runtime/Theme/Core 等基础层。