Merge pull request #67 from TMHSDigital/feat/uv-layer-grid-example

feat: add uv-layer-grid example (create_grid calc_uvs silent no-op)

Author: TMHSDigital

.cursor-plugin/plugin.json

@@ -78,6 +78,7 @@
     "examples/temp-override-join",
     "examples/text-version-stamp",
     "examples/turntable",
+    "examples/uv-layer-grid",
     "examples/wave-displace"
   ]
 }

.github/workflows/blender-smoke.yml

@@ -326,3 +326,15 @@ jobs:
           # it. Exits non-zero on failure.
           xvfb-run -a "$BLENDER" --background \
             --python examples/image-pixels-testcard/image_pixels_testcard.py --
+
+      - name: Shipped example - uv layer grid (calc_uvs silent no-op)
+        run: |
+          set -euo pipefail
+          # Check only (no render): create_grid(..., calc_uvs=True) without a
+          # pre-existing UV layer leaves 0 layers (silent no-op); pre-create +
+          # calc_uvs fills loops to the closed-form grid UVs
+          # ((x/size+1)/2, (y/size+1)/2) within 1e-6 including mesh persistence;
+          # explicit loop assignment is the calc_uvs-free fallback. Exits
+          # non-zero on failure.
+          xvfb-run -a "$BLENDER" --background \
+            --python examples/uv-layer-grid/uv_layer_grid.py --

AGENTS.md

@@ -27,7 +27,7 @@ The content base (counts are CI-enforced against README.md and the manifest):
 - 2 templates: `extension-addon-template` for Extensions Platform add-ons,
   and `headless-batch-script-template` for unattended batch jobs.
 - 17 snippets covering canonical patterns.
-- 20 examples under `examples/<name>/`: runnable scripts that assert a real
+- 21 examples under `examples/<name>/`: runnable scripts that assert a real
   API contract with deterministic checks, exit non-zero on failure, and
   optionally render a still via `--output`. Each is executed headless on
   Blender 4.5 LTS and 5.1 by `blender-smoke.yml`; its render ships in the
@@ -42,7 +42,7 @@ Blender-Developer-Tools/
   rules/<rule-name>.mdc          # 6 rule files
   templates/<template-name>/     # 2 starter templates
   snippets/<snippet-name>.py     # 17 standalone Python snippets
-  examples/<name>/               # 20 runnable smoke-gated examples (+ gallery.json)
+  examples/<name>/               # 21 runnable smoke-gated examples (+ gallery.json)
   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

@@ -19,7 +19,7 @@ skills/<skill-name>/SKILL.md   - AI workflow definitions, 12 total
 rules/<rule-name>.mdc          - Anti-pattern rules, 6 total
 templates/<template-name>/     - Starter projects, 2 total
 snippets/<snippet-name>.py     - Standalone code patterns, 17 total
-examples/<name>/               - Runnable smoke-gated examples, 20 total (+ gallery.json)
+examples/<name>/               - Runnable smoke-gated examples, 21 total (+ gallery.json)
 scripts/build_gallery.py       - Regenerates docs/gallery/ from gallery.json (stdlib only)
 scripts/site/                  - Vendored landing-page build (Jinja2)
 docs/gallery/                  - Committed generated gallery pages + hero renders
@@ -80,11 +80,11 @@ v0.1.0: canonical object creation and deletion, depsgraph evaluated mesh, bmesh
 
 v0.2.0: Principled BSDF material, driver-with-custom-function via `driver_namespace`, application handler registration, shader node group with cross-version `interface` API, `foreach_get` bulk vertex read, version-branch skeleton, and USD export with `evaluation_mode='RENDER'`.
 
-## Examples (20)
+## Examples (21)
 
 Runnable scripts at `examples/<name>/`, each asserting a real API contract with
 deterministic checks (exit non-zero on failure) and optionally rendering a still via
-`--output`. All twenty run headless on Blender 4.5 LTS and 5.1 in `blender-smoke.yml`;
+`--output`. All twenty-one run headless on Blender 4.5 LTS and 5.1 in `blender-smoke.yml`;
 their renders ship in the site gallery at `docs/gallery/`. `examples/gallery.json` is the
 gallery's source of truth. When authoring a new one, copy the anatomy of
 `examples/bmesh-gear/` (script structure, README shape, dark-studio render recipe) and

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>20 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>21 examples</strong>
 </p>
 
 <p align="center">
@@ -36,7 +36,7 @@
 
 ## Overview
 
-This repository ships **12 skills, 6 rules, 2 templates, 17 snippets, and 20 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 21 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.
 
@@ -171,7 +171,7 @@ non-destructive path.
 </details>
 
 <details>
-<summary><strong>Mesh, curves &amp; text</strong> — 6 examples</summary>
+<summary><strong>Mesh, curves &amp; text</strong> — 7 examples</summary>
 
 <table>
 <tr>
@@ -186,6 +186,20 @@ A 14-tooth gear built entirely with bmesh — with `bm.free()` in a `try`/`final
 ownership contract demands. Asserts the closed-form vert/edge/face counts and that the
 result is watertight (every edge borders exactly two faces).
 
+</td>
+</tr>
+<tr>
+<td width="46%" valign="middle">
+<a href="examples/uv-layer-grid/"><img src="examples/uv-layer-grid/preview.webp" alt="UV layer grid: two easel panels on a dark studio floor — left a flat teal square from a missing UV layer sampling texel (0,0), right a magenta/cyan neon checker proving pre-create + calc_uvs" /></a>
+</td>
+<td valign="middle">
+
+### [uv-layer-grid](examples/uv-layer-grid/)
+
+`bmesh.ops.create_grid(..., calc_uvs=True)` is a silent no-op unless a UV layer already
+exists — without one an Image Texture samples texel (0, 0) everywhere. Asserts the hazard,
+the pre-create repair against closed-form grid UVs, and an explicit assignment fallback.
+
 </td>
 </tr>
 <tr>

ROADMAP.md

@@ -98,8 +98,9 @@ Not committed; target list for the next content version. (v0.3.0 shipped the smo
 - Bump `blender_version_min` in the templates if 5.2 APIs are used
 - Additional snippets for asset library scripting, EXR baking, multi-file extensions
 - Gallery coverage follow-ups from the GPv3 review: light-linking, VSE sequences-to-strips witness (`grease-pencil-rosette`, `armature-bend`, `text-version-stamp`, and `image-pixels-testcard` shipped first)
-- UV-layer authoring witness: `bmesh.ops.create_grid(calc_uvs=True)` silently creates no UV layer unless one already exists, and an Image Texture without UVs samples texel (0,0) everywhere (found while authoring `image-pixels-testcard`)
+- ~~UV-layer authoring witness~~ **SHIPPED** as `examples/uv-layer-grid/` — `create_grid(..., calc_uvs=True)` silent no-op without a pre-existing UV layer; closed-form UV fill + explicit assignment fallback; dual-panel render (flat texel (0,0) vs neon checker)
 - Image save-format witness: float images saved to PNG with varying alpha suffer premultiply quantization (~0.98 worst-case round-trip error at 8-bit alpha extremes); EXR vs PNG storage contract
+- Attribute domain witness: writing a POINT-domain color attribute and reading it as if it were CORNER (or vice versa) silently shears colors across shared verts — companion to `color-attribute-wheel`
 
 ## Future (uncommitted)
 

docs/gallery/assets/uv-layer-grid-hero.webp

@@ -199,6 +199,7 @@ <h1>Examples Gallery</h1>
     <button class="chip" data-tag="rendering" type="button">rendering</button>
     <button class="chip" data-tag="shape-keys" type="button">shape-keys</button>
     <button class="chip" data-tag="transforms" type="button">transforms</button>
+    <button class="chip" data-tag="uv" type="button">uv</button>
   </div>
   <main id="main">
     <div class="grid">
@@ -422,6 +423,17 @@ <h2><a href="image-pixels-testcard/">image-pixels-testcard</a></h2>
           <a class="card-link" href="image-pixels-testcard/">View example <span aria-hidden="true">&rarr;</span></a>
         </div>
       </article>
+      <article class="card" data-tags="mesh bmesh uv materials">
+        <a class="card-media" href="uv-layer-grid/" aria-label="uv-layer-grid example detail page">
+          <img src="assets/uv-layer-grid-hero.webp" alt="uv-layer-grid — The UV-layer authoring hazard — bmesh" loading="lazy" decoding="async" />
+        </a>
+        <div class="card-body">
+          <h2><a href="uv-layer-grid/">uv-layer-grid</a></h2>
+          <p class="teaches">The UV-layer authoring hazard — bmesh.ops.create_grid(..., calc_uvs=True) is a silent no-op unless a UV layer already exists; without one an Image Texture samples texel (0,0) everywhere.</p>
+          <p class="witnesses"><span class="tag">witnesses</span> calc_uvs=True alone leaves 0 UV layers; pre-create + calc_uvs fills loops to the closed-form grid UVs ((x/size+1)/2, (y/size+1)/2) within 1e-6; explicit loop assignment is the calc_uvs-free fallback.</p>
+          <a class="card-link" href="uv-layer-grid/">View example <span aria-hidden="true">&rarr;</span></a>
+        </div>
+      </article>
     </div>
   </main>
   <footer>