v10/internal/design/spf/features/preload-modes.md

status, date, definition

status	date	definition
implemented	2026-05-20	sketched

Preload modes

SPF models native-like preload semantics with two values: the requested preload mode and whether user or programmatic intent has activated loading.

Implemented decisions

• none blocks source work until activation, metadata allows manifest/MediaSource/initialization work, and auto permits segment loading.
• Play and seeking activate loading. Activation is sticky for the current source and resets when the source changes.
• Keep DOM preload synchronization separate from activation tracking so adapter input and engine intent cannot overwrite each other accidentally.
• Default to metadata-like behavior and preserve unknown extended values in state for forward compatibility without reflecting them as invalid DOM values.
• Downstream behaviors consume derived gates rather than reinterpreting preload independently.

Deferred scope

More granular modes, deactivation after activation, and additional activation triggers require their own use cases.

Current sources of truth

• Preload state machine and tests: packages/spf/src/playback/behaviors/sync-preload.ts and packages/spf/src/playback/behaviors/tests/sync-preload.test.ts
• DOM activation tracking and tests: packages/spf/src/playback/behaviors/dom/track-load-triggers.ts and its colocated tests
• Shared preload helpers: packages/spf/src/media/utils/preload.ts