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

package/README.md

@@ -4,7 +4,7 @@ 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.6-preview`。请使用 `@preview` 安装，并在生产接入前验证目标 BPMN XML 与引擎扩展。
+> 当前版本为 `0.3.7-preview`。请使用 `@preview` 安装，并在生产接入前验证目标 BPMN XML 与引擎扩展。
 
 ![BPMN Nova 流程设计器](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-designer.jpg)
 

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

@@ -588,6 +588,95 @@ async function resolvedImageData(asset, action, context, warnings, signal) {
   }
 }
 
+const AVATAR_SIZE = 32;
+const AVATAR_OVERLAP = 8;
+const AVATAR_VISIBLE_LIMIT = 2;
+let avatarClipSequence = 0;
+
+function timelineAvatarPeople(item) {
+  if (!item || item.kind === 'transition' || item.predicted || item.automated) return [];
+  return (item.participants || []).filter((participant) => String(participant?.name || '').trim());
+}
+
+function participantInitial(participant) {
+  return String(participant?.name || '').trim().slice(0, 1) || '?';
+}
+
+async function resolvedAvatarData(url, context, warnings, signal, item) {
+  const source = String(url || '').trim();
+  if (!source) return null;
+  const cache = context.avatarCache || (context.avatarCache = new Map());
+  if (cache.has(source)) return cache.get(source);
+  try {
+    signal?.throwIfAborted?.();
+    let data = source;
+    if (source.startsWith('data:')) {
+      if (!source.startsWith('data:image/')) throw new Error('Unexpected Data URL MIME type.');
+    } else {
+      const ownerWindow = context.document?.defaultView || globalThis;
+      const response = await ownerWindow.fetch(source, { signal });
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      const blob = await response.blob();
+      if (!blob.type.startsWith('image/')) throw new Error(`Unexpected MIME type: ${blob.type || 'unknown'}`);
+      data = await new Promise((resolve, reject) => {
+        const reader = new ownerWindow.FileReader();
+        reader.addEventListener('load', () => resolve(String(reader.result)), { once: true });
+        reader.addEventListener('error', () => reject(reader.error || new Error('Unable to read image.')), { once: true });
+        reader.readAsDataURL(blob);
+      });
+    }
+    cache.set(source, data);
+    return data;
+  } catch (error) {
+    cache.delete(source);
+    if (signal?.aborted) throw error;
+    warnings.push({ code: 'avatar-unavailable', message: '处理人头像无法嵌入 SVG，已显示姓名首字。', elementId: item?.elementId });
+    return null;
+  }
+}
+
+async function renderTimelineAvatars({ document, parent, people, x, y, theme, context, warnings, signal, item }) {
+  const visible = people.slice(0, AVATAR_VISIBLE_LIMIT);
+  const overflow = people.length - AVATAR_VISIBLE_LIMIT;
+  const count = visible.length + (overflow > 0 ? 1 : 0);
+  const primary = tone(theme, 'primary');
+  for (let index = 0; index < visible.length; index += 1) {
+    const left = x + index * (AVATAR_SIZE - AVATAR_OVERLAP);
+    const cx = left + AVATAR_SIZE / 2;
+    const cy = y + AVATAR_SIZE / 2;
+    const person = visible[index];
+    const data = await resolvedAvatarData(person.avatarUrl, context, warnings, signal, item);
+    parent.appendChild(svgElement(document, 'circle', {
+      cx, cy, r: AVATAR_SIZE / 2, fill: theme.colors.primarySoft, stroke: theme.colors.surface, 'stroke-width': 2,
+    }));
+    if (data) {
+      avatarClipSequence += 1;
+      const clipId = `nova-timeline-avatar-${avatarClipSequence}`;
+      const clip = svgElement(document, 'clipPath', { id: clipId });
+      clip.appendChild(svgElement(document, 'circle', { cx, cy, r: AVATAR_SIZE / 2 }));
+      parent.appendChild(clip);
+      parent.appendChild(svgElement(document, 'image', {
+        x: left, y, width: AVATAR_SIZE, height: AVATAR_SIZE, href: data, preserveAspectRatio: 'xMidYMid slice', 'clip-path': `url(#${clipId})`,
+      }));
+    } else {
+      parent.appendChild(svgElement(document, 'text', {
+        x: cx, y: y + 21, 'text-anchor': 'middle', fill: primary.foreground, 'font-size': 12, 'font-weight': 600, 'font-family': theme.fontFamily,
+      }, participantInitial(person)));
+    }
+  }
+  if (overflow > 0) {
+    const left = x + visible.length * (AVATAR_SIZE - AVATAR_OVERLAP);
+    const cx = left + AVATAR_SIZE / 2;
+    parent.appendChild(svgElement(document, 'circle', {
+      cx, cy: y + AVATAR_SIZE / 2, r: AVATAR_SIZE / 2, fill: theme.colors.primarySoft, stroke: theme.colors.surface, 'stroke-width': 2,
+    }));
+    parent.appendChild(svgElement(document, 'text', {
+      x: cx, y: y + 21, 'text-anchor': 'middle', fill: primary.foreground, 'font-size': 10, 'font-weight': 600, 'font-family': theme.fontFamily,
+    }, `+${overflow}`));
+  }
+  return count > 0 ? AVATAR_SIZE + (count - 1) * (AVATAR_SIZE - AVATAR_OVERLAP) : 0;
+}
+
 function timelineSequence(projection) {
   const groupedIds = new Set((projection.groups || []).flatMap((group) => group.itemIds || []));
   return [
@@ -670,9 +759,17 @@ async function renderTimelineItem({ document, parent, item, x, y, width, theme,
   parent.appendChild(svgElement(document, 'circle', { cx: railX, cy: y + 22, r: 4.5, fill: itemTone.strong }));
   const contentX = x + 46;
   const contentWidth = width - 46;
-  parent.appendChild(svgElement(document, 'text', { x: contentX, y: y + 20, fill: theme.colors.text, 'font-size': 15, 'font-weight': 650, 'font-family': theme.fontFamily }, `${item.name}${item.round > 1 ? `  第 ${item.round} 次` : ''}`));
+  const people = timelineAvatarPeople(item);
+  let textX = contentX;
+  if (people.length) {
+    const stackWidth = await renderTimelineAvatars({
+      document, parent, people, x: contentX, y: y + 6, theme, context, warnings, signal, item,
+    });
+    textX = contentX + stackWidth + 8;
+  }
+  parent.appendChild(svgElement(document, 'text', { x: textX, y: y + 20, fill: theme.colors.text, 'font-size': 15, 'font-weight': 650, 'font-family': theme.fontFamily }, `${item.name}${item.round > 1 ? `  第 ${item.round} 次` : ''}`));
   parent.appendChild(svgElement(document, 'text', { x: contentX + contentWidth, y: y + 20, 'text-anchor': 'end', fill: itemTone.foreground, 'font-size': 12, 'font-weight': 600, 'font-family': theme.fontFamily }, resultLabel(item)));
-  parent.appendChild(svgElement(document, 'text', { x: contentX, y: y + 42, fill: theme.colors.textSecondary, 'font-size': 11.5, 'font-family': theme.fontFamily }, item.summary || ''));
+  parent.appendChild(svgElement(document, 'text', { x: textX, y: y + 42, fill: theme.colors.textSecondary, 'font-size': 11.5, 'font-family': theme.fontFamily }, item.summary || ''));
   parent.appendChild(svgElement(document, 'text', { x: contentX + contentWidth, y: y + 42, 'text-anchor': 'end', fill: theme.colors.textMuted, 'font-size': 11, 'font-family': theme.fontFamily }, formatTime(item.time)));
   let actionY = y + 56;
   for (const action of actions) {

package/dist/modules/viewer/runtime-avatar.js

@@ -0,0 +1,49 @@
+function element(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+function participantInitial(participant) {
+  const name = String(participant?.name || '').trim();
+  return name.slice(0, 1) || '?';
+}
+
+export function renderRuntimeAvatar(participant, className = 'mb-runtime-details-avatar') {
+  const initial = participantInitial(participant);
+  const avatar = element('span', className, initial);
+  avatar.setAttribute('aria-hidden', 'true');
+  const url = String(participant?.avatarUrl || '').trim();
+  if (!url) return avatar;
+  const image = document.createElement('img');
+  image.src = url;
+  image.alt = '';
+  image.addEventListener('error', () => {
+    image.remove();
+    if (!avatar.textContent) avatar.textContent = initial;
+  }, { once: true });
+  avatar.textContent = '';
+  avatar.appendChild(image);
+  return avatar;
+}
+
+export function renderRuntimeAvatarStack(participants = [], { visibleLimit = 2 } = {}) {
+  const people = (participants || []).filter((item) => String(item?.name || '').trim());
+  if (!people.length) return null;
+  const stack = element('span', 'mb-runtime-timeline-avatars');
+  stack.setAttribute('aria-hidden', 'true');
+  people.slice(0, visibleLimit).forEach((participant) => {
+    stack.appendChild(renderRuntimeAvatar(participant));
+  });
+  const overflow = people.length - visibleLimit;
+  if (overflow > 0) {
+    stack.appendChild(element('span', 'mb-runtime-details-avatar mb-runtime-timeline-avatar-more', `+${overflow}`));
+  }
+  return stack;
+}
+
+export function shouldRenderTimelineAvatars(item) {
+  if (!item || item.predicted || item.automated) return false;
+  return (item.participants || []).some((participant) => String(participant?.name || '').trim());
+}

package/dist/modules/viewer/timeline.js

@@ -1,6 +1,7 @@
 import { createDefaultIconRegistry, createIconElement } from '../icons/index.js';
 import { formatRuntimeInstant } from '../runtime/index.js';
 import { renderRuntimeApprovalContent } from './runtime-content.js';
+import { renderRuntimeAvatarStack, shouldRenderTimelineAvatars } from './runtime-avatar.js';
 import { applyRuntimeTone } from '../theme/index.js';
 
 function element(tag, className, text) {
@@ -100,7 +101,15 @@ function renderActivityItem({ item, registry, conditionLabel, onItemClick, onDet
   heading.append(title, element('em', '', resultText(item)));
   const meta = element('div', 'mb-runtime-timeline-meta');
   meta.append(element('span', '', item.summary || (item.automated ? item.statusLabel : '')), element('time', '', formatTime(item.time)));
-  trigger.append(heading, meta);
+  const copy = element('div', 'mb-runtime-timeline-card-copy');
+  copy.append(heading, meta);
+  const avatars = shouldRenderTimelineAvatars(item) ? renderRuntimeAvatarStack(item.participants) : null;
+  if (avatars) {
+    trigger.classList.add('has-avatars');
+    trigger.append(avatars, copy);
+  } else {
+    trigger.appendChild(copy);
+  }
   trigger.addEventListener('click', (event) => {
     onItemClick?.(item, event);
     onDetailsRequest?.(item, event.currentTarget, event);

package/dist/styles.css

@@ -938,6 +938,11 @@ button.mb-runtime-action-summary:hover, button.mb-runtime-action-summary:focus-v
 .mb-runtime-timeline-content { min-width: 0; display: grid; gap: 4px; }
 .mb-runtime-timeline-card { width: 100%; min-width: 0; overflow: visible; border: 0; border-radius: 0; display: grid; color: inherit; background: transparent; box-shadow: none; }
 .mb-runtime-timeline-card-main { width: 100%; min-width: 0; border: 0; border-radius: 8px; padding: 5px 7px; display: grid; gap: 3px; color: inherit; background: transparent; text-align: left; font: inherit; cursor: pointer; transition: background-color .14s ease, box-shadow .14s ease; }
+.mb-runtime-timeline-card-main.has-avatars { grid-template-columns: auto minmax(0, 1fr); align-items: start; column-gap: 8px; }
+.mb-runtime-timeline-card-copy { min-width: 0; display: grid; gap: 3px; }
+.mb-runtime-timeline-avatars { display: flex; align-items: center; margin-top: 2px; }
+.mb-runtime-timeline-avatars .mb-runtime-details-avatar + .mb-runtime-details-avatar { margin-left: -8px; box-shadow: 0 0 0 2px var(--nova-color-surface, #fff); }
+.mb-runtime-timeline-avatar-more { font-size: var(--nova-font-size-xs, 10px); }
 .mb-runtime-timeline-card-main:hover { background: var(--nova-color-primary-soft, #f5f6ff); }
 .mb-runtime-timeline-card-main:focus-visible { outline: none; background: var(--nova-color-primary-soft, #f5f6ff); box-shadow: inset 0 0 0 2px color-mix(in srgb, var(--nova-color-primary) 22%, transparent); }
 .mb-runtime-timeline-card-main:active { background: color-mix(in srgb, var(--nova-color-primary-soft) 84%, var(--nova-color-primary)); }

package/llms-full.txt

@@ -323,7 +323,7 @@ Before changing Nova package versions, publishing, or recovering a partial relea
 - **流程展示**：只读 BPMN、实际审批路径、移动时间线和完整 BPMN 运行态。
 - **嵌入与扩展**：宿主布局、业务属性、节点内容、主题、审批详情及纯 SVG 导出。
 
-当前版本为 **`0.3.6-preview`**，使用 `@preview` 安装。组件负责建模、展示和交互；流程执行、审批提交及权限由宿主业务系统负责。完整能力与 Preview 边界见[项目介绍](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/guide/overview.md)。
+当前版本为 **`0.3.7-preview`**，使用 `@preview` 安装。组件负责建模、展示和交互；流程执行、审批提交及权限由宿主业务系统负责。完整能力与 Preview 边界见[项目介绍](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/guide/overview.md)。
 
 ## 安装
 
@@ -412,7 +412,7 @@ npm run docs:ai:check
 BPMN Nova 提供可嵌入的流程设计器、只读 Viewer、运行态审批轨迹、实例级主题、纯 SVG 导出，以及 React / Vue 适配。项目使用独立的 DOM / SVG 渲染实现，不依赖 `bpmn-js`，并为 Flowable 与 Activiti 提供 XML Profile 和属性扩展。
 
 > [!IMPORTANT]
-> 当前版本为 `0.3.6-preview`。它适合 SDK 评估、产品集成验证和企业审批原型；公开 Interface、BPMN XML round-trip 与引擎兼容能力仍在持续稳定中，建议使用 `@preview` 安装并在生产接入前完成目标流程验证。
+> 当前版本为 `0.3.7-preview`。它适合 SDK 评估、产品集成验证和企业审批原型；公开 Interface、BPMN XML round-trip 与引擎兼容能力仍在持续稳定中，建议使用 `@preview` 安装并在生产接入前完成目标流程验证。
 
 AI 或代码生成工具接入必须从 [`llms.txt`](https://github.com/daxiangme/bpmn-nova/blob/dev/llms.txt) 的完整安装流程开始；需要全部接口与定制上下文时再读取 [`llms-full.txt`](https://github.com/daxiangme/bpmn-nova/blob/dev/llms-full.txt)。这两份文件也会随三个公开 npm 包发布。
 
@@ -479,7 +479,7 @@ BPMN Nova 是一个引擎中立、实例级可嵌入的 BPMN UI SDK。它把“
 | 流程设计 | Studio / Designer | 编辑完整流程定义、属性和 XML |
 | 只读展示 | Viewer `standard` | 展示完整 BPMN 结构，不叠加实例轨迹 |
 | 实际路径 | Viewer `approval` | 按实例已发生的有效路径展示状态、意见和异常线路 |
-| 移动时间线 | Viewer `compact` | 按审批访问轮次纵向展示动作、图文、附件和 Bottom Sheet 详情 |
+| 移动时间线 | Viewer `compact` | 按审批访问轮次纵向展示处理人头像、动作、图文、附件和 Bottom Sheet 详情 |
 | 完整 BPMN | Viewer `standard` + Runtime | 保留完整 BPMN，并叠加节点状态、动作摘要和回退线路 |
 
 `projection: 'auto'` 会根据容器与 Runtime 场景选择合适投影；需要稳定布局语义时，应显式传入投影。
@@ -944,7 +944,7 @@ console.log(artifact.svg, artifact.width, artifact.height, artifact.warnings)
 
 完整 Studio 的默认导出选项放在 `config.export`；单次调用传入的选项仍用于本次导出。
 
-导出内容不受当前缩放、平移或滚动影响。移动时间线会展开全部历史动作。审批图片通过 `purpose: 'export'` 解析并嵌入 Data URL；普通附件只输出名称、MIME 和大小。第一版不导出 PNG/PDF。
+导出内容不受当前缩放、平移或滚动影响。移动时间线会展开全部历史动作，并与页面一样绘制处理人头像。审批图片通过 `purpose: 'export'` 解析并嵌入 Data URL；普通附件只输出名称、MIME 和大小。第一版不导出 PNG/PDF。
 
 ## 9. 清理与生命周期
 
@@ -1528,6 +1528,8 @@ export const scenarioSnapshots = {
 
 `approval` 和 `compact` 会重排、聚合或过滤图元，展示不保证与 `standard` 的位置相同。普通开始/结束事件默认在完整 BPMN 可见，在实际路径/时间线默认隐藏。需要显示时设置 `runtimeTraceOptions.showStartMilestone / showEndMilestone`。
 
+自 `0.3.7-preview` 起，`compact` 移动时间线在人工任务卡标题左侧展示处理人头像：读取 `participant.avatarUrl`，没有图片时用名字首字，与默认节点详情相同。只写 `assignee: '李经理'` 的旧记录出不了照片。`avatarUrl` 不要填凭证或短期签名。预测节点、自动任务和驳回/退回条不画头像。会签多人叠放最多两个头像，其余以 `+N` 表示。移动时间线的 SVG 导出与确认预览使用同一套头像：有图则嵌入 Data URL，失败时回退首字。
+
 默认投影可能追加唯一可预测的后续人工节点；预测不是已发生事实，也不应写回 `activities` 或审批日志。需要严格只读历史时配置 `runtimeTraceOptions.includePredicted: false`；Studio 中放在 `config.viewer.runtimeTraceOptions`。
 
 ## 5. 加载、更新和交互
@@ -1840,7 +1842,7 @@ export function createAssetResolver(resolveAssetUrl: ResolveAssetUrl): RuntimeAs
 
 # BPMN Nova 快速开始
 
-本文面向通过 NPM 集成 BPMN Nova 的应用开发者。版本 `0.3.6-preview` 要求现代浏览器；Node.js 18+ 用于构建、SSR 和开发工具。
+本文面向通过 NPM 集成 BPMN Nova 的应用开发者。版本 `0.3.7-preview` 要求现代浏览器；Node.js 18+ 用于构建、SSR 和开发工具。
 
 ## 1. 按语言与框架选择入口
 
@@ -2073,7 +2075,7 @@ viewer.destroy()
 | --- | --- |
 | `standard` | 完整 BPMN 流程图 |
 | `approval` | 桌面端实际有效路径图 |
-| `compact` | 适合移动端的纵向审批时间线 |
+| `compact` | 适合移动端的纵向审批时间线，人工任务卡展示处理人头像 |
 | `auto` | 按 Viewer 容器宽度在 `approval` 与 `compact` 间切换 |
 
 只有显式设置 `responsive: true` 且没有固定投影，或直接设置 `projection: 'auto'` 时，才启用响应式切换。
@@ -2316,7 +2318,7 @@ 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.6-preview`。请使用 `@preview` 安装，并在生产接入前验证目标 BPMN XML 与引擎扩展。
+> 当前版本为 `0.3.7-preview`。请使用 `@preview` 安装，并在生产接入前验证目标 BPMN XML 与引擎扩展。
 
 ![BPMN Nova 流程设计器](../../assets/bpmn-nova-designer.jpg)
 
@@ -2573,7 +2575,7 @@ Viewer 接收引擎中立的 Runtime Snapshot。三种投影使用相同数据
 | 投影 | 配置 | 适用场景 |
 | --- | --- | --- |
 | 实际路径 | `projection: 'approval'` | 只展示实际发生的有效路径 |
-| 移动时间线 | `projection: 'compact'` | 按访问轮次展示动作、图片和附件 |
+| 移动时间线 | `projection: 'compact'` | 按访问轮次展示处理人头像、动作、图片和附件 |
 | 完整 BPMN | `projection: 'standard'` + `runtime` | 完整结构叠加运行状态 |
 
 ```js
@@ -2686,7 +2688,7 @@ const artifact = await shell.exportSvg({ theme: 'dark' })
 console.log(artifact.svg, artifact.warnings)
 ```
 
-导出完整业务内容，不受当前缩放、平移或滚动影响。图片会通过 Resolver 嵌入 SVG，普通附件只展示摘要。
+导出完整业务内容，不受当前缩放、平移或滚动影响。图片会通过 Resolver 嵌入 SVG，普通附件只展示摘要。移动时间线导出与页面一致，在人工任务卡标题左侧绘制处理人头像。
 
 ![SVG 导出确认预览](../../assets/bpmn-nova-svg-export-preview.jpg)
 
@@ -2737,7 +2739,7 @@ BPMN Nova 的 Vue 3.3+ Adapter，提供 Studio、Designer、Viewer、审批轨
 
 > **English summary:** Vue 3.3+ components and exposed instance methods for BPMN Nova process design, viewing, approval traces, properties, themes, and SVG export.
 
-> 当前版本为 `0.3.6-preview`。Vue 由宿主工程提供，本包不会替应用选择或升级框架版本。
+> 当前版本为 `0.3.7-preview`。Vue 由宿主工程提供，本包不会替应用选择或升级框架版本。
 
 ![BPMN Nova Vue 流程工作台](../../assets/bpmn-nova-designer.jpg)
 
@@ -2989,7 +2991,7 @@ defineProps({
 ```
 
 - `approval`：实际发生的有效路径。
-- `compact`：移动时间线、审批动作、图片和附件。
+- `compact`：移动时间线、处理人头像、审批动作、图片和附件。
 - `standard`：完整 BPMN 叠加运行状态。
 
 ![BPMN Nova Vue 移动审批时间线](../../assets/bpmn-nova-approval-mobile-timeline.jpg)
@@ -3111,7 +3113,7 @@ BPMN Nova 的 React 18+ Adapter，提供 Studio、Designer、Viewer、审批轨
 
 > **English summary:** React 18+ components and refs for BPMN Nova process design, viewing, approval traces, properties, themes, and SVG export.
 
-> 当前版本为 `0.3.6-preview`。React 与 React DOM 由宿主工程提供，本包不会替应用选择或升级框架版本。
+> 当前版本为 `0.3.7-preview`。React 与 React DOM 由宿主工程提供，本包不会替应用选择或升级框架版本。
 
 ![BPMN Nova React 流程工作台](../../assets/bpmn-nova-designer.jpg)
 
@@ -3334,7 +3336,7 @@ export function ApprovalTrace({ xml, runtime, resolveAsset }) {
 ```
 
 - `approval`：实际发生的有效路径。
-- `compact`：移动时间线、审批动作、图片和附件。
+- `compact`：移动时间线、处理人头像、审批动作、图片和附件。
 - `standard`：完整 BPMN 叠加运行状态。
 
 ![BPMN Nova React 移动审批时间线](../../assets/bpmn-nova-approval-mobile-timeline.jpg)
@@ -3452,7 +3454,7 @@ Apache-2.0. See [LICENSE](https://github.com/daxiangme/bpmn-nova/blob/dev/packag
 
 # BPMN Nova 组件参数
 
-本手册记录 `0.3.6-preview` 的公开组件参数、回调和实例方法。所有视觉组件都需要具有实际尺寸的容器，并显式导入所属包的 `styles.css`。
+本手册记录 `0.3.7-preview` 的公开组件参数、回调和实例方法。所有视觉组件都需要具有实际尺寸的容器，并显式导入所属包的 `styles.css`。
 
 ## 在线体验
 
@@ -3736,7 +3738,7 @@ Runtime Details、Timeline 和 Transition Details 组件通过对应 `createReac
 
 <!-- SOURCE: docs/src/api/index.md -->
 
-# BPMN Nova v0.3.6 Preview API
+# BPMN Nova v0.3.7 Preview API
 
 ## Framework Adapter 类型门面
 
@@ -4340,7 +4342,7 @@ Studio Shell 的轨迹切换项可通过 `projectionOptions` 配置。Playground
 
 运行实例默认使用稳定的 `approval` 实际路径图，不根据容器宽度自动改变展示形态。传入 `responsive: true` 且未显式设置 `projection`，或直接设置 `projection: 'auto'`，才会启用响应式切换：Viewer 容器宽度 `>= 720px` 时渲染实际有效路径图，`< 720px` 时切换为原生纵向滚动的审批时间线。响应式判断使用 `ResizeObserver`，不依赖全局窗口宽度；显式指定 `standard / approval / compact` 会固定投影。无 Runtime Snapshot 时默认仍为 `standard`。Compact 时间线始终占满 Viewer 容器宽度，不保留桌面居中最大宽度。
 
-`approval` 与 `compact` 都由 `createRuntimeTraceProjection()` 生成。普通 StartEvent / EndEvent 默认只在 `standard` 完整 BPMN 中显示，实际路径图和移动时间线从第一个真实 Activity Visit 开始；消息、定时、信号等特殊事件仍作为运行时里程碑保留。可通过 `runtimeTraceOptions.showStartMilestone / showEndMilestone` 恢复普通里程碑。投影优先按带时间的 `edgeVisits`、Activity Visit 和运行时转移还原实际路径，只在路径唯一可预测时追加后续人工任务。条件网关不会成为轨迹卡片，实际命中的 Sequence Flow 名称会作为步骤间条件标签，原始表达式不会进入轨迹 UI。需要核对流程定义时切换到 `standard` 查看完整 BPMN。
+`approval` 与 `compact` 都由 `createRuntimeTraceProjection()` 生成。普通 StartEvent / EndEvent 默认只在 `standard` 完整 BPMN 中显示，实际路径图和移动时间线从第一个真实 Activity Visit 开始；消息、定时、信号等特殊事件仍作为运行时里程碑保留。可通过 `runtimeTraceOptions.showStartMilestone / showEndMilestone` 恢复普通里程碑。投影优先按带时间的 `edgeVisits`、Activity Visit 和运行时转移还原实际路径，只在路径唯一可预测时追加后续人工任务。条件网关不会成为轨迹卡片，实际命中的 Sequence Flow 名称会作为步骤间条件标签，原始表达式不会进入轨迹 UI。需要核对流程定义时切换到 `standard` 查看完整 BPMN。自 `0.3.7-preview` 起，默认 Compact 时间线读取 `RuntimeParticipant`：人工任务卡在标题左侧展示处理人头像，有 `avatarUrl` 时出图，否则用名字首字；预测节点、自动任务和驳回/退回条不画头像。
 
 ```js
 const trace = createRuntimeTraceProjection({ model, runtime, presentation })
@@ -4457,7 +4459,7 @@ const artifact = await viewer.exportSvg({
 viewer.openSvgExportPreview()
 ```
 
-`SvgExportArtifact` 包含 `svg`、`blob`、文件名、尺寸、`viewBox` 与非阻断 `warnings`。移动时间线会展开全部历史动作；附件只输出名称、MIME 和大小，审批图片通过 `runtimeAssetResolver(asset, { purpose: 'export', ... })` 解析并转为 Data URL 内嵌。自定义 HTML Renderer 需要在 `svgExport.nodeRenderers` 或 `svgExport.runtimeTimelineRenderer` 提供纯 SVG 适配，否则导出器使用标准视觉并记录警告。导出不使用 `foreignObject`、页面 CSS、Blob URL 或临时附件地址。
+`SvgExportArtifact` 包含 `svg`、`blob`、文件名、尺寸、`viewBox` 与非阻断 `warnings`。移动时间线会展开全部历史动作；附件只输出名称、MIME 和大小，审批图片通过 `runtimeAssetResolver(asset, { purpose: 'export', ... })` 解析并转为 Data URL 内嵌。自 `0.3.7-preview` 起，默认 Compact 时间线导出还会绘制处理人头像：有 `RuntimeParticipant.avatarUrl` 时直接抓取并嵌入，失败或未提供时用名字首字，不走附件 Resolver。自定义 HTML Renderer 需要在 `svgExport.nodeRenderers` 或 `svgExport.runtimeTimelineRenderer` 提供纯 SVG 适配，否则导出器使用标准视觉并记录警告。导出不使用 `foreignObject`、页面 CSS、Blob URL 或临时附件地址。
 
 ## 实例级主题与运行态外观
 
@@ -5517,7 +5519,7 @@ Default   ●
 
 # BPMN Nova NPM 包与发布
 
-版本：`0.3.6-preview`。BPMN Nova 只发布三个 `@bpmn-nova` 公共包，均使用 ESM、附带 TypeScript 声明、采用 Apache-2.0 License，并通过 `preview` dist-tag 发布。
+版本：`0.3.7-preview`。BPMN Nova 只发布三个 `@bpmn-nova` 公共包，均使用 ESM、附带 TypeScript 声明、采用 Apache-2.0 License，并通过 `preview` dist-tag 发布。
 
 ## 公共包
 
@@ -5537,6 +5539,8 @@ React/Vue 的声明入口显式重导出宿主常用的 Core 类型：`BpmnEdge`
 
 `0.3.6-preview` 在 Adapter 根入口补充 `inspectRuntime`、`formatRuntimeInstant`、`parseRuntimeInstant`、`activityState` 及对应类型；并修正同一实例 Runtime 刷新与 `setRegions()` 的视口行为。详见更新日志与审批轨迹接入指南。
 
+`0.3.7-preview` 在 Compact 移动时间线的人工任务卡展示处理人头像，SVG 导出与确认预览同步；无 `avatarUrl` 时用名字首字，与默认节点详情一致。详见更新日志与审批轨迹接入指南。
+
 ## Studio 子路径
 
 Studio 根入口重新导出稳定的完整能力；以下子路径用于让导入意图更清晰：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmn-nova/studio",
-  "version": "0.3.6-preview",
+  "version": "0.3.7-preview",
   "description": "Complete BPMN Nova Studio with Designer, Viewer, Palette, Properties and runtime visualization.",
   "keywords": [
     "bpmn",