feat: add image-pixels-testcard example (flat RGBA pixel buffer + save() lifecycle witness) (#60)

The gallery had no coverage of bpy.types.Image, and bulk pixels.foreach_set
was an explicit ROADMAP candidate. A procedural broadcast test card written
with one foreach_set witnesses the contracts AI-generated image code gets
wrong: the buffer is always flat RGBA (channels == 4 even with alpha=False),
byte storage quantizes at exactly <= 0.5/255 and strictly > 0, scale()
reallocates so stale-size bulk reads raise, and Image.save() silently flips
source to FILE and drops the in-memory buffer -- later pixels reads come from
whatever sits on disk, proven by overwriting the file with an imposter.
save_render() is the non-destructive path. All contracts probed identical on
4.5.11 LTS and 5.1.2.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: TMHSDigital

.cursor-plugin/plugin.json

@@ -70,6 +70,7 @@
     "examples/gn-instance-grid",
     "examples/gn-sdf-remesh",
     "examples/grease-pencil-rosette",
+    "examples/image-pixels-testcard",
     "examples/parent-inverse-orrery",
     "examples/shader-node-group",
     "examples/shape-key-blend",

.github/workflows/blender-smoke.yml

@@ -311,3 +311,18 @@ jobs:
           # at to_mesh_clear(). Exits non-zero on failure.
           xvfb-run -a "$BLENDER" --background \
             --python examples/text-version-stamp/text_version_stamp.py --
+
+      - name: Shipped example - image pixels testcard (flat RGBA buffer + save lifecycle)
+        run: |
+          set -euo pipefail
+          # Check only (no render): a procedural broadcast test card written with
+          # one pixels.foreach_set; asserts the buffer is always flat RGBA
+          # (channels == 4 even with alpha=False, RGB-stride writes raise), the
+          # byte round-trip error is <= 0.5/255 and strictly > 0 (storage really
+          # is 8-bit) while float_buffer=True round-trips at float32 precision,
+          # scale() reallocates so stale-size bulk reads raise, and save() flips
+          # source to FILE and drops the buffer (pixels silently re-load from
+          # disk — proven with an imposter file) while save_render() preserves
+          # it. Exits non-zero on failure.
+          xvfb-run -a "$BLENDER" --background \
+            --python examples/image-pixels-testcard/image_pixels_testcard.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.
-- 19 examples under `examples/<name>/`: runnable scripts that assert a real
+- 20 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
@@ -41,7 +41,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>/               # 19 runnable smoke-gated examples (+ gallery.json)
+  examples/<name>/               # 20 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, 19 total (+ gallery.json)
+examples/<name>/               - Runnable smoke-gated examples, 20 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 (19)
+## Examples (20)
 
 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 nineteen run headless on Blender 4.5 LTS and 5.1 in `blender-smoke.yml`;
+`--output`. All twenty 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

@@ -17,14 +17,14 @@
 </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>19 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>20 examples</strong>
 </p>
 
 ---
 
 ## Overview
 
-This repository ships **12 skills, 6 rules, 2 templates, 17 snippets, and 19 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 20 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.
 
@@ -332,6 +332,25 @@ but planar, that body edits regenerate geometry, that `version_string` is not ba
 semver on LTS builds (`"4.5.11 LTS"`), and that a Mesh reference dies at
 `to_mesh_clear()`.
 
+</td>
+</tr>
+<tr>
+<td width="46%" valign="middle">
+<a href="examples/image-pixels-testcard/"><img src="examples/image-pixels-testcard/preview.webp" alt="Image pixels testcard: a studio monitor showing a procedural broadcast test card — seven neon color bars behind the classic dark circle, a luminance ramp, and a PLUGE row with a white bottom-left origin marker — over a teal underglow on a dark studio floor" /></a>
+</td>
+<td valign="middle">
+
+### [image-pixels-testcard](examples/image-pixels-testcard/)
+
+A procedural broadcast test card written into `bpy.data.images.new()` with one
+`pixels.foreach_set()` call. Asserts the buffer is always flat RGBA (`channels == 4`
+even with `alpha=False`), that byte storage quantizes at exactly ≤ 0.5/255 and
+strictly > 0 while `float_buffer=True` round-trips at float32 precision, that
+`scale()` reallocates (stale-size reads raise), and the `save()` trap: `source`
+silently flips to `FILE`, the buffer drops, and later `pixels` reads come from
+whatever sits on disk — proven with an imposter file. `save_render()` is the
+non-destructive path.
+
 </td>
 </tr>
 </table>

ROADMAP.md

@@ -97,7 +97,9 @@ Not committed; target list for the next content version. (v0.3.0 shipped the smo
 - Refresh the `slotted-actions-animation` skill against any 5.2 changes
 - 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, bulk `pixels.foreach_set`, VSE sequences-to-strips witness (`grease-pencil-rosette`, `armature-bend`, and `text-version-stamp` shipped first)
+- 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`)
+- 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
 
 ## Future (uncommitted)