feat: add custom-normals-shade example (post-4.1 shading contract) (#97)

A prop's silhouette lives or dies on which edges shade hard and which
shade smooth, and since Blender 4.1 that is mesh data: face smooth flags
plus a sharp_edge attribute. AI-generated code still emits the removed API
(mesh.use_auto_smooth, shade_auto_smooth), so this example pins the truth
on both supported versions: the legacy API is AttributeError on 4.5 LTS
and 5.1; set_sharp_from_angle marks sharp exactly the edges an
independent dihedral recompute predicts (188/388 across 3 meshes);
evaluated loop normals weld across smooth edges and split by the dihedral
across sharp ones (0.0 deviation); and per-loop custom normals survive
depsgraph evaluation within their int16 storage quantization (1.407e-04 —
asserting float-exactness is a real, caught bug).

Version-gated divergence, probed on both binaries: the legacy
shade_auto_smooth operator needs the bundled Smooth-by-Angle node-group
asset — headless on 4.5 it returns {'CANCELLED'} with the mesh untouched
(silent flat shading for scripts that ignore the return set), while 5.1
FINISHES with the NODES modifier. The data API is the portable path.

Falsified: threshold drift (exit 5, 4 extra edges), smooth flags lost
after marking (exit 6, 3.83e-01), float-exact custom normals (exit 7,
1.407e-04 vs 1e-6). Check output identical on Blender 4.5.11 LTS and
5.1.2 except the asserted operator divergence.

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

Author: TMHSDigital

.cursor-plugin/plugin.json

@@ -65,6 +65,7 @@
     "examples/collision-hull-proxy",
     "examples/compositor-glare",
     "examples/curve-bevel-arc",
+    "examples/custom-normals-shade",
     "examples/damped-track-aim",
     "examples/depsgraph-export",
     "examples/driver-wave",

.github/workflows/blender-smoke.yml

@@ -460,3 +460,17 @@ jobs:
           # the 255-face per-piece engine budget. Exits non-zero on failure.
           xvfb-run -a "$BLENDER" --background \
             --python examples/collision-hull-proxy/collision_hull_proxy.py --
+
+      - name: Shipped example - custom normals + shade by angle (post-4.1 shading contract)
+        run: |
+          set -euo pipefail
+          # Check only (no render): a jerry can prop; asserts the legacy
+          # shading API stays removed (use_auto_smooth/use_custom_normals/
+          # calc_normals), set_sharp_from_angle sharp sets matching an
+          # independent dihedral recompute exactly, evaluated normal welds/
+          # splits, custom split normals surviving depsgraph evaluation
+          # within int16 quantization, and the version-gated shade_auto_smooth
+          # operator divergence (CANCELLED headless on 4.5, FINISHED on 5.1).
+          # Exits non-zero on failure.
+          xvfb-run -a "$BLENDER" --background \
+            --python examples/custom-normals-shade/custom_normals_shade.py --

README.md

@@ -18,7 +18,7 @@
 </p>
 
 <p align="center">
-  <strong>12 skills</strong> &nbsp;&bull;&nbsp; <strong>6 rules</strong> &nbsp;&bull;&nbsp; <strong>2 templates</strong> &nbsp;&bull;&nbsp; <strong>17 snippets</strong> &nbsp;&bull;&nbsp; <strong>31 examples</strong>
+  <strong>12 skills</strong> &nbsp;&bull;&nbsp; <strong>6 rules</strong> &nbsp;&bull;&nbsp; <strong>2 templates</strong> &nbsp;&bull;&nbsp; <strong>17 snippets</strong> &nbsp;&bull;&nbsp; <strong>32 examples</strong>
 </p>
 
 <p align="center">
@@ -36,7 +36,7 @@
 
 ## Overview
 
-This repository ships **12 skills, 6 rules, 2 templates, 17 snippets, and 31 runnable examples** for Blender Python development targeting Blender 5.1 (current stable) with Blender 4.5 LTS fallback support.
+This repository ships **12 skills, 6 rules, 2 templates, 17 snippets, and 32 runnable examples** for Blender Python development targeting Blender 5.1 (current stable) with Blender 4.5 LTS fallback support.
 
 The content is consumed by AI coding agents (Cursor, Claude Code, any MCP-capable client) when working on Blender add-ons, geometry nodes scripts, batch pipelines, or animation tooling. There is no build step. Edit the markdown and Python files directly.
 
@@ -504,7 +504,7 @@ round-trips through the raw `POINT` buffer.
 </details>
 
 <details>
-<summary><strong>Game asset pipeline</strong> — 6 examples</summary>
+<summary><strong>Game asset pipeline</strong> — 7 examples</summary>
 
 <table>
 <tr>
@@ -610,6 +610,27 @@ tests prove containment (5.9e-08), convexity, watertightness, outward
 winding, and Euler characteristic 2 per piece. Proud details cost cage rows;
 concave grooves are free.
 
+</td>
+</tr>
+<tr>
+<td width="46%" valign="middle">
+<a href="examples/custom-normals-shade/"><img src="examples/custom-normals-shade/preview.webp" alt="Custom normals and shade by angle: three olive-drab jerry can props with pressed X ribs and red spout rings on a dark studio floor - one faceted flat, one smeared by smooth-everything, one crisp with correct hard edges - proving the post-4.1 shading contract" /></a>
+</td>
+<td valign="middle">
+
+### [custom-normals-shade](examples/custom-normals-shade/)
+
+The shading contract a prop's silhouette depends on: since Blender 4.1,
+hard edges are mesh data (face smooth flags + `sharp_edge` attribute), and
+`use_auto_smooth` / `use_custom_normals` / `calc_normals` are AttributeError
+on **both** 4.5 LTS and 5.1. `set_sharp_from_angle` marks sharp exactly the
+edges an independent dihedral recompute predicts; evaluated loop normals
+weld across smooth edges and split by the dihedral across sharp ones;
+custom split normals survive depsgraph evaluation within their int16
+quantization (1.407e-04, not float-exact). Documents the legacy
+`shade_auto_smooth` operator trap: CANCELLED headless on 4.5, FINISHED
+with the Smooth-by-Angle modifier on 5.1.
+
 </td>
 </tr>
 </table>

ROADMAP.md

@@ -113,7 +113,7 @@ Not committed; target list for the next content version. (v0.3.0 shipped the smo
 - ~~GAMMA_CROSS blend-curve witness~~ **SHIPPED** as `examples/vse-gamma-cross/` — the cross blends in a gamma-0.5 space: `((1-t)·√A + t·√B)²` with `t = (frame − start)/duration`, never 1 inside the effect; mid-cross dips 0.115 below the sRGB lerp from crimson/teal (closed form (0.341, 0.349, 0.463) confirmed per frame); AgX-default sampling poisons the fit (0.146 red-channel error, `view_transform='Standard'` mandatory); deleting a consumed input orphans-and-deletes the effect — follow-up to `vse-cut-list`
 - Falsy `bpy_prop_collection` trap snippet: an empty collection is falsy, so `editor.strips or editor.sequences` silently falls through to the legacy accessor on an empty timeline — always branch on `hasattr`; likely generalizes across the API (found authoring `vse-cut-list`)
 - ~~Collision compound witness~~ **SHIPPED** as `examples/collision-hull-proxy/` — game-prop collision as a compound of convex pieces, each a `bmesh.ops.convex_hull` of a coarse `sec(π/n)`-inflated cage (containment 5.9e-08, watertight, positive signed volume, Euler 2, per-piece 255-face budget: body 70, caps 60×3, compound 250); a hull of the dense render mesh measures 374 faces — over budget — which is why pipelines hull cages; proud details cost cage rows, concave grooves are free; byte-identical on 4.5.11 and 5.1.2
-- Custom-normals / shade-by-angle witness (game prop shading) — `use_auto_smooth` removed in 4.1; assert what 4.5 vs 5.1 actually expose (`shade_smooth_by_angle` operator / Smooth-by-Angle node group), per-loop custom normals surviving depsgraph evaluation, unit-length basis, hard edges landing exactly where an independently recomputed dihedral angle crosses the threshold
+- ~~Custom-normals / shade-by-angle witness~~ **SHIPPED** as `examples/custom-normals-shade/` — the post-4.1 shading contract: `use_auto_smooth`/`use_custom_normals`/`calc_normals` are AttributeError on BOTH 4.5.11 and 5.1.2; `set_sharp_from_angle` sharp sets match an independent dihedral recompute exactly (188/388 edges, 3 meshes); evaluated normal welds/splits exact (0.0 dev); custom split normals survive depsgraph evaluation within int16 quantization (1.407e-04, not float-exact); **divergence**: the legacy `shade_auto_smooth` operator CANCELS headless on 4.5 ("Asset loading is unfinished", mesh untouched, no exception) while 5.1 FINISHES with the Smooth-by-Angle NODES modifier — the data API is the portable path
 - prop-origin-transform witness — origin to base center, `transform_apply` through the data API, delta transforms, `matrix_parent_inverse` so parented children do not teleport; closed forms: post-apply scale exactly (1,1,1), local bbox min Z == 0, world bbox unchanged (builds on `parent-inverse-orrery`, does not duplicate it)
 - mesh-hygiene-audit witness — the engine-ingest checklist as executable contract: no ngons, no loose vertices, no non-manifold edges, no zero-area faces, consistent outward winding; closed forms via Euler characteristic and exact edge-face incidence counts