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

package/dist/pie/resource-monitor.d.ts

@@ -69,7 +69,9 @@ export interface MediaRetryReadyDetail extends ResourceMonitorEventDetail {
     mediaTag: "audio" | "video";
 }
 /**
- * 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 declare class ResourceMonitor {
     private config;
@@ -77,13 +79,20 @@ export declare class ResourceMonitor {
     private observer;
     private mutationObserver;
     private errorHandler;
+    /** Retries scheduled so far, keyed by the URL without retry parameters. */
     private retryAttempts;
+    /** Elements that failed to load each URL; a retry reloads the first one. */
     private retryTargets;
     private container;
-    private isBrowser;
+    private readonly isBrowser;
+    /** URLs referenced inside the container; timing entries for others are ignored. */
     private containerResources;
     private provider;
     private started;
+    /**
+     * Bumped on every start and stop, so timers and listeners captured in an
+     * earlier lifecycle see themselves as stale.
+     */
     private lifecycleVersion;
     private pendingRetryTimers;
     private retryInFlight;
@@ -116,13 +125,10 @@ export declare class ResourceMonitor {
      * Start monitoring resources in the given container
      */
     start(container: HTMLElement): void;
-    /**
-     * Stop monitoring and clean up
-     */
     stop(): void;
     /**
-     * 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.
      */
     private setupMutationObserver;
     /**
@@ -137,45 +143,38 @@ export declare class ResourceMonitor {
      * Set up PerformanceObserver to track resource loading timing
      */
     private setupPerformanceObserver;
-    /**
-     * Handle resource timing entry
-     */
     private handleResourceTiming;
+    private logResourceTiming;
     private isLifecycleActive;
     private clearRetryTracking;
     private clearPendingMediaCheck;
     private getRetryTargets;
     private getPrimaryRetryTarget;
-    /**
-     * Handle successful resource load
-     */
     private handleSuccessfulLoad;
     private resolveMediaTarget;
     private resolveMediaTargetsForUrl;
     private normalizeRetrySuccessResourceType;
     private isMediaRetryRecovered;
     private finalizeRetrySuccess;
+    /**
+     * 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.
+     */
     private reconcileMediaRetrySuccess;
+    private completeMediaRetry;
     private handleMediaRetryReconciliationTimeout;
     private dispatchMediaRetryReady;
-    /**
-     * Handle failed resource load
-     */
     private handleFailedLoad;
     /**
-     * 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.
      */
     private isRelevantResource;
-    /**
-     * 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
-     */
     private isResourceInContainer;
-    /**
-     * Set up error event handler for resource loading failures
-     */
     private setupErrorHandler;
     /**
      * Check if element is a resource element
@@ -189,18 +188,21 @@ export declare class ResourceMonitor {
      * Handle permanent resource failure after all retries exhausted
      */
     private handlePermanentFailure;
-    /**
-     * Log retry schedule information
-     */
+    /** Exponential backoff, capped at `maxRetryDelay`. */
+    private retryDelay;
     private logRetrySchedule;
     /**
-     * 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.
      */
     private performRetryLoadAttempt;
-    private retryResourceLoad;
     /**
-     * Dispatch a custom event from the container
+     * 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.
      */
+    private retryResourceLoad;
     private dispatchEvent;
     /**
      * Get current retry statistics