diff --git a/ROADMAP.md b/ROADMAP.md
index 107a11f96..95e1a67ef 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -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. |
diff --git a/crates/engine/src/cmd.rs b/crates/engine/src/cmd.rs
index 0e90dc198..b90204504 100644
--- a/crates/engine/src/cmd.rs
+++ b/crates/engine/src/cmd.rs
@@ -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());
diff --git a/crates/engine/src/design_context_tests.rs b/crates/engine/src/design_context_tests.rs
new file mode 100644
index 000000000..3aa0ab09b
--- /dev/null
+++ b/crates/engine/src/design_context_tests.rs
@@ -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", ¶ms).unwrap())
+}
+
+fn context(s: &mut Session, params: Value) -> Value {
+ s.execute("inspect.designContext", ¶ms).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": ""}))
+ .unwrap();
+ let v = context(&mut s, json!({"ids": [instance]}));
+ let n = only(&v);
+ assert!(n["code"][0]["code"].as_str().unwrap().contains(""), "{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());
+}
diff --git a/crates/engine/src/dev.rs b/crates/engine/src/dev.rs
index bc46aae9f..a1bc7bb18 100644
--- a/crates/engine/src/dev.rs
+++ b/crates/engine/src/dev.rs
@@ -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;
diff --git a/crates/engine/src/dev/design_context.rs b/crates/engine/src/dev/design_context.rs
new file mode 100644
index 000000000..bb2d6aff5
--- /dev/null
+++ b/crates/engine/src/dev/design_context.rs
@@ -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,
+ styles: BTreeSet,
+ components: BTreeSet,
+ /// 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, 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 {
+ 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, derived: &mut Map, 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) -> Map {
+ 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 {
+ 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 {
+ 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 {
+ 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, missing: &mut Vec) -> 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 = 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, missing: &mut Vec) -> 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) -> 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> = BTreeMap::new();
+ let mut stack: Vec = 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)> {
+ let cmd = "inspect.designContext";
+ let doc = s.doc()?;
+ if get(p, "ids").is_some() || get(p, "id").is_some() {
+ let ids: Vec = 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 {
+ 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 {
+ 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 {
+ 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
+ )]
+}
diff --git a/crates/engine/src/lib.rs b/crates/engine/src/lib.rs
index 6fe5633ad..98c87951c 100644
--- a/crates/engine/src/lib.rs
+++ b/crates/engine/src/lib.rs
@@ -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;
diff --git a/crates/mcp/src/tools.rs b/crates/mcp/src/tools.rs
index 9a546dc2a..7fb32e984 100644
--- a/crates/mcp/src/tools.rs
+++ b/crates/mcp/src/tools.rs
@@ -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 {
),
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
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) -> Result {
+ 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) -> Result {
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),
diff --git a/crates/mcp/tests/it/inspect_fields.rs b/crates/mcp/tests/it/inspect_fields.rs
index 930ba3c78..9ea79905c 100644
--- a/crates/mcp/tests/it/inspect_fields.rs
+++ b/crates/mcp/tests/it/inspect_fields.rs
@@ -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);
+}
diff --git a/docs/mcp.md b/docs/mcp.md
index 8940fa184..cad511f21 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -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 ``, `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 `.`, 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