Interface DetectionFrameSource

Load semantic detection frames for the requested media-time range.

Sources should return detection data, not renderer artifacts. Implementers should prefer sorted frames and avoid mutating returned frames after handing them to the renderer. options is additive context; ignoring it stays correct for any source that does not compose other sources.

Optional coverage hook. Resolve when the source has enough data to answer loadFrames for the requested range.

Playback awaits it under an enabled detection playback gate, which a session with appendable detections gets by default; otherwise a caller that wants to wait awaits it itself. A composed source fans it out to the entries it composes.

Optional source coverage report for timeline UI and buffering decisions.

Optional monotonically increasing source version. Buffered timelines use this to refresh only when the current range changed. Sources that can revise an existing frame must implement this hook; without it, overlapping frame identities are treated as immutable across rolling window loads.

Optionally describe changes after version that overlap ranges.

This allows a hot timeline to patch a small progressive-inference append without reloading and copying its complete buffered window.