[jonluca]

Summary

Add an opt-in for hosts that want a paused video pipeline to survive background suspension, avoiding a rebuild when the system preserves it. Recover a failed software video queue before waking its feeder, while leaving healthy buffered frames intact.

What changed

• Add retainsVideoPipelineWhenBackgrounded, defaulting to false and applying only to paused sessions.
• Preserve the existing playing-session, audio-only, PiP and in-flight load/seek policies.
• Flush a failed software video queue before play resumes. A healthy queue is not flushed, even when full.
• Document the host's responsibility to reload if the system invalidates a retained decoder; add policy and play-order regression tests.

Test plan

• Device / OS: Apple M4 Max, macOS 27.0.1, Xcode 27.1.
• Source media: policy and injected queue-status tests; the existing two-frame 64x64 HEVC Main 10 MP4 fixture with PQ/BT.2020 and HDR10+ metadata exercises the in-flight load/background path.
• 60 focused background/renderer Swift tests and 4 public API documentation tests pass, covering keepalive, grace windows, in-flight load decisions and selection preservation.
• AetherEngine builds for arm64 iOS18 simulator with -warnings-as-errors.
• Documentation link validation and git diff --check pass.
• Physical iOS/tvOS suspension was not exercised. Retention remains opt-in because system-invalidated decoder sessions can still require a reload.

Checklist

• CHANGELOG.md updated
• Conventional commit
• Engine-owned behavior
• Public API documented

[Copilot]

🟡 Changes recommended

Resuming a retained session while backgrounded bypasses playing-session policy, allowing disabled background playback or continued software video feeding.

1 open issue

• Reapply background playback policy after retained-session resume · New

What changed in this PR

Adds opt-in retention of paused video pipelines to avoid rebuilding them after background suspension when the system preserves the decoder.

Changes:

• Adds retainsVideoPipelineWhenBackgrounded, defaulting to false, to background lifecycle policy.
• Recovers failed software video queues before playback resumes while preserving healthy queues.
• Documents retention limitations and adds policy and recovery-order tests.

File	Description
Tests/​AetherEngineTests/​SampleBufferRendererLookaheadTests.swift	Tests failed-queue recovery order and healthy-queue preservation.
Tests/​AetherEngineTests/​BackgroundKeepaliveTests.swift	Tests the opt-in default and paused-session policy.
Sources/​AetherEngine/​Renderer/​SampleBufferRenderer.swift	Adds failed-queue recovery and queue injection for tests.
Sources/​AetherEngine/​Native/​SoftwarePlaybackHost.swift	Recovers the video queue before resuming transport.
Sources/​AetherEngine/​AetherEngine.swift	Exposes retention configuration and updates background policy.
docs/​api.md	Documents retention behavior and host reload responsibility.
CHANGELOG.md	Records the retention option and queue recovery behavior.

_{Review effort: Balanced}