tiny-essentials 1.28.1 → 1.28.2

package/dist/v1/basics/html.d.mts

@@ -9,7 +9,7 @@
  * @throws {Error} - If an unexpected error occurs while handling the result.
  * @throws {DOMException} - If the FileReader encounters an error while reading the file.
  */
-export function readFileBlob(file: File | Blob, method: "readAsArrayBuffer" | "readAsDataURL" | "readAsText" | "readAsBinaryString"): Promise<any>;
+export declare function readFileBlob(file: File | Blob, method: 'readAsArrayBuffer' | 'readAsDataURL' | 'readAsText' | 'readAsBinaryString'): Promise<any>;
 /**
  * Reads a file as a Base64 string using FileReader, and optionally formats it as a full data URL.
  *
@@ -24,7 +24,7 @@ export function readFileBlob(file: File | Blob, method: "readAsArrayBuffer" | "r
  * @throws {Error} - If the result does not match the expected data URL format or Base64 structure.
  * @throws {DOMException} - If the FileReader fails to read the file.
  */
-export function readBase64Blob(file: File | Blob, isDataUrl?: boolean | string): Promise<string>;
+export declare function readBase64Blob(file: File | Blob, isDataUrl?: boolean | string): Promise<string>;
 /**
  * Reads a file and strictly validates its content as proper JSON using FileReader.
  *
@@ -38,7 +38,7 @@ export function readBase64Blob(file: File | Blob, isDataUrl?: boolean | string):
  * @throws {Error} - If the result is empty or structurally invalid as JSON.
  * @throws {DOMException} - If the FileReader fails to read the file.
  */
-export function readJsonBlob(file: File | Blob): Promise<Record<string | number | symbol, any> | any[]>;
+export declare function readJsonBlob(file: File | Blob): Promise<Record<string | number | symbol, any> | any[]>;
 /**
  * Saves a JSON object as a downloadable file.
  * @param {string} filename
@@ -46,7 +46,8 @@ export function readJsonBlob(file: File | Blob): Promise<Record<string | number
  * @param {number} [spaces=2]
  * @throws {TypeError} - If arguments do not match expected types.
  */
-export function saveJsonFile(filename: string, data: any, spaces?: number): void;
+export declare function saveJsonFile(filename: string, data: any, spaces?: number): void;
+export type FetchOnProgressResult = (loaded: number, total: number) => void;
 /**
  * Callback function used to report the progress of a data download.
  *
@@ -67,7 +68,7 @@ export function saveJsonFile(filename: string, data: any, spaces?: number): void
  * @param {(res: Response) => ResponseInit} [returnResponse] - The callback function to return the ResponseInit to ReadableStream.
  * @returns {Response} A new Response object with the tracked stream.
  */
-export function trackFetchProgress(response: Response, onProgress: FetchOnProgressResult, returnResponse?: (res: Response) => ResponseInit): Response;
+export declare function trackFetchProgress(response: Response, onProgress: FetchOnProgressResult, returnResponse?: (res: Response) => ResponseInit): Response;
 /**
  * Loads and parses a JSON from a remote URL using Fetch API.
  *
@@ -77,7 +78,7 @@ export function trackFetchProgress(response: Response, onProgress: FetchOnProgre
  * @returns {Promise<any[] | Record<string | number | symbol, unknown>>} Parsed JSON object.
  * @throws {Error} Throws if fetch fails, times out, or returns invalid JSON.
  */
-export function fetchJson(url: string | URL | Request, options?: RequestInit | null, onProgress?: FetchOnProgressResult): Promise<any[] | Record<string | number | symbol, unknown>>;
+export declare function fetchJson(url: string | URL | Request, options?: RequestInit | null, onProgress?: FetchOnProgressResult): Promise<any[] | Record<string | number | symbol, unknown>>;
 /**
  * Loads a remote file as a Blob using Fetch API.
  *
@@ -88,7 +89,7 @@ export function fetchJson(url: string | URL | Request, options?: RequestInit | n
  * @returns {Promise<Blob>} - The fetched file as a Blob.
  * @throws {Error} Throws if fetch fails, response is not ok, or MIME type is not allowed.
  */
-export function fetchBlob(url: string | URL | Request, allowedMimeTypes?: string[], options?: RequestInit | null, onProgress?: FetchOnProgressResult): Promise<Blob>;
+export declare function fetchBlob(url: string | URL | Request, allowedMimeTypes?: string[], options?: RequestInit | null, onProgress?: FetchOnProgressResult): Promise<Blob>;
 /**
  * Loads a remote file as a text using Fetch API.
  * @param {string | URL | Request} url - The full URL to fetch the file from.
@@ -98,7 +99,39 @@ export function fetchBlob(url: string | URL | Request, allowedMimeTypes?: string
  * @returns {Promise<string>} - The fetched file as a text.
  * @throws {Error} Throws if fetch fails, response is not ok, or MIME type is not allowed.
  */
-export function fetchText(url: string | URL | Request, allowedMimeTypes?: string[], options?: RequestInit | null, onProgress?: FetchOnProgressResult): Promise<string>;
+export declare function fetchText(url: string | URL | Request, allowedMimeTypes?: string[], options?: RequestInit | null, onProgress?: FetchOnProgressResult): Promise<string>;
+export type ImageLoadResult = {
+    /**
+     * The image element instance used for loading.
+     */
+    element: HTMLImageElement;
+    /**
+     * The browser event triggered by the final lifecycle state.
+     */
+    event: Event;
+    /**
+     * The specific outcome string of the loading process.
+     */
+    status: ImageLoadStatus;
+    /**
+     * Indicates if the image was successfully loaded without errors.
+     */
+    isSuccess: boolean;
+    /**
+     * The total duration in milliseconds from start to finish.
+     */
+    loadTimeMs: number;
+    /**
+     * An object containing the rendered and intrinsic sizes of the image.
+     */
+    dimensions: {
+        width: number;
+        height: number;
+        naturalWidth: number;
+        naturalHeight: number;
+    };
+};
+export type ImageLoadStatus = 'loaded' | 'aborted';
 /**
  * Represents the final state and metadata of an attempted image load.
  * @typedef {Object} ImageLoadResult
@@ -127,10 +160,10 @@ export function fetchText(url: string | URL | Request, allowedMimeTypes?: string
  * @param {(event: Event, startTime: number) => void} [options.onLoading]
  * @returns {Promise<ImageLoadResult>}
  */
-export function loadImage(options: {
+export declare function loadImage(options: {
     url: string;
-    crossOrigin?: string | undefined;
-    onLoading?: ((event: Event, startTime: number) => void) | undefined;
+    crossOrigin?: string;
+    onLoading?: (event: Event, startTime: number) => void;
 }): Promise<ImageLoadResult>;
 /**
  * Installs a script that toggles CSS classes on a given element
@@ -146,61 +179,19 @@ export function loadImage(options: {
  * @returns {() => void} Function that removes all installed event listeners.
  * @throws {TypeError} If any provided setting is invalid.
  */
-export function installWindowHiddenScript(settings?: {
-    element?: Element | undefined;
-    hiddenClass?: string | undefined;
-    visibleClass?: string | undefined;
-    onVisible?: ((data: {
+export declare function installWindowHiddenScript(settings?: {
+    element?: Element;
+    hiddenClass?: string;
+    visibleClass?: string;
+    onVisible?: (data: {
         type: string;
         oldType: string;
         oldClass: string;
-    }) => void) | undefined;
-    onHidden?: ((data: {
+    }) => void;
+    onHidden?: (data: {
         type: string;
         oldType: string;
         oldClass: string;
-    }) => void) | undefined;
+    }) => void;
 }): () => void;
-/**
- * Callback function used to report the progress of a data download.
- */
-export type FetchOnProgressResult = (loaded: number, total: number) => void;
-/**
- * Represents the final state and metadata of an attempted image load.
- */
-export type ImageLoadResult = {
-    /**
-     * The image element instance used for loading.
-     */
-    element: HTMLImageElement;
-    /**
-     * The browser event triggered by the final lifecycle state.
-     */
-    event: Event;
-    /**
-     * The specific outcome string of the loading process.
-     */
-    status: ImageLoadStatus;
-    /**
-     * Indicates if the image was successfully loaded without errors.
-     */
-    isSuccess: boolean;
-    /**
-     * The total duration in milliseconds from start to finish.
-     */
-    loadTimeMs: number;
-    /**
-     * An object containing the rendered and intrinsic sizes of the image.
-     */
-    dimensions: {
-        width: number;
-        height: number;
-        naturalWidth: number;
-        naturalHeight: number;
-    };
-};
-/**
- * Describes the possible resolution states for the image loading attempt.
- */
-export type ImageLoadStatus = "loaded" | "aborted";
 //# sourceMappingURL=html.d.mts.map

package/dist/v1/basics/index.d.mts

@@ -1,68 +1,12 @@
-import { multiplyArrayBlocks } from './array.mjs';
-import { valMediaContentMetadata } from './mediaContent.mjs';
-import { valMediaContentMetadataPartial } from './mediaContent.mjs';
-import { parseMediaMetadata } from './mediaContent.mjs';
-import { extractMediaId3Tags } from './mediaContent.mjs';
-import { diffStrings } from './text.mjs';
-import { diffObjList } from './text.mjs';
-import { diffArrayList } from './array.mjs';
-import { breakdownDuration } from './clock.mjs';
-import { calculateMarketcap } from './simpleMath.mjs';
-import { compareMarketcap } from './simpleMath.mjs';
-import { getPercentage } from './simpleMath.mjs';
-import { areElsCollTop } from './collision.mjs';
-import { areElsCollBottom } from './collision.mjs';
-import { areElsCollLeft } from './collision.mjs';
-import { areElsCollRight } from './collision.mjs';
-import { areElsCollPerfTop } from './collision.mjs';
-import { areElsCollPerfBottom } from './collision.mjs';
-import { areElsCollPerfLeft } from './collision.mjs';
-import { areElsCollPerfRight } from './collision.mjs';
-import { areElsColliding } from './collision.mjs';
-import { areElsPerfColliding } from './collision.mjs';
-import { getElsColliding } from './collision.mjs';
-import { getElsPerfColliding } from './collision.mjs';
-import { getElsCollOverlap } from './collision.mjs';
-import { getElsCollOverlapPos } from './collision.mjs';
-import { getRectCenter } from './collision.mjs';
-import { getElsRelativeCenterOffset } from './collision.mjs';
-import { getElsCollDirDepth } from './collision.mjs';
-import { getElsCollDetails } from './collision.mjs';
-import { safeTextTrim } from './text.mjs';
-import { installWindowHiddenScript } from './html.mjs';
-import { genFibonacciSeq } from './simpleMath.mjs';
-import { fetchJson } from './html.mjs';
-import { fetchText } from './html.mjs';
-import { readJsonBlob } from './html.mjs';
-import { readFileBlob } from './html.mjs';
-import { readBase64Blob } from './html.mjs';
-import { saveJsonFile } from './html.mjs';
-import { documentIsFullScreen } from './fullScreen.mjs';
-import { isScreenFilled } from './fullScreen.mjs';
-import { requestFullScreen } from './fullScreen.mjs';
-import { exitFullScreen } from './fullScreen.mjs';
-import { isFullScreenMode } from './fullScreen.mjs';
-import { onFullScreenChange } from './fullScreen.mjs';
-import { offFullScreenChange } from './fullScreen.mjs';
-import { isJsonObject } from './objChecker.mjs';
-import { arraySortPositions } from './array.mjs';
-import { formatBytes } from './simpleMath.mjs';
-import { addAiMarkerShortcut } from './text.mjs';
-import { extendObjType } from './objFilter.mjs';
-import { reorderObjTypeOrder } from './objFilter.mjs';
-import { cloneObjTypeOrder } from './objFilter.mjs';
-import { countObj } from './objChecker.mjs';
-import { objType } from './objFilter.mjs';
-import { ruleOfThree } from './simpleMath.mjs';
-import { getSimplePerc } from './simpleMath.mjs';
-import { asyncReplace } from './text.mjs';
-import { getAge } from './simpleMath.mjs';
-import { formatCustomTimer } from './clock.mjs';
-import { formatDayTimer } from './clock.mjs';
-import { formatTimer } from './clock.mjs';
-import { getTimeDuration } from './clock.mjs';
-import { shuffleArray } from './array.mjs';
-import { toTitleCase } from './text.mjs';
-import { toTitleCaseLowerFirst } from './text.mjs';
-export { multiplyArrayBlocks, valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, diffStrings, diffObjList, diffArrayList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst };
+import { diffArrayList, shuffleArray, arraySortPositions, multiplyArrayBlocks } from './array.mjs';
+import { breakdownDuration, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration } from './clock.mjs';
+import { readJsonBlob, saveJsonFile, fetchJson, installWindowHiddenScript, readFileBlob, readBase64Blob, fetchText } from './html.mjs';
+import { extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, objType } from './objFilter.mjs';
+import { countObj, isJsonObject } from './objChecker.mjs';
+import { documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange } from './fullScreen.mjs';
+import { calculateMarketcap, compareMarketcap, formatBytes, genFibonacciSeq, getAge, getPercentage, getSimplePerc, ruleOfThree } from './simpleMath.mjs';
+import { addAiMarkerShortcut, diffStrings, diffObjList, safeTextTrim, toTitleCase, toTitleCaseLowerFirst, asyncReplace } from './text.mjs';
+import { areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails } from './collision.mjs';
+import { extractMediaId3Tags, parseMediaMetadata, valMediaContentMetadata, valMediaContentMetadataPartial } from './mediaContent.mjs';
+export { multiplyArrayBlocks, valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, diffStrings, diffObjList, diffArrayList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };
 //# sourceMappingURL=index.d.mts.map

package/dist/v1/basics/mediaContent.cjs

@@ -1,12 +1,18 @@
 'use strict';
 
 /**
+ * A type representing either a static string or a function that returns a string, used to resolve an unknown artist's name.
  * @typedef {string|(() => string)} UnknownArtistGetter
  */
 
+/**
+ * Represents the data type for images, which can be raw binary (Uint8Array) or a string (such as a Blob URL or Data URL).
+ * @typedef {Uint8Array|string} PictureDataType
+ */
+
 /**
  * Represents an image attachment template.
- * @template {Uint8Array|string} PictureData
+ * @template {PictureDataType} PictureData
  * @typedef {Object} IPictureTemplate
  * @property {string} format - The MIME type of the image (e.g., 'image/jpeg').
  * @property {PictureData} data - The raw binary data of the image.
@@ -28,7 +34,7 @@
 /**
  * This metadata structure is modeled template.
  *
- * @template {IPictureTemplate<Uint8Array|string>} IPictureContent
+ * @template {IPictureTemplate<PictureDataType>} IPictureContent
  * @typedef {Object} ContentMetadataTemplate
  * @property {string|null} title - The title of the track.
  * @property {string|null} album - The name of the album.
@@ -49,7 +55,8 @@
  * This metadata structure is modeled after the standard output of the
  * `music-metadata@11.13.0` npm package.
  *
- * @typedef {ContentMetadataTemplate<IPicture>} MediaContentMetadata
+ * @template {PictureDataType} PictureData
+ * @typedef {ContentMetadataTemplate<IPictureTemplate<PictureData>>} MediaContentMetadata
  */
 
 /**
@@ -67,7 +74,8 @@
  * The final content object used within the media, combining
  * core playback properties with rich metadata.
  *
- * @typedef {MediaContentBase & MediaContentMetadata} MediaContent
+ * @template {PictureDataType} PictureData
+ * @typedef {MediaContentBase & MediaContentMetadata<PictureData>} MediaContent
  */
 
 //////////////////////////////////////////////////////////////////
@@ -76,11 +84,11 @@
  * A promise that resolves to an object containing the extracted metadata.
  * @callback ParseMediaContentMetadata
  * @param {Blob} data - The raw file blob.
- * @returns {Promise<{ common: Partial<ContentMetadataTemplate<IPictureTemplate<Uint8Array|string>>> }>} A promise resolving to the common metadata properties.
+ * @returns {Promise<{ common: Partial<ContentMetadataTemplate<IPictureTemplate<PictureDataType>>> }>} A promise resolving to the common metadata properties.
  */
 
 /**
- * @typedef {Object} LoadingMediaProgress
+ * @typedef {Object} LoadingMediaProgress Represents the current state of a media loading operation, including its status, execution stage, and the URL being processed.
  * @property {'loading'|'success'} status - The current status of the operation.
  * @property {LoadingProgressStage} stage - The current execution stage.
  * @property {ProgressEvent<EventTarget>} [event] - The current loading event.
@@ -88,14 +96,17 @@
  */
 
 /**
+ * Defines the specific execution stages of a successful loading process.
  * @typedef {'INITIALIZING'|'DOWNLOADING'|'METADATA_LOADED'|'EXTRACTING_ID3'|'COMPLETE'} LoadingProgressStage
  */
 
 /**
+ * Defines the specific stages where a loading error might occur.
  * @typedef {'INITIALIZING'|'DOWNLOADING'|'METADATA'|'ID3'|'UNKNOWN'} LoadingErrorStage
  */
 
 /**
+ * A data structure containing details about a media loading error.
  * @typedef {Object} MediaLoadingErrorData
  * @property {Error} error - The original error object.
  * @property {string} url - The URL that failed.
@@ -105,14 +116,19 @@
 //////////////////////////////////////////////////////////////////
 
 const checkString = (/** @type {string} */ val, /** @type {string} */ name) => {
+  if (typeof name !== 'string') throw new TypeError('Expected "name" to be a string.');
   if (typeof val !== 'string')
     throw new TypeError(`Expected "${name}" to be a string, but received ${typeof val}.`);
 };
+
 const checkFunction = (/** @type {Function} */ val, /** @type {string} */ name) => {
+  if (typeof name !== 'string') throw new TypeError('Expected "name" to be a string.');
   if (typeof val !== 'function')
     throw new TypeError(`Expected "${name}" to be a function, but received ${typeof val}.`);
 };
+
 const checkObject = (/** @type {Object<string, any> | null} */ val, /** @type {string} */ name) => {
+  if (typeof name !== 'string') throw new TypeError('Expected "name" to be a string.');
   if (typeof val !== 'object' || val === null || Array.isArray(val)) {
     throw new TypeError(
       `Expected "${name}" to be a plain object, but received ${val === null ? 'null' : Array.isArray(val) ? 'array' : typeof val}.`,
@@ -123,7 +139,10 @@ const checkObject = (/** @type {Object<string, any> | null} */ val, /** @type {s
 /** @type {Map<string, number>} */
 const _blobCounter = new Map();
 
-/** @returns {MediaContentBase} */
+/**
+ * Returns a new object initialized with the default values for the core media content properties.
+ * @returns {MediaContentBase}
+ */
 const getMediaContentBase = () => ({
   id: '',
   title: '',
@@ -133,7 +152,10 @@ const getMediaContentBase = () => ({
   weight: 1,
 });
 
-/** @returns {MediaContentMetadata} */
+/**
+ * Returns a new object initialized with the default values for the media content metadata properties.
+ * @returns {MediaContentMetadata<PictureDataType>}
+ */
 const getMediaContentMetadata = () => ({
   title: null,
   album: null,
@@ -194,7 +216,7 @@ const generateSimpleHash = async (str) => {
 
 /**
  * Helper to convert Uint8Array or Base64 string directly into a high performance Blob URL.
- * @param {Uint8Array|string} data
+ * @param {PictureDataType} data
  * @param {string} format
  * @returns {string} The generated Blob URL or original string if already valid.
  */
@@ -256,7 +278,8 @@ const blobUrlToBase64 = async (url) => {
 
 /**
  * Safely revokes Blob URLs to prevent memory leaks from createObjectURL.
- * @param {MediaContent} content
+ * @template {PictureDataType} PictureData
+ * @param {MediaContent<PictureData>} content
  */
 const revokeContentUrls = (content) => {
   checkObject(content, 'content');
@@ -294,6 +317,7 @@ const validateMediaContent = (common, isPartial) => {
     /** @type {string[] | IPictureTemplate<string|Uint8Array>[] | undefined} */ v,
     /** @type {(value: any, index: number, array: any[]) => any} */ valueValidator,
   ) => {
+    checkFunction(valueValidator, 'valueValidator');
     if (isUndefinedAllowed(v)) return true;
     if (Array.isArray(v) && v.every(valueValidator)) return true;
     return false;
@@ -339,10 +363,11 @@ const validateMediaContent = (common, isPartial) => {
 
   /**
    * Validate Nested Objects (Disk and Track)
+   * @param {string} name
    * @param {MediaNumber|null} [info]
-   * @param {string} [name]
    */
-  const validateTrackInfo = (info, name) => {
+  const validateTrackInfo = (name, info) => {
+    checkString(name, 'name');
     if (isUndefinedAllowed(info)) return; // Ignores if partial
 
     if (info === undefined || info === null) {
@@ -357,8 +382,8 @@ const validateMediaContent = (common, isPartial) => {
       throw new TypeError(`Invalid metadata: "${name}.of" must be a number or null.`);
   };
 
-  validateTrackInfo(common.disk, 'disk');
-  validateTrackInfo(common.track, 'track');
+  validateTrackInfo('disk', common.disk);
+  validateTrackInfo('track', common.track);
 };
 
 /**
@@ -366,21 +391,27 @@ const validateMediaContent = (common, isPartial) => {
  * This ensures that if a property is present, it matches the expected type.
  * @param {ContentMetadataTemplate<IPictureTemplate<string | Uint8Array<ArrayBufferLike>>>} common
  */
-const valMediaContentMetadata = (common) => validateMediaContent(common, false);
+const valMediaContentMetadata = (common) => {
+  checkObject(common, 'common');
+  return validateMediaContent(common, false);
+};
 
 /**
  * Helper to validate types within the media content metadata object.
  * Allows the absence of properties (useful for updates/patch).
  * @param {Partial<ContentMetadataTemplate<IPictureTemplate<string | Uint8Array<ArrayBufferLike>>>>} common
  */
-const valMediaContentMetadataPartial = (common) => validateMediaContent(common, true);
+const valMediaContentMetadataPartial = (common) => {
+  checkObject(common, 'common');
+  return validateMediaContent(common, true);
+};
 
 /**
  * Downloads an audio file from a URL and extracts its ID3/metadata tags.
  *
  * @param {string} url - The full URL of the audio file to be downloaded.
  * @param {ParseMediaContentMetadata} parseFile - The function used to parse the file data.
- * @returns {Promise<MediaContentMetadata>} A promise that resolves to an object containing the extracted metadata.
+ * @returns {Promise<MediaContentMetadata<string>>} A promise that resolves to an object containing the extracted metadata.
  * @throws {TypeError} If the provided `url` is not a string or `parseFile` is not a function.
  * @throws {Error} If the network request fails or the parsing process encounters an error.
  */
@@ -440,15 +471,16 @@ const extractMediaId3Tags = async (url, parseFile) => {
  * A Static Factory Method that prepares a MediaContent object by
  * extracting metadata from an audio source.
  *
+ * @template {PictureDataType} PictureData
  * @param {string | HTMLMediaElement} source - A URL string or an existing Audio object.
- * @param {Partial<MediaContentBase & MediaContentMetadata> & { id?: string; weight?: number }} [defaultMetadata={}] - Optional default metadata that overrides automatic extraction.
- * @param {Partial<MediaContentBase & MediaContentMetadata> & { id?: string; weight?: number }} [metadata={}] - Optional manual metadata that overrides automatic extraction.
+ * @param {Partial<MediaContentBase & MediaContentMetadata<PictureData>> & { id?: string; weight?: number }} [defaultMetadata={}] - Optional default metadata that overrides automatic extraction.
+ * @param {Partial<MediaContentBase & MediaContentMetadata<PictureData>> & { id?: string; weight?: number }} [metadata={}] - Optional manual metadata that overrides automatic extraction.
  * @param {ParseMediaContentMetadata} [parseFile] - Private helper to interface with parseFile.
  * @param {Object} [callbacks={}] - Callbacks for monitoring the loading process.
  * @param {(progress: LoadingMediaProgress) => void} [callbacks.onProgress] - Callback triggered on stage changes.
  * @param {(error: MediaLoadingErrorData) => void} [callbacks.onError] - Callback triggered when a non-fatal or fatal error occurs.
  * @param {UnknownArtistGetter} unknownArtist
- * @returns {Promise<MediaContent>} A promise that resolves to a valid MediaContent object.
+ * @returns {Promise<MediaContent<PictureData>>} A promise that resolves to a valid MediaContent object.
  * @throws {MediaLoadingError} If the preparation process fails at any stage.
  *
  * @example
@@ -482,7 +514,8 @@ const parseMediaMetadata = async (
   source,
   defaultMetadata = {},
   metadata = {},
-  parseFile = (url) => {
+  parseFile = (data) => {
+    if (!(data instanceof Blob)) throw new TypeError('Expected "data" to be a Blob.');
     return new Promise((resolve, reject) => reject(new TypeError('parseFile library not found.')));
   },
   callbacks = {},
@@ -516,6 +549,11 @@ const parseMediaMetadata = async (
    * @param {ProgressEvent<EventTarget>} [event]
    */
   const notifyProgress = (stage, event) => {
+    checkString(stage, 'stage');
+    if (event !== undefined && !(event instanceof Event)) {
+      throw new TypeError('Expected "event" to be an Event or undefined.');
+    }
+
     if (callbacks.onProgress) {
       callbacks.onProgress({
         event,
@@ -527,6 +565,9 @@ const parseMediaMetadata = async (
   };
 
   const notifyError = (/** @type {Error} */ error, /** @type {LoadingErrorStage} */ stage) => {
+    if (!(error instanceof Error)) throw new TypeError('Expected "error" to be an Error.');
+    checkString(stage, 'stage'); // Adicionado
+
     if (callbacks.onError) {
       callbacks.onError({
         error,
@@ -603,7 +644,7 @@ const parseMediaMetadata = async (
     };
 
     // 4. Automatic Metadata Extraction (ID3 Tags)
-    /** @type {Partial<MediaContentMetadata>} */
+    /** @type {Partial<MediaContentMetadata<string>>} */
     let extractedMetadata = {};
     notifyProgress('EXTRACTING_ID3');
     try {
@@ -621,6 +662,7 @@ const parseMediaMetadata = async (
      * @returns {string}
      */
     const getFallbackTitleFromUrl = (url) => {
+      checkString(url, 'url');
       try {
         // Remove query params or hashes, get the last segment, and strip extension
         const filename = url.split(/[?#]/)[0].split('/').pop();
@@ -654,7 +696,7 @@ const parseMediaMetadata = async (
       });
     }
 
-    return /** @type {MediaContent} */ (finalContent);
+    return /** @type {MediaContent<PictureData>} */ (finalContent);
   } catch (err) {
     // If it's already a MediaLoadingError, re-throw it.
     // Otherwise, wrap it.