@@ -6,6 +6,45 @@ configuration, architectural decisions. Anything a user would notice goes to
 
 ## Unreleased
 
+### 2026-08-01 - the first compressed format
+
+- `png` is the first generator where the output size does not follow from the
+  content. Everything before the closing chunk streams straight out while
+  being counted, then a padding chunk makes up the difference. Nothing is
+  buffered, whatever the picture size.
+- **The padding channel was measured before it was built.** Five independent
+  decoders - Pillow, FFmpeg, Tcl/Tk, the Windows Imaging Component and
+  exiftool - all read an image with an extra chunk between IDAT and IEND and
+  return identical pixels. This had been recorded as an open question that
+  had to be measured rather than assumed, and it was.
+- **A private chunk rather than tEXt.** Both work everywhere, but exiftool
+  reports "Text/EXIF chunk(s) found after PNG IDAT" for tEXt. A warning in
+  the checking tool is what makes a tester think the generator is broken,
+  which is the same cost already recorded for 7Z.
+- **PNG has unreachable sizes and that is a property of the format.** The
+  smallest is 73 bytes, the next reachable is 83, and 74 to 82 cannot be hit
+  because the smallest possible chunk costs 12 bytes. Measured by scanning
+  every size from 0 to 400.
+- The exact size guard was restated as the rule it actually protects: exact
+  or an error, never a different size in silence. It now also walks sizes
+  below the declared minimum, so the refusal path is exercised rather than
+  assumed.
+- **Mutation found two holes in the guards themselves.** The seed test only
+  ran with the label on, and the label carries the seed in its text - so a
+  generator could ignore the seed everywhere else and still pass. And no test
+  ever asked for a size below the minimum, so the code that refuses could
+  have been deleted unnoticed. Both closed.
+- `imagelabel` draws a 3 by 5 bitmap font written here rather than taken from
+  a font file. No dependency, no licence to check, and identical pixels on
+  every machine. Known limit: at three pixels wide M, N and W stay similar.
+- `--set key=value` is repeatable and maps one to one onto the properties
+  block of a recipe.
+- Measured while building this: a gradient compresses to 0.1% of its raw
+  size, noise to 75%. A 3840x2160 gradient encodes in about 176 ms, and
+  writing it to disk instead of counting it costs nothing measurable - so the
+  temp file option would have bought time it does not buy and cost disk space
+  it does not have.
+
 ### 2026-08-01 - review after the first format
 
 A read through everything written so far, before starting the second format.
 
@@ -12,8 +12,15 @@ because it turns other people's test suites red.
 
 ### Added
 
-- `tfg generate` produces text files of an exact size. Ask for 10 485 761
-  bytes and you get exactly that, from 0 bytes upward.
+- `tfg generate` produces **text and PNG files** of an exact size. Ask for
+  10 485 761 bytes and you get exactly that.
+- PNG carries the label burned into the picture, and its size is made exact
+  by a private chunk that decoders ignore. Checked against Pillow, FFmpeg,
+  Tcl/Tk, the Windows Imaging Component and exiftool - all five read the
+  image, the pixels are unchanged and none of them reports a warning.
+- `--set` sets a format property and can be repeated:
+  `--set width=1920 --set height=1080`. Leave it out and the picture size is
+  chosen to suit the file size you asked for.
 - `tfg formats` lists what this build supports, with the fidelity level, the
   determinism level, the minimum size and the padding channel of each format.
 - Every run writes a `manifest.json` next to the files - path, size, SHA-256,
@@ -57,5 +64,10 @@ because it turns other people's test suites red.
   never a silent difference from what you ordered.
 - **The last word can be clipped.** Hitting the exact size wins over ending
   on a word boundary.
+- **A few PNG sizes cannot be reached.** The smallest PNG is 73 bytes and the
+  next reachable size is 83, because the chunk that makes up any difference
+  costs 12 bytes on its own. Anything from 83 bytes upward works. Asking for
+  a size in between gets an error naming both neighbours - never a file of a
+  different size.
 - Text files are UTF-8 with LF line endings. Other encodings and line endings
   are not implemented yet.
@@ -97,6 +97,13 @@ func generate(ctx context.Context, args []string, out, errOut io.Writer) int {
 		asJSON   = fs.Bool("json", false, "write the manifest to standard output")
 	)
 
+	// One repeatable flag rather than a separate flag per format property.
+	// Twenty five formats with a dozen properties each would give a surface
+	// nobody reads in --help, and this maps one to one onto the properties
+	// block of a recipe, so both surfaces speak the same words.
+	props := propertyFlag{}
+	fs.Var(&props, "set", "format property, repeatable: --set width=1920 --set height=1080")
+
 	fs.Usage = func() {
 		fmt.Fprint(errOut, "tfg generate - produce files.\n\nFlags:\n")
 		fs.PrintDefaults()
@@ -133,13 +140,14 @@ func generate(ctx context.Context, args []string, out, errOut io.Writer) int {
 	}
 
 	target := engine.Target{
-		ID:       *id,
-		Format:   *formatID,
-		Count:    *count,
-		Bytes:    bytesWanted,
-		NameTmpl: *name,
-		Label:    !*clean,
-		Expected: *expected,
+		ID:         *id,
+		Format:     *formatID,
+		Count:      *count,
+		Bytes:      bytesWanted,
+		NameTmpl:   *name,
+		Label:      !*clean,
+		Expected:   *expected,
+		Properties: props,
 	}
 	opt := engine.Options{
 		OutDir:  *outDir,
@@ -263,6 +271,25 @@ func classify(err error) int {
 	return ExitRuntime
 }
 
+// propertyFlag collects repeated --set key=value pairs.
+type propertyFlag map[string]string
+
+func (p propertyFlag) String() string { return "" }
+
+func (p propertyFlag) Set(v string) error {
+	key, value, found := strings.Cut(v, "=")
+	if !found || key == "" {
+		return fmt.Errorf("expected key=value, got %q", v)
+	}
+	if _, exists := p[key]; exists {
+		// Setting the same property twice is a mistake worth naming. One of
+		// the two values would be lost, and nobody would know which.
+		return fmt.Errorf("%s is set more than once", key)
+	}
+	p[key] = value
+	return nil
+}
+
 func args2(args []string) []string {
 	out := []string{"generate"}
 	return append(out, args...)
 
@@ -8,5 +8,6 @@ package all
 
 import (
 	// Each format registers itself when its package is loaded.
+	_ "github.com/donislawdev/TestingFilesGenerator/internal/format/png"
 	_ "github.com/donislawdev/TestingFilesGenerator/internal/format/txt"
 )
@@ -0,0 +1,81 @@
+package imagelabel
+
+// A 3 by 5 pixel font, drawn here rather than taken from a font file.
+//
+// Two reasons. A font file is a dependency with a licence to check, and this
+// project answers that question often enough already. And a bitmap font is
+// exact - the same label renders to the same pixels on every machine and
+// every version, which the byte stability promise needs.
+//
+// Letters are drawn in upper case only. At three pixels wide, lower case is
+// not legible, and the label is metadata rather than content.
+//
+// Each glyph is five rows of three columns. A '#' is a lit pixel.
+
+const (
+	glyphWidth  = 3
+	glyphHeight = 5
+)
+
+var glyphs = map[rune]string{
+	'A': "###" + "#.#" + "###" + "#.#" + "#.#",
+	'B': "##." + "#.#" + "##." + "#.#" + "##.",
+	'C': "###" + "#.." + "#.." + "#.." + "###",
+	'D': "##." + "#.#" + "#.#" + "#.#" + "##.",
+	'E': "###" + "#.." + "##." + "#.." + "###",
+	'F': "###" + "#.." + "##." + "#.." + "#..",
+	'G': "###" + "#.." + "#.#" + "#.#" + "###",
+	'H': "#.#" + "#.#" + "###" + "#.#" + "#.#",
+	'I': "###" + ".#." + ".#." + ".#." + "###",
+	'J': "..#" + "..#" + "..#" + "#.#" + "###",
+	'K': "#.#" + "#.#" + "##." + "#.#" + "#.#",
+	'L': "#.." + "#.." + "#.." + "#.." + "###",
+	'M': "#.#" + "###" + "###" + "#.#" + "#.#",
+	'N': "#.#" + "###" + "###" + "###" + "#.#",
+	'O': "###" + "#.#" + "#.#" + "#.#" + "###",
+	'P': "###" + "#.#" + "###" + "#.." + "#..",
+	'Q': "###" + "#.#" + "#.#" + "###" + "..#",
+	'R': "###" + "#.#" + "##." + "#.#" + "#.#",
+	'S': "###" + "#.." + "###" + "..#" + "###",
+	'T': "###" + ".#." + ".#." + ".#." + ".#.",
+	'U': "#.#" + "#.#" + "#.#" + "#.#" + "###",
+	'V': "#.#" + "#.#" + "#.#" + "#.#" + ".#.",
+	'W': "#.#" + "#.#" + "###" + "###" + "#.#",
+	'X': "#.#" + "#.#" + ".#." + "#.#" + "#.#",
+	'Y': "#.#" + "#.#" + ".#." + ".#." + ".#.",
+	'Z': "###" + "..#" + ".#." + "#.." + "###",
+
+	'0': "###" + "#.#" + "#.#" + "#.#" + "###",
+	'1': ".#." + "##." + ".#." + ".#." + "###",
+	'2': "###" + "..#" + "###" + "#.." + "###",
+	'3': "###" + "..#" + "###" + "..#" + "###",
+	'4': "#.#" + "#.#" + "###" + "..#" + "..#",
+	'5': "###" + "#.." + "###" + "..#" + "###",
+	'6': "###" + "#.." + "###" + "#.#" + "###",
+	'7': "###" + "..#" + "..#" + "..#" + "..#",
+	'8': "###" + "#.#" + "###" + "#.#" + "###",
+	'9': "###" + "#.#" + "###" + "..#" + "###",
+
+	' ': "..." + "..." + "..." + "..." + "...",
+	'-': "..." + "..." + "###" + "..." + "...",
+	'.': "..." + "..." + "..." + "..." + ".#.",
+	':': "..." + ".#." + "..." + ".#." + "...",
+	'_': "..." + "..." + "..." + "..." + "###",
+	'/': "..#" + "..#" + ".#." + "#.." + "#..",
+	'+': "..." + ".#." + "###" + ".#." + "...",
+	'#': "#.#" + "###" + "#.#" + "###" + "#.#",
+}
+
+// unknown stands in for any character with no glyph, so a label never
+// silently loses part of itself.
+const unknown = "###" + "#.#" + "#.#" + "#.#" + "###"
+
+func glyph(r rune) string {
+	if r >= 'a' && r <= 'z' {
+		r -= 'a' - 'A'
+	}
+	if g, ok := glyphs[r]; ok {
+		return g
+	}
+	return unknown
+}
@@ -0,0 +1,93 @@
+// Package imagelabel draws the self describing label into pixels.
+//
+// Seven image formats burn the same label, so they share one rasteriser
+// rather than carrying seven copies of it.
+package imagelabel
+
+import (
+	"image"
+	"image/color"
+	"image/draw"
+)
+
+// Padding around the text inside its band, in scaled pixels.
+const pad = 2
+
+// Draw burns text into the top left of img and returns the height of the band
+// it used.
+//
+// The band gets a solid background so the text stays readable whatever the
+// picture underneath looks like. Without that, a label over a bright gradient
+// is invisible in exactly the screenshot somebody attaches to a bug report.
+//
+// It draws what fits and stops. A picture too small for the label is not a
+// reason to fail - the caller decides whether to ask for a label at all, and
+// says so in the manifest when it is left out.
+func Draw(img draw.Image, text string) int {
+	b := img.Bounds()
+	if b.Dx() <= 0 || b.Dy() <= 0 || text == "" {
+		return 0
+	}
+
+	scale := scaleFor(b.Dx(), len(text))
+	if scale == 0 {
+		return 0
+	}
+
+	bandH := glyphHeight*scale + 2*pad
+	if bandH > b.Dy() {
+		bandH = b.Dy()
+	}
+
+	band := image.Rect(b.Min.X, b.Min.Y, b.Max.X, b.Min.Y+bandH)
+	draw.Draw(img, band, image.NewUniform(color.RGBA{R: 16, G: 16, B: 16, A: 255}), image.Point{}, draw.Src)
+
+	ink := color.RGBA{R: 240, G: 240, B: 240, A: 255}
+	x := b.Min.X + pad
+	for _, r := range text {
+		if x+glyphWidth*scale > b.Max.X {
+			break
+		}
+		drawGlyph(img, glyph(r), x, b.Min.Y+pad, scale, ink)
+		x += (glyphWidth + 1) * scale
+	}
+	return bandH
+}
+
+// scaleFor picks the largest whole scale at which the whole label fits across
+// the image. Whole numbers only, so a glyph is never resampled and the result
+// is identical on every machine.
+func scaleFor(width, chars int) int {
+	if chars <= 0 {
+		return 0
+	}
+	needed := chars*(glyphWidth+1) + 2*pad
+	for s := 4; s >= 1; s-- {
+		if needed*s <= width {
+			return s
+		}
+	}
+	return 0
+}
+
+func drawGlyph(img draw.Image, g string, x, y, scale int, ink color.Color) {
+	for row := 0; row < glyphHeight; row++ {
+		for col := 0; col < glyphWidth; col++ {
+			if g[row*glyphWidth+col] != '#' {
+				continue
+			}
+			for dy := 0; dy < scale; dy++ {
+				for dx := 0; dx < scale; dx++ {
+					img.Set(x+col*scale+dx, y+row*scale+dy, ink)
+				}
+			}
+		}
+	}
+}
+
+// Fits says whether a label would be drawn at all at this width. The caller
+// needs to know before planning, so that a picture too small to carry one is
+// reported rather than quietly unlabelled.
+func Fits(width, chars int) bool {
+	return scaleFor(width, chars) > 0
+}
Original file line number	Diff line number	Diff line change
`@@ -8,5 +8,6 @@ package all`
`8`	`8`
`9`	`9`	`import (`
`10`	`10`	`// Each format registers itself when its package is loaded.`
	`11`	`+ _ "github.com/donislawdev/TestingFilesGenerator/internal/format/png"`
`11`	`12`	`_ "github.com/donislawdev/TestingFilesGenerator/internal/format/txt"`
`12`	`13`	`)`