Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

50.0 KB
Raw Blame
use crate::{Result, Session, params::bad, render_jobs::job_error};
use serde::Deserialize;
use serde_json::{Value, json};
use solidcraft_doc::render_resources::{CpuHdrEnvironment, GpuHdrEnvironment};
use solidcraft_doc::render_settings::{RenderJob, RenderSetup};
use solidcraft_render::{
    RenderOperation, RenderRequest,
    job::{ImageRequest, Integrator, JobId, RaytraceOptions},
};

#[derive(Default, Deserialize)]
#[serde(default, deny_unknown_fields)]
struct Start {
    aging: solidcraft_doc::render_aging::SavedAgingStack,
    studio_weights: Option<[f64; 3]>,
    progressive: bool,
    denoise: bool,
    samples: Option<u32>,
    max_depth: Option<u32>,
    seed: Option<u32>,
    integrator: Integrator,
    environment: Option<EnvironmentRequest>,
    raytrace: Option<RaytraceOptions>,
    led_strip: Option<solidcraft_render::job::led_strip::LedStripOptions>,
    led_samples: Option<u32>,
    setup: Option<String>,
    settings: Option<RenderSetup>,
    transparent_background: bool,
    replace: bool,
}

#[derive(Deserialize)]
#[serde(default, deny_unknown_fields)]
struct EnvironmentRequest {
    path: String,
    resource: Option<solidcraft_doc::render_resources::HdrId>,
    expected_sha256: Option<solidcraft_doc::render_resources::HdrId>,
    rotation_radians: f64,
    intensity: f64,
    samples: u32,
}
impl Default for EnvironmentRequest {
    fn default() -> Self {
        Self { path: String::new(), resource: None, expected_sha256: None, rotation_radians: 0.0, intensity: 1.0, samples: 16 }
    }
}

#[derive(Default, Deserialize)]
#[serde(default, deny_unknown_fields)]
struct ProgressiveStart {
    caustics: Option<solidcraft_render::job::CausticOptions>,
    studio_weights: Option<[f64; 3]>,
    aging: solidcraft_doc::render_aging::SavedAgingStack,
    #[serde(default)]
    nested_media: bool,
    volume: Option<solidcraft_render::job::volume::HomogeneousVolume>,
    adaptive: Option<solidcraft_render::job::adaptive::AdaptiveSampling>,
    transmission_samples: Option<u32>,
    finishing: solidcraft_render::job::finishing::Finishing,
    backdrop: Option<solidcraft_render::job::finishing::Backdrop>,
    linear_exr: bool,
    integrator: Integrator,
    setup: Option<String>,
    settings: Option<RenderSetup>,
    transparent_background: bool,
    replace: bool,
    progressive: bool,
    samples: Option<u32>,
    max_depth: Option<u32>,
    seed: Option<u32>,
    raytrace: super::transmission::Raytrace,
    lens: Option<solidcraft_render::job::ThinLens>,
    lighting: Option<solidcraft_render::job::StudioLighting>,
    tone_map: Option<solidcraft_render::job::ToneMap>,
    environment: Option<super::environment::Input>,
    denoise: bool,
}

pub(crate) struct Prepared {
    pub(crate) replace: bool,
    pub(crate) submission: Option<solidcraft_render::job::PreparedSubmission>,
    pub(crate) reply: Value,
}

fn lower_led(input: &mut Start, command: &str) -> Result<()> {
    if input.led_strip.is_none() && input.led_samples.is_some() {
        return Err(bad(command, "led_samples requires led_strip"));
    }
    if let Some(strip) = input.led_strip {
        if input.integrator != Integrator::Raytrace {
            return Err(bad(command, "led_strip requires integrator: raytrace"));
        }
        strip.append_to(input.raytrace.get_or_insert_default(), input.led_samples.unwrap_or(16)).map_err(job_error)?;
        input.led_strip = None;
        input.led_samples = None;
    }
    Ok(())
}

#[cfg(test)]
mod union_lowering_tests {
    use super::*;
    #[test]
    fn led_lowering_keeps_hdr_reflection_aa_and_anisotropy_inputs_without_reading_hdr() {
        let wire = json!({"integrator":"raytrace","environment":{"path":"unopened.hdr","rotation_radians":0.75,"intensity":2,"samples":64},"raytrace":{"primary_samples":4,"reflections":{"bodies":[{"body":"receiver","mode":"rough_specular"}],"samples":16,"max_bounces":3},"anisotropic_faces":[{"body_index":0,"body_name":"receiver","face":0,"tangent":[1,0,0],"orientation":"quarter_turn","roughness_x":0.2,"roughness_y":0.5},null],"punctual_lights":[{"position_mm":[0,0,20],"color":[1,1,1],"intensity":1,"reference_distance_mm":20,"minimum_distance_mm":0.001}]},"led_strip":{"center_mm":[0,0,10],"length_mm":8,"width_mm":0.5,"length_axis":[1,0,0],"width_axis":[0,-1,0],"color":[1,0.5,0.25],"intensity":2},"led_samples":64});
        let mut input: Start = serde_json::from_value(wire.clone()).unwrap();
        let before = input.raytrace.clone().unwrap();
        lower_led(&mut input, "render.preflight").unwrap();
        let after = input.raytrace.unwrap();
        assert_eq!(before.primary_samples, after.primary_samples);
        assert_eq!(before.reflections, after.reflections);
        assert_eq!(before.anisotropic_faces, after.anisotropic_faces);
        assert_eq!(before.punctual_lights, after.punctual_lights);
        assert_eq!(after.area_lights.as_ref().unwrap().len(), 1);
        assert_eq!(after.area_samples, Some(64));
        let environment = input.environment.unwrap();
        assert_eq!(environment.path, "unopened.hdr");
        assert_eq!(environment.rotation_radians, 0.75);
        assert_eq!(environment.intensity, 2.0);
        assert_eq!(environment.samples, 64);
        assert!(input.led_strip.is_none() && input.led_samples.is_none());
        assert_eq!(wire["environment"]["path"], json!("unopened.hdr"));
    }
}

/// Resolve portable intent before choosing an executor. Legacy requests are left intact;
/// complete saved jobs cannot be silently overridden by a second set of runtime controls.
enum SavedHdr {
    Cpu(CpuHdrEnvironment),
    Gpu(GpuHdrEnvironment),
}

struct Normalized {
    params: Value,
    hdr: Option<SavedHdr>,
    surfaces: solidcraft_doc::render_surface::SurfaceBindings,
    optics: solidcraft_doc::render_optics::OpticalBindings,
}

fn normalize_saved_job(s: &Session, params: &Value, command: &str) -> Result<Option<Normalized>> {
    let Some(object) = params.as_object() else {
        return Ok(None);
    };
    let named = object.get("setup").filter(|value| !value.is_null());
    let inline = object.get("settings").filter(|value| !value.is_null());
    if named.is_some() && inline.is_some() {
        return Err(bad(command, "choose either setup or settings"));
    }
    let mut settings = if let Some(value) = inline {
        if value.get("job").is_none_or(Value::is_null) {
            return Ok(None);
        }
        serde_json::from_value::<RenderSetup>(value.clone()).map_err(|e| bad(command, e.to_string()))?
    } else if let Some(settings) = named.and_then(Value::as_str).and_then(|name| s.doc.render.setups.get(name)) {
        if settings.job.is_none() {
            return Ok(None);
        }
        settings.clone()
    } else {
        return Ok(None);
    };
    if let Some(key) = object.keys().find(|key| !matches!(key.as_str(), "setup" | "settings" | "replace" | "studio_weights")) {
        return Err(bad(
            command,
            format!(
                "saved job already defines the active method and its options; runtime `{key}` cannot override it (use job: null for a runtime request)"
            ),
        ));
    }
    settings.validate().map_err(|e| bad(command, e.to_string()))?;
    s.doc.render.validate_resources(&settings).map_err(|e| bad(command, e.to_string()))?;
    let Some(job) = settings.job.take() else {
        return Ok(None);
    };
    let optics = std::mem::take(&mut settings.optics);
    let surfaces = std::mem::take(&mut settings.surfaces);
    let mut hdr = None;
    let mut lowered = match job {
        RenderJob::Raster { transparent_background } => json!({"transparent_background":transparent_background}),
        RenderJob::CpuRaytrace { mut options, transparent_background } => {
            hdr = options.hdr.map(SavedHdr::Cpu);
            let aging = std::mem::take(&mut options.aging);
            let raytrace = options.to_runtime(settings.exposure_ev).map_err(|e| bad(command, e.to_string()))?;
            // The legacy CPU path reads EV from RaytraceOptions. There is one saved authority.
            settings.exposure_ev = 0.0;
            json!({"integrator":"raytrace","raytrace":raytrace,"aging":aging,"transparent_background":transparent_background})
        }
        RenderJob::GpuPath { transparent_background, options } => {
            hdr = options.hdr.map(SavedHdr::Gpu);
            json!({
            "progressive":true,
            "transparent_background":transparent_background,
            "samples":options.samples,"max_depth":options.max_depth,"seed":options.seed,
            "lens":options.lens,"lighting":options.lighting,"tone_map":options.tone_map,
            "denoise":options.denoise,"environment":options.environment,
            "finishing":options.finishing,"backdrop":options.backdrop,"linear_exr":options.linear_exr,
            "caustics":options.caustics,"adaptive":options.adaptive,"transmission_samples":options.transmission_samples,"volume":options.volume,"nested_media":options.nested_media,"aging":options.aging
            })
        }
    };
    lowered["settings"] = serde_json::to_value(settings).map_err(|e| bad(command, e.to_string()))?;
    if let Some(weights) = object.get("studio_weights") {
        lowered["studio_weights"] = weights.clone();
    }
    if let Some(replace) = object.get("replace") {
        lowered["replace"] = replace.clone();
    }
    Ok(Some(Normalized { params: lowered, hdr, surfaces, optics }))
}

pub(crate) fn prepare(s: &Session, params: &Value, command: &str, cancel: &solidcraft_render::job::CancelToken) -> Result<Prepared> {
    prepare_with_metadata(s, params, command, cancel, None)
}
pub(crate) fn prepare_with_metadata(
    s: &Session,
    params: &Value,
    command: &str,
    cancel: &solidcraft_render::job::CancelToken,
    retained: Option<&solidcraft_render::job::RetainedMetadata>,
) -> Result<Prepared> {
    cancel.check().map_err(job_error)?;
    let normalized = normalize_saved_job(s, params, command)?;
    let saved_hdr = normalized.as_ref().and_then(|normalized| normalized.hdr.as_ref());
    let params = normalized.as_ref().map_or(params, |normalized| &normalized.params);
    if params.get("progressive").and_then(Value::as_bool) == Some(true) {
        let hdr = match saved_hdr {
            Some(SavedHdr::Gpu(hdr)) => Some(*hdr),
            Some(SavedHdr::Cpu(_)) => {
                return Err(bad(command, "saved CPU HDR cannot enter a GPU request"));
            }
            None => None,
        };
        return prepare_progressive(
            s,
            params,
            command,
            normalized.is_some(),
            hdr,
            normalized.as_ref().map(|n| &n.surfaces),
            normalized.as_ref().map(|n| &n.optics),
            cancel,
            retained,
        );
    }
    let gpu_raytrace =
        params.get("raytrace").and_then(Value::as_object).is_some_and(|o| ["clear_coats", "textures"].iter().any(|key| o.contains_key(*key)));
    if gpu_raytrace
        || params.get("environment").is_some_and(|e| e.get("kind").is_some())
        || ["lens", "lighting", "tone_map"].iter().any(|key| params.get(*key).is_some())
        || params.get("denoise").is_some_and(|value| value != &json!(false))
    {
        return Err(bad(
            command,
            "runtime GPU transmission, texture, lens, environment, lighting, tone-map and denoise controls require progressive rendering",
        ));
    }
    let mut input: Start = serde_json::from_value(params.clone()).map_err(|e| bad(command, e.to_string()))?;
    let coats = input.settings.as_mut().map_or_else(Default::default, |settings| std::mem::take(&mut settings.coats));
    // A checked file HDR uses the runtime request lane, but its optical targets
    // remain stable authored identities. Extract them before validating job:null
    // settings, just as for stable coats; never discard or turn them into ordinals
    // in the UI. Exact visible identities are resolved from the captured scene.
    let inline_optics = input.settings.as_mut().map_or_else(Default::default, |settings| std::mem::take(&mut settings.optics));
    let normalized_optics = normalized.as_ref().map(|n| &n.optics).filter(|bindings| !bindings.is_empty());
    if normalized_optics.is_some() && !inline_optics.is_empty() {
        return Err(bad(command, "choose normalized or inline stable optics, not both"));
    }
    let saved_optics = normalized_optics.or((!inline_optics.is_empty()).then_some(&inline_optics));
    if let Some(bindings) = saved_optics {
        if input.integrator != Integrator::Raytrace {
            return Err(bad(command, "stable optics require CPU or GPU ray tracing"));
        }
        let options = input.raytrace.get_or_insert_default();
        bindings.validate_for_cpu_path(options.path.is_some()).map_err(|e| bad(command, e.to_string()))?;
        if options.volume.is_some_and(|volume| volume.active()) {
            return Err(bad(command, "CPU Atmosphere cannot combine with saved Glass or subsurface scattering; settings are kept"));
        }
        if options.denoise && bindings.iter().any(|binding| binding.optics.subsurface.is_some_and(|scatter| scatter.active())) {
            return Err(bad(command, "CPU subsurface random walks have no surface-denoiser guides; disable denoising explicitly"));
        }
        if !options.dielectrics.is_empty() {
            return Err(bad(command, "saved optics cannot combine with runtime dielectric overrides"));
        }
    }
    if !coats.is_empty() && input.integrator != Integrator::Raytrace {
        return Err(bad(command, "stable clear coats require CPU or GPU ray tracing"));
    }
    validate_studio_weights(input.studio_weights, command)?;
    if input.integrator == Integrator::Raytrace && input.studio_weights.is_some() {
        return Err(bad(command, "studio_weights apply to raster or the implicit GPU studio; use explicit CPU light intensities"));
    }
    if input.progressive {
        return prepare_progressive(s, params, command, false, None, None, None, cancel, retained);
    }
    if input.denoise {
        return Err(bad(command, "denoise requires GPU progressive rendering"));
    }
    if input.samples.is_some() || input.max_depth.is_some() || input.seed.is_some() {
        return Err(bad(command, "sampling controls require progressive rendering"));
    }
    if input.setup.is_some() && input.settings.is_some() {
        return Err(bad(command, "choose either setup or settings"));
    }
    // Reject unavailable execution before capturing authoritative product meshes.
    // Runtime services are independent of the document and can be checked cold.
    let host = s.render_job_host().ok_or_else(|| bad(command, "no image host is installed"))?;
    if !host.is_available() {
        return Err(bad(command, "image host is unavailable"));
    }
    host.validate_integrator(input.integrator).map_err(job_error)?;
    lower_led(&mut input, command)?;
    if !input.aging.is_empty() {
        if input.integrator != Integrator::Raytrace {
            return Err(bad(command, "stable CPU aging requires the CPU raytrace integrator"));
        }
        input.aging.validate().map_err(|e| bad(command, e.to_string()))?;
        input.raytrace.get_or_insert_with(RaytraceOptions::default);
    }
    let saved_surfaces = normalized.as_ref().map(|n| &n.surfaces).filter(|bindings| !bindings.is_empty());
    if saved_surfaces.is_some() {
        if input.integrator != Integrator::Raytrace {
            return Err(bad(command, "saved opaque surfaces require CPU or GPU ray tracing"));
        }
        solidcraft_render::job::textures::validate_cpu_options(input.raytrace.as_ref().unwrap_or(&RaytraceOptions::default())).map_err(job_error)?;
        if normalized.as_ref().is_some_and(|n| !n.optics.is_empty()) && input.raytrace.as_ref().is_none_or(|options| options.path.is_none()) {
            return Err(bad(command, "CPU maps with Glass require Indirect lighting and separate targets"));
        }
    }
    if input.integrator == Integrator::Raster && input.raytrace.is_some() {
        return Err(bad(command, "raytrace options require integrator: raytrace"));
    }
    if let Some(options) = &input.raytrace {
        options.retained_bytes().map_err(job_error)?;
        if !input.aging.is_empty() {
            if options.aging.as_ref().is_some_and(|stack| !stack.is_empty()) {
                return Err(bad(command, "choose stable authored aging or captured runtime aging, not both"));
            }
            if input.aging.iter().any(|layer| layer.active()) && options.anisotropic_faces.iter().any(Option::is_some) {
                return Err(bad(command, "CPU aging cannot replace independently authored anisotropic roughness axes"));
            }
        }
        options.budget.validate_execution().map_err(job_error)?;
        // Check the complete image envelope before any source file is read.
        let dimensions = if let Some(name) = &input.setup {
            let settings = s.doc.render.setups.get(name).ok_or_else(|| bad(command, "no saved render setup with that name"))?;
            (settings.width, settings.height)
        } else if let Some(settings) = &input.settings {
            (settings.width, settings.height)
        } else {
            let defaults = RenderSetup::default();
            (defaults.width, defaults.height)
        };
        options.budget.validate_image(dimensions.0, dimensions.1, options.camera_sampling().map_err(job_error)?).map_err(job_error)?;
        if let Some(lens) = options.lens {
            let camera = input
                .setup
                .as_ref()
                .and_then(|name| s.doc.render.setups.get(name))
                .map(|setup| setup.camera)
                .or_else(|| input.settings.as_ref().map(|setup| setup.camera))
                .or(s.camera)
                .unwrap_or_default();
            lens.validate_camera(&camera).map_err(job_error)?;
        }
        if let Some(output) = &options.output {
            output.validate_image(dimensions.0, dimensions.1).map_err(job_error)?;
            output.presentation(options.exposure_ev, [0; 3], input.transparent_background).validate().map_err(job_error)?;
        }
    }
    // Refuse conflicting sources before VFS/resource access. Sky is a direct
    // radiance consumer and never a substitute for unread HDR bytes.
    if (saved_hdr.is_some() || input.environment.is_some())
        && input.raytrace.as_ref().is_some_and(|options| options.sky.is_some() || options.environment.is_some())
    {
        return Err(bad(command, "choose either CPU HDR input, gradient Sky or constant environment"));
    }
    let environment = if let Some(saved_hdr) = saved_hdr {
        let SavedHdr::Cpu(hdr) = saved_hdr else {
            return Err(bad(command, "saved GPU HDR cannot enter a CPU request"));
        };
        if input.integrator != Integrator::Raytrace || input.environment.is_some() {
            return Err(bad(command, "saved CPU HDR requires raytrace without a runtime environment override"));
        }
        let resource = s.doc.render.resources.required(&hdr.resource).map_err(|e| bad(command, e.to_string()))?;
        Some(
            solidcraft_render::lighting::environment_input::EnvironmentInput::new(resource.source(), hdr.rotation_rad, hdr.intensity, hdr.samples)
                .map_err(|e| bad(command, e.to_string()))?,
        )
    } else if let Some(environment) = &input.environment {
        if input.integrator != Integrator::Raytrace {
            return Err(bad(command, "environment requires raytrace"));
        }
        let source = if let Some(id) = environment.resource {
            if !environment.path.is_empty() || environment.expected_sha256.is_some() {
                return Err(bad(command, "choose an embedded HDR resource or a file path with optional expected_sha256"));
            }
            s.doc.render.resources.required(&id).map_err(|e| bad(command, e.to_string()))?.source()
        } else {
            if environment.path.is_empty()
                || environment.path.len() > 4096
                || environment.path.capacity() > 4096
                || environment.path.chars().any(char::is_control)
            {
                return Err(bad(command, "environment requires a bounded HDR input path"));
            }
            let bytes =
                solidcraft_io::vfs::read(&environment.path, solidcraft_render::lighting::MAX_HDR_BYTES).map_err(|e| bad(command, e.to_string()))?;
            if environment.expected_sha256.is_some_and(|id| id != solidcraft_doc::render_resources::HdrId::of(&bytes)) {
                return Err(bad(command, "HDR file changed since selection; inspect and select it again"));
            }
            solidcraft_render::lighting::HdrSource::new(bytes).map_err(|e| bad(command, e.to_string()))?
        };
        Some(
            solidcraft_render::lighting::environment_input::EnvironmentInput::new(
                source,
                environment.rotation_radians,
                environment.intensity,
                environment.samples,
            )
            .map_err(|e| bad(command, e.to_string()))?,
        )
    } else {
        None
    };
    let mut scene = crate::product_scene::extract(s)?;
    if let Some(bindings) = saved_optics {
        let options = input.raytrace.as_mut().ok_or_else(|| bad(command, "saved CPU optics require a CPU raytrace request"))?;
        if !options.dielectrics.is_empty() {
            return Err(bad(command, "saved optics cannot combine with runtime dielectric overrides"));
        }
        options.dielectrics = super::optical_bindings::resolve_cpu_path(s, &scene, bindings, options.path.is_some(), command)?;
        options.validate().map_err(job_error)?;
    }
    super::coat_bindings::apply(s, &mut scene, &coats, input.raytrace.as_ref(), command)?;
    if !input.aging.is_empty() {
        let options = input.raytrace.as_mut().ok_or_else(|| bad(command, "CPU aging requires a CPU raytrace request"))?;
        if options.aging.as_ref().is_some_and(|stack| !stack.is_empty()) {
            return Err(bad(command, "choose stable authored aging or captured runtime aging, not both"));
        }
        options.aging = Some(Box::new(super::effects::resolve_aging(s, &scene, &input.aging, command)?));
        options.validate().map_err(job_error)?;
    }
    if environment.is_some() {
        input.raytrace.as_ref().unwrap_or(&RaytraceOptions::default()).validate_environment_reflections(&scene).map_err(job_error)?;
    }
    let settings = if let Some(name) = &input.setup {
        s.doc.render.setups.get(name).cloned().ok_or_else(|| bad(command, "no saved render setup with that name"))?
    } else if let Some(settings) = &input.settings {
        settings.clone()
    } else {
        let mut settings = RenderSetup::default();
        if let Some(camera) = s.camera {
            settings.camera = camera;
        } else {
            settings.camera.fit(&scene.bounds);
        }
        settings
    };
    if input.integrator == Integrator::Raster && !settings.stage.is_empty() {
        return Err(bad(command, "passive stages require a raytrace executor"));
    }
    super::staging::apply(&mut scene, &settings, command)?;
    let budget = input.raytrace.as_ref().map_or(solidcraft_render::job::CpuBudget::Compact, |o| o.budget);
    if input.integrator == Integrator::Raytrace {
        settings.validate_for_cpu(budget).map_err(|e| bad(command, e.to_string()))?;
        budget.validate_execution().map_err(job_error)?;
        budget
            .validate_image(
                settings.width,
                settings.height,
                input.raytrace.as_ref().map(|o| o.camera_sampling()).transpose().map_err(job_error)?.flatten(),
            )
            .map_err(job_error)?;
    } else {
        settings.validate().map_err(|e| bad(command, e.to_string()))?;
    }
    // The raster image executor has no exposure or environment controls. A setup saved with them
    // (the render workspace and the other executors use them) still renders here, and the reply
    // names what this render leaves out (#5089). The raytrace path takes them only through a
    // saved job, so a raytrace request with them is still refused.
    let ignored = if input.integrator == Integrator::Raster { ignored_controls(&settings) } else { Vec::new() };
    if input.integrator != Integrator::Raster
        && (settings.exposure_ev != 0.0 || settings.environment_rotation != 0.0 || settings.environment_intensity != 1.0)
    {
        return Err(bad(command, "exposure and environment controls are not supported by the R4a CPU image executor"));
    }
    let mut descriptor = host.descriptor_for(input.integrator).map_err(job_error)?;
    if input.integrator == Integrator::Raytrace {
        descriptor.limits = budget.image_limits(input.raytrace.as_ref().is_some_and(|o| o.progressive.is_some()));
    }
    let expected_executor = descriptor.id.clone();
    let mut backend = s.render_backend();
    backend.executors = vec![descriptor];
    let mut features = scene.required_features();
    if environment.is_some() {
        features.push(solidcraft_render::RenderFeature::Hdri);
    }
    let refraction = input.raytrace.as_ref().is_some_and(|options| !options.dielectrics.is_empty());
    if refraction && !features.contains(&solidcraft_render::RenderFeature::Refraction) {
        features.push(solidcraft_render::RenderFeature::Refraction);
    }
    let environment_info = environment.as_ref().map(|e| e.metadata());
    let resolved = solidcraft_render::resolve_request(
        &[backend],
        &RenderRequest {
            backend: Some(settings.backend.clone()),
            mode: settings.mode,
            operation: RenderOperation::Image,
            width: u64::from(settings.width),
            height: u64::from(settings.height),
            format: Some(settings.format),
            features,
            policy: Default::default(),
        },
    )
    .map_err(|e| bad(command, e.to_string()))?;
    if resolved.executor != expected_executor {
        return Err(bad(command, "resolved executor is not installed as an image job host"));
    }
    let textures = if let Some(bindings) = saved_surfaces {
        let overrides = super::surface_bindings::resolve(s, &scene, bindings, command)?;
        super::textures::capture_with_resources(&scene, &overrides, Some(&s.doc.render.texture_resources), command)?
    } else {
        None
    };
    let request = ImageRequest {
        studio_weights: validate_studio_weights(input.studio_weights, command)?,
        environment: None,
        textures,
        integrator: input.integrator,
        raytrace: input.raytrace.take(),
        camera: settings.camera,
        width: settings.width,
        height: settings.height,
        background: settings.background,
        transparent_background: input.transparent_background,
    };
    let environment_bytes = environment.as_ref().map_or(Ok(0), |e| e.required_bytes()).map_err(|e| bad(command, e.to_string()))?;
    let submission =
        host.prepare_submission_with_metadata(scene, request, Default::default(), environment, cancel.clone(), retained).map_err(job_error)?;
    let request = submission.request();
    let mut admission = submission.admission();
    let retained_lights = request.raytrace.as_ref().map_or(Ok(0), |o| o.retained_bytes()).map_err(job_error)?;
    let retained_environment =
        if environment_info.is_some() { std::mem::size_of::<solidcraft_render::lighting::environment_input::EnvironmentInfo>() as u64 } else { 0 };
    let retained_request_bytes = retained_lights
        .checked_add(retained_environment)
        .and_then(|bytes| bytes.checked_add(request.retained_resource_metadata_bytes()))
        .ok_or_else(|| bad(command, "request metadata overflow"))?;

    admission.estimated_total_bytes = admission
        .estimated_total_bytes
        .checked_add(environment_bytes)
        .and_then(|v| v.checked_add(retained_request_bytes))
        .filter(|v| *v <= budget.limits().max_job_bytes)
        .ok_or_else(|| bad(command, "environment job exceeds per-job memory limit"))?;
    admission.preparation_bytes =
        admission.preparation_bytes.checked_add(environment_bytes).ok_or_else(|| bad(command, "environment admission overflow"))?;
    let transparency = match input.integrator {
        Integrator::Raster => "sorted_alpha_approximation",
        Integrator::Raytrace if refraction => "physical_transmission",
        Integrator::Raytrace if input.transparent_background => "coverage_alpha",
        Integrator::Raytrace => "opaque_only",
    };
    let path = request.raytrace.as_ref().is_some_and(|options| options.path.is_some());
    let stage_transport = if path && refraction {
        "CPU finite-depth diffuse/specular and dielectric path lighting"
    } else if path {
        "CPU finite-depth opaque diffuse/specular path lighting"
    } else {
        "CPU direct/specular only; no diffuse interreflection"
    };
    let dielectric_boundaries = match (refraction, path) {
        (true, true) => vec!["thin_sheet", "closed_box", "closed_mesh"],
        (true, false) => vec!["thin_sheet", "closed_box"],
        (false, _) => Vec::new(),
    };
    let mut reply = json!({"ignored_controls":ignored,"stage_panels":settings.stage.len(),"stage_transport":stage_transport, "cpu_budget":budget,"cpu_limits":budget.limits(),"environment":environment_info,"textures":request.textures.as_ref().map(|maps|maps.summary()),"retained_request_bytes":retained_request_bytes,"resolved":resolved,"admission":admission,"request":request,"scene_generation":s.revision,"host":host.kind(),"transparency":transparency,"refraction":refraction,"dielectric_boundaries":dielectric_boundaries});
    if !coats.is_empty() {
        reply["coats"] = json!(coats);
    }
    if request.raytrace.as_ref().is_some_and(|options| options.denoise) {
        reply["denoising"] = json!({
            "method":"edge_aware_atrous", "backend":"native_cpu", "passes":3, "steps":[1,2,4],
            "guides":"deterministic_center_ray_albedo_normal_camera_relative_position_depth",
            "bypass":"glass, sharp CPU mirror overrides, smooth metal/coat, emitter, background and partial coverage first hits",
            "limitation":"biased spatial filter; first-hit guides do not reconstruct reflection/refraction or depth-of-field correspondences",
            "raw_linear_accumulator_preserved":true,"raw_linear_exr_preserved":true,
            "output_stage":"linear_before_tone_map", "work_units":"one pixel visit per pass, each with at most 25 taps",
            "checkpoints":"every complete published pass uses the same filter"
        });
    }
    Ok(Prepared { replace: input.replace, submission: Some(submission), reply })
}

fn prepare_progressive(
    s: &Session,
    params: &Value,
    command: &str,
    require_gpu_path: bool,
    saved_hdr: Option<GpuHdrEnvironment>,
    saved_surfaces: Option<&solidcraft_doc::render_surface::SurfaceBindings>,
    saved_optics: Option<&solidcraft_doc::render_optics::OpticalBindings>,
    cancel: &solidcraft_render::job::CancelToken,
    retained: Option<&solidcraft_render::job::RetainedMetadata>,
) -> Result<Prepared> {
    let cpu_raytrace = params
        .get("raytrace")
        .and_then(Value::as_object)
        .is_some_and(|o| o.keys().any(|key| !matches!(key.as_str(), "dielectrics" | "clear_coats" | "textures")));
    if params.get("integrator").is_some_and(|v| v.as_str() != Some("raster"))
        || cpu_raytrace
        || params.get("led_strip").is_some()
        || params.get("led_samples").is_some()
        || params.get("environment").is_some_and(|e| e.is_object() && e.get("kind").is_none())
    {
        return Err(bad(command, "progressive rendering does not accept CPU raytrace, environment or LED options"));
    }
    let mut input: ProgressiveStart = serde_json::from_value(params.clone()).map_err(|e| bad(command, e.to_string()))?;
    let coats = input.settings.as_mut().map_or_else(Default::default, |settings| std::mem::take(&mut settings.coats));
    let inline_optics = input.settings.as_mut().map_or_else(Default::default, |settings| std::mem::take(&mut settings.optics));
    let normalized_optics = saved_optics.filter(|bindings| !bindings.is_empty());
    if normalized_optics.is_some() && !inline_optics.is_empty() {
        return Err(bad(command, "choose normalized or inline stable optics, not both"));
    }
    let saved_optics = normalized_optics.or((!inline_optics.is_empty()).then_some(&inline_optics));
    if let Some(bindings) = saved_optics {
        bindings.validate().map_err(|e| bad(command, e.to_string()))?;
        if !input.raytrace.dielectrics.is_empty() || !input.raytrace.clear_coats.is_empty() {
            return Err(bad(command, "saved optical bindings cannot be mixed with transient optical overrides"));
        }
    }
    validate_studio_weights(input.studio_weights, command)?;
    if input.studio_weights.is_some() && (input.lighting.is_some() || input.environment.is_some() || saved_hdr.is_some()) {
        return Err(bad(command, "studio_weights require the implicit GPU studio without environment lighting"));
    }
    if input.integrator != Integrator::Raster || !input.progressive {
        return Err(bad(command, "progressive rendering requires the registered GPU request method"));
    }
    if input.setup.is_some() && input.settings.is_some() {
        return Err(bad(command, "choose either setup or settings"));
    }
    let mut scene = crate::product_scene::extract(s)?;
    if !input.progressive
        && (!input.raytrace.dielectrics.is_empty()
            || !input.raytrace.clear_coats.is_empty()
            || !input.raytrace.textures.is_empty()
            || input.lens.is_some()
            || input.lighting.is_some()
            || input.tone_map.is_some()
            || input.environment.is_some()
            || input.denoise)
    {
        return Err(bad(
            command,
            "runtime transmission, clear-coat, texture, lens, environment, lighting, tone-map and denoise controls require progressive rendering",
        ));
    }
    if let Some(bindings) = saved_surfaces.filter(|bindings| !bindings.is_empty()) {
        if !input.raytrace.textures.is_empty() {
            return Err(bad(command, "saved surfaces cannot be combined with runtime texture overrides"));
        }
        input.raytrace.textures = super::surface_bindings::resolve(s, &scene, bindings, command)?;
    }
    if let Some(bindings) = saved_optics.filter(|b| !b.is_empty()) {
        if !input.raytrace.dielectrics.is_empty() || !input.raytrace.clear_coats.is_empty() {
            return Err(bad(command, "saved optical bindings cannot be mixed with transient optical overrides"));
        }
        input.raytrace.dielectrics = super::optical_bindings::resolve(s, &scene, bindings, command)?;
    }
    if !coats.is_empty() && !input.raytrace.clear_coats.is_empty() {
        return Err(bad(command, "stable clear coats cannot combine with runtime clear-coat overrides"));
    }
    super::transmission::apply(&mut scene, &input.raytrace.dielectrics, command)?;
    super::coat_bindings::apply(s, &mut scene, &coats, None, command)?;
    super::clear_coat::apply(&mut scene, &input.raytrace.clear_coats, command)?;
    let settings = if let Some(name) = &input.setup {
        s.doc.render.setups.get(name).cloned().ok_or_else(|| bad(command, "no saved render setup with that name"))?
    } else if let Some(settings) = &input.settings {
        settings.clone()
    } else {
        let mut settings = RenderSetup::default();
        if let Some(camera) = s.camera {
            settings.camera = camera;
        } else {
            settings.camera.fit(&scene.bounds);
        }
        settings
    };
    settings.validate_for_gpu().map_err(|e| bad(command, e.to_string()))?;
    if settings.environment_rotation != 0.0 || settings.environment_intensity != 1.0 {
        return Err(bad(command, "environment controls are not supported by the installed image executors"));
    }
    if !input.progressive && (input.samples.is_some() || input.max_depth.is_some() || input.seed.is_some() || settings.exposure_ev != 0.0) {
        return Err(bad(command, "sampling and exposure controls require progressive rendering"));
    }
    super::staging::apply(&mut scene, &settings, command)?;
    let mut options = solidcraft_render::job::JobOptions::default();
    if let Some(samples) = input.samples {
        options.samples = samples;
    }
    if let Some(depth) = input.max_depth {
        options.max_depth = depth;
    }
    if let Some(seed) = input.seed {
        options.seed = seed;
    }
    options.exposure_ev = settings.exposure_ev;
    options.lens = input.lens;
    options.lighting = input.lighting;
    options.tone_map = input.tone_map.unwrap_or_default();
    options.denoise = input.denoise;
    options.finishing = input.finishing;
    options.backdrop = input.backdrop;
    options.linear_exr = input.linear_exr;
    options.aging = super::effects::resolve_aging(s, &scene, &input.aging, command)?;
    options.nested_media = input.nested_media;
    options.volume = input.volume;
    options.caustics = input.caustics;
    options.adaptive = input.adaptive;
    options.transmission_samples = input.transmission_samples.unwrap_or(1);
    options.validate().map_err(job_error)?;
    if let Some(super::environment::Input::BuiltinHdr { id, .. }) = &input.environment
        && options.lighting.as_ref().is_some_and(|lighting| lighting.sun.is_some())
        && super::library::owns_sun(id, command)?
    {
        return Err(bad(command, "built-in HDR and analytic lighting cannot both own the sun"));
    }
    let environment = if let Some(hdr) = saved_hdr {
        if input.environment.is_some() {
            return Err(bad(command, "saved GPU HDR cannot have a runtime environment override"));
        }
        let resource = s.doc.render.resources.required(&hdr.resource).map_err(|e| bad(command, e.to_string()))?;
        Some(std::sync::Arc::new(
            solidcraft_render::lighting::environment::EnvironmentSource::from_hdr(
                resource.source(),
                hdr.rotation_rad,
                hdr.intensity,
                hdr.assume_linear_srgb,
            )
            .map_err(|e| bad(command, e.to_string()))?,
        ))
    } else {
        input.environment.as_ref().map(|source| source.capture(&s.doc.render.resources, command)).transpose()?
    };
    let mut features = scene.required_features();
    if environment.is_some() {
        features.push(solidcraft_render::RenderFeature::Hdri);
    }
    if input.progressive {
        features.push(solidcraft_render::RenderFeature::Progressive);
        if scene.has_transmission() {
            features.push(solidcraft_render::RenderFeature::Refraction);
        }
    }
    let mut backend = s.render_backend();
    if require_gpu_path {
        backend.executors.retain(|executor| executor.id.as_str() == "gpu-path");
        if backend.executors.is_empty() {
            return Err(bad(command, "saved gpu_path method requires an installed gpu-path executor"));
        }
    }
    let resolved = solidcraft_render::resolve_request(
        &[backend],
        &RenderRequest {
            backend: Some(settings.backend.clone()),
            mode: settings.mode,
            operation: RenderOperation::Image,
            width: u64::from(settings.width),
            height: u64::from(settings.height),
            format: Some(settings.format),
            features,
            policy: Default::default(),
        },
    )
    .map_err(|e| bad(command, e.to_string()))?;
    if require_gpu_path && resolved.executor.as_str() != "gpu-path" {
        return Err(bad(command, "saved gpu_path method requires the gpu-path executor; another progressive executor cannot substitute for it"));
    }
    if options.denoise && resolved.executor.as_str() != "gpu-path" {
        return Err(bad(command, "denoise requires the native gpu-path executor"));
    }
    let host = s.render_jobs.host_for(&resolved.executor).ok_or_else(|| bad(command, "resolved executor is not installed as an image job host"))?;
    if !host.is_available() {
        return Err(bad(command, "image host is unavailable"));
    }
    let request = ImageRequest {
        studio_weights: validate_studio_weights(input.studio_weights, command)?,
        integrator: Default::default(),
        raytrace: None,
        environment,
        camera: settings.camera,
        width: settings.width,
        height: settings.height,
        background: settings.background,
        transparent_background: input.transparent_background,
        textures: super::textures::capture_with_resources(&scene, &input.raytrace.textures, Some(&s.doc.render.texture_resources), command)?,
    };
    let refraction = input.progressive && scene.has_transmission();
    let submission = host.prepare_submission_with_metadata(scene, request, options, None, cancel.clone(), retained).map_err(job_error)?;
    let request = submission.request();
    let mut admission = submission.admission();
    let retained_options_bytes = options.retained_bytes().map_err(job_error)?;
    admission.estimated_total_bytes = admission
        .estimated_total_bytes
        .checked_add(request.retained_resource_metadata_bytes())
        .and_then(|bytes| bytes.checked_add(retained_options_bytes))
        .filter(|bytes| *bytes <= host.job_limit_bytes())
        .ok_or_else(|| bad(command, "GPU work and retained metadata exceed the per-job limit"))?;
    let reply = json!({"stage_panels":settings.stage.len(),"resolved":resolved,"admission":admission,"request":request,"textures":request.textures.as_ref().map(|resources|resources.summary()),"scene_generation":s.revision,"host":host.kind(),"transparency":if refraction {"physical_transmission"} else if input.transparent_background {"coverage_alpha"} else if input.progressive {"opaque_only"} else {"sorted_alpha_approximation"},"options":options,"retained_options_bytes":retained_options_bytes,"environment":request.environment.as_ref().map(|source|source.info()),"refraction":refraction,"dielectric_boundaries": if resolved.executor.as_str() == "gpu-path" {vec!["thin_sheet","closed_box","closed_mesh"]} else {Vec::<&str>::new()}});
    let mut reply = reply;
    if !coats.is_empty() {
        reply["coats"] = json!(coats);
    }
    if options.denoise {
        reply["denoising"] = json!({
            "method":"edge_aware_atrous", "passes":3, "steps":[1,2,4],
            "guides":"deterministic_center_ray_albedo_normal_position_depth",
            "bypass":"glass, smooth metal/coat, emitter, background and partial coverage first hits",
            "limitation":"first-hit guides do not reconstruct reflection/refraction or depth-of-field correspondences",
            "raw_linear_accumulator_preserved":true, "output_stage":"linear_before_tone_map"
        });
    }
    Ok(Prepared { replace: input.replace, submission: Some(submission), reply })
}

/// The setup's controls the raster image executor doesn't apply: those not at their neutral value.
fn ignored_controls(settings: &RenderSetup) -> Vec<&'static str> {
    let mut ignored = Vec::new();
    if settings.exposure_ev != 0.0 {
        ignored.push("exposure_ev");
    }
    if settings.environment_rotation != 0.0 {
        ignored.push("environment_rotation");
    }
    if settings.environment_intensity != 1.0 {
        ignored.push("environment_intensity");
    }
    ignored
}

pub(super) fn preflight(s: &mut Session, params: &Value) -> Result<Value> {
    prepare(s, params, "render.preflight", &solidcraft_render::job::CancelToken::default()).map(|p| p.reply)
}

pub(super) fn start(s: &mut Session, params: &Value) -> Result<Value> {
    let p = prepare(s, params, "render.start", &solidcraft_render::job::CancelToken::default())?;
    let status = s
        .render_jobs
        .start_prepared(
            s.revision,
            p.submission.ok_or_else(|| bad("render.start", "missing prepared submission"))?,
            p.replace,
            params.get("setup").and_then(Value::as_str).map(str::to_owned),
        )
        .map_err(job_error)?;
    let mut status = json!(status);
    if let (Some(out), Some(ignored)) = (status.as_object_mut(), p.reply.get("ignored_controls")) {
        out.insert("ignored_controls".into(), ignored.clone());
    }
    Ok(status)
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct Regrade {
    job: Option<JobId>,
    presentation: solidcraft_render::job::presentation::Presentation,
}
pub(super) fn regrade(s: &mut Session, params: &Value) -> Result<Value> {
    let input: Regrade = serde_json::from_value(params.clone()).map_err(|e| bad("render.result.regrade", e.to_string()))?;
    input.presentation.validate().map_err(job_error)?;
    let job = result_source(s, input.job, "render.result.regrade")?;
    Ok(json!(s.render_jobs.regrade(job, input.presentation).map_err(job_error)?))
}

fn result_source(s: &mut Session, job: Option<JobId>, command: &str) -> Result<JobId> {
    s.render_jobs.collect().map_err(job_error)?;
    job.or_else(|| s.render_selected_result()).ok_or_else(|| bad(command, "no completed result is selected"))
}

pub(super) fn status(s: &mut Session, params: &Value) -> Result<Value> {
    let input: ResultJob = serde_json::from_value(params.clone()).map_err(|e| bad("render.status", e.to_string()))?;
    s.advance_render_batch()?;
    let Some(job) = input.job else {
        return Ok(json!({"queue":s.render_queue_state()}));
    };
    let mut reply = json!(s.render_jobs.status(job).map_err(job_error)?);
    if let Some(object) = reply.as_object_mut() {
        object.insert("queue".into(), json!(s.render_queue_state()));
    }
    Ok(reply)
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct Pin {
    job: Option<JobId>,
}
pub(super) fn pin(s: &mut Session, params: &Value) -> Result<Value> {
    let input: Pin = serde_json::from_value(params.clone()).map_err(|e| bad("render.result.pin", e.to_string()))?;
    let job = if params.get("job").is_some_and(Value::is_null) { None } else { Some(result_source(s, input.job, "render.result.pin")?) };
    Ok(json!({"frame":s.render_jobs.pin(job).map_err(job_error)?}))
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct ResultJob {
    job: Option<JobId>,
}

pub(super) fn copy(s: &mut Session, params: &Value) -> Result<Value> {
    let input: ResultJob = serde_json::from_value(params.clone()).map_err(|e| bad("render.result.copy", e.to_string()))?;
    let job = result_source(s, input.job, "render.result.copy")?;
    let frame = s
        .render_jobs
        .handle(job)
        .map_err(job_error)?
        .frame()
        .map_err(job_error)?
        .ok_or_else(|| bad("render.result.copy", "render has no completed image"))?;
    let size = (u64::from(frame.info.width), u64::from(frame.info.height));
    if solidcraft_render::RenderLimits::default().fit(size.0, size.1, None) != Some(size) {
        return Err(bad("render.result.copy", "clipboard image exceeds 4096 per side or 4194304 pixels; export the PNG instead"));
    }
    Ok(json!({"frame":frame.info}))
}

pub(crate) fn cancel_params(params: &Value) -> Result<Option<JobId>> {
    let empty = Value::Object(Default::default());
    let params = if params.is_null() { &empty } else { params };
    let input: ResultJob = serde_json::from_value(params.clone()).map_err(|e| bad("render.cancel", e.to_string()))?;
    Ok(input.job)
}
pub(super) fn cancel(s: &mut Session, params: &Value) -> Result<Value> {
    let requested = cancel_params(params)?;
    if requested.is_none() && s.cancel_native_preparation() {
        return Ok(json!({"preparing":true,"cancel_requested":true,"queue":s.render_queue_state()}));
    }
    let job = requested.or(s.render_queue_state().job).ok_or_else(|| bad("render.cancel", "job is required without an active shot queue"))?;
    let status = s.render_jobs.status(job).map_err(job_error)?;
    s.cancel_render_batch(job);
    if status.progress.phase.terminal() {
        return Ok(json!(status));
    }
    Ok(json!(s.render_jobs.handle(job).map_err(job_error)?.cancel().map_err(job_error)?))
}

#[derive(Clone, Copy, Debug, Default, PartialEq, Deserialize)]
#[serde(rename_all = "snake_case")]
enum ExportFormat {
    #[default]
    Png,
    Exr,
}
impl ExportFormat {
    fn extension(self) -> &'static str {
        match self {
            Self::Png => "png",
            Self::Exr => "exr",
        }
    }
}
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct Export {
    #[serde(default)]
    format: ExportFormat,
    job: Option<JobId>,
    path: String,
    #[serde(default)]
    overwrite: bool,
}

pub(super) fn export(s: &mut Session, params: &Value) -> Result<Value> {
    let input: Export = serde_json::from_value(params.clone()).map_err(|e| bad("render.export", e.to_string()))?;
    let path = std::path::Path::new(&input.path);
    if input.path.len() > 4096
        || input.path.chars().any(char::is_control)
        || !path.extension().is_some_and(|x| x.eq_ignore_ascii_case(input.format.extension()))
    {
        return Err(bad("render.export", "a bounded destination with the explicitly selected png/exr extension is required"));
    }
    // Atomic native writers are also used for the app's own files and do not
    // apply a request's path scope. Check the caller's destination explicitly.
    solidcraft_io::vfs::check(&input.path).map_err(|e| bad("render.export", e.to_string()))?;
    let job = result_source(s, input.job, "render.export")?;
    let frame = s.render_jobs.frame(job).map_err(job_error)?;
    let bytes = match input.format {
        ExportFormat::Png => frame.png(),
        ExportFormat::Exr => frame
            .linear_exr()
            .ok_or_else(|| bad("render.export", "this completed job has no raw linear master; enable retention before rendering"))?,
    };
    // Replace atomically without reading an arbitrarily large previous target into memory.
    // Design saves retain their independent backup policy.
    let result =
        if input.overwrite { solidcraft_io::write_atomic(path, bytes, false) } else { solidcraft_io::safe_write::create_atomic(path, bytes) };
    result.map_err(|e| bad("render.export", format!("could not export completed {}: {e}", input.format.extension())))?;
    Ok(
        json!({"job":job,"path":input.path,"bytes":bytes.len(),"format":input.format.extension(),"encoding":if input.format==ExportFormat::Exr {"scene_linear_srgb_d65"} else {"srgb"},"alpha":if input.format==ExportFormat::Exr {"coverage_premultiplied"} else {"straight"},"frame":frame.info,"linear_master":frame.linear_master_info(),"presentation":frame.presentation()}),
    )
}

fn validate_studio_weights(weights: Option<[f64; 3]>, command: &str) -> Result<Option<[f64; 3]>> {
    if weights.is_some_and(|weights| weights.iter().any(|value| !value.is_finite() || !(0.0..=1.0).contains(value))) {
        return Err(bad(command, "studio visibility weights must be finite in 0..1"));
    }
    Ok(weights)
}