perf(theme): add a core web vitals baseline by francoistibo · Pull Request #520 · BeAPI/beapi-frontend-framework

francoistibo · 2026-10-15T13:50:06Z

Dotez les projets d'images LCP « opt-in », d'images statiques redimensionnées, d'un logo à faible priorité, d'une initialisation JavaScript en mode veille et d'animations sans défilement, afin que les nouveaux thèmes démarrent avec des scores CWV plus proches de la moyenne.

Résumé

Ajoute un mode LCP opt-in sur get_the_image() (is_lcp) : fetchpriority="high", decoding="sync", pas de loading="lazy". fetchpriority="high" n'est jamais combiné avec loading="lazy".
Ajoute get_theme_static_image_markup() / the_theme_static_image() : width et height lus dans le fichier du thème (SVG ou raster) pour limiter le CLS. Un alt vide est rendu alt="" (image décorative) ; false ou null retire l'attribut.
Conserve alt="" quand l'appelant le demande sur une image de la médiathèque, pour que les technologies d'assistance ignorent l'image.
Passe le logo du header en fetchpriority="low", pour qu'il ne concurrence pas la vraie image LCP.
Précharge les fonts uniquement via le filtre bea_theme_framework_preload_fonts. La liste est vide par défaut : seuls les fichiers réellement affichés au premier rendu doivent y figurer.
Remplace la boucle de scroll de Animation par un IntersectionObserver partagé. Les options (start, end, playOnce, hideOnReachEnd) et les callbacks (onInit, onShow, onHide, onDestroy) restent les mêmes.
Ajoute deferInitialization() pour lancer le JavaScript non critique au repos du navigateur (INP).
Documente ce socle et ce qui reste à configurer par projet (WP Rocket, robots.txt, cache, fonts, embeds tiers) dans le README.

Plan de test

the_image() avec 'is_lcp' => true produit fetchpriority="high", decoding="sync" et aucun loading="lazy".
the_image() avec 'alt' => '' produit alt="".
the_theme_static_image() sur un SVG qui a width et height reprend ces attributs et alt="".
Le logo du header a fetchpriority="low".
Sans le filtre bea_theme_framework_preload_fonts, aucun <link rel="preload" as="font"> n'est imprimé.
Un élément .js-animation-opacity reçoit is-visible en entrant dans le viewport, et reste masqué avant.
prefers-reduced-motion et l'impression désactivent toujours les animations.

Note

Medium Risk
Touches front-page image attributes, scroll-driven animations (behavior may differ slightly from the old scroll-percent logic), and build output manifest shape; low security impact but worth regression-testing hero animations and static images after deploy.

Overview
Adds a Core Web Vitals baseline to the theme framework so new projects start closer to good LCP, CLS, and INP scores.

PHP / markup: get_the_image() gains opt-in is_lcp (fetchpriority="high", no loading="lazy"; decoding stays caller-controlled). Decorative alt="" is preserved on media library images. New the_theme_static_image() / helpers output width/height from build manifest imageDimensions in dist/assets.json, with a per-request filesystem fallback. Performance hooks add opt-in font preload via bea_theme_framework_preload_fonts and fetchpriority="low" on the custom logo. Assets reads imageDimensions and tolerates manifest keys that are not plain string paths.

Build: WebpackStaticImageDimensionsPlugin writes intrinsic sizes for dist/images/* into assets.json at compile time (SVG parse + optional sharp for rasters).

JS: Animation drops the oneloop.js scroll observer loop for shared IntersectionObserver instances (fallback shows content when IO is missing). New deferInitialization() runs non-critical work on idle for INP.

Docs: README documents theme-provided CWV helpers vs per-project cache, SEO, fonts, and embeds.

^{Reviewed by Cursor Bugbot for commit b82bd4f. Bugbot is set up for automated code reviews on this repo. Configure here.}

herewithme · 2026-10-15T14:35:45Z

Revue perf backend

Très bon socle CWV dans l'ensemble (LCP / CLS / INP bien ciblés, README honnête sur ce qui reste par projet). Mon seul vrai point de vigilance est backend, et il est concentré dans get_theme_static_image_dimensions() / get_theme_static_image_markup().

I/O fichier répété, non caché

Aujourd'hui, chaque appel de the_theme_static_image() paye, à chaque requête, sans mémoïsation :

get_theme_file_uri() → résolution child/parent (contient des file_exists())
get_theme_static_image_dimensions() → re-résout le même fichier via get_theme_file_path() (encore des file_exists())
is_readable() (stat)
puis file_get_contents() + preg_match (SVG) ou wp_getimagesize() (raster)

Soit ~3-4 syscalls fichier + un read + de la regex par image. En boucle (ex. archive de 80 cartes avec placeholder), c'est un pattern N+1 sur le filesystem.

Important : sur une infra où le web root / le thème est monté en réseau (NFS, EFS, montage partagé multi-front), chaque stat/open/read devient un aller-retour réseau de l'ordre du ms → potentiellement des centaines de ms de I/O invisibles en dev local SSD. Ni le realpath cache ni l'OPcache ne couvrent file_get_contents/wp_getimagesize.

Pistes (par ordre de préférence)

Dimensions calculées au build et stockées dans le manifest assets.json (déjà mis en cache depuis 486448a2) → au runtime, zéro accès fichier. Option la plus propre et robuste sur FS réseau.
Sinon cache persistant (object cache, clé = version de build) + mémoïsation par requête (static $cache). La mémoïsation seule ne sauve pas le 1er hit par requête sur FS réseau ; le cache persistant si.
A minima : résoudre le chemin une seule fois (éviter le double get_theme_file_uri() + get_theme_file_path()) et mémoïser par requête.

Secondaire : new WP_HTML_Tag_Processor() instancié par image (pur CPU, négligeable à l'unité, s'additionne à N élevé) — à ne regarder qu'après l'I/O.

Benchmark avant/après souhaité

Avant merge, j'aimerais un A/B master vs cette branche, même jeu de données / même infra :

Template de stress (généré par WP-CLI) rendant the_theme_static_image() pour N ∈ {1, 20, 50, 100}, mix SVG / raster + un gros SVG, plus une page de contrôle sans le helper.
Blackfire + wp profile hook : temps inclusif et nombre d'appels de get_theme_static_image_dimensions, file_get_contents, wp_getimagesize, is_readable, get_theme_file_path/uri.
Runs cache objet froid vs chaud, et SSD local vs web root monté réseau (latence injectée) → mesurer le delta par N.

Critères : sur cache chaud, le coût doit être ~indépendant de N et file_get_contents/wp_getimagesize appelés 0 fois.

Point annexe à mesurer

decoding="sync" sur l'image LCP : à objectiver (WebPageTest) avant de le garder par défaut — async est souvent préférable pour ne pas bloquer le paint.

cedric07 · 2026-10-15T14:29:32Z

 			'before'  => '',
 			'after'   => '',
 			'default' => false,
+			'is_lcp'  => false,


Pour une utilisation avec ARI, il faut bien le laisser à false car c'est ARI qui gère automatiquement ce fetchpriority via la déclaration de sa taille d'image au bon format.

Le documenter ? gérer un warning ou autre ? ou bien le tester avec ARI et s'assurer que ça ne casse rien si c'est à true ?

cedric07 · 2026-10-15T14:33:00Z

+	 *
+	 * @return void
+	 */
+	public function preload_fonts(): void {


ça fonctionne bien sur les fonts du dossier dist ? donc fonctionne dans un contexte fontsource ou font custom ? les fontsources sont aussi copiées dans le dossier dist

cedric07 · 2026-10-15T14:34:57Z

+			continue;
+		}
+
+		// Empty alt marks a decorative image; omitting the attribute is not equivalent for AT.


Il y avait déjà un fix dans la fonction the_image pour avoir un alt à vide si on le force, sinon l'attribut était supprimé.

Ici c'est le même principe, sauf que c'est une nouvelle fonction pour appeler une image venant du thème c'est ça (avec les attributs width/height etc...) ?

cedric07 · 2026-10-15T14:37:43Z

 		 */
 		add_action( 'wp', [ $this, 'register_assets' ] );
+		add_action( 'wp_head', [ $this, 'preload_fonts' ], 1 );
+		add_filter( 'get_custom_logo_image_attributes', [ $this, 'deprioritize_custom_logo' ], 20 );


Utile ? car notre logo est généralement un svg, soit inline, soit venant du thème ou alors une image venant d'un champ ACF. Ce filtre se base sur quoi ?

Car on est pas en FSE

cedric07 · 2026-10-15T14:38:44Z

Voir avec @n-langle vu que ça touche à oneloop ?

cedric07 · 2026-10-15T14:40:05Z

Good job, merci @francoistibo :)

francoistibo · 2026-10-15T14:48:43Z

@asadowski10 voilà une PR qui reprend ce que j'ai pu faire de générique en terme de perf sur Liora. y'a quasi la meme sur BBT. on va repasser sur tout ce qui touche a nos pratiques TD en réunion d'équipe, et je veux bien une petite review plugin dev ensuite

francoistibo · 2026-10-19T13:42:16Z

@herewithme dans ce commit, Les dimensions des images statiques sont maintenant calculées au build et stockées dans dist/assets.json (imageDimensions) ; au runtime on lit le manifeste déjà en cache, donc plus de lecture fichier en boucle sur un thème buildé. Fallback fichier une fois par chemin/requête si l’asset n’est pas dans le manifeste. URI mémoïsée, sans double résolution child/parent quand il n’y a pas de thème enfant.

herewithme · 2026-10-19T13:56:23Z

@herewithme dans ce commit, Les dimensions des images statiques sont maintenant calculées au build et stockées dans dist/assets.json (imageDimensions) ; au runtime on lit le manifeste déjà en cache, donc plus de lecture fichier en boucle sur un thème buildé. Fallback fichier une fois par chemin/requête si l’asset n’est pas dans le manifeste. URI mémoïsée, sans double résolution child/parent quand il n’y a pas de thème enfant.

Top, un bench avant/après ? :)

Give projects opt-in LCP images, sized static images, a low-priority logo, idle JS init, and scroll-free animations so new themes start closer to good CWV scores. Co-authored-by: Cursor <cursoragent@cursor.com>

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit b82bd4f. Configure here.}

cursor · 2026-10-19T15:42:04Z

+		delta,
+		direction: { x: Math.sign(delta.x), y: Math.sign(delta.y) },
+	}
+}


Scroll direction lost across observers

Medium Severity

getScrollInfos() writes lastScroll on every call, so only the first IntersectionObserver callback in a turn keeps a real delta. Later observers (and destroy()) then see direction as 0. Translation presets use scrollInfos.direction.y on show/hide, so those animations get a wrong or empty offset when several rootMargin groups fire together — the translation preset’s random start range makes that common while scrolling.

Additional Locations (2)

src/js/classes/Animation.js#L217-L227

src/js/classes/Animation.js#L130-L136

^{Reviewed by Cursor Bugbot for commit b82bd4f. Configure here.}

cedric07 reviewed Oct 15, 2026

View reviewed changes

francoistibo requested a review from asadowski10 October 15, 2026 14:45

francoistibo and others added 2 commits October 19, 2026 17:34

perf(theme): add a core web vitals baseline

a979dc3

Give projects opt-in LCP images, sized static images, a low-priority logo, idle JS init, and scroll-free animations so new themes start closer to good CWV scores. Co-authored-by: Cursor <cursoragent@cursor.com>

perf(theme): cache static image dimensions in assets.json at build time

b82bd4f

francoistibo force-pushed the feat/cwv-baseline branch from 1498fe6 to b82bd4f Compare October 19, 2026 15:35

cursor Bot reviewed Oct 19, 2026

View reviewed changes

Navigation Menu

Repository navigation

perf(theme): add a core web vitals baseline - #520

perf(theme): add a core web vitals baseline#520
francoistibo wants to merge 2 commits into
masterfrom
feat/cwv-baseline

francoistibo commented Oct 15, 2026 •

edited by cursor Bot

Loading

Uh oh!

herewithme commented Oct 15, 2026

Uh oh!

cedric07 Oct 15, 2026

Uh oh!

cedric07 Oct 15, 2026

Uh oh!

cedric07 Oct 15, 2026

Uh oh!

cedric07 Oct 15, 2026

Uh oh!

cedric07 Oct 15, 2026

Uh oh!

cedric07 Oct 15, 2026

Uh oh!

cedric07 commented Oct 15, 2026

Uh oh!

francoistibo commented Oct 15, 2026

Uh oh!

francoistibo commented Oct 19, 2026

Uh oh!

herewithme commented Oct 19, 2026

Uh oh!

cursor Bot left a comment

Uh oh!

cursor Bot Oct 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

francoistibo commented Oct 15, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Résumé

Plan de test

Uh oh!

herewithme commented Oct 15, 2026

Revue perf backend

I/O fichier répété, non caché

Pistes (par ordre de préférence)

Benchmark avant/après souhaité

Point annexe à mesurer

Uh oh!

cedric07 Oct 15, 2026

Choose a reason for hiding this comment

Uh oh!

cedric07 Oct 15, 2026

Choose a reason for hiding this comment

Uh oh!

cedric07 Oct 15, 2026

Choose a reason for hiding this comment

Uh oh!

cedric07 Oct 15, 2026

Choose a reason for hiding this comment

Uh oh!

cedric07 Oct 15, 2026

Choose a reason for hiding this comment

Uh oh!

cedric07 Oct 15, 2026

Choose a reason for hiding this comment

Uh oh!

cedric07 commented Oct 15, 2026

Uh oh!

francoistibo commented Oct 15, 2026

Uh oh!

francoistibo commented Oct 19, 2026

Uh oh!

herewithme commented Oct 19, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Oct 19, 2026

Choose a reason for hiding this comment

Scroll direction lost across observers

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

francoistibo commented Oct 15, 2026 •

edited by cursor Bot

Loading