fix(examples): redesign sky-texture-sun-elevation hero as a sky-lit obelisk diptych

README.md

@@ -325,7 +325,7 @@ byte images stay straight 8-bit. Also witnesses `EXR color_mode='RGB'` dropping
 </tr>
 <tr>
 <td width="46%" valign="middle">
-<a href="examples/sky-texture-sun-elevation/"><img src="examples/sky-texture-sun-elevation/preview.webp" alt="Sky texture sun elevation: pale glazed jar diptych on a dark floor — left panel low sun at 8 degrees, the jar dim twilight blue under a deep blue zenith, right panel high sun at 55 degrees, the jar bright under a pale daylight sky" /></a>
+<a href="examples/sky-texture-sun-elevation/"><img src="examples/sky-texture-sun-elevation/preview.webp" alt="Sky texture sun elevation: diptych of a red-granite obelisk on a paved plaza lit only by the sky — left panel sun at 8 degrees, navy dusk with an orange horizon glow and the obelisk face raked orange, right panel sun at 55 degrees, bright blue midday sky, sunlit paving and a short shadow" /></a>
 </td>
 <td valign="middle">
 
@@ -336,7 +336,7 @@ code misses across 4.5 → 5.1. `sky_type` is `NISHITA` on 4.5 LTS and
 `MULTIPLE_SCATTERING` on 5.1 (`NISHITA` gone); `dust_density` exists only on 4.5
 (`aerosol_density` on 5.1). Two tiny Cycles EXR zenith probes assert
 `sun_elevation` 8° → 55° brightens zenith (rise **2.25x** / **1.50x**, gate ≥ 1.25).
-Gallery still is a dual-elevation diptych so the contract reads at thumbnail scale.
+Gallery still is a sky-lit obelisk diptych (8° dusk | 55° midday) so the contract reads at thumbnail scale.
 
 </td>
 </tr>

docs/gallery/index.html

@@ -717,7 +717,7 @@ <h2><a href="custom-normals-shade/">custom-normals-shade</a></h2>
       </article>
       <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="Split view of a pale glazed jar under a procedural sky: dim twilight blue at sun elevation 8 degrees on the left, bright daylight at 55 degrees on the right." loading="lazy" decoding="async" />
+          <img src="assets/sky-texture-sun-elevation-hero.webp" alt="A red-granite obelisk on a paved plaza lit only by the sky: navy dusk with an orange horizon glow at sun elevation 8 degrees, bright blue midday and a short shadow at 55 degrees." loading="lazy" decoding="async" />
         </a>
         <div class="card-body">
           <h2><a href="sky-texture-sun-elevation/">sky-texture-sun-elevation</a></h2>

examples/gallery.json

@@ -460,7 +460,7 @@
       "name": "sky-texture-sun-elevation",
       "dir": "examples/sky-texture-sun-elevation",
       "teaches": "World ShaderNodeTexSky driving Background Color — the sky contract across 4.5 LTS and 5.1. sky_type is NISHITA on 4.5 and MULTIPLE_SCATTERING on 5.1 (NISHITA gone); dust_density exists only on 4.5 (aerosol_density on 5.1). Two tiny Cycles OPEN_EXR zenith probes prove sun_elevation 8 deg to 55 deg brightens zenith (rise 2.25x on 5.1.2, 1.50x on 4.5.11, gate >= 1.25).",
-      "alt": "Split view of a pale glazed jar under a procedural sky: dim twilight blue at sun elevation 8 degrees on the left, bright daylight at 55 degrees on the right.",
+      "alt": "A red-granite obelisk on a paved plaza lit only by the sky: navy dusk with an orange horizon glow at sun elevation 8 degrees, bright blue midday and a short shadow at 55 degrees.",
       "witnessesFix": "AI code still assigns sky_type='NISHITA' and dust_density on 5.1 — both are wrong (NISHITA removed; dust_density is AttributeError; use MULTIPLE_SCATTERING + aerosol_density). A near-black Background Strength alone is not a sky: Sky must link into Background Color. Elevation that does not brighten zenith fails the rise gate.",
       "hero": "docs/gallery/assets/sky-texture-sun-elevation-hero.webp",
       "preview": "examples/sky-texture-sun-elevation/preview.webp",

examples/gallery_framing.py

@@ -65,9 +65,9 @@
 the scene the still actually renders from. Multi-scene examples (e.g.
 vse-cut-list, whose gallery still renders from a dedicated ``Bay`` scene
 while ``bpy.context.scene`` is the cut-list scene) must pass that scene
-and its camera explicitly. Examples whose subject IS the world or the
-atmosphere (sky-texture-sun-elevation) have no renderable hero for the
-matte to isolate — they do not call this helper.
+and its camera explicitly. World/sky contracts still stage a renderable
+hero for the matte: sky-texture-sun-elevation measures its gnomon obelisk
+in each diptych panel, with ground and plaza passed as stage.
 """
 import os
 import sys

examples/sky-texture-sun-elevation/README.md

@@ -2,8 +2,9 @@
 
 A runnable example that builds a World whose Background Color is driven by
 `ShaderNodeTexSky`, then proves `sun_elevation` is load-bearing with two tiny
-Cycles EXR zenith probes — and stages a dual-elevation gallery diptych so the
-contract is visible at thumbnail scale.
+Cycles EXR zenith probes. The gallery still is a sky study: a red-granite
+gnomon obelisk on a paved plaza, lit by nothing but the sky, shown at both
+elevations side by side so the contract reads at thumbnail scale.
 
 **What it witnesses:** the Sky Texture contract AI-generated lighting code most
 often gets wrong across the 4.5 LTS → 5.1 window.
@@ -33,26 +34,40 @@ multiple scattering) but clears the same gate on both binaries.
 
 ## Stage deviation
 
-World carries a Nishita / multiple-scattering Sky Texture instead of the
-default near-black Background — the contract *is* the sky. Gallery still is a
-dual-elevation diptych (8° | 55°) so failure (identical panels) is visible at
-thumbnail scale. Layer 1 still holds: `view_transform='Standard'`, designed
-materials, chosen camera, no helpers in frame.
-
-The jar is pale glaze, and the studio key and fill only model its form
-(70 W and 10 W). With saturated terracotta and a 420 W key, the studio lights
-lit the jar and both panels looked the same: the sky, the thing under test,
-was not what lit it. Now the jar reads dim twilight blue under the 8° sun and
-bright under the 55° sun. Mean luma is about 0.35, above the dark-stage band,
-which is information under this deviation, not a failure.
-
-## Framing deviation
-
-The hero is the sky itself — a world contract, not an object on the stage.
-The silhouette matte can only measure the jar in each 640 px panel (about
-0.37 x / 0.49 y), so an out-of-band number would be a measurement artifact,
-not the composition. The diptych is not wired to `examples/gallery_framing.py`;
-the helper has no `deviation=` flag to report through.
+The World carries a Nishita / multiple-scattering Sky Texture instead of the
+default near-black Background, and there are no studio lights: the contract
+*is* the sky, so the sky's sun disc is the key and its dome is the fill. The
+still is a diptych, 8° | 55°, split by a dark 12 px rule, with one Background
+Strength (0.035) for both panels so `sun_elevation` is the only variable. If
+it did not take, the two panels would render identical.
+
+What reads at a glance: at 8° a deep navy sky with a dusk glow on the left
+horizon, the obelisk's sun face raked orange, the plaza nearly dark and the
+shadow running long out of frame; at 55° a bright blue sky, a sunlit plaza,
+and a short shadow ending on the bronze meridian scale inlaid in the paving.
+The ground runs to the horizon, so there is no void below it.
+
+Layer 1 still holds: `view_transform='Standard'`, designed materials (red
+granite, limestone, bronze, matte gilt, brick-pattern paving), a chosen 35 mm
+camera on a `TRACK_TO` aim, no helpers in frame. Standard does not compress
+highlights, so the render path fails with exit 12 if more than 0.05 % of the
+still clips to white. The committed still has zero clipped pixels. The
+pyramidion is matte gilt rather than metal: a metallic cap Fresnel-glinted
+the 55° sun to pure white at grazing angles, whatever its roughness. Mean
+luma is about 0.20, reported against the calibration set as information
+under this deviation.
+
+The sky's `sun_rotation` is a compass bearing, measured clockwise from +Y.
+The first draft assumed the opposite convention and put the shadow on the
+wrong side. `_sun_rotation_for_shadow` holds the measured mapping.
+
+## Framing
+
+Each 640 × 720 panel is its own frame, and the gnomon is measured in it
+through `examples/gallery_framing.py` (exit 10). Both panels share geometry
+and camera, so one measurement covers both. On 5.2.1 the fill is
+x 0.566 / y 0.794 and the margins are left 0.100, right 0.334,
+bottom 0.044, top 0.161. The ground, plaza and meridian inlay are stage.
 
 ## Run
 
@@ -63,7 +78,7 @@ blender --background --python sky_texture_sun_elevation.py --
 # Falsifier: Sky→Background unlinked. Must exit non-zero (world links).
 blender --background --python sky_texture_sun_elevation.py -- --unlink-sky
 
-# Also render the gallery diptych (Cycles):
+# Also render the gallery diptych (Cycles; framing gate exit 10, clip gate exit 12):
 blender --background --python sky_texture_sun_elevation.py -- --output sky.png
 ```
 
@@ -84,7 +99,10 @@ against it.
 | 7 | High-elevation zenith luma below floor |
 | 8 | Zenith luma did not rise with elevation |
 | 9 | `--output` produced no file |
+| 10 | `--output` framing violation (`gallery_framing`, per panel) |
+| 12 | `--output` still clips to white under Standard (> 0.05 % of pixels) |
 
 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).
-Smoke does not pass `--output` or `--unlink-sky`.
+Smoke does not pass `--output` or `--unlink-sky`, so exits 10 and 12 are
+render-path only.