fix(examples): gate compositor-glare and collision-hull-proxy stills; lint every gallery entry

These were the only 2 of 132 gallery entries whose render path never called
gallery_framing, so their framing was eyeballed, not measured.
collision-hull-proxy is also in the pinned asset-quality reference set yet
never ran the asset-quality floors.

- compositor-glare: check_framing (hero and elements = the rings, stage =
  floor) before the beauty render; exit 10. render_still now returns a code.
- collision-hull-proxy: check_framing (hero = hydrant, elements = hydrant +
  hulls, stage = floor + wall; exit 10) and check_asset_quality on the
  hydrant (exit 11), both before the render.
- READMEs list the new exits.
- tests/check_render_gates.py (in Validate): every directory in
  examples/gallery.json or showcase/gallery.json must import gallery_framing
  and call check_framing or measure_framing_deviation. 132/132 pass.

Proof (local, .scratch/blender-5.2.1-windows-x64, 5.2.1 LTS, EEVEE):
- compositor-glare --output: framing_fill x=0.734 ok, margins min 0.117 ok,
  exit 0. Probe: camera pulled back to y=-30 -> "framing violation ...
  fill x=0.219 FAIL".
- collision-hull-proxy --output: framing_fill y=0.833 ok, margins ok;
  aq_naming ok, materials n=4 dominant 0.50 ok, edge90 0.035 ok; exit 0.
- Both gates passed as composed, so the committed heroes are unchanged.
- check_render_gates on the pre-fix compositor_glare.py reports it.

Closes #342

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: TMHSDigital

.github/workflows/validate.yml

@@ -70,6 +70,9 @@ jobs:
       - name: Check EEVEE engine-id mappings
         run: python3 tests/check_engine_id.py
 
+      - name: Every gallery still is gated by gallery_framing
+        run: python3 tests/check_render_gates.py
+
       - name: Check falsifiers declare the budget they target
         run: python3 tests/check_falsifier_targets.py
 

docs/gallery/collision-hull-proxy/index.html

@@ -81,16 +81,16 @@ <h2 id="run">Run<a class="anchor" href="#run" aria-label="Link to this section">
 blender --background --python collision_hull_proxy.py -- --output hydrant.png --engine cycles</code></pre>
 <h2 id="exit-codes">Exit codes<a class="anchor" href="#exit-codes" aria-label="Link to this section">#</a></h2>
 <p>Per-script sequential checks. <code>9</code> is a valid check code; there is no rule against it.</p>
-<div class="table-wrap"><table><thead><tr><th scope="col">Code</th><th scope="col">Meaning</th></tr></thead><tbody><tr><td>0</td><td>Success</td></tr><tr><td>1</td><td>Uncaught exception (FATAL wrapper)</td></tr><tr><td>2</td><td>argparse / usage</td></tr><tr><td>3</td><td>Render vertex escapes its hull (<code>--shrink-hull</code> lands here)</td></tr><tr><td>4</td><td>Hull edge does not border exactly two faces</td></tr><tr><td>5</td><td>Signed volume ≤ 0 (inverted winding)</td></tr><tr><td>6</td><td>Hull vertex off its own face plane</td></tr><tr><td>7</td><td>Euler characteristic ≠ 2</td></tr><tr><td>8</td><td>Piece over the 255-face collision budget</td></tr><tr><td>9</td><td><code>--output</code> produced no file</td></tr></tbody></table></div>
+<div class="table-wrap"><table><thead><tr><th scope="col">Code</th><th scope="col">Meaning</th></tr></thead><tbody><tr><td>0</td><td>Success</td></tr><tr><td>1</td><td>Uncaught exception (FATAL wrapper)</td></tr><tr><td>2</td><td>argparse / usage</td></tr><tr><td>3</td><td>Render vertex escapes its hull (<code>--shrink-hull</code> lands here)</td></tr><tr><td>4</td><td>Hull edge does not border exactly two faces</td></tr><tr><td>5</td><td>Signed volume ≤ 0 (inverted winding)</td></tr><tr><td>6</td><td>Hull vertex off its own face plane</td></tr><tr><td>7</td><td>Euler characteristic ≠ 2</td></tr><tr><td>8</td><td>Piece over the 255-face collision budget</td></tr><tr><td>9</td><td><code>--output</code> produced no file</td></tr><tr><td>10</td><td>Gallery framing violation (render path)</td></tr><tr><td>11</td><td>Gallery asset-quality violation (render path)</td></tr></tbody></table></div>
 <p>The <code>blender-smoke</code> workflow runs the check on Blender 5.2 LTS and 4.5 LTS (5.1 on the weekly cron, the <code>needs-5.1</code> PR label, or manual dispatch). Smoke does not pass <code>--output</code> or <code>--shrink-hull</code>.</p>
     </section>
     <section class="detail-section src" id="source">
       <h2>Source</h2>
       <div class="src-meta">
         <code>examples/collision-hull-proxy/collision_hull_proxy.py</code>
-        <span>524 lines &middot; <a href="https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/collision-hull-proxy/collision_hull_proxy.py">View on GitHub &rarr;</a></span>
+        <span>549 lines &middot; <a href="https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/collision-hull-proxy/collision_hull_proxy.py">View on GitHub &rarr;</a></span>
       </div>
-      <div class="code" data-lines="524">
+      <div class="code" data-lines="549">
 <pre class="gutter" aria-hidden="true">1
 2
 3
@@ -614,7 +614,32 @@ <h2>Source</h2>
 521
 522
 523
-524</pre><pre class="code-lines"><span class="s">&quot;&quot;&quot;A fire hydrant prop plus its convex collision proxies — a runnable example.
+524
+525
+526
+527
+528
+529
+530
+531
+532
+533
+534
+535
+536
+537
+538
+539
+540
+541
+542
+543
+544
+545
+546
+547
+548
+549</pre><pre class="code-lines"><span class="s">&quot;&quot;&quot;A fire hydrant prop plus its convex collision proxies — a runnable example.
 
 Witnesses the collision contract every game prop pipeline (engines generally,
 FiveM/GTA-style prop workflows specifically) depends on: a prop&#x27;s collision is
@@ -654,6 +679,13 @@ <h2>Source</h2>
 <span class="k">import</span> bpy, bmesh, sys, os, math, argparse
 <span class="k">from</span> mathutils <span class="k">import</span> Vector
 
+<span class="c"># Shared render gates (render path only) — see gallery_framing.py and</span>
+<span class="c"># gallery_asset_quality.py</span>
+sys.path.insert(<span class="n">0</span>, os.path.join(os.path.dirname(os.path.abspath(__file__)), os.pardir))
+sys.dont_write_bytecode = <span class="k">True</span>  <span class="c"># keep examples/__pycache__ out of the repo tree</span>
+<span class="k">import</span> gallery_framing
+<span class="k">import</span> gallery_asset_quality
+
 SEGMENTS = <span class="n">48</span>          <span class="c"># lathe resolution of the render mesh</span>
 CAGE_SEG_BODY = <span class="n">8</span>      <span class="c"># collision cage resolutions — the hull face budget</span>
 CAGE_SEG_CAP = <span class="n">8</span>       <span class="c">#   is spent through these, not through SEGMENTS</span>
@@ -1096,8 +1128,26 @@ <h2>Source</h2>
     scene.render.filepath = path
     <span class="c"># AgX would flatten the enamel toward pastel (docs/VISUAL-STYLE.md)</span>
     scene.view_settings.view_transform = <span class="s">&#x27;Standard&#x27;</span>
+    <span class="c"># Layer 1 framing gate and the asset-quality floors, both before the</span>
+    <span class="c"># beauty render so a defective still ships no artifact. The hero is the</span>
+    <span class="c"># hydrant itself; its hulls are framed elements too.</span>
+    hydrant = [o <span class="k">for</span> g <span class="k">in</span> groups <span class="k">for</span> o <span class="k">in</span> g[<span class="s">&quot;render&quot;</span>]]
+    hulls = [hull <span class="k">for</span> _, hull, _ <span class="k">in</span> pieces]
+    fcode = gallery_framing.check_framing(
+        scene, cam, hero=hydrant, elements=hydrant + hulls, stage=[floor, wall],
+    )
+    <span class="k">if</span> fcode:
+        <span class="k">return</span> fcode
+    acode = gallery_asset_quality.check_asset_quality(
+        scene, cam, hydrant, stage=[floor, wall],
+    )
+    <span class="k">if</span> acode:
+        <span class="k">return</span> acode
     bpy.ops.render.render(write_still=<span class="k">True</span>)
-    <span class="k">return</span> os.path.exists(path) <span class="k">and</span> os.path.getsize(path) &gt; <span class="n">0</span>
+    <span class="k">if</span> <span class="k">not</span> (os.path.exists(path) <span class="k">and</span> os.path.getsize(path) &gt; <span class="n">0</span>):
+        print(<span class="s">&quot;ERROR: render produced no file&quot;</span>, file=sys.stderr)
+        <span class="k">return</span> <span class="n">9</span>
+    <span class="k">return</span> <span class="n">0</span>
 
 
 <span class="k">def</span> main():
@@ -1124,9 +1174,9 @@ <h2>Source</h2>
         <span class="k">return</span> code
 
     <span class="k">if</span> args.output:
-        <span class="k">if</span> <span class="k">not</span> render_still(groups, pieces, os.path.abspath(args.output), args.engine):
-            print(<span class="s">&quot;ERROR: render produced no file&quot;</span>, file=sys.stderr)
-            <span class="k">return</span> <span class="n">9</span>
+        rcode = render_still(groups, pieces, os.path.abspath(args.output), args.engine)
+        <span class="k">if</span> rcode:
+            <span class="k">return</span> rcode
         print(<span class="s">f&quot;</span><span class="s">rendered still </span>{args.output}<span class="s">&quot;</span>)
 
     print(<span class="s">&quot;collision-hull-proxy OK&quot;</span>)

docs/gallery/compositor-glare/index.html

@@ -76,16 +76,16 @@ <h2 id="run">Run<a class="anchor" href="#run" aria-label="Link to this section">
 blender --background --python compositor_glare.py -- --output rings.png --engine cycles</code></pre>
 <h2 id="exit-codes">Exit codes<a class="anchor" href="#exit-codes" aria-label="Link to this section">#</a></h2>
 <p>Per-script sequential checks. <code>9</code> is a valid check code; there is no rule against it.</p>
-<div class="table-wrap"><table><thead><tr><th scope="col">Code</th><th scope="col">Meaning</th></tr></thead><tbody><tr><td>0</td><td>Success</td></tr><tr><td>1</td><td>Uncaught exception (FATAL wrapper)</td></tr><tr><td>2</td><td>argparse / usage</td></tr><tr><td>3</td><td>Compositor tree / Glare / Threshold / link-chain contract (<code>--threshold-high</code> lands here)</td></tr><tr><td>4</td><td>Check render missing, tube dark, no halo, or halo does not fall off</td></tr><tr><td>5</td><td>Halo present with compositing off</td></tr><tr><td>6</td><td><code>--output</code> produced no file</td></tr></tbody></table></div>
+<div class="table-wrap"><table><thead><tr><th scope="col">Code</th><th scope="col">Meaning</th></tr></thead><tbody><tr><td>0</td><td>Success</td></tr><tr><td>1</td><td>Uncaught exception (FATAL wrapper)</td></tr><tr><td>2</td><td>argparse / usage</td></tr><tr><td>3</td><td>Compositor tree / Glare / Threshold / link-chain contract (<code>--threshold-high</code> lands here)</td></tr><tr><td>4</td><td>Check render missing, tube dark, no halo, or halo does not fall off</td></tr><tr><td>5</td><td>Halo present with compositing off</td></tr><tr><td>6</td><td><code>--output</code> produced no file</td></tr><tr><td>10</td><td>Gallery framing violation (render path; checked before the beauty render)</td></tr></tbody></table></div>
 <p>The <code>blender-smoke</code> workflow runs the check on Blender 5.2 LTS and 4.5 LTS (5.1 on the weekly cron, the <code>needs-5.1</code> PR label, or manual dispatch). Smoke does not pass <code>--output</code> or <code>--threshold-high</code>.</p>
     </section>
     <section class="detail-section src" id="source">
       <h2>Source</h2>
       <div class="src-meta">
         <code>examples/compositor-glare/compositor_glare.py</code>
-        <span>379 lines &middot; <a href="https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/compositor-glare/compositor_glare.py">View on GitHub &rarr;</a></span>
+        <span>398 lines &middot; <a href="https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/compositor-glare/compositor_glare.py">View on GitHub &rarr;</a></span>
       </div>
-      <div class="code" data-lines="379">
+      <div class="code" data-lines="398">
 <pre class="gutter" aria-hidden="true">1
 2
 3
@@ -464,7 +464,26 @@ <h2>Source</h2>
 376
 377
 378
-379</pre><pre class="code-lines"><span class="s">&quot;&quot;&quot;Bloom through the compositor across the 4.x -&gt; 5.x boundary — a runnable example.
+379
+380
+381
+382
+383
+384
+385
+386
+387
+388
+389
+390
+391
+392
+393
+394
+395
+396
+397
+398</pre><pre class="code-lines"><span class="s">&quot;&quot;&quot;Bloom through the compositor across the 4.x -&gt; 5.x boundary — a runnable example.
 
 Witnesses the compositor-plumbing contract that AI-generated Blender code breaks
 constantly:
@@ -504,6 +523,11 @@ <h2>Source</h2>
 <span class="k">from</span> bpy_extras.object_utils <span class="k">import</span> world_to_camera_view
 <span class="k">from</span> mathutils <span class="k">import</span> Vector
 
+<span class="c"># Shared Layer 1 framing measurement (render path only) — see gallery_framing.py</span>
+sys.path.insert(<span class="n">0</span>, os.path.join(os.path.dirname(os.path.abspath(__file__)), os.pardir))
+sys.dont_write_bytecode = <span class="k">True</span>  <span class="c"># keep examples/__pycache__ out of the repo tree</span>
+<span class="k">import</span> gallery_framing
+
 RING_MAJOR = <span class="n">0.7</span>
 RING_MINOR = <span class="n">0.12</span>
 RING_Z = <span class="n">0.85</span>                <span class="c"># ring center height; bottom edge grazes the floor</span>
@@ -745,7 +769,11 @@ <h2>Source</h2>
 
 <span class="k">def</span> render_still(scene, path, engine, samples, width):
     <span class="s">&quot;&quot;&quot;Dark-studio beauty pass: the same rings, now grounded on a reflective
-    floor — the glow and its reflection are the compositor&#x27;s doing.&quot;&quot;&quot;</span>
+    floor — the glow and its reflection are the compositor&#x27;s doing.
+
+    Returns 0, 10 (gallery framing violation, checked before the beauty
+    render) or 6 (no file written).&quot;&quot;&quot;</span>
+    rings = [o <span class="k">for</span> o <span class="k">in</span> scene.objects <span class="k">if</span> o.type == <span class="s">&#x27;MESH&#x27;</span>]
     <span class="c"># glossy dark floor stays below the bloom threshold; only the rings bloom</span>
     mesh = bpy.data.meshes.new(<span class="s">&quot;Floor&quot;</span>)
     half = <span class="n">30.0</span>
@@ -796,8 +824,18 @@ <h2>Source</h2>
     scene.render.image_settings.file_format = <span class="s">&#x27;WEBP&#x27;</span> <span class="k">if</span> path.lower().endswith(<span class="s">&quot;.webp&quot;</span>) <span class="k">else</span> <span class="s">&#x27;PNG&#x27;</span>
     scene.render.use_compositing = <span class="k">True</span>
     scene.render.filepath = path
+    <span class="c"># Layer 1 framing gate (silhouette matte) — exit 10 on violation, before</span>
+    <span class="c"># the beauty render so a defective composition ships no artifact.</span>
+    fcode = gallery_framing.check_framing(
+        scene, cam, hero=rings, elements=rings, stage=[floor],
+    )
+    <span class="k">if</span> fcode:
+        <span class="k">return</span> fcode
     bpy.ops.render.render(write_still=<span class="k">True</span>)
-    <span class="k">return</span> os.path.exists(path) <span class="k">and</span> os.path.getsize(path) &gt; <span class="n">0</span>
+    <span class="k">if</span> <span class="k">not</span> (os.path.exists(path) <span class="k">and</span> os.path.getsize(path) &gt; <span class="n">0</span>):
+        print(<span class="s">&quot;ERROR: render produced no file&quot;</span>, file=sys.stderr)
+        <span class="k">return</span> <span class="n">6</span>
+    <span class="k">return</span> <span class="n">0</span>
 
 
 <span class="k">def</span> main():
@@ -828,10 +866,10 @@ <h2>Source</h2>
         <span class="k">return</span> code
 
     <span class="k">if</span> args.output:
-        <span class="k">if</span> <span class="k">not</span> render_still(scene, os.path.abspath(args.output), args.engine, args.samples,
-                            args.width):
-            print(<span class="s">&quot;ERROR: render produced no file&quot;</span>, file=sys.stderr)
-            <span class="k">return</span> <span class="n">6</span>
+        rcode = render_still(scene, os.path.abspath(args.output), args.engine, args.samples,
+                             args.width)
+        <span class="k">if</span> rcode:
+            <span class="k">return</span> rcode
         print(<span class="s">f&quot;</span><span class="s">rendered still </span>{args.output}<span class="s">&quot;</span>)
 
     print(<span class="s">&quot;compositor-glare OK&quot;</span>)

examples/collision-hull-proxy/README.md

@@ -86,6 +86,8 @@ against it.
 | 7 | Euler characteristic ≠ 2 |
 | 8 | Piece over the 255-face collision budget |
 | 9 | `--output` produced no file |
+| 10 | Gallery framing violation (render path) |
+| 11 | Gallery asset-quality violation (render path) |
 
 The `blender-smoke` workflow runs the check on Blender 5.2 LTS and 4.5 LTS
 (5.1 on the weekly cron, the `needs-5.1` PR label, or manual dispatch).

examples/collision-hull-proxy/collision_hull_proxy.py

@@ -38,6 +38,13 @@
 import bpy, bmesh, sys, os, math, argparse
 from mathutils import Vector
 
+# Shared render gates (render path only) — see gallery_framing.py and
+# gallery_asset_quality.py
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), os.pardir))
+sys.dont_write_bytecode = True  # keep examples/__pycache__ out of the repo tree
+import gallery_framing
+import gallery_asset_quality
+
 SEGMENTS = 48          # lathe resolution of the render mesh
 CAGE_SEG_BODY = 8      # collision cage resolutions — the hull face budget
 CAGE_SEG_CAP = 8       #   is spent through these, not through SEGMENTS
@@ -480,8 +487,26 @@ def light(name, loc, energy, size, col, rot):
     scene.render.filepath = path
     # AgX would flatten the enamel toward pastel (docs/VISUAL-STYLE.md)
     scene.view_settings.view_transform = 'Standard'
+    # Layer 1 framing gate and the asset-quality floors, both before the
+    # beauty render so a defective still ships no artifact. The hero is the
+    # hydrant itself; its hulls are framed elements too.
+    hydrant = [o for g in groups for o in g["render"]]
+    hulls = [hull for _, hull, _ in pieces]
+    fcode = gallery_framing.check_framing(
+        scene, cam, hero=hydrant, elements=hydrant + hulls, stage=[floor, wall],
+    )
+    if fcode:
+        return fcode
+    acode = gallery_asset_quality.check_asset_quality(
+        scene, cam, hydrant, stage=[floor, wall],
+    )
+    if acode:
+        return acode
     bpy.ops.render.render(write_still=True)
-    return os.path.exists(path) and os.path.getsize(path) > 0
+    if not (os.path.exists(path) and os.path.getsize(path) > 0):
+        print("ERROR: render produced no file", file=sys.stderr)
+        return 9
+    return 0
 
 
 def main():
@@ -508,9 +533,9 @@ def main():
         return code
 
     if args.output:
-        if not render_still(groups, pieces, os.path.abspath(args.output), args.engine):
-            print("ERROR: render produced no file", file=sys.stderr)
-            return 9
+        rcode = render_still(groups, pieces, os.path.abspath(args.output), args.engine)
+        if rcode:
+            return rcode
         print(f"rendered still {args.output}")
 
     print("collision-hull-proxy OK")

examples/compositor-glare/README.md

@@ -51,6 +51,7 @@ against it.
 | 4 | Check render missing, tube dark, no halo, or halo does not fall off |
 | 5 | Halo present with compositing off |
 | 6 | `--output` produced no file |
+| 10 | Gallery framing violation (render path; checked before the beauty render) |
 
 The `blender-smoke` workflow runs the check on Blender 5.2 LTS and 4.5 LTS
 (5.1 on the weekly cron, the `needs-5.1` PR label, or manual dispatch).