[jonluca]

Summary

Let hosts coordinating audible focus across several players own renderer audio-session activation. Coalesce concurrent category setup through the existing process-wide transition queue and validate current settings on later loads, avoiding repeated configuration of an already matching session.

What changed

• Add rendererAudioSessionActivationEnabled, defaulting to true. When disabled before load, renderer loads and interruption recovery skip activation and channel preference changes.
• Validate category, mode, route-sharing policy and multichannel support off-main before load. Concurrent loads share the operation; later loads retry after failures or external session changes.
• Keep configuration ordered with activation and deactivation through SharedOutputCoordinator.
• Document the distinction between activation, category setup and the existing opt-in for final deactivation.

Test plan

• Device / OS: Apple M4 Max, macOS 27.0.1, Xcode 27.1.
• Source media: none; deterministic coordinator and activation-ownership tests.
• 26 shared-output, audio-session transition order and teardown-policy Swift tests, plus 4 public API documentation tests, pass.
• AetherEngine builds for arm64 iOS18 simulator with -warnings-as-errors.
• Documentation link validation and git diff --check pass.
• Physical iOS/tvOS audio routes and interruption recovery were not exercised.

Checklist

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

[Copilot]

🟡 Changes recommended

Route-change handling can still overwrite host-managed channel preferences when renderer activation is disabled.

1 open issue

• Gate channel preference ownership on renderer activation · New

What changed in this PR

This PR adds host control over renderer audio-session activation and moves category validation into the process-wide transition queue.

Changes:

• Add a default-enabled activation flag for renderer loads and interruption recovery.
• Coalesce concurrent category setup and revalidate settings on later loads.
• Add ownership tests and document activation, configuration, and deactivation responsibilities.

File	Description
Tests/​AetherEngineTests/​SharedOutputCoordinatorTests.swift	Test configuration coalescing, revalidation, and activation ownership.
Sources/​AetherEngine/​SharedOutputCoordinator.swift	Serialize and coalesce category configuration.
Sources/​AetherEngine/​AetherEngine+Loading.swift	Gate renderer activation with the new ownership flag.
Sources/​AetherEngine/​AetherEngine.swift	Expose the flag and validate category settings at load.
README.md	Update category-configuration timing documentation.
docs/​formats.md	Clarify load-time audio-session setup.
docs/​api.md	Document host-managed activation and lifecycle responsibilities.
CHANGELOG.md	Announce activation control and shared category setup.

_{Review effort: Balanced}