@bpmn-nova/studio 0.3.5-preview → 0.3.6-preview

package/README.md

@@ -4,32 +4,21 @@ BPMN Nova 的 Vanilla JavaScript / TypeScript 完整入口，提供流程设计
 
 > **English summary:** The complete framework-neutral BPMN Nova package for process design, viewing, approval traces, themes, properties, and pure SVG export.
 
-> 当前版本为 `0.3.5-preview`。请使用 `@preview` 安装，并在生产接入前验证目标 BPMN XML 与引擎扩展。
+> 当前版本为 `0.3.6-preview`。请使用 `@preview` 安装，并在生产接入前验证目标 BPMN XML 与引擎扩展。
 
 ![BPMN Nova 流程设计器](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-designer.jpg)
 
-## 什么时候使用
-
-- Vanilla JavaScript 或 TypeScript 项目安装本包。
-- React 18+ 项目安装 `@bpmn-nova/react`。
-- Vue 3.3+ 项目安装 `@bpmn-nova/vue`。
-- 一个项目只需要选择一个公开包，不需要安装 Core、Viewer、Runtime、Theme 等内部 Module。
-
 ## 安装
 
 ```bash
 npm install @bpmn-nova/studio@preview
 ```
 
-```js
-import '@bpmn-nova/studio/styles.css'
-```
-
-BPMN Nova 不会在 JavaScript 中隐式注入 CSS。视觉容器必须有明确高度。
+Vanilla JavaScript / TypeScript 项目选择本包；React 18+ 和 Vue 3.3+ 项目分别选择 `@bpmn-nova/react` 或 `@bpmn-nova/vue`。
 
-使用代码生成助手或 IDE Agent 接入时，从随包的 `llms.txt` 开始；需要完整接口和定制资料时再读取 `llms-full.txt`。两份文件都包含在 npm tarball 中，不依赖源码仓库可见性。
+CSS 必须显式导入 `@bpmn-nova/studio/styles.css`；视觉容器及其父级需要具有可计算高度。
 
-## 流程设计
+## 最小用法
 
 ```html
 <div id="studio" style="height: 720px"></div>
@@ -43,374 +32,34 @@ import {
 } from '@bpmn-nova/studio'
 import '@bpmn-nova/studio/styles.css'
 
-const model = createEmptyProcess('flowable')
-model.id = 'Process_PurchaseApproval'
-model.name = '采购申请审批流程'
-
-const config = {
-  modeling: {
-    allowedNodeTypes: ['startEvent', 'userTask', 'exclusiveGateway', 'endEvent'],
-    allowedEdgeTypes: ['sequenceFlow'],
-  },
-  ui: { controlSize: 'medium' },
-}
-
 const studio = createStudioController({
-  model,
-  config,
+  model: createEmptyProcess('flowable'),
 })
 const shell = createStudioShell({
   container: document.querySelector('#studio'),
   studio,
-  config,
-  mode: 'design',
-  allowedModes: ['design'],
-  theme: 'auto',
-})
-
-const xml = studio.exportXml()
-
-// 页面卸载时释放实例。
-shell.destroy()
-studio.destroy()
-```
-
-`allowedNodeTypes` 与 `allowedEdgeTypes` 同时约束 XML 导入、Palette、连接、快捷新增、模板和节点类型转换；不传时开放 Nova 当前支持的全部图元。`allowedModes` 控制默认工作台显示和允许切换的模式。不传 Runtime 时实例模式保持空运行事实，不会注入演示审批数据。
-
-## 嵌入宿主工作台
-
-默认 `BpmnStudioShell` 仍是包含 Header、Palette、Canvas、Properties 和 Statusbar 的完整工作台。宿主要复用自己的业务属性面板时，应显式隐藏 Nova 右侧区域，并把业务面板作为 Nova 根节点的外部兄弟区域：
-
-```js
-const shell = createStudioShell({
-  container: novaHost,
-  studio,
-  config: {
-    ui: { controlSize: 'medium', regions: { right: 'hidden' } },
-  },
   mode: 'design',
   allowedModes: ['design'],
-  slots: {
-    headerStart({ container, actions, getState, subscribe }) {
-      // 在 Nova Header 左侧挂载宿主的返回入口、业务图标、流程名称和类型。
-      // 完整替换 Header 时改用 slots.header，并继续调用 actions。
-    },
-    headerActions({ container, actions, getMode, subscribeMode, ui }) {
-      // 替换默认“校验 / 导入 / 导出”，在这里挂载宿主的“校验 / 保存 / 发布”。
-      // 校验按钮调用 actions.validate()；保存和发布继续调用宿主服务。
-    },
-  },
-  theme: 'auto',
-})
-
-shell.setRegions({ right: 'default' })
-shell.actions.undo()
-shell.actions.redo()
-shell.actions.fitView()
-const issues = shell.actions.validate()
-const xml = shell.actions.exportXml('flowable')
-```
-
-`regions` 支持 `header`、`left`、`right`、`footer` 的 `default | hidden` 状态；隐藏区域不占布局轨道，也不保留折叠按钮。Design 默认显示左右，Viewer 仅右侧，Instance 默认隐藏两侧；显式 `regions.right: 'default'` 可在 Instance 开启右侧。`setRegions()` 原地更新默认 Shell，不重建 Controller 或 Canvas。`layout()` 是完整布局替换，不能与 `regions` 同时使用。
-
-`headerActions` 只替换 Header 最右侧动作组，`headerStart` 可与其同时使用，完整 `header` 的优先级更高。未提供 `headerActions` 时仍显示默认“校验 / 导入 / 导出”。顶部不再重复显示最佳视图；底部缩放区和 `fitView()` Interface 保持不变。
-
-`shell.actions.validate()` 作为 Header 动作，以 `toolbar` 来源先更新 Nova 默认状态栏、再发送 Validation Event，最后返回 issues；程序化调用 `shell.validate()` 使用 `api` 来源。`valid` 表示没有 error，warning 不默认阻止发布：
-
-```js
-const offValidation = shell.subscribeValidation((event) => {
-  console.log(event.source, event.valid, event.errorCount, event.warningCount, event.issues)
-})
-
-shell.validate()
-offValidation()
-```
-
-宿主发布按钮可以复用 Toolbar 来源的完整流程；仅 error 默认阻止发布：
-
-```js
-async function publishProcess(actions) {
-  const issues = actions.validate()
-  if (issues.some((issue) => issue.level === 'error')) return
-  await publishXml(actions.exportXml())
-}
-```
-
-`shell.actions` 只封装撤销、重做、布局、视图、校验和 BPMN/SVG 导入导出。宿主的保存草稿、发布、权限、文件选择和服务端事务不属于 Nova Actions。
-
-## 侧栏内容与平滑折叠
-
-`slots.right` 只替换内容，Nova 保留宽度管理和分隔线中点折叠按钮；不要同时将 `regions.right` 设置为 `hidden`，否则自定义内容也隐藏。`config.ui.rightPanel.layout` 默认 `flex`，宿主安排固定头尾和 `flex: 1; min-height: 0; overflow: auto` 内容区；改为 `scroll` 时由 Nova 滚动整个内容。
-
-```js
-const shell = createStudioShell({
-  container,
-  studio,
-  config: { ui: {
-    leftPanel: { collapsible: true, defaultCollapsed: false },
-    rightPanel: { collapsible: true, defaultCollapsed: false, layout: 'scroll' },
-  } },
-  slots: {
-    right({ container, shell }) {
-      const text = document.createElement('p')
-      container.append(text)
-      const render = ({ selectedElement }) => { text.textContent = selectedElement?.id ?? '未选择元素' }
-      render(shell.getPanelSelection())
-      const off = shell.subscribePanelSelection(render)
-      return () => { off(); text.remove() }
-    },
-  },
-})
-const offSidebar = shell.subscribeSidebarChange(({ side, collapsed, source }) => console.log(side, collapsed, source))
-shell.setSidebarCollapsed('left', true)
-console.log(shell.getSidebarState().left)
-// 卸载时 offSidebar(); shell.destroy(); studio.destroy()
-```
-
-默认左右可独立折叠；200ms 动画尊重减少动态效果，不卸载内容、不丢失表单和滚动状态、不自动 Fit。Shell 容器 ≤720px 时首次默认收起并保留按钮，展开挤压画布，宽窄屏分别记忆状态。`defaultCollapsed` 只用于初始化；隐藏不同于收起。`panelSelection` 包含 `{ selection, selectedElement, trace }`，Design 从 Controller 派生，Viewer/Instance 从实际点击派生而不回写设计选择。
-
-完整配置、事件契约、窄屏与 Flex 样式见仓库 [CUSTOMIZATION.md](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/CUSTOMIZATION.md#侧栏布局与平滑折叠)，或包内 `llms-full.txt` 同名章节。上述新增能力自 `0.3.5-preview` 提供。
-
-## Config 与 Header 控件尺寸
-
-`config` 统一承载静态配置：`modeling` 是 Controller 初始化约束，`ui` 是 Shell 区域和尺寸，`viewer` 是只读/实例展示选项，`export` 是 SVG 导出默认值。`config.ui.controlSize` 默认 `medium`，支持 `small`（28px）、`medium`（32px）、`large`（40px）和 `24px`–`48px` 的 CSS 像素字符串。
-
-```js
-shell.setConfig({
-  ui: {
-    controlSize: '36px',
-    regions: { right: 'hidden' },
-    sidebarWidth: { left: 232, right: 344 },
-  },
-  viewer: { responsive: true },
-  export: { padding: 36 },
-})
-
-console.log(shell.getConfig())
-console.log(shell.ui.controlSize, shell.ui.controlHeight) // 36px, 36px
-```
-
-尺寸只作用于 Header；Footer、Canvas 浮动工具、Palette 和 Properties 不随之缩放。Header Slot 可读取只读 `ui`，并继承 `--nova-control-height`、`--nova-header-height`、`--nova-control-font-size`、`--nova-control-padding-inline`、`--nova-control-icon-size` 和 `--nova-control-radius`。Element Plus `default`、Ant Design `middle` 都对应 Nova `medium`。
-
-旧顶层配置仍兼容但已 Deprecated；同一字段同时出现时旧顶层显式值优先。`setConfig()` 原地应用 UI、Viewer 和 Export，不重建 Canvas；`config.modeling` 只在创建 Controller 时生效，运行中继续通过 `setPropertiesProfile()` 修改 Profile，节点/连线白名单保持不变量。
-
-## Mode 与节点副标题投影
-
-`design`、`viewer`、`instance` 分别表示流程设计、流程展示和审批轨迹。Shell 是唯一 Mode 状态源：
-
-```js
-const unsubscribe = shell.subscribeMode((event) => {
-  console.log(event.mode, event.previousMode, event.source, event.allowedModes)
-})
-
-shell.getMode()
-shell.setMode('viewer')
-shell.setAllowedModes(['design', 'viewer'])
-```
-
-`setMode()` 仅在实际成功切换时返回 `true`。`setAllowedModes()` 拒绝空数组、重复值和未知值；若移除当前 Mode，会回退到新数组首项并发送一次 `allowed-modes` 事件。切换只改变 Shell 展示，不进入 Model、History 或 Studio State。
-
-标准任务与容器卡片支持定义态副标题 Resolver：
-
-```js
-const summaries = new Map()
-const shell = createStudioShell({
-  container,
-  studio,
-  nodeSubtitleResolver({ node, mode, surface, defaultSubtitle }) {
-    return summaries.has(node.id) ? summaries.get(node.id) : undefined
-  },
-})
-
-summaries.set('ServiceTask_Archive', '归档到采购系统')
-shell.refreshPresentation()
-summaries.set('ServiceTask_Archive', null)
-shell.refreshPresentation()
-```
-
-`undefined` 保留默认副标题，`null` 移除副标题行，字符串（包括空字符串）作为覆盖值。Resolver 同步应用于 Design、Viewer 与标准 SVG 降级视觉；完整自定义 Renderer 优先，Instance 始终使用 Runtime Presentation。`refreshPresentation()` 不写 XML、不创建历史、不改变选择、Scope 或视口。
-
-## 只读 Viewer
-
-```js
-import { importBpmn } from '@bpmn-nova/studio'
-import { BpmnViewer } from '@bpmn-nova/studio/viewer'
-import '@bpmn-nova/studio/styles.css'
-
-const viewer = new BpmnViewer({
-  container: document.querySelector('#viewer'),
-  model: importBpmn(xml, 'flowable'),
-  projection: 'standard',
   theme: 'auto',
 })
 
-viewer.fitView()
-viewer.destroy()
-```
-
-也可以从 `@bpmn-nova/studio` 根入口导入所有公开 Interface；子路径用于明确表达接入场景。
-
-![BPMN Nova 只读流程展示](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-viewer.jpg)
-
-## 审批轨迹
-
-完整 XML、Snapshot、宿主转换器及 Core 生命周期示例见[审批轨迹接入指南](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/RUNTIME-INTEGRATION.md)，正文也包含在包内 `llms-full.txt`。Studio 现有 Runtime 类型出口保持不变；Vue/React 自 `0.3.5-preview` 提供的新增类型出口和旧版兼容写法在指南中单独说明。
-
-Viewer 接收引擎中立的 Runtime Snapshot。三种投影使用相同数据：
-
-| 投影 | 配置 | 适用场景 |
-| --- | --- | --- |
-| 实际路径 | `projection: 'approval'` | 只展示实际发生的有效路径 |
-| 移动时间线 | `projection: 'compact'` | 按访问轮次展示动作、图片和附件 |
-| 完整 BPMN | `projection: 'standard'` + `runtime` | 完整结构叠加运行状态 |
-
-```js
-const runtime = {
-  processInstanceId: 'purchase-20260824',
-  status: 'running',
-  activities: [{
-    id: 'activity-manager-1',
-    elementId: 'UserTask_Manager',
-    visitId: 'visit-manager-1',
-    status: 'completed',
-    assignee: '李经理',
-    endTime: '2026-08-24T10:12:00+08:00',
-  }],
-  actions: [{
-    id: 'action-manager-approve',
-    type: 'approve',
-    elementId: 'UserTask_Manager',
-    visitId: 'visit-manager-1',
-    activityId: 'activity-manager-1',
-    actor: { id: 'manager-li', name: '李经理' },
-    occurredAt: '2026-08-24T10:12:00+08:00',
-    content: {
-      plainText: '资料完整，同意提交总经理审批。',
-      blocks: [
-        { type: 'paragraph', text: '资料完整，同意提交总经理审批。' },
-        { type: 'image', assetId: 'quotation-preview' },
-        { type: 'file', assetId: 'purchase-checklist' },
-      ],
-      assets: [
-        {
-          id: 'quotation-preview',
-          name: '现场报价单.png',
-          mediaType: 'image/png',
-          width: 1280,
-          height: 720,
-        },
-        {
-          id: 'purchase-checklist',
-          name: '采购核验清单.txt',
-          mediaType: 'text/plain',
-          size: 248,
-        },
-      ],
-    },
-  }],
-  visitedEdges: [],
-}
-
-const runtimeAssetResolver = async (asset, { purpose, signal }) => {
-  const response = await fetch(
-    `/api/runtime-assets/${encodeURIComponent(asset.id)}?purpose=${purpose}`,
-    { signal },
-  )
-  if (!response.ok) return null
-  return response.url
+function dispose() {
+  shell.destroy()
+  studio.destroy()
 }
-
-viewer.setRuntime(runtime)
-viewer.setProjection('compact')
-viewer.setDisplayOptions({ runtimeAssetResolver })
-```
-
-Snapshot 只保存资源引用，不保存 URL、Base64、Blob 或 HTML。上传、权限签发和资源存储由宿主业务系统负责。
-
-| 实际路径 | 移动时间线 |
-| --- | --- |
-| ![审批实际路径](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-approval-effective-path.jpg) | ![移动审批时间线](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-approval-mobile-timeline.jpg) |
-
-![完整 BPMN 审批轨迹](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-approval-full-bpmn.jpg)
-
-## 主题与运行态配色
-
-```js
-shell.setTheme({
-  mode: 'auto',
-  dark: {
-    colors: {
-      canvas: '#0b1018',
-      surface: '#18202b',
-    },
-  },
-})
-
-shell.setRuntimeAppearance({
-  statuses: { completed: 'success', active: 'primary' },
-  actions: {
-    approve: { label: '通过', tone: 'success' },
-    reject: { label: '驳回', tone: 'danger' },
-  },
-})
-```
-
-主题限定在实例根节点；`auto` 会跟随并监听浏览器系统主题变化，不修改宿主页面的 `<html>`。
-
-![BPMN Nova 深色运行态](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-dark-runtime.jpg)
-
-## SVG 导出
-
-```js
-// 打开确认预览，用户确认后下载。
-shell.openSvgExportPreview({
-  theme: 'current',
-  transparentBackground: false,
-  filename: '采购申请审批流程.svg',
-})
-
-// 或只创建 Artifact，不触发下载。
-const artifact = await shell.exportSvg({ theme: 'dark' })
-console.log(artifact.svg, artifact.warnings)
 ```
 
-导出完整业务内容，不受当前缩放、平移或滚动影响。图片会通过 Resolver 嵌入 SVG，普通附件只展示摘要。
-
-![SVG 导出确认预览](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-svg-export-preview.jpg)
-
-## 支持的子路径
-
-```js
-import { BpmnDesigner } from '@bpmn-nova/studio/designer'
-import { BpmnViewer } from '@bpmn-nova/studio/viewer'
-import { createRuntimePresentation } from '@bpmn-nova/studio/runtime'
-import { createThemeController } from '@bpmn-nova/studio/theme'
-import { exportDiagramSvg } from '@bpmn-nova/studio/export-svg'
-import { flowableProfile } from '@bpmn-nova/studio/flowable'
-import { activitiProfile } from '@bpmn-nova/studio/activiti'
-```
-
-## 常见问题
-
-- **界面为空或高度为 0：** 为 Studio/Viewer 的父容器设置明确高度。
-- **界面没有样式：** 导入一次 `@bpmn-nova/studio/styles.css`。
-- **附件不可用：** 提供 `runtimeAssetResolver`，并为不同 purpose 返回当前有效地址。
-- **SSR 报错：** 在浏览器挂载阶段创建实例，服务端只准备 XML 和 Runtime 数据。
-- **重复安装：** 不直接安装任何未列出的 `@bpmn-nova/*` 内部 Module。
-
-## 文档与 AI
+在页面卸载时调用 `dispose()`；SSR 应用只在客户端创建视觉实例。
 
-- npm 包内 `llms.txt`：可执行安装入口
-- npm 包内 `llms-full.txt`：完整 AI 上下文
-- [项目首页](https://github.com/daxiangme/bpmn-nova)
-- [快速开始](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/GETTING-STARTED.md)
-- [公开 Interface](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/API.md)
-- [审批轨迹接入指南](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/RUNTIME-INTEGRATION.md)
-- [自定义指南](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/CUSTOMIZATION.md)
+## 完整文档
 
-## 能力边界
+- [官网与文档](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/index.md)
+- [Studio 接入、宿主组合和完整示例](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/guide/studio.md)
+- [组件参数与事件](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/components/index.md)、[公开 API](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/api/index.md)
+- [审批轨迹接入](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/guide/runtime.md)、[自定义扩展](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/customization/index.md)
+- [更新日志](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/changelog.md)
 
-BPMN Nova 负责建模、展示、审批轨迹、主题和 SVG 导出；不负责流程引擎执行、审批提交、附件上传存储、权限签发或 PNG/PDF 导出。当前 Preview 不声明 BPMN Schema 100% 覆盖。
+官网尚未部署，以上链接暂指向仓库文档。AI 接入从随包的 `llms.txt` 开始；`llms-full.txt` 提供完整离线上下文，两份文件都包含在 npm tarball 中。
 
 ## License
 

package/dist/modules/export-svg/render.js

@@ -2,7 +2,7 @@ import { NODE_DEFINITIONS, edgeWaypoints, roundedPath, routeRuntimeTransition, s
 import { createDefaultIconRegistry, resolveNodeVisual } from '../icons/index.js';
 import { resolveNodeSubtitle, supportsNodeSubtitle } from '../node-presentation/index.js';
 import { resolveNodeGeometry, resolvePresentationWaypoints } from '../node-geometry/index.js';
-import { createRuntimePresentation } from '../runtime/index.js';
+import { createRuntimePresentation, formatRuntimeInstant } from '../runtime/index.js';
 import { createRuntimeAppearance } from '../theme/index.js';
 
 const SVG_NS = 'http://www.w3.org/2000/svg';
@@ -170,7 +170,7 @@ function finite(value, fallback = 0) {
 }
 
 function formatTime(value) {
-  return value ? String(value).replace('T', ' ') : '';
+  return formatRuntimeInstant(value);
 }
 
 function formatSize(value) {

package/dist/modules/renderer-svg/index.js

@@ -737,6 +737,7 @@ export class DiagramRenderer {
     const boundsW = maxX - minX || 1;
     const boundsH = maxY - minY || 1;
     const rect = this.viewport.getBoundingClientRect();
+    if (rect.width < 1 || rect.height < 1) return;
     const maxZoom = options.maxZoom ?? 1.15;
     const minZoom = options.minZoom ?? 0.25;
     const rawZoom = Math.min((rect.width - padding * 2) / boundsW, (rect.height - padding * 2) / boundsH, maxZoom);

package/dist/modules/runtime/diagnostics.js

@@ -0,0 +1,22 @@
+const DIAGNOSTIC_FIELDS = ['code', 'level', 'message', 'fieldPath', 'elementId', 'activityId', 'visitId', 'actionId', 'transitionId', 'edgeId'];
+
+export function createDiagnostic(input = {}) {
+  const diagnostic = {
+    code: String(input.code || 'runtime-issue'),
+    level: input.level === 'error' || input.level === 'info' ? input.level : 'warning',
+    message: String(input.message || ''),
+  };
+  for (const field of DIAGNOSTIC_FIELDS.slice(3)) {
+    if (input[field]) diagnostic[field] = String(input[field]);
+  }
+  return Object.freeze(diagnostic);
+}
+
+export function pushDiagnostic(list, input) {
+  if (!list) return null;
+  const diagnostic = createDiagnostic(input);
+  if (!list.some((item) => item.code === diagnostic.code && item.fieldPath === diagnostic.fieldPath && item.activityId === diagnostic.activityId && item.visitId === diagnostic.visitId && item.actionId === diagnostic.actionId && item.transitionId === diagnostic.transitionId)) {
+    list.push(diagnostic);
+  }
+  return diagnostic;
+}

package/dist/modules/runtime/index.d.ts

@@ -51,9 +51,27 @@ export interface RuntimeApprovalActionPresentation extends Omit<RuntimeApprovalA
   assetCount: number
   order: number
 }
+export interface RuntimeDiagnostic {
+  code: string
+  level: 'error' | 'warning' | 'info'
+  message: string
+  fieldPath?: string
+  elementId?: string
+  activityId?: string
+  visitId?: string
+  actionId?: string
+  transitionId?: string
+  edgeId?: string
+}
+export interface RuntimeInstant {
+  instant: number | null
+  raw: string
+  kind: 'offset' | 'z' | 'naive' | 'invalid' | 'missing'
+}
 export interface RuntimeApprovalActionSummary {
   actions: RuntimeApprovalActionPresentation[]
   latestAction: RuntimeApprovalActionPresentation | null
+  latestNonEmptyComment: RuntimeApprovalActionPresentation | null
   actionText: string
   actionSummary: string
   imageCount: number
@@ -70,6 +88,7 @@ export interface ActivityInstance {
   assigneeId?: string
   participant?: RuntimeParticipant
   visitId?: string
+  supersedesVisitId?: string
   multiInstanceId?: string
   approvalMode?: 'single' | 'all' | 'any'
   multiInstanceMode?: 'parallel' | 'sequential'
@@ -92,6 +111,7 @@ export interface RuntimeTransition {
   state?: 'active' | 'resolved'
   resolvedAt?: string
   resolvedByActivityId?: string
+  invalidatedElementIds?: string[]
   invalidatedActivityIds?: string[]
   invalidatedEdgeIds?: string[]
 }
@@ -120,10 +140,18 @@ export interface RuntimeTransitionPresentation extends RuntimeTransition {
   label: string
   latest: boolean
   issues: string[]
+  invalidatedElementIds: string[]
   invalidatedActivityIds: string[]
   invalidatedEdgeIds: string[]
   action: RuntimeApprovalActionPresentation | null
 }
+export interface ActivityVisitState {
+  status: ActivityStatus
+  records: ActivityInstance[]
+  latestRecords: ActivityInstance[]
+  visits: Array<{ id: string; round: number; records: ActivityInstance[]; effective?: boolean; superseded?: boolean }>
+  effectiveVisits: Array<{ id: string; round: number; records: ActivityInstance[]; effective?: boolean; superseded?: boolean }>
+}
 export interface NodeRuntimePresentation extends RuntimeApprovalActionSummary {
   elementId: string
   status: ActivityStatus | 'rejected'
@@ -141,13 +169,15 @@ export interface NodeRuntimePresentation extends RuntimeApprovalActionSummary {
   round: number
   records: ActivityInstance[]
   latestRecords: ActivityInstance[]
-  visits: Array<{ id: string; round: number; records: ActivityInstance[] } & RuntimeApprovalActionSummary>
+  visits: Array<{ id: string; round: number; records: ActivityInstance[]; effective: boolean; superseded: boolean } & RuntimeApprovalActionSummary>
+  effectiveVisits: Array<{ id: string; round: number; records: ActivityInstance[]; effective: boolean; superseded: boolean } & RuntimeApprovalActionSummary>
   transitions: RuntimeTransitionPresentation[]
   isReentry: boolean
   hasDetails: boolean
 }
 export interface RuntimePresentation {
   runtime: ProcessInstanceSnapshot
+  diagnostics: readonly RuntimeDiagnostic[]
   getNode(elementId: string): NodeRuntimePresentation
   getEdge(edgeId: string): { edgeId: string; status: ActivityStatus; visited: boolean; historicallyVisited: boolean; superseded: boolean }
   getAction(actionId: string): RuntimeApprovalActionPresentation | null
@@ -161,9 +191,13 @@ export interface RuntimeAppearanceLike {
   resolveTransition(transition?: { type?: string }): { tone: string }
 }
 
-export function normalizeRuntime(snapshot?: Partial<ProcessInstanceSnapshot> | null): ProcessInstanceSnapshot
-export function activityState(runtime: ProcessInstanceSnapshot | null | undefined, elementId: string): ActivityStatus
-export function createRuntimePresentation(context: { model: ProcessModel; runtime?: ProcessInstanceSnapshot | null; appearance?: RuntimeAppearanceLike | null }): RuntimePresentation
+export function parseRuntimeInstant(value?: string | null): RuntimeInstant
+export function formatRuntimeInstant(value?: string | RuntimeInstant | null): string
+export function compareRuntimeOrder(left: { instant?: number | null; index?: number } | string | null | undefined, right: { instant?: number | null; index?: number } | string | null | undefined): number
+export function normalizeRuntime(snapshot?: Partial<ProcessInstanceSnapshot> | null, options?: { diagnostics?: RuntimeDiagnostic[]; model?: ProcessModel | null }): ProcessInstanceSnapshot
+export function activityState(runtime: ProcessInstanceSnapshot | null | undefined, elementId: string, options?: { diagnostics?: RuntimeDiagnostic[] }): ActivityVisitState
+export function inspectRuntime(snapshot?: Partial<ProcessInstanceSnapshot> | null, options?: { model?: ProcessModel | null; appearance?: RuntimeAppearanceLike | null }): { runtime: ProcessInstanceSnapshot; diagnostics: readonly RuntimeDiagnostic[] }
+export function createRuntimePresentation(context: { model: ProcessModel; runtime?: ProcessInstanceSnapshot | null; appearance?: RuntimeAppearanceLike | null; diagnostics?: RuntimeDiagnostic[] }): RuntimePresentation
 export function demoRuntime(): ProcessInstanceSnapshot
 
 export type RuntimeElement = BpmnNode | BpmnEdge