Backtestshugorun-20261002-200313#12536

Issue #12536 Merged fix PR # Run 2 Oct 2026 · run-20261002-200313 gohugoio/hugo

images: Opacity problem with Resize + Padding with PNG output

Better

Our patch was judged better than the merged fix.

In this judgment, Patch A = our agent, Patch B = the merged fix.

Both patches fix the same root cause. Hex color strings are parsed into `color.RGBA`, which Go treats as alpha-premultiplied. A transparent color like `#00f7` (B=0xff > A=0x77) is therefore an invalid premultiplied value and gets corrupted when drawn onto a PNG/RGBA destination. Both switch `hexStringToColorGo` to return `color.NRGBA` for transparent colors, and both make `ColorGoToHexString` and the luminance calculation read the non-premultiplied channels. Both regenerate the same `padding-transparent-chained.png` golden, so on the reported Resize + Padding + PNG scenario they are equivalent in correctness.

The differences are in scope, risk and tests.

Patch B bundles a separate behavioral change in `resources/image.go`. It skips source-palette clamping for every Filter action on paletted PNGs, which its own comment attributes to a different problem. This changes output for all filters on indexed PNGs: they no longer stay paletted, so file sizes and appearance change. It also required regenerating the `overlay.png` and `text.png` goldens. That is unrelated to the padding-opacity issue and adds regression risk.

Patch B also normalizes every `Color` to NRGBA inside `init()` and reworks `AddColorToPalette` equality. These are broader edits that ripple into palette handling. It also rewrites an existing test expectation (`color.RGBA{...,A:0x80}` -> `color.NRGBA`) instead of only adding coverage.

Patch A is minimal. It returns plain `RGBA` for opaque colors, preserving existing behavior, and `NRGBA` only for transparent ones. Its small `colorGoToRGBA8` helper is used consistently for hex output and luminance.

Patch A's tests are much stronger:
- Unit tests for parsing and hex round-tripping of transparent colors.
- A filter test checking padding and text draw identically onto premultiplied and non-premultiplied destinations.
- An end-to-end integration test that resizes to PNG, pads with `#00f7` and decodes the published file to assert the exact NRGBA pixel. This directly reproduces the issue scenario.

Patch B adds only a couple of parse-table entries and relies on golden images.

With equal core correctness, Patch A wins on its targeted scope, lower risk and substantially better tests.

The judge saw only the two patches, labelled A and B in random order, with issue links and version numbers removed. The reasoning above is shown verbatim.

Solve

1h 10m

Wall-clock time in the container

Full test suite

No new failures

3,760 passed · 99 skipped · 3,861 total

Contamination audit

Clean

No sign the agent saw the real fix

Patch size

175vs 58 merged

Changed lines, ours vs merged

What version of Hugo are you using (hugo version)?

$ hugo version
hugo v0.126.1+extended linux/amd64

Does this issue reproduce with the latest release?

Yes.

Report

The 0 function currently ignores the transparency setting when padding a PNG image. While the documentation does state 'conversion to WEBP is required to support transparency' (under Other recipes), I can't see a reason why PNG shouldn't be supported, given that it has an alpha channel. For the moment I have resorted to first converting the image to WEBP, then applying transparent padding, and then converting it back to PNG, but this does not feel like an elegant solution.

The two patches

Our patch+167 −8
resources/images/color.goindex fe233c7b7..11deff476 100644@@ -70,8 +70,8 @@ func (c Color) Key() string {  func (c *Color) init() error { 	c.hex = ColorGoToHexString(c.color)-	r, g, b, _ := c.color.RGBA()-	c.luminance = 0.2126*c.toSRGB(uint8(r)) + 0.7152*c.toSRGB(uint8(g)) + 0.0722*c.toSRGB(uint8(b))+	r, g, b, _ := colorGoToRGBA8(c.color)+	c.luminance = 0.2126*c.toSRGB(r) + 0.7152*c.toSRGB(g) + 0.0722*c.toSRGB(b) 	return nil } @@ -108,12 +108,21 @@ func ReplaceColorInPalette(c color.Color, p color.Palette) {  // ColorGoToHexString converts a color.Color to a hex string. func ColorGoToHexString(c color.Color) string {-	r, g, b, a := c.RGBA()-	rgba := color.RGBA{uint8(r), uint8(g), uint8(b), uint8(a)}-	if rgba.A == 0xff {-		return fmt.Sprintf("#%.2x%.2x%.2x", rgba.R, rgba.G, rgba.B)+	r, g, b, a := colorGoToRGBA8(c)+	if a == 0xff {+		return fmt.Sprintf("#%.2x%.2x%.2x", r, g, b) 	}-	return fmt.Sprintf("#%.2x%.2x%.2x%.2x", rgba.R, rgba.G, rgba.B, rgba.A)+	return fmt.Sprintf("#%.2x%.2x%.2x%.2x", r, g, b, a)+}++// colorGoToRGBA8 returns the 8-bit channel values of c.+// For color.NRGBA, the non-alpha-premultiplied channel values are returned.+func colorGoToRGBA8(c color.Color) (r, g, b, a uint8) {+	if nc, ok := c.(color.NRGBA); ok {+		return nc.R, nc.G, nc.B, nc.A+	}+	r32, g32, b32, a32 := c.RGBA()+	return uint8(r32), uint8(g32), uint8(b32), uint8(a32) }  // ColorGoToColor converts a color.Color to a Color.@@ -195,5 +204,11 @@ func hexStringToColorGo(s string) (color.Color, error) { 		return nil, err 	} -	return color.RGBA{b[0], b[1], b[2], b[3]}, nil+	if b[3] == 0xff {+		// Fully opaque, alpha-premultiplied and non-alpha-premultiplied values are the same.+		return color.RGBA{b[0], b[1], b[2], b[3]}, nil+	}++	// The hex notation is non-alpha-premultiplied, see issue 12536.+	return color.NRGBA{b[0], b[1], b[2], b[3]}, nil }resources/images/color_test.goindex 540f3bea8..400d22baa 100644@@ -123,3 +123,41 @@ func TestColorLuminance(t *testing.T) { 	c.Assert(hexStringToColor("#d5bc9f").Luminance(), hqt.IsSameFloat64, 0.5261577672685374) 	c.Assert(hexStringToColor("#ffffff").Luminance(), hqt.IsSameFloat64, 1.0) }++// See issue 12536.+func TestHexStringToColorGoTransparent(t *testing.T) {+	c := qt.New(t)++	for _, test := range []struct {+		arg    string+		expect color.NRGBA+	}{+		{"#00f7", color.NRGBA{R: 0x00, G: 0x00, B: 0xff, A: 0x77}},+		{"#4287f580", color.NRGBA{R: 0x42, G: 0x87, B: 0xf5, A: 0x80}},+		{"ff000000", color.NRGBA{R: 0xff, G: 0x00, B: 0x00, A: 0x00}},+	} {+		c.Run(test.arg, func(c *qt.C) {+			c.Parallel()++			result, err := hexStringToColorGo(test.arg)+			c.Assert(err, qt.IsNil)+			// The hex notation is not alpha-premultiplied.+			c.Assert(color.NRGBAModel.Convert(result), qt.Equals, test.expect)+			r, g, b, a := result.RGBA()+			er, eg, eb, ea := test.expect.RGBA()+			c.Assert([]uint32{r, g, b, a}, qt.DeepEquals, []uint32{er, eg, eb, ea})+		})+	}+}++// See issue 12536.+func TestHexStringToColorRoundTripTransparent(t *testing.T) {+	c := qt.New(t)++	for _, hex := range []string{"#4287f580", "#0000ff77", "#ff000000"} {+		cc := hexStringToColor(hex)+		c.Assert(cc.ColorHex(), qt.Equals, hex)+	}++	c.Assert(hexStringToColor("#768a9a80").Luminance(), hqt.IsSameFloat64, hexStringToColor("#768a9a").Luminance())+}resources/images/filters_test.goindex ce8ae9f5a..a68d7251a 100644@@ -14,9 +14,13 @@ package images  import (+	"image"+	"image/color"+	"image/draw" 	"testing"  	qt "github.com/frankban/quicktest"+	"github.com/gohugoio/gift" 	"github.com/gohugoio/hugo/common/hashing" ) @@ -30,3 +34,69 @@ func TestFilterHash(t *testing.T) { 	c.Assert(hashing.HashString(f.Gamma(32)), qt.Not(qt.Equals), hashing.HashString(f.Gamma(33))) 	c.Assert(hashing.HashString(f.Gamma(32)), qt.Equals, hashing.HashString(f.Gamma(32))) }++// Transparent colors must be drawn the same way regardless of whether the+// destination image is alpha-premultiplied or not.+// See issue 12536.+func TestFiltersTransparentColorPremultipliedDst(t *testing.T) {+	c := qt.New(t)++	newWhite := func(premultiplied bool) draw.Image {+		r := image.Rect(0, 0, 100, 60)+		var img draw.Image+		if premultiplied {+			img = image.NewRGBA(r)+		} else {+			img = image.NewNRGBA(r)+		}+		draw.Draw(img, r, image.White, image.Point{}, draw.Src)+		return img+	}++	apply := func(f gift.Filter, premultiplied bool) *image.NRGBA {+		src := newWhite(premultiplied)+		g := gift.New(f)+		var dst draw.Image+		if premultiplied {+			dst = image.NewRGBA(g.Bounds(src.Bounds()))+		} else {+			dst = image.NewNRGBA(g.Bounds(src.Bounds()))+		}+		g.Draw(dst, src)+		result := image.NewNRGBA(dst.Bounds())+		draw.Draw(result, result.Bounds(), dst, dst.Bounds().Min, draw.Src)+		return result+	}++	filters := &Filters{}++	c.Run("padding", func(c *qt.C) {+		for _, premultiplied := range []bool{false, true} {+			result := apply(filters.Padding(10, "#00f7"), premultiplied)+			c.Assert(result.NRGBAAt(0, 0), qt.Equals, color.NRGBA{R: 0x00, G: 0x00, B: 0xff, A: 0x77}, qt.Commentf("premultiplied: %t", premultiplied))+			c.Assert(result.NRGBAAt(60, 40), qt.Equals, color.NRGBA{R: 0xff, G: 0xff, B: 0xff, A: 0xff}, qt.Commentf("premultiplied: %t", premultiplied))+		}+	})++	c.Run("text", func(c *qt.C) {+		f := filters.Text("Hugo", map[string]any{"color": "#00f7", "size": 40, "x": 5, "y": 5})+		nonPremultiplied := apply(f, false)+		premultiplied := apply(f, true)+		var changed int+		for i := 0; i < len(premultiplied.Pix); i += 4 {+			if nonPremultiplied.Pix[i] != 0xff {+				changed+++			}+			// Blue drawn over opaque white must leave blue and alpha untouched.+			c.Assert(premultiplied.Pix[i+2], qt.Equals, uint8(0xff), qt.Commentf("pixel %d", i/4))+			c.Assert(premultiplied.Pix[i+3], qt.Equals, uint8(0xff), qt.Commentf("pixel %d", i/4))+			for j := range 4 {+				diff := int(premultiplied.Pix[i+j]) - int(nonPremultiplied.Pix[i+j])+				c.Assert(diff >= -1 && diff <= 1, qt.IsTrue, qt.Commentf("pixel %d channel %d: %d vs %d", i/4, j, premultiplied.Pix[i+j], nonPremultiplied.Pix[i+j]))+			}+		}+		c.Assert(changed > 0, qt.IsTrue)+		// Fully covered pixels: blue with alpha 0x77 over white.+		c.Assert(premultiplied.Pix, qt.Contains, uint8(0x88))+	})+}resources/images/images_integration_test.goindex 172449d21..52c2d2664 100644@@ -14,9 +14,14 @@ package images_test  import (+	"image/color"+	"image/png"+	"os"+	"path/filepath" 	"testing"  	"github.com/bep/logg"+	qt "github.com/frankban/quicktest" 	"github.com/gohugoio/hugo/htesting" 	"github.com/gohugoio/hugo/hugolib" )@@ -182,3 +187,34 @@ Page. 		builder.Build() 	} }++// Transparent hex colors must not be treated as alpha-premultiplied.+// See issue 12536.+func TestTransparentColorsIssue12536(t *testing.T) {+	files := `+-- hugo.toml --+-- assets/sunset.jpg --+sourcefilename: ../testdata/sunset.jpg+-- assets/circle.png --+sourcefilename: ../testdata/fuzzy-cirlcle.png+-- layouts/home.html --+{{ $sunset := resources.Get "sunset.jpg" }}+{{ with ($sunset.Resize "x50 png").Filter (images.Padding 20 "#00f7") | resources.Copy "images/padding.png" }}{{ .Publish }}{{ end }}+{{ with (resources.Get "circle.png").Process "png #00f7" | resources.Copy "images/bgcolor.png" }}{{ .Publish }}{{ end }}+`++	b := hugolib.Test(t, files, hugolib.TestOptWithConfig(func(cfg *hugolib.IntegrationTestConfig) {+		cfg.NeedsOsFS = true+	}))++	expect := color.NRGBA{R: 0x00, G: 0x00, B: 0xff, A: 0x77}++	for _, name := range []string{"padding.png", "bgcolor.png"} {+		f, err := os.Open(filepath.Join(b.H.Conf.WorkingDir(), "public", "images", name))+		b.Assert(err, qt.IsNil)+		img, err := png.Decode(f)+		f.Close()+		b.Assert(err, qt.IsNil)+		b.Assert(color.NRGBAModel.Convert(img.At(0, 0)), qt.Equals, expect, qt.Commentf(name))+	}+}resources/images/testdata/images_golden/filters/padding/padding-transparent-chained.pngindex 899e21f25..34392755c 100644Binary files a/resources/images/testdata/images_golden/filters/padding/padding-transparent-chained.png and b/resources/images/testdata/images_golden/filters/padding/padding-transparent-chained.png differ 
Merged fix · PR #+39 −19
resources/image.goindex 467e23f26..a2ed5f3c9 100644@@ -321,7 +321,7 @@ func (i *imageResource) Filter(filters ...any) (images.ImageResource, error) { 		return nil, err 	} -	confMain.Action = "filter"+	confMain.Action = images.ActionFilter 	confMain.Key = hashing.HashString(gfilters)  	return i.doWithImageConfig(confMain, func(src image.Image) (image.Image, error) {@@ -438,7 +438,11 @@ func (i *imageResource) doWithImageConfig(conf images.ImageConfig, f func(src im 			converted = tmp 		} -		if conf.TargetFormat == images.PNG {+		// Preserve the source palette for the geometric actions so an indexed+		// PNG stays indexed. Filters (e.g. images.Overlay, images.Text) routinely+		// introduce colors outside the source palette, and clamping the result+		// back to that palette destroys the filtered output. See issue 12543.+		if conf.TargetFormat == images.PNG && conf.Action != images.ActionFilter { 			// Apply the colour palette from the source 			if paletted, ok := src.(*image.Paletted); ok { 				palette := paletted.Paletteresources/images/color.goindex fe233c7b7..72f3710e3 100644@@ -69,9 +69,12 @@ func (c Color) Key() string { }  func (c *Color) init() error {-	c.hex = ColorGoToHexString(c.color)-	r, g, b, _ := c.color.RGBA()-	c.luminance = 0.2126*c.toSRGB(uint8(r)) + 0.7152*c.toSRGB(uint8(g)) + 0.0722*c.toSRGB(uint8(b))+	// Normalize to the canonical non-premultiplied form so that equal colors+	// compare equal whether they came from a hex string or from image pixels.+	nrgba := color.NRGBAModel.Convert(c.color).(color.NRGBA)+	c.color = nrgba+	c.hex = ColorGoToHexString(nrgba)+	c.luminance = 0.2126*c.toSRGB(nrgba.R) + 0.7152*c.toSRGB(nrgba.G) + 0.0722*c.toSRGB(nrgba.B) 	return nil } @@ -88,10 +91,13 @@ func (c Color) toSRGB(i uint8) float64 { // Note that it does no additional checks, so callers must make sure // that the palette is valid for the relevant format. func AddColorToPalette(c color.Color, p color.Palette) color.Palette {-	var found bool-	if slices.Contains(p, c) {-		found = true-	}+	// Compare color values rather than interface values, so that e.g. a+	// color.NRGBA is found even if the palette holds it as a color.RGBA.+	cr, cg, cb, ca := c.RGBA()+	found := slices.ContainsFunc(p, func(v color.Color) bool {+		vr, vg, vb, va := v.RGBA()+		return cr == vr && cg == vg && cb == vb && ca == va+	})  	if !found { 		p = append(color.Palette{c}, p...)@@ -108,12 +114,13 @@ func ReplaceColorInPalette(c color.Color, p color.Palette) {  // ColorGoToHexString converts a color.Color to a hex string. func ColorGoToHexString(c color.Color) string {-	r, g, b, a := c.RGBA()-	rgba := color.RGBA{uint8(r), uint8(g), uint8(b), uint8(a)}-	if rgba.A == 0xff {-		return fmt.Sprintf("#%.2x%.2x%.2x", rgba.R, rgba.G, rgba.B)+	// Hex notation is not alpha-premultiplied, so convert via NRGBA to+	// un-premultiply the color components of any transparent color.+	nrgba := color.NRGBAModel.Convert(c).(color.NRGBA)+	if nrgba.A == 0xff {+		return fmt.Sprintf("#%.2x%.2x%.2x", nrgba.R, nrgba.G, nrgba.B) 	}-	return fmt.Sprintf("#%.2x%.2x%.2x%.2x", rgba.R, rgba.G, rgba.B, rgba.A)+	return fmt.Sprintf("#%.2x%.2x%.2x%.2x", nrgba.R, nrgba.G, nrgba.B, nrgba.A) }  // ColorGoToColor converts a color.Color to a Color.@@ -195,5 +202,8 @@ func hexStringToColorGo(s string) (color.Color, error) { 		return nil, err 	} -	return color.RGBA{b[0], b[1], b[2], b[3]}, nil+	// Hex notation is not alpha-premultiplied, so this must be a color.NRGBA;+	// as a color.RGBA any transparent color would be invalid (component > alpha)+	// and corrupted when drawn onto an alpha-premultiplied image. See issue 12536.+	return color.NRGBA{b[0], b[1], b[2], b[3]}, nil }resources/images/color_test.goindex 540f3bea8..47bc5ae8b 100644@@ -39,8 +39,12 @@ func TestHexStringToColor(t *testing.T) { 		{"#ffffff", color.White}, 		{"ffffff", color.White}, 		{"#000", color.Black},-		{"#4287f5", color.RGBA{R: 0x42, G: 0x87, B: 0xf5, A: 0xff}},-		{"777", color.RGBA{R: 0x77, G: 0x77, B: 0x77, A: 0xff}},+		{"#4287f5", color.NRGBA{R: 0x42, G: 0x87, B: 0xf5, A: 0xff}},+		{"777", color.NRGBA{R: 0x77, G: 0x77, B: 0x77, A: 0xff}},+		// Hex notation is not alpha-premultiplied, so a transparent color+		// must parse to a color.NRGBA. See issue 12536.+		{"#00f7", color.NRGBA{R: 0x00, G: 0x00, B: 0xff, A: 0x77}},+		{"4287f580", color.NRGBA{R: 0x42, G: 0x87, B: 0xf5, A: 0x80}}, 	} {  		c.Run(test.arg, func(c *qt.C) {@@ -71,10 +75,11 @@ func TestColorToHexString(t *testing.T) { 		{color.Black, "#000000"}, 		{color.RGBA{R: 0x42, G: 0x87, B: 0xf5, A: 0xff}, "#4287f5"}, -		// 50% opacity.+		// 50% opacity. Hex notation is not alpha-premultiplied, so the+		// components of a transparent color are the non-premultiplied ones. 		// Note that the .Colors (dominant colors) received from the Image resource 		// will always have an alpha value of 0xff.-		{color.RGBA{R: 0x42, G: 0x87, B: 0xf5, A: 0x80}, "#4287f580"},+		{color.NRGBA{R: 0x42, G: 0x87, B: 0xf5, A: 0x80}, "#4287f580"}, 	} {  		c.Run(test.expect, func(c *qt.C) {resources/images/config.goindex 4cbd7e629..e8fd69c94 100644@@ -36,6 +36,7 @@ const ( 	ActionCrop   = "crop" 	ActionFit    = "fit" 	ActionFill   = "fill"+	ActionFilter = "filter" )  var Actions = map[string]bool{resources/images/testdata/images_golden/filters/padding/padding-transparent-chained.pngindex 899e21f25..34392755c 100644Binary files a/resources/images/testdata/images_golden/filters/padding/padding-transparent-chained.png and b/resources/images/testdata/images_golden/filters/padding/padding-transparent-chained.png differresources/images/testdata/images_golden/filters/paletted/overlay.pngindex 10d9dd6fd..631854dd8 100644Binary files a/resources/images/testdata/images_golden/filters/paletted/overlay.png and b/resources/images/testdata/images_golden/filters/paletted/overlay.png differresources/images/testdata/images_golden/filters/paletted/text.pngindex 71a9c3e2d..65d1a60ce 100644Binary files a/resources/images/testdata/images_golden/filters/paletted/text.png and b/resources/images/testdata/images_golden/filters/paletted/text.png differ