@@ -108,6 +108,16 @@ export type { CaptureOptions, CaptureResult, CaptureBufferResult, CapturePerfSum
108108 * both times shows its frame for `heldVideoTime`, so footage does not smear. */
109109export type BeforeCaptureHook = ( page : Page , time : number , heldVideoTime ?: number ) => Promise < void > ;
110110
111+ /** The per-frame wait a capture is in, worded for the stall error a user reads. */
112+ type CaptureStep =
113+ | "seeking the timeline"
114+ | "decoding CSS background images"
115+ | "injecting video frames"
116+ | "waiting for page seek handlers"
117+ | "loading color-grading LUTs"
118+ | "compositing the page"
119+ | "capturing the frame" ;
120+
111121export interface CaptureSession {
112122 browser : Browser ;
113123 /** Exact ownership token for this browser acquisition. */
@@ -298,6 +308,7 @@ export interface CaptureSession {
298308 * retries via screenshot.
299309 */
300310 deFrameTimeouts ?: number ;
311+ captureStep ?: CaptureStep ;
301312 /**
302313 * drawElement init passed every gate but stopped before verification +
303314 * canvas injection: the session has no video-frame injector yet (probe
@@ -2856,8 +2867,10 @@ async function prepareFrameForCapture(
28562867 ) ;
28572868
28582869 const seekStart = Date . now ( ) ;
2870+ session . captureStep = "seeking the timeline" ;
28592871 const hasPendingComposite = await seekPageTimeline ( page , quantizedTime , seekOptions ) ;
28602872
2873+ session . captureStep = "decoding CSS background images" ;
28612874 await decodeDynamicCssBackgroundImages ( page ) ;
28622875
28632876 const seekMs = Date . now ( ) - seekStart ;
@@ -2867,9 +2880,12 @@ async function prepareFrameForCapture(
28672880 // replacements for <video> elements.
28682881 const beforeCaptureStart = Date . now ( ) ;
28692882 if ( session . onBeforeCapture ) {
2883+ session . captureStep = "injecting video frames" ;
28702884 await session . onBeforeCapture ( page , quantizedTime , heldVideoTime ) ;
28712885 }
2886+ session . captureStep = "waiting for page seek handlers" ;
28722887 await waitForPendingSeekCompletion ( page ) ;
2888+ session . captureStep = "loading color-grading LUTs" ;
28732889 await page . evaluate ( async ( ) => {
28742890 const runtime = (
28752891 window as Window & {
@@ -2889,6 +2905,7 @@ async function prepareFrameForCapture(
28892905 session . captureMode !== "beginframe" &&
28902906 session . captureMode !== "drawelement"
28912907 ) {
2908+ session . captureStep = "compositing the page" ;
28922909 await page . evaluate ( async ( ) => {
28932910 const w = window as unknown as { __hf_page_composite_prepare ?: ( ) => Promise < boolean > } ;
28942911 if ( typeof w . __hf_page_composite_prepare === "function" ) {
@@ -2909,6 +2926,7 @@ async function prepareFrameForCapture(
29092926 } ) ;
29102927 }
29112928
2929+ session . captureStep = "capturing the frame" ;
29122930 return { quantizedTime, seekMs, beforeCaptureMs } ;
29132931}
29142932
@@ -4189,12 +4207,14 @@ async function captureAccumulatedFrame(
41894207 const frameTime = quantizeSeekTime ( absFrameIndex / fps , fps ) ;
41904208
41914209 const eventfulSeekStart = Date . now ( ) ;
4210+ session . captureStep = "seeking the timeline" ;
41924211 await seekPageTimeline ( session . page , frameTime , undefined ) ;
41934212 const totals = { seekMs : Date . now ( ) - eventfulSeekStart , beforeCaptureMs : 0 , screenshotMs : 0 } ;
41944213 if ( session . onBeforeCapture ) {
41954214 // The injector copies a video's own style only when its frame changes: inject at frameTime
41964215 // first so the held frame carries frameTime's style, not the first sample's.
41974216 const injectStart = Date . now ( ) ;
4217+ session . captureStep = "injecting video frames" ;
41984218 await session . onBeforeCapture ( session . page , frameTime , frameTime ) ;
41994219 totals . beforeCaptureMs += Date . now ( ) - injectStart ;
42004220 }
@@ -4237,6 +4257,7 @@ async function captureAccumulatedFrame(
42374257 }
42384258
42394259 const restoreSeekStart = Date . now ( ) ;
4260+ session . captureStep = "seeking the timeline" ;
42404261 await seekPageTimeline ( session . page , frameTime , { suppressEvents : true } ) ;
42414262 totals . seekMs += Date . now ( ) - restoreSeekStart ;
42424263
@@ -4603,6 +4624,7 @@ export async function captureFramesBatchPipelined(
46034624 const fps = fpsToNumber ( options . fps ) ;
46044625 const quantized = times . map ( ( t ) => quantizeTimeToFrame ( t , fps ) ) ;
46054626
4627+ session . captureStep = "capturing the frame" ;
46064628 const { encodeResults, failedAt, error } = await produceDrawElementFrameBatch (
46074629 page ,
46084630 quantized ,
0 commit comments