@design.estate/dees-catalog 3.98.0 → 3.98.1

package/ts_web/elements/00group-chart/dees-chart-area/component.ts

@@ -10,6 +10,11 @@ import * as domtools from '@design.estate/dees-domtools';
 import { demoFunc } from './demo.js';
 import { chartAreaStyles } from './styles.js';
 import { renderChartArea } from './template.js';
+import {
+  haveSameSeriesLayout,
+  planRealtimeChartUpdates,
+  type IRealtimeChartPoint,
+} from './realtime-updates.js';
 import { getEchartsSeriesColors, hexToRgba } from '../dees-chart-echarts-theme.js';
 
 import type { IChartApi, ISeriesApi, UTCTimestamp, MouseEventParams } from 'lightweight-charts';
@@ -101,22 +106,44 @@ export class DeesChartArea extends DeesElement {
   private seriesApis: Map<string, ISeriesApi<any>> = new Map();
   private priceLines: Map<string, any[]> = new Map();
   private tooltipEl: HTMLDivElement | null = null;
+  private crosshairActive = false;
+  private pendingRealtimePrune = false;
+  private crosshairMoveHandler: ((param: MouseEventParams) => void) | null = null;
+  private chartContainer: HTMLDivElement | null = null;
+  private readonly chartMouseLeaveHandler = () => {
+    this.chart?.clearCrosshairPosition();
+    this.handleCrosshairCleared();
+  };
 
   constructor() {
     super();
     domtools.elementBasic.setup();
     this.registerGarbageFunction(async () => {
       this.stopAutoScroll();
-      if (this.chart) {
+      const chart = this.chart;
+      const crosshairMoveHandler = this.crosshairMoveHandler;
+      this.chart = null;
+      this.crosshairMoveHandler = null;
+      this.chartContainer?.removeEventListener('mouseleave', this.chartMouseLeaveHandler);
+      this.chartContainer = null;
+      this.tooltipEl = null;
+      this.crosshairActive = false;
+      this.pendingRealtimePrune = false;
+      if (crosshairMoveHandler && chart) {
         try {
-          this.chart.remove();
-          this.chart = null;
-          this.seriesApis.clear();
-          this.priceLines.clear();
-        } catch (e) {
-          console.error('Error destroying chart:', e);
+          chart.unsubscribeCrosshairMove(crosshairMoveHandler);
+        } catch (error) {
+          console.error('Error unsubscribing chart crosshair:', error);
         }
       }
+      try {
+        chart?.remove();
+      } catch (error) {
+        console.error('Error destroying chart:', error);
+      } finally {
+        this.seriesApis.clear();
+        this.priceLines.clear();
+      }
     });
   }
 
@@ -129,14 +156,48 @@ export class DeesChartArea extends DeesElement {
   // --- Helpers ---
 
   private convertDataToLC(data: Array<{ x: any; y: number }>): Array<{ time: UTCTimestamp; value: number }> {
-    return data
-      .map(point => {
-        const ms = typeof point.x === 'number' ? point.x : new Date(point.x).getTime();
-        return { time: Math.floor(ms / 1000) as UTCTimestamp, value: point.y };
-      })
+    const pointsByTime = new Map<number, { time: UTCTimestamp; value: number }>();
+    for (const point of data) {
+      const ms = typeof point.x === 'number' ? point.x : new Date(point.x).getTime();
+      const time = Math.floor(ms / 1000);
+      if (!Number.isFinite(time) || !Number.isFinite(point.y)) continue;
+      // Lightweight Charts requires unique ordered timestamps. The latest
+      // sample wins when multiple updates land in the same second.
+      pointsByTime.set(time, { time: time as UTCTimestamp, value: point.y });
+    }
+    return [...pointsByTime.values()]
       .sort((a, b) => (a.time as number) - (b.time as number));
   }
 
+  private getSeriesName(series: ChartSeriesConfig[number], index: number): string {
+    return series.name || `series-${index}`;
+  }
+
+  private getSeriesKey(series: ChartSeriesConfig[number], index: number): string {
+    return `${index}:${this.getSeriesName(series, index)}`;
+  }
+
+  private getCanonicalChartSeries(chartSeries: ChartSeriesConfig): ChartSeriesConfig {
+    const cutoffTime = Date.now() - this.rollingWindow;
+    return chartSeries.map((series) => ({
+      ...series,
+      data: this.convertDataToLC(series.data.filter((point) => {
+        if (!this.realtimeMode || this.rollingWindow <= 0) return true;
+        const ms = typeof point.x === 'number' ? point.x : new Date(point.x).getTime();
+        return ms > cutoffTime;
+      })).map((point) => ({
+        x: (point.time as number) * 1000,
+        y: point.value,
+      })),
+    }));
+  }
+
+  private getRenderedSeriesData(api: ISeriesApi<any>): IRealtimeChartPoint[] {
+    return api.data()
+      .filter((point): point is { time: UTCTimestamp; value: number } => 'value' in point)
+      .map((point) => ({ time: point.time as number, value: point.value }));
+  }
+
   private colorToRgba(color: string, alpha: number): string {
     if (/^#[0-9a-fA-F]{6}$/.test(color)) {
       return hexToRgba(color, alpha);
@@ -238,7 +299,7 @@ export class DeesChartArea extends DeesElement {
       });
 
       api.setData(this.convertDataToLC(s.data));
-      this.updatePriceLines(s.name || `series-${index}`, api, s.data, color);
+      this.updatePriceLines(this.getSeriesKey(s, index), api, s.data, color);
 
       if (this.yAxisScaling !== 'dynamic') {
         api.applyOptions({
@@ -248,17 +309,77 @@ export class DeesChartArea extends DeesElement {
         } as any);
       }
 
-      this.seriesApis.set(s.name || `series-${index}`, api);
+      this.seriesApis.set(this.getSeriesKey(s, index), api);
     });
     this.computeStats(chartSeries);
+    this.pendingRealtimePrune = false;
 
-    // Without an explicit rolling window the visible range is never set elsewhere,
-    // leaving lightweight-charts' default zoom (data squeezed to the right edge).
-    if (this.rollingWindow <= 0) {
+    if (this.realtimeMode && this.rollingWindow > 0) {
+      void this.updateTimeWindow();
+    } else {
       this.chart.timeScale().fitContent();
     }
   }
 
+  private updateSeriesPresentation(chartSeries: ChartSeriesConfig) {
+    const isDark = !this.goBright;
+    chartSeries.forEach((series, index) => {
+      const seriesKey = this.getSeriesKey(series, index);
+      const api = this.seriesApis.get(seriesKey);
+      if (!api) return;
+      const color = this.resolveSeriesColor(series, index, isDark);
+      api.applyOptions({
+        topColor: this.colorToRgba(color, isDark ? 0.4 : 0.5),
+        bottomColor: this.colorToRgba(color, 0),
+        lineColor: color,
+      });
+      this.updatePriceLines(seriesKey, api, series.data, color);
+    });
+    this.computeStats(chartSeries);
+
+    if (this.yAxisScaling === 'dynamic') {
+      const allValues = chartSeries.flatMap((series) => series.data.map((point) => point.y));
+      if (allValues.length > 0) {
+        const dynamicMax = Math.ceil(Math.max(...allValues) * 1.1);
+        for (const [, api] of this.seriesApis) {
+          api.applyOptions({
+            autoscaleInfoProvider: () => ({ priceRange: { minValue: 0, maxValue: dynamicMax } }),
+          } as any);
+        }
+      }
+    }
+  }
+
+  private handleCrosshairCleared() {
+    this.crosshairActive = false;
+    if (this.tooltipEl) this.tooltipEl.style.display = 'none';
+    this.flushPendingRealtimePrune();
+  }
+
+  private clearCrosshairForDataReplacement() {
+    this.pendingRealtimePrune = false;
+    this.chart?.clearCrosshairPosition();
+    this.crosshairActive = false;
+    if (this.tooltipEl) this.tooltipEl.style.display = 'none';
+  }
+
+  private flushPendingRealtimePrune() {
+    if (
+      !this.pendingRealtimePrune
+      || this.crosshairActive
+      || !this.chart
+      || !this.realtimeMode
+      || this.rollingWindow <= 0
+    ) return;
+
+    const canonicalSeries = this.getCanonicalChartSeries(this.internalChartData);
+    canonicalSeries.forEach((series, index) => {
+      const api = this.seriesApis.get(this.getSeriesKey(series, index));
+      if (api) api.setData(this.convertDataToLC(series.data));
+    });
+    this.pendingRealtimePrune = false;
+  }
+
   private computeStats(chartSeries: ChartSeriesConfig) {
     const isDark = !this.goBright;
     this.seriesStats = chartSeries.map((s, index) => {
@@ -327,15 +448,18 @@ export class DeesChartArea extends DeesElement {
     this.tooltipEl = document.createElement('div');
     this.tooltipEl.className = 'lw-tooltip';
     this.tooltipEl.style.display = 'none';
-    this.shadowRoot!.querySelector('.chartContainer')?.appendChild(this.tooltipEl);
+    this.chartContainer = this.shadowRoot!.querySelector('.chartContainer') as HTMLDivElement | null;
+    this.chartContainer?.appendChild(this.tooltipEl);
+    this.chartContainer?.addEventListener('mouseleave', this.chartMouseLeaveHandler);
 
-    this.chart.subscribeCrosshairMove((param: MouseEventParams) => {
+    this.crosshairMoveHandler = (param: MouseEventParams) => {
       if (!this.tooltipEl) return;
 
-      if (!param.point || !param.time || param.point.x < 0 || param.point.y < 0) {
-        this.tooltipEl.style.display = 'none';
+      if (!param.point || param.time === undefined || param.point.x < 0 || param.point.y < 0) {
+        this.handleCrosshairCleared();
         return;
       }
+      this.crosshairActive = true;
 
       const isDark = !this.goBright;
       const bgColor = isDark ? 'hsl(0 0% 9%)' : 'hsl(0 0% 100%)';
@@ -345,11 +469,13 @@ export class DeesChartArea extends DeesElement {
       let html = '';
       let idx = 0;
       let hasData = false;
-      for (const [name, api] of this.seriesApis) {
+      for (const api of this.seriesApis.values()) {
         const data = param.seriesData.get(api);
         if (data && 'value' in data && (data as any).value !== undefined) {
           hasData = true;
-          const color = this.resolveSeriesColor(this.chartSeries[idx], idx, isDark);
+          const series = this.internalChartData[idx];
+          const name = series ? this.getSeriesName(series, idx) : `series-${idx}`;
+          const color = this.resolveSeriesColor(series, idx, isDark);
           const formatted = this.yAxisFormatter((data as any).value);
           html += `<div style="display:flex;align-items:center;gap:8px;margin:${idx > 0 ? '6px' : '0'} 0;">
             <span style="display:inline-block;width:10px;height:10px;background:${color};border-radius:2px;"></span>
@@ -378,15 +504,19 @@ export class DeesChartArea extends DeesElement {
       if (left + 200 > containerWidth) left = param.point.x - 216;
       this.tooltipEl.style.left = `${left}px`;
       this.tooltipEl.style.top = `${param.point.y - 16}px`;
-    });
+    };
+    this.chart.subscribeCrosshairMove(this.crosshairMoveHandler);
   }
 
   // --- Lifecycle ---
 
   public async firstUpdated() {
     await this.domtoolsPromise;
+    if (!this.isConnected) return;
     this.lcBundle = await DeesServiceLibLoader.getInstance().loadLightweightCharts();
+    if (!this.isConnected) return;
     await new Promise(resolve => requestAnimationFrame(resolve));
+    if (!this.isConnected) return;
 
     const chartContainer = this.shadowRoot!.querySelector('.chartContainer') as HTMLDivElement;
     if (!chartContainer) return;
@@ -446,9 +576,11 @@ export class DeesChartArea extends DeesElement {
         },
       ];
 
-      this.internalChartData = chartSeries;
-      this.recreateSeries(chartSeries);
+      const canonicalSeries = this.getCanonicalChartSeries(chartSeries);
+      this.internalChartData = canonicalSeries;
+      this.recreateSeries(canonicalSeries);
       this.setupTooltip();
+      this.syncAutoScroll();
     } catch (error) {
       console.error('Failed to initialize chart:', error);
     }
@@ -461,7 +593,8 @@ export class DeesChartArea extends DeesElement {
       this.applyTheme();
     }
 
-    if (changedProperties.has('series') && this.chart && this.series.length > 0) {
+    const seriesChanged = changedProperties.has('series') && this.series.length > 0;
+    if (seriesChanged && this.chart) {
       await this.updateSeries(this.series);
     }
 
@@ -469,19 +602,22 @@ export class DeesChartArea extends DeesElement {
       // yAxisFormatter is used by the tooltip; LC price scale uses default formatting
     }
 
-    if (changedProperties.has('realtimeMode') && this.chart) {
-      if (this.realtimeMode && this.rollingWindow > 0 && this.autoScrollInterval > 0) {
-        this.startAutoScroll();
+    const realtimeConfigurationChanged = changedProperties.has('realtimeMode')
+      || changedProperties.has('rollingWindow');
+    const autoScrollConfigurationChanged = realtimeConfigurationChanged
+      || changedProperties.has('autoScrollInterval');
+    if (this.chart && realtimeConfigurationChanged) {
+      if (!seriesChanged && this.internalChartData.length > 0) {
+        await this.updateSeries(this.internalChartData);
+      }
+      if (this.realtimeMode && this.rollingWindow > 0) {
+        await this.updateTimeWindow();
       } else {
-        this.stopAutoScroll();
+        this.chart.timeScale().fitContent();
       }
     }
-
-    if (changedProperties.has('autoScrollInterval') && this.chart) {
-      this.stopAutoScroll();
-      if (this.realtimeMode && this.rollingWindow > 0 && this.autoScrollInterval > 0) {
-        this.startAutoScroll();
-      }
+    if (this.chart && autoScrollConfigurationChanged) {
+      this.syncAutoScroll();
     }
 
     if (changedProperties.has('chartLines') && this.chart) {
@@ -507,80 +643,84 @@ export class DeesChartArea extends DeesElement {
     if (!this.chart) return;
 
     try {
-      this.internalChartData = newSeries;
-
-      if (this.rollingWindow > 0 && this.realtimeMode) {
-        const now = Date.now();
-        const cutoffTime = now - this.rollingWindow;
+      void animate;
+      const canonicalSeries = this.getCanonicalChartSeries(newSeries);
+      this.internalChartData = canonicalSeries;
+      const renderedKeys = [...this.seriesApis.keys()];
+      const canonicalKeys = canonicalSeries.map((series, index) => this.getSeriesKey(series, index));
+
+      if (!haveSameSeriesLayout(renderedKeys, canonicalKeys)) {
+        this.clearCrosshairForDataReplacement();
+        this.recreateSeries(canonicalSeries);
+        this.updateSeriesPresentation(canonicalSeries);
+        return;
+      }
 
-        if (newSeries.length !== this.seriesApis.size) {
-          this.recreateSeries(newSeries);
-        } else {
-          const isDark = !this.goBright;
-          newSeries.forEach((s, index) => {
-            const name = s.name || `series-${index}`;
-            const api = this.seriesApis.get(name);
-            if (!api) return;
-            const filtered = s.data.filter(point => {
-              const ms = typeof point.x === 'number' ? point.x : new Date(point.x).getTime();
-              return ms > cutoffTime;
-            });
-            api.setData(this.convertDataToLC(filtered));
-            const color = this.resolveSeriesColor(s, index, isDark);
-            api.applyOptions({
-              topColor: this.colorToRgba(color, isDark ? 0.4 : 0.5),
-              bottomColor: this.colorToRgba(color, 0),
-              lineColor: color,
-            });
-            this.updatePriceLines(name, api, filtered, color);
-          });
-          this.computeStats(newSeries);
-        }
+      if (!this.realtimeMode || this.rollingWindow <= 0) {
+        this.clearCrosshairForDataReplacement();
+        canonicalSeries.forEach((series, index) => {
+          this.seriesApis.get(this.getSeriesKey(series, index))!
+            .setData(this.convertDataToLC(series.data));
+        });
+        this.pendingRealtimePrune = false;
+        this.updateSeriesPresentation(canonicalSeries);
+        return;
+      }
 
-        try {
-          this.chart.timeScale().setVisibleRange({
-            from: Math.floor(cutoffTime / 1000) as UTCTimestamp,
-            to: Math.floor(now / 1000) as UTCTimestamp,
-          });
-        } catch (e) { /* range may be invalid */ }
+      const plannedUpdates = canonicalSeries.map((series, index) => {
+        const api = this.seriesApis.get(this.getSeriesKey(series, index))!;
+        const canonicalData = this.convertDataToLC(series.data)
+          .map((point) => ({ time: point.time as number, value: point.value }));
+        return {
+          api,
+          canonicalData,
+          plan: planRealtimeChartUpdates(this.getRenderedSeriesData(api), canonicalData),
+        };
+      });
 
-        if (this.yAxisScaling === 'dynamic') {
-          const allValues = newSeries.flatMap(s =>
-            s.data.filter(p => {
-              const ms = typeof p.x === 'number' ? p.x : new Date(p.x).getTime();
-              return ms > cutoffTime;
-            }).map(d => d.y)
-          );
-          if (allValues.length > 0) {
-            const dynamicMax = Math.ceil(Math.max(...allValues) * 1.1);
-            for (const [, api] of this.seriesApis) {
-              api.applyOptions({
-                autoscaleInfoProvider: () => ({ priceRange: { minValue: 0, maxValue: dynamicMax } }),
-              } as any);
-            }
-          }
+      if (plannedUpdates.some(({ plan }) => plan.replacementRequired)) {
+        this.clearCrosshairForDataReplacement();
+        for (const { api, canonicalData } of plannedUpdates) {
+          api.setData(canonicalData.map((point) => ({
+            time: point.time as UTCTimestamp,
+            value: point.value,
+          })));
         }
+        this.pendingRealtimePrune = false;
       } else {
-        if (newSeries.length !== this.seriesApis.size) {
-          this.recreateSeries(newSeries);
-        } else {
-          const isDark = !this.goBright;
-          newSeries.forEach((s, index) => {
-            const name = s.name || `series-${index}`;
-            const api = this.seriesApis.get(name);
-            if (!api) return;
-            api.setData(this.convertDataToLC(s.data));
-            const color = this.resolveSeriesColor(s, index, isDark);
-            api.applyOptions({
-              topColor: this.colorToRgba(color, isDark ? 0.4 : 0.5),
-              bottomColor: this.colorToRgba(color, 0),
-              lineColor: color,
-            });
-            this.updatePriceLines(name, api, s.data, color);
-          });
-          this.computeStats(newSeries);
+        for (const { api, plan } of plannedUpdates) {
+          for (const update of plan.updates) {
+            api.update({
+              time: update.point.time as UTCTimestamp,
+              value: update.point.value,
+            }, update.historicalUpdate);
+          }
+        }
+
+        const pruneRequired = plannedUpdates.some(({ plan }) => plan.pruneRequired);
+        const pruneRecommended = plannedUpdates.some(({ plan }) => plan.pruneRecommended);
+        if (pruneRequired) {
+          this.clearCrosshairForDataReplacement();
+          for (const { api, canonicalData } of plannedUpdates) {
+            api.setData(canonicalData.map((point) => ({
+              time: point.time as UTCTimestamp,
+              value: point.value,
+            })));
+          }
+        } else if (pruneRecommended && this.crosshairActive) {
+          this.pendingRealtimePrune = true;
+        } else if (pruneRecommended) {
+          for (const { api, canonicalData } of plannedUpdates) {
+            api.setData(canonicalData.map((point) => ({
+              time: point.time as UTCTimestamp,
+              value: point.value,
+            })));
+          }
+          this.pendingRealtimePrune = false;
         }
       }
+
+      this.updateSeriesPresentation(canonicalSeries);
     } catch (error) {
       console.error('Failed to update chart series:', error);
     }
@@ -600,15 +740,28 @@ export class DeesChartArea extends DeesElement {
 
   public async appendData(newData: { name?: string; data: Array<{ x: any; y: number }> }[]) {
     if (!this.chart) return;
+    const nextSeries = this.internalChartData.map((series) => ({
+      ...series,
+      data: [...series.data],
+    }));
+    const namedOccurrences = new Map<string, number>();
     newData.forEach((s, index) => {
-      const name = s.name || `series-${index}`;
-      const api = this.seriesApis.get(name);
-      if (!api || s.data.length === 0) return;
-      for (const point of s.data) {
-        const lcPoints = this.convertDataToLC([point]);
-        if (lcPoints.length > 0) api.update(lcPoints[0]);
+      let targetIndex = index;
+      if (s.name) {
+        const occurrence = namedOccurrences.get(s.name) ?? 0;
+        namedOccurrences.set(s.name, occurrence + 1);
+        const matchingIndices = this.internalChartData
+          .map((series, seriesIndex) => series.name === s.name ? seriesIndex : -1)
+          .filter((seriesIndex) => seriesIndex >= 0);
+        const matchingIndex = matchingIndices[occurrence];
+        if (matchingIndex === undefined) return;
+        targetIndex = matchingIndex;
       }
+      const targetSeries = nextSeries[targetIndex];
+      if (!targetSeries || s.data.length === 0) return;
+      targetSeries.data.push(...s.data);
     });
+    await this.updateSeries(nextSeries);
   }
 
   public async updateOptions(options: Record<string, any>) {
@@ -653,25 +806,32 @@ export class DeesChartArea extends DeesElement {
 
   private refreshPriceLines() {
     const isDark = !this.goBright;
-    this.chartSeries.forEach((s, index) => {
-      const name = s.name || `series-${index}`;
-      const api = this.seriesApis.get(name);
+    this.getCanonicalChartSeries(this.internalChartData).forEach((s, index) => {
+      const seriesKey = this.getSeriesKey(s, index);
+      const api = this.seriesApis.get(seriesKey);
       if (!api) return;
-      this.updatePriceLines(name, api, s.data, this.resolveSeriesColor(s, index, isDark));
+      this.updatePriceLines(seriesKey, api, s.data, this.resolveSeriesColor(s, index, isDark));
     });
   }
 
   private startAutoScroll() {
-    if (this.autoScrollTimer) return;
+    if (this.autoScrollTimer !== null) return;
     this.autoScrollTimer = window.setInterval(() => {
       this.updateTimeWindow();
     }, this.autoScrollInterval);
   }
 
   private stopAutoScroll() {
-    if (this.autoScrollTimer) {
+    if (this.autoScrollTimer !== null) {
       window.clearInterval(this.autoScrollTimer);
       this.autoScrollTimer = null;
     }
   }
+
+  private syncAutoScroll() {
+    this.stopAutoScroll();
+    if (this.realtimeMode && this.rollingWindow > 0 && this.autoScrollInterval > 0) {
+      this.startAutoScroll();
+    }
+  }
 }

package/ts_web/elements/00group-chart/dees-chart-area/realtime-updates.ts

@@ -0,0 +1,110 @@
+export interface IRealtimeChartPoint {
+  time: number;
+  value: number;
+}
+
+export interface IRealtimeChartUpdate {
+  point: IRealtimeChartPoint;
+  historicalUpdate: boolean;
+}
+
+export interface IRealtimeChartUpdatePlan {
+  replacementRequired: boolean;
+  updates: IRealtimeChartUpdate[];
+  pruneRecommended: boolean;
+  pruneRequired: boolean;
+}
+
+/**
+ * Lightweight Charts can update the newest point or append newer points with
+ * update(). Historical update() calls may only target timestamps that already
+ * exist. Everything else needs an exact setData() replacement.
+ */
+export const planRealtimeChartUpdates = (
+  renderedData: readonly IRealtimeChartPoint[],
+  canonicalData: readonly IRealtimeChartPoint[],
+): IRealtimeChartUpdatePlan => {
+  if (canonicalData.length === 0) {
+    return {
+      replacementRequired: renderedData.length !== 0,
+      updates: [],
+      pruneRecommended: false,
+      pruneRequired: false,
+    };
+  }
+  if (renderedData.length === 0) {
+    return {
+      replacementRequired: false,
+      updates: canonicalData.map((point) => ({ point, historicalUpdate: false })),
+      pruneRecommended: false,
+      pruneRequired: false,
+    };
+  }
+
+  const renderedByTime = new Map(renderedData.map((point) => [point.time, point]));
+  const canonicalByTime = new Map(canonicalData.map((point) => [point.time, point]));
+  const canonicalStart = canonicalData[0].time;
+  const renderedLastTime = renderedData[renderedData.length - 1].time;
+
+  // Points before canonicalStart are an expired rolling-window prefix and may
+  // stay hidden temporarily. Missing points anywhere else are structural
+  // deletions (including suffix deletion) and require an exact replacement.
+  const hasStructuralDeletion = renderedData.some(
+    (point) => point.time >= canonicalStart && !canonicalByTime.has(point.time),
+  );
+  if (hasStructuralDeletion) {
+    return {
+      replacementRequired: true,
+      updates: [],
+      pruneRecommended: false,
+      pruneRequired: false,
+    };
+  }
+
+  const updates: IRealtimeChartUpdate[] = [];
+  for (const canonicalPoint of canonicalData) {
+    const renderedPoint = renderedByTime.get(canonicalPoint.time);
+    if (!renderedPoint) {
+      if (canonicalPoint.time < renderedLastTime) {
+        // Historical update() cannot insert a missing timestamp.
+        return {
+          replacementRequired: true,
+          updates: [],
+          pruneRecommended: false,
+          pruneRequired: false,
+        };
+      }
+      updates.push({ point: canonicalPoint, historicalUpdate: false });
+      continue;
+    }
+
+    if (renderedPoint.value !== canonicalPoint.value) {
+      updates.push({
+        point: canonicalPoint,
+        historicalUpdate: canonicalPoint.time < renderedLastTime,
+      });
+    }
+  }
+
+  const firstCanonicalPointIndex = renderedData.findIndex((point) => point.time >= canonicalStart);
+  const retainedPrefixLength = firstCanonicalPointIndex === -1
+    ? renderedData.length
+    : firstCanonicalPointIndex;
+  const projectedLength = renderedData.length
+    + updates.filter((update) => !renderedByTime.has(update.point.time)).length;
+  // Retain at most one additional hidden rolling window before compacting.
+  const retentionLimit = Math.max(canonicalData.length * 2, 2);
+  const pruneRecommended = retainedPrefixLength > 0 && projectedLength > retentionLimit;
+  // Hover may defer a recommended compaction to preserve the active crosshair,
+  // but never beyond two additional hidden windows.
+  const hardRetentionLimit = Math.max(canonicalData.length * 3, 3);
+  const pruneRequired = retainedPrefixLength > 0 && projectedLength > hardRetentionLimit;
+
+  return { replacementRequired: false, updates, pruneRecommended, pruneRequired };
+};
+
+export const haveSameSeriesLayout = (
+  renderedNames: readonly string[],
+  canonicalNames: readonly string[],
+): boolean => renderedNames.length === canonicalNames.length
+  && renderedNames.every((name, index) => name === canonicalNames[index]);