feat(showcase): add bookshelf

[TMHSDigital]

What

New showcase piece showcase/bookshelf/: a stained bookcase (two housed shelves, a base on a recessed plinth, five lapped back boards, stepped cornice) with thirty-eight rounded-spine hardbacks. Twenty-nine stand, seven lie in three stacks, and two lean on a neighbour. Each book has a U-section cover (cloth or leather), a page block glued into its boards, and two gilt bands built on the spine's own chain.

Why this item

MODE: auto, SUBJECT: auto. The first unclaimed ROADMAP.md candidate that was not in flight was "Bookshelf with leaning books". No open PRs. origin/feat/showcase-butter-churn is a stale branch of a piece that already shipped. It is a showcase piece, not an example: it asserts declared asset budgets and witnesses no API contract.

The budget that matters: lean contact (exit 22)

A leaning book has to rest on its neighbour's head edge and on the shelf, not in either. Neither mistake is visible to the seat, envelope, triangle or overlap budgets. The overlap budget has to exempt this contact by design. The piece:

1. finds each leaning book on the finished mesh (its largest face, a board, tilted 3°–80°);
2. finds the upright neighbour on the side it leans toward;
3. reads the plane of the leaning board's outer face off the mesh;
4. asserts that the neighbour's deepest vertex sits 0.3–2.0 mm behind that plane. Measured: 0.80 mm on both leaning books.

It measures against a plane, not the cover solid. The first version measured against the solid, and --deep-lean then exited 0: the board is 2.8 mm thick, so a head edge driven 4.5 mm in ends up in the book's hollow and reads as no contact.

Falsifiers (all live-run-proven on 4.5.11, 5.1.2, 5.2.1, identical exits; AABB unchanged in every run)

Flag	Target budget	Measured	Exit
--skip-decimate	LOD1 ratio	1.0000	9
--stray-vert	hygiene	loose_v 1	15
--lift-z	grounded zmin	0.050	16
--float-side	named sides	side z 5 mm	16
--short-shelves	dado bite	−4.0 mm	17
--loose-pages	page-block bite	−0.9 mm	17
--float-books	book seat	−5.0 mm	18
--float-bands	band seat	−1.1 mm	18
--tall-book	headroom	−3.9 mm	20
--uniform-books	size spread	1.030 / 1.000	21
--air-lean	lean contact	−3.0 mm	22
--deep-lean	lean contact	+4.5 mm	22
--crowd-books	book overlaps	11	23
--sharp-shelf	edge treatment	12 edges	24

python tests/check_falsifier_targets.py passes statically, and --run <5.2.1> --only bookshelf gives 14/14 ok. Both are live-run-proven.

Exit-code matrix (live-run-proven, local binaries under .scratch/)

Run	4.5.11 LTS	5.1.2	5.2.1 LTS
default	0	0	0
every falsifier above	declared code	declared code	declared code
tests/smoke/run_example.py	PASS	PASS	PASS

The default measurements are byte-identical across all three versions, with two exceptions. LOD2 is 2388 tris on 5.2 against 2398 on 4.5 and 5.1; this is the known DECIMATE COLLAPSE divergence, and the LOD2 ratio stays inside its band. The glTF file is 8 bytes smaller on 5.2 (785828 vs 785836 bytes).

The version reported by each binary: Blender 4.5.11 LTS, Blender 5.1.2, Blender 5.2.1 LTS. The smoke runs on CI's floating 4.5/5.2 point releases will be CI-proven once the checks report.

Local validate jobs (live-run-proven)

• The check_engine_id, check_exit_code_readme, check_falsifier_targets, check_gallery_images and check_import_export_rules checks all pass.
• tests/smoke/test_harness.py passes.
• measure_hero_drift --only bookshelf reports "matches" (mean_abs 0.0036).
• build_gallery.py builds 51 examples and 35 showcase pieces. I read the generated <img alt> in docs/gallery/index.html and docs/gallery/bookshelf/index.html: it is the full sentence, not truncated.
• The count, structure and manifest jobs are left to CI (CI-proven).

Visual gates

• Contact sheet: docs/gallery/contact-sheets/bookshelf-contact-sheet.webp. Measured values are from contact_sheet.py; the verdicts are inspection-only.
  • Mean luma 0.227, inside the calibration band 0.151–0.279. Pass.
  • Stage darkness 0.207, inside 0.145–0.213. Pass.
  • Wedge warmth +0.106, a warm pool, lower than damped-track and gear. Pass.
  • Saturation 0.216, inside 0.144–0.250. Pass.
  • Subject fill: y 0.794 (x 0.353, a tall narrow piece). Pass.
  • Thumbnail legibility: it reads as a bookcase with books at thumbnail size. Pass.
• Asset sheet: docs/gallery/asset-sheets/bookshelf.webp, set against collision-hull-proxy, socket-attach-points, vertex-color-ao, wheelbarrow and apothecary-shelf. Verdict (inspection-only): not the least-designed object in the lineup. The book fill, the spine bands, the stacks and the leaners give it detail comparable to apothecary-shelf, and more than the hydrant or the well. The carcass alone is plainer than the apothecary's crest-and-drawer carcass.
• Hero inspection (inspection-only): no z-fight speckle, and spines shade round. Gilt was first fully metallic, which mirrored the dark stage and rendered the bands black; it is now half metallic, and the bands read across every spine.

Findings the budgets forced

These are recorded in the piece README:

• The page-block tail sat on a shelf's plane.
• Every spine has the same facet angles, so square neighbours shared planes by accident. The fix is a four-step yaw cycle; a half-degree cycle was not enough on 45° chamfers.
• Neighbours' front-facing planes coincided. The fix is a 0.9 mm set-back step.
• A stacked book could land its underside on the plane of the page block below it.
• Parts were matched to covers by centroid, which went wrong in stacks. They are now matched by mean vertex distance.
• The deep lean went through the board, as described above.

Labels

needs-5.1 is applied because the piece runs a Cycles normal bake and uses the version-branched EEVEE id, so CI also exercises 5.1.

🤖 Generated with Claude Code