[orut34iop]

Summary

preserveASSMarkup already preserves primary sidecar ASS events and their script header, but secondary sidecars silently use the default text decoder and discard the header. Honor the same opt-in option on the secondary channel and publish secondarySidecarASSHeader independently.

What changed

• Secondary decoding passes the existing option to SubtitleDecoder; the existing ASS/SSA codec gate keeps SRT/VTT output unchanged.
• Reset the secondary header on a new sidecar, embedded selection, clear and stop. Publication stays behind the existing cancellation/active-channel checks.
• Document which header belongs to which cue list. No renderer, forced default styling, channel-exclusivity rule or new embedded decoding path.

Builds on the existing primary API from #48 and per-stream ASS decoding from #267. All changes are based on main 151322d1b843b4414a0fcffa9ed44e8b3a9d087e; #824 and #825 touch adjacent secondary state/comments but are separate contributions, so merge order may require textual reconciliation.

Test plan

• Host: Mac17,3, macOS 26.7.1 (25G241), Swift 6.4 / Xcode toolchain; default traits, native SwiftPM.
• Media: existing generated Matroska fixture with English ASS at 640×480 and Spanish ASS at 1920×1080, identical raw placement tags; generated SubRip sidecar. No private media or device playback claim.
• Regression coverage: two independent headers/raw events, default headerless output, ASS-to-SubRip/embedded selection, independent clear, cancelled publication, stop, carryover restoration and WebVTT staying text.
• Strict cooperative-pool focused run: 34 Swift Testing tests passed. Full serial run passed: 795 XCTest (one existing skip) and 4620 Swift Testing tests / 634 suites.
• The initial full parallel run failed only in the existing SoftwarePacketMemoryFIFOTests history-walk assertion with invalidCursor; reclaimable-history test assumptions are also addressed by open test(cache): respect kernel purges in history eviction checks #819. No unrelated tests were edited; failed evidence was retained.
• Documentation links and git diff --check passed.
• Valid Apple Development signing and verification for local test executables; no ad-hoc signing.

Checklist

• CHANGELOG.md updated
• Conventional commit
• Fix lives in the engine
• Public API documented

[superuser404notfound]

Thanks @orut34iop, this is a clean, well-scoped change.

Review notes:

• The embedded secondary path already builds its drain decoder with preserveASSMarkup, so secondary ASS reached hosts as raw event lines from that path but as cleaned text from a sidecar. This PR makes the channel consistent, and the separate secondarySidecarASSHeader is the right shape since PlayRes and styles differ per script (the 640/1920 fixture shows it well).
• Reset points look complete: new sidecar, embedded selection, clearSecondarySubtitle(), stopInternal(). Publication stays behind the cancellation and active-channel guards, and after the merge also behind #822's load-generation guard.
• Conflict with #822 in startSecondarySidecarDecode was additive on both sides; resolved by keeping the origin-aware header resolution plus the generation capture and adding the preserveASS capture.
• Changelog entry moved into [Unreleased] (the auto-merge had placed it under 7.40.0) and rewritten in house style.

Verified on the merged tree: 780 XCTest (1 skipped, 0 failures) and 4711 Swift Testing tests in 650 suites, all passing.

Merging.

[superuser404notfound]

Released in 7.45.0 (52802af).