From 1ef9448076631e2c57bb6147d3bc61e21fdf56ed Mon Sep 17 00:00:00 2001 From: Daniel Roe Date: Fri, 20 Nov 2026 10:53:47 +0000 Subject: [PATCH 1/2] feat(stats-generator): score interaction trace by main-thread work to commit --- .../src/interaction-work.test.ts | 260 ++++++++++++++++++ .../stats-generator/src/interaction-work.ts | 220 +++++++++++++++ 2 files changed, 480 insertions(+) create mode 100644 packages/stats-generator/src/interaction-work.test.ts create mode 100644 packages/stats-generator/src/interaction-work.ts diff --git a/packages/stats-generator/src/interaction-work.test.ts b/packages/stats-generator/src/interaction-work.test.ts new file mode 100644 index 00000000..1a3ae586 --- /dev/null +++ b/packages/stats-generator/src/interaction-work.test.ts @@ -0,0 +1,260 @@ +import assert from 'node:assert/strict' +import test from 'node:test' +import { getInteractionWorkFromTrace } from './interaction-work.ts' + +const PID = 1 +const MAIN_TID = 10 +const COMPOSITOR_TID = 11 +const OTHER_PID = 2 +const TIME_ORIGIN = 2_000_000 + +const at = (ms: number) => TIME_ORIGIN + ms * 1000 + +function metadata() { + return [ + threadName(PID, MAIN_TID, 'CrRendererMain'), + threadName(PID, COMPOSITOR_TID, 'Compositor'), + threadName(OTHER_PID, MAIN_TID, 'CrRendererMain'), + ] +} + +function threadName(pid: number, tid: number, name: string) { + return { name: 'thread_name', ph: 'M', pid, tid, ts: 0, args: { name } } +} + +function eventTiming(data: { + interactionId?: number + timeStamp: number + duration: number + processingStart: number + processingEnd: number + commitFinishTime?: number +}) { + return { + name: 'EventTiming', + ph: 'b', + pid: PID, + tid: MAIN_TID, + ts: at(data.timeStamp), + args: { data: { interactionId: 7, ...data } }, + } +} + +function task( + start: number, + end: number, + { name = 'RunTask', pid = PID, tid = MAIN_TID } = {}, +) { + return { name, ph: 'X', pid, tid, ts: at(start), dur: (end - start) * 1000 } +} + +function click({ + commitFinishTime = 1006 as number | null, + tasks = [] as ReturnType[], +} = {}) { + return { + traceEvents: [ + ...metadata(), + eventTiming({ + timeStamp: 1000, + duration: 16, + processingStart: 1000.5, + processingEnd: 1001, + }), + eventTiming({ + timeStamp: 1000.2, + duration: 15.8, + processingStart: 1001.2, + processingEnd: 1003, + ...(commitFinishTime === null ? {} : { commitFinishTime }), + }), + task(999.8, 1003.2), + task(1003.5, 1005, { tid: COMPOSITOR_TID }), + task(1003.5, 1005, { pid: OTHER_PID }), + ...tasks, + task(1008, 1010), + ], + } +} + +test('excludes idle time before the frame and work after commit', () => { + assert.deepEqual( + getInteractionWorkFromTrace(click({ tasks: [task(1004.5, 1006.5)] })), + { + workToCommit: 4.7, + inputDelay: 0.5, + processingDuration: 2.5, + renderingWork: 1.7, + }, + ) +}) + +test('counts all main-thread time up to commit when there is no idle time', () => { + assert.deepEqual( + getInteractionWorkFromTrace( + click({ tasks: [task(1003.2, 1005), task(1005, 1006.5)] }), + ), + { + workToCommit: 6, + inputDelay: 0.5, + processingDuration: 2.5, + renderingWork: 3, + }, + ) +}) + +test('counts overlapping tasks once', () => { + assert.equal( + getInteractionWorkFromTrace( + click({ + tasks: [task(1005.2, 1006.2), task(1003.5, 1005.5), task(1004, 1005)], + }), + )?.renderingWork, + 2.7, + ) +}) + +test('returns null without commitFinishTime', () => { + assert.equal( + getInteractionWorkFromTrace( + click({ + commitFinishTime: null, + tasks: [task(1004.5, 1006.5), task(1005.5, 1005.8, { name: 'Commit' })], + }), + ), + null, + ) +}) + +test('returns null when commitFinishTime does not follow processing', () => { + assert.equal( + getInteractionWorkFromTrace( + click({ commitFinishTime: 1002, tasks: [task(1004.5, 1006.5)] }), + ), + null, + ) + assert.equal( + getInteractionWorkFromTrace({ + traceEvents: [ + ...metadata(), + eventTiming({ + timeStamp: 1000, + duration: 16, + processingStart: 1000.5, + processingEnd: 1001, + commitFinishTime: 1002, + }), + eventTiming({ + timeStamp: 1000.2, + duration: 15.8, + processingStart: 1001.2, + processingEnd: 1003, + }), + task(999.8, 1006.5), + ], + }), + null, + ) +}) + +test('caps the commit boundary at the end of the Event Timing duration', () => { + assert.equal( + getInteractionWorkFromTrace( + click({ commitFinishTime: 1030, tasks: [task(1004, 1020)] }), + )?.renderingWork, + 12.2, + ) +}) + +test('scores an interaction that ends with processing without commit data', () => { + assert.deepEqual( + getInteractionWorkFromTrace({ + traceEvents: [ + ...metadata(), + eventTiming({ + timeStamp: 1000.287, + duration: 0.754, + processingStart: 1000.791, + processingEnd: 1001.041, + }), + task(999.8, 1003.2), + ], + }), + { + workToCommit: 0.754, + inputDelay: 0.504, + processingDuration: 0.25, + renderingWork: 0, + }, + ) +}) + +test('returns null without an interaction or a renderer main thread', () => { + assert.equal(getInteractionWorkFromTrace(undefined), null) + assert.equal(getInteractionWorkFromTrace({ traceEvents: [] }), null) + assert.equal( + getInteractionWorkFromTrace({ + traceEvents: [ + ...metadata(), + eventTiming({ + interactionId: 0, + timeStamp: 1000, + duration: 16, + processingStart: 1000.5, + processingEnd: 1003, + commitFinishTime: 1006, + }), + task(999.8, 1003.2), + ], + }), + null, + ) + assert.equal( + getInteractionWorkFromTrace({ + traceEvents: click().traceEvents.filter( + (event) => event.name !== 'thread_name', + ), + }), + null, + ) + assert.equal( + getInteractionWorkFromTrace({ + traceEvents: [ + ...metadata(), + eventTiming({ + timeStamp: 1000, + duration: 0, + processingStart: 1000, + processingEnd: 1000, + }), + task(999.8, 1003.2), + ], + }), + null, + ) +}) + +test('scores the interaction with the longest Event Timing duration', () => { + const trace = click({ tasks: [task(1004.5, 1006.5)] }) + trace.traceEvents.unshift( + eventTiming({ + interactionId: 3, + timeStamp: 900, + duration: 8, + processingStart: 901, + processingEnd: 905, + commitFinishTime: 906, + }), + ) + trace.traceEvents.push( + eventTiming({ + interactionId: 9, + timeStamp: 1100, + duration: 4, + processingStart: 1101, + processingEnd: 1102, + commitFinishTime: 1103, + }), + ) + assert.equal(getInteractionWorkFromTrace(trace)?.workToCommit, 4.7) +}) diff --git a/packages/stats-generator/src/interaction-work.ts b/packages/stats-generator/src/interaction-work.ts new file mode 100644 index 00000000..60088dab --- /dev/null +++ b/packages/stats-generator/src/interaction-work.ts @@ -0,0 +1,220 @@ +export interface InteractionWork { + /** Input delay plus processing duration plus rendering work, in ms. */ + workToCommit: number + /** Input timestamp to the start of the first event handler, in ms. */ + inputDelay: number + /** Start of the first event handler to the end of the last, in ms. */ + processingDuration: number + /** Renderer main-thread busy time from the end of processing until the interaction's frame commits, in ms. */ + renderingWork: number +} + +interface EventTimingData { + interactionId?: number + timeStamp?: number + duration?: number + processingStart?: number + processingEnd?: number + commitFinishTime?: number +} + +interface TraceEvent { + name?: string + ph?: string + pid?: number + tid?: number + ts?: number + dur?: number + args?: { name?: string; data?: EventTimingData } +} + +type CompleteEvent = TraceEvent & { ts: number; dur: number } + +/** Trace-clock timestamps in microseconds. */ +interface Interaction { + pid: number + start: number + end: number + processingStart: number + processingEnd: number + commitFinish?: number +} + +function isFiniteNumber(value: unknown): value is number { + return typeof value === 'number' && Number.isFinite(value) +} + +function maxDefined(a: number | undefined, b: number | undefined) { + return a === undefined ? b : b === undefined ? a : Math.max(a, b) +} + +/** + * Event Timing fields are milliseconds relative to the document's time origin, with microsecond precision. + * The start event's `ts` is the trace-clock time of its `timeStamp`. + */ +function toInteraction(event: TraceEvent): Interaction | undefined { + const data = event.args?.data + if ( + !isFiniteNumber(event.pid) || + !isFiniteNumber(event.ts) || + !isFiniteNumber(data?.timeStamp) || + !isFiniteNumber(data.duration) || + !isFiniteNumber(data.processingStart) || + !isFiniteNumber(data.processingEnd) + ) + return undefined + + const { ts } = event + const { timeStamp } = data + const toTraceTime = (ms: number) => Math.round(ts + (ms - timeStamp) * 1000) + return { + pid: event.pid, + start: ts, + end: toTraceTime(timeStamp + data.duration), + processingStart: toTraceTime(data.processingStart), + processingEnd: toTraceTime(data.processingEnd), + commitFinish: isFiniteNumber(data.commitFinishTime) + ? toTraceTime(data.commitFinishTime) + : undefined, + } +} + +/** Merges the Event Timing entries of each interaction and returns the one with the longest duration. */ +function findLongestInteraction( + events: readonly TraceEvent[], +): Interaction | undefined { + const interactions = new Map() + for (const event of events) { + const interactionId = event.args?.data?.interactionId + if (event.name !== 'EventTiming' || event.ph !== 'b' || !interactionId) + continue + const current = toInteraction(event) + if (!current) continue + + const key = `${current.pid}:${interactionId}` + const existing = interactions.get(key) + interactions.set( + key, + existing + ? { + pid: current.pid, + start: Math.min(existing.start, current.start), + end: Math.max(existing.end, current.end), + processingStart: Math.min( + existing.processingStart, + current.processingStart, + ), + processingEnd: Math.max( + existing.processingEnd, + current.processingEnd, + ), + commitFinish: maxDefined( + existing.commitFinish, + current.commitFinish, + ), + } + : current, + ) + } + + let longest: Interaction | undefined + for (const interaction of interactions.values()) { + if ( + !longest || + interaction.end - interaction.start > longest.end - longest.start + ) + longest = interaction + } + return longest +} + +function getMainThreadTasks(events: readonly TraceEvent[], pid: number) { + const threads = new Set( + events + .filter( + (event) => + event.ph === 'M' && + event.name === 'thread_name' && + event.args?.name === 'CrRendererMain' && + event.pid === pid && + isFiniteNumber(event.tid), + ) + .map((event) => event.tid), + ) + if (threads.size === 0) return undefined + return events.filter( + (event): event is CompleteEvent => + event.ph === 'X' && + event.name === 'RunTask' && + event.pid === pid && + threads.has(event.tid) && + isFiniteNumber(event.ts) && + isFiniteNumber(event.dur), + ) +} + +/** Total length of the union of the tasks' intervals, clipped to [from, to]. */ +function getBusyTime( + tasks: readonly CompleteEvent[], + from: number, + to: number, +): number { + const intervals = tasks + .map(({ ts, dur }) => [Math.max(ts, from), Math.min(ts + dur, to)]) + .filter(([start, end]) => end > start) + .sort((a, b) => a[0] - b[0]) + + let busy = 0 + let current: number[] | undefined + for (const interval of intervals) { + if (current && interval[0] <= current[1]) { + current[1] = Math.max(current[1], interval[1]) + continue + } + if (current) busy += current[1] - current[0] + current = interval + } + if (current) busy += current[1] - current[0] + return busy +} + +/** + * Scores the longest interaction in a Chrome trace as input delay plus processing duration, plus the renderer main + * thread's busy time from the end of processing until `commitFinishTime`, capped at the end of the Event Timing + * duration. Returns null when the trace has no interaction or renderer main thread, or when the duration extends past + * processing without a later `commitFinishTime`. + */ +export function getInteractionWorkFromTrace( + trace: unknown, +): InteractionWork | null { + const events = + (trace as { traceEvents?: readonly TraceEvent[] } | undefined) + ?.traceEvents ?? [] + const interaction = findLongestInteraction(events) + if (!interaction) return null + const tasks = getMainThreadTasks(events, interaction.pid) + const { start, end, processingStart, processingEnd, commitFinish } = + interaction + const commitBoundary = + end <= processingEnd + ? end + : commitFinish === undefined || commitFinish <= processingEnd + ? undefined + : Math.min(commitFinish, end) + if (!tasks || commitBoundary === undefined) return null + + const inputDelay = Math.round(processingStart - start) + const processingDuration = Math.round(processingEnd - processingStart) + const renderingWork = Math.round( + getBusyTime(tasks, processingEnd, commitBoundary), + ) + const workToCommit = inputDelay + processingDuration + renderingWork + if (inputDelay < 0 || processingDuration < 0 || workToCommit <= 0) return null + + return { + workToCommit: workToCommit / 1000, + inputDelay: inputDelay / 1000, + processingDuration: processingDuration / 1000, + renderingWork: renderingWork / 1000, + } +} From ad09f3b1594b448e1a1848fdd5657179f8d1a292 Mon Sep 17 00:00:00 2001 From: Daniel Roe Date: Fri, 20 Nov 2026 10:53:47 +0000 Subject: [PATCH 2/2] feat: record interaction work to commit alongside the Lighthouse breakdown --- .../Description.mdx | 2 +- ...FrameworkClientRenderedVersionCharts.astro | 13 ++ .../Description.mdx | 2 +- ...FrameworkServerRenderedVersionCharts.astro | 13 ++ .../shared/InteractionBreakdownChart.astro | 12 +- .../shared/InteractionChartCaption.astro | 17 +-- .../shared/InteractionHistoryChart.astro | 27 ++-- .../LighthouseRenderedInteractionCharts.astro | 31 ++++- packages/docs/src/content/docs/methodology.md | 61 ++++++++- packages/docs/src/lib/chart-measurements.ts | 53 +++++++- .../docs/src/lib/interaction-history.test.ts | 128 ++++++++++++++++++ packages/docs/src/lib/interaction-phases.ts | 100 ++++++++++---- packages/docs/src/lib/prepare-chart.ts | 22 ++- packages/docs/src/lib/result-content.ts | 20 +++ packages/docs/src/lib/types.ts | 18 +++ packages/results/src/benchmark-schemas.ts | 22 +++ .../src/benchmark-artifacts.ts | 26 +++- .../src/client-rendering.test.ts | 82 +++++++++++ .../stats-generator/src/client-rendering.ts | 13 ++ .../src/clientSideRendered/run-benchmark.ts | 17 ++- .../src/clientSideRendered/types.ts | 2 + .../src/rendered-sample-metrics.ts | 7 + .../src/run-client-side-rendered-benchmark.ts | 3 + .../src/run-server-side-rendered-benchmark.ts | 3 + .../src/server-rendering.test.ts | 82 +++++++++++ .../stats-generator/src/server-rendering.ts | 13 ++ .../src/serverSideRendered/run-benchmark.ts | 17 ++- .../src/serverSideRendered/types.ts | 2 + packages/stats-generator/src/types.ts | 2 + 29 files changed, 743 insertions(+), 67 deletions(-) diff --git a/packages/docs/src/benchmarks/lighthouse-client-side-rendered-tests/Description.mdx b/packages/docs/src/benchmarks/lighthouse-client-side-rendered-tests/Description.mdx index 59997c51..0b9f052a 100644 --- a/packages/docs/src/benchmarks/lighthouse-client-side-rendered-tests/Description.mdx +++ b/packages/docs/src/benchmarks/lighthouse-client-side-rendered-tests/Description.mdx @@ -1,4 +1,4 @@ -These CSR browser performance tests use Lighthouse to measure paint timings and a controlled navigation interaction. +These CSR browser performance tests use Lighthouse to measure paint timings and a controlled navigation interaction. The interaction is also scored as [work to commit](/methodology/#interaction-work-to-commit) from the same trace. Methodology: [Client Side Rendered Tests (Lighthouse)](/methodology/#client-side-rendered-tests-lighthouse). diff --git a/packages/docs/src/benchmarks/lighthouse-client-side-rendered-tests/LighthouseFrameworkClientRenderedVersionCharts.astro b/packages/docs/src/benchmarks/lighthouse-client-side-rendered-tests/LighthouseFrameworkClientRenderedVersionCharts.astro index 3c85d2a5..c32c605d 100644 --- a/packages/docs/src/benchmarks/lighthouse-client-side-rendered-tests/LighthouseFrameworkClientRenderedVersionCharts.astro +++ b/packages/docs/src/benchmarks/lighthouse-client-side-rendered-tests/LighthouseFrameworkClientRenderedVersionCharts.astro @@ -4,7 +4,9 @@ import { prepareLighthouseClientSideRenderedTestsFcpMsHistory, prepareLighthouseClientSideRenderedTestsFirstPaintMsHistory, prepareLighthouseClientSideRenderedTestsInteractionHistory, + prepareClientSideRenderedInteractionWorkHistory, } from '../../lib/prepare-chart' +import { INTERACTION_WORK } from '../../lib/interaction-phases' import VersionLineChart from '../../components/VersionLineChart.astro' import InteractionHistoryChart from '../shared/InteractionHistoryChart.astro' @@ -16,6 +18,8 @@ const { versions } = Astro.props const interactionData = prepareLighthouseClientSideRenderedTestsInteractionHistory(versions) +const interactionWorkData = + prepareClientSideRenderedInteractionWorkHistory(versions) --- +{ + interactionWorkData.length > 0 ? ( + + ) : null +} { interactionData.length > 0 ? ( +{ + interactionWorkData.length > 0 ? ( + + ) : null +} { interactionData.length > 0 ? ( ({ +const { title, data, metric = LIGHTHOUSE_INTERACTION } = Astro.props +const series = metric.parts.map(({ key, label, color }) => ({ key, label, color, @@ -37,7 +41,7 @@ const chart1Table = prepareInteractionBreakdownTable(chart1) defaultValue="chart" > - + diff --git a/packages/docs/src/benchmarks/shared/InteractionChartCaption.astro b/packages/docs/src/benchmarks/shared/InteractionChartCaption.astro index a3d891bb..1253f6a0 100644 --- a/packages/docs/src/benchmarks/shared/InteractionChartCaption.astro +++ b/packages/docs/src/benchmarks/shared/InteractionChartCaption.astro @@ -1,22 +1,23 @@ --- -import { INTERACTION_PHASES } from '../../lib/interaction-phases' +import { + LIGHTHOUSE_INTERACTION, + type InteractionMetric, +} from '../../lib/interaction-phases' interface Props { title?: string + metric?: InteractionMetric } -const { title } = Astro.props +const { title, metric = LIGHTHOUSE_INTERACTION } = Astro.props ---
{title &&

{title}

} -

- Total latency is split into the three consecutive phases reported by - Lighthouse. -

+

{metric.summary}

    { - INTERACTION_PHASES.map(({ label, description }) => ( + metric.parts.map(({ label, description }) => (
  • The {label.toLowerCase()}, {description}
  • @@ -25,7 +26,7 @@ const { title } = Astro.props