@aelionsdk/media 0.1.0-beta.1

package/dist/opfs-cache.d.ts

@@ -0,0 +1,11 @@
+import { type CacheAddress, type CacheStore, type CacheStoreSnapshot } from './cache-store.js';
+export declare class OpfsCacheStore implements CacheStore {
+    #private;
+    constructor(directoryName?: string, maxBytes?: number);
+    get(address: CacheAddress, signal?: AbortSignal): Promise<Uint8Array | undefined>;
+    put(address: CacheAddress, value: Uint8Array, signal?: AbortSignal): Promise<void>;
+    delete(address: CacheAddress, signal?: AbortSignal): Promise<void>;
+    clear(signal?: AbortSignal): Promise<void>;
+    snapshot(): CacheStoreSnapshot;
+}
+//# sourceMappingURL=opfs-cache.d.ts.map

package/dist/opfs-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opfs-cache.d.ts","sourceRoot":"","sources":["../src/opfs-cache.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACxB,MAAM,kBAAkB,CAAC;AAqB1B,qBAAa,cAAe,YAAW,UAAU;;gBAY5B,aAAa,SAAoB,EAAE,QAAQ,SAAsB;IAcvE,GAAG,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IA4BvF,GAAG,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAmClF,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAclE,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB1C,QAAQ,IAAI,kBAAkB;CAiEtC"}

package/dist/opfs-cache.js

@@ -0,0 +1,179 @@
+import { throwIfAborted } from '@aelionsdk/core';
+import { cacheAddressKey, } from './cache-store.js';
+async function fileName(key) {
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(key)));
+    return `${[...digest].map(value => value.toString(16).padStart(2, '0')).join('')}.bin`;
+}
+export class OpfsCacheStore {
+    #maxBytes;
+    #directory;
+    #entries = new Map();
+    #ready;
+    #mutation = Promise.resolve();
+    #bytes = 0;
+    #clock = 0;
+    #hits = 0;
+    #misses = 0;
+    #evictions = 0;
+    constructor(directoryName = 'aelion-cache-v1', maxBytes = 512 * 1_024 * 1_024) {
+        if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+            throw new RangeError('maxBytes must be a positive safe integer');
+        }
+        if (directoryName.length === 0 || directoryName.includes('/')) {
+            throw new TypeError('OPFS cache directoryName must be a leaf name');
+        }
+        this.#maxBytes = maxBytes;
+        this.#directory = navigator.storage
+            .getDirectory()
+            .then(root => root.getDirectoryHandle(directoryName, { create: true }));
+        this.#ready = this.#loadIndex();
+    }
+    async get(address, signal) {
+        throwIfAborted(signal, 'OPFS cache read');
+        await this.#ready;
+        const key = cacheAddressKey(address);
+        const entry = this.#entries.get(key);
+        if (entry === undefined) {
+            this.#misses += 1;
+            return undefined;
+        }
+        try {
+            const handle = await (await this.#directory).getFileHandle(entry.file);
+            const bytes = new Uint8Array(await (await handle.getFile()).arrayBuffer());
+            throwIfAborted(signal, 'OPFS cache read');
+            if (bytes.byteLength !== entry.bytes)
+                throw new Error('OPFS cache entry size mismatch');
+            entry.access = ++this.#clock;
+            this.#hits += 1;
+            return bytes;
+        }
+        catch (error) {
+            if (error instanceof DOMException && error.name === 'NotFoundError') {
+                this.#entries.delete(key);
+                this.#bytes -= entry.bytes;
+                this.#misses += 1;
+                return undefined;
+            }
+            throw error;
+        }
+    }
+    put(address, value, signal) {
+        const task = this.#mutation.then(async () => {
+            throwIfAborted(signal, 'OPFS cache write');
+            await this.#ready;
+            if (value.byteLength > this.#maxBytes)
+                throw new RangeError('Cache entry exceeds OPFS budget');
+            const estimate = await navigator.storage.estimate();
+            const available = (estimate.quota ?? Number.MAX_SAFE_INTEGER) - (estimate.usage ?? 0);
+            if (value.byteLength > available) {
+                throw new DOMException('Insufficient OPFS quota', 'QuotaExceededError');
+            }
+            const key = cacheAddressKey(address);
+            const name = await fileName(key);
+            const directory = await this.#directory;
+            const handle = await directory.getFileHandle(name, { create: true });
+            const stream = await handle.createWritable();
+            try {
+                await stream.write(value);
+                await stream.close();
+            }
+            catch (error) {
+                await stream.abort().catch(() => undefined);
+                await directory.removeEntry(name).catch(() => undefined);
+                throw error;
+            }
+            const previous = this.#entries.get(key);
+            if (previous !== undefined)
+                this.#bytes -= previous.bytes;
+            this.#entries.set(key, { file: name, bytes: value.byteLength, access: ++this.#clock });
+            this.#bytes += value.byteLength;
+            await this.#evict();
+            await this.#saveIndex();
+        });
+        this.#mutation = task.catch(() => undefined);
+        return task;
+    }
+    delete(address, signal) {
+        return this.#enqueue(async () => {
+            throwIfAborted(signal, 'OPFS cache delete');
+            await this.#ready;
+            const key = cacheAddressKey(address);
+            const entry = this.#entries.get(key);
+            if (entry === undefined)
+                return;
+            this.#entries.delete(key);
+            this.#bytes -= entry.bytes;
+            await (await this.#directory).removeEntry(entry.file).catch(() => undefined);
+            await this.#saveIndex();
+        });
+    }
+    clear(signal) {
+        return this.#enqueue(async () => {
+            throwIfAborted(signal, 'OPFS cache clear');
+            await this.#ready;
+            const directory = await this.#directory;
+            await Promise.all([...this.#entries.values()].map(entry => directory.removeEntry(entry.file).catch(() => undefined)));
+            this.#entries.clear();
+            this.#bytes = 0;
+            await this.#saveIndex();
+        });
+    }
+    snapshot() {
+        return {
+            entries: this.#entries.size,
+            bytes: this.#bytes,
+            maxBytes: this.#maxBytes,
+            hits: this.#hits,
+            misses: this.#misses,
+            evictions: this.#evictions,
+        };
+    }
+    async #loadIndex() {
+        try {
+            const handle = await (await this.#directory).getFileHandle('index.json');
+            const parsed = JSON.parse(await (await handle.getFile()).text());
+            this.#clock = parsed.clock;
+            for (const [key, entry] of Object.entries(parsed.entries)) {
+                if (typeof entry.file === 'string' &&
+                    Number.isSafeInteger(entry.bytes) &&
+                    entry.bytes >= 0 &&
+                    Number.isSafeInteger(entry.access)) {
+                    this.#entries.set(key, { ...entry });
+                    this.#bytes += entry.bytes;
+                }
+            }
+            await this.#evict();
+        }
+        catch (error) {
+            if (!(error instanceof DOMException && error.name === 'NotFoundError'))
+                throw error;
+        }
+    }
+    async #saveIndex() {
+        const handle = await (await this.#directory).getFileHandle('index.json', { create: true });
+        const stream = await handle.createWritable();
+        await stream.write(JSON.stringify({
+            version: 1,
+            clock: this.#clock,
+            entries: Object.fromEntries(this.#entries),
+        }));
+        await stream.close();
+    }
+    async #evict() {
+        const directory = await this.#directory;
+        while (this.#bytes > this.#maxBytes) {
+            const oldest = [...this.#entries.entries()].sort((left, right) => left[1].access - right[1].access)[0];
+            if (oldest === undefined)
+                return;
+            this.#entries.delete(oldest[0]);
+            this.#bytes -= oldest[1].bytes;
+            await directory.removeEntry(oldest[1].file).catch(() => undefined);
+            this.#evictions += 1;
+        }
+    }
+    #enqueue(operation) {
+        const task = this.#mutation.then(operation);
+        this.#mutation = task.catch(() => undefined);
+        return task;
+    }
+}

package/dist/proxy.d.ts

@@ -0,0 +1,26 @@
+import type { JsonObject, JsonValue } from '@aelionsdk/core';
+export interface AssetRepresentation {
+    readonly id: string;
+    readonly role: 'original' | 'proxy' | 'thumbnail' | 'waveform';
+    readonly locator: JsonValue;
+    readonly durationUs?: number;
+    readonly width?: number;
+    readonly height?: number;
+    readonly contentHash?: string;
+    readonly sourceStartUs?: number;
+}
+export interface SelectRepresentationOptions {
+    readonly purpose: 'preview' | 'export' | 'thumbnail' | 'waveform';
+    readonly maxDimension?: number;
+    readonly sourceDurationUs?: number;
+    readonly durationToleranceUs?: number;
+}
+export interface RepresentationSelection {
+    readonly representation: AssetRepresentation;
+    readonly usedProxy: boolean;
+    readonly diagnostics: readonly string[];
+}
+export declare function selectAssetRepresentation(asset: Readonly<JsonObject>, options: SelectRepresentationOptions): RepresentationSelection;
+/** Proxy and source use the same normalized presentation timeline. */
+export declare function proxyPresentationTimeUs(sourceTimeUs: number, representation: AssetRepresentation): number;
+//# sourceMappingURL=proxy.d.ts.map

package/dist/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE7D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,GAAG,WAAW,GAAG,UAAU,CAAC;IAC/D,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,CAAC;IAClE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,cAAc,EAAE,mBAAmB,CAAC;IAC7C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAiCD,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,EAC3B,OAAO,EAAE,2BAA2B,GACnC,uBAAuB,CA8CzB;AAED,sEAAsE;AACtE,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,mBAAmB,GAClC,MAAM,CAYR"}

package/dist/proxy.js

@@ -0,0 +1,86 @@
+function object(value) {
+    return value !== null && value !== undefined && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function representation(value) {
+    const entry = object(value);
+    if (entry === undefined ||
+        typeof entry.id !== 'string' ||
+        (entry.role !== 'original' &&
+            entry.role !== 'proxy' &&
+            entry.role !== 'thumbnail' &&
+            entry.role !== 'waveform') ||
+        entry.locator === undefined) {
+        return undefined;
+    }
+    return {
+        id: entry.id,
+        role: entry.role,
+        locator: entry.locator,
+        ...(typeof entry.durationUs === 'number' ? { durationUs: entry.durationUs } : {}),
+        ...(typeof entry.width === 'number' ? { width: entry.width } : {}),
+        ...(typeof entry.height === 'number' ? { height: entry.height } : {}),
+        ...(typeof entry.contentHash === 'string' ? { contentHash: entry.contentHash } : {}),
+        ...(typeof entry.sourceStartUs === 'number' ? { sourceStartUs: entry.sourceStartUs } : {}),
+    };
+}
+export function selectAssetRepresentation(asset, options) {
+    const values = Array.isArray(asset.representations)
+        ? asset.representations.flatMap(value => {
+            const parsed = representation(value);
+            return parsed === undefined ? [] : [parsed];
+        })
+        : [];
+    const original = values.find(value => value.role === 'original') ??
+        {
+            id: `${typeof asset.id === 'string' ? asset.id : 'asset'}:original`,
+            role: 'original',
+            locator: asset.locator ?? null,
+            ...(options.sourceDurationUs === undefined ? {} : { durationUs: options.sourceDurationUs }),
+        };
+    if (options.purpose === 'export') {
+        return { representation: original, usedProxy: false, diagnostics: [] };
+    }
+    const role = options.purpose === 'preview'
+        ? 'proxy'
+        : options.purpose === 'thumbnail'
+            ? 'thumbnail'
+            : 'waveform';
+    const diagnostics = [];
+    const candidates = values
+        .filter(value => value.role === role)
+        .filter(value => {
+        if (options.sourceDurationUs === undefined || value.durationUs === undefined)
+            return true;
+        const tolerance = options.durationToleranceUs ?? 1_000;
+        const consistent = Math.abs(value.durationUs - options.sourceDurationUs) <= tolerance;
+        if (!consistent)
+            diagnostics.push('MEDIA_PROXY_DURATION_MISMATCH');
+        return consistent;
+    })
+        .sort((left, right) => {
+        const leftSize = Math.max(left.width ?? Number.MAX_SAFE_INTEGER, left.height ?? 0);
+        const rightSize = Math.max(right.width ?? Number.MAX_SAFE_INTEGER, right.height ?? 0);
+        const target = options.maxDimension ?? Number.MAX_SAFE_INTEGER;
+        const leftPenalty = leftSize > target ? leftSize - target + target : target - leftSize;
+        const rightPenalty = rightSize > target ? rightSize - target + target : target - rightSize;
+        return leftPenalty - rightPenalty || left.id.localeCompare(right.id);
+    });
+    const selected = candidates[0];
+    return selected === undefined
+        ? { representation: original, usedProxy: false, diagnostics }
+        : { representation: selected, usedProxy: selected.role === 'proxy', diagnostics };
+}
+/** Proxy and source use the same normalized presentation timeline. */
+export function proxyPresentationTimeUs(sourceTimeUs, representation) {
+    if (!Number.isSafeInteger(sourceTimeUs) || sourceTimeUs < 0) {
+        throw new RangeError('sourceTimeUs must be a non-negative safe integer');
+    }
+    const mapped = sourceTimeUs - (representation.sourceStartUs ?? 0);
+    if (mapped < 0 ||
+        (representation.durationUs !== undefined && mapped >= representation.durationUs)) {
+        throw new RangeError('Source time is outside the representation timeline');
+    }
+    return mapped;
+}

package/dist/range-reader.d.ts

@@ -0,0 +1,31 @@
+import type { ByteRange, RangeRead, RangeReader } from './types.js';
+export declare class MemoryRangeReader implements RangeReader {
+    #private;
+    readonly id: string;
+    readonly kind: "memory";
+    constructor(id: string, bytes: Uint8Array);
+    size(signal?: AbortSignal): Promise<number>;
+    read(range: ByteRange, signal?: AbortSignal): Promise<RangeRead>;
+}
+export declare class BlobRangeReader implements RangeReader {
+    #private;
+    readonly id: string;
+    readonly kind: "blob";
+    constructor(id: string, blob: Blob);
+    size(signal?: AbortSignal): Promise<number>;
+    read(range: ByteRange, signal?: AbortSignal): Promise<RangeRead>;
+}
+export interface FetchRangeReaderOptions {
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly fetch?: typeof globalThis.fetch;
+}
+export declare class FetchRangeReader implements RangeReader {
+    #private;
+    readonly id: string;
+    readonly url: string;
+    readonly kind: "network";
+    constructor(id: string, url: string, options?: FetchRangeReaderOptions);
+    size(signal?: AbortSignal): Promise<number>;
+    read(range: ByteRange, signal?: AbortSignal): Promise<RangeRead>;
+}
+//# sourceMappingURL=range-reader.d.ts.map

package/dist/range-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"range-reader.d.ts","sourceRoot":"","sources":["../src/range-reader.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAgCpE,qBAAa,iBAAkB,YAAW,WAAW;;aAKjC,EAAE,EAAE,MAAM;IAJ5B,SAAgB,IAAI,EAAG,QAAQ,CAAU;gBAIvB,EAAE,EAAE,MAAM,EAC1B,KAAK,EAAE,UAAU;IAKZ,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAS3C,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC;CAiBxE;AAED,qBAAa,eAAgB,YAAW,WAAW;;aAK/B,EAAE,EAAE,MAAM;IAJ5B,SAAgB,IAAI,EAAG,MAAM,CAAU;gBAIrB,EAAE,EAAE,MAAM,EAC1B,IAAI,EAAE,IAAI;IAKL,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IASrC,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC;CAe9E;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CAC1C;AAED,qBAAa,gBAAiB,YAAW,WAAW;;aAOhC,EAAE,EAAE,MAAM;aACV,GAAG,EAAE,MAAM;IAP7B,SAAgB,IAAI,EAAG,SAAS,CAAU;gBAMxB,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,MAAM,EAC3B,OAAO,GAAE,uBAA4B;IAM1B,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IA+B3C,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC;CA8E9E"}

package/dist/range-reader.js

@@ -0,0 +1,200 @@
+import { AelionError, throwIfAborted } from '@aelionsdk/core';
+function assertRange(range) {
+    if (!Number.isSafeInteger(range.offset) ||
+        !Number.isSafeInteger(range.length) ||
+        range.offset < 0 ||
+        range.length <= 0) {
+        throw new RangeError('Byte range offset must be non-negative and length must be positive');
+    }
+    if (!Number.isSafeInteger(range.offset + range.length)) {
+        throw new RangeError('Byte range end exceeds the safe integer range');
+    }
+}
+function asError(value) {
+    return value instanceof Error ? value : new Error('RangeReader failed', { cause: value });
+}
+function mediaNetworkError(code, message, cause) {
+    return new AelionError([
+        {
+            code,
+            severity: 'error',
+            message,
+            recoverable: true,
+            ...(cause === undefined ? {} : { cause }),
+        },
+    ]);
+}
+export class MemoryRangeReader {
+    id;
+    kind = 'memory';
+    #bytes;
+    constructor(id, bytes) {
+        this.id = id;
+        this.#bytes = bytes.slice();
+    }
+    size(signal) {
+        try {
+            throwIfAborted(signal, 'memory source size');
+            return Promise.resolve(this.#bytes.byteLength);
+        }
+        catch (error) {
+            return Promise.reject(asError(error));
+        }
+    }
+    read(range, signal) {
+        try {
+            throwIfAborted(signal, 'memory range read');
+            assertRange(range);
+            if (range.offset + range.length > this.#bytes.byteLength) {
+                throw new RangeError('Byte range exceeds source size');
+            }
+            return Promise.resolve({
+                bytes: this.#bytes.slice(range.offset, range.offset + range.length),
+                range,
+                totalSize: this.#bytes.byteLength,
+                source: 'memory',
+            });
+        }
+        catch (error) {
+            return Promise.reject(asError(error));
+        }
+    }
+}
+export class BlobRangeReader {
+    id;
+    kind = 'blob';
+    #blob;
+    constructor(id, blob) {
+        this.id = id;
+        this.#blob = blob;
+    }
+    size(signal) {
+        try {
+            throwIfAborted(signal, 'blob source size');
+            return Promise.resolve(this.#blob.size);
+        }
+        catch (error) {
+            return Promise.reject(asError(error));
+        }
+    }
+    async read(range, signal) {
+        throwIfAborted(signal, 'blob range read');
+        assertRange(range);
+        if (range.offset + range.length > this.#blob.size) {
+            throw new RangeError('Byte range exceeds source size');
+        }
+        const buffer = await this.#blob.slice(range.offset, range.offset + range.length).arrayBuffer();
+        throwIfAborted(signal, 'blob range read');
+        return {
+            bytes: new Uint8Array(buffer),
+            range,
+            totalSize: this.#blob.size,
+            source: 'blob',
+        };
+    }
+}
+export class FetchRangeReader {
+    id;
+    url;
+    kind = 'network';
+    #fetch;
+    #headers;
+    #size;
+    constructor(id, url, options = {}) {
+        this.id = id;
+        this.url = url;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+        this.#headers = options.headers ?? {};
+    }
+    async size(signal) {
+        throwIfAborted(signal, 'network source size');
+        if (this.#size !== undefined)
+            return this.#size;
+        let response;
+        try {
+            response = await this.#fetch(this.url, {
+                method: 'HEAD',
+                headers: this.#headers,
+                ...(signal === undefined ? {} : { signal }),
+            });
+        }
+        catch (cause) {
+            throw mediaNetworkError('MEDIA_NETWORK_OR_CORS_FAILED', 'Media HEAD request failed because of network or CORS policy', cause);
+        }
+        if (!response.ok) {
+            throw new Error(`HEAD request failed with HTTP ${response.status}`);
+        }
+        const contentLength = response.headers.get('content-length');
+        if (contentLength === null)
+            return this.#probeSize(signal);
+        const size = Number(contentLength);
+        if (!Number.isSafeInteger(size) || size <= 0) {
+            throw new Error('Content-Length is missing or outside the safe integer range');
+        }
+        this.#size = size;
+        return size;
+    }
+    async read(range, signal) {
+        throwIfAborted(signal, 'network range read');
+        assertRange(range);
+        const end = range.offset + range.length - 1;
+        let response;
+        try {
+            response = await this.#fetch(this.url, {
+                headers: { ...this.#headers, Range: `bytes=${range.offset}-${end}` },
+                ...(signal === undefined ? {} : { signal }),
+            });
+        }
+        catch (cause) {
+            throw mediaNetworkError('MEDIA_NETWORK_OR_CORS_FAILED', 'Media Range request failed because of network or CORS policy', cause);
+        }
+        if (response.status !== 206) {
+            throw mediaNetworkError(response.status === 200 ? 'MEDIA_RANGE_UNSUPPORTED' : 'MEDIA_RANGE_REQUEST_FAILED', response.status === 200
+                ? 'Server ignored Range and returned the full resource'
+                : `Range request failed with HTTP ${response.status}`);
+        }
+        const contentRange = response.headers.get('content-range');
+        const parsed = contentRange?.match(/^bytes (\d+)-(\d+)\/(\d+)$/u);
+        if (parsed === undefined || parsed === null) {
+            throw new Error('Range response is missing a valid Content-Range header');
+        }
+        const actualStart = Number(parsed[1]);
+        const actualEnd = Number(parsed[2]);
+        const totalSize = Number(parsed[3]);
+        if (actualStart !== range.offset ||
+            actualEnd !== end ||
+            !Number.isSafeInteger(totalSize) ||
+            totalSize <= end) {
+            throw new Error('Range response does not match the requested byte interval');
+        }
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        if (bytes.byteLength !== range.length) {
+            throw new Error('Range response body length does not match Content-Range');
+        }
+        this.#size = totalSize;
+        return { bytes, range, totalSize, source: 'network' };
+    }
+    async #probeSize(signal) {
+        let response;
+        try {
+            response = await this.#fetch(this.url, {
+                headers: { ...this.#headers, Range: 'bytes=0-0' },
+                ...(signal === undefined ? {} : { signal }),
+            });
+        }
+        catch (cause) {
+            throw mediaNetworkError('MEDIA_NETWORK_OR_CORS_FAILED', 'Media Range size probe failed because of network or CORS policy', cause);
+        }
+        if (response.status !== 206) {
+            throw mediaNetworkError('MEDIA_RANGE_UNSUPPORTED', 'Source size is unavailable and the server does not support byte ranges');
+        }
+        const contentRange = response.headers.get('content-range');
+        const parsed = contentRange?.match(/^bytes 0-0\/(\d+)$/u);
+        const size = parsed === undefined || parsed === null ? Number.NaN : Number(parsed[1]);
+        if (!Number.isSafeInteger(size) || size <= 0) {
+            throw new Error('Range size probe returned an invalid Content-Range');
+        }
+        this.#size = size;
+        return size;
+    }
+}

package/dist/resource-governor.d.ts

@@ -0,0 +1,32 @@
+import { type Disposable } from '@aelionsdk/core';
+export interface MediaResourceBudget {
+    readonly decoderSlots: number;
+    readonly gpuBytes: number;
+    readonly cacheBytes: number;
+}
+export type MediaResourcePriority = 'export' | 'preview' | 'background';
+export interface MediaResourceRequest extends MediaResourceBudget {
+    readonly ownerId: string;
+    readonly priority: MediaResourcePriority;
+}
+export interface MediaResourceGovernorSnapshot {
+    readonly budget: MediaResourceBudget;
+    readonly used: MediaResourceBudget;
+    readonly activeLeases: number;
+    readonly pendingRequests: number;
+    readonly disposed: boolean;
+}
+export interface MediaResourceLease extends Disposable {
+    readonly ownerId: string;
+    readonly allocation: MediaResourceBudget;
+}
+/** Shared page-level admission controller for decoder, GPU and cache allocations. */
+export declare class PageMediaResourceGovernor implements Disposable {
+    #private;
+    constructor(budget: MediaResourceBudget, maxPending?: number);
+    get disposed(): boolean;
+    snapshot(): MediaResourceGovernorSnapshot;
+    acquire(request: MediaResourceRequest, signal?: AbortSignal): Promise<MediaResourceLease>;
+    dispose(): void;
+}
+//# sourceMappingURL=resource-governor.d.ts.map

package/dist/resource-governor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-governor.d.ts","sourceRoot":"","sources":["../src/resource-governor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,SAAS,GAAG,YAAY,CAAC;AAExE,MAAM,WAAW,oBAAqB,SAAQ,mBAAmB;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;CAC1C;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAC;CAC1C;AA6BD,qFAAqF;AACrF,qBAAa,yBAA0B,YAAW,UAAU;;gBASvC,MAAM,EAAE,mBAAmB,EAAE,UAAU,SAAM;IAShE,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAEM,QAAQ,IAAI,6BAA6B;IAUzC,OAAO,CAAC,OAAO,EAAE,oBAAoB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAuCzF,OAAO,IAAI,IAAI;CAmEvB"}