Add URL Metric mutation helpers to extension initialization API by ShyamGadde · Pull Request #1951 · WordPress/performance · GitHub

Summary

Fixes #1930

Relevant technical choices

Exposed URL Metric mutation helpers (getRootData, extendRootData, getElementData, extendElementData) in the initialize args to match what was already available in finalize args
Moved client extension initialization logic down to occur after the urlMetric definition
Updated extensions (Image Prioritizer and Embed Optimizer) to use these helpers directly during initialization
Eliminated need for storing temporary data and the finalize phase in extensions
Emits a deprecation warning if the client extensions includes a finalize function

…nalize` args Signed-off-by: Shyamsundar Gadde <shyamsundar.gadde@rtcamp.com>

Signed-off-by: Shyamsundar Gadde <shyamsundar.gadde@rtcamp.com>

…ric has been initialized Signed-off-by: Shyamsundar Gadde <shyamsundar.gadde@rtcamp.com>

Signed-off-by: Shyamsundar Gadde <shyamsundar.gadde@rtcamp.com>

Do we even need this anymore? I think we can remove this and then replace this:

externalBackgroundImages.push( externalBackgroundImage );

With:

	log(
		'Detected external background image for LCP element:',
		externalBackgroundImage
	);
	extendRootData( { lcpElementExternalBackgroundImage: externalBackgroundImage } );

Note that this handleLCPMetric could get called multiple times as new LCP candidates are expected.

Done in 8e5b031.

We need to keep this for now, especially since existing plugins are using this, but also because we're in beta so we can't just remove something. We can deprecate it, however. For example, of extension.finalize instanceof Function is truthy, then we can emit a deprecation warning:

extensionLogger.warn( 'Use of the finalize function in extensions is deprecated. Please refactor your extension to use the initialize function instead, and update the URL Metric data as soon as a change is detected rather than waiting until finalization.' );

Done in b2b48b3.

Signed-off-by: Shyamsundar Gadde <shyamsundar.gadde@rtcamp.com>

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: ShyamGadde <shyamgadde@git.wordpress.org>
Co-authored-by: westonruter <westonruter@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

… update/extension-initialize-helpers

@ShyamGadde I just realized that since the these functions are newly exposed among the InitializeArgs that we need to ensure that Image Prioritizer and Embed Optimizer are updated to require 1.0.0-beta4. See fb7e35c.

I've also improved typing in 2f20963.

Please review and test the additional changes to ensure they're working as expected.

Codecov Report

❌ Patch coverage is 75.00000% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 72.24%. Comparing base (ee3fe25) to head (9f079eb).
⚠️ Report is 1178 commits behind head on trunk.

Files with missing lines	Patch %	Lines
plugins/optimization-detective/load.php	0.00%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##            trunk    #1951   +/-   ##
=======================================
  Coverage   72.24%   72.24%           
=======================================
  Files          85       85           
  Lines        6953     6953           
=======================================
  Hits         5023     5023           
  Misses       1930     1930

Flag	Coverage Δ
multisite	72.24% <75.00%> (ø)
single	40.67% <75.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Thanks for catching that! I've tested them and it's working correctly.

ShyamGadde added 5 commits March 21, 2025 15:25

Expose URL Metrics mutation helpers in initialize args to match `fi…

793aedb

…nalize` args Signed-off-by: Shyamsundar Gadde <shyamsundar.gadde@rtcamp.com>

Remove unnecessary log

2dca347

Signed-off-by: Shyamsundar Gadde <shyamsundar.gadde@rtcamp.com>

Clean up breadcrumbedElementsMap right after it is last used

f8f2fc1

Signed-off-by: Shyamsundar Gadde <shyamsundar.gadde@rtcamp.com>

Move client extension initialization logic to occur after the URL Met…

1cfae6c

…ric has been initialized Signed-off-by: Shyamsundar Gadde <shyamsundar.gadde@rtcamp.com>

Eliminate finalize API from extensions

3f6f10b

Signed-off-by: Shyamsundar Gadde <shyamsundar.gadde@rtcamp.com>

ShyamGadde added this to the optimization-detective 1.0.0-beta4 milestone Mar 21, 2025

ShyamGadde added [Type] Enhancement A suggestion for improvement of an existing feature [Plugin] Optimization Detective Issues for the Optimization Detective plugin labels Mar 21, 2025

westonruter requested changes Mar 21, 2025

View reviewed changes

westonruter mentioned this pull request Mar 21, 2025

Explore compressing URL Metrics to work within the 64 KiB limit #1893

Closed

ShyamGadde added 2 commits March 24, 2025 19:47

Simplify Image Prioritizer's LCP handling to directly extend root data

8e5b031

Signed-off-by: Shyamsundar Gadde <shyamsundar.gadde@rtcamp.com>

Deprecate finalize API in extensions rather than removing it

b2b48b3

Signed-off-by: Shyamsundar Gadde <shyamsundar.gadde@rtcamp.com>

ShyamGadde marked this pull request as ready for review March 24, 2025 14:30

ShyamGadde requested review from adamsilverstein and felixarntz as code owners March 24, 2025 14:30

ShyamGadde requested a review from westonruter March 24, 2025 14:31

westonruter added 4 commits March 25, 2025 12:35

Eliminate type duplication and export function types

2f20963

Bump Optimization Detective to 1.0.0-beta4

fb7e35c

Merge branch 'trunk' of https://github.com/WordPress/performance into…

ecd8d7a

… update/extension-initialize-helpers

Remove obsolete PhpDeprecationInspection

974be38

Bump version in constant

9f079eb

westonruter approved these changes Mar 26, 2025

View reviewed changes

westonruter merged commit 2a1299d into WordPress:trunk Mar 26, 2025

westonruter mentioned this pull request Mar 26, 2025

Update finalize docs in OD introduction readme #1958

Merged

This was referenced Apr 3, 2025

Ensure URL Metric is initially constructed with all elements prior to initializing extensions #1968

Merged

Explore use of the fetchLater API should be used instead of using keepalive fetch at pagehide when available #1970

Open

westonruter added [Plugin] Embed Optimizer Issues for the Embed Optimizer plugin (formerly Auto Sizes) [Plugin] Image Prioritizer Issues for the Image Prioritizer plugin (dependent on Optimization Detective) labels Jan 8, 2026

+              	/**
+              	 * Detected LCP external background image candidates.
+              	 *
+              	 * @type {Array<{
+              	 *     url: string,
+              	 *     tag: string,
+              	 *     id: string|null,
+              	 *     class: string|null,
+              	 * }>}
+              	 */
+              	const externalBackgroundImages = [];

-              	// Finalize extensions.
-              	if ( extensions.size > 0 ) {
-              		/** @type {Promise[]} */
-              		const extensionFinalizePromises = [];
-              		/** @type {string[]} */
-              		const finalizingExtensionModuleUrls = [];
-              		for ( const [
-              			extensionModuleUrl,
-              			extension,
-              		] of extensions.entries() ) {
-              			if ( extension.finalize instanceof Function ) {
-              				const extensionLogger = createLogger(
-              					isDebug,
-              					`[Optimization Detective: ${
-              						extension.name || 'Unnamed Extension'
-              					}]`
-              				);
-              				try {
-              					const finalizePromise = extension.finalize( {
-              						isDebug,
-              						...extensionLogger,
-              						getRootData,
-              						getElementData,
-              						extendElementData,
-              						extendRootData,
-              					} );
-              					if ( finalizePromise instanceof Promise ) {
-              						extensionFinalizePromises.push( finalizePromise );
-              						finalizingExtensionModuleUrls.push(
-              							extensionModuleUrl
-              						);
-              					}
-              				} catch ( err ) {
-              					error(
-              						`Unable to start finalizing extension '${ extensionModuleUrl }':`,
-              						err
-              					);
-              				}
-              			}
-              		}
-              		// Wait for all extensions to finish finalizing.
-              		const settledFinalizePromises = await Promise.allSettled(
-              			extensionFinalizePromises
-              		);
-              		for ( const [
-              			i,
-              			settledFinalizePromise,
-              		] of settledFinalizePromises.entries() ) {
-              			if ( settledFinalizePromise.status === 'rejected' ) {
-              				error(
-              					`Failed to finalize extension '${ finalizingExtensionModuleUrls[ i ] }':`,
-              					settledFinalizePromise.reason
-              				);
-              			}
-              		}
-              	}

Add URL Metric mutation helpers to extension initialization API by ShyamGadde · Pull Request #1951 · WordPress/performance · GitHub

Uh oh!

Add URL Metric mutation helpers to extension initialization API - #1951

Add URL Metric mutation helpers to extension initialization API#1951
westonruter merged 12 commits into
WordPress:trunkfrom
ShyamGadde:update/extension-initialize-helpers

ShyamGadde commented Mar 21, 2025 •
edited
Loading

Uh oh!

Uh oh!

westonruter Mar 21, 2025

Uh oh!

ShyamGadde Mar 24, 2025

Uh oh!

westonruter Mar 21, 2025

Uh oh!

ShyamGadde Mar 24, 2025

Uh oh!

Uh oh!

github-actions Bot commented Mar 24, 2025

Uh oh!

westonruter commented Mar 25, 2025

Uh oh!

codecov Bot commented Mar 26, 2025 •
edited
Loading

Uh oh!

Uh oh!

ShyamGadde commented Mar 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Add URL Metric mutation helpers to extension initialization API by ShyamGadde · Pull Request #1951 · WordPress/performance · GitHub

Uh oh!

Add URL Metric mutation helpers to extension initialization API - #1951

Add URL Metric mutation helpers to extension initialization API#1951westonruter merged 12 commits intoWordPress:trunkWordPress/performance:trunkfrom ShyamGadde:update/extension-initialize-helpersShyamGadde/wp-performance:update/extension-initialize-helpersCopy head branch name to clipboard

Conversation

ShyamGadde commented Mar 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Relevant technical choices

Uh oh!

westonruter Mar 21, 2025

Choose a reason for hiding this comment

Uh oh!

ShyamGadde Mar 24, 2025

Choose a reason for hiding this comment

Uh oh!

westonruter Mar 21, 2025

Choose a reason for hiding this comment

Uh oh!

ShyamGadde Mar 24, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Mar 24, 2025

Uh oh!

westonruter commented Mar 25, 2025

Uh oh!

codecov Bot commented Mar 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

ShyamGadde commented Mar 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Add URL Metric mutation helpers to extension initialization API#1951
westonruter merged 12 commits into
WordPress:trunkfrom
ShyamGadde:update/extension-initialize-helpers

ShyamGadde commented Mar 21, 2025 •
edited
Loading

codecov Bot commented Mar 26, 2025 •
edited
Loading