feat: add light-link-studio example witnessing receiver collections in pixels (#91)

Light linking is the staging feature AI code misses twice: the API lives
on the light OBJECT (ld.light_linking is an AttributeError), and the
restriction only counts if it survives in pixels. The check renders twice
in one pass — linked (4.0x hero/decoy ratio at projected centers) and
unlinked in the same run (decoy rises 244% while the hero holds at 0.0%
drift) — and documents that EEVEE Next honors linking too (5.5x on 4.5,
5.9x on 5.1), with Cycles pinned for deterministic samples.

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

Author: TMHSDigital

.cursor-plugin/plugin.json

@@ -73,6 +73,7 @@
     "examples/gn-sdf-remesh",
     "examples/grease-pencil-rosette",
     "examples/image-pixels-testcard",
+    "examples/light-link-studio",
     "examples/lod-decimate-chain",
     "examples/parent-inverse-orrery",
     "examples/png-exr-alpha",

.github/workflows/blender-smoke.yml

@@ -437,3 +437,14 @@ jobs:
           # lerp deviation at mid. Exits non-zero on failure.
           xvfb-run -a "$BLENDER" --background \
             --python examples/vse-gamma-cross/vse_gamma_cross.py --
+
+      - name: Shipped example - light link studio (receiver collections in pixels)
+        run: |
+          set -euo pipefail
+          # Check only (two tiny Cycles renders): a key linked to the hero
+          # collection must light only the hero (luminance ratio >= 3x at
+          # projected centers), and unlinking must raise the decoy >= 50%
+          # with hero drift <= 5%. Also guards the Object-level API path
+          # (ld.light_linking is an AttributeError). Exits non-zero on failure.
+          xvfb-run -a "$BLENDER" --background \
+            --python examples/light-link-studio/light_link_studio.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>29 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>30 examples</strong>
 </p>
 
 <p align="center">
@@ -36,7 +36,7 @@
 
 ## Overview
 
-This repository ships **12 skills, 6 rules, 2 templates, 17 snippets, and 29 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 30 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.
 
@@ -186,7 +186,7 @@ byte images stay straight 8-bit. Also witnesses `EXR color_mode='RGB'` dropping
 </details>
 
 <details>
-<summary><strong>Mesh, curves &amp; text</strong> — 9 examples</summary>
+<summary><strong>Mesh, curves &amp; text</strong> — 10 examples</summary>
 
 <table>
 <tr>
@@ -306,6 +306,22 @@ ending in `length=` vs `frame_end=`, and `left_handle`/`right_handle`/`duration`
 the deprecated `frame_final_*`. Asserts closed-form spans, GC wiring and clamping, the
 consumed-input compositing contract, and a save/reload round-trip.
 
+</td>
+</tr>
+<tr>
+<td width="46%" valign="middle">
+<a href="examples/light-link-studio/"><img src="examples/light-link-studio/preview.webp" alt="Light link studio: a blazing orange hero sphere over a LINKED plaque beside a dim steel decoy over UNLINKED on a dark studio floor - one key light restricted to the hero collection" /></a>
+</td>
+<td valign="middle">
+
+### [light-link-studio](examples/light-link-studio/)
+
+Object light linking proven in pixels: a key linked to the hero's collection
+lights only the hero (4.0x luminance ratio at projected centers), and
+unlinking in the same check raises the decoy 244% with 0.0% hero drift. The
+API is `obj.light_linking` — the Light datablock has none — and EEVEE Next
+honors linking too (measured), with Cycles pinned for deterministic samples.
+
 </td>
 </tr>
 <tr>

ROADMAP.md

@@ -101,7 +101,7 @@ Not committed; target list for the next content version. (v0.3.0 shipped the smo
 - ~~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~~ **SHIPPED** as `examples/png-exr-alpha/` — float→PNG is RGBA16 and false-unpremultiplies as if associated-alpha (closed-form err 0.98 at RGB 0.02 / a=1/255); OpenEXR preserves float RGBA; byte→PNG is straight RGBA8; `EXR color_mode='RGB'` drops alpha
 - 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`
-- Light-linking collection witness: object light linking / receiver collections so a key illuminates only the hero (common AI miss when staging multi-light studios)
+- ~~Light-linking collection witness~~ **SHIPPED** as `examples/light-link-studio/` — the API is `obj.light_linking` on the light OBJECT (`ld.light_linking` is an AttributeError on both versions); linked ratio 4.0x at projected-center luminance samples, unlink raises the decoy 244–251% with 0.0% hero drift in the same two-render check; EEVEE Next honors linking too (5.5x on 4.5.11, 5.9x on 5.1.2), Cycles pinned for deterministic samples
 - ~~VSE sequences-to-strips witness~~ **SHIPPED** as `examples/vse-cut-list/` — `.sequences` removed on 5.x (4.5 bridges to `.strips`), `new_effect` end kwarg `frame_end=` (4.5) vs `length=` (5.x), `frame_final_*` deprecated in favor of `left_handle`/`right_handle`/`duration`, TRANSFORM effect type removed, GAMMA_CROSS clamps to the source overlap, effect strips consume inputs only when stacked above them, same-scene scene strips render transparent; save/reload round-trip + tiny-render pixel witness
 - ~~glTF export round-trip witness~~ **SHIPPED** as `examples/gltf-export-roundtrip/` — `export_yup` bakes `(x,y,z)→(x,z,−y)` into vertex data with no node rotation (probed identical on 4.5.11 and 5.1.2), `export_apply` ships the evaluated mesh (one disk vertex per evaluated loop), TEXCOORD_0 is V-flipped on disk, per-triangle material bindings survive; exporter/importer RNA signatures byte-identical between 4.5.11 and 5.1.2 (guarded against future renames); `Mesh.calc_normals()` removal on 5.x surfaced during authoring
 - ~~LOD decimate chain witness~~ **SHIPPED** as `examples/lod-decimate-chain/` — Decimate COLLAPSE evaluated through the depsgraph is non-destructive (obj.data keeps closed-form counts), evaluated tris hit `ratio × base` within 5% (measured 0.0–0.44%), silhouette bbox survives within 1e-3 (measured 7.7e-6); a stacked Decimate halves the effective ratio, an aggressive 0.02 ratio collapses the nose tip — both caught failure modes

docs/gallery/assets/light-link-studio-hero.webp

@@ -524,6 +524,17 @@ <h2><a href="vse-gamma-cross/">vse-gamma-cross</a></h2>
           <a class="card-link" href="vse-gamma-cross/">View example <span aria-hidden="true">&rarr;</span></a>
         </div>
       </article>
+      <article class="card" data-tags="rendering">
+        <a class="card-media" href="light-link-studio/" aria-label="light-link-studio example detail page">
+          <img src="assets/light-link-studio-hero.webp" alt="light-link-studio — One key, one hero: a light linked to a receiver collection lights only the hero, proven by two pixel renders in one pass." loading="lazy" decoding="async" />
+        </a>
+        <div class="card-body">
+          <h2><a href="light-link-studio/">light-link-studio</a></h2>
+          <p class="teaches">One key, one hero: a light linked to a receiver collection lights only the hero, proven by two pixel renders in one pass. Linked: 4.0x luminance ratio; unlinked in the same check: the decoy rises 244% while the hero holds at 0.0% drift.</p>
+          <p class="witnesses"><span class="tag">witnesses</span> The API is obj.light_linking on the light OBJECT (ld.light_linking is an AttributeError). Luminance is sampled at each sphere&#x27;s projected center; EEVEE Next honors linking too (5.5x on 4.5, 5.9x on 5.1), Cycles pinned for deterministic samples.</p>
+          <a class="card-link" href="light-link-studio/">View example <span aria-hidden="true">&rarr;</span></a>
+        </div>
+      </article>
     </div>
   </main>
   <footer>