Display Click to Load placeholders on demand

Historically, the Click to Load placeholders were only drawn once at
the point page load completed. That had two problems:
1. Sometimes placeholders would take too long to display, if the page
   took a long time to load fully.
2. Sometimes placeholders would not be displayed at all, if the
   blocked content was only created after page load had finished.

To fix that, let's display the placeholders when instructed by the
platform using a "displayClickToLoadPlaceholders" update message.

Author: kzar

src/features/click-to-play.js

@@ -20,6 +20,9 @@ let sharedStrings = null
 const entities = []
 const entityData = {}
 
+let readyResolver
+const ready = new Promise(resolve => { readyResolver = resolve })
+
 /*********************************************************
  *  Widget Replacement logic
  *********************************************************/
@@ -364,22 +367,6 @@ class DuckWidget {
     }
 }
 
-/**
- * Initialise the Click to Load feature, once the necessary details have been
- * returned by the platform.
- * @returns {Promise}
- */
-async function initCTL () {
-    await replaceClickToLoadElements()
-
-    window.addEventListener('ddg-ctp-replace-element', ({ target }) => {
-        replaceClickToLoadElements(target)
-    }, { capture: true })
-
-    // Inform surrogate scripts that CTP is ready
-    originalWindowDispatchEvent(createCustomEvent('ddg-ctp-ready'))
-}
-
 function replaceTrackingElement (widget, trackingElement, placeholderElement, hideTrackingElement = false, currentPlaceholder = null) {
     widget.dispatchEvent(trackingElement, 'ddg-ctp-tracking-element')
 
@@ -537,6 +524,8 @@ function showExtraUnblockIfShortPlaceholder (shadowRoot, placeholder) {
  *   in the document will be replaced instead.
  */
 async function replaceClickToLoadElements (targetElement) {
+    await ready
+
     for (const entity of Object.keys(config)) {
         for (const widgetData of Object.values(config[entity].elementData)) {
             const selector = widgetData.selectors.join()
@@ -1312,7 +1301,7 @@ async function createYouTubePreview (originalElement, widget) {
 // Convention is that each function should be named the same as the sendMessage
 // method we are calling into eg. calling `sendMessage('getClickToLoadState')`
 // will result in a response routed to `updateHandlers.getClickToLoadState()`.
-const updateHandlers = {
+const messageResponseHandlers = {
     getClickToLoadState (response) {
         devMode = response.devMode
         isYoutubePreviewsEnabled = response.youtubePreviewsEnabled
@@ -1322,14 +1311,15 @@ const updateHandlers = {
         //       first.
 
         // Start Click to Load
-        if (document.readyState === 'complete') {
-            initCTL()
-        } else {
-            // Content script loaded before page content, so wait for load.
-            window.addEventListener('load', (event) => {
-                initCTL()
-            })
-        }
+        window.addEventListener('ddg-ctp-replace-element', ({ target }) => {
+            replaceClickToLoadElements(target)
+        }, { capture: true })
+
+        // Inform surrogate scripts that CTP is ready
+        originalWindowDispatchEvent(createCustomEvent('ddg-ctp-ready'))
+
+        // Mark the feature as ready, to allow placeholder replacements.
+        readyResolver()
     },
     setYoutubePreviewsEnabled: function (resp) {
         if (resp?.messageType && typeof resp?.value === 'boolean') {
@@ -1346,6 +1336,8 @@ const updateHandlers = {
     }
 }
 
+const knownMessage = Object.prototype.hasOwnProperty.bind(messageResponseHandlers)
+
 export function init (args) {
     const websiteOwner = args?.site?.parentEntity
     const settings = args?.featureSettings?.clickToPlay || {}
@@ -1411,17 +1403,25 @@ export function init (args) {
     })
 
     // Request the current state of Click to Load from the platform.
-    // Note: When the response is received, initCTL() is then called by the
-    //       response handler to finish starting up the feature.
+    // Note: When the response is received, the response handler finishes
+    //       starting up the feature.
     sendMessage('getClickToLoadState')
 }
 
 export function update (args) {
-    const detail = args && args.detail
-    if (!(detail && detail.func)) { return }
+    // Unsupported update message.
+    if (!args?.detail) return
 
-    const fn = updateHandlers[detail.func]
-    if (typeof fn !== 'function') { return }
+    // Message response.
+    if (typeof args?.detail?.func === 'string' && knownMessage(args.detail.func)) {
+        return messageResponseHandlers[args.detail.func](args.detail.response)
+    }
 
-    fn(detail.response)
+    // Other known update messages.
+    if (args?.detail?.type === 'displayClickToLoadPlaceholders') {
+        // TODO: Pass `args.detail.ruleAction` through, that way only content
+        //       corresponding to the entity for that ruleAction need to be
+        //       replaced with a placeholder.
+        return replaceClickToLoadElements()
+    }
 }