Leverage URL metrics to reserve space for embeds to reduce CLS

plugins/embed-optimizer/class-embed-optimizer-tag-visitor.php

@@ -26,26 +26,76 @@ final class Embed_Optimizer_Tag_Visitor {
 	 */
 	protected $added_lazy_script = false;
 
+	/**
+	 * Determines whether the processor is currently at a figure.wp-block-embed tag.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @param OD_HTML_Tag_Processor $processor Processor.
+	 * @return bool Whether at the tag.
+	 */
+	private function is_embed_figure( OD_HTML_Tag_Processor $processor ): bool {
+		return (
+			'FIGURE' === $processor->get_tag()
+			&&
+			true === $processor->has_class( 'wp-block-embed' )
+		);
+	}
+
+	/**
+	 * Determines whether the processor is currently at a div.wp-block-embed__wrapper tag.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @param OD_HTML_Tag_Processor $processor Processor.
+	 * @return bool Whether the tag should be measured and stored in URL metrics
+	 */
+	private function is_embed_wrapper( OD_HTML_Tag_Processor $processor ): bool {
+		return (
+			'DIV' === $processor->get_tag()
+			&&
+			true === $processor->has_class( 'wp-block-embed__wrapper' )
+		);
+	}
+
 	/**
 	 * Visits a tag.
 	 *
 	 * @since 0.2.0
 	 *
 	 * @param OD_Tag_Visitor_Context $context Tag visitor context.
-	 * @return bool Whether the visit or visited the tag.
+	 * @return bool Whether the tag should be measured and stored in URL metrics.
 	 */
 	public function __invoke( OD_Tag_Visitor_Context $context ): bool {
 		$processor = $context->processor;
-		if ( ! (
-			'FIGURE' === $processor->get_tag()
-			&&
-			true === $processor->has_class( 'wp-block-embed' )
-		) ) {
+
+		/*
+		 * The only thing we need to do if it is a div.wp-block-embed__wrapper tag is return true so that the tag
+		 * will get measured and stored in the URL Metrics.
+		 */
+		if ( $this->is_embed_wrapper( $processor ) ) {
+			return true;
+		}
+
+		// Short-circuit if not a figure.wp-block-embed tag.
+		if ( ! $this->is_embed_figure( $processor ) ) {
 			return false;
 		}
 
-		$max_intersection_ratio = $context->url_metrics_group_collection->get_element_max_intersection_ratio( $processor->get_xpath() );
+		$embed_wrapper_xpath = $processor->get_xpath() . '/*[1][self::DIV]';
+		$minimum_height      = $context->url_metrics_group_collection->get_element_minimum_height( $embed_wrapper_xpath );
+		if ( is_float( $minimum_height ) ) {
+			$min_height_style = sprintf( 'min-height: %dpx;', $minimum_height );
+			$style            = $processor->get_attribute( 'style' );
+			if ( is_string( $style ) ) {
+				$style = $min_height_style . ' ' . $style;
+			} else {
+				$style = $min_height_style;
+			}
+			$processor->set_attribute( 'style', $style );
+		}
 
+		$max_intersection_ratio = $context->url_metrics_group_collection->get_element_max_intersection_ratio( $embed_wrapper_xpath );
 		if ( $max_intersection_ratio > 0 ) {
 			/*
 			 * The following embeds have been chosen for optimization due to their relative popularity among all embed types.
@@ -119,6 +169,12 @@ public function __invoke( OD_Tag_Visitor_Context $context ): bool {
 			$this->added_lazy_script = true;
 		}
 
-		return true;
+		/*
+		 * At this point the tag is a figure.wp-block-embed, and we can return false because this does not need to be
+		 * measured and stored in URL Metrics. Only the child div.wp-block-embed__wrapper tag is measured and stored
+		 * so that this visitor can look up the height to set as a min-height on the figure.wp-block-embed. For more
+		 * information on what the return values mean for tag visitors, see <https://github.com/WordPress/performance/issues/1342>.
+		 */
+		return false;
 	}
 }

plugins/embed-optimizer/detect.js

@@ -0,0 +1,91 @@
+const consoleLogPrefix = '[Embed Optimizer]';
+
+/**
+ * @typedef {import("../optimization-detective/types.d.ts").ElementMetrics} ElementMetrics
+ * @typedef {import("../optimization-detective/types.d.ts").URLMetric} URLMetric
+ */
+
+/**
+ * Log a message.
+ *
+ * @param {...*} message
+ */
+function log( ...message ) {
+	// eslint-disable-next-line no-console
+	console.log( consoleLogPrefix, ...message );
+}
+
+/**
+ * Embed element heights.
+ *
+ * @type {Map<string, DOMRectReadOnly>}
+ */
+const loadedElementContentRects = new Map();
+
+/**
+ * Initialize.
+ *
+ * @param {Object}  args         Args.
+ * @param {boolean} args.isDebug Whether to show debug messages.
+ */
+export async function initialize( { isDebug } ) {
+	const embedWrappers =
+		/** @type NodeListOf<HTMLDivElement> */ document.querySelectorAll(
+			'.wp-block-embed > .wp-block-embed__wrapper[data-od-xpath]'
+		);
+
+	for ( const embedWrapper of embedWrappers ) {
+		monitorEmbedWrapperForResizes( embedWrapper );
+	}
+
+	if ( isDebug ) {
+		log( 'Loaded embed content rects:', loadedElementContentRects );
+	}
+}
+
+/**
+ * Initialize.
+ *
+ * @param {Object}    args           Args.
+ * @param {boolean}   args.isDebug   Whether to show debug messages.
+ * @param {URLMetric} args.urlMetric Pending URL metric.
+ */
+export async function finalize( { urlMetric, isDebug } ) {
+	if ( isDebug ) {
+		log( 'URL metric to be sent:', urlMetric );
+	}
+
+	for ( const element of urlMetric.elements ) {
+		if ( loadedElementContentRects.has( element.xpath ) ) {
+			if ( isDebug ) {
+				log(
+					`Overriding boundingClientRect for ${ element.xpath }:`,
+					element.boundingClientRect,
+					'=>',
+					loadedElementContentRects.get( element.xpath )
+				);
+			}
+			// TODO: Maybe element.boundingClientRect should rather be element.initialBoundingClientRect and the schema is extended by Embed Optimizer to add an element.finalBoundingClientRect (same goes for intersectionRect and intersectionRatio).
+			element.boundingClientRect = loadedElementContentRects.get(
+				element.xpath
+			);
+		}
+	}
+}
+
+/**
+ * Monitors embed wrapper for resizes.
+ *
+ * @param {HTMLDivElement} embedWrapper Embed wrapper DIV.
+ */
+function monitorEmbedWrapperForResizes( embedWrapper ) {
+	if ( ! ( 'odXpath' in embedWrapper.dataset ) ) {
+		throw new Error( 'Embed wrapper missing data-od-xpath attribute.' );
+	}
+	const xpath = embedWrapper.dataset.odXpath;
+	const observer = new ResizeObserver( ( entries ) => {
+		const [ entry ] = entries;
+		loadedElementContentRects.set( xpath, entry.contentRect );
+	} );
+	observer.observe( embedWrapper, { box: 'content-box' } );
+}

plugins/embed-optimizer/hooks.php

@@ -20,8 +20,9 @@ function embed_optimizer_add_hooks(): void {
 
 	if ( defined( 'OPTIMIZATION_DETECTIVE_VERSION' ) ) {
 		add_action( 'od_register_tag_visitors', 'embed_optimizer_register_tag_visitors' );
+		add_filter( 'embed_oembed_html', 'embed_optimizer_filter_oembed_html_to_detect_embed_presence' );
 	} else {
-		add_filter( 'embed_oembed_html', 'embed_optimizer_filter_oembed_html' );
+		add_filter( 'embed_oembed_html', 'embed_optimizer_filter_oembed_html_to_lazy_load' );
 	}
 }
 add_action( 'init', 'embed_optimizer_add_hooks' );
@@ -40,17 +41,54 @@ function embed_optimizer_register_tag_visitors( OD_Tag_Visitor_Registry $registr
 }
 
 /**
- * Filter the oEmbed HTML.
+ * Filters the list of Optimization Detective extension module URLs to include the extension for Embed Optimizer.
+ *
+ * @since n.e.x.t
+ *
+ * @param string[]|mixed $extension_module_urls Extension module URLs.
+ * @return string[] Extension module URLs.
+ */
+function embed_optimizer_filter_extension_module_urls( $extension_module_urls ): array {
+	if ( ! is_array( $extension_module_urls ) ) {
+		$extension_module_urls = array();
+	}
+	$extension_module_urls[] = add_query_arg( 'ver', EMBED_OPTIMIZER_VERSION, plugin_dir_url( __FILE__ ) . 'detect.js' );
+	return $extension_module_urls;
+}
+
+/**
+ * Filter the oEmbed HTML to detect when an embed is present so that the Optimization Detective extension module can be enqueued.
+ *
+ * This ensures that the module for handling embeds is only loaded when there is an embed on the page.
+ *
+ * @since n.e.x.t
+ *
+ * @param string|mixed $html The oEmbed HTML.
+ * @return string Unchanged oEmbed HTML.
+ */
+function embed_optimizer_filter_oembed_html_to_detect_embed_presence( $html ): string {
+	if ( ! is_string( $html ) ) {
+		$html = '';
+	}
+	add_filter( 'od_extension_module_urls', 'embed_optimizer_filter_extension_module_urls' );
+	return $html;
+}
+
+/**
+ * Filter the oEmbed HTML to lazy load the embed.
  *
  * Add loading="lazy" to any iframe tags.
  * Lazy load any script tags.
  *
  * @since 0.1.0
  *
- * @param string $html The oEmbed HTML.
+ * @param string|mixed $html The oEmbed HTML.
  * @return string Filtered oEmbed HTML.
  */
-function embed_optimizer_filter_oembed_html( string $html ): string {
+function embed_optimizer_filter_oembed_html_to_lazy_load( $html ): string {
+	if ( ! is_string( $html ) ) {
+		$html = '';
+	}
 	$html_processor = new WP_HTML_Tag_Processor( $html );
 	if ( embed_optimizer_update_markup( $html_processor, true ) ) {
 		add_action( 'wp_footer', 'embed_optimizer_lazy_load_scripts' );

plugins/embed-optimizer/tests/test-cases/nested-figure-embed.php

@@ -4,7 +4,7 @@
 		$test_case->populate_url_metrics(
 			array(
 				array(
-					'xpath'             => '/*[1][self::HTML]/*[2][self::BODY]/*[1][self::FIGURE]',
+					'xpath'             => '/*[1][self::HTML]/*[2][self::BODY]/*[1][self::FIGURE]/*[1][self::DIV]',
 					'isLCP'             => false,
 					'intersectionRatio' => 1,
 				),
@@ -14,7 +14,7 @@
 					'intersectionRatio' => 1,
 				),
 				array(
-					'xpath'             => '/*[1][self::HTML]/*[2][self::BODY]/*[2][self::FIGURE]',
+					'xpath'             => '/*[1][self::HTML]/*[2][self::BODY]/*[2][self::FIGURE]/*[1][self::DIV]',
 					'isLCP'             => false,
 					'intersectionRatio' => 0,
 				),
@@ -74,12 +74,12 @@ static function ( OD_Tag_Visitor_Context $context ) use ( $test_case ): bool {
 				<title>...</title>
 			</head>
 			<body>
-				<figure class="wp-block-embed is-type-video">
+				<figure style="background: black; color:gray" class="wp-block-embed is-type-video">
 					<div class="wp-block-embed__wrapper">
 						<video src="https://example.com/video1.mp4" poster="https://example.com/poster1.jpg" width="640" height="480"></video>
 					</div>
 				</figure>
-				<figure class="wp-block-embed is-type-rich is-provider-figurine wp-block-embed-figurine">
+				<figure style="background: black; color: white;" class="wp-block-embed is-type-rich is-provider-figurine wp-block-embed-figurine">
 					<div class="wp-block-embed__wrapper">
 						<figure>
 							<p>So I heard you like <code>FIGURE</code>?</p>
@@ -101,13 +101,13 @@ static function ( OD_Tag_Visitor_Context $context ) use ( $test_case ): bool {
 				<link data-od-added-tag rel="preload" as="image" href="https://example.com/poster1.jpg">
 			</head>
 			<body>
-				<figure data-od-xpath="/*[1][self::HTML]/*[2][self::BODY]/*[1][self::FIGURE]" class="wp-block-embed is-type-video">
-					<div class="wp-block-embed__wrapper">
+				<figure data-od-replaced-style="background: black; color:gray" style="min-height: 500px; background: black; color:gray" class="wp-block-embed is-type-video">
+					<div data-od-xpath="/*[1][self::HTML]/*[2][self::BODY]/*[1][self::FIGURE]/*[1][self::DIV]" class="wp-block-embed__wrapper">
 						<video data-od-added-preload data-od-xpath="/*[1][self::HTML]/*[2][self::BODY]/*[1][self::FIGURE]/*[1][self::DIV]/*[1][self::VIDEO]" preload="auto" src="https://example.com/video1.mp4" poster="https://example.com/poster1.jpg" width="640" height="480"></video>
 					</div>
 				</figure>
-				<figure data-od-xpath="/*[1][self::HTML]/*[2][self::BODY]/*[2][self::FIGURE]" class="wp-block-embed is-type-rich is-provider-figurine wp-block-embed-figurine">
-					<div class="wp-block-embed__wrapper">
+				<figure data-od-replaced-style="background: black; color: white;" style="min-height: 500px; background: black; color: white;" class="wp-block-embed is-type-rich is-provider-figurine wp-block-embed-figurine">
+					<div data-od-xpath="/*[1][self::HTML]/*[2][self::BODY]/*[2][self::FIGURE]/*[1][self::DIV]" class="wp-block-embed__wrapper">
 						<figure>
 							<p>So I heard you like <code>FIGURE</code>?</p>
 							<video data-od-added-preload data-od-xpath="/*[1][self::HTML]/*[2][self::BODY]/*[2][self::FIGURE]/*[1][self::DIV]/*[1][self::FIGURE]/*[2][self::VIDEO]" preload="none" src="https://example.com/video2.mp4" poster="https://example.com/poster2.jpg" width="640" height="480"></video>

plugins/embed-optimizer/tests/test-cases/single-spotify-embed-outside-viewport-with-subsequent-script.php

@@ -4,7 +4,7 @@
 		$test_case->populate_url_metrics(
 			array(
 				array(
-					'xpath'             => '/*[1][self::HTML]/*[2][self::BODY]/*[1][self::FIGURE]',
+					'xpath'             => '/*[1][self::HTML]/*[2][self::BODY]/*[1][self::FIGURE]/*[1][self::DIV]',
 					'isLCP'             => false,
 					'intersectionRatio' => 0,
 				),
@@ -35,8 +35,8 @@
 				<title>...</title>
 			</head>
 			<body>
-				<figure data-od-xpath="/*[1][self::HTML]/*[2][self::BODY]/*[1][self::FIGURE]" class="wp-block-embed is-type-rich is-provider-spotify wp-block-embed-spotify wp-embed-aspect-21-9 wp-has-aspect-ratio">
-					<div class="wp-block-embed__wrapper">
+				<figure data-od-added-style style="min-height: 500px;" class="wp-block-embed is-type-rich is-provider-spotify wp-block-embed-spotify wp-embed-aspect-21-9 wp-has-aspect-ratio">
+					<div data-od-xpath="/*[1][self::HTML]/*[2][self::BODY]/*[1][self::FIGURE]/*[1][self::DIV]" class="wp-block-embed__wrapper">
 						<iframe data-od-added-loading loading="lazy" title="Spotify Embed: Deep Focus" style="border-radius: 12px" width="100%" height="352" frameborder="0" allowfullscreen allow="autoplay; clipboard-write; encrypted-media; fullscreen; picture-in-picture" src="https://open.spotify.com/embed/playlist/37i9dQZF1DWZeKCadgRdKQ?utm_source=oembed"></iframe>
 					</div>
 				</figure>

plugins/embed-optimizer/tests/test-cases/single-twitter-embed-inside-viewport.php

@@ -4,7 +4,7 @@
 		$test_case->populate_url_metrics(
 			array(
 				array(
-					'xpath'             => '/*[1][self::HTML]/*[2][self::BODY]/*[1][self::FIGURE]',
+					'xpath'             => '/*[1][self::HTML]/*[2][self::BODY]/*[1][self::FIGURE]/*[1][self::DIV]',
 					'isLCP'             => true,
 					'intersectionRatio' => 1,
 				),
@@ -36,7 +36,7 @@
 				<link data-od-added-tag rel="preconnect" href="https://pbs.twimg.com">
 			</head>
 			<body>
-				<figure class="wp-block-embed is-type-rich is-provider-twitter wp-block-embed-twitter">
+				<figure data-od-added-style style="min-height: 500px;" class="wp-block-embed is-type-rich is-provider-twitter wp-block-embed-twitter">
 					<div class="wp-block-embed__wrapper">
 						<blockquote class="twitter-tweet" data-width="550" data-dnt="true"><p lang="en" dir="ltr">We want your feedback for the Privacy Sandbox 📨<br><br>Learn why your feedback is critical through real examples and learn how to provide it ↓ <a href="https://t.co/anGk6gWkbc">https://t.co/anGk6gWkbc</a></p>&mdash; Chrome for Developers (@ChromiumDev) <a href="https://twitter.com/ChromiumDev/status/1636796541368139777?ref_src=twsrc%5Etfw">March 17, 2023</a></blockquote>
 						<script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>

plugins/embed-optimizer/tests/test-cases/single-twitter-embed-outside-viewport.php

@@ -4,7 +4,7 @@
 		$test_case->populate_url_metrics(
 			array(
 				array(
-					'xpath'             => '/*[1][self::HTML]/*[2][self::BODY]/*[1][self::FIGURE]',
+					'xpath'             => '/*[1][self::HTML]/*[2][self::BODY]/*[1][self::FIGURE]/*[1][self::DIV]',
 					'isLCP'             => false,
 					'intersectionRatio' => 0,
 				),
@@ -34,7 +34,7 @@
 				<title>...</title>
 			</head>
 			<body>
-				<figure class="wp-block-embed is-type-rich is-provider-twitter wp-block-embed-twitter">
+				<figure data-od-added-style style="min-height: 500px;" class="wp-block-embed is-type-rich is-provider-twitter wp-block-embed-twitter">
 					<div class="wp-block-embed__wrapper">
 						<blockquote class="twitter-tweet" data-width="550" data-dnt="true"><p lang="en" dir="ltr">We want your feedback for the Privacy Sandbox 📨<br><br>Learn why your feedback is critical through real examples and learn how to provide it ↓ <a href="https://t.co/anGk6gWkbc">https://t.co/anGk6gWkbc</a></p>&mdash; Chrome for Developers (@ChromiumDev) <a href="https://twitter.com/ChromiumDev/status/1636796541368139777?ref_src=twsrc%5Etfw">March 17, 2023</a></blockquote>
 						<script data-od-added-type type="application/vnd.embed-optimizer.javascript" async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>

plugins/embed-optimizer/tests/test-cases/single-wordpress-tv-embed-inside-viewport.php

@@ -4,7 +4,7 @@
 		$test_case->populate_url_metrics(
 			array(
 				array(
-					'xpath'             => '/*[1][self::HTML]/*[2][self::BODY]/*[1][self::FIGURE]',
+					'xpath'             => '/*[1][self::HTML]/*[2][self::BODY]/*[1][self::FIGURE]/*[1][self::DIV]',
 					'isLCP'             => true,
 					'intersectionRatio' => 1,
 				),
@@ -39,8 +39,8 @@
 				<link data-od-added-tag rel="preconnect" href="https://v0.wordpress.com">
 			</head>
 			<body>
-				<figure data-od-xpath="/*[1][self::HTML]/*[2][self::BODY]/*[1][self::FIGURE]" class="wp-block-embed is-type-video is-provider-wordpress-tv wp-block-embed-wordpress-tv wp-embed-aspect-16-9 wp-has-aspect-ratio">
-					<div class="wp-block-embed__wrapper">
+				<figure data-od-added-style style="min-height: 500px;" class="wp-block-embed is-type-video is-provider-wordpress-tv wp-block-embed-wordpress-tv wp-embed-aspect-16-9 wp-has-aspect-ratio">
+					<div data-od-xpath="/*[1][self::HTML]/*[2][self::BODY]/*[1][self::FIGURE]/*[1][self::DIV]" class="wp-block-embed__wrapper">
 						<iframe title="VideoPress Video Player" aria-label=\'VideoPress Video Player\' width=\'750\' height=\'422\' src=\'https://video.wordpress.com/embed/vaWm9zO6?hd=1&amp;cover=1\' frameborder=\'0\' allowfullscreen allow=\'clipboard-write\'></iframe>
 						<script src=\'https://v0.wordpress.com/js/next/videopress-iframe.js?m=1674852142\'></script>
 					</div>