Image Gift Overlay Creator

/**
 * Overlays a gift-themed animated GIF on top of an image.
 * This function creates a container element with the original image as a background
 * and places an animated GIF on top of it, returning the container.
 *
 * @param {HTMLImageElement} originalImg The original javascript Image object.
 * @param {string} [gifUrl] The URL of the GIF to overlay. Defaults to a built-in falling gifts animation. The URL can be a web link or a Base64 data URI.
 * @param {number} [x=0] The horizontal position (in pixels) of the overlay from the left edge of the image.
 * @param {number} [y=0] The vertical position (in pixels) of the overlay from the top edge of the image.
 * @param {string} [width='100%'] The width of the overlay. Can be in pixels (e.g., '150px') or percentage (e.g., '100%').
 * @param {string} [height='100%'] The height of the overlay. Can be in pixels (e.g., '150px') or percentage (e.g., '100%').
 * @param {number} [opacity=0.8] The opacity of the overlay, from 0.0 (fully transparent) to 1.0 (fully opaque).
 * @returns {HTMLElement} A div element containing the original image with the GIF overlay, ready to be displayed.
 */
function processImage(originalImg, gifUrl = 'data:image/gif;base64,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v7///wAGKOCABBZo4IEIJqjgggw26OCDEEYo4YQUVmjhhRhmqOGGHHbo4YcghijiiCSWaOKJKKao4oostujiizDGKOOMNNZo44045qjjjjz26OOPQAYp5JBEFmnkkUgmqeSSTDbp5JNQRinllFRWaeWVWGap5ZZcdunll2CGKeaYZJZp5plopqnmmmy26eabcMYp55x01mnnnXjmqeeefPbp55+ABirooIQWauihiCaq6KKMNuroo5BGKumklFZq6aWYZqrpppx26umnoIYq6qiklmrqqaimquqqrLbq6quwxirrrLTWauutuOaq66689urrr8AGK+ywxBZr7LHIJqvsssw26+yz0EYr7bTUVmvttdhmq+223Hbr7bfghivuuOSWa+656KarrrrsphIBACH5BAkJABoALAAAAABkAGQAAAX/ICeOZGmeaKqubOu+cCzPdG3feK7vfO//wKBwSCwaj8ikcslsOp/QqHRKrVqv2Kx2y+16v+CweEwum8/otHrNbrvf8Lh8Tq/b7/i8fs/v+/+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmqq6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsfIycrLzM3Oz9DR0tPU1f8ANdzl09fY2drb3N3e3+Di4+Tl5ufo6err7O3u7/Dx8vP09fb3+Pn6+/z9/v/w8woMCBBAsaPAgwocKFDBs6fAgxosSJFCtavIgxY8N2/yA2bPhwY0eQI0d+HEmypMmTK1OkfJmypcuXJ1PCzAlyps2bB2XevMmzp8+fQIMKHUq0qNChR5MmLWq0qVOnUKP6nEq1KtWrWLMiVbp1q9evYMOKHUu2bNmzaNOqXcu2rdu3cOPKnUu3rt27ePPq3cu3r9+/gAMLHky4sOHDiBMrXsy4sePHkCNLnky5suXLmDNr3sy5s+fPoEOLHk26tOnTqFOrXs26tevXsGPLnk27tu3buHPr3s27t+/fwIMLH068uPHjyJMrX868ufPn0KNLn069uvXryLFk1769u/fv4MOLH285vHvz6NOrX8++vfv38OPLn0+/vv37+PPr38+/v///AAYo4IAEFmjggQgmqOCCDDbo4IMQRijhhBRWaOGFGGao4YYcdujhhx9G+OCEI5Zo4okopqjiiiy26OKLMMYo44w01mjjjTjmqOOOPPbo449ABinkkEQWaeSRSCap5JJMNunkk1BGKeWUVFZp5ZVYZqnlllx26eWXYIYp5phklmnmmWimqeaabLbp5ptwxinnnHTWaeedeOap55589unnn4AGKuighBZq6KGIJqrooow26uijkEYq6aSUVmrppZhmqummnHbq6aeghirqqKSWauqpqKaq6qqsturqq7DGKuus/9Zq66245qrrrrz26uuvwAYr7LDEFmvsscgmq+yvzMJAwQMEMABAADTYoIIFEjDAgQMP+ECDAA4QkEMHA0AQwAP47rttAvvu4QMC/O67LgL87gtAvwAIEAEAOgQwQMMMNPDABA8UUAEDCExgwAMPPBAAAQYcoEAH+O6bgAEJTNABBAYc0EADDjDQwAMP/GCBAAYkUEADHBBQwwMGHJBABxTwYAIJJ2SQwAMP/GDAAx4sUMEDDDRwwQEJSBDByAUkUEG/BOKLcgEOQOCzBAccUEADHSCQwwcPPNBABA0sUAAEGJDAwwcbbDAAAwYgUMEDDPQLNgISSP20AwckQMAEGSCQ9gMHDv9c4IADDzTwQAMNILCAAww8UAADBPQbN+CDDw7AQAQJTNABAww88EADD0zgwAMPPPBABA0sUEADDSCQwwckwMAEGCSgQAMNNLAAAw888IADD0QAgQMP/GDCAAYkUEEDDTRwwQGSH+DAA3wXz334CCRw+gMOBBCAAg4kUMEDCRw/fvvst+8BACH5BAkJABYALAAAAABkAGQAAAX/ICeOZGmeaKqubOu+cCzPdG3feK7vfO//wKBwSCwaj8ikcslsOp/QqHRKrVqv2Kx2y+16v+CweEwum8/otHrNbrvf8Lh8Tq/b7/i8fs/v+/+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmqq6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsfIycrLzM3Oz9DR0tPU1f8ANdzl09fY2drb3N3e3+Di4+Tl5ufo6err7O3u7/Dx8vP09fb3+Pn6+/z9/v/w8woMCBBAsaPAgwocKFDBs6fAgxosSJFCtavIgxY8N2/yBGjhxYsaPIkyhTqlzJsqXLlzBjypxJs6bNmzhz6tzJs6fPn0CDCh1IdCjSo0iTKv1lUajTpw4vTpxKtWo9BQA3WMS4lWvXrhg/gB1LdqzZs2jTql3Ltq1bghzgyp1L9yDduwABGMB7d28BAv8CDiy4sIACAQAE/u17t3EBCAAAKIBcGS/ky5gxaw4AwPLlAQAnS55MubTpy6Ixa97MubPnAzUVAECsurXr2LBTs55Nu7bt25hr697Nu7fv38CDCx9OvLjx48iTK1/OvLnz59CjS59Ovbr169iza9/Ovbv37+DDix9Pvrz58+jTq1/Pvr379/Djy59Pv779+/jz69/Pv7///wAGKOCABBZo4IEIJqjgggw26OCDEEYo4YQUVmjhhRhmqOGGHHbo4YcghijiiCSWaOKJKKao4oostujiizDGKOOMNNZo44045qjjjjz26OOPQAYp5JBEFmnkkUgmqeSSTDbp5JNQRinllFRWaeWVWGap5ZZcdunll2CGKeaYZJZp5plopqnmmmy26eabcMYp55x01mnnnXjmqeeefPbp55+ABirooIQWauihiCaq6KKMNuroo5BGKumklFZq6aWYZqrpppx26umnoIYq6qiklmrqqaimquqqrLbq6quwxirrrLTWauutuOaq66689urrr8AGK+ywxBZr7LHIJqvsssw26+yz0EYr7bTUVmvttdhmq+223Hbr7bfghivuuOSWa+656KarrrrsphIBACH5BAkJABoALAAAAABkAGQAAAX/ICeOZGmeaKqubOu+cCzPdG3feK7vfO//wKBwSCwaj8ikcslsOp/QqHRKrVqv2Kx2y+16v+CweEwum8/otHrNbrvf8Lh8Tq/b7/i8fs/v+/+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmqq6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsfIycrLzM3Oz9DR0tPU1f8ANdzl09fY2drb3N3e3+Di4+Tl5ufo6err7O3u7/Dx8vP09fb3+Pn6+/z9/v/w8woMCBBAsaPAgwocKFDBs6fAgxosSJFCtavIgxY8N2/yA2bPhwY0eQI0d+HEmypMmTK1OkfJmypcuXJ1PCzAlyps2bB2XevMmzp8+fQIMKHUq0qNChR5MmLWq0qVOnUKP6nEq1KtWrWLMiVbp1q9evYMOKHUu2bNmzaNOqXcu2rdu3cOPKnUu3rt27ePPq3cu3r9+/gAMLHky4sOHDiBMrXsy4sePHkCNLnky5suXLmDNr3sy5s+fPoEOLHk26tOnTqFOrXs26tevXsGPLnk27tu3buHPr3s27t+/fwIMLH068uPHjyJMrX868ufPn0KNLn069uvXryLFk1769u/fv4MOLH285vHvz6NOrX8++vfv38OPLn0+/vv37+PPr38+/v///AAYo4IAEFmjggQgmqOCCDDbo4IMQRijhhBRWaOGFGGao4YYcdujhhx9G+OCEI5Zo4okopqjiiiy26OKLMMYo44w01mjjjTjmqOOOPPbo449ABinkkEQWaeSRSCap5JJMNunkk1BGKeWUVFZp5ZVYZqnlllx26eWXYIYp5phklmnmmWimqeaabLbp5ptwxinnnHTWaeedeOap55589unnn4AGKuighBZq6KGIJqrooow26uijkEYq6aSUVmrppZhmqummnHbq6aeghirqqKSWauqpqKaq6qqsturqq7DGKuus/9Zq66245qrrrrz26uuvwAYr7LDEFmvsscgmq+yvzMJAwQMEMABAADTYoIIFEjDAgQMP+ECDAA4QkEMHA0AQwAP47rttAvvu4QMC/O67LgL87gtAvwAIEAEAOgQwQMMMNPDABA8UUAEDCExgwAMPPBAAAQYcoEAH+O6bgAEJTNABBAYc0EADDjDQwAMP/GCBAAYkUEADHBBQwwMGHJBABxTwYAIJJ2SQwAMP/GDAAx4sUMEDDDRwwQEJSBDByAUkUEG/BOKLcgEOQOCzBAccUEADHSCQwwcPPNBABA0sUAAEGJDAwwcbbDAAAwYgUMEDDPQLNgISSP20AwckQMAEGSCQ9gMHDv9c4IADDzTwQAMNILCAAww8UAADBPQbN+CDDw7AQAQJTNABAww88EADD0zgwAMPPPBABA0sUEADDSCQwwckwMAEGCSgQAMNNLAAAw888IADD0QAgQMP/GDCAAYkUEEDDTRwwQGSH+DAA3wXz334CCRw+gMOBBCAAg4kUMEDCRw/fvvst+8BACH5BAkJABYALAAAAABkAGQAAAX/ICeOZGmeaKqubOu+cCzPdG3feK7vfO//wKBwSCwaj8ikcslsOp/QqHRKrVqv2Kx2y+16v+CweEwum8/otHrNbrvf8Lh8Tq/b7/i8fs/v+/+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmqq6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsfIycrLzM3Oz9DR0tPU1f8ANdzl09fY2drb3N3e3+Di4+Tl5ufo6err7O3u7/Dx8vP09fb3+Pn6+/z9/v/w8woMCBBAsaPAgwocKFDBs6fAgxosSJFCtavIgxY8N2/yBGjhxYsaPIkyhTqlzJsqXLlzBjypxJs6bNmzhz6tzJs6fPn0CDCh1IdCjSo0iTKv1lUajTpw4vTpxKtWo9BQA3WMS4lWvXrhg/gB1LdqzZs2jTql3Ltq1bghzgyp1L9yDduwABGMB7d28BAv8CDiy4sIACAQAE/u17t3EBCAAAKIBcGS/ky5gxaw4AwPLlAQAnS55MubTpy6Ixa97MubPnAzUVAECsurXr2LBTs55Nu7bt25hr697Nu7fv38CDCx9OvLjx48iTK1/OvLnz59CjS59Ovbr169iza9/Ovbv37+DDix9Pvrz58+jTq1/Pvr379/Djy59Pv779+/jz69/Pv7///wAGKOCABBZo4IEIJqjgggw26OCDEEYo4YQUVmjhhRhmqOGGHHbo4YcghijiiCSWaOKJKKao4oostujiizDGKOOMNNZo44045qjjjjz26OOPQAYp5JBEFmnkkUgmqeSSTDbp5JNQRinllFRWaeWVWGap5ZZcdunll2CGKeaYZJZp5plopqnmmmy26eabcMYp55x01mnnnXjmqeeefPbp55+ABirooIQWauihiCaq6KKMNuroo5BGKumklFZq6aWYZqrpppx26umnoIYq6qiklmrqqaimquqqrLbq6quwxirrrLTWauutuOaq66689urrr8AGK+ywxBZr7LHIJqvsssw26+yz0EYr7bTUVmvttdhmq+223Hbr7bfghivuuOSWa+656KarrrrsphIBACH5BAkJABkALAAAAABkAGQAAAX/ICeOZGmeaKqubOu+cCzPdG3feK7vfO//wKBwSCwaj8ikcslsOp/QqHRKrVqv2Kx2y+16v+CweEwum8/otHrNbrvf8Lh8Tq/b7/i8fs/v+/+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmqq6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsfIycrLzM3Oz9DR0tPU1f8ANdzl09fY2drb3N3e3+Di4+Tl5ufo6err7O3u7/Dx8vP09fb3+Pn6+/z9/v/w8woMCBBAsaPAgwocKFDBs6fAgxosSJFCtavIgxY8N2/yBGjhxYsaPIkyhTqlzJsqXLlzBjypxJs6bNmzhz6tzJs6fPn0CDCh1IdCjSo0iTKv1lUajTpw4vTpxKtWo9BQA3WMS4lWvXrhg/gB1LdqzZs2jTql3Ltq1bghzgyp1L9yDduwABGMB7d28BAv8CDiy4sIACAQAE/u17t3EBCAAAKIBcGS/ky5gxaw4AwPLlAQAnS55MubTpy6Ixa97MubPnAzUVAECsurXr2LBTs55Nu7bt25hr697Nu7fv38CDCx9OvLjx48iTK1/OvLnz59CjS59Ovbr169iza9/Ovbv37+DDix9Pvrz58+jTq1/Pvr379/Djy59Pv779+/jz69/Pv7///wAGKOCABBZo4IEIJqjgggw26OCDEEYo4YQUVmjhhRhmqOGGHHbo4YcghijiiCSWaOKJKKao4oostujiizDGKOOMNNZo44045qjjjjz26OOPQAYp5JBEFmnkkUgmqeSSTDbp5JNQRinllFRWaeWVWGap5ZZcdunll2CGKeaYZJZp5plopqnmmmy26eabcMYp55x01mnnnXjmqeeefPbp55+ABirooIQWauihiCaq6KKMNuroo5BGKumklFZq6aWYZqrpppx26umnoIYq6qiklmrqqaimquqqrLbq6quwxirrrLTWauutuOaq66689urrr9QCADs=', x = 0, y = 0, width = '100%', height = '100%', opacity = 0.8) {

    // Create a container div that will hold both images.
    const container = document.createElement('div');
    // Use relative positioning to allow absolute positioning for the overlay.
    container.style.position = 'relative';
    // Match the container size to the original image dimensions.
    container.style.width = originalImg.naturalWidth + 'px';
    container.style.height = originalImg.naturalHeight + 'px';
    // Use inline-block to make the container only as big as the image.
    container.style.display = 'inline-block';

    // Clone the original image to avoid modifying the passed-in object.
    const baseImage = originalImg.cloneNode();
    baseImage.style.display = 'block'; // Prevents extra space below the image.
    baseImage.style.width = '100%';
    baseImage.style.height = '100%';

    // Create the img element for the GIF overlay.
    const gifOverlay = document.createElement('img');
    gifOverlay.src = gifUrl;

    // Style the GIF to sit on top of the base image.
    gifOverlay.style.position = 'absolute';
    gifOverlay.style.left = x + 'px';
    gifOverlay.style.top = y + 'px';
    gifOverlay.style.width = width;
    gifOverlay.style.height = height;
    gifOverlay.style.opacity = opacity;
    gifOverlay.style.pointerEvents = 'none'; // Makes the overlay non-interactive.

    // Add both images to the container.
    container.appendChild(baseImage);
    container.appendChild(gifOverlay);

    // Return the container element.
    return container;
}