feat: measurable framing gate + restage hygiene/origin heroes into the band (#107)

* feat: add shared framing-measurement helper for gallery renders

Layer 1 framing was the only mandatory render rule with no number
attached, so agents eyeballed it and overshot in both directions.
examples/gallery_framing.py measures hero fill (0.70-0.90 of frame in
at least one axis) and all-elements edge margins (>= 0.02) on a staged
scene, defaulting to a silhouette alpha matte (exact for round or
angled subjects) with a bbox-projection strategy documented as the
cheap alternative for boxy subjects. check_framing prints the measured
values in the house log style and exits 10 on violation, render path
only, so check-only smoke runtimes are untouched. It also establishes
the repo's cross-example sharing mechanism: a __file__-relative
sys.path shim that keeps every example standalone-runnable from the
repository root.

Signed-off-by: fOuttaMyPaint <TMhospitalitystrategies@gmail.com>

* fix: restage hygiene and origin heroes into the framing band

Both renders sat outside the Layer 1 band in opposite directions, the
failure mode the new helper exists to catch. mesh-hygiene-audit was at
0.391 fill (two small valves in a large empty stage); the camera moves
from 38mm at (0,-7.8,1.9) to 50mm at (0,-5.0,1.5), landing fill at
0.803x0.733 with all margins >= 0.05. The backlit through-hole and
loose-vert bead staging is untouched and no light shape re-enters the
frame. prop-origin-transform was at 0.906 fill with the shipped asset
cropped at both side edges and the tops; the camera pulls back from
(1.15,-5.35,1.45) to (1.15,-5.9,1.55) only until margins clear, landing
fill at 0.816x0.678 with margins >= 0.072. Both render paths now call
gallery_framing.check_framing before the beauty render (exit 10, no
artifact on violation); check code and closed forms are unchanged, and
check-only output is byte-identical to main on 5.1.2 and 4.5.11.
Contact sheets recomposited against the pinned calibration set.

Signed-off-by: fOuttaMyPaint <TMhospitalitystrategies@gmail.com>

* docs: codify the framing band in VISUAL-STYLE and CLAUDE gates

Layer 1 framing now carries its numbers where every run reads them:
the 0.70-0.90 fill band in at least one axis, the 2 percent minimum
edge margin, the hero-fill versus all-elements-margin distinction, and
the instruction to measure with examples/gallery_framing.py rather
than eyeball. CLAUDE.md's quality gates gain the matching framing-gate
bullet so the standard example prompt inherits the rule by reference,
plus one line naming the cross-example import shim. A read-only survey
of every shipped hero with the helper found 13 examples outside the
band (worklist for a future pass, not fixed here).

Signed-off-by: fOuttaMyPaint <TMhospitalitystrategies@gmail.com>

* docs: note the shared framing helper in AGENTS.md structure

Signed-off-by: fOuttaMyPaint <TMhospitalitystrategies@gmail.com>

---------

Signed-off-by: fOuttaMyPaint <TMhospitalitystrategies@gmail.com>

Author: TMHSDigital

AGENTS.md

@@ -36,6 +36,7 @@ Blender-Developer-Tools/
   templates/<template-name>/     # 2 starter templates
   snippets/<snippet-name>.py     # 17 standalone Python snippets
   examples/<name>/               # 23 runnable smoke-gated examples (+ gallery.json)
+  examples/gallery_framing.py    # shared Layer 1 framing measurement (render path only)
   scripts/build_gallery.py       # generates docs/gallery/ (stdlib only)
   scripts/site/                  # vendored landing-page build (build_site.py + template)
   docs/gallery/                  # committed generated gallery pages + hero assets

CLAUDE.md

@@ -94,6 +94,9 @@ wire all of: gallery.json entry, `.cursor-plugin/plugin.json` examples array (CI
 a `blender-smoke.yml` step, a README gallery row, hero webp (1280×720) in
 `docs/gallery/assets/` + preview webp (1200×675), then run `python scripts/build_gallery.py`.
 Renders must conform to the gallery look spec at `docs/VISUAL-STYLE.md`.
+Render paths gate framing through the shared helper `examples/gallery_framing.py` —
+imported via a `__file__`-relative `sys.path` shim, the repo's only
+cross-example import mechanism (see its docstring).
 
 ## Blender Runtime Discovery
 
@@ -118,6 +121,7 @@ Stage with **explicit paths only** — never `git add -A` or `git add .`. Cursor
 ## Quality Gates for Example Runs
 
 - `docs/VISUAL-STYLE.md` is the **binding** render standard; deviations are defects.
+- **Framing gate:** Layer 1 framing is measured, not eyeballed — the example's `--output` render path calls the shared helper `examples/gallery_framing.py` (`check_framing`, exit 10 on violation) before writing the still: hero fill 0.70–0.90 of frame in at least one axis, every element that matters clearing all four edges by ≥ 0.02. The check-only path never invokes it, so smoke runtimes are unaffected.
 - **Contact-sheet gate:** composite the candidate hero beside the pinned calibration set — currently `armature-bend`, `damped-track-aim`, `bmesh-gear` — commit the composite under `docs/gallery/contact-sheets/`, link it in the PR body, and report per-criterion verdicts (stage darkness, wedge warmth, subject fill, saturation, thumbnail legibility) including mean luminance versus the calibration images. A claim without the committed composite is not acceptable evidence. **This list is the canonical home of the pinned set** — update it here when a new example outclasses a member; `docs/new-example-prompt.md` points here rather than naming members. The longer "calibration references" list in `docs/VISUAL-STYLE.md` is a style reference, not this contact-sheet set.
 - **Falsification:** every check must be proven to fail once — break the contract, observe the non-zero exit, restore — with the probe and the measured error reported in the PR body. An assertion that cannot fail witnesses nothing.
 - **After gallery regeneration** (`python scripts/build_gallery.py`), read the **generated HTML** character by character — the `<img alt>` text and witnesses callouts in `docs/gallery/index.html` and `docs/gallery/<name>/index.html` — not just `examples/gallery.json`. Precedent: the `teaches.split(".")[0]` bug truncated 14/21 card alts at dotted API paths like `bmesh.ops` while the source JSON looked fine (fixed in PR #68).

README.md

@@ -668,7 +668,7 @@ with the Smooth-by-Angle modifier on 5.1.
 </tr>
 <tr>
 <td width="46%" valign="middle">
-<a href="examples/mesh-hygiene-audit/"><img src="examples/mesh-hygiene-audit/preview.webp" alt="Mesh hygiene audit: dual-panel dirty vs clean street electrical pedestal — left orange emissive wireframe with loose-vert bead and DIRTY placard, right teal CLEAN manifold — proving the engine-ingest topology checklist" /></a>
+<a href="examples/mesh-hygiene-audit/"><img src="examples/mesh-hygiene-audit/preview.webp" alt="Mesh hygiene audit: dual-panel dirty vs clean brass street valves filling the frame — left with backlit through-hole, emissive boundary tubes and loose-vert bead over a DIRTY placard, right intact CLEAN manifold — proving the engine-ingest topology checklist" /></a>
 </td>
 <td valign="middle">
 
@@ -686,7 +686,7 @@ still: DIRTY through-hole + loose-vert bead vs CLEAN manifold (same brass).
 </tr>
 <tr>
 <td width="46%" valign="middle">
-<a href="examples/prop-origin-transform/"><img src="examples/prop-origin-transform/preview.webp" alt="Prop origin transform: dual-panel TRAP vs MPI KEEP street pedestals — left bare-parent accessory teleports with expected-seat ghost, right accessory stays put, emissive origin markers at base — proving scale apply, base origin, and matrix_parent_inverse" /></a>
+<a href="examples/prop-origin-transform/"><img src="examples/prop-origin-transform/preview.webp" alt="Prop origin transform: dual-panel TRAP vs MPI KEEP street pedestals with margins all around — left bare-parent conduit accessory teleports off its dark mount well, right accessory stays seated — proving scale apply, base origin, and matrix_parent_inverse" /></a>
 </td>
 <td valign="middle">
 

docs/VISUAL-STYLE.md

@@ -49,8 +49,18 @@ the default stage.
 
 ## Framing and camera
 
-- The subject fills roughly 70–90 % of the frame in at least one axis.
-  Nothing that matters may touch or cross the frame edge.
+- The subject fills 70–90 % of the frame in at least one axis, measured —
+  never eyeballed. Nothing that matters may touch or cross the frame edge.
+- Measure with the shared helper `examples/gallery_framing.py`, called on the
+  render path only (import shim and full contract in its docstring):
+  `gallery_framing.check_framing(sc, cam, hero=..., elements=..., stage=...)`
+  prints the numbers and exits 10 on violation. **Fill** is measured on the
+  hero subject only and must land in the 0.70–0.90 band in at least one axis,
+  neither axis above 0.90. **Margin** is measured on the union of every
+  element that matters — hero, placards, labels, comparison props, overlay
+  markers — and must clear all four edges by ≥ 2 % of the frame dimension.
+  Default strategy is the silhouette alpha matte; projection is the cheap
+  bbox alternative for boxy subjects (tradeoff in the helper's docstring).
 - Camera: a chosen angle, not the default — typically a 45–55 mm lens,
   slightly above subject height, aimed with a `TRACK_TO` constraint at an
   empty on the subject. Flat subjects present toward the camera (lean or

docs/gallery/assets/mesh-hygiene-audit-hero.webp

@@ -196,7 +196,7 @@ <h2>Run</h2>
 <pre><code>blender --background --python mesh_hygiene_audit.py --
 blender --background --python mesh_hygiene_audit.py -- --output hygiene.png
 blender --background --python mesh_hygiene_audit.py -- --output hygiene.png --engine cycles</code></pre>
-<p>Exits non-zero on failure. The <code>blender-smoke</code> workflow runs the check on Blender 4.5 LTS and 5.1.</p>
+<p>Exits non-zero on failure. The <code>blender-smoke</code> workflow runs the check on Blender 4.5 LTS and 5.1. The <code>--output</code> render path additionally measures framing against the Layer 1 band via <code>examples/gallery_framing.py</code> (exit 10 on violation) before writing the still.</p>
     </section>
     <section class="detail-section src">
       <h2>Source</h2>
@@ -226,6 +226,11 @@ <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> Matrix, 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
+
 AREA_EPS = <span class="n">1e-10</span>
 VOL_EPS = <span class="n">1e-8</span>
 
@@ -531,6 +536,7 @@ <h2>Source</h2>
     light(<span class="s">&quot;Rim&quot;</span>, (<span class="n">1.5</span>, <span class="n">4.5</span>, <span class="n">3.5</span>), <span class="n">280.0</span>, <span class="n">3.0</span>, (<span class="n">0.6</span>, <span class="n">0.78</span>, <span class="n">1.0</span>), (-<span class="n">55</span>, <span class="n">0</span>, <span class="n">170</span>))
     light(<span class="s">&quot;Wedge&quot;</span>, (<span class="n">2.5</span>, <span class="n">5.5</span>, <span class="n">4.0</span>), <span class="n">420.0</span>, <span class="n">6.0</span>, (<span class="n">1.0</span>, <span class="n">0.72</span>, <span class="n">0.42</span>), (-<span class="n">68</span>, <span class="n">0</span>, <span class="n">190</span>))
     light(<span class="s">&quot;Glint&quot;</span>, (-<span class="n">2.0</span>, -<span class="n">4.0</span>, <span class="n">3.2</span>), <span class="n">220.0</span>, <span class="n">2.0</span>, (<span class="n">1.0</span>, <span class="n">0.9</span>, <span class="n">0.75</span>), (<span class="n">55</span>, <span class="n">0</span>, -<span class="n">20</span>))
+    <span class="k">return</span> floor, wall
 
 
 <span class="k">def</span> _duplicate_mesh_obj(sc, src, name, loc):
@@ -694,10 +700,10 @@ <h2>Source</h2>
     <span class="k">for</span> p <span class="k">in</span> right.data.polygons:
         p.use_smooth = abs(p.normal.z) &lt; <span class="n">0.85</span>
 
-    placard(sc, <span class="s">&quot;DIRTY&quot;</span>, (-<span class="n">0.88</span>, -<span class="n">1.15</span>, <span class="n">0.02</span>), size=<span class="n">0.11</span>)
-    placard(sc, <span class="s">&quot;CLEAN&quot;</span>, (<span class="n">0.88</span>, -<span class="n">1.15</span>, <span class="n">0.02</span>), size=<span class="n">0.11</span>)
+    p_dirty = placard(sc, <span class="s">&quot;DIRTY&quot;</span>, (-<span class="n">0.88</span>, -<span class="n">1.15</span>, <span class="n">0.02</span>), size=<span class="n">0.11</span>)
+    p_clean = placard(sc, <span class="s">&quot;CLEAN&quot;</span>, (<span class="n">0.88</span>, -<span class="n">1.15</span>, <span class="n">0.02</span>), size=<span class="n">0.11</span>)
 
-    build_studio(sc)
+    floor, wall = build_studio(sc)
     <span class="c"># Out-of-frame POINT behind DIRTY — aperture glow without a rectangular AREA</span>
     <span class="c"># footprint on the floor (Layer 1: no visible light shapes).</span>
     hole_ld = bpy.data.lights.new(<span class="s">&quot;HoleBack&quot;</span>, <span class="s">&quot;POINT&quot;</span>)
@@ -718,12 +724,12 @@ <h2>Source</h2>
             ob.data.energy = <span class="n">140.0</span>
 
     cam_data = bpy.data.cameras.new(<span class="s">&quot;Cam&quot;</span>)
-    cam_data.lens = <span class="n">38.0</span>
+    cam_data.lens = <span class="n">50.0</span>
     cam = bpy.data.objects.new(<span class="s">&quot;Cam&quot;</span>, cam_data)
-    cam.location = (<span class="n">0.0</span>, -<span class="n">7.8</span>, <span class="n">1.9</span>)
+    cam.location = (<span class="n">0.0</span>, -<span class="n">5.0</span>, <span class="n">1.5</span>)
     sc.collection.objects.link(cam)
     aim = bpy.data.objects.new(<span class="s">&quot;Aim&quot;</span>, <span class="k">None</span>)
-    aim.location = (<span class="n">0.0</span>, <span class="n">0.0</span>, <span class="n">0.48</span>)
+    aim.location = (<span class="n">0.0</span>, <span class="n">0.0</span>, <span class="n">0.55</span>)
     sc.collection.objects.link(aim)
     tr = cam.constraints.new(<span class="s">&quot;TRACK_TO&quot;</span>)
     tr.target = aim
@@ -746,8 +752,22 @@ <h2>Source</h2>
     sc.render.image_settings.file_format = <span class="s">&quot;PNG&quot;</span>
     sc.render.filepath = path
     sc.view_settings.view_transform = <span class="s">&quot;Standard&quot;</span>
+    <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>
+    overlays = [o <span class="k">for</span> o <span class="k">in</span> sc.objects <span class="k">if</span> o.name.startswith((<span class="s">&quot;LooseBead&quot;</span>, <span class="s">&quot;Bnd&quot;</span>))]
+    fcode = gallery_framing.check_framing(
+        sc, cam,
+        hero=[left, right],
+        elements=[left, right, p_dirty, p_clean] + overlays,
+        stage=[floor, wall],
+    )
+    <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">9</span>
+    <span class="k">return</span> <span class="n">0</span>
 
 
 <span class="k">def</span> build_scene():
@@ -772,9 +792,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(ob, 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(ob, 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;mesh-hygiene-audit OK&quot;</span>)