fix(report): stabilize record timeline scaling (#2724)

* fix(report): stabilize record timeline scaling

* fix(report): address timeline scale review feedback

Author: EAGzzyCSL

apps/report/src/components/timeline/index.tsx

@@ -5,6 +5,11 @@ import type { ExecutionTask } from '@midscene/core';
 import { useTheme } from '@midscene/visualizer';
 import { useAllCurrentTasks, useExecutionDump } from '../store';
 import { buildTimelineScreenshots } from './build-timeline-screenshots';
+import {
+  DEFAULT_TIMELINE_MAX_TIME_MS,
+  createTimelineScale,
+  formatTimelineTime,
+} from './timeline-scale';
 
 interface TimelineItem {
   id: string;
@@ -65,7 +70,7 @@ const TimelineWidget = (props: {
   const { isDarkMode } = useTheme();
 
   const allScreenshots = props.screenshots || [];
-  let maxTime = 500;
+  let maxTime = DEFAULT_TIMELINE_MAX_TIME_MS;
   if (allScreenshots.length >= 2) {
     maxTime = Math.max(
       allScreenshots[allScreenshots.length - 1].timeOffset,
@@ -125,30 +130,12 @@ const TimelineWidget = (props: {
     const { clientWidth } = domRef.current;
     const canvasWidth = clientWidth * sizeRatio;
     const canvasHeight = BASE_HEIGHT * sizeRatio;
-
-    // Grid calculations
-    let singleGridWidth = 100 * sizeRatio;
-    let gridCount = Math.floor(canvasWidth / singleGridWidth);
-    const stepCandidate = [
-      50, 100, 200, 300, 500, 1000, 2000, 3000, 5000, 6000, 8000, 9000, 10000,
-      20000, 30000, 40000, 60000, 90000, 12000, 300000,
-    ];
-    let timeStep = stepCandidate[0];
-    for (let i = stepCandidate.length - 1; i >= 0; i--) {
-      if (gridCount * stepCandidate[i] >= maxTime) {
-        timeStep = stepCandidate[i];
-      }
-    }
-    const gridRatio = maxTime / (gridCount * timeStep);
-    if (gridRatio <= 0.8) {
-      singleGridWidth = Math.floor(singleGridWidth * (1 / gridRatio) * 0.9);
-      gridCount = Math.floor(canvasWidth / singleGridWidth);
-    }
-
-    const leftForTimeOffset = (t: number) =>
-      Math.floor((singleGridWidth * t) / timeStep);
-    const timeOffsetForLeft = (l: number) =>
-      Math.floor((l * timeStep) / singleGridWidth);
+    const { timeStep, visibleMaxTime, leftForTimeOffset, timeOffsetForLeft } =
+      createTimelineScale({
+        canvasWidth,
+        maxTime,
+        sizeRatio,
+      });
 
     // Create canvas
     const canvas = document.createElement('canvas');
@@ -162,11 +149,6 @@ const TimelineWidget = (props: {
     const screenshotMaxHeight =
       canvasHeight - screenshotTop - commonPadding * 1.5;
 
-    const formatTime = (num: number) => {
-      const s = num / 1000;
-      return s % 1 === 0 ? `${s}s` : `${s.toFixed(1)}s`;
-    };
-
     // Viewport-aware lazy loading: downsample by pixel position, then load rest
     const { imgCache } = stateRef.current;
     let isMounted = true;
@@ -266,12 +248,12 @@ const TimelineWidget = (props: {
 
       // Grid lines + time labels
       ctx.font = `${timeContentFontSize}px sans-serif`;
-      for (let i = 1; i <= gridCount; i++) {
-        const x = leftForTimeOffset(i * timeStep);
+      for (let tickMs = timeStep; tickMs < visibleMaxTime; tickMs += timeStep) {
+        const x = leftForTimeOffset(tickMs);
         ctx.fillStyle = hexToCSS(gridLineColor);
         ctx.fillRect(x, 0, sizeRatio, canvasHeight);
 
-        const label = formatTime(i * timeStep);
+        const label = formatTimelineTime(tickMs);
         const tw = ctx.measureText(label).width;
         ctx.fillStyle = hexToCSS(gridTextColor);
         ctx.fillText(
@@ -354,7 +336,7 @@ const TimelineWidget = (props: {
         }
 
         // Time label at cursor
-        const label = formatTime(timeOffsetForLeft(hoverX));
+        const label = formatTimelineTime(timeOffsetForLeft(hoverX));
         const tw = ctx.measureText(label).width;
         ctx.fillStyle = hexToCSS(titleBg);
         ctx.fillRect(hoverX + 5, timeTextTop, tw + 10, timeContentFontSize + 4);

apps/report/src/components/timeline/timeline-scale.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createTimelineScale,
+  formatTimelineTime,
+  pickNiceStep,
+} from './timeline-scale';
+
+describe('formatTimelineTime', () => {
+  it('uses milliseconds for values below one second', () => {
+    expect(formatTimelineTime(50)).toBe('50ms');
+    expect(formatTimelineTime(100)).toBe('100ms');
+    expect(formatTimelineTime(500)).toBe('500ms');
+    expect(formatTimelineTime(999)).toBe('999ms');
+  });
+
+  it('uses seconds for values at or above one second', () => {
+    expect(formatTimelineTime(1000)).toBe('1s');
+    expect(formatTimelineTime(1500)).toBe('1.5s');
+    expect(formatTimelineTime(300000)).toBe('300s');
+  });
+});
+
+describe('pickNiceStep', () => {
+  it('rounds rough steps up to readable values', () => {
+    expect(pickNiceStep(0.2)).toBe(1);
+    expect(pickNiceStep(73)).toBe(100);
+    expect(pickNiceStep(420)).toBe(500);
+    expect(pickNiceStep(1700)).toBe(2000);
+    expect(pickNiceStep(12000)).toBe(20000);
+    expect(pickNiceStep(173000)).toBe(200000);
+    expect(pickNiceStep(610000)).toBe(1000000);
+  });
+
+  it('falls back for invalid rough steps', () => {
+    expect(pickNiceStep(0)).toBe(1000);
+    expect(pickNiceStep(Number.NaN)).toBe(1000);
+    expect(pickNiceStep(Number.POSITIVE_INFINITY)).toBe(1000);
+  });
+});
+
+describe('createTimelineScale', () => {
+  it('pads the visible range so the last screenshot stays inside the canvas', () => {
+    const scale = createTimelineScale({
+      canvasWidth: 1000,
+      maxTime: 1_733_653,
+      sizeRatio: 2,
+    });
+
+    expect(scale.leftForTimeOffset(0)).toBe(0);
+    expect(scale.timeStep).toBe(500_000);
+    expect(scale.visibleMaxTime).toBe(2_000_000);
+    expect(scale.leftForTimeOffset(1_733_653)).toBeLessThan(1000);
+    expect(scale.leftForTimeOffset(scale.visibleMaxTime)).toBe(1000);
+    expect(scale.timeOffsetForLeft(1000)).toBe(2_000_000);
+  });
+
+  it('keeps long narrow timelines on a readable step instead of falling back to 50ms', () => {
+    const scale = createTimelineScale({
+      canvasWidth: 1000,
+      maxTime: 1_733_653,
+      sizeRatio: 2,
+    });
+
+    expect(scale.timeStep).toBe(500_000);
+    expect(scale.visibleMaxTime).toBe(2_000_000);
+  });
+
+  it('uses the canvas scale for positions independently from the nice tick step', () => {
+    const scale = createTimelineScale({
+      canvasWidth: 2000,
+      maxTime: 1000,
+      sizeRatio: 2,
+    });
+
+    expect(scale.timeStep).toBe(100);
+    expect(scale.leftForTimeOffset(250)).toBe(500);
+    expect(scale.leftForTimeOffset(500)).toBe(1000);
+  });
+
+  it('uses size ratio when choosing the readable tick step', () => {
+    const lowDensityScale = createTimelineScale({
+      canvasWidth: 1000,
+      maxTime: 1000,
+      sizeRatio: 1,
+    });
+    const highDensityScale = createTimelineScale({
+      canvasWidth: 1000,
+      maxTime: 1000,
+      sizeRatio: 2,
+    });
+
+    expect(lowDensityScale.timeStep).toBe(100);
+    expect(highDensityScale.timeStep).toBe(200);
+    expect(lowDensityScale.leftForTimeOffset(500)).toBe(500);
+    expect(highDensityScale.leftForTimeOffset(500)).toBe(500);
+  });
+});

apps/report/src/components/timeline/timeline-scale.ts

@@ -0,0 +1,68 @@
+const NICE_STEP_FACTORS = [1, 2, 3, 5, 10] as const;
+
+export const DEFAULT_TIMELINE_MAX_TIME_MS = 500;
+export const DESIRED_GRID_WIDTH_PX = 100;
+export const DEFAULT_TIME_STEP_MS = 1000;
+
+export interface TimelineScale {
+  pxPerMs: number;
+  timeStep: number;
+  visibleMaxTime: number;
+  leftForTimeOffset: (timeOffset: number) => number;
+  timeOffsetForLeft: (left: number) => number;
+}
+
+export const formatTimelineTime = (timeMs: number): string => {
+  if (Math.abs(timeMs) < 1000) {
+    return `${Math.round(timeMs)}ms`;
+  }
+
+  const seconds = timeMs / 1000;
+  return seconds % 1 === 0 ? `${seconds}s` : `${seconds.toFixed(1)}s`;
+};
+
+export const pickNiceStep = (roughStepMs: number): number => {
+  if (!Number.isFinite(roughStepMs) || roughStepMs <= 0) {
+    return DEFAULT_TIME_STEP_MS;
+  }
+
+  const magnitude = 10 ** Math.floor(Math.log10(roughStepMs));
+  const normalized = roughStepMs / magnitude;
+  const factor =
+    NICE_STEP_FACTORS.find((candidate) => candidate >= normalized) ?? 10;
+
+  // Timeline labels are rendered at integer millisecond precision, so sub-ms
+  // ticks would collapse into duplicate labels such as "0ms".
+  return Math.max(1, factor * magnitude);
+};
+
+export const createTimelineScale = ({
+  canvasWidth,
+  maxTime,
+  sizeRatio,
+}: {
+  canvasWidth: number;
+  maxTime: number;
+  sizeRatio: number;
+}): TimelineScale => {
+  const safeCanvasWidth = Math.max(canvasWidth, 1);
+  const safeMaxTime = Math.max(maxTime, 1);
+
+  const desiredGridPx = DESIRED_GRID_WIDTH_PX * sizeRatio;
+  const roughPxPerMs = safeCanvasWidth / safeMaxTime;
+  const roughStepMs = desiredGridPx / roughPxPerMs;
+  const timeStep = pickNiceStep(roughStepMs);
+  // Timeline thumbnails use x as the image's left edge. If maxTime maps exactly
+  // to the canvas right edge, the last thumbnail starts off-canvas. Extend the
+  // visible range to the next tick so the ending thumbnail still has room.
+  const visibleMaxTime = Math.ceil(safeMaxTime / timeStep) * timeStep;
+  const pxPerMs = safeCanvasWidth / visibleMaxTime;
+
+  return {
+    pxPerMs,
+    timeStep,
+    visibleMaxTime,
+    leftForTimeOffset: (timeOffset: number) => Math.floor(timeOffset * pxPerMs),
+    timeOffsetForLeft: (left: number) => Math.floor(left / pxPerMs),
+  };
+};