docs: document png alpha and svg metadata behavior - #24
Merged
Conversation
Adds the two lossless transforms introduced in v0.0.30 to the pipeline section, plus a head-to-head benchmark replaying microlinkhq/www#2183 on real production assets. ImgBot's column reproduces the numbers from its own PR body, which confirms the fixture set matches what it measured. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LP1pN2cuVgeVJujCnLBD4P
📝 WalkthroughWalkthroughREADME.md documents format-specific PNG and SVG optimization behavior. It also adds a production-asset comparison between optimo and ImgBot, including per-file and aggregate size results and pixel-comparison findings. ChangesOptimization documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Coverage Report for CI Build 31042557369Warning No base build found for commit Coverage: 68.203%Details
Uncovered ChangesNo uncovered changes found. Coverage RegressionsRequires a base build to compare against. How to fix this → Coverage Stats
💛 - Coveralls |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Line 55: Update the README statements for SVG whitespace handling and the
`magick compare -metric AE` check to distinguish metadata text from rendered
graphics: state that collapsing whitespace in `<title>` and `<desc>` may alter
their text content, while rendered graphics remain unchanged and rendered
outputs are pixel-identical. Do not claim that accessibility-reader text is
unchanged or that the pixel comparison proves SVG metadata equality.
- Line 54: Update the README description of opaque-alpha handling to state that
only opaque-alpha removal is skipped for animated PNGs, while the rest of the
PNG processing still applies.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
Addresses review feedback on #24. Animated PNGs are still optimized; only the opaque-alpha removal is skipped for them. The previous wording implied the whole pipeline skipped them. The blanket "every output is pixel-identical" claim was wrong. It was verified on one PNG and generalized to all 11 files. Re-running `magick compare -metric AE` across the set shows magnific.svg at 99, because SVGO's preset-default rounds path coordinates. The nine PNGs are all 0. The claim now states this per format. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LP1pN2cuVgeVJujCnLBD4P
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Line 168: Update the SVG comparison statement in the README to say the outputs
are not all pixel-identical, since adobe.svg has zero differing pixels. Replace
“a small number of pixels” with “99 pixels,” matching the reported metric for
magnific.svg.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
Addresses review feedback on #24. The sentence claimed both SVG outputs differ from their inputs, then reported 0 differing pixels for adobe.svg in the same breath. Only magnific.svg differs, at 99 pixels of 2,304. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LP1pN2cuVgeVJujCnLBD4P
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to the v0.0.30 fix, which landed on
masterdirectly and never got a review pass.What changed
Two additions to the README:
Pipelines now documents the two lossless transforms introduced in v0.0.30 — the opaque-alpha drop for PNG and the
<title>/<desc>whitespace collapse for SVG — including their limits (animated PNGs are skipped,<text>is never touched).Benchmark gains a head-to-head table replaying microlinkhq/www#2183, an ImgBot PR against a production site, with optimo run on the exact same inputs.
Why the benchmark is trustworthy
The ImgBot column reproduces the percentages from its own PR body byte for byte (
-11.02%,-10.84%,-9.38%total), which confirms the fixture set matches what ImgBot actually measured rather than a re-run under different conditions.optimo now matches or beats ImgBot on all 11 files: -9.51% vs -9.38% overall. The two files that motivated v0.0.30:
gmail-bimi-brand-logo.png— carried a fully opaque alpha channel. Every re-encode candidate came out larger than the input, so optimo's safety guard kept the original and saved 0 bytes while ImgBot saved 6.32%. Now -8.50%, ahead of ImgBot.bimi/adobe.svg— kept a literal newline inside<title>. Now at parity, 340 B.gmail-bimi-brand-logo.pngis pixel-identical to its input (magick compare -metric AEreports0), as are the other eight PNGs.adobe.svgis also0.magnific.svgis not — it reports99, because SVGO'spreset-defaultrounds path coordinates. That predates this PR and is now stated explicitly in the README rather than glossed as blanket losslessness.Note on process
The v0.0.30 fix (5f717b2) was pushed straight to
masterand released before review. Rewriting that history under a published tag would breakv0.0.30, so it stays as-is; this PR is the review pass for the behavior it introduced.Docs only — no code changes, no version bump.
Note
Low Risk
Documentation-only changes with no code, config, or release impact.
Overview
README-only follow-up that documents behavior already shipped in v0.0.30 (no runtime changes).
Under Pipelines, a new Format-specific lossless behavior section explains PNG opaque-alpha stripping (RGB conversion, animated PNG exception) and SVG
<title>/<desc>whitespace collapse (with<text>left alone).Under Benchmark, a Head-to-head on real assets subsection adds an 11-file table replaying microlinkhq/www#2183 against ImgBot, plus notes that both tools share the same backends, optimo’s aggregate savings, and which outputs are pixel-identical vs
magnific.svg’s SVGO path rounding.Reviewed by Cursor Bugbot for commit 08f4750. Bugbot is set up for automated code reviews on this repo. Configure here.
Summary by CodeRabbit