mattebox 0.1.0

package/dist/protocols/hls-live/index.js

@@ -0,0 +1,309 @@
+import { mergePlaylist, parseMediaPlaylist } from '../hls-cmaf/parse.js';
+import { registerLiveNamespace } from '../live-shared.js';
+const REFRESH_TOKEN = 'hls:live:refresh';
+const TICK_TOKEN = 'hls-live:reload';
+const INITIAL = {
+    manifestUrl: null,
+    target: null,
+    companions: [],
+    round: 0,
+    tickPending: false,
+    inflight: null,
+    lastEndSeq: -1,
+    awaitingTarget: false,
+};
+/**
+ * A two-hour DVR playlist is tens of kilobytes; reloading four of them every
+ * target duration saturates a slow link. The audio and text companions keep
+ * the full cadence because playback consumes them; the other video rungs
+ * only need to be fresh enough for a switch, which reloads the new target
+ * at once anyway.
+ */
+const LADDER_EVERY = 3;
+/**
+ * Every reload names its rendition in the token, the target's included. A
+ * response is merged into the rendition it was fetched for, never into
+ * whichever rendition is the target when it lands: a switch while a
+ * reload is in flight would otherwise file one rendition's segment URLs
+ * under another, and the scheduler would then append the wrong bytes under
+ * a matching rendition id, which no init guard can catch.
+ */
+function refreshToken(renditionId) {
+    return `${REFRESH_TOKEN}:${renditionId}`;
+}
+function renditionOfToken(token) {
+    return token.startsWith(`${REFRESH_TOKEN}:`) ? token.slice(REFRESH_TOKEN.length + 1) : null;
+}
+function findRendition(presentation, renditionId) {
+    for (const period of presentation.periods) {
+        for (const track of period.tracks) {
+            for (const rendition of track.renditions) {
+                if (rendition.id === renditionId)
+                    return rendition;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * The active tracks' playlists other than the window rendition's: every
+ * other video rendition, the audio group rendition, a segmented subtitle
+ * playlist. The whole video ladder reloads because a switch can only land
+ * on a rendition whose playlist reaches the playhead; one left at its
+ * startup window can never be scheduled from, so the switch never happens.
+ * Renditions without a playlist of their own (muxed audio, a text track in
+ * a single file) need no reload.
+ */
+function companionTargets(presentation, kernel, windowRenditionId) {
+    const activeIds = new Set(['video', 'audio', 'text']
+        .map((contentType) => kernel.tracks.active.get(contentType))
+        .filter((id) => id !== undefined));
+    const out = [];
+    for (const period of presentation.periods) {
+        for (const track of period.tracks) {
+            if (!activeIds.has(track.id))
+                continue;
+            for (const rendition of track.renditions) {
+                if (rendition.id === windowRenditionId || rendition.playlistUrl === undefined)
+                    continue;
+                out.push({
+                    url: rendition.playlistUrl,
+                    renditionId: rendition.id,
+                    ladder: track.contentType === 'video',
+                });
+            }
+        }
+    }
+    return out;
+}
+/** Loops a message back into the bus through a zero-delay schedule effect. */
+function feed(message) {
+    // biome-ignore lint/suspicious/noThenProperty: `then` is the schedule effect's field name from the message taxonomy
+    return { kind: 'schedule', token: 'hls-live:loopback', delayMs: 0, then: message };
+}
+function tick(delaySeconds) {
+    return {
+        kind: 'schedule',
+        token: TICK_TOKEN,
+        delayMs: Math.max(500, delaySeconds * 1000),
+        // biome-ignore lint/suspicious/noThenProperty: `then` is the schedule effect's field name from the message taxonomy
+        then: { type: 'TICK', token: TICK_TOKEN },
+    };
+}
+/**
+ * The rendition whose playlist drives the live window: the active video
+ * rendition, else the first with segments. Video leads, but an audio-only
+ * presentation (a radio or packed-audio DVR stream) has no video track, so
+ * audio drives the window there.
+ */
+function windowRendition(presentation, kernel) {
+    let fallback = null;
+    for (const contentType of ['video', 'audio']) {
+        for (const period of presentation.periods) {
+            for (const track of period.tracks) {
+                if (track.contentType !== contentType)
+                    continue;
+                for (const rendition of track.renditions) {
+                    if (!Array.isArray(rendition.segments) || rendition.segments.length === 0)
+                        continue;
+                    if (rendition.id === kernel.quality.active)
+                        return rendition;
+                    fallback = fallback ?? rendition;
+                }
+            }
+        }
+        if (fallback !== null)
+            return fallback;
+    }
+    return fallback;
+}
+/**
+ * The window fact for the rendition's current segment list, or null when
+ * the kernel already holds exactly that window: every companion reload
+ * feeds a MANIFEST_LOADED, and a window that has not moved is not news.
+ */
+function windowFact(presentation, rendition, kernel) {
+    const segments = rendition.segments;
+    if (!Array.isArray(segments) || segments.length === 0)
+        return null;
+    const first = segments[0];
+    const last = segments[segments.length - 1];
+    if (first === undefined || last === undefined)
+        return null;
+    const end = last.start + last.duration;
+    const holdBack = presentation.live?.holdBack ?? 3 * (presentation.live?.updatePeriod ?? last.duration);
+    const start = first.start;
+    const edge = Math.max(start, end - holdBack);
+    const known = kernel.live;
+    if (known !== null &&
+        known.span.start === start &&
+        known.span.end === end &&
+        known.edge === edge) {
+        return null;
+    }
+    return feed({ type: 'LIVE_WINDOW_CHANGED', start, end, edge });
+}
+/** The playlist URL a rendition's reload resolves against. */
+function playlistUrlFor(presentation, renditionId, target) {
+    const rendition = findRendition(presentation, renditionId);
+    if (rendition?.playlistUrl !== undefined)
+        return rendition.playlistUrl;
+    // A bare media-playlist source: the rendition has no playlist of its own
+    // and the manifest itself is reloaded as the target.
+    return target !== null && target.renditionId === renditionId ? target.url : null;
+}
+const reduceHlsLive = (slice, msg, kernel) => {
+    const state = slice ?? INITIAL;
+    if (msg.type === 'LOAD')
+        return [{ ...INITIAL, manifestUrl: msg.url }, []];
+    if (msg.type === 'UNLOAD' || msg.type === 'DETACH')
+        return [INITIAL, []];
+    if (msg.type === 'MANIFEST_LOADED') {
+        if (!msg.presentation.isLive) {
+            return [{ ...state, target: null, companions: [], inflight: null }, []];
+        }
+        const rendition = windowRendition(msg.presentation, kernel);
+        const effects = [];
+        // The reload target: the rendition's own playlist when it has one, the
+        // manifest itself for a bare media-playlist source.
+        const url = rendition?.playlistUrl ?? state.manifestUrl;
+        const target = url !== null && rendition !== null
+            ? { url, renditionId: rendition.id, ladder: false }
+            : state.target;
+        const companions = companionTargets(msg.presentation, kernel, rendition?.id ?? null);
+        const switched = state.target !== null && target !== null && target.renditionId !== state.target.renditionId;
+        let awaitingTarget = state.awaitingTarget;
+        let inflight = state.inflight;
+        if (switched && target !== null) {
+            // A quality switch moved the window onto a playlist last fetched at
+            // startup. Reload it now and hold the window until it lands. A reload
+            // of that very rendition already in flight serves the same purpose.
+            if (inflight !== target.renditionId) {
+                effects.push({ kind: 'fetch', token: refreshToken(target.renditionId), url: target.url });
+                inflight = target.renditionId;
+            }
+            awaitingTarget = true;
+        }
+        else if (!awaitingTarget && rendition !== null) {
+            const window = windowFact(msg.presentation, rendition, kernel);
+            if (window !== null)
+                effects.push(window);
+        }
+        // Only a dead loop (startup, or after ENDLIST) starts one.
+        let tickPending = state.tickPending;
+        if (!tickPending && inflight === null && target !== null) {
+            effects.push(tick(msg.presentation.live?.updatePeriod ?? 4));
+            tickPending = true;
+        }
+        return [{ ...state, target, companions, tickPending, inflight, awaitingTarget }, effects];
+    }
+    if (msg.type === 'TICK' && msg.token === TICK_TOKEN) {
+        if (state.target === null || kernel.presentation?.isLive !== true) {
+            return [{ ...state, tickPending: false, inflight: null }, []];
+        }
+        const effects = [];
+        let inflight = state.inflight;
+        // One target reload at a time: a second in flight would answer twice
+        // and every answer schedules the next tick, forking the loop.
+        if (inflight !== state.target.renditionId) {
+            effects.push({
+                kind: 'fetch',
+                token: refreshToken(state.target.renditionId),
+                url: state.target.url,
+            });
+            inflight = state.target.renditionId;
+        }
+        for (const companion of state.companions) {
+            if (companion.ladder && state.round % LADDER_EVERY !== 0)
+                continue;
+            effects.push({
+                kind: 'fetch',
+                token: refreshToken(companion.renditionId),
+                url: companion.url,
+            });
+        }
+        // The target's answer schedules the next tick.
+        return [{ ...state, round: state.round + 1, tickPending: false, inflight }, effects];
+    }
+    if (msg.type === 'SEGMENT_FAILED') {
+        const renditionId = renditionOfToken(msg.trackId);
+        if (renditionId === null)
+            return [state, []];
+        // A failed companion reload is nothing; a failed target reload is not
+        // fatal either: try again soon rather than let the loop die.
+        if (state.target === null || renditionId !== state.target.renditionId)
+            return [state, []];
+        if (state.tickPending)
+            return [{ ...state, inflight: null }, []];
+        return [{ ...state, inflight: null, tickPending: true }, [tick(2)]];
+    }
+    if (msg.type === 'SEGMENT_LOADED') {
+        const renditionId = renditionOfToken(msg.trackId);
+        if (renditionId === null || kernel.presentation === null)
+            return [state, []];
+        const isTarget = state.target !== null && renditionId === state.target.renditionId;
+        const url = playlistUrlFor(kernel.presentation, renditionId, state.target);
+        if (url === null)
+            return [state, []];
+        const text = new TextDecoder().decode(msg.bytes);
+        const media = parseMediaPlaylist(text, url);
+        if (media.playlist === null) {
+            // A bad reload is not fatal: try again on the same cadence.
+            if (!isTarget)
+                return [state, []];
+            if (state.tickPending)
+                return [{ ...state, inflight: null }, []];
+            return [{ ...state, inflight: null, tickPending: true }, [tick(2)]];
+        }
+        // Always merge, never re-parse: mergePlaylist rebases the new window onto
+        // the running timeline, which a fresh parse of a bare media playlist would
+        // throw away, stalling live once the first window drains.
+        const refreshed = mergePlaylist(kernel.presentation, renditionId, media.playlist);
+        const effects = [
+            feed({
+                type: 'PLAYLIST_REFRESHED',
+                trackId: renditionId,
+                renditionId,
+                mediaSequence: media.playlist.mediaSequence,
+                segments: media.playlist.segments,
+            }),
+            feed({ type: 'MANIFEST_LOADED', presentation: refreshed }),
+        ];
+        if (!isTarget) {
+            // A companion, or the target of a moment ago: merged in, nothing
+            // else. The window and the cadence belong to the target's reload.
+            return [state, effects];
+        }
+        const lastSegment = media.playlist.segments[media.playlist.segments.length - 1];
+        const endSeq = lastSegment?.seq ?? -1;
+        const changed = endSeq !== state.lastEndSeq;
+        const cadence = media.playlist.targetDuration || 4;
+        // RFC 8216: full cadence after a changed reload, half after an
+        // unchanged one. A switch's reload answers while the regular tick is
+        // still pending: that tick carries on, this answer adds none. The
+        // loop dies with ENDLIST.
+        let tickPending = state.tickPending;
+        if (!media.playlist.endlist && !tickPending) {
+            effects.push(tick(changed ? cadence : cadence / 2));
+            tickPending = true;
+        }
+        return [
+            { ...state, lastEndSeq: endSeq, tickPending, inflight: null, awaitingTarget: false },
+            effects,
+        ];
+    }
+    return [state, []];
+};
+/** The stage factory. Requires hls-cmaf; the loader enforces it. */
+export default function hlsLive() {
+    return {
+        name: 'hls-live',
+        provides: ['hls-live'],
+        requires: ['hls-cmaf'],
+        install(ctx) {
+            ctx.reduce('hls-live', reduceHlsLive);
+            registerLiveNamespace(ctx);
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/protocols/hls-live/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/protocols/hls-live/index.ts"],"names":[],"mappings":"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"}

package/dist/protocols/live-shared.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The engine.live surface both live adapters register. Reads come from
+ * kernel state, so the two implementations are identical by construction
+ * and loading both adapters is harmless.
+ */
+import type { StageContext } from '../types/stage.js';
+declare module '../index.js' {
+    interface MatteboxNamespaces {
+        live: LiveApi;
+    }
+}
+export interface LiveApi {
+    /** Where seekToEdge lands, in presentation time, or null before the first window. */
+    readonly edge: number | null;
+    /** Seconds between the availability end and the playhead, or null. */
+    readonly latency: number | null;
+    readonly atEdge: boolean;
+    seekToEdge(): void;
+}
+export declare function registerLiveNamespace(ctx: StageContext): void;
+//# sourceMappingURL=live-shared.d.ts.map

package/dist/protocols/live-shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-shared.d.ts","sourceRoot":"","sources":["../../src/protocols/live-shared.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,QAAQ,aAAa,CAAC;IAC3B,UAAU,kBAAkB;QAC1B,IAAI,EAAE,OAAO,CAAC;KACf;CACF;AAED,MAAM,WAAW,OAAO;IACtB,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,UAAU,IAAI,IAAI,CAAC;CACpB;AAKD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAyB7D"}

package/dist/protocols/live-shared.js

@@ -0,0 +1,32 @@
+/** How far behind the edge still counts as at it, in seconds. */
+const AT_EDGE_SLACK = 2;
+export function registerLiveNamespace(ctx) {
+    const api = {
+        get edge() {
+            return ctx.getState().live?.edge ?? null;
+        },
+        get latency() {
+            const state = ctx.getState();
+            if (state.live === null)
+                return null;
+            return state.live.span.end - state.playback.currentTime;
+        },
+        get atEdge() {
+            const state = ctx.getState();
+            if (state.live === null)
+                return false;
+            return state.playback.currentTime >= state.live.edge - AT_EDGE_SLACK;
+        },
+        seekToEdge() {
+            ctx.dispatch({ type: 'SEEK_TO_LIVE_EDGE' });
+        },
+    };
+    try {
+        ctx.registerNamespace('live', api);
+    }
+    catch {
+        // The other live adapter registered first. Both surfaces derive from
+        // the same kernel state, so the existing one already answers.
+    }
+}
+//# sourceMappingURL=live-shared.js.map

package/dist/protocols/live-shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-shared.js","sourceRoot":"","sources":["../../src/protocols/live-shared.ts"],"names":[],"mappings":"AAsBA,iEAAiE;AACjE,MAAM,aAAa,GAAG,CAAC,CAAC;AAExB,MAAM,UAAU,qBAAqB,CAAC,GAAiB;IACrD,MAAM,GAAG,GAAY;QACnB,IAAI,IAAI;YACN,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,IAAI,IAAI,CAAC;QAC3C,CAAC;QACD,IAAI,OAAO;YACT,MAAM,KAAK,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;YAC7B,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAC;YACrC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC;QAC1D,CAAC;QACD,IAAI,MAAM;YACR,MAAM,KAAK,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;YAC7B,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI;gBAAE,OAAO,KAAK,CAAC;YACtC,OAAO,KAAK,CAAC,QAAQ,CAAC,WAAW,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QACvE,CAAC;QACD,UAAU;YACR,GAAG,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,CAAC,CAAC;QAC9C,CAAC;KACF,CAAC;IACF,IAAI,CAAC;QACH,GAAG,CAAC,iBAAiB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,qEAAqE;QACrE,8DAA8D;IAChE,CAAC;AACH,CAAC"}

package/dist/stages/abr/index.d.ts

@@ -0,0 +1,16 @@
+import type { Stage } from '../../types/stage.js';
+export interface AbrOptions {
+    /** Fraction of the estimate a rendition may consume. */
+    readonly safetyFactor?: number;
+    /** Forward buffer required before switching up, in seconds. */
+    readonly upBufferSeconds?: number;
+    /** Forward buffer below which any sustainable down-switch happens immediately, in seconds. */
+    readonly downBufferSeconds?: number;
+    /** Fast-estimate fraction of the active bitrate that triggers the emergency floor. */
+    readonly emergencyFactor?: number;
+    /** Fast-estimate multiple of the emergency cap that releases it. */
+    readonly recoveryFactor?: number;
+}
+/** The stage factory. One chooser, one emergency constraint source. */
+export default function abr(options?: AbrOptions): Stage;
+//# sourceMappingURL=index.d.ts.map

package/dist/stages/abr/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/stages/abr/index.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAElD,MAAM,WAAW,UAAU;IACzB,wDAAwD;IACxD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,+DAA+D;IAC/D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,8FAA8F;IAC9F,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,sFAAsF;IACtF,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,oEAAoE;IACpE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AA8JD,uEAAuE;AACvE,MAAM,CAAC,OAAO,UAAU,GAAG,CAAC,OAAO,CAAC,EAAE,UAAU,GAAG,KAAK,CAavD"}

package/dist/stages/abr/index.js

@@ -0,0 +1,176 @@
+/**
+ * Adaptive bitrate as a stage, not kernel. It registers one chooser
+ * consulted at arbitration step 5 and one constraint source for
+ * emergencies; it never mutates another source's constraints and playback
+ * works identically without it, at the lowest permitted rendition.
+ *
+ * The chooser is a pure function of its arguments: every input comes from
+ * kernel telemetry, so replaying a trace through the same composition
+ * reproduces every decision. The emergency path lives in a slice reducer
+ * for the same reason.
+ */
+import { canSwitchTo } from '../../kernel/rendition-select.js';
+const DEFAULTS = {
+    safetyFactor: 0.7,
+    upBufferSeconds: 8,
+    downBufferSeconds: 4,
+    emergencyFactor: 0.5,
+    recoveryFactor: 2,
+};
+/** The conservative estimate: the minimum of the slow and fast EWMAs. */
+function estimateBps(telemetry) {
+    const slow = telemetry.throughputEwma;
+    const fast = telemetry.throughputFastEwma ?? slow;
+    if (slow === 0)
+        return fast;
+    if (fast === 0)
+        return slow;
+    return Math.min(slow, fast);
+}
+function choose(allowed, telemetry, options) {
+    const sorted = [...allowed].sort((a, b) => a.bitrate - b.bitrate);
+    const lowestRendition = sorted[0];
+    const current = allowed.find((r) => r.id === telemetry.current) ?? null;
+    const estimate = estimateBps(telemetry);
+    if (estimate === 0)
+        return (current ?? lowestRendition).id;
+    // The highest rendition the estimate sustains with headroom.
+    let best = lowestRendition;
+    for (const candidate of sorted) {
+        if (candidate.bitrate <= estimate * options.safetyFactor)
+            best = candidate;
+    }
+    if (current === null)
+        return best.id;
+    if (best.id === current.id)
+        return current.id;
+    const buffer = telemetry.bufferAhead ?? 0;
+    // The switch policy in force: codec-switch's when loaded, the kernel
+    // default otherwise. abr imports neither codec-switch nor knows which.
+    const policy = telemetry.canSwitchTo ?? canSwitchTo;
+    if (best.bitrate > current.bitrate) {
+        // Up only on a comfortable buffer, and never through a reloading switch.
+        if (buffer < options.upBufferSeconds)
+            return current.id;
+        if (policy(current, best) === 'reload')
+            return current.id;
+        return best.id;
+    }
+    // Down: aggressive on a thin buffer; on a healthy one only when the
+    // current rendition is genuinely unsustainable.
+    if (buffer < options.downBufferSeconds || current.bitrate > estimate) {
+        if (policy(current, best) === 'reload')
+            return current.id;
+        return best.id;
+    }
+    return current.id;
+}
+const INITIAL = { emergencyCap: null };
+/** Loops a command back into the bus through a zero-delay schedule effect. */
+function feed(message) {
+    // biome-ignore lint/suspicious/noThenProperty: `then` is the schedule effect's field name from the message taxonomy
+    return { kind: 'schedule', token: 'abr:emergency', delayMs: 0, then: message };
+}
+function activeBitrate(kernel) {
+    if (kernel.presentation === null || kernel.quality.active === null)
+        return null;
+    for (const period of kernel.presentation.periods) {
+        for (const track of period.tracks) {
+            for (const rendition of track.renditions) {
+                if (rendition.id === kernel.quality.active)
+                    return rendition.bitrate;
+            }
+        }
+    }
+    return null;
+}
+/** The track ABR steers: video where there is one, else audio. */
+function leadTrack(kernel) {
+    return kernel.tracks.active.get('video') ?? kernel.tracks.active.get('audio');
+}
+function lowestBitrate(kernel) {
+    let lowest = Number.POSITIVE_INFINITY;
+    for (const period of kernel.presentation?.periods ?? []) {
+        for (const track of period.tracks) {
+            if (track.contentType !== 'video')
+                continue;
+            for (const rendition of track.renditions) {
+                lowest = Math.min(lowest, rendition.bitrate);
+            }
+        }
+    }
+    return Number.isFinite(lowest) ? lowest : 0;
+}
+/** Samples smaller than this are jitter-dominated; ignore them for emergencies. */
+const MIN_SAMPLE_BYTES = 10_000;
+function createEmergencyReducer(options) {
+    return (slice, msg, kernel) => {
+        const state = slice ?? INITIAL;
+        if (msg.type === 'UNLOAD' || msg.type === 'DETACH')
+            return [INITIAL, []];
+        // Sample-driven only: a collapse shows up in the samples, not the clock.
+        // The trigger is the raw sample, not the average: waiting for an EWMA to
+        // catch up means waiting several slow segments, which is exactly the
+        // stall the emergency exists to prevent. A one-off spike self-heals
+        // because release watches the fast average.
+        //
+        // Only a media segment of the active rendition's own track is a sample.
+        // A playlist reload, an init segment, or an audio segment beside a video
+        // rendition is a small transfer whose time is latency, not bandwidth:
+        // counted, a 50 KB playlist that takes 120 ms reads as a collapse to
+        // 3 Mbps under a 7 Mbps rendition, and the cap flaps on every reload.
+        let raw = null;
+        if (msg.type === 'THROUGHPUT_SAMPLE') {
+            raw = msg.bps;
+        }
+        else if (msg.type === 'SEGMENT_LOADED' &&
+            msg.seq >= 0 &&
+            msg.trackId === leadTrack(kernel) &&
+            msg.rtt > 0 &&
+            msg.size >= MIN_SAMPLE_BYTES) {
+            raw = (msg.size * 8000) / msg.rtt;
+        }
+        if (raw === null)
+            return [state, []];
+        if (state.emergencyCap === null) {
+            const bitrate = activeBitrate(kernel);
+            if (bitrate === null || bitrate === 0)
+                return [state, []];
+            if (raw >= bitrate * options.emergencyFactor)
+                return [state, []];
+            // Collapse: floor the selection at what the network still carries,
+            // as this stage's own source so nobody else's constraint is touched.
+            const cap = Math.max(raw, lowestBitrate(kernel));
+            return [
+                { emergencyCap: cap },
+                [
+                    feed({
+                        type: 'CONSTRAIN',
+                        source: 'abr-emergency',
+                        constraint: { maxBitrate: cap },
+                    }),
+                ],
+            ];
+        }
+        if (kernel.stats.throughputFastEwma >= state.emergencyCap * options.recoveryFactor) {
+            return [INITIAL, [feed({ type: 'RELEASE_CONSTRAINT', source: 'abr-emergency' })]];
+        }
+        return [state, []];
+    };
+}
+/** The stage factory. One chooser, one emergency constraint source. */
+export default function abr(options) {
+    const resolved = { ...DEFAULTS, ...options };
+    return {
+        name: 'abr',
+        provides: ['abr'],
+        requires: ['scheduler', 'track-registry'],
+        install(ctx) {
+            ctx.registerChooser({
+                choose: (allowed, telemetry) => choose(allowed, telemetry, resolved),
+            });
+            ctx.reduce('abr', createEmergencyReducer(resolved));
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/stages/abr/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/stages/abr/index.ts"],"names":[],"mappings":"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"}

package/dist/stages/abr-cap-size/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The element-size cap from docs/08, verbatim: a ResizeObserver feeding one
+ * named constraint source. Its size is the litmus test for the constraint
+ * API; if this file grows, the API is wrong.
+ */
+import type { Stage } from '../../types/stage.js';
+export default function abrCapSize(): Stage;
+//# sourceMappingURL=index.d.ts.map

package/dist/stages/abr-cap-size/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/stages/abr-cap-size/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAElD,MAAM,CAAC,OAAO,UAAU,UAAU,IAAI,KAAK,CAkB1C"}

package/dist/stages/abr-cap-size/index.js

@@ -0,0 +1,21 @@
+export default function abrCapSize() {
+    return {
+        name: 'abr-cap-size',
+        requires: ['rendition-select'],
+        install(ctx) {
+            const observer = new ResizeObserver(([entry]) => {
+                if (entry === undefined)
+                    return;
+                const dpr = Math.min(globalThis.devicePixelRatio || 1, 2);
+                ctx.dispatch({
+                    type: 'CONSTRAIN',
+                    source: 'element-size',
+                    constraint: { maxHeight: entry.contentRect.height * dpr },
+                });
+            });
+            observer.observe(ctx.element);
+            return () => observer.disconnect();
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/stages/abr-cap-size/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/stages/abr-cap-size/index.ts"],"names":[],"mappings":"AAOA,MAAM,CAAC,OAAO,UAAU,UAAU;IAChC,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,QAAQ,EAAE,CAAC,kBAAkB,CAAC;QAC9B,OAAO,CAAC,GAAG;YACT,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE;gBAC9C,IAAI,KAAK,KAAK,SAAS;oBAAE,OAAO;gBAChC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,gBAAgB,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;gBAC1D,GAAG,CAAC,QAAQ,CAAC;oBACX,IAAI,EAAE,WAAW;oBACjB,MAAM,EAAE,cAAc;oBACtB,UAAU,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,WAAW,CAAC,MAAM,GAAG,GAAG,EAAE;iBAC1D,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;YACH,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAC9B,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC;QACrC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/stages/abr-persist/index.d.ts

@@ -0,0 +1,8 @@
+import type { Stage } from '../../types/stage.js';
+export interface AbrPersistStorage {
+    /** The remembered estimate in bits per second, or null for none. */
+    get(): number | null;
+    set(bps: number): void;
+}
+export default function abrPersist(storage: AbrPersistStorage): Stage;
+//# sourceMappingURL=index.d.ts.map

package/dist/stages/abr-persist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/stages/abr-persist/index.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAElD,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,GAAG,IAAI,MAAM,GAAG,IAAI,CAAC;IACrB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAcD,MAAM,CAAC,OAAO,UAAU,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,KAAK,CAqCpE"}