Skip to content

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

67.8 KB
Raw Blame
//! Contracts and result types for the commands in `cmd/sketch_create.rs`: the construction lines,
//! the spline edits, and (#12550) the tangent arcs and circles, slots, splines, conics, ellipses,
//! blend curves, line types and sketch text.
//!
//! The handlers read their parameters from the raw JSON, so each key here reads as its handler
//! reads it and fails with the handler's message. What only the design can tell (a curve or point
//! that does not exist, an expression that does not evaluate, a font that is not installed) stays
//! the handler's to check. A key the handler refuses when it is left out is optional in the type
//! and required in the schema, so that the handler's message, not the check's "is required", is
//! what a caller sees. A key the handler reads only in some cases (`diameter` when there is no
//! `radius`, `end` when there is no `sweep`, the keys of a text outside `edits`) is read here
//! only in those cases, so that a call that works is not warned about. A call with several
//! problems may get a different one first in strict than with the check off (the check goes key
//! by key, the handlers in their own order).

use std::borrow::Cow;

use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};
use serde::de::Error as _;
use serde::{Deserialize, Deserializer, Serialize};
use serde_json::{Value, json};
use solidcore_record::Vec2;

use super::check::{located, parse_issue, whole};
use super::motion::require;
use super::sketch_ends::SketchTarget;
use super::types::{AngleExpr, LengthExpr, Point2, Point3, SketchRef, not_blank_pattern, present};
use crate::params;

/// Create a reference line in the active sketch: infinite, or a segment of a given length.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct ConstructionLineParams {
    /// The construction method.
    pub mode: Option<ConstructionMethod>,
    /// Point to pass through; for tangent_at it selects a contact on the curve.
    pub at: Value,
    /// Second point of a two-point construction line.
    pub through: Option<Value>,
    /// Point used to select the closest solution when several exist; for a line with a
    /// `length`, the side of `at` it runs towards.
    pub near: Option<[f64; 2]>,
    /// Zero-based index in the deterministic list of solutions.
    pub solution: Option<usize>,
    /// A reference line for parallel and perpendicular constructions.
    pub curve: Option<String>,
    /// Second reference curve for a common tangent or an angle bisector.
    pub curve2: Option<String>,
    /// Choose the other tangent when two solutions exist.
    pub alternate: Option<bool>,
    /// Direction measured counter-clockwise from sketch X, in degrees.
    pub angle: Option<AngleExpr>,
    /// A segment of this length from `at` instead of an infinite line, held by a length
    /// dimension. For the horizontal, vertical, angle, parallel and perpendicular methods.
    pub length: Option<LengthExpr>,
    /// `false` makes a line with a `length` a normal sketch line, ready for a profile, instead
    /// of construction geometry (default `true`). An infinite line is always construction.
    pub construction: Option<bool>,
    /// The sketch (default: the one being edited).
    pub sketch: Option<SketchRef>,
}

#[derive(Debug, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ConstructionMethod {
    Free,
    Horizontal,
    Vertical,
    Angle,
    Parallel,
    Perpendicular,
    TangentExternal,
    TangentAt,
    TangentTwo,
    Bisector,
}

/// The curves and constraints created, together with the sketch solve.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ConstructionLineResult {
    pub curves: Vec<String>,
    pub constraints: Vec<String>,
    pub sketch: Value,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

/// Reverse a spline's direction: its last point becomes its first, and the curve runs the other
/// way along the same path. Its points, and the constraints on them and on the curve, stay. Takes
/// fit point, control point and closed splines; refused for a projected spline and for one an
/// offset uses or makes.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct SplineReverseParams {
    /// The spline's curve id.
    #[serde(deserialize_with = "spline_id")]
    pub curve: String,
    /// The sketch (default: the one being edited).
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "SketchRef")]
    pub sketch: Option<SketchRef>,
}

/// Take one point out of a spline: it runs through (or over) its other points only, and the point
/// goes with the constraints on it unless another curve uses it. Takes fit point, control point
/// and closed splines; refused for a closed spline's closing point, for an end joined to other
/// geometry or held by a constraint, when fewer than 2 points would be left (3 on a closed
/// spline), and for a projected, offset or patterned spline.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct SplineRemovePointParams {
    /// The spline's curve id.
    #[serde(deserialize_with = "spline_id")]
    pub curve: String,
    /// One of the spline's points: a point id, or the curve's `start` or `end` (`s1.end`).
    #[serde(deserialize_with = "point_ref")]
    pub point: String,
    /// The sketch (default: the one being edited).
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "SketchRef")]
    pub sketch: Option<SketchRef>,
}

/// What `sketch.spline.remove_point` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct SplineRemovePointResult {
    /// The spline's curve id (unchanged).
    pub curve: String,
    /// The id the point had.
    pub point: String,
    /// Whether the point went too; `false` when another curve still uses it.
    pub deleted: bool,
    /// The sketch's solve: `{solved, dof}`.
    pub sketch: Value,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

/// A point reference, with the handler's message for anything else.
fn point_ref<'de, D: serde::Deserializer<'de>>(d: D) -> Result<String, D::Error> {
    match Value::deserialize(d)? {
        Value::String(s) => Ok(s),
        _ => Err(serde::de::Error::custom("must be one of the spline's points")),
    }
}

/// A curve id, with the handler's message for anything else.
fn spline_id<'de, D: serde::Deserializer<'de>>(d: D) -> Result<String, D::Error> {
    match Value::deserialize(d)? {
        Value::String(s) => Ok(s),
        _ => Err(serde::de::Error::custom("must be a spline id")),
    }
}

/// What `sketch.spline.reverse` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct SplineReverseResult {
    /// The spline's curve id (unchanged).
    pub curve: String,
    /// The sketch's solve: `{solved, dof}`.
    pub sketch: Value,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

// ---------------------------------------------------------------------------------------------
// The creation commands of `cmd/sketch_create.rs` (#12550)

/// A value a handler reads with `null` as absent: `read` turns it into `T`, or into the handler's
/// message, which is passed on whole.
fn nullable<'de, D: Deserializer<'de>, T>(d: D, read: impl FnOnce(Value) -> Result<T, String>) -> Result<Option<T>, D::Error> {
    match Value::deserialize(d)? {
        Value::Null => Ok(None),
        v => read(v).map(Some).map_err(|message| D::Error::custom(whole(message))),
    }
}

/// `message` as the `Err` of a reader.
fn refuse<T>(message: impl Into<String>) -> Result<T, String> {
    Err(message.into())
}

/// The error of a handler's reader, as the message it gives.
fn message_of(e: crate::EngineError) -> String {
    match e {
        crate::EngineError::BadParams { msg, .. } => msg,
        other => other.to_string(),
    }
}

/// `params::string_list`'s reading of `v` as the list `key`, with its messages.
fn name_list(v: &Value, key: &str) -> Result<Vec<String>, String> {
    let mut p = serde_json::Map::new();
    p.insert(key.to_string(), v.clone());
    params::string_list("", &Value::Object(p), key).map_err(message_of)
}

/// Adds properties to an object schema.
fn add_properties(schema: &mut Schema, properties: Value) {
    if let (Some(Value::Object(have)), Value::Object(more)) = (schema.get_mut("properties"), properties) {
        have.extend(more);
    }
}

/// A point `[x, y]` or `{x, y}` in mm, as `params::req_vec2` reads it: the handlers say `` `key`
/// must be a point [x, y] `` for a missing one too.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct PointXY(pub Vec2);

impl<'de> Deserialize<'de> for PointXY {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        params::vec2(&Value::deserialize(d)?).map(PointXY).ok_or_else(|| D::Error::custom("must be a point [x, y]"))
    }
}

impl JsonSchema for PointXY {
    fn schema_name() -> Cow<'static, str> {
        "PointXY".into()
    }
    fn inline_schema() -> bool {
        true
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        generator.subschema_for::<Point2>()
    }
}

/// The forms of a point argument: [`SketchPoint`] and [`SnapPoint`] differ in the snaps.
fn point_arg_schema(generator: &mut SchemaGenerator, snaps: bool) -> Schema {
    let point = generator.subschema_for::<Point2>();
    let coordinate = generator.subschema_for::<LengthExpr>();
    let mut forms = vec![
        json!(point),
        json!({
            "description": "[x, y] where a coordinate may be an expression over the design's parameters, such as [\"w / 2\", 5]: a point that follows the parameters.",
            "type": "array", "items": coordinate, "minItems": 2, "maxItems": 2
        }),
        json!({"description": "An existing point's id such as \"l1.end\" or \"p3\", or a snap such as \"mid:l1\".", "type": "string"}),
        json!({"description": "An existing point by id.", "type": "object", "properties": {"ref": {"type": "string"}}, "required": ["ref"]}),
        json!({"description": "A point by place.", "type": "object", "properties": {"at": point}, "required": ["at"]}),
    ];
    let description = if snaps {
        let model = generator.subschema_for::<Point3>();
        forms.push(json!({"description": "A model vertex [x, y, z] in mm, projected into the sketch.", "type": "object", "properties": {"vertex": model}, "required": ["vertex"]}));
        forms.push(json!({"description": "A point on a model edge [x, y, z] in mm, projected into the sketch.", "type": "object", "properties": {"on_edge": model}, "required": ["on_edge"]}));
        "A sketch point: [x, y] in mm (a coordinate may be an expression), an existing point's id (\"l1.end\"), {ref} or {at}, a snap as text (\"mid:<line>\", \"on:<curve>:x,y\", \"x:<a>+<b>:x,y\", \"vertex:x,y,z\"), or a model {vertex} or {on_edge}."
    } else {
        "A sketch point: [x, y] in mm (a coordinate may be an expression over the design's parameters), an existing point's id such as \"l1.end\", or {ref} or {at}."
    };
    json_schema!({"description": description, "anyOf": forms})
}

/// A point argument as `sketch::parg` reads it: a place `[x, y]` (a coordinate may be an
/// expression), an existing point's id, `{ref}` or `{at}`. Kept as given, for the handler, which
/// has the design to find a point and evaluate an expression.
#[derive(Clone, Debug, PartialEq)]
pub struct SketchPoint(pub Value);

impl<'de> Deserialize<'de> for SketchPoint {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let v = Value::deserialize(d)?;
        crate::cmd::point_arg_form(&v, false).map(|()| SketchPoint(v)).map_err(|why| D::Error::custom(whole(why)))
    }
}

impl JsonSchema for SketchPoint {
    fn schema_name() -> Cow<'static, str> {
        "SketchPoint".into()
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        point_arg_schema(generator, false)
    }
}

/// A point argument of a command that snaps its points (`sketch_project::snap_points`): a
/// [`SketchPoint`], or a model `{vertex}` or `{on_edge}`. Snaps given as text are text.
#[derive(Clone, Debug, PartialEq)]
pub struct SnapPoint(pub Value);

impl<'de> Deserialize<'de> for SnapPoint {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let v = Value::deserialize(d)?;
        crate::cmd::point_arg_form(&v, true).map(|()| SnapPoint(v)).map_err(|why| D::Error::custom(whole(why)))
    }
}

impl JsonSchema for SnapPoint {
    fn schema_name() -> Cow<'static, str> {
        "SnapPoint".into()
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        point_arg_schema(generator, true)
    }
}

/// A width, as the slot commands read it: a number above 0.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct SlotWidth(pub f64);

impl<'de> Deserialize<'de> for SlotWidth {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)?.as_f64().and_then(params::finite) {
            Some(w) if w > 1e-9 => Ok(SlotWidth(w)),
            _ => Err(D::Error::custom("must be positive")),
        }
    }
}

impl JsonSchema for SlotWidth {
    fn schema_name() -> Cow<'static, str> {
        "SlotWidth".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({
            "description": "The slot's width in mm: more than 0.000000001 and below 1 000 000 000.",
            "type": "number", "exclusiveMinimum": 1e-9, "exclusiveMaximum": 1e9
        })
    }
}

/// The schema of curve ids as `params::string_list` reads them: a list of ids, or one id when
/// one is enough, with the bounds on the list.
fn curve_ids_schema(description: &str, min: usize, max: usize) -> Schema {
    let list = json!({"type": "array", "items": {"type": "string"}, "minItems": min, "maxItems": max});
    let forms = if min <= 1 && max >= 1 { json!([{"type": "string"}, list]) } else { json!([list]) };
    json_schema!({"description": description, "anyOf": forms})
}

/// `N` curves, as the tangent circles read `curves`: an id or a list of exactly `N` ids. A
/// missing, `null` or wrongly long one is refused with the same message.
#[derive(Clone, Debug, PartialEq)]
pub struct CurveIds<const N: usize>(pub Vec<String>);

impl<'de, const N: usize> Deserialize<'de> for CurveIds<N> {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let ids = name_list(&Value::deserialize(d)?, "curves").map_err(|m| D::Error::custom(whole(m)))?;
        if ids.len() == N { Ok(CurveIds(ids)) } else { Err(D::Error::custom(whole(format!("`curves` must list {N} curves")))) }
    }
}

impl<const N: usize> JsonSchema for CurveIds<N> {
    fn schema_name() -> Cow<'static, str> {
        format!("CurveIds{N}").into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        curve_ids_schema(&format!("Exactly {N} curves of the sketch (lines, circles or arcs), by id."), N, N)
    }
}

/// Lines, as the centerline and infinite line commands read `curves`: an id or a list of ids, at
/// least one.
#[derive(Clone, Debug, PartialEq)]
pub struct LineIds(pub Vec<String>);

impl<'de> Deserialize<'de> for LineIds {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let ids = name_list(&Value::deserialize(d)?, "curves").map_err(|m| D::Error::custom(whole(m)))?;
        if ids.is_empty() { Err(D::Error::custom(whole("`curves` must list lines"))) } else { Ok(LineIds(ids)) }
    }
}

impl JsonSchema for LineIds {
    fn schema_name() -> Cow<'static, str> {
        "LineIds".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        curve_ids_schema("The lines, by id: one id or a list of ids.", 1, params::MAX_STRING_LIST)
    }
}

/// `blend_curve`'s `continuity`, as `blend_order` reads it: g1 to g4 in either case, blank for g1.
#[derive(Clone, Debug, PartialEq)]
pub struct BlendContinuity(pub String);

impl<'de> Deserialize<'de> for BlendContinuity {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let v = Value::deserialize(d)?;
        if v.as_str().is_some_and(|s| s.trim().is_empty()) {
            return Ok(BlendContinuity(String::new()));
        }
        params::continuity("", Some(&v), "`continuity`", solidcraft_kernel::Construction::BlendCurve)
            .map(|g| BlendContinuity(g.as_str().to_string()))
            .map_err(|e| D::Error::custom(whole(message_of(e))))
    }
}

impl JsonSchema for BlendContinuity {
    fn schema_name() -> Cow<'static, str> {
        "BlendContinuity".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        let blank = super::types::whitespace_class();
        json_schema!({
            "description": "How the blend meets the two curves: g1 (the default, a tangent spline), g2, g3 or g4 (the curvature, its rate and the 4th derivative match too, as one Bézier of degree 5, 7 or 9). Either case; blank is g1.",
            "type": "string",
            "pattern": format!("^[{blank}]*([gG][1-4][{blank}]*)?$")
        })
    }
}

/// `periodic`, as `spline` reads it: true or false (`null` too is refused). Only a cubic fit
/// point spline (`FIT`) can be periodic; the control point splines refuse `true`.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Periodic<const FIT: bool>(pub bool);

impl<'de, const FIT: bool> Deserialize<'de> for Periodic<FIT> {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::Bool(b) if FIT || !b => Ok(Periodic(b)),
            Value::Bool(_) => Err(D::Error::custom(whole("periodic mode requires a cubic fit spline"))),
            _ => Err(D::Error::custom(whole("periodic must be boolean"))),
        }
    }
}

impl<const FIT: bool> JsonSchema for Periodic<FIT> {
    fn schema_name() -> Cow<'static, str> {
        if FIT { "PeriodicFit" } else { "PeriodicNever" }.into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        if FIT {
            json_schema!({"description": "Close the spline smoothly through its points (needs at least 3 distinct points). Default: false.", "type": "boolean"})
        } else {
            json_schema!({"description": "Not available for a control point spline: only false is accepted. Default: false.", "type": "boolean", "const": false})
        }
    }
}

/// A spline's points, as `point_list` reads them: 2 to 500 point arguments, snaps included.
#[derive(Clone, Debug, PartialEq)]
pub struct SplinePoints(pub Vec<Value>);

impl<'de> Deserialize<'de> for SplinePoints {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let Value::Array(list) = Value::deserialize(d)? else {
            return Err(D::Error::custom(whole("`points` must be a list")));
        };
        if list.len() < 2 || list.len() > solidcraft_sketch::MAX_SPLINE_POINTS {
            return Err(D::Error::custom(whole("a spline needs 2 to 500 points")));
        }
        for v in &list {
            crate::cmd::point_arg_form(v, true).map_err(|why| D::Error::custom(whole(why)))?;
        }
        Ok(SplinePoints(list))
    }
}

impl JsonSchema for SplinePoints {
    fn schema_name() -> Cow<'static, str> {
        "SplinePoints".into()
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        let point = generator.subschema_for::<SnapPoint>();
        json_schema!({
            "description": "The spline's points, 2 to 500, each [x, y], a point id or a snap; consecutive points must differ.",
            "type": "array", "items": point, "minItems": 2, "maxItems": solidcraft_sketch::MAX_SPLINE_POINTS
        })
    }
}

/// Make a line through a midpoint: the line's middle is `mid` and one end is `end`, the other is
/// the mirror image, held by a midpoint constraint.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = midpoint_required)]
pub struct MidpointLineParams {
    // Optional in the type and required in the schema (`midpoint_required`): left out, the handler
    // refuses it with its own message.
    /// The line's middle: a point.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "SnapPoint")]
    pub mid: Option<SnapPoint>,
    /// One end of the line, [x, y] in mm.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "PointXY")]
    pub end: Option<PointXY>,
    /// Make it construction geometry. Default: false.
    #[serde(default)]
    pub construction: Option<bool>,
    /// The sketch (default: the one being edited).
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
}

fn midpoint_required(schema: &mut Schema) {
    for key in ["mid", "end"] {
        require(schema, key);
    }
}

/// `sketch.arc.tangent`'s `end`: the id of an existing point, or a place [x, y].
#[derive(Clone, Debug, PartialEq)]
pub enum ArcEnd {
    /// The arc ends on this point.
    Point(String),
    /// A new point there.
    At(Vec2),
}

impl<'de> Deserialize<'de> for ArcEnd {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::String(id) => Ok(ArcEnd::Point(id)),
            v => params::vec2(&v).map(ArcEnd::At).ok_or_else(|| D::Error::custom("must be a point [x, y]")),
        }
    }
}

impl JsonSchema for ArcEnd {
    fn schema_name() -> Cow<'static, str> {
        "ArcEnd".into()
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        let point = generator.subschema_for::<Point2>();
        json_schema!({
            "description": "Where the arc ends: [x, y] in mm (a new point), or an existing point's id such as \"l2.start\" (the arc ends on that point).",
            "anyOf": [point, {"type": "string"}]
        })
    }
}

/// Draw an arc that leaves the end of a line, arc or spline tangent to it, and ends at `end`,
/// held by a tangent constraint.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = arc_tangent_required)]
pub struct ArcTangentParams {
    /// Where the arc starts: the end point of a drawn line, arc or spline, by id (`l1.end`).
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "SketchPoint")]
    pub start: Option<SketchPoint>,
    /// Where it ends.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "ArcEnd")]
    pub end: Option<ArcEnd>,
    /// The curve to be tangent to. Default: the first drawn curve that ends at `start`.
    #[serde(default)]
    pub curve: Option<String>,
    /// The sketch (default: the one being edited).
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
}

fn arc_tangent_required(schema: &mut Schema) {
    for key in ["start", "end"] {
        require(schema, key);
    }
}

/// A diameter, as `sketch.circle.two_tangent` reads it without a `radius`: a finite number.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Diameter(pub f64);

impl<'de> Deserialize<'de> for Diameter {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        Value::deserialize(d)?.as_f64().and_then(params::finite).map(Diameter).ok_or_else(|| D::Error::custom(whole("needs `radius` or `diameter`")))
    }
}

impl JsonSchema for Diameter {
    fn schema_name() -> Cow<'static, str> {
        "Diameter".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({"description": "A diameter in mm.", "type": "number", "exclusiveMinimum": -1e9, "exclusiveMaximum": 1e9})
    }
}

/// Draw a circle tangent to two curves, with a radius or a diameter, near a point; the radius is
/// held by a dimension.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = two_tangent_required)]
pub struct TwoTangentCircleKeys {
    /// The radius: a number in mm or a length expression. Wins over `diameter`.
    #[serde(default)]
    pub radius: Option<LengthExpr>,
    /// The diameter in mm, a number; used when there is no `radius`.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "Diameter")]
    pub diameter: Option<Diameter>,
    /// Which of the solutions: the circle whose centre is nearest this point, [x, y] in mm.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "PointXY")]
    pub near: Option<PointXY>,
    /// The two curves, by id: lines, circles or arcs of the sketch.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "CurveIds<2>")]
    pub curves: Option<CurveIds<2>>,
    /// The sketch (default: the one being edited).
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
}

fn two_tangent_required(schema: &mut Schema) {
    for key in ["near", "curves"] {
        require(schema, key);
    }
    schema.insert("anyOf".into(), json!([{"required": ["radius"]}, {"required": ["diameter"]}]));
}

/// `sketch.circle.two_tangent`'s parameters: [`TwoTangentCircleKeys`], with `diameter` left unread
/// when there is a `radius`, and a `radius` that isn't one left unread otherwise, as the handler
/// does.
#[derive(Debug)]
pub struct TwoTangentCircleParams(pub TwoTangentCircleKeys);

impl<'de> Deserialize<'de> for TwoTangentCircleParams {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let mut value = Value::deserialize(d)?;
        let radius = params::expr(&value, "radius").is_some();
        if let Some(keys) = value.as_object_mut() {
            keys.remove(if radius { "diameter" } else { "radius" });
        }
        serde_path_to_error::deserialize(&value).map(TwoTangentCircleParams).map_err(|e| D::Error::custom(located(&e)))
    }
}

impl JsonSchema for TwoTangentCircleParams {
    fn schema_name() -> Cow<'static, str> {
        "TwoTangentCircleParams".into()
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        let mut schema = TwoTangentCircleKeys::json_schema(generator);
        schema.insert("title".into(), "TwoTangentCircleParams".into());
        schema
    }
}

/// Draw a circle tangent to three curves, near a point, held by three tangent constraints.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = three_tangent_required)]
pub struct ThreeTangentCircleParams {
    /// Which of the solutions: the circle whose centre is nearest this point, [x, y] in mm.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "PointXY")]
    pub near: Option<PointXY>,
    /// The three curves, by id: lines, circles or arcs of the sketch.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "CurveIds<3>")]
    pub curves: Option<CurveIds<3>>,
    /// The sketch (default: the one being edited).
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
}

fn three_tangent_required(schema: &mut Schema) {
    for key in ["near", "curves"] {
        require(schema, key);
    }
}

/// Draw a slot from its centre and the centre of one end arc; the other end is the mirror
/// image. Four tangent constraints and an equal one hold it.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = slot_center_required)]
pub struct SlotCenterPointParams {
    /// The slot's centre, [x, y] in mm.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "PointXY")]
    pub center: Option<PointXY>,
    /// The centre of one end arc, [x, y] in mm; the other end is its mirror image through `center`.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "PointXY")]
    pub end: Option<PointXY>,
    /// The slot's width, in mm.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "SlotWidth")]
    pub width: Option<SlotWidth>,
    /// Join the new points to the existing points they land on. Default: true.
    #[serde(default)]
    pub connect: Option<bool>,
    /// The sketch (default: the one being edited).
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
}

fn slot_center_required(schema: &mut Schema) {
    for key in ["center", "end", "width"] {
        require(schema, key);
    }
}

/// Draw a slot along an arc through three points on its centre arc. Returns `centre_arc`: the
/// construction arc along the slot's middle.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = arc_slot_three_required)]
pub struct ArcSlotThreePointParams {
    /// The centre arc's start, [x, y] in mm.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "PointXY")]
    pub start: Option<PointXY>,
    /// A point the centre arc passes through, [x, y] in mm.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "PointXY")]
    pub through: Option<PointXY>,
    /// The centre arc's end, [x, y] in mm.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "PointXY")]
    pub end: Option<PointXY>,
    /// The slot's width, in mm.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "SlotWidth")]
    pub width: Option<SlotWidth>,
    /// The sketch (default: the one being edited).
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
}

fn arc_slot_three_required(schema: &mut Schema) {
    for key in ["start", "through", "end", "width"] {
        require(schema, key);
    }
}

/// The sweep of an arc slot, as `sketch.slot.arc_center` reads it: a number of degrees (`null`
/// is refused).
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Sweep(pub f64);

impl<'de> Deserialize<'de> for Sweep {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        Value::deserialize(d)?.as_f64().and_then(params::finite).map(Sweep).ok_or_else(|| D::Error::custom(whole("`sweep` must be finite degrees")))
    }
}

impl JsonSchema for Sweep {
    fn schema_name() -> Cow<'static, str> {
        "Sweep".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({"description": "The sweep in degrees, counter-clockwise from `start`; the sketch refuses one that is not above 0 and below 360.", "type": "number", "exclusiveMinimum": -1e9, "exclusiveMaximum": 1e9})
    }
}

/// Draw a slot along an arc from its centre, the start of its centre arc and its end or sweep.
/// Returns `centre_arc`: the construction arc along the slot's middle.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = arc_slot_center_required)]
pub struct ArcSlotCenterKeys {
    /// The centre of the arcs, [x, y] in mm.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "PointXY")]
    pub center: Option<PointXY>,
    /// The centre arc's start, [x, y] in mm; its distance from `center` is the arc's radius.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "PointXY")]
    pub start: Option<PointXY>,
    /// The slot's width, in mm.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "SlotWidth")]
    pub width: Option<SlotWidth>,
    /// How far the centre arc turns counter-clockwise, in degrees (0 to 360, not including
    /// either). Wins over `end`, which is then not read.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "Sweep")]
    pub sweep: Option<Sweep>,
    /// Without `sweep`: a point in the direction of the centre arc's end from `center` (the arc
    /// runs counter-clockwise from `start` to it), [x, y] in mm.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "PointXY")]
    pub end: Option<PointXY>,
    /// The sketch (default: the one being edited).
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
}

fn arc_slot_center_required(schema: &mut Schema) {
    for key in ["center", "start", "width"] {
        require(schema, key);
    }
    schema.insert("anyOf".into(), json!([{"required": ["sweep"]}, {"required": ["end"]}]));
}

/// `sketch.slot.arc_center`'s parameters: [`ArcSlotCenterKeys`], with `end` left unread when
/// `sweep` is there (`null` included), as the handler does.
#[derive(Debug)]
pub struct ArcSlotCenterParams(pub ArcSlotCenterKeys);

impl<'de> Deserialize<'de> for ArcSlotCenterParams {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let mut value = Value::deserialize(d)?;
        if let Some(keys) = value.as_object_mut().filter(|o| o.contains_key("sweep")) {
            keys.remove("end");
        }
        serde_path_to_error::deserialize(&value).map(ArcSlotCenterParams).map_err(|e| D::Error::custom(located(&e)))
    }
}

impl JsonSchema for ArcSlotCenterParams {
    fn schema_name() -> Cow<'static, str> {
        "ArcSlotCenterParams".into()
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        let mut schema = ArcSlotCenterKeys::json_schema(generator);
        schema.insert("title".into(), "ArcSlotCenterParams".into());
        schema
    }
}

/// The minor radius of an ellipse, as `sketch.ellipse` reads it: a number of mm above 0.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct MinorRadius(pub f64);

impl<'de> Deserialize<'de> for MinorRadius {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)?.as_f64().and_then(params::finite) {
            Some(r) if r > 1e-9 && r < 1e8 => Ok(MinorRadius(r)),
            _ => Err(D::Error::custom(whole("the minor radius must be positive"))),
        }
    }
}

impl JsonSchema for MinorRadius {
    fn schema_name() -> Cow<'static, str> {
        "MinorRadius".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({"description": "The minor radius in mm: above 0.000000001 and below 100 000 000.", "type": "number", "exclusiveMinimum": 1e-9, "exclusiveMaximum": 1e8})
    }
}

/// The point an ellipse passes through on its minor side, as `sketch.ellipse` reads `minor`
/// without a `minor_radius`.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct MinorPoint(pub Vec2);

impl<'de> Deserialize<'de> for MinorPoint {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        params::vec2(&Value::deserialize(d)?).map(MinorPoint).ok_or_else(|| D::Error::custom(whole("needs `minor` [x,y] or `minor_radius`")))
    }
}

impl JsonSchema for MinorPoint {
    fn schema_name() -> Cow<'static, str> {
        "MinorPoint".into()
    }
    fn inline_schema() -> bool {
        true
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        generator.subschema_for::<Point2>()
    }
}

/// `axes`, as `sketch.ellipse` reads it: true or false (`null` is the default).
fn axes_flag<'de, D: Deserializer<'de>>(d: D) -> Result<Option<bool>, D::Error> {
    nullable(d, |v| match v {
        Value::Bool(b) => Ok(b),
        _ => refuse("`axes` must be true or false"),
    })
}

/// Draw an ellipse from its centre, the end of its major axis and its minor radius or a point on
/// its minor side. By default it also gets its major and minor axes as construction lines, held
/// by midpoint, perpendicular and point-on-curve constraints.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = ellipse_required)]
pub struct EllipseKeys {
    /// The ellipse's centre, [x, y] in mm.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "PointXY")]
    pub center: Option<PointXY>,
    /// The end of the major axis, [x, y] in mm; not the centre.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "PointXY")]
    pub major: Option<PointXY>,
    /// The minor radius in mm. Wins over `minor`, which is then not read.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "MinorRadius")]
    pub minor_radius: Option<MinorRadius>,
    /// Without `minor_radius`: a point [x, y] in mm the ellipse passes through on its minor side;
    /// it must lie within the span of the major axis.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "MinorPoint")]
    pub minor: Option<MinorPoint>,
    /// Also add the major and minor axes as construction lines. Default: true.
    #[serde(default, deserialize_with = "axes_flag", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "bool")]
    pub axes: Option<bool>,
    /// Make it construction geometry. Default: false.
    #[serde(default)]
    pub construction: Option<bool>,
    /// The sketch (default: the one being edited).
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
}

fn ellipse_required(schema: &mut Schema) {
    for key in ["center", "major"] {
        require(schema, key);
    }
    schema.insert("anyOf".into(), json!([{"required": ["minor"]}, {"required": ["minor_radius"]}]));
}

/// `sketch.ellipse`'s parameters: [`EllipseKeys`], with `minor` left unread when there is a
/// `minor_radius`, and a `minor_radius` that isn't a number left unread, as the handler does.
#[derive(Debug)]
pub struct EllipseParams(pub EllipseKeys);

impl<'de> Deserialize<'de> for EllipseParams {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let mut value = Value::deserialize(d)?;
        let radius = params::num(&value, "minor_radius").is_some();
        if let Some(keys) = value.as_object_mut() {
            keys.remove(if radius { "minor" } else { "minor_radius" });
        }
        serde_path_to_error::deserialize(&value).map(EllipseParams).map_err(|e| D::Error::custom(located(&e)))
    }
}

impl JsonSchema for EllipseParams {
    fn schema_name() -> Cow<'static, str> {
        "EllipseParams".into()
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        let mut schema = EllipseKeys::json_schema(generator);
        schema.insert("title".into(), "EllipseParams".into());
        schema
    }
}

/// The conic's `rho`, as `sketch.conic` reads it: a number above 0 and below 1 (one of 1e9 or
/// more in size is ignored, as if left out).
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Rho(pub f64);

impl<'de> Deserialize<'de> for Rho {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::Number(n) => match n.as_f64().and_then(params::finite) {
                Some(r) if r > 1e-6 && r < 1.0 - 1e-6 => Ok(Rho(r)),
                Some(_) => Err(D::Error::custom(whole("`rho` must be between 0 and 1"))),
                None => Ok(Rho(0.5)),
            },
            _ => Err(D::Error::custom("must be a number between 0 and 1")),
        }
    }
}

impl JsonSchema for Rho {
    fn schema_name() -> Cow<'static, str> {
        "Rho".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({
            "description": "How full the curve is: above 0 and below 1. 0.5 is a parabola, less an ellipse, more a hyperbola. A number of 1e9 or more in size is ignored. Default: 0.5.",
            "type": "number", "exclusiveMinimum": 1e-6, "exclusiveMaximum": 1.0 - 1e-6
        })
    }
}

/// Draw a conic curve from its two ends and the apex where the tangents there meet.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = conic_required)]
pub struct ConicParams {
    /// The conic's start: a point.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "SnapPoint")]
    pub start: Option<SnapPoint>,
    /// The conic's end: a point, not the start.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "SnapPoint")]
    pub end: Option<SnapPoint>,
    /// The apex, where the tangents at both ends meet: a point, not the start or end.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "SnapPoint")]
    pub apex: Option<SnapPoint>,
    /// How full the curve is. Default: 0.5 (a parabola).
    #[serde(default)]
    pub rho: Option<Rho>,
    /// Make it construction geometry. Default: false.
    #[serde(default)]
    pub construction: Option<bool>,
    /// The sketch (default: the one being edited).
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
}

fn conic_required(schema: &mut Schema) {
    for key in ["start", "end", "apex"] {
        require(schema, key);
    }
}

/// Draw a fit point spline: a cubic spline through points, optionally closed (periodic).
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = points_required)]
pub struct FitPointSplineParams {
    /// The points the spline passes through.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "SplinePoints")]
    pub points: Option<SplinePoints>,
    /// Close it smoothly through its points. Default: false.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "Periodic<true>")]
    pub periodic: Option<Periodic<true>>,
    /// Make it construction geometry. Default: false.
    #[serde(default)]
    pub construction: Option<bool>,
    /// The sketch (default: the one being edited).
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
}

/// Draw a control point spline: a cubic one (`sketch.spline.control_point`) or one of degree 5
/// (`sketch.spline.control_point_5`), shaped by its control points.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = points_required)]
pub struct ControlPointSplineParams {
    /// The control points.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "SplinePoints")]
    pub points: Option<SplinePoints>,
    /// Refused as true: only a cubic fit point spline can be periodic. Default: false.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "Periodic<false>")]
    pub periodic: Option<Periodic<false>>,
    /// Make it construction geometry. Default: false.
    #[serde(default)]
    pub construction: Option<bool>,
    /// The sketch (default: the one being edited).
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
}

fn points_required(schema: &mut Schema) {
    require(schema, "points");
}

/// Join the end points of two curves with a blend curve: a tangent spline (g1), or one Bézier that
/// also matches the curves' curvature and more (g2 to g4).
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = blend_required)]
pub struct BlendCurveParams {
    /// The end point of the first curve, by id (`l1.end`).
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "SketchPoint")]
    pub a: Option<SketchPoint>,
    /// The end point of the second curve, by id (`a2.start`); not the same place as `a`.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "SketchPoint")]
    pub b: Option<SketchPoint>,
    /// g1 (the default), g2, g3 or g4.
    #[serde(default)]
    pub continuity: Option<BlendContinuity>,
    /// The sketch (default: the one being edited).
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
}

fn blend_required(schema: &mut Schema) {
    for key in ["a", "b"] {
        require(schema, key);
    }
}

/// Make lines centerlines (an axis: not in profiles), or ordinary lines again.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = curves_required)]
pub struct CenterlineParams {
    /// The lines, by id.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "LineIds")]
    pub curves: Option<LineIds>,
    /// True makes them centerlines, false ordinary lines. Default: each line switches.
    #[serde(default)]
    pub value: Option<bool>,
    /// The sketch (default: the one being edited).
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
}

/// Make lines infinite lines (construction geometry drawn across the whole view through the
/// line's two points), or ordinary lines again.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = curves_required)]
pub struct InfiniteLineParams {
    /// The lines, by id.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "LineIds")]
    pub curves: Option<LineIds>,
    /// True makes them infinite, false ordinary lines. Default: each line switches.
    #[serde(default)]
    pub value: Option<bool>,
    /// The sketch (default: the one being edited).
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
}

fn curves_required(schema: &mut Schema) {
    require(schema, "curves");
}

/// What the creation commands return: what they made and the sketch's solve.
#[derive(Debug, Serialize, JsonSchema)]
pub struct DrawResult {
    /// The ids of the curves made.
    pub curves: Vec<String>,
    /// The ids of the constraints made.
    pub constraints: Vec<String>,
    /// The sketch's solve: `{solved, dof}`.
    pub sketch: Value,
    /// What it added: `{points, curves, constraints, dimensions}`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub created: Option<Value>,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

/// What `sketch.slot.arc_three_point` and `sketch.slot.arc_center` return.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ArcSlotResult {
    #[serde(flatten)]
    pub drawn: DrawResult,
    /// The id of the construction arc along the slot's middle.
    pub centre_arc: Option<String>,
}

/// What `sketch.centerline` and `sketch.infinite` return.
#[derive(Debug, Serialize, JsonSchema)]
pub struct LineTypeResult {
    /// How many lines were changed.
    pub changed: usize,
    /// The sketch's solve: `{solved, dof}`.
    pub sketch: Value,
    /// What it added: `{points, curves, constraints, dimensions}`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub created: Option<Value>,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

// ---------------------------------------------------------------------------------------------
// Sketch text

/// The words of a text, as `text_source` reads `text`: a string that isn't blank, of at most
/// `MAX_TEXT_CHARS` characters (`null` is as left out).
fn text_words<'de, D: Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
    nullable(d, |v| match v {
        Value::String(t) if t.trim().is_empty() => refuse("`text` must not be empty"),
        Value::String(t) if t.chars().count() > solidcraft_sketch::MAX_TEXT_CHARS => refuse("text too long"),
        Value::String(t) => Ok(t),
        _ => refuse("`text` must be a string"),
    })
}

fn text_words_schema(_: &mut SchemaGenerator) -> Schema {
    json_schema!({"type": "string", "pattern": not_blank_pattern(), "maxLength": solidcraft_sketch::MAX_TEXT_CHARS})
}

fn text_expression<'de, D: Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
    nullable(d, |v| match v {
        Value::String(e) => Ok(e),
        _ => refuse("`text_expression` must be a string"),
    })
}

fn string_schema(_: &mut SchemaGenerator) -> Schema {
    json_schema!({"type": "string"})
}

/// A number of a text, as `text_number` reads it: a finite number, or text that isn't blank (an
/// expression), at most 4096 bytes.
fn text_number_form(v: &Value) -> bool {
    match v {
        Value::Number(n) => n.as_f64().and_then(params::finite).is_some(),
        Value::String(e) => !e.trim().is_empty() && e.len() <= 4096,
        _ => false,
    }
}

/// A text's `at`: `[x, y]` with each a number or an expression, or `{x, y}` of numbers.
fn text_at<'de, D: Deserializer<'de>>(d: D) -> Result<Option<Value>, D::Error> {
    nullable(d, |v| {
        let ok = match &v {
            Value::Array(a) => matches!(a.as_slice(), [x, y] if text_number_form(x) && text_number_form(y)),
            other => params::vec2(other).is_some(),
        };
        if ok { Ok(v) } else { refuse(crate::cmd::AT_MUST) }
    })
}

fn text_at_schema(generator: &mut SchemaGenerator) -> Schema {
    let coordinate = generator.subschema_for::<LengthExpr>();
    let point = generator.subschema_for::<Point2>();
    json_schema!({
        "anyOf": [{"type": "array", "items": coordinate, "minItems": 2, "maxItems": 2}, point]
    })
}

fn expression_string() -> Value {
    json!({"type": "string", "minLength": 1, "maxLength": 4096, "pattern": not_blank_pattern()})
}

/// A text's `height`: a number of mm above 0 and below 1e5, or an expression.
fn text_height<'de, D: Deserializer<'de>>(d: D) -> Result<Option<Value>, D::Error> {
    nullable(d, |v| {
        if !text_number_form(&v) {
            return refuse("`height` must be a length in mm, or an expression");
        }
        match v.as_f64() {
            Some(h) if !(h > 1e-6 && h < 1e5) => refuse("`height` must be positive"),
            _ => Ok(v),
        }
    })
}

fn text_height_schema(_: &mut SchemaGenerator) -> Schema {
    json_schema!({"anyOf": [{"type": "number", "exclusiveMinimum": 1e-6, "exclusiveMaximum": 1e5}, expression_string()]})
}

/// A text's `angle`: a number of degrees, or an expression.
fn text_angle<'de, D: Deserializer<'de>>(d: D) -> Result<Option<Value>, D::Error> {
    nullable(d, |v| if text_number_form(&v) { Ok(v) } else { refuse("`angle` must be an angle in degrees, or an expression") })
}

fn text_angle_schema(_: &mut SchemaGenerator) -> Schema {
    json_schema!({"anyOf": [{"type": "number", "exclusiveMinimum": -1e9, "exclusiveMaximum": 1e9}, expression_string()]})
}

fn text_font<'de, D: Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
    nullable(d, |v| match v {
        Value::String(f) => Ok(f),
        _ => refuse("`font` must be a font family name or a font file path"),
    })
}

macro_rules! text_flag {
    ($name:ident, $key:literal) => {
        fn $name<'de, D: Deserializer<'de>>(d: D) -> Result<Option<bool>, D::Error> {
            nullable(d, |v| match v {
                Value::Bool(b) => Ok(b),
                _ => refuse(concat!("`", $key, "` must be true or false")),
            })
        }
    };
}

text_flag!(text_bold, "bold");
text_flag!(text_italic, "italic");
text_flag!(text_reverse, "reverse");

fn text_align<'de, D: Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
    nullable(d, |v| match v {
        Value::String(a) if matches!(a.trim().to_ascii_lowercase().as_str(), "left" | "center" | "centre" | "right") => Ok(a),
        _ => refuse("`align` must be left, center or right"),
    })
}

/// A pattern for one of the words, whatever its case, with blanks around it.
fn word_pattern(words: &[&str]) -> String {
    let blank = super::types::whitespace_class();
    let case = |w: &str| w.chars().map(|c| format!("[{}{}]", c.to_ascii_uppercase(), c)).collect::<String>();
    format!("^[{blank}]*({})[{blank}]*$", words.iter().map(|w| case(w)).collect::<Vec<_>>().join("|"))
}

fn text_align_schema(_: &mut SchemaGenerator) -> Schema {
    json_schema!({"type": "string", "pattern": word_pattern(&["left", "center", "centre", "right"])})
}

fn text_letter_spacing<'de, D: Deserializer<'de>>(d: D) -> Result<Option<f64>, D::Error> {
    nullable(d, |v| v.as_f64().and_then(params::finite).map_or_else(|| refuse("`letter_spacing` must be a length in mm"), Ok))
}

fn text_letter_spacing_schema(_: &mut SchemaGenerator) -> Schema {
    json_schema!({"type": "number", "exclusiveMinimum": -1e9, "exclusiveMaximum": 1e9})
}

fn text_line_spacing<'de, D: Deserializer<'de>>(d: D) -> Result<Option<f64>, D::Error> {
    nullable(d, |v| v.as_f64().and_then(params::finite).filter(|s| *s > 0.0).map_or_else(|| refuse("`line_spacing` must be a positive factor"), Ok))
}

fn text_line_spacing_schema(_: &mut SchemaGenerator) -> Schema {
    json_schema!({"type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1e9})
}

fn text_path<'de, D: Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
    nullable(d, |v| match v {
        Value::String(c) => Ok(c),
        _ => refuse("`path` must be a curve id"),
    })
}

/// What a text is, as `sketch.text` and `sketch.edit_text` read it (`null` is as left out for
/// each).
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct TextKeys {
    /// The words, at most 4096 characters, `\n` breaking lines; not blank. Not with
    /// `text_expression`. When editing, kept when left out.
    #[serde(default, deserialize_with = "text_words", skip_serializing_if = "Option::is_none")]
    #[schemars(schema_with = "text_words_schema")]
    pub text: Option<String>,
    /// The words built from text parameters (`parameters.add` with unit text), number parameters
    /// and quoted texts joined by `+` (`"Label + '-L'"`, `"'W' + Width"`; `number(Width, 2)` is
    /// a number with 2 decimals). The text keeps it and follows the parameters; the reply's
    /// `exprs` returns it as `text`. Not with `text`. When editing, typed words replace it.
    #[serde(default, deserialize_with = "text_expression", skip_serializing_if = "Option::is_none")]
    #[schemars(schema_with = "string_schema")]
    pub text_expression: Option<String>,
    /// The baseline start, [x, y] in mm, or {x, y}; in `[x, y]` each is a number or an expression
    /// over the design's parameters as a string (`"plate_width / 2"`), which the text keeps and
    /// follows. Needed to make a text; when editing, kept when left out (and moving a text
    /// replaces its expressions with numbers). Does not place a text on a `path`.
    #[serde(default, deserialize_with = "text_at", skip_serializing_if = "Option::is_none")]
    #[schemars(schema_with = "text_at_schema")]
    pub at: Option<Value>,
    /// The capital height in mm (above 0, below 100 000), a number or an expression over the
    /// design's parameters. Default: 5. When editing, kept when left out.
    #[serde(default, deserialize_with = "text_height", skip_serializing_if = "Option::is_none")]
    #[schemars(schema_with = "text_height_schema")]
    pub height: Option<Value>,
    /// The direction of the baseline, counter-clockwise from sketch X: a number of degrees or an
    /// expression. Default: 0. When editing, kept when left out. Does not turn a text on a `path`.
    #[serde(default, deserialize_with = "text_angle", skip_serializing_if = "Option::is_none")]
    #[schemars(schema_with = "text_angle_schema")]
    pub angle: Option<Value>,
    /// An installed font's family or full name, or a .ttf or .otf file path (`~` and `%VAR%`
    /// expand); empty: the built-in Liberation Sans. Default: the built-in font. When editing,
    /// kept when left out.
    #[serde(default, deserialize_with = "text_font", skip_serializing_if = "Option::is_none")]
    #[schemars(schema_with = "string_schema")]
    pub font: Option<String>,
    /// An installed family's bold face. Default: false. When editing, kept when left out.
    #[serde(default, deserialize_with = "text_bold", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "bool")]
    pub bold: Option<bool>,
    /// An installed family's italic face (without one, the text is slanted). Default: false. When
    /// editing, kept when left out.
    #[serde(default, deserialize_with = "text_italic", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "bool")]
    pub italic: Option<bool>,
    /// Run the text the other way along its `path`. Default: false. When editing, kept when left
    /// out.
    #[serde(default, deserialize_with = "text_reverse", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "bool")]
    pub reverse: Option<bool>,
    /// The lines against `at`, or along the path: left, center (or centre) or right, either case.
    /// Default: left. When editing, kept when left out.
    #[serde(default, deserialize_with = "text_align", skip_serializing_if = "Option::is_none")]
    #[schemars(schema_with = "text_align_schema")]
    pub align: Option<String>,
    /// Extra space between letters, in mm. Default: 0. When editing, kept when left out.
    #[serde(default, deserialize_with = "text_letter_spacing", skip_serializing_if = "Option::is_none")]
    #[schemars(schema_with = "text_letter_spacing_schema")]
    pub letter_spacing: Option<f64>,
    /// The line distance as a multiple of the font's (above 0). Default: 1. When editing, kept
    /// when left out.
    #[serde(default, deserialize_with = "text_line_spacing", skip_serializing_if = "Option::is_none")]
    #[schemars(schema_with = "text_line_spacing_schema")]
    pub line_spacing: Option<f64>,
    /// A curve id of the sketch the baseline follows; empty: none. `at` and `angle` then do not
    /// place the text, and the curve becomes construction, a guide the letters stand on. When
    /// editing, kept when left out.
    #[serde(default, deserialize_with = "text_path", skip_serializing_if = "Option::is_none")]
    #[schemars(schema_with = "string_schema")]
    pub path: Option<String>,
}

/// The text keys of `value`, with the handler's messages: `text` and `text_expression` together
/// are refused first, as `text_source` does before it reads either.
fn read_text_keys<E: serde::de::Error>(value: &Value) -> Result<TextKeys, E> {
    let given = |k: &str| value.get(k).is_some_and(|v| !v.is_null());
    if given("text") && given("text_expression") {
        return Err(E::custom(whole("give `text` or `text_expression`, not both")));
    }
    serde_path_to_error::deserialize(value).map_err(|e| E::custom(located(&e)))
}

/// Make text in the sketch being edited: outlines that stay linked to their words and style, so a
/// later `sketch.edit_text` can change them. Give `text` or `text_expression`, and `at`.
#[derive(Debug)]
pub struct SketchTextParams(pub TextKeys);

impl<'de> Deserialize<'de> for SketchTextParams {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let value = Value::deserialize(d)?;
        // First, as the handler does.
        if value.get("at").is_none_or(Value::is_null) {
            return Err(D::Error::custom(whole(crate::cmd::AT_MUST)));
        }
        read_text_keys(&value).map(SketchTextParams)
    }
}

impl JsonSchema for SketchTextParams {
    fn schema_name() -> Cow<'static, str> {
        "SketchTextParams".into()
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        let mut schema = TextKeys::json_schema(generator);
        schema.insert("title".into(), "SketchTextParams".into());
        schema.insert(
            "description".into(),
            "Make text in the sketch being edited: outlines that stay linked to their words and style, so a later sketch.edit_text can change them. Give `text` or `text_expression`, and `at`."
                .into(),
        );
        add_properties(&mut schema, sketch_property());
        require(&mut schema, "at");
        schema.insert("anyOf".into(), json!([{"required": ["text"]}, {"required": ["text_expression"]}]));
        schema
    }
}

/// One text of `sketch.edit_text`: its link or one of its curves (`entity`), and the keys that
/// change.
#[derive(Debug)]
pub struct TextEdit {
    /// The text's link id.
    pub link: Option<String>,
    /// One of its curves, used when there is no `link`.
    pub entity: Option<String>,
    /// What changes.
    pub keys: TextKeys,
}

impl<'de> Deserialize<'de> for TextEdit {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let value = Value::deserialize(d)?;
        // `str_` reads a key that isn't text as left out.
        let name = |k: &str| value.get(k).and_then(Value::as_str).map(str::to_string);
        let (link, entity) = (name("link"), name("entity"));
        if link.is_none() && entity.is_none() {
            return Err(D::Error::custom(whole("give `link` or `entity`")));
        }
        Ok(TextEdit { link, entity, keys: read_text_keys(&value)? })
    }
}

/// The texts go into the sketch being edited whatever `sketch` says; the session reads it only to
/// report what the call `created`, so a call that names it still runs without a warning.
fn sketch_property() -> Value {
    json!({"sketch": {"description": "Only for the reply's `created`, which compares this sketch (default: the one being edited); the text always goes into the sketch being edited.", "type": ["integer", "string"]}})
}

fn edit_target_properties() -> Value {
    json!({
        "link": {"description": "The text's link id (the `link` the text's reply names).", "type": "string"},
        "entity": {"description": "One of the text's curves, by id, when there is no `link`.", "type": "string"}
    })
}

impl JsonSchema for TextEdit {
    fn schema_name() -> Cow<'static, str> {
        "TextEdit".into()
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        let mut schema = TextKeys::json_schema(generator);
        schema.insert("title".into(), "TextEdit".into());
        schema.insert("description".into(), "One text's change: the text by `link` or `entity`, and the keys to change; the rest is kept.".into());
        add_properties(&mut schema, edit_target_properties());
        schema.insert("anyOf".into(), json!([{"required": ["link"]}, {"required": ["entity"]}]));
        schema
    }
}

/// Change texts: one by `link` (or `entity`, one of its curves) with the keys to change, or
/// several at once by `edits`, the design rebuilt once, all or nothing. What is left out stays; a
/// number replaces an expression, and so does moving the text. With `edits`, the other keys of the
/// call (but `live`) are not read.
#[derive(Debug)]
pub struct EditTextParams {
    /// The several texts, when the call gives `edits`.
    pub edits: Option<Vec<TextEdit>>,
    /// The one text, when it does not.
    pub single: Option<TextEdit>,
    /// One frame of an interactive change.
    pub live: Option<bool>,
}

impl<'de> Deserialize<'de> for EditTextParams {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let value = Value::deserialize(d)?;
        // `live` takes effect only as `true`; anything else but a flag is a mistake.
        let live = match value.get("live") {
            None | Some(Value::Null) => None,
            Some(Value::Bool(b)) => Some(*b),
            Some(_) => return Err(D::Error::custom(whole("`live` must be true or false"))),
        };
        match value.get("edits") {
            None | Some(Value::Null) => {
                let single = TextEdit::deserialize(&value).map_err(|e| D::Error::custom(e.to_string()))?;
                Ok(EditTextParams { edits: None, single: Some(single), live })
            }
            Some(Value::Array(edits)) => {
                if edits.is_empty() || edits.len() > crate::cmd::MAX_TEXT_EDITS {
                    return Err(D::Error::custom(whole(format!("`edits` must hold 1 to {} edits", crate::cmd::MAX_TEXT_EDITS))));
                }
                let edits = edits
                    .iter()
                    .map(|e| serde_path_to_error::deserialize::<_, TextEdit>(e).map_err(|e| D::Error::custom(whole(parse_issue(&e).message))))
                    .collect::<Result<Vec<_>, _>>()?;
                Ok(EditTextParams { edits: Some(edits), single: None, live })
            }
            Some(_) => Err(D::Error::custom(whole("`edits` must be a list of edits"))),
        }
    }
}

impl JsonSchema for EditTextParams {
    fn schema_name() -> Cow<'static, str> {
        "EditTextParams".into()
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        let item = generator.subschema_for::<TextEdit>();
        let mut schema = TextKeys::json_schema(generator);
        schema.insert("title".into(), "EditTextParams".into());
        schema.insert(
            "description".into(),
            "Change texts: one by `link` (or `entity`, one of its curves) with the keys to change, or several at once by `edits`, the design rebuilt once, all or nothing. What is left out stays; a number replaces an expression, and so does moving the text. With `edits`, the other keys of the call (but `live`) are not read."
                .into(),
        );
        add_properties(&mut schema, edit_target_properties());
        add_properties(&mut schema, sketch_property());
        add_properties(
            &mut schema,
            json!({
                "edits": {"description": "Several texts changed together: each is `link` or `entity` with the keys to change.", "type": "array", "items": item, "minItems": 1, "maxItems": crate::cmd::MAX_TEXT_EDITS},
                "live": {"description": "One frame of an interactive change: the sketch is solved and shown, the features after it stay as they were until `sketch.drag_end`. A call with `live: true` is not checked against this schema yet.", "type": "boolean"}
            }),
        );
        schema.insert("anyOf".into(), json!([{"required": ["link"]}, {"required": ["entity"]}, {"required": ["edits"]}]));
        schema
    }
}

/// The expressions behind a text's numbers and words.
#[derive(Debug, Default, Serialize, JsonSchema)]
pub struct TextExpressions {
    /// `at`'s x.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub x: Option<String>,
    /// `at`'s y.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub y: Option<String>,
    /// The height.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub height: Option<String>,
    /// The angle.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub angle: Option<String>,
    /// The words (`text_expression`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub text: Option<String>,
}

/// One text made or changed.
#[derive(Debug, Serialize, JsonSchema)]
pub struct TextChange {
    /// The text's link id.
    pub link: String,
    /// The ids of its curves.
    pub curves: Vec<String>,
    /// The curve the text follows that became construction, a guide the letters stand on; null
    /// when none did.
    pub guide: Option<String>,
    /// The expressions the text keeps; absent when it keeps none.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub exprs: Option<TextExpressions>,
}

/// What `sketch.text` returns, and `sketch.edit_text` for one text.
#[derive(Debug, Serialize, JsonSchema)]
pub struct TextResult {
    #[serde(flatten)]
    pub change: TextChange,
    /// What it added: `{points, curves, constraints, dimensions}`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub created: Option<Value>,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

/// What `sketch.edit_text` returns for `edits`.
#[derive(Debug, Serialize, JsonSchema)]
pub struct TextEditsResult {
    /// Each edit's result, in order.
    pub edits: Vec<TextChange>,
    /// What it added: `{points, curves, constraints, dimensions}`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub created: Option<Value>,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

/// What `sketch.edit_text` returns: one text's result, or each edit's.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(untagged)]
pub enum EditTextResult {
    One(TextResult),
    Many(TextEditsResult),
}

#[cfg(test)]
#[path = "sketch_create_tests.rs"]
mod tests;