mirror of
https://github.com/storytold/figcraft.git
synced 2026-11-19 00:27:49 +00:00
Merge pull request #2444 from B-uchi/pr/design-context
M8: design context for AI agents
This commit is contained in:
10 files changed
+983
No files matched your search
@@ -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. |
|
||||
|
||||
@@ -125,3 +125,6 @@ real_name = "Madhav Agarwal"
|
||||
[people.Aathish-D]
|
||||
real_name = "Aathish Duraiswamy"
|
||||
sync_github_name = true
|
||||
|
||||
[people.B-uchi]
|
||||
real_name = "Ibuchukwu Umeano"
|
||||
@@ -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());
|
||||
|
||||
@@ -0,0 +1,409 @@
|
||||
//! `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": "<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());
|
||||
}
|
||||
|
||||
/// A colour variable in collection Theme (Light, Dark): (collection id, variable id).
|
||||
fn variable(s: &mut Session, name: &str, light: &str, dark: &str) -> (Value, String) {
|
||||
let c = s.execute("variable.createCollection", &json!({"name": format!("{name} theme"), "modes": ["Light", "Dark"]})).unwrap()["id"].clone();
|
||||
let v = s.execute("variable.create", &json!({"collection": c, "name": name, "type": "color", "values": {"Light": light, "Dark": dark}})).unwrap();
|
||||
(c, v["id"].as_str().unwrap().to_string())
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_variable_an_alias_reads_is_joined_too() {
|
||||
let mut s = session();
|
||||
let (c, brand) = variable(&mut s, "brand", "#3B5BDB", "#748FFC");
|
||||
let button = s
|
||||
.execute("variable.create", &json!({"collection": c, "name": "button", "type": "color", "values": {"Light": "#000000", "Dark": "#000000"}}))
|
||||
.unwrap()["id"]
|
||||
.as_str()
|
||||
.unwrap()
|
||||
.to_string();
|
||||
for mode in ["Light", "Dark"] {
|
||||
s.execute("variable.set", &json!({"variable": button, "mode": mode, "value": {"alias": brand}})).unwrap();
|
||||
}
|
||||
let r = node(&mut s, json!({"type": "rectangle", "width": 10, "height": 10, "props": {"fill": {"$var": button}}}));
|
||||
let v = context(&mut s, json!({"ids": [r]}));
|
||||
assert!(v["variables"].get(&button).is_some());
|
||||
assert_eq!(v["variables"][&brand]["name"], "brand", "the aliased variable is defined as well: {}", v["variables"]);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_variable_a_shared_style_binds_is_joined() {
|
||||
let mut s = session();
|
||||
let (_, brand) = variable(&mut s, "brand", "#3B5BDB", "#748FFC");
|
||||
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/Fill", "from": r})).unwrap()["id"].clone();
|
||||
s.execute("style.bind", &json!({"style": st, "field": "fill", "variable": brand})).unwrap();
|
||||
s.execute("style.apply", &json!({"style": st, "ids": [r]})).unwrap();
|
||||
let v = context(&mut s, json!({"ids": [r]}));
|
||||
assert_eq!(only(&v)["tokens"]["style.fill"]["name"], "Brand/Fill");
|
||||
assert_eq!(v["variables"][&brand]["name"], "brand", "the style's variable is defined: {}", v["variables"]);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn every_returned_text_layer_has_its_font_listed() {
|
||||
let mut s = session();
|
||||
let title = node(&mut s, json!({"type": "text", "text": "Title", "props": {"fontFamily": "Serif Display Test"}}));
|
||||
let busy = node(&mut s, json!({"type": "frame", "x": 300, "width": 200, "height": 200}));
|
||||
for _ in 0..12 {
|
||||
node(&mut s, json!({"type": "rectangle", "parent": busy, "width": 4, "height": 4}));
|
||||
}
|
||||
let v = context(&mut s, json!({"ids": [title, busy], "maxNodes": 2}));
|
||||
assert_eq!(v["target"]["layers"], 2);
|
||||
let families: Vec<&str> = v["fonts"].as_array().unwrap().iter().map(|f| f["family"].as_str().unwrap()).collect();
|
||||
assert_eq!(families, ["Serif Display Test"], "{}", v["fonts"]);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_malformed_target_is_refused_rather_than_read_as_the_selection() {
|
||||
let mut s = session();
|
||||
let (f, _, _) = card(&mut s);
|
||||
s.execute("select.set", &json!({"ids": [f]})).unwrap();
|
||||
for p in [json!({"id": "not-an-id"}), json!({"id": true}), json!({"ids": [f, "nope"]}), json!({"ids": "1"})] {
|
||||
assert!(s.execute("inspect.designContext", &p).is_err(), "{p}");
|
||||
}
|
||||
assert_eq!(context(&mut s, json!({"ids": []}))["target"]["layers"], 0, "an empty list reads nothing");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_font_stored_with_outer_spaces_isnt_taken_for_installed() {
|
||||
let mut s = session();
|
||||
let t = node(&mut s, json!({"type": "text", "text": "Hi", "props": {"fontFamily": " Missing Display Test "}}));
|
||||
let v = context(&mut s, json!({"ids": [t]}));
|
||||
let font = &v["fonts"][0];
|
||||
assert_eq!(font["family"], " Missing Display Test ", "the spelling stays as stored");
|
||||
assert_eq!(font["installed"], false, "{font}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn assets_follow_the_layers_returned_and_say_what_was_left_out() {
|
||||
let mut s = session();
|
||||
let frame = node(&mut s, json!({"type": "frame", "width": 400, "height": 400}));
|
||||
for seed in 0..20u8 {
|
||||
let img = image::RgbImage::from_fn(4, 4, |x, y| image::Rgb([x as u8, y as u8, seed]));
|
||||
let mut bytes = Vec::new();
|
||||
img.write_to(&mut std::io::Cursor::new(&mut bytes), image::ImageFormat::Png).unwrap();
|
||||
let data = base64::Engine::encode(&base64::engine::general_purpose::STANDARD, &bytes);
|
||||
s.execute("image.place", &json!({"data": data, "parent": frame})).unwrap();
|
||||
}
|
||||
let all = context(&mut s, json!({"ids": [frame]}));
|
||||
assert_eq!(all["assets"].as_array().unwrap().len(), 20);
|
||||
let few = context(&mut s, json!({"ids": [frame], "maxNodes": 5}));
|
||||
let shown = few["assets"].as_array().unwrap().len();
|
||||
assert_eq!(shown, 4, "only the images among the 5 layers returned");
|
||||
assert_eq!(few["truncated"]["assetsLeftOut"], 16);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_join_stopped_at_its_budget_says_so() {
|
||||
let mut s = session();
|
||||
let (c, first) = variable(&mut s, "v0", "#000000", "#000000");
|
||||
let mut prev = first.clone();
|
||||
for k in 1..6 {
|
||||
let next = s
|
||||
.execute(
|
||||
"variable.create",
|
||||
&json!({"collection": c, "name": format!("v{k}"), "type": "color", "values": {"Light": "#111111", "Dark": "#111111"}}),
|
||||
)
|
||||
.unwrap()["id"]
|
||||
.as_str()
|
||||
.unwrap()
|
||||
.to_string();
|
||||
for mode in ["Light", "Dark"] {
|
||||
s.execute("variable.set", &json!({"variable": prev, "mode": mode, "value": {"alias": next}})).unwrap();
|
||||
}
|
||||
prev = next;
|
||||
}
|
||||
let start = std::collections::BTreeSet::from([first]);
|
||||
let none = std::collections::BTreeSet::new();
|
||||
let (all, complete) = crate::design_context::referenced(s.doc().unwrap(), &start, &none, 100);
|
||||
assert_eq!((all.len(), complete), (6, true));
|
||||
let (some, complete) = crate::design_context::referenced(s.doc().unwrap(), &start, &none, 3);
|
||||
assert_eq!((some.len(), complete), (3, false), "{some:?}");
|
||||
}
|
||||
@@ -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;
|
||||
|
||||
@@ -0,0 +1,473 @@
|
||||
//! Design context: what an AI agent needs to build a design, in one read (`inspect.designContext`,
|
||||
//! the MCP tool `design_context`). The selection by default, as a tree in which every layer keeps
|
||||
//! apart what the designer set (`explicit`), what layout or the file worked out (`derived`) and
|
||||
//! what has no direct CSS equivalent (`unsupported`, with the reason). The variables, styles and
|
||||
//! components the tree uses are joined once at the top level, and a connected instance gives its
|
||||
//! code instead of its layers. Values are the file's own: nothing is guessed or converted, and
|
||||
//! `missing` says what the design doesn't specify.
|
||||
|
||||
use std::collections::{BTreeMap, BTreeSet};
|
||||
|
||||
use figcraft_color::{GradientKind, PaintKind};
|
||||
use figcraft_doc::{Document, EffectKind, Node, NodeId, NodeKind, Sizing, StrokeAlign, TextAutoResize};
|
||||
use serde_json::{Map, Value, json};
|
||||
|
||||
use crate::cmd::CommandSpec;
|
||||
use crate::cmd::component::describe_props;
|
||||
use crate::code_connect;
|
||||
use crate::codegen::CodeLang;
|
||||
use crate::inspect::{camel, node_json};
|
||||
use crate::params::{get, num, string, targets};
|
||||
use crate::{Result, Session, bad, spec};
|
||||
|
||||
/// The format's version: fields may be added without changing it.
|
||||
const VERSION: u64 = 1;
|
||||
/// How deep the tree goes by default.
|
||||
const DEFAULT_DEPTH: usize = 32;
|
||||
/// The deepest tree asked for.
|
||||
const MAX_DEPTH: usize = 128;
|
||||
/// How many layers it holds by default.
|
||||
const DEFAULT_NODES: usize = 2_000;
|
||||
/// The most layers asked for.
|
||||
const MAX_NODES: usize = 20_000;
|
||||
|
||||
/// Worked out rather than set, whatever the layer.
|
||||
const DERIVED: [&str; 3] = ["absoluteBounds", "rotation", "gridCell"];
|
||||
|
||||
/// What the tree used, to join at the top level.
|
||||
#[derive(Default)]
|
||||
struct Used {
|
||||
variables: BTreeSet<String>,
|
||||
styles: BTreeSet<String>,
|
||||
components: BTreeSet<NodeId>,
|
||||
/// Layers placed so far, and those left out for the cap.
|
||||
nodes: usize,
|
||||
left_out: usize,
|
||||
/// Reached `depth` with children left.
|
||||
cut_by_depth: bool,
|
||||
/// The layers placed.
|
||||
placed: BTreeSet<NodeId>,
|
||||
/// Font families of the text layers placed, with their styles.
|
||||
fonts: BTreeMap<String, BTreeSet<String>>,
|
||||
}
|
||||
|
||||
/// `property` of a layer has no direct CSS equivalent, because `why`.
|
||||
fn limit(out: &mut Vec<Value>, property: &str, why: &str) {
|
||||
out.push(json!({"property": property, "why": why}));
|
||||
}
|
||||
|
||||
/// What of `n` CSS can't say directly. The original values stay in `explicit`.
|
||||
fn limits(n: &Node) -> Vec<Value> {
|
||||
let mut out = Vec::new();
|
||||
if matches!(n.blend, figcraft_color::BlendMode::PlusDarker) {
|
||||
limit(&mut out, "blend", "only some browsers have the plus-darker blend mode");
|
||||
}
|
||||
if n.corners.smoothing > 0.0 {
|
||||
limit(&mut out, "cornerSmoothing", "CSS border-radius has no corner smoothing");
|
||||
}
|
||||
if !n.strokes.is_empty() {
|
||||
match n.stroke.align {
|
||||
StrokeAlign::Inside => {}
|
||||
StrokeAlign::Center => limit(&mut out, "strokeAlign", "a CSS border can't straddle the box edge"),
|
||||
StrokeAlign::Outside => {
|
||||
limit(&mut out, "strokeAlign", "a CSS border sits inside the box's border area: an outline or box-shadow comes closest")
|
||||
}
|
||||
}
|
||||
if n.stroke.profile().is_some() {
|
||||
limit(&mut out, "widthProfile", "CSS strokes have one width");
|
||||
}
|
||||
if n.stroke.brush.is_some() {
|
||||
limit(&mut out, "brush", "CSS has no brush strokes");
|
||||
}
|
||||
}
|
||||
for p in n.fills.iter().chain(&n.strokes) {
|
||||
match &p.kind {
|
||||
PaintKind::Gradient(g) if g.kind == GradientKind::Diamond => limit(&mut out, "fills", "CSS has no diamond gradient"),
|
||||
PaintKind::Pattern(_) => limit(&mut out, "fills", "a pattern fill needs an image or an SVG pattern in CSS"),
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
for e in &n.effects {
|
||||
match e.kind {
|
||||
EffectKind::Noise(_) => limit(&mut out, "effects", "CSS has no noise effect"),
|
||||
EffectKind::Texture(_) => limit(&mut out, "effects", "CSS has no roughened edge effect"),
|
||||
EffectKind::Glass(_) => limit(&mut out, "effects", "CSS has no curved glass effect"),
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
if let NodeKind::Text(t) = &n.kind {
|
||||
if t.path.is_some() {
|
||||
limit(&mut out, "textPath", "text on a path needs SVG");
|
||||
}
|
||||
if t.leading_trim != figcraft_doc::LeadingTrim::None {
|
||||
limit(&mut out, "leadingTrim", "CSS text-box-trim isn't in every browser");
|
||||
}
|
||||
if t.hanging_punctuation {
|
||||
limit(&mut out, "hangingPunctuation", "CSS hanging-punctuation isn't in every browser");
|
||||
}
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
/// Moves `key` of `explicit` to `derived`.
|
||||
fn derive(explicit: &mut Map<String, Value>, derived: &mut Map<String, Value>, key: &str) {
|
||||
if let Some(v) = explicit.remove(key) {
|
||||
derived.insert(key.into(), v);
|
||||
}
|
||||
}
|
||||
|
||||
/// Splits a layer's properties: a size or a position that layout decides isn't the designer's.
|
||||
fn split(doc: &Document, n: &Node, explicit: &mut Map<String, Value>) -> Map<String, Value> {
|
||||
let mut derived = Map::new();
|
||||
for key in DERIVED {
|
||||
derive(explicit, &mut derived, key);
|
||||
}
|
||||
let in_flow = n.parent.and_then(|p| doc.node(p)).is_some_and(|p| p.layout.is_some()) && !n.child_layout.absolute;
|
||||
if in_flow {
|
||||
derive(explicit, &mut derived, "x");
|
||||
derive(explicit, &mut derived, "y");
|
||||
}
|
||||
let (mut wide, mut tall) = (n.child_layout.sizing_h != Sizing::Fixed, n.child_layout.sizing_v != Sizing::Fixed);
|
||||
if let NodeKind::Text(t) = &n.kind {
|
||||
wide |= t.auto_resize == TextAutoResize::WidthAndHeight;
|
||||
tall |= matches!(t.auto_resize, TextAutoResize::WidthAndHeight | TextAutoResize::Height);
|
||||
}
|
||||
if wide {
|
||||
derive(explicit, &mut derived, "width");
|
||||
}
|
||||
if tall {
|
||||
derive(explicit, &mut derived, "height");
|
||||
}
|
||||
derived
|
||||
}
|
||||
|
||||
/// What a layer's tokens are called: bindings by field, shared styles by kind, as they would be
|
||||
/// looked up in the top-level `variables` and `styles`.
|
||||
fn tokens(doc: &Document, n: &Node, used: &mut Used) -> Map<String, Value> {
|
||||
let mut out = Map::new();
|
||||
for (field, id) in &n.bound {
|
||||
used.variables.insert(id.clone());
|
||||
let name = doc.variables.variables.iter().find(|v| v.id == *id).map(|v| v.name.clone());
|
||||
out.insert(field.clone(), json!({"variable": id, "name": name}));
|
||||
}
|
||||
let refs = &n.styles;
|
||||
let mut styles: Vec<(String, &String)> =
|
||||
[("fill", &refs.fill), ("stroke", &refs.stroke), ("effect", &refs.effect), ("grid", &refs.grid), ("text", &refs.text)]
|
||||
.into_iter()
|
||||
.filter_map(|(k, s)| s.as_ref().map(|s| (format!("style.{k}"), s)))
|
||||
.collect();
|
||||
if let NodeKind::Text(t) = &n.kind {
|
||||
let spans = t.spans();
|
||||
styles.extend(spans.iter().filter_map(|(a, b, s)| s.style_id.as_ref().map(|i| (format!("style.text[{a}..{b}]"), i))));
|
||||
}
|
||||
for (key, id) in styles {
|
||||
used.styles.insert(id.clone());
|
||||
let name = doc.styles.iter().find(|s| s.id == *id).map(|s| s.name.clone());
|
||||
out.insert(key, json!({"style": id, "name": name}));
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
/// The code component a component, set or instance is connected to, per language, with the
|
||||
/// instance's own values in its snippet.
|
||||
fn code(doc: &Document, id: NodeId) -> Vec<Value> {
|
||||
let Some(owner) = code_connect::owner(doc, id).and_then(|o| doc.node(o)) else { return vec![] };
|
||||
owner
|
||||
.code_links
|
||||
.iter()
|
||||
.filter_map(|l| {
|
||||
let lang = CodeLang::from_id(&l.language)?;
|
||||
let snippet = code_connect::connected_code(doc, id, lang, l)?;
|
||||
Some(json!({"language": l.language, "importPath": l.import_path, "name": l.name, "code": snippet}))
|
||||
})
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// Layer `id` and, to `depth`, what's under it, while the cap holds.
|
||||
fn layer(doc: &Document, id: NodeId, depth: usize, cap: usize, used: &mut Used) -> Option<Value> {
|
||||
let n = doc.node(id)?;
|
||||
used.nodes += 1;
|
||||
used.placed.insert(id);
|
||||
if let NodeKind::Text(t) = &n.kind {
|
||||
for (_, _, style) in t.spans() {
|
||||
used.fonts.entry(style.font_family.clone()).or_default().insert(style.font_style.clone());
|
||||
}
|
||||
}
|
||||
let Value::Object(mut explicit) = node_json(doc, id, 0) else { return None };
|
||||
explicit.remove("childCount");
|
||||
let mut out = Map::new();
|
||||
for key in ["id", "name", "type"] {
|
||||
if let Some(v) = explicit.remove(key) {
|
||||
out.insert(key.into(), v);
|
||||
}
|
||||
}
|
||||
let derived = split(doc, n, &mut explicit);
|
||||
let tokens = tokens(doc, n, used);
|
||||
let unsupported = limits(n);
|
||||
out.insert("explicit".into(), Value::Object(explicit));
|
||||
if !derived.is_empty() {
|
||||
out.insert("derived".into(), Value::Object(derived));
|
||||
}
|
||||
if !tokens.is_empty() {
|
||||
out.insert("tokens".into(), Value::Object(tokens));
|
||||
}
|
||||
if !unsupported.is_empty() {
|
||||
out.insert("unsupported".into(), Value::Array(unsupported));
|
||||
}
|
||||
if let Some(owner) = code_connect::owner(doc, id) {
|
||||
used.components.insert(owner);
|
||||
}
|
||||
let connected = code(doc, id);
|
||||
// An instance built from a code component needs its call, not its layers.
|
||||
let stop = matches!(n.kind, NodeKind::Instance { .. }) && !connected.is_empty();
|
||||
if !connected.is_empty() {
|
||||
out.insert("code".into(), Value::Array(connected));
|
||||
}
|
||||
if n.children.is_empty() {
|
||||
return Some(Value::Object(out));
|
||||
}
|
||||
if stop {
|
||||
out.insert("childCount".into(), json!(n.children.len()));
|
||||
return Some(Value::Object(out));
|
||||
}
|
||||
if depth == 0 {
|
||||
used.cut_by_depth = true;
|
||||
out.insert("childCount".into(), json!(n.children.len()));
|
||||
return Some(Value::Object(out));
|
||||
}
|
||||
let mut children = Vec::new();
|
||||
for c in &n.children {
|
||||
if used.nodes >= cap {
|
||||
used.left_out += 1;
|
||||
continue;
|
||||
}
|
||||
children.extend(layer(doc, *c, depth - 1, cap, used));
|
||||
}
|
||||
if children.len() < n.children.len() {
|
||||
out.insert("childCount".into(), json!(n.children.len()));
|
||||
}
|
||||
out.insert("children".into(), Value::Array(children));
|
||||
Some(Value::Object(out))
|
||||
}
|
||||
|
||||
/// A value as the panels show it: colours in hex.
|
||||
fn value_json(v: &figcraft_doc::VariableValue) -> Value {
|
||||
match v {
|
||||
figcraft_doc::VariableValue::Color(c) => json!(c.to_css_hex()),
|
||||
figcraft_doc::VariableValue::Number(n) => json!(n),
|
||||
figcraft_doc::VariableValue::String(s) => json!(s),
|
||||
figcraft_doc::VariableValue::Boolean(b) => json!(b),
|
||||
other => serde_json::to_value(other).unwrap_or(Value::Null),
|
||||
}
|
||||
}
|
||||
|
||||
/// `ids`' variables: every mode's stored and resolved value. A value that is an alias or a
|
||||
/// calculation stays in `value`; the variables it reads are in `ids` too ([`referenced`]).
|
||||
fn variables_json(doc: &Document, ids: &BTreeSet<String>, missing: &mut Vec<Value>) -> Value {
|
||||
let store = &doc.variables;
|
||||
let mut out = Map::new();
|
||||
for id in ids {
|
||||
let Some(var) = store.variables.iter().find(|v| v.id == *id) else {
|
||||
missing.push(json!({"what": "variable", "id": id, "why": "a layer is bound to it, but it isn't in this file"}));
|
||||
continue;
|
||||
};
|
||||
let collection = store.collection_by_id(&var.collection);
|
||||
let modes: Vec<Value> = collection
|
||||
.map(|c| c.modes.as_slice())
|
||||
.unwrap_or_default()
|
||||
.iter()
|
||||
.map(|m| {
|
||||
let chosen = BTreeMap::from([(var.collection.clone(), m.id.clone())]);
|
||||
json!({
|
||||
"mode": m.name,
|
||||
"value": var.values.get(&m.id).map(value_json),
|
||||
"resolved": store.resolve(id, &chosen).as_ref().map(value_json),
|
||||
})
|
||||
})
|
||||
.collect();
|
||||
let mut v = json!({"name": var.name, "collection": collection.map(|c| c.name.as_str()), "type": var.kind, "modes": modes});
|
||||
if !var.code_syntax.is_empty() {
|
||||
v["codeSyntax"] = json!(var.code_syntax);
|
||||
}
|
||||
if !var.description.is_empty() {
|
||||
v["description"] = json!(var.description);
|
||||
}
|
||||
out.insert(id.clone(), v);
|
||||
}
|
||||
Value::Object(out)
|
||||
}
|
||||
|
||||
/// Most variables followed through aliases.
|
||||
const MAX_VARIABLES: usize = 10_000;
|
||||
|
||||
/// The variables a tree uses: those its layers bind (`bound`), those its shared `styles` bind, and
|
||||
/// those any of them reads as an alias or in a colour calculation, however deep, up to `max`. The
|
||||
/// flag is false when `max` stopped it with variables still to follow.
|
||||
pub(crate) fn referenced(doc: &Document, bound: &BTreeSet<String>, styles: &BTreeSet<String>, max: usize) -> (BTreeSet<String>, bool) {
|
||||
let mut out: BTreeSet<String> = BTreeSet::new();
|
||||
let mut todo: Vec<String> = bound.iter().cloned().collect();
|
||||
todo.extend(doc.styles.iter().filter(|st| styles.contains(&st.id)).flat_map(|st| st.bound.values().cloned()));
|
||||
todo.reverse();
|
||||
while let Some(id) = todo.pop() {
|
||||
if out.contains(&id) {
|
||||
continue;
|
||||
}
|
||||
if out.len() >= max {
|
||||
return (out, false);
|
||||
}
|
||||
out.insert(id.clone());
|
||||
let Some(var) = doc.variables.variables.iter().find(|v| v.id == id) else { continue };
|
||||
for value in var.values.values() {
|
||||
match value {
|
||||
figcraft_doc::VariableValue::Alias(other) => todo.push(other.clone()),
|
||||
figcraft_doc::VariableValue::ColorAlpha { variable, .. } => todo.push(variable.clone()),
|
||||
figcraft_doc::VariableValue::ColorMix { from, to, .. } => todo.extend(from.variable().into_iter().chain(to.variable()).cloned()),
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
}
|
||||
(out, true)
|
||||
}
|
||||
|
||||
/// The shared styles the tree uses, with what each sets.
|
||||
fn styles_json(doc: &Document, ids: &BTreeSet<String>, missing: &mut Vec<Value>) -> Value {
|
||||
let mut out = Map::new();
|
||||
for id in ids {
|
||||
match doc.styles.iter().find(|s| s.id == *id) {
|
||||
Some(st) => {
|
||||
out.insert(id.clone(), camel(serde_json::to_value(st).unwrap_or(Value::Null)));
|
||||
}
|
||||
None => missing.push(json!({"what": "style", "id": id, "why": "a layer links to it, but it isn't in this file"})),
|
||||
}
|
||||
}
|
||||
Value::Object(out)
|
||||
}
|
||||
|
||||
/// The components and sets the tree uses: their properties, variants and code.
|
||||
fn components_json(doc: &Document, ids: &BTreeSet<NodeId>) -> Value {
|
||||
let mut out = Map::new();
|
||||
for id in ids {
|
||||
let Some(n) = doc.node(*id) else { continue };
|
||||
let mut v = json!({"name": n.name, "type": n.kind.type_name(), "properties": describe_props(doc, *id)["properties"]});
|
||||
if let NodeKind::Component { description, .. } = &n.kind
|
||||
&& !description.is_empty()
|
||||
{
|
||||
v["description"] = json!(description);
|
||||
}
|
||||
if !n.code_links.is_empty() {
|
||||
v["codeLinks"] = camel(serde_json::to_value(&n.code_links).unwrap_or(Value::Null));
|
||||
}
|
||||
out.insert(id.to_string(), v);
|
||||
}
|
||||
Value::Object(out)
|
||||
}
|
||||
|
||||
/// The font families the tree's text layers use, with their styles, and whether each is installed
|
||||
/// (the family name trimmed, as the missing-fonts list reads it). The spelling stays as stored.
|
||||
fn fonts(used: &BTreeMap<String, BTreeSet<String>>) -> Value {
|
||||
Value::Array(
|
||||
used.iter()
|
||||
.map(|(family, styles)| json!({"family": family, "styles": styles, "installed": figcraft_text::has_family(family.trim())}))
|
||||
.collect(),
|
||||
)
|
||||
}
|
||||
|
||||
/// What the request names: (where it came from, the layers).
|
||||
fn roots(s: &Session, p: &Value) -> Result<(&'static str, Vec<NodeId>)> {
|
||||
let cmd = "inspect.designContext";
|
||||
let doc = s.doc()?;
|
||||
let malformed = || bad(cmd, "ids: a list of layer ids (or id: one)");
|
||||
match (get(p, "ids"), get(p, "id")) {
|
||||
(Some(Value::Array(list)), _) if list.iter().all(|i| crate::params::id_of(i).is_some()) => {}
|
||||
(Some(_), _) => return Err(malformed()),
|
||||
(None, Some(one)) if crate::params::id_of(one).is_none() => return Err(malformed()),
|
||||
_ => {}
|
||||
}
|
||||
if get(p, "ids").is_some() || get(p, "id").is_some() {
|
||||
let ids: Vec<NodeId> = targets(s, p);
|
||||
if let Some(gone) = ids.iter().find(|i| !doc.contains(**i)) {
|
||||
return Err(bad(cmd, format!("no layer {gone}")));
|
||||
}
|
||||
return Ok(("ids", ids));
|
||||
}
|
||||
let page = |pg: NodeId| doc.node(pg).map(|n| n.children.clone()).unwrap_or_default();
|
||||
match string(p, "scope").as_deref() {
|
||||
None | Some("selection") => match s.selection() {
|
||||
ids if ids.is_empty() => Ok(("page", page(s.page()?))),
|
||||
ids => Ok(("selection", ids)),
|
||||
},
|
||||
Some("page") => Ok(("page", page(s.page()?))),
|
||||
Some("document") => Ok(("document", doc.pages.iter().flat_map(|pg| page(*pg)).collect())),
|
||||
Some(_) => Err(bad(cmd, "scope: selection|page|document")),
|
||||
}
|
||||
}
|
||||
|
||||
/// A whole-number parameter within `1..=max`.
|
||||
fn limit_param(p: &Value, key: &str, default: usize, max: usize) -> Result<usize> {
|
||||
match get(p, key) {
|
||||
None | Some(Value::Null) => Ok(default),
|
||||
Some(_) => match num(p, key).filter(|v| v.is_finite() && *v >= 0.0) {
|
||||
Some(v) => Ok((v as usize).min(max)),
|
||||
None => Err(bad("inspect.designContext", format!("{key}: a whole number"))),
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
fn design_context(s: &mut Session, p: &Value) -> Result<Value> {
|
||||
let (source, ids) = roots(s, p)?;
|
||||
let depth = limit_param(p, "depth", DEFAULT_DEPTH, MAX_DEPTH)?;
|
||||
let cap = limit_param(p, "maxNodes", DEFAULT_NODES, MAX_NODES)?.max(1);
|
||||
let doc = s.doc()?;
|
||||
let mut used = Used::default();
|
||||
let mut nodes = Vec::new();
|
||||
for id in &ids {
|
||||
if used.nodes >= cap {
|
||||
used.left_out += 1;
|
||||
continue;
|
||||
}
|
||||
nodes.extend(layer(doc, *id, depth, cap, &mut used));
|
||||
}
|
||||
let mut missing = vec![
|
||||
json!({"what": "responsive behaviour", "why": "the file stores no breakpoints: sizes are as designed here, and constraints, sizing and annotations are all it says about other widths"}),
|
||||
];
|
||||
let (joined, complete) = referenced(doc, &used.variables, &used.styles, MAX_VARIABLES);
|
||||
let variables = variables_json(doc, &joined, &mut missing);
|
||||
let styles = styles_json(doc, &used.styles, &mut missing);
|
||||
let components = components_json(doc, &used.components);
|
||||
let fonts = fonts(&used.fonts);
|
||||
let page = doc.node(s.page()?).map(|n| n.name.clone());
|
||||
// The assets of the layers returned: a smaller tree means a smaller list.
|
||||
let found = crate::devinspect::assets(doc, &ids);
|
||||
let assets: Vec<&crate::devinspect::Asset> = found.iter().filter(|a| used.placed.contains(&a.id)).collect();
|
||||
let assets_left_out = found.len() - assets.len();
|
||||
let mut out = json!({
|
||||
"version": VERSION,
|
||||
"document": {"name": doc.name, "page": {"id": s.page()?, "name": page}, "colorProfile": doc.color_profile.id()},
|
||||
"target": {"source": source, "ids": ids, "layers": used.nodes},
|
||||
"nodes": nodes,
|
||||
"variables": variables,
|
||||
"styles": styles,
|
||||
"components": components,
|
||||
"fonts": fonts,
|
||||
"assets": assets,
|
||||
"missing": missing,
|
||||
});
|
||||
if used.left_out > 0 || used.cut_by_depth {
|
||||
out["truncated"] = json!({"layersLeftOut": used.left_out, "assetsLeftOut": assets_left_out, "depth": used.cut_by_depth, "maxNodes": cap, "hint": "call again with the ids of the parts you need"});
|
||||
}
|
||||
if !complete {
|
||||
out["truncated"]["variables"] =
|
||||
json!({"maxVariables": MAX_VARIABLES, "why": "aliases go deeper than this: some variables they read aren't defined here"});
|
||||
}
|
||||
Ok(out)
|
||||
}
|
||||
|
||||
pub fn specs() -> Vec<CommandSpec> {
|
||||
vec![spec!(
|
||||
"inspect.designContext",
|
||||
"Design context",
|
||||
"{ids? | id? (those layers), scope?: selection|page|document (default the selection, or the page with nothing selected), depth? (default 32), maxNodes? (default 2000)} everything needed to build them, in one read → {version, document, target {source, ids, layers}, nodes [{id, name, type, explicit, derived?, tokens?, unsupported? [{property, why}], code?, children?, childCount?}], variables, styles, components, fonts, assets, missing [{what, why}], truncated?}",
|
||||
false,
|
||||
design_context
|
||||
)]
|
||||
}
|
||||
@@ -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;
|
||||
@@ -286,6 +287,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;
|
||||
|
||||
@@ -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),
|
||||
|
||||
@@ -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
@@ -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. The tree's layers and shared styles bind them, or another one reads them as an alias or in a colour calculation |
|
||||
| `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 layers in the tree |
|
||||
| `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: `layersLeftOut`, `assetsLeftOut`, `depth`, `maxNodes`; and `variables` when aliases went deeper than the 10,000 variables followed |
|
||||
|
||||
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
|
||||
|
||||
Reference in new issue
Block a user