feat(showcase): add book-trolley

[TMHSDigital]

Selection

MODE: auto, SUBJECT: auto. The first unclaimed item in the ROADMAP candidate pool was "Library ladder or book trolley with loose books" (the bookshelf shipped in #283). I built the trolley half as a showcase piece, because it is a prop with no API contract. Its value is a budget no shipped piece exercises: a two-point support. The ladder half goes back into the pool as its own candidate, a hook riding a round rail.

What it budgets

A double-sided library book truck. It has arched end panels standing in skids on four swivel casters, a flat deck, and on each side two troughs sloped 14°. Each trough is a tilted shelf with a backrest square to it. 47 hardbacks stand spines-out in the troughs and 5 lie in two loose stacks on the deck. Like every showcase piece it goes through UVs, a normal bake, LOD1/LOD2, a convex collider and a Unity glTF export.

The budget that matters (exit 21): a trough book rests on two supports, its tail on the shelf and its fore-edge against the backrest. If a book sits correctly on the shelf but stands off the backrest, it still passes every seat check, the AABB, the tri count and the overlap budget (which has to exempt both designed contacts). To catch that, the piece:

• pairs each shelf with the one backrest whose BVH overlaps it;
• finds each book's shelf by the nearest top plane, read off the mesh;
• asserts how deep the book's deepest cover vertex sits behind the backrest face plane, as a band of 0.3–2.0 mm.

Falsifiers — exit codes, live-run-proven on all three binaries

Binaries (local .scratch/): blender-4.5.11-windows-x64 (4.5.11 LTS), blender-5.1.2-windows-x64 (5.1.2), blender-5.2.1-windows-x64 (5.2.1 LTS).

Flag	Target budget	Declared	4.5.11	5.1.2	5.2.1	Measured
(default)	—	0	0	0	0	all budgets pass
--skip-decimate	LOD1 ratio	9	9	9	9	r1 1.0000
--stray-vert	hygiene	15	15	15	15	loose_v 1
--lift-z	grounded zmin	16	16	16	16	zmin 0.050
--float-caster	named wheels	16	16	16	16	wheel z 5.0 mm
--short-shelves	dado bite	17	17	17	17	−4.0 mm
--loose-pages	page-block bite	17	17	17	17	−0.9 mm
--float-books	book seat	18	18	18	18	−5.0 mm
--float-bands	band seat	18	18	18	18	−1.1 mm
--drop-plates	caster plate seat	18	18	18	18	−1.5 mm
--skew-caster	mirror symmetry	19	19	19	19	6.0 mm
--uniform-books	size spread	20	20	20	20	1.030 / 1.000
--off-back	backrest contact	21	21	21	21	−3.0 mm
--deep-back	backrest contact	21	21	21	21	4.5 mm
--crowd-books	book overlaps	22	22	22	22	13 overlaps
--sharp-deck	edge treatment	23	23	23	23	12 edges

Also live-run-proven:

• python tests/check_falsifier_targets.py (static): passes, 342 falsifiers across 36 pieces.
• --run <5.2.1> --only book-trolley: every falsifier observed at its declared code.
• tests/smoke/run_example.py --name book-trolley: [PASS] on 4.5.11, 5.1.2 and 5.2.1.
• Local validators: exit-code README, engine-id, import/export rules, gallery image sizes, harness unit tests (17 OK). build_gallery.py output is committed.

Default budgets are identical on all three binaries: 17704 tris, LOD 8852/3894, the same face counts, AABB 0.768×0.530×1.000, collider 308 tris. The only difference is the glTF size, 8 bytes smaller on 5.2 (exporter metadata, not a budget).

Findings fixed during authoring (live-run-proven)

• --drop-plates first exited 15, not 18. A 2 mm drop put the plate's lower chamfer and the fork's upper chamfer on the same 45° plane (8 coplanar pairs). The drop is now 2.5 mm.
• The edge falsifier first exited 19, not 23. Leaving one front backrest square broke mirror symmetry before the edge check ran. It now leaves the centred deck square instead.
• Bake artifacts, caught only on the hero (no budget measures them):
  • With a 10 mm cage, the books baked onto the end panels as pale streaks.
  • With a 3 mm cage, the loose stacks still baked dished grooves into the deck.
  • Fix: the bake source is now carcass + casters only (only wood takes a baked map), with the cage kept at 3 mm.

Visual gates

• Contact sheet: docs/gallery/contact-sheets/book-trolley-contact-sheet.webp, measured with scripts/contact_sheet.py. Calibration band: luma 0.151–0.279, stage 0.145–0.213.
  • Mean luminance 0.238: inside the band. Pass.
  • Stage darkness 0.204: inside the band. Pass.
  • Wedge warmth +0.166: warm, though cooler than bmesh-gear (+0.30) and damped-track-aim (+0.28). Pass.
  • Saturation 0.214: inside 0.144–0.250. Pass.
  • Subject fill 0.839 vertical (framing gate). Pass.
  • Thumbnail legibility: reads as a book cart with sloped rows. Pass (inspection-only).
• Asset sheet: docs/gallery/asset-sheets/book-trolley.webp, against collision-hull-proxy, socket-attach-points, vertex-color-ao, wheelbarrow and apothecary-shelf. Verdict pass (inspection-only): the trolley is not the least-designed object in the lineup. It has chamfered carcass, turned rail, four-part casters, 52 individually tinted, banded books and grained wood, and sits alongside apothecary-shelf in detail.
• Hero close-ups (inspection-only): no z-fight speckle, the wheels read round, the iron is near-black (not chrome), and there are no bake staircases after the fix above.

Labels

• live-run-proven: everything in the tables above, both sheets generated, framing gate.
• CI-proven: pending this PR's checks (blender-smoke 4.5/5.2, plus 5.1 via needs-5.1).
• inspection-only: the visual verdicts (thumbnail legibility, asset-sheet ranking, render defects).

🤖 Generated with Claude Code