Feature: Cuepoints Add-On for Media Components

[luwes]

Add a cuepoints capability for media stacks that can support it (timeline markers, ad or chapter-style events, or other time-based hooks), exposed as an optional add-on rather than baking it into every delegate. Implementation can use a class mixin pattern consistent with existing DOM media mixins (for example HlsJsMediaMetadataTracksMixin in @videojs/core).

Today the store already surfaces chaptersCues and metadata thumbnail cues from native text tracks (text-track feature), and hls.js delegates preserve metadata/chapters tracks via a mixin. A cuepoints add-on should clarify how programmatic or manifest-derived cuepoints integrate with that model—whether as a dedicated metadata track, synthetic cues, or a small state slice—and which components (HTML custom elements, React wrappers, SPF) opt in.

Context

• Video.js text tracks guide — chapters and metadata tracks, cuechange as the standard hook for time-based actions.
• Vidstack: Text tracks API and useActiveTextCues — cue lifecycle and active-cue subscription patterns in a modern player.
• MDN: TextTrack / cuechange — browser baseline for hidden metadata tracks and cue events.

[github-actions]

Triage Notes

Title updated → Feature: Cuepoints Add-On for Media Components

Labels added: media, pkg:core, pkg:html, pkg:react, api, spf, needs discussion

---

Relevant Docs

The text-track feature already surfaces cue state you'll want to build on:

• Text tracks reference (HTML) — chaptersCues, thumbnailCues, textTrackList state, and selectTextTracks selector
• Text tracks reference (React) — same state via usePlayer(selectTextTracks)

Directly related code in the repo:

• packages/core/src/dom/media/hls/metadata-tracks.ts — HlsJsMediaMetadataTracksMixin, the mixin pattern called out in the issue
• packages/core/src/dom/store/features/text-track.ts — where chaptersCues / thumbnailCues are currently derived
• packages/core/src/core/media/state.ts — MediaTextCue, MediaTextTrackState types

---

Design Question to Resolve First

The key open question before implementation: how do programmatic cuepoints integrate with the existing text-track model?

Three options worth evaluating:

1. Dedicated hidden metadata track — creates a native TextTrack with kind="metadata", cues are native VTTCue objects; cuechange fires automatically; consistent with browser baseline but limited state shape.
2. Synthetic state slice — a new store feature (cuepoints-feature) that manages an array of cuepoint objects and exposes an activeCuepoints selector; more flexible, no native track overhead.
3. Extend text-track feature — expose a programmatic API on top of the existing feature (e.g. addCuepoint, removeCuepoint) so cuepoints and native tracks stay in one feature.

---

Planning Recommendations

Related issues to coordinate with:

• Architecture: Text Track Spike — Actors, Reactors, and Primitives Reference Implementations #1158 — Architecture: Text Track Spike — ongoing SPF actors/reactors design for text tracks; cuepoints should align with or wait on this architecture decision
• Design: Strategy for Native Text Track Loading to Prevent Blocking Playback #988 — Design: Native Text Track Loading Strategy — native track loading approach will affect whether a synthetic metadata track is safe to add/remove dynamically
• Feature: Implement Multi Audio Tracks API for Supported Media Components #1261 — Feature: Multi Audio Tracks API — similar optional add-on pattern; useful reference for API shape and opt-in mechanism

Related open PR:

• feat(spf): architecture reactors #1218 (feat/spf-architecture-reactors-texttracks, DRAFT) — SPF text track reactor work; a cuepoints reactor would likely sit alongside this

Roadmap recommendation: Add to roadmap as a P2 item. The implementation path depends on decisions in #1158 and #988, so this is blocked by #1158 (text track architecture spike) until the actor/reactor model is settled. Not a strong fit for the current 26.2 milestone — suggest targeting 26.3 or post-GA once the text track architecture is stable.

Priority: P2 — useful capability, but no blocking use case for GA. Defer until text track architecture (#1158) is resolved.