@amazon/vinyl 1.2.0 → 1.2.2

package/dist/types/current/streaming/createTimelineContentTypesValue.d.ts

@@ -0,0 +1,21 @@
+import type { ContentTypesValue } from './ContentTypesValue';
+import type { MediaTimeline } from './MediaTimeline';
+import type { ObservableValue } from '@amazon/vinyl-observable';
+export interface TimelineContentTypesValueDeps {
+    /**
+     * The filtered, playable timeline. Content types are derived from the
+     * qualities that survive filtering, so a content type whose renditions are
+     * all filtered out (e.g. every audio rendition dropped by the sample-rate
+     * filter) is not reported — it never gates readiness and no source buffer
+     * is expected for it, so the remaining content types still play.
+     */
+    readonly mediaTimelineTransformed: ObservableValue<Promise<MediaTimeline>>;
+}
+/**
+ * Provides the MSE content types to create source buffers for, derived from the
+ * qualities that survive timeline filtering rather than the raw manifest. Only
+ * `'audio'`/`'video'` are reported; text is a sidecar pipeline, never an MSE
+ * source buffer.
+ */
+export declare function createTimelineContentTypesValue(deps: TimelineContentTypesValueDeps): ContentTypesValue;
+//# sourceMappingURL=createTimelineContentTypesValue.d.ts.map

package/dist/types/current/streaming/createTimelineContentTypesValue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTimelineContentTypesValue.d.ts","sourceRoot":"","sources":["../../../../src/streaming/createTimelineContentTypesValue.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAE/D,MAAM,WAAW,6BAA6B;IAC1C;;;;;;OAMG;IACH,QAAQ,CAAC,wBAAwB,EAAE,eAAe,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAA;CAC7E;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC3C,IAAI,EAAE,6BAA6B,GACpC,iBAAiB,CAgBnB"}

package/dist/types/current/streaming/createTimelineContentTypesValue.js

@@ -0,0 +1,25 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Provides the MSE content types to create source buffers for, derived from the
+ * qualities that survive timeline filtering rather than the raw manifest. Only
+ * `'audio'`/`'video'` are reported; text is a sidecar pipeline, never an MSE
+ * source buffer.
+ */
+export function createTimelineContentTypesValue(deps) {
+    return deps.mediaTimelineTransformed.map(async (timelinePromise) => {
+        const timeline = await timelinePromise;
+        const contentTypes = new Set();
+        for (const period of timeline.periods) {
+            for (const { metadata } of period.qualities) {
+                if (metadata.contentType === 'audio' ||
+                    metadata.contentType === 'video') {
+                    contentTypes.add(metadata.contentType);
+                }
+            }
+        }
+        return contentTypes;
+    });
+}

package/dist/types/current/streaming/mediaTimelineAccessibilityFilter.d.ts

@@ -0,0 +1,35 @@
+import type { MediaQualityMetadata } from './MediaQualityMetadata';
+import type { FilterPredicate } from '@amazon/vinyl-util';
+/**
+ * Thrown if the audio-description filter ever emptied a period's audio. The
+ * filter keeps at least one audio rendition per period by design, so this is a
+ * defensive guard rather than an expected path.
+ */
+export declare function throwNoPlayableAudio(): never;
+/**
+ * Characteristics that mark an audio rendition as an audio description (a.k.a.
+ * described video / DVS) — narration of on-screen action for viewers who cannot
+ * see it. HLS signals this with the `public.accessibility.describes-video`
+ * CHARACTERISTIC; DASH with a `description` Role. Such renditions must not be
+ * chosen as the default audio; they are an accessibility opt-in.
+ */
+export declare const AUDIO_DESCRIPTION_CHARACTERISTICS: readonly string[];
+/**
+ * Whether an audio quality is an audio-description rendition.
+ */
+export declare function isAudioDescription(quality: MediaQualityMetadata): boolean;
+/**
+ * Creates a filter that keeps audio-description renditions out of (or, when
+ * opted in, restricts audio to) the audio selection.
+ *
+ * - `preferDescription: false` (default): drop audio-description renditions
+ *   from each period *when a non-description audio alternative exists*, so the
+ *   main audio is chosen by default instead of the description track. If a
+ *   period has only description audio, it is kept (playback is never stranded).
+ * - `preferDescription: true`: keep only description renditions when the period
+ *   has any; otherwise keep all (again, never strand playback).
+ *
+ * Non-audio qualities are always kept.
+ */
+export declare function createAudioDescriptionFilter(preferDescription: boolean): FilterPredicate<MediaQualityMetadata>;
+//# sourceMappingURL=mediaTimelineAccessibilityFilter.d.ts.map

package/dist/types/current/streaming/mediaTimelineAccessibilityFilter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediaTimelineAccessibilityFilter.d.ts","sourceRoot":"","sources":["../../../../src/streaming/mediaTimelineAccessibilityFilter.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAGzD;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,KAAK,CAE5C;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,EAAE,SAAS,MAAM,EAG9D,CAAA;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAIzE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CACxC,iBAAiB,EAAE,OAAO,GAC3B,eAAe,CAAC,oBAAoB,CAAC,CA8BvC"}

package/dist/types/current/streaming/mediaTimelineAccessibilityFilter.js

@@ -0,0 +1,75 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { MediaUnsupportedError, memoize } from '@amazon/vinyl-util';
+/**
+ * Thrown if the audio-description filter ever emptied a period's audio. The
+ * filter keeps at least one audio rendition per period by design, so this is a
+ * defensive guard rather than an expected path.
+ */
+export function throwNoPlayableAudio() {
+    throw new MediaUnsupportedError('No playable audio rendition', 'audio');
+}
+/**
+ * Characteristics that mark an audio rendition as an audio description (a.k.a.
+ * described video / DVS) — narration of on-screen action for viewers who cannot
+ * see it. HLS signals this with the `public.accessibility.describes-video`
+ * CHARACTERISTIC; DASH with a `description` Role. Such renditions must not be
+ * chosen as the default audio; they are an accessibility opt-in.
+ */
+export const AUDIO_DESCRIPTION_CHARACTERISTICS = [
+    'public.accessibility.describes-video',
+    'description',
+];
+/**
+ * Whether an audio quality is an audio-description rendition.
+ */
+export function isAudioDescription(quality) {
+    return quality.characteristics.some((c) => AUDIO_DESCRIPTION_CHARACTERISTICS.includes(c));
+}
+/**
+ * Creates a filter that keeps audio-description renditions out of (or, when
+ * opted in, restricts audio to) the audio selection.
+ *
+ * - `preferDescription: false` (default): drop audio-description renditions
+ *   from each period *when a non-description audio alternative exists*, so the
+ *   main audio is chosen by default instead of the description track. If a
+ *   period has only description audio, it is kept (playback is never stranded).
+ * - `preferDescription: true`: keep only description renditions when the period
+ *   has any; otherwise keep all (again, never strand playback).
+ *
+ * Non-audio qualities are always kept.
+ */
+export function createAudioDescriptionFilter(preferDescription) {
+    // Per period (per unique array reference): does it have description audio,
+    // and does it have non-description ("main") audio?
+    const periodFlags = memoize((array) => {
+        let hasDescription = false;
+        let hasMain = false;
+        for (const quality of Array.from(array)) {
+            if (quality.contentType !== 'audio')
+                continue;
+            if (isAudioDescription(quality))
+                hasDescription = true;
+            else
+                hasMain = true;
+        }
+        return { hasDescription, hasMain };
+    }, (array) => array, 1);
+    return (quality, _index, array) => {
+        if (quality.contentType !== 'audio')
+            return true;
+        const { hasDescription, hasMain } = periodFlags(array);
+        if (preferDescription) {
+            // Nothing to prefer; keep all rather than strand playback.
+            if (!hasDescription)
+                return true;
+            return isAudioDescription(quality);
+        }
+        // No main alternative; keep all rather than strand playback.
+        if (!hasMain)
+            return true;
+        return !isAudioDescription(quality);
+    };
+}

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

@@ -0,0 +1,60 @@
+import type { Disposable } from '@amazon/vinyl-util';
+import type { TextTrackRenderer } from './TextTrackRenderer';
+/**
+ * The subset of a `VTTCue`'s positioning properties {@link computeCueLayout}
+ * reads. A native `VTTCue` satisfies this; a plain `TextTrackCue` (platforms
+ * without `VTTCue`) leaves them undefined and falls back to defaults.
+ */
+export interface CueGeometry {
+    readonly align?: string | null;
+    readonly line?: number | AutoKeyword;
+    readonly lineAlign?: LineAlignSetting;
+    readonly position?: number | AutoKeyword;
+    readonly positionAlign?: PositionAlignSetting;
+    readonly size?: number;
+    readonly snapToLines?: boolean;
+    readonly vertical?: DirectionSetting;
+}
+/** Inline styles (camelCase CSS properties) to apply to a rendered cue box. */
+export type CueLayout = Record<string, string>;
+/**
+ * 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 declare function computeCueLayout(cue: CueGeometry): CueLayout;
+/**
+ * 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 declare function renderCueText(text: string): string;
+/**
+ * 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 declare class HtmlTextTrackRenderer implements TextTrackRenderer, Disposable {
+    /** The overlay container to mount over the video. */
+    readonly element: HTMLElement;
+    private track;
+    private readonly styleElement;
+    private readonly onCueChange;
+    constructor();
+    setTextTrack(track: TextTrack | null): void;
+    setStyles(styles: readonly string[]): void;
+    dispose(): void;
+    private renderActiveCues;
+    private createCueBox;
+}
+//# sourceMappingURL=HtmlTextTrackRenderer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"HtmlTextTrackRenderer.d.ts","sourceRoot":"","sources":["../../../../src/text/HtmlTextTrackRenderer.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D;;;;GAIG;AACH,MAAM,WAAW,WAAW;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,CAAA;IACpC,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAA;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW,CAAA;IACxC,QAAQ,CAAC,aAAa,CAAC,EAAE,oBAAoB,CAAA;IAC7C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAA;CACvC;AAED,+EAA+E;AAC/E,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAK9C;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,WAAW,GAAG,SAAS,CAmD5D;AAmDD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAoBlD;AAeD;;;;;GAKG;AACH,qBAAa,qBAAsB,YAAW,iBAAiB,EAAE,UAAU;IACvE,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;IAE7B,OAAO,CAAC,KAAK,CAAyB;IAGtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkB;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgC;;IAgB5D,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,GAAG,IAAI;IAe3C,SAAS,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAI1C,OAAO,IAAI,IAAI;IAIf,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,YAAY;CAOvB"}

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"}