fix(gallery): gate committed gallery drift in CI and prune stale pages (#211)

Found in a review of the Pages site:

- docs/gallery/ is committed but regenerated at deploy, so a stale commit
  shipped fine and drifted silently. Validate now regenerates it and fails
  on any diff.
- build_gallery.py never removed the page folder of a renamed or removed
  entry, so the old page stayed published. It now deletes folders that
  hold only a generated index.html and match no entry.
- signpost-preview.webp and wall-torch-preview.webp in docs/gallery/assets
  were referenced by nothing and still published.
- The tag filter offered both "render" and "rendering", and both
  "transform" and "transforms". Merged into the majority spelling.

Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: TMHSDigital

.github/workflows/validate.yml

@@ -142,6 +142,20 @@ jobs:
       - name: Check falsifiers declare the budget they target
         run: python3 tests/check_falsifier_targets.py
 
+      - name: Check committed gallery matches its generator
+        # docs/gallery/ is committed, but pages.yml regenerates it at deploy, so a
+        # stale commit ships fine and drifts silently. Regenerate and require no diff.
+        run: |
+          python3 scripts/build_gallery.py
+          drift=$(git status --porcelain -- docs/gallery)
+          if [ -n "$drift" ]; then
+            echo "::error::docs/gallery/ is stale. Run 'python scripts/build_gallery.py' and commit the result."
+            echo "$drift"
+            git --no-pager diff --stat -- docs/gallery
+            exit 1
+          fi
+          echo "docs/gallery/ matches scripts/build_gallery.py output."
+
       - name: Validate template Python syntax
         run: |
           echo "Checking template Python syntax..."

docs/gallery/assets/signpost-preview.webp

@@ -323,13 +323,11 @@ <h1>Examples and Showcase</h1>
         <button class="chip" data-tag="parenting" type="button">parenting</button>
         <button class="chip" data-tag="performance" type="button">performance</button>
         <button class="chip" data-tag="properties" type="button">properties</button>
-        <button class="chip" data-tag="render" type="button">render</button>
         <button class="chip" data-tag="rendering" type="button">rendering</button>
         <button class="chip" data-tag="sequencer" type="button">sequencer</button>
         <button class="chip" data-tag="shape-keys" type="button">shape-keys</button>
         <button class="chip" data-tag="showcase" type="button">showcase</button>
         <button class="chip" data-tag="sky" type="button">sky</button>
-        <button class="chip" data-tag="transform" type="button">transform</button>
         <button class="chip" data-tag="transforms" type="button">transforms</button>
         <button class="chip" data-tag="uv" type="button">uv</button>
         <button class="chip" data-tag="world" type="button">world</button>
@@ -712,7 +710,7 @@ <h2><a href="custom-normals-shade/">custom-normals-shade</a></h2>
           <a class="card-link" href="custom-normals-shade/">View example<span class="sr-only"> custom-normals-shade</span> <span aria-hidden="true">&rarr;</span></a>
         </div>
       </article>
-      <article class="card" data-tags="world sky render">
+      <article class="card" data-tags="world sky rendering">
         <a class="card-media" href="sky-texture-sun-elevation/" tabindex="-1" aria-hidden="true">
           <img src="assets/sky-texture-sun-elevation-hero.webp" alt="sky-texture-sun-elevation — World ShaderNodeTexSky driving Background Color — the sky contract across 4.5 LTS and 5.1." loading="lazy" decoding="async" />
         </a>
@@ -745,7 +743,7 @@ <h2><a href="mesh-hygiene-audit/">mesh-hygiene-audit</a></h2>
           <a class="card-link" href="mesh-hygiene-audit/">View example<span class="sr-only"> mesh-hygiene-audit</span> <span aria-hidden="true">&rarr;</span></a>
         </div>
       </article>
-      <article class="card" data-tags="transform parenting game-pipeline">
+      <article class="card" data-tags="transforms parenting game-pipeline">
         <a class="card-media" href="prop-origin-transform/" tabindex="-1" aria-hidden="true">
           <img src="assets/prop-origin-transform-hero.webp" alt="prop-origin-transform — Street pedestal origin-to-base-center + data-API scale apply + matrix_parent_inverse for a flanged conduit accessory." loading="lazy" decoding="async" />
         </a>
@@ -811,7 +809,7 @@ <h2><a href="modular-kit-snap/">modular-kit-snap</a></h2>
           <a class="card-link" href="modular-kit-snap/">View example<span class="sr-only"> modular-kit-snap</span> <span aria-hidden="true">&rarr;</span></a>
         </div>
       </article>
-      <article class="card" data-tags="uv game-pipeline render">
+      <article class="card" data-tags="uv game-pipeline rendering">
         <a class="card-media" href="lightmap-uv-channel/" tabindex="-1" aria-hidden="true">
           <img src="assets/lightmap-uv-channel-hero.webp" alt="lightmap-uv-channel — A market cart carrying the two-channel UV contract for baked lighting: UV0 untouched, UVLight packed with no overlaps and a respected margin." loading="lazy" decoding="async" />
         </a>
@@ -833,7 +831,7 @@ <h2><a href="socket-attach-points/">socket-attach-points</a></h2>
           <a class="card-link" href="socket-attach-points/">View example<span class="sr-only"> socket-attach-points</span> <span aria-hidden="true">&rarr;</span></a>
         </div>
       </article>
-      <article class="card" data-tags="mesh attributes game-pipeline render">
+      <article class="card" data-tags="mesh attributes game-pipeline rendering">
         <a class="card-media" href="vertex-color-ao/" tabindex="-1" aria-hidden="true">
           <img src="assets/vertex-color-ao-hero.webp" alt="vertex-color-ao — A stone well carrying baked ambient occlusion in a colour attribute, with the bake held to the closed-form hemisphere integral rather than to a captured value." loading="lazy" decoding="async" />
         </a>

docs/gallery/assets/wall-torch-preview.webp

@@ -432,7 +432,7 @@
       "tags": [
         "world",
         "sky",
-        "render"
+        "rendering"
       ]
     },
     {
@@ -469,7 +469,7 @@
       "hero": "docs/gallery/assets/prop-origin-transform-hero.webp",
       "preview": "examples/prop-origin-transform/preview.webp",
       "tags": [
-        "transform",
+        "transforms",
         "parenting",
         "game-pipeline"
       ]
@@ -551,7 +551,7 @@
       "tags": [
         "uv",
         "game-pipeline",
-        "render"
+        "rendering"
       ]
     },
     {
@@ -579,7 +579,7 @@
         "mesh",
         "attributes",
         "game-pipeline",
-        "render"
+        "rendering"
       ]
     },
     {

docs/gallery/index.html

@@ -1059,6 +1059,16 @@ def main() -> int:
             encoding="utf-8",
         )
 
+    # A renamed or removed entry would otherwise leave its old page published
+    # forever. Only folders this generator wrote qualify: a lone index.html
+    # and nothing else, so assets/, contact-sheets/ and asset-sheets/ are safe.
+    names = {ex["name"] for ex in examples}
+    for d in sorted(p for p in OUT_DIR.iterdir() if p.is_dir() and p.name not in names):
+        if [c.name for c in d.iterdir()] == ["index.html"]:
+            (d / "index.html").unlink()
+            d.rmdir()
+            print(f"Removed stale page {d.relative_to(REPO)}")
+
     n_showcase = sum(1 for ex in examples if "showcase" in (ex.get("tags") or []))
     print(
         f"Wrote {OUT_DIR / 'index.html'} + {len(examples)} detail pages "