[framework] add reproducible assembly preview tooling

[sunzhenchuan007]

What changed

• add uv run bench2 preview-parts <family> for named cq.Assembly families;
• make the normal bench2 preview <family> generate the same component artifact automatically for Assemblies;
• preserve nested parent/child Location transforms and render separate VTK actors with correct depth occlusion;
• validate family.json component names, quantities, and solids consistency before rendering;
• group repeated instances by semantic component by default, with --per-instance for one-at-a-time highlighting;
• document the Assembly naming contract and add focused framework tests.

Why

Assembly families currently need family-specific scripts to build preview_parts.png. The existing STEP path folds an Assembly into a Compound and loses component names, so it cannot reproducibly produce semantic component four-views and highlight rows for unrelated families.

User impact

Contributors can now run one framework command. The output is deterministic designs/<family>/preview_parts.png: component four-views, full assembly overview, then metadata-ordered red-on-gray highlights. Invalid or unnamed Assembly metadata fails clearly instead of producing a misleading image.

Validation

• Ruff: pass
• Python compile: pass
• 9 unit tests: pass (nested translation/rotation, repeated instances, semantic separation, metadata failures, grouped/per-instance order, spec-only params, deterministic multi-actor rendering)
• real CLI smoke test: bench2 preview-parts safety_swivel_load_ring pass
• repeated end-to-end SHA-256: DA4DDA3E93CB42AF940267030C6A4D648DD6845EEDC8BC55A408220EAF986E27
• human inspection of the generated five-component four-view/overview/highlight image: approved
• git diff --check: pass

No family source, preview PNG, temporary renderer, PDF, or research attachment is included in this PR.

Closes #95

[github-actions]

bench2 validate

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.