@amazon/vinyl 2.0.0 → 3.0.0

package/dist/types/current/text/SidecarTextTrackController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SidecarTextTrackController.d.ts","sourceRoot":"","sources":["../../../../src/text/SidecarTextTrackController.ts"],"names":[],"mappings":"AAKA,OAAO,EAGH,aAAa,EACb,KAAK,KAAK,EACV,KAAK,kBAAkB,EAE1B,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EACR,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EAChB,MAAM,aAAa,CAAA;AAGpB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAE/D,OAAO,EAA8B,KAAK,WAAW,EAAE,MAAM,eAAe,CAAA;AAE5E,MAAM,WAAW,8BAA8B;IAC3C;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAA;IAEvC;;OAEG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAA;IAEhD;;;;;;;OAOG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,eAAe,CAC5C,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,IAAI,CACpC,CAAA;IAED;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;CAC1D;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,0BACT,SAAQ,aAAa,CAAC,iBAAiB,CACvC,YAAW,mBAAmB;IAelB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAbjC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,MAAM,CAEjC;IAED,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,SAAS,CAAqB;IAGtC,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAoB;gBAE5B,IAAI,EAAE,8BAA8B;IAQjE,IAAI,UAAU,IAAI,SAAS,aAAa,EAAE,CAEzC;IAED,IAAI,eAAe,IAAI,aAAa,GAAG,IAAI,CAE1C;IAED;;;;OAIG;IACH,aAAa,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,GAAG,IAAI;IAuBrD,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAM3C;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAO9B;;;OAGG;IACH,OAAO,CAAC,UAAU;IAiBlB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAavB,OAAO,IAAI,IAAI;IAMf,MAAM,IAAI,IAAI;IAQd;;;OAGG;IACH,OAAO,IAAI,IAAI;IAUf,OAAO,CAAC,SAAS;IAoCjB,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,UAAU;IAuBlB,OAAO,CAAC,aAAa;CAexB"}
+{"version":3,"file":"SidecarTextTrackController.d.ts","sourceRoot":"","sources":["../../../../src/text/SidecarTextTrackController.ts"],"names":[],"mappings":"AAKA,OAAO,EAKH,aAAa,EAEb,KAAK,KAAK,EACV,KAAK,kBAAkB,EAC1B,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EACR,mBAAmB,EACnB,0BAA0B,EAC1B,iBAAiB,EACjB,aAAa,EAChB,MAAM,aAAa,CAAA;AAGpB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAG/D,OAAO,KAAK,EACR,sBAAsB,EAEzB,MAAM,0BAA0B,CAAA;AACjC,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,wCAAwC,CAAA;AACxF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,MAAM,WAAW,8BAA8B;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,EAAE,sBAAsB,CAAA;IAElD;;OAEG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAA;IAEhD;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAAC,CAAA;IAEvE;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC,0BAA0B,CAAC,CAAA;IAE7D;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,EAAE,0BAA0B,CAAA;IAEvD;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,KAAK,CAAC,iBAAiB,CAAC,CAAA;CACxD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAChC,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,OAAO,EAAE,0BAA0B,GACpC,aAAa,GAAG,IAAI,CAiBtB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,0BACT,SAAQ,aAAa,CAAC,iBAAiB,CACvC,YAAW,mBAAmB;IAkBlB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAhBjC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,MAAM,CAEjC;IAID,OAAO,CAAC,OAAO,CAAQ;IAEvB,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,gBAAgB,CAA6B;IAGrD,OAAO,CAAC,IAAI,CAA4B;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA+B;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;gBAEf,IAAI,EAAE,8BAA8B;IAmBjE,IAAI,UAAU,IAAI,SAAS,aAAa,EAAE,CAEzC;IAED,IAAI,eAAe,IAAI,aAAa,GAAG,IAAI,CAE1C;IAED,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;OAGG;IACH,OAAO,CAAC,SAAS;IASjB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAqBxB,UAAU,IAAI,IAAI;IAKlB,QAAQ,IAAI,IAAI;IAOhB,OAAO,CAAC,SAAS;IAwDjB,OAAO,CAAC,UAAU;IAqBlB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAYnB;;;OAGG;IACH,OAAO,IAAI,IAAI;CASlB"}

package/dist/types/current/text/SidecarTextTrackController.js

@@ -2,185 +2,191 @@
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
-import { Abort, equalDeep, EventHostImpl, } from '@amazon/vinyl-util';
+import { createAbortSlot, createDisposer, equalDeep, EventHostImpl, logError, } from '@amazon/vinyl-util';
 import { loadWebVttCues } from './SidecarTextTrackLoader';
 import { pickPreferredTextTrack } from './pickPreferredTextTrack';
 import { applyVttCueStyle, isVttCue } from './VttCueStyle';
+/**
+ * Selects the text track that matches the given options, or null for none.
+ *
+ * The `enabled` mode gates everything: `'off'` renders nothing (default is
+ * `'forced'`). Otherwise an explicit {@link TextTrackSelection.id} wins; else
+ * the best language match is chosen among tracks filtered by kind and
+ * forced-ness. Forced-ness comes from {@link TextTrackSelection.forced} when
+ * set, otherwise from the mode (`'forced'` keeps only forced tracks, `'on'`
+ * only full tracks).
+ *
+ * @private
+ */
+export function resolveSelectedTrack(tracks, options) {
+    const mode = options.enabled ?? 'forced';
+    if (mode === 'off')
+        return null;
+    const selection = options.selection ?? {};
+    if (selection.id != null) {
+        return tracks.find((t) => t.id === selection.id) ?? null;
+    }
+    let pool = tracks;
+    if (selection.kind != null) {
+        pool = pool.filter((t) => t.kind === selection.kind);
+    }
+    // Explicit forced filter overrides the mode's forced/full split.
+    const forced = selection.forced ?? mode === 'forced';
+    pool = pool.filter((t) => t.forced === forced);
+    // pickPreferredTextTrack falls back to navigator.languages when no language
+    // preference is supplied.
+    return pickPreferredTextTrack(pool, selection.language);
+}
 /**
  * Manages a sidecar WebVTT-based text track lifecycle:
  *
- *  - holds a discovered list of {@link TextTrackInfo}
- *  - on activation, fetches the chosen track's WebVTT and pushes cues to a
- *    `TextTrack` created on the `HTMLMediaElement`
- *  - clears any previously activated cues when switching tracks
+ *  - tracks the discovered {@link TextTrackInfo} list (from the `textTracks`
+ *    observable) and the current selection (from the `options` observable)
+ *  - on selection, fetches the chosen track's WebVTT and pushes cues to a DOM
+ *    `TextTrack` obtained from the {@link MediaTextTrackProvider}
+ *  - clears cues and hides the DOM track when the selection changes or clears
  *
- * The controller is intentionally agnostic of HLS/DASH discovery details. Its
- * input is whatever list of {@link TextTrackInfo} entries the manifest layer
- * decides to surface.
+ * The controller is agnostic of HLS/DASH discovery details; its inputs are the
+ * observables supplied by the manifest layer.
  */
 export class SidecarTextTrackController extends EventHostImpl {
     deps;
     get [Symbol.toStringTag]() {
         return 'SidecarTextTrackController';
     }
+    // Whether the owning media track is current (rendering allowed). Toggled by
+    // activate()/deactivate() across suspensions such as ad breaks.
+    _active = false;
     _tracks = [];
-    _active = null;
-    _domTrack = null;
-    loadAbort = null;
-    // True once the app has made an explicit selection (including null). Until
-    // then, forced tracks auto-select on discovery.
-    _userSelected = false;
-    preferredLanguageSub;
+    _activeTextTrack = null;
+    // The DOM text track currently rendering cues, or null when hidden. Owned by
+    // the provider (never created/removed here).
+    _ref = null;
+    loadAbort = createAbortSlot();
+    disposer = createDisposer();
     constructor(deps) {
         super();
         this.deps = deps;
-        this.preferredLanguageSub =
-            deps.preferredTextLanguage?.onData((value, previous) => {
-                if (previous !== undefined)
-                    this.applyPreferredLanguage(value);
-            }) ?? null;
+        const { add } = this.disposer;
+        // Both fire immediately with the current value, resolving the initial
+        // track list and selection on construction.
+        add(deps.options.onData(() => this.refreshSelection()));
+        add(deps.textTracks.onData((tracksPromise) => {
+            tracksPromise
+                .then((tracks) => this.setTracks(tracks))
+                .catch((error) => {
+                // Manifest errors surface through the manifest
+                // controller; just note and don't double-report.
+                logError(this, 'text tracks promise rejected', error);
+            });
+        }));
     }
     get textTracks() {
         return this._tracks;
     }
     get activeTextTrack() {
+        return this._activeTextTrack;
+    }
+    get active() {
         return this._active;
     }
+    get disposed() {
+        return this.disposer.disposed;
+    }
     /**
-     * Replaces the discovered text track list. Emits `textTracksChange`. If
-     * the previously active track is no longer present, clears the active
-     * selection and emits `activeTextTrackChange`.
+     * Replaces the discovered track list, emits `textTracksChange`, then
+     * re-applies the current selection against the new list.
      */
-    setTextTracks(tracks) {
-        if (equalDeep(this._tracks, tracks))
+    setTracks(tracks) {
+        if (this.disposed)
             return;
         const previous = this._tracks;
+        if (equalDeep(previous, tracks))
+            return;
         this._tracks = tracks;
         this.dispatch('textTracksChange', { previous, current: tracks });
-        if (this._active && !tracks.some((t) => t.id === this._active.id)) {
-            // Clear a now-absent selection, but keep _userSelected intact.
-            this.selectById(null);
-        }
-        // A preferred language re-selects the best match as the list changes;
-        // otherwise auto-show forced captions until the app makes an explicit
-        // choice.
-        const preferred = this.deps.preferredTextLanguage?.value;
-        if (preferred != null) {
-            this.applyPreferredLanguage(preferred);
-        }
-        else if (!this._userSelected && !this._active) {
-            const forced = this.pickForcedTrack(tracks);
-            if (forced)
-                this.selectById(forced.id);
-        }
-    }
-    setActiveTextTrack(id) {
-        // An explicit app choice; stop auto-selecting forced tracks.
-        this._userSelected = true;
-        this.selectById(id);
-    }
-    /**
-     * Selects the track best matching the preferred language(s), or clears the
-     * selection when the preference is null or nothing matches.
-     */
-    applyPreferredLanguage(preferred) {
-        const target = pickPreferredTextTrack(this._tracks, preferred);
-        this.setActiveTextTrack(target?.id ?? null);
+        this.refreshSelection();
     }
     /**
-     * Applies a selection by id (null clears it) without marking it as an
-     * explicit user choice. Shared by setActiveTextTrack and forced auto-select.
+     * Recomputes the selection from the current options and track list,
+     * emitting `activeTextTrackChange` on change and (re)rendering when active.
      */
-    selectById(id) {
-        const next = id == null ? null : this._tracks.find((t) => t.id === id);
-        if (id != null && !next)
-            return; // unknown id is a no-op
-        const target = next ?? null;
-        if (target?.id === this._active?.id)
+    refreshSelection() {
+        const previous = this._activeTextTrack;
+        const target = resolveSelectedTrack(this._tracks, this.deps.options.value);
+        const trackChanged = target?.id !== previous?.id;
+        if (trackChanged) {
+            this._activeTextTrack = target;
+            this.dispatch('activeTextTrackChange', {
+                previous,
+                current: target,
+            });
+        }
+        if (!this._active)
             return;
-        const previous = this._active;
-        this.clearDomTrack();
-        this.loadAbort?.abort();
-        this.loadAbort = null;
-        this._active = target;
-        this.dispatch('activeTextTrackChange', {
-            previous,
-            current: target,
-        });
-        if (target)
+        // Cues carry their own authored styling, so only a track change (not a
+        // same-track options change) needs a (re)load.
+        if (!target)
+            this.hideCurrent();
+        else if (trackChanged || !this._ref)
             this.startLoad(target);
     }
-    /**
-     * The forced track to auto-select, or null. Prefers the default track's
-     * language, else the first forced track.
-     */
-    pickForcedTrack(tracks) {
-        const forced = tracks.filter((t) => t.forced);
-        if (forced.length === 0)
-            return null;
-        const defaultLang = tracks.find((t) => t.default)?.language;
-        if (defaultLang != null) {
-            const match = forced.find((t) => t.language === defaultLang);
-            if (match)
-                return match;
-        }
-        return forced[0];
-    }
-    suspend() {
-        this.loadAbort?.abort();
-        this.loadAbort = null;
-        this.clearDomTrack();
-    }
-    resume() {
-        // Rebuild only when an active selection exists and it isn't already
-        // rendering (clearDomTrack/suspend nulls _domTrack; setActiveTextTrack
-        // sets it).
-        if (!this._active || this._domTrack)
-            return;
-        this.startLoad(this._active);
+    deactivate() {
+        this._active = false;
+        this.hideCurrent();
     }
-    /**
-     * Cancels any in-flight load, clears the DOM TextTrack, and resets state.
-     * Called by the host when the underlying media is unloaded.
-     */
-    dispose() {
-        super.dispose();
-        this.preferredLanguageSub?.();
-        this.loadAbort?.abort();
-        this.loadAbort = null;
-        this.clearDomTrack();
-        this._tracks = [];
-        this._active = null;
+    activate() {
+        this._active = true;
+        // Rebuild only when a selection exists and it isn't already rendering.
+        if (!this._activeTextTrack || this._ref)
+            return;
+        this.startLoad(this._activeTextTrack);
     }
     startLoad(track) {
-        const media = this.deps.media;
-        // Without a media element there's nowhere to render cues and no
-        // playhead to drive segment selection, so skip fetching entirely.
-        // The active-selection state still surfaces via events.
-        if (!media)
-            return;
-        const abort = new Abort();
-        this.loadAbort = abort;
-        // Create the DOM TextTrack up front so cues render incrementally as
-        // segments arrive rather than after the whole playlist loads.
-        const dom = this.ensureDomTrack(media, track);
+        // Hide the previously-rendering track (a different rendition) so its
+        // cues don't linger alongside the new one; this also aborts any prior
+        // in-flight load and arms a fresh abort for this one.
+        this.hideCurrent();
+        const abort = this.loadAbort.value;
+        const ref = this.deps.textTrackProvider.getOrCreate(track.kind, track.label, track.language ?? undefined);
+        // With an injected renderer the browser must not paint (the renderer
+        // does), but the track still needs to be active for cue timing — hence
+        // 'hidden'. Without one, 'showing' uses native rendering. Set the mode
+        // before clearing: `cues` reads null while disabled.
+        const renderer = this.deps.textTrackRenderer;
+        ref.track.mode = renderer ? 'hidden' : 'showing';
+        ref.clear();
+        this._ref = ref;
+        renderer?.setTextTrack(ref.track);
         const CueCtor = getVttCueConstructor();
-        // Adjacent HLS caption segments commonly repeat the boundary cue in
-        // both segments (packagers do this so a client that only fetches one
-        // segment still renders the overlapping cue). Track seen keys per
-        // active load so we don't push the same cue twice.
+        // Adjacent HLS caption segments commonly repeat the boundary cue in both
+        // segments (so a client that only fetches one still renders the overlap).
+        // Track seen keys per active load so we don't push the same cue twice.
         const seen = new Set();
+        // Accumulate authored STYLE-block CSS and forward it to the renderer as
+        // it arrives — only wired when the renderer can actually consume styles.
+        const styles = new Set();
+        const setStyles = renderer?.setStyles?.bind(renderer);
         loadWebVttCues(track.uri, {
             abort,
             requestInit: this.deps.requestInit,
             variables: track.variables,
-            getCurrentTime: () => media.currentTime,
+            getCurrentTime: () => this.deps.playbackController.currentTime,
             onCues: (cues) => {
                 if (abort.aborted())
                     return;
                 if (CueCtor)
-                    this.appendCues(dom, CueCtor, cues, seen);
+                    this.appendCues(ref.track, CueCtor, cues, seen);
             },
+            onStyles: setStyles
+                ? (blocks) => {
+                    if (abort.aborted())
+                        return;
+                    for (const block of blocks)
+                        styles.add(block);
+                    setStyles([...styles]);
+                }
+                : undefined,
         }).catch((error) => {
             if (abort.aborted())
                 return;
@@ -190,12 +196,6 @@ export class SidecarTextTrackController extends EventHostImpl {
             });
         });
     }
-    ensureDomTrack(media, track) {
-        const dom = media.addTextTrack(track.kind, track.label, track.language ?? undefined);
-        dom.mode = 'showing';
-        this._domTrack = dom;
-        return dom;
-    }
     appendCues(dom, CueCtor, cues, seen) {
         for (const cue of cues) {
             const key = `${cue.startTime}|${cue.endTime}|${cue.text}`;
@@ -205,30 +205,43 @@ export class SidecarTextTrackController extends EventHostImpl {
             const domCue = new CueCtor(cue.startTime, cue.endTime, cue.text);
             if (cue.id != null)
                 domCue.id = cue.id;
-            // Apply the configured cue layout style (e.g. the default `size: 90`
-            // inset so long lines don't clip in fullscreen, which `::cue` CSS
-            // cannot fix). Only VTTCues carry these properties.
-            const cueStyle = this.deps.cueStyle?.value;
-            if (cueStyle && isVttCue(domCue)) {
-                applyVttCueStyle(domCue, cueStyle);
+            // Preserve the cue's own authored WebVTT settings (position, line,
+            // size, align, …). Only VTTCues carry these properties.
+            if (cue.settings && isVttCue(domCue)) {
+                applyVttCueStyle(domCue, cue.settings);
             }
             dom.addCue(domCue);
         }
     }
-    clearDomTrack() {
-        const dom = this._domTrack;
-        if (!dom)
+    /**
+     * Clears cues from the current DOM track and hides it, keeping the track for
+     * later reuse via the provider.
+     */
+    hideCurrent() {
+        // Cancel any in-flight load: its cues are no longer wanted, and a late
+        // rejection must not surface as a textTrackError.
+        this.loadAbort.abort();
+        const ref = this._ref;
+        if (!ref)
             return;
-        dom.mode = 'disabled';
-        // Best-effort: remove any cues we added so a future activation starts
-        // from a clean slate. Some platforms recreate the underlying TextTrack
-        // when the source changes; this is defensive.
-        if (dom.cues) {
-            const all = Array.from(dom.cues);
-            for (const cue of all)
-                dom.removeCue(cue);
-        }
-        this._domTrack = null;
+        this.deps.textTrackRenderer?.setTextTrack(null);
+        ref.clear();
+        ref.track.mode = 'disabled';
+        this._ref = null;
+    }
+    /**
+     * Cancels any in-flight load, hides the DOM text track, and resets state.
+     * Called by the host when the underlying media is unloaded.
+     */
+    dispose() {
+        if (this.disposed)
+            return;
+        super.dispose();
+        this.loadAbort.abort();
+        this.hideCurrent();
+        this.disposer.dispose();
+        this._tracks = [];
+        this._activeTextTrack = null;
     }
 }
 function getVttCueConstructor() {

package/dist/types/current/text/SidecarTextTrackLoader.d.ts

@@ -24,6 +24,11 @@ export interface LoadWebVttCuesOptions {
      * per HLS segment, or once for a direct `.vtt` document.
      */
     readonly onCues: (cues: readonly WebVttCue[]) => void;
+    /**
+     * Invoked with the CSS body of any `STYLE` blocks parsed from a document.
+     * Only called when a document actually declares styles.
+     */
+    readonly onStyles?: Maybe<(styles: readonly string[]) => void>;
     /**
      * Returns the current playback time (seconds on the presentation
      * timeline). Used to fetch caption segments in a window around the

package/dist/types/current/text/SidecarTextTrackLoader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SidecarTextTrackLoader.d.ts","sourceRoot":"","sources":["../../../../src/text/SidecarTextTrackLoader.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACR,KAAK,EACL,aAAa,EACb,kBAAkB,EACrB,MAAM,oBAAoB,CAAA;AAG3B,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,eAAe,CAAA;AAE3D;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAA;AAEzC;;;GAGG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAA;AAQzC,MAAM,WAAW,qBAAqB;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,CAAA;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAA;IAEhD;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;IAE5D;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,KAAK,IAAI,CAAA;IAErD;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,MAAM,CAAA;IAErC;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;IAElC;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;CACtC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,cAAc,CAChC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,qBAAqB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAsCf"}
+{"version":3,"file":"SidecarTextTrackLoader.d.ts","sourceRoot":"","sources":["../../../../src/text/SidecarTextTrackLoader.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACR,KAAK,EACL,aAAa,EACb,kBAAkB,EACrB,MAAM,oBAAoB,CAAA;AAG3B,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,eAAe,CAAA;AAE3D;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAA;AAEzC;;;GAGG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAA;AAQzC,MAAM,WAAW,qBAAqB;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,CAAA;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAA;IAEhD;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;IAE5D;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,KAAK,IAAI,CAAA;IAErD;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC,CAAA;IAE9D;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,MAAM,CAAA;IAErC;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;IAElC;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;CACtC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,cAAc,CAChC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,qBAAqB,GAC/B,OAAO,CAAC,IAAI,CAAC,CA0Cf"}

package/dist/types/current/text/SidecarTextTrackLoader.js

@@ -39,7 +39,7 @@ const IDLE_POLL_SECONDS = 0.25;
  * abort signal fires. Fetch failures reject the promise.
  */
 export async function loadWebVttCues(uri, options) {
-    const { abort, requestInit, variables, onCues, getCurrentTime } = options;
+    const { abort, requestInit, variables, onCues, onStyles, getCurrentTime } = options;
     const lookAhead = options.lookAhead ?? DEFAULT_TEXT_LOOK_AHEAD;
     const lookBehind = options.lookBehind ?? DEFAULT_TEXT_LOOK_BEHIND;
     const init = requestInit ?? undefined;
@@ -50,6 +50,7 @@ export async function loadWebVttCues(uri, options) {
             abort,
             variables: variables ?? undefined,
             onCues,
+            onStyles,
             getCurrentTime,
             lookAhead,
             lookBehind,
@@ -66,14 +67,17 @@ export async function loadWebVttCues(uri, options) {
             abort,
             variables: variables ?? undefined,
             onCues,
+            onStyles,
             getCurrentTime,
             lookAhead,
             lookBehind,
         });
     }
-    const cues = parseWebVtt(body).cues;
-    if (cues.length > 0)
-        onCues(cues);
+    const doc = parseWebVtt(body);
+    if (doc.cues.length > 0)
+        onCues(doc.cues);
+    if (onStyles && doc.styles.length > 0)
+        onStyles(doc.styles);
 }
 function looksLikeMediaPlaylist(uri) {
     const path = uri.split(/[?#]/)[0];
@@ -113,9 +117,11 @@ async function streamMediaPlaylistText(ctx) {
             abort: ctx.abort,
         });
         const body = await res.text();
-        const cues = parseWebVtt(body).cues;
-        if (cues.length > 0)
-            ctx.onCues(cues);
+        const doc = parseWebVtt(body);
+        if (doc.cues.length > 0)
+            ctx.onCues(doc.cues);
+        if (ctx.onStyles && doc.styles.length > 0)
+            ctx.onStyles(doc.styles);
     }
 }
 /**

package/dist/types/current/text/TextTrack.d.ts

@@ -1,5 +1,6 @@
 import type { ChangeEvent } from '../event/ChangeEvent';
 import type { ReadonlyEventHost } from '@amazon/vinyl-util';
+import type { ObjectSchema } from '@amazon/vinyl-validation';
 /**
  * Categorizes the role of a text track. Mirrors HTMLMediaElement.TextTrackKind.
  */
@@ -79,6 +80,64 @@ export interface TextTrackErrorEvent {
     readonly track: TextTrackInfo;
     readonly error: Error;
 }
+/**
+ * Which captions render:
+ * - `'off'` — nothing renders (not even forced narrative captions).
+ * - `'forced'` — only forced (narrative) tracks, so nothing shows unless the
+ *   content carries a forced track for the preferred language.
+ * - `'on'` — the full (non-forced) subtitle track for the preferred language.
+ */
+export type CaptionMode = 'on' | 'off' | 'forced';
+/**
+ * Criteria used to pick which text track to render. Applied in priority order:
+ * an explicit {@link id} wins; otherwise the best {@link language} match is
+ * chosen among tracks filtered by {@link kind} and by forced-ness (from
+ * {@link forced} when set, else from the controller's
+ * {@link TextTrackControllerOptions.enabled} mode).
+ */
+export interface TextTrackSelection {
+    /**
+     * Selects the text track with this exact identifier, ignoring the other
+     * criteria (but still gated by the `'off'` mode). If no track has this id,
+     * nothing is selected.
+     */
+    readonly id?: string | null;
+    /**
+     * Restricts selection to tracks of this kind (e.g. `'captions'`). Unset
+     * considers all kinds.
+     */
+    readonly kind?: TextTrackKind | null;
+    /**
+     * Preferred caption language(s), most-preferred first, as RFC 5646 tags.
+     * When unset (or empty) selection falls back to the platform's
+     * `navigator.languages`.
+     */
+    readonly language?: string | readonly string[] | null;
+    /**
+     * Explicit forced-ness filter. When set, only tracks whose `forced` flag
+     * equals this value are considered, overriding the forced/full split
+     * implied by the `enabled` mode. Unset means the mode decides.
+     */
+    readonly forced?: boolean | null;
+}
+/**
+ * Declarative configuration for a {@link TextTrackController}. Rendering is
+ * driven entirely by this value (via `VinylOptions.text`); there is no
+ * imperative track-select call.
+ */
+export interface TextTrackControllerOptions {
+    /**
+     * Which captions render (see {@link CaptionMode}). Unset defaults to
+     * `'forced'`.
+     */
+    readonly enabled?: CaptionMode | null;
+    /**
+     * The selection criteria (language / id / kind). When unset, the preferred
+     * languages fall back to the platform's `navigator.languages`.
+     */
+    readonly selection?: TextTrackSelection | null;
+}
+export declare const textTrackControllerOptionsValidator: ObjectSchema<TextTrackControllerOptions>;
 export declare const ALL_TEXT_TRACK_EVENTS: readonly ["textTracksChange", "activeTextTrackChange", "textTrackError"];
 /**
  * Read-only view of available text tracks and the active selection.
@@ -92,34 +151,29 @@ export interface ReadonlyTextTrackController extends ReadonlyEventHost<TextTrack
      * The currently active text track, or null if none is active.
      */
     readonly activeTextTrack: TextTrackInfo | null;
+    /**
+     * Returns true if this text track controller is active.
+     */
+    get active(): boolean;
 }
 /**
- * Provides access to the text tracks of the current media and allows
- * selecting one for playback.
- *
- * Selection is persisted across track changes only when applications choose
- * to call {@link setActiveTextTrack} again on the new track. This matches
- * how audio tracks are typically driven.
+ * Full controller for the current media's text tracks. Selection is driven
+ * declaratively through the controller's options (`VinylOptions.text`); this
+ * interface only adds the render lifecycle used by the owning media track.
  */
 export interface TextTrackController extends ReadonlyTextTrackController {
-    /**
-     * Selects the text track with the given id, or clears the active text
-     * track when called with null. No-op if the id does not match a known
-     * text track.
-     */
-    setActiveTextTrack(id: string | null): void;
     /**
      * Suspends cue rendering without changing the active selection: cancels any
-     * in-flight load and tears down the DOM text track (so its cues stop
-     * showing). Called when the owning media track is deactivated — e.g. while
-     * an ad plays over the suspended content. {@link resume} rebuilds it.
+     * in-flight load and hides the DOM text track (so its cues stop showing).
+     * Called when the owning media track is deactivated — e.g. while an ad
+     * plays over the suspended content. {@link activate} rebuilds it.
      */
-    suspend(): void;
+    deactivate(): void;
     /**
-     * Rebuilds the DOM text track for the active selection after a
-     * {@link suspend}, reloading its cues. No-op when nothing is active or when
-     * already rendering. Called when the owning media track is reactivated.
+     * Resumes rendering the active selection after a {@link deactivate},
+     * reloading its cues. No-op when nothing is selected or already rendering.
+     * Called when the owning media track is reactivated.
      */
-    resume(): void;
+    activate(): void;
 }
 //# sourceMappingURL=TextTrack.d.ts.map

package/dist/types/current/text/TextTrack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TextTrack.d.ts","sourceRoot":"","sources":["../../../../src/text/TextTrack.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAE3D;;GAEG;AACH,MAAM,MAAM,aAAa,GACnB,WAAW,GACX,UAAU,GACV,cAAc,GACd,UAAU,GACV,UAAU,CAAA;AAEhB;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC1B;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IAEnB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAE5B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAEhC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IAEtB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IAEzB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IAExB;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAA;IAE3C;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IAEpB;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAEhC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CACxD;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAC9B;;OAEG;IACH,QAAQ,CAAC,gBAAgB,EAAE,WAAW,CAAC,SAAS,aAAa,EAAE,CAAC,CAAA;IAEhE;;OAEG;IACH,QAAQ,CAAC,qBAAqB,EAAE,WAAW,CAAC,aAAa,GAAG,IAAI,CAAC,CAAA;IAEjE;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,mBAAmB,CAAA;CAC/C;AAED,MAAM,WAAW,mBAAmB;IAChC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;IAC7B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CACxB;AAED,eAAO,MAAM,qBAAqB,0EAIuB,CAAA;AAEzD;;GAEG;AACH,MAAM,WAAW,2BAA4B,SAAQ,iBAAiB,CAAC,iBAAiB,CAAC;IACrF;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAA;IAE7C;;OAEG;IACH,QAAQ,CAAC,eAAe,EAAE,aAAa,GAAG,IAAI,CAAA;CACjD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAoB,SAAQ,2BAA2B;IACpE;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAE3C;;;;;OAKG;IACH,OAAO,IAAI,IAAI,CAAA;IAEf;;;;OAIG;IACH,MAAM,IAAI,IAAI,CAAA;CACjB"}
+{"version":3,"file":"TextTrack.d.ts","sourceRoot":"","sources":["../../../../src/text/TextTrack.ts"],"names":[],"mappings":"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"}

package/dist/types/current/text/TextTrack.js

@@ -2,6 +2,26 @@
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
+import { array, boolean, isOneOf, object, string, } from '@amazon/vinyl-validation';
+const TEXT_TRACK_KINDS = [
+    'subtitles',
+    'captions',
+    'descriptions',
+    'chapters',
+    'metadata',
+];
+const textTrackSelectionValidator = object({
+    id: string().orNull().optional(),
+    kind: isOneOf(...TEXT_TRACK_KINDS)
+        .orNull()
+        .optional(),
+    language: string().or(array(string()).readonly()).orNull().optional(),
+    forced: boolean().orNull().optional(),
+});
+export const textTrackControllerOptionsValidator = object({
+    enabled: isOneOf('on', 'off', 'forced').orNull().optional(),
+    selection: textTrackSelectionValidator.orNull().optional(),
+});
 export const ALL_TEXT_TRACK_EVENTS = [
     'textTracksChange',
     'activeTextTrackChange',