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

package/dist/modules/runtime/visits.js

@@ -0,0 +1,167 @@
+import { parseRuntimeInstant, compareRuntimeOrder, runtimeInstant } from './time.js';
+import { pushDiagnostic } from './diagnostics.js';
+
+const TERMINAL = new Set(['completed', 'failed', 'cancelled', 'skipped']);
+
+export 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';
+}
+
+export function resolveEffectiveStatus(visits = []) {
+  const records = visits.flatMap((visit) => visit.records || []);
+  if (!records.length) return 'idle';
+  if (records.some((item) => item.status === 'active')) return 'active';
+  if (records.some((item) => item.status === 'failed')) return 'failed';
+  if (records.some((item) => item.status === 'completed')) return 'completed';
+  if (records.some((item) => item.status === 'cancelled') && !records.some((item) => item.status === 'completed')) return 'cancelled';
+  if (records.every((item) => item.status === 'skipped')) return 'skipped';
+  return resolveVisitStatus(records);
+}
+
+export 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: [],
+        index,
+      });
+    }
+    groups.get(key).records.push(record);
+  });
+  return [...groups.values()]
+    .sort((left, right) => compareRuntimeOrder(visitOrderKey(left), visitOrderKey(right)))
+    .map((visit, index) => ({ id: visit.id, records: visit.records, round: index + 1, index: visit.index }));
+}
+
+export function markEffectiveVisits(visits = [], { elementId, transitions = [], diagnostics = null } = {}) {
+  if (visits.length <= 1) {
+    return visits.map((visit) => ({ ...visit, effective: true, superseded: false }));
+  }
+  const ranges = visits.map((visit, index) => ({ visit, index, ...visitRange(visit) }));
+  const superseded = new Set();
+
+  for (const visit of visits) {
+    for (const record of visit.records) {
+      const target = record.supersedesVisitId;
+      if (!target) continue;
+      if (visits.some((candidate) => candidate.id === target)) superseded.add(target);
+      else {
+        pushDiagnostic(diagnostics, {
+          code: 'unknown-superseded-visit',
+          level: 'warning',
+          message: 'supersedesVisitId 未匹配到同节点 Visit。',
+          fieldPath: `activities.supersedesVisitId`,
+          elementId,
+          activityId: record.id,
+          visitId: visit.id,
+        });
+      }
+    }
+  }
+
+  const inbound = transitions.filter((transition) => ['reject', 'return'].includes(transition.type) && transition.targetElementId === elementId);
+  const timed = ranges.some((range) => range.start != null || range.end != null);
+
+  for (let earlierIndex = 0; earlierIndex < ranges.length; earlierIndex += 1) {
+    for (let laterIndex = earlierIndex + 1; laterIndex < ranges.length; laterIndex += 1) {
+      const earlier = ranges[earlierIndex];
+      const later = ranges[laterIndex];
+      if (superseded.has(later.visit.id)) continue;
+      const sequential = isSequentialReplacement(earlier, later, inbound);
+      const overlapping = isOverlappingOpen(earlier, later);
+      if (overlapping && !sequential) {
+        pushDiagnostic(diagnostics, {
+          code: 'concurrent-visits',
+          level: 'info',
+          message: '同一节点存在时间重叠且未声明替代关系的独立 Visit。',
+          fieldPath: 'activities.visitId',
+          elementId,
+          visitId: earlier.visit.id,
+        });
+        continue;
+      }
+      if (sequential) superseded.add(earlier.visit.id);
+    }
+  }
+
+  if (!timed) {
+    const activeCount = ranges.filter((range) => range.status === 'active').length;
+    if (activeCount <= 1) {
+      visits.slice(0, -1).forEach((visit) => superseded.add(visit.id));
+    } else {
+      pushDiagnostic(diagnostics, {
+        code: 'ambiguous-visit-order',
+        level: 'warning',
+        message: '多个 Visit 缺少可比较时间，未将历史 active 解释为先后重办。',
+        fieldPath: 'activities.startTime',
+        elementId,
+      });
+    }
+  }
+
+  return visits.map((visit) => {
+    const isSuperseded = superseded.has(visit.id);
+    return { ...visit, effective: !isSuperseded, superseded: isSuperseded };
+  });
+}
+
+function visitOrderKey(visit) {
+  let instant = null;
+  visit.records.forEach((record) => {
+    const start = runtimeInstant(record.startTime);
+    const end = runtimeInstant(record.endTime);
+    const candidate = start ?? end;
+    if (candidate == null) return;
+    instant = instant == null ? candidate : Math.min(instant, candidate);
+  });
+  return { instant, index: visit.index || 0 };
+}
+
+function visitRange(visit) {
+  let start = null;
+  let end = null;
+  let open = false;
+  for (const record of visit.records) {
+    const started = parseRuntimeInstant(record.startTime).instant;
+    const ended = parseRuntimeInstant(record.endTime).instant;
+    if (started != null) start = start == null ? started : Math.min(start, started);
+    if (ended != null) end = end == null ? ended : Math.max(end, ended);
+    if (record.status === 'active' && ended == null) open = true;
+  }
+  const status = resolveVisitStatus(visit.records);
+  if (status === 'active') open = true;
+  return { start, end, open, status };
+}
+
+function isOverlappingOpen(earlier, later) {
+  if (!earlier.open) return false;
+  if (later.start == null) return earlier.open && later.open;
+  if (earlier.end == null) return true;
+  return later.start < earlier.end;
+}
+
+function isSequentialReplacement(earlier, later, inbound) {
+  if (!TERMINAL.has(earlier.status) && !earlier.open) return false;
+  if (earlier.open && !TERMINAL.has(earlier.status)) return false;
+  if (earlier.end != null && later.start != null && later.start >= earlier.end) return true;
+  if (TERMINAL.has(earlier.status) && !earlier.open && later.start != null && earlier.start != null && later.start > earlier.start) return true;
+  const laterInstant = later.start ?? later.end;
+  return inbound.some((transition) => {
+    const at = runtimeInstant(transition.occurredAt || transition.time);
+    if (at == null || laterInstant == null) return inbound.length > 0 && TERMINAL.has(earlier.status);
+    const afterEarlier = earlier.end == null || at >= earlier.end || (earlier.start != null && at >= earlier.start);
+    return afterEarlier && at <= laterInstant;
+  });
+}

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

@@ -248,7 +248,7 @@ export class BpmnViewer {
   setModel(model: ProcessModel): void
   setRuntime(runtime: ProcessInstanceSnapshot | null): void
   refreshPresentation(): void
-  setDisplayOptions(options: { timeline?: ViewerTimelineOptions; runtimeDetails?: RuntimeDetailsOptions; runtimeTraceOptions?: RuntimeTraceProjectionOptions; runtimeAssetResolver?: RuntimeAssetResolver | null }): void
+  setDisplayOptions(options: { timeline?: ViewerTimelineOptions; runtimeDetails?: RuntimeDetailsOptions; runtimeTraceOptions?: RuntimeTraceProjectionOptions; runtimeAssetResolver?: RuntimeAssetResolver | null; replace?: boolean }): void
   setProjection(projection: ViewerProjection): void
   setTheme(theme: NovaThemeInput): NovaThemeState
   setThemeMode(mode: NovaThemeMode): NovaThemeState

package/dist/modules/viewer/index.js

@@ -1,7 +1,7 @@
 import { cloneModel, createEdge, getScopeGraph, NODE_DEFINITIONS } from '../core/index.js';
 import { createDefaultIconRegistry, createIconElement } from '../icons/index.js';
 import { DiagramRenderer } from '../renderer-svg/index.js';
-import { createRuntimePresentation, normalizeRuntime } from '../runtime/index.js';
+import { compareRuntimeOrder, createRuntimePresentation, formatRuntimeInstant, normalizeRuntime, parseRuntimeInstant } from '../runtime/index.js';
 import { createRuntimeTraceProjection } from './runtime-trace.js';
 import { renderDefaultRuntimeTimeline, RuntimeTimelineHost } from './timeline.js';
 import { renderRuntimeApprovalContent } from './runtime-content.js';
@@ -51,7 +51,7 @@ function renderRuntimeAction({ container, viewer, action, resolveAsset, compact
     element('em', '', appearance.label),
   );
   header.appendChild(heading);
-  if (action.occurredAt) header.appendChild(element('time', '', action.occurredAt));
+  if (action.occurredAt) header.appendChild(element('time', '', formatRuntimeInstant(action.occurredAt)));
   article.appendChild(header);
   if (action.targets?.length) article.appendChild(element('div', 'mb-runtime-action-targets', `目标：${action.targets.map((target) => target.name).join('、')}`));
   if (action.targetElementId && !action.targets?.length) article.appendChild(element('div', 'mb-runtime-action-targets', `目标节点：${action.targetElementId}`));
@@ -104,7 +104,7 @@ export function renderDefaultRuntimeDetails({ container, viewer, node, presentat
     applyRuntimeTone(recordStatus, viewer?.runtimeAppearance?.resolveStatus(record.status));
     title.append(element('strong', '', record.participant?.name || record.assignee || '待分配审批人'), recordStatus);
     copy.appendChild(title);
-    const time = [record.startTime, record.endTime].filter(Boolean).join(' — ');
+    const time = [record.startTime, record.endTime].map((value) => formatRuntimeInstant(value)).filter(Boolean).join(' — ');
     if (time) copy.appendChild(element('time', '', time));
     row.append(avatar, copy);
     body.appendChild(row);
@@ -113,7 +113,10 @@ export function renderDefaultRuntimeDetails({ container, viewer, node, presentat
   const renderedActionIds = new Set();
   if (!visits.length) body.appendChild(element('div', 'mb-runtime-details-empty', presentation.summary || presentation.statusLabel));
   visits.forEach((visit) => {
-    if (presentation.visits.length > 1) body.appendChild(element('div', 'mb-runtime-details-round', `第 ${visit.round} 次处理`));
+    if (presentation.visits.length > 1) {
+      const historical = visit.effective === false || visit.superseded;
+      body.appendChild(element('div', 'mb-runtime-details-round', historical ? `第 ${visit.round} 次处理 · 历史` : `第 ${visit.round} 次处理`));
+    }
     [...visit.records].reverse().forEach(appendRecord);
     [...visit.actions].reverse().forEach((action) => {
       renderRuntimeAction({ container: body, viewer, action, resolveAsset });
@@ -130,7 +133,7 @@ export function renderDefaultRuntimeDetails({ container, viewer, node, presentat
     const block = element('article', `mb-runtime-details-transition type-${transition.type}`);
     applyRuntimeTone(block, viewer?.runtimeAppearance?.resolveTransition(transition).tone);
     block.appendChild(element('strong', '', transition.type === 'reject' ? `驳回至 ${transition.targetName || transition.targetElementId}` : `退回至 ${transition.targetName || transition.targetElementId}`));
-    const meta = [transition.operator, transition.occurredAt || transition.time].filter(Boolean).join(' · ');
+    const meta = [transition.operator, formatRuntimeInstant(transition.occurredAt || transition.time)].filter(Boolean).join(' · ');
     if (meta) block.appendChild(element('span', '', meta));
     if (transition.action && !renderedActionIds.has(transition.action.id)) {
       renderRuntimeApprovalContent({
@@ -189,7 +192,7 @@ export function renderDefaultRuntimeTransitionDetails({
     actorStatus,
   );
   actorCopy.appendChild(actorTitle);
-  const time = transition.action?.occurredAt || transition.occurredAt || transition.time;
+  const time = formatRuntimeInstant(transition.action?.occurredAt || transition.occurredAt || transition.time);
   if (time) actorCopy.appendChild(element('time', '', time));
   actor.append(avatar, actorCopy);
   body.appendChild(actor);
@@ -312,7 +315,10 @@ function projectRuntime(runtime, projectedModel) {
       .map((id) => normalized.edgeVisits?.filter((visit) => visit.edgeId === id).at(-1))
       .filter(Boolean);
     if (visits.length === edge.sourceEdgeIds.length) {
-      const latest = visits.sort((a, b) => String(a.occurredAt || a.time || '').localeCompare(String(b.occurredAt || b.time || ''))).at(-1);
+      const latest = visits
+        .map((visit, index) => ({ visit, index, instant: parseRuntimeInstant(visit.occurredAt || visit.time).instant }))
+        .sort((left, right) => compareRuntimeOrder(left, right))
+        .at(-1)?.visit;
       projectedEdgeVisits.push({ ...latest, id: `ProjectedVisit_${edge.id}`, edgeId: edge.id });
     }
   }
@@ -394,6 +400,12 @@ export class BpmnViewer {
     this.projectedRuntime = null;
     this.runtimePresentation = null;
     this.selection = null;
+    this._sidebarTransitionActive = false;
+    this._sidebarViewport = null;
+    this._lastViewport = null;
+    this._timelineScroll = 0;
+    this._silentViewport = false;
+    this._pendingFit = false;
     this._detailsCleanup = null;
     this._detailsMotion = null;
     this._detailsRoot = null;
@@ -425,9 +437,11 @@ export class BpmnViewer {
     }
     this._resizeObserver = typeof ResizeObserver === 'function'
       ? new ResizeObserver(() => {
-        if (this.projection !== 'auto') return;
-        const next = this._resolveProjection();
-        if (next !== this.activeProjection) this.refresh();
+        this._refreshAutoProjection();
+        if (this._pendingFit && this._containerHasSize()) {
+          this._pendingFit = false;
+          this.renderer?.fitView?.();
+        }
       })
       : null;
     this._resizeObserver?.observe(options.container);
@@ -436,10 +450,33 @@ export class BpmnViewer {
   _resolveProjection() {
     if (this.projection !== 'auto') return this.projection;
     if (!this.runtime) return 'standard';
+    if (this._sidebarTransitionActive) return this.activeProjection;
     const width = this.container.clientWidth || this.container.getBoundingClientRect?.().width || 0;
     return width > 0 && width < 720 ? 'compact' : 'approval';
   }
 
+  // The Shell owns the transition. Do not replace the renderer at intermediate widths.
+  _setSidebarTransitionActive(active) {
+    if (this._sidebarTransitionActive === Boolean(active)) return;
+    this._sidebarTransitionActive = Boolean(active);
+    if (active) {
+      if (this.activeProjection !== 'compact') this._sidebarViewport = this.renderer?.getViewportState?.() || this._sidebarViewport;
+    } else this._refreshAutoProjection();
+  }
+
+  _refreshAutoProjection() {
+    if (this._sidebarTransitionActive || this.projection !== 'auto') return;
+    const next = this._resolveProjection();
+    if (next === this.activeProjection) return;
+    if (this.activeProjection !== 'compact') this._sidebarViewport = this.renderer?.getViewportState?.() || this._sidebarViewport;
+    this.refresh({ preserveViewport: this.activeProjection !== 'compact' });
+    if (this.activeProjection !== 'compact' && this._sidebarViewport) {
+      this._silentViewport = true;
+      try { this.renderer?.setViewportState?.(this._sidebarViewport); }
+      finally { this._silentViewport = false; }
+    }
+  }
+
   _rebuildProjection() {
     const previousProjection = this.activeProjection;
     this.activeProjection = this._resolveProjection();
@@ -494,33 +531,59 @@ export class BpmnViewer {
     return [];
   }
 
-  _emitTraceClick(payload) {
-    let element = payload.element || null;
-    if (element && payload.targetType === 'edge') {
-      const sourceIds = element.sourceEdgeIds?.length ? element.sourceEdgeIds : [element.id];
+  _resolveTraceClick(payload) {
+    if (!payload) return null;
+    const targetType = payload.targetType;
+    const transitionId = payload.transition?.id || payload.traceItem?.transitionId;
+    const transition = targetType === 'transition' && transitionId
+      ? this.runtimePresentation.getTransition(transitionId)
+      : null;
+    if (targetType === 'transition' && !transition) return null;
+    const elementId = transition?.sourceElementId || payload.elementId || payload.element?.id || payload.traceItem?.elementId;
+    let selectedElement;
+    if (targetType === 'edge') {
+      const current = this.projectedModel.edges.find((edge) => edge.id === elementId)
+        || this.model.edges.find((edge) => edge.id === elementId);
+      if (!current) return null;
+      const sourceIds = current.sourceEdgeIds?.length ? current.sourceEdgeIds : [current.id];
       const sourceEdges = sourceIds.map((id) => this.model.edges.find((edge) => edge.id === id)).filter(Boolean);
-      element = sourceEdges.find((edge) => element.name && edge.name === element.name) || sourceEdges[0] || element;
-    } else if (element?.id && payload.targetType !== 'edge') {
-      element = this.model.nodes.find((node) => node.id === element.id) || element;
-    }
-    const presentation = payload.presentation || (element?.id && payload.targetType !== 'edge'
-      ? this.runtimePresentation.getNode(element.id)
-      : null);
-    this.onTraceClick({
-      targetType: payload.targetType,
-      elementId: payload.elementId || element?.id,
-      element,
-      visitId: payload.visitId ?? payload.traceItem?.visitId ?? null,
-      traceItem: payload.traceItem || null,
-      transition: payload.transition || null,
+      selectedElement = sourceEdges.find((edge) => current.name && edge.name === current.name) || sourceEdges[0] || current;
+    } else selectedElement = this.model.nodes.find((node) => node.id === elementId) || null;
+    if (!selectedElement && !transition) return null;
+    const presentation = selectedElement?.id && targetType !== 'edge'
+      ? this.runtimePresentation.getNode(selectedElement.id)
+      : null;
+    const visitId = payload.visitId ?? payload.traceItem?.visitId ?? null;
+    const traceItems = this.traceProjection?.items || [];
+    const traceItem = traceItems.find((item) => payload.traceItem?.id && item.id === payload.traceItem.id)
+      || (targetType === 'transition' ? traceItems.find((item) => item.transitionId === transitionId) : null)
+      || (visitId ? traceItems.find((item) => item.elementId === elementId && item.visitId === visitId) : null)
+      || null;
+    const visit = visitId ? presentation?.visits?.find((item) => item.id === visitId) : null;
+    if (targetType === 'visit' && visitId && !traceItem && !visit) return null;
+    const records = traceItem?.records || visit?.records;
+    return {
+      targetType,
+      elementId: selectedElement?.id || elementId,
+      element: selectedElement,
+      visitId,
+      traceItem,
+      transition,
       presentation,
-      activityInstances: this._activityInstancesFor({ traceItem: payload.traceItem, presentation }),
-      actions: payload.traceItem?.actions || (payload.transition?.action ? [payload.transition.action] : presentation?.actions) || [],
+      activityInstances: records ? [...records] : this._activityInstancesFor({ presentation }),
+      actions: traceItem?.actions || visit?.actions || (transition?.action ? [transition.action] : presentation?.actions) || [],
       runtime: this.runtime,
       projection: this.activeProjection,
       originalEvent: payload.originalEvent,
       viewer: this,
-    });
+    };
+  }
+
+  _emitTraceClick(payload) {
+    const resolved = this._resolveTraceClick(payload);
+    if (!resolved) return;
+    this.options._onPanelSelection?.(resolved);
+    this.onTraceClick(resolved);
   }
 
   _mountRenderer() {
@@ -554,7 +617,7 @@ export class BpmnViewer {
         onDetailsRequest: (item, anchor, event) => {
           const node = this.model.nodes.find((candidate) => candidate.id === item.elementId);
           if (!node) return;
-          this._select('node', node, event, { emitTrace: false });
+          this._select('node', node, event, { emitTrace: false, traceItem: item });
           const presentation = this.runtimePresentation.getNode(node.id);
           if (presentation.hasDetails && this.runtimeDetailsOptions.autoOpen) {
             this._openRuntimeDetails(node, presentation, anchor, {
@@ -564,6 +627,7 @@ export class BpmnViewer {
         },
         onTransitionRequest: (item, anchor, event) => {
           const transition = this.runtimePresentation.getTransition(item.transitionId);
+          this.options._onPanelSelection?.(this._resolveTraceClick({ targetType: 'transition', transition, traceItem: item, originalEvent: event }));
           if (this.runtimeDetailsOptions.autoOpen) {
             this._openRuntimeTransitionDetails(transition, anchor, {
               restoreFocusVisible: event ? event.detail === 0 : Boolean(anchor?.matches?.(':focus-visible')),
@@ -598,21 +662,27 @@ export class BpmnViewer {
         this._emitTraceClick({ targetType: 'transition', element, transition, originalEvent: event });
         if (this.runtimeDetailsOptions.autoOpen) this.openRuntimeTransitionDetails(transition, event.currentTarget);
       },
-      onViewportChange: (viewport) => { this._disposeRuntimeDetails(); this.onViewportChange(viewport); },
+      onViewportChange: (viewport) => {
+        if (viewport) this._lastViewport = { zoom: viewport.zoom, pan: { ...viewport.pan } };
+        if (!this._silentViewport) this._disposeRuntimeDetails();
+        this.onViewportChange(viewport);
+      },
     });
   }
 
-  _select(kind, element, originalEvent = undefined, { emitTrace = true } = {}) {
+  _select(kind, element, originalEvent = undefined, { emitTrace = true, traceItem = null } = {}) {
     this.selection = { kind, id: element.id };
     this.renderer.setSelection(this.selection);
     const presentation = kind === 'node' ? this.runtimePresentation.getNode(element.id) : null;
     this.onElementClick({ kind, element, runtime: this.runtime, presentation });
     if (emitTrace) this._emitTraceClick({ targetType: kind, element, presentation, originalEvent });
+    else this.options._onPanelSelection?.(this._resolveTraceClick({ targetType: traceItem ? 'visit' : kind, element, presentation, traceItem, originalEvent }));
   }
 
   clearSelection() {
     this.selection = null;
     this.renderer.setSelection(null);
+    this.options._onPanelSelection?.(null);
     this.onElementClick(null);
   }
 
@@ -918,46 +988,144 @@ export class BpmnViewer {
     });
   }
 
-  refresh() {
+  _rendererKind() {
+    if (!this.renderer) return null;
+    return this.renderer instanceof RuntimeTimelineHost ? 'timeline' : 'diagram';
+  }
+
+  _containerHasSize() {
+    if (typeof document !== 'undefined' && document.hidden) return false;
+    const width = this.container.clientWidth || this.container.getBoundingClientRect?.().width || 0;
+    const height = this.container.clientHeight || this.container.getBoundingClientRect?.().height || 0;
+    return width >= 1 && height >= 1;
+  }
+
+  _capturePresentationState() {
+    const kind = this._rendererKind();
+    if (kind === 'diagram') {
+      const viewport = this.renderer?.getViewportState?.();
+      if (viewport) this._lastViewport = viewport;
+    } else if (kind === 'timeline') {
+      this._timelineScroll = this.container.scrollTop || this._timelineScroll || 0;
+    }
+    return {
+      kind,
+      details: this._detailsTarget ? { ...this._detailsTarget, anchor: this._detailsAnchor } : null,
+    };
+  }
+
+  _syncDiagramRenderer() {
+    this.renderer.options.visualModel = this.model;
+    this.renderer.options.runtimePresenter = () => this.runtimePresentation;
+    this.renderer.options.runtimeAppearance = this.runtimeAppearance;
+    this.renderer.mode = this.mode;
+    this.renderer.model = this.projectedModel;
+    this.renderer.runtime = this.projectedRuntime;
+    this.renderer.render();
+  }
+
+  _syncTimelineRenderer() {
+    Object.assign(this.renderer.options, {
+      model: this.projectedModel,
+      runtime: this.projectedRuntime,
+      presentation: this.runtimePresentation,
+      projection: this.traceProjection,
+      ...this._resolveTimelineOptions(),
+      appearance: this.runtimeAppearance,
+      themeState: this.themeController.getState(),
+    });
+    this.renderer.render();
+  }
+
+  _pruneSelection() {
+    if (!this.selection) return;
+    const collection = this.selection.kind === 'edge' ? this.projectedModel?.edges : this.projectedModel?.nodes;
+    if (!collection?.some((item) => item.id === this.selection.id)) this.selection = null;
+  }
+
+  _restoreRuntimeDetails(target) {
+    if (!target) return;
+    if (target.kind === 'node') {
+      const node = this.model.nodes.find((item) => item.id === target.id);
+      const presentation = node ? this.runtimePresentation.getNode(node.id) : null;
+      if (node && presentation?.hasDetails) this.openRuntimeDetails(node, presentation, target.anchor || null);
+      return;
+    }
+    if (target.kind === 'transition') {
+      const transition = this.runtimePresentation.getTransition(target.id);
+      if (transition) this._openRuntimeTransitionDetails(transition, target.anchor || null);
+    }
+  }
+
+  refresh(options = {}) {
+    const preserveViewport = options.preserveViewport === true;
+    const previous = this._capturePresentationState();
     this._disposeRuntimeDetails();
     this._rebuildProjection();
-    this._mountRenderer();
+    const kind = this.runtime && this.activeProjection === 'compact' && this.traceProjection ? 'timeline' : 'diagram';
+    const sameKind = previous.kind === kind && this.renderer;
+    if (sameKind && kind === 'diagram') this._syncDiagramRenderer();
+    else if (sameKind && kind === 'timeline') this._syncTimelineRenderer();
+    else this._mountRenderer();
+    this._pruneSelection();
     if (this.selection) this.renderer.setSelection?.(this.selection);
+    else this.renderer.setSelection?.(null);
+    this.options._onPanelSelection?.();
+    this._silentViewport = true;
+    try {
+      if (kind === 'diagram' && preserveViewport && this._lastViewport) this.renderer.setViewportState?.(this._lastViewport);
+      if (kind === 'timeline' && preserveViewport) this.container.scrollTop = this._timelineScroll || 0;
+    } finally {
+      this._silentViewport = false;
+    }
+    this._restoreRuntimeDetails(previous.details);
   }
 
-  setModel(model) { this.model = model; this._svgExportAssetCache.clear(); this.refresh(); }
+  setModel(model) {
+    const same = this.model === model || Boolean(this.model?.id && model?.id && this.model.id === model.id);
+    this.model = model;
+    this._svgExportAssetCache.clear();
+    this.refresh({ preserveViewport: same });
+  }
   setRuntime(runtime) {
-    this.runtime = runtime ? normalizeRuntime(runtime) : null;
+    const next = runtime ? normalizeRuntime(runtime) : null;
+    const sameInstance = Boolean(this.runtime) && Boolean(next) && (this.runtime.processInstanceId || '') === (next.processInstanceId || '');
+    this.runtime = next;
     this.mode = this.options.mode === 'instance' || this.runtime ? 'instance' : 'viewer';
     this._svgExportAssetCache.clear();
-    this.refresh();
+    this.refresh({ preserveViewport: sameInstance });
   }
   setProjection(projection) {
     if (!['auto', 'standard', 'approval', 'compact'].includes(projection)) return;
     this.projection = projection;
-    this.refresh();
-    requestAnimationFrame(() => this.renderer.fitView());
+    this.refresh({ preserveViewport: false });
+    requestAnimationFrame(() => {
+      if (this._containerHasSize()) this.renderer?.fitView?.();
+      else this._pendingFit = true;
+    });
   }
-  setDisplayOptions({ timeline, runtimeDetails, runtimeTraceOptions, runtimeAssetResolver } = {}) {
+  setDisplayOptions({ timeline, runtimeDetails, runtimeTraceOptions, runtimeAssetResolver, replace = false } = {}) {
     let changed = false;
     if (runtimeAssetResolver !== undefined) {
       this.runtimeAssetResolver = runtimeAssetResolver || null;
       this._svgExportAssetCache.clear();
       changed = true;
     }
-    if (runtimeTraceOptions !== undefined) {
-      this.runtimeTraceOptions = { ...this.runtimeTraceOptions, ...(runtimeTraceOptions || {}) };
+    if (replace || runtimeTraceOptions !== undefined) {
+      this.runtimeTraceOptions = replace
+        ? { ...(runtimeTraceOptions || {}) }
+        : { ...this.runtimeTraceOptions, ...(runtimeTraceOptions || {}) };
       changed = true;
     }
-    if (timeline !== undefined) {
-      this.timelineOptions = mergeTimelineOptions(this.timelineOptions, timeline || {});
+    if (replace || timeline !== undefined) {
+      this.timelineOptions = mergeTimelineOptions(replace ? {} : this.timelineOptions, timeline || {});
       changed = true;
     }
-    if (runtimeDetails !== undefined) {
-      this.runtimeDetailsOptions = mergeRuntimeDetailsOptions(this.runtimeDetailsOptions, runtimeDetails || {});
+    if (replace || runtimeDetails !== undefined) {
+      this.runtimeDetailsOptions = mergeRuntimeDetailsOptions(replace ? {} : this.runtimeDetailsOptions, runtimeDetails || {});
       changed = true;
     }
-    if (changed) this.refresh();
+    if (changed) this.refresh({ preserveViewport: true });
   }
   setTheme(theme) { return this.themeController.setTheme(theme); }
   setThemeMode(mode) { return this.themeController.setMode(mode); }
@@ -965,7 +1133,7 @@ export class BpmnViewer {
   setRuntimeAppearance(runtimeAppearance) {
     this.runtimeAppearanceOptions = runtimeAppearance || {};
     this.runtimeAppearance = createRuntimeAppearance(this.runtimeAppearanceOptions);
-    this.refresh();
+    this.refresh({ preserveViewport: true });
   }
   refreshPresentation() {
     if (this.mode !== 'viewer' || (this.runtime && this.activeProjection === 'compact')) return;
@@ -1013,6 +1181,8 @@ export class BpmnViewer {
   fitView() { this.renderer.fitView(); }
   zoomBy(delta) { this.renderer.zoomBy(delta); }
   destroy() {
+    this._sidebarTransitionActive = false;
+    this._sidebarViewport = null;
     this._svgExportPreview?.close?.({ immediate: true });
     this._svgExportPreview = null;
     this._svgExportAssetCache.clear();