Skip to content

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

63.2 KB
Raw Blame
//! Contracts and result types for the commands in `cmd/browser.rs`.

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 solidcraft_doc::BrowserEntry;

use super::canvas::CanvasPlane;
use super::check::{located, whole};
use super::types::{FeatureCommon, LengthExpr, feature_common, present};

/// Repair a part the modelling kernel refuses, or an open part that should be a solid: faces
/// SMLib refuses on their own are rebuilt on their own surfaces (geometry unchanged), free edges
/// that pair up within `gap` are sewn (each sewn edge carries its own gap as its tolerance; the
/// body's and the other edges' stay), and with `patch_holes` the loops of free edges left (missing
/// faces) are patched and sewn in. One undoable feature; refused, with why, when nothing applies.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct RepairParams {
    /// The part (body name).
    pub body: String,
    /// The widest gap between two free edges that is sewn, more than 0 and at most 1 mm.
    /// Default: 0.2 mm.
    #[serde(default)]
    pub gap: Option<LengthExpr>,
    /// Patch each loop of free edges no pair explains (a missing face) and sew the patch in: the
    /// plane of the faces around it where they are all that plane, else a patch tangent to them
    /// (G1). Default: false (the reply offers the patches).
    #[serde(default)]
    pub patch_holes: Option<bool>,
    #[serde(flatten, deserialize_with = "feature_common")]
    pub common: FeatureCommon,
}

/// A face rebuilt on its own surface, or one SMLib still refuses.
#[derive(Debug, Serialize, JsonSchema)]
pub struct RepairFace {
    /// The face's index in the part's face order before the repair (from 0).
    pub face: usize,
    /// Its surface: plane, cylinder, cone, sphere, torus or freeform.
    pub surface: String,
    /// What SMLib said about it.
    pub why: String,
}

/// Two free edges sewn into one.
#[derive(Debug, Serialize, JsonSchema)]
pub struct RepairSewn {
    /// The faces on either side, by index before the repair.
    pub faces: [usize; 2],
    /// The widest distance between the two edges, mm.
    pub gap: f64,
    /// A point halfway along the gap, [x, y, z].
    pub at: [f64; 3],
}

/// A loop of free edges no pair explains: a missing face.
#[derive(Debug, Serialize, JsonSchema)]
pub struct RepairHole {
    /// The faces around it, by index before the repair.
    pub faces: Vec<usize>,
    /// g0 (a patch in the plane of the faces around it) or g1 (tangent to curved neighbours).
    pub continuity: String,
    /// The patch was made and sewn in.
    pub patched: bool,
    /// Why it was not, when `patch_holes` asked for it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub why: Option<String>,
    /// The Patch that fills it: `{command: "surface.patch", params}`.
    pub patch: Value,
}

/// What the repair did, face by face.
#[derive(Debug, Serialize, JsonSchema)]
pub struct RepairDone {
    pub rebuilt: Vec<RepairFace>,
    /// Faces SMLib refuses that could not be rebuilt (the part may still be taken as a whole).
    pub refused: Vec<RepairFace>,
    pub sewn: Vec<RepairSewn>,
    pub holes: Vec<RepairHole>,
    /// Faces before and after.
    pub faces: [usize; 2],
    /// The largest edge tolerance before and after, mm.
    pub largest_edge_tolerance: [f64; 2],
    /// The part is a closed solid now.
    pub closed: bool,
    /// The modelling kernel takes the part now.
    pub modelling: bool,
    /// Its volume, mm³, when it is a closed solid.
    pub volume: Option<f64>,
}

/// What `body.repair` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct RepairResult {
    /// The new feature's id.
    pub feature: u64,
    /// The new feature's name.
    pub name: String,
    /// Every body after the feature.
    pub bodies: Vec<String>,
    /// The bodies the feature made.
    pub created_bodies: Vec<String>,
    /// Bodies that were there before and now have other geometry.
    pub changed_bodies: Vec<String>,
    /// Bodies that are gone.
    pub removed_bodies: Vec<String>,
    /// A warning from the evaluation (a hole left open), or `null`.
    pub warning: Option<String>,
    /// How long the feature took to evaluate, in milliseconds.
    pub ms: Option<f64>,
    pub repair: RepairDone,
    /// 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 units a design can show lengths in.
pub const DESIGN_UNITS: [&str; 5] = ["mm", "cm", "m", "in", "ft"];

/// One of [`DESIGN_UNITS`], with `document.units`' message for anything else.
#[derive(Clone, Debug, PartialEq)]
pub struct DesignUnits(pub String);

impl<'de> Deserialize<'de> for DesignUnits {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::String(u) if DESIGN_UNITS.contains(&u.as_str()) => Ok(DesignUnits(u)),
            _ => Err(D::Error::custom("must be mm, cm, m, in or ft")),
        }
    }
}

impl JsonSchema for DesignUnits {
    fn schema_name() -> Cow<'static, str> {
        "DesignUnits".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({"description": "The units the design shows lengths in.", "type": "string", "enum": DESIGN_UNITS})
    }
}

/// Change the units the design shows lengths in, and reads a bare number in. Values keep their
/// meaning: a unit-less parameter holding a bare number that lengths read is written with the
/// old unit (`10` becomes `10 mm`) when that keeps those lengths where they were. One undo
/// step; the same units again changes nothing.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct DocumentUnitsParams {
    /// The design's new units: mm, cm, m, in or ft.
    pub units: DesignUnits,
}

/// What `document.units` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct DocumentUnitsResult {
    /// The design's units now.
    pub units: String,
    /// The unit-less parameters now written with the old unit, so the lengths that read them
    /// stay where they were. Empty when nothing needed it, or the units didn't change.
    pub kept: Vec<String>,
    /// 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>,
}

// ---- Browser folders and Rename Body (#12276) ----
//
// 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. Whether a group, component, placement, joint,
// feature or body exists stays the handler's to check, and so do the keys that exclude one
// another. A key the handler reads only as text, a number or a flag, and otherwise takes as
// absent, is a plain optional field: the contract is the stricter of the two. A key the type
// has optional but the handler can't do without is required in the schema (`require`), so that
// the handler's own message, not "is required", is what a call that leaves it out gets.

/// The most keys, entries or paths a browser list may name, as the handlers cap them.
const MAX_LIST: usize = 10_000;
/// The longest item key, in bytes.
const MAX_KEY_BYTES: usize = 256;
/// The deepest placement path, in occurrence ids.
const MAX_PATH: usize = 64;
/// The longest group or body name, in bytes.
const MAX_NAME_BYTES: usize = 128;

/// The folders the browser lists items in, which a group or a move is in.
const FOLDERS: [&str; 3] = ["bodies", "sketches", "construction"];
/// The folders `browser.visibility` takes whole.
const VISIBILITY_FOLDERS: [&str; 6] = ["bodies", "sketches", "construction", "origin", "joints", "all"];

/// Adds each of `keys` to the schema's `required` list.
fn require(schema: &mut Schema, keys: &[&str]) {
    let mut required: Vec<Value> = schema.get("required").and_then(Value::as_array).cloned().unwrap_or_default();
    for key in keys {
        if !required.iter().any(|k| k == key) {
            required.push((*key).into());
        }
    }
    schema.insert("required".into(), Value::Array(required));
}

fn group_required(schema: &mut Schema) {
    require(schema, &["group"]);
}

fn group_and_name_required(schema: &mut Schema) {
    require(schema, &["group", "name"]);
}

fn body_and_name_required(schema: &mut Schema) {
    require(schema, &["body", "name"]);
}

fn folder_and_items_required(schema: &mut Schema) {
    require(schema, &["folder", "items"]);
}

fn folder_required(schema: &mut Schema) {
    require(schema, &["folder"]);
}

fn visible_required(schema: &mut Schema) {
    require(schema, &["visible"]);
}

/// A browser group's id, as `cmd/browser.rs` reads one: a non-negative whole number.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct GroupId(pub u64);

impl<'de> Deserialize<'de> for GroupId {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        Value::deserialize(d)?.as_u64().map(GroupId).ok_or_else(|| D::Error::custom("must be a group id"))
    }
}

impl JsonSchema for GroupId {
    fn schema_name() -> Cow<'static, str> {
        "GroupId".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({"description": "A browser group's id (see `browser.group`).", "type": "integer", "minimum": 0})
    }
}

/// `group` as `group_id` reads it: given, `null` included, a group id.
fn some_group<'de, D: Deserializer<'de>>(d: D) -> Result<Option<GroupId>, D::Error> {
    GroupId::deserialize(d).map(Some)
}

/// One of the three browser folders a group or an item list is in.
#[derive(Clone, Debug, PartialEq)]
pub struct BrowserFolder(pub String);

impl<'de> Deserialize<'de> for BrowserFolder {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::String(f) if FOLDERS.contains(&f.as_str()) => Ok(BrowserFolder(f)),
            _ => Err(D::Error::custom(whole("`folder` must be bodies, sketches or construction"))),
        }
    }
}

impl JsonSchema for BrowserFolder {
    fn schema_name() -> Cow<'static, str> {
        "BrowserFolder".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({"description": "A browser folder: bodies, sketches or construction.", "type": "string", "enum": FOLDERS})
    }
}

/// `browser.order`'s folder: one of the three, or `components`, the placed sub-components.
#[derive(Clone, Debug, PartialEq)]
pub struct OrderFolder(pub String);

impl<'de> Deserialize<'de> for OrderFolder {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::String(f) if f == "components" || FOLDERS.contains(&f.as_str()) => Ok(OrderFolder(f)),
            _ => Err(D::Error::custom(whole("`folder` must be bodies, sketches or construction"))),
        }
    }
}

impl JsonSchema for OrderFolder {
    fn schema_name() -> Cow<'static, str> {
        "OrderFolder".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({
            "description": "A browser folder: bodies, sketches, construction or components.",
            "type": "string",
            "enum": ["bodies", "sketches", "construction", "components"]
        })
    }
}

/// A group's name as `browser.group` reads it: surrounding spaces are cut; nothing left means
/// the default name.
#[derive(Clone, Debug, PartialEq)]
pub struct GroupName(pub String);

impl<'de> Deserialize<'de> for GroupName {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::String(n) if n.trim().len() > MAX_NAME_BYTES => Err(D::Error::custom(whole("`name` is too long"))),
            Value::String(n) => Ok(GroupName(n)),
            _ => Err(D::Error::custom("must be text")),
        }
    }
}

impl JsonSchema for GroupName {
    fn schema_name() -> Cow<'static, str> {
        "GroupName".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({"description": "A name of at most 128 bytes once surrounding spaces are cut.", "type": "string"})
    }
}

/// A name of 1 to 128 bytes once surrounding spaces are cut, as `browser.rename_group` and
/// `body.rename` read `name`.
#[derive(Clone, Debug, PartialEq)]
pub struct NewName(pub String);

impl<'de> Deserialize<'de> for NewName {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::String(n) if !n.trim().is_empty() && n.trim().len() <= MAX_NAME_BYTES => Ok(NewName(n)),
            _ => Err(D::Error::custom(whole("`name` must be 1…128 characters"))),
        }
    }
}

impl JsonSchema for NewName {
    fn schema_name() -> Cow<'static, str> {
        "NewName".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({"description": "Text of 1 to 128 bytes once surrounding spaces are cut.", "type": "string"})
    }
}

/// `name` for the commands that can't do without it: given, `null` included, a [`NewName`].
fn some_new_name<'de, D: Deserializer<'de>>(d: D) -> Result<Option<NewName>, D::Error> {
    NewName::deserialize(d).map(Some)
}

/// The name of a body, as `body.rename` reads `body`.
#[derive(Clone, Debug, PartialEq)]
pub struct BodyName(pub String);

impl<'de> Deserialize<'de> for BodyName {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::String(n) => Ok(BodyName(n)),
            _ => Err(D::Error::custom(whole("`body` must be a body name"))),
        }
    }
}

impl JsonSchema for BodyName {
    fn schema_name() -> Cow<'static, str> {
        "BodyName".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({"description": "A body's name. A placed copy's name (`KB (K:2)`) means the body it shows.", "type": "string"})
    }
}

fn some_body<'de, D: Deserializer<'de>>(d: D) -> Result<Option<BodyName>, D::Error> {
    BodyName::deserialize(d).map(Some)
}

/// What `entries` in `cmd/browser.rs` reads of a list of groups (numbers) and item keys
/// (strings): at most 10000, no key empty or over 256 bytes. `key` names the parameter in the
/// messages.
fn browser_entries(value: Value, key: &str) -> Result<Vec<BrowserEntry>, String> {
    let list = match value {
        Value::Array(a) => a
            .into_iter()
            .map(|x| match x {
                Value::String(s) => Some(BrowserEntry::Item(s)),
                _ => x.as_u64().map(BrowserEntry::Group),
            })
            .collect::<Option<Vec<_>>>(),
        _ => None,
    };
    let list = list.ok_or_else(|| whole(format!("`{key}` must be a list of item keys (strings) and group ids (numbers)")))?;
    if list.len() > MAX_LIST || list.iter().any(|e| e.as_item().is_some_and(|k| k.is_empty() || k.len() > MAX_KEY_BYTES)) {
        return Err(whole(format!("`{key}` has bad keys")));
    }
    Ok(list)
}

/// `browser.move`'s `items`: item keys and group ids, at least one.
#[derive(Clone, Debug, PartialEq)]
pub struct MovedEntries(pub Vec<BrowserEntry>);

impl<'de> Deserialize<'de> for MovedEntries {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let list = browser_entries(Value::deserialize(d)?, "items").map_err(D::Error::custom)?;
        if list.is_empty() { Err(D::Error::custom(whole("`items` must list item keys or group ids"))) } else { Ok(MovedEntries(list)) }
    }
}

/// `browser.order`'s `order`: item keys and top-level group ids, in display order; none clears
/// the folder's order.
#[derive(Clone, Debug, PartialEq)]
pub struct OrderEntries(pub Vec<BrowserEntry>);

impl<'de> Deserialize<'de> for OrderEntries {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        browser_entries(Value::deserialize(d)?, "order").map(OrderEntries).map_err(D::Error::custom)
    }
}

/// `browser.group`'s `items`: item keys, no group ids.
#[derive(Clone, Debug, PartialEq)]
pub struct GroupedItems(pub Vec<BrowserEntry>);

impl<'de> Deserialize<'de> for GroupedItems {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let list = browser_entries(Value::deserialize(d)?, "items").map_err(D::Error::custom)?;
        if list.iter().any(|e| e.as_item().is_none()) {
            Err(D::Error::custom(whole("`items` are item keys: move groups with browser.move")))
        } else {
            Ok(GroupedItems(list))
        }
    }
}

fn entries_schema(description: &str, group_ids: bool, min_items: u32) -> Schema {
    let item = json!({"type": "string", "minLength": 1, "maxLength": MAX_KEY_BYTES});
    let entry = if group_ids { json!({"anyOf": [item, {"type": "integer", "minimum": 0}]}) } else { item };
    json_schema!({"description": description, "type": "array", "items": entry, "minItems": min_items, "maxItems": MAX_LIST})
}

impl JsonSchema for MovedEntries {
    fn schema_name() -> Cow<'static, str> {
        "MovedEntries".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        entries_schema("Item keys (strings) and group ids (numbers); a number is always a group.", true, 1)
    }
}

impl JsonSchema for OrderEntries {
    fn schema_name() -> Cow<'static, str> {
        "OrderEntries".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        entries_schema("Item keys (strings) and top-level group ids (numbers); a number is always a group.", true, 0)
    }
}

impl JsonSchema for GroupedItems {
    fn schema_name() -> Cow<'static, str> {
        "GroupedItems".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        entries_schema("Item keys (strings).", false, 0)
    }
}

/// Where `browser.move` puts items: before an item key or a group id.
#[derive(Clone, Debug, PartialEq)]
pub struct BeforeEntry(pub BrowserEntry);

impl<'de> Deserialize<'de> for BeforeEntry {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::String(k) => Ok(BeforeEntry(BrowserEntry::Item(k))),
            v => v.as_u64().map(|id| BeforeEntry(BrowserEntry::Group(id))).ok_or_else(|| D::Error::custom("must be an item key or a group id")),
        }
    }
}

impl JsonSchema for BeforeEntry {
    fn schema_name() -> Cow<'static, str> {
        "BeforeEntry".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({"description": "An item key (text) or a group id (a number).", "anyOf": [{"type": "string"}, {"type": "integer", "minimum": 0}]})
    }
}

/// An item key or a group id in a reply.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(untagged)]
pub enum EntryKey {
    /// A group, by id.
    Group(u64),
    /// An item, by key.
    Item(String),
}

/// Make a group in a Browser folder, of the items given or empty. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct BrowserGroupParams {
    /// The folder: bodies, sketches or construction. Needed unless `parent` gives it.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "BrowserFolder")]
    pub folder: Option<BrowserFolder>,
    /// The component whose folder it is. Default: 0, the design.
    #[serde(default)]
    pub component: Option<u64>,
    /// The group the new one nests in, which gives it its component and folder (at most 8
    /// levels).
    #[serde(default)]
    pub parent: Option<GroupId>,
    /// The group's name, at most 128 bytes. Default: "Group" and the next number in the folder.
    #[serde(default)]
    pub name: Option<GroupName>,
    /// The items to put in it, by key; they leave the other groups they were in.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "GroupedItems")]
    pub items: Option<GroupedItems>,
}

/// What `browser.group` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct BrowserGroupMade {
    /// The new group's id.
    pub group: u64,
    pub name: String,
    /// The group it is in, or `null` at the folder's top level.
    pub parent: Option<u64>,
    /// 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>,
}

/// Remove a group: its items and child groups go up to the group that holds it, or the folder,
/// in the place the group had. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = group_required)]
pub struct BrowserUngroupParams {
    // Required in the schema (`group_required`), optional in the type: left out, the handler
    // refuses it with its own message.
    #[serde(default, deserialize_with = "some_group", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "GroupId")]
    pub group: Option<GroupId>,
}

/// What `browser.ungroup` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct BrowserUngrouped {
    /// The group that is gone.
    pub group: u64,
    /// 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>,
}

/// Rename a Browser group. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = group_and_name_required)]
pub struct BrowserRenameGroupParams {
    #[serde(default, deserialize_with = "some_group", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "GroupId")]
    pub group: Option<GroupId>,
    /// The new name, 1 to 128 characters once surrounding spaces are cut.
    #[serde(default, deserialize_with = "some_new_name", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "NewName")]
    pub name: Option<NewName>,
}

/// What `browser.rename_group` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct BrowserGroupRenamed {
    pub group: u64,
    /// The name now, without surrounding spaces.
    pub name: String,
    /// 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>,
}

/// Move items and groups in a Browser folder: into a group or to the folder's top level, before
/// an item or group or at the end. A group can't go into itself or past 8 levels. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = folder_and_items_required)]
pub struct BrowserMoveParams {
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "BrowserFolder")]
    pub folder: Option<BrowserFolder>,
    /// The component whose folder it is. Default: 0, the design.
    #[serde(default)]
    pub component: Option<u64>,
    /// What to move: item keys (strings) and group ids (numbers), at least one.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "MovedEntries")]
    pub items: Option<MovedEntries>,
    /// The group to move them into. Default: the folder's top level.
    #[serde(default)]
    pub group: Option<GroupId>,
    /// Put them before this item key or group id, in the list they go into. Default: the end.
    #[serde(default)]
    pub before: Option<BeforeEntry>,
}

/// What `browser.move` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct BrowserMoved {
    /// What was moved, as given.
    #[schemars(with = "Vec<EntryKey>")]
    pub items: Vec<BrowserEntry>,
    /// The group they went into, or `null` for the folder's top level.
    pub group: Option<u64>,
    /// 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>,
}

/// Set the display order of a Browser folder. An item that sits in a group belongs to the
/// group's list only. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = folder_required)]
pub struct BrowserOrderParams {
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "OrderFolder")]
    pub folder: Option<OrderFolder>,
    /// The component whose folder it is. Default: 0, the design.
    #[serde(default)]
    pub component: Option<u64>,
    /// The display order: item keys (strings) and top-level group ids (numbers); for
    /// `components`, the ids of the components placed in it. Empty or left out: the folder goes
    /// back to its default order.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "OrderEntries")]
    pub order: Option<OrderEntries>,
}

/// What `browser.order` returns: nothing but the warnings.
#[derive(Debug, Serialize, JsonSchema)]
pub struct BrowserOrdered {
    /// 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 list of item keys (strings, or numbers read as text), as `keys` in `cmd/browser.rs` reads
/// one: at most 10000, no key empty or over 256 bytes.
fn item_keys(value: Value, key: &str) -> Result<Vec<Value>, String> {
    let list = match value {
        Value::Array(a) if a.iter().all(|x| x.is_string() || x.as_u64().is_some()) => a,
        _ => return Err(whole(format!("`{key}` must be a list of item keys"))),
    };
    let bad_key = |x: &Value| x.as_str().is_some_and(|k| k.is_empty() || k.len() > MAX_KEY_BYTES);
    if list.len() > MAX_LIST || list.iter().any(bad_key) { Err(whole(format!("`{key}` has bad keys"))) } else { Ok(list) }
}

/// `browser.visibility`'s `items`: sketches, bodies, construction items, joints or origin items.
#[derive(Clone, Debug, PartialEq)]
pub struct ShownItems(pub Vec<Value>);

impl<'de> Deserialize<'de> for ShownItems {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        item_keys(Value::deserialize(d)?, "items").map(ShownItems).map_err(D::Error::custom)
    }
}

/// `browser.visibility`'s `features`: feature ids or names.
#[derive(Clone, Debug, PartialEq)]
pub struct ShownFeatures(pub Vec<Value>);

impl<'de> Deserialize<'de> for ShownFeatures {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        item_keys(Value::deserialize(d)?, "features").map(ShownFeatures).map_err(D::Error::custom)
    }
}

fn keys_schema(description: &str) -> Schema {
    json_schema!({
        "description": description,
        "type": "array",
        "items": {"anyOf": [{"type": "string", "minLength": 1, "maxLength": MAX_KEY_BYTES}, {"type": "integer", "minimum": 0}]},
        "maxItems": MAX_LIST
    })
}

impl JsonSchema for ShownItems {
    fn schema_name() -> Cow<'static, str> {
        "ShownItems".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        keys_schema("Sketches (id or name), bodies, construction items, joints or origin items (O, X, Y, Z, XY, XZ, YZ), by name.")
    }
}

impl JsonSchema for ShownFeatures {
    fn schema_name() -> Cow<'static, str> {
        "ShownFeatures".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        keys_schema("Feature ids or names.")
    }
}

/// `browser.visibility`'s `joints`: one to 10000 joint ids or names.
#[derive(Clone, Debug, PartialEq)]
pub struct ShownJoints(pub Vec<Value>);

impl<'de> Deserialize<'de> for ShownJoints {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let list = match Value::deserialize(d)? {
            Value::Array(a) if !a.is_empty() && a.len() <= MAX_LIST => a,
            _ => return Err(D::Error::custom(whole("`joints` must list 1..10000 joint ids or names"))),
        };
        if list.iter().all(|j| j.is_number() || j.is_string()) {
            Ok(ShownJoints(list))
        } else {
            Err(D::Error::custom(whole("`joint` must be an id or a name")))
        }
    }
}

impl JsonSchema for ShownJoints {
    fn schema_name() -> Cow<'static, str> {
        "ShownJoints".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({
            "description": "Joint ids (numbers) or names.",
            "type": "array",
            "items": {"type": ["number", "string"]},
            "minItems": 1,
            "maxItems": MAX_LIST
        })
    }
}

/// A placement's path, occurrence ids from the outermost down, as the handlers read one: `min`
/// to 64 whole numbers.
fn occurrence_ids(value: &Value, min: usize) -> Option<Vec<u64>> {
    value.as_array().filter(|a| a.len() >= min && a.len() <= MAX_PATH).and_then(|a| a.iter().map(Value::as_u64).collect::<Option<Vec<_>>>())
}

fn path_schema(description: &str, min_items: u32) -> Schema {
    json_schema!({"description": description, "type": "array", "items": {"type": "integer", "minimum": 0}, "minItems": min_items, "maxItems": MAX_PATH})
}

/// The path of one placement for `browser.visibility`'s `path`: at most 64 occurrence ids.
#[derive(Clone, Debug, PartialEq)]
pub struct PlacementPath(pub Vec<u64>);

impl<'de> Deserialize<'de> for PlacementPath {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        occurrence_ids(&Value::deserialize(d)?, 0)
            .map(PlacementPath)
            .ok_or_else(|| D::Error::custom(whole("`path` must list at most 64 occurrence ids")))
    }
}

impl JsonSchema for PlacementPath {
    fn schema_name() -> Cow<'static, str> {
        "PlacementPath".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        path_schema("A placement, by the occurrence ids from the design down.", 0)
    }
}

/// `browser.expand_all` and `browser.collapse_all`'s `path`: 1 to 64 occurrence ids.
#[derive(Clone, Debug, PartialEq)]
pub struct FoldPath(pub Vec<u64>);

impl<'de> Deserialize<'de> for FoldPath {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        occurrence_ids(&Value::deserialize(d)?, 1).map(FoldPath).ok_or_else(|| D::Error::custom(whole("`path` must list 1..64 occurrence ids")))
    }
}

impl JsonSchema for FoldPath {
    fn schema_name() -> Cow<'static, str> {
        "FoldPath".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        path_schema("A placement, by the occurrence ids from the design down.", 1)
    }
}

/// `browser.visibility`'s `paths`: one to 10000 placements, each 1 to 64 occurrence ids.
#[derive(Clone, Debug, PartialEq)]
pub struct PlacementPaths(pub Vec<Vec<u64>>);

impl<'de> Deserialize<'de> for PlacementPaths {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let list = match Value::deserialize(d)? {
            Value::Array(a) if !a.is_empty() && a.len() <= MAX_LIST => a,
            _ => return Err(D::Error::custom(whole("paths must list 1..10000 occurrence paths"))),
        };
        list.iter()
            .map(|p| occurrence_ids(p, 1))
            .collect::<Option<Vec<_>>>()
            .map(PlacementPaths)
            .ok_or_else(|| D::Error::custom(whole("each path must list 1..64 occurrence ids")))
    }
}

impl JsonSchema for PlacementPaths {
    fn schema_name() -> Cow<'static, str> {
        "PlacementPaths".into()
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        json_schema!({
            "description": "Placements, each by the occurrence ids from the design down; each with its descendants.",
            "type": "array",
            "items": generator.subschema_for::<FoldPath>(),
            "minItems": 1,
            "maxItems": MAX_LIST
        })
    }
}

/// A browser folder or group key, as `tree_folder_key` reads one.
#[derive(Clone, Debug, PartialEq)]
pub struct TreeFolderKeys(pub Vec<String>);

impl<'de> Deserialize<'de> for TreeFolderKeys {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let list = match Value::deserialize(d)? {
            Value::Array(a) if !a.is_empty() && a.len() <= MAX_LIST => a,
            _ => return Err(D::Error::custom(whole("`tree_folders` must list 1..10000 browser folder or group keys"))),
        };
        list.into_iter()
            .map(|k| match k {
                Value::String(k) if crate::cmd::browser::tree_folder_key(&k) => Some(k),
                _ => None,
            })
            .collect::<Option<Vec<_>>>()
            .map(TreeFolderKeys)
            .ok_or_else(|| {
                D::Error::custom(whole("a browser folder or group key is `<c0 | o:ids>/<folder | g<group id>>`, such as `c0/bodies` or `o:4/g7`"))
            })
    }
}

impl JsonSchema for TreeFolderKeys {
    fn schema_name() -> Cow<'static, str> {
        "TreeFolderKeys".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({
            "description": "Browser folder or group keys: `c0` (the design) or `o:` and the placement's occurrence ids joined by `/`, then `/bodies`, `/sketches`, `/construction`, `/joints`, `/canvases`, `/point_clouds` or `/g` and a group id.",
            "type": "array",
            "items": {"type": "string", "maxLength": 2048},
            "minItems": 1,
            "maxItems": MAX_LIST
        })
    }
}

/// A folder `browser.visibility` shows or hides whole.
#[derive(Clone, Debug, PartialEq)]
pub struct VisibilityFolder(pub String);

impl<'de> Deserialize<'de> for VisibilityFolder {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::String(f) if VISIBILITY_FOLDERS.contains(&f.as_str()) => Ok(VisibilityFolder(f)),
            Value::String(f) => Err(D::Error::custom(whole(format!("unknown folder `{f}` (bodies, sketches, construction, origin, joints, all)")))),
            _ => Err(D::Error::custom("must be bodies, sketches, construction, origin, joints or all")),
        }
    }
}

impl JsonSchema for VisibilityFolder {
    fn schema_name() -> Cow<'static, str> {
        "VisibilityFolder".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({"description": "A folder, whole: bodies, sketches, construction, origin, joints or all.", "type": "string", "enum": VISIBILITY_FOLDERS})
    }
}

/// `visible`: true or false.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Visible(pub bool);

impl<'de> Deserialize<'de> for Visible {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::Bool(b) => Ok(Visible(b)),
            _ => Err(D::Error::custom(whole("`visible` must be true or false"))),
        }
    }
}

impl JsonSchema for Visible {
    fn schema_name() -> Cow<'static, str> {
        "Visible".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({"description": "true to show, false to hide.", "type": "boolean"})
    }
}

fn some_visible<'de, D: Deserializer<'de>>(d: D) -> Result<Option<Visible>, D::Error> {
    Visible::deserialize(d).map(Some)
}

/// Show or hide what is in the Browser: name one kind of target (`items`, `joints`, `features`,
/// `folder`, `tree_folders` or `paths`). Saved with the design and undone like any other
/// change; the camera is not. With `isolate`, everything else is hidden.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = visible_required)]
pub struct BrowserVisibilityParams {
    // Required in the schema (`visible_required`), optional in the type, as `group` above.
    #[serde(default, deserialize_with = "some_visible", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "Visible")]
    pub visible: Option<Visible>,
    /// Sketches, bodies, construction items, joints or origin items, by key. With `isolate` and
    /// `visible: true`: the bodies to keep.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "ShownItems")]
    pub items: Option<ShownItems>,
    /// Joints, by id or name: their glyphs (they still constrain and move parts).
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "ShownJoints")]
    pub joints: Option<ShownJoints>,
    /// Features, by id or name: the bodies they made. Sketches go in `items`.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "ShownFeatures")]
    pub features: Option<ShownFeatures>,
    /// With `features`: only the bodies of this placement, which must be one of the features'
    /// component.
    #[serde(default)]
    pub path: Option<PlacementPath>,
    /// All of a kind: bodies, sketches, construction, origin, joints or all. Showing also shows
    /// the browser folders and groups that hold it, and `all` takes in the occurrence hides.
    #[serde(default)]
    pub folder: Option<VisibilityFolder>,
    /// The folders or groups themselves, by tree key; their items keep their own state.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "TreeFolderKeys")]
    pub tree_folders: Option<TreeFolderKeys>,
    /// Exact placements and their descendants, each by its occurrence ids.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "PlacementPaths")]
    pub paths: Option<PlacementPaths>,
    /// With `paths`, or `items` of bodies, and `visible: true`: show only those and hide
    /// everything else, other placements as placements. Default: false.
    #[serde(default)]
    pub isolate: Option<bool>,
}

/// What the browser hides and shows, as the design saves it.
#[derive(Debug, Serialize, JsonSchema)]
pub struct VisibilityState {
    /// Bodies hidden, by name.
    pub hidden_bodies: Vec<String>,
    /// Placements hidden with all their descendants, by occurrence path.
    pub hidden_occurrences: Vec<Vec<u64>>,
    /// Origin items and construction geometry hidden, by name.
    pub hidden_origin: Vec<String>,
    /// Sketches hidden, by feature id.
    pub hidden_sketches: Vec<u64>,
    /// Finished sketches shown although a feature uses them, by feature id.
    pub shown_sketches: Vec<u64>,
    /// Joints whose glyphs are hidden, by id. Present when there are any.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub hidden_joints: Vec<u64>,
    /// Whether the Origin folder is hidden. Present when set.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub origin_hidden: Option<bool>,
    /// Sketches whose closed profiles are not shaded, by feature id. Present when there are any.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub hidden_profiles: Vec<u64>,
    /// Sketches whose dimensions are shown, by feature id. Present when there are any.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub shown_dimensions: Vec<u64>,
    /// Bodies locked in the browser, by name. Present when there are any.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub locked_bodies: Vec<String>,
    /// Browser folders and groups hidden themselves, by tree key. Present when there are any.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub hidden_folders: Vec<String>,
}

impl From<&solidcraft_doc::Visibility> for VisibilityState {
    fn from(v: &solidcraft_doc::Visibility) -> Self {
        VisibilityState {
            hidden_bodies: v.hidden_bodies.clone(),
            hidden_occurrences: v.hidden_occurrences.clone(),
            hidden_origin: v.hidden_origin.clone(),
            hidden_sketches: v.hidden_sketches.clone(),
            shown_sketches: v.shown_sketches.clone(),
            hidden_joints: v.hidden_joints.clone(),
            origin_hidden: v.origin_hidden,
            hidden_profiles: v.hidden_profiles.clone(),
            shown_dimensions: v.shown_dimensions.clone(),
            locked_bodies: v.locked_bodies.clone(),
            hidden_folders: v.hidden_folders.clone(),
        }
    }
}

/// What an isolate kept.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(untagged)]
pub enum Isolated {
    /// The bodies kept, by name (`items`).
    Bodies(Vec<String>),
    /// The placements kept, by occurrence path (`paths`).
    Paths(Vec<Vec<u64>>),
}

/// What `browser.visibility` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct BrowserVisibilityResult {
    /// What was asked for.
    pub visible: bool,
    /// How many targets were changed. Not given by an isolate.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub changed: Option<usize>,
    /// What an isolate kept. Only given by an isolate.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub isolated: Option<Isolated>,
    /// What is hidden and shown now.
    pub visibility: VisibilityState,
    /// 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 component id `browser.expand_all` and `browser.collapse_all` read: a whole number.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct FoldComponent(pub u64);

impl<'de> Deserialize<'de> for FoldComponent {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        Value::deserialize(d)?.as_u64().map(FoldComponent).ok_or_else(|| D::Error::custom(whole("`component` must be a component id")))
    }
}

impl JsonSchema for FoldComponent {
    fn schema_name() -> Cow<'static, str> {
        "FoldComponent".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({"description": "A component's id; 0 is the design.", "type": "integer", "minimum": 0})
    }
}

/// Open every row of the Browser below a row (`browser.expand_all`) or close them, the row
/// itself staying open (`browser.collapse_all`). Display only: not saved with the design and not
/// an undo step. Give `path` or `component`, not both; neither takes the whole tree.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct BrowserFoldParams {
    /// A placement and its descendants, by occurrence ids (1 to 64).
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "FoldPath")]
    pub path: Option<FoldPath>,
    /// A component's own folders; 0 is the whole tree.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "FoldComponent")]
    pub component: Option<FoldComponent>,
}

/// What `browser.expand_all` and `browser.collapse_all` return: which Browser rows start open
/// and which closed.
#[derive(Debug, Serialize, JsonSchema)]
pub struct BrowserFoldResult {
    /// True after `browser.expand_all`, false after `browser.collapse_all`.
    pub open: bool,
    /// Tree keys of the rows that start open, sorted.
    pub open_by_default: Vec<String>,
    /// Tree keys of the rows that start closed (Origin, Named Views, Features…), sorted.
    pub closed_by_default: Vec<String>,
    /// 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>,
}

/// Rename a body; the features that use it follow. A placed copy's name means the body it shows.
/// One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = body_and_name_required)]
pub struct BodyRenameParams {
    // Required in the schema (`body_and_name_required`), optional in the type, as `group` above.
    #[serde(default, deserialize_with = "some_body", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "BodyName")]
    pub body: Option<BodyName>,
    /// The new name, 1 to 128 characters once surrounding spaces are cut; no other body may have it.
    #[serde(default, deserialize_with = "some_new_name", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "NewName")]
    pub name: Option<NewName>,
}

/// What `body.rename` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct BodyRenamed {
    /// The body's name before (the body a placed copy's name shows).
    pub body: String,
    /// Its name now, without surrounding spaces.
    pub name: String,
    /// 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>,
}

// ---- Named views and Redefine Sketch (#12499) ----
//
// As above: each key reads as its handler reads it and fails with the handler's message. A key
// the handler can't do without is optional in the type and required in the schema, so the
// handler's own message is what a call that leaves it out gets. Whether a view or a sketch
// exists, and whether a plane or a face can be found, stays the handler's to check.

fn view_required(schema: &mut Schema) {
    require(schema, &["view"]);
}

fn view_and_name_required(schema: &mut Schema) {
    require(schema, &["view", "name"]);
}

fn camera_required(schema: &mut Schema) {
    require(schema, &["camera"]);
}

fn sketch_and_plane_required(schema: &mut Schema) {
    require(schema, &["sketch", "plane"]);
}

/// A named view, as `view.rename` and `view.delete` read `view`: text.
#[derive(Clone, Debug, PartialEq)]
pub struct ViewKey(pub String);

impl<'de> Deserialize<'de> for ViewKey {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::String(n) => Ok(ViewKey(n)),
            _ => Err(D::Error::custom(whole("`view` must be a view name"))),
        }
    }
}

impl JsonSchema for ViewKey {
    fn schema_name() -> Cow<'static, str> {
        "ViewKey".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({"description": "A named view's name.", "type": "string"})
    }
}

fn some_view<'de, D: Deserializer<'de>>(d: D) -> Result<Option<ViewKey>, D::Error> {
    ViewKey::deserialize(d).map(Some)
}

/// The name `view.save` gives a view: at most 128 bytes once surrounding spaces are cut; nothing
/// left means the next free "Named View" number.
#[derive(Clone, Debug, PartialEq)]
pub struct SavedViewName(pub String);

impl<'de> Deserialize<'de> for SavedViewName {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::String(n) if n.trim().len() > MAX_NAME_BYTES => Err(D::Error::custom(whole("`name` is too long"))),
            Value::String(n) => Ok(SavedViewName(n)),
            _ => Err(D::Error::custom("must be text")),
        }
    }
}

impl JsonSchema for SavedViewName {
    fn schema_name() -> Cow<'static, str> {
        "SavedViewName".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({"description": "A name of at most 128 bytes once surrounding spaces are cut.", "type": "string"})
    }
}

/// The point a saved camera looks at, as the schemas of the view commands give it.
fn target_schema() -> Value {
    json!({
        "description": "The point the camera looks at, in mm: [x, y, z].",
        "type": "array",
        "items": {"type": "number"},
        "minItems": 3,
        "maxItems": 3
    })
}

/// The camera `view.save` keeps, as the handler reads it: finite numbers and a positive
/// distance. A `name` inside it is replaced by the call's `name`.
#[derive(Clone, Debug, PartialEq)]
pub struct ViewCamera(pub solidcraft_doc::NamedView);

impl<'de> Deserialize<'de> for ViewCamera {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        crate::cmd::browser::saved_view_form(&Value::deserialize(d)?).map(ViewCamera).map_err(|why| D::Error::custom(whole(why)))
    }
}

impl JsonSchema for ViewCamera {
    fn schema_name() -> Cow<'static, str> {
        "ViewCamera".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({
            "description": "An orbit camera. Angles are in radians, about the up axis.",
            "type": "object",
            "properties": {
                "target": target_schema(),
                "yaw": {"description": "Turn about the up axis; 0 looks along +Y, from the front.", "type": "number"},
                "pitch": {"description": "Elevation of the eye above the ground plane.", "type": "number"},
                "distance": {"description": "From the target to the eye, in mm.", "type": "number", "exclusiveMinimum": 0},
                "fov": {"description": "Vertical field of view; 0 is orthographic. Default: 0.", "type": "number", "default": 0.0}
            },
            "required": ["target", "yaw", "pitch", "distance"]
        })
    }
}

/// Keep the camera as a named view of the design. One undo step. A view of the same name is
/// replaced.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = camera_required)]
pub struct ViewSaveParams {
    // Optional in the type and required in the schema (`camera_required`): left out, the handler
    // refuses it with its own message.
    /// The camera to keep: `{target: [x, y, z], yaw, pitch, distance, fov?}`, finite, with a
    /// distance above 0.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "ViewCamera")]
    pub camera: Option<ViewCamera>,
    /// The view's name, at most 128 bytes once surrounding spaces are cut. Default: "Named View"
    /// and the first number no view's name has. A value that is not text is reported, though the
    /// handler would read it as left out.
    #[serde(default)]
    pub name: Option<SavedViewName>,
}

/// What `view.save` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ViewSaved {
    /// The name the view was kept under.
    pub view: String,
    /// 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>,
}

/// Rename a named view. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = view_and_name_required)]
pub struct ViewRenameParams {
    // Required in the schema (`view_and_name_required`), optional in the type, as `group` above.
    /// The view to rename, by name.
    #[serde(default, deserialize_with = "some_view", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "ViewKey")]
    pub view: Option<ViewKey>,
    /// The new name, 1 to 128 characters once surrounding spaces are cut; no other view may
    /// have it.
    #[serde(default, deserialize_with = "some_new_name", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "NewName")]
    pub name: Option<NewName>,
}

/// What `view.rename` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ViewRenamed {
    /// The view's name now, without surrounding spaces.
    pub view: String,
    /// 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>,
}

/// Delete a named view. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = view_required)]
pub struct ViewDeleteParams {
    // Required in the schema (`view_required`), optional in the type.
    /// The view to delete, by name.
    #[serde(default, deserialize_with = "some_view", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "ViewKey")]
    pub view: Option<ViewKey>,
}

/// What `view.delete` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ViewDeleted {
    /// The name of the view that is gone.
    pub deleted: String,
    /// 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>,
}

/// `view.list` takes no parameters.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct ViewListParams {}

/// A named view, as `view.list` gives it. Only its schema is described here: the reply carries
/// the design's own [`solidcraft_doc::NamedView`] values.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ViewEntry {
    /// The view's name.
    pub name: String,
    /// The point the camera looks at, in mm.
    pub target: [f64; 3],
    /// Turn about the up axis, in radians.
    pub yaw: f64,
    /// Elevation of the eye, in radians.
    pub pitch: f64,
    /// From the target to the eye, in mm.
    pub distance: f64,
    /// Vertical field of view in radians; 0 is orthographic.
    pub fov: f64,
}

/// What `view.list` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ViewListResult {
    /// The design's named views, in the order they were made.
    #[schemars(with = "Vec<ViewEntry>")]
    pub views: Vec<solidcraft_doc::NamedView>,
    /// 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 camera `view.apply` turns to, as the handler reads it: `up` is refused, `roll` is finite,
/// the pitch within ±π/2 and the rest finite with a positive distance.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct ApplyCamera(pub solidcraft_render::Camera);

impl<'de> Deserialize<'de> for ApplyCamera {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        crate::cmd::browser::applied_camera_form(&Value::deserialize(d)?).map(ApplyCamera).map_err(|why| D::Error::custom(whole(why)))
    }
}

impl JsonSchema for ApplyCamera {
    fn schema_name() -> Cow<'static, str> {
        "ApplyCamera".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({
            "description": "An orbit camera. Angles are in radians, about the up axis, which comes from the design settings.",
            "type": "object",
            "properties": {
                "target": target_schema(),
                "yaw": {"description": "Turn about the up axis; 0 looks along +Y (Front), π/2 along +X (Left), π (Back), -π/2 (Right).", "type": "number"},
                "pitch": {"description": "Elevation of the eye above the ground plane, within ±π/2; π/2 is Top.", "type": "number", "minimum": -std::f64::consts::FRAC_PI_2, "maximum": std::f64::consts::FRAC_PI_2},
                "distance": {"description": "From the target to the eye, in mm.", "type": "number", "exclusiveMinimum": 0},
                "fov": {"description": "Vertical field of view; 0 is orthographic. Default: 0.", "type": "number", "minimum": 0, "default": 0.0},
                "roll": {"description": "Turn about the viewing direction, clockwise; a finite number, clamped to ±π. Default: 0.", "type": "number", "default": 0.0}
            },
            "required": ["target", "yaw", "pitch", "distance"],
            "not": {"required": ["up"]}
        })
    }
}

/// Move the viewport (and the MCP screenshot) to a standard view, a named view or a camera. View
/// state only: not saved with the design and not an undo step. Give `view` or `camera`, not both.
/// (A `view` that is not text is read as absent when a `camera` is given, as the handler does.)
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct ViewApplyKeys {
    /// A standard view: front, back, top, bottom, left, right, iso or home (the model framed
    /// from there), or a named view's name. Not with `camera`.
    #[serde(default)]
    pub view: Option<String>,
    /// A camera to turn to. Not with `view`.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "ApplyCamera")]
    pub camera: Option<ApplyCamera>,
}

/// `view.apply`'s parameters: [`ViewApplyKeys`] with the two forms told apart.
///
/// The handler reads `view` as text and takes anything else as absent, and reads `camera` only
/// when `view` is not text, so the same holds here: a `view` that is not text is not looked at
/// when a `camera` is given, and one of neither is left to the handler's message.
#[derive(Debug)]
pub struct ViewApplyParams(pub ViewApplyKeys);

impl<'de> Deserialize<'de> for ViewApplyParams {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let mut value = Value::deserialize(d)?;
        if value.get("view").is_some_and(Value::is_string) {
            if value.get("camera").is_some() {
                return Err(D::Error::custom(whole("give `view` or `camera`, not both")));
            }
        } else if let Some(keys) = value.as_object_mut() {
            keys.remove("view");
        }
        serde_path_to_error::deserialize(&value).map(ViewApplyParams).map_err(|e| D::Error::custom(located(&e)))
    }
}

impl JsonSchema for ViewApplyParams {
    fn schema_name() -> Cow<'static, str> {
        "ViewApplyParams".into()
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        let mut schema = ViewApplyKeys::json_schema(generator);
        schema.insert("anyOf".into(), json!([{"required": ["view"]}, {"required": ["camera"]}]));
        schema.insert("not".into(), json!({"required": ["view", "camera"]}));
        schema
    }
}

/// A sketch by id or name, as `sketch.redefine` reads `sketch`.
#[derive(Clone, Debug, PartialEq)]
pub struct SketchKey(pub String);

impl<'de> Deserialize<'de> for SketchKey {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::Number(n) => Ok(SketchKey(n.to_string())),
            Value::String(s) => Ok(SketchKey(s)),
            _ => Err(D::Error::custom(whole("`sketch` must be an id or name"))),
        }
    }
}

impl JsonSchema for SketchKey {
    fn schema_name() -> Cow<'static, str> {
        "SketchKey".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({"description": "A sketch's feature id (a number) or its name.", "type": ["number", "string"]})
    }
}

fn some_sketch<'de, D: Deserializer<'de>>(d: D) -> Result<Option<SketchKey>, D::Error> {
    SketchKey::deserialize(d).map(Some)
}

/// The coordinates an explicit plane `{origin, x_dir, y_dir}` is given in: `world` or
/// `component`, the component's own. (No doc on the variants: they would make the schema a
/// `oneOf` of constants instead of a plain `enum`.)
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum PlaneFrame {
    World,
    Component,
}

impl PlaneFrame {
    /// The frame a handler names, as `world` or `component`.
    pub fn from_name(name: &str) -> Option<PlaneFrame> {
        match name {
            "world" => Some(PlaneFrame::World),
            "component" => Some(PlaneFrame::Component),
            _ => None,
        }
    }
}

impl<'de> Deserialize<'de> for PlaneFrame {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::String(f) if f == "world" => Ok(PlaneFrame::World),
            Value::String(f) if f == "component" => Ok(PlaneFrame::Component),
            _ => Err(D::Error::custom(whole("`frame` must be \"world\" or \"component\""))),
        }
    }
}

/// The occurrence ids of the placement a sketch is authored in, from the outermost down, as
/// `sketch.redefine` reads `author_path`: at most 64 nonzero whole numbers.
#[derive(Clone, Debug, PartialEq)]
pub struct AuthorPath(pub Vec<u64>);

impl<'de> Deserialize<'de> for AuthorPath {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::Array(path) if path.len() <= MAX_PATH => path
                .iter()
                .map(|id| id.as_u64().filter(|id| *id != 0).ok_or_else(|| D::Error::custom(whole("invalid author_path id"))))
                .collect::<Result<_, _>>()
                .map(AuthorPath),
            _ => Err(D::Error::custom(whole("author_path must contain at most64 ids"))),
        }
    }
}

impl JsonSchema for AuthorPath {
    fn schema_name() -> Cow<'static, str> {
        "AuthorPath".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({
            "description": "Occurrence ids, outermost first: at most 64 whole numbers above 0.",
            "type": "array",
            "items": {"type": "integer", "minimum": 1},
            "maxItems": MAX_PATH
        })
    }
}

/// Move a sketch to another plane, keeping its geometry and its dimension names: an origin or
/// construction plane, an explicit plane, or a planar face of the model. A face it follows is
/// refused where the sketch's own geometry would depend on later features. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = sketch_and_plane_required)]
pub struct RedefineSketchParams {
    // Optional in the type and required in the schema (`sketch_and_plane_required`): left out,
    // the handler refuses it with its own message.
    /// The sketch to move, by feature id or name.
    #[serde(default, deserialize_with = "some_sketch", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "SketchKey")]
    pub sketch: Option<SketchKey>,
    /// The new plane, as `sketch.create` takes it. A picked face is read as it reads one.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "CanvasPlane")]
    pub plane: Option<CanvasPlane>,
    /// Move the plane this far along its normal (mm or a length expression). Default: 0.
    #[serde(default)]
    pub offset: Option<LengthExpr>,
    /// The placement the sketch is authored in, as occurrence ids from the outermost down. Default: the
    /// sketch's saved one, else the active occurrence, else the component's only placement; a
    /// component sketch in a design with several placements needs it.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "AuthorPath")]
    pub author_path: Option<AuthorPath>,
    /// For an explicit plane `{origin, x_dir, y_dir}`: whether it is in the world's or the
    /// component's own coordinates. Default: world. A named plane or a face takes none.
    #[serde(default)]
    pub frame: Option<PlaneFrame>,
}

/// How a redefined sketch is attached to its plane: `exact_face` (to a face of a body, which it
/// follows), `sheet_face` (to a face of a sheet part) or `fixed` (where it is: an origin,
/// construction or explicit plane).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum RedefineAttachment {
    ExactFace,
    SheetFace,
    Fixed,
}

/// What `sketch.redefine` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct RedefineSketchResult {
    /// The sketch's feature id.
    pub sketch: u64,
    /// How it is attached now.
    pub attachment: Option<RedefineAttachment>,
    /// For an explicit plane: the coordinates it was read in.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub frame: Option<PlaneFrame>,
    /// For a world plane put into a component that is moved or turned: how it was stored.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub note: Option<String>,
    /// What the session reports for every sketch command: the ids of the points, curves,
    /// constraints and dimensions the sketch gained, `{points, curves, constraints, dimensions}`.
    /// The handler leaves it out; the session adds it.
    #[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>,
}

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