M8: design context for AI agents

inspect.designContext and the MCP tool design_context read the selection (or
ids, or a scope) in one call. Each layer keeps apart the values the designer
set (explicit), those layout or the file worked out (derived) and those with no
direct CSS equivalent (unsupported, with the reason). The variables (every
mode's stored and resolved value), styles, components, fonts and assets the
tree uses are joined once, and `missing` says what the design doesn't specify.
A connected instance gives its code snippet instead of its layers. Large trees
are capped and say so, and the MCP tool asks for fewer layers until the result
fits the client.
This commit is contained in:
B-uchi committed 2026-11-18 20:37:44 +01:00
1 parent d4b4387eb1
commit 2d4309c9aa
9 files changed
+820

No files matched your search

+1
View File
@@ -366,6 +366,7 @@ Ranked; detail and milestones in [`docs/roadmap.md`](docs/roadmap.md).
| Date | Change | Summary |
|---|---|---|
| 2026-11-18 | minor | M8: design context for AI agents. `inspect.designContext` and the MCP tool `design_context` read the selection (or `ids`, or a `scope`) in one call: a tree where each layer keeps apart `explicit` values, `derived` ones layout worked out and `unsupported` ones with no direct CSS equivalent, joined with the variables (every mode's stored and resolved value), styles, components, fonts and assets it uses, and what the design leaves `missing`. A connected instance gives its code instead of its layers, and a result that wouldn't fit the client asks for fewer layers. Numbers unchanged |
| 2026-11-18 | minor | M3, gap 10: library analytics count insertions and detachments of styles and variables. Applying one, or copying or duplicating content that uses it, inserts it; the Detach button detaches it; an instance counts as its component alone. Show usage and `library.usage` give them per style and variable over the chosen period. Modes aren't counted. Numbers unchanged. Tests: `library_asset_counts_tests`, `library_assets_tests`. |
| 2026-11-18 | minor | M9, gap 6: the browser build uses team libraries and plugin directories on a server, through its WebSocket requests: adding a library by its link, its styles and components, publishing to it, Show usage and the reports a file sends; browsing a directory and installing from it, for the page only. Scripts through `window.figcraft` still can't, as commands there don't wait for the server. Numbers unchanged. Tests: `exchange_tests`. |
| 2026-11-17 | minor | M6: Android Vector Drawable XML serialization uses the shared writer; application projection and colour policy remain local. Byte-parity tests cover full documents and generated deep wrappers; no new format capability or incumbent certification. |
+1
View File
@@ -100,6 +100,7 @@ fn registry() -> &'static Registry {
list.extend(crate::shapebuilder::specs());
list.extend(crate::codegen::specs());
list.extend(crate::devinspect::specs());
list.extend(crate::design_context::specs());
list.extend(crate::component_codegen::specs());
list.extend(crate::playground::specs());
list.extend(crate::code_connect::specs());
+288
View File
@@ -0,0 +1,288 @@
//! `inspect.designContext` against documents built with real commands.
use serde_json::{Value, json};
use crate::Session;
fn session() -> Session {
let mut s = Session::new();
s.execute("file.new", &json!({})).unwrap();
s
}
fn id(v: &Value) -> u64 {
v["id"].as_u64().unwrap()
}
fn node(s: &mut Session, params: Value) -> u64 {
id(&s.execute("node.create", &params).unwrap())
}
fn context(s: &mut Session, params: Value) -> Value {
s.execute("inspect.designContext", &params).unwrap()
}
/// A hugging auto layout card holding a fixed title and a filling line.
fn card(s: &mut Session) -> (u64, u64, u64) {
let f = node(s, json!({"type": "frame", "name": "Card", "x": 40, "y": 30, "width": 300, "height": 200, "props": {"fill": "#FFFFFF"}}));
s.execute("node.set", &json!({"ids": [f], "props": {"layout": {"mode": "vertical"}, "gap": 12, "padding": [16, 16, 16, 16], "sizingV": "hug"}}))
.unwrap();
let title = node(s, json!({"type": "text", "parent": f, "name": "Title", "text": "Pro plan", "props": {"fontSize": 24}}));
let line = node(s, json!({"type": "rectangle", "parent": f, "name": "Rule", "width": 100, "height": 2, "props": {"sizingH": "fill"}}));
(f, title, line)
}
fn only(v: &Value) -> &Value {
let nodes = v["nodes"].as_array().unwrap();
assert_eq!(nodes.len(), 1, "{v}");
&nodes[0]
}
#[test]
fn the_selection_is_what_is_read() {
let mut s = session();
let (f, title, _) = card(&mut s);
let other = node(&mut s, json!({"type": "rectangle", "name": "Elsewhere", "width": 10, "height": 10}));
s.execute("select.set", &json!({"ids": [f]})).unwrap();
let v = context(&mut s, json!({}));
assert_eq!(v["target"]["source"], "selection");
assert_eq!(only(&v)["id"], f);
assert_eq!(only(&v)["children"][0]["id"], title);
assert_eq!(v["target"]["layers"], 3);
assert!(!v.to_string().contains("Elsewhere"), "the rest of the page stays out");
let _ = other;
}
#[test]
fn several_selected_layers_each_come_back() {
let mut s = session();
let a = node(&mut s, json!({"type": "rectangle", "width": 10, "height": 10}));
let b = node(&mut s, json!({"type": "ellipse", "width": 10, "height": 10}));
s.execute("select.set", &json!({"ids": [a, b]})).unwrap();
assert_eq!(context(&mut s, json!({}))["nodes"].as_array().unwrap().len(), 2);
}
#[test]
fn ids_and_scopes_choose_the_target() {
let mut s = session();
let (f, _, _) = card(&mut s);
let other = node(&mut s, json!({"type": "rectangle", "width": 10, "height": 10}));
s.execute("select.set", &json!({"ids": [other]})).unwrap();
assert_eq!(context(&mut s, json!({"ids": [f]}))["target"]["source"], "ids");
assert_eq!(context(&mut s, json!({"scope": "page"}))["nodes"].as_array().unwrap().len(), 2);
s.execute("page.add", &json!({"name": "Second"})).unwrap();
assert_eq!(context(&mut s, json!({"scope": "document"}))["target"]["source"], "document");
assert!(s.execute("inspect.designContext", &json!({"ids": [999_999]})).is_err());
assert!(s.execute("inspect.designContext", &json!({"scope": "everything"})).is_err());
}
#[test]
fn nothing_selected_reads_the_page() {
let mut s = session();
card(&mut s);
s.execute("select.none", &json!({})).unwrap();
assert_eq!(context(&mut s, json!({}))["target"]["source"], "page");
}
#[test]
fn what_layout_decides_is_derived_and_what_the_designer_set_is_explicit() {
let mut s = session();
let (f, _, _) = card(&mut s);
let v = context(&mut s, json!({"ids": [f]}));
let frame = only(&v);
assert_eq!(frame["explicit"]["width"], 300.0, "a fixed width is the designer's");
assert_eq!(frame["explicit"]["x"], 40.0);
assert!(frame["explicit"].get("height").is_none(), "a hug height isn't");
assert!(frame["derived"]["height"].is_number());
assert!(frame["derived"]["absoluteBounds"].is_object());
assert_eq!(frame["explicit"]["layout"]["gap"], 12.0);
let (title, rule) = (&frame["children"][0], &frame["children"][1]);
assert!(title["derived"].get("x").is_some(), "its place comes from the flow: {title}");
assert!(title["explicit"].get("x").is_none());
assert!(title["derived"].get("width").is_some(), "auto-width text: {title}");
assert!(rule["derived"].get("width").is_some(), "fill: {rule}");
assert_eq!(rule["explicit"]["height"], 2.0);
}
#[test]
fn the_values_are_the_documents() {
let mut s = session();
let (f, title, _) = card(&mut s);
let v = context(&mut s, json!({"ids": [f]}));
let got = &only(&v)["children"][0]["explicit"];
let inspected = s.execute("node.get", &json!({"id": title})).unwrap();
for key in ["characters", "fontFamily", "fontSize", "lineHeight", "letterSpacing", "textAlign", "fontStyle"] {
assert_eq!(got[key], inspected[key], "{key}");
}
assert_eq!(got["characters"], "Pro plan");
}
#[test]
fn tokens_are_joined_with_every_modes_value() {
let mut s = session();
let c = s.execute("variable.createCollection", &json!({"name": "Theme", "modes": ["Light", "Dark"]})).unwrap();
let collection = c["id"].clone();
let var = s
.execute(
"variable.create",
&json!({"collection": collection, "name": "surface", "type": "color", "values": {"Light": "#FFFFFF", "Dark": "#101010"}}),
)
.unwrap();
let var_id = var["id"].as_str().unwrap().to_string();
s.execute("variable.update", &json!({"variable": var_id, "codeSyntax": {"WEB": "var(--surface)"}})).unwrap();
let r = node(&mut s, json!({"type": "rectangle", "width": 10, "height": 10, "props": {"fill": {"$var": var_id}}}));
let v = context(&mut s, json!({"ids": [r]}));
let bound = only(&v)["tokens"].as_object().unwrap().values().next().unwrap().clone();
assert_eq!((bound["variable"].as_str(), bound["name"].as_str()), (Some(var_id.as_str()), Some("surface")));
let entry = &v["variables"][var_id.as_str()];
assert_eq!((entry["name"].as_str(), entry["collection"].as_str()), (Some("surface"), Some("Theme")));
assert_eq!(entry["codeSyntax"]["WEB"], "var(--surface)");
assert_eq!(entry["modes"][0]["mode"], "Light");
assert_eq!(entry["modes"][1]["resolved"], "#101010");
}
#[test]
fn a_shared_style_is_named_and_defined_once() {
let mut s = session();
let r = node(&mut s, json!({"type": "rectangle", "width": 10, "height": 10, "props": {"fill": "#FF0000"}}));
let st = s.execute("style.create", &json!({"type": "paint", "name": "Brand/Red", "from": r})).unwrap();
s.execute("style.apply", &json!({"style": st["id"], "ids": [r]})).unwrap();
let v = context(&mut s, json!({"ids": [r]}));
assert_eq!(only(&v)["tokens"]["style.fill"]["name"], "Brand/Red");
assert_eq!(v["styles"].as_object().unwrap().len(), 1);
assert_eq!(v["styles"][st["id"].as_str().unwrap()]["name"], "Brand/Red");
}
#[test]
fn a_connected_instance_gives_its_code_not_its_layers() {
let mut s = session();
let b = node(&mut s, json!({"type": "frame", "name": "Button", "width": 80, "height": 32}));
node(&mut s, json!({"type": "text", "parent": b, "text": "Buy"}));
let main = id(&s.execute("component.create", &json!({"ids": [b]})).unwrap());
let instance = id(&s.execute("instance.create", &json!({"component": main})).unwrap());
s.execute("codeConnect.set", &json!({"id": main, "language": "react", "importPath": "@/ui/button", "name": "Button", "template": "<Button />"}))
.unwrap();
let v = context(&mut s, json!({"ids": [instance]}));
let n = only(&v);
assert!(n["code"][0]["code"].as_str().unwrap().contains("<Button />"), "{n}");
assert_eq!(n["code"][0]["importPath"], "@/ui/button");
assert!(n.get("children").is_none(), "{n}");
assert_eq!(n["childCount"], 1);
assert_eq!(v["components"].as_object().unwrap().len(), 1);
assert_eq!(v["components"][main.to_string()]["codeLinks"][0]["name"], "Button");
}
#[test]
fn an_unconnected_instance_shows_its_layers_and_properties() {
let mut s = session();
let b = node(&mut s, json!({"type": "frame", "name": "Tag", "width": 80, "height": 32}));
node(&mut s, json!({"type": "text", "parent": b, "text": "New"}));
let main = id(&s.execute("component.create", &json!({"ids": [b]})).unwrap());
let inner = id(&s.execute("instance.create", &json!({"component": main})).unwrap());
let outer = node(&mut s, json!({"type": "frame", "name": "Row", "width": 200, "height": 60}));
s.execute("node.reparent", &json!({"ids": [inner], "parent": outer})).unwrap();
let v = context(&mut s, json!({"ids": [outer]}));
let i = &only(&v)["children"][0];
assert_eq!(i["explicit"]["mainComponentName"], "Tag");
assert_eq!(i["children"].as_array().unwrap().len(), 1, "nested layers: {i}");
assert!(v["components"].get(main.to_string()).is_some());
}
#[test]
fn what_css_cant_say_is_reported_and_kept() {
let mut s = session();
let r = node(
&mut s,
json!({"type": "rectangle", "width": 50, "height": 50, "props": {"cornerRadius": 12, "cornerSmoothing": 0.6, "strokes": ["#000000"], "strokeWeight": 2, "strokeAlign": "outside"}}),
);
let v = context(&mut s, json!({"ids": [r]}));
let n = only(&v);
let said: Vec<&str> = n["unsupported"].as_array().unwrap().iter().map(|u| u["property"].as_str().unwrap()).collect();
assert_eq!(said, ["cornerSmoothing", "strokeAlign"], "{n}");
assert_eq!(n["explicit"]["cornerSmoothing"], s.execute("node.get", &json!({"id": r})).unwrap()["cornerSmoothing"]);
}
#[test]
fn a_plain_layer_claims_no_limits() {
let mut s = session();
let r = node(&mut s, json!({"type": "rectangle", "width": 50, "height": 50, "props": {"fill": "#123456", "cornerRadius": 4}}));
let v = context(&mut s, json!({"ids": [r]}));
assert!(only(&v).get("unsupported").is_none());
}
#[test]
fn hidden_layers_stay_in_the_tree_marked() {
let mut s = session();
let (f, title, _) = card(&mut s);
s.execute("node.set", &json!({"ids": [title], "props": {"visible": false}})).unwrap();
let v = context(&mut s, json!({"ids": [f]}));
assert_eq!(only(&v)["children"][0]["explicit"]["visible"], false);
}
#[test]
fn what_the_design_doesnt_say_is_missing_not_guessed() {
let mut s = session();
let (f, _, _) = card(&mut s);
let v = context(&mut s, json!({"ids": [f]}));
assert!(v["missing"].as_array().unwrap().iter().any(|m| m["what"] == "responsive behaviour"));
assert!(!v.to_string().contains("@media"));
}
#[test]
fn annotations_come_with_their_layer() {
let mut s = session();
let (f, _, _) = card(&mut s);
s.execute("annotation.add", &json!({"id": f, "label": "Cards stack on mobile"})).unwrap();
let v = context(&mut s, json!({"ids": [f]}));
assert_eq!(only(&v)["explicit"]["annotations"][0]["label"], "Cards stack on mobile");
}
#[test]
fn deep_trees_stop_at_depth_and_say_so() {
let mut s = session();
let mut parent = node(&mut s, json!({"type": "frame", "width": 100, "height": 100}));
let root = parent;
for _ in 0..6 {
parent = node(&mut s, json!({"type": "frame", "parent": parent, "width": 50, "height": 50}));
}
let v = context(&mut s, json!({"ids": [root], "depth": 2}));
assert_eq!(v["target"]["layers"], 3);
assert_eq!(v["truncated"]["depth"], true);
assert_eq!(only(&v)["children"][0]["children"][0]["childCount"], 1);
assert!(context(&mut s, json!({"ids": [root]})).get("truncated").is_none());
}
#[test]
fn a_large_selection_keeps_to_the_cap_and_counts_the_rest() {
let mut s = session();
let root = node(&mut s, json!({"type": "frame", "width": 1000, "height": 1000}));
for _ in 0..50 {
node(&mut s, json!({"type": "rectangle", "parent": root, "width": 5, "height": 5}));
}
let v = context(&mut s, json!({"ids": [root], "maxNodes": 10}));
assert_eq!(v["target"]["layers"], 10);
assert_eq!(v["truncated"]["layersLeftOut"], 41);
assert_eq!(only(&v)["childCount"], 50, "it says how many there are");
}
#[test]
fn reading_changes_nothing() {
let mut s = session();
let (f, _, _) = card(&mut s);
let before = s.execute("node.get", &json!({"id": f})).unwrap();
let undo = s.undo_depth();
context(&mut s, json!({"ids": [f]}));
assert_eq!(s.execute("node.get", &json!({"id": f})).unwrap(), before);
assert_eq!(s.undo_depth(), undo);
}
#[test]
fn junk_parameters_are_errors_not_panics() {
let mut s = session();
card(&mut s);
for p in [json!({"depth": "x"}), json!({"maxNodes": -1}), json!({"maxNodes": "many"}), json!({"depth": {}})] {
assert!(s.execute("inspect.designContext", &p).is_err(), "{p}");
}
assert!(s.execute("inspect.designContext", &json!({"ids": []})).is_ok());
assert!(s.execute("inspect.designContext", &json!({"maxNodes": 0})).is_ok());
}
+1
View File
@@ -2,6 +2,7 @@ pub mod annotations;
pub mod code_connect;
pub mod codegen;
pub mod component_codegen;
pub mod design_context;
pub mod dev_measurements;
pub mod dev_resources;
pub mod devcompare;
+434
View File
@@ -0,0 +1,434 @@
//! 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,
}
/// `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;
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),
}
}
/// The variables the tree uses: every mode's stored and resolved value. A value that is an alias
/// or a calculation stays in `value`, and aliased variables are listed too, in `aliases`.
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)
}
/// 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 under `ids`' tree, with their styles.
fn fonts(doc: &Document, roots: &[NodeId], cap: usize) -> Value {
let mut used: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
let mut stack: Vec<NodeId> = roots.to_vec();
let mut seen = 0usize;
while let Some(id) = stack.pop() {
seen += 1;
if seen > cap {
break;
}
let Some(n) = doc.node(id) else { continue };
if let NodeKind::Text(t) = &n.kind {
for (_, _, s) in t.spans() {
used.entry(s.font_family.clone()).or_default().insert(s.font_style.clone());
}
}
stack.extend(n.children.iter().copied());
}
let gone = crate::fonts::missing(doc);
Value::Array(
used.into_iter()
.map(|(family, styles)| {
let installed = !gone.iter().any(|m| m.family.eq_ignore_ascii_case(&family));
json!({"family": family, "styles": styles, "installed": installed})
})
.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()?;
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 variables = variables_json(doc, &used.variables, &mut missing);
let styles = styles_json(doc, &used.styles, &mut missing);
let components = components_json(doc, &used.components);
let fonts = fonts(doc, &ids, cap.saturating_mul(4));
let page = doc.node(s.page()?).map(|n| n.name.clone());
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": crate::devinspect::assets(doc, &ids),
"missing": missing,
});
if used.left_out > 0 || used.cut_by_depth {
out["truncated"] = json!({"layersLeftOut": used.left_out, "depth": used.cut_by_depth, "maxNodes": cap, "hint": "call again with the ids of the parts you need"});
}
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
)]
}
+3
View File
@@ -65,6 +65,7 @@ pub use dev::annotations;
pub use dev::code_connect;
pub use dev::codegen;
pub use dev::component_codegen;
pub use dev::design_context;
pub use dev::dev_measurements;
pub use dev::dev_resources;
pub use dev::devcompare;
@@ -284,6 +285,8 @@ mod datafill_tests;
#[cfg(test)]
mod default_props_tests;
#[cfg(test)]
mod design_context_tests;
#[cfg(test)]
mod design_paste_tests;
#[cfg(test)]
mod dev_measurements_tests;
+38
View File
@@ -100,6 +100,7 @@ pub const TOOL_NAMES: &[&str] = &[
"set_properties",
"inspect_document",
"get_node",
"design_context",
"select",
"export",
"screenshot",
@@ -122,6 +123,7 @@ const DOCUMENT_TOOLS: &[&str] = &[
"set_properties",
"inspect_document",
"get_node",
"design_context",
"select",
"export",
"screenshot",
@@ -252,6 +254,22 @@ fn tools() -> Vec<Value> {
),
true,
),
tool(
"design_context",
"Design context",
"Everything needed to build a design, in one read: the selection (or `ids`, or `scope`) as a tree where each layer separates `explicit` values the designer set, `derived` ones layout worked out and `unsupported` ones CSS can't say directly, plus the variables, styles, components, fonts and assets it uses and what the design leaves `missing`. Implement connected instances with their `code`, never by rebuilding their layers. Large trees come back with `truncated`: ask again for the parts you need.",
obj(
json!({
"ids": ids_schema("Layers (default the selection)"),
"scope": {"type": "string", "enum": ["selection", "page", "document"], "description": "What to read without ids (default the selection, or the page when nothing is selected)"},
"depth": int("How deep the tree goes (default 32)"),
"maxNodes": int("Most layers in the tree (default 2000)"),
"maxBytes": int("The largest message your client reads (default 8 MiB): fewer layers come back to fit")
}),
&[],
),
true,
),
tool(
"select",
"Select layers",
@@ -419,6 +437,25 @@ fn exec(b: &mut dyn Backend, cmd: &str, params: Value) -> Result<Value, String>
b.call("engine.execute", json!({"command": cmd, "params": params}))
}
/// `inspect.designContext`, with fewer layers until the result fits what the client can read.
fn design_context(b: &mut dyn Backend, a: &Map<String, Value>) -> Result<ToolResult, String> {
let (_, budget) = budget(a)?;
let mut params = a.clone();
params.remove("maxBytes");
params.remove("document");
loop {
let value = exec(b, "inspect.designContext", Value::Object(params.clone()))?;
if wire_size(&value) <= budget {
return Ok(ToolResult::json(&value));
}
let layers = value.get("target").and_then(|t| t.get("layers")).and_then(Value::as_u64).unwrap_or(0);
if layers <= 1 {
return Err(format!("one layer's context is larger than {budget} bytes: call get_node with `fields` instead"));
}
params.insert("maxNodes".into(), json!(layers / 2));
}
}
fn wait_for_changes(b: &mut dyn Backend, a: &Map<String, Value>) -> Result<ToolResult, String> {
b.call("events.poll", Value::Object(a.clone())).map(|v| ToolResult::json(&v))
}
@@ -564,6 +601,7 @@ pub fn call_tool(b: &mut dyn Backend, name: &str, args: &Value) -> ToolResult {
"set_properties" => set_properties(b, &a),
"inspect_document" => inspect_document(b, &a),
"get_node" => get_node(b, &a),
"design_context" => design_context(b, &a),
"select" => select(b, &a),
"export" => export(b, &a),
"screenshot" => screenshot(b, &a),
+18
View File
@@ -210,3 +210,21 @@ fn invalid_compact_options_fail_in_tools_and_headless_control() {
}
}
}
#[test]
fn design_context_tool_reads_the_selection_and_fits_the_clients_limit() {
let mut c = Client::new();
let f = c.ok("create_node", json!({"type": "frame", "width": 400, "height": 400, "name": "Page"}));
let id = f["id"].clone();
for _ in 0..200 {
c.ok("create_node", json!({"type": "rectangle", "parent": id, "width": 4, "height": 4}));
}
c.ok("select", json!({"ids": [id]}));
let whole = c.ok("design_context", json!({}));
assert_eq!(whole["target"]["source"], "selection");
assert_eq!(whole["target"]["layers"], 201);
// Fewer layers come back rather than a message the client can't read.
let small = c.ok("design_context", json!({"maxBytes": 16384}));
assert!(small["target"]["layers"].as_u64().unwrap() < 201);
assert!(small["truncated"]["layersLeftOut"].as_u64().unwrap() > 0);
}
+36
View File
@@ -408,6 +408,7 @@ a later step can use `{"$step": 0, "field": "ids/0"}` to target the first match.
| `set_properties {ids, props}` | `node.set` on layers (geometry, fills, strokes, effects, corner radius, auto layout, sizing, constraints, masks (`isMask`, `maskType: alpha\|vector\|luminance`), handoff status (`devStatus: none\|readyForDev\|completed`; marking again clears "Changed"), a section's `sectionContentsHidden`, text…); returns the updated layers. |
| `inspect_document {depth, allPages, fields?, outline?}` | The document as JSON (its `id`, layer tree, styles, selection, history); `fields` selects layer properties, `outline: true` gives a compact tree (below). The tools that act on a document also take `document` (see Naming the document below). |
| `get_node {id, depth, fields?, outline?}` | One layer as JSON; takes the same `fields` and `outline` options; `pluginData` (`{key: value}`, values as strings) when the layer or page has layer data written with `set_properties {props: {pluginData}}`. |
| `design_context {ids?, scope?, depth?, maxNodes?, maxBytes?}` | Everything needed to build a design in one read: see [Design context](#design-context). |
| `select {ids}` | Replace the selection (`[]` deselects). |
| `export {ids, format, scale \| size, path?, bleed?, cropMarks?, bleedMarks?, cmyk?, contentsOnly?, includeBoundingBox?, svgOutlineText?, svgIdAttribute?, svgSimplifyStroke?, vdCompat?, colorProfile?, quality?}` | png, jpg, svg, webp, pdf, xml (an Android Vector Drawable: `svgIdAttribute` writes `android:name`, `vdCompat` is `bestEffort` (default: approximated with a warning), `exact` (left out with a warning) or `ignore` (no warnings: overlapping layer opacity dropped, even-odd fills kept as `fillType="evenOdd"`, diamond gradients left out), and the result lists `warnings` for what was changed or left out), or `fig`: the whole file as `.fig`, experimental (see Exporting `.fig` files below); `size` is `2x`, `512w` or `512h`; `quality` is the JPG quality, 1 to 100 (default 90). The image covers what the layers paint (shadows towards their offset, strokes, unclipped children, a mask group's mask; hidden layers take no room; a slice is its area with everything under it, or only the frame or group it sits in while `contentsOnly` is on); `contentsOnly: false` also draws every other layer showing in that area, `includeBoundingBox` exports the layers' own boxes; SVG: `svgOutlineText: false` keeps `<text>`, `svgIdAttribute` writes unique ids from layer names, `svgSimplifyStroke: false` writes every stroke as an outline; png, jpg and webp: `colorProfile` is `sameAsFile` (default: the document's profile), `srgb` or `displayP3`, the pixels converted (out-of-gamut colors clip) and the file tagged for it (PNG: `sRGB` chunk, or ICC and `cICP` for Display P3; JPG: ICC profile; WebP: ICC profile for Display P3, none for sRGB) (SVG, XML and RGB PDF output are always sRGB; PDF with `cmyk` is DeviceCMYK). The same options go in export settings (`export.add` / `export.update`). PDF: frames one page each (sized in points), anything else together on one page; print options: `bleed` (points or a length like `"3mm"`, `"0.125in"`), crop and bleed marks, CMYK colour (see Exports below), also taken by `file.export`, `file.exportLayers`, `file.exportFramesPdf` and stored per export setting by `export.add` / `export.update`; `run_command` `file.exportFramesPdf {page?, path?}` writes every top-level frame of a page. Without `path`, images come back as MCP image content, SVG as text, XML as text followed by `{format, bytes, warnings}`. Layers' own export settings: `run_command` with `export.add` / `export.update {index, size?, suffix?, format?}` / `export.remove` and `file.exportLayers {ids?, dir?, assets?}` (every layer once per setting, named `<layer><suffix>.<format>`, a slash in a layer name making a folder; `assets: true` exports the Inspect tab's assets instead: icons as SVG, images as PNG). |
| `screenshot {ids?, scale?, maxSize?, window?}` | PNG of the page (with background) or of layers, scaled to fit `maxSize` (default 1600). `window: true` captures the app window in front when attached, a window id (see Windows below) that window. |
@@ -419,6 +420,41 @@ a later step can use `{"$step": 0, "field": "ids/0"}` to target the first match.
| `inspect_ui {}` | Tool, view and status (and panels, timings and the app's `windows` when attached). |
| `wait_for_changes {after?, timeoutMs?, topics?, limit?}` | Wait for new comment events in the attached app; returns pending events at once, else waits up to `timeoutMs` (default 20 s, max 25 s). Pass the returned `cursor` back to keep watching. Headless returns immediately. |
### Design context
`design_context` (the command `inspect.designContext`) reads the selection, or `ids`, or `scope`
(`selection`, `page`, `document`; with nothing selected, the page). The result is one JSON object:
| Key | What it holds |
|---|---|
| `version` | The format's version; fields can be added without changing it |
| `document` | `name`, `page`, `colorProfile` |
| `target` | `source` (`selection`, `ids`, `page`, `document`), `ids`, `layers` in the tree |
| `nodes` | The tree, below |
| `variables` | By id: `name`, `collection`, `type`, `codeSyntax`, and `modes` with each `mode`'s stored `value` and `resolved` value |
| `styles` | By id: the shared styles the tree uses |
| `components` | By id: `name`, `type`, `properties` with variants, `codeLinks` |
| `fonts` | `family`, `styles`, and whether it's `installed` |
| `assets` | What `inspect.assets` lists for the same layers |
| `missing` | `{what, why}`: what the design doesn't specify. Always says that the file stores no breakpoints |
| `truncated` | When `depth` or `maxNodes` cut the tree, or `maxBytes` made the tool ask for fewer layers |
Each layer in `nodes` has `id`, `name`, `type` and:
- `explicit`: what the designer set, with the keys of `get_node`.
- `derived`: what the file worked out: `absoluteBounds`, `rotation`, `gridCell`, a position in an auto
layout flow, and a size that Hug, Fill or auto-sizing text decides.
- `tokens`: bound variables by field, and shared styles as `style.fill`, `style.text[0..5]` and so on,
with the `name` of each. `explicit` holds the value they resolved to.
- `unsupported`: `{property, why}` for what has no direct CSS equivalent. The value stays in `explicit`.
- `code`: for a component or instance connected to code, per language, `{language, importPath, name,
code}`, with the instance's own values in `code`. A connected instance stops there: `childCount`
says what it holds, and `get_node` reads it.
- `children`, or `childCount` where the tree stops.
Values are the file's own. Nothing is converted to CSS or guessed. Hidden layers are in the tree, with
`visible: false` in `explicit`.
### Compact layer trees
`inspect_document` and `get_node` accept `fields`, an array of exact, case-sensitive top-level node