Add AOT cache support for generator fat JAR

- Add build-cds.sh script to create Java 25 AOT cache (~21MB)
- AOT cache reduces warm time from 0.46s to 0.27s (~40% faster)
- Add .gitignore entries for platform-specific cache files
- Update README and BENCHMARK with AOT cache instructions and results

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: brunoborges

.gitignore

@@ -12,3 +12,8 @@ site/tooling/*.html
 
 # Generated aggregate file (built from individual JSON sources by html-generators/)
 site/data/snippets.json
+
+# Platform-specific CDS/AOT cache (generated by build-cds.sh)
+html-generators/generate.aot
+html-generators/generate.jsa
+html-generators/generate.classlist

html-generators/BENCHMARK.md

@@ -1,24 +1,38 @@
 # Generator Benchmarks
 
-Performance comparison of the three ways to run the HTML generator, measured on 85 snippets across 10 categories.
+Performance comparison of the four ways to run the HTML generator, measured on 85 snippets across 10 categories.
 
 ## Results
 
 | Method | Cold Start | Warm Average | Notes |
 |--------|-----------|-------------|-------|
-| **Fat JAR** (`java -jar`) | 1.72s | **0.46s** | Fastest warm; no JBang needed |
+| **Fat JAR + AOT** (`java -XX:AOTCache`) | 0.27s | **0.27s** | Fastest; requires one-time cache build |
+| **Fat JAR** (`java -jar`) | 1.72s | 0.46s | No setup needed |
 | **JBang** (`jbang generate.java`) | 0.96s | 0.77s | Includes JBang overhead |
 | **Python** (`python3 generate.py`) | 0.17s | 1.37s | Fastest cold start; slowest warm |
 
 - **Cold start**: First run after clearing caches / fresh process
-- **Warm average**: Mean of 4 subsequent runs
+- **Warm average**: Mean of 4 subsequent runs (AOT: mean of 5, no cold penalty)
 
 ## Key Takeaways
 
-- The **fat JAR** is the fastest option for repeated builds — **~40% faster** than JBang and **~3× faster** than Python at warm steady-state
+- The **fat JAR + AOT cache** is the fastest option — **~40% faster** than the plain fat JAR and **~5× faster** than Python
+- The AOT cache eliminates the JVM cold start penalty entirely (0.27s cold = 0.27s warm)
 - **Python** has the fastest cold start (no JVM boot) but is the slowest overall
 - **JBang** adds ~0.3s overhead vs the fat JAR due to its launcher and cache lookup
-- For CI/CD, the fat JAR is ideal — no JBang installation or dependency caching required
+- For CI/CD, the plain fat JAR is ideal — no AOT build step needed, and still very fast
+
+## AOT Cache Setup
+
+```bash
+# One-time: build the cache (~21 MB, platform-specific)
+./html-generators/build-cds.sh
+
+# Use it
+java -XX:AOTCache=html-generators/generate.aot -jar html-generators/generate.jar
+```
+
+The AOT cache uses Java 25 CDS (JEP 514/515) to pre-load ~3,300 classes from a training run. It is platform-specific (CPU arch + JDK version) and not committed to git.
 
 ## Environment
 

html-generators/README.md

@@ -9,6 +9,7 @@ This folder contains the build scripts that generate all HTML detail pages and `
 | `generate.java` | JBang script (Java 25) — primary generator |
 | `generate.py` | Python equivalent — produces identical output |
 | `generate.jar` | Pre-built fat JAR (no JBang/JDK setup needed) |
+| `build-cds.sh` | Script to build a platform-specific AOT cache |
 
 ## Running
 
@@ -20,15 +21,27 @@ java -jar html-generators/generate.jar
 
 Requires only a Java 25+ runtime — no JBang installation needed.
 
-### Option 2: JBang (for development)
+### Option 2: Fat JAR with AOT cache (fastest possible)
+
+```bash
+# One-time: build the AOT cache (~21 MB, platform-specific)
+./html-generators/build-cds.sh
+
+# Subsequent runs use the cache
+java -XX:AOTCache=html-generators/generate.aot -jar html-generators/generate.jar
+```
+
+The AOT cache (Java 25, JEP 514/515) pre-loads classes from a training run, reducing startup time by ~30%. The cache is platform-specific and is not committed to git — regenerate it after changing the JAR or JDK version.
+
+### Option 3: JBang (for development)
 
 ```bash
 jbang html-generators/generate.java
 ```
 
 Requires [JBang](https://jbang.dev) and Java 25+.
 
-### Option 3: Python
+### Option 4: Python
 
 ```bash
 python3 html-generators/generate.py

html-generators/build-cds.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Build an App CDS / AOT cache for the generator fat JAR.
+# The cache is platform-specific and must be regenerated when
+# the JAR or JDK version changes.
+#
+# Usage:
+#   ./html-generators/build-cds.sh          # creates generate.aot
+#   java -XX:AOTCache=html-generators/generate.aot -jar html-generators/generate.jar
+
+set -euo pipefail
+cd "$(git rev-parse --show-toplevel)"
+
+JAR="html-generators/generate.jar"
+AOT="html-generators/generate.aot"
+
+echo "Training run + AOT cache generation..."
+java -XX:AOTCacheOutput="$AOT" -jar "$JAR"
+echo "Done: $AOT ($(du -h "$AOT" | cut -f1))"
+echo ""
+echo "Run with:  java -XX:AOTCache=$AOT -jar $JAR"