test(examples): hold the published catalogue against a fresh render

CHANGELOG.md

@@ -67,6 +67,24 @@ follow semantic versioning; release dates are ISO 8601.
   other, so it catches one being corrected without the other — not a pair that was wrong
   together from the start.
 
+### Tests
+
+- **Every rendered document is now held against a fresh render.** A third of the example
+  catalogue — thirty-two documents, the cover-letter presets and most of the CV gallery
+  among them — rendered on every run with nothing comparing the result, so a change to the
+  engine moved those documents and no test said so. They are committed as previews now,
+  which is what puts them under `CommittedAssetDriftTest`: a PDF is compared by its bytes,
+  and a difference names the file that moved.
+
+  The list of deliberately unpublished documents shrinks from thirty-five entries to three,
+  each carrying its reason. The emoji gallery stays out on weight: its embedded glyph set
+  renders to nearly 4 MB against 1.4 MB for the thirty-two together, so committing it would
+  put another copy of that in history on every deliberate re-render. The other two hold
+  pixels rasterised at render time, which a CI runner antialiases differently from a
+  developer's machine — the measurement `AssetContent` already records — so committing them
+  would fail the build for a document nobody changed. Those three renders stay unguarded,
+  which is the price of the exceptions rather than an oversight.
+
 ### Fixed
 
 - **DOCX keeps the styling a mixed paragraph asks for.** A `RichText` paragraph exported

examples/README.md

@@ -70,10 +70,18 @@ towards.
 `GenerateAllExamples` renders the whole catalogue in one pass — the CV and
 cover-letter presets plus invoices, proposals, a schedule, the feature
 demos, and the flagships. The showcase site publishes the whole generated
-catalogue; a curated subset is committed under
+catalogue, and the same catalogue is committed under
 [`assets/readme/examples/`](../assets/readme/examples/) so the previews
 linked below open straight from GitHub.
 
+Committing them is what lets `CommittedAssetDriftTest` compare each one
+against a fresh render and fail on the difference, so a change to the engine
+that moves a document says so in the build rather than at the next release.
+A PDF is compared by its bytes. Three documents are held back and the guard
+records why for each: the emoji gallery on weight, and two whose pixels this
+repository rasterises at render time, which a CI runner antialiases differently
+from a developer's machine.
+
 ## Gallery — pick by your goal
 
 Examples are categorised by **maturity / intent**, not by the GraphCompose

examples/src/test/java/com/demcha/examples/CommittedAssetDriftTest.java

@@ -62,46 +62,33 @@ class CommittedAssetDriftTest {
      * removes it from its own guard — README would lose a figure and every test would stay
      * green.</p>
      *
-     * <p>Listing what is <em>not</em> published rather than what is keeps the shorter list, and
-     * puts the decision where it is actually made: a new example ships unpublished unless somebody
-     * says otherwise, and saying so is adding a file to the folder and a name off this list.</p>
+     * <p>The list used to carry a third of the catalogue, which meant a third of it rendered with
+     * nothing comparing the result. Those are committed now, so the default is published and this
+     * list is what has to earn an exception. Three do, for two different reasons.</p>
+     *
+     * <p><b>Weight.</b> The emoji gallery embeds a glyph set and renders to nearly 4 MB, against
+     * 1.4 MB for the thirty-two committed alongside it. Committing it would put another copy of
+     * that in history on every deliberate re-render.</p>
+     *
+     * <p><b>The machine, not the document.</b> The other two contain pixels this repository
+     * rasterises at render time, and the same glyphs come out with different antialiasing on
+     * Windows and on the Linux runner — the measurement {@link AssetContent} records, where five
+     * of 104 documents failed to match across the two. Three of those five are absorbed there, by
+     * naming the part and both machines' digests; these two are not, because a PDF is compared
+     * whole and has no part to name, and because the deck's difference is in content it renders
+     * rather than in a part it embeds. Committing them would fail the build on the runner for a
+     * document nobody changed.</p>
+     *
+     * <p>So their renders are unguarded, which is the price of the exception rather than an
+     * oversight — and the reason is recorded per file so a later reader does not re-run the
+     * experiment to find out.</p>
      */
     private static final Set<String> UNPUBLISHED_PREVIEWS = Set.of(
-            "cover-letter-blue-banner-v2.pdf",
-            "cover-letter-boxed-sections-v2.pdf",
-            "cover-letter-centered-headline-v2.pdf",
-            "cover-letter-classic-serif-v2.pdf",
-            "cover-letter-compact-mono-v2.pdf",
-            "cover-letter-editorial-blue-v2.pdf",
-            "cover-letter-engineering-resume-v2.pdf",
-            "cover-letter-executive-v2.pdf",
-            "cover-letter-mint-editorial-v2.pdf",
-            "cover-letter-modern-professional-v2.pdf",
-            "cover-letter-monogram-sidebar-v2.pdf",
-            "cover-letter-nordic-clean-v2.pdf",
-            "cover-letter-panel-v2.pdf",
-            "cover-letter-sidebar-portrait-v2.pdf",
-            "cover-letter-timeline-minimal-v2.pdf",
-            "cv-blue-banner-v2.pdf",
-            "cv-boxed-sections-v2.pdf",
-            "cv-centered-headline-v2.pdf",
-            "cv-editorial-blue-v2.pdf",
-            "cv-executive-v2.pdf",
-            "cv-minimal-underlined-v2.pdf",
-            "cv-mint-editorial-v2-custom.pdf",
-            "cv-mint-editorial-v2.pdf",
-            "cv-monogram-sidebar-v2.pdf",
-            "cv-sidebar-portrait-v2.pdf",
-            "emoji-clip-path.pdf",
+            // Weight: ~4 MB of embedded glyphs.
             "emoji-gallery.pdf",
+            // Rasterised at render time; antialiasing differs between Windows and the runner.
             "emoji-svg-vs-png.pdf",
-            "engine-deck.pptx",
-            "invoice-modern-v2.pdf",
-            "linkedin-carousel.pdf",
-            "linkedin-carousel.pptx",
-            "photo-clip.pdf",
-            "poetry-title.pdf",
-            "proposal-modern-v2.pdf");
+            "engine-deck.pptx");
 
     @BeforeAll
     static void generateEveryExample() throws Exception {