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/.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..49453ac 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.
 	 *
diff --git a/includes/Icon/CollectionItemsFactory.php b/includes/Icon/CollectionItemsFactory.php
index dd62873..3c4e25f 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 = 'v3';
+
+	/**
+	 * 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;
+	}
+}
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..59dfd95 100644
--- a/phpcs.xml.dist
+++ b/phpcs.xml.dist
@@ -10,6 +10,16 @@
 	<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.
+
+		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/perf/</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..d02853f
--- /dev/null
+++ b/tests/perf/README.md
@@ -0,0 +1,268 @@
+# 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 | 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
+
+- **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
+*/