docs(producer): note attempt-scoped beginFrameReuse semantics after partial retries

This commit is contained in:
vanceingalls
2026-07-11 20:32:20 +00:00
parent dde3afb72e
commit 2cd8a750e3
2 changed files with 9 additions and 1 deletions
@@ -146,7 +146,9 @@ function aggregateDedup(perfs: CapturePerfSummary[]): RenderPerfSummary["staticD
* render-level reuse outcome (SUM across workers — each worker ticks its own
* frame range). Both zero ⟺ no beginframe session ran (screenshot/drawElement
* sessions never increment these) → undefined, mirroring staticDedup's
* "undefined when it never engaged" contract.
* "undefined when it never engaged" contract. Also inherits `dedupPerfs`'
* retry semantics: a partial-capture retry resets the sink, so the sums cover
* only the final attempt's recaptured ranges (may be < totalFrames).
*/
function aggregateBeginFrameReuse(
perfs: CapturePerfSummary[],
@@ -380,6 +380,12 @@ export interface RenderPerfSummary {
* of `staticDedup` (predictive dedup never arms under beginframe); the
* static-frame fraction is noDamageFrames / (noDamageFrames + hasDamageFrames).
* Undefined when no session captured in beginframe mode.
*
* Like every metric aggregated from `dedupPerfs` (staticDedup, drawElement,
* subTimelineWait), a partial-capture RETRY replaces the counters with the
* final attempt's set (see the reset in executeDiskCaptureWithAdaptiveRetry)
* — after a missing-range retry the counts cover only the recaptured ranges,
* not the whole render, so noDamage + hasDamage may be < totalFrames.
*/
beginFrameReuse?: {
noDamageFrames: number;