@amazon/vinyl 1.1.1 → 1.2.1

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

@@ -0,0 +1,231 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Approximate row height for integer (snap-to-lines) `line` offsets. */
+const ROW_EM = 1.5;
+/**
+ * Maps a cue's WebVTT positioning settings to inline CSS. Pure and DOM-free so
+ * the (branchy) placement logic is unit-testable in isolation.
+ *
+ * A cue with neither `line` nor `position` set flows in the renderer's
+ * bottom-anchored, centered container (the common subtitle case). Otherwise it
+ * is absolutely positioned: `size` → width, `position`/`positionAlign` →
+ * horizontal, `line`/`lineAlign`/`snapToLines` → vertical (percentage lines, or
+ * whole rows counted from the bottom for negative integers), `align` → text
+ * alignment, `vertical` → writing mode.
+ */
+export function computeCueLayout(cue) {
+    const style = {};
+    // WebVTT's default text alignment is 'center'.
+    style.textAlign = cue.align || 'center';
+    if (cue.vertical === 'rl')
+        style.writingMode = 'vertical-rl';
+    else if (cue.vertical === 'lr')
+        style.writingMode = 'vertical-lr';
+    const size = typeof cue.size === 'number' ? cue.size : 100;
+    style.maxWidth = `${size}%`;
+    const line = typeof cue.line === 'number' ? cue.line : null;
+    const position = typeof cue.position === 'number' ? cue.position : null;
+    if (line == null && position == null)
+        return style;
+    style.position = 'absolute';
+    const transforms = [];
+    if (position == null) {
+        style.left = '50%';
+        transforms.push('translateX(-50%)');
+    }
+    else {
+        if (cue.positionAlign === 'line-right') {
+            style.right = `${100 - position}%`;
+        }
+        else if (cue.positionAlign === 'line-left') {
+            style.left = `${position}%`;
+        }
+        else {
+            style.left = `${position}%`;
+            transforms.push('translateX(-50%)');
+        }
+    }
+    if (line == null) {
+        style.bottom = '0';
+    }
+    else {
+        if (cue.snapToLines === false) {
+            if (cue.lineAlign === 'end') {
+                style.bottom = `${100 - line}%`;
+            }
+            else if (cue.lineAlign === 'center') {
+                style.top = `${line}%`;
+                transforms.push('translateY(-50%)');
+            }
+            else {
+                style.top = `${line}%`;
+            }
+        }
+        else if (line < 0) {
+            style.bottom = `${(-line - 1) * ROW_EM}em`;
+        }
+        else {
+            style.top = `${line * ROW_EM}em`;
+        }
+    }
+    if (transforms.length > 0)
+        style.transform = transforms.join(' ');
+    return style;
+}
+const HTML_ESCAPE = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+};
+/** Escapes text (and attribute values) for safe insertion via innerHTML. */
+function escapeHtml(text) {
+    // Character class, no backtracking.
+    return text.replace(/["&<>]/g, (ch) => HTML_ESCAPE[ch]);
+}
+// WebVTT inline tags rendered as the matching HTML element.
+const PASSTHROUGH_TAGS = new Set(['i', 'b', 'u', 'ruby', 'rt']);
+// Tags rendered as a <span> (styling/metadata carried via class/attributes).
+const SPAN_TAGS = new Set(['c', 'v', 'lang']);
+/** Opening HTML for a WebVTT start tag `inner` (the text between `<` and `>`). */
+function openTag(inner) {
+    // Timestamp tags (`<00:00:00.000>`) carry no styling — drop them.
+    if (/^\d/.test(inner))
+        return '';
+    // The head (before any annotation) is `name` plus `.class` segments.
+    const head = inner.split(/\s/, 1)[0];
+    const [name, ...classes] = head.split('.');
+    const annotation = inner.slice(head.length).trim();
+    const classAttr = classes.filter(Boolean).length
+        ? ` class="${escapeHtml(classes.filter(Boolean).join(' '))}"`
+        : '';
+    if (PASSTHROUGH_TAGS.has(name))
+        return `<${name}${classAttr}>`;
+    if (name === 'v') {
+        const title = annotation ? ` title="${escapeHtml(annotation)}"` : '';
+        return `<span${classAttr}${title}>`;
+    }
+    if (name === 'lang') {
+        const lang = annotation ? ` lang="${escapeHtml(annotation)}"` : '';
+        return `<span${classAttr}${lang}>`;
+    }
+    if (name === 'c')
+        return `<span${classAttr}>`;
+    return ''; // unknown tag: drop
+}
+/** Closing HTML for a WebVTT end tag named `name`. */
+function closeTag(name) {
+    if (PASSTHROUGH_TAGS.has(name))
+        return `</${name}>`;
+    if (SPAN_TAGS.has(name))
+        return '</span>';
+    return '';
+}
+/**
+ * Renders a cue's text payload as safe HTML. Text is escaped (so it can't
+ * inject nodes); newlines become `<br>`; and WebVTT cue tags are converted:
+ * `<c.foo>`→`<span class="foo">`, `<i>/<b>/<u>/<ruby>/<rt>` pass through,
+ * `<v Name>`→`<span title>`, `<lang xx>`→`<span lang>`, timestamp tags are
+ * dropped. Class-based styling requires matching app CSS (STYLE blocks in the
+ * VTT are not applied).
+ */
+export function renderCueText(text) {
+    let html = '';
+    // Each match is one tag (`<…>`), a run of non-`<` text, or a stray `<`.
+    // The tag body excludes `<` (as well as `>`) so a failed tag match on a
+    // `<`-heavy string bails after one char rather than scanning to the end —
+    // keeping this linear (no polynomial backtracking) on adversarial input.
+    for (const token of text.match(/<[^<>]*>|[^<]+|</g) ?? []) {
+        if (token[0] !== '<' || token === '<') {
+            html += escapeHtml(token).replace(/\n/g, '<br>');
+        }
+        else {
+            const inner = token.slice(1, -1);
+            html +=
+                inner[0] === '/'
+                    ? closeTag(inner.slice(1).split(/[.\s]/, 1)[0].toLowerCase())
+                    : openTag(inner);
+        }
+    }
+    return html;
+}
+/**
+ * Rewrites a WebVTT `STYLE` block's `::cue` selectors to target this renderer's
+ * HTML cue elements: `::cue(<sel>)` → `.vinyl-text-cue <sel>` (cue components
+ * become descendants of the cue box) and bare `::cue` → `.vinyl-text-cue`.
+ * Rules are global to `.vinyl-text-cue`, so concurrent players share them.
+ */
+function scopeCueRules(css) {
+    // Bounded character classes; no nested quantifiers, so no backtracking blowup.
+    return css
+        .replace(/::cue\(([^)]*)\)/g, '.vinyl-text-cue $1')
+        .replace(/::cue\b/g, '.vinyl-text-cue');
+}
+/**
+ * A {@link TextTrackRenderer} that paints cues as HTML into {@link element}.
+ * Mount `element` over the video; it stacks cues at the bottom, centered, and
+ * positions any cue that carries explicit WebVTT settings. The DOM track is
+ * expected to be `'hidden'` so only this renderer paints.
+ */
+export class HtmlTextTrackRenderer {
+    /** The overlay container to mount over the video. */
+    element;
+    track = null;
+    // Holds the authored STYLE-block CSS (::cue rules rewritten to target our
+    // cue elements). A <style> renders nothing itself, so it lives in-container.
+    styleElement;
+    onCueChange = () => this.renderActiveCues();
+    constructor() {
+        this.element = document.createElement('div');
+        this.element.className = 'vinyl-text-container';
+        Object.assign(this.element.style, {
+            display: 'flex',
+            flexDirection: 'column',
+            justifyContent: 'flex-end',
+            alignItems: 'center',
+            pointerEvents: 'none',
+        });
+        this.styleElement = document.createElement('style');
+        this.element.appendChild(this.styleElement);
+    }
+    setTextTrack(track) {
+        if (track === this.track)
+            return;
+        this.track?.removeEventListener('cuechange', this.onCueChange);
+        this.track = track;
+        // Drop the previous track's authored styles; the new one supplies its
+        // own via setStyles once loaded.
+        this.styleElement.textContent = '';
+        if (!track) {
+            this.element.replaceChildren(this.styleElement);
+            return;
+        }
+        track.addEventListener('cuechange', this.onCueChange);
+        this.renderActiveCues();
+    }
+    setStyles(styles) {
+        this.styleElement.textContent = styles.map(scopeCueRules).join('\n');
+    }
+    dispose() {
+        this.setTextTrack(null);
+    }
+    renderActiveCues() {
+        // Only invoked while a track is attached (from setTextTrack / cuechange).
+        const active = this.track.activeCues ?? [];
+        // Keep the <style> element; replace only the cue boxes.
+        const children = [this.styleElement];
+        for (let i = 0; i < active.length; i++) {
+            children.push(this.createCueBox(active[i]));
+        }
+        this.element.replaceChildren(...children);
+    }
+    createCueBox(cue) {
+        const box = document.createElement('div');
+        box.className = 'vinyl-text-cue';
+        Object.assign(box.style, computeCueLayout(cue));
+        box.innerHTML = renderCueText(cue.text ?? '');
+        return box;
+    }
+}

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

@@ -0,0 +1,103 @@
+import { EventHostImpl, type Maybe, type RequestInitOptions } from '@amazon/vinyl-util';
+import type { TextTrackController, TextTrackControllerOptions, TextTrackEventMap, TextTrackInfo } from './TextTrack';
+import type { ObservableValue } from '@amazon/vinyl-observable';
+import type { MediaTextTrackProvider } from './mediaTextTrackProvider';
+import type { ReadonlyPlaybackController } from '../playback/ReadonlyPlaybackController';
+import type { TextTrackRenderer } from './TextTrackRenderer';
+export interface SidecarTextTrackControllerDeps {
+    /**
+     * Hands out (memoized) DOM text tracks. Text tracks can only be created on a
+     * media element and never removed, so the provider reuses one track per
+     * rendition rather than accumulating them.
+     */
+    readonly textTrackProvider: MediaTextTrackProvider;
+    /**
+     * Optional request init options forwarded with each VTT fetch (e.g. CORS).
+     */
+    readonly requestInit?: Maybe<RequestInitOptions>;
+    /**
+     * The discovered text tracks, re-emitted whenever the manifest changes.
+     */
+    readonly textTracks: ObservableValue<Promise<readonly TextTrackInfo[]>>;
+    /**
+     * Declarative selection / rendering configuration. Re-applied on change.
+     */
+    readonly options: ObservableValue<TextTrackControllerOptions>;
+    /**
+     * Supplies the current playhead used to fetch caption segments in a window
+     * around it.
+     */
+    readonly playbackController: ReadonlyPlaybackController;
+    /**
+     * Optional renderer that paints cues itself (HTML overlay). When provided,
+     * the DOM text track is kept `'hidden'` (timing only) and the renderer is
+     * handed the active track; without one, the track renders natively
+     * (`'showing'`).
+     */
+    readonly textTrackRenderer?: Maybe<TextTrackRenderer>;
+}
+/**
+ * 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 declare function resolveSelectedTrack(tracks: readonly TextTrackInfo[], options: TextTrackControllerOptions): TextTrackInfo | null;
+/**
+ * Manages a sidecar WebVTT-based text track lifecycle:
+ *
+ *  - 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 agnostic of HLS/DASH discovery details; its inputs are the
+ * observables supplied by the manifest layer.
+ */
+export declare class SidecarTextTrackController extends EventHostImpl<TextTrackEventMap> implements TextTrackController {
+    private readonly deps;
+    get [Symbol.toStringTag](): string;
+    private _active;
+    private _tracks;
+    private _activeTextTrack;
+    private _ref;
+    private readonly loadAbort;
+    private readonly disposer;
+    constructor(deps: SidecarTextTrackControllerDeps);
+    get textTracks(): readonly TextTrackInfo[];
+    get activeTextTrack(): TextTrackInfo | null;
+    get active(): boolean;
+    get disposed(): boolean;
+    /**
+     * Replaces the discovered track list, emits `textTracksChange`, then
+     * re-applies the current selection against the new list.
+     */
+    private setTracks;
+    /**
+     * Recomputes the selection from the current options and track list,
+     * emitting `activeTextTrackChange` on change and (re)rendering when active.
+     */
+    private refreshSelection;
+    deactivate(): void;
+    activate(): void;
+    private startLoad;
+    private appendCues;
+    /**
+     * Clears cues from the current DOM track and hides it, keeping the track for
+     * later reuse via the provider.
+     */
+    private hideCurrent;
+    /**
+     * Cancels any in-flight load, hides the DOM text track, and resets state.
+     * Called by the host when the underlying media is unloaded.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=SidecarTextTrackController.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,250 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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:
+ *
+ *  - 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 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 = [];
+    _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;
+        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 track list, emits `textTracksChange`, then
+     * re-applies the current selection against the new list.
+     */
+    setTracks(tracks) {
+        if (this.disposed)
+            return;
+        const previous = this._tracks;
+        if (equalDeep(previous, tracks))
+            return;
+        this._tracks = tracks;
+        this.dispatch('textTracksChange', { previous, current: tracks });
+        this.refreshSelection();
+    }
+    /**
+     * Recomputes the selection from the current options and track list,
+     * emitting `activeTextTrackChange` on change and (re)rendering when active.
+     */
+    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;
+        // 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);
+    }
+    deactivate() {
+        this._active = false;
+        this.hideCurrent();
+    }
+    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) {
+        // 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 (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: () => this.deps.playbackController.currentTime,
+            onCues: (cues) => {
+                if (abort.aborted())
+                    return;
+                if (CueCtor)
+                    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;
+            this.dispatch('textTrackError', {
+                track,
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        });
+    }
+    appendCues(dom, CueCtor, cues, seen) {
+        for (const cue of cues) {
+            const key = `${cue.startTime}|${cue.endTime}|${cue.text}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const domCue = new CueCtor(cue.startTime, cue.endTime, cue.text);
+            if (cue.id != null)
+                domCue.id = cue.id;
+            // 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);
+        }
+    }
+    /**
+     * 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;
+        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() {
+    const g = globalThis;
+    return g.VTTCue ?? g.TextTrackCue ?? null;
+}

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

@@ -0,0 +1,65 @@
+import type { Maybe, ReadonlyAbort, RequestInitOptions } from '@amazon/vinyl-util';
+import { type WebVttCue } from './parseWebVtt';
+/**
+ * Seconds ahead of the playhead to keep cues buffered. Mirrors the media
+ * pipeline's default HLS `minBufferTime` so captions stay in step with the
+ * audio/video buffer.
+ */
+export declare const DEFAULT_TEXT_LOOK_AHEAD = 10;
+/**
+ * Seconds behind the playhead to keep cues buffered. Small window so that a
+ * short rewind (e.g. accidental skip-back) doesn't force a refetch.
+ */
+export declare const DEFAULT_TEXT_LOOK_BEHIND = 2;
+export interface LoadWebVttCuesOptions {
+    readonly abort?: Maybe<ReadonlyAbort>;
+    readonly requestInit?: Maybe<RequestInitOptions>;
+    /**
+     * HLS EXT-X-DEFINE variables to make available for `IMPORT` and for
+     * substitution of segment URIs when loading from an HLS media playlist.
+     */
+    readonly variables?: Maybe<Readonly<Record<string, string>>>;
+    /**
+     * Invoked with each batch of cues as soon as they are parsed. Called once
+     * 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
+     * playhead rather than draining the entire playlist up front.
+     */
+    readonly getCurrentTime: () => number;
+    /**
+     * Seconds ahead of the playhead to keep buffered. Default 10s.
+     */
+    readonly lookAhead?: Maybe<number>;
+    /**
+     * Seconds behind the playhead to keep buffered. Default 2s.
+     */
+    readonly lookBehind?: Maybe<number>;
+}
+/**
+ * Loads WebVTT cues from a URI, streaming them by playhead position.
+ *
+ * Two URI shapes are accepted:
+ *  - Direct `.vtt` document: fetched once and delivered via `onCues`.
+ *  - HLS media playlist (`.m3u8`): the playlist is parsed, then segments
+ *    whose time range overlaps the buffer window around `getCurrentTime()`
+ *    are fetched (closest to the playhead first), one at a time. Each
+ *    segment's cues are delivered via `onCues` as it is parsed.
+ *
+ * Cue start/end times are expected to already be on the presentation
+ * timeline (Shaka packager's default WebVTT output), so segments are joined
+ * without offset.
+ *
+ * The returned promise resolves once every segment has been fetched, or the
+ * abort signal fires. Fetch failures reject the promise.
+ */
+export declare function loadWebVttCues(uri: string, options: LoadWebVttCuesOptions): Promise<void>;
+//# sourceMappingURL=SidecarTextTrackLoader.d.ts.map

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

@@ -0,0 +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;;;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"}