From 126c66fa37841e045b34ff7a26bfb0bd187bc7eb Mon Sep 17 00:00:00 2001
From: Amaury Balmer <amaury@beapi.fr>
Date: Thu, 10 Sep 2026 15:21:29 +0200
Subject: [PATCH 1/6] test: add reproducible performance protocol for large
 icon sets

Stands up an isolated WordPress instance (port 8899, so it runs alongside the
normal dev env) holding 500 SVG icons: 200 in a theme folder and 300 contributed
through the media library, sized from ~11 KB to ~1.95 MB with 25 above 1 MB.

The rig exists to produce comparable before/after numbers rather than
assertions. It reproduces the three things that make WordPress VIP hurt:

- a persistent object cache that refuses items over 1 MB the way memcached does,
  silently returning false, which is exactly what no caller checks;
- media-library reads routed through a bpifs:// stream wrapper, so they are
  counted exactly and can be charged VIP Files-like latency;
- collections registered on every request, front end included.

Metrics land as one JSON record per request and are reduced to medians.
`resident` -- the SVG bytes actually held in memory -- is read by reflecting on
CollectionItem's private properties rather than through content(), so the
measurement stays honest once loading becomes lazy.

The object cache is file-backed rather than memcached: it reproduces the
semantics exactly but not the latency, so operation counts are the transferable
metric and wall time only indicative. That and the other limits are written up
in tests/perf/README.md.

phpcs now excludes ./tests/: grumphp passes changed files to phpcs explicitly,
which overrides the ruleset's file list, and the harness has to break WordPress
conventions to do its job -- a cache drop-in must assign
$GLOBALS['wp_object_cache'] and declare both a class and the wp_cache_*
functions in one file.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .gitignore                                    |   4 +
 package.json                                  |   7 +-
 phpcs.xml.dist                                |   7 +
 tests/perf/README.md                          | 261 ++++++++++
 tests/perf/bin/_env.sh                        |  66 +++
 tests/perf/bin/bench.sh                       | 128 +++++
 tests/perf/bin/generate-fixtures.mjs          | 221 ++++++++
 tests/perf/bin/report.mjs                     | 224 ++++++++
 tests/perf/bin/setup.sh                       | 171 +++++++
 tests/perf/bin/teardown.sh                    |  20 +
 tests/perf/drop-ins/object-cache.php          | 477 ++++++++++++++++++
 tests/perf/env/.wp-env.json                   |  20 +
 tests/perf/mu-plugins/bpi-perf-auth.php       |  70 +++
 tests/perf/mu-plugins/bpi-perf-probe.php      | 371 ++++++++++++++
 .../perf/theme/blockparty-perf/functions.php  | 133 +++++
 tests/perf/theme/blockparty-perf/index.php    |  24 +
 tests/perf/theme/blockparty-perf/style.css    |   6 +
 17 files changed, 2209 insertions(+), 1 deletion(-)
 create mode 100644 tests/perf/README.md
 create mode 100644 tests/perf/bin/_env.sh
 create mode 100755 tests/perf/bin/bench.sh
 create mode 100755 tests/perf/bin/generate-fixtures.mjs
 create mode 100755 tests/perf/bin/report.mjs
 create mode 100755 tests/perf/bin/setup.sh
 create mode 100755 tests/perf/bin/teardown.sh
 create mode 100644 tests/perf/drop-ins/object-cache.php
 create mode 100644 tests/perf/env/.wp-env.json
 create mode 100644 tests/perf/mu-plugins/bpi-perf-auth.php
 create mode 100644 tests/perf/mu-plugins/bpi-perf-probe.php
 create mode 100644 tests/perf/theme/blockparty-perf/functions.php
 create mode 100644 tests/perf/theme/blockparty-perf/index.php
 create mode 100644 tests/perf/theme/blockparty-perf/style.css

diff --git a/.gitignore b/.gitignore
index 6bd3701..5309cd3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -41,3 +41,7 @@ phpcs.xml
 /wp-tests-config.php
 /phpunit.xml
 /.phpunit.result.cache
+
+# Perf protocol: generated fixtures (~100 MB) and captured results
+tests/perf/fixtures/
+tests/perf/results/
diff --git a/package.json b/package.json
index bd0052c..4e64d31 100644
--- a/package.json
+++ b/package.json
@@ -18,7 +18,12 @@
 		"make-json": "wp i18n make-json languages/blockparty-icons-fr_FR.po languages/ --no-purge",
 		"env:start": "wp-env start --config=./.wp-env.json",
 		"env:stop": "wp-env stop --config=./.wp-env.json",
-		"test:php": "bash tests/bin/phpunit.sh"
+		"test:php": "bash tests/bin/phpunit.sh",
+		"perf:setup": "bash tests/perf/bin/setup.sh",
+		"perf:bench": "bash tests/perf/bin/bench.sh",
+		"perf:report": "node tests/perf/bin/report.mjs",
+		"perf:fixtures": "node tests/perf/bin/generate-fixtures.mjs",
+		"perf:teardown": "bash tests/perf/bin/teardown.sh"
 	},
 	"devDependencies": {
 		"@wordpress/env": "^10.39.0",
diff --git a/phpcs.xml.dist b/phpcs.xml.dist
index 1c41647..607c551 100644
--- a/phpcs.xml.dist
+++ b/phpcs.xml.dist
@@ -10,6 +10,13 @@
 	<file>./includes/</file>
 
 	<exclude-pattern>./build/</exclude-pattern>
+	<!--
+		The performance harness is not plugin code and is excluded from releases by
+		.distignore. It has to break WordPress conventions to do its job: the object
+		cache drop-in must assign $GLOBALS['wp_object_cache'] and declare both a class
+		and the wp_cache_* functions in one file.
+	-->
+	<exclude-pattern>./tests/</exclude-pattern>
 	<exclude-pattern>./node_modules/</exclude-pattern>
 	<exclude-pattern>./src/</exclude-pattern>
 	<exclude-pattern>./tools/</exclude-pattern>
diff --git a/tests/perf/README.md b/tests/perf/README.md
new file mode 100644
index 0000000..e363a84
--- /dev/null
+++ b/tests/perf/README.md
@@ -0,0 +1,261 @@
+# Blockparty Icons — performance protocol
+
+A reproducible local rig for the WordPress VIP performance problem: a site with
+500+ SVG icons, some larger than 1 MB, where the plugin loads every icon's content
+into memory on every request — front end included, whether or not any icon is used.
+
+The rig exists to produce **comparable before/after numbers**, so that a fix can be
+shown to work rather than asserted to.
+
+---
+
+## What it builds
+
+An isolated WordPress instance on <http://localhost:8899> (the normal dev env on
+8888 is untouched and can run at the same time):
+
+| | |
+|---|---|
+| `perf-theme` | 200 SVG icons in a theme folder, registered with `type => folder` |
+| `perf-media` | 300 SVG icons contributed through the back office (media library) |
+| icon sizes | ~11 KB → ~1.95 MB, following a fixed ladder; **25 icons exceed 1 MB** |
+| total payload | ~102 MB of SVG |
+| object cache | persistent, and refuses any item over 1 MB — like VIP's memcached |
+| pages | `/perf-empty/` (no icon), `/perf-single/` (1 icon), `/perf-many/` (20 icons) |
+
+The two collections deliberately mirror the VIP topology: theme files are local,
+media-library files are remote. `get_attached_file()` is routed through a `bpifs://`
+stream wrapper that counts every open and can charge artificial latency.
+
+---
+
+## Prerequisites
+
+- Docker running
+- Node 22 (`volta` pins it)
+- `composer` on the PATH — **the plugin resolves its classes through Composer's
+  PSR-4 autoloader**, so without `vendor/` nothing loads
+
+## Usage
+
+```bash
+# One-off: generate fixtures, boot the env, import 300 icons into the media library.
+# Takes several minutes, mostly the media import.
+npm run perf:setup
+
+# Capture a run. --label names the result set.
+npm run perf:bench -- --label=baseline
+
+# After changing the plugin, capture again and diff against the baseline.
+npm run perf:bench -- --label=after
+node tests/perf/bin/report.mjs --label=after --compare=baseline
+
+# Tear down (removes containers and the database, keeps the fixtures).
+npm run perf:teardown
+```
+
+Useful flags:
+
+| flag | effect |
+|---|---|
+| `--scale=small` (setup) | 50 icons instead of 500, for quick iteration on the rig itself |
+| `--skip-fixtures` (setup) | reuse the SVGs already generated |
+| `--runs=N` (bench) | samples per scenario, default 5; the first is dropped as warm-up |
+| `--latency-us=2000` (bench) | charge 2 ms per media-library file open, emulating VIP Files |
+
+---
+
+## Metrics
+
+The probe (`mu-plugins/bpi-perf-probe.php`) writes one JSON record per request.
+`report.mjs` reduces each scenario to a **median** so one container hiccup cannot
+move a number.
+
+| column | meaning |
+|---|---|
+| `icons` | icons held in registered collections |
+| `response KB` | bytes on the wire |
+| `resident` | **MB of SVG content held in memory.** The direct measure of the problem |
+| `peak mem` | `memory_get_peak_usage(true)` |
+| `media reads` | media-library file opens, exact, via the `bpifs://` wrapper |
+| `cache get` / `cache miss` | object-cache operations in the `blockparty-icons` group |
+| `set >1MB refused` | cache writes memcached would reject. **These never warm up** |
+| `init hook` | wall time inside `blockparty_icons_init` |
+| `wall` | total request time |
+
+`resident` is measured by reflecting on `CollectionItem`'s private properties, not
+by calling `content()`. Calling the getter would force lazily-loaded icons to
+resolve and destroy the very thing being measured — the number stays honest across
+the refactor.
+
+---
+
+## Faithfulness, and where it stops
+
+Deliberate choices worth knowing before trusting a number:
+
+- **The object cache is file-backed, not memcached.** It reproduces the *semantics*
+  exactly — persistence across requests, a 1 MB item ceiling, a silent `false` from
+  `wp_cache_set()` — but not the latency. Local file I/O is far cheaper than a
+  network round trip. **Treat operation counts as the transferable metric and wall
+  time as indicative only.** To model VIP, multiply `cache get` by a memcached RTT.
+- **Theme-folder file reads are not counted directly.** `glob()` bypasses PHP stream
+  wrappers, so only media-library reads get exact counts. Folder reads are inferred
+  from cache misses: a miss on `from_folder:*` means all 200 files were re-read.
+  `resident` covers what actually ended up in memory either way.
+- **Latency emulation is off by default** (`--latency-us=0`) so the baseline states
+  only what was really measured. Turn it on for a VIP-shaped picture.
+- **PHP memory limit is raised to 512 MB**, matching VIP's web limit. At PHP's
+  common 128 MB default this dataset does not merely run slowly — see below.
+
+---
+
+## Baseline (2026-09-10, 500 icons, latency 0, 4 runs)
+
+### At a 128 MB PHP memory limit, the plugin does not run at all
+
+Activating the plugin against this dataset fatals outright:
+
+```
+PHP Fatal error: Allowed memory size of 134217728 bytes exhausted
+(tried to allocate 31887360 bytes) in .../object-cache.php on line 216
+```
+
+The allocation that fails is `serialize()` on the 200-icon folder collection. The
+collection is built in full (~40 MB), then serialized for the cache (~32 MB more).
+Everything below therefore runs at 512 MB.
+
+### Measured
+
+| scenario | icons | response KB | resident MB | peak MB | media reads | cache get | cache miss | >1MB refused | init ms | wall ms |
+|---|---|---|---|---|---|---|---|---|---|---|
+| front-empty-warm | 500 | 20 | 101.7 | 154 | 15 | 301 | 16 | 16 | 602 | 640 |
+| front-empty-cold | 500 | 20 | 101.7 | 154 | 300 | 301 | 301 | 16 | 2557 | 2658 |
+| front-single-warm | 500 | 39 | 101.7 | 154 | 15 | 301 | 16 | 16 | 679 | 768 |
+| front-single-cold | 500 | 39 | 101.7 | 154 | 300 | 301 | 301 | 16 | 860 | 934 |
+| front-many-warm | 500 | 3513 | 101.7 | 154 | 15 | 301 | 16 | 16 | 305 | 363 |
+| rest-collections | 500 | <1 | 101.7 | 173 | 15 | 301 | 16 | 16 | 539 | 601 |
+| rest-theme-p1 | 500 | 12065 | 101.7 | 154 | 15 | 301 | 16 | 16 | 568 | 729 |
+| rest-media-p1 | 500 | 11805 | 101.7 | 171 | 15 | 301 | 16 | 16 | 230 | 284 |
+| rest-theme-search | 500 | 8818 | 101.7 | 154 | 15 | 301 | 16 | 16 | 459 | 558 |
+| editor-new-page | 500 | **24530** | 101.7 | 239 | 15 | 301 | 16 | 16 | 506 | 1201 |
+
+### What the numbers say
+
+1. **`resident` is 101.7 MB on every single row**, including `front-empty-*`, a page
+   with no icon block at all. The entire 102 MB icon corpus is loaded to render a
+   paragraph. It never varies, because nothing about the request influences it.
+
+2. **16 cache entries are permanently refused** for exceeding 1 MB:
+   - `from_folder:.../theme-icons` — the whole 200-icon collection as one entry
+   - 15 × `from_file:...` — each individual media icon above 1 MB
+
+   These are not slow-to-warm; they *never* warm. `wp_cache_set()` returns `false`,
+   no caller checks it, and the work is redone on every request forever. The
+   `from_folder` rejection alone means all 200 theme SVGs are re-read from disk on
+   every request.
+
+3. **301 object-cache gets per request**, 300 of them from the media-library
+   collection's per-file cache keys. On VIP each is a memcached round trip; at a
+   conservative 0.3 ms that is ~90 ms of pure latency before any rendering.
+
+4. **A cold cache costs 300 media reads and 61.8 MB** of remote reads. With
+   `--latency-us=2000` that alone adds ~600 ms.
+
+5. **The editor bootstraps 24.5 MB of HTML** because
+   `block_editor_rest_api_preload_paths` inlines the first 50 icons *with content*
+   for each collection. A single REST page is 12 MB.
+
+These reproduce the three failure modes in the audit: eager whole-corpus loading
+(point 1), cache entries too large to store (point 3), and the media-library
+registration pattern (point 5).
+
+---
+
+## After the fix
+
+Points 1, 3 and 5 applied: lazy payload loading, per-icon caching with a size
+guard, and the `attachments` collection type. Same dataset, same 4 runs.
+
+| scenario | resident MB | peak MB | media reads | cache get | >1MB refused | init ms | wall ms |
+|---|---|---|---|---|---|---|---|
+| front-empty-warm | 0.015 (−100%) | 12 (−92%) | 0 (−100%) | 2 (−99%) | 0 | 2.3 (−100%) | 58 (−91%) |
+| front-empty-cold | 0.015 (−100%) | 16 (−90%) | 0 (−100%) | 2 (−99%) | 0 | 329 (−87%) | 388 (−85%) |
+| front-single-warm | 0.032 (−100%) | 10 (−94%) | 0 (−100%) | 2 (−99%) | 0 | 1.3 (−100%) | 32 (−96%) |
+| front-many-warm | 3.42 (−97%) | 31 (−80%) | 0 (−100%) | 2 (−99%) | 0 | 1.5 (−99%) | 95 (−74%) |
+| rest-theme-p1 | 11.70 (−88%) | 33 (−79%) | 0 (−100%) | 2 (−99%) | 0 | 0.5 (−100%) | 55 (−92%) |
+| rest-media-p1 | 9.11 (−91%) | 27 (−84%) | 3 (−80%) | 2 (−99%) | 0 | 0.8 (−100%) | 67 (−77%) |
+| editor-new-page | 20.80 (−80%) | 147 (−38%) | 3 (−80%) | 2 (−99%) | 0 | 81 (−84%) | 432 (−64%) |
+
+Reading the rows:
+
+- **`resident` collapses from a flat 101.7 MB to what the request actually uses** —
+  15 KB for a page with no icon, 32 KB for a page with one, 11.7 MB for an editor
+  page that genuinely lists 50 icons.
+- **`cache get` drops from 301 to 2**: one index per collection, instead of one
+  lookup per media attachment.
+- **No cache entry is refused any more.** Indexes are small enough to store, and
+  payloads are cached individually — a 1.8 MB icon no longer poisons a collection.
+- `response KB` is unchanged where the payload is genuinely wanted: the same icons
+  are still delivered, byte for byte.
+
+### With VIP-shaped latency (`--latency-us=2000`)
+
+Charging 2 ms per media-library file open, which is what a VIP Files fetch costs:
+
+| scenario | before | after |
+|---|---|---|
+| front-empty-warm | 618 ms | 25 ms (−96%) |
+| front-empty-cold | **4806 ms** | 422 ms (−91%) |
+| front-single-warm | 547 ms | 30 ms (−94%) |
+| editor-new-page | 1057 ms | 556 ms (−47%) |
+
+### What is not addressed
+
+- **The editor still bootstraps ~22 MB.** `block_editor_rest_api_preload_paths`
+  inlines the first 50 icons of every collection, with content. Cutting 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. That was point 4 of the
+  audit and is out of scope here.
+- Rendering a page with 20 icons still resolves 20 payloads (3.4 MB). That is the
+  work the page actually requires.
+
+---
+
+## Files
+
+```
+tests/perf/
+  bin/
+    _env.sh                 shared config; works around three wp-env quirks
+    generate-fixtures.mjs   deterministic SVG generator (seeded, reproducible)
+    setup.sh                boot the env, import media, create pages
+    bench.sh                run the scenarios, capture metrics
+    report.mjs              aggregate to medians, render the table, diff runs
+    teardown.sh             destroy the env
+  drop-ins/object-cache.php instrumented cache with memcached's 1 MB ceiling
+  mu-plugins/
+    bpi-perf-probe.php      metrics + the bpifs:// remote-filesystem wrapper
+    bpi-perf-auth.php       test-only auth shim for REST scenarios
+  theme/blockparty-perf/    fixture theme; registers both collections
+  env/.wp-env.json          the isolated environment definition
+  fixtures/                 generated SVGs (git-ignored, ~102 MB)
+  results/                  captured runs (git-ignored)
+```
+
+### wp-env quirks worked around
+
+`@wordpress/env` 10.39:
+
+1. has **no `--config` flag** on any subcommand — it reads `.wp-env.json` from the
+   working directory, which is why the perf env lives in `tests/perf/env/`;
+2. ignores the `port` key, templating `${WP_ENV_PORT:-8888}` into docker-compose
+   instead — so the ports are set through environment variables;
+3. gives `wp-env run` no way to target a non-default env — so the harness talks to
+   the containers with `docker exec`, resolving them by published port.
+
+### Safety
+
+`bpi-perf-auth.php` authenticates any request presenting the `BPI_PERF_TOKEN`
+constant's value. It is inert unless that constant is defined, and it is defined
+only in `tests/perf/env/.wp-env.json`. It must never be copied into a real site.
diff --git a/tests/perf/bin/_env.sh b/tests/perf/bin/_env.sh
new file mode 100644
index 0000000..3776501
--- /dev/null
+++ b/tests/perf/bin/_env.sh
@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+#
+# Shared settings for the perf harness. Sourced by setup.sh and bench.sh.
+#
+# Three wp-env facts shape this file (@wordpress/env 10.39):
+#
+# 1. There is no --config flag. wp-env always reads .wp-env.json from the current
+#    working directory. The perf environment therefore lives in its own directory,
+#    tests/perf/env/, with its own .wp-env.json. That also gives it its own project
+#    hash, so its containers and database are fully isolated from the dev env.
+#
+# 2. Ports come from WP_ENV_PORT / WP_ENV_TESTS_PORT, not from the config file.
+#    We pin them so the perf instance can run alongside the dev env on 8888/8889.
+#
+# 3. `wp-env run` takes no config either, so we address the containers directly
+#    with docker exec, resolving them by the port they publish.
+
+export WP_ENV_PORT="${WP_ENV_PORT:-8899}"
+export WP_ENV_TESTS_PORT="${WP_ENV_TESTS_PORT:-8898}"
+
+PERF_ROOT="$( cd "$( dirname "${BASH_SOURCE[0]}" )/../../.." && pwd )"
+PERF_ENV_DIR="${PERF_ROOT}/tests/perf/env"
+PERF_BASE="http://localhost:${WP_ENV_PORT}"
+PERF_TOKEN="local-perf-harness-only"
+
+export PERF_ROOT PERF_ENV_DIR PERF_BASE PERF_TOKEN
+
+say() {
+	printf '\n\033[1m==> %s\033[0m\n' "$1"
+}
+
+# Run a wp-env subcommand against the perf environment.
+perf_wp_env() {
+	( cd "$PERF_ENV_DIR" && npx --prefix "$PERF_ROOT" wp-env "$@" )
+}
+
+# Resolve the perf environment's container names from the published port.
+perf_resolve_containers() {
+	local wp
+	wp="$( docker ps \
+		--filter "publish=${WP_ENV_PORT}" \
+		--filter "name=-wordpress-1" \
+		--format '{{.Names}}' | head -n1 )"
+
+	if [ -z "$wp" ]; then
+		echo "No running wp-env WordPress container publishing port ${WP_ENV_PORT}." >&2
+		echo "Start it with: tests/perf/bin/setup.sh" >&2
+		return 1
+	fi
+
+	PERF_WP_CONTAINER="$wp"
+	PERF_PROJECT="${wp%-wordpress-1}"
+	PERF_CLI_CONTAINER="${PERF_PROJECT}-cli-1"
+
+	export PERF_WP_CONTAINER PERF_PROJECT PERF_CLI_CONTAINER
+}
+
+# Run a command inside the CLI container, as the web user, at the WordPress root.
+incli() {
+	docker exec -u 33 -w /var/www/html "$PERF_CLI_CONTAINER" "$@"
+}
+
+# Run WP-CLI inside the perf environment.
+wpcli() {
+	incli wp "$@"
+}
diff --git a/tests/perf/bin/bench.sh b/tests/perf/bin/bench.sh
new file mode 100755
index 0000000..e857a36
--- /dev/null
+++ b/tests/perf/bin/bench.sh
@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+#
+# Run the Blockparty Icons perf scenarios and write a comparable result set.
+#
+#   tests/perf/bin/bench.sh --label=baseline [--runs=5] [--latency-us=0]
+#
+# --label      names the result file, so before/after runs can be diffed
+# --runs       samples per scenario (the first is discarded as a warm-up)
+# --latency-us artificial per-file latency for media-library reads, emulating VIP Files
+#
+set -euo pipefail
+
+# shellcheck source=tests/perf/bin/_env.sh
+source "$( dirname "${BASH_SOURCE[0]}" )/_env.sh"
+
+BASE="$PERF_BASE"
+TOKEN="$PERF_TOKEN"
+
+LABEL=""
+RUNS=5
+LATENCY=0
+
+for arg in "$@"; do
+	case "$arg" in
+		--label=*)      LABEL="${arg#*=}" ;;
+		--runs=*)       RUNS="${arg#*=}" ;;
+		--latency-us=*) LATENCY="${arg#*=}" ;;
+		*) echo "unknown argument: $arg" >&2; exit 1 ;;
+	esac
+done
+
+if [ -z "$LABEL" ]; then
+	echo "--label is required (e.g. --label=baseline)" >&2
+	exit 1
+fi
+
+cd "$PERF_ROOT"
+mkdir -p tests/perf/results
+
+perf_resolve_containers
+
+LOG_HOST="tests/perf/results/${LABEL}.log"
+SIZES_FILE="tests/perf/results/${LABEL}.sizes"
+: > "$SIZES_FILE"
+
+# wp-admin is gated by auth_redirect(), which validates the *auth*-scheme cookie,
+# while REST and the rest of WordPress read the logged_in one. Mint both.
+say "Minting an admin session for the editor scenario"
+ADMIN_ID="$( wpcli user list --role=administrator --field=ID --number=1 | tr -d '\r' )"
+LOGIN_COOKIE_NAME="$( wpcli eval 'echo LOGGED_IN_COOKIE;' | tr -d '\r' )"
+AUTH_COOKIE_NAME="$( wpcli eval 'echo AUTH_COOKIE;' | tr -d '\r' )"
+LOGIN_COOKIE_VALUE="$( wpcli eval "echo wp_generate_auth_cookie( ${ADMIN_ID}, time() + 7200, 'logged_in' );" | tr -d '\r' )"
+AUTH_COOKIE_VALUE="$( wpcli eval "echo wp_generate_auth_cookie( ${ADMIN_ID}, time() + 7200, 'auth' );" | tr -d '\r' )"
+
+if [ -z "$LOGIN_COOKIE_VALUE" ] || [ -z "$AUTH_COOKIE_VALUE" ]; then
+	echo "Could not mint auth cookies; the editor scenario will redirect." >&2
+else
+	echo "  admin user ${ADMIN_ID}, cookies minted"
+fi
+
+say "Resetting perf log"
+incli rm -f /var/www/html/wp-content/bpi-perf.log >/dev/null 2>&1 || true
+
+# hit URL, scenario-name, cold|warm, [auth]
+hit() {
+	local url="$1" name="$2" cache="$3" auth="${4:-noauth}"
+	local sep="?"
+	case "$url" in *\?*) sep="&" ;; esac
+
+	local full="${BASE}${url}${sep}bpi_perf_label=${name}&bpi_perf_latency_us=${LATENCY}"
+	local -a curl_args=( -s -o /dev/null -w '%{http_code} %{size_download}' --max-time 600 )
+
+	if [ "$auth" = "auth" ]; then
+		curl_args+=( -H "X-BPI-Perf-Token: ${TOKEN}" )
+		if [ -n "$LOGIN_COOKIE_VALUE" ]; then
+			curl_args+=( -b "${LOGIN_COOKIE_NAME}=${LOGIN_COOKIE_VALUE}" )
+			curl_args+=( -b "${AUTH_COOKIE_NAME}=${AUTH_COOKIE_VALUE}" )
+		fi
+	fi
+
+	local last_bytes=0
+	for i in $( seq 1 "$RUNS" ); do
+		if [ "$cache" = "cold" ]; then
+			wpcli cache flush >/dev/null 2>&1 || true
+		fi
+		local out code bytes
+		out="$( curl "${curl_args[@]}" "$full" )"
+		code="${out%% *}"
+		bytes="${out##* }"
+		last_bytes="$bytes"
+		if [ "$code" != "200" ]; then
+			printf '    %s run %s -> HTTP %s\n' "$name" "$i" "$code" >&2
+		fi
+	done
+
+	printf '%s\t%s\n' "$name" "$last_bytes" >> "$SIZES_FILE"
+	printf '  %-28s %s cache, %s runs, %s KB response\n' \
+		"$name" "$cache" "$RUNS" "$(( last_bytes / 1024 ))"
+}
+
+say "Running scenarios (latency=${LATENCY}us per media read)"
+
+# --- front end -------------------------------------------------------------
+hit "/perf-empty/"  "front-empty-warm"  warm
+hit "/perf-empty/"  "front-empty-cold"  cold
+hit "/perf-single/" "front-single-warm" warm
+hit "/perf-single/" "front-single-cold" cold
+hit "/perf-many/"   "front-many-warm"   warm
+
+# --- REST (editor data path) ----------------------------------------------
+hit "/wp-json/icons/v1/collections?context=edit"                 "rest-collections"   warm auth
+hit "/wp-json/icons/v1/perf-theme?context=edit&per_page=50"      "rest-theme-p1"      warm auth
+hit "/wp-json/icons/v1/perf-media?context=edit&per_page=50"      "rest-media-p1"      warm auth
+hit "/wp-json/icons/v1/perf-media?context=edit&per_page=50&page=4" "rest-media-p4"    warm auth
+hit "/wp-json/icons/v1/perf-theme?context=edit&search=icon-1"    "rest-theme-search"  warm auth
+
+# --- editor ----------------------------------------------------------------
+hit "/wp-admin/post-new.php?post_type=page" "editor-new-page" warm auth
+
+say "Collecting results"
+incli cat /var/www/html/wp-content/bpi-perf.log > "$LOG_HOST" 2>/dev/null || true
+
+if [ ! -s "$LOG_HOST" ]; then
+	echo "Perf log is empty — is the probe mu-plugin loaded?" >&2
+	exit 1
+fi
+
+node tests/perf/bin/report.mjs --label="$LABEL"
diff --git a/tests/perf/bin/generate-fixtures.mjs b/tests/perf/bin/generate-fixtures.mjs
new file mode 100755
index 0000000..9f4e722
--- /dev/null
+++ b/tests/perf/bin/generate-fixtures.mjs
@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+/**
+ * Generate deterministic SVG fixtures for the Blockparty Icons perf protocol.
+ *
+ * Two sets are produced:
+ *   - theme-icons/  consumed by the fixture theme as a `folder` collection (local FS, like a VIP theme)
+ *   - media-icons/  imported into the media library (remote FS on VIP, see the bpifs:// wrapper)
+ *
+ * Sizes follow a fixed ladder from ~10 KB to ~2 MB so that:
+ *   - the aggregate of any collection blows past memcached's 1 MB per-item limit
+ *   - a handful of *individual* icons also blow past it on their own
+ *
+ * Usage:
+ *   node tests/perf/bin/generate-fixtures.mjs [--scale=full|small] [--out=DIR]
+ */
+
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname( fileURLToPath( import.meta.url ) );
+const DEFAULT_OUT = resolve( HERE, '..', 'fixtures' );
+
+const KB = 1024;
+const MB = 1024 * 1024;
+
+/**
+ * Size ladder. Each bucket is [share, minBytes, maxBytes].
+ * `share` values are relative weights within a set.
+ */
+const LADDER = [
+	{ key: 'a', share: 0.55, min: 10 * KB, max: 50 * KB },
+	{ key: 'b', share: 0.28, min: 50 * KB, max: 250 * KB },
+	{ key: 'c', share: 0.12, min: 250 * KB, max: 1 * MB },
+	{ key: 'd', share: 0.05, min: 1 * MB, max: 2 * MB },
+];
+
+const SCALES = {
+	full: { theme: 200, media: 300 },
+	small: { theme: 20, media: 30 },
+};
+
+/** Deterministic PRNG (mulberry32) so runs are byte-for-byte reproducible. */
+function prng( seed ) {
+	let a = seed >>> 0;
+	return () => {
+		a = ( a + 0x6d2b79f5 ) >>> 0;
+		let t = a;
+		t = Math.imul( t ^ ( t >>> 15 ), t | 1 );
+		t ^= t + Math.imul( t ^ ( t >>> 7 ), t | 61 );
+		return ( ( t ^ ( t >>> 14 ) ) >>> 0 ) / 4294967296;
+	};
+}
+
+/** Assign a target byte size to every icon index, deterministically. */
+function planSizes( count, rand ) {
+	const plan = [];
+	let assigned = 0;
+
+	LADDER.forEach( ( bucket, i ) => {
+		// Last bucket soaks up the rounding remainder.
+		const n =
+			i === LADDER.length - 1
+				? count - assigned
+				: Math.round( count * bucket.share );
+		assigned += n;
+		for ( let k = 0; k < n; k++ ) {
+			plan.push( {
+				bucket: bucket.key,
+				bytes: Math.floor( bucket.min + rand() * ( bucket.max - bucket.min ) ),
+			} );
+		}
+	} );
+
+	// Interleave buckets so a paginated REST response (50 per page) sees a mix
+	// of sizes rather than 50 tiny icons on page 1.
+	const shuffled = [];
+	const stride = Math.ceil( Math.sqrt( plan.length ) ) || 1;
+	for ( let offset = 0; offset < stride; offset++ ) {
+		for ( let i = offset; i < plan.length; i += stride ) {
+			shuffled.push( plan[ i ] );
+		}
+	}
+
+	return shuffled;
+}
+
+/**
+ * Build a syntactically valid SVG padded with real path data up to `targetBytes`.
+ *
+ * Padding is genuine `<path d="...">` geometry rather than a comment blob, so that
+ * strip_tags(), preg_match_all() and WP_HTML_Tag_Processor do representative work.
+ */
+function buildSvg( name, targetBytes, rand ) {
+	const head =
+		`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" ` +
+		`role="img" aria-labelledby="t-${ name }">` +
+		`<title id="t-${ name }">${ name }</title>` +
+		`<path d="M12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20Zm0 3.5 2.1 4.3 4.7.7-3.4 3.3.8 4.7-4.2-2.2-4.2 2.2.8-4.7-3.4-3.3 4.7-.7Z" fill="currentColor"/>`;
+	const tail = `</svg>`;
+
+	const parts = [ head ];
+	let size = Buffer.byteLength( head ) + Buffer.byteLength( tail );
+
+	// Each filler path is ~600-700 bytes of plausible curve data.
+	while ( size < targetBytes ) {
+		const coords = [];
+		const segments = 24;
+		let x = ( rand() * 24 ).toFixed( 2 );
+		let y = ( rand() * 24 ).toFixed( 2 );
+		coords.push( `M${ x } ${ y }` );
+		for ( let s = 0; s < segments; s++ ) {
+			const c1x = ( rand() * 24 ).toFixed( 2 );
+			const c1y = ( rand() * 24 ).toFixed( 2 );
+			const c2x = ( rand() * 24 ).toFixed( 2 );
+			const c2y = ( rand() * 24 ).toFixed( 2 );
+			x = ( rand() * 24 ).toFixed( 2 );
+			y = ( rand() * 24 ).toFixed( 2 );
+			coords.push( `C${ c1x } ${ c1y } ${ c2x } ${ c2y } ${ x } ${ y }` );
+		}
+		coords.push( 'Z' );
+
+		const opacity = ( 0.1 + rand() * 0.9 ).toFixed( 3 );
+		const piece = `<path d="${ coords.join( ' ' ) }" fill="currentColor" fill-opacity="${ opacity }"/>`;
+
+		parts.push( piece );
+		size += Buffer.byteLength( piece );
+	}
+
+	parts.push( tail );
+	return parts.join( '' );
+}
+
+function generateSet( outDir, prefix, count, seed ) {
+	rmSync( outDir, { recursive: true, force: true } );
+	mkdirSync( outDir, { recursive: true } );
+
+	const rand = prng( seed );
+	const plan = planSizes( count, rand );
+	const entries = [];
+
+	plan.forEach( ( item, i ) => {
+		const index = String( i + 1 ).padStart( 3, '0' );
+		const name = `${ prefix }-${ index }`;
+		const svg = buildSvg( name, item.bytes, rand );
+		const bytes = Buffer.byteLength( svg );
+
+		writeFileSync( resolve( outDir, `${ name }.svg` ), svg );
+		entries.push( { name, file: `${ name }.svg`, bucket: item.bucket, bytes } );
+	} );
+
+	return entries;
+}
+
+function summarise( entries ) {
+	const total = entries.reduce( ( acc, e ) => acc + e.bytes, 0 );
+	const overLimit = entries.filter( ( e ) => e.bytes > MB );
+	const byBucket = {};
+	for ( const e of entries ) {
+		byBucket[ e.bucket ] = byBucket[ e.bucket ] || { count: 0, bytes: 0 };
+		byBucket[ e.bucket ].count++;
+		byBucket[ e.bucket ].bytes += e.bytes;
+	}
+	return {
+		count: entries.length,
+		totalBytes: total,
+		totalMB: +( total / MB ).toFixed( 2 ),
+		minBytes: Math.min( ...entries.map( ( e ) => e.bytes ) ),
+		maxBytes: Math.max( ...entries.map( ( e ) => e.bytes ) ),
+		overOneMB: overLimit.length,
+		byBucket,
+	};
+}
+
+function main() {
+	const args = Object.fromEntries(
+		process.argv.slice( 2 ).map( ( a ) => {
+			const [ k, v ] = a.replace( /^--/, '' ).split( '=' );
+			return [ k, v ?? true ];
+		} )
+	);
+
+	const scaleKey = args.scale === 'small' ? 'small' : 'full';
+	const scale = SCALES[ scaleKey ];
+	const out = args.out ? resolve( String( args.out ) ) : DEFAULT_OUT;
+
+	mkdirSync( out, { recursive: true } );
+
+	const theme = generateSet( resolve( out, 'theme-icons' ), 'theme-icon', scale.theme, 1337 );
+	const media = generateSet( resolve( out, 'media-icons' ), 'media-icon', scale.media, 4242 );
+
+	const manifest = {
+		generatedAt: new Date().toISOString(),
+		scale: scaleKey,
+		ladder: LADDER,
+		sets: {
+			theme: { dir: 'theme-icons', ...summarise( theme ), entries: theme },
+			media: { dir: 'media-icons', ...summarise( media ), entries: media },
+		},
+	};
+
+	writeFileSync(
+		resolve( out, 'manifest.json' ),
+		JSON.stringify( manifest, null, '\t' )
+	);
+
+	const t = manifest.sets.theme;
+	const m = manifest.sets.media;
+	const fmt = ( s ) =>
+		`${ s.count } icons, ${ s.totalMB } MB total, ${ ( s.minBytes / KB ).toFixed( 0 ) } KB → ` +
+		`${ ( s.maxBytes / MB ).toFixed( 2 ) } MB, ${ s.overOneMB } over 1 MB`;
+
+	process.stdout.write(
+		`scale     : ${ scaleKey }\n` +
+			`theme set : ${ fmt( t ) }\n` +
+			`media set : ${ fmt( m ) }\n` +
+			`total     : ${ ( ( t.totalBytes + m.totalBytes ) / MB ).toFixed( 2 ) } MB in ${ out }\n`
+	);
+}
+
+main();
diff --git a/tests/perf/bin/report.mjs b/tests/perf/bin/report.mjs
new file mode 100755
index 0000000..c99436c
--- /dev/null
+++ b/tests/perf/bin/report.mjs
@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+/**
+ * Aggregate a perf log into a comparable report.
+ *
+ *   node tests/perf/bin/report.mjs --label=baseline
+ *   node tests/perf/bin/report.mjs --label=after --compare=baseline
+ *
+ * Reads tests/perf/results/<label>.log (one JSON object per request) and writes
+ * tests/perf/results/<label>.json, then prints a table.
+ *
+ * The first sample of each scenario is dropped as a warm-up; the rest are reduced
+ * to a median so a single slow container hiccup cannot move the number.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname( fileURLToPath( import.meta.url ) );
+const RESULTS = resolve( HERE, '..', 'results' );
+
+/** Metrics that describe work done. Medians are reported for each. */
+const METRICS = [
+	{ key: 'items', label: 'icons', unit: '' },
+	{ key: 'response_kb', label: 'response KB', unit: '' },
+	{ key: 'resident_mb', label: 'resident', unit: 'MB' },
+	{ key: 'peak_mem_mb', label: 'peak mem', unit: 'MB' },
+	{ key: 'fs_reads', label: 'media reads', unit: '' },
+	{ key: 'fs_mb', label: 'media read', unit: 'MB' },
+	{ key: 'icons_oc_get', label: 'cache get', unit: '' },
+	{ key: 'icons_oc_miss', label: 'cache miss', unit: '' },
+	{ key: 'icons_oc_rejected', label: 'set >1MB refused', unit: '' },
+	{ key: 'hook_ms', label: 'init hook', unit: 'ms' },
+	{ key: 'wall_ms', label: 'wall', unit: 'ms' },
+];
+
+function median( values ) {
+	const nums = values.filter( ( v ) => typeof v === 'number' && !Number.isNaN( v ) );
+	if ( nums.length === 0 ) {
+		return null;
+	}
+	const sorted = [ ...nums ].sort( ( a, b ) => a - b );
+	const mid = Math.floor( sorted.length / 2 );
+	const value =
+		sorted.length % 2 === 0 ? ( sorted[ mid - 1 ] + sorted[ mid ] ) / 2 : sorted[ mid ];
+
+	return Math.round( value * 1000 ) / 1000;
+}
+
+/** Response sizes are captured by curl, not by the in-PHP probe. */
+function loadSizes( label ) {
+	const path = resolve( RESULTS, `${ label }.sizes` );
+	const sizes = {};
+	if ( ! existsSync( path ) ) {
+		return sizes;
+	}
+	for ( const line of readFileSync( path, 'utf8' ).split( '\n' ) ) {
+		if ( ! line.trim() ) {
+			continue;
+		}
+		const [ scenario, bytes ] = line.split( '\t' );
+		sizes[ scenario ] = Math.round( Number( bytes ) / 1024 );
+	}
+	return sizes;
+}
+
+function load( label ) {
+	const path = resolve( RESULTS, `${ label }.log` );
+	if ( ! existsSync( path ) ) {
+		throw new Error( `No log at ${ path }` );
+	}
+
+	const rows = readFileSync( path, 'utf8' )
+		.split( '\n' )
+		.filter( Boolean )
+		.map( ( line ) => {
+			try {
+				return JSON.parse( line );
+			} catch {
+				return null;
+			}
+		} )
+		.filter( Boolean );
+
+	const byScenario = new Map();
+	for ( const row of rows ) {
+		const key = row.label || 'unlabelled';
+		if ( ! byScenario.has( key ) ) {
+			byScenario.set( key, [] );
+		}
+		byScenario.get( key ).push( row );
+	}
+
+	const sizes = loadSizes( label );
+	const summary = {};
+	for ( const [ scenario, samples ] of byScenario ) {
+		// Drop the warm-up sample when we have more than one.
+		const used = samples.length > 1 ? samples.slice( 1 ) : samples;
+
+		const entry = {
+			samples: used.length,
+			ctx: used[ 0 ]?.ctx ?? '',
+			response_kb: sizes[ scenario ] ?? null,
+		};
+		for ( const { key } of METRICS ) {
+			if ( key === 'response_kb' ) {
+				continue; // Comes from curl, not from the probe.
+			}
+			entry[ key ] = median( used.map( ( s ) => s[ key ] ) );
+		}
+
+		// Carry the set of oversized cache keys, deduplicated.
+		const rejected = new Set();
+		for ( const s of used ) {
+			for ( const k of Object.keys( s.rejected_keys || {} ) ) {
+				rejected.add( k );
+			}
+		}
+		if ( rejected.size ) {
+			entry.rejected_keys = [ ...rejected ].sort();
+		}
+
+		summary[ scenario ] = entry;
+	}
+
+	return summary;
+}
+
+function fmt( value, width ) {
+	const s = value === null || value === undefined ? '—' : String( value );
+	return s.padStart( width );
+}
+
+function printTable( summary, compare ) {
+	const scenarios = Object.keys( summary );
+	const nameWidth = Math.max( 20, ...scenarios.map( ( s ) => s.length ) );
+
+	const cols = METRICS.map( ( m ) => ( {
+		...m,
+		width: Math.max( m.label.length, 9 ),
+	} ) );
+
+	const header =
+		'scenario'.padEnd( nameWidth ) + '  ' + cols.map( ( c ) => fmt( c.label, c.width ) ).join( '  ' );
+	console.log( '\n' + header );
+	console.log( '-'.repeat( header.length ) );
+
+	for ( const scenario of scenarios ) {
+		const row = summary[ scenario ];
+		const cells = cols.map( ( c ) => {
+			const now = row[ c.key ];
+			if ( ! compare || ! compare[ scenario ] ) {
+				return fmt( now, c.width );
+			}
+
+			const before = compare[ scenario ][ c.key ];
+			if ( before === null || now === null || before === now ) {
+				return fmt( now, c.width );
+			}
+
+			const delta = before === 0 ? null : Math.round( ( ( now - before ) / before ) * 100 );
+			const suffix = delta === null ? '' : ` (${ delta > 0 ? '+' : '' }${ delta }%)`;
+
+			return fmt( `${ now }${ suffix }`, c.width );
+		} );
+
+		console.log( scenario.padEnd( nameWidth ) + '  ' + cells.join( '  ' ) );
+	}
+
+	const rejecting = scenarios.filter( ( s ) => ( summary[ s ].icons_oc_rejected || 0 ) > 0 );
+	if ( rejecting.length ) {
+		console.log(
+			`\nCache entries refused for exceeding 1 MB (these never warm up, so the cost is paid on every request):`
+		);
+		const keys = new Set();
+		for ( const s of rejecting ) {
+			for ( const k of summary[ s ].rejected_keys || [] ) {
+				keys.add( k );
+			}
+		}
+		for ( const k of [ ...keys ].sort().slice( 0, 12 ) ) {
+			console.log( `  ${ k }` );
+		}
+		if ( keys.size > 12 ) {
+			console.log( `  … and ${ keys.size - 12 } more` );
+		}
+	}
+}
+
+function main() {
+	const args = Object.fromEntries(
+		process.argv.slice( 2 ).map( ( a ) => {
+			const [ k, v ] = a.replace( /^--/, '' ).split( '=' );
+			return [ k, v ?? true ];
+		} )
+	);
+
+	if ( ! args.label ) {
+		console.error( '--label is required' );
+		process.exit( 1 );
+	}
+
+	const summary = load( String( args.label ) );
+	writeFileSync(
+		resolve( RESULTS, `${ args.label }.json` ),
+		JSON.stringify( summary, null, '\t' )
+	);
+
+	let compare = null;
+	if ( args.compare ) {
+		const path = resolve( RESULTS, `${ args.compare }.json` );
+		if ( existsSync( path ) ) {
+			compare = JSON.parse( readFileSync( path, 'utf8' ) );
+			console.log( `\ncomparing "${ args.label }" against "${ args.compare }"` );
+		} else {
+			console.error( `no baseline at ${ path }, showing absolute numbers` );
+		}
+	}
+
+	printTable( summary, compare );
+	console.log( `\nwritten: tests/perf/results/${ args.label }.json` );
+}
+
+main();
diff --git a/tests/perf/bin/setup.sh b/tests/perf/bin/setup.sh
new file mode 100755
index 0000000..ad9646b
--- /dev/null
+++ b/tests/perf/bin/setup.sh
@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+#
+# Stand up the Blockparty Icons perf environment.
+#
+#   tests/perf/bin/setup.sh [--scale=full|small] [--skip-fixtures]
+#
+# Produces an isolated WordPress instance on http://localhost:8899 with:
+#   - 200 SVG icons in a theme folder    -> collection `perf-theme`
+#   - 300 SVG icons in the media library -> collection `perf-media`
+#   - icon sizes spread from ~10 KB to ~2 MB, several above memcached's 1 MB limit
+#   - a persistent object cache that refuses items over 1 MB, exactly like VIP
+#
+set -euo pipefail
+
+# shellcheck source=tests/perf/bin/_env.sh
+source "$( dirname "${BASH_SOURCE[0]}" )/_env.sh"
+
+SCALE="full"
+SKIP_FIXTURES=0
+
+for arg in "$@"; do
+	case "$arg" in
+		--scale=*)       SCALE="${arg#*=}" ;;
+		--skip-fixtures) SKIP_FIXTURES=1 ;;
+		*) echo "unknown argument: $arg" >&2; exit 1 ;;
+	esac
+done
+
+cd "$PERF_ROOT"
+
+# ---------------------------------------------------------------- fixtures
+
+if [ "$SKIP_FIXTURES" -eq 0 ]; then
+	say "Generating SVG fixtures (scale=${SCALE})"
+	node tests/perf/bin/generate-fixtures.mjs --scale="$SCALE"
+else
+	say "Reusing existing fixtures"
+fi
+
+if [ ! -f tests/perf/fixtures/manifest.json ]; then
+	echo "No fixtures found. Run without --skip-fixtures." >&2
+	exit 1
+fi
+
+# ------------------------------------------------------------------- build
+
+# The plugin's classes are found through Composer's PSR-4 autoloader. Without
+# vendor/ present, blockparty-icons.php loads but every one of its classes is missing.
+if [ ! -f vendor/autoload.php ]; then
+	say "Installing Composer dependencies (the plugin autoloads via PSR-4)"
+	composer install --no-interaction --no-progress
+fi
+
+if [ ! -d build ]; then
+	say "Building plugin assets"
+	npm run build
+fi
+
+# --------------------------------------------------------------- wp-env up
+
+say "Starting wp-env (port ${WP_ENV_PORT})"
+perf_wp_env start --update
+
+perf_resolve_containers
+echo "  containers: ${PERF_PROJECT}-*"
+
+# wp-env maps directories reliably; single-file mappings are less consistent
+# across versions. Copy the drop-in in if the mapping did not take.
+say "Verifying object cache drop-in"
+if incli test -f wp-content/object-cache.php; then
+	echo "  object-cache.php present"
+else
+	docker cp tests/perf/drop-ins/object-cache.php \
+		"${PERF_WP_CONTAINER}:/var/www/html/wp-content/object-cache.php"
+	docker cp tests/perf/drop-ins/object-cache.php \
+		"${PERF_CLI_CONTAINER}:/var/www/html/wp-content/object-cache.php"
+	echo "  object-cache.php copied into the containers"
+fi
+
+for required in wp-content/mu-plugins/bpi-perf-probe.php wp-content/bpi-fixtures/manifest.json; do
+	if ! incli test -f "$required"; then
+		echo "Missing ${required} in the container — wp-env mappings did not apply." >&2
+		exit 1
+	fi
+done
+echo "  mu-plugins and fixtures mounted"
+
+# ------------------------------------------------------------- wp settings
+
+say "Configuring WordPress"
+wpcli theme activate blockparty-perf
+wpcli plugin activate blockparty-icons
+wpcli rewrite structure '/%postname%/' --hard
+wpcli option update blog_public 0
+
+# --------------------------------------------------------- media library
+
+WANT_MEDIA="$( node -e "const m=require('./tests/perf/fixtures/manifest.json');process.stdout.write(String(m.sets.media.count))" )"
+MEDIA_COUNT="$( wpcli post list --post_type=attachment --post_mime_type=image/svg+xml --format=count | tr -d '\r' )"
+
+if [ "$MEDIA_COUNT" -lt "$WANT_MEDIA" ]; then
+	say "Importing ${WANT_MEDIA} SVG icons into the media library (slowest step, a few minutes)"
+	incli bash -c 'wp media import /var/www/html/wp-content/bpi-fixtures/media-icons/*.svg --porcelain > /dev/null'
+	MEDIA_COUNT="$( wpcli post list --post_type=attachment --post_mime_type=image/svg+xml --format=count | tr -d '\r' )"
+else
+	say "Media library already holds ${MEDIA_COUNT} SVG attachments, skipping import"
+fi
+
+# --------------------------------------------------------------- content
+
+say "Creating benchmark pages"
+
+make_page() {
+	local slug="$1" title="$2" content="$3"
+	local existing
+	existing="$( wpcli post list --post_type=page --name="$slug" --format=count | tr -d '\r' )"
+	if [ "$existing" != "0" ]; then
+		echo "  ${slug} already exists"
+		return
+	fi
+	wpcli post create \
+		--post_type=page \
+		--post_status=publish \
+		--post_name="$slug" \
+		--post_title="$title" \
+		--post_content="$content" \
+		--porcelain > /dev/null
+	echo "  ${slug} created"
+}
+
+ONE_ICON='<!-- wp:blockparty/icon {"icon":{"label":"theme-icon-001","name":"theme-icon-001","type":"raw","collection":"perf-theme"},"size":48} /-->'
+
+MANY_ICONS="$( node -e '
+const m = require("./tests/perf/fixtures/manifest.json");
+process.stdout.write(
+  m.sets.theme.entries.slice(0, 20).map((e) =>
+    `<!-- wp:blockparty/icon {"icon":{"label":"${e.name}","name":"${e.name}","type":"raw","collection":"perf-theme"},"size":32} /-->`
+  ).join("\n")
+);
+' )"
+
+make_page "perf-empty"  "Perf - no icon block"  '<!-- wp:paragraph --><p>No icon on this page.</p><!-- /wp:paragraph -->'
+make_page "perf-single" "Perf - one icon block" "$ONE_ICON"
+make_page "perf-many"   "Perf - twenty icons"   "$MANY_ICONS"
+
+# ---------------------------------------------------------------- summary
+
+say "Verifying registered collections"
+wpcli cache flush > /dev/null 2>&1 || true
+wpcli eval '
+$c = \Blockparty\Icons\get_icon_collections();
+$total = 0;
+foreach ( $c as $name => $col ) {
+	printf( "  %-12s %4d icons\n", $name, $col->count() );
+	$total += $col->count();
+}
+printf( "  %-12s %4d icons\n", "TOTAL", $total );
+'
+
+cat <<EOF
+
+Environment ready.
+
+  site   ${PERF_BASE}
+  admin  ${PERF_BASE}/wp-admin  (admin / password)
+  pages  /perf-empty/  /perf-single/  /perf-many/
+  media  ${MEDIA_COUNT} SVG attachments
+
+Next:
+  tests/perf/bin/bench.sh --label=baseline
+EOF
diff --git a/tests/perf/bin/teardown.sh b/tests/perf/bin/teardown.sh
new file mode 100755
index 0000000..ea76fa5
--- /dev/null
+++ b/tests/perf/bin/teardown.sh
@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+#
+# Destroy the perf environment. Fixtures and captured results are kept.
+#
+#   tests/perf/bin/teardown.sh [--purge-fixtures]
+#
+set -euo pipefail
+
+# shellcheck source=tests/perf/bin/_env.sh
+source "$( dirname "${BASH_SOURCE[0]}" )/_env.sh"
+
+say "Destroying the perf environment"
+perf_wp_env destroy || true
+
+if [ "${1:-}" = "--purge-fixtures" ]; then
+	say "Removing generated fixtures"
+	rm -rf "${PERF_ROOT}/tests/perf/fixtures"
+fi
+
+echo "Done."
diff --git a/tests/perf/drop-ins/object-cache.php b/tests/perf/drop-ins/object-cache.php
new file mode 100644
index 0000000..21eb753
--- /dev/null
+++ b/tests/perf/drop-ins/object-cache.php
@@ -0,0 +1,477 @@
+<?php
+/**
+ * Instrumented persistent object cache drop-in for the Blockparty Icons perf protocol.
+ *
+ * Purpose: reproduce the WordPress VIP failure mode locally.
+ *
+ * VIP runs memcached, which silently refuses any item larger than 1 MB. WordPress'
+ * cache API gives no feedback for that: `wp_cache_set()` returns false and every
+ * caller in this plugin ignores the return value. The result is a cache that never
+ * warms up -- each request pays the full cost of rebuilding the collection.
+ *
+ * This drop-in is file-backed rather than memcached-backed. That is deliberate:
+ *   - it needs no extra container or PHP extension in wp-env
+ *   - it reproduces the *semantics* exactly (persistence, 1 MB cap, silent failure)
+ *
+ * It does NOT reproduce memcached's latency. Local file I/O is much faster than a
+ * network round trip. Therefore the protocol treats **operation counts** as the
+ * primary metric and wall time as indicative only. See tests/perf/README.md.
+ *
+ * Tunables (define in wp-config.php or via the probe):
+ *   BPI_OC_MAX_ITEM_BYTES  per-item ceiling in bytes. Default 1048576 (memcached default).
+ *   BPI_OC_DIR             storage directory.
+ *   BPI_OC_DISABLED        set true to behave as a non-persistent cache.
+ */
+
+defined( 'ABSPATH' ) || exit;
+
+if ( ! defined( 'BPI_OC_MAX_ITEM_BYTES' ) ) {
+	define( 'BPI_OC_MAX_ITEM_BYTES', 1048576 );
+}
+
+if ( ! defined( 'BPI_OC_DIR' ) ) {
+	define( 'BPI_OC_DIR', WP_CONTENT_DIR . '/bpi-object-cache' );
+}
+
+/**
+ * Per-request counters. Read by the perf probe on shutdown.
+ *
+ * @var array
+ */
+$GLOBALS['bpi_oc_stats'] = [
+	'get'             => 0,
+	'get_hit'         => 0,
+	'get_miss'        => 0,
+	'get_runtime_hit' => 0,
+	'set'             => 0,
+	'set_ok'          => 0,
+	'set_rejected'    => 0,
+	'delete'          => 0,
+	'bytes_read'      => 0,
+	'bytes_written'   => 0,
+	'bytes_rejected'  => 0,
+	'largest_reject'  => 0,
+	'rejects'         => [], // group:key => bytes
+	'by_group'        => [], // group => [get, hit, miss, set_ok, set_rejected]
+];
+
+class BPI_Perf_Object_Cache {
+
+	/** @var array Runtime (single request) cache. */
+	private $runtime = [];
+
+	/** @var array Groups that must never be written to disk. */
+	private $non_persistent = [];
+
+	/** @var array Groups shared across sites. */
+	private $global_groups = [];
+
+	/** @var int */
+	private $blog_id = 1;
+
+	/** @var bool */
+	private $persistent = true;
+
+	public function __construct() {
+		$this->persistent = ! ( defined( 'BPI_OC_DISABLED' ) && BPI_OC_DISABLED );
+		$this->blog_id    = function_exists( 'get_current_blog_id' ) ? 1 : 1;
+
+		if ( $this->persistent && ! is_dir( BPI_OC_DIR ) ) {
+			@mkdir( BPI_OC_DIR, 0777, true );
+		}
+	}
+
+	/* ---------------------------------------------------------------- keys */
+
+	private function full_key( $key, $group ) {
+		$group = $group ?: 'default';
+		$scope = isset( $this->global_groups[ $group ] ) ? 'global' : $this->blog_id;
+
+		return $scope . ':' . $group . ':' . $key;
+	}
+
+	private function path( $full_key ) {
+		return BPI_OC_DIR . '/' . md5( $full_key ) . '.cache';
+	}
+
+	private function &group_stats( $group ) {
+		$group = $group ?: 'default';
+		if ( ! isset( $GLOBALS['bpi_oc_stats']['by_group'][ $group ] ) ) {
+			$GLOBALS['bpi_oc_stats']['by_group'][ $group ] = [
+				'get'          => 0,
+				'hit'          => 0,
+				'miss'         => 0,
+				'set_ok'       => 0,
+				'set_rejected' => 0,
+				'bytes_read'   => 0,
+			];
+		}
+
+		return $GLOBALS['bpi_oc_stats']['by_group'][ $group ];
+	}
+
+	/* --------------------------------------------------------------- reads */
+
+	public function get( $key, $group = 'default', $force = false, &$found = null ) {
+		$group    = $group ?: 'default';
+		$full_key = $this->full_key( $key, $group );
+
+		$GLOBALS['bpi_oc_stats']['get']++;
+		$gs = &$this->group_stats( $group );
+		$gs['get']++;
+
+		if ( ! $force && array_key_exists( $full_key, $this->runtime ) ) {
+			$found = true;
+			$GLOBALS['bpi_oc_stats']['get_hit']++;
+			$GLOBALS['bpi_oc_stats']['get_runtime_hit']++;
+			$gs['hit']++;
+
+			return $this->clone_value( $this->runtime[ $full_key ] );
+		}
+
+		if ( ! $this->persistent || isset( $this->non_persistent[ $group ] ) ) {
+			$found = false;
+			$GLOBALS['bpi_oc_stats']['get_miss']++;
+			$gs['miss']++;
+
+			return false;
+		}
+
+		$path = $this->path( $full_key );
+		if ( ! is_readable( $path ) ) {
+			$found = false;
+			$GLOBALS['bpi_oc_stats']['get_miss']++;
+			$gs['miss']++;
+
+			return false;
+		}
+
+		$raw = file_get_contents( $path );
+		if ( false === $raw ) {
+			$found = false;
+			$GLOBALS['bpi_oc_stats']['get_miss']++;
+			$gs['miss']++;
+
+			return false;
+		}
+
+		$GLOBALS['bpi_oc_stats']['bytes_read'] += strlen( $raw );
+		$gs['bytes_read']                      += strlen( $raw );
+
+		$envelope = @unserialize( $raw ); // phpcs:ignore WordPress.PHP.NoSilencedErrors
+		if ( ! is_array( $envelope ) || ! array_key_exists( 'data', $envelope ) ) {
+			$found = false;
+			$GLOBALS['bpi_oc_stats']['get_miss']++;
+			$gs['miss']++;
+
+			return false;
+		}
+
+		if ( ! empty( $envelope['expire'] ) && $envelope['expire'] < time() ) {
+			@unlink( $path ); // phpcs:ignore WordPress.PHP.NoSilencedErrors
+			$found = false;
+			$GLOBALS['bpi_oc_stats']['get_miss']++;
+			$gs['miss']++;
+
+			return false;
+		}
+
+		$this->runtime[ $full_key ] = $envelope['data'];
+
+		$found = true;
+		$GLOBALS['bpi_oc_stats']['get_hit']++;
+		$gs['hit']++;
+
+		return $this->clone_value( $envelope['data'] );
+	}
+
+	public function get_multiple( $keys, $group = 'default', $force = false ) {
+		$out = [];
+		foreach ( (array) $keys as $key ) {
+			$out[ $key ] = $this->get( $key, $group, $force );
+		}
+
+		return $out;
+	}
+
+	/* -------------------------------------------------------------- writes */
+
+	public function set( $key, $data, $group = 'default', $expire = 0 ) {
+		$group    = $group ?: 'default';
+		$full_key = $this->full_key( $key, $group );
+
+		$GLOBALS['bpi_oc_stats']['set']++;
+		$gs = &$this->group_stats( $group );
+
+		// Runtime cache always accepts, exactly like memcached-backed drop-ins.
+		$this->runtime[ $full_key ] = $data;
+
+		if ( ! $this->persistent || isset( $this->non_persistent[ $group ] ) ) {
+			$GLOBALS['bpi_oc_stats']['set_ok']++;
+			$gs['set_ok']++;
+
+			return true;
+		}
+
+		$payload = serialize( // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions
+			[
+				'data'   => $data,
+				'expire' => $expire ? time() + (int) $expire : 0,
+			]
+		);
+		$size    = strlen( $payload );
+
+		// This is the VIP behaviour we are reproducing: memcached refuses the item,
+		// wp_cache_set() returns false, and nothing in the calling code notices.
+		if ( $size > BPI_OC_MAX_ITEM_BYTES ) {
+			$GLOBALS['bpi_oc_stats']['set_rejected']++;
+			$GLOBALS['bpi_oc_stats']['bytes_rejected'] += $size;
+			$GLOBALS['bpi_oc_stats']['largest_reject']  = max(
+				$GLOBALS['bpi_oc_stats']['largest_reject'],
+				$size
+			);
+			$GLOBALS['bpi_oc_stats']['rejects'][ $group . ':' . $key ] = $size;
+			$gs['set_rejected']++;
+
+			return false;
+		}
+
+		$ok = false !== file_put_contents( $this->path( $full_key ), $payload, LOCK_EX ); // phpcs:ignore WordPress.WP.AlternativeFunctions
+
+		if ( $ok ) {
+			$GLOBALS['bpi_oc_stats']['set_ok']++;
+			$GLOBALS['bpi_oc_stats']['bytes_written'] += $size;
+			$gs['set_ok']++;
+		}
+
+		return $ok;
+	}
+
+	public function set_multiple( $data, $group = 'default', $expire = 0 ) {
+		$out = [];
+		foreach ( (array) $data as $key => $value ) {
+			$out[ $key ] = $this->set( $key, $value, $group, $expire );
+		}
+
+		return $out;
+	}
+
+	public function add( $key, $data, $group = 'default', $expire = 0 ) {
+		if ( function_exists( 'wp_suspend_cache_addition' ) && wp_suspend_cache_addition() ) {
+			return false;
+		}
+
+		$found = null;
+		$this->get( $key, $group, false, $found );
+		if ( $found ) {
+			return false;
+		}
+
+		return $this->set( $key, $data, $group, $expire );
+	}
+
+	public function add_multiple( array $data, $group = 'default', $expire = 0 ) {
+		$out = [];
+		foreach ( $data as $key => $value ) {
+			$out[ $key ] = $this->add( $key, $value, $group, $expire );
+		}
+
+		return $out;
+	}
+
+	public function replace( $key, $data, $group = 'default', $expire = 0 ) {
+		$found = null;
+		$this->get( $key, $group, false, $found );
+		if ( ! $found ) {
+			return false;
+		}
+
+		return $this->set( $key, $data, $group, $expire );
+	}
+
+	public function delete( $key, $group = 'default' ) {
+		$group    = $group ?: 'default';
+		$full_key = $this->full_key( $key, $group );
+
+		$GLOBALS['bpi_oc_stats']['delete']++;
+		unset( $this->runtime[ $full_key ] );
+
+		if ( ! $this->persistent ) {
+			return true;
+		}
+
+		$path = $this->path( $full_key );
+
+		return is_file( $path ) ? @unlink( $path ) : false; // phpcs:ignore WordPress.PHP.NoSilencedErrors
+	}
+
+	public function delete_multiple( array $keys, $group = 'default' ) {
+		$out = [];
+		foreach ( $keys as $key ) {
+			$out[ $key ] = $this->delete( $key, $group );
+		}
+
+		return $out;
+	}
+
+	public function incr( $key, $offset = 1, $group = 'default' ) {
+		$found = null;
+		$value = $this->get( $key, $group, false, $found );
+		if ( ! $found || ! is_numeric( $value ) ) {
+			return false;
+		}
+
+		$value = max( 0, (int) $value + (int) $offset );
+		$this->set( $key, $value, $group );
+
+		return $value;
+	}
+
+	public function decr( $key, $offset = 1, $group = 'default' ) {
+		return $this->incr( $key, -abs( (int) $offset ), $group );
+	}
+
+	/* --------------------------------------------------------------- admin */
+
+	public function flush() {
+		$this->runtime = [];
+
+		if ( ! $this->persistent || ! is_dir( BPI_OC_DIR ) ) {
+			return true;
+		}
+
+		foreach ( (array) glob( BPI_OC_DIR . '/*.cache' ) as $file ) {
+			@unlink( $file ); // phpcs:ignore WordPress.PHP.NoSilencedErrors
+		}
+
+		return true;
+	}
+
+	public function flush_runtime() {
+		$this->runtime = [];
+
+		return true;
+	}
+
+	public function flush_group( $group ) {
+		// Coarse but sufficient for the protocol: we never need surgical group flushes.
+		return $this->flush();
+	}
+
+	public function add_global_groups( $groups ) {
+		foreach ( (array) $groups as $group ) {
+			$this->global_groups[ $group ] = true;
+		}
+	}
+
+	public function add_non_persistent_groups( $groups ) {
+		foreach ( (array) $groups as $group ) {
+			$this->non_persistent[ $group ] = true;
+		}
+	}
+
+	public function switch_to_blog( $blog_id ) {
+		$this->blog_id = (int) $blog_id;
+	}
+
+	public function close() {
+		return true;
+	}
+
+	/**
+	 * WordPress expects values to be returned by value, not by reference.
+	 */
+	private function clone_value( $value ) {
+		if ( is_object( $value ) ) {
+			return clone $value;
+		}
+
+		return $value;
+	}
+}
+
+/* ------------------------------------------------------------- API shims */
+
+function wp_cache_init() {
+	$GLOBALS['wp_object_cache'] = new BPI_Perf_Object_Cache();
+}
+
+function wp_cache_add( $key, $data, $group = '', $expire = 0 ) {
+	return $GLOBALS['wp_object_cache']->add( $key, $data, $group, (int) $expire );
+}
+
+function wp_cache_add_multiple( array $data, $group = '', $expire = 0 ) {
+	return $GLOBALS['wp_object_cache']->add_multiple( $data, $group, (int) $expire );
+}
+
+function wp_cache_replace( $key, $data, $group = '', $expire = 0 ) {
+	return $GLOBALS['wp_object_cache']->replace( $key, $data, $group, (int) $expire );
+}
+
+function wp_cache_set( $key, $data, $group = '', $expire = 0 ) {
+	return $GLOBALS['wp_object_cache']->set( $key, $data, $group, (int) $expire );
+}
+
+function wp_cache_set_multiple( array $data, $group = '', $expire = 0 ) {
+	return $GLOBALS['wp_object_cache']->set_multiple( $data, $group, (int) $expire );
+}
+
+function wp_cache_get( $key, $group = '', $force = false, &$found = null ) {
+	return $GLOBALS['wp_object_cache']->get( $key, $group, $force, $found );
+}
+
+function wp_cache_get_multiple( $keys, $group = '', $force = false ) {
+	return $GLOBALS['wp_object_cache']->get_multiple( $keys, $group, $force );
+}
+
+function wp_cache_delete( $key, $group = '' ) {
+	return $GLOBALS['wp_object_cache']->delete( $key, $group );
+}
+
+function wp_cache_delete_multiple( array $keys, $group = '' ) {
+	return $GLOBALS['wp_object_cache']->delete_multiple( $keys, $group );
+}
+
+function wp_cache_incr( $key, $offset = 1, $group = '' ) {
+	return $GLOBALS['wp_object_cache']->incr( $key, $offset, $group );
+}
+
+function wp_cache_decr( $key, $offset = 1, $group = '' ) {
+	return $GLOBALS['wp_object_cache']->decr( $key, $offset, $group );
+}
+
+function wp_cache_flush() {
+	return $GLOBALS['wp_object_cache']->flush();
+}
+
+function wp_cache_flush_runtime() {
+	return $GLOBALS['wp_object_cache']->flush_runtime();
+}
+
+function wp_cache_flush_group( $group ) {
+	return $GLOBALS['wp_object_cache']->flush_group( $group );
+}
+
+function wp_cache_close() {
+	return $GLOBALS['wp_object_cache']->close();
+}
+
+function wp_cache_add_global_groups( $groups ) {
+	$GLOBALS['wp_object_cache']->add_global_groups( $groups );
+}
+
+function wp_cache_add_non_persistent_groups( $groups ) {
+	$GLOBALS['wp_object_cache']->add_non_persistent_groups( $groups );
+}
+
+function wp_cache_switch_to_blog( $blog_id ) {
+	$GLOBALS['wp_object_cache']->switch_to_blog( $blog_id );
+}
+
+function wp_cache_supports( $feature ) {
+	return in_array(
+		$feature,
+		[ 'add_multiple', 'set_multiple', 'get_multiple', 'delete_multiple', 'flush_runtime', 'flush_group' ],
+		true
+	);
+}
diff --git a/tests/perf/env/.wp-env.json b/tests/perf/env/.wp-env.json
new file mode 100644
index 0000000..db003af
--- /dev/null
+++ b/tests/perf/env/.wp-env.json
@@ -0,0 +1,20 @@
+{
+	"plugins": [ "../../.." ],
+	"themes": [ "../theme/blockparty-perf" ],
+	"mappings": {
+		"wp-content/mu-plugins": "../mu-plugins",
+		"wp-content/bpi-fixtures": "../fixtures",
+		"wp-content/object-cache.php": "../drop-ins/object-cache.php"
+	},
+	"config": {
+		"WP_DEBUG": false,
+		"WP_DEBUG_DISPLAY": false,
+		"WP_DEBUG_LOG": false,
+		"SCRIPT_DEBUG": false,
+		"WP_DEVELOPMENT_MODE": "",
+		"WP_MEMORY_LIMIT": "512M",
+		"WP_MAX_MEMORY_LIMIT": "512M",
+		"BPI_OC_MAX_ITEM_BYTES": 1048576,
+		"BPI_PERF_TOKEN": "local-perf-harness-only"
+	}
+}
diff --git a/tests/perf/mu-plugins/bpi-perf-auth.php b/tests/perf/mu-plugins/bpi-perf-auth.php
new file mode 100644
index 0000000..6847eff
--- /dev/null
+++ b/tests/perf/mu-plugins/bpi-perf-auth.php
@@ -0,0 +1,70 @@
+<?php
+/**
+ * Plugin Name: Blockparty Icons — Perf Auth Shim
+ * Description: Test-only authentication bypass so the bench runner can hit editor and REST endpoints. NEVER ship this.
+ *
+ * The icons REST endpoints require `edit_posts`, and the block editor requires a
+ * logged-in user. Rather than juggling cookies or application passwords in the bench
+ * script, this shim authenticates a request that presents the shared token.
+ *
+ * The token comes from the BPI_PERF_TOKEN constant, set in .wp-env.perf.json. With no
+ * constant defined the shim is inert, so a stray copy of this file cannot open anything up.
+ */
+
+defined( 'ABSPATH' ) || exit;
+
+add_filter(
+	'determine_current_user',
+	function ( $user_id ) {
+		if ( $user_id ) {
+			return $user_id;
+		}
+
+		if ( ! defined( 'BPI_PERF_TOKEN' ) ) {
+			return $user_id;
+		}
+
+		$expected = (string) constant( 'BPI_PERF_TOKEN' );
+		if ( '' === $expected ) {
+			return $user_id;
+		}
+
+		$provided = '';
+		if ( isset( $_SERVER['HTTP_X_BPI_PERF_TOKEN'] ) ) {
+			$provided = (string) $_SERVER['HTTP_X_BPI_PERF_TOKEN'];
+		}
+
+		if ( '' === $provided || ! hash_equals( $expected, $provided ) ) {
+			return $user_id;
+		}
+
+		$admin = get_users(
+			[
+				'role'    => 'administrator',
+				'number'  => 1,
+				'fields'  => 'ID',
+				'orderby' => 'ID',
+				'order'   => 'ASC',
+			]
+		);
+
+		return empty( $admin ) ? $user_id : (int) $admin[0];
+	},
+	20
+);
+
+/**
+ * The REST cookie check fails without a nonce even when the user is resolved.
+ * Accept the resolved user for token-authenticated requests.
+ */
+add_filter(
+	'rest_authentication_errors',
+	function ( $result ) {
+		if ( ! empty( $_SERVER['HTTP_X_BPI_PERF_TOKEN'] ) && is_user_logged_in() ) {
+			return true;
+		}
+
+		return $result;
+	},
+	20
+);
diff --git a/tests/perf/mu-plugins/bpi-perf-probe.php b/tests/perf/mu-plugins/bpi-perf-probe.php
new file mode 100644
index 0000000..5e8bcec
--- /dev/null
+++ b/tests/perf/mu-plugins/bpi-perf-probe.php
@@ -0,0 +1,371 @@
+<?php
+/**
+ * Plugin Name: Blockparty Icons — Perf Probe
+ * Description: Instrumentation for the Blockparty Icons performance protocol. Not for production.
+ *
+ * Records, per request:
+ *   - peak memory, and memory consumed by the `blockparty_icons_init` hook alone
+ *   - bytes of SVG content held resident in the registered collections
+ *   - object cache operation counts (gets / hits / misses / rejected sets)
+ *   - media-library file reads and bytes, via the bpifs:// stream wrapper
+ *
+ * Metrics land as one JSON object per line in wp-content/bpi-perf.log.
+ *
+ * Tag a request with ?bpi_perf_label=my-scenario so the bench runner can group runs.
+ */
+
+defined( 'ABSPATH' ) || exit;
+
+if ( ! defined( 'BPI_PERF_LOG' ) ) {
+	define( 'BPI_PERF_LOG', WP_CONTENT_DIR . '/bpi-perf.log' );
+}
+
+/**
+ * Microseconds of artificial latency charged on every media-library file open, to
+ * emulate VIP Files (a network filesystem) rather than a local disk.
+ *
+ * Defaults to 0 so the baseline stays honest about what was actually measured.
+ * Override per request with ?bpi_perf_latency_us=2000 — 2 ms is a conservative
+ * stand-in for a VIP Files round trip.
+ */
+if ( ! defined( 'BPI_PERF_REMOTE_LATENCY_US' ) ) {
+	define( 'BPI_PERF_REMOTE_LATENCY_US', 0 );
+}
+
+/**
+ * Route media-library files through the counting stream wrapper.
+ * On VIP, get_attached_file() returns a vip:// path backed by remote storage.
+ */
+if ( ! defined( 'BPI_PERF_REMOTE_MEDIA' ) ) {
+	define( 'BPI_PERF_REMOTE_MEDIA', true );
+}
+
+/**
+ * Effective latency for this request: query override, else the constant.
+ */
+function bpi_perf_latency_us() {
+	static $us = null;
+
+	if ( null !== $us ) {
+		return $us;
+	}
+
+	$us = (int) BPI_PERF_REMOTE_LATENCY_US;
+
+	// phpcs:ignore WordPress.Security.NonceVerification
+	if ( isset( $_GET['bpi_perf_latency_us'] ) ) {
+		// phpcs:ignore WordPress.Security.NonceVerification
+		$us = max( 0, min( 100000, (int) $_GET['bpi_perf_latency_us'] ) );
+	}
+
+	return $us;
+}
+
+/* ------------------------------------------------------------------ state */
+
+$GLOBALS['bpi_perf'] = [
+	'label'            => isset( $_GET['bpi_perf_label'] ) // phpcs:ignore WordPress.Security.NonceVerification
+		? sanitize_text_field( wp_unslash( $_GET['bpi_perf_label'] ) ) // phpcs:ignore WordPress.Security.NonceVerification
+		: 'unlabelled',
+	'fs_reads'         => 0,
+	'fs_bytes'         => 0,
+	'fs_time_us'       => 0,
+	'hook_time_ms'     => null,
+	'hook_mem_bytes'   => null,
+	'mem_before_hook'  => null,
+];
+
+/* --------------------------------------------------- bpifs:// stream wrapper */
+
+/**
+ * Pass-through stream wrapper that counts reads and can add latency.
+ *
+ * Models VIP Files: the bytes live somewhere else and every open costs a round trip.
+ */
+class BPI_Perf_Stream_Wrapper {
+
+	/** @var resource|null */
+	public $context;
+
+	/** @var resource|false */
+	private $handle = false;
+
+	private function real_path( $path ) {
+		return substr( $path, strlen( 'bpifs://' ) );
+	}
+
+	private function charge_latency() {
+		$us = bpi_perf_latency_us();
+
+		if ( $us > 0 ) {
+			usleep( $us );
+			$GLOBALS['bpi_perf']['fs_time_us'] += $us;
+		}
+	}
+
+	public function stream_open( $path, $mode, $options, &$opened_path ) {
+		$real = $this->real_path( $path );
+
+		$this->charge_latency();
+		$GLOBALS['bpi_perf']['fs_reads']++;
+
+		$this->handle = @fopen( $real, $mode ); // phpcs:ignore WordPress.WP.AlternativeFunctions,WordPress.PHP.NoSilencedErrors
+
+		return false !== $this->handle;
+	}
+
+	public function stream_read( $count ) {
+		$data = fread( $this->handle, $count ); // phpcs:ignore WordPress.WP.AlternativeFunctions
+
+		if ( is_string( $data ) ) {
+			$GLOBALS['bpi_perf']['fs_bytes'] += strlen( $data );
+		}
+
+		return $data;
+	}
+
+	public function stream_write( $data ) {
+		return fwrite( $this->handle, $data ); // phpcs:ignore WordPress.WP.AlternativeFunctions
+	}
+
+	public function stream_tell() {
+		return ftell( $this->handle );
+	}
+
+	public function stream_eof() {
+		return feof( $this->handle );
+	}
+
+	public function stream_seek( $offset, $whence = SEEK_SET ) {
+		return 0 === fseek( $this->handle, $offset, $whence );
+	}
+
+	public function stream_stat() {
+		return fstat( $this->handle );
+	}
+
+	public function stream_close() {
+		if ( is_resource( $this->handle ) ) {
+			fclose( $this->handle ); // phpcs:ignore WordPress.WP.AlternativeFunctions
+		}
+
+		return true;
+	}
+
+	public function stream_flush() {
+		return is_resource( $this->handle ) ? fflush( $this->handle ) : true;
+	}
+
+	public function unlink( $path ) {
+		return @unlink( $this->real_path( $path ) ); // phpcs:ignore WordPress.PHP.NoSilencedErrors
+	}
+
+	public function url_stat( $path, $flags ) {
+		$real = $this->real_path( $path );
+
+		// is_readable() lands here. On a remote FS this is a round trip too.
+		$this->charge_latency();
+
+		$stat = ( $flags & STREAM_URL_STAT_QUIET )
+			? @stat( $real ) // phpcs:ignore WordPress.PHP.NoSilencedErrors
+			: stat( $real );
+
+		return false === $stat ? false : $stat;
+	}
+
+	public function dir_opendir( $path, $options ) {
+		return false;
+	}
+}
+
+if ( ! in_array( 'bpifs', stream_get_wrappers(), true ) ) {
+	stream_wrapper_register( 'bpifs', 'BPI_Perf_Stream_Wrapper' );
+}
+
+/**
+ * Make media-library SVGs behave like VIP Files: remote, counted, optionally slow.
+ */
+add_filter(
+	'get_attached_file',
+	function ( $file ) {
+		if ( ! BPI_PERF_REMOTE_MEDIA || ! is_string( $file ) || '' === $file ) {
+			return $file;
+		}
+
+		if ( 0 === strpos( $file, 'bpifs://' ) ) {
+			return $file;
+		}
+
+		if ( '.svg' !== strtolower( substr( $file, -4 ) ) ) {
+			return $file;
+		}
+
+		return 'bpifs://' . $file;
+	},
+	// Late, so the real path is resolved first.
+	9999
+);
+
+/* ----------------------------------------------------- hook timing/memory */
+
+add_action(
+	'blockparty_icons_init',
+	function () {
+		$GLOBALS['bpi_perf']['_hook_start_t'] = microtime( true );
+		$GLOBALS['bpi_perf']['_hook_start_m'] = memory_get_usage( true );
+		$GLOBALS['bpi_perf']['mem_before_hook'] = memory_get_usage( true );
+	},
+	-PHP_INT_MAX
+);
+
+add_action(
+	'blockparty_icons_init',
+	function () {
+		if ( ! isset( $GLOBALS['bpi_perf']['_hook_start_t'] ) ) {
+			return;
+		}
+
+		$GLOBALS['bpi_perf']['hook_time_ms'] = round(
+			( microtime( true ) - $GLOBALS['bpi_perf']['_hook_start_t'] ) * 1000,
+			2
+		);
+		$GLOBALS['bpi_perf']['hook_mem_bytes'] = memory_get_usage( true ) - $GLOBALS['bpi_perf']['_hook_start_m'];
+	},
+	PHP_INT_MAX
+);
+
+/* ------------------------------------------------- resident content bytes */
+
+/**
+ * Sum the SVG payload currently held in memory by the registered collections.
+ *
+ * Uses reflection on CollectionItem's private properties rather than the content()
+ * getter on purpose: once content loading is made lazy, calling content() would
+ * force every icon to load and destroy the very thing we are measuring.
+ *
+ * @return array{collections:int, items:int, resident_bytes:int}
+ */
+function bpi_perf_collect_resident() {
+	$out = [
+		'collections'    => 0,
+		'items'          => 0,
+		'resident_bytes' => 0,
+	];
+
+	if ( ! function_exists( 'Blockparty\Icons\get_icon_collections' ) ) {
+		return $out;
+	}
+
+	$collections = \Blockparty\Icons\get_icon_collections();
+	$out['collections'] = count( $collections );
+
+	foreach ( $collections as $collection ) {
+		if ( ! is_object( $collection ) || ! method_exists( $collection, 'all' ) ) {
+			continue;
+		}
+
+		foreach ( $collection->all() as $item ) {
+			$out['items']++;
+
+			if ( ! is_object( $item ) ) {
+				continue;
+			}
+
+			try {
+				$ref = new ReflectionObject( $item );
+				foreach ( $ref->getProperties() as $prop ) {
+					$prop->setAccessible( true );
+
+					if ( ! $prop->isInitialized( $item ) ) {
+						continue;
+					}
+
+					$value = $prop->getValue( $item );
+					if ( is_string( $value ) ) {
+						$out['resident_bytes'] += strlen( $value );
+					}
+				}
+			} catch ( \Throwable $e ) { // phpcs:ignore Generic.CodeAnalysis.EmptyStatement
+				// Ignore: measurement must never break the request.
+			}
+		}
+	}
+
+	return $out;
+}
+
+/* ------------------------------------------------------------- reporting */
+
+add_action(
+	'shutdown',
+	function () {
+		// WP-CLI bootstraps WordPress too (the bench flushes the cache that way).
+		// Those invocations are not requests under test.
+		if ( defined( 'WP_CLI' ) && WP_CLI ) {
+			return;
+		}
+
+		$perf     = $GLOBALS['bpi_perf'];
+		$oc       = isset( $GLOBALS['bpi_oc_stats'] ) ? $GLOBALS['bpi_oc_stats'] : [];
+		$resident = bpi_perf_collect_resident();
+
+		$start = defined( 'WP_START_TIMESTAMP' )
+			? WP_START_TIMESTAMP
+			: ( $_SERVER['REQUEST_TIME_FLOAT'] ?? microtime( true ) );
+
+		$icons_group = $oc['by_group']['blockparty-icons'] ?? [];
+
+		$record = [
+			'ts'    => gmdate( 'c' ),
+			'label' => $perf['label'],
+			'uri'   => $_SERVER['REQUEST_URI'] ?? '',
+			'ctx'   => ( defined( 'REST_REQUEST' ) && REST_REQUEST ) ? 'rest' : ( is_admin() ? 'admin' : 'front' ),
+
+			// Headline numbers.
+			'wall_ms'        => round( ( microtime( true ) - $start ) * 1000, 2 ),
+			'peak_mem_mb'    => round( memory_get_peak_usage( true ) / 1048576, 2 ),
+			'hook_ms'        => $perf['hook_time_ms'],
+			'hook_mem_mb'    => null === $perf['hook_mem_bytes']
+				? null
+				: round( $perf['hook_mem_bytes'] / 1048576, 2 ),
+
+			// The direct measure of "how much SVG are we holding for nothing".
+			'collections'    => $resident['collections'],
+			'items'          => $resident['items'],
+			'resident_mb'    => round( $resident['resident_bytes'] / 1048576, 3 ),
+
+			// Remote (media library) filesystem cost.
+			'fs_reads'       => $perf['fs_reads'],
+			'fs_mb'          => round( $perf['fs_bytes'] / 1048576, 2 ),
+			'fs_latency_ms'  => round( $perf['fs_time_us'] / 1000, 1 ),
+
+			// Object cache behaviour.
+			'oc_get'         => $oc['get'] ?? 0,
+			'oc_hit'         => $oc['get_hit'] ?? 0,
+			'oc_miss'        => $oc['get_miss'] ?? 0,
+			'oc_set_ok'      => $oc['set_ok'] ?? 0,
+			'oc_rejected'    => $oc['set_rejected'] ?? 0,
+			'oc_reject_mb'   => round( ( $oc['bytes_rejected'] ?? 0 ) / 1048576, 2 ),
+			'oc_biggest_mb'  => round( ( $oc['largest_reject'] ?? 0 ) / 1048576, 2 ),
+
+			// Same, scoped to the plugin's own cache group.
+			'icons_oc_get'      => $icons_group['get'] ?? 0,
+			'icons_oc_hit'      => $icons_group['hit'] ?? 0,
+			'icons_oc_miss'     => $icons_group['miss'] ?? 0,
+			'icons_oc_set_ok'   => $icons_group['set_ok'] ?? 0,
+			'icons_oc_rejected' => $icons_group['set_rejected'] ?? 0,
+		];
+
+		// Keep the rejected-key list: it names exactly which cache entries are too big.
+		if ( ! empty( $oc['rejects'] ) ) {
+			$record['rejected_keys'] = $oc['rejects'];
+		}
+
+		file_put_contents( // phpcs:ignore WordPress.WP.AlternativeFunctions
+			BPI_PERF_LOG,
+			wp_json_encode( $record ) . "\n",
+			FILE_APPEND | LOCK_EX
+		);
+	},
+	PHP_INT_MAX
+);
diff --git a/tests/perf/theme/blockparty-perf/functions.php b/tests/perf/theme/blockparty-perf/functions.php
new file mode 100644
index 0000000..c4a5e91
--- /dev/null
+++ b/tests/perf/theme/blockparty-perf/functions.php
@@ -0,0 +1,133 @@
+<?php
+/**
+ * Fixture theme for the Blockparty Icons performance protocol.
+ *
+ * Reproduces the topology of the WordPress VIP site that exhibits the problem:
+ *
+ *   - `perf-theme`  : 200 icons in a folder shipped with the theme. On VIP theme
+ *                     files are local, so this collection reads the local disk.
+ *   - `perf-media`  : 300 icons contributed through the back office (media library).
+ *                     On VIP these live on VIP Files, a remote store. The perf probe
+ *                     routes get_attached_file() through bpifs:// so every read is
+ *                     counted and can be given realistic latency.
+ *
+ * The media-library registration below is copied from the pattern the plugin's own
+ * README and demo theme encourage. It is the code path point 5 of the audit targets.
+ */
+
+defined( 'ABSPATH' ) || exit;
+
+const BPI_PERF_FIXTURES = WP_CONTENT_DIR . '/bpi-fixtures';
+
+/**
+ * Allow SVG uploads so the 300 media-library icons can be contributed through the BO.
+ */
+add_filter(
+	'upload_mimes',
+	function ( $mimes ) {
+		$mimes['svg'] = 'image/svg+xml';
+
+		return $mimes;
+	}
+);
+
+/**
+ * WordPress refuses SVG uploads on a MIME/extension mismatch. Trust our own fixtures.
+ */
+add_filter(
+	'wp_check_filetype_and_ext',
+	function ( $data, $file, $filename ) {
+		if ( '.svg' === strtolower( substr( $filename, -4 ) ) ) {
+			$data['ext']  = 'svg';
+			$data['type'] = 'image/svg+xml';
+		}
+
+		return $data;
+	},
+	10,
+	3
+);
+
+add_action(
+	'blockparty_icons_init',
+	function () {
+		/*
+		 * Collection 1 — 200 icons from a theme folder (local filesystem).
+		 */
+		\Blockparty\Icons\register_icon_collection(
+			'perf-theme',
+			[
+				'label'  => 'Perf — theme folder',
+				'type'   => 'folder',
+				'source' => BPI_PERF_FIXTURES . '/theme-icons',
+			]
+		);
+
+		/*
+		 * Collection 2 — 300 icons contributed in the back office (media library).
+		 *
+		 * Two implementations, so the protocol can measure both:
+		 *
+		 *   attachments : the supported `type => attachments` collection. One query,
+		 *                 one cached index, content resolved on demand.
+		 *   legacy      : the pattern the plugin's README and demo theme used to
+		 *                 recommend — a WP_Query on every request, then one
+		 *                 from_file() call per attachment, each with its own cache key.
+		 *
+		 * Switch with:  wp option update bpi_perf_media_mode legacy
+		 */
+		if ( 'legacy' !== get_option( 'bpi_perf_media_mode', 'attachments' ) ) {
+			\Blockparty\Icons\register_icon_collection(
+				'perf-media',
+				[
+					'label' => 'Perf - media library',
+					'type'  => 'attachments',
+				]
+			);
+
+			return;
+		}
+
+		$query = new \WP_Query(
+			[
+				'post_type'      => 'attachment',
+				'post_status'    => 'inherit',
+				'post_mime_type' => 'image/svg+xml',
+				'posts_per_page' => 500, // phpcs:ignore WordPress.WP.PostsPerPage.posts_per_page_posts_per_page
+				'no_found_rows'  => true,
+			]
+		);
+
+		if ( ! $query->have_posts() ) {
+			return;
+		}
+
+		$media_collection = new \Blockparty\Icons\Icon\Collection(
+			'perf-media',
+			'Perf — media library'
+		);
+
+		foreach ( $query->posts as $svg ) {
+			$path = get_attached_file( $svg->ID );
+
+			if ( empty( $path ) ) {
+				continue;
+			}
+
+			try {
+				$items = \Blockparty\Icons\Icon\CollectionItemsFactory::from_file(
+					$path,
+					[
+						'name'  => $svg->post_name,
+						'label' => get_the_title( $svg ),
+					]
+				);
+				array_map( [ $media_collection, 'add' ], $items );
+			} catch ( \Exception $e ) { // phpcs:ignore Generic.CodeAnalysis.EmptyStatement
+				// Skip unreadable fixtures.
+			}
+		}
+
+		\Blockparty\Icons\register_icon_collection( $media_collection );
+	}
+);
diff --git a/tests/perf/theme/blockparty-perf/index.php b/tests/perf/theme/blockparty-perf/index.php
new file mode 100644
index 0000000..e1f4632
--- /dev/null
+++ b/tests/perf/theme/blockparty-perf/index.php
@@ -0,0 +1,24 @@
+<?php
+/**
+ * Minimal template. Kept deliberately bare so measurements reflect the plugin,
+ * not theme rendering work.
+ */
+defined( 'ABSPATH' ) || exit;
+?>
+<!doctype html>
+<html <?php language_attributes(); ?>>
+<head>
+	<meta charset="<?php bloginfo( 'charset' ); ?>">
+	<title><?php wp_title( '' ); ?></title>
+	<?php wp_head(); ?>
+</head>
+<body <?php body_class(); ?>>
+<?php
+while ( have_posts() ) {
+	the_post();
+	the_content();
+}
+wp_footer();
+?>
+</body>
+</html>
diff --git a/tests/perf/theme/blockparty-perf/style.css b/tests/perf/theme/blockparty-perf/style.css
new file mode 100644
index 0000000..f519471
--- /dev/null
+++ b/tests/perf/theme/blockparty-perf/style.css
@@ -0,0 +1,6 @@
+/*
+Theme Name: Blockparty Perf Fixture
+Description: Fixture theme for the Blockparty Icons performance protocol. Not for production.
+Version: 1.0.0
+Requires PHP: 8.1
+*/

From 9ca3e88363ecd2ed5317b088413d4f7f103028b4 Mon Sep 17 00:00:00 2001
From: Amaury Balmer <amaury@beapi.fr>
Date: Thu, 10 Sep 2026 15:21:55 +0200
Subject: [PATCH 2/6] perf(icons): load SVG payloads on demand instead of
 eagerly

With 500 icons totalling ~102 MB, every request held all of it in memory --
including a front-end page containing no icon block at all. At PHP's common
128 MB limit the plugin did not merely run slowly, it fatalled while serializing
a collection for the cache.

Three changes, measured with tests/perf against 500 icons on a cache that
refuses items over 1 MB:

1. Registering a collection now builds a lightweight index. CollectionItem holds
   a small serializable descriptor saying where its bytes live, and ContentLoader
   reads them the first time content() is called -- one icon to render a block,
   one page's worth to list a collection in the editor. __serialize() keeps
   resolved payloads out of the cached index so it cannot grow with use.

2. Payloads are cached individually, and Cache::set_cache() declines anything
   over 900 KB. Memcached (VIP and most managed hosts) refuses items above 1 MB
   and signals it only through a return value nothing checks, so an oversized
   entry was rebuilt, refused and rebuilt again forever. Sixteen entries were in
   that state in the baseline, including the whole 200-icon folder collection as
   a single entry, which meant re-reading all 200 files on every request. The
   ceiling is adjustable with the blockparty_icons_cache_max_item_bytes filter.

3. New `attachments` collection type for SVGs contributed through the media
   library: one query and one cached index, salted on the posts cache's
   last_changed so a newly uploaded icon appears at once. It replaces the pattern
   the README used to recommend -- a WP_Query plus a from_file() call per
   attachment -- which cost a query and a cache round trip per icon per request.

Cached index keys carry a format revision. A salt cannot do that job:
wp_cache_get_salted() unserializes the stored value before it compares salts, so
an entry written by an earlier release would be unserialized into the new class
shape before anything could reject it. Typed properties also gained defaults so
such an entry cannot leave one uninitialised.

Measured on 500 icons (median of 4 runs), front-end page with no icon block:
resident SVG 101.7 MB -> 0.015 MB, object-cache gets 301 -> 2, refused writes
16 -> 0, blockparty_icons_init 602 ms -> 2.3 ms. Charging 2 ms per media read to
emulate VIP Files, the same page on a cold cache goes 4806 ms -> 422 ms.

Not addressed here: the editor still bootstraps ~22 MB because
block_editor_rest_api_preload_paths inlines the first 50 icons of each
collection with their content.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .wp-env/themes/icon-block-theme/functions.php |  41 +----
 CHANGELOG.md                                  |   5 +
 README.md                                     |  54 ++++++-
 blockparty-icons.php                          |  15 +-
 includes/Helpers/Cache.php                    |  64 ++++++++
 includes/Icon/Collection.php                  |  17 ++
 includes/Icon/CollectionItem.php              | 106 +++++++++++-
 includes/Icon/CollectionItemsFactory.php      | 153 ++++++++++++++++--
 includes/Icon/ContentLoader.php               |  92 +++++++++++
 9 files changed, 496 insertions(+), 51 deletions(-)
 create mode 100644 includes/Icon/ContentLoader.php

diff --git a/.wp-env/themes/icon-block-theme/functions.php b/.wp-env/themes/icon-block-theme/functions.php
index 6a40cad..6e86efb 100644
--- a/.wp-env/themes/icon-block-theme/functions.php
+++ b/.wp-env/themes/icon-block-theme/functions.php
@@ -1,8 +1,6 @@
 <?php
 
 use function Blockparty\Icons\register_icon_collection;
-use Blockparty\Icons\Icon\Collection;
-use Blockparty\Icons\Icon\CollectionItemsFactory;
 
 add_filter( 'upload_mimes', 'wpc_mime_types' );
 
@@ -39,38 +37,15 @@ function wpc_mime_types( $mimes ) {
 		]
 	);
 
-	// Register collections with icons from media library.
-	$query = new \WP_Query(
+	// Register collections with icons from the media library.
+	//
+	// `attachments` runs a single query and caches one small index; the SVG payload
+	// of an icon is read only when that icon is actually rendered or listed.
+	register_icon_collection(
+		'mediatheque',
 		[
-			'post_type'      => 'attachment',
-			'post_status'    => 'inherit',
-			'post_mime_type' => 'image/svg+xml',
-			'posts_per_page' => 500, //phpcs:ignore WordPress.WP.PostsPerPage.posts_per_page_posts_per_page
-			'no_found_rows'  => true,
+			'label' => __( 'Media library', 'beapi-frontend-framework' ),
+			'type'  => 'attachments',
 		]
 	);
-
-	if ( $query->have_posts() ) {
-		$media_collection = new Collection( 'mediatheque', __( 'Media library', 'beapi-frontend-framework' ) );
-		foreach ( $query->posts as $svg ) {
-			$path = get_attached_file( $svg->ID );
-
-			if ( empty( $path ) ) {
-				continue;
-			}
-
-			try {
-				$items = CollectionItemsFactory::from_file(
-					$path,
-					[
-						'name'  => $svg->post_name,
-						'label' => get_the_title( $svg ),
-					]
-				);
-				array_map( [ $media_collection, 'add' ], $items );
-			} catch ( \Exception $e ) { // phpcs:ignore
-			}
-		}
-		register_icon_collection( $media_collection );
-	}
 } );
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bd1c62e..39e4829 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,11 @@ This plugin **doesn't run any sanitization on SVGs** before using them. Only use
 
 ### Unreleased
 
+- Load an icon's SVG only when it is used. Registering a collection now builds a lightweight index, so a front-end page no longer holds every icon of every collection in memory
+- Cache icon payloads individually, and skip the object cache for payloads over 900 KB. Memcached refuses items above 1 MB and reports it only through an unchecked return value, which made oversized collections rebuild on every request forever. Adjust with the `blockparty_icons_cache_max_item_bytes` filter
+- Add an `attachments` collection type for SVGs contributed through the media library: one query and one cached index, instead of a query plus a cache round trip per icon on every request
+- Version cached index keys, so entries written by an earlier release are never read back after an update
+- Add a reproducible performance protocol under `tests/perf`
 - Add a PHPUnit integration test suite covering every SVG source (folder, sprite, single file), the collection container, the registration API, front-end block rendering, both REST controllers, the object-cache wrapper and the KSES allowances — 176 tests. See `tests/README.md`
 - Run the suite in CI on PHP 8.1 through 8.4
 
diff --git a/README.md b/README.md
index 68af1d5..6024810 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,57 @@ add_action( 'blockparty_icons_init', 'register_collection' );
 
 This is an example for adding a SVG sprite as a source. If you want to add icons from a folder, change the `type` value to `folder` and the path of your `source` to `get_stylesheet_directory() . '/dist/icons/'` for example.
 
+## Icons contributed in the back office
+
+To offer the SVG files uploaded to the media library as a collection, use the `attachments` type:
+
+```php
+\Blockparty\Icons\register_icon_collection(
+    'mediatheque',
+    [
+        'label' => 'Media library',
+        'type'  => 'attachments',
+    ]
+);
+```
+
+This runs a single query and caches one compact index, invalidated as soon as any
+attachment changes. Pass extra `WP_Query` arguments through `query` to narrow the
+selection:
+
+```php
+\Blockparty\Icons\register_icon_collection(
+    'mediatheque',
+    [
+        'label' => 'Media library',
+        'type'  => 'attachments',
+        'query' => [ 'posts_per_page' => 1000 ],
+    ]
+);
+```
+
+Do **not** build such a collection by looping over attachments and calling
+`CollectionItemsFactory::from_file()` for each one. That costs a database query and
+one object-cache round trip per icon on every request, front end included.
+
+## Performance notes
+
+An icon's SVG payload is read only when it is actually needed — one icon when a block
+renders, one page's worth when the editor lists a collection. Registering a collection
+builds a lightweight index and reads no SVG at all.
+
+Payloads are cached individually rather than inside the collection, and payloads larger
+than 900 KB are not sent to the object cache: memcached (WordPress VIP and most managed
+hosts) refuses items over 1 MB and signals it only through a return value that nothing
+checks, which would otherwise mean rebuilding the same entry on every request forever.
+Raise or disable that ceiling on Redis or APCu:
+
+```php
+add_filter( 'blockparty_icons_cache_max_item_bytes', fn() => 5 * MB_IN_BYTES );
+```
+
+A reproducible benchmark for all of this lives in [`tests/perf`](tests/perf/README.md).
+
 ## Params
 
 | param     | description               |
@@ -41,7 +92,8 @@ This is an example for adding a SVG sprite as a source. If you want to add icons
 |-----------|---------------------------|
 | `label`   | Label of the collection.  |
 | `source`  | Path to the SVG sprite file or folder containing SVG files. |
-| `type`    | <ul><li>`sprite` for SVG sprite source.</li><li>`folder` for a folder containing SVG files.</li></ul> |
+| `type`    | <ul><li>`sprite` for SVG sprite source.</li><li>`folder` for a folder containing SVG files.</li><li>`attachments` for the SVG files in the media library.</li></ul> |
+| `query`   | Optional. For `attachments`, extra `WP_Query` arguments. |
 | `version` | Optional. Version string used for cache busting (e.g. theme version). When set, the sprite URL is appended with a `?v=...` query parameter. |
 
 ## How to develop
diff --git a/blockparty-icons.php b/blockparty-icons.php
index c294308..804737d 100644
--- a/blockparty-icons.php
+++ b/blockparty-icons.php
@@ -92,9 +92,10 @@ function preload_rest_endpoints( $paths ) {
  *   Optional. An array of additional arguments. Default empty array.
  *
  *   @type string      $label    Optional. A human friendly name for the collection.
- *   @type string      $type     Optional. The type of icons. Supported values are 'folder', 'sprite' or 'raw'.
- *   @type string      $source   Optional. The path to load the collection's icons. Depending on the 'type' can be a path to a folder or a SVG file.
+ *   @type string      $type     Optional. The type of icons. Supported values are 'folder', 'sprite', 'attachments' or 'raw'.
+ *   @type string      $source   Optional. The path to load the collection's icons. Depending on the 'type' can be a path to a folder or a SVG file. Unused for 'attachments'.
  *   @type array       $icon_map Optional. Use an array to override default labels for the icons.
+ *   @type array       $query    Optional. For 'attachments', extra WP_Query arguments.
  *   @type string|null $version  Optional. The collection version, use for cache busting in the sprite URL.
  * }
  *
@@ -125,6 +126,7 @@ function register_icon_collection( $name, array $args = [] ) {
 			'type'     => '',
 			'source'   => '',
 			'icon_map' => [],
+			'query'    => [],
 			'version'  => null,
 		]
 	);
@@ -144,6 +146,9 @@ function register_icon_collection( $name, array $args = [] ) {
 				$collection = false;
 			}
 			break;
+		case 'attachments':
+			$collection = Collection::from_attachments( $name, $args );
+			break;
 		/*case 'file':
 			try {
 				$collection = new Collection( $name, $args['label'] ?? null );
@@ -165,7 +170,7 @@ function register_icon_collection( $name, array $args = [] ) {
  * Add icons to an existing collection.
  *
  * @param string $collection_name The collection to add the icons to.
- * @param string $type            The type of icons. Supported values are 'folder', 'sprite' or 'raw'.
+ * @param string $type            The type of icons. Supported values are 'folder', 'sprite', 'file' or 'attachments'.
  * @param string $source          The path to load the collection's icons. Depending on the 'type' can be a path to a folder or a SVG file.
  * @param array  $args {
  *   Optional. An array of additional arguments. Default empty array.
@@ -187,6 +192,7 @@ function add_icons( string $collection_name, string $type, string $source, array
 		[
 			'label'    => '',
 			'icon_map' => [],
+			'query'    => [],
 			'version'  => null,
 		]
 	);
@@ -214,6 +220,9 @@ function add_icons( string $collection_name, string $type, string $source, array
 				return false;
 			}
 			break;
+		case 'attachments':
+			$items = CollectionItemsFactory::from_attachments( $args );
+			break;
 		default:
 			return false;
 	}
diff --git a/includes/Helpers/Cache.php b/includes/Helpers/Cache.php
index ecd4e5f..8c9ee27 100644
--- a/includes/Helpers/Cache.php
+++ b/includes/Helpers/Cache.php
@@ -4,6 +4,21 @@
 
 class Cache {
 
+	/**
+	 * Largest payload worth handing to the object cache, in bytes.
+	 *
+	 * Memcached — what WordPress VIP and most managed hosts run — refuses any item
+	 * over 1 MB and reports it only through a `false` return that nothing checks.
+	 * The effect is a cache that never warms: the entry is rebuilt, refused, and
+	 * rebuilt again on the next request, forever.
+	 *
+	 * We stay under the limit so the refusal never happens, leaving headroom for
+	 * the key and the backend's own framing. Redis and APCu tolerate far more;
+	 * raise it with the `blockparty_icons_cache_max_item_bytes` filter, or set 0
+	 * to disable the guard entirely.
+	 */
+	private const DEFAULT_MAX_ITEM_BYTES = 900000;
+
 	/**
 	 * Retrieves cached data if valid and unchanged.
 	 *
@@ -57,6 +72,11 @@ public static function set_cache( $cache_key, $data, $group, $salt, $expire = 0
 			return true;
 		}
 
+		// Do not pay for a write the backend is going to refuse.
+		if ( self::exceeds_max_item_bytes( $data ) ) {
+			return false;
+		}
+
 		if ( function_exists( 'wp_cache_set_salted' ) ) {
 			return wp_cache_set_salted( $cache_key, $data, $group, $salt, $expire );
 		}
@@ -73,6 +93,50 @@ public static function set_cache( $cache_key, $data, $group, $salt, $expire = 0
 		);
 	}
 
+	/**
+	 * The size ceiling in force for this site.
+	 *
+	 * @return int Bytes, or 0 when the guard is disabled.
+	 */
+	public static function max_item_bytes(): int {
+		/**
+		 * Filters the largest payload the plugin will hand to the object cache.
+		 *
+		 * Set to 0 to store items of any size — appropriate on Redis or APCu, where
+		 * there is no 1 MB per-item limit.
+		 *
+		 * @param int $bytes Default 900000.
+		 */
+		return max( 0, (int) apply_filters( 'blockparty_icons_cache_max_item_bytes', self::DEFAULT_MAX_ITEM_BYTES ) );
+	}
+
+	/**
+	 * Whether a payload is too large to be worth caching.
+	 *
+	 * @param mixed $data
+	 *
+	 * @return bool
+	 */
+	private static function exceeds_max_item_bytes( $data ): bool {
+		$max = self::max_item_bytes();
+		if ( 0 === $max ) {
+			return false;
+		}
+
+		// Icon payloads are strings, and measuring one is free.
+		if ( is_string( $data ) ) {
+			return strlen( $data ) > $max;
+		}
+
+		if ( is_scalar( $data ) || null === $data ) {
+			return false;
+		}
+
+		// Anything else has to be measured. The extra serialize() costs far less
+		// than rebuilding an uncacheable entry on every request.
+		return strlen( serialize( $data ) ) > $max; // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.serialize_serialize
+	}
+
 	private static function is_cache_disabled() {
 		if ( function_exists( 'wp_is_development_mode' ) ) {
 			return wp_is_development_mode( 'all' );
diff --git a/includes/Icon/Collection.php b/includes/Icon/Collection.php
index cb2f243..3a2e140 100644
--- a/includes/Icon/Collection.php
+++ b/includes/Icon/Collection.php
@@ -65,6 +65,23 @@ public static function from_sprite( string $name, string $path, array $args = []
 		return $collection;
 	}
 
+	/**
+	 * Create a new collection from the SVG attachments in the media library.
+	 *
+	 * @param string $name collection's name.
+	 * @param array $args collection's args. See CollectionItemsFactory::from_attachments().
+	 *
+	 * @return static
+	 */
+	public static function from_attachments( string $name, array $args = [] ): self {
+		$collection = new self( $name, $args['label'] ?? null );
+
+		$items = CollectionItemsFactory::from_attachments( $args );
+		array_map( [ $collection, 'add' ], $items );
+
+		return $collection;
+	}
+
 	public function __construct( string $name, $label = null ) {
 		$this->name  = $name;
 		$this->label = $label ?? $name;
diff --git a/includes/Icon/CollectionItem.php b/includes/Icon/CollectionItem.php
index f2c716f..9ae9e3f 100644
--- a/includes/Icon/CollectionItem.php
+++ b/includes/Icon/CollectionItem.php
@@ -8,14 +8,60 @@ class CollectionItem {
 	private ?string $label;
 	private string $type;
 	private ?string $version;
-	private string $content;
 
+	/**
+	 * Resolved SVG payload, or null while the item is still unresolved.
+	 *
+	 * @var string|null
+	 */
+	private ?string $content = null;
+
+	/**
+	 * Serializable descriptor saying where the payload can be read from.
+	 *
+	 * Null for items created with literal content. A plain array rather than a
+	 * closure so the item survives a round trip through the object cache.
+	 *
+	 * @var array|null
+	 */
+	private ?array $source = null;
+
+	/**
+	 * Create an item that already holds its content.
+	 *
+	 * @param string      $name
+	 * @param string      $type
+	 * @param string      $content
+	 * @param string|null $label
+	 * @param string|null $version
+	 */
 	public function __construct( string $name, string $type, string $content, ?string $label = null, ?string $version = null ) {
 		$this->name    = $name;
 		$this->type    = $type;
 		$this->content = $content;
 		$this->label   = $label ?? $name;
 		$this->version = $version;
+		$this->source  = null;
+	}
+
+	/**
+	 * Create an item whose content is read only when it is first needed.
+	 *
+	 * @param string      $name
+	 * @param string      $type
+	 * @param array       $source  Descriptor understood by ContentLoader.
+	 * @param string|null $label
+	 * @param string|null $version
+	 *
+	 * @return self
+	 */
+	public static function from_source( string $name, string $type, array $source, ?string $label = null, ?string $version = null ): self {
+		$item = new self( $name, $type, '', $label, $version );
+
+		$item->content = null;
+		$item->source  = $source;
+
+		return $item;
 	}
 
 	/**
@@ -48,12 +94,32 @@ public function type(): string {
 	/**
 	 * Get icon's content.
 	 *
+	 * For a deferred item this is where the SVG is actually read. The result is
+	 * memoized, so repeated calls within a request cost nothing.
+	 *
 	 * @return string
 	 */
 	public function content(): string {
+		if ( null === $this->content ) {
+			$this->content = null === $this->source
+				? ''
+				: ContentLoader::load( $this->source );
+		}
+
 		return $this->content;
 	}
 
+	/**
+	 * Whether the content is already in memory.
+	 *
+	 * Lets callers avoid triggering a read they do not need.
+	 *
+	 * @return bool
+	 */
+	public function is_resolved(): bool {
+		return null !== $this->content;
+	}
+
 	/**
 	 * Get icon's version.
 	 *
@@ -62,4 +128,42 @@ public function content(): string {
 	public function version(): ?string {
 		return $this->version;
 	}
+
+	/**
+	 * Keep resolved payloads out of the cached collection index.
+	 *
+	 * Without this, caching a collection after rendering a page would grow the
+	 * index by however many icons happened to be used, and eventually push it past
+	 * the object cache's per-item limit.
+	 *
+	 * @return array
+	 */
+	public function __serialize(): array {
+		return [
+			'name'    => $this->name,
+			'label'   => $this->label,
+			'type'    => $this->type,
+			'version' => $this->version,
+			'source'  => $this->source,
+			// Items with a source can always reload; only literal content is stored.
+			'content' => null === $this->source ? $this->content : null,
+		];
+	}
+
+	/**
+	 * @param array $data
+	 */
+	public function __unserialize( array $data ): void {
+		$this->name    = (string) ( $data['name'] ?? '' );
+		$this->label   = isset( $data['label'] ) ? (string) $data['label'] : $this->name;
+		$this->type    = (string) ( $data['type'] ?? 'raw' );
+		$this->version = $data['version'] ?? null;
+		$this->source  = $data['source'] ?? null;
+		$this->content = $data['content'] ?? null;
+
+		// An item with neither content nor a source would otherwise re-resolve forever.
+		if ( null === $this->content && null === $this->source ) {
+			$this->content = '';
+		}
+	}
 }
diff --git a/includes/Icon/CollectionItemsFactory.php b/includes/Icon/CollectionItemsFactory.php
index dd62873..41ff0dd 100644
--- a/includes/Icon/CollectionItemsFactory.php
+++ b/includes/Icon/CollectionItemsFactory.php
@@ -8,6 +8,37 @@ class CollectionItemsFactory {
 
 	private const CACHE_GROUP = 'blockparty-icons';
 
+	/**
+	 * Format revision of the cached index.
+	 *
+	 * Cached indexes hold serialized CollectionItem objects. Bump this whenever
+	 * their shape changes so that entries written by an earlier release are never
+	 * read back — the salt cannot do this job, because `wp_cache_get_salted()`
+	 * unserializes the stored value *before* it compares salts. Only a different
+	 * key keeps the two formats apart.
+	 */
+	private const CACHE_FORMAT = 'v2';
+
+	/**
+	 * Build a format-scoped cache key.
+	 *
+	 * @param string $key
+	 *
+	 * @return string
+	 */
+	private static function cache_key( string $key ): string {
+		return self::CACHE_FORMAT . ':' . $key;
+	}
+
+	/**
+	 * Salt component that invalidates cached indexes when the plugin is updated.
+	 *
+	 * @return string
+	 */
+	private static function cache_version(): string {
+		return defined( 'BLOCKPARTY_ICONS_VERSION' ) ? BLOCKPARTY_ICONS_VERSION : '0';
+	}
+
 	/**
 	 * Instantiate array of CollectionItem from a folder.
 	 *
@@ -18,8 +49,8 @@ class CollectionItemsFactory {
 	 * @throws CollectionCreationException
 	 */
 	public static function from_folder( string $folder, array $icon_map = [] ): array {
-		$cache_key = 'from_folder:' . $folder;
-		$salt      = md5( wp_json_encode( $icon_map ) );
+		$cache_key = self::cache_key( 'from_folder:' . $folder );
+		$salt      = [ md5( wp_json_encode( $icon_map ) ), self::cache_version() ];
 
 		$items = Cache::get_cache( $cache_key, self::CACHE_GROUP, $salt );
 		if ( is_array( $items ) ) {
@@ -34,14 +65,23 @@ public static function from_folder( string $folder, array $icon_map = [] ): arra
 		$items  = [];
 		$folder = trailingslashit( $folder );
 		foreach ( glob( $folder . '*.svg' ) as $svg ) {
-			$item_content = file_get_contents( $svg ); //phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents -- read local file
-			if ( ! $item_content ) {
+			// Skip empty files as before, but without reading their contents:
+			// the payload is loaded only if the icon is actually used.
+			if ( ! filesize( $svg ) ) {
 				continue;
 			}
 
 			$name    = pathinfo( $svg, PATHINFO_FILENAME );
 			$label   = $icon_map[ $name ] ?? $name;
-			$items[] = new CollectionItem( $name, 'raw', $item_content, $label );
+			$items[] = CollectionItem::from_source(
+				$name,
+				'raw',
+				[
+					'type' => 'file',
+					'path' => $svg,
+				],
+				$label
+			);
 		}
 
 		Cache::set_cache( $cache_key, $items, self::CACHE_GROUP, $salt, DAY_IN_SECONDS );
@@ -60,8 +100,8 @@ public static function from_folder( string $folder, array $icon_map = [] ): arra
 	 * @throws CollectionCreationException
 	 */
 	public static function from_sprite( string $path, array $icon_map = [], ?string $version = null ): array {
-		$cache_key = 'from_sprite:' . $path;
-		$salts     = [ md5( wp_json_encode( $icon_map ) ) ];
+		$cache_key = self::cache_key( 'from_sprite:' . $path );
+		$salts     = [ md5( wp_json_encode( $icon_map ) ), self::cache_version() ];
 		if ( $version ) {
 			$salts[] = $version;
 		}
@@ -113,8 +153,8 @@ public static function from_sprite( string $path, array $icon_map = [], ?string
 	 * @throws CollectionCreationException
 	 */
 	public static function from_file( string $path, array $args = [] ): array {
-		$cache_key = 'from_file:' . $path;
-		$salt      = md5( wp_json_encode( $args ) );
+		$cache_key = self::cache_key( 'from_file:' . $path );
+		$salt      = [ md5( wp_json_encode( $args ) ), self::cache_version() ];
 
 		$items = Cache::get_cache( $cache_key, self::CACHE_GROUP, $salt );
 		if ( is_array( $items ) ) {
@@ -134,9 +174,8 @@ public static function from_file( string $path, array $args = [] ): array {
 			]
 		);
 
-		$items        = [];
-		$item_content = file_get_contents( $path ); //phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents -- read local file
-		if ( ! $item_content ) {
+		$items = [];
+		if ( ! filesize( $path ) ) {
 			Cache::set_cache( $cache_key, $items, self::CACHE_GROUP, $salt, DAY_IN_SECONDS );
 
 			return $items;
@@ -144,13 +183,101 @@ public static function from_file( string $path, array $args = [] ): array {
 
 		$name    = $args['name'] ?? pathinfo( $path, PATHINFO_FILENAME );
 		$label   = $args['label'] ?? $name;
-		$items[] = new CollectionItem( $name, 'raw', $item_content, $label );
+		$items[] = CollectionItem::from_source(
+			$name,
+			'raw',
+			[
+				'type' => 'file',
+				'path' => $path,
+			],
+			$label
+		);
 
 		Cache::set_cache( $cache_key, $items, self::CACHE_GROUP, $salt, DAY_IN_SECONDS );
 
 		return $items;
 	}
 
+	/**
+	 * Instantiate array of CollectionItem from SVG attachments in the media library.
+	 *
+	 * Registering media-library icons one file at a time — a WP_Query followed by a
+	 * `from_file()` call per attachment — costs a database query and one cache
+	 * round trip per icon on every request. This builds the whole collection from a
+	 * single query and stores it as one small index, keyed on the posts cache's
+	 * `last_changed` value so contributing a new SVG in the back office invalidates
+	 * it immediately.
+	 *
+	 * @param array $args {
+	 *   Optional. An array of additional arguments. Default empty array.
+	 *
+	 *   @type array $icon_map Optional. Override labels, keyed by attachment slug.
+	 *   @type array $query    Optional. Extra WP_Query arguments, merged over the defaults.
+	 * }
+	 *
+	 * @return CollectionItem[]
+	 */
+	public static function from_attachments( array $args = [] ): array {
+		$args = (array) wp_parse_args(
+			$args,
+			[
+				'icon_map' => [],
+				'query'    => [],
+			]
+		);
+
+		$query_args = (array) wp_parse_args(
+			(array) $args['query'],
+			[
+				'post_type'      => 'attachment',
+				'post_status'    => 'inherit',
+				'post_mime_type' => 'image/svg+xml',
+				'posts_per_page' => 500, //phpcs:ignore WordPress.WP.PostsPerPage.posts_per_page_posts_per_page
+				'orderby'        => 'title',
+				'order'          => 'ASC',
+				'no_found_rows'  => true,
+			]
+		);
+
+		$cache_key = self::cache_key( 'from_attachments:' . md5( wp_json_encode( $query_args ) ) );
+		$salts     = [
+			md5( wp_json_encode( $args['icon_map'] ) ),
+			self::cache_version(),
+			// Any change to a post or attachment bumps this, so the index cannot go stale.
+			(string) wp_cache_get_last_changed( 'posts' ),
+		];
+
+		$items = Cache::get_cache( $cache_key, self::CACHE_GROUP, $salts );
+		if ( is_array( $items ) ) {
+			return $items;
+		}
+
+		// Only the fields needed to build the index.
+		$query_args['fields'] = 'all';
+
+		$query = new \WP_Query( $query_args );
+
+		$items = [];
+		foreach ( $query->posts as $attachment ) {
+			$name  = $attachment->post_name;
+			$label = $args['icon_map'][ $name ] ?? get_the_title( $attachment );
+
+			$items[] = CollectionItem::from_source(
+				$name,
+				'raw',
+				[
+					'type' => 'attachment',
+					'id'   => (int) $attachment->ID,
+				],
+				$label
+			);
+		}
+
+		Cache::set_cache( $cache_key, $items, self::CACHE_GROUP, $salts, DAY_IN_SECONDS );
+
+		return $items;
+	}
+
 	/**
 	 * Format SVG name from its id attribute.
 	 *
diff --git a/includes/Icon/ContentLoader.php b/includes/Icon/ContentLoader.php
new file mode 100644
index 0000000..493ebb7
--- /dev/null
+++ b/includes/Icon/ContentLoader.php
@@ -0,0 +1,92 @@
+<?php
+
+namespace Blockparty\Icons\Icon;
+
+use Blockparty\Icons\Helpers\Cache;
+
+/**
+ * Resolves an icon's SVG payload on demand.
+ *
+ * Collections hold a lightweight index — name, label, type and a small descriptor
+ * saying where the bytes live. The bytes themselves are only read when something
+ * actually asks for them: one icon when rendering a block, one page's worth when
+ * the editor lists a collection.
+ *
+ * Payloads are cached individually rather than as part of the collection, so a
+ * single oversized icon cannot make a whole collection uncacheable.
+ */
+final class ContentLoader {
+
+	private const CACHE_GROUP = 'blockparty-icons-content';
+
+	/**
+	 * Load the SVG payload described by a source descriptor.
+	 *
+	 * @param array $source Descriptor produced by CollectionItemsFactory.
+	 *
+	 * @return string SVG markup, or an empty string when it cannot be read.
+	 */
+	public static function load( array $source ): string {
+		$path = self::resolve_path( $source );
+		if ( null === $path ) {
+			return '';
+		}
+
+		$cache_key = 'content:' . md5( $path );
+		$salt      = defined( 'BLOCKPARTY_ICONS_VERSION' ) ? BLOCKPARTY_ICONS_VERSION : '0';
+
+		$cached = Cache::get_cache( $cache_key, self::CACHE_GROUP, $salt );
+		if ( is_string( $cached ) ) {
+			return $cached;
+		}
+
+		if ( ! is_readable( $path ) ) {
+			return '';
+		}
+
+		$content = file_get_contents( $path ); //phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents -- read local file
+		if ( ! is_string( $content ) ) {
+			return '';
+		}
+
+		/*
+		 * Cache::set_cache() declines payloads the object cache would refuse anyway,
+		 * so an icon larger than the backend's item limit simply stays uncached
+		 * instead of failing a write on every single request.
+		 */
+		Cache::set_cache( $cache_key, $content, self::CACHE_GROUP, $salt, DAY_IN_SECONDS );
+
+		return $content;
+	}
+
+	/**
+	 * Turn a source descriptor into a readable path.
+	 *
+	 * Descriptors are plain arrays so they survive serialization into the object
+	 * cache; a closure would not.
+	 *
+	 * @param array $source
+	 *
+	 * @return string|null
+	 */
+	private static function resolve_path( array $source ): ?string {
+		switch ( $source['type'] ?? '' ) {
+			case 'file':
+				$path = (string) ( $source['path'] ?? '' );
+
+				return '' === $path ? null : $path;
+
+			case 'attachment':
+				$id = (int) ( $source['id'] ?? 0 );
+				if ( ! $id ) {
+					return null;
+				}
+
+				$path = get_attached_file( $id );
+
+				return is_string( $path ) && '' !== $path ? $path : null;
+		}
+
+		return null;
+	}
+}

From ef2308faa26606a3526b7f495d47c61323962f79 Mon Sep 17 00:00:00 2001
From: Amaury Balmer <amaury@beapi.fr>
Date: Thu, 10 Sep 2026 15:31:03 +0200
Subject: [PATCH 3/6] docs(icons): say plainly what __serialize() guards
 against

The previous comment read as though it were fixing something the code does
today. It is not: the factories cache their index before anything calls
content(), so no resolved payload can currently reach the cache. It is a
structural guard, and the comment now says so.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 includes/Icon/CollectionItem.php | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/includes/Icon/CollectionItem.php b/includes/Icon/CollectionItem.php
index 9ae9e3f..199c758 100644
--- a/includes/Icon/CollectionItem.php
+++ b/includes/Icon/CollectionItem.php
@@ -130,11 +130,16 @@ public function version(): ?string {
 	}
 
 	/**
-	 * Keep resolved payloads out of the cached collection index.
+	 * Control what an item writes to the cache: never its payload.
 	 *
-	 * Without this, caching a collection after rendering a page would grow the
-	 * index by however many icons happened to be used, and eventually push it past
-	 * the object cache's per-item limit.
+	 * content() memoizes, so an item that has been rendered holds its full SVG —
+	 * up to a couple of megabytes. Serializing that back into a collection index
+	 * would rebuild the very problem lazy loading removes.
+	 *
+	 * The factories happen to cache their index before anything resolves, so this
+	 * changes nothing today. It is here to make the rule structural rather than a
+	 * property of call order: an item that knows where to re-read its bytes never
+	 * carries them, whenever and wherever it gets serialized.
 	 *
 	 * @return array
 	 */

From 86c22dc7b9b413984d67ca0dde33b925e408faa5 Mon Sep 17 00:00:00 2001
From: Amaury Balmer <amaury@beapi.fr>
Date: Thu, 10 Sep 2026 15:37:04 +0200
Subject: [PATCH 4/6] refactor(icons): drop __serialize()/__unserialize() from
 CollectionItem

They guarded against a resolved payload reaching a cached index, but no call
path does that: every factory caches its index before anything calls content().
Default PHP serialization is enough, and two fewer magic methods is two fewer
things to reason about.

Cached indexes stay comfortably cacheable without them -- 108 KB for the
200-icon folder collection, 138 KB for 300 media attachments, against a 900 KB
ceiling. Measured metrics are unchanged: resident SVG, object-cache operations,
refused writes and response bytes are all identical, and the timing difference
is container jitter (repeat runs of this same code give 1.8-2.3 ms for the init
hook, matching the previous commit).

CACHE_FORMAT goes to v3 because the on-disk shape changed: an entry written by
__serialize() would otherwise be unserialized into public dynamic properties,
leaving the real typed ones uninitialised.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 includes/Icon/CollectionItem.php         | 43 ------------------------
 includes/Icon/CollectionItemsFactory.php |  2 +-
 2 files changed, 1 insertion(+), 44 deletions(-)

diff --git a/includes/Icon/CollectionItem.php b/includes/Icon/CollectionItem.php
index 199c758..49453ac 100644
--- a/includes/Icon/CollectionItem.php
+++ b/includes/Icon/CollectionItem.php
@@ -128,47 +128,4 @@ public function is_resolved(): bool {
 	public function version(): ?string {
 		return $this->version;
 	}
-
-	/**
-	 * Control what an item writes to the cache: never its payload.
-	 *
-	 * content() memoizes, so an item that has been rendered holds its full SVG —
-	 * up to a couple of megabytes. Serializing that back into a collection index
-	 * would rebuild the very problem lazy loading removes.
-	 *
-	 * The factories happen to cache their index before anything resolves, so this
-	 * changes nothing today. It is here to make the rule structural rather than a
-	 * property of call order: an item that knows where to re-read its bytes never
-	 * carries them, whenever and wherever it gets serialized.
-	 *
-	 * @return array
-	 */
-	public function __serialize(): array {
-		return [
-			'name'    => $this->name,
-			'label'   => $this->label,
-			'type'    => $this->type,
-			'version' => $this->version,
-			'source'  => $this->source,
-			// Items with a source can always reload; only literal content is stored.
-			'content' => null === $this->source ? $this->content : null,
-		];
-	}
-
-	/**
-	 * @param array $data
-	 */
-	public function __unserialize( array $data ): void {
-		$this->name    = (string) ( $data['name'] ?? '' );
-		$this->label   = isset( $data['label'] ) ? (string) $data['label'] : $this->name;
-		$this->type    = (string) ( $data['type'] ?? 'raw' );
-		$this->version = $data['version'] ?? null;
-		$this->source  = $data['source'] ?? null;
-		$this->content = $data['content'] ?? null;
-
-		// An item with neither content nor a source would otherwise re-resolve forever.
-		if ( null === $this->content && null === $this->source ) {
-			$this->content = '';
-		}
-	}
 }
diff --git a/includes/Icon/CollectionItemsFactory.php b/includes/Icon/CollectionItemsFactory.php
index 41ff0dd..3c4e25f 100644
--- a/includes/Icon/CollectionItemsFactory.php
+++ b/includes/Icon/CollectionItemsFactory.php
@@ -17,7 +17,7 @@ class CollectionItemsFactory {
 	 * unserializes the stored value *before* it compares salts. Only a different
 	 * key keeps the two formats apart.
 	 */
-	private const CACHE_FORMAT = 'v2';
+	private const CACHE_FORMAT = 'v3';
 
 	/**
 	 * Build a format-scoped cache key.

From f638db8d0b1cb1f9551ad8e2c4f9c09690d7d1b1 Mon Sep 17 00:00:00 2001
From: Amaury Balmer <amaury@beapi.fr>
Date: Thu, 10 Sep 2026 22:29:37 +0200
Subject: [PATCH 5/6] build: scope the phpcs test exclusion to the perf harness

The exclusion was added for tests/perf, whose object-cache drop-in has to assign
$GLOBALS['wp_object_cache'] and declare a class alongside the wp_cache_*
functions. Written as ./tests/ it now also covers the PHPUnit suite that landed
on develop, which is phpcs-clean and should stay linted.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 phpcs.xml.dist | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/phpcs.xml.dist b/phpcs.xml.dist
index 607c551..59dfd95 100644
--- a/phpcs.xml.dist
+++ b/phpcs.xml.dist
@@ -15,8 +15,11 @@
 		.distignore. It has to break WordPress conventions to do its job: the object
 		cache drop-in must assign $GLOBALS['wp_object_cache'] and declare both a class
 		and the wp_cache_* functions in one file.
+
+		Scoped to tests/perf on purpose — the PHPUnit suite under tests/phpunit is
+		held to the standard like the rest of the code.
 	-->
-	<exclude-pattern>./tests/</exclude-pattern>
+	<exclude-pattern>./tests/perf/</exclude-pattern>
 	<exclude-pattern>./node_modules/</exclude-pattern>
 	<exclude-pattern>./src/</exclude-pattern>
 	<exclude-pattern>./tools/</exclude-pattern>

From d423c1fe46eee5546f87650fc163ab44111d52bc Mon Sep 17 00:00:00 2001
From: Amaury Balmer <amaury@beapi.fr>
Date: Thu, 10 Sep 2026 22:42:19 +0200
Subject: [PATCH 6/6] docs(perf): re-measure the figures after the rebase
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both columns re-taken in one session on the same machine and the same 500 icons,
the "before" side by checking the original classes back into the working tree
rather than reusing an older run. Every operation count is unchanged — resident
SVG 101.7 MB to 0.015 MB, 301 cache gets to 2, 16 refused writes to none. Wall
times shifted by a few tens of percent, which is what wall times do; the table
now reports what was actually measured.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 tests/perf/README.md | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/tests/perf/README.md b/tests/perf/README.md
index e363a84..d02853f 100644
--- a/tests/perf/README.md
+++ b/tests/perf/README.md
@@ -205,10 +205,17 @@ Charging 2 ms per media-library file open, which is what a VIP Files fetch costs
 
 | scenario | before | after |
 |---|---|---|
-| front-empty-warm | 618 ms | 25 ms (−96%) |
-| front-empty-cold | **4806 ms** | 422 ms (−91%) |
-| front-single-warm | 547 ms | 30 ms (−94%) |
-| editor-new-page | 1057 ms | 556 ms (−47%) |
+| front-empty-warm | 402 ms | 25 ms (−94%) |
+| front-empty-cold | **4546 ms** | 435 ms (−90%) |
+| front-single-warm | 414 ms | 41 ms (−90%) |
+| front-single-cold | 4739 ms | 493 ms (−90%) |
+| editor-new-page | 834 ms | 364 ms (−56%) |
+
+Both sides of this table were measured in the same session, on the same machine,
+against the same 500 icons — the "before" column by checking the original classes
+back out into the working tree, not by reusing an older run. Wall time moves by a
+few tens of percent between sessions depending on what else the machine is doing;
+the operation counts above do not move at all.
 
 ### What is not addressed