feat: add lightmap-uv-channel example

[TMHSDigital]

What this is

New example lightmap-uv-channel: the second UV layer engines require for baked lighting, on a reusable market cart (bed, axle, two wheels, four posts, arched canvas canopy — ground-level pivot, identity transforms by construction, Cart.* datablocks, watertight parts). UV0 is the texture channel (deterministic box projection); UVLight is the bake atlas (smart_project → lightmap_pack), with every contract independently verified rather than trusted from the packer.

Contract witnessed (check-only path)

Check	Measured (identical on 5.1.2 / 4.5.11)	Exit
Layers named UVMap/UVLight, exactly two per part	9 parts	3
Flags: active == UVLight, active_render == UVMap	re-asserted after ops; ops clear both flags	4
Channel 0 untouched by UV1 unwrap	drift 0.0 (tol 1e-6)	5
Every UV1 loop inside [0,1]	tol 1e-5	6
Non-overlap, independent binned strict-SAT	0 pairs	7
Margin ≥ half nominal (MARGIN_DIV × 0.01)	measured 0.00401 vs nominal 0.002	8
Island census + watertight parts	1114 islands, all manifold	9

Check output byte-identical on 4.5.11 LTS and 5.1.2. The UV layout is packer-version-dependent by design; the contracts are layout-independent invariants.

Falsification evidence (live run, exit codes observed)

• Clobber trap (the classic): unwrap+pack with active left on UVMap → UV0 drift 2.068 (tol 1e-6) → exit 5 territory. Confirmed on both versions with identical measured drift.
• Overlap injection: island translated onto a neighbor → 15 strict-SAT hits → exit 7.
• Margin collapse: MARGIN_DIV=0 → min island distance 2e-5 < 0.001 floor → exit 8.

Authoring hazards pinned (in code comments + README; ROADMAP updated)

• Held MeshUVLoopLayer.data after edit-mode UV ops segfaults 4.5.11 headless — EXCEPTION_ACCESS_VIOLATION, 5/5 repro, bisected down from a full-pipeline crash to the exact dangling read; the same read survives on 5.1.2. Second confirmation of the UV-handle lifetime hazard (first: triangulate-tangents); the ROADMAP snippet note now carries both.
• lightmap_pack silently no-ops (exit OK) when the active layer has no UVs — unwrap first, then pack.
• uv_layers.new() moves no flags; the edit-mode UV ops clear them — both halves of the active/active_render trap are pinned by the check.

Render and visual passes (iteration log)

• Pass 1 (6 iterations): draft1 blank board (islands floating off-board above frame — framing exit 10) + canopy clipped white; islands remapped onto the board face from live UVs; camera raised (draft4 framing ok, board too small); board enlarged/brought in (draft5 re-violated top, rebalanced) → draft6 final: cart co-anchored with the glowing atlas board, framing fill 0.822y, all margins clear.
• Pass 2 (4 iterations): falsify via collapse-drag (invisible degenerate polys), coplanar z-fight, tiny bevel strips → final: second-largest island translated intact onto the largest, drawn proud in emissive red — the overlap is unmistakable in the comparison capture.
• Pass 3: 320px thumbnail reads as cart + glowing atlas board in under a second.
• Pass 4 (in situ, Playwright): card reads instantly in compact mode at 1280 and 390; distinct from modular-kit-snap and every other card; detail page verified. featured_rank: no — strong card, but does not outclass any of the current eight featured members.
• Pass 5 (contact sheet): docs/gallery/contact-sheets/lightmap-uv-channel.webp — sits naturally in the calibration lineup (dark stage, warm subject, palette accents). Mean luminance 55.1 vs calibration 44.5–77.7 — mid-range, no outlier risk.

Generated output read

Card alt re-read character by character — complete, no truncation. WITNESSES numbers verified against measured check output: drift 0.0, 1114 islands, 0 overlaps, 0.00401 — all exact.

Test plan (exact binaries)

• E:\Blender-Developer-Tools\.scratch\blender-5.1.2-windows-x64\blender.exe — Blender 5.1.2: check exit 0, renders, all falsification probes, API probes.
• E:\Blender-Developer-Tools\.scratch\blender-4.5.11-windows-x64\blender.exe — Blender 4.5.11 LTS: check exit 0 (byte-identical), render parity confirmed visually, clobber probe, segfault bisect series.
• CI: both blender-smoke jobs run the new step (check-only) on their floating series releases.

Live run vs inspection-only

Live run: all checks, probes, renders, framing numbers, in-situ captures, contact sheet. Inspection only: engine-side bake/import behavior (not claimed — the README does not claim engine compatibility), Cycles engine path (--engine cycles flag exists; renders used EEVEE).