Part of #785: run and command_batch steps can use earlier results

A run (vectorcraft-cli run, the MCP command_batch tool) had no way to use
an id an earlier step returned. A parameter string that is exactly
$N.path or $last.path now takes that value from step N's result
(0-based), e.g. {"id":"$1.id"}; $$ starts a literal $, and a
reference to nothing fails the step. Objects given to a command are now
used as given: an ids element or id that isn't an object id (or an
unresolved reference) fails instead of the command acting on the
selection. text.setRangeStyle styles the selected type object when no
id is given, as text.setStyle does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

ROADMAP.md

@@ -98,7 +98,7 @@ grade by behaviour against `plan/illustrator/`, not by whether a menu item exist
   - JSON-lines control channel with real egui pointer and keyboard injection.
   - 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.
   - MCP protocol: five prompts (`prompts/list` / `prompts/get`: poster, icon set, recolour, trace-and-style, export set), `completion/complete` for prompt arguments and template variables read from the live catalogues (formats, effect ids, command ids, trace presets, swatch and object ids), four resource templates (`vectorcraft://object/{id}`, `//command/{id}`, `//effect/{id}`, `//swatch/{name}`) so an agent reads one thing instead of the whole document, and `logging/setLevel` with `notifications/message`. `window.panel` ids are case-insensitive (display labels work too), `vectorcraft://object/{id}` reads through `document.node {summary: true}` (the same reply bytes from one lookup instead of summarizing the whole document: a leaf read on a 2,000-object document drops from ~20 ms to ~0.06 ms), large containers slice with `document.node {depth?, childLimit?}` (truncated levels report `childCount`), `document.inspect` and the `inspect_document` tool slice the same way so a depth-0 read is the layer skeleton (~9.7 KB instead of ~2 MB on a 2,000-object document), `document.find` locates nodes by name/kind/text with ancestor paths, and the CLI sweeps the protocol surface over stdio against the compiled binary. `docs/mcp.md` has a Protocol section covering the capability table and what is deliberately absent (subscriptions, progress, cancellation, sampling, elicitation, Streamable HTTP — all of which need the transport to interleave reads).
-  - Headless CLI (`vectorcraft-cli run`, `convert`, `info`, `bench`, `perf`, `mcp`).
+  - Headless CLI (`vectorcraft-cli run`, `convert`, `info`, `bench`, `perf`, `mcp`). A `run` step, like a `command_batch` step over MCP, can use an earlier step's result (`"$1.id"`, #785).
   - Actions panel that records and plays back commands.
 - **UI:** Illustrator 2026 layout restyled to measured values:
   - Medium Dark theme, categorized and Advanced toolbars (a tool group's flyout opens on a right press, a long press or a press on its corner triangle), 35 pt document tabs, 33 pt panel tabs.
@@ -153,7 +153,7 @@ grade by behaviour against `plan/illustrator/`, not by whether a menu item exist
 - **Image Trace Flat Logo mode:** a fourth mode beside Black and White, Grayscale and Color, for flat-colour logos. Each pixel is read as a blend of the logo's colours (found automatically or named), the blend is interpolated smoothly and every outline is placed where two colours are equally present, so edges are accurate to a fraction of a pixel. Outlines are then cleaned: corners the blur rounded are put back, near-straight runs and near-circular arcs become exact lines and arcs, the rest is fitted with as few Béziers as the tolerance allows, touching colours overlap by a hair so no gap opens, and an outline that strays from the raw contour is fitted plainly instead. Gradients and photos are refused with advice to use Color. *Measured* (a local experiment, not run in CI): a flat-colour logo's vector original was rendered down to a soft 199 × 100 px transparent PNG, traced, and the result compared with the original at 1600 px wide. The built-in colour presets (6 Colors, 16 Colors, High Fidelity Photo, Low Fidelity Photo) had a mean edge error of 2.5 to 3.4 px and region overlap of 0.88 to 0.91; Flat Logo had 0.78 px and 0.966 (0.48 px and 0.975 from a crisp source), in about 0.1 s. Limits: flat-colour art only; needle-thin sharp tips are shortened by about 1.7 source pixels because the blur erases them; it works at no more than 1024 px on the long side (larger images are averaged down first); only one logo family has been scored against a vector original.
 - **Advanced art:** live Blends (steps/distance/smooth colour, editable spine, anchor-targeted Blend tool, faithful interpolation, knockout), Envelope Distort (warp/mesh/top object, Reset, full Envelope Options, mesh handles, Edit Contents; type, images, symbols, gradients, patterns and appearance distorted everywhere), Liquify tools with options and pen pressure, Puppet Warp with rotating pins, Perspective Grid with presets, movable planes and projected type (choosing a perspective tool shows the grid; Hide Grid hides it with the tool still chosen), Gradient Mesh, Shape Builder (stroke-only open paths and lines cut the regions they cross and enclose regions of their own; filled open paths count as closed; erase mode while Alt/Option is held: a minus pointer, red highlights of what will go, a click or drag deletes the regions touched, the pieces of open lines and the edges (outline pieces between the points where paths meet, opening their paths there) it passes over, one undo step, `shapeBuilder.merge {erase}` and `shapeBuilder.regions` edges over MCP), Live Paint (every path an edge, open lines included), Image Trace (12 presets, colour layers traced in parallel; a trace past two million anchor points or an image over 64 megapixels is refused with advice rather than running out of memory, and a selection too large to outline shows its bounds (#525); Object › Image Trace › Make and Make and Expand trace at once with the Default preset, #543; with an image selected the Control bar and the Properties panel show Image Trace, whose arrow traces with any preset, Mask (`object.maskImage`: a clipping path on the image's outline, selected so its handles crop), Crop Image (a crop box on the image, starting on its part over the artboard, dragged by its handles or inside it, the outside dimmed, with X/Y/W/H, Apply and Cancel in the Control bar, Enter and Escape, #734; `object.cropImage {rect}` for agents, `{trim: true}` cuts an image to its pixels that aren't fully transparent, pixel for pixel) and Embed or Unembed in place of Fill and Stroke; with an Image Trace object selected, its Preset (choosing another traces again), View, the Image Trace panel and Expand, plus Release in Properties; the five View modes (Tracing Result, with Outlines, Outlines, Outlines with Source Image, Source Image) redraw a trace on screen without tracing again, are saved with it and `imageTrace.setView` sets them, while exports and Expand keep the result; the panel's Advanced section is a header that stays open or closed as it was left (part of #641); Color mode's Palette: Limited, Full Tone (as many colours as the tones need, Less … More), Automatic (flat art with its own colours, else Full Tone; a heuristic) and Document Library (the most used colours of the document's swatches or a swatch library, filled with the swatch colours as they are), part of #641; Advanced › Create: Fills and/or Strokes, where lines up to the Stroke width trace as stroked centre lines (distance transform, thinning, a skeleton graph with spurs pruned, curve fitting; one width per line; without Fills, wider areas become stroked outlines), part of #641), pattern swatches with pattern editing mode, live Repeat (radial/grid/mirror).
 - **Paint and appearance (M3):**
-  - **Swatches:** names follow the colour model and are unique; Swatch Options (process/spot, Global, Gray/RGB/HSB/CMYK/Web, live preview); editing a global or spot swatch recolours every linked fill, stroke and text run in one undo step; multi-select and delete with confirmation; New Swatch and New Color Group dialogs (a group from the selected artwork's colours); swatches in colour groups convert, separate and count like any other. The Swatches panel selects ranges and whole groups, has a find field, and drags swatches to reorder, regroup or paint art; Add Used Colors, Select All Unused, Merge, Ungroup and Sort by Kind; a CMYK document keeps applied colours in CMYK. Swatch libraries: nine generated colour libraries and five gradient libraries in a library panel, saved as `.vcswatches`, `.gpl`, swatch exchange (`.ase`) or CSS, and loaded from `.vcswatches`, `.gpl` and `.ase` files (`.ase` both ways: RGB, CMYK, Lab and Gray; global, spot and process; groups); `swatch.library.copyToUser` copies a loaded library into the User Defined folder without replacing a file, and a file with the same extension and bytes as a User Defined library opens as that library. Tints of global and spot colours ("Name 40%") stay linked and separate as a percentage of their plate. Spot colours can be defined in Lab (Spot Colors options). A built-in [Registration] swatch prints on every plate.
+  - **Swatches:** names follow the colour model and are unique; Swatch Options (process/spot, Global, Gray/RGB/HSB/CMYK/Web, live preview); editing a global or spot swatch recolours every linked fill, stroke and text run in one undo step; multi-select and delete with confirmation; New Swatch and New Color Group dialogs (a group from the selected artwork's colours); swatches in colour groups convert, separate and count like any other. The Swatches panel selects ranges and whole groups, has a find field, and drags swatches to reorder, regroup or paint art; Add Used Colors, Select All Unused, Merge, Ungroup and Sort by Kind; a CMYK document keeps applied colours in CMYK. Swatch libraries: nine generated colour libraries and five gradient libraries in a library panel, saved as `.vcswatches`, `.gpl`, swatch exchange (`.ase`) or CSS, and loaded from `.vcswatches`, `.gpl` and `.ase` files (`.ase` both ways: RGB, CMYK, Lab and Gray; global, spot and process; groups) and from color books (`.acb`, read only: the RGB, CMYK or Lab colors of a book such as a Pantone book a user owns, named with its prefix and suffix, spot unless it says process, #831); `swatch.library.copyToUser` copies a loaded library into the User Defined folder without replacing a file, and a file with the same extension and bytes as a User Defined library opens as that library. Tints of global and spot colours ("Name 40%") stay linked and separate as a percentage of their plate. Spot colours can be defined in Lab (Spot Colors options). A built-in [Registration] swatch prints on every plate.
   - **Colour:** a Color Picker (colour field, H/S/B/R/G/B channel slider, HSB/RGB/Lab/CMYK fields, hex, web-only snapping, out-of-gamut correction); the Color panel follows each colour's own model and Alt-click paints the other proxy; proxies look through groups and show "?" for mixed paint; Invert, Complement, Apply Last Color (`,`) and Apply Last Gradient (`.`) keep the colour model; every paint command feeds the recent colours. The Color Guide has 21 harmony rules, Steps and Variation options and Limit to Library. Adjust Color Balance (its Global mode shifts tints) and Saturate preview live; Edit Colors and Recolor also reach meshes, images and patterns. Recolor Artwork has colour reduction, five recolour methods, presets, Limit to Library, a colour-wheel Edit tab and Edit Color Group; a local Color Themes panel saves five-colour themes. Fill/Stroke chips open swatch and mixer popovers (the Properties panel has the Control bar's Fill and Stroke chips, Stroke link and weight spinner, with nothing selected too), panels have Illustrator's Window menu keys (Align Shift+F7, Transform Shift+F8, Pathfinder Cmd+Shift+F9, Layers F7, Character Cmd+T…; every panel can be given one in Edit › Keyboard Shortcuts), and Eyedropper Options pick up and apply chosen attributes (Alt and Shift+Alt, image pixels). An ICC CMYK profile converts straight into the RGB working space (not through sRGB, so a wider space such as Wide Gamut RGB keeps colours sRGB can't hold) with the colour settings' black-point compensation, on the canvas and in RGB exports alike. Fills and strokes can overprint (Attributes panel, Overprint Black options), and CMYK documents blend in inks on screen, in PDF and when flattening. Document Color Mode converts the art, symbols, pattern tiles and swatches through the colour settings: Gray stays Gray, RGB greys separate into four-colour greys and a rich black as Illustrator does, or go on the black plate only with `grays: "black"` (also for `document.open {colorMode}`).
   - **Gradients:** lossless, validated gradient params; gradients follow rotate, reflect, shear, non-uniform scale and distortions; the Gradient tool edits the fill or stroke of the active proxy, type included; an interactive on-canvas annotator (move, length/angle, rotate, add/move/delete/duplicate stops, midpoints, a stop popover, Delete and arrow keys). The Gradient panel has the Fill/Stroke proxy, a gradient-swatch dropdown with Save to Swatches, midpoint locations, Alt-drag to copy or swap stops, swatch drops on the ramp and a stop eyedropper; copied appearances and graphic styles place gradients on each target's own bounds; gradient handles snap and honour Constrain Angle. Gradient stops stay linked to global and spot swatches. Freeform gradients (points and lines) are edited on the canvas; radial gradients have an extent ellipse, an aspect handle and an off-centre focal point (SVG `fx`/`fy`, PDF two-point radials). A stroke's gradient runs within, along or across it. Object ▸ Expand turns gradients into N objects or a gradient mesh.
   - **Strokes:** one stroke-geometry module shared by the canvas, SVG, PDF and Outline Stroke; dotted lines (zero-length dashes draw dots or squares); arrowheads with hollow outlines, tip-on-end or extend-past-end alignment and one opacity for line and head. SVG and PDF export arrowheads, width profiles, brushes and aligned strokes exactly as the canvas draws them; Outline Stroke and the live Outline Stroke effect outline every stroke item as drawn (dashes, heads, profiles, alignment); dashes can be fitted to corners and path ends; width profiles carry through dashes, and their corners take the join. The Stroke panel edits type's character strokes, follows the stroke units (its weight presets are round values in that unit: `0.25 mm`, `0.0625 in`, `1 px`, #426; fields show four decimals in mm, cm and inches, three in points), shows mixed values blank and opens from the Control bar. A width profile library, thirty more arrowheads, and Width Point Edit with multi-select and discontinuous points. Visual bounds and clicks cover the whole painted stroke. Scale Strokes & Effects, Scale Corners and Use Preview Bounds work everywhere, and new art inherits stroke options, a graphic style or the whole last appearance.

apps/vectorcraft-cli/src/main.rs

@@ -269,17 +269,23 @@ fn run(args: &[String]) -> Result<(), String> {
     } else if !matches!(steps.first(), Some(Step::Cmd(id, _)) if id == "file.new") {
         h.ensure_document();
     }
+    // Each step's result, for later steps to refer to (`"$1.id"`, see `vectorcraft_engine::steps`).
+    let mut results = vec![];
     for step in steps {
-        match step {
+        let r = match step {
             Step::Cmd(id, params) => {
+                let params = vectorcraft_engine::steps::resolve(&params, &results).map_err(|e| format!("{id}: {e}"))?;
                 let r = h.call("engine.execute", json!({"command": id, "params": params})).map_err(|e| format!("{id}: {e}"))?;
                 emit(json!({"step": "cmd", "command": id, "result": r}))?;
+                r
             }
             Step::Export(path) => {
                 let r = h.call("app.export", json!({"path": path, "scale": scale})).map_err(|e| format!("export {path}: {e}"))?;
                 emit(json!({"step": "export", "result": r}))?;
+                r
             }
-        }
+        };
+        results.push(r);
     }
     Ok(())
 }

apps/vectorcraft/src/gpu.rs

@@ -31,7 +31,7 @@ use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, OnceLock};
 
 use eframe::egui_wgpu::NativeAdapterSelectorMethod;
-use eframe::wgpu::{self, Backend, DeviceType, PowerPreference};
+use eframe::wgpu::{self, Backend, Backends, DeviceType, PowerPreference};
 
 /// The adapters a restart leaves out, those the window failed on, as comma-separated [`key`]s
 /// (`Vulkan:1002:164e`, `Metal:Intel Iris Pro Graphics`). Set by the app itself when it starts
@@ -81,6 +81,15 @@ pub fn preferred_displays(pref: Option<&str>, env: Option<PowerPreference>) -> V
     if automatic(pref, env) { display_gpus() } else { Vec::new() }
 }
 
+/// The graphics backends the window starts with: on Windows Direct3D 12, falling back to OpenGL,
+/// unless `WGPU_BACKEND` names others (`env_set`; `default` then holds them). Creating a Vulkan
+/// instance loads every installed Vulkan driver into the process, and a faulty one (Intel's
+/// `igvk64.dll`, #806) crashed the app before its window appeared. DX12 is Windows' own backend,
+/// as in PdfCraft. Elsewhere, `default`.
+pub fn backends(default: Backends, env_set: bool) -> Backends {
+    if cfg!(windows) && !env_set { Backends::DX12 | Backends::GL } else { default }
+}
+
 /// One adapter, as [`adapter_order`] sees it.
 #[derive(Clone, Debug)]
 pub struct Candidate {
@@ -809,6 +818,18 @@ mod tests {
         assert_eq!(adapter_order(&c, PowerPreference::LowPower, &[], None, &[c[1].key.clone()]), [0, 3, 2], "DX12 failed: Vulkan next");
     }
 
+    #[test]
+    fn windows_never_loads_vulkan_drivers_unless_asked() {
+        let all = Backends::all();
+        let start = backends(all, false);
+        if cfg!(windows) {
+            assert_eq!(start, Backends::DX12 | Backends::GL, "#806");
+        } else {
+            assert_eq!(start, all);
+        }
+        assert_eq!(backends(Backends::VULKAN, true), Backends::VULKAN, "WGPU_BACKEND=vulkan still picks it");
+    }
+
     #[test]
     fn power_preference_follows_the_environment_then_the_preference() {
         assert_eq!(power_preference(None, None), AUTOMATIC);

apps/vectorcraft/src/main.rs

@@ -118,12 +118,11 @@ fn end_before_teardown(frames: u64) {
 }
 
 /// Open files handed to the app (command line, macOS Finder and Dock) as documents. A file that
-/// can't be opened is reported in the status bar and on stderr; the others still open.
+/// can't be opened is reported to the user and on stderr; the others still open.
 fn open_files(app: &mut VectorcraftApp, files: Vec<String>) {
     for f in files {
-        if let Err(e) = vectorcraft_ui_egui::io::open_path(app, &f) {
+        if let Err(e) = vectorcraft_ui_egui::io::open_reporting(app, &f) {
             eprintln!("vectorcraft: {f}: {e}");
-            app.status(format!("Couldn't open {}: {e}", fileio::file_name(&f)));
         }
     }
 }
@@ -467,6 +466,7 @@ fn main() -> std::process::ExitCode {
             // Metal on an Iris Pro, #651). `WGPU_VALIDATION_INDIRECT_CALL=1` turns it back on.
             create.instance_descriptor.flags =
                 (eframe::wgpu::InstanceFlags::from_build_config() - eframe::wgpu::InstanceFlags::VALIDATION_INDIRECT_CALL).with_env();
+            create.instance_descriptor.backends = gpu::backends(create.instance_descriptor.backends, std::env::var_os("WGPU_BACKEND").is_some());
         }
         options
     };

crates/color/src/palette_io.rs

@@ -1,7 +1,8 @@
 //! Swatch library files: the native `.vcswatches` JSON (colour models, global, spot, gradients
 //! and colour groups exactly), `.gpl` palettes (8-bit RGB; colour groups as `# Group:` comment
 //! headers), swatch exchange `.ase` files (binary: solid colors in their own model, global, spot
-//! and process colors, color groups) and CSS custom properties (written only).
+//! and process colors, color groups), color books `.acb` (read only: the books a user owns, such
+//! as a Pantone book) and CSS custom properties (written only).
 
 use std::collections::{HashMap, HashSet};
 
@@ -79,6 +80,8 @@ const ASE_MAX_ENTRIES: usize = 100_000;
 /// The most UTF-16 code units of a name that are kept.
 const ASE_MAX_NAME: usize = 1024;
 const ASE_CUT_SHORT: &str = "the swatch exchange file is cut short";
+const ACB_SIGNATURE: &[u8] = b"8BCB";
+const ACB_CUT_SHORT: &str = "the color book is cut short";
 
 /// Write `lib` in `format` → the file's bytes. Pattern swatches (their tiles live in a document)
 /// and None are left out; `.gpl` keeps solid colours only, as 8-bit RGB, and `.ase` keeps solid
@@ -326,6 +329,9 @@ pub fn read_bytes(bytes: &[u8], name: &str) -> Result<SwatchLibrary, String> {
     if bytes.starts_with(ASE_SIGNATURE) {
         return read_ase(bytes, name);
     }
+    if bytes.starts_with(ACB_SIGNATURE) {
+        return read_acb(bytes, name).map_err(|e| if e == ASE_CUT_SHORT { ACB_CUT_SHORT.into() } else { e });
+    }
     read(&String::from_utf8_lossy(bytes), name)
 }
 
@@ -333,6 +339,7 @@ pub fn read_bytes(bytes: &[u8], name: &str) -> Result<SwatchLibrary, String> {
 /// [`read_bytes`] reads it, with the invalid bytes replaced (its first KiB is enough).
 pub fn sniff_bytes(bytes: &[u8]) -> bool {
     bytes.starts_with(ASE_SIGNATURE)
+        || bytes.starts_with(ACB_SIGNATURE)
         || std::str::from_utf8(bytes).is_ok_and(sniff)
         || sniff(&String::from_utf8_lossy(bytes.get(..1024).unwrap_or(bytes)))
 }
@@ -427,6 +434,67 @@ fn read_ase(bytes: &[u8], fallback: &str) -> Result<SwatchLibrary, String> {
     Ok(lib)
 }
 
+/// `.acb` (a color book, read only), from public descriptions of the format: after the signature
+/// come, big-endian, a `u16` version (1) and book id, the title, prefix, suffix and description
+/// as strings, a `u16` color count, page size and page selector offset, a `u16` color space (0
+/// RGB, 2 CMYK, 7 Lab) and the colors: each a name, a six-character catalog code and its
+/// components as bytes. RGB runs from 0 to 255, CMYK ink is stored inverted (255 is no ink), Lab
+/// lightness is 0 to 255 for 0 to 100 and a and b are offset by 128. A string is a `u32` count of
+/// UTF-16 code units, then the units; a `$$$/key=Text` string means `Text`, and `^R`, `^C` stand
+/// for ® and ©. An optional `spflspot` or `spflproc` at the end says whether the colors are spot
+/// or process colors (a book without it is a spot color book).
+///
+/// The book's colors are named with its prefix and suffix ("PANTONE 185 C"); colors without a
+/// name (the padding of a book's pages) are left out. A version other than 1, a color space other
+/// than those three or more than [`ASE_MAX_ENTRIES`] colors is an error.
+fn read_acb(bytes: &[u8], fallback: &str) -> Result<SwatchLibrary, String> {
+    let mut data = AseData(bytes);
+    data.bytes(ACB_SIGNATURE.len())?;
+    let version = data.u16()?;
+    if version != 1 {
+        return Err(format!("color book version {version} isn't supported (only 1)"));
+    }
+    let _book_id = data.u16()?;
+    let [title, prefix, suffix, _description] = [data.acb_string()?, data.acb_string()?, data.acb_string()?, data.acb_string()?];
+    let count = usize::from(data.u16()?);
+    if count > ASE_MAX_ENTRIES {
+        return Err(format!("the color book holds more than {ASE_MAX_ENTRIES} colors"));
+    }
+    let (_page_size, _page_offset) = (data.u16()?, data.u16()?);
+    let space = data.u16()?;
+    let mut colors = Vec::with_capacity(count);
+    for _ in 0..count {
+        let name = data.acb_string()?;
+        let _code = data.bytes(6)?;
+        let color = match space {
+            0 => {
+                let [r, g, b] = data.array::<3>()?;
+                Color::rgb8(r, g, b)
+            }
+            2 => {
+                let ink = |v: u8| f32::from(255 - v) / 255.0;
+                let [c, m, y, k] = data.array::<4>()?;
+                Color::cmyk(ink(c), ink(m), ink(y), ink(k))
+            }
+            7 => {
+                let [l, a, b] = data.array::<3>()?;
+                Color::lab(f32::from(l) * 100.0 / 255.0, f32::from(a) - 128.0, f32::from(b) - 128.0)
+            }
+            other => return Err(format!("color books in color space {other} aren't supported (only RGB, CMYK and Lab)")),
+        };
+        colors.push((name, color));
+    }
+    // Spot colors unless the book says process ones.
+    let spot = data.0.windows(8).last() != Some(b"spflproc".as_slice());
+    let mut lib = SwatchLibrary { name: if title.is_empty() { fallback.into() } else { title }, ..Default::default() };
+    let mut names = UniqueNames::default();
+    for (name, color) in colors.into_iter().filter(|(n, _)| !n.trim().is_empty()) {
+        let name = names.unique(format!("{prefix}{name}{suffix}").trim().to_string());
+        lib.swatches.push(Swatch { name, paint: Paint::solid(color), global: spot, spot });
+    }
+    Ok(lib)
+}
+
 /// The swatch of an `.ase` color block, `None` for a model other than RGB, CMYK, Lab and Gray.
 /// Components are clamped to their ranges.
 fn ase_swatch(body: &mut AseData) -> Result<Option<Swatch>, String> {
@@ -503,6 +571,20 @@ impl<'a> AseData<'a> {
         let v = f32::from_be_bytes(self.array()?);
         Ok(if v.is_finite() { v } else { 0.0 })
     }
+    /// A color book string ([`read_acb`]): a `u32` count of UTF-16 code units, then the units,
+    /// with `$$$/key=Text` read as `Text` and `^R`, `^C` as ®, ©; at most [`ASE_MAX_NAME`] units
+    /// are kept.
+    fn acb_string(&mut self) -> Result<String, String> {
+        let n = usize::try_from(self.u32()?).unwrap_or(usize::MAX);
+        let (units, _) = self.bytes(n.checked_mul(2).ok_or(ASE_CUT_SHORT)?)?.as_chunks::<2>();
+        let units: Vec<u16> = units.iter().take(ASE_MAX_NAME).map(|u| u16::from_be_bytes(*u)).take_while(|&u| u != 0).collect();
+        let s = String::from_utf16_lossy(&units);
+        let s = match s.strip_prefix("$$$/") {
+            Some(key) => key.split_once('=').map_or("", |(_, text)| text).to_string(),
+            None => s,
+        };
+        Ok(s.replace("^R", "®").replace("^C", "©"))
+    }
     /// A name up to its terminating zero, trimmed. A block that ends before it has no name.
     fn name(&mut self) -> Result<String, String> {
         if self.0.is_empty() {
@@ -553,6 +635,68 @@ mod tests {
     use crate::{Gradient, GradientPaint, GradientStop};
     use proptest::prelude::*;
 
+    /// A color book's string: a `u32` count of UTF-16 code units, then the units.
+    fn acb_str(out: &mut Vec<u8>, s: &str) {
+        let units: Vec<u16> = s.encode_utf16().collect();
+        out.extend((units.len() as u32).to_be_bytes());
+        units.iter().for_each(|u| out.extend(u.to_be_bytes()));
+    }
+
+    /// A color book in `space` (0 RGB, 2 CMYK, 7 Lab) with `colors` (name, components) and an
+    /// optional spot/process marker.
+    fn acb(space: u16, colors: &[(&str, &[u8])], marker: &[u8]) -> Vec<u8> {
+        let mut b = b"8BCB".to_vec();
+        b.extend(1u16.to_be_bytes());
+        b.extend(3000u16.to_be_bytes());
+        for s in ["$$$/colorbook/Test/title=Test Book^R", "TEST ", " C", "a book"] {
+            acb_str(&mut b, s);
+        }
+        b.extend((colors.len() as u16).to_be_bytes());
+        b.extend(7u16.to_be_bytes());
+        b.extend(0u16.to_be_bytes());
+        b.extend(space.to_be_bytes());
+        for (name, comps) in colors {
+            acb_str(&mut b, name);
+            b.extend(b"TST001");
+            b.extend(*comps);
+        }
+        b.extend(marker);
+        b
+    }
+
+    /// #831: color books (`.acb`) are read: their colors in RGB, CMYK or Lab, named with the book's
+    /// prefix and suffix, spot unless the book says process; page padding is left out.
+    #[test]
+    fn color_books_are_read() {
+        let lib = read_bytes(&acb(0, &[("185", &[228, 0, 43]), ("", &[0, 0, 0]), ("Red 032", &[239, 51, 64])], b"spflspot"), "fallback").unwrap();
+        assert_eq!(lib.name, "Test Book®");
+        let names: Vec<&str> = lib.swatches.iter().map(|s| s.name.as_str()).collect();
+        assert_eq!(names, ["TEST 185 C", "TEST Red 032 C"]);
+        assert!(lib.swatches.iter().all(|s| s.spot && s.global));
+        assert_eq!(lib.swatches[0].paint.color(), Some(Color::rgb8(228, 0, 43)));
+        // CMYK ink is stored inverted; a book marked process gives process colors.
+        let lib = read_bytes(&acb(2, &[("Cyan", &[0, 255, 255, 255])], b"spflproc"), "x").unwrap();
+        assert_eq!(lib.swatches[0].paint.color(), Some(Color::cmyk(1.0, 0.0, 0.0, 0.0)));
+        assert!(!lib.swatches[0].spot && !lib.swatches[0].global);
+        // Lab: lightness 0..255 for 0..100, a and b offset by 128; no marker: spot.
+        let lib = read_bytes(&acb(7, &[("Grey", &[255, 128, 128])], b""), "x").unwrap();
+        assert_eq!(lib.swatches[0].paint.color(), Some(Color::lab(100.0, 0.0, 0.0)));
+        assert!(lib.swatches[0].spot);
+        assert!(sniff_bytes(&acb(0, &[], b"")));
+        // Unsupported versions and color spaces, and short files, are errors.
+        let mut v2 = acb(0, &[], b"");
+        v2[5] = 2;
+        assert!(read_bytes(&v2, "x").is_err());
+        assert!(read_bytes(&acb(1, &[("x", &[1, 2, 3])], b""), "x").is_err());
+        let full = acb(0, &[("185", &[228, 0, 43])], b"");
+        for cut in 4..full.len() {
+            assert!(read_bytes(&full[..cut], "x").is_err(), "{cut} bytes");
+        }
+        let mut huge = b"8BCB\0\x01\0\x01".to_vec();
+        huge.extend(u32::MAX.to_be_bytes());
+        assert!(read_bytes(&huge, "x").is_err(), "a string longer than the file");
+    }
+
     fn sample() -> SwatchLibrary {
         let grad = Paint::Gradient(Box::new(GradientPaint::new(Gradient {
             kind: GradientKind::Linear,

crates/doc/src/hit.rs

@@ -86,6 +86,19 @@ pub fn objects_at(doc: &Document, p: Point, opt: HitOptions, scope: Option<NodeI
 
 /// [`hit_test`] passing over the nodes `skip` names (and their contents).
 fn hit_test_skipping(doc: &Document, p: Point, opt: HitOptions, skip: &dyn Fn(NodeId) -> bool) -> Option<Hit> {
+    let finish = |mut h: Hit| {
+        h.contents_of = h.ancestry.iter().rev().copied().find(|a| doc.node(*a).is_some_and(edits_contents));
+        h.layers = h.ancestry.iter().take_while(|a| doc.node(**a).is_some_and(Node::is_layer)).count();
+        h
+    };
+    // Isolation mode: only what is inside the isolated container hits. The art around it is
+    // locked, and clicks pass through it (#833).
+    if let Some(scope) = opt.scope
+        && let Some(container) = doc.node(scope).filter(|n| n.is_container())
+        && let Some(mut chain) = doc.ancestry(scope)
+    {
+        return hit_children(container, p, opt, skip, &mut chain).map(finish);
+    }
     let mut chain = Vec::new();
     for layer in doc.layers.iter().rev() {
         if !layer.visible || layer.locked {
@@ -100,10 +113,8 @@ fn hit_test_skipping(doc: &Document, p: Point, opt: HitOptions, skip: &dyn Fn(No
         }
         chain.push(layer.id);
         let opt = if matches!(layer.kind, NodeKind::Layer { preview: false, .. }) { HitOptions { outline: true, ..opt } } else { opt };
-        if let Some(mut h) = hit_children(layer, p, opt, skip, &mut chain) {
-            h.contents_of = h.ancestry.iter().rev().copied().find(|a| doc.node(*a).is_some_and(edits_contents));
-            h.layers = h.ancestry.iter().take_while(|a| doc.node(**a).is_some_and(Node::is_layer)).count();
-            return Some(h);
+        if let Some(h) = hit_children(layer, p, opt, skip, &mut chain) {
+            return Some(finish(h));
         }
         chain.pop();
     }
@@ -560,7 +571,11 @@ world",
         d.insert(Some(l), 9, far).unwrap();
         let at = |x: f64, scope| objects_at(&d, Point::new(x, 25.0), HitOptions::default(), scope);
         assert_eq!(at(30.0, None), vec![g, a_id]);
-        assert_eq!(at(30.0, Some(g))[..2], [c_id, b_id], "isolated: the group's own objects");
+        assert_eq!(at(30.0, Some(g)), [c_id, b_id], "isolated: the group's own objects");
+        // Isolated, the art around the group is locked: clicks pass through it (#833).
+        assert!(at(5.0, Some(g)).is_empty());
+        assert!(at(130.0, Some(g)).is_empty());
+        assert!(hit_test(&d, Point::new(5.0, 25.0), HitOptions { scope: Some(g), ..HitOptions::default() }).is_none());
         assert_eq!(at(5.0, None), vec![a_id]);
         assert!(at(90.0, None).is_empty());
     }

crates/engine/src/cmd/mod.rs

@@ -366,13 +366,23 @@ pub fn color_value(v: &Value) -> Option<Color> {
 
 /// Objects a command targets: explicit `ids` param or the selection.
 pub(crate) fn targets(s: &Session, p: &Value) -> Result<Vec<NodeId>> {
-    if let Some(ids) = ids_param(p, "ids") {
-        return Ok(ids);
+    // Objects given are used as given: a value that isn't an object id fails rather than the
+    // command acting on the selection instead (#785).
+    let object_id = |v: &Value| v.as_u64().map(NodeId).ok_or_else(|| EngineError::Other(format!("object ids are non-negative integers, not {v}")));
+    match p.get("ids").filter(|v| !v.is_null()) {
+        Some(Value::Array(a)) => return a.iter().map(object_id).collect(),
+        Some(v) => return Err(EngineError::Other(format!("`ids` must be an array of object ids, not {v}"))),
+        None => {}
     }
-    if let Some(id) = id_param(p, "id") {
-        return Ok(vec![id]);
+    match p.get("id").filter(|v| !v.is_null()) {
+        Some(v @ Value::Number(_)) => Ok(vec![object_id(v)?]),
+        // A step reference a batch couldn't resolve (other strings are other ids, such as an
+        // effect's).
+        Some(Value::String(r)) if r.starts_with('$') => {
+            Err(EngineError::Other(format!("`id` is the step reference {r:?}, which only `run` and `command_batch` resolve")))
+        }
+        _ => Ok(s.doc()?.selection.objects.clone()),
     }
-    Ok(s.doc()?.selection.objects.clone())
 }
 
 pub(crate) fn ok() -> Result<Value> {

crates/engine/src/cmd/swatchlib.rs

@@ -72,7 +72,7 @@ pub fn specs() -> Vec<CommandSpec> {
             "Other Library…",
             ["Window", "Swatch Libraries"],
             None,
-            "{path? | data?: file text | dataBase64?, name?: file name (default: the path's)} load a .vcswatches, .gpl or .ase (swatch exchange) library, or the swatches of any document VectorCraft opens (see document.formats), for the library panel (Window → Swatch Libraries lists it until the app quits; a file of the user library folder, or a file with the same extension and bytes as one there, opens as that User Defined library) → {library: id, name, count}",
+            "{path? | data?: file text | dataBase64?, name?: file name (default: the path's)} load a .vcswatches, .gpl, .ase (swatch exchange) or .acb (color book, read only) library, or the swatches of any document VectorCraft opens (see document.formats), for the library panel (Window → Swatch Libraries lists it until the app quits; a file of the user library folder, or a file with the same extension and bytes as one there, opens as that User Defined library) → {library: id, name, count}",
             always,
             load
         ),
@@ -130,7 +130,7 @@ impl LibraryFile for SwatchLibrary {
 }
 
 /// The extensions of library files [`palette_io::read_bytes`] reads.
-pub const LIBRARY_EXTS: &[&str] = &["vcswatches", "gpl", "ase"];
+pub const LIBRARY_EXTS: &[&str] = &["vcswatches", "gpl", "ase", "acb"];
 
 /// A library file the save commands write ([`Libraries::write`]).
 pub(crate) enum FileData {

crates/engine/src/cmd/textedit.rs

@@ -27,7 +27,7 @@ pub fn specs() -> Vec<CommandSpec> {
             "Character",
             [],
             None,
-            "{id, start?: byte, end?: byte (default: all text), font?, style?, size?: pt, leading?: pt|\"auto\", tracking?, kerning?: 1/1000 em|\"auto\", baselineShift?: pt, hScale?: %, vScale?: %, rotation?: deg, fill?: colour|\"none\", stroke?: colour|\"none\", strokeWidth?: pt, strokeOptions?: {weight?, cap?, join?, miterLimit?, dash?, dashOffset?, alignDashes?} (as stroke.set: the character stroke), underline?, strikethrough?, allCaps?: bool, smallCaps?: bool, position?: \"normal\"|\"superscript\"|\"subscript\" (sizes from Document Setup), features?: [\"dlig\", \"-liga\", …], charAlign?: \"romanBaseline\"|\"emBoxTop\"|\"emBoxCenter\"|\"emBoxBottom\"|\"icfTop\"|\"icfBottom\"} style a character range (runs are split at the range ends) → {id, runs}",
+            "{id? (default: the one selected type object), start?: byte, end?: byte (default: all text), font?, style?, size?: pt, leading?: pt|\"auto\", tracking?, kerning?: 1/1000 em|\"auto\", baselineShift?: pt, hScale?: %, vScale?: %, rotation?: deg, fill?: colour|\"none\", stroke?: colour|\"none\", strokeWidth?: pt, strokeOptions?: {weight?, cap?, join?, miterLimit?, dash?, dashOffset?, alignDashes?} (as stroke.set: the character stroke), underline?, strikethrough?, allCaps?: bool, smallCaps?: bool, position?: \"normal\"|\"superscript\"|\"subscript\" (sizes from Document Setup), features?: [\"dlig\", \"-liga\", …], charAlign?: \"romanBaseline\"|\"emBoxTop\"|\"emBoxCenter\"|\"emBoxBottom\"|\"icfTop\"|\"icfBottom\"} style a character range (runs are split at the range ends) → {id, runs}",
             has_doc,
             set_range_style
         ),
@@ -420,7 +420,14 @@ pub(crate) fn protect_missing_glyphs(before: &[TextRun], runs: &mut Vec<TextRun>
 
 fn set_range_style(s: &mut Session, p: &Value) -> Result<Value> {
     const C: &str = "text.setRangeStyle";
-    let id = id_param(p, "id").ok_or_else(|| bad(C, "missing `id`"))?;
+    // The type object given, else the one selected (#785).
+    let id = match p.get("id").filter(|v| !v.is_null()) {
+        Some(v) => v.as_u64().map(NodeId).ok_or_else(|| bad(C, format!("`id` must be an object id, not {v}")))?,
+        None => match super::typecmd::text_targets(s, &json!({}), C)?.as_slice() {
+            [one] => *one,
+            _ => return Err(bad(C, "missing `id`: give one, or select one type object")),
+        },
+    };
     let change = CharChange::parse(p, C, &s.doc()?.doc.setup)?;
     if change.is_empty() {
         return Err(bad(C, "nothing to change"));

crates/engine/src/cmd/webexport.rs

@@ -142,6 +142,17 @@ fn de_key<'de, T: Keyed, D: Deserializer<'de>>(d: D) -> std::result::Result<T, D
     T::parse(&s).ok_or_else(|| D::Error::custom(format!("`{s}`: {}", T::KEYS)))
 }
 
+/// A size in pixels: a number, rounded to whole pixels (`300.0` is 300).
+fn de_pixels<'de, D: Deserializer<'de>>(d: D) -> std::result::Result<Option<u32>, D::Error> {
+    let Some(v) = Option::<f64>::deserialize(d)? else { return Ok(None) };
+    let px = v.round();
+    if !(px.is_finite() && px >= 0.0 && px <= f64::from(u32::MAX)) {
+        return Err(D::Error::custom(format!("{v} is not a size in pixels")));
+    }
+    // In range and whole: the cast is exact.
+    Ok(Some(px as u32))
+}
+
 /// The file format.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
@@ -361,8 +372,10 @@ pub struct WebSettings {
     /// JPEG: embed the sRGB profile.
     pub embed_profile: bool,
     /// The image width in pixels (the height follows).
+    #[serde(deserialize_with = "de_pixels")]
     pub width: Option<u32>,
     /// The image height in pixels (the width follows).
+    #[serde(deserialize_with = "de_pixels")]
     pub height: Option<u32>,
     /// The image size in percent of the art's size in points.
     pub percent: Option<f64>,

crates/engine/src/lib.rs

@@ -9,6 +9,7 @@
 pub mod cmd;
 pub mod guard;
 pub mod inspect;
+pub mod steps;
 mod tooling;
 pub mod units;
 

crates/engine/src/steps.rs

@@ -0,0 +1,138 @@
+//! References between the steps of a batch (`vectorcraft-cli run`, MCP `command_batch`): a
+//! parameter string that is exactly `$N` or `$N.path` takes that value from the result of step `N`
+//! (0-based, in the order the steps ran), and `$last…` from the step before. A path goes into
+//! objects by key and into arrays by index: `$1.id`, `$2.ids.0`, `$last.ids[0]`. `$$` at the start
+//! of a string stands for one `$` and is never a reference (text such as `$$1.99`). A string that
+//! looks like a reference but names no value is an error, so a step never runs with a reference
+//! left in it.
+
+use serde_json::Value;
+
+/// Most nesting [`resolve`] walks into: deeper parameters are left as they are.
+const MAX_DEPTH: usize = 64;
+
+/// `params` with every step reference replaced from `results` (the results of the steps run so
+/// far, in order); an error names a reference that resolves to nothing.
+pub fn resolve(params: &Value, results: &[Value]) -> Result<Value, String> {
+    resolve_at(params, results, 0)
+}
+
+fn resolve_at(v: &Value, results: &[Value], depth: usize) -> Result<Value, String> {
+    if depth > MAX_DEPTH {
+        return Ok(v.clone());
+    }
+    Ok(match v {
+        Value::String(s) => match s.strip_prefix("$$") {
+            Some(rest) => Value::String(format!("${rest}")),
+            None => match parse(s) {
+                Some((step, path)) => lookup(s, step, &path, results)?,
+                None => v.clone(),
+            },
+        },
+        Value::Array(a) => Value::Array(a.iter().map(|x| resolve_at(x, results, depth + 1)).collect::<Result<_, _>>()?),
+        Value::Object(o) => Value::Object(o.iter().map(|(k, x)| Ok((k.clone(), resolve_at(x, results, depth + 1)?))).collect::<Result<_, String>>()?),
+        _ => v.clone(),
+    })
+}
+
+/// Which step a reference names.
+#[derive(Debug, PartialEq)]
+enum Step {
+    Index(usize),
+    Last,
+}
+
+/// A path segment: an object key or an array index (`.0` is either, as the value decides).
+#[derive(Debug, PartialEq)]
+enum Seg {
+    Key(String),
+    Index(usize),
+}
+
+/// `$N…` or `$last…` → the step and the path after it; `None` for any other string.
+fn parse(s: &str) -> Option<(Step, Vec<Seg>)> {
+    let rest = s.strip_prefix('$')?;
+    let digits = rest.bytes().take_while(u8::is_ascii_digit).count();
+    let (step, mut rest) = if digits > 0 {
+        let (n, rest) = rest.split_at_checked(digits)?;
+        (Step::Index(n.parse().ok()?), rest)
+    } else {
+        (Step::Last, rest.strip_prefix("last")?)
+    };
+    let mut path = vec![];
+    while !rest.is_empty() {
+        if let Some(r) = rest.strip_prefix('.') {
+            let len = r.bytes().take_while(|b| b.is_ascii_alphanumeric() || *b == b'_').count();
+            let (key, r) = r.split_at_checked(len)?;
+            if key.is_empty() {
+                return None;
+            }
+            path.push(Seg::Key(key.to_string()));
+            rest = r;
+        } else {
+            let (n, r) = rest.strip_prefix('[')?.split_once(']')?;
+            path.push(Seg::Index(n.parse().ok()?));
+            rest = r;
+        }
+    }
+    Some((step, path))
+}
+
+fn lookup(text: &str, step: Step, path: &[Seg], results: &[Value]) -> Result<Value, String> {
+    let (i, found) = match step {
+        Step::Index(i) => (i, results.get(i)),
+        Step::Last => (results.len().saturating_sub(1), results.last()),
+    };
+    let mut cur = found.ok_or_else(|| format!("`{text}`: there is no step {i} before this one (steps count from 0; write $$ for a literal $)"))?;
+    for seg in path {
+        let next = match (seg, cur) {
+            (Seg::Key(k), Value::Object(o)) => o.get(k),
+            (Seg::Key(k), Value::Array(a)) => k.parse::<usize>().ok().and_then(|n| a.get(n)),
+            (Seg::Index(n), Value::Array(a)) => a.get(*n),
+            _ => None,
+        };
+        cur = next.ok_or_else(|| format!("`{text}`: step {i}'s result has no such value (write $$ for a literal $)"))?;
+    }
+    Ok(cur.clone())
+}
+
+#[cfg(test)]
+mod tests {
+    use serde_json::json;
+
+    use super::*;
+
+    #[test]
+    fn references_take_values_from_earlier_results() {
+        let results = [json!({"index": 0}), json!({"id": 2}), json!({"ids": [5, 6]})];
+        let p = json!({"id": "$1.id", "ids": ["$2.ids.1", "$last.ids[0]"], "nested": {"all": "$2"}, "n": 3, "flag": true});
+        assert_eq!(resolve(&p, &results).unwrap(), json!({"id": 2, "ids": [6, 5], "nested": {"all": {"ids": [5, 6]}}, "n": 3, "flag": true}));
+    }
+
+    #[test]
+    fn plain_strings_and_escapes_are_left_alone() {
+        let results = [json!({"id": 2})];
+        let p = json!({"text": "costs $1", "price": "$$1.99", "name": "a$1.id", "dollar": "$", "word": "$lastname"});
+        assert_eq!(
+            resolve(&p, &results).unwrap(),
+            json!({"text": "costs $1", "price": "$1.99", "name": "a$1.id", "dollar": "$", "word": "$lastname"})
+        );
+    }
+
+    #[test]
+    fn a_reference_to_nothing_is_an_error() {
+        let results = [json!({"id": 2})];
+        for bad in ["$1", "$1.id", "$0.ids", "$0.id.x", "$last.nope", "$7[0]"] {
+            let e = resolve(&json!({"id": bad}), &results).unwrap_err();
+            assert!(e.contains(bad), "{bad}: {e}");
+        }
+        assert!(resolve(&json!({"id": "$last"}), &[]).is_err(), "no step before the first");
+        // Huge indexes and deep nesting don't panic.
+        assert!(resolve(&json!("$99999999999999999999999.id"), &results).is_ok_and(|v| v == json!("$99999999999999999999999.id")));
+        let mut deep = json!("$0.id");
+        for _ in 0..200 {
+            deep = json!([deep]);
+        }
+        assert!(resolve(&deep, &results).is_ok());
+    }
+}

crates/engine/src/tests.rs

@@ -853,3 +853,30 @@ fn new_layers_and_sublayers_are_numbered_together() {
     let sub = s.execute("layer.newSublayer", &json!({})).unwrap();
     assert_eq!(name(&s, &sub), "Layer 4", "the art doesn't count");
 }
+
+/// #785: objects given are used as given (a value that isn't an object id fails, never the
+/// selection instead), and `text.setRangeStyle` works on the selected type object without `id`.
+#[test]
+fn given_targets_are_used_as_given_and_range_style_takes_the_selected_type() {
+    let mut s = session();
+    let first = s.execute("text.create", &json!({"x": 10, "y": 60, "text": "first", "size": 30})).unwrap()["id"].clone();
+    s.execute("text.create", &json!({"x": 10, "y": 140, "text": "second", "size": 30})).unwrap();
+    for bad in [
+        json!({"id": "$1.id", "size": 60}),
+        json!({"id": 2.5, "size": 60}),
+        json!({"ids": [first.clone(), "$1.id"], "size": 60}),
+        json!({"ids": 3, "size": 60}),
+    ] {
+        assert!(s.execute("text.setStyle", &bad).is_err(), "{bad}");
+    }
+    // Another kind of id (an effect's) is still not an object id.
+    let sel = s.doc().unwrap().selection.objects.clone();
+    assert!(s.execute("effect.apply", &json!({"id": "stylize.dropShadow"})).is_ok());
+    assert_eq!(s.doc().unwrap().selection.objects, sel);
+    // The selected type object (the second) is styled when no id is given.
+    let r = s.execute("text.setRangeStyle", &json!({"start": 0, "end": 3, "style": "Bold"})).unwrap();
+    assert_ne!(r["id"], first);
+    s.execute("select.all", &json!({})).unwrap();
+    assert!(s.execute("text.setRangeStyle", &json!({"start": 0, "end": 3, "size": 40})).is_err(), "two type objects: which one?");
+    assert!(s.execute("text.setRangeStyle", &json!({"id": "two", "size": 40})).is_err());
+}

crates/engine/src/tests_webexport.rs

@@ -285,9 +285,16 @@ fn image_size_region_and_metadata() {
     assert_eq!(size(&mut s, json!({"width": 80})), (80, 60));
     assert_eq!(size(&mut s, json!({"height": 15})), (20, 15));
     assert_eq!(size(&mut s, json!({"percent": 150})), (60, 45));
+    // The dialog's fields send decimal numbers: rounded to whole pixels.
+    assert_eq!(size(&mut s, json!({"width": 80.0})), (80, 60));
+    assert_eq!(size(&mut s, json!({"height": 14.6})), (20, 15));
     for bad in [
         json!({"percent": 0}),
         json!({"width": 0}),
+        json!({"width": 0.2}),
+        json!({"width": -5}),
+        json!({"height": 1e300}),
+        json!({"height": "tall"}),
         json!({"format": "bmp"}),
         json!({"colors": "many"}),
         json!({"matte": "plaid"}),

crates/eps/src/import/native.rs

@@ -936,6 +936,14 @@ fn prune_unseen(frame: &Frame<'_>, view: &mut PageView, doc: &mut Document) -> u
         return 0;
     }
     let mut with = view.difference(doc, rect).any;
+    // Taking a text object out changes only what is drawn in its box. When the art would still
+    // differ from the page by more than `compare` allows with every candidate gone, the layers
+    // aren't used whatever is pruned: don't draw them again for each one (#758).
+    let margin = OUTLINE_REACH + 1.0;
+    let boxes: f64 = found.iter().filter_map(|(_, b)| *b).map(|b| b.inflate(margin, margin).intersect(rect).area().max(0.0)).sum();
+    if with - boxes / rect.area().max(1e-9) > MAX_DIFFERENCE {
+        return 0;
+    }
     let mut removed = 0;
     for (id, bounds) in found {
         if bounds.is_none_or(|b| b.intersect(rect).is_zero_area()) {

crates/mcp/src/tests_conventions.rs

@@ -129,3 +129,21 @@ fn conventions_resources_and_versioned_results() {
     rpc(&mut s, "initialize", json!({"protocolVersion":"2025-06-18"}));
     assert!(rpc(&mut s, "tools/list", json!({}))["result"].get("resultType").is_none());
 }
+
+/// #785: a batch step can use an earlier step's result (`"$N.path"`); a reference to nothing
+/// fails that step.
+#[test]
+fn batch_steps_refer_to_earlier_results() {
+    let mut s = Server::new(Box::new(Headless::with_document()));
+    let steps = json!([
+        {"id":"text.create","params":{"x":10,"y":60,"text":"plain and bold words","size":30}},
+        {"id":"shape.rectangle","params":{"x":0,"y":0,"width":20,"height":20}},
+        {"id":"text.setRangeStyle","params":{"id":"$0.id","start":10,"end":14,"style":"Bold"}},
+        {"id":"text.setRangeStyle","params":{"id":"$9.id","start":0,"end":1,"style":"Bold"}}
+    ]);
+    let r = call(&mut s, "command_batch", json!({"steps":steps,"stop_on_error":false}));
+    let p = payload(&r);
+    assert_eq!((p["completed"].clone(), p["failed"].clone()), (json!(3), json!(1)), "{p}");
+    assert_eq!(p["results"][2]["result"]["id"], p["results"][0]["result"]["id"], "the text, not the selected rectangle");
+    assert!(p["results"][3]["error"].as_str().unwrap().contains("$9.id"), "{p}");
+}

crates/mcp/src/tools.rs

@@ -96,7 +96,7 @@ pub fn tool_definitions() -> Vec<Value> {
         tool(
             "command_batch",
             "Run several commands",
-            "Run steps in order; each edit is its own undo step. Returns completed, failed and results. Stops on the first error by default.",
+            "Run steps in order; each edit is its own undo step. A param string that is exactly \"$N.path\" (N: 0-based step index) or \"$last.path\" takes that value from an earlier step's result, e.g. {\"id\":\"$1.id\"}; \"$$\" starts a literal \"$\". Returns completed, failed and results. Stops on the first error by default.",
             obj(
                 json!({"steps": {"type":"array", "items":obj(json!({"id":string("Command id"),"params":{"type":"object"}}), &["id"])}, "stop_on_error":{"type":"boolean", "default":true}}),
                 &["steps"],
@@ -899,6 +899,8 @@ fn command_batch(b: &mut dyn Backend, a: &Args) -> Result<ToolResult, String> {
         Some(v) => v.as_bool().ok_or("`stop_on_error` must be a boolean")?,
     };
     let (mut completed, mut failed, mut results) = (0, 0, Vec::new());
+    // Each step's result (null for a failed one), for later steps' `"$N.path"` references.
+    let mut values: Vec<Value> = vec![];
     for step in steps {
         let result = vectorcraft_engine::guard::catch_panic(|| {
             let args = step.as_object().ok_or("each step must be an object")?;
@@ -908,7 +910,7 @@ fn command_batch(b: &mut dyn Backend, a: &Args) -> Result<ToolResult, String> {
             let id = req_str(args, "id")?;
             let params = match args.get("params") {
                 None | Some(Value::Null) => json!({}),
-                Some(v @ Value::Object(_)) => v.clone(),
+                Some(v @ Value::Object(_)) => vectorcraft_engine::steps::resolve(v, &values)?,
                 Some(_) => return Err("`params` must be an object".into()),
             };
             b.call("engine.execute", json!({"command":id,"params":params}))
@@ -917,10 +919,12 @@ fn command_batch(b: &mut dyn Backend, a: &Args) -> Result<ToolResult, String> {
         match result {
             Ok(v) => {
                 completed += 1;
+                values.push(v.clone());
                 results.push(json!({"ok":true,"result":v}));
             }
             Err(e) => {
                 failed += 1;
+                values.push(Value::Null);
                 results.push(json!({"ok":false,"error":e}));
                 if stop {
                     break;

crates/render/src/lib.rs

@@ -107,8 +107,14 @@ pub struct RenderOptions {
     /// Images are sampled smoothly when scaled or rotated; off, each pixel takes its nearest image
     /// pixel (Pixel Preview with File Handling › Display Bitmaps as Anti-aliased Images off).
     pub smooth_images: bool,
+    /// Screen view in isolation mode: the isolated group or layer. Everything around it draws
+    /// dimmed ([`ISOLATION_DIM`]).
+    pub isolated: Option<NodeId>,
 }
 
+/// The opacity of the art around an isolated group or layer.
+pub const ISOLATION_DIM: f32 = 0.5;
+
 /// How edges are rasterized (raster export option).
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub enum AntiAlias {
@@ -174,6 +180,7 @@ impl Default for RenderOptions {
             progressive_placed: false,
             trace_views: false,
             smooth_images: true,
+            isolated: None,
         }
     }
 }
@@ -355,6 +362,11 @@ pub struct Renderer {
     /// Inline graphics being drawn inside inline graphics (a symbol whose art holds text showing
     /// it): drawing stops at [`MAX_INLINE_DEPTH`].
     inline_depth: u32,
+    /// [`RenderOptions::isolated`]'s layers and groups, from the top layer down to it, for the
+    /// frame (`stamp`) and document they were found in.
+    isolation: Option<(u64, usize, NodeId, Vec<NodeId>)>,
+    /// Drawing inside the isolated container or a dimmed object: nothing further dims.
+    isolation_settled: bool,
 }
 
 /// How deep inline graphics nest (text in a symbol shown inline in text…) before they draw nothing.
@@ -441,6 +453,8 @@ impl Renderer {
             adjusted: Default::default(),
             dim_images: None,
             inline_depth: 0,
+            isolation: None,
+            isolation_settled: false,
         }
     }
 
@@ -876,6 +890,46 @@ impl Renderer {
 
     /// [`Self::draw_node`] after culling and Layer Options.
     fn draw_layer_node(&mut self, ctx: &mut RenderContext, f: &Frame, n: &Node) {
+        // Isolation mode: the art around the isolated container draws dimmed (#833).
+        if let Some((isolated, path)) = self.isolation_path(f) {
+            // A container on the way down to it draws as usual: its members decide.
+            if path.contains(&n.id) && n.id != isolated {
+                return self.draw_layer_node_now(ctx, f, n);
+            }
+            self.isolation_settled = true;
+            if n.id == isolated {
+                self.draw_layer_node_now(ctx, f, n);
+            } else {
+                self.dimmed(ctx, f, &mut |r, c, fr| r.draw_layer_node_now(c, fr, n));
+            }
+            self.isolation_settled = false;
+            return;
+        }
+        self.draw_layer_node_now(ctx, f, n);
+    }
+
+    /// In isolation mode, while drawing outside the isolated container and the art dimmed around
+    /// it: the isolated container and its layers and groups, from the top layer down to it.
+    fn isolation_path(&mut self, f: &Frame) -> Option<(NodeId, Vec<NodeId>)> {
+        let isolated = f.opts.isolated.filter(|_| !self.isolation_settled)?;
+        let doc = std::ptr::from_ref(f.doc) as usize;
+        if !self.isolation.as_ref().is_some_and(|(stamp, d, id, _)| (*stamp, *d, *id) == (self.stamp, doc, isolated)) {
+            self.isolation = Some((self.stamp, doc, isolated, f.doc.ancestry(isolated).unwrap_or_default()));
+        }
+        let path = self.isolation.as_ref().map(|(.., path)| path.clone()).filter(|p| !p.is_empty())?;
+        Some((isolated, path))
+    }
+
+    /// `draw` at [`ISOLATION_DIM`], with nothing inside dimmed again.
+    fn dimmed(&mut self, ctx: &mut RenderContext, f: &Frame, draw: &mut group::Content) {
+        let settled = std::mem::replace(&mut self.isolation_settled, true);
+        let comp = Composite { opacity: ISOLATION_DIM, ..Default::default() };
+        self.group(ctx, f, comp, draw);
+        self.isolation_settled = settled;
+    }
+
+    /// [`Self::draw_layer_node`] past isolation mode's dimming.
+    fn draw_layer_node_now(&mut self, ctx: &mut RenderContext, f: &Frame, n: &Node) {
         if fx::has_object_fx(n) {
             return self.draw_object_fx(ctx, f, &Arc::new(n.clone()), false);
         }
@@ -998,6 +1052,22 @@ impl Renderer {
     fn draw_children(&mut self, ctx: &mut RenderContext, f: &Frame, children: &[Arc<Node>], knockout: bool) {
         if knockout {
             self.draw_knockout(ctx, f, children);
+        } else if let Some((_, path)) = self.isolation_path(f) {
+            // Isolation mode, in a container on the way down to the isolated one: each run of
+            // members around it draws dimmed as one (#833).
+            let mut rest = children;
+            while let Some(i) = rest.iter().position(|c| path.contains(&c.id)) {
+                let (around, from) = rest.split_at(i);
+                if !around.is_empty() {
+                    self.dimmed(ctx, f, &mut |r, c, fr| around.iter().for_each(|n| r.draw_arc(c, fr, n)));
+                }
+                let Some((on_path, after)) = from.split_first() else { break };
+                self.draw_arc(ctx, f, on_path);
+                rest = after;
+            }
+            if !rest.is_empty() {
+                self.dimmed(ctx, f, &mut |r, c, fr| rest.iter().for_each(|n| r.draw_arc(c, fr, n)));
+            }
         } else {
             for c in children {
                 self.draw_arc(ctx, f, c);

crates/render/src/tests_isolation.rs

@@ -218,3 +218,30 @@ fn copying_the_backdrop_changes_nothing_without_blending() {
     let worst = a.iter().zip(&b).map(|(x, y)| (*x as i32 - *y as i32).abs()).max().unwrap();
     assert!(worst <= 1, "differs by {worst}/255");
 }
+
+/// Isolation mode (#833): the art around the isolated group draws at half opacity, above it as
+/// well as below; the group's own art as usual.
+#[test]
+fn isolation_mode_dims_the_art_around_the_isolated_group() {
+    let mut d = Document::new(100.0, 100.0);
+    let l = d.layers[0].id;
+    let below = rect(&mut d, Rect::new(0.0, 0.0, 40.0, 40.0), [0.0, 0.0, 0.0]);
+    let inside = rect(&mut d, Rect::new(60.0, 60.0, 100.0, 100.0), [0.0, 0.0, 0.0]);
+    let above = rect(&mut d, Rect::new(60.0, 0.0, 100.0, 40.0), [0.0, 0.0, 0.0]);
+    let g = group(&mut d, vec![inside], 1.0, Blend::Normal, false);
+    let gid = g.id;
+    for n in [below, g, above] {
+        d.insert(Some(l), usize::MAX, n).unwrap();
+    }
+    let alpha = |img: &Rendered, x: usize, y: usize| img.pixels[(y * 100 + x) * 4 + 3];
+    let plain = render(&d);
+    let isolated = |id| render_with(&mut Renderer::new(), &d, &RenderOptions { isolated: Some(id), ..Default::default() });
+    let dimmed = isolated(gid);
+    assert_eq!(alpha(&dimmed, 80, 80), 255, "the isolated group's art");
+    for (x, y) in [(20, 20), (80, 20)] {
+        assert_eq!(alpha(&plain, x, y), 255);
+        assert!((120..=135).contains(&alpha(&dimmed, x, y)), "({x}, {y}): {}", alpha(&dimmed, x, y));
+    }
+    // An object that isn't in the document dims nothing.
+    assert_eq!(isolated(NodeId(u64::MAX)).pixels, plain.pixels);
+}

crates/tools/src/xform/artboard.rs

@@ -346,7 +346,10 @@ impl Tool for ArtboardTool {
         for h in Handle::ALL {
             o.push(Overlay::Anchor { p: h.pos(r), color: BLUE, filled: false, size: 7.0 });
         }
-        o.push(Overlay::Label { p: Point::new(r.x0, r.y0 - cx.tol(14.0)), text: format!("{:02} - {}", self.active + 1, ab.name), color: BLUE });
+        // Where the canvas names the other artboards: on the top edge, flush with the left one
+        // (labels are drawn 8 px right of and 14 px above their point).
+        let at = Point::new(r.x0 - cx.tol(8.0), r.y0 - cx.tol(4.0));
+        o.push(Overlay::Label { p: at, text: format!("{:02} - {}", self.active + 1, ab.name), color: BLUE });
         if let (Some(Drag::Resize { began: true, .. }), true) = (self.drag, cx.measurement_labels) {
             o.push(Overlay::Measure {
                 p: Point::new(r.x1, r.y1) + Vec2::new(cx.tol(12.0), cx.tol(12.0)),

crates/ui-egui/src/canvas.rs

@@ -249,6 +249,7 @@ pub fn show(app: &mut VectorcraftApp, ui: &mut Ui) {
         placed: vectorcraft_render::placed_document::generation(),
         pixel,
         smooth_images,
+        isolated: st.isolation.map(|id| id.0),
     };
     // Placed documents' bitmaps are being made: draw again when they are ready.
     if vectorcraft_render::placed_document::busy() {
@@ -298,6 +299,8 @@ pub fn show(app: &mut VectorcraftApp, ui: &mut Ui) {
             progressive_placed: true,
             trace_views: true,
             smooth_images,
+            // Isolation mode: the art around the isolated group or layer is dimmed (#833).
+            isolated: key.isolated.map(vectorcraft_doc::NodeId),
             ..opts
         };
         // Light documents render synchronously (no lag vs overlays); heavy ones go to the worker.
@@ -349,8 +352,11 @@ pub fn show(app: &mut VectorcraftApp, ui: &mut Ui) {
     if app.ui.view.pixel_preview && v.zoom >= PIXEL_GRID_ZOOM && app.session.prefs.show_pixel_grid {
         grid(&painter, &xf, 1.0, 1, LineLook { color: PIXEL_GRID, dots: false });
     }
-    // Artboard edges and names.
+    // Artboard edges and names. The Artboard tool labels its active artboard itself (following
+    // a move or resize): that one isn't named twice.
     let active_ab = 0;
+    let artboard_tool = app.session.tool_id() == "artboard";
+    let tool_labelled = artboard_tool.then(|| app.session.tool_options()["active"].as_u64()).flatten();
     for (i, ab) in doc.artboards.iter().enumerate() {
         let r = xf.rect_to_screen(ab.rect);
         let c = if i == active_ab { Color32::from_gray(0) } else { Color32::from_gray(120) };
@@ -359,7 +365,7 @@ pub fn show(app: &mut VectorcraftApp, ui: &mut Ui) {
         if doc.setup.has_bleed() {
             painter.add(Shape::closed_line(xf.quad(doc.setup.bleed_rect(ab.rect)), Stroke::new(1.0, t.bleed)));
         }
-        if app.session.tool_id() == "artboard" || doc.artboards.len() > 1 {
+        if (artboard_tool || doc.artboards.len() > 1) && tool_labelled != u64::try_from(i).ok() {
             painter.text(
                 r.left_top() - vec2(0.0, 4.0),
                 egui::Align2::LEFT_BOTTOM,
@@ -1078,47 +1084,46 @@ fn rulers(ui: &Ui, full: egui::Rect, xf: &Xf, hover: Option<Point>, unit: Unit,
     let step = unit.ruler_step(xf.zoom);
     let minor = step / 10.0;
     let font = egui::FontId::proportional(9.5);
-    let a = xf.to_doc(top.left_top());
-    let b = xf.to_doc(top.right_top());
-    let clip_top = p.with_clip_rect(top);
-    let mut x = (a.x / per / minor).floor() * minor;
-    while x * per <= b.x {
-        let sx = xf.to_screen(Point::new(x * per, 0.0)).x;
-        let is_major = ((x / step).round() * step - x).abs() < minor * 0.01;
-        let is_mid = ((x / (step / 2.0)).round() * (step / 2.0) - x).abs() < minor * 0.01;
-        let len = if is_major {
+    let near = |v: f64, every: f64| ((v / every).round() * every - v).abs() < minor * 0.01;
+    // A tick's length: the labelled ones longest, the halves between them shorter.
+    let tick = |v: f64| {
+        if near(v, step) {
             RULER
-        } else if is_mid {
+        } else if near(v, step / 2.0) {
             7.0
         } else {
             4.0
-        };
-        clip_top.line_segment([pos2(sx, top.bottom() - len), pos2(sx, top.bottom())], Stroke::new(1.0, t.ruler_tick));
-        if is_major {
+        }
+    };
+    // Each ruler measures along its own edge, in the canvas's coordinates turned with the view
+    // (#826): at 0° the top one reads x and the left one y. `draw` gets each tick's distance
+    // (screen points) from `from` along the ruler, and its value in `unit`.
+    let ticks = |from: Pos2, to: Pos2, axis: vectorcraft_geom::Vec2, draw: &mut dyn FnMut(f32, f64)| {
+        let along = |s: Pos2| xf.to_doc(s).to_vec2().dot(axis);
+        let (a, b) = (along(from), along(to));
+        let mut v = (a / per / minor).floor() * minor;
+        while v * per <= b {
+            draw(((v * per - a) * xf.zoom) as f32, v);
+            v += minor;
+        }
+    };
+    // The canvas's directions along the screen's x and y.
+    let (sn, cs) = xf.rot.sin_cos();
+    let clip_top = p.with_clip_rect(top);
+    ticks(top.left_top(), top.right_top(), vectorcraft_geom::Vec2::new(cs, -sn), &mut |d, x| {
+        let sx = top.left() + d;
+        clip_top.line_segment([pos2(sx, top.bottom() - tick(x)), pos2(sx, top.bottom())], Stroke::new(1.0, t.ruler_tick));
+        if near(x, step) {
             clip_top.text(pos2(sx + 2.0, top.top() + 1.0), egui::Align2::LEFT_TOP, ruler_label(x, step), font.clone(), t.ruler_tick);
         }
-        x += minor;
-    }
-    let a = xf.to_doc(left.left_top());
-    let b = xf.to_doc(left.left_bottom());
+    });
     let clip_left = p.with_clip_rect(left);
-    let mut y = (a.y / per / minor).floor() * minor;
-    while y * per <= b.y {
-        let sy = xf.to_screen(Point::new(0.0, y * per)).y;
-        let is_major = ((y / step).round() * step - y).abs() < minor * 0.01;
-        let is_mid = ((y / (step / 2.0)).round() * (step / 2.0) - y).abs() < minor * 0.01;
-        let len = if is_major {
-            RULER
-        } else if is_mid {
-            7.0
-        } else {
-            4.0
-        };
-        clip_left.line_segment([pos2(left.right() - len, sy), pos2(left.right(), sy)], Stroke::new(1.0, t.ruler_tick));
-        if is_major {
+    ticks(left.left_top(), left.left_bottom(), vectorcraft_geom::Vec2::new(sn, cs), &mut |d, y| {
+        let sy = left.top() + d;
+        clip_left.line_segment([pos2(left.right() - tick(y), sy), pos2(left.right(), sy)], Stroke::new(1.0, t.ruler_tick));
+        if near(y, step) {
             // Vertical labels read top-to-bottom, one digit per line like Illustrator.
-            let s = ruler_label(y, step);
-            for (k, ch) in s.chars().enumerate() {
+            for (k, ch) in ruler_label(y, step).chars().enumerate() {
                 clip_left.text(
                     pos2(left.left() + 4.0, sy + 2.0 + k as f32 * 8.5),
                     egui::Align2::LEFT_TOP,
@@ -1128,8 +1133,7 @@ fn rulers(ui: &Ui, full: egui::Rect, xf: &Xf, hover: Option<Point>, unit: Unit,
                 );
             }
         }
-        y += minor;
-    }
+    });
     if let Some(h) = hover {
         let s = xf.to_screen(h);
         clip_top.line_segment([pos2(s.x, top.top()), pos2(s.x, top.bottom())], Stroke::new(1.0, t.text));
@@ -1846,10 +1850,9 @@ fn recent(app: &mut VectorcraftApp, ui: &mut Ui) {
             crate::icons::icon(ui, "history", 16.0, t.icon);
             let r = ui.add(egui::Button::new(egui::RichText::new(&name).color(t.accent).size(13.0)).frame(false)).on_hover_text(&path);
             ui.add(egui::Label::new(egui::RichText::new(&folder).size(12.0).color(t.text_dim)).truncate());
-            if r.clicked()
-                && let Err(e) = crate::io::open_path(app, &path)
-            {
-                app.status(e);
+            if r.clicked() {
+                // A failure is reported to the user there.
+                let _ = crate::io::open_reporting(app, &path);
             }
         });
     }
@@ -2050,6 +2053,47 @@ mod tests {
     use vectorcraft_engine::Session;
     use vectorcraft_geom::Shape as _;
 
+    /// #826: in a turned view each ruler still has ticks along its whole length; at 0° the top one
+    /// reads x where the canvas has it.
+    #[test]
+    fn rulers_cover_their_length_at_any_rotation() {
+        let ctx = egui::Context::default();
+        crate::theme::install_fonts(&ctx);
+        let full = egui::Rect::from_min_size(pos2(0.0, 0.0), vec2(800.0, 600.0));
+        let [top, left, _] = ruler_rects(full);
+        for deg in [0.0_f64, 30.0, 90.0, 135.0, 200.0] {
+            let xf = Xf { rect: full, zoom: 1.0, center: Point::new(300.0, 200.0), rot: deg.to_radians() };
+            let mut out = ctx.run_ui(Default::default(), |ui| rulers(ui, full, &xf, None, Unit::Points, &Tokens::get(ui.ctx())));
+            out.textures_delta.clear();
+            // The ticks' positions along each ruler.
+            let along = |ruler: egui::Rect, x: bool| -> Vec<f32> {
+                let mut at: Vec<f32> = out
+                    .shapes
+                    .iter()
+                    .filter(|c| c.clip_rect == ruler)
+                    .filter_map(|c| match &c.shape {
+                        Shape::LineSegment { points: [a, b], .. } if x && a.x == b.x => Some(a.x),
+                        Shape::LineSegment { points: [a, b], .. } if !x && a.y == b.y => Some(a.y),
+                        _ => None,
+                    })
+                    .collect();
+                at.sort_by(f32::total_cmp);
+                at
+            };
+            for (ruler, x) in [(top, true), (left, false)] {
+                let at = along(ruler, x);
+                let (start, end) = if x { (ruler.left(), ruler.right()) } else { (ruler.top(), ruler.bottom()) };
+                let (Some(first), Some(last)) = (at.first(), at.last()) else { panic!("{deg}°: no ticks") };
+                assert!(first - start < 20.0 && end - last < 20.0, "{deg}°: ticks from {first} to {last} on {start}..{end}");
+                assert!(at.windows(2).all(|w| w[1] - w[0] < 20.0), "{deg}°: a gap in the ticks");
+            }
+            if deg == 0.0 {
+                let origin = xf.to_screen(Point::ZERO).x;
+                assert!(along(top, true).iter().any(|x| (x - origin).abs() < 0.01), "a tick at x = 0");
+            }
+        }
+    }
+
     #[test]
     fn shaper_selection_highlights_only_the_visible_result() {
         let mut s = Session::new();

crates/ui-egui/src/chrome.rs

@@ -265,23 +265,7 @@ pub fn control_bar(app: &mut VectorcraftApp, ui: &mut Ui) {
                     }
                     return;
                 }
-                // Align buttons.
-                for (icon, tip, p) in [
-                    ("align-start-vertical", "Horizontal Align Left", json!({"horizontal": "left"})),
-                    ("align-center-vertical", "Horizontal Align Center", json!({"horizontal": "center"})),
-                    ("align-end-vertical", "Horizontal Align Right", json!({"horizontal": "right"})),
-                    ("align-start-horizontal", "Vertical Align Top", json!({"vertical": "top"})),
-                    ("align-center-horizontal", "Vertical Align Center", json!({"vertical": "center"})),
-                    ("align-end-horizontal", "Vertical Align Bottom", json!({"vertical": "bottom"})),
-                ] {
-                    if widgets::icon_button(ui, icon, tl!(tip), false, 24.0).clicked() {
-                        let mut p = p;
-                        if sel.len() == 1 {
-                            p["to"] = json!("artboard");
-                        }
-                        app.run("object.align", p).ok();
-                    }
-                }
+                crate::panels::align::align_buttons(app, ui, 24.0);
                 ui.separator();
                 // The Transform link opens the whole Transform panel (reference point, rotate,
                 // shear, options) in a popover; X/Y/W/H follow inline while the bar has room.

crates/ui-egui/src/dialogs/confirm.rs

@@ -36,6 +36,17 @@ pub fn ask(app: &mut VectorcraftApp, message: &str, detail: &str, command: &str,
     app.ui.dialog = Some(Dialog::new(KIND, fields));
 }
 
+/// The dialog kind of a message with a Close button only ([`tell`]).
+pub const MESSAGE: &str = "message";
+
+pub(super) const MESSAGE_SPEC: DialogSpec = DialogSpec { ok: None, ..SPEC };
+
+/// Tell the user `message` (with an optional `detail` line), both in the UI language, in a dialog
+/// they close.
+pub fn tell(app: &mut VectorcraftApp, message: &str, detail: &str) {
+    app.ui.dialog = Some(Dialog::new(MESSAGE, json!({"message": message, "detail": detail})));
+}
+
 /// Closes before running, so a dialog the command opens stays open.
 fn confirm(app: &mut VectorcraftApp, d: &Dialog) -> Result<Value, String> {
     let params = d.fields.get("__params").cloned().unwrap_or_else(|| json!({}));

crates/ui-egui/src/dialogs/gradient_stop.rs

@@ -90,12 +90,19 @@ fn show(app: &mut VectorcraftApp, ctx: &egui::Context) {
     let screen =
         d.fields.get("screen").and_then(Value::as_array).and_then(|a| Some(egui::pos2(a.first()?.as_f64()? as f32, a.get(1)?.as_f64()? as f32)));
     let chip = Point::new(d.f64("x", 0.0), d.f64("y", 0.0));
-    let pos = screen.unwrap_or_else(|| {
-        app.canvas_rect.zip(app.view().copied()).map_or(ctx.content_rect().center(), |(r, v)| Xf::new(r, &v).to_screen(chip) + vec2(14.0, 14.0))
+    let area = egui::Id::new("gradient-stop-popover");
+    let size = ctx.memory(|m| m.area_rect(area)).map_or(POPOVER_SIZE, |r| r.size());
+    let pos = screen.unwrap_or_else(|| match app.canvas_rect.zip(app.view().copied()) {
+        Some((canvas, v)) => {
+            let xf = Xf::new(canvas, &v);
+            let at = xf.to_screen(chip);
+            selection_on_screen(app, &xf).map_or(at + vec2(14.0, 14.0), |art| beside_art(at, art, size, canvas))
+        }
+        None => ctx.content_rect().center(),
     });
     let swatches = d.str("tab") == "swatches";
     let mut tab = None;
-    let resp = egui::Area::new(egui::Id::new("gradient-stop-popover"))
+    let resp = egui::Area::new(area)
         .order(egui::Order::Foreground)
         .fixed_pos(pos)
         .constrain(true)
@@ -150,6 +157,34 @@ fn show(app: &mut VectorcraftApp, ctx: &egui::Context) {
     }
 }
 
+/// The popover's size before it has been drawn.
+const POPOVER_SIZE: egui::Vec2 = vec2(272.0, 360.0);
+
+/// The selected art's box on the screen.
+fn selection_on_screen(app: &VectorcraftApp, xf: &Xf) -> Option<egui::Rect> {
+    let st = app.session.active()?;
+    let b = st.doc.bounds_of(&st.selection.objects, false)?;
+    Some(egui::Rect::from_points(&xf.quad(b)))
+}
+
+/// Where the popover opened from a stop's chip at `chip` goes: beside the selected `art` on the
+/// first side of it with room for a popover of `size` in `room` (right, left, below, above), so
+/// the art it recolours stays in view (#862); else beside the chip.
+fn beside_art(chip: egui::Pos2, art: egui::Rect, size: egui::Vec2, room: egui::Rect) -> egui::Pos2 {
+    const GAP: f32 = 12.0;
+    let x = (chip.x - size.x / 2.0).clamp(room.left(), (room.right() - size.x).max(room.left()));
+    let y = (chip.y - size.y / 2.0).clamp(room.top(), (room.bottom() - size.y).max(room.top()));
+    [
+        egui::pos2(art.right() + GAP, y),
+        egui::pos2(art.left() - GAP - size.x, y),
+        egui::pos2(x, art.bottom() + GAP),
+        egui::pos2(x, art.top() - GAP - size.y),
+    ]
+    .into_iter()
+    .find(|p| room.contains_rect(egui::Rect::from_min_size(*p, size)))
+    .unwrap_or(chip + vec2(14.0, 14.0))
+}
+
 /// Document swatches as tiles: a click gives the stop (or point) that colour.
 fn swatch_grid(app: &mut VectorcraftApp, ui: &mut egui::Ui, target: &Target) {
     let colors = swatch_colors(app);
@@ -248,6 +283,28 @@ mod tests {
         app
     }
 
+    /// #862: the popover goes beside the art, on the first side with room, not over it.
+    #[test]
+    fn the_popover_goes_beside_the_art_it_edits() {
+        let room = egui::Rect::from_min_size(egui::pos2(0.0, 0.0), egui::vec2(1200.0, 800.0));
+        let size = egui::vec2(272.0, 360.0);
+        let place = |art: egui::Rect| egui::Rect::from_min_size(beside_art(art.center(), art, size, room), size);
+        // Room on the right.
+        let art = egui::Rect::from_min_max(egui::pos2(300.0, 300.0), egui::pos2(500.0, 450.0));
+        assert!(place(art).left() > art.right() && room.contains_rect(place(art)));
+        // Against the right edge: on the left.
+        let art = egui::Rect::from_min_max(egui::pos2(900.0, 300.0), egui::pos2(1150.0, 450.0));
+        assert!(place(art).right() < art.left());
+        // As wide as the room: below it, or above it near the bottom.
+        let art = egui::Rect::from_min_max(egui::pos2(100.0, 20.0), egui::pos2(1100.0, 300.0));
+        assert!(place(art).top() > art.bottom());
+        let art = egui::Rect::from_min_max(egui::pos2(100.0, 420.0), egui::pos2(1100.0, 780.0));
+        assert!(place(art).bottom() < art.top());
+        // Nowhere to go: beside the chip, as before.
+        let art = room.shrink(10.0);
+        assert_eq!(beside_art(art.center(), art, size, room), art.center() + egui::vec2(14.0, 14.0));
+    }
+
     fn stops(app: &VectorcraftApp) -> Vec<GradientStop> {
         match selected(app) {
             Some(Target::Stop(stops, _)) => stops,

crates/ui-egui/src/dialogs/mod.rs

@@ -216,6 +216,7 @@ registry! {
     FindFont: ["findFont"] => DialogSpec::window(crate::find_font::show, |app, _| crate::find_font::confirm(app)),
     SwatchOptions: [swatch_options::KIND] => swatch_options::SPEC,
     Confirm: [confirm::KIND] => confirm::SPEC,
+    Message: [confirm::MESSAGE] => confirm::MESSAGE_SPEC,
     NewSwatch: [new_swatch::KIND] => new_swatch::SPEC,
     NewColorGroup: [new_color_group::KIND] => new_color_group::SPEC,
     GradientStop: ["gradientStop"] => gradient_stop::SPEC,

crates/ui-egui/src/i18n/es.tsv

@@ -686,6 +686,7 @@
 	Divide Vertically Into	Dividir verticalmente en
 	Do Not Move	No mover
 	Do you want to save the changes you made to “{name}”?	¿Quieres guardar los cambios hechos en “{name}”?
+	Can't open “{name}”.	No se puede abrir «{name}».
 	Document	Documento
 	Document Color Mode	Modo de color del documento
 	Document Info	Información del documento
@@ -1497,6 +1498,8 @@
 	Monospaced	Monoespaciada
 	More	Más
 	More Pathfinder options	Más opciones de Buscatrazos
+	More Align options	Más opciones de alineación
+	More Paragraph options	Más opciones de párrafo
 	More Settings	Más ajustes
 	Move	Mover
 	Move All Objects	Mover todos los objetos
@@ -3779,3 +3782,8 @@ axis	Both	Ambos
 	Constrain	Restringir
 	Free Transform	Transformación libre
 	Perspective Distort	Distorsión de perspectiva
+@msg	`id` is the step reference {r}, which only `run` and `command_batch` resolve	`id` es la referencia a un paso {r}, que solo `run` y `command_batch` resuelven
+@msg	`ids` must be an array of object ids, not {v}	`ids` debe ser una lista de identificadores de objeto, no {v}
+@msg	`{text}`: step {i}'s result has no such value (write $$ for a literal $)	`{text}`: el resultado del paso {i} no tiene ese valor (escriba $$ para un $ literal)
+@msg	`{text}`: there is no step {i} before this one (steps count from 0; write $$ for a literal $)	`{text}`: no hay ningún paso {i} antes de este (los pasos se cuentan desde 0; escriba $$ para un $ literal)
+@msg	object ids are non-negative integers, not {v}	los identificadores de objeto son enteros no negativos, no {v}

crates/ui-egui/src/i18n/fr.tsv

@@ -688,6 +688,7 @@
 	Divide Vertically Into	Diviser verticalement en
 	Do Not Move	Ne pas déplacer
 	Do you want to save the changes you made to “{name}”?	Voulez-vous enregistrer les modifications apportées à « {name} » ?
+	Can't open “{name}”.	Impossible d’ouvrir « {name} ».
 	Document	Document
 	Document Color Mode	Mode colorimétrique du document
 	Document Info	Informations sur le document
@@ -1496,6 +1497,8 @@
 	Monospaced	À chasse fixe
 	More	Plus
 	More Pathfinder options	Plus d’options Pathfinder
+	More Align options	Plus d’options d’alignement
+	More Paragraph options	Plus d’options de paragraphe
 	More Settings	Plus de réglages
 	Move	Déplacer
 	Move All Objects	Déplacer tous les objets
@@ -3790,3 +3793,8 @@ axis	Both	Les deux
 	Insert Inline Symbol	Insérer un symbole dans le texte
 	ICF Top/Right	ICF haut/droite
 	ICF Bottom/Left	ICF bas/gauche
+@msg	`id` is the step reference {r}, which only `run` and `command_batch` resolve	`id` est la référence d’étape {r}, que seuls `run` et `command_batch` résolvent
+@msg	`ids` must be an array of object ids, not {v}	`ids` doit être une liste d’identifiants d’objet, pas {v}
+@msg	`{text}`: step {i}'s result has no such value (write $$ for a literal $)	`{text}` : le résultat de l’étape {i} n’a pas cette valeur (écrivez $$ pour un $ littéral)
+@msg	`{text}`: there is no step {i} before this one (steps count from 0; write $$ for a literal $)	`{text}` : il n’y a pas d’étape {i} avant celle-ci (les étapes sont comptées à partir de 0 ; écrivez $$ pour un $ littéral)
+@msg	object ids are non-negative integers, not {v}	les identifiants d’objet sont des entiers positifs ou nuls, pas {v}

crates/ui-egui/src/i18n/it.tsv

@@ -686,6 +686,7 @@
 	Divide Vertically Into	Dividi verticalmente in
 	Do Not Move	Non spostare
 	Do you want to save the changes you made to “{name}”?	Vuoi salvare le modifiche apportate a “{name}”?
+	Can't open “{name}”.	Impossibile aprire «{name}».
 	Document	Documento
 	Document Color Mode	Metodo colore documento
 	Document Info	Informazioni documento
@@ -1497,6 +1498,8 @@
 	Monospaced	Monospaziato
 	More	Altro
 	More Pathfinder options	Altre opzioni di Elaborazione tracciati
+	More Align options	Altre opzioni di allineamento
+	More Paragraph options	Altre opzioni di paragrafo
 	More Settings	Altre impostazioni
 	Move	Sposta
 	Move All Objects	Sposta tutti gli oggetti
@@ -3779,3 +3782,8 @@ axis	Both	Entrambi
 	Constrain	Vincola
 	Free Transform	Trasformazione libera
 	Perspective Distort	Distorsione prospettica
+@msg	`id` is the step reference {r}, which only `run` and `command_batch` resolve	`id` è il riferimento al passaggio {r}, che solo `run` e `command_batch` risolvono
+@msg	`ids` must be an array of object ids, not {v}	`ids` deve essere un elenco di ID oggetto, non {v}
+@msg	`{text}`: step {i}'s result has no such value (write $$ for a literal $)	`{text}`: il risultato del passaggio {i} non ha questo valore (scrivi $$ per un $ letterale)
+@msg	`{text}`: there is no step {i} before this one (steps count from 0; write $$ for a literal $)	`{text}`: non c’è un passaggio {i} prima di questo (i passaggi si contano da 0; scrivi $$ per un $ letterale)
+@msg	object ids are non-negative integers, not {v}	gli ID oggetto sono interi non negativi, non {v}

crates/ui-egui/src/i18n/ja.tsv

@@ -1122,6 +1122,7 @@
 	Divide Slices	スライスを分割
 	Divide Vertically Into	垂直方向に分割
 	Do you want to save the changes you made to “{name}”?	「{name}」への変更を保存しますか？
+	Can't open “{name}”.	「{name}」を開けません。
 	Document	ドキュメント
 	Document Ink Options	ドキュメントのインキオプション
 	Document JSON	ドキュメント JSON
@@ -1639,6 +1640,8 @@
 	Monochrome images	モノクロイメージ
 	More	多く
 	More Pathfinder options	その他のパスファインダーオプション
+	More Align options	その他の整列オプション
+	More Paragraph options	その他の段落オプション
 	More Settings	その他の設定
 	Move	移動
 	Move Anchors	アンカーポイントを移動
@@ -3771,3 +3774,8 @@ theme	Appearance	外観
 @msg	larger than 256 MB	256 MB を超えています
 @msg	the files come to more than 1 GB: add fewer at a time	ファイルの合計が 1 GB を超えています: 一度に追加するファイルを減らしてください
 @msg	every numbered name for it is taken in the Fonts folder	Fonts フォルダーでは、このファイルの番号付きの名前がすべて使われています
+@msg	`id` is the step reference {r}, which only `run` and `command_batch` resolve	`id` はステップ参照 {r} です。ステップ参照を解決できるのは `run` と `command_batch` だけです
+@msg	`ids` must be an array of object ids, not {v}	`ids` はオブジェクト ID の配列にしてください ({v} は使えません)
+@msg	`{text}`: step {i}'s result has no such value (write $$ for a literal $)	`{text}`: ステップ {i} の結果にその値はありません ($ そのものを書くには $$ と入力してください)
+@msg	`{text}`: there is no step {i} before this one (steps count from 0; write $$ for a literal $)	`{text}`: この前にステップ {i} はありません (ステップは 0 から数えます。$ そのものを書くには $$ と入力してください)
+@msg	object ids are non-negative integers, not {v}	オブジェクト ID は 0 以上の整数です ({v} は使えません)

crates/ui-egui/src/i18n/pt-br.tsv

@@ -636,6 +636,7 @@
 	Divide Slices…	Dividir Fatias…
 	Divide Vertically Into	Dividir Verticalmente Em
 	Do you want to save the changes you made to “{name}”?	Deseja salvar as alterações feitas em “{name}”?
+	Can't open “{name}”.	Não é possível abrir “{name}”.
 	Document	Documento
 	Document Color Mode	Modo de Cor do Documento
 	Document Info	Informações do Documento
@@ -1313,6 +1314,8 @@
 	Monochrome images	Imagens monocromáticas
 	More	Mais
 	More Pathfinder options	Mais opções de Localizador de Caminhos
+	More Align options	Mais opções de alinhamento
+	More Paragraph options	Mais opções de parágrafo
 	More Settings	Mais Configurações
 	Move	Mover
 	Move Anchors	Mover Âncoras

crates/ui-egui/src/i18n/ru.tsv

@@ -684,6 +684,7 @@
 	Divide Vertically Into	Разделить по вертикали на
 	Do Not Move	Не перемещать
 	Do you want to save the changes you made to “{name}”?	Сохранить изменения, внесённые в «{name}»?
+	Can't open “{name}”.	Не удаётся открыть «{name}».
 	Document	Документ
 	Document Color Mode	Цветовой режим документа
 	Document Info	Сведения о документе
@@ -1495,6 +1496,8 @@
 	Monospaced	Моноширинный
 	More	Больше
 	More Pathfinder options	Дополнительные параметры обработки контуров
+	More Align options	Дополнительные параметры выравнивания
+	More Paragraph options	Дополнительные параметры абзаца
 	More Settings	Дополнительные настройки
 	Move	Переместить
 	Move All Objects	Переместить все объекты
@@ -3777,3 +3780,8 @@ axis	Both	Оба
 	Perspective Distort	Искажение перспективы
 	Artboard	Монтажная область
 	Exit	Выйти
+@msg	`id` is the step reference {r}, which only `run` and `command_batch` resolve	`id` — это ссылка на шаг {r}, которую разрешают только `run` и `command_batch`
+@msg	`ids` must be an array of object ids, not {v}	`ids` должен быть массивом идентификаторов объектов, а не {v}
+@msg	`{text}`: step {i}'s result has no such value (write $$ for a literal $)	`{text}`: в результате шага {i} нет такого значения (чтобы написать сам $, введите $$)
+@msg	`{text}`: there is no step {i} before this one (steps count from 0; write $$ for a literal $)	`{text}`: перед этим шагом нет шага {i} (шаги считаются с 0; чтобы написать сам $, введите $$)
+@msg	object ids are non-negative integers, not {v}	идентификаторы объектов — неотрицательные целые числа, а не {v}

crates/ui-egui/src/i18n/uk.tsv

@@ -680,6 +680,7 @@
 	Divide Vertically Into	Розділити по вертикалі на
 	Do Not Move	Не переміщати
 	Do you want to save the changes you made to “{name}”?	Зберегти зміни, внесені до «{name}»?
+	Can't open “{name}”.	Не вдається відкрити «{name}».
 	Document	Документ
 	Document Color Mode	Колірний режим документа
 	Document Info	Відомості про документ
@@ -1491,6 +1492,8 @@
 	Monospaced	Моноширинний
 	More	Більше
 	More Pathfinder options	Додаткові параметри обробки контурів
+	More Align options	Додаткові параметри вирівнювання
+	More Paragraph options	Додаткові параметри абзацу
 	More Settings	Додаткові налаштування
 	Move	Перемістити
 	Move All Objects	Перемістити всі об’єкти
@@ -3762,3 +3765,8 @@ axis	Both	Обидві
 	Perspective Distort	Спотворення перспективи
 	Artboard	Монтажна область
 	Exit	Вийти
+@msg	`id` is the step reference {r}, which only `run` and `command_batch` resolve	`id` — це посилання на крок {r}, яке розв’язують лише `run` і `command_batch`
+@msg	`ids` must be an array of object ids, not {v}	`ids` має бути масивом ідентифікаторів об’єктів, а не {v}
+@msg	`{text}`: step {i}'s result has no such value (write $$ for a literal $)	`{text}`: у результаті кроку {i} немає такого значення (щоб написати сам $, введіть $$)
+@msg	`{text}`: there is no step {i} before this one (steps count from 0; write $$ for a literal $)	`{text}`: перед цим кроком немає кроку {i} (кроки рахуються з 0; щоб написати сам $, введіть $$)
+@msg	object ids are non-negative integers, not {v}	ідентифікатори об’єктів — невід’ємні цілі числа, а не {v}

crates/ui-egui/src/i18n/zh-hans.tsv

@@ -666,6 +666,7 @@
 	Divide Vertically Into	垂直分割为
 	Do Not Move	不移动
 	Do you want to save the changes you made to “{name}”?	要存储对“{name}”所做的更改吗？
+	Can't open “{name}”.	无法打开“{name}”。
 	Document	文档
 	Document Color Mode	文档颜色模式
 	Document Info	文档信息
@@ -1455,6 +1456,8 @@
 	Monochrome images	单色图像
 	More	较多
 	More Pathfinder options	更多路径查找器选项
+	More Align options	更多对齐选项
+	More Paragraph options	更多段落选项
 	More Settings	更多设置
 	Move	移动
 	Move All Objects	移动所有对象

crates/ui-egui/src/i18n/zh-hant.tsv

@@ -684,6 +684,7 @@
 	Divide Vertically Into	垂直分割為
 	Do Not Move	不移動
 	Do you want to save the changes you made to “{name}”?	要儲存對「{name}」所做的變更嗎？
+	Can't open “{name}”.	無法開啟「{name}」。
 	Document	文件
 	Document Color Mode	文件色彩模式
 	Document Info	文件資訊
@@ -1497,6 +1498,8 @@
 	Monospaced	等寬
 	More	更多
 	More Pathfinder options	更多路徑管理員選項
+	More Align options	更多對齊選項
+	More Paragraph options	更多段落選項
 	More Settings	更多設定
 	Move	移動
 	Move All Objects	移動所有物件

crates/ui-egui/src/io.rs

@@ -97,7 +97,24 @@ pub fn open_dialog(app: &mut VectorcraftApp) -> Result<(), String> {
         return Ok(());
     }
     let path = pick_open(app, &FilePick { filters: fileio::open_filters().collect(), ..Default::default() })?;
-    open_path(app, &path).map(|_| ())
+    open_reporting(app, &path).map(|_| ())
+}
+
+/// A file the user asked to open (File › Open, Open Recent, the Home screen, a drop, the Finder)
+/// couldn't be: say so in a dialog as well as the status bar, which is easily missed (#861).
+pub fn report_open_error(app: &mut VectorcraftApp, name: &str, e: &str) {
+    app.status(format!("Couldn't open {name}: {e}"));
+    let message = crate::i18n::fmt(tl!("Can't open “{name}”."), &[("name", name)]);
+    dialogs::confirm::tell(app, &message, &crate::i18n::message(crate::i18n::current(), e));
+}
+
+/// [`open_path`] for a file the user asked for, a failure reported ([`report_open_error`]).
+pub fn open_reporting(app: &mut VectorcraftApp, path: &str) -> Result<Value, String> {
+    let r = open_path(app, path);
+    if let Err(e) = &r {
+        report_open_error(app, &fileio::file_name(path), e);
+    }
+    r
 }
 
 fn read(app: &VectorcraftApp, path: &str) -> Result<Vec<u8>, String> {
@@ -699,6 +716,24 @@ mod tests {
         (VectorcraftApp::new(Session::new(), services), written)
     }
 
+    /// #861: a file the user opens that can't be opened is reported in a dialog they close, not
+    /// only in the status bar; a file an agent opens by path only answers with the error.
+    #[test]
+    fn a_file_the_user_cant_open_is_reported_in_a_dialog() {
+        let (mut app, _) = app();
+        app.services.read = Some(Box::new(|_: &str| Err("no such file".into())));
+        assert!(open_reporting(&mut app, "/docs/gone.ai").is_err());
+        let d = app.ui.dialog.take().expect("a dialog says so");
+        assert_eq!(
+            (d.kind.as_str(), d.str("message"), d.str("detail")),
+            (dialogs::confirm::MESSAGE, "Can't open “gone.ai”.".to_string(), "no such file".to_string())
+        );
+        assert!(app.ui.status.contains("gone.ai"));
+        // An agent's `file.open {path}` gets the error back and no dialog.
+        assert!(app.run("file.open", json!({"path": "/docs/gone.ai"})).is_err());
+        assert!(app.ui.dialog.is_none());
+    }
+
     fn bytes_of(app: &mut VectorcraftApp, cmd: &str, p: Value) -> Vec<u8> {
         let v = app.session.execute(cmd, &p).unwrap();
         vectorcraft_format::base64_decode(v["dataBase64"].as_str().unwrap()).unwrap()

crates/ui-egui/src/lib.rs

@@ -293,6 +293,8 @@ pub struct CacheKey {
     pub pixel: Option<[i64; 4]>,
     /// Images sampled smoothly ([`vectorcraft_render::RenderOptions::smooth_images`]).
     pub smooth_images: bool,
+    /// Isolation mode's group or layer ([`vectorcraft_render::RenderOptions::isolated`]).
+    pub isolated: Option<u64>,
 }
 
 #[derive(Clone, Copy, Debug, Default)]
@@ -704,7 +706,7 @@ impl VectorcraftApp {
             self.services.inbox.as_ref().map(|q| std::mem::take(&mut *q.lock().unwrap_or_else(|e| e.into_inner()))).unwrap_or_default();
         for (name, bytes) in arrived {
             if let Err(e) = io::open_bytes(self, &name, &bytes, None) {
-                self.status(format!("Couldn't open {name}: {e}"));
+                io::report_open_error(self, &name, &e);
             }
         }
         place::drain(self);

crates/ui-egui/src/menus.rs

@@ -884,7 +884,7 @@ pub fn run_ui_command(app: &mut VectorcraftApp, id: &str, p: &Value) -> Option<R
         "file.revert" if p.get("confirmed").and_then(Value::as_bool) != Some(true) => io::ask_revert(app),
         "file.reveal" => io::reveal(app),
         id if id.starts_with("file.openRecent") => match recent_slot(app, id).cloned() {
-            Some(path) => io::open_path(app, &path),
+            Some(path) => io::open_reporting(app, &path),
             None => Err("no such recent file".into()),
         },
         "type.findFont" => {

crates/ui-egui/src/panels/align.rs

@@ -52,6 +52,26 @@ pub const DISTRIBUTE: [(&str, &str, &str, &str); 6] = [
     ("dc-dist-right", "Horizontal Distribute Right", "horizontal", "right"),
 ];
 
+/// The six align buttons of the Control bar and the Properties panel, `size` points square.
+/// They align to what the Align panel's Align To says (the key object while there is one), as
+/// its own buttons do (#789).
+pub fn align_buttons(app: &mut VectorcraftApp, ui: &mut Ui, size: f32) {
+    let n = selection_len(app);
+    let to = align_to(app, ui.ctx());
+    for (icon, tip, axis, v) in [
+        ("align-start-vertical", "Horizontal Align Left", "horizontal", "left"),
+        ("align-center-vertical", "Horizontal Align Center", "horizontal", "center"),
+        ("align-end-vertical", "Horizontal Align Right", "horizontal", "right"),
+        ("align-start-horizontal", "Vertical Align Top", "vertical", "top"),
+        ("align-center-horizontal", "Vertical Align Center", "vertical", "center"),
+        ("align-end-horizontal", "Vertical Align Bottom", "vertical", "bottom"),
+    ] {
+        if widgets::icon_button(ui, icon, tl!(tip), false, size).clicked() {
+            app.run("object.align", align_params(json!({axis: v}), to, n)).ok();
+        }
+    }
+}
+
 /// Whether the selection has a key object.
 fn has_key(app: &VectorcraftApp) -> bool {
     app.session.active().is_some_and(|st| st.selection.key.is_some())
@@ -183,4 +203,35 @@ mod tests {
         app.run("select.key", json!({})).unwrap();
         assert_eq!(align_to(&app, &ctx), AlignTo::Selection, "no key: the choice again");
     }
+
+    /// #789: the Control bar's and the Properties panel's align buttons follow Align To too.
+    #[test]
+    fn the_other_align_buttons_align_to_the_align_to_choice() {
+        let mut app = VectorcraftApp::new(vectorcraft_engine::Session::new(), Default::default());
+        app.run("file.new", json!({"width": 200, "height": 200})).unwrap();
+        let a = app.run("shape.rectangle", json!({"x": 10, "y": 10, "width": 10, "height": 10})).unwrap()["id"].clone();
+        let b = app.run("shape.rectangle", json!({"x": 80, "y": 50, "width": 30, "height": 30})).unwrap()["id"].clone();
+        app.run("select.set", json!({"ids": [a, b]})).unwrap();
+        let ctx = egui::Context::default();
+        set_pstate(&ctx, "align-to", AlignTo::Artboard);
+        // One frame finds the first button (Horizontal Align Right is third); the next clicks it.
+        let at = std::cell::Cell::new(egui::Pos2::ZERO);
+        let frame = |app: &mut VectorcraftApp, events: Vec<egui::Event>| {
+            let mut out = ctx.run_ui(egui::RawInput { events, ..Default::default() }, |ui| {
+                ui.horizontal(|ui| {
+                    at.set(ui.cursor().min);
+                    align_buttons(app, ui, 24.0);
+                });
+            });
+            out.textures_delta.clear();
+        };
+        frame(&mut app, vec![]);
+        let right = at.get() + egui::vec2(2.0 * (24.0 + ctx.global_style().spacing.item_spacing.x) + 12.0, 12.0);
+        let press = |pressed| egui::Event::PointerButton { pos: right, button: egui::PointerButton::Primary, pressed, modifiers: Default::default() };
+        frame(&mut app, vec![egui::Event::PointerMoved(right), press(true)]);
+        frame(&mut app, vec![press(false)]);
+        let st = app.session.active().unwrap();
+        let x1 = |id: &serde_json::Value| st.doc.bounds_of(&[vectorcraft_doc::NodeId(id.as_u64().unwrap())], false).unwrap().x1;
+        assert_eq!((x1(&a), x1(&b)), (200.0, 200.0), "both to the artboard's right edge");
+    }
 }

crates/ui-egui/src/panels/color.rs

@@ -496,7 +496,7 @@ pub fn show(app: &mut VectorcraftApp, ui: &mut Ui) {
         (Some(c), _) => components(mode, &c),
         (None, _) => vec![0.0; mode.labels().len()],
     };
-    super::recent_colors_row(app, ui);
+    let recent = super::recent_colors_row(app, ui);
     widgets::divider(ui);
     // An edit of the active colour with its displayed components (`new`), or a colour clicked with
     // Alt held for the inactive proxy (`behind`).
@@ -585,6 +585,10 @@ pub fn show(app: &mut VectorcraftApp, ui: &mut Ui) {
             *new = Some((c, phase, components(mode, &c)));
         }
     };
+    // A recent colour, like the chips, recolours the selected gradient stop (or point).
+    if let Some(c) = recent {
+        pick(c, Live::Released, &mut new);
+    }
     // None / Black / White chips and the hex field.
     ui.horizontal(|ui| {
         ui.spacing_mut().item_spacing.x = 0.0;
@@ -691,12 +695,23 @@ mod tests {
     /// Run the panel for one frame with `events` and `modifiers`; returns the spectrum's rect (when
     /// the options are shown) and the panel's height.
     fn frame(app: &mut VectorcraftApp, ctx: &egui::Context, events: Vec<egui::Event>, modifiers: egui::Modifiers) -> (Option<Rect>, f32) {
+        frame_with(app, ctx, events, modifiers, "color-spectrum")
+    }
+
+    /// [`frame`] returning the rect of the panel's widget `id` instead of the spectrum's.
+    fn frame_with(
+        app: &mut VectorcraftApp,
+        ctx: &egui::Context,
+        events: Vec<egui::Event>,
+        modifiers: egui::Modifiers,
+        id: impl std::hash::Hash + std::fmt::Debug,
+    ) -> (Option<Rect>, f32) {
         let mut out = (None, 0.0);
         let events = std::iter::once(egui::Event::ModifiersChanged(modifiers)).chain(events).collect();
         let input = egui::RawInput { events, ..Default::default() };
         let mut full = ctx.run_ui(input, |ui| {
             show(app, ui);
-            out = (ctx.read_response(ui.id().with("color-spectrum")).map(|r| r.rect), ui.min_rect().height());
+            out = (ctx.read_response(ui.id().with(&id)).map(|r| r.rect), ui.min_rect().height());
         });
         full.textures_delta.clear();
         out
@@ -712,6 +727,27 @@ mod tests {
         frame(app, ctx, vec![], egui::Modifiers::NONE);
     }
 
+    #[test]
+    fn a_recent_colour_recolours_the_selected_gradient_stop() {
+        // #835: it replaced the whole gradient with the colour.
+        let mut app = app();
+        app.run("paint.setFill", json!({"color": "#ff0000"})).unwrap();
+        let stops = json!([{"offset": 0, "color": "#ffffff"}, {"offset": 1, "color": "#000000"}]);
+        app.run("paint.setFill", json!({"gradient": {"stops": stops, "start": [10, 35], "end": [60, 35]}})).unwrap();
+        app.select_tool("gradient");
+        app.run("gradient.selectStop", json!({"index": 1})).unwrap();
+        let red = app.session.recent_colors.iter().position(|c| c.to_hex() == "#ff0000").expect("red is a recent colour");
+        let ctx = egui::Context::default();
+        let none = egui::Modifiers::NONE;
+        let chip = frame_with(&mut app, &ctx, vec![], none, ("recent", red)).0.expect("the chip is drawn").center();
+        let button = |pressed| egui::Event::PointerButton { pos: chip, button: egui::PointerButton::Primary, pressed, modifiers: none };
+        frame(&mut app, &ctx, vec![egui::Event::PointerMoved(chip), button(true)], none);
+        frame(&mut app, &ctx, vec![button(false)], none);
+        let Paint::Gradient(g) = crate::panels::current_paints(&app).0 else { panic!("still a gradient") };
+        let hex: Vec<String> = g.gradient.stops.iter().map(|s| s.color.to_hex()).collect();
+        assert_eq!(hex, ["#ffffff", "#ff0000"]);
+    }
+
     fn paints_hex(app: &VectorcraftApp) -> (String, String) {
         let (f, s) = crate::panels::current_paints(app);
         (f.color().map(|c| c.to_hex()).unwrap_or_default(), s.color().map(|c| c.to_hex()).unwrap_or_default())

crates/ui-egui/src/panels/mod.rs

@@ -412,8 +412,8 @@ pub(crate) fn label_or_name(s: &str, built_in: bool) -> &str {
 }
 
 /// "Recent Colors" header + a row of chips (the Session's recent colours, which every paint
-/// command feeds); clicking one applies it to the active proxy (Alt: the inactive one).
-pub(crate) fn recent_colors_row(app: &mut VectorcraftApp, ui: &mut Ui) {
+/// command feeds); returns the one clicked, for the caller to apply.
+pub(crate) fn recent_colors_row(app: &VectorcraftApp, ui: &mut Ui) -> Option<Color> {
     let t = Tokens::get(ui.ctx());
     crate::widgets::subheader(ui, "Recent Colors");
     let (r, _) = ui.allocate_exact_size(vec2(ui.available_width(), 22.0), Sense::hover());
@@ -430,9 +430,7 @@ pub(crate) fn recent_colors_row(app: &mut VectorcraftApp, ui: &mut Ui) {
             chosen = Some(*c);
         }
     }
-    if let Some(c) = chosen {
-        apply_click(app, ui, json!({"color": color_json(&c)}));
-    }
+    chosen
 }
 
 /// A colour as command JSON, keeping its model.

crates/ui-egui/src/panels/paragraph.rs

@@ -60,6 +60,24 @@ fn shown_alignment(justify: Justify, rtl: bool) -> Justify {
     }
 }
 
+/// The seven alignment buttons, `size` points square, the one of `para`'s alignment on (the
+/// Paragraph panel's and the Properties panel's).
+pub fn alignment_buttons(app: &mut VectorcraftApp, ui: &mut Ui, para: &ParaStyle, size: f32) {
+    let shown = shown_alignment(para.justify, resolved_rtl(app, para));
+    for (j, icon, tip, id) in ALIGNMENTS {
+        if widgets::icon_button(ui, icon, tip, shown == j, size).clicked() {
+            para_cmd(app, "text.setStyle", json!({"justify": id}));
+        }
+    }
+}
+
+/// The Hyphenate checkbox of `para`'s paragraphs.
+pub fn hyphenate_check(app: &mut VectorcraftApp, ui: &mut Ui, para: &ParaStyle) {
+    if widgets::check(ui, tl!("Hyphenate"), para.hyphenate, true) {
+        format(app, json!({"hyphenate": !para.hyphenate}));
+    }
+}
+
 pub fn show(app: &mut VectorcraftApp, ui: &mut Ui) {
     let t = Tokens::get(ui.ctx());
     let Some((_, para)) = text_style(app) else {
@@ -67,14 +85,9 @@ pub fn show(app: &mut VectorcraftApp, ui: &mut Ui) {
         return;
     };
     let rtl = resolved_rtl(app, &para);
-    let shown = shown_alignment(para.justify, rtl);
     ui.horizontal(|ui| {
         ui.spacing_mut().item_spacing.x = 3.0;
-        for (j, icon, tip, id) in ALIGNMENTS {
-            if widgets::icon_button(ui, icon, tip, shown == j, 28.0).clicked() {
-                para_cmd(app, "text.setStyle", json!({"justify": id}));
-            }
-        }
+        alignment_buttons(app, ui, &para, 28.0);
         // Paragraph direction, with the Middle Eastern (Indic) options.
         if app.session.prefs.show_indic_options {
             ui.add_space(6.0);
@@ -127,9 +140,7 @@ pub fn show(app: &mut VectorcraftApp, ui: &mut Ui) {
     if pstate::<bool>(ui.ctx(), "pa-hide-options") {
         return;
     }
-    if widgets::check(ui, tl!("Hyphenate"), para.hyphenate, true) {
-        format(app, json!({"hyphenate": !para.hyphenate}));
-    }
+    hyphenate_check(app, ui, &para);
     // Japanese composition: how punctuation is spaced (JLREQ 3.1), with the East Asian options.
     if app.session.prefs.show_east_asian_options {
         ui.horizontal(|ui| {

crates/ui-egui/src/panels/properties.rs

@@ -57,21 +57,10 @@ pub fn show(app: &mut VectorcraftApp, ui: &mut Ui) {
     divider(ui);
     section_header(ui, tl!("Align"));
     ui.horizontal(|ui| {
-        for (icon, tip, p) in [
-            ("align-start-vertical", tl!("Horizontal Align Left"), json!({"horizontal": "left"})),
-            ("align-center-vertical", tl!("Horizontal Align Center"), json!({"horizontal": "center"})),
-            ("align-end-vertical", tl!("Horizontal Align Right"), json!({"horizontal": "right"})),
-            ("align-start-horizontal", tl!("Vertical Align Top"), json!({"vertical": "top"})),
-            ("align-center-horizontal", tl!("Vertical Align Center"), json!({"vertical": "center"})),
-            ("align-end-horizontal", tl!("Vertical Align Bottom"), json!({"vertical": "bottom"})),
-        ] {
-            if widgets::icon_button(ui, icon, tip, false, 26.0).clicked() {
-                let mut p = p;
-                if n_sel == 1 {
-                    p["to"] = json!("artboard");
-                }
-                app.run("object.align", p).ok();
-            }
+        super::align::align_buttons(app, ui, 26.0);
+        // The rest (Distribute Objects, Distribute Spacing, Align To) is the Align panel's.
+        if widgets::icon_button(ui, "ellipsis", tl!("More Align options"), false, 26.0).clicked() {
+            app.ui.open_panel = Some("align".into());
         }
     });
     if n_sel > 1 {
@@ -534,13 +523,17 @@ pub fn type_sections(app: &mut VectorcraftApp, ui: &mut Ui) {
     super::character::font_pickers(app, ui, &s, ("font", "font-style"), (w - 4.0, w - 4.0));
     super::character::metrics_grid(app, ui, "props-char", &s, w, false);
     section_header(ui, tl!("Paragraph"));
-    ui.horizontal(|ui| {
-        for (icon, j) in [("align-start-vertical", "left"), ("align-center-vertical", "center"), ("align-end-vertical", "right")] {
-            if widgets::icon_button(ui, icon, j, false, 24.0).clicked() {
-                app.run("text.setStyle", json!({"justify": j})).ok();
+    // As in the Paragraph panel: the seven alignments and Hyphenate (#775); the rest is there.
+    if let Some((_, para)) = super::character::text_style(app) {
+        ui.horizontal(|ui| {
+            ui.spacing_mut().item_spacing.x = 3.0;
+            super::paragraph::alignment_buttons(app, ui, &para, 24.0);
+            if widgets::icon_button(ui, "ellipsis", tl!("More Paragraph options"), false, 24.0).clicked() {
+                app.ui.open_panel = Some("paragraph".into());
             }
-        }
-    });
+        });
+        super::paragraph::hyphenate_check(app, ui, &para);
+    }
 }
 
 #[cfg(test)]
@@ -603,6 +596,20 @@ mod tests {
     }
 
     /// #530: Edit Artboards shows the active artboard, with New Artboard, Delete Artboard and Exit.
+    /// #775: type's Paragraph section has Hyphenate, and its checkbox turns it on.
+    #[test]
+    fn type_paragraph_section_hyphenates() {
+        let mut app = VectorcraftApp::new(Session::new(), Default::default());
+        app.run("file.new", json!({"width": 200, "height": 100})).unwrap();
+        app.run("text.create", json!({"x": 10, "y": 50, "text": "Paragraph"})).unwrap();
+        let ctx = egui::Context::default();
+        frame(&mut app, &ctx, vec![]);
+        let texts = frame(&mut app, &ctx, vec![]);
+        click(&mut app, &ctx, &texts, "Hyphenate");
+        let hyphenate = |app: &VectorcraftApp| crate::panels::character::text_style(app).unwrap().1.hyphenate;
+        assert!(hyphenate(&app));
+    }
+
     #[test]
     fn edit_artboards_adds_artboards_and_exits() {
         let mut app = VectorcraftApp::new(Session::new(), Default::default());

crates/ui-egui/src/panels/swatches.rs

@@ -642,7 +642,10 @@ fn body(app: &mut VectorcraftApp, ui: &mut Ui, salt: &'static str) {
         }
     });
     ui.add_space(4.0);
-    super::recent_colors_row(app, ui);
+    // A recent colour paints the active proxy (Alt: the inactive one), as a swatch does.
+    if let Some(c) = super::recent_colors_row(app, ui) {
+        super::apply_click(app, ui, json!({"color": super::color_json(&c)}));
+    }
     widgets::divider(ui);
     widgets::subheader(ui, tl!("Swatch Tiles"));
     let query = if pstate(ui.ctx(), "swatch-show-find") { widgets::search_field(ui, find_id(), tl!("Find")) } else { String::new() };

crates/ui-egui/src/place.rs

@@ -357,8 +357,10 @@ pub fn drop_files(app: &mut VectorcraftApp, mut files: Vec<(DropTarget, DropFile
                 }),
             },
         };
-        if let Err(e) = r {
-            app.status(if target == DropTarget::Open { format!("Couldn't open {name}: {e}") } else { format!("Couldn't place {name}: {e}") });
+        match r {
+            Err(e) if target == DropTarget::Open => io::report_open_error(app, &name, &e),
+            Err(e) => app.status(format!("Couldn't place {name}: {e}")),
+            Ok(()) => {}
         }
     }
 }

docs/development.md

@@ -45,7 +45,8 @@ How the web shell (`apps/vectorcraft-web/src/web.rs`) differs from desktop:
 
 The canvas is rasterized on the CPU (`vectorcraft-render`, vello_cpu); the GPU (wgpu, through eframe) only composites the canvas texture and draws the UI, so any GPU that can show the window will do. The desktop app picks the window's adapter itself (`apps/vectorcraft/src/gpu.rs`, eframe's `native_adapter_selector`) and logs every adapter it found and the one it uses.
 
-- **Order:** adapters that report they can't present to the window are never tried; then the one `WGPU_ADAPTER_NAME` names; hardware before software (llvmpipe, WARP); the native backends (Vulkan, Metal, DX12) before OpenGL; with Automatic, the GPU that drives a display, and among those the one that drives the primary display; then the power preference; then, on Windows, where each GPU is listed under both, a GPU's DX12 adapter before its Vulkan one (Intel's Vulkan driver made the whole window flicker black, #545), keeping the system's order among equals. `WGPU_BACKEND=vulkan` still picks Vulkan.
+- **Order:** adapters that report they can't present to the window are never tried; then the one `WGPU_ADAPTER_NAME` names; hardware before software (llvmpipe, WARP); the native backends (Vulkan, Metal, DX12) before OpenGL; with Automatic, the GPU that drives a display, and among those the one that drives the primary display; then the power preference; then a GPU's DX12 adapter before its Vulkan one (Intel's Vulkan driver made the whole window flicker black, #545), keeping the system's order among equals.
+- **Windows backends:** Direct3D 12, falling back to OpenGL. Vulkan isn't started at all unless `WGPU_BACKEND` asks for it (`WGPU_BACKEND=vulkan`): creating a Vulkan instance loads every installed Vulkan driver into the process, and a faulty one (Intel's `igvk64.dll`, #806) crashed the app before its window appeared.
 - **The GPU that drives the display.** A GPU without a monitor is the wrong one even when it says it can show the window: on a desktop with a Ryzen's integrated GPU (no monitor) and an NVIDIA card driving both monitors, power saving picked the integrated GPU, Windows had to present every frame across adapters, and the integrated GPU's driver reset under that: the graphics device was lost, or the desktop's compositor went down and every monitor stayed black for minutes (pdfcraft#378). So Automatic asks the system which GPU drives which display and puts that GPU first; the power preference only orders the rest, and decides alone where the system can't say.
   - **Windows:** `EnumDisplayDevices` (the display devices attached to the desktop, and the primary one), through the `winsafe` crate; the PCI ids in each device id are matched against wgpu's adapters. The registry doesn't tell a user which adapter drives a display, and WMI reports a resolution for a GPU without a monitor, so neither is used.
   - **Linux:** the connected connectors in `/sys/class/drm` and their cards' PCI ids; a built-in panel (`eDP`, `LVDS`, `DSI`) counts as the primary display.

docs/mcp.md

@@ -167,7 +167,7 @@ The older names below remain listed because existing workflows use them.
 |---|---|
 | `command_list` | Optional `filter`, `enabled_only`; returns the command array |
 | `command_run` | `id`, optional `params`; runs the command through the existing backend |
-| `command_batch` | `steps: [{id, params?}]`, optional `stop_on_error` (default true); returns `completed`, `failed`, `results: [{ok, result\|error}]`. Each edit has its own undo step; failures set `isError` |
+| `command_batch` | `steps: [{id, params?}]`, optional `stop_on_error` (default true); returns `completed`, `failed`, `results: [{ok, result\|error}]`. Each edit has its own undo step; failures set `isError`. A param string `"$N.path"` or `"$last.path"` takes a value from an earlier step's result (see `run` below) |
 | `doc_inspect` | Optional `depth`, `childLimit`; same summary as `inspect_document` |
 | `render_preview` | Optional `max_side` (1–4096, default 1024); inline PNG of the first artboard without editing it. Artboards too large to render within the allocation bound return a tool error |
 | `ui_inspect`, `ui_screenshot` | Connected desktop state/window capture; tool errors in headless mode |
@@ -573,6 +573,16 @@ applies to the `--cmd` just before it. `run` also accepts the host commands `fil
 `file.exportForScreens` and `tool.select`. `run --in`, `convert` and `info` read every format `document.open` reads
 (`vectorcraft-cli --help` lists them).
 
+A step can use an earlier step's result, in `run` as in the `command_batch` tool. A parameter string that is exactly
+`$N` or `$N.path` takes that value from the result of step `N` (counting from 0, in the order they ran; `run --in`'s
+open isn't a step), and `$last…` from the step before. A path goes into objects by key and arrays by index:
+`"$1.id"`, `"$2.ids.0"`, `"$last.ids[0]"`. A string starting with `$$` stands for one `$` (`"$$1.99"` is `$1.99`). A
+reference that names no value fails the step, so a command never runs with one left in it:
+
+```sh
+vectorcraft-cli run --cmd file.new --params '{"width":600,"height":200}'   --cmd text.create --params '{"x":10,"y":60,"text":"plain and bold words","size":30}'   --cmd text.setRangeStyle --params '{"id":"$1.id","start":10,"end":14,"style":"Bold"}'
+```
+
 ## Transparency and opacity masks
 
 Transparency and opacity-mask commands take `ids` (or `id`), so they need no selection. Opacity is a percentage
@@ -819,9 +829,11 @@ groups; `.gpl` is 8-bit RGB; a swatch exchange `.ase` file keeps solid colors in
 as the color it shows and leaves gradients out; CSS writes custom properties); without `path`
 it returns `{data}`, or `{dataBase64}` for `.ase`, and `user: true` saves into the user library
 folder of the desktop app (listed as category `user`, User Defined). `swatch.library.load {path? | data? |
-dataBase64?, name?}` loads a `.vcswatches`, `.gpl` or swatch exchange (`.ase`) file, or another document's swatches,
-as a library to add from. From an `.ase` file it reads RGB, CMYK, Lab and Gray colors as global, spot or process
-swatches and keeps their color groups. A file in the user library folder, or a file with the
+dataBase64?, name?}` loads a `.vcswatches`, `.gpl`, swatch exchange (`.ase`) or color book (`.acb`) file, or another
+document's swatches, as a library to add from. From an `.ase` file it reads RGB, CMYK, Lab and Gray colors as global,
+spot or process swatches and keeps their color groups. A color book (such as a Pantone book you own) gives its RGB,
+CMYK or Lab colors named with the book's prefix and suffix ("PANTONE 185 C"), as spot colors unless the book marks
+them as process colors; `.acb` files are read, never written. A file in the user library folder, or a file with the
 same extension and bytes as one there, loads as that User Defined library (category `user`).
 `swatch.library.copyToUser {library}` copies a loaded library into the user library folder of the desktop
 app (a library file as it is; a document's swatches or a library loaded from `data` or `dataBase64`