[framework] bench2 preview-parts: reproducible assembly component previews

[BenchCAD]

What changed

• uv run bench2 preview-parts <family> renders designs/<family>/preview_parts.png for named-cq.Assembly families: one four-view row per semantic component (own frame, bounding box in mm), the complete assembly in its true pose, then red-on-gray component highlight rows in family.json components order — repeated instances grouped with quantity=N by default, --per-instance for one row per instance.
• uv run bench2 preview <family> runs the same render automatically when build(**params) returns a named Assembly; single-part families are unchanged.
• The render comes from the derived stand-alone program — the same artifact every other preview renders. A new export harness (execute_cq_to_parts) executes it in the usual subprocess and walks the Assembly exactly like cq's toCompound(), exporting each shape-bearing node's raw local shape plus its absolute 3x4 world transform, so nested parent/child Location transforms survive without parsing STEP product structure.
• render_iso's VTK pipeline is generalized to styled multi-actor scenes (render_actors): shared normalized frame, camera fitted over the union of all actors, z-buffer depth occlusion. render_iso is now the one-actor teal case — same pipeline, same bytes.
• Naming contract, documented in docs/DESIGN_SPEC.md: name every shape-bearing node exactly after its component (quantity 1) or <component>_<NN> for repeated instances; exact declared names win over suffix stripping; semantically distinct components stay separate even with identical geometry. family.json must declare components with solids equal to the quantity sum — bench2 validate now checks that consistency, and every violation (non-Assembly result, unmatched or duplicate instance names, quantity drift) fails clearly instead of producing a misleading image.
• tests/ (new, wired into validate.yml): hermetic fixture families through the real derive -> subprocess -> manifest -> VTK pipeline — nested locations, translation + rotation, repeated instances, grouped vs --per-instance row layout, metadata mismatches, single-part skip/fail, and byte-determinism of the output PNG.

Example — what it renders (in-repo, committed)

docs/examples/preview_parts_demo/ is a runnable demo assembly — block, flanged bushing, and a bolt_01/bolt_02 pair in a nested, 30-deg-rotated sub-assembly — with both artifacts committed, embedded in DESIGN_SPEC, and kept runnable by a framework test.

Grouped default — one four-view row per component (bbox in mm), the complete assembly in pose, then red-on-gray highlight rows in components order (bolt highlights both instances, quantity=2):

--per-instance — bolt_01 and bolt_02 each get their own highlight row:

--transparent — non-highlighted components ghosted (see-through): the bushing shaft buried in its bore and both bolt shanks stay visible when highlighted. The opaque modes above are unchanged (styles gained an opacity channel; existing output is byte-identical):

Why

Multi-component families had no reproducible framework command for preview_parts.png: the STEP path folds an Assembly into a compound, so component names and hierarchy never reach the renderer, and each assembly family hand-rolled its own render script. family-pr-checks and the dossier close-out already expect the artifact; this makes it a one-command, deterministic framework output (hard / seed 0) for any unrelated named-Assembly family.

Draft #96 explores the same surface and its layout is kept here (it matches the reviewer-approved artifact in #80); the framework difference is that this implementation renders the derived program via the standard subprocess harness rather than calling part.build() in-process, so component evidence traces to the exact program the benchmark asks a model to produce.

Validation

• uv run ruff check framework tests — pass
• 21 unit tests — pass (uv run python -m unittest discover -s tests)
• bench2 validate on all three merged families — PASS (validate gate addition is inert for single-part families)
• Real-family smoke: bench2 preview-parts safety_swivel_load_ring (sources from [family] safety_swivel_load_ring #80, run in a scratch tree — that family and its PR are untouched) renders the 5-component grid; two consecutive runs produce byte-identical PNGs (same SHA-256), --per-instance degenerates to the grouped layout as expected since every quantity is 1
• Rendered output inspected by hand: component rows, pose, occlusion, and highlight order all read correctly
• Note: boundary edges render red under the current vtkFeatureEdges defaults; that is main's existing single-part behavior (visible in every committed preview.png) and is deliberately preserved byte-for-byte here rather than restyled in the same PR

Framework-only change: no file under designs/ is touched.

Closes #95

[github-actions]

bench2 validate

clevis_fork_head

  ✓ family.json: keys + base_plane valid
  ✓ pieces: build(10 params) + PARAM_SPEC + check present
  ✓ PARAM_SPEC: 10 params, all entries complete
  ✓ easy: 4/4 seeds sample+check+build+execute clean
  ✓ medium: 4/4 seeds sample+check+build+execute clean
  ✓ hard: 4/4 seeds sample+check+build+execute clean
  ✓ coverage: d1 reaches all 8 declared values (standard table fully covered)
  ✓ coverage: is_long reaches all 2 declared values (standard table fully covered)
  ✓ difficulty separation: difficulties produce distinct programs
  ✓ geometry novelty: 9/12 unique shapes (25% duplicate)
  ✓ solids: every instance non-degenerate, 1 solid(s) each
PASS — designs/clevis_fork_head

set_screw_shaft_collar

  ✓ family.json: keys + base_plane valid
  ✓ pieces: build(6 params) + PARAM_SPEC + check present
  ✓ PARAM_SPEC: 6 params, all entries complete
  ✓ easy: 4/4 seeds sample+check+build+execute clean
  ✓ medium: 4/4 seeds sample+check+build+execute clean
  ✓ hard: 4/4 seeds sample+check+build+execute clean
  ✓ coverage: bore_d reaches all 15 declared values (standard table fully covered)
  ✓ difficulty separation: difficulties produce distinct programs
  ✓ geometry novelty: 7/12 unique shapes (42% duplicate)
  ✓ solids: every instance non-degenerate, 1 solid(s) each
PASS — designs/set_screw_shaft_collar

slotted_din_rail

  ✓ family.json: keys + base_plane valid
  ✓ pieces: build(10 params) + PARAM_SPEC + check present
  ✓ PARAM_SPEC: 11 params, all entries complete
  ✓ easy: 4/4 seeds sample+check+build+execute clean
  ✓ medium: 4/4 seeds sample+check+build+execute clean
  ✓ hard: 4/4 seeds sample+check+build+execute clean
  ✓ difficulty separation: difficulties produce distinct programs
  ✓ geometry novelty: 6/12 unique shapes (50% duplicate)
  ✓ solids: every instance non-degenerate, 1 solid(s) each
PASS — designs/slotted_din_rail

speaker_pole_mount_socket

  ✓ family.json: keys + base_plane valid
  ✓ pieces: build(8 params) + PARAM_SPEC + check present
  ✓ PARAM_SPEC: 8 params, all entries complete
  ✓ easy: 4/4 seeds sample+check+build+execute clean
  ✓ medium: 4/4 seeds sample+check+build+execute clean
  ✓ hard: 4/4 seeds sample+check+build+execute clean
  ✓ coverage: bore_d reaches all 2 declared values (standard table fully covered)
  ✓ coverage: flange_od reaches all 2 declared values (standard table fully covered)
  ✓ coverage: flange_t reaches all 2 declared values (standard table fully covered)
  ✓ coverage: depth reaches all 6 declared values (standard table fully covered)
  ✓ difficulty separation: difficulties produce distinct programs
  ✓ geometry novelty: 9/12 unique shapes (25% duplicate)
  ✓ solids: every instance non-degenerate, 1 solid(s) each
PASS — designs/speaker_pole_mount_socket

Previews: the previews artifact on this run.

[BenchCAD]

Added the reviewable evidence this PR was missing: a committed, runnable example under docs/examples/preview_parts_demo/ (nested + rotated sub-assembly, repeated bolt_01/bolt_02), its grouped and --per-instance renders embedded in the PR body above and in DESIGN_SPEC, and a framework test that keeps the example runnable (d2037f4).

[BenchCAD]

Added --transparent per the request — opaque grouped/per-instance modes are unchanged, and the new ghost mode renders non-highlighted components see-through so internal parts (the bushing shaft in its bore, the bolt shanks) stay visible when highlighted. Demo artifact committed and embedded in the body above; DESIGN_SPEC/README/tests cover the mode (6af34db).

[sunzhenchuan007]

An old preview_parts.png might be left behind after failing

[BenchCAD]

@sunzhenchuan007 good catch on the stale artifact — fixed in f396456: preview_parts.png is now removed at the start of every run, so a failed run leaves nothing behind (and a family that stopped being an assembly sheds its obsolete artifact on the next preview); both paths are tested.

Also resolved the merge conflict with main: #115's centered-framing fix is ported into the multi-actor render_actors (projected-bounds midpoint over the union of all actors — identical math for the single-actor case), the cutaway panel comes along unchanged, and the demo artifacts are regenerated on the merged renderer. Branch is up to date with main and green locally.