@pie-players/pie-players-shared 0.3.75 → 1.0.0-beta.0

package/dist/pie/resource-monitor.js

@@ -21,13 +21,30 @@ const DEFAULT_CONFIG = {
     maxRetryDelay: 5000,
     debug: false,
 };
-// Constants
 const MAX_URL_LENGTH = 80;
-const URL_TRUNCATE_LENGTH = 77;
+/** Leaves room for the "..." prefix within MAX_URL_LENGTH. */
+const URL_TRUNCATE_LENGTH = MAX_URL_LENGTH - "...".length;
 const MEDIA_RETRY_RECONCILIATION_TIMEOUT_MS = 1200;
 const MEDIA_RETRY_RECONCILIATION_POLL_MS = 75;
+/** The elements of each initiator type that carry a resource URL. */
+const RESOURCE_SELECTOR_BY_INITIATOR = new Map([
+    ["img", "img[src]"],
+    ["audio", "audio[src]"],
+    ["video", "video[src]"],
+    ["link", "link[href]"],
+    ["source", "source[src]"],
+]);
+/** How a retry reloads each element type, as named in the retry log. */
+const RETRY_STRATEGY_BY_TAG = new Map([
+    ["img", "Cache-busting URL"],
+    ["link", "Cache-busting URL"],
+    ["audio", "element.load()"],
+    ["video", "element.load()"],
+]);
 /**
- * Tracks resource loads and provides retry capability
+ * Tracks the resource loads of one container and retries failed ones with
+ * exponential backoff and cache-busting URLs. The events it dispatches are
+ * listed in the event contract above.
  */
 export class ResourceMonitor {
     config;
@@ -35,13 +52,20 @@ export class ResourceMonitor {
     observer = null;
     mutationObserver = null;
     errorHandler = null;
+    /** Retries scheduled so far, keyed by the URL without retry parameters. */
     retryAttempts = new Map();
+    /** Elements that failed to load each URL; a retry reloads the first one. */
     retryTargets = new Map();
     container = null;
-    isBrowser;
-    containerResources = new Set(); // Track resources within our container
+    isBrowser = typeof window !== "undefined" && typeof document !== "undefined";
+    /** URLs referenced inside the container; timing entries for others are ignored. */
+    containerResources = new Set();
     provider;
     started = false;
+    /**
+     * Bumped on every start and stop, so timers and listeners captured in an
+     * earlier lifecycle see themselves as stale.
+     */
     lifecycleVersion = 0;
     pendingRetryTimers = new Map();
     retryInFlight = new Set();
@@ -76,8 +100,6 @@ export class ResourceMonitor {
         else if (this.provider && this.isDebugEnabled()) {
             this.logger.debug("Skipping provider lifecycle management for injected provider");
         }
-        this.isBrowser =
-            typeof window !== "undefined" && typeof document !== "undefined";
     }
     /**
      * Check if debug logging is enabled (dynamically checks window.PIE_DEBUG)
@@ -219,9 +241,6 @@ export class ResourceMonitor {
         this.started = true;
         this.logger.info("✅ Resource monitoring started");
     }
-    /**
-     * Stop monitoring and clean up
-     */
     stop() {
         if (!this.started)
             return;
@@ -265,8 +284,8 @@ export class ResourceMonitor {
         this.logger.info("Resource monitoring stopped");
     }
     /**
-     * Set up MutationObserver to track DOM changes within container
-     * This allows us to know which resources belong to our container
+     * Tracks resources added to the container, or retargeted inside it, so
+     * timing entries can be attributed to this container.
      */
     setupMutationObserver() {
         if (!this.isBrowser ||
@@ -278,13 +297,11 @@ export class ResourceMonitor {
         try {
             this.mutationObserver = new MutationObserver((mutations) => {
                 for (const mutation of mutations) {
-                    // Check added nodes
                     mutation.addedNodes.forEach((node) => {
                         if (node instanceof HTMLElement) {
                             this.scanElementForResources(node);
                         }
                     });
-                    // Check attribute changes (src, href changes)
                     if (mutation.type === "attributes" &&
                         mutation.target instanceof HTMLElement) {
                         const target = mutation.target;
@@ -300,7 +317,6 @@ export class ResourceMonitor {
                     }
                 }
             });
-            // Observe the container for changes
             this.mutationObserver.observe(this.container, {
                 childList: true,
                 subtree: true,
@@ -317,7 +333,6 @@ export class ResourceMonitor {
      * Scan an element and its descendants for resources
      */
     scanElementForResources(element) {
-        // Check the element itself
         if (this.isResourceElement(element)) {
             const src = this.getResourceSrc(element);
             if (src) {
@@ -327,7 +342,6 @@ export class ResourceMonitor {
                 }
             }
         }
-        // Check descendants
         const resourceSelectors = [
             "img",
             "audio",
@@ -379,11 +393,11 @@ export class ResourceMonitor {
                     }
                 }
             });
-            // Use 'type' (singular) instead of 'entryTypes' (plural) to support buffered option
-            // The buffered flag only works with the newer 'type' parameter
+            // `buffered` replays resources that loaded before the observer
+            // started, and is honored only with the single `type` form.
             this.observer.observe({
                 type: "resource",
-                buffered: true, // Capture resources loaded before observer started
+                buffered: true,
             });
             this.logger.debug("PerformanceObserver set up successfully");
         }
@@ -391,13 +405,8 @@ export class ResourceMonitor {
             this.logger.warn("Failed to set up PerformanceObserver:", error);
         }
     }
-    /**
-     * Handle resource timing entry
-     */
     handleResourceTiming(entry) {
-        // Only track media and image resources that are relevant to PIE content
-        const isRelevant = this.isRelevantResource(entry);
-        if (!isRelevant) {
+        if (!this.isRelevantResource(entry)) {
             if (this.isDebugEnabled() &&
                 (entry.initiatorType === "img" ||
                     entry.initiatorType === "audio" ||
@@ -408,69 +417,17 @@ export class ResourceMonitor {
         }
         const duration = entry.duration;
         const size = entry.transferSize;
-        const url = entry.name;
-        const originalUrl = this.getOriginalUrl(url);
-        // Detect actual failures: responseEnd === 0 means the request didn't complete
-        // Note: transferSize === 0 is NOT a failure indicator (can be cache, CORS, or small resources)
-        // We primarily rely on the error event handler for detecting failures
+        const originalUrl = this.getOriginalUrl(entry.name);
+        // A zero responseEnd means the request never completed. A zero
+        // transferSize does not: cached, cross-origin and tiny responses all
+        // report it. The error listener remains the main failure signal.
         const failed = entry.responseEnd === 0 && entry.duration > 0;
-        // Check if this was a retry that succeeded
         const wasRetried = this.retryAttempts.has(originalUrl);
         const retryCount = this.retryAttempts.get(originalUrl) || 0;
-        // Enhanced debug logging with detailed timing breakdown
-        if (this.isDebugEnabled()) {
-            const shortUrl = this.truncateUrl(url);
-            const sizeKB = (size / 1024).toFixed(2);
-            const status = failed ? "❌ FAILED" : "✅ SUCCESS";
-            // Detailed timing breakdown
-            const timingDetails = {
-                total: `${duration.toFixed(2)}ms`,
-                dns: entry.domainLookupEnd > 0
-                    ? `${(entry.domainLookupEnd - entry.domainLookupStart).toFixed(2)}ms`
-                    : "n/a",
-                tcp: entry.connectEnd > 0
-                    ? `${(entry.connectEnd - entry.connectStart).toFixed(2)}ms`
-                    : "n/a",
-                request: entry.responseStart > 0
-                    ? `${(entry.responseStart - entry.requestStart).toFixed(2)}ms`
-                    : "n/a",
-                response: entry.responseEnd > 0
-                    ? `${(entry.responseEnd - entry.responseStart).toFixed(2)}ms`
-                    : "n/a",
-                size: size > 0 ? `${sizeKB} KB` : "0 KB",
-                type: entry.initiatorType,
-                protocol: entry.nextHopProtocol || "unknown",
-            };
-            // Add retry context if this was retried
-            const retryContext = wasRetried && !failed
-                ? `\n   🔄 Retry Success: Succeeded after ${retryCount} ${retryCount === 1 ? "retry" : "retries"}`
-                : "";
-            this.logger.info(`📊 PIE Resource Load ${status}\n` +
-                `   URL: ${shortUrl}\n` +
-                `   Type: ${timingDetails.type} | Protocol: ${timingDetails.protocol}\n` +
-                `   ⏱️  Total Time: ${timingDetails.total}\n` +
-                `   └─ DNS Lookup: ${timingDetails.dns}\n` +
-                `   └─ TCP Connect: ${timingDetails.tcp}\n` +
-                `   └─ Request Time: ${timingDetails.request}\n` +
-                `   └─ Response Time: ${timingDetails.response}\n` +
-                `   📦 Transfer Size: ${timingDetails.size}${retryContext}`);
-        }
-        else {
-            // Simple logging when debug is off but tracking is on
-            this.logger.debug(`Resource loaded: ${entry.name}`, {
-                duration: `${duration.toFixed(2)}ms`,
-                size: `${size} bytes`,
-                type: entry.initiatorType,
-                failed,
-                wasRetried,
-                retryCount,
-            });
-        }
-        // Handle successful loads
+        this.logResourceTiming(entry, failed, wasRetried, retryCount);
         if (!failed) {
             this.handleSuccessfulLoad(originalUrl, entry, duration, size, retryCount, wasRetried);
         }
-        // Track with instrumentation provider
         this.trackInstrumentationEvent("pie-resource-load", {
             url: entry.name,
             duration: Math.round(duration),
@@ -480,11 +437,58 @@ export class ResourceMonitor {
             wasRetried,
             retryCount,
         });
-        // Track failed loads
         if (failed) {
             this.handleFailedLoad(originalUrl, entry, duration, retryCount, wasRetried);
         }
     }
+    logResourceTiming(entry, failed, wasRetried, retryCount) {
+        const duration = entry.duration;
+        const size = entry.transferSize;
+        if (!this.isDebugEnabled()) {
+            this.logger.debug(`Resource loaded: ${entry.name}`, {
+                duration: `${duration.toFixed(2)}ms`,
+                size: `${size} bytes`,
+                type: entry.initiatorType,
+                failed,
+                wasRetried,
+                retryCount,
+            });
+            return;
+        }
+        const shortUrl = this.truncateUrl(entry.name);
+        const sizeKB = (size / 1024).toFixed(2);
+        const status = failed ? "❌ FAILED" : "✅ SUCCESS";
+        const timingDetails = {
+            total: `${duration.toFixed(2)}ms`,
+            dns: entry.domainLookupEnd > 0
+                ? `${(entry.domainLookupEnd - entry.domainLookupStart).toFixed(2)}ms`
+                : "n/a",
+            tcp: entry.connectEnd > 0
+                ? `${(entry.connectEnd - entry.connectStart).toFixed(2)}ms`
+                : "n/a",
+            request: entry.responseStart > 0
+                ? `${(entry.responseStart - entry.requestStart).toFixed(2)}ms`
+                : "n/a",
+            response: entry.responseEnd > 0
+                ? `${(entry.responseEnd - entry.responseStart).toFixed(2)}ms`
+                : "n/a",
+            size: size > 0 ? `${sizeKB} KB` : "0 KB",
+            type: entry.initiatorType,
+            protocol: entry.nextHopProtocol || "unknown",
+        };
+        const retryContext = wasRetried && !failed
+            ? `\n   🔄 Retry Success: Succeeded after ${retryCount} ${retryCount === 1 ? "retry" : "retries"}`
+            : "";
+        this.logger.info(`📊 PIE Resource Load ${status}\n` +
+            `   URL: ${shortUrl}\n` +
+            `   Type: ${timingDetails.type} | Protocol: ${timingDetails.protocol}\n` +
+            `   ⏱️  Total Time: ${timingDetails.total}\n` +
+            `   └─ DNS Lookup: ${timingDetails.dns}\n` +
+            `   └─ TCP Connect: ${timingDetails.tcp}\n` +
+            `   └─ Request Time: ${timingDetails.request}\n` +
+            `   └─ Response Time: ${timingDetails.response}\n` +
+            `   📦 Transfer Size: ${timingDetails.size}${retryContext}`);
+    }
     isLifecycleActive(version) {
         return this.started && this.lifecycleVersion === version;
     }
@@ -517,9 +521,6 @@ export class ResourceMonitor {
         }
         return null;
     }
-    /**
-     * Handle successful resource load
-     */
     handleSuccessfulLoad(url, entry, duration, size, retryCount, wasRetried) {
         const detail = {
             url,
@@ -620,55 +621,45 @@ export class ResourceMonitor {
         this.clearPendingMediaCheck(url);
         this.clearRetryTracking(url);
     }
+    /**
+     * A retried media fetch that succeeds does not mean the element recovered:
+     * it can still hold an error or no source. Success waits until a media
+     * target reports metadata, checked on `loadedmetadata`/`canplay` and by
+     * polling, and the reconciliation timeout bounds the wait.
+     */
     reconcileMediaRetrySuccess(url, detail) {
         this.clearPendingMediaCheck(url);
         if (this.isMediaRetryRecovered(url)) {
-            this.dispatchEvent("pie-resource-load-success", detail);
-            this.finalizeRetrySuccess(url, detail);
+            this.completeMediaRetry(url, detail);
             return;
         }
         if (this.isDebugEnabled()) {
             this.logger.debug(`⏳ Waiting for media readiness before retry success: ${this.truncateUrl(url)}`);
         }
         const version = this.lifecycleVersion;
+        const isStale = () => !this.isLifecycleActive(version) || !this.retryAttempts.has(url);
         const mediaTargets = this.resolveMediaTargetsForUrl(url);
         const eventHandlers = [];
         const pollTimer = setInterval(() => {
-            if (!this.isLifecycleActive(version)) {
-                this.clearPendingMediaCheck(url);
-                return;
-            }
-            if (!this.retryAttempts.has(url)) {
+            if (isStale()) {
                 this.clearPendingMediaCheck(url);
                 return;
             }
             if (this.isMediaRetryRecovered(url)) {
-                this.dispatchEvent("pie-resource-load-success", detail);
-                this.finalizeRetrySuccess(url, detail);
+                this.completeMediaRetry(url, detail);
             }
         }, MEDIA_RETRY_RECONCILIATION_POLL_MS);
         const timeoutTimer = setTimeout(() => {
-            if (!this.isLifecycleActive(version)) {
-                this.clearPendingMediaCheck(url);
-                return;
-            }
-            if (!this.retryAttempts.has(url)) {
-                this.clearPendingMediaCheck(url);
-                return;
-            }
             this.clearPendingMediaCheck(url);
+            if (isStale())
+                return;
             this.handleMediaRetryReconciliationTimeout(url, detail);
         }, MEDIA_RETRY_RECONCILIATION_TIMEOUT_MS);
         for (const { mediaEl } of mediaTargets) {
             const handler = () => {
-                if (!this.isLifecycleActive(version))
+                if (isStale() || !this.isMediaRetryRecovered(url))
                     return;
-                if (!this.retryAttempts.has(url))
-                    return;
-                if (!this.isMediaRetryRecovered(url))
-                    return;
-                this.dispatchEvent("pie-resource-load-success", detail);
-                this.finalizeRetrySuccess(url, detail);
+                this.completeMediaRetry(url, detail);
             };
             mediaEl.addEventListener("loadedmetadata", handler);
             mediaEl.addEventListener("canplay", handler);
@@ -685,6 +676,10 @@ export class ResourceMonitor {
             },
         });
     }
+    completeMediaRetry(url, detail) {
+        this.dispatchEvent("pie-resource-load-success", detail);
+        this.finalizeRetrySuccess(url, detail);
+    }
     handleMediaRetryReconciliationTimeout(url, detail) {
         const shortUrl = this.truncateUrl(url);
         this.logger.warn(`⚠️  PIE Resource Retry Ready Timeout\n` +
@@ -724,19 +719,14 @@ export class ResourceMonitor {
             mediaEl.dispatchEvent(event);
         }
     }
-    /**
-     * Handle failed resource load
-     */
     handleFailedLoad(url, entry, duration, retryCount, wasRetried) {
         const shortUrl = this.truncateUrl(url);
         if (wasRetried) {
-            // This is a retry that also failed - use warn since we'll retry again
             this.logger.warn(`⚠️  PIE Resource Retry Failed\n` +
                 `   URL: ${shortUrl}\n` +
                 `   Retry Attempt: ${retryCount}\n` +
                 `   Remaining Attempts: ${this.config.maxRetries - retryCount}\n` +
                 `   Status: Will ${retryCount >= this.config.maxRetries ? "give up" : "retry again"}`);
-            // Dispatch retry failure event
             this.dispatchEvent("pie-resource-retry-failed", {
                 url,
                 resourceType: entry.initiatorType,
@@ -747,11 +737,9 @@ export class ResourceMonitor {
             });
         }
         else {
-            // Initial failure - use warn since we'll retry
             this.logger.warn(`⚠️  PIE Resource Initial Load Failed\n` +
                 `   URL: ${shortUrl}\n` +
                 `   Status: Will attempt ${this.config.maxRetries} ${this.config.maxRetries === 1 ? "retry" : "retries"}`);
-            // Dispatch initial failure event
             this.dispatchEvent("pie-resource-load-failed", {
                 url,
                 resourceType: entry.initiatorType,
@@ -761,7 +749,6 @@ export class ResourceMonitor {
                 error: "Initial resource load failed",
             });
         }
-        // Track error with instrumentation provider
         this.trackInstrumentationError(new Error(`Resource load failed: ${entry.name}`), {
             resourceUrl: entry.name,
             resourceType: entry.initiatorType,
@@ -771,109 +758,58 @@ export class ResourceMonitor {
         });
     }
     /**
-     * Check if resource is relevant to our container
-     * Uses container-scoped tracking via MutationObserver
-     * Also retroactively checks if resource belongs to container if not yet tracked
+     * Whether a timing entry belongs to this container. Timing entries carry
+     * absolute URLs, so a suffix match against a tracked URL also counts. The
+     * buffered observer also reports resources that loaded before the scan
+     * tracked them; those are looked up in the container's DOM.
      */
     isRelevantResource(entry) {
         const url = entry.name;
-        // Only track resources that we know are in our container
-        let isInContainer = this.containerResources.has(url);
-        if (!isInContainer) {
-            // Also check if it's a relative URL that might match
-            // (PerformanceResourceTiming gives absolute URLs)
-            for (const containerUrl of this.containerResources) {
-                if (url.endsWith(containerUrl) || containerUrl.endsWith(url)) {
-                    return true;
-                }
-            }
-            // Retroactively check if this resource belongs to our container
-            // This handles the case where resources load before MutationObserver scans
-            // PerformanceObserver can capture resources that loaded before it started (buffered: true)
-            // but if they loaded before MutationObserver scanned, they won't be in containerResources
-            if (this.container) {
-                // Simple check: if resource is a media/image type and we have a container,
-                // check if any element in container has this src/href
-                // This is a fallback for resources that loaded very quickly before scan completed
-                const isInContainer = this.isResourceInContainer(url, entry.initiatorType);
-                if (isInContainer) {
-                    this.containerResources.add(url);
-                    if (this.isDebugEnabled()) {
-                        this.logger.debug(`📌 Retroactively tracked resource: ${this.truncateUrl(url)}`);
-                    }
-                    return true;
-                }
+        if (this.containerResources.has(url))
+            return true;
+        for (const containerUrl of this.containerResources) {
+            if (url.endsWith(containerUrl) || containerUrl.endsWith(url)) {
+                return true;
             }
         }
-        return isInContainer;
+        if (!this.isResourceInContainer(url, entry.initiatorType))
+            return false;
+        this.containerResources.add(url);
+        if (this.isDebugEnabled()) {
+            this.logger.debug(`📌 Retroactively tracked resource: ${this.truncateUrl(url)}`);
+        }
+        return true;
     }
-    /**
-     * Check if a resource URL actually belongs to our container by checking DOM elements
-     * This is a fallback for resources that loaded before MutationObserver scanned
-     */
     isResourceInContainer(url, initiatorType) {
         if (!this.container) {
             return false;
         }
         try {
-            // Check if any element in the container has this URL as src/href
             const urlObj = new URL(url);
             const urlPath = urlObj.pathname + urlObj.search;
-            // For images, audio, video - check src attributes
-            if (initiatorType === "img" ||
-                initiatorType === "audio" ||
-                initiatorType === "video") {
-                const elements = this.container.querySelectorAll(`${initiatorType}[src]`);
-                for (const el of elements) {
-                    const resourceEl = el;
-                    if (resourceEl.src &&
-                        (resourceEl.src === url || resourceEl.src.endsWith(urlPath))) {
-                        return true;
-                    }
-                }
-            }
-            // For link elements (stylesheets) - check href
-            if (initiatorType === "link") {
-                const links = this.container.querySelectorAll("link[href]");
-                for (const link of links) {
-                    const linkEl = link;
-                    if (linkEl.href &&
-                        (linkEl.href === url || linkEl.href.endsWith(urlPath))) {
-                        return true;
-                    }
-                }
-            }
-            // For source elements (inside audio/video) - check src
-            if (initiatorType === "source") {
-                const sources = this.container.querySelectorAll("source[src]");
-                for (const source of sources) {
-                    const sourceEl = source;
-                    if (sourceEl.src &&
-                        (sourceEl.src === url || sourceEl.src.endsWith(urlPath))) {
-                        return true;
-                    }
+            const selector = RESOURCE_SELECTOR_BY_INITIATOR.get(initiatorType);
+            if (!selector)
+                return false;
+            for (const el of this.container.querySelectorAll(selector)) {
+                const src = this.getResourceSrc(el);
+                if (src && (src === url || src.endsWith(urlPath))) {
+                    return true;
                 }
             }
         }
         catch (error) {
-            // If URL parsing fails or querySelector fails, fall back to false
             if (this.isDebugEnabled()) {
                 this.logger.debug(`Error checking if resource is in container: ${error}`);
             }
         }
         return false;
     }
-    /**
-     * Set up error event handler for resource loading failures
-     */
     setupErrorHandler() {
         if (!this.container) {
             return;
         }
-        // Use capturing phase to catch errors before they bubble
         this.errorHandler = (event) => {
             const target = event.target;
-            // Only handle resource elements
             if (!this.isResourceElement(target)) {
                 return;
             }
@@ -882,9 +818,7 @@ export class ResourceMonitor {
             if (!src) {
                 return;
             }
-            // Get the original URL without retry parameters
             const originalSrc = this.getOriginalUrl(src);
-            // Check if we have retries remaining
             const currentRetries = this.retryAttempts.get(originalSrc) || 0;
             const remainingRetries = this.config.maxRetries - currentRetries;
             const willRetry = remainingRetries > 0;
@@ -896,14 +830,12 @@ export class ResourceMonitor {
                 remainingRetries,
                 willRetry,
             });
-            // Enhanced debug logging for errors
-            // Use warn if we'll retry, error if we've exhausted retries
+            const logMethod = willRetry
+                ? this.logger.warn.bind(this.logger)
+                : this.logger.error.bind(this.logger);
+            const icon = willRetry ? "⚠️" : "❌";
             if (this.isDebugEnabled()) {
                 const shortUrl = this.truncateUrl(src);
-                const logMethod = willRetry
-                    ? this.logger.warn.bind(this.logger)
-                    : this.logger.error.bind(this.logger);
-                const icon = willRetry ? "⚠️" : "❌";
                 logMethod(`${icon} PIE Resource Load Error\n` +
                     `   Element: <${tagName}>\n` +
                     `   URL: ${shortUrl}\n` +
@@ -912,21 +844,17 @@ export class ResourceMonitor {
                     `   Action: ${willRetry ? "Will retry with exponential backoff" : "Max retries reached, giving up"}`, diagnostics);
             }
             else {
-                const logMethod = willRetry
-                    ? this.logger.warn.bind(this.logger)
-                    : this.logger.error.bind(this.logger);
-                const icon = willRetry ? "⚠️" : "❌";
                 logMethod(`${icon} Resource error: ${tagName} failed to load ${src}`);
             }
             this.trackInstrumentationEvent("pie-resource-load-error", diagnostics);
-            // Track error with instrumentation provider
             this.trackInstrumentationError(new Error(`Resource load error: ${originalSrc}`), {
                 resourceType: tagName,
                 ...diagnostics,
             });
-            // Attempt retry with original URL
             this.retryResourceLoad(target, originalSrc);
         };
+        // Resource `error` events do not bubble, so only a capturing listener on
+        // the container sees them.
         this.container.addEventListener("error", this.errorHandler, true);
         this.logger.debug("Error handler attached to container");
     }
@@ -970,7 +898,6 @@ export class ResourceMonitor {
         else {
             this.logger.error(`❌ Failed to load resource after ${this.config.maxRetries} retries: ${url}`);
         }
-        // Dispatch permanent failure event
         this.dispatchEvent("pie-resource-load-error", {
             url,
             resourceType,
@@ -978,27 +905,21 @@ export class ResourceMonitor {
             maxRetries: this.config.maxRetries,
             error: `Resource permanently failed after ${this.config.maxRetries} retries`,
         });
-        // Track final failure with instrumentation provider
         this.trackInstrumentationError(new Error(`Resource permanently failed after ${this.config.maxRetries} retries: ${url}`), {
             resourceUrl: url,
             retryCount,
             resourceType,
         });
     }
-    /**
-     * Log retry schedule information
-     */
+    /** Exponential backoff, capped at `maxRetryDelay`. */
+    retryDelay(retryCount) {
+        return Math.min(this.config.initialRetryDelay * 2 ** retryCount, this.config.maxRetryDelay);
+    }
     logRetrySchedule(url, retryCount, delay, elementTag) {
         if (this.isDebugEnabled()) {
             const shortUrl = this.truncateUrl(url);
-            const nextDelay = Math.min(this.config.initialRetryDelay * Math.pow(2, retryCount + 1), this.config.maxRetryDelay);
-            const strategy = elementTag === "img"
-                ? "Cache-busting URL"
-                : elementTag === "audio" || elementTag === "video"
-                    ? "element.load()"
-                    : elementTag === "link"
-                        ? "Cache-busting URL"
-                        : "URL update";
+            const nextDelay = this.retryDelay(retryCount + 1);
+            const strategy = RETRY_STRATEGY_BY_TAG.get(elementTag) ?? "URL update";
             this.logger.info(`🔄 PIE Resource Retry Scheduled\n` +
                 `   URL: ${shortUrl}\n` +
                 `   Attempt: ${retryCount + 1}/${this.config.maxRetries}\n` +
@@ -1011,7 +932,8 @@ export class ResourceMonitor {
         }
     }
     /**
-     * Retry loading a failed resource with exponential backoff
+     * Reloads one element under a cache-busting URL. Media elements also need
+     * `load()`, since changing a `<source>` alone does not restart the fetch.
      */
     performRetryLoadAttempt(element, originalSrc, attemptNumber) {
         try {
@@ -1073,11 +995,15 @@ export class ResourceMonitor {
             else {
                 this.logger.error(`Error during retry for ${originalSrc}:`, error);
             }
-            this.trackInstrumentationError(new Error(`Retry attempt error for resource: ${originalSrc}`), {
-                ...diagnostics,
-            });
+            this.trackInstrumentationError(new Error(`Retry attempt error for resource: ${originalSrc}`), diagnostics);
         }
     }
+    /**
+     * Schedules the next retry of a failed resource with exponential backoff,
+     * or fails it permanently once `maxRetries` is spent. Every failing element
+     * joins the URL's retry targets; concurrent errors for one URL share the
+     * retry already in flight.
+     */
     retryResourceLoad(element, originalSrc) {
         this.getRetryTargets(originalSrc).add(element);
         if (!this.started)
@@ -1093,7 +1019,7 @@ export class ResourceMonitor {
             this.handlePermanentFailure(originalSrc, element.tagName.toLowerCase(), currentRetries);
             return;
         }
-        const delay = Math.min(this.config.initialRetryDelay * Math.pow(2, currentRetries), this.config.maxRetryDelay);
+        const delay = this.retryDelay(currentRetries);
         const attemptNumber = currentRetries + 1;
         this.retryInFlight.add(originalSrc);
         this.retryAttempts.set(originalSrc, attemptNumber);
@@ -1120,19 +1046,14 @@ export class ResourceMonitor {
         }, delay);
         this.pendingRetryTimers.set(originalSrc, timer);
     }
-    /**
-     * Dispatch a custom event from the container
-     */
     dispatchEvent(eventName, detail) {
         if (!this.container) {
-            // Silent return - if container is null, events can't be dispatched
-            // This should only happen if ResourceMonitor wasn't properly initialized
             return;
         }
         const event = new CustomEvent(eventName, {
             detail,
             bubbles: true,
-            composed: true, // Allow crossing shadow DOM boundaries
+            composed: true,
         });
         this.container.dispatchEvent(event);
     }