Colours in exports from materials and appearances; Appearance command

- Bodies export (STEP, 3MF) in the colour they are shown in: an appearance,
  else the physical material's look, else the colour the body was imported
  with (Document::body_color / painted). Physical materials used to export
  no colour at all.
- AppearanceCommand (Modify): a colour per body ("#rrggbb" or [r, g, b];
  null follows the material again), kept in the design and across renames.
- Material looks move to solvecraft-doc (material_color); the viewport draws
  appearance, material or imported colour, as exported.
- Engine test: brass and red ABS bodies export, re-import with their RGB, and
  keep it through open and export again.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01AS5Tn3xieewUSg3uxrMVdL

crates/engine/src/cmd/browser.rs

@@ -219,6 +219,9 @@ fn rename_body(s: &mut Session, p: &Value) -> Result<Value> {
     if let Some(m) = d.materials.remove(&old) {
         d.materials.insert(name.to_string(), m);
     }
+    if let Some(c) = d.appearances.remove(&old) {
+        d.appearances.insert(name.to_string(), c);
+    }
     if let Some(c) = d.body_components.remove(&old) {
         d.body_components.insert(name.to_string(), c);
     }

crates/engine/src/cmd/file.rs

@@ -162,9 +162,10 @@ fn export_to(s: &Session, path: &str, format: Format, bodies: &[String]) -> Resu
     let name = std::path::Path::new(path).file_stem().map(|x| x.to_string_lossy().to_string()).unwrap_or_else(|| s.doc.name.clone());
     // A design with components exports as a STEP assembly; otherwise bodies as placed.
     let bytes = if format == Format::Step && bodies.is_empty() && !s.doc.occurrences.is_empty() {
-        solvecraft_io::step_assembly(&s.doc, &s.model.state(), &name)?
+        solvecraft_io::step_assembly(&s.doc, &s.doc.painted(&s.model.state()), &name)?
     } else {
-        solvecraft_io::export(&s.world_state(), bodies, format, &name)?
+        // Bodies carry the colour they are shown in (appearance, material or imported).
+        solvecraft_io::export(&s.doc.painted(&s.world_state()), bodies, format, &name)?
     };
     std::fs::write(path, &bytes).map_err(|e| EngineError::Other(format!("{path}: {e}")))?;
     Ok(json!({"path": path, "bytes": bytes.len(), "format": format!("{format:?}")}))

crates/engine/src/cmd/inspect.rs

@@ -23,6 +23,10 @@ pub static COMMANDS: &[CommandSpec] = &[
         .at("SOLID", "MODIFY")
         .icon("material")
         .params("bodies: [names]; material: name (Steel, Aluminum, ABS Plastic, …; `material.list`)"),
+    CommandSpec::new("AppearanceCommand", "Appearance", appearance)
+        .at("SOLID", "MODIFY")
+        .icon("appearance")
+        .params("bodies: [names]; color: \"#rrggbb\" or [r, g, b] (0–255), or null to follow the material"),
     CommandSpec::new("material.list", "List Materials", material_list).noundo(),
     CommandSpec::new("engine.commands", "List Commands", commands).noundo(),
 ];
@@ -271,6 +275,41 @@ fn physical_material(s: &mut Session, p: &Value) -> Result<Value> {
     Ok(json!({"bodies": bodies, "material": canonical}))
 }
 
+/// A colour parameter: `"#rrggbb"` or `[r, g, b]` (0–255).
+fn color_param(v: &Value) -> Option<[u8; 3]> {
+    if let Some(t) = v.as_str() {
+        let h = t.trim().trim_start_matches('#');
+        if h.len() != 6 || !h.is_ascii() {
+            return None;
+        }
+        let byte = |i: usize| h.get(i..i + 2).and_then(|x| u8::from_str_radix(x, 16).ok());
+        return Some([byte(0)?, byte(2)?, byte(4)?]);
+    }
+    let a = v.as_array().filter(|a| a.len() == 3)?;
+    let c = |i: usize| a.get(i).and_then(Value::as_f64).filter(|x| x.is_finite() && (0.0..=255.0).contains(x)).map(|x| x.round() as u8);
+    Some([c(0)?, c(1)?, c(2)?])
+}
+
+fn appearance(s: &mut Session, p: &Value) -> Result<Value> {
+    let cmd = "AppearanceCommand";
+    let bodies = string_list(p, "bodies");
+    let st = s.model.state();
+    if bodies.is_empty() || bodies.iter().any(|b| st.body(b).is_none()) {
+        return Err(bad(cmd, "`bodies` must list existing bodies"));
+    }
+    let color = match p.get("color") {
+        None | Some(Value::Null) => None,
+        Some(v) => Some(color_param(v).ok_or_else(|| bad(cmd, "`color` must be \"#rrggbb\" or [r, g, b] with values 0–255"))?),
+    };
+    for b in &bodies {
+        match color {
+            Some(c) => s.doc_mut().appearances.insert(b.clone(), c),
+            None => s.doc_mut().appearances.remove(b),
+        };
+    }
+    Ok(json!({"bodies": bodies, "color": color.map(|c| format!("#{:02x}{:02x}{:02x}", c[0], c[1], c[2]))}))
+}
+
 fn material_list(_s: &mut Session, _p: &Value) -> Result<Value> {
     Ok(json!({"materials": solvecraft_doc::MATERIALS.iter().map(|(n, d)| json!({"name": n, "density_g_cm3": d})).collect::<Vec<_>>()}))
 }

crates/engine/src/tests.rs

@@ -951,6 +951,42 @@ fn sample_plate_step_round_trip() {
     }
 }
 
+/// Bodies export in the colour they are shown in: a material's look, an appearance over it,
+/// none for the default; and colours read from a STEP file survive the next export.
+#[test]
+fn material_and_appearance_colours_export_to_step() {
+    let mut s = Session::default();
+    run(&mut s, "PrimitiveBox", json!({"length": 10, "width": 10, "height": 10, "body_name": "BrassBox"}));
+    run(&mut s, "PrimitiveBox", json!({"corner": [20, 0, 0], "length": 10, "width": 10, "height": 10, "body_name": "RedAbs"}));
+    run(&mut s, "PrimitiveBox", json!({"corner": [40, 0, 0], "length": 10, "width": 10, "height": 10, "body_name": "Plain"}));
+    run(&mut s, "PhysicalMaterialCommand", json!({"bodies": ["BrassBox"], "material": "Brass"}));
+    run(&mut s, "PhysicalMaterialCommand", json!({"bodies": ["RedAbs"], "material": "ABS Plastic"}));
+    run(&mut s, "AppearanceCommand", json!({"bodies": ["RedAbs"], "color": "#d01c1c"}));
+    assert!(s.execute("AppearanceCommand", &json!({"bodies": ["RedAbs"], "color": "#12"})).is_err());
+    let rgb = |c: [u8; 3]| c.map(|x| x as f32 / 255.0);
+    let want =
+        [("BrassBox", Some(rgb(solvecraft_doc::material_color("Brass").unwrap()))), ("RedAbs", Some(rgb([0xd0, 0x1c, 0x1c]))), ("Plain", None)];
+    let same = |a: Option<[f32; 3]>, b: Option<[f32; 3]>| match (a, b) {
+        (Some(a), Some(b)) => a.iter().zip(b).all(|(x, y)| (x - y).abs() < 1e-3),
+        (None, None) => true,
+        _ => false,
+    };
+    let check = |imp: &solvecraft_kernel::StepImport| {
+        for (name, c) in want {
+            let b = imp.bodies.iter().find(|b| b.name == name).unwrap_or_else(|| panic!("no body {name}"));
+            assert!(same(b.body.color(), c), "{name}: {:?} vs {c:?}", b.body.color());
+        }
+    };
+    check(&step_round_trip(&mut s, "colours"));
+    // Open the export and export again: the file's colours are kept.
+    let p = std::env::temp_dir().join(format!("solvecraft-colours-{}.step", std::process::id()));
+    run(&mut s, "ExportCommand", json!({"path": p.to_string_lossy()}));
+    let mut s2 = Session::default();
+    run(&mut s2, "doc.open", json!({"path": p.to_string_lossy()}));
+    let _ = std::fs::remove_file(&p);
+    check(&step_round_trip(&mut s2, "colours2"));
+}
+
 /// Components export as a STEP assembly: products, occurrences, placements.
 #[test]
 fn components_export_as_step_assembly() {