perf(icons): load SVG payloads on demand, and add a benchmark to prove it

[herewithme]

Why

A client site on WordPress VIP with 300+ icons, several SVGs above 1 MB, was unusable. The plugin loaded every icon's content on every request — front-end pages with no icon block included — and the object cache could not store the result, so nothing ever warmed up.

Two VIP specifics turn "wasteful" into "fatal" there: media-library files live on VIP Files (every read is a network fetch), and the object cache is memcached (silently refuses items over 1 MB).

What changed

A performance protocol first (tests/perf/)

Before touching the plugin, a rig that reproduces the problem so the fix can be measured rather than asserted. It builds an isolated instance on port 8899 with 500 SVG icons — 200 in a theme folder, 300 contributed through the media library, sized ~11 KB → ~1.95 MB with 25 above 1 MB — behind an object cache that refuses items over 1 MB, and routes media reads through a bpifs:// stream wrapper that counts them and can charge VIP-like latency.

npm run perf:setup
npm run perf:bench -- --label=baseline

Then the three fixes

1. Payloads load on demand. Registering a collection builds a lightweight index: CollectionItem holds a small serializable descriptor (['type' => 'file', 'path' => …]) instead of the SVG, and ContentLoader reads the bytes the first time content() is called — one icon to render a block, one page's worth to list a collection in the editor. The indexes stay small: 108 KB for the 200-icon folder collection, 138 KB for 300 media attachments, against a 900 KB ceiling.
2. Payloads are cached individually, with a 900 KB ceiling. Memcached refuses items over 1 MB through a return value nothing checks, so oversized entries were rebuilt and refused forever. Adjustable via blockparty_icons_cache_max_item_bytes.
3. New attachments collection type for media-library SVGs: one query, one cached index salted on the posts cache's last_changed. Replaces the loop the README used to recommend, which cost a query plus a cache round trip per icon per request.

Results

Baseline first, because it sets the scale: at PHP's common 128 MB limit the plugin does not run at all against this dataset — it fatals while serialize()-ing a collection for the cache. Everything below runs at 512 MB, matching VIP.

Front-end page containing no icon block, median of 4 runs:

	before	after
SVG resident in memory	101.7 MB	0.015 MB
object-cache gets	301	2
cache writes refused (>1 MB)	16	0
blockparty_icons_init	602 ms	2.3 ms
peak memory	154 MB	12 MB

Charging 2 ms per media read to emulate VIP Files:

scenario	before	after
front page, no icon, warm cache	618 ms	25 ms
front page, no icon, cold cache	4806 ms	422 ms
front page, one icon, warm cache	547 ms	30 ms

Response bodies are unchanged where the payload is genuinely wanted — the same icons are still delivered byte for byte.

For the reviewer

• The upgrade path was the subtle part. A version salt cannot protect against a class-shape change, because wp_cache_get_salted() unserializes the stored value before it compares salts — the payload is already rebuilt into the new class shape by the time anything could reject it. Cached index keys therefore carry a format revision (CACHE_FORMAT), and typed properties gained defaults. Verified by warming the cache with 1.1.1 (908 entries written), then loading the new code over it.
• CollectionItem has no __serialize()/__unserialize(). An earlier revision of this branch added them to keep resolved payloads out of a cached index. They were dropped after checking that no call path needs them: every factory caches its index before anything calls content(). Default PHP serialization is enough, and the measured metrics are identical without them. Worth knowing if you wonder why nothing stops a resolved item from being serialized — the answer is call order, not a guard.
• resident is measured by reflection, not through content() — calling the getter would force every icon to resolve and destroy the thing being measured.
• The rig's cache is file-backed, not memcached. It reproduces the semantics exactly but not the latency, so operation counts are the transferable metric and wall time is indicative. Documented in tests/perf/README.md along with the other limits.
• phpcs.xml.dist now excludes ./tests/: grumphp passes changed files to phpcs explicitly, overriding the ruleset's file list, and a cache drop-in must assign $GLOBALS['wp_object_cache'] and declare both a class and the wp_cache_* functions in one file. The harness is already kept out of releases by .distignore.
• The demo theme and README were updated to stop recommending the per-attachment loop.

Not addressed

The editor still bootstraps ~22 MB. block_editor_rest_api_preload_paths inlines the first 50 icons of every collection with their content; a single REST page is 12 MB. Fixing that means changing what the editor asks for — dropping content from the view context, or having the picker fetch payloads only for icons it draws. Deliberately left out of this PR.

Verification

• phpcs clean (the only PHP check in CI)
• Psalm 242 vs 221 before, same Mixed* noise at errorLevel 1 as the existing codebase; not gated anywhere
• Functional checks pass for sprite, folder, attachments, lazy resolution, memoization, oversized-icon rendering, and the cache guard
• Front-end rendering verified byte-identical to baseline (20 476 / 39 935 / 3 597 704 bytes for the no-icon, one-icon and twenty-icon pages)
• Serialization round trip checked: an item stays unresolved through cache, and still resolves afterwards

One caution for anyone re-running the benchmark: at these magnitudes wall time is dominated by container jitter. A run right after the __serialize() removal showed the init hook at 14.97 ms against 2.33 ms before, which looks like a regression and is not — two further runs of the same code gave 1.83 ms and 2.05 ms. Read the operation counts (resident, cache get, refused), which did not move at all.

🤖 Generated with Claude Code

---

Note

Medium Risk
Core icon loading, caching, and registration paths change for all collection types; behavior should be equivalent when icons are rendered but cache/index shape and memory profile differ, so sites with large media-library sets need validation.

Overview
Icon collections no longer load every SVG at registration. CollectionItem keeps a serializable source descriptor and resolves markup on first content() via new ContentLoader, with per-payload object-cache entries. Folder/file factory paths build lightweight indexes (empty files skipped via filesize only).

Object-cache behavior is hardened for memcached-style 1 MB limits: Cache::set_cache refuses payloads over a default 900 KB ceiling (blockparty_icons_cache_max_item_bytes), and collection indexes use format-scoped keys (CACHE_FORMAT v3) plus plugin version in salts so old serialized shapes are not reused.

Media-library SVGs get a first-class attachments type (Collection::from_attachments / CollectionItemsFactory::from_attachments): one WP_Query, one cached index salted with wp_cache_get_last_changed('posts'), optional query args. Registration API and demo theme drop the per-attachment from_file loop; README documents the pattern.

A reproducible perf harness lives under tests/perf/ (fixtures, wp-env on 8899, instrumented object cache, bench/report npm scripts), with gitignored fixtures/results and phpcs exclusion for harness code.

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