Merge pull request #6608 from dotCooCoo/fix/inspect-pending-read-root

MCP: ui.inspect leaves out paths outside the read roots

crates/ui-egui/src/control.rs

@@ -249,8 +249,9 @@ pub fn inspect(app: &VectorcraftApp, ctx: &egui::Context) -> Value {
     // the layout.
     if let Some(fields) = ui.as_object_mut() {
         fields.remove("floating_panels");
+        leave_out_unreadable_paths(fields);
     }
-    json!({
+    let mut inspected = json!({
         "scriptRunning": app.session.script_running(),
         "scriptReport": app.session.script_report(),
         "tool": app.session.tool_id(),
@@ -294,8 +295,9 @@ pub fn inspect(app: &VectorcraftApp, ctx: &egui::Context) -> Value {
         "nativeMenuBar": app.services.native_menu.is_some(),
         // Saves and exports still being written in the background (Background Save / Export).
         "background": app.background.jobs.iter().filter(|j| !j.label.is_empty()).map(|j| j.label.as_str()).collect::<Vec<_>>(),
-        // Documents still being read off the UI thread (File › Open, Open Recent): their paths.
-        "opening": app.opening.pending.iter().map(|p| p.path.as_str()).collect::<Vec<_>>(),
+        // Documents still being read off the UI thread (File › Open, Open Recent): their paths, without
+        // the ones outside the read root.
+        "opening": app.opening.pending.iter().map(|p| p.path.as_str()).filter(|p| readable(p)).collect::<Vec<_>>(),
         // Files still being read off the UI thread for Place (the Place dialog's OK, drops): their
         // names, in the order they are placed.
         "placing": app.placing.pending.iter().map(|p| p.name.as_str()).collect::<Vec<_>>(),
@@ -305,7 +307,173 @@ pub fn inspect(app: &VectorcraftApp, ctx: &egui::Context) -> Value {
         // A native file dialog open off the UI thread (`open`, `place`, `save`, `folder`), waiting
         // for the person at the computer: what asked for it runs again when it answers.
         "fileDialog": app.picks.waiting_kind(),
-    })
+    });
+    let ids = unreadable_library_ids(app);
+    hide_library_ids(&mut inspected, &ids);
+    inspected
+}
+
+/// The fields of the UI state, by their keys in `ui.inspect`'s `ui`, that hold panel ids: the panel
+/// popped out of the collapsed column, the docking layout, closed panels' places and groups, the panels
+/// shown as icons or collapsed, and the older floating panels' record.
+const PANEL_FIELDS: [&str; 7] =
+    ["open_panel", "docking", "docking_hidden", "docking_hidden_groups", "docking_icons", "docking_collapsed", "floating_panels"];
+
+/// The ids of the loaded libraries (`loaded/<path>`) that the UI state refers to and whose file the
+/// request may not read, each with the id a reply shows instead: `loaded/<file name>`, as a library
+/// loaded without a path is named. The UI state refers to a library by its bare id in a library panel
+/// and the Color Guide's limit, and by a panel id (`library:<kind>:loaded/<path>`) in the fields of
+/// [`PANEL_FIELDS`] and the workspaces' layouts. Text the person types (a command palette query, a
+/// workspace's name) is not read. When another of those ids already shows that name, the next free one
+/// of `loaded/<file name> (2)`, `(3)` and so on is shown, in the sorted order of the full ids, so that
+/// two libraries stay two and `ui.inspect` and `ui.docking` show a library under the same id.
+fn unreadable_library_ids(app: &VectorcraftApp) -> Vec<(String, String)> {
+    let mut ids = std::collections::BTreeSet::new();
+    let ui = serde_json::to_value(&app.ui).unwrap_or_default();
+    for field in PANEL_FIELDS {
+        collect_library_panel_ids(&ui[field], &mut ids);
+    }
+    for workspace in ["custom_workspaces", "workspace_changes"].iter().filter_map(|k| ui[k].as_array()).flatten() {
+        for (_, layout) in workspace.as_object().into_iter().flatten().filter(|(k, _)| k.as_str() != "name") {
+            collect_library_panel_ids(layout, &mut ids);
+        }
+    }
+    collect_library_panel_ids(&json!(app.ui.transient_panel), &mut ids);
+    for id in app.ui.library_panels.iter().map(|p| p.id.as_str()).chain([app.ui.color_guide_limit.as_str()]) {
+        add_library_id(id, &mut ids);
+    }
+    let mut hidden = Vec::new();
+    let mut taken = std::collections::BTreeSet::new();
+    for id in ids {
+        let path = &id["loaded/".len()..];
+        let name = vectorcraft_engine::cmd::fileio::file_name(path);
+        if name != path && !readable(path) {
+            hidden.push((id, name));
+        } else {
+            taken.insert(id);
+        }
+    }
+    let mut hidden = hidden
+        .into_iter()
+        .map(|(id, name)| {
+            let mut shown = format!("loaded/{name}");
+            let mut n = 2;
+            while taken.contains(&shown) {
+                shown = format!("loaded/{name} ({n})");
+                n += 1;
+            }
+            taken.insert(shown.clone());
+            (id, shown)
+        })
+        .collect::<Vec<_>>();
+    // The longest first, so that an id that begins another one does not replace part of it.
+    hidden.sort_by_key(|(id, _)| std::cmp::Reverse(id.len()));
+    hidden
+}
+
+/// Adds `id` to `ids` when it is a loaded library's id (`loaded/<path>`).
+fn add_library_id(id: &str, ids: &mut std::collections::BTreeSet<String>) {
+    if id.len() > "loaded/".len() && id.starts_with("loaded/") {
+        ids.insert(id.to_string());
+    }
+}
+
+/// Adds to `ids` the loaded library id of every library panel id (`library:<kind>:loaded/<path>`)
+/// that `v` holds as a string or a key.
+fn collect_library_panel_ids(v: &Value, ids: &mut std::collections::BTreeSet<String>) {
+    let add = |s: &str, ids: &mut std::collections::BTreeSet<String>| {
+        if let Some((_, id)) = s.strip_prefix(crate::panels::library_panel::PREFIX).and_then(|rest| rest.split_once(':')) {
+            add_library_id(id, ids);
+        }
+    };
+    match v {
+        Value::String(s) => add(s, ids),
+        Value::Array(items) => items.iter().for_each(|item| collect_library_panel_ids(item, ids)),
+        Value::Object(fields) => {
+            for (key, item) in fields {
+                add(key, ids);
+                collect_library_panel_ids(item, ids);
+            }
+        }
+        _ => {}
+    }
+}
+
+/// Writes each id of `ids` as the id the reply shows instead, wherever `v` holds it: in a library's
+/// id, in its panel's id (`library:swatches:loaded/<path>`) and in keys.
+fn hide_library_ids(v: &mut Value, ids: &[(String, String)]) {
+    if ids.is_empty() {
+        return;
+    }
+    let hide = |s: &mut String| {
+        for (id, shown) in ids {
+            if s.contains(id.as_str()) {
+                *s = s.replace(id.as_str(), shown);
+            }
+        }
+    };
+    match v {
+        Value::String(s) => hide(s),
+        Value::Array(items) => items.iter_mut().for_each(|item| hide_library_ids(item, ids)),
+        Value::Object(fields) => {
+            for (mut key, mut item) in std::mem::take(fields) {
+                hide(&mut key);
+                hide_library_ids(&mut item, ids);
+                fields.insert(key, item);
+            }
+        }
+        _ => {}
+    }
+}
+
+/// The preferences that hold a folder, by their keys in `ui.engine_prefs` and the Preferences dialog.
+const PREF_FOLDERS: [&str; 6] = ["fontsFolder", "pluginsFolder", "scratchPrimary", "scratchSecondary", "recoveryFolder", "templatesFolder"];
+
+/// The scratch disk choices that are not paths.
+const SCRATCH_CHOICES: [&str; 2] = ["Startup", "None"];
+
+/// May the request being served read `path`? Under an automation read root (a control client's
+/// request), `ui.inspect` leaves out a path outside the root, as `ui.menu.list` leaves out a recent
+/// file or a listed script outside it.
+fn readable(path: &str) -> bool {
+    vectorcraft_engine::file_access::check_read(path).is_ok()
+}
+
+/// Takes out of `ui.inspect`'s copy of the UI state the paths the request may not read: recent files,
+/// a library panel's file and folder preferences (saved, and in an open Preferences dialog) outside
+/// the read root. The UI state itself is not changed.
+fn leave_out_unreadable_paths(ui: &mut serde_json::Map<String, Value>) {
+    if let Some(Value::Array(files)) = ui.get_mut("recent_files") {
+        files.retain(|f| f.as_str().is_some_and(readable));
+    }
+    if let Some(Value::Array(panels)) = ui.get_mut("library_panels") {
+        for panel in panels.iter_mut().filter_map(Value::as_object_mut) {
+            if panel.get("path").and_then(Value::as_str).is_some_and(|p| !readable(p)) {
+                panel.remove("path");
+            }
+        }
+    }
+    if let Some(Value::Object(prefs)) = ui.get_mut("engine_prefs") {
+        leave_out_unreadable_folders(prefs);
+    }
+    if let Some(Value::Object(dialog)) = ui.get_mut("dialog")
+        && dialog.get("kind").and_then(Value::as_str) == Some("preferences")
+        && let Some(Value::Object(fields)) = dialog.get_mut("fields")
+    {
+        leave_out_unreadable_folders(fields);
+    }
+}
+
+/// Takes out of `prefs` the folder preferences ([`PREF_FOLDERS`]) the request may not read. An
+/// empty value (no folder) and a scratch disk choice ([`SCRATCH_CHOICES`]) stay.
+fn leave_out_unreadable_folders(prefs: &mut serde_json::Map<String, Value>) {
+    for key in PREF_FOLDERS {
+        let Some(path) = prefs.get(key).and_then(Value::as_str).map(str::trim) else { continue };
+        if path.is_empty() || (key.starts_with("scratch") && SCRATCH_CHOICES.contains(&path)) || readable(path) {
+            continue;
+        }
+        prefs.remove(key);
+    }
 }
 
 fn key_from(name: &str) -> Option<egui::Key> {
@@ -348,7 +516,12 @@ pub fn handle(app: &mut VectorcraftApp, ctx: &egui::Context, req: &ControlReques
         "engine.commands" => ok(all_commands(app)),
         "document.inspect" => wrap(app.run("document.inspect", p.clone())),
         "ui.inspect" => ok(inspect(app, ctx)),
-        "ui.docking" => ok(crate::panel_docking::inspect(app, ctx)),
+        "ui.docking" => {
+            let mut docking = crate::panel_docking::inspect(app, ctx);
+            let ids = unreadable_library_ids(app);
+            hide_library_ids(&mut docking, &ids);
+            ok(docking)
+        }
         "ui.menu.list" => ok(serde_json::to_value(crate::menus::menu_entries(app)).unwrap_or_default()),
         "ui.contextMenu.list" => ok(serde_json::to_value(crate::menus::context_entries(app)).unwrap_or_default()),
         "ui.tool.select" => wrap(app.run("tool.select", json!({"tool": s("tool").unwrap_or("")}))),

crates/ui-egui/src/tests/automation.rs

@@ -360,6 +360,181 @@ fn recent_files_outside_the_read_root_are_not_listed_or_opened() {
     let _ = std::fs::remove_dir_all(base);
 }
 
+/// `ui.inspect` leaves out the paths outside the read root that the person's work put in it: files
+/// still opening, recent files, a library panel's file and folder preferences, saved and in the
+/// Preferences dialog.
+#[test]
+fn ui_inspect_leaves_out_paths_outside_the_read_root() {
+    let (mut app, tx, base) = confined("inspect");
+    std::fs::copy(base.join("in/a.svg"), base.join("in/c.svg")).unwrap();
+    let (a, b, c) = (s(base.join("in/a.svg")), s(base.join("outside/b.svg")), s(base.join("in/c.svg")));
+    let svg = std::fs::read(&a).unwrap();
+    for path in [&a, &b, &c] {
+        assert!(crate::opening::start(&mut app, path, svg.clone()).is_ok(), "{path} opens off the UI thread");
+    }
+    app.ui.recent_files = vec![a.clone(), b.clone(), c.clone()];
+    let panel = |id: &str, path: &str| -> crate::panels::library_panel::LibraryPanel {
+        serde_json::from_value(json!({"kind": "swatches", "id": id, "path": path})).unwrap()
+    };
+    let theirs = format!("loaded/{b}");
+    app.ui.library_panels = vec![panel("mine", &a), panel(&theirs, &b)];
+    app.ui.open_panel = Some(format!("library:swatches:{theirs}"));
+    let (inside, outside) = (s(base.join("in")), s(base.join("outside")));
+    app.ui.engine_prefs = json!({
+        "fontsFolder": inside, "templatesFolder": outside, "recoveryFolder": outside, "scratchPrimary": "Startup",
+        "scratchSecondary": "../private", "pluginsFolder": "",
+    });
+    app.ui.dialog = Some(crate::state::Dialog::new("preferences", json!({"fontsFolder": inside, "templatesFolder": outside})));
+
+    // The person sees every path.
+    let ctx = egui::Context::default();
+    let person = crate::control::inspect(&app, &ctx);
+    assert_eq!(person["opening"], json!([a, b, c]));
+    assert_eq!(person["ui"]["recent_files"], json!([a, b, c]));
+    assert_eq!(person["ui"]["library_panels"][1]["path"], b);
+    assert_eq!(person["ui"]["engine_prefs"]["templatesFolder"], outside);
+
+    // The client sees the ones inside the read root, in the same order.
+    let r = request(&mut app, &tx, "ui.inspect", json!({}));
+    let ui = &r["result"]["ui"];
+    assert_eq!(r["result"]["opening"], json!([a, c]), "{r}");
+    assert_eq!(ui["recent_files"], json!([a, c]));
+    assert_eq!(ui["library_panels"][0]["path"], a);
+    assert_eq!((ui["library_panels"][1]["id"].as_str(), ui["library_panels"][1].get("path")), (Some("loaded/b.svg"), None), "the panel stays");
+    assert_eq!(ui["open_panel"], "library:swatches:loaded/b.svg");
+    let prefs = ui["engine_prefs"].as_object().unwrap();
+    assert_eq!(
+        (prefs["fontsFolder"].as_str(), prefs["scratchPrimary"].as_str(), prefs["pluginsFolder"].as_str()),
+        (Some(inside.as_str()), Some("Startup"), Some(""))
+    );
+    assert!(["templatesFolder", "recoveryFolder", "scratchSecondary"].iter().all(|k| !prefs.contains_key(*k)), "{prefs:?}");
+    let fields = ui["dialog"]["fields"].as_object().unwrap();
+    assert_eq!((fields["fontsFolder"].as_str(), fields.get("templatesFolder")), (Some(inside.as_str()), None), "the Preferences dialog's copy too");
+    let hidden = json!(outside).to_string();
+    assert!(!r.to_string().contains(hidden.trim_matches('"')), "no path outside the root: {r}");
+    let r = request(&mut app, &tx, "ui.docking", json!({}));
+    assert_eq!(r["result"]["flyout"], "library:swatches:loaded/b.svg", "{r}");
+    assert_eq!(crate::panel_docking::inspect(&app, &ctx)["flyout"], json!(format!("library:swatches:{theirs}")), "the person's");
+    assert_eq!(app.ui.recent_files, [a.clone(), b.clone(), c.clone()], "the UI state is not changed");
+    assert_eq!(app.opening.pending.len(), 3, "and no open is canceled");
+
+    // A write root alone lets the client read none of them.
+    let write_only = AutomationRoots::new(&[], &[&base.join("out")]).unwrap();
+    let listed = vectorcraft_engine::file_access::confine(write_only.as_ref(), || crate::control::inspect(&app, &ctx));
+    assert_eq!((&listed["opening"], &listed["ui"]["recent_files"]), (&json!([]), &json!([])), "{listed}");
+    let _ = std::fs::remove_dir_all(base);
+}
+
+/// A closed panel's former place, as `ui.docking_hidden` keeps it.
+fn hidden_place() -> craft_ui::docking::Location<String> {
+    serde_json::from_value(json!({"floating": null, "anchor": null, "placement": {"Tab": {"before": null}}, "size": null, "stack": null})).unwrap()
+}
+
+/// `ui.inspect` hides the path of a library loaded from outside the read root wherever the reply holds
+/// its id, also when its panel is closed: here only the Color Guide's limit and a closed panel's place
+/// name it.
+#[test]
+fn ui_inspect_hides_a_closed_librarys_path_outside_the_read_root() {
+    let (mut app, tx, base) = confined("inspect-closed-lib");
+    let theirs = format!("loaded/{}", s(base.join("outside/b.svg")));
+    app.ui.color_guide_limit = theirs.clone();
+    app.ui.docking_hidden.insert(format!("library:swatches:{theirs}"), hidden_place());
+    let r = request(&mut app, &tx, "ui.inspect", json!({}));
+    let ui = &r["result"]["ui"];
+    assert_eq!(ui["color_guide_limit"], "loaded/b.svg", "{r}");
+    assert!(ui["docking_hidden"].as_object().unwrap().contains_key("library:swatches:loaded/b.svg"), "{r}");
+    let hidden = json!(s(base.join("outside"))).to_string();
+    assert!(!r.to_string().contains(hidden.trim_matches('"')), "no path outside the root: {r}");
+    assert_eq!(crate::control::inspect(&app, &egui::Context::default())["ui"]["color_guide_limit"], json!(theirs), "the person's");
+    let _ = std::fs::remove_dir_all(base);
+}
+
+/// Two libraries loaded from outside the read root with the same file name stay two in `ui.inspect`:
+/// the second one shows as `loaded/<file name> (2)`, the same in every place the reply names it.
+#[test]
+fn ui_inspect_keeps_two_hidden_libraries_with_one_file_name_apart() {
+    let (mut app, tx, base) = confined("inspect-same-name");
+    let (x, y) = (format!("loaded/{}", s(base.join("outside/x/b.svg"))), format!("loaded/{}", s(base.join("outside/y/b.svg"))));
+    let panel = |id: &str| -> crate::panels::library_panel::LibraryPanel { serde_json::from_value(json!({"kind": "swatches", "id": id})).unwrap() };
+    app.ui.library_panels = vec![panel(&x), panel(&y)];
+    for id in [&x, &y] {
+        app.ui.docking_hidden.insert(format!("library:swatches:{id}"), hidden_place());
+    }
+    app.ui.color_guide_limit = y.clone();
+    let r = request(&mut app, &tx, "ui.inspect", json!({}));
+    let ui = &r["result"]["ui"];
+    let ids: Vec<_> = ui["library_panels"].as_array().unwrap().iter().map(|p| p["id"].clone()).collect();
+    assert_eq!(ids, [json!("loaded/b.svg"), json!("loaded/b.svg (2)")], "{r}");
+    let keys: Vec<_> = ui["docking_hidden"].as_object().unwrap().keys().cloned().collect();
+    assert_eq!(keys, ["library:swatches:loaded/b.svg", "library:swatches:loaded/b.svg (2)"], "no entry is dropped: {r}");
+    assert_eq!(ui["color_guide_limit"], "loaded/b.svg (2)", "the same id everywhere");
+    let _ = std::fs::remove_dir_all(base);
+}
+
+/// `ui.inspect` and `ui.docking` show a hidden library under the same id, also when another hidden
+/// library with the same file name is in only one of the replies (here as the Color Guide's limit).
+#[test]
+fn ui_inspect_and_ui_docking_give_a_hidden_library_the_same_id() {
+    let (mut app, tx, base) = confined("inspect-docking-same-id");
+    let (x, y) = (format!("loaded/{}", s(base.join("outside/x/b.svg"))), format!("loaded/{}", s(base.join("outside/y/b.svg"))));
+    let panel: crate::panels::library_panel::LibraryPanel = serde_json::from_value(json!({"kind": "swatches", "id": y})).unwrap();
+    app.ui.library_panels = vec![panel];
+    app.ui.open_panel = Some(format!("library:swatches:{y}"));
+    app.ui.color_guide_limit = x.clone();
+    let r = request(&mut app, &tx, "ui.inspect", json!({}));
+    let ui = &r["result"]["ui"];
+    assert_eq!(
+        (ui["color_guide_limit"].as_str(), ui["open_panel"].as_str()),
+        (Some("loaded/b.svg"), Some("library:swatches:loaded/b.svg (2)")),
+        "{r}"
+    );
+    let d = request(&mut app, &tx, "ui.docking", json!({}));
+    assert_eq!(d["result"]["flyout"], ui["open_panel"], "{d}");
+    let _ = std::fs::remove_dir_all(base);
+}
+
+/// `ui.inspect` rewrites only the ids of libraries the UI state refers to: a script's report line and
+/// a command palette query that look like a library id, with no such library, stay as written, and
+/// the query does not take the file name of a real library outside the root.
+#[test]
+fn ui_inspect_keeps_text_that_only_looks_like_a_library_id() {
+    let (mut app, tx, base) = confined("inspect-lookalike");
+    let real = format!("loaded/{}", s(base.join("outside/x/d.svg")));
+    let panel: crate::panels::library_panel::LibraryPanel = serde_json::from_value(json!({"kind": "swatches", "id": real})).unwrap();
+    app.ui.library_panels = vec![panel];
+    let query = format!("library:swatches:loaded/{}", s(base.join("outside/d.svg")));
+    app.ui.palette_query = query.clone();
+    let text = format!("loaded/{}", s(base.join("outside/c.svg")));
+    let source = format!("vc.log({})", json!(text));
+    app.session.execute("script.run", &json!({"source": source, "name": "t.js"})).unwrap();
+    for _ in 0..10_000 {
+        if app.session.script_pump().is_some() {
+            break;
+        }
+    }
+    let r = request(&mut app, &tx, "ui.inspect", json!({}));
+    assert_eq!(r["result"]["scriptReport"]["log"], json!([text]), "{r}");
+    assert_eq!(r["result"]["ui"]["palette_query"], json!(query), "{r}");
+    assert_eq!(r["result"]["ui"]["library_panels"][0]["id"], "loaded/d.svg", "{r}");
+    let _ = std::fs::remove_dir_all(base);
+}
+
+/// A client without automation roots sees every loaded library's full id in `ui.inspect`.
+#[test]
+fn ui_inspect_shows_full_library_ids_without_a_read_root() {
+    let (tx, rx) = std::sync::mpsc::channel();
+    let mut app = VectorcraftApp::new(Session::new(), Default::default()).with_control(rx);
+    let theirs = format!("loaded/{}", s(std::env::temp_dir().join("vc-ui-roots-unconfined").join("b.svg")));
+    let panel: crate::panels::library_panel::LibraryPanel = serde_json::from_value(json!({"kind": "swatches", "id": theirs})).unwrap();
+    app.ui.library_panels = vec![panel];
+    app.ui.color_guide_limit = theirs.clone();
+    app.ui.docking_hidden.insert(format!("library:swatches:{theirs}"), hidden_place());
+    let r = request(&mut app, &tx, "ui.inspect", json!({}));
+    let ui = &r["result"]["ui"];
+    assert_eq!((&ui["library_panels"][0]["id"], &ui["color_guide_limit"]), (&json!(theirs), &json!(theirs)), "{r}");
+    assert!(ui["docking_hidden"].as_object().unwrap().contains_key(&format!("library:swatches:{theirs}")), "{r}");
+}
+
 /// Hidden logic-only ticks between the injection and its UI pass must not drain another step:
 /// one step per settled pass, not per hidden tick.
 #[test]

docs/control-protocol.md

@@ -92,7 +92,7 @@ the two can still win that race.
 | `engine.execute` | `{command, params}` | run any engine or UI command (see `engine.commands`). A key of `params` that the command's params description doesn't name is an error naming it and the nearest key the command takes, before anything runs (`unknown parameter `widht`; did you mean `width`?`); see [Parameter keys](mcp.md#parameter-keys) |
 | `engine.commands` | | every command with label, shortcut, params doc, enablement |
 | `document.inspect` | `{depth?, childLimit?, ids?, kind?, limit?, offset?}` | layer tree, selection, the key object (`key`, null without one; a key ruler guide as `keyGuide`), history, paint defaults; `depth` / `childLimit` slice the layer tree as `document.node {summary: true}` does; `ids`, `kind`, `limit` and `offset` list just some nodes as `nodes` (with `total`) instead of the whole tree, see [mcp.md](mcp.md). Each node reports `opacity` below 1 and `blend` when it isn't Normal; objects and compound paths report `fill`, `stroke` and `strokeWidth`, a compound path's members `compoundMember: true` instead |
-| `ui.inspect` | | tool, UI state, `screenMode` (0 normal, 1 full screen with menu bar, 2 full screen, 3 Presentation Mode), `taskBar` (`pinned`, and `rect` `[x, y, w, h]` while the Contextual Task Bar shows), `freeTransformWidget` (`[x, y, w, h]` while the Free Transform widget shows), view, canvas rect, window size, perf, background saves and exports still running, `nativeMenuBar` (true when the menus are in the macOS menu bar rather than the window; `ui.menu.list` lists the in-window menus either way), `fileDialog` (`"open"`, `"place"`, `"save"` or `"folder"` while a native file dialog is open, `null` otherwise; see below) |
+| `ui.inspect` | | tool, UI state, `screenMode` (0 normal, 1 full screen with menu bar, 2 full screen, 3 Presentation Mode), `taskBar` (`pinned`, and `rect` `[x, y, w, h]` while the Contextual Task Bar shows), `freeTransformWidget` (`[x, y, w, h]` while the Free Transform widget shows), view, canvas rect, window size, perf, background saves and exports still running, `nativeMenuBar` (true when the menus are in the macOS menu bar rather than the window; `ui.menu.list` lists the in-window menus either way), `fileDialog` (`"open"`, `"place"`, `"save"` or `"folder"` while a native file dialog is open, `null` otherwise; see below), `opening` (the paths of the documents still being read). Under `--automation-read-root` the reply leaves out the paths outside the read roots (see `docs/mcp.md`) |
 | `ui.menu.list` / `ui.menu.invoke` | `{command, params}` | the full menu tree / invoke an item |
 | `ui.contextMenu.list` | | the canvas context menu for the current selection, flattened like `ui.menu.list` (`path` holds its submenus). `ui.click {x, y, button: "right"}` on the canvas opens it, after selecting the object there unless it is already selected. With the Artboard tool it lists the artboard entries (see `docs/mcp.md`), after selecting the artboard there unless it is already selected. While a menu opened over locked objects is open, it has an `Unlock` submenu with one item for each locked object under the pointer, topmost first and at most 20, labeled with the object's name, which runs `layer.setProps {ids: [id], locked: false}`. A locked group gets one item, and the locked objects inside it get none. Hidden objects, objects on hidden, locked or template layers, and in isolation mode objects outside the isolated group get no item |
 | `ui.tool.select` / `ui.tool.list` | `{tool}` | |

docs/mcp.md

@@ -115,6 +115,16 @@ the suite) keep the agent to the folders you give it:
 - `file.recentFiles` and the control channel's `ui.menu.list` leave out the recent files outside the read roots. The
   other File › Open Recent Files rows keep their ids (`file.openRecent3` still opens the third file), and
   `file.openRecentN` for a file outside the roots ends with `no such recent file`, as an empty slot does.
+- `ui_inspect` (the control channel's `ui.inspect`) leaves out the paths outside the read roots: in `opening`, the
+  documents still being read; in `ui.recent_files`, the recent files; a library panel's `path` in `ui.library_panels`;
+  and the folder preferences in `ui.engine_prefs` and in an open Preferences dialog's `ui.dialog.fields`
+  (`fontsFolder`, `pluginsFolder`, `scratchPrimary`, `scratchSecondary`, `recoveryFolder`, `templatesFolder`; an
+  empty folder and the scratch disk choices `Startup` and `None` stay). A library loaded from a file outside the
+  roots shows as `loaded/<file name>` wherever `ui_inspect` and `ui.docking` name it: its id, its panel's id, the
+  Color Guide's `ui.color_guide_limit` and a closed panel's key in `ui.docking_hidden`, also when its panel is
+  closed. When another hidden library has the same file name, the libraries take `loaded/<file name>`,
+  `loaded/<file name> (2)`, `(3)` and so on in the order of their full ids, and each one keeps its id in both
+  replies. The other entries keep their order, and the app's own state is not changed.
 - Each flag may be given more than once (#3546): a path inside any of the read roots may be read, one inside any
   of the write roots written, so one session can read a project folder and a shared assets folder, or write to an
   output folder and a scratch folder, without widening a root to their common parent. A folder given twice

docs/target-app-parity.md

@@ -739,6 +739,7 @@ Moved from the ROADMAP's "Shipped so far" on 2026-10-10. Update it when a featur
   - Scripts: `#strict on` (and `//@strict on`) runs the script with the checks the [`$` object](https://extendscript.docsforadobe.dev/extendscript-tools-features/dollar-object/) help page gives for `$.strict`: an assignment to a read-only property throws a `TypeError`, and so does a new property on an object that takes none. VectorCraft's own rules: a getter-only property counts as read-only, the objects that take no new properties are the non-extensible ones (`Object.preventExtensions`, `seal`, `freeze`, and the frozen `vc` and `$` objects), the last `#strict` line of the script and its includes sets the whole run, a file `$.evalFile` runs keeps its own line's checks for its code, and the rest of ES5 strict mode stays with `'use strict'`. Without the line, runs are unchanged. `crates/engine/src/tests/script_include.rs` (`strict_on_*`, `strict_mode_in_eval_file_is_scoped`), `crates/js/src/interp_tests.rs` (`strict_writes_are_separate_from_es5_strict`).
   - Scripts folder: File › Scripts lists the `.js` and `.jsx` files of the `Scripts` folder next to the preferences, each named after its file without the extension, with each subfolder as a submenu, above Check Script… and Other Script… (https://helpx.adobe.com/illustrator/desktop/automate-visualize-data/automate-actions/install-and-run-scripts.html). VectorCraft's own rules: the folder is read again when the window becomes active and when the File menu opens, links are not followed, and one read stops at 2,048 entries, 512 scripts, 128 subfolders, 4 levels or 250 ms. `script.listInstalled` returns the listing. `crates/engine/src/tests/script_folder.rs`, `crates/ui-egui/src/tests/scripts_menu.rs`.
   - Open Recent Files under `--automation-read-root`: the control channel's `ui.menu.list` and `file.recentFiles` leave out the recent files outside the read roots, the other rows keep their ids, and `file.openRecentN` for one outside them answers `no such recent file`, as an empty slot does. `crates/ui-egui/src/tests/automation.rs`.
+  - `ui.inspect` under `--automation-read-root`: the documents still opening, the recent files, library panels' files and folder preferences (saved, and in an open Preferences dialog) outside the read roots are left out of the reply, a library loaded from outside them shows by its file name in `ui.inspect` and `ui.docking`, and the app's state is not changed. `crates/ui-egui/src/tests/automation.rs` (`ui_inspect_leaves_out_paths_outside_the_read_root`).
   - Scripts: `alert`, `confirm` and `prompt` open dialogs during a run, each with a Stop button that ends the run and puts every document back. In the app the run waits at the call for the person's answer; a run over MCP or the command line takes its answers in order from `script.run`'s `answers`, and the report lists each dialog with its answer. `crates/engine/src/tests/script_dialogs.rs`, `crates/ui-egui/src/tests/script_dialogs.rs`.
   - Parameter keys: the engine refuses a key that a command's params description doesn't name before the command runs, in every build and for every caller, including the app's own calls, the commands a command runs and the steps of `command.batch` and `action.batch`. An action recorded by an older version still plays from the Actions panel and the Batch dialog (`Session::replay`). `crates/engine/tests/it/param_keys.rs`.
   - MCP server with 25 tools (drawing, text, effects, Pathfinder, transforms, graphs, text wrap, export, screenshots, any command), attached to the running app or headless. Tool descriptions and replies agree with the engine: format lists come from its format table, `save_file` says it keeps the document's own format, `inspect_document` reports the paint type's characters show, and selection exports report the encoder's warnings. `--automation-read-root` / `--automation-write-root` (on `vectorcraft-cli mcp` and on `vectorcraft --control`) confine the files commands read and write to chosen folders, links followed, with the flags PhotoCraft takes (#832); each flag may be given more than once, a path inside any of its folders being allowed (#3546, `file_access::tests::several_roots_of_a_kind_each_grant_their_access`, `cli::mcp_automation_roots_take_several_folders`). A long export can be cancelled (`notifications/cancelled` stops it at the next page or group and writes nothing), reports page progress to a client that sent a progress token, and does not make other requests wait: engine-free ones answer at once, the rest are refused as busy after two seconds (#2165, #2171, #2172).