perf(report): memoize derived task and timeline data arrays (#2320)

* perf(report): memoize derived task and timeline data arrays

Memoizes the `useAllCurrentTasks` global selector output to prevent
unnecessary array allocations and referential instability on every
render. Also memoizes the heavy reduction for `allScreenshots` and
`idTaskMap` inside the `Timeline` component so it is not re-computed
unless the task array changes.

* refactor(report): extract pure helpers for memoized selectors and add tests

Builds on the memoization in #2320 by lifting the derivation logic out of
useAllCurrentTasks and Timeline into pure helpers, then covering them with
unit tests so the stable-reference promise is verifiable.

- flattenGroupedDumpTasks() and buildTimelineScreenshots() are now pure
  modules; the React hooks/components only call them inside useMemo.
- buildTimelineScreenshots is rewritten as compute-startingTime then
  collect-then-sort, removing the closure-mutated startingTime/idCount that
  the original reduce relied on. Legacy starting-time semantics (recorders
  with no screenshot still contribute their ts) are preserved and pinned by
  a regression test.
- idTaskMap no longer keeps dead keys for filtered-out recorder items.
- 14 new vitest cases under apps/report cover null input, empty/no-screenshot
  tasks, ordering across tasks, id uniqueness, repeated-call equality, and
  the legacy starting-time edge case.
- Drop .jules/bolt.md: agent scratchpad that should not live in the repo.

Validation: pnpm run lint, npx nx build report, vitest run (19 passed).

* test(report): add fixture-driven regression test for timeline builder

Runs flattenGroupedDumpTasks + buildTimelineScreenshots against every real
dump JSON under apps/report/test-data/ so future schema or refactor
regressions surface immediately instead of waiting for a browser run.

Each fixture is asserted to: produce an array, never emit an id that
cannot be reverse-mapped, and never emit a non-finite timeOffset.

---------

Co-authored-by: quanruzhuoxiu <quanruzhuoxiu@gmail.com>

Author: vincerevu

apps/report/src/components/store/flatten-tasks.test.ts

@@ -0,0 +1,70 @@
+import type {
+  ExecutionDump,
+  ExecutionTask,
+  GroupedActionDump,
+} from '@midscene/core';
+import { describe, expect, it } from 'vitest';
+import { flattenGroupedDumpTasks } from './flatten-tasks';
+
+const makeTask = (id: string): ExecutionTask =>
+  ({ taskId: id }) as unknown as ExecutionTask;
+
+const makeExecution = (taskIds: string[]): ExecutionDump =>
+  ({
+    name: `exec-${taskIds.join('-')}`,
+    tasks: taskIds.map(makeTask),
+  }) as unknown as ExecutionDump;
+
+const makeDump = (executionTaskIds: string[][]): GroupedActionDump =>
+  ({
+    groupName: 'group',
+    groupDescription: 'desc',
+    executions: executionTaskIds.map(makeExecution),
+  }) as unknown as GroupedActionDump;
+
+describe('flattenGroupedDumpTasks', () => {
+  it('returns an empty array when groupedDump is null', () => {
+    expect(flattenGroupedDumpTasks(null)).toEqual([]);
+  });
+
+  it('returns an empty array when no executions are present', () => {
+    expect(flattenGroupedDumpTasks(makeDump([]))).toEqual([]);
+  });
+
+  it('flattens tasks across executions while preserving order', () => {
+    const dump = makeDump([['a1', 'a2'], ['b1'], ['c1', 'c2', 'c3']]);
+
+    const result = flattenGroupedDumpTasks(dump);
+
+    expect(result).toHaveLength(6);
+    expect(result.map((t) => (t as any).taskId)).toEqual([
+      'a1',
+      'a2',
+      'b1',
+      'c1',
+      'c2',
+      'c3',
+    ]);
+  });
+
+  it('returns referentially identical task instances (no cloning)', () => {
+    const sharedTask = makeTask('shared');
+    const dump = {
+      executions: [{ tasks: [sharedTask] }],
+    } as unknown as GroupedActionDump;
+
+    const result = flattenGroupedDumpTasks(dump);
+
+    expect(result[0]).toBe(sharedTask);
+  });
+
+  it('produces equal output for repeated calls so memoization is meaningful', () => {
+    const dump = makeDump([['a', 'b'], ['c']]);
+
+    const first = flattenGroupedDumpTasks(dump);
+    const second = flattenGroupedDumpTasks(dump);
+
+    expect(second).toEqual(first);
+    expect(second).toHaveLength(3);
+  });
+});

apps/report/src/components/store/flatten-tasks.ts

@@ -0,0 +1,11 @@
+import type { ExecutionTask, GroupedActionDump } from '@midscene/core';
+
+export const flattenGroupedDumpTasks = (
+  groupedDump: GroupedActionDump | null,
+): ExecutionTask[] => {
+  if (!groupedDump) return [];
+  return groupedDump.executions.reduce<ExecutionTask[]>(
+    (acc, execution) => acc.concat(execution.tasks),
+    [],
+  );
+};

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

@@ -15,7 +15,9 @@ import {
   extractDumpMetaInfo,
   generateAnimationScripts,
 } from '@midscene/visualizer';
+import { useMemo } from 'react';
 import * as Z from 'zustand';
+import { flattenGroupedDumpTasks } from './flatten-tasks';
 
 const { create } = Z;
 
@@ -247,12 +249,5 @@ export const useExecutionDump = create<DumpStoreType>((set, get) => {
 
 export const useAllCurrentTasks = (): ExecutionTask[] => {
   const groupedDump = useExecutionDump((store) => store.dump);
-  if (!groupedDump) return [];
-
-  const tasksInside = groupedDump.executions.reduce<ExecutionTask[]>(
-    (acc2, execution) => acc2.concat(execution.tasks),
-    [],
-  );
-
-  return tasksInside;
+  return useMemo(() => flattenGroupedDumpTasks(groupedDump), [groupedDump]);
 };

apps/report/src/components/timeline/build-timeline-screenshots.fixtures.test.ts

@@ -0,0 +1,37 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { flattenGroupedDumpTasks } from '../store/flatten-tasks';
+import { buildTimelineScreenshots } from './build-timeline-screenshots';
+
+const testDataDir = path.resolve(__dirname, '../../../test-data');
+const fixtureFiles = fs
+  .readdirSync(testDataDir)
+  .filter((file) => file.endsWith('.json'));
+
+describe('helpers against real test-data fixtures', () => {
+  for (const file of fixtureFiles) {
+    it(`processes ${file} without errors`, () => {
+      const raw = fs.readFileSync(path.join(testDataDir, file), 'utf-8');
+      const dump = JSON.parse(raw);
+
+      const allTasks = flattenGroupedDumpTasks(dump);
+      expect(Array.isArray(allTasks)).toBe(true);
+
+      const result = buildTimelineScreenshots(allTasks);
+      expect(Array.isArray(result.allScreenshots)).toBe(true);
+      expect(result.idTaskMap).toBeTypeOf('object');
+      expect(typeof result.startingTime).toBe('number');
+
+      // Every emitted id must reverse-map to a real task
+      for (const shot of result.allScreenshots) {
+        expect(result.idTaskMap[shot.id]).toBeDefined();
+      }
+
+      // No NaN offsets — would imply startingTime mismatch
+      for (const shot of result.allScreenshots) {
+        expect(Number.isFinite(shot.timeOffset)).toBe(true);
+      }
+    });
+  }
+});

apps/report/src/components/timeline/build-timeline-screenshots.test.ts

@@ -0,0 +1,227 @@
+import type { ExecutionTask } from '@midscene/core';
+import { describe, expect, it } from 'vitest';
+import { buildTimelineScreenshots } from './build-timeline-screenshots';
+
+interface TaskFixtureOptions {
+  id: string;
+  startTs?: number;
+  uiContextScreenshot?: { base64: string };
+  recorder?: { ts: number; base64?: string }[];
+}
+
+const makeTask = (opts: TaskFixtureOptions): ExecutionTask =>
+  ({
+    taskId: opts.id,
+    timing: opts.startTs !== undefined ? { start: opts.startTs } : undefined,
+    uiContext: opts.uiContextScreenshot
+      ? { screenshot: opts.uiContextScreenshot }
+      : undefined,
+    recorder: opts.recorder?.map((r) => ({
+      type: 'screenshot',
+      ts: r.ts,
+      screenshot: r.base64 !== undefined ? { base64: r.base64 } : undefined,
+    })),
+  }) as unknown as ExecutionTask;
+
+describe('buildTimelineScreenshots', () => {
+  it('returns empty result for empty input', () => {
+    const { allScreenshots, idTaskMap, startingTime } =
+      buildTimelineScreenshots([]);
+    expect(allScreenshots).toEqual([]);
+    expect(idTaskMap).toEqual({});
+    expect(startingTime).toBe(-1);
+  });
+
+  it('drops recorder items that have no screenshot', () => {
+    const task = makeTask({
+      id: 'no-shot',
+      startTs: 1000,
+      recorder: [{ ts: 1100 }],
+    });
+
+    const { allScreenshots } = buildTimelineScreenshots([task]);
+
+    expect(allScreenshots).toEqual([]);
+  });
+
+  it('emits a single uiContext screenshot for a task without recorders', () => {
+    const task = makeTask({
+      id: 'ctx-only',
+      startTs: 5000,
+      uiContextScreenshot: { base64: 'CTX' },
+    });
+
+    const { allScreenshots, idTaskMap, startingTime } =
+      buildTimelineScreenshots([task]);
+
+    expect(startingTime).toBe(5000);
+    expect(allScreenshots).toHaveLength(1);
+    expect(allScreenshots[0]).toMatchObject({
+      img: 'CTX',
+      timeOffset: 0,
+    });
+    expect(idTaskMap[allScreenshots[0].id]).toBe(task);
+  });
+
+  it('uses the earliest recorder ts as the starting time and computes offsets', () => {
+    const task = makeTask({
+      id: 'with-recorder',
+      startTs: 2000,
+      recorder: [
+        { ts: 2500, base64: 'B' },
+        { ts: 1800, base64: 'A' },
+        { ts: 3000, base64: 'C' },
+      ],
+    });
+
+    const { allScreenshots, startingTime } = buildTimelineScreenshots([task]);
+
+    expect(startingTime).toBe(1800);
+    expect(allScreenshots.map((s) => s.timeOffset)).toEqual([0, 700, 1200]);
+    expect(allScreenshots.map((s) => s.img)).toEqual(['A', 'B', 'C']);
+  });
+
+  it('orders screenshots from multiple tasks by absolute time', () => {
+    const taskA = makeTask({
+      id: 'A',
+      startTs: 1000,
+      recorder: [{ ts: 1500, base64: 'A1' }],
+    });
+    const taskB = makeTask({
+      id: 'B',
+      startTs: 500,
+      recorder: [
+        { ts: 800, base64: 'B1' },
+        { ts: 2000, base64: 'B2' },
+      ],
+    });
+
+    const { allScreenshots, startingTime } = buildTimelineScreenshots([
+      taskA,
+      taskB,
+    ]);
+
+    expect(startingTime).toBe(500);
+    expect(allScreenshots.map((s) => s.img)).toEqual(['B1', 'A1', 'B2']);
+    expect(allScreenshots.map((s) => s.timeOffset)).toEqual([300, 1000, 1500]);
+  });
+
+  it('maps every emitted id back to the originating task', () => {
+    const taskA = makeTask({
+      id: 'A',
+      startTs: 1000,
+      uiContextScreenshot: { base64: 'CTX-A' },
+      recorder: [{ ts: 1100, base64: 'A1' }],
+    });
+    const taskB = makeTask({
+      id: 'B',
+      startTs: 2000,
+      recorder: [{ ts: 2100, base64: 'B1' }],
+    });
+
+    const { allScreenshots, idTaskMap } = buildTimelineScreenshots([
+      taskA,
+      taskB,
+    ]);
+
+    const taskByImg = (img: string) =>
+      idTaskMap[allScreenshots.find((s) => s.img === img)!.id];
+
+    expect(taskByImg('CTX-A')).toBe(taskA);
+    expect(taskByImg('A1')).toBe(taskA);
+    expect(taskByImg('B1')).toBe(taskB);
+  });
+
+  it('assigns unique ids across all emitted screenshots', () => {
+    const tasks = [
+      makeTask({
+        id: 'A',
+        startTs: 100,
+        uiContextScreenshot: { base64: 'CTX' },
+        recorder: [
+          { ts: 110, base64: 'A1' },
+          { ts: 120, base64: 'A2' },
+        ],
+      }),
+      makeTask({
+        id: 'B',
+        startTs: 200,
+        recorder: [{ ts: 210, base64: 'B1' }],
+      }),
+    ];
+
+    const { allScreenshots } = buildTimelineScreenshots(tasks);
+    const ids = allScreenshots.map((s) => s.id);
+
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it('produces equal output for repeated calls (allowing useMemo to short-circuit)', () => {
+    const tasks = [
+      makeTask({
+        id: 'A',
+        startTs: 1000,
+        recorder: [{ ts: 1100, base64: 'A1' }],
+      }),
+    ];
+
+    const first = buildTimelineScreenshots(tasks);
+    const second = buildTimelineScreenshots(tasks);
+
+    expect(second.allScreenshots).toEqual(first.allScreenshots);
+    expect(second.startingTime).toBe(first.startingTime);
+  });
+
+  it('does not put dropped recorder items into idTaskMap', () => {
+    const task = makeTask({
+      id: 'mixed',
+      startTs: 1000,
+      recorder: [
+        { ts: 1100, base64: 'KEEP' },
+        { ts: 1200 }, // no screenshot — should be dropped from idTaskMap too
+      ],
+    });
+
+    const { allScreenshots, idTaskMap } = buildTimelineScreenshots([task]);
+
+    expect(allScreenshots).toHaveLength(1);
+    expect(Object.keys(idTaskMap)).toHaveLength(1);
+    expect(idTaskMap[allScreenshots[0].id]).toBe(task);
+  });
+
+  it('still uses dropped recorder ts to compute starting time', () => {
+    // legacy behaviour: a recorder with no screenshot still contributes its ts
+    // to startingTime so that surviving entries render at the right offset.
+    const taskA = makeTask({
+      id: 'A',
+      startTs: 5000,
+      recorder: [{ ts: 800 }], // no screenshot but earliest ts
+    });
+    const taskB = makeTask({
+      id: 'B',
+      startTs: 6000,
+      recorder: [{ ts: 6100, base64: 'B1' }],
+    });
+
+    const { allScreenshots, startingTime } = buildTimelineScreenshots([
+      taskA,
+      taskB,
+    ]);
+
+    expect(startingTime).toBe(800);
+    expect(allScreenshots).toHaveLength(1);
+    expect(allScreenshots[0]).toMatchObject({
+      img: 'B1',
+      timeOffset: 5300, // 6100 - 800
+    });
+  });
+
+  it('does not crash when a task has no timing or uiContext at all', () => {
+    const task = makeTask({ id: 'bare' });
+
+    const { allScreenshots, startingTime } = buildTimelineScreenshots([task]);
+
+    expect(allScreenshots).toEqual([]);
+    expect(startingTime).toBe(-1);
+  });
+});