tiny-essentials 1.29.1 → 1.29.2

package/dist/v1/libs/html/loader/formats/TinyImageLoader.mjs

@@ -0,0 +1,1317 @@
+/**
+ * @fileoverview Concrete loader for images. Exposes cache detection, aspect
+ * ratio helpers, full control over the decode step, and advanced animation parsing.
+ */
+import TinyMediaLoader from '../TinyMediaLoader.mjs';
+import TinyImageProbe from '../probe/TinyImageProbe.mjs';
+import TinyMediaCache from '../utils/TinyMediaCache.mjs';
+const EMPTY_GIF = 'data:image/gif;base64,R0lGODlhAQABAAD/ACwAAAAAAQABAAACADs=';
+/**
+ * A reference to the early decoder type used for extracting metadata from raw bytes.
+ * @typedef {import('../TinyMediaLoader.mjs').MediaEarlyDecoder} MediaEarlyDecoder
+ */
+/**
+ * @typedef {Object} AnimationFrame
+ * @property {string} url - The Object URL of the single-frame blob.
+ * @property {string} cacheKey - The unique key used in TinyMediaCache.
+ */
+/**
+ * @typedef {Object} AnimationScriptStep
+ * @property {number} delay - Duration of the frame in milliseconds.
+ */
+/**
+ * @typedef {Object} ImageLoaderOptions
+ * @property {string} [src] - The image source URL.
+ * @property {number} [timeout] - Maximum time in milliseconds before the load is aborted.
+ * @property {string|null} [crossOrigin] - The CORS mode applied to the image.
+ * @property {'sync'|'async'|'auto'} [decoding] - The decoding hint passed to the browser.
+ * @property {HTMLImageElement|null} [element] - An existing DOM element to adopt.
+ * @property {boolean} [earlyDecode] - Whether to decode the dimensions from the response headers using WebCodecs.
+ * @property {boolean} [progressive] - Whether to show the image progressively while streaming (default true).
+ * @property {boolean} [autoReload] - Whether an external `src` change triggers a reload.
+ * @property {boolean} [stream] - Whether to download the image through fetch for byte progress.
+ * @property {boolean} [useHeadRequest] - Whether to perform a HEAD request to fetch HTTP headers before downloading.
+ * @property {BodyInit} [body] - The request body forwarded to the transport (ignored by `GET`/`HEAD`).
+ * @property {boolean} [mirror] - Whether concurrent loads of the same source share a single download (default true).
+ * @property {import('../utils/TinyMediaCache.mjs').default|null} [cache] - An optional shared memory cache.
+ * @property {'none'|'native'|'script-only'|'controlled'} [animationControl] - How animated images are handled.
+ */
+/**
+ * Reads the ISOBMFF boxes that live between two offsets.
+ * @param {Uint8Array} bytes - The full file buffer.
+ * @param {number} start - The offset of the first box.
+ * @param {number} end - The offset after the last box.
+ * @returns {Array<{ type: string, start: number, dataStart: number, dataEnd: number, end: number }>} The parsed box headers.
+ */
+function readIsoBoxes(bytes, start, end) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const result = [];
+    let offset = start;
+    while (offset + 8 <= end) {
+        let size = view.getUint32(offset);
+        const type = String.fromCharCode(bytes[offset + 4], bytes[offset + 5], bytes[offset + 6], bytes[offset + 7]);
+        let headerSize = 8;
+        if (size === 1) {
+            if (offset + 16 > end)
+                break;
+            size = view.getUint32(offset + 8) * 0x100000000 + view.getUint32(offset + 12);
+            headerSize = 16;
+        }
+        else if (size === 0) {
+            size = end - offset;
+        }
+        if (size < headerSize || offset + size > end)
+            break;
+        result.push({
+            type,
+            start: offset,
+            dataStart: offset + headerSize,
+            dataEnd: offset + size,
+            end: offset + size,
+        });
+        offset += size;
+    }
+    return result;
+}
+/**
+ * Concatenates a list of byte arrays into a single buffer.
+ * @param {Uint8Array<ArrayBuffer>[]} chunks - The chunks to join.
+ * @returns {Uint8Array<ArrayBuffer>} The concatenated bytes.
+ */
+function concatBytes(chunks) {
+    let length = 0;
+    for (const chunk of chunks)
+        length += chunk.length;
+    const out = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+/**
+ * Encodes an ASCII string as a byte array.
+ * @param {string} value - The ASCII string.
+ * @returns {Uint8Array<ArrayBuffer>} The encoded bytes.
+ */
+function asciiBytes(value) {
+    const out = new Uint8Array(value.length);
+    for (let i = 0; i < value.length; i += 1)
+        out[i] = value.charCodeAt(i);
+    return out;
+}
+/**
+ * Encodes a big-endian unsigned 16-bit integer.
+ * @param {number} value - The value to encode.
+ * @returns {Uint8Array<ArrayBuffer>} The encoded bytes.
+ */
+function u16be(value) {
+    return new Uint8Array([(value >> 8) & 0xff, value & 0xff]);
+}
+/**
+ * Encodes a big-endian unsigned 32-bit integer.
+ * @param {number} value - The value to encode.
+ * @returns {Uint8Array<ArrayBuffer>} The encoded bytes.
+ */
+function u32be(value) {
+    return new Uint8Array([
+        (value >>> 24) & 0xff,
+        (value >>> 16) & 0xff,
+        (value >>> 8) & 0xff,
+        value & 0xff,
+    ]);
+}
+/**
+ * Serializes an ISOBMFF box from its type and payload chunks.
+ * @param {string} type - The 4-character box type.
+ * @param {...Uint8Array<ArrayBuffer>} chunks - The payload chunks.
+ * @returns {Uint8Array<ArrayBuffer>} The serialized box.
+ */
+function buildIsoBox(type, ...chunks) {
+    const payload = concatBytes(chunks);
+    const out = new Uint8Array(8 + payload.length);
+    out.set(u32be(out.length), 0);
+    out.set(asciiBytes(type), 4);
+    out.set(payload, 8);
+    return out;
+}
+/**
+ * Wraps a raw AV1 sample into a self-contained single-frame AVIF file.
+ * @param {Uint8Array<ArrayBuffer>} av1c - The raw `av1C` configuration box.
+ * @param {number} width - The frame width in pixels.
+ * @param {number} height - The frame height in pixels.
+ * @param {Uint8Array<ArrayBuffer>} frame - The raw AV1 sample payload.
+ * @returns {Uint8Array<ArrayBuffer>} A valid single-frame AVIF file.
+ */
+function buildAvifFrame(av1c, width, height, frame) {
+    const ftyp = buildIsoBox('ftyp', asciiBytes('avif'), u32be(0), asciiBytes('avif'), asciiBytes('mif1'), asciiBytes('miaf'));
+    /** @param {number} dataOffset */
+    const buildMeta = (dataOffset) => {
+        const hdlr = buildIsoBox('hdlr', u32be(0), u32be(0), asciiBytes('pict'), u32be(0), u32be(0), u32be(0), new Uint8Array([0]));
+        const pitm = buildIsoBox('pitm', u32be(0), u16be(1));
+        const iloc = buildIsoBox('iloc', u32be(0), new Uint8Array([0x44, 0x00]), u16be(1), u16be(1), u16be(0), u16be(1), u32be(dataOffset), u32be(frame.length));
+        const infe = buildIsoBox('infe', u32be(0x02000000), u16be(1), u16be(0), asciiBytes('av01'), new Uint8Array([0]));
+        const iinf = buildIsoBox('iinf', u32be(0), u16be(1), infe);
+        const ispe = buildIsoBox('ispe', u32be(0), u32be(width), u32be(height));
+        const ipco = buildIsoBox('ipco', av1c, ispe);
+        const ipma = buildIsoBox('ipma', u32be(0), u32be(1), u16be(1), new Uint8Array([2, 0x81, 0x02]));
+        const iprp = buildIsoBox('iprp', ipco, ipma);
+        return buildIsoBox('meta', u32be(0), hdlr, pitm, iloc, iinf, iprp);
+    };
+    const placeholder = buildMeta(0);
+    const dataOffset = ftyp.length + placeholder.length + 8;
+    const meta = buildMeta(dataOffset);
+    const mdat = buildIsoBox('mdat', frame);
+    return concatBytes([ftyp, meta, mdat]);
+}
+/**
+ * Loads a single image with full lifecycle and animation control.
+ * @extends {TinyMediaLoader<HTMLImageElement>}
+ */
+class TinyImageLoader extends TinyMediaLoader {
+    /**
+     * Retrieves the tag name used to create the underlying element.
+     * @returns {string} The uppercase tag name, always `'IMG'`.
+     */
+    static get tagName() {
+        return 'IMG';
+    }
+    /** @type {HTMLImageElement|null} */
+    #image;
+    /** @type {string|null} */
+    #crossOrigin;
+    /** @type {'sync'|'async'|'auto'} */
+    #decoding;
+    /** @type {boolean} */
+    #stream;
+    // --- Animation Control State ---
+    /** @type {'none'|'native'|'script-only'|'controlled'} */
+    #animationControl;
+    /** @type {AnimationFrame[]} */
+    #frames = [];
+    /** @type {AnimationScriptStep[]} */
+    #animationScript = [];
+    /** @type {boolean} */
+    #isFrozen = false;
+    /** @type {boolean} */
+    #isPlaying = true;
+    /** @type {number} */
+    #playbackRate = 1.0;
+    /** @type {number} */
+    #currentFrameIndex = 0;
+    /** @type {ReturnType<typeof setTimeout>|null} */
+    #playbackTimer = null;
+    /** @type {string|null} */
+    #originalAnimatedUrl = null;
+    /** @type {TinyMediaCache|null} */
+    #frameCache = null;
+    /**
+     * Creates a new image loader and validates the provided options.
+     * @param {ImageLoaderOptions} [options] - The loader configuration.
+     * @throws {TypeError} If `crossOrigin` is not a string or null.
+     * @throws {TypeError} If `decoding` is not a string.
+     */
+    constructor(options = {}) {
+        if (options === null || typeof options !== 'object') {
+            throw new TypeError('The "options" argument must be an object.');
+        }
+        if (options.element !== null &&
+            options.element !== undefined &&
+            !(options.element instanceof HTMLImageElement)) {
+            throw new TypeError('The "element" option must be an HTMLImageElement or null.');
+        }
+        super({ useHeadRequest: false, ...options });
+        if (!options.cache)
+            this.#frameCache = new TinyMediaCache({ strategy: TinyMediaCache.Strategy.MANUAL });
+        const ANIMATION_MODES = ['none', 'native', 'script-only', 'controlled'];
+        const DECODING_MODES = ['sync', 'async', 'auto'];
+        const CROSS_ORIGIN = [null, 'anonymous', 'use-credentials'];
+        const { crossOrigin = null, decoding = 'async', stream = false, animationControl = 'none', } = options;
+        if (!ANIMATION_MODES.includes(animationControl)) {
+            throw new RangeError(`The "animationControl" option must be one of: ${ANIMATION_MODES.join(', ')}.`);
+        }
+        if (!DECODING_MODES.includes(decoding)) {
+            throw new RangeError(`The "decoding" option must be one of: ${DECODING_MODES.join(', ')}.`);
+        }
+        if (!CROSS_ORIGIN.includes(crossOrigin)) {
+            throw new RangeError('The "crossOrigin" option must be "anonymous", "use-credentials" or null.');
+        }
+        this.#crossOrigin = crossOrigin;
+        this.#decoding = decoding;
+        this.#image = null;
+        this.#animationControl = animationControl;
+        // To extract blobs and scripts, we MUST stream the bytes.
+        this.#stream = this.#animationControl !== 'none' ? true : Boolean(stream);
+        this._insertDecoder('image', (mime) => {
+            const probe = new TinyImageProbe(mime);
+            return {
+                write: (chunk) => {
+                    const size = probe.push(chunk);
+                    if (size)
+                        this._emitMetadata(size, 'PROBE');
+                },
+                close: () => {
+                    // When the download/stream ends, we call finalize()
+                    // to collect all accumulated animation metadata.
+                    const animationData = probe.finalize();
+                    // Emits advanced information (frames, loopCount, duration)
+                    if (animationData)
+                        this._emitMetadata(animationData, 'PROBE_ANIMATION');
+                    probe.close();
+                },
+            };
+        });
+    }
+    /**
+     * The underlying `<img>` element.
+     * @returns {HTMLImageElement|null} The current image element, or `null` before the load starts.
+     */
+    get image() {
+        return this.#image;
+    }
+    /**
+     * Indicates whether the image is downloaded through fetch for byte-level progress.
+     * @returns {boolean} `true` when streaming is enabled, otherwise `false`.
+     */
+    get stream() {
+        return this.#stream;
+    }
+    /**
+     * The intrinsic width of the image in pixels.
+     * @returns {number} The intrinsic width in pixels.
+     */
+    get naturalWidth() {
+        return this.#image?.naturalWidth ?? 0;
+    }
+    /**
+     * The intrinsic height of the image in pixels.
+     * @returns {number} The intrinsic height in pixels.
+     */
+    get naturalHeight() {
+        return this.#image?.naturalHeight ?? 0;
+    }
+    /**
+     * The aspect ratio of the image (width / height).
+     * @returns {number} The width divided by the height, or 0 when unknown.
+     */
+    get aspectRatio() {
+        const height = this.naturalHeight;
+        return height === 0 ? 0 : this.naturalWidth / height;
+    }
+    // --- Advanced Animation API ---
+    /**
+     * Freezes the animation. In native mode, falls back to the static 1st frame blob.
+     * @param {number|null} [frameIndex] - Frame index to freeze on (controlled mode only).
+     */
+    freeze(frameIndex = null) {
+        if (frameIndex !== null && (!Number.isInteger(frameIndex) || frameIndex < 0)) {
+            throw new RangeError('The "frameIndex" argument must be a non-negative integer or null.');
+        }
+        if (this.#animationControl === 'none' || this.#animationControl === 'script-only')
+            return;
+        this.#isFrozen = true;
+        if (this.#animationControl === 'native' && this.#frames.length > 0) {
+            const url = this.#frames[0].url;
+            if (this.#image) {
+                this._setInternalSrc(url);
+                this.#image.src = url;
+            }
+        }
+        else if (this.#animationControl === 'controlled') {
+            this.pause();
+            if (frameIndex !== null && frameIndex >= 0 && frameIndex < this.#frames.length) {
+                this.#currentFrameIndex = frameIndex;
+            }
+            if (this.#image && this.#frames[this.#currentFrameIndex]) {
+                const url = this.#frames[this.#currentFrameIndex].url;
+                this._setInternalSrc(url);
+                this.#image.src = url;
+            }
+        }
+    }
+    /**
+     * Unfreezes and resumes the animation.
+     */
+    unfreeze() {
+        if (this.#animationControl === 'none' || this.#animationControl === 'script-only')
+            return;
+        this.#isFrozen = false;
+        if (this.#animationControl === 'native') {
+            if (this.#image && this.#originalAnimatedUrl) {
+                this._setInternalSrc(this.#originalAnimatedUrl);
+                this.#image.src = this.#originalAnimatedUrl;
+            }
+        }
+        else if (this.#animationControl === 'controlled') {
+            this.play();
+        }
+    }
+    /**
+     * Plays the animation (controlled mode only).
+     */
+    play() {
+        if (this.#animationControl !== 'controlled')
+            return;
+        if (this.#playbackTimer)
+            return;
+        this.#isPlaying = true;
+        this.#isFrozen = false;
+        this.#playLoop();
+    }
+    /**
+     * Pauses the animation (controlled mode only).
+     */
+    pause() {
+        if (this.#animationControl !== 'controlled')
+            return;
+        this.#isPlaying = false;
+        if (this.#playbackTimer) {
+            clearTimeout(this.#playbackTimer);
+            this.#playbackTimer = null;
+        }
+    }
+    /**
+     * Gets or sets the playback speed modifier.
+     * @type {number}
+     */
+    get playbackRate() {
+        return this.#playbackRate;
+    }
+    set playbackRate(value) {
+        if (this.#animationControl !== 'controlled')
+            return;
+        this.#playbackRate = Math.max(0.1, Number(value) || 1);
+    }
+    /**
+     * Gets a deep copy of the current animation script or replaces it to modify behavior.
+     * @type {AnimationScriptStep[]}
+     */
+    get animationScript() {
+        return JSON.parse(JSON.stringify(this.#animationScript));
+    }
+    /**
+     * Replaces the animation script.
+     * @param {AnimationScriptStep[]} script - The new script.
+     * @throws {TypeError} If `script` is not an array of `{ delay: number }`.
+     * @throws {Error} If the loader is not in controlled mode.
+     */
+    set animationScript(script) {
+        if (this.#animationControl !== 'controlled') {
+            throw new Error('Animation script editing is only available in controlled mode.');
+        }
+        if (!Array.isArray(script)) {
+            throw new TypeError('The "script" value must be an array.');
+        }
+        this.#animationScript = Array.isArray(script) ? script : [];
+    }
+    // --- Core Lifecycle ---
+    /**
+     * Resolves the target element, wires the load listeners and decodes the image.
+     * @protected
+     * @returns {Promise<void>} A promise that resolves once the image is decoded and ready.
+     */
+    async _startLoad() {
+        // Frames, script and playback cursor are scoped to a single load. Releasing
+        // them here guarantees that a reload never mixes the frames of two images
+        // and that the frame cache keys stay stable across loads.
+        this._releaseAnimationFrames();
+        const image = /** @type {HTMLImageElement} */ (this._resolveElement());
+        this.#image = image;
+        if (this.#crossOrigin)
+            image.crossOrigin = this.#crossOrigin;
+        image.decoding = this.#decoding;
+        image.removeAttribute('src');
+        this._flushMutations();
+        let ready;
+        if (this.#stream) {
+            ready = await this.#streamInto(image);
+        }
+        else {
+            ready = this._waitForMedia(image, 'load');
+            image.src = this.src;
+            this._flushMutations();
+        }
+        await ready;
+        if (typeof image.decode === 'function') {
+            try {
+                await image.decode();
+            }
+            catch {
+                // A decode failure is non-fatal: the image is still renderable.
+            }
+        }
+    }
+    /**
+     * Builds the cache key that identifies a single frame of the current source.
+     * The index is the position of the frame in the source animation, never the
+     * current length of the frame array, so the key stays stable across loads.
+     * @param {number} index - The zero-based frame index.
+     * @returns {string} The cache key of the frame.
+     * @throws {RangeError} If `index` is not a non-negative integer.
+     */
+    #frameKey(index) {
+        if (!Number.isInteger(index) || index < 0) {
+            throw new RangeError('The "index" argument must be a non-negative integer.');
+        }
+        return `${this.src}:::frame=${index}`;
+    }
+    /**
+     * Returns the URL of a cached frame, or null when the frame was never sliced.
+     * @param {number} index - The zero-based frame index.
+     * @returns {string|null} The cached object URL.
+     * @throws {RangeError} If `index` is not a non-negative integer.
+     * @throws {Error} If no cache is available.
+     */
+    #getFrame(index) {
+        if (!Number.isInteger(index) || index < 0) {
+            throw new RangeError('The "index" argument must be a non-negative integer.');
+        }
+        const cache = this.cache ?? this.#frameCache;
+        if (!cache)
+            throw new Error('No cache is available to store animation frames.');
+        const entry = cache.get(this.#frameKey(index));
+        if (!entry) {
+            return null;
+        }
+        cache.acquire(this.#frameKey(index));
+        return entry.objectUrl;
+    }
+    /**
+     * Stores a sliced frame and returns its object URL.
+     * @param {number} index - The zero-based frame index.
+     * @param {Blob} blob - The single-frame blob.
+     * @returns {string} The object URL of the stored frame.
+     * @throws {RangeError} If `index` is not a non-negative integer.
+     * @throws {TypeError} If `blob` is not a Blob.
+     */
+    #setFrame(index, blob) {
+        if (!Number.isInteger(index) || index < 0) {
+            throw new RangeError('The "index" argument must be a non-negative integer.');
+        }
+        if (!(blob instanceof Blob)) {
+            throw new TypeError('The "blob" argument must be a Blob.');
+        }
+        const cache = this.cache ?? this.#frameCache;
+        if (!cache)
+            throw new Error('No cache is available to store animation frames.');
+        const key = this.#frameKey(index);
+        const entry = cache.set(key, blob, false, {}, this.src);
+        cache.acquire(key);
+        return entry.objectUrl;
+    }
+    /**
+     * Downloads the image through fetch, emitting byte-level progress.
+     * Updates the image source progressively during the stream.
+     * @param {HTMLImageElement} image - The target image element.
+     * @returns {Promise<Promise<void>>} A promise resolving to the final ready event load listener.
+     * @throws {TypeError} If `image` is not an HTMLImageElement.
+     * @throws {Error} If the network request fails.
+     */
+    async #streamInto(image) {
+        if (!(image instanceof HTMLImageElement)) {
+            throw new TypeError('The "image" argument must be an HTMLImageElement.');
+        }
+        const cached = this._acquireFromCache();
+        if (cached) {
+            this.emit('cachehit', cached);
+            this._setInternalSrc(cached.objectUrl);
+            this.#originalAnimatedUrl = cached.objectUrl;
+            // Se a imagem for animada e o controle não for 'none', precisamos popular this.#frames.
+            // Mesmo que seja 'native', precisamos do primeiro frame para a função freeze().
+            if (this.#animationControl !== 'none' &&
+                cached.metadata?.animation &&
+                this.#frames.length === 0) {
+                // Processamos o buffer da cache. O método #extractGifFrames cuidará de
+                // reutilizar URLs existentes ou adicionar novos frames à cache.
+                await this.#parseAnimationFromBuffer(await cached.blob.arrayBuffer());
+            }
+            if (this.#animationControl === 'controlled') {
+                this.#originalAnimatedUrl = null;
+                this.play();
+                return Promise.resolve();
+            }
+            const ready = this._waitForMedia(image, 'load');
+            image.src = cached.objectUrl;
+            this._flushMutations();
+            return ready;
+        }
+        let lastUpdate = performance.now();
+        /** @type {string|null} */
+        let previousUrl = null;
+        try {
+            const blob = await this._downloadStream(this.src, (_, chunks) => {
+                if (this.progressive && this.#animationControl !== 'controlled') {
+                    const now = performance.now();
+                    // Update visual image every 500ms to avoid thrashing CPU
+                    if (now - lastUpdate > 500) {
+                        lastUpdate = now;
+                        const currentBlob = new Blob(chunks, { type: this.metadata.type || 'image/jpeg' });
+                        const tempUrl = URL.createObjectURL(currentBlob);
+                        if (previousUrl)
+                            URL.revokeObjectURL(previousUrl);
+                        previousUrl = tempUrl;
+                        // Explicitly marks the temporary URL as internal so the MutationObserver
+                        // ignores it and keeps the original source URL for the cache engine.
+                        this._setInternalSrc(tempUrl);
+                        image.src = tempUrl;
+                        this._flushMutations();
+                    }
+                }
+            });
+            // Extração de script e frames usando arrayBuffer sem utilizar a tag Canvas
+            if (this.#animationControl !== 'none' && this.metadata.animation) {
+                await this.#parseAnimationFromBuffer(await blob.arrayBuffer());
+            }
+            const url = this.mirrored ? this.#adoptSharedBlob(blob) : this._cacheBlob(blob);
+            this._setInternalSrc(url);
+            if (this.#animationControl === 'controlled') {
+                this.#originalAnimatedUrl = null;
+                this.play();
+                return Promise.resolve(); // Fake load ready, control loop assumes rendering
+            }
+            this.#originalAnimatedUrl = url;
+            const ready = this._waitForMedia(image, 'load');
+            image.src = url;
+            this._flushMutations();
+            return ready;
+        }
+        finally {
+            if (previousUrl)
+                URL.revokeObjectURL(previousUrl);
+        }
+    }
+    // --- Animation Binary Slicer (Canvas-Free) ---
+    /**
+     * Slices the animation frames out of a fully downloaded buffer.
+     * @param {ArrayBuffer} arrayBuffer - The full file bytes.
+     * @returns {Promise<void>} Resolves once the frames are sliced.
+     * @throws {TypeError} If `arrayBuffer` is not an ArrayBuffer.
+     */
+    async #parseAnimationFromBuffer(arrayBuffer) {
+        if (!(arrayBuffer instanceof ArrayBuffer)) {
+            throw new TypeError('The "arrayBuffer" argument must be an ArrayBuffer.');
+        }
+        const bytes = new Uint8Array(arrayBuffer);
+        if (bytes.length < 12)
+            return;
+        if (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46) {
+            this.#extractGifFrames(bytes);
+        }
+        else if (bytes[0] === 0x52 &&
+            bytes[1] === 0x49 &&
+            bytes[2] === 0x46 &&
+            bytes[3] === 0x46 &&
+            bytes[8] === 0x57 &&
+            bytes[9] === 0x45 &&
+            bytes[10] === 0x42 &&
+            bytes[11] === 0x50) {
+            this.#extractWebpFrames(bytes);
+        }
+        else if (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) {
+            this.#extractApngFrames(bytes);
+        }
+        else if (bytes[4] === 0x66 && bytes[5] === 0x74 && bytes[6] === 0x79 && bytes[7] === 0x70) {
+            this.#extractAvifFrames(bytes);
+        }
+    }
+    /**
+     * Calculates the CRC-32 checksum for a given byte array.
+     * @param {Uint8Array} bytes - The bytes to checksum.
+     * @returns {number} The unsigned 32-bit checksum.
+     * @throws {TypeError} If `bytes` is not a Uint8Array.
+     */
+    #crc32(bytes) {
+        if (!(bytes instanceof Uint8Array)) {
+            throw new TypeError('The "bytes" argument must be a Uint8Array.');
+        }
+        let c = 0xffffffff;
+        for (let i = 0; i < bytes.length; i++) {
+            c ^= bytes[i];
+            for (let j = 0; j < 8; j++) {
+                c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+            }
+        }
+        return (c ^ 0xffffffff) >>> 0;
+    }
+    /**
+     * Slices an AVIF binary into multiple valid single-frame AVIF blobs.
+     * @param {Uint8Array<ArrayBuffer>} bytes - The full AVIF file.
+     * @returns {void}
+     * @throws {TypeError} If `bytes` is not a Uint8Array.
+     */
+    #extractAvifFrames(bytes) {
+        if (!(bytes instanceof Uint8Array)) {
+            throw new TypeError('The "bytes" argument must be a Uint8Array.');
+        }
+        const top = readIsoBoxes(bytes, 0, bytes.length);
+        const moov = top.find((box) => box.type === 'moov');
+        if (!moov)
+            return;
+        const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        const traks = readIsoBoxes(bytes, moov.dataStart, moov.dataEnd).filter((box) => box.type === 'trak');
+        /** @type {{ stbl: { dataStart: number, dataEnd: number }, timescale: number }|null} */
+        let track = null;
+        for (const trak of traks) {
+            const mdia = readIsoBoxes(bytes, trak.dataStart, trak.dataEnd).find((b) => b.type === 'mdia');
+            if (!mdia)
+                continue;
+            const minf = readIsoBoxes(bytes, mdia.dataStart, mdia.dataEnd).find((b) => b.type === 'minf');
+            if (!minf)
+                continue;
+            const stbl = readIsoBoxes(bytes, minf.dataStart, minf.dataEnd).find((b) => b.type === 'stbl');
+            if (!stbl)
+                continue;
+            const mdhd = readIsoBoxes(bytes, mdia.dataStart, mdia.dataEnd).find((b) => b.type === 'mdhd');
+            let timescale = 1000;
+            if (mdhd) {
+                const version = bytes[mdhd.dataStart];
+                timescale =
+                    version === 1 ? view.getUint32(mdhd.dataStart + 20) : view.getUint32(mdhd.dataStart + 12);
+            }
+            track = { stbl, timescale };
+            break;
+        }
+        if (!track)
+            return;
+        const children = readIsoBoxes(bytes, track.stbl.dataStart, track.stbl.dataEnd);
+        const stszBox = children.find((b) => b.type === 'stsz');
+        const stcoBox = children.find((b) => b.type === 'stco');
+        const co64Box = children.find((b) => b.type === 'co64');
+        const stscBox = children.find((b) => b.type === 'stsc');
+        const sttsBox = children.find((b) => b.type === 'stts');
+        const stsdBox = children.find((b) => b.type === 'stsd');
+        if (!stszBox || !stscBox || !stsdBox)
+            return;
+        const sampleSizes = [];
+        {
+            const base = stszBox.dataStart + 4;
+            const uniform = view.getUint32(base);
+            const count = view.getUint32(base + 4);
+            for (let i = 0; i < count; i += 1) {
+                sampleSizes.push(uniform > 0 ? uniform : view.getUint32(base + 8 + i * 4));
+            }
+        }
+        const chunkOffsets = [];
+        if (stcoBox) {
+            const count = view.getUint32(stcoBox.dataStart + 4);
+            for (let i = 0; i < count; i += 1) {
+                chunkOffsets.push(view.getUint32(stcoBox.dataStart + 8 + i * 4));
+            }
+        }
+        else if (co64Box) {
+            const count = view.getUint32(co64Box.dataStart + 4);
+            for (let i = 0; i < count; i += 1) {
+                const high = view.getUint32(co64Box.dataStart + 8 + i * 8);
+                const low = view.getUint32(co64Box.dataStart + 12 + i * 8);
+                chunkOffsets.push(high * 0x100000000 + low);
+            }
+        }
+        const stsc = [];
+        {
+            const count = view.getUint32(stscBox.dataStart + 4);
+            for (let i = 0; i < count; i += 1) {
+                const base = stscBox.dataStart + 8 + i * 12;
+                stsc.push({
+                    firstChunk: view.getUint32(base),
+                    samplesPerChunk: view.getUint32(base + 4),
+                });
+            }
+        }
+        const sampleDurations = [];
+        if (sttsBox) {
+            const count = view.getUint32(sttsBox.dataStart + 4);
+            for (let i = 0; i < count; i += 1) {
+                const base = sttsBox.dataStart + 8 + i * 8;
+                const entryCount = view.getUint32(base);
+                const delta = view.getUint32(base + 4);
+                for (let j = 0; j < entryCount; j += 1)
+                    sampleDurations.push(delta);
+            }
+        }
+        const sampleOffsets = [];
+        {
+            let sampleIndex = 0;
+            for (let i = 0; i < stsc.length; i += 1) {
+                const { firstChunk, samplesPerChunk } = stsc[i];
+                const lastChunk = i + 1 < stsc.length ? stsc[i + 1].firstChunk - 1 : chunkOffsets.length;
+                for (let chunk = firstChunk; chunk <= lastChunk; chunk += 1) {
+                    let offset = chunkOffsets[chunk - 1] ?? 0;
+                    for (let s = 0; s < samplesPerChunk; s += 1) {
+                        sampleOffsets.push(offset);
+                        offset += sampleSizes[sampleIndex] ?? 0;
+                        sampleIndex += 1;
+                    }
+                }
+            }
+        }
+        const entries = readIsoBoxes(bytes, stsdBox.dataStart + 8, stsdBox.dataEnd);
+        const sampleEntry = entries[0];
+        if (!sampleEntry)
+            return;
+        const width = view.getUint16(sampleEntry.dataStart + 24);
+        const height = view.getUint16(sampleEntry.dataStart + 26);
+        const entryChildren = readIsoBoxes(bytes, sampleEntry.dataStart + 78, sampleEntry.dataEnd);
+        const av1cBox = entryChildren.find((b) => b.type === 'av1C');
+        if (!av1cBox)
+            return;
+        /** @type {Uint8Array<ArrayBuffer>} */
+        const av1c = bytes.subarray(av1cBox.start, av1cBox.end);
+        const frameCount = Math.min(sampleSizes.length, sampleOffsets.length);
+        for (let i = 0; i < frameCount; i += 1) {
+            const size = sampleSizes[i];
+            const offset = sampleOffsets[i];
+            const duration = sampleDurations[i] ?? 0;
+            let delay = track.timescale > 0 ? Math.round((duration / track.timescale) * 1000) : 100;
+            if (delay <= 10)
+                delay = 100;
+            this.#animationScript.push({ delay });
+            if (this.#animationControl !== 'script-only') {
+                let url = this.#getFrame(i);
+                if (!url) {
+                    /** @type {Uint8Array<ArrayBuffer>} */
+                    const frameData = bytes.subarray(offset, offset + size);
+                    const file = buildAvifFrame(av1c, width, height, frameData);
+                    const blob = new Blob([file], { type: 'image/avif' });
+                    url = this.#setFrame(i, blob);
+                }
+                this.#frames.push({ url, cacheKey: this.#frameKey(i) });
+            }
+            if (this.#animationControl === 'native')
+                break;
+        }
+    }
+    /**
+     * Slices a WebP binary into multiple valid single-frame WebP blobs.
+     * @param {Uint8Array<ArrayBuffer>} bytes - The full WebP file.
+     * @returns {void}
+     * @throws {TypeError} If `bytes` is not a Uint8Array.
+     */
+    #extractWebpFrames(bytes) {
+        if (!(bytes instanceof Uint8Array)) {
+            throw new TypeError('The "bytes" argument must be a Uint8Array.');
+        }
+        if (bytes.length < 12)
+            return;
+        let offset = 12;
+        let vp8x = null;
+        let anim = null;
+        const preDataChunks = [];
+        const frames = [];
+        while (offset + 8 <= bytes.length) {
+            const view = new DataView(bytes.buffer, bytes.byteOffset + offset, 8);
+            const fourcc = String.fromCharCode(bytes[offset], bytes[offset + 1], bytes[offset + 2], bytes[offset + 3]);
+            const size = view.getUint32(4, true);
+            const payloadEnd = offset + 8 + size + (size % 2);
+            if (payloadEnd > bytes.length)
+                break;
+            const chunkBytes = bytes.subarray(offset, payloadEnd);
+            if (fourcc === 'VP8X') {
+                vp8x = chunkBytes;
+            }
+            else if (fourcc === 'ANIM') {
+                anim = chunkBytes;
+            }
+            else if (fourcc === 'ANMF') {
+                const payload = offset + 8;
+                const dur = bytes[payload + 12] | (bytes[payload + 13] << 8) | (bytes[payload + 14] << 16);
+                frames.push({ chunk: chunkBytes, delay: dur });
+            }
+            else {
+                if (!frames.length && fourcc !== 'VP8 ' && fourcc !== 'VP8L') {
+                    preDataChunks.push(chunkBytes);
+                }
+            }
+            offset = payloadEnd;
+        }
+        if (frames.length === 0)
+            return;
+        for (let i = 0; i < frames.length; i++) {
+            const frame = frames[i];
+            let delay = frame.delay;
+            if (delay <= 10)
+                delay = 100;
+            this.#animationScript.push({ delay });
+            if (this.#animationControl !== 'script-only') {
+                let url = this.#getFrame(i);
+                if (!url) {
+                    /** @type {Uint8Array<ArrayBuffer>[]} */
+                    const outChunks = [];
+                    if (vp8x)
+                        outChunks.push(vp8x);
+                    if (anim)
+                        outChunks.push(anim);
+                    for (const chunk of preDataChunks)
+                        outChunks.push(chunk);
+                    outChunks.push(frame.chunk);
+                    let totalPayloadSize = 4;
+                    for (const c of outChunks)
+                        totalPayloadSize += c.length;
+                    const riffHeader = new Uint8Array(12);
+                    const riffView = new DataView(riffHeader.buffer);
+                    riffHeader.set([0x52, 0x49, 0x46, 0x46], 0);
+                    riffView.setUint32(4, totalPayloadSize, true);
+                    riffHeader.set([0x57, 0x45, 0x42, 0x50], 8);
+                    const blob = new Blob([riffHeader, ...outChunks], { type: 'image/webp' });
+                    url = this.#setFrame(i, blob);
+                }
+                this.#frames.push({ url, cacheKey: this.#frameKey(i) });
+            }
+            if (this.#animationControl === 'native')
+                break;
+        }
+    }
+    /**
+     * Slices an APNG binary into multiple valid single-frame SVG blobs.
+     *
+     * APNG frames are deltas: a frame may cover only the sub-rectangle that
+     * changed, and `blend_op` / `dispose_op` decide how the frame interacts with
+     * the accumulated canvas. The SVG produced for frame `i` therefore replays
+     * every draw and every erase that happened up to `i`, which reproduces the
+     * exact pixels of the original APNG without a canvas element.
+     *
+     * @param {Uint8Array<ArrayBuffer>} bytes - The full APNG file.
+     * @returns {void}
+     * @throws {TypeError} If `bytes` is not a Uint8Array.
+     */
+    #extractApngFrames(bytes) {
+        if (!(bytes instanceof Uint8Array)) {
+            throw new TypeError('The "bytes" argument must be a Uint8Array.');
+        }
+        const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+        const IEND_BYTES = new Uint8Array([
+            0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4e, 0x44, 0xae, 0x42, 0x60, 0x82,
+        ]);
+        if (bytes.length < 8)
+            return;
+        /**
+         * @typedef {Object} ApngFrame
+         * @property {number} delay - Frame duration in milliseconds.
+         * @property {{ type: string, bytes: Uint8Array<ArrayBuffer> }[]} dataChunks - IDAT/fdAT chunks.
+         * @property {number} width - Frame width in pixels.
+         * @property {number} height - Frame height in pixels.
+         * @property {number} x - Frame X offset inside the canvas.
+         * @property {number} y - Frame Y offset inside the canvas.
+         * @property {number} disposeOp - 0 = NONE, 1 = BACKGROUND, 2 = PREVIOUS.
+         * @property {number} blendOp - 0 = SOURCE, 1 = OVER.
+         */
+        /** @type {ApngFrame[]} */
+        const frames = [];
+        /** @type {Uint8Array<ArrayBuffer>[]} */
+        const preDataChunks = [];
+        let iend = null;
+        let fullWidth = 0;
+        let fullHeight = 0;
+        let offset = 8;
+        let seenIdatOrFctl = false;
+        /** @type {ApngFrame|null} */
+        let currentFrame = null;
+        while (offset + 8 <= bytes.length) {
+            const view = new DataView(bytes.buffer, bytes.byteOffset + offset, 8);
+            const size = view.getUint32(0);
+            const type = String.fromCharCode(bytes[offset + 4], bytes[offset + 5], bytes[offset + 6], bytes[offset + 7]);
+            const chunkEnd = offset + 12 + size;
+            if (chunkEnd > bytes.length)
+                break;
+            const chunkBytes = bytes.subarray(offset, chunkEnd);
+            if (type === 'IHDR') {
+                const ihdrView = new DataView(chunkBytes.buffer, chunkBytes.byteOffset, chunkBytes.byteLength);
+                fullWidth = ihdrView.getUint32(8);
+                fullHeight = ihdrView.getUint32(12);
+                preDataChunks.push(chunkBytes);
+            }
+            else if (type === 'acTL') {
+                // The original animation controller is replaced by the frame script.
+            }
+            else if (type === 'fcTL') {
+                seenIdatOrFctl = true;
+                if (currentFrame)
+                    frames.push(currentFrame);
+                currentFrame = null;
+                if (size >= 26) {
+                    const fcTLView = new DataView(bytes.buffer, bytes.byteOffset + offset + 8, 26);
+                    const delayNum = fcTLView.getUint16(20);
+                    const delayDen = fcTLView.getUint16(22) || 100;
+                    currentFrame = {
+                        delay: delayDen === 0 ? 100 : Math.round((delayNum / delayDen) * 1000),
+                        dataChunks: [],
+                        width: fcTLView.getUint32(4),
+                        height: fcTLView.getUint32(8),
+                        x: fcTLView.getUint32(12),
+                        y: fcTLView.getUint32(16),
+                        disposeOp: fcTLView.getUint8(24),
+                        blendOp: fcTLView.getUint8(25),
+                    };
+                }
+            }
+            else if (type === 'IDAT') {
+                seenIdatOrFctl = true;
+                if (currentFrame)
+                    currentFrame.dataChunks.push({ type: 'IDAT', bytes: chunkBytes });
+            }
+            else if (type === 'fdAT') {
+                seenIdatOrFctl = true;
+                if (currentFrame)
+                    currentFrame.dataChunks.push({ type: 'fdAT', bytes: chunkBytes });
+            }
+            else if (type === 'IEND') {
+                iend = chunkBytes;
+                break;
+            }
+            else if (!seenIdatOrFctl) {
+                preDataChunks.push(chunkBytes);
+            }
+            offset = chunkEnd;
+        }
+        if (currentFrame)
+            frames.push(currentFrame);
+        if (frames.length === 0)
+            return;
+        /**
+         * Builds the base64 PNG of a single APNG frame.
+         * @param {ApngFrame} frame - The frame to encode.
+         * @returns {string} The base64-encoded PNG.
+         */
+        const buildFramePng = (frame) => {
+            const patchedPreData = preDataChunks.map((chunk) => {
+                const chunkType = String.fromCharCode(chunk[4], chunk[5], chunk[6], chunk[7]);
+                if (chunkType !== 'IHDR')
+                    return chunk;
+                const newIhdr = new Uint8Array(chunk);
+                const view = new DataView(newIhdr.buffer, newIhdr.byteOffset, newIhdr.byteLength);
+                view.setUint32(8, frame.width);
+                view.setUint32(12, frame.height);
+                view.setUint32(newIhdr.length - 4, this.#crc32(newIhdr.subarray(4, newIhdr.length - 4)));
+                return newIhdr;
+            });
+            const outChunks = [new Uint8Array(PNG_SIGNATURE), ...patchedPreData];
+            for (const chunk of frame.dataChunks) {
+                if (chunk.type === 'IDAT') {
+                    outChunks.push(chunk.bytes);
+                }
+                else if (chunk.type === 'fdAT') {
+                    const idatChunk = new Uint8Array(chunk.bytes.length - 4);
+                    const idatView = new DataView(idatChunk.buffer);
+                    idatView.setUint32(0, chunk.bytes.length - 16);
+                    idatChunk.set([0x49, 0x44, 0x41, 0x54], 4);
+                    idatChunk.set(chunk.bytes.subarray(12, chunk.bytes.length - 4), 8);
+                    idatView.setUint32(idatChunk.length - 4, this.#crc32(idatChunk.subarray(4, idatChunk.length - 4)));
+                    outChunks.push(idatChunk);
+                }
+            }
+            outChunks.push(iend ?? IEND_BYTES);
+            let totalSize = 0;
+            for (const c of outChunks)
+                totalSize += c.length;
+            const pngBuffer = new Uint8Array(totalSize);
+            let bufOffset = 0;
+            for (const c of outChunks) {
+                pngBuffer.set(c, bufOffset);
+                bufOffset += c.length;
+            }
+            let binary = '';
+            for (let j = 0; j < pngBuffer.length; j += 1) {
+                binary += String.fromCharCode(pngBuffer[j]);
+            }
+            return btoa(binary);
+        };
+        /** @type {Map<number, string>} */
+        const pngCache = new Map();
+        /**
+         * Returns the base64 PNG of a frame, encoding it only once.
+         * @param {number} index - The zero-based frame index.
+         * @returns {string} The base64-encoded PNG.
+         */
+        const getFramePng = (index) => {
+            let png = pngCache.get(index);
+            if (png === undefined) {
+                png = buildFramePng(frames[index]);
+                pngCache.set(index, png);
+            }
+            return png;
+        };
+        const canvasWidth = fullWidth || 1;
+        const canvasHeight = fullHeight || 1;
+        /** @type {string[]} */
+        const defs = [];
+        let maskSeq = 0;
+        /**
+         * Wraps `content` so the given rectangle becomes fully transparent.
+         * @param {string} content - The SVG markup to erase from.
+         * @param {number} x - Rectangle X offset.
+         * @param {number} y - Rectangle Y offset.
+         * @param {number} width - Rectangle width.
+         * @param {number} height - Rectangle height.
+         * @returns {string} The masked SVG markup.
+         */
+        const eraseRect = (content, x, y, width, height) => {
+            if (content === '')
+                return '';
+            if (width >= canvasWidth && height >= canvasHeight)
+                return '';
+            if (width <= 0 || height <= 0)
+                return content;
+            const id = `apng-mask-${maskSeq}`;
+            maskSeq += 1;
+            defs.push(`<mask id="${id}" maskUnits="userSpaceOnUse" x="0" y="0" width="${canvasWidth}" height="${canvasHeight}">` +
+                `<rect x="0" y="0" width="${canvasWidth}" height="${canvasHeight}" fill="#fff"/>` +
+                `<rect x="${x}" y="${y}" width="${width}" height="${height}" fill="#000"/>` +
+                `</mask>`);
+            return `<g mask="url(#${id})">${content}</g>`;
+        };
+        let state = '';
+        for (let i = 0; i < frames.length; i += 1) {
+            const frame = frames[i];
+            const stateBefore = state;
+            const imageTag = `<image href="data:image/png;base64,${getFramePng(i)}"` +
+                ` x="${frame.x}" y="${frame.y}" width="${frame.width}" height="${frame.height}"/>`;
+            // blend_op: 0 = SOURCE (replace the rect), 1 = OVER (alpha composite).
+            const drawn = frame.blendOp === 0
+                ? eraseRect(state, frame.x, frame.y, frame.width, frame.height) + imageTag
+                : state + imageTag;
+            let delay = frame.delay;
+            if (delay <= 10)
+                delay = 100;
+            this.#animationScript.push({ delay });
+            if (this.#animationControl !== 'script-only') {
+                let url = this.#getFrame(i);
+                if (!url) {
+                    const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${canvasWidth}" height="${canvasHeight}"` +
+                        ` viewBox="0 0 ${canvasWidth} ${canvasHeight}">` +
+                        (defs.length > 0 ? `<defs>${defs.join('')}</defs>` : '') +
+                        drawn +
+                        `</svg>`;
+                    url = this.#setFrame(i, new Blob([svg], { type: 'image/svg+xml' }));
+                }
+                this.#frames.push({ url, cacheKey: this.#frameKey(i) });
+            }
+            // dispose_op: 0 = NONE, 1 = BACKGROUND (erase), 2 = PREVIOUS (rollback).
+            if (frame.disposeOp === 1) {
+                state = eraseRect(drawn, frame.x, frame.y, frame.width, frame.height);
+            }
+            else if (frame.disposeOp === 2) {
+                state = stateBefore;
+            }
+            else {
+                state = drawn;
+            }
+            if (this.#animationControl === 'native')
+                break;
+        }
+    }
+    /**
+     * Slices a GIF binary into multiple valid single-frame GIF blobs.
+     * @param {Uint8Array<ArrayBuffer>} bytes - The full GIF file.
+     * @returns {void}
+     * @throws {TypeError} If `bytes` is not a Uint8Array.
+     */
+    #extractGifFrames(bytes) {
+        if (!(bytes instanceof Uint8Array)) {
+            throw new TypeError('The "bytes" argument must be a Uint8Array.');
+        }
+        if (bytes.length < 13)
+            return;
+        let offset = 13;
+        const packed = bytes[10];
+        const hasGCT = packed & 0x80;
+        const gctSize = hasGCT ? 3 * (1 << ((packed & 0x07) + 1)) : 0;
+        offset += gctSize;
+        // Cabeçalho global + Paleta de Cores (usado de base para todos os frames)
+        const globalHeader = bytes.subarray(0, offset);
+        let gce = null;
+        let delay = 100;
+        while (offset < bytes.length) {
+            const block = bytes[offset];
+            if (block === 0x3b)
+                break; // Trailer de fim do GIF
+            if (block === 0x21) {
+                const ext = bytes[offset + 1];
+                if (ext === 0xf9) {
+                    // Graphic Control Extension (Possui o Delay)
+                    gce = bytes.subarray(offset, offset + 8);
+                    delay = (bytes[offset + 4] | (bytes[offset + 5] << 8)) * 10;
+                    if (delay <= 10)
+                        delay = 100; // Correção para delays muito rápidos
+                }
+                // Pular blocos de dados
+                offset += 2;
+                while (offset < bytes.length && bytes[offset] !== 0) {
+                    offset += bytes[offset] + 1;
+                }
+                offset++;
+            }
+            else if (block === 0x2c) {
+                // Image Descriptor
+                const imgStart = offset;
+                offset += 10;
+                const localPacked = bytes[offset - 1];
+                if (localPacked & 0x80) {
+                    offset += 3 * (1 << ((localPacked & 0x07) + 1)); // LCT Local
+                }
+                offset++; // LZW Min Code
+                while (offset < bytes.length && bytes[offset] !== 0) {
+                    offset += bytes[offset] + 1;
+                }
+                offset++;
+                const imgEnd = offset;
+                // Registrar o script de tempo
+                this.#animationScript.push({ delay });
+                if (this.#animationControl !== 'script-only') {
+                    const index = this.#frames.length;
+                    let url = this.#getFrame(index);
+                    if (!url) {
+                        const frameBytes = new Uint8Array(globalHeader.length + (gce ? gce.length : 0) + (imgEnd - imgStart) + 1);
+                        frameBytes.set(globalHeader, 0);
+                        let cursor = globalHeader.length;
+                        if (gce) {
+                            frameBytes.set(gce, cursor);
+                            cursor += gce.length;
+                        }
+                        frameBytes.set(bytes.subarray(imgStart, imgEnd), cursor);
+                        frameBytes[frameBytes.length - 1] = 0x3b;
+                        const blob = new Blob([frameBytes], { type: 'image/gif' });
+                        url = this.#setFrame(index, blob);
+                    }
+                    this.#frames.push({ url, cacheKey: this.#frameKey(index) });
+                }
+                // Em modo Nativo, nós só precisamos fatiar o Primeiro frame para a função de freeze
+                if (this.#animationControl === 'native')
+                    break;
+                gce = null;
+            }
+            else {
+                break; // Bloco desconhecido, evita loops
+            }
+        }
+    }
+    /**
+     * Executes the manual animation loop.
+     * @returns {void}
+     */
+    #playLoop() {
+        if (!this.#isPlaying || this.#isFrozen || !this.#image || this.#frames.length === 0) {
+            return;
+        }
+        const frame = this.#frames[this.#currentFrameIndex];
+        if (!frame) {
+            return;
+        }
+        const scriptStep = this.#animationScript[this.#currentFrameIndex];
+        const delay = (scriptStep?.delay || 100) / this.#playbackRate;
+        this._setInternalSrc(frame.url);
+        this.#image.src = frame.url;
+        this._flushMutations();
+        this.#playbackTimer = setTimeout(() => {
+            this.#currentFrameIndex = (this.#currentFrameIndex + 1) % this.#frames.length;
+            this.#playLoop();
+        }, delay);
+    }
+    // --- Overrides ---
+    /**
+     * Builds the metadata descriptor for the loaded image.
+     * @protected
+     * @returns {import('../TinyMediaLoader.mjs').MediaMetadataDetails} The image metadata details.
+     */
+    _getMetadataDetails() {
+        const image = this.#image;
+        const animation = this.metadata.animation;
+        return {
+            type: image?.naturalWidth ? `image/${this.#getExtension()}` : 'image/*',
+            width: image?.naturalWidth ?? 0,
+            height: image?.naturalHeight ?? 0,
+            duration: animation ? animation.duration / 1000 : NaN,
+            size: this._getResourceSize(),
+        };
+    }
+    /**
+     * Aborts the fetch gracefully allowing a retry process to spin up safely on the same element instance without
+     * triggering stale asynchronous cache responses.
+     * @protected
+     * @returns {void}
+     */
+    _abort() {
+        super._abort();
+        if (this.#image) {
+            this.#image.src = EMPTY_GIF;
+            this._flushMutations();
+        }
+    }
+    /**
+     * Releases all acquired animation frames from the cache or revokes their
+     * object URLs. It also stops the playback loop, so a reload never leaves a
+     * timer pointing at a frame that no longer exists.
+     * @protected
+     * @returns {void}
+     */
+    _releaseAnimationFrames() {
+        if (this.#playbackTimer !== null) {
+            clearTimeout(this.#playbackTimer);
+            this.#playbackTimer = null;
+        }
+        for (const frame of this.#frames) {
+            const cache = this.cache ?? this.#frameCache;
+            if (cache) {
+                cache.release(frame.cacheKey);
+            }
+            else {
+                URL.revokeObjectURL(frame.url);
+            }
+        }
+        this.#frames = [];
+        this.#animationScript = [];
+        this.#currentFrameIndex = 0;
+        this.#isFrozen = false;
+        this.#isPlaying = false;
+    }
+    /**
+     * Detaches the load handlers, revokes the object URL and clears the source of the image element.
+     * @protected
+     * @returns {void} This method does not return a value.
+     */
+    _cleanup() {
+        this._revokeObjectUrl();
+        this.pause();
+        this._releaseAnimationFrames();
+        this.#originalAnimatedUrl = null;
+        if (this.#image) {
+            this.#image.onload = null;
+            this.#image.onerror = null;
+            this.#image.removeAttribute('src');
+            this.#image.src = EMPTY_GIF;
+            this._flushMutations();
+        }
+    }
+    /**
+     * Creates the `<img>` element used by the loader.
+     * @protected
+     * @returns {HTMLImageElement} A new, detached image element.
+     */
+    _createElement() {
+        return document.createElement('img');
+    }
+    /**
+     * Resolves the renderable URL for a blob that was shared by a mirrored
+     * download. The leading loader already owns the shared cache entry, so the
+     * mirror only mints a private object URL over the very same in-memory blob.
+     * @param {Blob} blob - The blob produced by the shared download.
+     * @returns {string} The URL the element must render.
+     * @throws {TypeError} If `blob` is not a Blob.
+     */
+    #adoptSharedBlob(blob) {
+        if (!(blob instanceof Blob)) {
+            throw new TypeError('The "blob" argument must be a Blob.');
+        }
+        this._setResourceSize(blob.size);
+        return this._createObjectUrl(blob);
+    }
+    /**
+     * Extracts the lowercase file extension from the image source.
+     * @returns {string} The file extension without a dot, or `'png'` when none is found.
+     */
+    #getExtension() {
+        const clean = this.src.split('?')[0].split('#')[0];
+        const dot = clean.lastIndexOf('.');
+        return dot === -1 ? 'png' : clean.slice(dot + 1).toLowerCase();
+    }
+}
+export default TinyImageLoader;