GitCorner

Code

ossartcraftfigcraft🌐
b45255bb6fe2
//! Design context: what an AI agent needs to build a design, in one read (`inspect.designContext`,
//! the MCP tool `design_context`). The selection by default, as a tree in which every layer keeps
//! apart what the designer set (`explicit`), what layout or the file worked out (`derived`) and
//! what has no direct CSS equivalent (`unsupported`, with the reason). The variables, styles and
//! components the tree uses are joined once at the top level, and a connected instance gives its
//! code instead of its layers. Values are the file's own: nothing is guessed or converted, and
//! `missing` says what the design doesn't specify.

use std::collections::{BTreeMap, BTreeSet};

use figcraft_color::{GradientKind, PaintKind};
use figcraft_doc::{Document, EffectKind, Node, NodeId, NodeKind, Sizing, StrokeAlign, TextAutoResize};
use serde_json::{Map, Value, json};

use crate::cmd::CommandSpec;
use crate::cmd::component::describe_props;
use crate::code_connect;
use crate::codegen::CodeLang;
use crate::inspect::{camel, node_json};
use crate::params::{get, num, string, targets};
use crate::{Result, Session, bad, spec};

/// The format's version: fields may be added without changing it.
const VERSION: u64 = 1;
/// How deep the tree goes by default.
const DEFAULT_DEPTH: usize = 32;
/// The deepest tree asked for.
const MAX_DEPTH: usize = 128;
/// How many layers it holds by default.
const DEFAULT_NODES: usize = 2_000;
/// The most layers asked for.
const MAX_NODES: usize = 20_000;

/// Worked out rather than set, whatever the layer.
const DERIVED: [&str; 3] = ["absoluteBounds", "rotation", "gridCell"];

/// What the tree used, to join at the top level.
#[derive(Default)]
struct Used {
    variables: BTreeSet<String>,
    styles: BTreeSet<String>,
    components: BTreeSet<NodeId>,
    /// Layers placed so far, and those left out for the cap.
    nodes: usize,
    left_out: usize,
    /// Reached `depth` with children left.
    cut_by_depth: bool,
    /// The layers placed.
    placed: BTreeSet<NodeId>,
    /// Font families of the text layers placed, with their styles.
    fonts: BTreeMap<String, BTreeSet<String>>,
}

/// `property` of a layer has no direct CSS equivalent, because `why`.
fn limit(out: &mut Vec<Value>, property: &str, why: &str) {
    out.push(json!({"property": property, "why": why}));
}

/// What of `n` CSS can't say directly. The original values stay in `explicit`.
fn limits(n: &Node) -> Vec<Value> {
    let mut out = Vec::new();
    if matches!(n.blend, figcraft_color::BlendMode::PlusDarker) {
        limit(&mut out, "blend", "only some browsers have the plus-darker blend mode");
    }
    if n.corners.smoothing > 0.0 {
        limit(&mut out, "cornerSmoothing", "CSS border-radius has no corner smoothing");
    }
    if !n.strokes.is_empty() {
        match n.stroke.align {
            StrokeAlign::Inside => {}
            StrokeAlign::Center => limit(&mut out, "strokeAlign", "a CSS border can't straddle the box edge"),
            StrokeAlign::Outside => {
                limit(&mut out, "strokeAlign", "a CSS border sits inside the box's border area: an outline or box-shadow comes closest")
            }
        }
        if n.stroke.profile().is_some() {
            limit(&mut out, "widthProfile", "CSS strokes have one width");
        }
        if n.stroke.brush.is_some() {
            limit(&mut out, "brush", "CSS has no brush strokes");
        }
    }
    for p in n.fills.iter().chain(&n.strokes) {
        match &p.kind {
            PaintKind::Gradient(g) if g.kind == GradientKind::Diamond => limit(&mut out, "fills", "CSS has no diamond gradient"),
            PaintKind::Pattern(_) => limit(&mut out, "fills", "a pattern fill needs an image or an SVG pattern in CSS"),
            _ => {}
        }
    }
    for e in &n.effects {
        match e.kind {
            EffectKind::Noise(_) => limit(&mut out, "effects", "CSS has no noise effect"),
            EffectKind::Texture(_) => limit(&mut out, "effects", "CSS has no roughened edge effect"),
            EffectKind::Glass(_) => limit(&mut out, "effects", "CSS has no curved glass effect"),
            _ => {}
        }
    }
    if let NodeKind::Text(t) = &n.kind {
        if t.path.is_some() {
            limit(&mut out, "textPath", "text on a path needs SVG");
        }
        if t.leading_trim != figcraft_doc::LeadingTrim::None {
            limit(&mut out, "leadingTrim", "CSS text-box-trim isn't in every browser");
        }
        if t.hanging_punctuation {
            limit(&mut out, "hangingPunctuation", "CSS hanging-punctuation isn't in every browser");
        }
    }
    out
}

/// Moves `key` of `explicit` to `derived`.
fn derive(explicit: &mut Map<String, Value>, derived: &mut Map<String, Value>, key: &str) {
    if let Some(v) = explicit.remove(key) {
        derived.insert(key.into(), v);
    }
}

/// Splits a layer's properties: a size or a position that layout decides isn't the designer's.
fn split(doc: &Document, n: &Node, explicit: &mut Map<String, Value>) -> Map<String, Value> {
    let mut derived = Map::new();
    for key in DERIVED {
        derive(explicit, &mut derived, key);
    }
    let in_flow = n.parent.and_then(|p| doc.node(p)).is_some_and(|p| p.layout.is_some()) && !n.child_layout.absolute;
    if in_flow {
        derive(explicit, &mut derived, "x");
        derive(explicit, &mut derived, "y");
    }
    let (mut wide, mut tall) = (n.child_layout.sizing_h != Sizing::Fixed, n.child_layout.sizing_v != Sizing::Fixed);
    if let NodeKind::Text(t) = &n.kind {
        wide |= t.auto_resize == TextAutoResize::WidthAndHeight;
        tall |= matches!(t.auto_resize, TextAutoResize::WidthAndHeight | TextAutoResize::Height);
    }
    if wide {
        derive(explicit, &mut derived, "width");
    }
    if tall {
        derive(explicit, &mut derived, "height");
    }
    derived
}

/// What a layer's tokens are called: bindings by field, shared styles by kind, as they would be
/// looked up in the top-level `variables` and `styles`.
fn tokens(doc: &Document, n: &Node, used: &mut Used) -> Map<String, Value> {
    let mut out = Map::new();
    for (field, id) in &n.bound {
        used.variables.insert(id.clone());
        let name = doc.variables.variables.iter().find(|v| v.id == *id).map(|v| v.name.clone());
        out.insert(field.clone(), json!({"variable": id, "name": name}));
    }
    let refs = &n.styles;
    let mut styles: Vec<(String, &String)> =
        [("fill", &refs.fill), ("stroke", &refs.stroke), ("effect", &refs.effect), ("grid", &refs.grid), ("text", &refs.text)]
            .into_iter()
            .filter_map(|(k, s)| s.as_ref().map(|s| (format!("style.{k}"), s)))
            .collect();
    if let NodeKind::Text(t) = &n.kind {
        let spans = t.spans();
        styles.extend(spans.iter().filter_map(|(a, b, s)| s.style_id.as_ref().map(|i| (format!("style.text[{a}..{b}]"), i))));
    }
    for (key, id) in styles {
        used.styles.insert(id.clone());
        let name = doc.styles.iter().find(|s| s.id == *id).map(|s| s.name.clone());
        out.insert(key, json!({"style": id, "name": name}));
    }
    out
}

/// The code component a component, set or instance is connected to, per language, with the
/// instance's own values in its snippet.
fn code(doc: &Document, id: NodeId) -> Vec<Value> {
    let Some(owner) = code_connect::owner(doc, id).and_then(|o| doc.node(o)) else { return vec![] };
    owner
        .code_links
        .iter()
        .filter_map(|l| {
            let lang = CodeLang::from_id(&l.language)?;
            let snippet = code_connect::connected_code(doc, id, lang, l)?;
            Some(json!({"language": l.language, "importPath": l.import_path, "name": l.name, "code": snippet}))
        })
        .collect()
}

/// Layer `id` and, to `depth`, what's under it, while the cap holds.
fn layer(doc: &Document, id: NodeId, depth: usize, cap: usize, used: &mut Used) -> Option<Value> {
    let n = doc.node(id)?;
    used.nodes += 1;
    used.placed.insert(id);
    if let NodeKind::Text(t) = &n.kind {
        for (_, _, style) in t.spans() {
            used.fonts.entry(style.font_family.clone()).or_default().insert(style.font_style.clone());
        }
    }
    let Value::Object(mut explicit) = node_json(doc, id, 0) else { return None };
    explicit.remove("childCount");
    let mut out = Map::new();
    for key in ["id", "name", "type"] {
        if let Some(v) = explicit.remove(key) {
            out.insert(key.into(), v);
        }
    }
    let derived = split(doc, n, &mut explicit);
    let tokens = tokens(doc, n, used);
    let unsupported = limits(n);
    out.insert("explicit".into(), Value::Object(explicit));
    if !derived.is_empty() {
        out.insert("derived".into(), Value::Object(derived));
    }
    if !tokens.is_empty() {
        out.insert("tokens".into(), Value::Object(tokens));
    }
    if !unsupported.is_empty() {
        out.insert("unsupported".into(), Value::Array(unsupported));
    }
    if let Some(owner) = code_connect::owner(doc, id) {
        used.components.insert(owner);
    }
    let connected = code(doc, id);
    // An instance built from a code component needs its call, not its layers.
    let stop = matches!(n.kind, NodeKind::Instance { .. }) && !connected.is_empty();
    if !connected.is_empty() {
        out.insert("code".into(), Value::Array(connected));
    }
    if n.children.is_empty() {
        return Some(Value::Object(out));
    }
    if stop {
        out.insert("childCount".into(), json!(n.children.len()));
        return Some(Value::Object(out));
    }
    if depth == 0 {
        used.cut_by_depth = true;
        out.insert("childCount".into(), json!(n.children.len()));
        return Some(Value::Object(out));
    }
    let mut children = Vec::new();
    for c in &n.children {
        if used.nodes >= cap {
            used.left_out += 1;
            continue;
        }
        children.extend(layer(doc, *c, depth - 1, cap, used));
    }
    if children.len() < n.children.len() {
        out.insert("childCount".into(), json!(n.children.len()));
    }
    out.insert("children".into(), Value::Array(children));
    Some(Value::Object(out))
}

/// A value as the panels show it: colours in hex.
fn value_json(v: &figcraft_doc::VariableValue) -> Value {
    match v {
        figcraft_doc::VariableValue::Color(c) => json!(c.to_css_hex()),
        figcraft_doc::VariableValue::Number(n) => json!(n),
        figcraft_doc::VariableValue::String(s) => json!(s),
        figcraft_doc::VariableValue::Boolean(b) => json!(b),
        other => serde_json::to_value(other).unwrap_or(Value::Null),
    }
}

/// `ids`' variables: every mode's stored and resolved value. A value that is an alias or a
/// calculation stays in `value`; the variables it reads are in `ids` too ([`referenced`]).
fn variables_json(doc: &Document, ids: &BTreeSet<String>, missing: &mut Vec<Value>) -> Value {
    let store = &doc.variables;
    let mut out = Map::new();
    for id in ids {
        let Some(var) = store.variables.iter().find(|v| v.id == *id) else {
            missing.push(json!({"what": "variable", "id": id, "why": "a layer is bound to it, but it isn't in this file"}));
            continue;
        };
        let collection = store.collection_by_id(&var.collection);
        let modes: Vec<Value> = collection
            .map(|c| c.modes.as_slice())
            .unwrap_or_default()
            .iter()
            .map(|m| {
                let chosen = BTreeMap::from([(var.collection.clone(), m.id.clone())]);
                json!({
                    "mode": m.name,
                    "value": var.values.get(&m.id).map(value_json),
                    "resolved": store.resolve(id, &chosen).as_ref().map(value_json),
                })
            })
            .collect();
        let mut v = json!({"name": var.name, "collection": collection.map(|c| c.name.as_str()), "type": var.kind, "modes": modes});
        if !var.code_syntax.is_empty() {
            v["codeSyntax"] = json!(var.code_syntax);
        }
        if !var.description.is_empty() {
            v["description"] = json!(var.description);
        }
        out.insert(id.clone(), v);
    }
    Value::Object(out)
}

/// Most variables followed through aliases.
const MAX_VARIABLES: usize = 10_000;

/// The variables a tree uses: those its layers bind (`bound`), those its shared `styles` bind, and
/// those any of them reads as an alias or in a colour calculation, however deep, up to `max`. The
/// flag is false when `max` stopped it with variables still to follow.
pub(crate) fn referenced(doc: &Document, bound: &BTreeSet<String>, styles: &BTreeSet<String>, max: usize) -> (BTreeSet<String>, bool) {
    let mut out: BTreeSet<String> = BTreeSet::new();
    let mut todo: Vec<String> = bound.iter().cloned().collect();
    todo.extend(doc.styles.iter().filter(|st| styles.contains(&st.id)).flat_map(|st| st.bound.values().cloned()));
    todo.reverse();
    while let Some(id) = todo.pop() {
        if out.contains(&id) {
            continue;
        }
        if out.len() >= max {
            return (out, false);
        }
        out.insert(id.clone());
        let Some(var) = doc.variables.variables.iter().find(|v| v.id == id) else { continue };
        for value in var.values.values() {
            match value {
                figcraft_doc::VariableValue::Alias(other) => todo.push(other.clone()),
                figcraft_doc::VariableValue::ColorAlpha { variable, .. } => todo.push(variable.clone()),
                figcraft_doc::VariableValue::ColorMix { from, to, .. } => todo.extend(from.variable().into_iter().chain(to.variable()).cloned()),
                _ => {}
            }
        }
    }
    (out, true)
}

/// The shared styles the tree uses, with what each sets.
fn styles_json(doc: &Document, ids: &BTreeSet<String>, missing: &mut Vec<Value>) -> Value {
    let mut out = Map::new();
    for id in ids {
        match doc.styles.iter().find(|s| s.id == *id) {
            Some(st) => {
                out.insert(id.clone(), camel(serde_json::to_value(st).unwrap_or(Value::Null)));
            }
            None => missing.push(json!({"what": "style", "id": id, "why": "a layer links to it, but it isn't in this file"})),
        }
    }
    Value::Object(out)
}

/// The components and sets the tree uses: their properties, variants and code.
fn components_json(doc: &Document, ids: &BTreeSet<NodeId>) -> Value {
    let mut out = Map::new();
    for id in ids {
        let Some(n) = doc.node(*id) else { continue };
        let mut v = json!({"name": n.name, "type": n.kind.type_name(), "properties": describe_props(doc, *id)["properties"]});
        if let NodeKind::Component { description, .. } = &n.kind
            && !description.is_empty()
        {
            v["description"] = json!(description);
        }
        if !n.code_links.is_empty() {
            v["codeLinks"] = camel(serde_json::to_value(&n.code_links).unwrap_or(Value::Null));
        }
        out.insert(id.to_string(), v);
    }
    Value::Object(out)
}

/// The font families the tree's text layers use, with their styles, and whether each is installed
/// (the family name trimmed, as the missing-fonts list reads it). The spelling stays as stored.
fn fonts(used: &BTreeMap<String, BTreeSet<String>>) -> Value {
    Value::Array(
        used.iter()
            .map(|(family, styles)| json!({"family": family, "styles": styles, "installed": figcraft_text::has_family(family.trim())}))
            .collect(),
    )
}

/// What the request names: (where it came from, the layers).
fn roots(s: &Session, p: &Value) -> Result<(&'static str, Vec<NodeId>)> {
    let cmd = "inspect.designContext";
    let doc = s.doc()?;
    let malformed = || bad(cmd, "ids: a list of layer ids (or id: one)");
    match (get(p, "ids"), get(p, "id")) {
        (Some(Value::Array(list)), _) if list.iter().all(|i| crate::params::id_of(i).is_some()) => {}
        (Some(_), _) => return Err(malformed()),
        (None, Some(one)) if crate::params::id_of(one).is_none() => return Err(malformed()),
        _ => {}
    }
    if get(p, "ids").is_some() || get(p, "id").is_some() {
        let ids: Vec<NodeId> = targets(s, p);
        if let Some(gone) = ids.iter().find(|i| !doc.contains(**i)) {
            return Err(bad(cmd, format!("no layer {gone}")));
        }
        return Ok(("ids", ids));
    }
    let page = |pg: NodeId| doc.node(pg).map(|n| n.children.clone()).unwrap_or_default();
    match string(p, "scope").as_deref() {
        None | Some("selection") => match s.selection() {
            ids if ids.is_empty() => Ok(("page", page(s.page()?))),
            ids => Ok(("selection", ids)),
        },
        Some("page") => Ok(("page", page(s.page()?))),
        Some("document") => Ok(("document", doc.pages.iter().flat_map(|pg| page(*pg)).collect())),
        Some(_) => Err(bad(cmd, "scope: selection|page|document")),
    }
}

/// A whole-number parameter within `1..=max`.
fn limit_param(p: &Value, key: &str, default: usize, max: usize) -> Result<usize> {
    match get(p, key) {
        None | Some(Value::Null) => Ok(default),
        Some(_) => match num(p, key).filter(|v| v.is_finite() && *v >= 0.0) {
            Some(v) => Ok((v as usize).min(max)),
            None => Err(bad("inspect.designContext", format!("{key}: a whole number"))),
        },
    }
}

fn design_context(s: &mut Session, p: &Value) -> Result<Value> {
    let (source, ids) = roots(s, p)?;
    let depth = limit_param(p, "depth", DEFAULT_DEPTH, MAX_DEPTH)?;
    let cap = limit_param(p, "maxNodes", DEFAULT_NODES, MAX_NODES)?.max(1);
    let doc = s.doc()?;
    let mut used = Used::default();
    let mut nodes = Vec::new();
    for id in &ids {
        if used.nodes >= cap {
            used.left_out += 1;
            continue;
        }
        nodes.extend(layer(doc, *id, depth, cap, &mut used));
    }
    let mut missing = vec![
        json!({"what": "responsive behaviour", "why": "the file stores no breakpoints: sizes are as designed here, and constraints, sizing and annotations are all it says about other widths"}),
    ];
    let (joined, complete) = referenced(doc, &used.variables, &used.styles, MAX_VARIABLES);
    let variables = variables_json(doc, &joined, &mut missing);
    let styles = styles_json(doc, &used.styles, &mut missing);
    let components = components_json(doc, &used.components);
    let fonts = fonts(&used.fonts);
    let page = doc.node(s.page()?).map(|n| n.name.clone());
    // The assets of the layers returned: a smaller tree means a smaller list.
    let found = crate::devinspect::assets(doc, &ids);
    let assets: Vec<&crate::devinspect::Asset> = found.iter().filter(|a| used.placed.contains(&a.id)).collect();
    let assets_left_out = found.len() - assets.len();
    let mut out = json!({
        "version": VERSION,
        "document": {"name": doc.name, "page": {"id": s.page()?, "name": page}, "colorProfile": doc.color_profile.id()},
        "target": {"source": source, "ids": ids, "layers": used.nodes},
        "nodes": nodes,
        "variables": variables,
        "styles": styles,
        "components": components,
        "fonts": fonts,
        "assets": assets,
        "missing": missing,
    });
    if used.left_out > 0 || used.cut_by_depth {
        out["truncated"] = json!({"layersLeftOut": used.left_out, "assetsLeftOut": assets_left_out, "depth": used.cut_by_depth, "maxNodes": cap, "hint": "call again with the ids of the parts you need"});
    }
    if !complete {
        out["truncated"]["variables"] =
            json!({"maxVariables": MAX_VARIABLES, "why": "aliases go deeper than this: some variables they read aren't defined here"});
    }
    Ok(out)
}

pub fn specs() -> Vec<CommandSpec> {
    vec![spec!(
        "inspect.designContext",
        "Design context",
        "{ids? | id? (those layers), scope?: selection|page|document (default the selection, or the page with nothing selected), depth? (default 32), maxNodes? (default 2000)}  everything needed to build them, in one read  → {version, document, target {source, ids, layers}, nodes [{id, name, type, explicit, derived?, tokens?, unsupported? [{property, why}], code?, children?, childCount?}], variables, styles, components, fonts, assets, missing [{what, why}], truncated?}",
        false,
        design_context
    )]
}