M5: proto.settings refuses an unknown device and answers the settings (#2027)

`proto.settings` took any string as the device ("Pixel Nonexistent", "iphone 16") and saved it in
the file: the presenter then drew no device frame while its picker showed the name as if it were
one. An unknown colour was already refused with the device's colours, but a typo in the device
went unnoticed, and an agent couldn't read the settings back (`proto.settings {}` answered
`{ok: true}`, and neither `inspect_document` nor `get_node` shows a page's prototype settings).

An unknown name, or a value that isn't a string, is now refused with every name the picker offers
("None", "Custom size" and the devices), and nothing changes. A known name is taken in any case and
with spaces around it, and stored as the picker spells it (`known_device`). Every call answers the
page's settings as they are after it (`settings_json`): device, background, rotation, the colour
shown, the screen as presented (null without a device), the custom size and responsive, beside the
`ok: true` it answered before; `proto.settings {}` reads them.

Test: `proto_present_tests::unknown_devices_are_refused_and_settings_read_back`. Docs: mcp.md,
prototyping-parity.md, ROADMAP.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LvG6E2LxvJ6MuFmiLA6Zqm

crates/engine/src/cmd/proto.rs

@@ -112,7 +112,7 @@ pub fn specs() -> Vec<CommandSpec> {
         spec!(
             "proto.settings",
             "Prototype settings",
-            "{device? (a device name, \"Custom size\" or \"None\"), background?, rotation? portrait|landscape (or 0|90; phones and tablets turn), color? (one of the device's colours by name), width?, height? (the custom size's screen, 1–10000 points; picks \"Custom size\"), responsive? bool (frames resize to the screen and their constraints and auto layout respond)}",
+            "{device? (a device name, \"Custom size\" or \"None\"; any case; another name is refused with the list), background?, rotation? portrait|landscape (or 0|90; phones and tablets turn), color? (one of the device's colours by name), width?, height? (the custom size's screen, 1–10000 points; picks \"Custom size\"), responsive? bool (frames resize to the screen and their constraints and auto layout respond)} → the page's settings after the call (none given: reads them)",
             true,
             settings
         ),
@@ -173,12 +173,51 @@ pub fn specs() -> Vec<CommandSpec> {
     ]
 }
 
-/// `proto.settings`: everything is checked before anything changes.
+/// The device setting `name` stands for, as the device picker names it: "None", "Custom size" or a
+/// model of [`PrototypeSettings::DEVICES`], whatever its case and the spaces around it.
+fn known_device(name: &str) -> Option<&'static str> {
+    let name = name.trim();
+    ["None", PrototypeSettings::CUSTOM_DEVICE]
+        .into_iter()
+        .chain(PrototypeSettings::DEVICES.iter().map(|d| d.name))
+        .find(|d| d.eq_ignore_ascii_case(name))
+}
+
+/// What `proto.settings` answers: the page's prototype settings (the device as the picker names it,
+/// the colour shown, the screen as presented, `null` without a device).
+fn settings_json(ps: &PrototypeSettings) -> Value {
+    let screen = ps.device().map(|d| json!({"width": d.width, "height": d.height}));
+    json!({
+        "ok": true,
+        "device": ps.device,
+        "background": format!("#{}", ps.background.to_hex()),
+        "rotation": ps.rotation,
+        "color": ps.device_color().map(|c| c.name),
+        "screen": screen,
+        "customSize": {"width": ps.custom_size[0], "height": ps.custom_size[1]},
+        "responsive": ps.responsive,
+    })
+}
+
+/// `proto.settings`: everything is checked before anything changes; an unknown device is refused
+/// with the devices to pick from, as an unknown colour is. Answers the settings as they are after
+/// the call, so a call without parameters reads them.
 fn settings(s: &mut Session, p: &Value) -> Result<Value> {
     let cmd = "proto.settings";
     let page = s.page()?;
     let bg = color(p, "background");
-    let dev = string(p, "device");
+    let dev = match p.get("device") {
+        None | Some(Value::Null) => None,
+        Some(v) => {
+            let name = v.as_str().unwrap_or_default();
+            let found = known_device(name).ok_or_else(|| {
+                let names: Vec<&str> =
+                    ["None", PrototypeSettings::CUSTOM_DEVICE].into_iter().chain(PrototypeSettings::DEVICES.iter().map(|d| d.name)).collect();
+                bad(cmd, format!("unknown device {}: device is one of {}", figcraft_format::clip(&v.to_string(), 60), names.join("|")))
+            })?;
+            Some(found.to_string())
+        }
+    };
     let rot = match p.get("rotation") {
         None | Some(Value::Null) => None,
         Some(v) => Some(rotation_of(v).ok_or_else(|| bad(cmd, "rotation: portrait|landscape"))?),
@@ -231,12 +270,13 @@ fn settings(s: &mut Session, p: &Value) -> Result<Value> {
         None if !colors.iter().any(|x| x.name == next.color) => next.color.clear(),
         None => {}
     }
+    let answer = settings_json(&next);
     if next != *prototype
         && let NodeKind::Page { prototype, .. } = &mut s.doc_mut()?.get_mut(page)?.kind
     {
         *prototype = next;
     }
-    ok()
+    Ok(answer)
 }
 
 /// Resize top-level `frame` to a screen of `(w, h)` as a responsive prototype does: its children

crates/engine/src/proto_present_tests.rs

@@ -97,3 +97,31 @@ fn explicit_variable_modes_go_back_to_auto() {
     assert!(s.execute("variable.setMode", &json!({"ids": [f], "collection": "Tokens", "mode": "Dusk"})).is_err());
     assert!(s.execute("variable.setMode", &json!({"ids": [f], "collection": "Tokens"})).is_err(), "a mode, or null for Auto");
 }
+
+/// #2027: an unknown device is refused with the devices to pick from, as an unknown colour is, and
+/// nothing changes; a known one is taken whatever its case and stored as the picker names it; the
+/// settings read back from `proto.settings` without parameters.
+#[test]
+fn unknown_devices_are_refused_and_settings_read_back() {
+    let mut s = Session::new();
+    let before = settings(&s);
+    for junk in [json!("Pixel Nonexistent"), json!(""), json!(42), json!(["iPhone 16"])] {
+        let err = s.execute("proto.settings", &json!({"device": junk, "responsive": true})).unwrap_err().to_string();
+        assert!(err.contains("unknown device") && err.contains("iPhone 17|") && err.contains("Custom size"), "{junk}: {err}");
+        assert_eq!(settings(&s), before, "{junk}: nothing changes");
+    }
+    let set = s.execute("proto.settings", &json!({"device": " iphone 16 ", "color": "black"})).unwrap();
+    assert_eq!(settings(&s).device, "iPhone 16", "stored as the picker names it");
+    assert_eq!((&set["device"], &set["color"]), (&json!("iPhone 16"), &json!("Black")));
+    let read = s.execute("proto.settings", &json!({})).unwrap();
+    assert_eq!(read, set, "a call without parameters reads the settings");
+    assert_eq!((&read["ok"], &read["rotation"], &read["responsive"]), (&json!(true), &json!("portrait"), &json!(false)));
+    assert_eq!(read["screen"], json!({"width": 393.0, "height": 852.0}));
+    assert!(read["background"].as_str().is_some_and(|c| c.starts_with('#')), "{read}");
+    // "None" and "Custom size" in any case; no device has no screen or colour.
+    s.execute("proto.settings", &json!({"device": "custom SIZE", "width": 800, "height": 600})).unwrap();
+    assert_eq!(settings(&s).device, PrototypeSettings::CUSTOM_DEVICE);
+    let none = s.execute("proto.settings", &json!({"device": "none"})).unwrap();
+    assert_eq!((&none["device"], &none["screen"], &none["color"]), (&json!("None"), &json!(null), &json!(null)));
+    assert_eq!(none["customSize"], json!({"width": 800.0, "height": 600.0}));
+}

docs/mcp.md

@@ -847,11 +847,15 @@ removes the whole conditional). Every one is an undo step and applies to all `id
 with the same interactions). Flows `proto.flow.add` / `rename` / `remove`,
 and the device, its rotation and the background `proto.settings {device?, background?,
 rotation?, color?, width?, height?, responsive?}` (`None`, `iPhone 16`, `iPhone 16 Pro Max`,
-`Android Compact`, `iPad mini`, `MacBook Air`, `Desktop` or `Custom size`; `rotation` `portrait` or
+`Android Compact`, `iPad mini`, `MacBook Air`, `Desktop` or `Custom size`, in any case; another
+name is an error that lists the devices, and nothing changes; `rotation` `portrait` or
 `landscape`, which turns phones and tablets; `color` one of the device's colours by name, e.g.
 `Black`, `White`, `Pink`, `Teal`, `Blue` for the iPhone 16 (an error lists them), `""` for the
 default; `width` / `height` set the custom size's screen, 1–10000 points, and pick `Custom size`,
-which is a bare screen without a body). On a device the presented frame is sized to the device's
+which is a bare screen without a body). Every call answers the page's settings as they are after
+it, so `proto.settings {}` reads them: `{device, background, rotation, color (the colour shown, null
+without a body), screen ({width, height} as presented, null without a device), customSize,
+responsive}`. On a device the presented frame is sized to the device's
 screen: a frame bigger than the screen scrolls through its whole size whatever its `overflow`, content
 past the frame's own edges scrolls only as its `overflow` allows (else it's clipped), and `fixed`
 layers stay on screen (pinned to the edges their constraints name). With `responsive: true` (saved

docs/prototyping-parity.md

@@ -1,6 +1,6 @@
 # Prototyping parity
 
-> **Last reviewed:** 2026-10-11 · **Last updated:** 2026-11-01 · **Change:** minor (Hide UI in the presenter's Options menu, and Cmd/Ctrl+\ as in the editor: the bar above the prototype and the navigation bar under it go away, a toast names the key that brings them back, `proto.presentOptions {hideUi}` (#1820); the Controller menu names each button as PlayStation and Switch controllers do; "Open in new tab" on Open link: off, the web build's own tab goes to the link; a manual overlay's position can be dragged on the canvas (#405); Open link notices now cover mail links, and skipping them covers only links the viewer fired (#1096); overlay positions relative to the layer that opens them; the Triggers row no longer lists delays on mouse triggers as missing; top-level frames bigger than the device's screen scroll in the player; Change to, set variable and set variable mode lay out what they change in the player, as the canvas does; presentation tabs, one per page of a file; a Present tab with device and scale controls (#537); core editor leftovers: delays on mouse triggers and manual overlay offsets; controller buttons on key/gamepad triggers, widgets that react in prototypes, `proto.evaluate` and the mode lookup rules pinned) · **Target:** Figma Design (desktop app 126.10.7)
+> **Last reviewed:** 2026-10-11 · **Last updated:** 2026-11-06 · **Change:** patch (`proto.settings` refuses an unknown device with the list of devices instead of saving it, takes a known one in any case, and answers the page's settings, so `proto.settings {}` reads them (#2027); Hide UI in the presenter's Options menu, and Cmd/Ctrl+\ as in the editor: the bar above the prototype and the navigation bar under it go away, a toast names the key that brings them back, `proto.presentOptions {hideUi}` (#1820); the Controller menu names each button as PlayStation and Switch controllers do; "Open in new tab" on Open link: off, the web build's own tab goes to the link; a manual overlay's position can be dragged on the canvas (#405); Open link notices now cover mail links, and skipping them covers only links the viewer fired (#1096); overlay positions relative to the layer that opens them; the Triggers row no longer lists delays on mouse triggers as missing; top-level frames bigger than the device's screen scroll in the player; Change to, set variable and set variable mode lay out what they change in the player, as the canvas does; presentation tabs, one per page of a file; a Present tab with device and scale controls (#537); core editor leftovers: delays on mouse triggers and manual overlay offsets; controller buttons on key/gamepad triggers, widgets that react in prototypes, `proto.evaluate` and the mode lookup rules pinned) · **Target:** Figma Design (desktop app 126.10.7)
 
 **Breadth ~92%, ready ~74% (estimated).** Every Figma trigger except media, every action except
 media control, every transition and easing exist; key/gamepad triggers take controller buttons,
@@ -107,6 +107,7 @@ tool; opt-in), **silent** (the documentation doesn't say; the case pins the curr
 
 | Date | Change | Summary |
 |---|---|---|
+| 2026-11-06 | patch | M5, #2027: `proto.settings` took any string as the device (`"Pixel Nonexistent"`, `"iphone 16"`) and saved it in the file; the presenter then drew no device while its picker showed the name as if it were one, and the settings couldn't be read back over MCP (`proto.settings {}` answered `{ok: true}`). An unknown name (or a non-string) is now refused with every name the picker offers (`None`, `Custom size` and the devices), as an unknown colour is refused with the device's colours, and nothing changes; a known name is taken in any case and stored as the picker spells it. Every call answers the page's settings after it: device, background, rotation, the colour shown, the screen as presented, the custom size and responsive. Test: `proto_present_tests::unknown_devices_are_refused_and_settings_read_back` |
 | 2026-10-31 | minor | Gap 15: the Controller menu names buttons as PlayStation and Switch controllers do; that item leaves the missing list. Estimate unchanged. Test: `present::tail_tests`. |
 | 2026-10-30 | minor | Opening a link in place: Open link has "Open in new tab", on by default; off, the web build's own tab goes to the link after the notice (or at once with it skipped); the desktop app has no tab of its own and opens the browser either way. Saved in files only when off (`openInNewTab`) and read from REST files. |
 | 2026-10-30 | patch | A manual overlay can be placed on the canvas (#405): while the interaction editor has an Open overlay action with Manual position open, the overlay frame shows dimmed, outlined, where it opens from the top-left of the layer that opens it (right below that layer without an offset), and dragging it moves it there. The X and Y fields follow while dragging, and the drag is one undo step (`crates/ui-egui/src/canvas/proto_canvas/overlay_ghost.rs`). Numbers unchanged |