@fses/workbench-app 0.2.0 → 0.2.1

package/node_modules/@fses/workbench-card/src/renderers/chart/useEchart.ts

@@ -0,0 +1,1820 @@
+import { nextTick, onBeforeUnmount, shallowRef, watch, type Ref } from 'vue';
+import * as echarts from 'echarts';
+import type { ECharts, EChartsOption } from 'echarts';
+import { buildDynamicEchartOption, normalizeDynamicEchartFieldMapping } from './dynamicEchartOption';
+import { buildCartesianResponsiveLayout, buildPieResponsiveLayout } from './chartResponsiveLayout';
+import {
+  bindWorkbenchEChartsRuntimeInteractions,
+  isWorkbenchHalfDonutPlaceholderData,
+  normalizeWorkbenchChartDisplayDefaults as normalizeSharedWorkbenchChartDisplayDefaults,
+  prepareWorkbenchEChartsRuntimeOption,
+} from './echartsRuntimeInteractions';
+import type {
+  BoxplotSeriesData,
+  CandlestickSeriesData,
+  DisplayBlockData,
+  EchartsScriptData,
+  FunnelStagesData,
+  GanttTasksData,
+  GaugeMetricData,
+  GeoGlobeData,
+  HeatmapMatrixData,
+  MapRegionsData,
+  MultiSeriesData,
+  NetworkGraphData,
+  ParetoSeriesData,
+  PieSlicesData,
+  RadarMetricsData,
+  SankeyFlowData,
+  ScatterPointsData,
+  TreeHierarchyData,
+  TreeNodeData,
+  WaterfallStepsData,
+} from '@fses/workbench-card/types';
+import { normalizeChartRendererKey } from './chartRendererRegistry';
+import {
+  applyWorkbenchChartThemeToOption,
+  readWorkbenchChartThemeTokens,
+  resolveWorkbenchChartThemeRoot,
+} from './workbenchChartTheme';
+export { normalizeChartRendererKey } from './chartRendererRegistry';
+
+const CHART_COLORS = ['#1f4fd4', '#17a34a', '#d97706', '#9333ea', '#0f766e', '#dc2626', '#0891b2'];
+const DEFAULT_ECHARTS_ROOT_PATH = '/echarts-examples';
+const OFFICIAL_ECHARTS_ROOT_PATH = 'https://echarts.apache.org/examples';
+const GL_REQUIREMENTS = new Set(['echarts-gl']);
+const GL_SERIES_TYPES = new Set(['graphGL', 'bar3D', 'scatter3D', 'line3D', 'lines3D', 'map3D', 'surface']);
+const GL_SCRIPT_PATTERN = /\b(globe|graphGL|bar3D|scatter3D|line3D|lines3D|map3D|surface)\b/;
+const WORKBENCH_METRIC_ROW_CONTEXT_KEY = '__workbenchMetricRowContext';
+const WORKBENCH_BAR_MIN_HEIGHT = 2;
+const WORKBENCH_DONUT_HOVER_LABEL_MAX_FONT_SIZE = 16;
+const WORKBENCH_DONUT_HOVER_GRAPHIC_ID = '__workbench_donut_hover_label__';
+const echartsMapLoadPromises = new Map<string, Promise<void>>();
+
+type JQueryCompatRequest<T = unknown> = Promise<T | undefined> & {
+  done(callback: (data: T) => void): JQueryCompatRequest<T>;
+  fail(callback: (error: unknown) => void): JQueryCompatRequest<T>;
+};
+
+type JQueryCompat = {
+  get(url: string, callback?: (data: unknown) => void): JQueryCompatRequest;
+  getJSON(url: string, callback?: (data: unknown) => void): JQueryCompatRequest;
+};
+
+type EchartsScriptApp = Record<string, unknown> & {
+  config?: Record<string, unknown>;
+  configParameters?: Record<string, unknown>;
+};
+
+type EchartsScriptScope = {
+  option?: EChartsOption;
+  echarts: typeof echarts;
+  myChart: ECharts;
+  $: JQueryCompat;
+  app: EchartsScriptApp;
+  ROOT_PATH: string;
+  window: Window;
+  document: Document;
+  fetch: typeof window.fetch;
+  Math: Math;
+  Date: DateConstructor;
+  Array: ArrayConstructor;
+  Object: ObjectConstructor;
+  Number: NumberConstructor;
+  String: StringConstructor;
+  Boolean: BooleanConstructor;
+  JSON: JSON;
+  console: Console;
+  setTimeout: typeof window.setTimeout;
+  clearTimeout: typeof window.clearTimeout;
+  setInterval: typeof window.setInterval;
+  clearInterval: typeof window.clearInterval;
+};
+
+let echartsGlLoadPromise: Promise<void> | null = null;
+const donutHoverCenterBindings = new WeakMap<ECharts, { option: EChartsOption }>();
+
+const regionMap = {
+  type: 'FeatureCollection',
+  features: [
+    { type: 'Feature', properties: { name: '东北' }, geometry: { type: 'Polygon', coordinates: [[[118, 42], [134, 42], [134, 53], [118, 53], [118, 42]]] } },
+    { type: 'Feature', properties: { name: '华北' }, geometry: { type: 'Polygon', coordinates: [[[108, 36], [122, 36], [122, 44], [108, 44], [108, 36]]] } },
+    { type: 'Feature', properties: { name: '华东' }, geometry: { type: 'Polygon', coordinates: [[[116, 28], [124, 28], [124, 36], [116, 36], [116, 28]]] } },
+    { type: 'Feature', properties: { name: '华中' }, geometry: { type: 'Polygon', coordinates: [[[108, 28], [116, 28], [116, 36], [108, 36], [108, 28]]] } },
+    { type: 'Feature', properties: { name: '华南' }, geometry: { type: 'Polygon', coordinates: [[[108, 20], [122, 20], [122, 28], [108, 28], [108, 20]]] } },
+    { type: 'Feature', properties: { name: '西部' }, geometry: { type: 'Polygon', coordinates: [[[78, 28], [108, 28], [108, 48], [78, 48], [78, 28]]] } },
+    { type: 'Feature', properties: { name: '海外' }, geometry: { type: 'Polygon', coordinates: [[[124, 18], [136, 18], [136, 26], [124, 26], [124, 18]]] } },
+  ],
+};
+
+let mapRegistered = false;
+
+function ensureMapRegistered() {
+  if (mapRegistered && echarts.getMap('workbench-regions')) return;
+  echarts.registerMap('workbench-regions', regionMap as never);
+  mapRegistered = true;
+}
+
+function assertRecord(value: unknown, shape: string): asserts value is Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`图表数据不是对象：${shape}`);
+}
+
+function assertArray(value: unknown, name: string): asserts value is unknown[] {
+  if (!Array.isArray(value)) throw new Error(`图表字段缺失或格式错误：${name}`);
+}
+
+function objectValue(value: unknown, key: string) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)[key]
+    : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function cloneOptionValue<T>(value: T): T {
+  if (Array.isArray(value)) return value.map((item) => cloneOptionValue(item)) as T;
+  if (isRecord(value)) {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, cloneOptionValue(item)])) as T;
+  }
+  return value;
+}
+
+function optionSeriesItems(option: EChartsOption): Record<string, unknown>[] {
+  const series = objectValue(option, 'series');
+  const items = Array.isArray(series) ? series : [series];
+  return items.filter(isRecord);
+}
+
+/**
+ * Caps a numeric option while preserving missing values with a readable default.
+ * @param value - Candidate option value.
+ * @param fallback - Default value used when the option is missing.
+ * @param max - Maximum allowed number.
+ * @returns Capped numeric value or the original non-number value.
+ */
+function cappedRuntimeNumber(value: unknown, fallback: number, max: number): unknown {
+  if (typeof value === 'number' && Number.isFinite(value)) return Math.min(value, max);
+  return value === undefined ? fallback : value;
+}
+
+/**
+ * Checks whether a color is explicitly transparent.
+ * @param value - Candidate color option.
+ * @returns True when the color should not receive visible bar fallbacks.
+ */
+function isTransparentRuntimeColor(value: unknown): boolean {
+  if (typeof value !== 'string') return false;
+  const normalized = value.replace(/\s+/g, '').toLowerCase();
+  return normalized === 'transparent' || normalized === 'rgba(0,0,0,0)' || /rgba\([^,]+,[^,]+,[^,]+,0\)/.test(normalized);
+}
+
+/**
+ * Checks whether a bar series is only used as an invisible layout helper.
+ * @param series - ECharts series option.
+ * @returns True for transparent helper bars such as waterfall offsets.
+ */
+function isTransparentRuntimeBarSeries(series: Record<string, unknown>): boolean {
+  const itemStyle = objectValue(series, 'itemStyle');
+  return isTransparentRuntimeColor(objectValue(series, 'color'))
+    || isTransparentRuntimeColor(objectValue(itemStyle, 'color'));
+}
+
+/**
+ * Checks whether a pie radius value represents a visible inner hole.
+ * @param value - Inner radius option from ECharts pie series.
+ * @returns True when the inner radius is greater than zero.
+ */
+function hasRuntimeInnerRadius(value: unknown): boolean {
+  if (typeof value === 'number') return value > 0;
+  if (typeof value !== 'string') return false;
+  const normalized = value.trim();
+  if (!normalized || normalized === '0' || normalized === '0%') return false;
+  const numeric = Number.parseFloat(normalized);
+  return Number.isFinite(numeric) && numeric > 0;
+}
+
+/**
+ * Checks whether a pie series is rendered as a donut with a center area.
+ * @param series - ECharts series option.
+ * @returns True for donut/ring pie series.
+ */
+function isRuntimeDonutSeries(series: Record<string, unknown>): boolean {
+  if (series.type !== 'pie') return false;
+  const radius = series.radius;
+  return Array.isArray(radius) && hasRuntimeInnerRadius(radius[0]);
+}
+
+/**
+ * Keeps donut hover labels centered in the ring instead of floating around slices.
+ * @param series - ECharts series option.
+ * @returns Donut series with centered, bounded emphasis label typography.
+ */
+function withReadablePieHoverLabel(series: Record<string, unknown>): Record<string, unknown> {
+  if (!isRuntimeDonutSeries(series)) return series;
+  const seriesLabel = objectValue(series, 'label');
+  const seriesLabelLine = objectValue(series, 'labelLine');
+  const emphasis = objectValue(series, 'emphasis');
+  const emphasisRecord = isRecord(emphasis) ? emphasis : {};
+  const label = objectValue(emphasisRecord, 'label');
+  const labelRecord = isRecord(label) ? label : {};
+  const {
+    width: _seriesLabelWidth,
+    overflow: _seriesLabelOverflow,
+    ellipsis: _seriesLabelEllipsis,
+    distance: _seriesLabelDistance,
+    distanceToLabelLine: _seriesLabelDistanceToLabelLine,
+    alignTo: _seriesLabelAlignTo,
+    edgeDistance: _seriesLabelEdgeDistance,
+    bleedMargin: _seriesLabelBleedMargin,
+    ...centerSeriesLabel
+  } = isRecord(seriesLabel) ? seriesLabel : {};
+  const {
+    width: _labelWidth,
+    overflow: _labelOverflow,
+    ellipsis: _labelEllipsis,
+    distance: _labelDistance,
+    distanceToLabelLine: _labelDistanceToLabelLine,
+    alignTo: _labelAlignTo,
+    edgeDistance: _labelEdgeDistance,
+    bleedMargin: _labelBleedMargin,
+    ...centerLabel
+  } = labelRecord;
+  return {
+    ...series,
+    label: {
+      ...centerSeriesLabel,
+      show: false,
+      position: 'center',
+      align: 'center',
+      verticalAlign: 'middle',
+      distance: 0,
+      offset: [0, 0],
+      rotate: 0,
+    },
+    labelLine: {
+      ...(isRecord(seriesLabelLine) ? seriesLabelLine : {}),
+      show: false,
+    },
+    labelLayout: {
+      hideOverlap: false,
+    },
+    emphasis: {
+      ...emphasisRecord,
+      label: {
+        ...centerLabel,
+        show: false,
+        position: 'center',
+        align: 'center',
+        verticalAlign: 'middle',
+        distance: 0,
+        offset: [0, 0],
+        rotate: 0,
+        fontSize: cappedRuntimeNumber(centerLabel.fontSize, 14, WORKBENCH_DONUT_HOVER_LABEL_MAX_FONT_SIZE),
+        fontWeight: centerLabel.fontWeight ?? 600,
+        lineHeight: cappedRuntimeNumber(centerLabel.lineHeight, 20, 22),
+      },
+    },
+  };
+}
+
+/**
+ * Gives non-zero bar values a visible footprint in compressed comparison charts.
+ * @param series - ECharts series option.
+ * @returns Bar series with a minimum visible height when appropriate.
+ */
+function withVisibleBarMinimum(series: Record<string, unknown>): Record<string, unknown> {
+  const coordinateSystem = typeof series.coordinateSystem === 'string' ? series.coordinateSystem : '';
+  if (
+    series.type !== 'bar'
+    || (coordinateSystem && coordinateSystem !== 'cartesian2d')
+    || series.barMinHeight !== undefined
+    || isTransparentRuntimeBarSeries(series)
+  ) return series;
+  return {
+    ...series,
+    barMinHeight: WORKBENCH_BAR_MIN_HEIGHT,
+  };
+}
+
+/**
+ * Applies workbench-card display defaults to all ECharts options before rendering.
+ * @param option - ECharts option from generated, materialized, or script renderers.
+ * @returns Option with generic readability safeguards.
+ */
+function normalizeWorkbenchChartDisplayDefaults(option: EChartsOption): EChartsOption {
+  const series = objectValue(option, 'series');
+  if (!Array.isArray(series) && !isRecord(series)) return option;
+  const normalizeSeries = (item: unknown) => (
+    isRecord(item) ? withReadablePieHoverLabel(withVisibleBarMinimum(item)) : item
+  );
+  return {
+    ...option,
+    series: Array.isArray(series) ? series.map(normalizeSeries) : normalizeSeries(series),
+  } as EChartsOption;
+}
+
+/**
+ * Reads one series option as a record by index.
+ * @param option - Runtime ECharts option.
+ * @param index - Series index from ECharts event params.
+ * @returns Series option when present.
+ */
+function runtimeSeriesAt(option: EChartsOption, index: number): Record<string, unknown> | null {
+  const series = objectValue(option, 'series');
+  const item = Array.isArray(series) ? series[index] : index === 0 ? series : undefined;
+  return isRecord(item) ? item : null;
+}
+
+/**
+ * Converts an ECharts center coordinate into pixels.
+ * @param value - Center coordinate, number or percentage string.
+ * @param size - Chart width or height.
+ * @returns Pixel coordinate.
+ */
+function chartCenterCoordinate(value: unknown, size: number): number {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string') {
+    const text = value.trim();
+    if (text.endsWith('%')) {
+      const percent = Number.parseFloat(text);
+      if (Number.isFinite(percent)) return size * percent / 100;
+    }
+    const numeric = Number.parseFloat(text);
+    if (Number.isFinite(numeric)) return numeric;
+  }
+  return size / 2;
+}
+
+/**
+ * Converts a pie radius value into pixels.
+ * @param value - Radius coordinate, number or percentage string.
+ * @param chart - Current ECharts instance.
+ * @returns Pixel radius.
+ */
+function chartRadiusCoordinate(value: unknown, chart: ECharts): number {
+  const base = Math.min(chart.getWidth(), chart.getHeight()) / 2;
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string') {
+    const text = value.trim();
+    if (text.endsWith('%')) {
+      const percent = Number.parseFloat(text);
+      if (Number.isFinite(percent)) return base * percent / 100;
+    }
+    const numeric = Number.parseFloat(text);
+    if (Number.isFinite(numeric)) return numeric;
+  }
+  return base * 0.42;
+}
+
+/**
+ * Resolves the center and text width available for a donut hover label.
+ * @param series - Donut series option.
+ * @param chart - Current ECharts instance.
+ * @returns Pixel center and safe text width.
+ */
+function donutHoverCenterGeometry(series: Record<string, unknown>, chart: ECharts): { x: number; y: number; width: number } {
+  const center = Array.isArray(series.center) ? series.center : ['50%', '50%'];
+  const radius = Array.isArray(series.radius) ? series.radius : [];
+  const innerRadius = chartRadiusCoordinate(radius[0], chart);
+  return {
+    x: chartCenterCoordinate(center[0], chart.getWidth()),
+    y: chartCenterCoordinate(center[1], chart.getHeight()),
+    width: Math.max(72, Math.floor(innerRadius * 2 - 12)),
+  };
+}
+
+/**
+ * Writes the centered donut hover label with ECharts graphic so old label layouts cannot pull it outside the ring.
+ * @param chart - Current ECharts instance.
+ * @param option - Runtime ECharts option used by the chart.
+ * @param seriesIndex - Hovered series index.
+ * @param label - Hover label text.
+ */
+function setDonutHoverCenterLabel(chart: ECharts, option: EChartsOption, seriesIndex: number, label: string): void {
+  const series = runtimeSeriesAt(option, seriesIndex);
+  if (!series || !isRuntimeDonutSeries(series) || !label.trim()) return;
+  const geometry = donutHoverCenterGeometry(series, chart);
+  chart.setOption({
+    graphic: [{
+      id: WORKBENCH_DONUT_HOVER_GRAPHIC_ID,
+      type: 'text',
+      x: geometry.x,
+      y: geometry.y,
+      z: 100,
+      silent: true,
+      style: {
+        text: label.trim(),
+        fill: '#1f2937',
+        fontSize: WORKBENCH_DONUT_HOVER_LABEL_MAX_FONT_SIZE,
+        fontWeight: 600,
+        lineHeight: 22,
+        width: geometry.width,
+        overflow: 'break',
+        align: 'center',
+        verticalAlign: 'middle',
+      },
+    }],
+  } as EChartsOption);
+}
+
+/**
+ * Clears the runtime graphic used for donut hover labels.
+ * @param chart - Current ECharts instance.
+ */
+function clearDonutHoverCenterLabel(chart: ECharts): void {
+  chart.setOption({
+    graphic: [{
+      id: WORKBENCH_DONUT_HOVER_GRAPHIC_ID,
+      $action: 'remove',
+    }],
+  } as EChartsOption);
+}
+
+/**
+ * Binds generic workbench-card donut hover behavior after the final runtime option is set.
+ * @param chart - Current ECharts instance.
+ * @param option - Final runtime ECharts option.
+ */
+function bindDonutHoverCenterLabel(chart: ECharts, option: EChartsOption): void {
+  if (!optionSeriesItems(option).some(isRuntimeDonutSeries)) return;
+  const existing = donutHoverCenterBindings.get(chart);
+  if (existing) {
+    existing.option = option;
+    return;
+  }
+  const binding = { option };
+  donutHoverCenterBindings.set(chart, binding);
+  chart.on('mouseover', (params: unknown) => {
+    const eventParams = params as { seriesType?: string; seriesIndex?: number; name?: unknown; data?: unknown };
+    if (eventParams.seriesType !== 'pie' || typeof eventParams.seriesIndex !== 'number') return;
+    const dataName = objectValue(eventParams.data, 'name');
+    const label = typeof eventParams.name === 'string' && eventParams.name.trim()
+      ? eventParams.name
+      : typeof dataName === 'string'
+        ? dataName
+        : '';
+    setDonutHoverCenterLabel(chart, binding.option, eventParams.seriesIndex, label);
+  });
+  chart.on('mouseout', (params: unknown) => {
+    const eventParams = params as { seriesType?: string };
+    if (eventParams.seriesType === 'pie') clearDonutHoverCenterLabel(chart);
+  });
+  chart.on('globalout', () => clearDonutHoverCenterLabel(chart));
+}
+
+function pieLegendLabelsFromOption(option: EChartsOption): string[] {
+  const seriesItems = optionSeriesItems(option);
+  if (seriesItems.length === 0 || !seriesItems.every((series) => series.type === 'pie')) return [];
+  return seriesItems.flatMap((series) => {
+    const data = series.data;
+    if (!Array.isArray(data)) return [];
+    return data.flatMap((item) => (
+      isRecord(item) && typeof item.name === 'string' && item.name.trim()
+        ? [item.name.trim()]
+        : []
+    ));
+  });
+}
+
+function legendWithRuntimeLabels(legend: unknown, labels: string[]): unknown {
+  if (labels.length === 0) return legend;
+  if (Array.isArray(legend)) {
+    return legend.map((item, index) => (
+      index === 0 && isRecord(item) ? { ...item, data: labels } : item
+    ));
+  }
+  if (legend === false) return legend;
+  return isRecord(legend) ? { ...legend, data: labels } : { data: labels };
+}
+
+function normalizeEchartsOptionPieLegend(option: EChartsOption): EChartsOption {
+  const labels = pieLegendLabelsFromOption(option);
+  if (labels.length === 0) return option;
+  const next = cloneOptionValue(option) as Record<string, unknown>;
+  next.legend = legendWithRuntimeLabels(next.legend, labels);
+  return next as EChartsOption;
+}
+
+/**
+ * 移除官方示例模板内置的图表标题和工具栏，避免与工作台卡片标题、操作区重复。
+ * @param option - 原始 ECharts option。
+ * @returns 不含模板标题与 toolbox 的运行时 option。
+ */
+function removeRuntimeEchartsChrome<T>(option: T): T {
+  if (!isRecord(option)) return option;
+  const optionRecord = option;
+  if (!Object.prototype.hasOwnProperty.call(optionRecord, 'title') && !Object.prototype.hasOwnProperty.call(optionRecord, 'toolbox')) {
+    return option;
+  }
+  const next = cloneOptionValue(option) as Record<string, unknown>;
+  delete next.title;
+  delete next.toolbox;
+  return next as T;
+}
+
+/**
+ * 判断 ECharts 类目轴是否已经包含运行时标签。
+ * @param axis - xAxis 配置。
+ * @returns 已有非空 data 数组时返回 true。
+ */
+function axisHasCategoryData(axis: unknown): boolean {
+  const firstAxis = Array.isArray(axis) ? axis.find(isRecord) : axis;
+  return isRecord(firstAxis) && Array.isArray(firstAxis.data) && firstAxis.data.length > 0;
+}
+
+/**
+ * 从协议数据中读取 X 轴类目标签。
+ * @param payload - protocolData 或 dataBinding.dataPayload。
+ * @returns 可渲染的类目标签。
+ */
+function categoryLabelsFromProtocolPayload(payload: unknown): string[] {
+  if (!isRecord(payload)) return [];
+  const categories = payload.categories;
+  const xAxis = isRecord(categories) ? categories.xAxis : undefined;
+  if (!Array.isArray(xAxis)) return [];
+  return xAxis.map((item, index) => {
+    const label = String(item ?? '').trim();
+    return label || `项 ${index + 1}`;
+  });
+}
+
+/**
+ * 从渲染数据中读取可用于恢复类目轴的协议标签。
+ * @param data - 当前卡片渲染数据。
+ * @returns 类目标签。
+ */
+function categoryLabelsFromRendererData(data: DisplayBlockData): string[] {
+  const directLabels = categoryLabelsFromProtocolPayload(objectValue(data, 'protocolData'));
+  if (directLabels.length > 0) return directLabels;
+  const dataBinding = objectValue(data, 'dataBinding');
+  return categoryLabelsFromProtocolPayload(objectValue(dataBinding, 'dataPayload'));
+}
+
+/**
+ * 补齐历史缓存中缺失的 ECharts 类目轴，避免浏览器回退显示 0..N 下标。
+ * @param option - 原始 ECharts option。
+ * @param data - 当前卡片渲染数据。
+ * @returns 带运行时类目轴的 option。
+ */
+function recoverMissingCartesianCategoryAxis(option: EChartsOption, data: DisplayBlockData): EChartsOption {
+  const optionRecord = option as Record<string, unknown>;
+  const xAxis = optionRecord.xAxis;
+  if ((!Array.isArray(xAxis) && !isRecord(xAxis)) || axisHasCategoryData(xAxis)) return option;
+  const labels = categoryLabelsFromRendererData(data);
+  if (labels.length === 0) return option;
+  const next = cloneOptionValue(option) as Record<string, unknown>;
+  const withLabels = (axisItem: unknown) => (
+    isRecord(axisItem)
+      ? { ...axisItem, type: typeof axisItem.type === 'string' ? axisItem.type : 'category', data: labels }
+      : axisItem
+  );
+  next.xAxis = Array.isArray(xAxis)
+    ? xAxis.map((axisItem, index) => (index === 0 ? withLabels(axisItem) : axisItem))
+    : withLabels(xAxis);
+  return next as EChartsOption;
+}
+
+/**
+ * 判断 series 是否不依赖 ECharts 外部坐标系。
+ * @param series - ECharts series 配置。
+ * @returns 饼图、雷达图、漏斗图和仪表盘返回 true。
+ */
+function isCoordinateFreeRuntimeSeries(series: Record<string, unknown>): boolean {
+  return series.type === 'pie'
+    || series.type === 'radar'
+    || series.type === 'funnel'
+    || series.type === 'gauge';
+}
+
+/**
+ * 移除非坐标图从官方模板继承到的坐标系索引。
+ * @param series - ECharts series 配置。
+ * @returns 可直接渲染的 series 配置。
+ */
+function sanitizeCoordinateFreeRuntimeSeries(series: Record<string, unknown>): Record<string, unknown> {
+  if (!isCoordinateFreeRuntimeSeries(series)) return series;
+  const {
+    coordinateSystem: _coordinateSystem,
+    xAxisIndex: _xAxisIndex,
+    yAxisIndex: _yAxisIndex,
+    gridIndex: _gridIndex,
+    calendarIndex: _calendarIndex,
+    matrixIndex: _matrixIndex,
+    polarIndex: _polarIndex,
+    geoIndex: _geoIndex,
+    bmapIndex: _bmapIndex,
+    ...rest
+  } = series;
+  return rest;
+}
+
+/**
+ * 清理最终 echartsOption 中非坐标图不需要的坐标组件，避免 ECharts 访问缺失坐标系时报错。
+ * @param option - 原始 ECharts option。
+ * @returns 清理后的 ECharts option。
+ */
+function sanitizeCoordinateFreeRuntimeOption(option: EChartsOption): EChartsOption {
+  const rawSeries = objectValue(option, 'series');
+  const hasSeriesArray = Array.isArray(rawSeries);
+  const seriesItems = hasSeriesArray
+    ? rawSeries.filter(isRecord)
+    : isRecord(rawSeries)
+      ? [rawSeries]
+      : [];
+  const hasInvalidSeriesItems = hasSeriesArray && seriesItems.length !== rawSeries.length;
+  const hasCoordinateFreeSeries = seriesItems.some(isCoordinateFreeRuntimeSeries);
+  if (seriesItems.length === 0) {
+    if (!hasInvalidSeriesItems) return option;
+    const next = cloneOptionValue(option) as Record<string, unknown>;
+    next.series = [];
+    return next as EChartsOption;
+  }
+  if (!hasInvalidSeriesItems && !hasCoordinateFreeSeries) return option;
+
+  const next = cloneOptionValue(option) as Record<string, unknown>;
+  const sanitizedSeries = hasCoordinateFreeSeries
+    ? seriesItems.map(sanitizeCoordinateFreeRuntimeSeries)
+    : seriesItems;
+  next.series = hasSeriesArray ? sanitizedSeries : sanitizedSeries[0];
+
+  if (hasCoordinateFreeSeries && sanitizedSeries.every(isCoordinateFreeRuntimeSeries)) {
+    delete next.xAxis;
+    delete next.yAxis;
+    delete next.grid;
+    delete next.calendar;
+    delete next.matrix;
+    delete next.polar;
+    delete next.geo;
+    delete next.bmap;
+  }
+
+  return next as EChartsOption;
+}
+
+/**
+ * 判断 ECharts option 是否使用极坐标系。
+ * @param option - 候选 ECharts option。
+ * @returns 存在 polar 组件或 polar series 时返回 true。
+ */
+function isPolarRuntimeOption(option: EChartsOption): boolean {
+  if (objectValue(option, 'polar') !== undefined || objectValue(option, 'angleAxis') !== undefined || objectValue(option, 'radiusAxis') !== undefined) {
+    return true;
+  }
+  return optionSeriesItems(option).some((series) => series.coordinateSystem === 'polar');
+}
+
+/**
+ * 移除极坐标物化卡片中误继承的笛卡尔坐标组件。
+ * @param option - 候选 ECharts option。
+ * @returns 极坐标运行时 option。
+ */
+function sanitizePolarRuntimeOption(option: EChartsOption): EChartsOption {
+  if (!isPolarRuntimeOption(option)) return option;
+  const optionRecord = option as Record<string, unknown>;
+  if (
+    !Object.prototype.hasOwnProperty.call(optionRecord, 'xAxis')
+    && !Object.prototype.hasOwnProperty.call(optionRecord, 'yAxis')
+    && !Object.prototype.hasOwnProperty.call(optionRecord, 'grid')
+  ) {
+    return option;
+  }
+
+  const next = cloneOptionValue(option) as Record<string, unknown>;
+  delete next.xAxis;
+  delete next.yAxis;
+  delete next.grid;
+  return next as EChartsOption;
+}
+
+/**
+ * 归一化持久化 echartsOption 的运行时渲染配置。
+ * @param option - 原始 ECharts option。
+ * @param data - 当前卡片渲染数据。
+ * @returns 可直接交给 ECharts 渲染的 option。
+ */
+/**
+ * Reads metric row contexts carried by workbench runtime metric payloads.
+ * @param data - Current renderer data.
+ * @returns Row contexts aligned with rendered series data items.
+ */
+function runtimeMetricRowContexts(data: DisplayBlockData): Record<string, unknown>[] {
+  const dataBinding = objectValue(data, 'dataBinding');
+  const dataBindingPayload = objectValue(dataBinding, 'dataPayload');
+  const dataBindingPayloadExtension = objectValue(dataBindingPayload, 'extension');
+  const protocolData = objectValue(data, 'protocolData');
+  const protocolDataExtension = objectValue(protocolData, 'extension');
+  for (const context of [
+    objectValue(data, 'metric_context'),
+    objectValue(data, 'metricContext'),
+    objectValue(dataBinding, 'metric_context'),
+    objectValue(dataBinding, 'metricContext'),
+    objectValue(dataBindingPayload, 'metric_context'),
+    objectValue(dataBindingPayloadExtension, 'metric_context'),
+    objectValue(protocolData, 'metric_context'),
+    objectValue(protocolDataExtension, 'metric_context'),
+  ]) {
+    const rows = objectValue(context, 'row_contexts');
+    if (Array.isArray(rows)) return rows.filter(isRecord);
+  }
+  return [];
+}
+
+/**
+ * Converts an arbitrary ECharts or metric context value into a comparable label.
+ * @param value - Candidate display value.
+ * @returns Trimmed display label.
+ */
+function metricContextLabel(value: unknown): string {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'string') return value.trim();
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Reads the typed storage value payload from one row-context dimension value.
+ * @param value - Candidate storage value.
+ * @returns Raw storage value when present.
+ */
+function metricContextStorageRawValue(value: unknown): unknown {
+  const record = isRecord(value) ? value : null;
+  if (!record || !Object.prototype.hasOwnProperty.call(record, 'value')) return undefined;
+  return record.value;
+}
+
+/**
+ * Reads labels that can identify a metric row context across chart renderers.
+ * @param rowContext - Runtime metric row context.
+ * @returns Comparable dimension labels for this row context.
+ */
+function metricRowContextLabels(rowContext: Record<string, unknown>): string[] {
+  const dimensionValues = objectValue(rowContext, 'dimension_values');
+  if (!isRecord(dimensionValues)) return [];
+  const labels = Object.values(dimensionValues).flatMap((value) => {
+    const dimensionValue = isRecord(value) ? value : {};
+    return [
+      metricContextLabel(dimensionValue.display_value),
+      metricContextLabel(dimensionValue.raw_value),
+      metricContextLabel(metricContextStorageRawValue(dimensionValue.storage_value)),
+    ];
+  }).filter(Boolean);
+  return Array.from(new Set(labels));
+}
+
+/**
+ * Checks whether a row-context label can identify the rendered category.
+ * @param rowContext - Runtime metric row context.
+ * @param categoryLabel - Rendered category label.
+ * @param mode - Matching mode.
+ * @returns True when the row context belongs to the category label.
+ */
+function metricRowContextMatchesCategoryLabel(
+  rowContext: Record<string, unknown>,
+  categoryLabel: string,
+  mode: 'exact' | 'disambiguated',
+): boolean {
+  const labels = metricRowContextLabels(rowContext);
+  if (mode === 'exact') return labels.includes(categoryLabel);
+  return labels.some((label) => label.startsWith(`${categoryLabel}+`));
+}
+
+/**
+ * Reads category labels from a category axis.
+ * @param axis - ECharts axis option.
+ * @returns Axis category labels.
+ */
+function categoryLabelsFromAxis(axis: unknown): string[] {
+  const axes = Array.isArray(axis) ? axis : [axis];
+  for (const item of axes) {
+    if (!isRecord(item) || item.type !== 'category' || !Array.isArray(item.data)) continue;
+    const labels = item.data.map(metricContextLabel);
+    if (labels.some(Boolean)) return labels;
+  }
+  return [];
+}
+
+/**
+ * Reads category labels already present in the normalized runtime option.
+ * @param option - Normalized ECharts option.
+ * @returns Category labels aligned with scalar series data.
+ */
+function runtimeOptionCategoryLabels(option: EChartsOption): string[] {
+  return [
+    categoryLabelsFromAxis(objectValue(option, 'xAxis')),
+    categoryLabelsFromAxis(objectValue(option, 'yAxis')),
+    categoryLabelsFromAxis(objectValue(option, 'angleAxis')),
+  ].find((labels) => labels.length > 0) ?? [];
+}
+
+/**
+ * Resolves the rendered category label for one ECharts data item.
+ * @param value - Original ECharts series data item.
+ * @param index - Series data index.
+ * @param categoryLabels - Axis category labels aligned with scalar data.
+ * @returns Comparable category label.
+ */
+function runtimeDataItemCategoryLabel(value: unknown, index: number, categoryLabels: string[]): string {
+  if (isRecord(value)) {
+    const name = metricContextLabel(value.name);
+    if (name) return name;
+    const itemValue = value.value;
+    if (Array.isArray(itemValue)) return metricContextLabel(itemValue[0]);
+    return categoryLabels[index] ?? '';
+  }
+  if (Array.isArray(value)) return metricContextLabel(value[0]);
+  return categoryLabels[index] ?? '';
+}
+
+/**
+ * Finds a unique row context for the clicked/rendered category label.
+ * @param rowContexts - Runtime metric row contexts.
+ * @param categoryLabel - Rendered category label.
+ * @returns Matching row context, or undefined when matching is ambiguous.
+ */
+function metricRowContextByCategoryLabel(
+  rowContexts: Record<string, unknown>[],
+  categoryLabel: string,
+): Record<string, unknown> | undefined {
+  if (!categoryLabel) return undefined;
+  const exactMatched = rowContexts.filter((rowContext) => metricRowContextMatchesCategoryLabel(rowContext, categoryLabel, 'exact'));
+  const disambiguatedMatched = rowContexts.filter((rowContext) => metricRowContextMatchesCategoryLabel(rowContext, categoryLabel, 'disambiguated'));
+  if (exactMatched.length === 1 && disambiguatedMatched.length === 0) return exactMatched[0];
+  if (exactMatched.length === 0 && disambiguatedMatched.length === 1) return disambiguatedMatched[0];
+  return undefined;
+}
+
+/**
+ * Attaches one row context to an ECharts data item without changing its displayed value.
+ * @param value - Original ECharts series data item.
+ * @param rowContext - Metric row context for the same rendered item.
+ * @returns Series data item carrying item-level detail identity.
+ */
+function dataItemWithRuntimeMetricRowContext(value: unknown, rowContext: Record<string, unknown> | undefined): unknown {
+  if (!rowContext && !isRecord(value)) return value;
+  if (!rowContext && isRecord(value)) {
+    const { [WORKBENCH_METRIC_ROW_CONTEXT_KEY]: _staleContext, ...rest } = value;
+    return rest;
+  }
+  if (isRecord(value)) return { ...value, [WORKBENCH_METRIC_ROW_CONTEXT_KEY]: rowContext };
+  return { value, [WORKBENCH_METRIC_ROW_CONTEXT_KEY]: rowContext };
+}
+
+/**
+ * Preserves metric detail identity on runtime ECharts option data items.
+ * @param option - Normalized ECharts option.
+ * @param data - Current renderer data.
+ * @returns ECharts option whose clickable data items include row contexts.
+ */
+function withRuntimeMetricRowContexts(option: EChartsOption, data: DisplayBlockData): EChartsOption {
+  const rowContexts = runtimeMetricRowContexts(data);
+  if (rowContexts.length === 0) return option;
+  const series = objectValue(option, 'series');
+  const categoryLabels = runtimeOptionCategoryLabels(option);
+  const attachSeries = (value: unknown): unknown => {
+    if (!isRecord(value) || !Array.isArray(value.data)) return value;
+    const labels = value.data.map((item, index) => runtimeDataItemCategoryLabel(item, index, categoryLabels));
+    const labelCounts = labels.reduce((counts, label) => counts.set(label, (counts.get(label) ?? 0) + 1), new Map<string, number>());
+    return {
+      ...value,
+      data: value.data.map((item, index) => dataItemWithRuntimeMetricRowContext(
+        item,
+        labelCounts.get(labels[index]) === 1 ? metricRowContextByCategoryLabel(rowContexts, labels[index]) : undefined,
+      )),
+    };
+  };
+  if (!Array.isArray(series) && !isRecord(series)) return option;
+  return {
+    ...option,
+    series: Array.isArray(series) ? series.map(attachSeries) : attachSeries(series),
+  };
+}
+
+function normalizeRuntimeEchartsOption(option: EChartsOption, data: DisplayBlockData): EChartsOption {
+  return normalizeSharedWorkbenchChartDisplayDefaults(withRuntimeMetricRowContexts(removeRuntimeEchartsChrome(
+    normalizeEchartsOptionPieLegend(
+      sanitizeCoordinateFreeRuntimeOption(
+        sanitizePolarRuntimeOption(
+          recoverMissingCartesianCategoryAxis(option, data),
+        ),
+      ),
+    ),
+  ), data));
+}
+
+function optionUsesEchartsGl(option: EChartsOption | null) {
+  if (!option) return false;
+  if (objectValue(option, 'globe')) return true;
+  const series = objectValue(option, 'series');
+  const normalizedSeries = Array.isArray(series) ? series : series ? [series] : [];
+  return normalizedSeries.some((item) => GL_SERIES_TYPES.has(String(objectValue(item, 'type'))));
+}
+
+function dataRequiresEchartsGl(data: DisplayBlockData, option: EChartsOption | null) {
+  const requires = Array.isArray(objectValue(data, 'requires')) ? objectValue(data, 'requires') as unknown[] : [];
+  const engine = String(objectValue(data, 'engine') || '');
+  return engine === 'echarts-gl'
+    || requires.some((item) => GL_REQUIREMENTS.has(String(item)))
+    || (data.shape === 'echartsScript' && GL_SCRIPT_PATTERN.test(data.script))
+    || optionUsesEchartsGl(option);
+}
+
+export function chartTheme(data: DisplayBlockData, option: EChartsOption | null) {
+  const explicitTheme = objectValue(data, 'theme');
+  if (typeof explicitTheme === 'string' && explicitTheme.trim()) return explicitTheme.trim();
+  return dataRequiresEchartsGl(data, option) ? 'dark' : undefined;
+}
+
+async function ensureEchartsGlLoaded() {
+  if (!echartsGlLoadPromise) {
+    echartsGlLoadPromise = import('echarts-gl').then(() => undefined);
+  }
+  await echartsGlLoadPromise;
+}
+
+function finiteValues(values: number[], fallback = [0, 1]) {
+  const safe = values.filter(Number.isFinite);
+  return safe.length ? safe : fallback;
+}
+
+/**
+ * Builds common ECharts option defaults.
+ * @param colors - Optional generated palette colors.
+ * @returns Base ECharts option.
+ */
+function baseOption(colors?: string[]): EChartsOption {
+  return {
+    color: colors?.length ? colors : CHART_COLORS,
+    animationDuration: 500,
+    grid: { left: 42, right: 24, top: 28, bottom: 38, containLabel: true },
+    tooltip: { trigger: 'item', confine: true },
+    textStyle: { color: '#475569', fontFamily: 'Inter, system-ui, sans-serif' },
+  };
+}
+
+/**
+ * Reads a non-empty string color array.
+ * @param value - Candidate palette value.
+ * @returns Palette colors.
+ */
+function stringPalette(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const colors = value
+    .map((item) => typeof item === 'string' ? item.trim() : '')
+    .filter(Boolean);
+  return colors.length > 0 ? colors : undefined;
+}
+
+/**
+ * Reads generated chart colors from renderer data.
+ * @param data - Workbench renderer data.
+ * @returns Generated palette colors.
+ */
+function paletteColorsFromData(data: unknown): string[] | undefined {
+  const directColors = stringPalette(objectValue(data, 'color'));
+  if (directColors) return directColors;
+  const palette = objectValue(data, 'palette');
+  const paletteColors = stringPalette(objectValue(palette, 'colors'));
+  return paletteColors ?? stringPalette(palette);
+}
+
+/**
+ * Reads a generated color from one pie slice.
+ * @param slice - Pie slice renderer data.
+ * @returns Slice color.
+ */
+function sliceColor(slice: unknown): string | undefined {
+  const color = objectValue(slice, 'color');
+  return typeof color === 'string' && color.trim() ? color.trim() : undefined;
+}
+
+/**
+ * Reads generated colors from pie slices.
+ * @param data - Pie renderer data.
+ * @returns Slice-level palette colors.
+ */
+function pieSliceColors(data: PieSlicesData): string[] | undefined {
+  const colors = data.slices.map((slice) => sliceColor(slice)).filter((color): color is string => Boolean(color));
+  return colors.length > 0 ? colors : undefined;
+}
+
+function fallbackSeriesType(rendererKey: string): 'bar' | 'line' {
+  return /bar|column/i.test(rendererKey) && !/line|area/i.test(rendererKey) ? 'bar' : 'line';
+}
+
+function seriesOption(data: MultiSeriesData, rendererKey = ''): EChartsOption {
+  assertArray(data.categories, 'categories');
+  assertArray(data.series, 'series');
+  const stacked = data.series.some((item) => item.name.includes('上期')) || data.narrative?.includes('堆叠');
+  const layout = buildCartesianResponsiveLayout(data.categories, data.series.length);
+  return {
+    ...baseOption(paletteColorsFromData(data)),
+    grid: layout.grid,
+    legend: layout.legend,
+    xAxis: {
+      type: 'category',
+      data: data.categories,
+      axisLine: { lineStyle: { color: '#dbe4f0' } },
+      axisTick: { show: false },
+      ...layout.xAxis,
+    },
+    yAxis: { type: 'value', axisLine: { show: false }, splitLine: { lineStyle: { color: '#eef2f7' } } },
+    tooltip: { trigger: 'axis', confine: true },
+    series: data.series.map((item) => ({
+      name: item.name,
+      type: item.type || fallbackSeriesType(rendererKey),
+      colorBy: item.colorBy,
+      itemStyle: item.itemStyle,
+      smooth: item.type === 'line',
+      stack: stacked && item.type === 'bar' ? 'total' : undefined,
+      areaStyle: data.unit === '累计指数' && item.type === 'line' ? { opacity: 0.18 } : undefined,
+      data: item.data,
+      barMaxWidth: 34,
+      symbolSize: 7,
+    })),
+  };
+}
+
+function waterfallOption(data: WaterfallStepsData): EChartsOption {
+  assertArray(data.steps, 'steps');
+  let running = 0;
+  const transparent: number[] = [];
+  const values = data.steps.map((step) => {
+    const raw = step.value ?? step.delta ?? 0;
+    const start = step.delta ? running : 0;
+    transparent.push(Math.max(0, start));
+    running = step.value ?? running + raw;
+    return Math.abs(raw);
+  });
+  return {
+    ...baseOption(),
+    xAxis: { type: 'category', data: data.steps.map((step) => step.label), axisTick: { show: false } },
+    yAxis: { type: 'value', splitLine: { lineStyle: { color: '#eef2f7' } } },
+    tooltip: { trigger: 'axis', confine: true },
+    series: [
+      { type: 'bar', stack: 'total', itemStyle: { color: 'transparent' }, emphasis: { disabled: true }, data: transparent },
+      { name: data.unit, type: 'bar', stack: 'total', barMaxWidth: 42, data: values },
+    ],
+  };
+}
+
+function heatmapOption(data: HeatmapMatrixData): EChartsOption {
+  assertArray(data.rows, 'rows');
+  assertArray(data.columns, 'columns');
+  assertArray(data.values, 'values');
+  const values = data.rows.flatMap((row, rowIndex) =>
+    data.columns.map((_column, columnIndex) => [columnIndex, rowIndex, data.values[rowIndex]?.[columnIndex] ?? 0, row]),
+  );
+  const flat = finiteValues(data.values.flat());
+  return {
+    ...baseOption(),
+    grid: { left: 80, right: 24, top: 22, bottom: 34 },
+    xAxis: { type: 'category', data: data.columns, splitArea: { show: true } },
+    yAxis: { type: 'category', data: data.rows, splitArea: { show: true } },
+    visualMap: { min: Math.min(...flat), max: Math.max(...flat), calculable: false, orient: 'horizontal', left: 'center', bottom: 0, inRange: { color: ['#dbeafe', '#1f4fd4'] } },
+    series: [{ type: 'heatmap', data: values, label: { show: true } }],
+  };
+}
+
+function pieOption(data: PieSlicesData): EChartsOption {
+  assertArray(data.slices, 'slices');
+  const layout = buildPieResponsiveLayout(data.slices);
+  const colors = pieSliceColors(data) ?? paletteColorsFromData(data);
+  const isDonut = Boolean(data.innerRadius);
+  return {
+    ...baseOption(colors),
+    legend: layout.legend,
+    series: [{
+      type: 'pie',
+      radius: data.innerRadius ? [`${data.innerRadius * 100}%`, '72%'] : ['0%', '72%'],
+      center: layout.series.center,
+      avoidLabelOverlap: true,
+      label: isDonut ? { show: false } : layout.series.label,
+      labelLine: isDonut ? { show: false } : layout.series.labelLine,
+      labelLayout: layout.series.labelLayout,
+      minShowLabelAngle: layout.series.minShowLabelAngle,
+      emphasis: isDonut
+        ? {
+          label: {
+            show: true,
+            position: 'center',
+            fontSize: 16,
+            fontWeight: 600,
+          },
+        }
+        : undefined,
+      data: data.slices.map((item) => ({
+        name: item.label,
+        value: item.value,
+        ...(sliceColor(item) ? { itemStyle: { color: sliceColor(item) } } : {}),
+      })),
+    }],
+  };
+}
+
+function radarOption(data: RadarMetricsData): EChartsOption {
+  assertArray(data.axes, 'axes');
+  return {
+    ...baseOption(),
+    radar: { radius: '68%', indicator: data.axes.map((axis) => ({ name: axis.label, max: data.max })), splitArea: { areaStyle: { color: ['#f8fafc', '#eef2ff'] } } },
+    series: [{ type: 'radar', areaStyle: { opacity: 0.18 }, data: [{ name: '评分', value: data.axes.map((axis) => axis.value) }] }],
+  };
+}
+
+function scatterOption(data: ScatterPointsData): EChartsOption {
+  assertArray(data.points, 'points');
+  return {
+    ...baseOption(),
+    xAxis: { type: 'value', name: data.xLabel, splitLine: { lineStyle: { color: '#eef2f7' } } },
+    yAxis: { type: 'value', name: data.yLabel, splitLine: { lineStyle: { color: '#eef2f7' } } },
+    tooltip: {
+      formatter: (params: unknown) => {
+        const item = params as { data?: [number, number, number, string] };
+        return `${item.data?.[3] || ''}<br/>${data.xLabel}: ${item.data?.[0]}<br/>${data.yLabel}: ${item.data?.[1]}${data.sizeLabel ? `<br/>${data.sizeLabel}: ${item.data?.[2]}` : ''}`;
+      },
+    },
+    series: [{
+      type: 'scatter',
+      data: data.points.map((point) => [point.x, point.y, point.size || 12, point.label]),
+      symbolSize: (value: unknown) => {
+        const tuple = value as [number, number, number];
+        return data.sizeLabel ? Math.max(12, tuple[2]) : 14;
+      },
+    }],
+  };
+}
+
+function funnelOption(data: FunnelStagesData): EChartsOption {
+  assertArray(data.stages, 'stages');
+  return {
+    ...baseOption(),
+    legend: { bottom: 0 },
+    series: [{ type: 'funnel', left: '10%', top: 18, bottom: 28, width: '80%', minSize: '28%', maxSize: '92%', sort: 'descending', gap: 4, label: { formatter: '{b}: {c}' }, data: data.stages.map((stage) => ({ name: stage.label, value: stage.value })) }],
+  };
+}
+
+function gaugeOption(data: GaugeMetricData): EChartsOption {
+  return {
+    ...baseOption(),
+    series: [{ type: 'gauge', min: 0, max: data.max, progress: { show: true, width: 16 }, axisLine: { lineStyle: { width: 16 } }, pointer: { width: 4 }, detail: { formatter: `{value}${data.unit || ''}`, fontSize: 28, color: '#0f172a' }, data: [{ value: data.value, name: data.label }] }],
+  };
+}
+
+function mapOption(data: MapRegionsData): EChartsOption {
+  assertArray(data.regions, 'regions');
+  ensureMapRegistered();
+  const values = finiteValues(data.regions.map((region) => region.value));
+  return {
+    ...baseOption(),
+    visualMap: { min: Math.min(...values), max: Math.max(...values), left: 0, bottom: 0, text: ['高', '低'], inRange: { color: ['#dbeafe', '#93c5fd', '#1f4fd4'] } },
+    series: [{ type: 'map', map: 'workbench-regions', roam: false, label: { show: true, color: '#0f172a' }, data: data.regions.map((region) => ({ name: region.name, value: region.value })) }],
+  };
+}
+
+function sankeyOption(data: SankeyFlowData): EChartsOption {
+  assertArray(data.nodes, 'nodes');
+  assertArray(data.links, 'links');
+  const labels = new Map(data.nodes.map((node) => [node.id, node.label]));
+  return {
+    ...baseOption(),
+    series: [{ type: 'sankey', left: 12, right: 20, top: 14, bottom: 14, nodeAlign: 'justify', data: data.nodes.map((node) => ({ name: node.label })), links: data.links.map((link) => ({ source: labels.get(link.source) || link.source, target: labels.get(link.target) || link.target, value: link.value })), lineStyle: { color: 'gradient', curveness: 0.5 } }],
+  };
+}
+
+function toTreeOptionNode(node: TreeNodeData): Record<string, unknown> {
+  return { name: node.label, value: node.value, children: node.children?.map((child) => toTreeOptionNode(child)) };
+}
+
+function treeOption(data: TreeHierarchyData): EChartsOption {
+  assertRecord(data.root, 'treeHierarchy.root');
+  return {
+    ...baseOption(),
+    series: [{ type: 'tree', data: [toTreeOptionNode(data.root)], top: 18, left: 16, bottom: 18, right: 110, symbolSize: 9, orient: 'LR', label: { position: 'left', verticalAlign: 'middle', align: 'right' }, leaves: { label: { position: 'right', verticalAlign: 'middle', align: 'left' } }, expandAndCollapse: false }],
+  };
+}
+
+function ganttOption(data: GanttTasksData): EChartsOption {
+  assertArray(data.timeline, 'timeline');
+  assertArray(data.tasks, 'tasks');
+  const statusColors: Record<GanttTasksData['tasks'][number]['status'], string> = { done: '#16a34a', running: '#1f4fd4', pending: '#94a3b8', risk: '#dc2626' };
+  return {
+    ...baseOption(),
+    grid: { left: 90, right: 28, top: 26, bottom: 34 },
+    xAxis: { type: 'category', data: data.timeline, axisTick: { show: false } },
+    yAxis: { type: 'category', data: data.tasks.map((task) => task.label), axisTick: { show: false } },
+    series: [{
+      type: 'custom',
+      renderItem(_params: unknown, api: unknown) {
+        const typedApi = api as { value: (index: number) => number | string; coord: (value: [number, number]) => [number, number]; size: (value: [number, number]) => [number, number]; style: (style: Record<string, unknown>) => Record<string, unknown> };
+        const categoryIndex = Number(typedApi.value(0));
+        const start = Number(typedApi.value(1));
+        const end = Number(typedApi.value(2));
+        const status = String(typedApi.value(3)) as GanttTasksData['tasks'][number]['status'];
+        const startPoint = typedApi.coord([start, categoryIndex]);
+        const endPoint = typedApi.coord([end, categoryIndex]);
+        const height = typedApi.size([0, 1])[1] * 0.48;
+        return { type: 'rect', shape: { x: startPoint[0], y: startPoint[1] - height / 2, width: Math.max(8, endPoint[0] - startPoint[0]), height, r: 6 }, style: typedApi.style({ fill: statusColors[status] || '#1f4fd4' }) };
+      },
+      encode: { x: [1, 2], y: 0 },
+      data: data.tasks.map((task, index) => [index, task.start, task.end, task.status, task.owner]),
+    }],
+  };
+}
+
+function candlestickOption(data: CandlestickSeriesData): EChartsOption {
+  assertArray(data.categories, 'categories');
+  assertArray(data.values, 'values');
+  return {
+    ...baseOption(),
+    xAxis: { type: 'category', data: data.categories, boundaryGap: true },
+    yAxis: { type: 'value', scale: true, splitLine: { lineStyle: { color: '#eef2f7' } } },
+    series: [{ type: 'candlestick', data: data.values.map((item) => [item.open, item.close, item.low, item.high]), itemStyle: { color: '#16a34a', color0: '#dc2626', borderColor: '#16a34a', borderColor0: '#dc2626' } }],
+  };
+}
+
+function boxplotOption(data: BoxplotSeriesData): EChartsOption {
+  assertArray(data.categories, 'categories');
+  assertArray(data.values, 'values');
+  return {
+    ...baseOption(),
+    xAxis: { type: 'category', data: data.categories, axisTick: { show: false } },
+    yAxis: { type: 'value', scale: true, splitLine: { lineStyle: { color: '#eef2f7' } } },
+    tooltip: { trigger: 'item', confine: true },
+    series: [{ type: 'boxplot', data: data.values }],
+  };
+}
+
+function paretoOption(data: ParetoSeriesData): EChartsOption {
+  assertArray(data.categories, 'categories');
+  assertArray(data.bars, 'bars');
+  assertArray(data.cumulative, 'cumulative');
+  const barName = '需求数';
+  const cumulativeName = '累计占比(%)';
+  return {
+    ...baseOption(),
+    legend: { bottom: 0, data: [barName, cumulativeName] },
+    xAxis: { type: 'category', data: data.categories, axisTick: { show: false } },
+    yAxis: [
+      { type: 'value', name: barName, splitLine: { lineStyle: { color: '#eef2f7' } } },
+      { type: 'value', name: '累计占比', min: 0, max: 100, axisLabel: { formatter: '{value}%' } },
+    ],
+    tooltip: { trigger: 'axis', confine: true, formatter: paretoTooltipFormatter },
+    series: [{ name: barName, type: 'bar', barMaxWidth: 34, data: data.bars }, { name: cumulativeName, type: 'line', yAxisIndex: 1, smooth: true, data: data.cumulative }],
+  };
+}
+
+function paretoTooltipFormatter(params: unknown): string {
+  const items = Array.isArray(params) ? params as Array<Record<string, unknown>> : [];
+  const title = typeof items[0]?.name === 'string' ? items[0].name : '';
+  const dataIndex = typeof items[0]?.dataIndex === 'number' ? items[0].dataIndex : 0;
+  const lines = items.map((item) => {
+    const marker = typeof item.marker === 'string' ? item.marker : '';
+    const name = String(item.seriesName ?? '');
+    const value = typeof item.value === 'number' ? item.value : Number(item.value);
+    if (name.includes('累计占比')) {
+      return `${marker}累计占比：${formatParetoPercent(value)}`;
+    }
+    return `${marker}${name}：${Number.isFinite(value) ? value : ''}`;
+  });
+  return [title, ...lines, `前 ${dataIndex + 1} 项累计占全部的比例`].filter(Boolean).join('<br/>');
+}
+
+function formatParetoPercent(value: number): string {
+  if (!Number.isFinite(value)) return '';
+  return `${Number(value.toFixed(2))}%`;
+}
+
+function networkOption(data: NetworkGraphData): EChartsOption {
+  assertArray(data.nodes, 'nodes');
+  assertArray(data.links, 'links');
+  const categoryNames: string[] = Array.from(new Set(data.nodes.map((node) => node.category || '默认')));
+  const categories = categoryNames.map((name) => ({ name }));
+  return {
+    ...baseOption(),
+    tooltip: { trigger: 'item', confine: true },
+    legend: { bottom: 0, data: categories.map((item) => item.name) },
+    series: [{ type: 'graph', layout: 'force', roam: false, draggable: false, categories, force: { repulsion: 160, edgeLength: 88 }, label: { show: true, formatter: '{b}' }, lineStyle: { color: '#94a3b8', opacity: 0.8 }, data: data.nodes.map((node) => ({ id: node.id, name: node.label, value: node.value, category: node.category || '默认', symbolSize: Math.max(24, Math.min(56, node.value || 28)) })), links: data.links.map((link) => ({ source: link.source, target: link.target, value: link.value || 1 })) }],
+  };
+}
+
+function geoGlobeOption(data: GeoGlobeData): EChartsOption {
+  assertArray(data.arcs, 'arcs');
+  const uniqueLabels: string[] = Array.from(new Set(data.arcs.flatMap((arc) => [arc.from, arc.to])));
+  return {
+    ...baseOption(),
+    radar: { radius: '62%', indicator: uniqueLabels.slice(0, 6).map((label) => ({ name: label, max: 100 })), splitArea: { areaStyle: { color: ['#eef2ff', '#f8fafc'] } } },
+    series: [{ type: 'radar', areaStyle: { opacity: 0.2 }, data: [{ name: data.centerLabel, value: uniqueLabels.slice(0, 6).map((label) => data.arcs.find((item) => item.from === label || item.to === label)?.value || 36) }] }],
+  };
+}
+
+function normalizeRootPath(rootPath = '') {
+  const nextRootPath = rootPath.trim() || DEFAULT_ECHARTS_ROOT_PATH;
+  return nextRootPath.replace(/\/$/, '') === OFFICIAL_ECHARTS_ROOT_PATH
+    ? DEFAULT_ECHARTS_ROOT_PATH
+    : nextRootPath;
+}
+
+function resolveEchartsResourceUrl(url: string, rootPath: string) {
+  const normalizedRootPath = normalizeRootPath(rootPath).replace(/\/$/, '');
+  if (url.startsWith(OFFICIAL_ECHARTS_ROOT_PATH)) return url.replace(OFFICIAL_ECHARTS_ROOT_PATH, DEFAULT_ECHARTS_ROOT_PATH);
+  if (/^(https?:)?\/\//.test(url) || /^(data|blob):/.test(url)) return url;
+  if (url === normalizedRootPath || url.startsWith(`${normalizedRootPath}/`)) return url;
+  if (url.startsWith('/')) return `${normalizedRootPath}${url}`;
+  return `${normalizedRootPath}/${url}`;
+}
+
+function optionItems(value: unknown) {
+  if (!value) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+function collectMapNamesFromOption(option: EChartsOption | null) {
+  const mapNames = new Set<string>();
+  const collectMapName = (candidate: unknown) => {
+    const mapName = objectValue(candidate, 'map') ?? objectValue(candidate, 'mapType');
+    if (typeof mapName === 'string' && mapName.trim()) mapNames.add(mapName.trim());
+  };
+  optionItems(objectValue(option, 'geo')).forEach(collectMapName);
+  optionItems(objectValue(option, 'geo3D')).forEach(collectMapName);
+  optionItems(objectValue(option, 'series')).forEach((item) => {
+    const type = String(objectValue(item, 'type') || '');
+    if (type === 'map' || type === 'map3D') collectMapName(item);
+  });
+  return Array.from(mapNames);
+}
+
+function normalizeRuntimeMapNames(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map((item) => normalizeRuntimeMapNames(item));
+  if (!value || typeof value !== 'object') return value;
+  const result: Record<string, unknown> = {};
+  Object.entries(value as Record<string, unknown>).forEach(([key, item]) => {
+    if ((key === 'geo' || key === 'geo3D') && item && typeof item === 'object') {
+      const normalizedGeo = normalizeRuntimeMapNames(item) as Record<string, unknown> | Record<string, unknown>[];
+      const fillMapName = (geoItem: Record<string, unknown>) => (
+        typeof geoItem.map === 'string' || typeof geoItem.mapType === 'string'
+          ? geoItem
+          : { ...geoItem, map: 'workbench-regions' }
+      );
+      result[key] = Array.isArray(normalizedGeo)
+        ? normalizedGeo.map((geoItem) => (geoItem && typeof geoItem === 'object' ? fillMapName(geoItem) : geoItem))
+        : fillMapName(normalizedGeo);
+      return;
+    }
+    if ((key === 'map' || key === 'mapType') && typeof item === 'string' && !item.trim()) {
+      result[key] = 'workbench-regions';
+      return;
+    }
+    result[key] = normalizeRuntimeMapNames(item);
+  });
+  return result;
+}
+
+async function ensureEchartsMapRegistered(mapName: string, rootPath: string | undefined) {
+  if (!mapName || echarts.getMap(mapName)) return;
+  if (mapName === 'workbench-regions') {
+    ensureMapRegistered();
+    return;
+  }
+  const normalizedRootPath = normalizeRootPath(rootPath);
+  const cacheKey = `${normalizedRootPath}:${mapName}`;
+  if (!echartsMapLoadPromises.has(cacheKey)) {
+    const resourceUrl = resolveEchartsResourceUrl(`/data/asset/geo/${encodeURIComponent(mapName)}.json`, normalizedRootPath);
+    echartsMapLoadPromises.set(cacheKey, window.fetch(resourceUrl)
+      .then(async (response) => {
+        if (!response.ok) throw new Error(`ECharts 地图资源加载失败：${response.status} ${resourceUrl}`);
+        const geoJson = await response.json();
+        if (!geoJson || typeof geoJson !== 'object' || !Array.isArray((geoJson as Record<string, unknown>).features)) {
+          throw new Error(`ECharts 地图资源格式错误：${mapName}`);
+        }
+        echarts.registerMap(mapName, geoJson as never);
+      })
+      .catch((error) => {
+        echartsMapLoadPromises.delete(cacheKey);
+        throw error;
+      }));
+  }
+  await echartsMapLoadPromises.get(cacheKey);
+}
+
+async function ensureEchartsMapsForOption(option: EChartsOption | null, rootPath?: string) {
+  const mapNames = collectMapNamesFromOption(option);
+  if (!mapNames.length) return;
+  await Promise.all(mapNames.map((mapName) => ensureEchartsMapRegistered(mapName, rootPath)));
+}
+
+function createJQueryCompat(rootPath: string, isActive: () => boolean, onError: (error: unknown) => void): JQueryCompat {
+  const request = <T>(
+    url: string,
+    read: (response: Response) => Promise<T>,
+    callback?: (data: T) => void,
+  ): JQueryCompatRequest<T> => {
+    const resourceUrl = resolveEchartsResourceUrl(String(url), rootPath);
+    const basePromise = window.fetch(resourceUrl)
+      .then((response) => {
+        if (!response.ok) throw new Error(`ECharts 示例资源加载失败：${response.status} ${resourceUrl}`);
+        return read(response);
+      });
+    const handledPromise = basePromise
+      .then((data) => {
+        if (isActive()) callback?.(data);
+        return data;
+      })
+      .catch((error) => {
+        if (isActive()) onError(error);
+        return undefined;
+      }) as JQueryCompatRequest<T>;
+    handledPromise.done = (doneCallback) => {
+      void handledPromise.then((data) => {
+        if (data !== undefined && isActive()) doneCallback(data);
+      });
+      return handledPromise;
+    };
+    handledPromise.fail = (failCallback) => {
+      void basePromise.catch((error) => {
+        if (isActive()) failCallback(error);
+      });
+      return handledPromise;
+    };
+    return handledPromise;
+  };
+  return {
+    get: (url, callback) => request(
+      url,
+      async (response) => {
+        const contentType = response.headers.get('content-type') || '';
+        if (contentType.includes('json') || /\.json(?:$|\?)/.test(url)) return response.json();
+        return response.text();
+      },
+      callback,
+    ),
+    getJSON: (url, callback) => request(url, (response) => response.json(), callback),
+  };
+}
+
+function createScopedChart(chart: ECharts, rootPath: string | undefined, isActive: () => boolean, onError: (error: unknown) => void): ECharts {
+  return new Proxy(chart, {
+    get(target, property, receiver) {
+      const value = Reflect.get(target, property, receiver);
+      if (typeof value !== 'function') return value;
+      return (...args: unknown[]) => {
+        if (!isActive()) return undefined;
+        if (property === 'setOption') {
+          const runtimeArgs = [
+            normalizeSharedWorkbenchChartDisplayDefaults(removeRuntimeEchartsChrome(args[0] as EChartsOption)),
+            ...args.slice(1),
+          ];
+          void ensureEchartsMapsForOption(runtimeArgs[0] as EChartsOption, rootPath)
+            .then(() => {
+              if (isActive()) {
+                Reflect.apply(value, target, runtimeArgs);
+                bindWorkbenchEChartsRuntimeInteractions(target, runtimeArgs[0] as EChartsOption);
+              }
+            })
+            .catch((error) => {
+              if (isActive()) onError(error);
+            });
+          return undefined;
+        }
+        return Reflect.apply(value, target, args);
+      };
+    },
+  }) as ECharts;
+}
+
+function createNoopChart(): ECharts {
+  return new Proxy({}, {
+    get() {
+      return () => undefined;
+    },
+  }) as ECharts;
+}
+
+function createNoopJQuery(): JQueryCompat {
+  const request = Promise.resolve(undefined) as JQueryCompatRequest;
+  request.done = () => request;
+  request.fail = () => request;
+  return {
+    get: () => request,
+    getJSON: () => request,
+  };
+}
+
+function runEchartsScript(script: string, rootPath: string | undefined, myChart: ECharts, jquery: JQueryCompat): EChartsOption | null {
+  const scope = {
+    option: undefined as EChartsOption | undefined,
+    echarts,
+    myChart,
+    $: jquery,
+    app: {} as EchartsScriptApp,
+    ROOT_PATH: normalizeRootPath(rootPath),
+    window,
+    document,
+    fetch: window.fetch.bind(window),
+    Math,
+    Date,
+    Array,
+    Object,
+    Number,
+    String,
+    Boolean,
+    JSON,
+    console,
+    setTimeout: window.setTimeout.bind(window),
+    clearTimeout: window.clearTimeout.bind(window),
+    setInterval: window.setInterval.bind(window),
+    clearInterval: window.clearInterval.bind(window),
+  };
+  const runner = Function(
+    'scope',
+    `
+      "use strict";
+      var option;
+      const echarts = scope.echarts;
+      const myChart = scope.myChart;
+      const $ = scope.$;
+      const app = scope.app;
+      const ROOT_PATH = scope.ROOT_PATH;
+      const window = scope.window;
+      const document = scope.document;
+      const fetch = scope.fetch;
+      const Math = scope.Math;
+      const Date = scope.Date;
+      const Array = scope.Array;
+      const Object = scope.Object;
+      const Number = scope.Number;
+      const String = scope.String;
+      const Boolean = scope.Boolean;
+      const JSON = scope.JSON;
+      const console = scope.console;
+      const setTimeout = scope.setTimeout;
+      const clearTimeout = scope.clearTimeout;
+      const setInterval = scope.setInterval;
+      const clearInterval = scope.clearInterval;
+      ${script}
+      return option;
+    `,
+  ) as (scope: EchartsScriptScope) => unknown;
+  const option = runner(scope);
+  if (!option) return null;
+  if (typeof option !== 'object' || Array.isArray(option)) throw new Error('ECharts 示例脚本没有生成 option 对象。');
+  const nextOption = option as EChartsOption;
+  if (optionUsesEchartsGl(nextOption) && !objectValue(nextOption, 'backgroundColor')) {
+    return removeRuntimeEchartsChrome({ backgroundColor: '#000', ...nextOption });
+  }
+  return removeRuntimeEchartsChrome(nextOption);
+}
+
+export function optionFromWorkbenchData(rendererKey: string, data: DisplayBlockData): EChartsOption | null {
+  assertRecord(data, 'DisplayBlockData');
+  const normalizedRendererKey = normalizeChartRendererKey(rendererKey || '');
+  const option = (() => {
+    if (data.shape === 'echartsOption' && objectValue(data, 'renderContract') === 'materializedPreview') {
+      return normalizeRuntimeEchartsOption(data.option as EChartsOption, data);
+    }
+    if (data.shape === 'echartsOption' && ['pie', 'donut'].includes(String(normalizedRendererKey)) && Array.isArray(objectValue(data, 'slices'))) {
+      return pieOption(data as unknown as PieSlicesData);
+    }
+    if (data.shape === 'echartsOption') return normalizeRuntimeEchartsOption(data.option as EChartsOption, data);
+    if (data.shape === 'echartsScript') {
+      return runEchartsScript(String(data.script), typeof data.rootPath === 'string' ? data.rootPath : undefined, createNoopChart(), createNoopJQuery());
+    }
+    if (data.shape === 'echartsDynamic') {
+      const dataBinding = objectValue(data, 'dataBinding');
+      const fieldMapping = objectValue(dataBinding, 'fieldMapping');
+      return buildDynamicEchartOption(objectValue(data, 'optionTemplate'), {
+        rows: [],
+        fieldMapping: normalizeDynamicEchartFieldMapping({
+          xField: objectValue(dataBinding, 'xField') ?? objectValue(fieldMapping, 'xField'),
+          yFields: objectValue(dataBinding, 'yFields') ?? objectValue(fieldMapping, 'yFields'),
+        }),
+      });
+    }
+    if (data.shape === 'singleSeries' || data.shape === 'multiSeries') return seriesOption(data, normalizedRendererKey);
+    if (data.shape === 'waterfallSteps') return waterfallOption(data);
+    if (data.shape === 'heatmapMatrix') return heatmapOption(data);
+    if (data.shape === 'pieSlices') return pieOption(data);
+    if (data.shape === 'radarMetrics') return radarOption(data);
+    if (data.shape === 'scatterPoints') return scatterOption(data);
+    if (data.shape === 'funnelStages') return funnelOption(data);
+    if (data.shape === 'gaugeMetric') return gaugeOption(data);
+    if (data.shape === 'mapRegions') return mapOption(data);
+    if (data.shape === 'sankeyFlow') return sankeyOption(data);
+    if (data.shape === 'treeHierarchy') return treeOption(data);
+    if (data.shape === 'ganttTasks') return ganttOption(data);
+    if (data.shape === 'candlestickSeries') return candlestickOption(data);
+    if (data.shape === 'boxplotSeries') return boxplotOption(data);
+    if (data.shape === 'paretoSeries') return paretoOption(data);
+    if (data.shape === 'networkGraph') return networkOption(data);
+    if (data.shape === 'geoGlobe') return geoGlobeOption(data);
+    if (['bar', 'line', 'mixedBarLine', 'area', 'stackedBar'].includes(String(normalizedRendererKey))) return seriesOption(data as MultiSeriesData, normalizedRendererKey);
+    return null;
+  })();
+  return option ? normalizeSharedWorkbenchChartDisplayDefaults(option) : null;
+}
+
+export async function prepareWorkbenchChartOption(data: DisplayBlockData, option: EChartsOption | null) {
+  if (dataRequiresEchartsGl(data, option)) await ensureEchartsGlLoaded();
+}
+
+export function chartNarrative(data: DisplayBlockData) {
+  return 'narrative' in data ? data.narrative : undefined;
+}
+
+export type WorkbenchEchartClickParams = {
+  componentType?: string;
+  seriesType?: string;
+  seriesName?: string;
+  name?: string | number;
+  value?: unknown;
+  data?: unknown;
+  dataIndex?: number;
+  event?: {
+    clientX?: number;
+    clientY?: number;
+    offsetX?: number;
+    offsetY?: number;
+  };
+};
+
+export function useEchart(
+  elementRef: Ref<HTMLElement | null>,
+  optionRef: Ref<EChartsOption | null>,
+  errorRef?: Ref<string>,
+  themeRef?: Ref<string | undefined>,
+  scriptRef?: Ref<EchartsScriptData | null>,
+  onChartClick?: (params: WorkbenchEchartClickParams) => void,
+) {
+  const chartRef = shallowRef<ECharts | null>(null);
+  const workbenchThemeVersion = shallowRef(0);
+  let resizeObserver: ResizeObserver | null = null;
+  let workbenchThemeObserver: MutationObserver | null = null;
+  let pendingFrame = 0;
+  let retryFrame = 0;
+  let windowResizeBound = false;
+  let mountId = 0;
+
+  /**
+   * 停止监听工作台主题根节点。
+   */
+  const stopWorkbenchThemeObserver = () => {
+    workbenchThemeObserver?.disconnect();
+    workbenchThemeObserver = null;
+  };
+
+  /**
+   * 开始监听宿主工作台主题切换，确保 CSS 变量变化后重绘图表。
+   * @param element - 当前图表容器。
+   */
+  const startWorkbenchThemeObserver = (element: HTMLElement | null) => {
+    stopWorkbenchThemeObserver();
+    if (!element || typeof MutationObserver === 'undefined') return;
+    const themeRoot = resolveWorkbenchChartThemeRoot(element);
+    if (!themeRoot) return;
+    workbenchThemeObserver = new MutationObserver(() => {
+      workbenchThemeVersion.value += 1;
+    });
+    workbenchThemeObserver.observe(themeRoot, {
+      attributes: true,
+      attributeFilter: ['data-workbench-style', 'data-dash-theme', 'style', 'class'],
+    });
+  };
+
+  const dispose = () => {
+    mountId += 1;
+    if (pendingFrame) window.cancelAnimationFrame(pendingFrame);
+    if (retryFrame) window.cancelAnimationFrame(retryFrame);
+    pendingFrame = 0;
+    retryFrame = 0;
+    if (windowResizeBound) {
+      window.removeEventListener('resize', resize);
+      windowResizeBound = false;
+    }
+    resizeObserver?.disconnect();
+    resizeObserver = null;
+    chartRef.value?.dispose();
+    chartRef.value = null;
+  };
+
+  const resize = () => {
+    const element = elementRef.value;
+    const chart = chartRef.value;
+    if (!element || !chart) return;
+    const { width, height } = element.getBoundingClientRect();
+    const nextWidth = Math.round(width);
+    const nextHeight = Math.round(height);
+    if (nextWidth <= 0 || nextHeight <= 0) return;
+    if (pendingFrame) window.cancelAnimationFrame(pendingFrame);
+    pendingFrame = window.requestAnimationFrame(() => {
+      pendingFrame = 0;
+      chart.resize({ width: nextWidth, height: nextHeight });
+    });
+  };
+
+  const mount = async () => {
+    await nextTick();
+    const currentMountId = mountId + 1;
+    mountId = currentMountId;
+    const element = elementRef.value;
+    const option = optionRef.value;
+    const scriptData = scriptRef?.value || null;
+    dispose();
+    mountId = currentMountId;
+    if (!element || (!option && !scriptData)) return;
+    const { width, height } = element.getBoundingClientRect();
+    if (width <= 0 || height <= 0) {
+      retryFrame = window.requestAnimationFrame(() => {
+        retryFrame = 0;
+        void mount();
+      });
+      return;
+    }
+    try {
+      const chart = echarts.init(element, themeRef?.value, {
+        renderer: 'canvas',
+        width: Math.round(width),
+        height: Math.round(height),
+      });
+      chartRef.value = chart;
+      if (onChartClick) {
+        chart.on('click', (params) => {
+          if (isWorkbenchHalfDonutPlaceholderData(params.data)) return;
+          const event = (params.event as { event?: MouseEvent; offsetX?: number; offsetY?: number } | undefined);
+          onChartClick({
+            componentType: typeof params.componentType === 'string' ? params.componentType : undefined,
+            seriesType: typeof params.seriesType === 'string' ? params.seriesType : undefined,
+            seriesName: typeof params.seriesName === 'string' ? params.seriesName : undefined,
+            name: typeof params.name === 'string' || typeof params.name === 'number' ? params.name : undefined,
+            value: params.value,
+            data: params.data,
+            dataIndex: typeof params.dataIndex === 'number' ? params.dataIndex : undefined,
+            event: {
+              clientX: event?.event?.clientX,
+              clientY: event?.event?.clientY,
+              offsetX: event?.offsetX,
+              offsetY: event?.offsetY,
+            },
+          });
+        });
+      }
+      resizeObserver = new ResizeObserver(resize);
+      resizeObserver.observe(element);
+      if (!windowResizeBound) {
+        window.addEventListener('resize', resize);
+        windowResizeBound = true;
+      }
+      const isActive = () => mountId === currentMountId && chartRef.value === chart;
+      if (option) {
+        const themedOption = applyWorkbenchChartThemeToOption(option, readWorkbenchChartThemeTokens(element));
+        const runtimeOption = prepareWorkbenchEChartsRuntimeOption(normalizeRuntimeMapNames(themedOption) as EChartsOption);
+        await ensureEchartsMapsForOption(runtimeOption, scriptData?.rootPath);
+        if (!isActive()) return;
+        chart.setOption(runtimeOption, true);
+        bindWorkbenchEChartsRuntimeInteractions(chart, runtimeOption);
+      }
+      if (scriptData) {
+        const onScriptError = (error: unknown) => {
+          errorRef && (errorRef.value = error instanceof Error ? error.message : 'ECharts 示例执行失败');
+        };
+        const scriptChart = createScopedChart(chart, scriptData.rootPath, isActive, onScriptError);
+        const jquery = createJQueryCompat(scriptData.rootPath || '', isActive, (error) => {
+          errorRef && (errorRef.value = error instanceof Error ? error.message : 'ECharts 示例资源加载失败');
+        });
+        const scriptOption = runEchartsScript(scriptData.script, scriptData.rootPath, scriptChart, jquery);
+        if (scriptOption && isActive()) {
+          const themedScriptOption = applyWorkbenchChartThemeToOption(scriptOption, readWorkbenchChartThemeTokens(element));
+          const runtimeScriptOption = prepareWorkbenchEChartsRuntimeOption(themedScriptOption);
+          await ensureEchartsMapsForOption(runtimeScriptOption, scriptData.rootPath);
+          if (isActive()) {
+            chart.setOption(runtimeScriptOption, true);
+            bindWorkbenchEChartsRuntimeInteractions(chart, runtimeScriptOption);
+          }
+        }
+      }
+      resize();
+      errorRef && (errorRef.value = '');
+    } catch (error) {
+      dispose();
+      errorRef && (errorRef.value = error instanceof Error ? error.message : '图表渲染失败');
+    }
+  };
+
+  watch(elementRef, (element) => {
+    startWorkbenchThemeObserver(element);
+  }, { immediate: true });
+
+  watch([elementRef, optionRef, themeRef || shallowRef(undefined), scriptRef || shallowRef(null), workbenchThemeVersion], () => {
+    void mount();
+  }, { immediate: true });
+
+  onBeforeUnmount(() => {
+    stopWorkbenchThemeObserver();
+    dispose();
+  });
+
+  return { chartRef, resize, dispose };
+}