Files

Henk 7e1c86f215 feat: initial v0.1.0 MVP

Replaces Smush Pro's optimisation pipeline without the grey-wash bug.

CLI commands working:
  wp h4b-img status
  wp h4b-img optimise --id=<n>
  wp h4b-img bulk
  wp h4b-img rescue

Verified on dev.rds.ink:
- ICC profile preservation works (the Smush-bug fix)
- Bulk: 20 attachments → 487 KB saved (10.4%), 0 errors
- Rescue: end-to-end mechanism verified on WorkingAsOne_horse fixture
- WebP synchronous, AVIF queued via WP-Cron
- Originals backed up to wp-content/h4b-img-originals/

See CHANGELOG.md for details + ../DESIGN-h4b-image-optim.md for architecture.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-19 13:41:03 +10:00

2.5 KiB

Raw Blame History

h4b-image-optim

ICC-safe image optimisation with WebP + AVIF generation for WordPress. Replaces Smush Pro without the grey-wash bug. No CDN.

Status: v0.1.0 MVP — under active development. Tested on AlmaLinux 9 + PHP 8.4 + Imagick 3.8.1.

Why this exists

Smush Pro's Ultra mode (lossy=2 + strip_exif=true) destroyed 1,345 high-contrast B&W ink art JPGs on rds.ink by stripping ICC profiles and applying aggressive JPEG quantisation. The diagnosis, rescue, and a full design document are in the sibling image-rescue/ directory.

This plugin is the structural fix: an in-house Smush replacement that never strips ICC profiles, with full source-code ownership and zero CDN dependency.

Features (v0.1)

✅ JPEG / PNG optimisation in place (Imagick + jpegoptim/pngquant)
✅ ICC profile preservation (the Smush-bug fix)
✅ EXIF orientation applied + GPS stripped for privacy
✅ WebP sibling generation (cwebp)
✅ AVIF sibling generation (avifenc, queued via WP-Cron)
✅ Backup of originals to wp-content/h4b-img-originals/, pruned after 90 days
✅ WP-CLI: wp h4b-img status, wp h4b-img optimise --id=<n>
🔜 Bulk processing (wp h4b-img bulk)
🔜 Picture-tag rewriting + .htaccess fallback
🔜 Admin settings page
🔜 Migration command from Smush metadata

Required system tools

Install on AlmaLinux 9:

dnf install --setopt=install_weak_deps=False \
  libwebp-tools jpegoptim libjpeg-turbo-utils libavif-tools pngquant

Verify with:

wp h4b-img status

Settings (v0.1 — set via WP-CLI)

wp option get h4b_image_optim_settings
wp option patch update h4b_image_optim_settings jpeg_quality 90

Key defaults:

Setting	Default	Why
`jpeg_quality`	85	Industry standard; visually lossless for art
`jpeg_chroma_subsampling`	`4:4:4`	The Smush-bug fix — no chroma loss on edges
`preserve_icc_profile`	`true`	Critical — never strip ICC
`generate_webp`	`true`	Always make .webp sibling
`generate_avif`	`true`	Always make .avif sibling (background)
`avif_async`	`true`	Don't block upload UI
`backup_originals`	`true`	Always
`backup_prune_days`	`90`	Cron prunes after 90 days
`resize_max_width`	`2560`	Hard cap on uploaded image size

Uninstall

uninstall.php deletes the settings option and clears cron hooks. It does not delete backup files or .webp/.avif siblings — those are user data.

License

GPL-2.0-or-later.

2.5 KiB Raw Blame History