GitCorner

Code

ossartcraftfigcraft๐ŸŒ
b45255bb6fe2
//! View menu, preferences and tools. View state is per document and drivable like everything else.

use figcraft_doc::NodeId;
use serde_json::{Value, json};

use super::{CommandSpec, ok};
use crate::params::{boolean, get, num, num_or, req_index, req_num, req_string, string};
use crate::tools::ToolId;
use crate::{EngineError, Result, Session, ViewState, bad, spec};

/// The active document's view state, for changing it.
fn view(s: &mut Session) -> Result<&mut ViewState> {
    Ok(&mut s.ds_mut()?.view)
}

/// Set one of a view's on/off settings from `on`, or toggle it when `on` is absent.
fn flag(s: &mut Session, p: &Value, f: fn(&mut ViewState) -> &mut bool) -> Result<Value> {
    let v = view(s)?;
    let slot = f(v);
    *slot = boolean(p, "on").unwrap_or(!*slot);
    Ok(json!({"on": *slot}))
}

/// One of a view's on/off settings.
type Slot = fn(&mut ViewState) -> &mut bool;

/// The View menu's on/off toggles (Pixel preview, with its scale, has its own command), and
/// whether the preferences keep each: files opened or made later start with the kept ones. Outline
/// modes and the sRGB soft-proof stay with their file, so a new file never opens in one.
const TOGGLES: &[(&str, Slot, bool)] = &[
    ("view.pixelGrid", |v| &mut v.pixel_grid, true),
    ("view.layoutGrids", |v| &mut v.layout_grids, true),
    ("view.rulers", |v| &mut v.rulers, true),
    ("view.slices", |v| &mut v.show_slices, true),
    ("view.comments", |v| &mut v.comments, true),
    ("view.multiplayerCursors", |v| &mut v.multiplayer_cursors, true),
    ("view.outlines", |v| &mut v.outlines, false),
    ("view.outlinesSelection", |v| &mut v.outlines_selection, false),
    ("view.outlinesHiddenLayers", |v| &mut v.outline_hidden, true),
    ("view.outlinesObjectBounds", |v| &mut v.outline_bounds, true),
    ("view.maskOutlines", |v| &mut v.mask_outlines, true),
    ("view.frameOutlines", |v| &mut v.frame_outlines, true),
    ("view.proofSrgb", |v| &mut v.proof_srgb, false),
    ("view.snapGeometry", |v| &mut v.snap_geometry, true),
    ("view.snapObjects", |v| &mut v.snap_objects, true),
    ("view.snapPixel", |v| &mut v.snap_pixel, true),
];

/// View toggle `id`: the file's view changes, and the preferences remember a kept one.
fn toggle(s: &mut Session, p: &Value, id: &str) -> Result<Value> {
    let Some(&(_, f, keep)) = TOGGLES.iter().find(|(k, ..)| *k == id) else { return Err(bad(id, "not a View toggle")) };
    let r = flag(s, p, f)?;
    if keep && let Some(on) = r.get("on").and_then(Value::as_bool) {
        s.prefs.view.insert(id.to_string(), on);
    }
    Ok(r)
}

/// Set `v`'s View toggles to the ones the preferences keep (the others stay as they are).
pub(crate) fn apply_kept(prefs: &crate::Prefs, v: &mut ViewState) {
    for (id, f, _) in TOGGLES.iter().filter(|t| t.2) {
        if let Some(on) = prefs.view.get(*id) {
            *f(v) = *on;
        }
    }
}

/// Whether the View menu's toggle `id` is on (the menus show a check mark); `None` for a command
/// that isn't one.
pub fn checked(s: &Session, id: &str) -> Option<bool> {
    let mut v = s.ds().ok()?.view.clone();
    if id == "view.pixelPreview" {
        return Some(v.pixel_preview);
    }
    TOGGLES.iter().find(|(k, ..)| *k == id).map(|(_, f, _)| *f(&mut v))
}

/// Pixel preview: toggles, or turns on at a resolution of 1x or 2x.
fn pixel_preview(s: &mut Session, p: &Value) -> Result<Value> {
    let scale = match p.get("scale") {
        None | Some(Value::Null) => None,
        Some(v) => match v.as_u64() {
            Some(k @ (1 | 2)) => Some(k as u8),
            _ => return Err(bad("view.pixelPreview", "`scale` must be 1 or 2")),
        },
    };
    let v = view(s)?;
    if let Some(k) = scale {
        v.pixel_scale = k;
    }
    v.pixel_preview = boolean(p, "on").unwrap_or(scale.is_some() || !v.pixel_preview);
    Ok(json!({"on": v.pixel_preview, "scale": v.pixel_scale}))
}

/// Zoom the active document to `z` about the view's centre, keeping that point in place.
fn zoom_to(s: &mut Session, z: f64) -> Result<Value> {
    let v = view(s)?;
    let c = (v.cx, v.cy);
    v.set_zoom_at(z, c);
    Ok(json!({"zoom": v.zoom}))
}

/// How far an arrow key pans the view with nothing selected (screen pixels). Measured in Figma at
/// 100% zoom: about 64 px (62-64 in two trials, +/-3 px).
pub const PAN_STEP_PX: f64 = 64.0;

/// Shift multiplies the arrow pan by this much (Figma: about 320 px, five steps).
pub const PAN_BIG_STEPS: f64 = 5.0;

/// `view.pan`: the arrow keys with nothing selected move the view by keyboard steps.
fn pan(s: &mut Session, p: &Value) -> Result<Value> {
    let step = if boolean(p, "big").unwrap_or(false) { PAN_STEP_PX * PAN_BIG_STEPS } else { PAN_STEP_PX };
    let dir = |k| num(p, k).filter(|v| v.is_finite()).unwrap_or(0.0).clamp(-100.0, 100.0) * step;
    let (dx, dy) = (dir("dx"), dir("dy"));
    let v = view(s)?;
    // Scrolling moves the content; panning right shows what is to the right.
    v.scroll(-dx, -dy, false);
    Ok(json!({"cx": v.cx, "cy": v.cy}))
}

/// Figma's zoom steps.
const STEPS: &[f64] = &[0.02, 0.03, 0.06, 0.13, 0.25, 0.5, 1.0, 2.0, 4.0, 8.0, 16.0, 32.0, 64.0, 128.0, 256.0];

/// The next zoom step above (`up`) or below `z` in Figma's fixed steps.
fn step(z: f64, up: bool) -> f64 {
    if up {
        STEPS.iter().copied().find(|s| *s > z * 1.001).unwrap_or(256.0)
    } else {
        STEPS.iter().rev().copied().find(|s| *s < z * 0.999).unwrap_or(0.02)
    }
}

/// The zoom tool: a click zooms a step in (or out) about the clicked point, a dragged area fills
/// the view.
fn zoom_at(s: &mut Session, p: &Value) -> Result<Value> {
    let (Some(x), Some(y)) = (num(p, "x").filter(|v| v.is_finite()), num(p, "y").filter(|v| v.is_finite())) else {
        return Err(bad("view.zoomAt", "`x` and `y` (page coordinates) are required"));
    };
    let v = view(s)?;
    match (num(p, "width"), num(p, "height")) {
        (Some(w), Some(h)) if w.is_finite() && h.is_finite() && w > 0.0 && h > 0.0 => {
            v.fit(figcraft_geom::Rect::new(x, y, x + w, y + h), ViewState::MAX_ZOOM);
        }
        _ => {
            let z = step(v.zoom, !boolean(p, "out").unwrap_or(false));
            v.set_zoom_at(z, (x, y));
        }
    }
    Ok(json!({"zoom": v.zoom, "cx": v.cx, "cy": v.cy}))
}

/// Select and fit the next (`dir` 1) or previous (-1) top-level frame on the page.
fn zoom_frame(s: &mut Session, dir: i64) -> Result<Value> {
    let ds = s.ds()?;
    let frames = ds.doc.top_frames(ds.page);
    if frames.is_empty() {
        return ok();
    }
    let cur = ds.selection.first().and_then(|i| ds.doc.top_level_frame(*i)).and_then(|f| frames.iter().position(|x| *x == f));
    let n = frames.len() as i64;
    let next = match cur {
        Some(c) => (c as i64 + dir).rem_euclid(n) as usize,
        None => 0,
    };
    let Some(f) = frames.get(next).copied() else { return ok() };
    let b = ds.doc.world_bounds(f).unwrap_or_default();
    let ds = s.ds_mut()?;
    ds.selection = vec![f];
    ds.view.fit(b, 256.0);
    Ok(json!({"frame": f}))
}

/// Move to the next (`dir` 1) or previous (-1) page, skipping dividers, and fit it.
fn page_step(s: &mut Session, dir: i64) -> Result<Value> {
    let ds = s.ds()?;
    let pages = &ds.doc.pages;
    let i = pages.iter().position(|p| *p == ds.page).unwrap_or(0) as i64;
    let n = pages.len() as i64;
    // Dividers never open: step over them, and stay put when only dividers lie ahead.
    let mut next = i + dir;
    let pg = loop {
        let page = usize::try_from(next).ok().and_then(|k| pages.get(k).copied());
        match page {
            Some(p) if !ds.doc.is_divider(p) => break p,
            Some(_) if dir != 0 && next >= 0 && next < n => next += dir,
            _ => break ds.page,
        }
    };
    let ds = s.ds_mut()?;
    ds.open_page(pg);
    ds.selection.clear();
    Ok(json!({"page": pg}))
}

/// Ask the UI to open or toggle the panel or dialog named `kind`.
fn ui(s: &mut Session, kind: &str) -> Result<Value> {
    s.request_ui(kind, json!({}));
    ok()
}

/// Move the keyboard `step` regions on (toolbar, layers, canvas, properties): the UI does it.
fn region(s: &mut Session, step: i64) -> Result<Value> {
    s.request_ui("focus.region", json!({"step": step}));
    ok()
}

/// Step the interface size through the Preferences sizes: `dir` 1 up, -1 down, 0 back to the
/// system's size (1). At an end it stays. Kept at once, as a size picked in Preferences is.
fn ui_scale_step(s: &mut Session, dir: i32) -> Result<Value> {
    let now = s.prefs.ui_scale;
    let next = match dir {
        0 => 1.0,
        1 => crate::UI_SCALE_SIZES.iter().copied().find(|v| *v > now + 1e-9).unwrap_or(now),
        _ => crate::UI_SCALE_SIZES.iter().rev().copied().find(|v| *v < now - 1e-9).unwrap_or(now),
    };
    if (next - now).abs() > 1e-9 {
        s.prefs.ui_scale = next;
        s.prefs_unsaved = true;
    }
    Ok(json!({"scale": s.prefs.ui_scale}))
}

/// Set one of the preferences' on/off settings from `on`, or toggle it when `on` is absent.
fn pref(s: &mut Session, p: &Value, f: fn(&mut crate::Prefs) -> &mut bool) -> Result<Value> {
    let slot = f(&mut s.prefs);
    *slot = boolean(p, "on").unwrap_or(!*slot);
    Ok(json!({"on": *slot}))
}

/// Switch the tool, unless the file is read-only and this tool needs editing.
pub(crate) fn tool(s: &mut Session, t: ToolId) -> Result<Value> {
    // A file you can't edit now (view only, or on its way to a server): moving around only, and
    // commenting with a comment link.
    if let Some(why) = s.active_read_only().filter(|why| !crate::live::tool_left(why, t)) {
        return Err(EngineError::Disabled(format!("tool.{}", t.id()), why.into()));
    }
    s.set_tool(t);
    Ok(json!({"tool": t.id()}))
}

/// Shift+T and choosing the Annotation tool: with a layer selected (or named by `id`/`ids`) the UI
/// is asked for its note at once; in the tool, a press on a layer selects it and asks (the engine
/// never writes the note). A named target is checked first: one that isn't a layer in the document
/// is an error and the tool stays as it was.
fn annotation(s: &mut Session, p: &Value) -> Result<Value> {
    let named = p.get("id").is_some_and(|v| !v.is_null()) || p.get("ids").is_some_and(|v| !v.is_null());
    let first = crate::params::targets(s, p).into_iter().find(|i| s.doc().is_ok_and(|d| d.node(*i).is_some_and(|n| !n.is_page())));
    if named && first.is_none() {
        return Err(bad("tool.annotation", "`id` must name a layer in this document (not a page)".to_string()));
    }
    let r = tool(s, ToolId::Annotation)?;
    if let Some(id) = first {
        if named {
            crate::cmd::edit::select_and_page(s, vec![id])?;
        }
        s.request_ui("annotation.new", json!({"id": id}));
    }
    Ok(r)
}

/// The View menu's commands and their parameters.
pub fn specs() -> Vec<CommandSpec> {
    vec![
        spec!("view.zoomIn", "Zoom in", "{}", false, |s, _| {
            let z = view(s)?.zoom;
            zoom_to(s, step(z, true))
        }),
        spec!("view.zoomOut", "Zoom out", "{}", false, |s, _| {
            let z = view(s)?.zoom;
            zoom_to(s, step(z, false))
        }),
        spec!("view.zoom100", "Zoom to 100%", "{}", false, |s, _| zoom_to(s, 1.0)),
        spec!("view.zoom50", "Zoom to 50%", "{}", false, |s, _| zoom_to(s, 0.5)),
        spec!("view.zoom200", "Zoom to 200%", "{}", false, |s, _| zoom_to(s, 2.0)),
        spec!("view.zoomFit", "Zoom to fit", "{}", false, |s, _| {
            let ds = s.ds_mut()?;
            if let Some(b) = ds.doc.page_content_bounds(ds.page) {
                ds.view.fit(b, 256.0);
            }
            Ok(json!({"zoom": ds.view.zoom}))
        }),
        spec!("view.zoomSelection", "Zoom to selection", "{}", false, |s, _| {
            let ds = s.ds_mut()?;
            if let Some(b) = ds.doc.bounds_of(&ds.selection) {
                ds.view.fit_selection(b, 256.0);
            }
            Ok(json!({"zoom": ds.view.zoom}))
        }),
        spec!(
            "view.set",
            "Set view",
            "{zoom?, cx?, cy? (page coordinate at the centre), vw?, vh? (viewport size), bottomInset? (height of the strip the bottom toolbar covers)}",
            false,
            |s, p| {
                let v = view(s)?;
                if let Some(z) = num(p, "zoom") {
                    v.zoom = z.clamp(ViewState::MIN_ZOOM, ViewState::MAX_ZOOM);
                }
                v.cx = num_or(p, "cx", v.cx);
                v.cy = num_or(p, "cy", v.cy);
                if let Some(w) = num(p, "vw") {
                    v.vw = w.clamp(10.0, 20000.0);
                }
                if let Some(h) = num(p, "vh") {
                    v.vh = h.clamp(10.0, 20000.0);
                }
                if let Some(i) = num(p, "bottomInset") {
                    v.bottom_inset = i.clamp(0.0, 20000.0);
                }
                Ok(serde_json::to_value(&*v).unwrap_or(Value::Null))
            }
        ),
        spec!(
            "view.zoomAt",
            "Zoom tool",
            "{x, y (page point kept in place), out? (zoom out a step), width?, height? (an area to fit instead)}",
            false,
            zoom_at
        ),
        spec!("view.get", "Get view", "{}", false, |s, _| Ok(serde_json::to_value(&s.ds()?.view).unwrap_or(Value::Null))),
        spec!("view.prevFrame", "Zoom to previous frame", "{}", false, |s, _| zoom_frame(s, -1)),
        spec!("view.nextFrame", "Zoom to next frame", "{}", false, |s, _| zoom_frame(s, 1)),
        spec!("view.prevPage", "Previous page", "{}", false, |s, _| page_step(s, -1)),
        spec!("view.nextPage", "Next page", "{}", false, |s, _| page_step(s, 1)),
        spec!("view.pixelGrid", "Pixel grid", "{on?}", false, |s, p| toggle(s, p, "view.pixelGrid")),
        spec!("view.layoutGrids", "Layout grids", "{on?}", false, |s, p| toggle(s, p, "view.layoutGrids")),
        spec!("view.rulers", "Rulers", "{on?}", false, |s, p| toggle(s, p, "view.rulers")),
        spec!("view.slices", "Slices", "{on?}", false, |s, p| toggle(s, p, "view.slices")),
        spec!("view.comments", "Comments", "{on?}", false, |s, p| toggle(s, p, "view.comments")),
        spec!("view.multiplayerCursors", "Multiplayer cursors", "{on?}  others' cursors in a live session", false, |s, p| {
            toggle(s, p, "view.multiplayerCursors")
        }),
        spec!("view.pan", "Pan the view", "{dx, dy (arrow-key steps, e.g. 1 or -1), big? (five times as far, like Shift)}", false, pan),
        spec!("view.outlines", "Outlines", "{on?}", false, |s, p| toggle(s, p, "view.outlines")),
        spec!("view.outlinesSelection", "Outlines for selection", "{on?}  outline mode for the selected layers only", false, |s, p| {
            toggle(s, p, "view.outlinesSelection")
        }),
        spec!(
            "view.outlinesHiddenLayers",
            "Include hidden layers in outlines",
            "{on?}  outline mode (and outlines for the selection) outlines hidden layers too; they can be clicked there",
            false,
            |s, p| { toggle(s, p, "view.outlinesHiddenLayers") }
        ),
        spec!(
            "view.outlinesObjectBounds",
            "Include object bounds in outlines",
            "{on?}  outline mode also draws each layer's box (groups, text, vectors); a click on a box's edge picks its layer",
            false,
            |s, p| { toggle(s, p, "view.outlinesObjectBounds") }
        ),
        spec!("view.maskOutlines", "Mask outlines", "{on?}", false, |s, p| toggle(s, p, "view.maskOutlines")),
        spec!("view.pixelPreview", "Pixel preview", "{on?, scale? (1|2: rendered pixels per page pixel; turns it on)}", false, pixel_preview),
        spec!("view.frameOutlines", "Frame outlines", "{on?}", false, |s, p| toggle(s, p, "view.frameOutlines")),
        spec!(
            "view.proofSrgb",
            "Soft-proof sRGB",
            "{on?}  mark the colours of a Display P3 file that sRGB screens and files can't show",
            false,
            |s, p| { toggle(s, p, "view.proofSrgb") }
        ),
        spec!("view.snapGeometry", "Snap to geometry", "{on?}", false, |s, p| toggle(s, p, "view.snapGeometry")),
        spec!("view.snapObjects", "Snap to objects", "{on?}", false, |s, p| toggle(s, p, "view.snapObjects")),
        spec!("view.snapPixel", "Snap to pixel grid", "{on?}", false, |s, p| toggle(s, p, "view.snapPixel")),
        spec!("view.toggleUi", "Show/Hide UI", "{on?}", false, |s, p| flag(s, p, |v| &mut v.ui_hidden)),
        spec!(
            "view.minimize",
            "Minimize the interface",
            "{on?}  collapses the navigation bar and both sidebars and keeps the toolbar (Shift+Cmd/Ctrl+\\, the Minimize button by the file name); the right sidebar shows while something is selected",
            false,
            |s, p| flag(s, p, |v| &mut v.ui_minimized)
        ),
        spec!("view.fullscreen", "Full screen", "{on?}  the window fills the screen (the desktop app; a no-op headless)", false, |s, p| {
            s.request_ui("window.fullscreen", json!({"on": boolean(p, "on")}));
            ok()
        }),
        spec!("view.layers", "Layers panel", "{}", false, |s, _| ui(s, "panel.layers")),
        spec!("view.assets", "Assets panel", "{}", false, |s, _| ui(s, "panel.assets")),
        spec!("view.design", "Design panel", "{}", false, |s, _| ui(s, "panel.design")),
        spec!("view.prototype", "Prototype panel", "{}", false, |s, _| ui(s, "panel.prototype")),
        spec!("view.designPrototype", "Switch between Design and Prototype", "{}", false, |s, _| ui(s, "panel.designPrototype")),
        spec!("view.devMode", "Developer Mode", "{}", false, |s, _| ui(s, "panel.devMode")),
        spec!("view.leftSidebar", "Show/Hide left sidebar", "{}", false, |s, _| ui(s, "panel.leftSidebar")),
        spec!(
            "view.panelWidths",
            "Reset panel widths",
            "{left?, right? (the panels' widths in pixels, kept within their limits)}  without either, both go back to their default width (a double-click on a panel's edge does it for that panel)",
            false,
            |s, p| {
                let width = |k| num(p, k).filter(|w| w.is_finite()).map(|w| w.clamp(0.0, 10_000.0));
                s.request_ui("panel.widths", json!({"left": width("left"), "right": width("right")}));
                ok()
            }
        ),
        // Several windows: the desktop app opens and focuses them (no-ops headless and in the browser).
        spec!(
            "window.new",
            "New window",
            "{path?, index?}  a new window with a new file, the file at `path`, or open file `index` moved into it",
            false,
            |s, p| {
                let index = if num(p, "index").is_some() { Some(req_index("window.new", p, "index")?) } else { None };
                s.request_ui("window.new", json!({"path": string(p, "path"), "index": index}));
                ok()
            }
        ),
        spec!("window.focus", "Bring window to front", "{id}  a window id (control channel `window.list`)", false, |s, p| {
            let id = req_index("window.focus", p, "id")?;
            s.request_ui("window.focus", json!({"id": id}));
            ok()
        }),
        spec!("view.nextRegion", "Focus next region", "{}", false, |s, _| region(s, 1)),
        spec!("view.previousRegion", "Focus previous region", "{}", false, |s, _| region(s, -1)),
        spec!(
            "view.contextMenu",
            "Show context menu",
            "{}  the selection's context menu at its layer row (when the layers panel has the keyboard) or on the canvas; the menu takes the keyboard",
            false,
            |s, _| ui(s, "contextMenu")
        ),
        spec!("view.themeLight", "Light theme", "{}", false, |s, _| {
            s.prefs.theme = "light".into();
            ok()
        }),
        spec!("view.themeDark", "Dark theme", "{}", false, |s, _| {
            s.prefs.theme = "dark".into();
            ok()
        }),
        spec!("view.themeSystem", "Follow system theme", "{}", false, |s, _| {
            s.prefs.theme = "system".into();
            ok()
        }),
        spec!("pref.keepTool", "Keep tool selected after use", "{on?}", false, |s, p| pref(s, p, |x| &mut x.keep_tool)),
        spec!("pref.highlightHover", "Highlight layers on hover", "{on?}", false, |s, p| pref(s, p, |x| &mut x.highlight_on_hover)),
        spec!("pref.renameDuplicates", "Rename duplicated layers", "{on?}", false, |s, p| pref(s, p, |x| &mut x.rename_duplicates)),
        spec!("pref.showDimensions", "Show dimensions on objects", "{on?}", false, |s, p| pref(s, p, |x| &mut x.show_dimensions)),
        spec!("pref.numberKeysOpacity", "Use number keys for opacity", "{on?}", false, |s, p| pref(s, p, |x| &mut x.number_keys_opacity)),
        spec!(
            "pref.scrollWheelZoom",
            "Scroll wheel zoom",
            "{on?}  a mouse wheel zooms the canvas about the pointer and Cmd/Ctrl+wheel scrolls it (Shift+wheel still scrolls sideways; trackpads are unchanged) โ†’ {on}",
            false,
            |s, p| pref(s, p, |x| &mut x.scroll_wheel_zoom)
        ),
        spec!(
            "pref.invertZoom",
            "Invert zoom direction",
            "{on?}  reverses wheel zoom: Cmd/Ctrl+wheel, and a plain mouse wheel with Scroll wheel zoom on, zoom out where they would zoom in (a trackpad pinch and panning are unchanged) โ†’ {on}",
            false,
            |s, p| pref(s, p, |x| &mut x.invert_zoom)
        ),
        spec!("pref.reduceMotion", "Reduce motion", "{on?}", false, |s, p| pref(s, p, |x| &mut x.reduce_motion)),
        spec!(
            "pref.uiScale",
            "Interface size",
            "{scale? (a size from 0.75 to 3 relative to the system's display scale: 1 is the system's own size, so 1.25 is 125 %, not 125; outside the range it stops at the nearest end; \"auto\" is 1; omit: just read it)} โ†’ {scale}: how large the whole interface is drawn; the canvas zoom is separate",
            false,
            |s, p| {
                match get(p, "scale") {
                    None => {}
                    Some(Value::String(v)) if v.trim().eq_ignore_ascii_case("auto") => s.prefs.ui_scale = 1.0,
                    Some(_) => {
                        let scale = req_num("pref.uiScale", p, "scale")?;
                        s.prefs.ui_scale = crate::clamp_ui_scale(scale).ok_or_else(|| bad("pref.uiScale", "`scale` must be a finite number"))?;
                    }
                }
                Ok(json!({"scale": s.prefs.ui_scale}))
            }
        ),
        spec!(
            "pref.uiScaleUp",
            "Larger interface",
            "{}  the next of the Preferences sizes above the current one; at the largest it stays โ†’ {scale}",
            false,
            |s, _| ui_scale_step(s, 1)
        ),
        spec!(
            "pref.uiScaleDown",
            "Smaller interface",
            "{}  the next of the Preferences sizes below the current one; at the smallest it stays โ†’ {scale}",
            false,
            |s, _| ui_scale_step(s, -1)
        ),
        spec!("pref.uiScaleReset", "Default interface size", "{}  back to the system's own size (1) โ†’ {scale}", false, |s, _| ui_scale_step(s, 0)),
        spec!("pref.autoSave", "Save files automatically", "{on?}", false, |s, p| pref(s, p, |x| &mut x.auto_save)),
        spec!("pref.startOnHome", "Start on the Home screen", "{on?}", false, |s, p| pref(s, p, |x| &mut x.start_on_home)),
        spec!("pref.nudge", "Nudge amount", "{small?, big?}", false, |s, p| {
            s.prefs.nudge_small = num(p, "small").unwrap_or(s.prefs.nudge_small).clamp(0.01, 1000.0);
            s.prefs.nudge_big = num(p, "big").unwrap_or(s.prefs.nudge_big).clamp(0.01, 10000.0);
            Ok(json!({"small": s.prefs.nudge_small, "big": s.prefs.nudge_big}))
        }),
        spec!(
            "pref.userName",
            "Your name",
            "{name (blank: the default: \"You\" on comments, \"Guest N\" in live sessions)} โ†’ {name}: what your comments are signed with and others see you as in live sessions; the live sessions you're in show the new name at once (blank keeps the name they gave you until you join again)",
            false,
            |s, p| {
                let name = req_string("pref.userName", p, "name")?;
                let name: String = name.trim().chars().filter(|c| !c.is_control()).take(crate::live::MAX_NAME).collect();
                s.prefs.user_name = if name.is_empty() { super::comment::DEFAULT_AUTHOR.into() } else { name };
                s.live_rename();
                Ok(json!({"name": s.prefs.user_name}))
            }
        ),
        spec!(
            "pref.publishServer",
            "Server for online sharing",
            "{url?: ws://host:port/ or wss://host/path/ (no key; empty: online sharing off; omit: back to the built-in server)} โ†’ {url, default (the built-in server)}: where Share โ–ธ Online keeps files and where join codes are asked",
            false,
            |s, p| {
                const CMD: &str = "pref.publishServer";
                let url = match get(p, "url") {
                    None => crate::live::DEFAULT_SERVER.to_string(),
                    Some(_) => req_string(CMD, p, "url")?.trim().to_string(),
                };
                let web_socket = url.starts_with("ws://") || url.starts_with("wss://");
                if !url.is_empty()
                    && (!web_socket || url.len() > 500 || url.contains(|c: char| c.is_whitespace() || c.is_control() || c == '?' || c == '#'))
                {
                    return Err(bad(
                        CMD,
                        "the server's address is ws://host:port/ or wss://host/path/, without a key (it is saved with your preferences)",
                    ));
                }
                s.prefs.publish_server = url;
                Ok(json!({"url": s.prefs.publish_server, "default": crate::live::DEFAULT_SERVER}))
            }
        ),
        spec!(
            "pref.language",
            "Interface language",
            "{language: system|en|bs|cs|ru|es|es-419|fr|de|pt-BR|ja|ka|ko|vi|zh-Hans|zh-Hant|โ€ฆ; else English}",
            false,
            |s, p| {
                let lang = req_string("pref.language", p, "language")?;
                let lang = lang.trim();
                // A BCP 47-style tag ("es", "pt-BR", "zh_Hans") or "system".
                let tag = lang.len() <= 35
                    && lang.split(['-', '_']).all(|part| !part.is_empty() && part.len() <= 8 && part.chars().all(|c| c.is_ascii_alphanumeric()));
                if !tag {
                    return Err(bad("pref.language", format!("`{lang}` is not a language code")));
                }
                s.prefs.language = lang.to_string();
                Ok(json!({"language": s.prefs.language}))
            }
        ),
        spec!("app.preferences", "Preferences", "{}", false, |s, _| ui(s, "dialog.preferences")),
        spec!("app.actions", "Actions", "{}", false, |s, _| ui(s, "palette.actions")),
        spec!("help.shortcuts", "Keyboard shortcuts", "{}", false, |s, _| ui(s, "panel.shortcuts")),
        spec!("help.about", "About FigCraft", "{}", false, |s, _| ui(s, "dialog.about")),
        spec!("help.page", "Help page", "{}", false, |s, _| ui(s, "open.help")),
        spec!(
            "help.gettingStarted",
            "Getting started",
            "{show? (default true; false closes them)}  the Getting started tips on the home screen: shows them again (the app opens the home screen), or closes them until asked for โ†’ {shown}",
            false,
            |s, p| {
                let show = boolean(p, "show").unwrap_or(true);
                s.prefs.getting_started_dismissed = !show;
                if show {
                    s.request_ui("home.gettingStarted", json!({}));
                }
                Ok(json!({"shown": show}))
            }
        ),
        spec!("libraries.open", "Libraries", "{}", false, |s, _| ui(s, "panel.libraries")),
        spec!(
            "tool.set",
            "Choose tool",
            "{tool: move|scale|hand|frame|section|slice|rectangle|line|arrow|ellipse|polygon|star|pen|pencil|text|comment|annotation|shapeBuilder | on boards: sticky|shape|connector|marker|highlighter|eraser|stamp}",
            false,
            |s, p| {
                let t = req_string("tool.set", p, "tool")?;
                let t = ToolId::from_id(&t).ok_or_else(|| bad("tool.set", format!("unknown tool `{t}`")))?;
                if t.on_boards() {
                    crate::board::require(s, &format!("tool.{}", t.id()))?;
                }
                if t == ToolId::Annotation {
                    return annotation(s, &json!({}));
                }
                tool(s, t)
            }
        ),
        spec!(
            "tool.crosshair",
            "Move the placement crosshair",
            "{dx?, dy? (arrow-key steps, e.g. 1 or -1), big? (the large nudge, like Shift)} โ€” the arrows with a shape or frame tool chosen and nothing selected: the first shows the crosshair in the middle of the view, the next move it by the nudge amount; Enter (`tool.place`) puts the object there",
            false,
            |s, p| {
                if !s.tool.tool.draws_shape() {
                    return Err(EngineError::Disabled("tool.crosshair".into(), "choose a shape or frame tool first".into()));
                }
                let step = if boolean(p, "big").unwrap_or(false) { s.prefs.nudge_big } else { s.prefs.nudge_small };
                let dir = |k| num(p, k).filter(|v| v.is_finite()).unwrap_or(0.0).clamp(-100.0, 100.0) * step;
                let (dx, dy) = (dir("dx"), dir("dy"));
                let (uid, page, centre, half) = {
                    let ds = s.ds()?;
                    let z = ds.view.zoom.max(1e-6);
                    (ds.uid, ds.page, figcraft_geom::Point::new(ds.view.cx, ds.view.cy), (ds.view.vw / z / 2.0, ds.view.vh / z / 2.0))
                };
                // "It will appear in the middle of the viewport": the first arrow shows it there (a
                // crosshair left on another page or document starts over).
                let at = match s.crosshair() {
                    Some(c) => figcraft_geom::Point::new(c.x + dx, c.y + dy),
                    None => centre,
                };
                s.tool.place_at = Some(at);
                s.tool.place_on = Some((uid, page));
                if let Ok(ds) = s.ds_mut() {
                    // "Move the crosshair around the canvas": nudged past an edge of the view, the
                    // view pans by the overshoot to keep it in sight.
                    let v = &mut ds.view;
                    v.cx += (at.x - (v.cx + half.0)).max(0.0) + (at.x - (v.cx - half.0)).min(0.0);
                    v.cy += (at.y - (v.cy + half.1)).max(0.0) + (at.y - (v.cy - half.1)).min(0.0);
                    ds.revision += 1;
                }
                Ok(json!({"x": at.x, "y": at.y}))
            }
        ),
        spec!(
            "tool.place",
            "Place with the tool",
            "{tool? (a shape or frame tool; default the current one), x?, y? (its centre, page coords; default the middle of the view)} โ€” what a click with the tool makes, selected (Enter with the tool chosen)",
            false,
            |s, p| {
                if let Some(t) = string(p, "tool") {
                    let t = ToolId::from_id(&t).ok_or_else(|| bad("tool.place", format!("unknown tool `{t}`")))?;
                    tool(s, t)?;
                }
                let at = num(p, "x").zip(num(p, "y")).map(|(x, y)| figcraft_geom::Point::new(x, y));
                s.place(at)?;
                Ok(json!({"ids": s.selection()}))
            }
        ),
        spec!(
            "tool.pencilBrush",
            "Pencil brush",
            "{preset? (taper|ink|ribbon|bristle|dots|stars|confetti|leaves | null: plain), spacing?, sizeJitter?, rotationJitter?, scatter?, seed?} (the brush new Pencil strokes get; omit `preset` to read it)",
            false,
            |s, p| {
                // `null` (unlike a missing preset) clears the brush.
                if let Some(v) = p.get("preset") {
                    let v = if v.is_null() { Value::Null } else { p.clone() };
                    s.tool.pencil_brush = super::props::brush_of(&v).ok_or_else(|| bad("tool.pencilBrush", super::props::BRUSH_HELP))?;
                }
                Ok(json!({"brush": s.tool.pencil_brush}))
            }
        ),
        spec!(
            "tool.scaleAnchor",
            "Scale anchor",
            "{anchor?: tl|t|tr|l|c|r|bl|b|br} (the origin of the Scale tool's factor field: the point of the selection that stays put; defaults to c, handle drags pivot on the opposite handle whatever it is; omit to read it)",
            false,
            |s, p| {
                if let Some(a) = string(p, "anchor") {
                    s.tool.scale_anchor = crate::tools::anchor_of(&a).ok_or_else(|| bad("tool.scaleAnchor", format!("unknown anchor `{a}`")))?;
                    if let Ok(ds) = s.ds_mut() {
                        ds.revision += 1;
                    }
                }
                Ok(json!({"anchor": crate::tools::anchor_name(s.tool.scale_anchor)}))
            }
        ),
        spec!("tool.move", "Move", "{}", false, |s, _| tool(s, ToolId::Move)),
        spec!("tool.scale", "Scale", "{}", false, |s, _| tool(s, ToolId::Scale)),
        spec!("tool.hand", "Hand", "{}", false, |s, _| tool(s, ToolId::Hand)),
        spec!("tool.frame", "Frame", "{}", false, |s, _| tool(s, ToolId::Frame)),
        spec!("tool.section", "Section", "{}", false, |s, _| tool(s, ToolId::Section)),
        spec!("tool.slice", "Slice", "{}", false, |s, _| tool(s, ToolId::Slice)),
        spec!("tool.rectangle", "Rectangle", "{}", false, |s, _| tool(s, ToolId::Rectangle)),
        spec!("tool.line", "Line", "{}", false, |s, _| tool(s, ToolId::Line)),
        spec!("tool.arrow", "Arrow", "{}", false, |s, _| tool(s, ToolId::Arrow)),
        spec!("tool.ellipse", "Ellipse", "{}", false, |s, _| tool(s, ToolId::Ellipse)),
        spec!("tool.polygon", "Polygon", "{}", false, |s, _| tool(s, ToolId::Polygon)),
        spec!("tool.star", "Star", "{}", false, |s, _| tool(s, ToolId::Star)),
        spec!("tool.pen", "Pen", "{}", false, |s, _| tool(s, ToolId::Pen)),
        spec!("tool.pencil", "Pencil", "{}", false, |s, _| tool(s, ToolId::Pencil)),
        spec!("tool.text", "Text", "{}", false, |s, _| tool(s, ToolId::Text)),
        spec!("tool.textOnPath", "Text on a path", "{}  a click on a shape's or vector's path puts new text on it", false, |s, _| {
            tool(s, ToolId::TextOnPath)
        }),
        spec!("tool.comment", "Comment", "{}", false, |s, _| tool(s, ToolId::Comment)),
        // Shift+T: with a layer selected (or an `id`) the UI is asked for its note at once; in the
        // tool, a press on a layer selects it and asks (the engine never writes the note).
        spec!("tool.annotation", "Annotation", "{id?|ids?}", false, annotation),
        spec!("tool.shapeBuilder", "Shape builder", "{}", false, |s, _| tool(s, ToolId::ShapeBuilder)),
        // `apply: false` is for the UI colour picker: the eyedropper only samples (into
        // `ToolState::picked`) and the picker writes the colour to the paint it edits.
        spec!("edit.pickColor", "Pick color", "{apply?}", false, |s, p| {
            let r = tool(s, ToolId::Eyedropper)?;
            s.tool.pick_only = !boolean(p, "apply").unwrap_or(true);
            s.tool.picked = None;
            Ok(r)
        }),
    ]
}

#[allow(dead_code)]
fn unused(_: NodeId) {}

#[cfg(test)]
mod start_on_home_tests {
    use serde_json::json;

    use crate::Session;

    #[test]
    fn start_on_home_is_a_preference_that_persists() {
        let mut s = Session::new();
        assert!(!s.prefs.start_on_home);
        assert_eq!(s.execute("pref.startOnHome", &json!({})).unwrap()["on"], true);
        assert!(s.prefs.start_on_home);
        // Saved with the other preferences and read back; older settings files without it read as off.
        let saved: crate::Prefs = serde_json::from_value(serde_json::to_value(&s.prefs).unwrap()).unwrap();
        assert!(saved.start_on_home);
        assert_eq!(s.execute("pref.startOnHome", &json!({"on": false})).unwrap()["on"], false);
        let old: crate::Prefs = serde_json::from_value(json!({"theme": "dark"})).unwrap();
        assert!(!old.start_on_home);
    }

    #[test]
    fn the_arrows_pan_64_px_and_320_with_shift_as_measured_in_figma() {
        let mut s = crate::Session::new();
        s.execute("view.set", &json!({"zoom": 1.0, "cx": 300, "cy": 200})).unwrap();
        s.execute("view.pan", &json!({"dx": 1})).unwrap();
        let v = &s.ds().unwrap().view;
        assert_eq!((v.cx, v.cy), (364.0, 200.0), "one press pans 64 px");
        s.execute("view.pan", &json!({"dy": -1, "big": true})).unwrap();
        let v = &s.ds().unwrap().view;
        assert_eq!((v.cx, v.cy), (364.0, -120.0), "Shift pans 320 px");
    }

    #[test]
    fn the_arrow_pan_is_the_same_screen_distance_at_any_zoom_on_both_axes() {
        // (zoom, dx, dy, big, expected centre change in document px)
        let cases = [
            (2.0, 1.0, 0.0, false, 32.0, 0.0),
            (0.5, 1.0, 0.0, false, 128.0, 0.0),
            (2.0, 0.0, 1.0, true, 0.0, 160.0),
            (0.5, 0.0, 1.0, true, 0.0, 640.0),
            (1.0, -1.0, 0.0, false, -64.0, 0.0),
            (1.0, 1.0, 0.0, true, 320.0, 0.0),
            (1.0, -1.0, 0.0, true, -320.0, 0.0),
            (1.0, 0.0, -1.0, false, 0.0, -64.0),
            (1.0, 0.0, 1.0, false, 0.0, 64.0),
            (1.0, 0.0, -1.0, true, 0.0, -320.0),
        ];
        for (zoom, dx, dy, big, ex, ey) in cases {
            let mut s = crate::Session::new();
            s.execute("view.set", &json!({"zoom": zoom, "cx": 300, "cy": 200})).unwrap();
            s.execute("view.pan", &json!({"dx": dx, "dy": dy, "big": big})).unwrap();
            let v = &s.ds().unwrap().view;
            let got = (v.cx - 300.0, v.cy - 200.0);
            assert!(
                (got.0 - ex).abs() < 1e-6 && (got.1 - ey).abs() < 1e-6,
                "zoom {zoom} dx {dx} dy {dy} big {big}: moved {got:?}, expected {:?}",
                (ex, ey)
            );
        }
    }
}