@bpmn-nova/studio 0.3.0-preview → 0.3.2-preview

package/dist/modules/runtime/index.js

@@ -0,0 +1,535 @@
+const TERMINAL_PROCESS_STATUSES = new Set(['completed', 'terminated']);
+const ABNORMAL_TRANSITION_TYPES = new Set(['reject', 'return']);
+const APPROVAL_ACTION_LABELS = {
+  submit: '提交', approve: '通过', reject: '驳回', return: '退回',
+  'add-sign': '加签', transfer: '转办', delegate: '委派', withdraw: '撤回', comment: '备注', skip: '跳过',
+};
+const OUTCOME_ACTION_TYPES = {
+  submitted: 'submit', approved: 'approve', rejected: 'reject', returned: 'return', skipped: 'skip',
+};
+
+function normalizeParticipant(record = {}) {
+  if (record.participant?.name) return { ...record.participant };
+  if (record.assignee) return { id: record.assigneeId || undefined, name: String(record.assignee) };
+  return null;
+}
+
+function recordOrder(record, index) {
+  const stamp = record.startTime || record.endTime;
+  const parsed = stamp ? Date.parse(stamp.replace(' ', 'T')) : Number.NaN;
+  return Number.isFinite(parsed) ? parsed : index;
+}
+
+function runtimeOrder(value, index) {
+  const stamp = value?.occurredAt || value?.time || value?.endTime || value?.startTime;
+  const parsed = stamp ? Date.parse(String(stamp).replace(' ', 'T')) : Number.NaN;
+  return Number.isFinite(parsed) ? parsed : index;
+}
+
+function normalizeRuntimeAsset(asset) {
+  if (!asset?.id) return null;
+  return {
+    id: String(asset.id),
+    name: String(asset.name || asset.id),
+    mediaType: String(asset.mediaType || 'application/octet-stream'),
+    ...(Number.isFinite(Number(asset.size)) ? { size: Number(asset.size) } : {}),
+    ...(Number.isFinite(Number(asset.width)) ? { width: Number(asset.width) } : {}),
+    ...(Number.isFinite(Number(asset.height)) ? { height: Number(asset.height) } : {}),
+  };
+}
+
+function normalizeApprovalContent(content, fallbackText = '') {
+  const source = typeof content === 'string' ? { plainText: content } : (content || {});
+  const assets = Array.isArray(source.assets) ? source.assets.map(normalizeRuntimeAsset).filter(Boolean) : [];
+  const blocks = Array.isArray(source.blocks)
+    ? source.blocks.filter((block) => block && typeof block === 'object').map((block) => {
+      if (block.type === 'paragraph') return { type: 'paragraph', text: String(block.text || '') };
+      if (block.type === 'image') return { type: 'image', assetId: String(block.assetId || ''), ...(block.alt ? { alt: String(block.alt) } : {}) };
+      if (block.type === 'file') return { type: 'file', assetId: String(block.assetId || '') };
+      return { type: String(block.type || 'unknown') };
+    })
+    : [];
+  const paragraphText = blocks.filter((block) => block.type === 'paragraph').map((block) => block.text.trim()).filter(Boolean).join('\n');
+  const plainText = String(source.plainText ?? fallbackText ?? paragraphText).trim() || paragraphText;
+  if (!blocks.length && plainText) blocks.push({ type: 'paragraph', text: plainText });
+  const referencedAssets = new Set(blocks.filter((block) => ['image', 'file'].includes(block.type)).map((block) => block.assetId));
+  assets.forEach((asset) => {
+    if (referencedAssets.has(asset.id)) return;
+    blocks.push({ type: asset.mediaType.startsWith('image/') ? 'image' : 'file', assetId: asset.id });
+  });
+  return { plainText, blocks, assets };
+}
+
+function normalizeApprovalAction(action, index) {
+  const type = String(action?.type || 'comment');
+  const actor = action?.actor?.name ? { ...action.actor, name: String(action.actor.name) } : null;
+  const targets = Array.isArray(action?.targets)
+    ? action.targets.filter((target) => target?.name).map((target) => ({ ...target, name: String(target.name) }))
+    : [];
+  return {
+    id: String(action?.id || `runtime-action-${index + 1}`),
+    type,
+    ...(action?.label ? { label: String(action.label) } : {}),
+    elementId: String(action?.elementId || ''),
+    visitId: String(action?.visitId || action?.activityId || action?.id || `runtime-action-${index + 1}`),
+    ...(action?.activityId ? { activityId: String(action.activityId) } : {}),
+    ...(actor ? { actor } : {}),
+    occurredAt: String(action?.occurredAt || action?.time || ''),
+    ...(targets.length ? { targets } : {}),
+    ...(action?.targetElementId ? { targetElementId: String(action.targetElementId) } : {}),
+    content: normalizeApprovalContent(action?.content),
+    ...(action?.metadata && typeof action.metadata === 'object' ? { metadata: { ...action.metadata } } : {}),
+  };
+}
+
+function legacyActionForRecord(record, index) {
+  const comment = String(record.comment || '').trim();
+  const type = OUTCOME_ACTION_TYPES[record.outcome] || (record.outcome && record.outcome !== 'pending' ? String(record.outcome) : 'comment');
+  if (!comment && (!record.outcome || record.outcome === 'pending')) return null;
+  return normalizeApprovalAction({
+    id: `legacy-activity-action:${record.id || index + 1}`,
+    type,
+    activityId: record.id || undefined,
+    elementId: record.elementId,
+    visitId: record.visitId || record.multiInstanceId || record.id || `record-${index + 1}`,
+    actor: normalizeParticipant(record) || undefined,
+    occurredAt: record.endTime || record.startTime || '',
+    content: comment ? { plainText: comment } : undefined,
+  }, index);
+}
+
+function actionText(action) {
+  return String(action?.content?.plainText || '').trim();
+}
+
+function approvalActionLabel(action) {
+  return action?.label || APPROVAL_ACTION_LABELS[action?.type] || action?.type || '审批操作';
+}
+
+function summarizeApprovalActions(actions = []) {
+  const latestAction = [...actions].reverse().find((action) => action.plainText || action.assetCount) || actions.at(-1) || null;
+  const assetSummary = latestAction
+    ? [latestAction.imageCount ? `${latestAction.imageCount} 张图片` : '', latestAction.fileCount ? `${latestAction.fileCount} 个附件` : ''].filter(Boolean).join(' · ')
+    : '';
+  return {
+    latestAction,
+    actionText: latestAction?.plainText || '',
+    actionSummary: latestAction ? [latestAction.label, latestAction.plainText, assetSummary].filter(Boolean).join(' · ') : '',
+    imageCount: actions.reduce((sum, action) => sum + action.imageCount, 0),
+    fileCount: actions.reduce((sum, action) => sum + action.fileCount, 0),
+    assetCount: actions.reduce((sum, action) => sum + action.assetCount, 0),
+  };
+}
+
+function groupVisits(records = []) {
+  const groups = new Map();
+  records.forEach((record, index) => {
+    const key = record.visitId
+      ? `visit:${record.visitId}`
+      : record.multiInstanceId
+        ? `multi:${record.multiInstanceId}`
+        : `record:${record.id || index}`;
+    if (!groups.has(key)) groups.set(key, { id: record.visitId || record.multiInstanceId || record.id || String(index), records: [], order: recordOrder(record, index) });
+    const visit = groups.get(key);
+    visit.records.push(record);
+    visit.order = Math.max(visit.order, recordOrder(record, index));
+  });
+  return [...groups.values()].sort((a, b) => a.order - b.order).map((visit, index) => ({ ...visit, round: index + 1 }));
+}
+
+function resolveVisitStatus(records = []) {
+  if (!records.length) return 'idle';
+  if (records.some((item) => item.status === 'failed')) return 'failed';
+  if (records.some((item) => item.status === 'active')) return 'active';
+  if (records.every((item) => item.status === 'skipped')) return 'skipped';
+  if (records.some((item) => item.status === 'cancelled') && !records.some((item) => item.status === 'completed')) return 'cancelled';
+  return 'completed';
+}
+
+function uniqueParticipants(records = []) {
+  const seen = new Set();
+  const result = [];
+  for (const record of records) {
+    const participant = normalizeParticipant(record);
+    if (!participant?.name) continue;
+    const key = participant.id || participant.name;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(participant);
+  }
+  return result;
+}
+
+function participantSummary(participants) {
+  if (!participants.length) return '';
+  const visible = participants.slice(0, 2).map((item) => item.name).join('、');
+  return participants.length > 2 ? `${visible} +${participants.length - 2}` : visible;
+}
+
+function candidateSummary(node) {
+  const properties = node?.properties || {};
+  const candidate = properties.candidateGroups || properties.candidateUsers;
+  if (!candidate) return '';
+  const value = Array.isArray(candidate) ? candidate.join('、') : String(candidate);
+  return value ? `待领取 · ${value}` : '';
+}
+
+function baseStatusLabel(status) {
+  return {
+    completed: '已完成', active: '处理中', failed: '失败', cancelled: '已取消', skipped: '未经过', idle: '未到达', rejected: '已驳回',
+  }[status] || status;
+}
+
+function transitionOrder(transition, index) {
+  const stamp = transition.occurredAt || transition.time;
+  const parsed = stamp ? Date.parse(stamp.replace(' ', 'T')) : Number.NaN;
+  return Number.isFinite(parsed) ? parsed : index;
+}
+
+function edgeVisitOrder(visit, index) {
+  const stamp = visit.occurredAt || visit.time;
+  const parsed = stamp ? Date.parse(stamp.replace(' ', 'T')) : Number.NaN;
+  return Number.isFinite(parsed) ? parsed : index;
+}
+
+function inferInvalidatedPath(model, runtime, transition) {
+  const source = model?.nodes?.find((node) => node.id === transition.sourceElementId);
+  const target = model?.nodes?.find((node) => node.id === transition.targetElementId);
+  if (!source || !target) return { activityIds: [], edgeIds: [], issues: ['驳回来源或目标节点不存在，无法推断失效路径。'] };
+  const rootScope = model.id;
+  if ((source.scopeId || rootScope) !== (target.scopeId || rootScope)) return { activityIds: [], edgeIds: [], issues: ['驳回跨越流程作用域，未自动重置路径。'] };
+  const visited = new Set(runtime.visitedEdges);
+  const edges = (model.edges || []).filter((edge) => visited.has(edge.id) && (edge.scopeId || rootScope) === (source.scopeId || rootScope));
+  const outgoing = new Map();
+  for (const edge of edges) {
+    if (!outgoing.has(edge.source)) outgoing.set(edge.source, []);
+    outgoing.get(edge.source).push(edge);
+  }
+  const paths = [];
+  const walk = (nodeId, nodeIds, edgeIds) => {
+    if (paths.length > 1 || nodeIds.length > (model.nodes?.length || 0) + 1) return;
+    if (nodeId === source.id) {
+      paths.push({ nodeIds, edgeIds });
+      return;
+    }
+    for (const edge of outgoing.get(nodeId) || []) {
+      if (nodeIds.includes(edge.target)) continue;
+      walk(edge.target, [...nodeIds, edge.target], [...edgeIds, edge.id]);
+    }
+  };
+  walk(target.id, [target.id], []);
+  if (paths.length !== 1) {
+    return {
+      activityIds: [], edgeIds: [],
+      issues: [paths.length ? '驳回路径存在多个候选分支，未自动重置路径。' : '未找到驳回目标到来源的已访问路径。'],
+    };
+  }
+  return { activityIds: paths[0].nodeIds.slice(1), edgeIds: paths[0].edgeIds, issues: [] };
+}
+
+export function normalizeRuntime(snapshot = {}) {
+  snapshot = snapshot || {};
+  const activities = Array.isArray(snapshot.activities)
+    ? snapshot.activities.map((record) => ({ ...record, participant: normalizeParticipant(record) || undefined }))
+    : [];
+  const explicitActions = Array.isArray(snapshot.actions)
+    ? snapshot.actions.map(normalizeApprovalAction)
+    : [];
+  const actions = [...explicitActions];
+  const explicitActivityIds = new Set(explicitActions.map((action) => action.activityId).filter(Boolean));
+  activities.forEach((record, index) => {
+    if (record.id && explicitActivityIds.has(record.id)) return;
+    const action = legacyActionForRecord(record, index);
+    if (action) actions.push(action);
+  });
+  const transitions = Array.isArray(snapshot.transitions)
+    ? snapshot.transitions.map((transition, index) => ({ id: transition.id || `runtime-transition-${index + 1}`, type: transition.type || 'forward', ...transition }))
+    : [];
+  transitions.forEach((transition, index) => {
+    if (transition.actionId && actions.some((action) => action.id === transition.actionId)) return;
+    if (!['reject', 'return', 'skip'].includes(transition.type)) return;
+    const comment = String(transition.comment || '').trim();
+    const sourceRecord = activities.find((record) => record.id === transition.sourceActivityId);
+    const reusable = actions.find((action) => action.activityId && action.activityId === transition.sourceActivityId
+      && action.type === transition.type && (!comment || actionText(action) === comment));
+    if (reusable) {
+      transition.actionId = reusable.id;
+      return;
+    }
+    const action = normalizeApprovalAction({
+      id: `legacy-transition-action:${transition.id}`,
+      type: transition.type,
+      activityId: transition.sourceActivityId,
+      elementId: transition.sourceElementId,
+      visitId: sourceRecord?.visitId || sourceRecord?.multiInstanceId || sourceRecord?.id || `transition:${transition.id}`,
+      actor: transition.operator ? { name: String(transition.operator) } : undefined,
+      occurredAt: transition.occurredAt || transition.time || '',
+      targetElementId: transition.targetElementId,
+      content: comment ? { plainText: comment } : undefined,
+    }, activities.length + actions.length + index);
+    actions.push(action);
+    transition.actionId = action.id;
+  });
+  const edgeVisits = Array.isArray(snapshot.edgeVisits)
+    ? snapshot.edgeVisits.map((visit, index) => ({ id: visit.id || `runtime-edge-visit-${index + 1}`, status: visit.status || 'effective', ...visit }))
+    : [];
+  const orderedActions = actions
+    .map((action, index) => ({ action, order: runtimeOrder(action, index), index }))
+    .sort((a, b) => (a.order - b.order) || (a.index - b.index))
+    .map(({ action }) => action);
+  return {
+    ...snapshot,
+    processInstanceId: snapshot.processInstanceId || '',
+    status: snapshot.status || 'running',
+    activities,
+    actions: orderedActions,
+    visitedEdges: Array.isArray(snapshot.visitedEdges) ? [...snapshot.visitedEdges] : [],
+    transitions,
+    edgeVisits,
+  };
+}
+
+export function activityState(runtime, elementId) {
+  if (!runtime) return { status: 'idle', records: [], latestRecords: [], visits: [] };
+  const records = runtime.activities.filter((item) => item.elementId === elementId);
+  const visits = groupVisits(records);
+  const latestRecords = visits.at(-1)?.records || [];
+  return { status: resolveVisitStatus(latestRecords), records, latestRecords, visits };
+}
+
+export function createRuntimePresentation({ model, runtime, appearance = null } = {}) {
+  const normalized = normalizeRuntime(runtime);
+  const nodes = new Map((model?.nodes || []).map((node) => [node.id, node]));
+  const activityStates = new Map((model?.nodes || []).map((node) => [node.id, activityState(normalized, node.id)]));
+  const nodePresentations = new Map();
+  const actionPresentations = normalized.actions.map((action, index) => {
+    const assets = action.content.assets || [];
+    const referenced = (action.content.blocks || []).filter((block) => ['image', 'file'].includes(block.type));
+    const imageIds = new Set(referenced.filter((block) => block.type === 'image').map((block) => block.assetId));
+    const fileIds = new Set(referenced.filter((block) => block.type === 'file').map((block) => block.assetId));
+    const images = assets.filter((asset) => imageIds.has(asset.id) || (!referenced.length && asset.mediaType.startsWith('image/')));
+    const files = assets.filter((asset) => fileIds.has(asset.id) || (!referenced.length && !asset.mediaType.startsWith('image/')));
+    const baseAction = {
+      ...action,
+      explicitLabel: action.label || null,
+      label: approvalActionLabel(action),
+      plainText: action.content.plainText || '',
+      images,
+      files,
+      imageCount: images.length,
+      fileCount: files.length,
+      assetCount: images.length + files.length,
+      order: runtimeOrder(action, index),
+    };
+    const resolvedAppearance = appearance?.resolveAction?.(baseAction);
+    return resolvedAppearance
+      ? { ...baseAction, label: resolvedAppearance.label, iconId: resolvedAppearance.iconId, tone: resolvedAppearance.tone }
+      : baseAction;
+  });
+  const actionMap = new Map(actionPresentations.map((action) => [action.id, action]));
+  const rawTransitions = normalized.transitions
+    .map((transition, index) => ({ ...transition, order: transitionOrder(transition, index) }))
+    .sort((a, b) => a.order - b.order);
+  const transitionPresentations = rawTransitions.map((transition) => {
+    const targetName = nodes.get(transition.targetElementId)?.name || transition.targetElementId || '';
+    const labelPrefix = transition.type === 'reject' ? '驳回至' : transition.type === 'return' ? '退回至' : transition.type === 'skip' ? '跳过' : '流转至';
+    const targetState = activityStates.get(transition.targetElementId);
+    const targetRecordsAfter = (targetState?.records || []).filter((record, index) => recordOrder(record, index) > transition.order);
+    const targetStatusAfter = resolveVisitStatus(groupVisits(targetRecordsAfter).at(-1)?.records || []);
+    const state = transition.state || (ABNORMAL_TRANSITION_TYPES.has(transition.type)
+      ? (targetRecordsAfter.length && targetStatusAfter !== 'active' ? 'resolved' : 'active')
+      : 'resolved');
+    const hasExplicitInvalidation = Array.isArray(transition.invalidatedActivityIds) || Array.isArray(transition.invalidatedEdgeIds);
+    const invalidation = hasExplicitInvalidation
+      ? { activityIds: [...(transition.invalidatedActivityIds || [])], edgeIds: [...(transition.invalidatedEdgeIds || [])], issues: [] }
+      : ABNORMAL_TRANSITION_TYPES.has(transition.type)
+        ? inferInvalidatedPath(model, normalized, transition)
+        : { activityIds: [], edgeIds: [], issues: [] };
+    return {
+      ...transition,
+      action: actionMap.get(transition.actionId) || null,
+      sourceName: nodes.get(transition.sourceElementId)?.name || transition.sourceElementId || '',
+      targetName,
+      label: targetName ? `${labelPrefix}：${targetName}` : labelPrefix,
+      state,
+      visible: ABNORMAL_TRANSITION_TYPES.has(transition.type) && state === 'active',
+      resolvedAt: transition.resolvedAt || (state === 'resolved' ? targetRecordsAfter.map((record) => record.endTime).filter(Boolean).at(-1) : undefined),
+      invalidatedActivityIds: invalidation.activityIds,
+      invalidatedEdgeIds: invalidation.edgeIds,
+      issues: invalidation.issues,
+    };
+  });
+  const latestAbnormal = [...transitionPresentations].reverse().find((item) => ABNORMAL_TRANSITION_TYPES.has(item.type));
+  transitionPresentations.forEach((transition) => { transition.latest = transition === latestAbnormal; });
+
+  const invalidatedNodes = new Map();
+  const invalidatedEdges = new Map();
+  const hasActivityAfter = (elementId, transition) => (activityStates.get(elementId)?.records || [])
+    .some((record, index) => recordOrder(record, index) > transition.order);
+  const hasEdgeVisitAfter = (edgeId, transition) => {
+    const edgeVisits = normalized.edgeVisits.filter((visit) => visit.edgeId === edgeId);
+    if (edgeVisits.length) return edgeVisits.some((visit, index) => visit.status !== 'superseded' && edgeVisitOrder(visit, index) > transition.order);
+    const edge = model?.edges?.find((item) => item.id === edgeId);
+    return edge ? hasActivityAfter(edge.target, transition) : false;
+  };
+  for (const transition of transitionPresentations.filter((item) => ABNORMAL_TRANSITION_TYPES.has(item.type))) {
+    for (const elementId of transition.invalidatedActivityIds) if (!hasActivityAfter(elementId, transition)) invalidatedNodes.set(elementId, transition);
+    for (const edgeId of transition.invalidatedEdgeIds) if (!hasEdgeVisitAfter(edgeId, transition)) invalidatedEdges.set(edgeId, transition);
+  }
+
+  for (const node of model?.nodes || []) {
+    const state = activityStates.get(node.id);
+    const actions = actionPresentations.filter((action) => action.elementId === node.id);
+    const visits = state.visits.map((visit) => {
+      const visitActions = actions.filter((action) => action.visitId === visit.id);
+      return { ...visit, actions: visitActions, ...summarizeApprovalActions(visitActions) };
+    });
+    const latestVisit = visits.at(-1) || null;
+    const latestRecords = latestVisit?.records || [];
+    const participants = uniqueParticipants(latestRecords);
+    const approvalMode = latestRecords.find((item) => item.approvalMode)?.approvalMode || null;
+    const multiInstanceMode = latestRecords.find((item) => item.multiInstanceMode)?.multiInstanceMode || null;
+    const declaredTotal = latestRecords.reduce((max, item) => Math.max(max, Number(item.totalInstances) || 0), 0);
+    const total = Math.max(declaredTotal, latestRecords.length, participants.length);
+    const completed = latestRecords.filter((item) => item.status === 'completed').length;
+    const required = latestRecords.reduce((max, item) => Math.max(max, Number(item.requiredInstances) || 0), 0) || (approvalMode === 'any' ? 1 : total);
+    const inboundReentry = transitionPresentations.some((item) => ABNORMAL_TRANSITION_TYPES.has(item.type) && item.targetElementId === node.id);
+    const latestSourceRejection = [...transitionPresentations].reverse().find((item) => item.type === 'reject' && item.sourceElementId === node.id);
+    const rejectionSource = latestRecords.some((item) => item.outcome === 'rejected')
+      || (latestSourceRejection && (!latestVisit || latestSourceRejection.order >= latestVisit.order));
+    const skipped = !state.records.length && transitionPresentations.some((item) => item.type === 'skip' && item.targetElementId === node.id);
+    let status = skipped ? 'skipped' : state.status;
+    if (rejectionSource && status === 'completed') status = 'rejected';
+    const isReentry = inboundReentry && Boolean(latestVisit) && (latestVisit.round > 1 || status === 'active');
+    const superseded = invalidatedNodes.has(node.id);
+    const pathStatus = superseded || status === 'rejected' ? 'idle' : status;
+
+    let statusLabel = baseStatusLabel(status);
+    if (isReentry && status === 'active') statusLabel = '重新审批';
+    else if (status === 'active' || status === 'completed') {
+      if (approvalMode === 'all') statusLabel = `${multiInstanceMode === 'sequential' ? '顺序会签' : '会签'} ${completed}/${total || required}`;
+      else if (approvalMode === 'any') statusLabel = `或签 ${completed}/${total || required}`;
+      else if (participants.length > 1) statusLabel = `多人审批 ${completed}/${total}`;
+    }
+
+    let summary = participantSummary(participants);
+    const isApprovalTask = ['userTask', 'callActivity'].includes(node.type);
+    const isAutomatedTask = ['serviceTask', 'scriptTask', 'businessRuleTask', 'sendTask', 'receiveTask'].includes(node.type);
+    if (!summary && isApprovalTask) {
+      if (status === 'active') summary = candidateSummary(node) || '待分配审批人';
+      else if (status === 'skipped') summary = '分支未经过';
+      else if (!state.records.length) summary = TERMINAL_PROCESS_STATUSES.has(normalized.status) ? '流程未经过' : '尚未流转';
+    } else if (!summary && isAutomatedTask) {
+      summary = status === 'active' ? '执行中' : status === 'completed' ? '执行完成' : status === 'failed' ? '执行失败' : status === 'skipped' ? '分支未经过' : '等待执行';
+    }
+
+    const relatedTransitions = transitionPresentations.filter((item) => item.sourceElementId === node.id || item.targetElementId === node.id);
+    const actionSummary = summarizeApprovalActions(actions);
+    nodePresentations.set(node.id, {
+      elementId: node.id, status, pathStatus, superseded, statusLabel, summary, fullSummary: participants.map((item) => item.name).join('、') || summary,
+      participants, approvalMode, multiInstanceMode, completed, total, required, round: latestVisit?.round || 0,
+      records: state.records, latestRecords, visits, transitions: relatedTransitions, actions, ...actionSummary,
+      isReentry,
+      hasDetails: Boolean(state.records.length || actions.length || relatedTransitions.length),
+    });
+  }
+
+  return {
+    runtime: normalized,
+    getNode(elementId) {
+      return nodePresentations.get(elementId) || {
+        elementId, status: 'idle', pathStatus: 'idle', superseded: false, statusLabel: '未到达', summary: '', fullSummary: '', participants: [], approvalMode: null,
+        multiInstanceMode: null, completed: 0, total: 0, required: 0, round: 0, records: [], latestRecords: [], visits: [], transitions: [], actions: [], latestAction: null,
+        actionText: '', actionSummary: '', imageCount: 0, fileCount: 0, assetCount: 0, isReentry: false, hasDetails: false,
+      };
+    },
+    getEdge(edgeId) {
+      const edgeVisits = normalized.edgeVisits.filter((visit) => visit.edgeId === edgeId);
+      const latestVisit = edgeVisits
+        .map((visit, index) => ({ visit, order: edgeVisitOrder(visit, index) }))
+        .sort((a, b) => a.order - b.order)
+        .at(-1)?.visit;
+      const visited = normalized.visitedEdges.includes(edgeId) || edgeVisits.length > 0;
+      const superseded = invalidatedEdges.has(edgeId) || latestVisit?.status === 'superseded';
+      const status = !visited || superseded ? 'idle' : 'completed';
+      return { edgeId, status, visited, historicallyVisited: visited, superseded };
+    },
+    getAction(actionId) { return actionMap.get(actionId) || null; },
+    getActions(elementId = null) { return elementId ? actionPresentations.filter((action) => action.elementId === elementId) : [...actionPresentations]; },
+    getTransition(transitionId) { return transitionPresentations.find((item) => item.id === transitionId) || null; },
+    getTransitions() { return transitionPresentations; },
+  };
+}
+
+export function demoRuntime() {
+  return normalizeRuntime({
+    processInstanceId: 'PI-DEMO-20260824-001',
+    status: 'running',
+    visitedEdges: ['Flow_Start_Submit', 'Flow_Submit_Manager', 'Flow_Manager_Gateway', 'Flow_To_Director'],
+    edgeVisits: [
+      { id: 'edge-start-submit-1', edgeId: 'Flow_Start_Submit', occurredAt: '2026-08-24 09:00' },
+      { id: 'edge-submit-manager-1', edgeId: 'Flow_Submit_Manager', occurredAt: '2026-08-24 09:08' },
+      { id: 'edge-manager-gateway-1', edgeId: 'Flow_Manager_Gateway', occurredAt: '2026-08-24 10:12' },
+      { id: 'edge-gateway-director-1', edgeId: 'Flow_To_Director', occurredAt: '2026-08-24 10:12' },
+    ],
+    activities: [
+      { id: 'act-start-1', elementId: 'StartEvent_1', visitId: 'visit-start-1', status: 'completed', startTime: '2026-08-24 09:00', endTime: '2026-08-24 09:00' },
+      { id: 'act-submit-1', elementId: 'UserTask_Submit', visitId: 'visit-submit-1', status: 'completed', assignee: '张三', startTime: '2026-08-24 09:00', endTime: '2026-08-24 09:08', outcome: 'submitted', comment: '采购申请已提交。' },
+      { id: 'act-manager-1', elementId: 'UserTask_Manager', visitId: 'visit-manager-1', status: 'completed', assignee: '李经理', startTime: '2026-08-24 09:08', endTime: '2026-08-24 10:12', outcome: 'approved', comment: '资料完整，同意提交总经理审批。' },
+      { id: 'act-gateway-1', elementId: 'Gateway_Amount', visitId: 'visit-gateway-1', status: 'completed', startTime: '2026-08-24 10:12', endTime: '2026-08-24 10:12' },
+      { id: 'act-director-1', elementId: 'UserTask_Director', visitId: 'visit-director-1', status: 'completed', assignee: '王总', startTime: '2026-08-24 10:12', endTime: '2026-08-24 10:30', outcome: 'rejected', comment: '采购金额说明不完整，请补充后重新提交。' },
+      { id: 'act-manager-2', elementId: 'UserTask_Manager', visitId: 'visit-manager-2', status: 'active', assignee: '李经理', startTime: '2026-08-24 10:31', outcome: 'pending' },
+    ],
+    actions: [
+      {
+        id: 'action-submit-1', type: 'submit', activityId: 'act-submit-1', elementId: 'UserTask_Submit', visitId: 'visit-submit-1',
+        actor: { id: 'user-zhang', name: '张三' }, occurredAt: '2026-08-24 09:08',
+        content: { plainText: '采购申请已提交。' },
+      },
+      {
+        id: 'action-manager-add-sign-1', type: 'add-sign', activityId: 'act-manager-1', elementId: 'UserTask_Manager', visitId: 'visit-manager-1',
+        actor: { id: 'user-manager-li', name: '李经理' }, targets: [{ id: 'user-supervisor-wang', name: '王主管' }], occurredAt: '2026-08-24 09:36',
+        content: { plainText: '采购金额较大，请协同核验报价材料。' },
+      },
+      {
+        id: 'action-manager-approve-1', type: 'approve', activityId: 'act-manager-1', elementId: 'UserTask_Manager', visitId: 'visit-manager-1',
+        actor: { id: 'user-manager-li', name: '李经理' }, occurredAt: '2026-08-24 10:12',
+        content: {
+          plainText: '资料完整，同意提交总经理审批。',
+          blocks: [
+            { type: 'paragraph', text: '资料完整，同意提交总经理审批。现场报价单和采购核验清单见附件。' },
+            { type: 'image', assetId: 'asset-quotation-image', alt: '现场报价单预览' },
+            { type: 'file', assetId: 'asset-purchase-checklist' },
+          ],
+          assets: [
+            { id: 'asset-quotation-image', name: '现场报价单.svg', mediaType: 'image/svg+xml', size: 2861, width: 960, height: 600 },
+            { id: 'asset-purchase-checklist', name: '采购核验清单.txt', mediaType: 'text/plain', size: 248 },
+          ],
+        },
+      },
+      {
+        id: 'action-director-reject-1', type: 'reject', activityId: 'act-director-1', elementId: 'UserTask_Director', visitId: 'visit-director-1',
+        actor: { id: 'user-director-wang', name: '王总' }, occurredAt: '2026-08-24 10:30', targetElementId: 'UserTask_Manager',
+        content: { plainText: '采购金额说明不完整，请补充后重新提交。' },
+      },
+      {
+        id: 'action-manager-transfer-2', type: 'transfer', activityId: 'act-manager-2', elementId: 'UserTask_Manager', visitId: 'visit-manager-2',
+        actor: { id: 'user-manager-li', name: '李经理' }, targets: [{ id: 'user-supervisor-wang', name: '王主管' }], occurredAt: '2026-08-24 10:34',
+        content: { plainText: '材料补充由王主管继续跟进。' },
+      },
+    ],
+    transitions: [{
+      id: 'transition-reject-director-manager',
+      type: 'reject',
+      sourceActivityId: 'act-director-1',
+      sourceElementId: 'UserTask_Director',
+      targetElementId: 'UserTask_Manager',
+      operator: '王总',
+      occurredAt: '2026-08-24 10:30',
+      actionId: 'action-director-reject-1',
+      comment: '采购金额说明不完整，请补充后重新提交。',
+      invalidatedActivityIds: ['Gateway_Amount', 'UserTask_Director'],
+      invalidatedEdgeIds: ['Flow_Manager_Gateway', 'Flow_To_Director'],
+    }],
+  });
+}

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

@@ -0,0 +1,95 @@
+export type NovaThemeMode = 'light' | 'dark' | 'auto'
+export type NovaResolvedTheme = 'light' | 'dark'
+
+export interface NovaThemeState {
+  mode: NovaThemeMode
+  resolvedTheme: NovaResolvedTheme
+}
+
+export interface NovaThemeSnapshot {
+  resolvedTheme: NovaResolvedTheme
+  colors: Readonly<Record<NovaSemanticColorToken, string>>
+  tones: Readonly<Record<string, Readonly<Required<NovaThemeTone>>>>
+  fontFamily: string
+}
+
+export type NovaSemanticColorToken =
+  | 'canvas' | 'surface' | 'surfaceRaised' | 'surfaceSubtle' | 'surfaceMuted'
+  | 'text' | 'textSecondary' | 'textMuted' | 'textInverse'
+  | 'border' | 'borderStrong' | 'divider'
+  | 'primary' | 'primaryHover' | 'primarySoft' | 'focusRing'
+  | 'edge' | 'gridDot' | 'backdrop'
+
+export interface NovaThemeTone {
+  foreground?: string
+  background?: string
+  border?: string
+  strong?: string
+}
+
+export interface NovaThemePalette {
+  colors?: Partial<Record<NovaSemanticColorToken, string>>
+  shadows?: Partial<Record<'sm' | 'md' | 'lg', string>>
+  tones?: Record<string, NovaThemeTone>
+}
+
+export interface NovaThemeOptions {
+  mode?: NovaThemeMode
+  light?: NovaThemePalette | null
+  dark?: NovaThemePalette | null
+}
+
+export type NovaThemeInput = NovaThemeMode | NovaThemeOptions
+
+export interface RuntimeActionAppearance {
+  label?: string
+  iconId?: string
+  tone?: string
+}
+
+export interface RuntimeAppearanceOptions {
+  statuses?: Record<string, string>
+  actions?: Record<string, RuntimeActionAppearance>
+  transitions?: Record<string, { tone?: string }>
+}
+
+export interface RuntimeAppearanceActionInput {
+  type?: string
+  explicitLabel?: string
+  label?: string
+}
+
+export interface RuntimeAppearanceTransitionInput {
+  type?: string
+}
+
+export interface RuntimeAppearanceResolver {
+  resolveStatus(status: string): string
+  resolveAction(action?: RuntimeAppearanceActionInput): Required<RuntimeActionAppearance>
+  resolveTransition(transition?: RuntimeAppearanceTransitionInput): { tone: string }
+}
+
+export class ThemeController {
+  constructor(options: {
+    root: HTMLElement
+    theme?: NovaThemeInput | null
+    onChange?: (state: NovaThemeState) => void
+  })
+  setTheme(theme: NovaThemeInput | null): NovaThemeState
+  setMode(mode: NovaThemeMode): NovaThemeState
+  getState(): NovaThemeState
+  getSnapshot(theme?: 'current' | NovaResolvedTheme): NovaThemeSnapshot
+  subscribe(listener: (state: NovaThemeState) => void): () => void
+  destroy(): void
+}
+
+export function createThemeController(options: ConstructorParameters<typeof ThemeController>[0]): ThemeController
+export function createRuntimeAppearance(options?: RuntimeAppearanceOptions): RuntimeAppearanceResolver
+export function applyRuntimeTone(element: HTMLElement | SVGElement, tone?: string | null): string
+
+export const NOVA_THEME_MODES: readonly NovaThemeMode[]
+export const DEFAULT_RUNTIME_APPEARANCE: Readonly<{
+  statuses: Readonly<Record<string, string>>
+  actions: Readonly<Record<string, Readonly<Required<RuntimeActionAppearance>>>>
+  transitions: Readonly<Record<string, Readonly<{ tone: string }>>>
+}>