From 2d4309c9aa61facdea6c698e0010fee43a2e5558 Mon Sep 17 00:00:00 2001 From: B-uchi Date: Wed, 18 Nov 2026 08:20:59 +0100 Subject: [PATCH 1/4] 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. --- ROADMAP.md | 1 + crates/engine/src/cmd.rs | 1 + crates/engine/src/design_context_tests.rs | 288 ++++++++++++++ crates/engine/src/dev.rs | 1 + crates/engine/src/dev/design_context.rs | 434 ++++++++++++++++++++++ crates/engine/src/lib.rs | 3 + crates/mcp/src/tools.rs | 38 ++ crates/mcp/tests/it/inspect_fields.rs | 18 + docs/mcp.md | 36 ++ 9 files changed, 820 insertions(+) create mode 100644 crates/engine/src/design_context_tests.rs create mode 100644 crates/engine/src/dev/design_context.rs 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": "