srcset-truth is a WordPress plugin for site operators whose pages send phones larger images than the layout needs. It corrects the sizes attribute, serves WebP copies next to the originals and reports the saving. It is MIT licensed, and v0.1.0 was released on 14 November 2026.
WordPress gives every attachment image a srcset with several widths. That part is fine. It then adds a sizes attribute that says, in effect, that the image is as wide as the viewport, up to its own width. For an image painted into a fixed slot, such as a card in a grid, that is false, and the browser trusts it.
The README’s worked case: a theme asks for the 1024 by 576 derivative and paints it into a 372 by 266 card. On a 412 px phone at a device pixel ratio of 2, the browser computes a need of 824 device pixels and downloads the 1024 px file. The 300 px and 768 px files already exist on disk, and one of them was the right answer. The srcset was correct and the sizes hint was wrong.
Two related faults ride along. Most uploads are JPEG, PNG or GIF, and WebP is much smaller. But converting a whole library is costly, and rewriting URLs by Accept header breaks on CDNs that do not vary on it. Themes also often set loading="lazy" on every image, including the largest one above the fold, which delays Largest Contentful Paint.
sizes value with a value from a width map the site supplies per template and per slot. Values a theme wrote itself are left alone unless you opt in.<picture>.wp srcset-truth audit.On a front-end HTML request every image passes one classifier, Corrector::correct(), whichever way it arrives: content filter, post thumbnail, attachment attributes or the page buffer. CoreDefault recognises core’s value. TemplateResolver and SlotResolver pick a template key and a slot. WidthMap looks the pair up, Compiler builds and validates the value, and the last length is capped at the image’s own width so a map written for big images never inflates small ones. If anything is unclear, core’s value stays.
You describe slots in the theme, or name them where you render:
add_filter('srcset_truth_width_map', function (array $map): array {
$map['default']['card'] = [[767, '92vw'], [1024, '46vw'], [null, '380px']];
return $map;
});
use function IndianOpinion\SrcsetTruth\with_slot;
echo with_slot('card', fn () => get_the_post_thumbnail(null, 'large'));
For WebP, SiblingCreator writes photo-768x432.jpg.webp next to photo-768x432.jpg for the main file and the medium, medium_large and large sizes. It uses Imagick or GD. File type comes from the signature, not the name, and writes are atomic. A sibling that is not smaller than its original is deleted. Backfill walks the library from the newest ID down on cron, with a stored cursor and a lock. Page requests never encode. They check whether a sibling exists, once per file per request.
Serving wraps the image in <picture> with a <source type="image/webp"> and leaves the <img> as it was, so a browser without WebP falls back. The source lists the same candidates in the same order, so the browser’s width choice does not change. The HTML is the same for every visitor, with no Vary: Accept, and each format has its own URL, so a CDN caches them separately. The plugin prints picture.srcset-truth{display:contents} so flex and grid layouts treat the image as a direct child.
The audit applies the specification’s pick rule: the smallest candidate whose density reaches the device pixel ratio. It reports the candidate under core’s sizes and the one under the emitted sizes, with bytes and flags such as unmapped and no-candidate-near-slot.
SRCSET_TRUTH_DISABLE set to true in wp-config.php hooks nothing.too-large and colour-profile and are recorded in a capped skip ledger so they are not retried until the original changes.max_execution_time.private, no-store and define DONOTCACHEPAGE.manage_options and a nonce.src and srcset to .webp in place, so browsers without WebP got broken images. Wrapping in <picture> is now the default, and the in-place rewrite is opt-in.wp_get_attachment_image() would have lost WebP under the new default, so that output is wrapped through its own filter.<picture> inside another. Each wrapped pair is now remembered for the request.srcset_truth_has_sibling yourself. Anything that syncs uploads to a media host must include the .webp files..card > img stop matching once the image sits inside <picture>.This is v0.1.0. The review reports 150 PHPUnit tests, PHPStan level 8 and phpcs all clean on a local PHP 8.3, with the tests running against stubs and mocks of WordPress plus the real WordPress 6.4 tag processor. CI has not yet run on GitHub, and the plugin has not run on a live site. It was specified, built and reviewed in separate roles by language-model coding agents under the editor’s direction.
It needs PHP 8.1 or later and WordPress 6.4 or later. WebP creation needs Imagick with WebP or GD with WebP. Without either, sizes correction still works.
The package is not on Packagist yet, so first add a Composer vcs repository entry for https://github.com/IndianOpinion/srcset-truth.
composer require indianopinion/srcset-truth