Add chapter markers and chapter title display

[ceyhun-o]

Summary

Adds chapter support to the seek bar and the default UI.

• <theoplayer-time-range show-chapter-markers> renders a <theoplayer-time-range-chapter-markers part="chapters">. It draws one segment per cue of the first chapters text track that has mode === 'showing', loaded cues and no load error. Segments expose part="chapter" plus the active, hover and discontinuous tokens, and these are forwarded with exportparts so theoplayer-time-range::part(chapter) still works. Markers are hidden while a linear ad plays.
  • Positions are pure CSS, so no ResizeObserver is needed. Inner boundaries use the thumb mapping, calc(var(--theoplayer-range-thumb-width) / 2 + fraction * (100% - var(--theoplayer-range-thumb-width))), so the thumb lands exactly on a chapter start. The first and last visible segments are flush with the edges of the bar.
  • TimeRange only passes player, min, max and hoverTime. The markers component watches the chapter track itself.
  • The seek bar's aria-valuetext gets the chapter title appended, through the new timeRangeChapterAriaValueText locale entry.
• <theoplayer-chapter-display> shows the chapter title at the preview time while hovering or dragging the seek bar, and otherwise at the current time. It is hidden when there is no title. Its size can be set with --theoplayer-chapter-display-font-size (default 16px).
• New previewActive state, sent with theoplayerpreviewactivechange and forwarded by UIContainer to state receivers. It is needed because previewTime keeps its last value after the pointer leaves the seek bar.
• <theoplayer-default-ui> turns on show-chapter-markers and shows the chapter display in its own row above the seek bar.
• React: ChapterDisplay and TimeRangeChapterMarkers wrappers. Also: a "Sintel with chapters" example source and docs.

Teardown fix

Removing a <theoplayer-ui> or <theoplayer-default-ui> (or unmounting it in React) threw TypeErrors from components that read player.textTracks, audioTracks or videoTracks on a player that UIContainer.disconnectedCallback had already destroyed. This also affected the existing audio and quality menus. Now:

- this._player.destroy();
  this._player = undefined;
  this.propagatePlayerToAllReceivers_();
+ player.destroy();

TimeRange also passes the player to its chapter markers synchronously in its player setter, through a ref, instead of waiting for the next render, so the markers detach before the player is destroyed. This has its own patch changeset.

Testing

Verified manually with real playback of the Sintel HLS stream and its side-loaded WebVTT chapters:

• 7 segments; at 6:00 "In pursuit" is active.
• Hovering shows "A dangerous quest", and leaving restores "In pursuit".
• The outer segments are flush with the edges of the bar.
• At a chapter start, the boundary is within 0.01px of the thumb centre at 1280px and 800px, including after resizing without a reload.
• A source without chapters shows no markers and no title.
• Keyboard: Home, End and the arrow keys update the title, the active marker and aria-valuetext.
• Ads (CSAI VAST): markers and title are hidden during the linear ad and come back afterwards, alongside the ad marker.
• React: DefaultUI and a custom UIContainer with TimeRange showChapterMarkers + ChapterDisplay, including hover.
• Teardown: removing the Default UI and unmounting React DefaultUI threw 6 uncaught errors before the fix and 0 after. The player is still destroyed.

test:typecheck, test:unit, build and test:docs pass.

Not tested: live/DVR streams. Touch was only checked with emulated touch in Chrome. During a touch drag, Chrome sends pointercancel, which ends the chapter preview and the existing preview box, while the seek keeps following the finger.

Link to Devin session: https://dolby.devinenterprise.com/sessions/50775d66d51648e18b378055b508b80a
Open in Devin Desktop: https://dolby.devinenterprise.com/desktop/session/50775d66d51648e18b378055b508b80a?variant=devin
Requested by: @ceyhun-o

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[changeset-bot]

🦋 Changeset detected

Latest commit: ba5dc4c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@theoplayer/web-ui	Minor
@theoplayer/react-ui	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR