chore(examples): stop the master showcase from dating itself (#470)

* chore(examples): stop the master showcase from dating itself

The showcase was a v1.5 release-status report, re-committed at every release
since. It announced what "v1.5 lands", carried an action item to tag v1.5.0
once develop merged, confirmed a release window for June 2026, and quoted two
benchmark scenarios by name at figures typed in during v1.5. Its metadata
subject and footer named v1.5 as well. The class javadoc calls the document
fictional, but a reader of the PDF sees the real repository name, real
benchmark scenario names and real version numbers, so the props and the claims
were indistinguishable.

Substituting fresh values would have been wrong twice over: it rots again on
the same schedule, and "v1.5 lands the cinematic features" does not become true
by writing 2.1 - those features did land in 1.5.

So the narrative no longer names a version or a date, and the two facts worth
stating are read at render time instead. The version comes from the filtered
banner.properties, the speed figures from the committed perf baseline shown
with its capture date. The examples module now puts that baseline on its own
classpath from where the gate keeps it, rather than holding a second copy that
would drift from the first.

The approval seal reads SAMPLE where it read a quarter and a year, which also
makes the document's fictional half visible in the render rather than only in
the javadoc.

The version lookup moves to a shared helper. It existed only in the deck, and
the deck's own comment explains why it exists - a literal keeps announcing
whichever line it was typed on - which is the same failure this commit repairs
in a second file.

* fix(examples): guard the baseline resource and repair what the extraction left behind

Removing majorMinor from the deck deleted the method but not its javadoc, so
the block was left heading logo() and documenting an @param version that
method does not take.

The showcase javadoc promised "three pages of designed content"; the document
renders two.

The examples job gates on the `code` path filter, which did not list
baselines/. Now that the module renders figures from the committed baseline, a
baseline-only refresh would have changed generated output while skipping the
job that checks it.

PerfBaseline degraded inconsistently: a missing resource was swallowed while a
malformed one threw from a static initializer and would have taken down every
example in the module, not just the one quoting a figure. Loading now never
throws, and a scenario whose figures are absent or non-numeric is treated as
absent rather than read as 0.0 - which would have rendered a plausible
"0.0 ms avg, 0 docs/sec" instead of admitting nothing was measured.

That fallback is honest at render time and wrong to discover in a published
PDF, so PerfBaselineTest asserts the resource really is on the classpath with
the scenarios the showcase quotes. Verified by pointing the pom entry at a
filename that does not exist: on a clean build two of its three tests fail with
the intended message.

Author: DemchaAV

.github/workflows/ci.yml

@@ -79,6 +79,9 @@ jobs:
               - '**/pom.xml'
               - '**/src/main/resources/**'
               - '**/src/test/resources/**'
+              # The examples module renders figures from the committed perf
+              # baseline, so a baseline-only refresh changes generated output.
+              - 'baselines/**'
               - '.mvn/**'
               - 'mvnw'
               - 'mvnw.cmd'

assets/readme/examples/master-showcase.pdf

@@ -146,6 +146,20 @@
                     <exclude>banner.properties</exclude>
                 </excludes>
             </resource>
+            <!--
+                The committed perf baseline, read straight from where the gate
+                keeps it. Examples that quote engine speed restate this file
+                rather than carrying literals, and pointing at the original
+                instead of copying it is what keeps the two from drifting.
+            -->
+            <resource>
+                <directory>${project.basedir}/../baselines</directory>
+                <targetPath>baselines</targetPath>
+                <filtering>false</filtering>
+                <includes>
+                    <include>current-speed-full.json</include>
+                </includes>
+            </resource>
         </resources>
         <plugins>
             <plugin>

assets/readme/examples/master-showcase.pptx

@@ -37,19 +37,16 @@
 import com.demcha.compose.document.svg.SvgIcon;
 import com.demcha.compose.font.FontName;
 import com.demcha.examples.support.ExampleOutputPaths;
+import com.demcha.examples.support.ExampleVersion;
 
 import java.awt.image.BufferedImage;
-import java.io.IOException;
 import java.io.InputStream;
 import java.nio.charset.StandardCharsets;
 import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Locale;
 import java.util.Objects;
-import java.util.Properties;
-import java.util.regex.Matcher;
-import java.util.regex.Pattern;
 
 /**
  * Parallel 2.0 release concept for the GraphCompose README hero and engine
@@ -116,7 +113,7 @@ public final class EngineDeckV2Example {
     private static final DocumentColor PALE_BLUE = DocumentColor.rgb(232, 243, 255);
     private static final DocumentColor PALE_MINT = DocumentColor.rgb(230, 249, 242);
 
-    private static final String VERSION = loadVersion();
+    private static final String VERSION = ExampleVersion.current();
 
     /**
      * The {@code major.minor} of {@link #VERSION}, for the banner's prose labels.
@@ -125,7 +122,7 @@ public final class EngineDeckV2Example {
      * so a literal would keep announcing whichever line it was typed on — the hero
      * still read "2.0" while the pill beside it read v2.1.0.</p>
      */
-    private static final String VERSION_LINE = majorMinor(VERSION);
+    private static final String VERSION_LINE = ExampleVersion.majorMinor(VERSION);
 
     private EngineDeckV2Example() {
     }
@@ -912,31 +909,6 @@ private static String snapshotDate(EngineDeckData.BenchRun bench) {
         return timestamp.substring(0, Math.min(10, timestamp.length()));
     }
 
-    /**
-     * Reduces a version to its {@code major.minor} line for display.
-     *
-     * @param version the resolved build version, possibly a qualifier or {@code "dev"}
-     * @return {@code "2.1"} for {@code "2.1.0"} / {@code "2.1.0-SNAPSHOT"}; the input
-     *         unchanged when it carries no dotted numeric prefix
-     */
-    private static String majorMinor(String version) {
-        Matcher matcher = Pattern.compile("^(\\d+)\\.(\\d+)").matcher(version);
-        return matcher.find() ? matcher.group(1) + "." + matcher.group(2) : version;
-    }
-
-    private static String loadVersion() {
-        Properties banner = new Properties();
-        try (InputStream in = EngineDeckV2Example.class.getResourceAsStream("/banner.properties")) {
-            if (in != null) {
-                banner.load(in);
-            }
-        } catch (IOException ignored) {
-            // Fall through to the development label below.
-        }
-        String value = banner.getProperty("version");
-        return value == null || value.isBlank() || value.startsWith("@") ? "dev" : value.trim();
-    }
-
     private static SvgIcon logo() {
         return icon("logo");
     }

examples/pom.xml

@@ -23,8 +23,11 @@
 import com.demcha.examples.support.theme.BusinessTheme;
 import com.demcha.compose.font.FontName;
 import com.demcha.examples.support.ExampleOutputPaths;
+import com.demcha.examples.support.ExampleVersion;
+import com.demcha.examples.support.PerfBaseline;
 
 import java.nio.file.Path;
+import java.util.Locale;
 
 /**
  * Kitchen-sink showcase combining the canonical surface end-to-end —
@@ -34,10 +37,17 @@
  * QR + Code 128 barcodes, document metadata, and header / footer chrome.
  *
  * <p>The rendered PDF reads like a fictional "GraphCompose Q2 Sample
- * Report" — three pages of designed content meant to look at a glance
+ * Report" — designed content meant to look at a glance
  * like the kind of business document GraphCompose was built to
  * generate, not a feature checklist. Use it as a reference when
  * composing your own multi-page documents.</p>
+ *
+ * <p>The narrative is deliberately undated. This file is regenerated and
+ * re-committed on every release, so anything that names a version, a date or a
+ * measurement would go stale between one release and the next — as it did. What
+ * survives is either sample copy that cannot age or a figure read at render time
+ * from {@link com.demcha.examples.support.PerfBaseline} and
+ * {@link com.demcha.examples.support.ExampleVersion}.</p>
  */
 public final class MasterShowcaseExample {
     private static final BusinessTheme THEME = BusinessTheme.modern();
@@ -90,7 +100,7 @@ static void compose(DocumentSession document) {
         document.metadata(DocumentMetadata.builder()
                 .title("GraphCompose master showcase")
                 .author("Jordan Rivera")
-                .subject("Comprehensive end-to-end demo of the v1.5 canonical surface")
+                .subject("Comprehensive end-to-end demo of the canonical document surface")
                 .keywords("graphcompose, showcase, business, theme, rich-text, table, shape, transform, barcode")
                 .creator("GraphCompose Examples")
                 .producer("GraphCompose")
@@ -109,7 +119,7 @@ static void compose(DocumentSession document) {
 
         document.footer(DocumentHeaderFooter.builder()
                 .zone(DocumentHeaderFooterZone.FOOTER)
-                .leftText("v1.5 — \"intuitive\" release")
+                .leftText("GraphCompose " + ExampleVersion.currentLine() + " — sample report")
                 .rightText("Page {page} of {pages}")
                 .fontSize(9f)
                 .textColor(MUTED)
@@ -165,16 +175,17 @@ static void compose(DocumentSession document) {
                                         .plain("Status: ")
                                         .bold("On track")
                                         .plain(" — ")
-                                        .accent("675 / 675 tests green", BRAND)
-                                        .plain(" — Q2 release window confirmed for ")
-                                        .underline("June 2026")
+                                        .accent("every gate green", BRAND)
+                                        .plain(" — release window confirmed for the ")
+                                        .underline("current quarter")
                                         .plain("."))
                                 .addRich(rich -> rich
                                         .plain("Performance: ")
                                         .color("invoice-template", BRAND_DEEP)
-                                        .plain(" 13.4 ms avg, 75 docs/sec; ")
+                                        .plain(" " + speed("invoice-template") + "; ")
                                         .color("feature-rich", BRAND_DEEP)
-                                        .plain(" 36.8 ms avg, 27 docs/sec.")))
+                                        .plain(" " + speed("feature-rich") + ". One machine, "
+                                               + PerfBaseline.get().capturedOn() + ".")))
                         .addSection("Seal", section -> section
                                 .padding(DocumentInsets.of(2))
                                 .addCircle(118, BRAND, circle -> circle
@@ -187,7 +198,7 @@ static void compose(DocumentSession document) {
                                                 style(FontName.HELVETICA_BOLD, 13,
                                                         DocumentTextDecoration.BOLD,
                                                         DocumentColor.WHITE)))
-                                        .position(label("Q2 / 2026",
+                                        .position(label("SAMPLE",
                                                         style(FontName.HELVETICA_BOLD, 7.5,
                                                                 DocumentTextDecoration.BOLD,
                                                                 SOFT_GOLD)),
@@ -222,7 +233,7 @@ static void compose(DocumentSession document) {
                                 .textStyle(THEME.text().h2())
                                 .margin(DocumentInsets.zero()))
                         .addRich(rich -> rich
-                                .plain("v1.5 lands the cinematic features that turn GraphCompose from \"tidy PDF layouter\" into a designed-document engine: ")
+                                .plain("The features below are what turn GraphCompose from a \"tidy PDF layouter\" into a designed-document engine: ")
                                 .bold("shape-as-container with clip path")
                                 .plain(", ")
                                 .bold("rotate / scale + per-layer z-index")
@@ -314,7 +325,7 @@ static void compose(DocumentSession document) {
                         .addSection("Card3", section -> highlightCard(section,
                                 "Transformable mixin",
                                 "rotate / scale on every shape",
-                                "v1.5 extends Transformable<T> to every leaf builder so any shape rotates around its placement centre.")))
+                                "Transformable<T> reaches every leaf builder, so any shape rotates around its placement centre.")))
 
                 // ───── Action items + status legend ─────
                 .addSection("ActionItems", section -> section
@@ -328,9 +339,9 @@ static void compose(DocumentSession document) {
                                 .textStyle(THEME.text().h2())
                                 .margin(DocumentInsets.zero()))
                         .addRich(rich -> rich
-                                .plain("• Tag ")
-                                .bold("v1.5.0")
-                                .plain(" on main once develop is merged through PR. ")
+                                .plain("• Publish the release notes once the branch ")
+                                .bold("merges through review")
+                                .plain(". ")
                                 .accent("Owner: maintainer", BRAND)
                                 .plain("."))
                         .addRich(rich -> rich
@@ -360,7 +371,7 @@ static void compose(DocumentSession document) {
                                 .padding(DocumentInsets.zero())
                                 .addBarcode(barcode -> barcode
                                         .code128()
-                                        .data("GC-MASTER-Q2-2026")
+                                        .data("GC-MASTER-SAMPLE")
                                         .foreground(BRAND)
                                         .size(180, 36))))
                 .build();
@@ -403,6 +414,23 @@ private static DocumentNode label(String text, DocumentTextStyle style) {
                 .build();
     }
 
+    /**
+     * One scenario's measured speed, phrased for the report.
+     *
+     * <p>Restates the committed baseline rather than a literal, so the figure
+     * moves when the measurement does instead of when somebody remembers.</p>
+     *
+     * @param scenario benchmark scenario name
+     * @return e.g. {@code "6.6 ms avg, 152 docs/sec"}, or a plain note when the
+     *         baseline does not carry the scenario
+     */
+    private static String speed(String scenario) {
+        return PerfBaseline.get().scenario(scenario)
+                .map(measured -> String.format(Locale.ROOT, "%.1f ms avg, %.0f docs/sec",
+                        measured.avgMillis(), measured.docsPerSecond()))
+                .orElse("not measured");
+    }
+
     private static DocumentTextStyle label() {
         return DocumentTextStyle.builder()
                 .fontName(FontName.HELVETICA_BOLD)

examples/src/main/java/com/demcha/examples/flagships/EngineDeckV2Example.java

@@ -0,0 +1,71 @@
+package com.demcha.examples.support;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.Properties;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * The reactor version, for examples that print it.
+ *
+ * <p>Read from the filtered {@code banner.properties} rather than written out,
+ * because example documents are regenerated on every release: a literal keeps
+ * announcing whichever line it was typed on. Shared so the value cannot drift
+ * between the documents that show it.</p>
+ */
+public final class ExampleVersion {
+
+    private static final Pattern MAJOR_MINOR = Pattern.compile("^(\\d+)\\.(\\d+)");
+
+    private static final String CURRENT = load();
+
+    private ExampleVersion() {
+    }
+
+    /**
+     * The full reactor version, or {@code "dev"} when the resource is absent or
+     * unfiltered (running straight from sources).
+     *
+     * @return version string
+     */
+    public static String current() {
+        return CURRENT;
+    }
+
+    /**
+     * The {@code major.minor} of {@link #current()}, for prose that names a line
+     * rather than a patch.
+     *
+     * @return the leading {@code major.minor}, or the version unchanged when it
+     *         carries no dotted numeric prefix
+     */
+    public static String currentLine() {
+        return majorMinor(CURRENT);
+    }
+
+    /**
+     * Reduces a version to its {@code major.minor} prefix.
+     *
+     * @param version version string to reduce
+     * @return the leading {@code major.minor}, or {@code version} unchanged when
+     *         it carries no dotted numeric prefix
+     */
+    public static String majorMinor(String version) {
+        Matcher matcher = MAJOR_MINOR.matcher(version);
+        return matcher.find() ? matcher.group(1) + "." + matcher.group(2) : version;
+    }
+
+    private static String load() {
+        Properties banner = new Properties();
+        try (InputStream in = ExampleVersion.class.getResourceAsStream("/banner.properties")) {
+            if (in != null) {
+                banner.load(in);
+            }
+        } catch (IOException ignored) {
+            // Fall through to the development label below.
+        }
+        String value = banner.getProperty("version");
+        return value == null || value.isBlank() || value.startsWith("@") ? "dev" : value.trim();
+    }
+}